Communitygithub.com

ux-md-generator

UX.md v1 構造的UI/UX仕様書の生成、抽出、監査、プレビュー、差分比較、検証を行います。アプリケーションの骨格(アプリシェル、空間予算計算、スクロールとz-indexの所有権、ページアーキタイプ、ルート到達可能性グラフ、URL状態永続化、オーバーレイ判定マトリックス、4状態ビュー契約、フォーム・ミューテーションエルゴノミクス、必須レイアウトプリミティブ)を定義し、DESIGN.mdとAGENTS.mdの構造的補完役として機能します。フロントエンド/UIプロジェクトの初期化時、リファレンス製品からのUXパターン抽出時、既存コードベースのレイアウトドリフト監査時、または新しいルート・ビューの追加時に使用してください。

ux-md-generator とは?

UX.md Generator and Structural Auditor (v1) は、AIエージェントが一貫性のあるUI/UX構造を維持できるように設計されたスキルです。このスキルは、DESIGN.md(ビジュアルトークン)とAGENTS.md(エージェント設定)の中間に位置する構造的仕様書として機能し、セッション間でのレイアウトのドリフトや矛盾を防ぎます。ゼロ依存のNode.jsスクリプト6本を同梱し、抽出→生成→検証の3フェーズパイプラインを実行。グリーンフィールドプロジェクトの初期化(合成モード)、既存製品からのUX逆引き(抽出モード)、コードベースの構造ドリフト検出(監査モード)、新機能追加時のルート同期(進化モード)の4つの動作モードを備えています。特に、12セクションからなるUX.mdの生成と、16の構造的検証ルールによる自動リンティングが特徴で、AIエージェントが具体的な数値(ビューポート予算、z-indexスケール、タッチターゲットサイズなど)に基づいてUIを構築するための契約を提供します。対応プラットフォームは、Webアプリ、モバイルネイティブ、デスクトップアプリ、ターミナルTUIで、Linear、ChatGPT Canvas、Stripe Dashboardなど主要なアーキタイプのプリセットも用意されています。

対応~Claude Code~Codex CLI~Cursor
npx skills add https://github.com/SolidStateNetwork/ux.md/tree/main/skills/ux-md-generator

お気に入りのAIに質問する

このエージェントスキルを事前に読み込んだ状態で新しいチャットを開きます。

ドキュメント

UX.md ジェネレーター & 構造監査ツール (v1)

概要

DESIGN.md が視覚トークン(色、タイポグラフィ、半径、シャドウ、スペーシングスケール)を指定するのに対し、UX.md はアプリケーションの構造的骨格とインタラクションルールを指定します。

UX.mdがないと、AIコーディングエージェントはセッションをまたいでドリフトします。つまり、コンテナ幅を混在させたり、プライマリCTAを移動したり、モーダルとドロワーを恣意的に切り替えたり、空状態やエラー状態を省略したり、F5 リフレッシュでフィルター状態を失ったり、デッドエンドルートを導入したりします。

このスキルは、scripts/ 内の6つのゼロ依存Node.jsスクリプトをバックエンドとする3フェーズパイプラインを使用して、4つのモードで動作します。


同梱CLIスクリプト

スクリプト目的使用例
scripts/extract-ux.mjspackage.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.mjs16の決定論的構造ルールと --check-code リンタールール(ルートパリティ、プリミティブ、デッドハンドラー、不正なz-indexなど)を実行node .agents/skills/ux-md-generator/scripts/validate-ux.mjs UX.md --strict --check-code
scripts/scaffold-ux.mjsUX.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.mjs2つの 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 でパリティを検証します。

3フェーズ生成パイプライン

フェーズ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 "<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永続化(Mermaid flowchart 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: 相互監査とマシン検証

  1. 生成された UX.md を resources/quality-checklist.md([UX-01] から [UX-16])に対して監査します。
  2. 自動リンスクリプトを実行します。
    node .agents/skills/ux-md-generator/scripts/validate-ux.mjs UX.md --strict --check-code
    
  3. 報告された error または warning の結果をすべて解決し、バリデーターが 0 errors で終了するまで再実行します。

関連スキル