Moddingflow/better-design

Better Design

依頼されたタスクを明確かつアクション可能にします。ユーザーは現在地を認識でき、アクションを実行する前にその内容を理解し、結果を受け取り、エラーから回復できます。一貫性、表現力、アクセシビリティは別々に評価します。完璧なUXを約束しないでください。

1. スコープとビジュアルの基盤を確立する

• モードを選択します: 作成、集中改善、監査、または計画。監査は読み取り専用にし、計画では変更を実装しないでください。ユーザーがリクエストしていない機能を追加しないでください。
• リクエストとプロジェクトからプラットフォームを確立します。コンテキストがない場合のみ、レスポンシブウェブ、セマンティックHTML、WCAG 2.2 AAを最初のターゲットとして使用します。
• レスポンシブサーフェスを構成または変更する前に、実際のデバイスとビューポートのマトリックスを定義します。ウェブサイトの場合は、製品がサポートするモバイル、タブレット、デスクトップ、ウルトラワイドのレイアウトを含めます。モバイルゲームの場合は、小型および標準的なスマートフォンとタブレットを含めます。デザイン制約とレイアウト動作は、デスクトップ構成を単に縮小するのではなく、それらのサーフェスに適応する必要があります。ブラウザ作業の場合は、ブラウザズームをマトリックスに含めてください。75%、100%、150%では、異なるクリッピング、密度、リフロー、インタラクションの障害が露呈する可能性があるためです。
• UI作業の前に、プロジェクトのDESIGN.md（ルート、docs/、design/、またはエージェントの指示に記載されたパス）を探して完全に読みます。これはインターフェースの値（フォント、タイプスケール、カラーロール、スペーシング、半径、コンポーネントサイズ、アイコン、モーション）の唯一の情報源です。新しいコードまたは変更されたコードのすべての値は、ロールまたはトークン名でそこから取得します。目測、丸め、または類似値の導入は絶対に行わないでください。ルールはdesign-md.mdにあります。
• 現在のランタイムまたは確認された現在のキャプチャを通じて既存の画面を検査し、その後、近くのコンポーネント、トークン、スタイル、プロジェクトルールを検査します。DESIGN.mdが存在しないからといってデザインシステムがないわけではありません。コードトークンがシステムです。進行中の無関係な作業は保持します。
• 実装の欠陥とリデザインリクエストを区別します。まず原因に対処します。不明確な順序、予測不能なアクション、フィードバックの貧弱さ、データ損失、またはコンテンツの喪失。
• 次の順序で決定を行います。明示的なタスクと制約 → DESIGN.mdと既存のシステム → プラットフォームの慣例 → ドメインタスク → このスキルの設定可能なベースライン。機能性と該当するアクセシビリティ要件はすべてのレベルで適用されます。
• デフォルトのビジュアルディレクション。 ユーザーがビジュアルスタイルを指定せず、プロジェクトにDESIGN.md、ブランド、コードトークン、または継承するライブUIがない場合は、ハウススタイルで構築します。Appleの精神に則ったプレミアム超ミニマル（黒いキャンバス、ウェイト500と340のほぼ白のGeologica、2つのグレー、リンクとフォーカス用の1つの青い色、ピル型アクション、トーンで区切られたサーフェス、唯一の色としての実際のコンテンツ）。ルールと既製のDESIGN.mdプリセットはhouse-style.mdにあります。スタイルを書き始める前に全体を読んでください。エージェントを別の場所に導く2つの誤読があるので、それらを明示的に確認します（house-style.mdセクション1）。プロダクトのドメイン、業界、オーディエンス、または名前は視覚的な手がかりではありません（「コーヒー焙煎所」、「開発者向け」）。また、触っていないスキャフォールドのデフォルトは継承するシステムではありません（shadcn/uiのデフォルトテーマ、Tailwindのデフォルトパレット、create-next-app、Vite、Expoスターター、Bootstrap、MUI、Chakraのデフォルト）。代わりにハウススタイルをそれらにマッピングします。適用する場合は、参照ファイルhouse-style.htmlから開始します。白紙のページからではありません。そのトークン、タイプクラス、ナビゲーション、ボタン、タイル、セクションリズムを取得し（またはスタックのコンポーネントに移植し）、そのコンテンツを置き換えます（house-style.mdセクション1）。ユーザーからの視覚的な手がかり（色、ムード、テーマ、参照、ブランド、オーディエンススタイル）はこれをオーバーライドします。リクエストに従い、ハウススタイルのうち、リクエストが未定義のままで矛盾しない部分のみを適用します。既存のプロダクトを、依頼がない限りハウススタイルにスタイル変更しないでください。ゲームは独自のアートディレクションを維持します。
• 確立されたブランド、密度、ゲーム的、エディトリアル、または表現力豊かな構成を維持します。それらを汎用的なグレーのCRMに置き換えないでください。実際の競合の場合は、最小限のアクセシブルな調整を選択し、特定の逸脱を説明します。
• 決定を実質的に変更する未知のものだけを明確にし、妥当な前提を簡潔に述べます。このスキルは、新しい承認またはHTMLゲートを導入しません。プロトタイプ、承認、ビルドに関する既存のプロジェクト要件は引き続き適用されます。

2. タスクとプロポーショナルな契約を定義する

• 主要なシナリオを平易な言葉とその観測可能な結果で説明します。エントリー → アクション → 結果 → エラー/リトライ → 戻る/キャンセルの流れをウォークスルーします。
• 主要タスク、セカンダリアクション、ヘルプを分離します。ユーザーに馴染みのある名前とパターンを選択し、ナビゲーションとアクションの場所を画面間で一貫させます。
• 単一の修正には、変更された決定とチェックの短い記録のみが必要です。新しいフローの場合は、実装前にコンパクトな契約を書きます。これは作業ツールであり、ユーザーへの必須文書ではありません。
• 構造、数値デフォルト、例外についてはdesign-contract.mdを使用します。JSON例がフォーマットを示しています。小さな変更のためにプロジェクトに丸ごと追加しないでください。
• 契約をプラットフォーム、目標、既存システム、ディレクション、影響を受けるコンポーネントとそのアクション/状態、レスポンシブ動作、受入証拠に限定します。計画されたチェックは完了したチェックではありません。

3. スタイリングの前にアートディレクションを設定する

否定ルールは出力を次の最も一般的なテンプレートに押しやるだけです。キャラクターはプロセスから生まれます。アイデンティティがタスクの一部であるサーフェス（ブランド、ランディング、ポートフォリオ、コンシューマーアプリ、ゲーム、エディトリアル、ランチャー）を作成またはリデザインする場合は、トークンを選択する前にart-direction.mdに従ってください。ハウススタイルが適用される場合（セクション1）、パレット、タイプ、シェイプ、モーショントークンはそのプリセットから取得されます。それでもコンセプトを書き、画像、各セクションの主要要素、および1つのシグネチャーディテールを選択させます（house-style.mdセクション10）。それ以外の場合は:

• プロダクトのドメイン、オーディエンス、コンテンツから、一文のコンセプトを導き出します。「モダン、クリーン、ミニマル」のような形容詞ではなく、その世界のオブジェクト、場所、またはクラフトに基づきます。3つの目標品質と3つの具体的なアンチ品質を追加します。
• 3-5の実際のリファレンスを収集し（ユーザー提供のものを優先、AI生成画像は不可）、それぞれから正確に何を採取するかをメモします。リズム、密度、数値の表示、マテリアル、光。
• 主要なデバイス（タイポグラフィ主導、画像主導、構造的主導）が異なる2-3のディレクションをスケッチし、タスクとオーディエンスに関連した理由で1つを選択します。
• コンセプトからパレットとタイプを導き出します。明記された起源と色味を帯びたニュートラルを持つパレット、3つのタイプ候補と理由のある選択。1つまたは2つのシグネチャーディテールを計画します。effects-library.mdのオプショナルプールにはテスト済みのものが含まれています。
• 同じコンセプトからモーションキャラクターを導き出します。その世界のものがどのように動くか（テンポ、重さ、物理、何かがバネのように動くかどうか）に加えて、1つのシグネチャーモーションディテール。パレット、タイプ、モーションは一つの声として読める必要があります。motion.mdを参照してください。
• DESIGN.md内、既存のブランド内、またはディレクションが継承されているデザインシステム内では、DESIGN.mdから取得するか、ライブサーフェスから一文で述べ、その中で作業します。高密度の作業ツールは、精度とデータタイポグラフィを通じてキャラクターを表現します。システムもユーザー手がかりもない場合は、ニュートラルフォールバックの密度でハウススタイルのアプリスケールとパレットを採用します。
• ディレクションを契約に記録します（direction、direction.motionを含む）。distinctivenessとmotionのチェックを計画します。選択したディレクションとそのトークンをDESIGN.mdに書き込むことで、後続の画面とセッションが同じ値から構築されるようにします。

4. 一貫した決定システムを構築する

• DESIGN.mdとコードトークンからトークンとコンポーネントを再利用します。新しいシステムの場合は、色、タイポグラフィ、スペーシング、半径、レイヤー、モーションのセマンティックロールを定義し、コンポーネントバリアントを選択します。
• すべての画面が同じ部分から構築されるようにセットを閉じます。1つまたは2つのフォントファミリー、少数のロールを持つ段階的なタイプスケール、固定されたスペーシングスケール、少数の半径、固定されたコンポーネントサイズ（例: ボタンsm/md/lg）。同じロール、すべての画面で同じ値。欠落している値はシステム上の決定です。ロールをDESIGN.mdとコードトークンに同じ変更で追加します。
• インターフェースをゼロから作成する場合（ハウススタイルが適用される場合はhouse-style presetから）、またはリデザインや複数コンポーネントの変更でDESIGN.mdが見つからない場合、テンプレートからDESIGN.mdを作成します。ライブコードトークンから導出し、値を発明するのではなく、矛盾を黙って修正せずに記録します。依頼がない限り、単一要素の修正のためにそれを作成しないでください。1行で提案します。DESIGN.mdとコードトークンは、どちらかに触れるすべての変更内で同期を保ちます。
• APIは意図、サイズ、密度、状態を表現します。ネイティブプロップ、フォーム参加、リンク、アクセシブルな名前を保持します。送信ボタンやhrefを持つリンクにonClickを要求しないでください。
• すべての要素を独自のhex、gap、shadow、radiusで調整しないでください。原因が共有されている場合は、共有トークンまたはバリアントを変更します。レイアウト計算、1pxのボーダー、0、fr、%、calc、aspect-ratio、および許可されたプロジェクト値は、それ自体が違反ではありません。
• テキストサイズはロールとコンテナによって選択します。
• ジオメトリを構築します。目測で配置しないでください。すべての画面、パネル、ゲームメニューについてlayout-geometry.mdに従い、結果を測定します（セクション8）。位置ずれはその原因（ピボット、アンカー、欠落したレイアウトグループ、スプライトのパディング、フォントメトリクス）で修正し、要素を微調整することで決して修正しないでください:
  • 等間隔。 一種類の兄弟要素は、1つのスペーシングトークンを持つレイアウトコンテナ（flex/grid gap、Unityレイアウトグループ、Godotボックスコンテナ、UMGボックス）に配置されるため、それらの間のすべてのギャップは同一になります。異なるギャップは、新しいグループとスケール上の明確なステップアップを意味する必要があります。近接性の梯子: コントロール内 < アイテム間 < グループ間 ≤ パディング。
  • 共有ライン。 行内のアイテムは、トップ/センター/ボトムを共有します（異なる高さはセンターを共有します）。列内のアイテムと設定リストのすべてのラベルは1つの垂直キーラインで始まり、コントロールは2番目のキーラインに配置されます。グリッドまたは固定ラベル列を使用し、行ごとのオフセットは使用しないでください。ボタンのセットは1つのサイズを共有します。
  • 小さなコントロール内のコンテンツは、フォントのラインボックスやパディングされたスプライト矩形ではなく、可視インク（キャップハイト、トリミングされたアイコンピクセル）によって中央揃えにされます。非対称アイコンは、宣言された光学的オフセットをコンポーネントに組み込みます。アイコン＋ラベルのペアは1つのギャップトークンを使用します。
  • 余裕のあるスペース。 何もオーバーフローしたり、コンテナの端に配置されたりしてはいけません。パディングは、少なくともそれが含むギャップと同じ大きさで、最長のローカライゼーション、ホバースケール、フォーカスリングのための余裕を持ちます。インタラクティブUIは、サポートされるすべてのアスペクト比でセーフエリア内に収まります。コンテンツが収まらない場合は、マージンではなくレイアウトを変更します。
• ブラックリストではなくプロセスを通じてタイポグラフィを選択します。コンセプト（時代、マテリアル、声、データ密度）から3つのファミリーをショートリストし、明記された理由で選択します。ファミリーは、実際のサイズと言語で読みやすく、必要なウェイト、スタイル、数字、グリフカバレッジ（サポートする場合はキリル文字を含む）、およびフォールバック動作を提供する必要があります。禁止されているファミリーはありませんが、習慣で選ばれたファミリーは欠陥です。理由なくあるトレンドのデフォルト（Inter、Uni Sans）を次のトレンドのデフォルト（Space Grotesk、DM Sans、Instrument Serif）に交換することは同じテンプレートです。スタイリッシュなタイプは、インターフェースを読みにくくしてはいけません。
• 優位性とコントラストを通じて階層を構築します。画面またはセクションごとに1つの主要要素、明確に段階付けられたタイプスケール（表現力豊かなサーフェスではボディの3-5倍、高密度ツールではより小さなステップ）、コンセプトに役立つ場所での意図的な非対称性、および1つのブロックパターンを繰り返すのではなく構造が異なる隣接セクション。
• 黄金比は、構成を改善する場合に比例、階層、クロッピング、またはホワイトスペースに情報を与えることができますが、必須の公式ではなく視覚的なツールです。実際のタスク、コンテンツ、レスポンシブ制約、可読性、既存システムは、それらが競合する場合は常に優先します。
• コンテンツがアクション、グループ化、またはビジュアルアンカーを通じて理解できる場合、主要画面を中断のない散文の壁にしないでください。密度の高い説明をスキャン可能なセクションに分割し、有用な場合は意味のあるコントロール、アイコン、イラスト、プレビュー、図、またはその他のタスク関連の画像とペアにします。たとえば、ダッシュボードやアカウントエリアは、ユーザーが設定できる内容を説明するだけでなく、主要なセクションと次のアクションを公開する必要があります。理解と競合したり、誤ったアフォーダンスを作成したりする装飾的なビジュアルを追加しないでください。
• 色は意味と強調のために使用します。色だけで状態を伝えないでください。エラー/成功/必須/選択された情報は、テキスト、アイコン、シェイプ、パターン、またはグレースケールおよび色覚障害でも見える別の非色の手がかりとペアにします。
• 不透明度、オーバーレイ、グラデーション、画像、および必要なすべてのテーマが適用された後の実際の隣接する前景/背景ペアでコントラストを確認します。閾値に近い結果を丸めないでください。通常のテキストおよびテキストの意味のある画像では少なくとも4.5:1、大きなテキスト（CSSで少なくとも24pxの通常または18.5pxの太字）では3:1のみを達成します。細い、小さい、または珍しいタイプではより高い値を目指します。
• アクティブコントロール、そのフォーカスまたは状態、および意味のあるグラフィカルオブジェクトを隣接する色に対して識別するために必要な視覚情報に対して、3:1の最小コントラスト比を確保します。ボーダーは、それがコントロールを識別可能にするものである場合にのみ必要です。その目的で使用される場合、同じ3:1の閾値を満たす必要があります。
• アイコンは、アクションの場合は塗りつぶし、ナビゲーションの場合は線画など、一貫したスタイルをグループ内で使用します。塗りつぶしと線画を混在させないでください。フォーカス可能またはインタラクティブなアイコンには、アクセシブルなラベルが必要です。

5. モーションとインタラクションに命を吹き込む

motion.md に記載されているように、すべてのインタラクションはモーションキャラクターから導出する必要があります。ハウススタイルのモーションは house-style.md セクション8にあります。

• フィードバックとトランジションを優先します。ボタンのホバーとプレス、ナビゲーションの画面間トランジション、モーダルの出現、状態の変化（ローディング、エラー、空の状態、成功）。
• 適切なタイミング関数と期間を選択します。イーズイン/アウト、イーズアウト、またはバウンスは、雰囲気と物理的な動きのタイプに基づきます。一貫性を維持します。すべてのトランジションが1つのパラダイム（例: デフォルトのイーズアウト、強調にはバウンス）に従います。すべてのインタラクションが一貫して応答していると感じられるように、期間を短く保ちます（複雑なトランジションでも300msを超えないようにします）。
• 動きがユーザーのインタラクションの知覚されたパフォーマンスを向上させることを確認します。待機時間を隠したり、コンテキストを提供したり、または操作を楽しく感じさせたりします。動きは、単なる装飾ではなく、目的を持っている必要があります。
• 動きを減らす設定（prefers-reduced-motion）を尊重します。モーションを完全に削除するか、より単純なバージョン（フェード、スケールなし、移動なし）に置き換えます。
• ローディングスプラッシュ、スケルトンローダー、進行状況バー、楽観的UIなど、読み込み状態を含めます。これらは、インターフェースが応答していることをユーザーに知らせるため、ユーザーが入力を失ったり、どこにいるのかわからなくなったりしないようにするために重要です。

6. アクセシビリティをデフォルトにする

キーボードナビゲーション、フォーカス管理、スクリーンリーダーのサポートは、最初からそれぞれのプラットフォーム上に構築する必要があります。

• セマンティックHTML（ネイティブ要素またはARIAロールを介して）を使用し、フォーカス可能な要素がネイティブのキーボードインタラクション（Enter、Space、Tab、矢印キー）を提供することを確認します。
• 論理的なタブ順序（TabキーとShift+Tab）を維持し、フォーカスをオフスクリーンや隠れた要素に移動させないでください。モーダルを開くときはフォーカスをモーダル内に閉じ込め、閉じたときにトリガー要素に戻します。
• スクリーンリーダーにコンテキスト（現在のページ、セクション、状態）を提供します。すべての画像にaltテキストを使用します（装飾画像の場合は空のalt）。ARIAライブリージョン（aria-live）を使用して、ユーザーアクションなしで変更されたコンテンツセクション（チャット、フィード、カートの更新）をアナウンスします。
• フォーカスインジケーター。すべてのフォーカス可能な要素には、明示的なフォーカススタイルが必要です。ブラウザのデフォルトのアウトラインに依存しないでください。フォーカスインジケーターは2px以上で、十分なコントラストがあり、コンポーネントの視覚的な手がかりの一部である必要があります。
• タッチターゲット。モバイルでは、タッチターゲットは少なくとも44x44 CSS pxである必要があります。小さいコントロール（チェックボックス、ラジオボタン、スライダーのサム）の場合は、パディングを使用するか、ヒット領域を拡張します。
• エラー。エラーをユーザーに明確に伝える方法（インラインエラーメッセージ、サマリー、色の変更に加えてアイコンとテキストを使用）を実装します。エラーは、どのフィールドに問題があるかを指定し、解決策を提案する必要があります。

7. 検証、監査、計画

• 各チェックを実行し、観察された問題を証拠とともに記録します（注釈付きスクリーンショットまたは構造化されたチェックリスト）。監査は読み取り専用です。実装しません。問題をすぐに修正しないでください。文書化して報告します。
• 監査中は、次のものを確認します。
  1. 各画面での目標とディレクションの適合性。
  2. システム全体でのトークンとコンポーネントの一貫性（DESIGN.mdとコード）。
  3. レイアウトジオメトリ（等間隔、共有ライン、余白）。
  4. コントラストと色の使用法。
  5. キーボードアクセシビリティとフォーカス管理。
  6. モーションの一貫性と目的。
  7. ドラッグ＆ドロップの準備ができているか（必要な場合、ドロップゾーンが存在するか）。
  8. 読み込み状態とエラー状態の存在。
• 計画は変更を実装しません。設計上の決定、推奨事項、見積もりを提供します。契約とディレクションを参照します。

8. DESIGN.mdを管理する

• DESIGN.mdは、インターフェース値の単一の情報源です。リアルタイムでコードトークンと同期している必要があります。
• DESIGN.mdを作成または更新するときは、テンプレートまたはhouse-style presetに従ってください。
• 新しい値を発明しないでください。既存のコードトークンから派生させるか、または新しい値を追加する理由を明確にします。
• 矛盾は黙って修正せずに記録し、修正の提案を添えます。
• 異なる値、トークン、またはパターンを使用する画面は、その逸脱を文書化する必要があります。

9. 構成と参照

このスキルは、参照用に次のファイルを提供します。

• references/design-md.md: DESIGN.mdの形式とルール。
• references/house-style.md: デフォルトのハウススタイルのビジュアルディレクションとトークン。
• assets/house-style.html: ハウススタイルの実装例。
• references/art-direction.md: アートディレクションを作成するためのプロセス。
• references/layout-geometry.md: 正確なレイアウトのためのルール。
• references/motion.md: モーション言語の作成に関するガイド。
• references/effects-library.md: テスト済みのシグネチャーエフェクトのオプショナルプール。
• references/design-contract.md: 設計契約の構造。
• assets/design-contract.example.json: 契約のJSON例。
• assets/DESIGN.template.md: DESIGN.mdのテンプレート。
• assets/DESIGN.house-style.md: ハウススタイル用のDESIGN.mdプリセット。