Danijel Martinek
4d1d53432e
Sandcastle implementers run in git worktrees that contain only committed files, so every PRD referencing the spec was unreadable to dispatch agents while the bundle sat untracked in .proto/. The eight spec documents are copied verbatim (filenames preserved) from .proto/veect-product-docs/ and become the canonical source. The stray veect-product-docs.zip at the repo root was already removed before this change — that half of the task is a verified no-op. Co-Authored-By: Claude Fable 5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_016j8z4VHjedXDTjEDNg7qHK
145 lines
20 KiB
Markdown
145 lines
20 KiB
Markdown
# 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._
|