Mobile UI Patterns skill for Codex

A good mobile screen does one primary job, puts its main action where a thumb reaches it, keeps every target at least 44 by 44 points, never hides content under system UI or the keyboard, and behaves the way the platform’s users expect.

Before designing

1. Identify the target: native iOS (SwiftUI/UIKit), native Android (Compose), React Native/Flutter, or mobile web. Read AGENTS.md and the existing navigation code (rg -n "TabView|NavigationStack|NavigationBar|createBottomTabNavigator|BottomNavigationBar").
2. List the top 3-5 destinations and the single most frequent action per screen.
3. Note one-handed vs two-handed use (commuting, standing, holding something).

Navigation model

Situation	Pattern	Notes
3-5 peer top-level destinations used often	Bottom tab bar (iOS TabView, M3 NavigationBar)	Labels always visible; keep tab state when switching
6+ destinations or rarely used sections	Tabs for top 4 + “More”, or a drawer	A drawer hides navigation; use it as secondary, not primary
Hierarchical drill-down	Stack navigation with back	Never break system back (Android back, iOS edge swipe)
Short task off the current context (filter, share, pick)	Bottom sheet, medium detent	Content behind stays visible; swipe-down and a close button both dismiss
Focused multi-step task (checkout, compose)	Full-screen modal with explicit Cancel/Done	Confirm discard if the user entered data
Switching views of the same data	Segmented control (iOS) or top tabs	Not for navigation between unrelated sections
Single primary creation action	FAB (Android) or a toolbar/nav bar button (iOS)	One FAB per screen; never for secondary actions

Reach and layout

• Primary actions go in the bottom third: sticky bottom button bar, bottom toolbar or FAB. The top corners are the hardest reach on large phones; keep only low-frequency or destructive-adjacent actions there (Edit, Settings).
• One primary button per screen, full-width or near it, 48-56pt tall.
• Single-column content. Horizontal carousels hide content; use them only for browsing peers, show a partial next card as the affordance.
• Spacing on a 4/8pt grid; 16pt side margins on phones, 20-24pt on larger phones.
• Body text 16-17px/pt minimum; support Dynamic Type (iOS) and font scaling (Android) up to at least 200% without truncating essentials.

Touch targets

Source	Minimum
Apple HIG	44 x 44 pt
Material 3	48 x 48 dp
WCAG 2.2 SC 2.5.8 (AA)	24 x 24 CSS px, or enough spacing

Design to 44-48. The visible icon can be 24; extend the hit area with padding. Keep at least 8pt between adjacent targets. List rows are fully tappable, not just their text.

Safe areas, viewport and keyboard (mobile web)

<meta name="viewport" content="width=device-width, initial-scale=1, viewport-fit=cover">

.app { min-height: 100dvh; }                  /* dvh tracks the collapsing URL bar */
.bottom-bar {
  position: sticky; bottom: 0;
  padding: 12px 16px calc(12px + env(safe-area-inset-bottom));
}
.header { padding-top: env(safe-area-inset-top); }
input, select, textarea { font-size: 16px; }  /* below 16px iOS Safari zooms on focus */

• 100vh on mobile includes the area behind browser chrome; use dvh (or svh for layouts that must never overflow).
• Do not disable zoom (maximum-scale=1, user-scalable=no); it is an accessibility failure.
• Fixed bottom bars and the on-screen keyboard conflict. Prefer position: sticky in a scroll container, and test with the keyboard open on iOS Safari and Android Chrome.
• The interactive-widget=resizes-content viewport key changes how Chromium resizes for the keyboard; Safari ignores it. Test both rather than relying on it.

Native: SwiftUI respects safe areas by default (.ignoresSafeArea() only for backgrounds); Compose needs Modifier.windowInsetsPadding(WindowInsets.safeDrawing) or Scaffold insets, and edge-to-edge is the default on recent Android targets.

Forms on phones

<input type="email" autocomplete="email" inputmode="email" enterkeyhint="next">
<input autocomplete="one-time-code" inputmode="numeric" pattern="[0-9]*">
<input type="tel" autocomplete="tel">

• Labels above fields, never placeholder-only.
• Right keyboard per field (inputmode, type), autocomplete for autofill.
• Scroll the focused field into view; keep the submit button reachable above the keyboard.
• Show errors inline under the field and keep the user’s input.

Gestures

• Every gesture needs a visible alternative (WCAG 2.5.1 and 2.5.7): swipe-to-delete also offers a menu or edit mode; drag-to-reorder also offers move buttons.
• Do not start custom horizontal swipes within about 20pt of the left screen edge on iOS (system back gesture) or either edge on Android (gesture navigation back).
• Pull-to-refresh only on lists that show changing data at the top.
• Long-press is undiscoverable; only use it for shortcuts that exist elsewhere.

Platform conventions

Element	iOS	Android (Material 3)
Back	Top-left chevron with previous title, edge swipe	System back gesture/button; top app bar arrow
Primary create	Nav bar ”+” or bottom toolbar	FAB
Alerts	Centered alert, destructive button red, cancel bold	Dialog with text buttons right-aligned
Action list	Action sheet / context menu	Bottom sheet or menu
Switch	Toggle	Switch

Cross-platform apps can share structure but should use native back behaviour, dialogs and pickers on each platform.

States to design for every screen

Loading (skeleton for known layout), empty, error with retry, offline, partial data, long content (names 3x longer, 200% text), and slow network. Hand these to $ui-copy-states for wording.

Verification

• Screens at 360 x 800 (common Android) and 393 x 852 (recent iPhone), plus 320 wide.
• Every interactive element hit area at least 44 x 44 (check in devtools or Xcode view debugger).
• No content under notch, home indicator or keyboard; test landscape once.
• Text scaled to 200%: nothing essential truncated or overlapping.
• System back works from every screen and does not lose entered data silently.
• Primary action reachable one-handed.

For web, Playwright device emulation gives quick screenshots:

npx playwright screenshot --device="iPhone 15" http://localhost:3000/checkout iphone.png
npx playwright screenshot --device="Pixel 7" http://localhost:3000/checkout pixel.png

Emulation does not reproduce keyboard and URL-bar behaviour; confirm those on a real device or simulator.

Review output

## Mobile review: <screen>
| # | Issue | Where | Impact | Fix |
|---|---|---|---|---|
| 1 | Save button in top-right, 32pt target | Edit profile | Hard reach, mis-taps | Sticky bottom primary button, 48pt |
Platform conventions broken: <...>
Tested on: <devices/sizes, text scale, keyboard open>

Related: page-level breakpoints in $responsive-design; implementation in $swiftui-views, $android-jetpack-compose or $react-native-expo.