UI Polish Pass

Core Pack — Always Active

This is a core skill. Use as the final step after design-review and ux-baseline-check on all visual work.

The screen works. Now make it feel right. This is the difference between functional and professional.

Core Lens

• Distill before decorating.
• Strip the screen to its essential structure, then add back only what earns its place.
• If a polish pass needs more color, more cards, and more chrome, it is probably not a polish pass.
• Use /bolder and /quieter as directional moves:
  • /bolder = increase contrast, hierarchy, or confidence without adding clutter
  • /quieter = remove noise, reduce emphasis, let the right thing lead

The Pass (run sequentially)

Pass 1: Spacing & Breathing Room

• Section spacing — major sections have clear visual separation (32-48px minimum between groups)
• Element spacing — consistent gaps within groups (use the project's spacing scale, usually 4/8/12/16/24)
• Edge padding — content doesn't touch container edges. Minimum 16px padding, 24-32px preferred
• The squint test — do clear groups emerge, or is it one undifferentiated blob?
• Remove, don't add — if two elements feel crowded, try removing one before adding more UI

Pass 2: Typography Hierarchy

• One clear headline — the page has exactly one thing that reads as the primary heading
• Three levels max — heading, subheading, body. If you need more, the IA is probably wrong
• Weight before size — try bold before bigger. Try softer opacity before smaller
• No orphan labels — labels without content, headers without their section
• Consistent text styles — same content type uses the same style everywhere

Pass 3: Alignment & Grid

• Left-align by default — center alignment is for special moments, not routine content
• Consistent gutters — columns have the same gap throughout
• Baseline alignment — text in adjacent columns sits cleanly together
• No rogue pixels — near-miss alignment reads cheap fast
• Max content width — prose doesn't exceed 65-75 characters per line

Pass 4: Color & Contrast

• Restrained palette — use project colors only, don't improvise new ones
• Tinted neutrals — prefer slightly warm/cool neutrals over pure gray
• Hierarchy through opacity — secondary text at 60-70%, tertiary at 40-50% when appropriate
• No decoration color — color means action, status, selection, or rare emphasis
• Dark/light mode — if the project supports both, check both

Pass 5: Interactive Feel

• Hover states exist — every clickable element acknowledges intent
• Transitions are smooth — 150-200ms for micro-interactions, ~300ms for layout changes
• Easing is refined — no bounce, no elastic, no novelty curves
• Cursor changes — pointer on clickable, not-allowed on disabled, grab on draggable
• Focus visible — tab through the page, always know where you are
• No dead zones — click targets are generous, not tiny islands of text

Pass 6: Micro-Details

• Tabular numbers — any dynamically updating number uses font-variant-numeric: tabular-nums to prevent layout shift (counters, prices, stats, timers)
• Text wrapping — headings use text-wrap: balance, body text uses text-wrap: pretty to avoid orphans
• Font smoothing — root layout has -webkit-font-smoothing: antialiased for crisper text on macOS
• Concentric border radius — nested rounded elements have outer radius = inner radius + padding (see alignment.md)
• Image outlines — images on light backgrounds get a subtle outline: 1px solid rgba(0,0,0,0.06) for consistent depth
• Icon animations — icons that change state (open/close, play/pause) cross-fade with opacity + scale, not hard swap
• Scale on press — buttons use scale(0.97) on active state for tactile feedback, 100ms transition
• No transition: all — always specify exact properties (transition-property: transform, opacity)

Pass 7: Final Proof

• Screenshot at 1x — does it still look professional at actual pixels?
• Compare to reference — side by side, honestly
• The 3-second test — can someone tell what the screen is for quickly?
• Would Linear or Vercel ship this?
• Final distill pass — what can you remove and make better at the same time?

When NOT to Polish

• Prototypes Aaron hasn't aligned on yet
• Throwaway experiments or spikes
• Internal tools where speed matters more than beauty

Polish comes after structure is approved. Never polish a bad foundation.

Speed Tips

• Fix spacing first — it solves half the problem
• Use the browser inspector grid overlay to check alignment
• Compare at actual viewport width, not narrow devtools panels
• If you're spending more than 15 minutes on polish, something structural is probably wrong
• If the UI feels weak, choose a direction: /bolder or /quieter, then commit