@loworbitstudio/visor-theme-engine 0.13.0 → 0.15.0

package/dist/adapters/index.d.ts

@@ -1,4 +1,4 @@
-import { g as GeneratedPrimitives, m as SemanticTokens, R as ResolvedThemeConfig } from '../types-CSO2avFQ.js';
+import { g as GeneratedPrimitives, m as SemanticTokens, R as ResolvedThemeConfig } from '../types-zug1_eLX.js';
 
 /**
  * Adapter types for the Visor theme engine.

package/dist/adapters/index.js

@@ -3,7 +3,9 @@ import {
   MATERIAL_TEXT_SLOTS,
   SELECTIVE_SHADE_STEPS,
   aliasFamily,
+  block,
   buildVisorFontUrl,
+  collectBrandPassthrough,
   fontStack,
   generateDarkCss,
   generateHairlineDecls,
@@ -18,7 +20,53 @@ import {
   resolveThemeBrand,
   resolveThemeFonts,
   sectionComment
-} from "../chunk-KFTTL3XP.js";
+} from "../chunk-DQ256PSE.js";
+
+// src/adapters/brand-passthrough.ts
+var SENTINEL_COLOR = "#ff00ff";
+function isDevBuild() {
+  return process.env.NODE_ENV !== "production";
+}
+function isUnresolved(value) {
+  return typeof value !== "string" || value.trim().length === 0;
+}
+function declFor(key, value) {
+  if (isUnresolved(value)) {
+    if (isDevBuild()) {
+      return `--${key}: ${SENTINEL_COLOR}; /* [visor-brand] UNRESOLVED pass-through value */`;
+    }
+    return `--${key}: ${value};`;
+  }
+  return `--${key}: ${value};`;
+}
+function indentBlock(selector, decls) {
+  if (decls.length === 0) return "";
+  return [selector + " {", ...decls.map((d) => `  ${d}`), "}"].join("\n");
+}
+function generateBrandPassthroughCss(passthrough, selectors) {
+  const lightKeys = Object.keys(passthrough.light);
+  const darkKeys = Object.keys(passthrough.dark);
+  if (lightKeys.length === 0 && darkKeys.length === 0) return "";
+  const blocks = [];
+  if (isDevBuild()) {
+    const names = [.../* @__PURE__ */ new Set([...lightKeys, ...darkKeys])].map((k) => `--${k}`).join(", ");
+    const count = lightKeys.length + darkKeys.length;
+    blocks.push(`/* [visor-brand] ${count} passthrough: ${names} */`);
+  }
+  if (lightKeys.length > 0) {
+    const decls = lightKeys.map((k) => declFor(k, passthrough.light[k]));
+    blocks.push(indentBlock(selectors.light, decls));
+  }
+  if (darkKeys.length > 0) {
+    const decls = darkKeys.map((k) => declFor(k, passthrough.dark[k]));
+    blocks.push(indentBlock(selectors.dark, decls));
+    const prefersInner = indentBlock(selectors.prefers, decls).split("\n").map((l) => `  ${l}`).join("\n");
+    blocks.push(`@media (prefers-color-scheme: dark) {
+${prefersInner}
+}`);
+  }
+  return blocks.filter(Boolean).join("\n\n");
+}
 
 // src/adapters/layers.ts
 var LAYER_ORDER = "@layer visor-primitives, visor-semantic, visor-brand, visor-adaptive, visor-bridge;";
@@ -102,6 +150,62 @@ function nextjsAdapter(input, options) {
   );
   lines.push(wrapInLayer("visor-primitives", primitivesBody));
   lines.push("");
+  const passthrough = collectBrandPassthrough(input.tokens, input.config.overrides);
+  const darkSelectors = scopePrefix ? [`${scopePrefix}.dark`, `${scopePrefix}.theme-dark`, `${scopePrefix}[data-theme="dark"]`] : [".dark", ".theme-dark", '[data-theme="dark"]'];
+  const passthroughCss = generateBrandPassthroughCss(passthrough, {
+    light: scopePrefix ?? ":root",
+    dark: darkSelectors.join(",\n"),
+    prefers: scopePrefix ? `${scopePrefix}:not(.light):not(.theme-light):not([data-theme="light"])` : ':root:not(.light):not(.theme-light):not([data-theme="light"])'
+  });
+  if (passthroughCss) {
+    lines.push(wrapInLayer("visor-brand", passthroughCss));
+    lines.push("");
+  }
+  const hostSelector = scopePrefix ?? ":root";
+  const lightModeSelector = `html:not(.dark) ${scopePrefix ?? ""}`.trim();
+  const darkModeSelector = `html.dark ${scopePrefix ?? ""}`.trim();
+  const prefersSelector = scopePrefix ? `${scopePrefix}:not(.light):not(.theme-light):not([data-theme="light"])` : ':root:not(.light):not(.theme-light):not([data-theme="light"])';
+  const semanticLines = [];
+  semanticLines.push("/* \u2500\u2500 Layer: Semantic aliases (VI-453) \u2500\u2500 */");
+  semanticLines.push(sectionComment("Discrete: Text size aliases (--text-N)"));
+  semanticLines.push(block(hostSelector, generateTextScaleAliasDecls()));
+  semanticLines.push("");
+  semanticLines.push(sectionComment("Discrete: Space aliases (--space-N)"));
+  semanticLines.push(block(hostSelector, generateSpaceAliasDecls(input.config)));
+  semanticLines.push("");
+  semanticLines.push(sectionComment("Intent aliases (light)"));
+  semanticLines.push(block(lightModeSelector, generateIntentDecls(input.tokens, "light")));
+  semanticLines.push("");
+  semanticLines.push(sectionComment("Hairline aliases (light)"));
+  semanticLines.push(block(lightModeSelector, generateHairlineDecls(input.tokens, "light")));
+  semanticLines.push("");
+  semanticLines.push(sectionComment("Intent aliases (dark) \u2014 manual toggle"));
+  semanticLines.push(block(darkModeSelector, generateIntentDecls(input.tokens, "dark")));
+  semanticLines.push("");
+  semanticLines.push(sectionComment("Hairline aliases (dark) \u2014 manual toggle"));
+  semanticLines.push(block(darkModeSelector, generateHairlineDecls(input.tokens, "dark")));
+  semanticLines.push("");
+  semanticLines.push(sectionComment("Intent aliases (dark) \u2014 prefers-color-scheme"));
+  {
+    const inner = block(prefersSelector, generateIntentDecls(input.tokens, "dark"));
+    semanticLines.push(`@media (prefers-color-scheme: dark) {
+${inner.split("\n").map((l) => `  ${l}`).join("\n")}
+}`);
+  }
+  semanticLines.push("");
+  semanticLines.push(sectionComment("Hairline aliases (dark) \u2014 prefers-color-scheme"));
+  {
+    const inner = block(prefersSelector, generateHairlineDecls(input.tokens, "dark"));
+    semanticLines.push(`@media (prefers-color-scheme: dark) {
+${inner.split("\n").map((l) => `  ${l}`).join("\n")}
+}`);
+  }
+  semanticLines.push("");
+  const semanticLayer = wrapInLayer("visor-semantic", semanticLines.join("\n").trim());
+  if (semanticLayer) {
+    lines.push(semanticLayer);
+    lines.push("");
+  }
   const lightBody = stripHeader(generateLightCss(input.tokens, { scopePrefix }));
   const darkBody = stripHeader(generateDarkCss(input.tokens, { scopePrefix }));
   lines.push(
@@ -357,7 +461,15 @@ function generateTypographyDecls(config, aliases) {
   for (const [name, value] of Object.entries(lineHeights)) {
     decls.push(`--line-height-${name}: ${value};`);
   }
-  decls.push("--letter-spacing-normal: 0.05em;");
+  const ls = config.typography["letter-spacing"];
+  decls.push(`--letter-spacing-xl: ${ls.xl};`);
+  decls.push(`--letter-spacing-lg: ${ls.lg};`);
+  decls.push(`--letter-spacing-md: ${ls.md};`);
+  decls.push(`--letter-spacing-sm: ${ls.sm};`);
+  decls.push(`--letter-spacing-xs: ${ls.xs};`);
+  decls.push(`--letter-spacing-tight: ${ls.tight};`);
+  decls.push(`--letter-spacing-normal: ${ls.md};`);
+  decls.push(`--letter-spacing-wide: ${ls.lg};`);
   return decls;
 }
 function generateShadowDecls(config) {
@@ -377,6 +489,7 @@ function generateMotionDecls(config) {
     "--motion-duration-300: 300ms;",
     `--motion-duration-500: ${config.motion["duration-slow"]};`,
     "--motion-duration-800: 800ms;",
+    "--motion-duration-1500: 1500ms;",
     "--motion-easing-linear: linear;",
     "--motion-easing-ease-in: cubic-bezier(0.4, 0, 1, 1);",
     "--motion-easing-ease-out: cubic-bezier(0, 0, 0.2, 1);",
@@ -431,7 +544,7 @@ function generateFumadocsBridgeDecls(tokens, mode) {
   }
   return decls;
 }
-function block(selector, decls) {
+function block2(selector, decls) {
   return [`${selector} {`, ...decls.map((d) => `  ${d}`), "}"].join("\n");
 }
 function sectionComment2(label) {
@@ -493,29 +606,29 @@ function docsAdapter(input, options) {
     "font-family: var(--font-sans);"
   ];
   lines.push(sectionComment2("Primitive: Colors"));
-  lines.push(block(scopeClass, [
+  lines.push(block2(scopeClass, [
     ...sharedDecls,
     "",
     ...generateColorDecls(input.primitives)
   ]));
   lines.push("");
   lines.push(sectionComment2("Primitive: Spacing"));
-  lines.push(block(scopeClass, generateSpacingDecls(input.config)));
+  lines.push(block2(scopeClass, generateSpacingDecls(input.config)));
   lines.push("");
   lines.push(sectionComment2("Primitive: Border Radius"));
-  lines.push(block(scopeClass, generateRadiusDecls(input.config)));
+  lines.push(block2(scopeClass, generateRadiusDecls(input.config)));
   lines.push("");
   lines.push(sectionComment2("Primitive: Typography"));
-  lines.push(block(scopeClass, generateTypographyDecls(input.config, aliasedFamilies)));
+  lines.push(block2(scopeClass, generateTypographyDecls(input.config, aliasedFamilies)));
   lines.push("");
   lines.push(sectionComment2("Primitive: Shadows"));
-  lines.push(block(scopeClass, generateShadowDecls(input.config)));
+  lines.push(block2(scopeClass, generateShadowDecls(input.config)));
   lines.push("");
   lines.push(sectionComment2("Primitive: Motion"));
-  lines.push(block(scopeClass, generateMotionDecls(input.config)));
+  lines.push(block2(scopeClass, generateMotionDecls(input.config)));
   lines.push("");
   lines.push(sectionComment2("Primitive: Miscellaneous"));
-  lines.push(block(scopeClass, generateMiscDecls()));
+  lines.push(block2(scopeClass, generateMiscDecls()));
   lines.push("");
   lines.push("\n/* \u2500\u2500 Section 2: Dark mode overrides \u2500\u2500 */");
   const darkDecls = generateSemanticDecls2(input.tokens, "dark");
@@ -539,7 +652,7 @@ function docsAdapter(input, options) {
   }
   if (darkPrimitiveOverrides.length > 0) {
     lines.push(sectionComment2("Primitive overrides (dark) \u2014 dark brand color anchors at shade 500"));
-    lines.push(block(`.dark ${scopeClass}`, darkPrimitiveOverrides));
+    lines.push(block2(`.dark ${scopeClass}`, darkPrimitiveOverrides));
     lines.push("");
   }
   const categories = ["Text", "Surface", "Border", "Interactive"];
@@ -551,7 +664,7 @@ function docsAdapter(input, options) {
   ];
   for (let i = 0; i < categories.length; i++) {
     lines.push(sectionComment2(`Adaptive: ${categories[i]} (dark) \u2014 manual toggle`));
-    lines.push(block(`.dark ${scopeClass}`, categoryDecls[i]));
+    lines.push(block2(`.dark ${scopeClass}`, categoryDecls[i]));
     lines.push("");
   }
   const pcsCategories = [
@@ -562,7 +675,7 @@ function docsAdapter(input, options) {
   ];
   for (const cat of pcsCategories) {
     lines.push(sectionComment2(`Adaptive: ${cat.label} (dark) \u2014 prefers-color-scheme`));
-    const inner = block(`${scopeClass}:not(.light)`, cat.entries);
+    const inner = block2(`${scopeClass}:not(.light):not(.theme-light):not([data-theme="light"])`, cat.entries);
     lines.push(`@media (prefers-color-scheme: dark) {
 ${inner.split("\n").map((l) => `  ${l}`).join("\n")}
 }`);
@@ -570,7 +683,7 @@ ${inner.split("\n").map((l) => `  ${l}`).join("\n")}
   }
   if (darkPrimitiveOverrides.length > 0) {
     lines.push(sectionComment2("Primitive overrides (dark) \u2014 prefers-color-scheme"));
-    const inner = block(`${scopeClass}:not(.light)`, darkPrimitiveOverrides);
+    const inner = block2(`${scopeClass}:not(.light):not(.theme-light):not([data-theme="light"])`, darkPrimitiveOverrides);
     lines.push(`@media (prefers-color-scheme: dark) {
 ${inner.split("\n").map((l) => `  ${l}`).join("\n")}
 }`);
@@ -585,38 +698,38 @@ ${inner.split("\n").map((l) => `  ${l}`).join("\n")}
   ];
   for (const cat of lightCategoryDecls) {
     lines.push(sectionComment2(`Adaptive: ${cat.label} (light)`));
-    lines.push(block(`html:not(.dark) ${scopeClass}`, cat.entries));
+    lines.push(block2(`html:not(.dark) ${scopeClass}`, cat.entries));
     lines.push("");
   }
   lines.push(sectionComment2("Fumadocs bridge: dark"));
-  lines.push(block(`.dark ${scopeClass}`, generateFumadocsBridgeDecls(input.tokens, "dark")));
+  lines.push(block2(`.dark ${scopeClass}`, generateFumadocsBridgeDecls(input.tokens, "dark")));
   lines.push("");
   lines.push(sectionComment2("Fumadocs bridge: light"));
-  lines.push(block(`html:not(.dark) ${scopeClass}`, generateFumadocsBridgeDecls(input.tokens, "light")));
+  lines.push(block2(`html:not(.dark) ${scopeClass}`, generateFumadocsBridgeDecls(input.tokens, "light")));
   lines.push("");
   const semanticLines = [];
   semanticLines.push("\n/* \u2500\u2500 Layer: Semantic aliases (VI-451) \u2500\u2500 */");
   semanticLines.push(sectionComment2("Discrete: Text size aliases (--text-N)"));
-  semanticLines.push(block(scopeClass, generateTextScaleAliasDecls()));
+  semanticLines.push(block2(scopeClass, generateTextScaleAliasDecls()));
   semanticLines.push("");
   semanticLines.push(sectionComment2("Discrete: Space aliases (--space-N)"));
-  semanticLines.push(block(scopeClass, generateSpaceAliasDecls(input.config)));
+  semanticLines.push(block2(scopeClass, generateSpaceAliasDecls(input.config)));
   semanticLines.push("");
   semanticLines.push(sectionComment2("Intent aliases (light)"));
-  semanticLines.push(block(`html:not(.dark) ${scopeClass}`, generateIntentDecls(input.tokens, "light")));
+  semanticLines.push(block2(`html:not(.dark) ${scopeClass}`, generateIntentDecls(input.tokens, "light")));
   semanticLines.push("");
   semanticLines.push(sectionComment2("Hairline aliases (light)"));
-  semanticLines.push(block(`html:not(.dark) ${scopeClass}`, generateHairlineDecls(input.tokens, "light")));
+  semanticLines.push(block2(`html:not(.dark) ${scopeClass}`, generateHairlineDecls(input.tokens, "light")));
   semanticLines.push("");
   semanticLines.push(sectionComment2("Intent aliases (dark) \u2014 manual toggle"));
-  semanticLines.push(block(`.dark ${scopeClass}`, generateIntentDecls(input.tokens, "dark")));
+  semanticLines.push(block2(`.dark ${scopeClass}`, generateIntentDecls(input.tokens, "dark")));
   semanticLines.push("");
   semanticLines.push(sectionComment2("Hairline aliases (dark) \u2014 manual toggle"));
-  semanticLines.push(block(`.dark ${scopeClass}`, generateHairlineDecls(input.tokens, "dark")));
+  semanticLines.push(block2(`.dark ${scopeClass}`, generateHairlineDecls(input.tokens, "dark")));
   semanticLines.push("");
   semanticLines.push(sectionComment2("Intent aliases (dark) \u2014 prefers-color-scheme"));
   {
-    const inner = block(`${scopeClass}:not(.light)`, generateIntentDecls(input.tokens, "dark"));
+    const inner = block2(`${scopeClass}:not(.light):not(.theme-light):not([data-theme="light"])`, generateIntentDecls(input.tokens, "dark"));
     semanticLines.push(`@media (prefers-color-scheme: dark) {
 ${inner.split("\n").map((l) => `  ${l}`).join("\n")}
 }`);
@@ -624,16 +737,25 @@ ${inner.split("\n").map((l) => `  ${l}`).join("\n")}
   semanticLines.push("");
   semanticLines.push(sectionComment2("Hairline aliases (dark) \u2014 prefers-color-scheme"));
   {
-    const inner = block(`${scopeClass}:not(.light)`, generateHairlineDecls(input.tokens, "dark"));
+    const inner = block2(`${scopeClass}:not(.light):not(.theme-light):not([data-theme="light"])`, generateHairlineDecls(input.tokens, "dark"));
     semanticLines.push(`@media (prefers-color-scheme: dark) {
 ${inner.split("\n").map((l) => `  ${l}`).join("\n")}
 }`);
   }
   semanticLines.push("");
   const brandResult = resolveThemeBrand(input.config.brand, { scope: scopeClass });
+  const passthroughCss = generateBrandPassthroughCss(
+    collectBrandPassthrough(input.tokens, input.config.overrides),
+    {
+      light: `html:not(.dark) ${scopeClass}`,
+      dark: `.dark ${scopeClass}`,
+      prefers: `${scopeClass}:not(.light):not(.theme-light):not([data-theme="light"])`
+    }
+  );
   const adaptiveLayer = wrapInLayer("visor-adaptive", lines.join("\n").trim());
   const semanticLayer = wrapInLayer("visor-semantic", semanticLines.join("\n").trim());
-  const brandLayer = wrapInLayer("visor-brand", brandResult.css);
+  const brandLayerBody = [brandResult.css, passthroughCss].filter(Boolean).join("\n\n");
+  const brandLayer = wrapInLayer("visor-brand", brandLayerBody);
   const head = fontLines.length > 0 ? fontLines.join("\n") + "\n" : "";
   const layerBlocks = [semanticLayer, brandLayer, adaptiveLayer].filter(Boolean);
   return head + LAYER_ORDER + "\n\n" + layerBlocks.join("\n\n") + "\n";

package/dist/{chunk-KFTTL3XP.js → chunk-DQ256PSE.js}

@@ -1347,6 +1347,91 @@ function generateShadeScale(color, role) {
   return scale;
 }
 
+// src/overrides.ts
+var TOKEN_CATEGORIES = [
+  { prefix: "text-", key: "text" },
+  { prefix: "surface-", key: "surface" },
+  { prefix: "border-", key: "border" },
+  { prefix: "interactive-", key: "interactive" },
+  { prefix: "hairline-", key: "hairline" }
+];
+function findToken(key, tokens) {
+  if (key === "hairline" && "default" in tokens.hairline) {
+    return { group: tokens.hairline, name: "default" };
+  }
+  for (const { prefix, key: groupKey } of TOKEN_CATEGORIES) {
+    if (key.startsWith(prefix)) {
+      const name = key.slice(prefix.length);
+      if (name in tokens[groupKey]) {
+        return { group: tokens[groupKey], name };
+      }
+    }
+  }
+  if (key in tokens.intent) {
+    return { group: tokens.intent, name: key };
+  }
+  return null;
+}
+function isRecognizedOverrideKey(key, tokens) {
+  return findToken(key, tokens) !== null;
+}
+function collectBrandPassthrough(tokens, overrides) {
+  const passthrough = { light: {}, dark: {} };
+  if (!overrides) return passthrough;
+  for (const mode of ["light", "dark"]) {
+    const modeOverrides = overrides[mode];
+    if (!modeOverrides) continue;
+    for (const [key, value] of Object.entries(modeOverrides)) {
+      if (!isRecognizedOverrideKey(key, tokens)) {
+        passthrough[mode][key] = value;
+      }
+    }
+  }
+  return passthrough;
+}
+function hasBrandPassthrough(passthrough) {
+  return Object.keys(passthrough.light).length > 0 || Object.keys(passthrough.dark).length > 0;
+}
+function applyOverrides(tokens, overrides) {
+  if (!overrides) return tokens;
+  const result = {
+    text: { ...tokens.text },
+    surface: { ...tokens.surface },
+    border: { ...tokens.border },
+    interactive: { ...tokens.interactive },
+    intent: { ...tokens.intent },
+    hairline: { ...tokens.hairline }
+  };
+  for (const group of ["text", "surface", "border", "interactive", "intent", "hairline"]) {
+    for (const [name, value] of Object.entries(result[group])) {
+      result[group][name] = { ...value };
+    }
+  }
+  if (overrides.light) {
+    for (const [key, value] of Object.entries(overrides.light)) {
+      const match = findToken(key, result);
+      if (match) {
+        match.group[match.name] = {
+          ...match.group[match.name],
+          light: value
+        };
+      }
+    }
+  }
+  if (overrides.dark) {
+    for (const [key, value] of Object.entries(overrides.dark)) {
+      const match = findToken(key, result);
+      if (match) {
+        match.group[match.name] = {
+          ...match.group[match.name],
+          dark: value
+        };
+      }
+    }
+  }
+  return result;
+}
+
 // src/fonts/theme-alias.ts
 var EMPTY_ALIASES = /* @__PURE__ */ new Map();
 function aliasFamily(family, themeSlug) {
@@ -1491,6 +1576,7 @@ function generateMotionPrimitives(config) {
   decls.push("--motion-duration-300: 300ms;");
   decls.push(`--motion-duration-500: ${config.motion["duration-slow"]};`);
   decls.push("--motion-duration-800: 800ms;");
+  decls.push("--motion-duration-1500: 1500ms;");
   decls.push("--motion-easing-linear: linear;");
   decls.push("--motion-easing-ease-in: cubic-bezier(0.4, 0, 1, 1);");
   decls.push("--motion-easing-ease-out: cubic-bezier(0, 0, 0.2, 1);");
@@ -1808,6 +1894,7 @@ export {
   hexToOklch,
   clampToSrgb,
   oklchToHex,
+  getLuminance,
   getContrastRatio,
   parseHex,
   parseRgba,
@@ -1822,10 +1909,14 @@ export {
   SELECTIVE_SHADE_STEPS,
   TAILWIND_GRAY,
   generateShadeScale,
+  collectBrandPassthrough,
+  hasBrandPassthrough,
+  applyOverrides,
   aliasFamily,
   fontStack,
   header,
   sectionComment,
+  block2 as block,
   generatePrimitivesCss,
   generateSemanticCss,
   generateTextScaleAliasDecls,

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, c as VisorBrand, B as BrandSlot, d as BrandSource, e as BrandResolution, f as ThemeBrandResult, R as ResolvedThemeConfig, g as GeneratedPrimitives, h as ThemeOutput, i as ThemeData, j as VisorThemeConfig, k as FullShadeScale, C as ColorRole, S as SelectiveShadeScale, l as RGB, P as ParsedColor, O as OKLCH, m as SemanticTokens, n as ShadeStep } from './types-CSO2avFQ.js';
-export { o as BRAND_VARIANTS, p as BrandVariant, q as ColorFormat, r as FontSource, s as RGBA, t as SemanticTokenValue } from './types-CSO2avFQ.js';
+import { F as FontResolveOptions, a as FontResolution, V as VisorTypography, b as FontDisplayStrategy, T as ThemeFontResult, G as GoogleFontEntry, c as VisorBrand, B as BrandSlot, d as BrandSource, e as BrandResolution, f as ThemeBrandResult, R as ResolvedThemeConfig, g as GeneratedPrimitives, h as ThemeOutput, i as ThemeData, j as VisorThemeConfig, k as FullShadeScale, C as ColorRole, S as SelectiveShadeScale, l as RGB, P as ParsedColor, O as OKLCH, m as SemanticTokens, n as ShadeStep } from './types-zug1_eLX.js';
+export { o as BRAND_VARIANTS, p as BrandVariant, q as ColorFormat, r as FontSource, s as RGBA, t as SemanticTokenValue } from './types-zug1_eLX.js';
 
 /**
  * Font resolver — maps font family names to loadable font resources.
@@ -315,6 +315,18 @@ var properties = {
 		type: "string",
 		description: "Theme group for the docs site theme switcher (e.g. 'Visor', 'Client', 'Low Orbit'). Used by `visor theme sync`. Defaults to folder-based grouping when omitted."
 	},
+	label: {
+		type: "string",
+		description: "Human-readable display name for the theme (e.g. 'Blacklight Pro'). Overrides the name-derived label in the docs theme switcher. Optional."
+	},
+	"default-mode": {
+		type: "string",
+		"enum": [
+			"light",
+			"dark"
+		],
+		description: "Default color mode when activating this theme. When set, the docs site forces this mode on theme switch (unless the user has a stored mode preference). Optional."
+	},
 	colors: {
 		type: "object",
 		description: "Color definitions for light mode. Only primary is required — all others have sensible defaults.",
@@ -502,19 +514,44 @@ var properties = {
 				type: "number",
 				description: "Type scale multiplier applied to the font-size ramp. Default: 1."
 			},
+			"text-on-light": {
+				type: "string",
+				description: "VI-375: text color placed on a LIGHT interactive background. Auto-picked for interactive *-text tokens whose paired *-bg has relative luminance > 0.5. Defaults to #FFFFFF (which deliberately still fails AA on a bright bg so the contrast validator flags it); set a readable near-black (e.g. #1E1F21) to clear the warning. Per-token overrides (overrides.{mode}.interactive-*-text) still win."
+			},
+			"text-on-dark": {
+				type: "string",
+				description: "VI-375: text color placed on a DARK interactive background. Auto-picked for interactive *-text tokens whose paired *-bg has relative luminance <= 0.5. Defaults to #FFFFFF. Per-token overrides still win."
+			},
 			"letter-spacing": {
 				type: "object",
-				description: "Letter spacing scale.",
+				description: "6-tier letter-spacing ramp (xl | lg | md | sm | xs | tight). Each value is a CSS length (e.g. \"0.1em\", \"0.44rem\", \"-0.01em\"). The legacy triad keys normal and wide remain valid for back-compat and map onto the ramp (normal->md, wide->lg, tight->tight).",
 				additionalProperties: false,
 				properties: {
+					xl: {
+						type: "string"
+					},
+					lg: {
+						type: "string"
+					},
+					md: {
+						type: "string"
+					},
+					sm: {
+						type: "string"
+					},
+					xs: {
+						type: "string"
+					},
 					tight: {
 						type: "string"
 					},
 					normal: {
-						type: "string"
+						type: "string",
+						description: "Deprecated legacy alias — maps to md."
 					},
 					wide: {
-						type: "string"
+						type: "string",
+						description: "Deprecated legacy alias — maps to lg."
 					}
 				}
 			},
@@ -946,6 +983,21 @@ interface ThemeValidationResult {
     errors: ValidationIssue[];
     warnings: ValidationIssue[];
 }
+/**
+ * Options for the validate() function.
+ */
+interface ValidateOptions {
+    /**
+     * When true, promote DARK_LIGHT_PARITY warnings and the
+     * "colors.neutral present without colors-dark.neutral" check
+     * from warning to error. Use this in CI to enforce the
+     * "always both modes" authoring convention.
+     *
+     * Opt-in today; flip to the default after all convergent
+     * themes add their dark neutral (see VI-495 docs).
+     */
+    strictDark?: boolean;
+}
 /**
  * Validate a theme config comprehensively.
  *
@@ -953,9 +1005,10 @@ interface ThemeValidationResult {
  * Results are JSON-serializable for CLI `--json` output.
  *
  * @param config - A parsed theme config object (from YAML or programmatic)
+ * @param options - Optional validator flags (e.g. strictDark)
  * @returns ThemeValidationResult with errors[], warnings[], and valid boolean
  */
-declare function validate(config: unknown): ThemeValidationResult;
+declare function validate(config: unknown, options?: ValidateOptions): ThemeValidationResult;
 
 /**
  * Shade Scale Generation
@@ -1062,6 +1115,30 @@ declare function assignSemanticTokens(lightPrimitives: GeneratedPrimitives, dark
  * replacing derived token values with user-specified values.
  */
 
+/** Pass-through brand tokens collected per mode (VI-493). */
+interface BrandPassthrough {
+    light: Record<string, string>;
+    dark: Record<string, string>;
+}
+/**
+ * Collect unrecognized override keys into a brand-passthrough map (VI-493).
+ *
+ * Any `overrides.{light,dark}` key that does NOT map to a recognized semantic,
+ * intent, or hairline token is captured here verbatim (key + value). These were
+ * previously DROPPED silently by `applyOverrides`; the adapters now emit them as
+ * bare `--<key>` custom properties inside `@layer visor-brand`, ending the
+ * dual-source-of-truth between `.visor.yaml` and hand-maintained `:root` blocks.
+ *
+ * Recognized tokens are excluded — they continue to flow through the normal
+ * semantic pipeline. Pass-through tokens are legitimately mode-asymmetric (a key
+ * may appear in `light` only, `dark` only, or both); no both-modes rule applies.
+ */
+declare function collectBrandPassthrough(tokens: SemanticTokens, overrides?: {
+    light?: Record<string, string>;
+    dark?: Record<string, string>;
+}): BrandPassthrough;
+/** True when the passthrough map carries at least one token in either mode. */
+declare function hasBrandPassthrough(passthrough: BrandPassthrough): boolean;
 /**
  * Apply override values to semantic tokens.
  * Returns a new SemanticTokens with overrides applied (does not mutate input).
@@ -1221,4 +1298,4 @@ declare function cleanFontValue(val: string): string;
  */
 declare function extractFromCSS(files: CSSFile[], name?: string): ExtractionResult;
 
-export { BrandResolution, BrandSlot, BrandSource, type CSSFile, ColorRole, type Confidence, DEFAULT_VISOR_BRAND, type ExtractedToken, type ExtractionResult, FONT_WEIGHT_ALIASES, type FontCoverageError, type FontCoverageResult, FontDisplayStrategy, type FontFaceDeclaration, FontResolution, FontResolveOptions, FullShadeScale, GeneratedPrimitives, GoogleFontEntry, OKLCH, ParsedColor, RGB, ResolvedThemeConfig, SEMANTIC_MAP, SelectiveShadeScale, SemanticTokens, ShadeStep, TAILWIND_GRAY, ThemeBrandResult, ThemeData, ThemeFontResult, ThemeOutput, type ThemeValidationResult, VISOR_BRANDS_CDN, VISOR_DEFAULT_BRAND_PATH, VISOR_FONTS_CDN, type ValidationIssue, type ValidationSeverity, VisorBrand, VisorThemeConfig, VisorTypography, applyOverrides, assignSemanticTokens, buildVisorBrandUrl, buildVisorFontUrl, clampToSrgb, cleanFontValue, compositeOverBackground, exportTheme, extractFromCSS, formatFontCoverageError, 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, resolveBrandSlot, resolveBrandSource, resolveConfig, resolveFont, resolveThemeBrand, resolveThemeFonts, rgbToHex, serializeColor, validate, validateConfig, validateFontCoverage, visorTheme_schema as visorThemeSchema };
+export { type BrandPassthrough, BrandResolution, BrandSlot, BrandSource, type CSSFile, ColorRole, type Confidence, DEFAULT_VISOR_BRAND, type ExtractedToken, type ExtractionResult, FONT_WEIGHT_ALIASES, type FontCoverageError, type FontCoverageResult, FontDisplayStrategy, type FontFaceDeclaration, FontResolution, FontResolveOptions, FullShadeScale, GeneratedPrimitives, GoogleFontEntry, OKLCH, ParsedColor, RGB, ResolvedThemeConfig, SEMANTIC_MAP, SelectiveShadeScale, SemanticTokens, ShadeStep, TAILWIND_GRAY, ThemeBrandResult, ThemeData, ThemeFontResult, ThemeOutput, type ThemeValidationResult, VISOR_BRANDS_CDN, VISOR_DEFAULT_BRAND_PATH, VISOR_FONTS_CDN, type ValidateOptions, type ValidationIssue, type ValidationSeverity, VisorBrand, VisorThemeConfig, VisorTypography, applyOverrides, assignSemanticTokens, buildVisorBrandUrl, buildVisorFontUrl, clampToSrgb, cleanFontValue, collectBrandPassthrough, compositeOverBackground, exportTheme, extractFromCSS, formatFontCoverageError, generateDarkCss, generateFullBundleCss, generateLightCss, generatePreloadLinks, generatePrimitives, generatePrimitivesCss, generateSemanticCss, generateShadeScale, generateStylesheetLinks, generateTheme, generateThemeData, generateThemeDataFromConfig, generateThemeFromConfig, getContrastRatio, googleFontsCatalog, hasBrandPassthrough, hexToOklch, hexToRgb, isValidColor, isValidHex, isVisorThemeConfig, lookupFontWeightAlias, lookupGoogleFont, normalizeHex, oklchToHex, parseCSSDeclarations, parseColor, parseConfig, parseFontFaceDeclarations, parseHex, parseHsla, parseOklch, parseRgba, resolveBrandSlot, resolveBrandSource, resolveConfig, resolveFont, resolveThemeBrand, resolveThemeFonts, rgbToHex, serializeColor, validate, validateConfig, validateFontCoverage, visorTheme_schema as visorThemeSchema };

package/dist/index.js

@@ -7,9 +7,11 @@ import {
   VISOR_BRANDS_CDN,
   VISOR_DEFAULT_BRAND_PATH,
   VISOR_FONTS_CDN,
+  applyOverrides,
   buildVisorBrandUrl,
   buildVisorFontUrl,
   clampToSrgb,
+  collectBrandPassthrough,
   compositeOverBackground,
   generateDarkCss,
   generateFullBundleCss,
@@ -20,7 +22,9 @@ import {
   generateShadeScale,
   generateStylesheetLinks,
   getContrastRatio,
+  getLuminance,
   googleFontsCatalog,
+  hasBrandPassthrough,
   hexToOklch,
   hexToRgb,
   isValidColor,
@@ -42,7 +46,7 @@ import {
   rgbToHex,
   rgbToOklch,
   serializeColor
-} from "./chunk-KFTTL3XP.js";
+} from "./chunk-DQ256PSE.js";
 
 // src/fonts/validate-coverage.ts
 var FONT_VAR_RE = /--font-(heading|display|body|sans|mono)\s*:\s*([^;]+);/g;
@@ -224,6 +228,15 @@ var visor_theme_schema_default = {
       type: "string",
       description: "Theme group for the docs site theme switcher (e.g. 'Visor', 'Client', 'Low Orbit'). Used by `visor theme sync`. Defaults to folder-based grouping when omitted."
     },
+    label: {
+      type: "string",
+      description: "Human-readable display name for the theme (e.g. 'Blacklight Pro'). Overrides the name-derived label in the docs theme switcher. Optional."
+    },
+    "default-mode": {
+      type: "string",
+      enum: ["light", "dark"],
+      description: "Default color mode when activating this theme. When set, the docs site forces this mode on theme switch (unless the user has a stored mode preference). Optional."
+    },
     colors: {
       type: "object",
       description: "Color definitions for light mode. Only primary is required \u2014 all others have sensible defaults.",
@@ -379,14 +392,27 @@ var visor_theme_schema_default = {
           type: "number",
           description: "Type scale multiplier applied to the font-size ramp. Default: 1."
         },
+        "text-on-light": {
+          type: "string",
+          description: "VI-375: text color placed on a LIGHT interactive background. Auto-picked for interactive *-text tokens whose paired *-bg has relative luminance > 0.5. Defaults to #FFFFFF (which deliberately still fails AA on a bright bg so the contrast validator flags it); set a readable near-black (e.g. #1E1F21) to clear the warning. Per-token overrides (overrides.{mode}.interactive-*-text) still win."
+        },
+        "text-on-dark": {
+          type: "string",
+          description: "VI-375: text color placed on a DARK interactive background. Auto-picked for interactive *-text tokens whose paired *-bg has relative luminance <= 0.5. Defaults to #FFFFFF. Per-token overrides still win."
+        },
         "letter-spacing": {
           type: "object",
-          description: "Letter spacing scale.",
+          description: '6-tier letter-spacing ramp (xl | lg | md | sm | xs | tight). Each value is a CSS length (e.g. "0.1em", "0.44rem", "-0.01em"). The legacy triad keys normal and wide remain valid for back-compat and map onto the ramp (normal->md, wide->lg, tight->tight).',
           additionalProperties: false,
           properties: {
+            xl: { type: "string" },
+            lg: { type: "string" },
+            md: { type: "string" },
+            sm: { type: "string" },
+            xs: { type: "string" },
             tight: { type: "string" },
-            normal: { type: "string" },
-            wide: { type: "string" }
+            normal: { type: "string", description: "Deprecated legacy alias \u2014 maps to md." },
+            wide: { type: "string", description: "Deprecated legacy alias \u2014 maps to lg." }
           }
         },
         "cdn-overrides": {
@@ -683,12 +709,25 @@ var KNOWN_TYPOGRAPHY_KEYS = /* @__PURE__ */ new Set([
   "letter-spacing",
   "scale",
   "slots",
-  "cdn-overrides"
+  "cdn-overrides",
+  // VI-375: default text colors for interactive backgrounds (auto-picked by
+  // paired `*-bg` luminance; theme-overridable).
+  "text-on-light",
+  "text-on-dark"
 ]);
 var KNOWN_CDN_OVERRIDE_KEYS = /* @__PURE__ */ new Set(["visor-fonts"]);
 var KNOWN_TYPOGRAPHY_FONT_KEYS = /* @__PURE__ */ new Set(["family", "weight", "weights", "source", "org"]);
 var KNOWN_TYPOGRAPHY_MONO_KEYS = /* @__PURE__ */ new Set(["family", "weight", "weights", "source", "org"]);
-var KNOWN_LETTER_SPACING_KEYS = /* @__PURE__ */ new Set(["tight", "normal", "wide"]);
+var KNOWN_LETTER_SPACING_KEYS = /* @__PURE__ */ new Set([
+  "xl",
+  "lg",
+  "md",
+  "sm",
+  "xs",
+  "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"]);
@@ -768,6 +807,12 @@ function checkUnknownKeys(obj, errors) {
         }
       }
     }
+    for (const key of ["text-on-light", "text-on-dark"]) {
+      const value = typo[key];
+      if (value !== void 0 && (typeof value !== "string" || !isValidColor(value))) {
+        errors.push(`'typography.${key}' must be a valid CSS color (hex, rgba, hsla, or oklch)`);
+      }
+    }
     if (typeof typo["cdn-overrides"] === "object" && typo["cdn-overrides"] !== null) {
       for (const key of Object.keys(typo["cdn-overrides"])) {
         if (!KNOWN_CDN_OVERRIDE_KEYS.has(key)) {
@@ -1091,9 +1136,29 @@ var DEFAULTS = {
   },
   typography: {
     scale: 1,
+    // VI-375: default text colors for interactive backgrounds. Auto-picked for
+    // `*-text` tokens by the paired `*-bg` luminance. The defaults preserve the
+    // historical white-on-button behavior (both default to white), so a theme
+    // that only overrides a bright button bg STILL fails AA and raises a
+    // WCAG_CONTRAST warning — the operator must opt into a readable on-light
+    // color (e.g. ENTR's `text-on-light: "#1E1F21"`) to clear it. This keeps the
+    // fix loud rather than silently flipping every theme's button text.
+    "text-on-light": "#FFFFFF",
+    "text-on-dark": "#FFFFFF",
     heading: { family: DEFAULT_FONT_SANS, weight: 600 },
     body: { family: DEFAULT_FONT_SANS, weight: 400 },
-    mono: { family: DEFAULT_FONT_MONO }
+    mono: { family: DEFAULT_FONT_MONO },
+    // VI-447: default 6-tier letter-spacing ramp. em-based so it scales with
+    // type size; `md` is anchored at the historical `--letter-spacing-normal`
+    // value (0.05em) so existing themes emit byte-identical output.
+    "letter-spacing": {
+      xl: "0.16em",
+      lg: "0.1em",
+      md: "0.05em",
+      sm: "0.025em",
+      xs: "0.01em",
+      tight: "-0.01em"
+    }
   },
   spacing: { base: 4 },
   radius: { sm: 2, md: 4, lg: 8, xl: 12, pill: 9999 },
@@ -1134,6 +1199,17 @@ function resolveBrand(brand) {
     ...brand.custom && { custom: brand.custom }
   };
 }
+function resolveLetterSpacing(ls) {
+  const d = DEFAULTS.typography["letter-spacing"];
+  return {
+    xl: ls?.xl ?? d.xl,
+    lg: ls?.lg ?? ls?.wide ?? d.lg,
+    md: ls?.md ?? ls?.normal ?? d.md,
+    sm: ls?.sm ?? d.sm,
+    xs: ls?.xs ?? d.xs,
+    tight: ls?.tight ?? d.tight
+  };
+}
 function resolveConfig(config) {
   const colors = config.colors;
   const originalColors = {};
@@ -1165,6 +1241,7 @@ function resolveConfig(config) {
   return {
     name: config.name,
     ...config.label !== void 0 && { label: config.label },
+    ...config["default-mode"] !== void 0 && { "default-mode": config["default-mode"] },
     version: 1,
     colors: {
       primary: colors.primary,
@@ -1181,6 +1258,8 @@ function resolveConfig(config) {
     "colors-dark": config["colors-dark"],
     typography: {
       scale: config.typography?.scale ?? DEFAULTS.typography.scale,
+      "text-on-light": config.typography?.["text-on-light"] ?? DEFAULTS.typography["text-on-light"],
+      "text-on-dark": config.typography?.["text-on-dark"] ?? DEFAULTS.typography["text-on-dark"],
       heading: {
         family: config.typography?.heading?.family ?? DEFAULTS.typography.heading.family,
         weight: config.typography?.heading?.weight ?? DEFAULTS.typography.heading.weight,
@@ -1212,7 +1291,8 @@ function resolveConfig(config) {
       ...config.typography?.["cdn-overrides"] && {
         "cdn-overrides": config.typography["cdn-overrides"]
       },
-      slots: config.typography?.slots ?? {}
+      slots: config.typography?.slots ?? {},
+      "letter-spacing": resolveLetterSpacing(config.typography?.["letter-spacing"])
     },
     brand: resolveBrand(config.brand),
     spacing: {
@@ -1261,6 +1341,10 @@ var CONFIG_BACKGROUND = "__CONFIG_BACKGROUND__";
 var CONFIG_SURFACE = "__CONFIG_SURFACE__";
 var CONFIG_DARK_BACKGROUND = "__CONFIG_DARK_BACKGROUND__";
 var CONFIG_DARK_SURFACE = "__CONFIG_DARK_SURFACE__";
+var DERIVE_ON_BG_PREFIX = "__DERIVE_ON_BG__";
+function deriveOnBg(pairedBgToken) {
+  return `${DERIVE_ON_BG_PREFIX}${pairedBgToken}`;
+}
 var SEMANTIC_TEXT_MAP = {
   primary: {
     light: { role: "neutral", shade: 900 },
@@ -1516,9 +1600,13 @@ var SEMANTIC_INTERACTIVE_MAP = {
     light: { role: "primary", shade: 800 },
     dark: { role: "primary", shade: 300 }
   },
+  // VI-375: was a hardcoded #ffffff constant in both modes — a blind spot that
+  // let a bright brand bg (ENTR dark mint) render white text at ~1.6:1. Now
+  // derives from the paired `primary-bg` luminance: light bg → text-on-light,
+  // dark bg → text-on-dark. Per-token override still wins.
   "primary-text": {
-    light: { constant: "#ffffff" },
-    dark: { constant: "#ffffff" }
+    light: { constant: deriveOnBg("primary-bg") },
+    dark: { constant: deriveOnBg("primary-bg") }
   },
   // VI-478: brand-derived alpha-overlay helpers (BL-193). `soft`/`glow` are
   // alpha overlays that track the theme's primary via color-mix (distinct from
@@ -1567,9 +1655,11 @@ var SEMANTIC_INTERACTIVE_MAP = {
     light: { role: "error", shade: 700 },
     dark: { role: "error", shade: 600 }
   },
+  // VI-375: derive from the paired `destructive-bg` luminance (was hardcoded
+  // #ffffff). Per-token override still wins.
   "destructive-text": {
-    light: { constant: "#ffffff" },
-    dark: { constant: "#ffffff" }
+    light: { constant: deriveOnBg("destructive-bg") },
+    dark: { constant: deriveOnBg("destructive-bg") }
   },
   // Ghost action
   "ghost-bg": {
@@ -1586,11 +1676,14 @@ var SEMANTIC_INTENT_MAP = {
     light: { role: "primary", shade: 500 },
     dark: { role: "primary", shade: 500 }
   },
-  // Text color paired with --primary backgrounds. Default white; themes whose
-  // primary fails AA on white pin to a graphite via overrides (entr does this).
+  // Single-source alias of --interactive-primary-text. Default white (same value
+  // as the interactive group); themes that need a different value (e.g. entr)
+  // override via overrides.{light,dark}["primary-text"] which replaces this alias
+  // with the explicit override value. Hand-authored static CSS (blackout-theme.css,
+  // neutral-theme.css) should consume --primary-text via this alias path.
   "primary-text": {
-    light: { constant: "#ffffff" },
-    dark: { constant: "#ffffff" }
+    light: { constant: "var(--interactive-primary-text)" },
+    dark: { constant: "var(--interactive-primary-text)" }
   },
   accent: {
     light: { role: "accent", shade: 500 },
@@ -1624,6 +1717,16 @@ var SEMANTIC_HAIRLINE_MAP = {
     dark: { constant: "rgba(255, 255, 255, 0.10)" }
   }
 };
+var INTERACTIVE_TEXT_BG_PAIRS = (() => {
+  const pairs = {};
+  for (const [name, mapping] of Object.entries(SEMANTIC_INTERACTIVE_MAP)) {
+    const light = mapping.light;
+    if ("constant" in light && light.constant.startsWith(DERIVE_ON_BG_PREFIX)) {
+      pairs[name] = light.constant.slice(DERIVE_ON_BG_PREFIX.length);
+    }
+  }
+  return pairs;
+})();
 var SEMANTIC_MAP = {
   text: SEMANTIC_TEXT_MAP,
   surface: SEMANTIC_SURFACE_MAP,
@@ -1661,6 +1764,66 @@ function resolveRef(ref, primitives, config) {
       return ref.constant;
   }
 }
+function pickTextForBg(bgValue, config) {
+  const parsed = parseColor(bgValue);
+  const luminance = parsed ? getLuminance(...parsed.rgb) : 0;
+  return luminance > 0.5 ? config.typography["text-on-light"] : config.typography["text-on-dark"];
+}
+function deriveInteractiveTextColors(interactive, config, opts = {}) {
+  const skip = opts.skipTokens ?? /* @__PURE__ */ new Set();
+  const modes = opts.modes ?? ["light", "dark"];
+  for (const [textToken, bgToken] of Object.entries(INTERACTIVE_TEXT_BG_PAIRS)) {
+    if (skip.has(textToken)) continue;
+    const textValue = interactive[textToken];
+    const bgValue = interactive[bgToken];
+    if (!textValue || !bgValue) continue;
+    const next = { ...textValue };
+    for (const mode of modes) {
+      next[mode] = pickTextForBg(bgValue[mode], config);
+    }
+    interactive[textToken] = next;
+  }
+}
+function reapplyInteractiveTextDerivation(tokens, config, overrides) {
+  if (!overrides) return tokens;
+  const skip = /* @__PURE__ */ new Set();
+  const bgOverriddenModes = /* @__PURE__ */ new Map();
+  for (const mode of ["light", "dark"]) {
+    const modeOverrides = overrides[mode];
+    if (!modeOverrides) continue;
+    for (const key of Object.keys(modeOverrides)) {
+      if (!key.startsWith("interactive-")) continue;
+      const tokenName = key.slice("interactive-".length);
+      if (tokenName in INTERACTIVE_TEXT_BG_PAIRS) {
+        skip.add(tokenName);
+      }
+      for (const [textToken, bgToken] of Object.entries(INTERACTIVE_TEXT_BG_PAIRS)) {
+        if (tokenName === bgToken) {
+          if (!bgOverriddenModes.has(textToken)) {
+            bgOverriddenModes.set(textToken, /* @__PURE__ */ new Set());
+          }
+          bgOverriddenModes.get(textToken).add(mode);
+        }
+      }
+    }
+  }
+  if (bgOverriddenModes.size === 0) return tokens;
+  const interactive = {};
+  for (const [name, value] of Object.entries(tokens.interactive)) {
+    interactive[name] = { ...value };
+  }
+  for (const [textToken, modes] of bgOverriddenModes) {
+    if (skip.has(textToken)) continue;
+    deriveInteractiveTextColors(interactive, config, {
+      // Re-derive only this token by skipping the others.
+      skipTokens: new Set(
+        Object.keys(INTERACTIVE_TEXT_BG_PAIRS).filter((t) => t !== textToken)
+      ),
+      modes: [...modes]
+    });
+  }
+  return { ...tokens, interactive };
+}
 function resolveMapping(mapping, lightPrimitives, darkPrimitives, config) {
   return {
     light: resolveRef(mapping.light, lightPrimitives, config),
@@ -1686,6 +1849,7 @@ function assignSemanticTokens(lightPrimitives, darkPrimitives, config) {
   for (const [name, mapping] of Object.entries(SEMANTIC_MAP.interactive)) {
     interactive[name] = resolveMapping(mapping, lightPrimitives, darkPrimitives, config);
   }
+  deriveInteractiveTextColors(interactive, config);
   for (const [name, mapping] of Object.entries(SEMANTIC_MAP.intent)) {
     intent[name] = resolveMapping(mapping, lightPrimitives, darkPrimitives, config);
   }
@@ -1695,71 +1859,6 @@ function assignSemanticTokens(lightPrimitives, darkPrimitives, config) {
   return { text, surface, border, interactive, intent, hairline };
 }
 
-// src/overrides.ts
-var TOKEN_CATEGORIES = [
-  { prefix: "text-", key: "text" },
-  { prefix: "surface-", key: "surface" },
-  { prefix: "border-", key: "border" },
-  { prefix: "interactive-", key: "interactive" },
-  { prefix: "hairline-", key: "hairline" }
-];
-function findToken(key, tokens) {
-  if (key === "hairline" && "default" in tokens.hairline) {
-    return { group: tokens.hairline, name: "default" };
-  }
-  for (const { prefix, key: groupKey } of TOKEN_CATEGORIES) {
-    if (key.startsWith(prefix)) {
-      const name = key.slice(prefix.length);
-      if (name in tokens[groupKey]) {
-        return { group: tokens[groupKey], name };
-      }
-    }
-  }
-  if (key in tokens.intent) {
-    return { group: tokens.intent, name: key };
-  }
-  return null;
-}
-function applyOverrides(tokens, overrides) {
-  if (!overrides) return tokens;
-  const result = {
-    text: { ...tokens.text },
-    surface: { ...tokens.surface },
-    border: { ...tokens.border },
-    interactive: { ...tokens.interactive },
-    intent: { ...tokens.intent },
-    hairline: { ...tokens.hairline }
-  };
-  for (const group of ["text", "surface", "border", "interactive", "intent", "hairline"]) {
-    for (const [name, value] of Object.entries(result[group])) {
-      result[group][name] = { ...value };
-    }
-  }
-  if (overrides.light) {
-    for (const [key, value] of Object.entries(overrides.light)) {
-      const match = findToken(key, result);
-      if (match) {
-        match.group[match.name] = {
-          ...match.group[match.name],
-          light: value
-        };
-      }
-    }
-  }
-  if (overrides.dark) {
-    for (const [key, value] of Object.entries(overrides.dark)) {
-      const match = findToken(key, result);
-      if (match) {
-        match.group[match.name] = {
-          ...match.group[match.name],
-          dark: value
-        };
-      }
-    }
-  }
-  return result;
-}
-
 // src/pipeline.ts
 function generatePrimitives(config) {
   return {
@@ -1819,6 +1918,7 @@ ${validation.errors.map((e) => `  - ${e}`).join("\n")}`
   const darkPrimitives = generateDarkPrimitives(resolved, primitives);
   let tokens = assignSemanticTokens(primitives, darkPrimitives, resolved);
   tokens = applyOverrides(tokens, resolved.overrides);
+  tokens = reapplyInteractiveTextDerivation(tokens, resolved, resolved.overrides);
   const output = {
     primitivesCss: generatePrimitivesCss(primitives, resolved),
     semanticCss: generateSemanticCss(tokens),
@@ -2242,7 +2342,7 @@ function checkTypeScaleCoherence(config, issues) {
 function checkLetterSpacing(config, issues) {
   const ls = config.typography?.["letter-spacing"];
   if (!ls) return;
-  for (const key of ["tight", "normal", "wide"]) {
+  for (const key of ["xl", "lg", "md", "sm", "xs", "tight", "normal", "wide"]) {
     const value = ls[key];
     if (value !== void 0) {
       if (typeof value !== "string" || !CSS_LENGTH_RE.test(value.trim())) {
@@ -2361,7 +2461,7 @@ function checkOverrides(config, issues) {
           issue(
             "warning",
             "UNKNOWN_OVERRIDE_KEY",
-            `'overrides.${mode}.${key}' does not match any known semantic token. Valid tokens include: text-primary, surface-page, border-default, interactive-primary-bg, etc.`,
+            `'overrides.${mode}.${key}' does not match any known semantic token; it will be emitted as a bare '--${key}' custom property in @layer visor-brand (brand pass-through). If you meant to override a semantic token, valid tokens include: text-primary, surface-page, border-default, interactive-primary-bg, etc.`,
             `overrides.${mode}.${key}`
           )
         );
@@ -2455,12 +2555,27 @@ function colorToRgb(color) {
 }
 var STANDARD_TEXT_TOKENS = ["primary", "secondary", "tertiary"];
 var STATUS_TEXT_TOKENS = ["error", "warning", "success", "info"];
+var INTERACTIVE_PAIRS_TO_VALIDATE = (() => {
+  const pairs = {};
+  for (const name of Object.keys(SEMANTIC_INTERACTIVE_MAP)) {
+    if (!name.endsWith("-text")) continue;
+    const bgToken = `${name.slice(0, -"-text".length)}-bg`;
+    if (bgToken in SEMANTIC_INTERACTIVE_MAP) {
+      pairs[name] = bgToken;
+    }
+  }
+  return pairs;
+})();
 function checkContrastWarnings(config, issues) {
   const resolved = resolveConfig(config);
   const lightPrimitives = generatePrimitives(resolved);
   const darkPrimitives = generateDarkPrimitives(resolved, lightPrimitives);
-  const tokens = applyOverrides(
-    assignSemanticTokens(lightPrimitives, darkPrimitives, resolved),
+  const tokens = reapplyInteractiveTextDerivation(
+    applyOverrides(
+      assignSemanticTokens(lightPrimitives, darkPrimitives, resolved),
+      resolved.overrides
+    ),
+    resolved,
     resolved.overrides
   );
   const lightBg = resolved.colors.background;
@@ -2523,7 +2638,10 @@ function checkContrastWarnings(config, issues) {
       );
     }
   }
-  const primaryOnBg = getContrastRatio(primary, lightBg, lightBgRgb);
+  const primaryBgToken = tokens.interactive["primary-bg"];
+  const lightPrimaryBg = primaryBgToken?.light ?? primary;
+  const darkPrimaryBg = primaryBgToken?.dark ?? darkPrimary;
+  const primaryOnBg = getContrastRatio(lightPrimaryBg, lightBg, lightBgRgb);
   if (primaryOnBg < CONTRAST_INTERACTIVE_AA) {
     issues.push(
       issue(
@@ -2534,7 +2652,7 @@ function checkContrastWarnings(config, issues) {
       )
     );
   }
-  const primaryOnSurface = getContrastRatio(primary, lightSurface, lightSurfaceRgb);
+  const primaryOnSurface = getContrastRatio(lightPrimaryBg, lightSurface, lightSurfaceRgb);
   if (primaryOnSurface < CONTRAST_INTERACTIVE_AA) {
     issues.push(
       issue(
@@ -2545,7 +2663,7 @@ function checkContrastWarnings(config, issues) {
       )
     );
   }
-  const darkPrimaryOnBg = getContrastRatio(darkPrimary, darkBg, darkBgRgb);
+  const darkPrimaryOnBg = getContrastRatio(darkPrimaryBg, darkBg, darkBgRgb);
   if (darkPrimaryOnBg < CONTRAST_INTERACTIVE_AA) {
     issues.push(
       issue(
@@ -2556,7 +2674,7 @@ function checkContrastWarnings(config, issues) {
       )
     );
   }
-  const darkPrimaryOnSurface = getContrastRatio(darkPrimary, darkSurface, darkSurfaceRgb);
+  const darkPrimaryOnSurface = getContrastRatio(darkPrimaryBg, darkSurface, darkSurfaceRgb);
   if (darkPrimaryOnSurface < CONTRAST_INTERACTIVE_AA) {
     issues.push(
       issue(
@@ -2567,6 +2685,33 @@ function checkContrastWarnings(config, issues) {
       )
     );
   }
+  for (const [textToken, bgToken] of Object.entries(INTERACTIVE_PAIRS_TO_VALIDATE)) {
+    const text = tokens.interactive[textToken];
+    const bg = tokens.interactive[bgToken];
+    if (!text || !bg) continue;
+    const lightRatio = getContrastRatio(text.light, bg.light, colorToRgb(bg.light));
+    if (lightRatio < CONTRAST_TEXT_AA) {
+      issues.push(
+        issue(
+          "warning",
+          "WCAG_CONTRAST",
+          `Light mode: interactive-${textToken} on interactive-${bgToken} has contrast ratio ${lightRatio.toFixed(2)}:1 (needs >= ${CONTRAST_TEXT_AA}:1)`,
+          `interactive.${textToken}`
+        )
+      );
+    }
+    const darkRatio = getContrastRatio(text.dark, bg.dark, colorToRgb(bg.dark));
+    if (darkRatio < CONTRAST_TEXT_AA) {
+      issues.push(
+        issue(
+          "warning",
+          "WCAG_CONTRAST",
+          `Dark mode: interactive-${textToken} on interactive-${bgToken} has contrast ratio ${darkRatio.toFixed(2)}:1 (needs >= ${CONTRAST_TEXT_AA}:1)`,
+          `interactive.${textToken}`
+        )
+      );
+    }
+  }
 }
 function checkColorSimilarity(config, issues) {
   const resolved = resolveConfig(config);
@@ -2642,14 +2787,15 @@ function checkRadiusScale(config, issues) {
     );
   }
 }
-function checkDarkLightParity(config, issues) {
+function checkDarkLightParity(config, issues, opts) {
   if (!config.colors) return;
   const colorKeys = Object.keys(config.colors).filter((k) => k !== "primary");
   const hasDarkSection = config["colors-dark"] !== void 0;
   if (colorKeys.length > 0 && !hasDarkSection) {
+    const severity = opts.strictDark ? "error" : "warning";
     issues.push(
       issue(
-        "warning",
+        severity,
         "DARK_LIGHT_PARITY",
         "Custom colors are set but no colors-dark section exists. Dark mode will use generated defaults which may not match your brand.",
         "colors-dark"
@@ -2663,9 +2809,10 @@ function checkDarkLightParity(config, issues) {
     for (const key of lightKeys) {
       if (key === "primary") continue;
       if (!darkKeys.has(key)) {
+        const severity = opts.strictDark ? "error" : "warning";
         issues.push(
           issue(
-            "warning",
+            severity,
             "DARK_LIGHT_PARITY",
             `Color "${key}" is set in colors but missing from colors-dark. Dark mode will use a generated default.`,
             "colors-dark"
@@ -2687,7 +2834,8 @@ function checkDarkLightParity(config, issues) {
     }
   }
 }
-function validate(config) {
+function validate(config, options) {
+  const opts = options || {};
   const errors = [];
   const warnings = [];
   const structurallyValid = checkStructuralIntegrity(config, errors);
@@ -2719,7 +2867,11 @@ function validate(config) {
     checkColorSimilarity(typedConfig, warnings);
     checkMissingGlowShadow(typedConfig, warnings);
     checkRadiusScale(typedConfig, warnings);
-    checkDarkLightParity(typedConfig, warnings);
+    const parityIssues = [];
+    checkDarkLightParity(typedConfig, parityIssues, opts);
+    for (const iss of parityIssues) {
+      (iss.severity === "error" ? errors : warnings).push(iss);
+    }
   }
   return {
     valid: errors.length === 0,
@@ -3229,6 +3381,7 @@ export {
   buildVisorFontUrl,
   clampToSrgb,
   cleanFontValue,
+  collectBrandPassthrough,
   compositeOverBackground,
   exportTheme,
   extractFromCSS,
@@ -3248,6 +3401,7 @@ export {
   generateThemeFromConfig,
   getContrastRatio,
   googleFontsCatalog,
+  hasBrandPassthrough,
   hexToOklch,
   hexToRgb,
   isValidColor,

package/dist/{types-CSO2avFQ.d.ts → types-zug1_eLX.d.ts}

@@ -294,6 +294,22 @@ interface VisorThemeConfig {
     };
     typography?: {
         scale?: number;
+        /**
+         * VI-375: text color placed on a LIGHT interactive background. Auto-picked
+         * for interactive `*-text` tokens whose paired `*-bg` resolves to a light
+         * color (relative luminance > 0.5). Defaults to `#FFFFFF` (preserving the
+         * historical white-on-button default, which deliberately still fails AA on
+         * a bright bg so the contrast validator flags it). Set a readable near-black
+         * (e.g. ENTR's `#1E1F21`) to clear the warning.
+         */
+        "text-on-light"?: string;
+        /**
+         * VI-375: text color placed on a DARK interactive background. Auto-picked
+         * for interactive `*-text` tokens whose paired `*-bg` resolves to a dark
+         * color (relative luminance <= 0.5). Theme-overridable. Defaults to
+         * `#FFFFFF`.
+         */
+        "text-on-dark"?: string;
         heading?: {
             family?: string;
             weight?: number;
@@ -322,9 +338,22 @@ interface VisorThemeConfig {
             source?: FontSource;
             org?: string;
         };
+        /**
+         * VI-447: 6-tier letter-spacing ramp (`xl | lg | md | sm | xs | tight`).
+         * Each value is a CSS length (e.g. `"0.1em"`, `"0.44rem"`, `"-0.01em"`).
+         * The legacy triad keys (`normal`, `wide`) stay valid for back-compat and
+         * map onto the ramp at resolve time (`normal`→md, `wide`→lg, `tight`→tight).
+         */
         "letter-spacing"?: {
+            xl?: string;
+            lg?: string;
+            md?: string;
+            sm?: string;
+            xs?: string;
             tight?: string;
+            /** @deprecated legacy alias — maps to `md`. */
             normal?: string;
+            /** @deprecated legacy alias — maps to `lg`. */
             wide?: string;
         };
         /**
@@ -412,6 +441,8 @@ interface ResolvedThemeConfig {
     name: string;
     /** Optional display label override forwarded from VisorThemeConfig.label. */
     label?: string;
+    /** Default color mode forwarded from VisorThemeConfig["default-mode"]. */
+    "default-mode"?: "dark" | "light";
     version: 1;
     colors: {
         primary: string;
@@ -427,6 +458,16 @@ interface ResolvedThemeConfig {
     "colors-dark"?: VisorThemeConfig["colors-dark"];
     typography: {
         scale: number;
+        /**
+         * VI-375: resolved default text color for LIGHT interactive backgrounds.
+         * Always present (defaults to `#1E1F21`); theme-overridable.
+         */
+        "text-on-light": string;
+        /**
+         * VI-375: resolved default text color for DARK interactive backgrounds.
+         * Always present (defaults to `#FFFFFF`); theme-overridable.
+         */
+        "text-on-dark": string;
         heading: {
             family: string;
             weight: number;
@@ -469,6 +510,19 @@ interface ResolvedThemeConfig {
          * consumes these; other adapters may ignore them.
          */
         slots: Partial<Record<MaterialTextSlot, TextSlotOverride>>;
+        /**
+         * VI-447: resolved 6-tier letter-spacing ramp. Always present — legacy
+         * triad input is folded onto the ramp and missing tiers fall back to the
+         * Visor default ramp, so every tier carries a CSS length.
+         */
+        "letter-spacing": {
+            xl: string;
+            lg: string;
+            md: string;
+            sm: string;
+            xs: string;
+            tight: string;
+        };
     };
     /**
      * Resolved brand block (VI-470). Always present — falls back to the Visor

package/package.json

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

@@ -20,6 +20,15 @@
       "type": "string",
       "description": "Theme group for the docs site theme switcher (e.g. 'Visor', 'Client', 'Low Orbit'). Used by `visor theme sync`. Defaults to folder-based grouping when omitted."
     },
+    "label": {
+      "type": "string",
+      "description": "Human-readable display name for the theme (e.g. 'Blacklight Pro'). Overrides the name-derived label in the docs theme switcher. Optional."
+    },
+    "default-mode": {
+      "type": "string",
+      "enum": ["light", "dark"],
+      "description": "Default color mode when activating this theme. When set, the docs site forces this mode on theme switch (unless the user has a stored mode preference). Optional."
+    },
     "colors": {
       "type": "object",
       "description": "Color definitions for light mode. Only primary is required — all others have sensible defaults.",
@@ -175,14 +184,27 @@
           "type": "number",
           "description": "Type scale multiplier applied to the font-size ramp. Default: 1."
         },
+        "text-on-light": {
+          "type": "string",
+          "description": "VI-375: text color placed on a LIGHT interactive background. Auto-picked for interactive *-text tokens whose paired *-bg has relative luminance > 0.5. Defaults to #FFFFFF (which deliberately still fails AA on a bright bg so the contrast validator flags it); set a readable near-black (e.g. #1E1F21) to clear the warning. Per-token overrides (overrides.{mode}.interactive-*-text) still win."
+        },
+        "text-on-dark": {
+          "type": "string",
+          "description": "VI-375: text color placed on a DARK interactive background. Auto-picked for interactive *-text tokens whose paired *-bg has relative luminance <= 0.5. Defaults to #FFFFFF. Per-token overrides still win."
+        },
         "letter-spacing": {
           "type": "object",
-          "description": "Letter spacing scale.",
+          "description": "6-tier letter-spacing ramp (xl | lg | md | sm | xs | tight). Each value is a CSS length (e.g. \"0.1em\", \"0.44rem\", \"-0.01em\"). The legacy triad keys normal and wide remain valid for back-compat and map onto the ramp (normal->md, wide->lg, tight->tight).",
           "additionalProperties": false,
           "properties": {
+            "xl": { "type": "string" },
+            "lg": { "type": "string" },
+            "md": { "type": "string" },
+            "sm": { "type": "string" },
+            "xs": { "type": "string" },
             "tight": { "type": "string" },
-            "normal": { "type": "string" },
-            "wide": { "type": "string" }
+            "normal": { "type": "string", "description": "Deprecated legacy alias — maps to md." },
+            "wide": { "type": "string", "description": "Deprecated legacy alias — maps to lg." }
           }
         },
         "cdn-overrides": {