udaysharmadev/skills/polish

polish: make AI interfaces stop looking AI-generated

Generic UI is not a taste problem, it's a decisions problem: default everything, no hierarchy, decoration instead of intent. You fix it by understanding the product first, auditing deliberately, and making a small number of strong decisions: not by sprinkling gradients.

When to use

• "this dashboard looks so generic, fix it"
• "our app screams AI-generated, help"
• "just tidy the dashboard a little, small tweaks only"

When NOT to use

• Users can't complete tasks → that's usability, friction's job. Fix

flow before aesthetics.

• Recreating an existing design from a screenshot/URL → ditto.
• The project has no product definition yet → hotseat/distill first;

you can't design for an unknown audience.

Prerequisites

Before touching a pixel, know: what the product is, who uses it, what the page's single primary action is, the existing design system (tokens, components, fonts already in the repo) and what's already built you can reuse. Existing good design tokens are an asset, not a suggestion, rewrite them only if they are actively broken, never for novelty.

Also establish the supported viewport range, color themes, locales, data extremes, input methods, and the implementation boundary. If the request is only "make it better", inspect the real interface first and return a concise direction before making a broad visual change. A visual preference is not evidence that a product problem exists.

Authority and preservation boundaries

• Preserve working behavior, content intent, URLs, analytics contracts, and

established component APIs unless the user authorizes a change.

• Do not replace a product's font, color system, component library, or page

structure merely because another style seems more fashionable.

• Do not claim WCAG conformance from a screenshot, an automated scan, or a

contrast ratio alone. These are partial evidence.

• Do not use real customer data in screenshots or reports. Mask or use a

representative fixture.

• Ask before changing copy with legal, pricing, safety, localization, or

conversion implications; visual polish does not grant editorial authority.

• Treat a design file, screenshot, and live app as different evidence. Name

which was inspected and what it cannot prove.

Modes

The mode bounds the diff. A "subtle polish" that restructures the page ignored the mode.

Repository and rendered-product inspection

Inspect before styling. This protects existing work and reveals whether the problem is visual, behavioral, content-related, or caused by a missing state.

1. Read repository guidance and locate the relevant route, component tree,

tokens, global styles, fonts, icon assets, responsive rules, and tests.

1. Identify the existing primitives: spacing scale, type scale, semantic color

roles, radii, elevation, breakpoints, focus treatment, and motion tokens. Record drift instead of declaring a new system from one screen.

1. Render the target route at its supported desktop and narrow widths. Capture

the initial, loading, populated, empty, error, disabled, validation, and long-content states that actually apply.

1. Exercise keyboard-only navigation, visible focus, escape behavior, dialogs,

menus, and form errors. Inspect semantic elements and accessible names, roles, and states where custom controls exist.

1. Test realistic stress: long translated strings, narrow widths, many rows,

missing images, slow network, zoom, dark theme, and reduced-motion preference when applicable.

1. Make an evidence list: observed issue, affected task/user, viewport/state,

likely cause, confidence, and whether it is visual polish or requires a handoff to friction, backend, or hotpath.

If no running interface is available, inspect markup and styles, use supplied screenshots as static evidence, and label every behavioral or visual result unverified. Do not pretend a code read is a rendered review.

Design decision framework

Write a direction paragraph before implementation. It must say the audience, primary job, hierarchy intent, density, visual character, constraints to keep, and the smallest set of changes expected to matter. Then decide changes in this order:

1. Structure: task order, grouping, primary action, content hierarchy, and

information density.

1. Rhythm: grid, container, alignment, spacing scale, and responsive

rearrangement.

1. Legibility: typography roles, line length, contrast, data formatting,

labels, and error copy placement.

1. Surfaces: semantic color, borders, elevation, icons, images, and dark

theme. Decoration needs a product reason.

1. Feedback: interactive states, loading, validation, empty/error/success,

focus, motion, and optimistic-update rollback.

Reject a change when it improves only a pristine screenshot but weakens a common task, real-data robustness, accessibility, performance, or consistency. When two directions are plausible, present the tradeoff instead of blending them into a generic compromise.

Interaction and state model

For each changed interactive component, specify the user action, enabled condition, feedback, success, recoverable failure, irreversible failure, and keyboard behavior. Include:

Use native controls when they fit. Custom widgets require the semantic and keyboard behavior users expect, not only similar pixels. Respect reduced-motion preferences; motion should explain a change or feedback, never be compulsory decoration.

Workflow

1. Audit against the checklist

Read references/audit.md and walk every applicable dimension (layout, type, color, spacing, hierarchy, states, motion, responsive, mobile) on the real rendered UI: screenshots of current state, not imagination. Note what's actually weak; skip what's already good and say so.

2. Decide the direction

One short paragraph before implementing: what should this feel like for its audience (dense tool for experts? calm consumer product?), which few changes get there, and what explicitly will not change. This is the brief you'll verify against.

3. Implement within the system

• Typography and spacing from the token scale (establish one if missing,

then use it everywhere).

• Color: a small role-based palette (background, surface, text, primary,

danger); contrast verified (AA minimum for text).

• Components reused before rebuilt; consistency beats local cleverness.
• Every interactive element gets its states: hover/focus/active,

disabled, loading, empty, error. States are where AI UI most often stops too early.

4. Verify like an engineer, not a vibes-machine

• Screenshot before/after at desktop + mobile widths; compare against the

direction paragraph.

• Walk empty/loading/error states with real data conditions, not just

the happy path.

• Keyboard pass: focus visible on every interactive element, tab order

sane.

• For web: check current Core Web Vitals (LCP, INP, CLS) where

measurable: good is LCP 2.5s or less, INP 200ms or less, and CLS 0.1 or less, each at the 75th percentile segmented mobile/desktop (https://web.dev/articles/defining-core-web-vitals-thresholds). Lab INP without real interactions is not evidence, and INP ignores scroll/hover/zoom. Large unoptimized hero images and layout shift are design bugs too.

• Then hand off: friction for usability, roadtest

for browser-flow evidence.

5. Review the implementation diff

Confirm tokens and reusable primitives were extended before adding one-off values. Check that responsive behavior uses content pressure rather than a single device stereotype, and that a layout change does not alter semantic reading or focus order. Remove experimental CSS, dead variants, duplicated breakpoints, and unused assets created during the polish pass.

For an interface with charts, tables, or dense controls, verify at least one realistic high-density state. For forms, verify invalid submission, inline error announcement where applicable, correction, and successful completion. For a destructive operation, the visual change must not obscure the consequence, confirmation, or recovery path.

For mobile overlays, sticky actions, zoom, or screenshot comparisons, read rendered evidence. Viewport emulation does not establish physical-device keyboard or assistive-technology behavior.

Accessibility and performance verification protocol

Run this proportionately to the changed surface. Automation finds regressions; keyboard, screen-reader-aware semantic review, and real rendering find different classes of problems.

1. Semantics: inspect headings, landmarks, native controls, labels,

accessible names, error/status announcement, and custom widget roles. Avoid ARIA where native HTML provides the behavior.

1. Keyboard: start from browser chrome, tab forward/backward, operate every

changed control, open/close overlays, and ensure focus returns sensibly. Check that focus is visible and not hidden by sticky UI or a modal.

1. Visual access: test contrast in all changed themes, color-independent

meaning, zoom/reflow, text spacing, narrow viewports, and target reach. Use the applicable WCAG criterion, including its scope and exceptions.

1. Motion: trigger transitions and asynchronous feedback with reduced motion

enabled. Verify a state change remains understandable when animation is off.

1. Runtime quality: inspect layout shift around images, fonts, async content,

banners, and skeletons; inspect interaction responsiveness around changed handlers. Measure only when the tool/environment supports it and state the page, device class, and conditions.

1. Regression scope: revisit an adjacent route or component that shares the

changed token/primitives. A global token edit needs broader evidence than a local class adjustment.

If an issue cannot be safely fixed inside the requested visual scope, report it with reproduction steps and route it. Do not hide accessibility or performance debt behind a polished screenshot.

Tool selection/fallback

• Browser/screenshot tooling audits and verifies the real rendered UI at the

product's supported responsive boundaries.

• No browser tooling → static pass over markup and styles only; every

visual claim is marked unverified, never "looks better".

• Contrast/CWV tooling → quote measured values; otherwise compute from

accessible data or state as unverified: never invent numbers.

The banned list