react-native-tv-best-practices

от callstackincubator

Проверяет приложения React Native TV на предмет навигации с помощью фокуса/D-pad, макета интерфейса для 10-футового экрана, интеграции воспроизведения/DRM для ТВ, производительности на ТВ с низким объемом памяти и доступности для ТВ. Используйте…

npx skills add https://github.com/callstackincubator/agent-skills --skill react-native-tv-best-practices

Скачать ZIP GitHub

1.6k

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

Detect the TV stack from package files, manifests, native folders, and platform tooling.
Reproduce navigation with the remote or D-pad path, not mouse/touch assumptions.
Confirm the focused element is always visible, reachable, and restored after modals/routes.
Check playback failures from the network/DRM layer upward before changing React controls.
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