| name | userinterface-wiki |
| description | UI/UX best practices for web interfaces. Use when reviewing animations, CSS, audio, typography, UX patterns, prefetching, or icon implementations. Covers 11 categories from animation principles to typography. Outputs file:line findings. |
| license | MIT |
| metadata | {"author":"raphael-salaja","version":"3.0.0"} |
User Interface Wiki
Comprehensive UI/UX best practices guide for web interfaces. Contains 152 rules across 12 categories, prioritized by impact to guide automated code review and generation.
When to Apply
Reference these guidelines when:
- Implementing or reviewing animations (CSS transitions, Motion/Framer Motion)
- Choosing between springs, easing curves, or no animation
- Working with AnimatePresence and exit animations
- Writing CSS with pseudo-elements or View Transitions API
- Adding audio feedback or procedural sound to UI
- Building morphing icon components
- Animating container width/height with dynamic content
- Designing UI that respects cognitive psychology (Fitts's, Hick's, Miller's laws)
- Implementing predictive prefetching for perceived performance
- Setting up typography, OpenType features, or numeric formatting
Rule Categories by Priority
| Priority | Category | Impact | Prefixes |
|---|
| 1 | Animation Principles | CRITICAL | timing-, physics-, staging- |
| 2 | Timing Functions | HIGH | spring-, easing-, duration-, none- |
| 3 | Exit Animations | HIGH | exit-, presence-, mode-, nested- |
| 4 | CSS Pseudo Elements | MEDIUM | pseudo-, transition-, native- |
| 5 | Audio Feedback | MEDIUM | a11y-, appropriate-, impl-, weight- |
| 6 | Sound Synthesis | MEDIUM | context-, envelope-, design-, param- |
| 7 | Morphing Icons | LOW | morphing- |
| 8 | Container Animation | MEDIUM | container- |
| 9 | Laws of UX | HIGH | ux- |
| 10 | Predictive Prefetching | MEDIUM | prefetch- |
| 11 | Typography | MEDIUM | type- |
| 12 | Visual Design | HIGH | visual- |
Quick Reference
1. Animation Principles (CRITICAL)
timing-under-300ms - User animations must complete within 300mstiming-consistent - Similar elements use identical timing valuestiming-no-entrance-context-menu - Context menus: no entrance animation, exit onlyeasing-natural-decay - Use exponential ramps for natural decay, not lineareasing-no-linear-motion - Linear easing only for progress indicatorsphysics-active-state - Interactive elements need :active scale transformphysics-subtle-deformation - Squash/stretch in 0.95-1.05 rangephysics-spring-for-overshoot - Springs for overshoot-and-settle, not easingphysics-no-excessive-stagger - Stagger delays under 50ms per itemstaging-one-focal-point - One prominent animation at a timestaging-dim-background - Dim modal/dialog backgroundsstaging-z-index-hierarchy - Animated elements respect z-index layers
2. Timing Functions (HIGH)
spring-for-gestures - Gesture-driven motion (drag, flick) must use springsspring-for-interruptible - Interruptible motion must use springsspring-preserves-velocity - Springs preserve input energy on releasespring-params-balanced - Avoid excessive oscillation in spring paramseasing-for-state-change - System state changes use easing curveseasing-entrance-ease-out - Entrances use ease-outeasing-exit-ease-in - Exits use ease-ineasing-transition-ease-in-out - View transitions use ease-in-outeasing-linear-only-progress - Linear only for progress/time representationduration-press-hover - Press/hover: 120-180msduration-small-state - Small state changes: 180-260msduration-max-300ms - User-initiated max 300msduration-shorten-before-curve - Fix slow feel with shorter duration, not curvenone-high-frequency - No animation for high-frequency interactionsnone-keyboard-navigation - Keyboard navigation instant, no animationnone-context-menu-entrance - Context menus: no entrance, exit only
3. Exit Animations (HIGH)
exit-requires-wrapper - Conditional motion elements need AnimatePresence wrapperexit-prop-required - Elements in AnimatePresence need exit propexit-key-required - Dynamic lists need unique keys, not indexexit-matches-initial - Exit mirrors initial for symmetrypresence-hook-in-child - useIsPresent in child, not parentpresence-safe-to-remove - Call safeToRemove after async cleanuppresence-disable-interactions - Disable interactions on exiting elementsmode-wait-doubles-duration - Mode "wait" doubles duration; halve timingmode-sync-layout-conflict - Mode "sync" causes layout conflictsmode-pop-layout-for-lists - Use popLayout for list reorderingnested-propagate-required - Nested AnimatePresence needs propagate propnested-consistent-timing - Coordinate parent-child exit durations
4. CSS Pseudo Elements (MEDIUM)
pseudo-content-required - ::before/::after need content propertypseudo-over-dom-node - Pseudo-elements over extra DOM nodes for decorationpseudo-position-relative-parent - Parent needs position: relativepseudo-z-index-layering - Z-index for correct pseudo-element layeringpseudo-hit-target-expansion - Negative inset for larger hit targetspseudo-marker-styling - Use ::marker for custom list bullet stylespseudo-first-line-styling - Use ::first-line for typographic treatmentstransition-name-required - View transitions need view-transition-nametransition-name-unique - Each transition name unique during transitiontransition-name-cleanup - Remove transition name after completiontransition-over-js-library - Prefer View Transitions API over JS librariestransition-style-pseudo-elements - Style ::view-transition-group for custom animationsnative-backdrop-styling - Use ::backdrop for dialog backgroundsnative-placeholder-styling - Use ::placeholder for input stylingnative-selection-styling - Use ::selection for text selection styling
5. Audio Feedback (MEDIUM)
a11y-visual-equivalent - Every sound must have a visual equivalenta11y-toggle-setting - Provide toggle to disable soundsa11y-reduced-motion-check - Respect prefers-reduced-motion for sounda11y-volume-control - Allow independent volume adjustmentappropriate-no-high-frequency - No sound on typing or keyboard navappropriate-confirmations-only - Sound for payments, uploads, submissionsappropriate-errors-warnings - Sound for errors that can't be overlookedappropriate-no-decorative - No sound on hover or decorative momentsappropriate-no-punishing - Inform, don't punish with harsh soundsimpl-preload-audio - Preload audio files to avoid delayimpl-default-subtle - Default volume subtle (0.3), not loudimpl-reset-current-time - Reset currentTime before replayweight-match-action - Sound weight matches action importanceweight-duration-matches-action - Sound duration matches action duration
6. Sound Synthesis (MEDIUM)
context-reuse-single - Reuse single AudioContext, don't create per soundcontext-resume-suspended - Resume suspended AudioContext before playingcontext-cleanup-nodes - Disconnect audio nodes after playbackenvelope-exponential-decay - Exponential ramps for natural decayenvelope-no-zero-target - Exponential ramps target 0.001, not 0envelope-set-initial-value - Set initial value before rampingdesign-noise-for-percussion - Filtered noise for clicks/tapsdesign-oscillator-for-tonal - Oscillators with pitch sweep for tonal soundsdesign-filter-for-character - Bandpass filter to shape percussive soundsparam-click-duration - Click sounds: 5-15ms durationparam-filter-frequency-range - Click filter: 3000-6000Hzparam-reasonable-gain - Gain under 1.0 to prevent clippingparam-q-value-range - Filter Q: 2-5 for focused but natural
7. Morphing Icons (LOW)
morphing-three-lines - Every icon uses exactly 3 SVG linesmorphing-use-collapsed - Unused lines use collapsed constantmorphing-consistent-viewbox - All icons share same viewBox (14x14)morphing-group-variants - Rotational variants share group and base linesmorphing-spring-rotation - Spring physics for grouped icon rotationmorphing-reduced-motion - Respect prefers-reduced-motionmorphing-jump-non-grouped - Instant rotation jump between non-grouped iconsmorphing-strokelinecap-round - Round stroke line capsmorphing-aria-hidden - Icon SVGs are aria-hidden
8. Container Animation (MEDIUM)
container-two-div-pattern - Outer animated div, inner measured div; never same elementcontainer-guard-initial-zero - Guard bounds === 0 on initial render, fall back to "auto"container-use-resize-observer - Use ResizeObserver for measurement, not getBoundingClientRectcontainer-overflow-hidden - Set overflow: hidden on animated container during transitionscontainer-no-excessive-use - Use sparingly: buttons, accordions, interactive elementscontainer-callback-ref - Use callback ref (not useRef) for measurement hookscontainer-transition-delay - Add small delay for natural catching-up feel
9. Laws of UX (HIGH)
ux-fitts-target-size - Size interactive targets for easy clicking (min 32px)ux-fitts-hit-area - Expand hit areas with invisible padding or pseudo-elementsux-hicks-minimize-choices - Minimize choices to reduce decision timeux-millers-chunking - Chunk data into groups of 5-9 for scannabilityux-doherty-under-400ms - Respond within 400ms to feel instantux-doherty-perceived-speed - Fake speed with skeletons, optimistic UI, progress indicatorsux-postels-accept-messy-input - Accept messy input, output clean dataux-progressive-disclosure - Show what matters now, reveal complexity laterux-jakobs-familiar-patterns - Use familiar UI patterns users know from other sitesux-aesthetic-usability - Visual polish increases perceived usabilityux-proximity-grouping - Group related elements spatially with tighter spacingux-similarity-consistency - Similar elements should look alikeux-common-region-boundaries - Use boundaries to group related contentux-von-restorff-emphasis - Make important elements visually distinctux-serial-position - Place key items first or last in sequencesux-peak-end-finish-strong - End experiences with clear success statesux-teslers-complexity - Move complexity to the system, not the userux-goal-gradient-progress - Show progress toward completionux-zeigarnik-show-incomplete - Show incomplete state to drive completionux-pragnanz-simplify - Simplify complex visuals into clear formsux-pareto-prioritize-features - Prioritize the critical 20% of featuresux-cognitive-load-reduce - Minimize extraneous cognitive loadux-uniform-connectedness - Visually connect related elements with lines or frames
10. Predictive Prefetching (MEDIUM)
prefetch-trajectory-over-hover - Trajectory prediction over hover; reclaims 100-200msprefetch-not-everything - Prefetch by intent, not viewport; avoid wasted bandwidthprefetch-hit-slop - Use hitSlop to trigger predictions earlierprefetch-touch-fallback - Fall back gracefully on touch devices (no cursor)prefetch-keyboard-tab - Prefetch on keyboard navigation when focus approachesprefetch-use-selectively - Use predictive prefetching where latency is noticeable
11. Typography (MEDIUM)
type-tabular-nums-for-data - Tabular numbers for columns, dashboards, pricingtype-oldstyle-nums-for-prose - Oldstyle numbers blend into body texttype-slashed-zero - Slashed zero in code-adjacent UIstype-opentype-contextual-alternates - Keep calt enabled for contextual glyph adjustmenttype-disambiguation-stylistic-set - Enable ss02 to distinguish I/l/1 and 0/Otype-optical-sizing-auto - Leave font-optical-sizing auto for size-adaptive glyphstype-antialiased-on-retina - Antialiased font smoothing on retina displaystype-text-wrap-balance-headings - text-wrap: balance on headings for even linestype-underline-offset - Offset underlines below descenderstype-no-font-synthesis - Disable font-synthesis to prevent faux bold/italictype-font-display-swap - Use font-display: swap to avoid invisible text during loadtype-variable-weight-continuous - Use continuous weight values (100-900) with variable fontstype-text-wrap-pretty - text-wrap: pretty for body text to reduce orphanstype-justify-with-hyphens - Pair text-align: justify with hyphens: autotype-letter-spacing-uppercase - Add letter-spacing to uppercase and small-caps texttype-proper-fractions - Use diagonal-fractions for proper typographic fractions
12. Visual Design (HIGH)
visual-concentric-radius - Inner radius = outer radius minus padding for nested elementsvisual-layered-shadows - Layer multiple shadows for realistic depthvisual-shadow-direction - All shadows share same offset direction (single light source)visual-no-pure-black-shadow - Use neutral colors, not pure black, for shadowsvisual-shadow-matches-elevation - Shadow size indicates elevation in consistent scalevisual-animate-shadow-pseudo - Animate shadow via pseudo-element opacity for performancevisual-consistent-spacing-scale - Use a consistent spacing scale, not arbitrary valuesvisual-border-alpha-colors - Semi-transparent borders adapt to any backgroundvisual-button-shadow-anatomy - Six-layer shadow anatomy for polished buttons
How to Use
Read individual rule files for detailed explanations and code examples:
rules/timing-under-300ms.md
rules/spring-for-gestures.md
rules/ux-doherty-under-400ms.md
rules/type-tabular-nums-for-data.md
Each rule file contains:
- Brief explanation of why it matters
- Incorrect code example with explanation
- Correct code example with explanation
Full Compiled Document
For the complete guide with all rules expanded: AGENTS.md
