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.

Before you begin: verify references

Confirm that every path in this skill's frontmatter references: exists relative to this SKILL.md. If any is missing, stop: the install is incomplete, usually because a flattening installer (for example npx skills install) dropped the repo-root knowledge-notes/ directory. Tell the user to reinstall by a method in 1-INSTALL.md and run verify-install.sh from the install root. Proceed without the references only if the user explicitly says to, and then say in the output that it was produced without the pack's reference material.

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.