ui-ux-pro-max-skill/.qoder/rules/ux-guideline.md

trigger

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		for everything	Medium
43	Accessibility	Form Labels	All	Inputs must have associated labels	Use label with for attribute or wrap input	Placeholder-only inputs		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
45	Accessibility	Skip Links	Web	Allow keyboard users to skip navigation	Provide skip to main content link	No skip link on nav-heavy pages	Skip to main content link	100 tabs to reach content	Medium
46	Performance	Image Optimization	All	Large images slow page load	Use appropriate size and format (WebP)	Unoptimized full-size images	srcset with multiple sizes	4000px image for 400px display	High
47	Performance	Lazy Loading	All	Load content as needed	Lazy load below-fold images and content	Load everything upfront	loading='lazy'	All images eager load	Medium
48	Performance	Code Splitting	Web	Large bundles slow initial load	Split code by route/feature	Single large bundle	dynamic import()	All code in main bundle	Medium
49	Performance	Caching	Web	Repeat visits should be fast	Set appropriate cache headers	No caching strategy	Cache-Control headers	Every request hits server	Medium
50	Performance	Font Loading	Web	Web fonts can block rendering	Use font-display swap or optional	Invisible text during font load	font-display: swap	FOIT (Flash of Invisible Text)	Medium
51	Performance	Third Party Scripts	Web	External scripts can block rendering	Load non-critical scripts async/defer	Synchronous third-party scripts	async or defer attribute