docs(product): commit design references under docs/product/reference/

Copy the founder's design handoff bundle (.proto/design/) into
docs/product/reference/ byte-for-byte so dispatch agents running in git
worktrees can read the HTML prototypes, veect-codebase/ prototype,
upload PNGs, and remaining bundle files (ADR-029: reference only, never
vendored into packages/). Ignore-list entries so whole-codebase auditors
and formatters skip reference material: .prettierignore (byte
preservation through lint-staged), .fallowrc.json ignorePatterns, root
ESLint ignores, and the coverage:diff allowlist in
scripts/coverage/diff.mjs (+ unit test). .DS_Store files skipped.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_016j8z4VHjedXDTjEDNg7qHK

docs/product/reference/project/uploads/design-brief-weave.md

@@ -0,0 +1,274 @@
+# Design Brief — "Weave" (working name) · v2
+
+_A hand-off for a design agent / designer. Founder OS · Phase 6._
+_Companion docs: `company-context.md` (strategy) · `design-app-prd.md` (MVP scope)._
+_v2 changes: folded in an adversarial design review (fixed art-direction contradictions, added missing screens/states, spec'd the AI interaction) **and integrated Impeccable** (impeccable.style) as Weave's craft standard._
+_Confidence: 🟢 verified · 🟡 reasoned · 🔴 assumption to validate._
+
+---
+
+## 0. On Impeccable (how it shows up in this brief)
+
+**Impeccable** (impeccable.style, by Paul Bakaus — open-source) is a *design language / "skill" for AI harnesses* (Claude Code, Cursor) whose entire purpose is to **stop AI-generated UIs from looking like AI** — to replace generic "slop" with real craft. 🟢 It's structured as a design language (rules) plus sub-skills for **building, "polishing" (critiquing + fixing), and teaching** good design. 🟡
+
+It matters to Weave **twice**, and both are load-bearing:
+1. **As Weave's own craft standard** — the UI you design from this brief must itself be Impeccable-grade (see §11.5 Craft Standard + the checklist in §20). Weave dogfoods the rules it sells.
+2. **As a product capability** — Weave doesn't just constrain output to the user's *system*; it holds output to a *craft standard* (an Impeccable-style ruleset) via a **Polish** pass, so results are **on-brand AND high-craft**. See PRD F9/F10. This is the deepening of the wedge: not just "your components," but "your components, arranged well."
+
+> ⚠️ **Fidelity note:** I could not fetch Impeccable's verbatim `DESIGN.md` this session (fetch was rate-limited). The craft rules in §11.5/§20 reflect Impeccable's documented anti-slop philosophy plus established craft; treat exact numeric values as 🟡/🔴 and reconcile them against the real Impeccable ruleset (or install the Impeccable skill) before locking. Sources listed at the end.
+
+## 1. Header / how-to
+
+- **Product:** Weave (working name — not final 🔴).
+- **One-liner:** A design-system-native canvas that turns your own tokens and components into real, production-ready React — held to a craft standard so it never looks generic.
+- **Surfaces:** Desktop web app (primary). Read-only shared preview link (any device) — *fast-follow, not MVP* (see PRD). No native mobile app.
+- **Who it's for:** Product/UI designers and design-engineer / design-system leads at startups & scale-ups that already have a design system and ship a React web product.
+- **How to use this brief:** §3–§7 = point of view + experience; §8–§9 = build map (IA + screens + states); §10–§14 + §20 = the craft bar. Recommendations are decisive defaults you may improve on, not pixel law. Everything 🔴 must be validated (see §19).
+
+## 2. Product snapshot
+
+- **What it is:** A visual canvas where a designer composes screens from **their own** components and tokens, gets **real React + Tailwind** out, and where a **craft layer (Impeccable)** keeps the result high-quality.
+- **The wedge:** v0 / Lovable / Bolt / Figma Make generate *generic* UI and throw your design system away. Weave makes your design system the **source of truth** and constrains everything — including AI — to it, **then polishes to a craft standard**.
+- **Emotional promise:** *"My design system is alive, what I make is what ships — and it looks like we hired a great designer, not an AI."* Relief, trust, quiet pride.
+
+## 3. Design north star
+
+> **Every screen must make the designer trust that what they see is exactly what will ship — built from their own system, arranged with real craft, with nothing lost in translation.**
+
+If a screen introduces doubt ("is this the real component? will the code match? is this on-brand? does this look generic?"), it has failed. **Trust is the product; craft is how trust is earned.**
+
+## 4. Design principles (opinionated, product-specific)
+
+1. **Your system is the hero; our chrome is stagehand.** Weave's UI is deliberately quiet, near-monochrome, recessive — a matte camera body around a bright photograph — so the user's brand dominates. *Why: the #1 complaint about competitors is off-brand output; our UI must never visually compete with the user's brand.*
+2. **Real, never represented.** The canvas renders the actual coded component at actual fidelity; preview = the same runtime as export. *Why: "roughly how it'll look" is the lie that makes handoff lossy.*
+3. **Show the code — trust is earned in the open.** Real code is a keystroke away, not a buried export; clean code that imports *their* components converts skeptics. *Why: designers have been burned by screenshot-to-code; visible honest code is the proof.*
+4. **AI proposes in your language; the system disposes.** AI output is always in the user's components/tokens, always shows provenance, always reversible; when it can't map, it *says so* — it never falls open to generic markup. *Why: constrained-to-your-system is the entire differentiator.*
+5. **Craft is not optional — Impeccable-grade or it doesn't ship.** Every surface (ours and the user's output) meets the craft checklist in §20: real type hierarchy, strict spacing, purposeful color, optical alignment, designed empty/error states. Generic is a bug. *Why: "on-brand but sloppy" still loses; the whole promise is that the output is genuinely good.*
+6. **Flow is a latency budget, not a slogan.** The core loop is keyboard-first and sub-frame (<16ms). *Match Figma's canvas responsiveness or don't ship the canvas.* *Why: designers forgive missing features, never lag in the core loop.*
+7. **Honest about fidelity.** Where something is prototype vs. production-ready, the UI says so plainly; never over-promise "shippable." *Why: over-claiming code quality loses the engineer — and the engineer is the veto.*
+
+## 5. Users & context (personas condensed *for design*)
+
+| | **Maya — Product Designer (primary)** | **Devon — Design-Systems / Design-Engineer Lead (champion + gatekeeper)** |
+|---|---|---|
+| Device/env | 27–32" display, macOS, Figma muscle memory, headphones-in flow | Dual monitor, VS Code + Figma, **reads the generated code** |
+| Emotional state | Impatient with handoff, burned by generic AI output, protective of brand | Skeptical of design-to-code claims, allergic to messy code |
+| Proficiency | Expert in design tools; reads code, writes little | Fluent React/Tailwind; owns the component library + the repo veto |
+| Accessibility | Long sessions → dark mode, low glare; keyboard-heavy | Scrutinizes output a11y/contrast |
+| Artifact they hold | Brand/visual decisions; often **no clean token file** (it's in Figma or the repo) | The **real coded components + tokens** (Tailwind config / repo) |
+| What wins them | On-brand, high-craft result in minutes, no relearning | Code that imports *their* components and passes review |
+
+> Design implication (from review): **Maya frequently does not own a DTCG/Tailwind file** — it's Devon's. Onboarding must not dead-end on "upload your tokens." See §9.2 no-file path.
+
+## 6. JTBD → top tasks
+
+| Job | Concrete tasks the UI must make effortless |
+|---|---|
+| Design finished → build matches without policing pixels → stop redlining | Compose from real components; see live code; export exact |
+| System changes → design & code stay in lockstep → "the library" means one thing | Re-import changed tokens; see impact/diff; apply safely |
+| Need a screen → ship it myself → move at idea-speed | Prompt or drag; export runnable code |
+| Using AI → build from *my* system → on-brand, not throwaway | Constrained AI compose with provenance; graceful "can't map" |
+| Result looks generic → make it genuinely good → look designed, not AI | One-click **Polish** to the craft standard |
+
+## 7. Core user journeys (name the "aha")
+
+**A. Onboarding → first value (target <20 min).**
+Sign in → **Bring your system**: (a) connect a Tailwind config / paste CSS variables, or (b) **no file? set 5 core tokens over the base kit** (brand, neutral, radius, font, spacing) → *base kit re-themes to their brand* → drop into a starter frame → prompt or drag a first section → **Polish** → open code → **export / copy**. **The aha: "these are *my* components now, arranged well, and the code is real."**
+
+**B. The core loop (daily).**
+Open project → compose/adjust on canvas (drag, props, tokens) ⇄ glance at live code ⇄ AI compose a section ⇄ **Polish** ⇄ export. Tight, keyboard-first, low-latency — *sketching that happens to produce production code*.
+
+**C. Habit / expansion.**
+Map/save components → reuse across screens/projects → **re-import updated tokens** (System update, §9.8) → (fast-follow) share read-only prototypes; (v2) sync to repo. The user's mapped library + saved patterns is the retention flywheel.
+
+## 8. Information architecture
+
+**Surfaces:** (1) Home/Projects · (2) Editor · (3) Preview (full-screen + fast-follow shared link) · (4) **Settings** (system, mappings, account).
+
+**Editor layout (persistent 3-pane + dual companion):**
+```
+Top bar:  Project ▾ · breakpoint [Desktop] · ⟳ Preview · ✧ Polish · </> Code · ⇪ Export · avatar
+Left rail:  Pages/Layers · Component Library · Tokens        (switchable)
+Center:     Canvas (frames, direct manipulation)  +  ✦ AI compose bar (docked bottom)
+Right rail: Inspector (props · tokens · layout for selection)
+Companion:  Code panel (right split / bottom drawer, toggle </>)  ·  Polish panel (✧, right)
+```
+**Two command surfaces, reconciled (review fix):** **⌘K = commands/navigation** (find, jump, run action); **✦ AI bar = generative** (compose/modify from your system). Typing `✦` inside ⌘K routes to the AI bar. Never two overlapping "type here to make UI" fields.
+
+**Screen map:** Home → Editor → {Component editor (focused), Token manager, **System update / re-import**, Polish, Preview, Code/Export, Settings}.
+
+## 9. Key screens (purpose · primary user · key elements · **all states**)
+
+### 9.1 Home / Projects
+- **Purpose:** get into work fast; hold projects + systems. **Elements:** project grid (live real-render thumbnails), New project, Bring a design system, recent, search.
+- **States:** **Empty** → warm single-CTA "Bring your design system to life" + 20-sec inline demo loop. **Loading** → skeletons matching grid rhythm. **Error** → inline retry. **Populated** → real-render thumbnails.
+
+### 9.2 Onboarding — Bring your system
+- **Purpose:** turn tokens/fonts/assets into a live, themed, craft-checked kit. **Elements:** connect Tailwind config / paste CSS vars / **Figma Variables** (if available) — **or the no-file path: set 5 core tokens** (brand, neutral ramp, radius, font, base spacing); font upload; asset upload; live re-theme preview; **token contrast check**.
+- **States:** **Initial** → inviting, two clear paths (file vs. no-file), example link. **Parsing** → per-token progress; kit tinting in. **Partial/invalid** → line-referenced human error ("We couldn't read `colors.brand` — map it?") + manual mapping; **never a hard stop**. **No-file** → 5-token quick form with live preview. **Success** → the **re-theme reveal** (Signature Moment #1) + "Your system is live."
+
+### 9.3 Editor / Canvas (the product)
+- **Purpose:** compose from real components; the home of flow. **Elements:** frames, drag-drop, auto-layout stacks (direction/gap/padding = tokens), multi-select, snap/align guides, undo/redo, ⌘K, ✦ AI bar, ✧ Polish.
+- **States:** **Empty frame** → ghost placeholder + hint ("Drag a component, or ✦ describe this screen"). **Selection** → inspector + guides. **Dragging** → snap lines, live auto-layout reflow. **AI proposing** → staged **ghost layer** of *real* components (see §10.6), provenance chips streaming in. **Polish running** → non-blocking scan with issue markers. **AI can't map** → inline first-class prompt (Signature Moment #6), not a dead error. **Save states (review fix):** autosave tick · **saving** · **offline (read-only banner)** · **reconnecting** · **conflict (two tabs)** resolution. **Latency guard:** all direct manipulation <16ms/frame.
+
+### 9.4 Component Library (manage · map · define) — *fully specified (was the weakest section)*
+- **Purpose:** the user's system as objects; **map** base-kit → their real coded components, and define reusable patterns. This is the retention flywheel and the wedge-critical mapping surface.
+- **Elements:**
+  - **Library list:** base kit · **mapped** components (linked to the team's real import path + prop names) · user-saved patterns; each shows usage count + a **mapping status** (mapped / unmapped / drifted).
+  - **Component detail:** a **variant matrix** (variant × state) with a **live state grid** (default / hover / focus / active / disabled / loading) rendered from the real runtime; a **token-binding panel** (which token drives which property); **prop editor**.
+  - **Mapping panel (wedge-critical):** map "Weave Button" → `@/components/ui/Button`, map props (`variant→kind`, etc.); preview the exact import the export will emit.
+  - **New component from selection** (save a composed pattern).
+- **States:** **Empty (user)** → "You've got the base kit — map it to your real components, or save your first pattern." **Mapping** → guided prop-matching with live code preview. **Editing variant** → focused mode, live state grid. **Drift flag** → quiet non-blocking marker; clicking opens **Impact review** (what changed, where used, apply/ignore). **Success** → component usable on canvas; export references the real import.
+
+### 9.5 Tokens / Design-system panel
+- **Purpose:** colors, type, spacing, radius, shadow as named tokens = single source of truth. **Elements:** grouped token lists, edit-in-place, **live contrast check** on color pairs, "where used" per token.
+- **States:** **Empty** → import or seed defaults. **Editing** → everything bound updates live (canvas + code) — the **token ripple** (Signature Moment #5). **Contrast fail** → inline AA warning with ratio + fix (icon+text, not color alone). **Success** → change ripples visibly.
+
+### 9.6 Prototype / Preview
+- **Purpose:** prove "what you see is what ships." **Elements:** full-screen live render, breakpoint switch, **real hover/focus/active states** (free from real components), device frame optional. *(Frame-to-frame click-through linking is cut from MVP — Figma-parity creep — see PRD §8.)*
+- **States:** **Loading** → fast real-render (no fake spinner). **Interactive** → cursor + keyboard, visible focus rings. **Error** → graceful "couldn't render — open editor." **(Fast-follow) Shared view** → clean, no editor chrome; link lifecycle: active / revoked / expired / 404.
+
+### 9.7 Code / Export
+- **Purpose:** earn trust; hand off. **Elements:** file tree, syntax-highlighted **read-only** React+Tailwind, token file, "Copy component," "Download project (.zip)." Code visibly **imports the user's mapped components** and references token vars; **fidelity badge** ("Production-grade" / "Prototype-grade").
+- **States:** **Generating** → streamed formatting. **Ready** → copy/download + honest badge. **Export success** → "Runs with `npm i && npm run dev`." **Error** → specific, retryable. **Unmapped-components warning** → "3 components aren't mapped to your repo yet — export will include Weave defaults for these. Map them?"
+
+### 9.8 System update (re-import changed tokens) — *new screen (review fix; closes JTBD #2)*
+- **Purpose:** keep design & code in lockstep when the system changes. **Elements:** re-import tokens → **diff** (added / changed / removed), **impact preview** ("affects 14 components across 3 screens"), one-click **apply with undo**, per-change accept/skip.
+- **States:** **No changes** → "Your system is up to date." **Diff** → grouped changes with before/after swatches. **Breaking change** → flags components that would break; safe-apply guidance. **Applied** → ripple + "System updated · undo."
+
+### 9.9 Settings — *new (was in IA, unspecified)*
+- **Purpose:** manage system source, component **mappings**, craft standard, account. **Elements:** design-system source, mapping table, **craft standard selector** (Weave default / Impeccable / custom), export defaults, team/billing. **States:** standard load/error; mapping health summary.
+
+### 9.10 Polish panel (Impeccable-driven) — *new product surface*
+- **Purpose:** critique the current screen against the craft standard and fix, in your tokens/components. **Elements:** ranked issue list (spacing off-scale, weak hierarchy, contrast fail, misalignment, orphaned state), each with a **why** (teach) and a **one-click fix**; "Polish all"; before/after.
+- **States:** **Clean** → "Impeccable. Nothing to fix." (earned, not flattering). **Issues** → grouped by severity, each fix previewable. **Applying** → animated corrections. **Can't auto-fix** → explains the manual change needed.
+
+## 10. Signature moments (the award bar — craft these first)
+
+1. **"The system comes alive."** During onboarding, as tokens resolve, the neutral base kit **re-themes to the user's brand in one crafted ~700ms cascade** (colors, type, radius sweeping across components). The *"those are mine"* moment. The single most important animation in the product.
+2. **"What you see is what ships."** Live synced split: nudge a component on canvas and the **real code updates in lockstep**, with the one reserved **live-green** indicator affirming preview = code = export.
+3. **"On-brand in one prompt."** Type *"a pricing section, three tiers"* → it assembles from **their** Card/Button/Text in **their** tokens, with provenance chips — visibly *not* the generic slate/Inter output expected from v0.
+4. **"The clean handoff."** Export becomes a readable file tree that **imports their real components** — a confident, almost anticlimactic *"of course it's real."* Delight through trustworthiness.
+5. **"Change once, everywhere."** *(new)* Edit `brand-500` in the token panel and watch a **~400ms ripple** re-theme every affected component on canvas *and* highlight the changed code lines. The best possible demo of "system as source of truth"; the daily-use aha.
+6. **"The graceful refusal."** *(new — the differentiator, as a moment not an error)* AI hits something your system can't express → a crafted, calm beat: *"You don't have a component for this yet. Compose one from your primitives?"* with its own motion and copy. An error state elevated to a signature interaction is an award-grade move — and it's the exact behavior that separates Weave from tools that fake it with generic markup.
+
+## 11. Visual & art direction
+
+- **Personality:** a precise, calm, professional **instrument** — studio equipment, not a toy. Confident restraint. "Matte body around a bright photo."
+- **Palette (chrome recedes — genuinely warm neutrals so the user's brand pops):**
+
+  | Role | Dark (default) | Light |
+  |---|---|---|
+  | App bg | `#121110` | `#FAF9F7` |
+  | Panel | `#191715` | `#FFFFFF` |
+  | Raised/float | `#221F1C` | `#FFFFFF` + border |
+  | Hairline border | `#2B2724` | `#ECE8E2` |
+  | Text primary | `#F1EEEA` | `#1A1714` |
+  | Text secondary | `#B8B0A6` | `#55504A` |
+  | Text tertiary *(large/non-essential only)* | `#8C847A` | `#8A8279` |
+  | **Interactive accent (iris)** — fills/selection | `#6E56F7` | `#5B44E0` |
+  | Iris **as text/link** (AA-safe variant) | `#A99BFF` | `#5B44E0` |
+  | **Reserved "live/real" green** — indicator only | `#3FB984` | `#1E9E6A` |
+  | Warning / Error | `#E0A03A` / `#E5484D` | same, AA-checked |
+
+  **Color rules (review fixes — resolve the contradictions):**
+  - **Green is reserved** exclusively for the live/synced indicator (Moment #2). **Success is NOT green** — success = neutral surface + iris check icon + label. This keeps green meaningful.
+  - **Iris as text must use `#A99BFF` on dark** (the `#6E56F7` fill fails AA as text). Iris fills are for selection/primary actions.
+  - **Tertiary text is large/non-essential only** (it doesn't clear AA 4.5:1 for body). Body/secondary uses `#B8B0A6`+.
+  - Every status pairs **icon + label** with color (never color alone).
+  - Dark is the **default and hero**; the canvas art-board can be set light/dark **independently** of the app theme so a light brand isn't judged against black.
+
+- **Typography:** chrome uses a **precise neutral grotesk that is NOT AI-branded** — *avoid Inter (the generic default), and avoid Geist (Vercel) / Söhne (OpenAI), which re-install the exact "AI look" we're fighting* (review catch: v0's output literally ships in Geist). Recommend **Untitled Sans, Suisse Int'l, or Neue Haas Grotesk/Unica** (or commission a cut). Mono for code/tokens: **Berkeley Mono** or **Commit Mono** (avoid the default JetBrains-everywhere look). **Type scale (UI):** 11 / 12 / 13 / 14 / 16 / 20 / 24, weights 400·500·600, line-height 1.4 (UI) / 1.6 (code), slight negative tracking on ≥20 only. **Critical:** the canvas renders the *user's* fonts — chrome type must stay neutral and never clash.
+- **Spacing & radius:** 4px base scale (4·8·12·16·24·32·48). Radius **6 / 10 / 14** — deliberately *not* "8px on everything."
+- **Iconography:** 1.5px stroke, geometric, consistent radius; quiet, learnable glyphs for component/token/frame/mapping/polish.
+- **Depth:** flat + hairline borders + one soft shadow tier for raised/floating; no skeuomorphism.
+- **Data-viz (light use — usage counts, contrast meters, polish scores):** monochrome + single accent; meters and small bars, not chart junk (follow standard restrained categorical palette if a dashboard grows).
+
+### 11.5 Craft standard — Impeccable alignment
+Weave's UI (and the output it generates) must pass the craft checklist in **§20**, derived from Impeccable's anti-slop philosophy: intentional type hierarchy (real size *and* weight contrast, not just size), strict spacing scale, purposeful and restrained color, true visual hierarchy and focal point, optical alignment/correction, depth used sparingly, motion with purpose, and **every state designed** (empty/loading/error/success are where craft shows). 🟡 *Reconcile exact rules with the real Impeccable ruleset before locking (§0 note).*
+
+## 12. Motion & micro-interactions
+
+- **Character:** precise, quick, spring-based for direct manipulation; motion clarifies causality, never decorates.
+- **Params (review fix — buildable, not vibes):** drag/direct-manipulation spring ≈ **stiffness 210 / damping 24**; micro-feedback **90–160ms** ease-out; panels/drawers **180–240ms**; **re-theme reveal 600–800ms** (the one indulgent moment); **token ripple ~400ms** propagation with synced code-line highlight; **AI placement stagger ~90ms** per element.
+- **`prefers-reduced-motion`:** honor fully — re-theme cascade → crossfade; ripple → instant; disable springs/parallax. No motion is load-bearing for meaning.
+
+## 13. Voice & microcopy
+
+- **Tone:** precise, calm, designer-native; speak in **components, tokens, frames, variants** — never "divs/markup." Confident, never hypey; honest about fidelity; **explains *why*** when it fixes something (the Impeccable "teach" instinct).
+- **Do words:** compose, system, tokens, components, live, real, ships, export, on-brand, polish, craft.
+- **Don't words:** magic ✨-as-crutch, "just," "simply," "AI-powered," "pixel-perfect," "website builder," "slop."
+- **Example strings:** onboarding success → *"Your system is live."* · export → *"Ready to ship. Runs with `npm i && npm run dev`."* · AI can't map → *"You don't have a component for this yet. Want me to compose one from your primitives?"* · polish clean → *"Impeccable. Nothing to fix."* · polish fix → *"Bumped this to your 24px step and matched your heading weight — here's why."*
+
+## 14. Accessibility & responsive
+
+- **Target:** WCAG 2.2 AA for Weave's own UI (the palette in §11 is tuned to pass — a tool that *sells* contrast checking cannot fail its own). Full keyboard operability of the canvas; visible focus rings; ARIA for panels/trees; respects reduced-motion + prefers-color-scheme.
+- **Color independence:** every status (live/warn/error, contrast/polish pass/fail) pairs icon/label with color.
+- **Output a11y:** surface **contrast checks on the user's token pairs** at import and in the token panel; the base kit ships **semantic HTML + ARIA** so exported code passes Devon's review (not just contrast).
+- **Chrome-vs-brand collision policy (review fix):** the iris selection outline and live-green dot must stay legible when the user's brand *is* violet or green — use a **dual-tone selection outline** (light/dark stroke pair) and always pair the live indicator with an icon+label; test chrome over violet/green/black/white canvases.
+- **Responsive (the app):** desktop-first, optimized ~1280–2560px; graceful ≥1024px; below → "Weave is best on desktop." Generated **output** is responsive-ready (auto-layout), with the second breakpoint a near-term follow (PRD).
+
+## 15. Technical & platform constraints (for design awareness)
+
+- **Stack:** desktop web app; output is **React + Tailwind**, tokens as CSS vars / Tailwind theme. Canvas, preview, and export share **one component runtime** → visual parity is by construction; design assuming no divergent mock rendering.
+- **Wedge-critical:** export emits the user's **real, mapped components** (import paths + prop names), not Weave-internal clones — design the **mapping** surface (§9.4) as first-class.
+- **Constraint that shapes UX:** AI is hard-limited to the project's component/token registry → design the **"can't map / compose from primitives"** path (Moment #6) and the **Polish** loop as first-class flows.
+- **Budgets:** <16ms/frame canvas on a 50-*node* screen (define node = one rendered element instance, incl. nested primitives); AI first paint <2s.
+
+## 16. Design success metrics
+
+- **Activation:** % of new users who compose a screen from their own system **and export** (target ≥40% 🔴).
+- **Time-to-first-value:** signup → first exported on-brand screen (<20 min median 🔴; guarded by the no-file onboarding path).
+- **Craft lift:** Polish-panel issues per screen trend down; % screens exported "clean" (no open craft issues).
+- **Task success:** compose-a-known-section success ≥90% in usability tests 🟡.
+- **Trust/delight:** SUS ≥80 🟡. *(The primary trust metric — would an engineer merge it — is measured on the eng side; see PRD §3.)*
+
+## 17. Deliverables expected (from the design agent)
+
+1. **User flows** for the 3 journeys (§7), incl. the **no-file onboarding** and the **system-update** loop.
+2. **Low→mid-fi wireframes** for all screens in §9 (9.1–9.10), each with empty/loading/error/success (+ save/offline/conflict for the editor).
+3. **Hi-fi designs:** onboarding (incl. re-theme frames), Editor, Component Library (variant matrix + mapping + drift), Tokens, System update, Polish panel, Preview, Code/Export, Settings.
+4. **Weave's own design system** (tokens, recessive-chrome components, dark+light) — dogfood the concept; ship it passing §20.
+5. **Prototypes + motion specs** for the 6 signature moments (§10).
+6. **Redlines** for the two hardest interactions: canvas↔code sync, and the constrained-AI **propose→accept / graceful-refusal** flow (§10.6).
+7. **Microcopy deck** (the voice in §13 across states) and **a11y-annotated** redlines.
+
+## 18. Inspiration / benchmarks (emulate the *quality*, do **not** clone)
+
+- **Linear** — precision, keyboard-first speed, restrained dark UI, ⌘K discipline.
+- **Figma** — canvas calm, direct-manipulation fluency, inspector clarity (the muscle memory to respect).
+- **Vercel/Geist & Raycast** — code-as-first-class-object; velocity — *but note (review):* leaning on these too hard reproduces the 2026 default uniform; borrow the discipline, not the skin.
+- **Subframe** — nearest competitor; study its visual-builder→React flow, then out-design it on "your own system + craft is the source of truth."
+- **Impeccable (impeccable.style)** — the craft bar itself; the anti-slop standard Weave must meet and enforce.
+- **One off-cluster reference (review fix):** **Teenage Engineering / broadcast-console & camera UI** — for one ownable, tactile detail that escapes the sameness. Cash the "instrument" metaphor into form: e.g., **engraved-label token chips** and **dial-like prop steppers** for numeric tokens.
+> Do not clone any of these. The synthesis — *a recessive, precise instrument that makes the user's brand and real, well-crafted code the hero* — is Weave's own.
+
+## 19. Open design questions (validate before locking — carries strategy 🔴s)
+
+- 🔴 **A1 (owns-code):** How much *code surface* do designers want? Design two framings — "export & hand to dev" (code as proof) vs. "you own/edit the code" (code as workspace) — and test which converts. Changes how prominent the code panel is.
+- 🔴 **A2 (Figma coexistence):** replacement canvas or per-phase tool alongside Figma? Recommend designing for **coexistence** first; validate with a clickable-mock task test before building the canvas.
+- 🔴 **A4 (vs Subframe):** make the "system + craft as source of truth" differentiation *visible* in the UI before hi-fi.
+- 🟡 **Mapping vs authoring:** MVP leans on **mapping to real components**; how much in-app authoring does Devon expect? Design mapping as first-class now, authoring as a path.
+- 🔴 **Impeccable rules (fidelity):** reconcile §11.5/§20 with the verbatim Impeccable `DESIGN.md`; decide whether Weave *embeds the Impeccable skill* or ships a compatible ruleset.
+- 🟡 **Fidelity labeling:** validate "Production-grade / Prototype-grade" language with real engineers.
+
+## 20. Appendix — Craft checklist (the "Impeccable-grade" bar)
+Every screen (Weave's UI *and* generated output) should pass:
+- **Type:** a real hierarchy via size **and** weight (not size alone); ≤2 families; consistent scale; no default-Inter look.
+- **Spacing:** everything on the 4px scale; intentional whitespace; related things grouped, unrelated things separated; no arbitrary gaps.
+- **Color:** restrained; one purposeful accent; neutrals do the work; color never the only signal; AA contrast.
+- **Hierarchy:** one clear focal point per screen; secondary/tertiary genuinely de-emphasized; alignment optical, not just mathematical.
+- **Depth:** used sparingly and consistently (one shadow tier); borders hairline; radius on-scale.
+- **Motion:** purposeful, fast, causal; reduced-motion honored.
+- **States:** empty/loading/error/success all designed; empty and error states are craft showcases, not afterthoughts.
+- **Detail:** optical corrections, consistent icon weight, no orphaned or truncated content, real content not lorem.
+> 🟡 Align exact thresholds with the real Impeccable ruleset (§0).
+
+---
+
+### Sources (Impeccable)
+- Impeccable — impeccable.style (site, docs, "Designing with Impeccable"): https://impeccable.style/ · https://impeccable.style/docs/impeccable/ · https://impeccable.style/designing/
+- GitHub — pbakaus/impeccable (incl. `DESIGN.md`, `SKILL.md`): https://github.com/pbakaus/impeccable
+- Overviews: https://abduzeedo.com/impeccable-open-source-ai-design-skill-better-ui · https://emelia.io/hub/impeccable-ai-design-skill
+
+_End of brief v2. Pair with `design-app-prd.md` for scope and acceptance criteria. Update as 🔴 items validate._