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.