Documenting a Color System: What to Write, Where to Keep It, and How to Keep It Current

Color system documentation has a specific failure mode: it is written once when the system is created, then diverges from the actual implementation as the system evolves, until it becomes actively misleading. The documentation problem for color systems is not writing it — it is keeping it accurate over time. A documentation structure that cannot survive its first quarter of production use is worse than no documentation, because it creates false confidence. **What to document: the four layers** Effective color system documentation covers four layers. The decision layer: why specific colors were chosen, what they are meant to communicate, and what constraints shaped the palette. This layer decays slowest — brand rationale rarely changes. The semantic layer: the meaning assignments, the token hierarchy, and the mapping from primitives to semantics. This layer changes when the semantic vocabulary evolves. The implementation layer: the actual token values, the CSS custom property names, the Figma variable IDs, and the platform-specific representations. This layer changes most frequently and is most often out of date. The usage layer: which tokens to use for which contexts, with examples. This layer changes when patterns evolve. **Where to keep it: proximity to the code** Documentation kept in a separate wiki or design tool diverges from the codebase fastest. Keeping token documentation in the codebase — as comments in the token definition file, as a generated reference from the tokens themselves — dramatically reduces the cost of updating it when values change. Design system teams that generate a documentation page directly from their token file (parsing the file to render a live reference) maintain accurate documentation almost automatically, because the source of truth and the documentation share the same source. **The changelog discipline** Color systems need a changelog: a dated record of what changed, why, and how to migrate. 'We changed --color-text-secondary from #6b7280 to #71717a because the gray warm-toned neutrals were inconsistent with the blue-toned primary palette' is more useful than a commit message. Changelogs serve three audiences: engineers who need to update component implementations, designers who need to update their tools, and future maintainers who need to understand why past decisions were made. Teams that maintain a color system changelog report faster incident diagnosis and more confident palette evolution. **Automated consistency checks** Documentation stays current most reliably when consistency is enforced by tooling. Linting rules that flag hard-coded color values in component files (insisting that tokens be used instead), CI checks that verify token names match the documented vocabulary, and design tool sync plugins that keep Figma variables in sync with the code token file — these reduce documentation drift to the boundary conditions where manual documentation remains necessary. The goal is not zero documentation but documentation that covers the decisions and rationale that automation cannot check.