react-mcu 1.2.0 → 1.3.1

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 { CustomColor, TonalPalette } from '@material/material-color-utilities';
 import * as react_jsx_runtime from 'react/jsx-runtime';
-import { SchemeTonalSpot, SchemeMonochrome, SchemeNeutral, SchemeVibrant, SchemeExpressive, SchemeFidelity, SchemeContent, CustomColor } from '@material/material-color-utilities';
 
 type HexCustomColor = Omit<CustomColor, "value"> & {
     hex: string;
@@ -29,52 +29,136 @@ 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;
     /**
      * Array of custom colors to include in the generated palette.
-     *
-     * @example
-     * ```ts
-     * customColors={[
-     *   { name: "brand", hex: "#FF5733", blend: true },
-     *   { name: "success", hex: "#28A745", blend: false }
-     * ]}
-     * ```
+     * Each custom color can be blended with the source color for harmonization.
      */
     customColors?: HexCustomColor[];
     /**
-     * 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
+     * Apply contrast adjustment to tonal palette shades when true.
+     * When true, all tonal palette shades are adjusted based on the contrast level.
+     * When false (default), contrast adjustments only apply to core Material Design tokens.
      */
     contrastAllColors?: boolean;
+    /**
+     * Adapt tonal palette shades for dark mode.
+     * When true, tonal palette shades automatically invert for dark mode
+     * (high values become dark, low values become light).
+     * When false (default), tonal palette values remain constant across light/dark mode.
+     */
+    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 tokenNames: readonly ["background", "error", "errorContainer", "inverseOnSurface", "inversePrimary", "inverseSurface", "onBackground", "onError", "onErrorContainer", "onPrimary", "onPrimaryContainer", "onPrimaryFixed", "onPrimaryFixedVariant", "onSecondary", "onSecondaryContainer", "onSecondaryFixed", "onSecondaryFixedVariant", "onSurface", "onSurfaceVariant", "onTertiary", "onTertiaryContainer", "onTertiaryFixed", "onTertiaryFixedVariant", "outline", "outlineVariant", "primary", "primaryContainer", "primaryFixed", "primaryFixedDim", "scrim", "secondary", "secondaryContainer", "secondaryFixed", "secondaryFixedDim", "shadow", "surface", "surfaceBright", "surfaceContainer", "surfaceContainerHigh", "surfaceContainerHighest", "surfaceContainerLow", "surfaceContainerLowest", "surfaceDim", "surfaceTint", "surfaceVariant", "tertiary", "tertiaryContainer", "tertiaryFixed", "tertiaryFixedDim"];
+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;
+    };
+};
+
+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"];
-type TokenName = (typeof tokenNames)[number];
 
 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 { Mcu, builder, useMcu };

package/dist/index.js

@@ -1,14 +1,17 @@
 "use client";
 
-// src/Mcu.tsx
+// src/lib/builder.ts
 import {
   argbFromHex,
   Blend,
+  blueFromArgb,
   DynamicColor,
   DynamicScheme,
+  greenFromArgb,
   Hct,
-  hexFromArgb as hexFromArgb2,
+  hexFromArgb,
   MaterialDynamicColors,
+  redFromArgb,
   SchemeContent,
   SchemeExpressive,
   SchemeFidelity,
@@ -18,94 +21,12 @@ import {
   SchemeVibrant,
   TonalPalette
 } from "@material/material-color-utilities";
-import { kebabCase, upperFirst } from "lodash-es";
-import { useMemo as useMemo2 } from "react";
-
-// src/Mcu.context.tsx
-import { hexFromArgb } from "@material/material-color-utilities";
-import {
-  useCallback,
-  useInsertionEffect,
-  useMemo,
-  useState
-} from "react";
-
-// src/lib/createRequiredContext.ts
-import { createContext, useContext } from "react";
-var createRequiredContext = () => {
-  const Ctx = createContext(null);
-  const useCtx = () => {
-    const contextValue = useContext(Ctx);
-    if (contextValue === null) {
-      throw new Error("Context value is null");
-    }
-    return contextValue;
-  };
-  return [useCtx, Ctx.Provider, Ctx];
-};
-
-// src/Mcu.context.tsx
-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
-}) => {
-  const [initials] = useState(() => ({
-    source: initialSource,
-    scheme: initialScheme,
-    contrast: initialContrast,
-    customColors: initialCustomColors,
-    contrastAllColors: initialContrastAllColors
-  }));
-  const [mcuConfig, setMcuConfig] = useState(initials);
-  const { css, mergedColorsLight, mergedColorsDark } = useMemo(
-    () => generateCss(mcuConfig),
-    [mcuConfig]
-  );
-  useInsertionEffect(() => {
-    let tag = document.getElementById(styleId);
-    if (!tag) {
-      tag = document.createElement("style");
-      tag.id = styleId;
-      document.head.appendChild(tag);
-    }
-    tag.textContent = css;
-  }, [css, styleId]);
-  const getMcuColor = useCallback(
-    (colorName, theme) => {
-      return hexFromArgb(
-        (theme === "light" ? mergedColorsLight : mergedColorsDark)[colorName]
-      );
-    },
-    [mergedColorsDark, mergedColorsLight]
-  );
-  const value = useMemo(
-    () => ({
-      initials,
-      setMcuConfig,
-      getMcuColor
-    }),
-    [getMcuColor, initials]
-  );
-  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 { kebabCase, startCase, upperFirst } from "lodash-es";
+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 schemesMap = {
@@ -117,14 +38,11 @@ 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 = [
@@ -159,135 +77,67 @@ var Variant = {
   FRUIT_SALAD: 8
 };
 var schemeToVariant = {
-  tonalSpot: Variant.TONAL_SPOT,
   monochrome: Variant.MONOCHROME,
   neutral: Variant.NEUTRAL,
+  tonalSpot: Variant.TONAL_SPOT,
   vibrant: Variant.VIBRANT,
   expressive: Variant.EXPRESSIVE,
   fidelity: Variant.FIDELITY,
   content: Variant.CONTENT
 };
-var mcuStyleId = "mcu-styles";
-function Mcu({
-  source,
-  scheme = DEFAULT_SCHEME,
-  contrast = DEFAULT_CONTRAST,
-  primary,
-  secondary,
-  tertiary,
-  neutral,
-  neutralVariant,
-  error,
-  colorMatch = DEFAULT_COLOR_MATCH,
-  customColors = DEFAULT_CUSTOM_COLORS,
-  contrastAllColors = DEFAULT_CONTRAST_ALL_COLORS,
-  children
-}) {
-  const config = useMemo2(
-    () => ({
-      source,
-      scheme,
-      contrast,
-      primary,
-      secondary,
-      tertiary,
-      neutral,
-      neutralVariant,
-      error,
-      colorMatch,
-      customColors,
-      // extras features
-      contrastAllColors
-    }),
-    [
-      contrast,
-      customColors,
-      scheme,
-      source,
-      primary,
-      secondary,
-      tertiary,
-      neutral,
-      neutralVariant,
-      error,
-      colorMatch,
-      contrastAllColors
-    ]
-  );
-  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 })
-  ] });
-}
 var tokenNames = [
   "background",
+  "error",
+  "errorContainer",
+  "inverseOnSurface",
+  "inversePrimary",
+  "inverseSurface",
   "onBackground",
-  "surface",
-  "surfaceDim",
-  "surfaceBright",
-  "surfaceContainerLowest",
-  "surfaceContainerLow",
-  "surfaceContainer",
-  "surfaceContainerHigh",
-  "surfaceContainerHighest",
+  "onError",
+  "onErrorContainer",
+  "onPrimary",
+  "onPrimaryContainer",
+  "onPrimaryFixed",
+  "onPrimaryFixedVariant",
+  "onSecondary",
+  "onSecondaryContainer",
+  "onSecondaryFixed",
+  "onSecondaryFixedVariant",
   "onSurface",
   "onSurfaceVariant",
+  "onTertiary",
+  "onTertiaryContainer",
+  "onTertiaryFixed",
+  "onTertiaryFixedVariant",
   "outline",
   "outlineVariant",
-  "inverseSurface",
-  "inverseOnSurface",
   "primary",
-  // "primaryDim",
-  "onPrimary",
   "primaryContainer",
-  "onPrimaryContainer",
   "primaryFixed",
   "primaryFixedDim",
-  "onPrimaryFixed",
-  "onPrimaryFixedVariant",
-  "inversePrimary",
-  "primaryFixed",
-  "primaryFixedDim",
-  "onPrimaryFixed",
-  "onPrimaryFixedVariant",
+  "scrim",
   "secondary",
-  // "secondaryDim",
-  "onSecondary",
   "secondaryContainer",
-  "onSecondaryContainer",
   "secondaryFixed",
   "secondaryFixedDim",
-  "onSecondaryFixed",
-  "onSecondaryFixedVariant",
+  "shadow",
+  "surface",
+  "surfaceBright",
+  "surfaceContainer",
+  "surfaceContainerHigh",
+  "surfaceContainerHighest",
+  "surfaceContainerLow",
+  "surfaceContainerLowest",
+  "surfaceDim",
+  "surfaceTint",
+  "surfaceVariant",
   "tertiary",
-  // "tertiaryDim",
-  "onTertiary",
   "tertiaryContainer",
-  "onTertiaryContainer",
   "tertiaryFixed",
-  "tertiaryFixedDim",
-  "onTertiaryFixed",
-  "onTertiaryFixedVariant",
-  "error",
-  // "errorDim",
-  "onError",
-  "errorContainer",
-  "onErrorContainer",
-  "scrim",
-  // added manually, was missing
-  "shadow"
-  // added manually, was missing
+  "tertiaryFixedDim"
 ];
 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 +160,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 +199,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 +217,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 +226,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 +290,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 +300,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 +337,452 @@ 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 = hexFromArgb(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] = 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 STANDARD_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 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
   };
 }
+
+// src/Mcu.tsx
+import { useMemo as useMemo2 } from "react";
+
+// src/Mcu.context.tsx
+import {
+  hexFromArgb as hexFromArgb2
+} from "@material/material-color-utilities";
+import React, {
+  useCallback,
+  useInsertionEffect,
+  useMemo,
+  useState
+} from "react";
+
+// src/lib/createRequiredContext.ts
+import { createContext, useContext } from "react";
+var createRequiredContext = () => {
+  const Ctx = createContext(null);
+  const useCtx = () => {
+    const contextValue = useContext(Ctx);
+    if (contextValue === null) {
+      throw new Error("Context value is null");
+    }
+    return contextValue;
+  };
+  return [useCtx, Ctx.Provider, Ctx];
+};
+
+// src/Mcu.context.tsx
+import { jsx } from "react/jsx-runtime";
+var [useMcu, Provider, McuContext] = createRequiredContext();
+var McuProvider = ({
+  styleId,
+  children,
+  ...configProps
+}) => {
+  const [initials] = useState(() => configProps);
+  const [mcuConfig, setMcuConfig] = useState(initials);
+  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) {
+      tag = document.createElement("style");
+      tag.id = styleId;
+      document.head.appendChild(tag);
+    }
+    tag.textContent = css;
+  }, [css, styleId]);
+  const getMcuColor = useCallback(
+    (colorName, theme) => {
+      const mergedColors = theme === "light" ? mergedColorsLight : mergedColorsDark;
+      const colorValue = mergedColors[colorName];
+      if (colorValue === void 0) {
+        throw new Error(`Unknown MCU token '${colorName}'`);
+      }
+      return hexFromArgb2(colorValue);
+    },
+    [mergedColorsDark, mergedColorsLight]
+  );
+  const value = useMemo(
+    () => ({
+      initials,
+      setMcuConfig,
+      getMcuColor,
+      allPalettes
+    }),
+    [getMcuColor, initials, allPalettes]
+  );
+  return /* @__PURE__ */ jsx(Provider, { value, children });
+};
+
+// src/Mcu.tsx
+import { jsx as jsx2 } from "react/jsx-runtime";
+var mcuStyleId = "mcu-styles";
+var DEFAULT_COLOR_MATCH = false;
+function Mcu({
+  source,
+  scheme = DEFAULT_SCHEME,
+  contrast = DEFAULT_CONTRAST,
+  primary,
+  secondary,
+  tertiary,
+  neutral,
+  neutralVariant,
+  error,
+  colorMatch = DEFAULT_COLOR_MATCH,
+  customColors = DEFAULT_CUSTOM_COLORS,
+  contrastAllColors = DEFAULT_CONTRAST_ALL_COLORS,
+  adaptiveShades = DEFAULT_ADAPTIVE_SHADES,
+  children
+}) {
+  const config = useMemo2(
+    () => ({
+      source,
+      scheme,
+      contrast,
+      primary,
+      secondary,
+      tertiary,
+      neutral,
+      neutralVariant,
+      error,
+      colorMatch,
+      customColors,
+      // extras features
+      contrastAllColors,
+      adaptiveShades
+    }),
+    [
+      contrast,
+      customColors,
+      scheme,
+      source,
+      primary,
+      secondary,
+      tertiary,
+      neutral,
+      neutralVariant,
+      error,
+      colorMatch,
+      contrastAllColors,
+      adaptiveShades
+    ]
+  );
+  return /* @__PURE__ */ jsx2(McuProvider, { ...config, styleId: mcuStyleId, children });
+}
 export {
   Mcu,
+  builder,
   useMcu
 };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "react-mcu",
-  "version": "1.2.0",
+  "version": "1.3.1",
   "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 "./lib/builder";
+
+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();