You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
Copy file name to clipboardExpand all lines: .storybook/components/Docs/GettingStarted.stories.mdx
+17
Original file line number
Diff line number
Diff line change
@@ -30,3 +30,20 @@ Storybook offers several facilities to demonstrate how components behave. Some c
30
30
-**Storybook View Options** allow for controlling the viewport, background color, and other details to help understand the component layout. Visually test how the component responds to different layouts
31
31
32
32
Storybook provides a lot of functionality, including [keyboard navigation](https://storybook.js.org/docs/react/get-started/browse-stories#sidebar-and-canvas). Explore [the docs](https://storybook.js.org/docs/react/get-started/introduction) to learn more.
33
+
34
+
### IDE Integrations
35
+
36
+
Since EDS provides many color tokens, it may prove useful to add some integrations to the IDE to show visual references for the colors in use.
37
+
38
+
- Install the [CSS Var Complete - VS Code Plugin](https://marketplace.visualstudio.com/items?itemName=phoenisx.cssvar) which provides better Intellisense while writing CSS and referencing CSS variables.
39
+
- Add the following settings in your workspace settings file:
EDS uses [tailwind utility classes](https://tailwindcss.com/docs/padding) (e.g. `mb-0` and `p-0`) inline in `*.stories.tsx` files to quickly add small styling tweaks, like spacing (e.g. `<Table.Cell className="p-0">`). This reduces the need for CSS module files made specifically for stories. Use the `!` modifier to override default component styles (e.g. `<Table.Cell className="!p-0">`).
304
+
EDS uses [tailwind utility classes](https://tailwindcss.com/docs/), (e.g.,`mb-0` and `p-0`) inline in `*.stories.tsx` files to demonstrate allowed compositions and example implementations.
305
305
306
306
Consider installing the VSCode extension [Tailwind CSS IntelliSense](https://marketplace.visualstudio.com/items?itemName=bradlc.vscode-tailwindcss) for autocomplete, linting, and hover previews.
EDS is a [themeable design system](https://bradfrost.com/blog/post/creating-themeable-design-systems/) that incorporates some high-level UI application variables to make easy systematic changes to the UI.
310
+
EDS is a [Headless design system](https://bradfrost.com/blog/post/creating-themeable-design-systems/) that incorporates some high-level UI application variables to make easy systematic changes to the UI.
311
311
312
-
This is a "lightly" themed system, meaning that only a few variables (such as key UI colors and other properties like border radius) are available for theming.
312
+
Learn more about EDS Theming [here](./?path=?path=/docs/documentation-theming--docs).
Copy file name to clipboardExpand all lines: .storybook/components/Docs/Guidelines/Theming.stories.mdx
+78-89
Original file line number
Diff line number
Diff line change
@@ -2,131 +2,120 @@ import { Canvas, Meta } from '@storybook/blocks';
2
2
3
3
<Metatitle="Documentation/Theming" />
4
4
5
-
# Theming overview
5
+
# Theming
6
6
7
-
"Theming", in the context of EDS, is the process of overriding the default styles of EDS components to match a different brand (or "theme"). We include useful examples under "Pages":
7
+
Below are instructions on how to use the tooling, configs, and tokens to define custom theme values for a project.
8
8
9
-
- A [wireframe theme](./?path=/story/pages-theming-wireframedemo--default) (an unbranded theme that can be used for prototyping a product before it has an official visual style).
9
+
## Using Tailwind with the Default Theme
10
10
11
-
Below are instructions on how to use the tooling and tokens to define custom theme values for a project.
11
+
Out of the box, EDS provides a basic tailwind configuration to use in any project. The provided EDS tailwind config hooks up EDS tokens to useful utility classes and some screen sizes. To import the tailwind config into the app's tailwind config, supply the [theme](https://tailwindcss.com/docs/theme) property for use:
EDS comes with some tooling to allow easy transfer of theme data from Figma (or some style-dictionary compatible format) into code.
17
+
module.exports= {
18
+
content: ['./app/**/*.{ts,tsx,jsx,js}'],
19
+
theme: edsConfig.theme,
20
+
// ... any other tailwind config
21
+
};
22
+
```
16
23
17
-
*`eds-init-theme` - This command sets up the initial file(s) for theming your application
18
-
*`eds-apply-theme` - This command parses the style dictionary files to generate the tokens used by EDS (and tailwind, or other tools)
24
+
If you only want part of the provided settings, you can review the [Tailwind Theme Customization][tailwind-theme] documentation, and the contents of the [provided config][eds-tailwind-config], and apply the parts you want to use.
19
25
20
-
Each of these tools reads config to figure out where to read/write files. This can be defined in several ways, e.g., a top-level file `.edsrc.json`, or as a key-value set in package.json. Example:
EDS comes with some optional tooling to allow easy transfer of theme data from Figma (or some style-dictionary compatible format) into code.
30
34
31
-
`.edsrc.json`
35
+
-`eds-init-theme` - This command creates the initial file(s) for theming your application
36
+
-`eds-apply-theme` - This command parses the local config file to generate the tokens used by EDS components and tools
37
+
38
+
Each of these tools reads config to figure out where to read/write files.
39
+
40
+
First, create a configuration file to determine the source and destination directories. This can be defined in a new file `.edsrc.json` in your project root. Example:
32
41
33
42
```json
43
+
// in a new file .edsrc.json
34
44
{
35
45
"src": "src/components/",
36
46
"dest": "src/components/"
37
47
}
38
48
```
39
49
40
-
`src` determines where the core theme file will be copied to (upon init) OR read from (upon apply), and `dest` determines where the processed files will be written to.
50
+
`src` determines where the core theme file will be copied to (upon running `eds-init-theme`) OR read from (upon running `eds-apply-theme`), and `dest` determines where the generated project files will be written to. Once created, you can use the provided commands.
41
51
42
52
### eds-init-theme
43
53
44
-
This will create an initial JSON file `app-theme.json` that defines ALL the available tokens for EDS that you can edit.
54
+
Command to run: `npx eds-init-theme`
45
55
46
-
EDS comes pre-packaged with many tokens that define the base style and character of the system. Users of EDS can theme certain aspects of all components, or details on specific components.
56
+
This will create a new JSON file `app-theme.json`that defines ALL the available tokens for EDS that you can edit. It will copy the template file to configured `src` path in your project.
47
57
48
-
```json
49
-
{
50
-
"eds": {
51
-
"anim": {
52
-
"fade": {
53
-
"quick": {
54
-
"value": "0.15s"
55
-
},
56
-
"long": {
57
-
"value": "0.4s"
58
-
}
59
-
},
60
-
"move": {
61
-
"quick": {
62
-
"value": "0.15s"
63
-
},
64
-
"medium": {
65
-
"value": "0.3s"
66
-
},
67
-
"long": {
68
-
"value": "0.4s"
69
-
}
70
-
},
71
-
"ease": {
72
-
"value": "ease"
73
-
}
74
-
},
75
-
// ...other token values
76
-
},
77
-
}
78
-
```
58
+
This file is a baseline config to be used later in the process.
79
59
80
60
### eds-apply-theme
81
61
82
-
After making changes to the `app-theme.json` to reflect what has been defined by design, update the project's theme files by running `npx eds-apply-theme`.
83
-
84
-
Once run, you will have a CSS file `app-theme.css` that includes a set of token values as CSS variables, which can be used in the app as appropriate.
85
-
86
-
```css
87
-
/**
88
-
* Do not edit directly
89
-
* Generated on Sunday, 01 Jan 2023 12:34:56 GMT
90
-
* To update, edit app-theme.json, then run `npx eds-apply-theme`
91
-
*/
92
-
93
-
:root {
94
-
--eds-anim-fade-quick: 0.15s;
95
-
--eds-anim-fade-long: 0.4s;
96
-
--eds-anim-move-quick: 0.15s;
97
-
--eds-anim-move-medium: 0.3s;
98
-
--eds-anim-move-long: 0.4s;
99
-
--eds-anim-ease: ease;
100
-
/* ...other token values... */
101
-
}
102
-
```
62
+
Command to run: `npx eds-apply-theme`
103
63
104
-
Add this file to your core app root file.
64
+
Using `eds-apply-theme` will read in the newly-created `app-theme.json`file, and create the tokens to use in your project.
105
65
106
-
This also generates an additional file `app-tailwind-theme.config.json` which contains [useful tailwind configuration](https://github.com/chanzuckerberg/edu-design-system?tab=readme-ov-file#tailwind-setup) for EDS-specific utility classes
107
-
This will also show a preview of the tokens in your IDE of choice. To use this config, replace the import from the package with a link to this files location:
66
+
Once run, you will have a set of theme files written to the configured `dest` path:
-`app-theme.css` (CSS file containing custom CSS variables with the theme values for the application)
69
+
-`app-tailwind-theme.config.json` (Configuration file for advanced tailwind configuration in the application)
113
70
114
-
That's it! Now, the theme will be applied to the tokens used by EDS components. To make other changes, edit `app-theme.json`, then re-run `npx eds-apply-theme`.
71
+
To use, add this file to your core app root file **after** where the imported EDS's `@chanzuckerberg/eds/index.css` file is inserted.
115
72
116
-
**NOTE**: do not edit this file directly. Instead, follow the instructions at the top of the file!
73
+
## Custom Theming and Tailwind
117
74
118
-
## How to manually apply a themein another product
75
+
When you have your own custom theme, you can use the tokens provided in `app-tailwind-theme.config.json` to do advanced tailwind configuration. This file contains all the tokens in JSON format, mapped to the literal values in your local theme.
119
76
120
-
You can also manage the creation of theme token definitions manually. In EDS, theming is implemented by overriding the values of the CSS variables representing tokens, which the EDS components use in their styles. This should update the style of the components to match the branding of a different product with minimum manual CSS styling overrides. (Some manual styling overrides will be necessary though because we don't have tokens for every little detail. In those cases, we could create a new token to make those overrides easier if it looks like something that could very well be useful for other products as well.)
77
+
You can use similar import values to what is in `@chanzuckerberg/eds/tailwind.config.ts` in your local tailwind configuration file:
121
78
122
-
These CSS variables overrides lives in the products using EDS components. This allows product teams to quickly iterate on their theme without making changes to EDS itself.
import {edsascustomTokens} from"<edsrc.json:dest>/app-tailwind-theme.config"; // where <edsrc.json:test> is the path configured in .edsrc.json
123
84
124
-
You can find the full list of CSS variables in [src/tokens-dist/css/variables.css](https://github.com/chanzuckerberg/edu-design-system/blob/main/src/tokens-dist/css/variables.css), and you can see examples of overriding them in [.storybook/pages/WireframeDemo/GlobalStyles.module.css](https://github.com/chanzuckerberg/edu-design-system/blob/main/.storybook/pages/WireframeDemo/GlobalStyles.module.css).
85
+
const {
86
+
background: backgroundColorTokens,
87
+
border: borderColorTokens,
88
+
text: textColorTokens,
89
+
...colorTokens
90
+
} =customTokens.theme.color;
125
91
126
-
If you're looking to set up a prototype using the [wireframe theme](./?path=/story/pages-theming-wireframedemo--default), you can copy and paste the variables defined in [.storybook/pages/WireframeDemo/GlobalStyles.module.css](https://github.com/chanzuckerberg/edu-design-system/blob/main/.storybook/pages/WireframeDemo/GlobalStyles.module.css). (The placeholder images will need to be added separately.)
92
+
// export the following
93
+
exportdefault {
94
+
...// your local content export
95
+
theme: {
96
+
colors: {
97
+
...colorTokens,
98
+
},
99
+
extend: {
100
+
backgroundColor: {
101
+
...backgroundColorTokens,
102
+
},
103
+
borderColor: {
104
+
...borderColorTokens,
105
+
},
106
+
textColor: {
107
+
...textColorTokens,
108
+
},
109
+
},
110
+
screens: {
111
+
...baseConfig.theme.screens, // you can mix in any base config values into the local theme
112
+
}
113
+
...// any local theme settings
114
+
}
115
+
} satisfiesConfig
127
116
128
-
If you are trying to customize the styling of a component but find that the style you want to override does not yet have a token for you to redefine, you can reach out to us to discuss whether a new token should be added.
117
+
```
129
118
130
-
## How to support theming in EDS
119
+
<hr />
131
120
132
-
Since other products rely on CSS variable tokens to theme EDS components, it's very important that, when working with color, components in the EDS package only use CSS variables representing tier 2 and tier 3 tokens for styling. EDS component styling should never use tier 1 tokens, JavaScript variables representing tokens, or raw hex codes. Non-color styling can use tokens from any tier. (This is only relevant to the EDS components themselves; examples in storybook or in other products do not need to follow this rule.)
121
+
If there are any future updates to the theme, edit the contents of `app-theme.json`, then re-run `npx eds-apply-theme`. Then commit the changes, and that's it!
@@ -33,7 +32,9 @@ Tokens are defined as a collection of JSON files, which then get converted by St
33
32
34
33
## Design token architecture
35
34
36
-
Design tokens live at `src/design-tokens`, and follows this directory structure:
35
+
Design tokens live at `src/design-tokens`. Primitive (tier-1) tokens live in `primitives.json`, and theme (tier-2/tier-3) tokens live in `themes.json`.
36
+
37
+
For typography tokens, thes directory structure is stored in the following tree:
37
38
38
39
```css
39
40
design-tokens
@@ -150,28 +151,3 @@ With the rest matching a corresponding use for the given component. For example,
150
151
The suffix here is arbitrary, but uses similar naming to tier two tokens. When possible, any new tier 3 tokens should be a more specifically named tier 2 token, to keep the naming consistent.
151
152
152
153
See the current set of tier 3 tokens [in storybook](/story/design-tokens-tier-3-component--colors).
153
-
154
-
155
-
## Tailwind Class Tokens
156
-
157
-
If the EDS tailwind config theme is being used, Tier 2 and tier 3 color tokens are available as a part of tailwind utility classes, and can be used to apply to specific attributes to a component. Background(prefix: bg-), border(prefix: border-), and text(prefix: text-) colors will only be available for themselves specifically. e.g.:
158
-
159
-
### These will not work
160
-
161
-
```html
162
-
<!-- will NOT work since tier 1 colors are not available -->
163
-
<div className="bg-brand-grape-100"></div>
164
-
<!-- will NOT work since background utility classes don't have border colors -->
165
-
<div className="bg-link-neutral"></div>
166
-
```
167
-
168
-
### These will work
169
-
```html
170
-
<!-- will work since button colors are available across all color utility classes -->
171
-
<div className="bg-button-icon-brand"></div>
172
-
<!-- will work since border colors are available for border color utility classes -->
173
-
<div className="border-link-neutral"></div>
174
-
<!-- will reflect respective color utility tokens
175
-
(background-brand-primary-strong and border-brand-primary-strong) -->
Copy file name to clipboardExpand all lines: CHANGELOG.md
+8
Original file line number
Diff line number
Diff line change
@@ -2,6 +2,14 @@
2
2
3
3
All notable changes to this project will be documented in this file. See [standard-version](https://github.com/conventional-changelog/standard-version) for commit guidelines.
***Select:** add ability to handle click and change event handlers ([#1839](https://github.com/chanzuckerberg/edu-design-system/issues/1839)) ([54a3de8](https://github.com/chanzuckerberg/edu-design-system/commit/54a3de8e5d1e9416b1ff24a18499ee5f02db3888))
11
+
***Select:** add support for label prop ([#1837](https://github.com/chanzuckerberg/edu-design-system/issues/1837)) ([c032ff2](https://github.com/chanzuckerberg/edu-design-system/commit/c032ff2b35f074076237aab0786325cc7237fa3a))
0 commit comments