maliang (馬良) —— 設計系統技能
腳本呼叫約定：
python3 scripts/…中的相對路徑以本 skill 的安裝目錄為基準（CWD 假設）。 在使用者專案中執行時，一律以{SKILL_DIR}絕對路徑呼叫，如python3 {SKILL_DIR}/scripts/ui-graph.py …；--target/--framework-file等輸入參數顯式指向使用者專案路徑，禁止把 skill 自帶的examples/當作分析目標。
十三個子命令覆蓋 UI/UX 全生命週期（研究→定義→設計→實作→驗證→交付→迭代，總圖見 references/meta/lifecycle.md）：design-md（建立 DESIGN.md，含領域探索與決策帳本）→ redesign（改版現有 UI）→ explore（方向未定時多方案發散-比較-收斂）→ draw-md（頁面級 UI markdown）· component（單元件 brief）→ preview（預覽驗證）→ critique（可用性評審）→ draw-harmony/draw-flutter/draw-element（框架程式碼）→ ui-graph（UI 關係管理）· ip（IP 形象）/ip-handbook（IP 視覺手冊）。
- design-md（上游）— 產出 prose-first 的 DESIGN.md（YAML token + Markdown 設計理由，Google Labs agent-first 格式）。支援「建立、應用、驗證、匯出」四個動作。解決「設計系統是什麼、為什麼」。
- redesign（上游旁路）— 改版現有 UI，10 維審計（含 SEO 與追蹤、產物一致性）+ 保留規則。支援 Refresh / Restructure / Rebuild / Deslop 四模式。解決「現有設計如何變好」。
- draw-md（中游）— 從 DESIGN.md 產出頁面級硬 token UI markdown（佈局章節 + 元件參數表，顏色/字體/間距全引用 token，RGBA + HEX）。解決「每個頁面/元件具體怎麼實作」。
- preview（驗證）— 使用 Element Plus 框架對 draw-md 產出進行即時預覽驗證，支援 iOS/Android 設備外殼。解決「效果對不對」。
- critique（驗證·深評）— Nielsen 10 啟發式 0-4 評分 + persona 走查 + 認知負荷清單，產出評分快照/趨勢/backlog。解決「好不好用」。UI 合規/a11y 清單讀
references/meta/web-interface-guidelines.md；產品 UI craft 紀律與嚴格評審/去 slop 深流程見references/interface-design/（原獨立 skill 併入） - draw-harmony（下游）— 將 draw-md 邏輯 UI 轉換為 HarmonyOS（ArkTS）框架實作。解決「HarmonyOS 程式碼怎麼寫」。
- draw-flutter（下游）— 將 draw-md 邏輯 UI 轉換為 Flutter 框架實作。解決「Flutter 程式碼怎麼寫」。
- draw-element（下游）— 將 draw-md 邏輯 UI 轉換為 Element Plus 框架實作。解決「Element Plus 程式碼怎麼寫」。
- ui-graph（關係管理）— 從 ui-markdown/ 產出 ui-relationships.json（層級 + 跳轉）+ ui-hash-state.json（雜湊基線）+ ui-implementation-map.json（邏輯 UI ↔ 實作映射）。解決「頁面關係怎麼管、變更怎麼追、實作缺口在哪」。
- ip（IP 形象）— 基於 DESIGN.md 調性構造 prompt，優先呼叫 text_to_image API 生成圖片，fallback 輸出結構化 prompt 文件。解決「專案 IP 形象怎麼生」。
- ip-handbook（IP 視覺手冊）— 8 模組產出規格（三視圖/動作延展/表情包/字體/色彩/版式/周邊物料/通用要求），2K 高畫質 3:4。解決「IP 視覺系統怎麼落地」。
子命令路由
🔴 CHECKPOINT：無 DESIGN.md 時，嚴禁直接進入 draw-md / draw-* 下游子命令 —— 必須先走 design-md 建立設計系統，否則產出的 UI markdown 與框架程式碼無 token 可引用。
| 使用者意圖 | 子命令 | 完整流程 |
|---|---|---|
| 建立 / 生成 DESIGN.md（從程式碼/截圖/訪談） | design-md | references/commands/design-md.md |
| 應用 DESIGN.md 到前端程式碼 | design-md | references/commands/design-md.md |
| lint / diff / 匯出 / 驗證 DESIGN.md | design-md | references/commands/design-md.md |
| 🔷 改版 / 重設計現有 UI（Refresh/Restructure/Rebuild/Deslop 去AI味） | redesign | references/commands/redesign.md |
| 🔷 方向性微調（bolder 更大膽 / quieter 更安靜 / distill 更精煉，保持視覺世界不變，redesign 輕檔前置） | redesign | references/commands/redesign.md |
| 🔷 單個元件 brief（做個按鈕 / 單個輸入框 / toast 等單元素，8 狀態硬門） | component | references/commands/component.md |
| 產出頁面級 UI markdown（token 表 + 頁面規格） | draw-md | references/commands/draw-md.md |
| 跨頁面複用元件（導覽列 / dock）規格化 | draw-md | references/commands/draw-md.md |
| 🔷 方向未定，先比較多套方案再定稿（佈局/密度/人格/互動模型真不同，預設 3 至多 5） | explore | references/commands/explore.md |
| 🔴 預覽 UI markdown 效果（設備外殼 + Element） | preview | references/commands/preview.md |
| 🔷 可用性評審 / 評分（Nielsen+persona 走查+認知負荷） | critique | references/commands/critique.md |
| 🔴 將 UI markdown 轉換為 HarmonyOS（ArkTS）程式碼 | draw-harmony | references/commands/draw-harmony.md |
| 🔴 將 UI markdown 轉換為 Flutter（Dart）程式碼 | draw-flutter | references/commands/draw-flutter.md |
| 🔴 將 UI markdown 轉換為 Element Plus（Vue 3）程式碼 | draw-element | references/commands/draw-element.md |
| 🔷 生成 / 查詢 UI 關係圖（層級 + 跳轉 + 雜湊 + 實作映射） | ui-graph | references/commands/ui-graph.md |
| 🔷 查詢跳轉目標未生成 / 異常跳轉 / 未實作頁面 / 規格↔程式碼語義漂移（功能缺失/寫死值/架構偏離） | ui-graph | references/commands/ui-graph.md |
| 🔷 基於 DESIGN.md 生成 IP 形象（API 優先，fallback prompt） | ip | references/commands/ip.md |
| 🔷 生成 IP 視覺手冊（三視圖/動作/表情/字體/色彩/版式/周邊） | ip-handbook | references/commands/ip-handbook.md |
🔴 標記的行需先確認 draw-md 產出存在；preview/draw-* 無 UI markdown 輸入時應在子命令流程內 fallback 引導使用者回退到 draw-md。使用者未指定目標框架時，draw-* 先查使用者專案已有前端棧（有 → 跟隨該棧並說明假設；無 → 按
framework/INDEX.md「框架選型指南」按場景推薦，經使用者確認後再進）。🔷 標記的行屬新增能力，critique 需先有 preview 產出或可訪問頁面，ui-graph 需先有 draw-md 產出，ip/ip-handbook 需先有 DESIGN.md。
進入子命令後，按其流程文檔執行。檢查點、邊界情形、交付核對清單均在各子命令文檔內 —— 本路由器不含流程主體。
任務規模分檔（輕檔 / 全檔）
| 檔位 | 判據 | 流程 |
|---|---|---|
| 輕檔 | 專案已有 DESIGN.md，且改動範圍 = 單元件（component 子命令）或單頁局部調整 | 不重走 design-md 與全頁清單流程：直接 draw-md 改目標頁（單元件走 component）+ preview 抽查該頁/該元件 |
| 全檔 | 新專案 / 新頁面類型 / 多頁改動 / 方向未定（先 explore）/ 無 DESIGN.md | 完整鏈路 design-md → draw-md → preview → draw-* |
輕檔不是門禁豁免。以下不可裁剪項任何檔位完整執行：
- a11y 檢查 — aria-label、觸控目標 ≥44px、對比度、
prefers-*偏好（CRITICAL 類，見references/meta/rules-priority.md衝突裁決規則 4，不可妥協）； - preview 硬門禁 — validate-draw-md 檢查與 preview 評審 disposition 照常；輕檔的「抽查」指只跑改動頁，不是跳過或降閾值。唯一例外：使用者明說不需要預覽時按
preview.md「跳過條件（顯式 opt-out）」跳過渲染與評審，validate 檢查照跑，交付說明掛 DEGRADED 橫幅； - draw-md 硬約束（token 引用 / 暗色引用 / 動效 ≤400ms）隨改動頁逐條過（見
references/commands/draw-md.md約束彙總）。
無 DESIGN.md 時的輕檔請求按「失敗模式與 fallback」第一行處理：引導先走 design-md，分檔不提供例外。
無人值守與 CHECKPOINT 降級
判據：使用者明說「你定 / 直接做」，或會話無人值守（使用者缺席、不回應）時，CHECKPOINT 不逐點阻塞。僅當「缺的資訊會改變核心方向、且推斷不出來」時才集中問一次；改得回來的細節自己決定並說明假設。
| CHECKPOINT 類別 | 無人值守時預設動作 |
|---|---|
| 方向 / 提案確認（design-md 0b/0c、explore 方向清單） | 按證據與推薦直接推進；explore 仍實體化 3 個方向、三張首屏縮到 480px 並排自選並寫明理由；任務明確只要一個方向時不問也不做對比頁 |
| 提取 / 盤點確認（token 提取、頁面清單） | 按現場證據取值並標置信（✅/⚠️/❓，寫法見 design-md「提取路徑置信標記」）；清單按預設規則生成 |
| 交付前確認（preview / critique 行動確認） | 按門禁與證據結果推進，交付說明首行掛降級橫幅；preview 跳過不屬於自選動作——僅使用者明說時按 preview.md「跳過條件（顯式 opt-out）」允許，無人值守一律照跑 |
| 素材 / API 類確認（ip 等） | API 不可用走既有 fallback；產物按新路徑落盤不覆蓋 |
呈現紀律：交付說明首行掛 ⚠️ DEGRADED: unattended（<原因>）（沿用 critique/preview 既有 DEGRADED 形狀，不引入第二模式）；自選決定與理由逐條寫入設計說明；看不了圖時寫明「未驗證實際視覺」、不給視覺評分；沒有可運行環境時不說互動已通過。使用者回歸後按其意見修訂，修訂走決策回寫。
弱 runtime 與跨 agent 降級
與上一節互補：無人值守表管使用者缺席軸，本表管運行能力軸（無 subagent / 非主流模型 / 上下文小的 runtime）。
按吃緊程度逐級降級，降級犧牲流程，不犧牲硬約束（a11y 檢查、token 引用、G01–G46 CRITICAL 門、真實資產協議不豁免）：
- explore 多方向並行 → 串行：每方向開工前只讀 DESIGN.md 契約與自己那張方向卡，不參考已做的方向；
- 仍吃緊 → 主方向 1 份完整規格 + 其餘方向輕量卡（只寫方向卡 7 欄 + 首屏骨架），比較頁降為方向卡並排；
- references 只讀當前子命令「meta 文檔載入時序」的必讀列，不全讀；
- draw-md 大批量頁面先交 P0 頁（見 default-pages），其餘頁方向確認後分批；
- 檢查點問答改為產出裡的 assumption 清單（gate 檔案與 CHECKPOINT 降級語義照舊——見上一節，兩者共用）。
版本檢查
本節讓使用者知道 maliang skill 有沒新版本。確定性邏輯（節流判定 / 版本比較 / 記錄）在 scripts/version-check.py，狀態檔案預設 ~/.maliang/version-check（--state 可改）；agent 只跑命令與 git ls-remote。
使用本 skill 時先跑 python3 {SKILL_DIR}/scripts/version-check.py due；輸出 skip:* 直接跳過本節。輸出 due 時：
- 運行
git -C {SKILL_DIR} ls-remote --tags --refs --sort=-v:refname origin 'v*'，取第一行 tag 傳給python3 {SKILL_DIR}/scripts/version-check.py compare <tag>（--current缺省讀本倉 SKILL.md frontmatter）； compare輸出same（含 tag 不符合 vX.Y.Z 形狀——按沒有標籤處理）就不用提；輸出newer時先完成使用者的任務，結束時告訴使用者「maliang 有新版本 vX.Y.Z，更新見 https://github.com/Kirky-X/maliang/releases，需要時運行git -C {SKILL_DIR} pull --ff-only；不想再收到提醒，運行python3 {SKILL_DIR}/scripts/version-check.py record off」；- 無論查到什麼，以實際結果收尾：
python3 {SKILL_DIR}/scripts/version-check.py record ok（查到了）或record failed（斷網/沙箱禁網，7 天後再試）。
是否更新由使用者決定，不自動執行更新，不下載任何檔案。
meta 文檔載入時序（階段 × 必讀）
規範層 references/meta/ 不要求一次全讀——按所處階段載入，規劃類工作不載入執行期文檔：
元規則：
rules-priority.md與philosophy.md是全階段裁決層，衝突時優先於各階段文檔；lifecycle.md是全生命週期總圖（七段×載體×檢查點）；theory-router.md是理論判斷輔助層（自動判階 + 段×理論模型包 + 觸發條件 + 複合規則），任何段需要用理論模型推理/歸因/說服時按需載入，其詳盡層design-theory-models.md只按錨點查、不全讀；llm-behavior.md在產出 > 2 屏的長文檔時必讀。
通用
- 不確定用哪個？ 先
design-md。沒有 DESIGN.md 就無法產出可靠的draw-md硬 token，更無法進行框架適配。 - 完整流程鏈路（每步產出 = 下步輸入）：
design-md（→.maliang/DESIGN.md） →draw-md（→.maliang/ui-markdown/.md） →preview（→.maliang/preview/preview_.html） →critique（→評分快照） →draw-harmony/draw-flutter/draw-element（→框架程式碼）；迭代經redesign/ui-graph回流 decisions 帳本。 - 維度規範（色 / 字 / 圖 / 距 / 角 / 線 / 佈局 / 對齊 / 海拔）在
references/dimensions/下（含 color-palettes 調色板庫、design-systems 參考設計系統、glass-effect/glass-advanced 液態玻璃配方、texture 紋理預算（一頁一紋理族/透明度 token 化）、elevation 表面海拔、alignment 對齊軸/同排等高/凸起關係、h5-frame H5 手機專屬頁容器契約）；設計原則在references/meta/principles.md，十三個子命令共享參考，不在本路由器重複。桌面頁到手機上的六條機械故障見references/meta/mobile-floor.md。 - 模板牆在
references/templates/：14 種設計語言（液態玻璃/M3 Expressive/Fluent 2/Bento/瑞士編輯/OLED 暗色/數據儀表板等） + 整頁模式（編輯分欄/縱深長廊/Dashboard 風格集/行動端五式/滾動圖帶/AI 工作台） + 落地頁編排 + 性格方向卡；選型走 README 四步路由 + variation-engine 七軸組合 + 跨次構建記憶（build-log + CSS 蓋章，≥5 軸相同即重選）。 - 交付物骨架模板在
template/：DESIGN.md 骨架 / ui-markdown 頁面骨架 / IP prompt 契約 / A11y 實測記錄，複製填充用——骨架字面型態的唯一 canonical 在各檔案，填法與校驗規則在對應子命令文檔；與模板牆分工（選型參考 vs 落盤起點）見template/README.md。 - 術語庫在
references/glossary.md。
參考資料
以下為 SKILL.md 中引用的參考資源（部分路徑）：
- 命令文檔：
references/commands/design-md.md、references/commands/redesign.md、references/commands/component.md、references/commands/draw-md.md、references/commands/explore.md、references/commands/preview.md、references/commands/critique.md、references/commands/draw-harmony.md、references/commands/draw-flutter.md、references/commands/draw-element.md、references/commands/ui-graph.md、references/commands/ip.md、references/commands/ip-handbook.md - Meta 文檔：
references/meta/lifecycle.md、references/meta/product-reasoning.md、references/meta/philosophy.md、references/meta/principles.md、references/meta/ux-laws.md、references/meta/token-provenance.md、references/meta/dials.md、references/meta/spec-schema.md、references/meta/analytics-events.md、references/meta/content-guide.md、references/meta/data-floor.md、references/meta/workbench-structures.md、references/meta/ai-tells.md、references/meta/rules-priority.md、references/meta/accessibility.md、references/meta/surface-modes.md、references/meta/token.md、references/meta/ux-rules.md、references/meta/numbered-gates.md、references/meta/performance.md、references/meta/hardening.md、references/meta/day-two-blacklist.md、references/meta/polish-craft.md、references/meta/llm-behavior.md、references/meta/mobile-floor.md、references/meta/app-screen-floor.md、references/meta/theory-router.md、references/meta/design-theory-models.md、references/meta/web-interface-guidelines.md、references/meta/visual-assets.md、references/meta/copy-strategy.md、references/meta/alignment.md - 維度文檔：
references/dimensions/（含 color-palettes、design-systems、glass-effect、glass-advanced、texture、elevation、alignment、h5-frame） - 模板：
references/templates/INDEX.md、references/templates/variation-engine.md、template/README.md - 框架選型：
references/framework/INDEX.md - 腳本：
scripts/version-check.py、scripts/style-ledger.py、scripts/ui-graph.py