Interface feel
The master pass for how an interface moves and responds. It audits what the app does today against forty items (twelve animation principles, eight UX laws, twenty UI techniques) and a motion system, writes a report, then fixes each finding by the pattern for that item. Most apps already have half of the list; the audit says so instead of adding it twice. Speed, targets and trust always apply; decoration is restrained in a work tool.
The project's own design system, motion tokens and rules win over anything here. Performance budgets (LCP, INP, bundle size), accessibility and copy are their own passes beside this one.
Files in this skill
| File | Use |
|---|---|
reference.md | each of the 40 items: how to check it, the fix pattern, when to skip it, what a real audit found |
motion.md | the motion system: tokens, twelve rules, CSS patterns, how to audit motion |
audit/census.sh | code census: counts the patterns behind each item, with file:line leads |
audit/probe.js | live page probe: real hit targets, durations, easings, figures, headings, code fields, placeholders |
report-template.md | the audit report: one verdict row per item, order of work, what was not checked |
Pass 1: audit (change nothing)
- Read the project's design system, motion tokens and UI rules first.
- Run the census from the project root:
bash <this skill>/audit/census.sh . --show 5. It reads the shipped surface only (dependencies, builds, vendored copies, tests, benches, generated files and comment lines are left out; add more withCENSUS_EXCLUDE="dir1,dir2"). Install ripgrep for a fast run; without it the script falls back to perl. A count is a lead to open, not a verdict. - Run the app. On each key page run
audit/probe.js(paste into the console, orawaitit in a browser tool's JavaScript runner) at 1440 wide and at 375, in each theme the app has. It scrolls the whole page a screen at a time and restores the position. A hidden tab has no width and paints no frames: show it first. Read its output with judgement: a target markedspaced(its gap to the next control reaches the floor) is a lower severity; figures only needtabular-numswhere they change; mark decorative mock windowsaria-hiddenor ignore their rows. - Drive by hand what no script can see, with real pointer events (a browser tool's click, not a synthetic
.click()): press each paid or irreversible action twice fast and count server effects; throttle the network and a write to 600 ms and press; open and close every layer fast and reopen it mid-exit, sampling its opacity (motion.md, "Measuring a reopen"); press inside a closing menu; type an accented and a differently cased query; move diagonally toward a hover submenu; Android back with a layer open; swipe a phone sheet. - Write the report from
report-template.md: all 40 rows, each there, missing, wrong or skip with a reason, evidence as file:line or a number, and build or pick. Show it before fixing.
Pass 2: fix by the checklist
- Trust first: item 39 and anything that can double a charge or lose data, with a test that fails before the fix.
- Build items change behaviour without a new look (hit slop, safe triangle, back gesture, accent folding, shortcuts, command menu entries, optimistic writes, skeletons, motion tokens, reversible transitions). Fix each by its pattern in
reference.mdandmotion.md, through the project's own components and tokens, with a test for any logic. - Pick items change the look or the product (corners, blur placeholders, undo instead of a confirm, an error beat, a new motion beat, a view transition). Bench each as before and after at scale 1 in both themes, numbered and separable; build only what the owner picks.
- Never trade removed decoration for new decoration.
Pass 3: verify
Re-run the census and the probe and compare the numbers with the report. Drive every fixed interaction the way a user would, in both themes, and at phone width separately. Report built, tested, visually approved and deployed as separate facts, and name what could not be measured (no physical phone, no production build).
The checklist
Numbers match reference.md and the report.
| # | Item | Fails when |
|---|---|---|
| A | Animation principles (motion.md) | |
| 1 | Squash and stretch | a landing badge, dot or knob stops dead |
| 2 | Anticipation | a press has no state within one frame (scale about 0.97, about 100 ms) |
| 3 | Staging | an opened layer leaves the primary thing unclear |
| 4 | Pose to pose | a busy button, label or icon swap jumps in width or content |
| 5 | Follow through | a layer's content arrives welded to its container |
| 6 | Slow in, slow out | linear or default ease on UI motion; more than three easings |
| 7 | Arcs | something travels far in a straight line |
| 8 | Secondary action | a completed action has no confirming second beat |
| 9 | Snappy timing | a UI response over 300 ms; one surface off its peers; exits not shorter |
| 10 | Exaggerated feedback | an invalid submit shows only a twitch, no colour beat |
| 11 | Solid drawing | shadows and layers disagree on light and depth |
| 12 | Appeal | one real flow, stepped at scale 1, shows a seam |
| B | UX laws | |
| 13 | Fitts | a real target under 32 px on desktop or 44 px on a phone |
| 14 | Bigger hit areas | targets grown by enlarging the picture, or siblings overlapping |
| 15 | Hick | more than five items in one menu block |
| 16 | Miller | more than about seven unchunked top-level items |
| 17 | Doherty | press to next paint over 400 ms with nothing answering first |
| 18 | Postel | an accent, case or spacing variant of a query finds nothing |
| 19 | Jakob | a pattern behaves unlike its platform (hover submenu, back closes a layer) |
| 20 | Frequency of use | a daily action is more than one step or one command away |
| C | Speed and feedback | |
| 21 | Skeleton loaders | a route paints blank or a spinner on the click frame |
| 22 | Optimistic updates | a cheap reversible write shows nothing until the server answers |
| 23 | Command menu | a destination is reachable by clicking but not by typing |
| 24 | Shortcut hints | a control with a shortcut does not show it in its tooltip |
| 25 | Undo toasts | a restorable delete has no undo (the owner decides if it replaces a confirm) |
| 26 | Stale-while-revalidate | a revisited page waits instead of painting its last data |
| 27 | Pre-rendering | a likely next page is not prefetched on intent (judge in production) |
| 28 | Blur placeholders | a loading picture is a grey box |
| 29 | View transitions | a grid-to-detail open has no shared-element morph |
| 30 | Swipe-to-dismiss | a phone sheet or drawer cannot be swiped shut |
| 31 | Interruptible animations | reopening during an exit replays from zero |
| D | Platform and detail | |
| 32 | Predictive back | Android back with a layer open leaves the page |
| 33 | Hit slop | small icon controls carry no invisible target growth |
| 34 | Safe-area insets | bottom floats ignore env(safe-area-inset-*) under viewport-fit=cover |
| 35 | One-time-code autofill | a code field lacks autocomplete="one-time-code" and inputmode="numeric" |
| 36 | Tabular numbers | changing figures jitter (no tabular-nums) |
| 37 | Balanced headlines | a short multi-line heading leaves an orphan (no text-wrap: balance) |
| 38 | Continuous corners | squircle corners not considered (a look call: bench it) |
| E | Trust | |
| 39 | Idempotency keys | two fast presses of a paid or irreversible action make two server effects |
| 40 | Safe triangle | a hover submenu closes on a diagonal move toward it |
Common mistakes
- Adding what exists: skeletons, caching and motion tokens are often there; the verdict is there.
- Client dedupe as the money guard: two clicks land before a re-render disables the button. Guard on the server (conditional update, deterministic key, lock) and hold the press in a ref.
- Growing the picture instead of the target; checking targets only at desktop width while a desktop rule kills the phone floor.
- Keyframes for open and close: they cannot reverse. Use transitions on a state attribute, and make a leaving layer
inert. - Treating undo, corners or error tone as engineering choices. They belong to the owner.
- Judging prefetch or timing on a dev server or a background tab.