mui

mui skill 概览

mui skill 是一份专注于 React 项目中使用 Material UI v7 的实战指南，特别适合你需要正确使用 sx 样式、构建感知 theme 的组件、处理响应式布局，并遵循最新 v7 模式，而不是得到泛泛的 React UI 建议时使用。它最适合前端开发者、依赖 AI 辅助编码的使用者，以及已经在使用 @mui/material、希望更快落地实现并减少版本相关错误的团队。

mui skill 能帮你完成什么

当你的真实目标不是“从零学习 MUI”，而是要安全地交付一个组件、页面、布局、主题方案或迁移任务时，就该用这个 mui skill。它尤其擅长：

• 用符合 MUI 习惯的 import 方式构建组件
• 优先使用 sx prop 做样式，而不是零散的 ad hoc CSS
• 使用 theme token 处理 spacing、palette 和 typography
• 干净地应用响应式断点
• 处理会让旧示例失效的 MUI v7 变更

谁适合安装这个 skill

如果你符合下面这些情况，这个 skill 很适合你：

• 已经在使用 React，并希望 AI agent 生成更靠谱的 MUI 代码
• 需要一份可复用的 mui 指南来支撑反复出现的前端任务
• 正在从 MUI v6 迁移，希望减少过时写法
• 希望通过 prompt 产出与 theme 保持一致的 UI 代码

如果你根本不用 MUI，那这个 skill 就会显得过于垂直。

为什么它比通用 prompt 更有用

像“做一个 Material UI 表单”这样的普通 prompt，常常会返回版本混杂的代码、薄弱的 theme 使用方式，或忽略 MUI 约定的样式写法。mui skill 提供了一些非常实用的护栏，重点约束在：

• MUI v7 组件模式
• 将 sx 作为主要样式路径
• package import 选择
• 响应式 prop 的用法
• 以 theme 为先的设计决策

这通常意味着首版生成后需要清理和返工的地方会少很多。

最关键的差异化价值

这个 mui skill 的核心价值不在于覆盖面广，而在于它能把 agent 收束到 MUI 用户真正关心的模式上：

• 面向 v7 的指导，包括从 v6 迁移时的 breaking changes
• 以 Box、Typography、Paper、Button、Grid2、Stack 以及常见应用 UI 基础组件为中心的示例
• resources/styling-guide.md 中提供的具体样式参考
• resources/theme-customization.md 中提供的实用 theme 配置模式

skill 明确指出的关键版本注意事项

这个 skill 会明确提示一些 MUI v7 的现实变化，而这些点正是 AI 生成代码时最容易踩坑的地方：

• deep imports 不再是安全默认项；优先使用 package exports
• Modal 上的 onBackdropClick 已被移除；应改用 onClose
• slots 和 slotProps 模式现在已经标准化
• 对于 Tailwind v4 搭配 enableCssLayer 这类配置，CSS layers 支持很重要

光是这些细节，就足以说明为什么在很多场景下，直接用这个 skill 会比依赖旧博客示例更稳妥。

如何使用 mui skill

如何安装 mui skill

用下面这条命令，把这个 skill 安装到你的 agent toolkit 上下文中：

npx skills add softaworks/agent-toolkit --skill mui

如果你的环境使用的是其他 skills loader，也请保持 repo 和 skill slug 不变：softaworks/agent-toolkit，skill 为 mui。

使用 mui 之前先看哪些文件

建议按这个顺序阅读：

1. skills/mui/SKILL.md
2. skills/mui/resources/styling-guide.md
3. skills/mui/resources/component-library.md
4. skills/mui/resources/theme-customization.md
5. skills/mui/skill-rules-fragment.json

这个阅读顺序很重要，因为 resources 里放的是具体实现模式，而 rules 文件能告诉你：哪些类型的 prompt 和哪些文件信号，本来就是为了触发 mui skill 而设计的。

mui skill 需要什么样的输入

当你给 agent 足够的前端上下文，让它能判断应该采用哪种组件、布局和 theme 模式时，mui skill 的效果最好。比较有用的输入包括：

• 你希望构建的组件或页面
• 你的 MUI 版本，尤其是在迁移场景下
• 样式应该使用 sx、theme overrides，还是 styled
• 响应式要求，比如 xs、sm、md
• 表单、对话框、卡片、导航或布局行为
• 现有 theme 文件路径，例如 src/theme.ts
• 无障碍或设计约束

弱输入：

• “Make this look better with MUI”

强输入：

• “Create a responsive MUI v7 settings page using Container, Paper, Stack, TextField, and Switch, styled with sx, using theme spacing and palette tokens, with mobile-first layout and no hardcoded colors.”

如何把模糊目标改写成高质量 mui prompt

一个好的 mui 使用 prompt，通常包含五个部分：

1. 目标 UI
2. 组件集合
3. 样式方法
4. theme / 响应式约束
5. 输出格式

示例：

“Using MUI v7, build a profile card component in TypeScript with Card, Avatar, Typography, and Button. Use sx only, reference theme palette and spacing, support xs to md responsive behavior, and return a self-contained component plus any extracted SxProps<Theme> styles.”

这比泛泛的需求更好，因为它明确告诉 agent：怎样才能始终待在 MUI 预期的工作流里。

实用的 mui skill 使用流程

一套可靠的 mui skill 工作流如下：

1. 先判断任务属于组件、布局、表单还是 theming
2. 明确点名你希望使用的 MUI primitives
3. 除非你确实需要别的方案，否则要求使用 sx 和 theme tokens
4. 明确要求响应式行为
5. 检查生成结果中的 imports 和 v7 兼容性
6. 再继续微调 spacing、variants 和 slot 级别的定制

这样做能让第一版草稿更接近可上生产的形态。

哪些触发词适合调用 mui skill

repo 中的 rule fragment 表明，包含以下术语的 prompt 特别适合触发 mui：

• mui
• material-ui
• @mui/material
• sx prop
• ThemeProvider
• createTheme
• useTheme
• Dialog
• Drawer
• TextField
• Autocomplete

如果你的 agent 不会自动触发 skill，那就在请求里有意识地加入这些词。

组件生成的最佳实践

建议让 agent 生成符合 skill 强调模式的代码：

• 从 @mui/material 或已批准的 package exports 中导入
• 样式保持 theme-aware
• 当抽离样式能提升复用性时，使用 SxProps<Theme>
• 优先使用 MUI 的布局 primitives，例如 Box、Stack、Container 和 Grid2
• 在 sx 中使用 breakpoint objects 处理响应式行为

这种组合通常会比把 inline CSS、CSS modules 和随意的 utility classes 混在一起，更容易产出干净的 mui 代码。

theme 相关任务的最佳实践

如果任务是做 theme customization，一定要把范围说清楚：

• 只改 palette
• 只改 typography
• 组件默认值
• dark mode
• 全局 ThemeProvider 接入

示例 prompt：

“Update our MUI v7 theme to use a custom primary and secondary palette, Inter typography, rounded corners, and button text without uppercase. Show the createTheme object and the ThemeProvider integration.”

这和 skill 中的 theme resource 很匹配，也能避免把本应放在 theme 层面的东西，误写成零散的一次性样式。

这个 skill 通常会映射到哪些 repo 文件

当你的 repo 中出现以下文件或信号时，mui skill 往往很相关：

• theme.ts 或 theme.tsx
• components/**/*.tsx
• *.styles.ts 或 *.styles.tsx
• 从 @mui/material、@mui/icons-material 或 @mui/system 导入

如果你的代码库已经有这些信号，那这个 skill 很值得纳入 Frontend Development 工作流。

第一版输出后要重点验证什么

在接受生成代码之前，先检查：

• imports 是否对 MUI v7 有效
• 是否还残留已废弃的 onBackdropClick
• 响应式 props 是否使用了当前推荐模式
• 是否优先使用 theme 值，而不是到处写原始 hex 和 px
• Grid2 的用法是否符合你已安装 package 的约定
• 在组件定制需要时，是否正确使用了 slots 和 slotProps

这些检查能尽早拦下最贵、最费返工成本的错误。

mui skill 常见问题

这个 mui skill 适合初学者吗？

适合，前提是你已经懂基础 React。这个 skill 能为常见任务提供一套实用的 mui 指南，不需要你先完整通读官方文档。
但如果你是 React 绝对新手，关于组件 state、props 和应用结构，可能仍然需要额外帮助。

mui skill 能替代 MUI 官方文档吗？

不能。它更适合作为实现加速器，而不是权威 API 参考。你可以用它生成质量更高的第一版代码、减少版本错误；遇到边缘 props 或细节 API 时，仍然应该去官方文档核对。

它主要是为 MUI v7 准备的吗？

是的，这正是使用它的主要理由之一。这个 skill 会突出那些会让旧示例不再可靠的变化，所以如果你平时的 prompt 总是在产出 v5 或 v6 时代的模式，它会特别有帮助。

什么情况下不该用这个 mui skill？

以下情况建议跳过：

• 你的项目不用 MUI
• 你需要一个与框架无关的设计系统答案
• 你想要纯 CSS、Tailwind-first 输出，或非 React 的 UI 方案
• 你的任务主要是业务逻辑而不是界面呈现

在这些场景里，这种垂直专精帮不上太多忙。

它和直接要求“Material UI code”有什么区别？

普通 prompt 往往会漏掉 MUI 的样式模型和版本细节。mui skill 会把 agent 更明确地引导到 sx、theme 集成、响应式断点和当前组件约定上，通常能明显减少重写时间。

我可以用 mui skill 做迁移任务吗？

可以。它很适合下面这类偏迁移的 prompt：

• 替换已废弃 API
• 更新 imports
• 把样式迁移到 sx
• 将旧的定制代码适配到 slots 和 slotProps

做迁移任务时，一定要明确写出你当前版本和目标版本。

如何改进 mui skill 的使用效果

给 agent 更明确的 UI 规格

想提升 mui 输出质量，最快的方法就是别再只说“做一个好看的组件”，而要明确给出：

• 布局结构
• 组件 primitives
• 响应式要求
• 视觉意图
• 状态行为
• theming 规则

例如，比起说“做一个设置页面”，更好的是指定“桌面端双栏、移动端单栏、使用 Paper 分区、主 CTA、TextField 校验状态，以及基于 theme 的 spacing”。

明确告诉它使用哪条样式路径

MUI 支持多种样式方案，但这个 skill 对大多数组件工作都明显偏向 sx。如果你不把这点说清楚，输出很容易漂移。

有用的指令：

• “Use sx for all local styling and keep values theme-aware.”

就这一句话，通常就能大幅提升一致性。

提供现有 theme 和设计 token

如果你的项目已经有 theme，把相关 palette 名称、spacing scale、typography 选择和组件 override 一并提供出来。mui skill 在能对齐你真实设计系统时，效果会明显更好，而不是临时替你“发明”一套风格。

最值得共享的输入包括：

• theme.ts
• 自定义 palette 名称
• typography variants
• dark mode 要求
• 偏好的圆角和 spacing 规则

只在确实有帮助时要求抽离样式

对于小组件，直接写 inline sx 往往更清楚。对于复用多或结构复杂的样式，可以要求使用 const styles: Record<string, SxProps<Theme>>。如果你不把这个选择说清楚，输出要么会碎得太散，要么会挤得太满。

一个不错的 refinement prompt：

• “Refactor repeated sx blocks into typed reusable style objects.”

留意常见失败模式

mui 使用里最常见的问题包括：

• 用硬编码颜色代替 palette tokens
• 大量直接写像素，而不是用 theme spacing
• 过时的 imports 或已废弃 API
• 非响应式布局
• 在 MUI primitives 已经能解决问题时，仍然过度使用自定义 CSS

与其默默后期修，不如直接把 prompt 收紧，这样更有效。

用有针对性的后续 prompt 迭代

拿到第一版后，不要只说“improve this”，而是一次只要求一种改进：

• “Make the layout mobile-first using breakpoint objects.”
• “Replace hardcoded colors with theme palette tokens.”
• “Convert the modal behavior to v7-safe onClose handling.”
• “Use slotProps for internal part customization.”

这种迭代方式会让 mui skill 稳定得多。

把资源文件当作 prompt 锚点来用

一个很实用的提效方式，是在 prompt 中明确提到这个 skill 涵盖的内部资源主题：

• component library patterns
• styling guide patterns
• theme customization patterns

即使 agent 不会真的去打开这些文件，只要你使用它们的语汇，也能把生成方向更好地拉回到 mui 指南预设的行为上。

为 Frontend Development 团队提升输出质量

如果是团队使用，建议把 prompt 规范统一到这些维度上：

• MUI 版本
• TypeScript 要求
• 默认使用 sx
• theme token 使用
• breakpoint 预期
• 基础无障碍要求
• import 约定

这样，mui skill 就不再只是一次性的助手，而会变成可复用的前端实现工具。

怎么判断 mui skill 是否真的在帮忙

如果生成出来的代码具备以下特征，就说明这个 skill 发挥作用了：

• 看起来像你现有的 MUI 代码库
• 使用当前 v7 兼容模式
• 需要修的 import 和样式问题更少
• 能尊重你的 theme
• 不会绕去泛泛的 React 样式写法

如果没有达到这些效果，通常问题在于上下文不够，而不是这个 skill 本身不该用。