@loworbitstudio/visor-theme-engine 0.15.1 → 0.17.0

package/dist/index.js

@@ -202,6 +202,397 @@ function validateFontCoverage(css) {
   return { errors };
 }
 
+// src/brand-strategy/types.ts
+var DEFAULT_BRAND_STRATEGY_TONE_STATES = [
+  "error",
+  "success",
+  "warning",
+  "info",
+  "empty",
+  "loading",
+  "validation-warning"
+];
+var DEFAULT_BRAND_STRATEGY_SURFACES = [
+  "manifest",
+  "cli",
+  "component-metadata"
+];
+var BRAND_VISIBILITIES = ["public", "private"];
+var GOVERNS_WILDCARD = "*";
+
+// src/brand-strategy/validate.ts
+function error(code, message, path) {
+  const issue2 = { severity: "error", code, message };
+  if (path !== void 0) issue2.path = path;
+  return issue2;
+}
+function isObject(value) {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+function isNonEmptyString(value) {
+  return typeof value === "string" && value.length > 0;
+}
+function isStringArray(value) {
+  return Array.isArray(value) && value.every((item) => typeof item === "string");
+}
+function normalizeTokenRef(ref) {
+  return ref.startsWith("--") ? ref.slice(2) : ref;
+}
+var TOP_LEVEL_KEYS = /* @__PURE__ */ new Set([
+  "positioning",
+  "essence",
+  "personality",
+  "archetype",
+  "pillars",
+  "voice",
+  "tone",
+  "lexicon",
+  "core",
+  "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) {
+  const errors = [];
+  if (!isObject(block)) {
+    errors.push(error("BRAND_STRATEGY_STRUCTURAL", "'brand-strategy' must be an object", "brand-strategy"));
+    return errors;
+  }
+  for (const key of Object.keys(block)) {
+    if (!TOP_LEVEL_KEYS.has(key)) {
+      errors.push(
+        error(
+          "BRAND_STRATEGY_UNKNOWN_KEY",
+          `Unknown key 'brand-strategy.${key}'. Valid keys: ${[...TOP_LEVEL_KEYS].join(", ")}`,
+          `brand-strategy.${key}`
+        )
+      );
+    }
+  }
+  const positioning = block.positioning;
+  if (!isObject(positioning)) {
+    errors.push(error("BRAND_STRATEGY_POSITIONING", "'brand-strategy.positioning' is required and must be an object", "brand-strategy.positioning"));
+  } else {
+    for (const field of ["onliness", "category", "differentiation"]) {
+      if (!isNonEmptyString(positioning[field])) {
+        errors.push(error("BRAND_STRATEGY_POSITIONING", `'brand-strategy.positioning.${field}' is required and must be a non-empty string`, `brand-strategy.positioning.${field}`));
+      }
+    }
+  }
+  if (!isStringArray(block.essence) || block.essence.length === 0) {
+    errors.push(error("BRAND_STRATEGY_ESSENCE", "'brand-strategy.essence' is required and must be a non-empty array of strings", "brand-strategy.essence"));
+  }
+  if (!Array.isArray(block.personality) || block.personality.length === 0) {
+    errors.push(error("BRAND_STRATEGY_PERSONALITY", "'brand-strategy.personality' is required and must be a non-empty array", "brand-strategy.personality"));
+  } else {
+    block.personality.forEach((trait, i) => {
+      if (!isObject(trait) || !isNonEmptyString(trait.trait) || !isNonEmptyString(trait.not)) {
+        errors.push(error("BRAND_STRATEGY_PERSONALITY", `'brand-strategy.personality[${i}]' must have non-empty 'trait' and 'not' strings`, `brand-strategy.personality[${i}]`));
+      }
+    });
+  }
+  const archetype = block.archetype;
+  if (!isObject(archetype)) {
+    errors.push(error("BRAND_STRATEGY_ARCHETYPE", "'brand-strategy.archetype' is required and must be an object", "brand-strategy.archetype"));
+  } else {
+    if (!isNonEmptyString(archetype.primary)) {
+      errors.push(error("BRAND_STRATEGY_ARCHETYPE", "'brand-strategy.archetype.primary' is required and must be a non-empty string", "brand-strategy.archetype.primary"));
+    }
+    for (const field of ["secondary", "tertiary"]) {
+      if (archetype[field] !== void 0 && !isNonEmptyString(archetype[field])) {
+        errors.push(error("BRAND_STRATEGY_ARCHETYPE", `'brand-strategy.archetype.${field}' must be a non-empty string when present`, `brand-strategy.archetype.${field}`));
+      }
+    }
+  }
+  if (!Array.isArray(block.pillars) || block.pillars.length === 0) {
+    errors.push(error("BRAND_STRATEGY_PILLARS", "'brand-strategy.pillars' is required and must be a non-empty array", "brand-strategy.pillars"));
+  } else {
+    block.pillars.forEach((pillar, i) => {
+      errors.push(...checkPillarStructure(pillar, i));
+    });
+  }
+  const voice = block.voice;
+  if (!isObject(voice) || !Array.isArray(voice.traits) || voice.traits.length === 0) {
+    errors.push(error("BRAND_STRATEGY_VOICE", "'brand-strategy.voice' is required and must have a non-empty 'traits' array", "brand-strategy.voice"));
+  } else {
+    voice.traits.forEach((trait, i) => {
+      if (!isObject(trait) || !isNonEmptyString(trait.name) || !isNonEmptyString(trait.do) || !isNonEmptyString(trait.dont)) {
+        errors.push(error("BRAND_STRATEGY_VOICE", `'brand-strategy.voice.traits[${i}]' must have non-empty 'name', 'do', and 'dont' strings`, `brand-strategy.voice.traits[${i}]`));
+      } else if (trait.example !== void 0 && !isNonEmptyString(trait.example)) {
+        errors.push(error("BRAND_STRATEGY_VOICE", `'brand-strategy.voice.traits[${i}].example' must be a non-empty string when present`, `brand-strategy.voice.traits[${i}].example`));
+      }
+    });
+  }
+  const tone = block.tone;
+  if (!isObject(tone) || Object.keys(tone).length === 0) {
+    errors.push(error("BRAND_STRATEGY_TONE", "'brand-strategy.tone' is required and must be a non-empty object keyed by UI state", "brand-strategy.tone"));
+  } else {
+    for (const [state, entry] of Object.entries(tone)) {
+      if (!isObject(entry) || !isNonEmptyString(entry.feeling) || !isNonEmptyString(entry.example)) {
+        errors.push(error("BRAND_STRATEGY_TONE", `'brand-strategy.tone.${state}' must have non-empty 'feeling' and 'example' strings`, `brand-strategy.tone.${state}`));
+      }
+    }
+  }
+  if (!Array.isArray(block.lexicon) || block.lexicon.length === 0) {
+    errors.push(error("BRAND_STRATEGY_LEXICON", "'brand-strategy.lexicon' is required and must be a non-empty array", "brand-strategy.lexicon"));
+  } else {
+    block.lexicon.forEach((entry, i) => {
+      if (!isObject(entry) || !isNonEmptyString(entry.use) || !isNonEmptyString(entry.avoid)) {
+        errors.push(error("BRAND_STRATEGY_LEXICON", `'brand-strategy.lexicon[${i}]' must have non-empty 'use' and 'avoid' strings`, `brand-strategy.lexicon[${i}]`));
+      }
+    });
+  }
+  if (!isStringArray(block.core) || block.core.length === 0) {
+    errors.push(error("BRAND_STRATEGY_CORE", "'brand-strategy.core' is required and must be a non-empty array of strings", "brand-strategy.core"));
+  }
+  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) {
+  const path = `brand-strategy.pillars[${index}]`;
+  if (!isObject(pillar)) {
+    return [error("BRAND_STRATEGY_PILLARS", `'${path}' must be an object`, path)];
+  }
+  const errors = [];
+  if (!isNonEmptyString(pillar.id)) {
+    errors.push(error("BRAND_STRATEGY_PILLARS", `'${path}.id' is required and must be a non-empty string`, `${path}.id`));
+  }
+  if (!isNonEmptyString(pillar.statement)) {
+    errors.push(error("BRAND_STRATEGY_PILLARS", `'${path}.statement' is required and must be a non-empty string`, `${path}.statement`));
+  }
+  const governs = pillar.governs;
+  if (!isObject(governs)) {
+    errors.push(error("BRAND_STRATEGY_PILLARS", `'${path}.governs' is required and must be an object`, `${path}.governs`));
+  } else {
+    for (const key of Object.keys(governs)) {
+      if (!GOVERNS_KEYS.has(key)) {
+        errors.push(error("BRAND_STRATEGY_GOVERNS", `Unknown key '${path}.governs.${key}'. Valid keys: ${[...GOVERNS_KEYS].join(", ")}`, `${path}.governs.${key}`));
+      }
+    }
+    for (const key of GOVERNS_KEYS) {
+      const list = governs[key];
+      if (list === void 0) continue;
+      if (!isStringArray(list)) {
+        errors.push(error("BRAND_STRATEGY_GOVERNS", `'${path}.governs.${key}' must be an array of strings`, `${path}.governs.${key}`));
+      } else if (list.length === 0) {
+        errors.push(error("BRAND_STRATEGY_GOVERNS", `'${path}.governs.${key}' must not be empty when present`, `${path}.governs.${key}`));
+      }
+    }
+    if (governs.tokens === void 0 && governs.components === void 0 && governs.surfaces === void 0) {
+      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 = {}) {
+  const errors = [];
+  const surfaces = ctx.surfaces ?? new Set(DEFAULT_BRAND_STRATEGY_SURFACES);
+  const states = ctx.states ?? new Set(DEFAULT_BRAND_STRATEGY_TONE_STATES);
+  strategy.pillars.forEach((pillar, i) => {
+    const path = `brand-strategy.pillars[${i}].governs`;
+    if (ctx.tokens && pillar.governs.tokens) {
+      for (const ref of pillar.governs.tokens) {
+        if (ref === GOVERNS_WILDCARD) continue;
+        if (!ctx.tokens.has(normalizeTokenRef(ref))) {
+          errors.push(error("BRAND_STRATEGY_GOVERNS_TOKEN", `Pillar '${pillar.id}' governs token '${ref}', which is not a known Visor token`, `${path}.tokens`));
+        }
+      }
+    }
+    if (pillar.governs.components) {
+      for (const ref of pillar.governs.components) {
+        if (ref === GOVERNS_WILDCARD) continue;
+        if (ctx.components && !ctx.components.has(ref)) {
+          errors.push(error("BRAND_STRATEGY_GOVERNS_COMPONENT", `Pillar '${pillar.id}' governs component '${ref}', which is not a known Visor component`, `${path}.components`));
+        }
+      }
+    }
+    if (pillar.governs.surfaces) {
+      for (const ref of pillar.governs.surfaces) {
+        if (!surfaces.has(ref)) {
+          errors.push(error("BRAND_STRATEGY_GOVERNS_SURFACE", `Pillar '${pillar.id}' governs surface '${ref}', which is not a recognized meta-surface (${[...surfaces].join(", ")})`, `${path}.surfaces`));
+        }
+      }
+    }
+  });
+  for (const state of Object.keys(strategy.tone)) {
+    if (!states.has(state)) {
+      errors.push(error("BRAND_STRATEGY_TONE_STATE", `tone key '${state}' does not map to a recognized UI state (${[...states].join(", ")})`, `brand-strategy.tone.${state}`));
+    }
+  }
+  return errors;
+}
+function validateBrandStrategy(block, ctx = {}) {
+  const errors = checkBrandStrategyStructure(block);
+  const warnings = [];
+  if (errors.length > 0) {
+    return { valid: false, errors, warnings };
+  }
+  for (const issue2 of checkBrandStrategyCoherence(block, ctx)) {
+    (issue2.severity === "error" ? errors : warnings).push(issue2);
+  }
+  return { valid: errors.length === 0, errors, warnings };
+}
+
+// src/brand-strategy/serialize.ts
+function compactGoverns(governs) {
+  const out = {};
+  if (governs.tokens) out.tokens = [...governs.tokens];
+  if (governs.components) out.components = [...governs.components];
+  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;
+  }
+  const archetype = { primary: strategy.archetype.primary };
+  if (strategy.archetype.secondary !== void 0) archetype.secondary = strategy.archetype.secondary;
+  if (strategy.archetype.tertiary !== void 0) archetype.tertiary = strategy.archetype.tertiary;
+  const tone = {};
+  for (const [state, entry] of Object.entries(strategy.tone)) {
+    tone[state] = { feeling: entry.feeling, example: entry.example };
+  }
+  const serialized = {
+    positioning: {
+      onliness: strategy.positioning.onliness,
+      category: strategy.positioning.category,
+      differentiation: strategy.positioning.differentiation
+    },
+    essence: [...strategy.essence],
+    personality: strategy.personality.map((p) => ({ trait: p.trait, not: p.not })),
+    archetype,
+    pillars: strategy.pillars.map(serializePillar),
+    voice: {
+      traits: strategy.voice.traits.map((t) => {
+        const trait = {
+          name: t.name,
+          do: t.do,
+          dont: t.dont
+        };
+        if (t.example !== void 0) trait.example = t.example;
+        return trait;
+      })
+    },
+    tone,
+    lexicon: strategy.lexicon.map((l) => ({ use: l.use, avoid: l.avoid })),
+    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
 import { parse as parseYaml } from "yaml";
 
@@ -230,7 +621,7 @@ var visor_theme_schema_default = {
     },
     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."
+      description: "Human-readable display name for the theme (e.g. 'My Brand Pro'). Overrides the name-derived label in the docs theme switcher. Optional."
     },
     "default-mode": {
       type: "string",
@@ -501,6 +892,69 @@ var visor_theme_schema_default = {
         ]
       }
     },
+    "brand-strategy": {
+      type: "object",
+      description: "Brand-strategy block (VI-505) \u2014 positioning, personality, pillars, voice, and tone as validated, serializable data. Sibling to `brand` (assets): different lifecycle and consumer. NOT expanded into derived CSS values; coherence-checked (pillars govern real tokens/components/surfaces; tone keys map to real UI states) and serialized to the agent manifest under `brand_strategy`.",
+      additionalProperties: false,
+      required: ["positioning", "essence", "personality", "archetype", "pillars", "voice", "tone", "lexicon", "core", "visibility"],
+      properties: {
+        positioning: { $ref: "#/$defs/brandPositioning" },
+        essence: {
+          type: "array",
+          items: { type: "string" },
+          minItems: 1,
+          description: "2\u20133 internal-facing core words (Aaker essence)."
+        },
+        personality: {
+          type: "array",
+          items: { $ref: "#/$defs/brandPersonalityTrait" },
+          minItems: 1,
+          description: "Brand-as-person traits, each sharpened by its antonym."
+        },
+        archetype: { $ref: "#/$defs/brandArchetype" },
+        pillars: {
+          type: "array",
+          items: { $ref: "#/$defs/brandPillar" },
+          minItems: 1,
+          description: "Strategic pillars \u2014 essence words made operational, each governing real tokens/components/surfaces."
+        },
+        voice: { $ref: "#/$defs/brandVoice" },
+        tone: {
+          type: "object",
+          description: "Voice flexed per UI state. Keys must be recognized UI states.",
+          minProperties: 1,
+          propertyNames: { enum: ["error", "success", "warning", "info", "empty", "loading", "validation-warning"] },
+          additionalProperties: { $ref: "#/$defs/brandToneEntry" }
+        },
+        lexicon: {
+          type: "array",
+          items: { $ref: "#/$defs/brandLexiconEntry" },
+          minItems: 1,
+          description: "Words to use and the ones to avoid."
+        },
+        core: {
+          type: "array",
+          items: { type: "string" },
+          minItems: 1,
+          description: "Aaker core/extended \u2014 the immutable subset, as section names."
+        },
+        visibility: {
+          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: {
       type: "object",
       description: "Spacing configuration.",
@@ -668,6 +1122,167 @@ var visor_theme_schema_default = {
           description: "Letter spacing in logical pixels (Flutter TextStyle.letterSpacing). Material defaults include negative values, e.g. -0.25 for displayLarge."
         }
       }
+    },
+    brandPositioning: {
+      type: "object",
+      description: "Positioning \u2014 the onliness, category, and differentiation wedge.",
+      additionalProperties: false,
+      required: ["onliness", "category", "differentiation"],
+      properties: {
+        onliness: { type: "string", minLength: 1, description: `The single sentence that passes Neumeier's "only" test.` },
+        category: { type: "string", minLength: 1, description: 'The category the brand competes in (e.g. "design system").' },
+        differentiation: { type: "string", minLength: 1, description: "What sets the brand apart within that category." }
+      }
+    },
+    brandPersonalityTrait: {
+      type: "object",
+      description: "A personality trait sharpened by its antonym (brand-as-person).",
+      additionalProperties: false,
+      required: ["trait", "not"],
+      properties: {
+        trait: { type: "string", minLength: 1 },
+        not: { type: "string", minLength: 1, description: "The antonym \u2014 what the trait is not." }
+      }
+    },
+    brandArchetype: {
+      type: "object",
+      description: "Brand archetype assignment (Pearson & Mark). Primary required; secondary/tertiary optional.",
+      additionalProperties: false,
+      required: ["primary"],
+      properties: {
+        primary: { type: "string", minLength: 1 },
+        secondary: { type: "string", minLength: 1 },
+        tertiary: { type: "string", minLength: 1 }
+      }
+    },
+    brandGoverns: {
+      type: "object",
+      description: 'What a pillar governs \u2014 design tokens, registry components, and/or meta-surfaces. At least one list is expected; use "*" for all of a namespace.',
+      additionalProperties: false,
+      minProperties: 1,
+      properties: {
+        tokens: { type: "array", items: { type: "string" }, minItems: 1, description: 'Semantic token refs (with or without the leading --), or "*".' },
+        components: { type: "array", items: { type: "string" }, minItems: 1, description: 'Registry component names, or "*" for all.' },
+        surfaces: { type: "array", items: { type: "string", enum: ["manifest", "cli", "component-metadata"] }, minItems: 1, description: "Meta-surfaces a pillar may govern." }
+      }
+    },
+    brandPillar: {
+      type: "object",
+      description: "A strategic pillar \u2014 an essence word made operational.",
+      additionalProperties: false,
+      required: ["id", "statement", "governs"],
+      properties: {
+        id: { type: "string", minLength: 1 },
+        statement: { type: "string", minLength: 1, description: "The pillar's claim in one line." },
+        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: {
+      type: "object",
+      description: "Voice \u2014 fixed across the brand; never flexes.",
+      additionalProperties: false,
+      required: ["traits"],
+      properties: {
+        traits: { type: "array", items: { $ref: "#/$defs/brandVoiceTrait" }, minItems: 1 }
+      }
+    },
+    brandVoiceTrait: {
+      type: "object",
+      description: "A fixed voice trait with a worked example.",
+      additionalProperties: false,
+      required: ["name", "do", "dont"],
+      properties: {
+        name: { type: "string", minLength: 1 },
+        do: { type: "string", minLength: 1, description: "What to do." },
+        dont: { type: "string", minLength: 1, description: "What not to do." },
+        example: { type: "string", minLength: 1, description: "A worked example sentence." }
+      }
+    },
+    brandToneEntry: {
+      type: "object",
+      description: "A single tone entry, keyed (in `tone`) to a recognized UI state.",
+      additionalProperties: false,
+      required: ["feeling", "example"],
+      properties: {
+        feeling: { type: "string", minLength: 1, description: "The feeling the copy should evoke in this state." },
+        example: { type: "string", minLength: 1, description: "A worked example message for this state." }
+      }
+    },
+    brandLexiconEntry: {
+      type: "object",
+      description: "A lexicon pairing \u2014 the word to use and the one to avoid.",
+      additionalProperties: false,
+      required: ["use", "avoid"],
+      properties: {
+        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)." }
+      }
     }
   }
 };
@@ -683,6 +1298,7 @@ var KNOWN_TOP_LEVEL_KEYS = /* @__PURE__ */ new Set([
   "colors-dark",
   "typography",
   "brand",
+  "brand-strategy",
   "spacing",
   "radius",
   "shadows",
@@ -1102,6 +1718,11 @@ function validateConfig(config) {
       }
     }
   }
+  if (obj["brand-strategy"] !== void 0) {
+    for (const iss of checkBrandStrategyStructure(obj["brand-strategy"])) {
+      errors.push(iss.path ? `${iss.message} (at ${iss.path})` : iss.message);
+    }
+  }
   if (obj.overrides !== void 0) {
     if (typeof obj.overrides !== "object" || obj.overrides === null) {
       errors.push("'overrides' must be an object");
@@ -1735,6 +2356,18 @@ var SEMANTIC_MAP = {
   intent: SEMANTIC_INTENT_MAP,
   hairline: SEMANTIC_HAIRLINE_MAP
 };
+function getKnownTokenRefs() {
+  const refs = /* @__PURE__ */ new Set();
+  for (const key of Object.keys(SEMANTIC_TEXT_MAP)) refs.add(`text-${key}`);
+  for (const key of Object.keys(SEMANTIC_SURFACE_MAP)) refs.add(`surface-${key}`);
+  for (const key of Object.keys(SEMANTIC_BORDER_MAP)) refs.add(`border-${key}`);
+  for (const key of Object.keys(SEMANTIC_INTERACTIVE_MAP)) refs.add(`interactive-${key}`);
+  for (const key of Object.keys(SEMANTIC_INTENT_MAP)) refs.add(key);
+  for (const key of Object.keys(SEMANTIC_HAIRLINE_MAP)) {
+    refs.add(key === "default" ? "hairline" : `hairline-${key}`);
+  }
+  return refs;
+}
 
 // src/assign.ts
 function lookupShade(primitives, role, shade) {
@@ -2862,6 +3495,12 @@ function validate(config, options) {
     const resolved = resolveConfig(typedConfig);
     checkResolvedCompleteness(resolved, errors);
   }
+  const brandStrategy = typedConfig["brand-strategy"];
+  if (brandStrategy) {
+    for (const iss of checkBrandStrategyCoherence(brandStrategy, { tokens: getKnownTokenRefs() })) {
+      (iss.severity === "error" ? errors : warnings).push(iss);
+    }
+  }
   if (errors.length === 0) {
     checkContrastWarnings(typedConfig, warnings);
     checkColorSimilarity(typedConfig, warnings);
@@ -3368,8 +4007,12 @@ function extractFromCSS(files, name = "extracted-theme") {
 }
 export {
   BRAND_VARIANTS,
+  BRAND_VISIBILITIES,
+  DEFAULT_BRAND_STRATEGY_SURFACES,
+  DEFAULT_BRAND_STRATEGY_TONE_STATES,
   DEFAULT_VISOR_BRAND,
   FONT_WEIGHT_ALIASES,
+  GOVERNS_WILDCARD,
   SEMANTIC_MAP,
   TAILWIND_GRAY,
   VISOR_BRANDS_CDN,
@@ -3379,6 +4022,8 @@ export {
   assignSemanticTokens,
   buildVisorBrandUrl,
   buildVisorFontUrl,
+  checkBrandStrategyCoherence,
+  checkBrandStrategyStructure,
   clampToSrgb,
   cleanFontValue,
   collectBrandPassthrough,
@@ -3400,6 +4045,7 @@ export {
   generateThemeDataFromConfig,
   generateThemeFromConfig,
   getContrastRatio,
+  getKnownTokenRefs,
   googleFontsCatalog,
   hasBrandPassthrough,
   hexToOklch,
@@ -3426,8 +4072,10 @@ export {
   resolveThemeBrand,
   resolveThemeFonts,
   rgbToHex,
+  serializeBrandStrategy,
   serializeColor,
   validate,
+  validateBrandStrategy,
   validateConfig,
   validateFontCoverage,
   visor_theme_schema_default as visorThemeSchema