ui-ux-mastery

name: ui-ux-mastery description: | Comprehensive UI/UX design system applying research-backed principles from Nielsen Norman Group, Baymard Institute, WCAG 2.2, cognitive psychology, and major design systems (Material Design 3, Apple HIG, Carbon, Atlassian, Fluent). Automatically triggers for: website design, landing pages, dashboards, forms, checkout flows, navigation, buttons, modals, cards, tables, mobile apps, accessibility, components, UI patterns, user interfaces, web applications, SaaS products, e-commerce, healthcare apps, enterprise software. Includes domain-specific prioritization matrices, conflict resolution frameworks, and evidence-based implementation patterns.

UI/UX Mastery Skill

This skill transforms Claude into a UI/UX expert by embedding research-backed design principles with domain-adaptive logic. Every interface decision follows evidence from 200,000+ hours of UX research.

CRITICAL: Domain Detection and Priority Matrix

Before ANY design decision, identify the domain and apply its priority hierarchy:

IF domain == "e-commerce":
    PRIORITY = [Trust, Checkout_Optimization, Product_Info, Mobile, Speed, Aesthetics]
    WEIGHTS = [0.25, 0.25, 0.20, 0.15, 0.10, 0.05]
    
ELIF domain == "saas" OR domain == "dashboard":
    PRIORITY = [Clarity, Efficiency, Data_Density, Learnability, Customization, Aesthetics]
    WEIGHTS = [0.25, 0.25, 0.20, 0.15, 0.10, 0.05]
    
ELIF domain == "healthcare" OR domain == "medical":
    PRIORITY = [Safety, Accuracy, Accessibility, Compliance, Efficiency, Aesthetics]
    WEIGHTS = [0.30, 0.25, 0.20, 0.15, 0.07, 0.03]
    # CRITICAL: Error prevention is NON-NEGOTIABLE in healthcare
    
ELIF domain == "enterprise" OR domain == "b2b":
    PRIORITY = [Efficiency, Reliability, Keyboard_Nav, Documentation, Security, Aesthetics]
    WEIGHTS = [0.30, 0.25, 0.20, 0.15, 0.07, 0.03]
    
ELIF domain == "consumer" OR domain == "mobile_app":
    PRIORITY = [Simplicity, Engagement, Speed, Personalization, Delight, Trust]
    WEIGHTS = [0.25, 0.20, 0.20, 0.15, 0.10, 0.10]
    
ELIF domain == "content" OR domain == "media" OR domain == "blog":
    PRIORITY = [Readability, Scannability, Navigation, Speed, Accessibility, Engagement]
    WEIGHTS = [0.30, 0.25, 0.20, 0.10, 0.10, 0.05]
    
ELSE:  # General web application (default)
    PRIORITY = [Usability, Accessibility, Clarity, Consistency, Speed, Aesthetics]
    WEIGHTS = [0.25, 0.25, 0.20, 0.15, 0.10, 0.05]

Universal Baseline: Nielsen's 10 Heuristics (ALWAYS APPLY)

These heuristics are NON-NEGOTIABLE across all domains:

1. Visibility of System Status

• Loading states: Use skeleton screens (perceived 20-30% faster than spinners)
• Progress indicators for operations >1 second
• Real-time feedback within 100ms for user actions
• Doherty Threshold: System response <400ms maintains flow state

2. Match Between System and Real World

• User-centric language, not technical jargon
• Icons with universal recognition (hamburger ≡, gear ⚙, etc.)
• Metaphors matching mental models
• Cultural considerations for international audiences

3. User Control and Freedom

• Undo/redo for all destructive actions
• Clear "emergency exits" (Cancel, Back, Close)
• Grace period for deletions (5-10 seconds recommended)
• Never trap users in flows without escape

4. Consistency and Standards

• Jakob's Law: Users spend 94% of time on OTHER sites
• Follow platform conventions (Material/iOS/Web)
• Internal consistency: Same action = same result everywhere
• External consistency: Match industry patterns

5. Error Prevention

• Constraints: Disable invalid options, not hide them
• Confirmations for high-impact actions (delete, submit, purchase)
• Smart defaults based on context/history
• Inline validation: "Reward Early, Punish Late" pattern

6. Recognition Over Recall

• Visible options, not hidden menus (hamburger penalty: 20%+ discoverability drop)
• Autocomplete for text inputs
• Recent items and search history
• Descriptive labels, not cryptic icons alone

7. Flexibility and Efficiency

• Keyboard shortcuts for power users
• Command palettes (⌘+K pattern)
• Customizable workflows
• Progressive disclosure for complexity

8. Aesthetic and Minimalist Design

• Every element must earn its place
• Signal-to-noise ratio: Maximize content, minimize chrome
• Whitespace is not wasted space
• 45-75 characters per line (66 optimal)

9. Error Recovery

• Error message formula: [What happened] + [Why] + [How to fix]
• Never blame the user
• Preserve user input on errors
• Offer direct path to resolution

10. Help and Documentation

• Contextual help at point of need
• Searchable documentation
• Progressive disclosure of complexity
• Tooltips for non-obvious features

Accessibility: WCAG 2.2 AA (NON-NEGOTIABLE)

ACCESSIBILITY_REQUIREMENTS = {
    "contrast_normal_text": "4.5:1",  # 14px regular or smaller
    "contrast_large_text": "3.0:1",   # 18px+ or 14px bold+
    "contrast_ui_components": "3.0:1",
    "touch_target_min": "44x44px",    # Apple HIG
    "touch_target_wcag": "24x24px",   # WCAG 2.2 minimum
    "focus_visible": True,            # Always visible focus indicators
    "keyboard_navigable": True,       # All functionality
    "screen_reader_compatible": True,
    "reduced_motion_support": True    # prefers-reduced-motion
}

Implementation Checklist

• All images have meaningful alt text (or alt="" for decorative)
• Heading hierarchy: H1 → H2 → H3 (no skipping)
• Form labels explicitly associated with inputs
• Error messages announced to screen readers (aria-live)
• Focus trapped in modals, returns on close
• Color NEVER sole indicator of meaning
• Keyboard: Tab order logical, Escape closes modals
• Links distinguished from buttons semantically
• Tables have proper headers and scope
• Skip links for main content

Color Blindness (8% of men affected)

/* Never rely solely on these pairs: */
AVOID_PAIRS = ["red/green", "blue/purple", "green/brown"]

/* Always add secondary indicators: */
- Icons alongside color indicators
- Patterns for charts/graphs
- Text labels for status

Reduced Motion

@media (prefers-reduced-motion: reduce) {
  *, *::before, *::after {
    animation-duration: 0.01ms !important;
    animation-iteration-count: 1 !important;
    transition-duration: 0.01ms !important;
  }
}

Cognitive Psychology: The 21 Laws of UX

Decision-Making Laws

Attention Laws

Motivation Laws

Perception Laws

Complexity Laws

Form Design (Research-Validated Patterns)

Label Placement (Eye-tracking data)

TOP_ALIGNED:     ~50ms cognitive load  ← RECOMMENDED
RIGHT_ALIGNED:   ~170-240ms
LEFT_ALIGNED:    ~500ms               ← AVOID
PLACEHOLDER_ONLY: ∞ (disappears)      ← NEVER USE

Validation Timing

def validate_field(field, is_correcting=False):
    if is_correcting:
        # User is fixing an error - validate as they type
        return validate_on_change(field)
    else:
        # First attempt - validate on blur
        return validate_on_blur(field)

Form Structure Requirements

• ALWAYS single-column (15.4 seconds faster, 95% CI)
• Mark required fields with asterisk (*) AND mark optional with "(optional)"
• Size fields to expected input (ZIP = short, email = medium)
• Group related fields with visual containers
• Maximum 12-14 form elements for checkout

Input Types

<!-- Use correct types for mobile keyboards -->
<input type="email">      <!-- @ key visible -->
<input type="tel">        <!-- Number pad -->
<input type="number" inputmode="decimal">  <!-- Decimal pad -->
<input type="search">     <!-- Search optimizations -->
<input type="url">        <!-- URL keyboard -->

Component Patterns

Buttons

HIERARCHY:
- Primary: One per view, main action (filled, high contrast)
- Secondary: Supporting actions (outlined or muted)
- Tertiary: Minor actions (text-only, underlined links)
- Destructive: Red/orange, requires confirmation for permanence

STATES (all required):
- Default, Hover, Focus (visible ring), Active (pressed), 
- Disabled (0.5 opacity + not-allowed cursor + aria-disabled)
- Loading (spinner + disabled interaction)

SIZING:
- Min height: 44px (touch), 36px (desktop)
- Min width: 64px
- Padding: 12-16px horizontal

LABELS:
- Verb + noun: "Save Changes", "Delete Account"
- Never just "Submit" or "Click Here"

Navigation

def choose_nav_pattern(item_count, platform, content_type):
    if platform == "mobile":
        if item_count <= 5:
            return "bottom_tab_bar"  # Always visible, thumb-reachable
        elif item_count <= 8 and content_type == "browsing":
            return "hamburger_menu"
        else:
            return "priority_plus"   # Show top items + "More"
    
    elif platform == "desktop":
        if item_count <= 7:
            return "horizontal_nav"  # Always visible
        else:
            return "mega_menu"       # 88% of top e-commerce uses this
    
    # NEVER use hamburger on desktop unless absolutely necessary
    # Hamburger causes 20%+ discoverability drop

Modals

// Accessibility requirements for modals
const modalRequirements = {
  focusTrap: true,           // Tab cycles within modal
  escapeCloses: true,        // Escape key dismisses
  clickOutsideCloses: true,  // Click overlay to dismiss
  returnFocus: true,         // Focus returns to trigger on close
  ariaModal: true,           // aria-modal="true"
  ariaLabelledby: true,      // Title connected to modal
  preventBodyScroll: true,   // Prevent background scroll
  maxWidth: "600px",         // Content-appropriate sizing
  maxHeight: "80vh"          // Scrollable within modal
};

// When to use modals vs other patterns
// USE modal: immediate attention needed, simple confirmation
// AVOID modal: complex forms (use page), can be inline (use expansion)

Tables

RESPONSIVE PATTERNS:
- Horizontal scroll: Simple, but loses context
- Card stack: Good for mobile, loses comparison ability
- Priority columns: Hide less important columns progressively

REQUIREMENTS:
- Sticky headers for scrollable tables
- Sortable columns with clear indicators
- Zebra striping OR clear row borders
- Adequate cell padding (12-16px)
- Right-align numbers for comparison
- Truncate with ellipsis + tooltip for overflow

Loading States

PATTERN SELECTION:
- <1 second: No indicator (feels instant)
- 1-3 seconds: Spinner or progress bar
- >3 seconds: Skeleton screen + progress percentage

SKELETON SCREENS:
- Match actual content layout
- Use subtle pulse animation
- Gray blocks for text, rounded for images
- Reduce perceived wait by 20-30%

PROGRESS INDICATORS:
- Determinate: Known duration (file upload)
- Indeterminate: Unknown duration (search)
- Start at 10-20% for Goal-Gradient Effect

Empty States

STRUCTURE:
1. Illustration/Icon (optional, adds warmth)
2. Heading: What happened
3. Body: Why it matters
4. CTA: What to do next

EXAMPLE:
"No projects yet"
"Projects help you organize your work. Create one to get started."
[+ Create Project]

NEVER leave truly empty - always guide user to next action

Typography System

/* Scale: Minor Third (1.2) or Perfect Fourth (1.333) */
:root {
  --text-xs: 0.75rem;    /* 12px - Labels, captions */
  --text-sm: 0.875rem;   /* 14px - Secondary text */
  --text-base: 1rem;     /* 16px - Body (minimum for accessibility) */
  --text-lg: 1.125rem;   /* 18px - Large body */
  --text-xl: 1.25rem;    /* 20px - H4 */
  --text-2xl: 1.5rem;    /* 24px - H3 */
  --text-3xl: 1.875rem;  /* 30px - H2 */
  --text-4xl: 2.25rem;   /* 36px - H1 */
  --text-5xl: 3rem;      /* 48px - Display */
  
  --leading-tight: 1.25;   /* Headings */
  --leading-normal: 1.5;   /* Body text (WCAG minimum) */
  --leading-relaxed: 1.75; /* Long-form reading */
  --measure: 66ch;         /* Optimal: 45-75 characters */
}

Spacing System

/* 8px base grid */
:root {
  --space-1: 0.25rem;   /* 4px */
  --space-2: 0.5rem;    /* 8px */
  --space-3: 0.75rem;   /* 12px */
  --space-4: 1rem;      /* 16px */
  --space-5: 1.5rem;    /* 24px */
  --space-6: 2rem;      /* 32px */
  --space-8: 3rem;      /* 48px */
  --space-10: 4rem;     /* 64px */
  --space-12: 6rem;     /* 96px */
}

Motion Guidelines

/* Duration by complexity */
--duration-instant: 100ms;    /* Micro-interactions */
--duration-fast: 200ms;       /* Simple transitions */
--duration-normal: 300ms;     /* Standard transitions */
--duration-slow: 500ms;       /* Complex transitions */

/* Easing curves */
--ease-out: cubic-bezier(0.0, 0.0, 0.2, 1);      /* Entering elements */
--ease-in: cubic-bezier(0.4, 0.0, 1, 1);          /* Exiting elements */
--ease-in-out: cubic-bezier(0.4, 0.0, 0.2, 1);    /* Moving elements */

Conflict Resolution Framework

When principles conflict, use this decision tree:

def resolve_conflict(principle_a, principle_b, context):
    # Resolution hierarchy (highest priority first):
    # 1. Safety/Accessibility (non-negotiable)
    # 2. Core Task Completion
    # 3. Domain-Specific Priority
    # 4. User Expertise Level
    # 5. Business Goals
    
    if either_is_safety_critical(principle_a, principle_b):
        return prioritize_safety()
    
    if either_violates_wcag_aa(principle_a, principle_b):
        return choose_accessible_option()
    
    domain_priorities = get_domain_priorities(context.domain)
    return apply_domain_weights(principle_a, principle_b, domain_priorities)

Common Conflicts and Resolutions

E-Commerce Specific Patterns

Cart Abandonment Prevention (70.19% average rate)

TOP CAUSES & SOLUTIONS:
1. Extra costs (48%) → Show all costs upfront on product page
2. Required account (26%) → Guest checkout prominently offered
3. Slow delivery (25%) → Clear delivery dates with options
4. Complicated checkout (22%) → 12-14 form elements max
5. Lack of trust (19%) → Trust signals near checkout button

Product Page Requirements

• Multiple images including "in scale" shots
• Zoom functionality
• Clear pricing with delivery info
• Reviews with rating distribution (4.0-4.7 stars optimal)
• Clear CTA above the fold

Trust Signals

• SSL badge near checkout
• Payment logos near payment fields
• Reviews increase conversion 12.5%
• Trust badges + card logos: 12.6% lift
• Avoid over-saturation (triggers anxiety)

Healthcare Specific Patterns

Error Prevention (CRITICAL)

• Double confirmation for high-impact actions
• Undo period for all reversible actions
• Clear distinction between similar data
• Abnormal values visually highlighted (not just color)
• 36% of patient safety reports mention usability issues

Enhanced Accessibility

• Larger touch targets for clinical environments
• High contrast for varying lighting
• Screen reader optimization for all critical functions
• No color-only indicators for ANY clinical data

SaaS/Dashboard Patterns

Data Visualization

• Critical metrics scannable in 2-5 seconds
• F-pattern layout (important content top-left)
• Card-based layouts for modularity
• Accessible color palettes (not just red/green)

Complex Data Tables

• Sticky headers and first column
• Sortable/filterable with visible active filters
• Bulk actions for efficiency
• Keyboard navigation support

Anti-Patterns to NEVER Use

Dark Patterns (Legally Risky)

• Confirmshaming: Guilt-inducing decline language
• Hidden costs: Fees revealed only at checkout
• Forced continuity: Silent trial-to-paid conversion
• Roach motel: Easy signup, difficult cancellation

Usability Anti-Patterns

• Placeholder-only labels
• Disabled buttons without explanation
• Color-only status indicators
• Auto-advancing carousels
• Modal on page load
• Breaking browser back button

Quality Assurance Checklist

Before shipping any UI:

Accessibility:

• Keyboard navigation complete
• Screen reader announces all content
• Color contrast meets WCAG AA
• Focus indicators visible
• Touch targets ≥44px
• prefers-reduced-motion respected

Usability:

• Error messages are helpful
• Loading states for async operations
• Empty states guide to action
• Undo available for destructive actions
• Forms validate inline

Responsive:

• Works on 320px width
• Touch targets adequate on mobile
• No horizontal scroll
• Typography remains readable

Key Statistics Reference

PERFORMANCE THRESHOLDS:
- System response: <400ms (Doherty Threshold)
- Animation duration: 100-500ms
- Form completion: Single-column 15+ seconds faster

CONVERSION DATA:
- Average cart abandonment: 70.19%
- Ideal checkout: 12-14 form elements
- Guest checkout impact: 24-30% abandonment reduction
- Review impact: 270% purchase increase at 5+ reviews

ACCESSIBILITY IMPACT:
- 16% world population has significant disability
- 26% of US adults have some disability
- 8% of men are color blind

READING BEHAVIOR:
- 80% viewing time on left half
- Users read only 20-28% of content
- Average page visit: <60 seconds

Implementation Priority

When building ANY interface, follow this sequence:

1. Structure First: Semantic HTML, proper heading hierarchy
2. Accessibility: WCAG AA compliance from the start
3. Core Functionality: Main user flows working
4. Responsive Design: Mobile-first or desktop-down
5. Loading States: Skeleton screens, progress indicators
6. Error Handling: Validation, error messages, recovery
7. Polish: Animation, micro-interactions, delight

This order ensures fundamentals are never sacrificed for aesthetics.