Skip to content

Commit

Permalink
docs(Theming): update details on using theming tooling and tailwind c…
Browse files Browse the repository at this point in the history 
…onfig (#1836)

- remove the detailed instructions for setting up tailwind in README.md
- move this instead to the Theming documentation, along with other related setup
- clean up the references to this content to better align with the new structure in Theming.mdx
  • Loading branch information
@booc0mtaco
booc0mtaco authored Jan 24, 2024
1 parent 9236ca9 commit 3fc3354
Show file tree
Hide file tree
Showing 5 changed files with 125 additions and 201 deletions.
17 changes: 17 additions & 0 deletions .storybook/components/Docs/GettingStarted.stories.mdx
View file
Original file line number Diff line number Diff line change
Expand Up @@ -30,3 +30,20 @@ Storybook offers several facilities to demonstrate how components behave. Some c
- **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

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.

### IDE Integrations

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.

- 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.
- Add the following settings in your workspace settings file:

```jsonc
{
// ...rest of the settings here
"cssvar.files": [
"node_modules/@chanzuckerberg/eds/lib/index.css"
]
}
```
- Restart VSCode
6 changes: 3 additions & 3 deletions .storybook/components/Docs/Guidelines/CodeGuidelines.stories.mdx
View file
Original file line number Diff line number Diff line change
Expand Up @@ -301,15 +301,15 @@ You can continue to use the `Icon` components' `color` prop with JavaScript vari

## Tailwind utility classes <a name="tailwind-utility-classes"></a>

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">`).
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.

Consider installing the VSCode extension [Tailwind CSS IntelliSense](https://marketplace.visualstudio.com/items?itemName=bradlc.vscode-tailwindcss) for autocomplete, linting, and hover previews.

## Theming conventions <a name="theming-conventions"></a>

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.
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.

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.
Learn more about EDS Theming [here](./?path=?path=/docs/documentation-theming--docs).

### Design Tokens <a name="design-tokens"></a>

Expand Down
167 changes: 78 additions & 89 deletions .storybook/components/Docs/Guidelines/Theming.stories.mdx
View file
Original file line number Diff line number Diff line change
Expand Up @@ -2,131 +2,120 @@ import { Canvas, Meta } from '@storybook/blocks';

<Meta title="Documentation/Theming" />

# Theming overview
# Theming

"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":
Below are instructions on how to use the tooling, configs, and tokens to define custom theme values for a project.

- 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).
## Using Tailwind with the Default Theme

Below are instructions on how to use the tooling and tokens to define custom theme values for a project.
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:

## How to apply a theme in another product
```ts
// in your tailwind.config.ts
import edsConfig from '@chanzuckerberg/eds/tailwind.config';

EDS comes with some tooling to allow easy transfer of theme data from Figma (or some style-dictionary compatible format) into code.
module.exports = {
content: ['./app/**/*.{ts,tsx,jsx,js}'],
theme: edsConfig.theme,
// ... any other tailwind config
};
```

* `eds-init-theme` - This command sets up the initial file(s) for theming your application
* `eds-apply-theme` - This command parses the style dictionary files to generate the tokens used by EDS (and tailwind, or other tools)
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.

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:
[tailwind-theme]: https://tailwindcss.com/docs/theme
[eds-tailwind-config]: https://github.com/chanzuckerberg/edu-design-system/blob/main/tailwind.config.ts

`package.json`
<hr />

```json
"eds": {
"src": "src/components/",
"dest": "src/components/"
},
```
## Setting up and using the theming tooling

EDS comes with some optional tooling to allow easy transfer of theme data from Figma (or some style-dictionary compatible format) into code.

`.edsrc.json`
- `eds-init-theme` - This command creates the initial file(s) for theming your application
- `eds-apply-theme` - This command parses the local config file to generate the tokens used by EDS components and tools

Each of these tools reads config to figure out where to read/write files.

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:

```json
// in a new file .edsrc.json
{
"src": "src/components/",
"dest": "src/components/"
}
```

`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.
`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.

### eds-init-theme

This will create an initial JSON file `app-theme.json` that defines ALL the available tokens for EDS that you can edit.
Command to run: `npx eds-init-theme`

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.
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.

```json
{
"eds": {
"anim": {
"fade": {
"quick": {
"value": "0.15s"
},
"long": {
"value": "0.4s"
}
},
"move": {
"quick": {
"value": "0.15s"
},
"medium": {
"value": "0.3s"
},
"long": {
"value": "0.4s"
}
},
"ease": {
"value": "ease"
}
},
// ...other token values
},
}
```
This file is a baseline config to be used later in the process.

### eds-apply-theme

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`.

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.

```css
/**
* Do not edit directly
* Generated on Sunday, 01 Jan 2023 12:34:56 GMT
* To update, edit app-theme.json, then run `npx eds-apply-theme`
*/

:root {
--eds-anim-fade-quick: 0.15s;
--eds-anim-fade-long: 0.4s;
--eds-anim-move-quick: 0.15s;
--eds-anim-move-medium: 0.3s;
--eds-anim-move-long: 0.4s;
--eds-anim-ease: ease;
/* ...other token values... */
}
```
Command to run: `npx eds-apply-theme`

Add this file to your core app root file.
Using `eds-apply-theme` will read in the newly-created `app-theme.json` file, and create the tokens to use in your project.

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
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:
Once run, you will have a set of theme files written to the configured `dest` path:

```diff
-const edsConfig = require('@chanzuckerberg/eds/tailwind.config');
+const edsConfig = require('./src/components/app-tailwind-theme.config');
```
- `app-theme.css` (CSS file containing custom CSS variables with the theme values for the application)
- `app-tailwind-theme.config.json` (Configuration file for advanced tailwind configuration in the application)

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`.
To use, add this file to your core app root file **after** where the imported EDS's `@chanzuckerberg/eds/index.css` file is inserted.

**NOTE**: do not edit this file directly. Instead, follow the instructions at the top of the file!
## Custom Theming and Tailwind

## How to manually apply a theme in another product
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.

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.)
You can use similar import values to what is in `@chanzuckerberg/eds/tailwind.config.ts` in your local tailwind configuration file:

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.
```ts
// in your tailwind.config.ts file
import type { Config } from 'tailwindcss';
import baseConfig from '@chanzuckerberg/eds/tailwind.config';
import {eds as customTokens} from "<edsrc.json:dest>/app-tailwind-theme.config"; // where <edsrc.json:test> is the path configured in .edsrc.json

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).
const {
background: backgroundColorTokens,
border: borderColorTokens,
text: textColorTokens,
...colorTokens
} = customTokens.theme.color;

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.)
// export the following
export default {
... // your local content export
theme: {
colors: {
...colorTokens,
},
extend: {
backgroundColor: {
...backgroundColorTokens,
},
borderColor: {
...borderColorTokens,
},
textColor: {
...textColorTokens,
},
},
screens: {
...baseConfig.theme.screens, // you can mix in any base config values into the local theme
}
... // any local theme settings
}
} satisfies Config

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.
```

## How to support theming in EDS
<hr />

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.)
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!
30 changes: 3 additions & 27 deletions .storybook/components/Docs/Guidelines/Tokens.stories.mdx
View file
Original file line number Diff line number Diff line change
Expand Up @@ -23,7 +23,6 @@ EDS is a [themeable design system](https://bradfrost.com/blog/post/creating-them
- [Color](#tier-2-colors)
- [Form](#tier-2-forms)
- [Tier 3 Component Tokens](#tier-3-component-tokens)
- [Tailwind Class Tokens](#tailwind-class-tokens)

## Style Dictionary

Expand All @@ -33,7 +32,9 @@ Tokens are defined as a collection of JSON files, which then get converted by St

## Design token architecture

Design tokens live at `src/design-tokens`, and follows this directory structure:
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`.

For typography tokens, thes directory structure is stored in the following tree:

```css
design-tokens
Expand Down Expand Up @@ -150,28 +151,3 @@ With the rest matching a corresponding use for the given component. For example,
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.

See the current set of tier 3 tokens [in storybook](/story/design-tokens-tier-3-component--colors).


## Tailwind Class Tokens

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.:

### These will not work

```html
<!-- will NOT work since tier 1 colors are not available -->
<div className="bg-brand-grape-100"></div>
<!-- will NOT work since background utility classes don't have border colors -->
<div className="bg-link-neutral"></div>
```

### These will work
```html
<!-- will work since button colors are available across all color utility classes -->
<div className="bg-button-icon-brand"></div>
<!-- will work since border colors are available for border color utility classes -->
<div className="border-link-neutral"></div>
<!-- will reflect respective color utility tokens
(background-brand-primary-strong and border-brand-primary-strong) -->
<div className="bg-brand-primary-strong border-brand-primary-strong"></div>
```
Loading

0 comments on commit 3fc3354

Please sign in to comment.