# Design System Site Pixel Parity Mechanism

这份机制只解决一件事：

**不允许再用“已经像素级还原”这种口头结论代替可追溯、可审计、可复核的验收链路。**

当前仓库里真正的问题，不是没人提 Figma，也不是没人提 pixel-perfect，而是下面四层没有被串成强制闸门：

1. `Figma 来源` 有同步，但不是每个 docs 页面都有明确基线
2. `组件实现` 有一部分已经 canonical 化，但很多页面仍挂旧 runtime 组件
3. `展示站页面` 更像 docs demo，不是 Figma frame 的镜像页
4. `视觉验收` 缺少统一的 pass / fail 口径

## 一句话原则

只有同时满足下面四个门槛，页面才可以宣称“通过像素级还原审查”：

1. 有明确的 Figma 基线
2. 页面消费 canonical 语义，而不是 runtime 近似实现
3. 页面布局本身是 Figma frame 还原，而不是文档式 demo 容器
4. 有视觉复核记录，并且状态为 `approved`

缺任何一项，都只能称为：

- `in review`
- `approximation`
- `blocked`

不能称为 pixel-perfect。

## 四层审查门

### Gate 1: Provenance Gate

每个组件页必须先绑定唯一基线：

- `figmaFileKey`
- `figmaPage`
- `figmaComponentSet`
- `figmaNodeId`
- 变体轴是否齐全

如果页面没有对应的 Figma 基线，只能进入 `blocked`，不允许进入像素审查。

### Gate 2: Canonical Gate

组件页只允许用以下两类来源：

- `src/canonical/*`
- 已通过 canonical 审查的生成封装

如果页面直接依赖 `src/components/*` 旧 runtime 组件，这一页只能算：

- `runtime approximation`

可以继续开发，但不能宣称 Figma 1:1。

### Gate 3: Frame Fidelity Gate

页面本身必须区分两种形态：

1. `docs-demo`
   - 说明型页面
   - 允许卡片、讲解文案、自由排版
   - 不可作为像素级验收页

2. `figma-frame`
   - 页面结构、容器、间距、对齐关系直接对应 Figma frame
   - 才能进入像素级验收

当前大部分页面的问题在这里：组件可能在变好，但页面容器还在用 docs shell 语言组织，所以整体看起来还是“不像 Figma”。

### Gate 4: Review Decision Gate

每个组件页必须有明确状态：

- `blocked`
- `in-review`
- `approved`

只有 `approved` 才算通过。`in-review` 代表正在接近 Figma，不代表已经通过。

## 当前仓库暴露出的典型根因

### 根因 1

“组件还原” 和 “站点展示还原” 被混为一谈。

结果是：

- 单个控件可能差不多
- 但整页容器、边距、标题、卡片、栏目结构仍是文档系统自己的语言

### 根因 2

很多页面仍直接导入 `src/components/*`，而不是 `src/canonical/*`。

这意味着页面展示的是运行时近似实现，不是 Figma-first 实现。

### 根因 3

“已进入像素级 review” 和 “已通过像素级 review” 没有被制度化地区分。

这会让团队在沟通中把中间状态误说成最终状态。

### 根因 4

基础数据审计存在，但视觉审计没有真正进入发布闸门。

现在能查出 token、hardcode、wrapper 漂移，却还不能自动回答：

- 这个页面是不是 Figma frame
- 这个页面有没有资格宣称 pixel-perfect

## 审查执行顺序

每个组件页必须按这个顺序推进：

1. 先建 provenance
2. 再切 canonical source
3. 再做 frame 级页面还原
4. 最后做像素级复核与签字

不要反过来。

如果在 `docs-demo` 页面里直接做“像素微调”，只会持续返工。

## 机器审计

仓库里新增了 `pnpm audit:docs-site`，它会检查：

- 每个 docs 页面是否登记在审查清单里
- 页面是否有 Figma 基线
- 页面实际导入的是 canonical 还是 runtime 组件
- 页面当前被标记成 `docs-demo`、`state-grid` 还是 `figma-frame`
- 页面是否已经被允许宣称 `approved`

这份审计故意是严格的。

如果目标是“整个设计系统网站都达到像素级还原”，那么只要还有一个组件页未满足四层审查门，整体就不应该被视为通过。

### 严重程度口径（2026-04-28 调整）

机器审计的 issue 分两级：

- **error（阻塞 overallPass）**
  - component 页缺 Figma baseline（`figmaPage / figmaComponentSet / figmaNodeId` 任一缺失）
  - component 页未消费 canonical（`actualSourceType !== 'canonical-only'`）
  - component 页非 figma-frame 渲染模式
  - component 页 `pixelReviewStage` 既非 `approved` 也非 `in-review`（如 `blocked` 或未知）
  - component 页 source-type 与 manifest 期望不匹配
  - manifest 引用的页面文件不存在 / 页面文件未登记 manifest

- **warn（不阻塞，但仍记录在 issues）**
  - component 页 `pixelReviewStage='in-review'`：已进入像素核对但未签字，属正常中间态
  - foundation 页（如 Icon / Color / Typography）source-type 与 manifest 期望不匹配：foundation 页允许导入 runtime 共享展示组件做资产目录，不视为 Figma-first 退化
  - foundation 页 `currentRenderingMode='docs-demo'`

`overallPass` 取决于 errors 是否为 0；warnings 不阻塞主 Session 启动门槛，但必须在 handoff 中显式列出待处理项。

## 当前站点审计快照（2026-04-24）

本轮已实际执行：

```bash
pnpm audit:docs-site
```

结果：

- `pagesChecked = 23`
- `componentPages = 17`
- `approvedComponentPages = 0`
- `blockedComponentPages = 17`
- `errors = 71`
- `warnings = 3`
- `overallPass = false`

### 本轮读到的事实

1. 当前没有任何组件页可以宣称已经通过像素级还原  
   `approvedComponentPages = 0`

2. `CheckBox / Radio` 虽然已经进入 review，但仍停留在：
   - `currentRenderingMode = state-grid`
   - `pixelReviewStage = in-review`

3. `Input / Select / DateTime / Switch` 虽然已切到 canonical source，  
   但仍缺：
   - 完整 Figma baseline
   - `figma-frame` 页面形态
   - `approved` 结论

4. `Button / Badge / InputNumber / Notification / Tooltip / Pagination / Progress / Slider / Rating / Table / TopBar`  
   目前仍主要依赖 `src/components/*` 旧 runtime 实现，不能宣称 Figma-first。

### 当前站点阻塞点

不是“页面不够多”，而是 3 个门槛同时没过：

1. **Provenance 不完整**  
   多个组件页缺 `figmaNodeId`

2. **Implementation 不一致**  
   很多组件页仍是 `runtime-only`

3. **Frame Fidelity 不达标**  
   当前大多数页面还是：
   - `docs-demo`
   - `state-grid`
   
   而不是：
   - `figma-frame`

### 当前执行策略

因此站点侧从本轮开始不再用“先铺页面、后微调”作为主策略，而是：

1. 先修生成链和 canonical 契约
2. 再选一个组件样板验证页面如何从 `docs-demo/state-grid` 进入 `figma-frame`
3. 样板优先仍然是 `Button`

## 团队使用方式

### 日常开发

每次改动组件页前先跑：

```bash
pnpm audit:design-system
pnpm audit:docs-site
```

### 准备提测

提测前至少跑：

```bash
pnpm audit:component-tokens
pnpm audit:tokenized-diff
pnpm audit:docs-site
pnpm test
```

### 发布口径

只有当某个页面在 `site-review-manifest.json` 中满足：

- `baselineStatus = captured`
- `expectedSourceType = canonical-only`
- `currentRenderingMode = figma-frame`
- `pixelReviewStage = approved`

才允许在对内或对外沟通里说：

`这个页面已经完成像素级还原。`

## 下一步建议

如果要最快看到质量提升，建议按下面顺序推进：

1. 先把 `Input / Select / DateTime / CheckBox / Radio / Switch` 从 `state-grid` 推进到 `figma-frame`
2. 再处理 `Button / Pagination / Slider / TopBar / Notification / Tooltip`
3. 最后统一处理 foundation 页的 Figma 原子资产闭环

这样可以先把最接近完成的页面变成真正通过，而不是让整个站点一直停留在“都在 review”。