# Platform Interaction Guidance

Platform conventions encode learned behavior, device constraints, and accessibility integration. Start from the target platform's current guidance, keep the product's task language and brand consistent, and adapt navigation chrome, input, and component behavior to each environment. Verify implementation details in primary documentation:

- [Apple Human Interface Guidelines](https://developer.apple.com/design/human-interface-guidelines/)
- [Material Design 3](https://m3.material.io/)
- [Microsoft Fluent 2](https://fluent2.microsoft.design/)
- [WCAG 2.2](https://www.w3.org/TR/WCAG22/)
- [MDN responsive design](https://developer.mozilla.org/en-US/docs/Learn_web_development/Core/CSS_layout/Responsive_Design)

## Navigation and information architecture

Keep information architecture and task names stable across platforms while adapting the navigation surface:

| Environment | Starting pattern | Contract to preserve |
|---|---|---|
| Web | URL-addressable top navigation or sidebar; optional command palette as an accelerator | Browser history, deep links, open-in-new-tab, scroll restoration, and a visible non-command navigation path |
| iOS/iPadOS | Navigation stack plus a tab bar for a small set of top-level destinations | System Back behavior, edge-swipe navigation where supported, sheet dismissal, and state restoration |
| Android | Navigation bar/rail/drawer selected for available width | System Back and predictive-back behavior, correct task back stack, and system-bar integration |
| Desktop | Menus, sidebars/toolbars, resizable windows, and documented shortcuts | Platform window controls, keyboard reachability, selection, copy/paste, undo, and persistent document state |
| TV/remote | Shallow hierarchy with directional focus | Deterministic next focus, visible focus, Back behavior, and reachable media/accessibility controls |

Do not force identical chrome across platforms. A bottom tab bar on iOS and an adaptive navigation rail on a wide Android layout can express the same architecture. Brand belongs in semantic color, typography, iconography, illustration, and motion tokens; it does not justify replacing a learned system gesture or control behavior.

Command palettes, gestures, and search are accelerators, not substitutes for discoverable structure. Every key destination needs a visible path. Modals and sheets are temporary task surfaces, not primary navigation containers. Preserve user position and entered state when Back returns to a previous surface unless privacy or explicit reset behavior requires otherwise.

## Safe areas and adaptive layout

- Consume platform-provided insets rather than hard-coding notch, status-bar, home-indicator, hinge, or window-control dimensions.
- On Apple platforms, use safe-area APIs and test Dynamic Type at large sizes. For edge-to-edge web content on iOS, use the documented viewport and `env(safe-area-inset-*)` behavior only after testing the actual browser/WebView.
- On Android, use current window-inset APIs and test edge-to-edge layouts with gesture navigation, three-button navigation where supported, display cutouts, and increased font scale.
- On the web, prefer content-led breakpoints, flexible layout primitives, and modern viewport units (`dvh`, `svh`, `lvh`) when mobile browser chrome affects full-height surfaces. Keep zoom and reflow enabled.
- On tablets, foldables, desktop windows, and split view, treat width and input capability as runtime conditions. Do not infer them from a device name or a single design-frame size.

Fixed headers, bottom actions, and overlays must reserve space so content and focused controls are never hidden beneath them. Test portrait, landscape, narrow split view, wide window, long localized labels, 200% browser zoom, and large system text. Reflow should preserve task order rather than merely shrink desktop chrome.

## Input, gestures, and focus

Every primary action needs an input-independent semantic control. Dragging, swiping, long-pressing, device motion, hover, and fine pointer movement require a visible alternative. Never disable browser zoom, text selection, context menus, paste, or password-manager behavior to protect a visual treatment.

- Preserve operating-system and assistive-technology shortcuts. Product shortcuts must be documented, discoverable, and remappable when the platform supports it.
- Ensure pointer interactions work from the keyboard; content revealed on hover must also appear on focus or activation.
- Keep touch/click targets large enough for the target platform and separate adjacent destructive actions. Test actual hit areas, not only visible glyph dimensions.
- For remote and gamepad input, define directional focus order explicitly and keep the active item visible while scrolling.
- For custom gestures near system-reserved edges, prefer moving the product gesture or adding a visible control. Do not assume an application can override the operating system.
- On route, sheet, and menu transitions, move focus according to the interaction contract: preserve sequential Tab order, return focus after explicit dismissal where required, and place screen-reader focus at the new task heading when navigation replaces the page.

## Accessibility and motion

Use native semantic controls and platform accessibility APIs before custom gesture recognizers or canvas-only interaction. Verify accessible name, role, value/state, reading order, keyboard order, and announced updates with the platform's real assistive technology.

Support text scaling, browser zoom/reflow, high-contrast or forced-color modes, reduced motion, captions, audio description where media requires it, and keyboard/switch access. Do not encode meaning through color, position, motion, or haptics alone. When reduced motion is requested, remove nonessential spatial travel and parallax; preserve necessary state feedback using immediate changes or restrained fades.

Cross-platform frameworks do not make accessibility behavior identical. Test VoiceOver on Apple targets, TalkBack and switch access on Android targets, supported screen readers and forced colors on Windows/web, and keyboard-only operation in every desktop-capable environment. A responsive browser preview is not evidence for native safe-area, Back, focus, or accessibility behavior.

## Verification matrix

Record evidence for the platform/input combinations that are in scope:

| Area | Minimum evidence |
|---|---|
| Navigation | Forward/back/deep-link paths, state restoration, and an unavailable-destination state |
| Layout | Small and large viewport, rotation/resize, safe areas, long content, localization, and text scaling |
| Input | Touch or pointer, keyboard, screen reader, and any product-specific gesture/remote path |
| Overlays | Open, Escape/Back dismissal, Tab behavior, focus restoration, scroll locking, and unsaved-change handling |
| System settings | Dark/light theme, high contrast or forced colors, reduced motion, and increased text size |
| Failure states | Offline/timeout/permission denial with a clear recovery path and no lost user input |

An intentional platform deviation must record the user need, affected platforms and input modes, accessibility impact, visible fallback, and test evidence. Aesthetic preference alone is not sufficient justification.