cc-web/.codex/skills/create-cc-web-theme/references/asset-workflow.md

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

目录

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

1. 建立素材台账

收到素材后立即记录：

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

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

2. 归档源素材

优先归档到：

.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 加权中心：

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 和生成脚本

每个派生资产至少记录：

{
  "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 和提取脚本仍然存在。