@nurix/etna 0.19.3 → 0.19.4

package/data/harnesses/code/skills/design/scripts/lib/checks.mjs

@@ -1,6 +1,7 @@
 // skills/design/scripts/lib/checks.mjs — the machine-check engine (beam 2, D19): every detector=source catalog rule as pure regex/token analysis over .tsx/.ts/.css/.html text, plus the lever-manifest drift check (cod-02, D10) whose vocabulary is read from the project's design-tokens artifact (design.tokens.json). Pure library — no argv, no CLI banner, no process.exit; fired at structural boundaries by phase-gate.mjs, preship-sweep.mjs, and self-integrity.mjs. Findings are [{rule, file, line, excerpt, fix}].
 import { readFileSync, existsSync, readdirSync, statSync } from 'node:fs';
 import { join } from 'node:path';
+import { findBudgetStamps, MOTION_STAGGER_CLASS, STAGGER_CHILD_CAP } from './vocabulary.mjs';
 
 // ---------------------------------------------------------------------------
 // File-type routing
@@ -123,6 +124,32 @@ function normColor(lit) {
 // ---------------------------------------------------------------------------
 
 const RE_COLOR_LITERAL = /#[0-9a-fA-F]{3,8}\b|rgba?\([^)]*\)|hsla?\([^)]*\)|oklch\([^)]*\)/g;
+
+// CSS generic + system family keywords — never counted as declared app families (typ-06);
+// narrower than SYSTEM_FONT_KEYWORDS, whose web-safe named fonts (Roboto, Arial…) DO count.
+const GENERIC_FAMILY_KEYWORDS = new Set([
+  'sans-serif', 'serif', 'monospace', 'cursive', 'fantasy', 'math', 'emoji', 'fangsong',
+  'system-ui', 'ui-sans-serif', 'ui-serif', 'ui-monospace', 'ui-rounded',
+  '-apple-system', 'blinkmacsystemfont', 'sfmono-regular',
+]);
+
+// Base signature of a color literal — the first three channels with the alpha slot stripped,
+// hex unified onto rgb — so an emitted color whose alpha rides var()/calc() (the intensity-
+// multiplied shadow layers, which RE_COLOR_LITERAL truncates mid-calc) can still be matched
+// against the manifest vocabulary.
+function colorBaseSig(lit) {
+  const s = lit.trim().toLowerCase();
+  if (/^#[0-9a-f]{3,8}$/.test(s)) {
+    const h = expandHex(s);
+    return `rgb:${parseInt(h.slice(0, 2), 16)},${parseInt(h.slice(2, 4), 16)},${parseInt(h.slice(4, 6), 16)}`;
+  }
+  const fn = s.match(/^(rgba?|hsla?|oklch)\(([^/)]*)/);
+  if (!fn) return null;
+  const nums = fn[2].match(/-?\d*\.?\d+%?/g);
+  if (!nums || nums.length < 3) return null;
+  const kind = fn[1].startsWith('rgb') ? 'rgb' : fn[1].startsWith('hsl') ? 'hsl' : 'oklch';
+  return `${kind}:${nums.slice(0, 3).join(',')}`;
+}
 const TW_UTILITY = '(?:bg|text|border|ring|ring-offset|fill|stroke|from|via|to|outline|divide|decoration|caret|accent|placeholder|shadow)';
 const PALETTE_HUES = 'red|orange|amber|yellow|lime|green|emerald|teal|cyan|sky|blue|indigo|violet|purple|fuchsia|pink|rose|slate|gray|grey|zinc|neutral|stone';
 const RE_PALETTE_CLASS = new RegExp(`\\b${TW_UTILITY}-(${PALETTE_HUES})-(\\d{2,3})\\b`, 'g');
@@ -244,7 +271,10 @@ export function checkLine(add, file, ext, lineNo, line, fileText) {
   {
     const neg = line.match(/(?:letter-spacing\s*:\s*|tracking-\[)(-?\d*\.?\d+)em/);
     if (neg && parseFloat(neg[1]) < -0.04) add('typ-08', file, lineNo, neg[0], 'Letter-spacing never below the -0.04em floor.');
-    if (/tracking-tighter\b/.test(line)) add('typ-08', file, lineNo, 'tracking-tighter', 'tracking-tighter (-0.05em) is below the -0.04em floor; use tracking-tight at most.');
+    // A `--tracking-tighter: var(…)` @theme line REMAPS the utility onto an authored token —
+    // that definition is the fix for this rule, not a violation; literal values still fall
+    // to the numeric floor check above.
+    if (/\btracking-tighter\b/.test(line) && !/--tracking-tighter\s*:\s*var\(/.test(line)) add('typ-08', file, lineNo, 'tracking-tighter', 'tracking-tighter (-0.05em) is below the -0.04em floor; use tracking-tight at most.');
     if (/\buppercase\b/.test(line) && !/tracking-(?:wide|wider|widest|\[)/.test(line)) add('typ-08', file, lineNo, 'uppercase', 'All-caps micro-labels carry positive tracking (>= 0.02em, caps band 0.05-0.12em); add tracking-wide.');
   }
   // typ-09: viewport-fluid font sizing.
@@ -406,6 +436,35 @@ export function checkLine(add, file, ext, lineNo, line, fileText) {
       if (d > 0 && (d < 150 || d > 300)) add('mot-07', file, lineNo, m[0], 'Loading-indicator delay sits in the 150-300ms band (nothing appears under 500ms).');
     }
   }
+  // mot-08 (numeric half): the per-item stagger unit holds the 0-60ms band, a declared cascade never
+  // reaches past the child cap, and no stagger delay lands at or over the 1s sequence ceiling. Child
+  // count and the actual total are confirmed on the rendered DOM at the render rung.
+  {
+    const unit = line.match(/--stagger-unit\s*:\s*(-?\d*\.?\d+)ms/);
+    if (unit && (parseFloat(unit[1]) < 0 || parseFloat(unit[1]) > 60)) {
+      add('mot-08', file, lineNo, unit[0], 'The stagger-unit token holds 0-60ms per item; pull the unit back into the band.');
+    }
+    const idxDelay = line.match(/(?:animationDelay|animation-delay|transitionDelay|transition-delay)[^;,}]*?(?:\b(?:i|idx|index)\s*\*\s*(\d*\.?\d+)|(\d*\.?\d+)\s*\*\s*(?:i|idx|index)\b)/);
+    if (idxDelay && parseFloat(idxDelay[1] ?? idxDelay[2]) > 60) {
+      add('mot-08', file, lineNo, idxDelay[0].slice(0, 60), 'Per-item stagger delay exceeds the 0-60ms unit band; derive it from the stagger-unit token (0-60ms).');
+    }
+    const calcUnit = line.match(/(?:animation|transition)-delay\s*:\s*calc\(\s*(\d*\.?\d+)ms\s*\*/);
+    if (calcUnit && parseFloat(calcUnit[1]) > 60) {
+      add('mot-08', file, lineNo, calcUnit[0], 'Per-item stagger delay exceeds the 0-60ms unit band; ride the stagger-unit token instead of a raw multiplier.');
+    }
+    if (/(?:animation|transition)-delay/.test(line)) {
+      const nth = line.match(/nth-child\((\d+)\)/);
+      if (nth && parseInt(nth[1], 10) > STAGGER_CHILD_CAP) {
+        add('mot-08', file, lineNo, nth[0], `Stagger cascades cap at ${STAGGER_CHILD_CAP} children; children past the cap arrive together.`);
+      }
+      if (/stagger|nth-child/i.test(line)) {
+        for (const m of line.matchAll(/(?:animation|transition)-delay\s*:\s*(\d*\.?\d+)(ms|s)\b/g)) {
+          const ms = m[2] === 's' ? parseFloat(m[1]) * 1000 : parseFloat(m[1]);
+          if (ms >= 1000) add('mot-08', file, lineNo, m[0], 'A stagger sequence totals under 1s; this per-item delay alone reaches the ceiling.');
+        }
+      }
+    }
+  }
   // mot-09: scroll-event listener driving animation.
   if (/addEventListener\(\s*["']scroll["']/.test(line)) add('mot-09', file, lineNo, 'addEventListener("scroll")', 'Ban scroll-event listeners for animation; use IntersectionObserver or scroll-linked scrubbing.');
   // mot-10: useState fed by a continuous scroll/pointer value.
@@ -561,6 +620,30 @@ export function checkFile(add, file, ext, text, lines) {
     }
   }
 
+  // typ-20 / col-16 / mot-08 (orchestration half): budget-gated vocabulary against the surface's
+  // budget stamp (lib/vocabulary.mjs). The display ramp step, wash consumption, and arrival cascades
+  // are legal only on a file stamped brand-forward; a baseline-stamped or unstamped file consuming
+  // them is the deterministic violation. Fired at the surfaces gate and the preship sweep through
+  // this shared engine.
+  if (ext === 'tsx' || ext === 'html') {
+    const brandForward = findBudgetStamps(text).includes('brand-forward');
+    const lineOf = (idx) => text.slice(0, idx).split('\n').length;
+    const displayUses = [...text.matchAll(/\btext-display\b|var\(--text-display\b/g)];
+    if (displayUses.length && !brandForward) {
+      add('typ-20', file, lineOf(displayUses[0].index), displayUses[0][0], 'The display ramp step appears only on surfaces stamped brand-forward; re-classify the surface with a recorded reason, or step this element down the ramp (text-h1).');
+    } else if (displayUses.length > 1) {
+      add('typ-20', file, lineOf(displayUses[1].index), `${displayUses.length} display-step elements`, 'At most one display-step element per surface; keep the focal one and step the rest down the ramp.');
+    }
+    const washUse = text.match(/var\(--wash-[a-z-]+\)/);
+    if (washUse && !brandForward) {
+      add('col-16', file, lineOf(washUse.index), washUse[0], 'A wash token is consumed only on brand-forward-stamped surfaces; re-classify the surface with a recorded reason, or remove the wash.');
+    }
+    const staggerUse = text.match(new RegExp(`\\b${MOTION_STAGGER_CLASS}\\b`));
+    if (staggerUse && !brandForward) {
+      add('mot-08', file, lineOf(staggerUse.index), staggerUse[0], 'Baseline-stamped surfaces skip arrival cascades; remove motion-stagger, or re-classify the surface with a recorded reason.');
+    }
+  }
+
   // int-01: a :focus / :focus-visible CSS rule that removes the outline with no visible ring replacement.
   if (ext === 'css') {
     for (const m of text.matchAll(/:focus(?:-visible)?\s*\{([^}]*)\}/g)) {
@@ -576,8 +659,10 @@ export function checkFile(add, file, ext, text, lines) {
     add('int-10', file, text.slice(0, text.search(/setInterval\(/)).split('\n').length, 'polling status update without aria-live', 'An aria-live region is present wherever async status updates render; wrap the live status in role="status" / aria-live="polite".');
   }
 
-  // cod-01: a token-defining CSS file that omits some of the 34 consumed tokens.
-  if (ext === 'css' && /--background\b/.test(text) && /--foreground\b/.test(text)) {
+  // cod-01: a token-defining CSS file that omits some of the 36 consumed tokens. The trigger
+  // requires DEFINITIONS at property position — a consumer file's `--color-background: var(--background)`
+  // @theme mapping must not read as a token-defining file.
+  if (ext === 'css' && /^\s*--background\s*:/m.test(text) && /^\s*--foreground\s*:/m.test(text)) {
     const missing = REQUIRED_TOKENS.filter((t) => !new RegExp(`--${t}\\s*:`).test(text));
     if (missing.length) add('cod-01', file, 1, `missing tokens: ${missing.slice(0, 6).join(', ')}${missing.length > 6 ? '…' : ''}`, 'Emitted CSS defines every token the substrate consumes; add the missing --token definitions.');
   }
@@ -599,6 +684,7 @@ export function checkFile(add, file, ext, text, lines) {
 const REQUIRED_TOKENS = [
   'background', 'foreground', 'card', 'card-foreground', 'muted', 'muted-foreground', 'border', 'input', 'ring',
   'primary', 'primary-foreground', 'accent', 'accent-foreground', 'destructive', 'destructive-foreground', 'success', 'warning',
+  'surface-raised', 'surface-overlay',
   'popover', 'popover-foreground', 'secondary', 'secondary-foreground',
   'chart-1', 'chart-2', 'chart-3', 'chart-4', 'chart-5',
   'sidebar', 'sidebar-foreground', 'sidebar-primary', 'sidebar-primary-foreground',
@@ -611,8 +697,10 @@ const REQUIRED_TOKENS = [
 
 // Run the checks that need the whole passed-in file set (token-set counts, distinct sizes).
 export function checkCrossFile(add, docs) {
-  // typ-06: more than two font families declared across the passed files.
+  // typ-06: more than three font families declared across the passed files (fourth banned), or three
+  // families none of which carries the numeric-mono job.
   const families = new Set();
+  const monoFamilies = new Set();
   const iconLibs = new Set();
   const explicitSizes = new Map(); // px -> {file,line,text}
   const hexByHue = new Map();      // hue bucket -> Set(normHex)
@@ -622,11 +710,17 @@ export function checkCrossFile(add, docs) {
 
   for (const d of docs) {
     d.lines.forEach((line, i) => {
-      // font families from declarations / --font-* / font-[Family]
-      for (const m of line.matchAll(/font-family\s*:\s*([^;{}]+)[;}]?|--font-[\w-]+\s*:\s*([^;]+);|font-\[["']?([A-Za-z][\w\s-]+)["']?\]/g)) {
+      // font families from declarations / --font-* family slots / font-[Family].
+      // --font-weight-*/--font-size-* carry numbers, not families; a stack whose first entry
+      // is a CSS generic (the emitted baseline's generics-only stacks) declares no family.
+      for (const m of line.matchAll(/font-family\s*:\s*([^;{}]+)[;}]?|--font-(?!weight-|size-)[\w-]+\s*:\s*([^;]+);|font-\[["']?([A-Za-z][\w\s-]+)["']?\]/g)) {
         const raw = (m[1] || m[2] || m[3] || '').trim();
         const first = raw.split(',')[0].replace(/["']/g, '').trim().toLowerCase();
-        if (first && !/^var\(/.test(first)) families.add(first);
+        if (first && !/^var\(/.test(first) && !GENERIC_FAMILY_KEYWORDS.has(first)) {
+          families.add(first);
+          // The numeric-mono job: declared as the mono slot or stacked onto a monospace generic.
+          if (/^--font-mono/.test(m[0]) || /\b(?:ui-)?monospace\b/i.test(raw)) monoFamilies.add(first);
+        }
       }
       // icon libraries from imports
       const imp = line.match(/from\s+["'](lucide-react|@heroicons\/\w+|react-icons(?:\/\w+)?|@phosphor-icons\/\w+|phosphor-react)["']/);
@@ -651,9 +745,19 @@ export function checkCrossFile(add, docs) {
     });
   }
 
-  if (families.size > 2) {
+  if (families.size > 3) {
+    const d = docs[0];
+    add('typ-06', d.file, 1, `${families.size} font families: ${[...families].join(', ')}`, 'At most three font families per app, each with a distinct job (display / body / numeric-mono); a fourth family is banned — drop the extra.');
+  } else if (families.size === 3 && monoFamilies.size === 0) {
     const d = docs[0];
-    add('typ-06', d.file, 1, `${families.size} font families: ${[...families].join(', ')}`, 'At most two font families per app (a sans and a mono); drop the extra family.');
+    add('typ-06', d.file, 1, `3 font families, none mono: ${[...families].join(', ')}`, 'Three families need three distinct jobs (display / body / numeric-mono); none of these is a declared mono — give the third family a real job or drop it.');
+  }
+
+  // typ-06 (scale half): distinct explicit sizes beyond the declared ramp's step count.
+  if (explicitSizes.size > 7) {
+    const anchorPx = [...explicitSizes.keys()].sort((a, b) => a - b)[7];
+    const anc = explicitSizes.get(anchorPx);
+    add('typ-06', anc.file, anc.line, `${explicitSizes.size} distinct explicit sizes`, 'The type scale holds the declared ramp\'s steps (<= 7); collapse the extras onto the ramp utilities (text-h1 … text-display).');
   }
 
   // typ-10: adjacent explicitly-declared type-scale steps closer than 25%.
@@ -709,6 +813,56 @@ export function checkSpacingScale(add, docs) {
   }
 }
 
+// CSS generic families, the ui-* keywords, and the conventional OS fallback faces that need no
+// package to render — the only stack entries cod-16 accepts without a registering import/@font-face.
+// Exported so the fail-closed cod-16 gate at derive-personality --emit (stack vs package.json
+// binding) reads the same vocabulary as this source shell.
+export const SYSTEM_FONT_KEYWORDS = new Set([
+  'sans-serif', 'serif', 'monospace', 'cursive', 'fantasy', 'math', 'emoji', 'fangsong',
+  'system-ui', 'ui-sans-serif', 'ui-serif', 'ui-monospace', 'ui-rounded',
+  '-apple-system', 'blinkmacsystemfont', 'segoe ui', 'roboto', 'helvetica', 'helvetica neue', 'arial',
+  'sfmono-regular', 'sf mono', 'menlo', 'consolas', 'courier new', 'liberation mono', 'monaco',
+  'georgia', 'times new roman', 'inherit', 'initial', 'unset',
+]);
+
+// Slugify a family name the way a fontsource package specifier spells it ("Inter Variable" -> inter).
+export function familySlug(name) {
+  return name.toLowerCase().replace(/\s+variable$/, '').trim().replace(/[^a-z0-9]+/g, '-');
+}
+
+// cod-16 (source shell): every named family in an emitted font stack binds to a registered family or
+// a system generic. Registration is an @font-face declaring the family or an @import whose package
+// specifier carries the family's slug (@fontsource/<slug>). The check arms only when the passed file
+// set carries at least one registration — the no-fonts-css-at-all case belongs to the fail-closed
+// package.json binding at derive-personality --emit, which owns this rule's gate.
+export function checkFontBinding(add, docs) {
+  const cssDocs = docs.filter((d) => d.ext === 'css');
+  const importSpecs = [];
+  const registered = new Set();
+  for (const d of cssDocs) {
+    for (const m of d.text.matchAll(/@import\s+(?:url\(\s*)?["']([^"']+)["']/g)) importSpecs.push(m[1].toLowerCase());
+    for (const m of d.text.matchAll(/@font-face\s*\{[^}]*font-family\s*:\s*["']?([^;"'}]+)/g)) registered.add(m[1].trim().toLowerCase());
+  }
+  if (!importSpecs.length && !registered.size) return;
+  const isBound = (name) => {
+    const n = name.toLowerCase();
+    if (SYSTEM_FONT_KEYWORDS.has(n) || registered.has(n)) return true;
+    const slug = familySlug(name);
+    return slug !== '' && importSpecs.some((spec) => spec.includes(`/${slug}`) || spec === slug);
+  };
+  for (const d of cssDocs) {
+    d.lines.forEach((line, i) => {
+      for (const m of line.matchAll(/(?:--font-[\w-]+|font-family)\s*:\s*([^;}]+)/g)) {
+        for (const fam of m[1].split(',')) {
+          const name = fam.replace(/["']/g, '').trim();
+          if (!name || /^var\(/.test(name)) continue;
+          if (!isBound(name)) add('cod-16', d.file, i + 1, name, `Font family "${name}" binds to nothing installed: add its registering @fontsource import (or @font-face) to the emitted CSS, or fall back to a system generic.`);
+        }
+      }
+    });
+  }
+}
+
 // Bucket a 6-digit hex into a coarse hue family name for shade counting.
 function hexHueBucket(hex) {
   const h = expandHex(hex);
@@ -808,7 +962,37 @@ export function loadManifestVocab(manifestPath) {
   const strokeToken = primitive['icon-stroke'] ? resolveAlias(root, primitive['icon-stroke']) : null;
   const iconStroke = strokeToken && typeof strokeToken.$value === 'number' ? strokeToken.$value : null;
 
-  return { colors, spacing, radius, durations, fonts, iconStroke };
+  // The v2 elevation/wash vocabularies: every color literal inside a shadow composite's or a wash
+  // gradient's preserved .css enters the color allowlist — both as the drift extractor will match it
+  // in emitted CSS (the raw RE_COLOR_LITERAL slice) and as the layer's own typed hex — so consuming
+  // the artifact's designed shadows/washes never reads as drift.
+  const addExpressiveGroup = (group) => {
+    for (const token of Object.values(group || {})) {
+      if (!token || typeof token !== 'object') continue;
+      const css = preservedCss(token);
+      if (css) {
+        for (const m of css.matchAll(RE_COLOR_LITERAL)) colors.add(normColor(m[0]));
+      }
+      const layers = Array.isArray(token.$value) ? token.$value : [];
+      for (const layer of layers) {
+        const c = layer && (layer.color || null);
+        if (c && typeof c === 'object' && typeof c.hex === 'string') colors.add(normColor(c.hex));
+      }
+    }
+  };
+  addExpressiveGroup(root.elevation);
+  addExpressiveGroup(root.wash);
+
+  // Alpha-stripped base signatures of every manifest color, plus the emitter's fixed neutral
+  // hairline base rgb(15 23 42) (the 2xs/xs shadow utilities the library leans on) — consulted
+  // only for literals whose alpha slot rides var()/calc(), where exact normalization is defeated.
+  const colorBases = new Set(['rgb:15,23,42']);
+  for (const c of colors) {
+    const b = colorBaseSig(c);
+    if (b) colorBases.add(b);
+  }
+
+  return { colors, spacing, radius, durations, fonts, iconStroke, colorBases };
 }
 
 // Flag any color/spacing/radius/duration/font literal in the diff files outside the manifest vocabulary (cod-02).
@@ -822,7 +1006,11 @@ export function checkDrift(add, docs, vocab) {
       // colors
       if (vocab.colors.size) {
         for (const m of line.matchAll(RE_COLOR_LITERAL)) {
-          if (!vocab.colors.has(normColor(m[0]))) add('cod-02', d.file, i + 1, m[0], "Value drifts from the lever manifest; use a color already in the artifact's color tokens, not a fresh literal.");
+          if (vocab.colors.has(normColor(m[0]))) continue;
+          // A var()/calc() alpha slot truncates the regex match mid-function and defeats exact
+          // normalization; such intensity-riding literals match on their base channels instead.
+          if (/(?:var|calc)\(/.test(m[0]) && vocab.colorBases && vocab.colorBases.has(colorBaseSig(m[0]))) continue;
+          add('cod-02', d.file, i + 1, m[0], "Value drifts from the lever manifest; use a color already in the artifact's color tokens, not a fresh literal.");
         }
       }
       // spacing (explicit only)
@@ -871,6 +1059,7 @@ export function checkDocs(docs, { vocab = null } = {}) {
   }
   checkCrossFile(sink.add, docs);
   checkSpacingScale(sink.add, docs);
+  checkFontBinding(sink.add, docs);
   if (vocab) checkDrift(sink.add, docs, vocab);
   // Stable sort: by file, then line, then rule id.
   sink.list.sort((a, b) => a.file.localeCompare(b.file) || a.line - b.line || a.rule.localeCompare(b.rule));

package/data/harnesses/code/skills/design/scripts/lib/vocabulary.mjs

@@ -0,0 +1,65 @@
+// skills/design/scripts/lib/vocabulary.mjs — single-source shared runtime vocabulary for the design skill's scripts: the delight-budget enum + file-header stamps, the surface-archetype budget defaults, the motion-moment class names, and the theme attribute convention. scaffold.mjs writes these strings; phase-gate.mjs reads them at the surfaces gate; the preship sweep and emission read them in later steps. One module so the stamp text, the enum, and the theme names never drift between the writer and its readers.
+
+// The two delight-budget values a surface can carry (references/structure.md, the delight budget).
+export const BUDGETS = ['baseline', 'brand-forward'];
+
+// The verbatim file-header comment scaffold.mjs writes at the top of each surface route file, keyed by budget.
+export const BUDGET_STAMPS = {
+  baseline: '// Surface: baseline',
+  'brand-forward': '// Surface: brand-forward (delight-allowing)',
+};
+
+// The stamp comment for a budget, or null when it is not one of BUDGETS.
+export function stampFor(budget) {
+  return Object.prototype.hasOwnProperty.call(BUDGET_STAMPS, budget) ? BUDGET_STAMPS[budget] : null;
+}
+
+// Matches any `// Surface:` header line, well-formed or not — gates count these to catch a malformed
+// or duplicated stamp against the well-formed matches below.
+export const BUDGET_STAMP_LOOSE_RE = /\/\/ Surface:.*/g;
+
+// Every well-formed budget stamp in a source blob, in order, as budget values ('baseline' | 'brand-forward').
+// Gates count occurrences (exactly one per route file) and read the stamped budget from this.
+export function findBudgetStamps(source) {
+  const re = /\/\/ Surface: (brand-forward \(delight-allowing\)|baseline)(?=\s|$)/g;
+  const found = [];
+  let m;
+  while ((m = re.exec(String(source))) !== null) {
+    found.push(m[1].startsWith('brand-forward') ? 'brand-forward' : 'baseline');
+  }
+  return found;
+}
+
+// Surface archetypes whose delight budget defaults to `baseline` — a `brand-forward` stamp on one of
+// these needs a recorded reason in the surface map (references/structure.md, the delight budget).
+export const BASELINE_DEFAULT_ARCHETYPES = ['list-detail', 'log-stream', 'command-center'];
+
+// Surface archetypes that are `brand-forward` *candidates* — granted when the look's delight is
+// expressive or the brief asks for presence, else baseline; no recorded reason needed either way.
+export const BRAND_FORWARD_CANDIDATE_ARCHETYPES = ['dashboard', 'entity-detail', 'create-edit'];
+
+// True when a `brand-forward` stamp on this archetype requires a recorded reason in the surface map.
+export function requiresBudgetReason(archetype, budget) {
+  return budget === 'brand-forward' && BASELINE_DEFAULT_ARCHETYPES.includes(String(archetype));
+}
+
+// Motion-moment CSS classes (references/structure.md the delight budget; data/combinations/motion.csv).
+// scaffold consumes them where the archetype calls: table rows ride motion-lift (hover feedback,
+// budget-free); card grids ride motion-stagger on brand-forward surfaces only — baseline-stamped
+// surfaces skip arrival cascades (mot-08). The render rung audits rendered stagger containers.
+export const MOTION_LIFT_CLASS = 'motion-lift';
+export const MOTION_STAGGER_CLASS = 'motion-stagger';
+// The derived custom property the stagger cascade reads; cap the staggered children at STAGGER_CHILD_CAP.
+export const STAGGER_DELAY_VAR = '--stagger-delay';
+export const STAGGER_CHILD_CAP = 8;
+
+// The theme runtime attribute: its name and the two legal rendered values. look.theme `both` boots
+// light with a working toggle, so the emitted default is always one of these two.
+export const THEME_ATTR = 'data-theme';
+export const THEME_VALUES = ['light', 'dark'];
+
+// Resolve a look.theme (light | dark | both) to the emitted default data-theme value (both → light);
+// anything unrecognized falls back to light.
+export function resolveThemeDefault(theme) {
+  return theme === 'dark' ? 'dark' : 'light';
+}

package/data/harnesses/code/skills/design/scripts/phase-gate.mjs

@@ -4,12 +4,20 @@ import { join, dirname, resolve, relative } from 'node:path';
 import { fileURLToPath } from 'node:url';
 import { spawnSync } from 'node:child_process';
 import { runChecks, formatFindings, walkUiFiles } from './lib/checks.mjs';
+import { findBudgetStamps, BUDGET_STAMP_LOOSE_RE, requiresBudgetReason } from './lib/vocabulary.mjs';
 
 const SCRIPT_DIR = dirname(fileURLToPath(import.meta.url));
 const PHASES = ['intake', 'structure', 'scaffold', 'tokens', 'fixtures', 'surfaces'];
 const ARCHETYPES = new Set(['list-detail', 'dashboard', 'entity-detail', 'create-edit', 'log-stream', 'command-center']);
 const PROVENANCE = new Set(['project', 'extracted', 'library', 'default']);
 const STATE_SYNONYMS = { loading: ['loading', 'skeleton'], empty: ['empty'], error: ['error'], partial: ['partial', 'degraded', 'stale'] };
+// The intake look block's enums (references/create.md, the look block). theme carries `both`; the emitted
+// data-theme value the attribute cascade uses is light|dark (both boots light) — that pair lives in vocabulary.mjs.
+const LOOK_THEMES = new Set(['light', 'dark', 'both']);
+const DELIGHT_LEVELS = new Set(['baseline', 'expressive']);
+const RESOLUTION_MODES = new Set(['confirmed', 'recorded']);
+// The resolution spine's legal shapes: project | library:<slug> | seed:<style-row>+<palette-row> | default.
+const RESOLUTION_RE = /^(project|default|library:.+|seed:.+\+.+)$/i;
 
 const useColor = process.stdout.isTTY;
 // Wrap a string in green/red when writing to a TTY, plain otherwise.
@@ -163,6 +171,11 @@ function requireMap(phase, project) {
 
 // Collect all .ts/.tsx source under a route directory into one lowercased blob.
 function routeSource(dir) {
+  return routeSourceRaw(dir).toLowerCase();
+}
+
+// Collect all .ts/.tsx source under a route directory, case preserved (the budget stamp is case-sensitive).
+function routeSourceRaw(dir) {
   let out = '';
   const stack = [dir];
   while (stack.length) {
@@ -175,7 +188,7 @@ function routeSource(dir) {
       else if (/\.(tsx|ts)$/.test(ent.name)) out += `\n${readText(full)}`;
     }
   }
-  return out.toLowerCase();
+  return out;
 }
 
 // Return the candidate route-dir slugs for a surface (name-kebab, route segments, archetype).
@@ -205,7 +218,7 @@ function missingStates(dir, states) {
   });
 }
 
-// Validate the load-bearing four-step globals.css import order (Cascade Contract 2).
+// Validate the load-bearing five-step globals.css import order (Cascade Contract 2).
 function checkImportOrder(rawCss) {
   const css = rawCss.replace(/\/\*[\s\S]*?\*\//g, '').replace(/^[ \t]*\/\/.*$/gm, '');
   const marks = [
@@ -217,7 +230,7 @@ function checkImportOrder(rawCss) {
   const absent = marks.filter(([, i]) => i < 0).map(([n]) => n);
   if (absent.length) {
     return { problem: `globals.css is missing: ${absent.join(', ')}.`, fix: [
-      'Emit the four-step cascade order (references/personality.md §4, Cascade Contract 2):',
+      'Emit the five-step cascade order (references/personality.md §4, Cascade Contract 2):',
       '@import "./personality.css"; -> @import "tailwindcss"; -> @import "@nurix/components/styles.css"; -> @theme inline { ... }',
     ] };
   }
@@ -230,9 +243,63 @@ function checkImportOrder(rawCss) {
   return null;
 }
 
+// Validate the payload's mandatory look block (references/create.md, the look block): presence, the theme /
+// delight / resolution-mode enums, 2–3 named anchor strings, the resolution shape, and — when the
+// resolution was authorized autonomously (resolution-mode: recorded) — that the artifact root
+// $description carries a resolution record naming the runner-up. Fails the gate with the exact fix.
+function validateLookBlock(payload, tokens) {
+  const look = payload.look;
+  if (!look || typeof look !== 'object' || Array.isArray(look)) {
+    fail('intake', 'payload carries no look block (payload.look).', [
+      'Add the mandatory look block to the artifact payload (references/create.md, the look block):',
+      'look: { theme: light|dark|both, anchors: ["Product A", "Product B"], delight: baseline|expressive,',
+      '        resolution: project | library:<slug> | seed:<style>+<palette> | default, resolution-mode: confirmed|recorded }.',
+    ]);
+  }
+  if (!LOOK_THEMES.has(look.theme)) {
+    fail('intake', `look.theme is "${look.theme ?? '(missing)'}"; must be light | dark | both.`, [
+      'Set look.theme from the brief; it is binding when stated, default light (references/create.md, the look block).',
+    ]);
+  }
+  if (!DELIGHT_LEVELS.has(look.delight)) {
+    fail('intake', `look.delight is "${look.delight ?? '(missing)'}"; must be baseline | expressive.`, [
+      'Set look.delight — the global delight ceiling per-surface budgets refine (references/create.md the look block, references/structure.md the delight budget).',
+    ]);
+  }
+  const mode = look['resolution-mode'];
+  if (!RESOLUTION_MODES.has(mode)) {
+    fail('intake', `look.resolution-mode is "${mode ?? '(missing)'}"; must be confirmed | recorded.`, [
+      'Set look.resolution-mode: confirmed when a confirmer authorized the pick, recorded when it was resolved autonomously (references/create.md, Resolution).',
+    ]);
+  }
+  const anchors = look.anchors;
+  if (!Array.isArray(anchors) || anchors.length < 2 || anchors.length > 3 || !anchors.every((a) => typeof a === 'string' && a.trim())) {
+    fail('intake', `look.anchors must be 2–3 non-empty named strings; got ${JSON.stringify(anchors ?? null)}.`, [
+      'Name two or three real products (["Linear", "Stripe Dashboard"]); adjectives are not anchors —',
+      'convert an adjective to a named product by asking (interactive) or inferring-and-recording (autonomous) via the design-md resemblance lookup (references/create.md, the look block).',
+    ]);
+  }
+  if (typeof look.resolution !== 'string' || !RESOLUTION_RE.test(look.resolution.trim())) {
+    fail('intake', `look.resolution is "${look.resolution ?? '(missing)'}"; must match project | library:<slug> | seed:<style>+<palette> | default.`, [
+      'Set look.resolution to the resolved source from the precedence spine (references/create.md, Resolution).',
+    ]);
+  }
+  if (mode === 'recorded') {
+    const desc = tokens.$description;
+    if (typeof desc !== 'string' || !desc.trim() || !/runner-up/i.test(desc)) {
+      fail('intake', 'resolution-mode is recorded but the artifact root $description carries no resolution record naming the runner-up.', [
+        'Write the resolution record into the artifact root $description — winner, runner-up, and the deciding evidence, e.g.:',
+        'resolution: library:stripe (recorded; runner-up palettes.csv#3; brief phrase "Stripe-dashboard territory" matched product + fintech traits).',
+        'A recorded (autonomous) resolution is legitimate only once it is auditable (references/create.md, Resolution).',
+      ]);
+    }
+  }
+}
+
 // intake gate: a structurally sound design-tokens artifact sits at project root — both files parse, the dark
-// file agrees with the resolver, and the payload carries a legal schema/provenance/product. Light checks only;
-// deep validation (coverage, aliases, parse-back) is derive-personality.mjs --check at the tokens gate.
+// file agrees with the resolver, the payload carries a legal schema/provenance/product, and the mandatory
+// look block is present and well-formed. Light checks only; deep validation (coverage, aliases, parse-back)
+// is derive-personality.mjs --check at the tokens gate.
 function gateIntake(project) {
   const tokensPath = join(project, 'design.tokens.json');
   const resolverPath = join(project, 'design.resolver.json');
@@ -269,10 +336,11 @@ function gateIntake(project) {
       'Add the file-level payload (schema, dtcg, product, provenance, sourced, lever-manifest, …) per data/design-tokens/SCHEMA.md.',
     ]);
   }
-  if (payload.schema !== 'design-tokens/v1') fail('intake', `payload schema is "${payload.schema || '(missing)'}", expected design-tokens/v1.`, ['Set schema: "design-tokens/v1" in the payload (data/design-tokens/SCHEMA.md).']);
+  if (payload.schema !== 'design-tokens/v2') fail('intake', `payload schema is "${payload.schema || '(missing)'}", expected design-tokens/v2.`, ['Set schema: "design-tokens/v2" in the payload (data/design-tokens/SCHEMA.md).']);
   if (!PROVENANCE.has(payload.provenance)) fail('intake', `payload provenance is "${payload.provenance || '(missing)'}"; must be one of project|extracted|library|default.`, ['Set provenance to one of: project | extracted | library | default (data/design-tokens/SCHEMA.md).']);
   if (typeof payload.product !== 'string' || !payload.product.trim()) fail('intake', 'payload product is missing or empty.', ['Set product to the product name; slugified it becomes the data-style value (data/design-tokens/SCHEMA.md).']);
-  pass('intake', `design.tokens.json + design.resolver.json present and parsing; payload schema design-tokens/v1, provenance "${payload.provenance}"${namesDark ? ', dark set named and present' : ', light-only'}.`);
+  validateLookBlock(payload, tokens);
+  pass('intake', `design.tokens.json + design.resolver.json present and parsing; payload schema design-tokens/v2, provenance "${payload.provenance}"${namesDark ? ', dark set named and present' : ', light-only'}; look block valid (theme ${payload.look.theme}, delight ${payload.look.delight}, ${Array.isArray(payload.look.anchors) ? payload.look.anchors.length : 0} anchors, resolution-mode ${payload.look['resolution-mode']}).`);
 }
 
 // structure gate: the map parses, is populated, has a temporal block, and every surface archetype is one of the six.
@@ -325,7 +393,7 @@ function gateScaffold(project) {
   if (noWire.length) fail('scaffold', `Route(s) not wired into the router: ${noWire.join('; ')}.`, ['Every surface route must be registered in src/App.tsx (react-router-dom) — routes and nav derive from the map, never decorated on.']);
   if (noShell.length) fail('scaffold', `Missing state-shell stubs: ${noShell.join('; ')}.`, ['Each surface needs its loading / empty / error / degraded shells wired (references/create.md -> scaffold).']);
   const globals = join(project, 'src/styles/globals.css');
-  if (!existsSync(globals)) fail('scaffold', 'Missing src/styles/globals.css (Tailwind glue with the four-step import order).', ['Emit src/styles/globals.css with the Cascade Contract 2 import order (references/personality.md §4).']);
+  if (!existsSync(globals)) fail('scaffold', 'Missing src/styles/globals.css (Tailwind glue with the five-step import order).', ['Emit src/styles/globals.css with the Cascade Contract 2 import order (references/personality.md §4).']);
   const orderErr = checkImportOrder(readText(globals));
   if (orderErr) fail('scaffold', orderErr.problem, orderErr.fix);
   pass('scaffold', `Shell, ${blk.surfaces.length} wired route dir(s) with state-shells, and globals.css import order all in place.`);
@@ -384,7 +452,11 @@ function gateFixtures(project) {
   pass('fixtures', `Seeded fixture module present for all ${blk.entities.length} entit(ies).`);
 }
 
-// surfaces gate: every surface's route dir exists and its shell contains every declared state branch.
+// surfaces gate: every surface's route dir exists, its shell contains every declared state branch, and
+// it carries exactly one well-formed budget stamp — with a recorded budget-reason in the map when a
+// brand-forward stamp overrides a baseline-default archetype (references/structure.md, the delight budget). The
+// budget-gated vocabulary sweeps (display step typ-20, wash col-16) land with the rule catalog in a
+// later step; the stamp is parsed here via lib/vocabulary.mjs so those sweeps reuse the same reader.
 function gateSurfaces(project) {
   const blk = requireMap('surfaces', project);
   const routesDir = join(project, 'src/routes');
@@ -396,14 +468,26 @@ function gateSurfaces(project) {
     const states = (s.states && s.states.length) ? s.states : ['loading', 'empty', 'error'];
     const miss = missingStates(dir, states);
     if (miss.length) problems.push(`${name}: shell missing state branch(es) ${miss.join(', ')}`);
+    const src = routeSourceRaw(dir);
+    const looseCount = (src.match(BUDGET_STAMP_LOOSE_RE) || []).length;
+    const stamps = findBudgetStamps(src);
+    if (looseCount === 0) {
+      problems.push(`${name}: no budget stamp at the top of the route file`);
+    } else if (stamps.length !== 1 || looseCount !== 1) {
+      problems.push(`${name}: expected exactly one well-formed budget stamp, found ${looseCount} "// Surface:" line(s) (${stamps.length} well-formed)`);
+    } else if (requiresBudgetReason(s.archetype, stamps[0]) && !(typeof s['budget-reason'] === 'string' && s['budget-reason'].trim())) {
+      problems.push(`${name}: brand-forward stamp on a ${s.archetype} surface (archetype defaults baseline) with no budget-reason in the surface map`);
+    }
   }
   if (problems.length) {
-    fail('surfaces', `${problems.length} surface(s) not fully composed:`, [
+    fail('surfaces', `${problems.length} surface(s) not fully composed. Handle these before finalizing:`, [
       ...problems.map((p) => `- ${p}`),
       'Fill every declared lifecycle state into its pre-created shell (references/create.md -> surfaces); states are composed with the surface, not bolted on.',
+      'Every surface route file carries exactly one stamp — "// Surface: baseline" or "// Surface: brand-forward (delight-allowing)"; scaffold.mjs writes it from the map budget, so re-classify by editing the surface budget in docs/design/structure.md and re-running scaffold.mjs.',
+      'A brand-forward stamp on a baseline-default archetype (list-detail / log-stream / command-center) needs a recorded budget-reason on that surface entry (references/structure.md, the delight budget).',
     ]);
   }
-  pass('surfaces', `All ${blk.surfaces.length} surface(s) have a route dir with every declared state branch present.`);
+  pass('surfaces', `All ${blk.surfaces.length} surface(s) have a route dir, every declared state branch, and exactly one legal budget stamp.`);
 }
 
 const GATES = { intake: gateIntake, structure: gateStructure, scaffold: gateScaffold, tokens: gateTokens, fixtures: gateFixtures, surfaces: gateSurfaces };