polish

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:

mcp__chrome-devtools__list_pages

If not connected, inform the user:

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:

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

Take initial screenshot for reference:

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:

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

4b. Check for errors:

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:

mcp__chrome-devtools__take_snapshot

Test hover states:

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

Test click interactions:

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

Test form inputs:

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

Step 6: Responsive Testing

Test across breakpoints:

# 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:

1. Take snapshot to find theme toggle
2. Click toggle
3. Screenshot both modes
4. Verify colors, contrast, and readability

Step 8: Final Verification

Before declaring complete:

## 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:

1. /frontend-design generates UI code
2. /polish verifies and refines in browser
3. Iterate until perfect

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

---

Output Format

When reporting verification results:

## 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