# Veect — UI & Design Gap Specification _The work order for what the current design does NOT yet cover. 2026-07-10._ _Ground truth for what exists: `veect-design-spec-current.md` (v1.0 — prototype, landing, codebase). Target: `veect-technical-spec.md` rev 1.2.1. Design language for everything below: the **ink instrument** (§2 of the design spec) — do not invent new colors or radii; the only new pattern this gap requires is specified in §6._ _Audience: the design agent (screens, states, motion) and the coding agent (behavior, integration seams). Every item carries its spec reference and milestone._ --- ## 0. The headline shift the UI hasn't made The prototype is a beautiful **SaaS-canvas fiction**: tokens arrive by _paste_, components are a demo kit + `.tsx` upload, output leaves by _export zip_. The shipped product (spec rev 1.2.1) is **repo-native**: tokens and components are _discovered from a connected repository_, projects _are_ git branches in app-managed worktrees, and output leaves by _Checkpoint → Publish → PR link_. Almost everything in this document derives from that one shift. The editor itself — canvas, panels, AI, Polish, history, view clusters, code panel — is largely **done and ahead of spec**; what's missing is the shell around it and the truth underneath it. **Vocabulary changes that ripple through all chrome:** "Export" → **Checkpoint** (commit to the branch) and **Publish** (push + PR link) · "project" = a branch (`veect/`) in a **workspace** (a connected repo) · "import tokens / upload component" → "connect repository / rescan". The export-zip dialog survives only inside Docker/CI contexts. --- ## 1. Already done — do not redesign Editor anatomy (top bar, activity bar, panels, board, tool pill, keyboard cascade) · view clusters & responsive variants · constrained AI (compose ghosts, scoped edits, refusal protocol, model picker, attachments) · Polish with craft-standard picker · history with restore cursor · code panel incl. **edit-mode round-trip grammar** · isolation mode · token editor with live ripple · System-update diff screen · Settings/Profile shells · Sign-in shell · Landing page. These are inherited into the product as-is; the technical spec has been amended to adopt the prototype's innovations (multi-view frames, bidirectional grammar) rather than the reverse. --- ## 2. New surfaces to design & build ### 2.1 Connect Repository — replaces token-paste onboarding as the primary path · **M4** · spec §6 The single most important missing flow; it carries first-run trust. - **Source chooser:** three calm cards — **GitHub** · **Git URL** · **Local folder**. Fragment-mono captions; no provider logos larger than 16-grid icons. - **GitHub device flow:** large copyable code, "approve in browser" link, waiting state (subtle pulse, no spinner), retry; **org-wall state** — auth succeeded but repo 404s → guidance card ("your org must authorize Veect — here's the link / ask an admin"), never a dead end. - **Git URL path:** URL field + auth method (token / SSH-agent); SSH first-connect shows a **host-fingerprint confirm** (mono, ink, Accept/Reject); "no agent reachable" vs "agent has no identities" are distinct states with distinct fixes. - **Local folder:** native picker; instant attach. - **Workspace-trust prompt (required, before first install):** plain-language card — "Veect will run this repository's install scripts and dev server on your machine. Only connect repositories you trust." Options: Trust & continue · **Install without scripts** (per-repo toggle, persisted) · Cancel. Voice: factual, not scary. - **Clone + install progress:** staged, honest, minutes-long (see §6 pattern): `cloning → installing (pnpm) → reading components → starting preview`. Each stage with elapsed time; cancellable; failure surfaces the doctor playbook string inline. - **Config wizard (repo has no `veect.config.json`):** repo file-tree browser (mono, indent guides), multi-select component folders, `appDir` picker for monorepos, detected framework + tokens shown as confirm chips; footer note: "This config will ride your first published branch." Writes workspace-local config until merged. - **Read-only connect:** allowed; persistent quiet banner "Design and checkpoint freely — Publish needs write access" + patch-export escape hatch in the project menu. - **States:** choose / device-wait / org-wall / auth-fail (specific) / fingerprint / trust / cloning / installing / scanning / wizard / env-needed (→ §2.3) / success — success is the **re-theme reveal recast**: components and tokens stream in FROM the repo and the mini-kit re-themes (Signature Moment #1, now earned from a clone instead of a paste). ### 2.2 Publish & branch status · **M3–M4** · spec §10 - **Top bar:** `Export` primary button becomes two verbs: **Checkpoint** (secondary) · **Publish** (primary). `✓ saved` stays (autosave ≠ checkpoint — the distinction needs a hover explainer). - **Branch card** (project dropdown + a status strip in the board's empty corner): `veect/checkout-flow · 4 checkpoints · 2 behind base` — mono, engraved. - **Publish flow:** progress → success = **PR deep-link as the hero action** ("Open pull request →"), copyable branch name; this is Signature Moment #4 (the clean handoff) relocated from the zip dialog. - **Failure states (each with its playbook string):** no write access (pre-detected at connect; button pre-disabled with reason) · branch-name policy rejected (offer prefix change) · signed-commits required (explain, link out) · commit-message policy (offer template config). - **Update from base:** staleness chip → one-click merge; **conflict state is read-only** — file list + "ask a developer" guidance card; never a merge editor. - **Unpublished-work nudge:** quiet chip after N checkpoints without publish; never a modal. ### 2.3 Environment & connection health · **M3 (local import) / M4 (full)** · spec §6 - **Env panel** (Settings section + first-run interstitial when detected): key list from `.env.example`/turbo/t3-env/next.config; masked value fields; "stays on this machine, encrypted" caption (Fragment Mono); per-key source badge. Local mode: "Import from your checkout's .env.local" one-click + staleness note. - **Adapter-crash translation:** the board's preview error state gets a human sentence ("Preview needs `DATABASE_URL` — add it in Environment") with a jump link — never a raw stack. - **Connection card:** provider, access level (read/write chip), last fetch, re-auth inline when token expires. - **Doctor strip:** git version, disk per workspace, adapter health — pass/warn/fail glyphs (ink/warn/err), one-line fixes; lives in Settings, surfaces as a toast only on failure. ### 2.4 Home, reworked: workspaces → projects → designs · **M4** · spec §2 - Hierarchy: **Workspace** (repo card: host icon, `owner/name`, branch count, disk, last fetch) → **Projects** (branch cards with checkpoint/publish status) → open editor. - "Bring a design system" card → **"Connect a repository"**; the Solstice system card pattern becomes the workspace card. - Keep a **Playground** entry (the current 5-token demo path, clearly labeled "no repo — sandbox") — it's the landing-page demo funnel and the only place token-paste onboarding survives. 🟡 founder-confirm. ### 2.5 Desktop shell surfaces · **M0–M7** · spec §3 - **First-run:** git-missing walk-through (per-OS instructions, re-check button); theme choice honored from OS. - **Settings additions:** AI key entry (masked, safeStorage caption, "test key" action) · vendored-PM info line · workspace disk usage + archive/cleanup actions · update channel + "restart to update" (adapters drain first — show "stopping previews…" toast). - **Deep links:** `veect://` open-workspace/project handling. - **Menu/tray:** minimal native menu (About, Check for updates, Quit) — everything else stays in-app. ### 2.6 Docker / headless sign-in · **M7** · spec §13 One page: token field (from `VEECT_TOKEN`), ink wordmark, no marketing. Session cookie after success. Device-flow codes render in-browser for container use. A "you're on a shared instance — publishes author as the stored identity" caption (multi-seat honesty). --- ## 3. Existing surfaces that must evolve | Surface | Change | Milestone · spec ref | | ------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------- | | **Library panel** | Demo kit + upload → **discovered components from the repo**: scan progress skeletons; per-file failure badges (⚠ + tooltip, never abort); `client / server / universal` environment badges (mono chips); `@deprecated` + `@veect-ignore` states; mapping badges retire ("map now" survives only for base-kit fallbacks in Playground). Custom `.tsx` upload survives only in Playground. | M1 · §7 | | **Server components on canvas** | Selectable/movable, **internals non-editable** — quiet engraved badge "server component — edits its props, not its insides"; settle shimmer (≤1s) on prop change instead of instant re-render. | M5 · §9 | | **Adapter status** | Board-level states: `starting preview…` (staged), `preview crashed — restarting (2/5)` with log-tail drawer, `restart failed` → doctor playbook. Never a blank board. | M1 · §9 | | **AI panel** | Add **provenance chips** on proposals ("built from Card ×3, Button — your library"); **"what was sent" disclosure** (collapsible mono block — privacy trust); **key-missing state** (setup hint + Settings link); model picker stays. | M6 · §14 | | **Checkpoint parity failure** | New blocking state on Checkpoint: "Canvas and generated code differ (parity 97.2%) — this is a bug on our side; nothing was committed" + diff thumbnail + report action. Honest, self-blaming voice. | M3 · §1 | | **Code panel** | `prettier ✓ tsc ✓` footer joins **commit context** (`last checkpoint a3f21c9 · 2m`); **code-owned flip**: if the real file was hand-edited outside Veect, panel banner "This design is code-owned now — Veect won't regenerate it" + read-only lock + un-own action. Edit-mode grammar stays (adopted into spec). | M3 · §12 | | **History panel** | Steps that became git checkpoints get a **commit tick + short SHA** (mono); restore-cursor semantics unchanged; caption clarifies "history is local; checkpoints are shared." | M3 · §11 | | **System-update screen** | Keep the diff/impact/apply-with-undo UI as-is — **rewire the source** from "paste tokens" to **Update-from-base** (repo diff of tokens/components after merge). The screen you built is exactly right; only its input changes. | M4 · §6 | | **Isolation mode** | Variant × state grid derives from **discovered prop types** (literal unions) instead of the demo kit's hardcoded variants. | M1 · §7 | | **Sign-in** | Becomes app first-run (no SaaS account in v1) — identity = provider connection; the screen's shell survives as the Docker token page (§2.6). | M4/M7 | | **Export dialog** | Retires from the top bar (→ Checkpoint/Publish). Its file-tree/`npm run dev` content survives inside Playground export + Docker/CI docs. | M3 | --- ## 4. Integration seams — where the prototype meets the spec The codebase's deliberate seams (its README "Handoff notes") map 1:1 onto spec subsystems — this is the coding agent's wiring diagram: | Prototype seam | Becomes | Spec ref | | -------------------------- | ------------------------------------------------------------------------------------------------- | -------- | | `engine/ai.ts#complete` | Server AI engine (Anthropic, registry-constrained, repair loop, refusal) | §14 | | Export zip | Git engine: checkpoint transaction + publish | §10 | | Placeholder projects | Workspaces/projects from SQLite + worktrees | §2, §11 | | Auth stub | Connections (device flow / PAT / SSH) + safeStorage | §6 | | Persistence (zustand only) | SQLite autosave/revisions + `design.veect.json` write-through; zustand stays the in-session store | §11 | | Demo registry JSON | Discovery engine output (`ComponentMeta`/`TokenRegistry`) | §7 | | Offline heuristics | Retained as the record/replay eval harness + demo mode | §14/§15 | --- ## 5. Design-language extensions (the only new rules) 1. **Long-running staged progress** — the one pattern the ink language lacks (clone/install take minutes). Spec: left-aligned stage list, Fragment Mono labels, current stage in `--t1` with elapsed time, done stages get an ink tick, pending in `--t3`; a single 1px progress hairline under the list (no bars, no spinners >600ms); always cancellable; failures replace the stage line with the playbook string in `--err`. 2. **Semantic assignments for new states:** connection/live health = `--live` (unchanged) · **AI-anything stays amber** (`--warn`) — publish/PR/checkpoint actions are **ink**, never green (success = ink tick + label, per the existing language) · destructive/conflict = `--err`. 3. **Trust & security captions** are Fragment Mono engraved (same as metadata) — security posture is presented as instrument fact, not marketing. 4. **The wordmark's square ink terminal** is the only brand mark on new surfaces (Docker page, first-run, PR-success card). No new marks. --- ## 6. State & playbook string catalog (per new surface) Write these in the §2.7 voice — each error names the cause and the next action, ≤2 sentences: git missing · device-code expired · org not authorized · token expired/revoked · no write access · SSH no-agent vs no-identities · host-fingerprint changed (⚠ stern) · clone failed (auth vs network) · install failed (registry/proxy/native-module → "this dependency needs tools this machine doesn't have — use Docker mode") · scripts blocked by trust choice · env missing (named key) · adapter crash/restart/gave-up · parity failure · publish rejected (×4 classes) · behind base · merge conflict · disk pressure · update ready (adapters will restart). --- ## 7. Build order (tied to spec milestones) | Priority | Items | Unblocks | | ----------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------- | | **P0 (M0–M3)** | Checkpoint/Publish verbs in top bar · history↔checkpoint ticks · code-owned flip · parity-fail state · env local import + crash translation · adapter status states · first-run git check | Local-mode complete product | | **P1 (M4)** | Connect Repository (full §2.1) · trust prompt · Home rework · Publish flow + failure playbooks · System-update rewire · read-only mode | The flagship remote flow; design-partner onboarding | | **P2 (M1/M5/M6)** | Library discovery states · isolation from real props · server-component affordances · AI provenance + disclosure + key settings | Real-repo depth | | **P3 (M7)** | Docker sign-in · disk/cleanup · deep links · update-drain toast | Self-host + polish | --- ## 8. Open design questions (founder or validation, not the design agent) 1. **Board ↔ design mapping:** prototype = one board of frames per project; spec = multiple named designs (folders) per project. **Recommendation:** one board _is_ one design doc (frames within it = its screens); the project dropdown gains a design switcher. Decide before M2 persistence lands. 🟡 2. **Playground mode** — keep the no-repo sandbox as a permanent funnel? (Recommended yes; it's the landing demo and the only home for token-paste + base kit.) 🟡 3. **Checkpoint granularity** — every explicit Save = commit (current spec) vs. designer-chosen "milestones"? Validate with design partners in V1 interviews. 🔴 4. **Landing page claims** — the proof strip (`0 unregistered / <10% LOC / <20 min`) states our _targets_ as facts; before public launch, either validate them (Phase 1 gate) or soften copy. 🔴 (flagged in `founder-os-audit.md`) --- _End of gap spec. Pair with `veect-design-spec-current.md` (what exists) and `veect-technical-spec.md` rev 1.2.1 (how it must behave). The design agent should deliver §2 screens with full state sets in the ink language; the coding agent wires §4 seams in milestone order._