Skip to content
Back to search

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.

Safety scan

A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.

Checked today
Badge for your README
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/skydashnet--material-design-3-ui-skill/badge.svg)](/listings/skydashnet--material-design-3-ui-skill)

HTML

<a href="/listings/skydashnet--material-design-3-ui-skill"><img src="/api/listings/skydashnet--material-design-3-ui-skill/badge.svg" alt="findsafeskills safety rating" /></a>

Install

i

Install instructions from the README

As written by the repo's author. findsafeskills has not verified these steps.

These steps run a script from the network that findsafeskills does not scan.

**macOS / Linux**

curl -fsSL https://raw.githubusercontent.com/skydashnet/material-design-3-ui-skill/main/install.sh | bash

**Windows PowerShell**

irm https://raw.githubusercontent.com/skydashnet/material-design-3-ui-skill/main/install.ps1 | iex

> The installer distributes the same portable skill package to the supported global agent locations. It does **not** install, authenticate, configure, or launch any AI agent.

------------------------------------------------------------------------

What was scanned

The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.

SKILL.md · Manifest · 241 lines

View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)

  1. ---
  2. 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.
  3. metadata:
  4. updated: 2026-10-01
  5. version: 1.1.1
  6. name: material-design-3-ui
  7. ---
  8. # Material Design 3 UI/UX
  9. ## Purpose
  10. Create interfaces that **behave like Material Design 3**, not interfaces that merely look rounded or “Google-like.”
  11. Treat M3 as a system:
  12. **user goal → information architecture → hierarchy → adaptive layout → semantic tokens → components → states → interaction → motion → accessibility → visual expression**
  13. M3 Expressive is optional. Use it to strengthen hierarchy, usability, recognition, and emotional clarity; never use it as permission to make every element loud.
  14. ## Source of truth
  15. 1. Prefer current official Material 3 guidance at `https://m3.material.io/`.
  16. 2. For Android implementation details, prefer `https://developer.android.com/`.
  17. 3. Treat design guidance separately from implementation-library/API status.
  18. 4. Verify current official guidance before asserting exact dimensions, dependency versions, experimental API names, or recently changed behavior.
  19. 5. Do not silently mix Material 2 rules into Material 3.
  20. 6. Pixel and Google-app screenshots are examples, not the specification.
  21. ## Core rules
  22. ### MUST
  23. - Start from the user’s task, content, hierarchy, and platform before styling.
  24. - Use semantic design tokens instead of scattered one-off values.
  25. - Choose components by purpose and behavior, not visual resemblance.
  26. - Prefer established M3/platform components when they solve the interaction.
  27. - Define important states: default, pressed, focus, hover where applicable, selected, disabled, loading, error, empty, and success where relevant.
  28. - Design for the available window rather than a guessed device category.
  29. - Preserve accessible contrast, target size, focus, semantics, scaling, and non-color state communication.
  30. - Respect system bars, safe areas, cutouts, keyboards/IME, foldable hinges, and edge-to-edge behavior where applicable.
  31. - Keep primary actions distinguishable from secondary and destructive actions.
  32. - Make custom components inherit the token, state, motion, and accessibility logic of the system.
  33. - Explain deliberate departures from M3 when product requirements justify them.
  34. ### MUST NOT
  35. - Do not “Materialize” a screen by only adding large radii, pastel colors, shadows, or Material Symbols.
  36. - Do not hardcode raw colors throughout screens when semantic roles can be used.
  37. - Do not use color alone to communicate meaning or state.
  38. - Do not wrap every section or list row in a card.
  39. - Do not maximize corner radius on every component.
  40. - Do not use FABs for minor, destructive, or ambiguous actions.
  41. - Do not use chips as generic buttons or primary navigation.
  42. - Do not use tabs for unrelated top-level destinations.
  43. - Do not make all components equally expressive.
  44. - Do not invent a new control when an established M3/platform control already solves the interaction.
  45. - Do not sacrifice accessibility to preserve a visual composition.
  46. - Do not stretch a compact/mobile layout unchanged across wide windows.
  47. ## Progressive-disclosure references
  48. Load only the references needed for the current task. Do not read every reference by default.
  49. | Need | Read |
  50. |---------------------------------------------------------|---------------------------------------|
  51. | Color roles, surfaces, dark theme, dynamic color | `references/color-system.md` |
  52. | Type hierarchy, scaling, expressive typography | `references/typography.md` |
  53. | Shape, cards, containment, elevation | `references/shape-and-elevation.md` |
  54. | Spacing, alignment, readable widths, safe areas | `references/spacing-and-layout.md` |
  55. | Buttons, FAB, cards, chips, selection, inputs, feedback | `references/component-selection.md` |
  56. | Navigation bar/rail/drawer, tabs, app bars | `references/navigation.md` |
  57. | Forms, validation, settings, text input | `references/forms-and-input.md` |
  58. | Snackbar, dialog, sheet, loading, empty/error states | `references/feedback-and-overlays.md` |
  59. | Responsive, tablet, foldable, desktop, multi-pane | `references/adaptive-design.md` |
  60. | Accessibility audit or any final UI review | `references/accessibility.md` |
  61. | Transitions, feedback animation, shape morphing | `references/motion.md` |
  62. | Material 3 Expressive | `references/m3-expressive.md` |
  63. | Final audit / suspicious “Material-looking” UI | `references/anti-patterns.md` |
  64. For a broad end-to-end design, load the references incrementally as decisions require them. Always include the accessibility reference before final approval.
  65. ## Workflow
  66. Follow this order unless the task explicitly scopes one stage.
  67. ### 1. Understand the product
  68. 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.
  69. 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.
  70. ### 2. Establish information architecture
  71. Before styling:
  72. - Group related information and identify the primary task per screen.
  73. - Separate navigation from actions and distinguish destructive actions.
  74. - Remove duplicated controls and define progressive disclosure.
  75. - Avoid showing information merely because space is available.
  76. ### 3. Choose adaptive structure
  77. Read `references/adaptive-design.md` and `references/navigation.md` when multiple window sizes or navigation forms matter.
  78. Prefer canonical patterns such as list-detail, supporting pane, feed, and adaptive navigation when they fit the content.
  79. Wider space must improve context or productivity rather than merely stretch content.
  80. ### 4. Build the theme semantically
  81. Read the relevant color, typography, shape/elevation, and spacing references.
  82. Use the hierarchy:
  83. **reference/system tokens → semantic/system roles → component tokens**
  84. Screens should depend on semantic roles rather than scattered literal values.
  85. ### 5. Select components
  86. Read `references/component-selection.md` plus specialized navigation/form/feedback references as needed.
  87. For each important control, determine its semantic purpose, emphasis, immediate or transactional behavior, interaction states, accessibility behavior, and adaptive behavior.
  88. ### 6. Define states and feedback
  89. Cover relevant loading, empty, error, success, disabled, selected, pressed, focus, hover, and busy/submitting states.
  90. Error states must provide a recovery path.
  91. ### 7. Apply accessibility
  92. Read `references/accessibility.md`.
  93. Accessibility is a release requirement. Do not defer it to visual polish.
  94. ### 8. Add motion
  95. Read `references/motion.md` only when motion is part of the task.
  96. Motion must explain state, hierarchy, spatial relationship, or response. Do not animate for spectacle.
  97. ### 9. Apply M3 Expressive if appropriate
  98. Read `references/m3-expressive.md`.
  99. Use a few deliberate expressive moments. Routine reading, forms, settings, and dense productivity surfaces should remain calm unless stronger expression improves usability.
  100. ### 10. Audit before approval
  101. Read `references/anti-patterns.md` and run the self-audit below.
  102. ## Self-audit
  103. Before delivering a design, score each applicable category `0`, `1`, or `2`.
  104. - `0` = incorrect / missing
  105. - `1` = partially correct / needs refinement
  106. - `2` = ready
  107. | Category | Check |
  108. |-----------------------|--------------------------------------------------------------|
  109. | Task clarity | Primary user goal and action are obvious |
  110. | Information hierarchy | Grouping and emphasis are coherent |
  111. | Component semantics | Controls match their actual behavior |
  112. | Token discipline | Semantic roles are used consistently |
  113. | Adaptive behavior | Layout improves across relevant windows |
  114. | States & feedback | Important states and recovery are covered |
  115. | Accessibility | Targets, contrast, semantics, focus, scaling, reduced motion |
  116. | Expressive restraint | Expression improves hierarchy without creating noise |
  117. A design with any `0` in **component semantics**, **states & feedback**, or **accessibility** is not ready for approval.
  118. Do not inflate scores to satisfy the user. State the concrete issue and correction.
  119. ## Handoff contract
  120. When asked to design, redesign, audit, or hand off a UI, provide enough detail for another designer or developer to reproduce the decisions.
  121. Unless the user requests another format, include as applicable:
  122. 1. **Design intent** — user goal and hierarchy.
  123. 2. **Layout** — regions, panes, navigation, adaptive behavior.
  124. 3. **Theme roles** — semantic colors, typography, shape, elevation.
  125. 4. **Component map** — exact M3 component type/variant for important controls.
  126. 5. **States** — interaction, loading, empty, error, success, disabled.
  127. 6. **Accessibility** — target size, contrast, names, focus, keyboard, scaling.
  128. 7. **Motion** — only meaningful transitions/state changes.
  129. 8. **Implementation notes** — platform-specific caveats and experimental/unsupported APIs.
  130. 9. **Self-audit** — include when the user asks for a review, audit, or production-readiness check.
  131. When creating actual code or an artifact, apply these decisions instead of stopping at a description.
  132. ## Semantic handoff example
  133. Prefer:
  134. ``` text
  135. Screen background: surface
  136. Primary text: onSurface
  137. Secondary text: onSurfaceVariant
  138. Primary CTA: filled button / primary + onPrimary
  139. Secondary CTA: outlined button
  140. Section container: surfaceContainer
  141. Subtle separator: outlineVariant
  142. Error container: errorContainer + onErrorContainer
  143. ```
  144. Avoid handoff based on arbitrary literals unless they come from the project’s token system.
  145. ## Platform implementation notes
  146. ### Android / Jetpack Compose
  147. - Prefer `androidx.compose.material3` for new M3 work.
  148. - Prefer stable APIs for production unless alpha/experimental dependencies are explicitly accepted.
  149. - Do not assume every M3 Expressive API is stable.
  150. - Use Material theme roles rather than raw colors.
  151. - Follow current Android adaptive guidance for resizable and large-window experiences.
  152. - Treat edge-to-edge and system insets as layout concerns.
  153. - For Wear OS, use Wear Material 3 rather than mixing mobile components.
  154. Do not hardcode library version numbers into generated implementation unless they are verified against current official release notes.
  155. ### Web / other platforms
  156. Material 3 guidance can inform the design even when an official implementation library does not expose every component.
  157. - reproduce semantics and token relationships, not Android-specific quirks,
  158. - preserve native platform accessibility and input conventions,
  159. - mark custom implementations clearly,
  160. - do not claim official platform availability without verification.
  161. ## Final principle
  162. **Material Design 3 is a semantic, adaptive, accessible design system.**
  163. 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.
  164. If the design only works because every surface is rounded and colorful, it is not a robust Material 3 design.
README.md · README · 611 lines · 2 findings marked

View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)

  1. <div align="center">
  2. # Material Design 3 UI/UX Skill
  3. ### Design the system. Not just the screenshot.
  4. A reusable **Agent Skill** that helps AI design and coding agents create, review, and implement interfaces using **Material Design 3**, **Material You**, and optional **Material 3 Expressive** principles.
  5. [![Material Design 3](https://img.shields.io/badge/Material_Design-3-6750A4?style=flat-square&logo=materialdesign&logoColor=white)](https://m3.material.io/) [![Skill Version](https://img.shields.io/badge/skill-v1.1.1-1f6feb?style=flat-square)](CHANGELOG.md) [![Supported Agents](https://img.shields.io/badge/agents-7-0f9d58?style=flat-square)](#supported-agents) [![GitHub stars](https://img.shields.io/github/stars/skydashnet/material-design-3-ui-skill?style=flat-square&logo=github&label=stars)](https://github.com/skydashnet/material-design-3-ui-skill/stargazers) [![GitHub forks](https://img.shields.io/github/forks/skydashnet/material-design-3-ui-skill?style=flat-square&logo=github&label=forks)](https://github.com/skydashnet/material-design-3-ui-skill/forks) [![License](https://img.shields.io/github/license/skydashnet/material-design-3-ui-skill?style=flat-square&label=license)](LICENSE)
  6. **Claude Code · OpenAI Codex · Google Antigravity · Kiro · OpenCode · Hermes Agent · OpenClaw**
  7. </div>
  8. ------------------------------------------------------------------------
  9. ## Quick install
  10. **macOS / Linux**
  11. ``` bash
  12. curl -fsSL https://raw.githubusercontent.com/skydashnet/material-design-3-ui-skill/main/install.sh | bash
    • Note: Pipes a downloaded script directly into a shell (curl | sh / wget | bash)
    • Line 22 on GitHub
  13. ```
  14. **Windows PowerShell**
  15. ``` powershell
  16. irm https://raw.githubusercontent.com/skydashnet/material-design-3-ui-skill/main/install.ps1 | iex
  17. ```
  18. > The installer distributes the same portable skill package to the supported global agent locations. It does **not** install, authenticate, configure, or launch any AI agent.
  19. ------------------------------------------------------------------------
  20. ## What this skill changes
  21. | Without a design skill | With `material-design-3-ui` |
  22. |------------------------------------|-----------------------------------------------------|
  23. | “Make it look Material” | Start from user goal, hierarchy, and semantics |
  24. | Rounded cards everywhere | Use containment only when it has a purpose |
  25. | Components chosen by appearance | Components chosen by behavior |
  26. | Random hex values | Semantic Material color roles and tokens |
  27. | Mobile UI stretched to desktop | Adaptive structure for the available window |
  28. | Accessibility checked at the end | Accessibility treated as a release requirement |
  29. | “Expressive” means more decoration | Expression used selectively to strengthen hierarchy |
  30. This is not a collection of pretty defaults. It is a **decision system for AI agents**.
  31. ------------------------------------------------------------------------
  32. ## Highlights
  33. - **Progressive disclosure** — a compact `SKILL.md` routes agents to 13 focused references only when needed.
  34. - **Semantic component rules** — buttons, FABs, chips, navigation, forms, feedback, surfaces, and more are selected by purpose.
  35. - **Adaptive by design** — compact through extra-large windows, multi-pane layouts, foldables, resizable windows, and edge-to-edge behavior.
  36. - **Accessibility-first** — contrast, touch targets, focus, keyboard, semantics, text scaling, localization, and reduced motion.
  37. - **M3 Expressive with restraint** — color, shape, size, motion, containment, and typography are used intentionally.
  38. - **Cross-agent distribution** — one package for 7 supported AI agents on Windows, macOS, and Linux.
  39. - **Regression checks** — static validation plus behavioral evaluation cases help prevent rule regressions.
  40. > **Core idea:** Material Design 3 is a semantic, adaptive, accessible design system—not a rounded-card aesthetic.
  41. ------------------------------------------------------------------------
  42. ## Explore
  43. [**Why it exists**](#why-this-exists) · [**Coverage**](#what-the-skill-covers) · [**Architecture**](#repository-structure) · [**Install options**](#installation) · [**Examples**](#example-tasks) · [**Tests**](#testing-and-regression-checks) · [**Contributing**](#contributing)
  44. ------------------------------------------------------------------------
  45. ## Why this exists
  46. Material Design 3 is easy to imitate visually and surprisingly easy to apply incorrectly.
  47. A UI can look “Material” while still using the wrong component semantics, weak hierarchy, arbitrary colors, inaccessible controls, broken responsive behavior, excessive cards, or decorative motion that does not communicate anything.
  48. This skill is designed to prevent that.
  49. Instead of telling an agent to simply *“make this look like Material Design 3,”* give it a reusable system that defines **how M3 decisions should actually be made**.
  50. ``` text
  51. User goal
  52. ↓
  53. Information architecture
  54. ↓
  55. Hierarchy
  56. ↓
  57. Adaptive layout
  58. ↓
  59. Semantic tokens
  60. ↓
  61. Components
  62. ↓
  63. States & interaction
  64. ↓
  65. Motion
  66. ↓
  67. Accessibility
  68. ↓
  69. Visual expression
  70. ```
  71. ------------------------------------------------------------------------
  72. ## What the skill covers
  73. ### Material 3 foundations
  74. - Semantic color roles and surface hierarchy
  75. - Material typography roles
  76. - Shape systems and reusable shape tokens
  77. - Elevation and tonal surface relationships
  78. - Spacing and alignment
  79. - Design tokens
  80. - Light and dark theme behavior
  81. - Dynamic color considerations
  82. ### Component selection
  83. The skill teaches agents to choose components by **purpose and behavior**, not by appearance.
  84. Coverage includes:
  85. - Filled, tonal, elevated, outlined, and text buttons
  86. - Icon buttons
  87. - FAB and Extended FAB
  88. - Split buttons and button groups
  89. - Cards
  90. - Lists
  91. - Dividers
  92. - Badges
  93. - Carousels
  94. - Chips
  95. - Checkboxes
  96. - Radio buttons
  97. - Switches
  98. - Segmented buttons
  99. - Navigation bars
  100. - Navigation rails
  101. - Navigation drawers
  102. - Top and bottom app bars
  103. - Tabs
  104. - Text fields
  105. - Search
  106. - Menus
  107. - Sliders
  108. - Date and time pickers
  109. - Dialogs
  110. - Bottom sheets
  111. - Snackbars
  112. - Tooltips
  113. - Progress and loading indicators
  114. ### Adaptive UI
  115. The skill treats responsiveness as a structural design problem rather than simply scaling a mobile screen.
  116. It covers:
  117. | Width class | Available width |
  118. |-------------|----------------:|
  119. | Compact | `< 600dp` |
  120. | Medium | `600–839dp` |
  121. | Expanded | `840–1199dp` |
  122. | Large | `1200–1599dp` |
  123. | Extra large | `≥ 1600dp` |
  124. It also guides agents through list-detail layouts, supporting panes, feeds, adaptive navigation, resizable windows, tablets, foldables, desktop-sized layouts, safe areas, and edge-to-edge interfaces.
  125. ### Accessibility
  126. Accessibility is treated as a release requirement.
  127. The rules include:
  128. - `48dp × 48dp` minimum Android-oriented touch targets
  129. - Text and UI contrast requirements
  130. - Visible and logical focus
  131. - Keyboard support
  132. - Accessible names for icon-only controls
  133. - Screen-reader semantics
  134. - Text scaling
  135. - Localization resilience
  136. - Reduced-motion support
  137. - Error recovery
  138. - Non-color state communication
  139. ### Material 3 Expressive
  140. M3 Expressive is supported as an **optional layer**, not a license to make every screen visually loud.
  141. The skill guides agents in the intentional use of:
  142. - Color
  143. - Shape
  144. - Size
  145. - Motion
  146. - Containment
  147. - Typography
  148. - Shape morphing
  149. - Expressive hierarchy
  150. - Emphasized actions
  151. - Selective visual moments
  152. The core rule is simple:
  153. > **Expression must improve hierarchy, usability, recognition, or emotional clarity.**
  154. ------------------------------------------------------------------------
  155. ## The anti-“fake Material” rules
  156. This skill explicitly rejects common shortcuts that produce interfaces which only *look* vaguely Material.
  157. ``` text
  158. DON'T:
  159. ✗ Put every section inside a rounded card
  160. ✗ Turn every control into a pill
  161. ✗ Use the primary color everywhere
  162. ✗ Add shadows to every container
  163. ✗ Use chips as generic buttons
  164. ✗ Use tabs as unrelated top-level navigation
  165. ✗ Add multiple competing FABs
  166. ✗ Treat gradients as a shortcut to “Material”
  167. ✗ Stretch a phone layout across desktop widths
  168. ✗ Animate elements purely for spectacle
  169. ✗ Ignore focus, keyboard, text scaling, or reduced motion
  170. DO:
  171. ✓ Start from the user's task
  172. ✓ Establish information hierarchy first
  173. ✓ Use semantic design tokens
  174. ✓ Select components by behavior
  175. ✓ Design all important states
  176. ✓ Adapt structure to available window size
  177. ✓ Preserve accessibility
  178. ✓ Use expression selectively
  179. ```
  180. ------------------------------------------------------------------------
  181. ## Repository structure
  182. ``` text
  183. .
  184. ├── SKILL.md
  185. ├── skill-files.txt
  186. ├── references/
  187. │ ├── accessibility.md
  188. │ ├── adaptive-design.md
  189. │ ├── anti-patterns.md
  190. │ ├── color-system.md
  191. │ ├── component-selection.md
  192. │ ├── feedback-and-overlays.md
  193. │ ├── forms-and-input.md
  194. │ ├── m3-expressive.md
  195. │ ├── motion.md
  196. │ ├── navigation.md
  197. │ ├── shape-and-elevation.md
  198. │ ├── spacing-and-layout.md
  199. │ └── typography.md
  200. ├── tests/
  201. │ ├── cases/
  202. │ └── validate_skill.py
  203. ├── install.sh
  204. ├── install.ps1
  205. ├── uninstall.sh
  206. ├── uninstall.ps1
  207. ├── CHANGELOG.md
  208. ├── CONTRIBUTING.md
  209. ├── LICENSE
  210. └── .github/
  211. ```
  212. ### Progressive disclosure
  213. `SKILL.md` is intentionally the **decision engine**, not a giant Material 3 textbook.
  214. It routes the agent to focused files under `references/` only when a task needs them. A navigation task can load navigation guidance; a form can load form and accessibility guidance; M3 Expressive guidance is loaded only when expression is relevant.
  215. This reduces unnecessary context while keeping detailed rules available on demand.
  216. `skill-files.txt` defines the portable skill package. The cross-agent installers copy `SKILL.md` plus every referenced package file to the selected host.
  217. ## Installation
  218. The fastest install commands are shown at the top of this README. The options below cover selective installation, upgrades, symlinks, and uninstalling.
  219. By default, the universal installer places the skill in the global skill location for every supported host. This avoids false negatives when an IDE is installed without its CLI on `PATH`.
  220. The installer is filesystem-only. It does **not** install, configure, authenticate, or launch any AI agent.
  221. > **Security note:** Piping a remote script directly into a shell is convenient, but review the script first when that matters for your environment. The clone-and-run method below is easier to inspect and pin to a specific commit or release.
  222. ### Supported agents
  223. | Agent | Global installation used by this project |
  224. |--------------------|-------------------------------------------------------------------|
  225. | Claude Code | `~/.claude/skills/material-design-3-ui/` |
  226. | OpenAI Codex | `~/.agents/skills/material-design-3-ui/` |
  227. | Google Antigravity | `~/.gemini/config/skills/material-design-3-ui/` |
  228. | Kiro | `~/.kiro/skills/material-design-3-ui/` |
  229. | OpenCode | `~/.config/opencode/skills/material-design-3-ui/` |
  230. | Hermes Agent | `~/.hermes/skills/material-design-3-ui/` |
  231. | OpenClaw | `${OPENCLAW_STATE_DIR:-~/.openclaw}/skills/material-design-3-ui/` |
  232. Every destination receives the same portable skill package: `SKILL.md` plus its progressive-disclosure `references/` files.
  233. ### Clone and install
  234. ``` bash
  235. git clone https://github.com/skydashnet/material-design-3-ui-skill.git
  236. cd material-design-3-ui-skill
  237. ./install.sh
  238. ```
  239. Windows:
  240. ``` powershell
  241. git clone https://github.com/skydashnet/material-design-3-ui-skill.git
  242. cd material-design-3-ui-skill
  243. .\install.ps1
  244. ```
  245. ### Install only detected agents
  246. ``` bash
  247. ./install.sh --detect
  248. ```
  249. ``` powershell
  250. .\install.ps1 -Detect
  251. ```
  252. Detection checks the relevant CLI when available and the host’s existing configuration directory. Universal mode remains the default because it is more reliable for GUI-only installations.
  253. ### Install for selected agents
  254. ``` bash
  255. ./install.sh --agent claude --agent codex --agent antigravity
  256. ```
  257. ``` powershell
  258. .\install.ps1 -Agent claude,codex,antigravity
  259. ```
  260. Supported names: `claude`, `codex`, `antigravity`, `kiro`, `opencode`, `hermes`, `openclaw`.
  261. > **Upgrading from v1.0:** v1.1 installs a multi-file skill package instead of only `SKILL.md`. If an older installation already exists, run the installer with `--force` / `-Force` after reviewing any local edits.
  262. ### Updating an existing installation
  263. The installer never silently overwrites a different existing skill directory. Re-run with force after reviewing local changes.
  264. ``` bash
  265. ./install.sh --force
  266. ```
  267. ``` powershell
  268. .\install.ps1 -Force
  269. ```
  270. If an existing copied installation has identical package files, the installer reports it as up to date. Changes to any reference require `--force` / `-Force` to replace it. Switching from a symlink to a copy also requires force, even when the files match.
  271. ### Symlink mode for contributors
  272. When working from a clone, link each host directly to the repository instead of copying the skill:
  273. ``` bash
  274. ./install.sh --link
  275. ```
  276. ``` powershell
  277. .\install.ps1 -Link
  278. ```
  279. Windows symbolic links may require Developer Mode or appropriate privileges.
  280. ### Uninstall
  281. ``` bash
  282. ./uninstall.sh
  283. ```
  284. ``` powershell
  285. .\uninstall.ps1
  286. ```
  287. The uninstaller only removes the `material-design-3-ui` skill directories at the supported global destinations.
  288. ------------------------------------------------------------------------
  289. ## Example tasks
  290. Once the skill is loaded, requests can stay focused on the actual product:
  291. ``` text
  292. Redesign this dashboard using Material Design 3.
  293. Audit this mobile screen for incorrect M3 component usage.
  294. Create an adaptive M3 layout for compact, medium, and expanded widths.
  295. Convert this design system to semantic Material 3 color roles.
  296. Review this settings screen for accessibility and hierarchy problems.
  297. Use Material 3 Expressive, but keep the interface suitable for a productivity app.
  298. Create a developer handoff for this screen using semantic M3 tokens and exact component variants.
  299. ```
  300. The agent should then apply the rules from `SKILL.md` instead of relying on a vague visual interpretation of Material Design.
  301. ------------------------------------------------------------------------
  302. ## Testing and regression checks
  303. The repository includes both static validation and behavioral evaluation fixtures.
  304. Run the static validator:
  305. ``` bash
  306. python tests/validate_skill.py
  307. ```
  308. It checks the skill frontmatter, reference routing, package manifest, installer coverage, repository guardrails, and evaluation fixtures.
  309. `tests/cases/` contains behavioral scenarios for settings, dashboards, adaptive navigation, form validation, M3 Expressive restraint, and fake-Material audits. These cases are designed to catch regressions in **agent decisions**, not merely Markdown formatting.
  310. GitHub Actions runs the static validator and Bash syntax checks on pushes and pull requests.
  311. ------------------------------------------------------------------------
  312. ## Design philosophy
  313. ### Semantics before styling
  314. A component is selected because its behavior matches the task—not because it has the desired shape.
  315. ### Tokens before literals
  316. Prefer:
  317. ``` text
  318. surface
  319. onSurface
  320. primary
  321. onPrimary
  322. surfaceContainer
  323. outlineVariant
  324. errorContainer
  325. ```
  326. over scattered values such as:
  327. ``` text
  328. #FFFFFF
  329. #6750A4
  330. 23px radius
  331. 18px shadow blur
  332. ```
  333. Literal values can still exist inside a project’s token implementation, but screens should depend on **semantic roles**.
  334. ### Hierarchy before decoration
  335. Spacing, typography, containment, color, shape, and size should communicate importance before decorative effects are introduced.
  336. ### Adaptive, not stretched
  337. A wider window should improve context or productivity. It should not simply produce a wider phone screen.
  338. ### Accessible by default
  339. Contrast, focus, touch targets, semantics, text scaling, keyboard input, localization, and reduced motion are part of the design—not cleanup work after the design is finished.
  340. ### Expressive with restraint
  341. M3 Expressive works best when important moments receive stronger emphasis and routine content remains calm enough to scan.
  342. ------------------------------------------------------------------------
  343. ## Workflow encoded in `SKILL.md`
  344. ``` text
  345. 1. Understand the product and platform
  346. 2. Establish information architecture
  347. 3. Define the primary task and hierarchy
  348. 4. Choose the adaptive layout
  349. 5. Build the semantic theme
  350. 6. Select the correct M3 components
  351. 7. Define interaction and system states
  352. 8. Apply accessibility requirements
  353. 9. Add meaningful motion
  354. 10. Apply M3 Expressive treatment when appropriate
  355. 11. Review against anti-patterns
  356. 12. Produce implementation-ready handoff
  357. ```
  358. This ordering matters. Styling is intentionally not the first step.
  359. ------------------------------------------------------------------------
  360. ## Review contract
  361. Before approving a UI, the skill asks the agent to evaluate:
  362. | Area | What should be verified |
  363. |---------------|---------------------------------------------------------------------|
  364. | Structure | Primary task, grouping, hierarchy, navigation vs. actions |
  365. | Theme | Semantic colors, typography, shapes, elevation, dark theme |
  366. | Components | Correct M3 semantics and variants |
  367. | States | Loading, empty, error, disabled, selected, pressed, focus, hover |
  368. | Adaptive | Compact through large-window behavior |
  369. | Accessibility | Targets, contrast, focus, labels, scaling, reduced motion |
  370. | Expressive | Whether expression improves the experience rather than adding noise |
  371. This makes the skill useful not only for generating UI, but also for **design reviews and audits**.
  372. ------------------------------------------------------------------------
  373. ## Intended use
  374. This repository is useful for:
  375. - UI/UX design agents
  376. - AI coding agents
  377. - Product design workflows
  378. - Design-system generation
  379. - Material 3 UI reviews
  380. - Accessibility reviews
  381. - Figma-oriented design specifications
  382. - Android and Jetpack Compose planning
  383. - Web interfaces inspired by Material 3 semantics
  384. - Responsive and adaptive UI planning
  385. - Designer-to-developer handoff
  386. It is especially useful when an agent would otherwise receive a vague instruction such as *“use Material Design 3.”*
  387. ------------------------------------------------------------------------
  388. ## Platform notes
  389. The design guidance is intentionally broader than a single implementation framework.
  390. For Android and Jetpack Compose, the skill favors current `androidx.compose.material3` guidance, semantic theme roles, adaptive layouts, edge-to-edge behavior, and stable APIs for production unless experimental dependencies are explicitly acceptable.
  391. For web and other platforms, the goal is to preserve M3 semantics, hierarchy, tokens, interaction logic, and accessibility without blindly reproducing Android-specific implementation details.
  392. Library/API availability changes over time. `SKILL.md` therefore instructs agents to verify current official documentation before asserting exact dependency versions or the availability of newer M3 Expressive APIs.
  393. ------------------------------------------------------------------------
  394. ## Source of truth
  395. This project is based on official Material Design and Android guidance.
  396. - [Material Design 3](https://m3.material.io/)
  397. - [Material 3 Components](https://m3.material.io/components)
  398. - [Material 3 Color Roles](https://m3.material.io/styles/color/roles)
  399. - [Material 3 Typography](https://m3.material.io/styles/typography/overview)
  400. - [Material Design Tokens](https://m3.material.io/foundations/design-tokens/overview)
  401. - [Material Usability & Accessibility](https://m3.material.io/foundations/usability)
  402. - [Material 3 Expressive](https://m3.material.io/blog/building-with-m3-expressive)
  403. - [Google Design research on M3 Expressive](https://design.google/library/expressive-material-design-google-research)
  404. - [Material 3 in Jetpack Compose](https://developer.android.com/develop/ui/compose/designsystems/material3)
  405. - [Adaptive Window Size Classes](https://developer.android.com/develop/adaptive-apps/guides/use-window-size-classes)
  406. - [Canonical Adaptive Layouts](https://developer.android.com/develop/adaptive-apps/guides/canonical-layouts)
  407. - [Android Accessibility](https://developer.android.com/design/ui/mobile/guides/foundations/accessibility)
  408. When this repository and the current official specification disagree, **the current official specification wins**.
  409. ------------------------------------------------------------------------
  410. ## Contributing
  411. Contributions that improve accuracy, component coverage, accessibility, adaptive behavior, implementation guidance, or compatibility with newer Material 3 guidance are welcome. See [CONTRIBUTING.md](CONTRIBUTING.md) before opening a pull request.
  412. When proposing a rule change:
  413. 1. Prefer official Material Design or Android documentation as evidence.
  414. 2. Separate design guidance from framework-specific API availability.
  415. 3. Avoid introducing Material 2 behavior as if it were Material 3.
  416. 4. Keep rules semantic and reusable rather than tied to one screenshot or product.
  417. 5. Preserve accessibility requirements.
  418. 6. Explain why the change improves correctness or practical agent behavior.
  419. ------------------------------------------------------------------------
  420. ## License
  421. Released under the [MIT License](LICENSE).
  422. You may use, copy, modify, merge, publish, and distribute this project under the terms of the license.
  423. ------------------------------------------------------------------------
  424. ## Disclaimer
  425. This is an **unofficial community project** and is not affiliated with, endorsed by, or sponsored by Google.
  426. Material Design, Material You, Android, and related names are trademarks or products of their respective owners. Official Google documentation remains the source of truth.
  427. ------------------------------------------------------------------------
  428. ## Make AI-generated Material UI actually behave like Material
  429. If this skill helps your workflow, consider starring the repository and contributing improvements as Material Design 3 continues to evolve.
  430. **Design the system—not just the screenshot.**

Ratings and comments

Sign in to rate this skill.

Sign in

Free to use. If it’s helped, pass it on.