---
name: mobile-ux
description: Clean, efficient, minimal, and intuitive mobile/app UX design. Use this skill whenever the user asks to build a mobile app, app screen, app flow, onboarding sequence, settings page, navigation structure, dashboard, or any interface where usability and information architecture matter more than visual flair. Also trigger when the user mentions UX, user flow, wireframe, interaction design, screen layout, tab bar, bottom sheet, gestures, pull-to-refresh, swipe actions, progressive disclosure, mobile navigation, app architecture, or says things like "make this easier to use", "simplify this UI", "organize this better", "clean up this layout", or "the flow doesn't feel right." This skill complements frontend-design - mobile-ux owns structure, hierarchy, flow, and interaction; frontend-design owns color, typography, motion, and visual identity. When both could apply, use mobile-ux for the skeleton and frontend-design for the skin.
---

# Mobile UX Skill

Build app interfaces where every element earns its place. This skill is about the decisions that make an app feel *obvious* - the kind of UX where users never think about the UX.

This skill produces working code (React/.jsx or HTML) but its value is in the structural decisions: what goes where, what's hidden, what's revealed, how screens connect, how state changes feel. Pair with the `frontend-design` skill when the visual layer needs attention.

## Core Philosophy

Three principles, in order of priority:

1. **Reduce, then organize, then style.** Before arranging elements, ask which ones can be removed entirely. The best interface is the one with the fewest decisions for the user. Every field, button, label, and section should survive the question: "What happens if I cut this?"

2. **Obvious > clever.** If something needs a tooltip, tutorial, or label to explain how it works, redesign it. Interactions should be self-evident. Patterns the user already knows (from iOS, Android, or widely-used apps) are free - novel interactions carry a learning cost and need to justify it.

3. **One primary action per screen.** Every screen has one thing it wants the user to do. Make that thing unmistakable. Everything else is secondary or tertiary, and the visual weight should reflect that hierarchy precisely.

## Before Writing Code

Think through these questions (silently - don't dump them on the user):

- **What's the user's job?** Not "what features does this have" but "what is the user trying to accomplish, and what's the fastest path to done?"
- **What's the entry state?** First-time user with no data? Returning user mid-task? This determines the default screen.
- **What are the failure modes?** Empty states, errors, partial data, slow connections. Design these first - they're what most users will actually see most often.
- **What's the minimum viable screen?** Start with the absolute minimum elements needed. Add from there only when justified.

## Information Architecture

### Content Hierarchy

Structure content in strict priority layers. On mobile, vertical space is the primary resource - spend it wisely.

**Layer 1 - Glanceable context** (top 15-20% of screen): Where am I? What's the status? Users should understand the current state within 500ms of seeing the screen. This means: a clear title or contextual header, any critical status indicators, and navigation context (back affordance, breadcrumb, tab highlight).

**Layer 2 - Primary content** (middle 50-60%): The thing the user came for. This is the scrollable core. It should start immediately - no hero banners, no decorative headers eating vertical space. On a list screen, the first item should be visible without scrolling. On a detail screen, the most important information comes first.

**Layer 3 - Actions** (bottom 15-20%): What can I do? Primary actions anchored to bottom of viewport (thumb zone). One prominent CTA. Secondary actions either inline with content or in overflow menus - never competing visually with the primary.

### Grouping & Sections

- Group related items visually with spacing, not borders or cards. Whitespace is the cheapest and clearest separator.
- Use section headers sparingly. If a section needs a header, it's usually because the grouping isn't obvious enough from context. Fix the grouping first.
- Limit sections visible without scrolling to 2-3. More than that and nothing feels primary.

### Data Density

Mobile screens are small but users aren't stupid. Don't oversimplify to the point of hiding useful information behind extra taps.

- **Lists**: Show enough metadata per row that users can find what they need without opening each item. Name + one key attribute + timestamp is a good baseline. Two lines per row is the sweet spot.
- **Forms**: Group fields logically. Show 4-6 fields per scroll viewport. More than 8 visible fields at once creates overwhelm; fewer than 3 wastes space and makes forms feel longer than they are (more scrolling = feels longer).
- **Dashboards**: Lead with one hero metric. Support with 2-4 secondary metrics. Details live behind taps, not on the summary screen.

## Navigation Patterns

Choose based on the app's structure, not personal preference. Each pattern has a clear use case:

### Tab Bar (Bottom Navigation)
Use when: 3-5 top-level destinations of roughly equal importance.
Rules:
- 3-5 tabs maximum. At 2, it's a toggle. At 6+, it's a junk drawer.
- Labels on every tab. Icon-only tabs fail usability testing consistently.
- The first tab is home/default. The tab the user needs most often goes leftmost (right-thumb dominant) or center (if there's a prominent creation action).
- Active state must be instantly distinguishable - filled icon vs outline, or color shift. Don't rely on subtle weight changes.
- Tabs persist across the full app experience. Don't hide them contextually unless the user is in a focused task (compose, edit, camera).

### Stack Navigation (Push/Pop)
Use when: linear drill-down from general → specific.
Rules:
- Always show a back affordance. Swipe-to-go-back is a supplement, not a replacement.
- Title in the nav bar should update to reflect current context.
- Keep stack depth under 4 levels. If you're deeper, the IA needs restructuring.
- Destructive actions (delete, discard) need confirmation at the point of action, not after navigating away.

### Modal / Bottom Sheet
Use when: focused task, selection, or confirmation that should return to the previous context.
Rules:
- Use bottom sheets for quick selections, filters, and options. They're thumb-friendly and feel lightweight.
- Full-screen modals for creation flows or multi-step tasks that need focus.
- Every modal needs a clear exit: X button, Cancel, or swipe-to-dismiss. Never trap the user.
- Modals don't go inside modals. If you need a second modal, rethink the flow.

### Drawer / Sidebar
Use when: many destinations (6+) or settings/account access.
Rules:
- Drawers are for secondary navigation. If users need the drawer every session, those items should be tabs instead.
- Hamburger menus reduce discoverability. If you use one, accept that items inside will be used less.

## Interaction Design

### Touch Targets
- Minimum 44×44pt tap targets (Apple HIG). 48×48dp on Android.
- Spacing between adjacent targets: minimum 8pt. If users will tap rapidly (e.g., a list of toggles), increase to 12pt.
- Thumb zone: primary actions in bottom 40% of screen. Destructive or infrequent actions can live higher.

### Feedback & State
Every interaction needs acknowledgment. The user should never wonder "did that work?"

- **Tap**: Immediate visual response (opacity change, scale, highlight) within 100ms.
- **Loading**: If >300ms, show a loading indicator. If >2s, show progress or a skeleton screen. Never show a blank screen.
- **Success**: Confirm completion. For small actions (toggle, favorite), a state change is enough. For big actions (submit, purchase), explicit confirmation.
- **Error**: Show what went wrong AND what to do about it. "Something went wrong" is not an error message. "Couldn't save - check your connection and try again" is.

### Gestures
Use established gesture vocabulary. Don't invent.
- Swipe left/right on list items: quick actions (delete, archive, pin). Max 2 actions per direction.
- Pull-to-refresh: reload content. Only on scrollable lists/feeds.
- Long press: secondary actions or context menu. Always provide an alternative path (overflow menu) since long press is not discoverable.
- Pinch-to-zoom: media only.

### Empty States
Empty states are the first screen new users see. Treat them as onboarding, not error pages.

- Explain what will appear here once there's data.
- Provide a single clear action to create the first item.
- Keep the tone helpful, not cute. "No items yet" + a create button beats an illustration of a sad robot.

### Loading Strategy
- **Skeleton screens** over spinners for content that has a predictable layout.
- **Optimistic updates** for user-initiated actions (toggle, like, save). Show the result immediately, reconcile with the server in the background. Roll back visually if it fails.
- **Progressive loading**: show the structure first, then populate. Header → list skeleton → real items.

## Screen Patterns

### List → Detail
The most common mobile pattern. Get it right.
- List: one-line or two-line items. Primary text + supporting text + optional metadata. Tap anywhere on the row to open detail.
- Detail: full content with contextual actions. Back button returns to list, preserving scroll position.
- Search/filter: top of list, collapsible on scroll. Filter chips > dropdown menus for mobile.

### Form / Input
- One column only. Multi-column forms don't work on mobile.
- Label above field (not inside as placeholder - placeholders disappear on focus and lose context).
- Show validation inline, as the user completes each field. Don't wait for submit.
- Keyboard type should match the field: email keyboard for email, numeric for phone, etc.
- Auto-advance where possible (OTP fields, date pickers).
- Sticky submit button at bottom of viewport, not below the fold.

### Settings
- Grouped list with section headers.
- Toggles for binary choices. Don't use checkboxes on mobile.
- Navigation rows (chevron >) for sub-pages.
- Destructive actions (delete account, log out) at the bottom, visually de-emphasized.

### Dashboard / Summary
- Hero metric: one number, big, at the top.
- Trend indicator: up/down/stable, relative to previous period.
- Supporting cards: 2-4 secondary metrics in a grid or horizontal scroll.
- Detail: tap any metric to drill into the full data.

## Implementation Patterns (React)

When producing code, apply these structural patterns:

### Screen Layout Skeleton
```jsx
// Every screen follows this structure
<div className="screen">
  {/* Layer 1: Context - fixed top */}
  <header className="screen-header">...</header>
  
  {/* Layer 2: Content - scrollable middle */}
  <main className="screen-content">...</main>
  
  {/* Layer 3: Actions - fixed bottom */}
  <footer className="screen-actions">...</footer>
</div>
```

### State Handling
Every data-driven screen must handle all four states explicitly. Don't let any state fall through to a blank screen:
```
if (loading) → skeleton / spinner
if (error) → error message + retry
if (empty) → empty state + CTA
if (data) → render content
```

### Responsive Touch Targets
```css
/* Base interactive element */
.tap-target {
  min-height: 44px;
  min-width: 44px;
  padding: 12px 16px;
  /* generous padding even when content is small */
}

/* List items */
.list-row {
  min-height: 56px;
  padding: 12px 16px;
  display: flex;
  align-items: center;
  gap: 12px;
}
```

### Safe Areas
Always account for device safe areas (notch, home indicator, status bar):
```css
.screen {
  padding-top: env(safe-area-inset-top);
  padding-bottom: env(safe-area-inset-bottom);
  padding-left: env(safe-area-inset-left);
  padding-right: env(safe-area-inset-right);
}
```

## Anti-Patterns - What to Avoid

- **Hamburger menus hiding primary navigation.** If users need it every session, it belongs in a tab bar.
- **Carousels for important content.** The second slide might as well not exist. Show it all, or pick the best one.
- **Confirmation dialogs for non-destructive actions.** "Are you sure you want to save?" - yes, obviously.
- **Bottom sheets stacking on bottom sheets.** Dismiss the first, then show the second. Or rethink the flow.
- **Floating action buttons for non-creation actions.** FABs are for "new" or "create." Don't use them for search, filter, or settings.
- **Tutorial overlays.** If the interface needs a tutorial, the interface is the problem. Coach marks are band-aids.
- **Pagination on mobile.** Use infinite scroll with a loading indicator. "Page 2 of 47" is a desktop pattern.
- **Splash screens longer than 1 second.** Show them during actual loading. Don't add artificial delay for "branding."
- **Custom pull-to-refresh animations.** Use the system default. Users expect a specific behavior and timing.
- **Alert dialogs for non-critical information.** Alerts interrupt. Use inline messaging, toasts, or banners instead. Alerts are for: destructive confirmations, permission requests, and critical errors only.

## Quality Checklist

Before delivering, verify:

- [ ] Can a new user understand what to do on every screen within 3 seconds?
- [ ] Is there exactly one primary action per screen, and is it visually dominant?
- [ ] Do all four states (loading, error, empty, data) have explicit designs?
- [ ] Are touch targets ≥44pt with ≥8pt spacing?
- [ ] Is primary content visible without scrolling?
- [ ] Does every interaction provide immediate feedback?
- [ ] Can the user always get back (back button, swipe, dismiss)?
- [ ] Are destructive actions guarded and reversible?
- [ ] Is the navigation depth ≤3 levels for any task?
- [ ] Would removing any element break the experience? (If not, remove it.)
