Purpose

Polish and refine frontend pages with a tight visual feedback loop. See changes live in Chrome as you work.

When to use: "polish this page", "touch up the UI", "take a peek at the styling", "improve the UX", "make this look better"

Requires: Chrome DevTools MCP (claude mcp add chrome-devtools)

Instructions

Step 1: Ensure Browser Connection

Before starting, verify Chrome is connected:

code

mcp__chrome-devtools__list_pages

If not connected, inform the user:

code

Chrome DevTools MCP not responding. Ensure Chrome is running with:
/Applications/Google\ Chrome.app/Contents/MacOS/Google\ Chrome --remote-debugging-port=9222

Step 2: Navigate to Target

Navigate to the page being worked on:

code

mcp__chrome-devtools__navigate_page(url: "http://localhost:3000/path")

Take initial screenshot for reference:

code

mcp__chrome-devtools__take_screenshot

Step 3: Implement Changes

Make frontend changes using Edit/Write tools. Follow these principles:

•Small increments - One logical change at a time
•Verify often - Screenshot after each meaningful change
•Check console - Catch errors early

Step 4: Visual Verification Loop

After each change:

4a. Reload and capture:

code

mcp__chrome-devtools__navigate_page(type: "reload")
mcp__chrome-devtools__take_screenshot

4b. Check for errors:

code

mcp__chrome-devtools__list_console_messages

4c. If errors found: Fix immediately before continuing.

4d. If visual issues: Note specific problem, make targeted fix, repeat.

Step 5: Test Interactions

Get the DOM tree to find interactive elements:

code

mcp__chrome-devtools__take_snapshot

Test hover states:

code

mcp__chrome-devtools__hover(uid: "element_uid")
mcp__chrome-devtools__take_screenshot

Test click interactions:

code

mcp__chrome-devtools__click(uid: "element_uid")
mcp__chrome-devtools__take_screenshot

Test form inputs:

code

mcp__chrome-devtools__fill(uid: "input_uid", value: "test value")
mcp__chrome-devtools__take_screenshot

Step 6: Responsive Testing

Test across breakpoints:

code

# Mobile
mcp__chrome-devtools__resize_page(width: 375, height: 667)
mcp__chrome-devtools__take_screenshot

# Tablet
mcp__chrome-devtools__resize_page(width: 768, height: 1024)
mcp__chrome-devtools__take_screenshot

# Desktop
mcp__chrome-devtools__resize_page(width: 1280, height: 800)
mcp__chrome-devtools__take_screenshot

Step 7: Theme Testing (if applicable)

If the app has dark/light mode:

•Take snapshot to find theme toggle
•Click toggle
•Screenshot both modes
•Verify colors, contrast, and readability

Step 8: Final Verification

Before declaring complete:

markdown

## Verification Checklist

- [ ] Visual matches intent
- [ ] No console errors
- [ ] Hover states work
- [ ] Click interactions work
- [ ] Mobile responsive (375px)
- [ ] Tablet responsive (768px)
- [ ] Desktop responsive (1280px+)
- [ ] Dark mode correct (if applicable)
- [ ] Light mode correct (if applicable)

Quick Reference

Navigation

Action	Tool
Go to URL	`navigate_page(url, type: "url")`
Reload	`navigate_page(type: "reload")`
Back	`navigate_page(type: "back")`

Capture

Action	Tool
Screenshot viewport	`take_screenshot`
Screenshot full page	`take_screenshot(fullPage: true)`
Get DOM tree	`take_snapshot`

Interact

Action	Tool
Click	`click(uid)`
Hover	`hover(uid)`
Type	`fill(uid, value)`
Press key	`press_key(key)`

Debug

Action	Tool
Console logs	`list_console_messages`
Network requests	`list_network_requests`
Run JS	`evaluate_script(function)`

Viewport

Action	Tool
Resize	`resize_page(width, height)`

Common Viewport Sizes

Device	Width	Height
iPhone SE	375	667
iPhone 14 Pro	390	844
iPad	768	1024
iPad Pro	1024	1366
Laptop	1280	800
Desktop	1440	900
Wide	1920	1080

Anti-patterns

•Blind editing - Multiple changes without visual verification
•Screenshot-only - Not checking console for errors
•Desktop-only - Skipping mobile/tablet testing
•Skip interactions - Not testing hover/click/focus
•Ignore errors - Proceeding with console errors present

Integration

With /frontend-design: Use /polish to validate and refine generated components

Workflow:

•/frontend-design generates UI code
•/polish verifies and refines in browser
•Iterate until perfect

Standalone: Just say "polish this page" to touch up existing UI

Output Format

When reporting verification results:

markdown

## Polish Complete

**URL:** http://localhost:3000/dashboard
**Changes:** Added card hover effects, time-based greeting

### Screenshots
- Desktop (1280x800): [captured]
- Mobile (375x667): [captured]

### Interactions Tested
- Card hover: ✅ Lift + shadow working
- New button: ✅ Click creates document
- Theme toggle: ✅ Switches correctly

### Console
- Errors: None
- Warnings: None

### Responsive
- Mobile: ✅ Layout adapts correctly
- Tablet: ✅ Cards reflow properly
- Desktop: ✅ Full width utilized

**Status:** Ready for commit