Skip to content

Commit cdbff73

Browse files
lachlanjclachlanjc
committed
docs: Reorganize Color Modes doc for clarity
1 parent 9dc959e commit cdbff73

File tree

3 files changed

+130
-150
lines changed

3 files changed

+130
-150
lines changed

‎packages/docs/src/pages/color-modes.mdx

Lines changed: 128 additions & 148 deletions
Original file line numberDiff line numberDiff line change
@@ -33,9 +33,7 @@ for optional color modes.
3333
}
3434
```
3535

36-
All colors found in `colors.modes` will be referenced by their key in the
37-
context object `rawColors.modes`. The above example will have two modes: `light`
38-
and `dark`.
36+
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.
3937

4038
## Initial colors
4139

@@ -46,101 +44,7 @@ color mode changes change. This is to allow for reference like
4644
- `colors.primary`, when the color mode is set to its initial mode
4745
- `colors.modes.dark.primary`, when the color mode is set to `dark`
4846

49-
Because of this, we store those initial colors with the other modes. They will
50-
be accessible as
51-
52-
- `rawColors.modes.__default` (if `initialColorModeName` is undefined)
53-
- `rawColors.modes.light` (using the value of `initialColorModeName`).
54-
55-
```js
56-
{
57-
config: {
58-
initialColorModeName: 'light',
59-
}
60-
rawColors: {
61-
primary: '#07c',
62-
modes: {
63-
// __default: {}, no '__default' here as initialColorModeName is defined
64-
light: { primary: '#07c' },
65-
dark: { primary: '#0cf' }
66-
}
67-
}
68-
}
69-
```
70-
71-
## Colors Object
72-
73-
The `colors` object contains Custom CSS Properties
74-
75-
```js
76-
{
77-
colors: {
78-
text: 'var(--theme-ui-colors-text)',
79-
background: 'var(--theme-ui-colors-background)',
80-
primary: 'var(--theme-ui-colors-primary)',
81-
}
82-
}
83-
```
84-
85-
## rawColors Object
86-
87-
If you need to pass original value somewhere where CSS Properties (e.g. WebGL
88-
Canvas) won't work, use `rawColors`
89-
90-
```js
91-
{
92-
rawColors: {
93-
text: '#000',
94-
background: '#fff',
95-
primary: '#07c',
96-
}
97-
}
98-
```
99-
100-
### Use specific modes
101-
102-
#### With the `sx` prop
103-
104-
```jsx
105-
export default (props) => (
106-
<div
107-
sx={(theme) => ({
108-
color: theme.rawColors.modes?.dark?.text
109-
bg: theme.rawColors.modes?.dark?.bg
110-
})}
111-
/>
112-
)
113-
114-
```
115-
116-
#### With Theme UI context
117-
118-
Use the [`useThemeUI`](/hooks#usethemeui) hook to access the context object
119-
directly in a component.
120-
121-
```jsx
122-
import { useThemeUI } from 'theme-ui'
123-
124-
export default (props) => {
125-
const { theme: { rawColors }, setColorMode } = useThemeUI()
126-
127-
return Object.entries(rawColors?.modes).map(([mode, values]) => ({
128-
<Button
129-
sx={{ bg: values.background, color: values.text }}
130-
onClick={() => setColorMode(mode)}
131-
>
132-
{mode}
133-
</Button>
134-
}))
135-
}
136-
137-
// OUTPUT
138-
139-
<Button>light</Button>
140-
<Button>dark</Button>
141-
<Button>deep</Button>
142-
// ...
143-
```
47+
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.
14448

14549
## Setting the color mode
14650

@@ -167,9 +71,11 @@ export default (props) => {
16771
}
16872
```
16973

170-
## Applying colors
74+
See our [guide to color mode toggles](/guides/color-mode-toggles) for more.
75+
76+
## Applying page-wide colors
17177

172-
The ThemeProvider component will automatically apply color mode styles to the
78+
The `ThemeProvider` component will automatically apply color mode styles (by setting `color` and `background-color`) to the
17379
`<html>` element.
17480

17581
```jsx
@@ -181,62 +87,26 @@ export default (props) => (
18187
)
18288
```
18389

184-
- To disable this behavior, add the `useRootStyles: false` flag to your theme.
90+
To disable this behavior, add the `useRootStyles: false` flag to your theme.
18591

186-
## Gatsby plugin
92+
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).
93+
94+
### Gatsby plugin
18795

18896
For use in a Gatsby site, install and use `gatsby-plugin-theme-ui` to add the
18997
ThemeProvider to the root of your application. The plugin will also help prevent
19098
the flash of colors that can happen during page load when a user has a
19199
non-default color mode set.
192100

193-
```sh
194-
npm i gatsby-plugin-theme-ui
195-
```
196-
197101
This plugin will look for a `src/gatsby-plugin-theme-ui/index.js` file to import
198102
and pass to the ThemeProvider.
199103

200-
```js filename=gatsby-config.js
201-
module.exports = {
202-
plugins: ['gatsby-plugin-theme-ui'],
203-
}
204-
```
205-
206-
See the [Gatsby plugin docs](/packages/gatsby-plugin) for more info.
104+
See the [Gatsby plugin docs](/packages/gatsby-plugin) for more info & examples.
207105

208-
## Advanced
106+
## Configuration
209107

210108
Theme UI includes a few advanced configuration options for color modes.
211109

212-
### Turn off custom properties
213-
214-
Theme UI uses [CSS custom properties](https://caniuse.com/#feat=css-variables)
215-
under the hood to help prevent the flash of color on load. If you’re targeting
216-
browsers that don't support custom properties you can turn off this setting.
217-
This will cause the colors to flash on initial page load.
218-
219-
```js
220-
// example theme colors
221-
{
222-
config: {
223-
useCustomProperties: false,
224-
},
225-
colors: {
226-
text: '#000',
227-
background: '#fff',
228-
primary: '#07c',
229-
modes: {
230-
dark: {
231-
text: '#fff',
232-
background: '#000',
233-
primary: '#0cf',
234-
}
235-
}
236-
}
237-
}
238-
```
239-
240110
### Responding to the `prefers-color-scheme` media query
241111

242112
The `useColorSchemeMediaQuery` option on the theme configuration initializes a
@@ -264,9 +134,7 @@ enabled by default.
264134
}
265135
```
266136

267-
- To enable the color mode to update when a user's current
268-
`prefers-color-scheme` media query value changes, set
269-
`useColorSchemeMediaQuery` to `'system'`.
137+
To enable the color mode to update when a user's current `prefers-color-scheme` media query value changes, set `useColorSchemeMediaQuery` to `'system'`.
270138

271139
### Disable persisting color mode on `localStorage`
272140

@@ -294,9 +162,11 @@ configuration.
294162
### Set a custom color mode for printing
295163

296164
By default, when printing a webpage, browsers will use the current color mode
297-
enabled. (This means if a user is currently using a dark or colored-background
298-
mode, their printed page will share that styling). If you’d like to set a color
299-
mode to be used on printing, set that color mode with the configuration option
165+
enabled. This means if a user is currently using a dark or colored-background
166+
mode, their printed page will share that styling.
167+
168+
If you’d like to set a color
169+
mode to be used on printing, such as light mode, set that color mode with the configuration option
300170
`printColorModeName`, set to one of your `colors.modes` names, the
301171
`initialColorModeName` value, or the string `'initial'`.
302172

@@ -321,3 +191,113 @@ no additional client-side JavaScript for printing.
321191
}
322192
}
323193
```
194+
195+
### Turn off custom properties
196+
197+
Theme UI uses [CSS custom properties](https://caniuse.com/#feat=css-variables)
198+
under the hood to help prevent the flash of color on load. If you’re targeting
199+
browsers that don't support custom properties, you can turn off this setting with `useCustomProperties: false`.
200+
This will cause the colors to flash on initial page load.
201+
202+
```js
203+
// example theme colors
204+
{
205+
config: {
206+
useCustomProperties: false,
207+
},
208+
colors: {
209+
text: '#000',
210+
background: '#fff',
211+
primary: '#07c',
212+
modes: {
213+
dark: {
214+
text: '#fff',
215+
background: '#000',
216+
primary: '#0cf',
217+
}
218+
}
219+
}
220+
}
221+
```
222+
223+
## Advanced: Accessing theme colors explicitly
224+
225+
### Colors object
226+
227+
The `colors` object contains Custom CSS Properties
228+
229+
```js
230+
{
231+
colors: {
232+
text: 'var(--theme-ui-colors-text)',
233+
background: 'var(--theme-ui-colors-background)',
234+
primary: 'var(--theme-ui-colors-primary)',
235+
}
236+
}
237+
```
238+
239+
### rawColors object
240+
241+
If you need to pass original value somewhere where CSS Properties (e.g. WebGL
242+
Canvas) won't work, use `rawColors`.
243+
244+
```js
245+
{
246+
rawColors: {
247+
text: '#000',
248+
background: '#fff',
249+
primary: '#07c',
250+
}
251+
}
252+
```
253+
254+
All colors found in `colors.modes` will be referenced by their key in the
255+
context object `rawColors.modes`.
256+
257+
### With the `sx` prop
258+
259+
```jsx
260+
export default (props) => (
261+
<div
262+
sx={(theme) => ({
263+
color: theme.rawColors.modes?.dark?.text
264+
bg: theme.rawColors.modes?.dark?.bg
265+
})}
266+
/>
267+
)
268+
```
269+
270+
### With Theme UI context
271+
272+
Use the [`useThemeUI`](/hooks#usethemeui) hook to access the context object
273+
directly in a component. The theme object it includes contains `colors` and `rawColors`.
274+
275+
<details>
276+
277+
<summary>Code example</summary>
278+
279+
```jsx
280+
import { useThemeUI } from 'theme-ui'
281+
282+
export default (props) => {
283+
const { theme: { rawColors }, setColorMode } = useThemeUI()
284+
285+
return Object.entries(rawColors?.modes).map(([mode, values]) => ({
286+
<Button
287+
sx={{ bg: values.background, color: values.text }}
288+
onClick={() => setColorMode(mode)}
289+
>
290+
{mode}
291+
</Button>
292+
}))
293+
}
294+
295+
// OUTPUT
296+
297+
<Button>light</Button>
298+
<Button>dark</Button>
299+
<Button>deep</Button>
300+
// ...
301+
```
302+
303+
</details>

‎packages/docs/src/pages/getting-started/gatsby.mdx

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -8,7 +8,7 @@ To use Theme UI with [Gatsby][], install and use
88
[`gatsby-plugin-theme-ui`](/packages/gatsby-plugin).
99

1010
```sh
11-
npm i theme-ui gatsby-plugin-theme-ui @emotion/react @mdx-js/react@v1
11+
npm i theme-ui gatsby-plugin-theme-ui @emotion/react @mdx-js/react
1212
```
1313

1414
Add the plugin to your `gatsby-config.js`.

‎packages/gatsby-plugin-theme-ui/README.md

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -3,7 +3,7 @@
33
Gatsby plugin for adding Theme UI context
44

55
```sh
6-
npm i theme-ui gatsby-plugin-theme-ui @emotion/react @mdx-js/react@v1
6+
npm i theme-ui gatsby-plugin-theme-ui @emotion/react @mdx-js/react
77
```
88

99
```js

0 commit comments

Comments
 (0)