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/styles-experimental.md

View on GitHub
# Compose Styles API (Experimental)

> `@ExperimentalFoundationStyleApi` — `androidx.compose.foundation:foundation:1.11.0-alpha06`
>
> AOSP source: `compose/foundation/foundation/src/commonMain/kotlin/androidx/compose/foundation/style/`

## What is the Styles API?

A declarative, state-driven styling system for Compose. Instead of manually chaining modifiers
and `animateXAsState` calls for every interaction state, you declare all visual states in a
single `Style { }` block. The framework handles state detection, property interpolation, and
animation automatically.

### Before vs After

```kotlin
// BEFORE — 15+ lines of imperative state wiring
val interactionSource = remember { MutableInteractionSource() }
val isPressed by interactionSource.collectIsPressedAsState()
val bgColor by animateColorAsState(
    if (isPressed) Color.DarkBlue else Color.Blue
)
val scale by animateFloatAsState(
    if (isPressed) 0.95f else 1f
)
Box(
    Modifier
        .graphicsLayer { scaleX = scale; scaleY = scale }
        .background(bgColor, RoundedCornerShape(16.dp))
        .clip(RoundedCornerShape(16.dp))
        .clickable(interactionSource = interactionSource, indication = null) { }
        .padding(16.dp)
)

// AFTER — Declarative. Done.
val style = Style {
    background(Color.Blue)
    shape(RoundedCornerShape(16.dp))
    contentPadding(16.dp)
    pressed(Style {
        animate(Style {
            background(Color.DarkBlue)
            scale(0.95f)
        })
    })
}
Box(Modifier.styleable(styleState = styleState, style = style))
```

The mental shift: **stop telling Compose how to animate between states**. Declare what each
state looks like — the framework interpolates.

---

## The Three Pieces

### 1. `Style { }` — Declare Visual States

A `Style` is a `fun interface`. You use the builder DSL:

```kotlin
val cardStyle = Style {
    // Base properties (always applied)
    background(Color(0xFFF5F5F5))
    shape(RoundedCornerShape(12.dp))
    contentPadding(16.dp)

    // State overrides — only applied when state is active
    selected(Style {
        animate(Style {
            background(Color.Blue.copy(alpha = 0.15f))
            borderWidth(2.dp)
            borderColor(Color.Blue)
        })
    })

    disabled(Style {
        background(Color(0xFFE0E0E0))
        contentColor(Color.Gray)  // no animate = instant snap
    })
}
```

`animate(Style { })` wraps properties that should interpolate smoothly.
Without `animate`, state changes snap immediately.

### 2. `MutableStyleState` — Drive State

```kotlin
// For toggle states (checked, selected, enabled) — set explicitly:
val styleState = remember { MutableStyleState(MutableInteractionSource()) }
styleState.isChecked = isChecked
styleState.isSelected = isSelected
styleState.isEnabled = isEnabled

// For interaction states (pressed, hovered, focused) — share interactionSource:
val interactionSource = remember { MutableInteractionSource() }
val styleState = remember { MutableStyleState(interactionSource) }
// isPressed, isHovered, isFocused auto-track from shared interactionSource
```

### 3. `Modifier.styleable()` — Apply to Any Composable

```kotlin
Box(
    Modifier
        .styleable(styleState = styleState, style = cardStyle)
        .clickable(interactionSource = interactionSource, indication = null) { }
)
```

Background renders, shape clips, borders draw, transforms apply, text properties propagate
to children via CompositionLocal. All animated.

---

## CRITICAL: Alpha06 Auto-Detection is Broken

**`styleable(style = myStyle)` without an explicit `styleState` does NOT detect interaction
states from sibling modifiers.** This is the single biggest trap in alpha06.

### What DOESN'T work:

```kotlin
// Compiles. Renders base style. State changes are SILENT.
Box(
    Modifier
        .styleable(style = myStyle)           // no styleState!
        .toggleable(value = isChecked, ...)   // style never sees this
)
```

### What DOES work:

**Pattern A — Toggle states (checked, selected, enabled):**
```kotlin
val styleState = remember { MutableStyleState(MutableInteractionSource()) }
styleState.isChecked = isChecked  // YOU drive the state

Box(
    Modifier
        .styleable(styleState = styleState, style = myStyle)
        .clickable { isChecked = !isChecked }
)
```

**Pattern B — Interaction states (pressed, hovered, focused):**
```kotlin
val interactionSource = remember { MutableInteractionSource() }
val styleState = remember { MutableStyleState(interactionSource) }

Box(
    Modifier
        .styleable(styleState = styleState, style = myStyle)
        .clickable(
            interactionSource = interactionSource,  // same instance!
            indication = null,
        ) { }
)
```

**Pattern C — Both (toggle button with press feedback):**
```kotlin
val interactionSource = remember { MutableInteractionSource() }
val styleState = remember { MutableStyleState(interactionSource) }
styleState.isChecked = isChecked  // explicit for toggle

Box(
    Modifier
        .styleable(styleState = styleState, style = myStyle)
        .clickable(
            interactionSource = interactionSource,
            indication = null,
        ) { isChecked = !isChecked }
)
```

**Rule: always pass `styleState` to `styleable()`.**

---

## Text Property Propagation Gotcha

`contentColor()`, `fontSize()`, `fontWeight()`, `letterSpacing()`, `textDecoration()`, and
other text properties propagate to ALL child composables inside the styleable box via
`CompositionLocal` (`LocalContentColor`, `LocalTextStyle`).

### Problem:
```kotlin
// fontSize(28.sp) from the Style applies to BOTH texts!
Box(Modifier.styleable(style = Style { fontSize(28.sp) })) {
    Text("Title")      // 28sp
    Text("Subtitle")   // also 28sp — overlap!
}
```

### Fix:
Use a single `Text` inside styled boxes when style sets text properties. Move
descriptions outside the styleable scope:

```kotlin
Text("Description goes here")  // outside the styled box
Box(Modifier.styleable(style = gradientStyle)) {
    Text("Title Only")  // only this gets styled
}
```

---

## Verified Properties (alpha06, tested on device)

| Property | Works? | Notes |
|----------|--------|-------|
| `background(Color)` | Yes | Fills behind content |
| `background(Brush)` | Yes | Gradient backgrounds |
| `shape(Shape)` | Yes | Clips content + background |
| `contentPadding(Dp)` | Yes | Inner padding |
| `borderWidth(Dp) + borderColor(Color)` | Yes | Must set both |
| `scale(Float)` | Yes | graphicsLayer transform |
| `rotationZ(Float)` | Yes | graphicsLayer rotation |
| `translationX/Y(Float)` | Yes | graphicsLayer offset |
| `alpha(Float)` | Yes | Opacity |
| `contentColor(Color)` | Yes | Propagates to child Text/Icon |
| `contentBrush(Brush)` | Yes | Gradient text |
| `fontSize(TextUnit)` | Yes | Propagates to children |
| `fontWeight(FontWeight)` | Yes | Propagates to children |
| `letterSpacing(TextUnit)` | Yes | Propagates to children |
| `textDecoration(TextDecoration)` | Yes | Underline, strikethrough |
| `animate(Style { })` | Yes | Smooth spring interpolation |
| `dropShadow(Shadow)` | No | `Shadow` constructor is internal |

---

## Style Composition

Styles compose with `.then()` — later styles override earlier ones per-property:

```kotlin
val base = Style {
    background(Color.Blue)
    shape(RoundedCornerShape(12.dp))
    contentPadding(16.dp)
}

val elevated = Style {
    borderWidth(2.dp)
    borderColor(Color.LightGray)
    scale(1.02f)
}

val dark = Style {
    background(Color(0xFF1E1E2E))  // overrides base's background
    contentColor(Color.White)
}

// Chained:
val composed = base.then(elevated).then(dark)

// Factory (equivalent):
val composed = Style(base, elevated, dark)
```

---

## Building Reusable Components

The Styles API maps to Compose's component conventions. The `style` parameter becomes
first-class, like `modifier`:

```kotlin
// 1. Defaults object — theme-aware default style
@OptIn(ExperimentalFoundationStyleApi::class)
object StyledChipDefaults {
    @Composable
    fun style(): Style {
        val bg = MaterialTheme.colorScheme.secondaryContainer
        val fg = MaterialTheme.colorScheme.onSecondaryContainer
        return Style {
            background(bg)
            shape(RoundedCornerShape(8.dp))
            contentPadding(horizontal = 16.dp, vertical = 8.dp)
            contentColor(fg)
            pressed(Style {
                animate(Style { scale(0.95f) })
            })
        }
    }
}

// 2. Component — style as parameter with default
@Composable
fun StyledChip(
    onClick: () -> Unit,
    modifier: Modifier = Modifier,
    style: Style = StyledChipDefaults.style(),
    content: @Composable () -> Unit,
) {
    val interactionSource = remember { MutableInteractionSource() }
    val styleState = remember { MutableStyleState(interactionSource) }

    Box(
        modifier = modifier
            .styleable(styleState = styleState, style = style)
            .clickable(
                interactionSource = interactionSource,
                indication = null,
                onClick = onClick,
            ),
        contentAlignment = Alignment.Center,
    ) {
        content()
    }
}

// 3. Usage — default, custom, or composed
StyledChip(onClick = {}) { Text("Default") }

StyledChip(
    onClick = {},
    style = Style {
        background(Color.Teal)
        shape(CircleShape)
        contentColor(Color.Black)
    },
) { Text("Custom") }

StyledChip(
    onClick = {},
    style = StyledChipDefaults.style().then(Style {
        borderWidth(2.dp)
        borderColor(Color.Teal)
    }),
) { Text("Composed") }
```

---

## Theme Integration

`StyleScope` extends `CompositionLocalAccessorScope`, so Style blocks can read
`MaterialTheme` values at resolution time:

```kotlin
@Composable
fun ThemedButton() {
    val primary = MaterialTheme.colorScheme.primary
    val onPrimary = MaterialTheme.colorScheme.onPrimary
    val surface = MaterialTheme.colorScheme.surface

    val style = Style {
        background(primary)
        contentColor(onPrimary)
        shape(RoundedCornerShape(12.dp))
        contentPadding(16.dp)
        pressed(Style {
            animate(Style {
                background(surface)
                contentColor(primary)
                scale(0.95f)
            })
        })
    }
    // When theme changes (dark/light), style re-resolves automatically
}
```

Capture theme colors in a `@Composable` scope, use in the Style builder. Theme switches
update all styled elements instantly.

---

## Architecture: How It Works

The API lives in 7 source files under `androidx.compose.foundation.style`:

| File | Purpose |
|------|---------|
| `Style.kt` | `fun interface Style` + composition operators |
| `StyleScope.kt` | ~50 property functions |
| `StyleState.kt` | `StyleState` interface + `MutableStyleState` |
| `StyleModifier.kt` | `Modifier.styleable()` implementation |
| `StyleAnimations.kt` | `animate()` blocks |
| `ResolvedStyle.kt` | Property resolution with bitset flagging |
| `ExperimentalFoundationStyleApi.kt` | Opt-in annotation |

### Two-Node System

`Modifier.styleable()` inserts two modifier nodes:

- **`StyleOuterNode`** — Layout (padding, sizing), drawing (background, border, shape),
  transforms (scale, rotation, translation, alpha). Can invalidate at draw layer only when
  transform/draw properties change — no recomposition.

- **`StyleInnerNode`** — Content padding and text style propagation. Sets `LocalContentColor`,
  `LocalTextStyle`, etc. so child `Text` and `Icon` composables pick up styled colors/fonts.

### Bitset-Based Property Tracking

`ResolvedStyle` uses bitset flags for ~50 properties. On state change:

1. Only the delta between old and new resolved properties is computed
2. Drawing-only changes (background, border, alpha) → **draw-only invalidation** (skips layout + composition)
3. Layout changes (padding, sizing) → layout invalidation
4. Text changes (contentColor, fontSize) → composition invalidation (updates CompositionLocals)

A press animation changing only `scale` and `background` never triggers recomposition.

---

## All StyleScope Properties

### Layout
- `contentPadding(Dp)`, `contentPadding(horizontal, vertical)`, `contentPadding(start, top, end, bottom)`
- `externalPadding(Dp)` and same variants
- `width(Dp)`, `height(Dp)`, `size(Dp)`, `size(width, height)`
- `minWidth/minHeight/maxWidth/maxHeight(Dp)`
- `fillWidth()`, `fillHeight()`, `fillSize()`

### Drawing
- `background(Color)`, `background(Brush)`
- `foreground(Color)`, `foreground(Brush)`
- `shape(Shape)`
- `borderWidth(Dp)`, `borderColor(Color)`, `borderBrush(Brush)`
- `border(width, color)`, `border(width, brush)`

### Transforms
- `scale(Float)`, `scaleX(Float)`, `scaleY(Float)`
- `rotationX(Float)`, `rotationY(Float)`, `rotationZ(Float)`
- `translationX(Float)`, `translationY(Float)`, `translation(x, y)`
- `alpha(Float)`, `clip(Boolean)`, `zIndex(Float)`
- `transformOrigin(TransformOrigin)`

### Text & Content
- `contentColor(Color)`, `contentBrush(Brush)`
- `fontSize(TextUnit)`, `fontWeight(FontWeight)`, `fontStyle(FontStyle)`
- `letterSpacing(TextUnit)`, `lineHeight(TextUnit)`
- `textDecoration(TextDecoration)`, `fontFamily(FontFamily)`
- `textAlign(TextAlign)`, `textDirection(TextDirection)`
- `textStyle(TextStyle)`, `textIndent(TextIndent)`
- `baselineShift(BaselineShift)`, `lineBreak(LineBreak)`
- `hyphens(Hyphens)`, `fontSynthesis(FontSynthesis)`

### Shadows (internal constructor in alpha06)
- `dropShadow(Shadow)`, `innerShadow(Shadow)`

### State Functions
- `pressed(Style)`, `hovered(Style)`, `focused(Style)`
- `selected(Style)`, `checked(Style)`, `disabled(Style)`

### Animation
- `animate(Style)` — default spring
- `animate(spec: AnimationSpec<Float>, Style)` — custom spec
- `animate(toSpec, fromSpec, Style)` — asymmetric enter/exit

### Composition
- `Style.then(other: Style)` — chain (later overrides)
- `Style(style1, style2)` — merge factory
- `Style(vararg styles)` — merge multiple

---

## Common Pitfalls

1. **Forgetting `styleState`** — the #1 bug. Style renders but never reacts to state.
2. **Not sharing `interactionSource`** — pressed/hovered/focused won't track without it.
3. **Multiple Text children in styled box** — all inherit fontSize/fontWeight/contentColor.
4. **Using `toggleable()` / `selectable()`** — they create their own interactionSource internally. Use `.clickable()` and set state explicitly on `MutableStyleState`.
5. **Missing `@OptIn(ExperimentalFoundationStyleApi::class)`** — required on all usages.
6. **Trying to use `dropShadow()`** — `Shadow` constructor is internal in alpha06, won't compile.
7. **No `indication = null` on clickable** — without it you get default ripple on top of your styled feedback.
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: 198kUpdated 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: 198kUpdated 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: 198kUpdated Claude CodeCodexVerifiedInstall