brand-intent 0.25.0 → 0.27.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "brand-intent",
-  "version": "0.25.0",
+  "version": "0.27.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

@@ -57,20 +57,6 @@ export interface ParsedBrand {
   locale: string;
   /** Named font primitives: name → font definition. First entry is the brand default. */
   fonts?: Record<string, ParsedFontDef>;
-  /** Token source type: 'figma' | 'inline' */
-  tokensSource: 'figma' | 'inline';
-  /** Figma file key (only when tokensSource === 'figma') */
-  figmaFileKey?: string;
-  /** Figma collection name (only when tokensSource === 'figma') */
-  figmaCollection?: string;
-  /** Path to the runtime tokens file (relative to /src) */
-  tokensFile: string;
-  /** Path to app icon asset (relative to /public), used for PWA icon */
-  appIcon?: string;
-  /** Path to favicon asset (relative to /public), used for browser tab icon */
-  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).
    *  Always present when any colors are declared — grouped-syntax brands get a flat projection
    *  generated from all entries, so legacy consumers keep working unchanged. */
@@ -103,11 +89,11 @@ export interface ParsedBrand {
   themePairs?: Record<string, ThemePair>;
   /** Non-fatal color findings: rule violations, rejected family pairs, reach config hints. */
   colorWarnings?: string[];
-  /** Inline themes: theme name → slot name → resolved hex color (only when tokensSource === 'inline') */
+  /** Inline themes: theme name → slot name → resolved hex color */
   themes?: Record<string, Record<string, string>>;
   /** Print annotations from inline # comments: slot name → annotation text */
   themeDescriptions?: Record<string, string>;
-  /** Spacing scale (only when tokensSource === 'inline') */
+  /** Spacing scale */
   spacing?: { unit: string; xs: number; s: number; m: number; l: number; xl: number };
   /** Divider style definitions: name → divider config */
   dividers?: Record<string, ParsedDividerDef>;
@@ -450,10 +436,7 @@ export function parseBrandFile(content: string, fileName: string): ParsedBrand {
     return { slot, value, line: lineNum };
   };
 
-  const result: Partial<ParsedBrand> = {
-    tokensFile: 'tokens.json',
-    tokensSource: 'figma',
-  };
+  const result: Partial<ParsedBrand> = {};
 
   type ActiveBlock = 'none' | 'brand-colors' | 'state-colors' | 'color-bounds' | 'color-adherence' | 'color-rules' | 'tones' | 'levels' | 'color-families' | 'theme' | 'spacing' | 'divider' | 'typography' | 'font' | 'logo' | 'photo' | 'video' | 'illustration' | 'label' | 'cta' | 'icons' | 'counter' | 'framing' | 'camera' | 'photo-look' | 'windows';
   let activeBlock: ActiveBlock = 'none';
@@ -1164,19 +1147,6 @@ export function parseBrandFile(content: string, fileName: string): ParsedBrand {
       case 'name':         result.name = value; break;
       case 'language':     result.language = value; break;
       case 'locale':       result.locale = value; break;
-      case 'tokens':
-        if (value === 'figma' || value === 'inline') {
-          result.tokensSource = value;
-        } else {
-          console.warn(`${fileName}:${lineNum}: unknown tokens source "${value}", defaulting to "figma"`);
-        }
-        break;
-      case 'figma-file-key':    result.figmaFileKey = value; break;
-      case 'figma-collection':  result.figmaCollection = value; break;
-      case 'tokens-file':       result.tokensFile = value; break;
-      case 'app-icon':          result.appIcon = value; break;
-      case 'favicon':           result.favicon = value; break;
-      case 'og-image':          result.ogImage = value; break;
       case 'spacing':
         activeBlock = 'spacing';
         break;

package/parser/purposeParser.ts

@@ -37,6 +37,8 @@ export interface ParsedPurpose {
   defaultPhoto?: string;
   /** Default video asset ID — pre-selects this video on page creation. */
   defaultVideo?: string;
+  /** Illustration ids a new page picks from; a .story page's `illustration:` overrides them. */
+  illustrations?: string[];
   /** When false, hides Take Photo / Upload buttons for this purpose. Default: true. */
   camera?: boolean;
   /** `camera: front | rear` — overrides the brand's camera facing for this purpose. */
@@ -170,6 +172,7 @@ export function parsePurposeFile(content: string, fileName: string): ParsedPurpo
   let defaultLogo: string | undefined;
   let defaultPhoto: string | undefined;
   let defaultVideo: string | undefined;
+  let illustrations: string[] | undefined;
   let camera: boolean | undefined;
   let cameraFacing: 'front' | 'rear' | undefined;
   let framing: string | undefined;
@@ -422,6 +425,12 @@ export function parsePurposeFile(content: string, fileName: string): ParsedPurpo
       continue;
     }
 
+    // Illustrations a new page picks from
+    if (line.startsWith('illustration:')) {
+      illustrations = line.slice(13).split(',').map(id => id.trim()).filter(Boolean);
+      continue;
+    }
+
     // Camera control
     if (line.startsWith('camera:')) {
       const value = line.slice(7).trim();
@@ -788,7 +797,7 @@ export function parsePurposeFile(content: string, fileName: string): ParsedPurpo
 
   const parsedExamples = resolveExamples(examples, slots, legacySamplesLine, fileName, warnings);
 
-  return { id, name, description, preferredCompositions: compositions, slots, density, palette, scope, context, voice, defaultLogo, defaultPhoto, defaultVideo, camera, cameraFacing, framing, goal, analyze, defaultIcon, bgPrompt, examples: parsedExamples, warnings };
+  return { id, name, description, preferredCompositions: compositions, slots, density, palette, scope, context, voice, defaultLogo, defaultPhoto, defaultVideo, illustrations, camera, cameraFacing, framing, goal, analyze, defaultIcon, bgPrompt, examples: parsedExamples, warnings };
 }
 
 /** Validate `example` blocks against the declared slots, or build examples from deprecated slot

package/parser/storyParser.ts

@@ -38,6 +38,8 @@ export interface ParsedStoryPage {
   purpose: string;
   /** Composition id; undefined = the implementation picks one of the purpose's compositions. */
   composition?: string;
+  /** Illustration ids; implementations pick one per story date, the same one every time for that date. */
+  illustrations?: string[];
   /** Page topic: what this page adds to the story. */
   topic?: string;
   /** Fixed slot texts, may contain `{variable}`s. A slot the page doesn't name is open. */
@@ -190,9 +192,10 @@ export function parseStoryFile(content: string, fileName: string): ParsedStory {
     // Page lines (2-space)
     if (currentPage) {
       if (indent !== 2) throw new Error(`${fileName}:${lineNum}: unexpected indent in page (page keys use 2 spaces)`);
-      const read = readKey(line, lineNum, currentPage, ['purpose', 'composition'], true);
+      const read = readKey(line, lineNum, currentPage, ['purpose', 'composition', 'illustration'], true);
       if (read && 'multi' in read) { multiKey = read.multi; multiIndent = 4; }
       else if (read?.key === 'purpose') currentPage.purpose = read.value;
+      else if (read?.key === 'illustration') currentPage.illustrations = read.value.split(',').map(id => id.trim()).filter(Boolean);
       else if (read) currentPage.composition = read.value;
       continue;
     }
@@ -278,7 +281,7 @@ export function parseStoryFile(content: string, fileName: string): ParsedStory {
  *  empty when the story fits. Variables count at their longest form for `maxLength`. */
 export function checkStory(
   story: ParsedStory,
-  brand: { purposes: ParsedPurpose[]; compositions: string[]; formats: string[] },
+  brand: { purposes: ParsedPurpose[]; compositions: string[]; formats: string[]; illustrations?: string[] },
   fileName: string,
 ): string[] {
   const problems: string[] = [];
@@ -308,6 +311,9 @@ export function checkStory(
       if (!brand.compositions.includes(page.composition)) say(`${where}: composition "${page.composition}" does not exist`);
       else if (!purpose.preferredCompositions.includes(page.composition)) say(`${where}: composition "${page.composition}" is not one of purpose "${purpose.id}"'s compositions`);
     }
+    for (const id of page.illustrations ?? []) {
+      if (brand.illustrations && !brand.illustrations.includes(id)) say(`${where}: illustration "${id}" does not exist`);
+    }
     checkTexts(where, purpose, page.texts);
   });
   story.examples.forEach((ex, i) => {

package/vscode-extension/syntaxes/brand.tmLanguage.json

@@ -6,7 +6,6 @@
     { "include": "#comment" },
     { "include": "#id-field" },
     { "include": "#name-field" },
-    { "include": "#tokens-enum" },
     { "include": "#brand-colors-header" },
     { "include": "#state-colors-header" },
     { "include": "#color-bounds-header" },
@@ -80,13 +79,6 @@
         "2": { "name": "string.unquoted.brand-intent-brand" }
       }
     },
-    "tokens-enum": {
-      "match": "^(tokens:)\\s+(figma|inline)",
-      "captures": {
-        "1": { "name": "keyword.control.brand-intent-brand" },
-        "2": { "name": "entity.name.tag.brand-intent-brand" }
-      }
-    },
     "brand-colors-header": {
       "match": "^(brand-colors)\\s*$",
       "captures": {
@@ -535,7 +527,7 @@
       }
     },
     "string-field": {
-      "match": "^(language|locale|app-icon|favicon|og-image|figma-file-key|figma-collection|tokens-file|spacing):?\\s*(.+)?",
+      "match": "^(language|locale|spacing):?\\s*(.+)?",
       "captures": {
         "1": { "name": "support.type.property-name.brand-intent-brand" },
         "2": { "name": "string.unquoted.brand-intent-brand" }
@@ -543,7 +535,7 @@
     },
     "keyword-partial": {
       "comment": "Fallback: color the keyword token on incomplete lines (while typing)",
-      "match": "^(id:|name:|language:|locale:|app-icon:|favicon:|og-image:|tokens:|figma-file-key:|figma-collection:|tokens-file:|spacing:|label:|cta:|color-mode:|color-strategy:|color-adherence:|brand-colors|state-colors|color-bounds|color-rules|color-families|theme|divider|font|typography|logo|photo|video|illustration|icons|counter|framing|windows)(?=\\s|$)",
+      "match": "^(id:|name:|language:|locale:|spacing:|label:|cta:|color-mode:|color-strategy:|color-adherence:|brand-colors|state-colors|color-bounds|color-rules|color-families|theme|divider|font|typography|logo|photo|video|illustration|icons|counter|framing|windows)(?=\\s|$)",
       "captures": {
         "1": { "name": "keyword.control.brand-intent-brand" }
       }

package/vscode-extension/syntaxes/purpose.tmLanguage.json

@@ -110,7 +110,7 @@
       ]
     },
     "asset-field": {
-      "match": "^(logo:|photo:|video:)\\s+([\\w-]+)",
+      "match": "^(logo:|photo:|video:|illustration:)\\s+([\\w, -]+)",
       "captures": {
         "1": { "name": "keyword.control.brand-intent-purpose" },
         "2": { "name": "entity.name.type.brand-intent-purpose" }
@@ -265,7 +265,7 @@
       "comment": "Fallback: color the keyword token on incomplete lines (while typing)",
       "patterns": [
         {
-          "match": "^(id:|name:|compositions:|density:|defaultIcon:|scope|voice|palette:|logo:|photo:|video:|camera:|framing:|goal:|analyze:|bg-prompt:|context|slot|example)(?=\\s|$)",
+          "match": "^(id:|name:|compositions:|density:|defaultIcon:|scope|voice|palette:|logo:|photo:|video:|illustration:|camera:|framing:|goal:|analyze:|bg-prompt:|context|slot|example)(?=\\s|$)",
           "captures": {
             "1": { "name": "keyword.control.brand-intent-purpose" }
           }

package/vscode-extension/syntaxes/story.tmLanguage.json

@@ -37,7 +37,7 @@
       }
     },
     "reference": {
-      "match": "^\\s+(purpose|composition)(:)\\s+([\\w:-]+)",
+      "match": "^\\s+(purpose|composition|illustration)(:)\\s+([\\w:, -]+)",
       "captures": {
         "1": { "name": "support.type.property-name.brand-intent-story" },
         "2": { "name": "punctuation.separator.brand-intent-story" },
@@ -66,7 +66,7 @@
           }
         },
         {
-          "match": "^\\s+(purpose|composition|topic|primary|secondary|detail|meta|cta|label)(?=:|\\s|$)",
+          "match": "^\\s+(purpose|composition|illustration|topic|primary|secondary|detail|meta|cta|label)(?=:|\\s|$)",
           "captures": {
             "1": { "name": "support.type.property-name.brand-intent-story" }
           }