Design Mode
Add to Chrome

Troubleshooting

Most issues fall into a handful of patterns. Here's the short list.

The side panel doesn't open

Make sure your browser supports MV3 side panels (Chrome 114+, Edge 114+, Arc, Brave). In Chrome, check Settings → Launch: Floating and Pin on top open a separate window rather than the docked panel. Some enterprise policies block the side panel API. Try a clean Chrome profile to rule out a conflicting extension.

MCP status chip stays offline

Cloud mode: confirm your bearer token is pasted on the extension's dedicated MCP page (opened from the header MCP chip) and the same token is in your agent's config. Local mode: confirm the companion server is running (clone the repo, npm install, npm start) and your config's cwd points at the repo root. Multiple Design Mode clients can share port 9960; never add a kill -9 startup command. If another application owns 9960, choose a different DM_PORT such as 9961 and set the extension's Local port to match. Self-hosted: confirm the relay URL is correct and Redis is healthy.

Send to Agent button is greyed out

The button only enables when an agent is actually attached (the MCP status chip will be the connected colour). Restart your agent after pasting the config snippet — most clients only re-read MCP servers at startup.

Edits aren't persisting

Design Mode stores edits in chrome.storage per origin. If you reload after switching to Incognito or a different Chrome profile, the storage is separate. Check the Changes tab is showing your edits — if it is, the storage is fine, just the page may have re-rendered.

Still stuck?

Open the Help panel inside the extension (? icon) → Copy diagnostics → file an issue on GitHub. The diagnostics block has the environment metadata maintainers need.

Related docs

Install Design Mode

Design Mode is a free browser extension for Chrome and Firefox. Install once, open the side panel (sidebar on Firefox), open any page and start designing. No account, no setup wizard.

MCP setup

Design Mode talks to AI coding agents over Model Context Protocol. You pick one of three connection modes (Cloud, Local, Self-hosted), paste the snippet, and restart your agent. Full snippets and the live mode comparison live on the /mcp page; this page links into it.

The Changes tab

The Changes tab is where every edit you make in the side panel lands. It's the foundation of the handoff — to a teammate, to a tracker, to an AI agent.