ui-polish-pass

UI の仕上げ

役割と対象範囲

ADS のクラフトオーナーとして、タスクの適合性と情報構造が整った後、同じビルド／レビューの作業内で、変更対象の画面に関係する仕組みを適用します。小さな変更には小さなチェックを行います。選定済みの方向性を再設計したり、プロトタイプを本番品質に仕上げたり、ユーティリティ作業を基本的なユーザビリティの確認から除外したりしないでください。新しい方向性が必要なのは、実際に未解決の判断事項がある場合であり、仕上げを儀式化するためではありません。

基本の視点

• 装飾の前に、要点を絞ります。
• 画面を必要最小限の構造に絞り込んでから、存在する価値のあるものだけを戻します。
• 仕上げのために色やカード、装飾要素を増やす必要があるなら、それはおそらく仕上げではありません。
• /bolder と /quieter を方向性の調整として使います。
  • /bolder ＝ ごちゃつきを増やさずに、コントラスト、階層、または確信を強める
  • /quieter ＝ ノイズや強調を減らし、適切な要素を際立たせる

ビジュアル基盤の確認

既存のプロダクトトークンを優先します。一貫した基盤がない場合は、仕上げに着手する前に、必要最小限のセットを定義します。

• 文字の役割、スケール、行の高さ、読みやすい行長
• 余白の段階とグルーピングのリズム
• サーフェス、境界線、テキスト、アクション、セマンティックカラー
• 角丸とエレベーションのルール
• アイコンファミリーとサイズのルール

既存のトークンが適合する場合、新しいトークンを作らないでください。繰り返し使われる要素に不整合がある場合は、認可された範囲内で細部を調整する前に、該当するプリミティブを修正します。変更範囲を黙って広げず、システム全体に関わる作業として報告してください。

基本的な仕組み

これらのルールはインターフェースの仕組みを標準化するものであり、プロダクトのアイデンティティを定めるものではありません。プロジェクト内にすでに厳格なルールを定めた一貫性のあるシステムがある場合は、それを維持してください。

コントロールの寸法

コントロールのサイズ体系がない場合は、次の3種類の高さを使います。

• compact: 32px は、デスクトップ専用の高密度なツール向けです
• default: 40px は、一般的なデスクトップのコントロール向けです
• touch: 48px は、タッチ操作を優先する画面や、モバイルの主要なコントロール向けです

同じ行にあるコントロールの高さはそろえます。タッチターゲットは、表示されるグリフが小さくても、少なくとも 48 × 48px とし、隣接するターゲットとの間隔を少なくとも 8px 空けます。一般的なコントロールには選択したファミリーで想定されるオプティカルサイズを使い、単独で配置する場合やエディトリアルな用途では、より大きなサイズを使います。アイコンとラベルの間隔、左右のパディング、角丸、フォーカス時の表示は、コントロールプリミティブに集約します。

ドロップダウンのキャレットは、端から少なくとも 16px 内側に配置し、テキストとの間隔として少なくとも 44px を確保します。 両方の値は、インスタンスごとのパッチにせず、共有のセレクト／メニュートリガープリミティブに設定します。 対象となるデスクトップとモバイル／WebKit の画面で、長いラベル、フォーカス、開閉の動作を検証します。

テキストの表示維持

• プロダクト仕様で1行表示が明示的に必要とされている場合を除き、コンテンツは折り返して表示します。
• 値を省略表示する場合は、アクセシブルなツールチップ、開示、または詳細画面で全文を確実に確認できるようにします。
• 長いコンテンツが折り返しまたは省略表示されてもページのオーバーフローを引き起こさないよう、必要に応じてフレックスやグリッドのテキスト要素に min-width: 0 を指定します。
• 意味のあるテキストを固定高さのコンテナに入れないでください。
• 長い名前、ローカライズによる文字列の拡張、ブラウザーのズーム、200％のテキスト拡大を検証します。
• インラインメタデータが主要なテキストを圧迫する場合は、文字サイズを小さくする前に縦積みまたは再配置します。
• テキストサイズやビューポート幅が変わっても、同じ情報階層を維持します。

データの形式ルール

• テキスト列は左揃え、数値列は右揃えにします。
• 変化する数値、比較値、価格、割合、件数、タイムスタンプには、桁幅が揃う数字を使用します。
• データの種類ごとに、ロケールに応じた形式を1つ適用します。小数点以下の桁数、単位、符号、日付形式、タイムゾーンを明示し、一貫性を保ちます。
• 欠損、ゼロ、該当なし、読み込み中は、それぞれ異なる状態として表します。意味が曖昧なダッシュではなく、意味が明確なラベルを使用します。
• 表のヘッダーと本文では、行の密度を揃えます。意味上の必要がない限り、1つの表の中で行の高さを混在させません。
• 情報量の多い表には、必要なページ幅を確保します。モーダル、入れ子のカード、幅の狭いサイドパネルに押し込まないでください。
• 画面幅が狭い場合は、優先列、行の詳細、カード、視認できる手がかりを伴う横スクロールなど、意図的な表の表示方法を選びます。デスクトップ用の列を、読めないほど縮小して表示しないでください。

インタラクション状態システム

すべてのインタラクティブなプリミティブで、1つのトークンレシピに基づき、有効、ホバー、フォーカス可視、押下、選択（該当する場合）、無効、処理中の状態を定義します。

• 周囲の長さに相当する面積を少なくとも2px確保し、コントラストに3:1以上の変化を持たせた、視認できるフォーカスインジケーターを使用します。背景面が変化する場合は、2色のリングを優先します。
• ホバー時に、利用可能な唯一の操作や説明が初めて表示される設計にしてはいけません。
• 押下中と処理中の状態では、周囲のレイアウトを動かさず、入力をすぐに受け付けたことを示します。
• 選択、ステータス、検証を色だけに頼って表現してはいけません。
• 無効なコントロールの理由が重要な場合は、近くに常時表示されるテキストで説明します。無効なコントロールにフォーカスしなければ表示されないツールチップに頼らないでください。
• 選択中かつホバー中、選択中かつフォーカス中、処理中かつ無効など、状態が組み合わさった場合も読みやすさを保ちます。

サーフェス階層

製品上の必要性が明確でない限り、意味上のサーフェス階層は最大3段階にします。

• base はページのキャンバスに使用します
• raised は常設パネルや作業領域のグループに使用します
• overlay はメニュー、ポップオーバー、ダイアログ、一時的なレイヤーに使用します

各階層では、背景、境界線、角の丸み、エレベーションのレシピをそれぞれ定義します。境界線はグループ化や状態を示し、シャドウは実際の高さを示します。余白を設けるだけの目的でカードを追加しないでください。入れ子になったサーフェスに明確な操作上または状態上の役割がない限り、カードの中にカードを配置するレイアウトは避けます。

フォームの構成

• 常時表示されるラベルを使用します。プレースホルダーテキストは例やヒントとして使い、唯一のラベルにしてはいけません。
• ラベル、コントロール、補助テキスト、検証、ステータスを、予測しやすい1つのコンポーネント構成にまとめます。
• 可能であれば補助テキストの領域を検証メッセージにも再利用し、エラーによってレイアウトが大きくずれないようにします。
• 適切な入力タイプ、入力モード、オートコンプリートトークン、ネイティブなセマンティクスを使用します。
• 入力欄のサイズは、想定される回答に合わせます。短い値の入力欄を、初期設定でページ全幅にしてはいけません。
• 検証メッセージは入力欄の近くに、操作へのフィードバックは操作を開始した場所の近くに配置します。トーストは補助的な確認手段とし、エラーや成功を伝える唯一の手段にしないでください。

非同期処理の安定性と復旧

• スケルトンと読み込み中のプレースホルダーは、レイアウトのずれを防げるよう、最終的なコンテンツに近い形状にします。
• 処理中も、開始に使ったコントロールを表示し続けます。無効にするかラベルを変更し、操作した場所に進行状況を表示します。
• リクエストの一部が失敗しても、利用可能な部分データは保持します。
• 楽観的更新には、ロールバックできる手段を用意します。取り消し可能な破壊的操作には「元に戻す」を優先し、本当に取り消せない操作には確認を求めます。
• 空状態とエラー状態では、ページの視覚的な骨格を維持し、次に役立つ操作を示します。

レスポンシブな変換とレイヤー構成

• 複雑なコンポーネントはそれぞれ、小さな画面での対応方針として、再配置、順序変更、開示、置き換え、または意図的なスクロールのいずれかを定めます。
• 作業内容が変わる場合、モバイルでは構成も変わります。デスクトップを一律に縮小したものではありません。
• 固定ヘッダー、画面下部のアクション、ダイアログ、フォーカス中のコントロールはセーフエリアを考慮し、コンテンツやキーボードフォーカスを覆わないようにします。
• ベースコンテンツ、固定要素、ポップオーバー、ダイアログ、通知には名前付きのレイヤートークンを使用します。任意の z-index 値を積み重ねないでください。
• ユーザーが戻ることを合理的に期待する場合は、ナビゲーションをまたいでスクロール位置、選択内容、フィルター、タスクのコンテキストを保持します。

これらの機械的なデフォルトを、書体、配色、密度の個性、ブランド表現を一律に決めるために使わないでください。これらは引き続きプロジェクトレベルで決定します。

アイコンのデフォルト

まず、プロジェクトで既に一貫して使用されているアイコンファミリーを維持します。それ以外の場合は、ライセンスで使用が許可されているなら、プロジェクトまたはユーザーの明示的な希望に従います。希望がない場合は、適切なオープンソースのアイコンファミリーを1つ選びます。ADSでは特定のアイコンベンダーを必須としていません。

• 太さ／ストロークと、選択したファミリーが想定する光学サイズを統一します。
• プロジェクトで移行が明示的に承認されるまでは、既存の一貫したアイコンファミリーを維持します。
• ネイティブプラットフォームの規約、ブランドシステム、ゲーム、その他のドメイン固有のビジュアル言語には、意図的な例外を認めます。
• 明示的なデザイン上の理由がない限り、1つの画面内で異なるアイコンファミリーやストロークシステムを混在させないでください。

共有の Icon または InlineIcon プリミティブを使用して、ファミリー、サイズ、ストローク、色、配置、アクセシビリティ、光学的な補正を一元管理します。

• テキストの横にあるアイコンは、テキストの初行のベースラインに揃えます。フレックスレイアウトでは、まずベースライン揃えを使い、ファミリー単位の光学的なオフセットは共有プリミティブで適用します。アイコンごとの場当たり的な微調整は行わないでください。
• 正方形のボタン、ツールバー、アバター、その他の固定サイズのアイコンコンテナー内に単独で配置するアイコンは、幾何学的に中央揃えにします。
• 装飾目的のアイコンは支援技術から隠します。アイコンのみのコントロールには、アクセシブルな名前が必要です。
• アイコンの意味が広く明確に伝わらない場合は、目に見えるラベルを併記します。

アイコンライブラリにはそれぞれ独自のライセンスがあります。再配布権がないプレミアムライブラリやライセンスキーをコミットしないでください。必要な表示を維持し、認可されたパッケージアクセスを使用し、リリース前にプロジェクト固有の共有条件とテンプレートの利用条件を確認します。選択したファミリーが意図する用途のライセンスを受けていない場合は、承認済みの代替品を選んでください。

仕上がりのレビュー

必須の7段階レビューを個別に行うのではなく、関連する観点をまとめて確認します。

• 余白と構成： 関連するコンテンツをまとめ、既定のスケールを使い、プロダクト本来の情報密度を保ちながら、明確な主役を1つ設けます。冗長な装飾を取り除くのは有効ですが、必要な情報まで削除してはいけません。
• タイポグラフィ： 役割に一貫性を持たせ、読みやすい行長にします。一般的なユーティリティ用の書体、自然な大文字・小文字の表記、定義済みの書体のリズムを保ちます。色を増やしたり文字を小さくしたりしても、情報アーキテクチャ（IA）のわかりにくさは解消できません。
• 配置： ガターを統一し、アイコンを視覚的に整列させ、コントロールの行を安定させ、コンテンツ幅を適切にします。同じファミリー全体で視覚的な補正が必要な場合は、共通のプリミティブを使います。
• 色とコントラスト： プロジェクトのセマンティックトークンを使い、最終的に合成された色をテストします。不特定の不透明度を指定しても、副次テキストが読みやすくなるとは限りません。サポート対象のテーマを確認します。
• 操作感： フォーカスを視覚的に示し、入力にすぐ反応する状態を保ちます。動きは目的がある場合に限り、中断可能な形で使います。高頻度で操作するコントロールでは、アニメーションが不要なこともあります。実装時は既存のモーショントークンと ../web-animation-design/SKILL.md に従います。ユーティリティ用途には控えめなイージングが適しています。ジェスチャーに連動するスプリングや表現豊かな動きには、状況に応じた理由が必要です。モーション低減設定を尊重します。バウンスも押下時の拡大縮小も、すべてに適するわけではありません。
• 仕上げ： 変化する数値には等幅数字を使い、折り返しに耐えられるようにし、アイコンに一貫性を持たせます。適切な場合は入れ子の角丸を同心円状にし、プロパティごとに意図したトランジションを設定します。transition: all は使いません。すべての画面要素にアンチエイリアス、画像のアウトライン、アニメーション付きのアイコン切り替え、押下時の拡大縮小を一律に適用してはいけません。

基盤となるルールは ADS/design-review に委ねます。視覚的なステータス表示や装飾用のドット、強制的な大文字表記、片側だけ角丸にした境界線、影に見せかけた装飾は使いません。データは文字どおり正確に保ちます。階層を作ることだけを目的に、区切り線やカードを追加してはいけません。

検証と終了基準

最終サイズと対象ビューポートでレンダリング結果を確認し、選定したベースラインや関連する参考資料と比較します。影響を受けるコントロールの動作、長いコンテンツ、レスポンシブな変更を確認します。判断基準は、実際のタスクが明確であることと参考資料への忠実さです。流行の特定プロダクトなら採用するかどうかではありません。スクリーンショットだけでは、操作性やデザインの受け入れられ方は検証できません。

仕上げは、依頼された成果物に必要な範囲にとどめます。使い捨ての実験は粗いままでも構いませんが、役に立つ社内ツールには読みやすさと動作するコントロールが必要です。仕上げの過程で構造上の欠陥が見つかった場合は、新たな再設計のループを設けず、既存の予算内で ADS の評価工程に所見を戻します。