UX.md ジェネレーター & 構造監査ツール (v1)
概要
DESIGN.md が視覚トークン(色、タイポグラフィ、半径、シャドウ、スペーシングスケール)を指定するのに対し、UX.md はアプリケーションの構造的骨格とインタラクションルールを指定します。
UX.mdがないと、AIコーディングエージェントはセッションをまたいでドリフトします。つまり、コンテナ幅を混在させたり、プライマリCTAを移動したり、モーダルとドロワーを恣意的に切り替えたり、空状態やエラー状態を省略したり、F5 リフレッシュでフィルター状態を失ったり、デッドエンドルートを導入したりします。
このスキルは、scripts/ 内の6つのゼロ依存Node.jsスクリプトをバックエンドとする3フェーズパイプラインを使用して、4つのモードで動作します。
同梱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 リンタールール(ルートパリティ、プリミティブ、デッドハンドラー、不正な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 | 2つの 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でパリティを検証します。
3フェーズ生成パイプライン
フェーズ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 "<Project Name>" --output UX.md
フェーズ2: ドメイン固有の12セクション合成
resources/ux-md-format.md、resources/layout-primitives.md、resources/writing-style-guide.md を読み込みます。リポジトリルートに UX.md を調整して配置します。
- YAMLフロントマター: 完全な設定(
spec_version: "1.0"、shell_budget、z_index_scale、thresholds、layout_primitives)。 - セクション
0から11を順番に:## 0. 製品・ドメイントポロジー## 1. 空間アーキテクチャ & アプリシェル(ASCIIワイヤーフレームとビューポート予算テーブル)## 2. スクロール、ビューポート & Z-Index契約## 3. コアページアーキタイプ(ブループリント)(### アーキタイプ: <ArchetypeID>見出しを使用)## 4. ナビゲーション、ルートグラフ & URL永続化(Mermaidflowchart LR、ルート到達可能性テーブル、状態永続化マトリックス)## 5. オーバーレイ & フィードバック判定マトリックス(フィールド数とpxしきい値)## 6. 必須ビューステート(4状態マトリックス)(Loading、Empty、Error、Populated)## 7. ミューテーション、フォーム & 権限エルゴノミクス(isDirtyガード、2層破壊的ルール、3方向権限ゲート)## 8. 実データストレス、密度 & トランケーション(単一リストスケーリングモード、min-w-0 truncate、-空セルプレースホルダートークン、tabular-nums)## 9. レスポンシブリフロー & 入力コレオグラフィー(折りたたみ順序、>= 44x44pxタッチターゲットと>= 8pxギャップ、ホバーインタラクションのタップ相当、セーフエリアスクロールパディング)## 10. 必須レイアウトプリミティブ(コード契約)(<AppShell>、<PageHeader>、<PageSection>、<DataStateBoundary>)## 11. プロジェクトのDo's、Don'ts、エージェントプロンプトガイド
記述制約:
- 曖昧な形容詞ゼロ: 明示的な数値(
<= 4 fields、1280px、>= 150ms)なしに「小さなフォーム」「きれいなレイアウト」「遅いリクエスト」「直感的なナビゲーション」と記述しないでください。resources/anti-patterns.md を参照。 - デッドエンドゼロ: セクション4のすべてのルートは、セクション3の有効な
<ArchetypeID>を参照し、Entry TriggerとExit / Cancel Fallbackの両方を定義する必要があります。 - レイアウトプリミティブの強制: すべてのルートが、セクション10で定義された4つの必須レイアウトプリミティブ(
<AppShell>、<PageHeader>、<PageSection>、<DataStateBoundary>)を構成していることを確認します。
フェーズ3: 相互監査とマシン検証
- 生成された
UX.mdを resources/quality-checklist.md([UX-01]から[UX-16])に対して監査します。 - 自動リンスクリプトを実行します。
node .agents/skills/ux-md-generator/scripts/validate-ux.mjs UX.md --strict --check-code - 報告された
errorまたはwarningの結果をすべて解決し、バリデーターが0 errorsで終了するまで再実行します。