ux-patterns

UX パターン

概要

思い込みで UI を生成してはいけません。まず、文書化されたパターンを必ず確認してください。

基本原則： すべての UI 要素は、文書化された UX パターンまたはデザインシステムのコンポーネントを参照できる必要があります。参照元を示せないなら、それは推測です。そして推測からは、素人同然の成果しか生まれません。

例外なし。回避策なし。近道なし。

最優先の指針

NO UI CODE WITHOUT A UX REFERENCE FIRST

適用できるパターンを特定していない場合、コンポーネントを書くことは認められません。参照元なしで UI コードを書いてしまった場合は、削除してください。参照元を確認して、最初からやり直してください。

言い訳は認められません：

• トークンなしで「手早くプロトタイプを作る」ことは禁止です
• 「あとでスタイルを整えればいい」と先送りすることは禁止です
• 「とりあえず動かすため」に任意のピクセル値を使うことは禁止です
• 「些細な」コンポーネントだからといって、導入プロトコルを省略することは禁止です
• 「急ごしらえ」の UI は必ずリリースされます。必ずです。

使用する場面

常に使用します：

• Web アプリケーション（SaaS、ダッシュボード、管理パネル）
• ランディングページやマーケティングサイト
• ゲームのインターフェース（メニュー、HUD、インベントリ、ショップ）
• CLI インターフェース（出力の書式設定、対話型プロンプト）
• モバイルアプリケーション
• コンポーネントライブラリ
• 人が視覚的に認識するあらゆる出力

以下も含みます：

• 「ただのプロトタイプです」（プロトタイプは製品になります）
• 「誰にも見られません」（必ず誰かが見ます）
• 「あとで整えます」（整えません）

導入プロトコル

digraph entry_protocol {
    rankdir=TB;
    start [label="Need to author UI code", shape=doublecircle];
    identify [label="IDENTIFY\nWhat UI pattern is this?", shape=diamond];
    reference [label="REFERENCE\nConsult pattern in\npattern-libraries.md", shape=box];
    tokens [label="TOKENS\nDesign tokens established?", shape=diamond];
    define_tokens [label="Establish tokens from\ndesign-tokens.md", shape=box];
    adopt [label="ADOPT\nApply reference spacing,\ntypography, layout", shape=box];
    adapt [label="ADAPT\nModify only what the\nspecific context demands", shape=box];
    write [label="Author UI code", shape=doublecircle];
    halt [label="HALT\nYou are guessing", shape=octagon, style=filled, fillcolor=red, fontcolor=white];

    start -> identify;
    identify -> reference [label="identified"];
    identify -> halt [label="unknown\npattern"];
    reference -> tokens;
    tokens -> adopt [label="yes"];
    tokens -> define_tokens [label="no"];
    define_tokens -> adopt;
    adopt -> adapt;
    adapt -> write;
    halt -> identify [label="research\nfirst"];
}

UI コードを少しでも書く前に、すべてのフェーズを実行してください：

1. 特定 -- これはどの UI パターンですか？（ナビゲーション、フォーム、データテーブル、モーダル、カードなど）
2. 参照 -- pattern-libraries.md でパターンを確認します
3. トークン -- このプロジェクトでデザイントークンが定義されていることを確認します（design-tokens.md を参照）
4. 採用 -- 参照元の余白、タイポグラフィ、レイアウト、インタラクションのパターンを適用します
5. 適応 -- 特定のコンテキストで必要な箇所だけを変更します
6. 作成 -- その後に初めて UI コードを書きます

フェーズを1つでも省略すれば、それは推測です。削除して、最初からやり直してください。

デザイントークンの要件

すべての UI プロジェクトで、コンポーネントコードを書く前に以下のトークンを定義する必要があります：

トークンのカテゴリ	定義する内容	重要な理由
色	プライマリ、セカンダリ、ニュートラルのスケール（50-950）、セマンティックカラー（エラー、成功、警告、情報）	「無作為な色」症候群を防ぎます
タイポグラフィ	フォントファミリー（最大2つ）、サイズスケール（xs から 4xl）、ウェイトスケール（normal、medium、semibold、bold）、行の高さ	視覚的な品質の95％はタイポグラフィで決まります
余白	基本単位（4px または 8px）、スケール（xs：4px から 3xl：64px）	体系的な余白が、プロフェッショナルな印象を生み出します
角丸	スケール：none、sm、md、lg、full	コンポーネントの形状に一貫性を持たせます
シャドウ	3～4段階のエレベーション（sm、md、lg、xl）	明確な奥行きの階層を確立します
ブレークポイント	最低限、sm（640px）、md（768px）、lg（1024px）、xl（1280px）	最初からレスポンシブな動作を実現します
Z-index	スケール：dropdown（10）、sticky（20）、modal（30）、popover（40）、toast（50）	Z-index の競合を防ぎます

プロジェクトの分類に応じた、すぐに使えるトークンテンプレートについては、design-tokens.md を確認してください。

パターンの検索方法

digraph pattern_selection {
    rankdir=TB;
    what [label="What am I building?", shape=diamond];
    saas [label="SaaS / Dashboard /\nAdmin Panel?", shape=diamond];
    game [label="Game Interface?", shape=diamond];
    marketing [label="Landing Page /\nMarketing Site?", shape=diamond];
    devtool [label="Developer Tool /\nCLI?", shape=diamond];
    ecommerce [label="Online Store?", shape=diamond];

    use_saas [label="SaaS patterns\n(data-dense, navigation-heavy)", shape=box];
    use_game [label="Game UI patterns\n(dark theme, bold, animated)", shape=box];
    use_marketing [label="Marketing patterns\n(conversion-focused, hero sections)", shape=box];
    use_devtool [label="Dev tool patterns\n(monospace, high contrast, minimal)", shape=box];
    use_ecommerce [label="E-commerce patterns\n(product-focused, trust signals)", shape=box];
    use_general [label="General UI patterns\n(clean, accessible, standard)", shape=box];

    lookup [label="Consult specific component\nin pattern-libraries.md", shape=box];

    what -> saas;
    saas -> use_saas [label="yes"];
    saas -> game [label="no"];
    game -> use_game [label="yes"];
    game -> marketing [label="no"];
    marketing -> use_marketing [label="yes"];
    marketing -> devtool [label="no"];
    devtool -> use_devtool [label="yes"];
    devtool -> ecommerce [label="no"];
    ecommerce -> use_ecommerce [label="yes"];
    ecommerce -> use_general [label="no"];

    use_saas -> lookup;
    use_game -> lookup;
    use_marketing -> lookup;
    use_devtool -> lookup;
    use_ecommerce -> lookup;
    use_general -> lookup;
}

プロジェクトの分類とパターンのカテゴリ別に整理された完全なリファレンスについては、pattern-libraries.md を確認してください。

アマチュア UI の特徴（アンチパターン）

これらは、AI が生成したアマチュア UI に見られる紛れもない特徴です。いずれも、参考資料を確認していないことを示しています。

アンチパターン	アマチュアっぽく見える理由	プロが行うこと
不規則な間隔	グリッドシステムがなく、隙間がランダムに感じられ、隣り合う要素間でパディングが異なります	スペーシングトークンを使用します。すべての間隔をトークンの値にします。
場当たり的な色	コンポーネントごとに色を選び、統一されたパレットがなく、異なる色相が多すぎます	まず完全なパレットを定義します。すべての色をトークンで指定します。
整理されていないタイポグラフィ	サイズが不揃いで、行の高さに一貫性がなく、ウェイトが多すぎて、階層が弱いです	フォントファミリーは最大 2 種類にします。文字サイズのスケールに従います。見出しの階層を意図的に設計します。
平坦な視覚的階層	すべて同じサイズとウェイトで、目を引く要素がなく、情報を読み取るのが困難です	主要な操作を視覚的に目立たせます。副次的な要素は控えめにします。サイズ、ウェイト、色、コントラストに変化をつけます。
角の不統一	角が鋭いものと丸いものが混在し、似た要素でも境界線の幅が異なります	角丸のスケールを定義します。同じ種類のコンポーネントには同じ角丸を使います。
プレースホルダーコンテンツ	「Lorem ipsum」、「ユーザー名」、「ここに説明」、「項目 1」などを使用します	実際のデータの形や長さを示す、現実的なコンテンツを使用します。
インタラクション状態の欠落	ボタンがカーソルに反応せず、リンクが分かりにくく、キーボードフォーカスリングがありません	すべてのインタラクティブ要素にインタラクション状態（ホバー、フォーカス、アクティブ、無効）を定義します。
すべてを中央揃えにするレイアウト	AI のデフォルトの挙動として、すべてのテキスト、コンテンツ、セクションを中央揃えにします	適切なグリッドを使った左揃えのレイアウトにします。意図がある場合にのみ中央揃えにします（ヒーロー見出し、CTA など）。
均一なテキストの壁	すべての段落、ラベル、説明で同じフォントサイズとウェイトを使います	ウェイトとサイズに変化をつけます。ラベルは小さく、軽めにします。見出しは大きく、太くします。説明文には控えめな色を使います。
正常系以外の状態の欠落	「データあり」の UI しかなく、スケルトンローダーもエラーメッセージもありません	すべての状態を設計します。空、読み込み中（スケルトン）、エラー、一部表示、成功を含めます。
コンポーネントが大きすぎる	ボタンが高すぎ、入力欄が広すぎ、カードがビューポート全体を占めます	標準的なサイズを使用します。ボタンの高さは 36-44px、入力欄は 36-40px にします。カードには最大幅を設定します。
余白のリズムがない	コンテンツが詰め込まれていたり、広すぎる空間の中に浮いていたりします	セクションの垂直方向のリズムを統一します。関連する項目は近くに配置し、関連しない項目との間には明確な間隔を設けます。
不要なエフェクト	無作為なグラデーション、あらゆる要素へのシャドウ、不要なアニメーションを使います	エフェクトには目的を持たせます。シャドウは高さを示し、グラデーションは控えめにします。アニメーションは機能的な目的に使います。
端数のない間隔	システムを使わず、10px、20px、30px を使用します	4px または 8px を基本単位にします。間隔の値は 4、8、12、16、24、32、48、64 にします。

コンポーネント検証チェックリスト

コンポーネントを作成する前に、すべての項目を確認します。

• このプロジェクトのデザイントークン（色、タイポグラフィ、スペーシング、角丸、シャドウ）が確立されている
• pattern-libraries.md からパターンを特定している
• スペーシングにトークンスケールを使用している（任意の px 値を使用していない）
• タイポグラフィに文字サイズのスケールを使用している（任意の font-size を使用していない）
• 定義済みのパレットから色を選んでいる（16 進数のリテラルを使用していない）
• 定義済みのスケールから角丸を選んでいる
• すべてのインタラクティブ要素にホバー／フォーカス／アクティブ／無効状態を定義している
• 少なくともモバイルとデスクトップでのレスポンシブな挙動を指定している
• 現実的なコンテンツを使用している（プレースホルダーテキストを使用していない）
• アクセシビリティを確認している：コントラスト比（本文テキストは 4.5:1、大きなテキストは 3:1）、aria ラベル、キーボード操作
• 空の状態を設計している
• 読み込み状態を設計している（スピナーよりスケルトンを推奨）
• エラー状態を設計している

すべての項目を満たせませんか？コンポーネントを作成する準備ができていません。

認知の罠

合理化	真実
「単なるプロトタイプです」	プロトタイプは製品になります。プロフェッショナルなプロトタイプでもトークンを使います。
「スタイリングは後で直します」	直しません。「後で」は決して訪れません。その後のタスクはすべて優先されます。
「ユーザーはデザイン要件を指定していません」	要件がないからといって、推測してよいわけではありません。デフォルトでトークンを適用してください。
「まずロジックを動かす必要があります」	ロジックとプレゼンテーションは別々のフェーズではありません。トークンの設定には 5 分しかかかりません。
「このコンポーネントにはそこまで必要ありません」	シンプルなコンポーネントこそ、不整合が根付く場所です。トークンを使わないボタンは、それが使われるすべてのページに悪影響を及ぼします。
「デザインシステムは後で導入します」	今トークンを使わなければ、後でデザインシステムの導入に苦労します。トークンを使えば、導入は簡単です。
「ハードコードした色を 1 つ使うくらいなら問題ありません」	1 つが 10 個になります。そして、偶然できた色のパレットができあがります。
「AI なら見た目をそれなりに仕上げられます」	「それなり」は、アマチュアの UI を定義する特徴です。プロかアマチュアか、選んでください。

ガードレール -- HALT と参照

次のいずれかに当てはまる場合：

• 定義済みのトークン値ではない color: #3b82f6 を書いている
• スペーシングトークンの代わりに padding: 10px を使っている
• タイプスケールにないフォントサイズを選んでいる
• pattern-libraries.md を参照せずにコンポーネントを作っている
• ホバー／フォーカス状態を「今は」対応しないことにしている
• 「Lorem ipsum」や「例文」を使っている
• 「問題なさそうだから」という理由ですべてを中央揃えにしている
• 「目立たせるため」にグラデーションや影を加えている
• デザイントークンを設定せずに CSS を書いている
• フォームパターンを参照せずにフォームを作っている
• ダッシュボードパターンを参照せずにダッシュボードを作っている

どれか 1 つでも当てはまる場合は、HALT。取り除いてください。エントリープロトコルに戻ってください。

統合

呼び出し元：

• godmode:intent-discovery -- UI に関わるデザインでは、このスキルを呼び出してください
• godmode:task-planning -- UI 作業を含む計画では、このスキルを参照してください
• godmode:delegated-execution -- UI 実装のサブエージェントは、このスキルを必ず使用してください

補完的なスキル：

• godmode:ui-engineering -- こちらが参照システムを提供し、もう一方が実装パターンを提供します
• godmode:design-integration -- 既存のデザインシステムを導入する場合に使用します

関連ファイル：

• pattern-libraries.md -- プロジェクトの分類とカテゴリ別の完全なパターンリファレンス
• design-tokens.md -- プロジェクトの分類別にすぐ使えるトークンテンプレート