feat(designer-mode): add dev-only in-app visual inspector

Add Designer Mode, a dev-only visual inspector for the extension UI gated
behind the DESIGNER_MODE build flag (dead-code-eliminated when off, so it
never ships in normal builds). It lets designers inspect any component,
edit styles live, and send plain-language change requests to an AI coding
agent that applies them to source.

- Vendored core under ui/helpers/designer-mode/core (Shadow-DOM panel,
  hover/select overlay, toggle, and localhost relay client)
- React fiber inspector adapter (react-adapter.ts)
- Gated init in ui/index.js and the DESIGNER_MODE flag wired through
  builds.yml and .metamaskrc.dist
- docs/designer-mode.md covering setup for both developers and designers

Co-authored-by: Cursor <cursoragent@cursor.com>

Author: andrepimenta

.metamaskrc.dist

@@ -60,6 +60,10 @@ BLOCKAID_PUBLIC_KEY=
 ; Enables the Settings Page - Developer Options
 ; ENABLE_SETTINGS_PAGE_DEV_OPTIONS=true
 
+; Enables Designer Mode — a dev-only in-app visual inspector (Ctrl+Shift+D).
+; Pair with the `designer-mode` skill's relay server. See docs/designer-mode.md.
+; DESIGNER_MODE=true
+
 ; SENTRY CONFIGURATION
 ; SENTRY_DSN             - For production builds only (do NOT use in development)
 ; SENTRY_DSN_DEV         - For local dev and one-off QA testing (sends to 'test-metamask' project)

builds.yml

@@ -292,6 +292,8 @@ env:
   - DECODING_API_URL: 'https://signature-insights.api.cx.metamask.io/v1'
   # Determines if feature flagged Settings Page - Developer Options should be used
   - ENABLE_SETTINGS_PAGE_DEV_OPTIONS: false
+  # Enables Designer Mode — a dev-only in-app visual inspector. See docs/designer-mode.md.
+  - DESIGNER_MODE: false
   # Used for debugging changes to the phishing warning page.
   # Modified in <root>/development/build/scripts.js:@getPhishingWarningPageUrl
   - PHISHING_WARNING_PAGE_URL: null

docs/designer-mode.md

@@ -0,0 +1,190 @@
+# Designer Mode
+
+Designer Mode is a **dev-only**, in-app visual inspector for the MetaMask
+extension UI. It lets a designer point at any component in the running
+extension, see its component name / source file / computed styles, tweak values
+live, and send a plain-language change request straight to an AI coding agent
+that applies the change to the source code.
+
+It is gated behind the `DESIGNER_MODE` build flag and is **never included in
+normal or production builds** — the inspector code is only imported when the
+flag is on, so it is dead-code-eliminated otherwise.
+
+---
+
+## Getting started
+
+Designer Mode runs inside a developer's local build and pairs with an AI coding
+agent. How you get set up depends on your role.
+
+### For developers
+
+The inspector only appears when the UI was built with `DESIGNER_MODE=true`.
+
+1. Add the flag to your **`.metamaskrc`** (not just `.metamaskrc.dist`):
+
+   ```
+   DESIGNER_MODE=true
+   ```
+
+2. **Fully restart** the dev build (the flag is read at startup, so a watch
+   rebuild from a file save will not pick it up):
+
+   ```bash
+   yarn start
+   ```
+
+3. Load / reload the unpacked extension in Chrome (`dist/chrome`) and open the
+   expanded view (`chrome-extension://<id>/home.html`) — the full-page view is
+   the best surface to inspect.
+
+If it is working, the DevTools console logs:
+
+- `[designer-mode] flag on — loading inspector…`
+- `[designer-mode] inspector active — press Ctrl+Shift+D`
+
+…and the floating 🎨 button appears in the bottom-right corner.
+
+#### Driving the agent loop (optional but recommended)
+
+For the full "edit → apply to code" loop, you need the `designer-mode` agent
+skill. Agent skills are **not committed to this repo** (per ADR #57) — they are
+synced on demand into the gitignored `.claude/`, `.cursor/`, and `.agents/`
+folders. If you don't already have `.claude/skills/designer-mode/`, install it:
+
+```bash
+yarn install   # refreshes the shared MetaMask/skills cache
+yarn skills    # syncs the skills into .claude/ , .cursor/ , .agents/
+```
+
+See the [AI Agent Skills](../README.md#ai-agent-skills-yarn-skills) section of
+the README for configuration (domain selection, private overlay, etc.). If the
+skill isn't found after `yarn skills`, your skills source may need the private
+Consensys overlay configured in `.skills.local`.
+
+Once installed, run the `designer-mode` skill in your AI coding assistant and say
+**"enter design mode"**. The skill starts the relay server and listens for
+requests. Without it, the panel still opens and inspects components — it will
+just show **"Not connected"** and the Send button stays disabled.
+
+### For designers
+
+You don't install or build anything yourself — Designer Mode runs inside a
+developer's local build. To get set up, pair with a developer on your team and
+ask them to:
+
+1. Start the extension with the **`DESIGNER_MODE=true`** flag (see "For
+   developers" above).
+2. Install and run the **`designer-mode` agent skill** in their AI coding
+   assistant (so your change requests actually get applied to the code).
+3. Load the unpacked extension in Chrome and open the **expanded view** — the
+   full-page window is the best surface to inspect.
+
+Then keep that developer in the loop while you work: each change you send goes to
+the agent on their machine, and they may need to approve steps along the way.
+
+> If you don't see the 🎨 button, ask the developer to confirm the build was
+> started with `DESIGNER_MODE=true` (and fully restarted after adding the flag).
+> If the panel says **"Not connected"**, ask them to start the `designer-mode`
+> skill — you can still inspect, but sending changes is disabled until it's running.
+
+---
+
+## How it works
+
+```
+┌─────────────────────────┐        ┌──────────────────┐        ┌─────────────────┐
+│  MetaMask extension UI   │  HTTP  │   Relay server   │        │   AI agent      │
+│  (DESIGNER_MODE=true)    │ ─────► │  localhost:3334  │ ─────► │  (designer-mode │
+│  inspector panel 🎨      │ ◄───── │                  │ ◄───── │   skill)        │
+└─────────────────────────┘        └──────────────────┘        └─────────────────┘
+        designer                       dev machine                  developer
+```
+
+1. The **inspector panel** runs inside the extension UI (enabled with the build flag).
+2. It talks to a small **relay server** on `http://localhost:3334`.
+3. An **AI agent** (running the `designer-mode` skill) listens to the relay,
+   applies the requested change to source, and replies back into the panel.
+
+> Because the extension UI and the relay run on the same machine, the default
+> `http://localhost:3334` works with no configuration. `http://localhost` is a
+> trustworthy origin, so the `chrome-extension://` page can reach it without any
+> manifest or CSP changes.
+
+---
+
+## Using the inspector
+
+### 1. Open the inspector
+
+- Click the floating **🎨 Designer Mode** button (bottom-right), or
+- Press **Ctrl+Shift+D** (works on Windows/Linux and macOS).
+
+The button can be dragged anywhere if it is in your way.
+
+### 2. Inspect a component
+
+- **Hover** over any element to highlight it and see its component name.
+- **Click** to lock the selection — the panel then shows full details:
+  - **Component** name, `data-testid`, and source file (`file.tsx:line`)
+  - **Layout** (display, position, size, flex)
+  - **Spacing** (margin/padding cross editors)
+  - **Typography** (font, size, weight, line height, color)
+  - **Fill & Stroke** (background, border, radius, shadow)
+  - **Design Tokens** and **CSS classes** applied to the element
+- Press **Esc** (or **Unlock**) to release the selection.
+
+### 3. Edit values live
+
+- Click any value to edit it inline; changes apply to the live UI immediately so
+  you can preview them.
+- For numeric values, use **↑ / ↓** to nudge by 1 (hold **Shift** for 10).
+- Use the color swatches to pick colors, and add/remove classes or tokens via
+  the pill lists.
+- Every edit you make is collected into a **pending edits** list shown above the
+  message box.
+
+> Live edits are a **preview only**. They are not written to the codebase until
+> you send them to the agent (next step). Refreshing the extension resets them.
+
+### 4. Send a change request
+
+At the bottom of the panel:
+
+- The **status dot** shows whether the agent is connected (green = connected).
+- Type a plain-language description of what you want (for example, *"make this
+  button bigger and use the primary brand color"*), and/or rely on your pending
+  inline edits.
+- Press **Enter** or click the **↑** send button.
+
+The agent receives the component info, your inline edits, and your message,
+applies the change to the source code, and replies in the panel's message
+thread. You can keep iterating — each send is a new request.
+
+> **Copy for AI**: if you would rather paste the details somewhere yourself, the
+> **Copy for AI** button in the header copies a formatted summary of the selected
+> component and your edits to the clipboard.
+
+---
+
+## Troubleshooting
+
+| Symptom | Likely cause / fix |
+| --- | --- |
+| No 🎨 button | Build was not started with `DESIGNER_MODE=true`, or the build wasn't fully restarted after adding the flag. Check the console for the `[designer-mode]` logs. |
+| `[designer-mode] failed to init` in console | The inspector threw on init — share the error with a developer. |
+| Panel shows **"Not connected"** | The relay server isn't running. A developer needs to run the `designer-mode` agent skill ("enter design mode"). Inspection still works; sending is disabled. |
+| Send button disabled | Same as above — the agent/relay is not connected. |
+| Sent a request but no reply | The agent may be busy or waiting for approval. Check with the developer running the skill. |
+
+---
+
+## Notes
+
+- Designer Mode is for **development only**. The `DESIGNER_MODE` flag defaults to
+  `false` in `builds.yml`, and the inspector is excluded from any build where the
+  flag is off.
+- Implementation lives in `ui/helpers/designer-mode/`; the gated entry point is in
+  `ui/index.js`.
+- The agent side is documented in the `designer-mode` skill
+  (`.claude/skills/designer-mode/`), which bundles the relay server.

ui/helpers/designer-mode/core/core.ts

@@ -0,0 +1,128 @@
+import type { InspectorAdapter, DesignerModeOptions, ComponentInfo } from './types';
+import { OverlayController } from './overlay';
+import { PanelController } from './panel';
+import { ToggleController } from './toggle';
+import { RelayClient } from './relay';
+
+export class DesignerModeCore {
+  private adapter: InspectorAdapter;
+
+  private options: DesignerModeOptions;
+
+  private relay: RelayClient;
+
+  private overlay: OverlayController;
+
+  private panel: PanelController;
+
+  private toggleCtrl: ToggleController | null = null;
+
+  private host: HTMLElement | null = null;
+
+  private isActive = false;
+
+  private selectedEl: HTMLElement | null = null;
+
+  private boundKeyDown: (e: KeyboardEvent) => void;
+
+  constructor(options: DesignerModeOptions & { adapter: InspectorAdapter }) {
+    this.adapter = options.adapter;
+    this.options = options;
+    this.relay = new RelayClient(options.relayUrl);
+    this.overlay = new OverlayController(this.adapter);
+    this.panel = new PanelController(this.relay, {
+      onClose: () => this.setActive(false),
+      onUnlock: () => {
+        this.overlay.unlock();
+        this.selectedEl = null;
+        this.panel.showCompact();
+      },
+    });
+    this.boundKeyDown = this.handleKeyDown.bind(this);
+  }
+
+  mount() {
+    if (this.host) {return;}
+    this.host = document.createElement('div');
+    this.host.setAttribute('data-designer-mode', 'root');
+    document.body.appendChild(this.host);
+
+    this.overlay.mount(this.host);
+    this.panel.mount(this.host);
+
+    if (this.options.defaultActive !== false) {
+      // show toggle button
+      this.toggleCtrl = new ToggleController();
+      this.toggleCtrl.setOnToggle(() => this.setActive(!this.isActive));
+      this.toggleCtrl.mount(this.host);
+    }
+
+    this.overlay.setOnSelect((info, el) => {
+      if (!info) { this.panel.hide(); this.selectedEl = null; return; }
+      this.selectedEl = el;
+      this.panel.show(info, el);
+    });
+
+    this.overlay.setOnHover((info, el) => {
+      if (!info || !el) { this.panel.hideHover(); return; }
+      this.panel.showHover(info, el);
+    });
+
+    document.addEventListener('keydown', this.boundKeyDown, true);
+
+    if (this.options.persistState) {
+      const saved = localStorage.getItem('designer-mode-active');
+      if (saved === 'true') {this.setActive(true);}
+    }
+  }
+
+  unmount() {
+    this.overlay.deactivate();
+    this.panel.unmount();
+    this.toggleCtrl?.unmount();
+    this.host?.remove();
+    this.host = null;
+    document.removeEventListener('keydown', this.boundKeyDown, true);
+  }
+
+  toggle() { this.setActive(!this.isActive); }
+
+  setActive(active: boolean) {
+    this.isActive = active;
+    if (active) {
+      this.overlay.activate();
+      if (this.toggleCtrl) {
+        const tp = this.toggleCtrl.getPosition();
+        this.panel.setPosition(tp.right, tp.bottom);
+      }
+      this.panel.showCompact();
+    } else {
+      this.overlay.deactivate();
+      this.panel.hide();
+    }
+    this.toggleCtrl?.setActive(active);
+    if (this.options.persistState) {
+      localStorage.setItem('designer-mode-active', String(active));
+    }
+  }
+
+  isMounted() { return Boolean(this.host?.isConnected); }
+
+  private handleKeyDown(e: KeyboardEvent) {
+    const modifier = e.ctrlKey || e.metaKey;
+    if (modifier && e.shiftKey && e.key === 'D') {
+      e.preventDefault();
+      this.toggle();
+    }
+  }
+
+  static async autoInit(options: DesignerModeOptions = {}) {
+    const { detectFramework } = await import('./utils');
+    const framework = await detectFramework();
+    const { createAdapter } = await import('./detect');
+    const adapter = createAdapter(framework);
+    const core = new DesignerModeCore({ ...options, adapter });
+    core.mount();
+    return core;
+  }
+}

ui/helpers/designer-mode/core/detect.ts

@@ -0,0 +1,21 @@
+import type { Framework, InspectorAdapter } from './types';
+import { buildFallbackInfo } from './utils';
+
+export function createAdapter(framework: Framework): InspectorAdapter {
+  // Lazy import to avoid bundling all adapters
+  // In practice, the user imports the specific adapter they need
+  // This is used for auto-detection in the extension / auto-init
+  return {
+    getComponentInfo(el: HTMLElement) {
+      return buildFallbackInfo(el);
+    },
+    onActivate() {
+      // No activation work needed for the fallback adapter.
+    },
+    onDeactivate() {
+      // No teardown needed for the fallback adapter.
+    },
+  };
+}
+
+export { detectFramework } from './utils';

ui/helpers/designer-mode/core/index.ts

@@ -0,0 +1,10 @@
+export { DesignerModeCore } from './core';
+export { RelayClient } from './relay';
+export { OverlayController } from './overlay';
+export { PanelController } from './panel';
+export { ToggleController } from './toggle';
+export { formatAgentPrompt, formatForClipboard } from './prompt';
+export { extractComputedStyles, buildDomPath, getDirectTextContent, serializeProps, detectFramework, buildComponentInfo, buildFallbackInfo, extractComponentNameFromPath } from './utils';
+export type { ComponentInfoFields } from './utils';
+export { createAdapter } from './detect';
+export type { ComponentInfo, ComputedStyleSnapshot, ChangesetEntry, DesignerModeOptions, InspectorAdapter, Framework, TokenPattern, RelayStatus } from './types';