material-design-3-ui-skill

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 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

Agent	Global installation used by this project
Claude Code	~/.claude/skills/material-design-3-ui/
OpenAI Codex	~/.agents/skills/material-design-3-ui/
Google Antigravity	~/.gemini/config/skills/material-design-3-ui/
Kiro	~/.kiro/skills/material-design-3-ui/
OpenCode	~/.config/opencode/skills/material-design-3-ui/
Hermes Agent	~/.hermes/skills/material-design-3-ui/
OpenClaw	${OPENCLAW_STATE_DIR:-~/.openclaw}/skills/material-design-3-ui/

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