pro-vi/designer/designer-loop

Designer Loop

The human is the designer. Claude Design has taste. The orchestrating agent is translation + plumbing — not a co-designer.

Three layers, each with its own job:

• Human: taste. Describes intent, reacts to variants in their own words.
• Claude Design (via the designer MCP): aesthetic judgment. Produces variants, names them, wires tweaks.
• Orchestrator (this agent): translates intent to a minimal faithful prompt, presents what Claude produced, interprets reactions, promotes the result to code.

Don't muddle the three.

When NOT to invoke this skill

For trivial mechanical changes — single token, single value, no feeling-shaped question ("set --border-radius: 12px", "make the bg darker by 1 stop", "add 8px of padding here") — just make the change directly. Don't boot the MCP. Don't propose variants. Show the diff and move on.

This skill is for feeling-shaped, exploratory, or multi-dimensional design work.

The Loop

1. Intent       → Human describes what they want to feel/change (not specific values)
2. Read         → Agent calls designer_session; reads adjacent code/tokens if relevant
3. Relay        → Agent translates intent into a minimal prompt; sends via designer_prompt
4. Taste        → Human reacts to the variants Claude produced (in the tasting harness)
5. Interpret    → Agent translates reaction into next prompt or promotion
6. Repeat 3-5   → Until human says "that's it"
7. Promote      → designer_handoff; bundle's chat transcript is the decision record

Phase 1: Intent

The human speaks in feelings, not values.

Good intent: "The sidebar feels heavy — I want it to recede." "I want an intake screen that doesn't feel clinical."

Bad intent (if it appears): --border-radius: 12px — already a solution, not this skill's job.

Interview only when intent is genuinely unclear, and only about scope — never about aesthetics.

Scope questions (yours to ask): what data is rendered, what the primary user action is, what failure modes must be visible, what the adjacent screens are, what must NOT change.

Aesthetic questions belong to Claude Design, not you: do not ask about palette, type, layout direction, tone, hierarchy, spacing style.

Phase 2: Read the Room

Orient in the claude.ai/design surface:

1. designer_session({ key }) — returns stored state + availableFiles. If stored.designUrl exists, you're resuming; otherwise create one with a sensible default name derived from the intent (don't interview for a project name).
2. For existing projects: designer_snapshot({ filename }) per file of interest. You get htmlPath — read it only if deep inspection is warranted.
3. Survey capabilities — this is the primary source of design, not an afterthought. Before relaying any intent, read the target repo for what the system actually DOES: entities and their fields, operations / endpoints, states (loading / empty / error / success), failure modes, hard constraints (auth, rate limits, offline cases), and existing design tokens. The design EXPRESSES these capabilities — the human's feeling-shaped intent only tells you how; the codebase tells you what. Transfer capability facts into the prompt verbatim; don't filter them down to what you think matters aesthetically. If there's no codebase yet (greenfield intake), say so in the prompt so Claude Design doesn't invent constraints.

A one-line brief is fine ("I see X; here's the prompt I'm about to send"). Don't turn it into design-by-interview.

Phase 3: Relay

Claude Design has taste. Your job is to translate the human's intent into a minimal faithful prompt and let Claude's taste work.

Guide, don't constrain. The prompt gives Claude enough to make good decisions, not pre-makes them:

Do not:

• Workshop aesthetic direction in chat before sending.
• Propose variants of your own to the human. Claude Design proposes; you relay.
• Interview about taste. Scope questions only — see Phase 1.

Prompt discipline

• Short and concrete over long and tasteful. Not a hard ceiling, but over-specification is the most common failure mode.
• Avoid ungrounded vibe adjectives. Vibe words without a concrete surface fight Claude's style coherence. Vibe word + concrete lever is fine; vibe essay ahead of the brief is not.
• Lock brand explicitly. Palette, type, component names — say them. Don't hope Claude guesses.
• Ask for tweaks on the dimensions you expect to iterate (type, spacing, palette). Claude wires live sliders.
• Quantities help. "N variations", "N loaders on a grid", "N-screen onboarding."
• Flat file layout for multi-file variants. Tell Claude "all files at project root, no subfolders." Claude tends to organize variants under a folder (directions/, variants/) which the current MCP's file list doesn't see through — use the handoff bundle if you need nested layouts.
• Pre-empt the clarifying-questions flow; don't lean on it. A decision-bearing prompt (scope and constraints pinned up front) leaves Claude nothing to ask, so the "Claude has some questions →" popover never appears. If it punts anyway — surfaced as awaitingClarification — answer by re-prompting with the missing specifics, or send decisive: true (which tells Claude to choose the most defensible answer and proceed). Do not expect designer to read or click that popover: it's ephemeral with no stable DOM contract, so designer deliberately won't scrape or auto-answer it. Deciding the requirement stays with you, the human designer.

Picking the right artifact shape

The split is not canvas-vs-files. The split is what's the unit of critique? — pick generation AND evaluation from that.

Heuristic threshold: once screens × meaningful states × breakpoints > ~8–10, stop multiplying variants. Converge to one routed prototype or structured handoff.

Canvas at what scale

Two sub-modes:

• Grid canvas — many small cells, each ≤300×300. For widgets where variants read at thumbnail scale.
• Storyboard canvas — a few frames at real device size, arranged as a sequence. For flows.

Variants of a full-viewport surface are neither. Grid canvas mangles them (type scale, whitespace, hierarchy only read at real size). Storyboard doesn't apply. Right shape: separate full-page HTML files viewed at real size — usually via Claude's own index.html gallery opened at currentUrl. Fall back to designer tasting --key <name> (local full-viewport switcher) only if the IDE chrome is distracting judgment.

Naming variants vs locking brand

• Brand tokens (palette, type, component names, product language) — specify explicitly.
• Variant names (what each disposable exploratory branch is called) — let Claude name them from the problem domain. Exception: if the human already has review-friendly labels in mind ("single-page / wizard / dense ops"), use those.

Tool sequence

Common loop for any variant shape:

1. designer_session({ key, action: 'create', name, fidelity: 'highfi' }).
2. designer_prompt({ prompt }) — terse, let-Claude-name. The MCP auto-appends a flat-file-layout instruction; if you want subfolders you must explicitly override in your prompt.
3. Hand the human the URL — designer_session({ key, action: 'status' }).currentUrl, or the URL echoed in the prompt result. The URL is the live design in Claude's IDE: all tweak sliders work, variant switcher works, fully interactive. This is the default taste path.
4. Repeat 2-3 as they react.
5. When they say "that's it": designer_handoff({ key }) — fetches the project export zip into ./artifacts/{key}/handoff-{ts}/: project/ with all variants + a regenerated decision-record.md. This is non-optional; it's what the implementing agent needs to build the real thing.

When designer_list({ scope: 'files' }) says authoritative: false

Claude Design sometimes organizes generated files under folders (directions/, variants/, shared/). The live file-list scrape only sees top-level files + folder names, never contents. When the result includes folders: […] and authoritative: false, the list is incomplete. Fall back to designer_handoff — the export-zip bundle is always complete (every project file).

When the URL isn't enough — full-viewport tasting

The URL shows Claude's IDE (chat panel + project tree + toolbar eating space). That's fine for most taste judgments, but breaks down when:

• You're comparing multiple screen-level variants and the IDE chrome is stealing viewport space the designs need.
• Claude didn't build an index.html switcher, so the URL only lets you see one variant at a time (navigating via ?file=).
• You need to judge the design at real app scale with no "is this just Claude wrapping?" distraction.

In those cases, after a handoff: designer tasting --key <name> — builds a local full-viewport switcher over the bundle, serves on 127.0.0.1, opens the browser. Keyboard 1/N switches. Notes field persists in localStorage.

Don't default to tasting. Reach for it when the URL framing is getting in the way.

Canvas-variant shape (compact widgets)

When the prompt is for a grid of small things ("20 loaders on a wrapping grid"), Claude generates one HTML file with everything on a canvas. The URL shows this perfectly — no tasting harness needed. designer_handoff at the end for code promotion.

Phase 4: Taste

Show the human the URL first. Only reach for the tasting harness when full-viewport matters more than interactivity.

The human reacts in their own language. Don't ask "accept or reject?" — ask "what do you think?"

Messy reactions are the point:

• "A is closer but still too stark"
• "B feels right but the gap is too much"
• "Neither — what if we kept the border but made it almost invisible?"
• "Yes. That's it."

The human can tune live via the tweak sliders Claude wired into the canvas. Those tweak positions are themselves a reaction — capture them.

Phase 5: Interpret

Translate reaction into the next move: