niahere 0.2.61 → 0.2.63

package/skills/userinterface-wiki/AGENTS.md

@@ -0,0 +1,3749 @@
+# 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 Prop for Nested AnimatePresence](#311-propagate-prop-for-nested-animatepresence)
+   - 3.12 [Coordinated Parent-Child Exit Timing](#312-coordinated-parent-child-exit-timing)
+4. [CSS Pseudo Elements](#4-css-pseudo-elements) — **MEDIUM**
+   - 4.1 [Content Property Required for Pseudo-Elements](#41-content-property-required-for-pseudo-elements)
+   - 4.2 [Pseudo-Elements Over DOM Nodes](#42-pseudo-elements-over-dom-nodes)
+   - 4.3 [Position Relative Parent for Pseudo-Elements](#43-position-relative-parent-for-pseudo-elements)
+   - 4.4 [Z-Index Layering for Pseudo-Elements](#44-z-index-layering-for-pseudo-elements)
+   - 4.5 [Hit Target Expansion with Pseudo-Elements](#45-hit-target-expansion-with-pseudo-elements)
+   - 4.6 [View Transition Name Required](#46-view-transition-name-required)
+   - 4.7 [Unique View Transition Names](#47-unique-view-transition-names)
+   - 4.8 [Clean Up View Transition Names](#48-clean-up-view-transition-names)
+   - 4.9 [View Transitions Over JS Libraries](#49-view-transitions-over-js-libraries)
+   - 4.10 [Style View Transition Pseudo-Elements](#410-style-view-transition-pseudo-elements)
+   - 4.11 [Use ::backdrop for Dialog Backgrounds](#411-use-backdrop-for-dialog-backgrounds)
+   - 4.12 [Use ::placeholder for Input Styling](#412-use-placeholder-for-input-styling)
+   - 4.13 [Use ::selection for Text Styling](#413-use-selection-for-text-styling)
+   - 4.14 [Use ::marker for Custom List Bullets](#414-use-marker-for-custom-list-bullets)
+   - 4.15 [Use ::first-line for Typographic Treatments](#415-use-first-line-for-typographic-treatments)
+5. [Audio Feedback](#5-audio-feedback) — **MEDIUM**
+   - 5.1 [Visual Equivalent for Every Sound](#51-visual-equivalent-for-every-sound)
+   - 5.2 [Toggle Setting to Disable Sounds](#52-toggle-setting-to-disable-sounds)
+   - 5.3 [Respect prefers-reduced-motion for Sound](#53-respect-prefers-reduced-motion-for-sound)
+   - 5.4 [Independent Volume Control](#54-independent-volume-control)
+   - 5.5 [No Sound on High-Frequency Interactions](#55-no-sound-on-high-frequency-interactions)
+   - 5.6 [Sound for Confirmations](#56-sound-for-confirmations)
+   - 5.7 [Sound for Errors and Warnings](#57-sound-for-errors-and-warnings)
+   - 5.8 [No Decorative Sound](#58-no-decorative-sound)
+   - 5.9 [Informative Not Punishing Sound](#59-informative-not-punishing-sound)
+   - 5.10 [Preload Audio Files](#510-preload-audio-files)
+   - 5.11 [Subtle Default Volume](#511-subtle-default-volume)
+   - 5.12 [Reset currentTime Before Replay](#512-reset-currenttime-before-replay)
+   - 5.13 [Match Sound Weight to Action](#513-match-sound-weight-to-action)
+   - 5.14 [Sound Duration Matches Action Duration](#514-sound-duration-matches-action-duration)
+6. [Sound Synthesis](#6-sound-synthesis) — **MEDIUM**
+   - 6.1 [Reuse Single AudioContext](#61-reuse-single-audiocontext)
+   - 6.2 [Resume Suspended AudioContext](#62-resume-suspended-audiocontext)
+   - 6.3 [Clean Up Audio Nodes After Playback](#63-clean-up-audio-nodes-after-playback)
+   - 6.4 [Exponential Decay for Natural Sound](#64-exponential-decay-for-natural-sound)
+   - 6.5 [No Zero Target for Exponential Ramps](#65-no-zero-target-for-exponential-ramps)
+   - 6.6 [Set Initial Value Before Ramp](#66-set-initial-value-before-ramp)
+   - 6.7 [Noise for Percussive Sounds](#67-noise-for-percussive-sounds)
+   - 6.8 [Oscillators for Tonal Sounds](#68-oscillators-for-tonal-sounds)
+   - 6.9 [Bandpass Filter for Sound Character](#69-bandpass-filter-for-sound-character)
+   - 6.10 [Click Duration 5-15ms](#610-click-duration-5-15ms)
+   - 6.11 [Click Filter 3000-6000Hz](#611-click-filter-3000-6000hz)
+   - 6.12 [Gain Under 1.0](#612-gain-under-10)
+   - 6.13 [Filter Q Value 2-5](#613-filter-q-value-2-5)
+7. [Morphing Icons](#7-morphing-icons) — **LOW**
+   - 7.1 [Icons Must Use Exactly Three Lines](#71-icons-must-use-exactly-three-lines)
+   - 7.2 [Use Collapsed Constant for Unused Lines](#72-use-collapsed-constant-for-unused-lines)
+   - 7.3 [Consistent ViewBox Size](#73-consistent-viewbox-size)
+   - 7.4 [Shared Group for Rotational Variants](#74-shared-group-for-rotational-variants)
+   - 7.5 [Spring Physics for Rotation](#75-spring-physics-for-rotation)
+   - 7.6 [Reduced Motion Support for Icons](#76-reduced-motion-support-for-icons)
+   - 7.7 [Instant Jump for Non-Grouped Icons](#77-instant-jump-for-non-grouped-icons)
+   - 7.8 [Round Stroke Line Caps](#78-round-stroke-line-caps)
+   - 7.9 [Aria Hidden on Icon SVGs](#79-aria-hidden-on-icon-svgs)
+8. [Container Animation](#8-container-animation) — **MEDIUM**
+   - 8.1 [Two-Div Pattern for Animated Bounds](#81-two-div-pattern-for-animated-bounds)
+   - 8.2 [Guard Against Zero on Initial Render](#82-guard-against-zero-on-initial-render)
+   - 8.3 [Use ResizeObserver for Measurement](#83-use-resizeobserver-for-measurement)
+   - 8.4 [Overflow Hidden on Animated Container](#84-overflow-hidden-on-animated-container)
+   - 8.5 [Use Animated Bounds Sparingly](#85-use-animated-bounds-sparingly)
+   - 8.6 [Use Callback Ref for Measurement](#86-use-callback-ref-for-measurement)
+   - 8.7 [Add Delay for Natural Container Transitions](#87-add-delay-for-natural-container-transitions)
+9. [Laws of UX](#9-laws-of-ux) — **HIGH**
+   - 9.1 [Size Interactive Targets for Easy Clicking](#91-size-interactive-targets-for-easy-clicking)
+   - 9.2 [Expand Hit Areas with Invisible Padding](#92-expand-hit-areas-with-invisible-padding)
+   - 9.3 [Minimize Choices to Reduce Decision Time](#93-minimize-choices-to-reduce-decision-time)
+   - 9.4 [Chunk Data into Groups of 5-9](#94-chunk-data-into-groups-of-5-9)
+   - 9.5 [Respond Within 400ms](#95-respond-within-400ms)
+   - 9.6 [Fake Speed When Actual Speed Isn't Possible](#96-fake-speed-when-actual-speed-isnt-possible)
+   - 9.7 [Accept Messy Input, Output Clean Data](#97-accept-messy-input-output-clean-data)
+   - 9.8 [Show What Matters Now, Reveal Complexity Later](#98-show-what-matters-now-reveal-complexity-later)
+   - 9.9 [Use Familiar UI Patterns](#99-use-familiar-ui-patterns)
+   - 9.10 [Visual Polish Increases Perceived Usability](#910-visual-polish-increases-perceived-usability)
+   - 9.11 [Group Related Elements Spatially](#911-group-related-elements-spatially)
+   - 9.12 [Similar Elements Should Look Alike](#912-similar-elements-should-look-alike)
+   - 9.13 [Use Boundaries to Group Related Content](#913-use-boundaries-to-group-related-content)
+   - 9.14 [Make Important Elements Visually Distinct](#914-make-important-elements-visually-distinct)
+   - 9.15 [Place Key Items First or Last](#915-place-key-items-first-or-last)
+   - 9.16 [End Experiences with Clear Success States](#916-end-experiences-with-clear-success-states)
+   - 9.17 [Move Complexity to the System](#917-move-complexity-to-the-system)
+   - 9.18 [Show Progress Toward Completion](#918-show-progress-toward-completion)
+   - 9.19 [Show Incomplete State to Drive Completion](#919-show-incomplete-state-to-drive-completion)
+   - 9.20 [Simplify Complex Visuals into Clear Forms](#920-simplify-complex-visuals-into-clear-forms)
+   - 9.21 [Prioritize the Critical 20% of Features](#921-prioritize-the-critical-20-of-features)
+   - 9.22 [Minimize Extraneous Cognitive Load](#922-minimize-extraneous-cognitive-load)
+   - 9.23 [Visually Connect Related Elements](#923-visually-connect-related-elements)
+10. [Predictive Prefetching](#10-predictive-prefetching) — **MEDIUM**
+    - 10.1 [Trajectory Prediction Over Hover Prefetching](#101-trajectory-prediction-over-hover-prefetching)
+    - 10.2 [Prefetch by Intent, Not Viewport](#102-prefetch-by-intent-not-viewport)
+    - 10.3 [Use hitSlop to Trigger Predictions Earlier](#103-use-hitslop-to-trigger-predictions-earlier)
+    - 10.4 [Fall Back Gracefully on Touch Devices](#104-fall-back-gracefully-on-touch-devices)
+    - 10.5 [Prefetch on Keyboard Navigation](#105-prefetch-on-keyboard-navigation)
+    - 10.6 [Use Predictive Prefetching Selectively](#106-use-predictive-prefetching-selectively)
+11. [Typography](#11-typography) — **MEDIUM**
+    - 11.1 [Tabular Numbers for Data Display](#111-tabular-numbers-for-data-display)
+    - 11.2 [Oldstyle Numbers for Body Text](#112-oldstyle-numbers-for-body-text)
+    - 11.3 [Slashed Zero for Disambiguation](#113-slashed-zero-for-disambiguation)
+    - 11.4 [Enable Contextual Alternates](#114-enable-contextual-alternates)
+    - 11.5 [Use Disambiguation Stylistic Set for UI](#115-use-disambiguation-stylistic-set-for-ui)
+    - 11.6 [Keep Optical Sizing Auto](#116-keep-optical-sizing-auto)
+    - 11.7 [Use Antialiased Font Smoothing](#117-use-antialiased-font-smoothing)
+    - 11.8 [Balance Headings with text-wrap](#118-balance-headings-with-text-wrap)
+    - 11.9 [Offset Underlines from Descenders](#119-offset-underlines-from-descenders)
+    - 11.10 [Disable Font Synthesis for Missing Styles](#1110-disable-font-synthesis-for-missing-styles)
+    - 11.11 [Use font-display swap](#1111-use-font-display-swap)
+    - 11.12 [Continuous Weight Values with Variable Fonts](#1112-continuous-weight-values-with-variable-fonts)
+    - 11.13 [text-wrap pretty for Body Text](#1113-text-wrap-pretty-for-body-text)
+    - 11.14 [Pair Justified Text with Hyphens](#1114-pair-justified-text-with-hyphens)
+    - 11.15 [Add Letter Spacing to Uppercase Text](#1115-add-letter-spacing-to-uppercase-text)
+    - 11.16 [Use Typographic Fractions](#1116-use-typographic-fractions)
+12. [Visual Design](#12-visual-design) — **HIGH**
+    - 12.1 [Concentric Border Radius for Nested Elements](#121-concentric-border-radius-for-nested-elements)
+    - 12.2 [Layer Multiple Shadows for Realistic Depth](#122-layer-multiple-shadows-for-realistic-depth)
+    - 12.3 [Consistent Shadow Direction Across UI](#123-consistent-shadow-direction-across-ui)
+    - 12.4 [Use Neutral Colors for Shadows](#124-use-neutral-colors-for-shadows)
+    - 12.5 [Shadow Size Indicates Elevation](#125-shadow-size-indicates-elevation)
+    - 12.6 [Animate Shadows via Pseudo-Element Opacity](#126-animate-shadows-via-pseudo-element-opacity)
+    - 12.7 [Use a Consistent Spacing Scale](#127-use-a-consistent-spacing-scale)
+    - 12.8 [Use Semi-Transparent Borders](#128-use-semi-transparent-borders)
+    - 12.9 [Full Shadow Anatomy on Buttons](#129-full-shadow-anatomy-on-buttons)
+
+---
+
+## 1. Animation Principles
+
+**Impact:** CRITICAL — Disney's 12 principles adapted for web. Violations here produce the most noticeable quality issues.
+
+### 1.1 User Animations Under 300ms
+
+User-initiated animations must complete within 300ms.
+
+**Incorrect (exceeds 300ms limit):**
+
+```css
+.button { transition: transform 400ms; }
+```
+
+**Correct (within 300ms):**
+
+```css
+.button { transition: transform 200ms; }
+```
+
+### 1.2 Consistent Timing for Similar Elements
+
+Similar elements must use identical timing values.
+
+**Incorrect (inconsistent timing):**
+
+```css
+.button-primary { transition: 200ms; }
+.button-secondary { transition: 150ms; }
+```
+
+**Correct (consistent timing):**
+
+```css
+.button-primary { transition: 200ms; }
+.button-secondary { transition: 200ms; }
+```
+
+### 1.3 No Entrance Animation on Context Menus
+
+Context menus should not animate on entrance (exit only).
+
+**Incorrect (animates entrance):**
+
+```tsx
+<motion.div initial={{ opacity: 0 }} animate={{ opacity: 1 }} />
+```
+
+**Correct (exit only):**
+
+```tsx
+<motion.div exit={{ opacity: 0 }} />
+```
+
+### 1.4 Exponential Ramps for Natural Decay
+
+Use exponential ramps, not linear, for natural decay.
+
+**Incorrect (linear ramp):**
+
+```ts
+gain.gain.linearRampToValueAtTime(0, t + 0.05);
+```
+
+**Correct (exponential ramp):**
+
+```ts
+gain.gain.exponentialRampToValueAtTime(0.001, t + 0.05);
+```
+
+### 1.5 No Linear Easing for Motion
+
+Linear easing should only be used for progress indicators, not motion.
+
+**Incorrect (linear for motion):**
+
+```css
+.card { transition: transform 200ms linear; }
+```
+
+**Correct (linear for progress only):**
+
+```css
+.progress-bar { transition: width 100ms linear; }
+```
+
+### 1.6 Active State Scale Transform
+
+Interactive elements must have active/pressed state with scale transform.
+
+**Incorrect (no active state):**
+
+```css
+.button:hover { background: var(--gray-3); }
+/* Missing :active state */
+```
+
+**Correct (active state present):**
+
+```css
+.button:active { transform: scale(0.98); }
+```
+
+### 1.7 Subtle Squash and Stretch
+
+Squash/stretch deformation must be subtle (0.95-1.05 range).
+
+**Incorrect (excessive deformation):**
+
+```tsx
+<motion.div whileTap={{ scale: 0.8 }} />
+```
+
+**Correct (subtle deformation):**
+
+```tsx
+<motion.div whileTap={{ scale: 0.98 }} />
+```
+
+### 1.8 Springs for Overshoot and Settle
+
+Use springs (not easing) when overshoot-and-settle is needed.
+
+**Incorrect (easing for bounce):**
+
+```tsx
+<motion.div transition={{ duration: 0.3, ease: "easeOut" }} />
+```
+
+**Correct (spring physics):**
+
+```tsx
+<motion.div transition={{ type: "spring", stiffness: 500, damping: 30 }} />
+```
+
+### 1.9 Stagger Under 50ms Per Item
+
+Stagger delays must not exceed 50ms per item.
+
+**Incorrect (excessive stagger):**
+
+```tsx
+transition={{ staggerChildren: 0.15 }}
+```
+
+**Correct (reasonable stagger):**
+
+```tsx
+transition={{ staggerChildren: 0.03 }}
+```
+
+### 1.10 Single Focal Point
+
+Only one element should animate prominently at a time.
+
+**Incorrect (competing animations):**
+
+```tsx
+<motion.div animate={{ scale: 1.1 }} />
+<motion.div animate={{ scale: 1.1 }} />
+```
+
+### 1.11 Dim Background for Focus
+
+Modal/dialog backgrounds should dim to direct focus.
+
+**Incorrect (transparent overlay):**
+
+```css
+.overlay { background: transparent; }
+```
+
+**Correct (dimmed overlay):**
+
+```css
+.overlay { background: var(--black-a6); }
+```
+
+### 1.12 Z-Index Layering for Animated Elements
+
+Animated elements must respect z-index layering.
+
+**Incorrect (no z-index):**
+
+```css
+.tooltip { /* No z-index, may render behind other elements */ }
+```
+
+**Correct (explicit z-index):**
+
+```css
+.tooltip { z-index: 50; }
+```
+
+---
+
+## 2. Timing Functions
+
+**Impact:** HIGH — Choosing the right timing function based on whether motion is user-driven, system-driven, or high-frequency.
+
+**Decision framework:** Is this motion reacting to the user, or is the system speaking?
+
+| Motion Type | Best Choice | Why |
+|-------------|-------------|-----|
+| User-driven (drag, flick, gesture) | Spring | Survives interruption, preserves velocity |
+| System-driven (state change, feedback) | Easing | Clear start/end, predictable timing |
+| Time representation (progress, loading) | Linear | 1:1 relationship between time and progress |
+| High-frequency (typing, fast toggles) | None | Animation adds noise, feels slower |
+
+### 2.1 Springs for Gesture-Driven Motion
+
+Gesture-driven motion (drag, flick, swipe) must use springs.
+
+**Incorrect (easing for drag):**
+
+```tsx
+<motion.div
+  drag="x"
+  transition={{ duration: 0.3, ease: "easeOut" }}
+/>
+```
+
+**Correct (spring for drag):**
+
+```tsx
+<motion.div
+  drag="x"
+  transition={{ type: "spring", stiffness: 500, damping: 30 }}
+/>
+```
+
+### 2.2 Springs for Interruptible Motion
+
+Motion that can be interrupted must use springs.
+
+**Incorrect (easing for interruptible):**
+
+```tsx
+<motion.div
+  animate={{ x: isOpen ? 200 : 0 }}
+  transition={{ duration: 0.3 }}
+/>
+```
+
+**Correct (spring for interruptible):**
+
+```tsx
+<motion.div
+  animate={{ x: isOpen ? 200 : 0 }}
+  transition={{ type: "spring", stiffness: 400, damping: 25 }}
+/>
+```
+
+### 2.3 Springs Preserve Input Velocity
+
+When velocity matters, use springs to preserve input energy.
+
+**Incorrect (velocity ignored):**
+
+```tsx
+onDragEnd={(e, info) => {
+  animate(target, { x: 0 }, { duration: 0.3 });
+}}
+```
+
+**Correct (velocity preserved):**
+
+```tsx
+onDragEnd={(e, info) => {
+  animate(target, { x: 0 }, {
+    type: "spring",
+    velocity: info.velocity.x,
+  });
+}}
+```
+
+### 2.4 Balanced Spring Parameters
+
+Spring parameters must be balanced; avoid excessive oscillation.
+
+**Incorrect (too bouncy):**
+
+```tsx
+transition={{
+  type: "spring",
+  stiffness: 1000,
+  damping: 5,
+}}
+```
+
+**Correct (balanced):**
+
+```tsx
+transition={{
+  type: "spring",
+  stiffness: 500,
+  damping: 30,
+}}
+```
+
+### 2.5 Easing for System State Changes
+
+System-initiated state changes should use easing curves.
+
+**Incorrect (spring for announcement):**
+
+```tsx
+<motion.div
+  animate={{ y: 0 }}
+  transition={{ type: "spring" }}
+/>
+```
+
+**Correct (easing for announcement):**
+
+```tsx
+<motion.div
+  animate={{ y: 0 }}
+  transition={{ duration: 0.2, ease: "easeOut" }}
+/>
+```
+
+### 2.6 Ease-Out for Entrances
+
+Entrances must use ease-out (arrive fast, settle gently).
+
+**Incorrect (ease-in for entrance):**
+
+```css
+.modal-enter { animation-timing-function: ease-in; }
+```
+
+**Correct (ease-out for entrance):**
+
+```css
+.modal-enter { animation-timing-function: ease-out; }
+```
+
+### 2.7 Ease-In for Exits
+
+Exits must use ease-in (build momentum before departure).
+
+**Incorrect (ease-out for exit):**
+
+```css
+.modal-exit { animation-timing-function: ease-out; }
+```
+
+**Correct (ease-in for exit):**
+
+```css
+.modal-exit { animation-timing-function: ease-in; }
+```
+
+### 2.8 Ease-In-Out for View Transitions
+
+View/mode transitions use ease-in-out for neutral attention.
+
+**Correct:**
+
+```css
+.page-transition { animation-timing-function: ease-in-out; }
+```
+
+### 2.9 Linear Easing Only for Progress
+
+Linear easing only for progress bars and time representation.
+
+**Incorrect (linear for motion):**
+
+```css
+.card-slide { transition: transform 200ms linear; }
+```
+
+**Correct (linear for progress):**
+
+```css
+.progress-bar { transition: width 100ms linear; }
+```
+
+### 2.10 Press and Hover 120-180ms
+
+Press and hover interactions should use 120-180ms duration.
+
+**Incorrect (too slow):**
+
+```css
+.button:hover { transition: background-color 400ms; }
+```
+
+**Correct (appropriate duration):**
+
+```css
+.button:hover { transition: background-color 150ms; }
+```
+
+### 2.11 Small State Changes 180-260ms
+
+Small state changes should use 180-260ms duration.
+
+**Correct:**
+
+```css
+.toggle { transition: transform 200ms ease; }
+```
+
+### 2.12 Max 300ms for User Actions
+
+User-initiated animations must not exceed 300ms.
+
+**Incorrect (exceeds limit):**
+
+```tsx
+<motion.div transition={{ duration: 0.5 }} />
+```
+
+**Correct (within limit):**
+
+```tsx
+<motion.div transition={{ duration: 0.25 }} />
+```
+
+### 2.13 Shorten Duration Before Adjusting Curve
+
+If animation feels slow, shorten duration before adjusting curve.
+
+**Incorrect (adjusting curve instead):**
+
+```css
+.element { transition: 400ms cubic-bezier(0, 0.9, 0.1, 1); }
+```
+
+**Correct (shorter duration):**
+
+```css
+.element { transition: 200ms ease-out; }
+```
+
+### 2.14 No Animation for High-Frequency Interactions
+
+High-frequency interactions should have no animation.
+
+**Incorrect (animated on every keystroke):**
+
+```tsx
+function SearchInput() {
+  return (
+    <motion.div animate={{ scale: [1, 1.02, 1] }}>
+      <input onChange={handleSearch} />
+    </motion.div>
+  );
+}
+```
+
+**Correct (no animation):**
+
+```tsx
+function SearchInput() {
+  return <input onChange={handleSearch} />;
+}
+```
+
+### 2.15 No Animation for Keyboard Navigation
+
+Keyboard navigation should be instant, no animation.
+
+**Incorrect (animated focus):**
+
+```tsx
+function Menu() {
+  return items.map(item => (
+    <motion.li
+      whileFocus={{ scale: 1.05 }}
+      transition={{ duration: 0.2 }}
+    />
+  ));
+}
+```
+
+**Correct (CSS focus-visible only):**
+
+```tsx
+function Menu() {
+  return items.map(item => (
+    <li className={styles.menuItem} />
+  ));
+}
+```
+
+### 2.16 No Entrance Animation for Context Menus
+
+Context menus should not animate on entrance (exit only).
+
+**Incorrect (entrance animation):**
+
+```tsx
+<motion.div
+  initial={{ opacity: 0, scale: 0.95 }}
+  animate={{ opacity: 1, scale: 1 }}
+  exit={{ opacity: 0 }}
+/>
+```
+
+**Correct (exit only):**
+
+```tsx
+<motion.div exit={{ opacity: 0, scale: 0.95 }} />
+```
+
+**Quick reference:**
+
+| Interaction | Timing | Type |
+|-------------|--------|------|
+| Drag release | Spring | `stiffness: 500, damping: 30` |
+| Button press | 150ms | `ease` |
+| Modal enter | 200ms | `ease-out` |
+| Modal exit | 150ms | `ease-in` |
+| Page transition | 250ms | `ease-in-out` |
+| Progress bar | varies | `linear` |
+| Typing feedback | 0ms | none |
+
+---
+
+## 3. Exit Animations
+
+**Impact:** HIGH — Correct AnimatePresence usage prevents layout shifts, stale interactions, and orphaned elements.
+
+### 3.1 AnimatePresence Wrapper Required
+
+Conditional motion elements must be wrapped in AnimatePresence.
+
+**Incorrect (no wrapper):**
+
+```tsx
+{isVisible && (
+  <motion.div exit={{ opacity: 0 }} />
+)}
+```
+
+**Correct (wrapped):**
+
+```tsx
+<AnimatePresence>
+  {isVisible && (
+    <motion.div exit={{ opacity: 0 }} />
+  )}
+</AnimatePresence>
+```
+
+### 3.2 Exit Prop Required Inside AnimatePresence
+
+Elements inside AnimatePresence should have exit prop defined.
+
+**Incorrect (missing exit):**
+
+```tsx
+<AnimatePresence>
+  {isOpen && (
+    <motion.div initial={{ opacity: 0 }} animate={{ opacity: 1 }} />
+  )}
+</AnimatePresence>
+```
+
+**Correct (exit defined):**
+
+```tsx
+<AnimatePresence>
+  {isOpen && (
+    <motion.div
+      initial={{ opacity: 0 }}
+      animate={{ opacity: 1 }}
+      exit={{ opacity: 0 }}
+    />
+  )}
+</AnimatePresence>
+```
+
+### 3.3 Unique Keys in AnimatePresence Lists
+
+Dynamic lists inside AnimatePresence must have unique keys.
+
+**Incorrect (index as key):**
+
+```tsx
+<AnimatePresence>
+  {items.map((item, index) => (
+    <motion.div key={index} exit={{ opacity: 0 }} />
+  ))}
+</AnimatePresence>
+```
+
+**Correct (stable unique key):**
+
+```tsx
+<AnimatePresence>
+  {items.map((item) => (
+    <motion.div key={item.id} exit={{ opacity: 0 }} />
+  ))}
+</AnimatePresence>
+```
+
+### 3.4 Exit Mirrors Initial for Symmetry
+
+Exit animation should mirror initial for symmetry.
+
+**Incorrect (asymmetric exit):**
+
+```tsx
+<motion.div
+  initial={{ opacity: 0, y: 20 }}
+  animate={{ opacity: 1, y: 0 }}
+  exit={{ scale: 0 }}
+/>
+```
+
+**Correct (symmetric exit):**
+
+```tsx
+<motion.div
+  initial={{ opacity: 0, y: 20 }}
+  animate={{ opacity: 1, y: 0 }}
+  exit={{ opacity: 0, y: 20 }}
+/>
+```
+
+### 3.5 useIsPresent in Child Component
+
+useIsPresent must be called from child of AnimatePresence, not parent.
+
+**Incorrect (hook in parent):**
+
+```tsx
+function Parent() {
+  const isPresent = useIsPresent();
+  return (
+    <AnimatePresence>
+      {show && <Child />}
+    </AnimatePresence>
+  );
+}
+```
+
+**Correct (hook in child):**
+
+```tsx
+function Child() {
+  const isPresent = useIsPresent();
+  return <motion.div data-exiting={!isPresent} />;
+}
+```
+
+### 3.6 Call safeToRemove After Async Work
+
+When using usePresence, always call safeToRemove after async work.
+
+**Incorrect (missing safeToRemove):**
+
+```tsx
+function AsyncComponent() {
+  const [isPresent, safeToRemove] = usePresence();
+
+  useEffect(() => {
+    if (!isPresent) {
+      cleanup();
+    }
+  }, [isPresent]);
+}
+```
+
+**Correct (safeToRemove called):**
+
+```tsx
+function AsyncComponent() {
+  const [isPresent, safeToRemove] = usePresence();
+
+  useEffect(() => {
+    if (!isPresent) {
+      cleanup().then(safeToRemove);
+    }
+  }, [isPresent, safeToRemove]);
+}
+```
+
+### 3.7 Disable Interactions on Exiting Elements
+
+Disable interactions on exiting elements using isPresent.
+
+**Incorrect (clickable during exit):**
+
+```tsx
+function Card() {
+  const isPresent = useIsPresent();
+  return <button onClick={handleClick}>Click</button>;
+}
+```
+
+**Correct (disabled during exit):**
+
+```tsx
+function Card() {
+  const isPresent = useIsPresent();
+  return (
+    <button onClick={handleClick} disabled={!isPresent}>
+      Click
+    </button>
+  );
+}
+```
+
+### 3.8 Mode "wait" Doubles Duration
+
+Mode "wait" nearly doubles animation duration; adjust timing accordingly.
+
+**Incorrect (too slow with wait):**
+
+```tsx
+<AnimatePresence mode="wait">
+  <motion.div transition={{ duration: 0.3 }} />
+</AnimatePresence>
+```
+
+**Correct (halved timing):**
+
+```tsx
+<AnimatePresence mode="wait">
+  <motion.div transition={{ duration: 0.15 }} />
+</AnimatePresence>
+```
+
+### 3.9 Mode "sync" Causes Layout Conflicts
+
+Mode "sync" causes layout conflicts; position exiting elements absolutely.
+
+**Incorrect (sync with layout competition):**
+
+```tsx
+<AnimatePresence mode="sync">
+  {items.map(item => (
+    <motion.div exit={{ opacity: 0 }}>{item}</motion.div>
+  ))}
+</AnimatePresence>
+```
+
+**Correct (popLayout instead):**
+
+```tsx
+<AnimatePresence mode="popLayout">
+  {items.map(item => (
+    <motion.div exit={{ opacity: 0 }}>{item}</motion.div>
+  ))}
+</AnimatePresence>
+```
+
+### 3.10 popLayout for List Reordering
+
+Use popLayout mode for list reordering animations.
+
+**Incorrect (default mode causes shifts):**
+
+```tsx
+<AnimatePresence>
+  {items.map(item => <ListItem key={item.id} />)}
+</AnimatePresence>
+```
+
+**Correct (popLayout prevents shifts):**
+
+```tsx
+<AnimatePresence mode="popLayout">
+  {items.map(item => <ListItem key={item.id} />)}
+</AnimatePresence>
+```
+
+### 3.11 Propagate Prop for Nested AnimatePresence
+
+Nested AnimatePresence must use propagate prop for coordinated exits.
+
+**Incorrect (children vanish instantly):**
+
+```tsx
+<AnimatePresence>
+  {isOpen && (
+    <motion.div exit={{ opacity: 0 }}>
+      <AnimatePresence>
+        {items.map(item => (
+          <motion.div key={item.id} exit={{ scale: 0 }} />
+        ))}
+      </AnimatePresence>
+    </motion.div>
+  )}
+</AnimatePresence>
+```
+
+**Correct (propagate on both):**
+
+```tsx
+<AnimatePresence propagate>
+  {isOpen && (
+    <motion.div exit={{ opacity: 0 }}>
+      <AnimatePresence propagate>
+        {items.map(item => (
+          <motion.div key={item.id} exit={{ scale: 0 }} />
+        ))}
+      </AnimatePresence>
+    </motion.div>
+  )}
+</AnimatePresence>
+```
+
+### 3.12 Coordinated Parent-Child Exit Timing
+
+Parent and child exit durations should be coordinated.
+
+**Incorrect (parent too fast):**
+
+```tsx
+<motion.div exit={{ opacity: 0 }} transition={{ duration: 0.1 }}>
+  <motion.div exit={{ scale: 0 }} transition={{ duration: 0.5 }} />
+</motion.div>
+```
+
+**Correct (coordinated timing):**
+
+```tsx
+<motion.div exit={{ opacity: 0 }} transition={{ duration: 0.2 }}>
+  <motion.div exit={{ scale: 0 }} transition={{ duration: 0.15 }} />
+</motion.div>
+```
+
+Reference: [Motion AnimatePresence Documentation](https://motion.dev/docs/react-animate-presence)
+
+---
+
+## 4. CSS Pseudo Elements
+
+**Impact:** MEDIUM — Leveraging pseudo-elements and View Transitions to reduce DOM nodes and improve transitions.
+
+### 4.1 Content Property Required for Pseudo-Elements
+
+::before and ::after require content property to render.
+
+**Incorrect (missing content):**
+
+```css
+.button::before {
+  position: absolute;
+  background: var(--gray-3);
+}
+```
+
+**Correct (content set):**
+
+```css
+.button::before {
+  content: "";
+  position: absolute;
+  background: var(--gray-3);
+}
+```
+
+### 4.2 Pseudo-Elements Over DOM Nodes
+
+Use pseudo-elements for decorative content instead of extra DOM nodes.
+
+**Incorrect (extra DOM node):**
+
+```tsx
+<button className={styles.button}>
+  <span className={styles.background} />
+  Click me
+</button>
+```
+
+**Correct (pseudo-element):**
+
+```tsx
+<button className={styles.button}>
+  Click me
+</button>
+```
+
+```css
+.button::before {
+  content: "";
+  /* decorative background */
+}
+```
+
+### 4.3 Position Relative Parent for Pseudo-Elements
+
+Parent must have position: relative for absolute pseudo-elements.
+
+**Incorrect (no position on parent):**
+
+```css
+.button::before {
+  content: "";
+  position: absolute;
+  inset: 0;
+}
+/* .button has no position */
+```
+
+**Correct (parent positioned):**
+
+```css
+.button {
+  position: relative;
+}
+
+.button::before {
+  content: "";
+  position: absolute;
+  inset: 0;
+}
+```
+
+### 4.4 Z-Index Layering for Pseudo-Elements
+
+Pseudo-elements need z-index to layer correctly with content.
+
+**Incorrect (covers button text):**
+
+```css
+.button::before {
+  content: "";
+  position: absolute;
+  inset: 0;
+  background: var(--gray-3);
+}
+```
+
+**Correct (layered behind):**
+
+```css
+.button {
+  position: relative;
+  z-index: 1;
+}
+
+.button::before {
+  content: "";
+  position: absolute;
+  inset: 0;
+  background: var(--gray-3);
+  z-index: -1;
+}
+```
+
+### 4.5 Hit Target Expansion with Pseudo-Elements
+
+Use negative inset values to expand hit targets without extra markup.
+
+**Incorrect (wrapper for hit target):**
+
+```tsx
+<div className={styles.wrapper}>
+  <a className={styles.link}>Link</a>
+</div>
+```
+
+**Correct (pseudo-element expansion):**
+
+```css
+.link {
+  position: relative;
+}
+
+.link::before {
+  content: "";
+  position: absolute;
+  inset: -8px -12px;
+}
+```
+
+### 4.6 View Transition Name Required
+
+Elements participating in view transitions need view-transition-name.
+
+**Incorrect (no transition name):**
+
+```ts
+document.startViewTransition(() => {
+  targetImg.src = newSrc;
+});
+```
+
+**Correct (transition name assigned):**
+
+```ts
+sourceImg.style.viewTransitionName = "card";
+document.startViewTransition(() => {
+  sourceImg.style.viewTransitionName = "";
+  targetImg.style.viewTransitionName = "card";
+});
+```
+
+### 4.7 Unique View Transition Names
+
+Each view-transition-name must be unique on the page during transition.
+
+**Incorrect (duplicate names):**
+
+```css
+.card {
+  view-transition-name: card;
+}
+/* Multiple cards with same name */
+```
+
+**Correct (unique per element):**
+
+```ts
+element.style.viewTransitionName = `card-${id}`;
+```
+
+### 4.8 Clean Up View Transition Names
+
+Remove view-transition-name after transition completes.
+
+**Incorrect (stale name):**
+
+```ts
+sourceImg.style.viewTransitionName = "card";
+document.startViewTransition(() => {
+  targetImg.style.viewTransitionName = "card";
+});
+```
+
+**Correct (name cleaned up):**
+
+```ts
+sourceImg.style.viewTransitionName = "card";
+document.startViewTransition(() => {
+  sourceImg.style.viewTransitionName = "";
+  targetImg.style.viewTransitionName = "card";
+});
+```
+
+### 4.9 View Transitions Over JS Libraries
+
+Prefer View Transitions API over JavaScript animation libraries for page transitions.
+
+**Incorrect (JS-based transition):**
+
+```tsx
+import { motion } from "motion/react";
+
+function ImageLightbox() {
+  return (
+    <motion.img layoutId="hero" />
+  );
+}
+```
+
+**Correct (native View Transition):**
+
+```ts
+function openLightbox(img: HTMLImageElement) {
+  img.style.viewTransitionName = "hero";
+  document.startViewTransition(() => {
+    // Native browser transition
+  });
+}
+```
+
+### 4.10 Style View Transition Pseudo-Elements
+
+Style view transition pseudo-elements for custom animations.
+
+**Incorrect (default crossfade only):**
+
+```ts
+document.startViewTransition(() => { /* ... */ });
+```
+
+**Correct (custom animation):**
+
+```css
+::view-transition-group(card) {
+  animation-duration: 300ms;
+  animation-timing-function: cubic-bezier(0.215, 0.61, 0.355, 1);
+}
+```
+
+### 4.11 Use ::backdrop for Dialog Backgrounds
+
+Use ::backdrop pseudo-element for dialog/popover backgrounds.
+
+**Incorrect (extra overlay node):**
+
+```tsx
+<>
+  <div className={styles.overlay} onClick={close} />
+  <dialog className={styles.dialog}>{children}</dialog>
+</>
+```
+
+**Correct (native ::backdrop):**
+
+```css
+dialog::backdrop {
+  background: var(--black-a6);
+  backdrop-filter: blur(4px);
+}
+```
+
+### 4.12 Use ::placeholder for Input Styling
+
+Use ::placeholder for input placeholder styling, not wrapper elements.
+
+**Incorrect (custom placeholder node):**
+
+```tsx
+<div className={styles.inputWrapper}>
+  {!value && <span className={styles.placeholder}>Enter text...</span>}
+  <input value={value} />
+</div>
+```
+
+**Correct (native ::placeholder):**
+
+```css
+input::placeholder {
+  color: var(--gray-9);
+  opacity: 1;
+}
+```
+
+### 4.13 Use ::selection for Text Styling
+
+Use ::selection for text selection styling.
+
+**Correct:**
+
+```css
+::selection {
+  background: var(--blue-a5);
+  color: var(--gray-12);
+}
+```
+
+### 4.14 Use ::marker for Custom List Bullets
+
+Use ::marker to style list bullets without extra elements or background-image hacks.
+
+**Incorrect (background image hack):**
+
+```css
+li {
+  list-style: none;
+  background: url("bullet.svg") no-repeat 0 4px;
+  padding-left: 20px;
+}
+```
+
+**Correct (native ::marker):**
+
+```css
+li::marker {
+  color: var(--gray-8);
+  font-size: 0.8em;
+}
+```
+
+### 4.15 Use ::first-line for Typographic Treatments
+
+Use ::first-line for drop-cap-adjacent styling without JavaScript or hardcoded spans.
+
+**Incorrect (manual span):**
+
+```tsx
+<p>
+  <span className={styles["first-line"]}>The opening line</span>
+  is styled differently from the rest.
+</p>
+```
+
+**Correct (native ::first-line):**
+
+```css
+.article p:first-of-type::first-line {
+  font-variant-caps: small-caps;
+  font-weight: var(--font-weight-medium);
+}
+```
+
+Reference: [MDN Pseudo-elements Reference](https://developer.mozilla.org/en-US/docs/Web/CSS/Reference/Selectors/Pseudo-elements), [View Transitions API](https://developer.mozilla.org/en-US/docs/Web/API/View_Transitions_API)
+
+---
+
+## 5. Audio Feedback
+
+**Impact:** MEDIUM — When and how to use sound in UI, covering accessibility, appropriateness, and implementation.
+
+### 5.1 Visual Equivalent for Every Sound
+
+Every audio cue must have a visual equivalent; sound never replaces visual feedback.
+
+**Incorrect (sound without visual):**
+
+```tsx
+function SubmitButton({ onClick }) {
+  const handleClick = () => {
+    playSound("success");
+    onClick();
+  };
+}
+```
+
+**Correct (sound with visual):**
+
+```tsx
+function SubmitButton({ onClick }) {
+  const [status, setStatus] = useState("idle");
+
+  const handleClick = () => {
+    playSound("success");
+    setStatus("success");
+    onClick();
+  };
+
+  return <button data-status={status}>Submit</button>;
+}
+```
+
+### 5.2 Toggle Setting to Disable Sounds
+
+Provide explicit toggle to disable sounds in settings.
+
+**Incorrect (no way to disable):**
+
+```tsx
+function App() {
+  return <SoundProvider>{children}</SoundProvider>;
+}
+```
+
+**Correct (toggle available):**
+
+```tsx
+function App() {
+  const { soundEnabled } = usePreferences();
+  return (
+    <SoundProvider enabled={soundEnabled}>
+      {children}
+    </SoundProvider>
+  );
+}
+```
+
+### 5.3 Respect prefers-reduced-motion for Sound
+
+Respect prefers-reduced-motion as proxy for sound sensitivity.
+
+**Incorrect (ignores preference):**
+
+```tsx
+function playSound(name: string) {
+  audio.play();
+}
+```
+
+**Correct (checks preference):**
+
+```tsx
+function playSound(name: string) {
+  const prefersReducedMotion = window.matchMedia(
+    "(prefers-reduced-motion: reduce)"
+  ).matches;
+
+  if (prefersReducedMotion) return;
+  audio.play();
+}
+```
+
+### 5.4 Independent Volume Control
+
+Allow volume adjustment independent of system volume.
+
+**Incorrect (always full volume):**
+
+```tsx
+function playSound() {
+  audio.volume = 1;
+  audio.play();
+}
+```
+
+**Correct (user-controlled volume):**
+
+```tsx
+function playSound() {
+  const { volume } = usePreferences();
+  audio.volume = volume;
+  audio.play();
+}
+```
+
+### 5.5 No Sound on High-Frequency Interactions
+
+Do not add sound to high-frequency interactions (typing, keyboard navigation).
+
+**Incorrect (sound on every keystroke):**
+
+```tsx
+function Input({ onChange }) {
+  const handleChange = (e) => {
+    playSound("keystroke");
+    onChange(e);
+  };
+}
+```
+
+**Correct (no sound on typing):**
+
+```tsx
+function Input({ onChange }) {
+  return <input onChange={onChange} />;
+}
+```
+
+### 5.6 Sound for Confirmations
+
+Sound is appropriate for confirmations: payments, uploads, form submissions.
+
+**Correct:**
+
+```tsx
+async function handlePayment() {
+  await processPayment();
+  playSound("success");
+  showConfirmation();
+}
+```
+
+### 5.7 Sound for Errors and Warnings
+
+Sound is appropriate for errors and warnings that can't be overlooked.
+
+**Correct:**
+
+```tsx
+function handleError(error: Error) {
+  playSound("error");
+  showErrorToast(error.message);
+}
+```
+
+### 5.8 No Decorative Sound
+
+Do not add sound to decorative moments with no informational value.
+
+**Incorrect (hover sound):**
+
+```tsx
+function Card({ onHover }) {
+  return (
+    <div onMouseEnter={() => playSound("hover")}>
+      {children}
+    </div>
+  );
+}
+```
+
+### 5.9 Informative Not Punishing Sound
+
+Sound should inform, not punish; avoid harsh sounds for user mistakes.
+
+**Incorrect (harsh buzzer):**
+
+```tsx
+function ValidationError() {
+  playSound("loud-buzzer");
+  return <span>Invalid input</span>;
+}
+```
+
+**Correct (gentle alert):**
+
+```tsx
+function ValidationError() {
+  playSound("gentle-alert");
+  return <span>Invalid input</span>;
+}
+```
+
+### 5.10 Preload Audio Files
+
+Preload audio files to avoid playback delay.
+
+**Incorrect (loads on demand):**
+
+```tsx
+function playSound(name: string) {
+  const audio = new Audio(`/sounds/${name}.mp3`);
+  audio.play();
+}
+```
+
+**Correct (preloaded):**
+
+```tsx
+const sounds = {
+  success: new Audio("/sounds/success.mp3"),
+  error: new Audio("/sounds/error.mp3"),
+};
+
+Object.values(sounds).forEach(audio => audio.load());
+
+function playSound(name: keyof typeof sounds) {
+  sounds[name].currentTime = 0;
+  sounds[name].play();
+}
+```
+
+### 5.11 Subtle Default Volume
+
+Default volume should be subtle, not loud.
+
+**Incorrect (too loud):**
+
+```tsx
+const DEFAULT_VOLUME = 1.0;
+```
+
+**Correct (subtle):**
+
+```tsx
+const DEFAULT_VOLUME = 0.3;
+```
+
+### 5.12 Reset currentTime Before Replay
+
+Reset audio currentTime before replay to allow rapid triggering.
+
+**Incorrect (won't replay if playing):**
+
+```tsx
+function playSound() {
+  audio.play();
+}
+```
+
+**Correct (reset before play):**
+
+```tsx
+function playSound() {
+  audio.currentTime = 0;
+  audio.play();
+}
+```
+
+### 5.13 Match Sound Weight to Action
+
+Sound weight should match action importance.
+
+**Incorrect (fanfare for toggle):**
+
+```tsx
+function handleToggle() {
+  playSound("triumphant-fanfare");
+  setEnabled(!enabled);
+}
+```
+
+**Correct (weight matches action):**
+
+```tsx
+function handleToggle() {
+  playSound("soft-click");
+  setEnabled(!enabled);
+}
+
+function handlePurchase() {
+  playSound("success-chime");
+  completePurchase();
+}
+```
+
+### 5.14 Sound Duration Matches Action Duration
+
+Sound duration should match action duration.
+
+**Incorrect (long sound for instant action):**
+
+```tsx
+function handleClick() {
+  playSound("long-whoosh"); // 2000ms
+}
+```
+
+**Correct (matched duration):**
+
+```tsx
+function handleClick() {
+  playSound("click"); // 50ms
+}
+
+function handleUpload() {
+  playSound("upload-progress"); // Matches upload duration
+}
+```
+
+**Sound appropriateness matrix:**
+
+| Interaction | Sound? | Reason |
+|-------------|--------|--------|
+| Payment success | Yes | Significant confirmation |
+| Form submission | Yes | User needs assurance |
+| Error state | Yes | Can't be overlooked |
+| Notification | Yes | May not be looking at screen |
+| Button click | Maybe | Only for significant buttons |
+| Typing | No | Too frequent |
+| Hover | No | Decorative only |
+| Scroll | No | Too frequent |
+| Navigation | No | Keyboard nav would be noisy |
+
+Reference: [Web Audio API Documentation](https://developer.mozilla.org/en-US/docs/Web/API/Web_Audio_API), [prefers-reduced-motion](https://developer.mozilla.org/en-US/docs/Web/CSS/@media/prefers-reduced-motion)
+
+---
+
+## 6. Sound Synthesis
+
+**Impact:** MEDIUM — Web Audio API best practices for procedural sound generation.
+
+### 6.1 Reuse Single AudioContext
+
+Reuse a single AudioContext instance; do not create new ones per sound.
+
+**Incorrect (new context per call):**
+
+```ts
+function playSound() {
+  const ctx = new AudioContext();
+}
+```
+
+**Correct (singleton):**
+
+```ts
+let audioContext: AudioContext | null = null;
+
+function getAudioContext(): AudioContext {
+  if (!audioContext) {
+    audioContext = new AudioContext();
+  }
+  return audioContext;
+}
+```
+
+### 6.2 Resume Suspended AudioContext
+
+Check and resume suspended AudioContext before playing.
+
+**Incorrect (plays without checking):**
+
+```ts
+function playSound() {
+  const ctx = getAudioContext();
+}
+```
+
+**Correct (resumes if suspended):**
+
+```ts
+function playSound() {
+  const ctx = getAudioContext();
+  if (ctx.state === "suspended") {
+    ctx.resume();
+  }
+}
+```
+
+### 6.3 Clean Up Audio Nodes After Playback
+
+Disconnect and clean up audio nodes after playback.
+
+**Incorrect (nodes remain connected):**
+
+```ts
+source.start();
+```
+
+**Correct (cleaned up on end):**
+
+```ts
+source.start();
+source.onended = () => {
+  source.disconnect();
+  gain.disconnect();
+};
+```
+
+### 6.4 Exponential Decay for Natural Sound
+
+Use exponential ramps for natural decay, not linear.
+
+**Incorrect (linear ramp):**
+
+```ts
+gain.gain.linearRampToValueAtTime(0, t + 0.05);
+```
+
+**Correct (exponential ramp):**
+
+```ts
+gain.gain.exponentialRampToValueAtTime(0.001, t + 0.05);
+```
+
+### 6.5 No Zero Target for Exponential Ramps
+
+Exponential ramps cannot target 0; use 0.001 or similar small value.
+
+**Incorrect (targets zero):**
+
+```ts
+gain.gain.exponentialRampToValueAtTime(0, t + 0.05);
+```
+
+**Correct (targets near-zero):**
+
+```ts
+gain.gain.exponentialRampToValueAtTime(0.001, t + 0.05);
+```
+
+### 6.6 Set Initial Value Before Ramp
+
+Set initial value before ramping to avoid glitches.
+
+**Incorrect (no initial value):**
+
+```ts
+gain.gain.exponentialRampToValueAtTime(0.001, t + 0.05);
+```
+
+**Correct (initial value set):**
+
+```ts
+gain.gain.setValueAtTime(0.3, t);
+gain.gain.exponentialRampToValueAtTime(0.001, t + 0.05);
+```
+
+### 6.7 Noise for Percussive Sounds
+
+Use filtered noise for clicks/taps, not oscillators.
+
+**Incorrect (oscillator for click):**
+
+```ts
+const osc = ctx.createOscillator();
+osc.type = "sine";
+```
+
+**Correct (noise burst for click):**
+
+```ts
+const buffer = ctx.createBuffer(1, ctx.sampleRate * 0.008, ctx.sampleRate);
+const data = buffer.getChannelData(0);
+for (let i = 0; i < data.length; i++) {
+  data[i] = (Math.random() * 2 - 1) * Math.exp(-i / 50);
+}
+```
+
+### 6.8 Oscillators for Tonal Sounds
+
+Use oscillators with pitch movement for tonal sounds (pops, confirmations).
+
+**Incorrect (static frequency):**
+
+```ts
+osc.frequency.value = 400;
+```
+
+**Correct (pitch sweep):**
+
+```ts
+osc.frequency.setValueAtTime(400, t);
+osc.frequency.exponentialRampToValueAtTime(600, t + 0.04);
+```
+
+### 6.9 Bandpass Filter for Sound Character
+
+Apply bandpass filter to shape percussive sounds.
+
+**Incorrect (raw noise):**
+
+```ts
+source.connect(gain).connect(ctx.destination);
+```
+
+**Correct (filtered noise):**
+
+```ts
+const filter = ctx.createBiquadFilter();
+filter.type = "bandpass";
+filter.frequency.value = 4000;
+filter.Q.value = 3;
+source.connect(filter).connect(gain).connect(ctx.destination);
+```
+
+### 6.10 Click Duration 5-15ms
+
+Click/tap sounds should be 5-15ms duration.
+
+**Incorrect (too long):**
+
+```ts
+const buffer = ctx.createBuffer(1, ctx.sampleRate * 0.1, ctx.sampleRate);
+```
+
+**Correct (appropriate duration):**
+
+```ts
+const buffer = ctx.createBuffer(1, ctx.sampleRate * 0.008, ctx.sampleRate);
+```
+
+### 6.11 Click Filter 3000-6000Hz
+
+Bandpass filter for clicks should be 3000-6000Hz.
+
+**Incorrect (too low):**
+
+```ts
+filter.frequency.value = 500;
+```
+
+**Correct (crisp range):**
+
+```ts
+filter.frequency.value = 4000;
+```
+
+### 6.12 Gain Under 1.0
+
+Gain values should not exceed 1.0 to prevent clipping.
+
+**Incorrect (clipping):**
+
+```ts
+gain.gain.setValueAtTime(1.5, t);
+```
+
+**Correct (safe gain):**
+
+```ts
+gain.gain.setValueAtTime(0.3, t);
+```
+
+### 6.13 Filter Q Value 2-5
+
+Filter Q for clicks should be 2-5 for focused but not harsh sound.
+
+**Incorrect (too resonant):**
+
+```ts
+filter.Q.value = 15;
+```
+
+**Correct (balanced Q):**
+
+```ts
+filter.Q.value = 3;
+```
+
+**Parameter translation table:**
+
+| User Says | Parameter Change |
+|-----------|------------------|
+| "too harsh" | Lower filter frequency, reduce Q |
+| "too muffled" | Higher filter frequency |
+| "too long" | Shorter duration, faster decay |
+| "cuts off abruptly" | Use exponential decay |
+| "more mechanical" | Higher Q, faster decay |
+| "softer" | Lower gain, triangle wave |
+
+Reference: [Web Audio API - MDN](https://developer.mozilla.org/en-US/docs/Web/API/Web_Audio_API)
+
+---
+
+## 7. Morphing Icons
+
+**Impact:** LOW — Building icon components that morph between any two icons through SVG line transformation.
+
+**Core concept:** Every icon is composed of exactly three SVG lines. Icons that need fewer lines collapse the extras to invisible center points. This constraint enables seamless morphing between any two icons.
+
+**Architecture:**
+
+```ts
+interface IconLine {
+  x1: number;
+  y1: number;
+  x2: number;
+  y2: number;
+  opacity?: number;
+}
+
+interface IconDefinition {
+  lines: [IconLine, IconLine, IconLine];
+  rotation?: number;
+  group?: string;
+}
+
+const CENTER = 7;
+const collapsed: IconLine = {
+  x1: CENTER, y1: CENTER, x2: CENTER, y2: CENTER, opacity: 0,
+};
+```
+
+### 7.1 Icons Must Use Exactly Three Lines
+
+Every icon MUST use exactly 3 lines. No more, no fewer.
+
+**Incorrect (only 2 lines):**
+
+```ts
+const checkIcon = {
+  lines: [
+    { x1: 2, y1: 7.5, x2: 5.5, y2: 11 },
+    { x1: 5.5, y1: 11, x2: 12, y2: 3 },
+  ],
+};
+```
+
+**Correct (3 lines with collapsed):**
+
+```ts
+const checkIcon = {
+  lines: [
+    { x1: 2, y1: 7.5, x2: 5.5, y2: 11 },
+    { x1: 5.5, y1: 11, x2: 12, y2: 3 },
+    collapsed,
+  ],
+};
+```
+
+### 7.2 Use Collapsed Constant for Unused Lines
+
+Unused lines must use the collapsed constant, not omission or null.
+
+**Incorrect (null for unused):**
+
+```ts
+const minusIcon = {
+  lines: [
+    { x1: 2, y1: 7, x2: 12, y2: 7 },
+    null,
+    null,
+  ],
+};
+```
+
+**Correct (collapsed constant):**
+
+```ts
+const minusIcon = {
+  lines: [
+    { x1: 2, y1: 7, x2: 12, y2: 7 },
+    collapsed,
+    collapsed,
+  ],
+};
+```
+
+### 7.3 Consistent ViewBox Size
+
+All icons must use the same viewBox (14x14 recommended).
+
+**Incorrect (mixed scales):**
+
+```ts
+const icon1 = { lines: [{ x1: 2, y1: 7, x2: 12, y2: 7 }, ...] }; // 14x14
+const icon2 = { lines: [{ x1: 4, y1: 14, x2: 24, y2: 14 }, ...] }; // 28x28
+```
+
+**Correct (consistent scale):**
+
+```ts
+const VIEWBOX_SIZE = 14;
+const CENTER = 7;
+```
+
+### 7.4 Shared Group for Rotational Variants
+
+Icons that are rotational variants MUST share the same group and base lines.
+
+**Incorrect (different line definitions):**
+
+```ts
+const arrowRight = { lines: [{ x1: 2, y1: 7, x2: 12, y2: 7 }, ...] };
+const arrowDown = { lines: [{ x1: 7, y1: 2, x2: 7, y2: 12 }, ...] };
+```
+
+**Correct (shared base lines):**
+
+```ts
+const arrowLines: [IconLine, IconLine, IconLine] = [
+  { x1: 2, y1: 7, x2: 12, y2: 7 },
+  { x1: 7.5, y1: 2.5, x2: 12, y2: 7 },
+  { x1: 7.5, y1: 11.5, x2: 12, y2: 7 },
+];
+
+const icons = {
+  "arrow-right": { lines: arrowLines, rotation: 0, group: "arrow" },
+  "arrow-down": { lines: arrowLines, rotation: 90, group: "arrow" },
+  "arrow-left": { lines: arrowLines, rotation: 180, group: "arrow" },
+  "arrow-up": { lines: arrowLines, rotation: -90, group: "arrow" },
+};
+```
+
+### 7.5 Spring Physics for Rotation
+
+Rotation between grouped icons should use spring physics for natural motion.
+
+**Incorrect (duration-based rotation):**
+
+```tsx
+<motion.g animate={{ rotate: rotation }} transition={{ duration: 0.3 }} />
+```
+
+**Correct (spring rotation):**
+
+```tsx
+const rotation = useSpring(definition.rotation ?? 0, activeTransition);
+
+<motion.g style={{ rotate: rotation, transformOrigin: "center" }} />
+```
+
+### 7.6 Reduced Motion Support for Icons
+
+Respect prefers-reduced-motion by disabling animations.
+
+**Incorrect (always animates):**
+
+```tsx
+function MorphingIcon({ icon }: Props) {
+  return <motion.line animate={...} transition={{ duration: 0.4 }} />;
+}
+```
+
+**Correct (respects preference):**
+
+```tsx
+function MorphingIcon({ icon }: Props) {
+  const reducedMotion = useReducedMotion() ?? false;
+  const activeTransition = reducedMotion ? { duration: 0 } : transition;
+
+  return <motion.line animate={...} transition={activeTransition} />;
+}
+```
+
+### 7.7 Instant Jump for Non-Grouped Icons
+
+When transitioning between icons NOT in the same group, rotation should jump instantly.
+
+**Incorrect (always animates rotation):**
+
+```tsx
+useEffect(() => {
+  rotation.set(definition.rotation ?? 0);
+}, [definition]);
+```
+
+**Correct (jumps when not grouped):**
+
+```tsx
+useEffect(() => {
+  if (shouldRotate) {
+    rotation.set(definition.rotation ?? 0);
+  } else {
+    rotation.jump(definition.rotation ?? 0);
+  }
+}, [definition, shouldRotate]);
+```
+
+### 7.8 Round Stroke Line Caps
+
+Lines should use strokeLinecap="round" for polished endpoints.
+
+**Incorrect (butt caps):**
+
+```tsx
+<motion.line strokeLinecap="butt" />
+```
+
+**Correct (round caps):**
+
+```tsx
+<motion.line strokeLinecap="round" />
+```
+
+### 7.9 Aria Hidden on Icon SVGs
+
+Icon SVGs should be aria-hidden since they're decorative.
+
+**Incorrect (no aria attribute):**
+
+```tsx
+<svg width={size} height={size}>...</svg>
+```
+
+**Correct (aria-hidden):**
+
+```tsx
+<svg width={size} height={size} aria-hidden="true">...</svg>
+```
+
+**Common icon patterns:**
+
+```ts
+// Two-line icons (check, minus, chevron) — one collapsed line
+const check = {
+  lines: [
+    { x1: 2, y1: 7.5, x2: 5.5, y2: 11 },
+    { x1: 5.5, y1: 11, x2: 12, y2: 3 },
+    collapsed,
+  ],
+};
+
+// Three-line icons (menu, asterisk) — all lines used
+const menu = {
+  lines: [
+    { x1: 2, y1: 3.5, x2: 12, y2: 3.5 },
+    { x1: 2, y1: 7, x2: 12, y2: 7 },
+    { x1: 2, y1: 10.5, x2: 12, y2: 10.5 },
+  ],
+};
+
+// Point icons (more, grip) — zero-length lines as dots
+const more = {
+  lines: [
+    { x1: 3, y1: 7, x2: 3, y2: 7 },
+    { x1: 7, y1: 7, x2: 7, y2: 7 },
+    { x1: 11, y1: 7, x2: 11, y2: 7 },
+  ],
+};
+```
+
+**Recommended transition:**
+
+```ts
+const defaultTransition: Transition = {
+  ease: [0.19, 1, 0.22, 1],
+  duration: 0.4,
+};
+```
+
+Reference: [Motion useSpring](https://motion.dev/docs/react-use-spring), [SVG Line Element](https://developer.mozilla.org/en-US/docs/Web/SVG/Element/line)
+
+---
+
+## 8. Container Animation
+
+**Impact:** MEDIUM — Animating container width and height using a measure-and-animate pattern with ResizeObserver and Motion.
+
+### 8.1 Two-Div Pattern for Animated Bounds
+
+Use an outer animated div and an inner measured div. Never measure and animate the same element — it creates a feedback loop.
+
+**Incorrect (measure and animate same element):**
+
+```tsx
+function AnimatedContainer({ children }) {
+  const [ref, bounds] = useMeasure();
+  return (
+    <motion.div ref={ref} animate={{ height: bounds.height }}>
+      {children}
+    </motion.div>
+  );
+}
+```
+
+**Correct (separate measure and animate targets):**
+
+```tsx
+function AnimatedContainer({ children }) {
+  const [ref, bounds] = useMeasure();
+  return (
+    <motion.div animate={{ height: bounds.height }}>
+      <div ref={ref}>{children}</div>
+    </motion.div>
+  );
+}
+```
+
+### 8.2 Guard Against Zero on Initial Render
+
+On initial render, measured bounds are 0. Guard against this to prevent animating from 0 to actual size.
+
+**Incorrect (animates from 0 on mount):**
+
+```tsx
+<motion.div animate={{ width: bounds.width }}>
+  <div ref={ref}>{children}</div>
+</motion.div>
+```
+
+**Correct (falls back to auto on first frame):**
+
+```tsx
+<motion.div animate={{ width: bounds.width > 0 ? bounds.width : "auto" }}>
+  <div ref={ref}>{children}</div>
+</motion.div>
+```
+
+### 8.3 Use ResizeObserver for Measurement
+
+Use ResizeObserver to track element dimensions. It fires on resize without causing layout thrashing.
+
+**Incorrect (measuring on every render):**
+
+```tsx
+function useMeasure(ref) {
+  const [bounds, setBounds] = useState({ width: 0, height: 0 });
+  useEffect(() => {
+    if (ref.current) {
+      const rect = ref.current.getBoundingClientRect();
+      setBounds({ width: rect.width, height: rect.height });
+    }
+  });
+  return bounds;
+}
+```
+
+**Correct (ResizeObserver):**
+
+```tsx
+function useMeasure() {
+  const [element, setElement] = useState(null);
+  const [bounds, setBounds] = useState({ width: 0, height: 0 });
+  const ref = useCallback((node) => setElement(node), []);
+
+  useEffect(() => {
+    if (!element) return;
+    const observer = new ResizeObserver(([entry]) => {
+      setBounds({
+        width: entry.contentRect.width,
+        height: entry.contentRect.height,
+      });
+    });
+    observer.observe(element);
+    return () => observer.disconnect();
+  }, [element]);
+
+  return [ref, bounds];
+}
+```
+
+### 8.4 Overflow Hidden on Animated Container
+
+Set overflow: hidden on the animated outer container to clip content during size transitions.
+
+**Incorrect (content overflows during animation):**
+
+```tsx
+<motion.div animate={{ height: bounds.height }}>
+  <div ref={ref}>{children}</div>
+</motion.div>
+```
+
+**Correct (clipped during transition):**
+
+```tsx
+<motion.div animate={{ height: bounds.height }} style={{ overflow: "hidden" }}>
+  <div ref={ref}>{children}</div>
+</motion.div>
+```
+
+### 8.5 Use Animated Bounds Sparingly
+
+Animated bounds is a subtle effect. Reserve it for interactive elements where size changes are meaningful.
+
+**Good use cases:** loading state buttons, expandable sections, accordions, FAQs, content reveals.
+
+**Bad use cases:** every container on the page, static layouts, elements that don't change size.
+
+### 8.6 Use Callback Ref for Measurement
+
+Use a callback ref (not useRef) for measurement hooks so the observer attaches when the DOM node is ready.
+
+**Incorrect (useRef may be null on first effect):**
+
+```tsx
+const ref = useRef(null);
+useEffect(() => {
+  if (!ref.current) return;
+  observer.observe(ref.current);
+}, []);
+```
+
+**Correct (callback ref guarantees node):**
+
+```tsx
+const [element, setElement] = useState(null);
+const ref = useCallback((node) => setElement(node), []);
+useEffect(() => {
+  if (!element) return;
+  observer.observe(element);
+  return () => observer.disconnect();
+}, [element]);
+```
+
+### 8.7 Add Delay for Natural Container Transitions
+
+Add a small delay so the transition feels like it's catching up to the content.
+
+**Correct:**
+
+```tsx
+<motion.div
+  animate={{ height: bounds.height }}
+  transition={{ duration: 0.2, delay: 0.05 }}
+  style={{ overflow: "hidden" }}
+>
+  <div ref={ref}>{children}</div>
+</motion.div>
+```
+
+Reference: [ResizeObserver - MDN](https://developer.mozilla.org/en-US/docs/Web/API/ResizeObserver), [Motion Documentation](https://motion.dev)
+
+---
+
+## 9. Laws of UX
+
+**Impact:** HIGH — Psychological principles behind interfaces that feel right. Violating these creates friction users can't articulate.
+
+### 9.1 Size Interactive Targets for Easy Clicking
+
+The bigger something is, the easier it is to click (Fitts's Law). Make interactive elements at least 32px.
+
+**Incorrect (tiny click target):**
+
+```css
+.icon-button {
+  width: 16px;
+  height: 16px;
+  padding: 0;
+}
+```
+
+**Correct (comfortable target):**
+
+```css
+.icon-button {
+  width: 32px;
+  height: 32px;
+  padding: 8px;
+}
+```
+
+### 9.2 Expand Hit Areas with Invisible Padding
+
+Use pseudo-elements or invisible padding to expand clickable areas beyond visible bounds.
+
+**Incorrect (visible size equals hit area):**
+
+```css
+.link {
+  font-size: 14px;
+}
+```
+
+**Correct (expanded invisible hit area):**
+
+```css
+.link {
+  position: relative;
+}
+
+.link::before {
+  content: "";
+  position: absolute;
+  inset: -8px -12px;
+}
+```
+
+### 9.3 Minimize Choices to Reduce Decision Time
+
+Decision time increases logarithmically with the number of choices (Hick's Law). Use progressive disclosure.
+
+**Incorrect (all options at once):**
+
+```tsx
+function Settings() {
+  return (
+    <div>
+      {allSettings.map(setting => (
+        <SettingRow key={setting.id} {...setting} />
+      ))}
+    </div>
+  );
+}
+```
+
+**Correct (progressive disclosure):**
+
+```tsx
+function Settings() {
+  return (
+    <div>
+      {commonSettings.map(setting => (
+        <SettingRow key={setting.id} {...setting} />
+      ))}
+      <details>
+        <summary>Advanced</summary>
+        {advancedSettings.map(setting => (
+          <SettingRow key={setting.id} {...setting} />
+        ))}
+      </details>
+    </div>
+  );
+}
+```
+
+### 9.4 Chunk Data into Groups of 5-9
+
+Working memory holds about 7 items (Miller's Law). Group and chunk large data sets for scannability.
+
+**Incorrect (raw unformatted data):**
+
+```tsx
+<span>4532015112830366</span>
+```
+
+**Correct (chunked for readability):**
+
+```tsx
+<span>4532 0151 1283 0366</span>
+```
+
+### 9.5 Respond Within 400ms
+
+Interactions must respond within 400ms to feel instant (Doherty Threshold). Above this, users notice delay.
+
+**Incorrect (no feedback during loading):**
+
+```tsx
+async function handleClick() {
+  const data = await fetchData();
+  setResult(data);
+}
+```
+
+**Correct (immediate optimistic feedback):**
+
+```tsx
+async function handleClick() {
+  setResult(optimisticData);
+  const data = await fetchData();
+  setResult(data);
+}
+```
+
+### 9.6 Fake Speed When Actual Speed Isn't Possible
+
+If you can't make something fast, make it feel fast with optimistic UI, skeletons, or progress indicators.
+
+**Incorrect (blank screen during load):**
+
+```tsx
+function Page() {
+  const { data, isLoading } = useFetch("/api/data");
+  if (isLoading) return null;
+  return <Content data={data} />;
+}
+```
+
+**Correct (skeleton during load):**
+
+```tsx
+function Page() {
+  const { data, isLoading } = useFetch("/api/data");
+  if (isLoading) return <Skeleton />;
+  return <Content data={data} />;
+}
+```
+
+### 9.7 Accept Messy Input, Output Clean Data
+
+Inputs should accept messy human data and normalize it (Postel's Law). Validate generously, format strictly.
+
+**Incorrect (rigid format required):**
+
+```tsx
+function DateInput({ onChange }) {
+  return (
+    <input
+      type="text"
+      placeholder="YYYY-MM-DD"
+      pattern="\d{4}-\d{2}-\d{2}"
+      onChange={onChange}
+    />
+  );
+}
+```
+
+**Correct (accepts multiple formats):**
+
+```tsx
+function DateInput({ onChange }) {
+  function handleChange(e) {
+    const parsed = parseFlexibleDate(e.target.value);
+    if (parsed) onChange(parsed);
+  }
+
+  return (
+    <input
+      type="text"
+      placeholder="Any date format"
+      onChange={handleChange}
+    />
+  );
+}
+```
+
+### 9.8 Show What Matters Now, Reveal Complexity Later
+
+Don't overwhelm users with everything at once. Reveal complexity incrementally as needed.
+
+**Incorrect (all controls visible):**
+
+```tsx
+function Editor() {
+  return (
+    <div>
+      <BasicTools />
+      <AdvancedTools />
+      <ExpertTools />
+      <DebugTools />
+    </div>
+  );
+}
+```
+
+**Correct (progressive disclosure):**
+
+```tsx
+function Editor() {
+  const [showAdvanced, setShowAdvanced] = useState(false);
+  return (
+    <div>
+      <BasicTools />
+      {showAdvanced && <AdvancedTools />}
+      <button onClick={() => setShowAdvanced(!showAdvanced)}>
+        Toggle
+      </button>
+    </div>
+  );
+}
+```
+
+### 9.9 Use Familiar UI Patterns
+
+Users spend most of their time on other sites. They expect yours to work the same way (Jakob's Law).
+
+**Incorrect (custom unconventional navigation):**
+
+```tsx
+function Nav() {
+  return (
+    <nav>
+      <button onClick={() => navigate("/")}>⬡</button>
+      <button onClick={() => navigate("/search")}>⬢</button>
+    </nav>
+  );
+}
+```
+
+**Correct (standard recognizable patterns):**
+
+```tsx
+function Nav() {
+  return (
+    <nav>
+      <Link href="/">Home</Link>
+      <Link href="/search">Search</Link>
+    </nav>
+  );
+}
+```
+
+### 9.10 Visual Polish Increases Perceived Usability
+
+Users perceive aesthetically pleasing design as more usable. Small visual details compound into trust.
+
+**Incorrect (unstyled, raw elements):**
+
+```css
+.card {
+  border: 1px solid black;
+  padding: 10px;
+}
+```
+
+**Correct (considered visual treatment):**
+
+```css
+.card {
+  padding: 16px;
+  background: var(--gray-2);
+  border: 1px solid var(--gray-a4);
+  border-radius: 12px;
+  box-shadow: var(--shadow-1);
+}
+```
+
+### 9.11 Group Related Elements Spatially
+
+Elements near each other are perceived as related (Law of Proximity). Use spacing to create visual groups.
+
+**Incorrect (uniform spacing between unrelated items):**
+
+```css
+.form label,
+.form input,
+.form .hint,
+.form .divider {
+  margin-bottom: 16px;
+}
+```
+
+**Correct (tighter spacing within groups, larger between):**
+
+```css
+.form label {
+  margin-bottom: 4px;
+}
+
+.form input {
+  margin-bottom: 2px;
+}
+
+.form .hint {
+  margin-bottom: 24px;
+}
+```
+
+### 9.12 Similar Elements Should Look Alike
+
+Elements that function the same should look the same (Law of Similarity). Visual consistency signals functional consistency.
+
+**Incorrect (same function, different appearance):**
+
+```css
+.save-button {
+  background: blue;
+  border-radius: 8px;
+}
+
+.submit-button {
+  background: green;
+  border-radius: 0;
+}
+```
+
+**Correct (same function, same appearance):**
+
+```css
+.primary-action {
+  background: var(--gray-12);
+  color: var(--gray-1);
+  border-radius: 8px;
+}
+```
+
+### 9.13 Use Boundaries to Group Related Content
+
+Elements sharing a clearly defined boundary are perceived as a group (Law of Common Region).
+
+**Incorrect (flat list with no visual grouping):**
+
+```tsx
+function Settings() {
+  return (
+    <div>
+      <Toggle label="Dark mode" />
+      <Toggle label="Notifications" />
+      <Input label="Email" />
+      <Input label="Password" />
+    </div>
+  );
+}
+```
+
+**Correct (bounded sections):**
+
+```tsx
+function Settings() {
+  return (
+    <div>
+      <section className={styles.group}>
+        <h3>Appearance</h3>
+        <Toggle label="Dark mode" />
+      </section>
+      <section className={styles.group}>
+        <h3>Account</h3>
+        <Input label="Email" />
+        <Input label="Password" />
+      </section>
+    </div>
+  );
+}
+```
+
+### 9.14 Make Important Elements Visually Distinct
+
+When multiple similar elements are present, the one that differs is most likely to be remembered (Von Restorff Effect).
+
+**Incorrect (primary action blends in):**
+
+```tsx
+<div className={styles.actions}>
+  <button className={styles.button}>Cancel</button>
+  <button className={styles.button}>Delete Account</button>
+</div>
+```
+
+**Correct (destructive action stands out):**
+
+```tsx
+<div className={styles.actions}>
+  <button className={styles["button-secondary"]}>Cancel</button>
+  <button className={styles["button-danger"]}>Delete Account</button>
+</div>
+```
+
+### 9.15 Place Key Items First or Last
+
+Users best remember the first and last items in a sequence (Serial Position Effect).
+
+**Incorrect (important action buried in middle):**
+
+```tsx
+<nav>
+  <Link href="/settings">Settings</Link>
+  <Link href="/">Home</Link>
+  <Link href="/about">About</Link>
+</nav>
+```
+
+**Correct (key items at edges):**
+
+```tsx
+<nav>
+  <Link href="/">Home</Link>
+  <Link href="/about">About</Link>
+  <Link href="/settings">Settings</Link>
+</nav>
+```
+
+### 9.16 End Experiences with Clear Success States
+
+People judge experiences by their peak moment and their end (Peak-End Rule). Invest in completion states.
+
+**Incorrect (abrupt end after action):**
+
+```tsx
+async function handleSubmit() {
+  await submitForm(data);
+  router.push("/");
+}
+```
+
+**Correct (satisfying completion state):**
+
+```tsx
+async function handleSubmit() {
+  await submitForm(data);
+  setStatus("success");
+}
+
+return status === "success" ? (
+  <SuccessScreen message="You're all set." />
+) : (
+  <Form onSubmit={handleSubmit} />
+);
+```
+
+### 9.17 Move Complexity to the System
+
+Every system has irreducible complexity (Tesler's Law). The question is who handles it — the user or the system.
+
+**Incorrect (complexity pushed to user):**
+
+```tsx
+<input
+  type="text"
+  placeholder="Enter date as YYYY-MM-DDTHH:mm:ss.sssZ"
+/>
+```
+
+**Correct (system absorbs complexity):**
+
+```tsx
+<DatePicker
+  onChange={(date) => setDate(date.toISOString())}
+/>
+```
+
+### 9.18 Show Progress Toward Completion
+
+People accelerate behavior as they approach a goal (Goal-Gradient Effect). Show how close they are.
+
+**Incorrect (no sense of progress):**
+
+```tsx
+function Onboarding({ step }) {
+  return <OnboardingStep step={step} />;
+}
+```
+
+**Correct (progress visible):**
+
+```tsx
+function Onboarding({ step, totalSteps }) {
+  return (
+    <div>
+      <ProgressBar value={step} max={totalSteps} />
+      <span>Step {step} of {totalSteps}</span>
+      <OnboardingStep step={step} />
+    </div>
+  );
+}
+```
+
+### 9.19 Show Incomplete State to Drive Completion
+
+People remember incomplete tasks better than completed ones (Zeigarnik Effect).
+
+**Incorrect (no indication of incomplete profile):**
+
+```tsx
+function Dashboard() {
+  return <DashboardContent />;
+}
+```
+
+**Correct (incomplete state visible):**
+
+```tsx
+function Dashboard({ profile }) {
+  return (
+    <div>
+      {!profile.isComplete && (
+        <Banner>
+          Complete your profile — {profile.completionPercent}% done
+        </Banner>
+      )}
+      <DashboardContent />
+    </div>
+  );
+}
+```
+
+### 9.20 Simplify Complex Visuals into Clear Forms
+
+People interpret complex visuals as the simplest form possible (Law of Pragnanz). Reduce visual noise.
+
+**Incorrect (visually noisy layout):**
+
+```css
+.card {
+  border: 2px dashed red;
+  background: linear-gradient(45deg, #f0f, #0ff);
+  box-shadow: 5px 5px 0 black, 10px 10px 0 gray;
+  outline: 3px dotted blue;
+}
+```
+
+**Correct (clear, simple form):**
+
+```css
+.card {
+  background: var(--gray-2);
+  border: 1px solid var(--gray-a4);
+  border-radius: 12px;
+  box-shadow: var(--shadow-1);
+}
+```
+
+### 9.21 Prioritize the Critical 20% of Features
+
+80% of users use 20% of features (Pareto Principle). Optimize the critical path first.
+
+**Incorrect (all features equally prominent):**
+
+```tsx
+function Toolbar() {
+  return (
+    <div>
+      {allFeatures.map(f => <Button key={f.id}>{f.label}</Button>)}
+    </div>
+  );
+}
+```
+
+**Correct (critical features prominent, rest accessible):**
+
+```tsx
+function Toolbar() {
+  return (
+    <div>
+      {criticalFeatures.map(f => <Button key={f.id}>{f.label}</Button>)}
+      <MoreMenu features={secondaryFeatures} />
+    </div>
+  );
+}
+```
+
+### 9.22 Minimize Extraneous Cognitive Load
+
+Remove anything that doesn't help the user complete their task. Decoration, redundant labels, and unnecessary options all add load.
+
+**Incorrect (extraneous elements):**
+
+```tsx
+function DeleteDialog() {
+  return (
+    <dialog>
+      <Icon name="warning" size={64} />
+      <h2>Warning!</h2>
+      <p>Are you absolutely sure you want to delete?</p>
+      <p>This action is permanent and cannot be undone.</p>
+      <p>All associated data will be lost forever.</p>
+      <div>
+        <button>Cancel</button>
+        <button>Delete</button>
+        <button>Learn More</button>
+      </div>
+    </dialog>
+  );
+}
+```
+
+**Correct (essential information only):**
+
+```tsx
+function DeleteDialog() {
+  return (
+    <dialog>
+      <h2>Delete this item?</h2>
+      <p>This can't be undone.</p>
+      <div>
+        <button>Cancel</button>
+        <button>Delete</button>
+      </div>
+    </dialog>
+  );
+}
+```
+
+### 9.23 Visually Connect Related Elements
+
+Elements that are visually connected (by lines, color, or frames) are perceived as more related (Law of Uniform Connectedness).
+
+**Incorrect (steps with no visual connection):**
+
+```tsx
+function Steps({ current }) {
+  return (
+    <div>
+      <span>Step 1</span>
+      <span>Step 2</span>
+      <span>Step 3</span>
+    </div>
+  );
+}
+```
+
+**Correct (connected with a visual line):**
+
+```tsx
+function Steps({ current }) {
+  return (
+    <div className={styles.steps}>
+      {steps.map((step, i) => (
+        <div key={step.id} className={styles.step} data-active={i <= current}>
+          <div className={styles.dot} />
+          {i < steps.length - 1 && <div className={styles.connector} />}
+          <span>{step.label}</span>
+        </div>
+      ))}
+    </div>
+  );
+}
+```
+
+Reference: [Laws of UX](https://lawsofux.com/) by Jon Yablonski
+
+---
+
+## 10. Predictive Prefetching
+
+**Impact:** MEDIUM — Loading content before the user clicks by analyzing cursor trajectory, reducing perceived latency by 100-200ms.
+
+### 10.1 Trajectory Prediction Over Hover Prefetching
+
+Hover prefetching starts too late. Trajectory prediction fires while the cursor is still in motion, reclaiming 100-200ms.
+
+**Incorrect (waits for hover):**
+
+```tsx
+<Link
+  href="/about"
+  onMouseEnter={() => router.prefetch("/about")}
+>
+  About
+</Link>
+```
+
+**Correct (trajectory-based):**
+
+```tsx
+const { elementRef } = useForesight({
+  callback: () => router.prefetch("/about"),
+  hitSlop: 20,
+  name: "about-link",
+});
+
+<Link ref={elementRef} href="/about">About</Link>
+```
+
+### 10.2 Prefetch by Intent, Not Viewport
+
+Don't prefetch everything visible in the viewport. Prefetch based on user intent to avoid wasted bandwidth.
+
+**Incorrect (prefetch all visible links):**
+
+```tsx
+<Link href="/page" prefetch={true}>Page</Link>
+```
+
+**Correct (intent-based prefetching):**
+
+```tsx
+<Link href="/page" prefetch={false}>Page</Link>
+```
+
+### 10.3 Use hitSlop to Trigger Predictions Earlier
+
+Expand the invisible prediction area around elements with hitSlop to start loading sooner.
+
+**Incorrect (tight prediction area):**
+
+```tsx
+const { elementRef } = useForesight({
+  callback: () => prefetch(),
+  hitSlop: 0,
+});
+```
+
+**Correct (expanded prediction area):**
+
+```tsx
+const { elementRef } = useForesight({
+  callback: () => prefetch(),
+  hitSlop: 20,
+});
+```
+
+### 10.4 Fall Back Gracefully on Touch Devices
+
+Touch devices have no cursor. Fall back to viewport or touch-start strategies automatically.
+
+**Incorrect (assumes cursor exists):**
+
+```tsx
+function PrefetchLink({ href, children }) {
+  return (
+    <Link
+      href={href}
+      onMouseMove={() => prefetch(href)}
+    >
+      {children}
+    </Link>
+  );
+}
+```
+
+**Correct (device-aware strategy):**
+
+```tsx
+const { elementRef } = useForesight({
+  callback: () => router.prefetch(href),
+  hitSlop: 20,
+});
+```
+
+### 10.5 Prefetch on Keyboard Navigation
+
+Monitor focus changes and prefetch when the user is a few tab stops away from a registered element.
+
+**Correct (tab-aware prefetching):**
+
+```tsx
+const { elementRef } = useForesight({
+  callback: () => router.prefetch("/settings"),
+  name: "settings-link",
+});
+```
+
+### 10.6 Use Predictive Prefetching Selectively
+
+Predictive prefetching doesn't belong in every project. Use it where navigation latency is noticeable.
+
+**Good use cases:** data-heavy dashboards, multi-page apps with slow API responses, e-commerce product pages.
+
+**Bad use cases:** static sites with instant navigation, single-page apps with all data preloaded.
+
+Reference: [ForesightJS](https://foresightjs.com), [Next.js Prefetching Docs](https://nextjs.org/docs/app/guides/prefetching)
+
+---
+
+## 11. Typography
+
+**Impact:** MEDIUM — CSS font and text properties most developers overlook. The difference between typographically considered and not.
+
+### 11.1 Tabular Numbers for Data Display
+
+Use tabular-nums for any numeric data that should align in columns.
+
+**Incorrect (proportional numbers misalign):**
+
+```css
+.price { font-variant-numeric: proportional-nums; }
+```
+
+**Correct (tabular numbers align):**
+
+```css
+.price { font-variant-numeric: tabular-nums; }
+```
+
+### 11.2 Oldstyle Numbers for Body Text
+
+Use oldstyle-nums in body text so numbers blend with lowercase letters. Use lining-nums in tables and headings.
+
+**Correct (prose):**
+
+```css
+.body-text { font-variant-numeric: oldstyle-nums; }
+```
+
+**Correct (data):**
+
+```css
+.data-table { font-variant-numeric: lining-nums tabular-nums; }
+```
+
+### 11.3 Slashed Zero for Disambiguation
+
+Enable slashed zero in code-adjacent UIs so users never confuse 0 with O.
+
+**Correct:**
+
+```css
+.code { font-variant-numeric: slashed-zero; }
+```
+
+### 11.4 Enable Contextual Alternates
+
+Keep contextual alternates (calt) enabled. They adjust punctuation and glyph shapes based on surrounding characters.
+
+**Correct (usually on by default — don't disable):**
+
+```css
+body { font-feature-settings: "calt" 1; }
+```
+
+### 11.5 Use Disambiguation Stylistic Set for UI
+
+Enable ss02 (or your font's disambiguation set) in code-facing UIs to distinguish I, l, 1 and 0, O.
+
+**Correct:**
+
+```css
+.code-ui { font-feature-settings: "ss02"; }
+```
+
+### 11.6 Keep Optical Sizing Auto
+
+Leave font-optical-sizing at auto. The font adjusts glyph shapes for the current size — thicker strokes at small sizes, finer details at large sizes.
+
+**Incorrect (forced off):**
+
+```css
+body { font-optical-sizing: none; }
+```
+
+**Correct (automatic adjustment):**
+
+```css
+body { font-optical-sizing: auto; }
+```
+
+### 11.7 Use Antialiased Font Smoothing
+
+Set -webkit-font-smoothing: antialiased on retina displays. Default subpixel rendering looks thicker and fuzzier.
+
+**Correct:**
+
+```css
+body {
+  -webkit-font-smoothing: antialiased;
+  -moz-osx-font-smoothing: grayscale;
+}
+```
+
+### 11.8 Balance Headings with text-wrap
+
+Use text-wrap: balance on headings to make lines roughly equal length instead of one long line and a short orphan.
+
+**Incorrect (unbalanced heading):**
+
+```css
+h1 { /* default text-wrap */ }
+```
+
+**Correct (balanced):**
+
+```css
+h1 { text-wrap: balance; }
+```
+
+### 11.9 Offset Underlines from Descenders
+
+Use text-underline-offset to push underlines below descenders so they look intentional.
+
+**Incorrect (underline collides with descenders):**
+
+```css
+a { text-decoration: underline; }
+```
+
+**Correct (offset underline):**
+
+```css
+a {
+  text-decoration: underline;
+  text-underline-offset: 3px;
+  text-decoration-skip-ink: auto;
+}
+```
+
+### 11.10 Disable Font Synthesis for Missing Styles
+
+Set font-synthesis: none to prevent the browser from faking bold or italic. Browser-generated faux styles look terrible.
+
+**Correct:**
+
+```css
+.icon-font,
+.display-font {
+  font-synthesis: none;
+}
+```
+
+**Typography quick reference:**
+
+| Property | Use Case | Value |
+|----------|----------|-------|
+| `font-variant-numeric: tabular-nums` | Data tables, pricing | Fixed-width digits |
+| `font-variant-numeric: oldstyle-nums` | Body text | Blends with lowercase |
+| `font-variant-numeric: slashed-zero` | Code UIs | Distinguishes 0 from O |
+| `font-feature-settings: "ss02"` | Code UIs | Disambiguates I/l/1 |
+| `font-optical-sizing: auto` | Everywhere | Size-adaptive glyphs |
+| `-webkit-font-smoothing: antialiased` | Retina displays | Thinner, cleaner text |
+| `text-wrap: balance` | Headings | Even line lengths |
+| `text-underline-offset: 3px` | Links | Clear descender space |
+| `font-synthesis: none` | Display/icon fonts | Prevents faux styles |
+
+### 11.11 Use font-display swap
+
+Set font-display: swap so text renders immediately with a fallback while the custom font loads.
+
+**Correct:**
+
+```css
+@font-face {
+  font-family: "Inter";
+  src: url("/fonts/inter.woff2") format("woff2");
+  font-display: swap;
+}
+```
+
+### 11.12 Continuous Weight Values with Variable Fonts
+
+Variable fonts accept any integer from 100-900, not just standard stops.
+
+**Correct (precise weight):**
+
+```css
+.medium { font-weight: 450; }
+.semibold { font-weight: 550; }
+```
+
+### 11.13 text-wrap pretty for Body Text
+
+Use text-wrap: pretty for body text to reduce orphans. Use balance for headings.
+
+**Correct:**
+
+```css
+p { text-wrap: pretty; }
+h1, h2, h3 { text-wrap: balance; }
+```
+
+### 11.14 Pair Justified Text with Hyphens
+
+Justified text without hyphens creates rivers of whitespace.
+
+**Incorrect (rivers):**
+
+```css
+.article { text-align: justify; }
+```
+
+**Correct (hyphenation prevents rivers):**
+
+```css
+.article {
+  text-align: justify;
+  hyphens: auto;
+}
+```
+
+### 11.15 Add Letter Spacing to Uppercase Text
+
+Uppercase and small-caps text needs positive letter-spacing to feel open and readable.
+
+**Incorrect (tight uppercase):**
+
+```css
+.label {
+  text-transform: uppercase;
+  font-size: 12px;
+}
+```
+
+**Correct (opened up):**
+
+```css
+.label {
+  text-transform: uppercase;
+  font-size: 12px;
+  letter-spacing: 0.05em;
+}
+```
+
+### 11.16 Use Typographic Fractions
+
+Enable diagonal-fractions to convert 1/2, 1/3 into proper typographic fractions.
+
+**Correct:**
+
+```css
+.recipe { font-variant-numeric: diagonal-fractions; }
+```
+
+Reference: [Inter Typeface](https://rsms.me/inter/), [MDN font-feature-settings](https://developer.mozilla.org/en-US/docs/Web/CSS/font-feature-settings), [MDN font-variant-numeric](https://developer.mozilla.org/en-US/docs/Web/CSS/font-variant-numeric)
+
+---
+
+## 12. Visual Design
+
+**Impact:** HIGH — CSS design fundamentals that compound into visual polish. Small details that separate considered interfaces from default ones.
+
+### 12.1 Concentric Border Radius for Nested Elements
+
+When nesting rounded elements, inner radius must equal outer radius minus the gap. Same radius on both creates uneven curves.
+
+**Incorrect (same radius on both):**
+
+```css
+.outer {
+  border-radius: 16px;
+  padding: 8px;
+}
+
+.inner {
+  border-radius: 16px;
+}
+```
+
+**Correct (concentric radius):**
+
+```css
+.outer {
+  --padding: 8px;
+  --inner-radius: 8px;
+
+  border-radius: calc(var(--inner-radius) + var(--padding));
+  padding: var(--padding);
+}
+
+.inner {
+  border-radius: var(--inner-radius);
+}
+```
+
+### 12.2 Layer Multiple Shadows for Realistic Depth
+
+A single box-shadow looks flat. Layer multiple shadows with increasing blur and decreasing opacity to mimic real light.
+
+**Incorrect (single flat shadow):**
+
+```css
+.card {
+  box-shadow: 0 4px 16px rgba(0, 0, 0, 0.2);
+}
+```
+
+**Correct (layered shadows):**
+
+```css
+.card {
+  box-shadow:
+    0 1px 2px rgba(0, 0, 0, 0.06),
+    0 4px 8px rgba(0, 0, 0, 0.04),
+    0 12px 24px rgba(0, 0, 0, 0.03);
+}
+```
+
+### 12.3 Consistent Shadow Direction Across UI
+
+All shadows must share the same offset direction to imply a single light source. Mixed directions feel broken.
+
+**Incorrect (conflicting light sources):**
+
+```css
+.card { box-shadow: 0 4px 8px rgba(0, 0, 0, 0.1); }
+.modal { box-shadow: 4px 0 8px rgba(0, 0, 0, 0.1); }
+.tooltip { box-shadow: 0 -4px 8px rgba(0, 0, 0, 0.1); }
+```
+
+**Correct (consistent top-down light):**
+
+```css
+.card { box-shadow: 0 2px 8px rgba(0, 0, 0, 0.08); }
+.modal { box-shadow: 0 8px 24px rgba(0, 0, 0, 0.12); }
+.tooltip { box-shadow: 0 4px 12px rgba(0, 0, 0, 0.1); }
+```
+
+### 12.4 Use Neutral Colors for Shadows
+
+Pure black shadows look harsh. Use deep neutrals or semi-transparent dark colors.
+
+**Incorrect (pure black):**
+
+```css
+.card {
+  box-shadow: 0 4px 12px rgba(0, 0, 0, 0.25);
+}
+```
+
+**Correct (neutral shadow):**
+
+```css
+.card {
+  box-shadow: 0 4px 12px rgba(17, 24, 39, 0.08);
+}
+```
+
+### 12.5 Shadow Size Indicates Elevation
+
+Larger blur and offset means higher elevation. Use a consistent shadow scale.
+
+**Correct (elevation scale):**
+
+```css
+:root {
+  --shadow-1: 0 1px 2px rgba(0, 0, 0, 0.05);
+  --shadow-2: 0 2px 8px rgba(0, 0, 0, 0.08);
+  --shadow-3: 0 8px 24px rgba(0, 0, 0, 0.12);
+}
+
+.card { box-shadow: var(--shadow-1); }
+.dropdown { box-shadow: var(--shadow-2); }
+.modal { box-shadow: var(--shadow-3); }
+```
+
+### 12.6 Animate Shadows via Pseudo-Element Opacity
+
+Transitioning box-shadow directly forces expensive repaints. Animate opacity on a pseudo-element instead.
+
+**Incorrect (animating box-shadow):**
+
+```css
+.card {
+  box-shadow: var(--shadow-1);
+  transition: box-shadow 0.2s ease;
+}
+.card:hover {
+  box-shadow: var(--shadow-3);
+}
+```
+
+**Correct (pseudo-element opacity):**
+
+```css
+.card {
+  position: relative;
+  box-shadow: var(--shadow-1);
+}
+.card::after {
+  content: "";
+  position: absolute;
+  inset: 0;
+  border-radius: inherit;
+  box-shadow: var(--shadow-3);
+  opacity: 0;
+  transition: opacity 0.2s ease;
+  pointer-events: none;
+  z-index: -1;
+}
+.card:hover::after {
+  opacity: 1;
+}
+```
+
+### 12.7 Use a Consistent Spacing Scale
+
+Don't use arbitrary pixel values. Define a scale and use it throughout.
+
+**Incorrect (arbitrary values):**
+
+```css
+.header { padding: 17px; }
+.card { margin-bottom: 13px; }
+.section { gap: 22px; }
+```
+
+**Correct (consistent scale):**
+
+```css
+:root {
+  --space-1: 4px;
+  --space-2: 8px;
+  --space-3: 12px;
+  --space-4: 16px;
+  --space-5: 24px;
+  --space-6: 32px;
+  --space-7: 48px;
+}
+
+.header { padding: var(--space-4); }
+.card { margin-bottom: var(--space-3); }
+.section { gap: var(--space-5); }
+```
+
+### 12.8 Use Semi-Transparent Borders
+
+Semi-transparent borders adapt to any background color and create subtle, non-jarring separation.
+
+**Incorrect (hardcoded border color):**
+
+```css
+.card {
+  border: 1px solid #e5e5e5;
+}
+```
+
+**Correct (alpha border):**
+
+```css
+.card {
+  border: 1px solid var(--gray-a4);
+}
+```
+
+### 12.9 Full Shadow Anatomy on Buttons
+
+A polished button uses six layered techniques, not just a single box-shadow:
+
+1. **Outer cut shadow** — 0.5px dark box-shadow to "cut" the button into the surface
+2. **Inner ambient highlight** — 1px inset box-shadow on all sides for environmental light reflections
+3. **Inner top highlight** — 1px inset top highlight for the primary light source from above
+4. **Layered depth shadows** — At least 3 external shadows for natural lighting
+5. **Text drop-shadow** — Drop-shadow on text/icons for better contrast against the button background
+6. **Subtle gradient background** — If you can tell there's a gradient, it's too much
+
+**Incorrect (flat button):**
+
+```css
+.button {
+  background: var(--gray-12);
+  color: var(--gray-1);
+  box-shadow: 0 2px 4px rgba(0, 0, 0, 0.1);
+}
+```
+
+**Correct (full shadow anatomy):**
+
+```css
+.button {
+  background: linear-gradient(
+    to bottom,
+    color-mix(in srgb, var(--gray-12) 100%, white 4%),
+    var(--gray-12)
+  );
+  color: var(--gray-1);
+  box-shadow:
+    0 0 0 0.5px rgba(0, 0, 0, 0.3),
+    inset 0 0 0 1px rgba(255, 255, 255, 0.04),
+    inset 0 1px 0 rgba(255, 255, 255, 0.07),
+    0 1px 2px rgba(0, 0, 0, 0.1),
+    0 2px 4px rgba(0, 0, 0, 0.06),
+    0 4px 8px rgba(0, 0, 0, 0.03);
+  text-shadow: 0 1px 1px rgba(0, 0, 0, 0.15);
+}
+```
+
+Reference: [Designing Beautiful Shadows in CSS](https://www.joshwcomeau.com/css/designing-shadows/), [Concentric Border Radius](https://jakub.kr/work/concentric-border-radius), [@PixelJanitor](https://threadreaderapp.com/thread/1623358514440859649)
+
+---
+
+## Output Format
+
+When reviewing files, output findings as:
+
+```
+file:line - [rule-id] description of issue
+
+Example:
+components/modal/index.tsx:45 - [timing-under-300ms] Exit animation 400ms exceeds 300ms limit
+components/button/styles.module.css:12 - [physics-active-state] Missing :active transform
+components/drawer/index.tsx:23 - [spring-for-gestures] Drag interaction using easing instead of spring
+```
+
+## Summary Table
+
+After findings, output a summary:
+
+| Rule | Count | Severity |
+|------|-------|----------|
+| `timing-under-300ms` | 2 | HIGH |
+| `physics-active-state` | 3 | MEDIUM |
+| `exit-requires-wrapper` | 1 | HIGH |
+
+## References
+
+- [The Illusion of Life: Disney Animation](https://www.amazon.com/Illusion-Life-Disney-Animation/dp/0786860707)
+- [Apple WWDC23: Animate with Springs](https://developer.apple.com/videos/play/wwdc2023/10158)
+- [Motion Documentation](https://motion.dev)
+- [The Beauty of Bezier Curves - Freya Holmer](https://www.youtube.com/watch?v=aVwxzDHniEw)
+- [MDN Pseudo-elements Reference](https://developer.mozilla.org/en-US/docs/Web/CSS/Reference/Selectors/Pseudo-elements)
+- [View Transitions API](https://developer.mozilla.org/en-US/docs/Web/API/View_Transitions_API)
+- [Web Audio API Documentation](https://developer.mozilla.org/en-US/docs/Web/API/Web_Audio_API)
+- [prefers-reduced-motion](https://developer.mozilla.org/en-US/docs/Web/CSS/@media/prefers-reduced-motion)
+- [SVG Line Element](https://developer.mozilla.org/en-US/docs/Web/SVG/Element/line)
+- [ResizeObserver - MDN](https://developer.mozilla.org/en-US/docs/Web/API/ResizeObserver)
+- [Laws of UX](https://lawsofux.com/) by Jon Yablonski
+- [ForesightJS](https://foresightjs.com)
+- [Next.js Prefetching Docs](https://nextjs.org/docs/app/guides/prefetching)
+- [Inter Typeface](https://rsms.me/inter/)
+- [MDN font-feature-settings](https://developer.mozilla.org/en-US/docs/Web/CSS/font-feature-settings)
+- [MDN font-variant-numeric](https://developer.mozilla.org/en-US/docs/Web/CSS/font-variant-numeric)
+- [Designing Beautiful Shadows in CSS - Josh W. Comeau](https://www.joshwcomeau.com/css/designing-shadows/)
+- [Concentric Border Radius](https://jakub.kr/work/concentric-border-radius)
+- [Nested Rounded Corners](https://www.ondrejkonecny.com/blog/nested-rounded-corners/)
+- [MDN text-wrap](https://developer.mozilla.org/en-US/docs/Web/CSS/text-wrap)