/tailwind-token-consolidation

name: tailwind-token-consolidation
description: Use when consolidating, deduping, or reducing the number of CSS custom properties / Tailwind v4 design tokens in a globals.css file. Triggers on requests like "reduce tokens", "standardize design tokens", "too many tokens", "dedupe globals.css", "shrink @theme inline", "collapse similar colors", or any task whose goal is fewer tokens while keeping the same visual result. Covers @theme inline, --color-* aliases, :root/.dark/.dashboard-page blocks, dead-token analysis, value-similar collapse, single-use inlining, and the Tailwind v4 arbitrary-value escape syntax.

Tailwind Token Consolidation

You are reducing the count of design tokens in a Tailwind v4 `globals.css` while preserving visual fidelity.

REQUIRED, in order, for every consolidation task:

1. **Audit first, edit never-first.** Parse `globals.css` into structured blocks (`@theme inline`, `:root`, `.dark`, every other scoped block). Count tokens. Build a usage map by scanning ALL `.ts/.tsx/.css/.mdx` files (excluding `globals.css`) for class names AND `var(--...)` refs. 2. **Compute the LIVE set transitively.** A token is live if (a) its suffix appears as a Tailwind class anywhere, OR (b) it is referenced as `var(--name)` anywhere, OR (c) it is referenced inside another live token's value. Iterate to a fixed point. 3. **Scan `globals.css`'s own utility classes too.** Any `var(--...)` inside `.X { ... }` blocks (outside `:root`/`.dark`/`@theme inline`) is a hard dependency. Tokens demanded by those classes MUST stay. 4. **Build a deterministic rename map** as data (`old_suffix -> new_suffix` or `DELETE`). Apply it to globals.css AND code in a single script. Never hand-edit class names across the codebase. 5. **Verify after every pass:** run `pnpm typecheck`, `pnpm lint`, `pnpm format`, `pnpm build`. All must pass before declaring done.

Do not skip any step. A skipped step is a failed task.

The Two Reduction Levers (apply in this order)

| Lever | What it removes | Risk | |---|---|---| | 1. **Dead deletion** | Tokens with zero usage in code + zero intra-globals demand | None — safe | | 2. **Value-similar collapse** | Rename `--button` → `--card` when values are within ~5% in both light + dark | Small — pick truly-similar values only |

DO NOT inline tokens into Tailwind arbitrary values (`px-[17px]`, `text-[16px]/[1.6875rem]`, `shadow-[#000_0px_1px]`). Inlining trades named-token clutter for arbitrary-value clutter — same noise, different file. Named tokens carry intent; arbitrary values destroy it. Realistic reduction with these two levers alone is 50–60%, not 70%. If the user asks for a higher number, push back: the right answer is fewer tokens, not the same noise in className strings.

The Eight Bugs You Will Hit (anticipate them)

1. **Value precedence bug.** When N tokens collapse to one canonical name, first-write-wins from parse order is unpredictable. The result is often the WRONG color (e.g., `--danger` ends up holding `--diagnostics-table-error-border` value, which is the pale border tint, not the bright red). **Fix:** add an explicit `CANONICAL_SOURCE` override dict mapping new tokens to a specific source token whose value should win.

2. **Scoped override bug.** `.dashboard-page { --text-inline: 14px; }` only works because `--text-inline` is a `var()`-referenced custom property. Tokens overridden in any scoped block (`.dashboard-page`, `.dark .dashboard-page`, etc.) MUST stay as tokens; deleting them silently breaks the scoped override.

3. **Intra-globals consumer bug.** Utility classes inside `globals.css` (e.g., `.dropdown-menu-highlight { padding: var(--spacing-dropdown-menu-padding); }`) read tokens that don't appear in any `.tsx` file. Deleting these from `@theme` produces a runtime-undefined CSS var. **Fix:** strip `@theme inline`/`:root`/`.dark`/etc. blocks from the CSS text before scanning, then collect every `var(--X)` ref in the remainder. Those tokens MUST stay.

4. **Category cross-pollination bug.** A suffix can appear in multiple categories. For example, `organization-section-surface` is a COLOR (`white`) AND a SHADOW alias prefix (`--shadow-organization-section-surface`). If your map has both `'organization-section-surface': 'card'` (color) and `'organization-section-surface': 'surface-soft'` (shadow), the second one will overwrite the bare-token rename in your global map. **Fix:** only the COLOR category renames the bare `--X` token. For SHADOW/SPACING/TEXT/RADIUS/FONT/TRACKING, rename ONLY the `--<theme-prefix>-X` alias, never the bare name.

5. **Aggressive icon-color collapse bug.** Collapsing every "grey icon" (#696969, #898989, #b3b3b3, #c1c1c1, #dddddd) to a single `--icon` token makes the originally-light icons look noticeably darker — and on dark surfaces (e.g., dropdown menus that stay dark in both modes), it inverts the intended contrast. **Fix:** keep TWO icon tones: `--icon` (~#696969 mid-grey) and `--icon-soft` (~#b3b3b3 light-grey). Map originally-light icons to `--icon-soft`.

6. **Surface-with-conditional-transparency bug.** Some tokens are `transparent` in one mode and a concrete color in the other (e.g., `--repository-card-panel: #ffffff` in light, `transparent` in dark — the dark version is intentionally see-through). Collapsing into `--card` makes the panel opaque in dark mode, visibly changing the layered look. **Fix:** if a token's value is `transparent` in one mode and concrete in the other, do NOT collapse it with an always-opaque token. Either keep it separate or inline the conditional logic in the consuming className.

7. **`bg-X` color/image collision bug.** Tailwind v4 resolves `bg-X` against BOTH `--color-X` (background-color) and `--background-image-X` (background-image). If only `--background-image-X` exists, `bg-X` paints the gradient correctly. But if you rename some OTHER token (e.g., `--install-button-text`) to `--install-button`, you create a `--color-install-button` alias — and now `bg-install-button`