We're live on Product Hunt!Support us
ColorArchive

A curated color library with 5,000+ algorithmically generated colors. Browse, search, save favorites, and export palette tokens — no account required.

CollectionsFamiliesNotesGuidesFree ResourcesConvertColorblindAboutSupportUpdates
Ready for static export
Privacy·Terms·Refunds·Cookies·Commerce Disclosure
colorarchive.org · © 2026 ColorArchive
Skip to content
ColorArchive
ProLog in
ArchiveAll ColorsCollections
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.

Featured collection
Data Dashboard

Cobalt signal, teal confirmation, amber warning, crimson alert, and slate neutral — a perceptually balanced palette designed for analytics dashboards and data visualization interfaces.

Open collectionAll collections
Open next
Design Token GeneratorWCAG Contrast AuditorBrand Starter Kit
Practical next step

Move from the guide into a concrete palette lane

Guides explain the use case. Collections prove the taste. Pro handles the export and implementation layer.

Upgrade to ProMore 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.
Token Architecture
Design Token Architecture for Color: Building Scalable, Maintainable Systems
A well-structured token architecture makes color systems easier to maintain, theme, and evolve. The three-tier model — primitive, semantic, component — provides the foundation for color systems that survive rebrands, multi-theme requirements, and team scale.
Design Systems
Color Token Naming Conventions: Primitive, Semantic, and Component Layers
How to structure a three-layer token naming system that scales from a small product to a multi-brand design system — with practical naming patterns used by leading teams.