Design Space
A local host for Claude Design’s canvas and tweaks panel — built for humans and coding agents (Claude Code, Codex, Cursor). Agents edit designs/<name>/Design.jsx and JSON state on disk; you preview in the browser.
Quick start
npm install
npx design-space dev
Open http://localhost:5173/ — toolbar shows active design, zoom, Comment, Edit, Feedback, and Tweaks.
Refinement questions: design-space questions ask opens the modal; design-space questions wait blocks until the user submits.
Agent integration: MCP server (npm run mcp), events.jsonl polling, and the bundled Codex / Claude Code / Cursor skills — see docs/mcp-and-hooks.md and the install instructions below.
Comment / Edit: DevTools-style outlines, arrow-key tree walk, drag box-select (comments), Figma-like CSS inspector panel.
Inline comments: Comment mode → click elements in the preview; saved to comments.json for agents.
Edit panel: Edit mode → click an element to change text and basic styles; saved to overrides.json.
For agents
Read AGENTS.md — file layout, CLI, canvas state, design/tweak guidance distilled from Claude Design’s system prompt, and workflow.
For the underlying Claude Design system prompt (humans-only reference), see docs/claude-design-prompt.extracted.md.
npx design-space scaffold my-flow --title "My flow"
# edit designs/my-flow/Design.jsx
npx design-space validate my-flow
npx design-space dev
npx design-space tweaks get --design my-flow
npx design-space state get
CLAUDE.md points agents at the same doc.
What’s included
| Piece | Role |
|---|
designs/<name>/ | Agent-editable designs (Design.jsx, tweak defaults) |
src/lib/design-canvas.jsx | Figma-style canvas (pan/zoom, sections, artboards, focus) |
src/lib/tweaks-panel.jsx | Floating tweaks UI + edit-mode protocol |
src/lib/design-review.jsx | Comment mode, edit panel, overrides, agent feedback export |
src/host/ | Shell iframe + toolbar + questions modal + feedback sidebar |
bin/design-space.mjs | CLI for scaffold, state, tweaks, dev server |
Persistence
| Data | Location |
|---|
| Active design | designs/active.json |
| Tweak defaults | designs/<name>/tweaks.defaults.json |
| Tweak overrides (UI) | designs/<name>/tweaks.json (gitignored) |
| Refinement Q&A | designs/<name>/questions.json |
| Inline comments | designs/<name>/comments.json (gitignored) |
| Edit overrides | designs/<name>/overrides.json (gitignored) |
| Agent-readable merge | designs/<name>/agent-feedback.md |
| Canvas layout | public/.design-canvas.state.json |
| Viewport pan/zoom | Browser localStorage |
Scripts
npm run dev — Vite dev servernpm run design -- <cmd> — CLI shorthandnpx design-space <cmd> — same CLI when linked globallynpm test — vitest smoke suite (core helpers + CLI round-trip)npm run lint / npm run format — ESLint + Prettier
Optional: Google Fonts API key
The Edit panel's Font dropdown ships a curated seed of ~50 popular Google Fonts plus all web-safe stacks. If you want the full ~1500-family catalog (sorted by popularity), set a Google Fonts API key:
cp .env.example .env.local
# then edit .env.local and paste your key into VITE_GOOGLE_FONTS_API_KEY
Get a key from https://console.cloud.google.com/apis/credentials, enable the Web Fonts Developer API in the same project, and (recommended) restrict the key to http://localhost:5173/* under "Application restrictions". When set, picking any Google font in the Edit panel auto-injects the matching <link> stylesheet so the font renders live.
.env.local is gitignored — never commit it.
Install the skill (any agent)
The design-space skill at skills/design-space/SKILL.md follows the open Agent Skills format and works with Claude Code, Cursor, Codex, Copilot, Cline, and ~50 other agents. Install it into any of them with one command:
npx skills add bengold/design-space # installs into all detected agents (project scope)
npx skills add bengold/design-space -g # global scope
npx skills add bengold/design-space -a claude-code # target one agent
Run npx skills add bengold/design-space --list to preview before installing.
Install as a Claude Code plugin
