Skip to content

docs: Reorganize Color Modes doc for clarity #2365

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
lachlanjc merged 1 commit into from
Nov 21, 2022
Merged

docs: Reorganize Color Modes doc for clarity #2365

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
276 changes: 128 additions & 148 deletions packages/docs/src/pages/color-modes.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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

Expand All @@ -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) => (
<div
sx={(theme) => ({
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]) => ({
<Button
sx={{ bg: values.background, color: values.text }}
onClick={() => setColorMode(mode)}
>
{mode}
</Button>
}))
}

// OUTPUT

<Button>light</Button>
<Button>dark</Button>
<Button>deep</Button>
// ...
```
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

Expand All @@ -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
`<html>` element.

```jsx
Expand All @@ -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
Expand Down Expand Up @@ -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`

Expand Down Expand Up @@ -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'`.

Expand All @@ -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) => (
<div
sx={(theme) => ({
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`.

<details>

<summary>Code example</summary>

```jsx
import { useThemeUI } from 'theme-ui'

export default (props) => {
const { theme: { rawColors }, setColorMode } = useThemeUI()

return Object.entries(rawColors?.modes).map(([mode, values]) => ({
<Button
sx={{ bg: values.background, color: values.text }}
onClick={() => setColorMode(mode)}
>
{mode}
</Button>
}))
}

// OUTPUT

<Button>light</Button>
<Button>dark</Button>
<Button>deep</Button>
// ...
```

</details>
2 changes: 1 addition & 1 deletion packages/docs/src/pages/getting-started/gatsby.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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`.
Expand Down
2 changes: 1 addition & 1 deletion packages/gatsby-plugin-theme-ui/README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down
⚡