polaris-visual-sandbox

Polaris UI Sandbox — Claude Code plugin

Build pixel-exact Shopify Polaris UI from a screenshot or design, and prove it by measuring the reference and asserting the rendered DOM against those numbers — not by eyeballing a screenshot.

This repo is a Claude Code plugin marketplace. The plugin ships two skills and an isolated visual sandbox that runs outside your project but renders your project's own @shopify/polaris + React, so measurements match what your app actually ships. Nothing is scaffolded into your repo.

What's inside

Skill	What it does
polaris-visual-sandbox	The strict measure → build → assert → iterate → apply loop. Boots the sandbox, drives Playwright, asserts the DOM.
polaris-design	Idiomatic Polaris authoring patterns (layout, forms, tables, modals, feedback states).

Plus the sandbox app (sandbox/) and Python tooling (tokens.py, measure.py).

Install (per teammate)

/plugin marketplace add mrmarufpro/polaris-visual-sandbox
/plugin install polaris-visual-sandbox@polaris-visual-sandbox

Restart Claude Code (or reload plugins) after installing. To update later: /plugin marketplace update polaris-visual-sandbox.

Installing wires up the prerequisite MCP servers declared in .mcp.json (playwright, context7) — approve them when prompted. If a teammate already has those configured, the existing ones are reused.

Prerequisites

The sandbox renders your project's Polaris and verifies the DOM, so each machine needs:

• Node + npm — the sandbox's build tooling installs on first run.
• python3 with Pillow — pip install pillow (the measurement scripts use PIL).
• Playwright MCP — bundled via .mcp.json; approve on install.
• context7 MCP — bundled via .mcp.json (optional but recommended for prop docs).
• Your project must have @shopify/polaris and react installed.

Use it

From a Shopify Polaris project, ask Claude something like:

"Make this match exactly" + a screenshot, and the target file to apply it to.

The polaris-visual-sandbox skill triggers and runs the loop. Under the hood it boots the sandbox from your project root:

"${CLAUDE_PLUGIN_ROOT}/skills/polaris-visual-sandbox/scripts/start-sandbox.sh"

which prints connection info as JSON:

{"type":"sandbox-started","url":"http://localhost:6090","port":6090,
 "slot_path":"~/.cache/polaris-visual-sandbox/Slot.tsx",
 "node_modules":"<your project>/web/frontend/node_modules",
 "polaris_styles":".../@shopify/polaris/build/esm/styles.css","polaris_version":"13.9.5"}

The agent writes Polaris JSX to slot_path, screenshots localhost:6090, asserts the DOM with Playwright, iterates until exact, then applies the result to your real component/page. Stop + reset with:

"${CLAUDE_PLUGIN_ROOT}/skills/polaris-visual-sandbox/scripts/stop-sandbox.sh" --reset

How it stays version-accurate

start-sandbox.sh discovers your project's node_modules (searching cwd and web/frontend, frontend, app, client, src; override with --node-modules <path>). Vite aliases @shopify/polaris/react/react-dom to that copy, and tokens.py reads the same styles.css. The plugin only ships the build tooling — your project owns the components and tokens.

Notes & limits

• Port 6090 by default (--port to change). If you also run an in-repo sandbox on 6090, stop one first.
• Monorepos / unusual layouts: if Polaris isn't auto-found, pass --node-modules. pnpm symlinked stores are handled.
• No write into your repo until the final "apply to target" step — the sandbox itself lives in ~/.cache/polaris-visual-sandbox.

Updating

Bump version in .claude-plugin/plugin.json and .claude-plugin/marketplace.json, commit, and push. Teammates get the update via /plugin marketplace update (or on the next plugin refresh).

Repo layout

.claude-plugin/{marketplace.json, plugin.json}
.mcp.json                         # playwright + context7
skills/
  polaris-visual-sandbox/{SKILL.md, polaris-reference.md, scripts/}
  polaris-design/SKILL.md
sandbox/                          # Vite app source (run from a cache dir, not here)