|
| 1 | +--- |
| 2 | +name: userinterface-wiki |
| 3 | +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. |
| 4 | +license: MIT |
| 5 | +metadata: |
| 6 | + author: raphael-salaja |
| 7 | + version: "3.0.0" |
| 8 | +--- |
| 9 | + |
| 10 | +# User Interface Wiki |
| 11 | + |
| 12 | +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. |
| 13 | + |
| 14 | +## When to Apply |
| 15 | + |
| 16 | +Reference 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 | + |
| 237 | +Read individual rule files for detailed explanations and code examples: |
| 238 | + |
| 239 | +``` |
| 240 | +rules/timing-under-300ms.md |
| 241 | +rules/spring-for-gestures.md |
| 242 | +rules/ux-doherty-under-400ms.md |
| 243 | +rules/type-tabular-nums-for-data.md |
| 244 | +``` |
| 245 | + |
| 246 | +Each 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 | + |
| 253 | +For the complete guide with all rules expanded: `AGENTS.md` |
0 commit comments