Design Token Organizer

A token system fails in two directions: too few tokens and every button hard-codes its own blue; too many and nobody can find the right one. This skill audits the style values already living in a codebase or design file and restructures them into a three-tier architecture — primitive, semantic, component — with a naming grammar strict enough that the right token is guessable without opening the file.

When to use this skill

A stylesheet audit shows dozens of near-identical colors, spacings, or shadows
A team wants dark mode or a second brand and the styles are hard-coded
Design and engineering disagree about which values are the official ones
A component library is starting and needs a token foundation before it grows
Someone asks to "clean up the CSS variables" or "organize our tokens"

Instructions

Harvest every raw value in scope: colors, font sizes, weights, line heights, spacing, radii, shadows, borders, z-index, motion durations. Record each with an occurrence count and one example location.
Cluster near-duplicates. Six grays within a few percent of each other are one decision made six times; propose a canonical value per cluster and report the collapse ratio, for example 41 colors down to 12.
Define the primitive tier: raw values named by scale position, never by usage. color-blue-500, space-4, radius-md, shadow-2. A primitive must never contain a word like button, header, or error.
Define the semantic tier: purpose-named tokens that reference primitives. color-text-muted, color-surface-raised, space-stack-gap. Semantic names answer what something is for, and this is the only tier product code should touch by default.
Add component tokens sparingly, only where a component deliberately diverges: button-radius referencing radius-md rather than a fresh value. If a component token would merely repeat the semantic value, delete it.
Set the theming boundary: a theme — dark mode, a second brand — remaps semantic tokens only. If a theme needs to touch a primitive or a component style, the semantic tier has a hole; fix the tier, not the theme.
Write a migration table mapping every old value to its token. Keep a short explicit allowlist for genuine one-offs rather than inventing junk tokens to reach full coverage.
State the review rule that keeps the system alive: new code references semantic tokens; raw values fail review unless they are on the allowlist.

Output format

Produce three artifacts: the audit summary with clusters and collapse ratio, the token definition file, and the migration table. The definition file follows this shape:

:root {
  /* primitives — raw values, no opinions */
  --color-gray-900: #17191d;
  --color-gray-600: #5c626e;
  --color-blue-500: #2f6fed;
  --space-2: 8px;
  --space-4: 16px;
  --radius-md: 6px;

  /* semantic — purpose, references primitives only */
  --color-text-default: var(--color-gray-900);
  --color-text-muted: var(--color-gray-600);
  --color-action-primary: var(--color-blue-500);
  --space-stack-gap: var(--space-4);
}

[data-theme='dark'] {
  /* themes remap the semantic tier only */
  --color-text-default: #f2f4f8;
  --color-text-muted: #9aa1ad;
}

Naming grammar

Pattern: category, then concept, then variant — color-text-muted, space-stack-gap
Scales use consistent steps: numeric ramps (100 through 900) for color, one scheme per category for size, never two schemes mixed
No abbreviations that save three characters at the cost of a lookup; bg has earned its place, txt has not
A name must survive a value change — never color-light-blue, because next quarter it may be teal

Quality bar

Component tokens reference semantic tokens, semantic tokens reference primitives, and nothing skips a tier
Dark mode or a rebrand is achievable without editing a single component style
Every token has at least one real usage; speculative tokens are deleted, not stockpiled
The migration table accounts for every harvested value: token, allowlist, or explicitly retired
A newcomer can guess the token for muted caption text on the first try

Common failure modes

Usage names in the primitive tier, like color-button-blue, which lock the palette to today's UI
A semantic tier so thin that product code reaches past it into primitives, quietly breaking theming
Tokenizing one-offs into names like space-13px that add lookup cost and no meaning
Shipping the token file without the migration table, so old values and new tokens coexist forever