material-theme-builder 3.2.0 → 4.0.0

package/dist/cli.js

@@ -1,11 +1,17 @@
 #!/usr/bin/env node
 
 // src/cli.ts
-import * as fs from "fs";
-import * as path from "path";
-import { Command, Option } from "commander";
+import * as fs2 from "fs";
+import * as path2 from "path";
+import { Command, Option as Option2 } from "commander";
 import { z } from "zod";
 
+// src/cli.options.ts
+import {
+  InvalidArgumentError,
+  Option
+} from "commander";
+
 // src/lib/builder.ts
 import {
   argbFromHex as argbFromHex2,
@@ -116,9 +122,9 @@ function buildFigmaVariables(ctx) {
     paletteHexMap[paletteName] = {};
     for (const tone of STANDARD_TONES) {
       const argb = palette.tone(tone);
-      const path2 = `ref/palette/${paletteName}/${tone}`;
+      const path3 = `ref/palette/${paletteName}/${tone}`;
       const hex = hexFromArgb2(argb).toUpperCase();
-      paletteHexMap[paletteName][hex] = path2;
+      paletteHexMap[paletteName][hex] = path3;
       const color = {
         r: redFromArgb(argb) / 255,
         g: greenFromArgb(argb) / 255,
@@ -126,7 +132,7 @@ function buildFigmaVariables(ctx) {
         a: 1
       };
       variables.push({
-        path: path2,
+        path: path3,
         scopes: ["ALL_SCOPES"],
         values: { Light: color, Dark: color }
       });
@@ -210,8 +216,8 @@ function buildFigmaTokens(ctx) {
       $extensions: toDtcgExtensions(v)
     };
   }
-  function parsePath(path2) {
-    const parts = path2.split("/");
+  function parsePath(path3) {
+    const parts = path3.split("/");
     if (parts[0] === "ref" && parts[1] === "palette" && parts[2] && parts[3]) {
       return {
         kind: "palette",
@@ -661,6 +667,39 @@ function toShadcnVars(mergedColors) {
   });
   return Object.fromEntries(entries);
 }
+function toShadcnAliasVars(prefix, fallbacks) {
+  const entries = SHADCN_MAPPING.map(([cssVar, m3Token]) => {
+    const bare = cssVar.slice(2);
+    const property = `--${prefix}-sys-color-${m3Token}`;
+    return [
+      bare,
+      fallbacks ? `var(${property}, ${fallbacks[bare]})` : `var(${property})`
+    ];
+  });
+  return Object.fromEntries(entries);
+}
+function buildShadcnAliases(ctx) {
+  const lines = Object.entries(toShadcnAliasVars(ctx.prefix)).map(
+    ([name, value]) => `--${name}: ${value};`
+  );
+  return `:root:root,
+.dark.dark {
+  ${lines.join("\n  ")}
+}
+`;
+}
+function buildShadcnRegistryItem(ctx, { fallback = false } = {}) {
+  const concrete = fallback ? buildShadcn(ctx) : void 0;
+  const vars = (mode) => toShadcnAliasVars(ctx.prefix, concrete?.[mode]);
+  return {
+    $schema: "https://ui.shadcn.com/schema/registry-item.json",
+    name: "material-theme-builder",
+    type: "registry:theme",
+    title: "Material Theme Builder",
+    description: `Points shadcn's CSS variables at the M3 custom properties \`<Mtb>\` emits, so every shadcn component follows whichever theme is above it in the tree.${fallback ? " Falls back to this theme's own colors where no `<Mtb>` is mounted." : ""}`,
+    cssVars: { light: vars("light"), dark: vars("dark") }
+  };
+}
 function buildShadcn(ctx) {
   const { mergedColorsLight, mergedColorsDark } = ctx;
   return {
@@ -671,6 +710,64 @@ function buildShadcn(ctx) {
 
 // src/lib/builder.tailwind.ts
 import { kebabCase as kebabCase3 } from "lodash-es";
+
+// src/lib/tokens.ts
+var DEFAULT_PREFIX = "md";
+var tokenDescriptions = {
+  background: "Default background color for screens and large surfaces.",
+  error: "Color for error states, used on elements like error text and icons.",
+  errorContainer: "Fill color for error container elements like error banners.",
+  inverseOnSurface: "Color for text and icons on inverse surface backgrounds.",
+  inversePrimary: "Primary color used on inverse surface, e.g. buttons on snackbars.",
+  inverseSurface: "Background for elements that require reverse contrast, such as snackbars.",
+  onBackground: "Color for text and icons displayed on the background.",
+  onError: "Color for text and icons on error-colored elements.",
+  onErrorContainer: "Color for text and icons on error container elements.",
+  onPrimary: "Color for text and icons on primary-colored elements like filled buttons.",
+  onPrimaryContainer: "Color for text and icons on primary container elements like tonal buttons.",
+  onPrimaryFixed: "Color for text and icons on primary fixed elements, constant across themes.",
+  onPrimaryFixedVariant: "Lower-emphasis color for text and icons on primary fixed elements.",
+  onSecondary: "Color for text and icons on secondary-colored elements.",
+  onSecondaryContainer: "Color for text and icons on secondary container elements.",
+  onSecondaryFixed: "Color for text and icons on secondary fixed elements, constant across themes.",
+  onSecondaryFixedVariant: "Lower-emphasis color for text and icons on secondary fixed elements.",
+  onSurface: "High-emphasis color for text and icons on surface backgrounds.",
+  onSurfaceVariant: "Medium-emphasis color for text and icons on surface variant backgrounds.",
+  onTertiary: "Color for text and icons on tertiary-colored elements.",
+  onTertiaryContainer: "Color for text and icons on tertiary container elements.",
+  onTertiaryFixed: "Color for text and icons on tertiary fixed elements, constant across themes.",
+  onTertiaryFixedVariant: "Lower-emphasis color for text and icons on tertiary fixed elements.",
+  outline: "Subtle color for borders and dividers to create visual separation.",
+  outlineVariant: "Lower-emphasis border color used for decorative dividers.",
+  primary: "Main brand color, used for key components like filled buttons and active states.",
+  primaryContainer: "Fill color for large primary elements like cards and tonal buttons.",
+  primaryFixed: "Fixed primary color that stays the same in light and dark themes.",
+  primaryFixedDim: "Dimmed variant of the fixed primary color for lower emphasis.",
+  scrim: "Color overlay for modals and dialogs to obscure background content.",
+  secondary: "Accent color for less prominent elements like filter chips and selections.",
+  secondaryContainer: "Fill color for secondary container elements like tonal buttons and input fields.",
+  secondaryFixed: "Fixed secondary color that stays the same in light and dark themes.",
+  secondaryFixedDim: "Dimmed variant of the fixed secondary color for lower emphasis.",
+  shadow: "Color for elevation shadows applied to surfaces and components.",
+  surface: "Default surface color for cards, sheets, and dialogs.",
+  surfaceBright: "Brightest surface variant, used for elevated surfaces in dark themes.",
+  surfaceContainer: "Middle-emphasis container color for grouping related content.",
+  surfaceContainerHigh: "Higher-emphasis container color for elements like cards.",
+  surfaceContainerHighest: "Highest-emphasis container color for text fields and other input areas.",
+  surfaceContainerLow: "Lower-emphasis container color for subtle surface groupings.",
+  surfaceContainerLowest: "Lowest-emphasis container, typically the lightest surface in light theme.",
+  surfaceDim: "Dimmest surface variant, used for recessed areas or dark theme backgrounds.",
+  surfaceTint: "Tint color applied to surfaces for subtle primary color elevation overlay.",
+  surfaceVariant: "Alternative surface color for differentiated areas like sidebar backgrounds.",
+  tertiary: "Third accent color for complementary elements that balance primary and secondary.",
+  tertiaryContainer: "Fill color for tertiary container elements like complementary cards.",
+  tertiaryFixed: "Fixed tertiary color that stays the same in light and dark themes.",
+  tertiaryFixedDim: "Dimmed variant of the fixed tertiary color for lower emphasis."
+};
+function isTokenName(key) {
+  return key in tokenDescriptions;
+}
+var tokenNames = Object.keys(tokenDescriptions).filter(isTokenName);
 var SHADE_TO_TONE = [
   [50, 95],
   [100, 90],
@@ -692,6 +789,8 @@ var CORE_PALETTES = [
   "neutral",
   "neutral-variant"
 ];
+
+// src/lib/builder.tailwind.ts
 function buildTailwind(ctx, options) {
   const { prefix, mergedColorsLight, hexCustomColors } = ctx;
   const lines = [];
@@ -724,17 +823,8 @@ function buildTailwind(ctx, options) {
   ${lines.join("\n  ")}
 }
 `;
-  if (options?.shadcn) {
-    const shadcnLines = SHADCN_MAPPING.map(
-      ([shadcnVar, m3Token]) => `${shadcnVar}: var(--${prefix}-sys-color-${m3Token});`
-    );
-    output += `
-:root,
-.dark {
-  ${shadcnLines.join("\n  ")}
-}
-`;
-  }
+  if (options?.shadcn) output += `
+${buildShadcnAliases(ctx)}`;
   return output;
 }
 
@@ -761,7 +851,27 @@ var DEFAULT_SCHEME = "tonalSpot";
 var DEFAULT_CONTRAST = 0;
 var DEFAULT_CUSTOM_COLORS = [];
 var DEFAULT_BLEND = true;
-var DEFAULT_PREFIX = "md";
+var HEX_COLOR = /^#?(?:[0-9a-f]{3}|[0-9a-f]{6}|[0-9a-f]{8})$/i;
+function isHexColor(value) {
+  return HEX_COLOR.test(value);
+}
+function assertHexColor(label, value) {
+  if (!isHexColor(value))
+    throw new Error(
+      `Invalid ${label}: '${value}'. Expected a hex color \u2014 3, 6 or 8 hex digits, with or without '#' (e.g. #6750A4).`
+    );
+}
+function assertHexInputs(source, cores, customColors) {
+  assertHexColor("source", source);
+  for (const [name, hex] of Object.entries(cores))
+    if (hex !== void 0) assertHexColor(name, hex);
+  customColors.forEach(
+    (color, i) => assertHexColor(`customColors[${i}].hex`, color.hex)
+  );
+}
+function optionalHex(hex) {
+  return hex?.trim() || void 0;
+}
 var STANDARD_TONES = [
   0,
   4,
@@ -812,61 +922,6 @@ var schemeToVariant = {
   fidelity: Variant.FIDELITY,
   content: Variant.CONTENT
 };
-var tokenDescriptions = {
-  background: "Default background color for screens and large surfaces.",
-  error: "Color for error states, used on elements like error text and icons.",
-  errorContainer: "Fill color for error container elements like error banners.",
-  inverseOnSurface: "Color for text and icons on inverse surface backgrounds.",
-  inversePrimary: "Primary color used on inverse surface, e.g. buttons on snackbars.",
-  inverseSurface: "Background for elements that require reverse contrast, such as snackbars.",
-  onBackground: "Color for text and icons displayed on the background.",
-  onError: "Color for text and icons on error-colored elements.",
-  onErrorContainer: "Color for text and icons on error container elements.",
-  onPrimary: "Color for text and icons on primary-colored elements like filled buttons.",
-  onPrimaryContainer: "Color for text and icons on primary container elements like tonal buttons.",
-  onPrimaryFixed: "Color for text and icons on primary fixed elements, constant across themes.",
-  onPrimaryFixedVariant: "Lower-emphasis color for text and icons on primary fixed elements.",
-  onSecondary: "Color for text and icons on secondary-colored elements.",
-  onSecondaryContainer: "Color for text and icons on secondary container elements.",
-  onSecondaryFixed: "Color for text and icons on secondary fixed elements, constant across themes.",
-  onSecondaryFixedVariant: "Lower-emphasis color for text and icons on secondary fixed elements.",
-  onSurface: "High-emphasis color for text and icons on surface backgrounds.",
-  onSurfaceVariant: "Medium-emphasis color for text and icons on surface variant backgrounds.",
-  onTertiary: "Color for text and icons on tertiary-colored elements.",
-  onTertiaryContainer: "Color for text and icons on tertiary container elements.",
-  onTertiaryFixed: "Color for text and icons on tertiary fixed elements, constant across themes.",
-  onTertiaryFixedVariant: "Lower-emphasis color for text and icons on tertiary fixed elements.",
-  outline: "Subtle color for borders and dividers to create visual separation.",
-  outlineVariant: "Lower-emphasis border color used for decorative dividers.",
-  primary: "Main brand color, used for key components like filled buttons and active states.",
-  primaryContainer: "Fill color for large primary elements like cards and tonal buttons.",
-  primaryFixed: "Fixed primary color that stays the same in light and dark themes.",
-  primaryFixedDim: "Dimmed variant of the fixed primary color for lower emphasis.",
-  scrim: "Color overlay for modals and dialogs to obscure background content.",
-  secondary: "Accent color for less prominent elements like filter chips and selections.",
-  secondaryContainer: "Fill color for secondary container elements like tonal buttons and input fields.",
-  secondaryFixed: "Fixed secondary color that stays the same in light and dark themes.",
-  secondaryFixedDim: "Dimmed variant of the fixed secondary color for lower emphasis.",
-  shadow: "Color for elevation shadows applied to surfaces and components.",
-  surface: "Default surface color for cards, sheets, and dialogs.",
-  surfaceBright: "Brightest surface variant, used for elevated surfaces in dark themes.",
-  surfaceContainer: "Middle-emphasis container color for grouping related content.",
-  surfaceContainerHigh: "Higher-emphasis container color for elements like cards.",
-  surfaceContainerHighest: "Highest-emphasis container color for text fields and other input areas.",
-  surfaceContainerLow: "Lower-emphasis container color for subtle surface groupings.",
-  surfaceContainerLowest: "Lowest-emphasis container, typically the lightest surface in light theme.",
-  surfaceDim: "Dimmest surface variant, used for recessed areas or dark theme backgrounds.",
-  surfaceTint: "Tint color applied to surfaces for subtle primary color elevation overlay.",
-  surfaceVariant: "Alternative surface color for differentiated areas like sidebar backgrounds.",
-  tertiary: "Third accent color for complementary elements that balance primary and secondary.",
-  tertiaryContainer: "Fill color for tertiary container elements like complementary cards.",
-  tertiaryFixed: "Fixed tertiary color that stays the same in light and dark themes.",
-  tertiaryFixedDim: "Dimmed variant of the fixed tertiary color for lower emphasis."
-};
-function isTokenName(key) {
-  return key in tokenDescriptions;
-}
-var tokenNames = Object.keys(tokenDescriptions).filter(isTokenName);
 function deriveCustomPaletteName(tokenName, allPaletteNamesKebab) {
   let baseName = tokenName;
   if (/^on[A-Z]/.test(baseName) && baseName.length > 2) {
@@ -985,11 +1040,20 @@ function builder(hexSource, {
   customColors: hexCustomColors = DEFAULT_CUSTOM_COLORS,
   prefix = DEFAULT_PREFIX
 } = {}) {
+  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);
@@ -997,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"
     },
@@ -1128,6 +1192,8 @@ function builder(hexSource, {
     toFigmaTokens: () => buildFigmaTokens(ctx),
     toTailwind: (options) => buildTailwind(ctx, options),
     toShadcn: () => buildShadcn(ctx),
+    toShadcnAliases: () => buildShadcnAliases(ctx),
+    toShadcnRegistryItem: (options) => buildShadcnRegistryItem(ctx, options),
     toFlutter: () => buildFlutter(ctx),
     mergedColorsLight,
     mergedColorsDark,
@@ -1135,89 +1201,220 @@ function builder(hexSource, {
   };
 }
 
+// src/cli.options.ts
+function parseHexColor(value) {
+  if (!isHexColor(value))
+    throw new InvalidArgumentError(
+      "Expected a hex color \u2014 3, 6 or 8 hex digits, with or without '#' (e.g. #6750A4)."
+    );
+  return value;
+}
+function addSourceArgument(command) {
+  return command.argument(
+    "<source>",
+    "Source color in hex format (e.g. #6750A4)",
+    parseHexColor
+  );
+}
+function addThemeOptions(command) {
+  return command.addOption(
+    new Option("--scheme <name>", "Color scheme variant").choices(schemeNames).default(DEFAULT_SCHEME)
+  ).option(
+    "--contrast <number>",
+    "Contrast level from -1.0 to 1.0",
+    parseFloat,
+    DEFAULT_CONTRAST
+  ).option("--primary <hex>", "Primary color override", parseHexColor).option("--secondary <hex>", "Secondary color override", parseHexColor).option("--tertiary <hex>", "Tertiary color override", parseHexColor).option("--error <hex>", "Error color override", parseHexColor).option("--neutral <hex>", "Neutral color override", parseHexColor).option(
+    "--neutral-variant <hex>",
+    "Neutral variant color override",
+    parseHexColor
+  ).option(
+    "--no-fallback",
+    "Omit this theme's colors as the var() fallbacks in the registry item, so it renders nothing without an <Mtb> above it"
+  ).option(
+    "--prefix <string>",
+    "CSS variable prefix (e.g. md \u2192 --md-sys-color-*, --md-ref-palette-*)",
+    DEFAULT_PREFIX
+  );
+}
+function builderOptions(opts) {
+  return {
+    scheme: opts.scheme,
+    contrast: opts.contrast,
+    primary: opts.primary,
+    secondary: opts.secondary,
+    tertiary: opts.tertiary,
+    error: opts.error,
+    neutral: opts.neutral,
+    neutralVariant: opts.neutralVariant,
+    prefix: opts.prefix
+  };
+}
+function themeFrom(command) {
+  const opts = command.opts();
+  return {
+    options: builderOptions(opts),
+    // Declared as a negation, so commander's own default here is `true` -- the
+    // 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
+  };
+}
+
+// src/cli.shadcn.ts
+import { spawnSync } from "child_process";
+import * as fs from "fs";
+import * as path from "path";
+import "commander";
+var NPX = ["npx", "--yes"];
+var DEFAULT_SHADCN = "shadcn@latest";
+var YES = "--yes";
+var ITEM = "mtb.json";
+function addArgv(shadcn, forwarded = []) {
+  return [...NPX, shadcn, "add", `./${ITEM}`, YES, ...forwarded];
+}
+function fail(message, code = 1) {
+  console.error(`Error: ${message}`);
+  process.exit(code);
+}
+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 { options, fallback } = themeFrom(command);
+  const item = builder(source, options).toShadcnRegistryItem({ fallback });
+  fs.writeFileSync(file, `${JSON.stringify(item, null, 2)}
+`);
+}
+function runApply(source, forwarded, 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
 var customColorSchema = z.array(
   z.object({
     name: z.string(),
-    hex: z.string(),
+    hex: z.string().refine(
+      isHexColor,
+      "must be a hex color \u2014 3, 6 or 8 hex digits, with or without '#' (e.g. #FF5733)"
+    ),
     blend: z.boolean().default(DEFAULT_BLEND)
   })
 );
 function writeFigmaTokens(theme, outputDir) {
-  fs.mkdirSync(outputDir, { recursive: true });
+  fs2.mkdirSync(outputDir, { recursive: true });
   for (const [filename, content] of Object.entries(theme.toFigmaTokens())) {
-    const filePath = path.join(outputDir, filename);
-    fs.writeFileSync(filePath, JSON.stringify(content, null, 2) + "\n");
+    const filePath = path2.join(outputDir, filename);
+    fs2.writeFileSync(filePath, JSON.stringify(content, null, 2) + "\n");
     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":
       return process.stdout.write(theme.toTailwind({ shadcn: opts.shadcn }));
     case "shadcn":
       return process.stdout.write(json(theme.toShadcn()));
+    case "registry-item":
+      return process.stdout.write(
+        json(theme.toShadcnRegistryItem({ fallback: opts.fallback }))
+      );
     case "flutter":
       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 Command();
-program.name("material-theme-builder").description("Generate a color theme from a source color").argument("<source>", "Source color in hex format (e.g. #6750A4)").addOption(
-  new Option("--scheme <name>", "Color scheme variant").choices(schemeNames).default(DEFAULT_SCHEME)
+addThemeOptions(
+  addSourceArgument(
+    program.name("material-theme-builder").description("Generate a color theme from a source color")
+  ).enablePositionalOptions()
 ).option(
-  "--contrast <number>",
-  "Contrast level from -1.0 to 1.0",
-  parseFloat,
-  DEFAULT_CONTRAST
-).option("--primary <hex>", "Primary color override").option("--secondary <hex>", "Secondary color override").option("--tertiary <hex>", "Tertiary color override").option("--error <hex>", "Error color override").option("--neutral <hex>", "Neutral color override").option("--neutral-variant <hex>", "Neutral variant color override").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, 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)"
-).option(
-  "--prefix <string>",
-  "CSS variable prefix (e.g. md \u2192 --md-sys-color-*, --md-ref-palette-*)",
-  DEFAULT_PREFIX
-).action((source, opts) => {
+).action((source, opts, command) => {
   if (opts.shadcn && opts.format !== "tailwind") {
     console.error(
       "Error: --shadcn only applies to --format tailwind. For concrete color values, use --format shadcn."
     );
     process.exit(1);
   }
+  if (command.getOptionValueSource("fallback") === "cli" && opts.format !== "registry-item") {
+    console.error(
+      "Error: --no-fallback only applies to --format registry-item."
+    );
+    process.exit(1);
+  }
   let customColors = [];
   if (opts.customColors) {
-    const result2 = customColorSchema.safeParse(JSON.parse(opts.customColors));
-    if (!result2.success) {
+    let parsed;
+    try {
+      parsed = JSON.parse(opts.customColors);
+    } catch {
       console.error("Error: --custom-colors must be valid JSON");
       process.exit(1);
     }
+    const result2 = customColorSchema.safeParse(parsed);
+    if (!result2.success) {
+      const issue = result2.error.issues[0];
+      const where = issue?.path.length ? ` at ${issue.path.join(".")}` : "";
+      console.error(
+        `Error: --custom-colors${where}: ${issue?.message ?? "is invalid"}`
+      );
+      process.exit(1);
+    }
     customColors = result2.data;
   }
   const result = builder(source, {
-    scheme: opts.scheme,
-    contrast: opts.contrast,
-    primary: opts.primary,
-    secondary: opts.secondary,
-    tertiary: opts.tertiary,
-    error: opts.error,
-    neutral: opts.neutral,
-    neutralVariant: opts.neutralVariant,
-    customColors,
-    prefix: opts.prefix
+    ...builderOptions(opts),
+    customColors
   });
   writeOutput(result, opts);
 });
+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)
+);
 program.parse();

package/dist/index.d.ts

@@ -27,6 +27,31 @@ type ShadcnTheme = {
     light: Record<ShadcnVarName, string>;
     dark: Record<ShadcnVarName, string>;
 };
+/**
+ * A shadcn registry item carrying the alias mapping, as
+ * `toShadcnRegistryItem()` returns it.
+ *
+ * @see https://ui.shadcn.com/schema/registry-item.json
+ */
+type ShadcnRegistryItem = {
+    $schema: string;
+    name: string;
+    type: "registry:theme";
+    title: string;
+    description: string;
+    cssVars: ShadcnTheme;
+};
+/** Options for `toShadcnRegistryItem()`. */
+type ShadcnRegistryItemOptions = {
+    /**
+     * Embed this theme's concrete colors as the `var()` fallbacks, so the item
+     * also works where nothing declares the M3 custom properties. Off by default
+     * — see `buildShadcnRegistryItem()` for why.
+     *
+     * @default false
+     */
+    fallback?: boolean;
+};
 
 /** DTCG color value (direct, non-alias) */
 type DtcgColorValue = {
@@ -110,6 +135,8 @@ type MtbConfig = {
     /**
      * Array of custom colors to include in the generated palette.
      * Each custom color can be blended with the source color for harmonization.
+     *
+     * @see https://m3.material.io/blog/dynamic-color-harmony
      */
     customColors?: HexCustomColor[];
     /**
@@ -178,6 +205,8 @@ declare function builder(hexSource: MtbConfig["source"], { scheme, contrast, pri
     };
     toTailwind: (options?: TailwindOptions) => string;
     toShadcn: () => ShadcnTheme;
+    toShadcnAliases: () => string;
+    toShadcnRegistryItem: (options?: ShadcnRegistryItemOptions) => ShadcnRegistryItem;
     toFlutter: () => string;
     mergedColorsLight: {
         [x: string]: number;
@@ -195,4 +224,4 @@ declare function builder(hexSource: MtbConfig["source"], { scheme, contrast, pri
     };
 };
 
-export { type McuConfig, type MtbConfig, type ShadcnTheme, type ShadcnVarName, builder };
+export { type McuConfig, type MtbConfig, type ShadcnRegistryItem, type ShadcnTheme, type ShadcnVarName, builder };