references/documentation-and-ownership.md

Documentation, ownership and renaming

Read at steps 5 and 6 of token-naming. The five questions come from the source page's "Documenting" panel; the templates that answer them are registry decisions (see source-notes.md).

The five questions

The page asks, and does not answer:

1. What is related?
2. How do people find values?
3. Which tokens did we apply?
4. Who is responsible?
5. Where can I find the list?

A token set is documented when each question has a written answer that a new developer, designer, content specialist, QA engineer, product manager or accessibility specialist (the page's collaboration list) can find without asking.

Documentation template

One page per token set, or one section per category in a larger system. Headings match the questions so readers recognise them.

# Tokens: <set or category>

## Grammar
<one line: the declared segment order, separators per platform, tier prefixes>
<one line: what `primary` means in this set>

## Related tokens
<groups that change together: a text role and its on-accent variant, a
surface and its border, a duration and its easing>

## How to find a value
<the search path a reader follows: category, then role, then variant,
then state; the file or Figma collection each category lives in; the
decoder for abbreviations if any (bg, fg)>

## Where applied
| Component | Tokens used |
| --- | --- |
| Button | semantic.action.primary, semantic.text.on-accent, ... |

## Owner
<see the owner table>

## Where the list lives
<one repository path or URL; code is the definitive source, every other
copy (Figma, docs site) is generated or synced from it>

## Deprecated
<the rename map>

The "Where applied" table is the answer to "which tokens did we apply". Fill it from the code, not from memory: grep the component for token references and paste the list. When a component's list is empty, it is hard-coding values, which design-system and design-debt-audit audit.

Owner table

One owner per token group. A group without an owner is where duplicates and orphaned tokens accumulate.

Roles are placeholders; replace with names. The cadence and channel columns are what makes "who is responsible" answerable in practice: an owner with no review date and no channel is a label. Accessibility review of colour changes belongs with the accessibility specialist regardless of who owns the group.

Naming alignment workshop

The page's workshop goals, arranged as an agenda. Timings are a registry suggestion for a 60 minute session; the page gives none.

The output of the session is the "Grammar" section of the documentation template, filled in, plus the owner table with names.

Rename map

Renaming a token without a window breaks every consumer at once. Keep the old name as an alias of the new one for a stated period, mark it deprecated where the tooling shows it, publish the map, then remove.

In DTCG JSON, the old token keeps its entry with $value set to the alias of the new token and $description beginning Deprecated: with the replacement and the removal version. In CSS, the old custom property is declared as var(--new-name) with a comment on the same line. Build tooling that can emit deprecation warnings (Style Dictionary's deprecated attribute, Figma's variable description) should carry the same text.

How long the window stays open, how the removal is announced and what a breaking change requires are design-system-governance decisions; this skill only insists that the window exists and the map is published.