description: Design, redesign, review, or implement user interfaces using Google Material Design 3 (M3), Material You, and optional Material 3 Expressive principles. Use for UI/UX screens, app flows, design systems, component selection, theming, responsive/adaptive layouts, accessibility audits, Figma-ready specifications, or developer handoff where Material Design 3 is required. metadata: updated: 2026-08-17 version: 1.1.0 name: material-design-3-ui

Material Design 3 UI/UX

Purpose

Create interfaces that behave like Material Design 3, not interfaces that merely look rounded or “Google-like.”

Treat M3 as a system:

user goal → information architecture → hierarchy → adaptive layout → semantic tokens → components → states → interaction → motion → accessibility → visual expression

M3 Expressive is optional. Use it to strengthen hierarchy, usability, recognition, and emotional clarity; never use it as permission to make every element loud.

Source of truth

1. Prefer current official Material 3 guidance at https://m3.material.io/.
2. For Android implementation details, prefer https://developer.android.com/.
3. Treat design guidance separately from implementation-library/API status.
4. Verify current official guidance before asserting exact dimensions, dependency versions, experimental API names, or recently changed behavior.
5. Do not silently mix Material 2 rules into Material 3.
6. Pixel and Google-app screenshots are examples, not the specification.

Core rules

MUST

• Start from the user’s task, content, hierarchy, and platform before styling.
• Use semantic design tokens instead of scattered one-off values.
• Choose components by purpose and behavior, not visual resemblance.
• Prefer established M3/platform components when they solve the interaction.
• Define important states: default, pressed, focus, hover where applicable, selected, disabled, loading, error, empty, and success where relevant.
• Design for the available window rather than a guessed device category.
• Preserve accessible contrast, target size, focus, semantics, scaling, and non-color state communication.
• Respect system bars, safe areas, cutouts, keyboards/IME, foldable hinges, and edge-to-edge behavior where applicable.
• Keep primary actions distinguishable from secondary and destructive actions.
• Make custom components inherit the token, state, motion, and accessibility logic of the system.
• Explain deliberate departures from M3 when product requirements justify them.

MUST NOT

• Do not “Materialize” a screen by only adding large radii, pastel colors, shadows, or Material Symbols.
• Do not hardcode raw colors throughout screens when semantic roles can be used.
• Do not use color alone to communicate meaning or state.
• Do not wrap every section or list row in a card.
• Do not maximize corner radius on every component.
• Do not use FABs for minor, destructive, or ambiguous actions.
• Do not use chips as generic buttons or primary navigation.
• Do not use tabs for unrelated top-level destinations.
• Do not make all components equally expressive.
• Do not invent a new control when an established M3/platform control already solves the interaction.
• Do not sacrifice accessibility to preserve a visual composition.
• Do not stretch a compact/mobile layout unchanged across wide windows.

Progressive-disclosure references

Load only the references needed for the current task. Do not read every reference by default.

For a broad end-to-end design, load the references incrementally as decisions require them. Always include the accessibility reference before final approval.

Workflow

Follow this order unless the task explicitly scopes one stage.

1. Understand the product

Identify: - platform, - primary user goal, - primary action, - top-level destinations, - content hierarchy, - data density, - input methods, - brand constraints, - required states and edge cases, - target window sizes, - whether M3 Expressive is desired or appropriate.

If missing information does not block the work, make a conservative M3-aligned assumption and state it. Ask only when the missing information materially changes architecture or interaction.

2. Establish information architecture

Before styling: - group related information, - separate navigation from actions, - identify the primary task per screen, - remove duplicated controls, - define progressive disclosure, - separate destructive actions, - avoid showing information merely because space is available.

3. Choose adaptive structure

Read references/adaptive-design.md and references/navigation.md when multiple window sizes or navigation forms matter.

Prefer canonical patterns such as list-detail, supporting pane, feed, and adaptive navigation when they fit the content.

Wider space must improve context or productivity rather than merely stretch content.

4. Build the theme semantically

Read the relevant color, typography, shape/elevation, and spacing references.

Use the hierarchy:

reference/system tokens → semantic/system roles → component tokens

Screens should depend on semantic roles rather than scattered literal values.

5. Select components

Read references/component-selection.md plus specialized navigation/form/feedback references as needed.

For each important control determine: 1. semantic purpose, 2. emphasis, 3. immediate vs transactional behavior, 4. interaction states, 5. accessibility behavior, 6. adaptive behavior.

6. Define states and feedback

Cover relevant: - loading, - empty, - error, - success, - disabled, - selected, - pressed, - focus, - hover, - busy/submitting.

Error states must provide a recovery path.

7. Apply accessibility

Read references/accessibility.md.

Accessibility is a release requirement. Do not defer it to visual polish.

8. Add motion

Read references/motion.md only when motion is part of the task.

Motion must explain state, hierarchy, spatial relationship, or response. Do not animate for spectacle.

9. Apply M3 Expressive if appropriate

Read references/m3-expressive.md.

Use a few deliberate expressive moments. Routine reading, forms, settings, and dense productivity surfaces should remain calm unless stronger expression improves usability.

10. Audit before approval

Read references/anti-patterns.md and run the self-audit below.

Self-audit

Before delivering a design, score each applicable category 0, 1, or 2.

• 0 = incorrect / missing
• 1 = partially correct / needs refinement
• 2 = ready

A design with any 0 in component semantics, states & feedback, or accessibility is not ready for approval.

Do not inflate scores to satisfy the user. State the concrete issue and correction.

Handoff contract

When asked to design, redesign, audit, or hand off a UI, provide enough detail for another designer or developer to reproduce the decisions.

Unless the user requests another format, include as applicable:

1. Design intent — user goal and hierarchy.
2. Layout — regions, panes, navigation, adaptive behavior.
3. Theme roles — semantic colors, typography, shape, elevation.
4. Component map — exact M3 component type/variant for important controls.
5. States — interaction, loading, empty, error, success, disabled.
6. Accessibility — target size, contrast, names, focus, keyboard, scaling.
7. Motion — only meaningful transitions/state changes.
8. Implementation notes — platform-specific caveats and experimental/unsupported APIs.
9. Self-audit — include when the user asks for a review, audit, or production-readiness check.

When creating actual code or an artifact, apply these decisions instead of stopping at a description.

Semantic handoff example

Prefer:

Screen background: surface
Primary text: onSurface
Secondary text: onSurfaceVariant
Primary CTA: filled button / primary + onPrimary
Secondary CTA: outlined button
Section container: surfaceContainer
Subtle separator: outlineVariant
Error container: errorContainer + onErrorContainer

Avoid handoff based on arbitrary literals unless they come from the project’s token system.

Platform implementation notes

Android / Jetpack Compose

• Prefer androidx.compose.material3 for new M3 work.
• Prefer stable APIs for production unless alpha/experimental dependencies are explicitly accepted.
• Do not assume every M3 Expressive API is stable.
• Use Material theme roles rather than raw colors.
• Follow current Android adaptive guidance for resizable and large-window experiences.
• Treat edge-to-edge and system insets as layout concerns.
• For Wear OS, use Wear Material 3 rather than mixing mobile components.

Do not hardcode library version numbers into generated implementation unless they are verified against current official release notes.

Web / other platforms

Material 3 guidance can inform the design even when an official implementation library does not expose every component.

• reproduce semantics and token relationships, not Android-specific quirks,
• preserve native platform accessibility and input conventions,
• mark custom implementations clearly,
• do not claim official platform availability without verification.

Final principle

Material Design 3 is a semantic, adaptive, accessible design system.

A successful M3 interface should remain coherent when brand colors change, the window resizes, dark theme turns on, text scales up, keyboard replaces touch, or expressive styling is reduced.

If the design only works because every surface is rounded and colorful, it is not a robust Material 3 design.

Material Design 3 UI/UX Skill

A reusable Agent Skill for designing, redesigning, reviewing, and implementing interfaces with Google Material Design 3, Material You, and Material 3 Expressive principles.

This repository provides a practical SKILL.md that teaches AI design and coding agents how to use Material Design 3 as a real design system—not as a collection of rounded cards, purple buttons, and Material icons.

The skill turns M3 guidance into actionable rules for information architecture, visual hierarchy, semantic design tokens, component selection, adaptive layouts, interaction states, motion, accessibility, implementation handoff, and optional M3 Expressive treatment.

Why this exists

Material Design 3 is easy to imitate visually and surprisingly easy to apply incorrectly.

A UI can look “Material” while still using the wrong component semantics, weak hierarchy, arbitrary colors, inaccessible controls, broken responsive behavior, excessive cards, or decorative motion that does not communicate anything.

This skill is designed to prevent that.

Instead of telling an agent to simply “make this look like Material Design 3,” give it a reusable system that defines how M3 decisions should actually be made.

User goal
   ↓
Information architecture
   ↓
Hierarchy
   ↓
Adaptive layout
   ↓
Semantic tokens
   ↓
Components
   ↓
States & interaction
   ↓
Motion
   ↓
Accessibility
   ↓
Visual expression

What the skill covers

Material 3 foundations

• Semantic color roles and surface hierarchy
• Material typography roles
• Shape systems and reusable shape tokens
• Elevation and tonal surface relationships
• Spacing and alignment
• Design tokens
• Light and dark theme behavior
• Dynamic color considerations

Component selection

The skill teaches agents to choose components by purpose and behavior, not by appearance.

Coverage includes:

• Filled, tonal, elevated, outlined, and text buttons
• Icon buttons
• FAB and Extended FAB
• Split buttons and button groups
• Cards
• Lists
• Dividers
• Badges
• Carousels
• Chips
• Checkboxes
• Radio buttons
• Switches
• Segmented buttons
• Navigation bars
• Navigation rails
• Navigation drawers
• Top and bottom app bars
• Tabs
• Text fields
• Search
• Menus
• Sliders
• Date and time pickers
• Dialogs
• Bottom sheets
• Snackbars
• Tooltips
• Progress and loading indicators

Adaptive UI

The skill treats responsiveness as a structural design problem rather than simply scaling a mobile screen.

It covers:

It also guides agents through list-detail layouts, supporting panes, feeds, adaptive navigation, resizable windows, tablets, foldables, desktop-sized layouts, safe areas, and edge-to-edge interfaces.

Accessibility

Accessibility is treated as a release requirement.

The rules include:

• 48dp × 48dp minimum Android-oriented touch targets
• Text and UI contrast requirements
• Visible and logical focus
• Keyboard support
• Accessible names for icon-only controls
• Screen-reader semantics
• Text scaling
• Localization resilience
• Reduced-motion support
• Error recovery
• Non-color state communication

Material 3 Expressive

M3 Expressive is supported as an optional layer, not a license to make every screen visually loud.

The skill guides agents in the intentional use of:

• Color
• Shape
• Size
• Motion
• Containment
• Typography
• Shape morphing
• Expressive hierarchy
• Emphasized actions
• Selective visual moments

The core rule is simple:

Expression must improve hierarchy, usability, recognition, or emotional clarity.

The anti-“fake Material” rules

This skill explicitly rejects common shortcuts that produce interfaces which only look vaguely Material.

DON'T:
✗ Put every section inside a rounded card
✗ Turn every control into a pill
✗ Use the primary color everywhere
✗ Add shadows to every container
✗ Use chips as generic buttons
✗ Use tabs as unrelated top-level navigation
✗ Add multiple competing FABs
✗ Treat gradients as a shortcut to “Material”
✗ Stretch a phone layout across desktop widths
✗ Animate elements purely for spectacle
✗ Ignore focus, keyboard, text scaling, or reduced motion

DO:
✓ Start from the user's task
✓ Establish information hierarchy first
✓ Use semantic design tokens
✓ Select components by behavior
✓ Design all important states
✓ Adapt structure to available window size
✓ Preserve accessibility
✓ Use expression selectively

Repository structure

.
├── SKILL.md
├── skill-files.txt
├── references/
│   ├── accessibility.md
│   ├── adaptive-design.md
│   ├── anti-patterns.md
│   ├── color-system.md
│   ├── component-selection.md
│   ├── feedback-and-overlays.md
│   ├── forms-and-input.md
│   ├── m3-expressive.md
│   ├── motion.md
│   ├── navigation.md
│   ├── shape-and-elevation.md
│   ├── spacing-and-layout.md
│   └── typography.md
├── tests/
│   ├── cases/
│   └── validate_skill.py
├── install.sh
├── install.ps1
├── uninstall.sh
├── uninstall.ps1
├── CHANGELOG.md
├── CONTRIBUTING.md
├── LICENSE
└── .github/

Progressive disclosure

SKILL.md is intentionally the decision engine, not a giant Material 3 textbook.

It routes the agent to focused files under references/ only when a task needs them. A navigation task can load navigation guidance; a form can load form and accessibility guidance; M3 Expressive guidance is loaded only when expression is relevant.

This reduces unnecessary context while keeping detailed rules available on demand.

skill-files.txt defines the portable skill package. The cross-agent installers copy SKILL.md plus every referenced package file to the selected host.

Installation

One command — macOS / Linux

curl -fsSL https://raw.githubusercontent.com/skydashnet/material-design-3-ui-skill/main/install.sh | bash

One command — Windows PowerShell

irm https://raw.githubusercontent.com/skydashnet/material-design-3-ui-skill/main/install.ps1 | iex

By default, the universal installer places the skill in the global skill location for every supported host. This avoids false negatives when an IDE is installed without its CLI on PATH.

The installer is filesystem-only. It does not install, configure, authenticate, or launch any AI agent.

Security note: Piping a remote script directly into a shell is convenient, but review the script first when that matters for your environment. The clone-and-run method below is easier to inspect and pin to a specific commit or release.

Supported agents

Every destination receives the same portable skill package: SKILL.md plus its progressive-disclosure references/ files.

Clone and install

git clone https://github.com/skydashnet/material-design-3-ui-skill.git
cd material-design-3-ui-skill
./install.sh

Windows:

git clone https://github.com/skydashnet/material-design-3-ui-skill.git
cd material-design-3-ui-skill
.\install.ps1

Install only detected agents

./install.sh --detect

.\install.ps1 -Detect

Detection checks the relevant CLI when available and the host's existing configuration directory. Universal mode remains the default because it is more reliable for GUI-only installations.

Install for selected agents

./install.sh --agent claude --agent codex --agent antigravity

.\install.ps1 -Agent claude,codex,antigravity

Supported names: claude, codex, antigravity, kiro, opencode, hermes, openclaw.

Upgrading from v1.0: v1.1 installs a multi-file skill package instead of only SKILL.md. If an older installation already exists, run the installer with --force / -Force after reviewing any local edits.

Updating an existing installation

The installer never silently overwrites a different existing skill directory. Re-run with force after reviewing local changes.

./install.sh --force

.\install.ps1 -Force

If the installed SKILL.md is already identical, the installer reports it as up to date and makes no change.

Symlink mode for contributors

When working from a c