brand-intent 0.7.0 → 0.9.0

package/README.md

@@ -44,10 +44,10 @@ npx brand-intent init
 
 Two skills are now installed in your AI agent.
 
-- **`/brand-intent`** authors, validates, and generates on-brand content from your DSL files.
-- **`/brief`** exports a portable `{brand-id}-brief.md`. Use it to hand the brand to a tool that doesn't read Brand Intent directly, like a Claude design project, another LLM, or a collaborator.
+- **`/brand-intent`** authors, validates, and generates on-brand content from your Brand Intent files.
+- **`/brief`** exports a portable `{brand-id}-brief.md`. Use it to hand the brand to a tool that doesn't read Brand Intent directly, like a Claude Design project, another LLM, or a collaborator.
 
-Edit your DSL files whenever strategy or expression evolves. Regenerate briefs after any change.
+Edit your Brand Intent files whenever strategy or expression evolves. Regenerate briefs after any change.
 
 ## Documentation
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "brand-intent",
-  "version": "0.7.0",
+  "version": "0.9.0",
   "description": "An open file format specification for making brand intent machine-readable.",
   "author": "Christophe Stoll <christophe@stoll.studio>",
   "license": "MIT",
@@ -33,7 +33,11 @@
     "design-system"
   ],
   "scripts": {
-    "release": "./scripts/release.sh"
+    "release": "./scripts/release.sh",
+    "test": "tsx tests/brandParser.test.ts && tsx tests/identityParser.test.ts && tsx tests/realBrands.test.ts"
+  },
+  "devDependencies": {
+    "tsx": "^4.19.0"
   },
   "files": [
     "cli/",

package/parser/brandParser.ts

@@ -6,6 +6,19 @@
  * handles expression-layer primitives only (colors, typography, dividers, assets, badge styles).
  */
 
+import type {
+  BrandColorGroup,
+  BrandColorEntry,
+  ColorMode,
+  PaletteStrategy,
+  Adherence,
+  AdherenceTolerances,
+  ColorBounds,
+  StateColors,
+  GroupKey,
+  NeutralRole,
+} from './types';
+
 // ── Parsed type ────────────────────────────────────────────────────────────────
 
 export interface ParsedBrand {
@@ -31,10 +44,26 @@ export interface ParsedBrand {
   favicon?: string;
   /** Path to OG image asset (relative to /public), used for social sharing previews */
   ogImage?: string;
-  /** Core brand color primitives: name → hex (e.g. primary, secondary, accent1, accent2, white) */
+  /** Core brand color primitives: name → hex (e.g. primary, secondary, accent1, accent2, white).
+   *  Always present when any colors are declared — grouped-syntax brands get a flat projection
+   *  generated from all entries, so legacy consumers keep working unchanged. */
   brandColors?: Record<string, string>;
   /** Structured print specs per brand color: name → {pantone?, hks?, cmyk?} */
   brandColorPrint?: Record<string, BrandColorPrintSpec>;
+  /** Grouped-syntax representation (v0.8.0+). Present only when the `brand-colors` block uses the grouped form. */
+  colorGroups?: BrandColorGroup[];
+  /** Per-brand fixed state colors (problem/warning/success/info/inactive). */
+  stateColors?: StateColors;
+  /** Bounds for guided derivation (luminance + saturation floor). */
+  colorBounds?: ColorBounds;
+  /** Color resolution mode. Defaults behave as `static` when absent. */
+  colorMode?: ColorMode;
+  /** Palette strategy default for Path A (guided shuffle). Optional. */
+  colorStrategy?: PaletteStrategy;
+  /** Adherence level for guided derivation. Optional — engine-side default per level. */
+  colorAdherence?: Adherence;
+  /** Per-brand tolerance overrides for the declared adherence level. */
+  colorAdherenceOverrides?: AdherenceTolerances;
   /** Inline themes: theme name → slot name → resolved hex color (only when tokensSource === 'inline') */
   themes?: Record<string, Record<string, string>>;
   /** Print annotations from inline # comments: slot name → annotation text */
@@ -62,6 +91,12 @@ export interface ParsedAssetDef {
   lottieSrc?: string;
   animated?: boolean;
   loop?: boolean;
+  /** Path to a glTF/GLB 3D model. When present, the asset renders as a live 3D object; `src` remains the 2D fallback. */
+  gltfSrc?: string;
+  /** Procedural generator id (e.g. "mobius", "spiral", "ribbon"). Renders as live geometry; `src` is the 2D fallback. */
+  generator?: string;
+  /** Default parameters for the procedural generator, keyed by param name. Declared via the indented `generator-params` sub-block. */
+  generatorParams?: Record<string, number>;
 }
 
 export interface ParsedBadgeStyle {
@@ -131,6 +166,13 @@ export interface ParsedDividerDef {
 
 // ── Helpers ────────────────────────────────────────────────────────────────────
 
+const GROUP_KEYWORDS = new Set<string>(['primary', 'secondary', 'accent', 'neutral']);
+const NEUTRAL_ROLES = new Set<NeutralRole>(['light', 'subtle', 'mid', 'muted', 'dark']);
+const STATE_KEYS = new Set<string>(['problem', 'warning', 'success', 'info', 'inactive']);
+const VALID_COLOR_MODES = new Set<ColorMode>(['static', 'dynamic', 'guided']);
+const VALID_STRATEGIES = new Set<PaletteStrategy>(['monochrome', 'duotone', 'tricolor', 'spectrum']);
+const VALID_ADHERENCES = new Set<Adherence>(['strict', 'on-brand', 'flexible']);
+
 /**
  * Expand a 3-digit hex to 6-digit. Pass-through for 6 or 8-digit.
  * Returns null for invalid input.
@@ -244,7 +286,7 @@ export function parseBrandFile(content: string, fileName: string): ParsedBrand {
     tokensSource: 'figma',
   };
 
-  type ActiveBlock = 'none' | 'brand-colors' | 'theme' | 'spacing' | 'divider' | 'typography' | 'font' | 'logo' | 'photo' | 'video' | 'illustration' | 'label' | 'cta';
+  type ActiveBlock = 'none' | 'brand-colors' | 'state-colors' | 'color-bounds' | 'color-adherence' | 'theme' | 'spacing' | 'divider' | 'typography' | 'font' | 'logo' | 'photo' | 'video' | 'illustration' | 'label' | 'cta';
   let activeBlock: ActiveBlock = 'none';
   let currentThemeName = '';
   let currentDividerName = '';
@@ -253,6 +295,18 @@ export function parseBrandFile(content: string, fileName: string): ParsedBrand {
   const brandColors: Record<string, string> = {};
   const brandColorPrint: Record<string, BrandColorPrintSpec> = {};
   let currentBrandColorName = '';
+
+  // Grouped brand-colors state (v0.8.0+).
+  // Shape is detected lazily: when the first non-blank indented line inside `brand-colors`
+  // is a bare group keyword, the block switches to grouped mode. Otherwise it stays flat.
+  type GroupedShape = 'unknown' | 'flat' | 'grouped';
+  let brandColorsShape: GroupedShape = 'unknown';
+  const colorGroups: BrandColorGroup[] = [];
+  let currentGroup: BrandColorGroup | null = null;
+  let currentGroupedEntry: BrandColorEntry | null = null;
+  const stateColorsRaw: Record<string, string> = {};
+  const colorBoundsRaw: Record<string, string> = {};
+  const adherenceOverridesRaw: Record<string, string> = {};
   const themes: Record<string, Record<string, string>> = {};
   const themeDescriptions: Record<string, string> = {};
   const spacingRaw: Record<string, string> = {};
@@ -264,6 +318,7 @@ export function parseBrandFile(content: string, fileName: string): ParsedBrand {
   const videosRaw: Array<{ id: string; props: Record<string, string> }> = [];
   const illustrationsRaw: Array<{ id: string; props: Record<string, string> }> = [];
   let currentAssetId = '';
+  let currentSubBlock: string | null = null;
   const labelRaw: Record<string, string> = {};
   const ctaRaw: Record<string, string> = {};
 
@@ -282,7 +337,123 @@ export function parseBrandFile(content: string, fileName: string): ParsedBrand {
     if (isIndented) {
       if (activeBlock === 'brand-colors') {
         const trimmed = raw.trimStart();
+        if (trimmed === '') continue;
         const indentLen = raw.length - trimmed.length;
+
+        // Shape detection: first non-blank indented line decides.
+        // Grouped = bare group keyword (`primary`/`secondary`/`accent`/`neutral`) at 2-space indent.
+        // Flat    = `key: value` at 2-space indent.
+        if (brandColorsShape === 'unknown') {
+          if (GROUP_KEYWORDS.has(trimmed) && indentLen <= 2) {
+            brandColorsShape = 'grouped';
+          } else {
+            brandColorsShape = 'flat';
+          }
+        }
+
+        if (brandColorsShape === 'grouped') {
+          // ── Grouped shape ────────────────────────────────────────────────
+          const groupKwMatch = GROUP_KEYWORDS.has(trimmed) && indentLen <= 2;
+          if (groupKwMatch) {
+            const key = trimmed as GroupKey;
+            if (colorGroups.some(g => g.key === key)) {
+              throw new Error(`${fileName}:${lineNum}: duplicate color group "${key}"`);
+            }
+            currentGroup = { key, entries: [] };
+            colorGroups.push(currentGroup);
+            currentGroupedEntry = null;
+            continue;
+          }
+          if (!currentGroup) {
+            throw new Error(
+              `${fileName}:${lineNum}: grouped brand-colors entries must appear inside a group block (primary/secondary/accent/neutral)`,
+            );
+          }
+          // Group-level properties at 4-space indent OR color-entry header / sub-properties.
+          // We distinguish by: entry header = starts with `#` or `$`.
+          if (trimmed.startsWith('#') || trimmed.startsWith('$')) {
+            // New entry. Header forms:
+            //   "#HEX  Display Name"
+            //   "$group.role"
+            if (trimmed.startsWith('#')) {
+              // Split header: "#HEX  Name" — hex then whitespace then name
+              const headerMatch = trimmed.match(/^(#[0-9a-fA-F]{3,8})(?:\s+(.+))?$/);
+              if (!headerMatch) {
+                throw new Error(
+                  `${fileName}:${lineNum}: expected "#HEX  Name" entry header, got "${trimmed}"`,
+                );
+              }
+              const hex = normalizeHex(headerMatch[1]);
+              if (!hex) {
+                throw new Error(
+                  `${fileName}:${lineNum}: invalid hex "${headerMatch[1]}"`,
+                );
+              }
+              const name = (headerMatch[2] ?? '').trim();
+              if (!name) {
+                throw new Error(
+                  `${fileName}:${lineNum}: color entry needs a display name after the hex`,
+                );
+              }
+              currentGroupedEntry = { hex, name };
+              currentGroup.entries.push(currentGroupedEntry);
+            } else {
+              // $group.role reference — resolved in finalisation pass.
+              const refMatch = trimmed.match(/^\$([a-z]+)\.([a-z-]+)$/i);
+              if (!refMatch) {
+                throw new Error(
+                  `${fileName}:${lineNum}: expected "$group.role" reference, got "${trimmed}"`,
+                );
+              }
+              currentGroupedEntry = {
+                hex: '',
+                name: '',
+                referencedFrom: `${refMatch[1]}.${refMatch[2]}`,
+              };
+              currentGroup.entries.push(currentGroupedEntry);
+            }
+            continue;
+          }
+          // `key: value` line — either group property (indent ≤ 4) or entry sub-property.
+          const colonIdx = trimmed.indexOf(':');
+          if (colonIdx === -1) continue;
+          const key = trimmed.slice(0, colonIdx).trim();
+          const value = trimmed.slice(colonIdx + 1).trim();
+          // Group property lives at indent 4 and only appears before the first entry.
+          if (indentLen <= 4 && !currentGroupedEntry) {
+            if (key === 'meaning') {
+              currentGroup.meaning = value;
+            } else if (key === 'distribution') {
+              if (currentGroup.key === 'neutral') {
+                throw new Error(
+                  `${fileName}:${lineNum}: neutral group cannot declare distribution — it's the scale, not a selection target`,
+                );
+              }
+              const pct = parseFloat(value.replace(/%$/, ''));
+              if (isNaN(pct)) {
+                throw new Error(
+                  `${fileName}:${lineNum}: distribution "${value}" is not a number`,
+                );
+              }
+              currentGroup.distribution = pct;
+            }
+            continue;
+          }
+          // Entry sub-property.
+          if (!currentGroupedEntry) continue;
+          if (key === 'role') {
+            currentGroupedEntry.role = value;
+            if (value === 'default') currentGroupedEntry.isDefault = true;
+          } else if (key === 'meaning') {
+            currentGroupedEntry.meaning = value;
+          } else if (key === 'pantone' || key === 'hks' || key === 'cmyk') {
+            if (!currentGroupedEntry.print) currentGroupedEntry.print = {};
+            currentGroupedEntry.print[key] = value;
+          }
+          continue;
+        }
+
+        // ── Flat shape (legacy) ────────────────────────────────────────────
         const colonIdx = trimmed.indexOf(':');
         if (colonIdx !== -1) {
           const key = trimmed.slice(0, colonIdx).trim();
@@ -308,6 +479,36 @@ export function parseBrandFile(content: string, fileName: string): ParsedBrand {
         }
         continue;
       }
+      if (activeBlock === 'state-colors') {
+        const trimmed = raw.trimStart();
+        const colonIdx = trimmed.indexOf(':');
+        if (colonIdx !== -1) {
+          const key = trimmed.slice(0, colonIdx).trim();
+          const value = trimmed.slice(colonIdx + 1).trim();
+          stateColorsRaw[key] = value;
+        }
+        continue;
+      }
+      if (activeBlock === 'color-bounds') {
+        const trimmed = raw.trimStart();
+        const colonIdx = trimmed.indexOf(':');
+        if (colonIdx !== -1) {
+          const key = trimmed.slice(0, colonIdx).trim();
+          const value = trimmed.slice(colonIdx + 1).trim();
+          colorBoundsRaw[key] = value;
+        }
+        continue;
+      }
+      if (activeBlock === 'color-adherence') {
+        const trimmed = raw.trimStart();
+        const colonIdx = trimmed.indexOf(':');
+        if (colonIdx !== -1) {
+          const key = trimmed.slice(0, colonIdx).trim();
+          const value = trimmed.slice(colonIdx + 1).trim();
+          adherenceOverridesRaw[key] = value;
+        }
+        continue;
+      }
       if (activeBlock === 'theme' && currentThemeName) {
         // slot: #HEX or $ref  # optional comment
         const colonIdx = raw.indexOf(':');
@@ -375,19 +576,33 @@ export function parseBrandFile(content: string, fileName: string): ParsedBrand {
         continue;
       }
       if ((activeBlock === 'logo' || activeBlock === 'photo' || activeBlock === 'video' || activeBlock === 'illustration') && currentAssetId) {
+        const indent = raw.match(/^(\s*)/)?.[1].length ?? 0;
         const colonIdx = raw.indexOf(':');
         if (colonIdx !== -1) {
           const key = raw.slice(0, colonIdx).trim();
           const value = raw.slice(colonIdx + 1).trim();
           const arr = activeBlock === 'logo' ? logosRaw : activeBlock === 'photo' ? photosRaw : activeBlock === 'video' ? videosRaw : illustrationsRaw;
           const last = arr[arr.length - 1];
-          if (last && last.id === currentAssetId) last.props[key] = value;
+          if (last && last.id === currentAssetId) {
+            // 4+ space indent after a bare sub-block keyword (e.g. generator-params) → nested param.
+            // Store under "subBlock.key" so toAssetDef can split it out.
+            if (indent >= 4 && currentSubBlock) {
+              last.props[`${currentSubBlock}.${key}`] = value;
+            } else {
+              last.props[key] = value;
+              currentSubBlock = null;
+            }
+          }
         } else {
           const trimmed = raw.trim();
           if (trimmed === 'animated' || trimmed === 'loop') {
             const arr = activeBlock === 'logo' ? logosRaw : activeBlock === 'photo' ? photosRaw : activeBlock === 'video' ? videosRaw : illustrationsRaw;
             const last = arr[arr.length - 1];
             if (last && last.id === currentAssetId) last.props[trimmed] = 'true';
+            currentSubBlock = null;
+          } else if (trimmed === 'generator-params') {
+            // Open a nested sub-block — subsequent deeper-indented key: value lines attach here.
+            currentSubBlock = 'generator-params';
           }
         }
         continue;
@@ -406,14 +621,30 @@ export function parseBrandFile(content: string, fileName: string): ParsedBrand {
       continue;
     }
 
-    // Non-indented line ends any active block
-    activeBlock = 'none';
-
+    // Blank lines are ignored — they don't close active blocks (grouped brand-colors
+    // relies on blank lines between groups for readability).
     if (raw.trim() === '') continue;
 
+    // Non-indented non-blank line ends any active block
+    activeBlock = 'none';
+
     // brand-colors — starts the brand color primitives block
     if (raw.trim() === 'brand-colors') {
       activeBlock = 'brand-colors';
+      currentGroup = null;
+      currentGroupedEntry = null;
+      continue;
+    }
+
+    // state-colors — flat block of problem/warning/success/info/inactive
+    if (raw.trim() === 'state-colors') {
+      activeBlock = 'state-colors';
+      continue;
+    }
+
+    // color-bounds — luminance + saturation floor for guided derivation
+    if (raw.trim() === 'color-bounds') {
+      activeBlock = 'color-bounds';
       continue;
     }
 
@@ -496,18 +727,178 @@ export function parseBrandFile(content: string, fileName: string): ParsedBrand {
       case 'cta':
         activeBlock = 'cta';
         break;
+      case 'color-mode':
+        if (!VALID_COLOR_MODES.has(value as ColorMode)) {
+          throw new Error(`${fileName}:${lineNum}: color-mode must be "static", "dynamic", or "guided", got "${value}"`);
+        }
+        result.colorMode = value as ColorMode;
+        break;
+      case 'color-strategy':
+        if (!VALID_STRATEGIES.has(value as PaletteStrategy)) {
+          throw new Error(`${fileName}:${lineNum}: color-strategy must be one of monochrome/duotone/tricolor/spectrum, got "${value}"`);
+        }
+        result.colorStrategy = value as PaletteStrategy;
+        break;
+      case 'color-adherence':
+        if (!VALID_ADHERENCES.has(value as Adherence)) {
+          throw new Error(`${fileName}:${lineNum}: color-adherence must be "strict", "on-brand", or "flexible", got "${value}"`);
+        }
+        result.colorAdherence = value as Adherence;
+        // Optional indented overrides follow.
+        activeBlock = 'color-adherence';
+        break;
       default:
         // Unknown keys silently ignored for forward compatibility
         break;
     }
   }
 
-  // Store brand colors
+  // ── Finalise grouped brand-colors (v0.8.0+) ────────────────────────────────
+  if (colorGroups.length > 0) {
+    // Resolve $group.role references in declaration order — a reference may only point
+    // to a group earlier in the list than its containing group.
+    const resolvedNames = new Set<string>();
+    for (let gi = 0; gi < colorGroups.length; gi++) {
+      const group = colorGroups[gi];
+      for (const entry of group.entries) {
+        if (!entry.referencedFrom) {
+          // Normal entry — ensure its name doesn't collide (important for flat projection).
+          if (resolvedNames.has(entry.name)) {
+            throw new Error(`${fileName}: duplicate color name "${entry.name}" in brand-colors`);
+          }
+          resolvedNames.add(entry.name);
+          continue;
+        }
+        // Reference shape: "<group>.<role>"
+        const [refGroupKey, refRole] = entry.referencedFrom.split('.');
+        const refGroupIdx = colorGroups.findIndex(g => g.key === refGroupKey);
+        if (refGroupIdx === -1) {
+          throw new Error(`${fileName}: reference "$${entry.referencedFrom}" targets unknown group "${refGroupKey}"`);
+        }
+        if (refGroupIdx >= gi) {
+          throw new Error(`${fileName}: reference "$${entry.referencedFrom}" must point to a group declared earlier (forward/self references forbidden)`);
+        }
+        const refGroup = colorGroups[refGroupIdx];
+        // Find the target entry. `default` matches explicit or first-declared default.
+        let target: BrandColorEntry | undefined;
+        if (refRole === 'default') {
+          target = refGroup.entries.find(e => e.isDefault) ?? refGroup.entries[0];
+        } else {
+          target = refGroup.entries.find(e => e.role === refRole);
+        }
+        if (!target) {
+          throw new Error(`${fileName}: reference "$${entry.referencedFrom}" — no entry with role "${refRole}" in group "${refGroupKey}"`);
+        }
+        entry.hex = target.hex;
+        entry.name = target.name;
+        // Don't add referenced name to resolvedNames — it's already registered under the target.
+      }
+
+      // Apply default selection rule for identity groups.
+      if (group.key !== 'neutral' && group.entries.length > 0) {
+        const explicit = group.entries.find(e => e.isDefault);
+        if (!explicit) {
+          // First-declared wins implicitly.
+          group.entries[0].isDefault = true;
+        }
+      }
+
+      // Neutral-group role validation.
+      if (group.key === 'neutral') {
+        for (const entry of group.entries) {
+          if (entry.role && !NEUTRAL_ROLES.has(entry.role as NeutralRole)) {
+            throw new Error(
+              `${fileName}: neutral entry "${entry.name}" role "${entry.role}" is not in the fixed vocabulary (light | subtle | mid | muted | dark)`,
+            );
+          }
+        }
+      }
+    }
+
+    result.colorGroups = colorGroups;
+
+    // Build flat projection so legacy consumers keep working unchanged.
+    // Key convention: the entry's display name lowercased, spaces → hyphens.
+    // Name collisions already rejected above, so the projection is deterministic.
+    for (const group of colorGroups) {
+      for (const entry of group.entries) {
+        const key = entry.name.toLowerCase().replace(/\s+/g, '-');
+        if (!brandColors[key]) {
+          brandColors[key] = entry.hex;
+          if (entry.print) brandColorPrint[key] = entry.print;
+        }
+      }
+    }
+  }
+
+  // Store brand colors (flat projection)
   if (Object.keys(brandColors).length > 0) {
     result.brandColors = brandColors;
     if (Object.keys(brandColorPrint).length > 0) result.brandColorPrint = brandColorPrint;
   }
 
+  // ── Finalise state-colors / color-bounds / adherence overrides ────────────
+  if (Object.keys(stateColorsRaw).length > 0) {
+    const state: StateColors = {};
+    for (const [key, value] of Object.entries(stateColorsRaw)) {
+      if (!STATE_KEYS.has(key)) continue; // forward-compat: ignore unknown
+      const hex = normalizeHex(value);
+      if (!hex) {
+        throw new Error(`${fileName}: state-colors "${key}" value "${value}" is not a valid hex`);
+      }
+      (state as Record<string, string>)[key] = hex;
+    }
+    if (Object.keys(state).length > 0) result.stateColors = state;
+  }
+
+  if (Object.keys(colorBoundsRaw).length > 0) {
+    const bounds: ColorBounds = {};
+    if (colorBoundsRaw.light !== undefined) bounds.light = parseFloat(colorBoundsRaw.light);
+    if (colorBoundsRaw.dark !== undefined) bounds.dark = parseFloat(colorBoundsRaw.dark);
+    if (colorBoundsRaw['saturation-floor'] !== undefined) {
+      bounds.saturationFloor = parseFloat(colorBoundsRaw['saturation-floor']);
+    }
+    result.colorBounds = bounds;
+  }
+
+  if (Object.keys(adherenceOverridesRaw).length > 0) {
+    const overrides: AdherenceTolerances = {};
+    if (adherenceOverridesRaw['hue-tolerance'] !== undefined) {
+      overrides.hueTolerance = parseFloat(adherenceOverridesRaw['hue-tolerance']);
+    }
+    if (adherenceOverridesRaw['sat-tolerance'] !== undefined) {
+      overrides.satTolerance = parseFloat(adherenceOverridesRaw['sat-tolerance']);
+    }
+    if (Object.keys(overrides).length > 0) result.colorAdherenceOverrides = overrides;
+  }
+
+  // ── Minimum-structure validation for color-mode: guided ───────────────────
+  if (result.colorMode === 'guided') {
+    if (colorGroups.length === 0) {
+      throw new Error(
+        `${fileName}: color-mode: guided requires grouped brand-colors syntax — flat syntax is not sufficient. See the Minimum Structure section in the guided-colors spec.`,
+      );
+    }
+    const primary = colorGroups.find(g => g.key === 'primary');
+    const neutral = colorGroups.find(g => g.key === 'neutral');
+    if (!primary) {
+      throw new Error(`${fileName}: color-mode: guided requires a "primary" group`);
+    }
+    if (!neutral) {
+      throw new Error(`${fileName}: color-mode: guided requires a "neutral" group`);
+    }
+    const neutralRoles = new Set(neutral.entries.map(e => e.role).filter(Boolean));
+    if (!neutralRoles.has('light')) {
+      throw new Error(`${fileName}: color-mode: guided requires neutral group to declare at least role "light"`);
+    }
+    if (!neutralRoles.has('dark')) {
+      throw new Error(`${fileName}: color-mode: guided requires neutral group to declare at least role "dark"`);
+    }
+    if (primary.entries.length === 0) {
+      throw new Error(`${fileName}: color-mode: guided requires primary group to have at least one color`);
+    }
+  }
+
   // Finalise inline tokens — resolve $ref values against brandColors, apply optional alpha.
   //
   // Theme slot grammar:
@@ -616,6 +1007,18 @@ export function parseBrandFile(content: string, fileName: string): ParsedBrand {
     if (raw.props['lottie']) def.lottieSrc = raw.props['lottie'];
     if (raw.props['animated'] === 'true') def.animated = true;
     if (raw.props['loop'] === 'true') def.loop = true;
+    if (raw.props['gltf']) def.gltfSrc = raw.props['gltf'];
+    if (raw.props['generator']) def.generator = raw.props['generator'];
+    // generator-params are stored as "generator-params.KEY" by the sub-block parser.
+    const paramEntries: [string, number][] = [];
+    for (const [k, v] of Object.entries(raw.props)) {
+      if (k.startsWith('generator-params.')) {
+        const paramKey = k.slice('generator-params.'.length);
+        const n = parseFloat(v);
+        if (!Number.isNaN(n)) paramEntries.push([paramKey, n]);
+      }
+    }
+    if (paramEntries.length > 0) def.generatorParams = Object.fromEntries(paramEntries);
     return def;
   };
   if (logosRaw.length > 0 || photosRaw.length > 0 || videosRaw.length > 0 || illustrationsRaw.length > 0) {

package/parser/identityParser.ts

@@ -26,6 +26,8 @@ export interface ParsedIdentity {
   tagline?: string;
   /** Competitive positioning — what makes this brand the only one of its kind */
   positioning?: string;
+  /** Brand purpose — why the brand exists, the inner motivation (distinct from promise, mission, vision) */
+  purpose?: string;
   /** Organizational mission — what the brand does, for whom */
   mission?: string;
   /** Aspirational future state */
@@ -109,6 +111,7 @@ export function parseIdentityFile(content: string, fileName: string): ParsedIden
   let promise = '';
   let tagline = '';
   let positioning = '';
+  let purpose = '';
   let mission = '';
   let vision = '';
   let archetype = '';
@@ -195,6 +198,7 @@ export function parseIdentityFile(content: string, fileName: string): ParsedIden
         if (continuationKey === 'essence') essence += ' ' + continuation;
         else if (continuationKey === 'promise') promise += ' ' + continuation;
         else if (continuationKey === 'positioning') positioning += ' ' + continuation;
+        else if (continuationKey === 'purpose') purpose += ' ' + continuation;
         else if (continuationKey === 'mission') mission += ' ' + continuation;
         else if (continuationKey === 'vision') vision += ' ' + continuation;
         continue;
@@ -300,6 +304,10 @@ export function parseIdentityFile(content: string, fileName: string): ParsedIden
           positioning = val;
           continuationKey = 'positioning';
           break;
+        case 'purpose':
+          purpose = val;
+          continuationKey = 'purpose';
+          break;
         case 'mission':
           mission = val;
           continuationKey = 'mission';
@@ -425,6 +433,7 @@ export function parseIdentityFile(content: string, fileName: string): ParsedIden
   // Optional fields — only include if present
   if (tagline) result.tagline = tagline;
   if (positioning) result.positioning = positioning;
+  if (purpose) result.purpose = purpose;
   if (mission) result.mission = mission;
   if (vision) result.vision = vision;
   if (archetype) result.archetype = archetype;

package/parser/index.ts

@@ -7,6 +7,19 @@ export type { ParsedIdentity, ParsedVoice, ParsedPillars, ParsedAudience, Parsed
 
 export { parseBrandFile } from './brandParser';
 export type { ParsedBrand, ParsedFontDef, ParsedTypographyDef, ParsedDividerDef, BrandColorPrintSpec, ParsedAssetDef, ParsedBadgeStyle } from './brandParser';
+export type {
+  ColorMode,
+  PaletteStrategy,
+  Adherence,
+  AdherenceTolerances,
+  ColorBounds,
+  StateColors,
+  GroupKey,
+  IdentityGroupKey,
+  NeutralRole,
+  BrandColorEntry,
+  BrandColorGroup,
+} from './types';
 
 export { parseFormatFile } from './formatParser';
 export type { ParsedFormat } from './formatParser';

package/parser/types.ts

@@ -15,3 +15,80 @@ export interface ZoneInsets {
 
 /** Text alignment options. */
 export type TextAlign = 'left' | 'center' | 'right' | 'justify';
+
+// ── Guided colors (v0.8.0) ────────────────────────────────────────────────────
+
+/** Color resolution mode declared at the brand level. */
+export type ColorMode = 'static' | 'dynamic' | 'guided';
+
+/** Palette construction strategy for guided shuffle (Path A only). */
+export type PaletteStrategy = 'monochrome' | 'duotone' | 'tricolor' | 'spectrum';
+
+/** Adherence level — how tightly guided derivation follows brand groups. */
+export type Adherence = 'strict' | 'on-brand' | 'flexible';
+
+/** Optional per-brand tolerance overrides for the declared adherence level. */
+export interface AdherenceTolerances {
+  /** Hue drift tolerance in degrees. */
+  hueTolerance?: number;
+  /** Saturation variance tolerance in percentage points. */
+  satTolerance?: number;
+}
+
+/** Bounds for all guided derivation — brand scales, state variants, neutral interpolation. */
+export interface ColorBounds {
+  /** Max luminance for derived tints (0–1). Never brighter than this. */
+  light?: number;
+  /** Min luminance for derived shades (0–1). Never darker than this. */
+  dark?: number;
+  /** Min saturation (0–100) for derived colors — prevents washed-out grays. */
+  saturationFloor?: number;
+}
+
+/** Fixed per-brand state (problem / success / warning / info / inactive) colors. */
+export interface StateColors {
+  problem?: string;
+  warning?: string;
+  success?: string;
+  info?: string;
+  inactive?: string;
+}
+
+/** Identity group keys (neutral is structurally distinct). */
+export type IdentityGroupKey = 'primary' | 'secondary' | 'accent';
+/** All four group keys. */
+export type GroupKey = IdentityGroupKey | 'neutral';
+
+/** Fixed neutral-role vocabulary — ordered light → dark. */
+export type NeutralRole = 'light' | 'subtle' | 'mid' | 'muted' | 'dark';
+
+/** One entry within a brand color group. */
+export interface BrandColorEntry {
+  /** Resolved 6-digit hex (uppercase). */
+  hex: string;
+  /** Display name as authored (`#HEX  Name` → "Name"). Reference entries inherit the target's name. */
+  name: string;
+  /** Authored role (identity groups) or fixed neutral-role vocabulary (neutral group). */
+  role?: string;
+  /** Marks this entry as the group default. Only meaningful in identity groups. */
+  isDefault?: boolean;
+  /** Authored meaning string — human-facing only, engine ignores. */
+  meaning?: string;
+  /** When the entry was declared via a `$group.role` reference, the reference path (informational only). */
+  referencedFrom?: string;
+  /** Print specs authored on this entry (Pantone, HKS, CMYK). */
+  print?: { pantone?: string; hks?: string; cmyk?: string };
+}
+
+/** One color group within the `brand-colors` block. */
+export interface BrandColorGroup {
+  /** Group key — fixed vocabulary. */
+  key: GroupKey;
+  /** Authored meaning — human-facing only. */
+  meaning?: string;
+  /** Selection-probability weight (0–100). Invalid on neutral. */
+  distribution?: number;
+  /** Ordered entries as declared. */
+  entries: BrandColorEntry[];
+}
+

package/skills/brief.md

@@ -10,7 +10,7 @@ description: Generate a portable markdown brand brief from Brand Intent DSL file
 > If `$ARGUMENTS` names a brand id (e.g. "krume", "studio-stoll"): locate that brand folder under the current working directory and generate its brief.
 > If no brand is found: tell the user to run `/brand-intent onboard` (or `npx brand-intent init` to scaffold the Krume example) and stop.
 
-You are generating a **portable brand brief** — a single markdown file, `{brand-id}-brief.md`, written at the brand root. The brief is format-agnostic: it can be dropped into any tool that doesn't read Brand Intent DSL files directly — a Claude design project, another LLM, a human collaborator.
+You are generating a **portable brand brief** — a single markdown file, `{brand-id}-brief.md`, written at the brand root. The brief is format-agnostic: it can be dropped into any tool that doesn't read Brand Intent files directly — a Claude Design project, another LLM, a human collaborator.
 
 The brief is **derived**, not authored. Every value comes verbatim from the DSL files. You never rephrase, interpret, or invent.
 
@@ -194,4 +194,4 @@ Generated by `/brief` from brand-intent v{version}. To change anything in this b
 - **Omit absent optional sections entirely.** No empty headers, no "none" placeholders.
 - **Never add `guardrails:` to the DSL.** The Guardrails section in the brief is always derived from existing `.identity` fields.
 - **Never invent.** If `voice.always` is empty, the Always list is empty. Don't fill gaps.
-- **Claude design is an example, not a dependency.** This brief works anywhere. Don't phrase it as Claude-specific.
+- **Claude Design is an example, not a dependency.** This brief works anywhere. Don't phrase it as Claude-specific.