Skip to content

Commit 3cf5472

Browse files
authored
docs: Add theming recipes (#869)
* docs: Add theming recipes * docs: clarify that only themes for the *same* VarGroup are mutually exclusive
1 parent 4c887b7 commit 3cf5472

File tree

4 files changed

+151
-3
lines changed

4 files changed

+151
-3
lines changed

apps/docs/docs/learn/06-recipes/03-descendant styles.mdx

-3
Original file line numberDiff line numberDiff line change
@@ -6,9 +6,6 @@
66
sidebar_position: 3
77
---
88

9-
import Tabs from '@theme/Tabs';
10-
import TabItem from '@theme/TabItem';
11-
129
# Variables for descendant styles
1310

1411
It is not uncommon to define styles on an element that are dependent on a parent element's state,
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,30 @@
1+
---
2+
# Copyright (c) Meta Platforms, Inc. and affiliates.
3+
#
4+
# This source code is licensed under the MIT license found in the
5+
# LICENSE file in the root directory of this source tree.
6+
sidebar_position: 4
7+
---
8+
9+
# Reset Theme
10+
11+
The `stylex.defineVars` function is used to create a set of CSS variables,
12+
called `VarGroup`s. Further, the `stylex.createTheme` function can be used to create
13+
`Theme`s, that override the values of the variables defined within `VarGroup`s.
14+
15+
Many `VarGroup`s can be defined which can then be independently overridden with `Theme`s.
16+
However, `Theme`s for the *same* `VarGroup` are mutually exclusive and do not merge.
17+
Any variable in a `VarGroup` that is not explicitly overridden in a `Theme` for that `VarGroup`
18+
is set to its default value.
19+
20+
This characteristic of `Theme`s can be used to define a "empty" theme that resets all variables
21+
to their default values.
22+
23+
## Example
24+
25+
```tsx
26+
import * as stylex from '@stylexjs/stylex';
27+
import { vars } from './variables.stylex';
28+
29+
export const resetVars = stylex.createTheme(vars, {});
30+
```
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,42 @@
1+
---
2+
# Copyright (c) Meta Platforms, Inc. and affiliates.
3+
#
4+
# This source code is licensed under the MIT license found in the
5+
# LICENSE file in the root directory of this source tree.
6+
sidebar_position: 5
7+
---
8+
9+
# Merge Themes
10+
11+
`Theme`s for the *same* `VarGroup` are mutually exclusive and do not merge.
12+
Any variable in a `VarGroup` that is not explicitly overridden in a `Theme` for that `VarGroup`
13+
is set to its default value.
14+
15+
However, you can reuse common constants when defining multiple themes for a particular
16+
`VarGroup` and avoid excessive repetition.
17+
18+
## Example
19+
20+
```tsx
21+
import * as stylex from '@stylexjs/stylex';
22+
import { vars } from './variables.stylex';
23+
24+
const themeBlueVars = {
25+
backgroundColor: 'blue',
26+
};
27+
const themeBlue = stylex.createTheme(vars, themeBlueVars);
28+
29+
const themeBigVars = {
30+
size: '128px',
31+
};
32+
const themeBig = stylex.createTheme(vars, themeBigVars);
33+
34+
const themeBigBlueVars = {...themeBlueVars, ...themeBigVars};
35+
const themeBigBlue = stylex.createTheme(vars, themeBigBlueVars);
36+
```
37+
38+
The StyleX compiler is able to resolve local object constants and merge them.
39+
This is useful to be able to define a `Theme` that merges the values of two or more
40+
other `Theme`s without repetition.
41+
42+
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,79 @@
1+
---
2+
# Copyright (c) Meta Platforms, Inc. and affiliates.
3+
#
4+
# This source code is licensed under the MIT license found in the
5+
# LICENSE file in the root directory of this source tree.
6+
sidebar_position: 6
7+
---
8+
9+
# Light and Dark Themes
10+
11+
It is a common pattern to define separate `light`, `dark` and system themes
12+
to provide the ability to switch between different color schemes.
13+
14+
This would typically be done by defining three separate `Theme`s:
15+
16+
```tsx
17+
const lightVars = {
18+
primaryColor: 'black',
19+
...
20+
};
21+
export const light = stylex.createTheme(vars, lightVars);
22+
23+
const darkVars = {
24+
primaryColor: 'white',
25+
...
26+
};
27+
export const dark = stylex.createTheme(vars, darkVars);
28+
29+
const systemVars = {
30+
primaryColor: {
31+
default: 'black',
32+
'@media (prefers-color-scheme: dark)': 'white',
33+
},
34+
...
35+
};
36+
export const system = stylex.createTheme(vars, systemVars);
37+
```
38+
This pattern is well supported and will work in all browsers that support CSS variables.
39+
40+
## Using the `light-dark()` CSS function
41+
42+
In modern browsers, we suggest using the
43+
[`light-dark()`](https://developer.mozilla.org/en-US/docs/Web/CSS/color_value/light-dark)
44+
CSS function instead which will simplify the code and remove the need to define themes.
45+
46+
```tsx
47+
export const vars = stylex.defineVars({
48+
primaryColor: 'light-dark(black, white)',
49+
...
50+
});
51+
```
52+
53+
You can now control the color scheme applied by using the `color-scheme` CSS property.
54+
55+
```tsx
56+
const styles = stylex.create({
57+
light: {
58+
colorScheme: 'light',
59+
},
60+
dark: {
61+
colorScheme: 'dark',
62+
},
63+
system: {
64+
colorScheme: 'light dark',
65+
},
66+
});
67+
68+
<div {...stylex.props(styles[colorScheme])}>
69+
...
70+
</div>
71+
```
72+
73+
You *can* still define custom themes for other use-cases and use `light-dark()` within them.
74+
75+
### Limitations
76+
77+
1. The `light-dark()` CSS function can only be used for color values.
78+
2. The `light-dark()` function is not supported in older browsers.
79+

0 commit comments

Comments
 (0)