GroundRules: Skill for Claude Code

tvOS Design Guidelines

Apple TV is a living room device driven entirely by focus-based navigation and the Siri Remote. There is no pointer, no touch screen, and no mouse. Every design decision must account for the 10-foot viewing distance, the simplicity of the remote, and the lean-back nature of TV consumption.

---

1. Focus-Based Navigation (CRITICAL)

The focus system is the foundation of all tvOS interaction. There is no cursor -- users move focus between elements using the Siri Remote touch surface.

Rules

FOCUS-01: Every interactive element must have a clearly visible focus state. The focused item must be unmistakably distinguished from unfocused items. Use scaling (typically 1.05x-1.1x), elevation via shadow, brightness changes, or border highlights. Never rely on color alone.

FOCUS-02: Focus movement must be predictable and follow a logical spatial layout. When a user swipes right, focus must move to the element visually to the right. Avoid layouts where focus jumps unexpectedly across the screen. Grid and linear layouts are safest.

FOCUS-03: Use focus guides (UIFocusGuide) to bridge gaps in layouts. When visual gaps exist between focusable elements, add invisible focus guides so the user does not get stuck. Every swipe should move focus somewhere meaningful.

FOCUS-04: Apply the parallax effect to focused items. Focused cards, posters, and icons should exhibit a subtle parallax tilt responding to touch surface movement. Use layered images (LSR format) with foreground, midground, and background layers. This communicates depth and confirms focus.

Correct:

// SwiftUI — custom focus engine with explicit focus state
struct ContentView: View {
    @FocusState private var focusedItem: String?

    var body: some View {
        HStack(spacing: 40) {
            ForEach(items) { item in
                CardView(item: item)
                    .focusable()
                    .focused($focusedItem, equals: item.id)
                    .scaleEffect(focusedItem == item.id ? 1.1 : 1.0)
                    .shadow(radius: focusedItem == item.id ? 20 : 0)
                    .animation(.easeInOut(duration: 0.15), value: focusedItem)
            }
        }
    }
}