feat: stash-ui 0.1.0（40 个组件 + 文档站 + 主题机制）

2026-10-28 20:44:18 +08:00
commit 52296b3368
153 changed files with 17129 additions and 0 deletions
@@ -0,0 +1,88 @@
+# 外部风格接入（截图 → 组件/令牌）
+
+> 用在「使用方给了一张别的网站截图，风格和 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 套圆角。