@loworbitstudio/visor-theme-engine 0.4.1 → 0.5.0

package/dist/adapters/index.d.ts

@@ -1,4 +1,4 @@
-import { c as GeneratedPrimitives, i as SemanticTokens, R as ResolvedThemeConfig } from '../types-gAlkt__C.js';
+import { c as GeneratedPrimitives, i as SemanticTokens, R as ResolvedThemeConfig } from '../types-ljcTtODU.js';
 
 /**
  * Adapter types for the Visor theme engine.
@@ -139,8 +139,10 @@ declare function deckAdapter(input: AdapterInput, options?: DeckAdapterOptions):
 /**
  * Generate docs-site CSS for a theme.
  *
- * Output is class-scoped (.{slug}-theme) with no @layer wrapping,
- * matching the hand-written theme files in packages/docs/app/.
+ * Output is class-scoped (.{slug}-theme) and wrapped in @layer visor-adaptive
+ * so consumer overrides (unlayered) and visor-core's own visor-adaptive layer
+ * cascade correctly. Font @import / @font-face statements stay outside the
+ * layer block per CSS spec (VI-312).
  */
 declare function docsAdapter(input: AdapterInput, options?: DocsAdapterOptions): string;
 
@@ -177,9 +179,11 @@ declare function flutterAdapter(input: AdapterInput, options?: FlutterAdapterOpt
 /**
  * CSS @layer utilities for adapter output.
  *
- * Establishes a specificity ordering so theme overrides work
- * without !important. Layers are adapter-only — the base
- * generateFullBundleCss output is not wrapped in layers.
+ * Establishes a specificity ordering so theme overrides work without
+ * !important. Both adapter output (here) and visor-core's emitted CSS
+ * (packages/tokens/src/generate/generate-css.ts) declare this same layer
+ * order — defense in depth, so whichever stylesheet loads first establishes
+ * the cascade.
  */
 /** Layer order declaration — must appear before any @layer blocks. */
 declare const LAYER_ORDER = "@layer visor-primitives, visor-semantic, visor-adaptive, visor-bridge;";

package/dist/adapters/index.js

@@ -11,7 +11,7 @@ import {
   parseColor,
   resolveThemeFonts,
   sectionComment
-} from "../chunk-G4B57FB3.js";
+} from "../chunk-U5FXQ5EC.js";
 
 // src/adapters/layers.ts
 var LAYER_ORDER = "@layer visor-primitives, visor-semantic, visor-adaptive, visor-bridge;";
@@ -418,6 +418,7 @@ function docsAdapter(input, options) {
   const slug = toKebabCase2(input.config.name);
   const scopeClass = `.${slug}-theme`;
   const includeFontImports = options?.includeFontImports ?? true;
+  const fontLines = [];
   const lines = [];
   if (includeFontImports && input.config.typography) {
     const fontResult = resolveThemeFonts(input.config.typography);
@@ -426,8 +427,8 @@ function docsAdapter(input, options) {
     for (const font of fontSlots) {
       if (font && font.source === "google-fonts" && font.cssUrl && !seenUrls.has(font.cssUrl)) {
         seenUrls.add(font.cssUrl);
-        lines.push(`@import url("${font.cssUrl}");`);
-        lines.push("");
+        fontLines.push(`@import url("${font.cssUrl}");`);
+        fontLines.push("");
       }
     }
     const scale = input.config.typography?.scale ?? 1;
@@ -437,17 +438,17 @@ function docsAdapter(input, options) {
         seenFamilies.add(font.family);
         for (const weight of font.weights) {
           const url = buildVisorFontUrl(font.org ?? "", font.family, weight);
-          lines.push("@font-face {");
-          lines.push(`  font-family: "${font.family}";`);
-          lines.push(`  src: url("${url}") format("woff2");`);
-          lines.push(`  font-weight: ${weight};`);
-          lines.push(`  font-style: ${font.italic ? "italic" : "normal"};`);
-          lines.push(`  font-display: ${font.display};`);
+          fontLines.push("@font-face {");
+          fontLines.push(`  font-family: "${font.family}";`);
+          fontLines.push(`  src: url("${url}") format("woff2");`);
+          fontLines.push(`  font-weight: ${weight};`);
+          fontLines.push(`  font-style: ${font.italic ? "italic" : "normal"};`);
+          fontLines.push(`  font-display: ${font.display};`);
           if (scale !== 1) {
-            lines.push(`  size-adjust: ${Math.round(scale * 100)}%;`);
+            fontLines.push(`  size-adjust: ${Math.round(scale * 100)}%;`);
           }
-          lines.push("}");
-          lines.push("");
+          fontLines.push("}");
+          fontLines.push("");
         }
       }
     }
@@ -562,7 +563,9 @@ ${inner.split("\n").map((l) => `  ${l}`).join("\n")}
   lines.push(sectionComment2("Fumadocs bridge: light"));
   lines.push(block(`html:not(.dark) ${scopeClass}`, generateFumadocsBridgeDecls(input.tokens, "light")));
   lines.push("");
-  return lines.join("\n") + "\n";
+  const layered = wrapInLayer("visor-adaptive", lines.join("\n").trim());
+  const head = fontLines.length > 0 ? fontLines.join("\n") + "\n" : "";
+  return head + LAYER_ORDER + "\n\n" + layered + "\n";
 }
 
 // src/flutter/color-to-dart.ts

package/dist/{chunk-G4B57FB3.js → chunk-U5FXQ5EC.js}

@@ -116,6 +116,21 @@ function lookupGoogleFont(family) {
   return catalogMap.get(family.toLowerCase());
 }
 
+// src/fonts/font-aliases.ts
+var FONT_WEIGHT_ALIASES = {
+  "PP Model Mono": {
+    400: "Book",
+    800: "Super"
+  },
+  "PP Model Plastic": {
+    400: "Book",
+    800: "Super"
+  }
+};
+function lookupFontWeightAlias(family, weight) {
+  return FONT_WEIGHT_ALIASES[family]?.[weight] ?? null;
+}
+
 // src/fonts/resolve.ts
 var DEFAULT_WEIGHTS = [400, 700];
 var DEFAULT_DISPLAY = "swap";
@@ -156,7 +171,7 @@ var WEIGHT_NAMES = {
 function buildVisorFontUrl(org, family, weight) {
   const slug = buildFamilySlug(family);
   const prefix = buildFamilyPrefix(family);
-  const weightName = WEIGHT_NAMES[weight] ?? `W${weight}`;
+  const weightName = lookupFontWeightAlias(family, weight) ?? WEIGHT_NAMES[weight] ?? `W${weight}`;
   return `${VISOR_FONTS_CDN}/${org}/${slug}/${prefix}-${weightName}.woff2`;
 }
 function resolveFont(family, options = {}) {
@@ -964,8 +979,11 @@ var LIGHTNESS_TARGETS = {
   200: 0.87,
   300: 0.78,
   400: 0.65,
-  500: -1,
-  // placeholder — replaced by input L at anchor (brand color lives at 500)
+  // 500 is the reference midpoint (Tailwind gray-500's OKLCH L ≈ 0.55).
+  // At the anchor shade the input L is used directly; this value seeds the
+  // interpolation math in computeLightness() for inputs that don't land at
+  // the reference midpoint.
+  500: 0.55,
   600: 0.45,
   700: 0.38,
   800: 0.3,
@@ -1012,20 +1030,20 @@ function computeLightness(step, inputL, anchorShade) {
   if (step === anchorShade) {
     return inputL;
   }
-  const anchorTarget = anchorShade === 600 ? inputL : LIGHTNESS_TARGETS[anchorShade];
+  const anchorTarget = LIGHTNESS_TARGETS[anchorShade];
   const stepTarget = LIGHTNESS_TARGETS[step];
   if (Math.abs(anchorTarget - inputL) < 0.01) {
     return stepTarget;
   }
   if (step < anchorShade) {
-    const anchorDefaultL = anchorShade === 600 ? 0.45 : LIGHTNESS_TARGETS[anchorShade];
+    const anchorDefaultL = LIGHTNESS_TARGETS[anchorShade];
     const rawRange = 0.97 - anchorDefaultL;
     const newRange = 0.97 - inputL;
     if (rawRange <= 0) return stepTarget;
     const t = (stepTarget - anchorDefaultL) / rawRange;
     return inputL + t * newRange;
   } else {
-    const anchorDefaultL = anchorShade === 600 ? 0.45 : LIGHTNESS_TARGETS[anchorShade];
+    const anchorDefaultL = LIGHTNESS_TARGETS[anchorShade];
     const rawRange = anchorDefaultL - 0.14;
     const newRange = inputL - 0.14;
     if (rawRange <= 0) return stepTarget;
@@ -1043,7 +1061,7 @@ function generateShadeScale(color, role) {
   for (const step of steps) {
     const targetL = computeLightness(step, inputL, anchorShade);
     let targetC = inputC * CHROMA_MULTIPLIERS[step];
-    if (role === "neutral") {
+    if (role === "neutral" && step !== anchorShade) {
       targetC = Math.min(targetC, maxNeutralChroma);
     }
     scale[step] = oklchToHex(targetL, targetC, inputH);
@@ -1389,6 +1407,8 @@ var MATERIAL_TEXT_SLOTS = [
 export {
   googleFontsCatalog,
   lookupGoogleFont,
+  FONT_WEIGHT_ALIASES,
+  lookupFontWeightAlias,
   VISOR_FONTS_CDN,
   buildVisorFontUrl,
   resolveFont,

package/dist/index.d.ts

@@ -1,5 +1,5 @@
-import { F as FontResolveOptions, a as FontResolution, V as VisorTypography, b as FontDisplayStrategy, T as ThemeFontResult, G as GoogleFontEntry, R as ResolvedThemeConfig, c as GeneratedPrimitives, d as ThemeOutput, e as ThemeData, f as VisorThemeConfig, g as FullShadeScale, C as ColorRole, S as SelectiveShadeScale, h as RGB, P as ParsedColor, O as OKLCH, i as SemanticTokens, j as ShadeStep } from './types-gAlkt__C.js';
-export { k as ColorFormat, l as FontSource, m as RGBA, n as SemanticTokenValue } from './types-gAlkt__C.js';
+import { F as FontResolveOptions, a as FontResolution, V as VisorTypography, b as FontDisplayStrategy, T as ThemeFontResult, G as GoogleFontEntry, R as ResolvedThemeConfig, c as GeneratedPrimitives, d as ThemeOutput, e as ThemeData, f as VisorThemeConfig, g as FullShadeScale, C as ColorRole, S as SelectiveShadeScale, h as RGB, P as ParsedColor, O as OKLCH, i as SemanticTokens, j as ShadeStep } from './types-ljcTtODU.js';
+export { k as ColorFormat, l as FontSource, m as RGBA, n as SemanticTokenValue } from './types-ljcTtODU.js';
 
 /**
  * Font resolver — maps font family names to loadable font resources.
@@ -28,6 +28,22 @@ declare function buildVisorFontUrl(org: string, family: string, weight: number):
  */
 declare function resolveFont(family: string, options?: FontResolveOptions): FontResolution;
 
+/**
+ * Font weight-name alias registry for the Visor Fonts CDN URL builder.
+ *
+ * Standard PostScript naming (Light/Regular/Medium/Bold/ExtraBold/Black)
+ * is handled by the WEIGHT_NAMES table in resolve.ts. Foundries that use
+ * non-standard names (e.g. Pangram Pangram's `Book` and `Super`) register
+ * per-family overrides here so theme authors can keep writing standard
+ * weight numbers in their .visor.yaml files.
+ *
+ * Family keys are exact-match (case-sensitive); weight keys are the numeric
+ * weight (300, 400, 500, …) as in WEIGHT_NAMES. The mapped string is the
+ * PostScript-style suffix that follows `{Family}-` in the bucket filename.
+ */
+declare const FONT_WEIGHT_ALIASES: Record<string, Record<number, string>>;
+declare function lookupFontWeightAlias(family: string, weight: number): string | null;
+
 /**
  * Preload hint generation for font loading performance.
  *
@@ -556,6 +572,20 @@ var properties = {
 				}
 			}
 		}
+	},
+	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: "§3.1 V7-primitive → 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"
+				}
+			}
+		}
 	}
 };
 var $defs = {
@@ -898,4 +928,4 @@ declare function cleanFontValue(val: string): string;
  */
 declare function extractFromCSS(files: CSSFile[], name?: string): ExtractionResult;
 
-export { type CSSFile, ColorRole, type Confidence, type ExtractedToken, type ExtractionResult, FontDisplayStrategy, type FontFaceDeclaration, FontResolution, FontResolveOptions, FullShadeScale, GeneratedPrimitives, GoogleFontEntry, OKLCH, ParsedColor, RGB, ResolvedThemeConfig, SEMANTIC_MAP, SelectiveShadeScale, SemanticTokens, ShadeStep, TAILWIND_GRAY, ThemeData, ThemeFontResult, ThemeOutput, type ThemeValidationResult, VISOR_FONTS_CDN, type ValidationIssue, type ValidationSeverity, VisorThemeConfig, VisorTypography, applyOverrides, assignSemanticTokens, buildVisorFontUrl, clampToSrgb, cleanFontValue, compositeOverBackground, exportTheme, extractFromCSS, generateDarkCss, generateFullBundleCss, generateLightCss, generatePreloadLinks, generatePrimitives, generatePrimitivesCss, generateSemanticCss, generateShadeScale, generateStylesheetLinks, generateTheme, generateThemeData, generateThemeDataFromConfig, generateThemeFromConfig, getContrastRatio, googleFontsCatalog, hexToOklch, hexToRgb, isValidColor, isValidHex, isVisorThemeConfig, lookupGoogleFont, normalizeHex, oklchToHex, parseCSSDeclarations, parseColor, parseConfig, parseFontFaceDeclarations, parseHex, parseHsla, parseOklch, parseRgba, resolveConfig, resolveFont, resolveThemeFonts, rgbToHex, serializeColor, validate, validateConfig, visorTheme_schema as visorThemeSchema };
+export { type CSSFile, ColorRole, type Confidence, type ExtractedToken, type ExtractionResult, FONT_WEIGHT_ALIASES, FontDisplayStrategy, type FontFaceDeclaration, FontResolution, FontResolveOptions, FullShadeScale, GeneratedPrimitives, GoogleFontEntry, OKLCH, ParsedColor, RGB, ResolvedThemeConfig, SEMANTIC_MAP, SelectiveShadeScale, SemanticTokens, ShadeStep, TAILWIND_GRAY, ThemeData, ThemeFontResult, ThemeOutput, type ThemeValidationResult, VISOR_FONTS_CDN, type ValidationIssue, type ValidationSeverity, VisorThemeConfig, VisorTypography, applyOverrides, assignSemanticTokens, buildVisorFontUrl, clampToSrgb, cleanFontValue, compositeOverBackground, exportTheme, extractFromCSS, generateDarkCss, generateFullBundleCss, generateLightCss, generatePreloadLinks, generatePrimitives, generatePrimitivesCss, generateSemanticCss, generateShadeScale, generateStylesheetLinks, generateTheme, generateThemeData, generateThemeDataFromConfig, generateThemeFromConfig, getContrastRatio, googleFontsCatalog, hexToOklch, hexToRgb, isValidColor, isValidHex, isVisorThemeConfig, lookupFontWeightAlias, lookupGoogleFont, normalizeHex, oklchToHex, parseCSSDeclarations, parseColor, parseConfig, parseFontFaceDeclarations, parseHex, parseHsla, parseOklch, parseRgba, resolveConfig, resolveFont, resolveThemeFonts, rgbToHex, serializeColor, validate, validateConfig, visorTheme_schema as visorThemeSchema };

package/dist/index.js

@@ -1,4 +1,5 @@
 import {
+  FONT_WEIGHT_ALIASES,
   MATERIAL_TEXT_SLOTS,
   TAILWIND_GRAY,
   VISOR_FONTS_CDN,
@@ -19,6 +20,7 @@ import {
   hexToRgb,
   isValidColor,
   isValidHex,
+  lookupFontWeightAlias,
   lookupGoogleFont,
   normalizeHex,
   oklchToHex,
@@ -32,7 +34,7 @@ import {
   rgbToHex,
   rgbToOklch,
   serializeColor
-} from "./chunk-G4B57FB3.js";
+} from "./chunk-U5FXQ5EC.js";
 
 // src/pipeline.ts
 import { parse as parseYaml } from "yaml";
@@ -339,6 +341,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: {
@@ -839,13 +853,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 },
@@ -976,6 +994,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 = {
@@ -1826,35 +1867,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) {
@@ -1878,34 +1959,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(
@@ -2575,6 +2628,7 @@ function extractFromCSS(files, name = "extracted-theme") {
   return { config, tokens, unmapped, warnings };
 }
 export {
+  FONT_WEIGHT_ALIASES,
   SEMANTIC_MAP,
   TAILWIND_GRAY,
   VISOR_FONTS_CDN,
@@ -2606,6 +2660,7 @@ export {
   isValidColor,
   isValidHex,
   isVisorThemeConfig,
+  lookupFontWeightAlias,
   lookupGoogleFont,
   normalizeHex,
   oklchToHex,

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

@@ -247,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 {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@loworbitstudio/visor-theme-engine",
-  "version": "0.4.1",
+  "version": "0.5.0",
   "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",

package/src/visor-theme.schema.json

@@ -299,6 +299,18 @@
           "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": "§3.1 V7-primitive → 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": {