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/accessibility.md

View on GitHub
# Accessibility Reference

## Semantics — Exposing UI to Accessibility Services

Semantics describe UI elements to screen readers, voice commands, and testing tools. Compose generates semantics automatically for built-in components, but custom views require manual annotation.

```kotlin
// Built-in components have semantics
Button(onClick = { }) { Text("Click me") }  // Auto-announces as button

// Custom composables need explicit semantics
Box(
    modifier = Modifier.semantics {
        role = Role.Button
        onClick(label = "Activate") { true }
    }
) {
    Text("Custom button")
}
```

Executable smoke check for built-in button semantics:

```kotlin verify
// name: button-text-exposes-click-action
// repeat: 3
// assert: text = "Click me"
// assert: has-click-action = "Click me"
// assert-not: text = "Delete"
@Composable
fun Subject() {
    Button(onClick = { }) { Text("Click me") }
}
```

**Source**: `androidx/compose/ui/semantics/`

---

## contentDescription — Labels for Accessibility

Every meaningful visual element needs a label for screen readers.

### When to Set contentDescription

**DO**: Images, icons, buttons without text, decorative with meaningful purpose

```kotlin
// Icon in a button: set contentDescription
Button(onClick = { }) {
    Icon(Icons.Default.Settings, contentDescription = "App settings")
}

// Text-only button: contentDescription auto-generated
Button(onClick = { }) { Text("Save") }

// Standalone image: always set description
Image(
    painter = painterResource(R.drawable.product),
    contentDescription = "Product photo: wireless headphones"
)
```

### When to Set contentDescription = null

**Purely decorative images** that convey no information:

```kotlin
// Decorative divider line
Divider(modifier = Modifier.padding(vertical = 8.dp))

// Purely decorative background
Box(
    modifier = Modifier
        .background(Color.Gray)
        .size(100.dp)
) {
    Image(
        painter = painterResource(R.drawable.background_pattern),
        contentDescription = null  // Purely decorative
    )
}

// Icon next to label: skip icon description
Row {
    Icon(
        painter = painterResource(R.drawable.verified),
        contentDescription = null,  // Label below describes it
        tint = Color.Green
    )
    Text("Verified")
}
```

Omitting `contentDescription` or using `null` tells the screen reader to skip the element.

---

## Modifier.semantics — Merging and Overriding

### Default Merging

By default, child semantics merge with parents:

```kotlin
// Child text is included in parent semantics
Column(modifier = Modifier.semantics { heading() }) {
    Text("Section Title")  // Screen reader: "Section Title, heading"
}
```

### Clearing and Setting Semantics

Use `clearAndSetSemantics` to override all child semantics:

```kotlin
// Screen reader ignores children, announces custom label
Box(
    modifier = Modifier.clearAndSetSemantics {
        contentDescription = "Custom audio player with play/pause"
    }
) {
    Icon(Icons.Default.PlayArrow, contentDescription = null)
    Text("00:30")  // Not read
    Icon(Icons.Default.VolumeUp, contentDescription = null)  // Not read
}
```

### Merging Disabled

Prevent children from merging:

```kotlin
Box(
    modifier = Modifier.semantics(mergeDescendants = false) {
        heading()
    }
) {
    Text("Heading")  // Announced separately, not merged
}
```

---

## Touch Target Sizing

Minimum touch target is 48dp × 48dp per Material Design and WCAG guidelines.

```kotlin
// Small button without sufficient touch target
Button(modifier = Modifier.size(32.dp)) { }  // TOO SMALL

// Proper touch target
Button(
    modifier = Modifier.sizeIn(minWidth = 48.dp, minHeight = 48.dp)
) { }

// Alternative: add padding
Box(
    modifier = Modifier
        .size(32.dp)
        .sizeIn(minWidth = 48.dp, minHeight = 48.dp)
) {
    Icon(Icons.Default.Edit, contentDescription = "Edit")
}

// For clickable elements without Button
Box(
    modifier = Modifier
        .clip(RoundedCornerShape(8.dp))
        .clickable { /* ... */ }
        .sizeIn(minWidth = 48.dp, minHeight = 48.dp),
    contentAlignment = Alignment.Center
) {
    Icon(Icons.Default.Close, contentDescription = "Close")
}
```

---

## Headings — Screen Reader Navigation

Headings allow users to navigate by section. Set heading semantic:

```kotlin
// Level 1 heading
Text(
    text = "Products",
    modifier = Modifier.semantics { heading() },
    style = MaterialTheme.typography.headlineLarge
)

// Subheading (no formal levels in Compose; use structure)
Text(
    text = "New Arrivals",
    modifier = Modifier.semantics { heading() },
    style = MaterialTheme.typography.headlineMedium
)
```

Screen readers announce "heading" and allow jumping between sections. Use headings to structure content logically, not for styling.

---

## Custom Actions

Allow screen readers to trigger complex interactions:

```kotlin
@Composable
fun SlideToUnlock() {
    Box(
        modifier = Modifier
            .fillMaxWidth()
            .height(64.dp)
            .semantics {
                customActions = listOf(
                    CustomAccessibilityAction(label = "Unlock") {
                        unlock()
                        true
                    },
                    CustomAccessibilityAction(label = "Emergency call") {
                        emergencyCall()
                        true
                    }
                )
            }
            .background(MaterialTheme.colorScheme.primary)
    ) {
        Text("Slide to Unlock", color = Color.White)
    }
}
```

Custom actions appear in the accessibility menu. Avoid for standard interactions (Button, Checkbox).

---

## Traversal Order

Control screen reader navigation order explicitly when needed:

```kotlin
// Default: top-to-bottom, left-to-right
Row {
    Button(onClick = { }) { Text("First") }
    Button(onClick = { }) { Text("Second") }
}

// Custom order (right-to-left)
Row {
    Button(
        onClick = { },
        modifier = Modifier.semantics { traversalIndex = 1f }
    ) { Text("Read Second") }
    Button(
        onClick = { },
        modifier = Modifier.semantics { traversalIndex = 0f }
    ) { Text("Read First") }
}

// Group items as single traversal unit
Column(
    modifier = Modifier.semantics(mergeDescendants = false) {
        isTraversalGroup = true
    }
) {
    Text("Label")
    Text("Value")
}
```

Use `traversalIndex` sparingly. Good structure is usually sufficient.

---

## State Descriptions

Inform users of component state (enabled/disabled, checked/unchecked):

```kotlin
@Composable
fun AccessibleCheckbox(
    checked: Boolean,
    onCheckedChange: (Boolean) -> Unit,
    label: String
) {
    Row(
        modifier = Modifier
            .clip(RoundedCornerShape(8.dp))
            .clickable { onCheckedChange(!checked) }
            .semantics {
                this.contentDescription = label
                this.stateDescription = if (checked) "Checked" else "Unchecked"
                role = Role.Checkbox
            }
            .sizeIn(minWidth = 48.dp, minHeight = 48.dp)
    ) {
        Icon(
            if (checked) Icons.Default.CheckBox else Icons.Default.CheckBoxOutlineBlank,
            contentDescription = null,
            tint = MaterialTheme.colorScheme.primary
        )
        Text(label, modifier = Modifier.padding(start = 12.dp))
    }
}
```

Screen reader announces: "Label, Checkbox, Checked" or "Label, Checkbox, Unchecked".

---

## Live Regions

Announce dynamic content changes without requiring interaction:

```kotlin
@Composable
fun LiveMessage(message: String, modifier: Modifier = Modifier) {
    Text(
        text = message,
        modifier = modifier.semantics {
            liveRegion = LiveRegionMode.Assertive  // Polite or Assertive
        }
    )
}

// Usage
var status by remember { mutableStateOf("Loading...") }

LaunchedEffect(Unit) {
    delay(2000)
    status = "Done loading"  // Screen reader announces immediately
}

LiveMessage(message = status)
```

**Assertive**: Interrupts current speech. Use for critical updates (error, alert).
**Polite**: Queues after current speech. Use for status updates.

---

## Testing Semantics

Use Compose Test APIs to verify accessibility:

```kotlin
@get:Rule
val composeTestRule = createComposeRule()

@Test
fun testContentDescription() {
    composeTestRule.setContent {
        Icon(
            Icons.Default.Settings,
            contentDescription = "App settings"
        )
    }

    composeTestRule
        .onNodeWithContentDescription("App settings")
        .assertIsDisplayed()
}

@Test
fun testHeading() {
    composeTestRule.setContent {
        Text("Main Title", modifier = Modifier.semantics { heading() })
    }

    composeTestRule
        .onNode(isHeading())
        .assertIsDisplayed()
        .assertTextEquals("Main Title")
}

@Test
fun testTouchTarget() {
    composeTestRule.setContent {
        Button(modifier = Modifier.size(32.dp)) { Text("Too small") }
    }

    composeTestRule
        .onNodeWithText("Too small")
        .assertHeightIsAtLeast(48.dp)  // Fails: 32.dp < 48.dp
}

@Test
fun testCustomAction() {
    composeTestRule.setContent {
        Box(
            modifier = Modifier.semantics {
                customActions = listOf(
                    CustomAccessibilityAction("Unlock") { true }
                )
            }
        )
    }

    composeTestRule
        .onNode(hasCustomAccessibilityAction("Unlock"))
        .performCustomAccessibilityAction("Unlock")
}
```

---

## Anti-Patterns

### Decorative Images Without null contentDescription

```kotlin
// DON'T: Screen reader reads useless description
Image(
    painter = painterResource(R.drawable.separator_line),
    contentDescription = "Line"  // No value
)

// DO
Image(
    painter = painterResource(R.drawable.separator_line),
    contentDescription = null
)
```

### Clickable Without Semantics

```kotlin
// DON'T: No semantic role or description
Box(
    modifier = Modifier
        .clickable { deleteItem() }
        .size(32.dp)
) {
    Icon(Icons.Default.Delete, contentDescription = null)
}

// DO
Box(
    modifier = Modifier
        .clickable { deleteItem() }
        .sizeIn(minWidth = 48.dp, minHeight = 48.dp)
        .semantics {
            role = Role.Button
            contentDescription = "Delete item"
        },
    contentAlignment = Alignment.Center
) {
    Icon(Icons.Default.Delete, contentDescription = null)
}
```

### Hardcoded Content Descriptions Without Context

```kotlin
// DON'T: Generic, doesn't describe purpose
Icon(Icons.Default.Star, contentDescription = "Icon")

// DO: Specific
Icon(Icons.Default.Star, contentDescription = "Add to favorites")
```

### Missing Heading Structure

```kotlin
// DON'T: No navigation structure
Column {
    Text("Section 1")
    Text("Section 2")
    Text("Section 3")
}

// DO
Column {
    Text("Section 1", modifier = Modifier.semantics { heading() })
    Text("Section 2", modifier = Modifier.semantics { heading() })
    Text("Section 3", modifier = Modifier.semantics { heading() })
}
```

---

## Resources

- **Compose Accessibility**: https://developer.android.com/develop/ui/compose/accessibility
- **Material Design Accessibility**: https://m3.material.io/foundations/accessible-design
- **WCAG 2.1**: https://www.w3.org/WAI/WCAG21/quickref/
- **Testing A11y in Compose**: https://developer.android.com/develop/ui/compose/testing#a11y
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