Design Tokens — the single source of truth

Design tokens are named, structured key–value pairs that store every visual decision in a design system — color, spacing, type, radius, motion — as data instead of hardcoded literals. One token (color.bg.default) is authored once and consumed everywhere: Figma, CSS, iOS, Android, Tailwind. Change the value, every surface updates. Tokens turn "the brand blue" from a number scattered across 400 files into one row that design and engineering both point at.

Why tokens (read before you skip the semantic tier)

• Single source of truth. The value lives in one place. No #2563EB typed by hand in a component.
• Design↔code parity. Designers edit Figma variables; engineers consume the same names. The handoff is the token, not a redline.
• Theming for free. Light/dark, multi-brand, density, and platform are modes of the same semantic tokens. Swap the mode, not the markup.
• Scale. A 12-step gray ramp, a type scale, a spacing scale — defined once, referenced by intent. Adding a brand is a new mode, not a rewrite.
• Refactor safety. Renaming or deprecating a decision is a token change with a known blast radius, not a global find-and-replace.

The 3-tier architecture (the core mental model)

Tokens flow in one direction. Components reference semantic. Semantic references primitive. Primitive references nothing. Never let a component reach past semantic into a raw primitive.