| Reference | Value |
|---|---|
| Subject and boundary | The token source, the generation pipeline, the generated CSS and theme, and how a product loads and overrides them. |
| Verified source | tokens.json, build.ts, parse.ts, tools/build-tokens.ts, tokens README, create-cn.ts at tag v0.40.0. Verified tag v0.40.0, commit 43bba26a73dd0f7aa01cb7c8f37d697734b367ad, checked 2026-11-10; earlier pass checked November 7, 2026. |
| Support state | Current token pipeline, generated artifacts and cascade in published v0.40.0. Parsing remains repository-internal; the public token exports are listed in the tokens README. |
flowchart LR
S["tokens.json (DTCG + yesid.clamp)"] --> P["parseTokens: validate"]
P --> B["buildAll: pure strings"]
I["UI inventory: brand/index.ts + ui exports"] --> B
B --> A["tools/build-tokens.ts: write if changed, LF"]
A --> C["packages/tokens/tokens.css + theme.css"]
A --> M["packages/motion/src/tokens.ts"]
A --> D["DESIGN.md"]
C --> G["ci:tokens drift gate + Ubuntu/Windows byte parity"]
M --> G
D --> G
| Stage | Contract |
|---|---|
| Source | packages/tokens/tokens.json is the only place a value is edited: colour, font, text, tracking, measure, size, space, radius, shadow, surface, syntax, glass, border, z, duration, ease, opacity, breakpoint, container and density groups. |
| Parse | parse.ts validates the tree; fluid values use the yesid.clamp extension with structured min, preferred and max, and incomplete triples are rejected. |
| Generate | build.ts selects the generators and returns strings with no filesystem or checkout knowledge. |
| Adapt | tools/build-tokens.ts reads the token file and the public UI inventory (brand component exports and primitive subpaths), refuses to generate DESIGN.md from an empty inventory, and writes only files whose bytes changed. --check reports drift without writing. |
| Outputs | tokens.css (custom properties plus @custom-media breakpoints), theme.css (Tailwind @theme map and semantic colour utilities), motion tokens.ts and DESIGN.md. All are committed and never hand-edited. bun run tokens:lint lints DESIGN.md with @google/design.md. |
| Verify | bun run ci:tokens regenerates and fails on a diff in the four files. CI also generates them on Windows and compares bytes with Ubuntu. |
@import '@yesid/tokens/tokens.css';
@import 'tailwindcss';
@import '@yesid/ui/base.css';
@source '../node_modules/@yesid/ui/src';
| Concern | Contract |
|---|---|
| Theme | @yesid/ui/base.css imports @yesid/tokens/theme.css. A product never pastes or regenerates the theme. |
| Overrides | Product token overrides go in the product stylesheet after these imports. |
| Fonts | Import @yesid/tokens/fonts.css from the root layout; preload only the latin faces with preloadFont in the SvelteKit preload hook. |
| Density | data-density="compact" on <html> or a subtree applies the density.compact overrides. |
| Breakpoints | Tablet from 768px, desktop from 1024px. Using @custom-media inside Svelte styles needs @csstools/postcss-global-data and postcss-custom-media in the product build. |
| Fluid type | CSS emits clamp(min, preferred, max); DESIGN.md typography uses the maximum because its schema takes one dimension. |
| Contrast | @yesid/tokens tests its semantic contrast pairs. Colours a product mixes itself are the product's to check. |
Apply these roles explicitly to prose and code.
| Reading role | Tailwind classes | Size / line height |
|---|---|---|
| Prose | text-reading lg:text-reading-desktop leading-[1.7] |
19/20px, 1.7 |
| Block code or terminal prose | font-mono text-reading-code lg:text-reading-code-desktop leading-[1.6] |
16/17px, 1.6 |
| Inline code | font-mono text-reading-inline-code |
0.95em, inherited |
| Figure caption | text-reading-caption leading-[1.6] |
16px, 1.6 |
| Supporting prose | text-reading-support leading-[1.7] |
18px, 1.7 |
| Section heading | text-reading-heading lg:text-reading-heading-desktop |
20/22px, heading hierarchy preserved |
lg is 1024px in the default Tailwind theme, matching --desktop-min; products with custom breakpoints use that threshold explicitly. Reading roles keep their size inside compact-density subtrees. text-body, text-small, text-mono and text-caption keep their values because they also size controls, labels and data. Display, hero and impact roles are separate. Floating nav sizes are one value at every tier: --text-nav-link-* 1rem (16px) and --text-nav-brand-* 1.125rem (18px).
text in tokens.json and run bun run tokens:build.BASE_TEXT_VOCABULARY in packages/ui/src/cn/create-cn.ts. The UI test that compares the merger's text vocabulary with every generated text token fails until it is there; without it, cn classifies the class as a text colour, so it can drop the caller's colour and keep a competing size.bun run api:report (the tokens report and the CSS hashes change) and add a fragment for @yesid/tokens and @yesid/ui.Because tokens.json is a Turbo global dependency, a token edit invalidates cached build, test and check results in every workspace.
No Figma variables are exported and no design-tool round trip is verified. Package tests cover parsing, serialization, generators, fonts, contrast and generated bytes; how overrides render inside a product is that product's check.