/native

Android Material 3 (incl. Expressive)

Google's Material Design 3 reference for the Native skill. Material 3 Expressive-aware (Google I/O 2025). Source: https://m3.material.io/ Last validated against secondary sources: 2026-05 (cutoff). For canonical wording, always re-fetch the official URL.

Scope

Material 3 (M3) is Google's open-source design system for Android, Wear OS, Web, and Flutter. Material 3 Expressive (announced Google I/O 2025-05-13) is the largest update since M3's introduction — research-backed evolution covering theming, components, motion, shape, and typography.

This reference is structured to match m3.material.io — Foundations / Styles / Components / Patterns / Develop — with Jetpack Compose API mappings and links back into SKILL.md.

Top-level Sections

1. Material 3 Expressive

The 2025 evolution. Backed by more user research than any previous M3 update. Available via Compose Material 3 1.4+ / BOM 2025.12+.

What changed

When to apply Expressive

• New screens / new apps: default to Expressive components from day 1.
• Existing apps: opt in per surface. Start with non-critical screens (settings, secondary tabs) to validate motion/shape adoption with users.
• Branded / consumer apps: Expressive is named "Expressive" because it leans into brand personality — strong fit for media, lifestyle, social, retail.
• Enterprise / utility apps: still benefit, but adopt conservatively — heavy motion can fatigue daily-use surfaces.

Adoption checklist

• Compose BOM ≥ 2025.12 / Material 3 artifact ≥ 1.4.0
• Kotlin ≥ 2.0.20 (Strong Skipping); Compose Compiler bundled with Kotlin since 2.0.0
• Use new spring tokens via MaterialTheme.motionScheme (don't hard-code tween(300))
• Migrate BottomAppBar → FlexibleBottomAppBar where height flexibility helps
• Replace indeterminate CircularProgressIndicator → LoadingIndicator (richer motion, accessibility-improved announcements)
• Add FloatingToolbar for contextual actions where you previously stuffed icons into the top app bar

→ Implementation: SKILL.md Native Stack Defaults / UI row, reference/modern-stack.md

2. Foundations

Accessibility

• TalkBack labels: Modifier.semantics { contentDescription = ... } or Modifier.clearAndSetSemantics.
• Touch target minimum: 48×48 dp (M3 baseline; matches Android platform). Use Modifier.minimumInteractiveComponentSize() to enforce.
• Color contrast: WCAG AA (4.5:1 normal, 3:1 large). M3's tonal palette generation respects this when seed color is appropriate.
• TalkBack focus order: Modifier.semantics { isTraversalGroup = true; traversalIndex = ... }.
• Live regions: Modifier.semantics { liveRegion = LiveRegionMode.Polite } for snackbars, error messages.
• Reduce animations: respect Settings.Global.ANIMATOR_DURATION_SCALE == 0f and accessibilityManager.isReduceMotionEnabled.

Adaptive design

Window Size Classes (compact / medium / expanded / large / extra-large — last two added in 2025):

API: androidx.compose.material3.adaptive 1.2+. Use NavigationSuiteScaffold (compact → NavigationBar; medium → NavigationRail; expanded → PermanentNavigationDrawer) for adaptive top-level navigation. Use ListDetailPaneScaffold / SupportingPaneScaffold / ThreePaneScaffold for list-detail and supporting layouts.

Customization

• Theme builder approach: pick seed color → tonal palette generation → light + dark schemes → component override.
• Dynamic Color (API 31+): dynamicLightColorScheme(context) / dynamicDarkColorScheme(context) extracts palette from user wallpaper.
• Brand override: provide a fixed ColorScheme when brand is non-negotiable; still respect dark/light + Reduce Transparency.

Design tokens

Single source of truth for style values. M3 publishes:

Compose: tokens are exposed via MaterialTheme.colorScheme, MaterialTheme.typography, MaterialTheme.shapes, MaterialTheme.motionScheme (Expressive).

Interaction states

Always use InteractionSource + indication; never hand-roll state opacity per component.

Layout

• Compact baseline grid: 4dp (icons + tight spacing), 8dp (component-internal), 16dp (default padding).
• Margins: 16dp default screen edge; 24dp on medium+.
• Material spacing tokens: padding-small (8dp), medium (16dp), large (24dp) — use via M3 component defaults.
• Edge-to-edge: enableEdgeToEdge() (mandatory under API 36 — windowOptOutEdgeToEdgeEnforcement removed); use WindowInsets.systemBars / Modifier.windowInsetsPadding() to respect inset regions.

Content design

• Voice and tone: clear, concise, conversational; don't over-apologize for errors.
• Sentence case for buttons / titles (not Title Case).
• Action labels are verbs: "Save", "Delete", "Send" — not "OK".
• Error messages: state the problem, suggest the fix, link to action when possible.
• Empty states: explain what's missing + how to add the first item.

→ Hand off copy to Prose (UX writing) and Polyglot (localization).

Iconography

• Material Symbols — variable-font icon library. Three styles: Outlined (default), Rounded, Sharp. Three optical sizes: 20 / 24 / 40dp. Four weights: 100/300/400/700.
• Compose: androidx.compose.material.icons.Icons.Outlined.* etc. (canonical 24dp set bundled with material-icons-extended artifact). For variable-font Material Symbols use the compose-icons library or import SVGs.
• Always pair icon with text label when an action is non-obvious or the user is keyboard-only.

3. Styles

Color

Color roles (the M3 paradigm — semantic, not brand-positional):

Compose access: MaterialTheme.colorScheme.primary, etc.

Dynamic Color (API 31+): dynamicLightColorScheme(LocalContext.current). Fall back to brand ColorScheme on API < 31 or when user has overridden.

Typography

15 type roles, each defines size / weight / line-height / letter-spacing / font:

Compose: MaterialTheme.typography.bodyLarge. Apply via Text(..., style = MaterialTheme.typography.bodyLarge).

Roboto Flex variable font support: weight, width, optical size axes — supported in Expressive's emphasis variants.

Shape

Compose: MaterialTheme.shapes.medium returns RoundedCornerShape(12.dp).

Material Shapes Library (Expressive): 35 new shapes (squircle, scallop, cookie, etc.) + shape morphing API for animating between shapes during interaction. Use MaterialShapes.Cookie9Sided, MaterialShapes.Scallop, etc.

Motion

Easing tokens:

Duration tokens: short1 (50ms) → extraLong4 (1000ms). Pick by content complexity, not aesthetic preference.

Expressive — spring system: MotionScheme.expressive() exposes spring-based animations as defaults. Components use spring physics for state transitions, gestures, and shape morphing. Access via MaterialTheme.motionScheme.defaultSpatialSpec(), etc.

Elevation

Compose: Surface(tonalElevation = ..., shadowElevation = ...). M3 prefers tonal elevation (color shift) over shadow on Surface (especially in dark mode).

Sound

• Sparingly. Avoid notification fatigue.
• Use system sounds (ToneGenerator, SoundPool) for confirmations.
• Match haptic + sound for stronger feedback.

4. Components (Jetpack Compose API)

Action

Communication

Containment

Navigation

Selection

Text Input

Layout primitives

5. Patterns

Top-level navigation

• 2-5 destinations in Navigation Bar; use Navigation Rail / Drawer for 6+.
• Stay persistent — destinations don't appear/disappear by context.
• Adaptive: NavigationSuiteScaffold swaps the surface (Bar/Rail/Drawer) automatically across Window Size Classes.

Hierarchical navigation

• Navigation Compose 2.8+ type-safe — @Serializable data class destinations.
• Stack: NavController.navigate(Destination(...)).
• Deep links: navDeepLink<Destination>() with App Links (assetlinks.json) — see reference/deeplink-routing.md.

Predictive back (API 36 default ON)

• Use BackHandler (Compose) / OnBackPressedDispatcher (Views).
• Manifest: android:enableOnBackInvokedCallback="true".
• For Compose: PredictiveBackHandler for custom predictive animations.
• Never use onBackPressed() / KEYCODE_BACK — not invoked at targetSdk 36.

Search

• SearchBar for in-app search at top level (expandable).
• DockedSearchBar for embedded search.
• Use Window Size Class to decide expanded vs docked.

Onboarding

• Minimal screens (3-5 max); skip-by-default.
• Honor reduced animations.
• Never gate core app entry on permission grants — use soft pre-prompt + graceful degradation.

Empty states

• Headline + supporting text + primary action.
• Use Icon + Text + Button in a Column; consider ListItem-derived layout for in-list empties.

Settings

• Scaffold + LazyColumn with ListItem rows + Switch / RadioButton / Card groupings.
• Match Settings app conventions: section headers, supporting text under headlines.

Feedback

• Snackbar for transient confirmation (auto-dismiss).
• AlertDialog for blocking decisions only.
• Haptic via HapticFeedback.performHapticFeedback(...) (Compose LocalHapticFeedback); never decorative.
• Sound sparingly.

Edge-to-edge

• enableEdgeToEdge() in Activity.onCreate() — mandatory under API 36.
• Apply Modifier.windowInsetsPadding(WindowInsets.systemBars) where chrome must respect insets.
• Use Scaffold — handles insets automatically when configured.

Pull to refresh

• PullToRefreshBox (Expressive) — modern API replacing older SwipeRefresh patterns.

6. Develop (Compose-first)

Versions to track

State and lifecycle

• Strong Skipping: stable types skipped automatically. But does NOT make types stable — still apply @Stable / @Immutable or use kotlinx.collections.immutable (PersistentList, ImmutableList) for high-frequency unstable params.
• collectAsStateWithLifecycle() — mandatory for flows in UI.
• remember keys — match all observable deps; missing key causes stale state.

Theming

MaterialTheme(
    colorScheme = if (useDynamic) dynamicLightColorScheme(LocalContext.current) else BrandLightScheme,
    typography = AppTypography,
    shapes = AppShapes,
    motionScheme = MaterialMotionScheme.expressive(),   // M3 Expressive
) { content() }

Dark mode

• isSystemInDarkTheme() — switch between lightColorScheme() and darkColorScheme().
• Provide explicit dynamicDarkColorScheme() for API 31+.
• Avoid hard-coding Color.White / Color.Black — use MaterialTheme.colorScheme.surface etc.

Implementation Hooks

Cross-Platform Notes (M3 scope, Android focus)

Native scope is iOS + Android mobile. Wear / TV / Auto are not Native's default scope unless explicitly requested.

Versioning & Drift

• Google I/O annually (May) — Material updates typically announced here.
• Compose BOM updated quarterly — track via androidx.compose:compose-bom-alpha for previews.
• Target SDK 36 mandatory on Google Play from 2026-08-31 for new apps and updates.
• 16KB native lib alignment required on new releases since 2025-11-01.
• Material 3 Expressive stable — confirmed in Compose Material 3 1.4+; APIs marked @ExperimentalMaterial3ExpressiveApi on earlier alphas; graduates to stable per-component.

#TODO(agent): re-fetch https://m3.material.io/ and https://developer.android.com/jetpack/androidx/releases/compose-material3 via a JS-capable fetcher to validate exact 1.4.x patch versions, @ExperimentalMaterial3ExpressiveApi graduation status per component, and any new Expressive components added after 2026-05.

Authoritative URLs