跳转到使用指南
material-3作者 hamen

Material 3 Skill.

用于移动应用设计的 Claude Code 和 Codex skill:实现 Material Design 3 token、组件和自适应布局。

  • Mobile Apps
  • UI 代码
hamen/material-3-skill · skills/material-3/SKILL.mdSKILL.md
--- name: material-3 description: Implement Google's Material Design 3 (Material You) UI system. Primary: Jetpack Compose Material3 (MaterialTheme, components, adaptive layout). Also Flutter and limited web (@material/web, maintenance mode). Covers tokens, 30+ components, layout, theming, M3 Expressive (platform matrix), and accessibility. Use when: "material design", "MD3", "material you", "Jetpack Compose", "MaterialTheme", "material component", … --- ## Philosophy ## Current Updates: Google I/O 2026 ## Decision Tree ## Design Token System ## Jetpack Compose (primary) ## Web (limited): @material/web
前言和章节标题读取自上游文件,2026-09-14 · 完整 31,218 字符

01 功能说明

material-3 skill 在 Claude Code 和 Codex 中的作用

摘要、工作流与产物,均读自该 skill 的 SKILL.md。

来自 SKILL.md读取于 2026-09-14 · 非实际运行记录

以 skill 自身的术语

指导以 Jetpack Compose Material3 为主要目标实现 Google 的 Material Design 3(Material You),同时涵盖 Flutter 及通过 @material/web 实现的有限网页路径。它涵盖了颜色、字号体系、形状、层级和动效的 md.sys token 系统,30 多个组件及其变体的快速参考,自适应布局与导航、主题与动态颜色、M3 Expressive 平台矩阵,以及无障碍性。

审查模式会在十个类别上为应用或页面打出 0-10 分,并生成合规报告。它面向需要具体 MD3 默认值的设计师和开发者:五种窗口尺寸类别、以色调层级取代阴影、8dp 间距系统,以及大窗口下的最大内容宽度。

它产出什么

  • 一份 markdown 格式的 MD3 合规报告,包含总体评分和各类别评分、严重问题、警告、通过项以及优先修复建议。
  • 一个基于 MaterialTheme 构建的 Compose 主题,其 colorScheme 由 dynamicLightColorScheme、lightColorScheme 或生成的主题代码提供。
  • 一段由 md-sys 自定义属性组成的 CSS 主题代码块,包括通过媒体查询或类应用的深色主题变体。
查看示例提示词 ↗

工作方式

  1. 01
    除非技术栈另有说明,否则从 Compose 开始

    该文件将 Jetpack Compose Material3 视为默认路径,在编写任何代码之前,「决策树」会将应用外壳、单个组件、主题、表单、导航和数据展示分别导向特定章节和参考文件。

  2. 02
    应用 Token 层

    所有 MD3 token 都位于 md.sys 命名空间;Compose 将相同的语义角色映射到 MaterialTheme.colorScheme、typography 和 shapes,而 web 端则将其映射到以 md-sys 为前缀的 CSS custom properties。

  3. 03
    从 Quick Reference 中选取 Components

    组件表列出了每个组件的 web element 名称、关键变体和分类,并标注了哪些没有 @material/web 实现,以便可以用 CSS custom properties 结合标准 HTML 来构建。

  4. 04
    使用 Common Patterns 进行组装

    App Shell、Card Grid 和 Form Layout 模式均以 HTML 加 CSS 形式给出,包括一个断点,可在窄宽度下将导航栏(navigation rail)转换为底部导航。

  5. 05
    按需进行审查

    通过 audit 调用时,该 skill 会检查一个 URL、源文件或正在运行的应用,并在撰写报告前对十个类别分别打出 0 到 10 分。

02 找到适合场景

何时使用 material-3 Skill

在 Claude Code 或 Codex 中需要此类移动应用设计时使用 material-3 skill。适用范围和限制取自该 skill 的自有文件。

适合场景

  • 在 Jetpack Compose 中使用 androidx.compose.material3 的 composable(如 Scaffold、Button 和 NavigationBar)构建新的 Android 界面或应用。
  • 在 Android 12 及以上版本中,根据用户壁纸生成带有动态颜色的主题,否则回退到静态的浅色和深色配色方案。
  • 一种能够适配手机、可折叠设备、桌面、手表和 XR 的布局,而不是固定的手机优先设计。
  • 依据 MD3 审查现有应用或页面,并获得可据以工作的评分报告。
  • 通过在根元素或任意祖先元素上设置 MD3 CSS custom properties 来为 web UI 设置主题。

了解边界

  • 在 web 端期望使用 M3 Expressive 功能,因为 Material Web 只做维护,并未在其中实现 Expressive。
  • 在没有 hydration 策略的情况下进行服务端渲染,因为这些 web components 是需要 JavaScript 的自定义元素。
  • 仍混用 Material 2 和 Material 3 库的项目,两者的 API 和样式互不兼容。
  • 仅适配手机的布局,忽视大屏设备和折叠屏,包括将交互内容置于折痕处的情况。

需要提供的信息

  • 一个任务参数该 skill 接受 component、theme、layout、scaffold 或 audit 参数,后跟简短描述或 URL,用于选择要遵循的章节或参考文件。
  • 要审查的目标对于 audit 工作,可提供用于浏览器检查的 URL、用于读取源代码的文件路径,或对正在运行的应用的访问权限。
  • 用于自定义主题的种子颜色单个种子颜色即可派生出完整的配色方案;文件中指向了 material-color-utilities 包用于生成这些值。
  • 用于代码审查的源文件Compose 审查会读取 Kotlin 文件,以查找 MaterialTheme 的使用情况、composable、原始 Color 值、硬编码的 Dp 以及缺失的 semantics。

03 Skill 内部

material-3 这个 skill 给 Claude Code 和 Codex 的规则

SKILL.md 为 Agent 设定的 8 条具体指令、默认值与限制——文件中真正改变结果的部分。

  1. 新的 Material 相关工作优先使用 Compose

    对于新的 Android 工作,该文件建议在组件、expressive API、自适应 scaffold 以及 Styles API 集成方面优先使用 Jetpack Compose Material3;Android Views 仅在现有应用中可以接受。

  2. 绝不硬编码颜色

    使用 md-sys-color token,而不是原始的十六进制或 rgb 值,因为硬编码颜色会破坏动态主题、深色模式和对比度调整。

  3. 保持预期的色调配对

    只按设计好的方式组合颜色,例如 primary 与 on-primary、surface-container 与 on-surface 搭配;任意搭配会在动态色彩和高对比度模式下破坏对比度。

  4. 分割线使用 outline-variant

    分割线使用 outline-variant 绘制;outline 则保留给重要边界,例如文本框边框。

  5. 单独导入 Web Components

    切勿整体导入 @material/web 包;只导入正在使用的组件模块,因为全部导入会破坏打包体积。

  6. 在大屏窗口上限制宽度

    在大型(1200dp+)和超大型(1600dp+)窗口中,内容宽度上限为 840-1040dp,因为无限延伸的文本行难以阅读。

  7. 层级通过色调表现,而非阴影

    MD3 通过表面的色调颜色而非阴影来表达层级;只有当某个元素需要与繁杂背景额外区分时,才会加入阴影。

  8. 在 MD3 中使用 Roboto 是正确的

    Roboto 或 Roboto Flex 是 Material 的默认字体,frontend-design 中避免使用 Roboto 的建议在此不适用;只有在有意定制字号体系时才替换它。

04 投入使用

在 Claude Code 或 Codex 中安装 material-3

一条 npx skills add 命令,然后在你的 Agent 中执行第一个任务和对结果的清单检查。

将 material-3 添加到 Claude Code、Codex 或你的 Agent

在你的项目中运行;安装程序会询问要把它添加到哪个 Agent。

Terminal
npx skills add https://github.com/hamen/material-3-skill --skill material-3

针对 skills/material-3/SKILL.md 的通用 skills CLI 形式;该仓库可能会记录自己的路径。

给 Skill 第一个移动应用设计任务

按 skill 自身的术语撰写;把括号中的部分换成你的内容。

Starter prompt
We're moving our [Android app] from Material 2 to MD3. Set up MaterialTheme with dynamic color on Android 12+ and wire the md.sys color, type and shape tokens, then rebuild [screen name] as a Scaffold with a navigation rail on medium and expanded window size classes. We ship on foldables too, so keep interactive content off the hinge and constrain content width on large windows.

来源:依据 SKILL.md,按 skill 自身的术语撰写。

检查首次结果

SKILL.md 本身如何描述正确的结果:

  • 验证对比度和触控目标,而不仅仅是是否使用了 MD3 角色。
  • 在网页样式表中搜索硬编码的十六进制颜色。
  • 在 Kotlin 源码中搜索原始 Color 值。
  • 在 JavaScript 和 TypeScript 中搜索遗留的 Material 2 导入。
  • 调整视口大小或使用响应式模式,检查各断点下的布局。

在 OpenDesign 中通过其 SKILL.md 链接导入 material-3:Plugins → Add → Skill → Import from link,然后在顶部栏中选择它。

05 开源、可追溯

来源、许可与验证

本页面事实的来源,以及最后检查时间。

Author
hamen
Repository
github.com/hamen/material-3-skill 分支 master
Skill 文件
skills/material-3/SKILL.md 验证时记录的内容校验和;提交 14385f2
License
MIT 来自 LICENSE。
仓库星标数
1,384 GitHub 快照摄于 2026-09-14,针对整个 hamen/material-3-skill 仓库。不是 material-3 的评分或使用计数。
已由 OpenDesign 验证
2026-09-14 已检查源文件、路径、许可文本和 star 数量。未内置在 OpenDesign 主程序(检查日期 2026-08-28);本页面未记录实际运行。

SKILL.md 内部

  1. 理念三条原则——个性化、自适应和富有表现力——定义了动态色彩、窗口尺寸类别和弹簧动效。
  2. 决策树根据你正在构建的内容和目标平台,指向相应章节和参考文件。
  3. 设计 Token 体系md.sys 颜色、字体、形状、层级和动效 token,以及与 Compose 和 CSS 的映射。
  4. 组件速查表包含 30 多个组件的表格,列出对应的 Web 元素、关键变体和分类。
  5. Jetpack Compose(首选)androidx.compose.material3 配置、MaterialTheme、动态色彩、自适应 UI 与 insets。
  6. Web(有限支持):@material/web处于维护模式的 Web components,需单独导入,通过 CSS 自定义属性进行主题设置及深色主题。
  7. 常见模式HTML 与 CSS 中的应用外壳、卡片网格与表单布局代码片段。
  8. 反模式涵盖 MD2 混用的硬性禁止事项
Skill 自身的描述
「实现 Google 的 Material Design 3 (Material You) UI 系统。主要使用:Jetpack Compose Material3(MaterialTheme、组件、自适应布局)。也支持 Flutter 和有限的 web(@material/web,维护模式)。涵盖 token、30+ 组件、布局、主题、M3 Expressive(平台矩阵)和无障碍功能。使用场景:「material design」、「MD3」、「material you」、「Jetpack Compose」、「MaterialTheme」、「material component」、「md3 button」。」

SKILL.md 的前言描述。完整文件约 31,218 字符。在 GitHub 上阅读完整文件。

Material 3

在真实移动应用设计任务上运行 material-3。

下载 OpenDesign,从其 SKILL.md 链接导入 material-3,粘贴上述提示词,并在查看结果前阅读计划。

终端
npx skills add https://github.com/hamen/material-3-skill --skill material-3

OpenDesign 桌面客户端

一套设计系统,让每一次创作都保持品牌一致

在完整的 Vibe Design Workspace 中,用同一套品牌规则生成网页、PPT、可交互原型、数据看板、图像与 HTML 视频。连接本地 Codex、Claude Code、Cursor 等编程助手,即可免费创作。

  • 覆盖网页、PPT、原型、数据看板、图像与视频
  • 140+ 设计系统,以及完整模板与技能库
  • 连接本地 Codex 与 21+ 款编程助手 · 免费使用
免费下载

支持 macOS 与 Windows