@nurix/etna 0.18.18 → 0.18.20

package/data/harnesses/code/skills/design/references/personality.md

@@ -0,0 +1,504 @@
+# Personality — the look pipeline
+
+`design.md → derivation → token emission`. One resolved `design.md` (its two machine blocks — see
+[SCHEMA.md](../data/design-md/SCHEMA.md)) becomes three emitted files that *are* the state: no sidecar
+cache, no JSON. `derive-personality.mjs` runs the pipeline: `--check` is the coverage gate that must
+pass before `--emit` writes `personality.css`, `globals.css`, and the `<html>` attributes in `index.html`.
+
+The look comes entirely from the cascade. A surface composes in semantic tokens (`bg-card`,
+`text-foreground`) and reads its personality from the CSS variables this file emits. Switch the resolved
+`design.md`, re-emit, and every surface re-skins with zero JSX edits — the invariant the exemplars are
+validated against.
+
+## 1. The pipeline
+
+```
+resolved design.md ──▶ derive-personality.mjs --check ──▶ (green) ──▶ --emit src/styles/
+   (design-primitives          coverage gate:                            personality.css
+    + lever-manifest)          every primitive, dial, token             globals.css
+                               assigned or hinted, or exit 1            index.html <html> attrs
+```
+
+`--check` never best-efforts (D6/D29): if any of the 26 primitives, 2 dials, density tier, or 34 color
+tokens is unassigned and un-hinted it exits non-zero naming the offending keys, and the `tokens` phase
+gate stays shut. Emission runs only over a document that passed.
+
+## 2. Derivation — design.md → primitives and tokens
+
+Hybrid: **deterministic wherever the document states a value; judgment-with-recorded-rationale for the
+gaps.** The `design-primitives` block already carries all 26 keys (names without the leading `--`) plus
+the dials, so the mapping is near 1:1.
+
+| design.md source | Emitted target | Rule |
+| --- | --- | --- |
+| the 24 static primitives (geometric · typographic · surface · iconography · layout · temporal) | `[data-style="<slug>"] { --<key>: <value> }` | 1:1 by name |
+| `density-gap`, `density-inset` | governed refs in `[data-style]`; base set by the tier | via the density mechanism (§7) |
+| `ease-enter`, `ease-exit`, `stagger-delay` (derived — *not* in the 26) | computed at emit | rules below |
+| `lever-manifest.color-tokens.light.<token>` (17 semantic + 17 substrate) | `:root, :root[data-theme="light"] { --<token>: <value> }` | 1:1 by name |
+| `verbosity` · `feedback` | `<html data-verbosity>` · `<html data-feedback>` | dial → attribute |
+| `density-tier` | `<html data-density>` → `[data-density]` base | tier → attribute |
+| `fonts.sans` / `fonts.mono` (equal `font-sans`/`font-mono`) | `@theme inline` font keys + the primitive | §4 |
+| `product-traits` | read by the front gate; **not** emitted to CSS | — |
+
+**Derived temporal** (SCHEMA: computed from `ease-default` and `duration-unit`, never authored, never
+gated):
+- `--ease-exit: var(--ease-default)` — departure mirrors the neutral curve.
+- `--ease-enter` → the emphasized-decelerate arrival curve `cubic-bezier(0.16, 1, 0.3, 1)` (fast in,
+  settles clean); reuse `ease-default` verbatim if it is already a decelerate curve.
+- `--stagger-delay` → `duration-unit × 0.15`, clamped `0–40ms`, emitted as a concrete ms; a snappier
+  tempo staggers less. (`50ms → 8ms`.)
+
+**Gaps → hint → write-back.** Where a value needs judgment the document carries a `hint:` line. A hint
+passes `--check` but not `--emit`: emission resolves each hint to a concrete value *and rewrites the line
+with its rationale* so the document stays self-explaining and re-derivable (`contrast-boost: 1.1  #
+derived: dense-grid brief → one step up (was hint)`). Judgment is recorded into the `design.md`, never
+silent — the full convention is [SCHEMA.md](../data/design-md/SCHEMA.md) §"hint convention". After
+resolution no bare `hint:` remains.
+
+## 3. `src/styles/personality.css`
+
+The token system. The header comment carries the resolved personality — this comment *is* the cache
+record. Values below are one project's (`meridian`, the SCHEMA worked example); the shape is invariant.
+
+```css
+/* 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:     meridian   (<html data-style="meridian">)   — the project's own personality (rosterless)
+ *   density:   dense       (<html data-density="dense">)
+ *   verbosity: default     (<html data-verbosity="default">)
+ *   feedback:  subtle       (<html data-feedback="subtle">)
+ *   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="meridian"] 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 (§6): 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) */
+  --background: #ffffff;
+  --foreground: #0f172a;
+  --card: #ffffff;
+  --card-foreground: #0f172a;
+  --muted: #f1f5f9;
+  --muted-foreground: #64748b;
+  --border: #e2e8f0;
+  --input: #e2e8f0;
+  --ring: #6366f1;
+  --primary: #4f46e5;
+  --primary-foreground: #ffffff;
+  --accent: #eef2ff;
+  --accent-foreground: #4f46e5;
+  --destructive: #dc2626;
+  --destructive-foreground: #ffffff;
+  --success: #16a34a;
+  --warning: #d97706;
+  /* substrate (17, the D6 set) — popover/secondary/chart/sidebar the library consumes */
+  --popover: #ffffff;
+  --popover-foreground: #0f172a;
+  --secondary: #f1f5f9;
+  --secondary-foreground: #0f172a;
+  --chart-1: #4f46e5;
+  --chart-2: #0ea5e9;
+  --chart-3: #16a34a;
+  --chart-4: #d97706;
+  --chart-5: #dc2626;
+  --sidebar: #f8fafc;
+  --sidebar-foreground: #0f172a;
+  --sidebar-primary: #4f46e5;
+  --sidebar-primary-foreground: #ffffff;
+  --sidebar-accent: #eef2ff;
+  --sidebar-accent-foreground: #4f46e5;
+  --sidebar-border: #e2e8f0;
+  --sidebar-ring: #6366f1;
+}
+
+/* ── 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 (§7),
+ * so the global tier and per-surface step still compose. */
+[data-style="meridian"] {
+  --radius: 6px;
+  --shadow-intensity: 0.5;
+  --border-weight: 1px;
+  --density-gap: var(--density-base-gap);
+  --density-inset: var(--density-base-inset);
+  --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;
+  --duration-unit: 50ms;
+  --duration-fast: 100ms;
+  --duration-normal: 150ms;
+  --duration-slow: 250ms;
+  --ease-default: cubic-bezier(0.4, 0, 0.2, 1);
+  --ease-enter: cubic-bezier(0.16, 1, 0.3, 1);   /* derived from ease-default */
+  --ease-exit: var(--ease-default);              /* derived: departure mirrors the neutral curve */
+  --stagger-delay: 8ms;                          /* derived: duration-unit × 0.15, clamped 0–40ms */
+  --contrast-boost: 1;
+  --icon-stroke: 1.75;
+  --icon-size-base: 16px;
+  --sidebar-width-expanded: 248px;
+  --sidebar-width-collapsed: 56px;
+  --topbar-height: 52px;
+  --side-panel-width: 420px;
+  --side-panel-width-rich: 640px;
+  --modal-width-max: 560px;
+  --form-max-width: 640px;
+  --table-row-height: 40px;
+}
+
+/* ── 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. See §7. */
+[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 (a log-stream runs tighter than a settings form inside the same
+ * app). 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 (§4). */
+[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: #0f172a; --foreground: #f8fafc; ... 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;
+  }
+}
+```
+
+## 4. `src/styles/globals.css`
+
+Wires personality into Tailwind v4. `main.tsx` imports this one file. The `@theme inline` keyword inlines
+each value into the generated utilities (so `bg-card` compiles to `background-color: var(--card)` and
+`--font-sans: var(--font-sans)` is *not* a circular `:root` write — it inlines into `.font-sans`).
+
+```css
+/* src/styles/globals.css — Tailwind v4 glue + @theme inline mappings (emitted). */
+
+/* CASCADE CONTRACT 2 (§6): 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 (§7) 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: 400;
+  --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: "Inter", system-ui, sans-serif;
+  --font-mono: "JetBrains Mono", ui-monospace, monospace;
+
+  /* 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. */
+  --color-background: var(--background);
+  --color-foreground: var(--foreground);
+  --color-card: var(--card);
+  --color-card-foreground: var(--card-foreground);
+  --color-muted: var(--muted);
+  --color-muted-foreground: var(--muted-foreground);
+  --color-border: var(--border);
+  --color-input: var(--input);
+  --color-ring: var(--ring);
+  --color-primary: var(--primary);
+  --color-primary-foreground: var(--primary-foreground);
+  --color-accent: var(--accent);
+  --color-accent-foreground: var(--accent-foreground);
+  --color-destructive: var(--destructive);
+  --color-destructive-foreground: var(--destructive-foreground);
+  --color-success: var(--success);
+  --color-warning: var(--warning);
+  --color-popover: var(--popover);
+  --color-popover-foreground: var(--popover-foreground);
+  --color-secondary: var(--secondary);
+  --color-secondary-foreground: var(--secondary-foreground);
+  --color-chart-1: var(--chart-1);
+  --color-chart-2: var(--chart-2);
+  --color-chart-3: var(--chart-3);
+  --color-chart-4: var(--chart-4);
+  --color-chart-5: var(--chart-5);
+  --color-sidebar: var(--sidebar);
+  --color-sidebar-foreground: var(--sidebar-foreground);
+  --color-sidebar-primary: var(--sidebar-primary);
+  --color-sidebar-primary-foreground: var(--sidebar-primary-foreground);
+  --color-sidebar-accent: var(--sidebar-accent);
+  --color-sidebar-accent-foreground: var(--sidebar-accent-foreground);
+  --color-sidebar-border: var(--sidebar-border);
+  --color-sidebar-ring: var(--sidebar-ring);
+}
+
+/* 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"] *)); */
+```
+
+## 5. `index.html`
+
+Vite entry (no `layout.tsx`). The `<html>` attributes carry the personality state; the HTML comment is
+the cache record.
+
+```html
+<!-- 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="meridian"
+  data-density="dense"
+  data-verbosity="default"
+  data-feedback="subtle"
+  data-theme="light"
+>
+  <head>
+    <meta charset="UTF-8" />
+    <meta name="viewport" content="width=device-width, initial-scale=1.0" />
+    <title>Meridian</title>
+  </head>
+  <body>
+    <div id="root"></div>
+    <script type="module" src="/src/main.tsx"></script>
+  </body>
+</html>
+```
+
+## 6. The two cascade contracts and their failure modes
+
+Both are hardened with the in-CSS comments above and enforced by the code-and-token rules (`cod-*`) in
+[hard-rules.md](./hard-rules.md); the `scaffold` and `tokens` phase gates check them.
+
+**Contract 1 — the specificity/attribute pair.** Semantic + substrate tokens sit under
+`:root, :root[data-theme="light"]` **and** `<html>` carries `data-theme="light"`.
+*Failure mode:* a bare `:root { --background: … }` is specificity `(0,1,0)` — the library's own
+`:root { --background: … }` in `styles.css` is also `(0,1,0)` and imported *later*, so it wins and every
+surface silently reverts to shadcn gray. The `:root[data-theme="light"]` arm is `(0,2,0)` and out-wins —
+but only if `data-theme="light"` is actually on `<html>`; drop the attribute and the arm never matches,
+leaving only the losing bare `:root`. Both halves are load-bearing together.
+
+**Contract 2 — the import order.** `personality.css → tailwindcss → @nurix/components/styles.css →
+@theme inline`. *Failure mode:* put `@theme inline` (or the whole consumer theme) *before* the library
+import and the library's own `@theme` radius scale (`--radius-lg: var(--radius)`, its own offsets) comes
+later and wins — the personality `--radius` stops driving the scale and archetype radius switching breaks.
+The consumer `@theme` must come last. `rules/general.md` (frontend section) states this same order — it is
+co-authority, not a restatement to drift from.
+
+## 7. Density — global tier composed with a per-archetype relative step (D31)
+
+Two composed levels, pure cascade, no JS:
+
+1. **Global tier** — `density-tier` (spacious | standard | dense) from the `design.md` emits
+   `data-density` on `<html>`. `[data-density="…"]` writes only the **base** multipliers
+   (`--density-base-gap/inset`); `--density-gap/inset` resolve *from* the base. Switching the tier
+   re-tiers the whole surface coherently.
+2. **Per-archetype step** — a surface carries `data-density-step="tighter"|"looser"` (from its
+   surface-catalog `density-modifier`, [surface-catalog.md](../data/operator-pack/surface-catalog.md)),
+   emitted by `scaffold.mjs` onto the surface root. It re-derives `--density-gap/inset` as
+   `calc(base × 0.85|1.15)` — a **relative** step off whatever tier the app runs, reading
+   `--density-base-*` (never itself, so no circular reference and never an absolute override). A
+   log-stream inside a `standard` app resolves one step denser without pinning an absolute value.
+
+Both feed the library through `--spacing: calc(0.25rem * var(--density-gap))` in `@theme`: every library
+`p-*`/`gap-*` is `calc(var(--spacing) × N)`, and `--density-gap` resolves per element (respecting a
+`data-density-step` ancestor), so the tier and the step both reach the library's internal spacing. This
+composes *with*, never replaces, the behavioral dials (D4) — density is spatial chrome; verbosity/feedback
+are behavior.
+
+## 8. Dial wiring and the lifecycle
+
+`data-verbosity` and `data-feedback` set behavioral variables the lifecycle and interaction layers read:
+
+- `--label-display` / `--helper-text-display` — `compact`/`expert` verbosity collapse form labels and
+  helper text; `full`/`default` keep them. Field chrome reads these, not a JS branch.
+- `--tooltip-delay` — tightens with verbosity (`800ms → 0ms`).
+- `--feedback-press-scale`, `--focus-ring-width`, `--focus-ring-offset` — `minimal` feedback flattens the
+  press and thins the focus ring; `subtle` keeps the operator-default ring.
+
+The lifecycle pattern ([lifecycle.md](./lifecycle.md)) consumes the dials directly: empty-state richness
+scales with verbosity (`full` gets the acknowledge-value-action triad, `expert` gets one bare line);
+confirmation depth rides feedback. Focus and overlay discipline read the feedback ring variables
+([interaction.md](./interaction.md)). Components that must branch structurally on a dial read the `<html>`
+attribute — they never duplicate the state.
+
+## 9. Sidebar width via the SidebarProvider style prop
+
+The library hardcodes `--sidebar-width` / `--sidebar-width-icon` as inline styles, overridable only via the
+provider's `style` prop. The shell wires the personality primitives in:
+
+```tsx
+<SidebarProvider
+  style={{
+    "--sidebar-width": "var(--sidebar-width-expanded)",
+    "--sidebar-width-icon": "var(--sidebar-width-collapsed)",
+  } as React.CSSProperties}
+>
+```
+
+This is the one layout primitive that cannot reach the library through `@theme` — the style prop is the
+supported seam.
+
+## 10. Coverage checklist — every token the library consumes is emitted
+
+Enumerated against [the substrate audit](../../../docs/brainstorm/design/u1-audit-report.md). Emission
+sets each; none falls back to a shadcn-gray default (D6).
+
+| Library consumes | How | Emitted at |
+| --- | --- | --- |
+| `--radius` (283 `rounded-*`) | direct primitive + `@theme` radius scale | `[data-style]` · `@theme` |
+| shadow (`shadow-xs/sm/md/lg`, 58) | `--shadow-*` alpha rides `--shadow-intensity` | `@theme` |
+| font weight (`font-medium/semibold/bold/normal`, 139) | two-weight map to `--font-weight-strong` | `@theme` |
+| tracking (`tracking-*`, 13) | `--tracking-tight/tighter → --heading-tracking` | `@theme` |
+| spacing (all `p-*`/`gap-*`) | `--spacing` density remap | `@theme` |
+| `font-mono` (9) / `font-sans` | inlined font keys | `@theme` |
+| 15 semantic colors (888 uses) | direct token values | `:root[data-theme=light]` |
+| `--success`, `--warning` | direct token values (library ignores today — §11) | `:root[data-theme=light]` |
+| `--destructive-foreground` (unmapped by library) | explicit `--color-destructive-foreground` map | `@theme` |
+| 17 substrate (`popover`/`secondary`/`chart-1..5`/`sidebar` family) | direct token values | `:root[data-theme=light]` |
+| `--sidebar-width` / `--sidebar-width-icon` | SidebarProvider `style` prop | shell (§9) |
+
+## 11. Upstream gaps — expected, never worked around
+
+Some values live in `@nurix/components` JS, not CSS, so they do not follow tokens until the library adopts
+them. This is expected, filed as user-owned upstream work (D6) — **never** patched with brittle per-instance
+overrides:
+
+- **Chart palettes** — the d3 family (`bar-graph`, `line-graph`, `pie-graph`, `sparkline`, …) hardcodes
+  oklch/hex and ignores `--chart-1..5`. Color props are per-instance overridable, but the defaults are
+  upstream. Emit `--chart-1..5` regardless, so adoption is a drop-in.
+- **Status literals** — `changes-list` and `statistics` hardcode emerald/amber/sky rather than
+  `--success`/`--warning`. Upstream token adoption is the fix.
+- **Motion & icon stroke** — `duration: .2/.3` and `strokeWidth: 2/1.75` are JS numbers; `--duration-*`
+  and `--icon-stroke` reach consumer-emitted markup but not library internals.
+- **Filled-control foreground** — `text-white` pinned on filled primary/destructive; the mapped
+  `--destructive-foreground` waits on the library reading it.
+
+The stance: emit the complete token surface now so the library "just works" the moment it adopts each token;
+do not build an override layer that fights the library and rots.

package/data/harnesses/code/skills/design/references/structure.md

@@ -0,0 +1,138 @@
+# Structure derivation
+
+The second create phase. Runs after intake, before scaffold. Two steps, in order: the **object pass**, then **archetype assignment**. The output is one small, durable file — `docs/design/structure.md` — that every later phase reads and `scaffold.mjs` consumes.
+
+The pass is never skipped. A small brief earns a proportionally small pass — a two-entity brief gets a two-entity map — but it always runs. Skipping straight to layout is the characteristic structural failure: screens that look plausible and model the domain wrongly. The structure phase gate requires a populated map before scaffold opens; an empty pass fails it.
+
+## The object pass
+
+Extract the domain model from the brief. Record, per the map schema below:
+
+- **Entities** — the nouns the operator works with (Ticket, Customer, Agent, Device). Extract what the brief and its domain support; do not fabricate entities the domain lacks, and do not promote an attribute to an entity.
+- **Attributes** — the fields each entity carries.
+- **Relationships and cardinalities** — how entities connect, recorded as `{to, cardinality}` (`one-to-one`, `one-to-many`, `many-to-one`, `many-to-many`).
+- **Lifecycle states** — the ordered states an entity moves through (new → open → pending → resolved → closed). Omit for stateless entities.
+- **Unit of work** — the one entity the operator's day turns on (the ticket, the case, the job). It anchors the home surface.
+- **Core loop** — the verb sequence the operator runs on the unit of work (triage → assign → work → resolve → close).
+
+Two modeling traps, both fatal to structure:
+
+- **Metrics are not entities.** CAC, open-ticket-count, and p95-latency are instances of one Metric object, not entity rows. They render on a dashboard; they never earn their own list surface.
+- **One entity, one home.** An entity's data and actions gather on one surface, cross-linked from everywhere else — never scattered across screens.
+
+## The temporal probe
+
+Runs inside the object pass — temporal semantics are model facts, not styling facts, and the brief states none of them. Probe five questions:
+
+- **Intermediate states** — does an action pass through pending / saving / processing / awaiting-approval before its terminal state?
+- **Read-model lag** — is there delay between write and read visibility? Where yes, staleness is marked honestly downstream.
+- **Deletion semantics** — archive, trash, hard delete, or regulatory retention? Each is a different surface and a different affordance.
+- **History** — is prior state auditable or required? Its answer surfaces as a model fact — a History/audit entity, a timeline, or a versioned attribute.
+- **Failure paths** — validation, server error, disconnection, concurrent edit.
+
+Four answers land in the map's `temporal` block (`intermediate-states`, `read-model-lag`, `deletion`, `failure-paths`); history's answer lands wherever the model puts it (an entity, an attribute, a surface). The probe is what makes the lifecycle phase's states bindable — the tool spends most of its life in states the brief never mentions.
+
+## Archetype assignment
+
+Each entity and workflow claims surfaces from the closed six-archetype catalog. `data/operator-pack/surface-catalog.md` is canonical for the choosing rules, the per-archetype density modifier, and the exemplar pointer; the assignment reads them. Orientation:
+
+| archetype | claimed when |
+| --- | --- |
+| `list-detail` | a high-cardinality collection worked one item at a time — the unit of work's home |
+| `dashboard` | a read-first overview answering a few standing questions across entities (Metric instances) |
+| `entity-detail` | one rich entity's attributes, relationships, and actions gathered on a single surface |
+| `create-edit` | minting or editing one entity — a stepper that mirrors edit; templates prefill |
+| `log-stream` | append-only, high-volume, time-ordered events — read and filter, rarely edit |
+| `command-center` | a live multi-pane monitor over several entities at once, with drill-down |
+
+Membership is closed. New archetypes enter only as pack data, ledger-recorded — never invented per run.
+
+**Navigation derives from the object model, never decorated on.** Top-level nav entries are the primary entities and their home surfaces; secondary entities are reached through their parent's detail surface, not promoted. The unit of work is the home. Cap top-level entries at what stays countable on one hand — nav categories the model does not carry are a structural defect, not a convenience.
+
+## The map: `docs/design/structure.md`
+
+The derivation's whole output. Human prose above the block; the fenced `yaml structure` block is the machine contract — `scaffold.mjs` reads it, so the field names are law. Scaffold generates routes, navigation wiring, and per-surface state-shell stubs from `surfaces[]`, and keys fixture wiring off `entities[]`.
+
+```yaml structure
+unit-of-work: <entity>
+core-loop: <verb → verb → verb>
+entities:
+  - name: <Entity>
+    attributes: [<field>, ...]
+    lifecycle: [<state>, ...]        # omit for stateless entities
+    relationships:
+      - { to: <Entity>, cardinality: one-to-one | one-to-many | many-to-one | many-to-many }
+temporal:
+  intermediate-states: [<state>, ...]
+  read-model-lag: <none | description>
+  deletion: <archive | trash | hard | retained>
+  failure-paths: [validation, server-error, disconnection, concurrent-edit, ...]
+surfaces:
+  - name: <Surface>
+    archetype: list-detail | dashboard | entity-detail | create-edit | log-stream | command-center
+    route: /<path>
+    entity: <Entity>
+    density-modifier: <integer step; positive = denser; mirrors the catalog's per-archetype modifier>
+    states: [loading, empty, error, partial]   # applicable subset; data surfaces carry all four
+```
+
+## OOUX structural diagnostics
+
+Four judged diagnostics for a wrong object model (after Sophia Prater's OOUX vocabulary). Run them over the map and over any UI under review; each is a one-line detection question:
+
+- **Shapeshifter** — is one entity rendered inconsistently across surfaces? (Does a Ticket's status pill look different in the queue than in the detail?)
+- **Masked** — is an entity hidden inside another's UI, with no surface of its own? (Is Customer only ever a string on a Ticket, never its own object?)
+- **Broken** — is an entity's data or actions split across surfaces with no complete home? (Are a Device's config and its telemetry on two unrelated screens?)
+- **Isolated** — is an entity unreachable from the navigation and from its relationships? (Can the operator reach an Agent from anywhere?)
+
+These are judgment, not machine rules — no waiver, no score. A finding is raised, ranked, and fixed at the model layer, never patched at the surface.
+
+## Worked example — a ticket queue
+
+Brief: *"A support ticket queue. Agents triage incoming tickets, assign them, work them to resolution, and close them. Tickets come from customers."*
+
+```yaml structure
+unit-of-work: Ticket
+core-loop: triage → assign → work → resolve → close
+entities:
+  - name: Ticket
+    attributes: [subject, body, status, priority, channel, requester, assignee, created_at, updated_at]
+    lifecycle: [new, open, pending, resolved, closed]
+    relationships:
+      - { to: Customer, cardinality: many-to-one }
+      - { to: Agent, cardinality: many-to-one }
+  - name: Customer
+    attributes: [name, email, org]
+    relationships:
+      - { to: Ticket, cardinality: one-to-many }
+  - name: Agent
+    attributes: [name, email, role, availability]
+    relationships:
+      - { to: Ticket, cardinality: one-to-many }
+temporal:
+  intermediate-states: [assigning, saving-reply, pending-customer]
+  read-model-lag: none            # single-writer per ticket
+  deletion: archive               # tickets are retained for audit, never hard-deleted
+  failure-paths: [validation, server-error, disconnection, concurrent-edit]
+surfaces:
+  - name: Ticket Queue
+    archetype: list-detail
+    route: /tickets
+    entity: Ticket
+    density-modifier: 1
+    states: [loading, empty, error, partial]
+  - name: Ticket Detail
+    archetype: entity-detail
+    route: /tickets/:id
+    entity: Ticket
+    density-modifier: 0
+    states: [loading, empty, error, partial]
+  - name: New Ticket
+    archetype: create-edit
+    route: /tickets/new
+    entity: Ticket
+    density-modifier: -1
+    states: [loading, error]
+```
+
+Navigation: top-level is **Tickets** — the unit of work's home. Customer and Agent are reached through Ticket Detail, not promoted to top-level nav (derived, not decorated). History — the audit of status changes and replies — surfaces as a timeline on the detail, not a fifth temporal key. OOUX pass: the status pill renders identically on queue and detail (no Shapeshifter), and Customer links out to its own detail rather than living only as a string (no Masked).