abhixv/m3-expressive-design-skill

**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.
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.
| You ask | Unassisted | With this skill |
|---|---|---|
| "Standard scheme default spatial spring?" | damping 0.8, stiffness 380 (those are the *expressive* values) | **damping 0.9, stiffness 700** |
| "What does elevation level 3 resolve to?" | 12dp | **6dp** |
| "Radius for a child inside a 48dp card with 16dp padding?" | "48dp, keep it consistent" | **32dp**, since inner = outer − padding |
| "Gap between the two action buttons?" | a number, stated as spec | *"My design decision (not in M3): 12dp"* |
| "Fade the color with a bouncy spring?" | sure | color and opacity take **effects** springs: damping 1.0, no overshoot |
| "Ship this expressive treatment on web" | sure | availability is uneven, so it checks platforms.md first |
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:
| Model | Without the skill | With the skill |
|---|---|---|
| Claude Sonnet | 11/14, and 2 of the 3 misses were confidently wrong numbers | **14/14** |
| Claude Haiku | 10/14, all 4 misses answered "unknown" | **14/14** |
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
| Path | Contents |
|---|---|
| SKILL.md | Entry point: source contract, quick-reference decision table, the 7 expressive tactics, router, common-mistakes table |
| references/tokens.md | The numeric bedrock: 30 type styles, the 10-step corner scale, spring damping/stiffness for both schemes, web curve conversions, elevation, contrast levels |
| references/component-tokens.md | **916 per-component values** across 104 component groups: container heights and widths, icon sizes, internal spacing, shape and elevation assignments |
| references/components/*.md | 7 files, 40+ components. The sibling-choice rule ("use this instead of that when..."), anatomy, every size variant, placement, states, color and type role mapping, do/don'ts |
| references/motion.md, shape.md, typography.md, color.md, color-schemes.md, transitions.md | The style systems in depth: motion schemes, 35 shapes and morphing, baseline vs emphasized type, role pairing, dynamic color, transition patterns |
| references/layout.md, interaction.md, foundations.md, platforms.md | Breakpoints and canonical layouts. States, gestures, accessibility. Elevation, spacing, icons. Per-platform API availability |