Documenting Color Systems: What to Write Down and Why Most Teams Skip It

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. Future contributors apply the colors inconsistently because they do not know the rules — which colors are for text only, which are decorative, which encode states, which must meet WCAG AA. This issue covers the minimum viable color system documentation and how to structure it so it actually gets used.

Documentation Design Systems Color Tokens Workflow

Highlights

Color system documentation has three distinct audiences with three different needs: 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, which colors must not be used on white backgrounds). Writing one document for all three audiences produces a document that serves none of them. The minimum viable documentation is three separate tables, each targeting one audience.

The most common undocumented decision in color systems is the 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 in the system, depending on who you ask. Without explicit documentation of what primary-500 means (the interactive element color for high-emphasis actions in the default light theme), every new contributor will interpret it differently — and over time 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. Systems built on descriptive names (what it is) require designers to memorize which blue to use for which purpose. Systems built on semantic names (what it does) are self-documenting — the name communicates the use context. The tradeoff: semantic naming requires more upfront architecture decisions, but those decisions are what you need to document anyway.

The three documentation layers

Layer 1 — Base palette: the raw colors before semantic assignment. Document each base color with its hex value, OKLCH coordinates, and a plain-language description of its perceptual quality ("warm amber at medium lightness", "near-black cool neutral"). 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 it maps to in the default theme, (b) the base color it maps to 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 the component library or Storybook, adjacent to the components that use the tokens, gets consulted regularly. The most effective documentation format for color systems: 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. The second most effective format: a Figma library with documented annotations directly on each color swatch. Engineers who use design handoff will see the documentation without leaving their workflow.

Newer issue

Color in Data Visualization: Choosing Palettes That Inform Without Misleading

2028-11-11

Older issue

Color on Small Screens: What Changes When Your Canvas Is a Phone

2028-11-25