Design Token Documentation as Usage Contracts

WHY IT EXISTS: Design tokens exist to centralize visual decisions so a single change propagates everywhere, but a name like color-background-secondary means nothing without context. Documentation was invented to answer the question engineers actually ask: which token do I grab for this situation? Without it, teams embed hex codes by hand or misuse semantic tokens, defeating the purpose of the system.

THE MENTAL MODEL: Treat token documentation as a decision tree, not a style guide. A developer does not want to browse every color in your brand; they want to know that surface-elevated maps to the card background in light mode and automatically inverts in dark mode. The docs should encode the design rule so the human does not have to guess.

HOW IT WORKS: Effective documentation surfaces three things in one view: the token name, the resolved value per platform, and the intended usage. It is usually generated from the same JSON or YAML that feeds the build pipeline, so web sees a CSS variable, iOS sees a Swift constant, and Android sees an XML resource, all from one source. The best docs add taxonomy, showing whether a token is a primitive, a semantic alias, or a component-specific override, and they include deprecation notices that explain the replacement token. If the docs are handwritten in a wiki, they will rot.

WHEN TO USE IT: Build token documentation once your naming convention is stable and at least two platforms or teams consume the tokens. It is essential when you have tiered architectures where brand colors feed semantic tokens that feed component properties, because the indirection saves memory only if people understand the map. Use it when designers and engineers are arguing about the right value for a state, because the docs encode the decision and end the debate.

WHEN NOT TO USE IT: Do not invest in heavy documentation while your token taxonomy is still churning weekly. If the names are not yet stable, docs become a liability that misleads more than it helps. Also avoid documentation that is just a flat table of names and hex codes; that is a reference sheet, not a system, and it will not stop anyone from using a brand blue directly on a warning banner.

ONE CANONICAL EXAMPLE: A team maintains a spacing scale where space-4 resolves to 16px on web and 16pt on mobile. The documentation page shows the token, the platform values, and a usage note: use space-4 for the gap between related buttons in a modal footer. An engineer later needs to tighten a layout and sees space-3 is 12px, but the usage note warns that 12px is too tight for touch targets. They stick with space-4 and avoid a design review cycle.