# 外部风格接入（截图 → 组件/令牌）

> 用在「使用方给了一张别的网站截图，风格和 stash-ui 不一致」的场景。
> 目的：**先对齐方案，再动代码**；把「能吸收的」吸进库，把「只能页面私有的」明确记成例外。
> 规则来源：[DESIGN.md §11](../DESIGN.md)。

## 0. 一句话原则

截图只提供**意图**，不提供实现。先把它翻译成「骨架 / 组件 / 形态值 / 交互」，
再决定每一项落在哪一层：主题变量、组件参数、组件变体、新组件、页面私有。

## 1. 接入单（收到截图后先填）

```md
### 项目：<名称>    来源：<截图/URL>    日期：<日期>

1. 布局骨架：<几栏、页头/侧栏/底栏、最大宽度、断点>
2. 组件清单：<截图里出现的每个控件，按出现顺序>
3. 形态值：<主色、圆角、阴影、控件高度、字号阶梯、间距节奏>
4. 交互：<hover / 展开 / 切换 / 空态 / 加载>
5. 范围：<整站统一 / 只此一页 / 只此一个组件>
```

## 2. 映射表（核心产物）

| # | 截图里的东西 | 库里的对应 | 结论 | 证据（值） |
| --- | --- | --- | --- | --- |
| 1 | 顶栏 64px 白底 | `Layout headerVariant="solid"` + `headerHeight` | ✅ 参数可调 | 截图 64，库默认 60 |
| 2 | 主色 #6C5CE7 | `--su-color-primary` 主题覆盖 | ✅ 主题 | 只改变量 |
| 3 | 按钮 48 高、10 圆角 | `Button` 只有 32/36/44 | ⚠️ 缺尺寸档 | 需新增 `size="lg"`（40/48） |
| 4 | 卡片 16 圆角 | `--su-radius-md` 12 | ⚠️ 缺档 | 主题覆盖不了，需 `radius` 档或新令牌 |
| 5 | 瀑布流列表 | 无 | ❌ 新组件 | 判定：是否 ≥2 处会用 → `Masonry` |
| 6 | 封面左上角角标 | `Cover` + 绝对定位 | ⚠️ 组合即可 | 不需要新组件，写组合模式 |
| 7 | 背景光晕 | 无 | 🟡 页面私有 | 一次性装饰，页面 CSS |

图例：✅ 现有能力（调参/主题）｜⚠️ 需要参数化或加变体｜❌ 需要新组件｜🟡 页面私有

## 3. 决策：先问三个问题

1. **换主题能不能解决？** 只是颜色/字体 → `themes/<name>.css` 改变量，不动组件。
2. **同结构、不同形态或交互？** → 给现有组件加 `size` / `variant` / `radius` 之类的受控参数。
3. **结构不一样？** → 评估新组件：
   - 会不会在 ≥2 个页面/使用方出现？
   - 能不能用 props 表达，不夹带业务字段？
   - 两条都满足才进库，否则先做页面私有实现，并记一笔「候选组件」。

## 4. 评审要点（给使用方确认的最小信息）

- **差异表**：每一项「截图值 / 库值 / 结论」；
- **API 草案**：新增/修改的 props（只写名字、类型、默认值，不写实现）；
- **影响面**：会不会改现有组件默认值（破坏性）、要不要同步文档与展示页；
- **兼容性提示**（改共享组件必填）：
  - 调用方清单（哪些页面/组件在用）；
  - 变更性质：新增可选 prop（兼容）/ 改默认值（视觉回归）/ 改删 prop（破坏性）/ 只改样式（视觉回归）；
  - 回归范围（要重截哪些页面 / 哪些 demo）；
  - 破坏性改动的旧 → 新写法对照；
- **不做的事**：哪些按页面私有处理，理由是什么。

> 评审通过前**不动代码**。这一步是「先停下来统一方案」的落点。

## 5. 实施顺序（库先行）

```text
① 令牌（如果是新形态值）
② 组件 props / variant / 新组件
③ 展示页示例（每个新能力至少一个 demo）
④ 契约：COMPONENTS.md 对应小节 + 变更记录
⑤ 主题文件（如果只是配色）
⑥ 页面接入（只写页面私有的那部分 + 注释说明）
```

## 6. 验收清单（外来风格专项）

- [ ] 深色主题：新能力在 `data-scheme="dark"` 下不串色（只吃语义令牌）
- [ ] 键盘：新交互可聚焦、有焦点环、Esc/方向键行为明确
- [ ] `prefers-reduced-motion`：动效有降级
- [ ] 移动端：390 宽无横向溢出；触屏不依赖 hover
- [ ] 业务隔离：组件不 import 业务类型、不请求数据
- [ ] 默认值：外来品牌值没有写进组件默认值，只在主题/页面里
- [ ] 文档：契约、展示页、README 组件表、变更记录四处同步

## 7. 反面样本（不要这么做）

- 把截图里的品牌色写成组件默认主色；
- 在页面里覆盖 `_button_xxx` 这种 hash 类名；
- 为了一个页面复制一份组件到项目里改；
- 「先页面实现，回头再收」但没登记候选组件；
- 截图里每个数值都硬编码，最后页面上出现 6 套圆角。