frontend-design.md 24 KB
前端设计
面向 Web 前端、H5、后台管理、官网、落地页、CMS 模板页面、品牌视觉、Banner、图标和社交媒体图片，提供从需求理解、设计思维、信息架构、视觉设计、交互状态、响应式布局到工程落地和浏览器验证的完整流程。
本模板已吸收 UI/UX Pro Max 规则，无外部依赖。设计优先级：无障碍 > 响应式 > 视觉层级 > 一致性 > 性能 > 交互反馈 > 排版 > 色彩 > 动效 > 间距（具体要求见后续步骤）。
输入要求
- 页面/功能目标（必填）：页面要解决什么用户问题或业务目标
- 目标用户（必填）：使用者角色、设备场景、操作频率
- 内容素材（可选）：文案、图片、品牌色、Logo、现有页面
- 技术栈（可选）：HTML/CSS/JS、Vue、React、Taro、CMS模板等
- 设计约束（可选）：品牌规范、兼容浏览器、SEO、性能、无障碍要求
- 设计资产类型（可选）：页面、组件库、品牌规范、Banner、图标、社媒图、数据图表
执行流程
第一步：需求与场景分析
- 明确页面核心目标和转化路径
- 识别用户角色、设备、访问入口和关键任务
- 明确交付类型：官网/后台/H5/表单/列表/详情/仪表盘/CMS模板/品牌规范/Banner/图标/社媒图
标注不确定信息，必要时先向用户确认
✓ 前端场景分析: - 页面类型: [类型] - 设计资产: [页面/品牌/Banner/图标/社媒图] - 目标用户: [角色] - 核心任务: [任务] - 主要设备: [桌面/移动/自适应]
第二步：设计思维与 UX 策略
- 使用双钻模型：发现问题 → 定义问题 → 构思方案 → 交付方案
- 必要时输出用户画像、用户旅程、痛点、HMW 问题陈述
- 营销页可使用 AIDA：注意 → 兴趣 → 欲望 → 行动
- 数据页必须选择合适图表：柱状/折线/漏斗/热力/雷达/树图等，并说明理由
- 明确首屏价值主张、主 CTA、用户三次点击内的目标路径
第二步点五：快速原型与草图
在进入完整信息架构前，对关键页面输出低保真原型，快速对齐视觉预期，减少后期返工。
适用条件（满足任一即启用）：
- 首次设计该页面/组件，无现存参考
- 用户需求描述少于 30 字且无设计参考图
- 涉及多步骤交互流程
输出内容：
- 线框图：用 ASCII 或 Markdown 表格绘制关键页面的区块布局，标注每个区块的内容和优先级
- 交互流：用箭头文本描述关键路径的页面跳转和状态变化
- 关键决策点：标注哪些设计选择需要用户确认（如导航方式、列表 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 思路：
/* 原始 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 种语言完整覆盖校验。
输出格式
## 前端设计方案
### 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、组件约定和断点规范