@loworbitstudio/visor-theme-engine 0.16.0 → 0.17.1

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, g as BrandStrategy, h as BrandStrategyContext, i as BrandStrategyIssue, j as BrandStrategyValidationResult, S as SerializedBrandStrategy, R as ResolvedThemeConfig, k as GeneratedPrimitives, l as ThemeOutput, m as ThemeData, n as VisorThemeConfig, o as FullShadeScale, C as ColorRole, p as SelectiveShadeScale, q as RGB, P as ParsedColor, O as OKLCH, r as SemanticTokens, s as ShadeStep } from './types-BstIS9rL.js';
-export { t as BRAND_VARIANTS, u as BRAND_VISIBILITIES, v as BrandArchetype, w as BrandGoverns, x as BrandLexiconEntry, y as BrandPersonalityTrait, z as BrandPillar, A as BrandPositioning, D as BrandStrategyIssueSeverity, E as BrandToneEntry, H as BrandVariant, I as BrandVisibility, J as BrandVoice, K as BrandVoiceTrait, L as ColorFormat, M as DEFAULT_BRAND_STRATEGY_SURFACES, N as DEFAULT_BRAND_STRATEGY_TONE_STATES, Q as FontSource, U as GOVERNS_WILDCARD, W as RGBA, X as SemanticTokenValue } from './types-BstIS9rL.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, C as ColorScheme, f as ThemeBrandResult, g as BrandStrategy, h as BrandStrategyContext, i as BrandStrategyIssue, j as BrandStrategyValidationResult, S as SerializedBrandStrategy, R as ResolvedThemeConfig, k as GeneratedPrimitives, l as ThemeOutput, m as ThemeData, n as VisorThemeConfig, o as FullShadeScale, p as ColorRole, q as SelectiveShadeScale, r as RGB, P as ParsedColor, O as OKLCH, s as SemanticTokens, t as ShadeStep } from './types-Cvm7vFwe.js';
+export { u as BRAND_VARIANTS, v as BRAND_VISIBILITIES, w as BrandAccessibility, x as BrandArchetype, y as BrandBoilerplate, z as BrandColorPairing, A as BrandColorUsage, D as BrandContrastTarget, E as BrandGoverns, H as BrandLexiconEntry, I as BrandMessaging, J as BrandPersonalityTrait, K as BrandPillar, L as BrandPositioning, M as BrandStrategyIssueSeverity, N as BrandToneEntry, Q as BrandVariant, U as BrandVisibility, W as BrandVoice, X as BrandVoiceTrait, Y as ColorFormat, Z as DEFAULT_BRAND_STRATEGY_SURFACES, _ as DEFAULT_BRAND_STRATEGY_TONE_STATES, $ as FontSource, a0 as GOVERNS_WILDCARD, a1 as RGBA, a2 as SemanticTokenValue } from './types-Cvm7vFwe.js';
 
 /**
  * Font resolver — maps font family names to loadable font resources.
@@ -234,6 +234,7 @@ declare function resolveBrandSource(brand: VisorBrand): BrandSource;
  */
 declare function resolveThemeBrand(brand: VisorBrand | undefined, options?: {
     scope?: string;
+    colorScheme?: ColorScheme;
 }): ThemeBrandResult;
 
 /**
@@ -291,8 +292,11 @@ declare function validateBrandStrategy(block: unknown, ctx?: BrandStrategyContex
 /**
  * Serialize a validated brand strategy for the manifest. Returns `null` when
  * `visibility: private`. Optional fields (`archetype.secondary`,
- * `voice.traits[].example`, absent `governs` lists) are emitted only when
- * present, so the agent reads a clean, predictable object.
+ * `voice.traits[].example`, absent `governs` lists, the Phase 2 wave-1 fields
+ * `pillars[].proof` / `messaging` / `taglines` / `boilerplate` / `colorUsage` /
+ * `accessibility`) are emitted only when present, so the agent reads a clean,
+ * predictable object. The Phase 2 fields are all PUBLIC — a private record
+ * never reaches this point, so visibility is enforced once, up top (D4).
  */
 declare function serializeBrandStrategy(strategy: BrandStrategy): SerializedBrandStrategy | null;
 
@@ -387,6 +391,15 @@ var properties = {
 		],
 		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."
 	},
+	"color-scheme": {
+		type: "string",
+		"enum": [
+			"dark-only",
+			"light-only",
+			"adaptive"
+		],
+		description: "Brand constraint declaring which color modes the theme supports. 'dark-only'/'light-only' lock the brand to a single mode; 'adaptive' supports both. Complements 'default-mode' (the runtime default) — 'color-scheme' is authoritative for the brand-lock. Defaults to 'adaptive' when omitted. Optional."
+	},
 	colors: {
 		type: "object",
 		description: "Color definitions for light mode. Only primary is required — all others have sensible defaults.",
@@ -856,6 +869,27 @@ var properties = {
 					"private"
 				],
 				description: "Client brands are private and are omitted from the public agent manifest."
+			},
+			messaging: {
+				$ref: "#/$defs/brandMessaging"
+			},
+			taglines: {
+				type: "array",
+				items: {
+					type: "string",
+					minLength: 1
+				},
+				minItems: 1,
+				description: "Phase 2 wave-1 (VI-541). Permanent, brand-level signature line(s) — who the brand is, not what it sells this quarter."
+			},
+			boilerplate: {
+				$ref: "#/$defs/brandBoilerplate"
+			},
+			colorUsage: {
+				$ref: "#/$defs/brandColorUsage"
+			},
+			accessibility: {
+				$ref: "#/$defs/brandAccessibility"
 			}
 		}
 	},
@@ -1208,6 +1242,15 @@ var $defs = {
 			},
 			governs: {
 				$ref: "#/$defs/brandGoverns"
+			},
+			proof: {
+				type: "array",
+				items: {
+					type: "string",
+					minLength: 1
+				},
+				minItems: 1,
+				description: "Phase 2 wave-1 (VI-541). Reasons-to-believe — checkable evidence backing this pillar's claim (the message-house foundation)."
 			}
 		}
 	},
@@ -1298,6 +1341,134 @@ var $defs = {
 				minLength: 1
 			}
 		}
+	},
+	brandMessaging: {
+		type: "object",
+		description: "Phase 2 wave-1 (VI-541). Message-house roof — the single umbrella message above the pillars.",
+		additionalProperties: false,
+		required: [
+			"roof"
+		],
+		properties: {
+			roof: {
+				type: "string",
+				minLength: 1,
+				description: "One overarching statement the pillars support."
+			}
+		}
+	},
+	brandBoilerplate: {
+		type: "object",
+		description: "Phase 2 wave-1 (VI-541). Reusable \"about us\" copy — short and long forms.",
+		additionalProperties: false,
+		required: [
+			"short",
+			"long"
+		],
+		properties: {
+			short: {
+				type: "string",
+				minLength: 1
+			},
+			long: {
+				type: "string",
+				minLength: 1
+			}
+		}
+	},
+	brandColorPairing: {
+		type: "object",
+		description: "A color-pairing rule expressed as brand intent (not a computed value).",
+		additionalProperties: false,
+		required: [
+			"use",
+			"with",
+			"rule"
+		],
+		properties: {
+			use: {
+				type: "string",
+				minLength: 1,
+				description: "The token or role being used (e.g. --primary)."
+			},
+			"with": {
+				type: "string",
+				minLength: 1,
+				description: "What it pairs against (token, role, or surface)."
+			},
+			rule: {
+				type: "string",
+				minLength: 1,
+				description: "The intent — when and how the pairing is allowed."
+			}
+		}
+	},
+	brandColorUsage: {
+		type: "object",
+		description: "Phase 2 wave-1 (VI-541). Color-usage intent — the brand's allowed pairings.",
+		additionalProperties: false,
+		required: [
+			"pairings"
+		],
+		properties: {
+			pairings: {
+				type: "array",
+				items: {
+					$ref: "#/$defs/brandColorPairing"
+				},
+				minItems: 1
+			}
+		}
+	},
+	brandContrastTarget: {
+		type: "object",
+		description: "A contrast target expressed as brand intent (a WCAG 2.1 AA threshold).",
+		additionalProperties: false,
+		required: [
+			"context",
+			"ratio"
+		],
+		properties: {
+			context: {
+				type: "string",
+				minLength: 1,
+				description: "The text/UI context the target applies to."
+			},
+			ratio: {
+				type: "string",
+				minLength: 1,
+				description: "The minimum contrast ratio (e.g. \"4.5:1\")."
+			}
+		}
+	},
+	brandAccessibility: {
+		type: "object",
+		description: "Phase 2 wave-1 (VI-541). Accessibility intent — the standard and its contrast targets (authored as intent; live computation is the render surface's concern).",
+		additionalProperties: false,
+		required: [
+			"standard",
+			"contrast",
+			"intent"
+		],
+		properties: {
+			standard: {
+				type: "string",
+				minLength: 1,
+				description: "The conformance standard. Visor targets \"WCAG 2.1 AA\"."
+			},
+			contrast: {
+				type: "array",
+				items: {
+					$ref: "#/$defs/brandContrastTarget"
+				},
+				minItems: 1
+			},
+			intent: {
+				type: "string",
+				minLength: 1,
+				description: "How the brand applies the standard (intent, not computed results)."
+			}
+		}
 	}
 };
 var visorTheme_schema = {
@@ -1427,6 +1598,7 @@ declare function clampToSrgb(L: number, C: number, H: number): RGB;
  * Convert OKLCH to hex, with gamut clamping.
  */
 declare function oklchToHex(L: number, C: number, H: number): string;
+declare function getLuminance(r: number, g: number, b: number): number;
 declare function getContrastRatio(color1: string | ParsedColor, color2: string | ParsedColor, compositeBackground?: RGB): number;
 /** Parse a hex color string into a ParsedColor. */
 declare function parseHex(str: string): ParsedColor | null;
@@ -1603,9 +1775,11 @@ declare function generatePrimitivesCss(primitives: GeneratedPrimitives, config:
 declare function generateSemanticCss(tokens: SemanticTokens): string;
 declare function generateLightCss(tokens: SemanticTokens, options?: {
     scopePrefix?: string;
+    colorScheme?: ColorScheme;
 }): string;
 declare function generateDarkCss(tokens: SemanticTokens, options?: {
     scopePrefix?: string;
+    colorScheme?: ColorScheme;
 }): string;
 declare function generateFullBundleCss(primitives: GeneratedPrimitives, tokens: SemanticTokens, config: ResolvedThemeConfig): string;
 
@@ -1684,4 +1858,4 @@ declare function cleanFontValue(val: string): string;
  */
 declare function extractFromCSS(files: CSSFile[], name?: string): ExtractionResult;
 
-export { type BrandPassthrough, BrandResolution, BrandSlot, BrandSource, BrandStrategy, BrandStrategyContext, BrandStrategyIssue, BrandStrategyValidationResult, 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, SerializedBrandStrategy, 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, checkBrandStrategyCoherence, checkBrandStrategyStructure, clampToSrgb, cleanFontValue, collectBrandPassthrough, compositeOverBackground, exportTheme, extractFromCSS, formatFontCoverageError, generateDarkCss, generateFullBundleCss, generateLightCss, generatePreloadLinks, generatePrimitives, generatePrimitivesCss, generateSemanticCss, generateShadeScale, generateStylesheetLinks, generateTheme, generateThemeData, generateThemeDataFromConfig, generateThemeFromConfig, getContrastRatio, getKnownTokenRefs, 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, serializeBrandStrategy, serializeColor, validate, validateBrandStrategy, validateConfig, validateFontCoverage, visorTheme_schema as visorThemeSchema };
+export { type BrandPassthrough, BrandResolution, BrandSlot, BrandSource, BrandStrategy, BrandStrategyContext, BrandStrategyIssue, BrandStrategyValidationResult, 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, SerializedBrandStrategy, 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, checkBrandStrategyCoherence, checkBrandStrategyStructure, clampToSrgb, cleanFontValue, collectBrandPassthrough, compositeOverBackground, exportTheme, extractFromCSS, formatFontCoverageError, generateDarkCss, generateFullBundleCss, generateLightCss, generatePreloadLinks, generatePrimitives, generatePrimitivesCss, generateSemanticCss, generateShadeScale, generateStylesheetLinks, generateTheme, generateThemeData, generateThemeDataFromConfig, generateThemeFromConfig, getContrastRatio, getKnownTokenRefs, getLuminance, 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, serializeBrandStrategy, serializeColor, validate, validateBrandStrategy, validateConfig, validateFontCoverage, visorTheme_schema as visorThemeSchema };

package/dist/index.js

@@ -46,7 +46,7 @@ import {
   rgbToHex,
   rgbToOklch,
   serializeColor
-} from "./chunk-DQ256PSE.js";
+} from "./chunk-BUWBBUFG.js";
 
 // src/fonts/validate-coverage.ts
 var FONT_VAR_RE = /--font-(heading|display|body|sans|mono)\s*:\s*([^;]+);/g;
@@ -248,7 +248,13 @@ var TOP_LEVEL_KEYS = /* @__PURE__ */ new Set([
   "tone",
   "lexicon",
   "core",
-  "visibility"
+  "visibility",
+  // Phase 2 wave-1 (VI-541) — all optional.
+  "messaging",
+  "taglines",
+  "boilerplate",
+  "colorUsage",
+  "accessibility"
 ]);
 var GOVERNS_KEYS = /* @__PURE__ */ new Set(["tokens", "components", "surfaces"]);
 function checkBrandStrategyStructure(block) {
@@ -347,6 +353,64 @@ function checkBrandStrategyStructure(block) {
   if (!isNonEmptyString(block.visibility) || !BRAND_VISIBILITIES.includes(block.visibility)) {
     errors.push(error("BRAND_STRATEGY_VISIBILITY", `'brand-strategy.visibility' is required and must be one of: ${BRAND_VISIBILITIES.join(", ")}`, "brand-strategy.visibility"));
   }
+  errors.push(...checkPhase2Structure(block));
+  return errors;
+}
+function checkPhase2Structure(block) {
+  const errors = [];
+  if (block.messaging !== void 0) {
+    const messaging = block.messaging;
+    if (!isObject(messaging) || !isNonEmptyString(messaging.roof)) {
+      errors.push(error("BRAND_STRATEGY_MESSAGING", "'brand-strategy.messaging' must be an object with a non-empty 'roof' string", "brand-strategy.messaging"));
+    }
+  }
+  if (block.taglines !== void 0) {
+    if (!isStringArray(block.taglines) || block.taglines.length === 0) {
+      errors.push(error("BRAND_STRATEGY_TAGLINES", "'brand-strategy.taglines' must be a non-empty array of strings when present", "brand-strategy.taglines"));
+    } else if (!block.taglines.every(isNonEmptyString)) {
+      errors.push(error("BRAND_STRATEGY_TAGLINES", "'brand-strategy.taglines' entries must be non-empty strings", "brand-strategy.taglines"));
+    }
+  }
+  if (block.boilerplate !== void 0) {
+    const boilerplate = block.boilerplate;
+    if (!isObject(boilerplate) || !isNonEmptyString(boilerplate.short) || !isNonEmptyString(boilerplate.long)) {
+      errors.push(error("BRAND_STRATEGY_BOILERPLATE", "'brand-strategy.boilerplate' must be an object with non-empty 'short' and 'long' strings", "brand-strategy.boilerplate"));
+    }
+  }
+  if (block.colorUsage !== void 0) {
+    const colorUsage = block.colorUsage;
+    if (!isObject(colorUsage) || !Array.isArray(colorUsage.pairings) || colorUsage.pairings.length === 0) {
+      errors.push(error("BRAND_STRATEGY_COLOR_USAGE", "'brand-strategy.colorUsage' must be an object with a non-empty 'pairings' array", "brand-strategy.colorUsage"));
+    } else {
+      colorUsage.pairings.forEach((pairing, i) => {
+        if (!isObject(pairing) || !isNonEmptyString(pairing.use) || !isNonEmptyString(pairing.with) || !isNonEmptyString(pairing.rule)) {
+          errors.push(error("BRAND_STRATEGY_COLOR_USAGE", `'brand-strategy.colorUsage.pairings[${i}]' must have non-empty 'use', 'with', and 'rule' strings`, `brand-strategy.colorUsage.pairings[${i}]`));
+        }
+      });
+    }
+  }
+  if (block.accessibility !== void 0) {
+    const accessibility = block.accessibility;
+    if (!isObject(accessibility)) {
+      errors.push(error("BRAND_STRATEGY_ACCESSIBILITY", "'brand-strategy.accessibility' must be an object", "brand-strategy.accessibility"));
+    } else {
+      if (!isNonEmptyString(accessibility.standard)) {
+        errors.push(error("BRAND_STRATEGY_ACCESSIBILITY", "'brand-strategy.accessibility.standard' is required and must be a non-empty string", "brand-strategy.accessibility.standard"));
+      }
+      if (!isNonEmptyString(accessibility.intent)) {
+        errors.push(error("BRAND_STRATEGY_ACCESSIBILITY", "'brand-strategy.accessibility.intent' is required and must be a non-empty string", "brand-strategy.accessibility.intent"));
+      }
+      if (!Array.isArray(accessibility.contrast) || accessibility.contrast.length === 0) {
+        errors.push(error("BRAND_STRATEGY_ACCESSIBILITY", "'brand-strategy.accessibility.contrast' must be a non-empty array", "brand-strategy.accessibility.contrast"));
+      } else {
+        accessibility.contrast.forEach((target, i) => {
+          if (!isObject(target) || !isNonEmptyString(target.context) || !isNonEmptyString(target.ratio)) {
+            errors.push(error("BRAND_STRATEGY_ACCESSIBILITY", `'brand-strategy.accessibility.contrast[${i}]' must have non-empty 'context' and 'ratio' strings`, `brand-strategy.accessibility.contrast[${i}]`));
+          }
+        });
+      }
+    }
+  }
   return errors;
 }
 function checkPillarStructure(pillar, index) {
@@ -383,6 +447,13 @@ function checkPillarStructure(pillar, index) {
       errors.push(error("BRAND_STRATEGY_GOVERNS", `'${path}.governs' must declare at least one of: ${[...GOVERNS_KEYS].join(", ")}`, `${path}.governs`));
     }
   }
+  if (pillar.proof !== void 0) {
+    if (!isStringArray(pillar.proof) || pillar.proof.length === 0) {
+      errors.push(error("BRAND_STRATEGY_PROOF", `'${path}.proof' must be a non-empty array of strings when present`, `${path}.proof`));
+    } else if (!pillar.proof.every(isNonEmptyString)) {
+      errors.push(error("BRAND_STRATEGY_PROOF", `'${path}.proof' entries must be non-empty strings`, `${path}.proof`));
+    }
+  }
   return errors;
 }
 function checkBrandStrategyCoherence(strategy, ctx = {}) {
@@ -442,6 +513,15 @@ function compactGoverns(governs) {
   if (governs.surfaces) out.surfaces = [...governs.surfaces];
   return out;
 }
+function serializePillar(p) {
+  const pillar = {
+    id: p.id,
+    statement: p.statement,
+    governs: compactGoverns(p.governs)
+  };
+  if (p.proof !== void 0) pillar.proof = [...p.proof];
+  return pillar;
+}
 function serializeBrandStrategy(strategy) {
   if (strategy.visibility === "private") {
     return null;
@@ -453,7 +533,7 @@ function serializeBrandStrategy(strategy) {
   for (const [state, entry] of Object.entries(strategy.tone)) {
     tone[state] = { feeling: entry.feeling, example: entry.example };
   }
-  return {
+  const serialized = {
     positioning: {
       onliness: strategy.positioning.onliness,
       category: strategy.positioning.category,
@@ -462,11 +542,7 @@ function serializeBrandStrategy(strategy) {
     essence: [...strategy.essence],
     personality: strategy.personality.map((p) => ({ trait: p.trait, not: p.not })),
     archetype,
-    pillars: strategy.pillars.map((p) => ({
-      id: p.id,
-      statement: p.statement,
-      governs: compactGoverns(p.governs)
-    })),
+    pillars: strategy.pillars.map(serializePillar),
     voice: {
       traits: strategy.voice.traits.map((t) => {
         const trait = {
@@ -483,6 +559,38 @@ function serializeBrandStrategy(strategy) {
     core: [...strategy.core],
     visibility: strategy.visibility
   };
+  if (strategy.messaging !== void 0) {
+    serialized.messaging = { roof: strategy.messaging.roof };
+  }
+  if (strategy.taglines !== void 0) {
+    serialized.taglines = [...strategy.taglines];
+  }
+  if (strategy.boilerplate !== void 0) {
+    serialized.boilerplate = {
+      short: strategy.boilerplate.short,
+      long: strategy.boilerplate.long
+    };
+  }
+  if (strategy.colorUsage !== void 0) {
+    serialized.colorUsage = {
+      pairings: strategy.colorUsage.pairings.map((p) => ({
+        use: p.use,
+        with: p.with,
+        rule: p.rule
+      }))
+    };
+  }
+  if (strategy.accessibility !== void 0) {
+    serialized.accessibility = {
+      standard: strategy.accessibility.standard,
+      contrast: strategy.accessibility.contrast.map((c) => ({
+        context: c.context,
+        ratio: c.ratio
+      })),
+      intent: strategy.accessibility.intent
+    };
+  }
+  return serialized;
 }
 
 // src/pipeline.ts
@@ -520,6 +628,11 @@ var visor_theme_schema_default = {
       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."
     },
+    "color-scheme": {
+      type: "string",
+      enum: ["dark-only", "light-only", "adaptive"],
+      description: "Brand constraint declaring which color modes the theme supports. 'dark-only'/'light-only' lock the brand to a single mode; 'adaptive' supports both. Complements 'default-mode' (the runtime default) \u2014 'color-scheme' is authoritative for the brand-lock. Defaults to 'adaptive' when omitted. Optional."
+    },
     colors: {
       type: "object",
       description: "Color definitions for light mode. Only primary is required \u2014 all others have sensible defaults.",
@@ -834,7 +947,17 @@ var visor_theme_schema_default = {
           type: "string",
           enum: ["public", "private"],
           description: "Client brands are private and are omitted from the public agent manifest."
-        }
+        },
+        messaging: { $ref: "#/$defs/brandMessaging" },
+        taglines: {
+          type: "array",
+          items: { type: "string", minLength: 1 },
+          minItems: 1,
+          description: "Phase 2 wave-1 (VI-541). Permanent, brand-level signature line(s) \u2014 who the brand is, not what it sells this quarter."
+        },
+        boilerplate: { $ref: "#/$defs/brandBoilerplate" },
+        colorUsage: { $ref: "#/$defs/brandColorUsage" },
+        accessibility: { $ref: "#/$defs/brandAccessibility" }
       }
     },
     spacing: {
@@ -1056,7 +1179,13 @@ var visor_theme_schema_default = {
       properties: {
         id: { type: "string", minLength: 1 },
         statement: { type: "string", minLength: 1, description: "The pillar's claim in one line." },
-        governs: { $ref: "#/$defs/brandGoverns" }
+        governs: { $ref: "#/$defs/brandGoverns" },
+        proof: {
+          type: "array",
+          items: { type: "string", minLength: 1 },
+          minItems: 1,
+          description: "Phase 2 wave-1 (VI-541). Reasons-to-believe \u2014 checkable evidence backing this pillar's claim (the message-house foundation)."
+        }
       }
     },
     brandVoice: {
@@ -1099,6 +1228,66 @@ var visor_theme_schema_default = {
         use: { type: "string", minLength: 1 },
         avoid: { type: "string", minLength: 1 }
       }
+    },
+    brandMessaging: {
+      type: "object",
+      description: "Phase 2 wave-1 (VI-541). Message-house roof \u2014 the single umbrella message above the pillars.",
+      additionalProperties: false,
+      required: ["roof"],
+      properties: {
+        roof: { type: "string", minLength: 1, description: "One overarching statement the pillars support." }
+      }
+    },
+    brandBoilerplate: {
+      type: "object",
+      description: 'Phase 2 wave-1 (VI-541). Reusable "about us" copy \u2014 short and long forms.',
+      additionalProperties: false,
+      required: ["short", "long"],
+      properties: {
+        short: { type: "string", minLength: 1 },
+        long: { type: "string", minLength: 1 }
+      }
+    },
+    brandColorPairing: {
+      type: "object",
+      description: "A color-pairing rule expressed as brand intent (not a computed value).",
+      additionalProperties: false,
+      required: ["use", "with", "rule"],
+      properties: {
+        use: { type: "string", minLength: 1, description: "The token or role being used (e.g. --primary)." },
+        with: { type: "string", minLength: 1, description: "What it pairs against (token, role, or surface)." },
+        rule: { type: "string", minLength: 1, description: "The intent \u2014 when and how the pairing is allowed." }
+      }
+    },
+    brandColorUsage: {
+      type: "object",
+      description: "Phase 2 wave-1 (VI-541). Color-usage intent \u2014 the brand's allowed pairings.",
+      additionalProperties: false,
+      required: ["pairings"],
+      properties: {
+        pairings: { type: "array", items: { $ref: "#/$defs/brandColorPairing" }, minItems: 1 }
+      }
+    },
+    brandContrastTarget: {
+      type: "object",
+      description: "A contrast target expressed as brand intent (a WCAG 2.1 AA threshold).",
+      additionalProperties: false,
+      required: ["context", "ratio"],
+      properties: {
+        context: { type: "string", minLength: 1, description: "The text/UI context the target applies to." },
+        ratio: { type: "string", minLength: 1, description: 'The minimum contrast ratio (e.g. "4.5:1").' }
+      }
+    },
+    brandAccessibility: {
+      type: "object",
+      description: "Phase 2 wave-1 (VI-541). Accessibility intent \u2014 the standard and its contrast targets (authored as intent; live computation is the render surface's concern).",
+      additionalProperties: false,
+      required: ["standard", "contrast", "intent"],
+      properties: {
+        standard: { type: "string", minLength: 1, description: 'The conformance standard. Visor targets "WCAG 2.1 AA".' },
+        contrast: { type: "array", items: { $ref: "#/$defs/brandContrastTarget" }, minItems: 1 },
+        intent: { type: "string", minLength: 1, description: "How the brand applies the standard (intent, not computed results)." }
+      }
     }
   }
 };
@@ -1110,6 +1299,7 @@ var KNOWN_TOP_LEVEL_KEYS = /* @__PURE__ */ new Set([
   "group",
   "label",
   "default-mode",
+  "color-scheme",
   "colors",
   "colors-dark",
   "typography",
@@ -1390,6 +1580,12 @@ function validateConfig(config) {
       errors.push("'default-mode' must be either 'dark' or 'light'");
     }
   }
+  if (obj["color-scheme"] !== void 0) {
+    const scheme = obj["color-scheme"];
+    if (scheme !== "dark-only" && scheme !== "light-only" && scheme !== "adaptive") {
+      errors.push("'color-scheme' must be one of: dark-only, light-only, adaptive");
+    }
+  }
   if (typeof obj.colors !== "object" || obj.colors === null) {
     errors.push("'colors' is required and must be an object");
     return { valid: false, errors };
@@ -1679,6 +1875,9 @@ function resolveConfig(config) {
     name: config.name,
     ...config.label !== void 0 && { label: config.label },
     ...config["default-mode"] !== void 0 && { "default-mode": config["default-mode"] },
+    // BO-55: always-resolved brand constraint — existing themes (no field) resolve
+    // to 'adaptive', preserving back-compat.
+    "color-scheme": config["color-scheme"] ?? "adaptive",
     version: 1,
     colors: {
       primary: colors.primary,
@@ -2371,8 +2570,8 @@ ${validation.errors.map((e) => `  - ${e}`).join("\n")}`
   const output = {
     primitivesCss: generatePrimitivesCss(primitives, resolved),
     semanticCss: generateSemanticCss(tokens),
-    lightCss: generateLightCss(tokens),
-    darkCss: generateDarkCss(tokens),
+    lightCss: generateLightCss(tokens, { colorScheme: resolved["color-scheme"] }),
+    darkCss: generateDarkCss(tokens, { colorScheme: resolved["color-scheme"] }),
     fullBundleCss: generateFullBundleCss(primitives, tokens, resolved)
   };
   return { config: resolved, primitives, tokens, output };
@@ -3719,6 +3918,36 @@ function extractBackgroundSurface(declarations) {
   }
   return result;
 }
+function detectExplicitColorScheme(files) {
+  for (const file of files) {
+    const content = file.content.replace(/\/\*[\s\S]*?\*\//g, "");
+    const re = /(?<![\w-])color-scheme\s*:\s*([^;}]+)/gi;
+    let m;
+    while ((m = re.exec(content)) !== null) {
+      const keywords = m[1].trim().toLowerCase().split(/\s+/).filter((k) => k.length > 0 && k !== "only");
+      const hasDark = keywords.includes("dark");
+      const hasLight = keywords.includes("light");
+      if (hasDark && hasLight) return "adaptive";
+      if (hasDark) return "dark-only";
+      if (hasLight) return "light-only";
+      if (keywords.includes("normal")) return "adaptive";
+    }
+  }
+  return null;
+}
+function detectColorScheme(files, bgSurface, warnings) {
+  const explicit = detectExplicitColorScheme(files);
+  const heuristic = bgSurface.dark.background && !bgSurface.light.background ? "dark-only" : "adaptive";
+  if (explicit) {
+    if (heuristic !== "adaptive" && heuristic !== explicit) {
+      warnings.push(
+        `color-scheme ambiguity: source CSS explicitly declares 'color-scheme: ${explicit}' but the background heuristic suggests '${heuristic}'. Using the explicit declaration \u2014 review the source if this is unexpected.`
+      );
+    }
+    return explicit;
+  }
+  return heuristic;
+}
 function extractFromCSS(files, name = "extracted-theme") {
   const warnings = [];
   const allDeclarations = [];
@@ -3792,6 +4021,7 @@ function extractFromCSS(files, name = "extracted-theme") {
   if (Object.keys(darkColors).length > 0) {
     config["colors-dark"] = darkColors;
   }
+  config["color-scheme"] = detectColorScheme(files, bgSurface, warnings);
   if (typography.heading || typography.display || typography.body || typography.mono) {
     config.typography = {};
     if (typography.heading) config.typography.heading = typography.heading;
@@ -3862,6 +4092,7 @@ export {
   generateThemeFromConfig,
   getContrastRatio,
   getKnownTokenRefs,
+  getLuminance,
   googleFontsCatalog,
   hasBrandPassthrough,
   hexToOklch,