# 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/<slug>`) 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._
