agentic-dev/docs/product/design-brief-veect.md

# Design Brief — "Veect" (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 Veect's craft standard._
_**v3 (2026-07-10): the interactive prototype + codebase now exist and are ground truth** — see `veect-design-spec-current.md` (authoritative design language: the monochrome ink instrument) and `veect-ui-gap-spec.md` (the remaining work: repo-connect, publish, environment surfaces + editor deltas). This brief remains authoritative for **intent** (north star, principles, journeys, signature moments, voice, a11y) — where §11's old art direction conflicts with the design spec, **the design spec wins**._
_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 Veect **twice**, and both are load-bearing:

1. **As Veect'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). Veect dogfoods the rules it sells.
2. **As a product capability** — Veect 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:** **Veect** — decided 2026-07-10. Pronounced **VEEKT**, rhymes with _piqued_ (lock this in all voice work). Lowercase `veect` in CLI/code contexts.
- **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. Veect 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.** Veect'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, rev 1.2: repo-connect flow).**
Open the app → **Connect a repository**: GitHub device-code sign-in → pick the repo (or paste a git URL / choose a local folder) → Veect clones + installs (honest, first-class progress — this is minutes, design it) → repo has `veect.config.json`? straight in; **no config? the wizard**: browse the repo tree, pick component folders visually, confirm detected framework/tokens → _the component library and tokens load from the repo and the canvas re-themes to their brand_ → compose a first section (drag or ✦) → **Polish** → **Checkpoint → Publish** → the PR link. **The aha: "these are _our actual components_ — and that's a real branch my team can review."**

**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 — Connect your repository _(rev 1.2: replaces the file-upload flow)_

- **Purpose:** get from zero to the repo's live system. **Elements:** three connect paths presented as equals — **GitHub** (device-code card: the code large and copyable, "waiting for approval" state), **git URL** (HTTPS+token / SSH-via-agent, with a plain-language access explainer), **local folder** picker; then **clone + install progress** (real stages: cloning → installing → reading components — with honest time feel, never an indeterminate spinner for minutes); then **the config wizard** if the repo has no `veect.config.json`: a repo-tree browser with visual multi-select of component folders, detected framework/tokens shown for confirmation, "we'll include this config in your first published branch."
- **States:** **Choose source** → three calm cards. **Device-code wait** → code + "approve in browser" with retry. **Auth failed / no access** → specific, kind, actionable ("This token can't see acme/shop — ask for read access or try SSH"). **Read-only connect** → allowed, with a quiet banner ("You can design and checkpoint; Publish needs write access"). **Cloning/Installing** → staged progress, cancellable. **Wizard** → tree browser, folder multi-select, confirm chips. **Env needed** → detected `.env.example` → the Environment panel (§9.12), skippable with consequences stated. **Success** → components + tokens stream into the library and **the canvas re-themes from the repo's own system** (Signature Moment #1) + "acme/shop 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 "Veect 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 Veect 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** (Veect 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.

### 9.11 Publish & branch status _(new in rev 1.2)_

- **Purpose:** turn a checkpoint into a reviewable PR without the designer knowing git. **Elements:** per-project branch card (`veect/checkout-flow` · commits · behind-base indicator), **Checkpoint** and **Publish** as distinct, honest verbs; after publish, the **compare/PR deep link** as the hero action; "Update from base" with plain-language explanation.
- **States:** **Unpublished checkpoints** → gentle nudge chip. **Publishing** → progress. **Published** → PR link + "your team can review this now." **Push rejected (no write access / protected)** → specific fix path, patch-export escape hatch. **Behind base** → staleness count + Update action. **Conflict on update** → read-only conflict view, "ask a developer" guidance — never a merge editor in v1.

### 9.12 Environment & connection health _(new in rev 1.2)_

- **Purpose:** the app's honest answer to "why is preview broken?" **Elements:** per-workspace env form (keys from `.env.example`, values masked, stored encrypted, never committed — say so in-UI); connection card (provider, access level, last fetch); doctor strip (git, disk, adapter health) with one-line fixes.
- **States:** **Missing env** → adapter crash translated to a human sentence ("Preview needs `DATABASE_URL` — add it here; it stays on this machine"). **Values saved** → adapter restarts automatically. **Token expired / revoked** → re-auth flow inline. **Disk pressure** → per-workspace usage + archive suggestions.

## 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 Veect from tools that fake it with generic markup.

## 11. Visual & art direction — **v3: SUPERSEDED by the shipped design language**

> **The implemented design language wins.** The prototype resolved this section's recommendations into something sharper than what was written here — the **monochrome ink instrument**: no chromatic accent at all (the accent IS the ink, `#161513`/`#F4F4F2`), warm paper neutrals, radius **2px** everywhere in chrome, hairline separation with zero floating shadows, **Instrument Sans** (UI) + **Fragment Mono** (engraved labels) + the customer's own font for canvas content, hand-drawn 16-grid icons, **amber reserved exclusively for AI-scope affordances**, muted `--live` green for status, dark by default. **The authoritative tokens, values, and rules live in `veect-design-spec-current.md` §2 — design all new surfaces from that file, not from this section's history.**
>
> What survives from this section as still-binding intent: the **personality** ("a precise, calm instrument — matte body around a bright photo"); **color never the only signal** (icon + label always); the **canvas art-board theme is independent** of app chrome so light brands aren't judged on black; chrome type never competes with the customer's canvas font; and the data-viz restraint rule below.
>
> **Wordmark (corrected from the naming decision):** the mark is the lowercase `veect` wordmark closed by the **square ink terminal** — "the vector point" (design spec §2.1). No pictorial mark. _(The earlier ee-pair concept is retired; the pair/parity story lives on in Signature Moment #2's canvas=code lockstep, not in the logotype.)_

- **Data-viz (light use — usage counts, contrast meters, polish scores):** monochrome + single accent; meters and small bars, not chart junk.
- **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

Veect'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 Veect'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 → "Veect 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 Veect-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. **Veect'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 Veect 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 Veect'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 Veect _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 (Veect'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._