anima

anima 是做什么的？

概述

一个作品 = 一个短篇的品牌化动态作品：一段介绍/预告/公告视频、一个单独的动画插图或一个动态英雄区。HyperFrames 负责创造动态效果；anima 则让它看起来像 PageFly。 这是一个设计系统，而不是模板库：可复用的东西不是某个 index.html 文件，而是三个与具体创作无关的层次——品牌令牌（references/brand.css，共享身份在 _pf-brand/）、运动行为指南（references/style-guide.md）和一套品牌化动态模块组件库（components/）——它们在 templates/canvas.html 上按需自由组合。Page Checkup 介绍视频是第一个工作示例（examples/before-after/）。与 illustra 模型相同（组件库 + 自由组合 + 风格指南 + 治理），只是从静态艺术移植到了动态效果。anima 和 illustra 保持为独立的技能——anima 在需要静态 PNG 时会调用 illustra；两者互不包含。

协调 HyperFrames——而非重新发明

视频制作机制（合成结构、时间线契约、场景过渡、lint/inspect/validate、渲染）：请遵循 hyperframes 技能。此技能仅增加：品牌预设（references/brand.css）、运动行为指南（references/style-guide.md）、组件库（components/）。

这里不会重复任何 HyperFrames 的创作规则（DRY - 避免与 HF 升级产生偏差）。

何时使用

• 制作一个短篇的品牌化 PageFly 动态作品：

  • 介绍/预告/公告（“PageFly 新功能：…”），
  • 一个单独的动画插图（一个概念的动画），
  • 动态英雄区（一个动起来的英雄区段），或
  • 素材片段：一个品牌化标题卡切入到现有真实录制（屏幕录制、产品演示）。

  前三者是 1600x900 的无缝循环。素材片段是 1920x1080 且线性的——在创作前请查看 references/style-guide.md -> 素材片段。

• 案例有清晰的节拍：一个介绍性暂停、一个可选的之前/之后变形、一个单一功能暂停。对于动画插图/英雄区，介绍标题卡（场景 1）常常被省略。

不适用于： 静态营销图像（使用 illustra / feature-demo）；非 PF 品牌（替换 references/brand.css 即可——引擎是品牌无关的，PF 只是默认预设）。

前置条件（两个层级）

• 渲染/重新修饰一个已有示例： npm hyperframes（通过 npx，首次运行时自动获取）+ Node >= 22 + FFmpeg。第一步： 运行 npx hyperframes doctor 并报告任何缺失的依赖项，然后再继续。
• 创作一个新作品： 另外需要 hyperframes 技能家族（创作知识——时间线契约、过渡、质量检查）。这些技能位于用户全局目录 ~/.claude/skills/，并未打包在此仓库中——克隆 PageFly 并不能得到它们。anima 携带了足够的 PF 约定，可以在没有它们的情况下继续，但它将所有机械规则委托给它们，因此如果缺少这些技能，创作质量会急剧下降。

新机器上的首次设置

每台机器运行一次。可以安全地重新运行——所有步骤都是幂等的。

npx hyperframes doctor                                   # 1. Node >= 22, FFmpeg, Chrome, 内存
cd /tmp && npx hyperframes init hf-bootstrap \
             --example blank --non-interactive           # 2. 安装 HF 技能家族
ls ~/.claude/skills/hyperframes                          # 3. 验证：SKILL.md + references/
rm -rf /tmp/hf-bootstrap                                 # 4. 一次性脚手架，删除它

注意：

• 没有专门的“安装技能”命令。init 搭建一个项目并安装技能——根据其自身的 --skip-skills 帮助文本，“init 总是检查 AI 技能与 GitHub”（在 CLI v0.7.108 上验证；HYPERFRAMES_SKIP_SKILLS=1 选择退出）。因此有了这个一次性目录。不要在此仓库内运行 init——它会把脚手架散落到技能树中。
• init 需要一个项目名称，而不是路径——如上所述，首先 cd 到父目录。
• 它会一次性安装约 15 个技能：hyperframes、hyperframes-cli、hyperframes-media、hyperframes-registry，以及动画库适配器（gsap、animejs、css-animations、lottie、three、typegpu、waapi、tailwind）和 website-to-hyperframes。
• HyperFrames 不是一个 Claude 插件——不要在扩展市场中寻找它。
• 渲染需要网络。 GSAP 在 templates/canvas.html 和每个示例中都从 cdn.jsdelivr.net（锁定 3.14.2 版本）加载，这与上游 hyperframes 模式一致。离线渲染会失败。

工作流程

1. 了解意图（先问，后计划）。 在生成之前，向成员询问一个简短的概要——哪种类型（预告片 / 动画插图 / 动态英雄区）、哪些场景 / 节拍、布局、过渡——然后展示一段话的计划以供确认。如果他们直接说“试试看”，则跳过概要直接进行。介绍性标题卡（场景 1）是可选的——对于动画插图/英雄区，除非案例想要“PageFly 新功能”的框架，否则省略它。
2. 理解案例 -> 信息以及它需要哪些节拍（介绍？之前/之后变形？单一功能？）。用一句话表述：什么是新的以及为什么重要。
3. 从一个舞台开始。 自由形式的新案例 -> 复制 templates/canvas.html（空白的品牌化 1600x900 舞台，内联 brand.css，循环幕布已连好但处于惰性状态）。之前/之后 -> 改为从 examples/before-after/ 开始。将工作文件保存为案例自身目录下的 index.html（HF CLI 运行目录中的 index.html；保持已提交的 canvas.html 原样）。
4. 选择模块 从 components/（索引：references/component-catalog.md）。将每个模块的标记粘贴到一个场景中，并将其 <!-- Timeline recipe --> 粘贴到单一的 tl 时间线中，根据场景的进入时间重新计算偏移量。注意任何你必须构建的定制部分。展示资产（logo-lockup、before-after-card）的模块期望一个位于你的 index.html 旁边的 assets/ 目录——创建它并从 examples/before-after/assets/pf-logo.svg 复制 PF 标志，再加上你自己的截图裁剪。
5. 应用行为指南（references/style-guide.md）：缓动（每个场景至少变化 3 种）、呼吸发光、循环接缝幕布、节奏 / 节拍锚点。标签、眉毛和徽章遵循共享工具包（_pf-brand/label-rules.md + _pf-brand/badges.html）——Poppins 字体，句子首字母大写，通过 var(--badge-*) 实现柔和徽章；从不使用全大写眉毛或金属色药丸徽章。将结构和时间线规则推迟到 hyperframes 技能处理。
6. 质量检查： npx hyperframes lint && npx hyperframes validate && npx hyperframes inspect。修复溢出、对比度和 H.264 条带问题。使用 npx hyperframes inspect --at 4.6,5.3 精确定位特定节拍。
7. 渲染： npx hyperframes render。然后收获可重用部分——运行下面的治理扫描。

硬性规则

镜像 references/style-guide.md；将完整的视频机制列表推迟到 hyperframes 技能。

1. 仅使用品牌变量。 永远不要硬编码品牌颜色/圆角/阴影——始终使用 var(--...)；通过 color-mix(in srgb, var(--token) N%, transparent) 从实色令牌衍生出透明色调（发光令牌预烘焙），这样替换 brand.css 即可换品牌。字面例外的（按风格指南）：字体 "Poppins" / "JetBrains Mono"（渲染器无法解析 var(--font-*)）；GSAP 颜色补间；SVG stroke；中性色。
2. 每个场景不透明底色。 没有跳切——场景到场景是在不透明的 --bg 上进行模糊交叉淡入淡出（hyperframes 的硬性规则）。
3. 仅进入动画，最后一个节拍除外。每个元素都使用动画进入（gsap.from / fromTo）；退出补间仅存在于循环尾部。
4. 没有表情符号。 图标是手绘的——CSS 点、绘制的 SVG 勾选路径、绿色药丸徽章——永远不会使用表情符号字符。
5. 确定性的。 没有 Math.random() / Date.now()；只有有限重复（永远不要 repeat: -1）——渲染必须可重现。
6. 无缝循环（仅限循环作品）。 对于预告片/动画插图/英雄区：发光效果从隐藏开始，并且 #loopveil 在接近尾部时淡出为海军蓝，以使最后一帧 == 第 0 帧。素材片段是线性的，而不是循环——它仍然以幕布结束以实现干净的尾部，但第 0 帧和最后一帧不需要匹配。

文件映射

路径	角色
.claude/skills/_pf-brand/	品牌身份令牌 + 徽章调色板 + 标签规则的事实来源 (brand-identity.css， badges.html， label-rules.md)。它是一个兄弟技能目录，而不是 anima 的子目录——本技能中的每个裸 _pf-brand/ 都解析为此路径。A 层 + 徽章从此处同步到 references/brand.css。今天由 anima 消费；illustra 仍然在 illustra/references/brand.css 保留自己的分支，并且不读取此文件。
references/brand.css	品牌预设：A 层身份 + 徽章调色板（从 _pf-brand/ 同步）+ B 层视频表面调色板。替换以更换品牌。
references/style-guide.md	运动行为指南：节奏、缓动、发光、循环接缝、过渡、标签/徽章、做与不做。训练记录本——追加每次优化。
references/component-catalog.md	组件库索引 + 晋升治理 + 已创建部件日志。
components/*.html	自包含的运动模块（pf- 前缀）：引导注释 + 作用域 <style> + 标记 + 一个 <!-- Timeline recipe -->。粘贴到案例的时间线中。
templates/canvas.html	空白的品牌化 1600x900 HF 舞台；内联 brand.css，循环幕布已就绪。从自由形式案例在此开始。
examples/before-after/	Page Checkup 介绍 = 工作示例，通过 data-composition-variables 参数化。从之前/之后开始。

渲染直接使用 npx hyperframes render——没有专门的渲染脚本（不同于 illustra 用于 Playwright PNG 的 render.mjs）。

治理——训练模型（“不要每次都重新做”）

每次优化都沉淀到共享层中，永远不会沉淀到一次性文件中：

• 调整品牌颜色/发光 -> references/brand.css（身份 + 徽章调色板位于 _pf-brand/）
• 更改标签/徽章品味 -> _pf-brand/label-rules.md + _pf-brand/badges.html
• 锁定新的缓动/节奏/技术（“现代 PF”） -> references/style-guide.md
• 一个模块被第二次手动构建 -> 通过建议 + 批准将其提升到 components/。

在每个作品完成后，根据 3 个标准扫描你手动构建的内容：

1. 可重用 - 一个通用的运动概念，不特定于该案例的内容。（“我是否会为不同的功能再次合理构建这个？”）
2. 自包含且可参数化 - 自有标记 + 作用域 CSS + 清晰的时间线配方；接受文本/颜色/大小。
3. 品牌化且干净 - 仅使用 var，遵循风格指南。

全部 3 个条件满足 -> 提议将其提升：一个新的 components/<name>.html + component-catalog.md 中已创建部件的一行（向成员确认是/否；从不自动添加，从不让他们判断技术细节）。 强烈信号： 一个部件被第二次构建几乎总是要提升。保持组件库精简（YAGNI）——直到真实案例需要时才创建部件。每次使用都会充实组件库和行为指南，因此下一个作品工作量更少。默认门控 = 建议 + 批准。