token-documentation

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