A production-minded Agent Skill for designing, implementing, and reviewing
interfaces with Material 3 Expressive.
Click the cover to watch the video on YouTube.
Install · Capabilities · Read the skill · Documentation
Express with intent. This skill helps an AI agent make deliberate product, interaction, accessibility, and engineering decisions — using expressive design where it improves hierarchy, recognition, feedback, or emotional clarity, not just to make screens louder or rounder.
- Design new screens and end-to-end app flows using Material 3 semantics.
- Apply M3 Expressive intentionally: size, color, shape, motion, typography, containment, and flexible component composition.
- Build and refine semantic themes for light, dark, and dynamic color.
- Select appropriate Material components and states for the target platform.
- Plan adaptive experiences for phones, tablets, foldables, desktop windows, and wearable surfaces.
- Implement, modernize, and review interfaces without inventing unsupported APIs.
- Deliver accessible, internationalized, production-ready UI and developer handoff notes.
- Start with the user task. Information architecture, content hierarchy, and interaction come before decoration.
- Preserve Material semantics. A button must remain recognizable as a button; selected, disabled, destructive, and navigational states must remain clear.
- Express with intent. Choose only the expressive treatments that make the important information or action easier to understand.
- Respect platform capability. Native expressive components and APIs vary by platform and library. Use supported components where available; adapt principles honestly elsewhere.
- Ship complete states. Loading, empty, error, success, disabled, focus, hover, and pressed states are part of the design.
- Treat accessibility as a release requirement. Include keyboard, screen-reader, contrast, text scaling, reduced motion, and localization checks.
The recommended route is the Skills CLI:
npx skills add asimawdah/material-expressive-skillChoose the agent and installation scope supported by the CLI. The repository follows the open Agent Skills directory format and has no runtime dependencies.
Clone or copy the repository into the skill directory used by your agent. For example:
# OpenAI Codex
git clone https://github.com/asimawdah/material-expressive-skill.git \
~/.codex/skills/material-expressive-skill
# Claude Code
git clone https://github.com/asimawdah/material-expressive-skill.git \
~/.claude/skills/material-expressive-skillFor other clients, use their current documented Agent Skills directory. Restart or refresh the client if it does not discover the new skill automatically.
After installation, ask naturally:
- "Design an expressive Material 3 dashboard for a personal finance app."
- "Implement this screen in Jetpack Compose using Material 3 Expressive."
- "Review this Flutter screen for Material 3 consistency and accessibility."
- "Adapt this mobile flow for tablet and desktop windows."
- "Audit this interface and suggest only the expressive changes that improve its hierarchy."
The skill is triggered by requests involving Material Design 3, M3 Expressive, Material You, expressive Material interfaces, relevant implementation work, or Material-focused design reviews.
material-expressive-skill/
├── SKILL.md
├── README.md
├── CHANGELOG.md
├── CONTRIBUTING.md
├── LICENSE
├── assets/
│ ├── expressive_icon.svg
│ └── Introducing-Material-3-Expressive.jpg
├── references/
│ ├── expressive-principles.md
│ ├── design-foundations.md
│ ├── components-and-patterns.md
│ ├── motion-and-feedback.md
│ ├── adaptive-layouts.md
│ ├── accessibility-and-internationalization.md
│ ├── platform-guidance.md
│ ├── implementation-workflow.md
│ ├── review-checklist.md
│ └── official-sources.md
├── examples/
│ └── expressive-task-list.md
├── templates/
│ ├── design-brief.md
│ └── implementation-handoff.md
├── scripts/
│ └── validate_skill.py
├── tests/
│ └── test_validate_skill.py
└── .github/
└── workflows/
└── validate.yml
The root SKILL.md is the decision engine. Focused references are loaded only when a task needs them, keeping the default context small and easier to maintain.
| Target | Guidance |
|---|---|
| Android / Jetpack Compose | Primary native implementation path; verify current Compose Material 3 APIs and release channel. |
| Wear OS | Use Wear Compose Material 3 and wearable-specific patterns. |
| Android Views | Use available Material Components and platform conventions; do not assume Compose-only APIs exist. |
| Flutter | Apply Material 3 roles and patterns with the Flutter SDK's actual widget and theme support. |
| Web | Apply semantic tokens, responsive structure, and accessible interaction; do not claim native Compose expressive parity. |
| React Native / SwiftUI / other | Adapt the design principles to the target platform's native conventions and available component ecosystem. |
This is a design and implementation skill, not a replacement component library. It does not bundle third-party UI packages or claim that every M3 Expressive component is available everywhere.
Start with SKILL.md, then open the references relevant to the task:
- Expressive principles
- Design foundations and tokens
- Components and patterns
- Motion and feedback
- Adaptive layouts
- Accessibility and internationalization
- Platform guidance
- Implementation workflow
- Review checklist
- Official sources and version verification
See the expressive task-list walkthrough for a practical design decision example. Reusable planning documents are available in templates/.
Requires Python 3.10 or newer. No third-party packages are needed.
python scripts/validate_skill.py
python -m unittest discover -s tests -vGitHub Actions runs the same checks for pushes and pull requests.
Official Material guidance and platform API documentation are the source of truth. Before using a new component, token, dependency, or API, verify its current availability for the target platform and release channel. Record meaningful changes in CHANGELOG.md.
The references summarize guidance in original wording and link to authoritative sources. Material Design and related names are trademarks of Google; this project is independent and is not affiliated with or endorsed by Google.
Corrections, platform notes, examples, and improvements are welcome. Read CONTRIBUTING.md before opening a pull request.
MIT. See LICENSE.