Skip to content
docsp
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

Text
src/tokens/source.ts  ->  pnpm tokens  ->  tokens/tokens.css
                                           tokens/themes.json
                                           tokens/contrast-report.md
  • src/tokens/source.ts is the single source: gray scales, accent presets, code colors, spacing, type and radius scales.
  • pnpm tokens builds the package and writes the three generated files. Never edit them by hand.
  • tokens/contrast-report.md lists the contrast of every text and background pair of every preset.
  • docs/token-map.md maps 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

Terminal
$ pnpm lint:tokens

scripts/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() or hsla() color;
  • a pixel value other than 1px and 2px (hairline borders and focus ring geometry), outside @media queries.

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.

↑ ↓ to move↵ to openSearching docsp