@gong-ym/ai-spec-auto 0.2.3

package/.agents/skills/domains/web/ui-verification/rules/errors-css-priority.md

@@ -0,0 +1,50 @@
+---
+title: CSS 优先级覆盖问题
+impact: HIGH
+impactDescription: 组件样式被页面级样式覆盖，布局失效
+tags: errors, css, priority, specificity, modules
+---
+
+## CSS 优先级覆盖问题
+
+**错误模式**：组件样式被覆盖
+
+| 错误模式 | 典型表现 | 根本原因 | 避免方法 |
+|---------|---------|----------|----------|
+| **组件样式被覆盖** | 组件布局失效（如 flex 变成 block） | 页面级样式覆盖了组件内部样式 | 检查 CSS 优先级，使用更具体的选择器或 CSS Modules |
+
+**Incorrect（页面级样式覆盖组件样式）：**
+
+```css
+/* 页面级样式 */
+.card {
+  display: block; /* 覆盖了组件的 flex */
+}
+
+/* 组件内部样式 */
+.card {
+  display: flex; /* 被页面级样式覆盖 */
+}
+```
+
+**Correct（使用 CSS Modules 或更具体的选择器）：**
+
+```css
+/* 使用 CSS Modules */
+.card {
+  display: flex;
+}
+
+/* 或使用更具体的选择器 */
+.page .card {
+  display: flex;
+}
+```
+
+**验收时检查**：
+- [ ] 组件样式是否被页面级样式覆盖（如 `display: block` 覆盖了 `display: flex`）？
+- [ ] 传入的 `className` 是否会覆盖组件内部的关键样式？
+- [ ] 是否使用了 CSS Modules 的类名冲突检查？
+
+**验收时特别关注**：
+- 检查 CSS 优先级覆盖问题（组件样式是否被页面级样式覆盖）

package/.agents/skills/domains/web/ui-verification/rules/errors-flex-column-width.md

@@ -0,0 +1,46 @@
+---
+title: 换行后列宽不一致
+impact: MEDIUM
+impactDescription: Flex 布局换行后列宽不一致
+tags: errors, layout, flex, grid, column-width
+---
+
+## 换行后列宽不一致
+
+**错误模式**：换行后列宽不一致
+
+| 错误模式 | 典型表现 | 根本原因 | 避免方法 |
+|---------|---------|----------|----------|
+| **换行后列宽不一致** | 第一行和第二行的卡片宽度不同 | Flex 布局每行独立计算 | 使用 Grid 而非 Flex 来保证列宽一致 |
+
+**Incorrect（Flex 布局，换行后列宽不一致）：**
+
+```css
+.flex-container {
+  display: flex;
+  flex-wrap: wrap;
+}
+
+.flex-item {
+  flex: 1 1 280px; /* Flex 每行独立计算，列宽可能不一致 */
+}
+```
+
+**Correct（Grid 布局，列宽一致）：**
+
+```css
+.grid-container {
+  display: grid;
+  grid-template-columns: repeat(auto-fill, minmax(280px, 1fr));
+  gap: 16px;
+}
+```
+
+**验收时检查**：
+- [ ] 列表换行后列宽是否一致（使用 Grid）？
+
+**看到设计稿时，默认不会出现以下反审美的效果**：
+- 换行后列宽不一致
+
+**相关规则**：
+- `writing-list-layout.md` - 横向列表布局规则

package/.agents/skills/domains/web/ui-verification/rules/errors-flex-layout.md

@@ -0,0 +1,46 @@
+---
+title: Flex 布局问题
+impact: HIGH
+impactDescription: Flex 不铺满、留空白
+tags: errors, layout, flex, flex-grow, width
+---
+
+## Flex 布局问题
+
+**错误模式**：Flex 不铺满、留空白
+
+| 错误模式 | 典型表现 | 根本原因 | 避免方法 |
+|---------|---------|----------|----------|
+| **Flex 不铺满、留空白** | 横向列表右侧留大片空白 | 使用了 `flex: 0 1 fixed-width`，不允许增长 | 使用 `flex-grow: 1` 或 `flex: 1 1 min-width` |
+
+**Incorrect（Flex 不允许增长）：**
+
+```css
+.flex-item {
+  flex: 0 1 280px; /* 不允许增长，右侧留空白 */
+}
+```
+
+**Correct（Flex 允许增长）：**
+
+```css
+.flex-item {
+  flex: 1 1 minmax(280px, 1fr); /* 允许增长，铺满宽度 */
+}
+
+/* 或 */
+.flex-item {
+  flex-grow: 1; /* 允许增长 */
+  flex-shrink: 1;
+  flex-basis: 280px;
+}
+```
+
+**验收时检查**：
+- [ ] Flex 布局需要铺满时是否使用了 `flex-grow: 1`，而非 `flex: 0 1 fixed-width`？
+
+**验收时特别关注**：
+- 检查 Flex 布局是否正确使用了 `flex-grow`
+
+**相关规则**：
+- `writing-list-layout.md` - 横向列表布局规则

package/.agents/skills/domains/web/ui-verification/rules/errors-grid-container-width.md

@@ -0,0 +1,44 @@
+---
+title: Grid 容器宽度问题
+impact: HIGH
+impactDescription: Grid 一行只有一个元素，列表竖向排列
+tags: errors, layout, grid, container, width
+---
+
+## Grid 容器宽度问题
+
+**错误模式**：Grid 一行只有一个
+
+| 错误模式 | 典型表现 | 根本原因 | 避免方法 |
+|---------|---------|----------|----------|
+| **Grid 一行只有一个** | 列表竖向排列，一行只有一个元素 | Grid 容器宽度不确定，`auto-fill` 只算出一列 | 确保 Grid 容器有明确宽度（如 `width: 100%`） |
+
+**Incorrect（Grid 容器宽度不确定）：**
+
+```css
+.grid-container {
+  /* 缺少 width，auto-fill 可能只算出一列 */
+  display: grid;
+  grid-template-columns: repeat(auto-fill, minmax(280px, 1fr));
+}
+```
+
+**Correct（Grid 容器有明确宽度）：**
+
+```css
+.grid-container {
+  width: 100%; /* 必须明确宽度 */
+  display: grid;
+  grid-template-columns: repeat(auto-fill, minmax(280px, 1fr));
+  gap: 16px;
+}
+```
+
+**验收时检查**：
+- [ ] Grid 容器是否有明确宽度（如 `width: 100%`），否则 `auto-fill` 可能只算出一列？
+
+**验收时特别关注**：
+- 检查 Grid 容器是否有明确宽度
+
+**相关规则**：
+- `writing-list-layout.md` - 横向列表布局规则

package/.agents/skills/domains/web/ui-verification/rules/errors-page-container-width.md

@@ -0,0 +1,39 @@
+---
+title: 页面容器宽度限制错误
+impact: HIGH
+impactDescription: 右侧大片留白，影响视觉体验
+tags: errors, layout, container, max-width, responsive
+---
+
+## 页面容器宽度限制错误
+
+**错误模式**：页面容器宽度限制
+
+| 错误模式 | 典型表现 | 根本原因 | 避免方法 |
+|---------|---------|----------|----------|
+| **页面容器宽度限制** | 右侧大片留白 | 写死 `max-width`，未考虑响应式 | 除非设计稿特别说明，否则不限制 `max-width` |
+
+**Incorrect（写死 max-width）：**
+
+```css
+.page-container {
+  max-width: 1200px; /* 写死宽度，未考虑响应式 */
+  margin: 0 auto;
+}
+```
+
+**Correct（自适应宽度）：**
+
+```css
+.page-container {
+  width: 100%; /* 自适应视口宽度 */
+  padding: 0 16px; /* 可选：添加内边距 */
+}
+```
+
+**验收时检查**：
+- [ ] 页面容器是否有不必要的 `max-width` 限制？
+- [ ] 是否有右侧大片留白的问题？
+
+**相关规则**：
+- `writing-page-container-width.md` - 页面容器宽度规则

package/.agents/skills/domains/web/ui-verification/rules/tools-browser-navigation.md

@@ -0,0 +1,53 @@
+---
+title: 浏览器工具打开页面指南
+impact: HIGH
+impactDescription: 使用浏览器工具查看实际页面效果
+tags: tools, browser, navigation, playwright, cursor
+---
+
+## 浏览器工具打开页面指南
+
+**核心原则**：验收必须以「实际页面效果 vs 设计稿」为准，必须使用浏览器工具查看目标页面。
+
+### 在 Cursor 中优先使用 `@Browser`
+
+**操作步骤**：
+1. 使用 Browser 的导航（如 `browser_navigate`）前往目标 URL（例如 `http://localhost:5222/craft-sheet`）
+2. 等待页面加载完成
+3. 确认页面已加载完成、无报错，能够看到需要验收的区域
+
+**工具说明**：
+- **Browser**（@Browser，Cursor 专用）：在 Cursor IDE 中可用于打开目标页面、截取页面截图、获取页面快照（DOM/元素）等；**在 Cursor 中优先使用**。
+
+### 仅当不在 Cursor 或 Browser 不可用时，使用 Playwright MCP
+
+**操作步骤**：
+1. 调用 Playwright MCP 提供的导航工具（如 `browser_navigate`）前往目标 URL
+2. 等待页面加载完成
+
+**工具说明**：
+- **Playwright MCP**：用于在任何支持 MCP 的环境中打开目标页面、截图（整页或元素）、获取页面快照（如可访问性树）、查找元素并执行点击/输入/滚动/表单提交等交互；也可在需要时配合设置 cookies/localStorage 或模拟登录来访问受保护页面。**仅当不在 Cursor 或 Browser 不可用时使用**。
+
+### 获取实际页面的可比对信息
+
+**截图比对**：
+- 在 Cursor 中优先用 Browser 的 `browser_take_screenshot` 对目标页面（或关键区域）截图
+- 无 Browser 时用 Playwright MCP 的截图工具
+- 用途：与设计稿同区域截图并排对比
+
+**元素/快照比对**：
+- 在 Cursor 中优先用 Browser 的 `browser_snapshot` 获取页面结构、元素位置与尺寸
+- 无 Browser 时用 Playwright MCP 的快照/可访问性树工具
+- 用途：与设计稿（.pen/Figma）中对应节点坐标、尺寸、样式逐项对比
+
+**建议**：先做**整体或分区域截图**，与设计稿截图对比，发现差异后再用**元素快照**精确定位（如某块 padding、某字体大小）。
+
+**验收时检查**：
+- [ ] **按钮高度、宽度**：必须用浏览器工具实际查看渲染效果，不能仅凭代码推测
+- [ ] **对齐效果**：必须用浏览器查看实际对齐效果
+- [ ] **hover/active 状态**：必须用浏览器实际触发查看
+- [ ] **响应式表现**：必须用浏览器在不同视口下查看
+
+**相关规则**：
+- `errors-button-dimensions.md` - 按钮尺寸问题
+- `tools-design-guidelines.md` - 设计稿工具使用指南

package/.agents/skills/domains/web/ui-verification/rules/tools-design-guidelines.md

@@ -0,0 +1,53 @@
+---
+title: 设计稿工具使用指南（Pencil/Figma）
+impact: HIGH
+impactDescription: 使用设计稿工具获取可比对信息
+tags: tools, design, pencil, figma, mcp
+---
+
+## 设计稿工具使用指南（Pencil/Figma）
+
+**核心原则**：验收时必须获取设计稿侧的可比对信息，与实现页进行对比。
+
+### 设计稿类型与工具选择
+
+验收时：用 **Cursor Browser**（优先）或 **Playwright MCP**（无 Browser 时）获取实际页面截图/快照，再根据设计稿来源选择：
+
+- 设计稿为 `.pen` 时，用 **Pencil MCP** 获取设计稿截图或节点信息
+- 设计稿为 Figma 链接时，用 **Figma MCP** 获取对应截图或节点信息
+- 二者与实现页比对得出结论
+
+### 设计稿为 .pen（Pencil 设计稿）
+
+**工具**：**Pencil MCP**
+
+**操作**：
+- 对指定节点或画布截图（`get_screenshot`）
+- 获取布局结构（`snapshot_layout`）
+- 与实现页的截图或快照对应比对
+
+**工具说明**：
+- **.pen** 是 **Pencil** 的设计稿文件后缀
+- **Pencil MCP**：用于 `.pen` 设计稿，可查看设计稿细节、对指定节点或画布截图（如 `get_screenshot`）、获取布局结构（如 `snapshot_layout`）等，与实现页截图或快照对照
+
+### 设计稿为 Figma 链接
+
+**工具**：**Figma MCP**
+
+**操作**：
+- 从链接中解析 file key / node id
+- 对指定 frame 或节点调用 `get_screenshot`、`get_design_context` 等
+- 获取截图或布局/样式信息
+- 与实现页的截图或快照对应比对
+
+**工具说明**：
+- **Figma 链接**：如 `https://www.figma.com/design/<fileKey>/<fileName>?node-id=...`
+- **Figma MCP**：用于 Figma 设计稿，可从链接中解析 file key / node id，获取指定 frame 或节点的截图与布局/节点信息（如 `get_screenshot`、`get_design_context` 等）
+
+### 设计稿为其它静态图片
+
+**操作**：
+- 直接使用设计稿图片与 `browser_take_screenshot` 的截图并排或叠放对比
+
+**相关规则**：
+- `tools-browser-navigation.md` - 浏览器工具打开页面指南

package/.agents/skills/domains/web/ui-verification/rules/workflow-checklist.md

@@ -0,0 +1,27 @@
+---
+title: 快速检查清单
+impact: HIGH
+impactDescription: 验收流程检查清单
+tags: workflow, checklist, verification
+---
+
+## 快速检查清单
+
+### 验收前
+- [ ] 目标页面 URL 已确认（如 `http://localhost:5222/<route>`）
+- [ ] 设计稿（.pen 或图）可打开，可截图或取元素
+- [ ] 已有对应「UI 分析清单」更佳（作为按顺序比对的检查项列表）
+
+### 验收中（必须落地）
+- [ ] 已用 **Browser** 打开目标页面并获取截图或快照（详见 `tools-browser-navigation.md`）
+- [ ] 已获取设计稿对应区域截图或元素信息（详见 `tools-design-guidelines.md`）
+- [ ] **按从上到下、从左到右、从外到里**的顺序进行排查，**P0（布局、层级、文字、图片）四项无遗漏**（详见 `comparison-*.md`）
+- [ ] 已完成**实际页面 vs 设计稿**的截图比对或元素比对
+- [ ] 差异已按 P0（布局/层级/内容）/P1/P2 分类并写入「UI 问题清单」
+- [ ] **已检查布局常识问题**：页面容器宽度、横向列表铺满、元素完整性、对齐方式等（详见 `writing-*.md` 和 `errors-*.md`）
+
+### 修复后
+- [ ] 已再次用 **Browser** 打开页面并重新与设计稿比对（详见 `tools-browser-navigation.md`）
+- [ ] 问题清单状态与验收结论已更新
+- [ ] 完成「分析不足反思」并考虑反哺 design-analysis（详见 `workflow-reflection.md`）
+- [ ] **已检查常见错误模式**：CSS 优先级覆盖、Grid 容器宽度、Flex 布局铺满、对齐方式、按钮尺寸等（详见 `errors-*.md`）

package/.agents/skills/domains/web/ui-verification/rules/workflow-problem-list.md

@@ -0,0 +1,56 @@
+---
+title: UI 问题清单文档结构
+impact: HIGH
+impactDescription: 产出可追踪的问题清单文档
+tags: workflow, output, problem-list, template
+---
+
+## UI 问题清单文档结构
+
+### 文档路径
+
+```
+docs/样式还原/<名称>-UI问题清单.md
+```
+
+### 文档结构建议
+
+```markdown
+# <名称> - UI 问题清单
+
+> **参照文档**：`docs/样式还原/<名称>-UI分析清单.md`  
+> **设计稿**：`docs/设计稿/<路径>/<文件名>.pen` 或 Figma 链接  
+> **创建/更新日期**：YYYY-MM-DD
+
+## 一、按区域列问题（区域按从上到下、从左到右顺序排列）
+
+### 区域 A
+| 编号 | 问题描述 | 类型 | 当前实现 | 设计稿要求 | 优先级 |
+|------|----------|------|----------|------------|--------|
+| A1   | ...      | ...  | ...      | ...        | P0/P1/P2 |
+
+## 二、问题统计与修复顺序
+
+| 优先级 | 数量 | 说明 |
+|--------|------|------|
+| P0（布局/层级/内容） | n | 先修，不得遗漏 |
+| P1 | n | 次之 |
+| P2 | n | 可后续 |
+
+建议修复顺序：P0 → P1 → P2；同优先级内按**从上到下、从左到右、从外到里**。
+
+## 三、验收结论（随修复更新）
+
+- [ ] **P0（布局、层级、文字、图片）** 全部修复，且验收时已按从上到下、从左到右、从外到里逐项检查无遗漏
+- [ ] P1 全部修复
+- [ ] P2 已记录/部分修复
+- [ ] 已使用 Browser 进行实际页面与设计稿比对
+- [ ] 还原度自评：___%
+```
+
+### 问题描述要求
+
+- **问题描述**：简短、可操作（如「欢迎语区域整体水平居中」）
+- **当前实现**：现状（如 `align-items: center`）
+- **设计稿/分析清单要求**：明确要求（如「左对齐 flex-start」）
+- **优先级**：便于排期与迭代

package/.agents/skills/domains/web/ui-verification/rules/workflow-reflection.md

@@ -0,0 +1,44 @@
+---
+title: 反思分析不足模板
+impact: MEDIUM
+impactDescription: 反哺 design-analysis，减少同类遗漏
+tags: workflow, reflection, design-analysis
+---
+
+## 反思分析不足（反哺 design-analysis）
+
+### 为什么要反思
+
+UI 问题常暴露「设计稿分析」阶段的遗漏或描述不清。把「哪些问题是因为分析没做到位」总结下来，可补充到 **design-analysis** 的检查项与文档结构中，减少同类遗漏。
+
+### 反思要回答的问题
+
+1. **清单遗漏**：有哪些问题是「分析清单里根本没写」导致的？
+2. **描述不清**：有哪些是「分析清单写了但不具体」导致的？
+3. **步骤或模板**：design-analysis 的步骤或分析清单模板，应做哪些补充或修改？
+4. **设计常识缺失**：有哪些问题是「编写时缺乏主流网页设计常识」导致的？详见 `rules/writing-*.md` 和 `rules/errors-*.md`
+5. **CSS 优先级问题**：是否有组件样式被页面级样式覆盖的问题？详见 `rules/errors-css-priority.md`
+6. **浏览器验证缺失**：哪些细节问题是因为未用浏览器工具实际查看导致的？详见 `rules/tools-browser-navigation.md`
+
+### 反思输出方式
+
+- **短期**：在本次「UI 问题清单」文档末尾增加一节「分析不足反思」，按上面几问简要写出结论
+- **长期**：将共性结论沉淀到 `.agents/skills/design-analysis/SKILL.md`（常见遗漏检查点、文档结构等）
+
+### 反思记录模板
+
+```markdown
+## 分析不足反思（用于完善 design-analysis）
+
+### 清单遗漏
+- 问题：xxx
+- 建议：design-analysis 中增加 xxx
+
+### 描述不清
+- 问题：xxx
+- 建议：分析清单中必填 xxx
+
+### 对 design-analysis 的补充建议
+- [ ] 在常见遗漏检查点中增加：……
+- [ ] 在文档结构中增加：……
+```

package/.agents/skills/domains/web/ui-verification/rules/writing-alignment.md

@@ -0,0 +1,44 @@
+---
+title: 对齐方式规则
+impact: MEDIUM
+impactDescription: 确保图标与文本、按钮等元素的对齐正确
+tags: writing, alignment, flexbox, icon, text
+---
+
+## 对齐方式规则
+
+验收时发现的问题，很多是**编写代码时缺乏主流网页设计常识**导致的。应在实现阶段就主动避免这些反审美的效果，而不是等到验收才发现。
+
+**核心原则**：
+- ✅ **图标与文本的对齐**：检查 `align-items` 值，常见应为 `center`（水平居中）而非 `flex-start`（顶部对齐）
+- ✅ **按钮、卡片等元素的定位**：仔细对照设计稿的 `padding`、`margin`、定位规则
+
+**Incorrect（图标与文本顶部对齐）：**
+
+```css
+.icon-text {
+  display: flex;
+  align-items: flex-start; /* 顶部对齐，视觉不协调 */
+}
+```
+
+**Correct（图标与文本居中对齐）：**
+
+```css
+.icon-text {
+  display: flex;
+  align-items: center; /* 水平居中，视觉协调 */
+}
+```
+
+**验收时检查**：
+- [ ] 图标与文本的对齐方式是否正确（`align-items: center` 而非 `flex-start`）？
+- [ ] 按钮、卡片的 padding、margin、定位是否符合设计稿？
+- [ ] 绝对定位的元素是否正确设置了 `left`、`right`、`top`、`bottom`？
+
+**验收时特别关注**：
+- 必须用浏览器工具实际查看渲染效果（特别是按钮、对齐等细节）
+- 检查对齐方式是否正确设置
+
+**相关规则**：
+- `errors-alignment.md` - 对齐方式错误

package/.agents/skills/domains/web/ui-verification/rules/writing-element-completeness.md

@@ -0,0 +1,63 @@
+---
+title: 元素展示完整性规则
+impact: MEDIUM
+impactDescription: 避免展示不完整的元素，提升视觉体验
+tags: writing, layout, element, overflow, completeness
+---
+
+## 元素展示完整性规则
+
+验收时发现的问题，很多是**编写代码时缺乏主流网页设计常识**导致的。应在实现阶段就主动避免这些反审美的效果，而不是等到验收才发现。
+
+**核心原则**：
+- ❌ **不应展示不完整的元素**（如半截卡片、被裁切的按钮）
+- ✅ **要么完整展示，要么完全不展示**（使用 `overflow: hidden` 配合数量控制，而非视觉截断）
+
+**Incorrect（元素被截断显示）：**
+
+```tsx
+function CardList({ items }: { items: Item[] }) {
+  return (
+    <div className="card-list">
+      {items.map(item => (
+        <Card key={item.id} item={item} />
+      ))}
+    </div>
+  )
+}
+
+/* CSS: 没有控制，导致半截卡片显示 */
+.card-list {
+  display: flex;
+  overflow-x: auto; /* 横向滚动，可能显示半截卡片 */
+}
+```
+
+**Correct（完整展示或完全不展示）：**
+
+```tsx
+function CardList({ items }: { items: Item[] }) {
+  const visibleCount = Math.floor(containerWidth / cardWidth)
+  const visibleItems = items.slice(0, visibleCount)
+  
+  return (
+    <div className="card-list">
+      {visibleItems.map(item => (
+        <Card key={item.id} item={item} />
+      ))}
+    </div>
+  )
+}
+
+/* CSS: 使用 overflow: hidden 配合数量控制 */
+.card-list {
+  display: flex;
+  overflow: hidden; /* 隐藏超出部分 */
+}
+```
+
+**验收时检查**：
+- [ ] 是否有元素被截断显示（半截卡片等）？
+
+**看到设计稿时，默认不会出现以下反审美的效果**：
+- 元素截断

package/.agents/skills/domains/web/ui-verification/rules/writing-list-layout.md

@@ -0,0 +1,75 @@
+---
+title: 横向列表布局规则
+impact: HIGH
+impactDescription: 确保列表铺满宽度，换行后列宽一致
+tags: writing, layout, grid, flex, list
+---
+
+## 横向列表布局规则
+
+验收时发现的问题，很多是**编写代码时缺乏主流网页设计常识**导致的。应在实现阶段就主动避免这些反审美的效果，而不是等到验收才发现。
+
+**核心原则**：
+- ❌ **不应限制一行几个元素而留空白**（如固定列数导致右侧大片空白）
+- ❌ **不应出现元素被截断**（如半截卡片显示）
+- ✅ **应铺满可用宽度**，能放几个就放几个，不够再换行
+- ✅ **换行后应保持列宽一致**（使用 Grid 而非 Flex）
+
+**布局选择指导**：
+
+**Grid**：适合等列宽、多行一致的情况
+
+```css
+/* Correct: 使用 Grid 实现自适应列数 */
+.grid-container {
+  width: 100%; /* 必须明确宽度 */
+  display: grid;
+  grid-template-columns: repeat(auto-fill, minmax(280px, 1fr));
+  gap: 16px;
+}
+```
+
+**Flex**：适合自适应但每行独立计算的情况
+
+```css
+/* Correct: Flex 需要铺满时使用 flex-grow */
+.flex-container {
+  display: flex;
+  flex-wrap: wrap;
+}
+
+.flex-item {
+  flex: 1 1 minmax(280px, 1fr); /* 允许增长 */
+  /* 不要用 flex: 0 1 fixed-width */
+}
+```
+
+**Incorrect（Grid 容器宽度不确定）：**
+
+```css
+.grid-container {
+  /* 缺少 width，auto-fill 可能只算出一列 */
+  display: grid;
+  grid-template-columns: repeat(auto-fill, minmax(280px, 1fr));
+}
+```
+
+**Incorrect（Flex 不铺满，留空白）：**
+
+```css
+.flex-item {
+  flex: 0 1 280px; /* 不允许增长，右侧留空白 */
+}
+```
+
+**验收时检查**：
+- [ ] 横向列表是否铺满宽度，不会留大片空白？
+- [ ] 列表换行后列宽是否一致（使用 Grid）？
+- [ ] 是否有元素被截断显示（半截卡片等）？
+- [ ] Grid 容器是否有明确宽度（如 `width: 100%`），否则 `auto-fill` 可能只算出一列？
+- [ ] Flex 布局需要铺满时是否使用了 `flex-grow: 1`，而非 `flex: 0 1 fixed-width`？
+
+**相关规则**：
+- `errors-grid-container-width.md` - Grid 容器宽度问题
+- `errors-flex-layout.md` - Flex 布局问题
+- `errors-flex-column-width.md` - 换行后列宽不一致

package/.agents/skills/domains/web/ui-verification/rules/writing-page-container-width.md

@@ -0,0 +1,37 @@
+---
+title: 页面容器宽度规则
+impact: HIGH
+impactDescription: 避免右侧大片留白，提升页面自适应能力
+tags: writing, layout, container, responsive, max-width
+---
+
+## 页面容器宽度规则
+
+验收时发现的问题，很多是**编写代码时缺乏主流网页设计常识**导致的。应在实现阶段就主动避免这些反审美的效果，而不是等到验收才发现。
+
+**核心原则**：页面应自适应视口宽度，避免割裂的留白效果。除非设计稿明确要求固定宽度，否则默认不限制 `max-width`。
+
+**Incorrect（写死 max-width 导致右侧大片留白）：**
+
+```css
+.page-container {
+  max-width: 1200px; /* 写死宽度，未考虑响应式 */
+  margin: 0 auto;
+}
+```
+
+**Correct（自适应视口宽度）：**
+
+```css
+.page-container {
+  width: 100%; /* 自适应视口宽度 */
+  padding: 0 16px; /* 可选：添加内边距 */
+}
+```
+
+**验收时检查**：
+- [ ] 页面容器是否有不必要的 `max-width` 限制？
+- [ ] 是否有右侧大片留白的问题？
+
+**相关规则**：
+- `errors-page-container-width.md` - 页面容器宽度限制错误