jetpack-compose-material3-expert-skill

name: jetpack-compose-material3-expert-skill description: Write, review, or improve Jetpack Compose UI using Material Design 3, adaptive layout/navigation patterns, and modern Compose state/performance practices. Use when building new Android Compose screens, refactoring existing Compose code, auditing M3 theming, adapting UI for tablets/foldables, or aligning implementation with official Android guidance and the Reply sample app.

Jetpack Compose Material3 Expert Skill

Overview

Use this skill to implement and review Material 3 Compose code with strong defaults for theme architecture, adaptive navigation, state hoisting, performance, and accessibility. Prefer official Android APIs and naming, then use Reply sample patterns when choosing between multiple valid implementations.

Workflow Decision Tree

1) Review existing Compose code

• Verify M3 theme setup and token usage (see references/material3-theming.md)
• Verify adaptive layout/navigation logic and size-class handling (see references/adaptive-navigation-layout.md)
• Verify state ownership and Flow collection patterns (see references/state-management.md)
• Verify recomposition and lazy list performance patterns (see references/performance-patterns.md)
• Verify accessibility semantics, touch targets, and contrast assumptions (see references/accessibility.md)
• Compare architecture decisions against Reply sample patterns when relevant (see references/reply-sample-patterns.md)

2) Improve existing Compose code

• Replace hardcoded visual values with semantic M3 tokens from MaterialTheme
• Introduce dynamic color with API-level fallback if missing
• Move navigation and pane selection to explicit adaptive logic
• Hoist screen UI state to a state holder (ViewModel for screen-level concerns)
• Introduce stable lazy-list keys and reduce unnecessary recomposition triggers
• Fix accessibility gaps in roles, labels, and text/touch scaling behavior

3) Implement a new feature

• Define theme contract first (color, typography, shapes, surface roles)
• Define adaptive behavior by window width class and posture requirements
• Choose navigation shell (NavigationSuiteScaffold or explicit bar/rail/drawer)
• Define state model (UiState) and event contract before writing composables
• Build composables as stateless UI + callbacks where practical
• Add previews across multiple size classes and verify behavior parity

Core Guidelines

Material 3 Theming

• Build a single app theme entry point with MaterialTheme(colorScheme, typography, shapes)
• Use lightColorScheme and darkColorScheme as baseline schemes
• Enable dynamic color on Android 12+ via dynamicLightColorScheme / dynamicDarkColorScheme, with explicit fallback
• Prefer semantic roles (primary, surfaceContainerHigh, onSurfaceVariant) over raw color literals
• Keep component theming local unless a full-system token change is required

Adaptive Layout and Navigation

• Drive layout from current window size class, not device type assumptions
• Treat width class as the primary branching signal; include height/posture where needed
• Use NavigationSuiteScaffold when automatic bar/rail/drawer switching is desired
• Customize navigation type when product ergonomics require different breakpoints
• Handle foldable postures with FoldingFeature data when content can intersect a hinge

State and Data Flow

• Hoist state to the lowest common ancestor that needs to read/write it
• Keep local UI element state in remember / rememberSaveable
• Keep screen UI state in a dedicated holder (typically a ViewModel on Android)
• Expose immutable StateFlow for UI state and collect with collectAsStateWithLifecycle
• Pass state and callbacks down; do not pass ViewModel instances deep into leaf composables

Performance

• Use remember for expensive computations that should survive recomposition
• Use derivedStateOf for frequently changing inputs to limit downstream recompositions
• Always provide stable key values in LazyColumn/LazyRow
• Avoid mutating state from a stale point in composition ("backwards writes")
• Keep composables small and isolate changing state to reduce recomposition scope

Accessibility

• Prefer Material components first; they include strong semantics defaults
• Add meaningful descriptions for non-text interactive content
• Ensure interactive elements maintain usable target sizes
• Validate contrast and readability when overriding color roles
• Verify large text/scale behavior and traversal order in adaptive layouts

Reply-Informed Patterns

• Use a wrapper layer to decide navigation shell type from adaptive info
• Separate content type (single-pane vs dual-pane) from navigation type
• Keep list/detail logic explicit for medium and expanded layouts
• Model screen state as a single UiState object published by StateFlow

Quick Reference

Window Width Classes

Navigation Mapping (Common M3 Pattern)

Dynamic Color with Fallback

val colorScheme = when {
    dynamicColor && Build.VERSION.SDK_INT >= Build.VERSION_CODES.S ->
        if (darkTheme) dynamicDarkColorScheme(context) else dynamicLightColorScheme(context)
    darkTheme -> darkColorScheme()
    else -> lightColorScheme()
}

Review Checklist

Theme

• App theme defines colorScheme, typography, and shapes in one place
• Dynamic color is API-gated and has light/dark fallback
• UI uses semantic M3 roles instead of raw colors

Adaptive

• UI behavior changes from WindowSizeClass (not device heuristics only)
• Navigation shell is appropriate for compact/medium/expanded widths
• Fold/posture handling exists where hinge overlap is possible
• Preview coverage includes at least compact + medium + expanded scenarios

State

• Screen UI state comes from a dedicated state holder
• UI collects StateFlow with lifecycle awareness
• Composables receive state and events, not deep ViewModel dependencies
• rememberSaveable is used for restorable local UI element state

Performance

• Expensive computations are cached with remember
• Rapidly changing derived values use derivedStateOf when needed
• Lazy lists use stable keys
• No avoidable wide-scope recomposition triggers

Accessibility

• Interactive elements are labeled and discoverable
• Contrast remains valid after theme overrides
• Typography/layout remain usable at larger font scales
• Navigation and content order remain clear across adaptive layouts

References

• references/material3-theming.md - M3 theme architecture, color roles, dynamic color
• references/adaptive-navigation-layout.md - Window size classes, adaptive nav, fold posture
• references/state-management.md - State hoisting, ViewModel boundaries, Flow collection
• references/performance-patterns.md - Recomposition, lazy list keys, derived state, caching
• references/accessibility.md - Compose accessibility checks and semantic guidance
• references/reply-sample-patterns.md - File-level patterns from the Reply sample app

Philosophy

This skill optimizes for practical, production-safe Compose guidance:

• Prefer official Android APIs over custom abstractions when both solve the task
• Keep architecture explicit and testable, not framework-heavy
• Treat adaptive behavior as first-class product behavior, not a later patch
• Favor semantic M3 design tokens and accessibility by default