react-mcu 1.2.0 → 1.3.0

package/README.md

@@ -35,6 +35,8 @@ Extra:
 
 - [x] `contrastAllColors`: contrast also applies to custom-colors and shades
       (not only the core-colors)
+- [x] `adaptiveShades`: shades adapt to the light/dark mode (instead of being
+      fixed)
 
 # Usage
 
@@ -173,6 +175,37 @@ Simply override/remap
 > Make sure `:root, .dark { ... }` comes AFTER `.root { ... } .dark { ... }` to
 > take precedence.
 
+## Programmatic API
+
+```ts
+import { builder } from "react-mcu";
+
+const theme = builder("#6750A4", {
+  scheme: "vibrant",
+  contrast: 0.5,
+  primary: "#FF0000",
+  secondary: "#00FF00",
+  customColors: [
+    { name: "brand", hex: "#FF5733", blend: true },
+    { name: "success", hex: "#28A745", blend: false },
+  ],
+  contrastAllColors: true,
+});
+
+theme.toJson();
+theme.toCss();
+```
+
+## CLI
+
+```sh
+$ npx react-mcu builder "#6750A4"
+```
+
+will generate a `mcu-theme` folder with: `Light.tokens.json` and `Dark.tokens.json` [design-tokens](https://www.designtokens.org/tr/2025.10/) files, you can (both) import into Figma.
+
+See `npx react-mcu builder --help` for all available options.
+
 # Dev
 
 ## INSTALL
@@ -198,6 +231,12 @@ Pre-requisites:
 $ pnpm i
 ```
 
+## Validation
+
+```sh
+$ pnpm run lgtm
+```
+
 ## CONTRIBUTING
 
 When submitting a pull request, please include a changeset to document your

package/dist/index.d.ts

@@ -1,5 +1,5 @@
 import * as react_jsx_runtime from 'react/jsx-runtime';
-import { SchemeTonalSpot, SchemeMonochrome, SchemeNeutral, SchemeVibrant, SchemeExpressive, SchemeFidelity, SchemeContent, CustomColor } from '@material/material-color-utilities';
+import { CustomColor, TonalPalette } from '@material/material-color-utilities';
 
 type HexCustomColor = Omit<CustomColor, "value"> & {
     hex: string;
@@ -29,7 +29,6 @@ type McuConfig = {
      * When false (default), colors may be adjusted for better harmonization.
      * Corresponds to "Color match - Stay true to my color inputs" in Material Theme Builder.
      *
-     * @default false
      * @deprecated Not yet implemented. This prop is currently ignored.
      */
     colorMatch?: boolean;
@@ -48,33 +47,127 @@ type McuConfig = {
     /**
      * When true, applies the contrast level to all colors including custom colors and tonal palette shades.
      * When false (default), only core colors are affected by the contrast level.
-     *
-     * @default false
      */
     contrastAllColors?: boolean;
+    /**
+     * When true (default), tonal palette shades adapt to the theme (light/dark) with inverted tone values.
+     * In dark mode, high tones (light colors) map to low tones (dark colors) and vice versa.
+     * When false, shades remain the same across themes.
+     */
+    adaptiveShades?: boolean;
 };
-declare const schemesMap: {
-    readonly tonalSpot: typeof SchemeTonalSpot;
-    readonly monochrome: typeof SchemeMonochrome;
-    readonly neutral: typeof SchemeNeutral;
-    readonly vibrant: typeof SchemeVibrant;
-    readonly expressive: typeof SchemeExpressive;
-    readonly fidelity: typeof SchemeFidelity;
-    readonly content: typeof SchemeContent;
-};
-declare const schemeNames: (keyof typeof schemesMap)[];
+declare const schemeNames: readonly ["tonalSpot", "monochrome", "neutral", "vibrant", "expressive", "fidelity", "content"];
 type SchemeName = (typeof schemeNames)[number];
-declare function Mcu({ source, scheme, contrast, primary, secondary, tertiary, neutral, neutralVariant, error, colorMatch, customColors, contrastAllColors, children, }: McuConfig & {
+declare const DEFAULT_SCHEME: SchemeName;
+declare const DEFAULT_CONTRAST = 0;
+declare const DEFAULT_CONTRAST_ALL_COLORS = false;
+declare const DEFAULT_ADAPTIVE_SHADES = false;
+declare const DEFAULT_BLEND = true;
+declare function Mcu({ source, scheme, contrast, primary, secondary, tertiary, neutral, neutralVariant, error, colorMatch, customColors, contrastAllColors, adaptiveShades, children, }: McuConfig & {
     children?: React.ReactNode;
 }): react_jsx_runtime.JSX.Element;
-declare const tokenNames: readonly ["background", "onBackground", "surface", "surfaceDim", "surfaceBright", "surfaceContainerLowest", "surfaceContainerLow", "surfaceContainer", "surfaceContainerHigh", "surfaceContainerHighest", "onSurface", "onSurfaceVariant", "outline", "outlineVariant", "inverseSurface", "inverseOnSurface", "primary", "onPrimary", "primaryContainer", "onPrimaryContainer", "primaryFixed", "primaryFixedDim", "onPrimaryFixed", "onPrimaryFixedVariant", "inversePrimary", "primaryFixed", "primaryFixedDim", "onPrimaryFixed", "onPrimaryFixedVariant", "secondary", "onSecondary", "secondaryContainer", "onSecondaryContainer", "secondaryFixed", "secondaryFixedDim", "onSecondaryFixed", "onSecondaryFixedVariant", "tertiary", "onTertiary", "tertiaryContainer", "onTertiaryContainer", "tertiaryFixed", "tertiaryFixedDim", "onTertiaryFixed", "onTertiaryFixedVariant", "error", "onError", "errorContainer", "onErrorContainer", "scrim", "shadow"];
+declare const tokenNames: readonly ["background", "onBackground", "surface", "surfaceDim", "surfaceBright", "surfaceContainerLowest", "surfaceContainerLow", "surfaceContainer", "surfaceContainerHigh", "surfaceContainerHighest", "onSurface", "surfaceVariant", "onSurfaceVariant", "outline", "outlineVariant", "inverseSurface", "inverseOnSurface", "primary", "surfaceTint", "onPrimary", "primaryContainer", "onPrimaryContainer", "primaryFixed", "primaryFixedDim", "onPrimaryFixed", "onPrimaryFixedVariant", "inversePrimary", "secondary", "onSecondary", "secondaryContainer", "onSecondaryContainer", "secondaryFixed", "secondaryFixedDim", "onSecondaryFixed", "onSecondaryFixedVariant", "tertiary", "onTertiary", "tertiaryContainer", "onTertiaryContainer", "tertiaryFixed", "tertiaryFixedDim", "onTertiaryFixed", "onTertiaryFixedVariant", "error", "onError", "errorContainer", "onErrorContainer", "scrim", "shadow"];
 type TokenName = (typeof tokenNames)[number];
+declare function builder(hexSource: McuConfig["source"], { scheme, contrast, primary, secondary, tertiary, neutral, neutralVariant, error, customColors: hexCustomColors, contrastAllColors, adaptiveShades, }?: Omit<McuConfig, "source">): {
+    toCss(): string;
+    toJson(): {
+        seed: string;
+        coreColors: Record<string, string>;
+        extendedColors: {
+            name: string;
+            color: string;
+            description: string;
+            harmonized: boolean;
+        }[];
+        schemes: Record<string, Record<string, string>>;
+        palettes: Record<string, Record<string, string>>;
+    };
+    toFigmaTokens(): {
+        "Light.tokens.json": {
+            Schemes: Record<string, {
+                $type: "color";
+                $value: {
+                    colorSpace: "srgb";
+                    components: number[];
+                    alpha: number;
+                    hex: string;
+                };
+                $extensions: {
+                    "com.figma.scopes": string[];
+                    "com.figma.isOverride": boolean;
+                };
+            }>;
+            Palettes: Record<string, Record<string, {
+                $type: "color";
+                $value: {
+                    colorSpace: "srgb";
+                    components: number[];
+                    alpha: number;
+                    hex: string;
+                };
+                $extensions: {
+                    "com.figma.scopes": string[];
+                    "com.figma.isOverride": boolean;
+                };
+            }>>;
+            $extensions: {
+                "com.figma.modeName": string;
+            };
+        };
+        "Dark.tokens.json": {
+            Schemes: Record<string, {
+                $type: "color";
+                $value: {
+                    colorSpace: "srgb";
+                    components: number[];
+                    alpha: number;
+                    hex: string;
+                };
+                $extensions: {
+                    "com.figma.scopes": string[];
+                    "com.figma.isOverride": boolean;
+                };
+            }>;
+            Palettes: Record<string, Record<string, {
+                $type: "color";
+                $value: {
+                    colorSpace: "srgb";
+                    components: number[];
+                    alpha: number;
+                    hex: string;
+                };
+                $extensions: {
+                    "com.figma.scopes": string[];
+                    "com.figma.isOverride": boolean;
+                };
+            }>>;
+            $extensions: {
+                "com.figma.modeName": string;
+            };
+        };
+    };
+    mergedColorsLight: {
+        [x: string]: number;
+    };
+    mergedColorsDark: {
+        [x: string]: number;
+    };
+    allPalettes: {
+        primary: TonalPalette;
+        secondary: TonalPalette;
+        tertiary: TonalPalette;
+        error: TonalPalette;
+        neutral: TonalPalette;
+        "neutral-variant": TonalPalette;
+    };
+};
 
 type Api = {
     initials: McuConfig;
     setMcuConfig: (config: McuConfig) => void;
     getMcuColor: (colorName: TokenName, theme?: string) => string;
+    allPalettes: Record<string, TonalPalette>;
 };
 declare const useMcu: () => Api;
 
-export { Mcu, useMcu };
+export { DEFAULT_ADAPTIVE_SHADES, DEFAULT_BLEND, DEFAULT_CONTRAST, DEFAULT_CONTRAST_ALL_COLORS, DEFAULT_SCHEME, Mcu, builder, schemeNames, useMcu };

package/dist/index.js

@@ -4,11 +4,14 @@
 import {
   argbFromHex,
   Blend,
+  blueFromArgb,
   DynamicColor,
   DynamicScheme,
+  greenFromArgb,
   Hct,
   hexFromArgb as hexFromArgb2,
   MaterialDynamicColors,
+  redFromArgb,
   SchemeContent,
   SchemeExpressive,
   SchemeFidelity,
@@ -18,12 +21,14 @@ import {
   SchemeVibrant,
   TonalPalette
 } from "@material/material-color-utilities";
-import { kebabCase, upperFirst } from "lodash-es";
+import { kebabCase, startCase, upperFirst } from "lodash-es";
 import { useMemo as useMemo2 } from "react";
 
 // src/Mcu.context.tsx
-import { hexFromArgb } from "@material/material-color-utilities";
 import {
+  hexFromArgb
+} from "@material/material-color-utilities";
+import React, {
   useCallback,
   useInsertionEffect,
   useMemo,
@@ -48,26 +53,20 @@ var createRequiredContext = () => {
 import { jsx } from "react/jsx-runtime";
 var [useMcu, Provider, McuContext] = createRequiredContext();
 var McuProvider = ({
-  source: initialSource,
-  scheme: initialScheme,
-  contrast: initialContrast,
-  customColors: initialCustomColors,
-  contrastAllColors: initialContrastAllColors,
   styleId,
-  children
+  children,
+  ...configProps
 }) => {
-  const [initials] = useState(() => ({
-    source: initialSource,
-    scheme: initialScheme,
-    contrast: initialContrast,
-    customColors: initialCustomColors,
-    contrastAllColors: initialContrastAllColors
-  }));
+  const [initials] = useState(() => configProps);
   const [mcuConfig, setMcuConfig] = useState(initials);
-  const { css, mergedColorsLight, mergedColorsDark } = useMemo(
-    () => generateCss(mcuConfig),
-    [mcuConfig]
-  );
+  const configKey = JSON.stringify(configProps);
+  React.useEffect(() => {
+    setMcuConfig(configProps);
+  }, [configKey]);
+  const { css, mergedColorsLight, mergedColorsDark, allPalettes } = useMemo(() => {
+    const { toCss, ...rest } = builder(mcuConfig.source, mcuConfig);
+    return { css: toCss(), ...rest };
+  }, [mcuConfig]);
   useInsertionEffect(() => {
     let tag = document.getElementById(styleId);
     if (!tag) {
@@ -79,9 +78,12 @@ var McuProvider = ({
   }, [css, styleId]);
   const getMcuColor = useCallback(
     (colorName, theme) => {
-      return hexFromArgb(
-        (theme === "light" ? mergedColorsLight : mergedColorsDark)[colorName]
-      );
+      const mergedColors = theme === "light" ? mergedColorsLight : mergedColorsDark;
+      const colorValue = mergedColors[colorName];
+      if (colorValue === void 0) {
+        throw new Error(`Unknown MCU token '${colorName}'`);
+      }
+      return hexFromArgb(colorValue);
     },
     [mergedColorsDark, mergedColorsLight]
   );
@@ -89,25 +91,32 @@ var McuProvider = ({
     () => ({
       initials,
       setMcuConfig,
-      getMcuColor
+      getMcuColor,
+      allPalettes
     }),
-    [getMcuColor, initials]
+    [getMcuColor, initials, allPalettes]
   );
   return /* @__PURE__ */ jsx(Provider, { value, children });
 };
 
 // src/Mcu.tsx
-import { Fragment, jsx as jsx2, jsxs } from "react/jsx-runtime";
-function adjustToneForContrast(baseTone, contrastLevel, isDark, adjustmentFactor = DEFAULT_CONTRAST_ADJUSTMENT_FACTOR) {
+import { jsx as jsx2 } from "react/jsx-runtime";
+function adjustToneForContrast(baseTone, contrastLevel, adjustmentFactor = DEFAULT_CONTRAST_ADJUSTMENT_FACTOR) {
   if (contrastLevel === 0) return baseTone;
-  let adjustedTone;
-  if (isDark) {
-    adjustedTone = baseTone + contrastLevel * (100 - baseTone) * adjustmentFactor;
-  } else {
-    adjustedTone = baseTone - contrastLevel * baseTone * adjustmentFactor;
-  }
+  const distanceToCenter = baseTone - 50;
+  const delta = distanceToCenter * contrastLevel * adjustmentFactor;
+  const adjustedTone = baseTone + delta;
   return Math.max(0, Math.min(100, adjustedTone));
 }
+var schemeNames = [
+  "tonalSpot",
+  "monochrome",
+  "neutral",
+  "vibrant",
+  "expressive",
+  "fidelity",
+  "content"
+];
 var schemesMap = {
   tonalSpot: SchemeTonalSpot,
   monochrome: SchemeMonochrome,
@@ -117,14 +126,12 @@ var schemesMap = {
   fidelity: SchemeFidelity,
   content: SchemeContent
 };
-var schemeNames = Object.keys(
-  schemesMap
-);
 var DEFAULT_SCHEME = "tonalSpot";
 var DEFAULT_CONTRAST = 0;
 var DEFAULT_COLOR_MATCH = false;
 var DEFAULT_CUSTOM_COLORS = [];
 var DEFAULT_CONTRAST_ALL_COLORS = false;
+var DEFAULT_ADAPTIVE_SHADES = false;
 var DEFAULT_BLEND = true;
 var DEFAULT_CONTRAST_ADJUSTMENT_FACTOR = 0.2;
 var STANDARD_TONES = [
@@ -181,6 +188,7 @@ function Mcu({
   colorMatch = DEFAULT_COLOR_MATCH,
   customColors = DEFAULT_CUSTOM_COLORS,
   contrastAllColors = DEFAULT_CONTRAST_ALL_COLORS,
+  adaptiveShades = DEFAULT_ADAPTIVE_SHADES,
   children
 }) {
   const config = useMemo2(
@@ -197,7 +205,8 @@ function Mcu({
       colorMatch,
       customColors,
       // extras features
-      contrastAllColors
+      contrastAllColors,
+      adaptiveShades
     }),
     [
       contrast,
@@ -211,14 +220,11 @@ function Mcu({
       neutralVariant,
       error,
       colorMatch,
-      contrastAllColors
+      contrastAllColors,
+      adaptiveShades
     ]
   );
-  const { css } = useMemo2(() => generateCss(config), [config]);
-  return /* @__PURE__ */ jsxs(Fragment, { children: [
-    /* @__PURE__ */ jsx2("style", { id: mcuStyleId, children: css }),
-    /* @__PURE__ */ jsx2(McuProvider, { ...config, styleId: mcuStyleId, children })
-  ] });
+  return /* @__PURE__ */ jsx2(McuProvider, { ...config, styleId: mcuStyleId, children });
 }
 var tokenNames = [
   "background",
@@ -232,13 +238,14 @@ var tokenNames = [
   "surfaceContainerHigh",
   "surfaceContainerHighest",
   "onSurface",
+  "surfaceVariant",
   "onSurfaceVariant",
   "outline",
   "outlineVariant",
   "inverseSurface",
   "inverseOnSurface",
   "primary",
-  // "primaryDim",
+  "surfaceTint",
   "onPrimary",
   "primaryContainer",
   "onPrimaryContainer",
@@ -247,12 +254,7 @@ var tokenNames = [
   "onPrimaryFixed",
   "onPrimaryFixedVariant",
   "inversePrimary",
-  "primaryFixed",
-  "primaryFixedDim",
-  "onPrimaryFixed",
-  "onPrimaryFixedVariant",
   "secondary",
-  // "secondaryDim",
   "onSecondary",
   "secondaryContainer",
   "onSecondaryContainer",
@@ -261,7 +263,6 @@ var tokenNames = [
   "onSecondaryFixed",
   "onSecondaryFixedVariant",
   "tertiary",
-  // "tertiaryDim",
   "onTertiary",
   "tertiaryContainer",
   "onTertiaryContainer",
@@ -270,24 +271,14 @@ var tokenNames = [
   "onTertiaryFixed",
   "onTertiaryFixedVariant",
   "error",
-  // "errorDim",
   "onError",
   "errorContainer",
   "onErrorContainer",
   "scrim",
-  // added manually, was missing
   "shadow"
-  // added manually, was missing
 ];
 function toRecord(arr, getEntry) {
-  return arr.reduce(
-    (acc, item) => {
-      const [key, value] = getEntry(item);
-      acc[key] = value;
-      return acc;
-    },
-    {}
-  );
+  return Object.fromEntries(arr.map(getEntry));
 }
 function getPalette(palettes, colorName) {
   const palette = palettes[colorName];
@@ -310,7 +301,7 @@ function mergeBaseAndCustomColors(scheme, customColors, colorPalettes, contrastA
     const getPaletteForColor = (s) => getPalette(colorPalettes, colorname);
     const getTone = (baseTone) => (s) => {
       if (!contrastAllColors) return baseTone;
-      return adjustToneForContrast(baseTone, s.contrastLevel, s.isDark);
+      return adjustToneForContrast(baseTone, s.contrastLevel);
     };
     const colorDynamicColor = new DynamicColor(
       colorname,
@@ -349,25 +340,6 @@ function mergeBaseAndCustomColors(scheme, customColors, colorPalettes, contrastA
   });
   return { ...baseVars, ...customVars };
 }
-var cssVar = (colorName, colorValue) => {
-  const name = `--mcu-${kebabCase(colorName)}`;
-  const value = hexFromArgb2(colorValue);
-  return `${name}:${value};`;
-};
-var generateTonalPaletteVars = (paletteName, palette, scheme, applyContrast = false) => {
-  return STANDARD_TONES.map((tone) => {
-    let toneToUse = tone;
-    if (applyContrast && scheme) {
-      toneToUse = adjustToneForContrast(
-        tone,
-        scheme.contrastLevel,
-        scheme.isDark
-      );
-    }
-    const color = palette.tone(toneToUse);
-    return cssVar(`${paletteName}-${tone}`, color);
-  }).join(" ");
-};
 function createColorPalette(colorDef, baseScheme, effectiveSourceForHarmonization) {
   const colorArgb = argbFromHex(colorDef.hex);
   const harmonizedArgb = colorDef.blend ? Blend.harmonize(colorArgb, effectiveSourceForHarmonization) : colorArgb;
@@ -386,11 +358,7 @@ function createColorPalette(colorDef, baseScheme, effectiveSourceForHarmonizatio
   }
   return TonalPalette.fromHueAndChroma(hct.hue, targetChroma);
 }
-var toCssVars = (mergedColors) => {
-  return Object.entries(mergedColors).map(([name, value]) => cssVar(name, value)).join(" ");
-};
-function generateCss({
-  source: hexSource,
+function builder(hexSource, {
   scheme = DEFAULT_SCHEME,
   contrast = DEFAULT_CONTRAST,
   primary,
@@ -399,11 +367,12 @@ function generateCss({
   neutral,
   neutralVariant,
   error,
-  colorMatch = DEFAULT_COLOR_MATCH,
   customColors: hexCustomColors = DEFAULT_CUSTOM_COLORS,
-  contrastAllColors = DEFAULT_CONTRAST_ALL_COLORS
-}) {
+  contrastAllColors = DEFAULT_CONTRAST_ALL_COLORS,
+  adaptiveShades = DEFAULT_ADAPTIVE_SHADES
+} = {}) {
   const sourceArgb = argbFromHex(hexSource);
+  const sourceHct = Hct.fromInt(sourceArgb);
   const effectiveSource = primary || hexSource;
   const effectiveSourceArgb = argbFromHex(effectiveSource);
   const effectiveSourceForHarmonization = primary ? argbFromHex(primary) : sourceArgb;
@@ -462,12 +431,8 @@ function generateCss({
       createColorPalette(colorDef, baseScheme, effectiveSourceForHarmonization)
     ])
   );
-  const createSchemes = (baseConfig) => [
-    new DynamicScheme({ ...baseConfig, isDark: false }),
-    new DynamicScheme({ ...baseConfig, isDark: true })
-  ];
   const variant = schemeToVariant[scheme];
-  const [lightScheme, darkScheme] = createSchemes({
+  const schemeConfig = {
     sourceColorArgb: effectiveSourceArgb,
     variant,
     contrastLevel: contrast,
@@ -476,12 +441,26 @@ function generateCss({
     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,
@@ -499,67 +478,324 @@ function generateCss({
     colorPalettes,
     contrastAllColors
   );
-  const lightVars = toCssVars(mergedColorsLight);
-  const darkVars = toCssVars(mergedColorsDark);
-  const allTonalVars = [
-    // Core colors from the scheme
-    generateTonalPaletteVars(
-      "primary",
-      lightScheme.primaryPalette,
-      lightScheme,
-      contrastAllColors
-    ),
-    generateTonalPaletteVars(
-      "secondary",
-      lightScheme.secondaryPalette,
-      lightScheme,
-      contrastAllColors
-    ),
-    generateTonalPaletteVars(
-      "tertiary",
-      lightScheme.tertiaryPalette,
-      lightScheme,
-      contrastAllColors
-    ),
-    generateTonalPaletteVars(
-      "error",
-      lightScheme.errorPalette,
-      lightScheme,
-      contrastAllColors
-    ),
-    generateTonalPaletteVars(
-      "neutral",
-      lightScheme.neutralPalette,
-      lightScheme,
-      contrastAllColors
-    ),
-    generateTonalPaletteVars(
-      "neutral-variant",
-      lightScheme.neutralVariantPalette,
-      lightScheme,
-      contrastAllColors
-    ),
-    // Custom colors from our unified palette map
-    ...customColors.map((customColorObj) => {
-      const palette = getPalette(colorPalettes, customColorObj.name);
-      return generateTonalPaletteVars(
-        kebabCase(customColorObj.name),
-        palette,
-        lightScheme,
-        contrastAllColors
-      );
-    })
-  ].join(" ");
   return {
-    css: `
-:root { ${lightVars} ${allTonalVars} }
-.dark { ${darkVars} }
-`,
+    //
+    //  ██████ ███████ ███████
+    // ██      ██      ██
+    // ██      ███████ ███████
+    // ██           ██      ██
+    //  ██████ ███████ ███████
+    //
+    toCss() {
+      function cssVar(colorName, colorValue) {
+        const name = `--mcu-${kebabCase(colorName)}`;
+        const value = hexFromArgb2(colorValue);
+        return `${name}:${value};`;
+      }
+      function toCssVars(mergedColors) {
+        return Object.entries(mergedColors).map(([name, value]) => cssVar(name, value)).join(" ");
+      }
+      function generateTonalPaletteVars(paletteName, palette, scheme2, applyContrast, adaptiveShades2) {
+        return STANDARD_TONES.map((tone) => {
+          let toneToUse = tone;
+          if (adaptiveShades2 && scheme2.isDark) {
+            toneToUse = 100 - tone;
+          }
+          if (applyContrast) {
+            toneToUse = adjustToneForContrast(toneToUse, scheme2.contrastLevel);
+          }
+          const color = palette.tone(toneToUse);
+          return cssVar(`${paletteName}-${tone}`, color);
+        }).join(" ");
+      }
+      function generateTonalVars(s) {
+        return Object.entries(allPalettes).map(
+          ([name, palette]) => generateTonalPaletteVars(
+            kebabCase(name),
+            palette,
+            s,
+            contrastAllColors,
+            adaptiveShades
+          )
+        ).join(" ");
+      }
+      const lightVars = toCssVars(mergedColorsLight);
+      const darkVars = toCssVars(mergedColorsDark);
+      const lightTonalVars = generateTonalVars(lightScheme);
+      const darkTonalVars = generateTonalVars(darkScheme);
+      return `
+:root { ${lightVars} ${lightTonalVars} }
+.dark { ${darkVars} ${adaptiveShades ? darkTonalVars : lightTonalVars} }
+`;
+    },
+    //
+    //      ██ ███████  ██████  ███    ██
+    //      ██ ██      ██    ██ ████   ██
+    //      ██ ███████ ██    ██ ██ ██  ██
+    // ██   ██      ██ ██    ██ ██  ██ ██
+    //  █████  ███████  ██████  ██   ████
+    //
+    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] = hexFromArgb2(
+              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 STANDARD_TONES) {
+            tones[tone.toString()] = hexFromArgb2(
+              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: hexFromArgb2(argb).toUpperCase()
+        };
+      }
+      function figmaToken(argb) {
+        return {
+          $type: "color",
+          $value: argbToFigmaColorValue(argb),
+          $extensions: {
+            "com.figma.scopes": ["ALL_SCOPES"],
+            "com.figma.isOverride": true
+          }
+        };
+      }
+      function buildFigmaSchemeTokens(mergedColors) {
+        const tokens = {};
+        for (const [name, argb] of Object.entries(mergedColors)) {
+          tokens[startCase(name)] = figmaToken(argb);
+        }
+        return tokens;
+      }
+      function buildFigmaPaletteTokens(isDark) {
+        const palettes = {};
+        for (const [name, palette] of Object.entries(allPalettes)) {
+          const tones = {};
+          for (const tone of STANDARD_TONES) {
+            let toneToUse = tone;
+            if (adaptiveShades && isDark) {
+              toneToUse = 100 - tone;
+            }
+            if (contrastAllColors) {
+              toneToUse = adjustToneForContrast(toneToUse, contrast);
+            }
+            const argb = palette.tone(toneToUse);
+            tones[tone.toString()] = figmaToken(argb);
+          }
+          palettes[startCase(name)] = tones;
+        }
+        return palettes;
+      }
+      function buildModeFile(modeName, mergedColors, isDark) {
+        return {
+          Schemes: buildFigmaSchemeTokens(mergedColors),
+          Palettes: buildFigmaPaletteTokens(isDark),
+          $extensions: {
+            "com.figma.modeName": modeName
+          }
+        };
+      }
+      return {
+        "Light.tokens.json": buildModeFile("Light", mergedColorsLight, false),
+        "Dark.tokens.json": buildModeFile("Dark", mergedColorsDark, true)
+      };
+    },
+    //
+    // API
+    //
     mergedColorsLight,
-    mergedColorsDark
+    mergedColorsDark,
+    allPalettes
   };
 }
 export {
+  DEFAULT_ADAPTIVE_SHADES,
+  DEFAULT_BLEND,
+  DEFAULT_CONTRAST,
+  DEFAULT_CONTRAST_ALL_COLORS,
+  DEFAULT_SCHEME,
   Mcu,
+  builder,
+  schemeNames,
   useMcu
 };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "react-mcu",
-  "version": "1.2.0",
+  "version": "1.3.0",
   "description": "A React component library",
   "keywords": [
     "react",
@@ -28,32 +28,50 @@
     "dist",
     "src/tailwind.css"
   ],
+  "bin": {
+    "react-mcu": "./src/cli.ts"
+  },
   "type": "module",
   "devDependencies": {
     "@arethetypeswrong/cli": "^0.18.2",
     "@changesets/cli": "^2.27.7",
+    "@chromatic-com/storybook": "^5.0.0",
+    "@eslint/js": "^10.0.1",
     "@storybook/addon-docs": "^10.1.11",
     "@storybook/addon-themes": "^10.1.11",
     "@storybook/react-vite": "^10.1.11",
     "@tailwindcss/postcss": "^4.1.18",
     "@testing-library/dom": "^10.4.1",
     "@testing-library/react": "^16.3.1",
+    "@types/culori": "^4.0.1",
     "@types/lodash-es": "^4.17.12",
     "@types/react": "^19.2.7",
     "@types/react-dom": "^19.2.3",
     "@vitejs/plugin-react": "^5.1.2",
+    "ajv": "^8.18.0",
+    "ajv-formats": "^3.0.1",
     "chromatic": "^13.3.5",
+    "class-variance-authority": "^0.7.1",
+    "clsx": "^2.1.1",
+    "culori": "^4.0.2",
+    "eslint": "^10.0.0",
+    "eslint-plugin-react-hooks": "^7.0.1",
+    "eslint-plugin-sonarjs": "^3.0.7",
+    "globals": "^17.3.0",
     "husky": "^9.1.7",
     "jsdom": "^27.4.0",
     "lint-staged": "^16.2.7",
     "postcss": "^8.5.6",
     "prettier": "^3.3.3",
+    "prettier-plugin-organize-imports": "^4.3.0",
     "react": "^19.2.3",
     "react-dom": "^19.2.3",
     "storybook": "^10.1.11",
+    "tailwind-merge": "^3.4.0",
     "tailwindcss": "^4.1.18",
     "tsup": "^8.2.4",
     "typescript": "^5.5.4",
+    "typescript-eslint": "^8.55.0",
     "vitest": "^4.0.16"
   },
   "peerDependencies": {
@@ -62,13 +80,17 @@
   },
   "dependencies": {
     "@material/material-color-utilities": "^0.3.0",
-    "lodash-es": "^4.17.22"
+    "commander": "^14.0.3",
+    "lodash-es": "^4.17.22",
+    "tsx": "^4.21.0"
   },
   "scripts": {
     "build": "tsup",
-    "lgtm": "pnpm run build && pnpm run check-format && pnpm run check-exports && pnpm run typecheck && pnpm run test",
+    "lint": "eslint .",
+    "lgtm": "pnpm run build && pnpm run lint && pnpm run check-format && pnpm run check-exports && pnpm run typecheck && pnpm run test",
     "typecheck": "tsc",
     "test": "vitest run",
+    "pretest": "bash scripts/download-dtcg-schemas.sh",
     "format": "prettier --write .",
     "check-format": "prettier --check .",
     "check-exports": "attw --pack . --ignore-rules cjs-resolves-to-esm no-resolution",

package/src/cli.ts

@@ -0,0 +1,116 @@
+#!/usr/bin/env tsx
+
+// @example
+
+// ```sh
+// $ npx tsx src/cli.ts builder '#6750A4'
+// $ npx tsx src/cli.ts builder '#6750A4' --format css
+// $ npx tsx src/cli.ts builder '#6750A4' --adaptive-shades --format figma
+// ```
+
+import * as fs from "node:fs";
+import * as path from "node:path";
+
+import { Command, Option } from "commander";
+import {
+  builder,
+  DEFAULT_ADAPTIVE_SHADES,
+  DEFAULT_BLEND,
+  DEFAULT_CONTRAST,
+  DEFAULT_CONTRAST_ALL_COLORS,
+  DEFAULT_SCHEME,
+  schemeNames,
+} from "react-mcu";
+
+const program = new Command();
+
+program.name("react-mcu").description("m3 color system for react");
+
+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(
+    "--adaptive-shades",
+    "Adapt tonal palette shades for dark mode",
+    DEFAULT_ADAPTIVE_SHADES,
+  )
+  .option(
+    "--contrast-all-colors",
+    "Apply contrast adjustment to tonal palette shades",
+    DEFAULT_CONTRAST_ALL_COLORS,
+  )
+  .action((source: string, opts) => {
+    let customColors: { name: string; hex: string; blend: boolean }[] = [];
+    if (opts.customColors) {
+      try {
+        const parsed = JSON.parse(opts.customColors) as {
+          name: string;
+          hex: string;
+          blend?: boolean;
+        }[];
+        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,
+      adaptiveShades: opts.adaptiveShades,
+      contrastAllColors: opts.contrastAllColors,
+    });
+
+    if (opts.format === "css") {
+      process.stdout.write(result.toCss());
+    } else if (opts.format === "figma") {
+      const outputDir = opts.output ?? "mcu-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();