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:
- Where am I? — Page title + breadcrumbs
- What can I do here? — Primary actions visible above the fold
- What are the sub-sections? — Tabs, cards, or clearly labeled sections
- 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
| Pattern |
When to use |
Item count |
| Top nav (horizontal) |
Sections are equally important, product is simple |
3-7 top-level items |
| Sidebar (vertical) |
Complex product, long sessions, sections have subsections |
5-20 items with grouping |
| Tabs |
Related views of the same object (Overview / Activity / Settings) |
2-6 tabs on a single entity |
| Command palette |
Power users, large apps, cross-cutting actions |
Any size — supplements primary nav |
| Breadcrumbs |
Depth > 2 levels — always show path back to parent |
On all pages except homepage |
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:
- List every step the user takes from intent to completion (including navigation, clicks, form fields, confirmations).
- Identify friction points: Where does the user pause, make decisions, wait, or get confused?
- 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?
- 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
| Approach |
When to use |
| No confirmation |
Reversible actions with no data loss (archiving, toggling, moving) |
| Undo toast |
Destructive but recoverable actions (deleting a list item, removing a team member). Show "Undo" for 5-8 seconds. |
| Confirmation dialog |
Irreversible, high-stakes actions only (deleting an account, publishing to production, bulk delete). Require typing a confirmation string for the most dangerous actions. |
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:
| Level |
What to show |
Example |
| Essential |
Always visible — the core data and primary actions |
List view with key columns, main CTA |
| On interaction |
Revealed by hover, click, or expand |
Row hover actions, expandable details, tooltip info |
| On demand |
Available through explicit navigation or settings |
Advanced settings, raw data view, export options |
| Discoverable |
For power users who seek it out |
Keyboard shortcuts, API access, bulk actions, command palette |
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:
- WHAT happened — "Your payment failed" (not "Error 402")
- WHY it happened — "Your card was declined by your bank"
- 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:
| Technique |
When to use |
| Optimistic updates |
User actions on their own data (edits, toggles, creates). Update UI immediately. |
| Skeleton screens |
Initial page loads and data fetching. Show the layout shape before content arrives. Better than spinners for content-heavy pages. |
| Progress indicators |
File uploads, data imports, long computations. Show percentage or steps completed. |
| Lazy loading |
Below-the-fold content, images, secondary data. Load what's visible first. |
| Prefetching |
Links the user is likely to click next (visible nav items, "next" in a pagination). Fetch data on hover or viewport entry. |
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.
1---2name: ux-design3description: Use this skill when flows feel clunky, users are confused, navigation needs planning, onboarding needs design, or accessibility needs implementation. Covers information architecture, user flows, interaction patterns, progressive disclosure, and error handling UX.4---5
6# UX Design — Flows, Structure & Interaction
7
8Design 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.
9
10## Information Architecture
11
12The 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.
13
14### Core Principles
15
16- **Flat > deep.** Every additional level of nesting loses users. Aim for max 2 levels of hierarchy in navigation.
17- **Labels are architecture.** Vague labels cause wrong turns. If a label needs explanation, change the label.
18- **Group by user task, not data type.** "Marketing Assets" beats "Images | Documents | Videos." Users think in workflows, not file formats.
19- **5-9 items per group** (Miller's Law). More than 9 items in a nav section means it needs restructuring.
20- **Most-used items first.** Alphabetical ordering is lazy architecture — prioritize by frequency of use.
21
22### URL Structure
23
24URLs must mirror the information architecture:
25
26```
27/dashboard
28/projects
29/projects/[id]
30/projects/[id]/settings
31/settings/profile
32/settings/billing
33```
34
35Rules:
36- Nouns, not verbs: `/projects` not `/manage-projects`
37- Lowercase with hyphens: `/team-members` not `/teamMembers`
38- Meaningful IDs when possible: `/projects/acme-q4` not `/projects/a1b2c3`
39- Max 3 levels of depth in the URL path
40- Filter state in query params (`?status=active&owner=me`) for shareability
41
42### Page Content Hierarchy
43
44Every page must answer four questions in visual priority order:
45
461. **Where am I?** — Page title + breadcrumbs
472. **What can I do here?** — Primary actions visible above the fold
483. **What are the sub-sections?** — Tabs, cards, or clearly labeled sections
494. **What's most important?** — Visual hierarchy (size, weight, position) makes this obvious without reading
50
51### Page Types
52
53- **Dashboard:** Overview metrics + quick actions + recent activity. Never just a list of links.
54- **List page:** Filterable, sortable, searchable collection. Primary CTA to create new item. Show item count.
55- **Detail page:** Single object with all its information. Actions in the page header. Related objects linked.
56- **Settings page:** Grouped form fields. Save per-section, not one giant save button for the entire page.
57- **Empty state:** Explains what this page will contain + single CTA to add the first item. Never show an empty table with column headers.
58
59## Navigation Patterns
60
61Choose the pattern based on product complexity and number of sections:
62
63### Decision Framework
64
65| Pattern | When to use | Item count |
66|---------|------------|------------|
67| **Top nav (horizontal)** | Sections are equally important, product is simple | 3-7 top-level items |
68| **Sidebar (vertical)** | Complex product, long sessions, sections have subsections | 5-20 items with grouping |
69| **Tabs** | Related views of the same object (Overview / Activity / Settings) | 2-6 tabs on a single entity |
70| **Command palette** | Power users, large apps, cross-cutting actions | Any size — supplements primary nav |
71| **Breadcrumbs** | Depth > 2 levels — always show path back to parent | On all pages except homepage |
72
73### Sidebar Best Practices
74
75Group items with visual section headers. Use collapsible sections for depth. Structure:
76
77```
78WORKSPACE
79 Dashboard
80 Projects
81 Templates
82SETTINGS
83 Profile
84 Billing
85 Integrations
86```
87
88### Command Palette (Cmd+K)
89
90Implement as a modal overlay triggered by Cmd+K / Ctrl+K. Include three types of results:
91- **Navigation:** "Go to Settings," "Open Projects"
92- **Actions:** "Create project," "Invite teammate"
93- **Search:** "Find user John," "Search invoices"
94
95### Search and Filtering
96
97- Global search accessible from every page (header search bar)
98- Filters visible, not hidden in menus — show count of applied filters
99- Common filter dimensions: Status, Date range, Owner, Tags/Labels
100- Support saved/preset filters for common queries
101- Persist filter state in URL query params for shareability and bookmarking
102
103## User Flows
104
105### Task Analysis
106
107When designing or improving a flow, map the current steps a user takes to accomplish their goal. Then reduce:
108
1091. **List every step** the user takes from intent to completion (including navigation, clicks, form fields, confirmations).
1102. **Identify friction points:** Where does the user pause, make decisions, wait, or get confused?
1113. **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?
1124. **Target: 3-click rule for common tasks.** The most frequent user actions should require no more than 3 interactions from any starting point.
113
114### Step Reduction Principles
115
116- **Smart defaults** over blank forms — pre-fill everything inferable from context
117- **Inline creation** over navigate-to-form — let users create items where they need them
118- **Bulk operations** over one-at-a-time — if users do it to 10 items, let them do it to 10 at once
119- **Remember choices** — if the user picked a filter or view last time, restore it
120- **Combine related steps** — name + description on the same screen, not two separate screens
121
122## Interaction Patterns
123
124### Feedback — What Happens When You Click
125
126Every user action must produce visible feedback within 100ms. If the operation takes longer:
127- **< 1 second:** Show a spinner on the button or inline indicator
128- **1-10 seconds:** Show a progress indicator or skeleton screen
129- **> 10 seconds:** Show a progress bar with estimated time; allow background processing with notification on completion
130
131### Confirmation vs. Undo
132
133| Approach | When to use |
134|----------|------------|
135| **No confirmation** | Reversible actions with no data loss (archiving, toggling, moving) |
136| **Undo toast** | Destructive but recoverable actions (deleting a list item, removing a team member). Show "Undo" for 5-8 seconds. |
137| **Confirmation dialog** | Irreversible, high-stakes actions only (deleting an account, publishing to production, bulk delete). Require typing a confirmation string for the most dangerous actions. |
138
139Default to undo over confirmation dialogs. Confirmation dialogs interrupt flow and users click "OK" without reading them.
140
141### Inline vs. Modal Editing
142
143- **Inline editing** for single-field changes (rename, status change, quick note). Click to edit, blur or Enter to save.
144- **Modal/drawer** for multi-field edits that need context isolation (edit profile, configure integration).
145- **Full page** for complex creation flows (multi-step wizard, document editor).
146
147### Optimistic vs. Pessimistic Updates
148
149- **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.
150- **Pessimistic** (wait for server, then update UI): Use for financial transactions, permission changes, external API calls, and anything where partial failure creates inconsistency.
151
152## Progressive Disclosure
153
154Reveal complexity gradually. Four levels:
155
156| Level | What to show | Example |
157|-------|-------------|---------|
158| **Essential** | Always visible — the core data and primary actions | List view with key columns, main CTA |
159| **On interaction** | Revealed by hover, click, or expand | Row hover actions, expandable details, tooltip info |
160| **On demand** | Available through explicit navigation or settings | Advanced settings, raw data view, export options |
161| **Discoverable** | For power users who seek it out | Keyboard shortcuts, API access, bulk actions, command palette |
162
163### When Hiding Makes UX Worse
164
165Do not hide behind progressive disclosure:
166- **Error states** — always surface errors prominently
167- **Destructive consequences** — always show what will be deleted/changed
168- **Required information** — never put required fields in collapsed sections
169- **Current state** — the user should always see what's active, selected, or in progress
170
171## Error Handling UX
172
173### Error Message Pattern
174
175Every error message must answer three questions:
176
1771. **WHAT happened** — "Your payment failed" (not "Error 402")
1782. **WHY it happened** — "Your card was declined by your bank"
1793. **HOW TO FIX it** — "Update your payment method or try a different card" [with a link to payment settings]
180
181### Error State Design
182
183- **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.
184- **Empty results:** "No projects match your filters" with a CTA to clear filters — never a blank screen.
185- **Failed loads:** Show the last known good state with a "Retry" option, or a friendly error state with clear next steps.
186- **Partial failures:** If 8 of 10 items succeed, show success for the 8 and specific errors for the 2.
187
188### Retry Patterns
189
190- Auto-retry network failures with exponential backoff (1s, 2s, 4s) — max 3 attempts
191- Show a manual "Retry" button after auto-retries are exhausted
192- For background operations, queue retries silently and notify on persistent failure
193
194### Graceful Degradation
195
196When a feature or service is unavailable:
197- Show the rest of the page normally — do not block the entire UI
198- Display a contextual message where the failed component would appear
199- Provide an alternative path if one exists ("Analytics are temporarily unavailable. View raw data instead.")
200
201## Performance Perception
202
203Perceived speed matters more than actual speed. Techniques by situation:
204
205| Technique | When to use |
206|-----------|------------|
207| **Optimistic updates** | User actions on their own data (edits, toggles, creates). Update UI immediately. |
208| **Skeleton screens** | Initial page loads and data fetching. Show the layout shape before content arrives. Better than spinners for content-heavy pages. |
209| **Progress indicators** | File uploads, data imports, long computations. Show percentage or steps completed. |
210| **Lazy loading** | Below-the-fold content, images, secondary data. Load what's visible first. |
211| **Prefetching** | Links the user is likely to click next (visible nav items, "next" in a pagination). Fetch data on hover or viewport entry. |
212
213### Rules
214
215- Never show a blank white screen. Always show structure (skeleton) or previous state.
216- Animate transitions between states (loading → loaded) to avoid jarring layout shifts.
217- If an operation completes in < 200ms, do not show a loading indicator — it creates a flash that feels slower.
218- Prioritize above-the-fold content. The user does not need everything loaded before they can start reading or interacting.
whawkinsiv