material-theme-builder 2.1.0

package/dist/cli.js

@@ -0,0 +1,828 @@
+#!/usr/bin/env node
+
+// src/cli.ts
+import * as fs from "fs";
+import * as path from "path";
+import { Command, Option } from "commander";
+
+// src/lib/builder.ts
+import {
+  argbFromHex,
+  Blend,
+  blueFromArgb,
+  DynamicColor,
+  DynamicScheme,
+  greenFromArgb,
+  Hct,
+  hexFromArgb,
+  MaterialDynamicColors,
+  redFromArgb,
+  SchemeContent,
+  SchemeExpressive,
+  SchemeFidelity,
+  SchemeMonochrome,
+  SchemeNeutral,
+  SchemeTonalSpot,
+  SchemeVibrant,
+  TonalPalette
+} from "@material/material-color-utilities";
+import { kebabCase, startCase, upperFirst } from "lodash-es";
+var schemeNames = [
+  "tonalSpot",
+  "monochrome",
+  "neutral",
+  "vibrant",
+  "expressive",
+  "fidelity",
+  "content"
+];
+var schemesMap = {
+  tonalSpot: SchemeTonalSpot,
+  monochrome: SchemeMonochrome,
+  neutral: SchemeNeutral,
+  vibrant: SchemeVibrant,
+  expressive: SchemeExpressive,
+  fidelity: SchemeFidelity,
+  content: SchemeContent
+};
+var DEFAULT_SCHEME = "tonalSpot";
+var DEFAULT_CONTRAST = 0;
+var DEFAULT_CUSTOM_COLORS = [];
+var DEFAULT_BLEND = true;
+var DEFAULT_PREFIX = "md";
+var STANDARD_TONES = [
+  0,
+  4,
+  5,
+  6,
+  10,
+  12,
+  15,
+  17,
+  20,
+  22,
+  24,
+  25,
+  30,
+  35,
+  40,
+  50,
+  60,
+  70,
+  80,
+  87,
+  90,
+  92,
+  94,
+  95,
+  96,
+  98,
+  99,
+  100
+];
+var MTB_TONES = [
+  0,
+  5,
+  10,
+  15,
+  20,
+  25,
+  30,
+  35,
+  40,
+  50,
+  60,
+  70,
+  80,
+  90,
+  95,
+  98,
+  99,
+  100
+];
+var Variant = {
+  MONOCHROME: 0,
+  NEUTRAL: 1,
+  TONAL_SPOT: 2,
+  VIBRANT: 3,
+  EXPRESSIVE: 4,
+  FIDELITY: 5,
+  CONTENT: 6,
+  RAINBOW: 7,
+  FRUIT_SALAD: 8
+};
+var schemeToVariant = {
+  monochrome: Variant.MONOCHROME,
+  neutral: Variant.NEUTRAL,
+  tonalSpot: Variant.TONAL_SPOT,
+  vibrant: Variant.VIBRANT,
+  expressive: Variant.EXPRESSIVE,
+  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."
+};
+var tokenNames = Object.keys(
+  tokenDescriptions
+);
+function toRecord(arr, getEntry) {
+  return Object.fromEntries(arr.map(getEntry));
+}
+function getPalette(palettes, colorName) {
+  const palette = palettes[colorName];
+  if (!palette) {
+    throw new Error(
+      `Custom color palette not found for '${colorName}'. This is likely a bug in the implementation.`
+    );
+  }
+  return palette;
+}
+function mergeBaseAndCustomColors(scheme, customColors, colorPalettes) {
+  const baseVars = toRecord(tokenNames, (tokenName) => {
+    const dynamicColor = MaterialDynamicColors[tokenName];
+    const argb = dynamicColor.getArgb(scheme);
+    return [tokenName, argb];
+  });
+  const customVars = {};
+  customColors.forEach((color) => {
+    const colorname = color.name;
+    const getPaletteForColor = (s) => getPalette(colorPalettes, colorname);
+    const getTone = (baseTone) => (_s) => {
+      return baseTone;
+    };
+    const colorDynamicColor = new DynamicColor(
+      colorname,
+      getPaletteForColor,
+      (s) => getTone(s.isDark ? 80 : 40)(s),
+      // Main color: lighter in dark mode, darker in light mode
+      true
+      // background
+    );
+    const onColorDynamicColor = new DynamicColor(
+      `on${upperFirst(colorname)}`,
+      getPaletteForColor,
+      (s) => getTone(s.isDark ? 20 : 100)(s),
+      // Text on main color: high contrast (dark on light, light on dark)
+      false
+    );
+    const containerDynamicColor = new DynamicColor(
+      `${colorname}Container`,
+      getPaletteForColor,
+      (s) => getTone(s.isDark ? 30 : 90)(s),
+      // Container: subtle variant (darker in dark mode, lighter in light mode)
+      true
+      // background
+    );
+    const onContainerDynamicColor = new DynamicColor(
+      `on${upperFirst(colorname)}Container`,
+      getPaletteForColor,
+      (s) => getTone(s.isDark ? 90 : 30)(s),
+      // Text on container: high contrast against container background
+      false
+    );
+    customVars[colorname] = colorDynamicColor.getArgb(scheme);
+    customVars[`on${upperFirst(colorname)}`] = onColorDynamicColor.getArgb(scheme);
+    customVars[`${colorname}Container`] = containerDynamicColor.getArgb(scheme);
+    customVars[`on${upperFirst(colorname)}Container`] = onContainerDynamicColor.getArgb(scheme);
+  });
+  return { ...baseVars, ...customVars };
+}
+function createColorPalette(colorDef, baseScheme, effectiveSourceForHarmonization) {
+  const colorArgb = argbFromHex(colorDef.hex);
+  const harmonizedArgb = colorDef.blend ? Blend.harmonize(colorArgb, effectiveSourceForHarmonization) : colorArgb;
+  const hct = Hct.fromInt(harmonizedArgb);
+  let targetChroma;
+  if (colorDef.core && colorDef.chromaSource) {
+    if (colorDef.chromaSource === "neutral") {
+      targetChroma = baseScheme.neutralPalette.chroma;
+    } else if (colorDef.chromaSource === "neutralVariant") {
+      targetChroma = baseScheme.neutralVariantPalette.chroma;
+    } else {
+      targetChroma = baseScheme.primaryPalette.chroma;
+    }
+  } else {
+    targetChroma = baseScheme.primaryPalette.chroma;
+  }
+  return TonalPalette.fromHueAndChroma(hct.hue, targetChroma);
+}
+function builder(hexSource, {
+  scheme = DEFAULT_SCHEME,
+  contrast = DEFAULT_CONTRAST,
+  primary,
+  secondary,
+  tertiary,
+  neutral,
+  neutralVariant,
+  error,
+  customColors: hexCustomColors = DEFAULT_CUSTOM_COLORS,
+  prefix = DEFAULT_PREFIX
+} = {}) {
+  const sourceArgb = argbFromHex(hexSource);
+  const sourceHct = Hct.fromInt(sourceArgb);
+  const effectiveSource = primary || hexSource;
+  const effectiveSourceArgb = argbFromHex(effectiveSource);
+  const effectiveSourceForHarmonization = primary ? argbFromHex(primary) : sourceArgb;
+  const SchemeClass = schemesMap[scheme];
+  const primaryHct = Hct.fromInt(effectiveSourceArgb);
+  const baseScheme = new SchemeClass(primaryHct, false, contrast);
+  const allColors = [
+    // Core colors (hex may be undefined)
+    {
+      name: "primary",
+      hex: primary,
+      core: true,
+      chromaSource: "primary"
+    },
+    {
+      name: "secondary",
+      hex: secondary,
+      core: true,
+      chromaSource: "primary"
+    },
+    {
+      name: "tertiary",
+      hex: tertiary,
+      core: true,
+      chromaSource: "primary"
+    },
+    { name: "error", hex: error, core: true, chromaSource: "primary" },
+    {
+      name: "neutral",
+      hex: neutral,
+      core: true,
+      chromaSource: "neutral"
+    },
+    {
+      name: "neutralVariant",
+      hex: neutralVariant,
+      core: true,
+      chromaSource: "neutralVariant"
+    },
+    //
+    // Custom colors
+    //
+    ...hexCustomColors.map((c) => ({
+      name: c.name,
+      hex: c.hex,
+      blend: c.blend,
+      core: false
+    }))
+  ];
+  const definedColors = allColors.filter(
+    (c) => c.hex !== void 0
+  );
+  const colorPalettes = Object.fromEntries(
+    definedColors.map((colorDef) => [
+      colorDef.name,
+      createColorPalette(colorDef, baseScheme, effectiveSourceForHarmonization)
+    ])
+  );
+  const variant = schemeToVariant[scheme];
+  const schemeConfig = {
+    sourceColorArgb: effectiveSourceArgb,
+    variant,
+    contrastLevel: contrast,
+    primaryPalette: colorPalettes["primary"] || baseScheme.primaryPalette,
+    secondaryPalette: colorPalettes["secondary"] || baseScheme.secondaryPalette,
+    tertiaryPalette: colorPalettes["tertiary"] || baseScheme.tertiaryPalette,
+    neutralPalette: colorPalettes["neutral"] || baseScheme.neutralPalette,
+    neutralVariantPalette: colorPalettes["neutralVariant"] || baseScheme.neutralVariantPalette
+  };
+  const lightScheme = new DynamicScheme({ ...schemeConfig, isDark: false });
+  const darkScheme = new DynamicScheme({ ...schemeConfig, isDark: true });
+  const errorPalette = colorPalettes["error"];
+  if (errorPalette) {
+    lightScheme.errorPalette = errorPalette;
+    darkScheme.errorPalette = errorPalette;
+  }
+  const allPalettes = {
+    primary: lightScheme.primaryPalette,
+    secondary: lightScheme.secondaryPalette,
+    tertiary: lightScheme.tertiaryPalette,
+    error: lightScheme.errorPalette,
+    neutral: lightScheme.neutralPalette,
+    "neutral-variant": lightScheme.neutralVariantPalette,
+    // Add custom color palettes
+    ...Object.fromEntries(
+      definedColors.filter((c) => !c.core).map((colorDef) => [colorDef.name, colorPalettes[colorDef.name]])
+    )
+  };
+  const customColors = definedColors.filter((c) => !c.core).map((c) => ({
+    name: c.name,
+    blend: c.blend ?? DEFAULT_BLEND,
+    value: argbFromHex(c.hex)
+  }));
+  const mergedColorsLight = mergeBaseAndCustomColors(
+    lightScheme,
+    customColors,
+    colorPalettes
+  );
+  const mergedColorsDark = mergeBaseAndCustomColors(
+    darkScheme,
+    customColors,
+    colorPalettes
+  );
+  const schemePalettes = [
+    ["primary", lightScheme.primaryPalette],
+    ["secondary", lightScheme.secondaryPalette],
+    ["tertiary", lightScheme.tertiaryPalette],
+    ["error", lightScheme.errorPalette],
+    ["neutral", lightScheme.neutralPalette],
+    ["neutral-variant", lightScheme.neutralVariantPalette]
+  ];
+  function buildTokenToPaletteMap(schemePalettes2, scheme2) {
+    const result = {};
+    for (const propName of Object.getOwnPropertyNames(MaterialDynamicColors)) {
+      const dc = MaterialDynamicColors[propName];
+      if (!(dc instanceof DynamicColor)) continue;
+      const palette = dc.palette(scheme2);
+      for (const [palName, pal] of schemePalettes2) {
+        if (palette === pal) {
+          result[propName] = palName;
+          break;
+        }
+      }
+    }
+    return result;
+  }
+  const tokenToPalette = buildTokenToPaletteMap(schemePalettes, lightScheme);
+  const allPaletteNamesKebab = new Set(Object.keys(allPalettes).map(kebabCase));
+  function deriveCustomPaletteName(tokenName) {
+    let baseName = tokenName;
+    if (/^on[A-Z]/.test(baseName) && baseName.length > 2) {
+      baseName = baseName.charAt(2).toLowerCase() + baseName.slice(3);
+    }
+    if (baseName.endsWith("Container")) {
+      baseName = baseName.slice(0, -"Container".length);
+    }
+    const kebab = kebabCase(baseName);
+    return allPaletteNamesKebab.has(kebab) ? kebab : void 0;
+  }
+  return {
+    //
+    //  ██████ ███████ ███████
+    // ██      ██      ██
+    // ██      ███████ ███████
+    // ██           ██      ██
+    //  ██████ ███████ ███████
+    //
+    toCss() {
+      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));
+            if (!lookup[hex]) lookup[hex] = [];
+            lookup[hex].push({ paletteName, tone });
+          }
+        }
+        return lookup;
+      }
+      function sysColorVar(colorName, colorValue, lookup) {
+        const name = `--${prefix}-sys-color-${kebabCase(colorName)}`;
+        const hex = hexFromArgb(colorValue);
+        const matches = lookup[hex];
+        if (matches && matches.length > 0) {
+          const preferred = tokenToPalette[colorName] ?? deriveCustomPaletteName(colorName);
+          const match = (preferred ? matches.find((m) => m.paletteName === preferred) : void 0) ?? matches[0];
+          return `${name}:var(--${prefix}-ref-palette-${match.paletteName}-${match.tone});`;
+        }
+        return `${name}:${hex};`;
+      }
+      function toCssVars(mergedColors, lookup) {
+        return Object.entries(mergedColors).map(([name, value]) => sysColorVar(name, value, lookup)).join(" ");
+      }
+      function refPaletteVar(paletteName, tone, colorValue) {
+        const name = `--${prefix}-ref-palette-${paletteName}-${tone}`;
+        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 generateTonalVars() {
+        return Object.entries(allPalettes).map(
+          ([name, palette]) => generateTonalPaletteVars(kebabCase(name), palette)
+        ).join(" ");
+      }
+      const refPaletteLookup = buildRefPaletteLookup();
+      const lightVars = toCssVars(mergedColorsLight, refPaletteLookup);
+      const darkVars = toCssVars(mergedColorsDark, refPaletteLookup);
+      const tonalVars = generateTonalVars();
+      return `
+:root { ${lightVars} ${tonalVars} }
+.dark { ${darkVars} ${tonalVars} }
+`;
+    },
+    //
+    //      ██ ███████  ██████  ███    ██
+    //      ██ ██      ██    ██ ████   ██
+    //      ██ ███████ ██    ██ ██ ██  ██
+    // ██   ██      ██ ██    ██ ██  ██ ██
+    //  █████  ███████  ██████  ██   ████
+    //
+    toJson() {
+      const fixtureTokenOrder = [
+        "primary",
+        "surfaceTint",
+        "onPrimary",
+        "primaryContainer",
+        "onPrimaryContainer",
+        "secondary",
+        "onSecondary",
+        "secondaryContainer",
+        "onSecondaryContainer",
+        "tertiary",
+        "onTertiary",
+        "tertiaryContainer",
+        "onTertiaryContainer",
+        "error",
+        "onError",
+        "errorContainer",
+        "onErrorContainer",
+        "background",
+        "onBackground",
+        "surface",
+        "onSurface",
+        "surfaceVariant",
+        "onSurfaceVariant",
+        "outline",
+        "outlineVariant",
+        "shadow",
+        "scrim",
+        "inverseSurface",
+        "inverseOnSurface",
+        "inversePrimary",
+        "primaryFixed",
+        "onPrimaryFixed",
+        "primaryFixedDim",
+        "onPrimaryFixedVariant",
+        "secondaryFixed",
+        "onSecondaryFixed",
+        "secondaryFixedDim",
+        "onSecondaryFixedVariant",
+        "tertiaryFixed",
+        "onTertiaryFixed",
+        "tertiaryFixedDim",
+        "onTertiaryFixedVariant",
+        "surfaceDim",
+        "surfaceBright",
+        "surfaceContainerLowest",
+        "surfaceContainerLow",
+        "surfaceContainer",
+        "surfaceContainerHigh",
+        "surfaceContainerHighest"
+      ];
+      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) {
+          const colors = {};
+          for (const tokenName of fixtureTokenOrder) {
+            const dynamicColor = MaterialDynamicColors[tokenName];
+            const useScheme = backgroundScheme && (tokenName === "background" || tokenName === "onBackground") ? backgroundScheme : scheme2;
+            colors[tokenName] = hexFromArgb(
+              dynamicColor.getArgb(useScheme)
+            ).toUpperCase();
+          }
+          return colors;
+        }
+        function resolveOverridePalette(hex, role) {
+          if (!hex) return null;
+          return new SchemeClass(Hct.fromInt(argbFromHex(hex)), false, 0)[role];
+        }
+        const secPalette = resolveOverridePalette(secondary, "primaryPalette");
+        const terPalette = resolveOverridePalette(tertiary, "primaryPalette");
+        const errPalette = resolveOverridePalette(error, "primaryPalette");
+        const neuPalette = resolveOverridePalette(neutral, "neutralPalette");
+        const nvPalette = resolveOverridePalette(
+          neutralVariant,
+          "neutralVariantPalette"
+        );
+        const jsonSchemes = {};
+        const jsonContrastLevels = [
+          { name: "light", isDark: false, contrast: 0 },
+          { name: "light-medium-contrast", isDark: false, contrast: 0.5 },
+          { name: "light-high-contrast", isDark: false, contrast: 1 },
+          { name: "dark", isDark: true, contrast: 0 },
+          { name: "dark-medium-contrast", isDark: true, contrast: 0.5 },
+          { name: "dark-high-contrast", isDark: true, contrast: 1 }
+        ];
+        for (const { name, isDark, contrast: contrast2 } of jsonContrastLevels) {
+          const baseScheme2 = new SchemeClass(primaryHct, isDark, contrast2);
+          const composedScheme = new DynamicScheme({
+            sourceColorArgb: effectiveSourceArgb,
+            variant: schemeToVariant[scheme],
+            contrastLevel: contrast2,
+            isDark,
+            primaryPalette: baseScheme2.primaryPalette,
+            secondaryPalette: secPalette || baseScheme2.secondaryPalette,
+            tertiaryPalette: terPalette || baseScheme2.tertiaryPalette,
+            neutralPalette: neuPalette || baseScheme2.neutralPalette,
+            neutralVariantPalette: nvPalette || baseScheme2.neutralVariantPalette
+          });
+          if (errPalette) composedScheme.errorPalette = errPalette;
+          jsonSchemes[name] = extractSchemeColors(composedScheme, baseScheme2);
+        }
+        return jsonSchemes;
+      }
+      function rawPalettesToJson() {
+        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()] = hexFromArgb(
+              palette.tone(tone)
+            ).toUpperCase();
+          }
+          jsonPalettes[name] = tones;
+        }
+        return jsonPalettes;
+      }
+      function buildCoreColors(opts) {
+        const colors = { primary: opts.primary };
+        if (opts.secondary) colors.secondary = opts.secondary.toUpperCase();
+        if (opts.tertiary) colors.tertiary = opts.tertiary.toUpperCase();
+        if (opts.error) colors.error = opts.error.toUpperCase();
+        if (opts.neutral) colors.neutral = opts.neutral.toUpperCase();
+        if (opts.neutralVariant)
+          colors.neutralVariant = opts.neutralVariant.toUpperCase();
+        return colors;
+      }
+      const seed = hexSource.toUpperCase();
+      const coreColors = buildCoreColors({
+        primary: (primary || hexSource).toUpperCase(),
+        secondary,
+        tertiary,
+        error,
+        neutral,
+        neutralVariant
+      });
+      const extendedColors = hexCustomColors.map((c) => ({
+        name: c.name,
+        color: c.hex.toUpperCase(),
+        description: "",
+        harmonized: c.blend ?? DEFAULT_BLEND
+      }));
+      return {
+        seed,
+        coreColors,
+        extendedColors,
+        schemes: buildJsonSchemes(),
+        palettes: rawPalettesToJson()
+      };
+    },
+    //
+    // ███████ ██  ██████  ███    ███  █████
+    // ██      ██ ██       ████  ████ ██   ██
+    // █████   ██ ██   ███ ██ ████ ██ ███████
+    // ██      ██ ██    ██ ██  ██  ██ ██   ██
+    // ██      ██  ██████  ██      ██ ██   ██
+    //
+    toFigmaTokens() {
+      function argbToFigmaColorValue(argb) {
+        return {
+          colorSpace: "srgb",
+          components: [
+            redFromArgb(argb) / 255,
+            greenFromArgb(argb) / 255,
+            blueFromArgb(argb) / 255
+          ],
+          alpha: 1,
+          hex: hexFromArgb(argb).toUpperCase()
+        };
+      }
+      function figmaToken(argb) {
+        return {
+          $type: "color",
+          $value: argbToFigmaColorValue(argb),
+          $extensions: {
+            "com.figma.scopes": ["ALL_SCOPES"],
+            "com.figma.isOverride": true
+          }
+        };
+      }
+      function buildRefPaletteTokens() {
+        const palettes = {};
+        for (const [name, palette] of Object.entries(allPalettes)) {
+          const tones = {};
+          for (const tone of STANDARD_TONES) {
+            const argb = palette.tone(tone);
+            tones[tone.toString()] = figmaToken(argb);
+          }
+          palettes[startCase(name)] = tones;
+        }
+        return palettes;
+      }
+      function findToneInPalette(hex, paletteName, tones) {
+        for (const [tone, token] of Object.entries(tones)) {
+          if (token.$value.hex === hex) {
+            return `{ref.palette.${paletteName}.${tone}}`;
+          }
+        }
+        return null;
+      }
+      function findAlias(hex, tokenName, refPalettes2) {
+        const preferredPaletteKebab = tokenToPalette[tokenName] ?? deriveCustomPaletteName(tokenName);
+        const preferredPalette = preferredPaletteKebab ? startCase(preferredPaletteKebab) : void 0;
+        if (preferredPalette && refPalettes2[preferredPalette]) {
+          const match = findToneInPalette(
+            hex,
+            preferredPalette,
+            refPalettes2[preferredPalette]
+          );
+          if (match) return match;
+        }
+        for (const [palName, tones] of Object.entries(refPalettes2)) {
+          const match = findToneInPalette(hex, palName, tones);
+          if (match) return match;
+        }
+        return null;
+      }
+      function resolveModeValue(argb, tokenName, refPalettes2) {
+        const hex = hexFromArgb(argb).toUpperCase();
+        return findAlias(hex, tokenName, refPalettes2) ?? argbToFigmaColorValue(argb);
+      }
+      function buildSysColorTokens(mergedColors, refPalettes2) {
+        const tokens = {};
+        for (const [name, argb] of Object.entries(mergedColors)) {
+          const description = tokenDescriptions[name];
+          const cssVar = `--${prefix}-sys-color-${kebabCase(name)}`;
+          const value = resolveModeValue(argb, name, refPalettes2);
+          tokens[startCase(name)] = {
+            $type: "color",
+            $value: value,
+            ...description ? { $description: description } : {},
+            $extensions: {
+              "com.figma.scopes": ["ALL_SCOPES"],
+              "css.variable": cssVar
+            }
+          };
+        }
+        return tokens;
+      }
+      const refPalettes = buildRefPaletteTokens();
+      function buildModeFile(modeName, mergedColors) {
+        return {
+          ref: {
+            palette: refPalettes
+          },
+          sys: {
+            color: buildSysColorTokens(mergedColors, refPalettes)
+          },
+          $extensions: {
+            "com.figma.modeName": modeName
+          }
+        };
+      }
+      return {
+        "Light.tokens.json": buildModeFile("Light", mergedColorsLight),
+        "Dark.tokens.json": buildModeFile("Dark", mergedColorsDark)
+      };
+    },
+    //
+    // API
+    //
+    mergedColorsLight,
+    mergedColorsDark,
+    allPalettes
+  };
+}
+
+// src/cli.ts
+var program = new Command();
+program.name("material-theme-builder").description("m3 color system");
+program.command("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)
+).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, or figma", "figma").option("--output <dir>", "Output directory (required for figma format)").option(
+  "--prefix <string>",
+  "CSS variable prefix (e.g. md \u2192 --md-sys-color-*, --md-ref-palette-*)",
+  DEFAULT_PREFIX
+).action((source, opts) => {
+  let customColors = [];
+  if (opts.customColors) {
+    try {
+      const parsed = JSON.parse(opts.customColors);
+      customColors = parsed.map((c) => ({
+        name: c.name,
+        hex: c.hex,
+        blend: c.blend ?? DEFAULT_BLEND
+      }));
+    } catch {
+      console.error("Error: --custom-colors must be valid JSON");
+      process.exit(1);
+    }
+  }
+  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
+  });
+  if (opts.format === "css") {
+    process.stdout.write(result.toCss());
+  } else if (opts.format === "figma") {
+    const outputDir = opts.output ?? "material-theme";
+    fs.mkdirSync(outputDir, { recursive: true });
+    const files = result.toFigmaTokens();
+    for (const [filename, content] of Object.entries(files)) {
+      const filePath = path.join(outputDir, filename);
+      fs.writeFileSync(filePath, JSON.stringify(content, null, 2) + "\n");
+      console.error(`wrote ${filePath}`);
+    }
+  } else {
+    process.stdout.write(JSON.stringify(result.toJson(), null, 2) + "\n");
+  }
+});
+program.parse();