material-design-3-guide

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 /* Uses all seven pillars */ .md3-button { /* Shape */ border-radius : var (--md-sys-shape-corner-full); /* Color */ background-color : var (--md-sys-color-primary); color : var (--md-sys-color-on-primary); /* Typography */ 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); /* Layout */ 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 ); /* Motion */ 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 { /* Color - state layer */ background-color : var (--md-sys-color-primary); box-shadow : 0 2px 4px rgba ( 0 , 0 , 0 , 0.1 ); /* Motion */ transform : translateY (- 1px ); } /* Icons in button */ .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