shadcn-layouts

shadcn/Tailwind 布局

帮助生成能一次就正确渲染的 shadcn/Tailwind 组件。多数由 Agent 生成的 UI 都会失败，因为缺少对 CSS 布局工作原理的理解——问题不是语法错误，而是认知上的盲区。

何时使用此技能

在以下情况下使用此技能：

• 创建 shadcn/Tailwind 布局
• 调试高度或滚动问题
• 修复 flex/grid 问题
• 搭建全页应用外壳

以下情况请勿使用此技能：

• 编写后端代码
• 处理非 Tailwind CSS 项目
• 进行设计（请先使用 frontend-design）

核心原则

CSS 布局由约束决定。高度从显式设置高度的祖先元素向下传递。宽度则由内容向上决定。Agent 会失败，是因为它们应用类名时不了解约束链。

关键认知模型

模型 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 内容路径以及 globals.css 中的 CSS 变量

SL5：缺少组件依赖

症状： “Module not found”，功能异常 修复： 执行 npx shadcn add [component]，安装 peer 依赖

常见布局模式

全页应用外壳

// 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 打破继承链。

忽视溢出

添加 overflow-y-auto，却没有为 Flex 子元素设置 min-h-0。 修复： Flex 子元素需要 min-h-0 才能收缩。

猜测导入路径

猜测 shadcn/ui 之类的导入路径。 修复： 检查 components.json 中的别名。通常是 @/components/ui/*。

扁平化复合组件

扁平化复合组件（例如使用 Dialog，却没有 DialogTrigger/DialogContent）。 修复： 保留必需的嵌套结构。

生成前检查清单

• 已知导入别名（@/components/ui/*）
• html 设置了 h-full
• body 设置了 h-full 或 min-h-full
• 滚动容器具有显式高度
• Flex 滚动子元素设置了 min-h-0
• 固定元素设置了 shrink-0

相关技能

• frontend-design - 实现前的设计决策
• react-pwa - React 应用的 PWA 功能