majiayu000 Material Design Implementation Guide
This skill helps you create beautiful, consistent user interfaces following Google's Material Design 3 (Material You) guidelines. It covers components, design tokens, theming, accessibility, and best practices.
When to Use This Skill
Use this skill when:
- Creating new UI components with Material Design styling
- Implementing Material Design 3 (Material You) theming
- Setting up color schemes, typography, or elevation systems
- Building responsive layouts with Material Design patterns
- Converting designs to Material Design specifications
- Ensuring accessibility compliance with Material guidelines
- Working with React (MUI), Vue (Vuetify), or vanilla CSS/HTML
- Building Android apps with Material Components
- Implementing motion and animations per Material guidelines
Core Material Design 3 Principles
1. Material You (Personalization)
- Dynamic color theming based on user preferences
- Adaptive layouts that respond to context
- Emphasis on personal expression
2. Design Tokens
- Color: Primary, Secondary, Tertiary, Error, Neutral colors with variants
- Typography: Display, Headline, Title, Body, Label scales
- Elevation: Surface levels 0-5
- Shape: Rounded corners (none, small, medium, large, extra-large)
- Motion: Duration and easing curves
3. Key Concepts
- Surface: Containers that hold content
- State Layers: Visual feedback for interaction states
- Elevation: Depth through shadows and tonal differences
- Accessibility: WCAG 2.1 AA compliance minimum
Material Design 3 Color System
Color Roles
Primary: Main brand color (buttons, active states)
├── On-Primary: Text/icons on primary color
├── Primary Container: Less prominent primary elements
└── On-Primary Container: Content on primary container
Secondary: Accent color (FABs, selection controls)
├── On-Secondary
├── Secondary Container
└── On-Secondary Container
Tertiary: Complementary accent
├── On-Tertiary
├── Tertiary Container
└── On-Tertiary Container
Error: Error states
├── On-Error
├── Error Container
└── On-Error Container
Surfaces:
├── Surface: Default background
├── Surface-Variant: Subtle differentiation
├── On-Surface: Text/icons on surface
├── On-Surface-Variant: Lower emphasis text
├── Outline: Borders and dividers
└── Outline-Variant: Decorative elements
Dynamic Color Generation
Material Design 3 uses HCT (Hue, Chroma, Tone) color space:
// Example: Generate color scheme from source color
const sourceColor = '#6750A4'; // Primary color
// Tonal Palette (0-100 tone scale)
const tones = {
0: '#000000', // Black
10: '#21005D', // Darkest
20: '#381E72',
30: '#4F378B',
40: '#6750A4', // Source
50: '#7F67BE',
60: '#9A82DB',
70: '#B69DF8',
80: '#D0BCFF',
90: '#EADDFF',
95: '#F6EDFF',
99: '#FFFBFE',
100: '#FFFFFF' // White
};
Typography Scale
Type Scale Specifications
/* Display - Large, impactful text */
.md-display-large {
font-size: 57px;
line-height: 64px;
font-weight: 400;
letter-spacing: -0.25px;
}
.md-display-medium {
font-size: 45px;
line-height: 52px;
font-weight: 400;
}
.md-display-small {
font-size: 36px;
line-height: 44px;
font-weight: 400;
}
/* Headline - High-emphasis text */
.md-headline-large {
font-size: 32px;
line-height: 40px;
font-weight: 400;
}
.md-headline-medium {
font-size: 28px;
line-height: 36px;
font-weight: 400;
}
.md-headline-small {
font-size: 24px;
line-height: 32px;
font-weight: 400;
}
/* Title - Medium-emphasis text */
.md-title-large {
font-size: 22px;
line-height: 28px;
font-weight: 400;
}
.md-title-medium {
font-size: 16px;
line-height: 24px;
font-weight: 500;
letter-spacing: 0.15px;
}
.md-title-small {
font-size: 14px;
line-height: 20px;
font-weight: 500;
letter-spacing: 0.1px;
}
/* Body - Main content */
.md-body-large {
font-size: 16px;
line-height: 24px;
font-weight: 400;
letter-spacing: 0.5px;
}
.md-body-medium {
font-size: 14px;
line-height: 20px;
font-weight: 400;
letter-spacing: 0.25px;
}
.md-body-small {
font-size: 12px;
line-height: 16px;
font-weight: 400;
letter-spacing: 0.4px;
}
/* Label - UI elements */
.md-label-large {
font-size: 14px;
line-height: 20px;
font-weight: 500;
letter-spacing: 0.1px;
}
.md-label-medium {
font-size: 12px;
line-height: 16px;
font-weight: 500;
letter-spacing: 0.5px;
}
.md-label-small {
font-size: 11px;
line-height: 16px;
font-weight: 500;
letter-spacing: 0.5px;
}
Elevation System
Material Design 3 uses tonal elevation instead of shadows alone:
/* Elevation Levels */
.md-elevation-0 {
box-shadow: none;
/* Surface tint: 0% opacity */
}
.md-elevation-1 {
box-shadow: 0px 1px 2px rgba(0, 0, 0, 0.3),
0px 1px 3px 1px rgba(0, 0, 0, 0.15);
/* Surface tint: 5% opacity */
}
.md-elevation-2 {
box-shadow: 0px 1px 2px rgba(0, 0, 0, 0.3),
0px 2px 6px 2px rgba(0, 0, 0, 0.15);
/* Surface tint: 8% opacity */
}
.md-elevation-3 {
box-shadow: 0px 1px 3px rgba(0, 0, 0, 0.3),
0px 4px 8px 3px rgba(0, 0, 0, 0.15);
/* Surface tint: 11% opacity */
}
.md-elevation-4 {
box-shadow: 0px 2px 3px rgba(0, 0, 0, 0.3),
0px 6px 10px 4px rgba(0, 0, 0, 0.15);
/* Surface tint: 12% opacity */
}
.md-elevation-5 {
box-shadow: 0px 4px 4px rgba(0, 0, 0, 0.3),
0px 8px 12px 6px rgba(0, 0, 0, 0.15);
/* Surface tint: 14% opacity */
}
Shape System
/* Corner Radius Tokens */
:root {
--md-shape-corner-none: 0px;
--md-shape-corner-extra-small: 4px;
--md-shape-corner-small: 8px;
--md-shape-corner-medium: 12px;
--md-shape-corner-large: 16px;
--md-shape-corner-extra-large: 28px;
--md-shape-corner-full: 9999px; /* Fully rounded */
}
/* Component-specific shapes */
.md-button {
border-radius: var(--md-shape-corner-full); /* Fully rounded */
}
.md-card {
border-radius: var(--md-shape-corner-medium); /* 12px */
}
.md-dialog {
border-radius: var(--md-shape-corner-extra-large); /* 28px */
}
.md-chip {
border-radius: var(--md-shape-corner-small); /* 8px */
}
Common Components
Button (Filled)
<button class="md-button-filled">
<span class="md-button-label">Button</span>
</button>
.md-button-filled {
/* Container */
background-color: var(--md-sys-color-primary);
border: none;
border-radius: var(--md-shape-corner-full);
padding: 10px 24px;
min-height: 40px;
/* Label */
color: var(--md-sys-color-on-primary);
font-size: 14px;
font-weight: 500;
letter-spacing: 0.1px;
/* State layers */
position: relative;
cursor: pointer;
transition: box-shadow 0.2s cubic-bezier(0.4, 0, 0.2, 1);
}
.md-button-filled:hover::before {
content: '';
position: absolute;
inset: 0;
background-color: var(--md-sys-color-on-primary);
opacity: 0.08;
border-radius: inherit;
}
.md-button-filled:focus::before {
opacity: 0.12;
}
.md-button-filled:active::before {
opacity: 0.12;
}
.md-button-filled:disabled {
background-color: rgba(var(--md-sys-color-on-surface-rgb), 0.12);
color: rgba(var(--md-sys-color-on-surface-rgb), 0.38);
cursor: not-allowed;
}
Card (Elevated)
<div class="md-card-elevated">
<div class="md-card-content">
<h3 class="md-title-large">Card Title</h3>
<p class="md-body-medium">Card content goes here.</p>
</div>
<div class="md-card-actions">
<button class="md-button-text">Action</button>
</div>
</div>
.md-card-elevated {
background-color: var(--md-sys-color-surface-container-low);
border-radius: var(--md-shape-corner-medium);
padding: 16px;
box-shadow: 0px 1px 2px rgba(0, 0, 0, 0.3),
0px 1px 3px 1px rgba(0, 0, 0, 0.15);
transition: box-shadow 0.2s cubic-bezier(0.4, 0, 0.2, 1);
}
.md-card-elevated:hover {
box-shadow: 0px 1px 3px rgba(0, 0, 0, 0.3),
0px 4px 8px 3px rgba(0, 0, 0, 0.15);
}
.md-card-content {
margin-bottom: 16px;
}
.md-card-actions {
display: flex;
gap: 8px;
justify-content: flex-end;
}
Text Field (Filled)
<div class="md-text-field-filled">
<label class="md-text-field-label" for="input">Label</label>
<input
type="text"
id="input"
class="md-text-field-input"
placeholder="Placeholder"
>
<div class="md-text-field-active-indicator"></div>
</div>
.md-text-field-filled {
position: relative;
background-color: var(--md-sys-color-surface-container-highest);
border-radius: var(--md-shape-corner-extra-small) var(--md-shape-corner-extra-small) 0 0;
padding: 8px 16px 8px 16px;
}
.md-text-field-label {
display: block;
color: var(--md-sys-color-on-surface-variant);
font-size: 12px;
font-weight: 400;
letter-spacing: 0.4px;
margin-bottom: 4px;
}
.md-text-field-input {
width: 100%;
border: none;
background: transparent;
color: var(--md-sys-color-on-surface);
font-size: 16px;
line-height: 24px;
letter-spacing: 0.5px;
outline: none;
padding: 0;
}
.md-text-field-active-indicator {
position: absolute;
bottom: 0;
left: 0;
right: 0;
height: 1px;
background-color: var(--md-sys-color-on-surface-variant);
transition: height 0.2s, background-color 0.2s;
}
.md-text-field-filled:focus-within .md-text-field-active-indicator {
height: 2px;
background-color: var(--md-sys-color-primary);
}
Motion & Animation
Duration Tokens
:root {
/* Short - Small UI elements */
--md-motion-duration-short1: 50ms;
--md-motion-duration-short2: 100ms;
--md-motion-duration-short3: 150ms;
--md-motion-duration-short4: 200ms;
/* Medium - Moving UI elements */
--md-motion-duration-medium1: 250ms;
--md-motion-duration-medium2: 300ms;
--md-motion-duration-medium3: 350ms;
--md-motion-duration-medium4: 400ms;
/* Long - Large/complex elements */
--md-motion-duration-long1: 450ms;
--md-motion-duration-long2: 500ms;
--md-motion-duration-long3: 550ms;
--md-motion-duration-long4: 600ms;
/* Extra Long - Large screen transitions */
--md-motion-duration-extra-long1: 700ms;
--md-motion-duration-extra-long2: 800ms;
--md-motion-duration-extra-long3: 900ms;
--md-motion-duration-extra-long4: 1000ms;
}
Easing Curves
:root {
/* Standard - Most common */
--md-motion-easing-standard: cubic-bezier(0.4, 0, 0.2, 1);
/* Emphasized - Important transitions */
--md-motion-easing-emphasized: cubic-bezier(0.2, 0, 0, 1);
/* Decelerated - Entering screen */
--md-motion-easing-decelerated: cubic-bezier(0, 0, 0.2, 1);
/* Accelerated - Exiting screen */
--md-motion-easing-accelerated: cubic-bezier(0.4, 0, 1, 1);
}
Example Animations
/* Fade In */
@keyframes md-fade-in {
from {
opacity: 0;
}
to {
opacity: 1;
}
}
.fade-in {
animation: md-fade-in var(--md-motion-duration-short4) var(--md-motion-easing-decelerated);
}
/* Scale Up */
@keyframes md-scale-up {
from {
transform: scale(0.8);
opacity: 0;
}
to {
transform: scale(1);
opacity: 1;
}
}
.scale-up {
animation: md-scale-up var(--md-motion-duration-medium2) var(--md-motion-easing-emphasized);
}
/* Slide Up */
@keyframes md-slide-up {
from {
transform: translateY(100%);
}
to {
transform: translateY(0);
}
}
.slide-up {
animation: md-slide-up var(--md-motion-duration-medium4) var(--md-motion-easing-emphasized);
}
Accessibility Guidelines
Color Contrast
Material Design requires WCAG 2.1 AA compliance:
- Normal text: 4.5:1 contrast ratio minimum
- Large text (18px+ or 14px+ bold): 3:1 minimum
- UI components: 3:1 minimum
// Check contrast ratio
function getContrastRatio(color1, color2) {
// Returns ratio (e.g., 4.5)
// Use online tools or libraries like 'color' npm package
}
// Material Design color roles ensure proper contrast by default
Touch Targets
Minimum touch target size: 48x48 dp (density-independent pixels)
.md-button {
min-width: 48px;
min-height: 48px;
/* Even if visual size is smaller, ensure interactive area is 48x48 */
}
/* For small icons, add padding */
.md-icon-button {
width: 40px;
height: 40px;
padding: 4px; /* Total: 48x48 */
}
Focus Indicators
Always provide visible focus indicators:
.md-interactive:focus-visible {
outline: 2px solid var(--md-sys-color-primary);
outline-offset: 2px;
}
/* State layer for focus */
.md-interactive:focus-visible::before {
opacity: 0.12;
}
ARIA Attributes
<!-- Button with icon -->
<button aria-label="Close dialog">
<svg>...</svg>
</button>
<!-- Input with label -->
<label for="email">Email</label>
<input
id="email"
type="email"
aria-required="true"
aria-describedby="email-hint"
>
<span id="email-hint">We'll never share your email.</span>
<!-- Disabled state -->
<button disabled aria-disabled="true">
Submit
</button>
Responsive Design
Breakpoints
:root {
--md-breakpoint-compact: 600px; /* Phone */
--md-breakpoint-medium: 840px; /* Tablet */
--md-breakpoint-expanded: 1200px; /* Desktop */
--md-breakpoint-large: 1600px; /* Large desktop */
}
/* Compact (0-599px) */
@media (max-width: 599px) {
.md-container {
padding: 16px;
}
}
/* Medium (600-839px) */
@media (min-width: 600px) and (max-width: 839px) {
.md-container {
padding: 24px;
}
}
/* Expanded (840-1199px) */
@media (min-width: 840px) and (max-width: 1199px) {
.md-container {
padding: 24px;
max-width: 840px;
margin: 0 auto;
}
}
/* Large (1200px+) */
@media (min-width: 1200px) {
.md-container {
padding: 24px;
max-width: 1200px;
margin: 0 auto;
}
}
Adaptive Layouts
/* Navigation Rail (Medium+) */
@media (min-width: 600px) {
.md-nav-rail {
display: flex;
flex-direction: column;
width: 80px;
}
.md-nav-drawer {
display: none;
}
}
/* Navigation Drawer (Expanded+) */
@media (min-width: 840px) {
.md-nav-drawer {
display: block;
width: 256px;
}
.md-nav-rail {
display: none;
}
}
AI Assistant Instructions
When this skill is activated, you should:
1. Clarify Requirements
Ask the user:
- Which framework are they using? (React/MUI, Vue/Vuetify, vanilla HTML/CSS, Android)
- Which Material Design version? (Prefer Material Design 3 unless specified)
- What component(s) do they need?
- Do they have an existing theme/color scheme?
- Are there specific accessibility requirements?
2. Follow Material Design 3 Guidelines
Always:
- Use Material Design 3 (Material You) specifications by default
- Apply proper design tokens (color roles, typography scale, elevation)
- Ensure 48x48dp minimum touch targets
- Provide accessible color contrast (WCAG 2.1 AA minimum)
- Include proper state layers (hover, focus, active, disabled)
- Use appropriate motion/animation with correct easing curves
- Follow component-specific guidelines from Material Design documentation
Never:
- Use arbitrary colors—always use semantic color roles
- Skip accessibility considerations
- Implement custom components without checking official Material specs
- Use outdated Material Design 2 patterns (unless explicitly requested)
- Forget state layers for interactive elements
3. Provide Complete Implementations
Each component should include:
- HTML structure (semantic, accessible markup)
- CSS styles (using design tokens, proper specificity)
- Variants (filled, outlined, text, etc.)
- States (default, hover, focus, active, disabled)
- Responsive behavior (if applicable)
- ARIA attributes (for accessibility)
- Code comments (explaining Material Design specifications)
4. Reference Official Documentation
When implementing components:
- Check Material Design 3 Guidelines
- Reference component specifications for exact measurements
- Use official design tokens and naming conventions
- Link to relevant documentation sections in comments
5. Optimize for Framework
For React (MUI):
- Use MUI components and theming system
- Leverage
sxprop orstyledAPI - Follow MUI's Material Design 3 migration guide
For Vue (Vuetify):
- Use Vuetify 3+ components (Material Design 3)
- Apply theme customization via vuetify config
- Use Vuetify's built-in utilities
For Vanilla HTML/CSS:
- Provide self-contained, copy-paste ready code
- Use CSS custom properties for theming
- Include necessary JavaScript for interactions (if needed)
For Android:
- Use Material Components for Android library
- Provide XML layouts and Kotlin/Java code
- Reference Android-specific Material guidelines
6. Offer Customization Guidance
After providing base implementation:
- Show how to customize colors/theme
- Explain how to adjust spacing/sizing
- Provide variants (different sizes, styles)
- Suggest related components or patterns
7. Validate Against Best Practices
Before finalizing:
- ✅ Color contrast meets WCAG 2.1 AA
- ✅ Touch targets are 48x48dp minimum
- ✅ Focus indicators are visible and clear
- ✅ Component follows Material Design 3 specs
- ✅ Responsive design is considered
- ✅ Motion follows Material easing curves
- ✅ Code is clean, commented, and reusable
Common Patterns
Pattern 1: Full Page Layout with App Bar
See examples/layout-app-bar.html
Pattern 2: Form with Material Text Fields
See examples/form-material-inputs.html
Pattern 3: Card Grid with Responsive Layout
See examples/card-grid.html
Pattern 4: Bottom Navigation
See examples/bottom-navigation.html
Troubleshooting
Issue: Colors don't look right in dark mode
Solution: Ensure you're using semantic color roles (e.g., var(--md-sys-color-primary)) instead of hard-coded hex values. Material Design 3 color roles automatically adapt to light/dark themes.
Issue: Text is hard to read
Solution: Check color contrast ratio (4.5:1 for normal text, 3:1 for large text). Use on-* color roles for text on colored backgrounds (e.g., on-primary for text on primary color).
Issue: Buttons look flat/lack depth
Solution: Add proper elevation (box-shadow) and state layers. Filled buttons should have elevation level 0 at rest, level 1 on hover. Use ::before pseudo-element for state layers.
Issue: Animations feel choppy
Solution: Use Material Design easing curves (cubic-bezier values). Avoid linear animations. Choose appropriate durations (short: <200ms, medium: 200-400ms, long: 400-600ms).
Issue: Touch targets too small on mobile
Solution: Ensure minimum 48x48dp interactive area. Add padding to visual elements if needed to reach 48x48dp total touchable area.
Additional Resources
- Material Design 3 Official Guidelines
- Material Theme Builder - Generate color schemes
- Material Design Icons - Official icon library
- Material Components Web - Web Components
- MUI (React) - React implementation
- Vuetify (Vue) - Vue implementation
- Material Components Android
- Figma Material 3 Design Kit
Quick Reference: Design Tokens
/* Color Roles */
--md-sys-color-primary
--md-sys-color-on-primary
--md-sys-color-primary-container
--md-sys-color-on-primary-container
--md-sys-color-secondary
--md-sys-color-tertiary
--md-sys-color-error
--md-sys-color-surface
--md-sys-color-on-surface
--md-sys-color-outline
/* Typography */
--md-sys-typescale-display-large
--md-sys-typescale-headline-large
--md-sys-typescale-title-large
--md-sys-typescale-body-large
--md-sys-typescale-label-large
/* Elevation */
--md-sys-elevation-level0: box-shadow: none;
--md-sys-elevation-level1: box-shadow: 0px 1px 2px...;
--md-sys-elevation-level2: box-shadow: 0px 1px 2px...;
/* Shape */
--md-shape-corner-extra-small: 4px;
--md-shape-corner-small: 8px;
--md-shape-corner-medium: 12px;
--md-shape-corner-large: 16px;
--md-shape-corner-extra-large: 28px;
Note: This skill focuses on Material Design 3 (Material You). For Material Design 2 implementations, please specify this explicitly.