Implement Google's Material Design 3 (Material You) UI system. Primary: Jetpack Compose Material3 (MaterialTheme, components, adaptive layout). Also Flutter and limited web (@material/web, maintenance mode). Covers tokens, 30+ components, layout, theming, M3 Expressive (platform matrix), and accessibility. Use when: "material design", "MD3", "material you", "Jetpack Compose", "MaterialTheme", "material component", "md3 button".
user-invokable
true
argument-hint
[component|theme|layout|scaffold|audit] [description or URL]
Material Design 3
This skill guides implementation of Google's Material Design 3 (MD3) — a personal, adaptive, expressive design system. MD3 uses dynamic color, tonal surfaces, rounded shapes, and spring-based motion to create UIs that feel alive and personal.
Philosophy
MD3 is built on three principles:
Personal: Dynamic color adapts UI to the user's wallpaper or content. Theming is individual, not one-size-fits-all.
Adaptive: Layouts transform across 5 window size classes. Components resize, reposition, and change form factor responsively.
Expressive: Shape morphing, spring physics, and emphasized typography create moments of delight without sacrificing usability.
Current Updates: Google I/O 2026
Material's Google I/O 2026 update reinforces a Compose-first Android path and expands expressive/adaptive guidance:
Material Android is Compose-first: For new Android work, prefer Jetpack Compose Material3 for the latest components, expressive APIs, adaptive scaffolds, and Styles API integration. Android Views may remain necessary in existing apps, but they should not be treated as the default path for new Material 3 implementations.
Expressive layout system: Use an expressive layout scaffold to adapt screens across mobile, desktop, foldables, watches, XR, and other spatial form factors. Start from adaptive scaffolds/window size classes instead of fixed phone-first layouts.
8dp spacing system: Apply spacing tokens for margins, padding, and gaps so layouts and components can adapt programmatically to device type and density.
New/updated expressive components: Lists, menus, search, and search app bars have refreshed expressive guidance, with Jetpack Compose as the primary implementation target.
Watches and XR: Watches emphasize physics-based motion, arc text, and edge-hugging containers. XR emphasizes spatial panels and depth-based elevation.
Key differences from MD2:
Tonal surfaces replace elevation shadows as the primary depth cue
Dynamic color generates full schemes from a single seed color
Fully rounded corners by default (not slightly rounded)
Spring-based motion physics replace fixed easing curves for components
3 levels of user-controlled contrast (standard/medium/high)
Relationship with frontend-design skill:
When both skills are active, MD3 provides the design system (tokens, components, layout rules) and frontend-design provides creative direction within those constraints. MD3 rules take precedence for component structure and token usage. Note: Roboto/Roboto Flex IS the correct default typeface in MD3 — the frontend-design guidance to avoid Roboto does not apply when implementing MD3.
Decision Tree
What are you building?
Full app scaffold → See "Common Patterns: App Shell" + references/layout-and-responsive.md
Single component → See "Component Quick Reference" table → references/component-catalog.md
Custom theme → See references/theming-and-dynamic-color.md
Form / input layout → See references/component-catalog.md § Input Components
Navigation structure → See references/navigation-patterns.md
Data display → See references/component-catalog.md § Data Display
What platform?
Jetpack Compose → Primary: androidx.compose.material3, MaterialTheme, references/*
Flutter → useMaterial3: true in ThemeData, ColorScheme.fromSeed()
Web (vanilla JS) → @material/web (limited; maintenance mode) + CSS custom properties
Web (React/Vue/Svelte) → CSS custom properties + wrapper components (no official React lib)
Web (CSS-only) → MD3 token values as CSS custom properties (no <md-*> elements)
Design Token System
All MD3 tokens use the md.sys namespace. Jetpack Compose maps roles to MaterialTheme.colorScheme, MaterialTheme.typography, and MaterialTheme.shapes (same semantic roles as the spec). On the web, these map to CSS custom properties (--md-sys-*):
Color Tokens (--md-sys-color-*)
Token
Purpose
primary
High-emphasis fills, text, icons against surface
on-primary
Text/icons on primary
primary-container
Standout fill for key components (FAB, etc.)
on-primary-container
Text/icons on primary-container
secondary / on-secondary
Less prominent accents
secondary-container / on-secondary-container
Recessive components (tonal buttons)
tertiary / on-tertiary
Contrasting accents
tertiary-container / on-tertiary-container
Complementary containers
error / on-error
Error states (static — doesn't change with dynamic color)
Each style has tokens for: -font, -weight, -size, -line-height, -tracking
Plus 15 emphasized variants (higher weight) via --md-sys-typescale-emphasized-*
Full details: references/typography-and-shape.md
Shape Tokens (--md-sys-shape-corner-*)
Token
Value
Example components
none
0dp
—
extra-small
4dp
Chips, snackbars
small
8dp
Text fields, menus
medium
12dp
Cards
large
16dp
FABs, navigation drawer
large-increased
20dp
(Expressive)
extra-large
28dp
Dialogs, bottom sheets
extra-large-increased
32dp
(Expressive)
extra-extra-large
48dp
(Expressive)
full
9999px
Buttons, chips, badges
Elevation Levels
Level
DP
Tonal offset
Use
0
0dp
None
Flat surfaces, most components at rest
1
1dp
+5% primary
Elevated cards, modal sheets
2
3dp
+8% primary
Menus, nav bar, scrolled app bar
3
6dp
+11% primary
FAB, dialogs, search, date/time pickers
4
8dp
+12% primary
(hover/focus increase only)
5
12dp
+14% primary
(hover/focus increase only)
Elevation in MD3 is communicated through tonal surface color, not shadows. Shadows are only used when needed for additional protection against busy backgrounds.
Motion
MD3 Expressive (May 2025) introduced spring-based motion physics for components. The legacy easing/duration system is still used for transitions (enter/exit/shared-axis):
Note: Components marked with — for web element don't have @material/web implementations yet. Use CSS custom properties with standard HTML for these. Compose mappings and examples live in references/component-catalog.md.
Full component details with code examples: references/component-catalog.md
Jetpack Compose (primary)
Use androidx.compose.material3 with MaterialTheme and Material 3 composables (Scaffold, Button, NavigationBar, top app bars, etc.).
Theming: MaterialTheme(colorScheme = …, typography = …, shapes = …). Prefer dynamicLightColorScheme / dynamicDarkColorScheme on Android 12+ (API 31+) when dynamic color is desired; otherwise lightColorScheme / darkColorScheme or generated theme code from Material Theme Builder.
Adaptive UI: Window size classes, list-detail and supporting-pane layouts, foldables — see references/layout-and-responsive.md and references/navigation-patterns.md.
Edge-to-edge & insets: Lay out content with WindowInsets / scaffold padding so bars and IME behave correctly — see references/layout-and-responsive.md.
Experimental APIs: Some Material 3 APIs require @OptIn(ExperimentalMaterial3Api::class) or expressive opt-ins; match your BOM and compiler.
MaterialTheme(
colorScheme = colorScheme, // from dynamicLightColorScheme / lightColorScheme / etc.
typography = Typography(),
shapes = Shapes(),
) {
// M3 content — prefer references for Scaffold, navigation, text fields
}
Web (limited): @material/web
Important: Per Material Design 3 for Web, Material Web Components are in maintenance mode and M3 Expressive is not implemented on Web. Use @material/web for token-backed web UIs when appropriate, but do not treat it as equivalent to Compose for current Expressive features.
Setup
npm install @material/web
Import Components Individually
Always import only the components you use — importing the entire package bloats the bundle:
// Good — individual importsimport'@material/web/button/filled-button.js';
import'@material/web/button/outlined-button.js';
import'@material/web/textfield/outlined-text-field.js';
import'@material/web/icon/icon.js';
// Bad — never do thisimport'@material/web'; // imports everything
Full theming guide: references/theming-and-dynamic-color.md
Common Patterns
App Shell
Standard MD3 app with responsive navigation + top app bar + content area:
<divclass="md3-app"><navclass="md3-nav-rail"aria-label="Main navigation"><!-- Navigation rail for medium+ screens --><md-fabsize="small"aria-label="Compose"><md-iconslot="icon">edit</md-icon></md-fab><md-navigation-bar><md-navigation-tablabel="Home"><md-iconslot="active-icon">home</md-icon><md-iconslot="inactive-icon">home</md-icon></md-navigation-tab><md-navigation-tablabel="Search"><md-iconslot="active-icon">search</md-icon><md-iconslot="inactive-icon">search</md-icon></md-navigation-tab></md-navigation-bar></nav><mainclass="md3-content"><headerclass="md3-top-app-bar"><h1class="md3-top-app-bar__title"style="font: var(--md-sys-typescale-title-large)">
Page Title
</h1></header><divclass="md3-body"><!-- Content here --></div></main></div>
<divclass="md3-card-grid"><divclass="md3-card md3-card--outlined"><imgsrc="image.jpg"alt="Description"class="md3-card__media"><divclass="md3-card__content"><h3style="font: var(--md-sys-typescale-title-medium)">Card Title</h3><pstyle="font: var(--md-sys-typescale-body-medium); color: var(--md-sys-color-on-surface-variant)">
Supporting text for this card.
</p></div><divclass="md3-card__actions"><md-text-button>Learn more</md-text-button><md-filled-tonal-button>Action</md-filled-tonal-button></div></div></div>
More patterns: references/navigation-patterns.md, references/layout-and-responsive.md
Anti-Patterns
Never do these when implementing MD3:
Mix MD2 and MD3 libraries: Don't use @material/mdc-* (MD2) alongside @material/web (MD3). They have incompatible APIs and styling.
Hardcode colors: Always use var(--md-sys-color-*) tokens, never raw hex/rgb values. Hardcoded colors break dynamic theming, dark mode, and contrast adjustment.
Ignore tonal pairing: Only combine colors in their intended pairs (e.g., primary + on-primary, surface-container + on-surface). Arbitrary pairings break contrast in dynamic color and high contrast modes.
Use outline for dividers: Use outline-variant for dividers. outline is for important boundaries like text field borders.
Import all of @material/web: Always import individual component modules. Barrel imports include every component and destroy bundle size.
Use border-radius directly: Use shape tokens (var(--md-sys-shape-corner-medium)) so shapes stay consistent with theming.
Use shadows for elevation by default: MD3 communicates elevation through tonal surface color, not shadows. Only add shadows when elements need extra separation from busy backgrounds.
Apply frontend-design "avoid Roboto" rule: On Android, Roboto is the default Material typeface; web often uses Roboto or Roboto Flex with MD3 tokens. Replace only when intentionally customizing the type scale.
Assume SSR compatibility: @material/web uses Web Components (custom elements) which require JavaScript to render. They won't produce meaningful HTML in SSR without additional hydration strategies.
Ignore foldables and large screens: MD3 is designed for all screen sizes. Don't ship phone-only layouts — use canonical layouts, multi-pane at 600dp+, and test on foldable/tablet emulators. Place no interactive content across the fold/hinge.
Stretch content to fill wide screens: On Large (1200dp+) and Extra-large (1600dp+) windows, constrain content to a max width (840–1040dp). Endless-width text lines are unreadable.
See Jetpack Compose (primary) above. Use LocalContext.current with dynamicLightColorScheme / dynamicDarkColorScheme only when Build.VERSION.SDK_INT >= Build.VERSION_CODES.S and dynamic color is enabled; otherwise supply static light/dark schemes.
Component Name Mapping
Concept
Web
Flutter
Compose
Filled button
md-filled-button
FilledButton
Button
Outlined text field
md-outlined-text-field
OutlinedTextField
OutlinedTextField
FAB
md-fab
FloatingActionButton
FloatingActionButton
Navigation bar
md-navigation-bar
NavigationBar
NavigationBar
Switch
md-switch
Switch
Switch
M3 Expressive (May 2025)
The Expressive update adds visual richness while maintaining usability. Availability differs by platform — do not assume one stack implements everything.
Capability
Jetpack Compose
Flutter
Web (@material/web)
Expressive layout scaffold / adaptive layout
Compose-first via Material3 adaptive APIs and window size classes
Use Flutter adaptive/layout primitives
CSS/container queries/manual layout; no Material Web parity
8dp spacing system
Use design tokens / Dp spacing constants; keep margins, padding, and gaps adaptive
Use theme spacing constants
CSS custom properties / design tokens
Expressive lists, menus, search, search app bar
Primary target per current Material guidance; check BOM and opt-ins
Check current Flutter Material docs
Spec-aligned custom implementation; @material/web is maintenance-only
Spring / motion physics
Supported in Material 3 (see MotionScheme, expressive APIs per BOM)
Varies by Flutter Material version
Not in Material Web; use easing/duration or custom motion
Emphasized typography
Via theme / type scale
Via theme
Token/CSS only; no full Expressive component set
Shape morphing
Compose-first in Google’s expressive rollout
Check current Flutter docs
Not in @material/web
New button sizes (XS–XL), toggle
Follow Compose Material3 components
Follow Flutter MD3
Height/CSS approximations only
Extra corner tokens (e.g. large-increased)
MaterialTheme.shapes / tokens
Theme shapes
CSS --md-sys-shape-*
3 contrast levels
Scheme builders / system
Plugins / manual
SchemeContent contrast parameter in JS utilities
Watches / XR form factors
Use Compose/Wear/XR-specific guidance where available
Legacy easing/duration remains valid for transitions (enter/exit/shared-axis) where the spec still references them; see the Motion table below.
MD3 Compliance Audit
When invoked with audit as the argument (e.g., /material-3 audit), or when asked to audit/review MD3 compliance, analyze the target app or page and produce a compliance report.
Audit Procedure
Identify the target: The user provides a URL (use browser tools to inspect), file paths (read source), or a running app.
Inspect the following categories and score each 0–10:
Category
What to check
Color tokens
Web:--md-sys-color-* / generated CSS. Compose:MaterialTheme.colorScheme roles (no arbitrary Color(...) for surfaces without reason). Proper tonal pairing (onX on X). Dark theme. Flutter:ColorScheme roles.
Typography
MD3 type scale: ComposeMaterialTheme.typography; web typescale tokens; correct roles (Display, Headline, Title, Body, Label).
Canonical layouts; Compose window size class / adaptive APIs; readable max width on large widths; foldable hinge avoidance.
Navigation
Bar / rail / drawer / drawers+ComposeNavHost patterns per size class; predictive back where applicable.
Motion
ComposeMotionScheme / expressive APIs when used; transitions may still use easing/duration. Web: CSS motion tokens fallback.
Accessibility
MD3 roles help, but verify contrast: UI components often need 3:1 for large text/borders and 4.5:1 for normal text (WCAG 2.x). TalkBack/semantics (Compose), focus order, touch targets (~48dp). Web: ARIA, keyboard.
Theming
Compose:MaterialTheme + light/dark/dynamic as designed. Web: CSS custom properties on :root or subtree. Flutter:ThemeData + ColorScheme.
