Review interface surfaces, icons and motion

better-ui reviews visual polish for surfaces, icons and motion once the underlying interaction works. A polish issue never outranks a broken interaction. The skill preserves established component libraries, tokens, density and motion language. Consistent project preferences, including a deliberate shadow-free style, remain choices; inconsistent treatment of the same detail becomes a finding.

Surface guidance relates nested radii to padding and border width where layers share an even inset. Past 24px of padding, or with asymmetric padding, layers keep separate radius tokens. Optical alignment is judged visually: icon-side button padding starts 2px smaller, and asymmetric SVG glyphs are adjusted directly. Shadows convey elevation, while borders retain structural roles on dividers, cells, selected states and inputs. Transparent borders preserve edges in forced-colors mode when shadow rings disappear. Content images receive 1px outlines inset by 1px, using pure black at 0.1 alpha in light mode and pure white at 0.1 alpha in dark mode, excluding transparent artwork.

Interactive state changes use transitions or springs that can retarget when users reverse an action; keyframes serve one-time sequences. A pressed enabled button scales to 0.96 over 150ms with ease-out and can expose an opt-out through the component API. Frequent events such as typing, row hovers and tab changes respond instantly or with opacity or background-color transitions of 150ms or less. Expressive motion is reserved for infrequent events, and every animated state change retains a static color, icon or label cue.

Movement, scale and blur run behind the no-preference reduced-motion query, with opacity cross-fades as the fallback. Staged entrances use semantic chunks separated by 100ms, entering with opacity, 4px blur and 12px vertical movement over 300ms. Exits use opacity, 4px blur and -12px vertical movement over 150ms with ease-out; full travel is reserved for meaningful destinations such as closing drawers. Entrances use ease-out. State swaps use initial={false} on AnimatePresence to skip first-render animation without suppressing intentional entrances.

Infrequent contextual icon changes cross-fade from scale 0.25 to 1, opacity 0 to 1 and blur 4px to 0px. Spring versions use duration 0.3 and zero bounce; CSS versions retain both icons over 300ms with cubic-bezier(0.2, 0, 0, 1). Theme switches temporarily suppress transitions to prevent every color change animating together. Transitions name only changed properties. The will-change hint is added only for observed first-frame stutter, names the actual animated property, and is limited to transform properties, opacity and filter.

Hover styling is restricted to hover-capable pointers. Tailwind 4 guards hover variants with a hover query, while Tailwind 3 does not. Controls avoid duplicate touch feedback where a control draws its own pressed state. Scrollable overlays contain overscroll. Icons use a consistent library per surface, track adjacent text weight from 1.5px stroke at weight 400 to 2.5px at 700, inherit currentColor and use CSS states rather than separate assets. Outline icons are the default and fill marks active state. Only direction-dependent icon meanings mirror in RTL.

Use it for an authorized polish review or requested implementation on an already sound interaction. Reviews are read-only unless changes are requested. Connected tools require authorization, and synthetic fixtures avoid private customer data. Exact recipe values matter where given, while optical nudges remain visual starting points. The skill does not replace broader accessibility, layout or typography review and cannot certify uninspected behavior.

The input is the requested interface or component and its existing conventions. Source inspection reads every defined state, duration and easing. Browser verification walks those states and replays motion at 10% speed in the Animations panel. Unavailable checks are marked Not verified.

Findings are grouped by principle and severity, with file-and-line locations, before, after and user impact. HIGH covers broken interactions, ignored reduced-motion preferences and motion-only feedback. MEDIUM covers visible inconsistency; LOW covers isolated polish. Remaining HIGH findings yield Block; otherwise the result is Approve with outstanding work and inspected coverage stated.

better-typography owns text rendering and spacing, better-accessibility owns keyboard behavior and accessibility requirements, better-layout owns grouping and responsive structure, and better-colors owns tokens and contrast measurement. The workflow is adapted from jakubkrehel/skills under the MIT license.