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.

⭐5stars🔀1forks📁View on GitHub🕐Updated Jan 11, 2026⬇️5downloads

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.
namematerial-design
descriptionCreate 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 sx prop or styled API
  • 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

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.