10ft-ui

Files (1)

• SKILL.md

SKILL.md (first lines)

# 10-foot UI

> TV is a 10-foot UI: viewer sits 8–12 ft from a 1080p–4K screen. Decisions that are fine on phone (12pt text, 4:1 contrast, dense layouts) are broken on TV. This skill is the checklist for new screens that don't reuse the template's vetted ones.

If you're reusing `Home`, `Detail`, etc., **you don't need this skill** — they already comply. Load this only when generating something genuinely new.

## The numbers

| Spec | TV minimum | Phone minimum (for contrast) |
|------|------------|------------------------------|
| Body text size | 24pt | 14pt |
| Heading 1 | 48–64pt | 24–28pt |
| Line height | 1.4× font size | 1.2× |
| Touch / focus target | 96×96pt | 44×44pt |
| Body text contrast | 7:1 (AAA) | 4.5:1 (AA) |
| Focus ring thickness | 4px+ | n/a |
| Safe area margin | 5% of width/height each edge (overscan) | n/a |

The phone column is there to make the deltas obvious. On TV, everything is bigger, thicker, more contrasted.

## Overscan / safe area

TVs historically cropped 5% of the image edges. Modern flatscreens mostly don't, but the convention persists, and the platforms (especially Apple TV) enforce safe areas in their HIG. Practical rules:

- Don't put critical content within 5% of any edge.
- Don't anchor focus rings exactly to the edge — they'll get clipped on some screens.
- Use `useSafeAreaInsets()` (from `react-native-safe-area-context`) and offset all root containers.

The template's screen wrappers handle this. For a brand-new screen, replicate that pattern — don't put a `<View>` at `top: 0` and call it done.

## Focus is everything

A 10-ft UI is navigated by D-pad, not by pointing. Every interactive element must:

1. Be focusable (`<SpatialNavigationFocusableView>` or themed `<Pressable>`).
2. Have a visible focus state (focus ring, scale, glow — at least one, clearly visible at 10 ft).
3. Be reachable from at least one direction (no orphans).

If you can't D-pad to it, it doesn't exist.

See `spatial-navigation.md` for the focus tree primitives. This skill is about *visual* focus, not the focus tree.

## Layout density

Phone designers cram. TV designers don't.

- **Cards (tiles):** target 240–320px wide, 360–480px tall (16:9 thumbnail + label). Smaller → unreadable. Bigger → too few per row.
- **Rails:** 5–7 visible tiles per row on a 1080p layout. More = each tile becomes a postage stamp.
- **Grids:** 4–6 columns on 1080p. Same logic.
- **Whitespace:** generous. The user is 10 ft away, not 12 inches. Cramming reads as noise.

When in doubt, fewer-larger over more-smaller.

## Typography for TV

- **Font:** sans-serif. Serifs blur at distance. The template defaults to a clean sans; respect that.
- **Weight:** 400 for body, 700 for headings. Thin / hairline disappears.
- **Tracking:** very slight positive tracking helps legibility (1–2% letter-spacing). Not required, but improves polish.
- **Multiple lines:** avoid stacking more than 3 lines of body text without a break. Long-form reading on TV is a known failure mode.

## Color and contrast

Lower-quality TVs and bright rooms compress contrast. Account for the worst case:

- **Body text on background:** 7:1 minimum. If your brand says white on dark gray, check the actual ratio. `#FFFFFF on #1F1F1F` = 13:1, fine. `#CCCCCC on #1F1F1F` = 9.2:1, also fine. `#888888 on #1F1F1F` = 4.5:1, **not** fine for body.
- **Muted / secondary text:** 4.5:1 minimum. Below this it's invisible.
- **Focus ring vs background:** if the focus ring is 4px and high-contrast, it works. If you've themed it to a brand color that's too close to background, fix it (see `theming.md` focus ring decision rule).

## Motion

Motion is great on TV — large screens, dramatic feel — but with rules:

- **Focus transitions:** 150–250ms, ease-out. Faster feels jittery, slower feels sluggish.
- **Screen transitions:** 250–400ms.
- **Hero crossfades:** 300–500ms.
- **Avoid parallax / scroll-jacking** for the primary navigation. D-pad expects predictable, snap-style focus moves.

Animations that work on phone (subtle bounce, slide-in-from-bottom) often feel cheap on TV. Bigger, calmer motion reads better.

## Empty states

A screen with no content is a real possibility (empty watchlist, search with no results, category with no items). Don't let it render blank:

- Show a clear illustration or large icon.
- Headline at H2 size.
- One-sentence explanation.
- A CTA back to a populated screen ("Browse home", "Search").

This is the difference between "looks broken" and "looks intentional."

## Accessibility — non-optional even on TV

- **Captions / subtitles:** if content has them, they must be available (see `video-player.md`).
- **Screen reader:** Apple TV has VoiceOver; Android TV has TalkBack. Set `accessibilityLabel` on focusables. The template's components do this — preserve it when extending.
- **Reduced motion:** respect the system setting on Apple TV; gracefully skip non-essential animations.
- **Contrast:** see above; already covered.

## Decision tree: I need a new screen layout

1. **Can I describe it as one of `Home`, `Category`, `Detail`, `Player`, `Search`, `Settings`?** → Use that screen with different data. Stop.
2. **Is it a variation of one of those?** → Copy the closest screen as a starting file. Modify carefully. Keep its `SpatialNavigationRoot`, safe area, focus model.
3. **Is it genuinely new (live TV, profiles, browse-by-mood, etc.)?** → Apply this skill from scratch. Specifically:
   - Wrap in `<SpatialNavigationRoot>` + safe-area-aware container.
   - Use theme tokens for every color, size, spacing.
   - Compose from `Hero`, `Rail`, `Grid`, `Tile` where possible.
   - Run `run_focus_check` before considering it done.
   - Add an empty state.

## Anti-patterns

- **Small text "to fit more on screen".** Less content visible is better than unreadable content.
- **Hover states.** TV has no hover. Use focus states.
- **Mouse-sized buttons (44pt).** Too small. 96pt+ visible targets.
- **Edge-anchored content.** Overscan eats it. Use safe-area insets.
- **High-density grids (8+ columns).** Tiles become postage stamps.
- **Long forms with virtual keyboard.** TV text entry is painful. Minimize fields; offer voice / phone-handoff if the platform supports it.
- **Dense data tables.** TV is not a spreadsheet medium. Re-shape to lists, cards, or summary screens.

From giolaq/tv-build-harness, MIT-0.

More from giolaq/tv-build-harness