Material Design 3 UI/UX Skill

Design the system. Not just the screenshot.

A reusable Agent Skill that helps AI design and coding agents create, review, and implement interfaces using Material Design 3, Material You, and optional Material 3 Expressive principles.

Claude Code · OpenAI Codex · Google Antigravity · Kiro · OpenCode · Hermes Agent · OpenClaw

Quick install

macOS / Linux

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

Windows PowerShell

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

The installer distributes the same portable skill package to the supported global agent locations. It does not install, authenticate, configure, or launch any AI agent.

What this skill changes

Without a design skill With material-design-3-ui

“Make it look Material” Start from user goal, hierarchy, and semantics

Rounded cards everywhere Use containment only when it has a purpose

Components chosen by appearance Components chosen by behavior

Random hex values Semantic Material color roles and tokens

Mobile UI stretched to desktop Adaptive structure for the available window

Accessibility checked at the end Accessibility treated as a release requirement

“Expressive” means more decoration Expression used selectively to strengthen hierarchy

This is not a collection of pretty defaults. It is a decision system for AI agents.

Highlights

• Progressive disclosure — a compact SKILL.md routes agents to 13 focused references only when needed.

• Semantic component rules — buttons, FABs, chips, navigation, forms, feedback, surfaces, and more are selected by purpose.

• Adaptive by design — compact through extra-large windows, multi-pane layouts, foldables, resizable windows, and edge-to-edge behavior.

• Accessibility-first — contrast, touch targets, focus, keyboard, semantics, text scaling, localization, and reduced motion.

• M3 Expressive with restraint — color, shape, size, motion, containment, and typography are used intentionally.

• Cross-agent distribution — one package for 7 supported AI agents on Windows, macOS, and Linux.

• Regression checks — static validation plus behavioral evaluation cases help prevent rule regressions.

Core idea: Material Design 3 is a semantic, adaptive, accessible design system—not a rounded-card aesthetic.

Explore

Why it exists · Coverage · Architecture · Install options · Examples · Tests · Contributing

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:

Width class Available width

Compact < 600dp

Medium 600–839dp

Expanded 840–1199dp

Large 1200–1599dp

Extra large ≥ 1600dp

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

The fastest install commands are shown at the top of this README. The options below cover selective installation, upgrades, symlinks, and uninstalling.

By default, the universa