@pro-vi/designer 0.3.0

package/dist/ui-anchors.js

@@ -0,0 +1,182 @@
+async function hasSelector(browser, sel) {
+    return !!(await browser
+        .evalValue(`!!document.querySelector(${JSON.stringify(sel)})`)
+        .catch(() => false));
+}
+async function hasButtonMatching(browser, pattern) {
+    return !!(await browser
+        .evalValue(`(() => { const re = new RegExp(${JSON.stringify(pattern.source)}, ${JSON.stringify(pattern.flags)}); return Array.from(document.querySelectorAll('button')).some(b => re.test((b.textContent || '').trim())); })()`)
+        .catch(() => false));
+}
+export const UI_ANCHORS = [
+    {
+        id: 'home.creator',
+        category: 'home',
+        description: 'project-creator container',
+        requires: 'home',
+        check: async (b) => ({ ok: await hasSelector(b, '[data-testid="project-creator"]') })
+    },
+    {
+        id: 'home.nameInput',
+        category: 'home',
+        description: 'project-name input',
+        requires: 'home',
+        check: async (b) => ({ ok: await hasSelector(b, 'input[placeholder="Project name"]') })
+    },
+    {
+        id: 'home.wireframeButton',
+        category: 'home',
+        description: 'Wireframe fidelity button',
+        requires: 'home',
+        check: async (b) => ({ ok: await hasButtonMatching(b, /^Wireframe/) })
+    },
+    {
+        id: 'home.highFiButton',
+        category: 'home',
+        description: 'High fidelity button',
+        requires: 'home',
+        check: async (b) => ({ ok: await hasButtonMatching(b, /^High fidelity/) })
+    },
+    {
+        id: 'home.createButton',
+        category: 'home',
+        description: 'create-project button',
+        requires: 'home',
+        check: async (b) => ({ ok: await hasSelector(b, '[data-testid="create-project-button"]') })
+    },
+    {
+        id: 'home.projectsList',
+        category: 'home',
+        description: 'projects-list container',
+        requires: 'home',
+        check: async (b) => ({ ok: await hasSelector(b, '[data-testid="projects-list"]') })
+    },
+    {
+        id: 'home.projectCard',
+        category: 'home',
+        description: 'project-card (at least one)',
+        requires: 'home',
+        check: async (b) => ({ ok: await hasSelector(b, '[data-testid="project-card"]') })
+    },
+    {
+        id: 'session.promptTextarea',
+        category: 'session',
+        description: 'chat composer textarea',
+        requires: 'session',
+        check: async (b) => ({ ok: await hasSelector(b, '[data-testid="chat-composer-input"]') })
+    },
+    {
+        id: 'session.sendButton',
+        category: 'session',
+        description: 'send button',
+        requires: 'session',
+        check: async (b) => ({ ok: await hasSelector(b, '[data-testid="chat-send-button"]') })
+    },
+    {
+        id: 'session.htmlViewerIframe',
+        category: 'session',
+        description: 'html-viewer-iframe (design preview)',
+        requires: 'session',
+        check: async (b) => ({ ok: await hasSelector(b, '[data-testid="html-viewer-iframe"]') })
+    },
+    {
+        id: 'session.chatMessages',
+        category: 'session',
+        description: 'chat-messages container',
+        requires: 'session',
+        check: async (b) => ({ ok: await hasSelector(b, '[data-testid="chat-messages"]') })
+    },
+    {
+        id: 'session.iframeSrcPattern',
+        category: 'pattern',
+        description: 'iframe src is claudeusercontent.com with signed ?t= token',
+        requires: 'session',
+        check: async (b) => {
+            const src = await b.evalValue(`(() => { const el = document.querySelector('[data-testid="html-viewer-iframe"]'); return (el && el.src) || ''; })()`).catch(() => '');
+            if (!src)
+                return { ok: false, detail: 'no iframe src (is a file open?)' };
+            const ok = /claudeusercontent\.com/.test(src) && /[?&]t=/.test(src);
+            return { ok, detail: ok ? undefined : `src=${src.slice(0, 120)}...` };
+        }
+    },
+    {
+        id: 'session.chatTurnPrefix',
+        category: 'pattern',
+        description: "chat turns prefixed with 'You\\n' / 'Claude\\n'",
+        requires: 'session',
+        check: async (b) => {
+            const sample = await b.evalValue(`(() => { const c = document.querySelector('[data-testid="chat-messages"]'); const inner = c && c.children[0]; if (!inner) return ''; return Array.from(inner.children).slice(0, 3).map(d => (d.innerText||'').slice(0, 40)).join('|'); })()`).catch(() => '');
+            if (!sample)
+                return { ok: false, detail: 'no chat turns' };
+            const ok = /(^|\|)(You|Claude)(\\n|\n|$)/.test(sample) || /You\n|Claude\n/.test(sample);
+            return { ok, detail: ok ? undefined : `first turns: ${sample.slice(0, 120)}` };
+        }
+    },
+    {
+        id: 'share.shareButton',
+        category: 'share',
+        description: 'Share button (opens the dropdown containing handoff/export actions)',
+        requires: 'session',
+        check: async (b) => ({ ok: await hasButtonMatching(b, /^Share$/) })
+    },
+    {
+        id: 'share.handoffMenuItem',
+        category: 'share',
+        description: 'Handoff-to-Claude-Code menu item (inside Share dropdown)',
+        requires: 'session',
+        check: async (b) => {
+            const opened = await b.evalValue(`(() => { const btn = Array.from(document.querySelectorAll('button')).find(x => (x.textContent||'').trim() === 'Share'); if (!btn) return false; btn.click(); return true; })()`).catch(() => false);
+            if (!opened)
+                return { ok: false, detail: 'Share button not clickable' };
+            await new Promise((r) => setTimeout(r, 400));
+            const found = await hasButtonMatching(b, /handoff to claude code/i);
+            await b.evalValue(`document.dispatchEvent(new KeyboardEvent('keydown', { key: 'Escape', bubbles: true })); true`).catch(() => null);
+            return { ok: found, detail: found ? undefined : 'Share opened but no Handoff-to-Claude-Code item' };
+        }
+    },
+    {
+        id: 'pattern.sessionUrl',
+        category: 'pattern',
+        description: 'session URL matches /design/p/<uuid>',
+        requires: 'any',
+        check: async (_b, url) => {
+            const inSession = /\/design\/p\/[a-f0-9-]+/i.test(url);
+            return { ok: inSession || /claude\.ai\/design\/?(\?|$)/.test(url), detail: `url=${url.slice(0, 100)}` };
+        }
+    },
+    {
+        id: 'pattern.fileQueryParam',
+        category: 'pattern',
+        description: '?file=<name> opens a specific file (URL-based file switching)',
+        requires: 'session',
+        check: async (_b, url) => {
+            const ok = /[?&]file=/.test(url);
+            return { ok: true, detail: ok ? 'file param present' : '(no file open — not a regression)' };
+        }
+    }
+];
+export async function runHealth(browser, opts = {}) {
+    const currentUrl = (await browser.url().catch(() => '')) || '';
+    const inSession = /\/design\/p\/[a-f0-9-]+/i.test(currentUrl);
+    const onHome = /\/design\/?$/.test(currentUrl) || currentUrl.endsWith('/design');
+    const state = inSession ? 'session' : onHome ? 'home' : 'other';
+    const results = [];
+    for (const a of UI_ANCHORS) {
+        const base = { id: a.id, category: a.category, description: a.description, requires: a.requires };
+        const applicable = a.requires === 'any' ||
+            (a.requires === 'home' && state === 'home') ||
+            (a.requires === 'session' && state === 'session');
+        if (!applicable) {
+            results.push({ ...base, status: 'skip', detail: `needs ${a.requires} state; current=${state}` });
+            continue;
+        }
+        try {
+            const r = await a.check(browser, currentUrl);
+            results.push({ ...base, status: r.ok ? 'ok' : 'fail', detail: r.detail });
+        }
+        catch (e) {
+            results.push({ ...base, status: 'fail', detail: `threw: ${e.message}` });
+        }
+    }
+    return results;
+}

package/package.json

@@ -0,0 +1,60 @@
+{
+  "name": "@pro-vi/designer",
+  "version": "0.3.0",
+  "type": "module",
+  "description": "MCP + CLI for autonomous iteration of claude.ai/design — drives the design surface via agent-browser, downloads handoff bundles, and exposes a tasting harness for full-viewport variant comparison.",
+  "license": "MIT",
+  "author": "Provi Zhang",
+  "homepage": "https://github.com/pro-vi/designer",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/pro-vi/designer.git"
+  },
+  "bugs": {
+    "url": "https://github.com/pro-vi/designer/issues"
+  },
+  "keywords": [
+    "claude",
+    "claude-design",
+    "mcp",
+    "model-context-protocol",
+    "design",
+    "agent-browser",
+    "anthropic"
+  ],
+  "bin": {
+    "designer": "./bin/designer"
+  },
+  "scripts": {
+    "mcp": "tsx mcp-server.ts",
+    "cli": "tsx cli.ts",
+    "setup": "tsx cli.ts setup",
+    "doctor": "tsx cli.ts doctor",
+    "check": "tsc --noEmit",
+    "build": "tsc -p tsconfig.build.json",
+    "prepublishOnly": "npm run check && npm run build",
+    "postinstall": "node -e \"if (!process.env.npm_config_global) process.exit(0); console.log('\\n  designer installed. Next: run `designer setup` to launch debug Chrome, sign in, and register the MCP.\\n')\"",
+    "probe": "tsx scripts/probe.ts"
+  },
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.26.0",
+    "zod": "^3.23.8"
+  },
+  "devDependencies": {
+    "@types/node": "^25.6.0",
+    "tsx": "^4.21.0",
+    "typescript": "^6.0.3"
+  },
+  "engines": {
+    "node": ">=20"
+  },
+  "files": [
+    "dist/",
+    "bin/",
+    "skills/",
+    "scripts/designer-chrome.sh",
+    "selectors.json",
+    "README.md",
+    "LICENSE"
+  ]
+}

package/scripts/designer-chrome.sh

@@ -0,0 +1,38 @@
+#!/usr/bin/env bash
+# Launch a Chrome instance with remote debugging enabled, in a dedicated
+# user-data-dir so the default profile's debug-port lockdown (Chrome 136+)
+# doesn't block us. Sign in to Claude once inside the launched window;
+# the profile persists.
+
+set -e
+
+PORT="${DESIGNER_CDP:-9222}"
+PROFILE="$HOME/.chrome-designer-profile"
+CHROME="${CHROME_BIN:-/Applications/Google Chrome.app/Contents/MacOS/Google Chrome}"
+
+if [ ! -x "$CHROME" ]; then
+  echo "[designer-chrome] Chrome not found at: $CHROME" >&2
+  echo "                  Set CHROME_BIN to override." >&2
+  exit 1
+fi
+
+if curl -fs -o /dev/null "http://127.0.0.1:$PORT/json/version"; then
+  echo "[designer-chrome] CDP already listening on port $PORT — nothing to do."
+  echo "                  curl http://127.0.0.1:$PORT/json/version | head"
+  exit 0
+fi
+
+if pgrep -f "Google Chrome" >/dev/null; then
+  echo "[designer-chrome] WARNING: Chrome is already running." >&2
+  echo "                  If it's NOT a debug-mode Chrome, the launched window may not get the debug port." >&2
+  echo "                  Quit existing Chrome (Cmd+Q) first, or accept the risk and continue." >&2
+fi
+
+echo "[designer-chrome] Launching: $CHROME --remote-debugging-port=$PORT --user-data-dir=$PROFILE"
+echo "[designer-chrome] Sign in to claude.ai in the new window. Then navigate to https://claude.ai/design."
+echo "[designer-chrome] When done, leave this window open. The CDP server runs as long as Chrome runs."
+
+exec "$CHROME" \
+  --remote-debugging-port="$PORT" \
+  --user-data-dir="$PROFILE" \
+  "https://claude.ai/design"

package/selectors.json

@@ -0,0 +1,36 @@
+{
+  "_notes": "Captured 2026-04-17 from Chrome 147 via CDP. Override at ~/.designer/selectors.override.json. Prefer data-testid over class names — Claude's styled-components classes (sc-xxx) are regenerated on every build.",
+  "_urls": {
+    "home": "https://claude.ai/design",
+    "session": "https://claude.ai/design/p/{uuid}"
+  },
+  "login": {
+    "signedInIndicator": "[data-testid=\"create-project-button\"]"
+  },
+  "home": {
+    "creator": "[data-testid=\"project-creator\"]",
+    "nameInput": "input[placeholder=\"Project name\"]",
+    "wireframeButtonText": "Wireframe",
+    "highFiButtonText": "High fidelity",
+    "createButton": "[data-testid=\"create-project-button\"]",
+    "projectsList": "[data-testid=\"projects-list\"]",
+    "projectCard": "[data-testid=\"project-card\"]"
+  },
+  "composer": {
+    "promptTextarea": "[data-testid=\"chat-composer-input\"]",
+    "sendButton": "[data-testid=\"chat-send-button\"]",
+    "stopButton": null,
+    "attachButton": "button[aria-label=\"Attach file\"]",
+    "modelButton": "[data-testid=\"model-selector-button\"]"
+  },
+  "preview": {
+    "iframeOrContainer": "[data-testid=\"html-viewer-iframe\"]",
+    "exportButtonText": "Export",
+    "shareButtonText": "Share",
+    "emptyStateHeading": "Creations will appear here"
+  },
+  "messages": {
+    "chatMessagesContainer": "[data-testid=\"chat-messages\"]",
+    "generatingIndicator": null
+  }
+}

package/skills/designer-loop/SKILL.md

@@ -0,0 +1,214 @@
+---
+name: designer-loop
+description: "Human-participated design iteration loop driven by claude.ai/design via the `designer` MCP. The human is the designer; AI is translation + plumbing. Human states intent, AI reads what exists and relays intent to Claude Design, human tastes the variants Claude produces, AI interprets reactions and iterates. Promotes accepted result with a decision record (the bundle's chat transcript)."
+---
+
+# 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. If this is a frontend for an existing backend or codebase, read the backend's API shape and any existing design tokens in the target repo BEFORE prompting. Those are constraints to thread into the prompt verbatim, not aesthetic hypotheses to propose.
+
+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:
+
+| Guide (include) | Constrain (omit) |
+|---|---|
+| What the product does / data it renders | Color palette (unless it's a hard brand token) |
+| User's situation / primary action | Type treatment, font feel |
+| Entities, field names, copy that must appear | Layout direction, whitespace rules |
+| Adjacent surfaces / what must NOT change | Tone adjectives ("contemplative", "trustworthy") unless paired with a concrete lever |
+| Hard brand tokens (palette, type, existing component names) as non-negotiables | Visual hierarchy choices |
+| Quantity + shape of variants ("3 full-page files", "20 on a wrapping grid") | Variant names (let Claude pick) |
+
+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.
+
+### 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.
+
+| Unit of critique | What to generate | How to evaluate |
+|---|---|---|
+| Alternative treatments of one view | Canvas grid OR separate full-page files, based on scale (see below) | Canvas works for ≤300×300 cells; otherwise full-viewport with a switcher |
+| A journey across screens | One routed prototype with the sequence in context | Storyboard canvas — each frame is a screen in the flow |
+| Named interactive states (empty / loading / error / success) | One interactive prototype with the states as toggles | Tweak system or state buttons |
+| Scroll rhythm / long-form pacing | One scrollable artifact. Don't multiply it | Scroll at real width |
+| A system / shipped artifact | Routed prototype, zip, or handoff to code | `designer_handoff` |
+
+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 })` — tar.gz bundle with all variants + README + chat transcript. 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 tar.gz bundle is always folder-aware.
+
+### 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:
+
+- **"Too X"** → prompt for variants that move away from X.
+- **"Almost"** → narrow range, smaller adjustments.
+- **"What if..."** → human is designing now — execute their idea as the next prompt.
+- **"Yes"** → promote (Phase 7).
+- **Silence / uncertainty** → open the tasting harness, ask what's bothering them.
+- **Ambiguous** → before re-prompting, consider `designer_ask({ prompt })` to *consult* Claude: "given the human said X, what small change would address that?" — cheap (~15-30s text reply) and often surfaces the right adjustment.
+
+Never override with "but best practice says..." — capture the tension in the decision record instead.
+
+## Phase 6: Promote
+
+1. `designer_handoff({ key, openFile: <chosen variant> })` — downloads the tar.gz bundle under `./artifacts/{key}/handoff-{ts}/`. The bundle is the decision record:
+   - `README.md` — handoff protocol for the implementing agent
+   - `chats/chat1.md` — full transcript (every prompt + reply, verbatim)
+   - `project/*.html`, `*.jsx`, `*.css` — all design files including the chosen variant
+2. If this is a frontend for an existing codebase, the implementing agent (this one, or Claude Code downstream) reads the bundle's README + chat transcript first, then translates the chosen variant into real code in the target repo.
+3. Append to the codebase's design decision log with a short entry citing the bundle path + the human's final reaction verbatim.
+
+## Guardrails
+
+- **Read before relaying** (Phase 2). Call `designer_session` first — it returns `availableFiles`.
+- **Guide, don't constrain.** Scope + data + hard brand tokens in; aesthetic choices out.
+- **Lock brand explicitly.** Claude won't guess your palette.
+- **Let Claude name variants** from the problem domain.
+- **Capture feedback verbatim.** The bundle's chat transcript is the record — don't sanitize.
+- **Direct values execute.** If the human says `--border-radius: 12px` mid-loop, just do it (don't even invoke Claude Design for that). Still note the intent.
+- **Promote only after explicit "yes"** — "almost" is not "yes."
+
+## Anti-Patterns
+
+- **Interviewing about aesthetics.** Scope questions are fine when intent is genuinely unclear; taste questions aren't yours to ask.
+- **Proposing variants of your own.** Claude Design proposes. You relay.
+- **Constraining where Claude should have room.** Brand tokens are constraints; palette feelings and layout hunches aren't.
+- **Ungrounded vibe essays.** Vibe words without a concrete surface to attach to fight Claude's style coherence.
+- **Variant grid for full-screen experiences.** Shrinking an intake/onboarding/dashboard into a 400px cell loses hierarchy, type scale, whitespace. Screen-level variants → separate files + tasting harness.
+- **Separate files for compact widgets.** 20 loading indicators don't each need their own file. Grid canvas.
+- **Variant grid for journeys/states/systems.** Multiplying screens by variants blows up fast. Converge to one routed prototype.
+- **Auto-handoff.** Don't promote on every iteration. Handoff is Phase 7, not a sub-verb of `designer_prompt`.
+- **Invoking this skill for mechanical changes.** Single-token, single-value, no-feeling changes don't need the loop. Just edit.
+
+## When the MCP is not available
+
+Check first: `designer_*` tools should appear in the tool list. If they don't:
+
+1. Ask the human whether they've installed the `designer` package. If yes, the MCP may have disconnected — `claude mcp list` will show the status.
+2. If they haven't set it up: `cd ~/Development/_projs/designer && ./bin/designer setup` (or after publish: `npm i -g @pro-vi/designer && designer setup`).
+3. If setup isn't possible in this session, tell the human the skill can't run and fall back to making the change directly (no variant exploration).
+
+The MCP auto-launches debug Chrome on first tool call if the dedicated profile exists. Re-runs of `designer setup` are idempotent.