How to document a color palette so the next designer can use it

A palette that exists only in a Figma file is a palette that will be misused the moment the original designer leaves the project. Color documentation is the difference between a palette that lasts and one that drifts.

Design Systems Documentation Workflow

Highlights

The three things every palette needs documented: usage intent (when to use each color), don't-use rules (common misapplications), and the decision rationale (why this specific hue and not adjacent options). Most palettes document the first and skip the other two.

Color name documentation matters more than most designers think: a token named 'primary-500' tells engineers what it is but not what it does. A token named 'action-default' communicates intent and survives design system changes without becoming confusing.

Screenshot documentation of the palette in use — real interfaces, not swatches — is the most effective way to communicate intended application. A real-world example communicates more than three paragraphs of usage guidelines.

What a color palette actually needs documented

Most palette documentation stops at the swatch + hex value level. This is the minimum viable documentation — it captures what the colors are but not how to use them. Useful color documentation has three layers: the color definition (hex, HSL, token name), the usage intent (what this color is for, in what contexts, at what scale), and the negative space (what this color is not for, common misapplications, colors it should not appear next to). The negative space documentation is almost always missing and almost always the most valuable: 'do not use accent-orange for error states, even though it is vivid, because it reads as 'caution' rather than 'error'' is the kind of documentation that prevents the next designer from making the same mistake the first designer learned through painful iteration.

Semantic naming as living documentation

Token naming is a form of documentation that lives in the codebase alongside the code. A token named 'blue-500' documents the color's position in a scale; a token named 'feedback-info-default' documents its intended function. Semantic naming has a cost — it requires more upfront thinking and can feel over-engineered for small systems — but it pays dividends when the design system grows, the team changes, or a rebrand shifts the underlying palette values. The Brand Starter Kit uses a two-layer token approach: primitive tokens (the raw color values like sand-40, ocean-70) and semantic tokens (background-surface, text-primary, feedback-error) that reference primitive tokens. This structure makes palette swaps trivial: change the primitive, every semantic token updates automatically.

Real-world usage examples as documentation

Usage guidelines in prose are frequently ignored; usage examples in the actual product are immediately understood. The most effective palette documentation includes screenshots or Figma frames showing the palette applied to real product surfaces: a card in its default and hover state, a form with an error state, a modal with a success confirmation, a header with a navigation. These examples communicate the intended application more precisely than any written description, and they serve as a reference for what 'correct' looks like when new designers question an existing color choice. The best design systems document colors in context, not in isolation. A swatch is a starting point; a swatch-in-context is documentation.

Newer issue

Color meaning is cultural: what your palette communicates across regions

2026-11-19

Older issue

Color contrast for accessibility: what WCAG actually requires and why it matters

2026-12-10