shadcn-layouts

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

shadcn/Tailwind Layouts

shadcn/Tailwind 布局

Help generate shadcn/Tailwind components that render correctly the first time. Most agent-generated UI fails due to missing mental models about how CSS layout works—not syntax errors, but assumption gaps.

帮助一次性生成能正确渲染的shadcn/Tailwind组件。大多数由Agent生成的UI失败的原因是缺乏对CSS布局工作原理的思维模型——不是语法错误，而是认知偏差。

When to Use This Skill

何时使用此技能

Use this skill when:

Creating shadcn/Tailwind layouts
Debugging height/scroll issues
Fixing flex/grid problems
Setting up full-page app shells

Do NOT use this skill when:

Writing backend code
Working on non-Tailwind CSS projects
Designing (use frontend-design first)

在以下场景使用此技能：

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

请勿在以下场景使用此技能：

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

Core Principle

核心原则

CSS layout flows from constraints. Height flows down from explicit ancestors. Width flows up from content. Agents fail because they apply classes without understanding the constraint chain.

CSS布局由约束条件驱动。高度由上层显式定义的祖先元素向下传递，宽度由内容向上扩展。Agent生成的代码失败通常是因为在不理解约束链的情况下就应用类名。

Critical Mental Models

关键思维模型

Model 1: Height Inheritance Chain

模型1：高度继承链

h-full

means

height: 100%

. 100% of what? 100% of the parent's computed height.

BROKEN (chain incomplete):
<html>                        <!-- no height -->
  <body>                      <!-- no height -->
    <div class="h-full">      <!-- 100% of nothing = 0 -->

WORKING (chain complete):
<html class="h-full">         <!-- 100% of viewport -->
  <body class="h-full">       <!-- 100% of html -->
    <div class="h-full">      <!-- 100% of body = works -->

Rule: Trace from element up to

<html>

. Every ancestor needs explicit height, OR use viewport units (

h-screen

) to break the chain.

h-full

等价于

height: 100%

。100%是相对于什么的？相对于父元素的计算后高度。

BROKEN (chain incomplete):
<html>                        <!-- no height -->
  <body>                      <!-- no height -->
    <div class="h-full">      <!-- 100% of nothing = 0 -->

WORKING (chain complete):
<html class="h-full">         <!-- 100% of viewport -->
  <body class="h-full">       <!-- 100% of html -->
    <div class="h-full">      <!-- 100% of body = works -->

规则： 从目标元素向上追溯到

<html>

。每个祖先元素都需要显式设置高度，或者使用视窗单位（

h-screen

）打破继承链。

Model 2: Flex Overflow Gotcha

模型2：Flex溢出陷阱

Flex children have implicit

min-height: auto

, preventing shrinking below content size.

tsx

// 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 */}

Rule: Flex children that scroll need

min-h-0

. Children that shouldn't shrink need

shrink-0

Flex子元素默认有

min-height: auto

，这会阻止元素缩小到内容尺寸以下。

tsx

// 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

。

Model 3: Grid Parent/Child Separation

模型3：Grid父/子元素分离

Grid is defined on the parent. Children just occupy cells.

tsx

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

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

Rule:

flex

grid

must be declared on parent before direction/template classes work.

Grid布局是在父元素上定义的，子元素仅占据单元格。

tsx

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

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

规则： 必须先在父元素上声明

flex

或

grid

，方向/模板类才能生效。

Model 4: Scroll Container Dimensions

模型4：滚动容器尺寸

Scroll containers need explicit dimensions to know when to scroll.

tsx

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

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

滚动容器需要显式的尺寸才能知道何时触发滚动。

tsx

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

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

Diagnostic States

诊断状态

SL1: Height Chain Broken

SL1：高度链断裂

Symptoms: Elements collapse,

h-full

not working Fix: Trace to html, add heights or use

h-screen

症状： 元素塌陷，

h-full

不生效 修复方案： 向上追溯到html元素，为祖先添加高度或使用

h-screen

SL2: Flex Overflow Blocked

SL2：Flex溢出被阻止

Symptoms: Scroll doesn't work, content overflows Fix: Add

min-h-0

to flex children that scroll

症状： 无法滚动，内容溢出 修复方案： 为需要滚动的Flex子元素添加

min-h-0

SL3: Grid Structure Wrong

SL3：Grid结构错误

Symptoms: Items stack vertically instead of columns Fix: Ensure

grid grid-cols-*

on parent

症状： 元素垂直堆叠而非按列排列 修复方案： 确保父元素上同时有

grid grid-cols-*

类

SL4: Styles Not Applying

SL4：样式未生效

Symptoms: Unstyled components, colors wrong Fix: Check Tailwind content paths, CSS variables in globals.css

症状： 组件无样式，颜色显示错误 修复方案： 检查Tailwind的content路径，以及globals.css中的CSS变量

SL5: Component Dependencies Missing

SL5：组件依赖缺失

Symptoms: "Module not found", functionality broken Fix:

npx shadcn add [component]

, install peer deps

症状： "Module not found"，功能失效 修复方案： 执行

npx shadcn add [component]

，安装对等依赖

Common Layout Patterns

常见布局模式

Full-Page App Shell

整页应用外壳

tsx

// 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>

tsx

// 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>

Dashboard with Header

带头部的仪表盘

tsx

<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>

tsx

<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>

Card Grid

卡片网格

tsx

<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>

tsx

<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>

Anti-Patterns

反模式

The Height Assumption

高度假设

Using

h-full

without verifying ancestor chain. Fix: Trace to html. Use

h-screen

to break chain.

在未验证祖先链的情况下使用

h-full

。 修复方案： 向上追溯到html元素。使用

h-screen

打破继承链。

The Overflow Ignorance

忽略溢出

Adding

overflow-y-auto

without

min-h-0

on flex children. Fix: Flex children need

min-h-0

to shrink.

在Flex子元素上添加

overflow-y-auto

但未添加

min-h-0

。 修复方案： Flex子元素需要

min-h-0

才能缩小。

The Import Guess

猜测导入路径

Guessing import paths like

shadcn/ui

. Fix: Check

components.json

for alias. Usually

@/components/ui/*

猜测类似

shadcn/ui

的导入路径。 修复方案： 查看

components.json

中的别名。通常为

@/components/ui/*

。

The Flat Compound

扁平化复合组件

Flattening compound components (Dialog without DialogTrigger/DialogContent). Fix: Maintain required nesting structure.

将复合组件扁平化（比如使用Dialog但不包含DialogTrigger/DialogContent）。 修复方案： 保持要求的嵌套结构。

Pre-Generation Checklist

生成前检查清单

Import alias known (
```
@/components/ui/*
```
)
html has
```
h-full
```
body has
```
h-full
```
or
```
min-h-full
```
Scroll containers have explicit height
Flex scroll children have
```
min-h-0
```
Fixed elements have
```
shrink-0
```

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