@loworbitstudio/visor-theme-engine 0.4.1 → 0.4.2

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-SXT2KY6D.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-SXT2KY6D.js}

@@ -964,8 +964,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 +1015,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 +1046,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);

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.
@@ -556,6 +556,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 = {

package/dist/index.js

@@ -32,7 +32,7 @@ import {
   rgbToHex,
   rgbToOklch,
   serializeColor
-} from "./chunk-G4B57FB3.js";
+} from "./chunk-SXT2KY6D.js";
 
 // src/pipeline.ts
 import { parse as parseYaml } from "yaml";
@@ -339,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: {
@@ -839,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 },
@@ -976,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 = {
@@ -1826,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) {
@@ -1878,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-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.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",

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": {