Material 3 Expressive (Android UI/UX)

Overview

Design and review Android UI/UX using Material 3 Expressive. Prioritize component-token requests for dialogs, sheets, modals, toolbars, and buttons, with guidance plus token references by default.

Intake Questions

Target device class (phone, tablet, foldable, Wear OS)
Window size class (Compact, Medium, Expanded)
Brand constraints and dynamic color usage
Primary action(s) and desired hero moments (1-2 max)
Motion constraints and reduced-motion expectations
Accessibility targets (contrast, touch target)

Default Assumptions

Intensity level: Foundational
Window size class: Compact
Dynamic color: enabled
Standard navigation patterns preserved

Quick Workflow

Confirm intensity level + hero moments
Confirm device class + window size class
Load Tier 1 index and output template
Load component overview + token spec files
If theming needed, load Tier 3 foundation tokens
Output: guidance + token refs (see template)

Default Output Format (Guidance + Token Refs)

Use references/m3-component-token-output-template.md verbatim as the base output shell.

Context and intent (1-2 lines)
Intensity level + hero moments (count + location)
Window size class + device class
Component + variant
Token references: file paths + token groups to use (quote minimal key values only if needed)
Compose mapping reference (optional): references/compose-mapping.md
Behavior or interaction constraints (from overview)
Reduced-motion fallback note
Accessibility and performance checks
Optional: Compose mapping notes

Expressive Tactics

Lever	Application
Shape contrast	Bold corners on primary, subtle on secondary
Rich color	Primary/secondary containers for emphasis
Type hierarchy	Size + weight variation
Motion	Shape morph on press/select

Constraint: Max 1-2 hero moments per flow

Expressive Intensity Levels

Foundational: Clarity and familiarity first
Excellent: Stronger color, type, and shape while preserving patterns
Transformative: Bold layouts and motion with strict usability and accessibility

Common Mistakes

Mistake	Fix
Removing text labels for "cleaner" look	Keep labels; usability drops without them
Too many hero moments per screen	Limit to 1-2 per flow
Breaking navigation patterns	Preserve standard nav behaviors
No reduced-motion fallback	Honor system animation scale; provide reduced-motion or instant transitions when animation scale is 0
Hardcoding token values	Use semantic tokens (`md.sys.color.*`)
Ignoring window size classes	Test Compact, Medium, Expanded

Android-Specific Guidance

Preserve navigation and component behaviors
Keep touch targets generous and platform-consistent
Honor system animation scale; provide reduced-motion alternatives or instant transitions when animation scale is 0
Apply window size classes for tablets and foldables

Review Checklist

Hierarchy

Primary action identifiable within 2 seconds
Max 1-2 hero moments per screen
Labels preserved on all interactive elements

Accessibility

Color contrast: 4.5:1 text, 3:1 non-text
Touch targets: 48dp minimum
Motion: reduced-motion alternative provided
Screen reader: content descriptions present

Expressive Compliance

Intensity level consistent across feature
Standard patterns preserved
Dynamic color tokens used
Window size classes tested

Reference Tiers (Load in Order of Need)

Tier 1: Always Load First

Need	File
Component token lookup	`references/m3-expressive-specs-tokens-index.md`
Output format template	`references/m3-component-token-output-template.md`
New/updated components	`references/m3-expressive-components.md`

Tier 2: Component-Specific (Load When Requested)

Component	Overview	Tokens
Buttons	`m3-buttons.md`	`m3-buttons-specs-tokens.md`
Button Groups	`m3-button-groups.md`	`m3-button-groups-specs-tokens.md`
Dialogs	`m3-dialogs.md`	`m3-dialogs-specs-tokens.md`
Sheets	`m3-sheets.md`	`m3-bottom-sheets-specs-tokens.md` / `m3-side-sheets-specs-tokens.md`
Toolbars	`m3-toolbars.md`	`m3-toolbars-specs-tokens.md`
FABs	`m3-fabs.md`	`m3-fabs-specs-tokens.md`
Extended FAB	`m3-extended-fab.md`	`m3-extended-fab-specs-tokens.md`
FAB Menu	`m3-fab-menu.md`	`m3-fab-menu-specs-tokens.md`
Icon Buttons	`m3-icon-buttons.md`	`m3-icon-buttons-specs-tokens.md`
Split Button	`m3-split-button.md`	`m3-split-button-specs-tokens.md`
Navigation Bar	`m3-navigation-bar.md`	`m3-navigation-bar-specs-tokens.md`
Navigation Rail	`m3-navigation-rail.md`	`m3-navigation-rail-specs-tokens.md`
App Bars	`m3-app-bars.md`	`m3-app-bars-specs-tokens.md`
Carousel	`m3-carousel.md`	`m3-carousel-specs-tokens.md`
Progress Indicators	`m3-progress-indicators.md`	`m3-progress-indicators-specs-tokens.md`
Loading Indicator	`m3-loading-indicator.md`	`m3-loading-indicator-specs-tokens.md`

Tier 3: Foundation Tokens (Load for Theming)

Foundation	File
Color system	`m3-color-system.md`, `m3-color-foundation-tokens.md`
Typography	`m3-typography.md`, `m3-typography-foundation-tokens.md`, `m3-typography-fonts.md`, `m3-typography-type-scale-tokens.md`
Shape	`m3-shape.md`, `m3-shape-foundation-tokens.md`, `m3-shape-corner-radius-scale.md`, `m3-shape-morph.md`
Motion	`m3-motion-physics.md`, `m3-motion-foundation-tokens.md`, `m3-motion-specs.md`
Elevation	`m3-elevation.md`, `m3-elevation-specs-tokens.md`
State	`m3-state-foundation-tokens.md`

Tier 4: Evidence & Research (Load for Justification)

Resource	File
Research findings	`references/expressive-research.md`
Testing guidance	`references/m3-testing-material-3.md`
Expressive blog	`references/m3-expressive-blog.md`
Expressive guidelines	`references/m3-expressive-guidelines.md`
UX article	`references/medium-ux-article.md`

Tier 5: Wear OS (Load Only for Wearables)

Resource	File
Benefits	`references/wear-expressive-benefits.md`
Levels of expression	`references/wear-levels-of-expression.md`
Design language	`references/wear-expressive-design-language.md`
Blog	`references/wear-expressive-blog.md`
Compose Material3	`references/wear-compose-material3.md`

Supporting Resources

Resource	File
Android UI design hub	`references/android-ui-design-hub.md`
Expressive catalog	`references/expressive-catalog.md`
Compose mapping	`references/compose-mapping.md`

Maintenance

Refresh references with skills/material-3-expressive/scripts/update_m3_expressive_refs.py.
Requires Playwright and Chromium (.venv/bin/python -m playwright install chromium if needed).
CI runs weekly; local runs are for urgent changes.

Search Tips

Find a token prefix: rg "md.comp.button" skills/material-3-expressive/references/m3-buttons-specs-tokens.md
Find navigation tokens: rg "md.comp.navigation" skills/material-3-expressive/references/m3-.*navigation.*.md

Examples

Use assets/examples/ui/ExpressiveHomeScreen.kt as a Compose starting point
Use assets/examples/ui/ExpressiveButtonComparison.kt to see standard vs expressive button differences
Use assets/examples/ui/ExpressiveAntiPatterns.kt to learn common mistakes to avoid
Use assets/examples/ux/expressive-ux-brief-template.md to draft an expressive UX brief
Examples are illustrative; adapt sizes/colors to expressive tokens and project constraints.

material-3-expressive

Safety Notice

Copy this and send it to your AI assistant to learn