Files

T

seaislee1209andClaude Opus 4.8 afa8e07154 docs(claude): CLAUDE.md 对齐现状 — core/ 为开发目录、电商AI平台/ 为视觉标准答案

- 根 CLAUDE.md:删死目录(app//v2/);设计铁律从"改HTML/restraint.css"改为"改core/前端React+design-restraint.css";路径速查补 core/ 真实路径;新增认证定调(用户名+密码+邀请制,不用邮箱)
- design/CLAUDE.md:空模板参数表填为 AirShelf 真实值(React19/Vite7/自研路由/纯CSS/design-restraint.css/lucide/1440x900)

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>

2026-06-19 03:10:19 +08:00

6.2 KiB

Raw Permalink Blame History

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 必须长得像真接口

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

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

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

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

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

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

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

7. 与开发的交接标准

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

6.2 KiB Raw Permalink Blame History Unescape Escape