Agent skill

Material 3

Implement Google's Material Design 3 (Material You) UI system.

Install Material 3

skills CLI

$ npx skills add hamen/material-3-skill --skill material-3 -a claude-code

Project install by default; add -g for ~/.claude/skills/.

GitHub CLI

$ gh skill install hamen/material-3-skill material-3 --agent claude-code

Project scope by default; add --scope user for a personal install. Needs GitHub CLI 2.90.0 or later (public preview).

Manual copy

$ git clone --depth 1 https://github.com/hamen/material-3-skill.git skills-src && mkdir -p .claude/skills && cp -r skills-src/skills/material-3 .claude/skills/material-3 && rm -rf skills-src

Use ~/.claude/skills/ instead of .claude/skills for a personal install. The folder must contain SKILL.md.

Claude Code skills documentation · loads skills from .claude/skills/

Paste into Claude Code

Install the "material-3" agent skill from https://github.com/hamen/material-3-skill/tree/master/skills/material-3 into .claude/skills/material-3/ in this project. Copy the whole folder (SKILL.md and every file beside it), keep the folder name "material-3", then confirm the skill loads.

Claude Code copies the folder itself, the same result as the manual copy. Check what it changed before you commit it.

$skill-installer

$skill-installer install https://github.com/hamen/material-3-skill/tree/master/skills/material-3

Type this inside Codex. $skill-installer <name> installs a curated skill from openai/skills. The installer writes to $CODEX_HOME/skills (default ~/.codex/skills). Restart Codex if the skill does not show up.

skills CLI

$ npx skills add hamen/material-3-skill --skill material-3 -a codex

Project install goes to .agents/skills/; add -g for ~/.codex/skills/.

GitHub CLI

$ gh skill install hamen/material-3-skill material-3 --agent codex

Project scope by default (.agents/skills/); add --scope user for a personal install.

Manual copy

$ git clone --depth 1 https://github.com/hamen/material-3-skill.git skills-src && mkdir -p .agents/skills && cp -r skills-src/skills/material-3 .agents/skills/material-3 && rm -rf skills-src

Use ~/.agents/skills/ instead of .agents/skills for a personal install.

Codex skills documentation · loads skills from .agents/skills/

Paste into Codex

Install the "material-3" agent skill from https://github.com/hamen/material-3-skill/tree/master/skills/material-3 into .agents/skills/material-3/ in this project. Copy the whole folder (SKILL.md and every file beside it), keep the folder name "material-3", then confirm the skill loads.

Codex copies the folder itself, the same result as the manual copy. Check what it changed before you commit it.

skills CLI

$ npx skills add hamen/material-3-skill --skill material-3 -a cursor

Project install goes to .agents/skills/; add -g for ~/.cursor/skills/.

GitHub CLI

$ gh skill install hamen/material-3-skill material-3 --agent cursor

Project scope by default (.agents/skills/); add --scope user for a personal install.

Manual copy

$ git clone --depth 1 https://github.com/hamen/material-3-skill.git skills-src && mkdir -p .cursor/skills && cp -r skills-src/skills/material-3 .cursor/skills/material-3 && rm -rf skills-src

Use ~/.cursor/skills/ instead of .cursor/skills for a personal install.

Cursor skills documentation · loads skills from .cursor/skills/, .agents/skills/, .claude/skills/, .codex/skills/

Paste into Cursor

Install the "material-3" agent skill from https://github.com/hamen/material-3-skill/tree/master/skills/material-3 into .cursor/skills/material-3/ in this project. Copy the whole folder (SKILL.md and every file beside it), keep the folder name "material-3", then confirm the skill loads.

Cursor copies the folder itself, the same result as the manual copy. Check what it changed before you commit it.

gemini skills install

$ gemini skills install https://github.com/hamen/material-3-skill.git --path skills/material-3

--scope user (default) or --scope workspace; --path is the subfolder of the repo that holds the skill; --consent skips the security confirmation prompt.

skills CLI

$ npx skills add hamen/material-3-skill --skill material-3 -a gemini-cli

Project install goes to .agents/skills/; add -g for ~/.gemini/skills/.

GitHub CLI

$ gh skill install hamen/material-3-skill material-3 --agent gemini-cli

Project scope by default (.agents/skills/); add --scope user for a personal install.

Manual copy

$ git clone --depth 1 https://github.com/hamen/material-3-skill.git skills-src && mkdir -p .gemini/skills && cp -r skills-src/skills/material-3 .gemini/skills/material-3 && rm -rf skills-src

Use ~/.gemini/skills/ instead of .gemini/skills for a personal install, then run /skills reload.

Gemini CLI skills documentation · loads skills from .gemini/skills/, .agents/skills/

Paste into Gemini CLI

Install the "material-3" agent skill from https://github.com/hamen/material-3-skill/tree/master/skills/material-3 into .gemini/skills/material-3/ in this project. Copy the whole folder (SKILL.md and every file beside it), keep the folder name "material-3", then confirm the skill loads.

Gemini CLI copies the folder itself, the same result as the manual copy. Check what it changed before you commit it.

GitHub CLI

$ gh skill install hamen/material-3-skill material-3

Installs for Copilot at project scope by default; add --scope user for a personal install. Preview a skill first with gh skill preview. Needs GitHub CLI 2.90.0 or later (public preview).

skills CLI

$ npx skills add hamen/material-3-skill --skill material-3 -a github-copilot

Project install goes to .agents/skills/; add -g for ~/.copilot/skills/.

Manual copy

$ git clone --depth 1 https://github.com/hamen/material-3-skill.git skills-src && mkdir -p .github/skills && cp -r skills-src/skills/material-3 .github/skills/material-3 && rm -rf skills-src

Use ~/.copilot/skills/ instead of .github/skills for a personal install. Commit .github/skills so cloud agent and code review can use it.

GitHub Copilot skills documentation · loads skills from .github/skills/, .claude/skills/, .agents/skills/

Paste into GitHub Copilot

Install the "material-3" agent skill from https://github.com/hamen/material-3-skill/tree/master/skills/material-3 into .github/skills/material-3/ in this project. Copy the whole folder (SKILL.md and every file beside it), keep the folder name "material-3", then confirm the skill loads.

GitHub Copilot copies the folder itself, the same result as the manual copy. Check what it changed before you commit it.

skills CLI

$ npx skills add hamen/material-3-skill --skill material-3 -a opencode

OpenCode documents no install command of its own. Project install goes to .agents/skills/; add -g for ~/.config/opencode/skills/.

GitHub CLI

$ gh skill install hamen/material-3-skill material-3 --agent opencode

Project scope by default (.agents/skills/); add --scope user for a personal install.

Manual copy

$ git clone --depth 1 https://github.com/hamen/material-3-skill.git skills-src && mkdir -p .opencode/skills && cp -r skills-src/skills/material-3 .opencode/skills/material-3 && rm -rf skills-src

Use ~/.config/opencode/skills/ instead of .opencode/skills for a personal install.

OpenCode skills documentation · loads skills from .opencode/skills/, .claude/skills/, .agents/skills/

Paste into OpenCode

Install the "material-3" agent skill from https://github.com/hamen/material-3-skill/tree/master/skills/material-3 into .opencode/skills/material-3/ in this project. Copy the whole folder (SKILL.md and every file beside it), keep the folder name "material-3", then confirm the skill loads.

OpenCode copies the folder itself, the same result as the manual copy. Check what it changed before you commit it.

Facts

Skill name: material-3
GitHub stars: 1.5k
Used in: 2 other repos
Token cost: ~7.8k tokens
SKILL.md length: 2,316 words
Files: 8 (incl. references)
Skills in repo: 1
Repo updated: Jul 15, 2026
First seen: Oct 7, 2026
Licence: MIT

At a glance

Implement Google's Material Design 3 (Material You) UI system.

Works in 2 steps: Identify the target: The user provides a… → Inspect the following categories and…
: material design
SKILL.md covers Philosophy, Current Updates: Google I/O 2026, Decision Tree and Design Token System, plus 8 more sections
Calls flutter and npm; reaches fonts.googleapis.com

What it does

Material 3 is an agent skill from hamen/material-3-skill. Implement Google's Material Design 3 (Material You) UI system. Primary: Jetpack Compose Material3 (MaterialTheme, components, adaptive layout). Also Flutter and limited web (@material/web, maintenance mode). Covers tokens, 30+ components, layout, theming, M3 Expressive (platform matrix), and accessibility. Use when: "material design", "MD3", "material you", "Jetpack Compose", "MaterialTheme", "material component", "md3 button".

Its SKILL.md is about 7.8k tokens, which your agent loads only when the skill is triggered. The skill folder holds 9 other files, including reference files (for example `.claude-plugin/plugin.json`, `references/color-system.md` and `references/component-catalog.md`).

It sits in Frontend & Design, covering Android development, Theming and dark mode and Responsive design. It works with Jetpack Compose, Flutter and Android. The repository describes itself as: Material Design 3 skill for Claude Code — 30+ components, design tokens, theming, responsive layout, and MD3 compliance audit. The licence is MIT.

When your agent uses it

: material design
Jetpack Compose
Material component

Example prompts

“material design”
“material you”
“Jetpack Compose”
“/material-3”

Workflow steps

2 steps, taken from the first numbered list in SKILL.md.

Identify the target: The user provides a URL (use browser tools to inspect), file paths (read source), or a running app.
Inspect the following categories and score each 0–10

What it can do on your machine

Read from SKILL.md and the folder at commit 14385f2. It shows what the files ask for, not the result of running them.

Tool permissions
Pre-approves nothing: there is no allowed-tools line, so your agent's usual permission prompts apply.
From allowed-tools in the SKILL.md frontmatter.
Runs code
Shell commands in SKILL.md call:
- flutter
- npm
From the folder's file list and the shell code blocks in SKILL.md.
Network
Hosts in commands or code, which the agent is likely to contact:
- fonts.googleapis.com
Also links to:
- m3.material.io
From URLs in SKILL.md, links to its own repository left out.
Credentials
Names no API keys, tokens, secrets or passwords.
From names ending in _API_KEY, _TOKEN, _SECRET, _KEY or _PASSWORD in SKILL.md.

Context cost

Material 3 loads about 7.8k tokens when it runs, and up to ~36k if it reads all its reference files. Until then it costs about 111 tokens; SKILL.md has 2,316 words of instructions outside code blocks.

Always · name and description, kept in context so the agent knows when to use it: ~111
When it runs · the whole SKILL.md, loaded when a task matches: ~7.8k
With references · SKILL.md plus every file in references/, read only if the agent opens them: ~36k

Estimates: characters ÷ 4, the usual rule of thumb; real counts depend on the model's tokenizer. Scripts and assets cost tokens only if the agent reads them.

Safety

Auto-check passed

The automated check found no risky patterns in SKILL.md.

Automated static check — not a guarantee. Review scripts before installing. It scans the text of SKILL.md for risky patterns (piping downloads into a shell, reading credential files, hidden Unicode, destructive commands); files beside SKILL.md are not scanned.

SKILL.md

The full file from hamen/material-3-skill at commit 14385f2, republished under its MIT licence (© hamen). 2,316 words, ~7,805 tokens.

Download SKILL.mdSave it as .claude/skills/material-3/SKILL.md (or your agent's skills folder). This skill also uses 7 other files; get the full folder from GitHub.

name: material-3
description: Implement Google's Material Design 3 (Material You) UI system. Primary: Jetpack Compose Material3 (MaterialTheme, components, adaptive layout). Also Flutter and limited web (@material/web, maintenance mode). Covers tokens, 30+ components, layout, theming, M3 Expressive (platform matrix), and accessibility. Use when: "material design", "MD3", "material you", "Jetpack Compose", "MaterialTheme", "material component", "md3 button".
user-invokable: true
argument-hint: [component|theme|layout|scaffold|audit] [description or URL]

Material Design 3

This skill guides implementation of Google's Material Design 3 (MD3) — a personal, adaptive, expressive design system. MD3 uses dynamic color, tonal surfaces, rounded shapes, and spring-based motion to create UIs that feel alive and personal.

Philosophy

MD3 is built on three principles:

Personal: Dynamic color adapts UI to the user's wallpaper or content. Theming is individual, not one-size-fits-all.
Adaptive: Layouts transform across 5 window size classes. Components resize, reposition, and change form factor responsively.
Expressive: Shape morphing, spring physics, and emphasized typography create moments of delight without sacrificing usability.

Current Updates: Google I/O 2026

Material's Google I/O 2026 update reinforces a Compose-first Android path and expands expressive/adaptive guidance:

Material Android is Compose-first: For new Android work, prefer Jetpack Compose Material3 for the latest components, expressive APIs, adaptive scaffolds, and Styles API integration. Android Views may remain necessary in existing apps, but they should not be treated as the default path for new Material 3 implementations.
Expressive layout system: Use an expressive layout scaffold to adapt screens across mobile, desktop, foldables, watches, XR, and other spatial form factors. Start from adaptive scaffolds/window size classes instead of fixed phone-first layouts.
8dp spacing system: Apply spacing tokens for margins, padding, and gaps so layouts and components can adapt programmatically to device type and density.
New/updated expressive components: Lists, menus, search, and search app bars have refreshed expressive guidance, with Jetpack Compose as the primary implementation target.
Watches and XR: Watches emphasize physics-based motion, arc text, and edge-hugging containers. XR emphasizes spatial panels and depth-based elevation.

Key differences from MD2:

Tonal surfaces replace elevation shadows as the primary depth cue
Dynamic color generates full schemes from a single seed color
Fully rounded corners by default (not slightly rounded)
Spring-based motion physics replace fixed easing curves for components
3 levels of user-controlled contrast (standard/medium/high)

Relationship with frontend-design skill: When both skills are active, MD3 provides the design system (tokens, components, layout rules) and frontend-design provides creative direction within those constraints. MD3 rules take precedence for component structure and token usage. Note: Roboto/Roboto Flex IS the correct default typeface in MD3 — the frontend-design guidance to avoid Roboto does not apply when implementing MD3.

Decision Tree

What are you building?

Full app scaffold        → See "Common Patterns: App Shell" + references/layout-and-responsive.md
Single component         → See "Component Quick Reference" table → references/component-catalog.md
Custom theme             → See references/theming-and-dynamic-color.md
Form / input layout      → See references/component-catalog.md § Input Components
Navigation structure     → See references/navigation-patterns.md
Data display             → See references/component-catalog.md § Data Display

What platform?

Jetpack Compose          → Primary: androidx.compose.material3, MaterialTheme, references/*
Flutter                  → useMaterial3: true in ThemeData, ColorScheme.fromSeed()
Web (vanilla JS)         → @material/web (limited; maintenance mode) + CSS custom properties
Web (React/Vue/Svelte)   → CSS custom properties + wrapper components (no official React lib)
Web (CSS-only)           → MD3 token values as CSS custom properties (no <md-*> elements)

Design Token System

All MD3 tokens use the md.sys namespace. Jetpack Compose maps roles to MaterialTheme.colorScheme, MaterialTheme.typography, and MaterialTheme.shapes (same semantic roles as the spec). On the web, these map to CSS custom properties (--md-sys-*):

Color Tokens (`--md-sys-color-*`)

Token	Purpose
`primary`	High-emphasis fills, text, icons against surface
`on-primary`	Text/icons on primary
`primary-container`	Standout fill for key components (FAB, etc.)
`on-primary-container`	Text/icons on primary-container
`secondary` / `on-secondary`	Less prominent accents
`secondary-container` / `on-secondary-container`	Recessive components (tonal buttons)
`tertiary` / `on-tertiary`	Contrasting accents
`tertiary-container` / `on-tertiary-container`	Complementary containers
`error` / `on-error`	Error states (static — doesn't change with dynamic color)
`error-container` / `on-error-container`	Error container fills
`surface`	Default background
`on-surface`	Text/icons on any surface
`on-surface-variant`	Lower-emphasis text/icons on surface
`surface-container-lowest`	Lowest-emphasis container
`surface-container-low`	Low-emphasis container
`surface-container`	Default container (nav areas)
`surface-container-high`	High-emphasis container
`surface-container-highest`	Highest-emphasis container
`surface-dim` / `surface-bright`	Maintain relative brightness across light/dark
`inverse-surface` / `inverse-on-surface` / `inverse-primary`	Contrasting elements (snackbars)
`outline`	Important boundaries (text field borders)
`outline-variant`	Decorative elements (dividers)

Full details: references/color-system.md

Typography Tokens (`--md-sys-typescale-*`)

Scale	Sizes	Use
Display	L / M / S	Hero text, large numbers
Headline	L / M / S	Section headers
Title	L / M / S	Smaller headers, card titles
Body	L / M / S	Paragraph text, descriptions
Label	L / M / S	Buttons, chips, captions

Each style has tokens for: -font, -weight, -size, -line-height, -tracking Plus 15 emphasized variants (higher weight) via --md-sys-typescale-emphasized-*

Full details: references/typography-and-shape.md

Shape Tokens (`--md-sys-shape-corner-*`)

Token	Value	Example components
`none`	0dp	—
`extra-small`	4dp	Chips, snackbars
`small`	8dp	Text fields, menus
`medium`	12dp	Cards
`large`	16dp	FABs, navigation drawer
`large-increased`	20dp	(Expressive)
`extra-large`	28dp	Dialogs, bottom sheets
`extra-large-increased`	32dp	(Expressive)
`extra-extra-large`	48dp	(Expressive)
`full`	9999px	Buttons, chips, badges

Elevation Levels

Level	DP	Tonal offset	Use
0	0dp	None	Flat surfaces, most components at rest
1	1dp	+5% primary	Elevated cards, modal sheets
2	3dp	+8% primary	Menus, nav bar, scrolled app bar
3	6dp	+11% primary	FAB, dialogs, search, date/time pickers
4	8dp	+12% primary	(hover/focus increase only)
5	12dp	+14% primary	(hover/focus increase only)

Elevation in MD3 is communicated through tonal surface color, not shadows. Shadows are only used when needed for additional protection against busy backgrounds.

Motion

MD3 Expressive (May 2025) introduced spring-based motion physics for components. The legacy easing/duration system is still used for transitions (enter/exit/shared-axis):

Easing	Duration	Transition type
Emphasized	500ms	Begin and end on screen
Emphasized decelerate	400ms	Enter the screen
Emphasized accelerate	200ms	Exit the screen
Standard	300ms	Begin and end on screen (utility)
Standard decelerate	250ms	Enter screen (utility)
Standard accelerate	200ms	Exit screen (utility)

CSS easing values:

Emphasized: cubic-bezier(0.2, 0, 0, 1)
Emphasized decelerate: cubic-bezier(0.05, 0.7, 0.1, 1)
Emphasized accelerate: cubic-bezier(0.3, 0, 0.8, 0.15)
Standard: cubic-bezier(0.2, 0, 0, 1)
Standard decelerate: cubic-bezier(0, 0, 0, 1)
Standard accelerate: cubic-bezier(0.3, 0, 1, 1)

Component Quick Reference

Component	Web Element	Key Variants	Category
Button	`md-filled-button`, `md-outlined-button`, `md-text-button`, `md-elevated-button`, `md-filled-tonal-button`	Filled, Outlined, Text, Elevated, Tonal; 5 sizes (XS–XL); toggle	Actions
Button group	`md-button-group`	Standard, connected	Actions
Extended FAB	`md-extended-fab`	Surface, Primary, Secondary, Tertiary	Actions
FAB	`md-fab`	Small, Medium, Large	Actions
FAB menu	—	—	Actions
Icon button	`md-icon-button`, `md-filled-icon-button`, `md-filled-tonal-icon-button`, `md-outlined-icon-button`	Standard, Filled, Filled Tonal, Outlined	Actions
Segmented button	—	Single-select, Multi-select	Actions
Split button	—	—	Actions
Badge	—	Small (dot), Large (count)	Communication
Loading indicator	—	Linear, Circular	Communication
Progress indicator	`md-linear-progress`, `md-circular-progress`	Linear, Circular; determinate/indeterminate	Communication
Snackbar	—	Single-line, Two-line, Action	Communication
Tooltip	—	Plain, Rich	Communication
Card	—	Filled, Outlined, Elevated	Containment
Carousel	—	Multi-browse, Uncontained, Hero	Containment
Dialog	`md-dialog`	Basic, Full-screen	Containment
Bottom sheet	—	Standard, Modal	Sheets
Side sheet	—	Standard, Modal	Sheets
Divider	`md-divider`	Full-width, Inset	Containment
Checkbox	`md-checkbox`	—	Input
Chips	`md-chip-set`, `md-assist-chip`, `md-filter-chip`, `md-input-chip`, `md-suggestion-chip`	Assist, Filter, Input, Suggestion	Input
Date picker	—	Docked, Modal, Range	Input
Menu	`md-menu`, `md-menu-item`	—	Input
Radio button	`md-radio`	—	Input
Slider	`md-slider`	Continuous, Discrete, Range	Input
Switch	`md-switch`	With/without icon	Input
Text field	`md-filled-text-field`, `md-outlined-text-field`	Filled, Outlined	Input
Time picker	—	Docked, Modal	Input
App bar (top)	—	Center-aligned, Small, Medium, Large	Navigation
Navigation bar	`md-navigation-bar`	—	Navigation
Navigation drawer	`md-navigation-drawer`	Standard, Modal	Navigation
Navigation rail	—	—	Navigation
Search	—	Search bar, Search view	Navigation
Tabs	`md-tabs`, `md-primary-tab`, `md-secondary-tab`	Primary, Secondary	Navigation
Toolbar	—	—	Navigation
List	`md-list`, `md-list-item`	One-line, Two-line, Three-line	Data Display

Note: Components marked with — for web element don't have @material/web implementations yet. Use CSS custom properties with standard HTML for these. Compose mappings and examples live in references/component-catalog.md.

Full component details with code examples: references/component-catalog.md

Jetpack Compose (primary)

Use androidx.compose.material3 with MaterialTheme and Material 3 composables (Scaffold, Button, NavigationBar, top app bars, etc.).

Theming: MaterialTheme(colorScheme = …, typography = …, shapes = …). Prefer dynamicLightColorScheme / dynamicDarkColorScheme on Android 12+ (API 31+) when dynamic color is desired; otherwise lightColorScheme / darkColorScheme or generated theme code from Material Theme Builder.
Adaptive UI: Window size classes, list-detail and supporting-pane layouts, foldables — see references/layout-and-responsive.md and references/navigation-patterns.md.
Edge-to-edge & insets: Lay out content with WindowInsets / scaffold padding so bars and IME behave correctly — see references/layout-and-responsive.md.
Experimental APIs: Some Material 3 APIs require @OptIn(ExperimentalMaterial3Api::class) or expressive opt-ins; match your BOM and compiler.

kotlin

MaterialTheme(
    colorScheme = colorScheme, // from dynamicLightColorScheme / lightColorScheme / etc.
    typography = Typography(),
    shapes = Shapes(),
) {
    // M3 content — prefer references for Scaffold, navigation, text fields
}

Web (limited): @material/web

Important: Per Material Design 3 for Web, Material Web Components are in maintenance mode and M3 Expressive is not implemented on Web. Use @material/web for token-backed web UIs when appropriate, but do not treat it as equivalent to Compose for current Expressive features.

Setup

bash

npm install @material/web

Import Components Individually

Always import only the components you use — importing the entire package bloats the bundle:

javascript

// Good — individual imports
import '@material/web/button/filled-button.js';
import '@material/web/button/outlined-button.js';
import '@material/web/textfield/outlined-text-field.js';
import '@material/web/icon/icon.js';

// Bad — never do this
import '@material/web'; // imports everything

Basic Usage

html

<!DOCTYPE html>
<html lang="en">
<head>
  <meta charset="UTF-8">
  <meta name="viewport" content="width=device-width, initial-scale=1.0">
  <link href="https://fonts.googleapis.com/css2?family=Roboto+Flex:wght@400;500;700&display=swap" rel="stylesheet">
  <link href="https://fonts.googleapis.com/icon?family=Material+Symbols+Outlined" rel="stylesheet">
</head>
<body>
  <md-filled-button>Get started</md-filled-button>
  <md-outlined-text-field label="Email" type="email"></md-outlined-text-field>

  <script type="module">
    import '@material/web/button/filled-button.js';
    import '@material/web/textfield/outlined-text-field.js';
  </script>
</body>
</html>

Theming with CSS Custom Properties

Apply a custom theme by setting CSS custom properties on :root or any ancestor:

css

:root {
  /* Color scheme (generate with @material/material-color-utilities) */
  --md-sys-color-primary: #6750A4;
  --md-sys-color-on-primary: #FFFFFF;
  --md-sys-color-primary-container: #EADDFF;
  --md-sys-color-on-primary-container: #21005D;
  --md-sys-color-secondary: #625B71;
  --md-sys-color-on-secondary: #FFFFFF;
  --md-sys-color-secondary-container: #E8DEF8;
  --md-sys-color-on-secondary-container: #1D192B;
  --md-sys-color-surface: #FEF7FF;
  --md-sys-color-on-surface: #1D1B20;
  --md-sys-color-surface-container: #F3EDF7;
  --md-sys-color-outline: #79747E;
  --md-sys-color-outline-variant: #CAC4D0;

  /* Typography */
  --md-sys-typescale-body-large-font: 'Roboto Flex', sans-serif;
  --md-sys-typescale-body-large-size: 1rem;
  --md-sys-typescale-body-large-weight: 400;
  --md-sys-typescale-body-large-line-height: 1.5rem;

  /* Shape */
  --md-sys-shape-corner-full: 9999px;
  --md-sys-shape-corner-medium: 12px;
}

Component-Level Overrides

Override individual component tokens for specific customization:

css

md-filled-button {
  --md-filled-button-container-color: var(--md-sys-color-primary);
  --md-filled-button-label-text-color: var(--md-sys-color-on-primary);
  --md-filled-button-container-shape: var(--md-sys-shape-corner-full);
  --md-filled-button-container-height: 40px;
}

md-outlined-text-field {
  --md-outlined-text-field-container-shape: var(--md-sys-shape-corner-small);
  --md-outlined-text-field-focus-outline-color: var(--md-sys-color-primary);
}

Dark Theme

Apply dark theme by overriding color tokens on a class or media query:

css

@media (prefers-color-scheme: dark) {
  :root {
    --md-sys-color-primary: #D0BCFF;
    --md-sys-color-on-primary: #381E72;
    --md-sys-color-primary-container: #4F378B;
    --md-sys-color-on-primary-container: #EADDFF;
    --md-sys-color-surface: #141218;
    --md-sys-color-on-surface: #E6E0E9;
    --md-sys-color-surface-container: #211F26;
    --md-sys-color-outline: #938F99;
    --md-sys-color-outline-variant: #49454F;
  }
}

Full theming guide: references/theming-and-dynamic-color.md

Common Patterns

App Shell

Standard MD3 app with responsive navigation + top app bar + content area:

html

<div class="md3-app">
  <nav class="md3-nav-rail" aria-label="Main navigation">
    <!-- Navigation rail for medium+ screens -->
    <md-fab size="small" aria-label="Compose">
      <md-icon slot="icon">edit</md-icon>
    </md-fab>
    <md-navigation-bar>
      <md-navigation-tab label="Home">
        <md-icon slot="active-icon">home</md-icon>
        <md-icon slot="inactive-icon">home</md-icon>
      </md-navigation-tab>
      <md-navigation-tab label="Search">
        <md-icon slot="active-icon">search</md-icon>
        <md-icon slot="inactive-icon">search</md-icon>
      </md-navigation-tab>
    </md-navigation-bar>
  </nav>
  <main class="md3-content">
    <header class="md3-top-app-bar">
      <h1 class="md3-top-app-bar__title" style="font: var(--md-sys-typescale-title-large)">
        Page Title
      </h1>
    </header>
    <div class="md3-body">
      <!-- Content here -->
    </div>
  </main>
</div>

css

.md3-app {
  display: flex;
  min-height: 100vh;
  background: var(--md-sys-color-surface);
  color: var(--md-sys-color-on-surface);
}

.md3-nav-rail {
  width: 80px;
  background: var(--md-sys-color-surface);
  border-right: 1px solid var(--md-sys-color-outline-variant);
  display: flex;
  flex-direction: column;
  align-items: center;
  padding-top: 12px;
  gap: 12px;
}

.md3-content {
  flex: 1;
  display: flex;
  flex-direction: column;
}

.md3-top-app-bar {
  height: 64px;
  padding: 0 16px;
  display: flex;
  align-items: center;
  background: var(--md-sys-color-surface);
}

.md3-body {
  padding: 24px;
  flex: 1;
}

/* Responsive: switch to bottom nav on compact */
@media (max-width: 599px) {
  .md3-app { flex-direction: column; }
  .md3-nav-rail {
    order: 1;
    width: 100%;
    flex-direction: row;
    justify-content: center;
    border-right: none;
    border-top: 1px solid var(--md-sys-color-outline-variant);
    padding: 0;
  }
}

Card Grid

html

<div class="md3-card-grid">
  <div class="md3-card md3-card--outlined">
    <img src="image.jpg" alt="Description" class="md3-card__media">
    <div class="md3-card__content">
      <h3 style="font: var(--md-sys-typescale-title-medium)">Card Title</h3>
      <p style="font: var(--md-sys-typescale-body-medium); color: var(--md-sys-color-on-surface-variant)">
        Supporting text for this card.
      </p>
    </div>
    <div class="md3-card__actions">
      <md-text-button>Learn more</md-text-button>
      <md-filled-tonal-button>Action</md-filled-tonal-button>
    </div>
  </div>
</div>

css

.md3-card-grid {
  display: grid;
  grid-template-columns: repeat(auto-fill, minmax(300px, 1fr));
  gap: 16px;
}

.md3-card--outlined {
  border: 1px solid var(--md-sys-color-outline-variant);
  border-radius: var(--md-sys-shape-corner-medium, 12px);
  background: var(--md-sys-color-surface);
  overflow: hidden;
}

.md3-card__content { padding: 16px; }
.md3-card__actions { padding: 8px 16px 16px; display: flex; gap: 8px; justify-content: flex-end; }
.md3-card__media { width: 100%; aspect-ratio: 16/9; object-fit: cover; }

Form Layout

html

<form class="md3-form">
  <md-outlined-text-field label="Full name" required></md-outlined-text-field>
  <md-outlined-text-field label="Email" type="email" required></md-outlined-text-field>
  <md-outlined-text-field label="Message" type="textarea" rows="4"></md-outlined-text-field>
  <div class="md3-form__actions">
    <md-text-button type="reset">Cancel</md-text-button>
    <md-filled-button type="submit">Submit</md-filled-button>
  </div>
</form>

css

.md3-form {
  display: flex;
  flex-direction: column;
  gap: 16px;
  max-width: 560px;
}

.md3-form__actions {
  display: flex;
  gap: 8px;
  justify-content: flex-end;
  margin-top: 8px;
}

More patterns: references/navigation-patterns.md, references/layout-and-responsive.md

Show full SKILL.md (1,021 more words)Show less

Anti-Patterns

Never do these when implementing MD3:

Mix MD2 and MD3 libraries: Don't use @material/mdc-* (MD2) alongside @material/web (MD3). They have incompatible APIs and styling.
Hardcode colors: Always use var(--md-sys-color-*) tokens, never raw hex/rgb values. Hardcoded colors break dynamic theming, dark mode, and contrast adjustment.
Ignore tonal pairing: Only combine colors in their intended pairs (e.g., primary + on-primary, surface-container + on-surface). Arbitrary pairings break contrast in dynamic color and high contrast modes.
Use outline for dividers: Use outline-variant for dividers. outline is for important boundaries like text field borders.
Import all of @material/web: Always import individual component modules. Barrel imports include every component and destroy bundle size.
Use border-radius directly: Use shape tokens (var(--md-sys-shape-corner-medium)) so shapes stay consistent with theming.
Use shadows for elevation by default: MD3 communicates elevation through tonal surface color, not shadows. Only add shadows when elements need extra separation from busy backgrounds.
Apply frontend-design "avoid Roboto" rule: On Android, Roboto is the default Material typeface; web often uses Roboto or Roboto Flex with MD3 tokens. Replace only when intentionally customizing the type scale.
Assume SSR compatibility: @material/web uses Web Components (custom elements) which require JavaScript to render. They won't produce meaningful HTML in SSR without additional hydration strategies.
Ignore foldables and large screens: MD3 is designed for all screen sizes. Don't ship phone-only layouts — use canonical layouts, multi-pane at 600dp+, and test on foldable/tablet emulators. Place no interactive content across the fold/hinge.
Stretch content to fill wide screens: On Large (1200dp+) and Extra-large (1600dp+) windows, constrain content to a max width (840–1040dp). Endless-width text lines are unreadable.

Platform Notes

Flutter

dart

MaterialApp(
  theme: ThemeData(
    useMaterial3: true,
    colorScheme: ColorScheme.fromSeed(seedColor: Colors.deepPurple),
  ),
);

Jetpack Compose

See Jetpack Compose (primary) above. Use LocalContext.current with dynamicLightColorScheme / dynamicDarkColorScheme only when Build.VERSION.SDK_INT >= Build.VERSION_CODES.S and dynamic color is enabled; otherwise supply static light/dark schemes.

Component Name Mapping

Concept	Web	Flutter	Compose
Filled button	`md-filled-button`	`FilledButton`	`Button`
Outlined text field	`md-outlined-text-field`	`OutlinedTextField`	`OutlinedTextField`
FAB	`md-fab`	`FloatingActionButton`	`FloatingActionButton`
Navigation bar	`md-navigation-bar`	`NavigationBar`	`NavigationBar`
Switch	`md-switch`	`Switch`	`Switch`

M3 Expressive (May 2025)

The Expressive update adds visual richness while maintaining usability. Availability differs by platform — do not assume one stack implements everything.

Capability	Jetpack Compose	Flutter	Web (`@material/web`)
Expressive layout scaffold / adaptive layout	Compose-first via Material3 adaptive APIs and window size classes	Use Flutter adaptive/layout primitives	CSS/container queries/manual layout; no Material Web parity
8dp spacing system	Use design tokens / `Dp` spacing constants; keep margins, padding, and gaps adaptive	Use theme spacing constants	CSS custom properties / design tokens
Expressive lists, menus, search, search app bar	Primary target per current Material guidance; check BOM and opt-ins	Check current Flutter Material docs	Spec-aligned custom implementation; `@material/web` is maintenance-only
Spring / motion physics	Supported in Material 3 (see `MotionScheme`, expressive APIs per BOM)	Varies by Flutter Material version	Not in Material Web; use easing/duration or custom motion
Emphasized typography	Via theme / type scale	Via theme	Token/CSS only; no full Expressive component set
Shape morphing	Compose-first in Google’s expressive rollout	Check current Flutter docs	Not in `@material/web`
New button sizes (XS–XL), toggle	Follow Compose Material3 components	Follow Flutter MD3	Height/CSS approximations only
Extra corner tokens (e.g. large-increased)	`MaterialTheme.shapes` / tokens	Theme shapes	CSS `--md-sys-shape-*`
3 contrast levels	Scheme builders / system	Plugins / manual	`SchemeContent` contrast parameter in JS utilities
Watches / XR form factors	Use Compose/Wear/XR-specific guidance where available	Platform-specific	Web/spatial UI custom implementation

Web: Material Web is maintenance-only; M3 Expressive is not on Web. Use CSS easing/duration tokens as fallback for motion, not spring parity.

Legacy easing/duration remains valid for transitions (enter/exit/shared-axis) where the spec still references them; see the Motion table below.

MD3 Compliance Audit

When invoked with audit as the argument (e.g., /material-3 audit), or when asked to audit/review MD3 compliance, analyze the target app or page and produce a compliance report.

Audit Procedure

Identify the target: The user provides a URL (use browser tools to inspect), file paths (read source), or a running app.
Inspect the following categories and score each 0–10:

Category	What to check
Color tokens	Web: `--md-sys-color-` / generated CSS. Compose:* `MaterialTheme.colorScheme` roles (no arbitrary `Color(...)` for surfaces without reason). Proper tonal pairing (`onX` on `X`). Dark theme. Flutter: `ColorScheme` roles.
Typography	MD3 type scale: Compose `MaterialTheme.typography`; web typescale tokens; correct roles (Display, Headline, Title, Body, Label).
Shape	Compose `MaterialTheme.shapes` / component `Shape`; web `var(--md-sys-shape-*)`. Buttons: full; cards: medium; avoid magic numbers.
Elevation	Tonal elevation (`Surface` tonal/shadow as appropriate). Web: hover/focus where relevant.
Components	Compose: Material3 composables (`Button`, `Scaffold`, etc.). Web: `@material/web` or spec-aligned HTML/CSS. Correct variants.
Layout	Canonical layouts; Compose window size class / adaptive APIs; readable max width on large widths; foldable hinge avoidance.
Navigation	Bar / rail / drawer / drawers+Compose `NavHost` patterns per size class; predictive back where applicable.
Motion	Compose `MotionScheme` / expressive APIs when used; transitions may still use easing/duration. Web: CSS motion tokens fallback.
Accessibility	MD3 roles help, but verify contrast: UI components often need 3:1 for large text/borders and 4.5:1 for normal text (WCAG 2.x). TalkBack/semantics (Compose), focus order, touch targets (~48dp). Web: ARIA, keyboard.
Theming	Compose: `MaterialTheme` + light/dark/dynamic as designed. Web: CSS custom properties on `:root` or subtree. Flutter: `ThemeData` + `ColorScheme`.

Generate the report:

# MD3 Compliance Audit Report

Target: [URL or file path]
Date: [date]
Overall Score: [X/100]

## Scores by Category
| Category       | Score | Status |
|----------------|-------|--------|
| Color tokens   | X/10  | [pass/warn/fail] |
| Typography     | X/10  | [pass/warn/fail] |
| Shape          | X/10  | [pass/warn/fail] |
| Elevation      | X/10  | [pass/warn/fail] |
| Components     | X/10  | [pass/warn/fail] |
| Layout         | X/10  | [pass/warn/fail] |
| Navigation     | X/10  | [pass/warn/fail] |
| Motion         | X/10  | [pass/warn/fail] |
| Accessibility  | X/10  | [pass/warn/fail] |
| Theming        | X/10  | [pass/warn/fail] |

## Critical Issues
[List items scoring 0-3 with specific file:line references and fixes]

## Warnings
[List items scoring 4-6 with recommendations]

## Passing
[List items scoring 7-10 with notes on what's done well]

## Recommended Fixes (Priority Order)
1. [Most impactful fix first]
2. ...

Audit Methods

For a live URL (browser or devtools):

Inspect computed styles and CSS variables (--md-sys-*)
Resize viewport or use responsive mode for breakpoints
Capture screenshots at key widths if helpful

For source code (file paths provided):

Compose/Kotlin: .kt files — MaterialTheme, composables, Color(0x…) abuse, hard-coded Dp, missing Modifier.semantics where needed
Flutter: .dart — ThemeData, ColorScheme
Web: HTML/JSX/Vue/Svelte; CSS/SCSS for tokens
Check web imports for @material/web vs @material/mdc-* (MD2)

Quick checks (adapt paths to your stack):

# Web: hardcoded colors
grep -rn '#[0-9a-fA-F]\{3,8\}' --include='*.css' --include='*.scss'

# Compose: raw Color(...) audits (sample — tune for your codebase)
grep -rn 'Color(0x' --include='*.kt'

# MD2 on web
grep -rn '@material/mdc-' --include='*.js' --include='*.ts'

Browser automation (if your environment exposes MCP browser tools): navigate, snapshot DOM/CSS variables, resize for breakpoints — optional, not required.

Scoring Guide

9-10: Fully MD3 compliant, uses correct tokens and patterns
7-8: Mostly compliant, minor issues (e.g., a few hardcoded values)
4-6: Partially compliant, some MD3 patterns but significant gaps
1-3: Major violations, mostly non-MD3 or MD2 patterns
0: Not applicable or completely absent

Status thresholds: pass (7+), warn (4-6), fail (0-3)

Reference Documents

references/color-system.md — Color roles, tonal palettes, dynamic color, Compose + CSS mapping
references/typography-and-shape.md — Type scale, shape corners, elevation, motion, Expressive notes
references/component-catalog.md — Components: Compose + @material/web where applicable
references/navigation-patterns.md — Navigation selection, Compose-first adaptive patterns
references/layout-and-responsive.md — Breakpoints, canonical layouts, insets, foldables
references/theming-and-dynamic-color.md — Theming: Compose first, then Flutter and web

Files

SKILL.md and 7 other files (references) in skills/material-3 of hamen/material-3-skill.

SKILL.md
.claude-plugin/plugin.json
references/color-system.md
references/component-catalog.md
references/layout-and-responsive.md
references/navigation-patterns.md
references/theming-and-dynamic-color.md
references/typography-and-shape.md

Open the folder on GitHubat commit 14385f2

Used in 2 other repositories

We found 2 copies of this SKILL.md (exact, near-identical or edited) in other folders, from 2 other GitHub owners. This page covers the copy in hamen/material-3-skill, which our catalogue first saw on October 7, 2026.

Compare with similar skills

Material 3 next to the 5 skills that share the most tags, products or categories with it. Stars are the repository's; “used in” counts other GitHub owners with a copy.

Material 3 compared with similar skills
Skill	Stars	Used in	Tokens	Auto-check	Licence	Repo updated
Material 3 this skillhamen/material-3-skill	1.5k	2 repos	~7.8k	Automated safety check: Pass	MIT	2 mo ago
Android Designhashgraph-online/awesome-codex-plugins	1.2k	—	~2.5k	Automated safety check: Pass	Apache-2.0	yesterday
Compose Multiplatform Patternsmonta-app/ocpp-emulator	179	5 repos	~2k	Automated safety check: Pass	Apache-2.0	6 days ago
Android Compose Patternsmakifbaysal/tasktrooper	109	—	~1.9k	Automated safety check: Pass	Apache-2.0	2 days ago
STS Amethyst Launcher Design SystemModinMobileSTS/SlayTheAmethystModded	400	—	~1.7k	Automated safety check: Pass	Custom licence	8 days ago
Cometchat Android V6 Compose Customizationcometchat/cometchat-skills	129	—	~2k	Automated safety check: Pass	MIT	2 days ago

Similar skills

Android Design
hashgraph-online/awesome-codex-plugins
A skill your agent uses when the user asks for an Android app, Compose UI, Material 3, Material You, Material 3 Expressive, Pixel-style app, foldable/adaptive layout, Play Store deliverable, React…
1.2k GitHub stars~2.5k tokensUpdated yesterday
MobileAuto-check passed
Compose Multiplatform Patterns
monta-app/ocpp-emulator
Compose Multiplatform and Jetpack Compose patterns for KMP projects — state management, navigation, theming, performance, and platform-specific UI.
179 GitHub starsUsed in 5 repos~2k tokens
MobileAuto-check passed
Android Compose Patterns
makifbaysal/tasktrooper
A skill your agent uses when building native Android with Jetpack Compose - stateless composables, state hoisting, ViewModel-owned state, edge-to-edge, predictive back, adaptive layout, atomic…
109 GitHub stars~1.9k tokensUpdated 2 days ago
MobileAuto-check passed
STS Amethyst Launcher Design System
ModinMobileSTS/SlayTheAmethystModded
Design system imported from the SlayTheAmethyst Android Jetpack Compose launcher: Material 3 surfaces, user-selected seed colors, light and dark themes and typography rules.
400 GitHub stars~1.7k tokensUpdated 8 days ago
Frontend & DesignAuto-check passed
Cometchat Android V6 Compose Customization
cometchat/cometchat-skills
Make the CometChat Android v6 UI match your app in the Jetpack Compose cohort — theming with the CometChatTheme composable and lightColorScheme/darkColorScheme, per-component style data classes…
129 GitHub stars~2k tokensUpdated 2 days ago
Frontend & DesignAuto-check passed
Claude Android Ninja
Drjacky/claude-android-ninja
Build and migrate Android apps with Kotlin, Jetpack Compose, MVVM, Hilt, Room 3 (KSP, SQLiteDriver, Flow/suspend DAOs), Navigation3, and multi-module Gradle.
124 GitHub stars~5.2k tokensUpdated 8 days ago
MobileAuto-check passed

Works with

Questions about Material 3

What does Material 3 do?

Implement Google's Material Design 3 (Material You) UI system. Material 3 is an agent skill from hamen/material-3-skill. Implement Google's Material Design 3 (Material You) UI system.

When should I use Material 3?

Material 3 fits situations like: : material design; jetpack Compose; material component.

How do I install Material 3 in Claude Code?

Run `npx skills add hamen/material-3-skill --skill material-3 -a claude-code`. Or copy the skill folder (skills/material-3 in hamen/material-3-skill) into .claude/skills/material-3 in your project. Claude Code loads it when a task matches its description.

How do I install Material 3 in Codex?

Run `npx skills add hamen/material-3-skill --skill material-3 -a codex`. Or copy the skill folder (skills/material-3 in hamen/material-3-skill) into .agents/skills/material-3 in your project. Codex loads it when a task matches its description.

Can I use Material 3 in Cursor, Gemini CLI or GitHub Copilot?

Cursor, Gemini CLI, GitHub Copilot and OpenCode also load SKILL.md folders. With the skills CLI, run `npx skills add hamen/material-3-skill --skill material-3 -a cursor` (or -a gemini-cli, github-copilot or opencode for the others). To copy it by hand, put the folder in .cursor/skills/material-3, .gemini/skills/material-3, .github/skills/material-3 and .opencode/skills/material-3 in your project.

What does Material 3 need to run?

Going by SKILL.md and its folder, Material 3 needs the command-line tools its instructions call (flutter and npm).

Does Material 3 access the network?

SKILL.md names 2 domains. In commands or code: fonts.googleapis.com; the agent is likely to contact it when it follows the instructions. As links in the text: m3.material.io. This is read from the text; nothing was executed.

Is Material 3 safe to install?

Our automated static check of SKILL.md found no risky patterns, such as piping downloads into a shell, reading credential files or hidden Unicode. It is not a guarantee. Review the folder before installing.

What licence does Material 3 use?

Material 3 is published under the MIT licence (the repository's licence). It allows redistribution, so the full SKILL.md is shown on this page.

How many tokens does Material 3 use?

About 7.8k tokens (SKILL.md is roughly 31k characters). Agents keep only the skill's name and description in context until a task matches; then they load SKILL.md in full. Its references folder adds about 28k tokens, read only when the agent opens those files.

What are the alternatives to Material 3?

Skills that share tags, products or a category with Material 3: Android Design (hashgraph-online/awesome-codex-plugins, 1.2k stars), Compose Multiplatform Patterns (monta-app/ocpp-emulator, 179 stars), Android Compose Patterns (makifbaysal/tasktrooper, 109 stars) and STS Amethyst Launcher Design System (ModinMobileSTS/SlayTheAmethystModded, 400 stars). The comparison table on this page puts their stars, adoption, token cost, safety result and licence side by side.

Who maintains Material 3?

hamen (a GitHub user) maintains it in hamen/material-3-skill, which has 1,455 GitHub stars. The repository was last updated on July 15, 2026.

Source: hamen/material-3-skill on GitHub. Facts on this page come from the repository at the commit we read; the author's words are quoted as theirs.

Install Material 3

Facts

At a glance

What it does

When your agent uses it

Example prompts

Workflow steps

What it can do on your machine

Tool permissions

Runs code

Network

Credentials

Context cost

Safety

SKILL.md

Material Design 3

Philosophy

Current Updates: Google I/O 2026

Decision Tree

Design Token System

Color Tokens (--md-sys-color-*)

Typography Tokens (--md-sys-typescale-*)

Shape Tokens (--md-sys-shape-corner-*)

Elevation Levels

Motion

Component Quick Reference

Jetpack Compose (primary)

Web (limited): @material/web

Setup

Import Components Individually

Basic Usage

Theming with CSS Custom Properties

Component-Level Overrides

Dark Theme

Common Patterns

App Shell

Card Grid

Form Layout

Anti-Patterns

Platform Notes

Flutter

Jetpack Compose

Component Name Mapping

M3 Expressive (May 2025)

MD3 Compliance Audit

Audit Procedure

Audit Methods

Scoring Guide

Reference Documents

Files

Used in 2 other repositories

Compare with similar skills

Similar skills

Android Design

Compose Multiplatform Patterns

Android Compose Patterns

STS Amethyst Launcher Design System

Cometchat Android V6 Compose Customization

Claude Android Ninja

Related

Questions about Material 3

Color Tokens (`--md-sys-color-*`)

Typography Tokens (`--md-sys-typescale-*`)

Shape Tokens (`--md-sys-shape-corner-*`)