docs(design): standing design context — PRODUCT.md register + DESIGN.md ledger

.claude/rules/design_context.md

@@ -0,0 +1,38 @@
+# Design Context — read before generating
+
+Any change that touches user-visible UI (components, CSS, copy, motion,
+icons, layout) MUST read these two files FIRST and conform to them:
+
+1. `docs/design/PRODUCT.md` — register, users, voice, **anti-references**
+   (what NodeBench must never look like)
+2. `docs/design/DESIGN.md` — approved decisions ledger, each with its
+   enforcement; plus the Start→Iterate→Polish→Maintain loop mapped to this
+   repo's machinery
+
+Pattern: impeccable.style/designing — `init` writes PRODUCT.md/DESIGN.md and
+every later command reads both before generating. Ours adds teeth: a ledger
+entry must name its guard/contract/lint, and agent briefs for UI work must
+include both files in the agent's required reading.
+
+## Hard rules distilled (the ones agents break most)
+
+- Stroke-SVG icons only, `stroke="currentColor"` — never emoji (guard-tested)
+- Every new animation/transition gets a `prefers-reduced-motion: reduce` flatten
+- Prose leads; structure collapses; no memo furniture in conversation
+- Honest empty over fake full — no badge/score/state without computation
+- One accent (`--rd-accent` terracotta); motion settles once then rests
+- New design decisions land in DESIGN.md WITH their enforcement, or they are
+  not decisions
+
+## When delegating UI work to subagents
+
+Copy this into the brief: "Read docs/design/PRODUCT.md and
+docs/design/DESIGN.md first; conform to the anti-references; any new
+decision you make must be proposed as a DESIGN.md entry with enforcement."
+
+## Related
+
+- `reexamine_design_reduction` — earned complexity, kill jargon
+- `product_design_dogfood` — verify in the running UI
+- `.claude/rules/reference_attribution.md` — impeccable.style/designing is
+  the cited prior art for the standing-context pattern

docs/design/DESIGN.md

@@ -0,0 +1,41 @@
+# DESIGN.md — approved decisions ledger
+
+Standing context every design-touching agent reads BEFORE generating, after
+[PRODUCT.md](PRODUCT.md). Pattern: impeccable.style/designing ("approved
+decisions get written into DESIGN.md") — extended with our rule that every
+entry cites its ENFORCEMENT, because a decision without a guard is a wish.
+
+| Decision | Enforced by |
+|---|---|
+| Terracotta ember on near-black paper; `#d97757` accent via `--rd-accent`; Manrope display + JetBrains Mono data | `src/design/designSystem.ts` manifest + `npm run lint:design` |
+| One motion identity: `--rd-ease-settle` cubic-bezier(.22,1,.36,1), durations 240/480/840ms; enter once, drift subtly, rest | `agent-workspace.css` tokens; reduced-motion blocks per system |
+| The ember motif carries the product truth: landing threads → thinking thread → run theater → answer ticks | evidence folders `docs/design/ui-contract/2026*` |
+| `prefers-reduced-motion` flattens EVERY animated system to its static composition | CSS guards + emulated verification (animationName: none) |
+| Icons are stroke SVG (`stroke="currentColor"`), never emoji | `ChatResponseShape.guard.test.ts` emoji-block assertion |
+| The answer is chat-shaped: prose leads; Reasoning/Tool/Sources collapse into the message, closed by default | `docs/design/ONE_CHAT_INTERFACE.md`; ChatResponseShape + honesty guards |
+| ONE `ChatAssistantMessage` renders every completed answer (flagship, replay, panel) — renderer drift is structurally impossible | guard asserts both renderers import it; Phase B adapter fit-gate |
+| Honesty is a rendering rule: empty over faked (no badge without computed state, `telemetry not recorded`, `Source needed`), failures render as failures | `chatRuns.contract.test.ts` L3 schemas; `canonicalAnswer.ts` refusal reasons |
+| Compact shapes never re-inflate memo furniture | `computeIsCompactResponse` + guard-pinned gates |
+| Surface invariants (anchors, computed geometry, theme wiring, forced states) live in executable contracts, run per-PR + nightly | `ui-contract/surfaces/*.contract.json` + `ui-contract-runner.spec.ts` + `nightly-design-loop.yml` |
+| Every UI change ships with matched before/after captures | `docs/design/ui-contract/YYYYMMDD-<slice>/` + manifest schema |
+| Copy is calm + evidential; labels a non-technical reader parses in 2s | PRODUCT.md voice; `reexamine_design_reduction` rule |
+
+## The loop (impeccable's, mapped to our machinery)
+
+- **Start** — read PRODUCT.md + this file; for signature work, produce/pick a
+  hi-fi reference *before* CSS (code toward an image, not a paragraph).
+- **Iterate** — name the discipline: typeset / layout / colorize / animate;
+  `bolder` to bring a safe design to life, `quieter` to calm a shouting one;
+  `critique` = our screenshot nitpick pass.
+- **Polish (pre-ship gauntlet)** — audit = contract runner + guards;
+  clarify = copy pass tuned to PRODUCT.md users; harden = reduced-motion,
+  a11y, mobile geometry, theme parity.
+- **Maintain** — design debt is tracked like code debt: nightly captures,
+  dated evidence folders, decisions land HERE when approved — before the
+  debt solidifies.
+
+## Amending this ledger
+
+A new decision enters only with its enforcement named (guard, contract
+clause, lint, or scheduled capture). Aspirations without teeth go in a PR
+description, not here.

docs/design/PRODUCT.md

@@ -0,0 +1,46 @@
+# PRODUCT.md — the design register
+
+Standing context every design-touching agent reads BEFORE generating.
+Pattern: impeccable.style/designing (init → PRODUCT.md; every command reads it
+first). Companion: [DESIGN.md](DESIGN.md) — the approved-decisions ledger.
+
+## Register
+
+Evidence-first decision intelligence. **Design serves the receipt** — every
+pixel either helps a person trust a claim, trace a source, or take the next
+action. The product's soul is "answers with receipts"; the interface's job is
+to make honesty legible at a glance.
+
+## Users
+
+Founders, bankers, operators — reading fast, deciding under uncertainty,
+often between meetings, frequently on a phone. They forgive density; they do
+not forgive being lied to by a UI. A wrong confidence signal costs them real
+money.
+
+## Voice
+
+Calm, evidential, precise. Numbers over adjectives. States their limits out
+loud ("telemetry not recorded", "Source needed"). Never hypes, never
+apologizes decoratively, never says "powered by AI".
+
+## Anti-references (what NodeBench must NEVER look like)
+
+- **Emoji as interface icons** — color glyphs that ignore the theme. Stroke
+  SVG only. (Shipped twice, caught twice, guard-tested now.)
+- **Memo furniture in conversation** — labeled always-open sections
+  ("SHORT ANSWER") where prose should lead. The document costume is dead.
+- **Dashboard-of-widgets** — stat tiles that don't change a decision.
+- **Fake-data theater** — placeholder confidence, hardcoded scores, badges
+  without computation behind them. An honest empty beats a fake full.
+- **Generic-SaaS gradient wash** — purple/indigo hero gradients, glass blur
+  for its own sake, spinning decorations. Our warmth is terracotta ember on
+  near-black paper, earned by restraint.
+- **Shouting typography** — all-caps walls, oversized labels competing with
+  content. Eyebrows whisper; prose speaks.
+- **Hype copy in UI** — "revolutionary", "magical", exclamation points.
+
+## When in doubt
+
+Prefer: prose leads · structure collapses · honesty visible · one accent ·
+motion settles once then rests. The receipt is the aesthetic.