UX rules · 129

Anchor links should scroll smoothly to target section

Do Use scroll-behavior: smooth on html element

Don't Jump directly without transition

✓ html { scroll-behavior: smooth; }

✗ <a href='#section'> without CSS

Fixed nav should not obscure content

Do Add padding-top to body equal to nav height

Don't Let nav overlap first section content

✓ pt-20 (if nav is h-20)

✗ No padding compensation

Current page/section should be visually indicated

Do Highlight active nav item with color/underline

Don't No visual feedback on current location

✓ text-primary border-b-2

✗ All links same style

Users expect back to work predictably

Do Preserve navigation history properly

Don't Break browser/app back button behavior

✓ history.pushState()

✗ location.replace()

URLs should reflect current state for sharing

Do Update URL on state/view changes

Don't Static URLs for dynamic content

✓ Use query params or hash

✗ Single URL for all states

Show user location in site hierarchy

Do Use for sites with 3+ levels of depth

Don't Use for flat single-level sites

✓ Home > Category > Product

✗ Only on deep nested pages

Too many animations cause distraction and motion sickness

Do Animate 1-2 key elements per view maximum

Don't Animate everything that moves

✓ Single hero animation

✗ animate-bounce on 5+ elements

Animations should feel responsive not sluggish

Do Use 150-300ms for micro-interactions

Don't Use animations longer than 500ms for UI

✓ transition-all duration-200

✗ duration-1000

Respect user's motion preferences

Do Check prefers-reduced-motion media query

Don't Ignore accessibility motion settings

✓ @media (prefers-reduced-motion: reduce)

✗ No motion query check

Show feedback during async operations

Do Use skeleton screens or spinners

Don't Leave UI frozen with no feedback

✓ animate-pulse skeleton

✗ Blank screen while loading

Hover effects don't work on touch devices

Do Use click/tap for primary interactions

Don't Rely only on hover for important actions

✓ onClick handler

✗ onMouseEnter only

Infinite animations are distracting

Do Use for loading indicators only

Don't Use for decorative elements

✓ animate-spin on loader

✗ animate-bounce on icons

Some CSS properties trigger expensive repaints

Do Use transform and opacity for animations

Don't Animate width/height/top/left properties

✓ transform: translateY()

✗ top: 10px animation

Linear motion feels robotic

Do Use ease-out for entering ease-in for exiting

Don't Use linear for UI transitions

✓ ease-out

✗ linear

Stacking context conflicts cause hidden elements

Do Define z-index scale system (10 20 30 50)

Don't Use arbitrary large z-index values

✓ z-10 z-20 z-50

✗ z-[9999]

Hidden overflow can clip important content

Do Test all content fits within containers

Don't Blindly apply overflow-hidden

✓ overflow-auto with scroll

✗ overflow-hidden truncating content

Fixed elements can overlap or be inaccessible

Do Account for safe areas and other fixed elements

Don't Stack multiple fixed elements carelessly

✓ Fixed nav + fixed bottom with gap

✗ Multiple overlapping fixed elements

New stacking contexts reset z-index

Do Understand what creates new stacking context

Don't Expect z-index to work across contexts

✓ Parent with z-index isolates children

✗ z-index: 9999 not working

Layout shift when content loads is jarring

Do Reserve space for async content

Don't Let images/content push layout around

✓ aspect-ratio or fixed height

✗ No dimensions on images

100vh can be problematic on mobile browsers

Do Use dvh or account for mobile browser chrome

Don't Use 100vh for full-screen mobile layouts

✓ min-h-dvh or min-h-screen

✗ h-screen on mobile

Content too wide is hard to read

Do Limit max-width for text content (65-75ch)

Don't Let text span full viewport width

✓ max-w-prose or max-w-3xl

✗ Full width paragraphs

Small buttons are hard to tap accurately

Do Minimum 44x44px touch targets

Don't Tiny clickable areas

✓ min-h-[44px] min-w-[44px]

✗ w-6 h-6 buttons

Adjacent touch targets need adequate spacing

Do Minimum 8px gap between touch targets

Don't Tightly packed clickable elements

✓ gap-2 between buttons

✗ gap-0 or gap-1

Custom gestures can conflict with system

Do Avoid horizontal swipe on main content

Don't Override system gestures

✓ Vertical scroll primary

✗ Horizontal swipe carousel only

300ms tap delay feels laggy

Do Use touch-action CSS or fastclick

Don't Default mobile tap handling

✓ touch-action: manipulation

✗ No touch optimization

Accidental refresh is frustrating

Do Disable where not needed

Don't Enable by default everywhere

✓ overscroll-behavior: contain

✗ Default overscroll

Tactile feedback improves interaction feel

Do Use for confirmations and important actions

Don't Overuse vibration feedback

✓ navigator.vibrate(10)

✗ Vibrate on every tap

Keyboard users need visible focus indicators

Do Use visible focus rings on interactive elements

Don't Remove focus outline without replacement

✓ focus:ring-2 focus:ring-blue-500

✗ outline-none without alternative

Visual feedback on interactive elements

Do Change cursor and add subtle visual change

Don't No hover feedback on clickable elements

✓ hover:bg-gray-100 cursor-pointer

✗ No hover style

Show immediate feedback on press/click

Do Add pressed/active state visual change

Don't No feedback during interaction

✓ active:scale-95

✗ No active state

Clearly indicate non-interactive elements

Do Reduce opacity and change cursor

Don't Confuse disabled with normal state

✓ opacity-50 cursor-not-allowed

✗ Same style as enabled

Prevent double submission during async actions

Do Disable button and show loading state

Don't Allow multiple clicks during processing

✓ disabled={loading} spinner

✗ Button clickable while loading

Users need to know when something fails

Do Show clear error messages near problem

Don't Silent failures with no feedback

✓ Red border + error message

✗ No indication of error

Confirm successful actions to users

Do Show success message or visual change

Don't No confirmation of completed action

✓ Toast notification or checkmark

✗ Action completes silently

Prevent accidental destructive actions

Do Confirm before delete/irreversible actions

Don't Delete without confirmation

✓ Are you sure modal

✗ Direct delete on click

Text must be readable against background

Do Minimum 4.5:1 ratio for normal text

Don't Low contrast text

✓ #333 on white (7:1)

✗ #999 on white (2.8:1)

Don't convey information by color alone

Do Use icons/text in addition to color

Don't Red/green only for error/success

✓ Red text + error icon

✗ Red border only for error

Images need text alternatives

image failed to load

image failed to load

Do Descriptive alt text for meaningful images

Don't Empty or missing alt attributes

✓ alt='Dog playing in park'

✗ alt='' for content images

Screen readers use headings for navigation

Do Use sequential heading levels h1-h6

Don't Skip heading levels or misuse for styling

✓ h1 then h2 then h3

✗ h1 then h4

Interactive elements need accessible names

Do Add aria-label for icon-only buttons

Don't Icon buttons without labels

✓ aria-label='Close menu'

✗ <button><Icon/></button>

All functionality accessible via keyboard

Do Tab order matches visual order

Don't Keyboard traps or illogical tab order

✓ tabIndex for custom order

✗ Unreachable elements

Content should make sense when read aloud

Do Use semantic HTML and ARIA properly

Don't Div soup with no semantics

✓ <nav> <main> <article>

✗ <div> for everything

Inputs must have associated labels

Do Use label with for attribute or wrap input

Don't Placeholder-only inputs

✓ <label for='email'>

✗ placeholder='Email' only

Error messages must be announced

Do Use aria-live or role=alert for errors

Don't Visual-only error indication

✓ role='alert'

✗ Red border only

Allow keyboard users to skip navigation

Do Provide skip to main content link

Don't No skip link on nav-heavy pages

✓ Skip to main content link

✗ 100 tabs to reach content

Large images slow page load

Do Use appropriate size and format (WebP)

Don't Unoptimized full-size images

✓ srcset with multiple sizes

✗ 4000px image for 400px display

Load content as needed

Do Lazy load below-fold images and content

Don't Load everything upfront

✓ loading='lazy'

✗ All images eager load

Large bundles slow initial load

Do Split code by route/feature

Don't Single large bundle

✓ dynamic import()

✗ All code in main bundle

Repeat visits should be fast

Do Set appropriate cache headers

Don't No caching strategy

✓ Cache-Control headers

✗ Every request hits server

Web fonts can block rendering

Do Use font-display swap or optional

Don't Invisible text during font load

✓ font-display: swap

✗ FOIT (Flash of Invisible Text)

External scripts can block rendering

Do Load non-critical scripts async/defer

Don't Synchronous third-party scripts

✓ async or defer attribute

✗ <script src='...'> in head

Large JavaScript slows interaction

Do Monitor and minimize bundle size

Don't Ignore bundle size growth

✓ Bundle analyzer

✗ No size monitoring

CSS/JS can block first paint

Do Inline critical CSS defer non-critical

Don't Large blocking CSS files

✓ Critical CSS inline

✗ All CSS in head

Every input needs a visible label

Do Always show label above or beside input

Don't Placeholder as only label

✓ <label>Email</label><input>

✗ placeholder='Email' only

Errors should appear near the problem

Do Show error below related input

Don't Single error message at top of form

✓ Error under each field

✗ All errors at form top

Validate as user types or on blur

Do Validate on blur for most fields

Don't Validate only on submit

✓ onBlur validation

✗ Submit-only validation

Use appropriate input types

Do Use email tel number url etc

Don't Text input for everything

✓ type='email'

✗ type='text' for email

Help browsers autofill correctly

Do Use autocomplete attribute properly

Don't Block or ignore autofill

✓ autocomplete='email'

✗ autocomplete='off' everywhere

Mark required fields clearly

Do Use asterisk or (required) text

Don't No indication of required fields

✓ * required indicator

✗ Guess which are required

Let users see password while typing

Do Toggle to show/hide password

Don't No visibility toggle

✓ Show/hide password button

✗ Password always hidden

Confirm form submission status

Do Show loading then success/error state

Don't No feedback after submit

✓ Loading -> Success message

✗ Button click with no response

Inputs should look interactive

Do Use distinct input styling

Don't Inputs that look like plain text

✓ Border/background on inputs

✗ Borderless inputs

Show appropriate keyboard for input type

Do Use inputmode attribute

Don't Default keyboard for all inputs

✓ inputmode='numeric'

✗ Text keyboard for numbers

Design for mobile then enhance for larger

Do Start with mobile styles then add breakpoints

Don't Desktop-first causing mobile issues

✓ Default mobile + md: lg: xl:

✗ Desktop default + max-width queries

Test at all common screen sizes

Do Test at 320 375 414 768 1024 1440

Don't Only test on your device

✓ Multiple device testing

✗ Single device development

Mobile layouts need touch-sized targets

Do Increase touch targets on mobile

Don't Same tiny buttons on mobile

✓ Larger buttons on mobile

✗ Desktop-sized targets on mobile

Text must be readable on all devices

Do Minimum 16px body text on mobile

Don't Tiny text on mobile

✓ text-base or larger

✗ text-xs for body text

Set viewport for mobile devices

Do Use width=device-width initial-scale=1

Don't Missing or incorrect viewport

✓ <meta name='viewport'...>

✗ No viewport meta tag

Avoid horizontal scrolling

Do Ensure content fits viewport width

Don't Content wider than viewport

✓ max-w-full overflow-x-hidden

✗ Horizontal scrollbar on mobile

Images should scale with container

Do Use max-width: 100% on images

Don't Fixed width images overflow

✓ max-w-full h-auto

✗ width='800' fixed

Tables can overflow on mobile

Do Use horizontal scroll or card layout

Don't Wide tables breaking layout

✓ overflow-x-auto wrapper

✗ Table overflows viewport

Adequate line height improves readability

Do Use 1.5-1.75 for body text

Don't Cramped or excessive line height

✓ leading-relaxed (1.625)

✗ leading-none (1)

Long lines are hard to read

Do Limit to 65-75 characters per line

Don't Full-width text on large screens

✓ max-w-prose

✗ Full viewport width text

Consistent type hierarchy aids scanning

Do Use consistent modular scale

Don't Random font sizes

✓ Type scale (12 14 16 18 24 32)

✗ Arbitrary sizes

Fonts should load without layout shift

Do Reserve space with fallback font

Don't Layout shift when fonts load

✓ font-display: swap + similar fallback

✗ No fallback font

Body text needs good contrast

Do Use darker text on light backgrounds

Don't Gray text on gray background

✓ text-gray-900 on white

✗ text-gray-400 on gray-100

Headings should stand out from body

Do Clear size/weight difference

Don't Headings similar to body text

✓ Bold + larger size

✗ Same size as body

Show system status during waits

Do Show spinner/skeleton for operations > 300ms

Don't No feedback during loading

✓ Skeleton or spinner

✗ Frozen UI

Guide users when no content exists

Do Show helpful message and action

Don't Blank empty screens

✓ No items yet. Create one!

✗ Empty white space

Help users recover from errors

Do Provide clear next steps

Don't Error without recovery path

✓ Try again button + help link

✗ Error message only

Show progress for multi-step processes

Do Step indicators or progress bar

Don't No indication of progress

✓ Step 2 of 4 indicator

✗ No step information

Transient messages for non-critical info

Do Auto-dismiss after 3-5 seconds

Don't Toasts that never disappear

✓ Auto-dismiss toast

✗ Persistent toast

Confirm successful actions

Do Brief success message

Don't Silent success

✓ Saved successfully toast

✗ No confirmation

Handle long content gracefully

Do Truncate with ellipsis and expand option

Don't Overflow or broken layout

✓ line-clamp-2 with expand

✗ Overflow or cut off

Use locale-appropriate date formats

Do Use relative or locale-aware dates

Don't Ambiguous date formats

✓ 2 hours ago or locale format

✗ 01/02/03

Format large numbers for readability

Do Use thousand separators or abbreviations

Don't Long unformatted numbers

✓ 1.2K or 1,234

✗ 1234567

Show realistic placeholders during dev

Do Use realistic sample data

Don't Lorem ipsum everywhere

✓ Real sample content

✗ Lorem ipsum

Users should be able to skip tutorials

Do Provide Skip and Back buttons

Don't Force linear unskippable tour

✓ Skip Tutorial button

✗ Locked overlay until finished

Help users find results faster

Do Show predictions as user types

Don't Require full type and enter

✓ Debounced fetch + dropdown

✗ No suggestions

Dead ends frustrate users

Do Show 'No results' with suggestions

Don't Blank screen or '0 results'

✓ Try searching for X instead

✗ No results found.

Editing one by one is tedious

Do Allow multi-select and bulk edit

Don't Single row actions only

✓ Checkbox column + Action bar

✗ Repeated actions per row

Users need to know they talk to AI

Do Clearly label AI generated content

Don't Present AI as human

✓ AI Assistant label

✗ Fake human name without label

Waiting for full text is slow

Do Stream text response token by token

Don't Show loading spinner for 10s+

✓ Typewriter effect

✗ Spinner until 100% complete

Elements should respond to eye tracking before pinch

Do Scale/highlight element on look

Don't Static element until pinch

✓ hoverEffect()

✗ onTap only

UI needs Z-depth to separate content from environment

Do Use glass material and z-offset

Don't Flat opaque panels blocking view

✓ .glassBackgroundEffect()

✗ bg-white

Video consumes massive data and energy

Do Click-to-play or pause when off-screen

Don't Auto-play high-res video loops

✓ playsInline muted preload='none'

✗ autoplay loop

Heavy 3D/Image assets increase carbon footprint

Do Compress and lazy load 3D models

Don't Load 50MB textures

✓ Draco compression

✗ Raw .obj files

AI needs user feedback to improve

Do Thumps up/down or 'Regenerate'

Don't Static output only

✓ Feedback component

✗ Read-only text

Parallax/Scroll-jacking causes nausea

Do Respect prefers-reduced-motion

Don't Force scroll effects

✓ @media (prefers-reduced-motion)

✗ ScrollTrigger.create()

Icon-only buttons must have accessible names

Do Add aria-label to icon buttons

Don't Icon button without label

✓ <button aria-label='Close'><XIcon /></button>

✗ <button><XIcon /></button>

All form controls need labels or aria-label

Do Use label element or aria-label

Don't Input without accessible name

✓ <label for='email'>Email</label><input id='email' />

✗ <input placeholder='Email' />

Interactive elements must support keyboard interaction

Do Add onKeyDown alongside onClick

Don't Click-only interaction

✓ <div onClick={fn} onKeyDown={fn} tabIndex={0}>

✗ <div onClick={fn}>

Use semantic HTML before ARIA attributes

Do Use button/a/label elements

Don't Div with role attribute

✓ <button onClick={fn}>Submit</button>

✗ <div role='button' onClick={fn}>Submit</div>

Async updates need aria-live for screen readers

Do Add aria-live='polite' for dynamic content

Don't Silent async updates

✓ <div aria-live='polite'>{status}</div>

✗ <div>{status}</div> // no announcement

Decorative icons should be hidden from screen readers

Do Add aria-hidden='true' to decorative icons

Don't Decorative icon announced

✓ <Icon aria-hidden='true' />

✗ <Icon /> // announced as 'image'

All interactive elements need visible focus states

Do Use :focus-visible with ring/outline

Don't No focus indication

✓ focus-visible:ring-2 focus-visible:ring-blue-500

✗ outline-none // no replacement

Never remove outline without providing replacement

Do Replace outline with visible alternative

Don't Remove outline completely

✓ focus:outline-none focus:ring-2

✗ focus:outline-none // nothing else

Checkbox/radio must share hit target with label

Do Wrap input and label together

Don't Separate tiny checkbox

✓ <label class='flex gap-2'><input type='checkbox' /><span>Option</span></label>

✗ <input type='checkbox' id='x' /><label for='x'>Option</label>

Inputs need autocomplete attribute for autofill

Do Add appropriate autocomplete value

Don't Missing autocomplete

✓ <input autocomplete='email' type='email' />

✗ <input type='email' />

Use semantic input type attributes

Do Use email/tel/url/number types

Don't text type for everything

✓ <input type='email' />

✗ <input type='text' /> // for email

Never prevent paste functionality

Do Allow paste on all inputs

Don't Block paste on password/code

✓ <input type='password' />

✗ <input onPaste={e => e.preventDefault()} />

Disable spellcheck on emails and codes

Do Set spellcheck='false' on codes

Don't Spellcheck on technical input

✓ <input spellCheck='false' type='email' />

✗ <input type='email' /> // red squiggles

Keep submit enabled and show spinner during requests

Do Show loading spinner keep enabled

Don't Disable button during submit

✓ <button>{loading ? <Spinner /> : 'Submit'}</button>

✗ <button disabled={loading}>Submit</button>

Show error messages inline near the problem field

Do Inline error with focus on first error

Don't Single error at top

✓ <input /><span class='text-red-500'>{error}</span>

✗ <div class='error'>{allErrors}</div> // at top

Virtualize lists exceeding 50 items

Do Use virtual list for large datasets

Don't Render all items

✓ <VirtualList items={items} />

✗ items.map(item => <Item />)

Avoid layout reads during render phase

Do Read layout in effects or callbacks

Don't getBoundingClientRect in render

✓ useEffect(() => { el.getBoundingClientRect() })

✗ const rect = el.getBoundingClientRect() // in render

Group DOM operations to minimize reflows

Do Batch writes then reads

Don't Interleave reads and writes

✓ writes.forEach(w => w()); reads.forEach(r => r())

✗ write(); read(); write(); read(); // thrashing

Add preconnect links for CDN domains

Do Preconnect to known domains

Don't <link rel='preconnect' href='https://cdn.example.com' />

✓ // no preconnect hint

✗ Low

Lazy-load images below the fold

Do Use loading='lazy' for below-fold images

Don't Load all images eagerly

✓ <img loading='lazy' src='...' />

✗ <img src='...' /> // above fold only

URL should reflect current UI state

Do Sync filters/tabs/pagination to URL

Don't State only in memory

✓ ?tab=settings&page=2

✗ useState only // lost on refresh

Stateful components should support deep-linking

Do Enable sharing current view via URL

Don't No shareable state

✓ router.push({ query: { ...filters } })

✗ setFilters(f) // not in URL

Destructive actions require confirmation

Do Show confirmation dialog before delete

Don't Delete without confirmation

✓ if (confirm('Delete?')) delete()

✗ onClick={delete} // no confirmation

Use proper Unicode characters

Do Use ... curly quotes proper dashes

Don't ASCII approximations

✓ 'Hello...' with proper ellipsis

✗ 'Hello...' with three dots

Handle text overflow properly

Do Use truncate/line-clamp/break-words

Don't Text overflows container

✓ <p class='truncate'>Long text...</p>

✗ <p>Long text...</p> // overflows

Use non-breaking spaces for units and brand names

Do Use &nbsp; between number and unit

Don't 10&nbsp;kg or Next.js&nbsp;14

✓ 10 kg // may wrap

✗ Low

Never disable zoom in viewport meta

Do Allow user zoom

Don't <meta name='viewport' content='width=device-width'>

✓ <meta name='viewport' content='maximum-scale=1'>

✗ Critical

Avoid transition: all - specify properties

Do Transition specific properties

Don't transition: all

✓ transition-colors duration-200

✗ transition-all duration-200

Never use outline-none without replacement

Do Provide visible focus replacement

Don't Remove outline with nothing

✓ focus:outline-none focus:ring-2 focus:ring-blue-500

✗ focus:outline-none // alone

Use Intl for date/number formatting

Do Use Intl.DateTimeFormat

Don't Hardcoded date format

✓ new Intl.DateTimeFormat('en').format(date)

✗ date.toLocaleDateString() // or manual format