Tailwind 4 made tokens feel closer to CSS

Tailwind v4 puts more of the token system in the place where tokens eventually have to work: CSS.

That does not make token maintenance automatic. It does make bad names and duplicated decisions easier to see. A theme can be read alongside the cascade instead of being treated as a separate translation layer.

Tokens are promises about reuse. The cleanup question is whether the promise is still true.

a name creates a maintenance obligation

A value used once can remain local. A value used across several surfaces may deserve a name. The trouble starts when every temporary decision gets promoted to shared vocabulary.

@theme {
  --color-blue-button: oklch(0.61 0.19 255);
  --color-new-blue-button: oklch(0.58 0.21 260);
  --color-marketing-blue: oklch(0.64 0.18 252);
}

Those names describe the history of a team making changes, not a coherent theme. They also make the next change harder: nobody knows which blue button is safe to remove.

The first cleanup step is often deletion, not another naming convention.

separate palette from product meaning

Primitive and semantic tokens answer different questions.

Primitives describe a scale:

@theme {
  --color-slate-950: oklch(0.16 0.03 250);
  --color-blue-600: oklch(0.55 0.18 255);
  --space-3: 0.75rem;
  --space-4: 1rem;
}

Semantics describe use:

@theme {
  --color-page-bg: var(--color-slate-950);
  --color-action-bg: var(--color-blue-600);
  --space-card-padding: var(--space-4);
}

The indirection is worthwhile when the role is real. A page background can change color without changing what it means. An action can keep its role while the palette changes. A copied primitive cannot express either distinction.

component tokens need an exit test

Component-level tokens are useful when a component owns a decision that other components should not inherit.

@theme {
  --color-card-border: oklch(0.84 0.02 250);
  --shadow-card: 0 1px 2px rgb(0 0 0 / 0.08);
}

They become expensive when every component gets a private vocabulary. Before adding one, I would ask two questions:

• Is this value likely to be reused?
• Would changing it globally be an intentional change or an accident?

If the answer to both is no, a local declaration may be clearer. A token should earn its scope.

repeated arbitrary values are already a system

Arbitrary values solve legitimate edge cases. A layout may really need a 13 pixel offset.

The smell is repetition.

<section class="rounded-[7px] p-[18px] shadow-[0_2px_12px_rgb(0_0_0_/_0.08)]">

When the same arbitrary value appears in several places, the system has a decision without a name. The answer is not always to add a token. It may be that these components should not be identical. The point is to make that choice deliberate.

dark mode tests the names

Dark mode exposes tokens that were named for appearance rather than role.

Light gray and dark gray become ambiguous when text, borders, focus rings, and disabled controls all need different contrast behavior. Role-based names leave room for the values to change per theme.

@theme {
  --color-bg: oklch(0.99 0.01 250);
  --color-fg: oklch(0.18 0.02 250);
  --color-border-subtle: oklch(0.86 0.02 250);
}

@media (prefers-color-scheme: dark) {
  :root {
    --color-bg: oklch(0.16 0.02 250);
    --color-fg: oklch(0.94 0.01 250);
    --color-border-subtle: oklch(0.28 0.02 250);
  }
}

The names survive the mode switch. That is a good test for whether they describe a stable responsibility.

cleanup should leave less behind

A useful token cleanup is quiet. It removes dead names, merges values that are genuinely the same, returns one-off choices to components, and adds semantic names only where the product repeats a decision.

Tailwind v4 makes this work feel closer to editing CSS because more of the token layer is visible there. The practical gain is not novelty. It is that the browser’s final vocabulary is closer to the source vocabulary, so drift has fewer places to hide.