nebula-tv: Skill for Claude Code

Android TV Compose Patterns — Nebula Reference

1. Focus — The Golden Rule

Every interactive element must be visually focused AND keyboard-activatable. TV users cannot tap. D-pad Center (KEYCODE_DPAD_CENTER) = click.

Option A: Use TV Material3 (preferred)

import androidx.tv.material3.Card
import androidx.tv.material3.Button

// TV Card handles focus, scale animation, and OK key automatically
Card(onClick = { /* fires on D-pad center too */ }) { content() }
Button(onClick = { }) { Text("Action") }

Option B: Custom Focus with Scale Animation ("Focus as State" pattern)

var isFocused by remember { mutableStateOf(false) }
val scale by animateFloatAsState(if (isFocused) 1.05f else 1f, label = "scale")

Box(
    modifier = Modifier
        .scale(scale)
        .border(
            width = if (isFocused) 2.dp else 0.dp,
            color = MaterialTheme.colorScheme.primary,
            shape = RoundedCornerShape(8.dp)
        )
        .onFocusChanged { isFocused = it.isFocused }
        .focusable()
        .clickable { performAction() }
)

2. ⚠️ Critical Modifier Order Rule

focusRequester() MUST appear BEFORE any modifier that adds focusability:

// ✅ CORRECT — focusRequester before focusable
Modifier
    .focusRequester(focusRequester)
    .focusable()

// ❌ WRONG — focusRequester will silently fail to attach
Modifier
    .focusable()
    .focusRequester(focusRequester)

3. Auto-Focus on Panel Entry

Always request focus on the first item when a panel becomes visible:

val firstItemFocus = remember { FocusRequester() }

LaunchedEffect(Unit) {
    runCatching { firstItemFocus.requestFocus() }  // runCatching handles "no focused item" gracefully
}

// CORRECT ORDER: focusRequester before focusable
Box(modifier = Modifier
    .focusRequester(firstItemFocus)  // ← first
    .focusable()                      // ← second
)

4. focusGroup — Fix Erratic Focus in Grids

Without focusGroup, D-pad in lazy lists "jumps erratically" when items recompose during scroll. Wrap each row in focusGroup() to contain traversal: