mui

mui skill 概覽

mui skill 是一份專注於在 React 專案中使用 Material UI v7 的實務指南，特別適合你需要正確使用 sx 樣式、建立可感知 theme 的元件、處理 responsive 版面，以及採用最新 v7 寫法，而不是得到泛泛的 React UI 建議時。對前端開發者、使用 AI 輔助寫程式的使用者，以及已經在用 @mui/material、希望加快實作並減少版本相關錯誤的團隊來說，這個 mui skill 特別有價值。

mui skill 能幫你完成什麼

當你的真正目標不是「從零學 MUI」，而是要安全地交付一個元件、頁面、版型、theme 或 migration 時，就很適合使用這個 mui skill。它特別擅長：

• 以符合慣例的 import 方式建立 MUI 元件
• 用 sx prop 取代零散、臨時的 CSS 寫法
• 使用 theme token 來處理 spacing、palette 與 typography
• 乾淨地套用 responsive breakpoints
• 處理會讓舊範例失效的 MUI v7 變更

哪些人適合安裝這個 skill

如果你符合以下情況，這個 skill 很適合你：

• 已經在使用 React，想讓 AI agent 產出更好的 MUI 程式碼
• 需要一份可重複使用的 mui 指南，支援持續性的前端工作
• 正在從 MUI v6 遷移，希望少踩過時模式的坑
• 想用 prompt 產出與 theme 一致的 UI 程式碼

如果你根本沒有使用 MUI，這個 skill 就會過於聚焦。

為什麼它比一般通用 prompt 更有用

像「做一個 Material UI 表單」這種普通 prompt，很常產出版本混雜的程式碼、薄弱的 theme 使用方式，或忽略 MUI 慣例的 styling。mui skill 額外提供了實務上的 guardrails，重點放在：

• MUI v7 的元件寫法
• 以 sx 作為主要 styling 路徑
• package import 的選擇
• responsive props 的使用方式
• 以 theme 為優先的設計決策

這通常代表你在拿到第一版草稿後，需要清理的東西會少很多。

最重要的差異化價值

這個 mui skill 的主要價值不在於涵蓋範圍多廣，而在於它把 agent 聚焦到真正是 MUI 使用者會在意的模式上：

• 具備 v7 意識的指引，包含從 v6 帶來的 breaking changes
• 範例圍繞 Box、Typography、Paper、Button、Grid2、Stack 以及常見的 app UI building blocks
• 在 resources/styling-guide.md 提供具體的 styling 參考
• 在 resources/theme-customization.md 提供實用的 theme 設定模式

skill 特別點出的關鍵版本注意事項

這個 skill 會明確指出 MUI v7 中那些很容易讓 AI 產生錯誤程式碼的現實差異：

• deep imports 不再是安全的預設做法；優先使用 package exports
• Modal 上的 onBackdropClick 已被移除；改用 onClose
• slots 與 slotProps 模式現在已經標準化
• CSS layers 支援很重要，尤其像 Tailwind v4 搭配 enableCssLayer 這類設定

光是這些細節，就足以成為你使用這個 skill、而不是依賴舊部落格範例的理由。

如何使用 mui skill

如何安裝 mui skill

使用以下指令，將這個 skill 安裝到你的 agent toolkit context：

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 版本，尤其是正在 migration 時
• styling 要用 sx、theme overrides，還是 styled
• responsive 需求，例如 xs、sm、md
• 表單、dialog、card、navigation 或 layout 的行為需求
• 現有 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. styling 方法
4. theme / responsive 限制
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. 先判斷任務屬於 component、layout、form 還是 theming
2. 明確點名你要使用的 MUI primitives
3. 除非真的需要其他路徑，否則要求使用 sx 與 theme tokens
4. 明確要求 responsive 行為
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 不會自動觸發 skills，就刻意在請求裡放入這些詞。

元件產生的最佳實務

請 agent 產出的程式碼，盡量遵循這個 skill 強調的模式：

• 從 @mui/material 或核可的 package exports 進行 import
• 樣式維持對 theme 有感知
• 當抽出樣式能提升重用性時，使用 SxProps<Theme>
• 優先使用 MUI 的 layout primitives，例如 Box、Stack、Container 與 Grid2
• 在 sx 中使用 breakpoint objects 來實作 responsive 行為

這種組合通常比混用 inline CSS、CSS modules 與任意 utility classes，更能得到乾淨的 mui 輸出。

theme 工作的最佳實務

當任務是 theme 客製化時，請明確界定範圍：

• 只調整 palette
• 只調整 typography
• 元件預設值
• dark mode
• 全 app 的 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 的設定，散落成一次性的 styling。

這個 skill 常對應到哪些 repo 檔案

當你的 repo 出現以下檔案或訊號時，mui skill 往往特別相關：

• theme.ts 或 theme.tsx
• components/**/*.tsx
• *.styles.ts 或 *.styles.tsx
• 從 @mui/material、@mui/icons-material 或 @mui/system 進行 import

如果你的 codebase 已經有這些跡象，對 Frontend Development 工作流來說，這個 skill 會是很值得安裝的候選。

第一版輸出後要驗證什麼

在接受產生出的程式碼前，請先檢查：

• imports 是否符合 MUI v7
• 沒有使用已棄用的 onBackdropClick
• responsive props 是否採用目前的寫法
• 是否用 theme 值取代到處散落的 raw hex 與 px
• Grid2 的使用方式是否符合你已安裝的 package 慣例
• 當元件需要更細部客製時，是否正確使用 slots 與 slotProps

這些檢查能提早抓出最昂貴的錯誤。

mui skill 常見問題

這個 mui skill 適合初學者嗎？

適合，前提是你已經懂基本的 React。這個 skill 能為常見任務提供實用的 mui 指南，不需要你一開始就把完整文件全看完。但如果你是 React 的完全新手，對 component state、props 與 app 結構可能仍需要額外協助。

mui skill 能取代 MUI 官方文件嗎？

不能。它最適合當成實作加速器，而不是權威的 API 參考來源。你可以用它產出更好的第一版草稿、避開版本錯誤；遇到邊界情況的 props 時，再回官方文件確認。

這主要是給 MUI v7 用的嗎？

是，這正是使用它的主要理由之一。這個 skill 會特別點出那些讓舊範例不再可靠的變更，所以如果你平常的 prompts 常產出 v5 或 v6 時代的模式，它會特別有幫助。

什麼情況下不該使用這個 mui skill？

以下情況可以跳過：

• 你的專案沒有使用 MUI
• 你需要的是 framework-agnostic 的 design system 答案
• 你想要 raw CSS、Tailwind-first 輸出，或非 React 的 UI 解法
• 你的任務主要是 business logic，而不是畫面呈現

在這些情境下，這種專門化不太能幫上忙。

它和直接要求「Material UI code」有什麼不同？

一般 prompt 常常會漏掉 MUI 的 styling 模型與版本細節。mui skill 會把 agent 導向 sx、theme 整合、responsive breakpoints 與目前的元件慣例，通常能有效降低重寫時間。

我可以用 mui skill 做 migration 工作嗎？

可以。它很適合用在偏 migration 的 prompt，例如：

• 替換已棄用的 API
• 更新 imports
• 把 styling 移到 sx
• 將舊的客製化程式碼改寫成 slots 與 slotProps

做 migration 任務時，務必清楚寫出你目前的版本與目標版本。

如何改善 mui skill 的使用效果

給 agent 更明確的 UI 規格

想提升 mui 輸出的最快方法，就是不要再只說「做一個好看的元件」，而是明確定義：

• 版面結構
• 元件 primitives
• 響應式行為
• 視覺意圖
• 狀態行為
• theme 規則

例如，與其說「做一個設定頁」，不如指定「桌機雙欄、手機單欄、使用 Paper 區塊、主要 CTA、TextField 驗證狀態，以及基於 theme 的 spacing」。

告訴它要走哪一條 styling 路徑

MUI 支援多種 styling 方式，但這個 skill 很明確地偏好在大多數元件工作中使用 sx。如果你不講清楚，輸出就可能開始飄掉。

實用指令：

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

光這一句，就能大幅提升一致性。

提供現有的 theme 與 design tokens

如果你的專案本來就有 theme，請提供相關的 palette 名稱、spacing scale、typography 選擇，以及 component overrides。當 mui skill 能對齊你真正的 design system，而不是臨時猜一套時，品質會明顯更好。

最值得提供的輸入包括：

• theme.ts
• 自訂 palette 名稱
• typography variants
• dark mode 需求
• 偏好的 radius 與 spacing 規則

只有在真的有幫助時才要求抽出 styles

對小型元件來說，直接寫 inline sx 通常更清楚。若是可重用或較複雜的樣式，再要求使用 const styles: Record<string, SxProps<Theme>>。如果你不先表明這個取捨，輸出就可能變得不是太碎，就是太擁擠。

一個好的 refinement prompt：

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

留意常見失敗模式

mui 使用上最常見的問題包括：

• 用硬編碼顏色取代 palette tokens
• 大量使用 raw pixel spacing，而不是 theme spacing
• 過時的 imports 或已棄用 API
• 缺乏 responsive 版面
• 在 MUI primitives 已能解決問題時，仍過度依賴自訂 CSS

這些問題，通常比起事後默默修改，更適合透過收緊 prompt 來修正。

用有針對性的 follow-up 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 穩定很多。

把 resource 檔案當成 prompt 錨點

提升結果的一個實用方法，是在 prompt 裡直接提到這個 skill 涵蓋的內部 resource 主題：

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

即使你的 agent 不會真的去打開那些檔案，使用它們的語彙，也能把模型推向這份 mui 指南原本預期的行為模式。

提升 Frontend Development 團隊的輸出品質

如果是團隊使用，建議把 prompt 標準化，至少固定包含：

• MUI 版本
• TypeScript 要求
• 以 sx 作為預設 styling
• theme token 的使用
• breakpoint 預期
• 基本無障礙要求
• import 慣例

這樣能讓 mui skill 從一次性的輔助工具，變成可重複使用的前端實作工具。

如何判斷 mui skill 是否真的有幫助

如果產生出的程式碼符合以下條件，就代表這個 skill 有發揮作用：

• 看起來像你現有的 MUI codebase
• 使用的是目前 v7 相容的模式
• 需要修正的 import 與 styling 問題更少
• 有尊重你的 theme
• 不會繞去使用泛用的 React styling 寫法

如果沒有達到，通常該修正的是你提供的脈絡，而不是直接放棄這個 skill。