page-structure

Page Structure and Wireframes

Applicable Scenarios

Structural design of a single functional page
Patterns such as list pages, detail pages, form pages, etc.
Content hierarchy and arrangement of primary/secondary actions
Page skeleton specifications for frontend developers

Core Principles

1. 页面目标先行
   每个页面只解决 1~3 个核心目标
   不要让一个页面承担过多

2. 用户视线流动
   F 模式 / Z 模式 / 古登堡图
   按用户阅读顺序排列内容

Clear primary/secondary distinction A page has only 1 primary action Secondary actions are de-emphasized Dangerous actions are isolated
Content first Content-driven design, not decoration-driven


## 5 个关键问题

每个页面必须回答：

```text
1. 页面目标：这个页面帮助用户完成什么？
2. 核心信息：用户必须先看到什么？
3. 主操作：用户最重要的动作是什么？
4. 次操作：哪些动作可以弱化？
5. 反馈区域：系统如何告诉用户结果？

Common Page Patterns

List Page

顶部：筛选 + 搜索 + 主操作（如"新建"）
中间：列表本身（表格 / 卡片 / 时间轴）
底部：分页

状态：
  - 加载中
  - 空列表（无数据）
  - 有数据
  - 错误（加载失败）
  - 无权限

Detail Page

顶部：返回 + 标题 + 状态徽章 + 主操作
左/中：核心信息分组展示
右：辅助信息 / 相关操作 / 历史记录
底部：危险操作（删除）

状态：
  - 加载中
  - 详情数据
  - 资源不存在
  - 无权限
  - 已删除

Form Page

顶部：标题 + 进度（多步表单）
中间：表单字段（按重要性分组）
底部：提交 + 取消 + 保存草稿

状态：
  - 默认（空）
  - 有数据（编辑模式）
  - 校验中
  - 校验失败（字段级错误）
  - 提交中（loading）
  - 提交成功
  - 提交失败

Dashboard

顶部：时间筛选 + 全局指标
中间：图表区（按重要性排列）
右侧：最新动态 / 待办

状态：
  - 加载中
  - 数据正常
  - 部分数据缺失
  - 完全无数据

Output Format

Page Structure Description

## 页面：[页面名]

### 基本信息

- 页面目标：[1 句话]
- 用户角色：[谁用]
- 进入路径：[从哪进入]
- 视觉风格：[来自 visual-style skill]

### 内容层级

┌──────────────────────────────────┐ │ Top: [content] │ ├──────────────────────────────────┤ │ Main area: [content] │ │ │ │ - Core information: │ │ - Primary action: │ │ │ ├──────────────────────────────────┤ │ Bottom: [secondary action / pagination] │ └──────────────────────────────────┘


### 主要元素

| 元素 | 类型 | 用途 | 优先级 |
|------|------|------|--------|
| 页面标题 | h1 | 标识页面 | P0 |
| 操作按钮 | 按钮组 | 主操作 | P0 |
| 数据列表 | Table | 展示数据 | P0 |
| 筛选器 | Filter | 缩小范围 | P1 |
| 分页 | Pagination | 数据导航 | P1 |

### 状态说明

| 状态 | 触发条件 | 显示内容 | 用户行动 |
|------|---------|---------|---------|
| 加载中 | 页面初始加载 | Skeleton + Spinner | 等待 |
| 有数据 | 加载成功 | 完整列表 | 浏览/操作 |
| 空状态 | 无数据 | 空状态图 + 引导文案 + 主操作 | 创建第一项 |
| 错误 | 加载失败 | 错误信息 + 重试按钮 | 重试 |
| 无权限 | 权限校验失败 | 权限提示 + 联系管理员链接 | 申请权限 |

### 异常处理

- 网络错误：[处理方式]
- 表单校验失败：[处理方式]
- 操作冲突：[处理方式]

### 响应式要求

- 桌面端 (>1024px)：[布局]
- 平板 (768-1024px)：[布局]
- 移动端 (<768px)：[布局]

Workflow

1. 读取 PRD / 用户故事
2. 确定页面目标（不超过 3 个）
3. 列出必要内容元素
4. 按重要性排序
5. 选择页面模式（列表/详情/表单/仪表盘）
6. 设计内容层级（顶/中/底 或 左/中/右）
7. 区分主次操作
8. 列出所有状态（用 component-states skill）
9. 检查响应式
10. 输出页面结构说明

Quality Self-Check

□ 页面目标是否清晰（1~3 个）
□ 是否只有 1 个主操作
□ 内容层级是否合理（重要内容靠上）
□ 是否覆盖了所有状态
□ 异常情况是否定义
□ 响应式是否考虑
□ 前端能否据此实现

Common Pitfalls

Too many page goals——a page tries to do everything
Multiple primary actions——users do not know which one to click
Dangerous actions not isolated——"Delete" placed in the main area
Missing empty state——users see a blank screen when entering for the first time
Missing error state——nothing is displayed when loading fails
Responsiveness not considered——desktop design breaks on mobile
No visual flow——content is scattered and disordered

Supporting Templates

templates/page-spec-template.md — General page structure description (including four patterns: list/detail/form/dashboard)
templates/wireframe-spec-template.md — Wireframe description template
templates/design-brief-template.md — Design brief template (project entry)

Collaboration with Other Skills

上游：
  user-flow → 提供流程节点
  information-architecture → 提供页面在整体中的位置

平行：
  component-states → 详细定义每个状态
  responsive-design → 详细定义响应式规则
  visual-style → 视觉风格指引

下游：
  design-handoff → 交接给前端