@ranimontagna/agent-toolkit 0.3.6 → 0.3.7

package/skills/frontend/design/ui-ux-pro-max/data/ux-guidelines.csv

@@ -6,27 +6,27 @@ No,Category,Issue,Platform,Description,Do,Don't,Code Example Good,Code Example B
 5,Navigation,Deep Linking,All,URLs should reflect current state for sharing,Update URL on state/view changes,Static URLs for dynamic content,Use query params or hash,Single URL for all states,Medium
 6,Navigation,Breadcrumbs,Web,Show user location in site hierarchy,Use for sites with 3+ levels of depth,Use for flat single-level sites,Home > Category > Product,Only on deep nested pages,Low
 7,Animation,Excessive Motion,All,Too many animations cause distraction and motion sickness,Animate 1-2 key elements per view maximum,Animate everything that moves,Single hero animation,animate-bounce on 5+ elements,High
-8,Animation,Duration Timing,All,Animations should feel responsive not sluggish,Use 150-300ms for micro-interactions,Use animations longer than 500ms for UI,transition-all duration-200,duration-1000,Medium
+8,Animation,Duration Timing,All,Motion duration depends on distance complexity platform and user context,Use shared motion tokens and test that feedback stays responsive,Present 150-300ms or any cutoff as a universal requirement,transition-colors duration-200,One duration copied to every transition,Medium
 9,Animation,Reduced Motion,All,Respect user's motion preferences,Check prefers-reduced-motion media query,Ignore accessibility motion settings,@media (prefers-reduced-motion: reduce),No motion query check,High
 10,Animation,Loading States,All,Show feedback during async operations,Use skeleton screens or spinners,Leave UI frozen with no feedback,animate-pulse skeleton,Blank screen while loading,High
 11,Animation,Hover vs Tap,All,Hover effects don't work on touch devices,Use click/tap for primary interactions,Rely only on hover for important actions,onClick handler,onMouseEnter only,High
 12,Animation,Continuous Animation,All,Infinite animations are distracting,Use for loading indicators only,Use for decorative elements,animate-spin on loader,animate-bounce on icons,Medium
 13,Animation,Transform Performance,Web,Some CSS properties trigger expensive repaints,Use transform and opacity for animations,Animate width/height/top/left properties,transform: translateY(),top: 10px animation,Medium
-14,Animation,Easing Functions,All,Linear motion feels robotic,Use ease-out for entering ease-in for exiting,Use linear for UI transitions,ease-out,linear,Low
+14,Animation,Easing Functions,All,Easing should match how an element changes speed and purpose,Use deceleration when arriving acceleration when leaving and linear for constant-rate progress,Reject linear easing even for steady rotation or progress,ease-out for entry; linear for spinner,ease-in-out for every motion,Low
 15,Layout,Z-Index Management,Web,Stacking context conflicts cause hidden elements,Define z-index scale system (10 20 30 50),Use arbitrary large z-index values,z-10 z-20 z-50,z-[9999],High
 16,Layout,Overflow Hidden,Web,Hidden overflow can clip important content,Test all content fits within containers,Blindly apply overflow-hidden,overflow-auto with scroll,overflow-hidden truncating content,Medium
 17,Layout,Fixed Positioning,Web,Fixed elements can overlap or be inaccessible,Account for safe areas and other fixed elements,Stack multiple fixed elements carelessly,Fixed nav + fixed bottom with gap,Multiple overlapping fixed elements,Medium
 18,Layout,Stacking Context,Web,New stacking contexts reset z-index,Understand what creates new stacking context,Expect z-index to work across contexts,Parent with z-index isolates children,z-index: 9999 not working,Medium
-19,Layout,Content Jumping,Web,Layout shift when content loads is jarring,Reserve space for async content,Let images/content push layout around,aspect-ratio or fixed height,No dimensions on images,High
+19,Layout,Content Jumping,Web,Images badges validation text and skeleton replacements can shift nearby content when they update,Reserve appropriate space or keep async states in a stable content-driven container,Insert compact text or media without a layout strategy,aspect-ratio for media; stable count slot for badges,Badge insertion pushes toolbar actions,High
 20,Layout,Viewport Units,Web,100vh can be problematic on mobile browsers,Use dvh or account for mobile browser chrome,Use 100vh for full-screen mobile layouts,min-h-dvh or min-h-screen,h-screen on mobile,Medium
 21,Layout,Container Width,Web,Content too wide is hard to read,Limit max-width for text content (65-75ch),Let text span full viewport width,max-w-prose or max-w-3xl,Full width paragraphs,Medium
-22,Touch,Touch Target Size,Mobile,Small buttons are hard to tap accurately,Minimum 44x44px touch targets,Tiny clickable areas,min-h-[44px] min-w-[44px],w-6 h-6 buttons,High
+22,Touch,Touch Target Size,Mobile,Touch target guidance depends on platform and web context,Use 44pt on iOS and 48dp on Android; for web use the separate WCAG Target Size rule,Treat one unit or minimum as universal across platforms,iOS 44pt; Android 48dp; Web 24 CSS px plus WCAG exceptions,w-6 h-6 buttons,High
 23,Touch,Touch Spacing,Mobile,Adjacent touch targets need adequate spacing,Minimum 8px gap between touch targets,Tightly packed clickable elements,gap-2 between buttons,gap-0 or gap-1,Medium
 24,Touch,Gesture Conflicts,Mobile,Custom gestures can conflict with system,Avoid horizontal swipe on main content,Override system gestures,Vertical scroll primary,Horizontal swipe carousel only,Medium
 25,Touch,Tap Delay,Mobile,300ms tap delay feels laggy,Use touch-action CSS or fastclick,Default mobile tap handling,touch-action: manipulation,No touch optimization,Medium
 26,Touch,Pull to Refresh,Mobile,Accidental refresh is frustrating,Disable where not needed,Enable by default everywhere,overscroll-behavior: contain,Default overscroll,Low
 27,Touch,Haptic Feedback,Mobile,Tactile feedback improves interaction feel,Use for confirmations and important actions,Overuse vibration feedback,navigator.vibrate(10),Vibrate on every tap,Low
-28,Interaction,Focus States,All,Keyboard users need visible focus indicators,Use visible focus rings on interactive elements,Remove focus outline without replacement,focus:ring-2 focus:ring-blue-500,outline-none without alternative,High
+28,Interaction,Focus States,All,"Keyboard focus, including controls inside a modal, needs a visible indicator","Use a visible focus ring on every interactive control, including modal controls",Remove focus outline without replacement,focus:ring-2 focus:ring-blue-500,outline-none without alternative,High
 29,Interaction,Hover States,Web,Visual feedback on interactive elements,Change cursor and add subtle visual change,No hover feedback on clickable elements,hover:bg-gray-100 cursor-pointer,No hover style,Medium
 30,Interaction,Active States,All,Show immediate feedback on press/click,Add pressed/active state visual change,No feedback during interaction,active:scale-95,No active state,Medium
 31,Interaction,Disabled States,All,Clearly indicate non-interactive elements,Reduce opacity and change cursor,Confuse disabled with normal state,opacity-50 cursor-not-allowed,Same style as enabled,Medium
@@ -39,7 +39,7 @@ No,Category,Issue,Platform,Description,Do,Don't,Code Example Good,Code Example B
 38,Accessibility,Alt Text,All,Images need text alternatives,Descriptive alt text for meaningful images,Empty or missing alt attributes,alt='Dog playing in park',alt='' for content images,High
 39,Accessibility,Heading Hierarchy,Web,Screen readers use headings for navigation,Use sequential heading levels h1-h6,Skip heading levels or misuse for styling,h1 then h2 then h3,h1 then h4,Medium
 40,Accessibility,ARIA Labels,All,Interactive elements need accessible names,Add aria-label for icon-only buttons,Icon buttons without labels,aria-label='Close menu',<button><Icon/></button>,High
-41,Accessibility,Keyboard Navigation,Web,All functionality accessible via keyboard,Tab order matches visual order,Keyboard traps or illogical tab order,tabIndex for custom order,Unreachable elements,High
+41,Accessibility,Keyboard Navigation,Web,Web users need complete keyboard navigation with visible focus on every operable control,Keep tab order aligned with visual order and test every action without a pointer,Keyboard traps or illogical tab order,tabIndex for custom order,Unreachable elements,High
 42,Accessibility,Screen Reader,All,Content should make sense when read aloud,Use semantic HTML and ARIA properly,Div soup with no semantics,<nav> <main> <article>,<div> for everything,Medium
 43,Accessibility,Form Labels,All,Inputs must have associated labels,Use label with for attribute or wrap input,Placeholder-only inputs,<label for='email'>,placeholder='Email' only,High
 44,Accessibility,Error Messages,All,Error messages must be announced,Use aria-live or role=alert for errors,Visual-only error indication,role='alert',Red border only,High
@@ -53,7 +53,7 @@ No,Category,Issue,Platform,Description,Do,Don't,Code Example Good,Code Example B
 52,Performance,Bundle Size,Web,Large JavaScript slows interaction,Monitor and minimize bundle size,Ignore bundle size growth,Bundle analyzer,No size monitoring,Medium
 53,Performance,Render Blocking,Web,CSS/JS can block first paint,Inline critical CSS defer non-critical,Large blocking CSS files,Critical CSS inline,All CSS in head,Medium
 54,Forms,Input Labels,All,Every input needs a visible label,Always show label above or beside input,Placeholder as only label,<label>Email</label><input>,placeholder='Email' only,High
-55,Forms,Error Placement,All,Errors should appear near the problem,Show error below related input,Single error message at top of form,Error under each field,All errors at form top,Medium
+55,Forms,Error Placement,All,Each invalid field needs an inline error connected to that field,Show a specific error below the input and reference it with aria-describedby,Show only a top-level error without identifying each invalid field,"<input aria-describedby=""email-error""><p id=""email-error"">Enter an email address</p>",Red border or summary only,High
 56,Forms,Inline Validation,All,Validate as user types or on blur,Validate on blur for most fields,Validate only on submit,onBlur validation,Submit-only validation,Medium
 57,Forms,Input Types,All,Use appropriate input types,Use email tel number url etc,Text input for everything,type='email',type='text' for email,Medium
 58,Forms,Autofill Support,Web,Help browsers autofill correctly,Use autocomplete attribute properly,Block or ignore autofill,autocomplete='email',autocomplete='off' everywhere,Medium
@@ -76,7 +76,7 @@ No,Category,Issue,Platform,Description,Do,Don't,Code Example Good,Code Example B
 75,Typography,Font Loading,Web,Fonts should load without layout shift,Reserve space with fallback font,Layout shift when fonts load,font-display: swap + similar fallback,No fallback font,Medium
 76,Typography,Contrast Readability,All,Body text needs good contrast,Use darker text on light backgrounds,Gray text on gray background,text-gray-900 on white,text-gray-400 on gray-100,High
 77,Typography,Heading Clarity,All,Headings should stand out from body,Clear size/weight difference,Headings similar to body text,Bold + larger size,Same size as body,Medium
-78,Feedback,Loading Indicators,All,Show system status during waits,Show spinner/skeleton for operations > 300ms,No feedback during loading,Skeleton or spinner,Frozen UI,High
+78,Feedback,Loading Indicators,All,Loading feedback should match the expected wait and avoid flashing for near-instant work,Follow platform and component guidance; preserve layout focus and accessible busy status,Apply one timing threshold to every operation or leave long waits unexplained,Stable skeleton or progress with aria-busy,Flickering spinner or frozen UI,High
 79,Feedback,Empty States,All,Guide users when no content exists,Show helpful message and action,Blank empty screens,No items yet. Create one!,Empty white space,Medium
 80,Feedback,Error Recovery,All,Help users recover from errors,Provide clear next steps,Error without recovery path,Try again button + help link,Error message only,Medium
 81,Feedback,Progress Indicators,All,Show progress for multi-step processes,Step indicators or progress bar,No indication of progress,Step 2 of 4 indicator,No step information,Medium
@@ -94,7 +94,27 @@ No,Category,Issue,Platform,Description,Do,Don't,Code Example Good,Code Example B
 93,AI Interaction,Streaming,All,Waiting for full text is slow,Stream text response token by token,Show loading spinner for 10s+,Typewriter effect,Spinner until 100% complete,Medium
 94,Spatial UI,Gaze Hover,VisionOS,Elements should respond to eye tracking before pinch,Scale/highlight element on look,Static element until pinch,hoverEffect(),onTap only,High
 95,Spatial UI,Depth Layering,VisionOS,UI needs Z-depth to separate content from environment,Use glass material and z-offset,Flat opaque panels blocking view,.glassBackgroundEffect(),bg-white,Medium
-96,Sustainability,Auto-Play Video,Web,Video consumes massive data and energy,Click-to-play or pause when off-screen,Auto-play high-res video loops,playsInline muted preload='none',autoplay loop,Medium
+96,Sustainability,Auto-Play Video,Web,Autoplaying media consumes data and creates motion barriers,Prefer click-to-play; provide pause and captions; stop off-screen and honor reduced motion,Auto-play high-resolution loops without pause or captions,"<video controls preload=""none""><track kind=""captions"" /></video>",autoplay loop,Medium
 97,Sustainability,Asset Weight,Web,Heavy 3D/Image assets increase carbon footprint,Compress and lazy load 3D models,Load 50MB textures,Draco compression,Raw .obj files,Medium
 98,AI Interaction,Feedback Loop,All,AI needs user feedback to improve,Thumps up/down or 'Regenerate',Static output only,Feedback component,Read-only text,Low
-99,Accessibility,Motion Sensitivity,All,Parallax/Scroll-jacking causes nausea,Respect prefers-reduced-motion,Force scroll effects,@media (prefers-reduced-motion),ScrollTrigger.create(),High
+99,Accessibility,Motion Sensitivity,All,Parallax/Scroll-jacking causes nausea,Honor prefers-reduced-motion and present the final readable state without parallax or scroll-jacking,Force scroll effects,@media (prefers-reduced-motion),ScrollTrigger.create(),High
+100,Accessibility,Focus Not Obscured (Minimum),Web,WCAG 2.2 AA requires keyboard focus to remain at least partially visible,Offset sticky UI with scroll-padding and dismiss or move persistent overlays,Let headers footers banners or chat widgets fully cover focus,scroll-padding-top: var(--header-height),fixed overlay covers :focus,High
+101,Accessibility,Focus Not Obscured (Enhanced),Web,WCAG 2.2 AAA requires keyboard focus to remain fully visible,Keep the entire focused component unobscured by author-created content,Present this enhanced AAA criterion as an AA requirement or allow persistent UI to hide any part of focus,close persistent overlay before focus moves behind it,sticky footer covers half the focused button,Medium
+102,Accessibility,Focus Appearance,Web,WCAG 2.2 AAA defines minimum area and contrast for focus indicators,Use an indicator at least as large as a 2 CSS px perimeter with 3:1 state contrast,Present this enhanced AAA criterion as an AA requirement or use a thin low-contrast outline,outline: 2px solid currentColor; outline-offset: 2px,box-shadow: 0 0 1px low-contrast,Medium
+103,Accessibility,Dragging Movements,All,WCAG 2.2 AA requires a single-pointer alternative for author-controlled drag operations,Add buttons menus or tap-to-move controls and retain keyboard operation,Make dragging the only way to reorder resize or select,Move up and Move down buttons beside drag handle,drag handle only,High
+104,Accessibility,Target Size (Minimum),Web,WCAG 2.2 AA requires 24 CSS px pointer targets or an applicable exception,Use at least 24 by 24 CSS px or verify spacing equivalent inline user-agent or essential exceptions,Assume native 44pt or 48dp guidance defines web conformance,min-width: 24px; min-height: 24px,tiny adjacent icon buttons,High
+105,Accessibility,Consistent Help,All,WCAG 2.2 A requires repeated help mechanisms to stay in the same relative order,Keep contact self-help and automated help in consistent locations,Move help controls to different locations on each page,shared header help menu,page-specific help placement,Medium
+106,Forms,Redundant Entry,All,WCAG 2.2 A avoids requiring the same information twice in one process,Auto-populate prior values or let users select previously entered information,Ask users to retype the same address or account data without necessity,reuse confirmed shipping address,repeat full address form,Medium
+107,Security / Accessibility,Accessible Authentication (Minimum),All,WCAG 2.2 AA says authentication must not depend only on a cognitive function test unless an exception applies,Allow password managers and paste; offer passkeys OAuth or another non-cognitive method,Block paste or require manual OTP transcription with no alternative,"autocomplete=""current-password"" and paste allowed",onpaste preventDefault,Critical
+108,Animation,Auto-Rotating Content Controls,All,Auto-rotating content needs user control,Provide previous next and play/pause; stop on focus or hover and when reduced motion is requested,Auto-advance slides without a stop control,"button aria-label=""Pause carousel""",timer-only carousel,High
+109,Forms / Accessibility,Focusable Error Summary,Web,An error summary for failed validation complements inline field errors and must be easy to find by keyboard and screen reader users,Place it at the top of the form; move focus to its heading or container after failed submit; link each item to its invalid field; retain inline errors,Replace inline errors with a visual-only summary or move focus on every blur,"<div role=""alert"" tabindex=""-1"" aria-labelledby=""error-title""><h2 id=""error-title"">There is a problem</h2><a href=""#email"">Enter an email address</a></div>",Toast only with no field links or focus target,High
+110,Typography,Heading Line Balance,Web,Short multi-line headings may use balanced wrapping as a progressive visual heuristic,Bound the measure and test natural-wrap fallback across widths fonts and locales,Promise an exact final line or insert blanket nonbreaking spaces or hardcoded br tags,.hero-title { max-inline-size: 20ch; text-wrap: balance; },Heading copy rewritten with forced last-line breaks,Medium
+111,Layout,Long Token Wrapping,Web,URLs identifiers and user content must not force horizontal overflow,Use overflow-wrap anywhere and let flex or grid text children shrink,Apply word-break break-all to all prose,.token { min-inline-size: 0; overflow-wrap: anywhere; },.token { white-space: nowrap; },High
+112,Accessibility,Text Reflow and Spacing,Web,Text must remain available at narrow widths zoom and user spacing overrides,Use fluid sizes content-driven height and unitless line height,Clip text in fixed-width or fixed-height boxes,".copy { inline-size: min(100%, 65ch); height: auto; line-height: 1.5; }",.copy { width: 900px; height: 40px; overflow: hidden; },Critical
+113,Content,Essential Text Truncation,All,Headings actions errors safety text and distinguishing names need complete access,Wrap stack resize or provide a visible full-detail path,Clamp essential meaning only to make cards uniform,Action label wraps or opens full details,Primary action shown only as an unexplained ellipsis,Critical
+114,Content,Compact Label Semantics,All,Badges communicate state while chips or tags represent values or actions,Choose static or interactive markup from the label's meaning and ownership,Make every pill clickable or encode status with color alone,<span class='status'>Pending</span>,<div class='pill' onclick='toggle()'>Pending</div>,High
+115,Layout,Chip Collection Reflow,All,Filter chips and editable value collections must preserve labels when space or text size changes,Wrap the collection or use an operable +n disclosure for hidden overflow values,Force all chips into one clipped row or hide overflow values,<div class='chip-list'>{chips}</div> with flex-wrap,<div class='chip-list' style='height:32px;overflow:hidden'>,High
+116,Content,Compact Label Overflow,All,A badge chip or pill label should stay whole on one line when practical and disclose unavoidable truncation,Bound only unpredictable values; use nowrap with a shrinkable label; expose full text to keyboard pointer and touch users,Let one compact label wrap to a second line or use a hover-only tooltip,Flexible label with min-width 0 and an operable full-value disclosure,Fixed-width badge wraps to second line or clips with title-only recovery,High
+117,Accessibility,Compact Control Semantics,Web,Interactive chips need a native role accessible name state keyboard operation and visible focus,Prefer a button and expose pressed or selected state that matches the visible label,Use a clickable div or reveal the only action on hover,<button aria-pressed='true'>Open now</button>,<div class='selected' onclick='toggle()'>Open now</div>,Critical
+118,Accessibility,Contextual Live Badge Updates,Web,Async badge and count changes should announce a meaningful contextual status without moving focus,Use one appropriate atomic status message such as 3 items in cart,Announce a bare number or make every badge a competing live region,<span role='status' aria-atomic='true'>3 items in cart</span>,<span aria-live='polite'>3</span>,High
+119,Animation,Cancellable State Transitions,Web,Rapid compact-control changes can interrupt an in-flight transition,Cancel or replace prior motion; set the final semantic state directly and handle cancellation cleanup,Depend on animationend or transitionend for required state correctness,previous?.cancel(); setSelected(next),Enable the chip only inside transitionend,High

package/skills/frontend/design/ui-ux-pro-max/references/pro-rules.md

@@ -0,0 +1,117 @@
+# Common Rules for Professional UI + Pre-Delivery Checklist
+
+Load this file before final delivery of native/mobile app UI (iOS/Android/React Native/Flutter), or when the user reports the UI "doesn't look professional" and the cause isn't obvious from the priority table in SKILL.md.
+
+**Scope notice:** everything below targets native/mobile app UI. For web/desktop interaction patterns, use `references/quick-reference.md` (stack-agnostic) instead — these tables assume touch targets, safe areas, and platform gesture conventions that don't apply 1:1 to desktop web.
+
+These are frequently overlooked issues that make UI look unprofessional.
+
+## Icons & Visual Elements
+
+| Rule | Standard | Avoid | Why It Matters |
+|------|----------|--------|----------------|
+| **No Emoji as Structural Icons** | Use vector-based icons (e.g., Lucide, react-native-vector-icons, @expo/vector-icons). | Using emojis (🎨 🚀 ⚙️) for navigation, settings, or system controls. | Emojis are font-dependent, inconsistent across platforms, and cannot be controlled via design tokens. |
+| **Vector-Only Assets** | Use SVG or platform vector icons that scale cleanly and support theming. | Raster PNG icons that blur or pixelate. | Ensures scalability, crisp rendering, and dark/light mode adaptability. |
+| **Contextual Semantics** | Choose semantics from use, not glyph: hide decorative icons beside visible text from the accessibility tree; give meaningful standalone icons a text alternative; give icon controls an accessible name and expose selected/pressed/expanded state when applicable. | Treating one icon name as permanently decorative, meaningful, or interactive. | The same glyph can serve different purposes in different components. |
+| **Stable Interaction States** | Use color, opacity, or elevation transitions for press states without changing layout bounds. | Layout-shifting transforms that move surrounding content or trigger visual jitter. | Prevents unstable interactions and preserves smooth motion/perceived quality on mobile. |
+| **Correct Brand Logos** | Use official brand assets and follow their usage guidelines (spacing, color, clear space). | Guessing logo paths, recoloring unofficially, or modifying proportions. | Prevents brand misuse and ensures legal/platform compliance. |
+| **Consistent Icon Sizing** | Define icon sizes as design tokens (e.g., icon-sm, icon-md = 24pt, icon-lg). | Mixing arbitrary values like 20pt / 24pt / 28pt randomly. | Maintains rhythm and visual hierarchy across the interface. |
+| **Stroke Consistency** | Use a consistent stroke width within the same visual layer (e.g., 1.5px or 2px). | Mixing thick and thin stroke styles arbitrarily. | Inconsistent strokes reduce perceived polish and cohesion. |
+| **Filled vs Outline Discipline** | Use one icon style per hierarchy level. | Mixing filled and outline icons at the same hierarchy level. | Maintains semantic clarity and stylistic coherence. |
+| **Touch Target Minimum** | Use at least 44pt on iOS and 48dp on Android; expand the hit area when the visual icon is smaller. | Small icons without expanded tap area, or one unit reused across platforms. | Matches platform-specific target guidance. |
+| **Icon Alignment** | Align icons to text baseline and maintain consistent padding. | Misaligned icons or inconsistent spacing around them. | Prevents subtle visual imbalance that reduces perceived quality. |
+| **Icon Contrast** | Meaningful icons and control boundaries need at least 3:1 against adjacent colors; decorative icons must not carry information. | Low-contrast icons that carry meaning or state. | Applies the non-text contrast role instead of a text-size rule. |
+
+## Interaction (App)
+
+| Rule | Do | Don't |
+|------|----|----- |
+| **Tap feedback** | Provide clear pressed feedback (ripple/opacity/elevation) within 80-150ms | No visual response on tap |
+| **Animation timing** | Use shared tokens chosen for distance, complexity, platform, and user context | One duration/easing copied to every transition |
+| **Accessibility focus** | Ensure screen reader focus order matches visual order and labels are descriptive | Unlabeled controls or confusing focus traversal |
+| **Disabled state clarity** | Use disabled semantics (`disabled`/native disabled props), reduced emphasis, and no tap action | Controls that look tappable but do nothing |
+| **Touch target minimum** | Keep tap areas >=44x44pt (iOS) or >=48x48dp (Android), expand hit area when icon is smaller | Tiny tap targets or icon-only hit areas without padding |
+| **Gesture conflict prevention** | Keep one primary gesture per region and avoid nested tap/drag conflicts | Overlapping gestures causing accidental actions |
+| **Semantic native controls** | Prefer native interactive primitives (`Button`, `Pressable`, platform equivalents) with proper accessibility roles | Generic containers used as primary controls without semantics |
+
+## Light/Dark Mode Contrast
+
+| Rule | Do | Don't |
+|------|----|----- |
+| **Surface readability (light)** | Keep cards/surfaces clearly separated from background with sufficient opacity/elevation | Overly transparent surfaces that blur hierarchy |
+| **Text contrast (light)** | Maintain body text contrast >=4.5:1 against light surfaces | Low-contrast gray body text |
+| **Text contrast (dark)** | Maintain normal text contrast >=4.5:1 on dark surfaces; 3:1 is only for large text or non-text UI | Muted normal text that falls below the text threshold |
+| **Border and divider visibility** | Ensure separators are visible in both themes (not just light mode) | Theme-specific borders disappearing in one mode |
+| **State contrast parity** | Keep pressed/focused/disabled states equally distinguishable in light and dark themes | Defining interaction states for one theme only |
+| **Token-driven theming** | Use semantic color tokens mapped per theme across app surfaces/text/icons | Hardcoded per-screen hex values |
+| **Scrim and modal legibility** | Measure the composed result and use a scrim strong enough to isolate foreground content | Reusing one opacity without checking the actual background |
+
+## Layout & Spacing
+
+| Rule | Do | Don't |
+|------|----|----- |
+| **Safe-area compliance** | Respect top/bottom safe areas for all fixed headers, tab bars, and CTA bars | Placing fixed UI under notch, status bar, or gesture area |
+| **System bar clearance** | Add spacing for status/navigation bars and gesture home indicator | Let tappable content collide with OS chrome |
+| **Consistent content width** | Keep predictable content width per device class (phone/tablet) | Mixing arbitrary widths between screens |
+| **8dp spacing rhythm** | Use a consistent 4/8dp spacing system for padding/gaps/section spacing | Random spacing increments with no rhythm |
+| **Readable text measure** | Keep long-form text readable on large devices (avoid edge-to-edge paragraphs on tablets) | Full-width long text that hurts readability |
+| **Section spacing hierarchy** | Define clear vertical rhythm tiers (e.g., 16/24/32/48) by hierarchy | Similar UI levels with inconsistent spacing |
+| **Adaptive gutters by breakpoint** | Increase horizontal insets on larger widths and in landscape | Same narrow gutter on all device sizes/orientations |
+| **Scroll and fixed element coexistence** | Add bottom/top content insets so lists are not hidden behind fixed bars | Scroll content obscured by sticky headers/footers |
+
+---
+
+## Pre-Delivery Checklist (canonical — the only one)
+
+Before delivering app UI code, verify every item below. Start with the process steps, then the per-area checkboxes.
+
+### Process
+- [ ] Ran only searches relevant to the interface, such as `"keyboard focus modal" --domain ux` for modal keyboard behavior
+- [ ] Reviewed `quick-reference.md` §1–§3 (CRITICAL + HIGH) as a final pass
+- [ ] Tested on 375px (small phone) and in landscape orientation
+- [ ] Verified behavior with **reduced-motion** enabled and **Dynamic Type**/largest system text size
+- [ ] Checked dark mode contrast independently (never assume light-mode values carry over)
+- [ ] Confirmed all touch targets ≥44pt and no content hidden behind safe areas
+
+### Visual Quality
+- [ ] No emojis used as icons (use SVG instead)
+- [ ] All icons come from a consistent icon family and style
+- [ ] Official brand assets are used with correct proportions and clear space
+- [ ] Pressed-state visuals do not shift layout bounds or cause jitter
+- [ ] Semantic theme tokens are used consistently (no ad-hoc per-screen hardcoded colors)
+
+### Interaction
+- [ ] All tappable elements provide clear pressed feedback (ripple/opacity/elevation)
+- [ ] Touch targets meet minimum size (>=44x44pt iOS, >=48x48dp Android)
+- [ ] Micro-interaction timing uses shared, platform-appropriate tokens and remains responsive in context
+- [ ] Disabled states are visually clear and non-interactive
+- [ ] Screen reader focus order matches visual order, and interactive labels are descriptive
+- [ ] Gesture regions avoid nested/conflicting interactions (tap/drag/back-swipe conflicts)
+
+### Light/Dark Mode
+- [ ] Primary text contrast >=4.5:1 in both light and dark mode
+- [ ] Normal primary and secondary text contrast >=4.5:1 in both light and dark mode
+- [ ] Dividers/borders and interaction states are distinguishable in both modes
+- [ ] Modal/drawer scrim is measured against the real background and preserves foreground legibility
+- [ ] Both themes are tested before delivery (not inferred from a single theme)
+
+### Layout
+- [ ] Safe areas are respected for headers, tab bars, and bottom CTA bars
+- [ ] Scroll content is not hidden behind fixed/sticky bars
+- [ ] Verified on small phone, large phone, and tablet (portrait + landscape)
+- [ ] Horizontal insets/gutters adapt correctly by device size and orientation
+- [ ] 4/8dp spacing rhythm is maintained across component, section, and page levels
+- [ ] Long-form text measure remains readable on larger devices (no edge-to-edge paragraphs)
+
+### Accessibility
+- [ ] Decorative icons beside visible text are hidden from the accessibility tree (`aria-hidden="true"` on web or the native equivalent)
+- [ ] Meaningful images/icons without equivalent visible text have a text alternative
+- [ ] Icon controls have an accessible name and announce applicable selected/pressed/expanded state
+- [ ] Form fields have labels, hints, and clear error messages
+- [ ] Color is not the only indicator
+- [ ] Reduced motion and dynamic text size are supported without layout breakage
+- [ ] Sticky UI and overlays do not obscure keyboard focus
+- [ ] Dragging and swipe-only interactions have button/keyboard alternatives
+- [ ] Authentication allows password managers and paste, with a non-cognitive alternative
+- [ ] Auto-rotating content has pause/stop controls and stops on focus or reduced motion
+- [ ] Failed forms retain inline field errors; multi-error forms also focus a linked error summary after submit

package/skills/frontend/design/ui-ux-pro-max/references/quick-reference.md

@@ -0,0 +1,256 @@
+# Quick Reference — Full Rule Set (all 10 categories)
+
+Load this file when doing a UI review/audit pass, or when you need the full checklist for a category beyond the priority table in SKILL.md. Each rule is also present verbatim in `data/ux-guidelines.csv` / `data/app-interface.csv` and is reachable via `--domain ux` / `--domain web` search — this file is a static index for quick scanning without a search round-trip.
+
+## Quick Reference
+
+### 1. Accessibility (CRITICAL)
+
+- `color-contrast` - Minimum 4.5:1 ratio for normal text (large text 3:1); Material Design
+- `focus-states` - Visible focus rings on interactive elements (2–4px; Apple HIG, MD)
+- `alt-text` - Descriptive alt text for meaningful images
+- `aria-labels` - aria-label for icon-only buttons; accessibilityLabel in native (Apple HIG)
+- `icon-context` - Semantics depend on use: decorative icons beside visible text are hidden from the accessibility tree; meaningful icons need a text alternative; icon controls need an accessible name and applicable state
+- `keyboard-nav` - Tab order matches visual order; full keyboard support (Apple HIG)
+- `form-labels` - Use label with for attribute
+- `skip-links` - Skip to main content for keyboard users
+- `heading-hierarchy` - Sequential h1→h6, no level skip
+- `color-not-only` - Don't convey info by color alone (add icon/text)
+- `dynamic-type` - Support system text scaling; avoid truncation as text grows (Apple Dynamic Type, MD)
+- `reduced-motion` - Respect prefers-reduced-motion; reduce/disable animations when requested (Apple Reduced Motion API, MD)
+- `voiceover-sr` - Meaningful accessibilityLabel/accessibilityHint; logical reading order for VoiceOver/screen readers (Apple HIG, MD)
+- `escape-routes` - Provide cancel/back in modals and multi-step flows (Apple HIG)
+- `keyboard-shortcuts` - Preserve system and a11y shortcuts; offer keyboard alternatives for drag-and-drop (Apple HIG)
+- `focus-not-obscured` - Sticky UI, overlays, and banners must not hide the keyboard-focused control (WCAG 2.2 AA)
+- `focus-not-obscured-enhanced` - Keep the entire focused component visible (WCAG 2.2 AAA)
+- `focus-appearance` - Verify focus indicator area and 3:1 state contrast; visible focus alone is not enough (WCAG 2.2 AAA)
+- `dragging-alternative` - Every author-controlled drag action needs a single-pointer and keyboard alternative (WCAG 2.2 AA)
+- `web-target-size` - Web pointer targets need 24×24 CSS px or a documented exception; do not substitute native units (WCAG 2.2 AA)
+- `consistent-help` - Repeated help mechanisms stay in the same relative order across a page set (WCAG 2.2 A)
+- `redundant-entry` - Reuse information already supplied in the same process unless re-entry is essential (WCAG 2.2 A)
+- `accessible-authentication` - Allow password managers and paste; provide a non-cognitive authentication path (WCAG 2.2 Minimum, AA). The Enhanced AAA criterion is not represented in the dataset
+- `auto-rotation-controls` - Carousels and moving content need pause/stop controls and must stop on focus or reduced motion (WAI)
+- `contextual-live-badge-updates` - Announce a changed count/status as a complete contextual phrase without moving focus; use one appropriate live/status region and atomic updates only when needed
+
+### 2. Touch & Interaction (CRITICAL)
+
+- `touch-target-size` - Min 44×44pt (Apple) / 48×48dp (Material); extend hit area beyond visual bounds if needed
+- `touch-spacing` - Minimum 8px/8dp gap between touch targets (Apple HIG, MD)
+- `hover-vs-tap` - Use click/tap for primary interactions; don't rely on hover alone
+- `loading-buttons` - Disable button during async operations; show spinner or progress
+- `error-feedback` - Clear error messages near problem
+- `cursor-pointer` - Add cursor-pointer to clickable elements (Web)
+- `gesture-conflicts` - Avoid horizontal swipe on main content; prefer vertical scroll
+- `tap-delay` - Use touch-action: manipulation to reduce 300ms delay (Web)
+- `standard-gestures` - Use platform standard gestures consistently; don't redefine (e.g. swipe-back, pinch-zoom) (Apple HIG)
+- `system-gestures` - Don't block system gestures (Control Center, back swipe, etc.) (Apple HIG)
+- `press-feedback` - Visual feedback on press (ripple/highlight; MD state layers)
+- `haptic-feedback` - Use haptic for confirmations and important actions; avoid overuse (Apple HIG)
+- `gesture-alternative` - Don't rely on gesture-only interactions; always provide visible controls for critical actions
+- `safe-area-awareness` - Keep primary touch targets away from notch, Dynamic Island, gesture bar and screen edges
+- `no-precision-required` - Avoid requiring pixel-perfect taps on small icons or thin edges
+- `swipe-clarity` - Swipe actions must show clear affordance or hint (chevron, label, tutorial)
+- `drag-threshold` - Use a movement threshold before starting drag to avoid accidental drags
+
+### 3. Performance (HIGH)
+
+- `image-optimization` - Use WebP/AVIF, responsive images (srcset/sizes), lazy load non-critical assets
+- `image-dimension` - Declare width/height or use aspect-ratio to prevent layout shift (Core Web Vitals: CLS)
+- `font-loading` - Use font-display: swap/optional to avoid invisible text (FOIT); reserve space to reduce layout shift (MD)
+- `font-preload` - Preload only critical fonts; avoid overusing preload on every variant
+- `critical-css` - Prioritize above-the-fold CSS (inline critical CSS or early-loaded stylesheet)
+- `lazy-loading` - Lazy load non-hero components via dynamic import / route-level splitting
+- `bundle-splitting` - Split code by route/feature (React Suspense / Next.js dynamic) to reduce initial load and TTI
+- `third-party-scripts` - Load third-party scripts async/defer; audit and remove unnecessary ones (MD)
+- `reduce-reflows` - Avoid frequent layout reads/writes; batch DOM reads then writes
+- `content-jumping` - Reserve space for async content to avoid layout jumps (Core Web Vitals: CLS)
+- `lazy-load-below-fold` - Use loading="lazy" for below-the-fold images and heavy media
+- `virtualize-lists` - Virtualize lists with 50+ items to improve memory efficiency and scroll performance
+- `main-thread-budget` - Keep per-frame work under ~16ms for 60fps; move heavy tasks off main thread (HIG, MD)
+- `progressive-loading` - Use skeleton screens / shimmer instead of long blocking spinners for >1s operations (Apple HIG)
+- `input-latency` - Keep input latency under ~100ms for taps/scrolls (Material responsiveness standard)
+- `tap-feedback-speed` - Provide visual feedback within 100ms of tap (Apple HIG)
+- `debounce-throttle` - Use debounce/throttle for high-frequency events (scroll, resize, input)
+- `offline-support` - Provide offline state messaging and basic fallback (PWA / mobile)
+- `network-fallback` - Offer degraded modes for slow networks (lower-res images, fewer animations)
+
+### 4. Style Selection (HIGH)
+
+- `style-match` - Match style to product type (use `--design-system` for recommendations)
+- `consistency` - Use same style across all pages
+- `no-emoji-icons` - Use SVG icons (Heroicons, Lucide), not emojis
+- `color-palette-from-product` - Choose palette from product/industry (search `--domain color`)
+- `effects-match-style` - Shadows, blur, radius aligned with chosen style (glass / flat / clay etc.)
+- `platform-adaptive` - Respect platform idioms (iOS HIG vs Material): navigation, controls, typography, motion
+- `state-clarity` - Make hover/pressed/disabled states visually distinct while staying on-style (Material state layers)
+- `elevation-consistent` - Use a consistent elevation/shadow scale for cards, sheets, modals; avoid random shadow values
+- `dark-mode-pairing` - Design light/dark variants together to keep brand, contrast, and style consistent
+- `icon-style-consistent` - Use one icon set/visual language (stroke width, corner radius) across the product
+- `system-controls` - Prefer native/system controls over fully custom ones; only customize when branding requires it (Apple HIG)
+- `blur-purpose` - Use blur to indicate background dismissal (modals, sheets), not as decoration (Apple HIG)
+- `primary-action` - Each screen should have only one primary CTA; secondary actions visually subordinate (Apple HIG)
+
+### 5. Layout & Responsive (HIGH)
+
+- `viewport-meta` - width=device-width initial-scale=1 (never disable zoom)
+- `mobile-first` - Design mobile-first, then scale up to tablet and desktop
+- `breakpoint-consistency` - Use systematic breakpoints (e.g. 375 / 768 / 1024 / 1440)
+- `readable-font-size` - Minimum 16px body text on mobile (avoids iOS auto-zoom)
+- `line-length-control` - Mobile 35–60 chars per line; desktop 60–75 chars
+- `horizontal-scroll` - No horizontal scroll on mobile; ensure content fits viewport width
+- `spacing-scale` - Use 4pt/8dp incremental spacing system (Material Design)
+- `touch-density` - Keep component spacing comfortable for touch: not cramped, not causing mis-taps
+- `container-width` - Consistent max-width on desktop (max-w-6xl / 7xl)
+- `z-index-management` - Define layered z-index scale (e.g. 0 / 10 / 20 / 40 / 100 / 1000)
+- `fixed-element-offset` - Fixed navbar/bottom bar must reserve safe padding for underlying content
+- `scroll-behavior` - Avoid nested scroll regions that interfere with the main scroll experience
+- `viewport-units` - Prefer min-h-dvh over 100vh on mobile
+- `orientation-support` - Keep layout readable and operable in landscape mode
+- `content-priority` - Show core content first on mobile; fold or hide secondary content
+- `visual-hierarchy` - Establish hierarchy via size, spacing, contrast — not color alone
+- `compact-label-overflow` - Choose badge, status tag, filter chip, or removable value from its semantics; keep essential labels available and disclose unavoidable truncation to pointer and keyboard users
+- `chip-collection-reflow` - Wrap the collection before shrinking labels; make a `+n` overflow summary an operable disclosure instead of hiding values
+
+### 6. Typography & Color (MEDIUM)
+
+- `line-height` - Use 1.5-1.75 for body text
+- `line-length` - Limit to 65-75 characters per line
+- `font-pairing` - Match heading/body font personalities
+- `font-scale` - Consistent type scale (e.g. 12 14 16 18 24 32)
+- `contrast-readability` - Darker text on light backgrounds (e.g. slate-900 on white)
+- `text-styles-system` - Use platform type system: iOS 11 Dynamic Type styles / Material 5 type roles (display, headline, title, body, label) (HIG, MD)
+- `weight-hierarchy` - Use font-weight to reinforce hierarchy: Bold headings (600–700), Regular body (400), Medium labels (500) (MD)
+- `color-semantic` - Define semantic color tokens (primary, secondary, error, surface, on-surface) not raw hex in components (Material color system)
+- `color-dark-mode` - Dark mode uses desaturated / lighter tonal variants, not inverted colors; test contrast separately (HIG, MD)
+- `color-accessible-pairs` - Foreground/background pairs must meet 4.5:1 (AA) or 7:1 (AAA); use tools to verify (WCAG, MD)
+- `color-not-decorative-only` - Functional color (error red, success green) must include icon/text; avoid color-only meaning (HIG, MD)
+- `truncation-strategy` - Prefer wrapping over truncation; when truncating use ellipsis and provide full text via tooltip/expand (Apple HIG)
+- `letter-spacing` - Respect default letter-spacing per platform; avoid tight tracking on body text (HIG, MD)
+- `number-tabular` - Use tabular/monospaced figures for data columns, prices, and timers to prevent layout shift
+- `whitespace-balance` - Use whitespace intentionally to group related items and separate sections; avoid visual clutter (Apple HIG)
+- `heading-line-balance` - Use balanced wrapping on short headings as a progressive, user-agent-controlled heuristic; keep natural wrapping readable and never force final words together with blanket nonbreaking spaces
+- `long-token-wrapping` - Let URLs, IDs, and user content reflow with `overflow-wrap: anywhere` and a shrinkable flex/grid text child; do not apply `word-break: break-all` to normal prose
+
+### 7. Animation (MEDIUM)
+
+- `duration-timing` - Choose shared motion tokens by distance, complexity, platform, and user context; test that feedback remains responsive instead of treating one duration range as universal
+- `transform-performance` - Use transform/opacity only; avoid animating width/height/top/left
+- `loading-states` - Match feedback to the expected wait and platform/component guidance; avoid both flashing indicators for near-instant work and unexplained long waits
+- `excessive-motion` - Animate 1-2 key elements per view max
+- `easing` - Use deceleration when arriving, acceleration when leaving, and linear motion for genuinely constant-rate progress or rotation
+- `motion-meaning` - Every animation must express a cause-effect relationship, not just be decorative (Apple HIG)
+- `state-transition` - State changes (hover / active / expanded / collapsed / modal) should animate smoothly, not snap
+- `continuity` - Page/screen transitions should maintain spatial continuity (shared element, directional slide) (Apple HIG)
+- `parallax-subtle` - Use parallax sparingly; must respect reduced-motion and not cause disorientation (Apple HIG)
+- `spring-physics` - Prefer spring/physics-based curves over linear or cubic-bezier for natural feel (Apple HIG fluid animations)
+- `exit-faster-than-enter` - Exit animations shorter than enter (~60–70% of enter duration) to feel responsive (MD motion)
+- `stagger-sequence` - Stagger list/grid item entrance by 30–50ms per item; avoid all-at-once or too-slow reveals (MD)
+- `shared-element-transition` - Use shared element / hero transitions for visual continuity between screens (MD, HIG)
+- `interruptible` - Animations must be interruptible; user tap/gesture cancels in-progress animation immediately (Apple HIG)
+- `no-blocking-animation` - Never block user input during an animation; UI must stay interactive (Apple HIG)
+- `fade-crossfade` - Use crossfade for content replacement within the same container (MD)
+- `scale-feedback` - Subtle scale (0.95–1.05) on press for tappable cards/buttons; restore on release (HIG, MD)
+- `gesture-feedback` - Drag, swipe, and pinch must provide real-time visual response tracking the finger (MD Motion)
+- `hierarchy-motion` - Use translate/scale direction to express hierarchy: enter from below = deeper, exit upward = back (MD)
+- `motion-consistency` - Unify duration/easing tokens globally; all animations share the same rhythm and feel
+- `opacity-threshold` - Fading elements should not linger below opacity 0.2; either fade fully or remain visible
+- `modal-motion` - Modals/sheets should animate from their trigger source (scale+fade or slide-in) for spatial context (HIG, MD)
+- `navigation-direction` - Forward navigation animates left/up; backward animates right/down — keep direction logically consistent (HIG)
+- `layout-shift-avoid` - Animations must not cause layout reflow or CLS; use transform for position changes
+- `cancellable-state-transitions` - Rapid state changes must cancel/replace prior micro-interactions safely, set the new final state explicitly, and never depend on an animation-end event for correctness
+
+### 8. Forms & Feedback (MEDIUM)
+
+- `input-labels` - Visible label per input (not placeholder-only)
+- `error-placement` - Show a specific error below the related field and connect it with aria-describedby
+- `submit-feedback` - Loading then success/error state on submit
+- `required-indicators` - Mark required fields (e.g. asterisk)
+- `empty-states` - Helpful message and action when no content
+- `toast-dismiss` - Auto-dismiss toasts in 3-5s
+- `confirmation-dialogs` - Confirm before destructive actions
+- `input-helper-text` - Provide persistent helper text below complex inputs, not just placeholder (Material Design)
+- `disabled-states` - Disabled elements use reduced opacity (0.38–0.5) + cursor change + semantic attribute (MD)
+- `progressive-disclosure` - Reveal complex options progressively; don't overwhelm users upfront (Apple HIG)
+- `inline-validation` - Validate on blur (not keystroke); show error only after user finishes input (MD)
+- `input-type-keyboard` - Use semantic input types (email, tel, number) to trigger the correct mobile keyboard (HIG, MD)
+- `password-toggle` - Provide show/hide toggle for password fields (MD)
+- `autofill-support` - Use autocomplete / textContentType attributes so the system can autofill (HIG, MD)
+- `undo-support` - Allow undo for destructive or bulk actions (e.g. "Undo delete" toast) (Apple HIG)
+- `success-feedback` - Confirm completed actions with brief visual feedback (checkmark, toast, color flash) (MD)
+- `error-recovery` - Error messages must include a clear recovery path (retry, edit, help link) (HIG, MD)
+- `multi-step-progress` - Multi-step flows show step indicator or progress bar; allow back navigation (MD)
+- `form-autosave` - Long forms should auto-save drafts to prevent data loss on accidental dismissal (Apple HIG)
+- `sheet-dismiss-confirm` - Confirm before dismissing a sheet/modal with unsaved changes (Apple HIG)
+- `error-clarity` - Error messages must state cause + how to fix (not just "Invalid input") (HIG, MD)
+- `field-grouping` - Group related fields logically (fieldset/legend or visual grouping) (MD)
+- `read-only-distinction` - Read-only state should be visually and semantically different from disabled (MD)
+- `focus-management` - After failed submission with multiple errors, focus the error summary; without a summary, focus the first invalid field
+- `error-summary` - Put a focusable summary at the top after failed submit, link each item to its invalid field, and retain inline field errors
+- `touch-friendly-input` - Mobile input height ≥44px to meet touch target requirements (Apple HIG)
+- `destructive-emphasis` - Destructive actions use semantic danger color (red) and are visually separated from primary actions (HIG, MD)
+- `toast-accessibility` - Toasts must not steal focus; use aria-live="polite" for screen reader announcement (WCAG)
+- `aria-live-errors` - Form errors use aria-live region or role="alert" to notify screen readers (WCAG)
+- `contrast-feedback` - Error and success state colors must meet 4.5:1 contrast ratio (WCAG, MD)
+- `timeout-feedback` - Request timeout must show clear feedback with retry option (MD)
+
+### 9. Navigation Patterns (HIGH)
+
+- `bottom-nav-limit` - Bottom navigation max 5 items; use labels with icons (Material Design)
+- `drawer-usage` - Use drawer/sidebar for secondary navigation, not primary actions (Material Design)
+- `back-behavior` - Back navigation must be predictable and consistent; preserve scroll/state (Apple HIG, MD)
+- `deep-linking` - All key screens must be reachable via deep link / URL for sharing and notifications (Apple HIG, MD)
+- `tab-bar-ios` - iOS: use bottom Tab Bar for top-level navigation (Apple HIG)
+- `top-app-bar-android` - Android: use Top App Bar with navigation icon for primary structure (Material Design)
+- `nav-label-icon` - Navigation items must have both icon and text label; icon-only nav harms discoverability (MD)
+- `nav-state-active` - Current location must be visually highlighted (color, weight, indicator) in navigation (HIG, MD)
+- `nav-hierarchy` - Primary nav (tabs/bottom bar) vs secondary nav (drawer/settings) must be clearly separated (MD)
+- `modal-escape` - Modals and sheets must offer a clear close/dismiss affordance; swipe-down to dismiss on mobile (Apple HIG)
+- `search-accessible` - Search must be easily reachable (top bar or tab); provide recent/suggested queries (MD)
+- `breadcrumb-web` - Web: use breadcrumbs for 3+ level deep hierarchies to aid orientation (MD)
+- `state-preservation` - Navigating back must restore previous scroll position, filter state, and input (HIG, MD)
+- `gesture-nav-support` - Support system gesture navigation (iOS swipe-back, Android predictive back) without conflict (HIG, MD)
+- `tab-badge` - Use badges on nav items sparingly to indicate unread/pending; clear after user visits (HIG, MD)
+- `overflow-menu` - When actions exceed available space, use overflow/more menu instead of cramming (MD)
+- `bottom-nav-top-level` - Bottom nav is for top-level screens only; never nest sub-navigation inside it (MD)
+- `adaptive-navigation` - Large screens (≥1024px) prefer sidebar; small screens use bottom/top nav (Material Adaptive)
+- `back-stack-integrity` - Never silently reset the navigation stack or unexpectedly jump to home (HIG, MD)
+- `navigation-consistency` - Navigation placement must stay the same across all pages; don't change by page type
+- `avoid-mixed-patterns` - Don't mix Tab + Sidebar + Bottom Nav at the same hierarchy level
+- `modal-vs-navigation` - Modals must not be used for primary navigation flows; they break the user's path (HIG)
+- `focus-on-route-change` - After page transition, move focus to main content region for screen reader users (WCAG)
+- `persistent-nav` - Core navigation must remain reachable from deep pages; don't hide it entirely in sub-flows (HIG, MD)
+- `destructive-nav-separation` - Dangerous actions (delete account, logout) must be visually and spatially separated from normal nav items (HIG, MD)
+- `empty-nav-state` - When a nav destination is unavailable, explain why instead of silently hiding it (MD)
+
+### 10. Charts & Data (LOW)
+
+- `chart-type` - Match chart type to data type (trend → line, comparison → bar, proportion → pie/donut)
+- `color-guidance` - Use accessible color palettes; avoid red/green only pairs for colorblind users (WCAG, MD)
+- `data-table` - Provide table alternative for accessibility; charts alone are not screen-reader friendly (WCAG)
+- `pattern-texture` - Supplement color with patterns, textures, or shapes so data is distinguishable without color (WCAG, MD)
+- `legend-visible` - Always show legend; position near the chart, not detached below a scroll fold (MD)
+- `tooltip-on-interact` - Provide tooltips/data labels on hover (Web) or tap (mobile) showing exact values (HIG, MD)
+- `axis-labels` - Label axes with units and readable scale; avoid truncated or rotated labels on mobile
+- `responsive-chart` - Charts must reflow or simplify on small screens (e.g. horizontal bar instead of vertical, fewer ticks)
+- `empty-data-state` - Show meaningful empty state when no data exists ("No data yet" + guidance), not a blank chart (MD)
+- `loading-chart` - Use skeleton or shimmer placeholder while chart data loads; don't show an empty axis frame
+- `animation-optional` - Chart entrance animations must respect prefers-reduced-motion; data should be readable immediately (HIG)
+- `large-dataset` - For 1000+ data points, aggregate or sample; provide drill-down for detail instead of rendering all (MD)
+- `number-formatting` - Use locale-aware formatting for numbers, dates, currencies on axes and labels (HIG, MD)
+- `touch-target-chart` - Interactive chart elements (points, segments) must have ≥44pt tap area or expand on touch (Apple HIG)
+- `no-pie-overuse` - Avoid pie/donut for >5 categories; switch to bar chart for clarity
+- `contrast-data` - Data lines/bars vs background ≥3:1; data text labels ≥4.5:1 (WCAG)
+- `legend-interactive` - Legends should be clickable to toggle series visibility (MD)
+- `direct-labeling` - For small datasets, label values directly on the chart to reduce eye travel
+- `tooltip-keyboard` - Tooltip content must be keyboard-reachable and not rely on hover alone (WCAG)
+- `sortable-table` - Data tables must support sorting with aria-sort indicating current sort state (WCAG)
+- `axis-readability` - Axis ticks must not be cramped; maintain readable spacing, auto-skip on small screens
+- `data-density` - Limit information density per chart to avoid cognitive overload; split into multiple charts if needed
+- `trend-emphasis` - Emphasize data trends over decoration; avoid heavy gradients/shadows that obscure the data
+- `gridline-subtle` - Grid lines should be low-contrast (e.g. gray-200) so they don't compete with data
+- `focusable-elements` - Interactive chart elements (points, bars, slices) must be keyboard-navigable (WCAG)
+- `screen-reader-summary` - Provide a text summary or aria-label describing the chart's key insight for screen readers (WCAG)
+- `error-state-chart` - Data load failure must show error message with retry action, not a broken/empty chart
+- `export-option` - For data-heavy products, offer CSV/image export of chart data
+- `drill-down-consistency` - Drill-down interactions must maintain a clear back-path and hierarchy breadcrumb
+- `time-scale-clarity` - Time series charts must clearly label time granularity (day/week/month) and allow switching