Emit the colors as CSS variables, overridable at runtime

[SantaClaas]

Makes every generated color a CSS variable so it can be changed at runtime without a rebuild.

The problem

Theme values a plugin returns are inlined by Tailwind's JS config compat layer, so no --color-* variable was emitted at all:

.bg-primary { background-color: light-dark(#525a92, #bbc3ff); }

A plugin cannot reach @theme either — handed to addBase it is copied into the output verbatim as an at-rule nothing parses, and no utilities come out of it. The PluginAPI has no theme-registration hook; addBase is the only place a plugin can put a declaration.

How the tokens are wired

Leaves hold a literal color — every per-scheme role and every palette step — and are the only thing written out, as @property registrations:

@property --color-light-primary {
  syntax: "<color>";
  inherits: true;
  initial-value: #525a92;
}

This makes an override that is not a color fall back to the generated default instead of poisoning every declaration reading it, and makes the token animatable.

Composites are the light-dark() pairs. They are never declared — they live in the theme value as a fallback:

.bg-primary {
  background-color: var(--color-primary, light-dark(var(--color-light-primary), var(--color-dark-primary)));
}

Composites reference the leaves rather than restating their literals, so overriding --color-light-primary moves --color-primary and everything built on it. Because nothing defines --color-primary, setting it anywhere wins — including from @theme — and a color no utility uses costs nothing.

That last point is the one real lesson here: a plugin should read variables, not declare them. Anything it declares lands in @layer base, which beats the @layer theme a user's @theme override lands in, and is not tree-shaken. A first pass declared the composites in :root and silently broke @theme overrides, which had worked before this branch.

Why composites are not registered

A registered <color> property resolves to a single color at the element it is declared on and inherits as that color, so a registered light-dark() freezes at the root's color-scheme and stops following a dark subtree. Verified in a browser. initial-value may not contain var() either, which rules it out independently.

Roles are not derived from palette steps

Tempting, but a role is exactly a palette tone often enough to look right and not often enough to be correct:

	light	dark	light-high-contrast
spec-version: 2021	53/59	45/59	35/59
spec-version: 2025	12/59	13/59	28/59

The 2025 chroma multipliers and the contrast levels break the correspondence.

Two new options

contrasts — Material defines every role at four contrast levels, and the three non-default ones were 531 of 817 tokens, 68% of the output, which the example app does not use a single one of. They are opt-in now:

contrasts: high medium;   /* or `all`, or comma-separated */

The default level is always generated since the unqualified roles come from it. Breaking: bg-high-contrast-* and friends now need opting in.

colors — Material's neutral and error palettes share a name with Tailwind's and the step numbers only partly overlap, so the two scales interleave under the default extend (bg-neutral-50 is Material's mid grey, bg-neutral-500 is still Tailwind's). colors: replace sets theme.colors and drops Tailwind's palette so every name means one thing. black and white are kept explicitly, as those come from the theme rather than being built into the utilities.

Size

	raw	gzip
before	17.34 kB	3.90 kB
after	43.38 kB	6.27 kB

Fixed cost is 227 leaf registrations, ~1.83 kB gzip (581 and ~4.20 kB with contrasts: all). That part cannot be tree-shaken — a plugin cannot know which utilities the user's content will produce, and has no hook that runs late enough to prune.

Also

• createTheme was mutating the shared defaultConfiguration module object across calls
• SourceColorUndefinedError was dead code — a missing source color threw PluginOptionsUndefinedError
• docs/tailwind-plugin-api.md records the plugin API limits behind all of this, with open questions for later

Verification

41 tests pass, tsc clean, example app builds and renders. The browser-level claims — light-dark() freezing under registration, var() rejected in initial-value, invalid-override fallback, animation propagating through composites, layer ordering, and @theme overrides working again — were each measured in a browser rather than reasoned about. The snapshot covers theme and variables; snapshotting the theme alone would no longer catch a color regression.

🤖 Generated with Claude Code