brand-intent 0.5.1 → 0.7.0

package/README.md

@@ -34,12 +34,21 @@ ext install studiostoll.brand-intent-lang
 
 ### 2. Run init
 
-Installs the Brand Intent skill for your AI agent. The skill handles everything else: onboard your brand through a guided interview, explore the Krume bakery reference, generate and validate on-brand content.
+Installs two skills into your AI agent: `/brand-intent` and `/brief`. Together they cover the full loop. Onboard your brand, explore the Krume bakery reference, generate and validate on-brand content, and export a portable brief.
 
 ```bash
 npx brand-intent init
 ```
 
+### 3. Use your brand
+
+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.
+
+Edit your DSL files whenever strategy or expression evolves. Regenerate briefs after any change.
+
 ## Documentation
 
 - [Specification](SPEC.md): formal grammar for all five file types

package/cli/index.mjs

@@ -9,7 +9,7 @@ const __filename = fileURLToPath(import.meta.url);
 const __dirname = dirname(__filename);
 const PKG_ROOT = resolve(__dirname, '..');
 
-const SKILL_FILE = join(PKG_ROOT, 'skills', 'brand-intent.md');
+const SKILL_FILES = ['brand-intent.md', 'brief.md'];
 
 // ── Harness detection ──
 
@@ -69,12 +69,15 @@ function scaffoldExample(targetDir) {
 // ── Install skill ──
 
 async function installSkills(cwd) {
-  if (!existsSync(SKILL_FILE)) {
-    console.error('Error: skill file not found at', SKILL_FILE);
-    process.exit(1);
-  }
+  const skills = SKILL_FILES.map(name => {
+    const path = join(PKG_ROOT, 'skills', name);
+    if (!existsSync(path)) {
+      console.error('Error: skill file not found at', path);
+      process.exit(1);
+    }
+    return { name, content: readFileSync(path, 'utf-8') };
+  });
 
-  const skill = readFileSync(SKILL_FILE, 'utf-8');
   let harnesses = detectHarnesses(cwd);
 
   if (harnesses.length === 0) {
@@ -98,9 +101,11 @@ async function installSkills(cwd) {
   for (const { label, dir } of harnesses) {
     const target = join(cwd, dir);
     mkdirSync(target, { recursive: true });
-    const dest = join(target, 'brand-intent.md');
-    writeFileSync(dest, skill, 'utf-8');
-    console.log(`  \u2713 ${label} \u2014 ${dir}/brand-intent.md`);
+    for (const { name, content } of skills) {
+      const dest = join(target, name);
+      writeFileSync(dest, content, 'utf-8');
+      console.log(`  ✓ ${label} — ${dir}/${name}`);
+    }
   }
 
   return harnesses;
@@ -121,7 +126,7 @@ if (command && command !== 'init' && command !== 'install-skills' && command !==
 
 if (!command || command === '--help' || command === '-h') {
   console.log('Usage:');
-  console.log('  brand-intent init              Install the Brand Intent skill for your AI agent');
+  console.log('  brand-intent init              Install the Brand Intent and Brief skills for your AI agent');
   console.log('  brand-intent install-skills     Same as init (alias)');
   console.log('');
   console.log('Example:');
@@ -138,7 +143,7 @@ if (targetDir !== cwd) {
 }
 console.log('\n  This will:');
 console.log('  \u2014 Copy the Krume bakery reference into examples/krume/');
-console.log('  \u2014 Install the Brand Intent skill for your AI agent\n');
+console.log('  \u2014 Install the Brand Intent and Brief skills for your AI agent\n');
 const proceed = await ask('  Proceed? (Y/n) ');
 if (proceed.trim().toLowerCase() === 'n') {
   closeRl();
@@ -158,4 +163,5 @@ console.log('    /brand-intent onboard     Create your brand through a guided in
 console.log('    /brand-intent example     Scaffold the Krume reference implementation');
 console.log('    /brand-intent validate    Validate content against your brand rules');
 console.log('    /brand-intent             Discover brand files and available purposes');
+console.log('    /brief                    Generate a portable brand brief');
 console.log('');

package/examples/krume/krume.brand

@@ -142,14 +142,12 @@ spacing:
 divider line
   thickness: 0.15
   width: 100%
-  color: divider
   align: left
   spacing: s
 
 divider ruler
   thickness: 0.8
   width: 20%
-  color: divider
   align: left
   spacing: m
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "brand-intent",
-  "version": "0.5.1",
+  "version": "0.7.0",
   "description": "An open file format specification for making brand intent machine-readable.",
   "author": "Christophe Stoll <christophe@stoll.studio>",
   "license": "MIT",

package/parser/brandParser.ts

@@ -123,19 +123,117 @@ export interface ParsedDividerDef {
   thickness: number;
   /** Line width — percentage string (e.g. '15%') or '100%' */
   width: string;
-  /**
-   * Resolved color value. Supports:
-   * - Brand color names: 'accent1', 'accent2', 'primary', 'secondary', etc. (resolved to hex at parse time)
-   * - Raw hex: '#E32D39'
-   * - Theme slot names: 'logo' | 'cta' | 'sticker' | 'background' | 'text-primary' | … (resolved at render time via resolveDividerColor)
-   */
-  color: string;
   /** Spacing token name applied above and below the divider (xs | s | m | l | xl) */
   spacing: string;
   /** Horizontal alignment of a partial-width divider (default: 'left') */
   align: 'left' | 'center' | 'right';
 }
 
+// ── Helpers ────────────────────────────────────────────────────────────────────
+
+/**
+ * Expand a 3-digit hex to 6-digit. Pass-through for 6 or 8-digit.
+ * Returns null for invalid input.
+ */
+function normalizeHex(hex: string): string | null {
+  const m = hex.match(/^#([0-9a-fA-F]{3}|[0-9a-fA-F]{6}|[0-9a-fA-F]{8})$/);
+  if (!m) return null;
+  const body = m[1];
+  if (body.length === 3) {
+    return '#' + body.split('').map(c => c + c).join('').toUpperCase();
+  }
+  return '#' + body.toUpperCase();
+}
+
+/** Parse a 6-digit hex into [r, g, b]. Input must be normalised to 6 digits. */
+function hexToRgb(hex6: string): [number, number, number] {
+  const body = hex6.slice(1);
+  return [
+    parseInt(body.slice(0, 2), 16),
+    parseInt(body.slice(2, 4), 16),
+    parseInt(body.slice(4, 6), 16),
+  ];
+}
+
+/**
+ * Resolve a theme-slot value string to a final CSS color.
+ *
+ * Supports: `$ref`, `$ref NN%`, `#HEX`, `#HEX NN%`, raw rgba(...) pass-through.
+ * Throws on malformed alpha or unresolved `$ref`.
+ */
+function resolveThemeSlotValue(
+  raw: string,
+  brandColors: Record<string, string>,
+  fileName: string,
+  slot: string,
+): string {
+  const value = raw.trim();
+
+  // Legacy rgba(...) literal — pass through unchanged.
+  if (/^rgba?\s*\(/i.test(value)) return value;
+
+  // Detect an alpha suffix: "<base> NN%" (one or more spaces, numeric, trailing %).
+  // If the line contains a % but the shape doesn't match, it's malformed.
+  let base = value;
+  let alpha: number | null = null;
+  const alphaMatch = value.match(/^(\S+)\s+([0-9]+(?:\.[0-9]+)?)%$/);
+  if (alphaMatch) {
+    base = alphaMatch[1];
+    alpha = parseFloat(alphaMatch[2]);
+    if (alpha < 0 || alpha > 100) {
+      throw new Error(
+        `${fileName}: theme slot "${slot}" alpha must be between 0 and 100, got ${alpha}`,
+      );
+    }
+  } else if (value.includes('%')) {
+    throw new Error(
+      `${fileName}: theme slot "${slot}" alpha syntax is "<value> NN%" with a single space, got "${value}"`,
+    );
+  }
+
+  // Resolve base to a hex string.
+  let hex: string | null = null;
+  if (base.startsWith('$')) {
+    const refName = base.slice(1);
+    const resolved = brandColors[refName];
+    if (!resolved) {
+      throw new Error(
+        `${fileName}: theme slot "${slot}" references unknown brand color "$${refName}"`,
+      );
+    }
+    hex = normalizeHex(resolved);
+    if (!hex) {
+      throw new Error(
+        `${fileName}: theme slot "${slot}" base "$${refName}" resolves to "${resolved}", which is not a valid hex color`,
+      );
+    }
+  } else {
+    hex = normalizeHex(base);
+    if (!hex) {
+      // Not a hex, not a $ref — but it might be a bare keyword like "currentColor" or
+      // a semantic slot name used for dividers historically. Pass through only when
+      // no alpha was requested; with alpha, the base must be concrete.
+      if (alpha !== null) {
+        throw new Error(
+          `${fileName}: theme slot "${slot}" base "${base}" must be "$ref" or "#HEX" when using alpha`,
+        );
+      }
+      return value;
+    }
+  }
+
+  // No alpha → solid hex.
+  if (alpha === null) return hex;
+
+  // 100% alpha → emit solid hex (keep output clean).
+  if (alpha === 100) return hex;
+
+  const [r, g, b] = hexToRgb(hex);
+  // Drop trailing zeros for cleanliness: 0.7 not 0.70, 0.5 not 0.50.
+  const a = Number((alpha / 100).toFixed(4)).toString();
+  return `rgba(${r}, ${g}, ${b}, ${a})`;
+}
+
 // ── Parser ─────────────────────────────────────────────────────────────────────
 
 export function parseBrandFile(content: string, fileName: string): ParsedBrand {
@@ -191,6 +289,12 @@ export function parseBrandFile(content: string, fileName: string): ParsedBrand {
           const value = trimmed.slice(colonIdx + 1).trim();
           if (indentLen <= 2) {
             // Top-level color line: "  primary: #0324B1"
+            // Brand colors are solid primitives only — alpha belongs in theme slots.
+            if (/%/.test(value) || /rgba\s*\(/i.test(value)) {
+              throw new Error(
+                `${fileName}:${lineNum}: brand color "${key}" must be a solid hex — alpha syntax (e.g. "$ref 75%" or rgba()) is only allowed in theme slots`,
+              );
+            }
             brandColors[key] = value;
             currentBrandColorName = key;
           } else if (currentBrandColorName) {
@@ -236,6 +340,11 @@ export function parseBrandFile(content: string, fileName: string): ParsedBrand {
         if (colonIdx !== -1) {
           const key = raw.slice(0, colonIdx).trim();
           const value = raw.slice(colonIdx + 1).trim();
+          if (key === 'color') {
+            throw new Error(
+              `${fileName}:${lineNum}: divider "${currentDividerName}": color is no longer configurable. Remove the "color:" line — divider color is sourced from the theme's "divider" slot.`,
+            );
+          }
           if (!dividersRaw[currentDividerName]) dividersRaw[currentDividerName] = {};
           dividersRaw[currentDividerName][key] = value;
         }
@@ -399,19 +508,21 @@ export function parseBrandFile(content: string, fileName: string): ParsedBrand {
     if (Object.keys(brandColorPrint).length > 0) result.brandColorPrint = brandColorPrint;
   }
 
-  // Finalise inline tokens — resolve $ref values against brandColors
+  // Finalise inline tokens — resolve $ref values against brandColors, apply optional alpha.
+  //
+  // Theme slot grammar:
+  //   slot: $ref              → resolve ref to hex
+  //   slot: $ref 75%          → resolve ref, then apply alpha (rgba)
+  //   slot: #HEX              → pass through
+  //   slot: #HEX 30%          → apply alpha (rgba)
+  //   slot: rgba(...)         → pass through (legacy, discouraged)
+  //
+  // Alpha is expressed as `<number>%`, 0–100, separated from the base value by exactly one space.
+  // 100% emits solid hex (not rgba) to keep output clean.
   if (Object.keys(themes).length > 0) {
     for (const theme of Object.values(themes)) {
       for (const [slot, value] of Object.entries(theme)) {
-        if (value.startsWith('$')) {
-          const refName = value.slice(1);
-          const resolved = brandColors[refName];
-          if (resolved) {
-            theme[slot] = resolved;
-          } else {
-            console.warn(`${fileName}: unresolved brand color reference "$${refName}" in theme slot "${slot}"`);
-          }
-        }
+        theme[slot] = resolveThemeSlotValue(value, brandColors, fileName, slot);
       }
     }
     result.themes = themes;
@@ -428,12 +539,9 @@ export function parseBrandFile(content: string, fileName: string): ParsedBrand {
     };
   }
 
-  // Finalise dividers
+  // Finalise dividers — color is always sourced from the active theme's "divider" slot.
   if (Object.keys(dividersRaw).length > 0) {
     const dividers: Record<string, ParsedDividerDef> = {};
-    // Resolve a color value: brand color name (accent1, accent2, …) → hex,
-    // semantic slot names → kept as-is for resolveDividerColor(), raw hex → pass through.
-    const resolveColor = (c: string): string => brandColors[c] ?? c;
     for (const [name, raw] of Object.entries(dividersRaw)) {
       const alignRaw = raw['align'] ?? 'left';
       const align: ParsedDividerDef['align'] =
@@ -441,7 +549,6 @@ export function parseBrandFile(content: string, fileName: string): ParsedBrand {
       dividers[name] = {
         thickness: parseFloat(raw['thickness'] ?? '0.2'),
         width: raw['width'] ?? '100%',
-        color: resolveColor(raw['color'] ?? 'text-tertiary'),
         spacing: raw['spacing'] ?? 'xs',
         align,
       };

package/parser/purposeParser.ts

@@ -67,7 +67,7 @@ export interface ParsedPurposeSlot {
   itemGap?: number;
   /** List layout direction: 'vertical' (default) or 'horizontal'. */
   listDirection?: 'vertical' | 'horizontal';
-  /** When true, this slot is editable by the user in consume mode. Default: false. */
+  /** When false, this slot is locked — users cannot edit it in any mode. Default: true (editable). */
   editable?: boolean;
   typography: {
     fontFamily: string;

package/skills/brief.md

@@ -0,0 +1,197 @@
+---
+description: Generate a portable markdown brand brief from Brand Intent DSL files
+---
+
+# Brief
+
+**Scope:** `$ARGUMENTS`
+
+> If `$ARGUMENTS` is empty: auto-detect the active brand from the current working directory (see File Discovery in the Brand Intent skill) and generate its brief.
+> 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.
+
+The brief is **derived**, not authored. Every value comes verbatim from the DSL files. You never rephrase, interpret, or invent.
+
+## When to Regenerate
+
+The brief is a snapshot. Regenerate it after any change to `.identity`, `.brand`, `.purpose`, `.format`, or `.composition` files. The header always stamps the generation timestamp and the Brand Intent DSL version so stale briefs are detectable.
+
+## Procedure
+
+1. **Resolve the brand root.** Find the folder containing both `{brand-id}.identity` and `{brand-id}.brand`. If either file is missing, stop and tell the user to run `/brand-intent onboard`.
+
+2. **Read the required files.**
+   - `{brand-id}.identity` — strategic layer
+   - `{brand-id}.brand` — derived expression layer
+
+3. **Read optional files if present.** Each becomes a labeled optional section in the brief. If absent, omit the section entirely — do not emit empty headers.
+   - `{brand-id}.purpose` at brand root (rare)
+   - any files under `purposes/` (multiple allowed)
+   - any files under `formats/`
+   - any files under `compositions/`
+
+4. **Read the Brand Intent DSL version.** Try resolving the installed `brand-intent` package's `package.json` version. If unreachable (the skill runs in a harness, not always inside the brand-intent repo), use `"unknown"`.
+
+5. **Compose the brief** per the template below. Extract values verbatim — never rephrase or interpret. If a field is absent in the DSL, omit its row; never invent.
+
+6. **Auto-derive the Guardrails section** from `.identity`:
+   - every item in `voice.never`
+   - every item in `voice.always`
+   - `pillars.avoid` list
+   - every `anti-audience` block (label + description)
+
+   The Guardrails *section in the brief* is derived. Never add a `guardrails:` block to the DSL — guardrails live inside `.identity` already.
+
+7. **Write the file.** Output path: `{brand-root}/{brand-id}-brief.md`. If the file exists, confirm overwrite in one line before proceeding.
+
+8. **Report.** Print one line: `Wrote {path}. Regenerate after any DSL change.`
+
+## Output Template
+
+Write exactly this structure. Each section includes a one-line **role description** so the brief self-documents when pasted into any context.
+
+```markdown
+# {Brand Name} — Brand Brief
+
+> Portable brief derived from Brand Intent DSL files.
+> Brand Intent version: {version} · Generated: {ISO timestamp}
+> Source of truth lives in the DSL files. Regenerate after any DSL change.
+
+## Essence
+_Role: the irreducible truth of the brand._
+
+{identity.essence}
+
+## Promise
+_Role: what the brand commits to deliver._
+
+{identity.promise}
+
+## Positioning / Mission / Vision / Tagline / Archetype
+_Role: strategic frame. Only rows that exist in the identity are emitted._
+
+- **Positioning:** {...}
+- **Mission:** {...}
+- (etc. — skip any row whose field is absent)
+
+## Narratives
+_Role: the brand's stories. The primary narrative is the default story._
+
+- **{name}** (primary) — {text}
+- **{name}** — {text}
+
+## Voice
+_Role: how this brand sounds._
+
+- **Register:** {voice.register}
+- **Persona:** {voice.persona}
+- **Rhythm:** {voice.rhythm}
+
+## Values
+_Role: behavior statements, not keywords._
+
+- **{name}** — {behavior}
+
+## Content Pillars
+_Role: what the brand talks about, and what it avoids._
+
+- **Primary:** {pillars.primary}
+- **Secondary:** {pillars.secondary}
+- **Avoid:** {pillars.avoid}
+
+## Audiences
+_Role: who the brand speaks to._
+
+For each audience segment in `.identity`:
+
+- **{label}**
+  - Profile: {...}
+  - Motivation: {...}
+  - Language guidance: {...}
+
+## Expression (from .brand)
+_Role: derived expression conditions — the "how it looks and sounds" layer, not expression itself._
+
+- **Language / locale:** {brand.language} / {brand.locale}
+- **Color primitives:** list each `brand-colors` entry as `name → hex`
+- **Themes:** list each theme with its slot-to-color mappings
+- **Typography styles:** for each named style — font, weight, size (always append unit `cqh` — container-query-height, responsive to the canvas height), lineHeight, letterSpacing, flags like `uppercase`, autofit-min/max if present
+- **Fonts:** for each font block — name, source, variants
+- **Spacing scale:** unit + named steps (e.g. `cqmin` — container-query-min, responsive to the shorter canvas side; xs/s/m/l/xl)
+- **Dividers:** if present, list each
+- **Voice constraints:** `sentence-max`, `headline-pattern`, `number-format`, `register` (if absent in `.brand`, note "not declared" — do not omit the row)
+
+## Guardrails (auto-derived)
+_Role: hard rules any generator, agent, or reviewer must enforce._
+
+**Never:**
+- {each voice.never item}
+
+**Always:**
+- {each voice.always item}
+
+**Avoid topics:**
+- {each pillars.avoid item}
+
+**Anti-audiences:**
+- **{label}** — {description}
+
+## Purposes (optional)
+_Role: content types — what each piece of content is trying to do. Only emitted if any `.purpose` files are present._
+
+For each purpose, emit **glossed** tags — not verbatim DSL values:
+
+- **{id}** — {name}
+  - Compositions: {composition ids}
+  - **Density:** gloss the value — `light` = "minimal slots filled, headline-forward"; `medium` = "balanced slot fill"; `full` = "all slots populated". Emit as `{value} — "{gloss}"`.
+  - **Palette:** gloss — `dynamic` = "inherits theme colors at render time"; `fixed` = "uses a specific theme"; other values pass through verbatim.
+  - **Uses photo:** translate `camera:` field — `true` → "yes"; `false` → "no". Do not emit "camera: false".
+  - **Logo:** gloss — `text` = "wordmark (text logo)"; `mark` = "graphic mark"; other values pass through verbatim.
+  - Scope: {scope audience + pillars}
+  - Context: {context prose per slot}
+  - Slots: for each slot — id, typography, maxLength, samples. Omit `color:` references (theme-internal detail). Override hints (`hyphenate`, `textAlign`) pass through as-is.
+
+## Formats (optional)
+_Role: where content appears. Only emitted if any `.format` files are present._
+
+For each format, label axes and units explicitly:
+
+- **{id}** ({label} {sublabel}) — category: {category}
+  - **Size:** {width} × {height} px
+  - **Grid:** {rows} rows × {cols} cols — always state which number is which. The DSL writes `grid: ROWS COLS`.
+  - **Danger zone:** {top} {right} {bottom} {left} px (platform UI overlay insets)
+  - **Crop:** {top} {right} {bottom} {left} px, or "none"
+  - **Comfort zone:** {value}% inset from the usable area
+
+## Compositions (optional)
+_Role: spatial arrangement of slots. Only emitted if any `.composition` files are present._
+
+For each composition, gloss the layout mode and decode positioning tokens:
+
+- **{id}** ({name})
+  - **Mode:** gloss — `flow` = "sequential vertical stack of slots with tunable spacers between them"; `grid` = "2D cell placement on the format grid". Emit as `{mode} — "{gloss}"`.
+  - **Image:** if present, state whether it's full-bleed or panel-scoped (`full` → "full-bleed background", other values pass through).
+  - **Sticky bar:** translate `sticky: top m` as "pinned to top edge, size/padding `m` (from spacing scale)"; list each item (e.g. `label left`, `logo right`) with position noted.
+  - **Flow:** emit the raw flow string for precision, then a one-line prose gloss describing what the layout visually produces. Decode tokens:
+    - `spacer-xs/s/m/l/xl` — spacer using the named step from the spacing scale
+    - `spacer-auto` — flexible spacer that absorbs remaining space
+    - `{slot} left/center/right` — slot with its text alignment
+    - `panel {anchor} {width} {height}` — a constrained panel anchored to an edge or corner (e.g. `panel bottom-left 2/3 1/1` = "panel anchored to bottom-left, 2/3 canvas width × full canvas height")
+    - `split {edge} {fraction}` — the canvas is split at the given edge and fraction (e.g. `split bottom 1/2` = "canvas split horizontally, content occupies bottom half")
+    - `divider-{name}` — references a divider style from `.brand`
+    - `columns:N gap:{size}` — the slot renders as N columns with the named gap
+
+---
+Generated by `/brief` from brand-intent v{version}. To change anything in this brief, edit the DSL files and regenerate.
+```
+
+## Rules
+
+- **No rephrasing.** Values are extracted verbatim from the DSL files.
+- **No interpretation.** If a field is ambiguous, emit it as-is; don't explain it.
+- **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.