<tool_restrictions>

MANDATORY Tool Restrictions

REQUIRED TOOLS — use these, do not skip:

AskUserQuestion — REQUIRED for all user decisions (approval to apply fixes). Never ask questions as plain text. Keep context before the question to 2-3 sentences max.

BANNED TOOLS — calling these is a skill violation:

EnterPlanMode — BANNED. Execute phases below directly.
ExitPlanMode — BANNED. You are never in plan mode. </tool_restrictions>

Polish Workflow

Pre-ship visual refinement. The last step before shipping, not the first.

Announce at start: "I'm using the polish skill for a final visual quality pass."

Phase 0: Load References (MANDATORY)

<required_reading> Read ALL of these using the Read tool:

rules/interface/spacing.md — Spacing scale and philosophy
rules/interface/colors.md — Color rules, contrast, OKLCH
rules/interface/typography.md — Type hierarchy and OpenType
rules/interface/interactions.md — Eight interactive states
rules/interface/animation.md — Motion rules
references/frontend-design.md — Design review checklist </required_reading>

Phase 1: Visual Capture

Screenshot current state. Prefer Chrome MCP in Claude Code. Outside Claude, prefer agent-browser, then Playwright if needed:

1. mcp__claude-in-chrome__tabs_context_mcp
2. mcp__claude-in-chrome__navigate to the feature URL
3. mcp__claude-in-chrome__computer action=screenshot (desktop)
4. mcp__claude-in-chrome__resize_window width=375 height=812
5. mcp__claude-in-chrome__computer action=screenshot (mobile)
6. mcp__claude-in-chrome__resize_window width=1440 height=900

If no browser tool is available, ask the user to provide the component/page path or screenshots and review code directly.

Phase 2: Systematic Audit

Work through each dimension. Report findings as you go.

2.1 Spacing Verification

Check all spacing against the 4px scale (Tailwind's built-in: 1=4px, 2=8px, 3=12px, 4=16px, 6=24px, 8=32px):

Section padding consistent (p-4 md:p-6 lg:p-8 or similar)
Card/container padding not cramped (minimum p-4 for compact, p-6 standard)
Gap between elements uses gap-* not margin hacks
Button padding not cramped (px-4 py-2 minimum standard)
Heading margin-bottom creates hierarchy (heading closer to its body than to content above)
Consistent rhythm top to bottom
No arbitrary spacing values (p-[13px])
Content width constrained (max-w-prose for body text)

2.2 Interactive State Completeness

For every interactive element, verify all 8 states:

State	Check	Common Tailwind
Default	Base styling present	—
Hover	Subtle feedback (gated to `hover:hover`)	`hover:bg-gray-100`
Focus	Visible ring for keyboard	`focus-visible:ring-2`
Active	Press feedback	`active:scale-[0.97]`
Disabled	Reduced opacity, no pointer	`disabled:opacity-50 disabled:pointer-events-none`
Loading	Spinner or skeleton	`aria-busy="true"`
Error	Red border, message	`aria-invalid:border-red-500`
Success	Confirmation feedback	—

No hover-only interactions (touch users excluded)
Focus rings visible and consistent
Disabled states prevent interaction

2.3 Contrast & Color

Body text passes 4.5:1 against background
Large text (≥18px bold, ≥24px) passes 3:1
UI components (borders, icons) pass 3:1
Placeholder text passes 4.5:1 (commonly fails)
No grey text on colored backgrounds
No pure black (#000) on pure white (#fff)
Color not used as sole indicator

2.4 Typography

antialiased on body
Heading hierarchy clear (size + weight + color, not size alone)
Body text minimum 16px (text-base)
Line length constrained (45-75 characters)
text-balance on headings, text-pretty on body
tabular-nums on data tables, prices, timers
No weight change on hover (causes layout shift)

2.5 Motion

Entering elements use ease-out (not ease-in)
Durations appropriate (100-150ms feedback, 200-300ms state changes)
prefers-reduced-motion respected
Only transform and opacity animated (no width, height, top)
Exit animations faster than entrances (~75% duration)

2.6 Responsive

No horizontal scroll on mobile
Touch targets minimum 44px
Text readable without zooming
Images don't overflow container

Phase 3: Report & Fix

Present findings grouped by severity:

Critical (must fix)

Contrast failures
Missing focus states
Broken mobile layout
Touch targets too small

High (should fix)

Inconsistent spacing
Missing interactive states
Typography hierarchy unclear

Medium (nice to fix)

Motion refinements
Spacing fine-tuning
Dark mode adjustments

For each finding: state what's wrong, show the current Tailwind classes, show the fix (new Tailwind classes), then ask for approval before applying:

AskUserQuestion:
  question: "Apply this fix?"
  header: "Polish Fix"
  options:
    - label: "Apply"
      description: "Apply this fix now"
    - label: "Skip"
      description: "Skip this fix and move to the next finding"
    - label: "Apply all"
      description: "Apply this and all remaining fixes without asking"

If the user selects "Apply all", apply all remaining fixes without further prompts.

Phase 4: Verify

After all fixes, screenshot again:

1. mcp__claude-in-chrome__computer action=screenshot (desktop)
2. mcp__claude-in-chrome__resize_window width=375 height=812
3. mcp__claude-in-chrome__computer action=screenshot (mobile)

Compare before/after. Confirm improvements with user.

Phase 5: Final Checklist

Run the Design Review Checklist from frontend-design.md:

"Zoom in. Squint at it. Use it yourself."

<arc_log> After completing this skill, append to the activity log. See: references/arc-log.md

Entry: /arc:polish — [Component/page] polished ([key changes]) </arc_log>

<success_criteria> Polish is complete when:

Current state screenshotted (desktop + mobile)
All 6 audit dimensions checked
Findings presented by severity
Fixes applied with Tailwind classes
After-state screenshotted and compared
Zero critical issues remaining
Final checklist passed </success_criteria>