User Story Template for Mobile Apps
Mobile user stories fail in one of four ways: they ignore platform-specific interaction patterns (what works on iOS often does not translate to Android), they do not specify offline behavior (mobile users lose connectivity constantly), they skip performance requirements (a screen that loads in 800ms on an iPhone 15 Pro may take 3 seconds on a mid-range Android), or they overlook app store compliance requirements that can cause rejection.
This template extends the standard "As a user, I want... so that..." format with the mobile-specific acceptance criteria sections that prevent these failures. It is designed for React Native, Flutter, and native iOS/Android teams. Use it for any feature where the behavior on a mobile device differs meaningfully from the web equivalent.
What makes mobile stories different from web stories
The fundamental difference is context. Mobile users are distracted, often on slower networks, frequently interrupted, and using devices with wildly varying performance profiles. A web user at a desk has stable connectivity, a keyboard, and a large screen. A mobile user might be on a train with intermittent LTE on a three-year-old device with one hand holding the phone.
Platform divergence is the second major challenge. iOS and Android have different design languages, different gesture vocabularies, different permissions models, and different review processes. A story that says "implement swipe to delete" is incomplete — the swipe gesture direction, confirmation pattern, and undo behavior are all platform-specific and must be specified to avoid inconsistent implementations.
Finally, mobile stories must account for the device lifecycle: app state transitions (background, foreground, killed), push notification handling, deep link behavior, and the impact of device interruptions (phone calls, low battery warnings). These edge cases are invisible in web development but are the source of most mobile production incidents.
Template sections
5 sections covering the complete user story workflow.
Story format and persona
Write the story with a mobile-specific persona that captures device and context. The persona should specify whether this is a first-time or returning user, iOS or Android (or both), and the typical usage context (commuting, at desk, in a store). Context changes what "good" looks like.
As a returning user on iOS (iPhone X or newer), I want to view my recent activity while offline so that I can reference past information even when I have no signal on the subway. As an Android user on a mid-range device (Pixel 4a equivalent), I want to upload a photo so that it completes reliably even on a slow 4G connection.
Tips
- Separate iOS and Android stories when platform behavior genuinely differs — do not write one story and assume both platforms work the same way
- Include the usage context in the persona when it changes the acceptance criteria: "on the go" implies offline support; "in a meeting" implies silent/low-friction interactions
- For React Native or Flutter stories, note which behaviors must be platform-specific vs. which can be shared
Platform-specific behavior
Specify behavior that differs between iOS and Android: navigation patterns (iOS uses back-swipe gesture; Android uses system back button), interaction patterns (bottom sheets vs. full-screen modals), typography (system fonts differ), and permissions flows (each platform has its own permission request UI and flow).
iOS behavior: Use a modal bottom sheet for the filter panel. Dismiss with swipe-down gesture. The system back gesture (swipe from left edge) navigates to the previous screen, not the parent section. Android behavior: Use a full-screen bottom sheet. Dismiss with Android system back button or tapping the overlay. Respect the predictive back gesture on Android 13+.
Tips
- Reference platform HIG guidelines (Apple HIG, Material Design) rather than specifying every pixel — engineers know the platform conventions, they need to know when you want to deviate
- Flag explicitly when you want consistent cross-platform behavior: "This interaction should behave identically on iOS and Android to minimize support confusion"
- For permissions (camera, location, notifications): specify the request trigger moment, the permission rationale text, and the graceful degradation when permission is denied
Offline behavior
Every mobile story must specify offline behavior. The three options are: queue the action for sync when connectivity returns, show cached data with a staleness indicator, or block the action with a clear message explaining why. The default should never be a silent failure or an unhandled error state.
Offline behavior: - READ: Show cached data from the last successful fetch. Display a "Last updated [time]" indicator when offline. - WRITE (submit form): Queue the submission locally. Show a "Queued — will send when you reconnect" confirmation. Sync automatically when connectivity returns. Notify the user on success or failure of the queued action. - WRITE (upload photo): Show an error immediately if the file is over 5MB. For smaller files, queue with progress indicator.
Tips
- Test offline behavior explicitly in QA — disable the device's network connection, not just airplane mode, to test realistic degraded connectivity
- Queued actions need conflict resolution: what happens if the data changes server-side while the action is queued? Specify the resolution strategy
- Show a persistent offline indicator (a banner or subtle icon) when the user is offline for more than 3 seconds — do not let them discover it when an action fails
Performance budget
Specify explicit performance budgets for screen load time, animation frame rate, memory usage, and battery impact. Test these on mid-range devices (Pixel 4a for Android, iPhone SE for iOS), not flagship hardware. Most of your users are not on the latest device.
Performance requirements: - Initial screen load: under 400ms on mid-range devices (Pixel 4a / iPhone SE 3rd gen) on 4G - List scroll performance: 60fps sustained. No dropped frames during fast fling gestures. - Memory delta after opening this screen: under 15MB - Network data usage: under 200KB for the initial screen load (excluding user-uploaded content)
Tips
- Measure performance on a mid-range device over a throttled network (Slow 4G in DevTools or actual device testing) — flag if any requirement cannot be met without architectural changes
- Animations must run at 60fps — if they cannot due to complexity, remove the animation rather than shipping a janky one
- For image-heavy screens, specify lazy loading behavior and placeholder display to prevent perceived slowness even when the data is loading
Accessibility and app store compliance
Mobile accessibility requirements (VoiceOver on iOS, TalkBack on Android) must be specified in the story, not added as an afterthought. Flag any story that triggers app store review requirements: in-app purchases, privacy manifest changes, camera/microphone access, content age ratings, or permission changes.
Accessibility: All interactive elements must have accessibility labels. Images must have descriptive alt text. The minimum touch target size is 44×44pt (iOS) / 48×48dp (Android). Color contrast ratio must meet WCAG AA (4.5:1 for normal text). App store compliance: This feature requests camera access. Update the NSCameraUsageDescription in the iOS privacy manifest with the approved text: [text]. Submit for app store review before shipping to production.
Tips
- Test with VoiceOver and TalkBack enabled — do not rely on automated accessibility checkers alone
- Any change to requested permissions requires app store review. Plan this into the release timeline.
- For in-app purchases: Apple takes 15–30% commission, requires specific UI patterns, and prohibits links to external payment systems — review guidelines before designing the flow
Copy-paste template
## User Story (Mobile) **Story:** As a [iOS / Android / cross-platform] [user type with context], I want to [action], so that [user benefit]. **Priority:** [P0 / P1 / P2] **Platforms:** [iOS only / Android only / Both] --- ### Platform-Specific Behavior **iOS:** - Navigation: [How does the user navigate to/from this screen?] - Interactions: [Platform-specific gestures or patterns] - Deviations from HIG: [Any deliberate deviations from Apple HIG] **Android:** - Navigation: [Back button behavior, system gesture support] - Interactions: [Material Design patterns or deviations] - Android version minimum: [API level] --- ### Offline Behavior | User action | When offline | Recovery when reconnected | |---|---|---| | View [data] | Show cached version with "Last updated [time]" | Refresh automatically | | Submit [form] | Queue locally, show "Queued" state | Auto-submit, notify on result | | Upload [file] | Block if >5MB, queue smaller files | Resume upload automatically | --- ### Performance Budget | Metric | Target | Test device | |---|---|---| | Screen load (initial) | < [400]ms | Pixel 4a / iPhone SE on 4G | | Scroll frame rate | 60fps sustained | Mid-range device | | Memory delta | < [15]MB | Any device | | Network payload | < [200]KB | Throttled 4G | --- ### Accessibility - [ ] All interactive elements have accessibility labels - [ ] Images have descriptive alt text - [ ] Touch targets minimum 44×44pt (iOS) / 48×48dp (Android) - [ ] Color contrast ratio meets WCAG AA (4.5:1) - [ ] Tested with VoiceOver (iOS) and TalkBack (Android) --- ### App Store Compliance - Permissions required: [Camera / Location / Notifications / None] - Privacy manifest update: [Yes — reason / No] - Requires app store review: [Yes / No] - Content rating impact: [None / Update required] --- ### Acceptance Criteria - [ ] [Specific, testable criterion] - [ ] [Platform-specific criterion for iOS] - [ ] [Platform-specific criterion for Android] - [ ] [Offline scenario passes] - [ ] [Performance budget passes on mid-range device]
Frequently asked questions
Generate instead of filling in templates
Connect your tools, and Vantage generates the content using real product data. Free to start.
Free to start. No credit card required.