@loworbitstudio/visor-theme-engine 0.4.0 → 0.4.2

package/dist/index.js

@@ -1,4 +1,5 @@
 import {
+  MATERIAL_TEXT_SLOTS,
   TAILWIND_GRAY,
   VISOR_FONTS_CDN,
   buildVisorFontUrl,
@@ -31,7 +32,7 @@ import {
   rgbToHex,
   rgbToOklch,
   serializeColor
-} from "./chunk-NZF2MS4L.js";
+} from "./chunk-SXT2KY6D.js";
 
 // src/pipeline.ts
 import { parse as parseYaml } from "yaml";
@@ -223,6 +224,29 @@ var visor_theme_schema_default = {
             normal: { type: "string" },
             wide: { type: "string" }
           }
+        },
+        slots: {
+          type: "object",
+          description: "Per-slot overrides for the generated Flutter Material TextTheme. Any subset of the 16 slots may be specified; omitted slots fall through to the Material 3 2024 defaults shipped in visor_core.",
+          additionalProperties: false,
+          properties: {
+            displayLarge: { $ref: "#/$defs/textSlotOverride" },
+            displayMedium: { $ref: "#/$defs/textSlotOverride" },
+            displaySmall: { $ref: "#/$defs/textSlotOverride" },
+            headlineLarge: { $ref: "#/$defs/textSlotOverride" },
+            headlineMedium: { $ref: "#/$defs/textSlotOverride" },
+            headlineSmall: { $ref: "#/$defs/textSlotOverride" },
+            titleLarge: { $ref: "#/$defs/textSlotOverride" },
+            titleMedium: { $ref: "#/$defs/textSlotOverride" },
+            titleSmall: { $ref: "#/$defs/textSlotOverride" },
+            bodyLarge: { $ref: "#/$defs/textSlotOverride" },
+            bodyMedium: { $ref: "#/$defs/textSlotOverride" },
+            bodySmall: { $ref: "#/$defs/textSlotOverride" },
+            labelLarge: { $ref: "#/$defs/textSlotOverride" },
+            labelMedium: { $ref: "#/$defs/textSlotOverride" },
+            labelSmall: { $ref: "#/$defs/textSlotOverride" },
+            labelXSmall: { $ref: "#/$defs/textSlotOverride" }
+          }
         }
       }
     },
@@ -262,6 +286,17 @@ var visor_theme_schema_default = {
         xl: { type: "string" }
       }
     },
+    strokeWidths: {
+      type: "object",
+      description: "Stroke-width scale in pixels \u2014 used for borders, outlines, dividers, progress-indicator strokes. Defaults: thin=1, regular=1.5, medium=2, thick=2.5.",
+      additionalProperties: false,
+      properties: {
+        thin: { type: "number", minimum: 0 },
+        regular: { type: "number", minimum: 0 },
+        medium: { type: "number", minimum: 0 },
+        thick: { type: "number", minimum: 0 }
+      }
+    },
     motion: {
       type: "object",
       description: "Motion/animation configuration.",
@@ -304,6 +339,18 @@ var visor_theme_schema_default = {
           additionalProperties: { type: "string" }
         }
       }
+    },
+    migrate: {
+      type: "object",
+      description: "Migration metadata consumed by `visor migrate` commands. Does not affect CSS generation or theme application.",
+      additionalProperties: false,
+      properties: {
+        "token-substitution": {
+          type: "object",
+          description: "\xA73.1 V7-primitive \u2192 Visor-semantic substitution table. Maps V7 CSS custom property names (with -- prefix) to Visor semantic token names. Consumed by `visor migrate token-substitution`.",
+          additionalProperties: { type: "string" }
+        }
+      }
     }
   },
   $defs: {
@@ -316,6 +363,28 @@ var visor_theme_schema_default = {
         { pattern: "^hsla?\\(" },
         { pattern: "^oklch\\(" }
       ]
+    },
+    textSlotOverride: {
+      type: "object",
+      description: "Per-slot override for one Material TextTheme entry.",
+      additionalProperties: false,
+      properties: {
+        size: {
+          type: "number",
+          exclusiveMinimum: 0,
+          description: "Font size in logical pixels (Flutter TextStyle.fontSize)."
+        },
+        weight: {
+          type: "integer",
+          minimum: 100,
+          maximum: 900,
+          description: "Font weight."
+        },
+        "letter-spacing": {
+          type: "number",
+          description: "Letter spacing in logical pixels (Flutter TextStyle.letterSpacing). Material defaults include negative values, e.g. -0.25 for displayLarge."
+        }
+      }
     }
   }
 };
@@ -333,6 +402,7 @@ var KNOWN_TOP_LEVEL_KEYS = /* @__PURE__ */ new Set([
   "spacing",
   "radius",
   "shadows",
+  "strokeWidths",
   "motion",
   "overrides"
 ]);
@@ -353,14 +423,18 @@ var KNOWN_TYPOGRAPHY_KEYS = /* @__PURE__ */ new Set([
   "body",
   "mono",
   "letter-spacing",
-  "scale"
+  "scale",
+  "slots"
 ]);
 var KNOWN_TYPOGRAPHY_FONT_KEYS = /* @__PURE__ */ new Set(["family", "weight", "weights", "source", "org"]);
 var KNOWN_TYPOGRAPHY_MONO_KEYS = /* @__PURE__ */ new Set(["family"]);
 var KNOWN_LETTER_SPACING_KEYS = /* @__PURE__ */ new Set(["tight", "normal", "wide"]);
+var KNOWN_SLOT_NAMES = new Set(MATERIAL_TEXT_SLOTS);
+var KNOWN_SLOT_OVERRIDE_KEYS = /* @__PURE__ */ new Set(["size", "weight", "letter-spacing"]);
 var KNOWN_SPACING_KEYS = /* @__PURE__ */ new Set(["base"]);
 var KNOWN_RADIUS_KEYS = /* @__PURE__ */ new Set(["sm", "md", "lg", "xl", "pill"]);
 var KNOWN_SHADOW_KEYS = /* @__PURE__ */ new Set(["xs", "sm", "md", "lg", "xl"]);
+var KNOWN_STROKE_WIDTH_KEYS = /* @__PURE__ */ new Set(["thin", "regular", "medium", "thick"]);
 var KNOWN_MOTION_KEYS = /* @__PURE__ */ new Set(["duration-fast", "duration-normal", "duration-slow", "easing"]);
 var KNOWN_OVERRIDES_KEYS = /* @__PURE__ */ new Set(["light", "dark"]);
 function checkUnknownKeys(obj, errors) {
@@ -425,6 +499,31 @@ function checkUnknownKeys(obj, errors) {
         }
       }
     }
+    if (typeof typo.slots === "object" && typo.slots !== null) {
+      const slots = typo.slots;
+      for (const slotName of Object.keys(slots)) {
+        if (!KNOWN_SLOT_NAMES.has(slotName)) {
+          errors.push(
+            `Unknown key 'typography.slots.${slotName}'. Valid keys: ${[...MATERIAL_TEXT_SLOTS].join(", ")}`
+          );
+          continue;
+        }
+        const override = slots[slotName];
+        if (typeof override !== "object" || override === null) {
+          errors.push(
+            `'typography.slots.${slotName}' must be an object with optional size/weight/letter-spacing fields`
+          );
+          continue;
+        }
+        for (const key of Object.keys(override)) {
+          if (!KNOWN_SLOT_OVERRIDE_KEYS.has(key)) {
+            errors.push(
+              `Unknown key 'typography.slots.${slotName}.${key}'. Valid keys: ${[...KNOWN_SLOT_OVERRIDE_KEYS].join(", ")}`
+            );
+          }
+        }
+      }
+    }
   }
   if (typeof obj.spacing === "object" && obj.spacing !== null) {
     for (const key of Object.keys(obj.spacing)) {
@@ -447,6 +546,13 @@ function checkUnknownKeys(obj, errors) {
       }
     }
   }
+  if (typeof obj.strokeWidths === "object" && obj.strokeWidths !== null) {
+    for (const key of Object.keys(obj.strokeWidths)) {
+      if (!KNOWN_STROKE_WIDTH_KEYS.has(key)) {
+        errors.push(`Unknown key 'strokeWidths.${key}'. Valid keys: ${[...KNOWN_STROKE_WIDTH_KEYS].join(", ")}`);
+      }
+    }
+  }
   if (typeof obj.motion === "object" && obj.motion !== null) {
     for (const key of Object.keys(obj.motion)) {
       if (!KNOWN_MOTION_KEYS.has(key)) {
@@ -547,6 +653,23 @@ function validateConfig(config) {
         }
       }
     }
+    if (typeof typo.slots === "object" && typo.slots !== null) {
+      const slots = typo.slots;
+      for (const slotName of Object.keys(slots)) {
+        const override = slots[slotName];
+        if (typeof override !== "object" || override === null) continue;
+        const o = override;
+        if (o.size !== void 0 && (typeof o.size !== "number" || o.size <= 0)) {
+          errors.push(`'typography.slots.${slotName}.size' must be a positive number (logical pixels)`);
+        }
+        if (o.weight !== void 0 && (typeof o.weight !== "number" || o.weight < 100 || o.weight > 900)) {
+          errors.push(`'typography.slots.${slotName}.weight' must be between 100 and 900`);
+        }
+        if (o["letter-spacing"] !== void 0 && typeof o["letter-spacing"] !== "number") {
+          errors.push(`'typography.slots.${slotName}.letter-spacing' must be a number (Flutter logical pixels)`);
+        }
+      }
+    }
   }
   if (obj.overrides !== void 0) {
     if (typeof obj.overrides !== "object" || obj.overrides === null) {
@@ -595,6 +718,12 @@ var DEFAULTS = {
     lg: "0 10px 15px -3px rgba(0, 0, 0, 0.1), 0 4px 6px -4px rgba(0, 0, 0, 0.1)",
     xl: "0 20px 25px -5px rgba(0, 0, 0, 0.1), 0 8px 10px -6px rgba(0, 0, 0, 0.1)"
   },
+  strokeWidths: {
+    thin: 1,
+    regular: 1.5,
+    medium: 2,
+    thick: 2.5
+  },
   motion: {
     "duration-fast": "100ms",
     "duration-normal": "200ms",
@@ -671,7 +800,8 @@ function resolveConfig(config) {
       },
       mono: {
         family: config.typography?.mono?.family ?? DEFAULTS.typography.mono.family
-      }
+      },
+      slots: config.typography?.slots ?? {}
     },
     spacing: {
       base: config.spacing?.base ?? DEFAULTS.spacing.base
@@ -690,6 +820,12 @@ function resolveConfig(config) {
       lg: config.shadows?.lg ?? DEFAULTS.shadows.lg,
       xl: config.shadows?.xl ?? DEFAULTS.shadows.xl
     },
+    strokeWidths: {
+      thin: config.strokeWidths?.thin ?? DEFAULTS.strokeWidths.thin,
+      regular: config.strokeWidths?.regular ?? DEFAULTS.strokeWidths.regular,
+      medium: config.strokeWidths?.medium ?? DEFAULTS.strokeWidths.medium,
+      thick: config.strokeWidths?.thick ?? DEFAULTS.strokeWidths.thick
+    },
     motion: {
       "duration-fast": config.motion?.["duration-fast"] ?? DEFAULTS.motion["duration-fast"],
       "duration-normal": config.motion?.["duration-normal"] ?? DEFAULTS.motion["duration-normal"],
@@ -715,13 +851,17 @@ var SEMANTIC_TEXT_MAP = {
     light: { role: "neutral", shade: 900 },
     dark: { role: "neutral", shade: 50 }
   },
+  // VI-346: rebalanced to fixed-L shades (700/300, 600/400) so AA contrast holds
+  // by default for any reasonable input neutral. Shade 500 is brand-anchored
+  // (variable L = input itself) and therefore forbidden for any text level that
+  // must clear AA. See docs/token-rules.md and SEMANTIC_TEXT_MAP rationale.
   secondary: {
-    light: { role: "neutral", shade: 600 },
-    dark: { role: "neutral", shade: 400 }
+    light: { role: "neutral", shade: 700 },
+    dark: { role: "neutral", shade: 300 }
   },
   tertiary: {
-    light: { role: "neutral", shade: 400 },
-    dark: { role: "neutral", shade: 500 }
+    light: { role: "neutral", shade: 600 },
+    dark: { role: "neutral", shade: 400 }
   },
   disabled: {
     light: { role: "neutral", shade: 300 },
@@ -769,6 +909,12 @@ var SEMANTIC_SURFACE_MAP = {
     light: { constant: CONFIG_SURFACE },
     dark: { constant: CONFIG_DARK_SURFACE }
   },
+  // Distinct from card: glass themes (Blackout, Modern Minimal dark) set surface-card translucent.
+  // Floating panels rendered over arbitrary page content must be opaque — override this token there.
+  popover: {
+    light: { constant: CONFIG_SURFACE },
+    dark: { constant: CONFIG_DARK_SURFACE }
+  },
   subtle: {
     light: { role: "neutral", shade: 50 },
     dark: { role: "neutral", shade: 800 }
@@ -797,6 +943,12 @@ var SEMANTIC_SURFACE_MAP = {
     light: { role: "neutral", shade: 50 },
     dark: { role: "neutral", shade: 800 }
   },
+  // Persistent selected-state surface (active nav item, currently-selected list row).
+  // Distinct from interactive-active (transient press) and from accent-subtle (broader brand surface).
+  selected: {
+    light: { role: "primary", shade: 100 },
+    dark: { role: "primary", shade: 800 }
+  },
   "accent-subtle": {
     light: { role: "primary", shade: 50 },
     dark: { role: "primary", shade: 900 }
@@ -840,6 +992,29 @@ var SEMANTIC_SURFACE_MAP = {
   "info-default": {
     light: { role: "info", shade: 500 },
     dark: { role: "info", shade: 500 }
+  },
+  // 5-tier ordinal elevation scale — deepest (0) to highest (4)
+  // Light mode: BO-10 near-white ramp (white → neutral-300).
+  // Dark mode: deep neutral ramp (neutral-950 → neutral-600).
+  "elev-0": {
+    light: { constant: "#ffffff" },
+    dark: { role: "neutral", shade: 950 }
+  },
+  "elev-1": {
+    light: { role: "neutral", shade: 50 },
+    dark: { role: "neutral", shade: 900 }
+  },
+  "elev-2": {
+    light: { role: "neutral", shade: 100 },
+    dark: { role: "neutral", shade: 800 }
+  },
+  "elev-3": {
+    light: { role: "neutral", shade: 200 },
+    dark: { role: "neutral", shade: 700 }
+  },
+  "elev-4": {
+    light: { role: "neutral", shade: 300 },
+    dark: { role: "neutral", shade: 600 }
   }
 };
 var SEMANTIC_BORDER_MAP = {
@@ -977,28 +1152,28 @@ function resolveRef(ref, primitives, config) {
       return ref.constant;
   }
 }
-function resolveMapping(mapping, primitives, config) {
+function resolveMapping(mapping, lightPrimitives, darkPrimitives, config) {
   return {
-    light: resolveRef(mapping.light, primitives, config),
-    dark: resolveRef(mapping.dark, primitives, config)
+    light: resolveRef(mapping.light, lightPrimitives, config),
+    dark: resolveRef(mapping.dark, darkPrimitives, config)
   };
 }
-function assignSemanticTokens(primitives, config) {
+function assignSemanticTokens(lightPrimitives, darkPrimitives, config) {
   const text = {};
   const surface = {};
   const border = {};
   const interactive = {};
   for (const [name, mapping] of Object.entries(SEMANTIC_MAP.text)) {
-    text[name] = resolveMapping(mapping, primitives, config);
+    text[name] = resolveMapping(mapping, lightPrimitives, darkPrimitives, config);
   }
   for (const [name, mapping] of Object.entries(SEMANTIC_MAP.surface)) {
-    surface[name] = resolveMapping(mapping, primitives, config);
+    surface[name] = resolveMapping(mapping, lightPrimitives, darkPrimitives, config);
   }
   for (const [name, mapping] of Object.entries(SEMANTIC_MAP.border)) {
-    border[name] = resolveMapping(mapping, primitives, config);
+    border[name] = resolveMapping(mapping, lightPrimitives, darkPrimitives, config);
   }
   for (const [name, mapping] of Object.entries(SEMANTIC_MAP.interactive)) {
-    interactive[name] = resolveMapping(mapping, primitives, config);
+    interactive[name] = resolveMapping(mapping, lightPrimitives, darkPrimitives, config);
   }
   return { text, surface, border, interactive };
 }
@@ -1071,6 +1246,18 @@ function generatePrimitives(config) {
     info: generateShadeScale(config.colors.info, "info")
   };
 }
+function generateDarkPrimitives(config, lightPrimitives) {
+  const cd = config["colors-dark"];
+  return {
+    primary: cd?.primary ? generateShadeScale(cd.primary, "primary") : lightPrimitives.primary,
+    accent: cd?.accent ? generateShadeScale(cd.accent, "accent") : lightPrimitives.accent,
+    neutral: cd?.neutral ? config.colors.neutral === null ? TAILWIND_GRAY : generateShadeScale(cd.neutral, "neutral") : lightPrimitives.neutral,
+    success: cd?.success ? generateShadeScale(cd.success, "success") : lightPrimitives.success,
+    warning: cd?.warning ? generateShadeScale(cd.warning, "warning") : lightPrimitives.warning,
+    error: cd?.error ? generateShadeScale(cd.error, "error") : lightPrimitives.error,
+    info: cd?.info ? generateShadeScale(cd.info, "info") : lightPrimitives.info
+  };
+}
 function parseConfig(yamlString) {
   const parsed = parseYaml(yamlString);
   const result = validateConfig(parsed);
@@ -1103,7 +1290,8 @@ ${validation.errors.map((e) => `  - ${e}`).join("\n")}`
   }
   const resolved = resolveConfig(config);
   const primitives = generatePrimitives(resolved);
-  let tokens = assignSemanticTokens(primitives, resolved);
+  const darkPrimitives = generateDarkPrimitives(resolved, primitives);
+  let tokens = assignSemanticTokens(primitives, darkPrimitives, resolved);
   tokens = applyOverrides(tokens, resolved.overrides);
   const output = {
     primitivesCss: generatePrimitivesCss(primitives, resolved),
@@ -1677,35 +1865,75 @@ function colorToRgb(color) {
   const parsed = parseColor(color);
   return parsed ? parsed.rgb : [0, 0, 0];
 }
+var STANDARD_TEXT_TOKENS = ["primary", "secondary", "tertiary"];
+var STATUS_TEXT_TOKENS = ["error", "warning", "success", "info"];
 function checkContrastWarnings(config, issues) {
   const resolved = resolveConfig(config);
+  const lightPrimitives = generatePrimitives(resolved);
+  const darkPrimitives = generateDarkPrimitives(resolved, lightPrimitives);
+  const tokens = applyOverrides(
+    assignSemanticTokens(lightPrimitives, darkPrimitives, resolved),
+    resolved.overrides
+  );
   const lightBg = resolved.colors.background;
   const lightSurface = resolved.colors.surface;
   const primary = resolved.colors.primary;
   const lightBgRgb = colorToRgb(lightBg);
   const lightSurfaceRgb = colorToRgb(lightSurface);
-  const textDark = "#111827";
-  const textOnBg = getContrastRatio(textDark, lightBg, lightBgRgb);
-  if (textOnBg < CONTRAST_TEXT_AA) {
-    issues.push(
-      issue(
-        "warning",
-        "WCAG_CONTRAST",
-        `Light mode: text-primary on background has contrast ratio ${textOnBg.toFixed(2)}:1 (needs >= ${CONTRAST_TEXT_AA}:1)`,
-        "colors.background"
-      )
-    );
-  }
-  const textOnSurface = getContrastRatio(textDark, lightSurface, lightSurfaceRgb);
-  if (textOnSurface < CONTRAST_TEXT_AA) {
-    issues.push(
-      issue(
-        "warning",
-        "WCAG_CONTRAST",
-        `Light mode: text-primary on surface has contrast ratio ${textOnSurface.toFixed(2)}:1 (needs >= ${CONTRAST_TEXT_AA}:1)`,
-        "colors.surface"
-      )
-    );
+  const darkBg = resolved["colors-dark"]?.background ?? "#0a0a0a";
+  const darkSurface = resolved["colors-dark"]?.surface ?? "#171717";
+  const darkPrimary = resolved["colors-dark"]?.primary ?? primary;
+  const darkBgRgb = colorToRgb(darkBg);
+  const darkSurfaceRgb = colorToRgb(darkSurface);
+  const textTokensToCheck = [...STANDARD_TEXT_TOKENS, ...STATUS_TEXT_TOKENS];
+  for (const tokenName of textTokensToCheck) {
+    const tokenValue = tokens.text[tokenName];
+    if (!tokenValue) continue;
+    const fullName = `text-${tokenName}`;
+    const lightOnBg = getContrastRatio(tokenValue.light, lightBg, lightBgRgb);
+    if (lightOnBg < CONTRAST_TEXT_AA) {
+      issues.push(
+        issue(
+          "warning",
+          "WCAG_CONTRAST",
+          `Light mode: ${fullName} on background has contrast ratio ${lightOnBg.toFixed(2)}:1 (needs >= ${CONTRAST_TEXT_AA}:1)`,
+          "colors.background"
+        )
+      );
+    }
+    const lightOnSurface = getContrastRatio(tokenValue.light, lightSurface, lightSurfaceRgb);
+    if (lightOnSurface < CONTRAST_TEXT_AA) {
+      issues.push(
+        issue(
+          "warning",
+          "WCAG_CONTRAST",
+          `Light mode: ${fullName} on surface has contrast ratio ${lightOnSurface.toFixed(2)}:1 (needs >= ${CONTRAST_TEXT_AA}:1)`,
+          "colors.surface"
+        )
+      );
+    }
+    const darkOnBg = getContrastRatio(tokenValue.dark, darkBg, darkBgRgb);
+    if (darkOnBg < CONTRAST_TEXT_AA) {
+      issues.push(
+        issue(
+          "warning",
+          "WCAG_CONTRAST",
+          `Dark mode: ${fullName} on background has contrast ratio ${darkOnBg.toFixed(2)}:1 (needs >= ${CONTRAST_TEXT_AA}:1)`,
+          "colors-dark.background"
+        )
+      );
+    }
+    const darkOnSurface = getContrastRatio(tokenValue.dark, darkSurface, darkSurfaceRgb);
+    if (darkOnSurface < CONTRAST_TEXT_AA) {
+      issues.push(
+        issue(
+          "warning",
+          "WCAG_CONTRAST",
+          `Dark mode: ${fullName} on surface has contrast ratio ${darkOnSurface.toFixed(2)}:1 (needs >= ${CONTRAST_TEXT_AA}:1)`,
+          "colors-dark.surface"
+        )
+      );
+    }
   }
   const primaryOnBg = getContrastRatio(primary, lightBg, lightBgRgb);
   if (primaryOnBg < CONTRAST_INTERACTIVE_AA) {
@@ -1729,34 +1957,6 @@ function checkContrastWarnings(config, issues) {
       )
     );
   }
-  const darkBg = resolved["colors-dark"]?.background ?? "#0a0a0a";
-  const darkSurface = resolved["colors-dark"]?.surface ?? "#171717";
-  const darkPrimary = resolved["colors-dark"]?.primary ?? primary;
-  const darkBgRgb = colorToRgb(darkBg);
-  const darkSurfaceRgb = colorToRgb(darkSurface);
-  const textLight = "#f9fafb";
-  const textOnDarkBg = getContrastRatio(textLight, darkBg, darkBgRgb);
-  if (textOnDarkBg < CONTRAST_TEXT_AA) {
-    issues.push(
-      issue(
-        "warning",
-        "WCAG_CONTRAST",
-        `Dark mode: text-primary on background has contrast ratio ${textOnDarkBg.toFixed(2)}:1 (needs >= ${CONTRAST_TEXT_AA}:1)`,
-        "colors-dark.background"
-      )
-    );
-  }
-  const textOnDarkSurface = getContrastRatio(textLight, darkSurface, darkSurfaceRgb);
-  if (textOnDarkSurface < CONTRAST_TEXT_AA) {
-    issues.push(
-      issue(
-        "warning",
-        "WCAG_CONTRAST",
-        `Dark mode: text-primary on surface has contrast ratio ${textOnDarkSurface.toFixed(2)}:1 (needs >= ${CONTRAST_TEXT_AA}:1)`,
-        "colors-dark.surface"
-      )
-    );
-  }
   const darkPrimaryOnBg = getContrastRatio(darkPrimary, darkBg, darkBgRgb);
   if (darkPrimaryOnBg < CONTRAST_INTERACTIVE_AA) {
     issues.push(

package/dist/{types-DgAumoCX.d.ts → types-ljcTtODU.d.ts}

@@ -124,6 +124,23 @@ interface ParsedColor {
     format: ColorFormat;
     original: string;
 }
+/**
+ * The 15 Material 3 type-scale slots plus Visor's `labelXSmall` extension.
+ *
+ * Per-slot size / weight / letter-spacing can be overridden in
+ * `typography.slots` to tune the generated Flutter `TextTheme` without
+ * touching the global font families.
+ */
+type MaterialTextSlot = "displayLarge" | "displayMedium" | "displaySmall" | "headlineLarge" | "headlineMedium" | "headlineSmall" | "titleLarge" | "titleMedium" | "titleSmall" | "bodyLarge" | "bodyMedium" | "bodySmall" | "labelLarge" | "labelMedium" | "labelSmall" | "labelXSmall";
+/** Per-slot override in `typography.slots.<slot>`. All fields optional. */
+interface TextSlotOverride {
+    /** Font size in logical pixels (Flutter `TextStyle.fontSize`). */
+    size?: number;
+    /** Font weight (100–900, matching Flutter `FontWeight.w100..w900`). */
+    weight?: number;
+    /** Letter spacing in logical pixels (Flutter `TextStyle.letterSpacing`). */
+    "letter-spacing"?: number;
+}
 interface VisorThemeConfig {
     name: string;
     version: 1;
@@ -189,6 +206,13 @@ interface VisorThemeConfig {
             normal?: string;
             wide?: string;
         };
+        /**
+         * Per-slot overrides for the generated Flutter `TextTheme`. Any subset
+         * of the 16 Material slots may be specified; omitted slots fall
+         * through to `VisorTextStylesData.defaults` (Material 3 2024 scale).
+         * Flutter-only — ignored by CSS/NextJS adapters.
+         */
+        slots?: Partial<Record<MaterialTextSlot, TextSlotOverride>>;
     };
     spacing?: {
         base?: number;
@@ -207,6 +231,12 @@ interface VisorThemeConfig {
         lg?: string;
         xl?: string;
     };
+    strokeWidths?: {
+        thin?: number;
+        regular?: number;
+        medium?: number;
+        thick?: number;
+    };
     motion?: {
         "duration-fast"?: string;
         "duration-normal"?: string;
@@ -217,6 +247,21 @@ interface VisorThemeConfig {
         light?: Record<string, string>;
         dark?: Record<string, string>;
     };
+    /**
+     * Migration metadata — optional, additive, consumed by `visor migrate` commands.
+     * Does not affect CSS generation or theme application.
+     */
+    migrate?: {
+        /**
+         * §3.1 V7-primitive → Visor-semantic substitution table.
+         * Maps V7 CSS custom property names (without `var()`) to Visor semantic
+         * token names. Consumed by `visor migrate token-substitution`.
+         *
+         * @example
+         *   { "--panel": "--surface-card", "--text": "--text-primary" }
+         */
+        "token-substitution"?: Record<string, string>;
+    };
 }
 /** Config with all defaults resolved */
 interface ResolvedThemeConfig {
@@ -260,6 +305,12 @@ interface ResolvedThemeConfig {
         mono: {
             family: string;
         };
+        /**
+         * Per-slot Material `TextTheme` overrides, passed through from the
+         * raw config. Empty object when none supplied. Flutter adapter
+         * consumes these; other adapters may ignore them.
+         */
+        slots: Partial<Record<MaterialTextSlot, TextSlotOverride>>;
     };
     spacing: {
         base: number;
@@ -278,6 +329,12 @@ interface ResolvedThemeConfig {
         lg: string;
         xl: string;
     };
+    strokeWidths: {
+        thin: number;
+        regular: number;
+        medium: number;
+        thick: number;
+    };
     motion: {
         "duration-fast": string;
         "duration-normal": string;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@loworbitstudio/visor-theme-engine",
-  "version": "0.4.0",
+  "version": "0.4.2",
   "description": "Theme engine for the Visor design system — shade generation, token mapping, font resolution, and import/export for .visor.yaml themes.",
   "type": "module",
   "main": "./dist/index.js",