material-theme-builder 3.3.0 → 5.0.0

package/README.md

@@ -97,19 +97,43 @@ import { Mtb } from "material-theme-builder/react";
 >
 > Typically wrapping `{children}` in a
 > [layout](https://nextjs.org/docs/app/getting-started/layouts-and-pages#creating-a-layout).
+>
+> `<Mtb>` renders its `<style>`, so it works both server- and client-side.
+> Client-side is what you want when the theme has to be interactive through
+> `setMtbConfig`.
 
 > [!NOTE]
 >
-> CSS varnames are always kebab-cased, e.g. `myCustomColor1` →
-> `--md-sys-color-my-custom-color-1` / `--md-ref-palette-my-custom-color-1-<tone>`
+> For a theme that is not interactive / never changes at runtime, skip the
+> component entirely: the root entry holds `builder` alone, so a Server
+> Component can call it and emit `toCss()` into the document itself — no client
+> JS, and no `useMtb`.
+>
+> ```tsx
+> import { builder } from "material-theme-builder";
+>
+> const css = builder("#0e1216", { scheme: "vibrant" }).toCss();
+>
+> export default function RootLayout({
+>   children,
+> }: {
+>   children: React.ReactNode;
+> }) {
+>   return (
+>     <html lang="en">
+>       <head>
+>         <style dangerouslySetInnerHTML={{ __html: css }} />
+>       </head>
+>       <body>{children}</body>
+>     </html>
+>   );
+> }
+> ```
 
 > [!NOTE]
 >
-> `<Mtb>` injects the CSS from the client, and is the only thing here carrying
-> `"use client"`. The root entry holds `builder` alone — so from a
-> [React Server Component](https://react.dev/reference/rsc/server-components)
-> you can call it and emit `toCss()` into the document yourself, without
-> shipping components the page never renders.
+> CSS varnames are always kebab-cased, e.g. `myCustomColor1` →
+> `--md-sys-color-my-custom-color-1` / `--md-ref-palette-my-custom-color-1-<tone>`
 
 ## `useMtb`
 
@@ -129,25 +153,26 @@ return (
 
 ## Tailwind
 
-Compatible through [theme variables](https://tailwindcss.com/docs/theme), in two
-halves — a stylesheet for the standard tokens, and a plugin for the custom
-colors, the one part a shipped file cannot know:
+Compatible through [theme variables](https://tailwindcss.com/docs/theme) — one
+plugin, one line:
 
 ```css
 @import "tailwindcss";
 
-@import "material-theme-builder/tailwind.css";
 @plugin "material-theme-builder/tailwind" {
   custom-colors: myCustomColor1, myCustomColor2;
 }
 ```
 
-No hand-written block either side. Each name listed brings its four scheme roles
-and eleven shades — `bg-myCustomColor1`, `text-on-myCustomColor1`,
-`bg-myCustomColor1-container`, `bg-myCustomColor1-300`. Drop the `@plugin` line
-if you have no custom colors.
+Drop the `custom-colors` block if you have none.
+
+<details>
 
-The plugin takes a `prefix` too, mirroring `builder({ prefix })`:
+Each name listed brings its four scheme roles and eleven shades —
+`bg-myCustomColor1`, `text-on-myCustomColor1`, `bg-myCustomColor1-container`,
+`bg-myCustomColor1-300`.
+
+`prefix` mirrors `builder({ prefix })`:
 
 ```css
 @plugin "material-theme-builder/tailwind" {
@@ -156,65 +181,27 @@ The plugin takes a `prefix` too, mirroring `builder({ prefix })`:
 }
 ```
 
-The plugin can carry the standard tokens on its own — `@plugin` without the
-`@import` — for a setup that would rather not import CSS at all. Read the
-warning below first if you also use shadcn.
+</details>
 
 > [!TIP]
 >
-> Both halves declare their colors as
+> Colors are declared as
 > [inlined theme values](https://tailwindcss.com/docs/theme#referencing-other-variables):
-> `bg-primary` compiles to `background-color: var(--md-sys-color-primary)`,
-> with no `--color-primary` in between. That matters for nesting — a
-> `--color-primary` declared on `:root` would resolve against `:root`, out of
-> reach of a nested `<Mtb>` re-declaring the M3 properties.
-
-> [!WARNING]
->
-> Theme values a plugin contributes are _defaults_: an `@theme` block of your
-> own wins over them whatever the order, where the stylesheet — being CSS —
-> wins by import order.
->
-> That is why the standard tokens are left to the stylesheet. shadcn's
-> `@theme inline` claims three names M3 also uses — `background`, `primary`,
-> `secondary` — and with the two halves above the stylesheet takes them back,
-> so shadcn changes nothing. Only if you drop the `@import` and let the plugin
-> carry the standard tokens do you have to hand those three back yourself:
->
-> ```css
-> @theme inline {
->   --color-background: var(--md-sys-color-background);
->   --color-primary: var(--md-sys-color-primary);
->   --color-secondary: var(--md-sys-color-secondary);
-> }
-> ```
->
-> Left alone, `bg-secondary` resolves through shadcn's `--secondary`, which the
-> [shadcn](#shadcn) section below remaps to `secondary-container` — a tone 90
-> where you asked for a tone 40, under text still colored `on-secondary`.
+> `bg-primary` compiles to `background-color: var(--md-sys-color-primary)`, with
+> no `--color-primary` in between. That one would sit on `:root`, out of reach
+> of a nested `<Mtb>`.
 
 <details>
-<summary>The theme variables the stylesheet declares</summary>
+<summary>The names it declares</summary>
 
-Generated from [`toTailwind()`](#programmatic-api), so the two cannot drift:
+115 standard ones — every M3 scheme token (`bg-surface-container-low`,
+`text-on-primary`, `border-outline-variant`…), plus eleven Tailwind shades for
+each of `primary`, `secondary`, `tertiary`, `error`, `neutral` and
+`neutral-variant` (`bg-primary-300`). Then four roles and eleven shades per
+custom color you name.
 
-```css
-@theme inline {
-  --color-background: var(--md-sys-color-background);
-  --color-error: var(--md-sys-color-error);
-  --color-error-container: var(--md-sys-color-error-container);
-  --color-inverse-on-surface: var(--md-sys-color-inverse-on-surface);
-  --color-inverse-primary: var(--md-sys-color-inverse-primary);
-  --color-inverse-surface: var(--md-sys-color-inverse-surface);
-  --color-on-background: var(--md-sys-color-on-background);
-  --color-on-error: var(--md-sys-color-on-error);
-  /* ... */
-}
-```
-
-115 names in all — every M3 scheme token, plus eleven Tailwind shades for each
-of `primary`, `secondary`, `tertiary`, `error`, `neutral` and
-`neutral-variant`.
+They are theme _defaults_, so an `@theme` block of your own wins over them
+whatever the order. See [shadcn](#shadcn), where three names collide.
 
 </details>
 
@@ -225,157 +212,110 @@ Pre-requisites:
 - You should use
   [`tailwind.cssVariables`](https://ui.shadcn.com/docs/theming#css-variables)
 
-One command, from inside your project:
+In your
+[`globals.css`](https://ui.shadcn.com/docs/installation/manual#configure-styles):
 
-```sh
-$ npx material-theme-builder shadcn-apply "#6750A4"
-```
-
-Or from nothing at all — `shadcn-init` scaffolds a stock shadcn app
-(`shadcn init --preset b0 --template vite`), themes it and starts it:
-
-```sh
-$ npx material-theme-builder shadcn-init "#6750A4"
-```
+```css
+@import "tailwindcss";
+@import "tw-animate-css";
+@import "shadcn/tailwind.css";
 
-The verbs are shadcn's own — there, `init` is the new project and `apply` the
-existing one — and they are prefixed because shadcn is one integration here
-among Figma, CSS, Tailwind and Flutter: a bare `init` would read as "initialize
-material-theme-builder", and would leave no room for a `tailwind-init` later.
-
-Anything after a `--` is forwarded verbatim to the shadcn command underneath —
-`shadcn init` for `shadcn-init`, `shadcn add` for `shadcn-apply` — so
-`shadcn-init "#6750A4" -- --template next -n my-app` scaffolds Next instead.
-Options of ours go before the separator; one written after it is refused, rather
-than forwarded into an error from shadcn about a flag it has never heard of.
-`--print` writes the equivalent shell chain and runs nothing.
-
-`--shadcn-cli <spec>` pins which shadcn runs — `--shadcn-cli shadcn@4.18.0`, a
-tag, a fork, anything `npx` resolves — defaulting to `shadcn@latest`. (Not
-`--shadcn`: the root command has used that name since 3.2.0 for something else
-entirely, a boolean that appends the alias block to `--format tailwind`.) It
-reaches for neighbouring versions rather than back in time, though: the defaults
-these commands pass are shadcn 4.x vocabulary (`--preset b0` is a 4.x preset
-code), so pinning far enough back also means passing that era's preset after the
-`--`.
-
-Both do the same two things by hand, if you would rather: generate a registry
-item for your source color, and install it the way you install any shadcn theme.
+/* 👇🏻 ADD THIS 👇🏻 */
+@import "material-theme-builder/shadcn.css"; /* shadcn's variables remapping on M3 */
+@plugin "material-theme-builder/tailwind" { /* the M3 tw classNames (optional) */
+  custom-colors: myCustomColor1, myCustomColor2;
+}
+/* 👆🏻 ADD THIS 👆🏻 */
 
-```sh
-$ npx material-theme-builder "#6750A4" --format registry-item > mtb.json
-$ npx shadcn@latest add ./mtb.json && rm mtb.json
-```
+@custom-variant dark (&:is(.dark *));
 
-Either way, that rewrites the values inside your existing `:root` and `.dark`
-blocks, in place, pointing
-[shadcn's CSS variables](https://ui.shadcn.com/docs/theming#list-of-variables)
-at the M3 custom properties `<Mtb>` emits — so every shadcn component follows
-whichever theme is above it in the tree — and leaves that theme's own colors in
-as the `var()` fallbacks:
+@theme inline {
+  --color-background: var(--background);
+  ...
+}
 
-```css
 :root {
-  --card: var(--md-sys-color-surface-container-low, oklch(0.968 0.012 317.742));
+  --radius: 0.625rem;
+  --background: oklch(1 0 0);
+  ...
 }
 
 .dark {
-  --card: var(--md-sys-color-surface-container-low, oklch(0.227 0.01 303.714));
+  --background: oklch(0.145 0 0);
+  ...
 }
 ```
 
-So it works both ways round: live under an `<Mtb>`, and static — server-rendered,
-zero client JS — anywhere there is none.
+`shadcn.css` is the one that matters: it points
+[shadcn's variables](https://ui.shadcn.com/docs/theming#list-of-variables) at
+the M3 custom properties, so every shadcn component follows whichever `<Mtb>` is
+above it in the tree. It carries no colors of its own — mount an `<Mtb>`, or
+emit [`toCss()`](#programmatic-api) server-side, or nothing resolves.
 
-Every option lands in those fallbacks, `--scheme` and `--contrast` included, and
-`shadcn-init` and `shadcn-apply` take them all — so the item they generate is the one the
-by-hand route would have produced:
-
-```sh
-$ npx material-theme-builder shadcn-apply "#6750A4" --scheme vibrant --contrast 0.5
-```
+The `@plugin` line is optional. It is the [Tailwind](#tailwind) recipe
+unchanged, and what it adds is names to write yourself —
+`bg-surface-container-low`, `text-on-primary`, your custom colors. Drop it and
+every shadcn component still follows the theme.
 
-`--no-fallback` leaves the fallbacks out, on all three. `--custom-colors` is the
-one option the two subcommands do not take, and that is not an oversight:
-shadcn's variable set is fixed, so no component reads a custom color and a
-registry item cannot carry one.
+For the opposite trade — concrete `oklch()` values and no `var()` at all, frozen
+at build time — see [`toShadcn()`](#programmatic-api).
 
-> [!WARNING]
->
-> `shadcn add` overwrites shadcn's own `oklch()` values rather than keeping them
-> anywhere, so they are not a safety net. Where nothing declares the M3
-> properties _and_ there are no fallbacks, every variable resolves to nothing and
-> components render transparent — `git diff` your CSS, or re-run `shadcn init`,
-> to get shadcn's defaults back.
+<details>
+<summary>The three names both halves claim</summary>
 
 > [!NOTE]
 >
-> shadcn's CLI also appends a self-referential `--card: var(--card);` per
-> variable to your `@theme inline` block. It is noise, not a bug on your side:
-> those land _above_ your `:root`, so the real values win. Delete them if they
-> bother you.
+> Written down for the record. It moves one utility by one role, and you almost
+> certainly do not need to care.
 
-For the opposite trade — concrete `oklch()` values and no `var()` at all, frozen
-at build time — see [`toShadcn()`](#programmatic-api).
+Material and shadcn picked the same name for three things — `background`,
+`primary`, `secondary`. The plugin's colors are theme defaults, so on those
+three shadcn's `@theme inline` wins, and the utility goes through the mapping
+above:
 
-<details>
-<summary>Install the mapping alone, without generating anything</summary>
+```
+bg-secondary → --color-secondary → var(--secondary) → var(--md-sys-color-secondary-container)
+```
 
-The package publishes one too, so `shadcn add` has something to fetch without a
-build step of yours:
+Without shadcn it is one hop shorter, and lands on the role of the same name:
 
-```sh
-$ npx shadcn@latest add https://unpkg.com/material-theme-builder/registry-item.json
+```
+bg-secondary → --color-secondary → var(--md-sys-color-secondary)
 ```
 
-It is the mapping and nothing else — 31 `var()` references, no colors. Which is
-why it can be published at all: it is the same file whatever your source color,
-scheme or contrast, because those arrive at runtime from `<Mtb>`. And that is
-also its one requirement — mount an `<Mtb>`, or emit
-[`toCss()`](#programmatic-api) server-side, or nothing resolves. Generate your
-own, as above, to have colors to fall back on.
+Same destination either way, M3 — just not the same role. And only for
+`secondary`: `primary` maps to `primary`, and M3 `background` and `surface` are
+the same color.
 
-</details>
+If you ever want the M3 role itself, `<Mtb>` still emits it:
 
-<details>
-<summary>Rather import a stylesheet than let the CLI edit your file</summary>
+```html
+<div class="bg-[var(--md-sys-color-secondary)]"></div>
+```
 
-A stylesheet is shipped too, for setups that would rather keep the mapping in
-one line they can delete:
+or give it a name of its own:
 
 ```css
-@import "tailwindcss";
-@import "./shadcn.css"; /* shadcn's own `:root` and `.dark` */
-@import "material-theme-builder/shadcn.css"; /* ...then ours */
+@theme inline {
+  --color-m3-secondary: var(--md-sys-color-secondary);
+}
 ```
 
-> [!IMPORTANT]
->
-> It has to come AFTER shadcn's own `:root { ... }` and `.dark { ... }`, which
-> it overrides — so **not** at the top with your other imports, which is where
-> an `@import` normally goes and where this one silently loses:
->
-> ```css
-> /* ✗ `--card` falls back to shadcn's grey; nothing warns you */
-> @import "tailwindcss";
-> @import "material-theme-builder/shadcn.css";
-> @import "./shadcn.css";
-> ```
->
-> The registry item above exists to make this impossible to get wrong.
-
 </details>
 
 <details>
 <summary>The variables it remaps</summary>
 
 Both halves are generated from [`toShadcnAliases()`](#programmatic-api) and
-[`toShadcnRegistryItem()`](#programmatic-api), off one mapping, so neither can
-drift from the other:
+[`toShadcnRegistryItem()`](#programmatic-api), off one mapping, so they cannot
+drift. The selectors are doubled so the block outranks shadcn's own `:root` and
+`.dark` on
+[specificity](https://developer.mozilla.org/en-US/docs/Web/CSS/CSS_cascade/Specificity#increasing_specificity_by_duplicating_selector)
+rather than on order — which is what lets the `@import` sit with your others.
 
 ```css
-:root,
-.dark {
+:root:root,
+.dark.dark {
   --background: var(--md-sys-color-surface);
   --foreground: var(--md-sys-color-on-surface);
   --card: var(--md-sys-color-surface-container-low);
@@ -412,12 +352,106 @@ drift from the other:
 
 </details>
 
+### `shadcn-apply`
+
+The alternative, for colors to fall back on and no import to place. One command,
+from inside your project:
+
+```sh
+$ npx material-theme-builder shadcn-apply "#6750A4"
+```
+
+From nothing at all, scaffold with shadcn's own CLI first — what this repo
+dogfoods:
+
+```sh
+$ npx shadcn@latest init --preset b0 --name material-theme-app
+$ cd material-theme-app && npx material-theme-builder shadcn-apply "#6750A4"
+```
+
+It generates a registry item for your source color and hands it to `shadcn add`,
+which rewrites the values inside your existing `:root` and `.dark` blocks, in
+place. Same mapping as the stylesheet, with that theme's own colors left in as
+the `var()` fallbacks:
+
+```css
+:root {
+  --card: var(--md-sys-color-surface-container-low, oklch(0.968 0.012 317.742));
+}
+
+.dark {
+  --card: var(--md-sys-color-surface-container-low, oklch(0.227 0.01 303.714));
+}
+```
+
+So it works with no `<Mtb>` at all — the fallbacks render the theme statically,
+server-rendered, zero client JS. Your old values are overwritten, not kept
+anywhere: `git diff` is the undo.
+
+Both steps by hand, if you would rather:
+
+```sh
+$ npx material-theme-builder "#6750A4" --format registry-item > mtb.json
+$ npx shadcn@latest add ./mtb.json && rm mtb.json
+```
+
+`shadcn-apply` takes every theme option `material-theme-builder` itself takes,
+and they all land in those fallbacks:
+
+```sh
+$ npx material-theme-builder shadcn-apply "#6750A4" --scheme vibrant --contrast 0.5
+```
+
+<details>
+<summary>The rest of the options</summary>
+
+`--no-fallback` leaves the fallbacks out, on both — so shadcn's own colors are
+dropped rather than kept in reserve. Nothing then declares those variables
+except an `<Mtb>` or a [`toCss()`](#programmatic-api): without one, they resolve
+to nothing and the components render transparent.
+
+`--custom-colors` is the one option missing: shadcn's variable set is fixed, so
+a registry item cannot carry one.
+
+Anything after a `--` is forwarded verbatim to `shadcn add`. Our options go
+before it:
+
+```sh
+$ npx material-theme-builder shadcn-apply "#6750A4" -- --overwrite --dry-run
+```
+
+> [!NOTE]
+>
+> shadcn's CLI also appends a self-referential `--card: var(--card);` per
+> variable to your `@theme inline` block. Noise, not a bug: they land _above_
+> your `:root`, so the real values win. Delete them if they bother you.
+
+</details>
+
+<details>
+<summary>Install the mapping alone, without generating anything</summary>
+
+The package publishes a registry item too, so `shadcn add` has something to
+fetch without a build step:
+
+```sh
+$ npx shadcn@latest add https://unpkg.com/material-theme-builder/registry-item.json
+```
+
+It is the stylesheet's content, installed the registry way: the mapping and
+nothing else, no colors to fall back on. Generate your own, as above, to have
+some.
+
+</details>
+
 <details>
-  <summary>mapping details</summary>
-  see:
-  
-    - https://chatgpt.com/share/6899f20a-422c-8011-a072-62fb649589a0
-    - https://gemini.google.com/share/51e072b6f1d2
+<summary>mapping details</summary>
+
+see:
+
+- https://chatgpt.com/share/6899f20a-422c-8011-a072-62fb649589a0
+- https://gemini.google.com/share/51e072b6f1d2
+
 </details>
 
 # Dev
@@ -460,18 +494,17 @@ $ pnpm run lgtm
 ## CONTRIBUTING
 
 ```bash
-pnpm run storybook # the day-to-day loop -- no build needed, the stylesheets regenerate as you edit
-pnpm run build     # dist/, plus the generated stylesheets -- both gitignored
+pnpm run storybook # the day-to-day loop -- no build needed, `shadcn.css` regenerates as you edit
+pnpm run build     # dist/, plus the generated files -- all gitignored
 pnpm run lgtm      # everything CI checks
 ```
 
-`tailwind.css`, `shadcn.css` and `registry-item.json` are generated — from
-`toTailwind()`, `toShadcnAliases()` and `toShadcnRegistryItem()` — and
-gitignored. `pnpm run build` writes them (`scripts/generate.mjs`); the two
-stylesheets also get a `src/` copy, which is what Storybook `@import`s, and in
-Storybook a Vite plugin (`.storybook/main.ts`) rewrites those at server start
-and again on every edit under `src/lib/`, so the stories never show a stale
-vocabulary.
+`shadcn.css` and `registry-item.json` are generated — from `toShadcnAliases()`
+and `toShadcnRegistryItem()` — and gitignored. `pnpm run build` writes them
+(`scripts/generate.mjs`); `shadcn.css` also gets a `src/` copy, which is what
+Storybook `@import`s, and in Storybook a Vite plugin (`.storybook/main.ts`)
+rewrites it at server start and again on every edit under `src/lib/`, so the
+stories never show a stale vocabulary.
 
 `generate.mjs` builds the registry item without `{ fallback: true }`, which is
 what keeps every one of those outputs a function of the _mapping_ rather than of