Color Token Architecture: From Design Decisions to Production Code

Design tokens are not just a naming convention — they are an architecture decision that determines how much of your color system can be changed without rebuilding. A badly designed token architecture makes dark mode a two-week project. A well-designed one makes it a two-hour configuration change. This issue covers the structural principles that make token architectures maintainable.

Design Tokens Design Systems CSS Variables Tailwind

Highlights

The two-tier primitive/semantic split is the minimum viable token architecture. Primitive tokens are raw values: --color-blue-500: #3b82f6. Semantic tokens are intent references: --color-interactive-primary: var(--color-blue-500). The semantic tier is what components use. This separation means: change blue-500's hex value, and everything that references interactive-primary updates automatically. Add a dark mode that redefines interactive-primary to a lighter blue, and every component updates without touching component code. Without this split, dark mode requires auditing every component individually.

Semantic token naming should describe function, not appearance. --color-text-default is a good semantic token name. --color-text-dark-gray is a bad one — it describes the current value, not the purpose. When dark mode makes text light, --color-text-dark-gray is actively misleading. The naming test: can this token name remain accurate in dark mode, on a colored background, and in a high-contrast accessibility mode? If renaming the token for those contexts would make more sense, the name describes appearance rather than function.

Component tokens are the third tier many systems need. Between semantic tokens (intent across the system) and component implementation (specific usage), a component token layer allows component-level customization without breaking the semantic layer: --color-button-primary-background: var(--color-interactive-primary). This lets a design system consumer override button styles without modifying the global semantic layer. The tradeoff: three-tier token systems are significantly more complex to document and maintain. Only add the component tier when the system has confirmed use cases for component-level overrides — don't add it speculatively.

Structuring the primitive layer

The primitive layer should contain every color value the system will ever use, organized by hue. A full-scale primitive palette typically contains 6-12 hues × 8-12 lightness steps = 48-144 raw color values. The choice of lightness step distribution matters for dark mode: a linear scale (100, 200, 300 ... 900) makes it easy to find semantic equivalents in dark mode by inverting the step (what was step 200 in light mode becomes step 800 in dark mode). HSL-based lightness steps work better for this inversion than perceptual lightness steps (OKLCH L-steps), because HSL 200→800 inversion is predictable while OKLCH equivalents require manual testing. The trade-off: OKLCH produces more perceptually consistent steps, making it easier to choose semantically equivalent tones. Systems built for international deployment (multiple brand themes) often benefit from OKLCH primitives despite the inversion complexity.

Token format choices

CSS custom properties are the broadest-compatible output format — they work in every modern browser, integrate directly with Tailwind 4 (which reads CSS custom properties natively), and require no build step. JSON is the most portable format for cross-platform systems (iOS, Android, web from the same source) and is consumed directly by Style Dictionary. DTCG (Design Tokens Community Group) format, adopted by Tokens Studio and emerging as an industry standard, adds metadata (type, description, deprecated flag) that improves tooling support. For most web-only systems in 2025, CSS custom properties output from a simple JSON source is sufficient. For multi-platform systems, DTCG format + Style Dictionary is the current best practice. Avoid proprietary token formats tied to a specific tool — they create migration costs that outweigh short-term convenience.

Newer issue

Color as Navigation: How Wayfinding Systems Use Color to Move People

2028-12-16

Older issue

Color in Illustration: How Illustrators Build Palettes That Feel Intentional

2028-12-30