material-design
Create UI components and designs following Google Material Design 3 (Material You) guidelines. Use when building Material UI components, implementing Material theming, working with elevation, color systems, typography, motion, or creating Android/web interfaces with Material Design patterns.
When & Why to Use This Skill
This Claude skill facilitates the professional implementation of Google's Material Design 3 (Material You) framework. It empowers developers to generate high-quality, accessible UI components and design systems by providing precise code for dynamic theming, HCT color palettes, typography scales, and motion patterns, ensuring full compliance with modern Android and web interface standards.
Use Cases
- Building responsive web applications using Material Design 3 components and layouts across React, Vue, or vanilla HTML/CSS.
- Implementing dynamic 'Material You' color systems that adapt to user preferences using semantic color roles and tonal palettes.
- Ensuring WCAG 2.1 AA accessibility compliance by generating UI code with proper contrast ratios and 48x48dp touch targets.
- Developing native Android interfaces using Material Components for Android with Kotlin or Java implementation.
- Creating consistent design token systems for typography, elevation, and shape to maintain brand integrity across different platforms.
- Applying standardized motion durations and easing curves to enhance user experience with fluid, meaningful animations.
| name | material-design |
|---|---|
| description | Create UI components and designs following Google Material Design 3 (Material You) guidelines. Use when building Material UI components, implementing Material theming, working with elevation, color systems, typography, motion, or creating Android/web interfaces with Material Design patterns. |
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
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.