material-design-3

Material Design 3

使用 Material 3 的语义、组件、令牌、交互状态和平台行为，打造一致的产品界面。目标不是让屏幕看起来有几分 Material 风格，而是让它像出色的 Android 或 Web 产品一样运行，并且只在有助于呈现层级或提升理解时才运用表现力。

先明确上下文

修改 UI 前，先检查项目并回答以下问题：

• 当前涉及哪个目标平台：Android Compose、Android Views、Wear OS 还是 Web？
• 项目中已有的 Material 库和版本是什么？
• 所请求的 API 在该目标平台上是稳定版、实验版还是不可用？
• 现有主题、组件、导航模型、间距规范和资源有哪些？
• 屏幕的主要任务、主要操作、内容层级和状态模型是什么？
• 哪些紧凑、中等、展开、桌面、可折叠设备和输入场景需要考虑？

保留既有的产品特色和架构。除非任务明确要求重新设计或迁移，否则优先使用现有主题和可复用组件。绝不要为了顺手调整样式而升级依赖、启用 alpha 版本或将 Views 迁移到 Compose。

阅读相关参考资料

• 有关视觉层级、颜色、排版、形状、海拔、布局和组件选择，请阅读 references/design-foundations.md。
• 有关 Android 库、Compose 实现、主题、系统 UI 和 Views 边界，请阅读 references/android.md。
• 当请求使用 Material 3 Expressive 或它确实能带来显著帮助时，请阅读 references/expressive.md。
• 有关响应式／自适应行为、无障碍、键盘、焦点和验证，请阅读 references/adaptive-accessibility.md。
• 对于 HTML、CSS、Web 组件、Angular Material 或其他 Web 框架，请阅读 references/web.md。
• 选择或升级依赖、验证 API 是否可用或引用指南时，请阅读 references/sources.md，并从官方来源获取最新的版本相关信息。

只阅读当前目标平台所需的参考资料。

设计规则

先确立层级，再进行装饰

1. 确定一项主要任务以及必需的辅助操作。
2. 优先通过对齐、间距、排版和背景角色来组织内容。
3. 仅在有助于明确归属、交互、选择或滚动行为时添加容器。
4. 使用组件的强调样式来体现操作优先级。
5. 基本层级清晰后，再添加富有表现力的形状、颜色或动效。

使用 Material 角色，而非任意取值

• 使用 MaterialTheme 角色或 Material Web 系统令牌，不要到处散布字面颜色、形状、字体大小或海拔值。
• 将内容映射到 surface、surfaceContainer、primary、onSurfaceVariant、outlineVariant 和 error 等语义角色。
• 确保浅色、深色、动态颜色、对比度和禁用状态保持一致。
• 沿用产品的间距节奏。只有在内容或平台限制有充分理由时，才使用单独的自定义值。

保持界面简洁

• 不要给每个分区、行、指标或控件都套上描边卡片。
• 不要嵌套卡片，也不要在同一内容周围堆叠多个装饰性容器。
• 不要用嵌套容器或表面重复表达相同的归属、分组或强调。作为评审的经验准则，在父级表面中，每三个有意义的内容单元最多允许一个嵌套的显式容器（1:3）。
• 当某个内容单元需要自己的边界，而嵌套会超出父级的 1:3 配额时，应将其提升为同级的独立容器或表面，而不是嵌套。该单元从区域表面到自身的显式容器最多不超过两层；框架内部结构和仅用于布局的节点不计入。
• 当间距、表面角色变化或一条分隔线足以传达边界时，不要使用描边。
• 只有当持久边界属于组件职责的一部分时，才使用官方描边组件及其默认边框令牌。不要在组件或其父级外围再加第二层描边。
• 使用 outline 标识组件或状态所需的边界；仅对强调程度较低且非必要的分隔使用 outlineVariant。绝不要把装饰性低对比度描边作为焦点、错误、选中状态或控件边界的唯一提示。
• 不要用阴影作装饰。只有在确有重叠、需要与模态内容分隔，或浮动元素必须清晰呈现深度时，才使用阴影层级。
• 普通层级优先使用色调层级和容器表面角色。
• 除非产品或提供的参考明确要求，否则避免使用渐变、光晕、模糊、玻璃效果和装饰性边框。
• 默认调色板不要使用透明、半透明或“液态玻璃”效果。Material 表面应采用稳定、易读的颜色角色，而不是让壁纸、图像或底层透显出来。
• 不要使用 backdrop-filter、毛玻璃面板、高透明度的表面填充、半透明边框或玻璃质感高光来营造层次。
• 如果使用稳定的主题表面能提高可读性，就不要将重要文本、控件、表单或导航置于透明图像效果之上。
• 如果系统表面、媒体叠加层、沉浸式查看器或提供的品牌参考确实需要半透明效果，应将其限制在局部，保持语义对比度，测试浅色、深色和动态颜色，并提供纯色回退方案。
• 不要给所有表面都使用相同的大圆角。形状应体现组件家族、分组、状态或强调程度。
• 不要把操作界面改成落地页，不要添加超大号主视觉文案，也不要为了显得高端而制造空白区域。

让组件各司其职

• 将强调程度最高的填充操作用于主要完成操作；强调程度依次降低时，使用色调、描边或文本变体。
• 仅在频繁的屏幕级主要操作中使用 FAB。不要仅仅因为它具有 Material 风格就添加 FAB。
• 卡片用于内容各异、彼此独立且可单独操作的内容。对于密集、同质的内容，优先使用列表或无边框分区。
• 芯片用于紧凑属性、筛选条件、选择项或建议，而不是作为通用按钮或装饰性标签。
• 标签页用于同一目的地内的同级视图，而不是全局导航。
• 对话框用于简短且阻断流程的决策；底部表单用于情境选择或辅助任务；复杂流程使用全屏界面。
• 破坏性操作应明确标示，并与常规操作分开；仅在难以恢复时才要求确认。

确保每种状态都经过设计

覆盖工作流实际可能进入的启用、按下、聚焦、悬停（适用时）、选中、禁用、加载、空、错误、离线和成功状态。不要仅通过颜色传达状态。异步变化期间应保持内容和布局稳定。

将加载和表单视为产品状态

• 根据已知结构／内容的多少以及操作可能持续的时间，选择渐进式加载、骨架屏、行内进度提示或简单指示器。
• 优先使用与最终几何尺寸一致的稳定占位内容，而不是会遮住整个屏幕的居中旋转指示器。
• 独立区域就绪后，逐步显示内容；不要让无关操作阻塞可用内容。
• 明确显示提交、验证、自动保存、上传和重试状态，并确保用户可以恢复操作。
• 在设计约定中明确展示表单标签、辅助文本、错误、必填状态、焦点、键盘／IME 行为和操作层级。
• 除非说明当前状态或保留安全的导航／取消方式，否则不要禁用整个表单。

Material 3 Expressive 使用门槛

Material 3 Expressive 是一种有意强调重点的系统，不是装饰性润色。

• 对于密集、重复或高度实用的工作流，默认使用标准 Material 3。
• 仅在能改善注意力引导、反馈或情感基调的突出时刻，使用富有表现力的动效、形状对比、灵活的字体排印和新的表现力组件。
• 常用工具交互应比关键过渡或主视觉交互更克制。
• 不要让每个控件都变形、让每次数值变化都产生动画，也不要把形状库用作背景装饰。
• 确认已安装库中的确切 API。遵守 ExperimentalMaterial3ExpressiveApi 和发布渠道的边界。
• 如果现有项目使用稳定版 Material 3，而 Expressive 需要 alpha API，请在更改发布渠道前说明依赖／API 方面的权衡。

实施工作流

1. 检查渲染路径、主题、共享组件、依赖项和目标屏幕尺寸。
2. 编写简明的 UI 约定：内容优先级、导航、主要操作、组件、状态和自适应转换。
3. 选择官方组件；如果没有合适的组件，则选择最精简且易于访问的自定义组合。
4. 先实现主题角色和布局结构，再进行润色。
5. 添加交互行为、语义、系统内边距、焦点顺序和状态恢复。
6. 有选择地增强表现力，并移除任何无法传达信息的轮廓、阴影、容器或动画。
7. 在相关窗口尺寸和真实内容下验证，而不只是查看理想预览。

修改现有屏幕时，应采用范围最小且职责明确的改动。除非有明确要求，否则不要彻底替换应用的设计语言。

必需验证

对于可见的 UI 改动，仅通过编译不能证明视觉效果正确。

• 运行范围最小且相关的编译、lint 或框架检查。
• 检查确切的目标界面和视口。对于手机／平板布局，应包括紧凑型手机和所有其他受影响的窗口类别；对于 Wear、小组件和 Web，应改用各自目标专用的配置。
• 视情况检查较长的本地化文本、大字号、深色主题、动态／自定义颜色、加载、空内容和错误内容。
• 对适用的 Android 手机／平板屏幕，检查边到边布局内边距、IME 遮挡、手势区域、旋转／调整大小和状态连续性。
• 在 Web 上检查键盘导航、可见焦点、悬停、减少动态效果、缩放以及窄／宽布局。
• 确认 Android 触控目标达到 48dp，Web 点击区域符合平台规范。
• 确认对比度和含义不依赖颜色单独表达。
• 确认容器不会重复表达边界，也不会超过 1:3 的容纳预算或两层的手工嵌套限制。
• 确认有意义的边框以及状态或焦点指示器在所有受支持的主题和状态下都能清晰区分；装饰性描边不得承载必要含义。
• 确认没有裁切的标签、重叠的控件、意外嵌套的滚动区域或布局跳动。

在环境支持时，使用截图或预览进行视觉对比。明确说明实际检查了哪些设备／浏览器场景。

审查结果

审查或移交工作时，请报告：

• 所选的 Material 库，以及是否有任何 API 处于实验阶段；
• 已实现的层级结构和自适应行为；
• 已涵盖的无障碍功能和系统 UI 行为；
• 实际运行过的检查和实际检查过的屏幕尺寸；
• 尚存的设备、浏览器、迁移或依赖项风险。

不要仅凭命名、依赖项是否存在或编译结果，就声称已实现 Material 3 Expressive、自适应、无障碍或经过视觉验证的行为。