Design Systems

Search intent: color system documentation design tokens semantic naming documentation layer design system guide

Documenting Color Systems: The Three Layers Every Design System Needs

Most color systems fail not because the colors are wrong, but because the decisions behind them were never written down. When the designer who chose the palette leaves, the rationale disappears. This guide covers the minimum viable color system documentation — three layers targeting designers, engineers, and QA — and how to structure it so it actually gets used.

DocumentationDesign SystemsColor TokensProcess

Key points

Color system documentation has three distinct audiences: designers need intent (why this color, what emotion, what context); engineers need implementation (token name, value, override rules); QA and accessibility reviewers need constraints (minimum contrast ratios, which roles require WCAG AA vs AAA). Writing one document for all three audiences produces a document that serves none of them.

The most common undocumented decision is role assignment — which semantic tokens map to which base colors under which conditions. 'Primary' can mean the brand color, the most important action, or the most saturated color, depending on who you ask. Without explicit documentation, every new contributor interprets it differently and the system drifts.

Token naming tells a story about intent. A token named 'blue-500' describes what it is; a token named 'action-primary' describes what it does. Semantic naming is self-documenting — the name communicates the use context without requiring a separate reference document.

The three documentation layers

Layer 1 — Base palette: raw colors before semantic assignment. Document each base color with its hex value, OKLCH coordinates, and a plain-language description of its perceptual quality. No use-context at this layer — just what the color looks and feels like. This is the reference layer for designers and brand teams. Layer 2 — Semantic tokens: the mapping from base colors to functional roles. Document each semantic token with: (a) the base color in the default theme, (b) the base color in dark mode, (c) the use constraint ('never use as text on white — contrast ratio 2.1:1'), and (d) the intended context ('hover states on secondary interactive elements only'). This is the reference layer for engineers. Layer 3 — Composition rules: documented patterns for how tokens combine. Examples: 'action-primary on surface-default: always meets WCAG AA 4.5:1'; 'status-error on surface-default: meets WCAG AA for large text only (3:1), do not use for body-size error labels'. This is the reference layer for QA and accessibility reviewers.

Making documentation that gets used

Documentation that lives only in Notion or Confluence gets ignored by engineers and forgotten by designers within 6 months. Documentation that lives in Storybook, adjacent to the components that use the tokens, gets consulted regularly. The most effective format: a Storybook color story that renders every semantic token with its name, value, dark-mode value, use constraint, and a live contrast ratio check against both white and the default surface color. The ratio check should be automated — if the token value changes, the documentation immediately shows whether the constraint is still met. Second most effective: a Figma library with documented annotations directly on each color swatch. Engineers who use design handoff will see the documentation without leaving their workflow. Avoid documentation that requires a separate lookup step — the friction of switching tools ensures the documentation gets skipped under deadline pressure.

Practical next step

Move from the guide into a concrete palette lane

Guides explain the use case. Collections prove the taste. Packs handle the export and implementation layer.

Browse packs More guides

Related guides

Accessibility

Color Accessibility in 2025: WCAG 2.1, APCA, and the Dual-Standard Audit

WCAG 2.1's contrast ratio formula was not calibrated for font weight or size — it treats a 400-weight 12px label and a 700-weight 48px heading identically. APCA (Advanced Perceptual Contrast Algorithm), the foundation of the forthcoming WCAG 3.0, corrects this with a model that varies required contrast by font size and weight. This guide explains the practical differences, how to run a dual-standard audit, and what to prioritize during the standards transition.

Design Systems Guide

How to Build a Color Token System: The Complete Designer's Guide

A color token system is the infrastructure layer between your abstract brand palette and the code that implements it. Tokens translate color decisions into reusable, maintainable variables that can be updated globally, themed, and exported to any platform. Building a token system is not about adding complexity — it is about removing the hidden complexity that accumulates when colors are hard-coded directly into components.

Design Systems

Color Token Architecture: Building Maintainable Design Token Systems

A poorly designed token architecture makes dark mode a two-week rebuild. A well-designed one makes it a two-hour configuration change. This guide covers the structural principles — primitive, semantic, and component tier design — that determine how maintainable your color system is over time.