@tinkcarlos/skillora 0.2.0

package/.claude/skills/frontend-design/references/layout-anti-patterns.md

@@ -0,0 +1,582 @@
+# Layout Anti-Patterns & Solutions
+
+防止元素重叠、错乱、大面积空白的完整指南。
+
+---
+
+## 🔴 布局问题快速诊断
+
+```
+┌─────────────────────────────────────────────────────────────────┐
+│  问题诊断流程                                                     │
+├─────────────────────────────────────────────────────────────────┤
+│  元素重叠? → 检查 z-index + position + padding-top              │
+│  元素错乱? → 检查 Flexbox/Grid + min-width: 0                   │
+│  大片空白? → 检查 flex: 1 + min-height + 空状态设计             │
+│  间距不一? → 检查 8px 网格系统 + 组件内外间距                    │
+│  响应式断裂? → 检查 clamp() + auto-fit + 断点测试               │
+└─────────────────────────────────────────────────────────────────┘
+```
+
+---
+
+## 🔴 元素重叠 (Element Overlap)
+
+### 常见原因
+1. 固定定位元素没有预留空间
+2. z-index 管理混乱
+3. 绝对定位滥用
+4. 负margin使用不当
+
+### 解决方案
+
+#### 1. 固定导航栏 + 内容重叠
+
+```css
+/* ❌ 错误: 内容被导航栏遮挡 */
+.navbar { position: fixed; top: 0; }
+.content { /* 没有预留空间 */ }
+
+/* ✅ 正确: 预留导航栏高度 */
+.navbar { position: fixed; top: 0; height: 64px; }
+.content { padding-top: 64px; } /* 或 margin-top: 64px */
+
+/* ✅ 更好: 使用 CSS 变量 */
+:root { --navbar-height: 64px; }
+.navbar { height: var(--navbar-height); }
+.content { padding-top: var(--navbar-height); }
+```
+
+**Tailwind CSS:**
+```html
+<nav class="fixed top-0 h-16 ...">...</nav>
+<main class="pt-16 ...">...</main>
+
+<!-- 浮动导航栏 (推荐) -->
+<nav class="fixed top-4 left-4 right-4 ...">...</nav>
+<main class="pt-20 ...">...</main>
+```
+
+#### 2. z-index 管理
+
+```css
+/* ✅ 定义 z-index 层级系统 */
+:root {
+  --z-dropdown: 10;
+  --z-sticky: 20;
+  --z-fixed: 30;
+  --z-modal-backdrop: 40;
+  --z-modal: 50;
+  --z-popover: 60;
+  --z-tooltip: 70;
+}
+
+.dropdown { z-index: var(--z-dropdown); }
+.navbar { z-index: var(--z-fixed); }
+.modal { z-index: var(--z-modal); }
+```
+
+**Tailwind CSS 层级:**
+| 层级 | z-index | 用途 |
+|------|---------|------|
+| `z-10` | 10 | Dropdown, Popover |
+| `z-20` | 20 | Sticky elements |
+| `z-30` | 30 | Fixed navbar |
+| `z-40` | 40 | Modal backdrop |
+| `z-50` | 50 | Modal, Dialog |
+
+#### 3. 绝对定位替代方案
+
+```css
+/* ❌ 错误: 绝对定位导致重叠 */
+.parent { position: relative; }
+.child1 { position: absolute; top: 0; left: 0; }
+.child2 { position: absolute; top: 0; right: 0; }
+
+/* ✅ 正确: Flexbox 自动分配 */
+.parent { display: flex; justify-content: space-between; }
+.child1, .child2 { /* 自动定位 */ }
+
+/* ✅ 正确: Grid 精确控制 */
+.parent {
+  display: grid;
+  grid-template-columns: auto 1fr auto;
+}
+```
+
+---
+
+## 🔴 元素错乱 (Layout Shift)
+
+### 常见原因
+1. 图片/视频没有预留尺寸
+2. 动态内容加载
+3. 字体加载闪烁
+4. 广告/嵌入内容
+
+### 解决方案
+
+#### 1. 图片尺寸预留
+
+```html
+<!-- ❌ 错误: 没有尺寸，加载时布局跳动 -->
+<img src="photo.jpg" alt="Photo">
+
+<!-- ✅ 正确: 预留尺寸 -->
+<img src="photo.jpg" alt="Photo" width="800" height="600">
+
+<!-- ✅ 更好: aspect-ratio -->
+<img src="photo.jpg" alt="Photo" class="w-full aspect-video object-cover">
+```
+
+```css
+/* ✅ CSS aspect-ratio */
+.image-container {
+  aspect-ratio: 16 / 9;
+  width: 100%;
+}
+.image-container img {
+  width: 100%;
+  height: 100%;
+  object-fit: cover;
+}
+```
+
+#### 2. 骨架屏预留空间
+
+```html
+<!-- ✅ 骨架屏保持布局稳定 -->
+<div class="card">
+  <!-- 加载中 -->
+  <div class="skeleton h-48 w-full rounded-lg"></div>
+  <div class="skeleton h-4 w-3/4 mt-4"></div>
+  <div class="skeleton h-4 w-1/2 mt-2"></div>
+</div>
+```
+
+```css
+.skeleton {
+  background: linear-gradient(90deg, #f0f0f0 25%, #e0e0e0 50%, #f0f0f0 75%);
+  background-size: 200% 100%;
+  animation: shimmer 1.5s infinite;
+}
+@keyframes shimmer {
+  0% { background-position: 200% 0; }
+  100% { background-position: -200% 0; }
+}
+```
+
+#### 3. 字体加载优化
+
+```css
+/* ✅ 防止字体闪烁 */
+@font-face {
+  font-family: 'CustomFont';
+  src: url('font.woff2') format('woff2');
+  font-display: swap; /* 或 optional */
+}
+
+/* ✅ 字体回退尺寸匹配 */
+body {
+  font-family: 'CustomFont', system-ui, sans-serif;
+  font-size-adjust: 0.5; /* 调整回退字体大小 */
+}
+```
+
+---
+
+## 🔴 大面积空白 (Excessive Whitespace)
+
+### 常见原因
+1. 固定高度容器内容不足
+2. 没有使用弹性布局
+3. 空状态没有设计
+4. 响应式断点不合理
+
+### 解决方案
+
+#### 1. 动态高度
+
+```css
+/* ❌ 错误: 固定高度导致空白 */
+.card { height: 400px; }
+
+/* ✅ 正确: 动态高度 */
+.card {
+  height: auto;
+  min-height: fit-content;
+}
+
+/* ✅ 限制最大高度 + 滚动 */
+.card {
+  max-height: 400px;
+  overflow-y: auto;
+}
+```
+
+#### 2. 弹性填充
+
+```css
+/* ✅ 主内容区填充剩余空间 */
+.layout {
+  display: flex;
+  flex-direction: column;
+  min-height: 100vh;
+}
+.header { flex-shrink: 0; }
+.main { flex: 1; } /* 自动填充 */
+.footer { flex-shrink: 0; }
+```
+
+**Tailwind CSS:**
+```html
+<div class="flex flex-col min-h-screen">
+  <header class="shrink-0">...</header>
+  <main class="flex-1">...</main>
+  <footer class="shrink-0">...</footer>
+</div>
+```
+
+#### 3. 空状态设计
+
+```html
+<!-- ✅ 友好的空状态 -->
+<div class="flex flex-col items-center justify-center py-12 text-center">
+  <svg class="w-16 h-16 text-gray-400 mb-4">...</svg>
+  <h3 class="text-lg font-medium text-gray-900">No items yet</h3>
+  <p class="text-gray-500 mt-1">Get started by creating your first item.</p>
+  <button class="mt-4 btn-primary">Create Item</button>
+</div>
+```
+
+#### 4. Grid 自动填充
+
+```css
+/* ✅ 自动填充可用空间 */
+.grid {
+  display: grid;
+  grid-template-columns: repeat(auto-fill, minmax(280px, 1fr));
+  gap: 1.5rem;
+}
+
+/* ✅ 内容少时居中 */
+.grid-center {
+  display: grid;
+  grid-template-columns: repeat(auto-fit, minmax(280px, 1fr));
+  justify-content: center;
+  gap: 1.5rem;
+}
+```
+
+---
+
+## 🔴 间距不一致 (Inconsistent Spacing)
+
+### 间距系统
+
+```css
+/* ✅ 定义间距系统 */
+:root {
+  --space-1: 0.25rem;  /* 4px */
+  --space-2: 0.5rem;   /* 8px */
+  --space-3: 0.75rem;  /* 12px */
+  --space-4: 1rem;     /* 16px */
+  --space-5: 1.25rem;  /* 20px */
+  --space-6: 1.5rem;   /* 24px */
+  --space-8: 2rem;     /* 32px */
+  --space-10: 2.5rem;  /* 40px */
+  --space-12: 3rem;    /* 48px */
+  --space-16: 4rem;    /* 64px */
+}
+```
+
+### 组件间距规范
+
+| 组件类型 | 内部间距 | 外部间距 |
+|----------|----------|----------|
+| 按钮 | `px-4 py-2` (16px/8px) | `gap-2` (8px) |
+| 卡片 | `p-4` 或 `p-6` | `gap-4` 或 `gap-6` |
+| 表单字段 | `px-3 py-2` | `space-y-4` (16px) |
+| 列表项 | `px-4 py-3` | `divide-y` |
+| 导航项 | `px-3 py-2` | `gap-1` (4px) |
+| 段落 | - | `space-y-4` |
+| 章节 | `py-12` 或 `py-16` | - |
+
+### 内外间距黄金法则
+
+```
+┌─────────────────────────────────────────────────────────────┐
+│  间距黄金法则                                                │
+├─────────────────────────────────────────────────────────────┤
+│  ✅ 相关元素间距小 (4-8px)                                   │
+│  ✅ 不相关元素间距大 (16-24px)                               │
+│  ✅ 组件内部间距 < 组件外部间距                              │
+│  ✅ 使用 8px 网格系统 (4, 8, 12, 16, 24, 32, 48, 64)        │
+│  ❌ 避免奇数间距 (5px, 7px, 13px)                           │
+│  ❌ 避免过大间距 (>64px 除非是章节分隔)                      │
+└─────────────────────────────────────────────────────────────┘
+```
+
+---
+
+## 🔴 响应式断裂 (Responsive Breakage)
+
+### 断点测试清单
+
+| 断点 | 宽度 | 测试重点 |
+|------|------|----------|
+| Mobile S | 320px | 最小可用宽度 |
+| Mobile M | 375px | iPhone SE/8 |
+| Mobile L | 425px | 大手机 |
+| Tablet | 768px | iPad |
+| Laptop | 1024px | 小笔记本 |
+| Desktop | 1440px | 标准桌面 |
+| 4K | 2560px | 大屏幕 |
+
+### 常见断裂问题
+
+```css
+/* ❌ 错误: 固定宽度在小屏幕溢出 */
+.container { width: 1200px; }
+
+/* ✅ 正确: 响应式宽度 */
+.container {
+  width: min(90%, 1200px);
+  margin-inline: auto;
+}
+
+/* ❌ 错误: 文字在小屏幕太大 */
+h1 { font-size: 48px; }
+
+/* ✅ 正确: 响应式字体 */
+h1 { font-size: clamp(1.5rem, 5vw, 3rem); }
+```
+
+### 响应式检查清单
+
+- [ ] 320px 无水平滚动
+- [ ] 所有文字可读 (≥14px)
+- [ ] 触摸目标 ≥44px
+- [ ] 图片不溢出
+- [ ] 表格可滚动或堆叠
+- [ ] 导航可访问 (汉堡菜单)
+- [ ] 表单可用
+- [ ] 弹窗不超出屏幕
+
+---
+
+## 快速诊断命令
+
+```css
+/* 显示所有元素边界 */
+* { outline: 1px solid red !important; }
+
+/* 检查溢出元素 */
+* { outline: 1px solid rgba(255,0,0,0.2); }
+
+/* 高亮固定/绝对定位元素 */
+[style*="position: fixed"],
+[style*="position: absolute"],
+.fixed, .absolute {
+  outline: 3px solid blue !important;
+}
+```
+
+```javascript
+// 查找溢出元素
+document.querySelectorAll('*').forEach(el => {
+  if (el.scrollWidth > el.clientWidth) {
+    console.log('Horizontal overflow:', el);
+  }
+});
+```
+
+---
+
+## 🔴 防重叠/错乱/空白 CSS 模板
+
+### 基础布局模板 (防止所有常见问题)
+
+```css
+/* ===== 全局重置 ===== */
+*, *::before, *::after {
+  box-sizing: border-box;
+  margin: 0;
+  padding: 0;
+}
+
+/* ===== 根元素 ===== */
+html {
+  scroll-behavior: smooth;
+  -webkit-text-size-adjust: 100%;
+}
+
+body {
+  min-height: 100vh;
+  line-height: 1.5;
+  -webkit-font-smoothing: antialiased;
+}
+
+/* ===== 图片防溢出 ===== */
+img, picture, video, canvas, svg {
+  display: block;
+  max-width: 100%;
+  height: auto;
+}
+
+/* ===== 表单元素继承字体 ===== */
+input, button, textarea, select {
+  font: inherit;
+}
+
+/* ===== 文字防溢出 ===== */
+p, h1, h2, h3, h4, h5, h6 {
+  overflow-wrap: break-word;
+}
+
+/* ===== Flexbox 子元素防溢出 ===== */
+.flex > * {
+  min-width: 0;
+}
+
+/* ===== Grid 子元素防溢出 ===== */
+.grid > * {
+  min-width: 0;
+}
+```
+
+### Tailwind CSS 防重叠模板
+
+```html
+<!-- 固定导航栏 + 内容区 (防重叠) -->
+<nav class="fixed top-0 left-0 right-0 h-16 z-30 bg-white/80 backdrop-blur-xl border-b">
+  <!-- 导航内容 -->
+</nav>
+<main class="pt-16 min-h-screen">
+  <!-- 主内容 (pt-16 = 导航栏高度) -->
+</main>
+
+<!-- 浮动导航栏 (推荐) -->
+<nav class="fixed top-4 left-4 right-4 z-30 rounded-2xl bg-white/80 backdrop-blur-xl shadow-lg">
+  <!-- 导航内容 -->
+</nav>
+<main class="pt-24 min-h-screen">
+  <!-- 主内容 (pt-24 = 导航栏高度 + 边距) -->
+</main>
+
+<!-- 侧边栏布局 (防重叠) -->
+<div class="flex min-h-screen">
+  <aside class="w-64 shrink-0 border-r">
+    <!-- 侧边栏 -->
+  </aside>
+  <main class="flex-1 min-w-0 overflow-auto">
+    <!-- 主内容 (min-w-0 防止溢出) -->
+  </main>
+</div>
+
+<!-- 页脚固定底部 (防空白) -->
+<div class="flex flex-col min-h-screen">
+  <header class="shrink-0">...</header>
+  <main class="flex-1">...</main>
+  <footer class="shrink-0">...</footer>
+</div>
+
+<!-- 卡片网格 (自适应) -->
+<div class="grid grid-cols-1 sm:grid-cols-2 lg:grid-cols-3 gap-6">
+  <div class="min-w-0">卡片1</div>
+  <div class="min-w-0">卡片2</div>
+  <div class="min-w-0">卡片3</div>
+</div>
+
+<!-- 响应式容器 -->
+<div class="w-full max-w-7xl mx-auto px-4 sm:px-6 lg:px-8">
+  <!-- 内容 -->
+</div>
+```
+
+### 常见布局问题一键修复
+
+```css
+/* 问题: 内容被固定导航遮挡 */
+.main-content { padding-top: var(--navbar-height, 64px); }
+
+/* 问题: Flexbox 子元素溢出 */
+.flex-child { min-width: 0; overflow-wrap: break-word; }
+
+/* 问题: 长文本溢出容器 */
+.text-container {
+  overflow-wrap: break-word;
+  word-break: break-word;
+  hyphens: auto;
+}
+
+/* 问题: 图片拉伸变形 */
+.image-container {
+  aspect-ratio: 16 / 9;
+}
+.image-container img {
+  width: 100%;
+  height: 100%;
+  object-fit: cover;
+}
+
+/* 问题: 页脚不在底部 */
+.page-wrapper {
+  display: flex;
+  flex-direction: column;
+  min-height: 100vh;
+}
+.main-content { flex: 1; }
+
+/* 问题: 弹窗超出屏幕 */
+.modal {
+  max-width: min(90vw, 500px);
+  max-height: 90vh;
+  overflow-y: auto;
+}
+
+/* 问题: 表格在移动端溢出 */
+.table-container {
+  overflow-x: auto;
+  -webkit-overflow-scrolling: touch;
+}
+```
+
+---
+
+## 🔴 交付前布局检查清单
+
+```markdown
+## 布局检查清单
+
+### 元素重叠检查
+- [ ] 固定导航栏: 内容区有 pt-16/pt-20
+- [ ] 浮动元素: 有 top-4 left-4 right-4 边距
+- [ ] z-index: dropdown(10) < navbar(30) < modal(50)
+- [ ] 无绝对定位滥用
+
+### 元素错乱检查
+- [ ] 图片有 aspect-ratio + object-fit
+- [ ] Flexbox 子元素有 min-width: 0
+- [ ] 长文本有 overflow-wrap: break-word
+- [ ] 使用 clamp() 响应式尺寸
+
+### 空白检查
+- [ ] 主内容区使用 flex: 1
+- [ ] 页脚固定底部
+- [ ] 空状态有设计
+- [ ] 无固定高度导致空白
+
+### 间距检查
+- [ ] 使用 8px 网格系统
+- [ ] 组件内间距 < 组件外间距
+- [ ] 无奇数间距 (5px, 7px, 13px)
+
+### 响应式检查
+- [ ] 320px 测试通过
+- [ ] 768px 测试通过
+- [ ] 1024px 测试通过
+- [ ] 1440px 测试通过
+- [ ] 无水平滚动
+```
+