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

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

---

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

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

| 参数 | 本项目取值 | 说明 |
|---|---|---|
| 前端框架 | **React 19 + TypeScript** | 代码在 `core/frontend` |
| 构建工具 | **Vite 7** | — |
| 路由方案 | **自研 pathname 路由** `core/frontend/src/routes/route-config.ts`(无路由库,switch 渲染) | 新页面在此加一条,不引路由库 |
| 样式方案 | **纯 CSS**(全局 token + 每页 `*-page.css`,选择器收敛在页面根 class) | 不引 Tailwind / CSS Modules |
| 组件/图标库 | **lucide-react**(图标);无额外 UI 框架 | 只用 lucide,不新增图标库 |
| 设计 token 文件 | **`core/frontend/src/design-restraint.css`**(对应规范 `电商AI平台/design.md`) | 颜色/字号/间距唯一来源;改 token 破坏全站 |
| 基准视口 | **1440×900** | 像素核对(`core/qa/visual-parity/compare-page.mjs`)的视口 |
| 页面文件落位 | **`core/frontend/src/routes/<page>.tsx` + `src/<page>-page.css`** | 与工程目录同构 |
| Mock 数据落位 | **已接真实后端 API**(`core/frontend/src/api.ts`);新页若需 mock,用一层 `getXxx()` 取数函数 | 见 §4 |
| 类型定义文件 | **`core/frontend/src/types.ts`** | mock 字段形状对齐它 |

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

> **本项目(AirShelf)现状**:目标工程已存在 = `core/frontend`;**视觉标准答案** = `电商AI平台/` 的 `*.html` 设计稿 + `design.md` 设计规范。**还原老页面**时逐页对照对应 HTML(像素级);**出新页面**按本规范直接交付 React,不要再画静态 HTML。认证一律用户名+密码、不用邮箱(见根 `CLAUDE.md`)。

## 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 调用**。如果交接时开发需要做超出以上范围的改写，视为设计稿不合格，退回返工。