material-theme-builder 3.3.0 → 4.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,9 +153,8 @@ 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) — a
+stylesheet for the standard tokens, and a plugin for the custom colors:
 
 ```css
 @import "tailwindcss";
@@ -142,12 +165,15 @@ colors, the one part a shipped file cannot know:
 }
 ```
 
-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 `@plugin` line if you have no custom colors.
+
+<details>
+
+Each name listed brings its four scheme roles and eleven shades —
+`bg-myCustomColor1`, `text-on-myCustomColor1`, `bg-myCustomColor1-container`,
+`bg-myCustomColor1-300`.
 
-The plugin takes a `prefix` too, mirroring `builder({ prefix })`:
+`prefix` mirrors `builder({ prefix })`:
 
 ```css
 @plugin "material-theme-builder/tailwind" {
@@ -156,42 +182,15 @@ 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>
@@ -225,157 +224,110 @@ Pre-requisites:
 - You should use
   [`tailwind.cssVariables`](https://ui.shadcn.com/docs/theming#css-variables)
 
-One command, from inside your project:
-
-```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:
+In your
+[`globals.css`](https://ui.shadcn.com/docs/installation/manual#configure-styles):
 
-```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/tailwind.css"; /* the M3 tw classNames (optional) */
+@import "material-theme-builder/shadcn.css"; /* shadcn's variables remapping on M3 */
+@plugin "material-theme-builder/tailwind" { /* your custom colors (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:
+The other two are optional. They are the [Tailwind](#tailwind) recipe unchanged,
+and what they add is names to write yourself — `bg-surface-container-low`,
+`text-on-primary`, your custom colors. Drop them and every shadcn component
+still follows the theme.
 
-```sh
-$ npx material-theme-builder shadcn-apply "#6750A4" --scheme vibrant --contrast 0.5
-```
-
-`--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`. shadcn's `@theme inline` is the later of the two, so on
+those three it 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 +364,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

package/dist/cli.js

@@ -3,12 +3,11 @@
 // src/cli.ts
 import * as fs2 from "fs";
 import * as path2 from "path";
-import { Command as Command2 } from "commander";
+import { Command, Option as Option2 } from "commander";
 import { z } from "zod";
 
 // src/cli.options.ts
 import {
-  Command,
   InvalidArgumentError,
   Option
 } from "commander";
@@ -683,8 +682,8 @@ function buildShadcnAliases(ctx) {
   const lines = Object.entries(toShadcnAliasVars(ctx.prefix)).map(
     ([name, value]) => `--${name}: ${value};`
   );
-  return `:root,
-.dark {
+  return `:root:root,
+.dark.dark {
   ${lines.join("\n  ")}
 }
 `;
@@ -870,6 +869,9 @@ function assertHexInputs(source, cores, customColors) {
     (color, i) => assertHexColor(`customColors[${i}].hex`, color.hex)
   );
 }
+function optionalHex(hex) {
+  return hex?.trim() || void 0;
+}
 var STANDARD_TONES = [
   0,
   4,
@@ -1038,16 +1040,20 @@ function builder(hexSource, {
   customColors: hexCustomColors = DEFAULT_CUSTOM_COLORS,
   prefix = DEFAULT_PREFIX
 } = {}) {
-  assertHexInputs(
-    hexSource,
-    { primary, secondary, tertiary, error, neutral, neutralVariant },
-    hexCustomColors
-  );
+  const cores = {
+    primary: optionalHex(primary),
+    secondary: optionalHex(secondary),
+    tertiary: optionalHex(tertiary),
+    error: optionalHex(error),
+    neutral: optionalHex(neutral),
+    neutralVariant: optionalHex(neutralVariant)
+  };
+  assertHexInputs(hexSource, cores, hexCustomColors);
   const sourceArgb = argbFromHex2(hexSource);
   const sourceHct = Hct2.fromInt(sourceArgb);
-  const effectiveSource = primary || hexSource;
+  const effectiveSource = cores.primary || hexSource;
   const effectiveSourceArgb = argbFromHex2(effectiveSource);
-  const effectiveSourceForHarmonization = primary ? argbFromHex2(primary) : sourceArgb;
+  const effectiveSourceForHarmonization = cores.primary ? argbFromHex2(cores.primary) : sourceArgb;
   const SchemeClass = schemesMap[scheme];
   const primaryHct = Hct2.fromInt(effectiveSourceArgb);
   const baseScheme = new SchemeClass(primaryHct, false, contrast);
@@ -1055,32 +1061,32 @@ function builder(hexSource, {
     // Core colors (hex may be undefined)
     {
       name: "primary",
-      hex: primary,
+      hex: cores.primary,
       core: true,
       chromaSource: "primary"
     },
     {
       name: "secondary",
-      hex: secondary,
+      hex: cores.secondary,
       core: true,
       chromaSource: "primary"
     },
     {
       name: "tertiary",
-      hex: tertiary,
+      hex: cores.tertiary,
       core: true,
       chromaSource: "primary"
     },
-    { name: "error", hex: error, core: true, chromaSource: "primary" },
+    { name: "error", hex: cores.error, core: true, chromaSource: "primary" },
     {
       name: "neutral",
-      hex: neutral,
+      hex: cores.neutral,
       core: true,
       chromaSource: "neutral"
     },
     {
       name: "neutralVariant",
-      hex: neutralVariant,
+      hex: cores.neutralVariant,
       core: true,
       chromaSource: "neutralVariant"
     },
@@ -1231,7 +1237,6 @@ function addThemeOptions(command) {
     DEFAULT_PREFIX
   );
 }
-var THEME_OPTIONS = addThemeOptions(new Command()).options;
 function builderOptions(opts) {
   return {
     scheme: opts.scheme,
@@ -1245,16 +1250,6 @@ function builderOptions(opts) {
     prefix: opts.prefix
   };
 }
-function specifiedThemeArgs(command) {
-  const args = [];
-  for (const option of THEME_OPTIONS) {
-    const name = option.attributeName();
-    if (command.getOptionValueSource(name) !== "cli") continue;
-    if (option.long) args.push(option.long);
-    if (!option.negate) args.push(String(command.opts()[name]));
-  }
-  return args;
-}
 function themeFrom(command) {
   const opts = command.opts();
   return {
@@ -1263,256 +1258,48 @@ function themeFrom(command) {
     // opposite of the API's, and deliberately so: a CLI knows the source color,
     // which is what makes baking its colors in as the fallbacks free. See
     // `buildShadcnRegistryItem()`.
-    fallback: opts.fallback ?? true,
-    args: specifiedThemeArgs(command)
+    fallback: opts.fallback ?? true
   };
 }
 
 // src/cli.shadcn.ts
 import { spawnSync } from "child_process";
 import * as fs from "fs";
-import * as os from "os";
 import * as path from "path";
-import { InvalidArgumentError as InvalidArgumentError2 } from "commander";
+import "commander";
 var NPX = ["npx", "--yes"];
 var DEFAULT_SHADCN = "shadcn@latest";
-var SELF = "material-theme-builder";
-var INIT_TARGET = "shadcn init";
-var ADD_TARGET = "shadcn add";
+var YES = "--yes";
 var ITEM = "mtb.json";
-var APP_NAME = "material-theme-app";
-var NAME = { long: "--name", short: "-n", value: APP_NAME };
-var YES = { long: "--yes", short: "-y" };
-var INIT_DEFAULTS = [
-  { long: "--preset", short: "-p", value: "b0" },
-  { long: "--template", short: "-t", value: "vite" },
-  NAME,
-  YES
-];
-var ADD_DEFAULTS = [YES];
-function parseShadcnSpec(value) {
-  if (value.startsWith("-"))
-    throw new InvalidArgumentError2(
-      "A package spec cannot start with '-': npx would read it as one of its own options."
-    );
-  if (/^\d/.test(value))
-    throw new InvalidArgumentError2(
-      `That is a version, not a package spec -- write 'shadcn@${value}'.`
-    );
-  return value;
-}
-function addChainOptions(command) {
-  return command.option(
-    "--shadcn-cli <spec>",
-    "npx package spec for the shadcn CLI to run (a version, tag, fork or tarball \u2014 anything npx resolves)",
-    parseShadcnSpec,
-    DEFAULT_SHADCN
-  ).option(
-    "--print",
-    "Print the equivalent shell chain instead of running it"
-  );
-}
-function mentions(args, { long, short }) {
-  return args.some(
-    (arg) => arg === long || arg.startsWith(`${long}=`) || arg.startsWith(short)
-  );
-}
-function mergeDefaults(defaults, forwarded) {
-  const injected = defaults.filter((option) => !mentions(forwarded, option)).flatMap(
-    ({ long, value }) => value === void 0 ? [long] : [long, value]
-  );
-  return [...injected, ...forwarded];
-}
-function lastName(args) {
-  for (let i = args.length - 1; i >= 0; i--) {
-    const arg = args[i] ?? "";
-    if (arg === NAME.long || arg === NAME.short) return args[i + 1];
-    if (arg.startsWith(`${NAME.long}=`)) return arg.slice(NAME.long.length + 1);
-    if (arg.length > NAME.short.length && arg.startsWith(NAME.short))
-      return arg.slice(NAME.short.length);
-  }
-  return void 0;
-}
-function ownOptionIn(declared, forwarded) {
-  return forwarded.find(
-    (arg) => declared.some(
-      (option) => arg === option.long || arg === option.short || option.long !== void 0 && arg.startsWith(`${option.long}=`)
-    )
-  );
-}
-function refuseOwnOptions(command, forwarded, target) {
-  const misplaced = ownOptionIn(command.options, forwarded);
-  if (misplaced !== void 0)
-    fail(
-      `${misplaced} is ours, not shadcn's, so it belongs before the \`--\`. Everything after the separator is handed to \`${target}\` untouched.`
-    );
-}
-var DEFAULT_THEME = { options: {}, fallback: true, args: [] };
-function chainOptionsFrom(command) {
-  return { theme: themeFrom(command), shadcn: command.opts().shadcnCli };
-}
-function initPlan(source, forwarded = [], {
-  theme = DEFAULT_THEME,
-  shadcn = DEFAULT_SHADCN
-} = {}) {
-  const args = mergeDefaults(INIT_DEFAULTS, forwarded);
-  const dir = lastName(args) ?? APP_NAME;
-  return {
-    source,
-    theme,
-    dir,
-    steps: [
-      {
-        kind: "spawn",
-        label: INIT_TARGET,
-        argv: [...NPX, shadcn, "init", ...args],
-        where: "cwd"
-      },
-      { kind: "cd", dir },
-      { kind: "item", file: ITEM },
-      // The same spec as the step above, deliberately: a chain pinned for the
-      // scaffold and floating for the install is worse than one that floats
-      // throughout, since the two would disagree about the registry format
-      // without saying so.
-      {
-        kind: "spawn",
-        label: ADD_TARGET,
-        argv: [
-          ...NPX,
-          shadcn,
-          "add",
-          `./${ITEM}`,
-          ...mergeDefaults(ADD_DEFAULTS, [])
-        ],
-        where: "project"
-      },
-      { kind: "rm", file: ITEM },
-      // The handover: long-running by design, stdio inherited, ctrl-C reaching
-      // it. Package-manager detection is out of scope -- `shadcn init` under
-      // `npx` writes a `package-lock.json` and the `dev` script npm will run.
-      {
-        kind: "spawn",
-        label: "npm run dev",
-        argv: ["npm", "run", "dev"],
-        where: "project"
-      }
-    ]
-  };
-}
-function applyPlan(source, forwarded = [], {
-  theme = DEFAULT_THEME,
-  shadcn = DEFAULT_SHADCN
-} = {}) {
-  return {
-    source,
-    theme,
-    steps: [
-      { kind: "item", file: ITEM },
-      {
-        kind: "spawn",
-        label: ADD_TARGET,
-        argv: [
-          ...NPX,
-          shadcn,
-          "add",
-          `./${ITEM}`,
-          ...mergeDefaults(ADD_DEFAULTS, forwarded)
-        ],
-        where: "cwd"
-      },
-      { kind: "rm", file: ITEM }
-    ]
-  };
-}
-var SHELL_SAFE = /^[\w@%+=:,./-]+$/;
-function quote(argv) {
-  return argv.map(
-    (arg) => SHELL_SAFE.test(arg) ? arg : `'${arg.replaceAll("'", `'\\''`)}'`
-  ).join(" ");
-}
-function renderStep(plan, step) {
-  switch (step.kind) {
-    case "spawn":
-      return quote(step.argv);
-    case "cd":
-      return `cd ${step.dir}`;
-    // Rendered as the command someone could have run themselves -- theme options
-    // included, or the line would describe a different theme from the one the
-    // runner generates. The runner does the same thing in-process, being the very
-    // binary this spawns.
-    case "item":
-      return `${quote([...NPX, SELF, plan.source, ...plan.theme.args, "--format", "registry-item"])} > ${step.file}`;
-    case "rm":
-      return `rm ${step.file}`;
-  }
-}
-function renderChain(plan) {
-  return plan.steps.map((step) => renderStep(plan, step)).join(" && ");
+function addArgv(shadcn, forwarded = []) {
+  return [...NPX, shadcn, "add", `./${ITEM}`, YES, ...forwarded];
 }
 function fail(message, code = 1) {
   console.error(`Error: ${message}`);
   process.exit(code);
 }
-function run({ label, argv }, cwd) {
-  const [command = "", ...args] = argv;
-  const { error, status, signal } = spawnSync(command, args, {
-    cwd,
-    stdio: "inherit",
-    shell: false
-  });
-  if (error) fail(`${label} could not be started: ${error.message}`);
-  if (signal) process.exit(128 + (os.constants.signals[signal] ?? 0));
-  if (status !== 0) fail(`${label} failed`, status ?? 1);
-}
-function writeItem({ source, theme }, file) {
+function writeItem(source, command, file) {
   if (fs.existsSync(file))
     fail(
       `${path.basename(file)} already exists and would be overwritten, then deleted. Move it aside first.`
     );
   process.on("exit", () => fs.rmSync(file, { force: true }));
-  const item = builder(source, theme.options).toShadcnRegistryItem({
-    fallback: theme.fallback
-  });
+  const { options, fallback } = themeFrom(command);
+  const item = builder(source, options).toShadcnRegistryItem({ fallback });
   fs.writeFileSync(file, `${JSON.stringify(item, null, 2)}
 `);
 }
-function runStep(plan, step, projectDir) {
-  switch (step.kind) {
-    case "spawn":
-      return run(step, step.where === "project" ? projectDir : process.cwd());
-    case "item":
-      return writeItem(plan, path.join(projectDir, step.file));
-    case "rm":
-      return fs.rmSync(path.join(projectDir, step.file), { force: true });
-    // Nothing to do: the runner resolved the directory up front, where a shell
-    // would have changed into it. The step exists so that `--print` can say so.
-    case "cd":
-      return;
-  }
-}
-function runChain(plan) {
-  const projectDir = plan.dir ? path.resolve(plan.dir) : process.cwd();
-  if (plan.dir && fs.existsSync(projectDir))
-    fail(
-      `./${plan.dir} already exists. Pick another name with \`-- -n other-name\`, or remove it first.`
-    );
-  for (const step of plan.steps) runStep(plan, step, projectDir);
-}
-function execute(plan, command) {
-  if (command.opts().print === true) {
-    process.stdout.write(`${renderChain(plan)}
-`);
-    return;
-  }
-  runChain(plan);
-}
-function runInit(source, forwarded, command) {
-  refuseOwnOptions(command, forwarded, INIT_TARGET);
-  execute(initPlan(source, forwarded, chainOptionsFrom(command)), command);
-}
 function runApply(source, forwarded, command) {
-  refuseOwnOptions(command, forwarded, ADD_TARGET);
-  execute(applyPlan(source, forwarded, chainOptionsFrom(command)), command);
+  const file = path.resolve(ITEM);
+  writeItem(source, command, file);
+  const [bin = "", ...args] = addArgv(command.opts().shadcnCli, forwarded);
+  const { error, status } = spawnSync(bin, args, {
+    stdio: "inherit",
+    shell: false
+  });
+  if (error) fail(`shadcn add could not be started: ${error.message}`);
+  if (status !== 0) fail("shadcn add failed", status ?? 1);
+  fs.rmSync(file, { force: true });
 }
 
 // src/cli.ts
@@ -1534,9 +1321,20 @@ function writeFigmaTokens(theme, outputDir) {
     console.error(`wrote ${filePath}`);
   }
 }
+var FORMATS = [
+  "json",
+  "css",
+  "figma",
+  "tailwind",
+  "shadcn",
+  "registry-item",
+  "flutter"
+];
 function writeOutput(theme, opts) {
   const json = (value) => JSON.stringify(value, null, 2) + "\n";
   switch (opts.format) {
+    case "json":
+      return process.stdout.write(json(theme.toJson()));
     case "css":
       return process.stdout.write(theme.toCss());
     case "tailwind":
@@ -1551,11 +1349,9 @@ function writeOutput(theme, opts) {
       return process.stdout.write(theme.toFlutter());
     case "figma":
       return writeFigmaTokens(theme, opts.output ?? "material-theme");
-    default:
-      return process.stdout.write(json(theme.toJson()));
   }
 }
-var program = new Command2();
+var program = new Command();
 addThemeOptions(
   addSourceArgument(
     program.name("material-theme-builder").description("Generate a color theme from a source color")
@@ -1563,10 +1359,8 @@ addThemeOptions(
 ).option(
   "--custom-colors <json>",
   `Custom colors as JSON array (e.g. '[{"name":"brand","hex":"#FF5733","blend":true}]')`
-).option(
-  "--format <type>",
-  "Output format: json, css, figma, tailwind, shadcn, registry-item, or flutter",
-  "figma"
+).addOption(
+  new Option2("--format <type>", "Output format").choices(FORMATS).default("figma")
 ).option("--output <dir>", "Output directory (required for figma format)").option(
   "--shadcn",
   "Append the shadcn var() alias block to --format tailwind (for concrete values, use --format shadcn)"
@@ -1609,29 +1403,17 @@ addThemeOptions(
   });
   writeOutput(result, opts);
 });
-addChainOptions(
-  addThemeOptions(
-    addSourceArgument(
-      program.command("shadcn-init").description(
-        "Scaffold a new shadcn app themed from a source color, and start it"
-      )
-    ).argument(
-      "[shadcn-args...]",
-      "Options after a `--`, forwarded verbatim to `shadcn init`"
-    )
-  )
-).action(
-  (source, shadcnArgs, _opts, command) => runInit(source, shadcnArgs, command)
-);
-addChainOptions(
-  addThemeOptions(
-    addSourceArgument(
-      program.command("shadcn-apply").description("Theme the shadcn project in the current directory")
-    ).argument(
-      "[shadcn-args...]",
-      "Options after a `--`, forwarded verbatim to `shadcn add`"
-    )
+addThemeOptions(
+  addSourceArgument(
+    program.command("shadcn-apply").description("Theme the shadcn project in the current directory")
+  ).argument(
+    "[shadcn-args...]",
+    "Options after a `--`, forwarded verbatim to `shadcn add`"
   )
+).option(
+  "--shadcn-cli <spec>",
+  "npx package spec for the shadcn CLI to run (a version, tag, fork or tarball \u2014 anything npx resolves)",
+  DEFAULT_SHADCN
 ).action(
   (source, shadcnArgs, _opts, command) => runApply(source, shadcnArgs, command)
 );

package/dist/index.js

@@ -668,8 +668,8 @@ function buildShadcnAliases(ctx) {
   const lines = Object.entries(toShadcnAliasVars(ctx.prefix)).map(
     ([name, value]) => `--${name}: ${value};`
   );
-  return `:root,
-.dark {
+  return `:root:root,
+.dark.dark {
   ${lines.join("\n  ")}
 }
 `;
@@ -846,6 +846,9 @@ function assertHexInputs(source, cores, customColors) {
     (color, i) => assertHexColor(`customColors[${i}].hex`, color.hex)
   );
 }
+function optionalHex(hex) {
+  return hex?.trim() || void 0;
+}
 var STANDARD_TONES = [
   0,
   4,
@@ -1014,16 +1017,20 @@ function builder(hexSource, {
   customColors: hexCustomColors = DEFAULT_CUSTOM_COLORS,
   prefix = DEFAULT_PREFIX
 } = {}) {
-  assertHexInputs(
-    hexSource,
-    { primary, secondary, tertiary, error, neutral, neutralVariant },
-    hexCustomColors
-  );
+  const cores = {
+    primary: optionalHex(primary),
+    secondary: optionalHex(secondary),
+    tertiary: optionalHex(tertiary),
+    error: optionalHex(error),
+    neutral: optionalHex(neutral),
+    neutralVariant: optionalHex(neutralVariant)
+  };
+  assertHexInputs(hexSource, cores, hexCustomColors);
   const sourceArgb = argbFromHex2(hexSource);
   const sourceHct = Hct2.fromInt(sourceArgb);
-  const effectiveSource = primary || hexSource;
+  const effectiveSource = cores.primary || hexSource;
   const effectiveSourceArgb = argbFromHex2(effectiveSource);
-  const effectiveSourceForHarmonization = primary ? argbFromHex2(primary) : sourceArgb;
+  const effectiveSourceForHarmonization = cores.primary ? argbFromHex2(cores.primary) : sourceArgb;
   const SchemeClass = schemesMap[scheme];
   const primaryHct = Hct2.fromInt(effectiveSourceArgb);
   const baseScheme = new SchemeClass(primaryHct, false, contrast);
@@ -1031,32 +1038,32 @@ function builder(hexSource, {
     // Core colors (hex may be undefined)
     {
       name: "primary",
-      hex: primary,
+      hex: cores.primary,
       core: true,
       chromaSource: "primary"
     },
     {
       name: "secondary",
-      hex: secondary,
+      hex: cores.secondary,
       core: true,
       chromaSource: "primary"
     },
     {
       name: "tertiary",
-      hex: tertiary,
+      hex: cores.tertiary,
       core: true,
       chromaSource: "primary"
     },
-    { name: "error", hex: error, core: true, chromaSource: "primary" },
+    { name: "error", hex: cores.error, core: true, chromaSource: "primary" },
     {
       name: "neutral",
-      hex: neutral,
+      hex: cores.neutral,
       core: true,
       chromaSource: "neutral"
     },
     {
       name: "neutralVariant",
-      hex: neutralVariant,
+      hex: cores.neutralVariant,
       core: true,
       chromaSource: "neutralVariant"
     },

package/dist/react.js

@@ -3988,8 +3988,8 @@ function buildShadcnAliases(ctx) {
   const lines = Object.entries(toShadcnAliasVars(ctx.prefix)).map(
     ([name, value]) => `--${name}: ${value};`
   );
-  return `:root,
-.dark {
+  return `:root:root,
+.dark.dark {
   ${lines.join("\n  ")}
 }
 `;
@@ -4166,6 +4166,9 @@ function assertHexInputs(source, cores, customColors) {
     (color, i) => assertHexColor(`customColors[${i}].hex`, color.hex)
   );
 }
+function optionalHex(hex) {
+  return hex?.trim() || void 0;
+}
 var STANDARD_TONES = [
   0,
   4,
@@ -4334,16 +4337,20 @@ function builder(hexSource, {
   customColors: hexCustomColors = DEFAULT_CUSTOM_COLORS,
   prefix = DEFAULT_PREFIX
 } = {}) {
-  assertHexInputs(
-    hexSource,
-    { primary, secondary, tertiary, error, neutral, neutralVariant },
-    hexCustomColors
-  );
+  const cores = {
+    primary: optionalHex(primary),
+    secondary: optionalHex(secondary),
+    tertiary: optionalHex(tertiary),
+    error: optionalHex(error),
+    neutral: optionalHex(neutral),
+    neutralVariant: optionalHex(neutralVariant)
+  };
+  assertHexInputs(hexSource, cores, hexCustomColors);
   const sourceArgb = argbFromHex2(hexSource);
   const sourceHct = Hct2.fromInt(sourceArgb);
-  const effectiveSource = primary || hexSource;
+  const effectiveSource = cores.primary || hexSource;
   const effectiveSourceArgb = argbFromHex2(effectiveSource);
-  const effectiveSourceForHarmonization = primary ? argbFromHex2(primary) : sourceArgb;
+  const effectiveSourceForHarmonization = cores.primary ? argbFromHex2(cores.primary) : sourceArgb;
   const SchemeClass = schemesMap[scheme];
   const primaryHct = Hct2.fromInt(effectiveSourceArgb);
   const baseScheme = new SchemeClass(primaryHct, false, contrast);
@@ -4351,32 +4358,32 @@ function builder(hexSource, {
     // Core colors (hex may be undefined)
     {
       name: "primary",
-      hex: primary,
+      hex: cores.primary,
       core: true,
       chromaSource: "primary"
     },
     {
       name: "secondary",
-      hex: secondary,
+      hex: cores.secondary,
       core: true,
       chromaSource: "primary"
     },
     {
       name: "tertiary",
-      hex: tertiary,
+      hex: cores.tertiary,
       core: true,
       chromaSource: "primary"
     },
-    { name: "error", hex: error, core: true, chromaSource: "primary" },
+    { name: "error", hex: cores.error, core: true, chromaSource: "primary" },
     {
       name: "neutral",
-      hex: neutral,
+      hex: cores.neutral,
       core: true,
       chromaSource: "neutral"
     },
     {
       name: "neutralVariant",
-      hex: neutralVariant,
+      hex: cores.neutralVariant,
       core: true,
       chromaSource: "neutralVariant"
     },
@@ -4492,7 +4499,7 @@ function builder(hexSource, {
 }
 
 // src/ExportButton.tsx
-import { jsx as jsx2, jsxs } from "react/jsx-runtime";
+import { jsx as jsx2 } from "react/jsx-runtime";
 function ExportButton({ config }) {
   const handleExport = () => {
     try {
@@ -4526,24 +4533,16 @@ function ExportButton({ config }) {
       onClick: handleExport,
       title: "Export Figma Tokens",
       "aria-label": "Export Figma Tokens",
-      className: "fixed z-50 bottom-6 right-6",
-      children: /* @__PURE__ */ jsxs(
+      children: /* @__PURE__ */ jsx2(
         "svg",
         {
           xmlns: "http://www.w3.org/2000/svg",
           width: "24",
           height: "24",
           viewBox: "0 0 24 24",
-          fill: "none",
-          stroke: "currentColor",
-          strokeWidth: "2",
-          strokeLinecap: "round",
-          strokeLinejoin: "round",
-          children: [
-            /* @__PURE__ */ jsx2("path", { d: "M21 15v4a2 2 0 0 1-2 2H5a2 2 0 0 1-2-2v-4" }),
-            /* @__PURE__ */ jsx2("polyline", { points: "7 10 12 15 17 10" }),
-            /* @__PURE__ */ jsx2("line", { x1: "12", y1: "15", x2: "12", y2: "3" })
-          ]
+          fill: "currentColor",
+          "aria-hidden": true,
+          children: /* @__PURE__ */ jsx2("path", { d: "M8 24a4 4 0 0 1-4-4 4 4 0 0 1 4-4h4v4a4 4 0 0 1-4 4Zm0-6.5A2.5 2.5 0 0 0 5.5 20 2.5 2.5 0 0 0 8 22.5 2.5 2.5 0 0 0 10.5 20v-2.5H8ZM8 16a4 4 0 0 1-4-4 4 4 0 0 1 4-4h4v8H8Zm0-6.5A2.5 2.5 0 0 0 5.5 12 2.5 2.5 0 0 0 8 14.5h2.5v-5H8ZM8 8a4 4 0 0 1-4-4 4 4 0 0 1 4-4h4v8H8Zm0-6.5A2.5 2.5 0 0 0 5.5 4 2.5 2.5 0 0 0 8 6.5h2.5v-5H8Zm8 6.5h-4V0h4a4 4 0 0 1 4 4 4 4 0 0 1-4 4Zm-2.5-1.5H16A2.5 2.5 0 0 0 18.5 4 2.5 2.5 0 0 0 16 1.5h-2.5v5ZM16 16a4 4 0 0 1-4-4 4 4 0 0 1 4-4 4 4 0 0 1 4 4 4 4 0 0 1-4 4Zm0-6.5a2.5 2.5 0 0 0-2.5 2.5 2.5 2.5 0 0 0 2.5 2.5 2.5 2.5 0 0 0 2.5-2.5A2.5 2.5 0 0 0 16 9.5Z" })
         }
       )
     }
@@ -4574,7 +4573,7 @@ var createRequiredContext = () => {
 };
 
 // src/Mtb.context.tsx
-import { jsx as jsx3, jsxs as jsxs2 } from "react/jsx-runtime";
+import { jsx as jsx3, jsxs } from "react/jsx-runtime";
 var [useMtb, Provider, MtbContext] = createRequiredContext();
 var MtbProvider = ({
   styleId: styleId2,
@@ -4640,7 +4639,7 @@ var MtbProvider = ({
       figmaVariables
     ]
   );
-  return /* @__PURE__ */ jsxs2(Provider, { value, children: [
+  return /* @__PURE__ */ jsxs(Provider, { value, children: [
     /* @__PURE__ */ jsx3("style", { id: styleId2, dangerouslySetInnerHTML: { __html: css } }),
     children
   ] });

package/dist/shadcn.css

@@ -2,13 +2,13 @@
  * Generated by `scripts/generate.mjs` -- do not edit.
  *
  * Points shadcn's variables at the M3 custom properties `<Mtb>` emits, so
- * shadcn components follow the theme above them in the tree. Import it after
- * shadcn's own `:root` and `.dark` blocks, which it has to override -- or
- * skip the ordering question entirely and install `registry-item.json` with
- * `shadcn add`, which writes the same mapping into those blocks in place.
+ * shadcn components follow the theme above them in the tree. Import it with
+ * your other imports: the selectors are doubled, so it outranks shadcn's own
+ * `:root` and `.dark` wherever it lands. Or install `registry-item.json`
+ * with `shadcn add`, which writes the same mapping into those blocks.
  */
-: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);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "material-theme-builder",
-  "version": "3.3.0",
+  "version": "4.0.0",
   "description": "m3 color-system for JS/TS ecosystem",
   "keywords": [
     "react",
@@ -56,6 +56,7 @@
     "@fontsource-variable/inter": "^5.3.0",
     "@storybook/addon-docs": "^10.1.11",
     "@storybook/addon-themes": "^10.1.11",
+    "@storybook/icons": "^2.1.0",
     "@storybook/react-vite": "^10.1.11",
     "@tailwindcss/postcss": "^4.1.18",
     "@tanstack/react-table": "^9.1.2",
@@ -141,6 +142,7 @@
     "build-storybook": "pnpm run build && storybook build",
     "build-figma": "vite build --config figma-plugin/vite.config.ts && tsup --config figma-plugin/tsup.config.ts",
     "chromatic": "chromatic --project-token $CHROMATIC_PROJECT_TOKEN",
-    "changeset": "pnpm exec changeset"
+    "changeset": "pnpm exec changeset",
+    "dev": "pnpm run storybook"
   }
 }