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 server
• npm run design -- <cmd> — CLI shorthand
• npx design-space <cmd> — same CLI when linked globally
• npm 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

For Claude Code specifically, the repo ships a marketplace + plugin manifest that bundles the MCP server alongside the skill. The MCP server is shipped as a pre-bundled, dependency-free ESM file at mcp-server/dist/index.mjs (regenerated by npm run build:mcp) so the plugin works without any npm install step in the cache.

Install from the marketplace (any project):

/plugin marketplace add bengold/design-space
/plugin install design-space@design-space

Or install directly from a local checkout (no marketplace add):

/plugin install ./.claude-plugin

The MCP server resolves the project root from $DESIGN_SPACE_ROOT (set automatically by the plugin to $CLAUDE_PROJECT_DIR), falling back to walking up from cwd() to find designs/active.json.

Install as a Codex plugin

The Codex plugin version lives in .codex-plugin/plugin.json and bundles the same skill plus the prebuilt MCP server via .codex-plugin/mcp.json (resolved with $CODEX_PLUGIN_ROOT). The repo-root .mcp.json is the Claude Code project-scoped MCP config and resolves the same server with $CLAUDE_PROJECT_DIR — that way both tools find the bundle without colliding on env vars. Codex also discovers hooks/hooks.json, which runs the feedback poller on UserPromptSubmit so new Design Space comments and edits can be surfaced to the agent on the next turn.

The MCP server and hook both resolve the active Design Space project from $DESIGN_SPACE_ROOT, Codex/Claude/Cursor project env vars, hook cwd/workspace_roots, or by walking up from the current working directory to find designs/active.json.

Cursor / Claude Desktop setup

Write the MCP server config for any supported host:

npx design-space mcp install cursor          # writes ./.cursor/mcp.json
npx design-space mcp install cursor-global   # writes ~/.cursor/mcp.json
npx design-space mcp install claude-desktop  # writes the platform config

.cursor/mcp.json is gitignored — see .cursor/mcp.example.json for the shape.