agentic-dev/docs/product/design-app-prd.md

# PRD — Veect MVP · v2

> **⚡ v3 PIVOT NOTE (2026-07-10, updated for spec rev 1.2) — read first.** Distribution pivoted from cloud SaaS to **repo-native**, delivered as a **standalone app + Docker image**: connect a remote repo (GitHub/git URL) or local checkout; `veect.config.json` points at component folders; git worktree per design project (app-managed, repo untouched); SQLite + JSON-in-branch persistence; **Publish** pushes `veect/<slug>` for an ordinary PR. The npm-in-repo package is a later distribution. **Prototype note:** the built editor's multi-view frames (desktop/tablet/mobile clusters) supersede F3's "desktop breakpoint only," and its two-way code grammar supersedes F5's read-only code view — see `veect-design-spec-current.md` + `veect-ui-gap-spec.md`. **`veect-technical-spec.md` is now the authoritative build document.** Superseded here: F1 (token-file import → tokens read from the repo), F2's mapping half (components are the repo's real ones by construction), F7's zip export (output = commits on a branch), F8 (auth/cloud). Still authoritative here: the wedge, personas, JTBD, F3–F6 canvas/AI/preview behavior, F9 craft layer, §8 out-of-scope discipline, §13 validation gate (V1 concierge-PR test now runs _through the tool's own output_), and all Given/When/Then that concern editor behavior.

_Founder OS · Phase 6 (MVP Definition) · 2026-07-09_
_Companion docs: `company-context.md` (strategy) · `design-brief-veect.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. Veect 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) — Veect 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: Veect 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 "Veect 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 Veect 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-veect.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** (Veect 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 Veect'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** (Veect → 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.