From 1b216785633cad77156b2e784b7a605dc96f6eed Mon Sep 17 00:00:00 2001 From: hshum Date: Sat, 18 Jul 2026 13:29:42 -0700 Subject: [PATCH] =?UTF-8?q?docs(design):=20standing=20design=20context=20?= =?UTF-8?q?=E2=80=94=20PRODUCT.md=20register=20+=20DESIGN.md=20ledger?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Adopts the impeccable.style/designing pattern (init writes PRODUCT.md + DESIGN.md; every design command reads both before generating), made agent-native: PRODUCT.md carries register/users/voice and — new for this repo — explicit ANTI-REFERENCES (emoji icons, memo furniture, fake-data theater, gradient wash, shouting type, hype copy); DESIGN.md is the approved-decisions ledger where every entry must name its enforcement (guard/contract/lint) — a decision without teeth is a wish. A rules file wires "read both first" into every future session and into subagent briefs, and maps their Start→Iterate→Polish→Maintain loop onto our existing machinery (contracts, guards, nitpick loop, nightly captures). Prior art cited per reference_attribution: impeccable.style/designing. Co-Authored-By: Claude Fable 5 --- .claude/rules/design_context.md | 38 +++++++++++++++++++++++++++ docs/design/DESIGN.md | 41 +++++++++++++++++++++++++++++ docs/design/PRODUCT.md | 46 +++++++++++++++++++++++++++++++++ 3 files changed, 125 insertions(+) create mode 100644 .claude/rules/design_context.md create mode 100644 docs/design/DESIGN.md create mode 100644 docs/design/PRODUCT.md diff --git a/.claude/rules/design_context.md b/.claude/rules/design_context.md new file mode 100644 index 000000000..42781eed1 --- /dev/null +++ b/.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 diff --git a/docs/design/DESIGN.md b/docs/design/DESIGN.md new file mode 100644 index 000000000..49f968522 --- /dev/null +++ b/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-/` + 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. diff --git a/docs/design/PRODUCT.md b/docs/design/PRODUCT.md new file mode 100644 index 000000000..02a5f4e7e --- /dev/null +++ b/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.