layout-system

布局系统

为用户的实际屏幕编写可用的移动优先布局代码——重构后的页面外壳、网格或组件布局，而不是 CSS 教程。核心原则：内容决定结构。根据内容形态选择 Grid 或 Flexbox，在内容无法容纳时设置断点，并让弹性轨道吸收其余空间。

适用场景 / 转交

• 用于页面结构、对齐、响应式布局、网格、重叠/溢出问题和断点策略。
• 应用中的间距值本身不一致（没有比例体系）→ 先通过 skills/frontend-design/design-foundation 建立设计令牌。
• 某些宽度下文本难以阅读（行长、流体字体）→ skills/frontend-design/typography-system。
• 布局没问题，但屏幕显得杂乱 → skills/frontend-design/visual-hierarchy-refactoring。

步骤 1 — 检查代码库

1. 定位目标。 如果用户指定了屏幕/组件，阅读它及其 CSS。否则，使用 glob 查找主要布局文件（**/layout.*、**/App.*、**/*page*、全局 CSS）。
2. 识别样式系统。 Tailwind 类、CSS Modules 还是 styled-components——交付时沿用相同系统。
3. 搜索布局问题模式并记录数量：
   • width:\s*\d+px|w-\[\d+px\] — 固定宽度（导致布局损坏的首要原因）
   • 非叠加层/徽标中的 position:\s*absolute — 通过坐标布局
   • float:|margin-top:\s*-|margin-left:\s*- — 过时/负外边距技巧
   • @media — 统计不同断点值的数量；不同的最小宽度超过 4 个 = 断点泛滥
   • overflow-x 和 100vw — 可能导致水平滚动
4. 读取现有断点（Tailwind screens 或媒体查询）——除非它们本身有问题，否则沿用。
5. 检查间距令牌——如果已有比例体系，所有新增间隙/内边距都必须使用它。

步骤 2 — 收集需求

仅在无法推断时，一次性询问：最重要的屏幕/流程是什么，以及需要适配的最小和最大视口尺寸（默认：320px–1440px，内容最大宽度约为 1200–1280px）。根据代码推断信息密度和布局结构。不要停滞不前——如果用户指定了目标且代码可见，就说明假设并开始构建。

步骤 3 — 移动优先构建，并遵循以下决策规则

1. 从 320px、单列开始，只有在内容确有需要时才增加列。 绝不要把桌面设计向下压缩。
2. Grid 还是 Flexbox：
   • 行和列都必须对齐（页面外壳、仪表板、图库、标签对齐的表单）→ Grid。
   • 单一方向、尺寸由内容决定（导航栏、按钮行、标签列表、媒体对象）→ Flexbox。
   • 项目数量未知的卡片网格 → 使用 repeat(auto-fit, minmax(min(100%, 280px), 1fr)) 的 Grid——无需媒体查询。
   • 如果使用 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 px 下测试（如果无法渲染，则通过推理检查）。检查：水平滚动、列宽过窄（实际内容宽度低于约 250 px）、文本长度超出 45–75ch、触控目标小于 44 px、内容被粘性元素遮挡。

必需的输出格式

提交代码以及以下摘要：

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

质量标准（提交前检查）

• 在 320 px 下没有水平滚动条
• 容器没有固定像素宽度（允许设置 max-width 上限）
• 二维布局使用 Grid，一维布局使用 Flexbox — 不使用伪造百分比宽度的 Flexbox 列布局
• 每个断点下的正文长度均为 45–75ch
• 移动端触控目标 ≥ 44×44 px
• 所有间距/内边距均使用项目的间距比例（不引入新的随意数值）
• 每个组件最多 3 个断点，且均来自项目的断点集
• 视觉重排（Grid 定位、order）不会打乱 DOM/Tab 顺序
• 媒体使用 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 — 可复制并调整的模式：主视觉区、卡片网格、侧边栏+主内容区、响应式导航、圣杯布局、粘性页脚、容器查询卡片、宽高比媒体，以及断点表。构建任何标准模式时请阅读。