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/company-context.md

@@ -0,0 +1,83 @@
+# Company Context — "Weave" (working name)
+
+_Living strategy doc · Founder OS · last updated 2026-07-09_
+_Status: Phases 1–5 **compressed** at the founder's request to jump to Phase 6. Confidence tags: 🟢 verified · 🟡 reasoned · 🔴 assumed / needs validation._
+
+> **Working name only.** "Weave" is a placeholder so the docs read cleanly — not a naming decision. Real naming/trademark is a separate exercise. 🔴
+
+---
+
+## One-liner
+A **design-system-native canvas** that turns your own tokens and components into **real, production-ready React**, held to a **craft standard (Impeccable)** so output is on-brand *and* genuinely well-designed — so what a designer composes is exactly what ships.
+
+## Problem
+Product designers who already have a design system still can't ship on-brand UI without waiting on engineering. Today's AI design/code tools (v0, Lovable, Bolt, Figma Make) re-invent **generic** UI instead of using the team's own components and tokens — so the output is off-brand and thrown away, and the design→code handoff stays lossy.
+- 🟢 92% of designers and 91% of developers say the handoff process needs improvement (Figma, *State of the Designer*).
+- 🟢 Figma Make users report it "won't use my library components" / "created new ones that just looked like mine"; v0 "treats the Figma file as a screenshot" (Figma forum; user teardowns).
+- 🟢 The market has already conceded the pain — Bolt, Lovable and Figma all bolted on "use your design system" features in 2025 because generic output was the #1 designer complaint.
+
+## Beachhead ICP
+Product/UI designers and design-system / design-engineer leads at startups & scale-ups (~10–200 people) that **already have a design system** (tokens + component library) and ship a **React** web product. 🟡
+- **User (feels pain):** product designer · design-system designer · design engineer.
+- **Champion:** Head of Design / Design Systems lead. 🟡
+- **Economic buyer:** design leadership budget; escalates to VP/Eng at team tier. 🟡
+- **Veto:** Engineering ("will the emitted code meet our repo standards?") and Security at enterprise. 🟢
+
+## Top Jobs-to-be-Done (from discovery research)
+1. When I finish a design, I want the built UI to match it exactly without policing every pixel, so I can stop redlining.
+2. When our design system changes, I want Figma and code components to stay in lockstep, so "the library" means one thing everywhere.
+3. When I need a screen shipped, I want to produce it myself without an eng sprint slot, so I can move at the speed of the idea.
+4. When I use AI to generate UI, I want it built from **my** components/tokens (not a generic theme), so I get on-brand output I don't throw away.
+
+## Wedge / Positioning (April Dunford frame)
+- **For** product designers who have a design system but can't ship on-brand code without engineering,
+- **Weave is** a design-system-native canvas that emits real, production React from your own tokens + components,
+- **unlike** v0 / Lovable / Bolt / Figma Make, which are developer/prompt-first and generate generic, throwaway UI,
+- **so that** what you design is what gets built — on-brand, high-craft, with zero translation loss.
+- **Category:** "design-system-native design-to-code" — a wedge inside the crowded AI-builder space. 🟡
+
+**Two things deepen the wedge (added after review):**
+- **Real-component mapping** — export emits the team's *real* coded components (their import paths + prop names), not Weave-internal clones. Without this the output never clears the engineer's merge bar and the wedge collapses to "v0 with theming." 🟢 (this was the single biggest gap the red-team found)
+- **Craft layer (Impeccable)** — beyond "constrained to your system," a Polish pass holds output to a craft ruleset (impeccable.style — an open-source anti-"AI-slop" design language for AI harnesses). On-brand **and** high-craft is a sharper position than either alone. 🟡
+
+## Why now
+AI codegen is finally good enough for *constrained* composition; design-token standardization (W3C DTCG) is maturing; "design engineering" is rising as a role; Figma Dev Mode's per-seat pricing backlash has opened a door. 🟡
+
+## Competitive frame (from existing knowledge — deep teardown deferred)
+| Cluster | Players | Why they don't own the wedge |
+|---|---|---|
+| Prompt/dev-first app builders | v0, Lovable, Bolt | Fast but generic output; prompt-first not canvas-first; not BYO-design-system-first |
+| Visual design-to-code | **Subframe** (closest), Builder.io Fusion, Anima, Locofy | Subframe is strong but leans "design in browser → code"; others are dev-first imports or Figma-plugin exporters with fidelity issues |
+| Site builders | Framer, Webflow | Own proprietary runtime; you don't get *your* React components/code |
+| Incumbent | Figma (Dev Mode, Make) | Enormous stickiness, but generic AI output and a handoff "tax"; not designer-owned code from your system |
+
+**White space (the bet):** a **designer-first** canvas where a **bring-your-own design system is the source of truth** and AI is **constrained to it**. 🟡 *(Subframe is the nearest competitor; a real teardown is still owed to harden the "unowned" claim — see 🔴 A4.)*
+
+## North Star Metric
+**Weekly shipped screens** — screens whose code is exported and actually used, per active designer. No repo integration yet, so **proxy** it via an explicit "mark as shipped" + design-partner check-ins. 🟡
+- **Activation:** first screen composed from the user's *own* tokens + components and exported. 🟡
+- **Trust bar (primary, engineer-judged):** real PRs at design partners — merge rate + % LOC changed pre-merge. The right judge is the engineer, not the designer's self-report. 🟢
+- **Wedge-usage guardrail:** % of exported screens composed *majority* from the user's mapped/real components (not stock base kit) — so we can't "pass" by validating a re-themed generic kit. 🟡
+
+## Business model (compressed — full Phase 5 deferred)
+Per-seat SaaS for designers with a usage component on AI compose; land bottom-up with individual designers, expand to design teams. Not yet modeled. 🔴
+
+---
+
+## Validation gate status (Phase 1) — **NOT formally cleared**
+The pain is real and well-sourced 🟢, but the core belief rests on unvalidated assumptions. Per Founder OS discipline, the MVP in the PRD is scoped as **the cheapest way to test the core bet**, not a green-lit build. Run the validation experiment (see PRD §Risks/Validation) in parallel with any build.
+
+### Riskiest assumptions to validate
+- 🔴 **A1 — Designers want to compose/own real code.** Many want the *outcome* (their design shipped faithfully, fast), not to own a codebase. Evidence is genuinely mixed; some designers report AI codegen is *slower* than just designing.
+- 🔴 **A2 — Designers will adopt a new canvas.** Figma stickiness is structural (libraries, network effects, org process); real-world switching is usually *additive / per-phase*, not a replacement.
+- 🔴 **A3 — The bottleneck is tooling, not governance.** Practitioners repeatedly say design-system drift/sync is a people-and-process problem a tool alone won't fix.
+- 🔴 **A4 — "BYO design system → real code" is genuinely unowned.** Competitive teardown was deferred this pass; Subframe is close. Harden before fundraising claims.
+
+### Validation gate (sequenced, with kill criteria — run before/at the start of build)
+1. **Concierge real-PRs (primary):** hand-build 5 partners' screens from their own systems and open **real PRs** against their repos. **Pass** ≥3/5 merged with <10% LOC changed; **kill/rethink** if <2/5 or reviews are structural. Tests A1 *and* the trust bar with the correct judge, with zero product code.
+2. **Clickable-mock task test:** 5 designers complete the core task on a Figma prototype of the editor. **Pass** ≥4/5 unaided. Tests A2 (will they adopt a new canvas) before the canvas is built.
+3. **Fake-door demo** vs. a v0-style generic control: **pass** waitlist conversion ≥2× control.
+4. **Competitor teardown** (Subframe et al. — owed from Phase 2) to harden A4. No code needed.
+5. **10 problem interviews** with design-system leads probing A1 and A3.
+
+> Founder OS discipline: only the token-engine + shared-runtime spike should run concurrently with these. "Build in parallel with validation" is how the gate gets quietly bypassed — the red-team flagged exactly this.

docs/product/reference/project/uploads/design-app-prd.md

@@ -0,0 +1,177 @@
+# PRD — "Weave" MVP (working name) · v2
+
+_Founder OS · Phase 6 (MVP Definition) · 2026-07-09_
+_Companion docs: `company-context.md` (strategy) · `design-brief-weave.md` (UI/UX)_
+_v2 changes (from adversarial product review + Impeccable integration): **real-component mapping pulled into MVP** (the wedge depended on it); **Impeccable craft/Polish layer added** (F9); validation gate **sequenced with kill criteria**; trust metric moved to **engineer-observed merge behavior**; scope trims (share link, frame-linking, full authoring → deferred)._
+_Tags: 🟢 verified · 🟡 reasoned · 🔴 assumed / needs validation_
+
+---
+
+## 1. Problem & why now
+Product designers with an existing design system can't ship on-brand UI without engineering, and AI tools (v0, Lovable, Bolt, Figma Make) generate **generic, throwaway** code that ignores their tokens and components. Weave makes the design system the source of truth — a canvas where everything you compose is **real React built from your own components** — and holds output to a **craft standard (Impeccable)** so it's on-brand *and* genuinely good, not slop. (Evidence in `company-context.md`.)
+
+## 2. Goals & non-goals
+**Goals (MVP)**
+- Prove the core bet: **your design system in → on-brand, high-craft, production React out, from a visual canvas.**
+- Get a designer from "bring my system" to "export a screen's real code" in **one sitting (<20 min)** 🟡.
+- Clear the trust bar: an engineer would **merge** the output (import their real components, pass review), not rewrite it 🟢. *This is the bar the whole wedge rests on.*
+
+**Non-goals (MVP)**
+- Not a full-app/backend builder (Lovable/Bolt's lane) — Weave is **UI + prototypes**.
+- Not a Figma replacement or vector-illustration tool.
+- Not multi-framework, not real-time multiplayer, not repo round-trip, not a component-authoring studio (all deferred; §8).
+
+## 3. Success metrics
+| Metric | Definition | MVP target |
+|---|---|---|
+| **North Star** | Weekly shipped screens (code exported & used), proxied by an explicit **"mark as shipped"** + design-partner check-ins (no repo integration yet) | trend up 🟡 |
+| **Trust bar (primary, engineer-judged)** | Real PRs opened at design partners: **merge rate**, **% LOC changed pre-merge**, structural-vs-nit review comments | ≥60% merged with <10% LOC changed 🔴 |
+| **Wedge-usage** | % of exported screens composed *majority* from the user's **mapped/real** components (not stock base kit) | ≥50% floor 🔴 |
+| **Activation** | First screen composed from own system **and exported** | ≥40% of signups 🔴 |
+| **Time-to-first-value** | Signup → first exported on-brand screen | <20 min median 🔴 |
+| **Craft** | Open Polish issues per exported screen | trend →0 🟡 |
+| **Guardrail** | Canvas interaction latency | <16 ms/frame on a 50-node screen (node = one rendered element instance) 🟡 |
+
+## 4. Target users
+- **P1 — "Maya," product designer** (primary): has a design system, ships React, blocked on eng, burned by generic AI output. Often does **not** own a clean token file (it lives in Figma/repo).
+- **P2 — "Devon," design-systems / design-engineer lead** (champion + gatekeeper): owns the **real coded component library**; cares that output imports *their* components and passes review. Holds the merge veto.
+
+## 5. Core value & the "aha"
+*"I typed a screen, it came out in MY components and MY tokens, it's genuinely well-designed, and the code imports our real library."* Four trust beats: my system re-themes the tool → the canvas renders the **real** component → **Polish** makes it craft-grade → export imports our **real** components.
+
+## 6. MVP — the core loop
+```
+1. Bring your system  →  2. Map to your real components  →  3. Compose on canvas
+   tokens·fonts·assets     (Devon; optional if no coded lib)      real components
+   (file OR 5-token path)                                              ↓
+        ↑                                                    4. AI compose (constrained)
+        └──────────── 7. Export (imports your real code) ← 6. Polish (craft) ← 5. Preview
+```
+
+## 7. In scope (MVP) — each traced to the wedge
+| # | Capability | MVP boundary | Traces to |
+|---|---|---|---|
+| F1 | **Design-system import** | Tailwind config **or** paste CSS variables **or** Figma Variables (if available); **no-file path: set 5 core tokens** over the base kit. Upload fonts (woff2) + assets. One source of truth. | Whole wedge; Maya's real input path |
+| F2 | **Component library + mapping** | Tokenized **base kit** (~15 components, **semantic HTML + ARIA**). **Map base-kit components → the team's real components** (import path + prop names) so export references their library. Save composed **patterns**. *(Full variant/prop authoring deferred.)* | Wedge-critical: clears the merge bar; JTBD #2 |
+| F3 | **Canvas / composer** | Frames, drag/drop, **auto-layout** stacks (dir/gap/padding = tokens), props, token binding, undo/redo, keyboard-first. **Desktop breakpoint**; layout model responsive-ready. | Figma-like half; flow |
+| F4 | **AI compose (constrained)** | Prompt → assembles **only** from mapped/base components + tokens; **propose→accept** (staged ghost layer); shows provenance; **graceful refusal** (offers to compose from primitives w/ token binding + save) — never emits non-system markup. | The differentiator; JTBD #4 |
+| F5 | **Real code output** | Clean **React + Tailwind**; **imports the user's mapped components** (not inlined clones); tokens as CSS vars/Tailwind theme; Prettier; deterministic (same tree → same code). | The trust bar; JTBD #1 |
+| F6 | **Live preview** | Same runtime as canvas/export renders the **real** components; breakpoint switch; **real hover/focus/active states**. *(No frame-to-frame linking — see §8.)* | Kills "dead document"; JTBD #1 |
+| F7 | **Export / handoff** | Copy component code; **download runnable project (.zip)** wired to tokens + real component imports. *(Share link deferred.)* | Activation; North Star |
+| F8 | **Auth / projects** | Projects, autosave, single-player. **Manual provisioning acceptable** for a ~10-team design-partner MVP. | Table stakes |
+| **F9** | **Craft / Polish layer (Impeccable)** | Generated & composed output adheres to a **craft ruleset**; a **Polish** action critiques the screen (spacing, hierarchy, type, contrast, alignment, states), proposes **one-click fixes in your tokens/components**, and **explains why** (teach). | On-brand **and** high-craft = anti-slop; new user ask |
+| F10 | *(fast-follow)* **Pluggable standard** | Choose craft standard: Weave default / **Impeccable** / custom. | Extends F9; deepens moat |
+
+## 8. Explicitly OUT of scope (the load-bearing section) — deferred
+> Rule: *"Does the core value — on-brand, high-craft real code from a visual canvas — survive without it?"* If yes → cut.
+
+- **Full component-authoring studio** (variant/prop/slot editor). MVP = base kit + **mapping** + pattern-save; authoring recreates Subframe and risks a third source of truth. → fast-follow
+- **Real-time multiplayer.** Single-player + (later) share link. → v2
+- **Repo round-trip / two-way Git sync.** The dream; not needed to prove value. Export-only. → v2
+- **Share/read-only preview link.** Copy+zip is the activation event; link is virality, not the bet. → fast-follow
+- **Frame-to-frame prototyping / interaction linking.** Figma-parity creep; conflicts with "not a Figma replacement." Real component states come free. → v2
+- **Figma file (layout) import.** Fidelity rabbit hole (v0/Anima's failure). Tokens/Variables yes; layouts no. → v2
+- **Multiple frameworks** (Vue/Svelte/SwiftUI/HTML). React+Tailwind only. → later
+- **Full vector/illustration tools.** Composer, not illustrator. → out of lane
+- **Backend / data / auth-in-app / business logic.** Out of Lovable/Bolt's lane. → out of lane
+- **Second breakpoint (mobile).** Desktop MVP; model responsive-ready. → near-term follow
+- **Design-token governance/versioning, multi-brand; plugins/marketplace; comments/redline.** → v2
+
+## 9. User stories & acceptance criteria (Given/When/Then)
+
+**US-1 — Bring my system (incl. no-file path)**
+- **Given** a Tailwind config / pasted CSS vars / Figma Variables, **when** I import, **then** tokens parse and the base kit re-themes within ~3s.
+- **Given** I have no token file, **when** I choose the 5-token path, **then** I set brand/neutral/radius/font/spacing and the kit re-themes live — **no dead end**.
+- **Given** an invalid file, **when** I import, **then** I get a line-referenced error with manual mapping.
+
+**US-2 — Map to my real components**
+- **Given** a coded component library, **when** I map "Weave Button" → `@/components/ui/Button` and its props, **then** the code preview shows the exact real import, and canvas instances render as that mapped component.
+- **Given** unmapped components on a screen, **when** I export, **then** I'm warned which will fall back to Weave defaults, and offered to map them.
+
+**US-3 — AI compose, constrained**
+- **Given** an imported system, **when** I prompt "pricing, three tiers," **then** the result uses **only** my mapped/base components + tokens, staged as a ghost layer to **accept/discard**, listing components used.
+- **Given** the AI can't map a need, **when** it hits it, **then** it **says so** and offers to compose from primitives (with token binding + save) — **it does not inject generic markup**. **AC:** across a 100-prompt eval, **0 unregistered elements** in output. 🟢 (differentiator integrity)
+
+**US-4 — Trust the code (engineer-judged)**
+- **Given** a composed screen, **when** Devon opens the code, **then** it **imports our real components** (not re-declared inline), references token vars, is Prettier-clean, `tsc`+`eslint` clean.
+- **Given** an exported zip, **when** run (`npm i && npm run dev`), **then** it renders identically to preview (shared runtime).
+
+**US-5 — Prototype**
+- **Given** a screen, **when** I preview, **then** real hover/focus/active states work at the desktop breakpoint. *(No click-through linking in MVP.)*
+
+**US-6 — Keep system in lockstep** *(new)*
+- **Given** updated tokens, **when** I re-import, **then** I see a **diff + impact** ("affects 14 components / 3 screens") and can **apply with undo**; bindings are preserved; nothing silently breaks.
+
+**US-7 — Polish to craft standard** *(new — Impeccable)*
+- **Given** a composed screen, **when** I run **Polish**, **then** I get a ranked list of craft issues (off-scale spacing, weak hierarchy, contrast fail, misalignment, missing state), each with a **why** and a **one-click fix expressed in my tokens/components**.
+- **Given** a clean screen, **when** I Polish, **then** it says "Impeccable. Nothing to fix." (earned, not flattery).
+
+## 10. Low-fi wireframes
+_See `design-brief-weave.md` §9 for full screens + states. Editor spine:_
+```
+Top: Project ▾ · [Desktop] · ⟳Preview · ✧Polish · </>Code · ⇪Export
+Left: Pages/Layers · Library(map/patterns) · Tokens
+Center: Canvas + ✦ AI bar        Right: Inspector (props·tokens·layout) / Polish issues
+Companion: Code panel — imports { Button, Card } from "@/components/ui"
+```
+
+## 11. Functional requirements
+- FR-1 Parse Tailwind + CSS-vars + Figma Variables tokens; 5-token quick path; font/asset upload+storage; contrast check at import.
+- FR-2 Base kit (~15, semantic + ARIA) bound to tokens; **component-mapping registry** (Weave component → real import path + prop map); pattern save.
+- FR-3 Canvas engine: frames, drag/drop, auto-layout, token-bound props, desktop breakpoint (responsive-ready model), undo/redo, shortcuts, autosave+offline/conflict handling.
+- FR-4 AI compose constrained to the project registry; propose→accept staging; provenance; graceful-refusal path; 0-unregistered-elements guarantee.
+- FR-5 Codegen: tree → React+Tailwind, **imports mapped components**, tokens as vars, Prettier, deterministic; export = runnable zip.
+- FR-6 Single shared component runtime for canvas/preview/export; breakpoint switch; real interaction states.
+- FR-7 **Polish engine (F9):** evaluate a screen against the craft ruleset; produce ranked, explained, auto-fixable issues expressed in tokens/components.
+- FR-8 Token re-import: diff, impact analysis, safe apply+undo.
+- FR-9 Auth/projects/autosave (manual provisioning acceptable for partner MVP).
+
+## 12. Non-functional requirements
+- **Performance:** <16ms/frame canvas on a 50-node screen; AI first paint <2s; Polish scan <2s on a typical screen. 🟡
+- **Fidelity (corrected):** state the **shared-runtime invariant** (preview == export by construction) as the guarantee; **golden-file visual tests on real user-composed screens** with **pinned browser + fonts** (not base-kit-only). Target ≥98% match. 🟡
+- **Code quality:** exported project passes `tsc`+`eslint`; imports resolve against the mapped library; **semantic HTML/ARIA** in base kit.
+- **Security/privacy:** per-project isolation; assets/fonts scoped to project; **no training on user systems (absolute for MVP)**; SOC2 path noted (not MVP). 🟢 (eng/security veto)
+- **Accessibility (tool):** WCAG 2.2 AA for Weave's UI; keyboard-operable canvas.
+- **Browsers:** latest Chrome/Edge/Safari/Firefox; desktop-first.
+- **Reliability:** autosave ≤5s; no lost work on refresh; offline read-only + reconnect.
+
+## 13. Validation plan & gate (sequenced — review fix)
+> The MVP is a **bet to validate**, not a green light. Run these **before/at the start of build**, with pre-registered kill criteria. Only the token-engine + shared-runtime spike may run concurrently.
+
+| # | Experiment | Tests | Pass / Kill threshold |
+|---|---|---|---|
+| V1 | **Concierge real-PRs:** hand-build 5 partners' screens from their systems, open **real PRs** against their repos | A1 + the trust bar (right judge) | **Pass** ≥3/5 merged with <10% LOC changed; **Kill/rethink** if <2/5 or reviews are structural |
+| V2 | **Clickable-mock task test** (Figma prototype of the editor), 5 designers | A2 (will they work in a new canvas) | **Pass** ≥4/5 complete the core task unaided |
+| V3 | **Fake-door demo** ("your system → on-brand screen → real code") vs. a v0-style generic control | Desirability / positioning | **Pass** waitlist conversion ≥2× control |
+| V4 | **Subframe/competitor teardown** (owed from Phase 2) | A4 (is the wedge unowned) | Decision input; no code needed |
+| V5 | **10 problem interviews** with design-system leads | A1 + A3 (tooling vs governance) | Qualitative gate |
+
+## 14. Key risks & mitigations
+| Risk | L/I | Mitigation |
+|---|---|---|
+| 🔴 Designers want the *outcome*, not to own code (A1) | M/High | V1 + V3 before heavy build; position as "export & hand to dev," code as proof |
+| Output doesn't clear the merge bar (imports/clean) | M/High | Mapping in MVP; shared runtime; golden-file tests; V1 is the direct test |
+| AI "fails open" to generic markup | M/High | Registry-only codegen; explicit refusal path; 0-unregistered eval |
+| Won't displace Figma (A2) | H/Med | Position per-phase (coexist); V2 before canvas build |
+| Subframe/incumbents own it first (A4) | M/Med | V4 teardown; sharpen system+craft wedge; Impeccable moat |
+| Scope creep to "app builder" | H/Med | §8 is load-bearing; guard it |
+| Impeccable rules not literally matched | L/Med | Reconcile with real ruleset / embed the Impeccable skill (F10) |
+
+## 15. Open questions
+- Import a **coded** library at MVP (mapping assumes one exists) vs. base-kit-only for library-less teams? (Support both; mapping is first-class.) 🟡
+- Token source of truth first: Tailwind vs Figma Variables vs CSS vars? (Recommend Tailwind + CSS-vars, Figma Variables if API allows.) 🟡
+- **Embed the Impeccable skill directly, or ship a compatible ruleset?** (F10 decision.) 🔴
+- Promise "shippable" or "starting-point" code? (Fidelity labeling.) 🔴
+
+## 16. Build sequence (trust path first)
+0. **Validation gate (§13)** — V1/V4 need no product code; start immediately.
+1. **Component runtime + token engine** (base kit re-themes from tokens) — the spine.
+2. **Component mapping registry** (Weave → real imports) — the merge bar.
+3. **Canvas compose + inspector** on that runtime.
+4. **Codegen + export** (make the trust bar real early).
+5. **AI compose, constrained** (propose→accept, refusal).
+6. **Polish engine (Impeccable)** + **token re-import**.
+7. **Preview + auth/projects** hardening.
+
+## Exit gate (Phase 6)
+Scope is defensibly minimal — every §7 item traces to the wedge/North Star, §8 removes the rest, and the wedge-critical **mapping** and **craft** capabilities are now in. **Phase 1's gate remains uncleared (🔴 A1–A4):** treat this as the spec for a bet, and run §13 with its kill criteria before committing the full build.

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._