ui-polish-pass

# 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