1---
2name: userinterface-wiki
3description: 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.
4license: MIT
5metadata:
6  author: raphael-salaja
7  version: "3.0.0"
8---
9 
10# User Interface Wiki
11 
12Comprehensive UI/UX best practices guide for web interfaces. Contains 152 rules across 12 categories, prioritized by impact to guide automated code review and generation.
13 
14## When to Apply
15 
16Reference these guidelines when:
17- Implementing or reviewing animations (CSS transitions, Motion/Framer Motion)
18- Choosing between springs, easing curves, or no animation
19- Working with AnimatePresence and exit animations
20- Writing CSS with pseudo-elements or View Transitions API
21- Adding audio feedback or procedural sound to UI
22- Building morphing icon components
23- Animating container width/height with dynamic content
24- Designing UI that respects cognitive psychology (Fitts's, Hick's, Miller's laws)
25- Implementing predictive prefetching for perceived performance
26- Setting up typography, OpenType features, or numeric formatting
27 
28## Rule Categories by Priority
29 
30| Priority | Category | Impact | Prefixes |
31|----------|----------|--------|----------|
32| 1 | Animation Principles | CRITICAL | `timing-`, `physics-`, `staging-` |
33| 2 | Timing Functions | HIGH | `spring-`, `easing-`, `duration-`, `none-` |
34| 3 | Exit Animations | HIGH | `exit-`, `presence-`, `mode-`, `nested-` |
35| 4 | CSS Pseudo Elements | MEDIUM | `pseudo-`, `transition-`, `native-` |
36| 5 | Audio Feedback | MEDIUM | `a11y-`, `appropriate-`, `impl-`, `weight-` |
37| 6 | Sound Synthesis | MEDIUM | `context-`, `envelope-`, `design-`, `param-` |
38| 7 | Morphing Icons | LOW | `morphing-` |
39| 8 | Container Animation | MEDIUM | `container-` |
40| 9 | Laws of UX | HIGH | `ux-` |
41| 10 | Predictive Prefetching | MEDIUM | `prefetch-` |
42| 11 | Typography | MEDIUM | `type-` |
43| 12 | Visual Design | HIGH | `visual-` |
44 
45## Quick Reference
46 
47### 1. Animation Principles (CRITICAL)
48 
49- `timing-under-300ms` - User animations must complete within 300ms
50- `timing-consistent` - Similar elements use identical timing values
51- `timing-no-entrance-context-menu` - Context menus: no entrance animation, exit only
52- `easing-natural-decay` - Use exponential ramps for natural decay, not linear
53- `easing-no-linear-motion` - Linear easing only for progress indicators
54- `physics-active-state` - Interactive elements need :active scale transform
55- `physics-subtle-deformation` - Squash/stretch in 0.95-1.05 range
56- `physics-spring-for-overshoot` - Springs for overshoot-and-settle, not easing
57- `physics-no-excessive-stagger` - Stagger delays under 50ms per item
58- `staging-one-focal-point` - One prominent animation at a time
59- `staging-dim-background` - Dim modal/dialog backgrounds
60- `staging-z-index-hierarchy` - Animated elements respect z-index layers
61 
62### 2. Timing Functions (HIGH)
63 
64- `spring-for-gestures` - Gesture-driven motion (drag, flick) must use springs
65- `spring-for-interruptible` - Interruptible motion must use springs
66- `spring-preserves-velocity` - Springs preserve input energy on release
67- `spring-params-balanced` - Avoid excessive oscillation in spring params
68- `easing-for-state-change` - System state changes use easing curves
69- `easing-entrance-ease-out` - Entrances use ease-out
70- `easing-exit-ease-in` - Exits use ease-in
71- `easing-transition-ease-in-out` - View transitions use ease-in-out
72- `easing-linear-only-progress` - Linear only for progress/time representation
73- `duration-press-hover` - Press/hover: 120-180ms
74- `duration-small-state` - Small state changes: 180-260ms
75- `duration-max-300ms` - User-initiated max 300ms
76- `duration-shorten-before-curve` - Fix slow feel with shorter duration, not curve
77- `none-high-frequency` - No animation for high-frequency interactions
78- `none-keyboard-navigation` - Keyboard navigation instant, no animation
79- `none-context-menu-entrance` - Context menus: no entrance, exit only
80 
81### 3. Exit Animations (HIGH)
82 
83- `exit-requires-wrapper` - Conditional motion elements need AnimatePresence wrapper
84- `exit-prop-required` - Elements in AnimatePresence need exit prop
85- `exit-key-required` - Dynamic lists need unique keys, not index
86- `exit-matches-initial` - Exit mirrors initial for symmetry
87- `presence-hook-in-child` - useIsPresent in child, not parent
88- `presence-safe-to-remove` - Call safeToRemove after async cleanup
89- `presence-disable-interactions` - Disable interactions on exiting elements
90- `mode-wait-doubles-duration` - Mode "wait" doubles duration; halve timing
91- `mode-sync-layout-conflict` - Mode "sync" causes layout conflicts
92- `mode-pop-layout-for-lists` - Use popLayout for list reordering
93- `nested-propagate-required` - Nested AnimatePresence needs propagate prop
94- `nested-consistent-timing` - Coordinate parent-child exit durations
95 
96### 4. CSS Pseudo Elements (MEDIUM)
97 
98- `pseudo-content-required` - ::before/::after need content property
99- `pseudo-over-dom-node` - Pseudo-elements over extra DOM nodes for decoration
100- `pseudo-position-relative-parent` - Parent needs position: relative
101- `pseudo-z-index-layering` - Z-index for correct pseudo-element layering
102- `pseudo-hit-target-expansion` - Negative inset for larger hit targets
103- `pseudo-marker-styling` - Use ::marker for custom list bullet styles
104- `pseudo-first-line-styling` - Use ::first-line for typographic treatments
105- `transition-name-required` - View transitions need view-transition-name
106- `transition-name-unique` - Each transition name unique during transition
107- `transition-name-cleanup` - Remove transition name after completion
108- `transition-over-js-library` - Prefer View Transitions API over JS libraries
109- `transition-style-pseudo-elements` - Style ::view-transition-group for custom animations
110- `native-backdrop-styling` - Use ::backdrop for dialog backgrounds
111- `native-placeholder-styling` - Use ::placeholder for input styling
112- `native-selection-styling` - Use ::selection for text selection styling
113 
114### 5. Audio Feedback (MEDIUM)
115 
116- `a11y-visual-equivalent` - Every sound must have a visual equivalent
117- `a11y-toggle-setting` - Provide toggle to disable sounds
118- `a11y-reduced-motion-check` - Respect prefers-reduced-motion for sound
119- `a11y-volume-control` - Allow independent volume adjustment
120- `appropriate-no-high-frequency` - No sound on typing or keyboard nav
121- `appropriate-confirmations-only` - Sound for payments, uploads, submissions
122- `appropriate-errors-warnings` - Sound for errors that can't be overlooked
123- `appropriate-no-decorative` - No sound on hover or decorative moments
124- `appropriate-no-punishing` - Inform, don't punish with harsh sounds
125- `impl-preload-audio` - Preload audio files to avoid delay
126- `impl-default-subtle` - Default volume subtle (0.3), not loud
127- `impl-reset-current-time` - Reset currentTime before replay
128- `weight-match-action` - Sound weight matches action importance
129- `weight-duration-matches-action` - Sound duration matches action duration
130 
131### 6. Sound Synthesis (MEDIUM)
132 
133- `context-reuse-single` - Reuse single AudioContext, don't create per sound
134- `context-resume-suspended` - Resume suspended AudioContext before playing
135- `context-cleanup-nodes` - Disconnect audio nodes after playback
136- `envelope-exponential-decay` - Exponential ramps for natural decay
137- `envelope-no-zero-target` - Exponential ramps target 0.001, not 0
138- `envelope-set-initial-value` - Set initial value before ramping
139- `design-noise-for-percussion` - Filtered noise for clicks/taps
140- `design-oscillator-for-tonal` - Oscillators with pitch sweep for tonal sounds
141- `design-filter-for-character` - Bandpass filter to shape percussive sounds
142- `param-click-duration` - Click sounds: 5-15ms duration
143- `param-filter-frequency-range` - Click filter: 3000-6000Hz
144- `param-reasonable-gain` - Gain under 1.0 to prevent clipping
145- `param-q-value-range` - Filter Q: 2-5 for focused but natural
146 
147### 7. Morphing Icons (LOW)
148 
149- `morphing-three-lines` - Every icon uses exactly 3 SVG lines
150- `morphing-use-collapsed` - Unused lines use collapsed constant
151- `morphing-consistent-viewbox` - All icons share same viewBox (14x14)
152- `morphing-group-variants` - Rotational variants share group and base lines
153- `morphing-spring-rotation` - Spring physics for grouped icon rotation
154- `morphing-reduced-motion` - Respect prefers-reduced-motion
155- `morphing-jump-non-grouped` - Instant rotation jump between non-grouped icons
156- `morphing-strokelinecap-round` - Round stroke line caps
157- `morphing-aria-hidden` - Icon SVGs are aria-hidden
158 
159### 8. Container Animation (MEDIUM)
160 
161- `container-two-div-pattern` - Outer animated div, inner measured div; never same element
162- `container-guard-initial-zero` - Guard bounds === 0 on initial render, fall back to "auto"
163- `container-use-resize-observer` - Use ResizeObserver for measurement, not getBoundingClientRect
164- `container-overflow-hidden` - Set overflow: hidden on animated container during transitions
165- `container-no-excessive-use` - Use sparingly: buttons, accordions, interactive elements
166- `container-callback-ref` - Use callback ref (not useRef) for measurement hooks
167- `container-transition-delay` - Add small delay for natural catching-up feel
168 
169### 9. Laws of UX (HIGH)
170 
171- `ux-fitts-target-size` - Size interactive targets for easy clicking (min 32px)
172- `ux-fitts-hit-area` - Expand hit areas with invisible padding or pseudo-elements
173- `ux-hicks-minimize-choices` - Minimize choices to reduce decision time
174- `ux-millers-chunking` - Chunk data into groups of 5-9 for scannability
175- `ux-doherty-under-400ms` - Respond within 400ms to feel instant
176- `ux-doherty-perceived-speed` - Fake speed with skeletons, optimistic UI, progress indicators
177- `ux-postels-accept-messy-input` - Accept messy input, output clean data
178- `ux-progressive-disclosure` - Show what matters now, reveal complexity later
179- `ux-jakobs-familiar-patterns` - Use familiar UI patterns users know from other sites
180- `ux-aesthetic-usability` - Visual polish increases perceived usability
181- `ux-proximity-grouping` - Group related elements spatially with tighter spacing
182- `ux-similarity-consistency` - Similar elements should look alike
183- `ux-common-region-boundaries` - Use boundaries to group related content
184- `ux-von-restorff-emphasis` - Make important elements visually distinct
185- `ux-serial-position` - Place key items first or last in sequences
186- `ux-peak-end-finish-strong` - End experiences with clear success states
187- `ux-teslers-complexity` - Move complexity to the system, not the user
188- `ux-goal-gradient-progress` - Show progress toward completion
189- `ux-zeigarnik-show-incomplete` - Show incomplete state to drive completion
190- `ux-pragnanz-simplify` - Simplify complex visuals into clear forms
191- `ux-pareto-prioritize-features` - Prioritize the critical 20% of features
192- `ux-cognitive-load-reduce` - Minimize extraneous cognitive load
193- `ux-uniform-connectedness` - Visually connect related elements with lines or frames
194 
195### 10. Predictive Prefetching (MEDIUM)
196 
197- `prefetch-trajectory-over-hover` - Trajectory prediction over hover; reclaims 100-200ms
198- `prefetch-not-everything` - Prefetch by intent, not viewport; avoid wasted bandwidth
199- `prefetch-hit-slop` - Use hitSlop to trigger predictions earlier
200- `prefetch-touch-fallback` - Fall back gracefully on touch devices (no cursor)
201- `prefetch-keyboard-tab` - Prefetch on keyboard navigation when focus approaches
202- `prefetch-use-selectively` - Use predictive prefetching where latency is noticeable
203 
204### 11. Typography (MEDIUM)
205 
206- `type-tabular-nums-for-data` - Tabular numbers for columns, dashboards, pricing
207- `type-oldstyle-nums-for-prose` - Oldstyle numbers blend into body text
208- `type-slashed-zero` - Slashed zero in code-adjacent UIs
209- `type-opentype-contextual-alternates` - Keep calt enabled for contextual glyph adjustment
210- `type-disambiguation-stylistic-set` - Enable ss02 to distinguish I/l/1 and 0/O
211- `type-optical-sizing-auto` - Leave font-optical-sizing auto for size-adaptive glyphs
212- `type-antialiased-on-retina` - Antialiased font smoothing on retina displays
213- `type-text-wrap-balance-headings` - text-wrap: balance on headings for even lines
214- `type-underline-offset` - Offset underlines below descenders
215- `type-no-font-synthesis` - Disable font-synthesis to prevent faux bold/italic
216- `type-font-display-swap` - Use font-display: swap to avoid invisible text during load
217- `type-variable-weight-continuous` - Use continuous weight values (100-900) with variable fonts
218- `type-text-wrap-pretty` - text-wrap: pretty for body text to reduce orphans
219- `type-justify-with-hyphens` - Pair text-align: justify with hyphens: auto
220- `type-letter-spacing-uppercase` - Add letter-spacing to uppercase and small-caps text
221- `type-proper-fractions` - Use diagonal-fractions for proper typographic fractions
222 
223### 12. Visual Design (HIGH)
224 
225- `visual-concentric-radius` - Inner radius = outer radius minus padding for nested elements
226- `visual-layered-shadows` - Layer multiple shadows for realistic depth
227- `visual-shadow-direction` - All shadows share same offset direction (single light source)
228- `visual-no-pure-black-shadow` - Use neutral colors, not pure black, for shadows
229- `visual-shadow-matches-elevation` - Shadow size indicates elevation in consistent scale
230- `visual-animate-shadow-pseudo` - Animate shadow via pseudo-element opacity for performance
231- `visual-consistent-spacing-scale` - Use a consistent spacing scale, not arbitrary values
232- `visual-border-alpha-colors` - Semi-transparent borders adapt to any background
233- `visual-button-shadow-anatomy` - Six-layer shadow anatomy for polished buttons
234 
235## How to Use
236 
237Read individual rule files for detailed explanations and code examples:
238 
239```
240rules/timing-under-300ms.md
241rules/spring-for-gestures.md
242rules/ux-doherty-under-400ms.md
243rules/type-tabular-nums-for-data.md
244```
245 
246Each rule file contains:
247- Brief explanation of why it matters
248- Incorrect code example with explanation
249- Correct code example with explanation
250 
251## Full Compiled Document
252 
253For the complete guide with all rules expanded: `AGENTS.md`
254