@loworbitstudio/visor-theme-engine 0.13.0 → 0.14.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-BDRXkldG.js';
 
 /**
  * Adapter types for the Visor theme engine.

package/dist/adapters/index.js

@@ -4,6 +4,7 @@ import {
   SELECTIVE_SHADE_STEPS,
   aliasFamily,
   buildVisorFontUrl,
+  collectBrandPassthrough,
   fontStack,
   generateDarkCss,
   generateHairlineDecls,
@@ -18,7 +19,53 @@ import {
   resolveThemeBrand,
   resolveThemeFonts,
   sectionComment
-} from "../chunk-KFTTL3XP.js";
+} from "../chunk-YDRQQIOB.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 +149,17 @@ 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 lightBody = stripHeader(generateLightCss(input.tokens, { scopePrefix }));
   const darkBody = stripHeader(generateDarkCss(input.tokens, { scopePrefix }));
   lines.push(
@@ -562,7 +620,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 = block(`${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 +628,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 = block(`${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")}
 }`);
@@ -616,7 +674,7 @@ ${inner.split("\n").map((l) => `  ${l}`).join("\n")}
   semanticLines.push("");
   semanticLines.push(sectionComment2("Intent aliases (dark) \u2014 prefers-color-scheme"));
   {
-    const inner = block(`${scopeClass}:not(.light)`, generateIntentDecls(input.tokens, "dark"));
+    const inner = block(`${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 +682,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 = block(`${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-YDRQQIOB.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) {
@@ -1822,6 +1907,9 @@ export {
   SELECTIVE_SHADE_STEPS,
   TAILWIND_GRAY,
   generateShadeScale,
+  collectBrandPassthrough,
+  hasBrandPassthrough,
+  applyOverrides,
   aliasFamily,
   fontStack,
   header,

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-BDRXkldG.js';
+export { o as BRAND_VARIANTS, p as BrandVariant, q as ColorFormat, r as FontSource, s as RGBA, t as SemanticTokenValue } from './types-BDRXkldG.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.",
@@ -946,6 +958,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 +980,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 +1090,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 +1273,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,
@@ -21,6 +23,7 @@ import {
   generateStylesheetLinks,
   getContrastRatio,
   googleFontsCatalog,
+  hasBrandPassthrough,
   hexToOklch,
   hexToRgb,
   isValidColor,
@@ -42,7 +45,7 @@ import {
   rgbToHex,
   rgbToOklch,
   serializeColor
-} from "./chunk-KFTTL3XP.js";
+} from "./chunk-YDRQQIOB.js";
 
 // src/fonts/validate-coverage.ts
 var FONT_VAR_RE = /--font-(heading|display|body|sans|mono)\s*:\s*([^;]+);/g;
@@ -224,6 +227,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.",
@@ -1165,6 +1177,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,
@@ -1586,11 +1599,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 },
@@ -1695,71 +1711,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 {
@@ -2361,7 +2312,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}`
           )
         );
@@ -2642,14 +2593,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 +2615,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 +2640,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 +2673,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 +3187,7 @@ export {
   buildVisorFontUrl,
   clampToSrgb,
   cleanFontValue,
+  collectBrandPassthrough,
   compositeOverBackground,
   exportTheme,
   extractFromCSS,
@@ -3248,6 +3207,7 @@ export {
   generateThemeFromConfig,
   getContrastRatio,
   googleFontsCatalog,
+  hasBrandPassthrough,
   hexToOklch,
   hexToRgb,
   isValidColor,

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

@@ -412,6 +412,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;

package/package.json

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