message: docs: update color mode docs
diff: @@ -7,32 +7,23 @@ order: 4
  # Color Mode
  -By default, most of Chakra's component are dark mode compatible. To handle color
  -mode manually in your application, use the `useColorMode` hook. This value will
  -be stored in `localStorage` and used whenever the page is loaded.
  +When you use the `ChakraProvider` at the root of your app, you can automatically
  +use color mode in your apps.
  -## Enable Color Mode
  +By default, most of Chakra's component are dark mode compatible. To handle color
  +mode manually in your application, use the `useColorMode` or `useColorModeValue`
  +hooks.
  -To enable this behavior within your apps, wrap your application in a
  -`ColorModeProvider`.
  +> **Tip:** Chakra stores the color mode in `localStorage` and uses a class name
  +> strategy to ensure the color mode is persistent.
  -```jsx live=false
  -import * as React from "react"
  -import { ThemeProvider, ColorModeProvider } from "@chakra-ui/core"
  +## useColorMode hook
  -function Example({ children }) {
  - return (
  - <ThemeProvider>
  - <ColorModeProvider>{children}</ColorModeProvider>
  - </ThemeProvider>
  - )
  -}
  -```
  -
  -Then you can use the hook `useColorMode` within your application.
  +`useColorMode` is a React hook that gives you access to the current color mode,
  +and a function to toggle the color mode.
  ```jsx
  -function ColorModeExample() {
  +function Example() {
  const [colorMode, toggleColorMode] = useColorMode()
  return (
  <header>
  @@ -44,19 +35,20 @@ function ColorModeExample() {
  }
  ```
  -## Styling color modes
  -
  -To style dark mode in your components, use the `useColorModeValue` hook to
  -change the styles of your component.
  +## useColorModeValue hook
  -`useColorModeValue` takes 2 arguments: the value in light mode, and the value in
  +`useColorModeValue` is a React hook used to change any value or style based on
  +the color mode. It takes 2 arguments: the value in light mode, and the value in
  dark mode.
  ```jsx live=false
  -// here's the signature
  -const bg = useColorModeValue(lightMode, darkMode)
  +// Here's the signature
  +const bg = useColorModeValue(lightModeValue, darkModeValue)
  ```
  +Here's an example that changes the `background-color` and `color` using the
  +`useColorModeValue` hook.
  +
  > Click the **Toggle Mode** button to see it in action.
  ```jsx
  @@ -67,7 +59,7 @@ function StyleColorMode() {
  return (
  <>
  - <Box flex="1" mb={4} bg={bg} color={color}>
  + <Box mb={4} bg={bg} color={color}>
  This box's style will change based on the color mode.
  </Box>
  <Button size="sm" onClick={toggleColorMode}>
  @@ -111,3 +103,37 @@ function Example() {
  )
  }
  ```
  +
  +## Change color mode behavior
  +
  +Starting from v1.0, we've added new improvements to the color mode management.
  +
  +### Setting initial mode
  +
  +Sometimes, you want you app to start with light or dark mode by default. To
  +support this, add `theme.config.initialColorMode` to the theme and set it's
  +value to "light" or "dark".
  +
  +```jsx live=false
  +const theme = {
  + config: {
  + initialColorMode: "dark", // "light" | "dark"
  + },
  +}
  +```
  +
  +### Using system color mode
  +
  +In some scenarios, you might want your app to adapt to the user's OS color mode
  +preference. To support this, add `theme.config.useSystemColorMode`.
  +
  +This also updates the color mode whenever user changes this preference from
  +their OS.
  +
  +```jsx live=false
  +const theme = {
  + config: {
  + useSystemColorMode: true,
  + },
  +}
  +```
  