material-theme-builder 3.2.0 → 3.3.0

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 };

package/dist/index.js

@@ -653,6 +653,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,
+.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 {
@@ -663,6 +696,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],
@@ -684,6 +775,8 @@ var CORE_PALETTES = [
   "neutral",
   "neutral-variant"
 ];
+
+// src/lib/builder.tailwind.ts
 function buildTailwind(ctx, options) {
   const { prefix, mergedColorsLight, hexCustomColors } = ctx;
   const lines = [];
@@ -716,17 +809,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;
 }
 
@@ -744,7 +828,24 @@ 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)
+  );
+}
 var STANDARD_TONES = [
   0,
   4,
@@ -795,61 +896,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) {
@@ -968,6 +1014,11 @@ function builder(hexSource, {
   customColors: hexCustomColors = DEFAULT_CUSTOM_COLORS,
   prefix = DEFAULT_PREFIX
 } = {}) {
+  assertHexInputs(
+    hexSource,
+    { primary, secondary, tertiary, error, neutral, neutralVariant },
+    hexCustomColors
+  );
   const sourceArgb = argbFromHex2(hexSource);
   const sourceHct = Hct2.fromInt(sourceArgb);
   const effectiveSource = primary || hexSource;
@@ -1111,6 +1162,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,

package/dist/react.d.ts

@@ -55,60 +55,29 @@ type FigmaVariable = {
     values: Record<string, FigmaVariableValue>;
 };
 
-/** A custom color defined with a hex string instead of an ARGB integer. */
-type HexCustomColor = Omit<CustomColor, "value"> & {
-    hex: string;
-};
-/** Available Material You color scheme variants. */
-declare const schemeNames: readonly ["tonalSpot", "monochrome", "neutral", "vibrant", "expressive", "fidelity", "content"];
-type SchemeName = (typeof schemeNames)[number];
-/** Configuration for the Material Theme Builder. */
-type MtbConfig = {
-    /** Source color in hex format (e.g., "#6750A4") used to generate the color scheme */
-    source: string;
-    /** Color scheme variant. Default: "tonalSpot" */
-    scheme?: SchemeName;
-    /** Contrast level from -1.0 (reduced) to 1.0 (increased). Default: 0 (standard) */
-    contrast?: number;
-    /** Primary color - the main brand color. Overrides the default palette generation. */
-    primary?: string;
-    /** Secondary color - accent color. Overrides the default palette generation. */
-    secondary?: string;
-    /** Tertiary color - additional accent color. Overrides the default palette generation. */
-    tertiary?: string;
-    /** Neutral color - used for surfaces. Overrides the default palette generation. */
-    neutral?: string;
-    /** Neutral variant color - used for surfaces with slight tint. Overrides the default palette generation. */
-    neutralVariant?: string;
-    /** Error color - used for error states. Overrides the default palette generation. */
-    error?: string;
-    /**
-     * Color match mode for core colors.
-     * When true, stays true to input colors without harmonization.
-     * When false (default), colors may be adjusted for better harmonization.
-     * Corresponds to "Color match - Stay true to my color inputs" in Material Theme Builder.
-     *
-     * @deprecated Not yet implemented. This prop is currently ignored.
-     */
-    colorMatch?: boolean;
-    /**
-     * Array of custom colors to include in the generated palette.
-     * Each custom color can be blended with the source color for harmonization.
-     */
-    customColors?: HexCustomColor[];
-    /**
-     * Prefix for generated CSS custom properties and Figma token css.variable extensions.
-     * Scheme tokens use `--{prefix}-sys-color-*`, palette tones use `--{prefix}-ref-palette-*`.
-     * Default: "md" (Material Design convention).
-     */
-    prefix?: string;
-};
 /**
  * Material Design 3 token names and their descriptions.
  *
  * Centralizes both the canonical list of scheme tokens and their M3 color role semantics.
  *
- * @see https://m3.material.io/styles/color/the-color-system/color-roles
+ * The Material Design blog is the best source on *why* these roles are shaped
+ * the way they are — the spec pages state the what, the blog posts the
+ * reasoning, and they are where role changes get announced first (the
+ * tone-based surfaces post is what documents `surface-variant` giving way to
+ * `surface-container-highest`).
+ *
+ * Note that the list below is wider than the spec's own inventory — "26
+ * standard color roles organized into six groups" — because it also carries
+ * the add-on roles (fixed accents, surface dim/bright, inverse) and the ones
+ * the spec has since dropped but the exporters still emit: `background`,
+ * `onBackground`, `surfaceVariant`, `surfaceTint`.
+ *
+ * Deep links below are section anchors; the spec site is a client-rendered SPA,
+ * so `#:~:text=` fragments are stripped on load and only these work.
+ *
+ * @see https://m3.material.io/styles/color/roles
+ * @see https://m3.material.io/blog/tone-based-surface-color-m3
+ * @see https://m3.material.io/blog/science-of-color-design
  */
 declare const tokenDescriptions: {
     readonly background: "Default background color for screens and large surfaces.";
@@ -164,6 +133,57 @@ declare const tokenDescriptions: {
 /** Union of all known M3 color token names. */
 type TokenName = keyof typeof tokenDescriptions;
 
+/** A custom color defined with a hex string instead of an ARGB integer. */
+type HexCustomColor = Omit<CustomColor, "value"> & {
+    hex: string;
+};
+/** Available Material You color scheme variants. */
+declare const schemeNames: readonly ["tonalSpot", "monochrome", "neutral", "vibrant", "expressive", "fidelity", "content"];
+type SchemeName = (typeof schemeNames)[number];
+/** Configuration for the Material Theme Builder. */
+type MtbConfig = {
+    /** Source color in hex format (e.g., "#6750A4") used to generate the color scheme */
+    source: string;
+    /** Color scheme variant. Default: "tonalSpot" */
+    scheme?: SchemeName;
+    /** Contrast level from -1.0 (reduced) to 1.0 (increased). Default: 0 (standard) */
+    contrast?: number;
+    /** Primary color - the main brand color. Overrides the default palette generation. */
+    primary?: string;
+    /** Secondary color - accent color. Overrides the default palette generation. */
+    secondary?: string;
+    /** Tertiary color - additional accent color. Overrides the default palette generation. */
+    tertiary?: string;
+    /** Neutral color - used for surfaces. Overrides the default palette generation. */
+    neutral?: string;
+    /** Neutral variant color - used for surfaces with slight tint. Overrides the default palette generation. */
+    neutralVariant?: string;
+    /** Error color - used for error states. Overrides the default palette generation. */
+    error?: string;
+    /**
+     * Color match mode for core colors.
+     * When true, stays true to input colors without harmonization.
+     * When false (default), colors may be adjusted for better harmonization.
+     * Corresponds to "Color match - Stay true to my color inputs" in Material Theme Builder.
+     *
+     * @deprecated Not yet implemented. This prop is currently ignored.
+     */
+    colorMatch?: boolean;
+    /**
+     * 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[];
+    /**
+     * Prefix for generated CSS custom properties and Figma token css.variable extensions.
+     * Scheme tokens use `--{prefix}-sys-color-*`, palette tones use `--{prefix}-ref-palette-*`.
+     * Default: "md" (Material Design convention).
+     */
+    prefix?: string;
+};
+
 interface ExportButtonProps {
     /** Current theme configuration used to generate the exported tokens. */
     config: MtbConfig;