userinterface-wiki

What this skill does

# 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 ::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` - Spr