Skip to content

aldefy/compose-skill / skills/compose-expert

compose-expert

Unverified

Compose and Compose Multiplatform expert for UI development across Android, Desktop, iOS, and Web. Use whenever the user mentions Compose APIs (@Composable, remember, LaunchedEffect, NavHost, MaterialTheme, LazyColumn, Modifier, recomposition), Compose Multiplatform (commonMain, expect/actual, Res.*, ComposeUIViewController, UIKitView, ComposeViewport), Android TV (tv-material, D-pad, focus, Carousel), Material 3 motion, atomic design systems, design-to-code workflows, Paging 3, or navigation. Activates Review Mode on GitHub PR URLs and review phrases ("review this PR", "what's wrong with this"). Auto-detects Compose projects on session_start. Backed by actual androidx/androidx and JetBrains/compose-multiplatform-core source receipts. See "## When this skill applies" in SKILL.md for the full trigger surface.

FileKindSize
SKILL.mdskill md24.8 KB
agents/openai.yamlconfig278 B
references/accessibility.mdmarkdown11.2 KB
references/adaptive-layout-input.mdmarkdown5.2 KB
references/agentic-ui-a2ui.mdmarkdown4.7 KB
references/agsl-shaders.mdmarkdown11.5 KB
references/animation.mdmarkdown41.7 KB
references/appfunctions.mdmarkdown5.8 KB
references/appstate.mdmarkdown3.9 KB
references/atomic-design.mdmarkdown10.7 KB
references/auto-init.mdmarkdown1.6 KB
references/car-compose.mdmarkdown6.7 KB
references/composition-locals.mdmarkdown6.9 KB
references/deprecated-patterns.mdmarkdown8.3 KB
references/design-to-compose.mdmarkdown23.5 KB
references/graphics-modern.mdmarkdown2.6 KB
references/ink.mdmarkdown5.1 KB
references/lists-scrolling.mdmarkdown14.5 KB
references/material3-motion.mdmarkdown14.9 KB
references/media3-compose.mdmarkdown1.7 KB
references/ml-kit-agentic.mdmarkdown5.5 KB
references/modifiers.mdmarkdown13.6 KB
references/multiplatform.mdmarkdown21.1 KB
references/navigation-migration.mdmarkdown14.6 KB
references/navigation.mdmarkdown11.0 KB
references/official-android-skills.mdmarkdown2.7 KB
references/paging-mvi-testing.mdmarkdown6.4 KB
references/paging-offline.mdmarkdown6.4 KB
references/paging.mdmarkdown11.1 KB
references/performance.mdmarkdown22.7 KB
references/platform-specifics.mdmarkdown20.2 KB
references/pr-review.mdmarkdown14.1 KB
references/production-crash-playbook.mdmarkdown25.3 KB
references/remote-compose.mdmarkdown3.7 KB
references/side-effects.mdmarkdown13.0 KB
references/source-code/cmp-source.mdmarkdown17.8 KB
references/source-code/foundation-source.mdmarkdown560.9 KB
references/source-code/material3-source.mdmarkdown836.1 KB
references/source-code/navigation-source.mdmarkdown118.8 KB
references/source-code/runtime-source.mdmarkdown449.0 KB
references/source-code/ui-source.mdmarkdown313.1 KB
references/state-management.mdmarkdown17.6 KB
references/styles-experimental.mdmarkdown14.5 KB
references/text-editing.mdmarkdown3.8 KB
references/theming-material3.mdmarkdown13.0 KB
references/tv-compose.mdmarkdown30.2 KB
references/view-composition.mdmarkdown20.0 KB
references/wear-compose.mdmarkdown2.0 KB
references/xr-compose.mdmarkdown5.1 KB

references/modifiers.md

View on GitHub
# Jetpack Compose Modifiers Reference

Modifiers are the primary way to decorate or augment a composable. They apply layout, drawing, gesture, and accessibility behavior. Understanding modifier ordering and the available APIs is critical for correctness and performance.

## Modifier Chain Ordering

Order matters. Modifiers are applied left-to-right in the DSL, but conceptually they wrap bottom-to-top. Each modifier receives a lambda that draws/measures the content below it.

**Key rule:** each modifier in the chain can only *reduce* the constraints handed down by the modifiers before it — it can never grow the element past a size fixed earlier. So `padding` **before** `size` adds to the footprint; `padding` **after** `size` eats into it.

```kotlin verify
// name: padding-before-size-adds-to-footprint
// repeat: 3
// assert: width = 132.dp
// assert: height = 132.dp
// Footprint = 132x132. size fixes the 100x100 inner box, padding adds 16dp on
// every side (100 + 16 + 16 = 132), and the red background wraps the whole 132x132.
@Composable fun Subject() {
    Box(
        Modifier
            .background(Color.Red)
            .padding(16.dp)
            .size(100.dp)
    )
}
```

```kotlin verify
// name: size-before-padding-keeps-footprint
// repeat: 3
// assert: width = 100.dp
// assert: height = 100.dp
// Footprint = 100x100, NOT 132x132. size fixes the element at 100x100 first;
// the later padding cannot grow it — it insets the content inward to 68x68, and
// the red background (after padding) paints only that inner 68x68 region.
@Composable fun Subject() {
    Box(
        Modifier
            .size(100.dp)
            .padding(16.dp)
            .background(Color.Red)
    )
}
```

**Do:** put `padding` *before* `size` when you want the padding included in the final footprint (outer → inner: spacing, then sizing, then styling).
**Don't:** put `size` before `padding` and expect the padding to enlarge the element — a later modifier can shrink but never expand a size set earlier in the chain.

Source: `compose/ui/ui/src/commonMain/kotlin/androidx/compose/ui/Modifier.kt`

## Common Modifier Patterns

### Padding and Sizing

```kotlin
// Padding: external spacing around content
Box(Modifier.padding(16.dp)) { }

// Size: exact dimensions (overrides requested size from parent)
Box(Modifier.size(100.dp)) { }
Box(Modifier.size(width = 200.dp, height = 100.dp)) { }

// FillMaxWidth/FillMaxHeight: expand to available space
Box(Modifier.fillMaxWidth(0.8f)) { }  // 80% of parent width
Box(Modifier.fillMaxSize()) { }       // 100% of parent

// Do: apply padding before fillMaxWidth so the child fills the *padded* region
// (padding insets first, then fillMaxWidth expands within that inset area)
Column(Modifier.fillMaxWidth()) {
    Box(Modifier.padding(16.dp).fillMaxWidth()) { }
}

// Don't: apply fillMaxWidth after background if you want background to expand
// Instead:
Box(Modifier.fillMaxWidth().background(Color.Blue)) { }
```

### Background and Border

```kotlin
// Background applies a color to the surface
Box(Modifier.background(Color.Blue)) { }
Box(Modifier.background(Color.Blue, shape = RoundedCornerShape(8.dp))) { }

// Border draws a stroke (order matters!)
Box(
    Modifier
        .size(100.dp)
        .border(2.dp, Color.Black, RoundedCornerShape(8.dp))
        .background(Color.White)
)
// The border is drawn AFTER background in visual order (because modifiers below it are drawn first)

// Combine background + border: apply border first in chain
Box(
    Modifier
        .border(2.dp, Color.Black, RoundedCornerShape(8.dp))
        .background(Color.White)
)
```

### Clipping

```kotlin
// Clip content to a shape
Box(Modifier.clip(RoundedCornerShape(8.dp))) {
    Image(painter = painterResource(id = R.drawable.my_image), contentDescription = "")
}

// Do: apply clip before background if you want background inside the shape
Box(
    Modifier
        .clip(RoundedCornerShape(8.dp))
        .background(Color.Blue)
) { }

// Don't: background then clip. The background is drawn before the clip applies,
// so it keeps square corners.
Box(
    Modifier
        .background(Color.Blue)
        .clip(RoundedCornerShape(8.dp))
) { }
```

## Clickable and Combined Clickable

```kotlin
// Basic click handling with ripple effect (Material 3 default)
Button(onClick = { }) { Text("Click me") }

// Manual clickable with ripple
Box(
    Modifier
        .size(100.dp)
        .clickable(
            indication = ripple(),  // Material ripple feedback
            interactionSource = remember { MutableInteractionSource() }
        ) { /* handle click */ }
)

// Combined clickable: long press + double click + click
Box(
    Modifier
        .combinedClickable(
            onClick = { },
            onLongClick = { },
            onDoubleClick = { },
            indication = ripple()
        )
) { }

// Do: provide explicit interactionSource for testing/state observation
val interactionSource = remember { MutableInteractionSource() }
Box(
    Modifier.clickable(
        interactionSource = interactionSource,
        indication = ripple()
    ) { }
)

// Don't: forget indication parameter (will have no visual feedback)
Box(Modifier.clickable { }) { }  // No ripple
```

## Modifier.composed vs Modifier.Node

The old API (`composed`) is being phased out in favor of the new `ModifierNodeElement` API. Both work, but new code should use the latter.

### Old API: Modifier.composed

```kotlin
fun Modifier.myCustomModifier(value: String) = composed {
    val state = remember { mutableStateOf(value) }
    this.then(
        Modifier
            .background(Color.Blue)
            .clickable { state.value = "updated" }
    )
}
```

- Creates a new composable scope
- Captures composition locals
- Causes recomposition when remember state changes
- Deprecated but still supported

### New API: Modifier.Node

```kotlin
class MyCustomNode(var value: String) : Modifier.Node() {
    override fun onDetach() {
        // Cleanup when removed
    }
}

data class MyCustomElement(val value: String) : ModifierNodeElement<MyCustomNode>() {
    override fun create() = MyCustomNode(value)
    override fun update(node: MyCustomNode) {
        node.value = value
    }
}

fun Modifier.myCustomModifier(value: String) = this.then(MyCustomElement(value))
```

**Do:** Use `Modifier.Node` for new custom modifiers. It's more efficient and doesn't create composition scopes.
**Don't:** Create new `composed` modifiers; migrate existing ones to `Modifier.Node`.

Source: `compose/ui/ui/src/commonMain/kotlin/androidx/compose/ui/modifier/ModifierNodeElement.kt`

## Layout vs Drawing vs Pointer Input Modifiers

Modifiers fall into categories that affect when they execute:

```kotlin
// Layout modifier: affects measurement and layout pass
fun Modifier.customSize(width: Dp, height: Dp) =
    this.then(object : LayoutModifier {
        override fun MeasureScope.measure(measurable: Measurable, constraints: Constraints) =
            measurable.measure(Constraints.fixed(width.roundToPx(), height.roundToPx()))
                .run { layout(width = size.width, height = size.height) { place(0, 0) } }
    })

// Drawing modifier: doesn't affect layout, just draws after content
fun Modifier.customDraw() = drawBehind { drawCircle(Color.Red) }

// Pointer input modifier: handles gestures/events
fun Modifier.detectCustomGesture() = pointerInput(Unit) {
    detectTapGestures { offset -> /* handle */ }
}
```

**Do:** Use layout modifiers for sizing/positioning, drawing modifiers for visual effects, pointer modifiers for input.
**Don't:** Use layout modifiers to create visual effects; use drawing modifiers instead.

## Modifier.graphicsLayer — Performance Implications

`graphicsLayer` applies transformations at the graphics rendering level. It's more efficient than recomposing for animations.

```kotlin
// Efficient: transforms applied on the graphics layer, no recomposition
Box(
    Modifier.graphicsLayer(
        scaleX = 1.2f,
        scaleY = 1.2f,
        translationX = 10f,
        rotationZ = 45f,
        alpha = 0.8f
    )
) { }

// Less efficient: recomposes every frame
var scaleX by remember { mutableStateOf(1f) }
LaunchedEffect(Unit) {
    while (true) {
        scaleX = 1.2f
        delay(16)
    }
}
Box(Modifier.scale(scaleX)) { }
```

**Do:** Use `graphicsLayer` for animations and frequent property changes.
**Don't:** Animate state values that trigger recomposition when `graphicsLayer` would suffice.

Source: `compose/ui/ui/src/commonMain/kotlin/androidx/compose/ui/graphics/GraphicsLayerModifier.kt`

## Modifier.semantics — Accessibility

Semantics describe the meaning of UI elements for screen readers and accessibility tests.

```kotlin
// Add semantic label
Button(onClick = { }) {
    Icon(Icons.Default.Add, contentDescription = null)
    Text("Add item")
}

// Custom semantic properties
Box(
    Modifier
        .size(100.dp)
        .semantics {
            contentDescription = "Custom box"
            onClick(label = "Activate") { true }
        }
) { }

// Do: always provide contentDescription for images
Image(
    painter = painterResource(id = R.drawable.icon),
    contentDescription = "User avatar"
)

// Don't: forget contentDescription (screen readers won't announce it)
Image(painter = painterResource(id = R.drawable.icon), contentDescription = null) // Wrong
```

Source: `compose/ui/ui/src/commonMain/kotlin/androidx/compose/ui/semantics/Semantics.kt`

## Modifier.testTag — UI Testing

```kotlin
// Add a test tag for finding composables in tests
Box(Modifier.testTag("my_box")) { }

// In tests:
composeTestRule.onNodeWithTag("my_box").performClick()
composeTestRule.onNodeWithTag("my_box").assertIsDisplayed()
```

**Do:** Use unique, descriptive test tags.
**Don't:** Use test tags in production code for business logic.

## Review Checklist: Modifier Ordering Bugs

### Hardcoded Size After Caller's `modifier` Parameter

When a composable accepts `modifier: Modifier = Modifier` and chains a fixed `.height()` / `.width()` / `.size()` **after** it, the component's own size silently overrides whatever the caller passed — the caller's size modifier is applied first (outer) and wins.

```kotlin
// BAD: the caller's size (outer) is fixed first, so the component's inner .height(172.dp)
// is coerced back to the caller's value — the component's own 172.dp is silently ignored.
@Composable
fun BannerCard(
    modifier: Modifier = Modifier,
) {
    Box(
        modifier = modifier          // caller constraints applied first (outer) — these win
            .fillMaxWidth()
            .height(172.dp)          // inner — a later modifier can't override a size fixed earlier
            .clip(RoundedCornerShape(18.dp))
            .background(Color.Green.copy(alpha = 0.08f)),
    )
}

// Caller passes 200dp — renders 200dp, NOT 172dp (the outer fixed size wins):
BannerCard(modifier = Modifier.height(200.dp))

// Caller passes 100dp — renders 100dp, and the component's intended 172dp is lost:
BannerCard(modifier = Modifier.height(100.dp))
```

**Why it happens:** the modifier chain resolves outer-to-inner (left-to-right), and a fixed size passes a tight `[X, X]` constraint down. A later `.height(172.dp)` can only operate *within* that constraint — it can shrink but never grow past it — so it is coerced back to the caller's `X`. First (outer) size wins. To let the component set its own default while still honoring the caller, put the component's size **before** `modifier` so the caller can override it: `Modifier.height(172.dp).then(modifier)`.

**Fix option 1:** Component defaults first, caller can override via `.then(modifier)`:
```kotlin
// GOOD: component sets defaults, caller's modifier applied last and can override
@Composable
fun BannerCard(
    modifier: Modifier = Modifier,
) {
    Box(
        modifier = Modifier
            .fillMaxWidth()
            .height(172.dp)
            .clip(RoundedCornerShape(18.dp))
            .background(Color.Green.copy(alpha = 0.08f))
            .then(modifier),         // caller can override size
    )
}
```

**Fix option 2:** Use `defaultMinSize` for flexible sizing:
```kotlin
// GOOD: minimum guaranteed, caller can make it larger
@Composable
fun BannerCard(
    modifier: Modifier = Modifier,
) {
    Box(
        modifier = modifier
            .fillMaxWidth()
            .defaultMinSize(minHeight = 172.dp)  // floor, not ceiling
            .clip(RoundedCornerShape(18.dp))
            .background(Color.Green.copy(alpha = 0.08f)),
    )
}
```

**Rule:** When a composable accepts `modifier: Modifier = Modifier`, never chain fixed `.height()` / `.width()` / `.size()` after the caller's modifier — caller constraints become outer bounds and the component's fixed size either ignores or gets clamped by them. Use `.then(modifier)` at the end or `defaultMinSize` for flexible sizing. Flag in every PR review.

---

## Anti-patterns

### Creating Modifiers in Composition

```kotlin
// Don't: creates a new Modifier every recomposition
@Composable
fun BadModifier() {
    Box(Modifier.padding(16.dp).background(Color.Blue)) { }
}

// Do: extract to a variable or parameter
@Composable
fun GoodModifier(modifier: Modifier = Modifier) {
    Box(modifier.padding(16.dp).background(Color.Blue)) { }
}
```

### Conditional Modifier Chains Done Wrong

```kotlin
// Don't: breaks type checking and readability
val mod = if (isSelected) Modifier.background(Color.Blue) else Modifier
Box(mod.padding(16.dp)) { }

// Do: use then() for conditional chaining
Box(
    Modifier
        .padding(16.dp)
        .then(if (isSelected) Modifier.background(Color.Blue) else Modifier)
) { }
```

---

**Summary:** Master modifier ordering, prefer `Modifier.Node` over `composed`, use `graphicsLayer` for animations, and always consider the semantic layer for accessibility.
brainstormingobra/superpowersYou MUST use this before any creative work - creating features, building components, adding functionality, modifying behavior, or planning anything new, in software or out of it (a talk, a business, a renovation).Stars: 322kUpdated Claude CodeCodexVerifiedInstall
brand-guidelinesanthropics/skillsApplies Anthropic's official brand colors and typography to any sort of artifact that may benefit from having Anthropic's look-and-feel. Use it when brand colors or style guidelines, visual formatting, or company design standards apply.Stars: 197kUpdated Claude CodeCodexVerifiedInstall
frontend-designanthropics/skillsGuidance for distinctive, intentional visual design when building new UI or reshaping an existing one. Helps with aesthetic direction, typography, and making choices that don't read as templated defaults.Stars: 197kUpdated Claude CodeCodexVerifiedInstall
mcp-builderanthropics/skillsGuide for creating high-quality MCP (Model Context Protocol) servers that enable LLMs to interact with external services through well-designed tools. Use when building MCP servers to integrate external APIs or services, whether in Python (FastMCP) or Node/TypeScript (MCP SDK).Stars: 197kUpdated Claude CodeCodexVerifiedInstall