Architecture

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.

Pipeline

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.

Consumer cascade

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

Ordinary reading roles

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

Adding a text-size token

  1. Add it under text in tokens.json and run bun run tokens:build.
  2. Add its name to 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.
  3. Show it in the Gallery token sheet, run 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.

Limits

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.