@nurix/etna 0.18.18 → 0.18.20

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

@@ -0,0 +1,706 @@
+#!/usr/bin/env node
+// skills/design/scripts/derive-personality.mjs — design.md parser, coverage gate (--check), and token emitter (--emit) for the operator-UI personality system (D29, D6).
+
+import { readFileSync, writeFileSync, mkdirSync } from "node:fs";
+import { dirname, join } from "node:path";
+
+// The 26 visual primitives, in emission order (names are law; no leading --).
+const PRIMITIVES = [
+  "radius", "shadow-intensity", "border-weight", "density-gap", "density-inset",
+  "font-sans", "font-mono", "font-weight-normal", "font-weight-strong", "heading-tracking",
+  "duration-unit", "duration-fast", "duration-normal", "duration-slow", "ease-default",
+  "contrast-boost",
+  "icon-stroke", "icon-size-base",
+  "sidebar-width-expanded", "sidebar-width-collapsed", "topbar-height", "side-panel-width",
+  "side-panel-width-rich", "modal-width-max", "form-max-width", "table-row-height",
+];
+
+// The 17 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",
+];
+
+// The 17 substrate color tokens (the D6 set), in emission order.
+const SUBSTRATE_TOKENS = [
+  "popover", "popover-foreground", "secondary", "secondary-foreground",
+  "chart-1", "chart-2", "chart-3", "chart-4", "chart-5",
+  "sidebar", "sidebar-foreground", "sidebar-primary", "sidebar-primary-foreground",
+  "sidebar-accent", "sidebar-accent-foreground", "sidebar-border", "sidebar-ring",
+];
+
+const ALL_TOKENS = [...SEMANTIC_TOKENS, ...SUBSTRATE_TOKENS];
+
+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"];
+
+// 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 };
+
+// Strip a trailing #-comment while respecting quoted spans (hex colors are quoted, so an unquoted # is always a comment).
+function stripComment(line) {
+  let inSingle = false, inDouble = false;
+  for (let i = 0; i < line.length; i++) {
+    const c = line[i];
+    if (c === '"' && !inSingle) inDouble = !inDouble;
+    else if (c === "'" && !inDouble) inSingle = !inSingle;
+    else if (c === "#" && !inSingle && !inDouble) return line.slice(0, i);
+  }
+  return line;
+}
+
+// Remove one layer of matching surrounding quotes from a scalar.
+function unquote(raw) {
+  const s = raw.trim();
+  if (s.length >= 2 && ((s[0] === '"' && s.at(-1) === '"') || (s[0] === "'" && s.at(-1) === "'"))) {
+    return s.slice(1, -1);
+  }
+  return s;
+}
+
+// Split a string on a delimiter at bracket-depth 0 and outside quotes (handles nested [] {} and quoted commas).
+function splitTopLevel(str, delim) {
+  const parts = [];
+  let depth = 0, inSingle = false, inDouble = false, cur = "";
+  for (const c of str) {
+    if (c === '"' && !inSingle) { inDouble = !inDouble; cur += c; }
+    else if (c === "'" && !inDouble) { inSingle = !inSingle; cur += c; }
+    else if (!inSingle && !inDouble && (c === "[" || c === "{")) { depth++; cur += c; }
+    else if (!inSingle && !inDouble && (c === "]" || c === "}")) { depth--; cur += c; }
+    else if (!inSingle && !inDouble && c === delim && depth === 0) { parts.push(cur); cur = ""; }
+    else cur += c;
+  }
+  parts.push(cur);
+  return parts;
+}
+
+// Parse a scalar / inline array / inline object into a JS value.
+function parseScalar(raw) {
+  const s = raw.trim();
+  if (s.startsWith("[")) return parseInlineArray(s);
+  if (s.startsWith("{")) return parseInlineObject(s);
+  return unquote(s);
+}
+
+// Parse an inline [a, b, c] array into a JS array of parsed scalars.
+function parseInlineArray(s) {
+  const inner = s.slice(s.indexOf("[") + 1, s.lastIndexOf("]"));
+  if (inner.trim() === "") return [];
+  return splitTopLevel(inner, ",").map((x) => parseScalar(x)).filter((v) => !(typeof v === "string" && v === ""));
+}
+
+// Parse an inline { k: v, ... } object into a plain JS object.
+function parseInlineObject(s) {
+  const inner = s.slice(s.indexOf("{") + 1, s.lastIndexOf("}"));
+  const obj = {};
+  for (const part of splitTopLevel(inner, ",")) {
+    if (part.trim() === "") continue;
+    const ci = part.indexOf(":");
+    if (ci < 0) continue;
+    obj[part.slice(0, ci).trim()] = parseScalar(part.slice(ci + 1));
+  }
+  return obj;
+}
+
+// Turn a block's raw text into meaningful {indent, content} nodes (comment-stripped, blank-dropped).
+function toNodes(text) {
+  const nodes = [];
+  for (const rawLine of text.split("\n")) {
+    const line = stripComment(rawLine);
+    if (line.trim() === "") continue;
+    const indent = line.length - line.trimStart().length;
+    nodes.push({ indent, content: line.trim() });
+  }
+  return nodes;
+}
+
+// Recursively build a nested map from indentation nodes (tolerant mini-YAML for 2-space maps).
+function buildMap(nodes, start, indent) {
+  const obj = {};
+  let i = start;
+  while (i < nodes.length) {
+    const node = nodes[i];
+    if (node.indent < indent) break;
+    if (node.indent > indent) { i++; continue; }
+    const ci = node.content.indexOf(":");
+    if (ci < 0) { i++; continue; }
+    const key = node.content.slice(0, ci).trim();
+    const rest = node.content.slice(ci + 1).trim();
+    if (rest === "") {
+      if (i + 1 < nodes.length && nodes[i + 1].indent > indent) {
+        const [child, next] = buildMap(nodes, i + 1, nodes[i + 1].indent);
+        obj[key] = child;
+        i = next;
+      } else {
+        obj[key] = {};
+        i++;
+      }
+    } else {
+      obj[key] = parseScalar(rest);
+      i++;
+    }
+  }
+  return [obj, i];
+}
+
+// Parse a fenced-block body into a nested object via the mini-YAML parser.
+function parseBlock(text) {
+  const [obj] = buildMap(toNodes(text), 0, 0);
+  return obj;
+}
+
+// Extract the body of the fenced block whose info-string ends with the given label (e.g. "design-primitives").
+function extractFencedBlock(source, label) {
+  const lines = source.split("\n");
+  const openRe = new RegExp("^`{3,}\\s*yaml\\s+" + label + "\\s*$");
+  const closeRe = /^`{3,}\s*$/;
+  let capturing = false;
+  const body = [];
+  for (const line of lines) {
+    if (!capturing) {
+      if (openRe.test(line.trim())) capturing = true;
+      continue;
+    }
+    if (closeRe.test(line.trim())) return body.join("\n");
+    body.push(line);
+  }
+  return capturing ? body.join("\n") : null;
+}
+
+// Parse the leading --- frontmatter into a flat object.
+function parseFrontmatter(source) {
+  const m = /^---\s*\n([\s\S]*?)\n---\s*(\n|$)/.exec(source);
+  if (!m) return null;
+  const obj = {};
+  for (const rawLine of m[1].split("\n")) {
+    const line = stripComment(rawLine);
+    const ci = line.indexOf(":");
+    if (ci < 0) continue;
+    obj[line.slice(0, ci).trim()] = unquote(line.slice(ci + 1));
+  }
+  return obj;
+}
+
+// Parse a whole design.md into its three parsed parts.
+function parseDesignMd(source) {
+  const frontmatter = parseFrontmatter(source);
+  const primitivesText = extractFencedBlock(source, "design-primitives");
+  const manifestText = extractFencedBlock(source, "lever-manifest");
+  return {
+    frontmatter,
+    primitives: primitivesText == null ? null : parseBlock(primitivesText),
+    manifest: manifestText == null ? null : parseBlock(manifestText),
+  };
+}
+
+// True when a parsed leaf is a bare "hint:" pending judgment.
+function isHint(value) {
+  return typeof value === "string" && value.trim().startsWith("hint:");
+}
+
+// True when a leaf is present as a non-empty scalar.
+function isFilled(value) {
+  return typeof value === "string" && value.trim() !== "";
+}
+
+// True when an array of numeric-ish values is strictly ascending.
+function isAscending(arr) {
+  const nums = arr.map((v) => parseFloat(v));
+  if (nums.some((n) => Number.isNaN(n))) return false;
+  for (let i = 1; i < nums.length; i++) if (!(nums[i] > nums[i - 1])) return false;
+  return true;
+}
+
+// Run the coverage gate; return { errors: string[] }.
+function runCoverageGate(doc) {
+  const errors = [];
+  const { frontmatter, primitives, manifest } = doc;
+
+  // Rule 1 — frontmatter with schema and legal provenance.
+  if (!frontmatter) {
+    errors.push("frontmatter: missing --- frontmatter block");
+  } else {
+    if (frontmatter.schema !== "design-md/v1") {
+      errors.push(`frontmatter: schema must be "design-md/v1" (found ${frontmatter.schema ?? "nothing"})`);
+    }
+    if (!LEGAL_PROVENANCE.includes(frontmatter.provenance)) {
+      errors.push(`frontmatter: provenance must be one of ${LEGAL_PROVENANCE.join("|")} (found ${frontmatter.provenance ?? "nothing"})`);
+    }
+  }
+
+  // Rule 2 — both machine blocks present and parseable.
+  if (!primitives) errors.push("block: missing or unparseable `yaml design-primitives` block");
+  if (!manifest) errors.push("block: missing or unparseable `yaml lever-manifest` block");
+  if (!primitives || !manifest) return { errors };
+
+  // Rule 3 — every primitive assigned or hinted.
+  for (const key of PRIMITIVES) {
+    const v = primitives[key];
+    if (v === undefined) errors.push(`missing primitive: ${key}`);
+    else if (!isFilled(v)) errors.push(`empty primitive: ${key}`);
+  }
+
+  // Rule 4 — dials, tier, and traits.
+  if (!LEGAL_VERBOSITY.includes(primitives.verbosity)) {
+    errors.push(`dial verbosity: must be one of ${LEGAL_VERBOSITY.join("|")} (found ${primitives.verbosity ?? "nothing"})`);
+  }
+  if (!LEGAL_FEEDBACK.includes(primitives.feedback)) {
+    errors.push(`dial feedback: must be one of ${LEGAL_FEEDBACK.join("|")} (found ${primitives.feedback ?? "nothing"})`);
+  }
+  if (!LEGAL_DENSITY.includes(primitives["density-tier"])) {
+    errors.push(`density-tier: must be one of ${LEGAL_DENSITY.join("|")} (found ${primitives["density-tier"] ?? "nothing"})`);
+  }
+  const traits = primitives["product-traits"];
+  if (!Array.isArray(traits) || traits.length === 0) {
+    errors.push("product-traits: must be a non-empty list");
+  }
+
+  // Rule 5 — every color token valued under color-tokens.light.
+  const light = manifest["color-tokens"] && manifest["color-tokens"].light;
+  if (!light || typeof light !== "object") {
+    errors.push("color-tokens.light: missing color-tokens.light map");
+  } else {
+    for (const token of ALL_TOKENS) {
+      const v = light[token];
+      if (v === undefined) errors.push(`missing color token: ${token}`);
+      else if (!isFilled(v)) errors.push(`empty color token: ${token}`);
+    }
+  }
+
+  // Rule 6 — scales, motion, fonts, icons, accent-count.
+  const scaleCheck = (name, arr, allowAscending = true) => {
+    if (!Array.isArray(arr) || arr.length === 0) errors.push(`${name}: must be a non-empty list`);
+    else if (allowAscending && !isAscending(arr)) errors.push(`${name}: values must be ascending (found ${arr.join(", ")})`);
+  };
+  scaleCheck("spacing-scale", manifest["spacing-scale"]);
+  scaleCheck("radius-scale", manifest["radius-scale"]);
+
+  const shadow = manifest["shadow-levels"];
+  if (!Array.isArray(shadow) || shadow.length === 0) {
+    errors.push("shadow-levels: must be a non-empty list");
+  } else {
+    const ranks = shadow.map((s) => SHADOW_RANK[String(s).trim()]);
+    if (ranks.every((r) => r !== undefined)) {
+      for (let i = 1; i < ranks.length; i++) {
+        if (!(ranks[i] > ranks[i - 1])) { errors.push(`shadow-levels: must be ordered by increasing intensity (found ${shadow.join(", ")})`); break; }
+      }
+    }
+  }
+
+  const motion = manifest.motion;
+  if (!motion || typeof motion !== "object") {
+    errors.push("motion: missing motion block");
+  } else {
+    scaleCheck("motion.durations", motion.durations);
+    if (!Array.isArray(motion.easings) || motion.easings.length === 0) errors.push("motion.easings: must be a non-empty list");
+  }
+
+  const fonts = manifest.fonts;
+  if (!fonts || typeof fonts !== "object") {
+    errors.push("fonts: missing fonts block");
+  } else {
+    if (!isFilled(fonts.sans)) errors.push("fonts.sans: missing or empty");
+    if (!isFilled(fonts.mono)) errors.push("fonts.mono: missing or empty");
+  }
+
+  const icons = manifest.icons;
+  if (!icons || typeof icons !== "object") {
+    errors.push("icons: missing icons block");
+  } else {
+    if (!isFilled(icons.family)) errors.push("icons.family: missing or empty");
+    if (icons.stroke === undefined || String(icons.stroke).trim() === "") errors.push("icons.stroke: missing or empty");
+  }
+
+  const accent = parseFloat(manifest["accent-count"]);
+  if (Number.isNaN(accent) || accent < 1) errors.push(`accent-count: must be >= 1 (found ${manifest["accent-count"] ?? "nothing"})`);
+
+  return { errors };
+}
+
+// Collect every bare "hint:" leaf across primitives, dials, and color tokens for the emit refusal.
+function collectBareHints(doc) {
+  const hints = [];
+  const { primitives, manifest } = doc;
+  if (primitives) {
+    for (const key of [...PRIMITIVES, "verbosity", "feedback", "density-tier"]) {
+      if (isHint(primitives[key])) hints.push({ key, text: primitives[key].trim().slice(5).trim() });
+    }
+  }
+  const light = manifest && manifest["color-tokens"] && manifest["color-tokens"].light;
+  if (light) {
+    for (const token of ALL_TOKENS) {
+      if (isHint(light[token])) hints.push({ key: `color-tokens.light.${token}`, text: light[token].trim().slice(5).trim() });
+    }
+  }
+  return hints;
+}
+
+// Derive a rosterless data-style slug from the product name.
+function slugify(name) {
+  return String(name || "project").toLowerCase().trim()
+    .replace(/[^a-z0-9]+/g, "-").replace(/^-+|-+$/g, "") || "project";
+}
+
+// Quote multi-word font family names so the emitted CSS font stack is valid.
+function quoteFontStack(stack) {
+  return String(stack).split(",").map((f) => {
+    const t = f.trim();
+    if (t === "") return t;
+    if (t.startsWith('"') || t.startsWith("'")) return t;
+    return /\s/.test(t) ? `"${t}"` : t;
+  }).filter((t) => t !== "").join(", ");
+}
+
+// Derive --ease-enter: reuse ease-default if it is already a decelerate curve, else the emphasized-decelerate arrival curve.
+function deriveEaseEnter(easeDefault) {
+  const m = /cubic-bezier\(\s*[-\d.]+\s*,\s*([-\d.]+)/.exec(String(easeDefault));
+  if (m && parseFloat(m[1]) >= 0.9) return 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) {
+  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);");
+    else if (key === "density-inset") lines.push("  --density-inset: var(--density-base-inset);");
+    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") {
+      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 */`);
+    }
+  }
+  return lines.join("\n");
+}
+
+// Emit the full src/styles/personality.css content for a passing document.
+function emitPersonalityCss(doc, slug) {
+  const p = doc.primitives;
+  const light = doc.manifest["color-tokens"].light;
+  const density = p["density-tier"];
+  const verbosity = p.verbosity;
+  const feedback = p.feedback;
+
+  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);
+
+  return `/* src/styles/personality.css — operator-UI personality tokens (emitted; do not hand-edit).
+ *
+ * Active personality — code is the cache. There is no JSON sidecar; these values
+ * and the <html data-*> attributes in index.html ARE the state. To change the look,
+ * edit the resolved design.md and re-run derive-personality.mjs --emit.
+ *   style:     ${slug}   (<html data-style="${slug}">)   — the project's own personality (rosterless)
+ *   density:   ${density}   (<html data-density="${density}">)
+ *   verbosity: ${verbosity}   (<html data-verbosity="${verbosity}">)
+ *   feedback:  ${feedback}   (<html data-feedback="${feedback}">)
+ *   theme:     light   (<html data-theme="light">)   — light is the default; dark is opt-in
+ *
+ * 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. ──
+ * 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. */
+:root {
+  /* geometric */
+  --radius: 6px;
+  --shadow-intensity: 1;
+  --border-weight: 1px;
+  --density-base-gap: 1;                 /* the density tier writes this; see the density mechanism */
+  --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;
+  --font-weight-normal: 400;
+  --font-weight-strong: 600;
+  --heading-tracking: -0.01em;
+  /* temporal (+ derived) */
+  --duration-unit: 200ms;
+  --duration-fast: calc(var(--duration-unit) * 0.5);
+  --duration-normal: var(--duration-unit);
+  --duration-slow: calc(var(--duration-unit) * 2);
+  --ease-default: cubic-bezier(0.4, 0, 0.2, 1);
+  --ease-enter: cubic-bezier(0.16, 1, 0.3, 1);
+  --ease-exit: var(--ease-default);
+  --stagger-delay: 30ms;
+  /* surface */
+  --contrast-boost: 1;
+  /* iconography */
+  --icon-stroke: 1.75;
+  --icon-size-base: 16px;
+  /* operator layout */
+  --sidebar-width-expanded: 240px;
+  --sidebar-width-collapsed: 56px;
+  --topbar-height: 52px;
+  --side-panel-width: 480px;
+  --side-panel-width-rich: 640px;
+  --modal-width-max: 480px;
+  --form-max-width: 720px;
+  --table-row-height: 40px;
+  /* behavioral fallbacks (match verbosity=default + feedback=subtle) */
+  --label-display: inline-flex;
+  --helper-text-display: block;
+  --tooltip-delay: 500ms;
+  --feedback-press-scale: 0.99;
+  --focus-ring-width: 2px;
+  --focus-ring-offset: 1px;
+}
+
+/* ── 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. */
+:root,
+:root[data-theme="light"] {
+  /* semantic (17) */
+${semanticLines}
+  /* substrate (17, the D6 set) — popover/secondary/chart/sidebar the library consumes */
+${substrateLines}
+}
+
+/* ── The project personality: the single [data-style] block (D3, rosterless). ──
+ * Named after the project — not a preset. This materializes the design.md
+ * design-primitives block: 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. */
+[data-style="${slug}"] {
+${styleLines}
+}
+
+/* ── Behavioral dials (D4) — orthogonal to the visual primitives. ── */
+[data-verbosity="full"]    { --label-display: inline-flex; --helper-text-display: block; --tooltip-delay: 800ms; }
+[data-verbosity="default"] { --label-display: inline-flex; --helper-text-display: block; --tooltip-delay: 500ms; }
+[data-verbosity="compact"] { --label-display: none;        --helper-text-display: none;  --tooltip-delay: 200ms; }
+[data-verbosity="expert"]  { --label-display: none;        --helper-text-display: none;  --tooltip-delay: 0ms; }
+
+[data-feedback="subtle"]   { --feedback-press-scale: 0.99; --focus-ring-width: 2px; --focus-ring-offset: 1px; }
+[data-feedback="minimal"]  { --feedback-press-scale: 1;    --focus-ring-width: 1px; --focus-ring-offset: 0px; }
+
+/* ── Density: global tier → base multipliers (D31). ──
+ * The tier writes ONLY the base; --density-gap/inset resolve from it (above),
+ * so a per-surface step can re-derive relative to the tier. */
+[data-density="dense"]    { --density-base-gap: 0.85; --density-base-inset: 0.85; }
+[data-density="standard"] { --density-base-gap: 1;    --density-base-inset: 1; }
+[data-density="spacious"] { --density-base-gap: 1.15; --density-base-inset: 1.15; }
+
+/* ── Per-archetype density modifier (D31) — relative step on the tier, pure cascade, no JS. ──
+ * A surface element carries data-density-step; it re-derives one step off the
+ * inherited base. Reads --density-base-* (never itself) so it composes with the
+ * tier and never absolutely overrides it. The recomputed --density-gap flows into
+ * the library's p-*/gap-* through the @theme --spacing remap. */
+[data-density-step="tighter"] { --density-gap: calc(var(--density-base-gap) * 0.85); --density-inset: calc(var(--density-base-inset) * 0.85); }
+[data-density-step="looser"]  { --density-gap: calc(var(--density-base-gap) * 1.15); --density-inset: calc(var(--density-base-inset) * 1.15); }
+
+/* ── Dark theme — OPT-IN ONLY. ──
+ * Emitted only when the design.md ships a lever-manifest color-tokens.dark map.
+ * Light stays the default; this block never appears for a light-only project.
+[data-theme="dark"] {
+  --background: ...; --foreground: ...; ... all 34 tokens remapped ...
+} */
+
+/* ── Accessibility ── */
+@media (prefers-reduced-motion: reduce) {
+  :root, [data-style] {
+    --duration-unit: 0ms; --stagger-delay: 0ms;
+    --ease-default: linear; --ease-enter: linear; --ease-exit: linear;
+    --feedback-press-scale: 1;
+  }
+}
+@media (prefers-contrast: more) {
+  :root, [data-style] {
+    --contrast-boost: 1.15; --border-weight: 2px; --shadow-intensity: 0; --icon-stroke: 2;
+  }
+}
+`;
+}
+
+// Emit the full src/styles/globals.css content (Tailwind v4 glue + @theme inline mappings).
+function emitGlobalsCss(doc) {
+  const p = doc.primitives;
+  const fontSans = quoteFontStack(p["font-sans"]);
+  const fontMono = quoteFontStack(p["font-mono"]);
+  const fontWeightNormal = p["font-weight-normal"];
+  const colorMaps = ALL_TOKENS.map((t) => `  --color-${t}: var(--${t});`).join("\n");
+
+  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/general.md (frontend section) 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 */
+  /* 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);
+  --radius-md: calc(var(--radius) - 2px);
+  --radius-lg: var(--radius);
+  --radius-xl: calc(var(--radius) + 4px);
+
+  /* density remap — the single line that scales ALL library spacing. Every p-*/gap-*
+   * is calc(var(--spacing) × N); driving --spacing off --density-gap flows the 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-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)));
+
+  /* font weight — two-weight discipline: medium/semibold/bold all resolve to the
+   * single emphasis weight; operator UI carries no third weight. normal is emitted
+   * as a literal because its theme key and the primitive share a name (no self-ref). */
+  --font-weight-normal: ${fontWeightNormal};
+  --font-weight-medium: var(--font-weight-strong);
+  --font-weight-semibold: var(--font-weight-strong);
+  --font-weight-bold: var(--font-weight-strong);
+
+  /* tracking — heading tightness reaches the library's tracking-* utilities */
+  --tracking-tighter: var(--heading-tracking);
+  --tracking-tight: var(--heading-tracking);
+
+  /* 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. */
+  --font-sans: ${fontSans};
+  --font-mono: ${fontMono};
+
+  /* transitions */
+  --transition-fast: var(--duration-fast) var(--ease-default);
+  --transition-normal: var(--duration-normal) var(--ease-default);
+  --transition-slow: var(--duration-slow) var(--ease-default);
+  --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.
+   * --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"] *)); */
+`;
+}
+
+// Emit the index.html <html> attribute snippet the shell must carry.
+function emitIndexHtmlAttributes(doc, slug) {
+  const p = doc.primitives;
+  return `<!-- Personality state lives in these <html data-*> attributes — code is the cache.
+     There is no sidecar JSON. To change the look, edit the resolved design.md and
+     re-run derive-personality.mjs --emit; to nudge one axis, edit an attribute here. -->
+<html
+  lang="en"
+  data-style="${slug}"
+  data-density="${p["density-tier"]}"
+  data-verbosity="${p.verbosity}"
+  data-feedback="${p.feedback}"
+  data-theme="light"
+>
+`;
+}
+
+// Write a file, creating parent directories as needed.
+function writeFileEnsured(path, content) {
+  mkdirSync(dirname(path), { recursive: true });
+  writeFileSync(path, content);
+}
+
+// Print usage and exit non-zero.
+function usage() {
+  process.stderr.write("usage: derive-personality.mjs <design.md> [--check | --emit <outdir>]\n");
+  process.exit(2);
+}
+
+// Entry point: parse argv, run --check or --emit.
+function main() {
+  const argv = process.argv.slice(2);
+  let designPath = null;
+  let mode = "check";
+  let outdir = null;
+  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.startsWith("-") && designPath === null) designPath = a;
+    else usage();
+  }
+  if (!designPath) usage();
+  if (mode === "emit" && !outdir) usage();
+
+  let source;
+  try {
+    source = readFileSync(designPath, "utf8");
+  } catch {
+    process.stderr.write(`error: cannot read ${designPath}\n`);
+    process.exit(2);
+  }
+
+  const doc = parseDesignMd(source);
+  const { errors } = runCoverageGate(doc);
+  const slug = slugify(doc.frontmatter && doc.frontmatter.product);
+
+  if (errors.length > 0) {
+    process.stderr.write(`coverage gate FAILED (${designPath}): ${errors.length} issue(s)\n`);
+    for (const e of errors) process.stderr.write(`  - ${e}\n`);
+    process.exit(1);
+  }
+
+  if (mode === "check") {
+    const provenance = doc.frontmatter.provenance;
+    process.stdout.write(`coverage gate PASSED (${designPath}): 26 primitives, verbosity/feedback/density-tier, 34 color tokens, scales OK — provenance=${provenance}, style=${slug}\n`);
+    process.exit(0);
+  }
+
+  // --emit: refuse while any bare hint remains.
+  const hints = collectBareHints(doc);
+  if (hints.length > 0) {
+    process.stderr.write(`emit REFUSED (${designPath}): ${hints.length} unresolved hint(s) — resolve each to a concrete value before emission.\n`);
+    for (const h of hints) process.stderr.write(`  - ${h.key}: hint: ${h.text}\n`);
+    process.stderr.write("  Resolve with judgment and record the rationale: \"<key>: <value>   # derived: <rationale>\", then re-run --emit.\n");
+    process.exit(1);
+  }
+
+  const personalityCss = emitPersonalityCss(doc, slug);
+  const globalsCss = emitGlobalsCss(doc);
+  const htmlAttrs = emitIndexHtmlAttributes(doc, slug);
+  const personalityPath = join(outdir, "src/styles/personality.css");
+  const globalsPath = join(outdir, "src/styles/globals.css");
+  const attrsPath = join(outdir, "index-html-attributes.txt");
+  writeFileEnsured(personalityPath, personalityCss);
+  writeFileEnsured(globalsPath, globalsCss);
+  writeFileEnsured(attrsPath, htmlAttrs);
+
+  process.stdout.write(`emitted personality system for style=${slug} → ${outdir}\n`);
+  process.stdout.write(`  ${personalityPath}\n  ${globalsPath}\n  ${attrsPath}\n`);
+  process.exit(0);
+}
+
+main();