Skip to content

2001105254-netizen/RacePulsePH / .agents/skills/android-layout-specialist

android-layout-specialist

Verified

Design, build, debug, and optimize native and hybrid Android UI layouts across Jetpack Compose, XML ConstraintLayout, and Capacitor/React Native WebViews. Use when the user asks to create Android screens, fix broken edge-to-edge WindowInsets on Android 15/16+, eliminate nested scroll crashes, build adaptive/foldable UIs with WindowSizeClass, or eliminate frame drops and unnecessary recompositions.

FileKindSize
SKILL.mdskill md5.6 KB
references/adaptive-performance.mdmarkdown4.7 KB
references/edge-to-edge-insets.mdmarkdown4.7 KB

references/edge-to-edge-insets.md

View on GitHub
# Edge-to-Edge WindowInsets (Android 15/16+ Compose, XML, and WebView)

Targeting Android SDK 35+ (Android 15 and 16) enables edge-to-edge drawing automatically and turns `setStatusBarColor` and `setNavigationBarColor` into no-ops. Never wrap the entire screen in a global inset padding modifier; route insets by component role instead.

Verify Kotlin/Jetpack Compose and AndroidX helper signatures against current Android Developers documentation (`C-5`, `R-36`). Reference walkthrough cited in user brief: Android Developers edge-to-edge Compose + XML patterns.

## Role-Based Inset Routing

- **Full-Bleed Backgrounds:** Render surfaces, maps, and wallpapers edge-to-edge with zero inset padding so they extend cleanly behind translucent system bars.
- **Interactive Controls & App Bars:** Keep headers, buttons, and FABs clear of status bars, navigation bars, and display cutouts (`WindowInsets.safeDrawing`).
- **Scrolling Containers:** Allow lists to scroll behind translucent navigation/gesture bars while padding internal content so the final list item clears the gesture pill safely.

## 1. Jetpack Compose Implementation Pattern

Call `enableEdgeToEdge()` in `ComponentActivity.onCreate()`, configure `android:windowSoftInputMode="adjustResize"` in `AndroidManifest.xml`, and structure screens using `Scaffold`:

```kotlin
@Composable
fun ProductionScreen(
    items: ImmutableList<ItemUiModel>,
    onActionClick: () -> Unit
) {
    Scaffold(
        modifier = Modifier.fillMaxSize(),
        contentWindowInsets = WindowInsets.safeDrawing,
        topBar = {
            TopAppBar(
                title = { Text("Dashboard") },
                windowInsets = WindowInsets.statusBars.union(WindowInsets.displayCutout)
            )
        },
        floatingActionButton = {
            FloatingActionButton(onClick = onActionClick) {
                Icon(Icons.Default.Add, contentDescription = "Add")
            }
        }
    ) { innerPadding ->
        LazyColumn(
            modifier = Modifier
                .fillMaxSize()
                .consumeWindowInsets(innerPadding)
                .imePadding(),
            contentPadding = innerPadding
        ) {
            items(
                items = items,
                key = { it.id },
                contentType = { it.type }
            ) { item ->
                ItemRow(item)
            }
        }
    }
}
```

## 2. XML Views (`ConstraintLayout` + `RecyclerView`) Pattern

Avoid relying on bare `android:fitsSystemWindows="true"` on complex View roots. Capture initial XML padding once and update padding inside `ViewCompat.setOnApplyWindowInsetsListener`:

```kotlin
val initialPadding = Rect(
    recyclerView.paddingLeft,
    recyclerView.paddingTop,
    recyclerView.paddingRight,
    recyclerView.paddingBottom
)
recyclerView.clipToPadding = false

ViewCompat.setOnApplyWindowInsetsListener(recyclerView) { view, windowInsets ->
    val bars = windowInsets.getInsets(
        WindowInsetsCompat.Type.systemBars() or WindowInsetsCompat.Type.displayCutout()
    )
    view.updatePadding(
        left = initialPadding.left + bars.left,
        right = initialPadding.right + bars.right,
        bottom = initialPadding.bottom + bars.bottom
    )
    windowInsets
}
```

## 3. Capacitor / WebView Edge-to-Edge Pattern

Ensure `viewport-fit=cover` is present on the viewport meta tag in `index.html`, then pad headers and scrollable content per element rather than padding `<body>` globally:

```css
.app-header {
  padding-top: max(12px, env(safe-area-inset-top));
  padding-left: max(16px, env(safe-area-inset-left));
  padding-right: max(16px, env(safe-area-inset-right));
}

.scroll-list {
  padding-bottom: calc(24px + env(safe-area-inset-bottom));
}
```

## Edge-to-Edge Gotchas & RacePulsePH Context

- **Double-Applying Scaffold Insets:** Passing `Modifier.padding(innerPadding)` to a child that also sets `.systemBarsPadding()` creates large empty gaps at the top and bottom. Always call `.consumeWindowInsets(innerPadding)` or apply `innerPadding` once via `contentPadding`.
- **Android 15/16 `statusBarColor` Trap:** `window.statusBarColor` and XML `android:statusBarColor` are ignored on API 35+. Draw a background `Box` or `TopAppBar` under the status bar area and switch light/dark system icon contrast with `WindowCompat.getInsetsController(window, view).isAppearanceLightStatusBars`.
- **RacePulsePH Shell Check:** `android/variables.gradle` sets `targetSdkVersion = 36` and `android/app/src/main/res/layout/activity_main.xml` wraps a single `WebView` in `CoordinatorLayout`. In `index.html`, confirm `viewport-fit=cover` is added alongside `env(safe-area-inset-*)` styles in `src/access-ui.css`, `src/components/BottomNav.tsx`, and `src/components/RunningLoader.css` before enabling translucent system bar overlays.

finishing-a-development-branchobra/superpowersUse when implementation is complete, all tests pass, and you need to decide how to integrate the workStars: 322kUpdated Claude CodeCodexVerifiedInstall
systematic-debuggingobra/superpowersUse when encountering any bug, test failure, or unexpected behavior, before proposing fixesStars: 322kUpdated Claude CodeCodexVerifiedInstall
test-driven-developmentobra/superpowersUse when implementing any feature or bugfix, before writing implementation codeStars: 322kUpdated Claude CodeCodexVerifiedInstall
skill-creatoranthropics/skillsCreate new skills, modify and improve existing skills, and measure skill performance. Use when users want to create a skill from scratch, edit, or optimize an existing skill, run evals to test a skill, benchmark skill performance with variance analysis, or optimize a skill's description for better triggering accuracy.Stars: 198kUpdated Claude CodeCodexVerifiedInstall