brand-intent 0.12.1 → 0.14.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "brand-intent",
-  "version": "0.12.1",
+  "version": "0.14.0",
   "description": "An open file format specification for making brand intent machine-readable.",
   "author": "Christophe Stoll <christophe@stoll.studio>",
   "license": "MIT",
@@ -35,7 +35,7 @@
   ],
   "scripts": {
     "release": "./scripts/release.sh",
-    "test": "tsx tests/brandParser.test.ts && tsx tests/identityParser.test.ts && tsx tests/colorSystem.test.ts && tsx tests/realBrands.test.ts"
+    "test": "tsx tests/brandParser.test.ts && tsx tests/identityParser.test.ts && tsx tests/colorSystem.test.ts && tsx tests/icons.test.ts && tsx tests/purposeParser.test.ts && tsx tests/realBrands.test.ts"
   },
   "devDependencies": {
     "tsx": "^4.19.0"

package/parser/brandParser.ts

@@ -36,6 +36,8 @@ import {
   checkFamilyPair,
   reachCoversAll,
 } from './colorSystem';
+import { parseIconSource, isIconId } from './icons';
+import type { ParsedIconDef } from './icons';
 
 // ── Parsed type ────────────────────────────────────────────────────────────────
 
@@ -106,6 +108,26 @@ export interface ParsedBrand {
   label?: ParsedBadgeStyle;
   /** CTA pill style — padding (top/right/bottom/left in cqh) and corner radius (cqh, or 999 for full pill) */
   cta?: ParsedBadgeStyle;
+  /** Brand icon set (`icons` block), in declaration order. Absent → the brand has no set. */
+  icons?: ParsedIconDef[];
+  /** List counter component (`counter` block). */
+  counter?: ParsedCounterDef;
+}
+
+export type CounterFormat = '1' | '01' | '1.' | '(1)' | 'i';
+export type CounterShape = 'none' | 'circle' | 'square' | 'pill';
+
+export interface ParsedCounterDef {
+  /** Number format: 1 | 01 | 1. | (1) | i (lowercase roman). */
+  format: CounterFormat;
+  /** Typography style for the digits. Absent → the list item's typography. */
+  typography?: string;
+  /** Background shape, coloured with the theme's counter-bg / counter-fg. */
+  shape: CounterShape;
+  /** Counter height in em, relative to the list item text. */
+  size: number;
+  /** Inner padding in em. */
+  padding: number;
 }
 
 export interface ParsedAssetDef {
@@ -329,7 +351,7 @@ export function parseBrandFile(content: string, fileName: string): ParsedBrand {
     tokensSource: 'figma',
   };
 
-  type ActiveBlock = 'none' | 'brand-colors' | 'state-colors' | 'color-bounds' | 'color-adherence' | 'color-rules' | 'color-families' | 'theme' | 'spacing' | 'divider' | 'typography' | 'font' | 'logo' | 'photo' | 'video' | 'illustration' | 'label' | 'cta';
+  type ActiveBlock = 'none' | 'brand-colors' | 'state-colors' | 'color-bounds' | 'color-adherence' | 'color-rules' | 'color-families' | 'theme' | 'spacing' | 'divider' | 'typography' | 'font' | 'logo' | 'photo' | 'video' | 'illustration' | 'label' | 'cta' | 'icons' | 'counter';
   let activeBlock: ActiveBlock = 'none';
   let currentThemeName = '';
   let currentDividerName = '';
@@ -372,6 +394,10 @@ export function parseBrandFile(content: string, fileName: string): ParsedBrand {
   let currentSubBlock: string | null = null;
   const labelRaw: Record<string, string> = {};
   const ctaRaw: Record<string, string> = {};
+  const icons: ParsedIconDef[] = [];
+  let iconsDeclared = false;
+  const counterRaw: Record<string, { value: string; line: number }> = {};
+  let counterDeclared = false;
 
   for (let i = 0; i < lines.length; i++) {
     const raw = lines[i];
@@ -718,6 +744,29 @@ export function parseBrandFile(content: string, fileName: string): ParsedBrand {
         }
         continue;
       }
+      if (activeBlock === 'icons') {
+        const trimmed = raw.trim();
+        if (trimmed.startsWith('#')) continue;
+        const commentIdx = trimmed.search(/\s+#/);
+        const entry = commentIdx !== -1 ? trimmed.slice(0, commentIdx) : trimmed;
+        const colonIdx = entry.indexOf(':');
+        if (colonIdx === -1) throw new Error(`${fileName}:${lineNum}: icons entry must be "ID: SOURCE", got "${trimmed}"`);
+        const id = entry.slice(0, colonIdx).trim();
+        if (!isIconId(id)) throw new Error(`${fileName}:${lineNum}: invalid icon id "${id}" — use lowercase kebab-case`);
+        if (icons.some(ic => ic.id === id)) throw new Error(`${fileName}:${lineNum}: duplicate icon "${id}"`);
+        icons.push({ id, source: parseIconSource(entry.slice(colonIdx + 1), `${fileName}:${lineNum}`) });
+        continue;
+      }
+      if (activeBlock === 'counter') {
+        const trimmed = raw.trim();
+        if (trimmed.startsWith('#')) continue;
+        const commentIdx = trimmed.search(/\s+#/);
+        const entry = commentIdx !== -1 ? trimmed.slice(0, commentIdx) : trimmed;
+        const colonIdx = entry.indexOf(':');
+        if (colonIdx === -1) throw new Error(`${fileName}:${lineNum}: counter property must be "KEY: VALUE", got "${trimmed}"`);
+        counterRaw[entry.slice(0, colonIdx).trim()] = { value: entry.slice(colonIdx + 1).trim(), line: lineNum };
+        continue;
+      }
       // Indented line with no active block — ignore
       continue;
     }
@@ -766,6 +815,22 @@ export function parseBrandFile(content: string, fileName: string): ParsedBrand {
       continue;
     }
 
+    // icons — the brand icon set
+    if (raw.trim() === 'icons') {
+      if (iconsDeclared) throw new Error(`${fileName}:${lineNum}: duplicate icons block`);
+      iconsDeclared = true;
+      activeBlock = 'icons';
+      continue;
+    }
+
+    // counter — list counter component
+    if (raw.trim() === 'counter') {
+      if (counterDeclared) throw new Error(`${fileName}:${lineNum}: duplicate counter block`);
+      counterDeclared = true;
+      activeBlock = 'counter';
+      continue;
+    }
+
     // theme ThemeName — starts a theme block
     const themeMatch = raw.match(/^theme\s+(\S+)/);
     if (themeMatch) {
@@ -1182,6 +1247,12 @@ export function parseBrandFile(content: string, fileName: string): ParsedBrand {
     });
   }
 
+  // Counter colours default to the label badge's.
+  for (const theme of Object.values(themes)) {
+    if (theme['counter-bg'] === undefined && theme['label-bg'] !== undefined) theme['counter-bg'] = theme['label-bg'];
+    if (theme['counter-fg'] === undefined && theme['label-fg'] !== undefined) theme['counter-fg'] = theme['label-fg'];
+  }
+
   // Rule checks on every theme (only when the brand declares color-rules).
   if (colorRulesDeclared) {
     for (const [name, theme] of Object.entries(themes)) {
@@ -1349,6 +1420,59 @@ export function parseBrandFile(content: string, fileName: string): ParsedBrand {
     result.cta = parseBadgeStyle(ctaRaw, { padding: [0.8, 2.5, 0.8, 2.5], radius: 999 });
   }
 
+  // Finalise icon set — font glyphs need a declared font (bare `font U+…` → first font).
+  if (iconsDeclared) {
+    if (icons.length === 0) throw new Error(`${fileName}: icons block is empty`);
+    const fontNames = Object.keys(result.fonts ?? {});
+    for (const icon of icons) {
+      if (icon.source.kind !== 'font') continue;
+      if (!icon.source.font) {
+        if (fontNames.length === 0) throw new Error(`${fileName}: icon "${icon.id}" uses a font glyph, but no font block is declared`);
+        icon.source.font = fontNames[0];
+      } else if (!fontNames.includes(icon.source.font)) {
+        throw new Error(`${fileName}: icon "${icon.id}" references unknown font "$${icon.source.font}"`);
+      }
+    }
+    result.icons = icons;
+  }
+
+  // Finalise counter component
+  if (counterDeclared) {
+    const known = new Set(['format', 'typography', 'shape', 'size', 'padding']);
+    for (const [key, { line }] of Object.entries(counterRaw)) {
+      if (!known.has(key)) throw new Error(`${fileName}:${line}: unknown counter property "${key}"`);
+    }
+    const formats: CounterFormat[] = ['1', '01', '1.', '(1)', 'i'];
+    const shapes: CounterShape[] = ['none', 'circle', 'square', 'pill'];
+    const em = (key: string, fallback: number): number => {
+      const entry = counterRaw[key];
+      if (!entry) return fallback;
+      const m = entry.value.match(/^(\d+(?:\.\d+)?)(?:em)?$/);
+      if (!m) throw new Error(`${fileName}:${entry.line}: counter ${key} must be a number in em (e.g. "1.2em"), got "${entry.value}"`);
+      return parseFloat(m[1]);
+    };
+    const format = counterRaw['format']?.value ?? '1';
+    if (!formats.includes(format as CounterFormat)) {
+      throw new Error(`${fileName}:${counterRaw['format'].line}: counter format must be one of ${formats.join(' | ')}, got "${format}"`);
+    }
+    const shape = counterRaw['shape']?.value ?? 'circle';
+    if (!shapes.includes(shape as CounterShape)) {
+      throw new Error(`${fileName}:${counterRaw['shape'].line}: counter shape must be one of ${shapes.join(' | ')}, got "${shape}"`);
+    }
+    const counter: ParsedCounterDef = {
+      format: format as CounterFormat,
+      shape: shape as CounterShape,
+      size: em('size', 1),
+      padding: em('padding', 0.2),
+    };
+    const typo = counterRaw['typography'];
+    if (typo) {
+      if (!result.typographies?.[typo.value]) throw new Error(`${fileName}:${typo.line}: counter typography "${typo.value}" is not a declared typography`);
+      counter.typography = typo.value;
+    }
+    result.counter = counter;
+  }
+
   // Validate required fields
   const required: (keyof ParsedBrand)[] = ['id', 'name', 'language', 'locale'];
   for (const field of required) {

package/parser/colorSystem.ts

@@ -102,11 +102,12 @@ export function derivePairSlots(ground: string, figure: string, text: string): R
     'text-primary': text,
   };
   for (const [slot, alpha] of TEXT_TIERS) slots[slot] = withAlpha(text, alpha);
-  for (const slot of ['logo', 'cta', 'divider', 'icon', 'illustration', 'sticker-bg', 'label-bg']) {
+  for (const slot of ['logo', 'cta', 'divider', 'icon', 'illustration', 'sticker-bg', 'label-bg', 'counter-bg']) {
     slots[slot] = figure;
   }
   slots['sticker-fg'] = ground;
   slots['label-fg'] = ground;
+  slots['counter-fg'] = ground;
   return slots;
 }
 

package/parser/icons.ts

@@ -0,0 +1,140 @@
+/**
+ * Icons: brand icon sets (`icons` block in .brand) and icon references
+ * (`defaultIcon:` and `[id]` list-sample prefixes in .purpose).
+ *
+ * A reference resolves in the brand set first, then as a Phosphor name.
+ * `phosphor:NAME` skips the brand set.
+ */
+
+export const PHOSPHOR_WEIGHTS = ['thin', 'light', 'regular', 'bold', 'fill', 'duotone'] as const;
+export type PhosphorWeight = typeof PHOSPHOR_WEIGHTS[number];
+
+/** Where a brand icon comes from. */
+export type IconSource =
+  /** Glyph in a brand font. `font` is the font block name; exactly one of codepoint / glyph is set. */
+  | { kind: 'font'; font: string; codepoint?: number; glyph?: string }
+  /** SVG file, relative to the brand folder. */
+  | { kind: 'svg'; src: string }
+  /** Phosphor icon adopted into the set. `name` is PascalCase (e.g. "MapPin"). */
+  | { kind: 'phosphor'; name: string; weight?: PhosphorWeight };
+
+export interface ParsedIconDef {
+  /** Semantic id, e.g. "quote", "pin". */
+  id: string;
+  source: IconSource;
+}
+
+/** Icon reference from a .purpose file. */
+export interface IconRef {
+  /** Icon id as written, kebab-case (e.g. "quote", "map-pin"). */
+  id: string;
+  /** Set when written as `phosphor:NAME` — skips the brand set. */
+  library?: 'phosphor';
+  /** Phosphor weight. Only meaningful when the reference resolves to Phosphor. */
+  weight?: PhosphorWeight;
+}
+
+export type ResolvedIcon =
+  | { kind: 'brand'; icon: ParsedIconDef }
+  | { kind: 'phosphor'; name: string; weight?: PhosphorWeight };
+
+const ICON_ID = /^[a-z][a-z0-9-]*$/;
+
+/** "map-pin" → "MapPin" */
+export function phosphorName(id: string): string {
+  return id.split('-').map(w => w.charAt(0).toUpperCase() + w.slice(1)).join('');
+}
+
+function parseWeight(value: string, where: string): PhosphorWeight {
+  if (!(PHOSPHOR_WEIGHTS as readonly string[]).includes(value)) {
+    throw new Error(`${where}: invalid icon weight "${value}" — expected ${PHOSPHOR_WEIGHTS.join(', ')}`);
+  }
+  return value as PhosphorWeight;
+}
+
+/** Parse `quote`, `map-pin bold`, `phosphor:quotes duotone`. */
+export function parseIconRef(value: string, where: string): IconRef {
+  const parts = value.trim().split(/\s+/);
+  if (parts.length === 0 || parts.length > 2 || !parts[0]) {
+    throw new Error(`${where}: invalid icon reference "${value}" — expected "ID [WEIGHT]" or "phosphor:ID [WEIGHT]"`);
+  }
+  let id = parts[0];
+  let library: IconRef['library'];
+  if (id.startsWith('phosphor:')) {
+    library = 'phosphor';
+    id = id.slice(9);
+  }
+  if (!ICON_ID.test(id)) {
+    throw new Error(`${where}: invalid icon id "${id}" — use lowercase kebab-case (e.g. "map-pin")`);
+  }
+  const ref: IconRef = { id };
+  if (library) ref.library = library;
+  if (parts[1]) ref.weight = parseWeight(parts[1], where);
+  return ref;
+}
+
+/**
+ * Parse one entry of the `icons` block (the part after `ID:`):
+ *   font $display U+201C   glyph by codepoint
+ *   font $display icon.pin glyph by name
+ *   font U+201C            glyph in the default (first) font
+ *   icons/map.svg          brand SVG
+ *   phosphor wave light    Phosphor icon adopted into the set
+ * Font names are checked later, once all font blocks are known.
+ */
+export function parseIconSource(value: string, where: string): IconSource {
+  const parts = value.trim().split(/\s+/);
+  if (parts[0] === 'font') {
+    const rest = parts.slice(1);
+    if (rest.length === 0 || rest.length > 2) {
+      throw new Error(`${where}: font icon must be "font [$FONT] U+XXXX" or "font [$FONT] GLYPHNAME"`);
+    }
+    let font = '';
+    if (rest.length === 2) {
+      if (!rest[0].startsWith('$')) throw new Error(`${where}: font reference must start with "$" (e.g. "$display"), got "${rest[0]}"`);
+      font = rest[0].slice(1);
+    }
+    const glyphRef = rest[rest.length - 1];
+    const cp = glyphRef.match(/^U\+([0-9A-Fa-f]{4,6})$/);
+    if (cp) return { kind: 'font', font, codepoint: parseInt(cp[1], 16) };
+    if (/^U\+/i.test(glyphRef)) throw new Error(`${where}: invalid codepoint "${glyphRef}" — expected U+ and 4–6 hex digits`);
+    return { kind: 'font', font, glyph: glyphRef };
+  }
+  if (parts[0] === 'phosphor') {
+    if (parts.length < 2 || parts.length > 3) throw new Error(`${where}: phosphor icon must be "phosphor NAME [WEIGHT]"`);
+    if (!ICON_ID.test(parts[1])) throw new Error(`${where}: invalid Phosphor name "${parts[1]}" — use kebab-case (e.g. "map-pin")`);
+    const source: IconSource = { kind: 'phosphor', name: phosphorName(parts[1]) };
+    if (parts[2]) source.weight = parseWeight(parts[2], where);
+    return source;
+  }
+  if (parts.length === 1 && parts[0].toLowerCase().endsWith('.svg')) {
+    return { kind: 'svg', src: parts[0] };
+  }
+  throw new Error(`${where}: invalid icon source "${value}" — expected "font …", "phosphor …" or a path to an .svg file`);
+}
+
+/** Parse the icon id at the start of an `icons` block line. */
+export function isIconId(id: string): boolean {
+  return ICON_ID.test(id);
+}
+
+/**
+ * Resolve a reference against a brand's icon set.
+ * Brand set first, then Phosphor. Whether the Phosphor name exists is up to the consumer.
+ */
+export function resolveIconRef(ref: IconRef, icons: ParsedIconDef[] | undefined): ResolvedIcon {
+  if (!ref.library) {
+    const icon = icons?.find(i => i.id === ref.id);
+    if (icon) return { kind: 'brand', icon };
+  }
+  const resolved: ResolvedIcon = { kind: 'phosphor', name: phosphorName(ref.id) };
+  if (ref.weight) resolved.weight = ref.weight;
+  return resolved;
+}
+
+/** Split an optional `[id]` prefix off a list item: "[pin] Hafen Burgstaaken". */
+export function parseListItem(item: string): { icon?: IconRef; text: string } {
+  const m = item.match(/^\[([^\]]+)\]\s*(.*)$/s);
+  if (!m) return { text: item };
+  return { icon: parseIconRef(m[1], `list item "${item}"`), text: m[2] };
+}

package/parser/index.ts

@@ -23,7 +23,10 @@ export {
   DEFAULT_COLOR_RULES,
 } from './colorSystem';
 export type { ReachConfig } from './colorSystem';
-export type { ParsedBrand, ParsedFontDef, ParsedTypographyDef, ParsedDividerDef, BrandColorPrintSpec, ParsedAssetDef, ParsedBadgeStyle, LogoAlign } from './brandParser';
+export type { ParsedBrand, ParsedFontDef, ParsedTypographyDef, ParsedDividerDef, BrandColorPrintSpec, ParsedAssetDef, ParsedBadgeStyle, LogoAlign, ParsedCounterDef, CounterFormat, CounterShape } from './brandParser';
+
+export { parseIconRef, parseIconSource, resolveIconRef, parseListItem, phosphorName, PHOSPHOR_WEIGHTS } from './icons';
+export type { IconRef, IconSource, ParsedIconDef, ResolvedIcon, PhosphorWeight } from './icons';
 export type {
   ColorMode,
   PaletteStrategy,
@@ -54,7 +57,7 @@ export { parseFormatFile } from './formatParser';
 export type { ParsedFormat } from './formatParser';
 
 export { parsePurposeFile } from './purposeParser';
-export type { ParsedPurpose, ParsedPurposeSlot, Density } from './purposeParser';
+export type { ParsedPurpose, ParsedPurposeSlot, Density, ListMarker } from './purposeParser';
 
 export { parseCompositionFile } from './compositionParser';
 export type {

package/parser/purposeParser.ts

@@ -6,10 +6,13 @@
  */
 
 import type { SlotId } from './types';
+import { parseIconRef, parseListItem } from './icons';
+import type { IconRef } from './icons';
 
 // ── Parsed types ──────────────────────────────────────────────────────────────
 
 export type Density = 'light' | 'medium' | 'full';
+export type ListMarker = 'none' | 'counter' | 'icon';
 
 export interface ParsedPurpose {
   id: string;
@@ -37,10 +40,8 @@ export interface ParsedPurpose {
   camera?: boolean;
   /** When false, photo/video analysis skips this purpose (no AI text generation). Default: true. */
   analyze?: boolean;
-  /** Default icon (Phosphor PascalCase name, e.g. "ArrowRight"). */
-  defaultIcon?: string;
-  /** Default icon weight. */
-  defaultIconWeight?: string;
+  /** Default icon for the icon slot. Resolves in the brand set first, then Phosphor (see resolveIconRef). */
+  defaultIcon?: IconRef;
   /** Optional prompt text shown in the empty background placeholder. Default: "Select a background". */
   bgPrompt?: string;
 }
@@ -57,11 +58,13 @@ export interface ParsedPurposeSlot {
   slotType?: 'text' | 'list';
   /** Max number of items (list slots only). */
   maxItems?: number;
-  /** Whether per-item icons are supported (list slots only). */
-  icons?: boolean;
-  /** Icon-only list — icons fill available space, text is suppressed. */
+  /** List item marker (list slots only). Default: 'none'. */
+  marker?: ListMarker;
+  /** Default icon for `marker: icon` items without an `[id]` prefix (list slots only). */
+  defaultIcon?: IconRef;
+  /** Icon-only list — icons fill available space, text is suppressed. Implies `marker: icon`. */
   iconOnly?: boolean;
-  /** Space between icon and text, in em (list slots only). Default: 0.4 */
+  /** Space between marker and text, in em (list slots only). Default: 0.4 */
   iconGap?: number;
   /** Gap between list items in em. Default: 0.5 */
   itemGap?: number;
@@ -93,7 +96,8 @@ export interface ParsedPurposeSlot {
     autofitMin: number;
     autofitMax: number;
     textAlign: 'left' | 'center' | 'right' | 'justify';
-    hyphenate: boolean;
+    /** true = hyphenate freely (body text); 'fit' = only when a word doesn't fit at autofit-min. */
+    hyphenate: boolean | 'fit';
   }>;
 }
 
@@ -129,8 +133,7 @@ export function parsePurposeFile(content: string, fileName: string): ParsedPurpo
   let defaultVideo: string | undefined;
   let camera: boolean | undefined;
   let analyze: boolean | undefined;
-  let defaultIcon: string | undefined;
-  let defaultIconWeight: string | undefined;
+  let defaultIcon: IconRef | undefined;
   let bgPrompt: string | undefined;
   const slots: ParsedPurposeSlot[] = [];
   // For backward compat: track first # line text for fallback id
@@ -152,6 +155,19 @@ export function parsePurposeFile(content: string, fileName: string): ParsedPurpo
     if (!s.label) throw new Error(`${fileName}:${lineNum}: slot "${s.id}" missing label`);
     if ((!s.samples || s.samples.length === 0) && !s.iconOnly && !s.value) throw new Error(`${fileName}:${lineNum}: slot "${s.id}" missing samples or value`);
     if (!s.maxLength) throw new Error(`${fileName}:${lineNum}: slot "${s.id}" missing maxLength`);
+    if (s.iconOnly) {
+      if (s.marker && s.marker !== 'icon') throw new Error(`${fileName}:${lineNum}: slot "${s.id}": iconOnly needs "marker: icon", got "${s.marker}"`);
+      s.marker = 'icon';
+    }
+    if (s.defaultIcon && s.marker !== 'icon') throw new Error(`${fileName}:${lineNum}: slot "${s.id}": defaultIcon needs "marker: icon"`);
+    if (s.slotType === 'list') {
+      for (const sample of s.samples ?? []) {
+        for (const item of sample.split('\n')) {
+          const { icon } = parseListItem(item);
+          if (icon && s.marker !== 'icon') throw new Error(`${fileName}:${lineNum}: slot "${s.id}": sample item "${item}" names an icon, but the list has no "marker: icon"`);
+        }
+      }
+    }
     const t = s.typography as ParsedPurposeSlot['typography'];
     if (!s.typographyRef) {
       // Legacy direct font: path — all fields required
@@ -315,23 +331,16 @@ export function parsePurposeFile(content: string, fileName: string): ParsedPurpo
       continue;
     }
 
-    // Default icon: "defaultIcon: warning-circle" or "defaultIcon: warning-circle duotone"
-    // Accepts kebab-case (natural for file format) and converts to PascalCase for Phosphor lookup.
-    if (line.startsWith('defaultIcon:')) {
-      const parts = line.slice(12).trim().split(/\s+/);
-      // Convert kebab-case to PascalCase: "warning-circle" → "WarningCircle"
-      defaultIcon = parts[0].split('-').map(w => w.charAt(0).toUpperCase() + w.slice(1)).join('');
-      if (parts[1]) defaultIconWeight = parts[1];
+    // Default icon: "defaultIcon: quote", "defaultIcon: phosphor:warning-circle duotone"
+    if (line.startsWith('defaultIcon:') && !raw.startsWith(' ')) {
+      defaultIcon = parseIconRef(line.slice(12), `${fileName}:${lineNum}`);
       continue;
     }
 
     // Backward compat: "icon: warning-circle" (deprecated — use defaultIcon:)
-    if (line.startsWith('icon:')) {
+    if (line.startsWith('icon:') && !raw.startsWith(' ')) {
       console.warn(`${fileName}:${lineNum}: deprecated "icon:" — use "defaultIcon:" instead`);
-      const parts = line.slice(5).trim().split(/\s+/);
-      // Convert kebab-case to PascalCase: "warning-circle" → "WarningCircle"
-      defaultIcon = parts[0].split('-').map(w => w.charAt(0).toUpperCase() + w.slice(1)).join('');
-      if (parts[1]) defaultIconWeight = parts[1];
+      defaultIcon = parseIconRef(line.slice(5), `${fileName}:${lineNum}`);
       continue;
     }
 
@@ -411,6 +420,7 @@ export function parsePurposeFile(content: string, fileName: string): ParsedPurpo
         if (prop === 'uppercase: false') { currentSlot.typographyOverrides.uppercase = false; continue; }
         if (prop === 'hyphenate' || prop === 'hyphenate: true') { currentSlot.typographyOverrides.hyphenate = true; continue; }
         if (prop === 'hyphenate: false') { currentSlot.typographyOverrides.hyphenate = false; continue; }
+        if (prop === 'hyphenate: fit') { currentSlot.typographyOverrides.hyphenate = 'fit'; continue; }
         if (prop === 'autofit: none' || prop === 'autofit:none') {
           currentSlot.typographyOverrides.autofitMin = -1;
           currentSlot.typographyOverrides.autofitMax = -1;
@@ -462,9 +472,27 @@ export function parsePurposeFile(content: string, fileName: string): ParsedPurpo
           currentSlot.samples = raw.split('|').map(s => s.trim().replace(/\\n/g, '\n'));
           continue;
         }
-        if (prop === 'icons: true' || prop === 'icons:true') { currentSlot.icons = true; continue; }
-        if (prop === 'icons: false' || prop === 'icons:false') { currentSlot.icons = false; continue; }
-        if (prop === 'iconOnly: true' || prop === 'iconOnly:true') { currentSlot.iconOnly = true; currentSlot.icons = true; continue; }
+        if (prop.startsWith('marker:')) {
+          const m = prop.slice(7).trim();
+          if (m !== 'none' && m !== 'counter' && m !== 'icon') throw new Error(`${fileName}:${lineNum}: invalid marker "${m}" — must be "none", "counter" or "icon"`);
+          currentSlot.marker = m;
+          continue;
+        }
+        if (prop.startsWith('defaultIcon:')) {
+          currentSlot.defaultIcon = parseIconRef(prop.slice(12), `${fileName}:${lineNum}`);
+          continue;
+        }
+        if (prop === 'icons: true' || prop === 'icons:true') {
+          console.warn(`${fileName}:${lineNum}: deprecated "icons: true" — use "marker: counter" or "marker: icon"`);
+          currentSlot.marker = currentSlot.marker ?? 'counter';
+          continue;
+        }
+        if (prop === 'icons: false' || prop === 'icons:false') {
+          console.warn(`${fileName}:${lineNum}: deprecated "icons: false" — use "marker: none"`);
+          currentSlot.marker = currentSlot.marker ?? 'none';
+          continue;
+        }
+        if (prop === 'iconOnly: true' || prop === 'iconOnly:true') { currentSlot.iconOnly = true; continue; }
         if (prop.startsWith('iconGap:')) {
           const n = parseFloat(prop.slice(8).trim());
           if (isNaN(n) || n < 0) throw new Error(`${fileName}:${lineNum}: invalid iconGap "${prop.slice(8).trim()}"`);
@@ -624,5 +652,5 @@ export function parsePurposeFile(content: string, fileName: string): ParsedPurpo
     context = contextLines.join('\n').trim();
   }
 
-  return { id, name, description, preferredCompositions: compositions, slots, density, palette, scope, context, voice, defaultLogo, defaultPhoto, defaultVideo, camera, analyze, defaultIcon, defaultIconWeight, bgPrompt };
+  return { id, name, description, preferredCompositions: compositions, slots, density, palette, scope, context, voice, defaultLogo, defaultPhoto, defaultVideo, camera, analyze, defaultIcon, bgPrompt };
 }

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

@@ -28,6 +28,9 @@
     { "include": "#color-group-entry" },
     { "include": "#color-group-reference" },
     { "include": "#color-group-entry-property" },
+    { "include": "#icons-counter-header" },
+    { "include": "#icon-entry" },
+    { "include": "#counter-value" },
     { "include": "#theme-header" },
     { "include": "#brand-color-entry" },
     { "include": "#brand-color-print-sub" },
@@ -384,6 +387,39 @@
         "14": { "name": "constant.language.boolean.brand-intent-brand" }
       }
     },
+    "icons-counter-header": {
+      "comment": "Bare `icons` / `counter` block headers.",
+      "match": "^(icons|counter)\\s*$",
+      "captures": {
+        "1": { "name": "keyword.control.brand-intent-brand" }
+      }
+    },
+    "icon-entry": {
+      "comment": "icons entry: ID: font [$FONT] U+XXXX|GLYPH  /  ID: phosphor NAME [WEIGHT]  /  ID: PATH.svg",
+      "match": "^(\\s{2,})(?!(?:src|lottie|gltf):)([a-z][a-z0-9-]*)(:\\s*)(?:(font)(?:\\s+(\\$[\\w-]+))?\\s+(\\S+)|(phosphor)\\s+([a-z][a-z0-9-]*)(?:\\s+(thin|light|regular|bold|fill|duotone))?|(\\S+\\.svg))\\s*(#.*)?$",
+      "captures": {
+        "2": { "name": "entity.name.function.brand-intent-brand" },
+        "3": { "name": "punctuation.separator.key-value.brand-intent-brand" },
+        "4": { "name": "keyword.other.brand-intent-brand" },
+        "5": { "name": "variable.other.brand-intent-brand" },
+        "6": { "name": "constant.character.brand-intent-brand" },
+        "7": { "name": "keyword.other.brand-intent-brand" },
+        "8": { "name": "string.unquoted.brand-intent-brand" },
+        "9": { "name": "variable.parameter.brand-intent-brand" },
+        "10": { "name": "string.unquoted.brand-intent-brand" },
+        "11": { "name": "comment.line.number-sign.brand-intent-brand" }
+      }
+    },
+    "counter-value": {
+      "comment": "counter block properties (typography: is covered by typography-value)",
+      "match": "^(\\s{2,})(format|shape|size|padding)(:\\s*)(\\S+)\\s*(#.*)?$",
+      "captures": {
+        "2": { "name": "support.type.property-name.brand-intent-brand" },
+        "3": { "name": "punctuation.separator.key-value.brand-intent-brand" },
+        "4": { "name": "constant.numeric.brand-intent-brand" },
+        "5": { "name": "comment.line.number-sign.brand-intent-brand" }
+      }
+    },
     "badge-header": {
       "comment": "Bare `label:` or `cta:` line that introduces a badge style block.",
       "match": "^(label|cta):\\s*$",
@@ -409,7 +445,7 @@
     },
     "keyword-partial": {
       "comment": "Fallback: color the keyword token on incomplete lines (while typing)",
-      "match": "^(id:|name:|language:|locale:|domain:|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)(?=\\s|$)",
+      "match": "^(id:|name:|language:|locale:|domain:|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)(?=\\s|$)",
       "captures": {
         "1": { "name": "keyword.control.brand-intent-brand" }
       }

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

@@ -22,6 +22,7 @@
     { "include": "#override-value" },
     { "include": "#list-property" },
     { "include": "#sample-item" },
+    { "include": "#sample-icon-continuation" },
     { "include": "#property" },
     { "include": "#keyword-partial" }
   ],
@@ -59,7 +60,7 @@
       }
     },
     "default-icon": {
-      "match": "^(defaultIcon:)\\s+([\\w-]+)(?:\\s+(thin|light|regular|bold|fill|duotone))?",
+      "match": "^\\s*(defaultIcon:)\\s+((?:phosphor:)?[a-z][a-z0-9-]*)(?:\\s+(thin|light|regular|bold|fill|duotone))?",
       "captures": {
         "1": { "name": "keyword.control.brand-intent-purpose" },
         "2": { "name": "entity.name.function.brand-intent-purpose" },
@@ -164,7 +165,15 @@
           }
         },
         {
-          "match": "^\\s{4,}(italic|uppercase|hyphenate)(?:(:)\\s+(true|false))?\\s*$",
+          "match": "^\\s{4,}(italic|uppercase)(?:(:)\\s+(true|false))?\\s*$",
+          "captures": {
+            "1": { "name": "support.type.property-name.brand-intent-purpose" },
+            "2": { "name": "punctuation.separator.brand-intent-purpose" },
+            "3": { "name": "constant.language.brand-intent-purpose" }
+          }
+        },
+        {
+          "match": "^\\s{4,}(hyphenate)(?:(:)\\s+(true|false|fit))?\\s*$",
           "captures": {
             "1": { "name": "support.type.property-name.brand-intent-purpose" },
             "2": { "name": "punctuation.separator.brand-intent-purpose" },
@@ -207,7 +216,7 @@
     },
     "list-property": {
       "comment": "4-space indented properties under type: list blocks",
-      "match": "^\\s{4,}(icons|iconOnly|iconGap|itemGap|maxItems|direction)(:)\\s+(.*)",
+      "match": "^\\s{4,}(marker|icons|iconOnly|iconGap|itemGap|maxItems|direction)(:)\\s+(.*)",
       "captures": {
         "1": { "name": "support.type.property-name.brand-intent-purpose" },
         "2": { "name": "punctuation.separator.brand-intent-purpose" },
@@ -216,9 +225,17 @@
     },
     "sample-item": {
       "comment": "Multi-line sample entries -- dim only the dash, leave text unstyled",
-      "match": "^(\\s{4,})(-)(?=\\s)",
+      "match": "^(\\s{4,})(-)(?=\\s)(?:\\s+(\\[[^\\]]+\\]))?",
+      "captures": {
+        "2": { "name": "comment.line.dash.brand-intent-purpose" },
+        "3": { "name": "entity.name.function.brand-intent-purpose" }
+      }
+    },
+    "sample-icon-continuation": {
+      "comment": "[ID] icon prefix on list item continuation lines",
+      "match": "^(\\s{6,})(\\[[^\\]]+\\])",
       "captures": {
-        "2": { "name": "comment.line.dash.brand-intent-purpose" }
+        "2": { "name": "entity.name.function.brand-intent-purpose" }
       }
     },
     "keyword-partial": {