token-rename

Rename a token family so every consumer, mirror, and doc moves in the same commit — the build, not memory, finds the stragglers.

When invoked

Use this skill when a token family changes its names rather than its values — a renumbered scale, a renamed suffix grammar, a prefix change. For adding a token, use new-token; for changing what a token resolves to, no rename machinery is needed.

The governing idea

A rename touches thousands of var() sites, but almost none of them need judgment — the work is one codemod plus a build-error-driven checklist. scripts/validate-theme-mirrors.mjs and scripts/validate-token-references.mjs hold every hand mirror of token data to the CSS, and scripts/validate-token-usage.mjs fails on any reference nothing defines, so after the mechanical sweep the chain enumerates exactly what remains. Timing matters more than mechanics: renames on the published token surface are breaking changes for consumers, so batch them and land them before a release, never dribbled across versions.

Instructions

1. Write the mapping first

Old name to new name, one line per token, primitives and semantics both. The mapping is the review artifact — get it agreed before touching a file. If the rename introduces a new prefix, add it to CATEGORY_PREFIXES in scripts/generate-token-registry.mjs first (generation fails until the category has a home) and give the category its place wherever counts display.

2. Codemod the mechanical layer

A scripted replace over the token files and every consumer: CSS, TS/TSX and JSON under src/** and website/src/**, plus the token names in scripts/generate-agent-skill.mjs. Order the replacements longest-name-first so a shorter name never clobbers a longer one's substring, and match whole custom-property names (the name followed by a non-name character), never bare substrings. Run it, then git diff --stat — the shape of the diff should match the mapping's reach, and a file count far off the expectation means the pattern over- or under-matched.

3. Let the chain enumerate the rest

npm run validate-registry

Expect failures — they are the checklist, not a problem. The usual remainder, each named by its validator:

• Hand mirrors — the playground's ramp/step tables, presets.ts overrides, InspectMode's prefix strings (validate-theme-mirrors.mjs names each), and the action-family token names in scripts/validate-theme-presets.mjs (ACTION_PAIRINGS, the required action roles, any SANCTIONED_AA_GAPS keys), which that script fails on by name. Two fail at generation rather than in a validator: LIGHT_SURFACE_STEPS in website/src/lib/theme/theme-overrides.ts names neutral steps, and the tint function throws on a step the neutral table does not hold; and the consumer skills' prose in scripts/generate-agent-skill.mjs names tokens through a lookup that throws on a name the registry does not hold. The playground export's THEME.md and prompt templates in website/src/lib/theme/theme-export.ts name tokens too, and scripts/validate-theme-export.mjs fails on one that no longer exists.
• Validator parsers — a renumbering can break the regexes that parse the old shape (step patterns, label parsers). Fixing a parser to accept the new grammar is expected; weakening what it asserts is not.
• design.md — every token name it mentions is held to the registry, so stale prose fails by name, and a family size it states in words is held to the token files by scripts/validate-design-counts.mjs, so a renumber that adds or drops a step fails until the sentence moves too.
• Docs and doc pages — the foundations pages' swatch rows and src/stories/Tokens.stories.tsx carry names in data arrays the mirrors guard; page prose that describes the old grammar (a "sizes run xs to xl" sentence) is yours to catch by reading, since no validator parses prose meaning.

Repeat codemod-then-chain until green, then npm run verify — the story tests and built-HTML checks catch a renamed token that a runtime path assembles dynamically.

4. Land it whole

One category per commit, verify green between categories, and note the rename in the entry the release skill writes when the version ships — a renamed published token is exactly what a consumer's changelog exists for.

Guardrails

• Never weaken a validator to get past a rename failure — fix the data or the parser's grammar, keeping what it asserts
• Never leave a category half-renamed across commits; a commit is a complete category or it is not pushed
• Old names never linger as aliases — the token files carry one name per token, and consumers get the rename through a release note, not a shim