Using One Connect

Designer and mocks

Describe an interface in one sentence. Your design agent proposes screens on a canvas, you keep or discard each proposal, and a frozen release is reviewed against your project's versioned design system before it goes to engineering.

Start a design#

Open Designer (/designer) from the command palette. The start screen asks one thing: What are you designing?

Describe the interface in a sentence.
Pick the Design agent. Relay and coordinator-only agents are excluded, because the studio never asks you to work in another app.
Choose New prototype, or Revise existing UI and point the agent at Repository files to study (read-only).
Start designing creates a design document from your sentence and gives the agent a generate job.

Starters and Recent designs sit below the box.

The canvas#

A design opens on its own canvas (/designer?document=<id>) with every screen side by side at the chosen viewport: phone, tablet or desktop.

Select a layer to open a small panel with the controls that matter for that kind of layer; everything else is behind Layout and more. Every change is one undo step.
Play runs the prototype, with its links and interactions.
The status in the top bar is one of Draft, Agent working, Needs you, Needs attention, Ready for review or Approved.
Keyboard: ⌘Z and ⇧⌘Z undo and redo, ⌘D duplicates, Delete removes, Escape closes a sheet or clears the selection.
To make something reusable, select a layer and choose Make reusable; it becomes a component.

The ask bar#

The ask bar is the only way to talk to the agent. A request becomes a focused job scoped to the selected layers, or to the whole design. Progress, the agent's questions (answered in place) and its transcript unfold above the box.

The agent answers with proposals: typed design operations against the exact version you were looking at. Each proposal lands on the canvas next to the screens it changes, with Keep and Discard. Nothing is applied until you keep it.

Designs are structured documents, not HTML. Agents read them with get_design_document and get_design_components, check them with validate_design_document, and propose with propose_design_changes. Proposals can add, move, update and remove nodes and screens, set tokens and components, and wire interactions; they can never contain code, HTML, CSS or URLs, and an agent can never apply or approve its own proposal.

The project design system#

Every project has a versioned design system contract. The Design system sheet shows this design's foundations (colours, type, spacing and shape, density, motion) and publishes them as the project system; Edit the full project contract opens the complete editor. The contract holds:

Colour roles for a light and a dark palette: canvas, surfaces, text, accent, divider, focus ring, and success, warning, danger and information. Appearance chooses light, dark or both.
Typography: a system or serif-display pairing and a base size, on a fixed 1.2 scale.
Shape and density: compact or comfortable, corner radius, border width, and soft shadows or flat borders.
Layout, motion and accessibility: maximum width, navigation style, subtle or reduced motion, minimum target size and focus-ring width.
Text: component notes and rules.

Edits are an autosaved draft, never the approved contract. A live specimen renders buttons, fields, badges, tabs, a dialog, a table and the four content states from the draft, in light or dark.

Validate draft measures the draft on the daemon: errors, warnings, a SHA-256 and a field-by-field diff. Save as vN records an immutable revision for exactly that validated draft. Blocking contrast failures (body, secondary and status text, action labels, links, the focus ring and input boundaries) prevent saving. Each revision generates DESIGN.md, tokens.css, tokens.json (Design Tokens Community Group format) and a static specimen, and Versions lists every revision with diffs and downloads.

Contract drift#

Saving a new version never touches existing assignments or running work: each assignment keeps the contract revision frozen when it was created. Mocks built on an older contract show contract drift, and approvals made under the old contract become stale until a human records a drift exception or approves a revision built on the current contract.

Review and release#

The Review sheet groups what still needs attention, the evidence a release carries, your own review and the handoff to engineering.

Create a release for review. A release freezes this version, its tokens and its source, so the review is exact. Readiness blockers are listed first.
Check it. Five checklist items: responsive layout, keyboard and focus, contrast, content states, and visual and token compliance. Each records its result and its basis: static (measured from source), browser (an executed check with passed evidence on this revision) or human (you looked at it in Play). Static findings never approve anything.
Independent review. The author of a revision cannot be its only approver. Request a review from a different agent; it reads the revision with get_design_mock and submits submit_design_review with its own checklist. Its verdict is advisory.
Approve revision N. Approval needs every item to pass and no open findings. Approvals belong to exact revisions and never carry over to a later one.

Hand off to engineering#

Once a release is approved, choose a Build agent and a different Review agent, then Prepare the build workflow. One Connect prepares a workflow under Workflows whose steps cite the exact release, content hash and contract hash, with acceptance criteria for tokens, states, keyboard and focus, and phone, tablet and desktop evidence. Nothing starts until you run it. A design approval is not a passing implementation: the build goes through normal review, checks and merge.

On the canvas, a Designer artifact node attaches one finalized revision to the steps plugged into it, and shows a miniature of it. Workflow validation refuses a revision whose approval no longer holds.

Mocks#

Mocks (/mocks) is the gallery of captured revisions: static thumbnails, gate state, approved revision, stale approvals and older-contract markers, plus in-progress jobs that need attention. One artifact's view keeps the selected revision, page and viewport in the address and offers:

Compare: added, removed and changed files, a line diff and two revisions side by side.
Source: an autosaved draft per file. Saving captures a new revision. Restore this file from revision N is the undo; history is never rewritten.
Refine: a request that continues the same assignment when possible, or creates a child issue scoped to the mock folder.
Handoff bundle: a local export of the revision's exact files, a manifest with its gate, reviews, exceptions and evidence, the screenshots, the contract's DESIGN.md, tokens.css, tokens.json and specimen, and HANDOFF.md. Nothing is published or sent.

HTML mocks are captured from design/<slug>/ in an agent's worktree with register_design_mock. Capture refuses symlinks, changed files, secrets and disallowed file types, stores every file by SHA-256, and runs static findings: remote resources and network APIs, browser storage, off-palette colours and stale tokens, a missing viewport tag or language, missing pages and an invalid handoff.

Previews#

Mac app: Open interactive preview opens the revision in a separate native window with no network, no WebRTC, a non-persistent data store, navigation denial and a restrictive content security policy. Local links between pages work; anything blocked is explained.
Browser: a static layout render with scripts, handlers and links removed, in a sandboxed frame. It is labelled as a layout check, and mock code never runs there.

Skills for design work#

Design agents get pinned skills, loaded only when they apply:

upstream: Taste Skill (MIT, landing pages and redesigns only), Vercel Web Interface Guidelines (MIT), VoltAgent DESIGN.md reference analyses (MIT), and a guide for an already-installed Playwright CLI;
original One Connect skills (Apache-2.0): design-system contract, accessible product UI, responsive mocks, product UI patterns, typography and content, design-system implementation, and visual critique.

Every pinned file is verified by SHA-256 on each read. Issues labelled design, ui, mock, frontend or branding get the whole library; design-implementation and design-review get their own sets. The table is under Settings → Project and policies → Designer skills.