@loworbitstudio/visor-theme-engine 0.11.0 → 0.13.0

package/dist/adapters/index.d.ts

@@ -1,4 +1,4 @@
-import { c as GeneratedPrimitives, i as SemanticTokens, R as ResolvedThemeConfig } from '../types-Dwc1V0Nc.js';
+import { g as GeneratedPrimitives, m as SemanticTokens, R as ResolvedThemeConfig } from '../types-CSO2avFQ.js';
 
 /**
  * Adapter types for the Visor theme engine.
@@ -195,8 +195,15 @@ declare function flutterAdapter(input: AdapterInput, options?: FlutterAdapterOpt
  * order — defense in depth, so whichever stylesheet loads first establishes
  * the cascade.
  */
-/** Layer order declaration — must appear before any @layer blocks. */
-declare const LAYER_ORDER = "@layer visor-primitives, visor-semantic, visor-adaptive, visor-bridge;";
+/**
+ * Layer order declaration — must appear before any @layer blocks.
+ *
+ * `visor-brand` (VI-470) is ordered immediately after `visor-semantic`: brand
+ * asset vars (`--brand-*`) sit above semantic tokens so brand overrides stay
+ * cleanly separable, while still below `visor-adaptive` chrome and the
+ * `visor-bridge` framework layer.
+ */
+declare const LAYER_ORDER = "@layer visor-primitives, visor-semantic, visor-brand, visor-adaptive, visor-bridge;";
 /**
  * Wrap CSS content in a named @layer block.
  */

package/dist/adapters/index.js

@@ -15,12 +15,13 @@ import {
   generateTextScaleAliasDecls,
   header,
   parseColor,
+  resolveThemeBrand,
   resolveThemeFonts,
   sectionComment
-} from "../chunk-43TVIXUS.js";
+} from "../chunk-KFTTL3XP.js";
 
 // src/adapters/layers.ts
-var LAYER_ORDER = "@layer visor-primitives, visor-semantic, visor-adaptive, visor-bridge;";
+var LAYER_ORDER = "@layer visor-primitives, visor-semantic, visor-brand, visor-adaptive, visor-bridge;";
 function wrapInLayer(layerName, css) {
   const trimmed = css.trim();
   if (!trimmed) return "";
@@ -629,10 +630,13 @@ ${inner.split("\n").map((l) => `  ${l}`).join("\n")}
 }`);
   }
   semanticLines.push("");
+  const brandResult = resolveThemeBrand(input.config.brand, { scope: scopeClass });
   const adaptiveLayer = wrapInLayer("visor-adaptive", lines.join("\n").trim());
   const semanticLayer = wrapInLayer("visor-semantic", semanticLines.join("\n").trim());
+  const brandLayer = wrapInLayer("visor-brand", brandResult.css);
   const head = fontLines.length > 0 ? fontLines.join("\n") + "\n" : "";
-  return head + LAYER_ORDER + "\n\n" + semanticLayer + "\n\n" + adaptiveLayer + "\n";
+  const layerBlocks = [semanticLayer, brandLayer, adaptiveLayer].filter(Boolean);
+  return head + LAYER_ORDER + "\n\n" + layerBlocks.join("\n\n") + "\n";
 }
 
 // src/flutter/color-to-dart.ts

package/dist/{chunk-43TVIXUS.js → chunk-KFTTL3XP.js}

@@ -217,11 +217,11 @@ function resolveFont(family, options = {}) {
     };
   }
   if (explicitSource === "fontshare") {
-    const cssUrl = buildFontshareCssUrl(family, requestedWeights, italic, display);
+    const cssUrl2 = buildFontshareCssUrl(family, requestedWeights, italic, display);
     return {
       family,
       source: "fontshare",
-      cssUrl,
+      cssUrl: cssUrl2,
       weights: requestedWeights,
       italic,
       display,
@@ -256,7 +256,7 @@ function resolveFont(family, options = {}) {
     const weights = availableWeights.length > 0 ? availableWeights : catalogEntry.weights;
     const hasItalic = catalogEntry.styles.includes("italic");
     const resolvedItalic = italic && hasItalic;
-    const cssUrl = buildGoogleFontsCssUrl(
+    const cssUrl2 = buildGoogleFontsCssUrl(
       catalogEntry.family,
       weights,
       resolvedItalic,
@@ -266,7 +266,7 @@ function resolveFont(family, options = {}) {
       family: catalogEntry.family,
       // Use canonical casing from catalog
       source: "google-fonts",
-      cssUrl,
+      cssUrl: cssUrl2,
       weights,
       italic: resolvedItalic,
       display,
@@ -711,6 +711,180 @@ function resolveThemeFonts(typography, options) {
   };
 }
 
+// src/brand/resolve.ts
+var VISOR_BRANDS_CDN = "https://brands.visor.design";
+var DEFAULT_FORMAT = "svg";
+var DEFAULT_BRAND_SOURCE = "visor-brands";
+var VISOR_DEFAULT_BRAND_PATH = "/themes/visor/brand";
+var DEFAULT_VISOR_BRAND = {
+  org: "low-orbit-studio",
+  source: "local",
+  logo: {
+    slug: "visor",
+    formats: ["svg"],
+    light: `${VISOR_DEFAULT_BRAND_PATH}/visor-logo-light.svg`,
+    dark: `${VISOR_DEFAULT_BRAND_PATH}/visor-logo-dark.svg`,
+    // Aspect ratios are the real SVG viewBoxes from the VI-469 asset set.
+    aspectRatio: "1269.97 / 540",
+    clearSpace: "0.5rem"
+  },
+  brandmark: {
+    slug: "visor",
+    formats: ["svg"],
+    // Single-file mark — same asset on light and dark surfaces.
+    light: `${VISOR_DEFAULT_BRAND_PATH}/visor-brandmark.svg`,
+    dark: `${VISOR_DEFAULT_BRAND_PATH}/visor-brandmark.svg`,
+    aspectRatio: "1 / 1",
+    clearSpace: "0.25rem"
+  },
+  wordmark: {
+    slug: "visor",
+    formats: ["svg"],
+    light: `${VISOR_DEFAULT_BRAND_PATH}/visor-wordmark-light.svg`,
+    dark: `${VISOR_DEFAULT_BRAND_PATH}/visor-wordmark-dark.svg`,
+    aspectRatio: "1100 / 316",
+    clearSpace: "0.5rem"
+  },
+  monochrome: {
+    slug: "visor",
+    formats: ["svg"],
+    // Single-file mark, tinted via mask-image + currentColor.
+    light: `${VISOR_DEFAULT_BRAND_PATH}/visor-monochrome.svg`,
+    dark: `${VISOR_DEFAULT_BRAND_PATH}/visor-monochrome.svg`,
+    aspectRatio: "2210 / 636",
+    clearSpace: "0.25rem"
+  },
+  favicon: {
+    slug: "visor",
+    formats: ["svg", "png"],
+    // The Visor symbol (brandmark) doubles as the favicon source; Phase 2's
+    // build step generates the sized .ico/.png set from it (§4.D).
+    light: `${VISOR_DEFAULT_BRAND_PATH}/visor-favicon.svg`,
+    dark: `${VISOR_DEFAULT_BRAND_PATH}/visor-favicon.svg`,
+    aspectRatio: "1 / 1"
+  }
+};
+function buildVisorBrandUrl(org, slug, variant, mode, format, cdnBase) {
+  const base = cdnBase ?? VISOR_BRANDS_CDN;
+  const orgSegment = org ? `/${org}` : "";
+  const modeSuffix = mode === "dark" ? "-dark" : "";
+  return `${base}${orgSegment}/${slug}/${variant}${modeSuffix}.${format}`;
+}
+function buildLocalBrandPath(slug, variant, mode, format, explicit) {
+  if (explicit) return explicit;
+  const modeSuffix = mode === "dark" ? "-dark" : "";
+  return `/themes/${slug}/brand/${variant}${modeSuffix}.${format}`;
+}
+function resolveBrandSlot(variant, slot, options) {
+  const source = options.source;
+  const format = slot.formats?.[0] ?? DEFAULT_FORMAT;
+  const slug = slot.slug ?? variant;
+  const clearSpace = slot.clearSpace ?? null;
+  const aspectRatio = slot.aspectRatio ?? null;
+  if (source === "local") {
+    const light2 = buildLocalBrandPath(slug, variant, "light", format, slot.light);
+    const dark2 = buildLocalBrandPath(slug, variant, "dark", format, slot.dark);
+    const guidance = slot.light || slot.dark ? null : `Brand variant "${variant}" is a local asset. Place the file(s) at public${light2}${light2 !== dark2 ? ` and public${dark2}` : ""} in your project, or set brand.${variant}.light / .dark to an explicit public/-relative path.`;
+    return { variant, source, light: light2, dark: dark2, clearSpace, aspectRatio, guidance };
+  }
+  const org = options.org ?? "";
+  const light = slot.light ?? buildVisorBrandUrl(org, slug, variant, "light", format, options.cdnBase);
+  const dark = slot.dark ?? buildVisorBrandUrl(org, slug, variant, "dark", format, options.cdnBase);
+  return { variant, source, light, dark, clearSpace, aspectRatio, guidance: null };
+}
+function resolveBrandSource(brand) {
+  return brand.source ?? DEFAULT_BRAND_SOURCE;
+}
+
+// src/brand/types.ts
+var BRAND_VARIANTS = [
+  "logo",
+  "brandmark",
+  "wordmark",
+  "monochrome",
+  "favicon",
+  "animated"
+];
+
+// src/brand/pipeline.ts
+function cssUrl(value) {
+  return `url("${value}")`;
+}
+function staticDeclsFor(r) {
+  const decls = [];
+  decls.push(`--brand-${r.variant}-light: ${cssUrl(r.light)};`);
+  decls.push(`--brand-${r.variant}-dark: ${cssUrl(r.dark)};`);
+  if (r.clearSpace !== null) {
+    decls.push(`--brand-${r.variant}-clear-space: ${r.clearSpace};`);
+  }
+  if (r.aspectRatio !== null) {
+    decls.push(`--brand-${r.variant}-aspect-ratio: ${r.aspectRatio};`);
+  }
+  return decls;
+}
+function modeDecl(r, mode) {
+  return `--brand-${r.variant}: ${cssUrl(r[mode])};`;
+}
+function block(selector, decls) {
+  if (decls.length === 0) return "";
+  return [`${selector} {`, ...decls.map((d) => `  ${d}`), "}"].join("\n");
+}
+function generateBrandCSS(resolutions, scope) {
+  if (resolutions.length === 0) return "";
+  const baseSelector = scope ? scope : ":root";
+  const lightSelector = scope ? `html:not(.dark) ${scope}` : ":root";
+  const darkSelector = scope ? `.dark ${scope}` : ".dark";
+  const pcsSelector = scope ? `${scope}:not(.light)` : ":root:not(.light)";
+  const lines = [];
+  const staticDecls = resolutions.flatMap(staticDeclsFor);
+  lines.push("/* --- Brand: forced-mode aliases + tokens --- */");
+  lines.push(block(baseSelector, staticDecls));
+  lines.push("");
+  const lightDecls = resolutions.map((r) => modeDecl(r, "light"));
+  lines.push("/* --- Brand: variants (light) --- */");
+  lines.push(block(lightSelector, lightDecls));
+  lines.push("");
+  const darkDecls = resolutions.map((r) => modeDecl(r, "dark"));
+  lines.push("/* --- Brand: variants (dark) \u2014 manual toggle --- */");
+  lines.push(block(darkSelector, darkDecls));
+  lines.push("");
+  lines.push("/* --- Brand: variants (dark) \u2014 prefers-color-scheme --- */");
+  const inner = block(pcsSelector, darkDecls);
+  lines.push(
+    `@media (prefers-color-scheme: dark) {
+${inner.split("\n").map((l) => `  ${l}`).join("\n")}
+}`
+  );
+  return lines.join("\n").trim();
+}
+function resolveThemeBrand(brand, options) {
+  const effective = brand ?? DEFAULT_VISOR_BRAND;
+  const scope = options?.scope ?? "";
+  const source = resolveBrandSource(effective);
+  const org = effective.org ?? null;
+  const cdnBase = effective["cdn-overrides"]?.["visor-brands"] ?? null;
+  const slotOptions = { source, org, cdnBase };
+  const warnings = [];
+  const variants = [];
+  const custom = [];
+  for (const variant of BRAND_VARIANTS) {
+    const slot = effective[variant];
+    if (!slot) continue;
+    const resolution = resolveBrandSlot(variant, slot, slotOptions);
+    variants.push(resolution);
+    if (resolution.guidance) warnings.push(resolution.guidance);
+  }
+  if (effective.custom) {
+    for (const [key, slot] of Object.entries(effective.custom)) {
+      const resolution = resolveBrandSlot(key, slot, slotOptions);
+      custom.push(resolution);
+      if (resolution.guidance) warnings.push(resolution.guidance);
+    }
+  }
+  const css = generateBrandCSS([...variants, ...custom], scope);
+  return { variants, custom, css, warnings };
+}
+
 // src/color.ts
 function normalizeHex(hex) {
   let color = hex.replace(/^#/, "");
@@ -1199,7 +1373,7 @@ function sectionComment(label) {
   return `
 /* --- ${label} --- */`;
 }
-function block(selector, declarations) {
+function block2(selector, declarations) {
   if (declarations.length === 0) return "";
   return [selector + " {", ...declarations.map((d) => `  ${d}`), "}", ""].join(
     "\n"
@@ -1356,20 +1530,20 @@ function generatePrimitivesCss(primitives, config, options) {
   const host = options?.scopePrefix ?? ":root";
   lines.push(sectionComment("Primitive: Colors"));
   lines.push(
-    block(host, [generateColorPrimitives(primitives)])
+    block2(host, [generateColorPrimitives(primitives)])
   );
   lines.push(sectionComment("Primitive: Spacing"));
-  lines.push(block(host, generateSpacingPrimitives(config)));
+  lines.push(block2(host, generateSpacingPrimitives(config)));
   lines.push(sectionComment("Primitive: Border Radius"));
-  lines.push(block(host, generateRadiusPrimitives(config)));
+  lines.push(block2(host, generateRadiusPrimitives(config)));
   lines.push(sectionComment("Primitive: Typography"));
-  lines.push(block(host, generateTypographyPrimitives(config, options?.aliasedFamilies)));
+  lines.push(block2(host, generateTypographyPrimitives(config, options?.aliasedFamilies)));
   lines.push(sectionComment("Primitive: Shadows"));
-  lines.push(block(host, generateShadowPrimitives(config)));
+  lines.push(block2(host, generateShadowPrimitives(config)));
   lines.push(sectionComment("Primitive: Motion"));
-  lines.push(block(host, generateMotionPrimitives(config)));
+  lines.push(block2(host, generateMotionPrimitives(config)));
   lines.push(sectionComment("Primitive: Miscellaneous"));
-  lines.push(block(host, generateMiscPrimitives()));
+  lines.push(block2(host, generateMiscPrimitives()));
   return header("Visor Theme \u2014 Primitives") + lines.join("\n");
 }
 function hairlineDeclName(name) {
@@ -1381,32 +1555,32 @@ function generateSemanticCss(tokens) {
   const textDecls = Object.entries(tokens.text).map(
     ([name, { light }]) => `--text-${name}: ${light};`
   );
-  lines.push(block(":root", textDecls));
+  lines.push(block2(":root", textDecls));
   lines.push(sectionComment("Semantic: Surface"));
   const surfaceDecls = Object.entries(tokens.surface).map(
     ([name, { light }]) => `--surface-${name}: ${light};`
   );
-  lines.push(block(":root", surfaceDecls));
+  lines.push(block2(":root", surfaceDecls));
   lines.push(sectionComment("Semantic: Border"));
   const borderDecls = Object.entries(tokens.border).map(
     ([name, { light }]) => `--border-${name}: ${light};`
   );
-  lines.push(block(":root", borderDecls));
+  lines.push(block2(":root", borderDecls));
   lines.push(sectionComment("Semantic: Interactive"));
   const interactiveDecls = Object.entries(tokens.interactive).map(
     ([name, { light }]) => `--interactive-${name}: ${light};`
   );
-  lines.push(block(":root", interactiveDecls));
+  lines.push(block2(":root", interactiveDecls));
   lines.push(sectionComment("Semantic: Intent (aliases)"));
   const intentDecls = Object.entries(tokens.intent).map(
     ([name, { light }]) => `--${name}: ${light};`
   );
-  lines.push(block(":root", intentDecls));
+  lines.push(block2(":root", intentDecls));
   lines.push(sectionComment("Semantic: Hairline (aliases)"));
   const hairlineDecls = Object.entries(tokens.hairline).map(
     ([name, { light }]) => `${hairlineDeclName(name)}: ${light};`
   );
-  lines.push(block(":root", hairlineDecls));
+  lines.push(block2(":root", hairlineDecls));
   return header("Visor Theme \u2014 Semantic") + lines.join("\n");
 }
 var TEXT_SCALE_ALIASES = [
@@ -1474,17 +1648,17 @@ function generateLightCss(tokens, options) {
   const { textDecls, surfaceDecls, borderDecls, interactiveDecls, intentDecls, hairlineDecls } = buildAdaptiveDecls(tokens, "light");
   const host = options?.scopePrefix ?? ":root";
   lines.push(sectionComment("Adaptive: Text (light)"));
-  lines.push(block(host, textDecls));
+  lines.push(block2(host, textDecls));
   lines.push(sectionComment("Adaptive: Surface (light)"));
-  lines.push(block(host, surfaceDecls));
+  lines.push(block2(host, surfaceDecls));
   lines.push(sectionComment("Adaptive: Border (light)"));
-  lines.push(block(host, borderDecls));
+  lines.push(block2(host, borderDecls));
   lines.push(sectionComment("Adaptive: Interactive (light)"));
-  lines.push(block(host, interactiveDecls));
+  lines.push(block2(host, interactiveDecls));
   lines.push(sectionComment("Adaptive: Intent aliases (light)"));
-  lines.push(block(host, intentDecls));
+  lines.push(block2(host, intentDecls));
   lines.push(sectionComment("Adaptive: Hairline aliases (light)"));
-  lines.push(block(host, hairlineDecls));
+  lines.push(block2(host, hairlineDecls));
   return header("Visor Theme \u2014 Light") + lines.join("\n");
 }
 function generateDarkCss(tokens, options) {
@@ -1495,23 +1669,23 @@ function generateDarkCss(tokens, options) {
   const darkSelector = darkSelectors.join(",\n");
   const prefersSelector = prefix ? `${prefix}:not(.light):not(.theme-light):not([data-theme="light"])` : ':root:not(.light):not(.theme-light):not([data-theme="light"])';
   lines.push(sectionComment("Adaptive: Text (dark) \u2014 manual toggle"));
-  lines.push(block(darkSelector, textDecls));
+  lines.push(block2(darkSelector, textDecls));
   lines.push(sectionComment("Adaptive: Surface (dark) \u2014 manual toggle"));
-  lines.push(block(darkSelector, surfaceDecls));
+  lines.push(block2(darkSelector, surfaceDecls));
   lines.push(sectionComment("Adaptive: Border (dark) \u2014 manual toggle"));
-  lines.push(block(darkSelector, borderDecls));
+  lines.push(block2(darkSelector, borderDecls));
   lines.push(sectionComment("Adaptive: Interactive (dark) \u2014 manual toggle"));
-  lines.push(block(darkSelector, interactiveDecls));
+  lines.push(block2(darkSelector, interactiveDecls));
   lines.push(sectionComment("Adaptive: Intent aliases (dark) \u2014 manual toggle"));
-  lines.push(block(darkSelector, intentDecls));
+  lines.push(block2(darkSelector, intentDecls));
   lines.push(sectionComment("Adaptive: Hairline aliases (dark) \u2014 manual toggle"));
-  lines.push(block(darkSelector, hairlineDecls));
+  lines.push(block2(darkSelector, hairlineDecls));
   lines.push(
     sectionComment("Adaptive: Text (dark) \u2014 prefers-color-scheme")
   );
   lines.push(
     `@media (prefers-color-scheme: dark) {
-${block(prefersSelector, textDecls)}}`
+${block2(prefersSelector, textDecls)}}`
   );
   lines.push("");
   lines.push(
@@ -1519,7 +1693,7 @@ ${block(prefersSelector, textDecls)}}`
   );
   lines.push(
     `@media (prefers-color-scheme: dark) {
-${block(prefersSelector, surfaceDecls)}}`
+${block2(prefersSelector, surfaceDecls)}}`
   );
   lines.push("");
   lines.push(
@@ -1527,7 +1701,7 @@ ${block(prefersSelector, surfaceDecls)}}`
   );
   lines.push(
     `@media (prefers-color-scheme: dark) {
-${block(prefersSelector, borderDecls)}}`
+${block2(prefersSelector, borderDecls)}}`
   );
   lines.push("");
   lines.push(
@@ -1535,7 +1709,7 @@ ${block(prefersSelector, borderDecls)}}`
   );
   lines.push(
     `@media (prefers-color-scheme: dark) {
-${block(prefersSelector, interactiveDecls)}}`
+${block2(prefersSelector, interactiveDecls)}}`
   );
   lines.push("");
   lines.push(
@@ -1543,7 +1717,7 @@ ${block(prefersSelector, interactiveDecls)}}`
   );
   lines.push(
     `@media (prefers-color-scheme: dark) {
-${block(prefersSelector, intentDecls)}}`
+${block2(prefersSelector, intentDecls)}}`
   );
   lines.push("");
   lines.push(
@@ -1551,7 +1725,7 @@ ${block(prefersSelector, intentDecls)}}`
   );
   lines.push(
     `@media (prefers-color-scheme: dark) {
-${block(prefersSelector, hairlineDecls)}}`
+${block2(prefersSelector, hairlineDecls)}}`
   );
   lines.push("");
   return header("Visor Theme \u2014 Dark") + lines.join("\n");
@@ -1618,6 +1792,14 @@ export {
   generatePreloadLinks,
   generateStylesheetLinks,
   resolveThemeFonts,
+  VISOR_BRANDS_CDN,
+  VISOR_DEFAULT_BRAND_PATH,
+  DEFAULT_VISOR_BRAND,
+  buildVisorBrandUrl,
+  resolveBrandSlot,
+  resolveBrandSource,
+  BRAND_VARIANTS,
+  resolveThemeBrand,
   normalizeHex,
   isValidHex,
   hexToRgb,

package/dist/index.d.ts

@@ -1,5 +1,5 @@
-import { F as FontResolveOptions, a as FontResolution, V as VisorTypography, b as FontDisplayStrategy, T as ThemeFontResult, G as GoogleFontEntry, R as ResolvedThemeConfig, c as GeneratedPrimitives, d as ThemeOutput, e as ThemeData, f as VisorThemeConfig, g as FullShadeScale, C as ColorRole, S as SelectiveShadeScale, h as RGB, P as ParsedColor, O as OKLCH, i as SemanticTokens, j as ShadeStep } from './types-Dwc1V0Nc.js';
-export { k as ColorFormat, l as FontSource, m as RGBA, n as SemanticTokenValue } from './types-Dwc1V0Nc.js';
+import { F as FontResolveOptions, a as FontResolution, V as VisorTypography, b as FontDisplayStrategy, T as ThemeFontResult, G as GoogleFontEntry, c as VisorBrand, B as BrandSlot, d as BrandSource, e as BrandResolution, f as ThemeBrandResult, R as ResolvedThemeConfig, g as GeneratedPrimitives, h as ThemeOutput, i as ThemeData, j as VisorThemeConfig, k as FullShadeScale, C as ColorRole, S as SelectiveShadeScale, l as RGB, P as ParsedColor, O as OKLCH, m as SemanticTokens, n as ShadeStep } from './types-CSO2avFQ.js';
+export { o as BRAND_VARIANTS, p as BrandVariant, q as ColorFormat, r as FontSource, s as RGBA, t as SemanticTokenValue } from './types-CSO2avFQ.js';
 
 /**
  * Font resolver — maps font family names to loadable font resources.
@@ -150,6 +150,92 @@ interface FontCoverageResult {
 declare function formatFontCoverageError(filename: string, declaredAt: string, family: string): string;
 declare function validateFontCoverage(css: string): FontCoverageResult;
 
+/**
+ * Brand-asset resolver — maps a `brand` block's slots to loadable asset URLs.
+ *
+ * Mirrors `fonts/resolve.ts`:
+ *   - `VISOR_BRANDS_CDN` is the default CDN base (parallels `VISOR_FONTS_CDN`).
+ *   - `buildVisorBrandUrl()` constructs a CDN URL for a variant (Phase 2+).
+ *   - `source: local` resolves to a path under the consuming app's `public/`.
+ *   - `DEFAULT_VISOR_BRAND` is the Visor default brand stock themes fall back to.
+ */
+
+/** Default CDN base for brand assets (Phase 2+; unused while source is `local`). */
+declare const VISOR_BRANDS_CDN = "https://brands.visor.design";
+/**
+ * Local public/ path prefix for the Visor default brand. VI-469 produces the
+ * SVGs at this canonical location (`packages/docs/public/themes/visor/brand/`),
+ * served from the docs app's `public/` root as `/themes/visor/brand/...`.
+ */
+declare const VISOR_DEFAULT_BRAND_PATH = "/themes/visor/brand";
+/**
+ * The Visor default brand. Stock themes that omit a `brand` block resolve to
+ * this — they are not logo-less (D3). Declared as `source: local` so Phase 1
+ * resolves it to the bundled SVGs at `/themes/visor/brand/` (no CDN).
+ *
+ * Aspect ratios and clear-space are pinned per variant (Q6). These are the
+ * canonical Visor mark dimensions; per-theme `brand` blocks override any slot.
+ */
+declare const DEFAULT_VISOR_BRAND: VisorBrand;
+/**
+ * Build a visor-brands CDN URL for a brand variant (Phase 2+).
+ *
+ * Default pattern: `https://brands.visor.design/{org}/{slug}/{variant}[-dark].{format}`.
+ * When `cdnBase` is provided, that base replaces `VISOR_BRANDS_CDN`. When `org`
+ * is empty (the CDN base already encodes the namespace), the org segment is
+ * dropped: `{cdnBase}/{slug}/{variant}[-dark].{format}`.
+ *
+ * Mirrors `buildVisorFontUrl`. Content-hashing (Q5) is a Phase 2 concern and is
+ * intentionally omitted here.
+ */
+declare function buildVisorBrandUrl(org: string, slug: string, variant: string, mode: "light" | "dark", format: string, cdnBase?: string | null): string;
+/**
+ * Resolve a single brand slot to a `BrandResolution`.
+ *
+ * Resolution order (mirrors the fonts resolver):
+ *   1. `source: local` → public/ paths (Phase 1).
+ *   2. `source: visor-brands` → CDN URLs via `buildVisorBrandUrl` (Phase 2+).
+ *
+ * `org` / `source` / `cdnBase` fall back to the brand-block-wide defaults when
+ * the slot omits them.
+ */
+declare function resolveBrandSlot(variant: string, slot: BrandSlot, options: {
+    source: BrandSource;
+    org: string | null;
+    cdnBase?: string | null;
+}): BrandResolution;
+/** Resolve the brand-block-wide source default (slot-level `source` is not supported). */
+declare function resolveBrandSource(brand: VisorBrand): BrandSource;
+
+/**
+ * Theme brand pipeline — connects brand resolution to the .visor.yaml flow.
+ *
+ * Takes the `brand` block from a .visor.yaml file and produces:
+ *   - Resolved brand assets (local public/ paths or CDN URLs).
+ *   - Mode-scoped `--brand-{variant}` CSS custom properties, plus explicit
+ *     `--brand-{variant}-light` / `-dark` forced-mode aliases (Q1).
+ *   - Per-variant `--brand-{variant}-clear-space` / `-aspect-ratio` tokens (Q6).
+ *   - Warnings for assets needing manual setup.
+ *
+ * The emitted CSS is a raw declaration body (no @layer wrapper). Adapters wrap
+ * it in `@layer visor-brand` (ordered after `visor-semantic`).
+ */
+
+/**
+ * Resolve all brand assets for a theme's `brand` configuration.
+ *
+ * Main entry point for the brand pipeline — called during .visor.yaml import.
+ * When `brand` is omitted, falls back to the Visor default brand (D3) so stock
+ * themes are never logo-less.
+ *
+ * @param brand   The resolved `brand` block (or undefined → Visor default).
+ * @param options `scope` — optional scope selector (e.g. `.blackout-theme`)
+ *                that prefixes the emitted selectors for class-scoped adapters.
+ */
+declare function resolveThemeBrand(brand: VisorBrand | undefined, options?: {
+    scope?: string;
+}): ThemeBrandResult;
+
 /**
  * Import Pipeline
  *
@@ -501,6 +587,86 @@ var properties = {
 			}
 		}
 	},
+	brand: {
+		type: "object",
+		description: "Brand-asset declarations (VI-470). Per-slot logo/brandmark/wordmark/etc. entries resolved to asset URLs and emitted as mode-scoped --brand-* CSS variables in a dedicated visor-brand cascade layer. Omitted → the Visor default brand (stock themes are not logo-less).",
+		additionalProperties: false,
+		properties: {
+			org: {
+				type: "string",
+				description: "CDN namespace for brand assets. Required when source is \"visor-brands\" (unless cdn-overrides.visor-brands is set)."
+			},
+			source: {
+				type: "string",
+				"enum": [
+					"visor-brands",
+					"local"
+				],
+				description: "Where assets resolve from. Default: \"visor-brands\". Phase 1 supports \"local\" (resolves to public/ paths); CDN resolution lands later."
+			},
+			"cdn-overrides": {
+				type: "object",
+				description: "Per-source CDN base URL override. Only visor-brands is supported.",
+				additionalProperties: false,
+				properties: {
+					"visor-brands": {
+						type: "string",
+						minLength: 1,
+						description: "CDN base URL that replaces brands.visor.design for source: visor-brands slots."
+					}
+				}
+			},
+			logo: {
+				$ref: "#/$defs/brandSlot"
+			},
+			brandmark: {
+				$ref: "#/$defs/brandSlot"
+			},
+			wordmark: {
+				$ref: "#/$defs/brandSlot"
+			},
+			monochrome: {
+				$ref: "#/$defs/brandSlot"
+			},
+			favicon: {
+				$ref: "#/$defs/brandSlot"
+			},
+			animated: {
+				$ref: "#/$defs/brandSlot"
+			},
+			custom: {
+				type: "object",
+				description: "Operator-defined slots, addressed by key.",
+				additionalProperties: {
+					$ref: "#/$defs/brandSlot"
+				}
+			}
+		},
+		"if": {
+			properties: {
+				source: {
+					"const": "visor-brands"
+				}
+			},
+			required: [
+				"source"
+			]
+		},
+		then: {
+			anyOf: [
+				{
+					required: [
+						"org"
+					]
+				},
+				{
+					required: [
+						"cdn-overrides"
+					]
+				}
+			]
+		}
+	},
 	spacing: {
 		type: "object",
 		description: "Spacing configuration.",
@@ -667,6 +833,40 @@ var $defs = {
 			}
 		]
 	},
+	brandSlot: {
+		type: "object",
+		description: "A single brand-variant declaration. Resolves to light + dark asset URLs; clearSpace and aspectRatio are tokenized per variant (VI-470, Q6).",
+		additionalProperties: false,
+		properties: {
+			slug: {
+				type: "string",
+				description: "CDN/asset-set slug. Required when source is visor-brands (Phase 2+)."
+			},
+			formats: {
+				type: "array",
+				items: {
+					type: "string"
+				},
+				description: "Preferred asset formats, first wins (e.g. [\"svg\"], [\"svg\", \"png\"])."
+			},
+			light: {
+				type: "string",
+				description: "Explicit light-mode asset filename or public/-relative path (overrides the inferred name)."
+			},
+			dark: {
+				type: "string",
+				description: "Explicit dark-mode asset filename or public/-relative path (overrides the inferred name)."
+			},
+			clearSpace: {
+				type: "string",
+				description: "Tokenized safe-zone padding enforced by <Logo> (e.g. \"0.5rem\"). Emitted as --brand-{variant}-clear-space."
+			},
+			aspectRatio: {
+				type: "string",
+				description: "Tokenized locked aspect ratio (e.g. \"3 / 1\"); else derived from the SVG viewBox. Emitted as --brand-{variant}-aspect-ratio."
+			}
+		}
+	},
 	textSlotOverride: {
 		type: "object",
 		description: "Per-slot override for one Material TextTheme entry.",
@@ -1021,4 +1221,4 @@ declare function cleanFontValue(val: string): string;
  */
 declare function extractFromCSS(files: CSSFile[], name?: string): ExtractionResult;
 
-export { type CSSFile, ColorRole, type Confidence, type ExtractedToken, type ExtractionResult, FONT_WEIGHT_ALIASES, type FontCoverageError, type FontCoverageResult, FontDisplayStrategy, type FontFaceDeclaration, FontResolution, FontResolveOptions, FullShadeScale, GeneratedPrimitives, GoogleFontEntry, OKLCH, ParsedColor, RGB, ResolvedThemeConfig, SEMANTIC_MAP, SelectiveShadeScale, SemanticTokens, ShadeStep, TAILWIND_GRAY, ThemeData, ThemeFontResult, ThemeOutput, type ThemeValidationResult, VISOR_FONTS_CDN, type ValidationIssue, type ValidationSeverity, VisorThemeConfig, VisorTypography, applyOverrides, assignSemanticTokens, buildVisorFontUrl, clampToSrgb, cleanFontValue, compositeOverBackground, exportTheme, extractFromCSS, formatFontCoverageError, generateDarkCss, generateFullBundleCss, generateLightCss, generatePreloadLinks, generatePrimitives, generatePrimitivesCss, generateSemanticCss, generateShadeScale, generateStylesheetLinks, generateTheme, generateThemeData, generateThemeDataFromConfig, generateThemeFromConfig, getContrastRatio, googleFontsCatalog, hexToOklch, hexToRgb, isValidColor, isValidHex, isVisorThemeConfig, lookupFontWeightAlias, lookupGoogleFont, normalizeHex, oklchToHex, parseCSSDeclarations, parseColor, parseConfig, parseFontFaceDeclarations, parseHex, parseHsla, parseOklch, parseRgba, resolveConfig, resolveFont, resolveThemeFonts, rgbToHex, serializeColor, validate, validateConfig, validateFontCoverage, visorTheme_schema as visorThemeSchema };
+export { BrandResolution, BrandSlot, BrandSource, type CSSFile, ColorRole, type Confidence, DEFAULT_VISOR_BRAND, type ExtractedToken, type ExtractionResult, FONT_WEIGHT_ALIASES, type FontCoverageError, type FontCoverageResult, FontDisplayStrategy, type FontFaceDeclaration, FontResolution, FontResolveOptions, FullShadeScale, GeneratedPrimitives, GoogleFontEntry, OKLCH, ParsedColor, RGB, ResolvedThemeConfig, SEMANTIC_MAP, SelectiveShadeScale, SemanticTokens, ShadeStep, TAILWIND_GRAY, ThemeBrandResult, ThemeData, ThemeFontResult, ThemeOutput, type ThemeValidationResult, VISOR_BRANDS_CDN, VISOR_DEFAULT_BRAND_PATH, VISOR_FONTS_CDN, type ValidationIssue, type ValidationSeverity, VisorBrand, VisorThemeConfig, VisorTypography, applyOverrides, assignSemanticTokens, buildVisorBrandUrl, buildVisorFontUrl, clampToSrgb, cleanFontValue, compositeOverBackground, exportTheme, extractFromCSS, formatFontCoverageError, generateDarkCss, generateFullBundleCss, generateLightCss, generatePreloadLinks, generatePrimitives, generatePrimitivesCss, generateSemanticCss, generateShadeScale, generateStylesheetLinks, generateTheme, generateThemeData, generateThemeDataFromConfig, generateThemeFromConfig, getContrastRatio, googleFontsCatalog, hexToOklch, hexToRgb, isValidColor, isValidHex, isVisorThemeConfig, lookupFontWeightAlias, lookupGoogleFont, normalizeHex, oklchToHex, parseCSSDeclarations, parseColor, parseConfig, parseFontFaceDeclarations, parseHex, parseHsla, parseOklch, parseRgba, resolveBrandSlot, resolveBrandSource, resolveConfig, resolveFont, resolveThemeBrand, resolveThemeFonts, rgbToHex, serializeColor, validate, validateConfig, validateFontCoverage, visorTheme_schema as visorThemeSchema };

package/dist/index.js

@@ -1,8 +1,13 @@
 import {
+  BRAND_VARIANTS,
+  DEFAULT_VISOR_BRAND,
   FONT_WEIGHT_ALIASES,
   MATERIAL_TEXT_SLOTS,
   TAILWIND_GRAY,
+  VISOR_BRANDS_CDN,
+  VISOR_DEFAULT_BRAND_PATH,
   VISOR_FONTS_CDN,
+  buildVisorBrandUrl,
   buildVisorFontUrl,
   clampToSrgb,
   compositeOverBackground,
@@ -29,12 +34,15 @@ import {
   parseHsla,
   parseOklch,
   parseRgba,
+  resolveBrandSlot,
+  resolveBrandSource,
   resolveFont,
+  resolveThemeBrand,
   resolveThemeFonts,
   rgbToHex,
   rgbToOklch,
   serializeColor
-} from "./chunk-43TVIXUS.js";
+} from "./chunk-KFTTL3XP.js";
 
 // src/fonts/validate-coverage.ts
 var FONT_VAR_RE = /--font-(heading|display|body|sans|mono)\s*:\s*([^;]+);/g;
@@ -418,6 +426,55 @@ var visor_theme_schema_default = {
         }
       }
     },
+    brand: {
+      type: "object",
+      description: "Brand-asset declarations (VI-470). Per-slot logo/brandmark/wordmark/etc. entries resolved to asset URLs and emitted as mode-scoped --brand-* CSS variables in a dedicated visor-brand cascade layer. Omitted \u2192 the Visor default brand (stock themes are not logo-less).",
+      additionalProperties: false,
+      properties: {
+        org: {
+          type: "string",
+          description: 'CDN namespace for brand assets. Required when source is "visor-brands" (unless cdn-overrides.visor-brands is set).'
+        },
+        source: {
+          type: "string",
+          enum: ["visor-brands", "local"],
+          description: 'Where assets resolve from. Default: "visor-brands". Phase 1 supports "local" (resolves to public/ paths); CDN resolution lands later.'
+        },
+        "cdn-overrides": {
+          type: "object",
+          description: "Per-source CDN base URL override. Only visor-brands is supported.",
+          additionalProperties: false,
+          properties: {
+            "visor-brands": {
+              type: "string",
+              minLength: 1,
+              description: "CDN base URL that replaces brands.visor.design for source: visor-brands slots."
+            }
+          }
+        },
+        logo: { $ref: "#/$defs/brandSlot" },
+        brandmark: { $ref: "#/$defs/brandSlot" },
+        wordmark: { $ref: "#/$defs/brandSlot" },
+        monochrome: { $ref: "#/$defs/brandSlot" },
+        favicon: { $ref: "#/$defs/brandSlot" },
+        animated: { $ref: "#/$defs/brandSlot" },
+        custom: {
+          type: "object",
+          description: "Operator-defined slots, addressed by key.",
+          additionalProperties: { $ref: "#/$defs/brandSlot" }
+        }
+      },
+      if: {
+        properties: { source: { const: "visor-brands" } },
+        required: ["source"]
+      },
+      then: {
+        anyOf: [
+          { required: ["org"] },
+          { required: ["cdn-overrides"] }
+        ]
+      }
+    },
     spacing: {
       type: "object",
       description: "Spacing configuration.",
@@ -532,6 +589,38 @@ var visor_theme_schema_default = {
         { pattern: "^oklch\\(" }
       ]
     },
+    brandSlot: {
+      type: "object",
+      description: "A single brand-variant declaration. Resolves to light + dark asset URLs; clearSpace and aspectRatio are tokenized per variant (VI-470, Q6).",
+      additionalProperties: false,
+      properties: {
+        slug: {
+          type: "string",
+          description: "CDN/asset-set slug. Required when source is visor-brands (Phase 2+)."
+        },
+        formats: {
+          type: "array",
+          items: { type: "string" },
+          description: 'Preferred asset formats, first wins (e.g. ["svg"], ["svg", "png"]).'
+        },
+        light: {
+          type: "string",
+          description: "Explicit light-mode asset filename or public/-relative path (overrides the inferred name)."
+        },
+        dark: {
+          type: "string",
+          description: "Explicit dark-mode asset filename or public/-relative path (overrides the inferred name)."
+        },
+        clearSpace: {
+          type: "string",
+          description: 'Tokenized safe-zone padding enforced by <Logo> (e.g. "0.5rem"). Emitted as --brand-{variant}-clear-space.'
+        },
+        aspectRatio: {
+          type: "string",
+          description: 'Tokenized locked aspect ratio (e.g. "3 / 1"); else derived from the SVG viewBox. Emitted as --brand-{variant}-aspect-ratio.'
+        }
+      }
+    },
     textSlotOverride: {
       type: "object",
       description: "Per-slot override for one Material TextTheme entry.",
@@ -567,6 +656,7 @@ var KNOWN_TOP_LEVEL_KEYS = /* @__PURE__ */ new Set([
   "colors",
   "colors-dark",
   "typography",
+  "brand",
   "spacing",
   "radius",
   "shadows",
@@ -607,6 +697,22 @@ var KNOWN_SHADOW_KEYS = /* @__PURE__ */ new Set(["xs", "sm", "md", "lg", "xl"]);
 var KNOWN_STROKE_WIDTH_KEYS = /* @__PURE__ */ new Set(["thin", "regular", "medium", "thick"]);
 var KNOWN_MOTION_KEYS = /* @__PURE__ */ new Set(["duration-fast", "duration-normal", "duration-slow", "easing", "easing-overshoot"]);
 var KNOWN_OVERRIDES_KEYS = /* @__PURE__ */ new Set(["light", "dark"]);
+var KNOWN_BRAND_KEYS = /* @__PURE__ */ new Set([
+  "org",
+  "source",
+  "cdn-overrides",
+  "logo",
+  "brandmark",
+  "wordmark",
+  "monochrome",
+  "favicon",
+  "animated",
+  "custom"
+]);
+var KNOWN_BRAND_STANDARD_SLOTS = ["logo", "brandmark", "wordmark", "monochrome", "favicon", "animated"];
+var KNOWN_BRAND_SLOT_KEYS = /* @__PURE__ */ new Set(["slug", "formats", "light", "dark", "clearSpace", "aspectRatio"]);
+var KNOWN_BRAND_SOURCES = /* @__PURE__ */ new Set(["visor-brands", "local"]);
+var KNOWN_BRAND_CDN_OVERRIDE_KEYS = /* @__PURE__ */ new Set(["visor-brands"]);
 function checkUnknownKeys(obj, errors) {
   for (const key of Object.keys(obj)) {
     if (!KNOWN_TOP_LEVEL_KEYS.has(key)) {
@@ -702,6 +808,46 @@ function checkUnknownKeys(obj, errors) {
       }
     }
   }
+  if (typeof obj.brand === "object" && obj.brand !== null) {
+    const brand = obj.brand;
+    for (const key of Object.keys(brand)) {
+      if (!KNOWN_BRAND_KEYS.has(key)) {
+        errors.push(`Unknown key 'brand.${key}'. Valid keys: ${[...KNOWN_BRAND_KEYS].join(", ")}`);
+      }
+    }
+    if (typeof brand["cdn-overrides"] === "object" && brand["cdn-overrides"] !== null) {
+      for (const key of Object.keys(brand["cdn-overrides"])) {
+        if (!KNOWN_BRAND_CDN_OVERRIDE_KEYS.has(key)) {
+          errors.push(`Unknown key 'brand.cdn-overrides.${key}'. Valid keys: ${[...KNOWN_BRAND_CDN_OVERRIDE_KEYS].join(", ")}`);
+        }
+      }
+    }
+    for (const slot of KNOWN_BRAND_STANDARD_SLOTS) {
+      const slotObj = brand[slot];
+      if (typeof slotObj === "object" && slotObj !== null) {
+        for (const key of Object.keys(slotObj)) {
+          if (!KNOWN_BRAND_SLOT_KEYS.has(key)) {
+            errors.push(`Unknown key 'brand.${slot}.${key}'. Valid keys: ${[...KNOWN_BRAND_SLOT_KEYS].join(", ")}`);
+          }
+        }
+      }
+    }
+    if (typeof brand.custom === "object" && brand.custom !== null) {
+      const custom = brand.custom;
+      for (const slotName of Object.keys(custom)) {
+        const slotObj = custom[slotName];
+        if (typeof slotObj !== "object" || slotObj === null) {
+          errors.push(`'brand.custom.${slotName}' must be an object with optional slug/formats/light/dark/clearSpace/aspectRatio fields`);
+          continue;
+        }
+        for (const key of Object.keys(slotObj)) {
+          if (!KNOWN_BRAND_SLOT_KEYS.has(key)) {
+            errors.push(`Unknown key 'brand.custom.${slotName}.${key}'. Valid keys: ${[...KNOWN_BRAND_SLOT_KEYS].join(", ")}`);
+          }
+        }
+      }
+    }
+  }
   if (typeof obj.spacing === "object" && obj.spacing !== null) {
     for (const key of Object.keys(obj.spacing)) {
       if (!KNOWN_SPACING_KEYS.has(key)) {
@@ -857,6 +1003,60 @@ function validateConfig(config) {
       }
     }
   }
+  if (obj.brand !== void 0) {
+    if (typeof obj.brand !== "object" || obj.brand === null) {
+      errors.push("'brand' must be an object");
+    } else {
+      const brand = obj.brand;
+      if (brand.source !== void 0 && !KNOWN_BRAND_SOURCES.has(brand.source)) {
+        errors.push(`'brand.source' must be one of: ${[...KNOWN_BRAND_SOURCES].join(", ")}`);
+      }
+      const brandCdn = brand["cdn-overrides"];
+      const visorBrandsOverride = brandCdn?.["visor-brands"];
+      if (visorBrandsOverride !== void 0 && typeof visorBrandsOverride !== "string") {
+        errors.push("'brand.cdn-overrides.visor-brands' must be a string URL");
+      }
+      if (typeof visorBrandsOverride === "string" && visorBrandsOverride.length === 0) {
+        errors.push("'brand.cdn-overrides.visor-brands' must not be empty");
+      }
+      const orgOptional = typeof visorBrandsOverride === "string" && visorBrandsOverride.length > 0;
+      if (brand.source === "visor-brands" && !orgOptional && !brand.org) {
+        errors.push("'brand.org' is required when brand.source is 'visor-brands' (unless brand.cdn-overrides.visor-brands is set)");
+      }
+      const allSlots = [];
+      for (const slot of KNOWN_BRAND_STANDARD_SLOTS) {
+        if (typeof brand[slot] === "object" && brand[slot] !== null) {
+          allSlots.push(brand[slot]);
+        }
+      }
+      if (typeof brand.custom === "object" && brand.custom !== null) {
+        for (const slot of Object.values(brand.custom)) {
+          if (typeof slot === "object" && slot !== null) allSlots.push(slot);
+        }
+      }
+      for (const slot of allSlots) {
+        if (slot.formats !== void 0) {
+          if (!Array.isArray(slot.formats) || !slot.formats.every((f) => typeof f === "string")) {
+            errors.push(`'brand.<slot>.formats' must be an array of format strings (e.g., ["svg", "png"])`);
+          }
+        }
+      }
+      if (typeof brand.animated === "object" && brand.animated !== null) {
+        const animated = brand.animated;
+        if (Array.isArray(animated.formats) && !animated.formats.every(
+          (f) => typeof f === "string" && f.toLowerCase() === "svg"
+        )) {
+          errors.push("'brand.animated.formats' must be SVG-only (the animated slot accepts self-contained animated SVGs only)");
+        }
+        for (const mode of ["light", "dark"]) {
+          const p = animated[mode];
+          if (typeof p === "string" && !p.toLowerCase().endsWith(".svg")) {
+            errors.push(`'brand.animated.${mode}' must be an .svg path (the animated slot is SVG-only)`);
+          }
+        }
+      }
+    }
+  }
   if (obj.overrides !== void 0) {
     if (typeof obj.overrides !== "object" || obj.overrides === null) {
       errors.push("'overrides' must be an object");
@@ -917,6 +1117,23 @@ var DEFAULTS = {
     easing: "cubic-bezier(0.4, 0, 0.2, 1)"
   }
 };
+function resolveBrand(brand) {
+  if (!brand) return DEFAULT_VISOR_BRAND;
+  return {
+    org: brand.org ?? DEFAULT_VISOR_BRAND.org,
+    source: brand.source ?? DEFAULT_VISOR_BRAND.source,
+    ...brand["cdn-overrides"] && { "cdn-overrides": brand["cdn-overrides"] },
+    logo: brand.logo ?? DEFAULT_VISOR_BRAND.logo,
+    brandmark: brand.brandmark ?? DEFAULT_VISOR_BRAND.brandmark,
+    wordmark: brand.wordmark ?? DEFAULT_VISOR_BRAND.wordmark,
+    monochrome: brand.monochrome ?? DEFAULT_VISOR_BRAND.monochrome,
+    favicon: brand.favicon ?? DEFAULT_VISOR_BRAND.favicon,
+    // animated is optional with no Visor default (D2): pass through only when a
+    // theme declares it, so undeclared themes emit no --brand-animated.
+    ...brand.animated && { animated: brand.animated },
+    ...brand.custom && { custom: brand.custom }
+  };
+}
 function resolveConfig(config) {
   const colors = config.colors;
   const originalColors = {};
@@ -997,6 +1214,7 @@ function resolveConfig(config) {
       },
       slots: config.typography?.slots ?? {}
     },
+    brand: resolveBrand(config.brand),
     spacing: {
       base: config.spacing?.base ?? DEFAULTS.spacing.base
     },
@@ -1208,7 +1426,7 @@ var SEMANTIC_SURFACE_MAP = {
   // VI-478: status soft tints (BL-193) — alpha overlays, semantically distinct
   // from the OPAQUE `surface-{status}-subtle` above (do NOT alias them together).
   // Default to a color-mix of the status color so they track the theme; themes
-  // pin exact values via overrides (blacklight-underground: success @10%,
+  // pin exact values via overrides (blacklight-pro: success @10%,
   // warning/error @12%).
   "success-soft": {
     light: { constant: "color-mix(in srgb, var(--color-success-500) 10%, transparent)" },
@@ -1305,7 +1523,7 @@ var SEMANTIC_INTERACTIVE_MAP = {
   // VI-478: brand-derived alpha-overlay helpers (BL-193). `soft`/`glow` are
   // alpha overlays that track the theme's primary via color-mix (distinct from
   // any opaque surface); `strong` is a solid lightened-brand emphasis color.
-  // Themes pin exact values via overrides — e.g. blacklight-underground sets
+  // Themes pin exact values via overrides — e.g. blacklight-pro sets
   // soft @12% / glow @32% / strong #FFD050.
   "primary-soft": {
     light: { constant: "color-mix(in srgb, var(--color-primary-500) 12%, transparent)" },
@@ -2997,12 +3215,17 @@ function extractFromCSS(files, name = "extracted-theme") {
   return { config, tokens, unmapped, warnings };
 }
 export {
+  BRAND_VARIANTS,
+  DEFAULT_VISOR_BRAND,
   FONT_WEIGHT_ALIASES,
   SEMANTIC_MAP,
   TAILWIND_GRAY,
+  VISOR_BRANDS_CDN,
+  VISOR_DEFAULT_BRAND_PATH,
   VISOR_FONTS_CDN,
   applyOverrides,
   assignSemanticTokens,
+  buildVisorBrandUrl,
   buildVisorFontUrl,
   clampToSrgb,
   cleanFontValue,
@@ -3042,8 +3265,11 @@ export {
   parseHsla,
   parseOklch,
   parseRgba,
+  resolveBrandSlot,
+  resolveBrandSource,
   resolveConfig,
   resolveFont,
+  resolveThemeBrand,
   resolveThemeFonts,
   rgbToHex,
   serializeColor,

package/dist/{types-Dwc1V0Nc.d.ts → types-CSO2avFQ.d.ts}

@@ -119,6 +119,111 @@ interface GoogleFontEntry {
     category: string;
 }
 
+/**
+ * Brand-asset resolution types for the Visor theme engine.
+ *
+ * Models the fonts subsystem (`packages/theme-engine/src/fonts/`): a per-theme
+ * `brand` block declares logo/brandmark/wordmark/etc. slots, the resolver maps
+ * each to loadable asset URLs (Phase 1: local public/ paths; Phase 2+: CDN),
+ * and the pipeline emits `--brand-{variant}` CSS custom properties into a
+ * dedicated `visor-brand` cascade layer.
+ *
+ * Phase 1 (VI-470) supports `source: local` only — no CDN. The `visor-brands`
+ * source value is reserved in the type union so the schema stays
+ * forward-compatible (parallels the fonts `visor-fonts` source).
+ */
+/** Where a brand asset is loaded from. Phase 1 resolves only `local`. */
+type BrandSource = "visor-brands" | "local";
+/**
+ * Standard brand variant slots. A fixed set covers the common lockups; custom
+ * operator-defined slots are addressed by key through the `custom` map.
+ */
+type BrandVariant = "logo" | "brandmark" | "wordmark" | "monochrome" | "favicon" | "animated";
+/** Ordered list of the standard brand variant slots. */
+declare const BRAND_VARIANTS: readonly BrandVariant[];
+/**
+ * A single brand-slot declaration in `.visor.yaml`. Each slot may declare a
+ * `slug` (CDN namespace, Phase 2+), an explicit per-mode `light`/`dark`
+ * filename or path, plus the tokenized `clearSpace` (safe-zone) and
+ * `aspectRatio` enforced by `<Logo>` (Q6).
+ */
+interface BrandSlot {
+    /** CDN/asset-set slug. Required when `source: visor-brands` (Phase 2+). */
+    slug?: string;
+    /** Preferred asset formats, first wins (e.g. `["svg"]`, `["svg", "png"]`). */
+    formats?: string[];
+    /** Explicit light-mode asset filename or path (overrides the inferred name). */
+    light?: string;
+    /** Explicit dark-mode asset filename or path (overrides the inferred name). */
+    dark?: string;
+    /** Tokenized safe-zone padding enforced by `<Logo>` (Q6), e.g. "0.5rem". */
+    clearSpace?: string;
+    /** Tokenized locked aspect ratio (Q6), e.g. "3 / 1"; else derived from viewBox. */
+    aspectRatio?: string;
+}
+/**
+ * The `brand` block from a `.visor.yaml` file. Structured like `typography`:
+ * shared `org`/`source`/`cdn-overrides` defaults plus the standard slots and
+ * an optional `custom` map.
+ */
+interface VisorBrand {
+    /** CDN namespace; required when `source: visor-brands` unless cdn-overrides is set. */
+    org?: string;
+    /** Where assets resolve from. Phase 1 supports `local` only. Default: `visor-brands`. */
+    source?: BrandSource;
+    /** Per-source CDN base URL overrides (Phase 2+). Only `visor-brands` is supported. */
+    "cdn-overrides"?: {
+        "visor-brands"?: string;
+    };
+    /** Full lockup. */
+    logo?: BrandSlot;
+    /** Symbol only. */
+    brandmark?: BrandSlot;
+    /** Type only. */
+    wordmark?: BrandSlot;
+    /** Single-color mark (tinted via CSS mask-image + currentColor). */
+    monochrome?: BrandSlot;
+    /** Favicon source. */
+    favicon?: BrandSlot;
+    /**
+     * Animated lockup. Optional and SVG-only (D2/D3): the asset must be a
+     * self-contained animated SVG (inlined `<style>`/@keyframes or SMIL) so it
+     * animates inside `<img>`. Stock themes omit this — absent → no
+     * `--brand-animated` emitted. Reduced-motion consumers fall back to `logo`.
+     */
+    animated?: BrandSlot;
+    /** Operator-defined slots, addressed by key. */
+    custom?: Record<string, BrandSlot>;
+}
+/** A single resolved brand variant — light + dark asset URLs plus its tokens. */
+interface BrandResolution {
+    /** The variant slot this resolution covers ("logo", "brandmark", or a custom key). */
+    variant: string;
+    /** Where this asset comes from. */
+    source: BrandSource;
+    /** Resolved light-mode asset URL/path. */
+    light: string;
+    /** Resolved dark-mode asset URL/path. */
+    dark: string;
+    /** Tokenized safe-zone padding (null when not declared). */
+    clearSpace: string | null;
+    /** Tokenized locked aspect ratio (null when not declared). */
+    aspectRatio: string | null;
+    /** Human-readable guidance for assets needing manual setup (e.g. local files). */
+    guidance: string | null;
+}
+/** Result of resolving all brand assets for a theme. */
+interface ThemeBrandResult {
+    /** Resolved standard-slot variants in declaration order. */
+    variants: BrandResolution[];
+    /** Resolved custom-slot variants in declaration order. */
+    custom: BrandResolution[];
+    /** Mode-scoped `--brand-*` CSS custom property declarations (no @layer wrapper). */
+    css: string;
+    /** Warnings for assets needing manual setup. */
+    warnings: string[];
+}
+
 /**
  * Types for the Visor Theme Engine
  *
@@ -240,6 +345,13 @@ interface VisorThemeConfig {
          */
         slots?: Partial<Record<MaterialTextSlot, TextSlotOverride>>;
     };
+    /**
+     * Brand-asset declarations (VI-470). Structured like `typography` — per-slot
+     * logo/brandmark/wordmark/etc. entries resolved to asset URLs and emitted as
+     * mode-scoped `--brand-*` CSS vars in a dedicated `visor-brand` cascade layer.
+     * Omitted → the Visor default brand (stock themes are not logo-less).
+     */
+    brand?: VisorBrand;
     spacing?: {
         base?: number;
     };
@@ -358,6 +470,11 @@ interface ResolvedThemeConfig {
          */
         slots: Partial<Record<MaterialTextSlot, TextSlotOverride>>;
     };
+    /**
+     * Resolved brand block (VI-470). Always present — falls back to the Visor
+     * default brand when the source config omits `brand` (D3).
+     */
+    brand: VisorBrand;
     spacing: {
         base: number;
     };
@@ -434,4 +551,4 @@ interface ThemeData {
     output: ThemeOutput;
 }
 
-export type { ColorRole as C, FontResolveOptions as F, GoogleFontEntry as G, OKLCH as O, ParsedColor as P, ResolvedThemeConfig as R, SelectiveShadeScale as S, ThemeFontResult as T, VisorTypography as V, FontResolution as a, FontDisplayStrategy as b, GeneratedPrimitives as c, ThemeOutput as d, ThemeData as e, VisorThemeConfig as f, FullShadeScale as g, RGB as h, SemanticTokens as i, ShadeStep as j, ColorFormat as k, FontSource as l, RGBA as m, SemanticTokenValue as n };
+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 };

package/package.json

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

@@ -222,6 +222,55 @@
         }
       }
     },
+    "brand": {
+      "type": "object",
+      "description": "Brand-asset declarations (VI-470). Per-slot logo/brandmark/wordmark/etc. entries resolved to asset URLs and emitted as mode-scoped --brand-* CSS variables in a dedicated visor-brand cascade layer. Omitted → the Visor default brand (stock themes are not logo-less).",
+      "additionalProperties": false,
+      "properties": {
+        "org": {
+          "type": "string",
+          "description": "CDN namespace for brand assets. Required when source is \"visor-brands\" (unless cdn-overrides.visor-brands is set)."
+        },
+        "source": {
+          "type": "string",
+          "enum": ["visor-brands", "local"],
+          "description": "Where assets resolve from. Default: \"visor-brands\". Phase 1 supports \"local\" (resolves to public/ paths); CDN resolution lands later."
+        },
+        "cdn-overrides": {
+          "type": "object",
+          "description": "Per-source CDN base URL override. Only visor-brands is supported.",
+          "additionalProperties": false,
+          "properties": {
+            "visor-brands": {
+              "type": "string",
+              "minLength": 1,
+              "description": "CDN base URL that replaces brands.visor.design for source: visor-brands slots."
+            }
+          }
+        },
+        "logo": { "$ref": "#/$defs/brandSlot" },
+        "brandmark": { "$ref": "#/$defs/brandSlot" },
+        "wordmark": { "$ref": "#/$defs/brandSlot" },
+        "monochrome": { "$ref": "#/$defs/brandSlot" },
+        "favicon": { "$ref": "#/$defs/brandSlot" },
+        "animated": { "$ref": "#/$defs/brandSlot" },
+        "custom": {
+          "type": "object",
+          "description": "Operator-defined slots, addressed by key.",
+          "additionalProperties": { "$ref": "#/$defs/brandSlot" }
+        }
+      },
+      "if": {
+        "properties": { "source": { "const": "visor-brands" } },
+        "required": ["source"]
+      },
+      "then": {
+        "anyOf": [
+          { "required": ["org"] },
+          { "required": ["cdn-overrides"] }
+        ]
+      }
+    },
     "spacing": {
       "type": "object",
       "description": "Spacing configuration.",
@@ -336,6 +385,38 @@
         { "pattern": "^oklch\\(" }
       ]
     },
+    "brandSlot": {
+      "type": "object",
+      "description": "A single brand-variant declaration. Resolves to light + dark asset URLs; clearSpace and aspectRatio are tokenized per variant (VI-470, Q6).",
+      "additionalProperties": false,
+      "properties": {
+        "slug": {
+          "type": "string",
+          "description": "CDN/asset-set slug. Required when source is visor-brands (Phase 2+)."
+        },
+        "formats": {
+          "type": "array",
+          "items": { "type": "string" },
+          "description": "Preferred asset formats, first wins (e.g. [\"svg\"], [\"svg\", \"png\"])."
+        },
+        "light": {
+          "type": "string",
+          "description": "Explicit light-mode asset filename or public/-relative path (overrides the inferred name)."
+        },
+        "dark": {
+          "type": "string",
+          "description": "Explicit dark-mode asset filename or public/-relative path (overrides the inferred name)."
+        },
+        "clearSpace": {
+          "type": "string",
+          "description": "Tokenized safe-zone padding enforced by <Logo> (e.g. \"0.5rem\"). Emitted as --brand-{variant}-clear-space."
+        },
+        "aspectRatio": {
+          "type": "string",
+          "description": "Tokenized locked aspect ratio (e.g. \"3 / 1\"); else derived from the SVG viewBox. Emitted as --brand-{variant}-aspect-ratio."
+        }
+      }
+    },
     "textSlotOverride": {
       "type": "object",
       "description": "Per-slot override for one Material TextTheme entry.",