brand-intent 0.3.2 → 0.4.1

package/package.json

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

package/parser/brandParser.ts

@@ -45,8 +45,8 @@ export interface ParsedBrand {
   dividers?: Record<string, ParsedDividerDef>;
   /** Named typography styles: name → style definition */
   typographies?: Record<string, ParsedTypographyDef>;
-  /** Brand-declared assets: curated logos, photos, videos with labels and metadata */
-  assets?: { logos?: ParsedAssetDef[]; photos?: ParsedAssetDef[]; videos?: ParsedAssetDef[] };
+  /** Brand-declared assets: curated logos, photos, videos, illustrations with labels and metadata */
+  assets?: { logos?: ParsedAssetDef[]; photos?: ParsedAssetDef[]; videos?: ParsedAssetDef[]; illustrations?: ParsedAssetDef[] };
   /** Label badge style — padding (top/right/bottom/left in cqh) and corner radius (cqh) */
   label?: ParsedBadgeStyle;
   /** CTA pill style — padding (top/right/bottom/left in cqh) and corner radius (cqh, or 999 for full pill) */
@@ -146,7 +146,7 @@ export function parseBrandFile(content: string, fileName: string): ParsedBrand {
     tokensSource: 'figma',
   };
 
-  type ActiveBlock = 'none' | 'brand-colors' | 'theme' | 'spacing' | 'divider' | 'typography' | 'font' | 'logo' | 'photo' | 'video' | 'label' | 'cta';
+  type ActiveBlock = 'none' | 'brand-colors' | 'theme' | 'spacing' | 'divider' | 'typography' | 'font' | 'logo' | 'photo' | 'video' | 'illustration' | 'label' | 'cta';
   let activeBlock: ActiveBlock = 'none';
   let currentThemeName = '';
   let currentDividerName = '';
@@ -164,6 +164,7 @@ export function parseBrandFile(content: string, fileName: string): ParsedBrand {
   const logosRaw: Array<{ id: string; props: Record<string, string> }> = [];
   const photosRaw: Array<{ id: string; props: Record<string, string> }> = [];
   const videosRaw: Array<{ id: string; props: Record<string, string> }> = [];
+  const illustrationsRaw: Array<{ id: string; props: Record<string, string> }> = [];
   let currentAssetId = '';
   const labelRaw: Record<string, string> = {};
   const ctaRaw: Record<string, string> = {};
@@ -264,18 +265,18 @@ export function parseBrandFile(content: string, fileName: string): ParsedBrand {
         }
         continue;
       }
-      if ((activeBlock === 'logo' || activeBlock === 'photo' || activeBlock === 'video') && currentAssetId) {
+      if ((activeBlock === 'logo' || activeBlock === 'photo' || activeBlock === 'video' || activeBlock === 'illustration') && currentAssetId) {
         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 : videosRaw;
+          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;
         } else {
           const trimmed = raw.trim();
           if (trimmed === 'animated' || trimmed === 'loop') {
-            const arr = activeBlock === 'logo' ? logosRaw : activeBlock === 'photo' ? photosRaw : videosRaw;
+            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';
           }
@@ -341,13 +342,13 @@ export function parseBrandFile(content: string, fileName: string): ParsedBrand {
       continue;
     }
 
-    // logo/photo/video <id> — starts an asset block
-    const assetMatch = raw.match(/^(logo|photo|video)\s+(\S+)/);
+    // logo/photo/video/illustration <id> — starts an asset block
+    const assetMatch = raw.match(/^(logo|photo|video|illustration)\s+(\S+)/);
     if (assetMatch) {
       const [, type, id] = assetMatch;
       currentAssetId = id;
-      activeBlock = type as 'logo' | 'photo' | 'video';
-      const arr = type === 'logo' ? logosRaw : type === 'photo' ? photosRaw : videosRaw;
+      activeBlock = type as 'logo' | 'photo' | 'video' | 'illustration';
+      const arr = type === 'logo' ? logosRaw : type === 'photo' ? photosRaw : type === 'video' ? videosRaw : illustrationsRaw;
       arr.push({ id, props: {} });
       continue;
     }
@@ -510,11 +511,12 @@ export function parseBrandFile(content: string, fileName: string): ParsedBrand {
     if (raw.props['loop'] === 'true') def.loop = true;
     return def;
   };
-  if (logosRaw.length > 0 || photosRaw.length > 0 || videosRaw.length > 0) {
+  if (logosRaw.length > 0 || photosRaw.length > 0 || videosRaw.length > 0 || illustrationsRaw.length > 0) {
     result.assets = {};
     if (logosRaw.length > 0) result.assets.logos = logosRaw.map(toAssetDef);
     if (photosRaw.length > 0) result.assets.photos = photosRaw.map(toAssetDef);
     if (videosRaw.length > 0) result.assets.videos = videosRaw.map(toAssetDef);
+    if (illustrationsRaw.length > 0) result.assets.illustrations = illustrationsRaw.map(toAssetDef);
   }
 
   // Finalise label / cta badge styles

package/parser/compositionParser.ts

@@ -22,6 +22,26 @@ export interface ParsedImageRegion {
   colEnd?: number;    // 0-based column (undefined = full width)
 }
 
+/** Anchor keywords for illustration placement. */
+export type IllustrationAnchor =
+  | 'top-left' | 'top-center' | 'top-right'
+  | 'center-left' | 'center' | 'center-right'
+  | 'bottom-left' | 'bottom-center' | 'bottom-right';
+
+/** Parsed illustration placement from `illustration:` line. */
+export interface ParsedIllustration {
+  anchor: IllustrationAnchor;
+  fit: 'width' | 'height';
+  /** Scale as fraction 0–1 (e.g. 0.9 = 90% of canvas dimension). */
+  scale: number;
+}
+
+const ILLUSTRATION_ANCHORS = new Set<string>([
+  'top-left', 'top-center', 'top-right',
+  'center-left', 'center', 'center-right',
+  'bottom-left', 'bottom-center', 'bottom-right',
+]);
+
 export interface ParsedComposition {
   /** Programmatic ID (from `id:` line, or fallback from first `#` line). */
   id: string;
@@ -44,6 +64,8 @@ export interface ParsedComposition {
   sticky: ParsedStickyRegion[];
   /** Flow regions — content-driven flow areas. */
   flow: ParsedFlowRegion | null;
+  /** Illustration placement (grid mode only for now). */
+  illustration?: ParsedIllustration;
 }
 
 /** A sticky (repetition) region — composed elements that don't participate in flow. */
@@ -179,6 +201,7 @@ export function parseCompositionFile(content: string, fileName: string): ParsedC
   const slots: ParsedSlot[] = [];
   const sticky: ParsedStickyRegion[] = [];
   let flow: ParsedFlowRegion | null = null;
+  let illustration: ParsedIllustration | undefined = undefined;
 
   /** Parse a fraction string like "2/3" → 0.667. */
   function parseFraction(s: string, ctx: string): number {
@@ -260,6 +283,23 @@ export function parseCompositionFile(content: string, fileName: string): ParsedC
       continue;
     }
 
+    // Illustration placement: "illustration: bottom-center fit-width 90%"
+    if (line.startsWith('illustration:')) {
+      const parts = line.slice(13).trim().split(/\s+/);
+      if (parts.length < 3) throw new Error(`${fileName}:${lineNum}: invalid illustration line — expected "illustration: <anchor> <fit-width|fit-height> <N%>"`);
+      const anchor = parts[0];
+      if (!ILLUSTRATION_ANCHORS.has(anchor)) throw new Error(`${fileName}:${lineNum}: invalid illustration anchor "${anchor}" (expected ${[...ILLUSTRATION_ANCHORS].join(', ')})`);
+      const fitStr = parts[1];
+      if (fitStr !== 'fit-width' && fitStr !== 'fit-height') throw new Error(`${fileName}:${lineNum}: invalid illustration fit "${fitStr}" (expected fit-width or fit-height)`);
+      const scaleStr = parts[2];
+      const scaleMatch = scaleStr.match(/^(\d+(?:\.\d+)?)%$/);
+      if (!scaleMatch) throw new Error(`${fileName}:${lineNum}: invalid illustration scale "${scaleStr}" (expected e.g. "90%")`);
+      const scale = parseFloat(scaleMatch[1]) / 100;
+      if (scale <= 0 || scale > 2) throw new Error(`${fileName}:${lineNum}: illustration scale out of range (expected 1%–200%)`);
+      illustration = { anchor: anchor as IllustrationAnchor, fit: fitStr === 'fit-width' ? 'width' : 'height', scale };
+      continue;
+    }
+
     // grid: is no longer used in layout files (format owns the grid). Silently skip.
     if (line.startsWith('grid:')) {
       console.warn(`${fileName}:${lineNum}: "grid:" in layout files is no longer needed — format defines the grid`);
@@ -512,5 +552,5 @@ export function parseCompositionFile(content: string, fileName: string): ParsedC
   // Validate required fields
   if (!image) image = 'full'; // default to full-bleed image
   if (!logo && !logoNone && !sticky.length) throw new Error(`${fileName}: missing "logo:" line (or use sticky: block)`);
-  return { id, name, description, mode, image, imageExplicit, logo, logoNone: logoNone || undefined, icon, slots, sticky, flow };
+  return { id, name, description, mode, image, imageExplicit, logo, logoNone: logoNone || undefined, icon, slots, sticky, flow, illustration };
 }

package/parser/index.ts

@@ -21,6 +21,8 @@ export type {
   ParsedStickyRegion,
   ParsedFlowItem,
   ParsedImageRegion,
+  ParsedIllustration,
+  IllustrationAnchor,
   GridYKeyword,
 } from './compositionParser';