M3 Expressive: a Material Design 3 skill for AI coding agents

Give Claude Code, Codex, Cursor, Copilot, and Gemini CLI the real Material Design 3 spec. Exact
design tokens, per-component dp geometry, motion spring values, shape morphing rules, emphasized
typography, color roles, and 2,587 reference images, packaged as an
Agent Skill your assistant loads on its own the moment you ask for
Material UI.

claude plugin marketplace add abhixv/m3-expressive-design-skill
claude plugin install m3-expressive@m3-expressive

Not on Claude? Jump to Codex, Cursor, GitHub Copilot,
Gemini CLI, or
Windsurf, Cline, opencode, Zed, and anything else.

Why this exists

Ask any model for a Material 3 Expressive spec and it will answer instantly, in the right vocabulary,
with numbers that look exactly like real tokens. Some of them are. The rest are invented, and an
invented dp value is indistinguishable from a real one on the page, so it ships.

This skill closes that gap two ways. It puts the actual values in reach, and it holds the model to a
source contract: every number, token name, and component name must be looked up, and anything M3
doesn't publish gets labelled as a design decision instead of quietly passed off as spec.

The last two matter as much as the first three. Most Material mistakes aren't missing knowledge,
they're plausible defaults applied to the wrong component, and those are what the do/don't rules
in each reference catch.

Measured. 14 questions whose answers are exact values from the references, asked through
claude -p with no tools and no skill, then again with this plugin loaded. Run on 11 October 2026:

The first two rows of the table above are the two wrong answers Sonnet gave. Strong models already
know a lot of M3 from memory; the skill's job is the remaining values, and the ones they get wrong
without noticing.

What you get

Size: the repo is under 1 MB, so plugin install and git clone are quick. The images are
495 MB and entirely optional, since every number lives in the markdown. See
reference images.

Install

Claude Code

As a plugin. One command, and claude plugin marketplace update keeps it current:

claude plugin marketplace add abhixv/m3-expressive-design-skill
claude plugin install m3-expressive@m3-expressive

claude plugin list                                  # what's installed
claude plugin marketplace update m3-expressive      # pull updates
claude plugin uninstall m3-expressive

As a personal skill. Available in every project. Claude Code picks up any directory under
~/.claude/skills/ that contains a SKILL.md:

git clone https://github.com/abhixv/m3-expressive-design-skill.git ~/m3-skill
ln -s ~/m3-skill/skills/m3-expressive ~/.claude/skills/m3-expressive

git clone https://github.com/abhixv/m3-expressive-design-skill.git "$env:USERPROFILE\m3-skill"
New-Item -ItemType Directory -Force "$env:USERPROFILE\.claude\skills" | Out-Null
Copy-Item -Recurse -Force `
  "$env:USERPROFILE\m3-skill\skills\m3-expressive" "$env:USERPROFILE\.claude\skills\"

As a project skill. Commit it, and everyone who clones your repo gets it, scoped to that project:

mkdir -p .claude/skills
cp -r /path/to/m3-skill/skills/m3-expressive .claude/skills/
git add .claude/skills/m3-expressive && git commit -m "Add m3-expressive skill"

your-project/
└── .claude/
    └── skills/
        └── m3-expressive/
            ├── SKILL.md
            ├── references/
            ├── scripts/
            └── visuals/        # consider .gitignore-ing, see slim install

Claude apps (web, desktop, mobile)

Zip the text-only build and upload it under Settings > Capabilities > Skills. The images are
far past any upload limit, so leave them out. The skill is fully functional without them:

cd /path/to/m3-skill/skills
zip -r m3-expressive.zip m3-expressive -x "m3-expressive/visuals/*"

Codex CLI

Codex reads AGENTS.md, either the repo's at the project root or a global one at
~/.codex/AGENTS.md. Clone the skill once, then point Codex at it:

git clone https://github.com/abhixv/m3-expressive-design-skill.git ~/m3-skill

Append the pointer block to ~/.codex/AGENTS.md (global) or your project's
AGENTS.md (per-repo). If your Codex version supports skill directories natively, drop it in there
instead. Same folder, no changes:

mkdir -p ~/.codex/skills
ln -s ~/m3-skill/skills/m3-expressive ~/.codex/skills/m3-expressive

Cursor

Cursor loads project rules from .cursor/rules/*.mdc. Vendor the skill into the repo, then add a rule
that routes to it:

mkdir -p .cursor/rules .agent-skills
cp -r /path/to/m3-skill/skills/m3-expressive .agent-skills/

.cursor/rules/m3-expressive.mdc:

---
description: Material Design 3 / M3 Expressive spec, tokens, component dp, motion springs
globs: ["**/*.kt", "**/*.dart", "**/*.tsx", "**/*.css"]
alwaysApply: false
---

Read `.agent-skills/m3-expressive/SKILL.md` before writing any Material Design UI, then follow
its "Where to look" table into the specific reference file. Never state a dp value, token name,
or spring parameter from memory. Look it up. Label anything not in M3 as a design decision.

GitHub Copilot

Copilot reads .github/copilot-instructions.md. Vendor the skill into the repo and add the
pointer block to that file:

mkdir -p .agent-skills .github
cp -r /path/to/m3-skill/skills/m3-expressive .agent-skills/

Gemini CLI

Gemini CLI reads GEMINI.md, at the project root or ~/.gemini/GEMINI.md globally. Same move: clone
the skill, add the pointer block.

Any other agent, the universal method

Windsurf (.windsurf/rules/), Cline (.clinerules/), opencode and Zed (AGENTS.md), Aider
(CONVENTIONS.md), or anything with a system-prompt file: the mechanism is always the same two steps.

1. Put the folder somewhere the agent can read. Either .agent-skills/m3-expressive/ in the repo,
   or ~/m3-skill/skills/m3-expressive globally.
2. Add the pointer block to whatever instruction file that agent loads.

Some runtimes are converging on a shared ~/.agents/skills/ location. If yours does, one symlink
covers all of them at once:

mkdir -p ~/.agents/skills
ln -s ~/m3-skill/skills/m3-expressive ~/.agents/skills/m3-expressive

The pointer block

Paste this into AGENTS.md, GEMINI.md, .github/copilot-instructions.md, CLAUDE.md, or your
agent's equivalent. Fix the path to match where you put the folder:

## Material Design 3 / M3 Expressive

The M3 spec lives at `.agent-skills/m3-expressive/`.

Before writing or reviewing any Material Design UI (components, dp values, corner radii,
motion springs, type styles, color roles, adaptive layouts), read
`.agent-skills/m3-expressive/SKILL.md` and follow its "Where to look" table into the
specific reference file.

Never state a number, token name, or component name from memory. Look it up:
- exact values (type scale, radii, springs, elevation) -> `references/tokens.md`
- per-component dp geometry -> `references/component-tokens.md`
- component behavior, variants, do/don'ts -> `references/components/*.md`
- platform API availability -> `references/platforms.md`

If a value genuinely isn't in M3, say so and label it "my design decision (not in M3)"
rather than presenting it as spec.

That block is the whole trick. It transplants the source contract into agents that don't
auto-discover skills, which is why this works the same everywhere.

Reference images (optional)

The repo ships the caption index (visuals/INDEX.tsv) but not the 2,587 images, which would make
every install a 495 MB download. The skill reads the index to tell you which diagram answers your
question; to actually open the diagrams, add the images in either of two ways:

# 1. Download the zip from the latest release (495 MB) and unpack it into the skill folder
cd ~/.claude/skills/m3-expressive
curl -L -o visuals.zip https://github.com/abhixv/m3-expressive-design-skill/releases/latest/download/m3-expressive-visuals.zip
unzip -q visuals.zip && rm visuals.zip

# 2. Or regenerate them from m3.material.io (~5 min, 2,587 files, needs Node.js)
cd ~/.claude/skills/m3-expressive && node scripts/refresh-m3.js images visuals

Both put the files under visuals/, next to INDEX.tsv, where references/visuals.md expects
them. .gitignore already excludes them, so vendoring the skill into your own repo stays light.

Verify it loaded

Restart your agent, since skills are discovered at startup, then ask something only the skill can
answer:

What are the expressive fast spatial spring values, and what corner radius should a child inside a
48dp-radius card with 16dp padding use?

Correct: damping 0.6 / stiffness 800, and 32dp (inner = outer − padding). Anything else and
the skill isn't being read. Check that the folder contains SKILL.md at its top level, and that your
pointer path is right.

Using it

Claude Code loads it automatically whenever a request touches Material Design. The skill's
description triggers on M3, M3 Expressive, Material You, Material components, motion springs, shape
morphing, emphasized typography, color roles, adaptive layout, and Jetpack Compose / MDC-Android /
Flutter / web Material UI. You can also invoke it by name:

/m3-expressive

It's built for three kinds of work:

• Designing. "Design a now-playing screen with M3 Expressive." You get a spec with real token
  values, and every unpublished value labelled as a decision rather than smuggled in as spec.
• Implementing. "Build this as a Compose component." references/platforms.md gets checked
  first: availability is uneven, and M3 Expressive APIs are experimental until Compose 1.5.0.
• Reviewing. "Check this screen against M3." The common-mistakes table and the per-component
  do/don't rules exist for exactly this pass.

Keeping it current

cd ~/.claude/skills/m3-expressive

node scripts/refresh-m3.js pages /tmp/m3-pages    # guideline prose to markdown
node scripts/refresh-m3.js images visuals         # reference images + caption index
node scripts/refresh-component-tokens.js          # per-component dp, rewrites the reference in place

refresh-component-tokens.js is byte-reproducible and writes over its reference directly. The other
two write to a directory you name, so diff before folding changes in, since the references carry
hand-written organization on top of the raw output. Requires Node.js; nothing else here does.

On accuracy. Design guidance, placement rules, and do/don'ts come from the Material guidelines.
The md.comp.* geometry in component-tokens.md, plus the type scale, spring, shape, and elevation
values, comes from the generated androidx.compose.material3.tokens sources, and each group carries
the generator version it was taken from. The two are kept distinct on purpose, so the skill can
attribute correctly. Known gaps are recorded as ## Gaps sections rather than filled with plausible
values. Captured July 2026.

FAQ

What an agent skill is

A folder with a SKILL.md at its root, carrying YAML frontmatter with a name and a description.
The agent reads only the description until something in your request matches it, then loads the body
and, from there, whichever reference files it needs. It's why 800 KB of specification costs almost no
context until the moment it's relevant.

Does it work with models other than Claude?

Yes. SKILL.md and the references are plain markdown with no Claude-specific syntax. Claude Code
discovers the folder automatically; every other agent needs the pointer block,
which takes about thirty seconds.

Do I need the 495 MB of images?

No. Every number, rule, and token lives in the markdown. The images are for reading measurement
diagrams and canonical screens, useful when a spec is ambiguous and optional otherwise. See
reference images.

Is M3 Expressive a new version of Material?

No. It's an evolution of Material 3, not "M4", and M3 isn't deprecated. It adds components, updated
tokens, and design tactics. SKILL.md opens with this because getting it wrong colors every
downstream decision.

Does it cover Compose, Flutter, and web equally?

It covers the design system for all of them, and is explicit that platform availability is uneven.
references/platforms.md maps what's actually shipped where. Compose M3 Expressive APIs are
experimental until Compose 1.5.0; MDC-Android and Material Web are in maintenance mode.

Will it override my own design system?

No. It supplies M3 values when you ask for M3. When you're working against your own tokens, it's the
component behavior, sibling-choice rules, and do/don'ts that carry over.

Contributing

Corrections to values, gaps worth filling, and install recipes for agents not covered here are all
welcome. Open an issue or a PR. If you're correcting a number, cite where the real one lives so it can
be verified.

License

MIT for this repository's original work: the refresh scripts, the skill structure, and the
authored organization of the references. See LICENSE.

Everything else keeps its own license, and NOTICE.md records which is which:

• Material Design guidelines (the design guidance in references/) are © Google LLC, used under
  CC BY 4.0 with attribution
• AndroidX token values (component-tokens.md) are Apache License 2.0, © The Android Open Source
  Project; values extracted and reformatted, none altered
• Reference images (the release zip) are © Google LLC, unmodified, and optional. They are not in
  the repo tree; download them only if you want them.

Material Design, Material You, Android, and Jetpack Compose are trademarks of Google LLC. This
project is not affiliated with, sponsored by, or endorsed by Google.