企业官网建设流程全解析

• AI 技能
• 媒体生成

本指南围绕text-to-lottie技能库中的核心配方文档 recipe-loaders-icons.md 展开，系统讲解如何用 Claude Code / Codex 等编码 Agent 生成生产级的 Lottie 加载器、Spinner、进度环、徽章、图标动画以及成功/失败/警告等状态反馈动画。读完本文，你将掌握该配方的默认设计原则、8 个可直接套用的动画预设、时间与缓动参数、循环无缝（loop seam）的工程化做法，以及如何结合官方 Skottie 播放器完成透明背景、帧级验证与槽位（slot）控制的可交付流程。

适用场景：loading spinner、looping loader、progress ring、animated icon、success check、error x、warning triangle、toast icon、empty state、status badge、done indicator，以及任何紧凑型状态提示动画。

一、配方定位与路由机制：何时启用 loaders/icons 配方

text-to-lottie技能采用"薄控制面 + 一层引用库"的架构：主入口 SKILL.md 仅负责任务路由，不内嵌全部规则。当用户意图命中以下关键词时，Agent 应加载本配方：

• Loader / Icon / Spinner / Badge 动画→ 路由到references/recipe-loaders-icons.md+references/motion-taste.md；
• Success / Error / Warning / Completion / Empty state→ 路由到references/recipe-loaders-icons.md+references/design-taste.md+references/motion-taste.md。

该路由规则在 SKILL.md 的参考加载表中明确列出，并在 routing-prompts.json 的评估用例中得到验证——例如用例"Make a loopable warning icon with a subtle pulse."的预期引用即包含recipe-loaders-icons.md、design-taste.md与motion-taste.md，且明确要求避开recipe-typography.md与recipe-product-promo.md。

配方文档开篇即界定了其适用范围：loaders、spinners、progress loops、badges、simple icons、success/error states、warning alerts、empty states 与 compact status animations。这意味着它面向的是"小而精"的状态型动画，而非大段文案、复杂叙事或产品推广场景；后者应分别交由 typography、chapterization、product-promo 等配方处理。

二、用户语言别名：识别自然语言请求

配方给出了可直接匹配的用户表述清单（User-Language Aliases），用于把口语化请求映射到本配方：

当 Agent 收到上述任一表述时，即进入本配方的工作模式。

三、默认设计原则（Defaults）

配方定义了在任何 loaders/icons 动画中都要遵循的默认值，这些默认值同时被 player-contract.md 的 Background Policy 与 SKILL.md 的 Scene Rules 所支撑：

1. 透明背景：图标、加载器、overlay、徽章默认输出透明背景。仓库的 thumbnails.ts 在渲染场景缩略图时先执行canvas.clear(ck.TRANSPARENT)再anim.seekFrame(0)渲染，正是为了在无背景干扰下确认透明输出没有多余图层；若动画确需全画幅背景，才按 player-contract 提供带bgColor槽位的背景层。
2. 循环动画必须无缝：loaders/spinners/progress 默认干净循环；而 success/error/warning 状态除非用户明确要求循环，否则播放一次并稳定停在最终姿态。
3. 小尺寸下几何清晰：图形在缩小时依然锐利可读（避免过细的线条与过密的细节）。
4. 单一基本型重复优于杂乱部件：优先用一个 primitive（圆点、圆环、短划）或一个图标想法，配合相位偏移（phase offset）形成节奏，而不是堆砌互不相关的运动部件。
5. 只加一个 charm 手势：如 blink（眨眼）、bounce（弹跳）、pulse（脉冲）、draw-on（描边浮现），且仅在符合品牌调性时使用。

四、八种预设（Presets）详解

配方提供 8 个开箱即用的动画预设，每个预设都隐含了明确的循环策略与运动特征：

其中phase-dots与orbital-loader直接呼应 motion-taste.md 的 "Loop And Generative Motion" 一节：重复元素需要按 index、distance、row 或 path position 做相位偏移，lockstep 齐步运动会显得机械；循环接缝要通过整数波形周期、闭合旋转、wrapped drift 或回收的 emanation rings 来工程化。

五、时间与缓动规范（Timing And Easing）

配方给出两类明确的时间预算：

• 状态反馈（state feedback）：30–75 帧，且以稳定最终姿态收尾。以fr: 60计约为 0.5–1.25 秒，足够让用户感知"完成"但不过度拖沓。
• 加载器（loaders）：60–120 帧的无缝循环，即约 1–2 秒一个循环周期，既保持持续动感又不过于急促。

缓动方面，配方强调两条硬规则：

1. 连续线性（continuous linear）只用于旋转与进度类循环——轨道旋转、扫描进度这类机械往复是唯一适合 linear 的场景；
2. 成功状态使用短 ease-out 或低反弹的 spring-like settle——数值冲过头再回落，但幅度必须小。

这与 motion-taste.md 的 Timing Defaults 表完全对齐（"Loaders/icons: loop cleanly over 60-120 frames"、"State feedback icons: 30-75 frames, usually with a short hold"），并可从其 Easing Anchors 表中推导出更精细的贝塞尔曲线。下表为 motion-taste 中"已知可用、按行为推导"的锚点（Bezier 记法x1,y1,x2,y2），可用于本配方各类状态的缓动选择：

在 Lottie JSON 中，一个三次贝塞尔(x1,y1,x2,y2)需要拆成两个关键帧上的手柄：起始关键帧的出向手柄o:{x:[x1],y:[y1]}与目标关键帧的入向手柄i:{x:[x2],y:[y2]}（见 lottie-spec-map.md）。overshoot 的紧凑替代方案是让结束关键帧的i.y大于 1，例如 1.08–1.2；若嫌手柄方案复杂，可先做一帧"越过目标再回弹"的 settle-back 关键帧（Skottie 安全）。Anticipation（预示）则把起始帧o.y压到 0 以下。

六、提问策略：只在必要时提问（Ask Only When Needed）

配方奉行"少提问、强默认"原则（这也是 SKILL.md Operating Model 的总体要求），仅在结果会发生实质变化时追问：

1. 循环 vs 一次性——仅当请求本身存在歧义时才问；
2. 目标尺寸——当图标必须适配特定 UI 槽位时问清尺寸，因为小尺寸直接决定细节密度与描边宽度；
3. 品牌/强调色——当没有源风格可循时询问 accent 颜色。

七、构建要点（Construction Notes）与 Lottie JSON 落地

7.1 结构层面的工程约束

• 用 trim paths 处理描边：勾号、圆圈、圆环、圆形加载器的绘制动画都应使用ty:"tm"（trim path）配合ty:"st"（stroke）实现，而不是逐帧烘焙路径。这是本配方最重要的结构建议，也符合 lottie-spec-map.md 中形状原语清单（tm、st、rc、el、sh、sr、fl、tr）。
• 首尾帧必须匹配：循环动画的工程核心是"首尾状态一致或周期锁定"。位置、透明度、颜色、以及感知速度（首尾角速度）都要对齐——motion-taste 称之为"match first and last frames in position, opacity, color, and perceived velocity"。
• 小图标尺寸下避免过度细节：低于小型图标尺寸时，减少细节数量，保证可辨识度。
• 只暴露有意义的槽位：为强调色（accent color）、描边宽度（stroke width）暴露 slot；背景色槽位仅在全画幅场景下才提供。

7.2 槽位（Slot）与 controls.json：让属性面板可编辑

配方要求"为 accent color、stroke width 暴露 slot"。在 player-contract 协议中，槽位定义在 Lottie 顶层slots，属性通过sid引用：

{ "slots": { "accentColor": { "p": { "a": 0, "k": [0.2, 0.5, 1, 1] } }, "strokeWidth": { "p": { "a": 0, "k": 4 } } } }

对应形状属性以sid绑定（例如圆环描边颜色与宽度）：

{ "c": { "sid": "accentColor" } }, { "w": { "sid": "strokeWidth" } }

再在同一场景目录放置controls.json提供标签与数值范围：

{ "controls": [ { "sid": "accentColor", "label": "Accent color" }, { "sid": "strokeWidth", "label": "Stroke width", "min": 1, "max": 12, "step": 0.5 } ] }

controls.json的字段（sid、label、min、max、step）与仓库 common.ts 中ControlMeta接口一一对应；播放器通过 Skottie 自动发现槽位并在属性面板渲染控件。槽位值类型到控件的映射如下：

注意槽位类型必须与引用它的属性类型兼容；属性缺少sid时渲染器可能回退到内联值或类型默认值，不要依赖"缺失槽位"。仓库前端在 lottie.ts 中实现了applySlotValues，支持 scalar / color / vec2 / text 四种槽位类型，并在 UI 编辑后把lottie.json写回场景目录（/__scenes/lottie），确保public/projects始终是控制的唯一事实来源（见 scenes.ts）。

7.3 示意：一个 trim-path 对勾（check-complete）的最小结构

结合 lottie-spec-map.md 的结构规范，一个"对勾描边绘制 + 落定"的成功态可组织为：形状层（ty:4）→ 组（ty:"gr"，组内tr放最后）→ 路径（ty:"sh"）+ 描边（ty:"st"）+ 修剪路径（ty:"tm"）。修剪路径的e（终点百分比）在首帧为0、末帧为100，即可得到描边逐笔浮现的效果；收尾用settle-soft（.00,.65,.51,.99）落定并保持最终姿态。类似地，圆形加载器用ty:"el"+ty:"st"+ty:"tm"，旋转段用连续线性缓动并保证首尾角度形成整数周期。

上述 JSON 结构为基于 spec map 的示意写法，用于说明配方结构约束如何落地；仓库中的实际可运行示例场景为默认 512×512 背景场景 scene-1/lottie.json（可作为新建场景的骨架参考）。

八、常见失败模式（Common Failure Modes）与规避

配方明确列出 5 类高频失败，必须在渲染验证中逐一排除：

1. 循环接缝可见（loop seam is visible）——首尾帧不一致或速度不匹配；规避方式是对齐首尾状态与感知速度。
2. 重复部件齐步运动，机械感强——重复元素全部同相；规避方式是按索引/距离/路径位置施加相位偏移（除非 lockstep 就是意图）。
3. 运动过程中图标不可辨识——形变/位移破坏了图形语义；规避方式是控制运动幅度、保持轮廓稳定。
4. 错误/警告态动画过于俏皮——状态反馈的"charm 手势"要用在正确场景；错误态应克制、受控，而不是弹跳卖萌。
5. 描边端点/连接渲染与预期不符——stroke caps/joins 在不同渲染器存在差异；务必在官方 Skottie 播放器中验证，而不是依赖其他渲染器或 IDE 预览。

其中第 1、2 条与 motion-taste.md 的 Loop And Generative Motion 完全一致，第 5 条与 lottie-spec-map.md 的 "SVG, masks, gradients, blend modes, and intersections can differ between renderers. Verify in Skottie" 相互印证。

九、验收清单（Acceptance Checks）

完成动画后，必须逐条通过以下验收：

• 循环接缝不可见：循环播放时首尾过渡无感知断层；
• 重复运动使用相位偏移：除非 lockstep 是有意设计；
• 运动中图标保持可辨识：任意中间帧都能读出图形语义；
• 节奏实用而非慌乱：30–75 帧状态反馈、60–120 帧加载循环，落定清晰；
• 透明输出无多余背景层：不烘焙不透明矩形填充画布。

十、端到端验证流程：结合官方播放器交付

配方与 player-contract 一致要求：交付物是在官方 Skottie 播放器中可渲染的场景，而不是孤立的 JSON。验证流程如下：

1. 场景写入public/projects/<project>/<scene-N>/lottie.json（仓库的 scenes.ts 会自动扫描该目录并生成场景树，缺失lottie.json的目录会被忽略）；
2. 先做 JSON 校验：

   node -e "JSON.parse(require('fs').readFileSync('public/projects/<project>/<scene-N>/lottie.json','utf8'))"

3. 启动开发服务器（npm run dev，端口以 Vite 输出为准），用curl -s http://localhost:<port>/__context确认场景出现在上下文与播放状态中；
4. 用帧定位精确检查：http://localhost:<port>/<project>/<scene>?frame=<N>，新场景至少检查 frame0、中点和op - 1（op为排他上界，ip:0, op:90, fr:60实际渲染 0–89 帧）；
5. 对循环动画额外检查接缝帧（末帧与首帧的连续性），对状态动画检查落定帧的最终姿态；
6. 确认背景策略与用途一致：加载器/图标默认透明，全画幅才有背景层；
7. 检查空白画布、缺失资源、未样式化形状、图层顺序、缓动僵硬、裁切、文本溢出与 SVG 伪影，直到动画干净且"意图明确"。

透明背景验证可以直接复用仓库 thumbnails.ts 的做法——在canvas.clear(ck.TRANSPARENT)的透明画布上渲染 frame 0，任何不该出现的背景像素都会立刻暴露。此外，output-rubric.md 的 Motion And Loop Quality 一节也要求：重复元素使用 reading-order stagger 或相位偏移、循环接缝经过工程化（matched endpoints、integer cycles、wrapped drift、closed rotation 或 recycled emanation），并强调"仅检查首尾静态帧不足以评判运动质量"——必须逐帧 scrub 播放。

十一、实战要点小结

• 先路由后动手：命中 loader/icon/state 关键词时加载本配方 + motion-taste（状态类再加 design-taste），不要打开整个引用库。
• 默认即约束：透明背景、无缝循环、单一 primitive 重复、最多一个 charm 手势、小尺寸可读。
• 预设是起点：8 个预设覆盖加载、描边、徽章、成功/错误/警告、进度、相位点阵；选定后按时间与缓动规范微调。
• 循环是工程问题：首尾对齐 + 相位偏移 + 周期锁定，缺一不可。
• 槽位服务可编辑性：accent color、stroke width 用 slot + controls.json 暴露，透明图标不提供背景槽位。
• 以 Skottie 为准：trim path 描边、stroke caps/joins、透明输出全部在官方播放器逐帧验证后再交付。

• AI 技能
• 媒体生成