/userinterface-wiki

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 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
• `pseudo-marker-styling` - Use ::marker for custom list bullet styles
• `pseudo-first-line-styling` - Use ::first-line for typographic treatments
• `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 ::placehol