UX.md 生成器與結構審計工具 (v1)
概覽
雖然 DESIGN.md 指定了視覺標記(顏色、字體、圓角、陰影、間距比例),UX.md 則指定了應用程式的結構骨架和互動規則。
沒有 UX.md,AI 編碼代理會在會話之間漂移:混合容器寬度、移動主要 CTA、在模態框和抽屜之間任意切換、遺漏空狀態或錯誤狀態、在 F5 刷新時丟失篩選狀態,以及引入死胡同路徑。
此工具透過四種操作模式運作,使用由 scripts/ 中六個零依賴項 Node.js 腳本支援的三階段管線。
綑綁的 CLI 腳本
| 腳本 | 用途 | 使用範例 |
|---|---|---|
scripts/extract-ux.mjs | 掃描 package.json、AGENTS.md、DESIGN.md 和原始碼路徑 (src/app、src/pages) 成為結構化 JSON | node .agents/skills/ux-md-generator/scripts/extract-ux.mjs . --output ux-scan.json |
scripts/generate-ux.mjs | 從原型、產品預設 (--preset linear) 或 ux-scan.json 生成包含 12 個章節的 UX.md | node .agents/skills/ux-md-generator/scripts/generate-ux.mjs --preset linear --project "Acme" --output UX.md |
scripts/validate-ux.mjs | 執行 16 項確定性結構與 --check-code linter 規則(路徑一致性、原語、無效處理器、異常 z-index) | node .agents/skills/ux-md-generator/scripts/validate-ux.mjs UX.md --strict --check-code |
scripts/scaffold-ux.mjs | 從 UX.md 生成 ux-contract.css 自訂屬性和 React/TypeScript 佈局原語(AppShell.tsx、PageHeader.tsx、PageSection.tsx、DataStateBoundary.tsx) | node .agents/skills/ux-md-generator/scripts/scaffold-ux.mjs UX.md --out-dir src/components/ux |
scripts/preview-ux.mjs | 生成獨立的響應式 ux-preview.html 互動式線框模擬器 | node .agents/skills/ux-md-generator/scripts/preview-ux.mjs UX.md --output ux-preview.html |
scripts/diff-ux.mjs | 比較兩個 UX.md 檔案的路徑、原型、預算或閾值回歸 | node .agents/skills/ux-md-generator/scripts/diff-ux.mjs UX.old.md UX.md --json |
操作模式
- 綜合(全新專案 /
init): 執行extract-ux.mjs+generate-ux.mjs從專案上下文和DESIGN.md生成初始UX.md,然後自訂路徑、原型和領域規則。 - 從參考產品提取(參考產品或 URL): 從指定的參考產品(例如 Linear、ChatGPT Canvas、Stripe Dashboard、Shopify 或 Supabase)提取空間外殼、互動規則、鍵盤快捷鍵和頁面原型。
- 審計與逆向工程(現有程式碼庫):
執行
extract-ux.mjs以發現現有路徑(src/app/**、src/pages/**、src/routes/**),檢測結構漂移,並生成統一的UX.md。 - 演進(功能新增 / 路徑同步):
每當新增頁面或工作流程時,更新第 3 節(頁面原型)和第 4 節(導航、路徑圖與 URL 持久化),並透過
validate-ux.mjs UX.md --check-code驗證一致性。
三階段生成管線
階段 1:確定性提取與原型分類
- 執行
node .agents/skills/ux-md-generator/scripts/extract-ux.mjs .(或直接檢查package.json、AGENTS.md和DESIGN.md)來檢測目標執行時期、認證邊界、現有路徑和DESIGN.md的斷點。 - 載入 resources/archetype-taxonomy.md 並確認:
platform_profile:web-app|mobile-native|desktop-app|terminal-tuiarchetype:b2b-saas-workspace|ai-chat-canvas|analytics-dashboard|ecommerce-storefront|developer-tool
- 可選擇透過以下方式預先設定
UX.md:node .agents/skills/ux-md-generator/scripts/generate-ux.mjs --archetype <archetype> --project "<專案名稱>" --output UX.md
階段 2:領域特定 12 節綜合
載入 resources/ux-md-format.md、resources/layout-primitives.md 和 resources/writing-style-guide.md。在儲存庫根目錄自訂 UX.md,包含:
- YAML frontmatter: 完整配置(
spec_version: "1.0"、shell_budget、z_index_scale、thresholds、layout_primitives)。 - 章節
0到11按順序排列:## 0. 產品與領域拓樸## 1. 空間架構與應用程式外殼(ASCII 線框與視口預算表)## 2. 滾動、視口與 Z-Index 契約## 3. 核心頁面原型(藍圖)(使用### 原型:<原型ID>標題)## 4. 導航、路徑圖與 URL 持久化(Mermaidflowchart LR、路徑可達性表和狀態持久化矩陣)## 5. 覆蓋層與反饋決策矩陣(欄位計數和px閾值)## 6. 強制檢視狀態(四狀態矩陣)(Loading、Empty、Error、Populated)## 7. 變更操作、表單與權限人體工學(isDirty保護、2 層破壞性規則、3 向權限閘門)## 8. 真實數據壓力、密度與截斷(單一列表縮放模式、min-w-0 truncate、-空白儲存格佔位符號、tabular-nums)## 9. 響應式重排與輸入編排(摺疊順序、>= 44x44px觸控目標搭配>= 8px間距、懸停互動的點擊等效操作、安全區域滾動內距)## 10. 強制佈局原語(程式碼契約)(<AppShell>、<PageHeader>、<PageSection>、<DataStateBoundary>)## 11. 專案注意事項、禁止事項與代理提示指南
寫作限制:
- 零模糊形容詞: 不要寫 「小表單」、「乾淨佈局」、「慢請求」 或 「直觀導航」 而不帶明確數字(
<= 4 個欄位、1280px、>= 150ms)。請參閱 resources/anti-patterns.md。 - 零死結: 第 4 節中的每個路徑都必須引用第 3 節中的一個有效的
<原型ID>,並定義「進入觸發器」和「退出 / 取消回退」。 - 強制佈局原語: 確保所有路徑都使用第 10 節中定義的 4 個強制佈局原語(
<AppShell>、<PageHeader>、<PageSection>、<DataStateBoundary>)。
階段 3:跨審計與機器驗證
- 根據 resources/quality-checklist.md(
[UX-01]到[UX-16])審計生成的UX.md。 - 執行自動化 linter 腳本:
node .agents/skills/ux-md-generator/scripts/validate-ux.mjs UX.md --strict --check-code - 解決所有報告的
error或warning發現,並重新執行,直到驗證器以0 個錯誤退出。