📦

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.

0 installs

Trust: 34 — Low

Browser

Ask AI about Design Mode

I know everything about Design Mode. Ask me about installation, configuration, usage, or troubleshooting.

0/500

Loading tools...

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

You: "Can you make the heading on the
     homepage larger? It's the h1 inside
     the hero section, I think it's in
     components/Hero.tsx or maybe
     pages/index.tsx, and it uses Tailwind,
     the class is text-3xl I think..."

Claude: "Which heading exactly? Can you
        share the file path?"

3 messages just to identify the element.

With Design Mode

You: [click the heading, type "make bigger"]
You: "apply annotations"

Claude: ✅ Updated Hero.tsx — changed
        text-3xl to text-5xl font-bold
        [screenshot attached]

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 /mcp in Claude Code — you should see design-mode with 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.
Check MCP server status:
```
/mcp
```
If design-mode isn't listed, restart Claude Code.
Plugin not installed:
```
/plugin list
```
If design-mode isn'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://newtab or chrome://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-index can 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 UserPromptSubmit hook 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