On this page
Design tokens
The token pipeline, the generated files and the lint that keeps raw values out of components.
Every color, size, radius and font of the interface is a token. Components use only tokens, so a theme axis changes one set of values instead of many components.
Pipeline
src/tokens/source.ts -> pnpm tokens -> tokens/tokens.css
tokens/themes.json
tokens/contrast-report.mdsrc/tokens/source.tsis the single source: gray scales, accent presets, code colors, spacing, type and radius scales.pnpm tokensbuilds the package and writes the three generated files. Never edit them by hand.tokens/contrast-report.mdlists the contrast of every text and background pair of every preset.docs/token-map.mdmaps every measure of the design specification to its token, with the reason for every change.
CI runs pnpm tokens and fails when the generated files differ from the committed ones, so commit them together with
source.ts.
Lint
$ pnpm lint:tokensscripts/lint-tokens.mjs reads the components, layouts, scripts and styles/ of the package and fails on:
- a raw hex color such as
#1b1b1a; - an
rgb(),rgba(),hsl()orhsla()color; - a pixel value other than
1pxand2px(hairline borders and focus ring geometry), outside@mediaqueries.
Add a token to source.ts instead, run pnpm tokens, and use the custom property.
Theme attributes
The theme axes reach the tokens through attributes on <html>: data-mode, data-grays, data-radius,
data-header, data-code, data-headings, and the code theme through data-code-theme and data-code-mode.
tokens.css defines values per attribute. The accent arrives as four inline custom properties, from which
tokens.css derives --accent and --on-accent for the current mode.