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:

# 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:

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.