---
name: ui-polish-pass
description: Fixes common problems in AI-built interfaces - inconsistent spacing, missing empty, loading and error states, broken phone layouts, weak focus and contrast, text overflow, mismatched buttons - and verifies with screenshots at 390px and 1440px. Use when a UI works but looks rough.
---

# UI Polish Pass

Goal: make an existing working UI look deliberate without redesigning it. Change styling and states, not features. Always compare before and after screenshots.

## Workflow

1. Start the app and take baseline screenshots of each main screen at two widths: 390px (phone) and 1440px (desktop). Use whatever browser automation the project or environment provides (for example Playwright). Save them outside the repo or in an ignored folder.
2. Find the design primitives already in the code: CSS variables, theme file, Tailwind config, a component library. Polish by using them. Do not introduce a second styling system or a new UI dependency without asking.
3. Audit each screen against the checklist. Write down findings with file references before editing.
4. Fix in this order: broken layout, missing states, accessibility, consistency, then visual refinement. Group changes by kind and run the app after each group.
5. Take the same screenshots again and compare. Fix regressions. Report what changed.

## Checklist

Layout and spacing
- Pick a spacing scale (for example 4, 8, 12, 16, 24, 32) and use only those values. Replace one-off pixel values.
- Consistent page gutters and max content width; content does not touch screen edges at 390px (at least 16px side padding).
- Alignment: labels, inputs and buttons share left edges; grids use the same gap everywhere; icon and text are vertically centered.
- No horizontal page scroll at 390px. Tables either scroll inside their own container or collapse into cards.

States
- Loading: a skeleton or spinner, and the layout does not jump when data arrives.
- Empty: a short message that says what the area is for and offers the next action.
- Error: says what went wrong in plain words and offers retry; form errors appear next to the field.
- Disabled and in-progress buttons are visibly different and block double submit.

Text
- Long names, emails, URLs and words wrap or truncate with an ellipsis and a tooltip or full view elsewhere; test with a 60-character string and with an empty string.
- A clear type scale: one size for body, a few for headings; line height around 1.4 to 1.6 for body text; body text at least 16px on mobile.

Buttons and controls
- One primary button per view, with secondary and tertiary styles used consistently. Same height, radius and padding for the same role.
- Touch targets at least 44px tall on mobile; enough spacing between adjacent targets.
- Link and button semantics: navigation is an anchor, actions are buttons.

Accessibility
- Visible focus ring on every interactive element; never remove outline without a replacement.
- Contrast of text against background at least 4.5:1 (3:1 for large text and UI icons); check light gray placeholder and disabled text in particular.
- Inputs have labels; images have alt text; icon-only buttons have an accessible name.
- Works with keyboard only: tab order follows visual order, dialogs trap and restore focus, Escape closes them.

Color
- Few colors: one accent, neutrals, and semantic success, warning and danger. Reuse variables, no stray hex codes.
- If the app supports dark mode, check both themes.

## Screenshot verification

```
# example with Playwright CLI; adapt to the available tooling
npx playwright screenshot --viewport-size=390,844 --full-page http://localhost:3000/ shots/home-390.png
npx playwright screenshot --viewport-size=1440,900 --full-page http://localhost:3000/ shots/home-1440.png
```

Inspect every screenshot yourself. Check the states too: force an empty list, a failed request and a slow response.

## Pitfalls

- Redesigning instead of polishing: keep the structure and brand the user already has.
- Fixing desktop only. The phone width is where most defects live.
- Changing copy, routes or logic. Out of scope; note them as suggestions.
- Putting real user data, emails or secrets in screenshots you share.
- Pixel-perfect tweaks on one screen while a shared component is the actual cause: fix the component.

## Report back

List of fixes grouped by kind with file references, before and after screenshot paths for 390px and 1440px, and any issues left for the user to decide.

Source: [AnyModel skills catalog](https://anymodel.org/en/skills) · License: [CC BY 4.0](https://creativecommons.org/licenses/by/4.0/)
