android-layouts

Files (8)

• SKILL.md
• CHANGELOG.md · references/
• COMPOSE_LAYOUTS.md · references/
• INTEROP.md · references/
• LESSONS_LEARNED.md · references/
• MATERIAL_DESIGN.md · references/
• PROFILING_TOOLS.md · references/
• XML_LAYOUTS.md · references/

SKILL.md (first lines)

# Android Layout Best Practices

Layout performance and structure guidance for XML/View systems and Jetpack Compose.

For Compose-specific concerns (stability, recomposition, side effects, animations, modifier
extensions), use the **android-compose-ui** skill. This skill focuses on layout hierarchy,
structure, and performance.

## Reference Index

| File | Topics |
|------|--------|
| [XML_LAYOUTS.md](references/XML_LAYOUTS.md) | ConstraintLayout, merge/include, ViewStub, double taxation, RecyclerView, CoordinatorLayout, ViewPager2, WindowInsets |
| [COMPOSE_LAYOUTS.md](references/COMPOSE_LAYOUTS.md) | Layout phases, custom layouts, SubcomposeLayout, modifier order, WindowInsets, contentPadding, HorizontalPager |
| [INTEROP.md](references/INTEROP.md) | View-to-Compose migration, AndroidView, ComposeView |
| [MATERIAL_DESIGN.md](references/MATERIAL_DESIGN.md) | Scaffold, TopAppBar, NavigationBar/Rail, drawers, inset contracts |
| [PROFILING_TOOLS.md](references/PROFILING_TOOLS.md) | Layout Inspector, Lint, Perfetto, benchmarking |
| [LESSONS_LEARNED.md](references/LESSONS_LEARNED.md) | Self-learning log |
| [CHANGELOG.md](references/CHANGELOG.md) | Update history |

---

## Core Principle

**Flat hierarchies are fast hierarchies.** Every widget in the tree pays init + measure + layout +
draw cost. Each nesting level multiplies that cost across all children. The single most impactful
layout optimization is reducing depth.

---

## XML Layout Rules

### Hierarchy Depth

- Target **max 10 levels** of nesting. Profile anything deeper.
- Replace nested `LinearLayout` (especially weighted) with a single `ConstraintLayout`.
- Use `<merge>` as root tag when the layout will be included in another — eliminates one
  nesting level.
- Use `<include>` to reuse layout fragments; combine with `<merge>` for zero-overhead inclusion.

### Double Taxation

Some layout containers measure children multiple times:

| Container | Double Measure? | Why |
|-----------|-----------------|-----|
| `LinearLayout` with weights | Yes | Weight distribution requires pre-measure |
| `RelativeLayout` | Yes | Constraints may reference each other |
| `GridLayout` with weights | Yes | Same as LinearLayout weights |
| `ConstraintLayout` | No | Single-pass constraint solver |

**Rule:** If a container triggers double measurement, replace it with `ConstraintLayout` or
restructure to avoid the multi-pass trigger.

### ViewStub

Use `ViewStub` for layouts that are rarely or conditionally visible (error states, empty states,
progress indicators). `ViewStub` is a zero-dimension placeholder that inflates the real layout
only when `setVisibility(VISIBLE)` or `inflate()` is called.

```xml
<ViewStub
    android:id="@+id/stub_error"
    android:layout="@layout/error_state"
    android:layout_width="match_parent"
    android:layout_height="wrap_content" />
```

```kotlin
val stub = findViewById<ViewStub>(R.id.stub_error)
stub.inflate()
```

After inflation, the `ViewStub` is replaced by the inflated view. It cannot be re-inflated.

### RecyclerView over ListView

Always use `RecyclerView`. `ListView` creates a new view for every item — no recycling.
`RecyclerView` reuses view holders and provides built-in diffing via `DiffUtil`.

### Compound Drawables

When a `TextView` has an adjacent `ImageView` (icon + text), replace both with a single
`TextView` using compound drawables:

```xml
<TextView
    android:drawableStart="@drawable/ic_search"
    android:drawablePadding="8dp"
    android:text="@string/search" />
```

This eliminates one view from the hierarchy.

### CoordinatorLayout

For coordinating scroll-dependent UI (collapsing toolbar, FAB, snackbar). See
[references/XML_LAYOUTS.md](references/XML_LAYOUTS.md) for full patterns with
`AppBarLayout`, `CollapsingToolbarLayout`, and scroll flags.

Key rule: connect `app:layout_behavior="@string/appbar_scrolling_view_behavior"` on
the scrolling sibling, and `app:layout_scrollFlags` on the AppBar children.

### ViewPager2

RecyclerView-based paging. Use `FragmentStateAdapter` for fragment pages,
`RecyclerView.Adapter` for view pages. Connect with `TabLayoutMediator` for tabs.
For new Compose code, prefer `HorizontalPager` (see Compose Layout Rules).

---

## Compose Layout Rules

### Layout Phases

Compose rendering has three phases: **Composition → Layout → Drawing**. Each phase can be
skipped independently when inputs haven't changed.

- **Composition** runs when state read during composition changes.

From kvithayathil/agent-resources, Apache-2.0.

More from kvithayathil/agent-resources