brand-intent 0.9.0 → 0.11.0

package/package.json

@@ -1,16 +1,16 @@
 {
   "name": "brand-intent",
-  "version": "0.9.0",
+  "version": "0.11.0",
   "description": "An open file format specification for making brand intent machine-readable.",
   "author": "Christophe Stoll <christophe@stoll.studio>",
   "license": "MIT",
   "repository": {
     "type": "git",
-    "url": "https://github.com/studiostoll/brand-intent.git"
+    "url": "git+https://github.com/studiostoll/brand-intent.git"
   },
   "homepage": "https://intent.stoll.studio",
   "bin": {
-    "brand-intent": "./cli/index.mjs"
+    "brand-intent": "cli/index.mjs"
   },
   "exports": {
     ".": {
@@ -34,7 +34,7 @@
   ],
   "scripts": {
     "release": "./scripts/release.sh",
-    "test": "tsx tests/brandParser.test.ts && tsx tests/identityParser.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/realBrands.test.ts"
   },
   "devDependencies": {
     "tsx": "^4.19.0"

package/parser/brandParser.ts

@@ -17,7 +17,25 @@ import type {
   StateColors,
   GroupKey,
   NeutralRole,
+  ColorRules,
+  ColorFamilies,
+  ColorFamily,
+  FamilyColor,
+  FamilyRole,
+  FamilyOrder,
+  FamilyBorrow,
+  ToneClass,
+  ThemePair,
 } from './types';
+import {
+  DEFAULT_COLOR_RULES,
+  isHex6,
+  contrastRatio,
+  derivePairSlots,
+  resolveTextColor,
+  checkFamilyPair,
+  reachCoversAll,
+} from './colorSystem';
 
 // ── Parsed type ────────────────────────────────────────────────────────────────
 
@@ -64,6 +82,14 @@ export interface ParsedBrand {
   colorAdherence?: Adherence;
   /** Per-brand tolerance overrides for the declared adherence level. */
   colorAdherenceOverrides?: AdherenceTolerances;
+  /** Contrast + tone rules (`color-rules` block). Absent when not declared. */
+  colorRules?: ColorRules;
+  /** Color families (`color-families` block): ordered sets with roles, reach config and checked pairs. */
+  colorFamilies?: ColorFamilies;
+  /** Ground / figure / text for every pair theme (authored `ground:`/`figure:` themes and emitted family pairs). */
+  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') */
   themes?: Record<string, Record<string, string>>;
   /** Print annotations from inline # comments: slot name → annotation text */
@@ -97,8 +123,15 @@ export interface ParsedAssetDef {
   generator?: string;
   /** Default parameters for the procedural generator, keyed by param name. Declared via the indented `generator-params` sub-block. */
   generatorParams?: Record<string, number>;
+  /** Logos only: artwork per horizontal placement, declared via `align-left` / `align-center` / `align-right`
+   *  sub-blocks. Consumers render the variant matching where the logo sits, else the base `src`. */
+  alignVariants?: Partial<Record<LogoAlign, { src: string; aspectRatio?: number }>>;
+  /** Library group (e.g. "experimental"). Consumers list each group as its own section after the ungrouped assets. */
+  group?: string;
 }
 
+export type LogoAlign = 'left' | 'center' | 'right';
+
 export interface ParsedBadgeStyle {
   /** Padding in cqh: [top, right, bottom, left] */
   padding: [number, number, number, number];
@@ -172,6 +205,16 @@ const STATE_KEYS = new Set<string>(['problem', 'warning', 'success', 'info', 'in
 const VALID_COLOR_MODES = new Set<ColorMode>(['static', 'dynamic', 'guided']);
 const VALID_STRATEGIES = new Set<PaletteStrategy>(['monochrome', 'duotone', 'tricolor', 'spectrum']);
 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 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;
+
+/** Flat-projection key for a display name: lowercased, spaces → hyphens. */
+function colorKey(name: string): string {
+  return name.toLowerCase().replace(/\s+/g, '-');
+}
 
 /**
  * Expand a 3-digit hex to 6-digit. Pass-through for 6 or 8-digit.
@@ -286,7 +329,7 @@ export function parseBrandFile(content: string, fileName: string): ParsedBrand {
     tokensSource: 'figma',
   };
 
-  type ActiveBlock = 'none' | 'brand-colors' | 'state-colors' | 'color-bounds' | 'color-adherence' | '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';
   let activeBlock: ActiveBlock = 'none';
   let currentThemeName = '';
   let currentDividerName = '';
@@ -307,6 +350,14 @@ export function parseBrandFile(content: string, fileName: string): ParsedBrand {
   const stateColorsRaw: Record<string, string> = {};
   const colorBoundsRaw: Record<string, string> = {};
   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 }> };
+  const familiesProps: Record<string, string> = {};
+  const familiesRaw: RawFamily[] = [];
+  let familiesDeclared = false;
+  let currentFamily: RawFamily | null = null;
+  let inPairs = false;
   const themes: Record<string, Record<string, string>> = {};
   const themeDescriptions: Record<string, string> = {};
   const spacingRaw: Record<string, string> = {};
@@ -509,6 +560,56 @@ export function parseBrandFile(content: string, fileName: string): ParsedBrand {
         }
         continue;
       }
+      if (activeBlock === 'color-rules') {
+        const trimmed = raw.trim();
+        const colonIdx = trimmed.indexOf(':');
+        if (colonIdx !== -1) {
+          colorRulesRaw[trimmed.slice(0, colonIdx).trim()] = trimmed.slice(colonIdx + 1).trim();
+        }
+        continue;
+      }
+      if (activeBlock === 'color-families') {
+        const trimmed = raw.trim();
+        if (trimmed === '') continue;
+        const familyMatch = trimmed.match(/^family\s+(\S+)$/);
+        if (familyMatch) {
+          if (familiesRaw.some(f => f.name === familyMatch[1])) {
+            throw new Error(`${fileName}:${lineNum}: duplicate family "${familyMatch[1]}"`);
+          }
+          currentFamily = { name: familyMatch[1], line: lineNum, colors: [], pairs: [] };
+          familiesRaw.push(currentFamily);
+          inPairs = false;
+          continue;
+        }
+        if (!currentFamily) {
+          const colonIdx = trimmed.indexOf(':');
+          if (colonIdx === -1) {
+            throw new Error(`${fileName}:${lineNum}: expected "key: value" or "family NAME" in color-families, got "${trimmed}"`);
+          }
+          familiesProps[trimmed.slice(0, colonIdx).trim()] = trimmed.slice(colonIdx + 1).trim();
+          continue;
+        }
+        if (trimmed === 'pairs') {
+          inPairs = true;
+          continue;
+        }
+        if (inPairs && trimmed.includes('/')) {
+          const parts = trimmed.split('/').map(p => p.trim());
+          if (parts.length !== 2 || !parts[0] || !parts[1]) {
+            throw new Error(`${fileName}:${lineNum}: pair must be "ground / figure", got "${trimmed}"`);
+          }
+          currentFamily.pairs.push({ ground: parts[0], figure: parts[1], line: lineNum });
+          continue;
+        }
+        const colonIdx = trimmed.indexOf(':');
+        const key = colonIdx !== -1 ? trimmed.slice(0, colonIdx).trim() : trimmed;
+        if (colonIdx === -1 || !FAMILY_ROLES.has(key as FamilyRole)) {
+          throw new Error(`${fileName}:${lineNum}: family "${currentFamily.name}": expected core / accent / contrast / pairs, got "${trimmed}"`);
+        }
+        inPairs = false;
+        currentFamily.colors.push({ role: key, value: trimmed.slice(colonIdx + 1).trim(), line: lineNum });
+        continue;
+      }
       if (activeBlock === 'theme' && currentThemeName) {
         // slot: #HEX or $ref  # optional comment
         const colonIdx = raw.indexOf(':');
@@ -600,9 +701,9 @@ export function parseBrandFile(content: string, fileName: string): ParsedBrand {
             const last = arr[arr.length - 1];
             if (last && last.id === currentAssetId) last.props[trimmed] = 'true';
             currentSubBlock = null;
-          } else if (trimmed === 'generator-params') {
+          } else if (trimmed === 'generator-params' || (activeBlock === 'logo' && /^align-(left|center|right)$/.test(trimmed))) {
             // Open a nested sub-block — subsequent deeper-indented key: value lines attach here.
-            currentSubBlock = 'generator-params';
+            currentSubBlock = trimmed;
           }
         }
         continue;
@@ -648,6 +749,23 @@ export function parseBrandFile(content: string, fileName: string): ParsedBrand {
       continue;
     }
 
+    // color-rules — contrast minimums and tone rules
+    if (raw.trim() === 'color-rules') {
+      activeBlock = 'color-rules';
+      colorRulesDeclared = true;
+      continue;
+    }
+
+    // color-families — ordered color sets with roles, reach and pairs
+    if (raw.trim() === 'color-families') {
+      if (familiesDeclared) throw new Error(`${fileName}:${lineNum}: duplicate color-families block`);
+      activeBlock = 'color-families';
+      familiesDeclared = true;
+      currentFamily = null;
+      inPairs = false;
+      continue;
+    }
+
     // theme ThemeName — starts a theme block
     const themeMatch = raw.match(/^theme\s+(\S+)/);
     if (themeMatch) {
@@ -831,6 +949,91 @@ export function parseBrandFile(content: string, fileName: string): ParsedBrand {
     }
   }
 
+  const colorWarnings: string[] = [];
+
+  // ── Finalise color-rules ──────────────────────────────────────────────────
+  const rules: ColorRules = { ...DEFAULT_COLOR_RULES, avoid: [], tones: [...DEFAULT_COLOR_RULES.tones] as [number, number] };
+  if (colorRulesDeclared) {
+    const num = (key: string) => {
+      const n = parseFloat(colorRulesRaw[key]);
+      if (isNaN(n) || n < 1 || n > 21) {
+        throw new Error(`${fileName}: color-rules "${key}" must be a contrast ratio between 1 and 21, got "${colorRulesRaw[key]}"`);
+      }
+      return n;
+    };
+    if (colorRulesRaw.text !== undefined) rules.text = num('text');
+    if (colorRulesRaw.figure !== undefined) rules.figure = num('figure');
+    if (colorRulesRaw.avoid !== undefined) {
+      for (const combo of colorRulesRaw.avoid.split(',').map(c => c.trim()).filter(Boolean)) {
+        const parts = combo.split('+').map(c => c.trim());
+        if (parts.length !== 2 || !parts.every(t => TONE_CLASSES.has(t as ToneClass))) {
+          throw new Error(`${fileName}: color-rules avoid "${combo}" must be two of light / mid / dark joined by "+"`);
+        }
+        rules.avoid.push([parts[0] as ToneClass, parts[1] as ToneClass]);
+      }
+    }
+    if (colorRulesRaw.tones !== undefined) {
+      const t = colorRulesRaw.tones.split(',').map(v => parseFloat(v.trim()));
+      if (t.length !== 2 || t.some(isNaN) || t[0] >= t[1]) {
+        throw new Error(`${fileName}: color-rules tones must be two ascending contrast values, e.g. "1.8, 4.5"`);
+      }
+      rules.tones = [t[0], t[1]];
+    }
+    result.colorRules = rules;
+  }
+
+  // ── Finalise color-families: colors + flat projection (pairs later, after themes) ──
+  let colorFamilies: ColorFamilies | undefined;
+  if (familiesDeclared) {
+    const order = (familiesProps.order ?? 'cycle') as FamilyOrder;
+    if (!FAMILY_ORDERS.has(order)) throw new Error(`${fileName}: color-families order must be "cycle" or "sequence", got "${order}"`);
+    const borrow = (familiesProps.borrow ?? 'both') as FamilyBorrow;
+    if (!FAMILY_BORROWS.has(borrow)) throw new Error(`${fileName}: color-families borrow must be previous / next / both / none, got "${borrow}"`);
+    const distance = familiesProps.distance !== undefined ? Number(familiesProps.distance) : 1;
+    if (!Number.isInteger(distance) || distance < 1) throw new Error(`${fileName}: color-families distance must be a whole number ≥ 1, got "${familiesProps.distance}"`);
+    if (familiesRaw.length === 0) throw new Error(`${fileName}: color-families declares no family`);
+
+    const shared: Array<{ name: string; hex: string }> = [];
+    for (const ref of (familiesProps.shared ?? '').split(',').map(r => r.trim()).filter(Boolean)) {
+      if (!ref.startsWith('$')) throw new Error(`${fileName}: color-families shared entries must be $refs to brand-colors, got "${ref}"`);
+      const hex = brandColors[ref.slice(1)] ? normalizeHex(brandColors[ref.slice(1)]) : null;
+      if (!hex || !isHex6(hex)) throw new Error(`${fileName}: color-families shared "${ref}" is not a known 6-digit brand color`);
+      shared.push({ name: ref.slice(1), hex });
+    }
+
+    const families: ColorFamily[] = [];
+    for (const raw of familiesRaw) {
+      const counts: Record<string, number> = {};
+      for (const c of raw.colors) counts[c.role] = (counts[c.role] ?? 0) + 1;
+      if (counts.core !== 1) throw new Error(`${fileName}:${raw.line}: family "${raw.name}" needs exactly one core color`);
+      if (counts.contrast !== 1) throw new Error(`${fileName}:${raw.line}: family "${raw.name}" needs exactly one contrast color`);
+      const seen: Record<string, number> = {};
+      const colors: FamilyColor[] = raw.colors.map(c => {
+        const m = c.value.match(/^(#[0-9a-fA-F]{3,6})(?:\s+(.+))?$/);
+        const hex = m ? normalizeHex(m[1]) : null;
+        if (!m || !hex || !isHex6(hex)) {
+          throw new Error(`${fileName}:${c.line}: family "${raw.name}" ${c.role} must be "#HEX" or "#HEX  Name", got "${c.value}"`);
+        }
+        seen[c.role] = (seen[c.role] ?? 0) + 1;
+        const generated = `${raw.name.toLowerCase()}-${c.role}${counts[c.role] > 1 ? `-${seen[c.role]}` : ''}`;
+        const name = m[2]?.trim() || generated;
+        return { role: c.role as FamilyRole, hex, name, key: colorKey(name) };
+      });
+      for (const c of colors) {
+        if (brandColors[c.key]) {
+          throw new Error(`${fileName}: family "${raw.name}" color name "${c.name}" collides with an existing brand color`);
+        }
+        brandColors[c.key] = c.hex;
+      }
+      families.push({ name: raw.name, colors, pairs: [] });
+    }
+    colorFamilies = { order, borrow, distance, shared, families };
+    if (borrow !== 'none' && reachCoversAll(families.length, { order, borrow, distance })) {
+      colorWarnings.push(`color-families: borrow "${borrow}" with distance ${distance} reaches every family — the borrow rule has no effect`);
+    }
+    result.colorFamilies = colorFamilies;
+  }
+
   // Store brand colors (flat projection)
   if (Object.keys(brandColors).length > 0) {
     result.brandColors = brandColors;
@@ -873,10 +1076,10 @@ export function parseBrandFile(content: string, fileName: string): ParsedBrand {
   }
 
   // ── Minimum-structure validation for color-mode: guided ───────────────────
-  if (result.colorMode === 'guided') {
+  if (result.colorMode === 'guided' && !(colorFamilies && colorFamilies.families.length >= 2)) {
     if (colorGroups.length === 0) {
       throw new Error(
-        `${fileName}: color-mode: guided requires grouped brand-colors syntax — flat syntax is not sufficient. See the Minimum Structure section in the guided-colors spec.`,
+        `${fileName}: color-mode: guided requires grouped brand-colors syntax or a color-families block with at least two families — flat syntax alone is not sufficient.`,
       );
     }
     const primary = colorGroups.find(g => g.key === 'primary');
@@ -910,15 +1113,97 @@ export function parseBrandFile(content: string, fileName: string): ParsedBrand {
   //
   // 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)) {
-        theme[slot] = resolveThemeSlotValue(value, brandColors, fileName, slot);
+  //
+  // Pair themes: `ground:` + `figure:` (+ optional `text:`) derive every slot not written explicitly.
+  const themePairs: Record<string, ThemePair> = {};
+  const neutral = colorGroups.find(g => g.key === 'neutral');
+  const neutralText = ['dark', 'light']
+    .map(role => neutral?.entries.find(e => e.role === role)?.hex)
+    .filter((h): h is string => !!h);
+  for (const [name, theme] of Object.entries(themes)) {
+    const pairRaw: Partial<Record<typeof PAIR_KEYS[number], string>> = {};
+    for (const key of PAIR_KEYS) {
+      if (theme[key] !== undefined) { pairRaw[key] = theme[key]; delete theme[key]; }
+    }
+    for (const [slot, value] of Object.entries(theme)) {
+      theme[slot] = resolveThemeSlotValue(value, brandColors, fileName, slot);
+    }
+    if (Object.keys(pairRaw).length === 0) continue;
+    if (!pairRaw.ground || !pairRaw.figure) {
+      throw new Error(`${fileName}: theme "${name}" needs both "ground:" and "figure:" (pair theme), or neither`);
+    }
+    const solid = (key: string, value: string) => {
+      const hex = resolveThemeSlotValue(value, brandColors, fileName, key);
+      if (!isHex6(hex)) throw new Error(`${fileName}: theme "${name}" ${key} must be a solid 6-digit color, got "${value}"`);
+      return hex;
+    };
+    const ground = solid('ground', pairRaw.ground);
+    const figure = solid('figure', pairRaw.figure);
+    let text: string;
+    if (pairRaw.text) {
+      text = solid('text', pairRaw.text);
+    } else {
+      const resolved = resolveTextColor(ground, neutralText, rules);
+      text = resolved.text;
+      if (!resolved.passes) {
+        colorWarnings.push(`theme "${name}": no text color reaches ${rules.text}:1 on ${ground} — using ${text} (${resolved.ratio.toFixed(1)}:1)`);
+      }
+    }
+    themes[name] = { ...derivePairSlots(ground, figure, text), ...theme };
+    themePairs[name] = { ground, figure, text };
+  }
+
+  // Family pairs → checked; valid ones become themes named `{Family}-{n}` (n = declared position).
+  if (colorFamilies) {
+    const config = { order: colorFamilies.order, borrow: colorFamilies.borrow, distance: colorFamilies.distance };
+    colorFamilies.families.forEach((family, index) => {
+      const raw = familiesRaw[index];
+      raw.pairs.forEach((p, n) => {
+        const resolve = (value: string) => {
+          const hex = value.startsWith('$') ? (brandColors[value.slice(1)] ? normalizeHex(brandColors[value.slice(1)]) : null) : normalizeHex(value);
+          if (!hex || !isHex6(hex)) throw new Error(`${fileName}:${p.line}: pair color "${value}" is not a known 6-digit color`);
+          return hex;
+        };
+        const check = checkFamilyPair(resolve(p.ground), resolve(p.figure), index, colorFamilies!, config, rules, neutralText);
+        const themeName = `${family.name}-${n + 1}`;
+        if (check.valid) {
+          if (themes[themeName]) throw new Error(`${fileName}: family pair theme "${themeName}" collides with an authored theme`);
+          themes[themeName] = derivePairSlots(check.ground, check.figure, check.text);
+          themePairs[themeName] = { ground: check.ground, figure: check.figure, text: check.text, family: family.name };
+          family.pairs.push({ ...check, theme: themeName });
+          if (!check.textPasses) {
+            colorWarnings.push(`${themeName}: no text color reaches ${rules.text}:1 on ${check.ground} — using ${check.text} (${check.textRatio.toFixed(1)}:1)`);
+          }
+        } else {
+          family.pairs.push(check);
+          colorWarnings.push(`${themeName} (${check.ground} / ${check.figure}) rejected: ${check.reasons.join('; ')}`);
+        }
+      });
+    });
+  }
+
+  // Rule checks on every theme (only when the brand declares color-rules).
+  if (colorRulesDeclared) {
+    for (const [name, theme] of Object.entries(themes)) {
+      const bg = theme['background'];
+      if (!bg || !isHex6(bg)) continue;
+      const txt = theme['text-primary'];
+      if (txt && isHex6(txt) && contrastRatio(bg, txt) < rules.text && !themePairs[name]) {
+        colorWarnings.push(`theme "${name}": text-primary ${txt} on ${bg} is ${contrastRatio(bg, txt).toFixed(1)}:1, below ${rules.text}:1`);
+      }
+      const fig = theme['logo'];
+      if (fig && isHex6(fig) && contrastRatio(bg, fig) < rules.figure && !themePairs[name]?.family) {
+        colorWarnings.push(`theme "${name}": logo ${fig} on ${bg} is ${contrastRatio(bg, fig).toFixed(1)}:1, below ${rules.figure}:1`);
       }
     }
+  }
+
+  if (Object.keys(themes).length > 0) {
     result.themes = themes;
     result.themeDescriptions = themeDescriptions;
   }
+  if (Object.keys(themePairs).length > 0) result.themePairs = themePairs;
+  if (colorWarnings.length > 0) result.colorWarnings = colorWarnings;
   if (Object.keys(spacingRaw).length > 0) {
     result.spacing = {
       unit: spacingRaw['unit'] ?? 'cqmin',
@@ -1009,6 +1294,7 @@ export function parseBrandFile(content: string, fileName: string): ParsedBrand {
     if (raw.props['loop'] === 'true') def.loop = true;
     if (raw.props['gltf']) def.gltfSrc = raw.props['gltf'];
     if (raw.props['generator']) def.generator = raw.props['generator'];
+    if (raw.props['group']) def.group = raw.props['group'];
     // generator-params are stored as "generator-params.KEY" by the sub-block parser.
     const paramEntries: [string, number][] = [];
     for (const [k, v] of Object.entries(raw.props)) {
@@ -1019,6 +1305,13 @@ export function parseBrandFile(content: string, fileName: string): ParsedBrand {
       }
     }
     if (paramEntries.length > 0) def.generatorParams = Object.fromEntries(paramEntries);
+    // align-* sub-blocks are stored as "align-left.src" / "align-left.aspect".
+    for (const align of ['left', 'center', 'right'] as const) {
+      const src = raw.props[`align-${align}.src`];
+      if (!src) continue;
+      const aspect = raw.props[`align-${align}.aspect`];
+      def.alignVariants = { ...def.alignVariants, [align]: { src, ...(aspect ? { aspectRatio: parseFloat(aspect) } : {}) } };
+    }
     return def;
   };
   if (logosRaw.length > 0 || photosRaw.length > 0 || videosRaw.length > 0 || illustrationsRaw.length > 0) {

package/parser/colorSystem.ts

@@ -0,0 +1,270 @@
+/**
+ * Color system helpers — pair themes, color rules, color families.
+ *
+ * Pure functions shared by the parser (validation at parse time) and by
+ * consumers (guided generation, test views with live config overrides).
+ * Contrast math follows WCAG 2.x relative luminance.
+ */
+
+import type {
+  ColorRules,
+  ColorFamilies,
+  ColorFamily,
+  FamilyBorrow,
+  FamilyOrder,
+  ToneClass,
+  PairOrigin,
+  PairCheck,
+} from './types';
+
+// ── Contrast ────────────────────────────────────────────────────────────────
+
+const HEX6 = /^#[0-9a-fA-F]{6}$/;
+
+/** True for a 6-digit `#RRGGBB` string (the only form the contrast math accepts). */
+export function isHex6(value: string): boolean {
+  return HEX6.test(value);
+}
+
+/** WCAG relative luminance of a 6-digit hex. */
+export function relativeLuminance(hex: string): number {
+  const channel = (i: number) => {
+    const v = parseInt(hex.slice(i, i + 2), 16) / 255;
+    return v <= 0.03928 ? v / 12.92 : ((v + 0.055) / 1.055) ** 2.4;
+  };
+  return 0.2126 * channel(1) + 0.7152 * channel(3) + 0.0722 * channel(5);
+}
+
+/** WCAG contrast ratio between two 6-digit hex colors (1–21). */
+export function contrastRatio(a: string, b: string): number {
+  const la = relativeLuminance(a);
+  const lb = relativeLuminance(b);
+  const [hi, lo] = la >= lb ? [la, lb] : [lb, la];
+  return (hi + 0.05) / (lo + 0.05);
+}
+
+// ── Rules ───────────────────────────────────────────────────────────────────
+
+export const DEFAULT_COLOR_RULES: ColorRules = {
+  text: 4.5,
+  figure: 3,
+  avoid: [],
+  tones: [1.8, 4.5],
+};
+
+/** Tone class from contrast against white: below tones[0] light, at/above tones[1] dark. */
+export function toneClass(hex: string, tones: [number, number] = DEFAULT_COLOR_RULES.tones): ToneClass {
+  const vsWhite = contrastRatio(hex, '#FFFFFF');
+  if (vsWhite < tones[0]) return 'light';
+  if (vsWhite >= tones[1]) return 'dark';
+  return 'mid';
+}
+
+/** Rule violations for a ground/figure pair (empty = passes). Reach is checked separately. */
+export function pairRuleViolations(ground: string, figure: string, rules: ColorRules): string[] {
+  const reasons: string[] = [];
+  const ratio = contrastRatio(ground, figure);
+  if (ratio < rules.figure) {
+    reasons.push(`contrast ${ratio.toFixed(1)}:1 below ${rules.figure}:1`);
+  }
+  const tg = toneClass(ground, rules.tones);
+  const tf = toneClass(figure, rules.tones);
+  for (const [a, b] of rules.avoid) {
+    if ((tg === a && tf === b) || (tg === b && tf === a)) {
+      reasons.push(`${tg}+${tf} combination avoided`);
+      break;
+    }
+  }
+  return reasons;
+}
+
+// ── Pair themes ─────────────────────────────────────────────────────────────
+
+/** Alpha stops for the derived text tiers below text-primary. */
+const TEXT_TIERS: Array<[string, number]> = [
+  ['text-secondary', 0.85],
+  ['text-tertiary', 0.7],
+  ['text-subtle', 0.55],
+  ['text-muted', 0.4],
+];
+
+function withAlpha(hex: string, alpha: number): string {
+  const r = parseInt(hex.slice(1, 3), 16);
+  const g = parseInt(hex.slice(3, 5), 16);
+  const b = parseInt(hex.slice(5, 7), 16);
+  return `rgba(${r}, ${g}, ${b}, ${alpha})`;
+}
+
+/** Full theme slot map derived from a ground / figure / text triple. */
+export function derivePairSlots(ground: string, figure: string, text: string): Record<string, string> {
+  const slots: Record<string, string> = {
+    'background': ground,
+    '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']) {
+    slots[slot] = figure;
+  }
+  slots['sticker-fg'] = ground;
+  slots['label-fg'] = ground;
+  return slots;
+}
+
+/**
+ * Resolve the text color for a ground.
+ * `preferred` candidates are tried in order; the first reaching `rules.text` wins.
+ * When none passes, the highest-contrast preferred candidate is used (`passes: false`).
+ * Black/white are only considered when no preferred candidates exist.
+ */
+export function resolveTextColor(
+  ground: string,
+  preferred: string[],
+  rules: ColorRules,
+): { text: string; ratio: number; passes: boolean } {
+  const candidates = preferred.filter(isHex6);
+  const pool = candidates.length > 0 ? candidates : ['#000000', '#FFFFFF'];
+  for (const c of pool) {
+    const ratio = contrastRatio(ground, c);
+    if (ratio >= rules.text) return { text: c, ratio, passes: true };
+  }
+  let best = pool[0];
+  let bestRatio = contrastRatio(ground, best);
+  for (const c of pool.slice(1)) {
+    const ratio = contrastRatio(ground, c);
+    if (ratio > bestRatio) { best = c; bestRatio = ratio; }
+  }
+  return { text: best, ratio: bestRatio, passes: false };
+}
+
+// ── Families ────────────────────────────────────────────────────────────────
+
+export interface ReachConfig {
+  order: FamilyOrder;
+  borrow: FamilyBorrow;
+  distance: number;
+}
+
+/** Families reachable from `index` (excluding itself), labelled by direction. */
+export function reachableFamilies(count: number, index: number, config: ReachConfig): Map<number, 'prev' | 'next'> {
+  const reach = new Map<number, 'prev' | 'next'>();
+  if (config.borrow === 'none') return reach;
+  const wantPrev = config.borrow === 'previous' || config.borrow === 'both';
+  const wantNext = config.borrow === 'next' || config.borrow === 'both';
+  for (let d = 1; d <= config.distance; d++) {
+    if (wantPrev) {
+      const j = index - d;
+      if (j >= 0) reach.set(j, 'prev');
+      else if (config.order === 'cycle') reach.set(((j % count) + count) % count, 'prev');
+    }
+    if (wantNext) {
+      const j = index + d;
+      if (j < count) { if (!reach.has(j)) reach.set(j, 'next'); }
+      else if (config.order === 'cycle') { const w = j % count; if (!reach.has(w)) reach.set(w, 'next'); }
+    }
+  }
+  reach.delete(index);
+  return reach;
+}
+
+/** True when the reach config lets every family borrow from every other one. */
+export function reachCoversAll(count: number, config: ReachConfig): boolean {
+  if (count < 3) return false;
+  for (let i = 0; i < count; i++) {
+    if (reachableFamilies(count, i, config).size < count - 1) return false;
+  }
+  return true;
+}
+
+/** Where a color comes from, seen from family `index`. Null = not usable there. */
+export function colorOrigin(
+  hex: string,
+  index: number,
+  system: Pick<ColorFamilies, 'families' | 'shared'>,
+  config: ReachConfig,
+): PairOrigin | null {
+  const families = system.families;
+  if (families[index]?.colors.some(c => c.hex === hex)) return 'own';
+  if (system.shared.some(s => s.hex === hex)) return 'shared';
+  const reach = reachableFamilies(families.length, index, config);
+  for (const [j, dir] of reach) {
+    if (families[j].colors.some(c => c.hex === hex)) return dir;
+  }
+  return null;
+}
+
+/** 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;
+}
+
+/** Text candidates for a family ground: its contrast color(s), then shared colors, then extras. */
+export function familyTextCandidates(family: ColorFamily, shared: Array<{ hex: string }>, extra: string[] = []): string[] {
+  const out: string[] = [];
+  for (const c of family.colors) if (c.role === 'contrast') out.push(c.hex);
+  for (const s of shared) out.push(s.hex);
+  for (const e of extra) out.push(e);
+  return [...new Set(out)];
+}
+
+/** Validate one ground/figure pair for family `index` against reach + rules. */
+export function checkFamilyPair(
+  ground: string,
+  figure: string,
+  index: number,
+  system: ColorFamilies,
+  config: ReachConfig,
+  rules: ColorRules,
+  extraTextCandidates: string[] = [],
+): PairCheck {
+  const reasons: string[] = [];
+  const origins: [PairOrigin | null, PairOrigin | null] = [
+    colorOrigin(ground, index, system, config),
+    colorOrigin(figure, index, system, config),
+  ];
+  for (const [hex, origin] of [[ground, origins[0]], [figure, origins[1]]] as const) {
+    if (origin === null) {
+      const owner = owningFamily(hex, system.families);
+      reasons.push(owner ? `${hex} from ${owner} is out of reach` : `${hex} is not in any family or shared`);
+    }
+  }
+  reasons.push(...pairRuleViolations(ground, figure, rules));
+  const family = system.families[index];
+  const text = resolveTextColor(ground, familyTextCandidates(family, system.shared, extraTextCandidates), rules);
+  return {
+    ground,
+    figure,
+    text: text.text,
+    figureRatio: contrastRatio(ground, figure),
+    textRatio: text.ratio,
+    textPasses: text.passes,
+    tones: [toneClass(ground, rules.tones), toneClass(figure, rules.tones)],
+    origins: [origins[0] ?? 'outside', origins[1] ?? 'outside'],
+    valid: reasons.length === 0,
+    reasons,
+  };
+}
+
+/** Every ordered ground/figure pair available to family `index`, checked. */
+export function enumerateFamilyPairs(
+  index: number,
+  system: ColorFamilies,
+  config: ReachConfig,
+  rules: ColorRules,
+  extraTextCandidates: string[] = [],
+): PairCheck[] {
+  const pool = new Set<string>();
+  for (const c of system.families[index].colors) pool.add(c.hex);
+  for (const s of system.shared) pool.add(s.hex);
+  for (const j of reachableFamilies(system.families.length, index, config).keys()) {
+    for (const c of system.families[j].colors) pool.add(c.hex);
+  }
+  const colors = [...pool];
+  const out: PairCheck[] = [];
+  for (const g of colors) {
+    for (const f of colors) {
+      if (g === f) continue;
+      out.push(checkFamilyPair(g, f, index, system, config, rules, extraTextCandidates));
+    }
+  }
+  return out;
+}

package/parser/index.ts

@@ -6,7 +6,24 @@ export { parseIdentityFile } from './identityParser';
 export type { ParsedIdentity, ParsedVoice, ParsedPillars, ParsedAudience, ParsedAntiAudience, ParsedValue } from './identityParser';
 
 export { parseBrandFile } from './brandParser';
-export type { ParsedBrand, ParsedFontDef, ParsedTypographyDef, ParsedDividerDef, BrandColorPrintSpec, ParsedAssetDef, ParsedBadgeStyle } from './brandParser';
+export {
+  contrastRatio,
+  relativeLuminance,
+  toneClass,
+  isHex6,
+  pairRuleViolations,
+  derivePairSlots,
+  resolveTextColor,
+  reachableFamilies,
+  reachCoversAll,
+  colorOrigin,
+  familyTextCandidates,
+  checkFamilyPair,
+  enumerateFamilyPairs,
+  DEFAULT_COLOR_RULES,
+} from './colorSystem';
+export type { ReachConfig } from './colorSystem';
+export type { ParsedBrand, ParsedFontDef, ParsedTypographyDef, ParsedDividerDef, BrandColorPrintSpec, ParsedAssetDef, ParsedBadgeStyle, LogoAlign } from './brandParser';
 export type {
   ColorMode,
   PaletteStrategy,
@@ -19,6 +36,18 @@ export type {
   NeutralRole,
   BrandColorEntry,
   BrandColorGroup,
+  ToneClass,
+  ColorRules,
+  FamilyOrder,
+  FamilyBorrow,
+  FamilyRole,
+  FamilyColor,
+  PairOrigin,
+  PairCheck,
+  FamilyPair,
+  ColorFamily,
+  ColorFamilies,
+  ThemePair,
 } from './types';
 
 export { parseFormatFile } from './formatParser';

package/parser/types.ts

@@ -92,3 +92,88 @@ export interface BrandColorGroup {
   entries: BrandColorEntry[];
 }
 
+
+// ── Color rules, pair themes, color families (v0.10.0) ────────────────────────
+
+/** Tone class of a color, from its contrast against white. */
+export type ToneClass = 'light' | 'mid' | 'dark';
+
+/** Brand-wide contrast and tone rules. */
+export interface ColorRules {
+  /** Min contrast for text on ground. */
+  text: number;
+  /** Min contrast between ground and figure. */
+  figure: number;
+  /** Tone combinations a pair must not form (unordered). */
+  avoid: Array<[ToneClass, ToneClass]>;
+  /** Tone thresholds as contrast vs white: [light below, dark at/above]. */
+  tones: [number, number];
+}
+
+/** How families are arranged. */
+export type FamilyOrder = 'cycle' | 'sequence';
+/** Which neighbours a family may borrow from. */
+export type FamilyBorrow = 'previous' | 'next' | 'both' | 'none';
+/** Fixed role vocabulary inside a family. */
+export type FamilyRole = 'core' | 'accent' | 'contrast';
+
+/** One color declared inside a family. */
+export interface FamilyColor {
+  role: FamilyRole;
+  /** 6-digit uppercase hex. */
+  hex: string;
+  /** Display name (authored, or generated as `{family}-{role}[-n]`). */
+  name: string;
+  /** Key in the flat `brandColors` projection. */
+  key: string;
+}
+
+/** Where a pair color comes from, seen from the pair's family. */
+export type PairOrigin = 'own' | 'prev' | 'next' | 'shared' | 'outside';
+
+/** A checked ground/figure pair. */
+export interface PairCheck {
+  ground: string;
+  figure: string;
+  /** Resolved text color for this ground. */
+  text: string;
+  figureRatio: number;
+  textRatio: number;
+  /** False when no text candidate reaches the text rule (best one is used). */
+  textPasses: boolean;
+  tones: [ToneClass, ToneClass];
+  origins: [PairOrigin, PairOrigin];
+  valid: boolean;
+  /** Why the pair fails (empty when valid). */
+  reasons: string[];
+}
+
+/** A curated pair as declared in a family's `pairs` block. */
+export interface FamilyPair extends PairCheck {
+  /** Theme name the pair was emitted as (only when valid), e.g. `Winter-3`. */
+  theme?: string;
+}
+
+export interface ColorFamily {
+  name: string;
+  colors: FamilyColor[];
+  pairs: FamilyPair[];
+}
+
+export interface ColorFamilies {
+  order: FamilyOrder;
+  borrow: FamilyBorrow;
+  distance: number;
+  /** Colors allowed in every family (resolved from `shared:` refs). */
+  shared: Array<{ name: string; hex: string }>;
+  families: ColorFamily[];
+}
+
+/** Ground / figure / text of a pair theme (declared or emitted from a family pair). */
+export interface ThemePair {
+  ground: string;
+  figure: string;
+  text: string;
+  /** Family the theme was emitted from, when it came from `color-families`. */
+  family?: string;
+}