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 performancenav-*: D-pad navigation, Back/Menu behavior, keyboard/search inputdesign-*: 10-foot typography, layout, color, focus visibilityperf-*: startup, memory, lists, animation, and network constraints on TV hardwarevideo-*: playback architecture, DRM/protocol selection, debugginga11y-*: TV accessibility implementation and audit checkssetup-*: stack detection, setup, architecture, cross-platform behaviortest-* 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 |
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.
1---2name: react-native-tv-best-practices3description: Reviews React Native TV apps for focus/D-pad navigation, 10-foot UI layout, TV playback/DRM integration, low-memory TV performance, and TV accessibility. Use when building, debugging, or reviewing react-native-tvos, Expo TV, Amazon Vega/Kepler, or React Native web TV targets where the issue depends on remote input, TV focus, TV packaging, TV hardware, or TV playback constraints.4license: MIT5---6
7# React Native TV Best Practices
8
9## Overview
10
11TV-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.
12
13Use 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](../react-native-best-practices/SKILL.md).
14
15## Skill Format
16
17Reference files are grouped by topic prefix:
18
19- `focus-*`: focus engines, focus guides, focus event performance
20- `nav-*`: D-pad navigation, Back/Menu behavior, keyboard/search input
21- `design-*`: 10-foot typography, layout, color, focus visibility
22- `perf-*`: startup, memory, lists, animation, and network constraints on TV hardware
23- `video-*`: playback architecture, DRM/protocol selection, debugging
24- `a11y-*`: TV accessibility implementation and audit checks
25- `setup-*`: stack detection, setup, architecture, cross-platform behavior
26- `test-*` and `release-*`: test coverage, E2E, and CI/release workflows
27
28## When to Apply
29
30Apply this skill when the app targets a TV platform and the work involves:
31
32- Focus movement, visible focus, focus restoration, or remote/D-pad input
33- TV layout readability, overscan/safe areas, or 10-foot UI density
34- TV player controls, manifests, DRM, decoder support, or playback errors
35- Performance on low-memory TV hardware, especially with video or large carousels
36- TV accessibility with screen readers, captions, focus order, or remote-only interaction
37- Platform setup for `react-native-tvos`, Expo TV, Amazon Vega/Kepler, Tizen, or webOS
38
39## Before You Start — Identify the TV Stack
40
41This 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.
42
43| Stack | How to detect | Setup expectations |
44| ----------------------------------------------------- | ------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------ |
45| **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 |
46| **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 |
47| **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 |
48| **Web-based TV** (Tizen, webOS) | web bundler (Rsbuild/webpack) + platform packaging; spatial-nav library | Platform SDK packaging; `@noriginmedia/norigin-spatial-navigation` for focus |
49
50The focus, 10-foot design, performance, accessibility, and player guidance applies across all of these — only the **setup/build** expectations are stack-specific.
51
52## Review Rules
53
54- Resolve the target stack before setup advice.
55- Prefer natural focus order and focus guides before imperative focus calls or broad `nextFocus*` maps.
56- Treat focus loss, invisible focus, and broken Back/Menu behavior as navigation bugs.
57- Check readability, safe areas, and focus states at TV distance before tuning visual details.
58- Profile on the weakest supported TV device before reporting performance fixes as complete.
59- Separate playback failures by layer: manifest request, DRM license exchange, decoder capability, player state, and React UI controls.
60
61## Priority-Ordered Guidelines
62
63| Priority | Category | Impact | Prefix |
64|----------|----------|--------|--------|
65| 1 | Focus and D-pad navigation | CRITICAL | `focus-*`, `nav-*` |
66| 2 | List, animation, and input performance | CRITICAL | `perf-*` |
67| 3 | Playback and DRM failures | HIGH | `video-*` |
68| 4 | 10-foot readability and layout | HIGH | `design-*` |
69| 5 | TV accessibility | HIGH | `a11y-*` |
70| 6 | Stack setup, testing, and release | MEDIUM | `setup-*`, `test-*`, `release-*` |
71
72## Quick Reference
73
741. Detect the TV stack from package files, manifests, native folders, and platform tooling.
752. Reproduce navigation with the remote or D-pad path, not mouse/touch assumptions.
763. Confirm the focused element is always visible, reachable, and restored after modals/routes.
774. Check playback failures from the network/DRM layer upward before changing React controls.
785. Measure list, animation, memory, and startup work on the weakest supported TV target.
79
80## References
81
82### Focus and Navigation
83
84| File | Impact | Description |
85|------|--------|-------------|
86| [focus-management.md](references/focus-management.md) | CRITICAL | Focus engines, focus guides, `nextFocus*`, and focus restoration |
87| [focus-performance.md](references/focus-performance.md) | CRITICAL | Avoiding frame drops from focus event handling |
88| [nav-directional.md](references/nav-directional.md) | CRITICAL | Directional navigation rules across TV platforms |
89| [nav-patterns.md](references/nav-patterns.md) | CRITICAL | Global/local navigation, modals, tabs, and Back behavior |
90| [nav-keyboard.md](references/nav-keyboard.md) | MEDIUM | Search and text input with remotes |
91
92### Design
93
94| File | Impact | Description |
95|------|--------|-------------|
96| [design-10foot.md](references/design-10foot.md) | HIGH | 10-foot review heuristics |
97| [design-typography.md](references/design-typography.md) | HIGH | TV type sizing and readability |
98| [design-layout.md](references/design-layout.md) | HIGH | Safe areas, spacing, carousels, and focus room |
99| [design-color.md](references/design-color.md) | MEDIUM | Contrast and TV display color constraints |
100
101### Performance
102
103| File | Impact | Description |
104|------|--------|-------------|
105| [perf-overview.md](references/perf-overview.md) | HIGH | TV performance targets and profiling order |
106| [perf-lists.md](references/perf-lists.md) | CRITICAL | Virtualized rows and poster-heavy lists |
107| [perf-animations.md](references/perf-animations.md) | CRITICAL | Focus and transition animation performance |
108| [perf-memory.md](references/perf-memory.md) | HIGH | Low-memory TV crashes and image/video pressure |
109| [perf-network.md](references/perf-network.md) | HIGH | Remote input, request stalls, and network resilience |
110
111### Video, Accessibility, Setup, Testing
112
113| File | Impact | Description |
114|------|--------|-------------|
115| [video-streaming.md](references/video-streaming.md) | HIGH | TV platform protocol/DRM selection |
116| [video-players.md](references/video-players.md) | HIGH | Player choices and custom controls |
117| [video-debugging.md](references/video-debugging.md) | HIGH | Manifest, DRM, codec, and playback debugging |
118| [a11y-overview.md](references/a11y-overview.md) | MEDIUM | TV-specific accessibility differences |
119| [a11y-implementation.md](references/a11y-implementation.md) | HIGH | Accessible labels, roles, live regions, and focus |
120| [a11y-checklist.md](references/a11y-checklist.md) | MEDIUM | Launch accessibility audit checklist |
121| [setup-getting-started.md](references/setup-getting-started.md) | MEDIUM | `react-native-tvos` and Expo TV setup |
122| [setup-cross-platform.md](references/setup-cross-platform.md) | MEDIUM | Platform detection and cross-platform caveats |
123| [setup-architecture.md](references/setup-architecture.md) | MEDIUM | Code sharing and project structure |
124| [test-strategy.md](references/test-strategy.md) | MEDIUM | TV testing scope and coverage split |
125| [test-javascript.md](references/test-javascript.md) | MEDIUM | JS-level remote/focus test helpers |
126| [test-e2e.md](references/test-e2e.md) | MEDIUM | Appium and TV E2E coverage |
127| [release-cicd.md](references/release-cicd.md) | MEDIUM | CI, build fingerprinting, and release checks |
128
129## Problem → Skill Mapping
130
131| Symptom | Start Here |
132| ------------------------------------ | ---------------------------------------------------------------------------- |
133| "Focus jumps to wrong element" | [focus-management.md](references/focus-management.md) → Debugging section |
134| "App freezes when scrolling lists" | [perf-lists.md](references/perf-lists.md) → Virtualization |
135| "Animations stutter on Fire TV" | [perf-animations.md](references/perf-animations.md) → Native driver |
136| "Text too small on TV" | [design-typography.md](references/design-typography.md) → Minimum sizes |
137| "Video won't play / DRM errors" | [video-streaming.md](references/video-streaming.md) → DRM section |
138| "Screen reader skips elements" | [a11y-implementation.md](references/a11y-implementation.md) → Roles & labels |
139| "Back button doesn't work right" | [nav-patterns.md](references/nav-patterns.md) → Back navigation |
140| "Keyboard covers content" | [nav-keyboard.md](references/nav-keyboard.md) → Built-in vs custom |
141| "App takes forever to start" | [perf-overview.md](references/perf-overview.md) → Startup time |
142| "Images causing memory crashes" | [perf-memory.md](references/perf-memory.md) → Image optimization |
143| "CI pipeline takes hours" | [release-cicd.md](references/release-cicd.md) → Fingerprinting |
144| "How to share code across platforms" | [setup-architecture.md](references/setup-architecture.md) → Code sharing |
145
146## Security (TV-Specific)
147
148General dependency/input hygiene applies as in any RN app; the TV-specific deltas worth calling out:
149
150- Never embed FairPlay/Widevine/PlayReady keys in client code — treat the license server as the trust boundary and keep DRM tokens server-issued.
gabrielmoreira