Design Tokens (DTCG Format)

When to use this

• You are defining or restructuring a token JSON/JSON5 file and need the W3C DTCG schema.
• You need a Style Dictionary 4.x pipeline that transforms DTCG tokens into CSS custom properties.
• You want three-tier token architecture (primitive, semantic, component) and need naming rules that scale past 200 tokens.
• You are swapping themes (light/dark, brand A/brand B) by reassigning semantic tokens to different primitives.
• Do NOT use this when you need OKLCH palette generation logic; use color-oklch-palettes instead.

Mental model

DTCG (Design Token Community Group) defines a JSON schema where every token is an object with a $value and a $type. Groups nest via plain object keys. The $type propagates down: set it on a group and every child inherits it unless overridden.

The three-tier model works like indirection layers. Primitives are raw values (a hex color, a pixel size). Semantic tokens point at primitives by alias ({color.blue.500}). Component tokens point at semantics ({color.surface.primary}). You never use a primitive directly in code; the semantic layer is the contract between design and engineering. Theming works by swapping which primitives the semantic layer resolves to. This means a dark theme is a new set of semantic-to-primitive mappings, not a second copy of component tokens.

Style Dictionary 4.x consumes DTCG natively. It resolves aliases at build time, runs transforms (name casing, unit conversion, color format), and emits platform files. The pipeline is: source files, preprocessors, token resolution, transforms, format, file output.