@caoscompanybr/merlin 3.5.0

package/.merlin-core/skills/general/design-ux-patterns/references/ux-guidelines.md

@@ -0,0 +1,837 @@
+# Complete UX Guidelines (133 Rules)
+
+> Reference data for the design-ux-patterns skill. Organized by category with do/don't and code examples.
+
+## Navigation (1-20)
+
+### 1. Smooth Scroll Behavior
+
+- **Do:** `html { scroll-behavior: smooth; }` with `prefers-reduced-motion` override
+- **Don't:** Use JavaScript-based smooth scroll that ignores motion preferences
+- **Severity:** Medium
+
+### 2. Sticky Navigation
+
+- **Do:** `position: sticky; top: 0; z-index: 50;` with shadow on scroll
+- **Don't:** Use `position: fixed` which removes element from flow
+- **Severity:** Medium
+
+### 3. Active Navigation State
+
+- **Do:** Highlight current page/section with `aria-current="page"` + visual indicator
+- **Don't:** Rely only on color change without accessible markup
+- **Severity:** High
+
+### 4. Back Button Support
+
+- **Do:** Use proper routing that supports browser back/forward navigation
+- **Don't:** Break browser history with `window.location.replace()` for internal navigation
+- **Severity:** High
+
+### 5. Deep Linking
+
+- **Do:** Every significant view should have a unique URL for sharing/bookmarking
+- **Don't:** Use client-side state that can't be reconstructed from the URL
+- **Severity:** Medium
+
+### 6. Breadcrumbs
+
+- **Do:** Use `<nav aria-label="Breadcrumb"><ol>` with structured data
+- **Don't:** Use `<div>` with `>` separators and no semantic markup
+- **Severity:** Medium
+
+### 7. Bottom Nav Limit
+
+- **Do:** Maximum 5 items in bottom navigation. Always include both icon and text label.
+- **Don't:** Cram 6+ items into bottom nav or use icon-only navigation items
+- **Severity:** High
+
+### 8. Drawer Usage
+
+- **Do:** Use drawer/sidebar for secondary navigation (settings, account, help), not primary actions
+- **Don't:** Place primary navigation actions inside a hamburger menu — they become invisible
+- **Severity:** High
+
+### 9. Nav Label + Icon
+
+- **Do:** Navigation items must have both icon and text label for discoverability
+- **Don't:** Use icon-only navigation — it harms discoverability and forces users to guess meaning
+- **Severity:** High
+
+### 10. Nav Hierarchy
+
+- **Do:** Clearly separate primary navigation (tabs/bottom bar) from secondary (drawer/settings)
+- **Don't:** Mix navigation levels — tab bar items should not open drawers or nested tab bars
+- **Severity:** Medium
+
+### 11. Modal Escape
+
+- **Do:** Modals and sheets must offer a clear close/dismiss affordance. Support swipe-down on mobile.
+- **Don't:** Trap users in modals without visible close button or gesture support
+- **Severity:** High
+
+### 12. Search Accessible
+
+- **Do:** Search must be easily reachable (top bar or dedicated tab). Provide recent and suggested queries.
+- **Don't:** Bury search behind multiple taps or hide it in a menu
+- **Severity:** Medium
+
+### 13. State Preservation
+
+- **Do:** Navigating back must restore previous scroll position, filter state, and input values
+- **Don't:** Reset page state on back navigation — users lose their place and work
+- **Severity:** High
+
+### 14. Gesture Nav Support
+
+- **Do:** Support system gesture navigation (iOS swipe-back, Android predictive back) without conflict
+- **Don't:** Override system gestures with custom swipe handlers on the same edge
+- **Severity:** Medium
+
+### 15. Adaptive Navigation
+
+- **Do:** Large screens (≥1024px) use sidebar navigation. Small screens use bottom nav or top bar.
+- **Don't:** Force the same navigation layout across all screen sizes
+- **Severity:** Medium
+
+### 16. Back Stack Integrity
+
+- **Do:** Back button behavior must be predictable — always return to the previous screen in the stack
+- **Don't:** Silently reset the navigation stack or unexpectedly jump to home on back press
+- **Severity:** High
+
+### 17. Navigation Consistency
+
+- **Do:** Navigation placement and structure must stay the same across all pages of the application
+- **Don't:** Change navigation layout, position, or items depending on the current page
+- **Severity:** High
+
+### 18. Modal vs Navigation
+
+- **Do:** Use modals for confirmations, alerts, and self-contained tasks. Use navigation for primary user flows.
+- **Don't:** Use modals as navigation screens — they break the user's mental model and back button behavior
+- **Severity:** Medium
+
+### 19. Focus on Route Change
+
+- **Do:** After page/route transition, move focus to the main content region for screen reader users
+- **Don't:** Leave focus on the previous page's navigation element after route change
+- **Severity:** High
+
+### 20. Persistent Nav
+
+- **Do:** Core navigation must remain reachable from deep pages — never hide it entirely in sub-flows
+- **Don't:** Remove global navigation on detail pages, forcing users to use only the back button
+- **Severity:** Medium
+
+## Animation (7-14)
+
+### 7. Excessive Animation
+
+- **Do:** Use subtle, purposeful animations that guide attention (150-300ms)
+- **Don't:** Animate everything or use durations > 500ms for UI transitions
+- **Severity:** High
+
+### 8. Animation Duration
+
+- **Do:** Micro-interactions: 150-300ms. Page transitions: 300-500ms. Loading: loop until complete.
+- **Don't:** Use the same duration for all animations regardless of context
+- **Severity:** Medium
+
+### 9. Reduced Motion
+
+- **Do:** `@media (prefers-reduced-motion: reduce) { *, *::before, *::after { animation-duration: 0.01ms !important; transition-duration: 0.01ms !important; } }`
+- **Don't:** Ignore the preference or only apply it to some animations
+- **Severity:** Critical
+
+### 10. Loading States
+
+- **Do:** Show skeleton screens for content, spinners for actions, progress bars for uploads
+- **Don't:** Show blank screens or only text "Loading..."
+- **Severity:** High
+
+### 11. Hover vs Tap Distinction
+
+- **Do:** Use `@media (hover: hover)` to apply hover effects only on hover-capable devices
+- **Don't:** Apply `:hover` styles that get stuck on touch devices
+- **Severity:** Medium
+
+### 12. Continuous Animation
+
+- **Do:** Allow users to pause/stop continuous animations (carousels, marquees)
+- **Don't:** Run infinite animations without pause controls (WCAG 2.2.2)
+- **Severity:** High
+
+### 13. Transform Performance
+
+- **Do:** Animate `transform` and `opacity` only — they run on the compositor thread
+- **Don't:** Animate `width`, `height`, `top`, `left`, `margin`, `padding` — they trigger layout
+- **Severity:** Medium
+
+### 14. Easing Functions
+
+- **Do:** Use `ease-out` for entrances, `ease-in` for exits, `ease-in-out` for position changes
+- **Don't:** Use `linear` for UI transitions (feels robotic) or custom beziers without testing
+- **Severity:** Low
+
+## Layout (15-21)
+
+### 15. Z-Index Management
+
+- **Do:** Use a z-index scale: base(0), dropdown(100), sticky(200), modal(300), toast(400), tooltip(500)
+- **Don't:** Use arbitrary z-index values (999, 9999, 99999)
+- **Severity:** Medium
+
+### 16. Overflow Handling
+
+- **Do:** Use `overflow-x: auto` on containers that may overflow, with scroll indicators
+- **Don't:** Use `overflow: hidden` to hide problems — fix the root cause
+- **Severity:** Medium
+
+### 17. Fixed Positioning
+
+- **Do:** Use `position: fixed` only for persistent UI (nav, FAB, toast). Test on mobile.
+- **Don't:** Use fixed positioning for content that should scroll with the page
+- **Severity:** Medium
+
+### 18. Stacking Context
+
+- **Do:** Create explicit stacking contexts with `isolation: isolate` on container elements
+- **Don't:** Add `position: relative; z-index` to fix stacking — understand the stacking context
+- **Severity:** Low
+
+### 19. Content Jumping (CLS)
+
+- **Do:** Reserve space for dynamic content (images, ads, embeds) with explicit dimensions
+- **Don't:** Insert content that pushes existing content down after initial render
+- **Severity:** High
+
+### 20. Viewport Units
+
+- **Do:** Use `dvh` (dynamic viewport height) for full-screen layouts on mobile
+- **Don't:** Use `100vh` which doesn't account for mobile browser chrome
+- **Severity:** Medium
+
+### 21. Container Width
+
+- **Do:** Set `max-width` on content containers (1280px typical). Center with `margin: 0 auto`.
+- **Don't:** Let content stretch to full viewport width on large screens
+- **Severity:** Medium
+
+## Touch & Mobile (22-27)
+
+### 22. Touch Target Size
+
+- **Do:** Minimum 44x44px touch target (48x48px recommended). Use padding to expand small elements.
+- **Don't:** Use small icons/links without expanding their touch area
+- **Severity:** Critical
+- **Code:** `button { min-width: 44px; min-height: 44px; }`
+
+### 23. Touch Target Spacing
+
+- **Do:** Minimum 8px gap between adjacent touch targets
+- **Don't:** Place touch targets directly adjacent with no gap
+- **Severity:** High
+
+### 24. Gesture Conflicts
+
+- **Do:** Avoid horizontal swipe gestures that conflict with browser back/forward
+- **Don't:** Override system gestures or use swipe for destructive actions without confirmation
+- **Severity:** Medium
+
+### 25. Tap Delay
+
+- **Do:** Use `touch-action: manipulation` to remove 300ms tap delay
+- **Don't:** Use click handlers without addressing the delay on older mobile browsers
+- **Severity:** Medium
+
+### 26. Pull to Refresh
+
+- **Do:** If implementing, use `overscroll-behavior-y: contain` to prevent browser PTR conflicts
+- **Don't:** Implement custom PTR that fights with the browser's native behavior
+- **Severity:** Low
+
+### 27. Haptic Feedback
+
+- **Do:** Use `navigator.vibrate()` sparingly for confirmations on mobile (if supported)
+- **Don't:** Use haptics for routine interactions or without checking API support
+- **Severity:** Low
+
+## Interaction States (28-35)
+
+### 28. Focus States
+
+- **Do:** Visible focus ring on ALL interactive elements. Use `:focus-visible` to avoid showing on click.
+- **Don't:** `outline: none` or `outline: 0` without a replacement focus style
+- **Severity:** Critical
+- **Code:** `*:focus-visible { outline: 2px solid var(--primary); outline-offset: 2px; }`
+
+### 29. Hover States
+
+- **Do:** Subtle visual change (opacity, color shift, shadow) that doesn't alter layout
+- **Don't:** Change element size or position on hover — causes layout shifts
+- **Severity:** High
+
+### 30. Active States
+
+- **Do:** Visual press/click feedback (scale down slightly, darken) for buttons and cards
+- **Don't:** Skip active state — users need feedback that their click registered
+- **Severity:** Medium
+
+### 31. Disabled States
+
+- **Do:** `opacity: 0.5; cursor: not-allowed; pointer-events: none;` plus `aria-disabled="true"`
+- **Don't:** Only visually dim without preventing interaction or communicating state
+- **Severity:** High
+
+### 32. Loading Buttons
+
+- **Do:** Replace button text with spinner, set `aria-busy="true"`, disable during load
+- **Don't:** Allow double-clicks or show no feedback during async action
+- **Severity:** High
+
+### 33. Error Feedback
+
+- **Do:** Inline error near the source, red border + icon + text, `role="alert"` for screen readers
+- **Don't:** Only show a toast/banner that disappears before users can read it
+- **Severity:** Critical
+
+### 34. Success Feedback
+
+- **Do:** Clear success message near the action, green check + text, auto-dismiss after 5s
+- **Don't:** Show nothing after successful action — users need confirmation
+- **Severity:** High
+
+### 35. Confirmation Dialogs
+
+- **Do:** Require confirmation for destructive actions. State what will happen. Offer undo when possible.
+- **Don't:** Delete/remove items immediately without confirmation or undo option
+- **Severity:** High
+
+## Accessibility (36-45)
+
+### 36. Color Contrast
+
+- **Do:** 4.5:1 for normal text, 3:1 for large text (18px+ or 14px+ bold), 3:1 for UI components
+- **Don't:** Use light gray (#999) on white or assume "it looks fine" without checking
+- **Severity:** Critical
+
+### 37. Color-Only Information
+
+- **Do:** Use color + icon + text to convey status (green check "Success", red X "Error")
+- **Don't:** Use only red/green colors to indicate pass/fail — color-blind users can't distinguish
+- **Severity:** Critical
+
+### 38. Alt Text
+
+- **Do:** Descriptive alt for content images. `alt=""` for decorative images. `aria-label` for icon buttons.
+- **Don't:** Leave alt attribute missing entirely (screen readers read the filename)
+- **Severity:** Critical
+
+### 39. Heading Hierarchy
+
+- **Do:** One `<h1>` per page. Never skip levels. Use headings for structure, not styling.
+- **Don't:** Use `<h3>` because it looks the right size — use CSS to style the correct heading level
+- **Severity:** High
+
+### 40. ARIA Labels
+
+- **Do:** `aria-label` on icon-only buttons/links. `aria-labelledby` for sections. `aria-describedby` for hints.
+- **Don't:** Add redundant ARIA to elements that already have accessible names (e.g., button with text)
+- **Severity:** High
+
+### 41. Keyboard Navigation
+
+- **Do:** All interactive elements reachable via Tab. Logical tab order. Enter/Space activate.
+- **Don't:** Use `tabindex > 0` (breaks natural order). Use div/span as buttons without role+keyboard.
+- **Severity:** Critical
+
+### 42. Screen Reader Testing
+
+- **Do:** Test with NVDA (Windows) or VoiceOver (Mac) at least once per major feature
+- **Don't:** Assume ARIA labels work correctly without testing with actual screen readers
+- **Severity:** High
+
+### 43. Form Labels
+
+- **Do:** `<label for="id">` on every input. Group related inputs in `<fieldset>` with `<legend>`.
+- **Don't:** Use placeholder text as the only label — it disappears on input
+- **Severity:** Critical
+
+### 44. Error Messages
+
+- **Do:** Associate errors to inputs via `aria-describedby`. Use `role="alert"` for dynamic errors.
+- **Don't:** Display errors far from the input or only at the top of the form
+- **Severity:** High
+
+### 45. Skip Links
+
+- **Do:** First focusable element: `<a href="#main" class="sr-only focus:not-sr-only">Skip to content</a>`
+- **Don't:** Omit skip links — keyboard users must Tab through entire nav on every page
+- **Severity:** High
+
+## Performance (46-53)
+
+### 46. Image Optimization
+
+- **Do:** WebP/AVIF with `<picture>` fallback. Explicit `width`/`height`. `srcset` for responsive.
+- **Don't:** Serve unoptimized PNG/JPG at full resolution for all viewports
+- **Severity:** High
+
+### 47. Lazy Loading
+
+- **Do:** `loading="lazy"` on below-fold images. Eager load above-fold hero/LCP image.
+- **Don't:** Lazy load the hero image (delays LCP) or skip lazy loading entirely
+- **Severity:** High
+
+### 48. Code Splitting
+
+- **Do:** Dynamic `import()` for route-level splitting. Lazy load heavy components (charts, editors).
+- **Don't:** Ship entire app as single bundle — check with `webpack-bundle-analyzer` or equivalent
+- **Severity:** Medium
+
+### 49. Caching
+
+- **Do:** Immutable assets (hashed filenames): `Cache-Control: max-age=31536000, immutable`. HTML: no-cache.
+- **Don't:** Cache HTML pages aggressively or skip cache headers entirely
+- **Severity:** Medium
+
+### 50. Font Loading
+
+- **Do:** `display=swap` on Google Fonts. Preload critical fonts. Limit to 2-3 weights.
+- **Don't:** Load 6+ font weights or use `display=block` (causes FOIT)
+- **Severity:** Medium
+
+### 51. Third-Party Scripts
+
+- **Do:** Load analytics/ads with `async` or `defer`. Use `dns-prefetch` for external domains.
+- **Don't:** Load third-party scripts synchronously in `<head>` — blocks rendering
+- **Severity:** High
+
+### 52. Bundle Size
+
+- **Do:** Tree-shake unused code. Replace heavy libs (moment.js -> date-fns, lodash -> lodash-es).
+- **Don't:** Import entire libraries when you only need one function
+- **Severity:** Medium
+
+### 53. Render Blocking
+
+- **Do:** Inline critical CSS. Defer non-critical CSS with `media="print" onload="this.media='all'"`.
+- **Don't:** Include large CSS files in `<head>` that block first render
+- **Severity:** High
+
+## Forms (54-63)
+
+### 54. Input Labels
+
+- **Do:** Visible label above or beside every input, using `<label for="">` association
+- **Don't:** Use placeholder as the only label — fails WCAG and confuses users once they start typing
+- **Severity:** Critical
+
+### 55. Error Placement
+
+- **Do:** Show error message directly below the invalid input, with red border + icon
+- **Don't:** Only show errors at the top of the form or in a separate section
+- **Severity:** High
+
+### 56. Inline Validation
+
+- **Do:** Validate on blur (not on every keystroke). Show success state for corrected fields.
+- **Don't:** Validate while the user is still typing — it's distracting
+- **Severity:** Medium
+
+### 57. Input Types
+
+- **Do:** `type="email"` for emails, `type="tel"` for phones, `type="url"` for URLs, `inputmode="numeric"` for numbers
+- **Don't:** Use `type="text"` for everything — mobile users get wrong keyboard
+- **Severity:** Medium
+
+### 58. Autofill Support
+
+- **Do:** Use `autocomplete` attributes: `name`, `email`, `tel`, `address-line1`, `cc-number`, etc.
+- **Don't:** Disable autofill (`autocomplete="off"`) — it frustrates users and ignores browser hints
+- **Severity:** Medium
+
+### 59. Required Field Indicators
+
+- **Do:** Mark required fields with asterisk (\*) + "(required)" text. Or mark optional fields instead.
+- **Don't:** Rely on color alone to indicate required fields
+- **Severity:** Medium
+
+### 60. Password Visibility Toggle
+
+- **Do:** Provide show/hide toggle on password inputs with `aria-label` that updates on toggle
+- **Don't:** Force users to type passwords blind, especially on mobile
+- **Severity:** Medium
+
+### 61. Submit Feedback
+
+- **Do:** Disable submit button + show spinner during async submit. Show success/error after.
+- **Don't:** Allow multiple submits or show no feedback while waiting
+- **Severity:** High
+
+### 62. Input Affordance
+
+- **Do:** Inputs should look like inputs — border, background contrast, clear boundaries
+- **Don't:** Make inputs look like plain text or blend into the background
+- **Severity:** Medium
+
+### 63. Mobile Keyboards
+
+- **Do:** Use `inputmode="numeric"` for PIN fields, `inputmode="decimal"` for prices
+- **Don't:** Use `type="number"` for things that aren't quantities (phone, zip, credit card)
+- **Severity:** Medium
+
+## Responsive (64-71)
+
+### 64. Mobile-First
+
+- **Do:** Write base styles for mobile, then add complexity with `min-width` media queries
+- **Don't:** Design for desktop first and try to squeeze it into mobile
+- **Severity:** High
+
+### 65. Breakpoint Testing
+
+- **Do:** Test at: 375px (iPhone SE), 390px (iPhone 14), 768px (iPad), 1024px (laptop), 1440px (desktop)
+- **Don't:** Only test at one mobile and one desktop size
+- **Severity:** High
+
+### 66. Touch-Friendly
+
+- **Do:** Increase padding on interactive elements for mobile. No hover-only interactions.
+- **Don't:** Assume mouse precision on touch devices
+- **Severity:** High
+
+### 67. Readable Font Size
+
+- **Do:** Minimum 16px body text on all viewports (prevents iOS auto-zoom on input focus)
+- **Don't:** Use 12-14px body text on mobile for "fitting more content"
+- **Severity:** High
+
+### 68. Viewport Meta
+
+- **Do:** `<meta name="viewport" content="width=device-width, initial-scale=1">`
+- **Don't:** Set `maximum-scale=1` or `user-scalable=no` (breaks accessibility zoom)
+- **Severity:** Critical
+
+### 69. Horizontal Scroll
+
+- **Do:** Prevent with `max-width: 100%` on images/embeds. Use `overflow-x: auto` on tables.
+- **Don't:** Allow horizontal scroll on the main page body
+- **Severity:** High
+
+### 70. Image Scaling
+
+- **Do:** `img { max-width: 100%; height: auto; }` as baseline. Use `srcset` for responsive images.
+- **Don't:** Serve 2000px-wide images to mobile viewports
+- **Severity:** Medium
+
+### 71. Table Handling
+
+- **Do:** On mobile: horizontal scroll wrapper, card layout, or collapsible rows
+- **Don't:** Let wide tables break the layout or become unreadable on small screens
+- **Severity:** Medium
+
+## Typography (72-77)
+
+### 72. Line Height
+
+- **Do:** 1.5-1.6 for body, 1.2-1.3 for headings, 1.7+ for long-form reading
+- **Don't:** Use 1.0 line height or the browser default without setting it explicitly
+- **Severity:** High
+
+### 73. Line Length
+
+- **Do:** 65-75 characters per line (`max-width: 65ch` or `max-w-prose` in Tailwind)
+- **Don't:** Allow text to span the full viewport width on large screens
+- **Severity:** Medium
+
+### 74. Font Size Scale
+
+- **Do:** Use a consistent scale ratio (1.25 major third recommended). Define tokens for each step.
+- **Don't:** Use arbitrary sizes (13px, 17px, 22px) with no systematic relationship
+- **Severity:** Medium
+
+### 75. Font Loading Strategy
+
+- **Do:** Preload critical fonts. Use `font-display: swap`. Subset to needed characters.
+- **Don't:** Load all weights/styles upfront. Use `font-display: block` (causes invisible text flash).
+- **Severity:** Medium
+
+### 76. Contrast Readability
+
+- **Do:** Test body text contrast at actual size and on actual backgrounds (not just hero sections)
+- **Don't:** Assume a color combo works because it passes contrast at large heading sizes
+- **Severity:** High
+
+### 77. Heading Clarity
+
+- **Do:** Clear visual distinction between heading levels (size, weight, spacing)
+- **Don't:** Make h2 and h3 look nearly identical — users need visual hierarchy cues
+- **Severity:** Medium
+
+## Feedback (78-83)
+
+### 78. Loading Indicators
+
+- **Do:** Skeleton screens for content loading, spinners for actions, progress bars for deterministic operations
+- **Don't:** Show blank white screens during loading or only a generic "Loading..."
+- **Severity:** High
+
+### 79. Empty States
+
+- **Do:** Helpful message + illustration + action button ("No projects yet — Create your first project")
+- **Don't:** Show a blank screen or only "No data" text
+- **Severity:** Medium
+
+### 80. Error Recovery
+
+- **Do:** Clear error message + specific fix instruction + retry action ("Connection failed — Check your internet and try again [Retry]")
+- **Don't:** Show technical error messages (500 Internal Server Error) to end users
+- **Severity:** High
+
+### 81. Progress Indicators
+
+- **Do:** Show step count for multi-step flows ("Step 2 of 4"). Progress bar for uploads/processing.
+- **Don't:** Leave users guessing how many steps remain or how long an operation takes
+- **Severity:** Medium
+
+### 82. Toast Notifications
+
+- **Do:** Auto-dismiss success toasts after 5s. Persist error toasts until dismissed. Stack multiple.
+- **Don't:** Show toasts that cover important UI, overlap each other, or disappear too quickly (< 3s)
+- **Severity:** Medium
+
+### 83. Confirmation Messages
+
+- **Do:** Confirm success inline near the action when possible, not just in toast
+- **Don't:** Only confirm via toast that the user might miss
+- **Severity:** Medium
+
+## Content (84-87)
+
+### 84. Text Truncation
+
+- **Do:** Use ellipsis (`text-overflow: ellipsis`) + tooltip/expand for long text. Show full text on interaction.
+- **Don't:** Hard-truncate text without indicating there's more content
+- **Severity:** Low
+
+### 85. Date Formatting
+
+- **Do:** Relative for recent ("2 hours ago"), absolute for old ("Jan 15, 2026"). Use user's locale.
+- **Don't:** Show raw ISO timestamps or use ambiguous formats (01/02/03)
+- **Severity:** Low
+
+### 86. Number Formatting
+
+- **Do:** Locale-aware formatting: commas, decimals, currency symbols. Abbreviate large numbers (1.2M).
+- **Don't:** Show raw numbers without formatting (1000000 instead of 1,000,000)
+- **Severity:** Low
+
+### 87. Placeholder Content
+
+- **Do:** Use realistic placeholder content during development that matches expected data shape
+- **Don't:** Use "Lorem ipsum" in production or test with only short strings
+- **Severity:** Low
+
+## Specialized Patterns (88-99)
+
+### 88. Onboarding - User Freedom
+
+- **Do:** Always provide skip + back buttons in onboarding flows
+- **Don't:** Trap users in mandatory onboarding without escape
+- **Severity:** Medium
+
+### 89. Search - Autocomplete
+
+- **Do:** Show suggestions after 2+ characters, debounce at 300ms, highlight matching text
+- **Don't:** Wait for Enter to search, show results without relevance ranking
+- **Severity:** Medium
+
+### 90. Search - No Results
+
+- **Do:** Helpful "no results" with suggestions: check spelling, try broader terms, browse categories
+- **Don't:** Show blank or only "No results found" without guidance
+- **Severity:** Medium
+
+### 91. Data Entry - Bulk Actions
+
+- **Do:** Checkbox selection + floating action bar showing count ("3 selected — Delete | Export")
+- **Don't:** Force users to act on items one at a time
+- **Severity:** Medium
+
+### 92. AI - Disclaimer
+
+- **Do:** Clearly label AI-generated content. Show confidence levels when available.
+- **Don't:** Present AI output as authoritative fact without disclaimer
+- **Severity:** High
+
+### 93. AI - Streaming Response
+
+- **Do:** Stream text token-by-token with typing indicator. Allow stop/cancel mid-generation.
+- **Don't:** Wait for full response then dump all text at once
+- **Severity:** Medium
+
+### 94. Spatial UI - Gaze Hover (VisionOS)
+
+- **Do:** Use system hover effects that respond to eye tracking. Increase target sizes for gaze.
+- **Don't:** Use small targets or custom hover that fights the system's spatial interaction model
+- **Severity:** Medium (platform-specific)
+
+### 95. Spatial UI - Depth Layering
+
+- **Do:** Use z-depth to indicate hierarchy and interactivity in spatial interfaces
+- **Don't:** Flatten all UI to a single plane in spatial computing environments
+- **Severity:** Medium (platform-specific)
+
+### 96. Sustainability - Auto-Play Video
+
+- **Do:** Never auto-play video with sound. Offer play button. Prefer static thumbnails on mobile.
+- **Don't:** Auto-play video on page load (wastes bandwidth, startles users)
+- **Severity:** High
+
+### 97. Sustainability - Asset Weight
+
+- **Do:** Target < 500KB initial page weight. Compress images aggressively. Use system fonts as fallback.
+- **Don't:** Ship 5MB+ pages with unoptimized assets
+- **Severity:** Medium
+
+### 98. AI - Feedback Loop
+
+- **Do:** Provide thumbs up/down or rate response quality for AI outputs
+- **Don't:** Offer no way for users to signal bad AI output
+- **Severity:** Medium
+
+### 99. Motion Sensitivity
+
+- **Do:** Provide UI toggle to disable animations in addition to OS-level preference
+- **Don't:** Rely solely on OS `prefers-reduced-motion` — not all users know about it
+- **Severity:** Medium
+
+## Advanced Animation (100-107)
+
+### 100. Spring Physics
+
+- **Do:** Prefer spring/physics-based animation curves over linear or cubic-bezier for natural, organic feel
+- **Don't:** Use linear easing for UI transitions — it feels robotic and unnatural
+- **Severity:** Medium
+
+### 101. Exit Faster Than Enter
+
+- **Do:** Exit animations should be ~60-70% of enter duration to feel responsive (e.g., enter 300ms, exit 200ms)
+- **Don't:** Use the same duration for enter and exit — exits should feel snappier
+- **Severity:** Medium
+
+### 102. Stagger Sequence
+
+- **Do:** Stagger list/grid item entrance by 30-50ms per item for a polished reveal effect
+- **Don't:** Show all items at once (flat) or stagger too slowly (>100ms) — both feel wrong
+- **Severity:** Low
+
+### 103. Shared Element Transition
+
+- **Do:** Use shared element / hero transitions for visual continuity between screens (card → detail page)
+- **Don't:** Use unrelated transitions between screens that share visible elements — breaks spatial continuity
+- **Severity:** Medium
+
+### 104. Interruptible Animations
+
+- **Do:** All animations must be interruptible — user tap or gesture immediately cancels in-progress animation
+- **Don't:** Block user input during animations or force users to wait for animation completion
+- **Severity:** High
+
+### 105. No Blocking Animation
+
+- **Do:** UI must stay interactive during all animations — never disable input while animating
+- **Don't:** Use animations that prevent the user from taking their next action
+- **Severity:** High
+
+### 106. Motion Consistency
+
+- **Do:** Unify duration and easing tokens globally — all animations share the same rhythm and timing feel
+- **Don't:** Mix fast (100ms) and slow (500ms) transitions randomly across the same interface
+- **Severity:** Medium
+
+### 107. Hierarchy Motion
+
+- **Do:** Use translate/scale direction to express hierarchy: enter from below = deeper level, exit upward = going back
+- **Don't:** Use random animation directions — movement should communicate navigation direction
+- **Severity:** Low
+
+## Advanced Forms & Feedback (108-119)
+
+### 108. Progressive Disclosure
+
+- **Do:** Reveal complex options progressively — show basic fields first, advanced settings behind a toggle/expand
+- **Don't:** Overwhelm users upfront with every possible field and option on a single screen
+- **Severity:** Medium
+
+### 109. Form Autosave
+
+- **Do:** Long forms (5+ fields) should auto-save drafts to prevent data loss on accidental dismissal or navigation
+- **Don't:** Lose all user input when they accidentally close a tab or navigate away from a long form
+- **Severity:** Medium
+
+### 110. Sheet Dismiss Confirm
+
+- **Do:** Confirm before dismissing a modal/sheet/drawer that contains unsaved user changes
+- **Don't:** Silently discard unsaved changes when a user swipes down or taps outside a modal
+- **Severity:** High
+
+### 111. Field Grouping
+
+- **Do:** Group related fields logically using `<fieldset>` + `<legend>` or clear visual grouping with spacing/borders
+- **Don't:** Present all form fields in a flat undifferentiated list — users can't scan or understand the structure
+- **Severity:** Medium
+
+### 112. Read-Only Distinction
+
+- **Do:** Read-only fields should be visually distinct from both editable and disabled states (e.g., no border, plain text style)
+- **Don't:** Make read-only look identical to disabled — they have different semantics and user expectations
+- **Severity:** Medium
+
+### 113. Focus Management
+
+- **Do:** After a form submission error, auto-focus the first invalid field and scroll it into view
+- **Don't:** Show errors without moving focus — keyboard and screen reader users can't find the problem
+- **Severity:** High
+- **Code:** `document.querySelector('[aria-invalid="true"]')?.focus()`
+
+### 114. Error Summary
+
+- **Do:** For forms with multiple errors, show a summary at the top with anchor links to each invalid field
+- **Don't:** Only show inline errors without a summary — users with many errors can't see the full picture
+- **Severity:** Medium
+- **Code:** `<div role="alert"><h2>3 errors found</h2><ul><li><a href="#email">Email is required</a></li>...</ul></div>`
+
+### 115. Undo Support
+
+- **Do:** Allow undo for destructive or bulk actions with a time-limited toast ("Deleted 3 items — Undo")
+- **Don't:** Immediately and permanently execute destructive actions without any recovery option
+- **Severity:** High
+
+### 116. Destructive Emphasis
+
+- **Do:** Destructive actions use semantic danger color (red) and are visually separated from primary actions
+- **Don't:** Style delete/remove buttons identically to save/submit — users will click them by mistake
+- **Severity:** High
+
+### 117. Toast Accessibility
+
+- **Do:** Toasts must use `aria-live="polite"` for screen reader announcement. Must not steal focus from current task.
+- **Don't:** Use `aria-live="assertive"` for routine notifications or let toasts capture keyboard focus
+- **Severity:** Medium
+- **Code:** `<div role="status" aria-live="polite">Changes saved successfully</div>`
+
+### 118. ARIA Live Errors
+
+- **Do:** Dynamic form errors must use `aria-live` region or `role="alert"` to notify screen readers immediately
+- **Don't:** Add error text to the DOM without any ARIA announcement — screen reader users won't know it appeared
+- **Severity:** High
+- **Code:** `<span role="alert" id="email-error">Please enter a valid email</span>`
+
+### 119. Timeout Feedback
+
+- **Do:** Request timeouts must show clear user-friendly feedback with a retry action button
+- **Don't:** Show a blank screen, spinner forever, or technical timeout error without recovery option
+- **Severity:** High