material-design-3-ui
Design, redesign, review, or implement user interfaces using Google Material Design 3 (M3), Material You, and optional Material 3 Expressive principles. Use for UI/UX screens, app flows, design systems, component selection, theming, responsive/adaptive layouts, accessibility audits, Figma-ready specifications, or developer handoff where Material Design 3 is required.
- License 许可
- MIT
- 最近更新
- 2026-10-31
- Stars
- ★ 0
- Forks
- 1
01 前言 Front Matter
- name
- material-design-3-ui
- metadata
- { "updated": 1790812800000, "version": "1.1.1" }
- description
- Design, redesign, review, or implement user interfaces using Google Material Design 3 (M3), Material You, and optional Material 3 Expressive principles. Use for UI/UX screens, app flows, design systems, component selection, theming, responsive/adaptive layouts, accessibility audits, Figma-ready specifications, or developer handoff where Material Design 3 is required.
02 资源文件 30
- 参考文档CHANGELOG.md2.0 KB
- 参考文档CONTRIBUTING.md4.7 KB
- 脚本install.ps19.4 KB
- 脚本install.sh8.7 KB
- 许可证LICENSE1.1 KB
- 参考文档README.md22.3 KB
- 参考文档references/accessibility.md2.1 KB
- 参考文档references/adaptive-design.md1.9 KB
- 参考文档references/anti-patterns.md2.2 KB
- 参考文档references/color-system.md2.8 KB
- 参考文档references/component-selection.md4.4 KB
- 参考文档references/feedback-and-overlays.md1.8 KB
- 参考文档references/forms-and-input.md2.1 KB
- 参考文档references/m3-expressive.md1.7 KB
- 参考文档references/motion.md1.3 KB
- 参考文档references/navigation.md1.9 KB
- 参考文档references/shape-and-elevation.md1.8 KB
- 参考文档references/spacing-and-layout.md1.5 KB
- 参考文档references/typography.md2.0 KB
- 参考文档skill-files.txt388 B
- 参考文档tests/cases/01-settings-screen.md875 B
- 参考文档tests/cases/02-dashboard.md813 B
- 参考文档tests/cases/03-navigation.md801 B
- 参考文档tests/cases/04-form-validation.md720 B
- 参考文档tests/cases/05-m3-expressive.md818 B
- 参考文档tests/cases/06-audit-fake-material.md695 B
- 参考文档tests/README.md1.1 KB
- 脚本tests/validate_skill.py3.7 KB
- 脚本uninstall.ps1877 B
- 脚本uninstall.sh679 B
03 SKILL.md 正文
Material Design 3 UI/UX
Purpose
Create interfaces that behave like Material Design 3, not interfaces that merely look rounded or “Google-like.”
Treat M3 as a system:
user goal → information architecture → hierarchy → adaptive layout → semantic tokens → components → states → interaction → motion → accessibility → visual expression
M3 Expressive is optional. Use it to strengthen hierarchy, usability, recognition, and emotional clarity; never use it as permission to make every element loud.
Source of truth
- Prefer current official Material 3 guidance at
https://m3.material.io/. - For Android implementation details, prefer
https://developer.android.com/. - Treat design guidance separately from implementation-library/API status.
- Verify current official guidance before asserting exact dimensions, dependency versions, experimental API names, or recently changed behavior.
- Do not silently mix Material 2 rules into Material 3.
- Pixel and Google-app screenshots are examples, not the specification.
Core rules
MUST
- Start from the user’s task, content, hierarchy, and platform before styling.
- Use semantic design tokens instead of scattered one-off values.
- Choose components by purpose and behavior, not visual resemblance.
- Prefer established M3/platform components when they solve the interaction.
- Define important states: default, pressed, focus, hover where applicable, selected, disabled, loading, error, empty, and success where relevant.
- Design for the available window rather than a guessed device category.
- Preserve accessible contrast, target size, focus, semantics, scaling, and non-color state communication.
- Respect system bars, safe areas, cutouts, keyboards/IME, foldable hinges, and edge-to-edge behavior where applicable.
- Keep primary actions distinguishable from secondary and destructive actions.
- Make custom components inherit the token, state, motion, and accessibility logic of the system.
- Explain deliberate departures from M3 when product requirements justify them.
MUST NOT
- Do not “Materialize” a screen by only adding large radii, pastel colors, shadows, or Material Symbols.
- Do not hardcode raw colors throughout screens when semantic roles can be used.
- Do not use color alone to communicate meaning or state.
- Do not wrap every section or list row in a card.
- Do not maximize corner radius on every component.
- Do not use FABs for minor, destructive, or ambiguous actions.
- Do not use chips as generic buttons or primary navigation.
- Do not use tabs for unrelated top-level destinations.
- Do not make all components equally expressive.
- Do not invent a new control when an established M3/platform control already solves the interaction.
- Do not sacrifice accessibility to preserve a visual composition.
- Do not stretch a compact/mobile layout unchanged across wide windows.
Progressive-disclosure references
Load only the references needed for the current task. Do not read every reference by default.
| Need | Read |
|---|---|
| Color roles, surfaces, dark theme, dynamic color | references/color-system.md |
| Type hierarchy, scaling, expressive typography | references/typography.md |
| Shape, cards, containment, elevation | references/shape-and-elevation.md |
| Spacing, alignment, readable widths, safe areas | references/spacing-and-layout.md |
| Buttons, FAB, cards, chips, selection, inputs, feedback | references/component-selection.md |
| Navigation bar/rail/drawer, tabs, app bars | references/navigation.md |
| Forms, validation, settings, text input | references/forms-and-input.md |
| Snackbar, dialog, sheet, loading, empty/error states | references/feedback-and-overlays.md |
| Responsive, tablet, foldable, desktop, multi-pane | references/adaptive-design.md |
| Accessibility audit or any final UI review | references/accessibility.md |
| Transitions, feedback animation, shape morphing | references/motion.md |
| Material 3 Expressive | references/m3-expressive.md |
| Final audit / suspicious “Material-looking” UI | references/anti-patterns.md |
For a broad end-to-end design, load the references incrementally as decisions require them. Always include the accessibility reference before final approval.
Workflow
Follow this order unless the task explicitly scopes one stage.
1. Understand the product
Identify the platform, primary user goal and action, top-level destinations, content hierarchy, data density, input methods, brand constraints, required states and edge cases, target window sizes, and whether M3 Expressive is appropriate.
If missing information does not block the work, make a conservative M3-aligned assumption and state it. Ask only when the missing information materially changes architecture or interaction.
2. Establish information architecture
Before styling:
- Group related information and identify the primary task per screen.
- Separate navigation from actions and distinguish destructive actions.
- Remove duplicated controls and define progressive disclosure.
- Avoid showing information merely because space is available.
3. Choose adaptive structure
Read references/adaptive-design.md and references/navigation.md when multiple window sizes or navigation forms matter.
Prefer canonical patterns such as list-detail, supporting pane, feed, and adaptive navigation when they fit the content.
Wider space must improve context or productivity rather than merely stretch content.
4. Build the theme semantically
Read the relevant color, typography, shape/elevation, and spacing references.
Use the hierarchy:
reference/system tokens → semantic/system roles → component tokens
Screens should depend on semantic roles rather than scattered literal values.
5. Select components
Read references/component-selection.md plus specialized navigation/form/feedback references as needed.
For each important control, determine its semantic purpose, emphasis, immediate or transactional behavior, interaction states, accessibility behavior, and adaptive behavior.
6. Define states and feedback
Cover relevant loading, empty, error, success, disabled, selected, pressed, focus, hover, and busy/submitting states.
Error states must provide a recovery path.
7. Apply accessibility
Read references/accessibility.md.
Accessibility is a release requirement. Do not defer it to visual polish.
8. Add motion
Read references/motion.md only when motion is part of the task.
Motion must explain state, hierarchy, spatial relationship, or response. Do not animate for spectacle.
9. Apply M3 Expressive if appropriate
Read references/m3-expressive.md.
Use a few deliberate expressive moments. Routine reading, forms, settings, and dense productivity surfaces should remain calm unless stronger expression improves usability.
10. Audit before approval
Read references/anti-patterns.md and run the self-audit below.
Self-audit
Before delivering a design, score each applicable category 0, 1, or 2.
0= incorrect / missing1= partially correct / needs refinement2= ready
| Category | Check |
|---|---|
| Task clarity | Primary user goal and action are obvious |
| Information hierarchy | Grouping and emphasis are coherent |
| Component semantics | Controls match their actual behavior |
| Token discipline | Semantic roles are used consistently |
| Adaptive behavior | Layout improves across relevant windows |
| States & feedback | Important states and recovery are covered |
| Accessibility | Targets, contrast, semantics, focus, scaling, reduced motion |
| Expressive restraint | Expression improves hierarchy without creating noise |
A design with any 0 in component semantics, states & feedback, or accessibility is not ready for approval.
Do not inflate scores to satisfy the user. State the concrete issue and correction.
Handoff contract
When asked to design, redesign, audit, or hand off a UI, provide enough detail for another designer or developer to reproduce the decisions.
Unless the user requests another format, include as applicable:
- Design intent — user goal and hierarchy.
- Layout — regions, panes, navigation, adaptive behavior.
- Theme roles — semantic colors, typography, shape, elevation.
- Component map — exact M3 component type/variant for important controls.
- States — interaction, loading, empty, error, success, disabled.
- Accessibility — target size, contrast, names, focus, keyboard, scaling.
- Motion — only meaningful transitions/state changes.
- Implementation notes — platform-specific caveats and experimental/unsupported APIs.
- Self-audit — include when the user asks for a review, audit, or production-readiness check.
When creating actual code or an artifact, apply these decisions instead of stopping at a description.
Semantic handoff example
Prefer:
Screen background: surface
Primary text: onSurface
Secondary text: onSurfaceVariant
Primary CTA: filled button / primary + onPrimary
Secondary CTA: outlined button
Section container: surfaceContainer
Subtle separator: outlineVariant
Error container: errorContainer + onErrorContainer
Avoid handoff based on arbitrary literals unless they come from the project’s token system.
Platform implementation notes
Android / Jetpack Compose
- Prefer
androidx.compose.material3for new M3 work. - Prefer stable APIs for production unless alpha/experimental dependencies are explicitly accepted.
- Do not assume every M3 Expressive API is stable.
- Use Material theme roles rather than raw colors.
- Follow current Android adaptive guidance for resizable and large-window experiences.
- Treat edge-to-edge and system insets as layout concerns.
- For Wear OS, use Wear Material 3 rather than mixing mobile components.
Do not hardcode library version numbers into generated implementation unless they are verified against current official release notes.
Web / other platforms
Material 3 guidance can inform the design even when an official implementation library does not expose every component.
- reproduce semantics and token relationships, not Android-specific quirks,
- preserve native platform accessibility and input conventions,
- mark custom implementations clearly,
- do not claim official platform availability without verification.
Final principle
Material Design 3 is a semantic, adaptive, accessible design system.
A successful M3 interface should remain coherent when brand colors change, the window resizes, dark theme turns on, text scales up, keyboard replaces touch, or expressive styling is reduced.
If the design only works because every surface is rounded and colorful, it is not a robust Material 3 design.
04 同仓库更多 Skills
security-review
Security code review for vulnerabilities. Use when asked to "security review", "find vulnerabilities", "check for security issues", "audit security", "OWASP review", or review code for injection, XSS, authentication, authorization, cryptography issues. Provides systematic review with confidence-based reporting.
security-model
Define, review, or update SECURITY_MODEL.md files that tell security review tools a repository's threat model, trust boundaries, invariants, reportable finding classes, and exclusions. Use when asked to "write a security model", "threat model this repo for scanners", "define security review scope", "what counts as a vulnerability here", "update SECURITY_MODEL.md", "why did the scanner flag or miss this", or to check whether existing security guidance still matches the code. Not for running a security review or editing the SECURITY.md disclosure policy.
mobile-harness
Portable Android and iOS device-control harness for agents. Use when an agent needs to control or automate Android/iOS devices — tap, swipe, screenshot, app control — locally (ADB/Portal/Simulator) or on Mobilerun cloud devices.
compose-agent
Helps AI coding assistants write modern Jetpack Compose: correct state, side effects, performance-aware modifiers, Navigation 3, Paging 3 in Compose, coroutines on lifecycle, animations, UI tests, focus/keyboard navigation, Compose Multiplatform boundaries, idiomatic Kotlin, and well-shaped composable APIs. Targets the mistakes LLMs actually make in Compose code. Use when reading, writing, or reviewing Compose projects.
web-design-guidelines
Web platform design and accessibility guidelines. Use when building web interfaces, auditing accessibility, implementing responsive layouts, or reviewing web UI code. Triggers on tasks involving HTML, CSS, web components, WCAG compliance, responsive design, or web performance.
watchos-design-guidelines
Apple Human Interface Guidelines for Apple Watch. Use when building watchOS apps, complications, or workout features. Triggers on tasks involving Watch UI, Digital Crown, glanceable interfaces, or wrist-based interactions.