Mobile Platform Guidelines
Turn platform knowledge into explicit product decisions and testable checks. Preserve outcome parity while allowing implementation and interaction differences between iOS and Android.
Select the platform mode
- iOS: use the iOS reference and check navigation, safe areas, Dynamic Type, VoiceOver, Reduce Motion, keyboard, permissions, and system surfaces.
- Android: use the Android reference and check predictive Back, edge-to-edge insets, scalable text, TalkBack, adaptive layouts, process recreation, and Material/custom behavior.
- Cross-platform: review shared user outcomes and record where behavior must diverge.
Read the existing first-party references before making a claim:
For products whose core value depends on device motion, audio, or haptics, also read sensor, audio, and haptic behavior. Treat hardware availability, permission, interruption, route change, and a visible non-sensor alternative as required product states.
Recheck the linked official documentation before version-specific claims. Record the documentation date, OS/version scope, and whether a conclusion is observed, derived, or not-tested.
Run the review
- Establish target OS versions, form factors, input modes, appearance, text-size settings, and relevant system integrations.
- Map each platform rule to a screen, state, flow, component, or system surface.
- Separate product outcome parity from implementation parity; do not force identical navigation or permission behavior.
- Mark each check
pass,fail,not-tested, ornot-applicable. A screenshot can support visible layout evidence but cannot prove runtime semantics. - Give every failure an owner, workaround/fallback, and verification method.
Create:
platform-review.mdusing assets/platform-review-template.md.platform-guidelines.jsonusing assets/platform-guidelines-template.json and references/platform-guidelines-schema.md.
Run python3 scripts/validate_platform_guidelines.py <path-to-platform-guidelines.json> and fix structural errors. Keep runtime checks untested until a device or executable prototype supplies evidence.
Enforce the output order
- Platform scope and source freshness.
- Outcome-parity contract.
- Rule/check matrix by platform and area.
- Fallbacks, risks, and device test plan.
- Decision, open questions, and confidence.
Do not label a design “native” from visual resemblance alone.


