material-theme-builder 4.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
@@ -153,19 +165,18 @@ return (
 
 ## Tailwind
 
-Compatible through [theme variables](https://tailwindcss.com/docs/theme) — a
-stylesheet for the standard tokens, and a plugin for the custom colors:
+Compatible through [theme variables](https://tailwindcss.com/docs/theme) — one
+plugin, one line:
 
 ```css
 @import "tailwindcss";
 
-@import "material-theme-builder/tailwind.css";
 @plugin "material-theme-builder/tailwind" {
   custom-colors: myCustomColor1, myCustomColor2;
 }
 ```
 
-Drop the `@plugin` line if you have no custom colors.
+Drop the `custom-colors` block if you have none.
 
 <details>
 
@@ -193,27 +204,16 @@ Each name listed brings its four scheme roles and eleven shades —
 > of a nested `<Mtb>`.
 
 <details>
-<summary>The theme variables the stylesheet declares</summary>
-
-Generated from [`toTailwind()`](#programmatic-api), so the two cannot drift:
+<summary>The names it declares</summary>
 
-```css
-@theme inline {
-  --color-background: var(--md-sys-color-background);
-  --color-error: var(--md-sys-color-error);
-  --color-error-container: var(--md-sys-color-error-container);
-  --color-inverse-on-surface: var(--md-sys-color-inverse-on-surface);
-  --color-inverse-primary: var(--md-sys-color-inverse-primary);
-  --color-inverse-surface: var(--md-sys-color-inverse-surface);
-  --color-on-background: var(--md-sys-color-on-background);
-  --color-on-error: var(--md-sys-color-on-error);
-  /* ... */
-}
-```
+115 standard ones — every M3 scheme token (`bg-surface-container-low`,
+`text-on-primary`, `border-outline-variant`…), plus eleven Tailwind shades for
+each of `primary`, `secondary`, `tertiary`, `error`, `neutral` and
+`neutral-variant` (`bg-primary-300`). Then four roles and eleven shades per
+custom color you name.
 
-115 names in all — every M3 scheme token, plus eleven Tailwind shades for each
-of `primary`, `secondary`, `tertiary`, `error`, `neutral` and
-`neutral-variant`.
+They are theme _defaults_, so an `@theme` block of your own wins over them
+whatever the order. See [shadcn](#shadcn), where three names collide.
 
 </details>
 
@@ -233,9 +233,8 @@ In your
 @import "shadcn/tailwind.css";
 
 /* 👇🏻 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) */
+@plugin "material-theme-builder/tailwind" { /* the M3 tw classNames (optional) */
   custom-colors: myCustomColor1, myCustomColor2;
 }
 /* 👆🏻 ADD THIS 👆🏻 */
@@ -265,10 +264,10 @@ 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.
 
-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.
+The `@plugin` line is optional. It is the [Tailwind](#tailwind) recipe
+unchanged, and what it adds is names to write yourself —
+`bg-surface-container-low`, `text-on-primary`, your custom colors. Drop it and
+every shadcn component still follows the theme.
 
 For the opposite trade — concrete `oklch()` values and no `var()` at all, frozen
 at build time — see [`toShadcn()`](#programmatic-api).
@@ -282,8 +281,9 @@ at build time — see [`toShadcn()`](#programmatic-api).
 > certainly do not need to care.
 
 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:
+`primary`, `secondary`. The plugin's colors are theme defaults, so on those
+three shadcn's `@theme inline` wins, and the utility goes through the mapping
+above:
 
 ```
 bg-secondary → --color-secondary → var(--secondary) → var(--md-sys-color-secondary-container)
@@ -506,18 +506,17 @@ $ pnpm run lgtm
 ## CONTRIBUTING
 
 ```bash
-pnpm run storybook # the day-to-day loop -- no build needed, the stylesheets regenerate as you edit
-pnpm run build     # dist/, plus the generated stylesheets -- both gitignored
+pnpm run storybook # the day-to-day loop -- no build needed, `shadcn.css` regenerates as you edit
+pnpm run build     # dist/, plus the generated files -- all gitignored
 pnpm run lgtm      # everything CI checks
 ```
 
-`tailwind.css`, `shadcn.css` and `registry-item.json` are generated — from
-`toTailwind()`, `toShadcnAliases()` and `toShadcnRegistryItem()` — and
-gitignored. `pnpm run build` writes them (`scripts/generate.mjs`); the two
-stylesheets also get a `src/` copy, which is what Storybook `@import`s, and in
-Storybook a Vite plugin (`.storybook/main.ts`) rewrites those at server start
-and again on every edit under `src/lib/`, so the stories never show a stale
-vocabulary.
+`shadcn.css` and `registry-item.json` are generated — from `toShadcnAliases()`
+and `toShadcnRegistryItem()` — and gitignored. `pnpm run build` writes them
+(`scripts/generate.mjs`); `shadcn.css` also gets a `src/` copy, which is what
+Storybook `@import`s, and in Storybook a Vite plugin (`.storybook/main.ts`)
+rewrites it at server start and again on every edit under `src/lib/`, so the
+stories never show a stale vocabulary.
 
 `generate.mjs` builds the registry item without `{ fallback: true }`, which is
 what keeps every one of those outputs a function of the _mapping_ rather than of

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