brand-intent 0.15.0 → 0.17.0

package/package.json

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

@@ -116,6 +116,27 @@ export interface ParsedBrand {
   framings?: ParsedFramingDef[];
   /** Camera defaults (`camera` block). Absent → rear camera, no grid. */
   camera?: ParsedCameraDef;
+  /** Photo treatment (`photo-look` block). Absent → photos stay as taken. */
+  photoLook?: ParsedPhotoLookDef;
+}
+
+export type PhotoLookKey = 'saturation' | 'contrast' | 'warmth' | 'fade' | 'mono' | 'duotone';
+
+export interface ParsedPhotoLookDef {
+  /** -100..100, 0 = unchanged. */
+  saturation: number;
+  /** -100..100, 0 = unchanged. */
+  contrast: number;
+  /** -100 (cool) .. 100 (warm), 0 = unchanged. */
+  warmth: number;
+  /** Lifted black point, 0..100. */
+  fade: number;
+  /** Black-and-white. */
+  mono: boolean;
+  /** Map luminance onto two colors (resolved hex), shadows → highlights. Excludes `mono`. */
+  duotone?: { shadow: string; highlight: string };
+  /** Keys the person cannot change. All others are starting values. */
+  fixed: PhotoLookKey[];
 }
 
 export interface ParsedCameraDef {
@@ -250,6 +271,14 @@ const VALID_STRATEGIES = new Set<PaletteStrategy>(['monochrome', 'duotone', 'tri
 const VALID_ADHERENCES = new Set<Adherence>(['strict', 'on-brand', 'flexible']);
 const TONE_CLASSES = new Set<ToneClass>(['light', 'mid', 'dark']);
 const FAMILY_ROLES = new Set<FamilyRole>(['core', 'accent', 'contrast']);
+
+const DAYS_IN_MONTH = [31, 29, 31, 30, 31, 30, 31, 31, 30, 31, 30, 31];
+function isMonthDay(value: string): boolean {
+  const m = value.match(/^(\d{2})-(\d{2})$/);
+  if (!m) return false;
+  const month = Number(m[1]), day = Number(m[2]);
+  return month >= 1 && month <= 12 && day >= 1 && day <= DAYS_IN_MONTH[month - 1];
+}
 const FAMILY_ORDERS = new Set<FamilyOrder>(['cycle', 'sequence']);
 const FAMILY_BORROWS = new Set<FamilyBorrow>(['previous', 'next', 'both', 'none']);
 const PAIR_KEYS = ['ground', 'figure', 'text'] as const;
@@ -372,7 +401,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' | 'icons' | 'counter' | 'framing' | 'camera';
+  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' | 'framing' | 'camera' | 'photo-look';
   let activeBlock: ActiveBlock = 'none';
   let currentThemeName = '';
   let currentDividerName = '';
@@ -395,7 +424,7 @@ export function parseBrandFile(content: string, fileName: string): ParsedBrand {
   const adherenceOverridesRaw: Record<string, string> = {};
   const colorRulesRaw: Record<string, string> = {};
   let colorRulesDeclared = false;
-  type RawFamily = { name: string; line: number; colors: Array<{ role: string; value: string; line: number }>; pairs: Array<{ ground: string; figure: string; line: number }> };
+  type RawFamily = { name: string; line: number; from?: string; colors: Array<{ role: string; value: string; line: number }>; pairs: Array<{ ground: string; figure: string; line: number }> };
   const familiesProps: Record<string, string> = {};
   const familiesRaw: RawFamily[] = [];
   let familiesDeclared = false;
@@ -421,6 +450,8 @@ export function parseBrandFile(content: string, fileName: string): ParsedBrand {
   let counterDeclared = false;
   const cameraRaw: Record<string, { value: string; line: number }> = {};
   let cameraDeclared = false;
+  const photoLookRaw: Record<string, { value: string; line: number }> = {};
+  let photoLookDeclared = false;
   const framingsRaw: Array<{ id: string; line: number; props: Record<string, { value: string; line: number }> }> = [];
 
   for (let i = 0; i < lines.length; i++) {
@@ -653,8 +684,16 @@ export function parseBrandFile(content: string, fileName: string): ParsedBrand {
         }
         const colonIdx = trimmed.indexOf(':');
         const key = colonIdx !== -1 ? trimmed.slice(0, colonIdx).trim() : trimmed;
+        if (key === 'from' && colonIdx !== -1) {
+          const value = trimmed.slice(colonIdx + 1).trim();
+          if (currentFamily.from !== undefined) throw new Error(`${fileName}:${lineNum}: family "${currentFamily.name}" declares from: twice`);
+          if (!isMonthDay(value)) throw new Error(`${fileName}:${lineNum}: family "${currentFamily.name}" from: must be "MM-DD" (e.g. 12-01), got "${value}"`);
+          inPairs = false;
+          currentFamily.from = value;
+          continue;
+        }
         if (colonIdx === -1 || !FAMILY_ROLES.has(key as FamilyRole)) {
-          throw new Error(`${fileName}:${lineNum}: family "${currentFamily.name}": expected core / accent / contrast / pairs, got "${trimmed}"`);
+          throw new Error(`${fileName}:${lineNum}: family "${currentFamily.name}": expected from / core / accent / contrast / pairs, got "${trimmed}"`);
         }
         inPairs = false;
         currentFamily.colors.push({ role: key, value: trimmed.slice(colonIdx + 1).trim(), line: lineNum });
@@ -801,6 +840,18 @@ export function parseBrandFile(content: string, fileName: string): ParsedBrand {
         cameraRaw[entry.slice(0, colonIdx).trim()] = { value: entry.slice(colonIdx + 1).trim(), line: lineNum };
         continue;
       }
+      if (activeBlock === 'photo-look') {
+        const trimmed = raw.trim();
+        if (trimmed.startsWith('#')) continue;
+        // `# …` is a comment, but `#RGB` / `#RRGGBB` is a duotone color
+        const commentIdx = trimmed.search(/\s+#(?![0-9a-f]{3}(?:[0-9a-f]{3}(?:[0-9a-f]{2})?)?(?:\s|$))/i);
+        const entry = commentIdx !== -1 ? trimmed.slice(0, commentIdx) : trimmed;
+        const colonIdx = entry.indexOf(':');
+        // Bare flag (`mono`) or KEY: VALUE
+        if (colonIdx === -1) photoLookRaw[entry.trim()] = { value: '', line: lineNum };
+        else photoLookRaw[entry.slice(0, colonIdx).trim()] = { value: entry.slice(colonIdx + 1).trim(), line: lineNum };
+        continue;
+      }
       if (activeBlock === 'framing') {
         const trimmed = raw.trim();
         if (trimmed.startsWith('#')) continue;
@@ -881,6 +932,14 @@ export function parseBrandFile(content: string, fileName: string): ParsedBrand {
       continue;
     }
 
+    // photo-look — photo treatment (saturation)
+    if (raw.trim() === 'photo-look') {
+      if (photoLookDeclared) throw new Error(`${fileName}:${lineNum}: duplicate photo-look block`);
+      photoLookDeclared = true;
+      activeBlock = 'photo-look';
+      continue;
+    }
+
     // framing <id> — photo framing module (horizon position)
     const framingMatch = raw.match(/^framing\s+(\S+)\s*$/);
     if (framingMatch) {
@@ -1150,7 +1209,16 @@ export function parseBrandFile(content: string, fileName: string): ParsedBrand {
         }
         brandColors[c.key] = c.hex;
       }
-      families.push({ name: raw.name, colors, pairs: [] });
+      families.push({ name: raw.name, ...(raw.from ? { from: raw.from } : {}), colors, pairs: [] });
+    }
+    const dated = familiesRaw.filter(f => f.from !== undefined);
+    if (dated.length > 0 && dated.length < familiesRaw.length) {
+      const missing = familiesRaw.filter(f => f.from === undefined).map(f => f.name).join(', ');
+      throw new Error(`${fileName}: color-families: from: must be declared on every family or on none (missing: ${missing})`);
+    }
+    for (const f of dated) {
+      const twin = dated.find(o => o !== f && o.from === f.from);
+      if (twin) throw new Error(`${fileName}:${f.line}: families "${twin.name}" and "${f.name}" share from: ${f.from}`);
     }
     colorFamilies = { order, borrow, distance, shared, families };
     if (borrow !== 'none' && reachCoversAll(families.length, { order, borrow, distance })) {
@@ -1557,6 +1625,60 @@ export function parseBrandFile(content: string, fileName: string): ParsedBrand {
     result.camera = camera;
   }
 
+  // Finalise photo treatment
+  if (photoLookDeclared) {
+    const keys: PhotoLookKey[] = ['saturation', 'contrast', 'warmth', 'fade', 'mono', 'duotone'];
+    for (const [key, { line }] of Object.entries(photoLookRaw)) {
+      if (key !== 'fixed' && !keys.includes(key as PhotoLookKey)) throw new Error(`${fileName}:${line}: unknown photo-look property "${key}"`);
+    }
+    const int = (key: string, min: number, max: number): number => {
+      const p = photoLookRaw[key];
+      if (!p) return 0;
+      const n = Number(p.value);
+      if (!/^[+-]?\d+$/.test(p.value) || n < min || n > max) {
+        throw new Error(`${fileName}:${p.line}: photo-look ${key} must be an integer from ${min} to ${max}, got "${p.value}"`);
+      }
+      return n;
+    };
+    const look: ParsedPhotoLookDef = {
+      saturation: int('saturation', -100, 100),
+      contrast: int('contrast', -100, 100),
+      warmth: int('warmth', -100, 100),
+      fade: int('fade', 0, 100),
+      mono: false,
+      fixed: [],
+    };
+    const mono = photoLookRaw['mono'];
+    if (mono) {
+      if (mono.value !== '') throw new Error(`${fileName}:${mono.line}: photo-look mono is a flag and takes no value`);
+      look.mono = true;
+    }
+    const duo = photoLookRaw['duotone'];
+    if (duo) {
+      if (mono) throw new Error(`${fileName}:${duo.line}: photo-look cannot be both mono and duotone`);
+      const refs = duo.value.split(/\s+/);
+      if (refs.length !== 2) throw new Error(`${fileName}:${duo.line}: photo-look duotone must be "SHADOW HIGHLIGHT", got "${duo.value}"`);
+      const [shadow, highlight] = refs.map(ref => {
+        if (ref.startsWith('$') && !brandColors[ref.slice(1)]) {
+          throw new Error(`${fileName}:${duo.line}: photo-look duotone references unknown brand color "${ref}"`);
+        }
+        const hex = normalizeHex(ref.startsWith('$') ? brandColors[ref.slice(1)] : ref);
+        if (!hex) throw new Error(`${fileName}:${duo.line}: photo-look duotone colors must be $ref or #HEX, got "${ref}"`);
+        return hex;
+      });
+      look.duotone = { shadow, highlight };
+    }
+    const fixed = photoLookRaw['fixed'];
+    if (fixed) {
+      for (const key of fixed.value.split(/\s+/)) {
+        if (!keys.includes(key as PhotoLookKey)) throw new Error(`${fileName}:${fixed.line}: photo-look fixed lists unknown key "${key}"`);
+        if (!photoLookRaw[key]) throw new Error(`${fileName}:${fixed.line}: photo-look fixed lists "${key}", which is not set`);
+        look.fixed.push(key as PhotoLookKey);
+      }
+    }
+    result.photoLook = look;
+  }
+
   // Finalise framing modules
   if (framingsRaw.length > 0) {
     const known = new Set(['label', 'horizon', 'description']);

package/parser/colorSystem.ts

@@ -193,6 +193,23 @@ export function colorOrigin(
   return null;
 }
 
+/**
+ * Family in season on `date`: the one with the latest `from:` on or before that
+ * month/day, wrapping to the year's last start before the first one. Uses the
+ * date's local calendar day. -1 when the families declare no dates.
+ */
+export function familyIndexForDate(families: Pick<ColorFamily, 'from'>[], date: Date): number {
+  if (families.length === 0 || families.some(f => !f.from)) return -1;
+  const today = `${String(date.getMonth() + 1).padStart(2, '0')}-${String(date.getDate()).padStart(2, '0')}`;
+  let best = -1;
+  let latest = -1;
+  families.forEach((f, i) => {
+    if (f.from! <= today && (best === -1 || f.from! > families[best].from!)) best = i;
+    if (latest === -1 || f.from! > families[latest].from!) latest = i;
+  });
+  return best !== -1 ? best : latest;
+}
+
 /** Name of the family that declares `hex` (first match), for error messages. */
 export function owningFamily(hex: string, families: ColorFamily[]): string | undefined {
   return families.find(f => f.colors.some(c => c.hex === hex))?.name;

package/parser/index.ts

@@ -20,10 +20,11 @@ export {
   familyTextCandidates,
   checkFamilyPair,
   enumerateFamilyPairs,
+  familyIndexForDate,
   DEFAULT_COLOR_RULES,
 } from './colorSystem';
 export type { ReachConfig } from './colorSystem';
-export type { ParsedBrand, ParsedFontDef, ParsedTypographyDef, ParsedDividerDef, BrandColorPrintSpec, ParsedAssetDef, ParsedBadgeStyle, LogoAlign, ParsedCounterDef, CounterFormat, CounterShape, ParsedFramingDef, ParsedCameraDef } from './brandParser';
+export type { ParsedBrand, ParsedFontDef, ParsedTypographyDef, ParsedDividerDef, BrandColorPrintSpec, ParsedAssetDef, ParsedBadgeStyle, LogoAlign, ParsedCounterDef, CounterFormat, CounterShape, ParsedFramingDef, ParsedCameraDef, ParsedPhotoLookDef, PhotoLookKey } from './brandParser';
 
 export { parseIconRef, parseIconSource, resolveIconRef, parseListItem, phosphorName, PHOSPHOR_WEIGHTS } from './icons';
 export type { IconRef, IconSource, ParsedIconDef, ResolvedIcon, PhosphorWeight } from './icons';

package/parser/types.ts

@@ -156,6 +156,8 @@ export interface FamilyPair extends PairCheck {
 
 export interface ColorFamily {
   name: string;
+  /** Start date `MM-DD` (`from:`). Declared on every family or on none. */
+  from?: string;
   colors: FamilyColor[];
   pairs: FamilyPair[];
 }

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

@@ -15,6 +15,7 @@
     { "include": "#color-rules-entry" },
     { "include": "#color-families-property" },
     { "include": "#family-header" },
+    { "include": "#family-from" },
     { "include": "#family-role" },
     { "include": "#family-pairs-keyword" },
     { "include": "#color-mode-enum" },
@@ -143,6 +144,15 @@
         "5": { "name": "string.unquoted.brand-intent-brand" }
       }
     },
+    "family-from": {
+      "comment": "Family start date: from: MM-DD",
+      "match": "^(\\s{4,})(from)(:\\s*)(\\d{2}-\\d{2})\\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" }
+      }
+    },
     "family-pairs-keyword": {
       "match": "^(\\s{4,})(pairs)\\s*$",
       "captures": {
@@ -389,8 +399,8 @@
       }
     },
     "icons-counter-header": {
-      "comment": "Bare `icons` / `counter` block headers.",
-      "match": "^(icons|counter)\\s*$",
+      "comment": "Bare `icons` / `counter` / `camera` / `photo-look` block headers.",
+      "match": "^(icons|counter|camera|photo-look)\\s*$",
       "captures": {
         "1": { "name": "keyword.control.brand-intent-brand" }
       }