| name | material-design-3-guide |
| description | Master guide for Material Design 3 — covering the full specification from Material You foundations through M3 Expressive. Explains when to use each Material Design 3 skill subset (color, motion, typography, shape, layout, components, icons). Use this when starting a Material Design 3 project, when you need to understand which M3 skill to apply, or when the user asks about Material Design 3 in general. |
| license | Apache-2.0 |
Material Design 3 Guide
Overview
This is the master guide for implementing Material Design 3 (M3) — covering the full specification from Material You foundations through M3 Expressive enhancements. It explains the overall system and directs you to specialized skills for each aspect.
Keywords: Material Design 3, M3, Material Design, design system, Google design, Material You, expressive design, UI design, M3 Expressive, React, MUI, Angular Material, Vue, Vuetify, Svelte, SMUI, Tailwind CSS, Next.js, Flutter, Jetpack Compose, web components, Beer CSS, Ink, CLI, terminal UI
What is Material Design 3?
Material Design 3 is Google's open-source design system for creating digital products. It has evolved through two major phases:
Material You (M3 Baseline)
The foundational M3 system introduced:
- Dynamic Color: Adaptive themes derived from user wallpapers and preferences
- Tonal Palettes: Five key palettes with systematic tonal generation
- Type Scale: 15 baseline type styles across five roles
- Shape System: Semantic corner radius scale from none to full
- Elevation System: Five levels with tinting for depth
- Component Library: Complete set of accessible, themed components
- Token System: CSS custom properties for consistent theming
M3 Expressive (Latest Evolution)
Building on Material You, M3 Expressive adds:
- 30-Style Type Scale: 15 emphasized variants alongside the 15 baseline styles
- 35 Expressive Shapes: Decorative shape library with smooth morphing
- Physics-Based Motion: Spring parameters (stiffness, damping, velocity) replacing traditional easing
- Fixed Accent Colors: Colors that stay constant across light and dark themes
- Contrast Levels: Standardized standard, medium, and high contrast modes
- New Components: Split buttons, button groups, floating toolbars, FAB menus
- Background Blur: Depth effects for overlays and navigation
- Haptic Integration: Coordinated vibration with spring animations
The Seven Pillars of Material Design 3
Material Design 3 is built on seven interconnected design pillars:
1. Color and Dynamic Theming
What: Vibrant, adaptive color systems with 26+ roles, proper contrast, and accessibility
Use the material-design-3-color skill when:
- Setting up color palettes or themes
- Implementing dynamic color (Material You)
- Working with primary, secondary, tertiary color roles
- Ensuring color accessibility and contrast
- Creating light and dark themes
- Defining color tokens and variables
- Applying state layers (hover, focus, pressed)
- Implementing elevation tinting
- Setting up fixed accent colors for branding (M3 Expressive)
- Configuring contrast levels (standard, medium, high) (M3 Expressive)
- Defining surface container hierarchy
Key concepts: Tonal palettes, color roles, dynamic color, accessibility, theming, fixed accents, contrast levels, surface containers
2. Motion and Animation
What: Physics-based, natural animations that guide attention and provide feedback
Use the material-design-3-motion skill when:
- Adding transitions between screens or states
- Implementing micro-interactions (hover, focus, press)
- Creating page or view transitions
- Animating component states
- Building loading states or progress indicators
- Implementing ripple effects
- Creating stagger animations for lists
- Morphing containers or shapes
- Choosing between expressive and standard motion (M3 Expressive)
- Integrating haptic feedback with animations (M3 Expressive)
Key concepts: Spring physics, stiffness/damping/velocity, easing curves, duration, transitions, haptics
3. Typography
What: Clear, readable type hierarchy using variable fonts and defined scales
Use the material-design-3-typography skill when:
- Setting up text styles and hierarchy
- Defining font families and weights
- Implementing the type scale (display, headline, title, body, label)
- Working with variable fonts
- Ensuring text readability and accessibility
- Setting line heights and letter spacing
- Creating responsive typography
- Using emphasized type styles for key moments (M3 Expressive)
Key concepts: Type scale (15 baseline + 15 emphasized), variable fonts, hierarchy, readability, medium contrast
4. Shape and Containment
What: Rounded corners, morphing shapes, and expressive decorative forms
Use the material-design-3-shape skill when:
- Defining border radius for components
- Creating rounded corners on cards, buttons, dialogs
- Implementing shape tokens (updated: Large 20dp, XL 32dp, XXL 48dp)
- Morphing shapes between states
- Working with containers and containment
- Styling buttons, FABs, chips, or input fields
- Using the 35 expressive shape library (M3 Expressive)
- Implementing expressive shape morphing (M3 Expressive)
Key concepts: Border radius, shape scale, morphing, containment, 35 expressive shapes, rounded corners
5. Layout and Size Hierarchy
What: Strategic use of spacing, size, containment, and depth to create visual flow
Use the material-design-3-layout skill when:
- Setting up page layouts and grids
- Defining spacing systems
- Creating responsive layouts
- Implementing size-based hierarchy
- Working with breakpoints
- Positioning components
- Creating visual emphasis through size
- Implementing elevation and depth
- Using background blur for overlays (M3 Expressive)
- Defining explicit vs implicit containment
- Implementing interaction states (hover, focus, pressed, disabled)
Key concepts: Spacing scale, grid systems, responsive design, visual hierarchy, background blur, containment, state layers
6. Components
What: Complete library of accessible, themed UI components
Use the material-design-3-components skill when:
- Building buttons, cards, dialogs, navigation, or any UI component
- Looking up component specifications (sizing, spacing, colors)
- Implementing new M3 Expressive components (split buttons, button groups, toolbars)
- Understanding component interaction states
- Choosing the right component for a use case
- Implementing FABs, chips, text fields, tabs, or menus
Key concepts: Action, containment, communication, navigation, selection, text input components
7. Icons
What: Material Symbols variable font icon system with 2,500+ icons
Use the material-design-3-icons skill when:
- Adding icons to an interface
- Configuring Material Symbols (fill, weight, grade, optical size)
- Implementing icon accessibility
- Using icon fill transitions for selection state
- Sizing icons correctly for different components
- Choosing an icon style (outlined, rounded, sharp)
Key concepts: Material Symbols, variable font axes (FILL, wght, GRAD, opsz), icon accessibility
When to Use Which Skill
Starting a New Material Design 3 Project
Step 1: Color Foundation
- Use
material-design-3-color first
- Set up your color palette and theme
- Define all color tokens (primary, secondary, tertiary, surfaces, fixed accents)
- Implement both light and dark themes
- Configure contrast levels
Step 2: Typography System
- Use
material-design-3-typography
- Define your type scale and font families (baseline + emphasized)
- Set up typography tokens
- Choose Roboto or custom brand fonts
Step 3: Shape System
- Use
material-design-3-shape
- Define shape tokens for all corner radii (updated values)
- Set up component-specific shapes
Step 4: Icons
- Use
material-design-3-icons
- Load Material Symbols (choose one style)
- Configure default variable font axes
Step 5: Layout Foundation
- Use
material-design-3-layout
- Set up spacing scale and grid system
- Define breakpoints for responsive design
- Set up containment patterns and interaction states
Step 6: Build Components
- Use
material-design-3-components
- Build all UI components using the established tokens
- Follow component-specific specifications
Step 7: Add Motion
- Use
material-design-3-motion
- Implement transitions and animations (choose expressive vs standard)
- Add micro-interactions to interactive elements
- Integrate haptic feedback where appropriate
Working on Specific Components
Buttons:
- Components:
material-design-3-components (specs, variants, button groups)
- Shape:
material-design-3-shape (full radius, pill shape)
- Color:
material-design-3-color (primary/secondary/tertiary)
- Typography:
material-design-3-typography (label-large)
- Motion:
material-design-3-motion (hover, focus, press states)
- Layout:
material-design-3-layout (spacing, sizing)
- Icons:
material-design-3-icons (button icons)
Cards:
- Components:
material-design-3-components (elevated, filled, outlined)
- Shape:
material-design-3-shape (medium radius, 12dp)
- Color:
material-design-3-color (surface container variants)
- Typography:
material-design-3-typography (title + body text)
- Motion:
material-design-3-motion (elevation change on hover)
- Layout:
material-design-3-layout (padding, content flow)
Dialogs/Modals:
- Components:
material-design-3-components (dialog specs)
- Shape:
material-design-3-shape (extra-large radius, 32dp)
- Color:
material-design-3-color (surface-container-high)
- Typography:
material-design-3-typography (headline + body)
- Motion:
material-design-3-motion (enter/exit animations)
- Layout:
material-design-3-layout (centered, max-width, background blur)
Navigation:
- Components:
material-design-3-components (bar, rail, drawer, tabs)
- Color:
material-design-3-color (surface variant, active states)
- Typography:
material-design-3-typography (label-large)
- Shape:
material-design-3-shape (indicators, pills)
- Motion:
material-design-3-motion (transition animations)
- Layout:
material-design-3-layout (nav structure)
- Icons:
material-design-3-icons (navigation icons with fill toggle)
Forms/Inputs:
- Components:
material-design-3-components (text fields, selectors)
- Shape:
material-design-3-shape (extra-small radius, 4dp)
- Color:
material-design-3-color (surface variant, outlines)
- Typography:
material-design-3-typography (body text, labels)
- Motion:
material-design-3-motion (focus animations)
- Layout:
material-design-3-layout (field spacing, alignment)
Common Scenarios
"Make it look Material Design 3":
- Start with
material-design-3-color - set up the color system
- Apply
material-design-3-shape - add rounded corners
- Use
material-design-3-typography - implement the type scale
- Load
material-design-3-icons - set up Material Symbols
- Build with
material-design-3-components - use M3 component specs
- Add
material-design-3-motion - implement spring animations
- Apply
material-design-3-layout - ensure proper spacing
"Make it M3 Expressive":
- Follow the standard M3 setup above
- Add emphasized type styles from
material-design-3-typography
- Use expressive shapes from
material-design-3-shape for decorative moments
- Switch to expressive motion mode from
material-design-3-motion
- Implement new components (split buttons, button groups, toolbars) from
material-design-3-components
- Add fixed accent colors and contrast levels from
material-design-3-color
- Use background blur from
material-design-3-layout
"Add Material Design animations":
- Primarily use
material-design-3-motion
- May need
material-design-3-color for state layers
- May need
material-design-3-shape for morphing shapes
"Fix Material Design colors":
- Use
material-design-3-color exclusively
- Focus on color roles, contrast, and theming
"Style this button/card/dialog":
- Start with
material-design-3-components for specs
- Then apply shape + color + typography as needed
"Make it responsive":
- Primarily
material-design-3-layout
- May need
material-design-3-typography for responsive text
- May need
material-design-3-shape for responsive radii
"Implement dark mode":
- Use
material-design-3-color for theme switching
- Ensure all color tokens are defined for both themes
- Adjust icon grade for dark mode via
material-design-3-icons
"Add icons":
- Use
material-design-3-icons for Material Symbols setup
- Use
material-design-3-color for icon color tokens
Integration Principles
All Skills Work Together
Material Design 3 is a holistic system - the skills are designed to be used together:
- Color defines the palette
- Typography defines the text
- Shape defines the form
- Motion defines the behavior
- Layout defines the structure
- Components define the building blocks
- Icons define the visual language
Consistency is Key
When using multiple skills:
- Use tokens/variables defined in each skill
- Don't hard-code values
- Maintain consistency across all design aspects
- Test the combined result, not just individual parts
Example: Complete Button Implementation
.md3-button {
border-radius: var(--md-sys-shape-corner-full);
background-color: var(--md-sys-color-primary);
color: var(--md-sys-color-on-primary);
font-family: var(--md-sys-typescale-label-large-font);
font-size: var(--md-sys-typescale-label-large-size);
font-weight: var(--md-sys-typescale-label-large-weight);
letter-spacing: var(--md-sys-typescale-label-large-tracking);
padding: var(--md-sys-spacing-2) var(--md-sys-spacing-6);
min-height: 40px;
display: inline-flex;
align-items: center;
gap: var(--md-sys-spacing-2);
transition:
background-color var(--md-sys-motion-duration-short2) var(--md-sys-motion-easing-standard),
box-shadow var(--md-sys-motion-duration-short2) var(--md-sys-motion-easing-standard),
transform var(--md-sys-motion-duration-short2) var(--md-sys-motion-easing-standard);
}
.md3-button:hover {
background-color: var(--md-sys-color-primary);
box-shadow: 0 2px 4px rgba(0,0,0,0.1);
transform: translateY(-1px);
}
.md3-button .material-symbols-outlined {
font-size: 18px;
font-variation-settings: 'opsz' 20;
}
Quick Reference
Which Skill for Which Property?
| Property | Skill |
|---|
color, background-color | material-design-3-color |
font-size, font-family, line-height, font-weight, letter-spacing | material-design-3-typography |
border-radius, clip-path | material-design-3-shape |
transition, animation, @keyframes | material-design-3-motion |
margin, padding, gap, width, height, display, grid | material-design-3-layout |
box-shadow (elevation) | material-design-3-layout (+ motion for transitions) |
backdrop-filter (blur) | material-design-3-layout |
font-variation-settings (icons) | material-design-3-icons |
| Component-specific specs | material-design-3-components |
Which Skill for Which Component?
| Component | Primary Skill | Supporting Skills |
|---|
| Buttons | components | color, shape, typography, motion |
| Cards | components | color, shape, layout |
| Dialogs | components | color, shape, layout, motion |
| Navigation | components | color, icons, layout, motion |
| Text Fields | components | color, shape, typography |
| FABs | components | color, shape, icons, motion |
| Chips | components | color, shape, typography |
| Tabs | components | color, typography, icons, motion |
| Lists | components | color, typography, layout |
| Menus | components | color, shape, layout |
File Organization
When implementing M3, organize your code:
styles/
├── tokens/
│ ├── color.css # From material-design-3-color
│ ├── typography.css # From material-design-3-typography
│ ├── shape.css # From material-design-3-shape
│ ├── motion.css # From material-design-3-motion
│ ├── layout.css # From material-design-3-layout
│ └── icons.css # From material-design-3-icons
├── components/
│ ├── button.css # Uses all skills
│ ├── card.css # Uses all skills
│ ├── dialog.css # Uses all skills
│ ├── navigation.css # Uses all skills
│ └── text-field.css # Uses all skills
└── main.css # Imports all tokens
Best Practices
Do's
- ✅ Use all seven pillars - M3 works best when all aspects are implemented
- ✅ Start with tokens - Define all design tokens before building components
- ✅ Follow the skills - Each skill provides tested, research-backed guidelines
- ✅ Test accessibility - All skills include accessibility requirements
- ✅ Support both themes - Always implement light and dark modes
- ✅ Use semantic names - Use token names, not hard-coded values
- ✅ Be consistent - Apply the same patterns across all components
- ✅ Cover the full spec - Include Material You baseline and M3 Expressive additions
Don'ts
- ❌ Don't cherry-pick - Using only color without shape/motion isn't really M3
- ❌ Don't hard-code - Always use the defined tokens and variables
- ❌ Don't skip accessibility - Contrast, sizing, and motion preferences matter
- ❌ Don't ignore dark mode - It's a core part of M3
- ❌ Don't improvise values - Use the scales provided in each skill
- ❌ Don't mix design systems - Don't combine M3 with other design languages
- ❌ Don't forget motion - Static M3 misses the "expressive" part
- ❌ Don't skip icons - Material Symbols are integral to the M3 visual language
Material Design 3 for Different Web Stacks
M3 can be implemented across many web stacks. Each framework has a dedicated library-specific skill with full setup, theming, and component examples. Use the overview table below to find the right skill for your project.
Web Stack Overview
| Stack | Primary Library | M3 Support | Skill |
|---|
| Vanilla CSS | CSS custom properties | Full (manual) | m3-web-vanilla |
| Web Components | @material/web (Lit) | Full M3 | m3-web-webcomponents |
| React / Next.js | MUI (@mui/material) | M3 theming | m3-web-react |
| Angular | @angular/material | Full M3 (official) | m3-web-angular |
| Vue | Vuetify 3 | Full M3 | m3-web-vue |
| Svelte | SMUI / @material/web | Partial M3 | m3-web-svelte |
| Tailwind CSS | tailwind-material-3 plugin | Token-based M3 | m3-web-tailwind |
| Ink (React CLI) | ink + @inkjs/ui | Token-based M3 | m3-web-ink |
| Flutter | material / m3e_design | Full M3 | m3-web-flutter |
| Android | Jetpack Compose Material 3 | Full M3 + Expressive | m3-web-android |
Choosing the Right Stack
| If your project uses... | Recommended Skill | Why |
|---|
| No framework (vanilla) | m3-web-vanilla | Full control, zero dependencies |
| React or Next.js | m3-web-react | Largest ecosystem, SSR support |
| Angular | m3-web-angular | Official, best M3 integration |
| Vue | m3-web-vue | Enterprise-ready, excellent docs |
| Svelte / SvelteKit | m3-web-svelte | Best available for Svelte |
| Tailwind CSS | m3-web-tailwind | Utility-first with M3 tokens |
| Any framework | m3-web-webcomponents | Official, framework-agnostic |
| CLI / Terminal | m3-web-ink | React-based, themeable |
| Flutter | m3-web-flutter | Official, cross-platform |
| Android | m3-web-android | Official, most complete M3 |
Tips for choosing:
- Angular projects: Use
m3-web-angular — best official M3 support of any web framework
- React projects: Use
m3-web-react for MUI, or m3-web-webcomponents for Google's official components
- Vue projects: Use
m3-web-vue — Vuetify 3 is mature and well-documented
- Framework-agnostic: Use
m3-web-webcomponents or m3-web-vanilla
- Prototype quickly: Use
m3-web-vanilla (Beer CSS) or m3-web-webcomponents via CDN
- Need Tailwind: Use
m3-web-tailwind to map M3 tokens to Tailwind config
- Mobile + Web: Use
m3-web-flutter for cross-platform M3
- CLI / Terminal: Use
m3-web-ink with M3 color tokens mapped to terminal colors
Resources
Material Design 3 Core Skills
material-design-3-color - Color palettes, theming, accessibility, fixed accents, contrast levelsmaterial-design-3-motion - Animations, transitions, micro-interactions, spring physics, hapticsmaterial-design-3-typography - Type scale (30 styles), fonts, hierarchy, emphasized variantsmaterial-design-3-shape - Border radius, containment, morphing, 35 expressive shapesmaterial-design-3-layout - Spacing, grids, responsive design, background blur, interaction statesmaterial-design-3-components - Complete component catalog with specs and implementationmaterial-design-3-icons - Material Symbols, variable font axes, icon accessibility
Library-Specific Skills
m3-web-vanilla - Vanilla CSS custom properties, Beer CSS, zero-dependency M3m3-web-webcomponents - Google's official @material/web Lit-based componentsm3-web-react - React / MUI / Next.js M3 theming and SSR integrationm3-web-angular - Angular Material M3 theming, SCSS mixins, schematicsm3-web-vue - Vuetify 3 M3 theming, components, dark modem3-web-svelte - SMUI + direct @material/web in Svelte/SvelteKitm3-web-tailwind - Tailwind CSS M3 token mapping and plugin setupm3-web-ink - Ink React CLI with @inkjs/ui M3 themingm3-web-flutter - Flutter M3 theming, dynamic color, M3 Expressive packagesm3-web-android - Jetpack Compose Material 3, dynamic color, M3 Expressive
External Resources
Checklist for Material Design 3 Projects
Starting a new M3 project? Follow this checklist:
Foundation
Implementation
M3 Expressive Enhancements (Optional)
Quality Assurance
Summary
Material Design 3 is a complete design system covering the full specification from Material You foundations through M3 Expressive enhancements. It is built on seven interconnected pillars, each with a dedicated skill:
- Color - The palette, themes, and accessibility
- Motion - The behavior, physics, and haptics
- Typography - The voice, hierarchy, and emphasis
- Shape - The personality, form, and expression
- Layout - The structure, depth, and containment
- Components - The building blocks and interactions
- Icons - The visual language and symbols
Use this guide to understand which skill to apply for your specific needs, and remember that M3 works best when all seven pillars work together in harmony.
