@loworbitstudio/visor-theme-engine 0.16.0 → 0.17.1

package/dist/{types-BstIS9rL.d.ts → types-Cvm7vFwe.d.ts}

@@ -291,6 +291,12 @@ interface BrandPillar {
     statement: string;
     /** What the pillar governs (coherence-checked against the live system). */
     governs: BrandGoverns;
+    /**
+     * Reasons-to-believe — the message-house foundation (VI-541, Phase 2 wave-1).
+     * Concrete, checkable evidence backing this pillar's claim. Optional so a
+     * record can carry pillars without proof points.
+     */
+    proof?: string[];
 }
 /** A fixed voice trait with a worked example. */
 interface BrandVoiceTrait {
@@ -319,15 +325,56 @@ interface BrandLexiconEntry {
     use: string;
     avoid: string;
 }
+/** Message-house roof — the single umbrella message above the pillars. */
+interface BrandMessaging {
+    /** One overarching statement the pillars support (message-house roof). */
+    roof: string;
+}
+/** Reusable "about us" copy — short and long forms. */
+interface BrandBoilerplate {
+    short: string;
+    long: string;
+}
+/** A color-pairing rule expressed as brand intent (not a computed value). */
+interface BrandColorPairing {
+    /** The token or role being used (e.g. `--primary`). */
+    use: string;
+    /** What it pairs against (token, role, or surface). */
+    with: string;
+    /** The intent — when and how the pairing is allowed. */
+    rule: string;
+}
+/** Color-usage intent — the brand's allowed pairings. */
+interface BrandColorUsage {
+    pairings: BrandColorPairing[];
+}
+/** A contrast target expressed as brand intent (a WCAG 2.1 AA threshold). */
+interface BrandContrastTarget {
+    /** The text/UI context the target applies to. */
+    context: string;
+    /** The minimum contrast ratio (e.g. "4.5:1"). */
+    ratio: string;
+}
+/** Accessibility intent — the standard and its contrast targets. */
+interface BrandAccessibility {
+    /** The conformance standard. Visor targets "WCAG 2.1 AA". */
+    standard: string;
+    /** WCAG 2.1 AA contrast targets, authored as intent (live computation is the render surface's concern). */
+    contrast: BrandContrastTarget[];
+    /** How the brand applies the standard (intent, not computed results). */
+    intent: string;
+}
 /** Visibility of a brand strategy. Client brands are `private`. */
 type BrandVisibility = "public" | "private";
 /**
  * The `brand-strategy` block — strategy + verbal identity as data.
  *
  * `tone` is keyed by UI state (`error`, `success`, …); the keys are validated
- * against the recognized UI states (coherence check D2). All ten fields are
- * required in v1 — F1 authors the full record, and the downstream Workbench
- * surfaces render each section.
+ * against the recognized UI states (coherence check D2). The ten Phase 1 fields
+ * are required in v1 — F1 authors the full record, and the downstream Workbench
+ * surfaces render each section. The Phase 2 wave-1 fields (`messaging`,
+ * `taglines`, `boilerplate`, `colorUsage`, `accessibility`; VI-541) are optional
+ * so a record — e.g. a private client brand — can omit them.
  */
 interface BrandStrategy {
     positioning: BrandPositioning;
@@ -343,6 +390,16 @@ interface BrandStrategy {
     /** Aaker core/extended — the immutable subset, as section names. */
     core: string[];
     visibility: BrandVisibility;
+    /** Message-house roof — the umbrella message above the pillars. */
+    messaging?: BrandMessaging;
+    /** Permanent, brand-level signature line(s) — who the brand is, not what it sells this quarter. */
+    taglines?: string[];
+    /** Reusable "about us" copy — short and long forms. */
+    boilerplate?: BrandBoilerplate;
+    /** Color-usage intent — the brand's allowed pairings. */
+    colorUsage?: BrandColorUsage;
+    /** Accessibility intent — WCAG 2.1 AA standard + contrast targets. */
+    accessibility?: BrandAccessibility;
 }
 /**
  * The agent-facing projection of a brand strategy, embedded in
@@ -426,6 +483,11 @@ interface TextSlotOverride {
     /** Letter spacing in logical pixels (Flutter `TextStyle.letterSpacing`). */
     "letter-spacing"?: number;
 }
+/**
+ * BO-55/BO-56: brand color-mode constraint. `dark-only`/`light-only` lock the
+ * brand to a single mode; `adaptive` supports both (the historical default).
+ */
+type ColorScheme = "dark-only" | "light-only" | "adaptive";
 interface VisorThemeConfig {
     name: string;
     version: 1;
@@ -435,6 +497,13 @@ interface VisorThemeConfig {
     label?: string;
     /** Default color mode to force when the theme is activated ('dark' or 'light'). If unset, user/system preference applies. */
     "default-mode"?: "dark" | "light";
+    /**
+     * BO-55: 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.
+     */
+    "color-scheme"?: ColorScheme;
     colors: {
         primary: string;
         accent?: string;
@@ -617,6 +686,12 @@ interface ResolvedThemeConfig {
     label?: string;
     /** Default color mode forwarded from VisorThemeConfig["default-mode"]. */
     "default-mode"?: "dark" | "light";
+    /**
+     * BO-55: Brand constraint for supported color modes. Always resolved (defaults
+     * to 'adaptive' when the theme omits it) so downstream readers (engine/extractor/gate)
+     * get a guaranteed value.
+     */
+    "color-scheme": ColorScheme;
     version: 1;
     colors: {
         primary: string;
@@ -779,4 +854,4 @@ interface ThemeData {
     output: ThemeOutput;
 }
 
-export { type BrandPositioning as A, type BrandSlot as B, type ColorRole as C, type BrandStrategyIssueSeverity as D, type BrandToneEntry as E, type FontResolveOptions as F, type GoogleFontEntry as G, type BrandVariant as H, type BrandVisibility as I, type BrandVoice as J, type BrandVoiceTrait as K, type ColorFormat as L, DEFAULT_BRAND_STRATEGY_SURFACES as M, DEFAULT_BRAND_STRATEGY_TONE_STATES as N, type OKLCH as O, type ParsedColor as P, type FontSource as Q, type ResolvedThemeConfig as R, type SerializedBrandStrategy as S, type ThemeFontResult as T, GOVERNS_WILDCARD as U, type VisorTypography as V, type RGBA as W, type SemanticTokenValue as X, type FontResolution as a, type FontDisplayStrategy as b, type VisorBrand as c, type BrandSource as d, type BrandResolution as e, type ThemeBrandResult as f, type BrandStrategy as g, type BrandStrategyContext as h, type BrandStrategyIssue as i, type BrandStrategyValidationResult as j, type GeneratedPrimitives as k, type ThemeOutput as l, type ThemeData as m, type VisorThemeConfig as n, type FullShadeScale as o, type SelectiveShadeScale as p, type RGB as q, type SemanticTokens as r, type ShadeStep as s, BRAND_VARIANTS as t, BRAND_VISIBILITIES as u, type BrandArchetype as v, type BrandGoverns as w, type BrandLexiconEntry as x, type BrandPersonalityTrait as y, type BrandPillar as z };
+export { type FontSource as $, type BrandColorUsage as A, type BrandSlot as B, type ColorScheme as C, type BrandContrastTarget as D, type BrandGoverns as E, type FontResolveOptions as F, type GoogleFontEntry as G, type BrandLexiconEntry as H, type BrandMessaging as I, type BrandPersonalityTrait as J, type BrandPillar as K, type BrandPositioning as L, type BrandStrategyIssueSeverity as M, type BrandToneEntry as N, type OKLCH as O, type ParsedColor as P, type BrandVariant as Q, type ResolvedThemeConfig as R, type SerializedBrandStrategy as S, type ThemeFontResult as T, type BrandVisibility as U, type VisorTypography as V, type BrandVoice as W, type BrandVoiceTrait as X, type ColorFormat as Y, DEFAULT_BRAND_STRATEGY_SURFACES as Z, DEFAULT_BRAND_STRATEGY_TONE_STATES as _, type FontResolution as a, GOVERNS_WILDCARD as a0, type RGBA as a1, type SemanticTokenValue as a2, type FontDisplayStrategy as b, type VisorBrand as c, type BrandSource as d, type BrandResolution as e, type ThemeBrandResult as f, type BrandStrategy as g, type BrandStrategyContext as h, type BrandStrategyIssue as i, type BrandStrategyValidationResult as j, type GeneratedPrimitives as k, type ThemeOutput as l, type ThemeData as m, type VisorThemeConfig as n, type FullShadeScale as o, type ColorRole as p, type SelectiveShadeScale as q, type RGB as r, type SemanticTokens as s, type ShadeStep as t, BRAND_VARIANTS as u, BRAND_VISIBILITIES as v, type BrandAccessibility as w, type BrandArchetype as x, type BrandBoilerplate as y, type BrandColorPairing as z };

package/package.json

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

@@ -29,6 +29,11 @@
       "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) — '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.",
@@ -343,7 +348,17 @@
           "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) — who the brand is, not what it sells this quarter."
+        },
+        "boilerplate": { "$ref": "#/$defs/brandBoilerplate" },
+        "colorUsage": { "$ref": "#/$defs/brandColorUsage" },
+        "accessibility": { "$ref": "#/$defs/brandAccessibility" }
       }
     },
     "spacing": {
@@ -565,7 +580,13 @@
       "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 — checkable evidence backing this pillar's claim (the message-house foundation)."
+        }
       }
     },
     "brandVoice": {
@@ -608,6 +629,66 @@
         "use": { "type": "string", "minLength": 1 },
         "avoid": { "type": "string", "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)." }
+      }
     }
   }
 }