# 前端设计

面向 Web 前端、H5、后台管理、官网、落地页、CMS 模板页面、品牌视觉、Banner、图标和社交媒体图片，提供从需求理解、设计思维、信息架构、视觉设计、交互状态、响应式布局到工程落地和浏览器验证的完整流程。

> 本模板已吸收 UI/UX Pro Max 规则，无外部依赖。设计优先级：无障碍 > 响应式 > 视觉层级 > 一致性 > 性能 > 交互反馈 > 排版 > 色彩 > 动效 > 间距（具体要求见后续步骤）。

## 输入要求

1. **页面/功能目标**（必填）：页面要解决什么用户问题或业务目标
2. **目标用户**（必填）：使用者角色、设备场景、操作频率
3. **内容素材**（可选）：文案、图片、品牌色、Logo、现有页面
4. **技术栈**（可选）：HTML/CSS/JS、Vue、React、Taro、CMS模板等
5. **设计约束**（可选）：品牌规范、兼容浏览器、SEO、性能、无障碍要求
6. **设计资产类型**（可选）：页面、组件库、品牌规范、Banner、图标、社媒图、数据图表

## 执行流程

### 第一步：需求与场景分析

- 明确页面核心目标和转化路径
- 识别用户角色、设备、访问入口和关键任务
- 明确交付类型：官网/后台/H5/表单/列表/详情/仪表盘/CMS模板/品牌规范/Banner/图标/社媒图
- 标注不确定信息，必要时先向用户确认

```
✓ 前端场景分析:
- 页面类型: [类型]
- 设计资产: [页面/品牌/Banner/图标/社媒图]
- 目标用户: [角色]
- 核心任务: [任务]
- 主要设备: [桌面/移动/自适应]
```

### 第二步：设计思维与 UX 策略

- 使用双钻模型：发现问题 → 定义问题 → 构思方案 → 交付方案
- 必要时输出用户画像、用户旅程、痛点、HMW 问题陈述
- 营销页可使用 AIDA：注意 → 兴趣 → 欲望 → 行动
- 数据页必须选择合适图表：柱状/折线/漏斗/热力/雷达/树图等，并说明理由
- 明确首屏价值主张、主 CTA、用户三次点击内的目标路径

### 第二步点五：快速原型与草图

在进入完整信息架构前，对关键页面输出低保真原型，快速对齐视觉预期，减少后期返工。

**适用条件**（满足任一即启用）：

- 首次设计该页面/组件，无现存参考
- 用户需求描述少于 30 字且无设计参考图
- 涉及多步骤交互流程

**输出内容**：

1. **线框图**：用 ASCII 或 Markdown 表格绘制关键页面的区块布局，标注每个区块的内容和优先级
2. **交互流**：用箭头文本描述关键路径的页面跳转和状态变化
3. **关键决策点**：标注哪些设计选择需要用户确认（如导航方式、列表 vs 卡片、弹窗 vs 新页面）

**输出格式**：

```
┌─────────────────────────────┐
│  Header (Logo + 导航)       │  ← P0
├─────────────────────────────┤
│  Hero / 核心操作区          │  ← P0
├─────────────────────────────┤
│  内容区 (列表/卡片/表单)    │  ← P1
├─────────────────────────────┤
│  Footer                     │  ← P2
└─────────────────────────────┘

交互流: 列表页 → 点击[新建] → 表单页 → 提交 → 列表页(刷新+提示)
待确认: 列表用表格还是卡片？筛选放顶部还是侧栏？
```

此步骤产出未经视觉润色，仅用于结构对齐。用户确认骨架后进入第三步细化。

### 第三步：信息架构与内容层级

- 梳理页面区块：Header / Hero / 内容区 / CTA / Footer 等
- 明确信息优先级：首屏必须传达什么，次级内容如何展开
- 定义导航、面包屑、筛选、分页、标签等结构
- 对 CMS 页面，明确模板变量和字段来源
- 对 Banner/社媒图，明确主标题、副标题、CTA、Logo、背景、视觉焦点和安全区

### 第四步：视觉风格、品牌与设计系统

定义可落地的设计系统，而不是只描述“好看”：

| 维度      | 产出                                               |
| --------- | -------------------------------------------------- |
| 设计风格  | 风格名称、适用场景、不适用场景、关键视觉特征       |
| 色彩      | 主色、辅助色、背景色、状态色、文本色、暗色模式覆盖 |
| 字体      | 字体配对、字号层级、行高、字重、标题/正文/注释     |
| 间距      | 4/8px 栅格或项目现有 spacing token，组件/分区间距  |
| 圆角/阴影 | 卡片、按钮、浮层、输入框规范                       |
| 图标/图片 | 图标风格、图片比例、alt、占位、压缩和导出策略      |
| 组件      | Button/Input/Card/Table/Dialog/Toast 等            |
| 品牌      | Logo 安全距离、最小尺寸、禁用规则、品牌语气        |

设计系统必须采用三级 token 思路：

```css
/* 原始 Token */
--color-blue-600: #2563eb;
--space-4: 1rem;

/* 语义 Token */
--color-primary: var(--color-blue-600);
--spacing-section: var(--space-12);

/* 组件 Token */
--button-bg: var(--color-primary);
--card-padding: var(--space-6);
```

#### CSS/SCSS 工程约束

| 规则       | 要求                                                                                                                  |
| :--------- | :-------------------------------------------------------------------------------------------------------------------- |
| 嵌套深度   | ≤3 层，禁止过度嵌套导致特异性膨胀                                                                                     |
| z-index    | 统一管理，定义层级常量：`--z-dropdown:100` / `--z-sticky:200` / `--z-overlay:300` / `--z-modal:400` / `--z-toast:500` |
| 单位优先级 | `rem` > `vh/vw/%` > `px`；字体/间距走 rem，布局走百分比或 vw                                                          |
| 公共样式   | 变量/mixin/函数抽离到 `variables.scss`/`mixins.scss`，组件内禁止重复定义                                              |
| 行内样式   | 禁止；特殊情况需注释说明理由                                                                                          |
| 硬编码颜色 | 禁止；必须走 CSS 变量或设计 token                                                                                     |

### 第五步：组件、交互状态与资产规格

每个可交互元素必须覆盖状态：

- 默认 / Hover / Focus / Active / Disabled
- Loading / Empty / Error / Success
- 表单校验错误、异步提交、防重复提交
- 弹窗、抽屉、提示、确认二次操作
- 后台管理必须考虑批量操作、筛选重置、分页保留
- 长任务必须设计 AJAX 渐进式防卡死交互：Init 创建任务、Step 分批执行、Poll 轮询状态
- Banner 必须定义尺寸、主视觉、主标题、副标题、CTA、Logo 和安全区
- 图标必须定义尺寸、线宽、圆角、填充/描边、SVG title/aria 策略
- 社媒图必须定义平台尺寸、文字安全区、导出格式和品牌一致性

#### Init-Step-Poll 前端交互规范

| 阶段      | 前端动作                               | UI 状态                        |
| --------- | -------------------------------------- | ------------------------------ |
| Init      | 提交参数，禁用按钮，创建任务           | `queued`，显示初始化中         |
| Step      | 循环请求或由 Poll 驱动分批执行         | `running`，显示进度条/当前批次 |
| Poll      | 轮询任务状态，不重复提交表单           | 显示百分比、失败数、日志摘要   |
| Done      | 停止轮询，展示结果和下一步操作         | `success`，允许下载/查看/刷新  |
| Failed    | 停止轮询，展示错误和重试入口           | `error`，允许重试/复制错误     |
| Cancelled | 停止轮询，展示已取消状态和重新发起入口 | `cancelled`，允许重新发起/返回 |

**交互约束**：

- 轮询间隔建议 800-2000ms，页面隐藏时降频或暂停
- 连续失败 3 次必须停止轮询并提示网络/服务异常
- 用户离开页面前，如任务仍在运行，应提示任务可在后台继续或确认取消
- 禁止用户重复点击造成重复任务；按钮必须有 disabled/loading 状态
- 进度必须可感知：百分比、已处理/总数、当前步骤、失败数至少提供两项
- 取消后状态变为 `cancelled`，必须停止轮询并禁止继续提交 Step / Poll；允许重新发起或返回

### 第六步：响应式与兼容性设计

| 断点         | 设计重点                                          |
| ------------ | ------------------------------------------------- |
| `sm` 640px   | 移动端单列布局、触控热区不小于 44px、底部操作优先 |
| `md` 768px   | 平板双列/折叠侧栏、表格横向滚动                   |
| `lg` 1024px  | 桌面信息密度、快捷操作、固定筛选/侧栏             |
| `xl` 1280px  | 大屏内容宽度控制，避免行长过宽                    |
| `2xl` 1536px | 宽屏留白、网格扩展、数据看板布局                  |

兼容性要求：

- 避免依赖实验性 CSS，除非明确允许
- 表格、长文本、图片必须定义溢出策略
- CMS 模板需兼容目标站点现有 CSS 作用域，避免全局污染

### 第七步：可访问性、安全性与可用性检查

#### 可访问性

- 颜色对比度至少达到 WCAG AA
- 表单控件必须有 label 或 aria-label
- 键盘可访问：Tab 顺序、Focus 样式、Esc 关闭浮层
- 图片必须有 alt；装饰图可用空 alt
- 动画必须可降级，避免强闪烁和过度动效
- 交互反馈需在 100ms 内可感知，长任务必须有 Loading 或进度提示
- 空状态不得为空，必须提供说明、引导或 CTA

#### 前端安全

| 威胁       | 防护措施                                                                                            |
| :--------- | :-------------------------------------------------------------------------------------------------- |
| XSS        | 用户输入输出必须 `htmlspecialchars()` / `v-text` / `dangerouslySetInnerHTML` 审查；富文本白名单过滤 |
| CSRF       | 状态变更请求必须带 Token；Cookie `SameSite=Strict`                                                  |
| 敏感信息   | 禁止明文存储密钥/Token 于前端代码或 localStorage；敏感数据仅存 HttpOnly Cookie                      |
| 接口权限   | 前端路由守卫 + 后端接口鉴权，禁止仅靠前端隐藏按钮                                                   |
| 第三方脚本 | CDN 资源必须 `integrity` + `crossorigin`，禁用不可信第三方 JS                                       |

### 第八步：前端实现方案

根据项目技术栈输出可执行实现方案：

- HTML 语义结构
- CSS 命名与作用域策略（BEM/CSS Modules/Scoped CSS/Tailwind/项目现有规范）
- 组件拆分：页面组件、业务组件、基础组件
- 状态管理：本地状态、URL查询参数、全局状态
- 数据接口：字段映射、空值处理、错误提示
- CMS模板：模板标签、字段转义、缓存清理、静态资源路径
- 长任务交互：Init/Step/Poll 接口字段、轮询间隔、取消/重试策略
- 组件库选择：按项目技术栈选择原生、Tailwind、shadcn/ui、Ant Design、Element Plus 等，并说明取舍
- 品牌/Banner/图标/社媒图：输出 HTML/CSS/SVG 或设计参数，不把设计资产停留在文字描述

#### 项目目录规范

通用前端项目结构（按技术栈调整）：

```
src/
├── api/          # 接口请求层，按模块拆分
├── assets/       # 静态资源（图片/字体/图标）
├── components/   # 公共组件
├── composables/  # 组合式函数（Vue）/ 自定义 Hooks（React）
├── constants/    # 常量与枚举
├── hooks/        # 业务 Hooks
├── layouts/      # 布局组件
├── pages/        # 页面组件
├── router/       # 路由配置
├── store/        # 状态管理
├── styles/       # 全局样式、变量、mixin
├── types/        # TypeScript 类型定义
├── utils/        # 工具函数
└── App.vue / main.ts
```

#### 命名规范

| 类别           | 规则               | 示例                               |
| :------------- | :----------------- | :--------------------------------- |
| 组件文件       | 大驼峰             | `UserList.vue`、`OrderDetail.tsx`  |
| 工具/页面/样式 | 短横线             | `user-info.ts`、`index.scss`       |
| 变量           | 小驼峰             | `userList`、`isLoading`            |
| 常量           | 全大写+下划线      | `MAX_COUNT`、`API_BASE_URL`        |
| 布尔           | is/has/should 前缀 | `isVisible`、`hasPermission`       |
| 函数           | 动词开头           | `getUserInfo()`、`handleSubmit()`  |
| 事件处理       | handle 前缀        | `handleClick`、`handleChange`      |
| CSS 类名       | 短横线 / BEM       | `user-card`、`card__title--active` |

#### 代码质量基线

| 语言           | 规则                                                                             |
| :------------- | :------------------------------------------------------------------------------- |
| **通用**       | const/let 禁止 var；禁止魔法数字→抽常量；嵌套 ≤3 层；早返回消除 else             |
| **JavaScript** | 箭头函数优先；async/await 优先；数组用 map/filter/reduce                         |
| **TypeScript** | 必须定义接口/类型；禁止 any→用 unknown；函数参数+返回值必标注类型                |
| **Vue**        | 组件名多单词；props 定义 type/default/validator；computed 禁止副作用；watch 慎用 |
| **React**      | 函数式+Hooks；禁止循环/条件中使用 Hooks；状态扁平化；事件 handle 开头            |

#### ESLint / Prettier 基线配置

| 规则       | 值                 |
| :--------- | :----------------- |
| 缩进       | 2 空格             |
| 引号       | 单引号             |
| 分号       | 强制末尾分号       |
| 文件末尾   | 保留一个空行       |
| 未使用变量 | error              |
| console    | warn（生产 error） |
| 尾逗号     | es5 模式           |
| 行宽       | 100 字符           |

#### 性能实现规范

| 类别      | 规则                                                                            |
| :-------- | :------------------------------------------------------------------------------ |
| 图片      | 压缩 + WebP 格式；`loading="lazy"` 懒加载；响应式 `srcset`                      |
| 组件/路由 | 路由懒加载 `() => import()`；非首屏组件异步加载                                 |
| 高频事件  | scroll/resize/input 必须防抖（300ms）或节流（100ms）                            |
| 大列表    | >100 条必须虚拟滚动，禁止全量渲染 DOM                                           |
| 渲染优化  | `React.memo`/`useMemo`/`computed` 减少冗余渲染；避免在 render 中创建新对象/函数 |
| 首屏      | 关键 CSS 内联，非关键资源 `async/defer`；控制首屏请求数                         |

### 第九步：浏览器验证

前端交付必须有验证证据：

| 验证项   | 方法                                                 |
| -------- | ---------------------------------------------------- |
| 视觉还原 | 浏览器截图或人工对照                                 |
| 响应式   | 检查移动/平板/桌面断点                               |
| 交互状态 | 点击、输入、提交、错误、空状态                       |
| 控制台   | 无 JS error / 资源 404                               |
| 网络     | 核心接口状态码正确                                   |
| 性能     | 首屏资源不过大，图片尺寸合理                         |
| A11y     | 对比度、键盘导航、aria/label                         |
| 设计资产 | 尺寸、导出格式、安全区、品牌一致性                   |
| 安全     | XSS 过滤、CSRF Token、敏感信息不入前端代码、接口权限 |
| 长任务   | Init/Step/Poll 状态流正确，轮询可停止、可失败提示    |

### 第十步：记录到项目记忆

前端设计完成后，将关键决策记录到项目记忆（参见 `project-memory-management.md`）：

- 记录设计系统 token、字体配对、色板、组件约定和断点规范
- 记录页面结构、交互模式、设计风格和可访问性要求
- 记录品牌规范、Banner尺寸、图标风格、社媒图规格
- 记录 CMS 模板变量、字段映射和静态资源路径约定

## 国际化（i18n）规范

> 当项目需要支持多语言、多区域或跨时区时启用本节。

**启用条件**：项目要求 ≥2 种语言 / 同界面需按地区展示不同格式 / API 提示需按客户端语言切换 / 后台需多语言内容管理。

**核心规则**：

- 所有用户可见文本外置到语言包，不硬编码在组件内
- 语言包键使用 `模块.场景.键` 命名，每个键附注释说明出现位置
- 占位符用插值变量，复数用 ICU MessageFormat，不写三目表达式
- 项目指定 fallback 语言，缺失键时回落到默认语言而非显示键名
- 日期/数字/货币/百分比使用 `Intl.*Format`，时区统一存 UTC 展示时转换
- 语言包结构：`locales/{locale}.json` + `index.js` 加载器按 locale 异步加载

**API 多语言约定**：客户端通过 `Accept-Language` 头或 URL 前缀传递语言；服务端按请求语言返回错误消息和枚举文案；业务枚举值保持语言无关，文案由前端按 locale 映射；API 返回 ISO 8601 时间戳和原始数字，格式化由前端处理。

**验证要点**：所有可见文本已外置 / 复数占位符使用 ICU 规则 / 缺失键有 fallback / 至少完成 2 种语言完整覆盖校验。

## 输出格式

````markdown
## 前端设计方案

### 1. 页面目标

- **页面类型**: [官网/后台/H5/CMS模板]
- **设计资产**: [页面/品牌/Banner/图标/社媒图]
- **目标用户**: [用户角色]
- **核心任务**: [一句话说明]

### 2. UX策略

- **设计模型**: [双钻/AIDA/用户旅程/其他]
- **首屏价值主张**: [说明]
- **主CTA**: [说明]

### 3. 信息架构

| 区块     | 内容   | 优先级   | 说明   |
| -------- | ------ | -------- | ------ |
| [区块名] | [内容] | P0/P1/P2 | [说明] |

### 4. 视觉与品牌规范

| 项目          | 值                  | 用途       |
| ------------- | ------------------- | ---------- |
| 设计风格      | [风格]              | [适用场景] |
| Primary Color | [颜色/token]        | [用途]     |
| 字体配对      | [标题/正文]         | [用途]     |
| Logo规则      | [安全距离/最小尺寸] | [说明]     |

### 5. 组件与状态

| 组件   | 状态                           | 行为   |
| ------ | ------------------------------ | ------ |
| Button | default/hover/loading/disabled | [行为] |

### 6. 设计资产规格

| 资产   | 尺寸/格式 | 安全区 | 导出要求 |
| ------ | --------- | ------ | -------- |
| Banner | [尺寸]    | [说明] | [格式]   |
| Icon   | [尺寸]    | [说明] | SVG/PNG  |

### 7. 响应式策略

| 断点   | 布局   | 注意事项 |
| ------ | ------ | -------- |
| mobile | [布局] | [说明]   |

### 8. 实现说明

```[语言/框架]
[关键结构或组件代码]
```

### 9. 验证清单

| 检查项     | 状态        | 证据        |
| ---------- | ----------- | ----------- |
| 响应式     | 通过/未通过 | [截图/步骤] |
| 控制台错误 | 通过/未通过 | [结果]      |
| 可访问性   | 通过/未通过 | [结果]      |
| 安全性     | 通过/未通过 | [结果]      |
````

## 质量标准

- 不得只给抽象审美描述，必须给出可执行的布局、组件、状态和 token
- 必须说明设计风格、色彩、字体、间距、品牌和组件规则
- 品牌/Banner/图标/社媒图请求必须输出尺寸、导出格式、安全区和验收标准
- 关键交互必须覆盖 Loading/Empty/Error/Disabled 状态
- 长任务必须采用 Init → Step → Poll，前端必须提供进度、错误、重试/取消和防重复提交
- 移动端触控热区不得小于 44px
- 表单必须包含校验规则和错误提示
- 输出到页面的用户内容必须转义，CMS 模板必须避免 XSS
- 图片必须有尺寸、比例、alt 和降级策略
- 必须说明响应式断点和溢出处理
- 前端交付必须包含浏览器验证方法或证据
- CSS 嵌套深度 ≤3，z-index 必须统一管理，颜色禁止硬编码
- 前端安全必须逐项检查：XSS 过滤、CSRF Token、敏感信息不入 localStorage、接口权限后端兜底
- 命名遵循规范：组件大驼峰、工具短横线、布尔 is/has 前缀、函数动词开头
- TypeScript 禁用 any，函数签名必须完整标注类型
- ESLint/Prettier 基线必须输出 2空格/单引号/分号/末尾空行四项

## 失败回退机制

| 步骤                                 | 失败条件                                     | 回退目标                                   | 最大重试 | 不可恢复时升级路径                     |
| ------------------------------------ | -------------------------------------------- | ------------------------------------------ | -------- | -------------------------------------- |
| 第一步：需求与场景分析               | 页面目标或用户角色不清                       | 列出2-3种页面/资产类型假设，由用户选择     | 2        | 输出澄清问题清单，等待用户确认         |
| 第二步：设计思维与 UX 策略           | 用户路径或转化目标不清                       | 使用最小用户旅程和 AIDA 草案               | 1        | 输出 UX 假设清单                       |
| 第三步：信息架构与内容层级           | 内容素材不足                                 | 生成结构骨架并标注待补文案/图片            | 1        | 输出素材缺口清单                       |
| 第四步：视觉风格、品牌与设计系统     | 无品牌规范                                   | 使用中性设计系统，标注可替换 token         | 1        | 要求用户提供品牌色/参考站              |
| 第五步：组件、交互状态与资产规格     | 业务流程或资产规格不完整                     | 覆盖通用状态和标准尺寸，复杂状态标注待确认 | 1        | 输出状态机/资产规格草案                |
| 第六步：响应式与兼容性设计           | 目标设备不明确                               | 默认移动优先 + 桌面增强                    | 1        | 标注兼容范围假设                       |
| 第七步：可访问性、安全性与可用性检查 | 无法测量对比度、安全基线缺失或键盘行为不可用 | 输出检查清单和手动验证步骤                 | 1        | 标注未实测项                           |
| 第八步：前端实现方案                 | 技术栈未知                                   | 输出 HTML/CSS 通用方案，避免框架特定代码   | 0        | 要求用户确认技术栈                     |
| 第九步：浏览器验证                   | 无运行环境                                   | 输出本地验证步骤，标注未截图               | 1        | 等待用户提供运行地址或截图             |
| 第十步：记录到项目记忆               | 项目记忆系统不可用                           | 输出前端设计决策到本地文件                 | 1        | 标注"设计规范未沉淀"，提示用户手动保存 |

## 关联 reference

- **code-generation**（代码生成）— 根据前端设计方案生成页面结构、样式和组件代码
- **code-review**（代码审查）— 审查前端实现的可访问性、性能、安全和状态覆盖
- **test-generation**（测试用例生成）— 生成交互、表单、响应式和组件测试
- **doc-generation**（文档生成）— 将设计系统和组件规范整理为文档
- **cms-development**（CMS二次开发）— CMS模板页面参考其模板变量、输出转义和缓存规范
- **project-memory-management**（项目记忆管理）— 记录设计 token、组件约定和断点规范