diff --git a/packages/docs/src/pages/color-modes.mdx b/packages/docs/src/pages/color-modes.mdx index a52dd5004..dc5faf619 100644 --- a/packages/docs/src/pages/color-modes.mdx +++ b/packages/docs/src/pages/color-modes.mdx @@ -33,9 +33,7 @@ for optional color modes. } ``` -All colors found in `colors.modes` will be referenced by their key in the -context object `rawColors.modes`. The above example will have two modes: `light` -and `dark`. +In your components, using e.g. `sx={{ color: 'text' }}` will automatically pick up the current color mode, with no adaptation necessary, even if you add more color modes later. ## Initial colors @@ -46,101 +44,7 @@ color mode changes change. This is to allow for reference like - `colors.primary`, when the color mode is set to its initial mode - `colors.modes.dark.primary`, when the color mode is set to `dark` -Because of this, we store those initial colors with the other modes. They will -be accessible as - -- `rawColors.modes.__default` (if `initialColorModeName` is undefined) -- `rawColors.modes.light` (using the value of `initialColorModeName`). - -```js -{ - config: { - initialColorModeName: 'light', - } - rawColors: { - primary: '#07c', - modes: { - // __default: {}, no '__default' here as initialColorModeName is defined - light: { primary: '#07c' }, - dark: { primary: '#0cf' } - } - } -} -``` - -## Colors Object - -The `colors` object contains Custom CSS Properties - -```js -{ - colors: { - text: 'var(--theme-ui-colors-text)', - background: 'var(--theme-ui-colors-background)', - primary: 'var(--theme-ui-colors-primary)', - } -} -``` - -## rawColors Object - -If you need to pass original value somewhere where CSS Properties (e.g. WebGL -Canvas) won't work, use `rawColors` - -```js -{ - rawColors: { - text: '#000', - background: '#fff', - primary: '#07c', - } -} -``` - -### Use specific modes - -#### With the `sx` prop - -```jsx -export default (props) => ( -
({ - color: theme.rawColors.modes?.dark?.text - bg: theme.rawColors.modes?.dark?.bg - })} - /> -) - -``` - -#### With Theme UI context - -Use the [`useThemeUI`](/hooks#usethemeui) hook to access the context object -directly in a component. - -```jsx -import { useThemeUI } from 'theme-ui' - -export default (props) => { - const { theme: { rawColors }, setColorMode } = useThemeUI() - - return Object.entries(rawColors?.modes).map(([mode, values]) => ({ - - })) -} - -// OUTPUT - - - - -// ... -``` +By default, this works by setting CSS Custom Properties for each theme color, then when the color mode is changed, updating the properties. This makes color modes SSR-safe, since the generated CSS for your components doesn’t rely on knowing the user’s color mode to render. See below how to access the raw color values or disable the use off Custom Properties. ## Setting the color mode @@ -167,9 +71,11 @@ export default (props) => { } ``` -## Applying colors +See our [guide to color mode toggles](/guides/color-mode-toggles) for more. + +## Applying page-wide colors -The ThemeProvider component will automatically apply color mode styles to the +The `ThemeProvider` component will automatically apply color mode styles (by setting `color` and `background-color`) to the `` element. ```jsx @@ -181,62 +87,26 @@ export default (props) => ( ) ``` -- To disable this behavior, add the `useRootStyles: false` flag to your theme. +To disable this behavior, add the `useRootStyles: false` flag to your theme. -## Gatsby plugin +If you’d like to apply your theme color to the browser, [see our guide to the theme color meta tag](/guides/theme-color-meta-tag). + +### Gatsby plugin For use in a Gatsby site, install and use `gatsby-plugin-theme-ui` to add the ThemeProvider to the root of your application. The plugin will also help prevent the flash of colors that can happen during page load when a user has a non-default color mode set. -```sh -npm i gatsby-plugin-theme-ui -``` - This plugin will look for a `src/gatsby-plugin-theme-ui/index.js` file to import and pass to the ThemeProvider. -```js filename=gatsby-config.js -module.exports = { - plugins: ['gatsby-plugin-theme-ui'], -} -``` - -See the [Gatsby plugin docs](/packages/gatsby-plugin) for more info. +See the [Gatsby plugin docs](/packages/gatsby-plugin) for more info & examples. -## Advanced +## Configuration Theme UI includes a few advanced configuration options for color modes. -### Turn off custom properties - -Theme UI uses [CSS custom properties](https://caniuse.com/#feat=css-variables) -under the hood to help prevent the flash of color on load. If you’re targeting -browsers that don't support custom properties you can turn off this setting. -This will cause the colors to flash on initial page load. - -```js -// example theme colors -{ - config: { - useCustomProperties: false, - }, - colors: { - text: '#000', - background: '#fff', - primary: '#07c', - modes: { - dark: { - text: '#fff', - background: '#000', - primary: '#0cf', - } - } - } -} -``` - ### Responding to the `prefers-color-scheme` media query The `useColorSchemeMediaQuery` option on the theme configuration initializes a @@ -264,9 +134,7 @@ enabled by default. } ``` -- To enable the color mode to update when a user's current - `prefers-color-scheme` media query value changes, set - `useColorSchemeMediaQuery` to `'system'`. +To enable the color mode to update when a user's current `prefers-color-scheme` media query value changes, set `useColorSchemeMediaQuery` to `'system'`. ### Disable persisting color mode on `localStorage` @@ -294,9 +162,11 @@ configuration. ### Set a custom color mode for printing By default, when printing a webpage, browsers will use the current color mode -enabled. (This means if a user is currently using a dark or colored-background -mode, their printed page will share that styling). If you’d like to set a color -mode to be used on printing, set that color mode with the configuration option +enabled. This means if a user is currently using a dark or colored-background +mode, their printed page will share that styling. + +If you’d like to set a color +mode to be used on printing, such as light mode, set that color mode with the configuration option `printColorModeName`, set to one of your `colors.modes` names, the `initialColorModeName` value, or the string `'initial'`. @@ -321,3 +191,113 @@ no additional client-side JavaScript for printing. } } ``` + +### Turn off custom properties + +Theme UI uses [CSS custom properties](https://caniuse.com/#feat=css-variables) +under the hood to help prevent the flash of color on load. If you’re targeting +browsers that don't support custom properties, you can turn off this setting with `useCustomProperties: false`. +This will cause the colors to flash on initial page load. + +```js +// example theme colors +{ + config: { + useCustomProperties: false, + }, + colors: { + text: '#000', + background: '#fff', + primary: '#07c', + modes: { + dark: { + text: '#fff', + background: '#000', + primary: '#0cf', + } + } + } +} +``` + +## Advanced: Accessing theme colors explicitly + +### Colors object + +The `colors` object contains Custom CSS Properties + +```js +{ + colors: { + text: 'var(--theme-ui-colors-text)', + background: 'var(--theme-ui-colors-background)', + primary: 'var(--theme-ui-colors-primary)', + } +} +``` + +### rawColors object + +If you need to pass original value somewhere where CSS Properties (e.g. WebGL +Canvas) won't work, use `rawColors`. + +```js +{ + rawColors: { + text: '#000', + background: '#fff', + primary: '#07c', + } +} +``` + +All colors found in `colors.modes` will be referenced by their key in the +context object `rawColors.modes`. + +### With the `sx` prop + +```jsx +export default (props) => ( +
({ + color: theme.rawColors.modes?.dark?.text + bg: theme.rawColors.modes?.dark?.bg + })} + /> +) +``` + +### With Theme UI context + +Use the [`useThemeUI`](/hooks#usethemeui) hook to access the context object +directly in a component. The theme object it includes contains `colors` and `rawColors`. + +
+ +Code example + +```jsx +import { useThemeUI } from 'theme-ui' + +export default (props) => { + const { theme: { rawColors }, setColorMode } = useThemeUI() + + return Object.entries(rawColors?.modes).map(([mode, values]) => ({ + + })) +} + +// OUTPUT + + + + +// ... +``` + +
diff --git a/packages/docs/src/pages/getting-started/gatsby.mdx b/packages/docs/src/pages/getting-started/gatsby.mdx index 293308a30..d3dc61754 100755 --- a/packages/docs/src/pages/getting-started/gatsby.mdx +++ b/packages/docs/src/pages/getting-started/gatsby.mdx @@ -8,7 +8,7 @@ To use Theme UI with [Gatsby][], install and use [`gatsby-plugin-theme-ui`](/packages/gatsby-plugin). ```sh -npm i theme-ui gatsby-plugin-theme-ui @emotion/react @mdx-js/react@v1 +npm i theme-ui gatsby-plugin-theme-ui @emotion/react @mdx-js/react ``` Add the plugin to your `gatsby-config.js`. diff --git a/packages/gatsby-plugin-theme-ui/README.md b/packages/gatsby-plugin-theme-ui/README.md index 0d1c47541..85030165e 100755 --- a/packages/gatsby-plugin-theme-ui/README.md +++ b/packages/gatsby-plugin-theme-ui/README.md @@ -3,7 +3,7 @@ Gatsby plugin for adding Theme UI context ```sh -npm i theme-ui gatsby-plugin-theme-ui @emotion/react @mdx-js/react@v1 +npm i theme-ui gatsby-plugin-theme-ui @emotion/react @mdx-js/react ``` ```js