Design Token Patterns

Quick Guide: A token system is a one-way dependency graph — primitives hold raw values, semantic tokens name intent, component tokens hold local exceptions, and consumers only ever touch the top two tiers. Deliver tokens as CSS custom properties: primitives in :root, semantic aliases reassigned per scope, component tokens on the component's own selector. Name a token for its role, never for the mode it happens to appear in (--color-surface-raised, never --color-dark-bg). Store complete colour values rather than bare channel triplets. Where tokens must exist in more than one language, generate every output from one DTCG source.

Detailed Resources:

• examples/core.md — tier construction, aliasing, naming grammar, custom property delivery, @property registration
• examples/scales.md — generated spacing and type series, modular scales, fluid type, density multipliers
• examples/pipeline.md — DTCG source files, build platforms, typed TypeScript export, publishing outside the owning repository
• examples/utility-framework-bridge.md — projecting tokens into a layer that generates utility classes
• reference.md — naming grammar table, DTCG $type reference, build config shape, authoring checklist

Which path applies

• Tokens live only in this repository and are only ever read from CSS — hand-write the custom properties. Follow examples/core.md and examples/scales.md; a build step producing one file nobody else reads is cost with no payoff.
• Tokens must exist in a second language or platform, or ship outside the repository that owns them — author a DTCG source and generate every output from it. Follow examples/pipeline.md; the tiers and names are identical, the source is JSON instead of CSS.