Communitygithub.com

UX.md 生成器與結構審計工具

生成、提取、審計、預覽、比較和驗證 UX.md v1 結構化 UI/UX 規格。定義應用程式骨架(應用程式外殼、空間預算計算、滾動與 Z-Index 所有權、頁面原型、路徑可達性圖表、URL 狀態持久化、覆蓋層決策矩陣、四狀態視圖契約、表單與變更操作人體工學,以及強制佈局原語),作為 DESIGN.md 和 AGENTS.md 的結構化補充。在初始化前端/UI 專案、從參考產品提取 UX 模式、審計現有程式碼庫的佈局漂移,或新增路徑與視圖時使用。

UX.md 生成器與結構審計工具 是什麼?

這是一個用於生成、提取、審計、預覽、比較和驗證 UX.md v1 結構化規格的專業工具。它專注於定義應用程式的結構骨架和互動規則,以補充 DESIGN.md(定義視覺標記)和 AGENTS.md(定義行為)之間的空白。此工具支援多種作業模式:在全新專案中從頭合成 UX.md、從參考產品(如 Linear、ChatGPT Canvas)提取 UX 模式、審計現有程式碼庫以檢測結構漂移,以及在新增功能或路徑時逐步演進規格。它包含一套六個無依賴項的 Node.js 腳本(extract-ux.mjs、generate-ux.mjs、validate-ux.mjs、scaffold-ux.mjs、preview-ux.mjs、diff-ux.mjs),並遵循嚴格的三階段管線:確定性提取與原型分類、領域特定 12 節綜合(涵蓋空間架構、滾動與 Z-Index 契約、頁面原型藍圖、導航圖、覆蓋層決策、四狀態矩陣、表單人體工學、響應式重排、強制佈局原語等),以及跨審計與機器驗證。寫作限制要求零模糊形容詞、零死結路徑,並強制使用佈局原語。此工具也支援透過 validate-ux.mjs --check-code 進行自動化 lint 檢查,以確保結構完整性。

相容平台~Claude Code~Codex CLI~Cursor
npx skills add https://github.com/SolidStateNetwork/ux.md/tree/main/skills/ux-md-generator

在你喜歡的 AI 中提問

開啟一個已預先載入此 Agent Skill 的新對話。

說明文件

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) 成為結構化 JSONnode .agents/skills/ux-md-generator/scripts/extract-ux.mjs . --output ux-scan.json
scripts/generate-ux.mjs從原型、產品預設 (--preset linear) 或 ux-scan.json 生成包含 12 個章節的 UX.mdnode .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

操作模式

  1. 綜合(全新專案 / init): 執行 extract-ux.mjs + generate-ux.mjs 從專案上下文和 DESIGN.md 生成初始 UX.md,然後自訂路徑、原型和領域規則。
  2. 從參考產品提取(參考產品或 URL): 從指定的參考產品(例如 Linear、ChatGPT Canvas、Stripe Dashboard、Shopify 或 Supabase)提取空間外殼、互動規則、鍵盤快捷鍵和頁面原型。
  3. 審計與逆向工程(現有程式碼庫): 執行 extract-ux.mjs 以發現現有路徑(src/app/**、src/pages/**、src/routes/**),檢測結構漂移,並生成統一的 UX.md。
  4. 演進(功能新增 / 路徑同步): 每當新增頁面或工作流程時,更新第 3 節(頁面原型)和第 4 節(導航、路徑圖與 URL 持久化),並透過 validate-ux.mjs UX.md --check-code 驗證一致性。

三階段生成管線

階段 1:確定性提取與原型分類

  1. 執行 node .agents/skills/ux-md-generator/scripts/extract-ux.mjs .(或直接檢查 package.json、AGENTS.md 和 DESIGN.md)來檢測目標執行時期、認證邊界、現有路徑和 DESIGN.md 的斷點。
  2. 載入 resources/archetype-taxonomy.md 並確認:
    • platform_profile:web-app | mobile-native | desktop-app | terminal-tui
    • archetype:b2b-saas-workspace | ai-chat-canvas | analytics-dashboard | ecommerce-storefront | developer-tool
  3. 可選擇透過以下方式預先設定 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 持久化(Mermaid flowchart 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:跨審計與機器驗證

  1. 根據 resources/quality-checklist.md([UX-01] 到 [UX-16])審計生成的 UX.md。
  2. 執行自動化 linter 腳本:
    node .agents/skills/ux-md-generator/scripts/validate-ux.mjs UX.md --strict --check-code
    
  3. 解決所有報告的 error 或 warning 發現,並重新執行,直到驗證器以 0 個錯誤 退出。

相關技能