ui-polish-pass

UI polish pass

Last reviewed: 2026-11-10

Quick prompts

For anyone improving a site or app, whether a small-business owner or someone at a larger company practicing better prompts. Small layout glitches make a site feel untrustworthy and harder to use, even when the content is good. Paste a prompt into any AI assistant that can see the site or repo.

1. "Look at the home page and one other page of the site or app I work on, on a phone and a laptop. List anything misaligned, cramped, or cut off. Report in plain language first; don't change anything yet." Why this prompt works: Scope: naming the pages and screen sizes keeps the answer specific.

2. "Compare the buttons and form fields across the site I work on. Are any inconsistent in size, color, or spacing? Give me a short list with where each one appears before suggesting fixes." Why this prompt works: Ask for a report first so you can decide what is worth changing.

3. "Check whether text on the site I work on is easy to read on a large monitor: line length, spacing, and font size. Rate each as fine or needs work and explain why, without making edits." Why this prompt works: Give criteria: listing what to judge makes the review consistent.

Make focused visual improvements to an existing interface. Follow its existing design system and technology. Prefer existing components and theme tokens, keep the interface clear and appropriately dense, and avoid a wholesale redesign unless the user asks for one.

Hard limits

• No new features. No changes to content, copy, navigation, links, routes, business logic, or behavior.
• Smallest change that keeps the existing design. Fix shared styles and tokens before one-off overrides.
• Do not lower contrast, remove focus indicators, or shrink targets that already pass. If a contrast audit ran before, re-measure what you touch and keep its fixes.
• Do not scale everything up on big screens. Use content-width limits and responsive rules.
• Deliver as a review PR only. Do not merge, deploy to production, or touch DNS, mail, hosting settings, or secrets without explicit approval from the owner in their own words.

Inputs to gather

1. Repo, branch to start from, and PR base (if another review PR is open on the same files, stack on its branch so the diff shows only this pass).
2. Build and serve commands, required env vars (names only; never print values), and any build-minute or deploy limits. If deploys are metered, make one push for the whole task.
3. Design source of truth: tokens/CSS variables, component library, Tailwind config, theme switch (light/dark/high-contrast), breakpoints.
4. Route list with one example per template, plus any routes that are off in this build (feature flags, paid areas, logged-in areas).
5. Test accounts or seed data for authenticated screens, if in scope.

Step 1: Classify the interface

Pick every type that applies (a site can be several) and use the matching row to set priorities.

Type	Prioritize	Do not touch
Article / blog / editorial	Reading measure (about 60–80 characters), line height, heading rhythm, blockquotes, tables, code blocks, image captions, in-page anchors clearing sticky headers, long-word wrapping	Article text, headings, author/date data, ad or embed placement agreed with the owner
Marketing / landing	Hero and CTA hierarchy, section spacing rhythm, button rows wrapping on phones, logo/testimonial grids, fold behavior at 1920 and 4K	Copy, offer, CTA destinations, tracking attributes, A/B test markup
Docs / knowledge base	Sidebar and table-of-contents alignment, code blocks and copy buttons, callouts, anchor offsets, search box, version switcher, wide tables scrolling inside their own box	Doc content, URL structure, search index config
E-commerce / catalog	Product card alignment (equal heights, price and button on one baseline), filter panel, price/sale/stock states, cart and checkout spacing, image aspect ratios	Prices, product data, checkout logic, payment iframes, analytics events
Dashboard / data-dense	Table density, numeric alignment (tabular figures, right-aligned numbers), sticky headers, chart legends, empty/loading/error states, panel gutters	Data, calculations, chart types, column order, default filters
SaaS / app with auth	Consistent controls across screens, modals and drawers, toasts, menus, disabled/loading states, focus return after dialogs	Auth flows, permissions, form validation rules, API calls
Forms-heavy flow	Label/field alignment, consistent field heights, error message placement, required markers, step indicators, button order	Fields, field order, validation logic, submission endpoints

Rendering model: for static or SSR sites, check built HTML from the production build. For SPAs, wait for hydration and network idle, and check client-side route changes, not only first load. For third-party widgets (search UIs, embeds, chat), their stylesheets may load after yours; raise selector specificity under a scoped wrapper instead of using !important everywhere.

Step 2: Inspect before changing

• Run the app from a clean install with the production build command.
• Use a real browser (Playwright with Chromium, or the Chrome DevTools protocol). Some hosts and preview URLs block script user agents, so curl results are not evidence of what users see.
• Screenshot every sampled route at every size and theme before any edit. Keep these as the "before" set.
• List problems by category: spacing, alignment, type hierarchy, control consistency, borders and surfaces, icons, feedback states (hover, focus-visible, active, selected, disabled, loading, empty, error, success), and accessibility (focus visibility, accessible names, target size).

Step 3: Fix

• Change tokens and shared component styles first. One change in a shared file beats twenty page overrides.
• Common high-value fixes: scroll-margin-top for anchors under sticky headers; max-width on wraps and reading columns; minmax() grids that drop columns at breakpoints; equal-height cards with actions pinned to the bottom; one control height for inputs and selects; visible state for toggles (aria-expanded, aria-pressed); tables that scroll inside their own container on phones.
• Keep targets at least 24×24 CSS px or properly spaced (WCAG 2.5.8). Prefer 44×44 for primary touch actions.
• Make sure a focused element is not fully hidden behind sticky headers, cookie bars, or chat bubbles (WCAG 2.4.11).
• Force states in the browser (:hover, :focus-visible, [disabled], [aria-invalid], open menus) instead of submitting real forms or creating real records.

Step 4: Validate

Viewports (width × height):

• Desktop: 1366×768, 1440×900, 1920×1080 (laptop/desktop), 2560×1440 (QHD/2K), 3840×2160 (4K UHD)
• Tablet: 768×1024 portrait, 1024×768 landscape, 820×1180
• Phone: 360×800, 390×844, 430×932, plus 320×568 for the smallest case

At each size and theme, check: no horizontal overflow, no clipping or overlap, no awkward empty space, no text under 12px for content, content width capped on 2K/4K (no lines stretching edge to edge), header fits its row, menus open and close, keyboard Tab order and visible focus, accessible names on icon-only controls, and 200% zoom does not break layout (WCAG 1.4.4/1.4.10 reflow at 320 CSS px).

Also run: the production build, existing tests and linters, and axe-core on the sampled routes in each theme. Re-measure contrast on anything whose colors you changed.

Report format

1. Interface type(s) and rendering model you detected.
2. Before/after table: area, before (measured or described), after.
3. Screenshots or crops for the main changes (commit them under a docs folder only if the repo already keeps such assets; otherwise attach to the PR).
4. Validation matrix: routes × sizes × themes, with counts of failures found and fixed.
5. Contrast on touched pairs (foreground, background, ratio, required).
6. Not verified: routes, states, or themes you could not open, and why.
7. PR link, base branch, and a clear "not merged" line.

References

• WCAG 2.2 and What's New: https://www.w3.org/TR/WCAG22/ , https://www.w3.org/WAI/standards-guidelines/wcag/new-in-22/
• Understanding 1.4.10 Reflow: https://www.w3.org/WAI/WCAG22/Understanding/reflow.html
• Understanding 2.5.8 Target Size (Minimum): https://www.w3.org/WAI/WCAG22/Understanding/target-size-minimum.html
• MDN responsive design and scroll-margin: https://developer.mozilla.org/en-US/docs/Learn_web_development/Core/CSS_layout/Responsive_Design , https://developer.mozilla.org/en-US/docs/Web/CSS/scroll-margin
• Playwright emulation and screenshots: https://playwright.dev/docs/emulation
• axe-core: https://github.com/dequelabs/axe-core