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-color.md
title: Color and Contrast for TV Displays impact: MEDIUM tags: color, contrast, hdr, palette, accessibility, tv-design
Color and Contrast for TV Displays
Color systems that work on phones can wash out or over-glow on TV. Distance, panel technology, ambient light, and HDR all affect how colors appear.
Quick Reference
Aim for ≥4.5:1 contrast ratio for normal text, ≥7:1 for core UI
Avoid pure white (#FFFFFF) on pure black (#000000) for entire screens — causes eye fatigue
Focus indicators need multi-cue: color + border/outline + mild scale
Test in both SDR and HDR modes; ship a palette that works in both
Contrast Ratios
| Context | Minimum Ratio | Notes |
|---|---|---|
| Normal text | ≥ 4.5:1 | WCAG standard |
| Core UI (menus, buttons, captions) | ≥ 7:1 | Holds up on cheap panels and bright rooms |
| Focus indicators | Multi-cue | Color alone fails for color-deficient users |
Color Palette with Contrast Ratios
| Purpose | Color | vs Black | vs Dark Gray (#1a1a1a) | Use Case |
|---|---|---|---|---|
| Primary text | #FFFFFF | 21:1 | 17.8:1 | Body text, headings |
| Secondary text | #E5E5E7 | 18.5:1 | 15.7:1 | Labels, metadata |
| Tertiary text | #A1A1AA | 8.6:1 | 7.3:1 | Timestamps, auxiliary |
| Disabled text | #6B7280 | 4.2:1 | 3.6:1 | Inactive elements (sparingly) |
| Primary accent | #007AFF | 8.2:1 | 7.0:1 | Links, CTAs, selected states |
| Focus border | #00D4FF | 11.3:1 | 9.6:1 | Focus indicators, active |
| Success | #34C759 | 9.8:1 | 8.3:1 | Confirmations, positive |
| Warning | #FF9500 | 7.1:1 | 6.0:1 | Warnings, notices |
| Danger | #FF3B30 | 5.9:1 | 5.0:1 | Errors, destructive actions |
WCAG 1.4.3 requires 4.5:1 for normal text and 3:1 for large text (≥24px, or ≥18.66px bold). The disabled-text row falls below 4.5:1 by design — inactive/disabled UI components are exempt from the contrast minimum. Don't reuse that ratio for active text.
Ambient Light Adaptation
| Environment | Background | Primary Text | Secondary Text | Accent | Min Contrast |
|---|---|---|---|---|---|
| Bright room | #000000 | #FFFFFF | #E5E5E7 | #007AFF | 7:1 |
| Dim room | #1a1a1a | #E5E5E7 | #B3B3B3 | #5AC8FA | 4.5:1 |
| Dark room | #2a2a2a | #D1D1D6 | #8E8E93 | #64D2FF | 3:1 |
The dark-room 3:1 minimum applies to large text and UI components only (WCAG large-text / non-text contrast). Keep body text at 4.5:1 regardless of ambient profile.
HDR Considerations
HDR displays show brighter whites and deeper blacks — great for video, but UI can over-glow:
Keep UI whites around 80-90% luminance — avoid hard #FFFFFF for long-lived text
Watch highlights (focus glow, selection chips) against HDR content — cap intensity to prevent blooming
Test both SDR and HDR modes; ship a palette that doesn't collapse in either
Display Variations
Consider various TV display technologies:
LCD, LED, QLED, OLED render colors differently
Design for Standard picture mode — many TVs offer Cinema/Game/HDR modes
Use sRGB color space for consistency across TVs and mobile
Darker colors save power on OLED screens
Technical Considerations
Gradients: Can display as color bands — use high-color-depth gradients
Dithering: Apply noise to reduce color banding — creates illusion of more colors
Color-based information: Never rely solely on color to convey information — add text labels
Test on multiple devices and color spaces — viewing in real life matters
Related Skills
design-typography.md — Text sizing and readability
design-10foot.md — 10-foot experience principles
a11y-implementation.md — Accessible color and contrast
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