SDD UI — Visual Component Editor

Purpose

Use this workflow when implementing a React component from a screenshot reference in an SDD project. The split-panel editor shows the spec screenshot on the left and the live component on the right, so you can iterate visually until they match.

Prerequisites

• sdd CLI installed globally
• Playwright MCP configured in Claude Code settings
  • e.g. @playwright/mcp or @executeautomation/playwright-mcp
  • If not configured, inform the user and stop — visual feedback won't work without it

Workflow

Step 1 — Read the spec

Read the SDD feature file to understand what the component should look like and do. Look for any screenshot paths referenced in the feature doc.

Step 2 — Launch the editor

# Single screenshot — detached (recommended when run by an agent)
sdd ui launch-editor LoginForm \
  --screenshot product/features/auth/login.png \
  --detach

# Multiple screenshots (e.g. desktop + mobile)
sdd ui launch-editor LoginForm \
  --screenshot product/features/auth/login-desktop.png \
  --screenshot product/features/auth/login-mobile.png \
  --detach

The command will:

• Scaffold code/components/LoginForm.tsx if it doesn't exist
• Print the exact component file path to edit
• Start the editor at http://localhost:5174

With --detach the process runs in background and the terminal is immediately free. Without --detach it runs in foreground (use Ctrl+C to stop).

With multiple screenshots, the left panel shows a tab per screenshot. With a single screenshot, no tab bar is shown.

Step 3 — Implement the component

Edit the file printed by sdd ui launch-editor (e.g. code/components/LoginForm.tsx).

Write a React component that matches the screenshot. Use standard HTML/CSS or inline styles — no external UI library unless the project already uses one.

Vite HMR will update the right panel automatically on every save.

Step 4 — Visual check with Playwright

After each save, screenshot the live preview and compare it with the spec:

mcp__playwright__navigate http://localhost:5174
mcp__playwright__screenshot

The left panel already shows the spec screenshot for direct comparison. Note differences in layout, spacing, typography, colors, and component structure.

Step 5 — Iterate

Edit component → Playwright screenshot → compare → repeat until the preview matches the spec.

Step 6 — Finalize

sdd ui stop
sdd mark-synced product/features/auth/login.md
git add -A && git commit -m "sdd sync: implement LoginForm component"

Notes

• The component file is permanent — it lives in code/components/ and is part of your project
• Port 5174 by default (not 5173) to avoid conflicts with the user's app dev server
• If the component needs props, scaffold it with hardcoded sample data for the preview

Troubleshooting

Playwright MCP not configured: Stop and ask the user to add it to their Claude Code MCP settings before continuing.

Component import fails in preview: Check that the component file has a valid default export and no TypeScript errors.

Port already in use: sdd ui launch-editor LoginForm --screenshot login.png --port 5175