🇺🇸English

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

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

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

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

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

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

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

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
• container-transition-delay - Add small delay for natural catching-up feel

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
• - Use familiar UI patterns users know from other sites

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

12. Visual Design (HIGH)

• visual-concentric-radius - Inner radius = outer radius minus padding for nested elements
• visual-layered-shadows - Layer multiple shadows for realistic depth
• visual-shadow-direction - All shadows share same offset direction (single light source)
• visual-no-pure-black-shadow - Use neutral colors, not pure black, for shadows
• visual-shadow-matches-elevation - Shadow size indicates elevation in consistent scale
• visual-animate-shadow-pseudo - Animate shadow via pseudo-element opacity for performance
• visual-consistent-spacing-scale - Use a consistent spacing scale, not arbitrary values
• visual-border-alpha-colors - Semi-transparent borders adapt to any background

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.md

Weekly Installs

1.6K

Repository

raphaelsalaja/u…ace-wiki

GitHub Stars

624

First Seen

8 days ago

Security Audits

Gen Agent Trust HubPassSocketPassSnykPass

Installed on

codex1.6K

cursor1.6K

opencode1.6K

github-copilot1.6K

gemini-cli1.6K

amp1.6K