material-theme-builder 5.0.0 → 5.1.0

package/README.md

@@ -2,7 +2,7 @@
 [![](https://img.shields.io/badge/chromatic-171c23.svg?logo=chromatic)](https://www.chromatic.com/library?appId=695eb517cb602e59b4cc045c&branch=main)
 [![](https://img.shields.io/badge/storybook-171c23.svg?logo=storybook)](https://main--695eb517cb602e59b4cc045c.chromatic.com)
 
-Outputs [m3 colors](https://m3.material.io/styles/color/system/overview) `--md-sys-color-*` and `--md-ref-palette-*`, 1:1 with [Material Theme Builder](https://material-foundation.github.io/material-theme-builder/), either:
+Outputs [m3 colors](https://m3.material.io/styles/color/system/overview) `--md-sys-color-*`, 1:1 with [Material Theme Builder](https://material-foundation.github.io/material-theme-builder/), and the `--md-ref-palette-*` tonal palettes they are drawn from, either:
 
 - [programmatically](#programmatic-api)
 - from [CLI](#cli)
@@ -19,8 +19,8 @@ Support for:
 - [x] core-colors overrides: primary, secondary, tertiary, error, neutral,
       neutralVariant
 - [x] custom-colors (aka. "Extended colors")
-  - [x] Harmonization (aka. `blend`) -- with effective color: `source` or
-        `primary` if defined
+  - [x] Harmonization (aka. `blend`, on by default) -- with effective color:
+        `source` or `primary` if defined
 - [x] Shades (aka. "tonals")
 - [ ] colorMatch
 
@@ -52,6 +52,18 @@ theme.toShadcnAliases();
 theme.toShadcnRegistryItem({ fallback: true });
 ```
 
+> [!NOTE]
+>
+> `toJson()` is shaped like Material Theme Builder's JSON export, and its
+> `schemes` match it. Its `palettes`, though, are the reference palettes: the
+> palettes the system colors are drawn from, the same ones, tones and values as
+> the `--md-ref-palette-*` of `toCss()` (`error` and custom colors included, 28
+> tones). Material Theme Builder's own export holds other palettes -- five, at
+> 18 tones, which ignore the scheme variant and are not the palettes its
+> `schemes` come from. They are not reproduced: Material Theme Builder's
+> maintainers say they are only there as reference. See [ADR 0001](docs/adr/0001-reference-palettes-are-the-scheme-palettes.md)
+> for why.
+
 ## CLI
 
 ```sh

package/dist/cli.js

@@ -27,19 +27,17 @@ import {
   SchemeNeutral,
   SchemeTonalSpot,
   SchemeVibrant,
-  TonalPalette as TonalPalette2
+  TonalPalette
 } from "@material/material-color-utilities";
 import { kebabCase as kebabCase4, upperFirst as upperFirst2 } from "lodash-es";
 
 // src/lib/builder.css.ts
-import {
-  hexFromArgb
-} from "@material/material-color-utilities";
+import { hexFromArgb } from "@material/material-color-utilities";
 import { kebabCase } from "lodash-es";
 function buildCss(ctx) {
   const {
     prefix,
-    allPalettes,
+    refPalettes,
     mergedColorsLight,
     mergedColorsDark,
     tokenToPalette,
@@ -47,10 +45,9 @@ function buildCss(ctx) {
   } = ctx;
   function buildRefPaletteLookup() {
     const lookup = {};
-    for (const [name, palette] of Object.entries(allPalettes)) {
-      const paletteName = kebabCase(name);
-      for (const tone of STANDARD_TONES) {
-        const hex = hexFromArgb(palette.tone(tone));
+    for (const [paletteName, tones] of Object.entries(refPalettes)) {
+      for (const { tone, argb } of tones) {
+        const hex = hexFromArgb(argb);
         if (!lookup[hex]) lookup[hex] = [];
         lookup[hex].push({ paletteName, tone });
       }
@@ -78,15 +75,12 @@ function buildCss(ctx) {
     const value = hexFromArgb(colorValue);
     return `${name}:${value};`;
   }
-  function generateTonalPaletteVars(paletteName, palette) {
-    return STANDARD_TONES.map((tone) => {
-      const color = palette.tone(tone);
-      return refPaletteVar(paletteName, tone, color);
-    }).join(" ");
+  function generateTonalPaletteVars(paletteName, tones) {
+    return tones.map(({ tone, argb }) => refPaletteVar(paletteName, tone, argb)).join(" ");
   }
   function generateTonalVars() {
-    return Object.entries(allPalettes).map(
-      ([name, palette]) => generateTonalPaletteVars(kebabCase(name), palette)
+    return Object.entries(refPalettes).map(
+      ([paletteName, tones]) => generateTonalPaletteVars(paletteName, tones)
     ).join(" ");
   }
   const refPaletteLookup = buildRefPaletteLookup();
@@ -388,29 +382,8 @@ import {
   DynamicScheme,
   Hct,
   hexFromArgb as hexFromArgb4,
-  MaterialDynamicColors,
-  TonalPalette
+  MaterialDynamicColors
 } from "@material/material-color-utilities";
-var MTB_TONES = [
-  0,
-  5,
-  10,
-  15,
-  20,
-  25,
-  30,
-  35,
-  40,
-  50,
-  60,
-  70,
-  80,
-  90,
-  95,
-  98,
-  99,
-  100
-];
 var FIXTURE_TOKEN_ORDER = [
   "primary",
   "surfaceTint",
@@ -465,7 +438,6 @@ var FIXTURE_TOKEN_ORDER = [
 function buildJson(ctx) {
   const {
     hexSource,
-    sourceHct,
     effectiveSourceArgb,
     primaryHct,
     SchemeClass,
@@ -476,34 +448,16 @@ function buildJson(ctx) {
     error,
     neutral,
     neutralVariant,
-    hexCustomColors
+    hexCustomColors,
+    refPalettes
   } = ctx;
-  const neuHct = neutral ? Hct.fromInt(argbFromHex(neutral)) : sourceHct;
-  const nvHct = neutralVariant ? Hct.fromInt(argbFromHex(neutralVariant)) : sourceHct;
-  const rawPalettes = {
-    primary: TonalPalette.fromInt(effectiveSourceArgb),
-    secondary: secondary ? TonalPalette.fromInt(argbFromHex(secondary)) : TonalPalette.fromHueAndChroma(sourceHct.hue, sourceHct.chroma / 3),
-    tertiary: tertiary ? TonalPalette.fromInt(argbFromHex(tertiary)) : TonalPalette.fromHueAndChroma(
-      (sourceHct.hue + 60) % 360,
-      sourceHct.chroma / 2
-    ),
-    neutral: TonalPalette.fromHueAndChroma(
-      neuHct.hue,
-      Math.min(neuHct.chroma / 12, 4)
-    ),
-    "neutral-variant": TonalPalette.fromHueAndChroma(
-      nvHct.hue,
-      Math.min(nvHct.chroma / 6, 8)
-    )
-  };
   function buildJsonSchemes() {
-    function extractSchemeColors(scheme2, backgroundScheme) {
+    function extractSchemeColors(scheme2) {
       const colors = {};
       for (const tokenName of FIXTURE_TOKEN_ORDER) {
         const dynamicColor = MaterialDynamicColors[tokenName];
-        const useScheme = backgroundScheme && (tokenName === "background" || tokenName === "onBackground") ? backgroundScheme : scheme2;
         colors[tokenName] = hexFromArgb4(
-          dynamicColor.getArgb(useScheme)
+          dynamicColor.getArgb(scheme2)
         ).toUpperCase();
       }
       return colors;
@@ -543,26 +497,18 @@ function buildJson(ctx) {
         neutralVariantPalette: nvPalette || baseScheme.neutralVariantPalette
       });
       if (errPalette) composedScheme.errorPalette = errPalette;
-      jsonSchemes[name] = extractSchemeColors(composedScheme, baseScheme);
+      jsonSchemes[name] = extractSchemeColors(composedScheme);
     }
     return jsonSchemes;
   }
-  function rawPalettesToJson() {
+  function refPalettesToJson() {
     const jsonPalettes = {};
-    const RAW_PALETTE_NAMES = [
-      "primary",
-      "secondary",
-      "tertiary",
-      "neutral",
-      "neutral-variant"
-    ];
-    for (const name of RAW_PALETTE_NAMES) {
-      const palette = rawPalettes[name];
-      const tones = {};
-      for (const tone of MTB_TONES) {
-        tones[tone.toString()] = hexFromArgb4(palette.tone(tone)).toUpperCase();
+    for (const [name, tones] of Object.entries(refPalettes)) {
+      const jsonTones = {};
+      for (const { tone, argb } of tones) {
+        jsonTones[tone.toString()] = hexFromArgb4(argb).toUpperCase();
       }
-      jsonPalettes[name] = tones;
+      jsonPalettes[name] = jsonTones;
     }
     return jsonPalettes;
   }
@@ -589,14 +535,14 @@ function buildJson(ctx) {
     name: c.name,
     color: c.hex.toUpperCase(),
     description: "",
-    harmonized: c.blend ?? DEFAULT_BLEND
+    harmonized: c.blend
   }));
   return {
     seed,
     coreColors,
     extendedColors,
     schemes: buildJsonSchemes(),
-    palettes: rawPalettesToJson()
+    palettes: refPalettesToJson()
   };
 }
 
@@ -945,51 +891,53 @@ function getPalette(palettes, colorName) {
   }
   return palette;
 }
-function mergeBaseAndCustomColors(scheme, customColors, colorPalettes) {
-  const baseVars = toRecord(tokenNames, (tokenName) => {
-    const dynamicColor = MaterialDynamicColors2[tokenName];
-    const argb = dynamicColor.getArgb(scheme);
-    return [tokenName, argb];
-  });
-  const customVars = {};
-  customColors.forEach((color) => {
-    const colorname = color.name;
-    const getPaletteForColor = () => getPalette(colorPalettes, colorname);
-    const colorDynamicColor = new DynamicColor(
+function buildCustomColorRoles(colorname, palette) {
+  const getPaletteForColor = () => palette;
+  return {
+    [colorname]: new DynamicColor(
       colorname,
       getPaletteForColor,
       (s) => s.isDark ? 80 : 40,
       // Main color: lighter in dark mode, darker in light mode
       true
       // background
-    );
-    const onColorDynamicColor = new DynamicColor(
+    ),
+    [`on${upperFirst2(colorname)}`]: new DynamicColor(
       `on${upperFirst2(colorname)}`,
       getPaletteForColor,
       (s) => s.isDark ? 20 : 100,
       // Text on main color: high contrast (dark on light, light on dark)
       false
-    );
-    const containerDynamicColor = new DynamicColor(
+    ),
+    [`${colorname}Container`]: new DynamicColor(
       `${colorname}Container`,
       getPaletteForColor,
       (s) => s.isDark ? 30 : 90,
       // Container: subtle variant (darker in dark mode, lighter in light mode)
       true
       // background
-    );
-    const onContainerDynamicColor = new DynamicColor(
+    ),
+    [`on${upperFirst2(colorname)}Container`]: new DynamicColor(
       `on${upperFirst2(colorname)}Container`,
       getPaletteForColor,
       (s) => s.isDark ? 90 : 30,
       // Text on container: high contrast against container background
       false
-    );
-    customVars[colorname] = colorDynamicColor.getArgb(scheme);
-    customVars[`on${upperFirst2(colorname)}`] = onColorDynamicColor.getArgb(scheme);
-    customVars[`${colorname}Container`] = containerDynamicColor.getArgb(scheme);
-    customVars[`on${upperFirst2(colorname)}Container`] = onContainerDynamicColor.getArgb(scheme);
+    )
+  };
+}
+function mergeBaseAndCustomColors(scheme, customColorRoles) {
+  const baseVars = toRecord(tokenNames, (tokenName) => {
+    const dynamicColor = MaterialDynamicColors2[tokenName];
+    const argb = dynamicColor.getArgb(scheme);
+    return [tokenName, argb];
   });
+  const customVars = {};
+  for (const roles of Object.values(customColorRoles)) {
+    for (const [tokenName, dynamicColor] of Object.entries(roles)) {
+      customVars[tokenName] = dynamicColor.getArgb(scheme);
+    }
+  }
   return { ...baseVars, ...customVars };
 }
 function createColorPalette(colorDef, baseScheme, effectiveSourceForHarmonization) {
@@ -1008,7 +956,17 @@ function createColorPalette(colorDef, baseScheme, effectiveSourceForHarmonizatio
   } else {
     targetChroma = baseScheme.primaryPalette.chroma;
   }
-  return TonalPalette2.fromHueAndChroma(hct.hue, targetChroma);
+  return TonalPalette.fromHueAndChroma(hct.hue, targetChroma);
+}
+function buildRefPalettes(allPalettes) {
+  const refPalettes = {};
+  for (const [name, palette] of Object.entries(allPalettes)) {
+    refPalettes[kebabCase4(name)] = STANDARD_TONES.map((tone) => ({
+      tone,
+      argb: palette.tone(tone)
+    }));
+  }
+  return refPalettes;
 }
 function buildTokenToPaletteMap(schemePalettes, scheme) {
   const result = {};
@@ -1037,7 +995,7 @@ function builder(hexSource, {
   neutral,
   neutralVariant,
   error,
-  customColors: hexCustomColors = DEFAULT_CUSTOM_COLORS,
+  customColors: customColorInputs = DEFAULT_CUSTOM_COLORS,
   prefix = DEFAULT_PREFIX
 } = {}) {
   const cores = {
@@ -1048,9 +1006,12 @@ function builder(hexSource, {
     neutral: optionalHex(neutral),
     neutralVariant: optionalHex(neutralVariant)
   };
-  assertHexInputs(hexSource, cores, hexCustomColors);
+  assertHexInputs(hexSource, cores, customColorInputs);
+  const hexCustomColors = customColorInputs.map((c) => ({
+    ...c,
+    blend: c.blend ?? DEFAULT_BLEND
+  }));
   const sourceArgb = argbFromHex2(hexSource);
-  const sourceHct = Hct2.fromInt(sourceArgb);
   const effectiveSource = cores.primary || hexSource;
   const effectiveSourceArgb = argbFromHex2(effectiveSource);
   const effectiveSourceForHarmonization = cores.primary ? argbFromHex2(cores.primary) : sourceArgb;
@@ -1141,18 +1102,21 @@ function builder(hexSource, {
   };
   const customColors = definedColors.filter((c) => !c.core).map((c) => ({
     name: c.name,
-    blend: c.blend ?? DEFAULT_BLEND,
     value: argbFromHex2(c.hex)
   }));
+  const customColorRoles = Object.fromEntries(
+    customColors.map((color) => [
+      color.name,
+      buildCustomColorRoles(color.name, getPalette(colorPalettes, color.name))
+    ])
+  );
   const mergedColorsLight = mergeBaseAndCustomColors(
     lightScheme,
-    customColors,
-    colorPalettes
+    customColorRoles
   );
   const mergedColorsDark = mergeBaseAndCustomColors(
     darkScheme,
-    customColors,
-    colorPalettes
+    customColorRoles
   );
   const schemePalettes = [
     ["primary", lightScheme.primaryPalette],
@@ -1163,6 +1127,7 @@ function builder(hexSource, {
     ["neutral-variant", lightScheme.neutralVariantPalette]
   ];
   const tokenToPalette = buildTokenToPaletteMap(schemePalettes, lightScheme);
+  const refPalettes = buildRefPalettes(allPalettes);
   const allPaletteNamesKebab = new Set(Object.keys(allPalettes).map(kebabCase4));
   const ctx = {
     hexSource,
@@ -1175,11 +1140,11 @@ function builder(hexSource, {
     neutralVariant,
     error,
     hexCustomColors,
-    sourceHct,
     effectiveSourceArgb,
     primaryHct,
     SchemeClass,
     allPalettes,
+    refPalettes,
     mergedColorsLight,
     mergedColorsDark,
     tokenToPalette,
@@ -1197,7 +1162,8 @@ function builder(hexSource, {
     toFlutter: () => buildFlutter(ctx),
     mergedColorsLight,
     mergedColorsDark,
-    allPalettes
+    allPalettes,
+    customColorRoles
   };
 }
 
@@ -1310,7 +1276,8 @@ var customColorSchema = z.array(
       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)
+    // left to builder(), which applies DEFAULT_BLEND to an omitted `blend`
+    blend: z.boolean().optional()
   })
 );
 function writeFigmaTokens(theme, outputDir) {

package/dist/index.d.ts

@@ -1,4 +1,4 @@
-import { CustomColor, TonalPalette } from '@material/material-color-utilities';
+import { CustomColor, TonalPalette, DynamicColor } from '@material/material-color-utilities';
 
 /**
  * shadcn CSS variable → M3 sys-color token mapping.
@@ -97,8 +97,13 @@ type TailwindOptions = {
 };
 
 /** A custom color defined with a hex string instead of an ARGB integer. */
-type HexCustomColor = Omit<CustomColor, "value"> & {
+type HexCustomColor = Omit<CustomColor, "value" | "blend"> & {
     hex: string;
+    /**
+     * Harmonize the color with the source (or `primary`, when given) -- "Harmonize"
+     * in Material Theme Builder. Default: `DEFAULT_BLEND` (true).
+     */
+    blend?: boolean;
 };
 /** Available Material You color scheme variants. */
 declare const schemeNames: readonly ["tonalSpot", "monochrome", "neutral", "vibrant", "expressive", "fidelity", "content"];
@@ -164,7 +169,7 @@ type McuConfig = MtbConfig;
  * const json = theme.toJson();
  * ```
  */
-declare function builder(hexSource: MtbConfig["source"], { scheme, contrast, primary, secondary, tertiary, neutral, neutralVariant, error, customColors: hexCustomColors, prefix, }?: Omit<MtbConfig, "source">): {
+declare function builder(hexSource: MtbConfig["source"], { scheme, contrast, primary, secondary, tertiary, neutral, neutralVariant, error, customColors: customColorInputs, prefix, }?: Omit<MtbConfig, "source">): {
     toCss: () => string;
     toJson: () => {
         seed: string;
@@ -222,6 +227,11 @@ declare function builder(hexSource: MtbConfig["source"], { scheme, contrast, pri
         neutral: TonalPalette;
         "neutral-variant": TonalPalette;
     };
+    customColorRoles: {
+        [k: string]: {
+            [x: string]: DynamicColor;
+        };
+    };
 };
 
 export { type McuConfig, type MtbConfig, type ShadcnRegistryItem, type ShadcnTheme, type ShadcnVarName, builder };

package/dist/index.js

@@ -13,19 +13,17 @@ import {
   SchemeNeutral,
   SchemeTonalSpot,
   SchemeVibrant,
-  TonalPalette as TonalPalette2
+  TonalPalette
 } from "@material/material-color-utilities";
 import { kebabCase as kebabCase4, upperFirst as upperFirst2 } from "lodash-es";
 
 // src/lib/builder.css.ts
-import {
-  hexFromArgb
-} from "@material/material-color-utilities";
+import { hexFromArgb } from "@material/material-color-utilities";
 import { kebabCase } from "lodash-es";
 function buildCss(ctx) {
   const {
     prefix,
-    allPalettes,
+    refPalettes,
     mergedColorsLight,
     mergedColorsDark,
     tokenToPalette,
@@ -33,10 +31,9 @@ function buildCss(ctx) {
   } = ctx;
   function buildRefPaletteLookup() {
     const lookup = {};
-    for (const [name, palette] of Object.entries(allPalettes)) {
-      const paletteName = kebabCase(name);
-      for (const tone of STANDARD_TONES) {
-        const hex = hexFromArgb(palette.tone(tone));
+    for (const [paletteName, tones] of Object.entries(refPalettes)) {
+      for (const { tone, argb } of tones) {
+        const hex = hexFromArgb(argb);
         if (!lookup[hex]) lookup[hex] = [];
         lookup[hex].push({ paletteName, tone });
       }
@@ -64,15 +61,12 @@ function buildCss(ctx) {
     const value = hexFromArgb(colorValue);
     return `${name}:${value};`;
   }
-  function generateTonalPaletteVars(paletteName, palette) {
-    return STANDARD_TONES.map((tone) => {
-      const color = palette.tone(tone);
-      return refPaletteVar(paletteName, tone, color);
-    }).join(" ");
+  function generateTonalPaletteVars(paletteName, tones) {
+    return tones.map(({ tone, argb }) => refPaletteVar(paletteName, tone, argb)).join(" ");
   }
   function generateTonalVars() {
-    return Object.entries(allPalettes).map(
-      ([name, palette]) => generateTonalPaletteVars(kebabCase(name), palette)
+    return Object.entries(refPalettes).map(
+      ([paletteName, tones]) => generateTonalPaletteVars(paletteName, tones)
     ).join(" ");
   }
   const refPaletteLookup = buildRefPaletteLookup();
@@ -374,29 +368,8 @@ import {
   DynamicScheme,
   Hct,
   hexFromArgb as hexFromArgb4,
-  MaterialDynamicColors,
-  TonalPalette
+  MaterialDynamicColors
 } from "@material/material-color-utilities";
-var MTB_TONES = [
-  0,
-  5,
-  10,
-  15,
-  20,
-  25,
-  30,
-  35,
-  40,
-  50,
-  60,
-  70,
-  80,
-  90,
-  95,
-  98,
-  99,
-  100
-];
 var FIXTURE_TOKEN_ORDER = [
   "primary",
   "surfaceTint",
@@ -451,7 +424,6 @@ var FIXTURE_TOKEN_ORDER = [
 function buildJson(ctx) {
   const {
     hexSource,
-    sourceHct,
     effectiveSourceArgb,
     primaryHct,
     SchemeClass,
@@ -462,34 +434,16 @@ function buildJson(ctx) {
     error,
     neutral,
     neutralVariant,
-    hexCustomColors
+    hexCustomColors,
+    refPalettes
   } = ctx;
-  const neuHct = neutral ? Hct.fromInt(argbFromHex(neutral)) : sourceHct;
-  const nvHct = neutralVariant ? Hct.fromInt(argbFromHex(neutralVariant)) : sourceHct;
-  const rawPalettes = {
-    primary: TonalPalette.fromInt(effectiveSourceArgb),
-    secondary: secondary ? TonalPalette.fromInt(argbFromHex(secondary)) : TonalPalette.fromHueAndChroma(sourceHct.hue, sourceHct.chroma / 3),
-    tertiary: tertiary ? TonalPalette.fromInt(argbFromHex(tertiary)) : TonalPalette.fromHueAndChroma(
-      (sourceHct.hue + 60) % 360,
-      sourceHct.chroma / 2
-    ),
-    neutral: TonalPalette.fromHueAndChroma(
-      neuHct.hue,
-      Math.min(neuHct.chroma / 12, 4)
-    ),
-    "neutral-variant": TonalPalette.fromHueAndChroma(
-      nvHct.hue,
-      Math.min(nvHct.chroma / 6, 8)
-    )
-  };
   function buildJsonSchemes() {
-    function extractSchemeColors(scheme2, backgroundScheme) {
+    function extractSchemeColors(scheme2) {
       const colors = {};
       for (const tokenName of FIXTURE_TOKEN_ORDER) {
         const dynamicColor = MaterialDynamicColors[tokenName];
-        const useScheme = backgroundScheme && (tokenName === "background" || tokenName === "onBackground") ? backgroundScheme : scheme2;
         colors[tokenName] = hexFromArgb4(
-          dynamicColor.getArgb(useScheme)
+          dynamicColor.getArgb(scheme2)
         ).toUpperCase();
       }
       return colors;
@@ -529,26 +483,18 @@ function buildJson(ctx) {
         neutralVariantPalette: nvPalette || baseScheme.neutralVariantPalette
       });
       if (errPalette) composedScheme.errorPalette = errPalette;
-      jsonSchemes[name] = extractSchemeColors(composedScheme, baseScheme);
+      jsonSchemes[name] = extractSchemeColors(composedScheme);
     }
     return jsonSchemes;
   }
-  function rawPalettesToJson() {
+  function refPalettesToJson() {
     const jsonPalettes = {};
-    const RAW_PALETTE_NAMES = [
-      "primary",
-      "secondary",
-      "tertiary",
-      "neutral",
-      "neutral-variant"
-    ];
-    for (const name of RAW_PALETTE_NAMES) {
-      const palette = rawPalettes[name];
-      const tones = {};
-      for (const tone of MTB_TONES) {
-        tones[tone.toString()] = hexFromArgb4(palette.tone(tone)).toUpperCase();
+    for (const [name, tones] of Object.entries(refPalettes)) {
+      const jsonTones = {};
+      for (const { tone, argb } of tones) {
+        jsonTones[tone.toString()] = hexFromArgb4(argb).toUpperCase();
       }
-      jsonPalettes[name] = tones;
+      jsonPalettes[name] = jsonTones;
     }
     return jsonPalettes;
   }
@@ -575,14 +521,14 @@ function buildJson(ctx) {
     name: c.name,
     color: c.hex.toUpperCase(),
     description: "",
-    harmonized: c.blend ?? DEFAULT_BLEND
+    harmonized: c.blend
   }));
   return {
     seed,
     coreColors,
     extendedColors,
     schemes: buildJsonSchemes(),
-    palettes: rawPalettesToJson()
+    palettes: refPalettesToJson()
   };
 }
 
@@ -922,51 +868,53 @@ function getPalette(palettes, colorName) {
   }
   return palette;
 }
-function mergeBaseAndCustomColors(scheme, customColors, colorPalettes) {
-  const baseVars = toRecord(tokenNames, (tokenName) => {
-    const dynamicColor = MaterialDynamicColors2[tokenName];
-    const argb = dynamicColor.getArgb(scheme);
-    return [tokenName, argb];
-  });
-  const customVars = {};
-  customColors.forEach((color) => {
-    const colorname = color.name;
-    const getPaletteForColor = () => getPalette(colorPalettes, colorname);
-    const colorDynamicColor = new DynamicColor(
+function buildCustomColorRoles(colorname, palette) {
+  const getPaletteForColor = () => palette;
+  return {
+    [colorname]: new DynamicColor(
       colorname,
       getPaletteForColor,
       (s) => s.isDark ? 80 : 40,
       // Main color: lighter in dark mode, darker in light mode
       true
       // background
-    );
-    const onColorDynamicColor = new DynamicColor(
+    ),
+    [`on${upperFirst2(colorname)}`]: new DynamicColor(
       `on${upperFirst2(colorname)}`,
       getPaletteForColor,
       (s) => s.isDark ? 20 : 100,
       // Text on main color: high contrast (dark on light, light on dark)
       false
-    );
-    const containerDynamicColor = new DynamicColor(
+    ),
+    [`${colorname}Container`]: new DynamicColor(
       `${colorname}Container`,
       getPaletteForColor,
       (s) => s.isDark ? 30 : 90,
       // Container: subtle variant (darker in dark mode, lighter in light mode)
       true
       // background
-    );
-    const onContainerDynamicColor = new DynamicColor(
+    ),
+    [`on${upperFirst2(colorname)}Container`]: new DynamicColor(
       `on${upperFirst2(colorname)}Container`,
       getPaletteForColor,
       (s) => s.isDark ? 90 : 30,
       // Text on container: high contrast against container background
       false
-    );
-    customVars[colorname] = colorDynamicColor.getArgb(scheme);
-    customVars[`on${upperFirst2(colorname)}`] = onColorDynamicColor.getArgb(scheme);
-    customVars[`${colorname}Container`] = containerDynamicColor.getArgb(scheme);
-    customVars[`on${upperFirst2(colorname)}Container`] = onContainerDynamicColor.getArgb(scheme);
+    )
+  };
+}
+function mergeBaseAndCustomColors(scheme, customColorRoles) {
+  const baseVars = toRecord(tokenNames, (tokenName) => {
+    const dynamicColor = MaterialDynamicColors2[tokenName];
+    const argb = dynamicColor.getArgb(scheme);
+    return [tokenName, argb];
   });
+  const customVars = {};
+  for (const roles of Object.values(customColorRoles)) {
+    for (const [tokenName, dynamicColor] of Object.entries(roles)) {
+      customVars[tokenName] = dynamicColor.getArgb(scheme);
+    }
+  }
   return { ...baseVars, ...customVars };
 }
 function createColorPalette(colorDef, baseScheme, effectiveSourceForHarmonization) {
@@ -985,7 +933,17 @@ function createColorPalette(colorDef, baseScheme, effectiveSourceForHarmonizatio
   } else {
     targetChroma = baseScheme.primaryPalette.chroma;
   }
-  return TonalPalette2.fromHueAndChroma(hct.hue, targetChroma);
+  return TonalPalette.fromHueAndChroma(hct.hue, targetChroma);
+}
+function buildRefPalettes(allPalettes) {
+  const refPalettes = {};
+  for (const [name, palette] of Object.entries(allPalettes)) {
+    refPalettes[kebabCase4(name)] = STANDARD_TONES.map((tone) => ({
+      tone,
+      argb: palette.tone(tone)
+    }));
+  }
+  return refPalettes;
 }
 function buildTokenToPaletteMap(schemePalettes, scheme) {
   const result = {};
@@ -1014,7 +972,7 @@ function builder(hexSource, {
   neutral,
   neutralVariant,
   error,
-  customColors: hexCustomColors = DEFAULT_CUSTOM_COLORS,
+  customColors: customColorInputs = DEFAULT_CUSTOM_COLORS,
   prefix = DEFAULT_PREFIX
 } = {}) {
   const cores = {
@@ -1025,9 +983,12 @@ function builder(hexSource, {
     neutral: optionalHex(neutral),
     neutralVariant: optionalHex(neutralVariant)
   };
-  assertHexInputs(hexSource, cores, hexCustomColors);
+  assertHexInputs(hexSource, cores, customColorInputs);
+  const hexCustomColors = customColorInputs.map((c) => ({
+    ...c,
+    blend: c.blend ?? DEFAULT_BLEND
+  }));
   const sourceArgb = argbFromHex2(hexSource);
-  const sourceHct = Hct2.fromInt(sourceArgb);
   const effectiveSource = cores.primary || hexSource;
   const effectiveSourceArgb = argbFromHex2(effectiveSource);
   const effectiveSourceForHarmonization = cores.primary ? argbFromHex2(cores.primary) : sourceArgb;
@@ -1118,18 +1079,21 @@ function builder(hexSource, {
   };
   const customColors = definedColors.filter((c) => !c.core).map((c) => ({
     name: c.name,
-    blend: c.blend ?? DEFAULT_BLEND,
     value: argbFromHex2(c.hex)
   }));
+  const customColorRoles = Object.fromEntries(
+    customColors.map((color) => [
+      color.name,
+      buildCustomColorRoles(color.name, getPalette(colorPalettes, color.name))
+    ])
+  );
   const mergedColorsLight = mergeBaseAndCustomColors(
     lightScheme,
-    customColors,
-    colorPalettes
+    customColorRoles
   );
   const mergedColorsDark = mergeBaseAndCustomColors(
     darkScheme,
-    customColors,
-    colorPalettes
+    customColorRoles
   );
   const schemePalettes = [
     ["primary", lightScheme.primaryPalette],
@@ -1140,6 +1104,7 @@ function builder(hexSource, {
     ["neutral-variant", lightScheme.neutralVariantPalette]
   ];
   const tokenToPalette = buildTokenToPaletteMap(schemePalettes, lightScheme);
+  const refPalettes = buildRefPalettes(allPalettes);
   const allPaletteNamesKebab = new Set(Object.keys(allPalettes).map(kebabCase4));
   const ctx = {
     hexSource,
@@ -1152,11 +1117,11 @@ function builder(hexSource, {
     neutralVariant,
     error,
     hexCustomColors,
-    sourceHct,
     effectiveSourceArgb,
     primaryHct,
     SchemeClass,
     allPalettes,
+    refPalettes,
     mergedColorsLight,
     mergedColorsDark,
     tokenToPalette,
@@ -1174,7 +1139,8 @@ function builder(hexSource, {
     toFlutter: () => buildFlutter(ctx),
     mergedColorsLight,
     mergedColorsDark,
-    allPalettes
+    allPalettes,
+    customColorRoles
   };
 }
 export {

package/dist/react.d.ts

@@ -134,8 +134,13 @@ declare const tokenDescriptions: {
 type TokenName = keyof typeof tokenDescriptions;
 
 /** A custom color defined with a hex string instead of an ARGB integer. */
-type HexCustomColor = Omit<CustomColor, "value"> & {
+type HexCustomColor = Omit<CustomColor, "value" | "blend"> & {
     hex: string;
+    /**
+     * Harmonize the color with the source (or `primary`, when given) -- "Harmonize"
+     * in Material Theme Builder. Default: `DEFAULT_BLEND` (true).
+     */
+    blend?: boolean;
 };
 /** Available Material You color scheme variants. */
 declare const schemeNames: readonly ["tonalSpot", "monochrome", "neutral", "vibrant", "expressive", "fidelity", "content"];

package/dist/react.js

@@ -3333,19 +3333,17 @@ import {
   SchemeNeutral,
   SchemeTonalSpot,
   SchemeVibrant,
-  TonalPalette as TonalPalette2
+  TonalPalette
 } from "@material/material-color-utilities";
 import { kebabCase as kebabCase4, upperFirst as upperFirst2 } from "lodash-es";
 
 // src/lib/builder.css.ts
-import {
-  hexFromArgb
-} from "@material/material-color-utilities";
+import { hexFromArgb } from "@material/material-color-utilities";
 import { kebabCase } from "lodash-es";
 function buildCss(ctx) {
   const {
     prefix,
-    allPalettes,
+    refPalettes,
     mergedColorsLight,
     mergedColorsDark,
     tokenToPalette,
@@ -3353,10 +3351,9 @@ function buildCss(ctx) {
   } = ctx;
   function buildRefPaletteLookup() {
     const lookup = {};
-    for (const [name, palette] of Object.entries(allPalettes)) {
-      const paletteName = kebabCase(name);
-      for (const tone of STANDARD_TONES) {
-        const hex = hexFromArgb(palette.tone(tone));
+    for (const [paletteName, tones] of Object.entries(refPalettes)) {
+      for (const { tone, argb } of tones) {
+        const hex = hexFromArgb(argb);
         if (!lookup[hex]) lookup[hex] = [];
         lookup[hex].push({ paletteName, tone });
       }
@@ -3384,15 +3381,12 @@ function buildCss(ctx) {
     const value = hexFromArgb(colorValue);
     return `${name}:${value};`;
   }
-  function generateTonalPaletteVars(paletteName, palette) {
-    return STANDARD_TONES.map((tone) => {
-      const color = palette.tone(tone);
-      return refPaletteVar(paletteName, tone, color);
-    }).join(" ");
+  function generateTonalPaletteVars(paletteName, tones) {
+    return tones.map(({ tone, argb }) => refPaletteVar(paletteName, tone, argb)).join(" ");
   }
   function generateTonalVars() {
-    return Object.entries(allPalettes).map(
-      ([name, palette]) => generateTonalPaletteVars(kebabCase(name), palette)
+    return Object.entries(refPalettes).map(
+      ([paletteName, tones]) => generateTonalPaletteVars(paletteName, tones)
     ).join(" ");
   }
   const refPaletteLookup = buildRefPaletteLookup();
@@ -3694,29 +3688,8 @@ import {
   DynamicScheme,
   Hct,
   hexFromArgb as hexFromArgb4,
-  MaterialDynamicColors,
-  TonalPalette
+  MaterialDynamicColors
 } from "@material/material-color-utilities";
-var MTB_TONES = [
-  0,
-  5,
-  10,
-  15,
-  20,
-  25,
-  30,
-  35,
-  40,
-  50,
-  60,
-  70,
-  80,
-  90,
-  95,
-  98,
-  99,
-  100
-];
 var FIXTURE_TOKEN_ORDER = [
   "primary",
   "surfaceTint",
@@ -3771,7 +3744,6 @@ var FIXTURE_TOKEN_ORDER = [
 function buildJson(ctx) {
   const {
     hexSource,
-    sourceHct,
     effectiveSourceArgb,
     primaryHct,
     SchemeClass,
@@ -3782,34 +3754,16 @@ function buildJson(ctx) {
     error,
     neutral,
     neutralVariant,
-    hexCustomColors
+    hexCustomColors,
+    refPalettes
   } = ctx;
-  const neuHct = neutral ? Hct.fromInt(argbFromHex(neutral)) : sourceHct;
-  const nvHct = neutralVariant ? Hct.fromInt(argbFromHex(neutralVariant)) : sourceHct;
-  const rawPalettes = {
-    primary: TonalPalette.fromInt(effectiveSourceArgb),
-    secondary: secondary ? TonalPalette.fromInt(argbFromHex(secondary)) : TonalPalette.fromHueAndChroma(sourceHct.hue, sourceHct.chroma / 3),
-    tertiary: tertiary ? TonalPalette.fromInt(argbFromHex(tertiary)) : TonalPalette.fromHueAndChroma(
-      (sourceHct.hue + 60) % 360,
-      sourceHct.chroma / 2
-    ),
-    neutral: TonalPalette.fromHueAndChroma(
-      neuHct.hue,
-      Math.min(neuHct.chroma / 12, 4)
-    ),
-    "neutral-variant": TonalPalette.fromHueAndChroma(
-      nvHct.hue,
-      Math.min(nvHct.chroma / 6, 8)
-    )
-  };
   function buildJsonSchemes() {
-    function extractSchemeColors(scheme2, backgroundScheme) {
+    function extractSchemeColors(scheme2) {
       const colors = {};
       for (const tokenName of FIXTURE_TOKEN_ORDER) {
         const dynamicColor = MaterialDynamicColors[tokenName];
-        const useScheme = backgroundScheme && (tokenName === "background" || tokenName === "onBackground") ? backgroundScheme : scheme2;
         colors[tokenName] = hexFromArgb4(
-          dynamicColor.getArgb(useScheme)
+          dynamicColor.getArgb(scheme2)
         ).toUpperCase();
       }
       return colors;
@@ -3849,26 +3803,18 @@ function buildJson(ctx) {
         neutralVariantPalette: nvPalette || baseScheme.neutralVariantPalette
       });
       if (errPalette) composedScheme.errorPalette = errPalette;
-      jsonSchemes[name] = extractSchemeColors(composedScheme, baseScheme);
+      jsonSchemes[name] = extractSchemeColors(composedScheme);
     }
     return jsonSchemes;
   }
-  function rawPalettesToJson() {
+  function refPalettesToJson() {
     const jsonPalettes = {};
-    const RAW_PALETTE_NAMES = [
-      "primary",
-      "secondary",
-      "tertiary",
-      "neutral",
-      "neutral-variant"
-    ];
-    for (const name of RAW_PALETTE_NAMES) {
-      const palette = rawPalettes[name];
-      const tones = {};
-      for (const tone of MTB_TONES) {
-        tones[tone.toString()] = hexFromArgb4(palette.tone(tone)).toUpperCase();
+    for (const [name, tones] of Object.entries(refPalettes)) {
+      const jsonTones = {};
+      for (const { tone, argb } of tones) {
+        jsonTones[tone.toString()] = hexFromArgb4(argb).toUpperCase();
       }
-      jsonPalettes[name] = tones;
+      jsonPalettes[name] = jsonTones;
     }
     return jsonPalettes;
   }
@@ -3895,14 +3841,14 @@ function buildJson(ctx) {
     name: c.name,
     color: c.hex.toUpperCase(),
     description: "",
-    harmonized: c.blend ?? DEFAULT_BLEND
+    harmonized: c.blend
   }));
   return {
     seed,
     coreColors,
     extendedColors,
     schemes: buildJsonSchemes(),
-    palettes: rawPalettesToJson()
+    palettes: refPalettesToJson()
   };
 }
 
@@ -4242,51 +4188,53 @@ function getPalette(palettes, colorName) {
   }
   return palette;
 }
-function mergeBaseAndCustomColors(scheme, customColors, colorPalettes) {
-  const baseVars = toRecord(tokenNames, (tokenName) => {
-    const dynamicColor = MaterialDynamicColors2[tokenName];
-    const argb = dynamicColor.getArgb(scheme);
-    return [tokenName, argb];
-  });
-  const customVars = {};
-  customColors.forEach((color) => {
-    const colorname = color.name;
-    const getPaletteForColor = () => getPalette(colorPalettes, colorname);
-    const colorDynamicColor = new DynamicColor(
+function buildCustomColorRoles(colorname, palette) {
+  const getPaletteForColor = () => palette;
+  return {
+    [colorname]: new DynamicColor(
       colorname,
       getPaletteForColor,
       (s) => s.isDark ? 80 : 40,
       // Main color: lighter in dark mode, darker in light mode
       true
       // background
-    );
-    const onColorDynamicColor = new DynamicColor(
+    ),
+    [`on${upperFirst2(colorname)}`]: new DynamicColor(
       `on${upperFirst2(colorname)}`,
       getPaletteForColor,
       (s) => s.isDark ? 20 : 100,
       // Text on main color: high contrast (dark on light, light on dark)
       false
-    );
-    const containerDynamicColor = new DynamicColor(
+    ),
+    [`${colorname}Container`]: new DynamicColor(
       `${colorname}Container`,
       getPaletteForColor,
       (s) => s.isDark ? 30 : 90,
       // Container: subtle variant (darker in dark mode, lighter in light mode)
       true
       // background
-    );
-    const onContainerDynamicColor = new DynamicColor(
+    ),
+    [`on${upperFirst2(colorname)}Container`]: new DynamicColor(
       `on${upperFirst2(colorname)}Container`,
       getPaletteForColor,
       (s) => s.isDark ? 90 : 30,
       // Text on container: high contrast against container background
       false
-    );
-    customVars[colorname] = colorDynamicColor.getArgb(scheme);
-    customVars[`on${upperFirst2(colorname)}`] = onColorDynamicColor.getArgb(scheme);
-    customVars[`${colorname}Container`] = containerDynamicColor.getArgb(scheme);
-    customVars[`on${upperFirst2(colorname)}Container`] = onContainerDynamicColor.getArgb(scheme);
+    )
+  };
+}
+function mergeBaseAndCustomColors(scheme, customColorRoles) {
+  const baseVars = toRecord(tokenNames, (tokenName) => {
+    const dynamicColor = MaterialDynamicColors2[tokenName];
+    const argb = dynamicColor.getArgb(scheme);
+    return [tokenName, argb];
   });
+  const customVars = {};
+  for (const roles of Object.values(customColorRoles)) {
+    for (const [tokenName, dynamicColor] of Object.entries(roles)) {
+      customVars[tokenName] = dynamicColor.getArgb(scheme);
+    }
+  }
   return { ...baseVars, ...customVars };
 }
 function createColorPalette(colorDef, baseScheme, effectiveSourceForHarmonization) {
@@ -4305,7 +4253,17 @@ function createColorPalette(colorDef, baseScheme, effectiveSourceForHarmonizatio
   } else {
     targetChroma = baseScheme.primaryPalette.chroma;
   }
-  return TonalPalette2.fromHueAndChroma(hct.hue, targetChroma);
+  return TonalPalette.fromHueAndChroma(hct.hue, targetChroma);
+}
+function buildRefPalettes(allPalettes) {
+  const refPalettes = {};
+  for (const [name, palette] of Object.entries(allPalettes)) {
+    refPalettes[kebabCase4(name)] = STANDARD_TONES.map((tone) => ({
+      tone,
+      argb: palette.tone(tone)
+    }));
+  }
+  return refPalettes;
 }
 function buildTokenToPaletteMap(schemePalettes, scheme) {
   const result = {};
@@ -4334,7 +4292,7 @@ function builder(hexSource, {
   neutral,
   neutralVariant,
   error,
-  customColors: hexCustomColors = DEFAULT_CUSTOM_COLORS,
+  customColors: customColorInputs = DEFAULT_CUSTOM_COLORS,
   prefix = DEFAULT_PREFIX
 } = {}) {
   const cores = {
@@ -4345,9 +4303,12 @@ function builder(hexSource, {
     neutral: optionalHex(neutral),
     neutralVariant: optionalHex(neutralVariant)
   };
-  assertHexInputs(hexSource, cores, hexCustomColors);
+  assertHexInputs(hexSource, cores, customColorInputs);
+  const hexCustomColors = customColorInputs.map((c) => ({
+    ...c,
+    blend: c.blend ?? DEFAULT_BLEND
+  }));
   const sourceArgb = argbFromHex2(hexSource);
-  const sourceHct = Hct2.fromInt(sourceArgb);
   const effectiveSource = cores.primary || hexSource;
   const effectiveSourceArgb = argbFromHex2(effectiveSource);
   const effectiveSourceForHarmonization = cores.primary ? argbFromHex2(cores.primary) : sourceArgb;
@@ -4438,18 +4399,21 @@ function builder(hexSource, {
   };
   const customColors = definedColors.filter((c) => !c.core).map((c) => ({
     name: c.name,
-    blend: c.blend ?? DEFAULT_BLEND,
     value: argbFromHex2(c.hex)
   }));
+  const customColorRoles = Object.fromEntries(
+    customColors.map((color) => [
+      color.name,
+      buildCustomColorRoles(color.name, getPalette(colorPalettes, color.name))
+    ])
+  );
   const mergedColorsLight = mergeBaseAndCustomColors(
     lightScheme,
-    customColors,
-    colorPalettes
+    customColorRoles
   );
   const mergedColorsDark = mergeBaseAndCustomColors(
     darkScheme,
-    customColors,
-    colorPalettes
+    customColorRoles
   );
   const schemePalettes = [
     ["primary", lightScheme.primaryPalette],
@@ -4460,6 +4424,7 @@ function builder(hexSource, {
     ["neutral-variant", lightScheme.neutralVariantPalette]
   ];
   const tokenToPalette = buildTokenToPaletteMap(schemePalettes, lightScheme);
+  const refPalettes = buildRefPalettes(allPalettes);
   const allPaletteNamesKebab = new Set(Object.keys(allPalettes).map(kebabCase4));
   const ctx = {
     hexSource,
@@ -4472,11 +4437,11 @@ function builder(hexSource, {
     neutralVariant,
     error,
     hexCustomColors,
-    sourceHct,
     effectiveSourceArgb,
     primaryHct,
     SchemeClass,
     allPalettes,
+    refPalettes,
     mergedColorsLight,
     mergedColorsDark,
     tokenToPalette,
@@ -4494,7 +4459,8 @@ function builder(hexSource, {
     toFlutter: () => buildFlutter(ctx),
     mergedColorsLight,
     mergedColorsDark,
-    allPalettes
+    allPalettes,
+    customColorRoles
   };
 }
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "material-theme-builder",
-  "version": "5.0.0",
+  "version": "5.1.0",
   "description": "m3 color-system for JS/TS ecosystem",
   "keywords": [
     "react",