Professional Mobile App Standards
A stack-neutral method for building mobile apps that feel finished: every screen has a reason to exist, every action gives feedback, every failure has a way out, and every visual value comes from one design system.
The standards here are defaults, not a template to stamp onto every app. A good result fits the app's real users, domain, and existing code. A bad result is a generic app with every screen from a list, a new color palette nobody asked for, and a rewrite of working code.
Ground rules
These hold in every mode, because breaking them costs the user more than any polish gains.
- Read before you change. Find the stack, navigation library, theme or token file, shared components, and folder conventions before proposing anything. Most apps are existing apps; treat them that way unless told otherwise.
- Fit the requirements. Add a screen, state, or capability only when a real user journey needs it. Name the journey when you recommend it.
- Keep the brand. Extend the existing tokens and components. Change brand colors, fonts, or logo only with explicit approval.
- Keep the architecture. Work inside the current stack, state management, and folder structure. No new dependency when the platform or an existing one does the job; if one is really needed, say why.
- Keep behavior. UI work must not change business logic, API contracts, or data handling unless the task asks for that.
- Write only when asked to build. In audit or spec work, produce documents and recommendations. Edit code only when the task authorizes implementation.
- Report honestly. Separate what is built and verified, built but not verified (for example, not run on a device), and only recommended. Never call something done that is not.
Pick the mode
Match the depth of the workflow to the request. Running all seven phases for "add an empty state to the orders list" wastes the user's time.
| Request looks like | Mode | Phases | Main output |
|---|---|---|---|
| "Plan / design an app", "what screens do I need" | Plan | 1–4 | Analysis, screen inventory, flows, design-system spec |
| "Spec this feature / screen" | Spec | 1 (light), 3, 4 (light) | Screen and component specifications |
| "Build / redesign / polish this screen or flow" | Build | 1 (light), 3, 5, 6 | Code changes plus a short verification note |
| "Review / audit my app", "what's missing" | Audit | 1, 2, 6, 7 | Quality assessment report |
| "Is this ready to ship / store submission" | Release | 1 (light), 6, 7 | Release-readiness checklist and blocking issues |
When the mode is unclear, default to Audit for an existing app and Plan for a new one, and say which you picked.
Workflow
Phase 1: Application analysis
Learn the app before judging it. Capture: purpose, target users, domain, core features, user roles, authentication model, supported platforms and minimum OS versions, stack, and the existing design system (token file, theme provider, component folder).
How to find these quickly in code: the package manifest (package.json, pubspec.yaml, build.gradle, Podfile/SPM), app config (app.json/app.config.*, Info.plist, AndroidManifest.xml), the navigation root, and the theme file. Note what is unknown instead of guessing. Use templates/application-analysis.md for Plan and Audit modes.
Phase 2: Screen discovery
Build a screen inventory from the app's real journeys. Mark each screen Required, Optional, Missing, or Not applicable, and give a reason. Map navigation relationships and dependencies (for example, "Reset password needs the email-link deep link"). Read references/screen-inventory.md for the full catalog and the applicability rules. Use templates/screen-inventory.md.
Phase 3: UX architecture
Define user flows, navigation structure, screen hierarchy, interaction patterns, the UI states each screen needs, and accessibility concerns.
- Navigation:
references/navigation-standards.md - States:
references/ui-states.md. Every data-driven screen needs at least loading, empty, error, and offline behavior defined. - Interactions:
references/interaction-patterns.md - Templates:
templates/user-flow.md,templates/screen-specification.md
Phase 4: Design system
Define or extend tokens (color, type, spacing, radius, elevation, motion, icon sizes), components and their variants, and light/dark theme support. Read references/design-system.md. Use templates/design-system.md and templates/component-specification.md.
In an existing app, first inventory what exists: hard-coded colors, font sizes, and spacing values found in screen files are the usual cause of an app that "looks off". Consolidating them into tokens is often the highest-value change.
Phase 5: UI implementation
Build with the project's own stack and conventions.
- Reuse existing components; extend a component with a variant before creating a near-duplicate.
- Every style value comes from tokens. No raw hex colors, ad hoc font sizes, or magic spacing numbers in screens.
- Keep presentation separate from data and business logic (container/hook/view-model vs view, per the project's existing pattern).
- Implement all the states from the spec, not only the success path.
- Apply accessibility as you build (labels, roles, touch targets, text scaling); retrofitting costs more. See
references/accessibility-standards.md. - For anything touching auth, tokens, personal data, permissions, or payments, read
references/security-standards.mdfirst.
Phase 6: Quality assurance
Verify instead of assuming. Run what the project has: type-check, lint, unit/component tests, and the app itself on a simulator or emulator if available. Then walk the relevant checklists:
checklists/design-review.md: consistency and visual qualitychecklists/implementation-review.md: states, navigation, forms, performance, code qualitychecklists/accessibility-review.mdchecklists/release-readiness.md: Release mode only
If you could not run the app or test on a real device, say so in the report. Do not report device behavior you did not observe.
Audit and Release: deep checks that broad reviews miss
A wide audit spreads attention thin, and the problems that hurt most in production are often in config files rather than screens. In Audit and Release mode, check each of these explicitly and say what you found, even if the answer is "present":
- Push setup: Android Firebase config and FCM credentials, iOS push entitlement and APNs; token-fetch failures not swallowed in release builds (
references/production-readiness.md§5). - Crash handling: a render-error fallback (error boundary or framework equivalent) and a crash reporter in release builds.
- Version gate: a way to force or prompt an update when the backend changes (minimum-version check, remote config).
- Consent: Terms and Privacy agreement at sign-up, recorded on the server, when accounts are created.
- Not-found and deep-link fallback: a bad link or a deleted record shows a real screen, not a framework default.
- Store blockers: account deletion, monetization rules (codes or vouchers that unlock features), developer account type for regulated apps, reviewer demo account, iPad/tablet support claimed but not designed.
- Read the platform config itself:
app.json/app.config.*,Info.plist,AndroidManifest.xml,eas.json, Firebase files. Resolve the final config when the tooling allows (npx expo config --type introspect).
Phase 7: Final evaluation
Produce the quality report with templates/quality-assessment.md: completed items, missing screens, UI inconsistencies, UX problems, technical issues, accessibility problems, performance concerns, and recommended improvements ranked by user impact and effort. Cite file paths and line numbers for code findings.
Mandatory standards (summary)
The details live in the references; these are the lines that should never be crossed.
- States: No data screen ships without loading, empty, error, and offline handling. Errors say what happened and offer a next action (retry, edit, contact support), never only a raw error code.
- Feedback: Every tap that starts work shows a response within about 100 ms (pressed state, spinner, or optimistic update). Submit buttons disable or debounce while a request runs, so a double tap cannot create a duplicate.
- Touch targets: At least 44×44 pt (iOS) and 48×48 dp (Android), even when the visible icon is smaller.
- Contrast: Body text at least 4.5:1; large text and essential UI elements at least 3:1, in both light and dark themes.
- Text scaling: Layouts survive the largest system font size without clipped or overlapping text.
- Tokens: Components use centralized tokens; new raw values are a review failure.
- Navigation: Android back and the iOS swipe-back always do something sensible; unsaved changes are confirmed before discard; protected screens redirect to sign-in and return the user afterward.
- Security: Tokens go in Keychain/Keystore-backed secure storage, never plain AsyncStorage/SharedPreferences/UserDefaults. No secrets in the app binary. Sensitive data stays out of logs, analytics, and crash reports.
- Permissions: Ask in context, after explaining why, and handle denial with a working fallback.
- Platform conventions: Respect each platform's back behavior, system sheets, date pickers, haptics, and safe areas, unless the brand deliberately unifies them.
Quality gates
Work is done for its mode only when these pass. If one fails, report it as open rather than finishing silently.
| Gate | Plan | Spec | Build | Audit | Release |
|---|---|---|---|---|---|
| Every recommended screen or feature names the journey it serves | ✓ | ✓ | ✓ | ||
| Each screen has its states defined (loading, empty, error, offline, plus relevant others) | ✓ | ✓ | ✓ | ✓ | ✓ |
| No new raw style values outside the token file | ✓ | ✓ | |||
| Type-check, lint, and existing tests pass (or failures are reported with output) | ✓ | ✓ | |||
| Accessibility checklist walked; failures listed | ✓ | ✓ | ✓ | ✓ | |
| Existing branding, architecture, and business logic preserved, or changes approved | ✓ | ✓ | ✓ | ||
| Report separates verified, unverified, and recommended items | ✓ | ✓ | ✓ | ✓ | |
| Store-blocking items (privacy policy, account deletion, permission strings, icons, versioning) checked | ✓ | ||||
| Every deep check (push setup, crash handling, version gate, consent, not-found, store blockers) reported | ✓ | ✓ |
Expected outputs
- Plan: the content of the
application-analysis,screen-inventory,user-flow(key journeys), anddesign-systemtemplates. Combine them into one or two documents (for example a plan and a screen inventory) rather than one file per template: the reader wants one handoff, and each extra file costs time to write and to read. Use the templates as checklists for what to cover, not as files to produce. - Spec: one
screen-specificationper screen,component-specificationfor any new component. - Build: the code change, then a short note: what changed (files), states covered, checks run with results, and anything not verified.
- Audit: a
quality-assessmentreport with prioritized findings. - Release:
checklists/release-readiness.mdfilled in, with blockers first.
Write documents into the project's existing docs folder if there is one (for example docs/), otherwise ask or present them in the reply. Keep reports specific to the app: "The Orders list has no empty state (src/screens/Orders.tsx:88 renders an empty FlatList)" is useful; "consider adding empty states" is not.
Reference map
| File | Read when |
|---|---|
references/screen-inventory.md | Discovering screens or judging which ones an app needs |
references/ui-states.md | Specifying or building any data-driven screen, form, or async action |
references/design-system.md | Defining tokens, theming, building or reviewing components |
references/navigation-standards.md | Structuring navigation, auth gating, deep links, back behavior |
references/interaction-patterns.md | Lists, gestures, forms, keyboard, haptics, motion |
references/accessibility-standards.md | Building any UI; accessibility review |
references/security-standards.md | Auth, sessions, storage, permissions, sensitive screens, payments |
references/production-readiness.md | Performance, reliability, monitoring, store submission |