/ux-design

name: ux-design
description: "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."

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

| 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:

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 in