Using AI to Document Color Tokens (Without Lying)

The design system repo had forty-seven color tokens and zero usage docs. Someone pasted the CSS file into a chat model and asked for documentation. Ten minutes later they had a beautiful markdown table, semantic descriptions for every surface variable, and three hex values that did not exist anywhere in the source file. The pull request looked professional. The errors would have shipped to the public developer portal. Reviewers almost merged it because the prose was clear and the table was formatted correctly. Only a last-minute diff against tokens.css caught the invented values.

Large language models are good at prose structure and bad at exact color values. They confabulate hex codes, invent WCAG ratios, and describe tokens that sound plausible but map to nothing in your stylesheet. Used with a verification workflow, they compress documentation time dramatically. Used without verification, they generate authoritative-sounding lies that propagate into production repos because developers trust published docs more than they trust their own eyes against a hex picker.

This article covers where AI helps in color token documentation, where it fails, prompt patterns that reduce hallucination, and a human review discipline that keeps hex values, contrast pairs, and do-and-don’t examples accurate. The workflow treats the model as a drafting intern, not a source of truth. Values come from verified sources. Prompts forbid invention. Humans recompute contrast before merge. Documentation that lies about color is worse than no documentation—it trains the organization to use tokens that do not exist.

Where models help and where they fail

AI drafts naming rationale well when you supply verified token names and roles. Given --text-muted and --text-secondary with confirmed definitions, a model explains why they differ in readable prose for onboarding developers. It drafts usage guidelines from component lists you provide: surface-raised for cards, not for page background. It generates do-and-don’t HTML and CSS snippets illustrating correct and incorrect token application, useful for design system docs if someone compiles each snippet. It formats markdown tables quickly when columns cover token name, role, light value, dark value, and usage notes. It outlines migration narratives when you name the old token and the verified replacement.

AI fails at hex and OKLCH values. Models interpolate, round, or invent coordinates. Never paste AI-generated hex into tokens without checking the source file character by character. It fails at contrast ratios. LLMs approximate WCAG math and often cite wrong ratios, claiming 4.8:1 when the pair is 3.2:1. Always recompute in a contrast checker or audited tooling before any accessibility section ships. It fails at token inventory when you ask list all our color tokens without attaching the file; the model guesses common patterns like primary-500 and neutral-700 that may not exist in your system. It fails at legal and compliance claims. This palette passes WCAG AAA requires measurement, not model confidence. It fails at cross-file consistency. AI does not know your Figma variables diverged from production CSS last sprint unless you paste both exports and diff them.

The separation of labor matters. Mechanical extraction belongs to scripts. Prose generation belongs to models. Verification belongs to humans and CI. Style Dictionary output, Tokens Studio JSON, and pipelines aligned with the DTCG 2025.10 stable specification published October 2025 give you a canonical manifest. That spec stabilized token structure for cross-tool exchange in October 2025. Your docs should reference values from that manifest, not from model memory.

A verification workflow that treats AI as draft, not truth

The pipeline starts with source files: CSS, JSON, Figma export. A human or script extracts the canonical token list deterministically. Do not ask AI to find tokens. Parse them with grep, a Style Dictionary build, or your pipeline’s manifest generator. The extraction step must be reproducible. Attach the exact token list with values to prompts. Instruct explicitly: use only these values, do not invent tokens. AI drafts documentation sections: usage guidelines, do-and-don’t pairs, accessibility notes. Not the token file itself.

Human review follows a checklist that should feel as rigid as a type checker. Every hex and OKLCH matches the source file via diff tool, not eyeball. Every contrast claim is recomputed against a matrix exported from the same JSON that feeds production. Every code example runs in Storybook or an isolated sandbox. No tokens are documented that are not in the manifest. Dark mode pairs are documented together, not orphaned. Automate what repeats. Contrast matrices from token JSON should be scripted. AI interprets a matrix humans or scripts produced; it does not regenerate the matrix from imagination.

Recommended documentation sections split cleanly across owners. The token index is mechanical, generated from JSON. The semantic model explains what surfaces, text, borders, and accents mean in your product. Theme switching documents how data-theme, prefers-color-scheme, or class toggles apply. Accessibility holds matrix-driven rules with links to contrast tooling. Do and don’t sections hold reviewed code samples. FAQ drafts from real Slack questions need human confirmation before publish. Keeping canonical values out of hand-edited prose prevents the drift that makes docs worse than silence.

grep -oE '\-\-[a-z0-9-]+' src/tokens/colors.css | sort -u

Canonical values live in generated files from source, not in hand-edited markdown the model wrote. A sync script reads CSS and builds the table body. AI never touches hex cells in the index. The generated header comment in the doc file names the sync script so reviewers know which cells are machine-owned. Everything below a labeled usage section is fair game for model drafts after human review.

Team roles can overlap in small organizations. Design ops exports verified Figma variables on a schedule. Engineering maintains token JSON and runs sync scripts. An AI-assisted writer drafts prose from verified inputs. An accessibility reviewer signs the contrast matrix. A doc maintainer merges after checklist pass. What matters is the separation of value extraction and prose generation, not headcount.

Prompt patterns that constrain invention

Constrained table generation works when you paste verified JSON and forbid modification. A constraint block reduces invention. JSON input reduces parsing ambiguity compared to raw CSS alone.

You are documenting a design system color token set.

RULES:
Use ONLY the tokens and values in the JSON below.
Do not add, rename, or modify any hex value.
If a usage is unclear, write "TBD — confirm with design" instead of guessing.
Format as markdown table: Token | Value (light) | Value (dark) | Role | Usage notes

TOKEN JSON:
{paste verified export}

Generate the table and 2-sentence usage note per token.

Do-and-don’t prompts supply verified tokens and cap examples at three each direction, forbidding new names or values. Review compiles each snippet. Muted text on surface-0 needs contrast verification the model will not perform correctly.

Accessibility prose should consume a pre-computed matrix, not model arithmetic.

Here is a contrast matrix computed by our tooling (do not recalculate):

| Foreground | Background | Ratio | Pass AA |
| --text-primary | --surface-0 | 12.4:1 | yes |
| --text-muted | --surface-0 | 4.6:1 | yes |
| --text-muted | --surface-1 | 3.8:1 | no |

Write accessibility guidance for authors choosing text tokens on surface tokens.
Reference WCAG 2.2 SC 1.4.3. Do not cite ratios not in this table.

Figma-to-CSS alignment narratives document mappings you verified before prompting. Human step diffs Figma export against CSS. Changelog summarization from git diff lines works well for release notes when the diff is complete. Low hallucination risk because the model describes only what changed.

Anti-patterns deserve equal weight. Document our color system with no attachment guarantees fabrication. Asking AI to convert HSL to OKLCH mentally should be replaced by color.js, browser console, or pipeline output pasted for prose only. Publishing AI output without a second reviewer ships errors to consumers who cannot visually verify hex against production. Letting AI set token naming conventions ignores that naming is architecture; models default to Tailwind-style gray-500 unless you specify semantic patterns like text-primary.

CI can gate obvious hallucination. Fail a pull request if markdown contains hex patterns not found in tokens.json.

import { readFileSync } from 'node:fs';

const tokens = readFileSync('tokens.json', 'utf8');
const doc = readFileSync('docs/colors.md', 'utf8');
const hexInDoc = doc.match(/#[0-9a-fA-F]{6}\b/g) ?? [];

for (const hex of hexInDoc) {
  if (!tokens.includes(hex.toLowerCase())) {
    console.error(`Undocumented hex in prose: ${hex}`);
    process.exit(1);
  }
}

Style Dictionary plus sync scripts plus AI narrative in description templates integrates cleanly. Storybook tokens pages pull live custom properties from theme decorators. AI documents components; Storybook proves values render.

Case study: forty-seven tokens and a polished lie

A mid-size SaaS company had maintained tokens.css for three years without written guidance. New engineers copied hex from old components. Designers referenced Figma variables that had drifted. Onboarding meant shadowing a senior front-end developer for two weeks. The design system lead had one sprint to publish color docs before an enterprise security review that included vendor design consistency questions.

She exported tokens mechanically, built a JSON manifest with forty-seven entries including light and dark values, and ran an early contrast matrix script that output fourteen failing pairs nobody had documented. That matrix became the audit baseline, not something for the model to regenerate. She then prompted for usage prose, do-and-don’t sections, and theme-switching explanation with the constraint block and pasted JSON. The first draft was genuinely useful. Surface hierarchy finally had sentences attached. The do-and-don’t section included a mistake showing muted text on surface-2 that failed AA, which was valuable because it reflected a real failure from the matrix.

The table in the model output was the trap. Three dark mode values were wrong by one digit in the OKLCH lightness channel. They looked plausible in review because the document was long and the errors sat mid-table. A junior reviewer approved prose quality. The lead ran diff between extracted CSS and the markdown table and caught the drift. Had the table been sync-generated, the error class would not exist.

They changed process before merge. Sync script owned the index table forever. AI owned everything below a horizontal rule labeled usage. CI lint scanned for hex in prose. Contrast claims in accessibility section had to cite matrix row IDs, not freehand ratios. The second draft took longer to produce because prompts were narrower, but review time dropped sharply.

The enterprise review passed. More importantly, six weeks later a rebrand changed twelve tokens. The lead re-ran extraction, regenerated the table, prompted only for updated migration narrative from git diff, and shipped docs the same day as the CSS release. AI saved time on narrative. It did not touch values.

A contractor later proposed using AI to rewrite the contrast matrix because the brand had added three new surface tokens. The lead refused. She extended the matrix script, ran it against the updated manifest, and fed the output to the model with the same do-not-recalculate instruction used in the first release. The model produced clear guidance about which muted text pairs were now unsafe on elevated cards. One paragraph nearly claimed AA compliance for a pair at 3.9:1 because the model rounded up. The matrix said no. The error was caught in review, not in production.

Internationalization added another test. A translated doc draft localized token names by mistake, turning --text-muted into a Spanish phrase inside code fences. Lint rules caught code-shaped spans that did not match the manifest regex. Translation workflows now mark token strings as do-not-translate metadata before they reach any model. The lesson repeated across every failure mode: AI writes sentences. Scripts own numbers. Humans own judgment on edge cases scripts cannot encode.

When to skip AI entirely remains clear. Legal accessibility statements for regulated industries. Brand guidelines with trademarked color specifications from print vendors. First token naming architecture decisions. Incident postmortems where wrong color caused production outage. When AI saves the most time: initial doc pass on a mature token set that never had guidelines, translating docs for international teams while keeping values untranslated, generating onboarding quiz questions, rewriting dense WCAG references into plain language after an accessibility reviewer confirms accuracy, summarizing fifty-token diffs into release notes.

The workflow in one sentence: extract mechanically, prompt with constraints, draft with AI, verify like a linter failed. Models accelerate color token documentation when values come from verified sources, prompts forbid invention, and humans recompute contrast before merge. Use them for table scaffolding in prose sections, usage guidelines, do-and-don’t examples, and migration narratives. Never trust generated hex, OKLCH coordinates, or WCAG ratios without checking against tokens.css and a contrast checker. The organization that almost shipped the polished lie now treats undocumented hex in markdown as a build failure. That cultural shift mattered more than the ten minutes saved on the first draft.

Documentation debt compounds the same way token debt does. Every quarter without usage guidance adds another layer of copy-paste hex in product repos that will not match the next rebrand. AI lowers the cost of the first honest doc pass, but only if the output is chained to sources that outrank model memory. Treat October 2025 DTCG exports as the handoff format between design tools and doc generators. Treat CI gates on stray hex as non-negotiable. Treat contrast matrices as append-only artifacts referenced by ID in prose. The interns in this workflow are mechanical. The model is talented at explanation and dangerous at arithmetic. Write docs that respect that asymmetry and the forty-seven tokens will stay documented after the sprint ends.