# 主题素材归档与切片工作流

## 目录

1. 建立素材台账
2. 归档源素材
3. 分析构图与安全区
4. 提取背景、边框、图标和纹理
5. 处理动态组件装饰框
6. 保存 manifest 和生成脚本
7. 资产质量门禁

## 1. 建立素材台账

收到素材后立即记录：

| 字段 | 说明 |
|---|---|
| 角色 | 完整参考、背景、图标板、边框板、欢迎卡、纹理或字体 |
| 原始路径 | 会话附件或用户提供位置 |
| 归档路径 | 当前主题任务的 `references/source-assets/` |
| 尺寸/格式 | 像素尺寸、RGB/RGBA、PNG/WebP/JPEG 等 |
| SHA-256 | 防止后续误换源图 |
| 是否含 alpha | 决定是否需要背景分离 |
| 允许用途 | 背景、切片源、对照图或仅参考 |

不要把完整参考图直接当产品背景，也不要把带标题、尺寸标签和卡片底的图标板当 CSS sprite。

## 2. 归档源素材

优先归档到：

```text
.trellis/tasks/<date>-<theme-task>/references/source-assets/
```

保留原始文件名或建立清晰映射。归档后核对源附件与归档文件 hash 一致。后续脚本只读取归档路径，避免依赖可能清理的会话附件。

禁止删除：

- 完整概念图。
- 背景源图。
- 图标/边框/欢迎卡素材板。
- 视觉对照截图。
- 提取脚本和 manifest。

## 3. 分析构图与安全区

按原始像素尺寸记录：

- 主视觉主体 bbox。
- 适合侧栏和正文的低干扰区域。
- 不能被消息、遮罩或输入区压住的高权重区域。
- 顶部、底部和移动端裁切风险。
- 参考图中的真实视口与组件坐标。

遮罩的目标是稳定文字对比，不是继续压暗整张背景。先让背景主体可见，再由局部面板解决可读性。

## 4. 提取背景、边框、图标和纹理

### 背景

- 优先保留用户提供的原图和构图比例。
- 使用 WebP/PNG/JPEG 等项目已支持格式。
- 记录 `background-size`、`background-position` 和各视口裁切策略。
- 不对主视觉背景使用 blur，除非设计稿明确如此。

### 边框

- 从参考图提取时保留角线、短高光和必要装饰，清除烘焙背景与棋盘格。
- 先确认边框属于固定尺寸还是动态尺寸组件。
- 固定尺寸按钮可使用完整透明 PNG。
- 动态高度输入框、长工具块或可伸缩卡片使用 `border-image`/九宫格，或拆成角、边和独立装饰。
- 不把固定宽高比整框放在 `::before` 后强行覆盖动态内容。

### 图标

区分四个概念：

1. 设计目标尺寸。
2. 素材板中的物理像素尺寸。
3. 输出透明画布尺寸。
4. 实际 alpha 主体 bbox。

按控件用途选择源规格，不要所有图标统一从最大档裁出后再缩到同一个 CSS 尺寸。

- 小动作按钮：优先干净单色 mask，主体通常比容器小。
- 主操作按钮：使用更高规格源图，允许更大视觉主体。
- 多色状态、头像和主题装饰：保留原色，单独处理尺寸。
- 非方形图标：保持比例并放入统一画布，不拉伸。
- 非对称图标：按 alpha 加权重心校正光学中心。

alpha 加权中心：

```text
cx = sum(x * alpha) / sum(alpha)
cy = sum(y * alpha) / sum(alpha)
offset = canvas_center - (cx, cy)
```

### RGB 素材板分离 alpha

RGB WebP 常含有损压缩噪点，不能只用单一亮度阈值。推荐：

1. 按主体外扩 2–4px 裁剪。
2. 从边缘 flood-fill 识别与暗背景相连区域。
3. 结合亮度、色相和局部差值识别金色/浅色/状态色。
4. 去除小连通域噪点。
5. 对 alpha 轻微羽化，避免黑边。
6. 在深色、浅色和半透明背景上人工复核。

阈值必须针对当前素材板调试，不跨主题硬编码。

## 5. 处理动态组件装饰框

### 先问三个问题

1. 组件宽高是否随内容变化？
2. 哪些区域可以拉伸，哪些角/徽记必须保持比例？
3. 聚焦、拖拽、笔记、运行等状态是否改变 border 或尺寸？

### 推荐选择

| 场景 | 推荐 |
|---|---|
| 固定 48px 按钮 | 完整透明框图或 mask |
| 宽度变化、高度固定 | 水平三段切片或 `border-image` |
| 宽高都变化 | 九宫格 `border-image` |
| 底部中心徽记不能拉伸 | 框体九宫格 + 独立徽记，或通过不拉伸 slice 保留 |
| 装饰只是短角线 | CSS border + 小伪元素，不加载整张框 |

测试最短、常规和最长内容。只验证单行输入不能证明动态框正确。

## 6. 保存 manifest 和生成脚本

每个派生资产至少记录：

```json
{
  "name": "send",
  "source": "icon-sheet.webp",
  "source_sha256": "...",
  "source_box": [x, y, width, height],
  "variant": "24px",
  "detected_box": [x, y, width, height],
  "output": "icons/send.png",
  "size": [32, 32],
  "usage": "composer primary action"
}
```

生成脚本应：

- 使用项目已有依赖，避免为一次切图引入重量级包。
- 只读取归档源素材。
- 可重复运行并稳定覆盖派生资产。
- 写出 manifest，失败时指出具体资产。
- 用中文注释说明当前素材板特有的阈值、区域和校正。

Wasteland 案例脚本位于 `.trellis/tasks/07-17-gilded-wasteland-theme/research/extract_reference_chrome.py`，只可作为方法参考，不要直接复用其坐标和颜色阈值。

## 7. 资产质量门禁

- 文件格式、尺寸和 alpha 通道符合用途。
- 背景 hash 与归档源一致，或记录过转换原因。
- manifest 与实际文件一一对应，没有遗漏或多余派生图。
- 透明图在深/浅/半透明背景上无黑边和棋盘格。
- 尖角、纸飞机尾部、气泡尾巴和状态色未被裁掉。
- 图标实际主体尺寸符合控件层级，不以画布尺寸代替可见尺寸。
- 光学中心误差可解释并在按钮中实测。
- 浏览器请求所有资产返回 200，MIME 正确。
- 源素材、manifest 和提取脚本仍然存在。