# 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  | `<h1–h4>/<p>` + Tailwind              | size/weight/tone classes, neutral ramp  |
| button        | `<Button kind size>`                  | `variant→kind` rename shown in mappings |
| card          | `<Card>`                              | pad/gap classes                         |
| input         | `<TextField label placeholder />`     |                                         |
| avatar        | `<Avatar name />`                     |                                         |
| badge         | `@veect/base-kit` fallback + TODO     | until mapped — "map now" chip           |
| stack         | `<div>/<nav>` flex classes            |                                         |
| image/divider | semantic HTML                         |                                         |
| custom upload | real `import X from "./components/…"` | props sniffed from source               |

`tokens.css` generates from the live system. The **edit-mode parser** accepts exactly
this grammar back (line-referenced errors otherwise) — the grammar runs both ways.
Export dialog: honest file tree, `npm i && npm run dev`, copy `{Frame}.tsx`, fidelity
badge. Guarantee line: _deterministic — same tree, same code_.

---

## 10. Landing page

Carbon-mono flat (same language). Sections: fixed nav (scroll-spy underline, blur on
scroll) · Hero ("Your system in. Real React out.", masked line reveal, magnetic CTAs,
live 5-token kit demo with 3D tilt) · proof strip (0 unregistered / <10% LOC / <20 min)
· three-pillar wedge · graceful-refusal chat (typewriter) · code panel (staggered lines)
· Polish demo (run/undo on a Solstice card) · CTA. Left ruler tracks scroll. GSAP +
ScrollTrigger, all reduced-motion-safe.

---

## 11. Codebase map & seams

See `veect-codebase/README.md` for the atomic-design map (config / engine / store /
hooks / ui / atoms / molecules / organisms / templates / pages), product invariants,
and **Handoff notes** — the deliberate seams: model bridge (`engine/ai.ts#complete`),
export zip, placeholder projects, auth, persistence. Board substrate: React Flow
(`@xyflow/react`, MIT) — frames as custom nodes, zustand as single source of truth.
Pre-flight: `npm run typecheck && npm run lint`.
