React Native Tv Best Practices

CallstackOfficialPublished by Callstack

Skill
Guidelines
Software development
MIT
No issues found

From the author

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.

— the description by Callstack

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://autogineer.com/agent-skills/callstackincubator/react-native-tv-best-practices/download

Unzip 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 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

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/a11y-checklist.md

title: Accessibility Checklist for TV Apps impact: MEDIUM tags: accessibility, checklist, screen-reader, captions, focus, tv

Accessibility Checklist for TV Apps

Pre-launch checklist for remote-only navigation, TV screen readers, captions, and focus-visible UI.

[ ] All interactive elements reachable via D-pad or remote
[ ] Focus moves logically (left→right, top→bottom)
[ ] Focus is visible and clearly indicated (highlight or border)
[ ] No "focus traps" — areas where focus gets stuck or lost
[ ] Back button behaves consistently and predictably
[ ] Menus and modals trap focus while active and restore on close

[ ] All interactive elements have clear, descriptive labels ("Play Button", "Episode 2: Stranger Things")
[ ] Dynamic content changes announced via accessibilityLiveRegion
[ ] Screen reader correctly reads button states (selected, disabled)
[ ] Non-text elements (icons, images) have appropriate alt text/labels
[ ] Dialogs ("Are you still watching?") announced and navigable via screen reader

3. Visual Design & Contrast

[ ] Text size large enough for TV viewing (>18px minimum)
[ ] Text and interactive elements ≥4.5:1 contrast ratio against background
[ ] Focus indicators are high contrast and visible from distance
[ ] No overlaid or animated text on busy video backgrounds
[ ] No flashing or strobing elements (seizure risk)

4. Audio & Captions

[ ] Captions/subtitles available for all video content
[ ] Captions customizable: size, color, background
[ ] Audio descriptions available and easy to enable/disable
[ ] Action feedback ("Added to Watchlist") provided visually AND audibly
[ ] Autoplay previews can be paused or disabled by user

5. Search & Content Discovery

[ ] On-screen keyboard fully navigable with remote/D-pad
[ ] Search suggestions readable and selectable via focus
[ ] Search results announced to screen readers or at least navigable
[ ] Search input has visible label or hint ("Search for shows or movies")

6. Dynamic Content & Live Updates

[ ] New content in carousels/rows/lists is announced or focusable
[ ] Lazy-loaded content doesn't reset or lose focus state
[ ] Infinite scroll has clear separators/headings between content types
[ ] Row headers ("Recommended", "Trending Now") announced as landmarks

7. Interactive Features (Like, Rate, Watchlist)

[ ] Like/dislike/watchlist buttons focusable and labeled clearly
[ ] Button states (liked, saved) announced to screen readers
[ ] Confirmation messages both visual and accessible
[ ] All icons (heart, star, thumb) have text equivalents

8. Testing & Platform-Specific

[ ] Agent smoke-tested after loading the agent-device skill and reading agent-device help workflow; verified exposed labels, roles, states, focus, and modal focus behavior
[ ] Manually tested spoken output on platform screen readers (TalkBack, VoiceOver, VoiceView) before release
[ ] Reviewed against platform accessibility guidelines (tvOS HIG, Android TV UI)

9. Settings & User Control

[ ] Accessibility settings (captions, audio description, high contrast) easily accessible
[ ] Autoplay previews and audio can be disabled
[ ] Users can control text size, color themes, contrast where supported
[ ] App respects system-wide accessibility settings

10. Avoid These Common Mistakes

[ ] No unlabeled buttons or icons ("button1")
[ ] No focus on non-interactive elements (static labels)
[ ] No inaccessible custom components (carousels without keyboard support)
[ ] No functionality requiring complex remote combos or gestures only

Testing Tools

Tool	Type	Notes
agent-device	Agent-run	Load the `agent-device` skill and read `agent-device help workflow`, then inspect accessibility tree, focused elements, labels, roles, states, and modal focus behavior
TalkBack	Manual	Android TV, Fire TV
VoiceOver	Manual	Apple TV
React Native Testing Library	Integration	Test accessibility props/labels
Accessibility Inspector	Manual	Xcode (tvOS)

a11y-overview.md — Accessibility fundamentals
a11y-implementation.md — Implementation details
design-color.md — Color contrast guidelines

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

2026-11-09

AutoGineer is not affiliated with or endorsed by Callstack or Callstack.

Download ZIP

The ZIP holds the skill’s files, its licence files and an ATTRIBUTION.md. Download react-native-tv-best-practices.zip