stash-ui/docs/STYLE-INTAKE.md

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

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

0. 一句话原则

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

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

### 项目：<名称>    来源：<截图/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. 实施顺序（库先行）

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

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

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

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

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