Pipeline
The token pipeline is active for foundation CSS variables. It proves that tokens build from source and that the production stylesheet consumes the generated output.
Source and output#
| Item | Path or command | Role |
|---|---|---|
| Source tokens | tokens/core.tokens.json | Human-reviewed DTCG $value and $type token source |
| Build config | style-dictionary.config.mjs | Style Dictionary configuration and custom name transform |
| Generated CSS | assets/css/generated/tokens.css | Generated custom properties bundled before site CSS |
| Theme collections | tokens/themes/{light,dark}.tokens.json | Selector-scoped semantic colour overrides |
| Generated theme CSS | assets/css/generated/themes.css | Light and dark collection output |
| Generated data | data/brand/tokens.yml | Generated Hugo data for token reference tables |
| Tailwind bridge | tailwind.tokens.cjs | Generated token-backed Tailwind theme values |
| Diagram exports | tokens/exports/diagram.json, static/tokens/diagram.json | Resolved values for repository and published diagram use |
| Build command | npm run tokens:build | Rebuilds generated token CSS |
| Data command | npm run tokens:data | Rebuilds generated Hugo token data |
| Tailwind command | npm run tokens:tailwind | Rebuilds the generated Tailwind theme bridge |
| Theme command | npm run tokens:themes | Rebuilds selector-scoped theme collection CSS |
| Diagram command | npm run tokens:diagrams | Rebuilds diagram token exports |
| Test command | npm run tokens:test | Validates alias resolution and colour contrast |
| Update command | npm run tokens:update | Rebuilds and verifies all generated token output |
| Check command | npm run tokens:check | Verifies generated output and CSS references |
Hugo bundles the generated CSS before the processed site stylesheet, so assets/css/site.css can consume variables such as --color-accent, --font-serif, and --space-s-m without owning their values. outputReferences: true keeps the active colour alias chain visible in generated CSS: semantic interface variables resolve through their --color-palette-* primitives. The docs render category tables from data/brand/tokens.yml, which is generated from the same token metadata.
Use Token architecture for the source boundary, theme selection, consumer model, and complete change routine.
Build rules#
npm run tokens:buildshould finish without warnings.npm run tokens:updateshould rebuild core CSS, data, Tailwind values, theme CSS, and diagram exports before a token change is committed.npm run tokens:checkshould pass without mutating the working tree.- Generated output should be committed only when it is deterministic.
- Token source changes and generated output should land in the same commit.
visibility: internalis for supporting implementation primitives. It remains available for generated CSS aliases but does not appear in the public token table or Tailwind bridge.- CSS should not reference a generated token that is missing from the output.
- Site CSS must not contain raw hexadecimal colour literals. Add a semantic token instead, then consume its generated CSS variable.
- Site CSS must not use an ungoverned Tailwind colour-palette utility. The approved Tailwind colour utilities resolve through generated token variables.
- Site CSS must not use raw arbitrary font-weight, font-size or tracking utilities. Add or reuse a typography token and its token-backed utility instead.
- Warnings are treated as work, following ADR 0004’s dependency and warning policy.
Inspiration#
Red Hat Design System uses tokens as a productized design-system library, with installation guidance, generated token categories, and developer usage notes. That is useful inspiration, but this site keeps a smaller pipeline: source tokens, generated CSS, generated Hugo data, and category pages rendered from that data.