React Native TV UI Best Practices

This skill helps an agent review or build React Native TV UI across tvOS, Android TV, Fire TV, and Vega OS. Use it when the user asks to audit a TV app, fix focus or D-pad issues, or build common TV components (swimlanes, hero banners, drawers, tabs, modals, focus traps, search/auth flows). The references cover focus management, layout patterns, typography & contrast, input handling, and Vega-specific gotchas — pick the relevant one rather than reading them all. Anything that requires a TV at viewing distance (overscan, contrast under HDR, animation feel, 10-foot legibility) the agent flags for human verification rather than performing.

TV UX differs from mobile in ways the agent should keep in mind across every reference. Users sit ~10ft from the screen with a 9-button remote — no touch, no gestures. Focus moves along directional axes; navigation is linear. Type that's legible at phone distance is invisible at couch distance. Pure black/white looks sharp on a phone but blooms on HDR TVs. Animations carry meaning (signalling focus or direction) rather than decorating a touch. The reference files apply these constraints to specific surfaces — focus, layout, typography, input — so the agent doesn't need to reason about TV-vs-mobile differences each time.

Check before applying rules

1. Runtime. package.json will list react-native-tvos (→ tvOS + Android TV) or @amazon-devices/react-native-kepler (→ Vega). A monorepo may have both, scoped per package.
2. Confirm it's a TV app. No Platform.isTV and no TV runtime in deps → skill doesn't apply.

For Vega, defer to the live Amazon docs for API specifics. This skill only covers the non-obvious cross-runtime gotchas — see vega-specifics.md.

Static helper

node references/scripts/audit.js src runs grep-style checks across all four sections (focus, input, layout, typography). Section selectable via --only / --skip. Zero deps, exits 1 on findings.

It's a helper, not a full review. It only catches statically detectable patterns — most rules in the reference files require judgement, hardware, or human review and won't be caught regardless of how clean the audit runs. Read each match in context.