newspaper_wedding/.aidlc/knowledge/aidlc-design-agent/ux-guide.md

UX Guide

Nielsen's 10 Usability Heuristics (Applied)

Use these as a review checklist for every user-facing specification:

1. Visibility of system status: Show loading indicators, progress bars, success confirmations. Users must always know what is happening.
2. Match between system and real world: Use domain language the user understands. Avoid technical jargon in UI labels.
3. User control and freedom: Provide undo, cancel, and back. Never trap users in a flow without an exit.
4. Consistency and standards: Same action = same label = same position across all screens. Follow platform conventions.
5. Error prevention: Disable invalid actions, use type-appropriate inputs (date pickers, dropdowns), confirm destructive operations.
6. Recognition rather than recall: Show options, recent items, defaults. Minimize what users must remember between screens.
7. Flexibility and efficiency of use: Support keyboard shortcuts, bulk actions, and saved preferences for expert users without cluttering the novice experience.
8. Aesthetic and minimalist design: Every element must earn its place. Remove decorative elements that do not aid task completion.
9. Help users recognize, diagnose, and recover from errors: Error messages must say what went wrong, why, and what to do next. Never show raw error codes.
10. Help and documentation: Provide contextual help (tooltips, inline hints) at the point of need, not in a separate help section.

WCAG 2.1 AA Key Requirements

Perceivable

• Text contrast ratio: minimum 4.5:1 for normal text, 3:1 for large text (18px+ bold or 24px+)
• Non-text content has text alternatives (alt text, ARIA labels)
• Content does not rely solely on color to convey meaning (use icons, patterns, or text too)
• Media has captions or transcripts

Operable

• All functionality available via keyboard (Tab, Enter, Space, Arrow keys, Escape)
• Focus order follows a logical reading sequence
• Focus indicators are visible (never outline: none without replacement)
• No content flashes more than 3 times per second
• Touch targets are minimum 44x44 CSS pixels

Understandable

• Language of page is declared in HTML
• Form inputs have visible labels (not just placeholders)
• Error identification is specific ("Email is invalid" not "Error in field 3")
• Consistent navigation across pages

Robust

• Valid HTML semantics (headings in order, lists for lists, tables for tabular data)
• ARIA roles used correctly (not overused; native HTML elements preferred)
• Content works across browsers and assistive technologies

Interaction Patterns Reference

Forms

• Labels above inputs (not beside, not inside as placeholder-only)
• Inline validation on blur, not on every keystroke
• Submit button disabled until required fields are valid (with visual explanation)
• Group related fields with fieldset/legend
• Mark optional fields, not required ones (most fields should be required)

Data Tables

• Sortable columns with sort indicator (arrow direction)
• Filterable with clear filter indicators and reset option
• Pagination with page size selector and total count
• Row selection with bulk action toolbar
• Empty state message with guidance ("No results. Try adjusting your filters.")

Navigation

• Primary navigation: persistent, max 7 items, current page highlighted
• Breadcrumbs for hierarchical content (3+ levels deep)
• Search: globally accessible, auto-suggest after 3 characters, recent searches shown

Feedback & States

• Loading: Skeleton screens for initial load, spinners for actions (with timeout message after 5s)
• Success: Inline confirmation near the action, auto-dismiss after 5s, do not redirect immediately
• Error: Inline near the cause, red but with icon (not color-only), actionable message
• Empty: Illustration + explanation + primary action ("No items yet. Create your first item.")
• Confirmation: Required for delete, bulk operations, and irreversible actions. Include what will happen and an undo option if possible.

User Flow Documentation Format

For each user flow, specify:

Flow: [name]
Persona: [who performs this]
Trigger: [what initiates the flow]
Steps:
  1. [Screen/state] -> [user action] -> [system response]
  2. [Screen/state] -> [user action] -> [system response]
  ...
Success outcome: [what the user sees when done]
Error paths:
  - [condition] -> [error screen/message] -> [recovery action]

Information Architecture

Navigation Hierarchy Principles

• Maximum 3 levels of nesting for primary navigation
• Flat is better than deep — prefer broad categories with fewer sub-levels
• Every page must be reachable within 3 clicks from the home/dashboard
• Use progressive disclosure: show summary first, detail on demand

Content Grouping Strategies

• Group by user task (what they want to do), not by system structure (how it is built)
• Card sorting reference: use open card sort for new IA, closed card sort to validate existing
• Related actions should be visually proximate (Gestalt principle of proximity)

Labeling Taxonomy

• Labels must use the user's language, not internal jargon
• Consistent verb forms across navigation (all nouns or all verbs, not mixed)
• Test labels with 5+ representative users before finalizing

Sitemap Structure Patterns

• Hub-and-spoke: central dashboard with links to feature areas (suits task-based apps)
• Hierarchical: nested tree (suits content-heavy sites, documentation)
• Sequential: linear flow (suits onboarding, checkout, wizards)
• Choose the pattern that matches the primary user workflow

Responsive and Adaptive Design

Breakpoint Strategy (Mobile-First)

• Design for smallest screen first, then enhance for larger screens
• Common breakpoints: 320px (mobile), 768px (tablet), 1024px (desktop), 1440px (large desktop)
• Content dictates breakpoints, not device names — add breakpoints where the layout breaks

Layout Adaptation Patterns

• Fluid: Percentage-based widths, content reflows naturally (default approach)
• Adaptive: Distinct fixed layouts per breakpoint (use when fluid is insufficient)
• Responsive: Combination of fluid grids, flexible images, and media queries (recommended)

Touch Target Sizing

• Minimum 44x44 CSS pixels for all interactive elements (WCAG 2.1 AA)
• 8px minimum spacing between adjacent touch targets
• Increase to 48x48 px for primary actions on mobile

Content Priority Shifting

• Stack columns vertically on mobile (most important content first)
• Hide secondary navigation behind a menu icon on small screens
• Collapse data tables into card views on mobile
• Defer non-critical images and media on slow connections

Performance Considerations for Mobile

• Target < 3s load time on 3G connections
• Lazy-load images and below-the-fold content
• Minimize JavaScript payload (< 200KB compressed for initial load)
• Use responsive images (srcset) to serve appropriately sized assets