enhance-web-ui

サーフェスルーター：/uiux。現在のスキル：enhance-web-ui。ネイティブの iOS／Android（SwiftUI／Compose、Web レイヤーなし）は対象外です。Apple HIG／Material を直接使用してください。

ページ UI の改善

自由度：混合。 構成と階層の判断は［自由度高］、ライブ読み取り、DOM の矩形、3 つのビューポートでの検証は［自由度低 — 正確に実行］です。

既存の画面を、より落ち着いた階層、よりスマートなコンテンツ配置、表現力がありながら目的にかなった動き、理解を助ける洗練されたトランジションを備えた、まとまりのあるインターフェースに変えます。これは「チップ／カード／シャドウを追加する」スキルではありません。装飾を加える前に、情報を再配置し、削り、段階的に見せます。

「使いにくい」「ひどい」「スペースが無駄」「高さに一貫性がない」といった曖昧ながらも切実なユーザーフィードバックは、ほとんどの場合、以下の §X にある Hidden Failure Mode を示しています。ユーザーが指摘した表面的な装飾ではなく、まずそこから確認してください。

ブラウザー自動化を使用する場合、protocol-browser-anti-stall スキルがあれば、最初にその手順に従ってください。

考え方

1. 調査 — プリミティブ、トークン、実際のデータ契約
2. 優先順位付け — 主要／二次／メタデータ／アクション／周辺情報
3. 構成 — 装飾の前に、削る → グループ化する → 固定する → 段階的に見せる
4. 検証 — 1440／1024／800 ＋ 2 種類の目視確認 ＋ 矩形の均一性

実例

調査： 学習アプリ（階層 A）。統計タイルが Tooltip ラッパーを共有。「今日 0/10」が 3 回表示されています。 優先順位付け： 主要な要素は次のレッスンへの CTA です。カウントはメタデータであり、3 つ目の見出しではありません。 構成： Tooltip を block w-full に修正し、重複するカウントを 2 つ削除します。チップは追加しません。 検証： タイルの幅が一致し、カテゴリの目視確認で色相が明確に区別でき、CTA は引き続きブランドカラーのターゲット 1 つだけです。

報告前のセルフチェック

• まず構成する — 最初に行った編集が装飾ではない
• 実データを使う — ステータスやカウントをモックしない。バグが繰り返される場合はプリミティブを修正する
• 3 つのビューポートで確認する — CTA が折り返さず、空のときは使われていないスロットが折りたたまれる
• 適切な担当スキルを使う — フロー／情報設計 → enhance-web-ux、ブレークポイントのみ → audit-responsive

---

ルール

装飾する前に構成を整えます。 グラデーション、モーション、ぼかし、マスク、影を追加する前に、階層、グループ化、配置、リズムを整えます。

雑然とした画面は構造で整理します。 混み合った画面にバッジ、ラベル、カード、区切り線、補足テキストをさらに重ねないでください。副次的な情報は、目立たない領域、フッターバンド、ホバー／フォーカス時の表示、ドロワー、または段階的に情報を開示するレイヤーに移します。

ひと目で階層が分かるようにします。 すべての文言を読む前に、ユーザーが主要な要素、補足コンテンツ、メタデータ、アクションを把握できるようにします。

モーションには意味を持たせます。 フィードバック、状態変化、空間的な関係、操作可能性、注意喚起を示す場合に限り、アニメーションを使います。ステータスやブランドのトーンを伝え、動きを減らす設定にも対応する場合を除き、きらめきをループさせないでください。

ローカルのデザインシステムを使います。 既存のプリミティブ、トークン、角丸、間隔、タイポグラフィ、アニメーションヘルパー、ダーク／ライトのサーフェスを再利用します。一度限りのものを新たに作る前に、ローカルのプリミティブを拡張してください。

モック、機能しない UI、独自に逸脱した UI は絶対にリリースしないでください。 拡張は、製品の実際のデータコントラクト、バックエンド／API の状態、データベーススキーマ、または既存のドメインヘルパーに接続する必要があります。UI の視覚的なフィードバックを改善する場合は、まず、それを反映すべき実際のステータス、タイムスタンプ、件数、所有者、エラー、進捗、権限、ライフサイクルのデータがないか確認します。堅実なユーザー体験に必要なデータが存在しない場合は、コンポーネント内で状態を偽装するのではなく、バックエンド／スキーマ／API に最小限の拡張を提案または実装してください。

ビューポートに応じて情報密度を調整します。 デスクトップではメタデータを階層的に表示できます。タブレットではグループ化をよりコンパクトにします。幅の狭い画面では段階的に情報を開示し、CTA を折り返さないようにします。

拡張ルール — 製品の領域に合わせて彩度を調整します。条件付きスロットが使われない状態になっていないか監査します。同一ビューポート内で情報が重複していないか確認します。サイトではなくプリミティブを修正します。コンテンツを装飾する前にクロームを落ち着かせます。視覚ゾーンごとにブランドカラーの要素は 1 つにします。アクティブだからといってレイアウトを強調しすぎないでください：references/live-read.md §拡張ルールを参照してください。

スタイル変更時に避ける、よくある既定の選択肢。 指示がないと、モデルは同じようなスタイルを選びがちです。Inter／Roboto、すべてのコントロールでピル型ボタン、等幅フォントまたは「01 / 02 / 03」のセクションラベル、クリーム色／オフホワイトのキャンバス、紫のグラデーション、均等な 3 枚のカード、見出し内のイタリック体の強調語などです。代わりに、リポジトリ独自のフォント、角丸、カラーパレットのトークンを使ってください。最初の案がこれらのいずれかに当てはまる場合は、作業記録に明記して差し替えてください。

---

ワークフローのチェックリスト

コピーして進捗を管理します。

UI ENHANCE /<route-or-component>
- [ ] 0. DOMAIN: product class -> colour-tier + density-tier (see Domain Colour Tier)
- [ ] 1. RECON: route, component tree, data fields, tokens, primitives, wrappers
- [ ] 2. CONTENT RANK: primary, secondary, metadata, actions, ambient
- [ ] 3. LIVE READ: 1440 / 1024 / 800 screenshots + DOM rect measurements
- [ ] 4. PAIN MAP: crowding, dead space, weak hierarchy, dup info, wrapper collapse,
 conditional-slot zero-state, monochromatic surfaces, hard cuts, bland motion
- [ ] 5. COMPOSITION PLAN: move, group, pin, crop, reveal, fade, animate
- [ ] 6. IMPLEMENT: primitive-level fixes first, smallest site-level diffs after
- [ ] 7. VERIFY: three viewports + DOM uniformity + squint-for-colour-distinction
 + reduced motion + dark/light if supported
- [ ] 8. WRITE-UP: before pain -> design principle -> after behavior

---

ステップ 1 - 調査：既存のビジュアルシステムを把握する [自由度：高]

ルート／コンポーネントを最後まで読んでから、以下を確認します。

• レイアウトプリミティブ：Card、Section、Drawer、Tabs、Badge、Button、 Tooltip、グリッド／リストのヘルパー。
• スタイルシステム：Tailwind の設定、CSS 変数、デザイントークン、テーマコンテキスト、 アニメーションユーティリティ、既存の角丸／影。
• データの形状：利用可能なすべてのフィールド。特に、現在タイトルに押し込まれているものやモーダル内に隠れているメタデータ。
• データソース：API エンドポイント、ローダー／アクション、データベーススキーマ、キャッシュキー、 バックエンドのステータス列挙型、バリデーションエラー、権限、ライフサイクルイベント。これらを使えば、UI のフィードバックを装飾的なものではなく、実際の状態に基づくものにできます。
• 既存のコメント：「DO NOT」、「avoid」、「deprecated」、「design」、 「layout」、「spacing」、「motion」、「overflow」を検索します。

簡潔なコンポーネントマップを出力します。

<Page>
|-- Header - title, context, primary action
|-- Body/Grid/List - main content
|-- Detail/Drawer - progressive disclosure
`-- Footer/Chrome - metadata, controls, scroll status

また、グリッドセルから描画される子要素までの間にある、すべてのラッパー／レイアウトプリミティブを列挙します。例：Tooltip、Trigger、Popover、Slot、 AnimatedDiv、Tippy、motion.div など。それぞれの既定の display、 width、flex-shrink を記録します。ラッパーの折りたたみによる不具合はここに隠れていることが多く、ステップ 6 の プリミティブ優先の修正 も、ここで判断します。

---

ステップ 1.5 - ドメインの色と密度ティア [HIGH freedom]

色に手を加える前に、まず製品のカテゴリを特定します。同じ /8 の色合いでも、金融ダッシュボードでは「高級感があり控えめ」と感じられる一方、学習アプリでは「単調で活気がない」と感じられます。ティアを選び、一貫して適用してください。1つの製品内でティアを混在させてはいけません。

ティア	例	サーフェスの背景色	アクセントの塗り	カテゴリ別の色相の使い方	出典
A — 鮮やか／ゲーミフィケーション	Duolingo、Drops、Habitica、Strava、子ども向け／学習、フィットネス、カジュアルゲーム	/15–/25 のグラデーション＋/30–/40 のリング	単色のトークン（bg-success、bg-cta）、単色背景に白文字	意味のあるカテゴリごとに異なる色相を割り当てる（success/error/streak/xp/info/premium）。色そのものがゲーミフィケーションです	Duolingo のデザインシステム、Figma 2026 トレンドレポート
B — 表現豊かなコンシューマー向け	Spotify、遊び心のあるサーフェスを持つ Notion、Robinhood のオンボーディング、コンテンツ／ライフスタイルアプリ	/10–/18 のグラデーション＋/20–/28 のリング	半単色（bg-cta/85）	3～5 種類のセマンティックカラーを使い、装飾的なパレットは控えめにする	Spotify、Notion
C — 生産性向け／プロツール	Linear、GitHub、Vercel、Figma のクローム、デザインツール	/6–/12 の色合い＋/15 のリング	1つのアクセント＋4つのセマンティック状態	アクセントは主要なアクション用に限定し、セマンティック状態はステータスにのみ使用する	Linear、Radix
D — 控えめ／データ密度が高い	Stripe ダッシュボード、AWS コンソール、オブザーバビリティ／金融／管理／医療	ほぼニュートラルなサーフェス。ステータスピルにのみ /4–/8 を使用	CTA 用のアクセントは1つ。セマンティック状態は4種類（success/warn/error/info）	色はデータのシグナルに限定し、クロームは無彩色に保つ — NN/g の 60-30-10	Stripe、ColorArchive の SaaS ダッシュボード

ティアの見分け方（デザインを始める前に実施）：

1. 製品のマーケティングコピー、README、またはオンボーディングを読みます。「play、streak、level、fun、journey、daily、habit、master」などの語があればティア A または B、「workspace、dashboard、report、audit、query、pipeline」などの語があればティア C または D です。
2. 既存の主要な CTA を確認します。彩度の高い単色に大きな影があれば A、落ち着いた単色なら B/C、アウトラインまたはゴーストが中心なら D です。
3. セマンティック状態のトークン（success、warning、error、info と、アプリ固有の xp、streak、premium、ai、tone-1..6）を確認します。ブランド上の意味を持つセマンティックカラーが5色を超える場合はティア A です。基本の4色だけならティア C/D です。

ティアの不一致は、コンシューマー向けアプリで「単調」というフィードバックにつながる、見落とされがちな最大の原因です。 ティア A の製品にティア D の /8 の色合いを使うと、すべてのトークンが技術的には「正しく」ても、色あせて AI 生成のように見えてしまいます。

---

ステップ 2 - レイアウトの前にコンテンツの順位を決める [HIGH freedom]

表示されるすべての要素を分類します。

順位	意味	デフォルトの扱い
主要	ページの主題	最も大きなスケール、最も強いコントラスト、最も広いスペース
二次	主要要素の解釈を助ける	主要要素の近くに、小さくまとめて配置
メタデータ	日付、件数、統計、ステータス	タイトルの積み重ねではなく、フッター／レール／テーブル列に固定
アクション	ユーザーが実行できること	対象の近くに配置し、安定したタップ領域を確保して、折り返さない
環境要素	ブランド、雰囲気、装飾的なシグナル	背景、マスク、低コントラストにし、削除可能にする

ルール：

• すべてが主要なら、主要なものは何もありません。
• メタデータが見出しを圧迫する場合は、下部の帯、サイドレール、テーブル列、ツールチップ、または詳細ドロワーに移動します。
• アクションが折り返される場合は、段階的に短縮するか、アイコン＋ツールチップにします。
• グリッドに使われていないスペースがある場合は、コンテンツを追加する前に、スパン、密度の高い配置、アスペクト比、またはコンテンツの配置を調整します。

---

Step 3 - ライブ確認 [自由度低 — 指示どおりに実行]

次のページを確認します。

1440 x 900 desktop composition
1024 x 700 tablet / split-screen stress
800 x 700 narrow desktop / large mobile stress

各ビューポートについて、次の点を記録します。

• 最初に目を引く要素。
• 混み合っていると感じる箇所。
• 空いている、またはバランスが悪いと感じる箇所。
• 折り返しや省略表示があるラベル。
• スクロール領域の端が唐突に切れているか、穏やかに示されているか。
• ホバー／フォーカス状態で操作可能であることが説明されているか。
• コンソール／実行時のエラー。

目を細めて確認します。スクリーンショットを頭の中でぼかしても、ページの主要な領域がサイズ、コントラスト、グループ分け、余白によって見分けられる必要があります。

次に、4 つのサブパスを実行します。

• 3a 目を細めて 2 回確認 — 階層（「最初にどこへ目が引きつけられるか」）とカテゴリ（「色や形だけで関連項目を見分けられるか」）を確認します。A/B ティアのタイルはぼかしても異なる色相に見え、D ティアはほぼ均一に見える必要があります。
• 3b DOM 均一性ゲート — 繰り返し要素の rect を取得します。共通の grid-cols-N 親の下で幅の差が 1px を超える場合、ラッパーの崩れです。ラッパーを修正してください。
• 3c 条件付きスロットのゼロ状態確認 — 任意スロットを、それぞれ現実的な最小限のコンテンツでレンダリングします。min-h／aspect-ratio の下限が残っている場合、そのスロットは不要な領域を占めています。
• 3d 情報重複スキャン — 1 画面内で 2 回以上表示されるデータをすべて列挙します。表示場所は 1 つに統一してください。 rect スクリプト、ラッパー崩れの原因、画面内スキャンの例については、references/live-read.md §Step 3 を参照してください。

---

Step 4 - 構成の調整 [自由度高]

次の順に調整することをおすすめします。

1. 減らす：繰り返し表示されるヒント、重複ラベル、重要度の低いアイコン、ノイズになる UI、念のためのメタデータを削除します。
2. まとめる：近接させ、共通の領域に配置して、関連要素がひとまとまりに見えるようにします。グループ間の間隔を広げ、グループ内の間隔を狭めます。
3. 固定する：統計情報、コードのメタデータ、タイムスタンプ、進捗状況をカードのフッター、サイドレール、下部の帯、固定表示の要約、または列に移動します。
4. 段階的に表示する：役立つ場合に限り、ホバー、フォーカス、タブ、アコーディオン、ドロワー、詳細パネル、「もっと見る」などを使って副次的なコンテンツを表示します。
5. バランスを調整する：カードの幅、グリッドの密度、アスペクト比、順序、配置を変更し、重要な項目に十分なスペースを確保して、空白が意図的に見えるようにします。
6. 境界を和らげる：強制的な切り抜きを、フェード、マスク、スクロールシャドウ、カーテン、固定表示のグラデーション、またはビューポートに応じた端の処理に置き換えます。
7. アニメーションを加える：静的な構成が機能するようになってから、マイクロインタラクションを追加します。

---

隠れた失敗パターン（見つけにくいもの）

これらは「ユーザーが指摘したのに、最初の確認では見落とした」パターンです。フィードバックが曖昧でも感覚的には明確（「使いにくい」「ひどい」「スペースの無駄」「高さに一貫性がない」「AI 生成っぽい」）な場合は、装飾に手を加える前にこの一覧を確認してください。各項目には、検出プローブ（確認するポイント）と修正方法（問題を解消する最小限の変更）があります。スタックを問わず適用できます。

検出プローブと修正方法を使って H1〜H16 を確認します。H1 アクティブ状態の見た目の重さの不一致、H2 ルートルートでの UI の同語反復、H3 カードの上に重ねたカード状の UI、H4 ブランドカラーの競合、H5 ライブラリが挿入するインライン幅、H6 無駄または窮屈な 2 列、H7 ホバー時のみの操作可能性、H8 UI に組み込まれたヒット領域、H9 古いデータ優先度、H10 aria-current の欠落、H11 動きを妨げるアニメーション、H12 コンテンツがないのに領域を確保するスロット、H13 ラッパー崩れのタイル、H14 画面内の重複、H15 単色のサーフェス、H16 左寄せのスタック。 完全なカタログ、パターンライブラリ、プリミティブ優先のパッチルール、動作と実装のルール、計画テンプレート、妥当性チェックについては、references/details.md を参照してください。

さらに読む

• 拡張ルールと Step 3 のサブパス（目を細めた確認、DOM 均一性、ゼロ状態、重複）
• 隠れた失敗パターン H1〜H16、パターンライブラリ、プリミティブ優先のパッチルール、テンプレート、妥当性チェック