89 lines
4.6 KiB
Markdown
89 lines
4.6 KiB
Markdown
# 外部风格接入（截图 → 组件/令牌）
|
||
|
||
> 用在「使用方给了一张别的网站截图，风格和 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 套圆角。
|