tailwind-token-consolidation

# 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` may set `background-color: white` on top of the gradient, making the button look empty/invisible. **Fix:** before collapsing a color suffix to name `X`, grep for `--background-image-X` and any `bg-X` class usage. If either exists, pick a different target name (e.g., keep `--install-button-text` instead of renaming to `--install-button`). 8. **Always-dark surface bug.** Tokens for dropdown menus, tooltips, popovers-that-stay-dark, etc., have text/icon colors that are LIGHT in BOTH light and dark modes (because the surface stays dark regardless of theme). Collapsing `--dropdown-menu-text` into `--foreground` makes the dropdown text dark in light mode (dark text on dark surface = invisible). **Fix:** before collapsing a token, diff its light-mode and dark-mode values. If both values are on the same side of the L=0.5 line (both light or both dark), it lives on an always-light or always-dark surface and CANNOT be collapsed with a flipping token like `--foreground` or `--icon`. Keep it as its own token. ## The Three-Pass Block Transformation When emitting a `:root` or `.dark` block, write entries in THIS order: ```python # Pass 1: canonical (non-renamed) entries — these set the source of truth. for name, value in original_decls.items(): target = TOKEN_RENAME.get(name) if target is None or target == name: out[name] = fix_var_refs(value) # Pass 2: CANONICAL_SOURCE overrides — explicit pick for collapsed groups. for new_token, source_token in CANONICAL_SOURCE.items(): if source_token in original_decls: out[new_token] = fix_var_refs(original_decls[source_token]) # Pass 3: other renamed entries — only if the target isn't already set. for name, value in original_decls.items(): target = TOKEN_RENAME.get(name) if target and target != name and target not in out: out[target] = fix_var_refs(value) ``` This guarantees: (a) the canonical token's original value always wins over a rename, (b) you explicitly control which source provides the value for NEW tokens like `--danger`, and (c) duplicate entries never appear in the output. ## Apply-And-Verify Loop Run this loop after EVERY rename-map change: ```bash git checkout -- apps/web # always start from a clean tree python3 /tmp/transform.py # apply the rename + inline map pnpm typecheck && pnpm lint && pnpm format && pnpm --filter web build ``` If any check fails, fix the map (not the generated output), then re-run. Hand-editing the generated `globals.css` is a footgun: the next transformation run will overwrite your fix. ## Rationalization Table | You will think | Don't | |---|---| | "I'll just delete this token, no one uses it" — without searching globals.css's own classes | Strip the @theme/:root/.dark blocks and search the remainder for `var(--X)` first | | "These two greys are basically the same" — without checking BOTH light and dark mode values | Diff both modes. A value that's close in light can diverge in dark | | "I'll inline single-use tokens into arbitrary values for extra reduction" | That's just relocating the noise. Keep named tokens; inlining is anti-consolidation | | "User asked for 70% — I should hit it even if I have to inline" | Push back. 50–60% with named tokens beats 70% with arbitrary values. Report the honest number | | "I'll fix the broken class manually after the script runs" | The next script run will revert your edit. Fix the script, not the artifact | | "First-write-wins is fine, parse order is deterministic" | Until someone reorders `:root`. Use explicit `CANONICAL_SOURCE` overrides | | "This rename target name is fine, no collisions" — but there's already a `--background-image-<name>` | Grep for `--background-image-<target>` and `bg-<target>` usage before picking the target name | ## Before Declaring Done You MUST have: 1. Run `pnpm typecheck` — exit 0. 2. Run `pnpm lint` — 0 errors, 0 warnings. 3. Run `pnpm format` — completed. 4. Run `pnpm --filter web build` — exit 0. 5. Counted final tokens with `rg "^\s*--[a-z][a-zA-Z0-9-]*\s*:" apps/web/app/globals.css -o | sort -u | wc -l`. Report before/after counts and the percentage reduction. 6. Confirmed at least the top 3 visible surfaces (cards, page background, dropdowns) render with the intended colors by reading the resulting `:root` block end-to-end and verifying canonical values match what you expected. A green build with broken visual output is a failed task. A counted reduction without verification is a failed task.