feat: Tailwind v4 plugin, and the shadcn remap as a stylesheet

[abernier]

Supersedes #167 (Tailwind half only, closed) — this one also covers shadcn.

Tailwind

@import "tailwindcss";
@plugin "material-theme-builder/tailwind" {
  custom-colors: myCustomColor1, myCustomColor2;
}

instead of the ~180-line @theme inline { --color-*: var(--md-sys-color-*) } block.

Custom colors are the part a stylesheet could never cover — their names live in the app, not in the package — so they were exactly the manual step the README kept warning about ("Do not forget to manually add your custom colors"). Each one registers its four M3 roles and its shades, under both spellings: bg-myCustomColor1 (what the README documented) and bg-my-custom-color-1 (what toTailwind() emits).

Options: prefix (default md), custom-colors, shades (default true — off leaves Tailwind's own neutral-* alone). Read case- and dash-insensitively, because Prettier lowercases CSS declaration names and would otherwise turn a user's customColors: into customcolors: on save. An unknown option throws rather than silently doing nothing.

shadcn

@import "material-theme-builder/shadcn.css";

instead of the 31-line :root, .dark { … } block. The file already existed in src/, it just wasn't exported.

It stays a stylesheet rather than an option on the plugin, on purpose: a plugin can only reach @layer base, and shadcn's own :root/.dark are unlayered — layered styles lose to unlayered ones whatever their specificity, so a shadcn: true option would have been a silent no-op on a default shadcn globals.css. The "import it after" note stays, for that same cascade reason.

Same reason behind a caveat now documented: for the color names shadcn and M3 share (primary, secondary, background), shadcn's @theme inline beats the plugin's theme whatever the order — Tailwind gives a CSS @theme precedence over a plugin's. Those utilities keep shadcn's semantics, which shadcn.css has already pointed at M3.

Also

• token names move to src/lib/tokens.ts, so the plugin — which runs inside the CSS build — reads them without pulling Material Color Utilities in (dist/tailwind.js is 7 KB, no runtime dep). Re-exported from builder.ts; public surface unchanged.
• tailwind.css keeps working and gains the two roles it was missing: --color-surface-tint, --color-surface-variant — found by a new test holding the shipped stylesheets against what the plugin registers.
• another test holds the plugin against toTailwind(), name for name, so the two spellings of the theme can't drift.
• tailwindcss added as an optional peer dep.

Verified

pnpm run lgtm green (72 tests). Beyond unit tests, the built dist/ was run through a real @tailwindcss/postcss build: utilities, tonal shades, opacity modifiers (bg-primary/50), custom colors in both spellings, and a shadcn-shaped globals.css where --background ends up resolving to --md-sys-color-surface.

🤖 Generated with Claude Code

[abernier]

Second commit, after review: the one-liner was hiding what the wall of declarations made obvious. The listings are back in the README — folded, next to the two rules that generate them:

• scheme role → --color-<role> → utility, kebab-cased
• the shade → tone table (50→95 … 950→5), which was only ever implicit before

Same for shadcn: the 31-line block is in the README again, plus a paragraph on how to read it (containers back shadcn's tinted fills, outline-variant its borders).

Three tests hold the README against the plugin — a listing that drifts fails the build instead of quietly misleading its reader. Checked by deleting a line from each: both fail as expected.

[abernier]

Correction on the previous comment: the README tests are gone, and so is the generator I floated. The doc commit is now README-only — the listings are back, kept by hand.

What still guards the mappings are the two tests on the files that actually ship: src/tailwind.css against the plugin name for name (that is what found the missing --color-surface-tint), and src/shadcn.css against SHADCN_MAPPING line for line. The README points at both files rather than claiming to be checked itself.

[abernier]

Reverted the breaking part: tailwind.css stays exported, changeset back to minor. The PR is now strictly additive — nothing is removed, no semantics change for anyone already using the pasted block, no migration.

Also corrected a claim I made earlier in this PR and had wrong: @import "material-theme-builder/tailwind.css" after a @theme inline of your own does not win under Vite — the import gets hoisted above it. Verified with a real vite build. The reliable way to take a shared name back is a @theme written (not imported) in globals.css, which is what the README now says. Only secondary needs it.

toTailwind({ shadcn: true }) output is byte-identical to main again; src/styles/globals.css too, so no Chromatic movement.