@loworbitstudio/visor-theme-engine 0.15.1 → 0.17.0

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

@@ -224,6 +224,228 @@ interface ThemeBrandResult {
     warnings: string[];
 }
 
+/**
+ * Brand-strategy types for the Visor theme engine (VI-505).
+ *
+ * The Brand Record as validated, serializable, theme-aware data — a top-level
+ * `brand-strategy` block in `.visor.yaml`, SIBLING to the asset-only `brand`
+ * block (`packages/theme-engine/src/brand/`). The two have different lifecycles
+ * and consumers: `brand` declares logo/wordmark/etc. assets; `brand-strategy`
+ * declares positioning, personality, pillars, voice, and tone.
+ *
+ * Shape follows F1 — Visor's authored Brand Record
+ * (`docs/brand/visor-brand-record.yaml`) — itself derived from the VI-498
+ * research sketch (§5a).
+ *
+ * This module is deliberately self-contained and engine-decoupled (D4): the
+ * types, the pure validators (coherence context is injected, never imported),
+ * and the serializer lift cleanly into a future `@loworbitstudio/visor-brand`
+ * package. Engine-specific wiring (the known-token set, the comprehensive
+ * `validate()` pass, the manifest serialization call-site) lives outside.
+ */
+/** Positioning — the onliness, category, and differentiation wedge. */
+interface BrandPositioning {
+    /** The single sentence that passes Neumeier's "only" test. */
+    onliness: string;
+    /** The category the brand competes in (e.g. "design system"). */
+    category: string;
+    /** What sets the brand apart within that category. */
+    differentiation: string;
+}
+/** A personality trait sharpened by its antonym (brand-as-person). */
+interface BrandPersonalityTrait {
+    /** The trait (e.g. "precise"). */
+    trait: string;
+    /** What the trait is NOT — the antonym that earns it its keep (e.g. "fussy"). */
+    not: string;
+}
+/**
+ * Brand archetype assignment (Pearson & Mark — twelve archetypes). Primary is
+ * required; secondary and tertiary are optional refinements.
+ */
+interface BrandArchetype {
+    primary: string;
+    secondary?: string;
+    tertiary?: string;
+}
+/**
+ * What a pillar governs — the link that turns a slogan into a checkable claim.
+ * Targets span three namespaces: design tokens, registry components, and
+ * meta-surfaces (the manifest, the CLI, component metadata). The `openness`
+ * pillar governs the last of these, which is why `governs` accepts more than
+ * tokens/components (F1 schema note). At least one target list is expected.
+ */
+interface BrandGoverns {
+    /** Semantic token refs (with or without the leading `--`), or `"*"` for all. */
+    tokens?: string[];
+    /** Registry component names, or `"*"` for all. */
+    components?: string[];
+    /** Meta-surfaces (e.g. `manifest`, `cli`, `component-metadata`). */
+    surfaces?: string[];
+}
+/** A strategic pillar — an essence word made operational. */
+interface BrandPillar {
+    /** Stable id (e.g. "coherence"). */
+    id: string;
+    /** The pillar's claim in one line. */
+    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 {
+    /** Trait name (e.g. "plainspoken"). */
+    name: string;
+    /** What to do. */
+    do: string;
+    /** What not to do. */
+    dont: string;
+    /** A worked example sentence (F1 carries one on every trait). */
+    example?: string;
+}
+/** Voice — fixed across the brand; never flexes. */
+interface BrandVoice {
+    traits: BrandVoiceTrait[];
+}
+/** A single tone entry, keyed (in `tone`) to a recognized UI state. */
+interface BrandToneEntry {
+    /** The feeling the copy should evoke in this state. */
+    feeling: string;
+    /** A worked example message for this state. */
+    example: string;
+}
+/** A lexicon pairing — the word to use and the one to avoid. */
+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). 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;
+    /** 2–3 internal-facing core words (Aaker essence). */
+    essence: string[];
+    personality: BrandPersonalityTrait[];
+    archetype: BrandArchetype;
+    pillars: BrandPillar[];
+    voice: BrandVoice;
+    /** Voice flexed per UI state. Keys ∈ recognized UI states. */
+    tone: Record<string, BrandToneEntry>;
+    lexicon: BrandLexiconEntry[];
+    /** 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
+ * `visor-manifest.json` under `brand_strategy` (D3). Structurally identical to
+ * the authored shape so an agent reads `voice.traits` / `tone.error` the way it
+ * reads a component's `when_to_use`. Only PUBLIC strategies are serialized.
+ */
+type SerializedBrandStrategy = BrandStrategy;
+/** Recognized UI states a `tone` key may target (coherence check D2). */
+declare const DEFAULT_BRAND_STRATEGY_TONE_STATES: readonly string[];
+/** Recognized meta-surfaces a pillar may govern (coherence check D2). */
+declare const DEFAULT_BRAND_STRATEGY_SURFACES: readonly string[];
+/** Valid `visibility` values. */
+declare const BRAND_VISIBILITIES: readonly BrandVisibility[];
+/** Wildcard accepted in any `governs` target list — matches all of that namespace. */
+declare const GOVERNS_WILDCARD = "*";
+type BrandStrategyIssueSeverity = "error" | "warning";
+/** A single validation finding. Mirrors the engine's `ValidationIssue` shape. */
+interface BrandStrategyIssue {
+    severity: BrandStrategyIssueSeverity;
+    code: string;
+    message: string;
+    path?: string;
+}
+/** Structured validation result for a brand-strategy block. */
+interface BrandStrategyValidationResult {
+    valid: boolean;
+    errors: BrandStrategyIssue[];
+    warnings: BrandStrategyIssue[];
+}
+/**
+ * Coherence context — the real-world sets a strategy's links are checked
+ * against. Injected by the caller (the engine `validate()` pass, the manifest
+ * builder, or a test) so the validator stays pure and engine-decoupled (D4).
+ */
+interface BrandStrategyContext {
+    /** Known semantic token names WITHOUT the leading `--` (e.g. "primary", "surface-card"). When omitted, token coherence is skipped. */
+    tokens?: ReadonlySet<string>;
+    /** Known registry component names. When omitted, only `"*"` is accepted for components. */
+    components?: ReadonlySet<string>;
+    /** Recognized meta-surfaces. Defaults to {@link DEFAULT_BRAND_STRATEGY_SURFACES}. */
+    surfaces?: ReadonlySet<string>;
+    /** Recognized UI states for `tone` keys. Defaults to {@link DEFAULT_BRAND_STRATEGY_TONE_STATES}. */
+    states?: ReadonlySet<string>;
+}
+
 /**
  * Types for the Visor Theme Engine
  *
@@ -381,6 +603,15 @@ interface VisorThemeConfig {
      * Omitted → the Visor default brand (stock themes are not logo-less).
      */
     brand?: VisorBrand;
+    /**
+     * Brand-strategy block (VI-505) — 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→tokens/components/surfaces; tone→UI states) and
+     * serialized to the agent manifest. Liftable into a future
+     * `@loworbitstudio/visor-brand` package (D4).
+     */
+    "brand-strategy"?: BrandStrategy;
     spacing?: {
         base?: number;
     };
@@ -605,4 +836,4 @@ interface ThemeData {
     output: ThemeOutput;
 }
 
-export { type BrandSlot as B, type ColorRole as C, type FontResolveOptions as F, type GoogleFontEntry as G, type OKLCH as O, type ParsedColor as P, type ResolvedThemeConfig as R, type SelectiveShadeScale as S, type ThemeFontResult as T, type VisorTypography as V, 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 GeneratedPrimitives as g, type ThemeOutput as h, type ThemeData as i, type VisorThemeConfig as j, type FullShadeScale as k, type RGB as l, type SemanticTokens as m, type ShadeStep as n, BRAND_VARIANTS as o, type BrandVariant as p, type ColorFormat as q, type FontSource as r, type RGBA as s, type SemanticTokenValue as t };
+export { GOVERNS_WILDCARD as $, type BrandContrastTarget as A, type BrandSlot as B, type ColorRole as C, type BrandGoverns as D, type BrandLexiconEntry as E, type FontResolveOptions as F, type GoogleFontEntry as G, type BrandMessaging as H, type BrandPersonalityTrait as I, type BrandPillar as J, type BrandPositioning as K, type BrandStrategyIssueSeverity as L, type BrandToneEntry as M, type BrandVariant as N, type OKLCH as O, type ParsedColor as P, type BrandVisibility as Q, type ResolvedThemeConfig as R, type SerializedBrandStrategy as S, type ThemeFontResult as T, type BrandVoice as U, type VisorTypography as V, type BrandVoiceTrait as W, type ColorFormat as X, DEFAULT_BRAND_STRATEGY_SURFACES as Y, DEFAULT_BRAND_STRATEGY_TONE_STATES as Z, type FontSource as _, type FontResolution as a, type RGBA as a0, type SemanticTokenValue as a1, 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 BrandAccessibility as v, type BrandArchetype as w, type BrandBoilerplate as x, type BrandColorPairing as y, type BrandColorUsage as z };

package/package.json

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

@@ -22,7 +22,7 @@
     },
     "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",
@@ -293,6 +293,69 @@
         ]
       }
     },
+    "brand-strategy": {
+      "type": "object",
+      "description": "Brand-strategy block (VI-505) — 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–3 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 — 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 — 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) — 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.",
@@ -460,6 +523,167 @@
           "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 — 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 — 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 — 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 — 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 — checkable evidence backing this pillar's claim (the message-house foundation)."
+        }
+      }
+    },
+    "brandVoice": {
+      "type": "object",
+      "description": "Voice — 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 — 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 — 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)." }
+      }
     }
   }
 }