ui-polish — make the UI look like a real team shipped it

When to use this skill

Trigger when the visual quality of an interface is the bottleneck. Strong signals:

• "make this look better", "polish this page", "improve the design", "this looks AI-generated"
• A screenshot in the conversation with the user pointing out spacing, alignment, or visual hierarchy issues
• A new component just landed and the user wants it to match the rest of the system

Do not trigger for: a11y-only requests (separate skill territory), pure animation work without a structural problem, or when the design system is locked and the user is asking you to break it.

The output contract

Code changes that pass this checklist:

1. Type scale: at most 6 sizes in use, geometric ratio (e.g. 12, 14, 16, 20, 24, 32). No font-size: 13px one-off.
2. Spacing: every margin/padding/gap is a multiple of 4 (preferably 8). No margin: 17px.
3. Color: every color comes from a token (color-bg-surface, color-text-muted) — not a raw hex inline.
4. States covered: every interactive element has explicit :hover, :focus-visible, :active, and :disabled. Forms have loading + error + empty + success.
5. Density: deliberate. Marketing pages breathe. Dense data UIs are tight. Don't average.
6. Motion: at most one purposeful transition per interaction (e.g. 150ms opacity on hover). No bouncy nonsense.

Workflow

1 — Diagnose before touching

Read the current component. Identify the actual problems, in priority order:

• Hierarchy: can the eye find the primary action in <1 second?
• Alignment: do edges line up? Is there a grid?
• Spacing: is there a rhythm, or are gaps random?
• Contrast: does text actually pass 4.5:1 against its background?
• States: what happens on hover, focus, disabled, loading, empty?

Name the top three problems out loud. Don't start editing until you can articulate what's wrong.

2 — Look at what already exists

• Is there a design system in the repo? (Tailwind config, shadcn/ui, Chakra, Radix, MUI?)
• What spacing scale is in tailwind.config.{ts,js} or the equivalent? Use it. Don't introduce new tokens unless the user asks.
• What components already exist? Reuse <Button> from the library before hand-rolling one.

3 — Apply the fixes in this order

1. Structure first: get the layout grid and visual hierarchy right. Use flex/grid; remove ad-hoc margins.
2. Spacing: replace every margin/padding with a token value. Use gap on flex/grid containers instead of margins on children.
3. Type: collapse every font size to the existing scale. Set deliberate weights — only 400, 500, 600, 700 unless the design system uses something else.
4. Color: replace inline hex with tokens. If you need a new shade, add it to the config, don't sprinkle.
5. States: add :hover, :focus-visible, :disabled. Replace fade-in with a real loading skeleton or spinner. Add empty states with a one-line "why this is empty + the next action".
6. Motion: one short transition per interaction. transition: opacity 150ms ease is usually enough.

4 — Verify with the browser

If a dev server is running, use the preview tools (or Playwright via browser-qa) to:

• Screenshot the new state at desktop + mobile widths
• Tab through interactive elements and confirm focus rings are visible
• Hover over actionable items and confirm state change

Show the user the before/after screenshots. Don't just claim it looks better.

5 — Hand-off

Summarize what you changed in 5 bullets max:

• The structural fix (e.g. "switched to a 12-col grid")
• The spacing rule (e.g. "all margins now multiples of 8")
• The token usage (e.g. "replaced 6 inline hex with color-text-* tokens")
• The new states (e.g. "added loading skeleton, empty state, error inline")
• Anything that should be promoted to the design system

Patterns and anti-patterns

✅ Do:

• Steal mercilessly from existing top-tier UIs. Linear, Vercel, Stripe, Notion — study their spacing rhythm before inventing your own.
• Default to a single accent color. Two is brave. Three is a brand crisis.
• Use outline-offset: 2px for focus rings; never set outline: none without a replacement.
• Match line-height to font size: body 1.5x, headings 1.2x.

❌ Don't:

• Don't add shadows to fix unclear hierarchy. Fix the hierarchy.
• Don't use transition: all. Be explicit about what animates.
• Don't reach for new fonts. The existing one almost always works with better weight + spacing choices.
• Don't center-align everything. Left-align body copy. Always.

Example invocation

User pastes a screenshot of a dashboard card: "this looks like AI slop, make it look good"

1. Diagnose: hierarchy is flat (label, value, delta are all the same weight), gaps are random (12, 17, 20px), the chart has no axis labels, focus state is missing on the time-range toggle.
2. Check repo — uses Tailwind with a custom scale. Spacing tokens: 1, 2, 3, 4, 6, 8, 12.
3. Restructure: bigger weight on the metric value (font-semibold, text-3xl), smaller muted label above (text-xs, text-muted-foreground, uppercase tracking-wide).
4. Normalize: all gaps to gap-2 (8px) inside the card, gap-6 (24px) between cards.
5. Add chart axis labels with the muted color token; add :focus-visible ring to the time-range button.
6. Add a loading skeleton (one shimmer line at the right height) for when the metric is fetching.
7. Show the user before/after, list the 5 changes.

See also

• code-auditor — for finding hard-coded magic numbers and inline styles at scale
• browser-qa — to verify the polished UI doesn't break the user flows
• refactor-master — when polishing reveals that the component needs to be split