layout-system

レイアウトシステム

ユーザーの実際の画面に対して、動作するモバイルファーストのレイアウトコードを生成します — リファクタリングされたページシェル、グリッド、またはコンポーネントレイアウトであり、CSS のチュートリアルではありません。基本原則: コンテンツが構造を決定する。コンテンツの形に応じて Grid と Flexbox を選択し、コンテンツが崩れる箇所にブレークポイントを置き、残りは柔軟なトラックに吸収させます。

使用する場面 / 引き継ぎ

• ページ構造、配置、レスポンシブ対応、グリッド、重なり/オーバーフローのバグ、ブレークポイント戦略に使用します。
• アプリ全体でスペーシングの値自体が不整合（スケールがない）→ まず skills/frontend-design/design-foundation でトークンを確立します。
• 特定の幅でテキストが読みにくい（行長、可変フォントサイズ）→ skills/frontend-design/typography-system。
• レイアウトは問題ないが画面がごちゃごちゃして見える → skills/frontend-design/visual-hierarchy-refactoring。

ステップ 1 — コードベースを調査する

1. 対象を特定します。 ユーザーが画面やコンポーネントを指定した場合は、それとその CSS を読みます。そうでなければ、主要なレイアウトファイル（**/layout.*、**/App.*、**/*page*、グローバル CSS）を glob します。
2. スタイリングシステムを検出します。 Tailwind クラスか、CSS Modules か、styled-components か — 同じシステムで納品します。
3. レイアウトの臭いを grep し、件数を記録します:
   • width:\s*\d+px|w-\[\d+px\] — 固定幅（崩れの最大の原因）
   • position:\s*absolute でオーバーレイ/バッジ以外 — 座標によるレイアウト
   • float:|margin-top:\s*-|margin-left:\s*- — レガシー/ネガティブマージンのハック
   • @media — 異なるブレークポイント値の数を数えます。4 つを超える異なる min-width はブレークポイントの乱立です
   • overflow-x と 100vw — 横スクロールの疑い
4. 既存のブレークポイントを読みます（Tailwind の screens、またはメディアクエリ）— それが問題でない限り再利用します。
5. スペーシングトークンの有無を確認します — スケールが存在する場合、新しいギャップ/パディングはすべてそれを使わなければなりません。

ステップ 2 — ヒアリング

推測できない場合にのみ、一度にまとめて質問します: どの画面/フローが最も重要か、そして考慮すべき最小と最大のビューポート（デフォルト: 320px〜1440px、コンテンツは約 1200〜1280px で上限）。密度とスタックはコードから推測します。止まらないでください — 対象が指定されコードが見えるなら、前提を述べて構築します。

ステップ 3 — モバイルファーストで構築する。以下の判断ルールに従います

1. 320px の単一カラムから始め、コンテンツがカラムを正当化する箇所にのみカラムを追加します。 デスクトップのデザインを下方向に縮小してはいけません。
2. Grid か Flexbox か:
   • 行と列の両方を揃える必要がある（ページシェル、ダッシュボード、ギャラリー、ラベルを揃えたフォーム）→ Grid。
   • 一方向で、サイズがコンテンツに駆動される（ナビゲーションバー、ボタン行、タグリスト、メディアオブジェクト）→ Flexbox。
   • アイテム数が不明なカードグリッド → Grid で repeat(auto-fit, minmax(min(100%, 280px), 1fr)) — メディアクエリはゼロ。
   • カラムを偽装するためにパーセント幅の子要素で Flexbox を使っているなら、Grid に切り替えます。
3. ページシェル: grid-template-areas を使った Grid。より狭い幅ではエリアを折りたたみます。標準形:

.shell { display: grid; gap: var(--space-4); grid-template-areas: "header" "main" "footer"; }
@media (min-width: 768px) {
  .shell {
    grid-template-columns: 250px minmax(0, 1fr);
    grid-template-areas: "header header" "sidebar main" "footer footer";
  }
  .sidebar { position: sticky; top: 0; height: fit-content; }
}

（minmax(0, 1fr) — 裸の 1fr ではなく — これにより幅の広い子要素がトラックを押し広げられません。） 4. コンテンツからのブレークポイント: 何かが崩れる（行が長すぎる、カラムが詰まりすぎる、孤立した余白）までリサイズし、そこにブレークポイントを置きます。コンポーネントごとに 2〜3 個までに抑えます。プロジェクトの既存のブレークポイントトークンを使います。 5. コンテナクエリ は、コンポーネントが異なる幅のコンテナ（サイドバー内とメイン内の両方のカード）でレンダリングされる場合に使います: ラッパーに container-type: inline-size、コンポーネントに @container (min-width: …)。ビューポートのメディアクエリはページレベルの構造にのみ使います。 6. メディアの比率: aspect-ratio + object-fit: cover。レスポンシブ画像に固定の高さを決して使わないでください。 7. 単位: スペース/タイプには rem、トラックには %/fr/minmax()、テキストの行長には ch、px はボーダーと真にピクセルが関わる事柄にのみ使います。

パターン集の全体（ヒーロー、カードグリッド、サイドバー、レスポンシブナビ、ホーリーグレイル、スティッキーフッター、コンテナクエリのカード）については、references/layout-patterns.md を読んで、再発明するのではなく適応させてください。

ステップ 4 — チェックポイントで検証する

320、375、768、1024、1440 でテストします（レンダリングできない場合は、頭の中で検証します）。確認する項目：横スクロール、押しつぶされたカラム（実コンテンツが ~250px 未満）、45〜75ch の範囲外のテキスト行長、44px 未満のタッチターゲット、固定要素の下に隠れるコンテンツ。

必須の出力形式

コードと次のサマリーを提出します。

## Layout changes
[Refactored files with full code — same styling system as the project]

## Decisions
| Question | Choice | Rule applied |
| Shell | Grid, template-areas | 2-D alignment needed |
| Card list | auto-fit minmax(280px, 1fr) | unknown item count → no media queries |
| Breakpoints | 768px, 1024px (existing tokens) | content broke at sidebar collapse |
| Container queries | card only | renders in 2 container widths |

## Smells removed
| Smell | Where | Replaced by |
| fixed width 960px | Header.tsx | max-width + margin-inline auto |
| ... |

## Verified
320 / 375 / 768 / 1024 / 1440 — [result per width, or "reasoned, not rendered" flagged]

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

• 320px で横スクロールバーが出ない
• コンテナに固定ピクセル幅が一切ない（max-width による上限は可）
• 2 次元は Grid、1 次元は Flexbox — パーセント幅の flex-column によるごまかしは不可
• すべてのブレークポイントで本文の行長が 45〜75ch
• モバイルでタッチターゲットが 44×44px 以上
• すべての余白／パディングがプロジェクトのスペーシングスケールを使用している（新たなマジックナンバーなし）
• コンポーネントごとのブレークポイントが 3 つ以下で、すべてプロジェクトのブレークポイントセット由来
• 視覚的な並べ替え（Grid 配置、order）が DOM／タブ順を乱さない
• メディアに aspect-ratio を使用し、固定高さの画像ボックスがない

統合

• 利用するもの：skills/frontend-design/design-foundation のスペーシングスケールとブレークポイントトークン。
• 生成するもの：skills/frontend-design/typography-system（行長、可変フォントサイズ）と skills/frontend-design/visual-hierarchy-refactoring（余白、グルーピング）が洗練し、skills/frontend-design/component-architecture が再利用可能なレイアウトコンポーネントとしてコード化する、ページシェルとレイアウトパターン。
• 成果物のアクセシビリティは skills/frontend-design/accessibility-excellence によって監査されます。

参考資料

• references/layout-patterns.md — コピーして応用できるパターン：ヒーロー、カードグリッド、サイドバー＋メイン、レスポンシブナビ、ホーリーグレイル、スティッキーフッター、コンテナクエリカード、アスペクト比メディア、およびブレークポイント表。標準的なパターンを構築するときに読みます。