@kyralabs/m3e-tokens 1.0.1 → 1.1.0

package/README.md

@@ -35,6 +35,27 @@ or from the command line:
 npx m3e-theme --seed "#6750A4" --variant expressive > theme.css
 ```
 
+Optional core colors replace the palettes the variant would derive from the seed, like Material
+Theme Builder's: `secondary`, `tertiary`, `neutral`, `neutralVariant` and `error`. Each palette
+keeps the given color's hue and chroma (`TonalPalette.fromInt`); the variant still maps the roles
+to tones. For example, a red primary on grey surfaces:
+
+```ts
+createTheme({
+  seed: '#d84848',
+  variant: 'fidelity',
+  coreColors: { neutral: '#808080', neutralVariant: '#808080' },
+});
+```
+
+```sh
+npx m3e-theme --seed "#d84848" --variant fidelity --neutral "#808080" --neutral-variant "#808080"
+```
+
+The CLI flags are `--secondary`, `--tertiary`, `--neutral`, `--neutral-variant` and `--error`.
+With spec 2025 (the `tonalSpot`, `neutral`, `vibrant` and `expressive` variants) the outline and
+surface-variant roles come from the neutral palette, so `neutralVariant` has no effect there.
+
 Other entries: `./components/<name>.css` (component tokens), `./material-symbols.css` (Rounded;
 `-outlined` and `-sharp` too), `./fonts-full.css` (every Google Sans Flex axis), and JS token
 objects from `.` and `./components`.

package/dist/cli/theme.js

@@ -5089,13 +5089,55 @@ var COLOR_ROLES = Object.getOwnPropertyNames(
 var rolesFor = (specVersion) => specVersion === "2025" ? COLOR_ROLES : COLOR_ROLES.filter((r) => !SPEC_2025_ONLY_ROLES.includes(r));
 var HEX = /^#(?:[0-9a-f]{3}|[0-9a-f]{6})$/i;
 var normalizeHex = (hex) => hexFromArgb(argbFromHex(hex));
-function schemeColors(seed, variant, isDark, contrast, specVersion) {
-  const scheme = new SCHEMES[variant](
+var CORE_COLORS = ["secondary", "tertiary", "neutral", "neutralVariant", "error"];
+function normalizeCoreColors(coreColors, caller) {
+  const out = {};
+  for (const key of Object.keys(coreColors)) {
+    if (!CORE_COLORS.includes(key)) {
+      throw new Error(`${caller}: unknown core color "${key}"`);
+    }
+  }
+  for (const key of CORE_COLORS) {
+    const hex = coreColors[key];
+    if (hex === void 0) continue;
+    if (typeof hex !== "string" || !HEX.test(hex)) {
+      throw new Error(
+        `${caller}: core color ${key} must be #rgb or #rrggbb, got ${JSON.stringify(hex)}`
+      );
+    }
+    out[key] = normalizeHex(hex);
+  }
+  return out;
+}
+function withCoreColors(scheme, coreColors) {
+  if (CORE_COLORS.every((key) => coreColors[key] === void 0)) return scheme;
+  const palette = (key) => {
+    const hex = coreColors[key];
+    return hex === void 0 ? void 0 : TonalPalette.fromInt(argbFromHex(hex));
+  };
+  return new DynamicScheme({
+    sourceColorHct: scheme.sourceColorHct,
+    variant: scheme.variant,
+    contrastLevel: scheme.contrastLevel,
+    isDark: scheme.isDark,
+    platform: scheme.platform,
+    specVersion: scheme.specVersion,
+    primaryPalette: scheme.primaryPalette,
+    secondaryPalette: palette("secondary") ?? scheme.secondaryPalette,
+    tertiaryPalette: palette("tertiary") ?? scheme.tertiaryPalette,
+    neutralPalette: palette("neutral") ?? scheme.neutralPalette,
+    neutralVariantPalette: palette("neutralVariant") ?? scheme.neutralVariantPalette,
+    errorPalette: palette("error") ?? scheme.errorPalette
+  });
+}
+function schemeColors(seed, variant, isDark, contrast, specVersion, coreColors = {}) {
+  const variantScheme = new SCHEMES[variant](
     Hct.fromInt(argbFromHex(seed)),
     isDark,
     contrast,
     specVersion
   );
+  const scheme = withCoreColors(variantScheme, normalizeCoreColors(coreColors, "schemeColors"));
   const out = {};
   for (const role of rolesFor(specVersion)) {
     const method = dynamicColors[role];
@@ -5127,9 +5169,11 @@ function createTheme(options) {
       `createTheme: contrast must be within [-1, 1], got ${String(options.contrast)}`
     );
   }
+  const coreColors = normalizeCoreColors(options.coreColors ?? {}, "createTheme");
+  const hasCoreColors = Object.keys(coreColors).length > 0;
   const roles = rolesFor(specVersion);
   const build = (isDark, extra) => {
-    const colors = schemeColors(seed, variant, isDark, contrast, specVersion);
+    const colors = schemeColors(seed, variant, isDark, contrast, specVersion, coreColors);
     for (const [role, hex] of Object.entries(extra ?? {})) {
       if (!roles.includes(role)) throw new Error(`createTheme: unknown color role "${role}"`);
       if (!HEX.test(hex)) throw new Error(`createTheme: override ${role} must be a hex color`);
@@ -5150,6 +5194,7 @@ function createTheme(options) {
     cssText,
     tokens: {
       seed: normalizeHex(seed),
+      ...hasCoreColors ? { coreColors } : {},
       variant,
       contrast,
       specVersion,
@@ -5159,18 +5204,30 @@ function createTheme(options) {
     }
   };
 }
-
-// src/cli/theme.ts
 var USAGE = `usage: m3e-theme --seed <#hex> [options]
 
-  --variant   ${VARIANTS.join(" | ")}  (default tonalSpot)
-  --mode      light | dark | system  (default system)
-  --contrast  -1\u20261 or ${Object.keys(CONTRAST).join(" | ")}  (default standard)
-  --spec      ${SPEC_VERSIONS.join(" | ")}  (default 2025)
-  --motion    expressive | standard  (default expressive)
-  --selector  single compound selector  (default :root)
-  --out       file to write  (default stdout)`;
-function run(argv) {
+  --variant          ${VARIANTS.join(" | ")}  (default tonalSpot)
+  --mode             light | dark | system  (default system)
+  --contrast         -1\u20261 or ${Object.keys(CONTRAST).join(" | ")}  (default standard)
+  --spec             ${SPEC_VERSIONS.join(" | ")}  (default 2025)
+  --motion           expressive | standard  (default expressive)
+  --selector         single compound selector  (default :root)
+  --out              file to write  (default stdout)
+
+Core colors (optional; each replaces the palette derived from --seed):
+  --secondary        <#hex>
+  --tertiary         <#hex>
+  --neutral          <#hex>  surfaces and backgrounds
+  --neutral-variant  <#hex>  surface variants and outlines
+  --error            <#hex>`;
+var CORE_COLOR_FLAGS = {
+  secondary: "secondary",
+  tertiary: "tertiary",
+  neutral: "neutral",
+  "neutral-variant": "neutralVariant",
+  error: "error"
+};
+function parseThemeArgs(argv) {
   const { values } = parseArgs({
     args: argv,
     options: {
@@ -5182,16 +5239,24 @@ function run(argv) {
       motion: { type: "string" },
       selector: { type: "string" },
       out: { type: "string" },
+      secondary: { type: "string" },
+      tertiary: { type: "string" },
+      neutral: { type: "string" },
+      "neutral-variant": { type: "string" },
+      error: { type: "string" },
       help: { type: "boolean", short: "h" }
     }
   });
-  if (values.help || !values.seed) {
-    console.error(USAGE);
-    return values.help ? 0 : 2;
+  if (values.help || !values.seed) return { help: true, exitCode: values.help ? 0 : 2 };
+  const coreColors = {};
+  for (const [flag, key] of Object.entries(CORE_COLOR_FLAGS)) {
+    const value = values[flag];
+    if (value !== void 0) coreColors[key] = value;
   }
   const contrast = values.contrast;
   const options = {
     seed: values.seed,
+    ...Object.keys(coreColors).length > 0 ? { coreColors } : {},
     ...values.variant ? { variant: values.variant } : {},
     ...values.mode ? { mode: values.mode } : {},
     ...contrast === void 0 ? {} : { contrast: contrast in CONTRAST ? contrast : Number(contrast) },
@@ -5199,8 +5264,18 @@ function run(argv) {
     ...values.motion ? { motionScheme: values.motion } : {},
     ...values.selector ? { selector: values.selector } : {}
   };
-  const { cssText } = createTheme(options);
-  if (values.out) writeFileSync(values.out, cssText);
+  return { help: false, options, out: values.out };
+}
+
+// src/cli/theme.ts
+function run(argv) {
+  const args = parseThemeArgs(argv);
+  if (args.help) {
+    console.error(USAGE);
+    return args.exitCode;
+  }
+  const { cssText } = createTheme(args.options);
+  if (args.out) writeFileSync(args.out, cssText);
   else process.stdout.write(cssText);
   return 0;
 }