Update to Building React Native Apps

{
  "name": "react-native-tv-best-practices",
  "description": "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.",
  "included_files": [
    {
      "relative_path": "agents/openai.yaml",
      "size_in_bytes": 307
    },
    {
      "relative_path": "references/a11y-checklist.md",
      "size_in_bytes": 4436
    },
    {
      "relative_path": "references/a11y-implementation.md",
      "size_in_bytes": 4523
    },
    {
      "relative_path": "references/a11y-overview.md",
      "size_in_bytes": 2840
    },
    {
      "relative_path": "references/design-10foot.md",
      "size_in_bytes": 3023
    },
    {
      "relative_path": "references/design-color.md",
      "size_in_bytes": 3892
    },
    {
      "relative_path": "references/design-layout.md",
      "size_in_bytes": 3066
    },
    {
      "relative_path": "references/design-typography.md",
      "size_in_bytes": 2679
    },
    {
      "relative_path": "references/focus-management.md",
      "size_in_bytes": 6565
    },
    {
      "relative_path": "references/focus-performance.md",
      "size_in_bytes": 3546
    },
    {
      "relative_path": "references/nav-directional.md",
      "size_in_bytes": 3737
    },
    {
      "relative_path": "references/nav-keyboard.md",
      "size_in_bytes": 3662
    },
    {
      "relative_path": "references/nav-patterns.md",
      "size_in_bytes": 4510
    },
    {
      "relative_path": "references/perf-animations.md",
      "size_in_bytes": 3038
    },
    {
      "relative_path": "references/perf-lists.md",
      "size_in_bytes": 3343
    },
    {
      "relative_path": "references/perf-memory.md",
      "size_in_bytes": 2557
    },
    {
      "relative_path": "references/perf-network.md",
      "size_in_bytes": 2727
    },
    {
      "relative_path": "references/perf-overview.md",
      "size_in_bytes": 3660
    },
    {
      "relative_path": "references/release-cicd.md",
      "size_in_bytes": 3307
    },
    {
      "relative_path": "references/setup-architecture.md",
      "size_in_bytes": 3849
    },
    {
      "relative_path": "references/setup-cross-platform.md",
      "size_in_bytes": 3400
    },
    {
      "relative_path": "references/setup-getting-started.md",
      "size_in_bytes": 5196
    },
    {
      "relative_path": "references/test-e2e.md",
      "size_in_bytes": 3691
    },
    {
      "relative_path": "references/test-javascript.md",
      "size_in_bytes": 3775
    },
    {
      "relative_path": "references/test-strategy.md",
      "size_in_bytes": 2330
    },
    {
      "relative_path": "references/video-debugging.md",
      "size_in_bytes": 1595
    },
    {
      "relative_path": "references/video-players.md",
      "size_in_bytes": 3300
    },
    {
      "relative_path": "references/video-streaming.md",
      "size_in_bytes": 2142
    }
  ],
  "skill_md_contents": "---\nname: react-native-tv-best-practices\ndescription: 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.\nlicense: MIT\n---\n\n# React Native TV Best Practices\n\n## Overview\n\nTV-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.\n\nUse 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).\n\n## Skill Format\n\nReference files are grouped by topic prefix:\n\n- `focus-*`: focus engines, focus guides, focus event performance\n- `nav-*`: D-pad navigation, Back/Menu behavior, keyboard/search input\n- `design-*`: 10-foot typography, layout, color, focus visibility\n- `perf-*`: startup, memory, lists, animation, and network constraints on TV hardware\n- `video-*`: playback architecture, DRM/protocol selection, debugging\n- `a11y-*`: TV accessibility implementation and audit checks\n- `setup-*`: stack detection, setup, architecture, cross-platform behavior\n- `test-*` and `release-*`: test coverage, E2E, and CI/release workflows\n\n## When to Apply\n\nApply this skill when the app targets a TV platform and the work involves:\n\n- Focus movement, visible focus, focus restoration, or remote/D-pad input\n- TV layout readability, overscan/safe areas, or 10-foot UI density\n- TV player controls, manifests, DRM, decoder support, or playback errors\n- Performance on low-memory TV hardware, especially with video or large carousels\n- TV accessibility with screen readers, captions, focus order, or remote-only interaction\n- Platform setup for `react-native-tvos`, Expo TV, Amazon Vega/Kepler, Tizen, or webOS\n\n## Before You Start — Identify the TV Stack\n\nThis 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.\n\n| Stack                                                 | How to detect                                                                                     | Setup expectations                                                                                                             |\n| ----------------------------------------------------- | ------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------ |\n| **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             |\n| **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 |\n| **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                   |\n| **Web-based TV** (Tizen, webOS)                       | web bundler (Rsbuild/webpack) + platform packaging; spatial-nav library                           | Platform SDK packaging; `@noriginmedia/norigin-spatial-navigation` for focus                                                   |\n\nThe focus, 10-foot design, performance, accessibility, and player guidance applies across all of these — only the **setup/build** expectations are stack-specific.\n\n## Review Rules\n\n- Resolve the target stack before setup advice.\n- Prefer natural focus order and focus guides before imperative focus calls or broad `nextFocus*` maps.\n- Treat focus loss, invisible focus, and broken Back/Menu behavior as navigation bugs.\n- Check readability, safe areas, and focus states at TV distance before tuning visual details.\n- Profile on the weakest supported TV device before reporting performance fixes as complete.\n- Separate playback failures by layer: manifest request, DRM license exchange, decoder capability, player state, and React UI controls.\n\n## Priority-Ordered Guidelines\n\n| Priority | Category | Impact | Prefix |\n|----------|----------|--------|--------|\n| 1 | Focus and D-pad navigation | CRITICAL | `focus-*`, `nav-*` |\n| 2 | List, animation, and input performance | CRITICAL | `perf-*` |\n| 3 | Playback and DRM failures | HIGH | `video-*` |\n| 4 | 10-foot readability and layout | HIGH | `design-*` |\n| 5 | TV accessibility | HIGH | `a11y-*` |\n| 6 | Stack setup, testing, and release | MEDIUM | `setup-*`, `test-*`, `release-*` |\n\n## Quick Reference\n\n1. Detect the TV stack from package files, manifests, native folders, and platform tooling.\n2. Reproduce navigation with the remote or D-pad path, not mouse/touch assumptions.\n3. Confirm the focused element is always visible, reachable, and restored after modals/routes.\n4. Check playback failures from the network/DRM layer upward before changing React controls.\n5. Measure list, animation, memory, and startup work on the weakest supported TV target.\n\n## References\n\n### Focus and Navigation\n\n| File | Impact | Description |\n|------|--------|-------------|\n| [focus-management.md](references/focus-management.md) | CRITICAL | Focus engines, focus guides, `nextFocus*`, and focus restoration |\n| [focus-performance.md](references/focus-performance.md) | CRITICAL | Avoiding frame drops from focus event handling |\n| [nav-directional.md](references/nav-directional.md) | CRITICAL | Directional navigation rules across TV platforms |\n| [nav-patterns.md](references/nav-patterns.md) | CRITICAL | Global/local navigation, modals, tabs, and Back behavior |\n| [nav-keyboard.md](references/nav-keyboard.md) | MEDIUM | Search and text input with remotes |\n\n### Design\n\n| File | Impact | Description |\n|------|--------|-------------|\n| [design-10foot.md](references/design-10foot.md) | HIGH | 10-foot review heuristics |\n| [design-typography.md](references/design-typography.md) | HIGH | TV type sizing and readability |\n| [design-layout.md](references/design-layout.md) | HIGH | Safe areas, spacing, carousels, and focus room |\n| [design-color.md](references/design-color.md) | MEDIUM | Contrast and TV display color constraints |\n\n### Performance\n\n| File | Impact | Description |\n|------|--------|-------------|\n| [perf-overview.md](references/perf-overview.md) | HIGH | TV performance targets and profiling order |\n| [perf-lists.md](references/perf-lists.md) | CRITICAL | Virtualized rows and poster-heavy lists |\n| [perf-animations.md](references/perf-animations.md) | CRITICAL | Focus and transition animation performance |\n| [perf-memory.md](references/perf-memory.md) | HIGH | Low-memory TV crashes and image/video pressure |\n| [perf-network.md](references/perf-network.md) | HIGH | Remote input, request stalls, and network resilience |\n\n### Video, Accessibility, Setup, Testing\n\n| File | Impact | Description |\n|------|--------|-------------|\n| [video-streaming.md](references/video-streaming.md) | HIGH | TV platform protocol/DRM selection |\n| [video-players.md](references/video-players.md) | HIGH | Player choices and custom controls |\n| [video-debugging.md](references/video-debugging.md) | HIGH | Manifest, DRM, codec, and playback debugging |\n| [a11y-overview.md](references/a11y-overview.md) | MEDIUM | TV-specific accessibility differences |\n| [a11y-implementation.md](references/a11y-implementation.md) | HIGH | Accessible labels, roles, live regions, and focus |\n| [a11y-checklist.md](references/a11y-checklist.md) | MEDIUM | Launch accessibility audit checklist |\n| [setup-getting-started.md](references/setup-getting-started.md) | MEDIUM | `react-native-tvos` and Expo TV setup |\n| [setup-cross-platform.md](references/setup-cross-platform.md) | MEDIUM | Platform detection and cross-platform caveats |\n| [setup-architecture.md](references/setup-architecture.md) | MEDIUM | Code sharing and project structure |\n| [test-strategy.md](references/test-strategy.md) | MEDIUM | TV testing scope and coverage split |\n| [test-javascript.md](references/test-javascript.md) | MEDIUM | JS-level remote/focus test helpers |\n| [test-e2e.md](references/test-e2e.md) | MEDIUM | Appium and TV E2E coverage |\n| [release-cicd.md](references/release-cicd.md) | MEDIUM | CI, build fingerprinting, and release checks |\n\n## Problem → Skill Mapping\n\n| Symptom                              | Start Here                                                                   |\n| ------------------------------------ | ---------------------------------------------------------------------------- |\n| \"Focus jumps to wrong element\"       | [focus-management.md](references/focus-management.md) → Debugging section    |\n| \"App freezes when scrolling lists\"   | [perf-lists.md](references/perf-lists.md) → Virtualization                   |\n| \"Animations stutter on Fire TV\"      | [perf-animations.md](references/perf-animations.md) → Native driver          |\n| \"Text too small on TV\"               | [design-typography.md](references/design-typography.md) → Minimum sizes      |\n| \"Video won't play / DRM errors\"      | [video-streaming.md](references/video-streaming.md) → DRM section            |\n| \"Screen reader skips elements\"       | [a11y-implementation.md](references/a11y-implementation.md) → Roles & labels |\n| \"Back button doesn't work right\"     | [nav-patterns.md](references/nav-patterns.md) → Back navigation              |\n| \"Keyboard covers content\"            | [nav-keyboard.md](references/nav-keyboard.md) → Built-in vs custom           |\n| \"App takes forever to start\"         | [perf-overview.md](references/perf-overview.md) → Startup time               |\n| \"Images causing memory crashes\"      | [perf-memory.md](references/perf-memory.md) → Image optimization             |\n| \"CI pipeline takes hours\"            | [release-cicd.md](references/release-cicd.md) → Fingerprinting               |\n| \"How to share code across platforms\" | [setup-architecture.md](references/setup-architecture.md) → Code sharing     |\n\n## Security (TV-Specific)\n\nGeneral dependency/input hygiene applies as in any RN app; the TV-specific deltas worth calling out:\n\n- Never embed FairPlay/Widevine/PlayReady keys in client code — treat the license server as the trust boundary and keep DRM tokens server-issued.\n"
}