Material Design 3

---
name: material-design-3
description: Apply the Material Design 3 visual design system when building or restyling websites and UI. Use whenever the user asks to build, theme, restyle, or "make it look like" Material Design 3, mentions material 3, material you, M3, or describes tonal color roles (primary/container/on-), pill-shaped buttons, tonal elevation — even if they don't name the style explicitly. Do NOT use for non-visual tasks or when another named design system is requested.
license: MIT
---

# Material Design 3 Design System

Google's current design system: tonal color roles generated from a seed color, Roboto typography, five-step shape scale, tonal elevation instead of heavy shadows, and emphasized motion easing. The baseline light scheme uses a violet seed.

Apply this system holistically: colors, type, spacing, radius, borders, shadows, and motion together produce the look. Token values come from the officially published token set. When in doubt, match the reference sites listed at the end.

## When to use

- Building a new page or component that should read as Material Design 3.
- Restyling existing UI to this aesthetic.
- The user names the style, an alias (material 3, material you, M3, MD3), or describes its traits: tonal color roles (primary/container/on-); pill-shaped buttons; tonal elevation; large rounded corners on cards; state layers on interaction.

## Design tokens

### Color palette

- Surface (baseline light): `#fffbfe` (--color-bg)
- Surface-container: `#f7f2fa` (--color-surface)
- Surface-variant for chips and outlines: `#e7e0ec` (--color-surface-variant)
- On-surface: `#1c1b1f` (--color-text)
- On-surface-variant: `#49454f` (--color-text-muted)
- Primary: `#6750a4` (--color-accent)
- On-primary: `#ffffff` (--color-on-accent)
- Primary-container: `#eaddff` (--color-accent-container)
- On-primary-container: `#21005d` (--color-on-accent-container)
- Error: `#b3261e` (--color-error)
- Outline: `#79747e` (--color-border)

### Typography

- Display / headings: Roboto (fallback: system-ui, sans-serif)
- Body: Roboto (fallback: system-ui, sans-serif)
- Type scale: 1.125 ratio, base 16px — computed steps: 16px / 18px / 20px / 23px / 26px / 29px (body / h5 / h4 / h3 / h2 / h1; scale further for display sizes)
- Headings: weight 400, line-height 1.25, letter-spacing 0
- Body: line-height 1.5, letter-spacing 0.009em

### Spacing, radius, border

- Spacing scale (px): 4, 8, 12, 16, 24, 32, 40, 48 — 4dp grid; comfortable touch targets (48dp minimum); consistent 16dp screen margins on mobile, 24dp on larger screens.
- Border radius: xs 4px, sm 8px, md 12px, lg 16px, xl 28px, full 999px — The M3 shape scale. Cards use md/lg, dialogs xl, buttons and FABs full or lg.
- Border treatment: 1px solid #79747e — Outline color for outlined buttons, text fields, and chips; most surfaces separate by tone instead of borders.

### Shadows

- elevation-1: `0 1px 2px rgba(0,0,0,0.3), 0 1px 3px 1px rgba(0,0,0,0.15)` — Cards at rest
- elevation-2: `0 1px 2px rgba(0,0,0,0.3), 0 2px 6px 2px rgba(0,0,0,0.15)` — Raised components, FAB at rest
- elevation-3: `0 4px 8px 3px rgba(0,0,0,0.15), 0 1px 3px rgba(0,0,0,0.3)` — Dialogs, hovered FAB

### Layout

- Max content width: 1600px
- Responsive layout grid: 4 columns compact, 8 medium, 12 expanded
- Navigation rail or drawer on large screens, bottom bar on mobile
- Prefer tonal surface changes over shadows to express hierarchy

### Effects

- State layers: 8% hover, 12% pressed overlay of the on-color
- Optional dynamic color: derive the full scheme from one seed color

### Motion

- Easing: cubic-bezier(0.2, 0, 0, 1); durations 200ms / 300ms / 500ms
- Emphasized easing for large transitions, standard for small
- Container-transform pattern for card-to-detail navigation
- Durations 200–500ms; longer for larger surfaces

## CSS variables (drop-in)

```css
:root {
  --color-bg: #fffbfe;
  --color-surface: #f7f2fa;
  --color-surface-variant: #e7e0ec;
  --color-text: #1c1b1f;
  --color-text-muted: #49454f;
  --color-accent: #6750a4;
  --color-on-accent: #ffffff;
  --color-accent-container: #eaddff;
  --color-on-accent-container: #21005d;
  --color-error: #b3261e;
  --color-border: #79747e;
  --radius-xs: 4px;
  --radius-sm: 8px;
  --radius-md: 12px;
  --radius-lg: 16px;
  --radius-xl: 28px;
  --radius-full: 999px;
  --shadow-elevation-1: 0 1px 2px rgba(0,0,0,0.3), 0 1px 3px 1px rgba(0,0,0,0.15);
  --shadow-elevation-2: 0 1px 2px rgba(0,0,0,0.3), 0 2px 6px 2px rgba(0,0,0,0.15);
  --shadow-elevation-3: 0 4px 8px 3px rgba(0,0,0,0.15), 0 1px 3px rgba(0,0,0,0.3);
  --border-default: 1px solid #79747e;
  --font-display: Roboto, system-ui, sans-serif;
  --font-body: Roboto, system-ui, sans-serif;
  --text-base: 16px;
  --leading-heading: 1.25;
  --leading-body: 1.5;
  --tracking-heading: 0;
  --tracking-body: 0.009em;
  --ease: cubic-bezier(0.2, 0, 0, 1);
  --duration-fast: 200ms;
  --duration-base: 300ms;
  --duration-slow: 500ms;
}
```

Google Fonts: `<link rel="preconnect" href="https://fonts.gstatic.com" crossorigin><link href="https://fonts.googleapis.com/css2?family=Roboto:wght@400;500&display=swap" rel="stylesheet">`

## Component recipes

- **Nav:** Top app bar on surface color, 64px, title in 22px Roboto; elevates tonally on scroll
- **Hero:** M3 is app-first: lead with a large headline in Display Large (57px), supporting text, filled pill button + outlined companion
- **Card:** Filled card on surface-container, 12px radius, elevation-1; content padding 16px
- **Button (primary):** Filled button: primary bg, on-primary text, full pill, 40px tall, state layers on interaction
- **Button (secondary):** Outlined button: 1px outline border, primary text, pill
- **Form fields:** Outlined text field: 1px outline, 4px radius, floating label that shrinks into the border gap on focus, primary-colored when active

Where this spec is silent (footers, responsive breakpoints, empty states), derive the treatment from the tokens above and the Do/Don't rules — never fall back to generic defaults. Every interactive element needs a visible keyboard focus state consistent with the style (use the accent color or the border treatment, not the browser default).

## Signature element

Tonal color pairs — every fill color has a matching 'on-' color and a soft 'container' variant — plus pill-shaped filled buttons and 12–28px rounded surfaces. Spend boldness here; keep everything else quiet.

## Do

- Always pair a color with its matching on-color; never hand-pick text colors over fills
- Use container variants for soft emphasis instead of opacity tricks
- Express hierarchy with tone (surface-container steps) before reaching for shadows
- Follow the shape scale — mixing arbitrary radii breaks the system

## Don't

- Don't use heavy black shadows; M3 elevation is soft and mostly tonal
- Don't introduce colors outside the tonal palette roles
- No sharp corners on interactive components
- Don't shrink touch targets below 48px

## Accessibility notes

- The published tonal pairs are contrast-checked by construction (on-primary vs primary etc.) — keep the pairs intact
- On-surface-variant #49454f on bg passes AA; avoid using outline #79747e as a text color
- State-layer opacities are part of the spec and required for visible focus/hover feedback

## Reference sites

- Material 3 documentation: https://m3.material.io
- Material Web components: https://github.com/material-components/material-web

For the exhaustive machine-readable spec, see references/tokens.md and tokens.json in this skill folder.

Install this skill

unzip material-design-3.zip -d ~/.claude/skills/

npx shadcn add https://claude-design-skills.convoke.software/r/material-design-3.json

Settings → Capabilities → Skills → Upload skill → material-design-3.zip