@nurix/etna 0.19.2 → 0.19.4

package/data/harnesses/code/skills/design/scripts/derive-personality.mjs

@@ -1,19 +1,29 @@
 #!/usr/bin/env node
-// skills/design/scripts/derive-personality.mjs — design-tokens artifact resolver, coverage gate (--check; SCHEMA.md rules 1–12), and CSS emitter (--emit) for the operator-UI personality system (D29, D6).
+// skills/design/scripts/derive-personality.mjs — design-tokens artifact resolver, coverage gate (--check; SCHEMA.md rules 1–15), and CSS emitter (--emit) for the operator-UI personality system (D29, D6).
 //
-// The reference consumer of data/design-tokens/SCHEMA.md: resolves an artifact directory
-// (design.tokens.json + design.resolver.json [+ design.tokens.dark.json]) through the resolver's
-// deterministic order — concatenate the set files, overlay the selected theme context, resolve
-// aliases — then validates (rules 1–12) or emits personality.css / globals.css / the <html> attributes.
+// The reference consumer of data/design-tokens/SCHEMA.md (schema design-tokens/v2): resolves an
+// artifact directory (design.tokens.json + design.resolver.json [+ design.tokens.dark.json]) through
+// the resolver's deterministic order — concatenate the set files, overlay the selected theme context,
+// resolve aliases — then validates (rules 1–15) or emits personality.css / globals.css / fonts.css /
+// the <html> attributes. --emit refuses while any token carries a hint; --provisional (golden/
+// regression flows only, never shipped output) emits hinted tokens at their provisional $values
+// instead. --emit also enforces two emission contracts: font binding (contract 2, cod-16 — every
+// emitted stack family binds to a generated @fontsource import / installed package or a system
+// generic, fail-closed) and emitter completeness (contract 3 — an authored token group with no
+// emitter refuses to emit, naming the group).
 //
-// Usage: derive-personality.mjs <artifact-dir> [--check | --emit <outdir>] [--theme light|dark]
+// Usage: derive-personality.mjs <artifact-dir> [--check | --emit <outdir> [--provisional]] [--theme light|dark]
 
 import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
 import { dirname, join } from "node:path";
+import { fileURLToPath } from "node:url";
+import { SYSTEM_FONT_KEYWORDS, familySlug } from "./lib/checks.mjs";
 
 const EXT = "com.nurix.design";
+const SCRIPT_DIR = dirname(fileURLToPath(import.meta.url));
+const COMBINATIONS_DIR = join(SCRIPT_DIR, "..", "data", "combinations");
 
-// The 26 visual primitives and their DTCG $type, in emission order (leaf names are law; no leading --).
+// The 27 visual primitives and their DTCG $type, in emission order (leaf names are law; no leading --).
 const PRIMITIVE_TYPES = new Map([
   ["radius", "dimension"], ["shadow-intensity", "number"], ["border-weight", "dimension"],
   ["density-gap", "number"], ["density-inset", "number"],
@@ -21,7 +31,7 @@ const PRIMITIVE_TYPES = new Map([
   ["font-weight-normal", "fontWeight"], ["font-weight-strong", "fontWeight"],
   ["heading-tracking", "number"],
   ["duration-unit", "duration"], ["duration-fast", "duration"], ["duration-normal", "duration"],
-  ["duration-slow", "duration"], ["ease-default", "cubicBezier"],
+  ["duration-slow", "duration"], ["ease-default", "cubicBezier"], ["stagger-unit", "duration"],
   ["contrast-boost", "number"],
   ["icon-stroke", "number"], ["icon-size-base", "dimension"],
   ["sidebar-width-expanded", "dimension"], ["sidebar-width-collapsed", "dimension"],
@@ -31,11 +41,12 @@ const PRIMITIVE_TYPES = new Map([
 ]);
 const PRIMITIVES = [...PRIMITIVE_TYPES.keys()];
 
-// The 17 semantic color tokens, in emission order.
+// The 19 semantic color tokens, in emission order.
 const SEMANTIC_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",
 ];
 
 // The 17 substrate color tokens (the D6 set), in emission order.
@@ -48,17 +59,41 @@ const SUBSTRATE_TOKENS = [
 
 const ALL_TOKENS = [...SEMANTIC_TOKENS, ...SUBSTRATE_TOKENS];
 
-const RAMP_STEPS = ["h1", "h2", "h3", "body", "small", "caption"];
+const RAMP_STEPS = ["h1", "h2", "h3", "body", "small", "caption", "display"];
+const ELEVATION_TOKENS = ["sm", "md", "lg", "overlay"];
+const WASH_TOKENS = ["surface", "emphasis"];
 const LEGAL_VERBOSITY = ["full", "default", "compact", "expert"];
 const LEGAL_FEEDBACK = ["subtle", "minimal"];
 const LEGAL_DENSITY = ["spacious", "standard", "dense"];
 const LEGAL_PROVENANCE = ["project", "extracted", "library", "default"];
-const LEGAL_TYPES = ["color", "dimension", "duration", "cubicBezier", "fontFamily", "fontWeight", "number", "typography"];
+const LEGAL_TYPES = ["color", "dimension", "duration", "cubicBezier", "fontFamily", "fontWeight", "number", "typography", "shadow", "gradient"];
 const LEGAL_THEMES = ["light", "dark"];
 const MANIFEST_KEYS = ["spacing-scale", "radius-scale", "shadow-levels", "motion", "icons", "accent-count"];
 
+// The optional persisted intake look block's enums — mirrored from phase-gate.mjs validateLookBlock
+// (the intake authority) so a persisted payload.look cannot rot unchecked.
+const LOOK_THEMES = ["light", "dark", "both"];
+const LOOK_DELIGHTS = ["baseline", "expressive"];
+const LOOK_RESOLUTION_MODES = ["confirmed", "recorded"];
+const LOOK_RESOLUTION_RE = /^(project|default|library:.+|seed:.+\+.+)$/i;
+
+// Contract 3 — the emitter registry: every authored token group's named consumer in the emitted
+// output. --emit refuses an authored group absent from this map (a group with no emitter vanishes).
+const EMITTED_GROUPS = new Map([
+  ["primitive", "the [data-style] primitives block"],
+  ["color", "the armored theme blocks (:root, :root[data-theme=\"light\"] / :root[data-theme=\"dark\"])"],
+  ["typography", "the @theme ramp text utilities (text-h1 … text-display)"],
+  ["elevation", "the --shadow-sm/md/lg/overlay composites + @theme shadow utilities"],
+  ["wash", "--wash-surface / --wash-emphasis (optional presence)"],
+]);
+const TYPOGRAPHY_SUBGROUPS = ["family", "ramp"];
+
+// Legal $description opening tags (rule 15): the provenance-layer vocabulary (source/brief/deviation,
+// 00-layering.md Composition A) plus the established mechanical-annotation prefixes.
+const LEGAL_DESCRIPTION_TAGS = ["source", "brief", "deviation", "derived", "corpus", "rationale", "note", "synthesized", "brand", "dark"];
+
 // Shadow-level names ranked by increasing intensity, for the ordering check.
-const SHADOW_RANK = { none: 0, "2xs": 1, xs: 2, sm: 3, md: 4, lg: 5, xl: 6, "2xl": 7 };
+const SHADOW_RANK = { none: 0, "2xs": 1, xs: 2, sm: 3, md: 4, lg: 5, xl: 6, "2xl": 7, overlay: 8 };
 
 // ---------------------------------------------------------------------------
 // CSS value parsers — the parse-back authority (rule 9); byte-compatible with convert-design-md.mjs
@@ -111,16 +146,38 @@ function parseColorCss(css) {
     return value;
   }
   m = /^rgba?\(\s*(\d+)\s*,\s*(\d+)\s*,\s*(\d+)\s*(?:,\s*([\d.]+)\s*)?\)$/.exec(s);
+  if (!m) m = /^rgba?\(\s*(\d+)\s+(\d+)\s+(\d+)\s*(?:\/\s*([\d.]+%?)\s*)?\)$/.exec(s); // modern space syntax
   if (m) {
     const bytes = [m[1], m[2], m[3]].map(Number);
     const hex = "#" + bytes.map((b) => b.toString(16).padStart(2, "0")).join("");
     const value = { colorSpace: "srgb", components: bytes.map((b) => round5(b / 255)), hex };
-    if (m[4] !== undefined) value.alpha = parseFloat(m[4]);
+    if (m[4] !== undefined) value.alpha = m[4].endsWith("%") ? round5(parseFloat(m[4]) / 100) : parseFloat(m[4]);
     return value;
   }
   throw new Error(`unparseable color: ${JSON.stringify(css)}`);
 }
 
+// Parse one shadow-list string (the elevation byte form) into the DTCG layer array. A layer color's
+// alpha may ride the master multiplier as calc(A * var(--shadow-intensity)) — A is the layer alpha.
+function parseShadowCss(css) {
+  return splitTopLevel(css, ",").map((layerRaw) => {
+    const s = layerRaw.trim();
+    const colorStart = s.search(/rgba?\(|oklch\(|hsla?\(|#[0-9a-fA-F]/);
+    if (colorStart < 0) throw new Error(`shadow layer names no color: ${JSON.stringify(s)}`);
+    const colorCss = s.slice(colorStart).trim().replace(/calc\(\s*([\d.]+)\s*\*\s*var\(--shadow-intensity\)\s*\)/, "$1");
+    const dims = s.slice(0, colorStart).trim().split(/\s+/);
+    if (dims.length < 3 || dims.length > 4) throw new Error(`shadow layer wants 3-4 lengths (offsetX offsetY blur [spread]): ${JSON.stringify(s)}`);
+    const dim = (d) => (d === "0" ? { value: 0, unit: "px" } : parseDimensionCss(d));
+    return {
+      color: parseColorCss(colorCss),
+      offsetX: dim(dims[0]),
+      offsetY: dim(dims[1]),
+      blur: dim(dims[2]),
+      spread: dims[3] !== undefined ? dim(dims[3]) : { value: 0, unit: "px" },
+    };
+  });
+}
+
 // Parse a tracking string ("0" | "0em" | "-0.015em") into its em-multiplier number.
 function parseTrackingCss(css) {
   const m = /^([+-]?\d*\.?\d+)(em)?$/.exec(css.trim());
@@ -182,6 +239,25 @@ function serializeValue(type, value) {
     if (value.colorSpace === "srgb" && value.hex) return value.hex;
     return `oklch(${value.components.join(" ")}${value.alpha !== undefined ? ` / ${value.alpha}` : ""})`;
   }
+  if (type === "shadow") {
+    // Deterministic fallback (the migration always preserves .css): zero lengths serialize bare "0";
+    // the layer alpha rides the master multiplier so --shadow-intensity keeps flattening shadows.
+    const dim = (d) => (d.value === 0 ? "0" : `${d.value}${d.unit}`);
+    const layerColor = (c) => {
+      const alpha = c.alpha ?? 1;
+      if (c.colorSpace === "srgb") {
+        const bytes = c.components.map((n) => Math.round(n * 255));
+        return `rgb(${bytes.join(" ")} / calc(${alpha} * var(--shadow-intensity)))`;
+      }
+      return `oklch(${c.components.join(" ")} / calc(${alpha} * var(--shadow-intensity)))`;
+    };
+    return value.map((l) => `${dim(l.offsetX)} ${dim(l.offsetY)} ${dim(l.blur)} ${dim(l.spread ?? { value: 0, unit: "px" })} ${layerColor(l.color)}`).join(", ");
+  }
+  if (type === "gradient") {
+    // Deterministic fallback (authored washes preserve .css): a top-down tint ramp from the stop list.
+    const stops = value.map((s) => `${serializeValue("color", s.color)} ${Math.round(s.position * 100)}%`).join(", ");
+    return `linear-gradient(180deg, ${stops})`;
+  }
   return String(value);
 }
 
@@ -275,7 +351,7 @@ function loadArtifact(dir, errors) {
     errors.push("rule 1 — design.resolver.json: missing the theme modifier");
     return null;
   }
-  if (themeModifier.default !== "light") errors.push("rule 1 — design.resolver.json: theme default must be light (light-first)");
+  if (!LEGAL_THEMES.includes(themeModifier.default)) errors.push(`rule 1 — design.resolver.json: theme default must be light|dark (found ${JSON.stringify(themeModifier.default)}); it mirrors the payload's theme-default`);
   if (!Array.isArray(themeModifier.contexts?.light) || themeModifier.contexts.light.length !== 0) {
     errors.push("rule 1 — design.resolver.json: the light context must be the empty overlay [] (the base set is the light rendering)");
   }
@@ -406,24 +482,20 @@ function verifyScalarParseBack(name, token, css, errors) {
   }
 }
 
-// Run the full coverage gate (rules 1–11) over one artifact directory; returns everything emit needs.
-function runCheck(dir, theme) {
+// Run the full coverage gate (rules 1–15) over one artifact directory; returns everything emit needs.
+// requestedTheme null = boot theme follows the payload's theme-default (light when absent).
+function runCheck(dir, requestedTheme) {
   const errors = [];
   const artifact = loadArtifact(dir, errors);
   if (!artifact) return { errors };
-  const { base, files, views, payload } = artifact;
-
-  if (!views.has(theme)) {
-    errors.push(`rule 1 — resolver: --theme ${theme} requested but the resolver carries no ${theme} context`);
-    return { errors };
-  }
+  const { base, resolver, files, views, payload } = artifact;
 
   // Rule 2 — the file-level payload on the base root.
   if (!payload || typeof payload !== "object") {
     errors.push(`rule 2 — payload: missing $extensions["${EXT}"] on the base file's root group`);
     return { errors };
   }
-  if (payload.schema !== "design-tokens/v1") errors.push(`rule 2 — payload.schema: must be "design-tokens/v1" (found ${JSON.stringify(payload.schema)})`);
+  if (payload.schema !== "design-tokens/v2") errors.push(`rule 2 — payload.schema: must be "design-tokens/v2" (found ${JSON.stringify(payload.schema)})`);
   if (payload.dtcg !== "2025.10") errors.push(`rule 2 — payload.dtcg: must be "2025.10" (found ${JSON.stringify(payload.dtcg)})`);
   if (typeof payload.product !== "string" || payload.product.trim() === "") errors.push("rule 2 — payload.product: missing or empty");
   if (!LEGAL_PROVENANCE.includes(payload.provenance)) errors.push(`rule 2 — payload.provenance: must be one of ${LEGAL_PROVENANCE.join("|")} (found ${JSON.stringify(payload.provenance)})`);
@@ -432,23 +504,63 @@ function runCheck(dir, theme) {
   if (!LEGAL_FEEDBACK.includes(payload.feedback)) errors.push(`rule 2 — payload.feedback: must be one of ${LEGAL_FEEDBACK.join("|")} (found ${JSON.stringify(payload.feedback)})`);
   if (!LEGAL_DENSITY.includes(payload["density-tier"])) errors.push(`rule 2 — payload.density-tier: must be one of ${LEGAL_DENSITY.join("|")} (found ${JSON.stringify(payload["density-tier"])})`);
   if (!Array.isArray(payload["product-traits"]) || payload["product-traits"].length === 0) errors.push("rule 2 — payload.product-traits: must be a non-empty array");
+  if (payload["theme-default"] !== undefined && !LEGAL_THEMES.includes(payload["theme-default"])) {
+    errors.push(`rule 2 — payload.theme-default: must be light|dark when present (found ${JSON.stringify(payload["theme-default"])})`);
+  }
+  const themeDefault = LEGAL_THEMES.includes(payload["theme-default"]) ? payload["theme-default"] : "light";
+  const resolverDefault = (resolver.modifiers ?? []).find((m) => m?.name === "theme")?.default;
+  if (LEGAL_THEMES.includes(resolverDefault) && resolverDefault !== themeDefault) {
+    errors.push(`rule 2 — design.resolver.json: theme default ${JSON.stringify(resolverDefault)} does not mirror payload theme-default ${JSON.stringify(themeDefault)}`);
+  }
+  const anchors = payload.anchors;
+  const anchorsShapeOk = Array.isArray(anchors) && anchors.length >= 2 && anchors.length <= 3 && anchors.every((a) => typeof a === "string" && a.trim() !== "");
+  if (anchors !== undefined && !anchorsShapeOk) errors.push(`rule 2 — payload.anchors: must be an array of 2–3 non-empty strings when present (found ${JSON.stringify(anchors)})`);
+  if (payload.provenance === "project" && anchors === undefined) errors.push("rule 2 — payload.anchors: required on provenance: project artifacts (the named real-product anchors from intake)");
+  // Rule 2 (look) — the optional persisted intake look block (SCHEMA.md, the payload): enum-checked
+  // when present; theme-default and anchors stay the canonical top-level projections emission consumes.
+  const look = payload.look;
+  if (look !== undefined) {
+    if (look === null || typeof look !== "object" || Array.isArray(look)) {
+      errors.push("rule 2 — payload.look: must be an object when present (the persisted intake look block)");
+    } else {
+      if (!LOOK_THEMES.includes(look.theme)) errors.push(`rule 2 — payload.look.theme: must be one of ${LOOK_THEMES.join("|")} (found ${JSON.stringify(look.theme)})`);
+      if (!LOOK_DELIGHTS.includes(look.delight)) errors.push(`rule 2 — payload.look.delight: must be one of ${LOOK_DELIGHTS.join("|")} (found ${JSON.stringify(look.delight)})`);
+      if (!LOOK_RESOLUTION_MODES.includes(look["resolution-mode"])) errors.push(`rule 2 — payload.look.resolution-mode: must be one of ${LOOK_RESOLUTION_MODES.join("|")} (found ${JSON.stringify(look["resolution-mode"])})`);
+      const lookAnchors = look.anchors;
+      if (!Array.isArray(lookAnchors) || lookAnchors.length < 2 || lookAnchors.length > 3 || !lookAnchors.every((a) => typeof a === "string" && a.trim() !== "")) {
+        errors.push(`rule 2 — payload.look.anchors: must be an array of 2–3 non-empty named strings (found ${JSON.stringify(lookAnchors)})`);
+      }
+      if (typeof look.resolution !== "string" || !LOOK_RESOLUTION_RE.test(look.resolution.trim())) {
+        errors.push(`rule 2 — payload.look.resolution: must match project | library:<slug> | seed:<style>+<palette> | default (found ${JSON.stringify(look.resolution)})`);
+      }
+    }
+  }
   const lm = payload["lever-manifest"];
   for (const key of MANIFEST_KEYS) {
     if (lm?.[key] === undefined) errors.push(`rule 2 — payload.lever-manifest.${key}: missing`);
   }
 
+  const theme = requestedTheme ?? themeDefault;
+  if (!views.has(theme)) {
+    errors.push(`rule 1 — resolver: theme ${theme} selected but the resolver carries no ${theme} context`);
+    return { errors };
+  }
+
   const lightView = views.get("light");
   const lightTokens = collectTokens(lightView);
 
-  // Rule 3 — all 26 primitives present with the exact $type, each assigned or hinted.
+  // Rule 3 — all 27 primitives present with the exact $type, each assigned or hinted.
   for (const [key, type] of PRIMITIVE_TYPES) {
     const t = lightView.primitive?.[key];
     if (!isToken(t)) { errors.push(`rule 3 — primitive.${key}: missing`); continue; }
     if (t.$type !== type) errors.push(`rule 3 — primitive.${key}: $type ${JSON.stringify(t.$type)} (want ${type})`);
     if (isEmptyValue(t.$value)) errors.push(`rule 3 — primitive.${key}: empty $value`);
+    if (key === "stagger-unit" && typeof t.$value?.value === "number" && (t.$value.value < 0 || t.$value.value > 60)) {
+      errors.push(`rule 3 — primitive.stagger-unit: ${t.$value.value}ms outside the legal 0–60ms range`);
+    }
   }
 
-  // Rule 4 — all 34 color roles present, typed color, legal colorSpace, .css present (via alias when aliased).
+  // Rule 4 — all 36 color roles present, typed color, legal colorSpace, .css present (via alias when aliased).
   for (const role of ALL_TOKENS) {
     const t = lightView.color?.[role];
     if (!isToken(t)) { errors.push(`rule 4 — color.${role}: missing`); continue; }
@@ -459,11 +571,15 @@ function runCheck(dir, theme) {
     if (typeof target.$extensions?.[EXT]?.css !== "string") errors.push(`rule 4 — color.${role}: missing preserved .css`);
   }
 
-  // Rule 5 — typography coverage: the three families and the six-step ramp with all five sub-values.
+  // Rule 5 — typography coverage: the three families (display optional) and the seven-step ramp with all five sub-values.
   for (const fam of ["heading", "body", "mono"]) {
     const t = lightView.typography?.family?.[fam];
     if (!isToken(t) || t.$type !== "fontFamily") errors.push(`rule 5 — typography.family.${fam}: missing or not $type fontFamily`);
   }
+  const famDisplay = lightView.typography?.family?.display;
+  if (famDisplay !== undefined && (!isToken(famDisplay) || famDisplay.$type !== "fontFamily")) {
+    errors.push("rule 5 — typography.family.display: not $type fontFamily (the slot is optional; its shape is not)");
+  }
   for (const step of RAMP_STEPS) {
     const t = lightView.typography?.ramp?.[step];
     if (!isToken(t) || t.$type !== "typography") { errors.push(`rule 5 — typography.ramp.${step}: missing or not $type typography`); continue; }
@@ -504,21 +620,25 @@ function runCheck(dir, theme) {
     if (typeof lm.icons?.family !== "string" || lm.icons.family === "") errors.push("rule 7 — lever-manifest.icons.family: missing or empty");
     if (!(lm["accent-count"] >= 1)) errors.push(`rule 7 — lever-manifest.accent-count: must be >= 1 (found ${JSON.stringify(lm?.["accent-count"])})`);
 
-    // Rule 8 — the look's own base values sit on its own allowlist.
-    const radius = lightView.primitive?.radius?.$value?.value;
-    if (Array.isArray(lm["radius-scale"]) && radius !== undefined && !lm["radius-scale"].includes(radius)) {
-      errors.push(`rule 8 — primitive.radius: ${radius} not on lever-manifest.radius-scale`);
+    // Rule 8 — the look's own base values sit on its own allowlist. An off-manifest value is legal
+    // only as a recorded deviation: its $description must open with the deviation: layer tag (rule 15).
+    const deviationTagged = (t) => typeof t?.$description === "string" && t.$description.startsWith("deviation:");
+    const radiusToken = lightView.primitive?.radius;
+    const radius = radiusToken?.$value?.value;
+    if (Array.isArray(lm["radius-scale"]) && radius !== undefined && !lm["radius-scale"].includes(radius) && !deviationTagged(radiusToken)) {
+      errors.push(`rule 8 — primitive.radius: ${radius} not on lever-manifest.radius-scale (off-manifest values need a deviation: $description)`);
     }
     for (const key of ["duration-fast", "duration-normal", "duration-slow"]) {
-      const ms = lightView.primitive?.[key]?.$value?.value;
-      if (Array.isArray(lm.motion?.durations) && ms !== undefined && !lm.motion.durations.includes(ms)) {
-        errors.push(`rule 8 — primitive.${key}: ${ms} not in lever-manifest.motion.durations`);
+      const t = lightView.primitive?.[key];
+      const ms = t?.$value?.value;
+      if (Array.isArray(lm.motion?.durations) && ms !== undefined && !lm.motion.durations.includes(ms) && !deviationTagged(t)) {
+        errors.push(`rule 8 — primitive.${key}: ${ms} not in lever-manifest.motion.durations (off-manifest values need a deviation: $description)`);
       }
     }
     const ease = lightView.primitive?.["ease-default"];
     if (isToken(ease) && Array.isArray(lm.motion?.easings)) {
       const easeCss = typeof ease.$extensions?.[EXT]?.css === "string" ? ease.$extensions[EXT].css : serializeValue("cubicBezier", ease.$value);
-      if (!lm.motion.easings.includes(easeCss)) errors.push(`rule 8 — primitive.ease-default: ${JSON.stringify(easeCss)} not in lever-manifest.motion.easings`);
+      if (!lm.motion.easings.includes(easeCss) && !deviationTagged(ease)) errors.push(`rule 8 — primitive.ease-default: ${JSON.stringify(easeCss)} not in lever-manifest.motion.easings (off-manifest values need a deviation: $description)`);
     }
   }
 
@@ -531,6 +651,20 @@ function runCheck(dir, theme) {
       const name = `${prefix}${path}`;
       if (token.$type === "color") {
         verifyColorParseBack(name, token, errors);
+      } else if (token.$type === "shadow" && typeof css === "string") {
+        try {
+          const reparsed = parseShadowCss(css);
+          if (JSON.stringify(reparsed) !== JSON.stringify(token.$value)) errors.push(`rule 9 — ${name}: shadow css ${JSON.stringify(css)} does not parse back to $value`);
+        } catch (e) {
+          errors.push(`rule 9 — ${name}: ${e.message}`);
+        }
+      } else if (token.$type === "gradient" && typeof css === "string") {
+        // A gradient's .css carries geometry the stop list does not; verify each stop color's byte form appears in it.
+        for (const [i, stop] of (Array.isArray(token.$value) ? token.$value : []).entries()) {
+          if (stop?.color && typeof stop.color === "object" && !css.includes(serializeValue("color", stop.color))) {
+            errors.push(`rule 9 — ${name}: stop ${i} color ${serializeValue("color", stop.color)} not present in the preserved .css`);
+          }
+        }
       } else if (typeof css === "string") {
         verifyScalarParseBack(name, token, css, errors);
       } else if (token.$type === "typography" && typeof css === "object" && css !== null) {
@@ -546,7 +680,7 @@ function runCheck(dir, theme) {
     }
   }
 
-  // Rule 10 — the dark file, when present, carries exactly the 34-role color group and nothing else.
+  // Rule 10 — the dark file, when present, carries exactly the 36-role color group and nothing else.
   const darkDoc = files.get("design.tokens.dark.json");
   if (darkDoc !== undefined) {
     const rootKeys = Object.keys(darkDoc).filter((k) => !k.startsWith("$"));
@@ -565,7 +699,7 @@ function runCheck(dir, theme) {
     }
   }
 
-  // Rule 11 — only the eight legal $type values appear, in any file.
+  // Rule 11 — only the ten legal $type values appear, in any file.
   for (const [fileName, doc] of files) {
     const prefix = fileName === "design.tokens.json" ? "" : `${fileName} `;
     for (const [path, token] of collectTokens(doc)) {
@@ -573,6 +707,70 @@ function runCheck(dir, theme) {
     }
   }
 
+  // True when a shadow/wash layer color is a legal DTCG color value; records rule errors under `where`.
+  const checkLayerColor = (color, where, rule) => {
+    if (!color || typeof color !== "object" || !["oklch", "srgb"].includes(color.colorSpace) || !Array.isArray(color.components)) {
+      errors.push(`${rule} — ${where}: color must be a typed oklch|srgb value (found ${JSON.stringify(color)})`);
+      return;
+    }
+    const isPureBlack = color.colorSpace === "srgb"
+      ? color.components.every((c) => c === 0)
+      : color.components[0] === 0 && color.components[1] === 0;
+    if (rule === "rule 13" && isPureBlack && (color.alpha ?? 1) >= 0.15) {
+      errors.push(`${rule} — ${where}: pure black at alpha ${color.alpha ?? 1} (≥ 0.15) — shadow colors are brand-tintable, never a hard black drop`);
+    }
+  };
+
+  // Rule 13 — elevation coverage: all four elevation.* present, $type shadow, ≥ 1 layer each,
+  // every layer shape-legal and rule-conformant, the byte form preserved; each assigned or hinted.
+  for (const level of ELEVATION_TOKENS) {
+    const t = lightView.elevation?.[level];
+    if (!isToken(t)) { errors.push(`rule 13 — elevation.${level}: missing`); continue; }
+    if (t.$type !== "shadow") { errors.push(`rule 13 — elevation.${level}: $type ${JSON.stringify(t.$type)} (want shadow)`); continue; }
+    if (!Array.isArray(t.$value) || t.$value.length === 0) { errors.push(`rule 13 — elevation.${level}: $value must be a non-empty array of layers`); continue; }
+    for (const [i, layer] of t.$value.entries()) {
+      checkLayerColor(layer?.color, `elevation.${level} layer ${i}`, "rule 13");
+      for (const dim of ["offsetX", "offsetY", "blur"]) {
+        if (typeof layer?.[dim]?.value !== "number") errors.push(`rule 13 — elevation.${level} layer ${i}: ${dim} must be a dimension`);
+      }
+    }
+    if (typeof t.$extensions?.[EXT]?.css !== "string") errors.push(`rule 13 — elevation.${level}: missing preserved .css (the serialized shadow list)`);
+  }
+  for (const level of Object.keys(lightView.elevation ?? {})) {
+    if (!level.startsWith("$") && !ELEVATION_TOKENS.includes(level)) errors.push(`rule 13 — elevation.${level}: not a legal level (sm|md|lg|overlay)`);
+  }
+
+  // Rule 14 — wash shape: the group is optional; when present, ≤ 2 gradient tokens named
+  // surface/emphasis with rule-conformant stops. Presence is never required.
+  if (lightView.wash !== undefined) {
+    const washKeys = Object.keys(lightView.wash).filter((k) => !k.startsWith("$"));
+    if (washKeys.length > 2) errors.push(`rule 14 — wash: at most 2 tokens (found ${washKeys.length})`);
+    for (const key of washKeys) {
+      if (!WASH_TOKENS.includes(key)) { errors.push(`rule 14 — wash.${key}: not a legal wash slot (surface|emphasis)`); continue; }
+      const t = lightView.wash[key];
+      if (!isToken(t) || t.$type !== "gradient") { errors.push(`rule 14 — wash.${key}: must be $type gradient`); continue; }
+      if (!Array.isArray(t.$value) || t.$value.length < 2) { errors.push(`rule 14 — wash.${key}: $value must be an array of ≥ 2 stops`); continue; }
+      for (const [i, stop] of t.$value.entries()) {
+        checkLayerColor(stop?.color, `wash.${key} stop ${i}`, "rule 14");
+        if (typeof stop?.position !== "number" || stop.position < 0 || stop.position > 1) errors.push(`rule 14 — wash.${key} stop ${i}: position must be a number in 0–1`);
+      }
+      if (typeof t.$extensions?.[EXT]?.css !== "string") errors.push(`rule 14 — wash.${key}: missing preserved .css (the authored gradient)`);
+    }
+  }
+
+  // Rule 15 — provenance vocabulary: a per-value $description opening with a tag must use a legal
+  // one (source:/brief:/deviation: are the layer tags; untagged = inherited). Rule 8 enforces the
+  // off-manifest side (every off-manifest value carries deviation:).
+  for (const [fileName, doc] of files) {
+    const prefix = fileName === "design.tokens.json" ? "" : `${fileName} `;
+    for (const [path, token] of collectTokens(doc)) {
+      const m = typeof token.$description === "string" && /^([a-z][a-z-]*):/.exec(token.$description);
+      if (m && !LEGAL_DESCRIPTION_TAGS.includes(m[1])) {
+        errors.push(`rule 15 — ${prefix}${path}: $description opens with unknown tag "${m[1]}:" (layer tags: source:|brief:|deviation:; untagged = inherited)`);
+      }
+    }
+  }
+
   // Rule 12 inventory — every token still carrying a hint (passes --check; --emit refuses).
   const hints = [];
   for (const [fileName, doc] of files) {
@@ -583,17 +781,19 @@ function runCheck(dir, theme) {
     }
   }
 
-  return { errors, payload, views, hints, hasDark: files.has("design.tokens.dark.json") };
+  return { errors, payload, views, hints, theme, hasDark: files.has("design.tokens.dark.json"), hasWash: lightView.wash !== undefined };
 }
 
 // ---------------------------------------------------------------------------
 // Emitter feed — flatten the resolved views into the value map the emitters consume
 // ---------------------------------------------------------------------------
 
-// Assemble the emitters' document: 26 primitive CSS strings + the payload dials, and the
-// 34-role CSS string map per theme (preferring each token's preserved .css).
+// Assemble the emitters' document: 27 primitive CSS strings + the payload dials, the 36-role CSS
+// string map per theme, the elevation/wash value strings, and the ramp steps as emitter-ready data
+// (preferring each token's preserved .css throughout).
 function buildEmitterDoc(views, payload, errors) {
-  const lightTokens = collectTokens(views.get("light"));
+  const lightView = views.get("light");
+  const lightTokens = collectTokens(lightView);
   const primitives = {};
   for (const key of PRIMITIVES) primitives[key] = cssFor(`primitive.${key}`, lightTokens, errors);
   primitives.verbosity = payload.verbosity;
@@ -609,7 +809,222 @@ function buildEmitterDoc(views, payload, errors) {
     for (const role of ALL_TOKENS) colorTokens.dark[role] = cssFor(`color.${role}`, darkTokens, errors);
   }
 
-  return { primitives, manifest: { "color-tokens": colorTokens } };
+  const elevation = {};
+  for (const level of ELEVATION_TOKENS) elevation[level] = cssFor(`elevation.${level}`, lightTokens, errors);
+
+  let wash = null;
+  if (lightView.wash !== undefined) {
+    wash = {};
+    for (const key of WASH_TOKENS) {
+      if (isToken(lightView.wash[key])) wash[key] = cssFor(`wash.${key}`, lightTokens, errors);
+    }
+  }
+
+  // Ramp steps as @theme text-utility data: size/line-height as literals; weight and tracking as
+  // var() references when they alias a personality primitive, so the utilities track the cascade.
+  const ramp = {};
+  for (const step of RAMP_STEPS) {
+    const t = lightView.typography?.ramp?.[step];
+    if (!isToken(t) || !t.$value || typeof t.$value !== "object") { errors.push(`emit — typography.ramp.${step}: missing composite`); continue; }
+    const v = t.$value;
+    const weightVar = { "{primitive.font-weight-strong}": "var(--font-weight-strong)", "{primitive.font-weight-normal}": "var(--font-weight-normal)" };
+    let fontWeight;
+    if (typeof v.fontWeight === "number") fontWeight = String(v.fontWeight);
+    else if (weightVar[v.fontWeight]) fontWeight = weightVar[v.fontWeight];
+    else {
+      const target = resolveAlias(v.fontWeight, lightTokens, "fontWeight", `typography.ramp.${step}.fontWeight`, errors);
+      fontWeight = target ? String(target.$value) : "400";
+    }
+    const preservedTracking = t.$extensions?.[EXT]?.css?.letterSpacing;
+    let letterSpacing;
+    if (v.letterSpacing === "{primitive.heading-tracking}") letterSpacing = "var(--heading-tracking)";
+    else if (typeof preservedTracking === "string") letterSpacing = preservedTracking;
+    else if (typeof v.letterSpacing === "number") letterSpacing = `${v.letterSpacing}em`;
+    else {
+      const target = resolveAlias(v.letterSpacing, lightTokens, "number", `typography.ramp.${step}.letterSpacing`, errors);
+      letterSpacing = target ? `${target.$value}em` : "0em";
+    }
+    ramp[step] = {
+      fontSize: `${v.fontSize?.value}${v.fontSize?.unit ?? "px"}`,
+      lineHeight: String(v.lineHeight),
+      fontWeight,
+      letterSpacing,
+    };
+  }
+
+  return { primitives, elevation, wash, ramp, manifest: { "color-tokens": colorTokens } };
+}
+
+// ---------------------------------------------------------------------------
+// Contract 3 — emitter completeness: every authored group reaches consumable output
+// ---------------------------------------------------------------------------
+
+// Refuse emission when any resolved view carries an authored token group (or typography subgroup)
+// absent from the emitter registry — machinery that accepts data it never emits is a silent breach.
+function checkEmitterCompleteness(views, emitErrors) {
+  for (const [context, view] of views) {
+    const label = context === "light" ? "" : ` [${context}]`;
+    for (const group of Object.keys(view)) {
+      if (group.startsWith("$")) continue;
+      if (!EMITTED_GROUPS.has(group)) {
+        emitErrors.push(`emitter completeness — authored token group "${group}"${label} has no emitter (contract 3): an authored group with no emitter simply vanishes; add its emitter to this script or remove the group. Emitters exist for: ${[...EMITTED_GROUPS.keys()].join(", ")}.`);
+      }
+    }
+    for (const sub of Object.keys(view.typography ?? {})) {
+      if (!sub.startsWith("$") && !TYPOGRAPHY_SUBGROUPS.includes(sub)) {
+        emitErrors.push(`emitter completeness — authored token group "typography.${sub}"${label} has no emitter (contract 3): only typography.family and typography.ramp reach the emitted output.`);
+      }
+    }
+  }
+}
+
+// ---------------------------------------------------------------------------
+// Contract 2 — font binding: fonts.css generation + the fail-closed cod-16 gate
+// ---------------------------------------------------------------------------
+
+// Parse a CSV text into row objects keyed by its header (RFC quoting: "" escapes a quote inside a quoted field).
+function parseCsv(text) {
+  const records = [];
+  let field = "", record = [], inQuotes = false;
+  const endField = () => { record.push(field); field = ""; };
+  const endRecord = () => { endField(); if (record.some((f) => f !== "")) records.push(record); record = []; };
+  for (let i = 0; i < text.length; i++) {
+    const c = text[i];
+    if (inQuotes) {
+      if (c === '"' && text[i + 1] === '"') { field += '"'; i++; }
+      else if (c === '"') inQuotes = false;
+      else field += c;
+    } else if (c === '"') inQuotes = true;
+    else if (c === ",") endField();
+    else if (c === "\n") endRecord();
+    else if (c !== "\r") field += c;
+  }
+  endRecord();
+  const header = records.shift() ?? [];
+  return records.map((cells) => Object.fromEntries(header.map((h, i) => [h, cells[i] ?? ""])));
+}
+
+// Load the family → registering-import resolver: typography.csv css-import rows first (paste-ready
+// static @fontsource imports, registering the plain family names), fonts-known.json as the fallback
+// oracle (family → static weights). Returns resolve(family) → { family, pkg, imports } | null.
+function loadFontResolver() {
+  const byFamily = new Map();
+  try {
+    for (const row of parseCsv(readFileSync(join(COMBINATIONS_DIR, "typography.csv"), "utf8"))) {
+      for (const col of ["heading_family", "body_family", "mono_family"]) {
+        const family = (row[col] ?? "").trim();
+        if (family === "" || byFamily.has(family.toLowerCase())) continue;
+        const slug = familySlug(family);
+        const imports = [...String(row["css-import"] ?? "").matchAll(/@import\s+'(@fontsource\/([a-z0-9-]+)\/[^']+)'/g)]
+          .filter((m) => m[2] === slug)
+          .map((m) => `@import '${m[1]}';`);
+        if (imports.length > 0) byFamily.set(family.toLowerCase(), { family, pkg: `@fontsource/${slug}`, imports });
+      }
+    }
+  } catch { /* typography.csv unreadable — fonts-known.json stays the oracle */ }
+  let knownFamilies = {};
+  try { knownFamilies = JSON.parse(readFileSync(join(COMBINATIONS_DIR, "fonts-known.json"), "utf8")).families ?? {}; } catch { /* absent oracle degrades to csv-only resolution */ }
+  const knownLower = new Map(Object.entries(knownFamilies).map(([name, weights]) => [name.toLowerCase(), weights]));
+  return (family) => {
+    const hit = byFamily.get(family.toLowerCase());
+    if (hit) return hit;
+    const weights = knownLower.get(family.toLowerCase());
+    if (!Array.isArray(weights) || weights.length === 0) return null;
+    const slug = familySlug(family);
+    return { family, pkg: `@fontsource/${slug}`, imports: weights.map((w) => `@import '@fontsource/${slug}/${w}.css';`) };
+  };
+}
+
+// Collect the artifact's font surfaces: the two emitted stacks (the cod-16 gate's subjects) and the
+// deduped named families across every fontFamily token (import generation covers all of them).
+function collectFontSurfaces(views, doc, errors) {
+  const lightTokens = collectTokens(views.get("light"));
+  const stacks = [
+    { name: "--font-sans", families: parseFontStackCss(String(doc.primitives["font-sans"])) },
+    { name: "--font-mono", families: parseFontStackCss(String(doc.primitives["font-mono"])) },
+  ];
+  const importFamilies = [];
+  const seen = new Set();
+  const push = (family) => {
+    const key = family.toLowerCase();
+    if (!seen.has(key) && !SYSTEM_FONT_KEYWORDS.has(key)) { seen.add(key); importFamilies.push(family); }
+  };
+  for (const stack of stacks) for (const family of stack.families) push(family);
+  for (const slot of ["heading", "body", "mono", "display"]) {
+    if (!lightTokens.has(`typography.family.${slot}`)) continue;
+    for (const family of parseFontStackCss(cssFor(`typography.family.${slot}`, lightTokens, errors))) push(family);
+  }
+  return { stacks, importFamilies };
+}
+
+// Read the emit target's dependency map, or null when the target is standalone (no package.json) —
+// the standalone case degrades the cod-16 gate to import-list validation.
+function readTargetDeps(outdir) {
+  const pkgPath = join(outdir, "package.json");
+  if (!existsSync(pkgPath)) return null;
+  try {
+    const pkg = JSON.parse(readFileSync(pkgPath, "utf8"));
+    return { ...(pkg.dependencies ?? {}), ...(pkg.devDependencies ?? {}) };
+  } catch {
+    return null;
+  }
+}
+
+// The emitted src/styles/fonts.css content: the generated registering-import list, one derivation.
+function emitFontsCss(entries, unresolved) {
+  const lines = [
+    "/* src/styles/fonts.css — @fontsource font registrations (emitted; do not hand-edit).",
+    " *",
+    " * One derivation, not two authored artifacts: this import list is GENERATED from the",
+    " * artifact's fontFamily tokens (typography.csv css-import rows; fonts-known.json fallback),",
+    " * and the emitted stacks use the same registered family names — so the flagship font cannot",
+    " * silently fail to bind (cod-16 gates the pair at --emit). Loaded FIRST by globals.css",
+    " * (step 1 of the five-step import order): faces register before any stack consumes them.",
+    " * To change a family, edit design.tokens.json and re-run derive-personality.mjs --emit. */",
+  ];
+  for (const entry of entries) lines.push("", `/* ${entry.family} — ${entry.pkg} */`, ...entry.imports);
+  for (const family of unresolved) lines.push("", `/* UNRESOLVED: "${family}" — no known @fontsource package registers it; register it via @font-face or swap the family (cod-16). */`);
+  if (entries.length === 0 && unresolved.length === 0) lines.push("", "/* every stack family is a system/generic face — nothing to register. */");
+  return lines.join("\n") + "\n";
+}
+
+// Contract 2 in full: generate fonts.css from the artifact's fontFamily tokens and run the cod-16
+// binding gate over the emitted stacks — (a) each named family rides a generated import whose
+// package is installed (project targets; standalone targets degrade to import-list validation), or
+// (b) is a recognized system/generic family. Returns { fontsCss, failures }.
+function buildFontBinding(views, doc, outdir, errors) {
+  const resolveFamily = loadFontResolver();
+  const { stacks, importFamilies } = collectFontSurfaces(views, doc, errors);
+  const deps = readTargetDeps(outdir);
+  const entries = [];
+  const unresolved = [];
+  for (const family of importFamilies) {
+    const hit = resolveFamily(family);
+    if (hit) { entries.push(hit); continue; }
+    const variablePkg = `@fontsource-variable/${familySlug(family)}`;
+    if (deps !== null && variablePkg in deps) {
+      // The consumer already installed the variable package (registers the "<Family> Variable" name).
+      entries.push({ family, pkg: variablePkg, imports: [`@import '${variablePkg}';`] });
+      continue;
+    }
+    unresolved.push(family);
+  }
+  const entryByFamily = new Map(entries.map((entry) => [entry.family.toLowerCase(), entry]));
+  const failures = [];
+  for (const stack of stacks) {
+    for (const family of stack.families) {
+      const key = family.toLowerCase();
+      if (SYSTEM_FONT_KEYWORDS.has(key)) continue;
+      const entry = entryByFamily.get(key);
+      const slug = familySlug(family);
+      if (!entry) {
+        failures.push(`"${family}" (emitted ${stack.name} stack): no known @fontsource package registers it (typography.csv, fonts-known.json${deps !== null ? ", package.json" : ""}) — install and register one (npm install @fontsource/${slug}, then re-run --emit) or swap to a bindable family / system generic.`);
+      } else if (deps !== null && !(entry.pkg in deps) && !(`@fontsource/${slug}` in deps) && !(`@fontsource-variable/${slug}` in deps)) {
+        failures.push(`"${family}" (emitted ${stack.name} stack): its registering import needs ${entry.pkg}, absent from package.json — npm install ${entry.pkg}`);
+      }
+    }
+  }
+  return { fontsCss: emitFontsCss(entries, unresolved), failures };
 }
 
 // ---------------------------------------------------------------------------
@@ -639,17 +1054,11 @@ function deriveEaseEnter(easeDefault) {
   return "cubic-bezier(0.16, 1, 0.3, 1)";
 }
 
-// Derive --stagger-delay in ms: duration-unit x 0.15, clamped 0-40.
-function deriveStaggerMs(durationUnit) {
-  const n = parseFloat(durationUnit);
-  const raw = Number.isNaN(n) ? 0 : n * 0.15;
-  return Math.max(0, Math.min(40, Math.round(raw)));
-}
-
-// Build the [data-style] primitive lines (governed density refs + derived temporals inserted after ease-default).
-function buildStyleBlockLines(primitives) {
+// Build the [data-style] primitive lines (governed density refs + derived temporals inserted after
+// the temporal family), then the elevation composites and the optional wash pair.
+function buildStyleBlockLines(doc) {
+  const primitives = doc.primitives;
   const easeEnter = deriveEaseEnter(primitives["ease-default"]);
-  const staggerMs = deriveStaggerMs(primitives["duration-unit"]);
   const lines = [];
   for (const key of PRIMITIVES) {
     if (key === "density-gap") lines.push("  --density-gap: var(--density-base-gap);");
@@ -657,10 +1066,18 @@ function buildStyleBlockLines(primitives) {
     else if (key === "font-sans") lines.push(`  --font-sans: ${quoteFontStack(primitives["font-sans"])};`);
     else if (key === "font-mono") lines.push(`  --font-mono: ${quoteFontStack(primitives["font-mono"])};`);
     else lines.push(`  --${key}: ${primitives[key]};`);
-    if (key === "ease-default") {
+    if (key === "stagger-unit") {
       lines.push(`  --ease-enter: ${easeEnter};   /* derived from ease-default */`);
       lines.push("  --ease-exit: var(--ease-default);              /* derived: departure mirrors the neutral curve */");
-      lines.push(`  --stagger-delay: ${staggerMs}ms;                          /* derived: duration-unit × 0.15, clamped 0–40ms */`);
+      lines.push("  --stagger-delay: var(--stagger-unit);                     /* derived: the motion-stagger cascade base */");
+    }
+  }
+  lines.push("  /* elevation (4) — designed shadow composites; --shadow-intensity stays the master multiplier */");
+  for (const level of ELEVATION_TOKENS) lines.push(`  --shadow-${level}: ${doc.elevation[level]};`);
+  if (doc.wash) {
+    lines.push("  /* wash (optional, <= 2) — low-chroma tint ramps, consumed only on budget-granted surfaces */");
+    for (const key of WASH_TOKENS) {
+      if (doc.wash[key] !== undefined) lines.push(`  --wash-${key}: ${doc.wash[key]};`);
     }
   }
   return lines.join("\n");
@@ -678,23 +1095,26 @@ function emitPersonalityCss(doc, slug, meta) {
 
   const semanticLines = SEMANTIC_TOKENS.map((t) => `  --${t}: ${light[t]};`).join("\n");
   const substrateLines = SUBSTRATE_TOKENS.map((t) => `  --${t}: ${light[t]};`).join("\n");
-  const styleLines = buildStyleBlockLines(p);
+  const styleLines = buildStyleBlockLines(doc);
 
   const darkSection = dark
     ? `/* ── Dark theme — OPT-IN ONLY (this look ships a dark overlay). ──
- * design.tokens.dark.json remaps all 34 color tokens; <html data-theme="dark">
- * opts in. Light stays the default. */
-[data-theme="dark"] {
-  /* semantic (17) */
+ * CASCADE CONTRACT 1b: :root[data-theme="dark"] (0,2,0) — a lone [data-theme="dark"]
+ * attribute selector (0,1,0) loses to the library's later bare :root block by source
+ * order. design.tokens.dark.json remaps all 36 color tokens; <html data-theme="dark">
+ * opts in (theme-default decides the boot attribute). */
+:root[data-theme="dark"] {
+  /* semantic (19) */
 ${SEMANTIC_TOKENS.map((t) => `  --${t}: ${dark[t]};`).join("\n")}
   /* substrate (17, the D6 set) — popover/secondary/chart/sidebar the library consumes */
 ${SUBSTRATE_TOKENS.map((t) => `  --${t}: ${dark[t]};`).join("\n")}
 }`
     : `/* ── Dark theme — OPT-IN ONLY. ──
- * Emitted only when the artifact ships a design.tokens.dark.json dark overlay.
- * Light stays the default; this block never appears for a light-only project.
-[data-theme="dark"] {
-  --background: ...; --foreground: ...; ... all 34 tokens remapped ...
+ * Emitted only when the artifact ships a design.tokens.dark.json dark overlay,
+ * as :root[data-theme="dark"] (0,2,0 — armored against the library's later :root).
+ * This block never appears for a light-only project.
+:root[data-theme="dark"] {
+  --background: ...; --foreground: ...; ... all 36 tokens remapped ...
 } */`;
 
   return `/* src/styles/personality.css — operator-UI personality tokens (emitted; do not hand-edit).
@@ -706,14 +1126,14 @@ ${SUBSTRATE_TOKENS.map((t) => `  --${t}: ${dark[t]};`).join("\n")}
  *   density:   ${density}   (<html data-density="${density}">)
  *   verbosity: ${verbosity}   (<html data-verbosity="${verbosity}">)
  *   feedback:  ${feedback}   (<html data-feedback="${feedback}">)
- *   theme:     ${meta.theme}   (<html data-theme="${meta.theme}">)   — light is the default; dark is opt-in
+ *   theme:     ${meta.theme}   (<html data-theme="${meta.theme}">)   — the payload's theme-default decides the boot theme
  *   artifact:  design.tokens.json (resolved via design.resolver.json)   — provenance: ${meta.provenance}, sourced ${meta.sourced}
  *
  * Semantic-token doctrine: components name purpose (bg-card, text-foreground, border-border);
  * this file resolves those names to values. Components never use dark: prefixes or literal colors.
  */
 
-/* ── System baseline: the 26 primitives at neutral operator defaults. ──
+/* ── System baseline: the 27 primitives at neutral operator defaults. ──
  * The safety net if <html> ever carries no data-style. The project's real
  * values live in the single [data-style="${slug}"] block below, which
  * overrides these. Improve/extract rewrites that block, never this baseline. */
@@ -726,9 +1146,10 @@ ${SUBSTRATE_TOKENS.map((t) => `  --${t}: ${dark[t]};`).join("\n")}
   --density-base-inset: 1;
   --density-gap: var(--density-base-gap);
   --density-inset: var(--density-base-inset);
-  /* typographic */
-  --font-sans: "Inter", system-ui, sans-serif;
-  --font-mono: "JetBrains Mono", ui-monospace, monospace;
+  /* typographic — generics only: the baseline never names a webfont it cannot
+   * guarantee is registered (cod-16); the [data-style] block carries the real stacks. */
+  --font-sans: system-ui, sans-serif;
+  --font-mono: ui-monospace, SFMono-Regular, monospace;
   --font-weight-normal: 400;
   --font-weight-strong: 600;
   --heading-tracking: -0.01em;
@@ -738,11 +1159,17 @@ ${SUBSTRATE_TOKENS.map((t) => `  --${t}: ${dark[t]};`).join("\n")}
   --duration-normal: var(--duration-unit);
   --duration-slow: calc(var(--duration-unit) * 2);
   --ease-default: cubic-bezier(0.4, 0, 0.2, 1);
+  --stagger-unit: 30ms;
   --ease-enter: cubic-bezier(0.16, 1, 0.3, 1);
   --ease-exit: var(--ease-default);
-  --stagger-delay: 30ms;
+  --stagger-delay: var(--stagger-unit);
   /* surface */
   --contrast-boost: 1;
+  /* elevation (neutral slate; the [data-style] block below carries the designed composites) */
+  --shadow-sm: 0 1px 3px 0 rgb(15 23 42 / calc(0.10 * var(--shadow-intensity))), 0 1px 2px -1px rgb(15 23 42 / calc(0.10 * var(--shadow-intensity)));
+  --shadow-md: 0 4px 6px -1px rgb(15 23 42 / calc(0.10 * var(--shadow-intensity))), 0 2px 4px -2px rgb(15 23 42 / calc(0.10 * var(--shadow-intensity)));
+  --shadow-lg: 0 10px 15px -3px rgb(15 23 42 / calc(0.10 * var(--shadow-intensity))), 0 4px 6px -4px rgb(15 23 42 / calc(0.10 * var(--shadow-intensity)));
+  --shadow-overlay: 0 20px 25px -5px rgb(15 23 42 / calc(0.10 * var(--shadow-intensity))), 0 8px 10px -6px rgb(15 23 42 / calc(0.10 * var(--shadow-intensity)));
   /* iconography */
   --icon-stroke: 1.75;
   --icon-size-base: 16px;
@@ -765,13 +1192,14 @@ ${SUBSTRATE_TOKENS.map((t) => `  --${t}: ${dark[t]};`).join("\n")}
 }
 
 /* ── Semantic + substrate color tokens — light theme. ──
- * CASCADE CONTRACT 1: the doubled selector out-specifies the library's bare
- * :root defaults in @nurix/components/styles.css — but ONLY because <html> carries
- * data-theme="light". A bare :root here loses to the later library import. All 34
- * tokens are set (D6): no consumed token falls back to a shadcn-gray default. */
+ * CASCADE CONTRACT 1: both theme blocks carry the same 0,2,0 armor — light as
+ * :root, :root[data-theme="light"] and dark as :root[data-theme="dark"] — because
+ * a bare :root or a lone attribute selector loses to the library's later :root
+ * block in @nurix/components/styles.css by source order. All 36 tokens are set
+ * (D6): no consumed token falls back to a shadcn-gray default. */
 :root,
 :root[data-theme="light"] {
-  /* semantic (17) */
+  /* semantic (19) */
 ${semanticLines}
   /* substrate (17, the D6 set) — popover/secondary/chart/sidebar the library consumes */
 ${substrateLines}
@@ -779,9 +1207,10 @@ ${substrateLines}
 
 /* ── The project personality: the single [data-style] block (D3, rosterless). ──
  * Named after the project — not a preset. This materializes the artifact's
- * primitive token group: all 26 primitives + the derived temporal. It is the
- * one block improve/extract rewrites. density-gap/inset are governed refs, so
- * the global tier and per-surface step still compose. */
+ * primitive token group (all 27 primitives + the derived temporals), the four
+ * elevation composites, and the optional wash pair. It is the one block
+ * improve/extract rewrites. density-gap/inset are governed refs, so the global
+ * tier and per-surface step still compose. */
 [data-style="${slug}"] {
 ${styleLines}
 }
@@ -812,10 +1241,34 @@ ${styleLines}
 
 ${darkSection}
 
+/* ── Motion moments — named classes consuming the temporal tokens. ──
+ * motion-lift: hover lift (-1px + elevation.sm) at duration-fast/ease-default.
+ * motion-stagger: children arrival cascade at --stagger-delay, capped at 8
+ * children (mot-08); consumption is budget-gated by the surface stamp. Both are
+ * inert under prefers-reduced-motion (mot-03). */
+@media (prefers-reduced-motion: no-preference) {
+  .motion-lift {
+    transition: transform var(--duration-fast) var(--ease-default), box-shadow var(--duration-fast) var(--ease-default);
+  }
+  .motion-lift:hover {
+    transform: translateY(-1px);
+    box-shadow: var(--shadow-sm);
+  }
+  @keyframes motion-stagger-arrive {
+    from { opacity: 0; transform: translateY(4px); }
+    to { opacity: 1; transform: translateY(0); }
+  }
+  .motion-stagger > * {
+    animation: motion-stagger-arrive var(--duration-normal) var(--ease-enter) backwards;
+    animation-delay: calc(var(--stagger-delay) * 7);   /* children past the 8-cap arrive with the 8th */
+  }
+${Array.from({ length: 8 }, (_, i) => `  .motion-stagger > :nth-child(${i + 1}) { animation-delay: calc(var(--stagger-delay) * ${i}); }`).join("\n")}
+}
+
 /* ── Accessibility ── */
 @media (prefers-reduced-motion: reduce) {
   :root, [data-style] {
-    --duration-unit: 0ms; --stagger-delay: 0ms;
+    --duration-unit: 0ms; --stagger-unit: 0ms; --stagger-delay: 0ms;
     --ease-default: linear; --ease-enter: linear; --ease-exit: linear;
     --feedback-press-scale: 1;
   }
@@ -838,15 +1291,17 @@ function emitGlobalsCss(doc) {
 
   return `/* src/styles/globals.css — Tailwind v4 glue + @theme inline mappings (emitted). */
 
-/* CASCADE CONTRACT 2: this four-step order is LOAD-BEARING. The library's
- * styles.css ships its own :root token defaults and its own @theme radius scale;
- * our @theme MUST come AFTER the import to win the radius scale and own every
- * mapping. rules/frontend.md states the same order — co-authority. */
-@import "./personality.css";          /* 1. token source (must be first) */
-@import "tailwindcss";                /* 2. framework */
-@import "@nurix/components/styles.css"; /* 3. library (before our @theme) */
-
-@theme inline {                       /* 4. consumer theme — AFTER the library, so it wins */
+/* CASCADE CONTRACT 2: this five-step order is LOAD-BEARING. fonts.css registers the
+ * @fontsource faces before any stack consumes them; the library's styles.css ships
+ * its own :root token defaults and its own @theme radius scale, so our @theme MUST
+ * come AFTER the import to win the radius scale and own every mapping.
+ * rules/frontend.md states the same order — co-authority. */
+@import "./fonts.css";                /* 1. font registration (faces before stacks) */
+@import "./personality.css";          /* 2. token source */
+@import "tailwindcss";                /* 3. framework */
+@import "@nurix/components/styles.css"; /* 4. library (before our @theme) */
+
+@theme inline {                       /* 5. consumer theme — AFTER the library, so it wins */
   /* radius scale — shadcn offsets on --radius, re-asserted so the CONSUMER owns it.
    * A flat personality sets --radius: 0 → every step collapses to 0. */
   --radius-sm: calc(var(--radius) - 4px);
@@ -859,12 +1314,14 @@ function emitGlobalsCss(doc) {
    * tier AND the per-surface density step into the library's internals. */
   --spacing: calc(0.25rem * var(--density-gap));
 
-  /* shadow — alpha rides --shadow-intensity (matches the library's shadow-xs/sm/md/lg use) */
+  /* shadow — the elevation.* composites become the shadow-* utilities; every alpha rides
+   * --shadow-intensity (2xs/xs stay the neutral slate hairlines the library leans on) */
   --shadow-2xs: 0 1px 2px 0 rgb(15 23 42 / calc(0.04 * var(--shadow-intensity)));
   --shadow-xs:  0 1px 2px 0 rgb(15 23 42 / calc(0.06 * var(--shadow-intensity)));
-  --shadow-sm:  0 1px 3px 0 rgb(15 23 42 / calc(0.10 * var(--shadow-intensity))), 0 1px 2px -1px rgb(15 23 42 / calc(0.10 * var(--shadow-intensity)));
-  --shadow-md:  0 4px 6px -1px rgb(15 23 42 / calc(0.10 * var(--shadow-intensity))), 0 2px 4px -2px rgb(15 23 42 / calc(0.10 * var(--shadow-intensity)));
-  --shadow-lg:  0 10px 15px -3px rgb(15 23 42 / calc(0.10 * var(--shadow-intensity))), 0 4px 6px -4px rgb(15 23 42 / calc(0.10 * var(--shadow-intensity)));
+  --shadow-sm:  ${doc.elevation.sm};
+  --shadow-md:  ${doc.elevation.md};
+  --shadow-lg:  ${doc.elevation.lg};
+  --shadow-overlay: ${doc.elevation.overlay};
 
   /* font weight — two-weight discipline: medium/semibold/bold all resolve to the
    * single emphasis weight; operator UI carries no third weight. normal is emitted
@@ -878,6 +1335,16 @@ function emitGlobalsCss(doc) {
   --tracking-tighter: var(--heading-tracking);
   --tracking-tight: var(--heading-tracking);
 
+  /* type ramp — the seven authored steps as text-* utilities (typ-09: the type scale IS the
+   * declared ramp; text-display is the scale-drama step, brand-forward surfaces only, typ-20) */
+${RAMP_STEPS.map((step) => {
+    const r = doc.ramp[step];
+    return `  --text-${step}: ${r.fontSize};
+  --text-${step}--line-height: ${r.lineHeight};
+  --text-${step}--font-weight: ${r.fontWeight};
+  --text-${step}--letter-spacing: ${r.letterSpacing};`;
+  }).join("\n")}
+
   /* fonts — emitted as the literal stack: a font is not a runtime-toggled token, and
    * the theme key shares a name with the personality primitive (no self-reference).
    * personality.css carries the same --font-sans/--font-mono for direct var() use. */
@@ -891,15 +1358,17 @@ function emitGlobalsCss(doc) {
   --transition-enter: var(--duration-normal) var(--ease-enter);
   --transition-exit: var(--duration-fast) var(--ease-exit);
 
-  /* semantic + substrate color maps — all 34, so bg-popover / bg-chart-1 / bg-sidebar resolve.
+  /* semantic + substrate color maps — all 36, so bg-popover / bg-chart-1 / bg-sidebar and the
+   * dark ladder's bg-surface-raised / bg-surface-overlay resolve.
    * --color-destructive-foreground is mapped explicitly (D6): the library leaves it unmapped. */
 ${colorMaps}
 }
 
-/* dark variant — emitted ONLY when the project ships dark; redefines the library's
- * class-based dark to follow data-theme so the library's dark: utilities honor our
- * convention. Absent for a light-only project.
-@custom-variant dark (&:where([data-theme="dark"], [data-theme="dark"] *)); */
+/* dark variant — ALWAYS ACTIVE: redefines the library's class-based dark: variant to
+ * follow the data-theme attribute, so library dark: utilities (legal inside the library,
+ * banned in project JSX by the no-literals rule) track the same attribute the theme
+ * blocks armor. Inert until <html data-theme="dark">; harmless for a light-only project. */
+@custom-variant dark (&:where([data-theme="dark"], [data-theme="dark"] *));
 `;
 }
 
@@ -932,7 +1401,7 @@ function writeFileEnsured(path, content) {
 
 // Print usage and exit non-zero.
 function usage() {
-  process.stderr.write("usage: derive-personality.mjs <artifact-dir> [--check | --emit <outdir>] [--theme light|dark]\n");
+  process.stderr.write("usage: derive-personality.mjs <artifact-dir> [--check | --emit <outdir> [--provisional]] [--theme light|dark]\n");
   process.exit(2);
 }
 
@@ -942,20 +1411,23 @@ function main() {
   let artifactDir = null;
   let mode = "check";
   let outdir = null;
-  let theme = "light";
+  let theme = null; // null = follow the payload's theme-default
+  let provisional = false;
   for (let i = 0; i < argv.length; i++) {
     const a = argv[i];
     if (a === "--check") mode = "check";
     else if (a === "--emit") { mode = "emit"; outdir = argv[++i] ?? null; }
     else if (a === "--theme") { theme = argv[++i] ?? null; }
+    else if (a === "--provisional") provisional = true;
     else if (!a.startsWith("-") && artifactDir === null) artifactDir = a;
     else usage();
   }
   if (!artifactDir) usage();
   if (mode === "emit" && !outdir) usage();
-  if (!LEGAL_THEMES.includes(theme)) usage();
+  if (provisional && mode !== "emit") usage();
+  if (theme !== null && !LEGAL_THEMES.includes(theme)) usage();
 
-  const { errors, payload, views, hints, hasDark } = runCheck(artifactDir, theme);
+  const { errors, payload, views, hints, theme: bootTheme, hasDark, hasWash } = runCheck(artifactDir, theme);
 
   if (errors.length > 0) {
     process.stderr.write(`check FAILED (${artifactDir}): ${errors.length} issue(s)\n`);
@@ -967,39 +1439,59 @@ function main() {
 
   if (mode === "check") {
     const hintNote = hints.length > 0 ? `, ${hints.length} hint(s) outstanding (emit will refuse)` : "";
-    process.stdout.write(`check PASSED (${artifactDir}): rules 1–11 OK — 26 primitives, 34 color roles, typography 3+6, payload/manifest/parse-back OK — provenance=${payload.provenance}, style=${slug}, theme=${theme}${hasDark ? ", dark overlay present" : ""}${hintNote}\n`);
+    process.stdout.write(`check PASSED (${artifactDir}): rules 1–15 OK — 27 primitives, 36 color roles, typography 3+7, elevation 4${hasWash ? ", wash present" : ""}, payload/manifest/parse-back OK — provenance=${payload.provenance}, style=${slug}, theme=${bootTheme}${hasDark ? ", dark overlay present" : ""}${hintNote}\n`);
     process.exit(0);
   }
 
-  // Rule 12 — emission precondition: refuse while any token carries a hint.
-  if (hints.length > 0) {
+  // Rule 12 — emission precondition: refuse while any token carries a hint. --provisional (the
+  // golden/regression flow) emits hinted tokens at their provisional $values instead — loudly.
+  if (hints.length > 0 && !provisional) {
     process.stderr.write(`emit REFUSED (${artifactDir}): ${hints.length} unresolved hint(s) — rule 12: every gated token must be concrete before emission.\n`);
     for (const h of hints) process.stderr.write(`  - ${h.key}: hint: ${h.text}\n`);
     process.stderr.write("  Resolve each with judgment: set the real $value, delete the hint key, record the rationale in $description — then re-run --emit.\n");
     process.exit(1);
   }
+  if (hints.length > 0) {
+    process.stdout.write(`emit PROVISIONAL (${artifactDir}): ${hints.length} hint(s) emitted at their provisional $values — regression/golden flow only, never shipped output.\n`);
+  }
 
   const emitErrors = [];
   const doc = buildEmitterDoc(views, payload, emitErrors);
+  checkEmitterCompleteness(views, emitErrors);
+  const fontBinding = buildFontBinding(views, doc, outdir, emitErrors);
   if (emitErrors.length > 0) {
     process.stderr.write(`emit FAILED (${artifactDir}): ${emitErrors.length} issue(s)\n`);
     for (const e of emitErrors) process.stderr.write(`  - ${e}\n`);
     process.exit(1);
   }
 
-  const meta = { provenance: payload.provenance, sourced: payload.sourced, theme };
+  // Contract 2 — the cod-16 font-binding gate, fail-closed at --emit. --provisional (the golden/
+  // regression flow over hint-carrying or brand-font library twins) demotes it to a loud warning.
+  if (fontBinding.failures.length > 0) {
+    if (!provisional) {
+      process.stderr.write(`emit FAILED (${artifactDir}): font binding (cod-16) — ${fontBinding.failures.length} unbound famil${fontBinding.failures.length === 1 ? "y" : "ies"}\n`);
+      for (const f of fontBinding.failures) process.stderr.write(`  - ${f}\n`);
+      process.exit(1);
+    }
+    process.stdout.write(`emit PROVISIONAL font-binding warning (${artifactDir}): ${fontBinding.failures.length} unbound famil${fontBinding.failures.length === 1 ? "y" : "ies"} — cod-16 fails closed at a real --emit\n`);
+    for (const f of fontBinding.failures) process.stdout.write(`  - ${f}\n`);
+  }
+
+  const meta = { provenance: payload.provenance, sourced: payload.sourced, theme: bootTheme };
   const personalityCss = emitPersonalityCss(doc, slug, meta);
   const globalsCss = emitGlobalsCss(doc);
   const htmlAttrs = emitIndexHtmlAttributes(doc, slug, meta);
   const personalityPath = join(outdir, "src/styles/personality.css");
   const globalsPath = join(outdir, "src/styles/globals.css");
+  const fontsPath = join(outdir, "src/styles/fonts.css");
   const attrsPath = join(outdir, "index-html-attributes.txt");
   writeFileEnsured(personalityPath, personalityCss);
   writeFileEnsured(globalsPath, globalsCss);
+  writeFileEnsured(fontsPath, fontBinding.fontsCss);
   writeFileEnsured(attrsPath, htmlAttrs);
 
   process.stdout.write(`emitted personality system for style=${slug} → ${outdir}\n`);
-  process.stdout.write(`  ${personalityPath}\n  ${globalsPath}\n  ${attrsPath}\n`);
+  process.stdout.write(`  ${personalityPath}\n  ${globalsPath}\n  ${fontsPath}\n  ${attrsPath}\n`);
   process.exit(0);
 }