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