An Agent Skill for building Android UI with Material Design 3 Expressive (MD3E) on Jetpack Compose.
It follows the Agent Skills specification: a slim SKILL.md
entry point plus a references/ tree loaded on demand. Native support is wide — the official client
showcase lists 46 clients, including Claude Code, Cursor, VS Code / GitHub Copilot, TRAE, Gemini
CLI, Codex, JetBrains Junie, Roo Code, Amp, OpenHands, Factory, Spring AI and CodeBuddy. In these,
the assistant matches your question against the description, loads SKILL.md, then opens only the
reference files that question actually needs.
A few editors still have no skill mechanism (Windsurf, Cline, 通义灵码, 文心快码). They can use the
skill through a rules file, but the cost is real: rules are injected every turn and cannot pull in
references/ by themselves, so the model may answer from the SKILL.md summary alone.
Material 3 Expressive is Google's 2025 evolution of Material Design 3, featuring:
- Spring-based motion (MotionScheme) replacing easing curves
- Expanded color system with 18 new Fixed color roles + 7 surface container roles
- New components: FloatingToolbar, ButtonGroup,
SplitButtonLayout, WideNavigationRail, ShortNavigationBar, ToggleFloatingActionButton, LoadingIndicator, and more - Expressive design principles: bolder colors, varied shapes, variable typography, container grouping
This skill covers both MD3E and baseline M3 — many components only have M3 specs, so the skill uses MD3E where available and falls back to M3 otherwise.
Knowledge baseline: 2026-11-10. Full M3E component set requires material3 1.5.0-rc01
(the 1.5.0 line entered beta on 2026-10-07 and reached RC on 2026-11-04); stable 1.4.0 ships
M3 + MotionScheme + partial Expressive only.
- Implementation specs (
references/recipes/): code-first spec per component family — every variant including the retired ones, exact values lifted from*Tokens.kt, color / shape / state matrices and runnable snippets. The official pages keep their measurements inside images, so this is the layer that carries the numbers you actually type - Complete API reference: Full
androidx.compose.material3package documentation (~8,000 lines) - Source-verified M3E signatures: 1.5.0-line APIs (
MaterialExpressiveTheme, 8-sizeShapes,MotionScheme,FloatingToolbar,ButtonGroup,SplitButtonLayout,LoadingIndicator, …) checked file-by-file againstandroidx/androidx - Code patterns: Ready-to-paste wiring for theming, adaptive navigation, floating toolbars, button groups, split buttons, search, loading, lists, motion and accessibility
- Official samples map: The 49 official
*Samples.ktfiles,compose-samplesapps, Now in Android and the official docs — tells you exactly which file to read per component - Design tokens: All 48 color roles, 15 base + 15
*Emphasizedtype styles, 8 shape sizes, motion system values - Component catalog: Every M3/M3E component organized by category with usage guidance, plus per-entry deprecation status
- Deprecation map: The baseline components M3E retired — segmented button, navigation drawer, bottom app bar, baseline nav bar/rail, 40dp small FAB, medium/large top app bar — and what replaces each. Keeps generated UI from looking like plain M3
- Version baseline: Feature gates, 1.5.0-line churn, BOM coverage (2026-11-10)
- Curated M3E notes: Design system, color/type/shape, motion physics, components, Compose API
- M3 vs M3E diff: Clear comparison and migration guide
- Official guidance, folded in: the m3.material.io component pages were distilled into
references/recipes/— variants, values, code, Do/Don't and accessibility per component — then the raw 263-page mirror was removed so there is a single source of truth - Code templates: Ready-to-use
MD3ETheme.kt,Color.kt,Type.kt,Shape.kt - Theme generator: Python script to generate a complete color scheme from a single seed color
The skill is a plain folder — SKILL.md + references/ + assets/ + scripts/. Pick the mode
your assistant supports.
Mode 1 — native skill support (recommended). Copy md3e/ into the client's skills directory,
keeping SKILL.md at the folder root. The directory name must match the name field (md3e):
| Client | Project-level | User-level |
|---|---|---|
| Claude Code | .claude/skills/md3e/ |
~/.claude/skills/md3e/ |
| Cursor | .cursor/skills/md3e/ |
~/.cursor/skills/md3e/ |
| VS Code / GitHub Copilot | .github/skills/md3e/ |
~/.copilot/skills/md3e/ |
| CodeBuddy | .codebuddy/skills/md3e/ |
~/.codebuddy/skills/md3e/ |
| Other native clients | see the client showcase (46 listed) |
How it is used: no slash command needed. The description in SKILL.md is the trigger — ask a
normal question ("build a floating toolbar", "what are the M3E color roles") and the assistant
decides to load the skill, then reads references/*.md on demand.
Mode 2 — rules file (fallback for clients without skill support). Put only the body of
SKILL.md into the rules entry and keep the md3e/ folder in the repo, so the relative
references/... paths still resolve. Never inline the whole references/ tree — rules files are
injected every turn, and inlining turns a 3k-line skill into a permanent context tax.
| Client | Rules entry |
|---|---|
| Windsurf | .windsurf/rules/md3e.md |
| Cline | .clinerules/md3e.md |
| 通义灵码 / 文心快码 | the tool's custom-instruction entry |
| Anything else | AGENTS.md at the repo root (widely recognised) |
Trade-off: in this mode the model always has SKILL.md in context but has to be told to open
a references/ file, so it may answer from the summary alone.
Most assistants with terminal access can install the skill themselves. Paste this prompt:
Install the MD3E skill from
<path-to-md3e>/:
- run
python <path-to-md3e>/scripts/install_skill.py --target <skills-dir>- verify
<skills-dir>/md3e/SKILL.mdstarts withname: md3e- verify
references/component-index.mdandreferences/m3e-api-signatures.mdexist- tell me the install path and how to verify it
Known locations are built in:
python scripts/install_skill.py --assistant claude --home # ~/.claude/skills/md3e
python scripts/install_skill.py --assistant cursor --home # ~/.cursor/skills/md3e
python scripts/install_skill.py --assistant copilot # .github/skills/md3e
python scripts/install_skill.py --assistant codebuddy --home # ~/.codebuddy/skills/md3e
python scripts/install_skill.py --target ./skills # ./skills/md3e
python scripts/install_skill.py --target ./skills --dry-run # show the plan onlyThe script installs skill content only (allow-list), refuses to install inside the source folder,
and refuses to overwrite an existing install without --force.
If the assistant cannot run commands, ask it to extract md3e.zip, copy the md3e/ folder into the
skills directory, and then run the same four checks.
Verify the install: ask "What is the MD3E knowledge baseline?" — the expected answer is
2026-11-10, citing references/version-baseline.md and material3 1.5.0-rc01. Any other answer
means the skill is not loaded.
md3e/
├── SKILL.md
├── references/
├── assets/
└── scripts/
python scripts/generate_theme.py --seed #6750A4 --package com.example.app --output ./theme/Install material-color-utilities for accurate HCT color generation — both the 0.2.x and the legacy
0.1.x APIs are auto-detected. Without it the script falls back to a built-in HSL approximation:
pip install material-color-utilitiesmd3e/
├── SKILL.md # Entry point: triggers, workflow, quick reference
├── references/
│ ├── recipes/ # Implementation specs — primary source of truth
│ │ ├── INDEX.md # Status legend (✅/⚠️/🧪/🚫), data precedence, coverage
│ │ ├── buttons.md # 5 styles × 5 sizes × 2 shapes + 4 toggle + SplitButton
│ │ ├── button-groups.md # standard (overflow) / connected (replaces segmented)
│ │ ├── icon-buttons.md # 4 styles × default/toggle × 5 sizes
│ │ ├── fabs.md # 56/80/96 + extended tiers + menu/toggle morphs
│ │ ├── app-bars.md # Small / MediumFlexible / LargeFlexible / docked toolbar
│ │ ├── navigation.md # Short bar / Wide rail / drawer replacement
│ │ ├── tabs.md # Primary / Secondary / scrollable
│ │ ├── text-fields.md # Filled / Outlined / Secure / search, two API styles
│ │ ├── selection.md # Checkbox / Radio / Switch / Slider / Chips + decision table
│ │ ├── feedback.md # Progress / Loading / Snackbar / Tooltip / Badge / Divider
│ │ ├── containers.md # Card / Dialog / BottomSheet / Menu / ListItem
│ │ ├── pickers.md # Date / DateRange / DateInput / Time
│ │ ├── carousel.md # multi-browse / uncontained / hero
│ │ └── foundations.md # Breakpoints / RTL / interaction / a11y baseline
│ ├── version-baseline.md # Version matrix, feature gates, 1.5.0 churn (2026-11-10)
│ ├── m3e/ # Curated M3E notes (5 zh + 5 en mirrors, verified 2026-10-23)
│ │ ├── design-system.md # Theming, dynamic color, system UI (+ design-system.en.md)
│ │ ├── color-typography-shape.md # Color / type / shape (+ color-typography-shape.en.md)
│ │ ├── motion-physics.md # MotionScheme spring physics (+ motion-physics.en.md)
│ │ ├── components.md # Component inventory by version line (+ components.en.md)
│ │ └── compose-api.md # API gates, migration, 1.5.0 churn (+ compose-api.en.md)
│ ├── compose-api-full.md # Complete official API reference (~8,000 lines, stable line)
│ ├── m3e-api-signatures.md # Source-verified 1.5.0-line signatures
│ ├── compose-patterns.md # Verified code patterns (theme/nav/toolbar/search/...)
│ ├── official-samples.md # Where the official samples live + what each shows
│ ├── component-index.md # Component -> source file -> sample -> recipe section
│ ├── design-tokens.md # Color/typography/shape/motion/elevation tokens
│ ├── components-catalog.md # All components by category with M3/M3E tags
│ ├── m3-vs-m3e-diff.md # Differences + migration guide + IO2026 updates
│ ├── expressive-design-tactics.md # 7 expressive design tactics with guidance
│ └── design-research.md # Color science, readability, motion patterns, a11y
├── assets/
│ └── templates/
│ ├── MD3ETheme.kt # MaterialExpressiveTheme setup template
│ ├── Color.kt # Full 48-role color scheme template
│ ├── Type.kt # 15 base type styles (+ 15 Emphasized slots documented)
│ └── Shape.kt # 8-size shape scale template
└── scripts/
├── generate_theme.py # Seed color -> complete Compose theme
├── install_skill.py # Install into a skills directory (AI can run this)
└── package_skill.py # Build dist/md3e.zip (repository only, not shipped)
| Category | M3 | MD3E |
|---|---|---|
| Theme | MaterialTheme |
MaterialExpressiveTheme |
| Color | lightColorScheme() / darkColorScheme() |
+ expressiveLightColorScheme() |
| Motion | Easing + duration tokens | MotionScheme.standard() / .expressive() |
| Opt-in | @ExperimentalMaterial3Api |
+ @ExperimentalMaterial3ExpressiveApi |
After installing the skill, just ask your AI assistant naturally. The skill auto-triggers on relevant requests:
Theming setup:
"Set up Material 3 Expressive theming for my Compose app with dynamic color support"
Component creation:
"Create a Material 3 Expressive floating toolbar with 3 action buttons" "Build a button group with overflow menu using MD3E" "Make a Material 3 card list following the design spec"
Design guidance:
"What are the MD3E color roles and when to use each?" "What's the difference between M3 and M3E motion system?" "Which shape should I use for a FAB?"
Migration:
"Migrate my app from MaterialTheme to MaterialExpressiveTheme" "Update my color scheme to include the new M3E fixed color roles"
Theme generation:
"Generate a Compose color scheme from the seed color #6750A4"
- m3.material.io — Official Material Design 3 Expressive guidelines
- androidx.compose.material3 — Official Compose Material 3 API reference
- Compose Material 3 guide — Official developer guide
This skill is for reference and educational purposes. The actual behavior of Material 3 Expressive components may vary depending on the Compose Material 3 library version. Always test in your own environment before relying on it for production.
Apache License 2.0 — same as the Material Design components and AndroidX libraries.
See CONTRIBUTING.md for how to report issues, propose changes, and submit pull requests. The file is repository-only and is not included in the release zip.
See CHANGELOG.md for the version history (SemVer).