# UI 设计稿开发规范（通用 CLAUDE.md）

> 把本文件放在 UI 设计稿工作区根目录。适用于任何 Web 项目：你（UI/设计 agent）产出的**不是静态 HTML 画稿，而是可直接并入目标工程的 SPA 页面代码**。
>
> **为什么有这份规范**：曾有项目以静态 HTML 交付设计稿，开发侧被迫做了一整轮"逐字转写 HTML→框架组件 + 像素级核对 + 全站死按钮审计"，成本极高且产生大量稿/码不一致。本规范的唯一目标：**设计稿即代码，交付物零转换并入主工程。**

---

## 0. 项目参数表（每个新项目开工前先填，未填不得动工）

向开发侧确认以下信息并填入。本文件其余部分所有规则引用这张表，不要凭喜好自选：

| 参数 | 本项目取值 | 说明 |
|---|---|---|
| 前端框架 | （如 React 19 / Vue 3 / Svelte） | 必须与目标工程一致；全新项目默认 React + TypeScript |
| 构建工具 | （如 Vite） | 默认 Vite |
| 路由方案 | （目标工程现有方案） | 复用目标工程的路由机制，不自带新路由库 |
| 样式方案 | （如纯 CSS / Tailwind / CSS Modules） | 与目标工程一致；目标工程没有的方案不准引入 |
| 组件/图标库 | （目标工程已有的） | 只用已有的，不新增 UI 框架和图标库 |
| 设计 token 文件 | （如 `src/styles.css` / `tokens.css`） | 颜色、字号、间距的唯一来源 |
| 基准视口 | （如 1440×900） | 像素核对和验收用的视口 |
| 页面文件落位 | （如 `src/routes/` + `src/<page>.css`） | 与目标工程目录同构 |
| Mock 数据落位 | （如 `src/mock/`） | 见 §4 |
| 类型定义文件 | （如 `src/types.ts`，可空） | mock 字段形状的对齐目标 |

> 目标工程尚不存在（全新项目）时：默认 React + TypeScript + Vite + 纯 CSS，并把你定下的取值回填此表，作为后续开发工程的初始约定。

## 1. 交付物形态（最重要的一条）

每个页面的交付物固定为：

| 文件 | 说明 |
|---|---|
| 页面组件 | 一个独立的页面级组件文件，按参数表落位 |
| 页面样式 | 该页专属样式文件，全部选择器收敛在页面根 class 下 |
| Mock 数据 | 该页全部演示数据，集中一个文件 |
| 路由注册 | 在目标工程的路由配置中加一项，页面可直达 |

**明确禁止**：
- ❌ 交付静态 `.html` 文件（任何形式，包括"先 HTML 后转组件"的中间产物）
- ❌ iframe 嵌套原型、截图/图片代替可交互区域
- ❌ jQuery、CDN `<script>`、内联 `<style>` 巨块
- ❌ 引入参数表之外的任何框架、UI 库、CSS 方案、图标库

## 2. 工作区与工程同构

- 设计稿工作区直接以目标工程的前端为模板搭骨架（入口、公共布局、token 文件、路由配置），在其上加页面；`npm run dev`（或等价命令）必须能跑
- 公共骨架（侧栏/导航/页脚/Toast 等）只实现一份并各页复用，不要每页重画
- 全新项目则先搭最小可运行骨架，再出页面

## 3. 视觉规范

- 颜色、间距、字号一律引用参数表指定的 token 文件；**新增 token 必须加进 token 文件并注释用途**，不许在页面样式里写裸色值复制粘贴
- 页面样式顶层必须有唯一根 class（如 `.products-page`），所有规则在其作用域内，防止跨页泄漏；不要重复写 reset
- 布局在基准视口下必须与设计意图逐像素一致，无横向滚动条；这是后续像素核对（pixelmatch 类工具）的验收视口
- 响应式要求由项目参数表注明；未注明时至少保证基准视口完整可用

## 4. 数据规范：mock 必须长得像真接口

这是历史返工的重灾区。规则：

1. 每页 mock 集中放参数表指定的 mock 目录，**禁止把数据硬编码散落在组件 JSX/模板里**
2. 目标工程已有类型定义的，mock 字段形状必须对齐；没有的，先写出 interface/类型再造数据，并在交接说明里标注"需后端提供的接口与字段"
3. 组件一律通过 props 或一层 `getXxx()` 取数函数拿数据——接真后端时只换数据源这一层
4. 列表类数据至少 8 条以上真实感数据（真实语言文案、不同状态混排），并且必须设计并实现 **loading / 空态 / 错误态** 三种 UI

## 5. 交互规范：不许有死按钮

交付页面默认会被行为审计工具**逐个控件真实点击**验收：

- 每个按钮、tab、toggle、下拉、可点卡片，点击后必须有**可观察的状态变化**（切换内容、开弹窗、改样式、出提示——本地 state 实现即可）
- 弹窗/抽屉可开可关（含遮罩点击、Esc）；表单为受控输入并有提交反馈
- 暂时没想好行为的入口：**宁可不画，也不要画一个没有 handler 的假按钮**；确需占位的，统一 `disabled` + 注明"规划中"
- 控制台零 error/warning

## 6. 交付自查清单（每页提交前过一遍）

- [ ] dev server 启动后，该页可通过路由直达
- [ ] 类型检查/构建零错误
- [ ] 基准视口下与设计意图一致，无横向滚动条
- [ ] mock 数据集中存放、字段对齐类型定义、三态齐全
- [ ] 全部可点控件有真实 handler，控制台无报错
- [ ] 页面样式收敛在根 class 下，未污染其他页面
- [ ] 附《接口接入说明》：本页用到哪些数据、对应/期望哪个后端接口、哪些字段是新增

## 7. 与开发的交接标准

设计稿工作区与目标工程目录同构，开发合入一个页面的动作应该只有：**拷贝页面组件 + 样式 + mock 三个文件、路由配置加一行、把 mock 取数层换成真实 API 调用**。如果交接时开发需要做超出以上范围的改写，视为设计稿不合格，退回返工。