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/theming-material3.md

View on GitHub
# Material 3 Theming Reference

## MaterialTheme Basics

`MaterialTheme` is the root provider for design tokens in Compose Material 3. It establishes `colorScheme`, `typography`, and `shapes` across your app.

```kotlin verify
// name: material-theme-provides-tokens
// repeat: 3
// assert: text = "Uses MaterialTheme.typography.bodyLarge"
// assert-not: text = "MaterialExpressiveTheme"
@Composable
fun Subject() {
    MaterialTheme(
        colorScheme = lightColorScheme(),
        typography = Typography(),
        shapes = Shapes()
    ) {
        // All descendants access tokens via MaterialTheme
        Scaffold {
            Text("Uses MaterialTheme.typography.bodyLarge")
        }
    }
}
```

**Source**: `androidx/compose/material3/MaterialTheme.kt`

---

## ColorScheme — Light and Dark

A `ColorScheme` bundles 29+ semantic color tokens (primary, secondary, error, surface, etc.).

### Default Light/Dark Schemes

```kotlin
// Light (default)
val lightColors = lightColorScheme(
    primary = Color(0xFF6200EE),
    secondary = Color(0xFF03DAC6)
)

// Dark
val darkColors = darkColorScheme(
    primary = Color(0xFFBB86FC),
    secondary = Color(0xFF03DAC6)
)

MaterialTheme(colorScheme = if (isDark) darkColors else lightColors) { ... }
```

### Dynamic Color (Material You)

Android 12+ supports extracting colors from wallpaper. Check `Build.VERSION.SDK_INT` before calling:

```kotlin
val colorScheme = if (Build.VERSION.SDK_INT >= Build.VERSION_CODES.S) {
    val context = LocalContext.current
    if (isDark) {
        dynamicDarkColorScheme(context)
    } else {
        dynamicLightColorScheme(context)
    }
} else {
    if (isDark) darkColorScheme() else lightColorScheme()
}

MaterialTheme(colorScheme = colorScheme) { ... }
```

This requires `android:READ_MEDIA_IMAGES` or context access. `dynamicColorScheme` APIs are in `androidx.compose.material3`.

---

## Typography — Custom Type Scales

`Typography` defines `displayLarge`, `headlineSmall`, `bodyLarge`, `labelSmall`, etc.

### Using Google Fonts

```kotlin
val Poppins = FontFamily(
    Font(R.font.poppins_regular, weight = FontWeight.Normal),
    Font(R.font.poppins_bold, weight = FontWeight.Bold),
    Font(R.font.poppins_italic, weight = FontWeight.Normal, style = FontStyle.Italic)
)

val customTypography = Typography(
    displayLarge = TextStyle(
        fontFamily = Poppins,
        fontSize = 57.sp,
        lineHeight = 64.sp,
        letterSpacing = (-0.25).sp
    ),
    bodyMedium = TextStyle(
        fontFamily = Poppins,
        fontSize = 14.sp,
        lineHeight = 20.sp
    )
)

MaterialTheme(typography = customTypography) { ... }
```

All M3 type styles follow a 15-level scale. Partial overrides keep defaults for unspecified styles.

---

## Shapes — Corner Radius Customization

`Shapes` defines `extraSmall`, `small`, `medium`, `large`, `extraLarge` corner radii.

```kotlin
val customShapes = Shapes(
    extraSmall = RoundedCornerShape(4.dp),
    small = RoundedCornerShape(8.dp),
    medium = RoundedCornerShape(12.dp),
    large = RoundedCornerShape(16.dp),
    extraLarge = RoundedCornerShape(28.dp)
)

MaterialTheme(shapes = customShapes) { ... }

// Use in components
Button(
    modifier = Modifier.clip(MaterialTheme.shapes.large)
) { ... }
```

Components automatically use theme shapes via `Surface` and `Card`.

---

## Dark Theme

### isSystemInDarkTheme()

Check system dark mode setting:

```kotlin
@Composable
fun MyApp() {
    val isDark = isSystemInDarkTheme()
    MaterialTheme(colorScheme = if (isDark) darkColorScheme() else lightColorScheme()) {
        // Content
    }
}
```

### Manual Toggle with Persistence

For user-selectable dark mode:

```kotlin
val darkModeState = rememberSaveable { mutableStateOf(isSystemInDarkTheme()) }

MaterialTheme(colorScheme = if (darkModeState.value) darkColorScheme() else lightColorScheme()) {
    Scaffold(
        floatingActionButton = {
            FloatingActionButton(onClick = { darkModeState.value = !darkModeState.value }) {
                Icon(Icons.Default.Settings, "Toggle theme")
            }
        }
    ) {
        // Content
    }
}
```

Persist selection via DataStore or SharedPreferences.

---

## Component-Level Styling

Use `MaterialTheme` tokens for colors, not hardcoded values:

```kotlin
// DO
Text(
    text = "Hello",
    color = MaterialTheme.colorScheme.onSurface,
    style = MaterialTheme.typography.bodyLarge
)

// DON'T
Text(text = "Hello", color = Color.Black, fontSize = 14.sp)
```

Common tokens:
- `primary`, `secondary`, `tertiary` — accent colors
- `surface`, `surfaceVariant` — container backgrounds
- `onPrimary`, `onSurface`, `onError` — text/content on colored backgrounds
- `error`, `errorContainer` — error states

---

## Surface vs Box

**Surface**: styled container with elevation, background from `colorScheme.surface`, respects theme.

```kotlin
Surface(
    color = MaterialTheme.colorScheme.surface,
    modifier = Modifier.fillMaxWidth()
) {
    // Has elevation, shadow
    Text("Themed container")
}
```

**Box**: plain container, no theming assumptions.

```kotlin
Box(
    modifier = Modifier
        .fillMaxWidth()
        .background(MaterialTheme.colorScheme.surface)
) {
    // Manual styling
    Text("Manual background")
}
```

Use `Surface` for semantic containers (cards, dialogs). Use `Box` for layout grouping.

---

## Scaffold — Layout Integration

`Scaffold` composes `topBar`, `floatingActionButton`, `snackbarHost`, and content with proper padding:

```kotlin
Scaffold(
    topBar = {
        TopAppBar(
            title = { Text("My App") },
            colors = TopAppBarDefaults.topAppBarColors(
                containerColor = MaterialTheme.colorScheme.primaryContainer
            )
        )
    },
    floatingActionButton = {
        FloatingActionButton(
            onClick = { /* ... */ },
            containerColor = MaterialTheme.colorScheme.tertiary
        ) {
            Icon(Icons.Default.Add, "Add item")
        }
    },
    snackbarHost = { SnackbarHost(it) }
) { innerPadding ->
    LazyColumn(modifier = Modifier.padding(innerPadding)) {
        // Content respects safe area
    }
}
```

`Scaffold` handles insets and spacing automatically. Don't nest `Scaffold` components.

---

## Extending Theme with CompositionLocal

Add custom design tokens:

```kotlin
data class AppColors(
    val brandPrimary: Color = Color(0xFF6200EE),
    val brandSecondary: Color = Color(0xFF03DAC6),
    val neutral: Color = Color.Gray
)

val LocalAppColors = compositionLocalOf { AppColors() }

@Composable
fun AppTheme(content: @Composable () -> Unit) {
    val appColors = AppColors()
    CompositionLocalProvider(LocalAppColors provides appColors) {
        MaterialTheme {
            content()
        }
    }
}

// Use custom tokens
@Composable
fun MyButton() {
    Button(
        colors = ButtonDefaults.buttonColors(
            containerColor = LocalAppColors.current.brandPrimary
        )
    ) { }
}
```

---

## Material 3 Expressive

M3 Expressive is the latest iteration of Material Design 3 — research-backed
enhancements to theming, components, motion, and typography, aligned with the
Android 16 visual style. It is *not* a separate library: the expressive
components ship inside `androidx.compose.material3:material3`, and most are still
behind an experimental opt-in.

> **Stability:** the expressive component APIs are annotated
> `@ExperimentalMaterial3ExpressiveApi` and their exact parameter lists still
> shift across `compose-bom` alphas. Treat every signature below as *shape, not
> gospel* — confirm against the BOM version you actually resolve. This is
> verified opt-in behavior, not the frozen final API.

### MaterialExpressiveTheme

Expressive components expect an expressive theme in scope. Use
`MaterialExpressiveTheme` instead of `MaterialTheme` at the app root when you
adopt expressive components — it wires the expressive color, shape, and motion
defaults (including `MotionScheme.expressive()`; see
`references/material3-motion.md`).

```kotlin
@OptIn(ExperimentalMaterial3ExpressiveApi::class)
@Composable
fun App() {
    MaterialExpressiveTheme(
        colorScheme = expressiveLightColorScheme(), // or dynamic / dark
        // motionScheme defaults to MotionScheme.expressive() under this theme
    ) {
        // expressive components resolve their defaults from here
    }
}
```

**Do:** wrap expressive components in `MaterialExpressiveTheme`.
**Don't:** drop an expressive component inside a plain `MaterialTheme` and expect
expressive motion/shape defaults — you get the standard scheme.

### Expressive components — what each is for

Each is `@ExperimentalMaterial3ExpressiveApi`; wrap the call site (or file) in
`@OptIn(ExperimentalMaterial3ExpressiveApi::class)`. Parameter lists shown are
the *shape* — verify against your BOM.

- **`ButtonGroup`** — a connected row of buttons that share a group shape and
  react as a set (press animations reflow neighbors). For segmented, related
  actions where a `Row` of separate buttons would read as disconnected.

  ```kotlin
  @OptIn(ExperimentalMaterial3ExpressiveApi::class)
  ButtonGroup(
      overflowIndicator = { /* menu for items past the width */ },
  ) {
      // clickableItem(...) / toggleableItem(...) entries — confirm the exact
      // scope API against your BOM
  }
  ```

- **`SplitButton`** — a primary action fused with a secondary trailing
  affordance (usually a dropdown). Two tap targets, one visual unit.

  ```kotlin
  @OptIn(ExperimentalMaterial3ExpressiveApi::class)
  SplitButtonLayout(
      leadingButton = { /* SplitButtonDefaults.LeadingButton { ... } */ },
      trailingButton = { /* SplitButtonDefaults.TrailingButton { ... } */ },
  )
  ```

- **`FloatingActionButtonMenu` + `ToggleFloatingActionButton`** — a FAB that
  expands into a menu of related actions. The toggle FAB is the button that
  opens/closes; the menu holds the items.

  ```kotlin
  @OptIn(ExperimentalMaterial3ExpressiveApi::class)
  FloatingActionButtonMenu(
      expanded = expanded,
      button = {
          ToggleFloatingActionButton(
              checked = expanded,
              onCheckedChange = { expanded = it },
          ) { /* icon */ }
      },
  ) {
      // FloatingActionButtonMenuItem(...) entries
  }
  ```

- **`LoadingIndicator`** — the expressive progress indicator, including the
  contained and "wavy" variants. Replaces a plain `CircularProgressIndicator`
  where the expressive look is wanted.

  ```kotlin
  @OptIn(ExperimentalMaterial3ExpressiveApi::class)
  LoadingIndicator() // determinate overload takes a progress lambda
  ```

- **`HorizontalFloatingToolbar`** — a floating, pill-shaped toolbar of actions
  that hovers over content (often paired with an attached FAB).

  ```kotlin
  @OptIn(ExperimentalMaterial3ExpressiveApi::class)
  HorizontalFloatingToolbar(expanded = true) {
      // action IconButtons
  }
  ```

### Expressive shape & typography

The expressive theme ships a richer shape scale (more corner sizes, including
larger and asymmetric families) and expressive type roles. Read them from the
theme rather than hardcoding — `MaterialTheme.shapes` / `MaterialTheme.typography`
resolve to the expressive values under `MaterialExpressiveTheme`.

---

## Anti-Patterns

### Hardcoding Colors
```kotlin
// DON'T
Text("Hello", color = Color(0xFF000000))

// DO
Text("Hello", color = MaterialTheme.colorScheme.onSurface)
```

### Ignoring Theme in Reusable Components
```kotlin
// DON'T
fun MyCard(content: @Composable () -> Unit) {
    Box(modifier = Modifier.background(Color.White))
}

// DO
fun MyCard(content: @Composable () -> Unit) {
    Surface(
        color = MaterialTheme.colorScheme.surface,
        shape = MaterialTheme.shapes.medium
    ) {
        content()
    }
}
```

### Mixing Material 2 and Material 3
Don't import both `androidx.compose.material` and `androidx.compose.material3`. Choose M3 for new projects.

### Expressive components without an expressive theme
Don't place `ButtonGroup`, `SplitButton`, `FloatingActionButtonMenu`, etc. under
a plain `MaterialTheme`. Without `MaterialExpressiveTheme` they fall back to the
standard motion/shape scheme and lose the expressive feel they exist for. Also
don't scatter `@OptIn(ExperimentalMaterial3ExpressiveApi::class)` and then pin an
old `compose-bom` — the signatures move between alphas; keep the BOM current.

### Not Providing All Theme Parameters
Partial `MaterialTheme` calls may leave descendants with defaults:

```kotlin
// Unsafe if colorScheme varies by locale
MaterialTheme(typography = customTypography) { ... }

// Better
MaterialTheme(
    colorScheme = currentColorScheme,
    typography = currentTypography,
    shapes = currentShapes
) { ... }
```

---

## Resources

- **Material 3 Tokens**: https://m3.material.io/
- **Compose Material3 Docs**: https://developer.android.com/develop/ui/compose/designsystems/material3
- **Dynamic Color**: Requires `androidx.compose.material3:material3` >= 1.1.0 and Android 12+
- **M3 Expressive**: https://developer.android.com/develop/ui/compose/designsystems/material3 — expressive components live in `androidx.compose.material3:material3` behind `@ExperimentalMaterial3ExpressiveApi`; confirm signatures against your resolved `compose-bom`.
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