visual-hierarchy-refactoring

視覚的階層のリファクタリング

実際の画面またはコンポーネントを取り上げ、目が正しい順序で正しいものに留まるようにリファクタリングします。成果物はリファクタリングされたコードと before/after の階層監査であり、デザイン論評ではありません。統括する原則は、階層はサイズ・太さ・明度のコントラストの関数であり、色は最後の手段である、そして最速の修正は強調の解除である。シグナルを増幅する前にノイズを静めることです。

使用する場面 / 引き継ぎ

• 特定の画面が、まともなトークンを使っているにもかかわらず、雑然としている、平坦、スキャンしづらい、「どこかおかしい」場合に使用します。
• 一貫したトークンがそもそも存在しない場合(すべての修正が新たなマジックナンバーになってしまう)→ まず skills/frontend-design/design-foundation。
• 問題が構造的である場合(カラムのずれ、モバイルでの崩れ)→ skills/frontend-design/layout-system。
• フォントサイズ自体がアプリ全体で混沌としている場合 → skills/frontend-design/typography-system。
• パレットが問題である場合(色相の衝突、至る所でのコントラスト失敗)→ skills/frontend-design/color-system。

ステップ 1 — 対象を調査する

1. 実際のコンポーネントを入手します。 ユーザーが指定した画面のファイルを読みます。指定がなければ、最も重要な 1 つの画面を尋ねてください(これがブロックする唯一の取り込み時の質問です)。環境が許せば、レンダリングするかスクリーンショットを撮ります。
2. 利用可能なトークンを読みます(スペーシングスケール、テキストサイズ、グレーランプ)。すべての修正はこれらを使わなければなりません。
3. コード内の階層の臭いを検出し、数えます:
   • 強調のインフレ: 画面ごとに、太字、色付き、大きい、または枠線付きの要素はいくつあるか?(3 つを超える競合する強調 = 何も強調されていない)
   • 窮屈なスペーシング: 無関係なグループ間の padding/margin が ≤8px
   • 真のグレー / 純黒: #808080 系、#000、色付きサーフェス上の text-gray-500
   • 均一なサイズ: タイトル、本文、メタデータが互いに 1 段階以内
   • 至る所で均等なスペーシング: グループ内とグループ間で同一の gap(ゲシュタルトのグループ化を壊す)
   • 枠線の乱用: スペーシングで分離できるところでのボックス・イン・ボックス

ステップ 2 — 階層監査を構築する

対象画面について、表示されているすべての要素を列挙し、以下を割り当てます:

• 意図された優先度: P1(この画面が存在する理由である 1 つのもの — 1 つ、おそらく 2 つの要素)、P2(補助)、P3(メタデータ/クローム)。
• 現在の視覚的な重み: 大きい / 中程度 / 静か。サイズ、太さ、色、周囲から判断します。

すべての不一致が作業項目です。単一の P1 を特定できない場合は、ユーザーに 1 つ質問してください: 「この画面で、ユーザーが最初にすべきこと、または見るべきものは何ですか?」 — その後、進めます。

ステップ 3 — この順序でリファクタリングする

変更は厳密にこの順序で適用してください — 各パスは次のパスの必要性をしばしば取り除きます。

1. まず余白。 多すぎる状態から始めて、引き締めます。無関係なグループ間の間隔を 2 倍にし、関連する項目は近づけます（ラベルは入力から 8px、フォームグループ間は 24px 以上）。標準のマージンが 16px なら、セクション間は 32〜48px を試してください。間隔はトークンスケールから取る必要があります。
2. P1 に触れる前に P2/P3 を弱める： ラベルから太字を外し、メタデータを中間グレーの段階（gray-500/600）まで明るくし、二次的なコンテンツを囲い込んでいるボーダーや背景を削除し、三次的なアクションは縮小するかアイコン化します。二次ボタンはアウトライン/ゴーストに、破壊的なアクションは確認されるまで控えめにします。
3. 次に P1 を強調する — ノイズが消えれば、通常は 1 つの手だけで済みます。1 段階サイズを上げる、ウェイトを 600→700 にする、最も暗いテキスト段階を使う、または単一の彩度の高い CTA を使う。4 つすべてではありません。
4. コントラストのはしごは色相ではなく明度で： P1 テキスト = 最も暗いグレーの段階、P2 = gray-600/700、P3 = gray-500。色味を帯びたグレーのみ（ブランドの温度に合わせる）— #808080/#000 は決して使いません。彩度の高い色はインタラクティブ要素とステータス用に取っておきます。
5. ゲシュタルトの法則でグループ化する： 近接（間隔が関係性を示す — グループ間のギャップはグループ内のギャップの 2 倍以上）、類似（同一の役割は同一に見える）、共通領域（間隔だけでは役割を果たせない場合にのみカード/背景を使う）。CSS を使った完全な原則セット：references/gestalt-principles.md。
6. サイズ比： 隣接する階層レベルは約 1.25〜1.5 倍異なるようにし、P1 と本文は約 1.5〜2 倍にします。2 つのレベルが互いに 10% 以内にある場合は、それらを統合してください。

正規の before/after（ほとんどの修正の形）

/* BEFORE: cramped, uniform, grey-on-grey */
.card { padding: 8px; }
.card h2 { font-size: 16px; font-weight: 400; color: #666; margin-bottom: 4px; }
.card p  { font-size: 14px; color: #999; line-height: 1.3; }

/* AFTER: room, clear ladder, tinted greys */
.card { padding: var(--space-6); }
.card h2 { font-size: var(--text-xl); font-weight: 600; color: var(--gray-900); margin-bottom: var(--space-2); }
.card p  { font-size: var(--text-base); color: var(--gray-600); line-height: 1.6; }
.card .meta { font-size: var(--text-sm); color: var(--gray-500); }

必要な出力形式

コードと次の監査を提出してください：

## Hierarchy audit — [screen name]
| Element | Intended | Was | Problem | Change |
| Submit button | P1 | quiet (same as Cancel) | competing siblings | solid brand bg; Cancel → ghost |
| Section labels | P3 | loud (bold, dark) | emphasis inflation | weight 400, gray-500 |
| Card metadata | P3 | medium | too prominent | text-sm, gray-500 |
| ... every element with a mismatch |

## Refactored code
[full component/CSS — same styling system, tokens only]

## What changed and why (≤5 bullets)
- [pass applied → effect, e.g. "Doubled inter-group spacing (space-4 → space-8): groups now scannable"]

## Scan test
First / second / third thing the eye hits now: [P1] → [P2] → [P2]. Matches intent: [yes / remaining gap]

品質基準（提出前に確認）

• 画面ごとに P1 はちょうど 1 つで、5 秒のスキャンに勝つ
• 画面ごとに強調要素は 3 つ以下。それ以外はすべて目に見えて控えめ
• 無関係なグループ間のギャップはグループ内のギャップの 2 倍以上。すべての間隔はトークンスケール上
• 結果内のフォントウェイトは 3 つ以下。太字は段落全体に適用しない
• テキストのはしごは色味を帯びたグレーの明度段階を使用。#808080 なし、#000 なし、強調のために新しい色相を導入しない
• 弱められたテキストも WCAG AA（4.5:1）を満たす — 控えめ ≠ 読めない。P3 は大きなサイズでのみ 3:1 まで許容
• 隣接するサイズレベルは 1.25 倍以上異なる。10% 以内の 2 つのレベルは存在しない
• 間隔だけでコンテンツをグループ化できる箇所ではボーダー/ボックスを削除
• すべての変更がトークンを参照している — 新しいマジックナンバーはゼロ

統合

• 消費する：skills/frontend-design/design-foundation のトークン、skills/frontend-design/typography-system のタイプスケール、skills/frontend-design/color-system のグレーランプ、skills/frontend-design/layout-system のページ構造。
• 生成する：skills/frontend-design/component-architecture がライブラリに一般化するリファクタリング済みコンポーネント。コントラストの決定は skills/frontend-design/accessibility-excellence によって検証されます。
• skills/frontend-design/frontend-orchestrator のパスでは、これはトークンが存在した後に実行されます（パス B ステップ 2）、またはマージンレベルの改良として実行されます（パス C）。

参照

• references/gestalt-principles.md — 6 つすべてのゲシュタルト原則（近接、類似、図と地、閉合、対称、共通領域）を CSS の適用例とともに解説し、さらに拡張された before/after リファクタリング例を収録。グループ化の問題が近接だけでは解決しない場合や、より多くの実例が必要な場合に読んでください。