react-native-tv-best-practices

Overview

TV-specific review guidance for React Native-backed apps on Apple TV, Android TV, Fire TV, Amazon Vega/Kepler, and web-based TV targets such as Tizen or webOS.

Use this skill only for TV deltas: remote input, focus engines, 10-foot layout, platform packaging, playback/DRM, low-memory TV hardware, and TV accessibility. For ordinary React Native performance or architecture issues, use react-native-best-practices.

Skill Format

Reference files are grouped by topic prefix:

• focus-*: focus engines, focus guides, focus event performance
• nav-*: D-pad navigation, Back/Menu behavior, keyboard/search input
• design-*: 10-foot typography, layout, color, focus visibility
• perf-*: startup, memory, lists, animation, and network constraints on TV hardware
• video-*: playback architecture, DRM/protocol selection, debugging
• a11y-*: TV accessibility implementation and audit checks
• setup-*: stack detection, setup, architecture, cross-platform behavior
• test-* and release-*: test coverage, E2E, and CI/release workflows

When to Apply

Apply this skill when the app targets a TV platform and the work involves:

• Focus movement, visible focus, focus restoration, or remote/D-pad input
• TV layout readability, overscan/safe areas, or 10-foot UI density
• TV player controls, manifests, DRM, decoder support, or playback errors
• Performance on low-memory TV hardware, especially with video or large carousels
• TV accessibility with screen readers, captions, focus order, or remote-only interaction
• Platform setup for react-native-tvos, Expo TV, Amazon Vega/Kepler, Tizen, or webOS

Before You Start — Identify the TV Stack

This skill covers several TV stacks. Detect which one the app targets before flagging setup issues — demanding react-native-tvos, a tvOS Podfile, or an Android TV manifest on a Vega/Kepler or web-based TV app produces false positives.

Stack	How to detect	Setup expectations
react-native-tvos (Apple TV, Android TV, Fire TV)	"react-native": "npm:react-native-tvos@…" in package.json	tvOS Podfile (platform :tvos); Android TV leanback/LEANBACK_LAUNCHER manifest entries; TV emulator/simulator
Expo + react-native-tvos	above plus @react-native-tvos/config-tv in app.json	EXPO_TV=1 prebuild; react-native-tvos version must match the Expo SDK; not all Expo features/libraries are available on TV
Amazon Vega / Kepler	Vega/Kepler SDK & tooling (@amazon-devices/* deps, Kepler manifest); no react-native-tvos	Amazon's Vega/Kepler toolchain — react-native-tvos, tvOS Podfile, and Android TV manifest do not apply
Web-based TV (Tizen, webOS)	web bundler (Rsbuild/webpack) + platform packaging; spatial-nav library	Platform SDK packaging; @noriginmedia/norigin-spatial-navigation for focus

The focus, 10-foot design, performance, accessibility, and player guidance applies across all of these — only the setup/build expectations are stack-specific.

Review Rules

• Resolve the target stack before setup advice.
• Prefer natural focus order and focus guides before imperative focus calls or broad nextFocus* maps.
• Treat focus loss, invisible focus, and broken Back/Menu behavior as navigation bugs.
• Check readability, safe areas, and focus states at TV distance before tuning visual details.
• Profile on the weakest supported TV device before reporting performance fixes as complete.
• Separate playback failures by layer: manifest request, DRM license exchange, decoder capability, player state, and React UI controls.

Priority-Ordered Guidelines

Priority	Category	Impact	Prefix
1	Focus and D-pad navigation	CRITICAL	focus-*, nav-*
2	List, animation, and input performance	CRITICAL	perf-*
3	Playback and DRM failures	HIGH	video-*
4	10-foot readability and layout	HIGH	design-*
5	TV accessibility	HIGH	a11y-*
6	Stack setup, testing, and release	MEDIUM	setup-*, test-*, release-*

Quick Reference

1. Detect the TV stack from package files, manifests, native folders, and platform tooling.
2. Reproduce navigation with the remote or D-pad path, not mouse/touch assumptions.
3. Confirm the focused element is always visible, reachable, and restored after modals/routes.
4. Check playback failures from the network/DRM layer upward before changing React controls.
5. Measure list, animation, memory, and startup work on the weakest supported TV target.

References

Focus and Navigation

File	Impact	Description
focus-management.md	CRITICAL	Focus engines, focus guides, nextFocus*, and focus restoration
focus-performance.md	CRITICAL	Avoiding frame drops from focus event handling
nav-directional.md	CRITICAL	Directional navigation rules across TV platforms
nav-patterns.md	CRITICAL	Global/local navigation, modals, tabs, and Back behavior
nav-keyboard.md	MEDIUM	Search and text input with remotes

Design

File	Impact	Description
design-10foot.md	HIGH	10-foot review heuristics
design-typography.md	HIGH	TV type sizing and readability
design-layout.md	HIGH	Safe areas, spacing, carousels, and focus room
design-color.md	MEDIUM	Contrast and TV display color constraints

Performance

File	Impact	Description
perf-overview.md	HIGH	TV performance targets and profiling order
perf-lists.md	CRITICAL	Virtualized rows and poster-heavy lists
perf-animations.md	CRITICAL	Focus and transition animation performance
perf-memory.md	HIGH	Low-memory TV crashes and image/video pressure
perf-network.md	HIGH	Remote input, request stalls, and network resilience

Video, Accessibility, Setup, Testing

File	Impact	Description
video-streaming.md	HIGH	TV platform protocol/DRM selection
video-players.md	HIGH	Player choices and custom controls
video-debugging.md	HIGH	Manifest, DRM, codec, and playback debugging
a11y-overview.md	MEDIUM	TV-specific accessibility differences
a11y-implementation.md	HIGH	Accessible labels, roles, live regions, and focus
a11y-checklist.md	MEDIUM	Launch accessibility audit checklist
setup-getting-started.md	MEDIUM	react-native-tvos and Expo TV setup
setup-cross-platform.md	MEDIUM	Platform detection and cross-platform caveats
setup-architecture.md	MEDIUM	Code sharing and project structure
test-strategy.md	MEDIUM	TV testing scope and coverage split
test-javascript.md	MEDIUM	JS-level remote/focus test helpers
test-e2e.md	MEDIUM	Appium and TV E2E coverage
release-cicd.md	MEDIUM	CI, build fingerprinting, and release checks

Problem → Skill Mapping

Symptom	Start Here
"Focus jumps to wrong element"	focus-management.md → Debugging section
"App freezes when scrolling lists"	perf-lists.md → Virtualization
"Animations stutter on Fire TV"	perf-animations.md → Native driver
"Text too small on TV"	design-typography.md → Minimum sizes
"Video won't play / DRM errors"	video-streaming.md → DRM section
"Screen reader skips elements"	a11y-implementation.md → Roles & labels
"Back button doesn't work right"	nav-patterns.md → Back navigation
"Keyboard covers content"	nav-keyboard.md → Built-in vs custom
"App takes forever to start"	perf-overview.md → Startup time
"Images causing memory crashes"	perf-memory.md → Image optimization
"CI pipeline takes hours"	release-cicd.md → Fingerprinting
"How to share code across platforms"	setup-architecture.md → Code sharing

Security (TV-Specific)

General dependency/input hygiene applies as in any RN app; the TV-specific deltas worth calling out:

• Never embed FairPlay/Widevine/PlayReady keys in client code — treat the license server as the trust boundary and keep DRM tokens server-issued.