SkillAgentSearch skills...

leanback-to-compose-tv-migration

Provides instructions and architectural patterns for migrating Android

Install / Use

npx skills add android/skills --skill leanback-to-compose-tv-migration

Installs into whichever agent you are using.

About this skill
📄

SKILL.md

Installable skill definition

Quality Score

93/100

Supported Platforms

Universal

Tags

Our assessment of leanback-to-compose-tv-migration

leanback-to-compose-tv-migration scores 93/100 on our quality scale, 89th of 319 Customer Support skills we index (top 28%).

Its SKILL.md is 34 KB long, well organised into 20 sections with 9 code examples: a thorough specification that gives an agent plenty to work with.

With 7,514 GitHub stars, it is one of the more widely adopted skills in the catalogue.

Substance
30/30
Structure
20/20
Description
12/15
Adoption
16/20
Freshness
15/15

Maintenance, license and trust

  • The repository was last updated about 2 months ago, so leanback-to-compose-tv-migration is actively maintained.
  • Our last check on 2026-10-26 found the source still online.
  • It is released under the Apache-2.0 license, a permissive license that allows use, modification and commercial use with attribution.
  • Its trust signals score 100/100, with no cautions. These come from repository metadata, not a code audit — read the skill file before letting an agent act on it.

Safety scan

No issues found

Our scan of the whole file found no instruction hijacking, hidden characters, credential access, data exfiltration or destructive commands. An AI review of the same text found nothing harmful.

AI review by kimi-k2.7-code on 2026-09-27. Automated pattern scan on 2026-09-27. It catches known dangerous patterns, not every risk — read a skill before letting an agent act on it.

leanback-to-compose-tv-migration compared with similar skills

All 4 of these similar skills score higher than leanback-to-compose-tv-migration; compare them before choosing.

SkillScoreStarsUpdatedFormat
leanback-to-compose-tv-migration (this skill)by android937.5k54d agoSKILL.md
x402by browser-use100121.0k3d agoSKILL.md
algorithmic-artby anthropics100177.9k55d agoSKILL.md
pptxby anthropics100177.9k55d agoSKILL.md
designby nextlevelbuilder100149.0k6d agoSKILL.md

Frequently asked questions

How do I install leanback-to-compose-tv-migration?
Run npx skills add android/skills --skill leanback-to-compose-tv-migration. The install tabs above show the steps for each supported agent.
Which AI agents does leanback-to-compose-tv-migration work with?
It is written for Universal, as a SKILL.md file. Other agents that read the same format can often use it too.
Is leanback-to-compose-tv-migration safe to use?
Our scan of the whole file found no instruction hijacking, hidden characters, credential access, data exfiltration or destructive commands. An AI review of the same text found nothing harmful. It is Apache-2.0-licensed and scores 100/100 on trust signals. Skills are instructions an agent will follow, so read the file before installing it and do not approve commands you do not understand.
Is leanback-to-compose-tv-migration still maintained?
The repository was last updated about 2 months ago, so leanback-to-compose-tv-migration is actively maintained.

name: leanback-to-compose-tv-migration description: Provides instructions and architectural patterns for migrating Android TV applications from legacy Leanback UI Toolkit, Android Views, or Support Fragments to Jetpack Compose for TV (androidx.tv). Use this skill for Leanback to Compose migrations, including browse screen, settings screen, authentication screen, login screen, or video playback screen migrations, or when replacing BrowseSupportFragment, LeanbackSettingsFragment, PreferenceFragment, BaseLeanbackPreferenceFragmentCompat, VideoSupportFragment, GuidedStepSupportFragment, SearchSupportFragment, VerticalGridSupportFragment, Presenter, ArrayObjectAdapter, or CursorMapper with modern Compose equivalents, implementing immersive carousels with focus memory, Media3 video playback with PlayerSurface, or custom 10-foot hero layouts. license: Complete terms in LICENSE.txt metadata: author: Google LLC last-updated: '2026-09-18' keywords:

  • Android TV
  • Jetpack Compose
  • Leanback
  • migration
  • androidx.tv
  • Carousel
  • 10-foot UI
  • PlayerSurface
  • Media3
  • focusRestorer
  • FocusRequester
  • TV development
  • Android Views
  • LeanbackSettingsFragment
  • PreferenceFragment
  • BrowseSupportFragment

The 10-foot UI

A "10-foot UI" is a design paradigm for televisions that tailors an interface for viewing from approximately 3 meters (10 feet) away. When designing for this experience, account for these key characteristics:

  • Viewing distance: Viewers are sitting far from the screen, "leaning back". Screen layouts are uncluttered, with text and UI elements that are large enough to be comfortably readable from a distance, without dense blocks of text.
  • Color contrast: To avoid washed out colors on TV displays with low contrast ratios, the design uses high-contrast palettes and distinct visual indicators so focused states remain visible across different TV panels.
  • D-pad navigation : Interaction relies on a directional remote control with limited 4-way navigation (Up, Down, Left, Right) with components organized into clear spatial grids and carousels without focus traps.

Core architecture and library selection

When migrating an Android TV application to Jetpack Compose, you must use androidx.tv libraries and follow these 10-foot UI patterns:

  • UI modernization: Focus on custom, cinematic layouts over legacy direct 1:1 templates. You must use Jetpack Compose for TV features like dynamic gradient hero backdrops, custom focus animations, custom navigation drawers, and custom layouts.
  • Primary design system : You must always use androidx.tv.material3.* (androidx.tv:tv-material) over mobile androidx.compose.material3.*. TV Material 3 provides built-in D-Pad focus handling, focus zoom scaling, and TV-optimized typography and shapes. To set up Compose for TV dependencies, follow Compose for TV setup.
  • Focus zoom animation : For interactive cards, you must use CompactCard, ClassicCard, or WideCardContainer with scale = CardDefaults.scale(focusedScale = 1.1f) to provide standard TV focus animation.
  • Coil image loading : To use declarative AsyncImage(model, contentDescription, ...) without passing an explicit ImageLoader parameter, you must include io.coil-kt:coil-compose in your Gradle dependencies.
  • Explicit imports : You must always import TV Material 3 classes explicitly (for example, import androidx.tv.material3.Surface, import androidx.tv.material3.ListItem) instead of using wildcard imports (import androidx.tv.material3.*).
  • File naming conventions : You must name Composable screen files after the screen (for example, name BrowseScreen as BrowseScreen.kt, PlaybackScreen as PlaybackScreen.kt, and AuthenticationScreen as AuthenticationScreen.kt). Don't use generic prefixes like Main.
  • Overscan and bezels : You must apply horizontal padding (for example, horizontal = 48.dp or 32.dp, vertical = 24.dp) to root containers, carousels, and top bars to prevent clipping.
  • Reading width constrainment : You must constrain reading width using Modifier.widthIn(max = 600.dp) on text columns for long-form text.
  • Media3 Compose dependencies : Include androidx.media3:media3-ui-compose in app/build.gradle when modernizing media playback screens.
  • Prohibition of legacy AndroidView wrappers : Don't use legacy AndroidView wrappers to embed View-based components into Jetpack Compose screens. All migrated screens must use Compose components or Media3 Compose surfaces (PlayerSurface).

D-pad focus handling and navigation

Jetpack Compose for TV (androidx.tv.material3) requires explicit focus management, as components don't receive initial focus automatically and navigation uses 2D spatial coordinates. To configure TV D-pad navigation, follow instructions in TV Navigation guide.

Initial focus

You must assign initial focus to the primary interactive element on every screen (such as the first action button, card, or ListItem) using FocusRequester when entering a screen. Define val focusRequester = remember { FocusRequester() }, attach Modifier.focusRequester(focusRequester) to the primary element, and request focus inside LaunchedEffect(Unit) { focusRequester.requestFocus() }:

val focusRequester = remember { FocusRequester() }
val focusManager = LocalFocusManager.current

LaunchedEffect(Unit) {
    focusRequester.requestFocus()
}
<br />

Note: For screens with dynamic state or pagers (like OnboardingScreen using HorizontalPager), you must pass the state key to LaunchedEffect (for example LaunchedEffect(pagerState.currentPage)) so that focus is re-applied when the page changes.

Bidirectional focus routing and avoiding focus traps

When interactive elements sit on opposite sides of the display, standard 2D spatial navigation fails to find targets across them. This creates focus traps where users are unable to navigate out of an area using the D-pad.

For symmetrical, bidirectional D-pad navigation without focus traps, you must rely on Compose's 2D spatial focus engine whenever possible. When connecting adjacent UI elements across scrollable containers (like LazyColumn or LazyRow), don't set directional overrides (up = ..., down = ...) targeting individual items inside lazy lists. When an item scrolls off-screen during vertical navigation, its FocusRequester becomes uninitialized, throwing IllegalStateException during focus searches:

Row(
    modifier = Modifier
        .fillMaxWidth()
        .padding(horizontal = 48.dp, vertical = 16.dp),
    horizontalArrangement = Arrangement.End
) {
    Button(
        onClick = { /* Search */ },
        modifier = Modifier.focusRequester(topBarFocusRequester)
    ) { Text("Search") }
}
<br />

Row focus recollection (Modifier.focusRestorer)

When navigating vertically between horizontal carousels (LazyRow), Compose's default 2D spatial focus engine searches along the X coordinate of the focused item. If a user scrolls right in Row 1 (for example to Item 4 at X=800dp) and presses DOWN to navigate to Row 2, spatial routing focuses whatever item sits at X=800dp in Row 2.

To make every row maintain its own recollection of card focus (restoring focus to the previously visited item when revisited), you must attach Modifier.focusRestorer (with no arguments) directly to the LazyRow. Don't pass custom fallback FocusRequester lambdas in lazy containers, as calling requestFocus on an unattached or off-screen item during rapid D-pad scrolling throws IllegalStateException.

LazyRow(
    modifier = Modifier.focusRestorer(),
    contentPadding = PaddingValues(horizontal = 48.dp),
    horizontalArrangement = Arrangement.spacedBy(16.dp)
) {
    itemsIndexed(videos) { vidIndex, video ->
        CompactCard(
            onClick = { onVideoClick(video) },
            image = {
                AsyncImage(
                    model = video.cardImageUrl,
                    contentDescription = video.title,
                    contentScale = ContentScale.Crop,
                    modifier = Modifier.fillMaxSize()
                )
            },
            title = { Text(video.title) },
            modifier = Modifier
                .then(
                    if (catIndex == 0 && vidIndex == 0) {
                        Modifier.focusRequester(firstCardFocusRequester)
                    } else {
                        Modifier
                    }
                )
                .onFocusChanged { focusState ->
                    if (focusState.isFocused) {
                        focusedVideo = video
                        focusedCategoryIndex = catIndex
                    }
                }
        )
    }
}
<br />

Text input, hardware keyboard enter interception, and IME focus chaining

When migrating search bars or login forms from Leanback (SearchSupportFragment, GuidedStepSupportFragment), don't use bare BasicTextField containers or empty Surface(onClick = {}) wrappers, as they prevent D-pad CENTER from attaching the virtual keyboard (IME).

  1. Clickable TV surface wrapper with Back-key interception (onPreviewKeyEvent) : Wrap standard M3 TextField inside a focusable TV Surface(onClick = { focusRequester.requestFocus() }, scale = ClickableSurfaceDefaults.scale(focusedScale = 1.01f), border = ClickableSurfaceDefaults.border(focusedBorder = Border(BorderStroke(2.dp, Color.White)))) to provide a focused border outline and D-pad focus scaling. You must attach Modifier.onPreviewKeyEvent on the text field or wrapper to intercept Key.Back and Key.Escape so the user's able to remove focus from the input field without exiting the screen.
  2. Why Back-key interception is mandatory : When editing a text field on Android TV, pressing the D-pad Back button normally navigates back and exits the screen. By intercepting Key.Back and Key.Escape on KeyUp in onPreviewKeyEvent to stop editing (clearing focus), the user's able to return to D-pad form navigation without being trapped in the text field or accidentally exiting the screen.
  3. IME focus chaining : For multi-field forms (such as Username and Password in authentication screens), attach KeyboardActions(onNext = { focusManager.moveFocus(FocusDirection.Down) }) with ImeAction.Next on top fields to route focus down to the next input box, and ImeAction.Done on the bottom field to route focus directly to the submit button:
Surface(
    onClick = { focusRequester.requestFocus() },
    border = ClickableSurfaceDefaults.border(focusedBorder = Border(border = BorderStroke(2.dp, Color.White))),
    modifier = Modifier
        .fillMaxWidth()
        .focusRequester(focusRequester)
) {
    OutlinedTextField(
        value = username,
        onValueChange = { username = it },
        label = { Text("Username") },
        singleLine = true,
        keyboardOptions = KeyboardOptions(imeAction = ImeAction.Next),
        keyboardActions = KeyboardActions(onNext = { focusManager.moveFocus(FocusDirection.Down) }),
        modifier = Modifier
            .fillMaxWidth()
            .onPreviewKeyEvent { event ->
                if (event.type == KeyEventType.KeyDown && (event.key == Key.Enter || event.key == Key.NumPadEnter)) {
                    focusManager.moveFocus(FocusDirection.Down)
                    true
                } else false
            }
    )
}

Surface(
    onClick = {},
    border = ClickableSurfaceDefaults.border(focusedBorder = Border(border = BorderStroke(2.dp, Color.White))),
    modifier = Modifier.fillMaxWidth()
) {
    OutlinedTextField(
        value = password,
        onValueChange = { password = it },
        la

Truncated for display — read the full file on GitHub.

Related Skills

View on GitHub
GitHub Stars7.5k
CategoryCustomer
Updated1mo ago
Forks488

Languages

Python

Trust signals

100/100

From repository metadata: license, adoption, age and documentation. Not a code audit — see the Safety scan above for what the skill file itself contains.

No cautions