Design Mode
Point at your UI. Tell Claude what to change. Watch it happen. Visual overlay for annotating and inspecting UI elements β Claude applies your design feedback directly to source code.
Ask AI about Design Mode
Powered by Claude Β· Grounded in docs
I know everything about Design Mode. Ask me about installation, configuration, usage, or troubleshooting.
0/500
Reviews
Documentation
Point at your UI. Tell Claude what to change. Watch it happen.
Stop describing UI changes in chat. Click the element, type what you want, and Claude edits the source code for you β with the right file, the right selector, the right framework.
Hover to inspect. Click to annotate. Claude applies the changes.
The Workflow
You: "activate design mode on http://localhost:3000"
β overlay appears on the page
You: [hover over the hero heading β see margin, padding, border visualized]
[click it, type "make this 48px bold"]
[shift+click the CTA button, type "rounded corners, blue gradient"]
[click the nav, type "more spacing between items"]
You: "apply my annotations"
β Claude finds the source files, applies all three changes, verifies with screenshots
No copy-pasting selectors. No digging through DevTools. No describing elements in chat. You point, you type, Claude builds.
Quick Start
1. Enable Chrome remote debugging β open chrome://inspect/#remote-debugging and tick "Allow remote debugging for this browser instance"
2. Install the plugin:
/plugin install design-mode
Or via marketplace:
/plugin marketplace add harshkedia177/design-mode
/plugin install design-mode@harshkedia177-design-mode
3. Go:
activate design mode on http://localhost:3000
That's it. Three steps. Full setup guide below if you hit issues.
Why Design Mode
Without Design Mode
3 messages just to identify the element. |
With Design Mode
One click. One message. Done. |
Features
See what you're changing
Box model visualization β Hover any element to see margin (red), padding (green), and border (yellow) as colored overlays. Stop guessing why things are spaced wrong.
Annotate in plain English
Click-to-annotate β Click any element, type what you want in natural language: "make this bigger", "change to blue", "add drop shadow". Gold pins mark your annotations so you can track them.
Claude knows exactly what you mean
Auto-read annotations β Every annotation includes the element's CSS selector, computed styles, a cropped screenshot, and the source file path. Claude doesn't have to guess β it gets full context automatically before every message.
Works with your framework
Source file mapping β Design Mode traces each element back to its source file. React, Vue, Svelte β it finds the component, not just the DOM node.
Batch your feedback
Multi-select β Shift+Click multiple elements, annotate each one, then apply all changes in a single pass. Redesign a whole section in one shot.
Try before you commit
CSS playground β Live-tweak styles in the browser with before/after screenshots. Experiment freely, then commit only what works.
Test every screen size
Responsive testing β Switch between mobile (375px), tablet (768px), and desktop (1280px) instantly. Or set any custom width.
Setup Guide
Step 1: Enable Chrome Remote Debugging
Design Mode connects to Chrome via the DevTools Protocol. You need to enable remote debugging β this is the same on macOS, Linux, and Windows.
Requires Chrome 144+ (stable since January 2026). Check your version at
chrome://settings/help.
- Open Chrome (or Chrome Canary / Chromium)
- Go to
chrome://inspect/#remote-debugging - Tick "Allow remote debugging for this browser instance"
That's it. You'll see a message like Server running at: 127.0.0.1:56829 β this means it's working.
This works the same on all platforms. macOS, Linux, Windows β same Chrome URL, same checkbox. No flags, no restart, no terminal commands needed.
How to verify it's working
Check that the DevToolsActivePort file was created:
macOS:
cat ~/Library/Application\ Support/Google/Chrome/DevToolsActivePort
Linux:
cat ~/.config/google-chrome/DevToolsActivePort
Windows (PowerShell):
Get-Content "$env:LOCALAPPDATA\Google\Chrome\User Data\DevToolsActivePort"
You should see a port number on the first line (e.g., 56829).
Alternative: Launch Chrome with a flag (if the checkbox method doesn't work)
Quit Chrome completely, then relaunch with the debugging flag:
macOS:
open -a "Google Chrome" --args --remote-debugging-port=9222
Linux:
google-chrome --remote-debugging-port=9222
Windows (Command Prompt):
"C:\Program Files\Google\Chrome\Application\chrome.exe" --remote-debugging-port=9222
Windows (PowerShell):
& "C:\Program Files\Google\Chrome\Application\chrome.exe" --remote-debugging-port=9222
Supported browsers and port file locations
Design Mode auto-discovers the debugging port from these locations:
| Browser | OS | Port file location |
|---|---|---|
| Chrome | macOS | ~/Library/Application Support/Google/Chrome/DevToolsActivePort |
| Chrome | Linux | ~/.config/google-chrome/DevToolsActivePort |
| Chrome | Windows | %LOCALAPPDATA%\Google\Chrome\User Data\DevToolsActivePort |
| Chrome Canary | macOS | ~/Library/Application Support/Google/Chrome Canary/DevToolsActivePort |
| Chromium | Linux | ~/.config/chromium/DevToolsActivePort |
Step 2: Install Design Mode
Claude Code Plugin (recommended β full experience)
In Claude Code, install directly:
/plugin install design-mode
Or via marketplace:
/plugin marketplace add harshkedia177/design-mode
/plugin install design-mode@harshkedia177-design-mode
Or use the interactive UI: run /plugin β Discover tab β select design-mode β choose your install scope. This gives you:
- All 9 MCP tools
- Auto-read annotations before every message (no manual step)
- Skills (
/design-mode,/annotate,/inspect-element,/playground) - Design assistant agent
- Auto-install dependencies on first launch
Standalone MCP β Claude Code CLI
claude mcp add --transport stdio design-mode -- npx -y design-mode-mcp
Standalone MCP β Claude Desktop
Add to ~/Library/Application Support/Claude/claude_desktop_config.json (macOS) or %APPDATA%\Claude\claude_desktop_config.json (Windows):
{
"mcpServers": {
"design-mode": {
"command": "npx",
"args": ["-y", "design-mode-mcp"]
}
}
}
Standalone MCP β Cursor / Windsurf / other MCP clients
Add to your .mcp.json or MCP settings:
{
"mcpServers": {
"design-mode": {
"command": "npx",
"args": ["-y", "design-mode-mcp"]
}
}
}
Local development (from source)
git clone https://github.com/harshkedia177/design-mode.git
cd design-mode
npm install
claude --plugin-dir .
Step 3: Verify Installation
- Chrome is open with a real web page (not
chrome://newtab) - Remote debugging is enabled (Step 1)
- Run
/mcpin Claude Code β you should seedesign-modewith 9 tools - Say
activate design modeβ a dark toolbar appears on the page
If something's wrong, check Troubleshooting.
Usage Guide
Activating the Overlay
activate design mode
Or navigate to a URL and activate in one step:
activate design mode on http://localhost:3000
A toolbar appears at the top of the page. To deactivate:
deactivate design mode
Inspecting Elements
Hover over any element to see its box model:
- Red/pink overlay β margin
- Green overlay β padding
- Yellow outline β border
- Tooltip β element tag, dimensions, classes
Works on everything β text, images, buttons, containers, SVGs.
Annotating Elements
- Click any element to select it
- An annotation panel appears
- Type what you want changed:
"make this text bigger""change background to blue""add 16px padding""rounded corners, drop shadow""move this to the right"
- Press Enter or click Save
- A gold pin marks the annotation
Multi-select: Hold Shift and click to annotate multiple elements. Apply all at once.
Applying Annotations
Plugin users: Just type your next message. Annotations are auto-read before every message.
apply my annotations
Claude will:
- Read all annotations with cropped screenshots
- Find the source files (React components, Vue files, etc.)
- Detect the styling approach (Tailwind, CSS Modules, styled-components, plain CSS)
- Apply the changes
- Screenshot the result
Standalone MCP users: Explicitly ask:
read my design mode annotations and apply them
Managing Annotations
Click "Notes" in the toolbar:
- See all annotations in a list
- Click one to scroll to and highlight that element
- Edit to change the annotation text
- Del to remove it
CSS Playground
Experiment with styles before committing:
/design-mode:playground
- Select an element
- Tweak CSS properties live
- See before/after screenshots
- Commit to source when happy
Responsive Testing
resize viewport to mobile # 375px
resize viewport to tablet # 768px
resize viewport to desktop # 1280px
resize viewport to 1440px # custom
reset viewport # restore default
Keyboard Shortcuts
| Key | Action |
|---|---|
Ctrl+Shift+D | Toggle overlay visibility |
Escape | Close annotation panel |
Enter | Save annotation |
Shift+Click | Select multiple elements |
Plugin vs Standalone
| Feature | Plugin | Standalone MCP |
|---|---|---|
| All 9 MCP tools | Yes | Yes |
| Hover/click/annotate overlay | Yes | Yes |
| Auto-read annotations every message | Yes | No (manual) |
Skills (/design-mode:*) | Yes | No |
| Design assistant agent | Yes | No |
| Auto-install dependencies | Yes | No (npx handles it) |
Use the plugin. The auto-read hook is the killer feature β you annotate in the browser, then just talk to Claude normally. No extra steps.
Skills Reference
Skills are available when installed as a Claude Code plugin.
| Skill | Trigger phrases | What it does |
|---|---|---|
/design-mode:design-mode | "activate design mode", "deactivate design mode" | Inject or remove the overlay |
/design-mode:annotate | "apply annotations", "apply my design feedback" | Read all annotations and apply changes to source code |
/design-mode:inspect-element | "inspect element", "inspect this button" | Get detailed info on any element by selector |
/design-mode:playground | "css playground", "open playground" | Live CSS experimentation with before/after screenshots |
MCP Tools Reference
The server exposes 9 tools via the Model Context Protocol:
| Tool | Parameters | Description |
|---|---|---|
activate | url? (string) | Inject the overlay into the current page. Optionally navigate to a URL first |
deactivate | β | Remove the overlay from the page |
read_annotations | β | Get all annotations with element data, computed styles, and cropped screenshots |
read_element | selector (string) | Inspect a specific element β returns styles, box model, source file info |
apply_style | selector (string), css (object) | Temporarily apply inline CSS to an element (revertable) |
screenshot | selector? (string) | Take a full-page screenshot, or a cropped screenshot of a specific element |
resize_viewport | width (number) | Emulate a responsive viewport width |
reset_viewport | β | Restore the default viewport |
eval_js | expression (string) | Execute JavaScript in the page context and return the result |
Architecture
ββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββ
β Claude Code β
β β
β ββββββββββββ ββββββββββββββ ββββββββββββββββββββ β
β β Skills βββββΆβ MCP Server βββββΆβ Chrome (CDP) β β
β ββββββββββββ ββββββββββββββ β β β
β ββββββββββββ β β Overlay Script β β
β β Hooks βββββββββββ β (hover/click/ β β
β β(auto-read)β β annotate) β β
β ββββββββββββ ββββββββββββββββββββ β
β ββββββββββββ β
β β Agent β design-assistant (autonomous processor) β
β ββββββββββββ β
ββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββ
| Component | File | Role |
|---|---|---|
| MCP Server | servers/index.js | Connects to Chrome via CDP. Auto-discovers debugging port from DevToolsActivePort file. Exposes 9 tools. |
| Overlay | scripts/overlay.js | Self-contained IIFE injected into the page. Handles hover highlights, click-to-annotate, box model rendering, toolbar UI. Stores state in window.__designMode. |
| Skills | skills/ | Orchestrate MCP tools for common workflows (activate, annotate, inspect, playground). |
| Hooks | hooks/hooks.json | SessionStart β auto-installs npm dependencies. UserPromptSubmit β silently reads annotations before every message. |
| Agent | agents/design-assistant.md | Autonomous agent that reads annotations, maps to source files, detects styling approach, applies changes, and verifies with screenshots. |
Supported Frameworks
Design Mode auto-detects the source file for annotated elements using framework-specific internals:
| Framework | Detection method | Requirements |
|---|---|---|
| React | __reactFiber$ + _debugSource | Dev mode (not production builds) |
| Vue 2 | __vue__ | Dev mode |
| Vue 3 | __vueParentComponent | Dev mode |
| Svelte | __svelte_meta | Dev mode |
| Custom | data-source attribute | Add data-source="path/to/file.tsx:42" to any element |
Note: Source mapping only works in development builds. Production builds strip debug metadata. Make sure your dev server is running in development mode.
Troubleshooting
Chrome connection issues
"MCP server not connecting" / server not listed in /mcp
-
Check Chrome remote debugging is enabled:
- Open
chrome://inspect/#remote-debuggingβ is "Allow remote debugging for this browser instance" checked? - Or verify the port file exists:
# macOS cat ~/Library/Application\ Support/Google/Chrome/DevToolsActivePort # Linux cat ~/.config/google-chrome/DevToolsActivePort - If the file doesn't exist, Chrome doesn't have remote debugging enabled. See Step 1.
- Open
-
Check MCP server status:
/mcpIf
design-modeisn't listed, restart Claude Code. -
Plugin not installed:
/plugin listIf
design-modeisn't listed, reinstall:/plugin install design-mode
"No suitable page target found"
Chrome is connected but there's no suitable page to attach to.
- Navigate to a real web page (not
chrome://newtaborchrome://extensions) - Or pass a URL:
activate design mode on http://localhost:3000 - Make sure the page is fully loaded
Overlay issues
Overlay not appearing after activation
- The page might be blocking script injection (CSP). Try on
http://localhost:3000 - Check Chrome console for errors (
Cmd+Option+J/Ctrl+Shift+J) - Try deactivating and reactivating:
deactivate design mode activate design mode
Hover highlights not showing
- Press
Ctrl+Shift+Dβ the overlay might be hidden - Elements with very high
z-indexcan appear above the overlay
Annotation issues
Annotations not auto-reading
- Auto-read only works with the plugin install, not standalone MCP
- Ensure Design Mode was activated via the MCP tool (not manually injected)
- The
UserPromptSubmithook must be active β the plugin installs this automatically
Source file not detected
- Your dev server must be running in development mode (not production)
- React: ensure
NODE_ENV=development - Custom: add
data-source="path/to/file.tsx:42"to elements - Claude falls back to searching the codebase by element content if detection fails
Installation issues
Dependencies not installing
The SessionStart hook auto-installs. If it fails, install manually:
cd /path/to/design-mode
npm install --production
Node.js version too old
Requires Node.js 18+. Check:
node --version
Update via nodejs.org or your package manager.
License
MIT β Harsh Kedia
