UX Guidelines Domain - UI/UX Pro Max

Overview

The UX domain provides actionable UX guidelines with do’s, don’ts, code examples (good and bad), and severity ratings. Covers accessibility, navigation, animation, forms, and more. Database: ux-guidelines.csv (99 guidelines)
Search columns: Category, Issue, Description, Platform
Output columns: Category, Issue, Platform, Description, Do, Don’t, Code Example Good, Code Example Bad, Severity

When to Use

Checking accessibility compliance
Reviewing code for UX issues
Understanding best practices
Fixing usability problems
Learning do’s and don’ts

Search Examples

python3 skills/ui-ux-pro-max/scripts/search.py "smooth scroll navigation" --domain ux

Expected Output

{
  "domain": "ux",
  "results": [
    {
      "Category": "Navigation",
      "Issue": "Smooth Scroll",
      "Platform": "Web",
      "Description": "Anchor links should scroll smoothly to target section",
      "Do": "Use scroll-behavior: smooth on html element",
      "Don't": "Jump directly without transition",
      "Code Example Good": "html { scroll-behavior: smooth; }",
      "Code Example Bad": "<a href='#section'> without CSS",
      "Severity": "High"
    }
  ]
}

Example 2: Animation Duration

python3 skills/ui-ux-pro-max/scripts/search.py "animation duration timing" --domain ux

Expected Output

{
  "domain": "ux",
  "results": [
    {
      "Category": "Animation",
      "Issue": "Duration Timing",
      "Platform": "All",
      "Description": "Animations should feel responsive not sluggish",
      "Do": "Use 150-300ms for micro-interactions",
      "Don't": "Use animations longer than 500ms for UI",
      "Code Example Good": "transition-all duration-200",
      "Code Example Bad": "duration-1000",
      "Severity": "Medium"
    }
  ]
}

Example 3: Reduced Motion Accessibility

python3 skills/ui-ux-pro-max/scripts/search.py "reduced motion accessibility" --domain ux

Expected Output

{
  "domain": "ux",
  "results": [
    {
      "Category": "Animation",
      "Issue": "Reduced Motion",
      "Platform": "All",
      "Description": "Respect user's motion preferences",
      "Do": "Check prefers-reduced-motion media query",
      "Don't": "Ignore accessibility motion settings",
      "Code Example Good": "@media (prefers-reduced-motion: reduce)",
      "Code Example Bad": "No motion query check",
      "Severity": "High"
    }
  ]
}

CSV Structure

Column	Description	Example
`No`	Row number	1
`Category`	Guideline category	”Navigation”, “Animation”, “Accessibility”
`Issue`	Specific issue	”Smooth Scroll”
`Platform`	Target platform	”Web”, “Mobile”, “All”
`Description`	Issue explanation	”Anchor links should scroll smoothly”
`Do`	Correct approach	”Use scroll-behavior: smooth”
`Don't`	Incorrect approach	”Jump directly without transition”
`Code Example Good`	Good code example	”html { scroll-behavior: smooth; }“
`Code Example Bad`	Bad code example	”<a href=‘#section’> without CSS”
`Severity`	Impact level	”High”, “Medium”, “Low”

Guideline Categories

All Categories

1. Accessibility (CRITICAL)

Color Contrast
Focus States
Alt Text
ARIA Labels
Keyboard Navigation
Form Labels
Screen Reader Support

Smooth Scroll
Sticky Navigation
Active State
Back Button
Deep Linking
Breadcrumbs

3. Animation

Excessive Motion
Duration Timing
Reduced Motion
Transform Performance
Loading States

4. Forms

Form Validation
Error Messages
Input Labels
Autocomplete
Loading Buttons

5. Touch & Interaction

Touch Target Size
Hover vs Tap
Cursor Pointer
Double Tap Zoom

6. Layout & Responsive

Viewport Meta
Readable Font Size
Horizontal Scroll
Content Jumping
Z-Index Management

7. Performance

Image Optimization
Lazy Loading
Code Splitting

8. Typography

Line Height
Line Length
Font Pairing

Priority by Severity

High Severity (MUST FIX)

These issues cause legal compliance problems, critical usability failures, or accessibility violations. Fix immediately.

Examples:

Color contrast below 4.5:1
Missing alt text on images
No keyboard navigation support
Broken back button
Touch targets below 44x44px
Ignoring prefers-reduced-motion

Medium Severity (SHOULD FIX)

These issues cause moderate usability problems or unprofessional appearance. Fix before launch.

Examples:

No active nav state
Animation durations too long
Missing loading states
No sticky navigation
Line height too tight

Low Severity (NICE TO FIX)

These issues are polish items that improve user experience. Fix when time permits.

Examples:

Missing breadcrumbs on shallow sites
No smooth scroll (instant is OK)
Basic hover effects

Code Examples by Category

Accessibility: Color Contrast

/* WCAG AA: 4.5:1 minimum */
.text {
  color: #1E293B; /* Dark slate */
  background: #F8FAFC; /* Light background */
  /* Contrast ratio: 14.1:1 ✓ */
}

Accessibility: Focus States

/* Visible focus ring */
button:focus-visible {
  outline: 3px solid #2563EB;
  outline-offset: 2px;
}

Animation: Reduced Motion

/* Respect user preference */
@media (prefers-reduced-motion: reduce) {
  * {
    animation-duration: 0.01ms !important;
    transition-duration: 0.01ms !important;
  }
}

Touch: Target Size

<!-- 44x44px minimum (Apple HIG) -->
<button class="h-12 w-12 p-3">
  <Icon size={24} />
</button>

Forms: Error Messages

// Clear error near input
<div>
  <input
    type="email"
    className={error ? 'border-red-500' : ''}
    aria-invalid={!!error}
    aria-describedby="email-error"
  />
  {error && (
    <p id="email-error" className="text-red-500 text-sm mt-1">
      {error}
    </p>
  )}
</div>

// Visual indication of current page
<nav>
  <Link
    href="/dashboard"
    className={pathname === '/dashboard' ? 'text-primary border-b-2' : 'text-muted'}
  >
    Dashboard
  </Link>
</nav>

WCAG Compliance Checklist

Level A (Minimum)

Level AA (Required)

Color contrast 4.5:1 for normal text
Color contrast 3:1 for large text (24px+)
Focus visible on all interactive elements
Page has a unique <title>
Headings in correct order (h1 → h2 → h3)
Touch targets minimum 44x44px

Level AAA (Enhanced)

Color contrast 7:1 for normal text
Color contrast 4.5:1 for large text
Line height 1.5+ for body text
Paragraph spacing 1.5x line height
Text resizable up to 200% without loss of content

Common UX Mistakes

Navigation
Animation
Forms
Touch

❌ Sticky nav without padding compensation

<nav class="fixed top-0">...</nav>
<main><!-- Content hidden behind nav ✗ --></main>

✅ Correct approach

<nav class="fixed top-0 h-16">...</nav>
<main class="pt-16"><!-- Content visible ✓ --></main>

❌ Too many animations

<div class="animate-bounce">
  <div class="animate-pulse">
    <div class="animate-spin">✗</div>
  </div>
</div>

✅ Minimal, purposeful animation

<button class="hover:scale-105 transition-transform">✓</button>

❌ Too many fields

<!-- 10+ fields = low conversion ✗ -->
<input name="firstName" />
<input name="lastName" />
<input name="email" />
<input name="phone" />
<input name="address" />
...

✅ Minimal fields

<!-- 3 fields max = high conversion ✓ -->
<input name="email" />
<input name="password" />
<button>Sign Up</button>

❌ Hover-only interactions on mobile

/* Mobile users can't hover ✗ */
.menu { display: none; }
.nav:hover .menu { display: block; }

✅ Click/tap interactions

// Works on mobile ✓
const [open, setOpen] = useState(false);
<button onClick={() => setOpen(!open)}>Menu</button>

Testing Checklist

Before Launch

Keyboard Navigation

Tab through entire page
Verify focus visible on all elements
Check tab order matches visual order
Test Enter/Space on buttons

Screen Reader

Test with VoiceOver (Mac) or NVDA (Windows)
Verify all images have alt text
Check form labels announced correctly
Ensure page title read aloud

Color Contrast

Use browser DevTools “Accessibility” panel
Check all text meets 4.5:1 minimum
Verify CTAs have 7:1+ contrast

Responsive

Test at 375px (mobile), 768px (tablet), 1024px (laptop)
Verify no horizontal scroll
Check touch targets 44x44px minimum
Test sticky elements don’t obscure content

Performance

Run Lighthouse in Chrome DevTools
Target: Accessibility score 95+
Check prefers-reduced-motion respected

Tools & Resources

Contrast Checker

https://webaim.org/resources/contrastchecker/

Lighthouse

Chrome DevTools → Lighthouse → Accessibility

axe DevTools

Browser extension for accessibility testing

WAVE

https://wave.webaim.org/ - Web accessibility evaluator

Next Steps

Accessibility Styles

Learn about the “Accessible & Ethical” style

Color Contrast

Find accessible color palettes

Typography

Choose readable fonts

Product Types

See UX considerations by product

Chart Domain UI Styles Reference

⌘I

CLI Reference

Search Domains

Design Resources

Contributing

​Overview

​When to Use

​Search Examples

​Example 1: Smooth Scroll Navigation

​Example 2: Animation Duration

​Example 3: Reduced Motion Accessibility

​CSV Structure

​Guideline Categories

​1. Accessibility (CRITICAL)

​2. Navigation

​3. Animation

​4. Forms

​5. Touch & Interaction

​6. Layout & Responsive

​7. Performance

​8. Typography

​Priority by Severity

​High Severity (MUST FIX)

​Medium Severity (SHOULD FIX)

​Low Severity (NICE TO FIX)

​Code Examples by Category

​Accessibility: Color Contrast

​Accessibility: Focus States

​Animation: Reduced Motion

​Touch: Target Size

​Forms: Error Messages

​Navigation: Active State

​WCAG Compliance Checklist

​Common UX Mistakes

​Testing Checklist

​Before Launch

​Tools & Resources

Contrast Checker

Lighthouse

axe DevTools

WAVE

​Next Steps

Accessibility Styles

Color Contrast

Typography

Product Types

Build docs developers (and LLMs) love

Overview

When to Use

Search Examples

Example 1: Smooth Scroll Navigation

Example 2: Animation Duration

Example 3: Reduced Motion Accessibility

CSV Structure

Guideline Categories

1. Accessibility (CRITICAL)

2. Navigation

3. Animation

4. Forms

5. Touch & Interaction

6. Layout & Responsive

7. Performance

8. Typography

Priority by Severity

High Severity (MUST FIX)

Medium Severity (SHOULD FIX)

Low Severity (NICE TO FIX)

Code Examples by Category

Accessibility: Color Contrast

Accessibility: Focus States

Animation: Reduced Motion

Touch: Target Size

Forms: Error Messages

Navigation: Active State

WCAG Compliance Checklist

Common UX Mistakes

Testing Checklist

Before Launch

Tools & Resources

Next Steps