designer-agent

Scaffold the Designer Agent toolkit into any project with one command. It drops in:

• CLAUDE.md — the Rooms always-loaded rules + locked tech-stack decisions
• .claude/agents/designer-ticket.md — the feature-implementation agent with a measured Figma verification loop (pixel-diff gate, not eyeballing)
• .claude/rules/ui/*.md — the 9 detailed UI rule files (architecture, layers, naming, styling, forms, data-fetching, loading, folder-structure, anti-patterns)
• designer-agent/ — the self-contained verification pipeline:
  • new-task.cjs — per-task workspace scaffolder (+ manifest.json; parses fileKey/nodeId from a Figma URL)
  • fetch-figma.cjs — batched Figma REST fetch → figma-spec.json + cached PNG renders (needs FIGMA_PAT)
  • parse-figma.cjs — Figma node-tree summarizer + icon-candidate extractor
  • screenshot-routes.cjs — Puppeteer driver; routes as CLI args; shoots desktop and 375px mobile; waits for webfonts; fails on console errors
  • diff-shots.cjs — pixel-diff gate: mismatch % vs threshold, heatmap, native-resolution crop pairs for failing bands
  • check-workspace.cjs — structure + completeness validator the agent must pass before reporting done
  • package.json — scratchpad-local deps (puppeteer, pixelmatch, pngjs) so your app's package.json is never touched
• .mcp.json — registers three MCP servers for Claude Code:
  • chrome-devtools — Chrome DevTools MCP (npx chrome-devtools-mcp@latest)
  • figma-dev-mode — Figma desktop Dev Mode MCP (http://127.0.0.1:3845/mcp)
  • figma-remote — Figma remote MCP (https://mcp.figma.com/mcp)

Why a pixel-diff gate

"Compare the two screenshots side-by-side" silently fails: full-page screenshots get downscaled when a model views them, so 1px borders, 14-vs-16px text, and near-identical grays become invisible — broken UI passes review. diff-shots.cjs measures at native resolution, reports a mismatch percentage against a threshold (default 5%), and emits crop pairs of only the failing bands — small enough for the model to actually see. The agent's receipt reports the number, not an impression.

Usage

From the root of the project you want to set up:

npx designer-agent init

This is non-destructive: existing files and existing MCP server entries are left untouched and reported as skipped. Pass --force to overwrite.

Options

| Flag | Effect | |---|---| | --dir <path> | Target directory (default: current working directory) | | --force | Overwrite existing files and MCP server entries | | -h, --help | Show help | | -v, --version | Show version |

After running init

1. Install the scratchpad deps (puppeteer, pixelmatch, pngjs live inside designer-agent/, not your app):

   cd designer-agent && npm install   # or: yarn / pnpm install

2. Restart Claude Code, then run /mcp to approve the newly registered servers.
3. Set FIGMA_PAT — a Figma personal access token; fetch-figma.cjs refuses to run without it.
4. Figma desktop MCP (figma-dev-mode): in the Figma desktop app, enable Preferences → Dev Mode MCP Server. Only needed if you use the local server.
5. Figma remote MCP (figma-remote): authenticate via OAuth when Claude Code prompts.
6. Chrome DevTools MCP: needs a local Chrome/Chromium install. The server is fetched on demand via npx.

You don't need all three servers. Trim .mcp.json to the ones you actually use — the remote Figma server covers most needs; the desktop server is only for the local Dev Mode flow. Note: MCP renders only exist in conversation context — the agent is required to fetch on-disk renders via fetch-figma.cjs regardless, because the diff gate runs against files.

The verification pipeline (what the agent runs)

node designer-agent/new-task.cjs my-feature --desc "..." --figma "<url>"   # scaffold + manifest
FIGMA_PAT=... node designer-agent/fetch-figma.cjs KEY 1:23 --task my-feature
node designer-agent/parse-figma.cjs designer-agent/my-feature/figma-spec.json
# ...implement from the JSON values...
node designer-agent/screenshot-routes.cjs --task my-feature /route:name     # desktop + mobile
node designer-agent/diff-shots.cjs designer-agent/my-feature/figma-cache/1-23.png \
  designer-agent/my-feature/shots/name.desktop.png --task my-feature        # the gate
node designer-agent/check-workspace.cjs my-feature                          # must print ✓

What gets written

<your-project>/
├── CLAUDE.md
├── .mcp.json                       # merged, not clobbered
├── .claude/
│   ├── agents/designer-ticket.md
│   └── rules/ui/*.md               # 9 files
└── designer-agent/
    ├── README.md
    ├── package.json                # scratchpad-local deps
    ├── new-task.cjs
    ├── fetch-figma.cjs
    ├── parse-figma.cjs
    ├── screenshot-routes.cjs
    ├── diff-shots.cjs
    └── check-workspace.cjs

init also appends designer-agent/ to your .gitignore (if one exists) — that folder is an agent scratchpad and should not be committed.

Upgrading from 0.1.x

• Re-run npx designer-agent init --force to pick up the new tools and the rewritten agent.
• 0.1.x added puppeteer to your app's devDependencies — you can remove it; the scratchpad now carries its own copy (init prints a note if it spots one).
• The old OUT_DIR=... screenshot-routes.cjs + "edit the ROUTES array" flow is gone — routes are CLI args now.
• Existing task folders keep working; add "legacy": true to a backfilled manifest.json to exempt pre-pipeline tasks from check-workspace.cjs completeness checks.

Notes

• The kit itself is pure Node, zero runtime dependencies — npx starts instantly. (The scaffolded scratchpad has its own three deps, installed separately inside designer-agent/.)
• Requires Node ≥ 18.
• The MCP server URLs/commands reflect the published Figma and Chrome DevTools MCP servers. If those change, edit .mcp.json directly.

License

MIT