shadcn-layouts

shadcn/Tailwind レイアウト

初回から正しく表示される shadcn/Tailwind コンポーネントの生成を支援します。エージェントが生成した UI の多くは、CSS レイアウトのメンタルモデルが不足しているために失敗します。構文エラーではなく、前提の理解不足が原因です。

このスキルを使うタイミング

次の場合にこのスキルを使ってください：

• shadcn/Tailwind レイアウトを作成する
• 高さやスクロールの問題をデバッグする
• flex/grid の問題を修正する
• ページ全体のアプリシェルを設定する

次の場合はこのスキルを使わないでください：

• バックエンドコードを書く
• Tailwind 以外の CSS プロジェクトに取り組む
• デザインする（先に frontend-design を使ってください）

基本原則

CSS レイアウトは制約に基づいて決まります。高さは明示的に指定された祖先から下へ伝わり、幅はコンテンツから上へ伝わります。エージェントが失敗するのは、制約の連鎖を理解せずにクラスを適用するためです。

重要なメンタルモデル

モデル 1：高さの継承チェーン

h-full は height: 100% を意味します。何の 100% でしょうか？ 親の計算済み高さの 100% です。

BROKEN (chain incomplete):
<html>                        
  <body>                      
    <div class="h-full">      

WORKING (chain complete):
<html class="h-full">         
  <body class="h-full">       
    <div class="h-full">      

ルール： 要素から <html> までさかのぼって確認してください。すべての祖先に明示的な高さが必要です。そうでなければ、ビューポート単位（h-screen）を使ってチェーンを断ち切ります。

モデル 2：Flex のオーバーフローに関する注意点

Flex の子要素には暗黙的に min-height: auto が設定されるため、コンテンツサイズより小さく縮小できません。

// BROKEN (won't scroll)
<div className="flex flex-col h-screen">
  <main className="flex-1 overflow-y-auto">  {/* Can't shrink! */}

// WORKING (scrolls correctly)
<div className="flex flex-col h-screen">
  <main className="flex-1 overflow-y-auto min-h-0">  {/* Can shrink */}

ルール： スクロールする Flex の子要素には min-h-0 が必要です。縮小させない子要素には shrink-0 が必要です。

モデル 3：Grid の親子の役割分担

Grid は親に定義します。子要素はセルを占めるだけです。

// BROKEN
<div className="grid-cols-3">           {/* Missing 'grid'! */}

// WORKING
<div className="grid grid-cols-3">      {/* 'grid' enables grid-cols-* */}

ルール： 方向やテンプレートのクラスを機能させるには、その前に親で flex または grid を宣言する必要があります。

モデル 4：スクロールコンテナの寸法

スクロールコンテナがスクロールするタイミングを判断するには、明示的な寸法が必要です。

// BROKEN (never scrolls)
<ScrollArea>  {/* No height constraint */}

// WORKING (flex-constrained)
<div className="flex flex-col h-screen">
  <ScrollArea className="flex-1 min-h-0">

診断状態

SL1：高さのチェーンが切れている

症状： 要素がつぶれる、h-full が機能しない 修正： html までさかのぼって確認し、高さを追加するか h-screen を使います

SL2：Flex のオーバーフローが妨げられている

症状： スクロールできない、コンテンツがはみ出す 修正： スクロールする Flex の子要素に min-h-0 を追加します

SL3：Grid の構造が間違っている

症状： アイテムが列ではなく縦に積み重なる 修正： 親に grid grid-cols-* があることを確認します

SL4：スタイルが適用されない

症状： コンポーネントにスタイルがない、色が正しくない 修正： Tailwind の content パスと globals.css の CSS 変数を確認します

SL5：コンポーネントの依存関係が不足している

症状： 「Module not found」、機能が動作しない 修正： npx shadcn add [component] を実行し、ピア依存関係をインストールします

よくあるレイアウトパターン

ページ全体のアプリシェル

// layout.tsx
<html lang="en" className="h-full">
  <body className="h-full">{children}</body>
</html>

// page.tsx
<div className="flex h-full">
  <aside className="w-64 shrink-0 border-r overflow-y-auto">
    <nav>...</nav>
  </aside>
  <main className="flex-1 min-w-0 overflow-y-auto">
    {children}
  </main>
</div>

ヘッダー付きダッシュボード

<div className="flex flex-col h-screen">
  <header className="h-16 shrink-0 border-b">...</header>
  <div className="flex flex-1 min-h-0">
    <aside className="w-64 shrink-0 border-r overflow-y-auto">...</aside>
    <main className="flex-1 min-w-0 overflow-y-auto p-6">
      {children}
    </main>
  </div>
</div>

カードグリッド

<div className="grid grid-cols-1 md:grid-cols-2 lg:grid-cols-3 gap-6">
  {items.map(item => (
    <Card key={item.id}>
      <CardHeader><CardTitle>{item.title}</CardTitle></CardHeader>
      <CardContent>{item.content}</CardContent>
    </Card>
  ))}
</div>

アンチパターン

高さを思い込む

祖先のチェーンを確認せずに h-full を使うことです。 修正： html までさかのぼって確認します。チェーンを断ち切るには h-screen を使います。

オーバーフローを無視する

Flex の子要素に min-h-0 を設定せずに overflow-y-auto を追加することです。 修正： Flex の子要素を縮小させるには min-h-0 が必要です。

インポートパスを推測する

shadcn/ui のようなインポートパスを推測することです。 修正： エイリアスは components.json で確認します。通常は @/components/ui/* です。

複合コンポーネントを単純化しすぎる

複合コンポーネントをフラット化することです（DialogTrigger や DialogContent を含まない Dialog など）。 修正： 必要なネスト構造を維持します。

生成前のチェックリスト

• インポートエイリアスがわかっている（@/components/ui/*）
• html に h-full がある
• body に h-full または min-h-full がある
• スクロールコンテナに明示的な高さがある
• スクロールする Flex の子要素に min-h-0 がある
• 固定要素に shrink-0 がある

関連スキル

• frontend-design - 実装前のデザイン上の判断
• react-pwa - React アプリ向けの PWA 機能