userinterface-wiki

User Interface Wiki Comprehensive UI/UX best practices guide for web interfaces. Contains 119 rules across 11 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- Quick Reference 1. Animation Principles (CRITICAL) timing-under-300ms - User animations must complete within 300ms timing-consistent - Similar elements use identical timing values timing-no-entrance-context-menu - Context menus: no entrance animation, exit only easing-natural-decay - Use exponential ramps for natural decay, not linear easing-no-linear-motion - Linear easing only for progress indicators physics-active-state - Interactive elements need :active scale transform physics-subtle-deformation - Squash/stretch in 0.95-1.05 range physics-spring-for-overshoot - Springs for overshoot-and-settle, not easing physics-no-excessive-stagger - Stagger delays under 50ms per item staging-one-focal-point - One prominent animation at a time staging-dim-background - Dim modal/dialog backgrounds staging-z-index-hierarchy - Animated elements respect z-index layers 2. Timing Functions (HIGH) spring-for-gestures - Gesture-driven motion (drag, flick) must use springs spring-for-interruptible - Interruptible motion must use springs spring-preserves-velocity - Springs preserve input energy on release spring-params-balanced - Avoid excessive oscillation in spring params easing-for-state-change - System state changes use easing curves easing-entrance-ease-out - Entrances use ease-out easing-exit-ease-in - Exits use ease-in easing-transition-ease-in-out - View transitions use ease-in-out easing-linear-only-progress - Linear only for progress/time representation duration-press-hover - Press/hover: 120-180ms duration-small-state - Small state changes: 180-260ms duration-max-300ms - User-initiated max 300ms duration-shorten-before-curve - Fix slow feel with shorter duration, not curve none-high-frequency - No animation for high-frequency interactions none-keyboard-navigation - Keyboard navigation instant, no animation none-context-menu-entrance - Context menus: no entrance, exit only 3. Exit Animations (HIGH) exit-requires-wrapper - Conditional motion elements need AnimatePresence wrapper exit-prop-required - Elements in AnimatePresence need exit prop exit-key-required - Dynamic lists need unique keys, not index exit-matches-initial - Exit mirrors initial for symmetry presence-hook-in-child - useIsPresent in child, not parent presence-safe-to-remove - Call safeToRemove after async cleanup presence-disable-interactions - Disable interactions on exiting elements mode-wait-doubles-duration - Mode "wait" doubles duration; halve timing mode-sync-layout-conflict - Mode "sync" causes layout conflicts mode-pop-layout-for-lists - Use popLayout for list reordering nested-propagate-required - Nested AnimatePresence needs propagate prop nested-consistent-timing - Coordinate parent-child exit durations 4. CSS Pseudo Elements (MEDIUM) pseudo-content-required - ::before/::after need content property pseudo-over-dom-node - Pseudo-elements over extra DOM nodes for decoration pseudo-position-relative-parent - Parent needs position: relative pseudo-z-index-layering - Z-index for correct pseudo-element layering pseudo-hit-target-expansion - Negative inset for larger hit targets transition-name-required - View transitions need view-transition-name transition-name-unique - Each transition name unique during transition transition-name-cleanup - Remove transition name after completion transition-over-js-library - Prefer View Transitions API over JS libraries transition-style-pseudo-elements - Style ::view-transition-group for custom animations native-backdrop-styling - Use ::backdrop for dialog backgrounds native-placeholder-styling - Use ::placeholder for input styling native-selection-styling - Use ::selection for text selection styling 5. Audio Feedback (MEDIUM) a11y-visual-equivalent - Every sound must have a visual equivalent a11y-toggle-setting - Provide toggle to disable sounds a11y-reduced-motion-check - Respect prefers-reduced-motion for sound a11y-volume-control - Allow independent volume adjustment appropriate-no-high-frequency - No sound on typing or keyboard nav appropriate-confirmations-only - Sound for payments, uploads, submissions appropriate-errors-warnings - Sound for errors that can't be overlooked appropriate-no-decorative - No sound on hover or decorative moments appropriate-no-punishing - Inform, don't punish with harsh sounds impl-preload-audio - Preload audio files to avoid delay impl-default-subtle - Default volume subtle (0.3), not loud impl-reset-current-time - Reset currentTime before replay weight-match-action - Sound weight matches action importance weight-duration-matches-action - Sound duration matches action duration 6. Sound Synthesis (MEDIUM) context-reuse-single - Reuse single AudioContext, don't create per sound context-resume-suspended - Resume suspended AudioContext before playing context-cleanup-nodes - Disconnect audio nodes after playback envelope-exponential-decay - Exponential ramps for natural decay envelope-no-zero-target - Exponential ramps target 0.001, not 0 envelope-set-initial-value - Set initial value before ramping design-noise-for-percussion - Filtered noise for clicks/taps design-oscillator-for-tonal - Oscillators with pitch sweep for tonal sounds design-filter-for-character - Bandpass filter to shape percussive sounds param-click-duration - Click sounds: 5-15ms duration param-filter-frequency-range - Click filter: 3000-6000Hz param-reasonable-gain - Gain under 1.0 to prevent clipping param-q-value-range - Filter Q: 2-5 for focused but natural 7. Morphing Icons (LOW) morphing-three-lines - Every icon uses exactly 3 SVG lines morphing-use-collapsed - Unused lines use collapsed constant morphing-consistent-viewbox - All icons share same viewBox (14x14) morphing-group-variants - Rotational variants share group and base lines morphing-spring-rotation - Spring physics for grouped icon rotation morphing-reduced-motion - Respect prefers-reduced-motion morphing-jump-non-grouped - Instant rotation jump between non-grouped icons morphing-strokelinecap-round - Round stroke line caps morphing-aria-hidden - Icon SVGs are aria-hidden 8. Container Animation (MEDIUM) container-two-div-pattern - Outer animated div, inner measured div; never same element container-guard-initial-zero - Guard bounds === 0 on initial render, fall back to "auto" container-use-resize-observer - Use ResizeObserver for measurement, not getBoundingClientRect container-overflow-hidden - Set overflow: hidden on animated container during transitions container-no-excessive-use - Use sparingly: buttons, accordions, interactive elements container-callback-ref - Use callback ref (not useRef) for measurement hooks 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-elements ux-hicks-minimize-choices - Minimize choices to reduce decision time ux-millers-chunking - Chunk data into groups of 5-9 for scannability ux-doherty-under-400ms - Respond within 400ms to feel instant ux-doherty-perceived-speed - Fake speed with skeletons, optimistic UI, progress indicators ux-postels-accept-messy-input - Accept messy input, output clean data ux-progressive-disclosure - Show what matters now, reveal complexity later 10. Predictive Prefetching (MEDIUM) prefetch-trajectory-over-hover - Trajectory prediction over hover; reclaims 100-200ms prefetch-not-everything - Prefetch by intent, not viewport; avoid wasted bandwidth prefetch-hit-slop - Use hitSlop to trigger predictions earlier prefetch-touch-fallback - Fall back gracefully on touch devices (no cursor) prefetch-keyboard-tab - Prefetch on keyboard navigation when focus approaches prefetch-use-selectively - Use predictive prefetching where latency is noticeable 11. Typography (MEDIUM) type-tabular-nums-for-data - Tabular numbers for columns, dashboards, pricing type-oldstyle-nums-for-prose - Oldstyle numbers blend into body text type-slashed-zero - Slashed zero in code-adjacent UIs type-opentype-contextual-alternates - Keep calt enabled for contextual glyph adjustment type-disambiguation-stylistic-set - Enable ss02 to distinguish I/l/1 and 0/O type-optical-sizing-auto - Leave font-optical-sizing auto for size-adaptive glyphs type-antialiased-on-retina - Antialiased font smoothing on retina displays type-text-wrap-balance-headings - text-wrap: balance on headings for even lines type-underline-offset - Offset underlines below descenders type-no-font-synthesis - Disable font-synthesis to prevent faux bold/italic 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.mdWeekly Installs447Repositoryraphaelsalaja/u…ace-wikiGitHub Stars324First Seen1 day agoSecurity AuditsGen Agent Trust HubPassSocketPassSnykPassInstalled oncodex443gemini-cli441amp441github-copilot441opencode441cursor441