@loworbitstudio/visor-theme-engine 0.15.0 → 0.16.0

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

@@ -224,6 +224,171 @@ 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;
+}
+/** 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;
+}
+/** 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.
+ */
+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;
+}
+/**
+ * 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 +546,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 +779,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 { 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 };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@loworbitstudio/visor-theme-engine",
-  "version": "0.15.0",
+  "version": "0.16.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",
@@ -100,7 +100,7 @@
           "properties": {
             "family": {
               "type": "string",
-              "description": "Google Fonts family name or CSS font stack."
+              "description": "Font family name — Google Fonts name, Visor Fonts name, or CSS font stack."
             },
             "weight": {
               "type": "integer",
@@ -111,7 +111,7 @@
             "source": {
               "type": "string",
               "enum": ["google-fonts", "visor-fonts", "local"],
-              "description": "Font source. Defaults to Google Fonts lookup, then local."
+              "description": "Font source. Default: \"google-fonts\". Use \"visor-fonts\" for CDN-hosted fonts, \"local\" for self-hosted fonts."
             },
             "org": {
               "type": "string",
@@ -126,7 +126,7 @@
           "properties": {
             "family": {
               "type": "string",
-              "description": "Google Fonts family name or CSS font stack."
+              "description": "Font family name — Google Fonts name, Visor Fonts name, or CSS font stack."
             },
             "weight": {
               "type": "integer",
@@ -137,7 +137,7 @@
             "source": {
               "type": "string",
               "enum": ["google-fonts", "visor-fonts", "local"],
-              "description": "Font source. Defaults to Google Fonts lookup, then local."
+              "description": "Font source. Default: \"google-fonts\". Use \"visor-fonts\" for CDN-hosted fonts, \"local\" for self-hosted fonts."
             },
             "org": {
               "type": "string",
@@ -151,7 +151,7 @@
           "properties": {
             "family": {
               "type": "string",
-              "description": "Google Fonts family name or CSS font stack."
+              "description": "Font family name — Google Fonts name, Visor Fonts name, or CSS font stack."
             },
             "weight": {
               "type": "integer",
@@ -162,7 +162,7 @@
             "source": {
               "type": "string",
               "enum": ["google-fonts", "visor-fonts", "local"],
-              "description": "Font source. Defaults to Google Fonts lookup, then local."
+              "description": "Font source. Default: \"google-fonts\". Use \"visor-fonts\" for CDN-hosted fonts, \"local\" for self-hosted fonts."
             },
             "org": {
               "type": "string",
@@ -293,6 +293,59 @@
         ]
       }
     },
+    "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."
+        }
+      }
+    },
     "spacing": {
       "type": "object",
       "description": "Spacing configuration.",
@@ -460,6 +513,101 @@
           "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" }
+      }
+    },
+    "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 }
+      }
     }
   }
 }