Ux Design

UX Design — Flows, Structure & Interaction

Design how users move through the app, find what they need, and accomplish tasks with minimal friction. This skill covers the structural and behavioral layer of UX — information architecture, navigation, user flows, interaction patterns, and error handling. For visual design (colors, typography, layout), see the beautify and ui-patterns skills. For onboarding flows, see ONBOARDING.md. For accessibility implementation, see ACCESSIBILITY.md.

Information Architecture

The goal of IA is that users never have to think about where to find something. Navigation should match the user's mental model, not the database schema or org chart.

Core Principles

• Flat > deep. Every additional level of nesting loses users. Aim for max 2 levels of hierarchy in navigation.
• Labels are architecture. Vague labels cause wrong turns. If a label needs explanation, change the label.
• Group by user task, not data type. "Marketing Assets" beats "Images | Documents | Videos." Users think in workflows, not file formats.
• 5-9 items per group (Miller's Law). More than 9 items in a nav section means it needs restructuring.
• Most-used items first. Alphabetical ordering is lazy architecture — prioritize by frequency of use.

URL Structure

URLs must mirror the information architecture:

/dashboard
/projects
/projects/[id]
/projects/[id]/settings
/settings/profile
/settings/billing

Rules:

• Nouns, not verbs: /projects not /manage-projects
• Lowercase with hyphens: /team-members not /teamMembers
• Meaningful IDs when possible: /projects/acme-q4 not /projects/a1b2c3
• Max 3 levels of depth in the URL path
• Filter state in query params (?status=active&owner=me) for shareability

Page Content Hierarchy

Every page must answer four questions in visual priority order:

1. Where am I? — Page title + breadcrumbs 2. What can I do here? — Primary actions visible above the fold 3. What are the sub-sections? — Tabs, cards, or clearly labeled sections 4. What's most important? — Visual hierarchy (size, weight, position) makes this obvious without reading

Page Types

• Dashboard: Overview metrics + quick actions + recent activity. Never just a list of links.
• List page: Filterable, sortable, searchable collection. Primary CTA to create new item. Show item count.
• Detail page: Single object with all its information. Actions in the page header. Related objects linked.
• Settings page: Grouped form fields. Save per-section, not one giant save button for the entire page.
• Empty state: Explains what this page will contain + single CTA to add the first item. Never show an empty table with column headers.

Navigation Patterns

Choose the pattern based on product complexity and number of sections:

Decision Framework

Sidebar Best Practices

Group items with visual section headers. Use collapsible sections for depth. Structure:

WORKSPACE
  Dashboard
  Projects
  Templates
SETTINGS
  Profile
  Billing
  Integrations

Command Palette (Cmd+K)

Implement as a modal overlay triggered by Cmd+K / Ctrl+K. Include three types of results:

• Navigation: "Go to Settings," "Open Projects"
• Actions: "Create project," "Invite teammate"
• Search: "Find user John," "Search invoices"

Search and Filtering

• Global search accessible from every page (header search bar)
• Filters visible, not hidden in menus — show count of applied filters
• Common filter dimensions: Status, Date range, Owner, Tags/Labels
• Support saved/preset filters for common queries
• Persist filter state in URL query params for shareability and bookmarking

User Flows

Task Analysis

When designing or improving a flow, map the current steps a user takes to accomplish their goal. Then reduce:

1. List every step the user takes from intent to completion (including navigation, clicks, form fields, confirmations). 2. Identify friction points: Where does the user pause, make decisions, wait, or get confused? 3. Eliminate steps: Every step must earn its place. Can two steps merge? Can a default eliminate a choice? Can a step be deferred to later? 4. Target: 3-click rule for common tasks. The most frequent user actions should require no more than 3 interactions from any starting point.

Step Reduction Principles

• Smart defaults over blank forms — pre-fill everything inferable from context
• Inline creation over navigate-to-form — let users create items where they need them
• Bulk operations over one-at-a-time — if users do it to 10 items, let them do it to 10 at once
• Remember choices — if the user picked a filter or view last time, restore it
• Combine related steps — name + description on the same screen, not two separate screens

Interaction Patterns

Feedback — What Happens When You Click

Every user action must produce visible feedback within 100ms. If the operation takes longer:

• < 1 second: Show a spinner on the button or inline indicator
• 1-10 seconds: Show a progress indicator or skeleton screen
• > 10 seconds: Show a progress bar with estimated time; allow background processing with notification on completion

Confirmation vs. Undo

Default to undo over confirmation dialogs. Confirmation dialogs interrupt flow and users click "OK" without reading them.

Inline vs. Modal Editing

• Inline editing for single-field changes (rename, status change, quick note). Click to edit, blur or Enter to save.
• Modal/drawer for multi-field edits that need context isolation (edit profile, configure integration).
• Full page for complex creation flows (multi-step wizard, document editor).

Optimistic vs. Pessimistic Updates

• Optimistic (update UI immediately, sync in background): Use for low-risk operations where failure is rare — toggling, liking, reordering, editing text. Roll back on failure with an error toast.
• Pessimistic (wait for server, then update UI): Use for financial transactions, permission changes, external API calls, and anything where partial failure creates inconsistency.

Progressive Disclosure

Reveal complexity gradually. Four levels:

When Hiding Makes UX Worse

Do not hide behind progressive disclosure:

• Error states — always surface errors prominently
• Destructive consequences — always show what will be deleted/changed
• Required information — never put required fields in collapsed sections
• Current state — the user should always see what's active, selected, or in progress

Error Handling UX

Error Message Pattern

Every error message must answer three questions:

1. WHAT happened — "Your payment failed" (not "Error 402") 2. WHY it happened — "Your card was declined by your bank" 3. HOW TO FIX it — "Update your payment method or try a different card" [with a link to payment settings]

Error State Design

• Form validation: Validate inline on blur, not on submit. Show the error adjacent to the field, not in a banner at the top. Use aria-invalid and aria-describedby to link error text to the field.
• Empty results: "No projects match your filters" with a CTA to clear filters — never a blank screen.
• Failed loads: Show the last known good state with a "Retry" option, or a friendly error state with clear next steps.
• Partial failures: If 8 of 10 items succeed, show success for the 8 and specific errors for the 2.

Retry Patterns

• Auto-retry network failures with exponential backoff (1s, 2s, 4s) — max 3 attempts
• Show a manual "Retry" button after auto-retries are exhausted
• For background operations, queue retries silently and notify on persistent failure

Graceful Degradation

When a feature or service is unavailable:

• Show the rest of the page normally — do not block the entire UI
• Display a contextual message where the failed component would appear
• Provide an alternative path if one exists ("Analytics are temporarily unavailable. View raw data instead.")

Performance Perception

Perceived speed matters more than actual speed. Techniques by situation:

Rules

• Never show a blank white screen. Always show structure (skeleton) or previous state.
• Animate transitions between states (loading → loaded) to avoid jarring layout shifts.
• If an operation completes in < 200ms, do not show a loading indicator — it creates a flash that feels slower.
• Prioritize above-the-fold content. The user does not need everything loaded before they can start reading or interacting.

Accessibility (a11y)

Accessibility is a quality attribute like performance or security. Building with correct HTML from the start provides 80% of accessibility for free. Retrofitting is expensive. This guide is organized in priority tiers — implement Tier 1 from day one, add Tiers 2 and 3 as the product matures.

Tier 1: Build From Day One

These five items cover 80% of accessibility issues. Implement them in every component from the start.

Semantic HTML

Use the correct HTML element for every purpose:

• <button> for actions, <a> for navigation — never the reverse, never <div onclick>
• <nav>, <main>, <aside>, <header>, <footer>, <article>, <section> for page structure
• <h1>-<h6> in order — no skipped levels, never used purely for styling
• <label> linked to every form input via for="id" attribute
• <ul>/<ol> for lists of items
• <table> with <th> headers for tabular data — never for layout
• <dialog> for modals

Semantic HTML provides screen reader navigation, keyboard behavior, and correct ARIA roles automatically. Fix HTML before adding ARIA attributes — ARIA is a repair tool, not a substitute for correct elements.

Keyboard Navigation

Every interaction must work without a mouse:

• All interactive elements (<button>, <a>, <input>, <select>) must be reachable with Tab
• All interactive elements must be activatable with Enter or Space
• Tab order must follow visual reading order (use DOM order, not tabindex hacks)
• Focus states must be clearly visible — never apply outline: none without a visible replacement. Style focus rings with a high-contrast outline (e.g., outline: 2px solid #005fcc; outline-offset: 2px)
• Escape must close modals, dropdowns, and popovers

Color Contrast

Minimum contrast ratios (WCAG AA):

Never rely on color alone to convey information. Status indicators, form validation, and charts must use icons, patterns, or text labels in addition to color.

Form Labels

• Every input must have a visible <label> linked via for="id". Placeholder text is not a label — it disappears on focus.
• Required fields: add a visual indicator (asterisk or "required" text) AND aria-required="true"
• Add autocomplete attributes for personal data fields: autocomplete="email", autocomplete="name", autocomplete="tel", etc.
• Group related fields with <fieldset> and <legend> (e.g., billing address fields).

Image Alt Text

• Every meaningful image: descriptive alt text, max 125 characters. Describe the content and function, not the appearance.
• Decorative images: alt="" (empty alt attribute, not a missing alt attribute)
• Charts and diagrams: provide a text summary nearby or via aria-describedby linking to a description element
• Icons used as buttons: the <button> must have an accessible label via aria-label or visually hidden text

Tier 2: Add After Launch

These items add significant value but require more implementation effort. Prioritize them once core flows are stable.

Focus Management

• When a modal opens, move focus to the first interactive element inside it
• When a modal closes, return focus to the element that triggered it
• Trap focus inside modals — Tab must not escape to background content. Implement with a focus trap utility.
• When content is dynamically added (new list item, inline edit), move focus to the new content or confirm action with a status message
• After a page-level action (delete item from list, form submission), move focus to a logical location — not the top of the page

Error Message Accessibility

• Connect error messages to their input via aria-describedby pointing to the error element's ID
• Add aria-invalid="true" to fields with validation errors
• Announce dynamic status changes with aria-live="polite" for status messages (save confirmation, progress updates)
• Announce urgent errors with aria-live="assertive" (form submission failure, session expiry)
• Error summary at the top of a form should be a list of links, each linking to the invalid field

Skip Navigation

Add a "Skip to main content" link as the first focusable element on every page. It should be visually hidden until focused:

.skip-link {
  position: absolute;
  left: -9999px;
  top: auto;
}
.skip-link:focus {
  position: fixed;
  top: 0;
  left: 0;
  z-index: 9999;
  padding: 1rem;
  background: white;
  color: black;
}

Reduced Motion

Respect the user's OS-level motion preference. See the motion-polish skill for the complete reduced motion CSS implementation and guidelines on what to disable vs. simplify.

• Implement @media (prefers-reduced-motion: reduce) to disable animations
• Use Tailwind motion-safe: prefix for animation classes
• Keep opacity transitions (fades are acceptable), remove transforms and movement
• Disable autoplay on videos and carousels

Tier 3: Polish

Implement after achieving product-market fit, or when targeting enterprise/government customers with compliance requirements.

Full ARIA Patterns

For custom interactive components that have no native HTML equivalent, implement complete ARIA patterns:

• Tabs: role="tablist", role="tab", role="tabpanel", aria-selected, arrow key navigation between tabs
• Menus: role="menu", role="menuitem", arrow key navigation, typeahead selection
• Combobox/Autocomplete: role="combobox", aria-expanded, aria-activedescendant, announced option count
• Date pickers: keyboard-navigable calendar grid, arrow keys for date navigation, announced month/year changes
• Drag and drop: provide keyboard alternative (move up/down buttons or reorder via menu)

Reference the WAI-ARIA Authoring Practices for the full specification of each pattern.

Screen Reader Testing

Test complete user flows with a screen reader — not just individual components:

• macOS: VoiceOver (Cmd+F5). Test in Safari (best VoiceOver support).
• Windows: NVDA (free) or JAWS. Test in Chrome or Firefox.
• Verify: page title announced on navigation, headings provide document outline, form labels read correctly, dynamic content changes announced, error states communicated.

Color Blindness

• Test with a color blindness simulator extension (e.g., Colorblindly, Sim Daltonism)
• Verify that no information is conveyed by color alone — all color-coded elements must have a secondary indicator
• Common failure: red/green for success/error without icons or text

Testing Checklist

Quick Test (5 minutes, every PR)

• [ ] Navigate the primary user flow (signup through core action) using only the keyboard
• [ ] Verify every interactive element is reachable with Tab
• [ ] Verify focus is visible on every element
• [ ] Verify every button activates with Enter or Space
• [ ] Verify Escape closes every modal and dropdown
• [ ] Verify no images are missing alt attributes

Automated Test (CI pipeline)

Run axe-core or Lighthouse accessibility audit on all primary pages. Integrate into CI so new violations block the build. Fix all critical and serious violations before merging. Track moderate violations as technical debt.

Deeper Test (quarterly or pre-major-release)

• [ ] Full flow test with VoiceOver or NVDA
• [ ] Browser zoom to 200% — verify no content loss or horizontal scrolling
• [ ] Color blindness simulation — verify no color-only information
• [ ] Verify all video content has captions

Common Mistakes

Onboarding Design

Onboarding has one job: get users to the aha moment as fast as possible. Everything else is noise. The best onboarding feels like using the product, not learning the product — interactive beats passive, doing beats reading.

Aha Moment Definition

Before designing onboarding, identify the single experience that makes a user say "I need this." Use this framework:

1. Look at retained users: What action did 80%+ of them take in their first week? 2. Look at churned users: What action did they NOT take? 3. The gap between these two groups is the activation metric. Onboarding exists to close this gap.

Examples of aha moments:

• Project management tool: Created a project and added a task
• Analytics platform: Saw their first dashboard with real data
• Communication tool: Sent and received a message from a teammate
• Design tool: Created and shared their first design

If the product is pre-launch and there is no retention data, identify the aha moment by asking: "What is the smallest demonstration of the product's core value?" Design onboarding to reach that moment in the fewest possible steps.

Onboarding Patterns

Choose the pattern based on product characteristics. Multiple patterns can be combined.

1. Setup Wizard

Best for: Products that require configuration before they are useful (workspace setup, data connection, role selection).

Implementation:

• 3-5 steps maximum. Each step asks ONE question or performs ONE action.
• Show a progress indicator: "Step 2 of 4"
• Always allow "Skip" on each step — but track skip rates. High skip rate on a step means the step is not earning its place.
• The final step must land on a populated, useful state — never a blank dashboard.

Typical flow: 1. "What will you use [Product] for?" — role/use-case selection 2. "Set up your workspace" — name, invite link generation 3. "Connect your data" — integration or import 4. "Here's your first [core object]" — pre-populated with their data

2. Checklist

Best for: Products with multiple activation criteria that users complete at their own pace.

Implementation:

• Persistent, visible checklist (sidebar widget or top banner). 4-6 items maximum.
• Pre-check the first item (account creation) to give momentum.
• Each item is a direct link to the action — not a description of what to do.
• Show progress: "3 of 5 complete"
• Celebrate completion (confetti animation, congratulations message).
• Dismiss after completion but keep accessible from settings or help menu.

Example:

• [x] Create your account
• [ ] Create your first project
• [ ] Invite a teammate
• [ ] Connect a data source
• [ ] Create your first report

3. Interactive Walkthrough

Best for: Complex products where users need guided context on the actual UI, not a separate tutorial.

Implementation:

• Step-by-step guidance overlaid on the real product UI.
• Highlight the element to interact with, dim everything else.
• Show a tooltip: what to do + why it matters (one sentence each).
• The user takes the actual action — not a simulation or demo mode.
• Allow re-triggering from a help menu for users who dismissed it early.

4. Templates and Sample Data

Best for: Products where empty state anxiety prevents action (dashboards, project tools, content platforms).

Implementation:

• Pre-populate the workspace with realistic sample data on first login.
• Offer "Start from template" alongside "Start from scratch" — template first, scratch second.
• Tailor templates to the use case selected during setup.
• Label sample data clearly: "Sample project — delete anytime."

5. Progressive Disclosure

Best for: Feature-rich products where showing everything on day one overwhelms users.

Implementation:

• Hide advanced features initially. Reveal based on usage triggers.
• Trigger format: "You've created 5 projects — did you know you can use folders to organize them?"
• Delivery: tooltips, banners, or in-app notification cards.
• Track which features are surfaced and their adoption rate after surfacing.

Personalization

Ask ONE question early to branch the experience. Keep it to a single selection screen.

By role:

• "I'm setting this up for myself" → solo onboarding, skip team features
• "I'm setting this up for my team" → workspace setup, invite flow, permissions overview
• "I'm evaluating tools for my company" → show ROI content, comparison features, import from competitor

By use case:

• Present 3-4 use cases that match the product's core segments
• Customize: templates offered, checklist items shown, example data populated, and feature emphasis

The personalization question should be the first or second step. Do not ask multiple branching questions — one is enough.

Anti-Patterns

Avoid these patterns that consistently degrade activation rates:

• Click-through tours that users dismiss without reading. Users click "Next" reflexively.
• Mandatory tutorials that block product access. Let users skip and discover.
• "Watch this video" as the primary onboarding. Video is passive. Users need to do, not watch.
• Tooltip overload that highlights every feature on the page simultaneously. Highlight one thing at a time.
• Static onboarding that does not adapt to what the user has already completed. If they created a project on their own, do not ask them to create one.
• No skip or exit option. Users must always be able to dismiss onboarding entirely.
• Ending on empty. Onboarding must leave the user looking at something useful — data, a template, a sample — never a blank screen.

Success Metrics

Track these to evaluate onboarding effectiveness: