Userinterface Wiki

# User Interface Wiki

**Version 3.0.0**
raphael-salaja
March 2026

> **Note:**
> This document is mainly for agents and LLMs to follow when reviewing,
> generating, or refactoring UI code. Humans may also find it useful, but
> guidance here is optimized for automation and consistency by AI-assisted workflows.

---

## Abstract

Comprehensive UI/UX best practices guide for web interfaces, designed for AI agents and LLMs. Contains 152 rules across 12 categories, prioritized by impact from critical (animation principles, timing functions) to incremental (morphing icons, typography). Each rule includes detailed explanations and code examples comparing incorrect vs. correct implementations.

---

## Table of Contents

1. [Animation Principles](#1-animation-principles) — **CRITICAL**
   - 1.1 [User Animations Under 300ms](#11-user-animations-under-300ms)
   - 1.2 [Consistent Timing for Similar Elements](#12-consistent-timing-for-similar-elements)
   - 1.3 [No Entrance Animation on Context Menus](#13-no-entrance-animation-on-context-menus)
   - 1.4 [Exponential Ramps for Natural Decay](#14-exponential-ramps-for-natural-decay)
   - 1.5 [No Linear Easing for Motion](#15-no-linear-easing-for-motion)
   - 1.6 [Active State Scale Transform](#16-active-state-scale-transform)
   - 1.7 [Subtle Squash and Stretch](#17-subtle-squash-and-stretch)
   - 1.8 [Springs for Overshoot and Settle](#18-springs-for-overshoot-and-settle)
   - 1.9 [Stagger Under 50ms Per Item](#19-stagger-under-50ms-per-item)
   - 1.10 [Single Focal Point](#110-single-focal-point)
   - 1.11 [Dim Background for Focus](#111-dim-background-for-focus)
   - 1.12 [Z-Index Layering for Animated Elements](#112-z-index-layering-for-animated-elements)
2. [Timing Functions](#2-timing-functions) — **HIGH**
   - 2.1 [Springs for Gesture-Driven Motion](#21-springs-for-gesture-driven-motion)
   - 2.2 [Springs for Interruptible Motion](#22-springs-for-interruptible-motion)
   - 2.3 [Springs Preserve Input Velocity](#23-springs-preserve-input-velocity)
   - 2.4 [Balanced Spring Parameters](#24-balanced-spring-parameters)
   - 2.5 [Easing for System State Changes](#25-easing-for-system-state-changes)
   - 2.6 [Ease-Out for Entrances](#26-ease-out-for-entrances)
   - 2.7 [Ease-In for Exits](#27-ease-in-for-exits)
   - 2.8 [Ease-In-Out for View Transitions](#28-ease-in-out-for-view-transitions)
   - 2.9 [Linear Easing Only for Progress](#29-linear-easing-only-for-progress)
   - 2.10 [Press and Hover 120-180ms](#210-press-and-hover-120-180ms)
   - 2.11 [Small State Changes 180-260ms](#211-small-state-changes-180-260ms)
   - 2.12 [Max 300ms for User Actions](#212-max-300ms-for-user-actions)
   - 2.13 [Shorten Duration Before Adjusting Curve](#213-shorten-duration-before-adjusting-curve)
   - 2.14 [No Animation for High-Frequency Interactions](#214-no-animation-for-high-frequency-interactions)
   - 2.15 [No Animation for Keyboard Navigation](#215-no-animation-for-keyboard-navigation)
   - 2.16 [No Entrance Animation for Context Menus](#216-no-entrance-animation-for-context-menus)
3. [Exit Animations](#3-exit-animations) — **HIGH**
   - 3.1 [AnimatePresence Wrapper Required](#31-animatepresence-wrapper-required)
   - 3.2 [Exit Prop Required Inside AnimatePresence](#32-exit-prop-required-inside-animatepresence)
   - 3.3 [Unique Keys in AnimatePresence Lists](#33-unique-keys-in-animatepresence-lists)
   - 3.4 [Exit Mirrors Initial for Symmetry](#34-exit-mirrors-initial-for-symmetry)
   - 3.5 [useIsPresent in Child Component](#35-useispresent-in-child-component)
   - 3.6 [Call safeToRemove After Async Work](#36-call-safetoremove-after-async-work)
   - 3.7 [Disable Interactions on Exiting Elements](#37-disable-interactions-on-exiting-elements)
   - 3.8 [Mode "wait" Doubles Duration](#38-mode-wait-doubles-duration)
   - 3.9 [Mode "sync" Causes Layout Conflicts](#39-mode-sync-causes-layout-conflicts)
   - 3.10 [popLayout for List Reordering](#310-poplayout-for-list-reordering)
   - 3.11 [Propagate Pro