ui-visual-composition

UI のビジュアル構成

目的

階層、余白、タイポグラフィ、色、奥行き、画像、仕上げの細部を通じて、AI エージェントが洗練されたビジュアル UI を作成し、評価できるよう支援します。ビジュアルデザインを機能的なコミュニケーションとして捉えます。インターフェースは、何が重要か、何が関連しているか、何を操作できるか、何が変化したかをユーザーが理解できるようにする必要があります。

このスキルでは、ビジュアルデザインの品質、レイアウト構成、タイポグラフィ、カラーシステム、奥行き、画像、仕上げ、アクセシビリティ、ビジュアル品質に影響するフロントエンドの実装方法を扱います。ビジュアル構成を決定する場合を除き、詳細な UX リサーチ、情報アーキテクチャ戦略、フロントエンドアーキテクチャは扱いません。

このスキルを使用する場合

ユーザーが UI の評価、再設計、製品ページの改善、フロントエンドのビジュアル実装、デザインシステムのガイダンス、スタイルの仕上げ、レイアウトの調整、タイポグラフィ、カラーパレット、空・エラー・読み込み状態の改善、生成された UI のビジュアル QA を求めている場合に使用します。

また、ビジュアルインターフェースのフロントエンドコードを作成する場合にも使用します。コンポーネント構成、セマンティックなマークアップ、トークン、状態のスタイル、レスポンシブな動作、アクセシビリティの詳細によって、ビジュアルに関する提案が実装後も活かされるかどうかが決まるためです。

このスキルを使用しない場合

ユーザーの主な依頼が、ユーザーリサーチの計画、製品戦略、市場でのポジショニング、分析の計測、バックエンド／フロントエンドアーキテクチャ、パフォーマンスエンジニアリング、ビジュアル表現を伴わないコピーライティング、詳細なインタラクションフロー設計の場合は、主要なフレームワークとして使用しないでください。これらのタスクのビジュアルデザインに関する部分に限って使用します。

恣意的な装飾を正当化するために使用しないでください。ビジュアル上の提案によって階層、理解しやすさ、品質の印象、アクセシビリティ、製品コンテキストとの適合性が向上しない場合は、その提案を取り除いてください。

基本原則

1. シェルではなく、機能から始めます。 ナビゲーションの枠組みやページの構成、装飾を設計する前に、具体的なユーザーのタスクとコンテンツを特定します。
2. 階層は骨組みです。 最も重要なコンテンツや操作に、最も気づきやすくします。色や装飾に頼る前に、サイズ、太さ、コントラスト、余白、配置、順序を活用します。
3. 新しさに目的がない限り、慣れ親しんだパターンを使います。 ユーザーは他の製品で得たメンタルモデルを持ち込むため、ユーザーのブランドや製品の目標から意図的な変更が正当化されない限り、一般的なコントロール、ナビゲーション、フォーム、フィードバックの慣例を維持します。
4. 意味ごとにグループ化します。 近接、共通領域、整列、つながりは、概念上の関係と一致させます。曖昧な余白は、意味も曖昧にします。
5. システムを使って選択肢を絞ります。 場当たり的な値を個別に使うのではなく、タイポグラフィ、余白、色、角丸、境界線、高さのトークンを使用します。
6. タイポグラフィはインターフェースの構造です。 コンテンツと状況に合う書体を選び、読みやすい行の長さ、行の高さ、配置、強調、階層を設定します。
7. 色には安全に意味を持たせます。 色は階層、状態、ブランドを補強するために使いますが、唯一の手がかりにはしません。コントラストを確保し、色覚や視力に制約のあるユーザーのニーズに照らしてテストします。
8. 奥行きでレイヤーを説明します。 影、重なり、境界線、背景の変化は、視覚的なノイズを生み出すのではなく、高さ、グループ化、フォーカス、インタラクションを明確にします。
9. 美しさは受け入れやすさを高めますが、ユーザビリティの欠点を正当化するものではありません。 洗練されたデザインは、ユーザーの許容度や信頼感を高めることがありますが、問題を覆い隠すこともあります。見た目の美しさを評価する前に、明瞭さ、アクセシビリティ、タスクへの適合性を検証します。
10. 必要な複雑さを隠さず、簡素化します。 表示する選択肢を減らし、複雑なタスクを分割します。ただし、ユーザーが判断や復旧に必要とする情報まで抽象化して隠してはいけません。
11. 実際のコンテンツに柔軟に対応できる設計にします。 ユーザーがアップロードした画像、長いラベル、空のデータ、エラー、読み込み中、無効状態、ローカライズによって、レイアウトが崩れないようにします。
12. ユーザー中心の観点からトレードオフを説明します。 推奨事項では、ユーザーの目標、理解しやすさ、アクセシビリティ、システムの一貫性、実装の実現可能性に触れます。

各原則を再利用可能なカードとしてまとめた内容は、references/principle-cards.md を参照してください。

デフォルトの推奨事項

より適切な選択につながるコンテキストがユーザーから示されない限り、これらのデフォルトを使用します。

領域	デフォルト	通常、最適な理由	変更する場合	変更前に確認すること
プロダクト／タスクの焦点	まず、中心となる機能または画面の目的を1つに絞ります	コンテンツやアクションが明確になる前に、アプリの枠組みを設計してしまうのを防げます	ユーザーがグローバルナビゲーション、デザインシステムのシェル、または情報アーキテクチャを明示的に求めている場合	主なタスクと、画面の成功基準を確認します
ビジュアルの方向性	プロフェッショナルで、温かみがあり、控えめで、コンテンツを重視します	多くの生産性、SaaS、ダッシュボード、管理、コマースのインターフェースに適しています	ブランドが遊び心のあるもの、高級感のあるもの、エディトリアル、若年層向け、非常に技術的、またはキャンペーン風の場合	ブランドの個性と参考例を確認します
情報密度	まずは余裕のある間隔にし、意図的な場合にのみ詰めます	余裕のあるレイアウトは、通常、よりすっきりと明瞭に見えます	ダッシュボード、プロ向けツール、トレーディング、オペレーション、またはデータ監視の用途で高密度が必要な場合	情報密度と、すばやく読み取る必要性を確認します
レイアウト戦略	内容幅に合わせたコンテナーでグループを明確にし、デフォルトで画面いっぱいに広げないようにします	大画面での行の長さや視覚的なずれを抑えられます	没入型キャンバス、マップ、メディア、スプレッドシート、タイムライン、またはデータグリッドで全幅が必要な場合	どのコンテンツを一緒に表示しておく必要があるか確認します
グリッド	それ自体を目的とする固定レイアウトではなく、シンプルで柔軟なグリッドとトークン化された間隔を使います	コンテンツを恣意的な列に押し込まずに、配置を整えられます	エディトリアル、マーケティング、またはデータ密度の高いレイアウトで、より強いグリッドロジックが必要な場合	コンテンツの種類とレスポンシブのブレークポイントを確認します
タイポグラフィ	UIにはシステムUIまたは高品質でニュートラルなサンセリフ体を使い、ブランドが求める場合に限り、表現力のあるディスプレイ書体を1つ組み合わせます	読み込みのリスクを抑え、読みやすさを向上できます	エディトリアル／ブランドの制作で、特徴的なタイポグラフィ表現が必要な場合	ブランドのトーンとフォントの制約を確認します
文字のスケール	本文、補足テキスト、ラベル、タイトル、ディスプレイ用の、再利用可能な少数の段階を用意します	階層の不統一を抑えられます	既存のデザインシステムに文字のスケールがある場合	デザインシステムのトークンの参照元を確認します
行の長さ	本文や長文は読みやすい幅に保ち、端から端まで広げないようにします	内容をすばやく把握しやすく、読み心地も向上します	データテーブル、コード、または短いカードで異なる幅が必要な場合	コンテンツの種類が特殊な場合に限り確認します
色	ニュートラルスケール、アクセントスケール、成功／警告／エラー／情報、フォーカス状態を含む、限られたパレットから意味的な役割を定義します	一貫性とアクセシビリティを支えます	ブランドパレットが固定されている場合、またはコンプライアンス／規制上の状態が指定されている場合	ブランドパレットとアクセシビリティの目標を確認します
コントラスト	コントラストを機能要件として扱い、テキスト、アイコン、コントロール、状態を検証します	アクセシビリティに欠けるUIや、信頼性の低いUIを防げます	大きな装飾テキストや、不可欠ではないイラストは対象外です	プロダクトで特定のアクセシビリティ基準が求められるか確認します
奥行き	小規模なエレベーションスケールと、一貫した光源モデルを使います	視覚的な混乱を招かずにレイヤーを作れます	ブランドが意図的にフラット／ブルータリスト、またはスキューモーフィックな場合	奥行きの方向性がブランド上の選択である場合に限り確認します
画像	高品質で用途に合った画像を使い、画像上のテキストはスクリーン、グラデーション、コンテナーで読みやすく保護します	画像はばらつきがあり、可読性を損なうことがあるためです	ユーザーが使用する写真やUGCが固定されている場合	画像の出典と変動性を確認します
境界線	多数の境界線を追加する前に、間隔、背景、影、または控えめな区切り線を使います	境界線はすぐに視覚的なノイズになります	データテーブル、法的フォーム、または項目が密集した設定画面で、明確な区分が必要な場合	情報密度や表形式での正確さが重要か確認します
空の状態	次のアクションにつながる、役立つ空の状態を用意します	空の状態は、体験の一部であり、単なる空白や失敗ではありません	空の状態が起こり得ない場合、または意図的に非表示にする場合	確認は不要です。デフォルトで実装します
モーション	フィードバック、連続性、読み込みのために、控えめで目的のあるモーションを使い、視覚効果の低減設定を尊重します	気を散らさずに明瞭さを高められます	エンターテインメント性が高いプロダクト、またはブランドモーションが重要な差別化要因である場合	モーションの許容度とアクセシビリティ上の制約を確認します
フロントエンド実装	セマンティックHTML、デザイントークン、レスポンシブCSS、視認できるフォーカス状態、キーボード操作、状態ごとのバリエーションを使います	実際のUIでビジュアル品質とアクセシビリティを保てます	プロトタイプが静的で、使い捨ての場合	本番環境の制約や、フレームワーク／デザインシステムのルールがあるか確認します

必須のユーザーへの質問

読みやすいテキスト、十分なコントラスト、明確な階層など、一般的なベストプラクティスについてユーザーに確認を求めないでください。これらはデフォルトで適用してください。

回答によってビジュアルソリューションが大きく変わる場合に限り、焦点を絞った質問をしてください。利用可能な場合は、question ツールまたは同等のツールを使用してください。質問するべき状況の例：

• プロダクトの目標、主要なタスク、対象ユーザー、またはプラットフォームが不明で、推測できない場合。
• ブランドの個性やビジュアルのトーンによって、書体、色、密度、画像、装飾が変わり得る場合。
• ユーザーが現行の UI、スクリーンショット、コード、デザインシステムの制約、または成功基準を提示せずに、デザインの刷新を求めている場合。
• アクセシビリティの目標、コンプライアンスの状況、または対象ユーザーのニーズが、通常のインクルーシブなデフォルトより厳しい場合。
• UI が、ユーザーがアップロードした画像、ローカライズ、非常に長い名前、未知のデータ密度、生成コンテンツなど、変動しやすいコンテンツを扱う場合。
• ユーザーが、一般的なメンタルモデルやプラットフォームの慣例と相反する可能性のある新しさを求めている場合。
• ユーザーがフロントエンドの実装を求めており、対象のフレームワーク、デザインシステム、または CSS の制約が重要な場合。

質問する際は、推奨するデフォルトと選択肢を提示してください。ユーザーが詳細なヒアリングを明示的に求めている場合を除き、一度に質問するのは一つにしてください。質問項目の全体については、references/decision-prompts.md にある質問ツール用のプロンプトを使用してください。

ワークフロー：既存の UI のレビュー

既存の UI をレビューする場合は、次の順番で確認してください。

1. タスクと状況への適合性。 主なユーザーの目標、対象ユーザー、プラットフォーム、成功基準を特定します。不明な場合は慎重に推測し、その前提を明記します。
2. メンタルモデルと慣例への適合性。 一般的なコントロール、ナビゲーション、検索、フォーム、フィードバックが、ユーザーの期待どおりに機能するか確認します。
3. 情報の階層。 主となるコンテンツやアクションを特定します。ビジュアル階層が、単なる文書順や意味的な重大度ではなく、重要度と一致しているか確認します。
4. グループ化とレイアウト。 近接性、配置、共通領域、画面幅、レスポンシブ動作、曖昧な余白を確認します。
5. タイポグラフィ。 フォントの選択、文字サイズの段階、行の長さ、行の高さ、強調、ラベルの扱い、配置、長いコンテンツへの対応を確認します。
6. 色とコントラスト。 パレットの役割、コントラスト、状態の意味付け、色だけに依存した意味、色相と彩度のバランス、ダークモードとライトモードへの影響を確認します。
7. 奥行きとレイヤーの構成。 影、境界線、重なり、サーフェスの色、モーダル、ポップオーバー、カード、フォーカスの階層を確認します。
8. 画像とメディア。 画像の品質、切り抜き、意図したサイズ、オーバーレイテキストのコントラスト、読み込み失敗、UGC、代替テキストの必要性を確認します。
9. 状態と堅牢性。 空、読み込み中、エラー、無効、フォーカス、ホバー、選択済み、入力検証、破壊的操作、成功の各状態を確認します。
10. アクセシビリティとインクルージョン。 知覚のしやすさ、操作性、簡潔さ、寛容性、キーボード操作の流れ、フォーカス、タッチターゲットの使いやすさ、動きへの配慮、スクリーンリーダー向けのセマンティクスを確認します。
11. フロントエンドでの実現可能性。 ビジュアルに関する提案が、トークン、セマンティックコンポーネント、レスポンシブ CSS、保守しやすいバリエーションで実装できるか確認します。
12. 修正の優先順位付け。 調査結果を、影響の大きい修正、仕上げの改善、状況に応じたトレードオフに分類します。最小限の変更で最大の改善が見込めるものを推奨します。

ワークフロー：UI の作成または改善

新しいデザインや提案を作成するときは、次の順序で進めます。

1. 中心となる機能を明確にします。 具体的な画面、タスク、対象ユーザー、完了目標を定義します。ナビゲーションの装飾ではなく、コンテンツと機能から始めます。
2. 必要な要素を列挙します。 主要コンテンツ、主要アクション、補助アクション、制約、状態を特定します。
3. 役立つ最もシンプルな構造を選びます。 低忠実度でレイアウトをスケッチするか、説明します。構造が機能するまでは、色、影、アイコン、詳細なタイポグラフィは避けます。
4. グレースケールで階層を作ります。 まず順序、グループ化、サイズ、ウェイト、間隔、コントラストを使います。色は、それなしでも階層が明確になってから加えます。
5. システムを確立します。 タイプスケール、間隔のスケール、グリッド／コンテナのルール、色の役割、角丸、境界線、エレベーショントークンを選びます。
6. レイアウトを構成します。 関連する要素を近くに配置し、関連しない要素は明確に分けます。曖昧な間隔は避けます。
7. タイポグラフィを適用します。 読みやすい本文、明確なタイトル、控えめなラベル、適切な行の高さ、一貫した強調、ベースラインや端の揃え方を設定します。
8. 色と状態を適用します。 ブランド、操作可能性、状態、フォーカスを示すために色を使います。コントラストを確認し、色以外の手がかりも加えます。
9. 奥行きと画像を加えます。 影、重なり、背景の変化、画像は、面、階層、ブランドを明確にする場合にのみ使います。
10. 端の状態を設計します。 空、読み込み中、エラー、無効、選択済み、フォーカス、ホバー、長いコンテンツ、狭い画面での動作を含めます。
11. アクセシビリティとフロントエンド実装を確認します。 セマンティックな構造、キーボード操作の流れ、フォーカスの視認性、レスポンシブな動作、トークン化、動きを抑える設定への対応を確保します。
12. 判断の理由を説明します。 提案は個人的な好みではなく、ユーザー目標とシステム品質の向上として示します。

判断のフレームワーク

ビジュアル上の判断に迷ったときは、次のフレームワークを使います。

1. その判断はタスクの達成に影響しますか？ 目新しさより、明確さ、親しみやすさ、アクセシビリティ、復旧のしやすさを優先します。
2. 製品の個性を表現していますか？ 表現していて、ブランドに関する情報が不足している場合は質問します。そうでなければ、控えめなデフォルトを使います。
3. 認知負荷を軽減しますか、それとも増やしますか？ 内容をまとめ、段階的に開示し、必要な複雑さを隠さずに推奨される経路を強調します。
4. 階層を強めますか、それとも混乱させますか？ すべてのビジュアル上の手がかりは、優先度や関係性を支えるものにします。
5. 実際のコンテンツでも機能しますか？ 長いラベル、空のデータ、密度の高いデータ、UGC、ローカライズ、ダークモード、レスポンシブなサイズでテストします。
6. 一貫して実装できますか？ 個別に作り込むパターンより、トークン化され再利用可能なパターンを優先します。
7. 特別な配慮なしにアクセシブルですか？ 色だけに依存する、小さすぎるターゲット、隠れたフォーカス、動き、脆弱なコントラスト、曖昧なラベルに頼っている場合は、見直します。

実践的なルール

階層

• スタイルを適用する前に要素の順位を決めます。主要、二次、三次、背景要素を判断します。
• 重要なものすべてを大きく、太字で、色付きの枠で囲まないでください。主要な要素を強調し、それ以外は目立たせないようにします。
• 複数のビジュアル要素を慎重に使います。サイズ、ウェイト、コントラスト、間隔、配置、色、奥行きのうち、強い手がかりは1つか2つで十分な場合が多くあります。
• 破壊的なアクションが自動的に主要アクションになるわけではありません。現在のタスクにおける役割に応じてスタイルを適用し、破壊的な判断を行うのが確認ステップである場合にのみ、そこで目立たせます。
• ラベルは、明確に構造化されたデータに対する最後の手段です。値だけで意味が伝わる場合は、ラベルを目立たなくするか削除します。

レイアウトと間隔

• まず余白をたっぷり取り、タスクに合うレイアウトになるまで調整します。最初から窮屈に始めて、見た目がかろうじて許容できるまで小さな余白を足していくのは避けます。
• 意味のある段階差を持つ、制約された間隔スケールを使います。数ピクセルしか違わない恣意的な値は避けます。
• 曖昧な間隔は避けます。関連する項目同士は、ほかのグループとの間隔よりも近づけます。
• 画面全体をデフォルトで埋め尽くさないようにします。全幅にすると読みやすさやグループ分けが損なわれる場合は、テキストやコンテンツの幅を制限します。
• グリッドは装飾ではなく、柔軟な構造として使います。コンテンツとその関係性に基づいてグリッドを決めます。
• 情報密度の高いレイアウトは、専門家向け、監視用、表形式、高頻度のタスクなどに意図的に採用します。

タイポグラフィ

• フォントは、単独で流行しているように見えるからではなく、コンテンツ、対象読者、プラットフォーム、ブランドに合わせて選びます。
• 小さな文字サイズスケールを使います。意図せず生じたように見える細かな違いは避けます。
• 本文は読みやすく保ちます。文章やカードでは行の長さを短くし、小さなテキストでは行間を広く、大きな見出しでは行間を狭くします。
• 読みやすさを優先してテキストを配置します。ラテン文字の本文の多くでは左揃えを優先します。中央揃えは、短く情報密度の低いコンテンツに限定して使います。
• タイポグラフィが視覚的な主役となる場合は、テキストとコントロールのベースラインを揃えます。
• 利用できる場合は、本物のイタリック、小型大文字、数字、ウェイトを使います。擬似的な傾斜、横方向への引き伸ばし、過度な字間は避けます。
• 階層の各レベルで、一貫した視覚的な手がかりは数個までにします。太字、イタリック、下線、全大文字、色、サイズを一度に組み合わせるのは避けます。

色

• 色を広く適用する前に、ニュートラル、ブランド／アクセント、セマンティック、フォーカス、サーフェスの役割を定義します。
• 色相、彩度、明度を調整するときは、HSL／OKLCHのような考え方を優先します。個別の16進数値を一つずつ選ぶのは避けます。
• 最終的なUIで必要に見える数より多くの色合いの段階を用意し、ホバー、アクティブ、境界線、背景、テキストの状態に一貫性を持たせます。
• 彩度の高い背景色の上で、知覚上のコントラストが低下する場合は灰色のテキストを使いません。その背景に調和する色を選びます。
• 明るい色でも彩度を保ち、個性や状態の違いが失われる、色あせたパレットは避けます。
• エラー、成功、警告、選択状態、リンク、必須フィールドには、色以外の手がかりも使います。

奥行き、サーフェス、境界線

• 一貫した光源のモデルを一つ使います。浮き上がったサーフェスには、互いに整合するハイライトとシャドウが必要です。
• 小規模なエレベーションスケールを使います。コントロールやカードには低め、ポップオーバーやドロップダウンには中程度、モーダルや操作をブロックするサーフェスには高めのエレベーションを使います。
• どこにでも目立つ境界線を追加する前に、控えめな背景色の変化、間隔、シャドウ、アクセントエッジを優先します。
• 重なりは、レイヤー構造を明確にする、意図的なフォーカルポイントを作る、または適度な動きを加える場合に限ります。重要なテキストやコントロールに重なって明瞭さを損なわないようにします。
• フラットデザインでも、階層、グループ分け、コントラスト、サーフェスの変化による奥行きの手がかりが必要です。

画像とメディア

• 十分な解像度があり、トリミングが効果的で、スタイルに一貫性があり、明確な用途を持つ画像を使います。
• コントラストを保護する手段（オーバーレイ、グラデーション、単色パネル、ぼかし、制御されたトリミング）なしに、予測できない画像の上へテキストを直接配置しないでください。
• 画像の意図されたサイズを尊重します。小さなアセットを品質が損なわれるほど拡大したり、詳細な画像を内容が判読できなくなるほど縮小したりしないでください。
• ユーザーがアップロードした画像は、レイアウトとコントラストに悪影響を及ぼす可能性があるものとして扱います。トリミング、フォールバック用サーフェス、安全なテキスト配置、モデレーション／プレースホルダー状態を用意します。

仕上げの詳細

• デフォルトのコンポーネントを意図的に改善します。フォーカスリング、空の状態、ホバー／アクティブ／無効状態、選択状態、バリデーション、ローディングスケルトン、マイクロコピーを見直します。
• 階層構造とアクセシビリティを整えた後、アクセントボーダー、控えめな背景、小さな装飾要素を使って仕上げます。
• 空の状態では、何が不足しているのか、それがなぜ重要なのか、次にどのような操作をすればよいのかを説明します。
• 効果の大きい細かな改善点を探します。見出しの行間を詰める、アイコンの位置を整える、選択状態を明確にする、角丸を統一する、サーフェスのコントラストを高める、不要なボーダーを減らすなどです。

アクセシビリティとインクルージョンに関する要件

アクセシビリティは、最後に行うコンプライアンス確認ではなく、視覚的な構成の中核要件として扱います。

• 知覚可能性を確保します。テキスト、アイコン、コントロール、状態は、コントラスト、サイズ、ラベル、代替テキスト、複数の手がかりによって知覚できるようにします。
• 操作可能性を確保します。コントロールには十分な大きさのターゲット領域、キーボード操作、論理的なフォーカス順序、視認できるフォーカス状態が必要です。
• わかりやすさを確保します。不必要な複雑さを減らし、明確なラベルを使い、可能な場合は関連する情報だけを表示し、モードを見えるようにします。
• エラーへの寛容さを確保します。可能な限りエラーを防ぎ、関連するフィールドの近くでエラーを説明し、ユーザーの入力を保持し、可能であれば取り消しや復旧に対応し、破壊的な操作は慎重に実行できるようにします。
• 色だけに頼らないでください。色にテキスト、アイコン、形状、位置、パターンを組み合わせます。
• モーションの低減設定を尊重します。重大な意味を伝えるために注意を引くモーションを使う場合は、モーションを使わない代替手段も用意します。
• プラットフォームに適したタッチターゲットの最小サイズを使います。操作の正確さが重要な場合や、モバイル、手元が不安定な状況、時間に追われる状況で使う場合は、ターゲットのサイズや間隔を広げます。
• インクルーシブな画像を使います。製品の状況で特定の表現が必要な場合を除き、特定の体型、能力、文化、デバイス、環境だけを想定させる視覚的な表現は避けます。
• 本番環境の UI では、WCAG AA 相当のコントラストと視認性の高いフォーカス表示をデフォルトにします。ユーザーの製品で、より厳格または異なる基準が必要な場合にのみ確認します。

フロントエンド実装のガイダンス

出力にフロントエンドのコードや実装に関するアドバイスが含まれる場合は、視覚的なデザインを実装可能な形にします。

• セマンティックな構造を維持します。視覚的な階層は文書構造と異なっていてもかまいませんが、見出し、ランドマーク、リスト、テーブル、ボタン、リンク、フォームコントロールはセマンティクスを正しく保ちます。
• 余白、フォントサイズ、行間、色、角丸、シャドウ／エレベーション、z-index、モーションの時間とイージングにはデザイントークンを使います。
• レスポンシブレイアウトの基本要素を使います。グリッド／フレックス、適切に応じたコンテナークエリまたはブレークポイント、読みやすいテキストの最大幅、流動的なメディアを使用します。
• プライマリ／セカンダリ／ターシャリ／破壊的な操作、選択状態、ホバー、アクティブ、無効、フォーカス、ローディング、エラー、成功に対応するコンポーネントのバリアントを用意します。
• 操作には実際のボタンを、ナビゲーションには実際のリンクを使います。セマンティクスとキーボード操作を備えないまま、非インタラクティブ要素をコントロールのように見せないでください。
• フォーカス状態を視認できるようにし、カラースキームと一貫性を持たせます。同等に視認できるフォーカスインジケーターに置き換えずに、アウトラインを削除しないでください。
• 表形式のデータにはセマンティックなテーブルを使います。レイアウト目的でテーブルを使わないでください。データ量の多いテーブルでは、配置、一覧性、固定表示されるコンテキスト、切り捨てのルール、レスポンシブ時のオーバーフロー動作を優先します。
• ライトモード／ダークモードには CSS 変数またはテーマトークンを使います。機械的に色を反転しないでください。各モードに応じてサーフェス、ボーダー、シャドウ、セマンティックカラーを調整します。
• 画像は明示的なサイズ、レスポンシブなソース、代替テキスト、適切な場合は遅延読み込みを指定して最適化し、メディアが壊れている場合や存在しない場合のフォールバックも用意します。
• モーションを低減するメディアクエリを使い、長いアニメーションの間、ユーザーへのフィードバックを妨げないようにします。
• 壊れやすい CSS や一度限りの状態ロジックを必要とする独自の視覚表現よりも、新規性はやや控えめでも保守しやすい解決策を優先します。

品質チェックリスト

批評、推奨事項、UI 実装を仕上げる前に、次の点を確認してください。

• ユーザーの主なタスクと主なアクションが明確です。
• 色を加える前でも、インターフェースをグレースケールで問題なく使用できます。
• 関連する要素が、近接、整列、共通の領域によってグループ化されています。
• 余白、文字、色、角丸、エレベーションに、統一されたシステムを使用しています。
• テキストが読みやすく、行が長くなりすぎず、階層を示す手がかりに一貫性があります。
• 色のコントラストが十分で、色だけに意味を担わせていません。
• 影、面、境界線が、実際のグループ化やエレベーションを表しています。
• 画像によってテキストのコントラスト、レイアウト、意味が損なわれていません。
• 空の状態、読み込み中、エラー、フォーカス、無効、選択済み、ホバーの各状態に対応しています。
• タッチターゲット、キーボード操作の流れ、フォーカスの視認性、スクリーンリーダー向けのセマンティクスを考慮しています。
• 長いコンテンツ、密度の高いデータ、UGC、ローカライズ、狭い画面に対応しています。
• 推奨事項の優先順位が明確で、ユーザーにとっての価値に基づいて説明されています。

完全版のチェックリストは、references/checklists.md を参照してください。

よくある避けるべき間違い

• 機能を設計する前にナビゲーションシェルを設計する。
• 階層が明確になる前に、色、影、グラデーション、アイコンを加える。
• 余白、文字、色のシステムを使わず、任意のピクセル値を使う。
• 重要な要素すべてを視覚的に目立たせる。
• リンク、エラー、ステータス、選択状態を色だけで表す。
• 余白、グループ化、背景のコントラストではなく、過剰な境界線を使う。
• 見た目のよい UI は自動的に使いやすいと考える。
• ユーザーが判断に必要な情報を見られなくなるほど単純化する。
• ユーザーやブランドに強い理由がないのに、一般的なメンタルモデルに反する。
• 静的な正常系の表示が洗練されているという理由で、例外的な状態を無視する。
• 見た目は適切でも、アクセシビリティやセマンティクスに問題のあるフロントエンドコードを生成する。

アンチパターンの全リストは、references/anti-patterns.md を参照してください。

ユーザーへの推奨事項の説明方法

視覚的な推奨事項は、好みではなく機能上のトレードオフとして説明してください。

次のパターンを使ってください。

1. 観察： 現在のデザインがどのように機能しているかを説明します。
2. 影響： ユーザーにどのような影響があるかを説明します。
3. 推奨事項： 具体的な変更を示します。
4. 理由： 階層、グループ化、読みやすさ、アクセシビリティ、慣習、実装との関連を説明します。
5. トレードオフ： 別の選択肢がより適切な場合に触れます。

例：

主なアクションとフィルターチップの視覚的な強さが同じため、互いに競合しています。主なアクションだけを塗りつぶしボタンにし、フィルターはサブのチップに変更して、ツールバーとコンテンツの間隔を広げてください。こうすることで、フィルターを見つけやすく保ちながら、一覧性を維持できます。