--- trigger: always_on --- | No | Category | Issue | Platform | Description | Do | Don't | Code Example Good | Code Example Bad | Severity | |----|----------|-------|----------|-------------|----|-------|-------------------|------------------|----------| | 1 | Navigation | Smooth Scroll | Web | Anchor links should scroll smoothly to target section | Use scroll-behavior: smooth on html element | Jump directly without transition | html { scroll-behavior: smooth; } | without CSS | High | | 2 | Navigation | Sticky Navigation | Web | Fixed nav should not obscure content | Add padding-top to body equal to nav height | Let nav overlap first section content | pt-20 (if nav is h-20) | No padding compensation | Medium | | 3 | Navigation | Active State | All | Current page/section should be visually indicated | Highlight active nav item with color/underline | No visual feedback on current location | text-primary border-b-2 | All links same style | Medium | | 4 | Navigation | Back Button | Mobile | Users expect back to work predictably | Preserve navigation history properly | Break browser/app back button behavior | history.pushState() | location.replace() | High | | 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 | | 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 | | 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 | | 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 | | 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 | | 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 | | 32 | Interaction | Loading Buttons | All | Prevent double submission during async actions | Disable button and show loading state | Allow multiple clicks during processing | disabled={loading} spinner | Button clickable while loading | High | | 33 | Interaction | Error Feedback | All | Users need to know when something fails | Show clear error messages near problem | Silent failures with no feedback | Red border + error message | No indication of error | High | | 34 | Interaction | Success Feedback | All | Confirm successful actions to users | Show success message or visual change | No confirmation of completed action | Toast notification or checkmark | Action completes silently | Medium | | 35 | Interaction | Confirmation Dialogs | All | Prevent accidental destructive actions | Confirm before delete/irreversible actions | Delete without confirmation | Are you sure modal | Direct delete on click | High | | 36 | Accessibility | Color Contrast | All | Text must be readable against background | Minimum 4.5:1 ratio for normal text | Low contrast text | #333 on white (7:1) | #999 on white (2.8:1) | High | | 37 | Accessibility | Color Only | All | Don't convey information by color alone | Use icons/text in addition to color | Red/green only for error/success | Red text + error icon | Red border only for error | High | | 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' | | 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 | | 42 | Accessibility | Screen Reader | All | Content should make sense when read aloud | Use semantic HTML and ARIA properly | Div soup with no semantics |