React Native Tv Best Practices
CallstackOfficialPublished by Callstack
- Skill
- Guidelines
- Software development
- MIT
- No issues found
AutoGineer summary
Written by AutoGineer from the skill’s own files, not by the author
This skill provides a comprehensive set of best practices for building, testing, and debugging React Native applications on TV platforms, including Apple TV, Android TV, Fire TV, and web-based targets. It focuses on the unique challenges of the 10-foot UI, such as remote-based D-pad navigation, focus management, TV-specific performance constraints, and accessibility requirements. The guidance helps developers navigate the differences between various TV stacks like react-native-tvos and Amazon Vega/Kepler.
What it does
- Provides heuristics for 10-foot UI design, typography, and layout.
- Offers strategies for managing focus engines and D-pad navigation.
- Details performance optimization for low-memory TV hardware.
- Outlines requirements for TV-specific accessibility and screen reader support.
- Explains how to handle video playback, DRM, and player controls.
- Guides developers on identifying and setting up the correct TV platform stack.
When to use it
- When building or debugging navigation issues related to remote inputs.
- When optimizing app performance for low-memory TV devices.
- When implementing accessibility features for TV screen readers.
- When troubleshooting video playback or DRM integration errors.
- When designing layouts for 10-foot viewing distances.
Advantages
- Reduces platform-specific bugs by providing clear stack-detection rules.
- Improves user experience through consistent focus and navigation patterns.
- Helps meet accessibility standards required for TV app store approval.
- Provides actionable debugging paths for common TV-specific failures.
Usage examples
- “How do I fix focus jumping to the wrong element in my React Native TV app?”
- The agent will guide you to use focus-management.md, recommending the use of TVFocusGuideView for shared focus paths and advising against imperative focus overrides.
- “My app crashes on Fire TV when scrolling through a long list of posters. What should I check?”
- The agent will point you to perf-lists.md and perf-memory.md to implement proper virtualization and optimize image memory usage for low-memory hardware.
Install
Download the skill as a ZIP:
https://mp-staging.autogineer.com/agent-skills/callstackincubator/react-native-tv-best-practices/downloadUnzip it into the cross-client skills folder of your project:
mkdir -p .agents/skills && unzip react-native-tv-best-practices.zip -d .agents/skills
Documentation by Callstack
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-*andrelease-*: 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.
Files
- ATTRIBUTION.mdAdded by AutoGineer879 B
- LICENSELicence file added by AutoGineer1.1 KiB
- SKILL.md10.9 KiB
- agents/openai.yaml307 B
- references/a11y-checklist.md4.3 KiB
- references/a11y-implementation.md4.4 KiB
- references/a11y-overview.md2.8 KiB
- references/design-10foot.md3.0 KiB
- references/design-color.md3.8 KiB
- references/design-layout.md3.0 KiB
- references/design-typography.md2.6 KiB
- references/focus-management.md6.4 KiB
- references/focus-performance.md3.5 KiB
- references/nav-directional.md3.6 KiB
- references/nav-keyboard.md3.6 KiB
- references/nav-patterns.md4.4 KiB
- references/perf-animations.md3.0 KiB
- references/perf-lists.md3.3 KiB
- references/perf-memory.md2.5 KiB
- references/perf-network.md2.7 KiB
- references/perf-overview.md3.6 KiB
- references/release-cicd.md3.2 KiB
- references/setup-architecture.md3.8 KiB
- references/setup-cross-platform.md3.3 KiB
- references/setup-getting-started.md5.1 KiB
- references/test-e2e.md3.6 KiB
- references/test-javascript.md3.7 KiB
- references/test-strategy.md2.3 KiB
- references/video-debugging.md1.6 KiB
- references/video-players.md3.2 KiB
- references/video-streaming.md2.1 KiB
references/design-10foot.md
title: The 10-Foot Experience impact: HIGH tags: 10-foot, tv-design, remote, feedback, shared-screen
The 10-Foot Experience
TV UIs are viewed from ~3 m (10 ft) with a D-pad remote, not 30 cm with a touchscreen. This file covers the TV-specific design concerns that follow from that distance and input model. For the concrete numbers, defer to the focused references:
Text sizing for distance → design-typography.md
Safe zones, spacing, grids → design-layout.md
Contrast and color on TV panels → design-color.md
Focus movement and modal focus traps → focus-management.md
Directional navigation rules → nav-directional.md
Quick Reference
Design for legibility at 3 m; verify by testing from a couch with a remote, not at a desk with a keyboard.
Acknowledge every remote press with a visual cue within ~100 ms.
Keep focus/transition animations under 200 ms so they never delay the next input.
Treat the TV as a shared device — don't expose personal data by default.
Input Latency and Feedback
TV hardware and remotes add ~100–200 ms between a button press and the on-screen response. Mask that latency, don't add to it:
Show a focus cue (highlight, ~3–5% scale, or border) within ~100 ms of every press.
Keep focus and transition animations under 200 ms; an animation that outlasts the next press is too long.
Use motion only to reinforce direction or highlight focus changes — never decorative sequences that block input.
Shared Screen Considerations
TVs are shared among family, roommates, and guests — design for that:
Don't display account email, payment details, or other personal data unless the action requires it.
Make profile switching reachable within 2 D-pad presses from the home screen.
Show a confirmation step for voice-entered text before submitting it.
Auto-dismiss subtitles, overlays, and menus on a timer once they've served their purpose.
Couch Test Checklist
Test each completed screen from the intended viewing position (couch, remote, ~3 m). Each step is pass/fail:
Reach the first Play action from the home screen in ≤3 D-pad presses.
Return to the starting screen using only the Back button.
After every directional press, focus lands on a visible element (no off-screen or lost focus).
Every press produces a visible cue within ~100 ms.
Screen remains legible with room lights both on and off.
If a step fails, reduce the number of focusable elements or realign the layout before adding manual nextFocus* overrides.
Related Skills
design-layout.md — Layout patterns, safe zones, component design
design-typography.md — Text sizing for distance
design-color.md — Contrast and color for TV displays
focus-management.md — Focus engine, traps, restoration
Requirements and compatibility
Works with: Claude Code, Claude apps, OpenAI Codex, GitHub Copilot, Cursor, Gemini CLI, Kiro, OpenCode, Goose, Amp, Roo Code, JetBrains Junie, Factory Droid, Devin (ex-Windsurf), Mistral Vibe, OpenHands, Letta
“Works with” means the tool reads the open Agent Skills format; a skill written for one tool may use features others lack.
Security
No issues found by our static scan· No issues found
A static scan is not a guarantee. Skills are third-party content: review a skill before you let an agent use it.
Attribution and licence
- Published by
- Callstack
- Publisher
- Callstack (Official)
- Source
- callstackincubator/agent-skills · skills/react-native-tv-best-practices · commit 59e9d17
- Licence
- MIT License (redistribution allowed)
- LICENSE (added by AutoGineer from LICENSE)
- ATTRIBUTION.md (written by AutoGineer)
- Synced
AutoGineer is not affiliated with or endorsed by Callstack.
Related skills
Web Artifacts Builder
AnthropicOfficial
A structured workflow for developing and bundling complex, multi-component React artifacts for Claude.
Software developmentClaude CodeClaude appsOpenAI Codex+14 moreApache-2.0Medium riskHas scriptsGitHub stars of the source repository188.6k
Frontend UI Engineering
Addy Osmani· Community
Engineering standards for building accessible, responsive, and production-ready frontend user interfaces.
Software developmentClaude CodeClaude appsOpenAI Codex+14 moreMITGitHub stars of the source repository113.9k
Ask Sonner
Emil Kowalski· Community
A comprehensive guide for implementing, styling, and troubleshooting the Sonner toast notification library in React applications.
Software developmentClaude CodeClaude appsOpenAI Codex+14 moreMITGitHub stars of the source repository54.3k
Pick UI Library
Emil Kowalski· Community
Get recommendations for frontend UI libraries based on a curated, opinionated list.
Software developmentClaude CodeClaude appsOpenAI Codex+14 moreMITGitHub stars of the source repository54.3k
Animate Expo
Emil Kowalski· Community
A senior mobile engineering guide for building React Native and Expo animations that feel correct on real devices.
Software developmentClaude CodeClaude appsOpenAI Codex+14 moreMITGitHub stars of the source repository54.3k
Prototype
Emil Kowalski· Community
A design engineering workflow for building and comparing distinct UI variants using an isolated picker harness.
Software developmentClaude CodeClaude appsOpenAI Codex+14 moreMITGitHub stars of the source repository54.3k
Download ZIP
The ZIP holds the skill’s files, its licence files and an ATTRIBUTION.md. Download react-native-tv-best-practices.zip