/token-documentation

name: token-documentation
description: "Write documentation for design tokens — covering semantic intent, usage context, and do/don't examples. Trigger when someone says: document these tokens, token reference, what does this token mean, token usage guide, write the token docs, token intent, or anything about creating human-readable documentation for design tokens."
references:
  - ../../knowledge-notes/token-architecture.md

Token documentation

A skill for writing documentation for design tokens that communicates semantic intent, usage context, and application rules across all three tiers. Output is reference documentation that tells consumers what a token means and how to use it correctly — not just what value it resolves to.

Context

Token documentation has a chronic problem: it stops at the value. A token reference that says `color.action.primary: #0066CC` tells a consumer the resolved colour, but not when to use it, what it communicates to users, which components it belongs on, or what happens when it is misapplied. Teams that rely purely on value-level documentation make naming decisions based on colour proximity rather than semantic intent, and the system drifts.

The goal is documentation that makes the semantic contract legible. A consumer reading these docs should come away understanding not just what a token resolves to, but why it exists and where it belongs.

Boundaries

This skill documents existing tokens. It does not create new tokens, redesign the token architecture, or validate token file structure (use `schema-validator` for structural validation, `token-audit` for architectural assessment). If the token set is empty or has not been defined yet, this skill does not apply — help the team establish their token architecture first. If only primitive tokens exist (no semantic tier), note that the documentation value is limited since primitive tokens are largely self-documenting, and suggest establishing a semantic tier before investing in documentation.

---

Configuration

Before producing output, check for a `.ds-ops-config.yml` file in the project root. If present, load:

• `integrations.style_dictionary` — if enabled, parse the token tree automatically
• `integrations.figma` — if enabled, pull Figma variables to cross-reference
• `integrations.documentation` — if enabled, check for existing token docs to update rather than rewrite

Auto-pull integrations

**Style Dictionary v4** (`integrations.style_dictionary.enabled: true`):

• Parse the config to extract the complete token tree with resolved references
• Auto-detect tier structure, token names, values, and reference chains
• This replaces the manual "provide your token files" step

**Figma MCP** (`integrations.figma.enabled: true`):

• Pull Figma variable collections and modes (light/dark, brand variants)
• Cross-reference Figma variables against code tokens for completeness check

**Documentation platform** (`integrations.documentation.enabled: true`):

• Check for existing token documentation to incorporate rather than overwrite

If an integration fails, log it and proceed with manual input.

Step 1: Gather the token set

Ask for or confirm (skip questions already answered by auto-pull):

• The tokens to be documented (a specific set, a full tier, or the entire system)
• The source format: JSON, DTCG, Tokens Studio export, Style Dictionary configuration, CSS custom properties (`:root { --token: value; }`), SCSS/Sass variables (`$token: value;`), TypeScript/JavaScript token objects, Tailwind config (`theme` / `extend` block), or listed by name
• Any existing documentation or notes on intent that should be incorporated
• The audience for the documentation (designers only, developers only, or both — this affects the technical depth)

For CSS custom properties and SCSS variables: infer token hierarchy from naming patterns (e.g. `--color-blue-500` → primitive, `--color-action-primary` → semantic, `--button-bg-default` → component). For Tailwind configs, the `theme` block is the token source. For TypeScript/JavaScript token objects: the exported object hierarchy maps directly to token tiers — nested keys are the path (e.g. `tokens.color.brand.blue[500]` → `color.brand.blue.500`). Include both the object key path and resolved value in the documentation. For `as const` objects, the literal types provide exact values without runtime ambiguity.

If the full system is being documented, suggest starting with the semantic tier. Primitive tokens document themselves — their names and values are sufficient. Semantic tokens are where intent documentation does the most work. If the system uses component tokens, include those after semantics.

Step 2: Document by tier

Primitive tokens

Primitive token documentation is lightweight. The goal is to establish what the scale looks like and what it is derived from — not to explain when to use `color.blue.400` vs `color.blue.500`, because that is the semantic tier's job.

Document:

• Scale overview: how the scale is structured and what increments mean
• Source: where the values come from (a specific palette tool, a brand colour system, a typographic scale)
• Usage constraint: one sentence stating that primitive tokens should not be used directly in components — they are referenced by semantic tokens

Format per primitive group:

[Token group name]
Scale: [describe the scale — e.g. 50–950 in 50-point increments, or T-shirt sizing]
Source: [where values come from]
Values: [list or reference to the token file]
Usage: Reference via semantic tokens only.

Semantic tokens

Semantic tokens carry the intent contract. This is where most documentation effort belongs.

For each semantic token or semantic token group, document:

**Intent:** What does this token communicate to users? One sentence. Not what it looks like — what it means. Example: `color.action.primary` — Identifies the primary interactive action in a given context. Signals that an element is the m