diff --git a/docs/product/README.md b/docs/product/README.md new file mode 100644 index 0000000..19e5548 --- /dev/null +++ b/docs/product/README.md @@ -0,0 +1,120 @@ +# Veect — Product Documentation Bundle + +_Entry point for the development agent. Generated 2026-07-10._ + +You are about to build **Veect**. This bundle is the complete product, design, and technical specification. Read this README first — it tells you what each document is, **which document wins when two disagree**, the invariants you must never break, and exactly where to start. + +--- + +## 1. What Veect is (read this once) + +Veect is a **standalone design application that connects to a code repository** and turns it into a design surface. A product designer connects their team's repo (remote via GitHub/GitLab/git URL, or a local checkout); Veect discovers the repo's **real components and design tokens** and lets the designer compose screens on a canvas using _only_ that system. Every design project is a **git branch in an app-managed worktree**; the designer composes, an AI assistant helps (constrained to the repo's own components), and the result is **checkpointed as real TSX and published as an ordinary pull request** the team can review. + +The wedge: v0 / Lovable / Bolt / Figma Make generate _generic, throwaway_ UI. Veect emits the team's **real components** as **real code an engineer will merge** — on-brand and high-craft, not slop. + +**Pronounced VEEKT** (rhymes with "piqued"). Design language is a **monochrome "ink instrument"** — the tool is deliberately colorless so the customer's brand is the hero. + +### The three invariants — never violate these + +1. **One runtime.** Canvas, preview, isolation view, and exported code all render the same node tree through the same renderer. No approximations, no "roughly how it'll look." +2. **0 unregistered elements.** AI output is whitelist-sanitized against the discovered component registry. Anything outside it is **refused, never faked** with generic markup. +3. **Deterministic code.** Same tree → byte-identical code, every time. Export imports the customer's real library; it never inlines cloned components. + +--- + +## 2. How to read these documents (authority hierarchy) + +Documents were written across several iterations and **deliberately supersede each other**. When two conflict, the higher-authority doc wins on its domain: + +| Domain | Authoritative doc | Notes | +| ----------------------------------------------------------------------------------------- | ----------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------- | +| **How the system must behave** (architecture, connections, git, adapters, AI, milestones) | **`veect-technical-spec.md`** (rev 1.2.2) | The primary build document. Start here after this README. | +| **Visual & interaction language** (color, type, radius, icons, motion, components) | **`veect-design-spec-current.md`** | Ground truth from the built prototype. **Wins over the design brief's older art-direction section.** | +| **UI/UX still to be built** (repo-connect, publish, environment, editor deltas) | **`veect-ui-gap-spec.md`** | Your UI work order. Everything the prototype doesn't cover yet. | +| **UX intent** (north star, principles, journeys, signature moments, voice, a11y) | **`design-brief-veect.md`** | Authoritative for _intent_; where its §11 art direction conflicts with the design spec, the design spec wins (it says so itself). | +| **Product scope — what & why** (features, out-of-scope, personas, acceptance criteria) | **`design-app-prd.md`** | Distribution details superseded by the tech spec; wedge/personas/JTBD/scope discipline still authoritative. | +| **Strategy & context** (problem, positioning, market, assumptions, decisions log) | **`company-context.md`** | The "why." Read for orientation; not a build doc. | +| **Project status** (what's validated, what's missing, non-code work) | **`founder-os-audit.md`** | Honest state-of-the-company. Read to understand what is NOT yet proven. | + +**Recommended reading order for building:** + +1. This README +2. `veect-technical-spec.md` (the whole thing — it's the backbone) +3. `veect-design-spec-current.md` (the design language you'll implement in) +4. `veect-ui-gap-spec.md` (what to build, in milestone order) +5. Skim `design-brief-veect.md`, `design-app-prd.md`, `company-context.md` for intent/scope/why +6. `founder-os-audit.md` last (context on what's unproven) + +--- + +## 3. What already exists vs. what you're building + +**⚠️ Not in this bundle (request from the founder):** the **interactive prototype** (`Veect.dc.html`), the **landing page** (`Veect Landing.dc.html`), and the **React 18 / TypeScript codebase** (`veect-codebase/`). These are the founder's built artifacts. `veect-design-spec-current.md` is their specification. **The codebase seeds `packages/editor`** — do not rebuild the editor from scratch. + +**Already built (inherit, do not redesign):** the entire editor — canvas (React Flow substrate, zustand store), 3-pane panels, activity bar, responsive **multi-view frames** (desktop/tablet/mobile clusters), constrained-AI UX (compose ghosts, scoped edits, refusal protocol, model picker), Polish pass, history with restore cursor, token editor with live ripple, isolation mode, the **bidirectional code grammar** (TSX generates _and_ parses back), and the landing page. See `veect-ui-gap-spec.md` §1. + +**What you're building** is the **repo-native layer** the prototype fakes: the desktop shell (Electron, bundled Node), repository connections, worktree/git engine, discovery engine (real component/token scanning), the preview adapters (embedded Vite + managed `next dev`), SQLite persistence, publish flow, and the new UI surfaces (Connect Repository, Checkpoint/Publish, Environment). The prototype's "seams" map 1:1 onto these subsystems — the wiring table is `veect-ui-gap-spec.md` §4. + +--- + +## 4. Locked decisions (do not relitigate) + +- **Distribution:** standalone desktop app (default) + Docker image (additional). The npm-in-repo package (Storybook-style) is a **later** distribution — build the core layered so it can be added. +- **Repository connection:** remote-first — GitHub device-flow, any git URL (token/SSH), or local folder. +- **Config:** `veect.config.json` (JSON, app-writable, schema-validated). `veect.preview.tsx` stays a hand-authored code file. +- **AI:** ships in v1. Anthropic; key via app Settings (OS-encrypted) or `ANTHROPIC_API_KEY` env. Haiku default, Sonnet option. +- **Framework support:** any React + TypeScript repo, with **full Next.js** (App Router incl. server components) as a first-class adapter via a managed `next dev`. +- **Persistence:** local SQLite (working state/history) + canonical `design.veect.json` committed on the branch (shareable/reviewable). +- **Name:** Veect · npm `veect` · scope `@veectjs/*`. + +Full decision logs live in `veect-technical-spec.md` §18 and `company-context.md`. + +--- + +## 5. Build order (start at M0) + +From `veect-technical-spec.md` §17, cross-referenced with the UI priorities in `veect-ui-gap-spec.md` §7: + +| Milestone | What | Proves | +| --------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------- | +| **M0** | Walking skeleton — shell boots with **no system Node**; open both fixture repos (Vite + Next) as local folders; one real component renders through **both** adapters; minimal worktree. | The bundled-runtime + dual-adapter foundation (highest technical risk — front-loaded deliberately). | +| **M1** | Discovery & registry — real component/token scan, props/tokens panels, watch/HMR, split lazy registries, perf-500 budgets; JSON config wizard. | The repo _is_ the design system. | +| **M2** | Canvas + doc + persistence — the prototype editor on real data; SQLite + JSON write-through. | Composing on real components, durably. | +| **M3** | Worktrees + codegen + checkpoint (local complete) — commit transaction, parity check, code-owned flip, committer identity, **env manager core**. | Real code an engineer would merge, on a branch. | +| **M4** | **Remote repositories + publish** — device flow, PAT/SSH, clone/install pipeline, trust prompt, publish → PR link, failure playbooks. | The flagship remote flow + design-partner onboarding. | +| **M5** | Next.js depth — server-component subtrees, root-layout/middleware handling, font fidelity, adapter pool/crash recovery. | Real Next.js repos work. | +| **M6** | AI compose — context assembly, constrained generation, ghost propose/accept, refusal, provenance, eval suite. | The differentiator, wired to the real registry. | +| **M7** | Docker + hardening — image, doctor, Windows pass, docs. | Self-host + shippable. | + +**Your first concrete actions:** (1) request the prototype codebase from the founder; (2) read `veect-technical-spec.md` end to end; (3) stand up the pnpm monorepo per its §3; (4) build M0 against the two kitchen fixtures defined in its §15. + +--- + +## 6. Known risks & unresolved items the spec flags + +These are called out so you don't discover them mid-build: + +- **Impeccable craft ruleset is unreconciled.** The Polish/craft layer (F9) cites Impeccable's _philosophy_ — the verbatim `DESIGN.md` rules couldn't be fetched. Treat exact craft thresholds as provisional; the founder can supply the real ruleset. +- **Trust model.** Cloning a repo and running its install scripts + dev server = executing repo code inside the app. This is a stated, mitigated surface (workspace-trust prompt, `--ignore-scripts` opt-in) — implement it, don't skip it. See tech spec §6 + §16. +- **Native-module / Electron ABI, `node` PATH shim, per-worktree installs, credential-helper mechanics, SSH-from-GUI, git-lfs** — all have specific handling in tech spec §3 + §6. These are the "fails on real machines" landmines; follow the spec precisely. +- **Open design questions** (need founder input before the noted milestone): board↔design-doc mapping (before M2); keep the no-repo "Playground" sandbox?; checkpoint granularity; landing-page proof-strip claims are targets stated as facts (validate before public traffic). See `veect-ui-gap-spec.md` §8. +- **Non-code, founder-owned:** name/domain/npm/trademark registration, design-partner recruiting, and Phase-1 validation are tracked in `founder-os-audit.md` — not your build work, but context for why some acceptance criteria reference "design partners." + +--- + +## 7. Document manifest + +| File | One line | +| ------------------------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| `README.md` | This entry point. | +| `veect-technical-spec.md` | **rev 1.2.2** — the authoritative build spec: architecture, distribution, connections, git/worktrees, adapters, AI, persistence, security, milestones, decision log. | +| `veect-design-spec-current.md` | The **built** design language + prototype/codebase spec — the monochrome ink instrument, editor anatomy, node model, AI/Polish/history UX, codegen grammar, landing. **Ground truth for visuals.** | +| `veect-ui-gap-spec.md` | The **work order** for UI not yet built — new surfaces (connect/publish/environment), editor deltas, the seams→subsystems wiring table, per-surface state/error catalog, build order. | +| `design-brief-veect.md` | UX **intent** — north star, opinionated principles, personas, journeys, the 6 signature moments, voice, accessibility, the Craft/Impeccable checklist. | +| `design-app-prd.md` | Product **scope** — the wedge, F1–F10 features with acceptance criteria, the load-bearing out-of-scope list, success metrics, the validation gate. | +| `company-context.md` | **Strategy** — problem, positioning (April Dunford), competitive frame, North Star Metric, riskiest assumptions, the naming decision, all pivots. | +| `founder-os-audit.md` | **Status** — Founder OS phase-by-phase: what's solid (product/tech), what's missing (validation, business model), and the recommended sequence. | + +--- + +_Build the invariants first and never break them; inherit the editor; follow the tech spec precisely on the "real machines" details; implement the design in the ink language. When a document disagrees with another, use the authority table in §2. Good building._ diff --git a/docs/product/company-context.md b/docs/product/company-context.md new file mode 100644 index 0000000..d279ca7 --- /dev/null +++ b/docs/product/company-context.md @@ -0,0 +1,131 @@ +# Company Context — Veect + +_Living strategy doc · Founder OS · last updated 2026-07-10_ + +## ✅ NAME DECIDED (2026-07-10): **Veect** + +Pronounced **VEEKT** (rhymes with _piqued_). Coined vessel — unclaimed sound, clean searches, veect.com + veect.ai confirmed available at decision time. **Brand mark (as shipped):** the lowercase `veect` wordmark closed by a **square ink terminal** ("the vector point") — no pictorial mark; design language = the monochrome ink instrument (see `veect-design-spec-current.md`). Chosen over finalists Weef, Vez, Gesso, Jig, Bezier after an 8-territory, ~150-candidate search with per-name conflict verification. + +- Registered/actioned by founder: veect.com, veect.ai. **Still open 🔴:** veect.dev, npm `veect` + org, GitHub org, X handle, EUIPO/USPTO knockout (classes 9/42; assess **Vectr** adjacency — vectr.com, an active vector-graphics editor), counsel pass before incorporating. Entity name suggestion: _Veect Labs d.o.o._ + +--- + +## ⚡ PIVOT (2026-07-10): repo-native distribution — **rev 1.2: standalone app, remote-first** + +Veect is a **standalone design application** (desktop, bundled runtime — no system Node needed; plus a **Docker image** for team/self-host/CI) that **connects to a repository**: GitHub (device-flow), any git URL, or a local checkout. One `veect.config.json` in the repo points at the component folders (a visual wizard writes it if absent). Each design project auto-creates a **git worktree + branch** (`veect/`, kept in app-managed workspaces — the user's repo is never touched); data lives in local **SQLite** plus a canonical `design.veect.json` committed on the branch; **Publish** pushes the branch and hands the designer a PR link. The npm-installed-in-repo package (Storybook-style) is a **later distribution** on the same core. Full spec: `veect-technical-spec.md` (rev 1.2). + +**Why this is stronger:** + +- The **mapping problem dissolves** — the canvas renders the repo's _actual_ components via the host's own toolchain, so exported code imports the real library by construction. The old red-team's #1 gap (engineer's merge bar) is solved structurally. 🟢 +- **GTM flips to a Storybook-like bottom-up dev-tool motion** — the developer installs it, then invites the designer in. This sidesteps much of A2 (designers adopting a new canvas) by making the dev the champion. +- Purpose sharpened (founder's words): _bring designers closer to developers so they work on prototypes directly on the codebase, with the components and context the codebase actually holds._ + +**What it changes / adds:** + +- **Riskiest assumption A5 — materially weakened by rev 1.2 🟡:** the standalone app bundles the Node runtime, clones the repo itself, installs dependencies itself, and manages env values in an encrypted local store — the designer no longer needs a dev environment, only **git installed + repo access + (for full-fidelity preview) env values**. Residual friction to validate: getting repo access granted, and apps whose previews need real secrets/backends. GTM note: the designer can now **self-serve** with read access — the developer's moment shifts from "install it for me" to "review my PR," which is a stronger wedge into the team. +- **Competitor frame shifts 🟡:** nearest neighbors are now **Onlook** ("Cursor for designers", edits real local code), **Storybook (+AI)** as the incumbent in-repo component tool, and Subframe. Veect's distinction: _component-registry canvas + project-as-worktree + constrained AI + designer-grade UX_, composing **new** designs from the real system (vs. Onlook editing existing pages; vs. Storybook documenting components rather than composing with them). +- **Business model note 🔴:** this distribution begs **open-core** (OSS/source-available tool → paid team/cloud layer: hosted previews, design sync, AI credits, dashboards — the Storybook→Chromatic analogy). Decide before launch; not blocking the build. +- Superseded from the SaaS PRD: F1 token-file import (tokens now read from the repo), F2 component _mapping_ (components are real by construction), F8 auth/cloud projects. The design brief's UI/UX (canvas, tokens panel, AI ghost layer, refusal, polish) carries over intact. + +_Locked with founder: AI compose in v1 (BYO Anthropic key) · full Next.js support (managed `next dev` adapter) · SQLite + JSON-in-branch hybrid persistence._ + +**Asset status (2026-07-10):** an **interactive editor prototype, landing page, and React 18/TS codebase exist** (`veect-design-spec-current.md` is their spec; React Flow board substrate, zustand store, two-way TSX grammar, responsive view clusters, constrained-AI UX, Polish, history — all built). The remaining product surface is the repo-native layer — connect/publish/environment — specified in `veect-ui-gap-spec.md`. + +--- + +_Status: Phases 1–5 **compressed** at the founder's request to jump to Phase 6. Confidence tags: 🟢 verified · 🟡 reasoned · 🔴 assumed / needs validation._ + +> Name is decided (see header). Trademark counsel pass remains the one open naming item. 🔴→🟡 + +--- + +## 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, +- **Veect 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 Veect-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. diff --git a/docs/product/design-app-prd.md b/docs/product/design-app-prd.md new file mode 100644 index 0000000..841ca5e --- /dev/null +++ b/docs/product/design-app-prd.md @@ -0,0 +1,205 @@ +# 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/` 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. diff --git a/docs/product/design-brief-veect.md b/docs/product/design-brief-veect.md new file mode 100644 index 0000000..9a27d12 --- /dev/null +++ b/docs/product/design-brief-veect.md @@ -0,0 +1,281 @@ +# 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._ diff --git a/docs/product/founder-os-audit.md b/docs/product/founder-os-audit.md new file mode 100644 index 0000000..0c66aee --- /dev/null +++ b/docs/product/founder-os-audit.md @@ -0,0 +1,40 @@ +# Veect — Founder OS Full-Project Audit + +_Founder OS phase sweep · 2026-07-10 · requested by founder ("make sure we are not missing something")_ +_Verdict up front: **the build is ahead of the validation.** Phases 6–7 are excellent and twice red-teamed; Phase 1's exit gate has never been cleared and Phase 5 (business model) doesn't exist. Neither blocks the M0 build — both block launch and fundraising._ + +## Phase-by-phase status + +| # | Phase | Status | What exists | What's missing | +| --- | ------------------ | ------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| 1 | Idea Validation | 🔴 **GATE OPEN** | Strong secondary evidence (92% handoff pain, Figma Make complaints, market conceding the DS-fidelity gap) 🟢; assumptions mapped A1–A5 | **Zero primary validation run.** V1 concierge-PRs, V2 mock task test, V3 fake-door, V5 interviews — all designed (PRD §13, with kill criteria), none executed. A1 (designers want code) and A4 (wedge unowned) still 🔴 | +| 2 | Market Research | 🟡 compressed | Competitive frame (v0/Lovable/Bolt/Figma Make/Subframe/Onlook/Storybook) from knowledge; naming hunt incidentally proved the space is being funded monthly (Legato $7M, Riff €14M — _vibe-coding adjacents_) | Deep teardown (owed for A4, esp. **Onlook + Subframe + Storybook-AI**); TAM/SAM/SOM never computed (research agents were declined) — needed for fundraising, not for building | +| 3 | Customer Discovery | 🟡 compressed | Personas Maya/Devon (secondary-sourced), JTBD ×4, buying committee sketch | No primary interviews; buying committee unvalidated (esp. security veto vs. the new "app clones your repo + device-flow token" model — **rev 1.2 makes discovery MORE urgent**: will enterprises allow it?) | +| 4 | Product Strategy | 🟢 solid | Dunford positioning, system+craft wedge, NSM (weekly shipped screens), differentiation vs all clusters | Roadmap beyond v1 (light); category narrative for launch | +| 5 | Business Model | 🔴 **MISSING** | One deferred note ("open-core, Storybook→Chromatic analogy") | **Nothing modeled.** Rev 1.2 made this load-bearing: standalone app + Docker forces the licensing/monetization decision (OSS core? free app + paid team features? Docker = paid tier?). "Build source-available" is in the spec on an assumption. Pricing, value metric, unit economics: absent | +| 6 | MVP Definition | 🟢 done | PRD v2 + pivot notes; scope discipline held through two pivots; out-of-scope list load-bearing | PRD partially superseded by spec (by design); refresh after M4 reality | +| 7 | Technical Planning | 🟢 done, twice red-teamed | Spec rev 1.2.1: standalone+Docker, remote-first connections, worktrees, adapters, AI, milestones M0–M7 with acceptance | **Impeccable ruleset still unreconciled** (F9/craft layer cites philosophy, not the verbatim DESIGN.md — fetch was blocked); fixtures to build | +| 8 | Go-to-Market | 🟡 head start | Positioning exists (P4) **and a full landing page is BUILT** (`Veect Landing.dc.html` — hero, proof strip, wedge, refusal demo, Polish demo) | Waitlist capture + analytics on the landing → **the V3 fake-door test is now nearly free**; launch plan, channel choice. ⚠️ The proof strip states targets (`0 unregistered / <10% LOC / <20 min`) as facts — validate or soften before public traffic | +| 9 | Growth | ⏳ correctly idle | NSM + activation metric defined | Post-launch phase; event taxonomy worth sketching before M4 ships telemetry-free (v1 has no telemetry — deliberate; revisit) | +| 10 | Customer Success | ⏳ correctly idle | — | Post-launch | +| 11 | Product Evolution | ⏳ correctly idle | Feature-test discipline documented in Founder OS | Post-launch | + +## Cross-cutting open items (the loose threads) + +1. **Naming/legal:** veect.com + .ai secured ✅ · veect.dev / npm `veect` + org / GitHub org / X handle — **register today** · EUIPO+USPTO knockout (watch **Vectr**) · counsel pass · entity formation (Veect Labs d.o.o.) + IP assignment **before any collaborator or coding-agent-generated code ships publicly**. +2. **Design partners:** V1 concierge-PRs and later M4 acceptance both need **~5 real teams with real repos**. Recruiting them is the longest-lead validation item — start now. +3. **Design brief 🔴s** (carried, unresolved): A1 code-surface framing (export-proof vs. code-workspace), fidelity labels ("production-grade/prototype-grade") to validate with engineers, Impeccable reconciliation, plus **new screens** (Connect Repository, Publish, Environment) added in rev 1.2 — the design agent should get the updated brief before building those flows. +4. **Security review posture:** rev 1.2's trust model (app executes repo code; device-flow tokens; env secrets) will face enterprise security questions — a one-page security FAQ is cheap insurance and doubles as marketing to Devon. +5. **Prototype ↔ brief drift: RESOLVED (2026-07-10)** — the prototype's design spec is stored as ground truth (`veect-design-spec-current.md`), the brief defers to it on art direction, the tech spec (rev 1.2.2) adopts its innovations (multi-view frames, bidirectional grammar), and the remaining UI work is specified in `veect-ui-gap-spec.md`. + +## Recommended sequence (next ~4 weeks) + +1. **Today:** registrations (npm/GitHub/X/veect.dev) + trademark knockout started + entity/counsel scheduled. +2. **This week:** hand spec rev 1.2.1 + design brief to the coding agent → **M0**. In parallel, start design-partner recruiting (5 teams). +3. **Weeks 1–2 (parallel with build):** run the validation gate — V1 concierge-PRs (no product needed), V3 fake-door landing page (= GTM start), 10 discovery interviews probing A1/A3 **and the rev 1.2 trust question** ("would your org connect this to your repo?"). +4. **Week 2–3:** Phase 5 sprint with me — licensing/open-core decision + pricing model + unit-economics skeleton. Blocks launch posture and any fundraising narrative; does not block the build. +5. **Week 3–4:** competitive teardown (Onlook/Subframe/Storybook-AI) to harden A4; reconcile Impeccable rules into F9; refresh design brief 🔴s with validation data. + +## Exit-gate summary + +Phase 6 ✅ · Phase 7 ✅ · Phase 4 ✅(light) · **Phase 1 ❌ — the discipline line: V1's kill criteria (≥3/5 PRs merged with <10% LOC changed) is the go/no-go for treating Veect as validated rather than believed** · Phase 5 ❌ — schedule the sprint · Phases 2–3 🟡 — upgrade opportunistically · 8 starts via the fake-door · 9–11 correctly parked. diff --git a/docs/product/veect-design-spec-current.md b/docs/product/veect-design-spec-current.md new file mode 100644 index 0000000..4e44e40 --- /dev/null +++ b/docs/product/veect-design-spec-current.md @@ -0,0 +1,267 @@ +# Veect — Product & Design Specification + +_v1.0 · July 2026 · covers `Veect.dc.html` (interactive prototype), `Veect Landing.dc.html`, and `veect-codebase/` (React 18 · TypeScript strict · Tailwind · shadcn-style)_ +_[Stored verbatim as project ground truth for the current design/prototype — founder-provided 2026-07-10. Companion: `veect-ui-gap-spec.md` for what is NOT yet in this design.]_ + +--- + +## 1. Product + +**Veect is a design-system-native canvas.** A designer brings their own tokens and +components; Veect composes screens from _only_ that system and exports production React +that imports their real library. The three invariants everything hangs on: + +1. **One runtime** — canvas, preview, isolation and export render the same tree through + the same renderer. No "roughly how it'll look." +2. **0 unregistered elements** — AI output is whitelist-sanitized against the component + registry; anything outside it is refused, never faked. +3. **Deterministic code** — same tree → same code, every time. Export imports the + customer's library (`@solstice/ui` in the demo), never inlined clones. + Demo fiction: the customer is **Solstice** (warm team-scheduling brand), with designer + Maya (owner) and design engineer Devon (reviewer, owns the merge veto). + +--- + +## 2. Brand & design language + +### 2.1 Logo + +Typographic wordmark: lowercase **`veect`**, Instrument Sans 600, letter-spacing −0.035em, +line-height 1, closed by a **square ink terminal** (the "vector point") sized ≈ 0.28 × font +size, baseline-aligned, `currentColor`. No pictorial mark. Codebase atom: `Logo size={n}`. + +### 2.2 Color — chrome tokens + +Color belongs to the customer's canvas; the instrument is monochrome. The accent IS the ink. +| Token | Light (default file value) | Dark | +|---|---|---| +| `--bg` / `--panel` | `#FCFCFB` | `#0E0E0D` | +| `--raised` / `--chip` | `#FFFFFF` / `#F4F3F0` | `#161615` | +| `--line` / `--line2` | `#E7E6E2` / `#CFCEC8` | `#262624` / `#3A3A37` | +| `--t1` / `--t2` / `--t3` | `#161513` / `#63615B` / `#9A978F` | `#F4F4F2` / `#A6A6A1` / `#73736E` | +| `--iris` (accent = ink) | `#161513` | `#F4F4F2` | +| `--iris-dim` | `rgba(22,21,19,.06)` | `rgba(244,244,242,.09)` | +| `--btn-ink` (text on accent) | `#FFFFFF` | `#0E0E0D` | +| `--warn` / `--err` / `--live` | `#9A7B3F` / `#B05E5E` / `#5B7F5E` | `#C2A36B` / `#C97070` / `#8BA88E` | +Amber (`--warn`) is reserved for AI-scope affordances (pick outline, scope chips, draw +strokes) and the unmapped-component warning. The prototype ships **dark by default** +(user preference); the codebase mirrors this (`index.html data-theme="dark"`). + +### 2.3 Surfaces & elevation + +Flat. Radius **2px everywhere** in chrome (customer canvas keeps its own `radius-md` +token). No floating shadows — separation is a hairline: popovers/menus use +`box-shadow: 0 0 0 1px var(--line2)`. Canvas frames sit on the board with a 1px +`rgba(0,0,0,.14)` ring. + +### 2.4 Typography + +- **UI**: Instrument Sans 400/500/600 — 13px base, 11–12.5px controls. +- **Labels**: Fragment Mono, 9–11px, uppercase, letter-spacing .06–.14em — all section + headers, metadata, and "engraved" captions. +- **Customer content**: the system's own font (demo: Bricolage Grotesque) — never used + for chrome. +- Scale discipline: chrome text never below 8px (activity-bar labels), canvas display + type responsive per view (§6). + +### 2.5 Iconography + +Hand-drawn 16-grid SVG, 1.5px stroke, round caps, `currentColor`. Set: chat (spark), +layers, library, tokens, history, inspect (sliders), polish (spark-4), code (chevrons), +pick (crosshair), draw (pen), eye / eye-off, mic. No icon fonts, no emoji. + +### 2.6 Motion + +120–450ms, `cubic-bezier(.2,.7,.2,1)`. Keyframes: `riseIn`, `popIn`, `fadeIn`, +`lineFlash` (code sync), `nodePulse` (token ripple). Everything respects +`prefers-reduced-motion`. + +### 2.7 Voice + +Plainspoken, no hype, no emoji. Refusals teach ("You don't have a component for this +yet"), fixes explain the _why_ in the user's own tokens. + +--- + +## 3. Screens + +| Screen | Purpose | Key elements | +| ----------------- | -------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| **Sign in** | design-partner entry | email → straight through; SSO stubs; provisioning note | +| **Home** | projects + systems | project grid (1 live + placeholders), search, Solstice system card (ramp, open tokens, re-import), "bring a design system" | +| **Onboarding** | the re-theme reveal | two paths: paste tokens (parse → contrast checks) or 5-token quick path (brand, neutrals, radius, type, spacing) with live mini-kit; ends "Bring it to life →" | +| **Editor** | the canvas (§4–5) | | +| **Settings** | system + governance | token source card, component mappings ("merge bar"), craft standard picker, export defaults, plan, delete | +| **Profile** | account | identity card, theme preference, workspace members (Maya/Devon), keyboard map, sign out | +| **System update** | US-6 re-import | paste → diff (CHANGED/ADDED/REMOVED + swatches) → impact line → apply-with-undo → ripple | +| **Landing** | marketing (§10) | | + +Navigation: project dropdown (top-left) is the hub — all projects, new project, export, +copy TSX, import tokens, upload component, settings, profile, onboarding demo. Escape and +outside-click dismiss. Avatar → Profile everywhere. + +--- + +## 4. Editor anatomy + +### 4.1 Top bar (36px) + +Wordmark · project dropdown · `✓ saved` · **view switcher** (centered: Desktop / Tablet / +Mobile / ⧉ All) · Preview · **Export** (primary) · theme toggle ◐ · avatar. + +### 4.2 Activity bar (44px, fixed left) + +Toggleable icon+label buttons, grouped by dividers: +`✦ Chat` │ `Layers · Library · Tokens · History` │ `Inspect · Polish` │ `Code`. +Click = open that panel/tab; click again = collapse. Active = `--iris-dim` chip. At +overlay widths (<1000px) panels are mutually exclusive and float over the board. + +### 4.3 Panels (resizable via edge-drag; « » collapse chevrons) + +- **Chat** (284px) — vertical AI thread (§7): bubbles, proposal Accept/Discard inline, + refusal actions, model picker (haiku/sonnet), image attachments, scope chip. +- **Board rail** (216px) — LAYERS: collapsible tree (caret-expand, double-click reveal), + per-frame **variant chips** (§6); LIBRARY: 10-component base kit with mapping badges, + isolation ◉, add +, drag-to-canvas, patterns, custom `.tsx/.jsx` upload; TOKENS: brand + ramp + curated swatches + hex, radius stepper, type picker, neutrals, spacing base — + every change ripples live (`nodePulse`); HISTORY: labelled steps, restore cursor (§8). +- **Inspector** (244px) — selection card, ✦ Edit-with-AI (scoped), content/variant/weight/ + tone/size controls, gap/pad steppers (system-scale steps), Tailwind utilities + (collapsible; w/h/max-w/shadow/opacity selects + custom string), token bindings, + FRAME settings (name, width ±80, **active view** line). Polish tab: §7.3. +- **Code** (380px, dark `#161311` always) — file segs (`{Frame}.tsx` / `tokens.css`), + line-numbered TSX with click-line→select-node sync and `lineFlash` on change; **edit + mode** (toggle → syntax-highlighted textarea → apply parses back via the generated + grammar, line-referenced errors); footer `prettier ✓ tsc ✓`. +- **Isolation** (over board) — variant × state grid per component on a paper stage, real + runtime, Esc exits. + +### 4.4 Board + +Infinite surface: scroll pans, ⌘/ctrl-scroll zooms at cursor, two-finger pinch, drag +empty board pans, background click deselects. Zoom cluster (− % + · fit · + frame · +board backdrop toggle). Frames render as **view clusters** (§6) with a draggable name +tab (`Home · 34 nodes · one codebase`). Selection = ink ring; hover = neutral ring; +AI-target = amber ring. Tool pill (bottom-center): **Pick (V) · Draw (D) · Overlays (O) +· Voice (stub)** — icon buttons with key hints. + +### 4.5 Preview + +Full-screen overlay, real hover/focus states, active view's width fills the screen +(mobile/tablet render as a centered device sheet). + +### 4.6 Keyboard + +`⌘K` commands · `✦` focus composer · `⌘Z/⇧⌘Z` undo/redo · `⌘0` fit · `⌘1` 100% · +`⌘±` zoom · `V/D/O` tools · `⌫` delete selection · `Esc` dismiss cascade (menu → modes → +refusal → proposal → scope → selection). + +--- + +## 5. Canvas node model + +`board → frame[] → (stack | card | heading | text | button | badge | input | avatar | +image | divider | custom)*`. Layout via `dir/gap/pad/padX/padY/align/justify/maxW/bg` +(4px scale). Content props per type; `tw` bag for curated utility classes. Frames carry +`x/y/w/views/view`. IDs are stable; comment anchors and code-line mapping key off them. + +--- + +## 6. Responsive variants — one tree, three widths + +- Views: **desktop** (frame's own `w`, default 1280) · **tablet 768** · **mobile 390**. +- A frame renders every enabled view side by side (120px gap) — same children, so an + edit anywhere updates every view. Captions (`tablet · 768`) label each block; the + **active view** (drives preview, code, export width) is ink-highlighted. +- Renderer responds to view width: row-stacks wrap ≤900, cards get flex-basis 240, + display type steps down (xl: 54 → 44 → 34px) ≤900/≤480. +- Switcher semantics: Desktop/Tablet/Mobile = show only that view + make it active; + **⧉ All** = all three. Layer chips: label click = select frame + make active (opens + frame settings); eye icon = show/hide that view (min 1). Cluster growth shifts + right-neighbors by the width delta — clusters never collide. + +--- + +## 7. AI, constrained + +### 7.1 Compose + +Prompt → system prompt embeds the registry JSON (types + allowed props) + brand voice +rules (one primary CTA per group, 4px spacing, no lorem). Response is sanitized: unknown +type ⇒ **refusal**, numeric props clamped to scale, strings capped. Result stages as a +**dashed ghost** on the active frame — Accept commits (history label `AI compose — +accepted`), Discard drops. + +### 7.2 Scoped edits + +Pick tool (V) or Inspector → "✦ Edit with AI": amber target ring + composer scope chip +(`h1 · Scheduling…`), inline bubble at cursor, type-aware quick actions (punchier / +shorter / demote / colorize ×n…). Edit proposals ghost beside the original and swap in +on Accept. + +### 7.3 Polish (the Impeccable pass) + +Ranked issues (HIGH/MED/LOW): weak hierarchy (display heading at 400), competing primary +CTAs, off-scale gaps (`gap-[18px]` drift), uneven sibling padding, AA contrast failures +(with measured ratios). Each: title — _why it matters_ — one-click fix **in the user's +tokens**. Fix-all; empty state "Impeccable. Nothing to fix." Craft standard selectable +in Settings (Veect default / Impeccable / custom DESIGN.md). + +### 7.4 Refusal protocol + +Off-registry ask (3D globe, video, charts…) ⇒ "You don't have a component for this yet" + +- reason + **Compose from primitives** / Not now. Never generic markup. Models: Haiku 4.5 + default, Sonnet 4.5 option; offline heuristics keep demos deterministic. + +--- + +## 8. History + +Every mutation is a labelled step (`Add Button`, `Polish — Two primary actions`, +`View → tablet`, `AI edit — accepted`…). History tab lists steps newest-first with age. +Clicking restores that state and sets a **cursor**: newer steps dim (35%); the next +meaningful edit truncates the dimmed trail. `⌘Z` walks steps; redo restores. + +--- + +## 9. Code generation & round-trip + +| Canvas | Export | Notes | +| ------------- | ------------------------------------- | --------------------------------------- | +| heading/text | `/

` + Tailwind | size/weight/tone classes, neutral ramp | +| button | `