Claude
Skill
huashu-design
花叔Design——用HTML做高保真原型、幻灯片、动画、可视化与专家评审。任何新设计100%先出三个方向初稿给用户选（指定风格/品牌也不豁免），选定后才执行。触发词：做原型、PPT、幻灯片、动画、设计风格、评审、做个HTML页面、UI mockup、导出MP4/GIF、做个好看的。生产级Web App/需后端的系统不适用。
Virus-scanned
Reviewed automatically before listing.
Download
mxyhi-ok-skills-huashu-design-7de4640.zip · 20352 KB
Install
skills CLI
npx skills add https://github.com/mxyhi/ok-skills/tree/main/huashu-design
Claude Code
claude plugin marketplace add https://llmmart.ai/marketplace.json && claude plugin install mxyhi-ok-skills@llmmart
Git
git clone https://github.com/mxyhi/ok-skills.git
The skills CLI installs just this skill, for any of its supported agents. Claude Code installs the whole mxyhi/ok-skills collection as a plugin from our marketplace. Git is the plain clone.
README
🌐 中文 · English
Huashu Design
「打字。回车。一份能交付的设计。」 "Type. Hit enter. A finished design lands in your lap."
在你的 agent 里打一句话，拿回一份能交付的设计。
3 到 30 分钟，你能 ship 一段产品发布动画、一个能点击的 App 原型、一套能编辑的 PPT、一份印刷级的信息图。
不是「AI 做的还行」那种水平——是看起来像大厂设计团队做的。给 skill 你的品牌资产（logo、色板、UI 截图），它会读懂你的品牌气质；什么都不给，三套逻辑顾问 + 60 种 HTML 原生风格库也能兜底到不出 AI slop。
你看到这篇 README 里的每一个动画，都是 huashu-design 自己做的。 不是 Figma，不是 AE，就是一句话 prompt + skill 跑通。下次产品发布要做宣传片？现在你也能做。
npx skills add alchaincyf/huashu-design
跨 agent 通用——Claude Code、Cursor、Codex、OpenClaw、Hermes 都能装。
📣 已改为 MIT 协议。 自 2026-05-14 起本 skill 完全开源（MIT License），个人和商用都免费，无需事先授权。原「个人使用免费、企业商用需授权」的条款已作废。(查看变更)
看效果 · 安装 · 能做什么 · 核心机制 · 和 Claude Design 的关系
▲ 25 秒 · Terminal → 4 方向 → Gallery ripple → 4 次 Focus → Brand reveal
👉 访问带音效的 HTML 互动版 ·
下载 MP4（含 BGM+SFX · 10MB）
📺 新手教程（花叔亲录）
不知道怎么用？看花叔录的 huashu-design 上手教程：
装上就能用
npx skills add alchaincyf/huashu-design
装完先自检：这个 skill 不只是 SKILL.md 一个文件，
references/、assets/、scripts/、demos/四个子目录里有 99 处被引用的配方、脚本、素材，缺一不可。装完看一眼安装目录（如~/.claude/skills/huashu-design/），如果只有 SKILL.md、没有那几个子目录，说明你的skillsCLI 版本太旧（≤1.5.15 有个只同步单文件的 bug，已在 1.5.19 修复）。升级后再装一次即可：npm i -g skills@latest # 或 npx skills@latest add alchaincyf/huashu-design升级后仍异常，就用
git clone兜底安装，把仓库克隆到任意 skills 目录即可：git clone https://github.com/alchaincyf/huashu-design.git ~/.claude/skills/huashu-design
然后在 Claude Code / Codex / Cursor 等任意支持 skills 的 agent 里直接说话：
「做一份 AI 心理学的演讲 PPT，推荐 3 个风格方向让我选」
「做个 AI 番茄钟 iOS 原型，4 个核心屏幕要真能点击」
「把这段逻辑做成 60 秒动画，导出 MP4 和 GIF」
「帮我对这个设计做一个 5 维度评审」
没有按钮、没有面板、没有 Figma 插件。
Star 趋势
能做什么
| 能力 | 交付物 | 典型耗时 |
|---|---|---|
| 交互原型（App / Web） | 单文件 HTML · 真 iPhone bezel · 可点击 · Playwright 验证 | 10–15 min |
| 演讲幻灯片 | HTML deck（浏览器演讲）+ 可编辑 PPTX（文本框保留） | 15–25 min |
| 时间轴动画 | MP4（25fps / 60fps 插帧）+ GIF（palette 优化）+ BGM | 8–12 min |
| 设计变体 | 3+ 并排对比 · Tweaks 实时调参 · 跨维度探索 | 10 min |
| 信息图 / 可视化 | 印刷级排版 · 可导 PDF/PNG/SVG | 10 min |
| 设计方向顾问 | 三套逻辑并行（秒数轮盘 + 现实参照获奖站 + 最佳设计师）· 直接出 3 版真实视觉 | 5 min |
| 5 维度专家评审 | 雷达图 + Keep/Fix/Quick Wins · 可操作修复清单 | 3 min |
Demo 画廊
设计方向顾问
模糊需求时的 fallback：三套互补逻辑并行——秒数轮盘（20 选 1 打破惯性）+ 现实参照（世界级获奖网站迁移）+ 最佳设计师（顶级工作室哲学），直接出 3 版真实视觉让你看着选，不让你在文字里盲选风格。背后是 60 种 HTML 原生风格库（网页 20 + PPT 20 + 信息图 20，纯 CSS 无需生图）。
iOS App 原型
iPhone 15 Pro 精确机身（灵动岛 / 状态栏 / Home Indicator）· 状态驱动多屏切换 · 真图从 Wikimedia/Met/Unsplash 取 · Playwright 自动点击测试。
Motion Design 引擎
Stage + Sprite 时间片段模型 · useTime / useSprite / interpolate / Easing 四 API 覆盖所有动画需求 · 一条命令导出 MP4 / GIF / 60fps 插帧 / 带 BGM 的成片。
HTML Slides → 可编辑 PPTX
HTML deck 浏览器演讲 · html2pptx.js 读 DOM 的 computedStyle 逐元素翻译成 PowerPoint 对象 · 导出的是真文本框，PPT 里双击即可编辑。
Tweaks · 实时变体切换
配色 / 字型 / 信息密度等参数化 · 侧边面板切换 · 纯前端 + localStorage 持久化 · 刷新不丢。
信息图 / 数据可视化
杂志级排版 · CSS Grid 精准分栏 · text-wrap: pretty 排印细节 · 真数据驱动 · 可导 PDF 矢量 / PNG 300dpi / SVG。
5 维度专家评审
哲学一致性 · 视觉层级 · 细节执行 · 功能性 · 创新性 各 0–10 分 · 雷达图可视化 · 输出 Keep / Fix / Quick Wins 清单。
Junior Designer 工作流
不闷头做大招：先写 assumptions + placeholders + reasoning，尽早 show 给你，再迭代。理解错了早改比晚改便宜 100 倍。
品牌资产协议 5 步硬流程
涉及具体品牌时强制执行：问 → 搜 → 下载（三条兜底）→ grep 色值 → 写 brand-spec.md。
Showcase · 真实案例
鹦鹉进化史网站 · 设计方向顾问三套逻辑实战（2.0）
Live demo · https://www.huasheng.ai/parrots/
一句「做个介绍鹦鹉进化史的网站」、零额外要求，skill 自动跑完整 2.0 顾问流程：先判断图片是内容必需 → 抓公共领域博物插画（Edward Lear / John Gould 的鹦鹉图录）→ 三套逻辑并行（秒数轮盘 + 现实参照获奖站 + 原研哉「白」哲学）各出一版真实视觉。素材齐了再设计，不是边设计边用色块占位。
「聊聊 skill」 · PM after-party 演讲 deck
Live demo · https://skill-huasheng.vercel.app
13 页 HTML deck，全部用 huashu-design 完成：
- 黑底极简衬线视觉系统（cover / about / hook / what / why / closing）
- 2 个带 BGM + SFX 的 22 秒 cinematic demo（Nuwa skill workflow + Darwin skill workflow），各采用完全独立的视觉语言：
- Nuwa：3D 知识 orbit + Pentagon 提炼 + SKILL.md typewriter + 「21 分钟」hero reveal
- Darwin：autoresearch loop spin + v1/v5 并列 diff + Hill-Climb 全屏曲线 + Ratchet gear lock
- 每个 cinematic 默认显示完整静态 workflow dashboard（观众随时能看清 skill 怎么跑），点 ▶ 才触发动画，跑完自动 fade 回 dashboard
- 嵌入 huasheng.ai 的 25 秒 hero 动画（iframe 本地化兜底）
- 真实数据：14,495 stargazers 真实曲线（gh API 拉取）+ DeepSeek V4 真实 specs（WebSearch 验证）
- 真实 AI 素材：用
huashu-gpt-image跑 4×2 grid 大图，extract_grid.py抠出 8 张独立透明 PNG，做 3D orbit 漂浮
适合参考的页面：
/slides/slide-04b-nuwa-flow.html· 静态 dashboard + cinematic overlay 双层架构/slides/slide-06b-darwin-flow.html· 完全独立视觉语言的对照案例/slides/slide-03b-deepseek-cover.html· AI slop vs 真实设计师视角的对比页
详细 cinematic patterns 见 references/cinematic-patterns.md。
核心机制
品牌资产协议
skill 里最硬的一段规则。涉及具体品牌（Stripe、Linear、Anthropic、自家公司等）时强制执行 5 步：
| 步骤 | 动作 | 目的 |
|---|---|---|
| 1 · 问 | 用户有 brand guidelines 吗？ | 尊重已有资源 |
| 2 · 搜官方品牌页 | <brand>.com/brand · brand.<brand>.com · <brand>.com/press |
抓权威色值 |
| 3 · 下载资产 | SVG 文件 → 官网 HTML 全文 → 产品截图取色 | 三条兜底，前一条失败立刻走下一条 |
| 4 · grep 提取色值 | 从资产里抓所有 #xxxxxx，按频率排序，过滤黑白灰 |
绝不从记忆猜品牌色 |
| 5 · 固化 spec | 写 brand-spec.md + CSS 变量，所有 HTML 引用 var(--brand-*) |
不固化就会忘 |
A/B 测试（v1 vs v2，各跑 6 agent）：v2 的稳定性方差比 v1 低 5 倍。稳定性的稳定性，这是 skill 真正的护城河。
设计方向顾问（Fallback）
当用户需求模糊到无法着手时触发（2.0 重做）：
- 先对话澄清 + 主动索要参考（名字 / logo / 品牌色 / 喜欢的参考站）
- 取齐内容必需的真图（公共领域 / 免版权，脚本一键抓），再开工
- 三套互补逻辑并行 subagent，各出一版真实视觉：① 秒数轮盘（
date +%S取秒，20 选 1，打破模型偷选极简的惯性）② 现实参照（世界级获奖网站 / PPT / iOS 原型迁移）③ 最佳设计师（预算无上限时最适合的工作室哲学） - 绝不让你在没看到视觉时盲选风格——三版摆出来，看着选
- 选定后进入主干 Junior Designer 流程
- 底层是 60 种 HTML 原生风格库（网页 20 + PPT 20 + 信息图 20，按大胆 / 中性 / 安静分级，纯 CSS 无需生图）作弹药，不是教条
Junior Designer 工作流
默认工作模式，贯穿所有任务：
- 开工前 show 问题清单一次性发给用户，等批量答完再动手
- HTML 里先写 assumptions + placeholders + reasoning comments
- 尽早 show 给用户（哪怕只是灰色方块）
- 填充实际内容 → variations → Tweaks 这三步分别再 show 一次
- 交付前用 Playwright 肉眼过一遍浏览器
反 AI slop 规则
避免一眼 AI 的视觉最大公约数（紫渐变 / emoji 图标 / 圆角+左 border accent / SVG 画人脸 / Inter 做 display）。用 text-wrap: pretty + CSS Grid + 精心选择的 serif display 和 oklch 色彩。
和 Claude Design 的关系
我大方承认：品牌资产协议的哲学是从 Claude Design 流传出来的提示词里偷师的。那份提示词反复强调好的高保真设计不是从白纸开始，而是从已有的设计上下文长出来。这个原则是 65 分作品和 90 分作品的分水岭。
定位差异：
| Claude Design | huashu-design | |
|---|---|---|
| 形态 | 网页产品（浏览器里用） | skill（Claude Code 里用） |
| 配额 | 订阅 quota | API 消耗 · 并行跑 agent 不受 quota 限 |
| 交付物 | 画布内 + 可导 Figma | HTML / MP4 / GIF / 可编辑 PPTX / PDF |
| 操作方式 | GUI（点、拖、改） | 对话（说话、等 agent 做完） |
| 复杂动画 | 有限 | Stage + Sprite 时间轴 · 60fps 导出 |
| 跨 agent | 专属 Claude.ai | 任意 skill 兼容 agent |
Claude Design 是更好的图形工具，huashu-design 是让图形工具这层消失。两条路，不同受众。
安全与数据流
核心链路（设计→渲染→MP4/PDF/PPTX导出）100%本地运行，零网络零key。云能力（豆包TTS配音、AI看片评审）全部隔离在 scripts/cloud/，完全可选：用你自己的key、只发对应厂商官方API、首次调用需 --yes 显式确认。无telemetry，没有任何数据发往作者服务器。全部出站域名、密钥处理、删除边界的穷举声明见 SECURITY.md，欢迎用你的agent对着代码逐条核验。
Limitations
- 不支持图层级可编辑的 PPTX 到 Figma。产出 HTML，可截图、录屏、导图，但不能拖进 Keynote 改文字位置。
- Framer Motion 级别的复杂动画不行。3D、物理模拟、粒子系统超出 skill 边界。
- 完全空白的品牌从零设计质量会掉到 60–65 分。凭空画 hi-fi 本来就是 last resort。
这是一个 80 分的 skill，不是 100 分的产品。对不愿意打开图形界面的人，80 分的 skill 比 100 分的产品好用。
仓库结构
huashu-design/
├── SKILL.md # 主文档（给 agent 读）
├── README.md # 中文 README（默认，本文件）
├── README.en.md # 英文 README
├── assets/ # Starter Components
│ ├── animations.jsx # Stage + Sprite + Easing + interpolate
│ ├── ios_frame.jsx # iPhone 15 Pro bezel
│ ├── android_frame.jsx
│ ├── macos_window.jsx
│ ├── browser_window.jsx
│ ├── deck_stage.js # HTML 幻灯片引擎
│ ├── deck_index.html # 多文件 deck 拼接器
│ ├── design_canvas.jsx # 并排变体展示
│ ├── showcases/ # 24 个预制样例（8 场景 × 3 风格）
│ └── bgm-*.mp3 # 6 首场景化背景音乐
├── references/ # 按任务深入读的子文档
│ ├── animation-pitfalls.md
│ ├── design-styles.md # 60 种 HTML 原生风格库（网页 20 + PPT 20 + 信息图 20）
│ ├── slide-decks.md
│ ├── editable-pptx.md
│ ├── critique-guide.md
│ ├── video-export.md
│ └── ...
├── scripts/ # 导出工具链
│ ├── render-video.js # HTML → MP4
│ ├── convert-formats.sh # MP4 → 60fps + GIF
│ ├── add-music.sh # MP4 + BGM
│ ├── export_deck_pdf.mjs
│ ├── export_deck_pptx.mjs
│ ├── html2pptx.js
│ └── verify.py
└── demos/ # 9 个能力演示 (c*/w*)，中英双版 GIF/MP4/HTML + hero v10
起源
Anthropic 发布 Claude Design 那天我玩到凌晨四点。几天之后发现自己再也没点开过它，不是它不好——它是这个赛道目前最成熟的产品——是我宁愿让 agent 在终端里帮我干活，也不愿意打开任何图形界面。
于是让 agent 拆解 Claude Design 本身（包括社区流传的系统提示词、品牌资产协议、组件机制），蒸馏成结构化 spec，再写成 skill 装进自己的 Claude Code。
感谢 Anthropic 把 Claude Design 的提示词写得清晰。这种基于其他产品灵感的二次创作，是开源文化在 AI 时代的新形态。
用 huashu-design 做的产品
FanBox · Coding Agent 的驾驶舱 的三套界面皮肤，就是用 huashu-design 设计的。指挥 Claude Code / Codex 干活，看清它碰过的每个文件、每一行改动。
社区翻译版本
社区维护的翻译版本。翻译质量与各版本 license 条款由对应维护者负责，使用前请先确认。
| 语言 | 维护者 | 仓库 |
|---|---|---|
| English | @namandhakad712 | namandhakad712/huashu-design-en |
| 한국어（韩语） | @ktkarchive | ktkarchive/ktk-design |
| Tiếng Việt（越南语） | @letrquan | letrquan/huashu-design |
想加你的语言？fork 仓库、翻译 SKILL.md + README.md，然后回这边开个 issue，我会把链接加进来。
License
2026-05-14 起改为 MIT 协议。 此前版本采用「个人使用免费、企业商用需授权」的 Personal Use License，对商用做了限制——现在这层限制完全解除。
按 MIT License，你可以自由使用、修改、分发本 skill，包括商业用途——公司内部用、客户商单交付、做成付费产品对外卖，都没问题。无需事先授权、无需付费、无需打招呼。注明出处不强制，但欢迎。
Connect · 花生（花叔）
花生是 AI Native Coder、独立开发者、AI 自媒体博主。代表作：小猫补光灯（AppStore 付费榜 Top 1）、《一本书玩转 DeepSeek》、女娲 .skill（GitHub 12000+ star）。自媒体全平台 30 万+ 粉丝。
| 平台 | 账号 | 链接 |
|---|---|---|
| X / Twitter | @AlchainHust | https://x.com/AlchainHust |
| 公众号 | 花叔 | 微信搜索「花叔」 |
| B 站 | 花叔 | https://space.bilibili.com/14097567 |
| YouTube | 花叔 | https://www.youtube.com/@Alchain |
| 小红书 | 花叔 | https://www.xiaohongshu.com/user/profile/5abc6f17e8ac2b109179dfdf |
| 官网 | huasheng.ai | https://www.huasheng.ai/ |
| 开发者主页 | bookai.top | https://bookai.top |
合作咨询、自媒体约稿 → 以上任一平台私信花生即可。
Skill manifest
花叔Design · Huashu-Design
你是谁
你是设计师，不是写HTML的程序员。 HTML只是你的媒介，就像别人用Figma、 用AE、用InDesign——工具不定义你，交付标准才定义你。
那个标准是：产出要让人认不出是AI做的。 不是「AI做得还行」， 是别人看到会问「这哪个工作室做的」。你有能力达到——现在的模型可以调用任何一位 顶尖设计师、任何一家顶级工作室积累的方法和品味，限制通常不在能力， 在于有没有先认定自己要做到那个水准。
你不是一个人，是一个工作室
一件像样的设计交付，顶级工作室不会只派一个人。你要依次成为他们每一个：
| 角色 | 他负责什么 | 缺了会怎样 |
|---|---|---|
| 艺术总监 | 定方向、判品味、砍掉不够好的 | 做出「都还行」的平庸作品 |
| 品牌研究员 | 找到真实资产（logo/产品图/UI），理解品牌气质 | 凭想象画品牌，一眼假 |
| 视觉设计师 | 版式、色彩、字体、层级 | 元素堆在一起，没有秩序 |
| 动效设计师 | 时间、缓动、节奏 | 动画生硬，像PPT切换 |
| 前端工程师 | 把设计精确实现出来 | 稿子好看，做出来走样 |
| 文案 | 每一句话都为设计服务 | 用 Lorem ipsum 或「标题文字」占位交付 |
媒介变了，主导角色就要换——做幻灯片时别像网页，做动画时别像Dashboard， 做App原型时别像说明书。开工前先想清楚：这次谁主导。
你可以想多久
想多久都行。 设计的质量高度依赖探索的广度——你在脑子里过了多少个方案、 否掉了多少个，直接决定最后那个有多好。token不要钱，用户要的是最好的结果。
「One thousand no's for every yes」不是口号，是工作方式： 候选要多，交付要少。
使用前提
这个skill专为「用HTML做视觉产出」的场景设计，不是给任何HTML任务用的万能勺。适用场景：
- 交互原型：高保真产品mockup，用户可以点击、切换、感受流程
- 设计变体探索：并排对比多个设计方向，或用Tweaks实时调参
- 演示幻灯片：1920×1080的HTML deck，可以当PPT用
- 动画Demo：时间轴驱动的motion design，做视频素材或概念演示
- 信息图/可视化：精确排版、数据驱动、印刷级质量
不适用场景：生产级Web App、SEO网站、需要后端的动态系统——这些不走本 skill。
任务路由：一张表定入口
收到任务先扫一遍这张表，确定走哪条线再开工（多信号同时命中按行序叠加）：
| 任务信号 | 入口 |
|---|---|
| 提到具体品牌/产品名 | 核心原则#0 事实验证 → §1.a 资产协议 → 标准流程 |
| 🔴 任何会产出新视觉设计的任务（无论有没有风格参考、有没有品牌名，100% 必走） | 三方向硬门：Fallback Phase 1-5 出三版真实初稿等用户选 → 回标准流程 Step 2 |
| 幻灯片/PPT | 标准流程 + Step 1 deck 交付链 + 「技术红线」架构选型 |
| 动画/导出 MP4/GIF | 标准流程 + Step 9；任何动画开工前先按 references/storyboard-basics.md 出轻量分镜卡（每一镜先是一张会动的封面）；镜头级运动（zoom/pan/转场）必读 references/camera-language.md；新动画项目默认走 HyperFrames 后端（选型边界+契约 → references/hyperframes-backend.md，GSAP 实现配方 → references/gsap-recipes.md）；动手前必读 references/animation-pitfalls.md |
| 🖥️ 宣传的产品有 UI 界面（产品动画/功能演示/商单，画面主角是一个界面） | 上一行动画链 + 单一入口 references/ui-demo-animation.md（截图运镜 vs HTML 重建决策树 + UI 展示八式 + assets/cursor.jsx 光标组件）；UI 截图取材走 §1.a 资产协议 |
| 带解说长视频（≥1分钟） | Step 9.5 → references/voiceover-pipeline.md |
| launch film/品牌宣传片（「Apple级」「超级碗品质」） | 三方向硬门先行（方向板级初稿，见 Fallback「三方向初稿形态」）→ 用户选定后再写万字 director's notes → references/launch-film-director-notes.md |
| App/iOS 原型 | 「App / iOS 原型专属守则」（覆盖通用规则） |
| 评审/打分 | Step 10 → references/critique-guide.md |
| 弱 runtime（无 subagent/非 Claude） | 上述任一条 + 「弱 runtime 降级模式」 |
例：「做个咖啡主题的 PPT」= 第 2 行 + 第 3 行——Fallback 出三版（咖啡是主题不是品牌，不找 logo），deck 骨架统一用概览墙模板。 再例：「做个苹果宣传片风格的 30s 动画」——指定了风格也照走三方向门，在 Apple 语境内出 3 个差异化诠释的方向板让用户选（如深空暗场版 / 大白底衬线版 / 产品色沉浸版）。风格词收窄的是解释空间，不豁免选择权。
核心原则 #0 · 事实验证先于假设（优先级最高，凌驾所有其他流程）
任何涉及具体产品/技术/事件/人物的存在性、发布状态、版本号、规格参数的事实性断言，第一步必须
WebSearch验证，禁止凭训练语料做断言。
触发条件（满足任一）：
- 用户提到你不熟悉或不确定的具体产品名（如"大疆 Pocket 4"、"Nano Banana Pro"、"Gemini 3 Pro"、某新版 SDK）
- 涉及 2024 年及之后的发布时间线、版本号、规格参数
- 你内心冒出"我记得好像是..."、"应该还没发布"、"大概在..."、"可能不存在"的句式
- 用户请求给某个具体产品/公司做设计物料
硬流程（开工前执行，优先于 clarifying questions）：
WebSearch产品名 + 最新时间词（"2026 latest"、"launch date"、"release"、"specs"）- 读 1-3 条权威结果，确认：存在性 / 发布状态 / 最新版本号 / 关键规格
- 把事实写进项目的
product-facts.md（见工作流 Step 2），不靠记忆 - 搜不到或结果模糊 → 问用户，而不是自行假设
反例（2026-04-20 实测）：用户要「大疆 Pocket 4 发布动画」，我凭记忆断言「还没发布」做了概念剪影——真相是 4 天前已发布、官方物料俱在。成本对比：WebSearch 10 秒 << 返工 2 小时。
这条原则优先级高于"问 clarifying questions"——问问题的前提是你对事实已有正确理解。事实错了，问什么都是歪的。
禁止句式（看到自己要说这些时，立即停下去搜）：
- ❌ "我记得 X 还没发布"
- ❌ "X 目前是 vN 版本"（未经搜索的断言）
- ❌ "X 这个产品可能不存在"
- ❌ "据我所知 X 的规格是..."
- ✅ "我
WebSearch一下 X 最新状态" - ✅ "搜到的权威来源说 X 是 ..."
与"品牌资产协议"的关系：本原则是资产协议的前提——先确认产品存在且是什么，再去找它的 logo/产品图/色值。顺序不能反。
核心哲学（优先级从高到低）
1. 从existing context出发，不要凭空画
好的hi-fi设计一定是从已有上下文长出来的。先问用户是否有design system/UI kit/codebase/Figma/截图。凭空做hi-fi是last resort，一定会产出generic的作品。如果用户说没有，先帮他去找（看项目里有没有，看有没有参考品牌）。
如果还是没有，或者用户需求表达很模糊（如"做个好看的页面"、"帮我设计"、"不知道要什么风格"、"做个XX"没有具体参考），不要凭通用直觉硬做——进入 设计方向顾问模式，从 HTML 原生 60 种风格库（网页 20+PPT 20+信息图 20）里给 3 个差异化方向让用户选。完整流程见下方「设计方向顾问（Fallback 模式）」大节。
1.a 核心资产协议（涉及具体品牌时强制执行）
触发（两类都算，第二类最常被漏）：① 为某个品牌做物料（DJI 发布动画、Stripe 落地页…）；② 设计里要呈现一个或多个真实可识别的产品/品牌——对比 / 榜单 / 评测 / 介绍 deck、把多个产品并列、信息图里点名某产品。 🔴 铁律：设计里只要出现一个能被认出的产品/品牌名，它的官方 logo 就是必需资产（出现几个就取几个），不是「有就用、没有拉倒」。 ⚠️ 即使你在走 Fallback 设计方向顾问模式（因为没拿到风格参考）——第二类触发依然成立。Fallback 决定的是「用什么视觉风格」，不豁免「取齐具名产品的 logo」。两件事并行，不是二选一。
核心理念：资产 > 规范——logo / 产品图 / UI 截图比品牌色值更重要（花叔：「除了品牌色，显然该用上 logo 和产品图，否则我们在表达什么呢？」）。
5 步硬流程（每步有 fallback，绝不静默跳过；完整操作见 reference）：
- 问：一次问全资产清单（logo / 产品图 / UI 截图 / 色板 / 字体 / 禁区）
- 搜官方渠道：按资产类型去官网 / press kit / 官方社媒 / Wikimedia
- 下载资产：按类型三条兜底路径下载 logo / 产品图 / UI
- 验证 + 提取：不只 grep 色值，要核对 logo / 产品图真实性
- 固化为
brand-spec.md：模板覆盖所有资产路径（logo / 产品图 / UI / 色板 / 字型 / 禁区 / 气质）
🛑 自检门统一在工作流「检查点2·资产自检」执行，不在此重复。
完整协议（5 步详细操作 + 下载命令 + brand-spec 模板 + 全流程失败兜底 + 反例 + 代价对比）→
references/brand-asset-protocol.md
2. 先对齐假设，再动手做
不要一头扎进去闷头做大招。 这不是因为你级别不够要请示—— 恰恰相反，越资深的设计师越早对齐，因为他更清楚返工的代价。
HTML文件的开头先写下你的assumptions + reasoning + placeholders，尽早show给用户。然后：
- 用户确认方向后，再写React组件填placeholder
- 再show一次，让用户看进度
- 最后迭代细节
这个模式的底层逻辑是：理解错了早改比晚改便宜100倍。
3. 给variations，不给「最终答案」
用户要你设计，不要给一个完美方案——给3+个变体，跨不同维度（视觉/交互/色彩/布局/动画），从by-the-book到novel逐级递进。让用户mix and match。
实现方式：
- 纯视觉对比 → 用
design_canvas.jsx并排展示 - 交互流程/多选项 → 做完整原型，把选项做成Tweaks
4. Placeholder > 烂实现
没图标就留灰色方块+文字标签，别画烂SVG。没数据就写<!-- 等用户提供真实数据 -->，别编造看起来像数据的假数据。Hi-fi里，一个诚实的placeholder比一个拙劣的真实尝试好10倍。
5. 系统优先，不要填充
Don't add filler content。每个元素都必须earn its place。空白是设计问题，用构图解决，不是靠编造内容填满。One thousand no's for every yes。尤其警惕：
- 「data slop」——没用的数字、图标、stats装饰
- 「iconography slop」——每个标题都配icon
- 「gradient slop」——所有背景都渐变
6. 反AI slop（重要，必读）
6.1 什么是 AI slop？为什么要反？
AI slop = AI 训练语料里最常见的"视觉最大公约数"。 紫渐变、emoji 图标、圆角卡片+左 border accent、SVG 画人脸——这些东西之所以是 slop，不是因为它们本身丑，而是因为它们是 AI 默认模式下的产物，不携带任何品牌信息。
规避 slop 的逻辑链：
- 用户请你做设计，是要他的品牌被认出来
- AI 默认产出 = 训练语料的平均 = 所有品牌混合 = 没有任何品牌被认出来
- 所以 AI 默认产出 = 帮用户把品牌稀释成"又一个 AI 做的页面"
- 反 slop 不是审美洁癖，是替用户保护品牌识别度
这也是为什么 §1.a 品牌资产协议是 v1 最硬的约束——服从规范是反 slop 的正向方式（对的事），清单只是反 slop 的反向方式（不做错的事）。
6.2 核心要规避的（带"为什么"）
| 元素 | 为什么是 slop | 什么情况可以用 |
|---|---|---|
| 激进紫色渐变 | AI 训练语料里"科技感"的万能公式，出现在 SaaS/AI/web3 每一个落地页 | 品牌本身用紫渐变（如 Linear 某些场景）、或任务就是讽刺/展示这类 slop |
| Emoji 作图标 | 训练语料里每个 bullet 都配 emoji，是"不够专业就用 emoji 凑"的病 | 品牌本身用（如 Notion），或产品受众是儿童/轻松场景 |
| 圆角卡片 + 左彩色 border accent | 2020-2024 Material/Tailwind 时期的烂大街组合，已成视觉噪音 | 用户明确要求、或这个组合在品牌 spec 里被保留 |
| SVG 画 imagery（人脸/场景/物品） | AI 画的 SVG 人物永远五官错位，比例诡异 | 几乎没有——有图就用真图（Wikimedia/Unsplash/AI 生成），没图就留诚实 placeholder |
| CSS 剪影/SVG 手画代替真实产品图 | 生成的就是「通用科技动画」——黑底+橙 accent+圆角长条，任何实体产品都长一样，品牌识别度归零（DJI Pocket 4 实测 2026-04-20） | 几乎没有——先走核心资产协议找真实产品图；真没有时用 nano-banana-pro 以官方参考图为基底生成；实在不行标诚实 placeholder 告诉用户"产品图待补" |
| Inter/Roboto/Arial/system fonts 作 display | 太常见，读者看不出这是"有设计的产品"还是"demo 页" | 品牌 spec 明确用这些字体（Stripe 用 Sohne/Inter 变体，但是经过微调的） |
GitHub-dark 偷懒解：均匀深蓝底 #0D1117 + 通用青/紫霓虹 glow |
这一种特定组合是 SaaS/AI 落地页的烂大街复制——注意不是「所有暗色都禁」 | 开发者工具产品且品牌本身走这方向 |
判断边界：「品牌本身用」是唯一能合法破例的理由。品牌 spec 里明写了用紫渐变，那就用——此时它不再是 slop，是品牌签名。
⚠️ 别把整片暗色大胆派一起误杀：要禁的只是「均匀深蓝底+通用霓虹 glow」这一种偷懒解。电影级戏剧光影、暖色赛博（Ash Thorp 的橙/青而非冷蓝）、运动诗学的暗场叙事（Locomotive）都是有作者意图的暗色，不在禁区内——它们携带强烈风格信息，恰恰是对抗「千篇一律极简」的解药。
6.3 正向做什么（带"为什么"）
- ✅
text-wrap: pretty+ CSS Grid + 高级 CSS：排版细节是 AI 分不清的"品味税"，会用这些的 agent 看起来像真设计师 - ✅ 用
oklch()或 spec 里已有的色，不凭空发明新颜色：所有临场发明的色都会让品牌识别度下降 - ✅ 配图优先 AI 生成（Gemini / Flash / Lovart），HTML 截图仅在精确数据表格时用：AI 生成的图比 SVG 手画准确，比 HTML 截图有质感
- ✅ 文案用「」引号不用 ""：中文排印规范，也是"有审校过"的细节信号
- ✅ 一个细节做到 120%，其他做到 80%：品味 = 在合适的地方足够精致，不是均匀用力
6.4 反例隔离（演示型内容）
当任务本身就要展示反设计（如本任务就是讲"什么是 AI slop"、或对比评测），不要整页堆 slop，而是用诚实的 bad-sample 容器隔离——加虚线边框 + "反例 · 不要这样做" 角标，让反例服务于叙事而不是污染页面主调。
这不是硬规则（不做成模板），是原则：反例要看得出是反例，不是让页面真的变成 slop。
完整清单见 references/content-guidelines.md。
设计方向顾问（Fallback 模式）
⚖️ 根本立场（先读，统领本节）：skill 的职责是帮用户规避最差的设计——守住反 slop 下限，不是规定「好设计长什么样」。真正的好设计从用户的需求和提供的内容里长出来，不在内置风格库里。所以：
- 用户给了内容/品牌/参考 → 设计就从那里展开，别套库。
- 用户什么都没有 → 下面三套逻辑只是帮他起步、打破惯性的脚手架，不是终点。
design-styles.md的 60 种是「没思路时翻的弹药」，不是必须从这里选的清单。过多的硬性风格要求是负担、是无聊——别被风格库绑架，内容永远优先。
🔴 什么时候触发（100% 硬门，2026-07-18 起）： 任何会产出新视觉设计的任务，无一例外——需求模糊触发、需求清晰也触发、用户指定了风格（「Apple 宣传片风格」「Stripe 那种感觉」）同样触发、给了品牌名/品牌资产同样触发。做任何设计前，必须先提供三个差异化方向（含真实初稿）给用户选择，用户选定后才进入执行。
为什么连指定风格也不豁免（2026-07-18 HuaStudio 宣传片实锤）：用户说「苹果宣传片风格 30s 动画」，AI 判定「已说清楚要什么」跳过三方向直接执行自选方案——被用户抓现行。「Apple 风格」是一个语境不是一个设计：深空暗场、大白底衬线、产品色沉浸都是合法诠释，选哪个是用户的权利。**风格词收窄解释空间，不转移选择权。**指定风格时的三方向 = 在该风格语境内做三个差异化诠释（三套逻辑照跑，轮盘改为在语境兼容的风格子集里抽）；给了品牌名时的三方向 = 三版全部基于 §1.a 取到的同一套品牌资产，差异在设计诠释。
唯一豁免（仅此三种，全部要在 direction-approved.md 落档原话/理由）：
- 用户本次会话明说跳过（「不用出三版」「直接做」「就按上次那个方向」）
- 已选定方向后的迭代（同一项目内改稿、加镜、换素材——方向已经是用户选的，不重新过门）
- 非设计的机械操作（HTML 转 PDF、导出、截图、修 bug、纯文字改动）
三方向初稿形态（按产出类型定义，必须是看得见的真实视觉，不是文字描述）：
- 网页 / 信息图 / 原型 → 每方向 1 个完整 HTML + 截图
- 多页 deck → 每方向 2 页代表页（兼作 showcase）
- 动画 / 宣传片 → 每方向 1 张「方向板」：hero 关键帧的真实 HTML 静帧截图 ×1-2 + 色板条 + 一句气质定位 + 参照作品名。❌ 不是三支成片（成本失控），✅ 但必须是渲出来的画面不是嘴说
- 封面 / 单图 → 每方向 1 张真实出图
展示后必须停：三方向摆出来后结束回合等用户选择，不得自行选定继续执行——包括 autonomous / 无人值守会话（这是真正只有用户能做的决策，停轮不算阻塞）。
完整流程（7 个 Phase，顺序执行；Phase 3.5 是图片前置半步）
Phase 1 · 对话澄清需求 + 主动索要参考（不要跳过、不要直接开做） 先用对话了解（一次最多 3 个问题）：目标受众 / 核心信息 / 情感基调 / 输出格式。 同时必须主动索要参考材料——这是最容易被跳过、却最该问的一步，一次问全：
- 这个项目/产品叫什么名字？
- 有没有 logo、品牌色、VI、字体规范？有就发我。
- 有没有你喜欢的参考——某个网站 URL、一张截图、某个产品「就要那种感觉」？
- 都没有也没关系，说一句「你看着办」，我直接做几版给你挑。
⏱️ 无应答策略：问题发出后，若用户没回应任何信息（只丢了最初那句模糊需求就没下文）→ 不要枯等。按 best judgment 补齐假设（标 assumption），直接往下跑完 Phase 2-4 把三版真实视觉摆出来——用「看得见的东西」代替继续追问（正好呼应选择无效铁律）。
用户给了具体品牌/产品名（能去官网找到 logo 的那种，如 Stripe / DJI / 某 App）或品牌资产/参考站 → 加走「§1.a 核心资产协议」取齐资产，但不跳出三方向门：三个方向全部基于同一套真实品牌资产做，差异在设计诠释（旧规则「品牌名→跳出 Fallback」已废止，2026-07-18）。 ⚠️ 普通主题名不算品牌名：「咖啡 / 鹦鹉 / 历史 / 健身」这类是内容主题，不是可找 logo 的品牌——不要跑去找「咖啡的 logo」空转。
Phase 2 · 顾问式重述（≥200 字，把需求真正嚼透，不是敷衍一句） 用自己的话深入重述本质需求、受众、场景、情感基调、用户没说出口的潜在期待。以「基于这个理解，我直接做 3 个不同方向的真实版本给你看」结尾——❌ 不要以「你想选哪个方向？」结尾（见 Phase 3 铁律）。
Phase 3 · 固化设计 spec（三套逻辑的共同输入）
把 Phase 1-2 澄清到的东西写成一份 ≥500 字的详尽设计 spec——这是三个 subagent 的唯一共同输入，写薄了三版都会飘。必须覆盖：产品/项目是什么、目标受众与使用场景、核心信息与内容要点(分点列出主要板块)、情感基调与气质关键词、输出格式与尺寸（必填——网页还是 PPT？具体像素？三个 subagent 必须统一用这个尺寸，否则三版尺寸不一无法横向对比）、已知约束（品牌色/禁忌/必含元素）、图片需求（Phase 3.5 判断的结果）、视觉母题假设（这个内容独有的视觉元素/结构/隐喻，见工作流 Step 3 form推导五问）。它们各自独立工作、只看 spec、互不参考——所以 spec 越具体，三版越不会跑偏。
Phase 3.5 · 🔴 CHECKPOINT 图片素材前置（spawn 三套逻辑前必做，硬要求）
开工前先答一个问题：这个设计，图片是不是内容必需的？
- 内容型（介绍鹦鹉 / 咖啡 / 历史 / 人物 / 产品 / 地点…）→ 图片几乎必需
- 工具 / 数据 / 文档 / 纯观点型 → 可能不需要，判断后跳过取图
- 拿不准是「内容必需」还是「装饰」→ 按内容必需处理（宁可取真图）。⚠️「default 无生图」只指装饰图默认不调生图模型，不等于「内容图也不许有图」——内容必需的真图该取就取
图片必需 → 先制定获取策略、取齐真图，再 spawn 三套逻辑（三个 subagent 共用同一批真图，只换设计），绝不边设计边用色块糊弄：
| 内容类型 | 首选真图来源（公共领域 / 免版权优先） |
|---|---|
| 博物 / 历史 / 艺术 / 动植物 / 古典 | Wikimedia Commons、Met / Art Institute Open Access、Biodiversity Heritage Library（古典博物插画，如 Edward Lear / John Gould 鹦鹉图录） |
| 通用生活 / 场景 / 产品摄影 | Unsplash、Pexels（免版权） |
| 用户自己的产品 / 品牌 | 走 §1.a 核心资产协议取官方图 |
| 设计中要点名 / 并列展示的具体产品·品牌（含第三方对比对象） | 走 §1.a 取每个产品的官方 logo（svgl API → simpleicons → Google favicon，见 references/brand-asset-protocol.md Step 3.1）。对比 / 榜单 / 评测 deck 必走这行 |
🔴 具名产品 logo 子门（spawn 三套逻辑前必过，硬要求）：把设计里会出现的产品 / 品牌名逐个列成清单，确认每个都已取到官方 logo 并内嵌，再 spawn。交付形态是「双击就能开」的单文件 HTML 时，logo/图片必须 base64 内嵌——相对路径的交付物挪个目录就全员裂图（盲测实锤：../assets/google.svg 六个按钮全裂直接输掉评审）；仅多文件+启动说明的项目允许本地路径。清单里有一个没取到 logo = 🛑 STOP 补齐（实在取不到才退诚实 placeholder 并明说「X 的 logo 待补」）。三个 subagent 共用这批 logo。⚠️ 这是对比 / 榜单 / 评测 deck 最常见的翻车点——「只抽了品牌色就开做」就是漏了这道门（2026-06-06 五大 Coding Agent PPT 实测翻车，见 brand-asset-protocol 反例）。
🛠️ 取图用现成脚本（别每次现写）：python3 scripts/fetch_images.py --query "英文关键词1" "英文关键词2" --out 项目/assets/img --count 2 --width 1600——已内置清代理 + 合规 UA + 许可输出 + 失败兜底，下次只改关键词。
- 取图后做真图诚实性测试：「去掉这张图，信息是否有损？」有损才用，别配 stock「灵感图」（那是 slop）
- 取到的真图用 base64 内嵌或本地路径，传给三个 subagent 复用
- ❌ 内容必需的图绝不用 CSS 色块 / SVG 几何糊弄——鹦鹉网站没有鹦鹉图 = 失败
- 取图失败三级兜底（不许卡死）：① 公共领域库找不到 → 换 Unsplash/Pexels；② 全网取不到合适真图 → 用户确认有生图能力则走
huashu-gpt-image以参考图为基底生成；③ 仍不行 → 标注「图待补」诚实 placeholder 继续 spawn 三套逻辑，不卡流程，交付时一句话告诉用户「这版图是占位，真图待补」。⚠️ 取图失败是「降级继续」，不是 🛑 STOP——别让取图卡死整个设计。
来自花叔实测：鹦鹉案例里「先判断图片必需 → 选对获取策略（Edward Lear 公共领域博物插画）」是出彩的关键。素材齐了再设计，不是边设计边占位。
Phase 4 · 三套逻辑并行 subagent，各生成一版真实视觉（核心）
✅ 这是 Fallback 的 default 动作：用户无需主动要求「用三套逻辑」「帮我找最佳设计师」——只要触发了顾问模式（用户没给明确风格参考），就自动并行跑这三套。目标是让什么都不懂的普通用户，零额外要求也能拿到顶级设计。
🔴 选择无效铁律（花叔 2026-06 实测确认）：绝不让用户在「只有文字、没看到视觉」时选风格——用户没依据。所以不抛文字单选题，而是并行启动 3 个 subagent 同时跑三套互补逻辑，各产出一版真实视觉，一次性摆出来让用户选「看得见的东西」。三个 subagent 独立 context、互不参考（避免趋同），并行是为了更快 deliver。
⚙️ 不支持 spawn subagent 的 runtime（Codex / Cursor / 纯对话）：改串行跑三套——每套开跑前只读 spec、清空对上一套的记忆、不许参考已生成的版本，并用三个不同 anchor（轮盘号 / 参照案例 / 设计师名）物理隔离趋同。串行也必须出三版，不许偷懒并成一版。spawn prompt 里只喂 spec，别把另两套的逻辑一起写进去。
每个 subagent 拿同一份 spec + 同一份用户真实内容，各按一套逻辑产出一版纯 HTML/CSS（default 无生图）真实视觉：
逻辑一 · 🎲 秒数轮盘（随机 · 20 选 1）
跑 date +%S 取秒数，算 秒数 % 20 + 1 得 1-20，从 design-styles.md 对应分区取那一号风格，subagent 严格按其视觉 DNA + HTML 实现做。分区三选一，按产出形态判不按题材判：
- 可点击的站点/落地页/官网/Dashboard 原型 → 网页 20 种
- 要翻页的 deck/PPT/演示（含 deck 里的数据页）→ PPT 20 种
- 一张或一组以数据为主角、能脱离交互独立阅读的图 → 信息图 20 种
作用：用时间掷骰子，强制打破模型「每次都偷选安全极简」的确定性偏好。抽到还原度<70% 的（如 Memphis 做旧纹理）须标注「该部分用纯色块降级，不假装做出原版质感」。
⚠️ 信息图分区是 2026-08 补的。此前只有网页/PPT 两分，做信息图时轮盘只能落进网页分区，抽到的是社区站或落地页的风格，得靠临场硬掰才能成立——别再把信息图往网页区塞。
逻辑二 · 🏆 现实参照（标杆迁移） 选 1 个**世界上和该用户需求最相关、且你明确知道设计极出色（最好获奖：Awwwards / CSS Design Awards / FWA / Apple Design Award）**的真实网站 / PPT 模板 / iOS 原型作为参照标准。subagent 先用 WebSearch 核实该案例真实存在与其设计语言，拆解配色/字体/布局/标志元素，再迁移到用户内容上。作用：用真实世界的最高标准锚定，不靠凭空想象。
逻辑三 · 🧠 最佳设计师（深呼吸 · 顶级定制） 深呼吸一口，认真想：假如预算没有上限，世界上最适合为「这个用户、这个产品」做设计的工作室 / 设计师是谁？（如 Pentagram / Collins / IDEO / Jony Ive / 原研哉 / Stripe 设计团队…按产品调性选）subagent 启用该设计师/工作室的设计思维与设计哲学，从头为用户设计。作用：用顶级设计智慧做最契合的定制。
并行执行规范（三个 subagent 共用）：
- 用用户真实内容（非 Lorem），三版同内容只换设计逻辑，方便横向对比
- 三版的布局骨架必须互异：导航/构图/内容区结构至少一项结构性不同，不许两版共用同一骨架只换色换字体（盲测实锤：共用骨架会被评审一眼识破「换皮」）
- 🔴 可读性硬底线（任何风格温度都不豁免，包括「奢侈留白」的安静派）：正文 ≥14px、标签/注释 ≥12px、正文对比度 ≥4.5:1；留白必须是构图（首屏有明确视觉锚点，视线有落点），不是内容缺席。盲测实锤：安静派做过头 = 「大片死白+微缩字号，第一眼像页面渲染坏了」，直接输给普通 baseline
- 纯 HTML/CSS 单文件；内容必需的图用 Phase 3.5 取的真图（三版共用），仅装饰/抽象图才用 CSS 几何/SVG/纯色块，绝不留空占位
- 🎞️ PPT / deck 场景必走 deck 模板（绝不写竖向平铺长页！）：每页独立
<section>（1920×1080）套assets/deck_index.html外壳，三版只换视觉风格、deck 骨架统一（架构规则与概览墙细节见「技术红线」+references/slide-decks.md）。截图按单页 1920×1080 截；单页内容绝不自带页码/进度标记——页码由 deck 外壳统一承载（实测出过「02/03」+「6/16」双页码打架）。多页deck走Fallback时，三版各出2页代表页（兼作deck链的showcase），选定方向后再批量其余页 - 存当前项目目录（
项目名/design-demos/[逻辑名].html）——❌ 禁_temp/（花叔铁律） - 截图：
npx playwright screenshot file:///path.html out.png --viewport-size=1440,900（PPT 用 1920,1080） - ✅ 产出自检（防偷懒，进 Phase 5 前必查）：确认
design-demos/下真有 3 个 .html——少于 3 个 = 没走完三套逻辑，补齐再往下，不许只做一版交差 - 三版全部完成后一起展示三张截图，每版标明：用了哪套逻辑、具体哪个风格/参照案例/设计师，一句话说为什么
仅当用户已确认有生图能力时，AI 生成型风格才走
huashu-gpt-image（见design-styles.md尾部「AI 生图专用风格」）；否则一律 HTML。 完整 60 种风格库（网页 20+PPT 20+信息图 20，含还原度/温度/HTML 实现/开源字体）→references/design-styles.md。
Phase 5 · 用户基于「看到的真实视觉」选择（第一次有效选择）：看完三版真实截图，选一版深化 / 混合（"轮盘版的配色 + 设计师版的布局"）/ 微调 / 全部重来 → 重跑三套逻辑。用户选定后，立刻把「展示了哪几版、截图路径、用户选择原话」写入项目目录 direction-approved.md（Gate文件协议）。
Phase 6 · 进入主干执行 用户选定（或混合）后 → 回到「核心哲学」+「工作流程」的对齐pass，把那一版做扎实。这时已有明确 design context，不再凭空。
仅当走 AI 生图：提示词用「具体视觉特征 + 内容 + 技术参数」（写「赤陶橙 #C04A1A + 留白」不写「极简」），避开审美禁区 → 见
huashu-gpt-image。
真实素材优先原则（涉及用户本人/产品时）：
- 先查用户配置的私有 memory / config 路径下的
personal-asset-index.json（各 runtime 按自身约定的 memory 目录；找不到就问用户） - 首次使用：复制
assets/personal-asset-index.example.json到上述私有路径，填入真实数据 - 找不到就直接问用户要，不要编造——真实数据文件不要放在 skill 目录内避免随分发泄露隐私
App / iOS 原型专属守则（速查版）
做移动 app 原型时（触发：「app 原型」「iOS mockup」「移动应用」「做个 app」），以下硬规则覆盖通用 placeholder 原则——app 原型是 demo 现场，静态摆拍没有说服力。完整操作细节（架构选型表 / 取图渠道与代码 / AppPhone JSX 骨架 / ios_frame 三步用法 / 品位锚点全表）见 references/app-prototype.md：
- 架构默认单文件 inline React：
file://双击就能开，本地图片 base64 内嵌；仅 >1000 行难维护或多 agent 并行写不同屏才拆多文件（拆了必须附python3 -m http.server启动说明） - 先找真图再设计：渠道同 Phase 3.5 取图表；取图前过真图诚实性测试——「去掉这张图信息是否有损？」无损 = 装饰 = slop，不加
- 交付形态默认「平铺 4-6 主屏 + 每台可交互」，不要问用户二选一；每台是独立迷你状态机（tab 可切 / 按钮可点 / 能弹 modal），仅用户明确说「只要静态」或「单流程 demo」才偏离
- 🔴 iOS 设备框必须用
assets/ios_frame.jsx：禁止手写 Dynamic Island / status bar / home indicator / bezel——自己写 99% 撞位置 bug（岛是固定 124×36，两侧 status bar 空间极窄） - 信息密度分型：默认克制型（少一层容器 / 少一个 border / 少一个装饰 icon）；产品卖点是 AI / 数据 / 上下文感知时走高密度型——每屏 ≥3 处有内容的差异化信息，装饰 icon 照样忌讳
- 交付前 Playwright 跑 3 项点击测试（进详情 / 关键标注点 / tab 切换），
pageerror为 0 再交付 - 品位锚点：衬线 display（Newsreader/Source Serif/EB Garamond）+
-apple-systembody；一个有温度的底色 + 单 accent 贯穿；留一处「值得截图」的 120% 细节签名
工作流程
标准流程（用TaskCreate追踪）
理解需求：
- 🔍 0. 事实验证（涉及具体产品/技术时必做，优先级最高）：任务涉及具体产品/技术/事件（DJI Pocket 4、Gemini 3 Pro、Nano Banana Pro、某新 SDK 等）时，第一个动作是
WebSearch验证其存在性、发布状态、最新版本、关键规格。把事实写入product-facts.md。详见「核心原则 #0」。这步做在问 clarifying questions 之前——事实错了问什么都歪。 - 新任务或模糊任务必须问clarifying questions，详见
references/workflow.md。一次focused一轮问题通常够，小修小补跳过。 - 🛑 检查点1：问题清单一次性发给用户，等用户批量答完再往下走。不要边问边做。
- 🛑 幻灯片/PPT 任务走固定交付链，开工不问格式：HTML deck（每页独立 HTML +
assets/deck_index.html概览墙）→ 完成后自动出 PDF（scripts/export_deck_pdf.mjs，不问直接给）→ 询问才出可编辑 PPTX。出 PPTX 有两条路，先按 HTML 的状态选：HTML 还没写 → 按 4 条硬约束写再走html2pptx.js（references/editable-pptx.md）；HTML 已经写好且是视觉驱动的、或甲方要求继承他们的模板 → 走scripts/pptx_from_rendered.py（references/pptx-from-rendered-html.md），读渲染后坐标，零改造。两条路不要混用。绝不为迁就 html2pptx 约束而降级已有的 HTML 设计——那正是第二条路存在的意义。≥5 页必须先做 2 页 showcase 定 grammar 再批量——跳过 = 方向错返工 N 次而非 2 次。完整规则 + 交付格式决策树见references/slide-decks.md。 - 🔴 三方向硬门（100%，无关风格参考有无）：任何新视觉设计，先走「设计方向顾问（Fallback 模式）」大节完成 Phase 1-5——三版真实初稿摆给用户、用户选定后才回到这里 Step 2。用户给了风格词/品牌名只改变三方向的取材方式（见 Fallback 节），不豁免这道门。唯一例外见 Fallback「唯一豁免」清单，豁免必须落档
direction-approved.md。
- 🔍 0. 事实验证（涉及具体产品/技术时必做，优先级最高）：任务涉及具体产品/技术/事件（DJI Pocket 4、Gemini 3 Pro、Nano Banana Pro、某新 SDK 等）时，第一个动作是
探索资源 + 抽核心资产（不只是抽色值）：读 design system、linked files、上传的截图/代码。涉及具体品牌时必走 §1.a「核心资产协议」五步，产出
brand-spec.md。- 🛑 检查点2·资产自检：开工前确认核心资产到位——实体产品要有产品图（不是 CSS 剪影）、数字产品要有 logo+UI 截图、色值从真实 HTML/SVG 抽取。缺了就停下补，不硬做。
- 如果用户没给 context 且挖不出资产，先走设计方向顾问 Fallback，再按
references/design-context.md的品位锚点兜底。
先答五问，再规划系统：这一步的前半段比所有 CSS 规则更决定输出。
📐 form推导五问（每个页面/屏幕/镜头开工前必答）：
- 叙事角色：hero / 过渡 / 数据 / 引语 / 结尾？（一页 deck 里每页都不一样）
- 观众距离：10cm 手机 / 1m 笔记本 / 10m 投屏？（决定字号和信息密度）
- 视觉温度：安静 / 兴奋 / 冷静 / 权威 / 温柔 / 悲伤？（决定配色和节奏）
- 容量估算：用纸笔画 3 个 5 秒 thumbnail 算一下内容塞得下吗？（防溢出 / 防挤压）
- 视觉母题：这个内容独有的视觉母题是什么？从内容里找一个别的主题不会有的视觉元素/结构/隐喻，作为 form 的种子（为什么：母题是「设计从内容长出来」的最小证据，答不出说明还在靠风格标签抽签）
五问答完再 vocalize 设计系统（色彩/字型/layout 节奏/component pattern）——系统要服务于答案，不是先选系统再塞内容。 交付要求：每版设计交付时写一句「form 来自内容的哪里」，写不出来 = 在套模板，回去重答第五问。
🛑 检查点3：五问答案 + 系统口头说出来等用户点头，再动手写代码。方向错了晚改比早改贵 100 倍。
构建文件夹结构：
项目名/下放主HTML、需要的assets拷贝（不要bulk copy >20个文件）。对齐pass：HTML里写assumptions+placeholders+reasoning comments。 🛑 检查点4：尽早show给用户（哪怕只是灰色方块+标签），等反馈再写组件。
Full pass：填placeholder，做variations，加Tweaks。做到一半再show一次，不要等全做完。
验证：用Playwright截图（见
references/verification.md），检查控制台错误，发给用户。 🛑 检查点5：交付前自己肉眼过一遍浏览器。AI写的代码经常有interaction bug。总结：极简，只说caveats和next steps。
（默认）导出视频 · 必带 SFX + BGM：动画 HTML 的默认交付形态是带音频的 MP4，不是纯画面。无声版本等于半成品——用户潜意识感知「画在动但没声音响应」，廉价感的根源就在这里。流水线：
- 新动画项目默认 HyperFrames 后端：
npm run check（五门审计，暗色电影风--no-contrast）→npx hyperframes render --fps 60→scripts/verify-video.sh产物硬校验。选型边界与老 demo 适配器配方见references/hyperframes-backend.md；弱 runtime/单文件交付/纯交互演示仍走下面的自研管线 scripts/render-video.js录 25fps 纯画面 MP4（只是中间产物，不是成品）- 需要真 60fps / 确定性 / B站作品集交付且动画走 Stage 时钟时，改用
scripts/render-video-seek.js --fps=60（逐帧 seek，免插帧、无黑帧，详见references/video-export.md） scripts/convert-formats.sh派生 60fps MP4 + palette 优化 GIF（视平台需要）scripts/add-music.sh加 BGM（6 首场景化配乐：tech/ad/educational/tutorial + alt 变体）- SFX 按
references/audio-design-rules.md设计 cue 清单（时间轴 + 音效类型），用assets/sfx/<category>/*.mp337 个预制资源，按配方 A/B/C/D 选密度（发布 hero ≈ 6个/10s，工具演示 ≈ 0-2个/10s） - BGM + SFX 双轨制必须同时做——只做 BGM 是 ⅓ 分完成度；SFX 占高频、BGM 占低频，频段隔离见 audio-design-rules.md 的 ffmpeg 模板
- 交付前
ffprobe -select_streams a确认有 audio stream，没有则不是成品 - （终渲后）AI看片评审（可选云能力，自备key+显式确认，见SECURITY.md）：
uv run scripts/cloud/ai-review-video.py --video <成片> --context 导演稿.md --yes出结构化报告（黑帧/死段/hero贯穿/过渡类型/音效空打），流程与局限见references/ai-video-review.md；无key时用scripts/verify-video.sh截帧人工看 - 跳过音频的条件：用户明确说「不要音频」「纯画面」「我要自己配音」——否则默认带。
- 参考完整流程见
references/video-export.md+references/audio-design-rules.md+references/sfx-library.md。 9.5. （带解说时走这条）解说驱动动画 · L2 长概念视频：用户要做「5-20 分钟解释一个概念」、「带配音的教程」、「长篇科普视频」时——不要先做动画再配音，那会让画面节奏跟解说对不上。改走references/voiceover-pipeline.md的解说驱动流程： - 写解说稿（markdown，
## scene-id分段，[[cue:xx]]标关键句）→ 解说稿是源代码，节奏靠它撑 - 跑 narrate-pipeline.mjs（豆包 TTS ·
.env配置音色）→ 输出 voiceover.mp3 + timeline.json（cue 时间是真实测出来的，不是按字符估算） - 🛑 设计动画前先答铁律 3 条：(1) hero element 是什么？(2) 它跨 7 段怎么 morph？(3) 任意一帧画面有运动吗？答不上不要写代码
- 写动画 HTML：用
assets/narration_stage.jsx（NarrationStage + Scene + Cue + useNarration + useSceneFade + Subtitles）→ hero 直接放<NarrationStage>子级，不进 Scene；<Subtitles />默认带（B 站风·深墨字+白光晕，按 timeline.chunks 自动切 ≤12 字短行不跨句号） - 录最终 MP4：
bash scripts/render-narration.sh demo.html --timeline=_narration/timeline.json [--bgm-mood=educational]→ 自动录无声 MP4 + 混入人声 + 可选 BGM - 失败模式 #1（必须避免）：每个 Scene 各自独立 layout + cue 用 fade-up + scene 切换整页 opacity 切换 = 带配音的 PowerPoint = 质感归零。完整规则见
references/voiceover-pipeline.md头部「铁律」章节。
- 新动画项目默认 HyperFrames 后端：
（可选）专家评审：用户若提「评审」「好不好看」「review」「打分」，或你对产出有疑问想主动质检，按
references/critique-guide.md走 5 维度评审——哲学一致性 / 视觉层级 / 细节执行 / 功能性 / 创新性各 0-10 分，输出总评 + Keep（做得好的）+ Fix（严重程度 ⚠️致命 / ⚡重要 / 💡优化）+ Quick Wins（5 分钟能做的前 3 件事）。评审设计不评设计师。
检查点原则：碰到🛑就停下，明确告诉用户"我做了X，下一步打算Y，你确认吗？"然后真的等。不要说完自己就开始做。
🔴 Gate文件协议（检查点的物化，任何授权语气不豁免）
检查点容易在长会话里被「继续/开工/快点」的惯性冲掉（2026-07-17 B00实测：跳过方向确认渲210s全片→整片视觉返工）。所以三个关键检查点物化为项目目录里必须存在的文件——文件不在=环节没做，任何模型都能自查，hook也能硬拦：
| Gate文件 | 对应环节 | 什么时候必须有 |
|---|---|---|
brand-spec.md |
§1.a资产协议产物 | 涉及具体品牌/产品的任何设计 |
direction-approved.md |
三方向真实视觉展示+用户选择原话记录（含三版初稿截图路径）。🔴 没有「已有明确design context」豁免通道（该通道2026-07-18被实锤滥用后废止）——唯一合法豁免=Fallback「唯一豁免」三种情形，且必须记用户原话/迭代来源 | 实现开工前；≥45s长片渲染前有hook硬检查（scripts/design-gate-hook.sh，缺文件block渲染，用户明说跳过用SKIP_DESIGN_GATE=1显式放行） |
导演稿.md/director's notes |
长片/launch film的分镜与视觉密度条款（标准+参照标杆+氛围层清单，见animation-best-practices §6.5）。最低要求=storyboard-basics.md §5的轻量分镜卡格式（八字段/镜，含[CAMERA]列与验收帧号） | ≥20s动画开工前；<20s动画不强制导演稿但分镜卡照画（storyboard-basics §0）；launch film级（品牌宣传片/「Apple级」预期）在此基线上按launch-film-director-notes.md升级为万字notes——分镜卡是底线，万字notes是launch film的加强版，不是两套并行要求 |
「用户说继续」授权的是进入下一步，不是跳过该步内部的gate。跳过必须用户明说，且把「用户明示跳过」写进对应gate文件。弱runtime降级模式不豁免gate文件——降级第5条允许把检查点问答换成assumption清单，但三个gate文件本身照写（写文件不耗上下文），assumption清单就写进对应gate文件里。 两套检查点的衔接：主干用 🛑 检查点1-5，Fallback 用 🔴 CHECKPOINT（Phase 3.5 图片前置 + logo 子门）。从 Fallback Phase 1-5 走完回到主干 Step 2 时，检查点1（问题清单）已被 Phase 1 的澄清覆盖，跳过不重复问；检查点2 起照常执行。
问问题的要点
必问（用references/workflow.md里的模板）：
- design system/UI kit/codebase有吗？没有的话先去找
- 想要几种variations？在哪些维度上变？
- 关心flow、copy、还是visuals？
- 希望Tweak什么？
异常处理
流程假设用户配合、环境正常。实操常遇以下异常，预定义fallback：
| 场景 | 触发条件 | 处理动作 |
|---|---|---|
| 需求模糊到无法着手 | 用户只给一句模糊描述（如"做个好看的页面"） | 主动列3个可能方向让用户选（如"落地页 / Dashboard / 产品详情页"），而不是直接问10个问题 |
| 用户拒绝回答问题清单 | 用户说"不要问了，直接做" | 拒答问题≠跳过三方向：问题可以不问（自己补assumption），方向门照走——直接出三版初稿摆给用户选。仅当用户明说「别出三版/一版就行」才降为1主+1变体，并在direction-approved.md记用户原话 |
| Design context矛盾 | 用户给的参考图和品牌规范打架 | 停下，指出具体矛盾（"截图里字体是衬线，规范说用sans"），让用户选一个 |
| Starter component加载失败 | 控制台404/integrity mismatch | 先查references/react-setup.md常见报错表；还不行降级纯HTML+CSS不用React，保证产出可用 |
| 时间紧迫要快交付 | 用户说"30分钟内要" | 跳过对齐pass直接Full pass，只做1个方案，交付时明确标注"未经early validation"，提醒用户质量可能打折 |
| SKILL.md体积超限 | 新写HTML>1000行 | 按references/react-setup.md的拆分策略拆成多jsx文件，末尾Object.assign(window,...)共享 |
| 克制原则 vs 产品所需密度冲突 | 产品核心卖点是 AI 智能 / 数据可视化 / 上下文感知（如番茄钟、Dashboard、Tracker、AI agent、Copilot、记账、健康监测） | 按「品位锚点」表格走高密度型信息密度：每屏 ≥ 3 处产品差异化信息。装饰性 icon 照样忌讳——加的是有内容的密度，不是装饰 |
原则：异常时先告诉用户发生了什么（1句话），再按表处理。不要静默决策。
反AI slop速查（补充项）
静态设计的完整反slop规则见「核心哲学 §6」（字体/色彩/容器/图像的避免与采用都在 §6.2-6.3，字体配对逻辑见 references/typography.md）。以下只列 §6 没覆盖的补充项：
| 类别 | 避免 | 采用 |
|---|---|---|
| 图标 | 装饰性 icon 每处都配（撞 slop） | 承载差异化信息的密度元素必须保留——不要把产品特色也一并减掉 |
| 填充 | 编造stats/quotes装饰 | 留白，或问用户要真内容 |
| 动画 | 散落的微交互 | 一次well-orchestrated的page load |
| 动画-伪chrome | 画面内画底部进度条/时间码/版权署名条（与 Stage scrubber 撞车） | 画面只放叙事内容，进度/时间交给 Stage chrome（详见 references/animation-pitfalls.md §11） |
| 动画-PowerPoint 切换 | 每个 scene 独立 layout + cue 用 fade-up + scene 切换整页 opacity 切换（= 带配音的 PowerPoint） | 整片是一个连续的运动叙事：选 1-2 个 hero element 跨 scene 持续存在，每段是 hero 的状态变化（位置/大小/形态），scene 之间 morph 不切（详见 references/voiceover-pipeline.md 「铁律」章节） |
技术红线（必读 references/react-setup.md）
React+Babel项目必须用pinned版本（见react-setup.md）。三条不可违反：
- never 写
const styles = {...}——多组件时命名冲突会炸。必须给唯一名字：const terminalStyles = {...} - scope不共享：多个
<script type="text/babel">之间组件不通，必须用Object.assign(window, {...})导出 - never 用
scrollIntoView——会搞坏容器滚动，用其他DOM scroll方法 - 手写 Stage / Sprite（不用
assets/animations.jsx）必须实现两件事：(a) tick 第一帧同步设window.__ready = true(b) 检测window.__recording === true时强制 loop=false——否则录视频必出问题
固定尺寸内容（幻灯片/视频）必须自己实现JS缩放，用auto-scale + letterboxing。
幻灯片架构选型（必先决定）：
- 🔴 默认且强烈推荐：多文件 + 概览墙（几乎所有 PPT——培训/路演/科普/课件/汇报）→ 每页独立 HTML +
assets/deck_index.html拼接器。这是 PPT 的默认交付形态：自带两种自适应 3D 概览（网格 iframe / 无限画廊图片，按秒数 60/40 随机）+ 任意页数自适应（少页倾斜居中、多页舒适大卡滚动）+ 统一页码。直接用，别重写概览（倾斜/点击命中/裁切三个坑已内建解决，见 slide-decks.md）。 - 单文件（仅 ≤5 页极简 pitch、且明确不需要概览墙、或需跨页共享 JS 状态）→
assets/deck_stage.js。 - 🛑 不要默认选单文件而绕过概览墙——北大 13 页 deck 实测踩坑：选了单文件 = 丢了概览墙，违背 PPT 默认交付形态。选单文件前先确认「这真的是 ≤5 页、且不需要概览墙」。
先读 references/slide-decks.md 的「🛑 先定架构」一节，错了会反复踩 CSS 特异性/作用域的坑。
Starter Components（assets/下）
造好的起手组件，直接copy进项目使用：
| 文件 | 何时用 | 提供 |
|---|---|---|
deck_index.html |
幻灯片的默认基础产物 | 直接复制为 index.html、编辑 MANIFEST 即用，不要重写概览逻辑（三个坑已内建解决）。自带两种自适应概览（网格 iframe 60% / 画廊 40%，画廊需 thumb 字段 + 先跑 scripts/gen_deck_thumbs.mjs）+ 键盘翻页 + scale + 计数器 + 打印合并。要改先读 references/slide-decks.md 三条硬约束 |
scripts/gen_deck_thumbs.mjs |
给无限画廊概览生成缩略图（网格 iframe 模式不需要） | playwright 截每页 + sharp 降采样 1600px JPEG：npm i playwright sharp && node gen_deck_thumbs.mjs --slides slides --out thumbs，再给 MANIFEST 每项加 thumb。分辨率别 <1000px 否则 hover 发虚 |
deck_stage.js |
做幻灯片（单文件架构，≤10页） | web component：auto-scale + 键盘导航 + slide counter + localStorage + speaker notes ⚠️ script 必须放在 </deck-stage> 之后，section 的 display: flex 必须写到 .active 上，详见 references/slide-decks.md 的两个硬约束 |
scripts/export_deck_pdf.mjs |
HTML→PDF 导出（多文件架构） · 每页独立 HTML 文件，playwright 逐个 page.pdf() → pdf-lib 合并。文字保留矢量可搜。依赖 playwright pdf-lib |
|
scripts/export_deck_stage_pdf.mjs |
HTML→PDF 导出（单文件 deck-stage 架构专用） · 2026-04-20 新增。处理 shadow DOM slot 导致的「只出 1 页」、absolute 子元素溢出等坑。详见 references/slide-decks.md 末节。依赖 playwright |
|
scripts/export_deck_pptx.mjs |
HTML→可编辑 PPTX（路线 A：HTML 还没写时用） · 调 html2pptx.js 导出原生可编辑文本框。HTML 必须符合 4 条硬约束（见 references/editable-pptx.md）。已经写好的视觉稿别硬跑它，改走下面一行。依赖 playwright pptxgenjs sharp |
|
scripts/pptx_from_rendered.py |
HTML→可编辑 PPTX（路线 B：HTML 已写好、或要继承甲方模板） · 读浏览器渲染后的 getBoundingClientRect，视觉驱动的 HTML（flex/居中/裸文字/背景图/SVG）零改造直接转；能以甲方 .pptx 为基底继承母版与版式，让他们改母版对全部页面生效（pptxgenjs 做不到）。见 references/pptx-from-rendered-html.md。依赖 playwright python-pptx Pillow |
|
scripts/html2pptx.js |
HTML→PPTX 元素级翻译器 · 读 computedStyle 把 DOM 逐元素翻译成 PowerPoint 对象（text frame / shape / picture）。export_deck_pptx.mjs 内部调用。要求 HTML 严格满足 4 条硬约束 |
|
design_canvas.jsx |
并排展示≥2个静态variations | 带label的网格布局 |
animations.jsx |
任何动画HTML | Stage + Sprite + useTime + Easing + interpolate |
ios_frame.jsx |
iOS App mockup | iPhone bezel + 状态栏 + 圆角 |
android_frame.jsx |
Android App mockup | 设备bezel |
macos_window.jsx |
桌面App mockup | 窗口chrome + 红绿灯 |
browser_window.jsx |
网页在浏览器里的样子 | URL bar + tab bar |
cursor.jsx |
产品UI演示里的光标操作叙事 | macOS光标4形状 + CursorSprite弧线轨迹（Catmull-Rom+收敛手抖）+ ClickRipple双圈解耦 + hover联动 + GSAP/Stage双驱动，帧确定性 |
用法：读取对应 assets 文件内容 → inline 进你的 HTML <script> 标签 → slot 进你的设计。
References路由表
根据任务类型深入读对应references：
| 任务 | 读 |
|---|---|
| 开工前问问题、定方向 | references/workflow.md |
| App/iOS 原型完整守则（架构表/取图代码/AppPhone骨架/ios_frame用法） | references/app-prototype.md |
| 反AI slop、内容规范、scale | references/content-guidelines.md |
| 字体排印/字体配对/中文排印 | references/typography.md |
| React+Babel项目setup | references/react-setup.md |
| 做幻灯片 | references/slide-decks.md + assets/deck_index.html（默认多文件概览墙）+ scripts/gen_deck_thumbs.mjs（画廊缩略图）+ assets/deck_stage.js（仅 ≤5 页单文件） |
| 导出可编辑 PPTX · 路线 A（HTML 还没写，按 4 条硬约束写） | references/editable-pptx.md + scripts/html2pptx.js |
| 导出可编辑 PPTX · 路线 B（HTML 已写好的视觉稿、甲方要求用他们的模板、或 A 转不出来） | references/pptx-from-rendered-html.md + scripts/pptx_from_rendered.py |
| 验证 PPTX/渲染产物时「先验证验证工具」 | references/pptx-from-rendered-html.md 的「验证」节 + references/verification.md |
| 做动画/motion（先读 pitfalls） | references/animation-pitfalls.md + references/animations.md + assets/animations.jsx |
| ⭐ 动画分镜/画面构图（任何动画开工前；每一镜先是一张会动的封面：定格帧十一律+景别体系+能量骨架+轻量分镜卡） | references/storyboard-basics.md（launch-film 导演稿是它的重装版） |
| ⭐ 镜头语言/运镜（zoom/pan/orbit/parallax/转场；预算制+镜间语法+PageCam 相机数学+CSS zoom 栅格化） | references/camera-language.md（设计判断）+ gsap-recipes.md §9 Camera Rig（实现） |
| ⭐ 产品UI展示动画（画面主角是一个界面：截图vs重建决策树+UI展示八式+typing+光标+3D巡览） | references/ui-demo-animation.md + assets/cursor.jsx |
| HyperFrames 渲染后端（新动画默认；选型边界/合成契约/老demo迁移/check流程） | references/hyperframes-backend.md |
| 设计语言的 GSAP 实现配方（easing 映射/运动语言8条/五段叙事骨架/seek 安全规则） | references/gsap-recipes.md |
| 动画的正向设计语法（Anthropic 级叙事/运动/节奏/表达风格） | references/animation-best-practices.md（5 段叙事+Expo easing+运动语言 8 条+3 种场景配方） |
| 带解说的长动画 / 长概念视频（5-20 分钟带配音、解说驱动画面、TTS 实测时长生成 timeline） | references/voiceover-pipeline.md（铁律：连续运动叙事、禁 PowerPoint 切换）+ assets/narration_stage.jsx + scripts/cloud/tts-doubao.mjs（可选云TTS，自备key，见SECURITY.md）+ scripts/narrate-pipeline.mjs + scripts/{mix-voiceover,render-narration}.sh |
| 做Tweaks实时调参 | references/tweaks-system.md |
| 没有design context怎么办 | references/design-context.md（薄 fallback） 或 references/design-styles.md（厚 fallback：HTML 原生 60 种风格库，网页 20+PPT 20+信息图 20，按温度分级） |
| 需求模糊要推荐风格方向 | references/design-styles.md（60 种 HTML 原生风格库，含还原度/温度/开源字体）+ assets/showcases/INDEX.md（预制截图画廊） |
| 按输出类型查场景模板（封面/PPT/信息图） | references/scene-templates.md |
| 输出完后验证 | references/verification.md + scripts/verify.py |
| 设计评审/打分（设计完成后可选） | references/critique-guide.md（5 维度评分+常见问题清单） |
| 动画导出MP4/GIF/加BGM | references/video-export.md + scripts/render-video.js（默认25fps）/ scripts/render-video-seek.js（真60fps·确定性·无黑帧，走Stage时钟时用）+ scripts/convert-formats.sh + scripts/add-music.sh |
| 动画加音效SFX（苹果发布会级，37个预制） | references/sfx-library.md + assets/sfx/<category>/*.mp3 |
| 动画音频配置规则（SFX+BGM双轨制、黄金配比、ffmpeg模板、场景配方） | references/audio-design-rules.md |
| Apple画廊展示风格（3D倾斜+悬浮卡片+缓慢pan+焦点� |
Files (ok-skills)
-
assets
-
director-notes-samples
-
launch-film-30s-sample.md 78.3 KB
# v5 · "Markdown is the new typewriter." > Director's Notes for the **huashu-md-html v2.0** launch film > 30 seconds · 1920×1080 · 25 fps · no voiceover > Director: huashu-design (acting as Apple-tier launch film director) > Composer: TBD (target: Max Richter / Ólafur Arnalds / Jóhann Jóhannsson minimal-cinematic register) > Color base: ivory white #FAFAF6 · ink #1A1A1A · terracotta #C2410C > Type: Newsreader (display + body) · JetBrains Mono (interface) · Noto Serif SC (中文) --- ## 目录 - [Part I · Director's Statement](#part-i--directors-statement) - [Part II · Visual System](#part-ii--visual-system) - [Part III · Story Arc](#part-iii--story-arc) - [Part IV · Shot-by-Shot Storyboard](#part-iv--shot-by-shot-storyboard) - [Part V · Production Manifest](#part-v--production-manifest) --- # Part I · Director's Statement ## 1.1 这不是一支「功能介绍片」 绝大多数 SaaS 升级视频都犯同一个错——把镜头当成 PPT。打开 → 6 个功能滑过 → logo + slogan → 结束。每一秒都在「展示」，没有一秒在「讲」。观众离开时记住的不是产品，而是「又一个看着像 AI 做的页面」。 **这支片不要做这个**。 我们要讲一个故事。故事只有一行： > **「md 是源代码，万物是产物。」** 这不是 slogan，是世界观。Markdown 不是「一种轻量级文档格式」——它是写作的源头。一切下游的形式（html、docx、pdf、epub）都是从这同一个源头派生出的产物。huashu-md-html v2.0 把这条产物链从 4 条延长到 6 条——但延长的不是「功能列表」，是**源头的影响力半径**。 如果观众看完这支片只记住一件事，我希望那件事是：「原来 md 才是源代码」。功能列表能记多少都是 bonus。 ## 1.2 视觉语言的语境对话 每一部好的宣传片都在跟一组前作对话。我希望这支片对话的语境是： **Apple — "Designed by Apple in California" (2013)** 那支片子是我心目中科技公司宣传片的天花板。导演 Mark Romanek 做对了三件事： 1. **纯白底 + 衬线字体**——告诉观众这是一支「关于设计的设计」，不是 demo 2. **慢拍**——每一句话的字幕都比观众阅读速度慢半拍，强迫观众停留 3. **Jony Ive 的旁白几乎像耳语**——不是兜售，是分享 我们这支片**没有 voiceover**，所以前两个原则要被 typography 和 timing 强化到 200%。 **Apple Silicon Launch Films (M1 / M2 / M3, 2020-2024)** 这一系列短片教会我**typography 也能跳舞**。"M1" 三个字符可以从消失、到出现、到放大、到旋转、到爆炸成尘埃、再到重组——观众看着一个 logo 在 30 秒里成为一支舞剧的主角。 **这支片的 hero 不是产品 UI，是 `md.` 这两个字符 + 一个橙色句点**。它要在 30 秒里成为舞剧主角。 **Anthropic 品牌语言（2024-2026）** Anthropic 把「赤陶橙 + 衬线 + 几何抽象」做成了 AI 公司的反 slop 样板。它告诉行业：你可以是科技公司，但你也可以看起来像 Penguin Classics 出版的一本哲学小书。 我们继承这套色彩。但要做得**更克制**——Anthropic 偶尔用纯赤陶橙作大色块；我们的赤陶橙永远只作 accent（占总画面 < 8% 面积），剩下 92% 留给象牙白和墨黑。 **Penguin Classics（1947 起，Romek Marber 1961 grid 之后）** Penguin 教会我**typography 的勇敢**。一本书的封面可以是大字号衬线 + 一条黑横线 + 没有插图——读者反而会停下来。 第 25-29 秒的 slogan reveal 借这个语言：**ONE SOURCE.** 和 **SIX FORMS.** 不是「装饰文字」，它们就是画面本身。 **Pentagram (Paula Scher / Michael Bierut)** Pentagram 的招牌是**信息建筑**——文字和文字之间的距离、文字和边界的距离、文字层级之间的字号比，都不是「凭直觉」，是数学。 我们的网格系统（Part II.3）来自这一传统。 **Kenya Hara《白》(2008)** Hara 写过：「白不是颜色，是一种感受性。」（白は色彩ではなく、感受性なのだ） 这支片的真正主角不是 `md.`，是包围它的**那片象牙白**。每一个 shot 都要留出至少 60% 的负空间。负空间不是「还没填满」，是内容本身。 **Massimo Vignelli — Modernism in design** Vignelli 的 8 字格言：「If you can design one thing, you can design everything.」（能设计好一件东西，你就能设计好一切） 我们的设计系统不允许「这一镜临时加一种字体」「这一镜临时加一个圆角值」。所有 12 个 shots 共享同一套 5 个色值、3 种字体、4 个 easing curves。 ## 1.3 观众画像 三类观众，按重要性排： **主受众 A · 已使用 v1 的 huashu-md-html 老用户（约占 60% 流量）** 他们打开片子是为了知道「升级了啥」。我们对他们的承诺：30 秒之内，你必须明确知道—— - 新增能力 5：md → 出版级 PDF - 新增能力 6：md → 标准 EPUB - 这两个能力的视觉品质比想象中更高（不是「我用 wkhtmltopdf 也能搞」级别） → Shot 08 和 Shot 09 各 3 秒，必须有「★ NEW」标签 + destination card 上必须能看到「印厂裁切标记」「Apple Books frame」这类**看得见的专业级细节**——让老用户秒懂「这不是凑数功能，是正经做了的」。 **次受众 B · 听说过 huashu-md-html 但没用的 AI Native 创作者（约 25%）** 他们关心的是「这个 skill 跟我有什么关系」。我们对他们的承诺：30 秒之内，你必须意识到—— - 你写文章 / 做调研 / 做白皮书时，**md 应该是你的 source of truth** - 6 种下游格式，一次命令解决 → Shot 04（any → md）要让他们看到 PDF/DOCX/PPTX/XLSX/HTML 一起被 md 吸收——这是「源头思维」的视觉具象化。 **外受众 C · 完全不熟悉的设计师 / 编辑 / 出版人（约 15%）** 他们看到的是一支「漂亮的科技短片」，不一定 follow up。我们对他们的承诺：30 秒之内，你必须留下印象—— - 这家做的东西**有出版社品位** - 跟你过去看到的 AI 工具不一样 → 整支片的反 AI slop 自检（Part II.7）就是为他们做的。任何紫渐变、emoji 图标、SVG 手画人物——一律不出现。 ## 1.4 节奏哲学 苹果宣传片的节奏不是匀速的。它是**慢拍 — 加速 — 顶峰 — 缓收**的曲线（详见 Part III 情绪曲线图）。 具体到这支片： - **0-3s 慢拍**：观众进入。typography 一个字符一个字符地呼吸。 - **3-6s 第一加速**：md 字符诞生，6 个文件 cards 鱼贯飞入。 - **6-22s 第二加速段**：6 个 capability 一气呵成，每个 3 秒不松手。 - **22-26s 顶峰**：slogan 双行 reveal，所有 chrome 同步律动。 - **26-30s 缓收**：capability map 慢慢淡入，最后一秒留给品牌印章 + 极弱的 piano 残响。 **关键决策**：第 22 秒是这支片的高潮点（不是第 29 秒）。29 秒是 resolution，22 秒是 climax。这两个不要混。 ## 1.5 这支片**不**做的事（反 AI slop 自检） 按重要性排： | 不做 | 原因 | |------|------| | 不用紫渐变 | 训练语料里「科技感」的万能公式，2026 年看是 cyber slop | | 不用 emoji 作图标 | 「不专业就用 emoji 凑」的病 | | 不画 SVG 人物 / 手 / 抽象人形 | AI 画的 SVG 人物永远五官错位、比例诡异 | | 不用 Inter/Roboto/Arial 作 display | 太常见，撞 system fonts | | 不用赛博霓虹 / 深蓝底 #0D1117 | GitHub dark mode 美学的烂大街复制 | | 不堆 effects（blur/glow/particle）| 一个 effect 出现两次就是装饰，三次就是 slop | | 不用 Lorem ipsum | 每一段假文都用真正能读的内容（含「md is the source. Anything else is product.」这种 hook） | | 不用 stock photo | 整支片不出现任何真实照片（it's about typography, not lifestyle） | | 不画进度条 + 时间码 + 版权署名条 | 这些是 player chrome，不是 content chrome——会和外部播放器撞 | | 不让 md 字符在每个 scene 都长得一样 | 它要在 12 镜里有 12 种状态，但保持同一个核心字形 | ## 1.6 一句话定位 > **"Markdown is the new typewriter."** > > A 30-second film about source-of-truth thinking, made for designers who write and writers who design. --- # Part II · Visual System ## 2.1 完整色板 不是 3 色，是 10 色。每一色都有**功能定义**（不是「好看就用」）。 ``` 名称 HEX 作用 占画面比例上限 ───────────────────────────────────────────────────────────────────── Ivory paper #FAFAF6 主底色（象牙白，一抹温度） 60-70% Mist #F2EDE4 次级背景层（card 阴影下的微暗） < 15% Mica #E6E1D6 细线 / 分隔符 / 卡片边框 < 5% Smoke #6B6B6B 次级文本 / metadata < 5% Cinder #3D3530 次级深色（深褐黑，不是纯黑） < 10% Ink #1A1A1A 主黑 / 主文本 20-25% Charred #2A2620 极深褐黑（封面卡专用） < 5% Terracotta #C2410C 主 accent（Anthropic 调） 5-8% Terra Hot #E55D21 高光 variant（仅 NEW 标签亮起一瞬）< 1% Terra Deep #8B2D08 阴影 variant（赤陶橙投影） < 1% ``` **铁律**： - 任何一镜不出现以上 10 色之外的颜色。**没有「这一镜临时加点冷灰」**。 - 赤陶橙系（Terracotta + variants）三色合计占画面 < 10%，否则视觉过载。 - 任何文本只能用 4 色之一：Ink / Cinder / Smoke / Terracotta。 ## 2.2 字体系统 ``` 字号层级 字体 weight 用途 字距 (em) ──────────────────────────────────────────────────────────────────────────────────── Display XXL Newsreader 700 slogan 顶字（200px） -0.035 Display XL Newsreader 700 capability number（48px） -0.020 Display L Newsreader 600 hero md 字符（300-480px） -0.040 Display M Newsreader 600 chapter title (32-44px) -0.015 Body L Newsreader 400 essay 正文 (18-22px) 0 Body M (zh) Noto Serif SC 500 中文 sub-line (20-26px) +0.04 Italic Newsreader italic 400 引语、副标 +0.01 Mono S JetBrains Mono 500 标签 / capability counter +0.18 Mono XS JetBrains Mono 700 NEW / version chip (11-14px) +0.22 Caret (block 3px wide) — typing cursor — ``` **字体加载策略**： - Google Fonts 预连接 `<link rel="preconnect" href="https://fonts.gstatic.com" crossorigin>` - 单一 `<link>` 请求合并所有 weights，减少 round-trip - 录制 MP4 前必须 `document.fonts.ready` 完成才开始计时（Stage 已实现） ## 2.3 网格系统 **主画布**：1920 × 1080 **外边距（safe zone）**：80px 上下左右 **主内容区**：1760 × 920 **12-column grid**：column-width = 132px，gutter = 16px **Baseline grid**：8px 基础律。所有 vertical position 必须是 8 的倍数（除非有特殊视觉理由）。 **黄金分割锚点**： - 上 1/3 线：y = 360 - 下 1/3 线：y = 720 - 中线：y = 540（hero md 默认 anchor） - 黄金分割上：y = 412 - 黄金分割下：y = 668 **关键安全区**： - 顶部 60px 内：chrome 元素区（capability counter, version chip） - 底部 60px 内：watermark / metadata 区 - 中央 800×600 区域：主内容禁区（每一镜的 hero 元素必须落在此区域内） ## 2.4 动画系统 **Easing 库**（共 4 条，禁用其他）： ``` 名称 曲线公式 用途 ────────────────────────────────────────────────────────────────── expoOut 1 - 2^(-10t) 默认 ease（90% 的入场用这个） overshoot cubic-bezier(0.34, 1.56, 0.64, 1) NEW 标签弹出 / 按钮浮现 linear t 底色 fade / paper texture 移动 expoIn 2^(10(t-1)) 退场 ease（10% 的出场用这个） ``` **Duration 字典**： ``` 事件类型 持续时间 备注 ──────────────────────────────────────────────────────── 字符 stagger 30-50ms 打字效果 / slogan 字符依次出现 小元素入场 300ms file card / pill / chip 中元素入场 500ms destination card / capability number hero 元素入场 700-900ms md 字符 morph slogan 字符入场 800ms "ONE SOURCE." 整体 scene 之间过渡 300ms 重叠 cross-dissolve + scale 退场 200-300ms 出场永远快于入场 ``` **Stagger 法则**： - 多元素同时进场时，相邻元素 delay 30-80ms（不是 0，也不超过 100ms） - 6 个 pill 进场：累计 stagger 250ms（每个 50ms） - slogan 字符进场：累计 stagger 280ms（每个 ~30ms × 10 字符） **Scene 之间过渡**： - 永远是 **cross-dissolve + soft scale**（不切换硬切） - 上一镜在末尾 300ms 内：opacity 1 → 0, scale 1 → 0.96 - 下一镜在开头 300ms 内：opacity 0 → 1, scale 1.04 → 1 - 两镜重叠 300ms（在时间轴上 Sprite end 比下一镜 start 大 0.3s） ## 2.5 Chrome 元素（贯穿全片） 这些是 **持续在画面里的小东西**，提供「这是一支完整的片子」的感觉。 **Chrome A · top-left · capability counter（00-22s）** ``` ┌─────────────┐ │ ● CAP·01 │ pulse dot (terracotta) + label │ ●●●●○○○○○ │ 6-dot progress (filled = current) └─────────────┘ ``` - 字体：JetBrains Mono 12px，letter-spacing 0.24em - 颜色：Ink for label, Terracotta for current dot, Mica for upcoming dots - 动画：每次切 scene 时，下一个 dot 从空心 → 实心（500ms expoOut） **Chrome B · top-right · version chip（02-30s）** ``` ╔═════════════════════════╗ ║ ● HUASHU-MD-HTML · v2.0 ║ ╚═════════════════════════╝ ``` - 字体：JetBrains Mono 13px Bold，letter-spacing 0.22em - 颜色：Terracotta dot + Ink label - 入场：02s 时整体 fade-in 600ms - pulse dot：每 4 秒做一次极弱呼吸（opacity 1 → 0.6 → 1, 1500ms ease-in-out） **Chrome C · bottom-center · timeline ticker（07-22s）** ``` any→md ━━━━●━━━━━━━━━━━━ md→html ─ html→md ─ md→docx ─ md→pdf ─ md→epub ``` - 字体：JetBrains Mono 11px，letter-spacing 0.18em - 当前 capability 用 Terracotta + bold，其他用 Smoke - 一条横线连接 6 个名字，进度点（●）随时间从左滑到右 - 入场：07s 时整条 fade-in 500ms **Chrome D · bottom-right · watermark（持续）** ``` CREATED BY HUASHU-DESIGN ``` - 字体：JetBrains Mono 10px，letter-spacing 0.24em - 颜色：rgba(26,26,26,0.32) - 完全静态，不动 **Chrome E · 极淡 paper texture（持续）** - SVG 噪点 + 极慢的 0.3% scale 呼吸 - opacity ≤ 0.04 - 录像时几乎看不见，但能让画面有「呼吸」 ## 2.6 音频系统 ### BGM 走向（30 秒分段曲线） ``` 强度 │ ╱╲ 1│ ╱╱ ╲╲ │ ╱╱ ╲╲ │ ╱╱ ╲ │ ╱╱ ╲ │ ╱╱ ╲ │ ╱╱ ╲ │ ╱╱ ╲ 0└──┴──┴──┴──┴──┴──┴──┴──┴──┴──┴──┴──┴──┴──┴──┴──┴ 0 2 4 6 8 10 12 14 16 18 20 22 24 26 28 30s │ │ │ │ │ │ 入场│ 弦乐进 │ 节奏律动加入 │ 顶峰 │ decay piano swell ``` **层级（每层 30 秒持续，强度变化由 envelope 控制）**： - **L0 · Room tone**（00-30s）：极弱 background noise，给画面「不死寂」的呼吸感 - **L1 · Piano single note**（00-08s）：单一钢琴音持续敲击，每 1.2 秒一次，慢慢累积 - **L2 · Piano arpeggio**（03-22s）：钢琴琶音入场，给「拾起节奏」的感觉 - **L3 · Cello drone**（08-22s）：低频弦乐铺底，给「重量」 - **L4 · Pulse**（15-22s）：极弱 sub-kick，4/4 节奏（不是 dance beat，是 cinematic pulse） - **L5 · String swell**（22-26s）：整组弦乐 swell up 到 climax - **L6 · Decay + reverb tail**（26-30s）：所有层级 decay，留下钢琴 + reverb **风格目标**：Max Richter 的 *On the Nature of Daylight* + Ólafur Arnalds 的 *Re:member* + Jóhann Jóhannsson 的 *Orphée* ### SFX 字典 ``` Cue 时间 类型 音量 ──────────────────────────────────────────────────────────────────── keyboard click 00.5-02.0 keypress × 12 -18dB（每次 30ms） cursor blink 02.0-02.8 subtle tick -28dB md morph swell 02.8-03.2 soft whoosh + bloom -16dB file card whoosh × 6 05.5-08.0 short whoosh -20dB（每次 200ms） absorb / ink drop 08.0-08.4 "absorb" splash -16dB paper rustle 08.5-09.0 paper turn -22dB chime: capability 02 → 09.0 single chime tone -18dB chime: capability 03 → 12.0 single chime tone -18dB chime: capability 04 → 15.0 single chime tone -18dB chime: NEW (05) 18.0 double chime + glow -14dB chime: NEW (06) 21.0 double chime + glow -14dB build sweep 22.0-22.6 ascending sweep -10dB impact (slogan ONE) 22.6 deep impact -8dB impact (slogan SIX) 23.4 deep impact -8dB pen flourish 24.0-24.4 pen on paper -22dB final stamp / sign-off 29.0-29.5 ink stamp -14dB ``` **SFX 频段隔离**（防止互相打架）： - BGM 占低频 (40Hz-2kHz) - SFX whooshes / chimes 占中高频 (2kHz-8kHz) - SFX impacts 占低频 sub (40Hz-120Hz) — 与 BGM cello 重叠但 BGM 同时 duck -3dB ## 2.7 反 AI slop 自检表（per-shot） 每一镜在执行前必须过这个 checklist： ``` □ 没有紫色（任何饱和度） □ 没有圆角卡片 + 左 border accent 的组合（除了 destination card 的诚实 mica border） □ 没有 emoji 作为图标 □ 没有 SVG 画的人物 / 抽象人形 □ 没有未在 Part II.1 色板里的颜色 □ 没有 Inter / Roboto / Arial 作为 display □ 字距、行高、字号都来自 Part II.2 字体系统（没有「凭手感」加的值） □ vertical position 是 8 的倍数（除了刻意的视觉理由） □ 赤陶橙在本镜占画面 < 10% □ 这一镜有至少一处「pause 暂停时值得截图」的细节（120% 签名） □ 上一镜到这一镜的过渡是 cross-dissolve + scale，不是硬切 □ 本镜结束时为下一镜做了视觉「让位」（不是「全画面填满到最后」） ``` --- # Part III · Story Arc ## 3.1 三幕结构 **ACT I · SET-UP (00.0 — 06.0s)** 观众进入画面。问题被提出：什么是 source of truth？ - SHOT 01 (0.0-1.5s) · BLANK PAGE - SHOT 02 (1.5-3.0s) · THE CURSOR - SHOT 03 (3.0-5.0s) · THE TRANSFORMATION - SHOT 04 (5.0-6.0s) · 进入 gathering（与 ACT II 重叠） **ACT II · ESCALATION (06.0 — 22.0s)** 答案展开：md 是源头。它向外辐射 6 条产物链。 - SHOT 04 (5.0-8.5s) · GATHERING（any → md） - SHOT 05 (8.5-11.5s) · FIRST FLOWER（md → html） - SHOT 06 (11.5-14.5s) · REVERSE FLOW（html → md） - SHOT 07 (14.5-17.5s) · PUBLISHER GRADE（md → docx） - SHOT 08 (17.5-20.5s) · ★ NEW · PRINT（md → pdf） - SHOT 09 (20.5-22.5s) · ★ NEW · EBOOK（md → epub，与 ACT III 重叠 0.5s） **ACT III · PAYOFF (22.5 — 30.0s)** 主题升华。slogan 出现。品牌印章。 - SHOT 10 (22.5-24.0s) · THE CONVERGENCE - SHOT 11 (24.0-26.5s) · ONE SOURCE. - SHOT 12 (26.5-29.0s) · SIX FORMS. - SHOT 13 (29.0-30.0s) · SIGN-OFF ## 3.2 情绪曲线 ``` 情绪强度 │ ╔═══╗ │ ╔══╝ ╚══╗ │ ╔═════╝ ╚══╗ │ ╔═══╝ ╚══╗ │ ╔══╝ ╚══╗ │ ╔═══╝ ╚════════╗ │ ╔═════╝ ╚══╗ │ ╔═════╝ ╚══ │ ╔════╝ │══╝ 0──┼──┼──┼──┼──┼──┼──┼──┼──┼──┼──┼──┼──┼──┼──┼──┼──┼──┼──┼──┼──┼──┼──┼──┼──┼──┼──┼──┼──┼──┼──> 0 2 4 6 8 10 12 14 16 18 20 22 24 26 28 30s │ │ │ │ │ │ │ │ │ blank cursor morph gather cap 02-04 cap 05/06 ★ slogan slogan sign-off ONE SIX ──────► PEAK 24.5s ``` **关键 emotional beats**： - **02.0s**：第一个 keyboard click → 观众进入 - **03.0s**：md 字符诞生 → 第一次「awe」 - **08.0s**：6 个文件 cards 收拢进 md → 「啊，原来 md 是源」第一次 click - **18.0s**：第一个 NEW 标签出现 → 老用户「噢」 - **22.5s**：所有 chrome 收拢，准备进入 Act III → tension build-up peak - **24.5s**：SIX FORMS. 落地 → emotional climax - **30.0s**：md 印章静静停留 → resolution --- # Part IV · Shot-by-Shot Storyboard 每一镜的格式： ``` SHOT NN · NAME [TIMECODE] | FUNCTION [VISUAL] 画面构图 [TYPE] 排版精确 spec [ANIM] 每元素 in/out/easing/delay [AUDIO] music beat + SFX cue [CHROME] 四角元素状态 [ANTI-SLOP] 通过的自检项 [WHY] 承接 + 推进 ``` --- ## SHOT 01 · "BLANK PAGE" **[TIMECODE]** 00.00 — 01.50s (1.5s) `|` **FUNCTION** 开场。引观众进入。给「空」一个时间。 **[VISUAL]** 整个 1920×1080 是 Ivory paper #FAFAF6。**画面里什么都没有**。 唯一的存在：一层极淡的 paper texture（SVG 噪点 + 0.3% scale 极慢呼吸），几乎看不见，但赋予画面「这是一张真的纸」的潜意识。 构图：完全空。这是 Kenya Hara 意义上的「白」——不是「还没画」，是「内容本身」。 **[TYPE]** 无文本。 **[ANIM]** - 0.00s · paper texture opacity 从 0 → 0.04（500ms linear） - 0.50-1.50s · 整个画面 hold，无动作。让观众的眼睛适应这个白。 - 1.40-1.50s · 画面中央偏左（x=860, y=540）开始浮现一个 cursor 的位置（透明，下一镜才显形） **[AUDIO]** - BGM: room tone 进入 (300ms fade-in to -38dB) - SFX: 无 **[CHROME]** 全部隐藏。Chrome A/B/C/D/E 都还没显形。 **[ANTI-SLOP]** - ✅ 没有 logo、没有「Loading...」、没有任何品牌前置 - ✅ 没有渐变、没有 effects - ✅ 这一镜的「pause-and-look」signature：画面有质感（paper texture）但绝不抢戏 **[WHY]** 苹果 "Designed by Apple in California" 也是这样开场——给空白一个时间。它告诉观众「这部片需要你慢下来」。如果开场就堆 logo 和 chrome，观众的注意力被分散，后面 30 秒都收不回。 这 1.5 秒是这支片最重要的 1.5 秒之一。 --- ## SHOT 02 · "THE CURSOR" **[TIMECODE]** 01.50 — 03.00s (1.5s) `|` **FUNCTION** typewriter 诞生。第一个内容。 **[VISUAL]** 画面中央偏左（x=860, y=540），一个垂直的黑色 block（3px × 56px, Ink #1A1A1A）开始闪烁。这是 cursor。 闪烁两次（0.7s 一周期 × 2）后，cursor 后面开始逐字出现 `# markdown.md`，字体 JetBrains Mono 56px，颜色 Ink #1A1A1A，letter-spacing -0.01em。 每打一个字符，键盘 click 音响一次。打完最后一个字符（13 个字符总计），cursor 在 `.md` 之后继续闪烁 1 次。 **[TYPE]** - Text: `# markdown.md` - Font: JetBrains Mono 500 weight - Size: 56px - Color: Ink #1A1A1A - Letter-spacing: -0.01em - Position: horizontal center, y = 540（baseline，文字 vertical center 略低于此） **[ANIM]** - 01.50s · cursor block opacity 0 → 1 (200ms) - 01.50-01.85s · cursor blink 第一次（off 200ms / on 200ms） - 01.85-02.20s · cursor blink 第二次 - 02.20-02.85s · 13 个字符 staggered 出现，每个间隔 50ms（共 650ms 完成），每个字符各自 fade + 1px slide-down (180ms expoOut) - 02.85-03.00s · cursor 在末尾再 blink 一次（最后一次，标志输入完成） **[AUDIO]** - BGM: piano 第一音敲击 at 01.50s (-22dB) - SFX: keyboard click × 13 (每字一次, -18dB, 30ms each) - SFX: 最后一次 cursor blink 后 200ms 静默（给下一镜 morph 让位） **[CHROME]** 仍隐藏。 **[ANTI-SLOP]** - ✅ cursor 不是 sci-fi 闪烁（不是 0.1s 极快闪烁），是 macOS terminal cursor 节奏的真实模拟 - ✅ typing 不是「字符一次性出现」，是真的有节奏的打字 - ✅ font 是 JetBrains Mono，不是 Courier 或 Menlo 这种系统默认 mono - ✅ pause-and-look signature：cursor 的 3px 宽度（不是 2px 或 4px）—— 一个非常精确的细节，懂行的人会注意到这是「真实 terminal 设计的」 **[WHY]** 这一镜是 setup 的核心：**markdown 不是一个名词，它是一个动作**——它是「敲击键盘把字符变成结构」这件事本身。 cursor 是写作的最小单位。从一个 cursor 开始，是「源代码」的诞生。 下一镜的 morph 就建立在这个观众已经接受「我们在写 markdown」的前提上。 --- ## SHOT 03 · "THE TRANSFORMATION" **[TIMECODE]** 03.00 — 05.00s (2.0s) `|` **FUNCTION** 揭示 hero。`# markdown.md` morph 成 hero `md.` **[VISUAL]** 第 03.00 秒：`# markdown.md`（56px mono）开始向中央收拢、放大、变形。 **morph 过程**（详细解构）： - 03.00-03.30s（300ms）：`# markdown.md` 的 `#` 和 `arkdown` 部分淡出（opacity 1 → 0），同时 `m` 和 `d.md` 的 `md` 部分留下。 - 03.30-04.10s（800ms）：留下的 `md` 从 mono 字体 morph 成 Newsreader serif，从 56px 放大到 480px，从 Ink 变成 Ink（不变色），位置不变（仍在画面中央）。 - 04.10-04.80s（700ms）：在 `md` 字符的右下角，一个 Terracotta 句点 `.` 浮现（fade-in + scale 0.6 → 1 + overshoot easing）。 - 04.80-05.00s（200ms）：句点正式 settle，hero 完整。下方 30px 出现一条 320px 宽的赤陶橙细线（terracotta accent rule, 2px thick），从中心向两端展开。 **结束帧**：`md.`（Newsreader 600 weight, 480px, Ink with Terracotta dot）+ 下方一条赤陶橙细线。画面其他全空。 **[TYPE]** - Text: `md.`（`md` Ink, `.` Terracotta） - Font: Newsreader 600 weight - Size: 480px (display L) - Letter-spacing: -0.04em - Color: `m`+`d` Ink #1A1A1A, `.` Terracotta #C2410C - 在 hero 中线（y = 540）水平垂直居中 - accent rule 下方 30px，width 320px（从 0 长成） **[ANIM]** - 03.00-03.30s · `#` `arkdown` `md`（中段）淡出 (opacity 1 → 0, expoOut) - 03.30-04.10s · `md` morph：fontFamily 切换、fontSize 从 56 → 480、weight 从 500 → 600（800ms expoOut，注意 morph 不是 abrupt 切换，而是 ghost 残影叠加 + scale up + opacity 切换） - 04.10-04.80s · `.` 入场 (700ms overshoot, scale 0.6 → 1) - 04.80-05.00s · accent rule width 0 → 320px (300ms expoOut) **[AUDIO]** - BGM: piano 第二音 at 03.00s (-20dB), 第三音 at 04.20s (-18dB) — piano 累积 - SFX: 03.00-03.20s soft whoosh（morph 开始时, -16dB） - SFX: 04.10s subtle bloom（句点出现的瞬间, -20dB） - SFX: 04.80s short paper rustle（accent rule 展开, -22dB） **[CHROME]** - 04.50s · Chrome B（version chip top-right）开始浮现 (fade-in 600ms) - 形态：`● HUASHU-MD-HTML · v2.0` - terracotta dot, mono text, Ink color - 进入位置：top: 78px, right: 80px - 仍隐藏：Chrome A, C, E（visible only ≥ 06s） **[ANTI-SLOP]** - ✅ morph 不是「淡出 + 淡入」的廉价 transition，是真正的字符变形（含 ghost 残影叠加） - ✅ 句点是 hero 的「签名细节」（120% 做到的那个）：Terracotta 句点小如指甲，但是这部片的视觉锚点，**所有后面的镜头里这个句点都保留为 hero 标识** - ✅ accent rule 不是装饰，是 hero 的 base line——它在 Shot 11 的 slogan 那里会再次出现，建立首尾呼应 - ✅ pause-and-look signature：480px Newsreader 'md' 的字距 -0.04em 让 m 和 d 之间几乎贴合但不接触，这是 Newsreader 这个字体在大字号时的招牌质感 **[WHY]** 这是 hero shot。后面 25 秒整部片的「主角」（`md.`）在此诞生。 morph 的设计哲学：**从 mono 到 serif，是从「我在打字」到「我在写作」的隐喻**。mono 是 typewriter，serif 是 publishing。md 同时是两者——它在键盘上敲，但它是 publishing 的源代码。 下一镜进入 ACT II，hero 已经站住了——它会被推到画面上方，让出空间给「物质化的产物」。 --- ## SHOT 04 · "GATHERING" (any → md) **[TIMECODE]** 05.00 — 08.50s (3.5s) `|` **FUNCTION** CAPABILITY 01 揭示。万物 → md。建立「md 是源」的世界观。 **[VISUAL]** 05.00s：hero `md.` 从画面中央（y=540）向上滑到 y=280（即 1/4 高度位置），同时缩小到 220px。 随后画面下半部（y=520 ~ y=900 区域）出现 6 张文件 cards，按顺序从画面外（下方 y=1140）飞入，沿一条隐形的抛物线轨迹向 md hero 收拢。 6 张 cards 的设计（**每张都是真实文件类型的迷你 demo，不是 fake bar lines**）： ``` .pdf │ 双栏布局 + 页眉 "doc.pdf" + 页码 "— 12 —" + 几行真实排版的小文字 .docx │ heading "On Markdown" + 副标 italic + 6 行段落 ascii .pptx │ 标题 "MD AS SOURCE" + 一个简化的 bar chart 占位 .xlsx │ 6×4 的 spreadsheet 网格 + 一些数字 .epub │ Apple Books 风的页面 + 章节标题 "Chapter 01" .html │ 一个浏览器 chrome（三个圆点 + URL bar "example.com"）+ 标题 + 段落 ``` 每张 card 尺寸 130×180px，白底 + Mica 边框 + 24°右上角 fold。 **飞行轨迹**：从下方 y=1140 出发，沿抛物线向 md hero 的「.」位置（约 x=960+50, y=280+90）汇聚。中段（在画面中部时）6 张 cards 排成扇形，每相邻两张间隔 220px。最终所有 6 张被 md 「吸收」（scale 1 → 0.5 + opacity 1 → 0，同时 position 收拢到一个点）。 吸收时机：从 05.60s 开始，每隔 0.18s 一张 launch。每张飞行 1.1s 后被吸收。最后一张 absorb 完成时间约 07.60s。 吸收完成后（07.60-08.20s），下方 60px 处出现 tagline：「万物 → md」（中文衬线，36px，Ink，italic） 08.20-08.50s · 整体 hold，准备进入 Shot 05。 **[TYPE]** - hero `md.`：缩小到 220px（同 SHOT 03 字体规格） - 6 cards 内部排版：JetBrains Mono 12-14px for labels, Newsreader 12-16px for content - tagline「万物 → md」：Noto Serif SC 36px italic + 中间的 → 是 Newsreader italic + Terracotta - 顶部 Chrome A 文字：JetBrains Mono 12px **[ANIM]** - 05.00-05.30s · hero md 缩放 + 上移（300ms expoOut） - 05.30s · Chrome A capability counter 入场（CAPABILITY · 01 显示，第一个 dot 实心） - 05.60-07.60s · 6 张 cards 依次发射（每张 launch delay = 5.60 + i × 0.18s, 飞行 1.1s，absorb at launch+1.1） - 07.60-08.20s · tagline「万物 → md」入场（fade-in 400ms + slight y slide 12px → 0） - 08.20-08.50s · hold **[AUDIO]** - BGM: piano arpeggio L2 进入 at 05.00s（-26dB → -20dB 渐入） - SFX: file card whoosh × 6（每张 launch 时一次，每次 200ms，-20dB） - SFX: absorb / ink drop（最后一张 card 被吸收时，-16dB） - SFX: paper rustle（tagline 入场时，-22dB） **[CHROME]** - A（top-left capability counter）: ON, 显示 `CAPABILITY · 01`, 第一个 dot 实心 - B（version chip）: ON, 持续显示 - C（timeline ticker）: OFF (会在 SHOT 05 入场) - D（watermark）: ON, 永远 ON - E（paper texture）: ON **[ANTI-SLOP]** - ✅ 6 张 cards 不是 emoji 也不是图标，是**有内部内容的迷你 demo**——每张都 readable - ✅ 飞行轨迹是抛物线（重力感），不是直线（电脑感） - ✅ 收拢时是「吸收」（scale + position 同时收）不是「叠加」 - ✅ 没有给 md 字符任何 glow 或 particle effects（不需要解释「md 在吸收」，观众自己看得懂） - ✅ pause-and-look signature：每一张 card 在飞行中段 pause 看，都能读出来「这是个 PDF / 这是个 DOCX」——这就是 120% 做到的细节 - ✅ tagline 用「→」而不是「to」或「至」，是 markdown 自己的字符 **[WHY]** 这是 ACT II 的开门镜。如果观众看完这 3.5 秒没意识到「噢，md 是源」，后面的镜头就白做了。 3.5 秒里有 3 个 micro-narrative beats： 1. hero 让位（md 上移）—— 暗示「我让位给我的产物们」 2. 6 个产物现身 —— 揭示「我能收的东西」 3. 全部归位回 md —— 「但他们最终都是 md」 下一镜进入 md → html 的正向流动——观众已经接受「md 是源」，现在 ready to see「md 怎么变」。 --- ## SHOT 05 · "FIRST FLOWER · HTML" (md → html) **[TIMECODE]** 08.50 — 11.50s (3.0s) `|` **FUNCTION** CAPABILITY 02。第一次正向输出。建立 ScenePipeline 模式（后续 5 镜共用此结构）。 **[VISUAL]** 08.50s：hero `md.` 从中心上方位置滑到画面左侧（x=480, y=540），尺寸保持 220px。 同时画面右侧 (x=1400, y=540) 出现一个 destination card：模拟「Tufte CSS 风的 essay html」。 destination card 设计（**真实可读的内容，不是 bar lines**）： ``` ┌─────────────────────────────────┐ │ │ │ On Markdown │ ← Newsreader 600, 32px, Ink │ AN ESSAY · 2026 │ ← Mono 11px, 0.18em, Smoke │ ▬▬▬ │ ← Terracotta rule 60×3px │ │ │ md is the source of truth. │ ← Newsreader 400, 18px, line-height 1.7 │ Anything else is product. │ │ We write once. Publish six │ │ ways. The river forks; the │ │ spring stays the same. │ │ │ │ ─ huashu, 2026.05.11 │ ← italic 14px, Smoke │ │ │ article.html · TUFTE THEME │ ← Mono 10px, 0.18em, Smoke (bottom) └─────────────────────────────────┘ 宽 480px × 高 560px 白底 + Mica border + 24° 角折 ``` md 字符与 destination card 之间用一条 terracotta 细线连接，从 md 的 dot 出发，向右生长 380px，箭头 head 触达 card 左边界。线上方 30px 处显示 label「md → html」（JetBrains Mono 14px Terracotta，letter-spacing 0.14em）。 09.80s 时：Chrome C（timeline ticker）首次入场，固定在 y=1000 处。 **[TYPE]** - 见 visual description 内嵌 - label「md → html」字号 14px， Mono Bold，Terracotta，letter-spacing 0.14em - destination card 顶部 chapter title 是 Newsreader 600, 32px, Ink - destination card 底部小印 mono 10px Smoke 0.18em **[ANIM]** - 08.50-08.80s · hero md 从 center-top 滑到 left-mid（300ms expoOut） - 08.80-09.10s · arrow line 从 md.dot 起点向右生长（300ms expoOut, 0 → 380px） - 09.10s · arrow head 浮现（200ms overshoot） - 09.20-09.40s · label「md → html」入场（fade-in + 8px y slide-down, 300ms expoOut） - 09.40-10.10s · destination card 整体入场（700ms expoOut, scale 0.85 → 1 + opacity 0 → 1） - 10.10-10.80s · destination card 内部 staggered 入场：title (400ms delay 0) → 副标 metadata (delay 200ms) → terracotta rule (delay 400ms) → 6 行正文 (each delay 60ms cascade) → 签名 (delay 1000ms) → bottom mono (delay 1100ms) - 10.80-11.50s · hold + 微观呼吸 (整体 scale 1 → 1.005 → 1, 600ms ease-in-out infinite, 但本镜只播放半个周期) **[AUDIO]** - BGM: cello drone L3 入场 at 09.00s (-30dB → -24dB) - SFX: chime: capability 02 at 09.00s (-18dB) - SFX: paper rustle（card 入场时, -22dB） - SFX: micro ticks（每行文字 staggered 入场时, -26dB each） **[CHROME]** - A: 推进到 `CAPABILITY · 02`, 第二个 dot 实心 - B: ON - **C: 首次入场** at 09.80s，`any→md ━━━━●━━━━━ md→html ─ html→md ─ md→docx ─ md→pdf ─ md→epub`，进度点 ● 位于第二格上方 - D: ON - E: ON **[ANTI-SLOP]** - ✅ destination card 的「On Markdown」essay 内容是真的可读的英文哲学小段，不是 Lorem ipsum - ✅ 「article.html · TUFTE THEME」这个小印是「pause 时能读出来的细节签名」 - ✅ 没用任何 glow 或 particle 来「强调」md → html 的转换——靠 typography 和构图自己讲清楚 - ✅ arrow line 不是 dashed 或 dotted（避免「网页教程」感），是 1.5px 实线 Terracotta - ✅ pause-and-look signature：destination card 顶部的「AN ESSAY · 2026」副标用了 Newsreader 的 small caps OpenType feature，0.18em 字距——是这一镜的 120% 细节 **[WHY]** 这是 ScenePipeline 模式的首次建立。后续 5 个 capability shots 都会按这个结构推进： 1. md 在左、destination 在右 2. arrow + label 在中间 3. destination card 内部 staggered 入场（每个 card 都有 6-8 个文字层级） 4. card 内容是真实可读的，不是 fake bar lines 观众看到第二次（SHOT 06）就会理解这个模式，看到第六次（SHOT 09）会有「啊，又来一次，但这次是 NEW」的感觉——这正是 ACT II 的节奏设计。 --- ## SHOT 06 · "REVERSE FLOW · MD" (html → md) **[TIMECODE]** 11.50 — 14.50s (3.0s) `|` **FUNCTION** CAPABILITY 03。反向归档：html → md。建立「双向流」概念。 **[VISUAL]** cross-dissolve 进入。前一镜的 destination card 在 11.50-11.80s 内缩小退场到右下角，新的 destination card（这次显示 markdown 源代码）从右侧入场。 新的 destination card 设计：**深底 markdown source 视图**（与 SHOT 05 的浅底 html 形成视觉对比）。 ``` ┌─────────────────────────────────┐ │ │ ← 背景 Charred #2A2620 │ # On Markdown │ ← Terracotta, mono 14px │ │ │ An essay · 2026 │ ← Smoke, mono 14px │ │ │ > md is the source. │ ← italic Smoke, mono 14px │ > Anything else is **product**. │ `**product**` 高亮 mica + bold │ │ │ - 1 source │ ← mono 14px Smoke │ - 6 forms │ │ - ∞ outputs │ │ │ │ essay.md · CLEAN MARKDOWN │ ← bottom Mono 10px Smoke └─────────────────────────────────┘ 480×560px, Charred 底, 顶部 24° 角折是 Cinder ``` arrow direction 反向：从右侧 destination card 向左 md 字符方向（短 Terracotta 线 + 箭头 head 指向左）。label 改为「html → md」。 **关键差异点**（和 SHOT 05 形成 visual rhyme）： - destination 在右、md 在左（同 SHOT 05） - 但 arrow direction 反向（visual: 我们在归档/拉回来） - card 是深底（视觉对比，强调这是 source） **[TYPE]** - 全卡片内部都是 JetBrains Mono 14px - markdown 语法元素配色：`#` 标题 Terracotta，`>` 引用 italic Smoke，`**bold**` Mica + bold，列表 dash Smoke - bottom mono 10px Smoke **[ANIM]** - 11.50-11.80s · 上一镜 card 退场（缩 → 右下角, fade out）+ md 字符保持 - 11.80-12.10s · arrow line 反向生长（这次从右向左, 300ms expoOut） - 12.10s · arrow head（指向左）浮现 - 12.20-12.40s · label「html → md」入场 - 12.40-13.10s · 新 destination card 入场（同 SHOT 05 入场逻辑） - 13.10-13.80s · markdown 内部 6 行 staggered 入场（每行 100ms delay） - 特殊 micro-detail：每一行入场时模拟 typewriter——line 的 character-by-character cascade reveal（让观众感觉到「这是 markdown 被「写出来」的过程」） - 13.80-14.50s · hold **[AUDIO]** - BGM: 持续 L1+L2+L3 layers - SFX: chime: capability 03 at 12.00s (-18dB) - SFX: paper rustle (12.40s) - SFX: 每行入场时极弱 keyboard click ticker（-26dB each, 100ms apart） **[CHROME]** - A: 推进到 `CAPABILITY · 03`，第三个 dot 实心 - B: ON - C: 进度点 ● 滑到「html→md」位置 - D: ON - E: ON **[ANTI-SLOP]** - ✅ 这是整支片唯一的「深底」镜头——刻意制造视觉对比，让观众知道「这是 source code」，不是「又来一个 destination」 - ✅ markdown 内部的 syntax highlighting 用的颜色不是 cyber 配色（不是 VS Code Dark+ 那种），是出版社配色（Terracotta + Smoke + Mica） - ✅ 「essay.md · CLEAN MARKDOWN」底部小印 → pause-and-look signature - ✅ 反向 arrow 不是「U-turn 曲线」，是直线 + 反向箭头——保持结构一致性 **[WHY]** 这一镜的真正作用不是「秀 capability 03」，是**告诉观众这条管道是双向的**。 如果整支片 6 个 capability 都是从 md 向外辐射，观众会以为「md 只是出去」。第 3 个 capability 让流动反向，建立「md 是一切的中枢」的世界观。 这是为什么 capability 顺序我选了 02 (md→html) → 03 (html→md) → 04 (md→docx) ——故意把反向 capability 卡在第 3 位，最大化「双向流」的认知 surprise。 --- ## SHOT 07 · "PUBLISHER GRADE · DOCX" (md → docx) **[TIMECODE]** 14.50 — 17.50s (3.0s) `|` **FUNCTION** CAPABILITY 04。出版社品位 docx。建立「md 不只是给程序员的」论点。 **[VISUAL]** 回到浅底，回到「md 在左、destination 在右」。 destination card 设计：**出版社级 docx 章节首页**（高密度信息，但完全克制）。 ``` ┌─────────────────────────────────┐ │ ON MARKDOWN│ ← page header, right-aligned, Smoke italic mono 9px │ CHAPTER · 01 │ ← Terracotta mono 11px bold 0.22em │ │ │ On Markdown │ ← Newsreader 700, 36px, Ink, lh 1.1 │ A short essay on source-of-truth│ ← Newsreader italic 14px, Smoke │ thinking │ │ │ │ ━━━━━━━━━━━━━━━━━━━━━━━━━━━ │ ← Terracotta full-width rule 3px │ │ │ ▬▬▬▬▬▬▬▬▬▬▬▬▬▬▬▬▬▬▬▬▬▬▬ │ ← 10 lines of mica bar paragraphs │ ▬▬▬▬▬▬▬▬▬▬▬▬▬▬▬▬▬▬▬▬ │ (varied widths 76-95%) │ ... │ │ │ │ — 1 — │ ← page number, centered, mono 10px Smoke └─────────────────────────────────┘ 480×580px, white card, Mica border, 24° corner fold ``` **特别细节**： - 顶部右上角的「page header」（书名 italic 灰色 mono）是真实出版社 docx 的细节签名 - 「CHAPTER · 01」前缀让观众一眼意识到「这是一本书的一页，不是一篇文章」 - terracotta full-width rule（不是细线，而是 3px 粗 rule）是出版社章节首页的招牌 - 底部 page number「— 1 —」前后的破折号是 Newsreader 的 em-dash，不是 hyphen **[TYPE]** - page header: Newsreader italic 9px, Smoke, letter-spacing 0.14em - CHAPTER · 01: JetBrains Mono Bold 11px, Terracotta, letter-spacing 0.22em - main title: Newsreader 700, 36px, Ink, line-height 1.05 - subtitle: Newsreader italic 14px, Smoke - terracotta rule: 3px thick, full card width - bar paragraphs: Mica color #E6E1D6, height 6px - page number: JetBrains Mono 10px, Smoke, letter-spacing 0.18em **[ANIM]** - 14.50-14.80s · 前一镜 card 退场 + md 保持 - 14.80-15.10s · arrow line 正向生长 - 15.10s · arrow head, label「md → docx」入场 - 15.30-16.10s · destination card 整体入场 - 16.10-17.00s · 内部 stagger：page header (delay 0) → CHAPTER 标 (delay 100ms) → title (delay 300ms) → subtitle (delay 500ms) → rule (delay 700ms) → 10 行段落 cascade (delay 850ms + 60ms cascade) → page number (delay 1600ms) - 17.00-17.50s · hold **[AUDIO]** - BGM: 持续；at 15.00s BGM 整体 swell +2dB（暗示我们在向高潮推进） - SFX: chime: capability 04 at 15.00s (-18dB) - SFX: paper rustle (15.30s) **[CHROME]** - A: `CAPABILITY · 04`, 第四个 dot 实心 - B/C/D/E: ON **[ANTI-SLOP]** - ✅ 不写「这是一本书的内页 mockup」的解释字（让排版自己说话） - ✅ bar paragraphs 用 Mica（#E6E1D6）这种极淡灰色，不是黑色——给「这是排版样式预览，不是真内容」的诚实信号 - ✅ pause-and-look signature：顶部 right-aligned page header italic mono——99% 的观众不会看，1% 的设计师看到会知道「这家做了功课」 - ✅ 这一镜是 6 个 capability 里色彩最饱和的（Terracotta 占了 page rule + chapter label + 顶部右 chrome counter）——刚好在故事弧的中段，符合「向高潮 build-up」的曲线 **[WHY]** CAPABILITY 04 是承上启下的关键一镜： - 它确认了「md 不只是 web 用」——它能做出版社级别的 docx - 它建立了「印刷品」的视觉语境，为 SHOT 08（pdf）和 SHOT 09（epub）做准备 观众看完这一镜，对「md → 印刷品」这条链条 ready。接下来两镜的 NEW 标签就有了承接。 --- ## SHOT 08 · "★ NEW · PRINT" (md → pdf) **[TIMECODE]** 17.50 — 20.50s (3.0s) `|` **FUNCTION** CAPABILITY 05。**NEW**。md → 出版级 PDF。第一次「升级」标志亮起。 **[VISUAL]** cross-dissolve 进入。这一镜的视觉强度**显著高于** SHOT 05-07——因为这是「新东西」，需要被记住。 视觉差异点： 1. **NEW 标签**：top-left 在 capability counter 旁边亮起一个 Terracotta 矩形框，内含「★ NEW」字符（JetBrains Mono Bold 13px, Terracotta, letter-spacing 0.22em，4px Terracotta border, 6px×12px padding） 2. **destination 不是单一卡片，是两张 PDF fan 出来**：A4 在后面（轻微 +5° 旋转），大32开（176×240mm，国内纸质书规格）在前面（轻微 -3° 旋转），形成「两个 page-size 都支持」的视觉 3. **每张 PDF 上有「印刷裁切标记」（crop marks）**——四角各一个 L 型小线，2px 粗，Smoke 色——这是真正印厂 PDF 的细节 4. arrow + label 配色全部用 Terracotta（不是 Ink），整体配色更暖 **两张 PDF 内容**： PDF A（A4, 后面）： ``` ┌──────────────────────────┐ │ ┌ ┐ │ ← crop marks │ A4 · 210×297mm │ ← Mono Bold 10px Terracotta │ ─── (Terracotta rule) │ │ On Markdown │ ← Newsreader 22px │ ────────────────── │ │ ▬▬▬▬▬▬▬▬▬▬▬ │ ← 7 lines mica bars │ ▬▬▬▬▬▬▬▬▬▬▬▬ │ │ ... │ │ │ │ └ ┘ │ ← crop marks └──────────────────────────┘ 360×460px, white card, +5° rotation ``` PDF B（大32开，前面）： ``` ┌────────────────────┐ │ ┌ ┐ │ ← crop marks │ 大32开 · 176×240mm│ ← Mono Bold 10px Terracotta │ ─── │ │ On Markdown │ ← Newsreader 19px │ ────────── │ │ ▬▬▬▬▬▬▬▬▬▬ │ ← 6 lines mica bars │ ... │ │ └ ┘ │ └────────────────────┘ 290×410px, white card, -3° rotation ``` **[TYPE]** - NEW 标签：Mono Bold 13px Terracotta, 0.22em letter-spacing, 1.5px Terracotta border - arrow label「md → pdf」：Mono Bold 14px Terracotta, 0.14em - PDF spec labels (A4 · 210×297mm 等)：Mono Bold 10px Terracotta, 0.2em - chapter titles inside PDFs：Newsreader 600 weight, 19-22px, Ink **[ANIM]** - 17.50-17.80s · 前一镜 card 退场 + md 保持 - 17.70s · **NEW 标签亮起**（特殊处理：scale 0.8 → 1.1 → 1.0 over 400ms with overshoot easing；同时一道极弱 terracotta glow 短暂 pulse 然后消失） - 17.80-18.10s · arrow + label 入场（这次用 Terracotta accent，强调「这是 NEW」） - 18.20-18.60s · PDF B（前面那张）入场（400ms expoOut, scale 0.85 → 1 + 顺时针 -8° → -3°） - 18.50-18.90s · PDF A（后面那张）紧随入场（400ms expoOut, scale 0.85 → 1 + 顺时针 0° → +5°，stagger delay 300ms） - 18.90-19.70s · 两张 PDF 内部 cascade staggered 入场 - 19.70s · 4 个 crop marks（PDF B 的）依次出现（80ms cascade，给「印厂工艺」的细节签名） - 19.70-20.50s · hold **[AUDIO]** - BGM: percussion pulse L4 加入 at 18.00s (-32dB)（极弱 sub-kick 4/4 节奏建立） - **SFX: chime: NEW (05) at 17.70s（double chime + soft glow + reverb tail, -14dB）** ← 这是整支片最重要的 SFX cue 之一 - SFX: paper rustle × 2（每张 PDF 入场时，-22dB each） - SFX: subtle "ink stamp" at 19.70s（crop marks 出现时, -22dB） **[CHROME]** - A: `CAPABILITY · 05`, 第五个 dot 实心 - A 旁边新增 NEW 标签 - B: ON, 此时 version chip 旁的橙点同步 pulse（强调「v2.0 新增」） - C: 进度点 ● 滑到「md→pdf」位置, 这个位置的文字字号加大 0.5px 强调 - D: ON - E: ON **[ANTI-SLOP]** - ✅ NEW 标签不是 emoji 不是 sticker——是 typographic mark（mono + 0.22em + ★ + border） - ✅ 两张 PDF 不是「叠在一起」的廉价 stacking，是 fan + 旋转（暗示「打开看」的物理动作） - ✅ crop marks 是真正印厂术语的视觉表达，pause 时能看到「啊这是 print-ready」 - ✅ 没用 glow 或 particle 来强调「NEW」——靠 typography 和 SFX 自己说话 - ✅ pause-and-look signature：PDF B 顶部的「大32开 · 176×240mm」中英混排，是花叔生态对国内纸质书规格的尊重 **[WHY]** 这是 ACT II 高潮镜之一。两件事必须同时发生： 1. 观众必须 immediate 意识到「这是新功能」 2. 必须用视觉细节说明「这不是凑数的 wkhtmltopdf 包装，是真正出版级」 NEW 标签 + crop marks + 两张 PDF fan + 完整的 A4 / 大32开规格说明——四件事一起做到上面两件。 下一镜的 epub 是双 NEW 镜头里的第二个，节奏感、情绪强度要比这一镜再上一档。 --- ## SHOT 09 · "★ NEW · EBOOK" (md → epub) **[TIMECODE]** 20.50 — 22.50s (2.0s) `|` **FUNCTION** CAPABILITY 06。**NEW**。md → 标准 EPUB3。第二个新功能。最后一个 capability。 **[VISUAL]** cross-dissolve 进入。这一镜的镜头时长**比前面短**（只 2.0s 而不是 3.0s）——因为我们已经建立了「NEW + destination」的模式，第二次出现观众秒懂，节奏可以加速。 destination card 设计：**Apple Books 风的 EPUB reader frame**（强调「这本书已经在阅读器里了」的现实感）。 ``` ╔════════════════════════════════════╗ ║ ● ● ● ║ ← window chrome (Apple Books) ╠════════════════════════════════════╣ ║ ║ ║ HUASHU · ORANGE BOOK ║ ← Mono Bold 10px Terracotta 0.22em ║ ║ ║ ║ ║ On ║ ← Newsreader 700, 30px, Ivory paper ║ Markdown ║ (on Charred bg) ║ ║ ║ ─── ║ ← Terracotta rule 40×2px ║ ║ ║ an essay · 花叔 ║ ← italic 14px Smoke on Charred ║ ║ ╠════════════════════════════════════╣ ║ Apple Books · 1 of 24 EPUB 3 ║ ← Mono 10px Smoke 0.14em ╚════════════════════════════════════╝ 460×470px, ivory paper outer + Charred inner book cover area 2px Ink border, 22px border-radius (modern app frame) ``` **关键视觉差异**： - 整体 frame 是「macOS app 窗口」感（三个圆点 + 圆角 22px） - 中间是「打开的电子书」cover area（Charred 底 + 出版社品位的 typography） - 底部是「Apple Books · 1 of 24」reader chrome - 整张 card 给人「我在 Apple Books 里读这本书」的现实感 **[TYPE]** - HUASHU · ORANGE BOOK：Mono Bold 10px, Terracotta, 0.22em - book title (On Markdown)：Newsreader 700, 30px, Ivory (on Charred bg), line-height 1.0 - terracotta rule：40×2px - author italic：Noto Serif SC italic 14px, Smoke - Apple Books chrome：Mono 10px, Smoke, 0.14em **[ANIM]** - 20.50-20.80s · 前一镜 PDF 退场 + md 保持 - 20.70s · NEW 标签**保持亮起**（这次不重新弹出，因为已经在 SHOT 08 建立了——直接显示「★ NEW」即可） - 20.80-21.10s · arrow + label「md → epub」入场（Terracotta accent，同 SHOT 08） - 21.20-21.80s · EPUB destination card 整体入场（600ms expoOut, scale 0.88 → 1） - 21.30-22.00s · 内部 staggered：window chrome dots (delay 0) → 顶部 brand label (delay 200ms) → book title 「On」(delay 400ms) → 「Markdown」(delay 480ms) → rule (delay 700ms) → author italic (delay 850ms) → bottom chrome (delay 1000ms) - 22.00-22.50s · hold + 准备 transition 到 ACT III **[AUDIO]** - BGM: percussion 持续，但 at 22.00s 整体 BGM swell +3dB（为 SHOT 10 的 convergence build-up） - **SFX: chime: NEW (06) at 20.70s（double chime + soft glow，比 SHOT 08 高半个音, -14dB）**——半音差让两个 NEW 镜头形成 musical relationship - SFX: window chrome subtle "click" at 21.20s（macOS 窗口出现感, -24dB） - SFX: page turn rustle at 21.40s **[CHROME]** - A: `CAPABILITY · 06`, 第六个 dot 实心（**全部实心 — 6/6**） - A 旁边 NEW 标签持续 - B: 版本 chip 的橙点 pulse 加强（amplitude × 1.5） - C: 进度点 ● 抵达最右端「md→epub」位置 - D: ON - E: ON **[ANTI-SLOP]** - ✅ 不画 Kindle 或 Apple Books 的真 logo（避免 IP 风险）；用 macOS 窗口 chrome 暗示「阅读器」即可 - ✅ 没用 e-ink 灰色滤镜（避免 Kindle slop） - ✅ 「Apple Books · 1 of 24」chrome 是真实出版数据感（24 章节，第 1 章） - ✅ pause-and-look signature：书名 「On / Markdown」**断行**——Newsreader 在 30px 大字号下的换行设计，致敬 Penguin Classics 封面排版 **[WHY]** 这一镜是 ACT II 的收尾。两件事必须完成： 1. 6 个 capability 全部展示完毕（counter 6/6 实心） 2. 情绪开始向 ACT III 的高潮 build-up 镜头长度从 3.0 → 2.0s 是刻意的——节奏在加速，观众感知到「我们要到顶峰了」。 --- ## SHOT 10 · "THE CONVERGENCE" **[TIMECODE]** 22.50 — 24.00s (1.5s) `|` **FUNCTION** ACT II → ACT III 的过渡。所有元素归位。准备 slogan。 **[VISUAL]** 22.50s：所有之前的 destination card 已退场。Chrome A/C 开始 fade out（capability counter 已 6/6 完成，使命达成）。 画面中央，md 字符从左侧位置（x=480）滑回正中（x=960），同时尺寸从 220px → 300px。 md 周围的 6 个 capability label（any→md / md→html / html→md / md→docx / md→pdf / md→epub）从远处（圆周 r=380px）逐个浮现，环绕 md 字符成圆形，每 60° 一个，按顺时针顺序排列（顶部从「any→md」开始）。这些 label 是 Mono Bold 14px Smoke（非 active）+ Terracotta（actually new）的 mix。 整体效果：**md 字符是太阳，6 个 capability 是行星。** 但这一镜不需要让观众停留太久——这是过渡镜。 23.50-24.00s：6 个 capability label 缓慢 fade out（200ms 每个，inverse cascade），md 字符继续保持在中央，缩小到 180px，准备让位给 slogan。 **[TYPE]** - 6 个 capability label：JetBrains Mono Bold 14px, letter-spacing 0.16em - 前 4 个（any→md / md→html / html→md / md→docx）：Smoke - 后 2 个（md→pdf / md→epub）：Terracotta **[ANIM]** - 22.50-22.80s · 上一镜 EPUB card 退场，Chrome A/C fade out（300ms linear） - 22.50-23.00s · md 字符滑回中央 + 放大（500ms expoOut） - 22.80-23.40s · 6 个 capability label 从 md 周围浮现（每个 60° 位置，r=380px，stagger 80ms each, fade-in 300ms + 微 outward slide 20px） - 23.40-23.80s · hold（6 个 label 在 md 周围 settle） - 23.80-24.00s · 6 个 label 同时
-
-
sfx
-
container
-
card-flip.mp3 11.9 KB · in bundle
-
card-snap.mp3 8.6 KB · in bundle
-
modal-open.mp3 10.2 KB · in bundle
-
stack-collapse.mp3 13.5 KB · in bundle
-
-
feedback
-
achievement.mp3 24.1 KB · in bundle
-
error-tone.mp3 11.9 KB · in bundle
-
notification-pop.mp3 10.2 KB · in bundle
-
success-chime.mp3 16.8 KB · in bundle
-
-
impact
-
brand-stamp.mp3 16.8 KB · in bundle
-
drop-thud.mp3 11.9 KB · in bundle
-
logo-reveal-v2.mp3 24.1 KB · in bundle
-
logo-reveal.mp3 24.1 KB · in bundle
-
-
keyboard
-
delete-key.mp3 8.6 KB · in bundle
-
enter.mp3 8.6 KB · in bundle
-
space-tap.mp3 8.6 KB · in bundle
-
type-fast.mp3 24.1 KB · in bundle
-
type.mp3 13.5 KB · in bundle
-
-
magic
-
ai-process.mp3 19.6 KB · in bundle
-
sparkle.mp3 13.5 KB · in bundle
-
transform.mp3 16.8 KB · in bundle
-
-
progress
-
complete-done.mp3 13.5 KB · in bundle
-
generate-start.mp3 13.5 KB · in bundle
-
loading-tick.mp3 8.6 KB · in bundle
-
-
terminal
-
command-execute.mp3 8.6 KB · in bundle
-
cursor-blink.mp3 8.6 KB · in bundle
-
output-appear.mp3 10.2 KB · in bundle
-
-
transition
-
dissolve.mp3 13.5 KB · in bundle
-
slide-in.mp3 10.2 KB · in bundle
-
swipe-horizontal.mp3 11.9 KB · in bundle
-
whoosh-fast.mp3 8.6 KB · in bundle
-
whoosh.mp3 10.2 KB · in bundle
-
-
ui
-
click-soft.mp3 8.6 KB · in bundle
-
click.mp3 8.6 KB · in bundle
-
focus.mp3 8.6 KB · in bundle
-
hover-subtle.mp3 8.6 KB · in bundle
-
tap-finger.mp3 8.6 KB · in bundle
-
toggle-on.mp3 8.6 KB · in bundle
-
-
-
showcases
-
cover
-
cover-build.html 5.5 KB · in bundle
-
cover-build.png 113.6 KB · in bundle
-
cover-pentagram.html 4.8 KB · in bundle
-
cover-pentagram.png 35.2 KB · in bundle
-
cover-takram.html 11.5 KB · in bundle
-
cover-takram.png 151.7 KB · in bundle
-
-
infographic
-
infographic-build.html 11.4 KB · in bundle
-
infographic-build.png 106.2 KB · in bundle
-
infographic-pentagram.html 13.6 KB · in bundle
-
infographic-pentagram.png 155.3 KB · in bundle
-
infographic-takram.html 21.9 KB · in bundle
-
infographic-takram.png 159.2 KB · in bundle
-
-
ppt
-
ppt-build.html 8.9 KB · in bundle
-
ppt-build.png 82.4 KB · in bundle
-
ppt-pentagram.html 11.7 KB · in bundle
-
ppt-pentagram.png 99 KB · in bundle
-
ppt-takram.html 15.3 KB · in bundle
-
ppt-takram.png 456.2 KB · in bundle
-
-
website-ai-nav
-
ainav-build.html 9.4 KB · in bundle
-
ainav-build.png 83.1 KB · in bundle
-
ainav-pentagram.html 10.3 KB · in bundle
-
ainav-pentagram.png 103.1 KB · in bundle
-
ainav-takram.html 12.4 KB · in bundle
-
ainav-takram.png 118.8 KB · in bundle
-
-
website-ai-writing
-
aiwriting-build.html 13.7 KB · in bundle
-
aiwriting-build.png 127.5 KB · in bundle
-
aiwriting-pentagram.html 13.9 KB · in bundle
-
aiwriting-pentagram.png 146.7 KB · in bundle
-
aiwriting-takram.html 17.6 KB · in bundle
-
aiwriting-takram.png 153.5 KB · in bundle
-
-
website-devdocs
-
devdocs-build.html 9.7 KB · in bundle
-
devdocs-build.png 66.6 KB · in bundle
-
devdocs-pentagram.html 12.5 KB · in bundle
-
devdocs-pentagram.png 114.3 KB · in bundle
-
devdocs-takram.html 12.8 KB · in bundle
-
devdocs-takram.png 109.2 KB · in bundle
-
-
website-homepage
-
homepage-build.html 8.1 KB · in bundle
-
homepage-build.png 60.3 KB · in bundle
-
homepage-pentagram.html 8.3 KB · in bundle
-
homepage-pentagram.png 55.8 KB · in bundle
-
homepage-takram.html 10.3 KB · in bundle
-
homepage-takram.png 124.6 KB · in bundle
-
-
website-saas
-
saas-build.html 12.6 KB · in bundle
-
saas-build.png 97.4 KB · in bundle
-
saas-pentagram.html 14.7 KB · in bundle
-
saas-pentagram.png 94.3 KB · in bundle
-
saas-takram.html 17.8 KB · in bundle
-
saas-takram.png 120.6 KB · in bundle
-
-
INDEX.md 5.4 KB
# Design Philosophy Showcases — 样例资产索引 > 8 种场景 × 3 种风格 = 24 个预制设计样例 > 用于 Phase 3 推荐设计方向时，直接展示「这个风格做出来长什么样」 ## 风格说明 | 代号 | 流派 | 风格名称 | 视觉气质 | |------|------|---------|---------| | **Pentagram** | 信息建筑派 | Pentagram / Michael Bierut | 黑白克制、瑞士网格、强字体层级、#E63946红色强调 | | **Build** | 极简主义派 | Build Studio | 奢侈品级留白(70%+)、微妙字重(200-600)、#D4A574暖金、精致 | | **Takram** | 东方哲学派 | Takram | 柔和科技感、自然色(米色/灰/绿)、圆角、图表如艺术 | ## 场景速查表 ### 内容设计场景 | # | 场景 | 规格 | Pentagram | Build | Takram | |---|------|------|-----------|-------|--------| | 1 | 公众号封面 | 1200×510 | `cover/cover-pentagram` | `cover/cover-build` | `cover/cover-takram` | | 2 | PPT数据页 | 1920×1080 | `ppt/ppt-pentagram` | `ppt/ppt-build` | `ppt/ppt-takram` | | 3 | 竖版信息图 | 1080×1920 | `infographic/infographic-pentagram` | `infographic/infographic-build` | `infographic/infographic-takram` | ### 网站设计场景 | # | 场景 | 规格 | Pentagram | Build | Takram | |---|------|------|-----------|-------|--------| | 4 | 个人主页 | 1440×900 | `website-homepage/homepage-pentagram` | `website-homepage/homepage-build` | `website-homepage/homepage-takram` | | 5 | AI导航站 | 1440×900 | `website-ai-nav/ainav-pentagram` | `website-ai-nav/ainav-build` | `website-ai-nav/ainav-takram` | | 6 | AI写作工具 | 1440×900 | `website-ai-writing/aiwriting-pentagram` | `website-ai-writing/aiwriting-build` | `website-ai-writing/aiwriting-takram` | | 7 | SaaS落地页 | 1440×900 | `website-saas/saas-pentagram` | `website-saas/saas-build` | `website-saas/saas-takram` | | 8 | 开发者文档 | 1440×900 | `website-devdocs/devdocs-pentagram` | `website-devdocs/devdocs-build` | `website-devdocs/devdocs-takram` | > 每个条目同时有 `.html`（源码）和 `.png`（截图）两个文件 ## 使用说明 ### Phase 3 推荐时引用 推荐设计方向后，可展示对应场景的预制截图： ``` 「这是 Pentagram 风格做公众号封面的效果 → [展示 cover/cover-pentagram.png]」 「Takram 风格做 PPT 数据页是这种感觉 → [展示 ppt/ppt-takram.png]」 ``` ### 场景匹配优先级 1. 用户需求的场景有精确匹配 → 直接展示对应场景 2. 无精确匹配但类型相近 → 展示最近似的场景（如「产品官网」→ 展示 SaaS 落地页） 3. 完全不匹配 → 跳过预制样例，直接进 Phase 3.5 现场生成 ### 横向对比展示 同一场景的 3 个风格适合并排展示，帮助用户直观比较： - 「这是同一个公众号封面，分别用 3 种风格实现的效果」 - 展示顺序：Pentagram（理性克制）→ Build（奢华极简）→ Takram（柔和温暖） ## 内容详情 ### 公众号封面（cover/） - 内容：Claude Code Agent 工作流 — 8 个并行 Agent 架构 - Pentagram：巨大红色「8」+ 瑞士网格线 + 数据条 - Build：超细字重「Agent」悬浮于 70% 留白中 + 暖金细线 - Takram：8 节点放射状流程图作为艺术品 + 米色底 ### PPT数据页（ppt/） - 内容：GLM-4.7 开源模型 Coding 能力突破（AIME 95.7 / SWE-bench 73.8% / τ²-Bench 87.4） - Pentagram：260px「95.7」锚点 + 红/灰/浅灰对比条形图 - Build：三组 120px 超细数字悬浮 + 暖金渐变对比条 - Takram：SVG 雷达图 + 三色叠加 + 圆角数据卡片 ### 竖版信息图（infographic/） - 内容：AI 记忆系统 CLAUDE.md 从 93KB 优化到 22KB - Pentagram：巨大「93→22」数字 + 编号区块 + CSS 数据条 - Build：极致留白 + 柔影卡片 + 暖金连接线 - Takram：SVG 环形图 + 有机曲线流程图 + 毛玻璃卡片 ### 个人主页（website-homepage/） - 内容：独立开发者 Alex Chen 的作品集首页 - Pentagram：112px 大名 + 瑞士网格分栏 + 编辑数字 - Build：玻璃态导航 + 悬浮统计卡片 + 超细字重 - Takram：纸质纹理 + 小圆形头像 + 发丝细分隔线 + 不对称布局 ### AI导航站（website-ai-nav/） - 内容：AI Compass — 500+ AI 工具目录 - Pentagram：方角搜索框 + 编号工具列表 + 大写分类标签 - Build：圆角搜索框 + 精致白色工具卡片 + 药丸标签 - Takram：有机错位卡片布局 + 柔和分类标签 + 图表式连接 ### AI写作工具（website-ai-writing/） - 内容：Inkwell — AI 写作助手 - Pentagram：86px 大标题 + 线框编辑器模型 + 网格特性列 - Build：漂浮编辑器卡片 + 暖金 CTA + 奢华写作体验 - Takram：诗意衬线标题 + 有机编辑器 + 流程图 ### SaaS落地页（website-saas/） - 内容：Meridian — 商业智能分析平台 - Pentagram：黑白分栏 + 结构化仪表盘 + 140px「3x」锚点 - Build：悬浮仪表盘卡片 + SVG 面积图 + 暖金渐变 - Takram：圆角柱状图 + 流程节点 + 柔和地球色 ### 开发者文档（website-devdocs/） - 内容：Nexus API — 统一 AI 模型网关 - Pentagram：左侧导航栏 + 方角代码块 + 红色字符串高亮 - Build：居中漂浮代码卡片 + 柔影 + 暖金图标 - Takram：米色代码块 + 流程图连接 + 虚线特性卡片 ## 文件统计 - HTML 源文件：24 个 - PNG 截图：24 个 - 总资产：48 个文件 --- **版本**：v1.0 **创建日期**：2026-02-13 **适用于**：design-philosophy skill Phase 3 推荐环节
-
-
android_frame.jsx 4.4 KB · in bundle
-
animations.jsx 10.3 KB · in bundle
-
banner.svg 9.3 KB · in bundle
-
bgm-ad.mp3 4.7 MB · in bundle
-
bgm-educational-alt.mp3 4.3 MB · in bundle
-
bgm-educational.mp3 3.9 MB · in bundle
-
bgm-tech.mp3 4.6 MB · in bundle
-
bgm-tutorial-alt.mp3 3.8 MB · in bundle
-
bgm-tutorial.mp3 5.3 MB · in bundle
-
browser_window.jsx 3.9 KB · in bundle
-
cursor.jsx 14.1 KB · in bundle
-
deck_index.html 20.8 KB · in bundle
-
deck_stage.js 11.4 KB
/** * <deck-stage> — HTML幻灯片外壳web component * * 提供功能： * - 固定尺寸canvas（默认1920×1080）+ auto-scale + letterbox * - 键盘导航（←/→/Space/Home/End/Esc） * - 左右点击区域导航 * - slide counter (当前/总数) * - localStorage持久化当前slide * - Speaker notes postMessage (支持外层渲染) * - Hash导航 (#slide-5 跳到第5张) * - Print-to-PDF支持 (Cmd+P / Ctrl+P 一页一slide) * - 自动给每个slide添加 data-screen-label * * 用法： * <deck-stage> * <section>Slide 1</section> * <section>Slide 2</section> * </deck-stage> * * 自定义尺寸： * <deck-stage width="1080" height="1920">...</deck-stage> * * Speaker notes：在<head>加 * <script type="application/json" id="speaker-notes"> * ["slide 1 notes", "slide 2 notes"] * </script> */ (function() { const STORAGE_KEY_PREFIX = 'deck-stage-slide-'; class DeckStage extends HTMLElement { constructor() { super(); this.attachShadow({ mode: 'open' }); this._currentSlide = 0; this._slides = []; this._storageKey = STORAGE_KEY_PREFIX + (location.pathname || 'default'); } connectedCallback() { this._width = parseInt(this.getAttribute('width')) || 1920; this._height = parseInt(this.getAttribute('height')) || 1080; // Shadow DOM 先渲染（独立于子节点，不受 parser 时机影响） this._render(); // 防御：若 script 放在 <head> 里（而非 </deck-stage> 之后）， // parser 此刻可能还没处理完子 <section>，querySelectorAll 会返回空。 // 延迟到下一个事件循环，确保子节点都已 parse 完毕。 const init = () => { this._collectSlides(); this._setupEventListeners(); this._restoreSlide(); this._updateDisplay(); this._setupPrintStyles(); }; if (this.ownerDocument.readyState === 'loading') { // 文档还在 parse，等 DOMContentLoaded 一次搞定所有 section this.ownerDocument.addEventListener('DOMContentLoaded', init, { once: true }); } else { // 文档已 parse 完（script 在 body 底部或 defer），下一帧收集即可 requestAnimationFrame(init); } } _render() { this.shadowRoot.innerHTML = ` <style> :host { display: block; position: fixed; inset: 0; background: #000; overflow: hidden; font-family: -apple-system, 'SF Pro Text', 'PingFang SC', sans-serif; } :host([noscale]) .stage { transform: none !important; top: 0 !important; left: 0 !important; } .stage { position: absolute; top: 50%; left: 50%; transform-origin: top left; will-change: transform; background: #fff; } .slide-wrapper { width: 100%; height: 100%; position: relative; } ::slotted(section) { display: none; width: 100%; height: 100%; position: absolute; top: 0; left: 0; overflow: hidden; } ::slotted(section.active) { display: block; } .counter { position: fixed; bottom: 20px; right: 20px; background: rgba(0, 0, 0, 0.6); color: #fff; padding: 6px 14px; border-radius: 999px; font-size: 13px; font-variant-numeric: tabular-nums; z-index: 100; user-select: none; opacity: 0.6; transition: opacity 0.2s; } .counter:hover { opacity: 1; } .nav-zone { position: fixed; top: 0; bottom: 0; width: 15%; cursor: pointer; z-index: 50; } .nav-zone.left { left: 0; } .nav-zone.right { right: 0; } .nav-hint { position: absolute; top: 50%; transform: translateY(-50%); width: 44px; height: 44px; border-radius: 999px; background: rgba(255, 255, 255, 0.1); color: rgba(255, 255, 255, 0.6); display: flex; align-items: center; justify-content: center; font-size: 24px; opacity: 0; transition: opacity 0.2s; } .nav-zone.left .nav-hint { left: 20px; } .nav-zone.right .nav-hint { right: 20px; } .nav-zone:hover .nav-hint { opacity: 1; } @media print { :host { position: static; background: #fff; } .counter, .nav-zone { display: none !important; } .stage { position: static; transform: none !important; page-break-after: always; } ::slotted(section) { display: block !important; position: relative !important; page-break-after: always; width: 100%; height: 100%; } } </style> <div class="stage" id="stage" style="width: ${this._width}px; height: ${this._height}px;"> <div class="slide-wrapper"> <slot></slot> </div> </div> <div class="nav-zone left" id="navLeft"> <div class="nav-hint">‹</div> </div> <div class="nav-zone right" id="navRight"> <div class="nav-hint">›</div> </div> <div class="counter" id="counter">1 / 1</div> `; } _collectSlides() { this._slides = Array.from(this.querySelectorAll(':scope > section')); this._slides.forEach((slide, idx) => { if (!slide.hasAttribute('data-screen-label')) { const num = String(idx + 1).padStart(2, '0'); slide.setAttribute('data-screen-label', num); } if (!slide.hasAttribute('data-om-validate')) { slide.setAttribute('data-om-validate', ''); } }); } _setupEventListeners() { window.addEventListener('resize', () => this._updateScale()); document.addEventListener('keydown', (e) => { if (e.target.matches('input, textarea, [contenteditable]')) return; switch (e.key) { case 'ArrowRight': case ' ': case 'PageDown': e.preventDefault(); this.next(); break; case 'ArrowLeft': case 'PageUp': e.preventDefault(); this.prev(); break; case 'Home': e.preventDefault(); this.goTo(0); break; case 'End': e.preventDefault(); this.goTo(this._slides.length - 1); break; } }); this.shadowRoot.getElementById('navLeft').addEventListener('click', () => this.prev()); this.shadowRoot.getElementById('navRight').addEventListener('click', () => this.next()); window.addEventListener('hashchange', () => this._handleHash()); if (location.hash) { setTimeout(() => this._handleHash(), 0); } const observer = new MutationObserver(() => { if (this.hasAttribute('noscale')) { this._updateScale(); } }); observer.observe(this, { attributes: true, attributeFilter: ['noscale'] }); } _handleHash() { const match = location.hash.match(/^#slide-(\d+)$/); if (match) { const idx = parseInt(match[1]) - 1; if (idx >= 0 && idx < this._slides.length) { this.goTo(idx); } } } _restoreSlide() { try { const stored = localStorage.getItem(this._storageKey); if (stored !== null) { const idx = parseInt(stored); if (idx >= 0 && idx < this._slides.length) { this._currentSlide = idx; } } } catch (e) {} } _saveSlide() { try { localStorage.setItem(this._storageKey, String(this._currentSlide)); } catch (e) {} } _updateScale() { if (this.hasAttribute('noscale')) { const stage = this.shadowRoot.getElementById('stage'); stage.style.transform = 'none'; stage.style.top = '0'; stage.style.left = '0'; return; } const stage = this.shadowRoot.getElementById('stage'); if (!stage) return; const viewportW = window.innerWidth; const viewportH = window.innerHeight; const scale = Math.min(viewportW / this._width, viewportH / this._height); const scaledW = this._width * scale; const scaledH = this._height * scale; const offsetX = (viewportW - scaledW) / 2; const offsetY = (viewportH - scaledH) / 2; stage.style.transform = `translate(${offsetX}px, ${offsetY}px) scale(${scale})`; stage.style.top = '0'; stage.style.left = '0'; } _updateDisplay() { this._slides.forEach((slide, idx) => { slide.classList.toggle('active', idx === this._currentSlide); }); const counter = this.shadowRoot.getElementById('counter'); if (counter) { counter.textContent = `${this._currentSlide + 1} / ${this._slides.length}`; } this._updateScale(); try { window.postMessage({ slideIndexChanged: this._currentSlide, totalSlides: this._slides.length }, '*'); } catch (e) {} try { if (window.parent && window.parent !== window) { window.parent.postMessage({ slideIndexChanged: this._currentSlide, totalSlides: this._slides.length }, '*'); } } catch (e) {} } _setupPrintStyles() { const printStyle = document.createElement('style'); printStyle.textContent = ` @media print { @page { size: ${this._width}px ${this._height}px; margin: 0; } body { margin: 0; padding: 0; } deck-stage { position: static !important; } deck-stage > section { display: block !important; position: relative !important; width: ${this._width}px !important; height: ${this._height}px !important; page-break-after: always; overflow: hidden; } deck-stage > section:last-child { page-break-after: auto; } } `; document.head.appendChild(printStyle); } next() { if (this._currentSlide < this._slides.length - 1) { this._currentSlide++; this._saveSlide(); this._updateDisplay(); } } prev() { if (this._currentSlide > 0) { this._currentSlide--; this._saveSlide(); this._updateDisplay(); } } goTo(idx) { if (idx >= 0 && idx < this._slides.length) { this._currentSlide = idx; this._saveSlide(); this._updateDisplay(); } } get currentSlide() { return this._currentSlide; } get totalSlides() { return this._slides.length; } } customElements.define('deck-stage', DeckStage); window.DeckStage = DeckStage; })(); -
design_canvas.jsx 5.1 KB · in bundle
-
ios_frame.jsx 4.6 KB · in bundle
-
macos_window.jsx 2.5 KB · in bundle
-
narration_stage.jsx 20.2 KB · in bundle
-
personal-asset-index.example.json 1.8 KB
{ "_meta": { "description": "个人素材索引模板 — 复制此文件并填入你的真实数据", "how_to_use": "1. 复制此文件到 ~/.claude/memory/personal-asset-index.json 2. 填入你的真实信息 3. design-philosophy skill 会自动读取", "note": "真实数据文件不要放在 skill 目录内，避免随 skill 分发泄露隐私" }, "identity": { "real_name": "你的真名", "pen_names": ["笔名1", "笔名2"], "english_name": "English Name", "title": "你的头衔/一句话介绍", "bio_short": "50-100字简介", "bio_long": "200-300字详细介绍", "avatar_url": "头像URL", "source": "数据来源备注" }, "contact": { "email": "your@email.com", "wechat_personal": "微信号", "source": "数据来源备注" }, "social_media": { "github": { "url": "https://github.com/yourname", "username": "yourname" }, "youtube": { "url": "https://www.youtube.com/@YourChannel", "channel_name": "频道名" }, "source": "数据来源备注" }, "websites": { "main_site": { "url": "https://yoursite.com", "description": "网站描述", "local_path": "/path/to/local/project/" } }, "products": { "product_1": { "name": "产品名", "type": "iOS App / Web App / CLI Tool / 电子书", "achievement": "主要成就", "icon_path": "/path/to/icon.png", "project_path": "/path/to/project/" } }, "stats": { "social_followers": "粉丝数", "product_users": "用户数", "source": "数据来源备注" }, "design_assets": { "article_images": { "base_path": "/path/to/images/", "notable_sets": [] } }, "knowledge_base": { "wechat_articles": "/path/to/knowledge_base/" } }
-
-
demos
-
md-html-narration
-
md-html-demo.html 37 KB · in bundle
-
script.md 3.4 KB
--- title: md还是html，这是个蠢问题 gap: 0.5 --- ## opening 前两天，[[cue:thariq]]Claude Code 团队的 Thariq 发了篇爆文。 标题就一句话，HTML 是新的 markdown。 他说他几乎不再写 md 文件了，全让 AI 给他生成 HTML。 500 万阅读，X 上立马吵翻了。 一派是 md 党，[[cue:two-camps]]觉得 md 才是 AI 时代的源代码。 另一派觉得 Thariq 说得对，HTML 才是终极答案。 ## md-side md 党的证据其实挺硬的。 你看 OpenAI 去年发的 AGENTS.md，[[cue:agents-md]]60000 多个项目用，AWS、Anthropic、Google、微软、OpenAI，AI 半壁江山一起捐进 Linux Foundation 做开放标准。 Karpathy 的 llm-wiki，主体就是三层 markdown，单一个 CLAUDE.md 文件，5 万 star。 Cloudflare 实测过一组数据，[[cue:token-saving]]同一篇博客，HTML 一万六千 token，转成 md 只要三千。 省 80%。 GitHub 官方也讲过一句，文档不再是描述代码，[[cue:doc-is-code]]文档就是代码。 ## html-side 但 html 党也没说错。 Thariq 那篇文章里几条论据我都同意。 第一是空间信息。[[cue:spatial]]diff、调用图、架构图，本来就是有空间维度的，md 把它压成一行字，html 能左右对照，理解效率不是一个量级的。 第二是动态体验。[[cue:dynamic]]做产品原型，按钮按下去什么颜色、什么 easing 曲线，文字描述再多没用，html 能让你直接看见。 第三是结构化阅读。[[cue:structured]]可折叠章节、tab 代码块、边栏术语表，跟同样的字线性堆一遍是两种东西。 Anthropic 现在的 Live Artifacts，HTML 已经从静态产物升级成可以交互、能拉实时数据的 dashboard。 ## the-real-question 我看完想说，[[cue:reveal]]这俩根本是在争一个蠢问题。 两边都赢了。 但赢的是不同的问题。 md 党回答的是，[[cue:question-md]]我们用什么写。 html 党回答的是，[[cue:question-html]]我们给人什么看。 这是两个问题。 怎么会有谁取代谁。 ## the-split 我觉得真问题是这个。 md 和 html 不是替代关系，[[cue:split]]是分工关系。 以前你写 md 自己也看 md。 那时候要折中，所以 md 胜出。 但 AI 出现后，[[cue:ai-changes]]第一次有了一个新情况。 生产成本可以被 AI 吸收。 HTML 那部分太重的代价，AI 替你扛。 你只负责消费。 原来要折中的需求，被拆成了两端的极端最优。 生产端要轻、要快、要 token efficient，[[cue:md-side-win]]那就是 md。 消费端要丰富、要可视化、要好分享，[[cue:html-side-win]]那就是 html。 两端各自登顶。 中间那个折中位置，没人需要了。 ## activity-proof 最干净的活样本是 Thariq 自己。 3 月份他发了篇 Skills 指南，[[cue:thariq-march]]强调核心还是 markdown。 5 月份他发了 HTML 是新 markdown。 同一个人，[[cue:same-person]]两端各自登顶，互不打架。 Karpathy 和 Lex Fridman 那对组合也一样。 内核是 markdown wiki，[[cue:karpathy-lex]]外壳是动态 HTML。 不是 Lex 替换了 Karpathy，是他在 Karpathy 的基础上加了一层消费层。 ## closing 所以下次你想吵这个的时候，[[cue:final]]先问自己一句。 你现在面对的是「写」，还是「看」。 写，[[cue:md-final]]用 md。 看，[[cue:html-final]]用 html。 工具替你处理切换。 立场可以放下了。
-
-
voiceover-demo
-
script.md 589 B
--- title: 什么是 token gap: 0.4 --- ## intro 你有没有想过，[[cue:question]]当我们和 AI 对话的时候，AI 到底是怎么理解我们的话的呢。 ## token-1 答案是它根本不理解汉字，[[cue:reveal]]它只认识 token。 ## token-2 你可以把 token 理解成 AI 的最小信息单位。 比如「人工智能」这四个字，[[cue:split]]在 AI 眼里可能是两个 token：人工，智能。 ## ending 所以下次看到「百万 token 上下文」这种说法，[[cue:context]]你就知道，它说的是 AI 一次能记住多少个这样的小块。 -
什么是token.html 11.7 KB · in bundle
-
-
c1-ios-prototype-en.html 34.3 KB · in bundle
-
c1-ios-prototype.html 34.3 KB · in bundle
-
c2-slides-pptx-en.html 32.1 KB · in bundle
-
c2-slides-pptx.html 32.2 KB · in bundle
-
c3-motion-design-en.html 36.2 KB · in bundle
-
c3-motion-design.html 36.2 KB · in bundle
-
c4-tweaks-en.html 30.4 KB · in bundle
-
c4-tweaks.html 30.4 KB · in bundle
-
c5-infographic-en.html 24.4 KB · in bundle
-
c5-infographic.html 24.2 KB · in bundle
-
c6-expert-review-en.html 25.8 KB · in bundle
-
c6-expert-review.html 26.2 KB · in bundle
-
hero-animation-v10-en.html 47.6 KB · in bundle
-
w1-brand-protocol-en.html 20.1 KB · in bundle
-
w1-brand-protocol.html 20.4 KB · in bundle
-
w2-junior-designer-en.html 30.6 KB · in bundle
-
w2-junior-designer.html 31 KB · in bundle
-
w3-fallback-advisor-en.html 23.3 KB · in bundle
-
w3-fallback-advisor.html 25.8 KB · in bundle
-
-
references
-
ai-video-review.md 3.9 KB
# AI看片评审闭环（scripts/cloud/ai-review-video.py） > 终渲MP4喂给视频理解模型（seed-2.0-lite），按固定checklist出结构化评审报告。 > 定位：**终渲后、交付前**的最后一道质检，替代人肉全片重看。不替代逐帧verify-video.sh。 > ⚠️ 可选云能力：压缩后的视频段会发送到火山方舟官方接口（ark.cn-beijing.volces.com）， > 使用你自己的ARK_API_KEY，需`--yes`或`HUASHU_CLOUD_OK=1`显式确认。见仓库根`SECURITY.md`。 > 不想用云：`scripts/verify-video.sh`截帧人工看，全程本地。 ## 何时用 - 终渲60fps成片出来后、交付/混音前，跑一遍 - SFX混音版出来后再跑一遍（onset核对只在有音轨时生效） - 改完大问题重渲后复检 - 不要在试渲30fps阶段跑（分辨率/节奏未定，浪费调用） ## 怎么用 ```bash cd 项目目录 && unset ALL_PROXY # 脚本内已免疫代理，unset是双保险 uv run ~/.claude/skills/huashu-design/scripts/cloud/ai-review-video.py \ --video 成片.mp4 \ --context 导演稿.md \ # 强烈建议带上：模型靠它区分「设计意图」和「bug」 --yes # 确认视频段发送火山方舟（或 HUASHU_CLOUD_OK=1） ``` - ARK_API_KEY 配在 skill 根目录 `.env`（已 gitignore）或环境变量，脚本只提取这一个变量 - 报告落盘：视频同目录 `<视频名>-AI评审.md`（`--output`可改） - `--segment-len` 默认60秒一段；`--model` 默认 doubao-seed-2-0-lite-260215 - 210秒片实测：6次API调用，6-10分钟，tokens约18万in/2万out（lite档，费用分钱级） ## 调用链路（三层混合，不是纯模型） 1. **ffmpeg客观检测**（确定性，不会漏）： - `silencedetect` → 音效onset时间表（模型**听不到**视频音轨，2026-07-17实测） - `freezedetect` → ≥3秒完全静止段清单 2. **模型分段看片**：60s/段压缩后送审（1280宽/15fps/crf28，扁平动画约0.5MB/分钟）， 每段prompt含checklist+导演稿+该段的onset/静止段数据，时间点换算成原片时间 3. **模型全片低清pass**：960宽/10fps全片单独送审，专查跨段叙事连贯/hero贯穿/整体节奏 4. 文本汇总call按①-⑧合并；分段原始记录+客观检测数据全部保留在报告附录 ## checklist与严重度 ①黑帧/渲染残缺 ②文字裁切/错字 ③元素重叠遮挡 ④叙事连贯（过渡按 camera-language.md §7 三层词汇识别：六式[流白/穿暗场/虚焦接力/黑场字卡/whip-pan/mask-wipe]、hidden-cut、travel[共享元素归位/字腔穿越]；裸切=未包装的硬切，记⚡） ⑤hero贯穿性 ⑥节奏死段（客观清单+模型判断刻意hold还是真死段）⑦音效打点（onset+画面事件核对） ⑧构图失衡/空白 ⚠️致命=交付前必修 | ⚡重要=观感明显受损 | 💡建议=锦上添花 ## 局限（用报告前必读） - **模型听不到声音**：⑦是「音轨onset时刻画面有没有事件」的单向核对， 判断不了音效选得对不对、音量对不对、BGM情绪对不对 - **看不到帧级细节**：1-2帧的闪烁、细微抖动、精确色值偏差、亚像素对齐抓不到， 这些仍靠 verify-video.sh 截帧人工看 - **过渡类型判断偏严**：压缩到15fps后，快速交叉淡出可能被报成「硬切」， 分段与全片pass矛盾时汇总会标「存疑」——存疑项自己抽帧确认再改 - **「刻意hold vs 死段」是模型意见**：b-roll垫口播的长定格常被放行，成片独立观看时要自己再判 - 调用失败（网络/key/额度）会如实写进报告头，绝不编造评审结果；失败段的时间范围会标出 ## 实测基准 首跑对象：B00-前三分钟主线-SFX.mp4（210s）。模型自主发现幕间过渡问题和hero断点方向正确 但把fade误报硬切；纯模型抓死段只中3/14，接入freezedetect后全覆盖。结论：客观检测层是 这个闭环的下限保证，模型负责语义判断。 -
animation-best-practices.md 21.9 KB
# Animation Best Practices · 正向动画设计语法 > 基于 Anthropic 官方三支产品动画（Claude Design / Claude Code Desktop / Claude for Word） > 的深度拆解，提炼出的"Anthropic 级"动画设计规则。 > > 配套 `animation-pitfalls.md`（避坑清单）使用——本文件是「**应该这样做**」， > pitfalls 是「**不要这样做**」，两者正交，都要读。 > > **约束声明**：本文件只收录**运动逻辑和表达风格**，**不引入任何品牌色具体色值**。 > 色彩决策走 §1.a 核心资产协议（从品牌 spec 抽取）或「设计方向顾问」 > （20 种哲学各自的配色方案）。本 reference 讨论的是「**怎么动**」，不是「**什么色**」。 --- ## §0 · 你是谁 · 身份与品味 > 在读后面任何技术规则之前，先读这一节。规则是**从身份涌现的**—— > 不是相反。 ### §0.1 身份锚点 **你是一个研究过 Anthropic / Apple / Pentagram / Field.io 运动档案的 motion designer。** 做动画时，你不是在调 CSS transition——你是在用数字元素**模拟一个物理世界**， 让观众的潜意识相信「这是有重量、有惯性、会溢出的物体」。 你不做 PowerPoint 式动画。你不做「fade in fade out」动画。你做的动画**让人相信屏幕 是一个可以伸手进去的空间**。 ### §0.2 核心信念（3 条） 1. **动画是物理学，不是动画曲线** `linear` 是数字，`expoOut` 是物体。你相信屏幕上的像素值得被当作"物体"对待。 每一条 easing 的选择，都是在回答「这个元素有多重？摩擦系数多大？」的物理问题。 2. **时间分配比曲线形状更重要** Slow-Fast-Boom-Stop 是你的呼吸。**均匀节奏的动画是技术演示，有节奏的动画是叙事。** 在正确的时刻慢下来——比在错误的时刻用对 easing 更重要。 3. **礼让观众，比炫技更难** 关键结果前停 0.5 秒是**技术**，不是妥协。**让人类大脑有反应时间，是动画师的最高素养。** AI 默认会做一个没有停顿的、信息密度满格的动画——那是新手。你要做的是克制。 ### §0.3 品味标准 · 什么是美 你对「好」和「great」的判断标准如下。每一条都有**识别方法**——当你看到一个候选动画时， 用这些问题判断它是否达标，而不是机械对照 14 条规则。 | 美的维度 | 识别方法（观众反应） | |---|---| | **物理重量感** | 动画结束时，元素"**落**"得稳——不是"**停**"在那里。观众潜意识觉得"这有重量" | | **礼让观众** | 关键信息出现前有一个可感的 pause（≥300ms）——观众来得及"**看见**"再继续 | | **留白** | 收尾是戛然而止 + hold，不是 fade to black。最后一帧清晰、肯定、有决定感 | | **克制** | 全片只有一处「120% 精致」，其余 80% 恰到好处——**到处炫技是廉价的信号** | | **手感** | 弧线（不是直线）、不规律（不是 setInterval 的机械节奏）、有呼吸感 | | **敬意** | 展示 tweak 的过程、展示 bug 的修复——**不藏工作、不给"魔法"**。AI 是协作者不是魔术师 | ### §0.4 自检 · 观众第一反应法 做完一支动画，**观众看完第一反应是什么？**——这是你唯一要优化的指标。 | 观众反应 | 评级 | 诊断 | |---|---|---| | "看起来挺流畅的" | good | 合格但无特色，你在做 PowerPoint | | "这个动画真顺" | good+ | 技术对了，但没惊艳 | | "这个东西看起来真的像**从桌面上浮起来的**" | great | 你触到了物理重量感 | | "这不像是 AI 做的" | great+ | 你触到了 Anthropic 的门槛 | | "我想**截图**发朋友圈" | great++ | 你做到了让观众主动传播 | **great 和 good 的区别，不在于技术正确度，在于品味判断**。技术正确 + 品味对 = great。 技术正确 + 品味空 = good。技术错误 = 没入门。 ### §0.5 身份和规则的关系 下面 §1-§8 的技术规则，是这套身份在具体场景的**执行手段**——不是独立规则清单。 - 遇到规则没覆盖的场景 → 回到 §0，用**身份**判断，不要瞎猜 - 遇到规则之间有冲突 → 回到 §0，用**品味标准**判断哪条更重要 - 想破一条规则 → 先回答："这样做符合 §0.3 哪一条美？" 答得上就破，答不上就别破 好。继续读下去。 --- ## 总览 · 动画是物理学的三层展开 大多数 AI 生成动画有廉价感的根源是——**它们表现得像「数字」不是「物体」**。 真实世界的物体有质量、有惯性、有弹性、会溢出。Anthropic 三支片子的「高级感」根源， 就在于给数字元素一套**物理世界的运动规则**。 这套规则有 3 个层次： 1. **叙事节奏层**：Slow-Fast-Boom-Stop 的时间分配 2. **运动曲线层**：Expo Out / Overshoot / Spring，拒绝 linear 3. **表达语言层**：展示过程、鼠标弧线、Logo 形变收束 --- ## 1. 叙事节奏 · Slow-Fast-Boom-Stop 5 段结构 Anthropic 三支片子无一例外遵循这个结构： | 段 | 占比 | 节奏 | 作用 | |---|---|---|---| | **S1 触发** | ~15% | 慢 | 给人类反应时间，建立真实感 | | **S2 生成** | ~15% | 中 | 视觉惊艳点出现 | | **S3 过程** | ~40% | 快 | 展示可控性/密度/细节 | | **S4 爆发** | ~20% | Boom | 镜头拉远/3D pop-out/多面板涌现 | | **S5 落幅** | ~10% | 静 | 品牌 Logo + 戛然而止 | **具体时长映射**（15 秒动画为例）： S1 触发 2s · S2 生成 2s · S3 过程 6s · S4 爆发 3s · S5 落幅 2s **禁止做的事**： - ❌ 均匀节奏（每秒信息密度一样）— 观众疲劳 - ❌ 持续高密度 — 无峰值无记忆点 - ❌ 渐弱收尾（fade out 到透明）— 应该**戛然而止** **自检**：用纸笔画 5 个 thumbnail，每个代表一段的高潮画面。如果 5 张图差别不大， 说明节奏没做出来。 --- ## 2. Easing 哲学 · 拒绝 linear，拥抱物理 Anthropic 三支片子的所有动效都用带「阻尼感」的贝塞尔曲线。默认的 cubic easeOut （`1-(1-t)³`）**不够锐**——起步不够快、停顿不够稳。 ### 三个核心 Easing（animations.jsx 已内置） ```js // 1. Expo Out · 迅速启动缓慢刹车（最常用，默认主 easing） // 对应 CSS: cubic-bezier(0.16, 1, 0.3, 1) Easing.expoOut(t) // = t === 1 ? 1 : 1 - Math.pow(2, -10 * t) // 2. Overshoot · 带弹性的 toggle/按钮弹出 // 对应 CSS: cubic-bezier(0.34, 1.56, 0.64, 1) Easing.overshoot(t) // 3. Spring 物理 · 几何体归位、自然落位 Easing.spring(t) ``` ### 用法映射 | 场景 | 用哪个 Easing | |---|---| | 卡片 rise-in / 面板入场 / Terminal fade / focus overlay | **`expoOut`**（主 easing，最常用） | | Toggle 切换 / 按钮弹出 / 强调交互 | `overshoot` | | Preview 几何体归位 / 物理落位 / UI 元素抖弹 | `spring` | | 持续运动（如鼠标轨迹插值） | `easeInOut`（保留对称性） | ### 反直觉洞察 大多数产品宣传片的动画**太快太硬**。`linear` 让数字元素像机器，`easeOut` 是基础分， `expoOut` 才是「高级感」的技术根源——它给数字元素一种**物理世界的重量感**。 --- ## 3. 运动语言 · 8 条共性原则 ### 3.1 底色不用纯黑纯白 Anthropic 三支片子没有一支用 `#FFFFFF` 或 `#000000` 做主底色。**带色温的中性色** （或暖或冷）有"纸张 / 画布 / 桌面"的物质感，削弱机器感。 **具体色值决策**走 §1.a 核心资产协议（从品牌 spec 抽取）或「设计方向顾问」 （20 种哲学各自的底色方案）。本 reference 不给具体色值——那是**品牌决策**，不是运动规则。 ### 3.2 Easing 绝不是 linear 见 §2。 ### 3.3 Slow-Fast-Boom-Stop 叙事 见 §1。 ### 3.4 展示「过程」而非「魔法结果」 - Claude Design 展示 tweak 参数、拖滑块（不是一键生成完美结果） - Claude Code 展示代码报错 + AI 修复（不是一次成功） - Claude for Word 展示 Redline 红删绿增的修改过程（不是直接给最终稿） **共同潜台词**：产品是**协作者、结对工程师、资深编辑**——不是一键魔术师。 这精准打击专业用户对「可控性」和「真实性」的痛点。 **反 AI slop**：AI 默认会做「魔法一键成功」的动画（一键生成 → 完美结果）， 这是通用公约数。**反过来做**——展示过程、展示 tweak、展示 bug 和修复—— 是品牌识别度的来源。 ### 3.5 鼠标轨迹人工绘制（弧线 + Perlin Noise） 真人鼠标运动不是直线，是「起步加速 → 弧线 → 减速修正 → 点击」。 AI 直接直线插值的鼠标轨迹**有潜意识排斥感**。 ```js // 二次贝塞尔曲线插值（起点 → 控制点 → 终点） function bezierQuadratic(p0, p1, p2, t) { const x = (1-t)*(1-t)*p0[0] + 2*(1-t)*t*p1[0] + t*t*p2[0]; const y = (1-t)*(1-t)*p0[1] + 2*(1-t)*t*p1[1] + t*t*p2[1]; return [x, y]; } // 路径：起点 → 偏离中点 → 终点（做弧线） const path = [[100, 100], [targetX - 200, targetY + 80], [targetX, targetY]]; // 再叠加极小的 Perlin Noise（±2px）制造「手抖」 const jitterX = (simpleNoise(t * 10) - 0.5) * 4; const jitterY = (simpleNoise(t * 10 + 100) - 0.5) * 4; ``` ### 3.6 Logo「形变收束」(Morph) Anthropic 三支片子的 Logo 出场**都不是简单 fade-in**，是**前一个视觉元素形变而来**。 **共同模式**：倒数 1-2 秒做 Morph / Rotate / Converge，让整个叙事在品牌点上「坍缩」。 **低成本实现**（不用真 morph）： 让前一个视觉元素「坍缩」成一个色块（scale → 0.1，向中心 translate）， 色块再「膨胀」展开成 wordmark。过渡用 150ms 快切 + motion blur （`filter: blur(6px)` → `0`）。 ```js <Sprite start={13} end={14}> {/* 坍缩：前一个元素 scale 0.1，opacity 保持，filter blur 增加 */} const scale = interpolate(t, [0, 0.5], [1, 0.1], Easing.expoOut); const blur = interpolate(t, [0, 0.5], [0, 6]); </Sprite> <Sprite start={13.5} end={15}> {/* 膨胀：Logo 从色块中心 scale 0.1 → 1，blur 6 → 0 */} const scale = interpolate(t, [0, 0.6], [0.1, 1], Easing.overshoot); const blur = interpolate(t, [0, 0.6], [6, 0]); </Sprite> ``` ### 3.7 衬线 + 无衬线双字体 - **品牌 / 旁白**：衬线（有「学术感 / 出版物感 / 品位」） - **UI / 代码 / 数据**：无衬线 + 等宽 **单一字体都是不对的**。衬线给「品位」，无衬线给「功能」。 具体字体选择走品牌 spec（brand-spec.md 的 Display / Body / Mono 三栈）或设计方向 顾问的 20 种哲学。本 reference 不给具体字体——那是**品牌决策**。 ### 3.8 焦点切换 = 背景减弱 + 前景锐化 + Flash 引导 焦点切换**不只是**降低 opacity。完整配方是： ```js // 非焦点元素的滤镜组合 tile.style.filter = ` brightness(${1 - 0.5 * focusIntensity}) saturate(${1 - 0.3 * focusIntensity}) blur(${focusIntensity * 4}px) // ← 关键：加 blur 才真的"退后" `; tile.style.opacity = 0.4 + 0.6 * (1 - focusIntensity); // 焦点完成后在焦点位置做 150ms Flash highlight 引导视线回流 focusOverlay.animate([ { background: 'rgba(255,255,255,0.3)' }, { background: 'rgba(255,255,255,0)' } ], { duration: 150, easing: 'ease-out' }); ``` **为什么 blur 是必须的**：只靠 opacity + brightness，焦点外的元素还是「锐利」的， 视觉上没有「退到后景」的效果。blur(4-8px) 让非焦点真的退一层景深。 --- ## 4. 具体运动技巧（可直接抄的代码片段） ### 4.1 FLIP / Shared Element Transition 按钮「膨胀」成输入框，**不是**按钮消失 + 新面板出现。核心是**同一个 DOM 元素**在 两种状态间 transition，不是两个元素 cross-fade。 ```jsx // 用 Framer Motion layoutId <motion.div layoutId="design-button">Design</motion.div> // ↓ 点击后同 layoutId <motion.div layoutId="design-button"> <input placeholder="Describe your design..." /> </motion.div> ``` 原生实现参考 https://aerotwist.com/blog/flip-your-animations/ ### 4.2「呼吸式」展开（width→height） 面板展开**不是同时拉 width 和 height**，而是： - 前 40% 时间：只拉 width（保持 height 小） - 后 60% 时间：width 保持，撑 height 这模拟物理世界「先展开，再注水」的感觉。 ```js const widthT = interpolate(t, [0, 0.4], [0, 1], Easing.expoOut); const heightT = interpolate(t, [0.3, 1], [0, 1], Easing.expoOut); style.width = `${widthT * targetW}px`; style.height = `${heightT * targetH}px`; ``` ### 4.3 Staggered Fade-up（30ms stagger） 表格行、卡片列、列表项入场时，**每个元素延迟 30ms**，`translateY` 从 10px 回到 0。 ```js rows.forEach((row, i) => { const localT = Math.max(0, t - i * 0.03); // 30ms stagger row.style.opacity = interpolate(localT, [0, 0.3], [0, 1], Easing.expoOut); row.style.transform = `translateY(${ interpolate(localT, [0, 0.3], [10, 0], Easing.expoOut) }px)`; }); ``` ### 4.4 非线性呼吸 · 关键结果前悬停 0.5s 机器执行快且连贯，但**关键结果出现前悬停 0.5 秒**，让观众大脑有反应时间。 ```jsx // 典型场景：AI 生成完 → 悬停 0.5s → 结果浮现 <Sprite start={8} end={8.5}> {/* 0.5s 停顿——什么也不动，让观众盯着加载状态 */} <LoadingState /> </Sprite> <Sprite start={8.5} end={10}> <ResultAppear /> </Sprite> ``` **反例**：AI 生成完立刻无缝切到结果——观众没反应时间，信息流失。 ### 4.5 Chunk Reveal · 模拟 token 流式 AI 生成文字**不要用 `setInterval` 单字符蹦出**（像老电影字幕），要用 **chunk reveal** ——一次出现 2-5 个字符，间隔不规律，模拟真实 token 流式输出。 ```js // 分 chunk 而不是分字符 const chunks = text.split(/(\s+|,\s*|\.\s*|;\s*)/); // 按词 + 标点切 let i = 0; function reveal() { if (i >= chunks.length) return; element.textContent += chunks[i++]; const delay = 40 + Math.random() * 80; // 不规律 40-120ms setTimeout(reveal, delay); } reveal(); ``` ### 4.6 Anticipation → Action → Follow-through Disney 12 原则中的 3 条。Anthropic 用得很显式： - **Anticipation**（预备）：动作开始前有小反向动作（按钮轻微缩小再弹出） - **Action**（动作）：主要动作本身 - **Follow-through**（跟随）：动作结束后有余韵（卡片落位后轻微 bounce） ```js // 卡片入场的完整三段 const anticip = interpolate(t, [0, 0.2], [1, 0.95], Easing.easeIn); // 预备 const action = interpolate(t, [0.2, 0.7], [0.95, 1.05], Easing.expoOut); // 主动 const settle = interpolate(t, [0.7, 1], [1.05, 1], Easing.spring); // 回弹 // 最终 scale = 三段乘积或分段应用 ``` **反例**：只有 Action 没有 Anticipation + Follow-through 的动画，像「PowerPoint 动画」。 ### 4.7 3D Perspective + translateZ 分层 想要「倾斜 3D + 悬浮卡片」的气质，给容器加 perspective，给单个元素不同的 translateZ： ```css .stage-wrap { perspective: 2400px; perspective-origin: 50% 30%; /* 视线略俯视 */ } .card-grid { transform-style: preserve-3d; transform: rotateX(8deg) rotateY(-4deg); /* 黄金比例 */ } .card:nth-child(3n) { transform: translateZ(30px); } .card:nth-child(5n) { transform: translateZ(-20px); } .card:nth-child(7n) { transform: translateZ(60px); } ``` **为什么 rotateX 8° / rotateY -4° 是黄金比例**： - 大于 10° → 元素扭曲感过强，看起来像「倒下」 - 小于 5° → 像「错切」而不是「透视」 - 8° × -4° 的非对称比例模拟「镜头在桌面左上角俯视」的 natural angle ### 4.8 斜向 Pan · 同时动 XY 镜头运动不是纯上下或纯左右，而是**同时动 XY** 模拟斜向移动： ```js const panX = Math.sin(flowT * 0.22) * 40; const panY = Math.sin(flowT * 0.35) * 30; stage.style.transform = ` translate(-50%, -50%) rotateX(8deg) rotateY(-4deg) translate3d(${panX}px, ${panY}px, 0) `; ``` **关键**：X 和 Y 的频率不同（0.22 vs 0.35），避免 Lissajous 循环规则化。 --- ## 5. 场景配方（三种叙事模板） 参考材料里三支视频对应三种产品性格。**选一种最贴合你的产品**，不要混搭。 ### 配方 A · Apple Keynote 戏剧式（Claude Design 类） **适合**：大版本发布、hero 动画、视觉惊艳优先 **节奏**：Slow-Fast-Boom-Stop 强弧线 **Easing**：全程 `expoOut` + 少量 `overshoot` **SFX 密度**：高（~0.4/s），SFX 音高调到 BGM 音阶 **BGM**：IDM / 极简科技电子，冷静+精密 **收束**：镜头急拉远 → drop → Logo 形变 → 空灵单音 → 戛然而止 ### 配方 B · 一镜到底工具式（Claude Code 类） **适合**：开发者工具、生产力 App、心流场景 **节奏**：持续稳定 flow，没有明显峰值 **Easing**：`spring` 物理 + `expoOut` **SFX 密度**：**0**（纯靠 BGM 驱动剪辑节奏） **BGM**：Lo-fi Hip-hop / Boom-bap，85-90 BPM **核心技巧**：关键 UI 动作踩在 BGM kick/snare 瞬态上——「**音乐律动即交互音效**」 ### 配方 C · 办公效率叙事式（Claude for Word 类） **适合**：企业软件、文档/表格/日历类、专业感优先 **节奏**：多 scene 硬切 + Dolly In/Out **Easing**：`overshoot`（toggle）+ `expoOut`（面板） **SFX 密度**：中（~0.3/s），UI click 为主 **BGM**：Jazzy Instrumental，小调，BPM 90-95 **核心亮点**：某一幕必有「全片高光」—— 3D pop-out / 脱离平面浮起 --- ## 6. 反例 · 这样做就是 AI slop | 反 pattern | 为什么错 | 正确做法 | |---|---|---| | `transition: all 0.3s ease` | `ease` 是 linear 的亲戚，所有元素同速 | 用 `expoOut` + 分元素 stagger | | 所有入场都 `opacity 0→1` | 没有运动方向感 | 配合 `translateY 10→0` + Anticipation | | Logo 淡入 | 没有叙事收束感 | Morph / Converge / 坍缩-展开 | | 鼠标直线移动 | 潜意识机器感 | 贝塞尔弧线 + Perlin Noise | | 打字单字蹦出（setInterval） | 像老电影字幕 | Chunk Reveal，随机间隔 | | 关键结果无悬停 | 观众没反应时间 | 结果前 0.5s 悬停 | | 焦点切换只改 opacity | 非焦点元素还锐利 | opacity + brightness + **blur** | | 纯黑底 / 纯白底 | 赛博感 / 反光疲劳 | 带色温的中性色（走品牌 spec） | | 所有动画同样快 | 无节奏 | Slow-Fast-Boom-Stop | | Fade out 收尾 | 无决定感 | 戛然而止（hold 最后一帧） | --- ## 6.5 · 导演稿的视觉密度条款（B00实战教训，2026-07-17） **只写叙事+运镜的导演稿，会收到线框稿。** B00阶跃b-roll实测：v1导演稿把六幕的叙事、时间轴、镜头运动写得很全，实现agent交付的动画动效全部合格、check全绿——但视觉是「三块素色暗块+大字」的示意图水平，被导演一票打回（「太简单太无聊」）。agent在没有密度标准时，永远按最省几何交差。 **导演稿（或任何动画brief）必须显式包含三样**： 1. **视觉密度标准**：每屏细节元素的量级要求（骨架UI内容行、图例、纹理、次级元素），以及一句可执行的验收表述，如「任意暂停一帧，和参照标杆摆在一起不丢人」 2. **参照标杆**：指向一个具体的已有成品（同项目旧动画/A系列/某个demo），构件工艺直接搬，不让agent凭空发明 3. **全局氛围层清单**：地面线锚定、构件软阴影、纸面/背景纹理、hero跟班或同类人格化小元素、静止构件的idle微动（呼吸/光标/微推进）——「空旷无聊感」的主要解药是这一层，不是主元素本身 **修复路径也有定式**：动效骨架（时间轴/运镜/morph路径/字卡时机）与视觉工艺（构件/密度/氛围）是两层，验收被打回时先问清是哪层的问题——动效过关就只做re-skin，不重编舞。 --- ## 7. 自检清单（动画交付前 60 秒） - [ ] 叙事结构是 Slow-Fast-Boom-Stop，不是均匀节奏？ - [ ] 默认 easing 是 `expoOut`，不是 `easeOut` 或 `linear`？ - [ ] Toggle / 按钮弹出用了 `overshoot`？ - [ ] 卡片 / 列表入场有 30ms stagger？ - [ ] 关键结果前有 0.5s 悬停？ - [ ] 打字用 Chunk Reveal，不是 setInterval 单字？ - [ ] 焦点切换加了 blur（不只是 opacity）？ - [ ] Logo 是形变收束（Morph），不是淡入？ - [ ] 底色不是纯黑 / 纯白（带色温）？ - [ ] 文字有衬线 + 无衬线层次？ - [ ] 收尾是戛然而止，不是渐弱？ - [ ] （有鼠标的话）鼠标轨迹是弧线，不是直线？ - [ ] SFX 密度符合产品性格（见配方 A/B/C）？ - [ ] BGM 和 SFX 有 6-8dB 响度差？（见 `audio-design-rules.md`） --- ## 8. 与其他 reference 的关系 | reference | 定位 | 关系 | |---|---|---| | `animation-pitfalls.md` | 技术避坑（16 条） | 「**不要这样做**」· 本文件的反面 | | `animations.md` | Stage/Sprite 引擎用法 | 动画**怎么写**的基础 | | `audio-design-rules.md` | 双轨制音频规则 | 动画**配音频**的规则 | | `sfx-library.md` | 37 个 SFX 清单 | 音效**素材库** | | `apple-gallery-showcase.md` | Apple 画廊展示风格 | 一种特定运动风格的专题 | | **本文件** | 正向运动设计语法 | 「**应该这样做**」 | **调用顺序**： 1. 先看 SKILL.md 工作流程 Step 3 的form推导五问（决定叙事角色和视觉温度） 2. 选定方向后读本文件确定**运动语言**（配方 A/B/C） 3. 写代码时参考 `animations.md` 和 `animation-pitfalls.md` 4. 导出视频时走 `audio-design-rules.md` + `sfx-library.md` --- ## 附录 · 本文件素材来源 - Anthropic 官方动画拆解：花叔项目目录的 `参考动画/BEST-PRACTICES.md` - Anthropic 音频拆解：同目录 `AUDIO-BEST-PRACTICES.md` - 3 支参考视频：`ref-{1,2,3}.mp4` + 对应 `gemini-ref-*.md` / `audio-ref-*.md` - **严格过滤**：本 reference 不收录任何具体品牌色值、字体名、产品名。 色彩/字体决策走 §1.a 核心资产协议或 20 种设计哲学。 -
animation-pitfalls.md 30.1 KB
# Animation Pitfalls：HTML 动画踩过的坑与规则 做动画时最常踩的 bug 和如何避免。每条规则都来自真实失败案例。 写动画之前读完这篇，能省一轮迭代。 ## 1. 叠层布局 —— `position: relative` 是默认义务 **踩的坑**：一个 sentence-wrap 元素包了 3 个 bracket-layer（`position: absolute`）。没给 sentence-wrap 设 `position: relative`，结果 absolute 的 bracket 以 `.canvas` 为坐标系，飘到屏幕底部 200px 外。 **规则**： - 任何包含 `position: absolute` 子元素的容器，**必须**显式 `position: relative` - 即使视觉上不需要「偏移」，也要写 `position: relative` 作为坐标系锚点 - 如果你在写 `.parent { ... }`，其子元素里有 `.child { position: absolute }`，下意识给 parent 加 relative **快速检查**：每出现一个 `position: absolute`，往上数 ancestor，确保最近的 positioned 祖先是你*想要的*坐标系。 ## 2. 字符陷阱 —— 不依赖稀有 Unicode **踩的坑**：想用 `␣` (U+2423 OPEN BOX) 可视化「空格 token」。Noto Serif SC / Cormorant Garamond 都没这个字形，渲染为空白/豆腐，观众完全看不到。 **规则**： - **动画里出现的每个字符，都必须在你选定的字体里存在** - 常见稀有字符黑名单：`␣ ␀ ␐ ␋ ↩ ⏎ ⌘ ⌥ ⌃ ⇧ ␦ ␖ ␛` - 要表达「空格 / 回车 / 制表符」这类元字符，用 **CSS 构造的语义盒子**： ```html <span class="space-key">Space</span> ``` ```css .space-key { display: inline-flex; padding: 4px 14px; border: 1.5px solid var(--accent); border-radius: 4px; font-family: monospace; font-size: 0.3em; letter-spacing: 0.2em; text-transform: uppercase; } ``` - Emoji 也要验证：某些 emoji 在 Noto Emoji 以外字体会 fallback 成灰色方框，最好用 `emoji` font-family 或 SVG ## 3. 数据驱动的 Grid/Flex 模板 **踩的坑**：代码里 `const N = 6` 个 tokens，但 CSS 写死 `grid-template-columns: 80px repeat(5, 1fr)`。结果第 6 个 token 没有 column，整个矩阵错位。 **规则**： - 当 count 从 JS 数组来（`TOKENS.length`），CSS 模板也应该数据驱动 - 方案 A：用 CSS 变量从 JS 注入 ```js el.style.setProperty('--cols', N); ``` ```css .grid { grid-template-columns: 80px repeat(var(--cols), 1fr); } ``` - 方案 B：用 `grid-auto-flow: column` 让浏览器自动扩展 - **禁用「固定数字 + JS 常量」的组合**，N 改了 CSS 不会同步更新 ## 4. 过渡断层 —— 场景切换要连续 **踩的坑**：zoom1 (13-19s) → zoom2 (19.2-23s) 之间，主句子已经 hidden，zoom1 fade out（0.6s）+ zoom2 fade in（0.6s）+ stagger delay（0.2s+）= 约 1 秒纯空白画面。观众以为动画卡住了。 **规则**： - 连续切换场景时，fade out 和 fade in 要**交叉重叠**，不是前一个完全消失再开始下一个 ```js // 差： if (t >= 19) hideZoom('zoom1'); // 19.0s out if (t >= 19.4) showZoom('zoom2'); // 19.4s in → 中间 0.4s 空白 // 好： if (t >= 18.6) hideZoom('zoom1'); // 提前 0.4s 开始 fade out if (t >= 18.6) showZoom('zoom2'); // 同时 fade in（cross-fade） ``` - 或者用一个「锚点元素」（如主句子）作为场景之间的视觉连接，zoom 切换期间它短暂回显 - 配 CSS transition 的 duration 算清楚，避免 transition 还没结束就触发下一个 ## 5. Pure Render 原则 —— 动画状态应可 seek **踩的坑**：用 `setTimeout` + `fireOnce(key, fn)` 链式触发动画状态。正常播放没问题，但做逐帧录制/seek到任意时间点时，之前的 setTimeout 已经执行过就无法「回到过去」。 **规则**： - `render(t)` 函数理想上是 **pure function**：给定 t 输出唯一 DOM 状态 - 如果必须用副作用（如 class 切换），用 `fired` set 配合显式 reset： ```js const fired = new Set(); function fireOnce(key, fn) { if (!fired.has(key)) { fired.add(key); fn(); } } function reset() { fired.clear(); /* 清所有 .show class */ } ``` - 暴露 `window.__seek(t)` 供 Playwright / 调试用： ```js window.__seek = (t) => { reset(); render(t); }; ``` - 动画相关的 setTimeout 不要跨越 >1 秒，否则 seek 回跳时会乱套 ## 6. 字体加载前测量 = 测错 **踩的坑**：页面一 DOMContentLoaded 就调用 `charRect(idx)` 测量 bracket 位置，字体还没加载，每个字符宽度是 fallback 字体的宽度，位置全错。等字体一加载（约 500ms 后），bracket 的 `left: Xpx` 还是老值，永久偏移。 **规则**： - 任何依赖 DOM 测量（`getBoundingClientRect`、`offsetWidth`）的布局代码，**必须**包在 `document.fonts.ready.then()` 里 ```js document.fonts.ready.then(() => { requestAnimationFrame(() => { buildBrackets(...); // 此时字体已就绪，测量准确 tick(); // 动画开始 }); }); ``` - 额外的 `requestAnimationFrame` 给浏览器一帧时间提交 layout - 如果用 Google Fonts CDN，`<link rel="preconnect">` 加速首次加载 ## 7. 录制准备 —— 为视频导出预留抓手 **踩的坑**：Playwright `recordVideo` 默认 25fps，从 context 创建就开始录。页面加载、字体加载的前 2 秒都被录进去。交付时视频前面 2 秒空白/闪白。 **规则**： - 提供 `render-video.js` 工具处理：warmup navigate → reload 重启动画 → 等 duration → ffmpeg trim head + 转 H.264 MP4 - 动画的**第 0 帧**要是最终布局已就位的完整初始状态（不是空白或加载中） - 想要 60fps？用 ffmpeg `minterpolate` 后处理，不指望浏览器源帧率 - 想要 GIF？两阶段 palette（`palettegen` + `paletteuse`），对 30s 1080p 动画能压到 3MB 参见 `video-export.md` 获取完整脚本调用方式。 ## 8. 批量导出 —— tmp 目录必须带 PID 防并发冲突 **踩的坑**：用 `render-video.js` 3 个进程并行录 3 个 HTML。因为 TMP_DIR 只用 `Date.now()` 命名，3 个进程同毫秒启动时共用同一个 tmp 目录。最先完成的进程清理 tmp，另外两个读目录时 `ENOENT`，全部崩溃。 **规则**： - 任何多进程可能共用的临时目录，命名必须带 **PID 或随机后缀**： ```js const TMP_DIR = path.join(DIR, '.video-tmp-' + Date.now() + '-' + process.pid); ``` - 如果确实想多文件并行，用 shell 的 `&` + `wait` 而不是在一个 node 脚本里 fork - 批量录多个 HTML 时，保守做法：**串行**运行（2 个以内可并行，3 个以上老实排队） ## 9. 录屏里有进度条/重播按钮 —— Chrome 元素污染视频 **踩的坑**：动画 HTML 加了 `.progress` 进度条、`.replay` 重播按钮、`.counter` 时间戳，方便人类调试播放。录成 MP4 交付时这些元素出现在视频底部，像把开发者工具截进去了一样。 **规则**： - HTML 里给人类用的「chrome 元素」（progress bar / replay button / footer / masthead / counter / phase labels）和视频内容本体分开管理 - **约定 class 名** `.no-record`：任何带这个 class 的元素，录屏脚本自动隐藏 - 脚本端（`render-video.js`）默认注入 CSS 隐藏常见 chrome class 名： ``` .progress .counter .phases .replay .masthead .footer .no-record [data-role="chrome"] ``` - 用 Playwright 的 `addInitScript` 注入（会在每次 navigate 前生效，reload 也稳） - 想看原样 HTML（带 chrome）时加 `--keep-chrome` flag ## 10. 录屏开头几秒动画重复 —— Warmup 帧泄漏 **踩的坑**：`render-video.js` 的旧流程 `goto → wait fonts 1.5s → reload → wait duration`。录制从 context 创建就开始，warmup 阶段动画已经播了一段，reload 后从 0 重启。结果视频前几秒是「动画中段 + 切换 + 动画从 0 开始」，重复感强。 **规则**： - **Warmup 和 Record 必须用独立的 context**： - Warmup context（无 `recordVideo` 选项）：只负责 load url、等字体、然后 close - Record context（有 `recordVideo`）：fresh 状态开始，animation 从 t=0 开始录 - ffmpeg `-ss trim` 只能裁 Playwright 的一点点 startup latency（~0.3s），**不能**用来掩盖 warmup 帧；源头要干净 - 录制 context 关闭 = webm 文件写入磁盘，这是 Playwright 的约束 - 相关代码模式： ```js // Phase 1: warmup (throwaway) const warmupCtx = await browser.newContext({ viewport }); const warmupPage = await warmupCtx.newPage(); await warmupPage.goto(url, { waitUntil: 'networkidle' }); await warmupPage.waitForTimeout(1200); await warmupCtx.close(); // Phase 2: record (fresh) const recordCtx = await browser.newContext({ viewport, recordVideo }); const page = await recordCtx.newPage(); await page.goto(url, { waitUntil: 'networkidle' }); await page.waitForTimeout(DURATION * 1000); await page.close(); await recordCtx.close(); ``` ## 11. 画面内别画「伪 chrome」—— 装饰版 player UI 与真 chrome 撞车 **踩的坑**：动画用 `Stage` 组件，已经自带 scrubber + 时间码 + 暂停按钮（属于 `.no-record` chrome，导出时自动隐藏）。我又在画面底部画了一条「`00:60 ──── CLAUDE-DESIGN / ANATOMY`」的"杂志页码感装饰进度条"，自我感觉良好。**结果**：用户看到两条进度条——一条是 Stage 控制器，一条是我画的装饰。视觉上完全撞车，认定为 bug。「视频内还有个进度条是怎么回事？」 **规则**： - Stage 已经提供：scrubber + 时间码 + 暂停/重播按钮。**画面内不要再画**进度指示、当前时间码、版权署名条、章节计数器——它们要么和 chrome 撞车，要么就是 filler slop（违反「earn its place」原则）。 - 「页码感」「杂志感」「底部署名条」这些**装饰诉求**，是 AI 自动加上的高频 filler。每一个出现都要警觉——它真的传达了不可替代的信息吗？还是单纯填满空白？ - 如果你坚信某个底部条带必须存在（例如：动画主题就是讲 player UI），那它必须**叙事必要**，且**视觉上和 Stage scrubber 显著区分**（不同位置、不同形式、不同色调）。 **元素归属测试**（每个画进 canvas 的元素必须能回答）： | 它属于什么 | 处理 | |------------|------| | 某一幕的叙事内容 | OK，留着 | | 全局 chrome（控制/调试用） | 加 `.no-record` class，导出时隐藏 | | **既不属于任何幕，又不是 chrome** | **删**。这就是无主之物，必然是 filler slop | **自检（交付前 3 秒）**：截一张静态图，问自己—— - 画面里有没有「看起来像 video player UI 的东西」（横线进度条、时间码、控制按钮模样）？ - 如果有，删掉它叙事是否有损？无损就删。 - 同一类信息（进度/时间/署名）有没有出现两次？合并到 chrome 一处。 **反例**：底部画 `00:42 ──── PROJECT NAME`、画面右下角画"CH 03 / 06"章节计数、画面边缘画版本号"v0.3.1"——都是伪 chrome filler。 ## 12. 录屏前置空白 + 录屏起点偏移 —— `__ready` × tick × lastTick 三联陷阱 **踩的坑（A · 前置空白）**：60 秒动画导出 MP4，前 2-3 秒是空白页面。`ffmpeg --trim=0.3` 剪不掉。 **踩的坑（B · 起点偏移，2026-04-20 真实事故）**：导出 24 秒视频，用户观感「视频 19 秒才开始播第一帧」。实际上动画从 t=5 开始录，录到 t=24 后 loop 回 t=0，再录 5 秒到 end——所以视频最后 5 秒才是动画真正的开头。 **根因**（两个坑共享一个根因）： Playwright `recordVideo` 从 `newContext()` 那一刻就开始写 WebM，此时 Babel/React/字体加载共耗时 L 秒（2-6s）。录屏脚本等 `window.__ready = true` 作为「动画从这里开始」的锚点——它和动画 `time = 0` 必须严格 pair。有两种常见错法： | 错法 | 症状 | |------|------| | `__ready` 在 `useEffect` 或同步 setup 阶段设（在 tick 第一帧之前） | 录屏脚本以为动画开始了，实际 WebM 还在录空白页 → **前置空白** | | tick 的 `lastTick = performance.now()` 在**脚本顶层**初始化 | 字体加载 L 秒被算进首帧 `dt`，`time` 瞬间跳到 L → 录屏全程滞后 L 秒 → **起点偏移** | **✅ 正确的完整 starter tick 模板**（手写动画必须用这个骨架）： ```js // ━━━━━━ state ━━━━━━ let time = 0; let playing = false; // ❗ 默认不播，等字体 ready 再启动 let lastTick = null; // ❗ sentinel——tick 首帧时 dt 强制为 0（别用 performance.now()） const fired = new Set(); // ━━━━━━ tick ━━━━━━ function tick(now) { if (lastTick === null) { lastTick = now; window.__ready = true; // ✅ pair：「录屏起点」与「动画 t=0」同一帧 render(0); // 再渲一次确保 DOM 就绪（此时字体已 ready） requestAnimationFrame(tick); return; } const dt = (now - lastTick) / 1000; // 首帧之后 dt 才开始推进 lastTick = now; if (playing) { let t = time + dt; if (t >= DURATION) { t = window.__recording ? DURATION - 0.001 : 0; // 录制时不 loop，留 0.001s 保留末帧 if (!window.__recording) fired.clear(); } time = t; render(time); } requestAnimationFrame(tick); } // ━━━━━━ boot ━━━━━━ // 不要在顶层立即 rAF——等字体加载完才启动 document.fonts.ready.then(() => { render(0); // 先把初始画面画出来（字体已就绪） playing = true; requestAnimationFrame(tick); // 首次 tick 会 pair __ready + t=0 }); // ━━━━━━ seek 接口（供 render-video 防御性矫正用）━━━━━━ window.__seek = (t) => { fired.clear(); time = t; lastTick = null; render(t); }; ``` **为什么这个模板对**： | 环节 | 为什么必须这样 | |------|-------------| | `lastTick = null` + 首帧 `return` | 避免「脚本加载到 tick 首次执行」的 L 秒被算进动画时间 | | `playing = false` 默认 | 字体加载期间 `tick` 即使运行也不推进 time，避免渲染错位 | | `__ready` 在 tick 首帧设 | 录屏脚本此刻开始计时，对应的画面是动画真正的 t=0 | | `document.fonts.ready.then(...)` 里才启动 tick | 规避字体 fallback 宽度测量、避免首帧字体跳变 | | `window.__seek` 存在 | 让 `render-video.js` 可以主动矫正——第二道防线 | **录屏脚本端的对应防御**： 1. `addInitScript` 注入 `window.__recording = true`（先于 page goto） 2. `waitForFunction(() => window.__ready === true)`，记录此刻偏移作为 ffmpeg trim 3. **额外**：`__ready` 之后主动 `page.evaluate(() => window.__seek && window.__seek(0))`，把 HTML 可能的 time 偏差强制归零——这是第二道防线，对付不严格遵守 starter 模板的 HTML **验证方法**：导出 MP4 后 ```bash ffmpeg -i video.mp4 -ss 0 -vframes 1 frame-0.png ffmpeg -i video.mp4 -ss $DURATION-0.1 -vframes 1 frame-end.png ``` 首帧必须是动画 t=0 的初始状态（不是中段，不是黑），末帧必须是动画终态（不是第二轮 loop 的某个时刻）。 **参考实现**：`assets/animations.jsx` 的 Stage 组件、`scripts/render-video.js` 都已按此协议实现。手写 HTML 必须套 starter tick 模板——每一行都是防过具体 bug。 ## 13. 录制时禁止 loop —— `window.__recording` 信号 **踩的坑**：动画 Stage 默认 `loop=true`（浏览器里方便看效果）。`render-video.js` 录完 duration 秒还多等 300ms 缓冲才停止，这 300ms 让 Stage 进入下一循环。ffmpeg `-t DURATION` 截取时，最后 0.5-1s 落入下一循环——视频结尾突然回到第一帧（Scene 1），观众以为视频出 bug。 **根因**：录制脚本和 HTML 之间没有"我在录制"的握手协议。HTML 不知道自己被录，依然按浏览器交互场景循环。 **规则**： 1. **录制脚本**：在 `addInitScript` 里注入 `window.__recording = true`（先于 page goto）： ```js await recordCtx.addInitScript(() => { window.__recording = true; }); ``` 2. **Stage 组件**：识别这个信号，强制 loop=false： ```js const effectiveLoop = (typeof window !== 'undefined' && window.__recording) ? false : loop; // ... if (next >= duration) return effectiveLoop ? 0 : duration - 0.001; // ↑ 留 0.001 防止 Sprite end=duration 被关掉 ``` 3. **结尾 Sprite 的 fadeOut**：录制场景下应设 `fadeOut={0}`，否则视频末尾会渐变到透明/暗色——用户期望停在清晰的最后一帧，不是淡出。手写 HTML 时建议结尾 Sprite 都用 `fadeOut={0}`。 **参考实现**：`assets/animations.jsx` 的 Stage / `scripts/render-video.js` 都已内置握手。手写 Stage 必须实现 `__recording` 检测——否则录制必踩这个坑。 **验证**：导出 MP4 后 `ffmpeg -ss 19.8 -i video.mp4 -frames:v 1 end.png`，检查倒数 0.2 秒是否还是预期最后一帧，没有突然切换到另一个 scene。 ## 14. 60fps 视频默认用帧复制 —— minterpolate 兼容性差 **踩的坑**：`convert-formats.sh` 用 `minterpolate=fps=60:mi_mode=mci...` 生成的 60fps MP4，在 macOS QuickTime / Safari 部分版本下无法打开（一片黑或直接拒打）。VLC / Chrome 能打开。 **根因**：minterpolate 输出的 H.264 elementary stream 包含某些播放器解析有问题的 SEI / SPS 字段。 **规则**： - 默认 60fps 用简单 `fps=60` filter（帧复制），兼容性广（QuickTime/Safari/Chrome/VLC 都能开） - 高质量插帧用 `--minterpolate` flag 显式启用——但**必须本地测过**目标播放器再交付 - 60fps 标签价值是**上传平台的算法识别**（Bilibili / YouTube 上 60fps 标记会优先推流），实际感知流畅度对 CSS 动画来说提升微弱 - 加 `-profile:v high -level 4.0` 提升 H.264 通用兼容性 **`convert-formats.sh` 已默认改成兼容模式**。如果你需要插帧高质量，加 `--minterpolate` flag： ```bash bash convert-formats.sh input.mp4 --minterpolate ``` ## 15. `file://` + 外部 `.jsx` 的 CORS 陷阱 —— 单文件交付必须内联引擎 **踩的坑**：动画 HTML 里用 `<script type="text/babel" src="animations.jsx"></script>` 外部加载引擎。本机双击打开（`file://` 协议）→ Babel Standalone 走 XHR 拉 `.jsx` → Chrome 报 `Cross origin requests are only supported for protocol schemes: http, https, chrome, chrome-extension...` → 整页黑屏，不报 `pageerror` 只报 console error，很容易当"动画没触发"误诊。 启 HTTP server 也未必救得了——本机有全局代理时 `localhost` 也会走代理，返回 502 / 连接失败。 **规则**： - **单文件交付（双击打开即用的 HTML）** → `animations.jsx` 必须**内联**到 `<script type="text/babel">...</script>` 标签内，不要用 `src="animations.jsx"` - **多文件项目（起 HTTP server 演示）** → 可以外部加载，但交付时明确写清 `python3 -m http.server 8000` 命令 - 判断标准：交付给用户的是"HTML 文件"还是"带 server 的项目目录"？前者用内联 - Stage 组件 / animations.jsx 经常 200+ 行——贴进 HTML `<script>` 块完全可接受，别怕体积 **最小验证**：双击你生成的 HTML，**不要**通过任何 server 打开。如果 Stage 正常显示动画首帧，才算通过。 ## 16. 跨 scene 反色上下文 —— 画面内元素不要硬编码颜色 **踩的坑**：做多场景动画时，`ChapterLabel` / `SceneNumber` / `Watermark` 等**跨 scene 都出现**的元素，在组件里写死 `color: '#1A1A1A'`（深色文字）。前 4 个 scene 浅底 OK，到第 5 个黑底 scene 时"05"和水印直接消失——不报错、不触发任何检查、关键信息隐形。 **规则**： - **跨多 scene 复用的画面内元素**（chapter 标签 / scene 编号 / 时间码 / 水印 / 版权条）**禁止硬编码颜色值** - 改用三种方式之一： 1. **`currentColor` 继承**：元素只写 `color: currentColor`，父 scene 容器设 `color: 计算值` 2. **invert prop**：组件接受 `<ChapterLabel invert />` 手动切换深浅 3. **基于底色自动计算**：`color: contrast-color(var(--scene-bg))`（CSS 4 新 API，或 JS 判断） - 交付前用 Playwright 抽**每个 scene 的代表帧**，人眼过一遍"跨 scene 元素"是否都可见 这条坑的隐蔽性在于——**没有 bug 报警**。只有人眼或 OCR 能发现。 ## 17. 离线/无 CDN 的真·自包含 —— React/Babel 全内联，且引擎也要 transpile **踩的坑（2026-05 觅游宣传动画）**：动画 HTML 用 `<script src="https://unpkg.com/react...">` + `<script src=".../@babel/standalone">` 走 CDN。本机有全局代理，Playwright 录制时 chromium 连 unpkg / Google Fonts 全部 `net::ERR_CONNECTION_CLOSED`： 1. React/ReactDOM 没加载 → `window.React undefined` 2. Babel 没加载 → `<script type="text/babel">` 里的 JSX 当普通 JS 跑 → `Unexpected token '<'` 修了 React/Babel 后又踩第二个坑：**把 `animations.jsx` 引擎当普通 `<script>` 内联，依然报 `Unexpected token '<'` → `window.Animations is undefined`**。根因：**`animations.jsx` 引擎本身含 JSX**（`Stage`/`Sprite` 组件 `return (<div>...)`），它原设计是用 `<script type="text/babel">` 由 Babel 转译加载的。只 transpile 了 app 代码、忘了 transpile 引擎 → 引擎那段 JSX 没被编译。 **规则**（要做「双击即开 / 离线 / 能被 Playwright 录」的真自包含单文件时）： - **React + ReactDOM 本地内联**：`curl` 下载 `react.production.min.js`（~10KB）+ `react-dom.production.min.js`（~131KB）到本地，inline 进 `<script>`，不走 CDN - **构建期 Babel 预编译，运行期不带 Babel**：用 `@babel/standalone`（下载一次，仅构建用）在 node 里 `Babel.transform(src,{presets:['react']}).code`，把 JSX → `React.createElement`。**app 和 `animations.jsx` 引擎两段都要过 transform**——引擎含 JSX，漏了它必报 `Unexpected token '<'` - **字体改系统字体**：Google Fonts CDN 同样会被代理掐断。中文动画用 `'PingFang SC'`（sans）/ `'Songti SC'`（serif）系统字体，不依赖网络。`document.fonts.ready` 对系统字体立即 resolve，录制不卡 - **base64 内联图片素材**：`<img src="png/x.png">` 相对路径在 `file://` 能渲染，但要真便携（移动文件不丢图）就 base64 data URL 内联；背景大图先转 JPEG 压一下再 base64 - **构建模板化**：HTML 模板留 `__REACT__/__REACTDOM__/__ASSETS__/__ENGINE__` token + 一段 `type="text/jsx-source"` 的 app 源码，node 构建脚本读 token 注入（vendor 原样、引擎+app 过 Babel）→ 写出最终单文件。改动画只改模板重跑构建 **验证**：Playwright `page.evaluate(()=>({React:typeof window.React, Animations:typeof window.Animations}))`——两个都该是 `object`。任一 `undefined` → 对应 `<script>` 抛了错（多半是没 transpile 的 JSX）。 **和坑 #15 的关系**：#15 讲「单文件别用 `src=` 外链 `.jsx`（file:// CORS）」；本坑更进一步——连 React/Babel/字体的**远程 CDN 在受限网络下也会断**，要做到真自包含必须全内联 + 构建期 transpile。 ## 18. 【HyperFrames】CSS transition + class 切换在 seek 渲染下不确定 CSS `transition` 走的是墙钟，不是时间轴。逐帧 seek 渲染时每帧都是独立截图，transition 的中间态取决于「seek 到这帧时过了多久墙钟时间」——完全不确定，可能永远停在起始值，也可能随机停在中间。c3 迁移实测（2026-07-17）：`.watermark-br` 用 `transition: opacity 0.6s` + class 切换，seek 渲染下透明度不听话。 **修法**：渲染路径上的一切状态变化都用 tween 或 t 的纯函数表达。迁移老 demo 时全文搜 `transition:`，逐个改成 `render(t)` 里的 lerp；新写合成从一开始就不写 transition。hover 等交互态的 transition 无所谓（渲染时不触发）。 ## 19. 【HyperFrames】代理 tween 首帧不触发 —— 手动补 `render(0)` 用代理 tween 把 `render(t)` 挂进 GSAP timeline 时（老 demo 适配器路线），timeline 停在 t=0 的状态下 `onUpdate` 不一定被调用——首帧可能是 HTML 的静态未初始化状态而非 `render(0)` 的画面。 **修法**：注册 timeline 后手动同步调一次 `render(0)`。配方全文见 `references/hyperframes-backend.md`。 ## 20. 【HyperFrames】contrast 门与暗色电影风冲突 —— 用 `--no-contrast`，其余四门必须 0 error `npm run check` 的 contrast 门按 WCAG AA 4.5:1 检查所有文字。暗色 cinematic 设计里 16-40% 透明度的水印、mono 标签、装饰性文字是**刻意的**低对比（电影感的一部分），会成片报错，且框架没有逐元素豁免机制。c3 实测 42 个 contrast error 全部是设计本意。 **修法**：暗色电影风产出用 `npx hyperframes check --no-contrast`，lint/runtime/layout/motion 四门仍必须 0 error。**亮底信息型产出不要跳 contrast**——那种场景下的报错通常是真的可读性问题（可读性硬底线见 SKILL.md Fallback 节）。 ## 21. 【HyperFrames/GSAP】fromTo 的 immediateRender 幻影 —— 元素提前数秒出现 GSAP 的 `fromTo()` 默认 `immediateRender: true`：build timeline 时就把 from 态渲染到元素上。如果 from 态本身可见（`autoAlpha > 0`），元素会在它的 tween 开始前就出现在画面里——火花、点击圈、涟漪、扬尘这类「短促特效」最容易中招（B00 实测一次踩了 4 处：特效在归位时刻前几秒就挂在画面上）。 **修法**：所有 from 态可见的 `fromTo()` 显式加 `immediateRender: false`；或改成「set 初始隐藏 + to」。自查方式：渲染后抽每幕开头帧，看有没有「不该在场的特效元素」。 ## 22. 【镜头】3D/放大模式下文字发糊 —— 放大走 CSS zoom 不走 transform scale **症状**：用 `transform: scale()` 推近页面（尤其 3D perspective 模式下），文字发糊，倍率越高越糊，2x 以上不可交付。 **根因**：Chromium 按元素的**布局尺寸**栅格化，再把位图放大。scale 只放大位图。 **解法**（shotcraft 判例，全库最贵知识）：相机层的放大走 **CSS `zoom` 属性**（布局级缩放，按放大后尺寸重新 layout 并栅格化，文字任意倍率锐利）。坐标换算和完整公式见 `camera-language.md` §3.4、`gsap-recipes.md` §9.2。注意：`zoom` 每帧触发 re-layout，是「禁 tween 布局属性」的唯一合法例外，只许用在 `#world` 相机层；离线逐帧渲染下渲染时长变慢属正常，产物质量优先。配套：全页截图 2x 起，特写另备 4x 切片在推进期 6f 交叉淡入。 ## 23. 【镜头】perspective 被中间层打断 —— 3D 瞬间变平 **症状**：设好了 `perspective` + `preserve-3d`，渲出来完全没有 3D 感，所有层平贴。 **根因**：`#camera` 与 3D 子元素之间的**任何中间层**加了 `overflow: hidden`、`filter`、`opacity < 1`、`clip-path` 之一，都会创建新 stacking context，flatten 掉 preserve-3d。 **解法**：3D 模式下滤镜/透明度效果只加在**最内层元素**上；容器链上逐层检查上述四类属性。排查口诀：从 `#camera` 到出问题的元素，中间每一层都 `getComputedStyle` 查一遍这四项。 ## 24. 【镜头】pan 露边 —— 平移时露出画布外空白 **症状**：镜头平移/摇镜时画面边缘露出白边或黑边。 **根因**：`#world` 尺寸只做到和视口一样大，镜头一动就出界。 **解法**：`#world` 四周外扩 bleed ≥ 最大 pan 振幅 + 8% 安全边距（camera-language §3.3）。背景层/氛围层要跟着铺满 bleed 区，别只铺视口。自查：把 timeline seek 到每段 pan 的两个端点截图，看四边。 ## 快速自查清单（开工前 5 秒） - [ ] 每个 `position: absolute` 的父元素都有 `position: relative`？ - [ ] 动画里的特殊字符（`␣` `⌘` `emoji`）都在字体里存在？ - [ ] Grid/Flex 模板的 count 和 JS 数据的 length 一致？ - [ ] 场景切换之间有 cross-fade，没有 >0.3s 的纯空白？ - [ ] DOM 测量代码包在 `document.fonts.ready.then()` 里？ - [ ] `render(t)` 是 pure 的，或有明确的 reset 机制？ - [ ] 第 0 帧是完整初始状态，不是空白？ - [ ] 画面内没有「伪 chrome」装饰（进度条/时间码/底部署名条与 Stage scrubber 撞车）？ - [ ] 动画 tick 第一帧同步设 `window.__ready = true`？（用 animations.jsx 自带；手写 HTML 自己加） - [ ] Stage 检测 `window.__recording` 强制 loop=false？（手写 HTML 必加） - [ ] 结尾 Sprite 的 `fadeOut` 设为 0（视频末尾停清晰帧）？ - [ ] 60fps MP4 默认用帧复制模式（兼容性），高质量插帧才加 `--minterpolate`？ - [ ] 导出后抽第 0 帧 + 末帧验证是动画初始/最终状态？ - [ ] 涉及具体品牌（Stripe/Anthropic/Lovart/...）：走完了「品牌资产协议」（SKILL.md §1.a 五步）？有没有写 `brand-spec.md`？ - [ ] 单文件交付的 HTML：`animations.jsx` 是内联的，不是 `src="..."`？（file:// 下 external .jsx 会 CORS 黑屏） - [ ] 跨 scene 出现的元素（chapter 标签/水印/scene 编号）没有硬编码颜色？在每个 scene 底色下都可见？ - [ ] 要离线/真自包含：React+ReactDOM 本地内联、**app 和 `animations.jsx` 引擎都过 Babel transpile**、字体用系统字体？（见坑 #17；引擎含 JSX，漏 transpile 必报 `Unexpected token '<'`） - [ ] 【HyperFrames】渲染路径上没有 CSS `transition`？状态变化全是 tween 或 t 的纯函数？（坑 #18） - [ ] 【HyperFrames】代理 tween 场景注册后补了 `render(0)`？（坑 #19） - [ ] 【HyperFrames】check 过了？暗色电影风用 `--no-contrast`，其余四门 0 error？（坑 #20） - [ ] 【HyperFrames/GSAP】from 态可见的 `fromTo()` 全部加了 `immediateRender:false`？（坑 #21，B00 实测 4 处幻影） - [ ] 【镜头】3D/放大特写走了 CSS `zoom`，没有 scale 放大发糊？（坑 #22） - [ ] 【镜头】`#camera` 到 3D 元素的中间层没有 overflow/filter/opacity/clip-path？（坑 #23） - [ ] 【镜头】`#world` 外扩了 bleed，pan 端点截图四边无露白？（坑 #24） -
animations.md 7.6 KB
# Animations：时间轴动画引擎 做动画/motion design HTML时读这个。原理、用法、典型模式。 ## 核心模式：Stage + Sprite 我们的动画系统（`assets/animations.jsx`）提供一个时间轴驱动的引擎： - **`<Stage>`**：整个动画的容器，自动提供auto-scale（fit viewport）+ scrubber + play/pause/loop控制 - **`<Sprite start end>`**：时间片段。一个Sprite只在`start`到`end`这段时间内显示。内部可以通过`useSprite()` hook读取自己的本地进度`t` (0→1) - **`useTime()`**：读当前全局时间（秒） - **`Easing.easeInOut` / `Easing.easeOut` / ...**：缓动函数 - **`interpolate(t, from, to, easing?)`**：根据t插值 这套模式借鉴Remotion/After Effects思路，但轻量、零依赖。 ## 起手 ```html <script type="text/babel" src="animations.jsx"></script> <script type="text/babel"> const { Stage, Sprite, useTime, useSprite, Easing, interpolate } = window.Animations; function Title() { const { t } = useSprite(); // 本地进度 0→1 const opacity = interpolate(t, [0, 1], [0, 1], Easing.easeOut); const y = interpolate(t, [0, 1], [40, 0], Easing.easeOut); return ( <h1 style={{ opacity, transform: `translateY(${y}px)`, fontSize: 120, fontWeight: 900, }}> Hello. </h1> ); } function Scene() { return ( <Stage duration={10}> {/* 10秒动画 */} <Sprite start={0} end={3}> <Title /> </Sprite> <Sprite start={2} end={5}> <SubTitle /> </Sprite> {/* ... */} </Stage> ); } const root = ReactDOM.createRoot(document.getElementById('root')); root.render(<Scene />); </script> ``` ## 常用动画模式 ### 1. Fade In / Fade Out ```jsx function FadeIn({ children }) { const { t } = useSprite(); const opacity = interpolate(t, [0, 0.3], [0, 1], Easing.easeOut); return <div style={{ opacity }}>{children}</div>; } ``` **注意范围**：`[0, 0.3]`意思是在sprite的前30%时间完成渐入，后面保持opacity=1。 ### 2. Slide In ```jsx function SlideIn({ children, from = 'left' }) { const { t } = useSprite(); const progress = interpolate(t, [0, 0.4], [0, 1], Easing.easeOut); const offset = (1 - progress) * 100; const directions = { left: `translateX(-${offset}px)`, right: `translateX(${offset}px)`, top: `translateY(-${offset}px)`, bottom: `translateY(${offset}px)`, }; return ( <div style={{ transform: directions[from], opacity: progress, }}> {children} </div> ); } ``` ### 3. 打字效果（⚠️ 先分清两种场景，别用逐字蹦） 匀速逐字 Typewriter 是官方反例（best-practices「AI slop」清单：像老电影字幕）。按内容选正解： - **AI 输出**（token 流式涌现）→ Chunk Reveal：不规律块状涌现，见 `animation-best-practices.md` §4.5 / `gsap-recipes.md` §3.4 - **用户输入**（真人在输入框打字）→ 3f/字符 + 光标常亮转闪烁 + 偶发退格，见 `ui-demo-animation.md` 八式③ ### 4. 数字计数 ```jsx function CountUp({ from = 0, to = 100, duration = 0.6 }) { const { t } = useSprite(); const progress = interpolate(t, [0, duration], [0, 1], Easing.easeOut); const value = Math.floor(from + (to - from) * progress); return <span>{value.toLocaleString()}</span>; } ``` ### 5. 分段解释（典型教学动画） ```jsx function Scene() { return ( <Stage duration={20}> {/* Phase 1: 展示问题 */} <Sprite start={0} end={4}> <Problem /> </Sprite> {/* Phase 2: 展示思路 */} <Sprite start={4} end={10}> <Approach /> </Sprite> {/* Phase 3: 展示结果 */} <Sprite start={10} end={16}> <Result /> </Sprite> {/* 全程显示的字幕 */} <Sprite start={0} end={20}> <Caption /> </Sprite> </Stage> ); } ``` ## Easing函数 预设的easing curves： | Easing | 特性 | 用在 | |--------|------|------| | `linear` | 匀速 | 滚动字幕、持续动画 | | `easeIn` | 慢→快 | 退场消失 | | `easeOut` | 快→慢 | 入场出现 | | `easeInOut` | 慢→快→慢 | 位置变化 | | **`expoOut`** ⭐ | **指数缓出** | **Anthropic 级主 easing**（物理重量感）| | **`overshoot`** ⭐ | **弹性回弹** | **Toggle / 按钮弹出 / 强调交互** | | `spring` | 弹簧 | 交互反馈、几何体归位 | | `anticipation` | 先反向再正向 | 强调动作 | **默认主 easing 用 `expoOut`**（不是 `easeOut`）—— 见 `animation-best-practices.md` §2。 入场用 `expoOut`、出场用 `easeIn`、toggle 用 `overshoot`——Anthropic 级动画的基础规律。 ## 节奏和时长指南 ### 微交互（0.1-0.3秒） - 按钮hover - 卡片expand - Tooltip出现 ### UI过渡（0.3-0.8秒） - 页面切换 - 模态框出现 - 列表item加入 ### 叙事动画（2-10秒每段） - 概念解释的一个phase - 数据图表的reveal - 场景转换 ### 单段叙事动画最长不超过10秒 人类注意力有限。10秒讲一件事，讲完换下一件。 ## 设计动画的思考顺序 ### 1. 先有内容/故事，再有动画 **错误**：先想要做fancy动画，再塞内容进去 **正确**：先想清楚要传达什么信息，再用动画手段serve这个信息 动画是**signal**，不是**装饰**。一个fade-in强调的是"这里很重要，请看"——如果什么都fade-in，signal就失效。 ### 2. 分Scene写时间轴 ``` 0:00 - 0:03 问题出现（fade in） 0:03 - 0:06 问题放大/展开（zoom+pan） 0:06 - 0:09 解法出现（slide in from right） 0:09 - 0:12 解法展开说明（typewriter） 0:12 - 0:15 结果演示（counter up + chart reveal） 0:15 - 0:18 总结一句话（static，读3秒） 0:18 - 0:20 CTA或fade out ``` 写完时间轴再写组件。 ### 3. 资源先行 动画要用的图片/图标/字体**先**准备好。不要画到一半去找素材——打断节奏。 ## 常见问题 **动画卡顿** → 主要是layout thrashing。用`transform`和`opacity`，不要动`top`/`left`/`width`/`height`/`margin`。浏览器GPU加速`transform`。 **动画太快，看不清楚** → 人读一个汉字需要100-150ms，一个词300-500ms。如果你用文字讲故事，单句至少留3秒。 **动画太慢，观众无聊** → 有趣的视觉变化要密集。静态画面超过5秒就会闷。 **多个动画互相影响** → 用CSS的`will-change: transform`提前告诉浏览器这个元素会动，减少reflow。 **录制成视频** → 用 skill 自带工具链（一条命令出三种格式）：见 `video-export.md` - `scripts/render-video.js` — HTML → 25fps MP4（Playwright + ffmpeg） - `scripts/convert-formats.sh` — 25fps MP4 → 60fps MP4 + 优化 GIF - 想要更精确的帧渲染？让 render(t) 成为 pure function，见 `animation-pitfalls.md` 第 5 条 ## 和视频工具的配合 这个skill做的是**HTML动画**（在浏览器里跑的）。如果最终产出要作为视频素材： - **短动画/concept demo**：用这里的方法做HTML动画 → 屏幕录制 - **长视频/叙事**（5-20 分钟带解说）：走 SKILL.md Step 9.5 解说驱动管线（`voiceover-pipeline.md`），不外推给其他工具 - **motion graphics**：专业的After Effects/Motion Canvas更合适 ## 需要物理动画（spring / decay）时 不要引 Popmotion（CDN 在受限网络必挂，违反自包含原则，见 `animation-pitfalls.md` #17）。spring 需求走 GSAP：`elastic.out` / `back.out` 及自定义 springEase 映射见 `gsap-recipes.md` §1.2；落地余震用 dampedSettle 闭式解（`camera-language.md` §9）。 -
app-prototype.md 9.7 KB
# App / iOS 原型专属守则 · 完整操作手册 > 从 SKILL.md 下沉的完整版。SKILL.md 保留 7 条硬规则速查，本文件是每条规则的展开：架构选型、取图渠道与代码、AppPhone JSX 骨架、ios_frame 三步用法、品位锚点全表。 做 iOS/Android/移动 app 原型时（触发：「app 原型」「iOS mockup」「移动应用」「做个 app」），下面四条**覆盖**通用 placeholder 原则——app 原型是 demo 现场，静态摆拍和米白占位卡没有说服力。 ### 0. 架构选型（必先决定） **默认单文件 inline React**——所有 JSX/data/styles 直接写进主 HTML 的 `<script type="text/babel">...</script>` 标签，**不要**用 `<script src="components.jsx">` 外部加载。原因：`file://` 协议下浏览器把外部 JS 当跨 origin 拦截，强制用户起 HTTP server 违反「双击就能开」的原型直觉。引用本地图片必须 base64 内嵌 data URL，别假设有 server。 **拆外部文件只在两种情况**： - (a) 单文件 >1000 行难维护 → 拆成 `components.jsx` + `data.js`，同时明确交付说明（`python3 -m http.server` 命令 + 访问 URL） - (b) 需要多 subagent 并行写不同屏 → `index.html` + 每屏独立 HTML（`today.html`/`graph.html`...），iframe 聚合，每屏也都是自包含单文件 **选型速查**： | 场景 | 架构 | 交付方式 | |------|------|----------| | 单人做 4-6 屏原型（主流） | 单文件 inline | 一个 `.html` 双击开 | | 单人做大型 App（>10 屏） | 多 jsx + server | 附启动命令 | | 多 agent 并行 | 多 HTML + iframe | `index.html` 聚合，每屏独立可开 | ### 1. 先找真图，不是 placeholder 摆着 默认主动去取真实图片填充，不要画 SVG、不要拿米白卡摆着、不要等用户要求。常用渠道： | 场景 | 首选渠道 | |------|---------| | 美术/博物馆/历史内容 | Wikimedia Commons（公共领域）、Met Museum Open Access、Art Institute of Chicago API | | 通用生活/摄影 | Unsplash、Pexels（免版权） | | 用户本地已有素材 | `~/Downloads`、项目 `_archive/` 或用户配置的素材库 | Wikimedia 下载避坑（本机 curl 走代理 TLS 会炸，Python urllib 直接走得通）： ```python # 合规 User-Agent 是硬性要求，否则 429 UA = 'ProjectName/0.1 (https://github.com/you; you@example.com)' # 用 MediaWiki API 查真实 URL api = 'https://commons.wikimedia.org/w/api.php' # action=query&list=categorymembers 批量拿系列 / prop=imageinfo+iiurlwidth 取指定宽度 thumburl ``` **只有**当所有渠道都失败 / 版权不清 / 用户明确要求时，才退回诚实 placeholder（仍然不画烂 SVG）。 **真图诚实性测试**（关键）：取图之前先问自己——「如果去掉这张图，信息是否有损？」 | 场景 | 判断 | 动作 | |------|------|------| | 文章/Essay 列表的封面、Profile 页的风景头图、设置页的装饰 banner | 装饰，与内容无内在关联 | **不要加**。加了就是 AI slop，等同紫色渐变 | | 博物馆/人物内容的肖像、产品详情的实物、地图卡片的地点 | 内容本身，有内在关联 | **必须加** | | 图谱/可视化背景的极淡纹理 | 氛围，服从内容不抢戏 | 加，但 opacity ≤ 0.08 | **反例**：给文字 Essay 配 Unsplash「灵感图」、给笔记 App 配 stock photo 模特——都是 AI slop。取真图的许可不等于滥用真图的通行证。 ### 2. 交付形态：默认「平铺 + 可操作」，不要问用户 iOS App 原型的**默认交付形态就一种，不要再问用户「要平铺还是可操作」**：**平铺 4-6 个主界面，且每一台都能交互**。一眼看全貌（多台 iPhone 并排），又每台都能点 tab 切换、在界面上做基本操作（展开、切换、选中、打开弹层）。两个好处一次给齐，别让用户二选一。 | 维度 | 默认做法 | |------|---------| | **屏数** | 平铺 **4-6 个主界面**（覆盖 app 的核心功能面，不是随便摆几个）。多于 6 个抓最主要的 4-6 个，其余可在单台内通过 tab/导航到达 | | **布局** | 多台独立 iPhone 横向 `flexWrap` 并排，每台上方一行 italic 小字标签说明这是哪个界面 | | **每台交互** | 每台都是独立的迷你状态机：tab bar 可切、界面内按钮/卡片/开关可点、能弹 modal——不是静态摆拍 | **只有两种特例才偏离默认**（用户明确说了才走，否则一律默认）： - 用户明确「只要静态截图 / 不用能点 / 就看 layout」→ 退回纯静态 overview（每台只渲染 `ScreenComponent`，不挂状态机） - 用户明确「只演示一条流程 / 走一遍 onboarding / 单机 demo」→ 单台 `AppPhone` 走完整 flow **默认骨架**（平铺多台，每台各自一个带 state 的 AppPhone）： ```jsx // 每台 = 一个独立状态机，初始落在自己负责的主界面 function AppPhone({ initial }) { const [screen, setScreen] = React.useState(initial); const [modal, setModal] = React.useState(null); // 按 screen 渲染对应 ScreenComponent，传入 onTabChange/onOpen/onClose/onToggle 等 callback return ( <IosFrame> <ScreenComponent screen={screen} onTabChange={setScreen} onOpen={setModal} onClose={() => setModal(null)} /> </IosFrame> ); } // 平铺：4-6 台并排，每台 initial 落在不同主界面 <div style={{display: 'flex', gap: 32, flexWrap: 'wrap', padding: 48, alignItems: 'flex-start'}}> {mainScreens.map(s => ( <div key={s.id}> <div style={{fontSize: 13, color: '#666', marginBottom: 8, fontStyle: 'italic'}}>{s.label}</div> <AppPhone initial={s.id} /> </div> ))} </div> ``` Screen 组件接 callback props（`onTabChange`、`onOpen`、`onClose`、`onToggle`、`onAnnotation`），不硬编码状态。TabBar、按钮、作品卡、开关加 `cursor: pointer` + hover 反馈。每台落在不同主界面，但 tab 切换后能到达彼此——平铺给全貌，点击给纵深。 ### 3. 交付前跑真实点击测试 静态截图只能看 layout，交互 bug 要点过才发现。用 Playwright 跑 3 项最小点击测试：进入详情 / 关键标注点 / tab 切换。检查 `pageerror` 为 0 再交付。Playwright 可用 `npx playwright` 调用，或按本机全局安装路径（`npm root -g` + `/playwright`）。 ### 4. 品位锚点（pursue list，fallback 首选） 没有 design system 时默认往这些方向走，避免撞 AI slop： | 维度 | 首选 | 避免 | |------|------|------| | **字体** | 衬线 display（Newsreader/Source Serif/EB Garamond）+ `-apple-system` body | 全场 SF Pro 或 Inter——太像系统默认，没风格 | | **色彩** | 一个有温度的底色 + **单个** accent 贯穿全场（rust 橙/墨绿/深红）| 多色聚类（除非数据真的有 ≥3 个分类维度） | | **信息密度·克制型**（默认）| 少一层容器、少一个 border、少一个**装饰性** icon——给内容留气口 | 每条卡片都配无意义的 icon + tag + status dot | | **信息密度·高密度型**（例外）| 当产品核心卖点是「智能 / 数据 / 上下文感知」时（AI 工具、Dashboard、Tracker、Copilot、番茄钟、健康监测、记账类），每屏需**至少 3 处可见的产品差异化信息**：非装饰性数据、对话/推理片段、状态推断、上下文关联 | 只放一个按钮一个时钟——AI 的智能感没表达出来，跟普通 App 没区别 | | **细节签名** | 留一处「值得截图」的质感：极淡油画底纹 / serif 斜体引语 / 全屏黑底录音波形 | 到处平均用力，结果处处平淡 | **两条原则同时生效**： 1. 品位 = 一个细节做到 120%，其它做到 80%——不是所有地方都精致，而是在合适的地方足够精致 2. 减法是 fallback，不是普适律——产品核心卖点需要信息密度支撑时（AI / 数据 / 上下文感知类），加法优先于克制。详见下文「信息密度分型」 ### 5. iOS 设备框必须用 `assets/ios_frame.jsx`——禁止手写 Dynamic Island / status bar 做 iPhone mockup 时**硬性绑定** `assets/ios_frame.jsx`。这是已经对齐过 iPhone 15 Pro 精确规格的标准外壳：bezel、Dynamic Island（124×36、top:12、居中）、status bar（时间/信号/电池、两侧避让岛、vertical center 对齐岛中线）、Home Indicator、content 区 top padding 都处理好了。 **禁止在你的 HTML 里自己写**以下任何一项： - `.dynamic-island` / `.island` / `position: absolute; top: 11/12px; width: ~120; 居中的黑圆角矩形` - `.status-bar` with 手写的时间/信号/电池图标 - `.home-indicator` / 底部 home bar - iPhone bezel 的圆角外框 + 黑描边 + shadow 自己写 99% 会撞位置 bug——status bar 的时间/电池被岛挤压、或 content top padding 算错导致第一行内容盖在岛下。iPhone 15 Pro 的刘海是**固定 124×36 像素**，留给 status bar 两侧的可用宽度很窄，不是你凭空估的。 **用法（严格三步）**： ```jsx // 步骤 1: Read 本 skill 的 assets/ios_frame.jsx（相对本 SKILL.md 的路径） // 步骤 2: 把整个 iosFrameStyles 常量 + IosFrame 组件贴进你的 <script type="text/babel"> // 步骤 3: 你自己的屏组件包在 <IosFrame>...</IosFrame> 里，不碰 island/status bar/home indicator <IosFrame time="9:41" battery={85}> <YourScreen /> {/* 内容从 top 54 开始渲染，下边留给 home indicator，你不用管 */} </IosFrame> ``` **例外**：只有用户明确要求「假装是 iPhone 14 非 Pro 的刘海」「做 Android 不是 iOS」「自定义设备形态」时才绕过——此时读对应 `android_frame.jsx` 或修改 `ios_frame.jsx` 的常量，**不要**在项目 HTML 里另起一套 island/status bar。 -
apple-gallery-showcase.md 11 KB
# Apple Gallery Showcase · 画廊展示墙动画风格 > 灵感来源：Claude Design 官网 hero 视频 + 苹果产品页「作品墙」式陈列 > 实战出处：huashu-design 发布 hero v5 > 适用场景：**产品发布 hero 动画、skill 能力演示、作品集展示**——任何需要把「多件高质量产出」同时展陈并引导观众注意力的场景 --- ## 触发判断：什么时候用这个风格 **适合**： - 有10张以上真实产出要同屏展示（PPT、App、网页、信息图） - 观众是专业受众（开发者、设计师、产品经理），对「质感」敏感 - 希望传递的气质是「克制、展览式、高级、有空间感」 - 需要焦点和全局同时存在（看细节但不失整体） **不适合**： - 单产品聚焦（用 frontend-design 的产品 hero 模板） - 情绪向/故事性强的动画（用时间轴叙事模板） - 小屏幕 / 竖屏（倾斜视角在小画面上会糊） --- ## 核心视觉 Token ```css :root { /* 浅色画廊调板 */ --bg: #F5F5F7; /* 主画布底 — 苹果官网灰 */ --bg-warm: #FAF9F5; /* 温暖米白变体 */ --ink: #1D1D1F; /* 主字色 */ --ink-80: #3A3A3D; --ink-60: #545458; --muted: #86868B; /* 次级文字 */ --dim: #C7C7CC; --hairline: #E5E5EA; /* 卡片1px边框 */ --accent: #D97757; /* 赤陶橙 — Claude brand */ --accent-deep:#B85D3D; --serif-cn: "Noto Serif SC", "Songti SC", Georgia, serif; --serif-en: "Source Serif 4", "Tiempos Headline", Georgia, serif; --sans: "Inter", -apple-system, "PingFang SC", system-ui; --mono: "JetBrains Mono", "SF Mono", ui-monospace; } ``` **关键原则**： 1. **绝不用纯黑底**。黑底会让作品看起来像电影、不像「可以被采用的工作成果」 2. **赤陶橙是唯一色相accent**，其他全部是灰阶 + 白 3. **三字体栈**（serif英+serif中+sans+mono）营造「出版物」而非「互联网产品」的气质 --- ## 核心布局模式 ### 1. 悬浮卡片（整个风格的基本单元） ```css .gallery-card { background: #FFFFFF; border-radius: 14px; padding: 6px; /* 内边距是「装裱纸」 */ border: 1px solid var(--hairline); box-shadow: 0 20px 60px -20px rgba(29, 29, 31, 0.12), /* 主阴影，软且长 */ 0 6px 18px -6px rgba(29, 29, 31, 0.06); /* 第二层近光，制造浮感 */ aspect-ratio: 16 / 9; /* 统一 slide 比例 */ overflow: hidden; } .gallery-card img { width: 100%; height: 100%; object-fit: cover; border-radius: 9px; /* 比卡片圆角略小，视觉嵌套 */ } ``` **反面教材**：不要贴边瓷砖（无padding无border无shadow）——那是信息图密度表达，不是展览。 ### 2. 3D倾斜作品墙 ```css .gallery-viewport { position: absolute; inset: 0; overflow: hidden; perspective: 2400px; /* 深一些的透视，倾斜不夸张 */ perspective-origin: 50% 45%; } .gallery-canvas { width: 4320px; /* 画布 = 2.25× viewport */ height: 2520px; /* 留出pan空间 */ transform-origin: center center; transform: perspective(2400px) rotateX(14deg) /* 向后倾 */ rotateY(-10deg) /* 向左转 */ rotateZ(-2deg); /* 轻微倾斜，去掉太规整 */ display: grid; grid-template-columns: repeat(8, 1fr); gap: 40px; padding: 60px; } ``` **参数 sweet spot**： - rotateX: 10-15deg（再多就像开酒会 VIP 背景板） - rotateY: ±8-12deg（左右对称感） - rotateZ: ±2-3deg（「这不是机器摆的」的人味） - perspective: 2000-2800px（小于2000会鱼眼，大于3000接近正投影） ### 3. 2×2 四角汇聚（选择场景） ```css .grid22 { display: grid; grid-template-columns: repeat(2, 800px); gap: 56px 64px; align-items: start; } ``` 每张卡片从对应角落（tl/tr/bl/br）向中心滑入 + fade in。对应的 `cornerEntry` 向量： ```js const cornerEntry = { tl: { dx: -700, dy: -500 }, tr: { dx: 700, dy: -500 }, bl: { dx: -700, dy: 500 }, br: { dx: 700, dy: 500 }, }; ``` --- ## 五种核心动画模式 ### 模式 A · 四角汇聚（0.8-1.2s） 4 个元素从视口四角滑入，同时缩放 0.85→1.0，对应 ease-out。适合「展示多方向选择」的开场。 ```js const inP = easeOut(clampLerp(t, start, end)); card.style.transform = `translate3d(${(1-inP)*ce.dx}px, ${(1-inP)*ce.dy}px, 0) scale(${0.85 + 0.15*inP})`; card.style.opacity = inP; ``` ### 模式 B · 选中放大 + 其他滑出（0.8s） 被选中的卡片放大 1.0→1.28，其他卡片 fade out + blur + 向四角漂回： ```js // 被选中 card.style.transform = `translate3d(${cellDx*outP}px, ${cellDy*outP}px, 0) scale(${1 + 0.28*easeOut(zoomP)})`; // 未选中 card.style.opacity = 1 - outP; card.style.filter = `blur(${outP * 1.5}px)`; ``` **关键**：未选中的要 blur，不是纯 fade。blur 模拟景深，视觉上把被选中的「推出来」。 ### 模式 C · Ripple 涟漪展开（1.7s） 从中心向外，按距离 delay，每张卡片依次淡入 + 从 1.25x 缩到 0.94x（「镜头拉远」）： ```js const col = i % COLS, row = Math.floor(i / COLS); const dc = col - (COLS-1)/2, dr = row - (ROWS-1)/2; const dist = Math.sqrt(dc*dc + dr*dr); const delay = (dist / maxDist) * 0.8; const localT = Math.max(0, (t - rippleStart - delay) / 0.7); card.style.opacity = easeOut(Math.min(1, localT)); // 同时整体 scale 1.25→0.94 const galleryScale = 1.25 - 0.31 * easeOut(rippleProgress); ``` ### 模式 D · Sinusoidal Pan（持续漂移） 用正弦波 + 线性漂移组合，避免 marquee 那种「有起点有终点」的循环感： ```js const panX = Math.sin(panT * 0.12) * 220 - panT * 8; // 横向左漂 const panY = Math.cos(panT * 0.09) * 120 - panT * 5; // 纵向上漂 const clampedX = Math.max(-900, Math.min(900, panX)); // 防止露边 ``` **参数**： - 正弦周期 `0.09-0.15 rad/s`（慢，约30-50秒一个摆动） - 线性漂移 `5-8 px/s`（比观众眨眼慢） - 振幅 `120-220 px`（大到能感觉，小到不会晕） ### 模式 E · Focus Overlay（焦点切换） **关键设计**：focus overlay 是一个**平面元素**（不倾斜），浮在倾斜画布之上。被选中的 slide 从瓦片位置（约400×225）缩放到屏幕中央（960×540），背景画布不倾斜变化但**变暗到 45%**： ```js // Focus overlay (flat, centered) focusOverlay.style.width = (startW + (endW - startW) * focusIntensity) + 'px'; focusOverlay.style.height = (startH + (endH - startH) * focusIntensity) + 'px'; focusOverlay.style.opacity = focusIntensity; // 背景卡片变暗，但依然可见（关键！不要100%遮罩） card.style.opacity = entryOp * (1 - 0.55 * focusIntensity); // 1 → 0.45 card.style.filter = `brightness(${1 - 0.3 * focusIntensity})`; ``` **清晰度铁律**： - Focus overlay 的 `<img>` 必须 `src` 直连原图，**不要复用 gallery 里的压缩缩略** - 提前 preload 所有原图到 `new Image()[]` 数组 - overlay 自身 `width/height` 按帧计算，浏览器每帧 resample 原图 --- ## 时间轴架构（可复用骨架） ```js const T = { DURATION: 25.0, s1_in: [0.0, 0.8], s1_type: [1.0, 3.2], s1_out: [3.5, 4.0], s2_in: [3.9, 5.1], s2_hold: [5.1, 7.0], s2_out: [7.0, 7.8], s3_hold: [7.8, 8.3], s3_ripple: [8.3, 10.0], panStart: 8.6, focuses: [ { start: 11.0, end: 12.7, idx: 2 }, { start: 13.3, end: 15.0, idx: 3 }, { start: 15.6, end: 17.3, idx: 10 }, { start: 17.9, end: 19.6, idx: 16 }, ], s4_walloff: [21.1, 21.8], s4_in: [21.8, 22.7], s4_hold: [23.7, 25.0], }; // 核心 easing（v9 历史实现用 cubic；新项目主 easing 默认 expoOut，见 best-practices §2 / hero-case-study 模式1 的修正） const easeOut = t => 1 - Math.pow(1 - t, 3); const easeInOut = t => t < 0.5 ? 4*t*t*t : 1 - Math.pow(-2*t+2, 3)/2; function lerp(time, start, end, fromV, toV, easing) { if (time <= start) return fromV; if (time >= end) return toV; let p = (time - start) / (end - start); if (easing) p = easing(p); return fromV + (toV - fromV) * p; } // 单一 render(t) 函数读时间戳、写所有元素 function render(t) { /* ... */ } requestAnimationFrame(function tick(now) { const t = ((now - startMs) / 1000) % T.DURATION; render(t); requestAnimationFrame(tick); }); ``` **架构精髓**：**所有状态由时间戳 t 推导**，没有状态机、没有 setTimeout。这样： - 播放到任意时刻 `window.__setTime(12.3)` 立刻跳转（方便 playwright 逐帧截） - 循环天然无缝（t mod DURATION） - Debug 时能冻结任意一帧 --- ## 质感细节（容易被忽略但致命） ### 1. SVG noise texture 浅色底最怕「太平」。叠加一层极弱的 fractalNoise： ```html <style> .stage::before { content: ''; position: absolute; inset: 0; background-image: url("data:image/svg+xml;utf8,<svg xmlns='http://www.w3.org/2000/svg' width='200' height='200'><filter id='n'><feTurbulence type='fractalNoise' baseFrequency='0.85' numOctaves='2' stitchTiles='stitch'/><feColorMatrix values='0 0 0 0 0.078 0 0 0 0 0.078 0 0 0 0 0.074 0 0 0 0.035 0'/></filter><rect width='100%' height='100%' filter='url(%23n)'/></svg>"); opacity: 0.5; pointer-events: none; z-index: 30; } </style> ``` 看上去没区别，去掉就知道有了。 ### 2. 角落品牌标识 ```html <div class="corner-brand"> <div class="mark"></div> <div>HUASHU · DESIGN</div> </div> ``` ```css .corner-brand { position: absolute; top: 48px; left: 72px; font-family: var(--mono); font-size: 12px; letter-spacing: 0.22em; text-transform: uppercase; color: var(--muted); } ``` 只在作品墙 scene 显示，淡入淡出。像美术馆展签。 ### 3. 品牌收束 wordmark ```css .brand-wordmark { font-family: var(--sans); font-size: 148px; font-weight: 700; letter-spacing: -0.045em; /* 负字距是关键，让字紧凑成标志 */ } .brand-wordmark .accent { color: var(--accent); font-weight: 500; /* accent字符反而细一点，视觉差 */ } ``` `letter-spacing: -0.045em` 是苹果产品页大字的标准做法。 --- ## 常见失败模式 | 症状 | 原因 | 解法 | |---|---|---| | 看起来像 PPT 模板 | 卡片没有 shadow / hairline | 加上两层 box-shadow + 1px border | | 倾斜感廉价 | 只用了 rotateY 没加 rotateZ | 加 ±2-3deg rotateZ 打破工整 | | Pan 感觉「卡顿」 | 用了 setTimeout 或 CSS keyframes 循环 | 用 rAF + sin/cos 连续函数 | | Focus 时字看不清 | 复用了 gallery 瓦片的低分图 | 独立 overlay + 原图 src 直连 | | 背景太空 | 纯色 `#F5F5F7` | 叠加 SVG fractalNoise 0.5 opacity | | 字体太"互联网" | 只有 Inter | 加 Serif（中英各一）+ mono 三栈 | --- ## 引用 - 完整实现样本：hero-animation-v5.html（作者本地样本，未随仓库分发） - 原始灵感：claude.ai/design hero 视频 - 参考审美：Apple 产品页、Dribbble shot 集合页 遇到「多件高质量产出要陈列」的动画需求，直接从此文件 copy 骨架，换内容 + 调 timing 即可。 -
audio-design-rules.md 9.4 KB
# 音频设计规则 · huashu-design > 所有动画 demo 的音频应用配方。和 `sfx-library.md`（资产清单）配套使用。 > 实战锤炼：huashu-design 发布 hero v1-v9 迭代 · Anthropic 三支官方片子的 Gemini 深度拆解 · 8000+ 次 A/B 对比 --- ## 核心原则 · 音频双轨制（铁律） 动画音频**必须分两层独立设计**，不能只做一层： | 层 | 作用 | 时间尺度 | 和视觉的关系 | 占据频段 | |---|---|---|---|---| | **SFX（节拍层）** | 标记每个视觉 beat | 0.2-2 秒短促 | **强同步**（帧级对齐） | **高频 800Hz+** | | **BGM（氛围底）** | 情绪铺底、声场 | 连续 20-60 秒 | 弱同步（段落级） | **中低频 <4kHz** | **只做BGM的动画是残废的**——观众潜意识感知到「画在动但没声音响应」，廉价感的根源就在这里。 --- ## 金标准 · 黄金配比 这几组数值是实测 Anthropic 三支官方片子 + 我们自己 v9 定版对比得出的**工程硬参数**，直接套用即可： ### 音量 - **BGM 音量**：`0.40-0.50`（相对满刻度 1.0） - **SFX 音量**：`1.00` - **响度差**：BGM 比 SFX peak **低 -6 到 -8 dB**（不是靠SFX绝对响度突出，靠响度差） - **amix 参数**：`normalize=0`（绝不用 normalize=1，会把动态范围压平） ### 频段隔离（P1 硬优化） Anthropic 的秘诀不是「SFX 音量大」，是**频段分层**： ```bash [bgm_raw]lowpass=f=4000[bgm] # BGM 限制在 <4kHz 的中低频 [sfx_raw]highpass=f=800[sfx] # SFX 推到 800Hz+ 的中高频 [bgm][sfx]amix=inputs=2:duration=first:normalize=0[a] ``` 为什么：人耳对 2-5kHz 区间最敏感（即「presence 频段」），SFX 如果都在这个区间，BGM 又全频段覆盖，**SFX 会被BGM的高频部分遮盖**。用 highpass 把 SFX 推高 + lowpass 把 BGM 压下，两者在频谱上各占一方，SFX 清晰度直接上一档。 ### Fade - BGM 入：`afade=in:st=0:d=0.3`（0.3s，避免硬切） - BGM 出：`afade=out:st=N-1.5:d=1.5`（1.5s 长尾，收束感） - SFX 自带 envelope，不需要额外 fade --- ## SFX cue 设计规则 ### 密度（每10秒多少个SFX） 实测 Anthropic 三支片子的 SFX 密度有三档： | 片子 | 每10s SFX 数 | 产品性格 | 场景 | |---|---|---|---| | Artifacts（ref-1） | **~9个/10s** | 功能密集、信息多 | 复杂工具演示 | | Code Desktop（ref-2） | **0个** | 纯氛围、冥想感 | 开发工具专注状态 | | Word（ref-3） | **~4个/10s** | 平衡、办公节奏 | 生产力工具 | **启发式**： - 产品性格冷静/专注 → SFX 密度低（0-3个/10s），BGM 为主 - 产品性格活泼/信息多 → SFX 密度高（6-9个/10s），SFX 驱动节奏 - **不要填满每个视觉 beat**——留白比密集更高级。**删掉 30-50% 的 cue 会让剩下的更有戏剧性**。 ### Cue 选择优先级 每个视觉 beat 不都要配 SFX。按这个优先级选： **P0 必配**（省略会有违和感）： - 打字（终端/输入） - 点击/选择（用户决策时刻） - 焦点切换（视觉主角转移） - Logo reveal（品牌收束） **P1 推荐配**： - 元素入场/离场（modal / card） - 完成/成功反馈 - AI 生成开始/结束 - 重大过渡（scene 切换） **P2 选配**（多了会乱）： - hover / focus-in - 进度 tick - 装饰性 ambient ### 时间戳对齐精度 - **同帧对齐**（0ms 误差）：点击/焦点切换/Logo 落定 - **前置 1-2 帧**（-33ms）：快速 whoosh（给观众心理预期） - **后置 1-2 帧**（+33ms）：物体落地/impact（符合真实物理） --- ## BGM 选择决策树 huashu-design skill 自带 6 首 BGM（`assets/bgm-*.mp3`）： ``` 动画性格是什么？ ├─ 产品发布 / 技术演示 → bgm-tech.mp3（minimal synth + piano） ├─ 教程讲解 / 工具使用 → bgm-tutorial.mp3（warm, instructional） ├─ 教育学习 / 原理解释 → bgm-educational.mp3（curious, thoughtful） ├─ 营销广告 / 品牌宣传 → bgm-ad.mp3（upbeat, promotional） └─ 同类风格需要变体 → bgm-*-alt.mp3（各自替代版） ``` ### 无 BGM 的场景（值得考虑） 参考 Anthropic Code Desktop（ref-2）：**0 SFX + 纯 Lo-fi BGM** 也能很高级。 **何时选无BGM**： - 动画时长 <10s（BGM 建立不起来） - 产品性格是「专注/冥想」 - 场景本身有环境音/讲解声 - SFX 密度很高时（避免听觉过载） --- ## 场景配方（开箱即用） ### 配方 A · 产品发布 hero（huashu-design v9 同款） ``` 时长：25 秒 BGM：bgm-tech.mp3 · 45% · 频段 <4kHz SFX 密度：~6个/10s cue： 终端打字 → type × 4（间隔0.6s） 回车 → enter 卡片汇聚 → card × 4（错峰 0.2s） 选中 → click Ripple → whoosh 4次焦点 → focus × 4 Logo → thud（1.5s） 音量：BGM 0.45 / SFX 1.0 · amix normalize=0 ``` ### 配方 B · 工具功能演示（参考 Anthropic Code Desktop） ``` 时长：30-45 秒 BGM：bgm-tutorial.mp3 · 50% SFX 密度：0-2个/10s（极少） 策略：让 BGM + 讲解 voiceover 驱动，SFX 只在**决定性时刻**（文件保存/命令执行完成） ``` ### 配方 C · AI 生成演示 ``` 时长：15-20 秒 BGM：bgm-tech.mp3 或无 BGM SFX 密度：~8个/10s（高密度） cue： 用户输入 → type + enter AI 开始处理 → magic/ai-process（1.2s 循环） 生成完成 → feedback/complete-done 结果呈现 → magic/sparkle 亮点：ai-process 可以循环 2-3 次贯穿整个生成过程 ``` ### 配方 D · 纯氛围长镜头（参考 Artifacts） ``` 时长：10-15 秒 BGM：无 SFX：单独使用 3-5 个精心设计的 cue 策略：每个 SFX 都是主角，没有BGM「糊在一起」的问题。 适合：单产品慢镜头、特写展示 ``` --- ## ffmpeg 合成模板 ### 模板 1 · 单 SFX 叠加到视频 ```bash ffmpeg -y -i video.mp4 -itsoffset 2.5 -i sfx.mp3 \ -filter_complex "[0:a][1:a]amix=inputs=2:normalize=0[a]" \ -map 0:v -map "[a]" output.mp4 ``` ### 模板 2 · 多 SFX 时间轴合成（按cue时间对齐） ```bash ffmpeg -y \ -i sfx-type.mp3 -i sfx-enter.mp3 -i sfx-click.mp3 -i sfx-thud.mp3 \ -filter_complex "\ [0:a]adelay=1100|1100[a0];\ [1:a]adelay=3200|3200[a1];\ [2:a]adelay=7000|7000[a2];\ [3:a]adelay=21800|21800[a3];\ [a0][a1][a2][a3]amix=inputs=4:duration=longest:normalize=0[mixed]" \ -map "[mixed]" -t 25 sfx-track.mp3 ``` **关键参数**： - `adelay=N|N`：前面是左声道延迟(ms)，后面是右声道，写两遍保证立体声对齐 - `normalize=0`：保留动态范围，关键！ - `-t 25`：截断到指定时长 ### 模板 3 · 视频 + SFX track + BGM（带频段隔离） ```bash ffmpeg -y -i video.mp4 -i sfx-track.mp3 -i bgm.mp3 \ -filter_complex "\ [2:a]atrim=0:25,afade=in:st=0:d=0.3,afade=out:st=23.5:d=1.5,\ lowpass=f=4000,volume=0.45[bgm];\ [1:a]highpass=f=800,volume=1.0[sfx];\ [bgm][sfx]amix=inputs=2:duration=first:normalize=0[a]" \ -map 0:v -map "[a]" -c:v copy -c:a aac -b:a 192k final.mp4 ``` --- ## 失败模式速查 | 症状 | 根因 | 修复 | |---|---|---| | SFX 听不见 | BGM 高频部分遮盖 | 加 `lowpass=f=4000` 给BGM + `highpass=f=800` 给SFX | | 音效过响刺耳 | SFX 绝对音量太大 | SFX 音量降到 0.7，同时降低 BGM 到 0.3，保持差值 | | BGM 和 SFX 节奏冲突 | BGM 选错了（用了有强beat的music） | 换成 ambient / minimal synth 的 BGM | | 动画结束 BGM 突然断 | 没做 fade out | `afade=out:st=N-1.5:d=1.5` | | SFX 重叠成糊 | cue 太密 + 每个 SFX 时长太长 | SFX 时长控到 0.5s 以内，cue 间隔 ≥ 0.2s | | 公众号 mp4 没声音 | 公众号有时会 mute auto-play | 不用担心，用户点开会有声音；gif 本来就没声音 | --- ## 和视觉的联动（高级） ### SFX 音色要和视觉风格匹配 - 暖米/纸张感视觉 → SFX 用**木质/柔和**音色（Morse, paper snap, soft click） - 冷黑科技视觉 → SFX 用**金属/数字**音色（beep, pulse, glitch） - 手绘/童趣视觉 → SFX 用**卡通/夸张**音色（boing, pop, zap） 我们当前 `apple-gallery-showcase.md` 的暖米底色 → 搭配 `keyboard/type.mp3`（mechanical）+ `container/card-snap.mp3`（soft）+ `impact/logo-reveal-v2.mp3`（cinematic bass） ### SFX 可以引导视觉节奏 高级技巧：**先设计 SFX 时间轴，然后调整视觉动画去对齐 SFX**（不是反过来）。 因为 SFX 每个 cue 都是一个「钟表 tick」，视觉动画适配 SFX 节奏会非常稳——反之 SFX 去追视觉，常常 ±1 帧对不上就有违和感。 --- ## 质量检查清单（发布前自检） - [ ] 响度差：SFX peak - BGM peak = -6 到 -8 dB？ - [ ] 频段：BGM lowpass 4kHz + SFX highpass 800Hz？ - [ ] amix normalize=0（保留动态范围）？ - [ ] BGM fade-in 0.3s + fade-out 1.5s？ - [ ] SFX 数量是否合适（按场景性格选密度）？ - [ ] 每个 SFX 和视觉 beat 同帧对齐（±1 帧内）？ - [ ] Logo reveal 音效时长够（建议 1.5s）？ - [ ] 关闭 BGM 听一遍：SFX 单独是否足够有节奏感？ - [ ] 关闭 SFX 听一遍：BGM 单独是否有情绪起伏？ 两层任何一层单独听都应该自洽。如果只有两层叠加才好听，说明没做好。 --- ## 参考 - SFX 资产清单：`sfx-library.md` - 视觉风格参考：`apple-gallery-showcase.md` - Anthropic 三支片子深度音频分析：AUDIO-BEST-PRACTICES.md（作者本地资料，未随仓库分发） - huashu-design v9 实战案例：hero-animation-v9-final.mp4（作者本地样本，未随仓库分发） -
brand-asset-protocol.md 15.1 KB
# 核心资产协议（完整版） > 从 SKILL.md「核心哲学 #1.a」下沉的完整协议（2026-06 瘦身）。SKILL.md 留了触发条件 + 5 步标题 + 自检；这里是 5 步详细操作、下载命令、brand-spec 模板、全流程失败兜底、反例与代价对比。 > 触发：任务涉及具体品牌/产品时强制执行。回 SKILL.md 看精简版与上下文。 #### 1.a 核心资产协议（涉及具体品牌时强制执行） > **这是 v1 最核心的约束，也是稳定性的生命线。** Agent 是否走通这个协议，直接决定输出质量是 40 分还是 90 分。不要跳过任何一步。 > > **v1.1 重构（2026-04-20）**：从「品牌资产协议」升级为「核心资产协议」。之前的版本过度聚焦色值和字体，漏掉了设计中最基础的 logo / 产品图 / UI 截图。花叔的原话：「除了所谓的品牌色，显然我们应该找到并且用上大疆的 logo，用上 pocket4 的产品图。如果是网站或者 app 等非实体产品的话，logo 至少该是必须的。这可能是比所谓的品牌设计的 spec 更重要的基本逻辑。否则，我们在表达什么呢？」 **触发条件**：任务涉及具体品牌——用户提了产品名/公司名/明确客户（Stripe、Linear、Anthropic、Notion、Lovart、DJI、自家公司等），不论用户是否主动提供了品牌资料。 **前置硬条件**：走协议前必须已通过「#0 事实验证先于假设」确认品牌/产品存在且状态已知。如果你还不确定产品是否已发布/规格/版本，先回去搜。 ##### 核心理念：资产 > 规范 **品牌的本质是「它被认出来」**。认出来靠什么？按识别度排序： | 资产类型 | 识别度贡献 | 必需性 | |---|---|---| | **Logo** | 最高 · 任何品牌出现 logo 就一眼识别 | **任何品牌都必须有** | | **产品图/产品渲染图** | 极高 · 实体产品的"主角"就是产品本身 | **实体产品（硬件/包装/消费品）必须有** | | **UI 截图/界面素材** | 极高 · 数字产品的"主角"是它的界面 | **数字产品（App/网站/SaaS）必须有** | | **色值** | 中 · 辅助识别，脱离前三项时经常撞衫 | 辅助 | | **字体** | 低 · 需配合前述才能建立识别 | 辅助 | | **气质关键词** | 低 · agent 自检用 | 辅助 | **翻译成执行规则**： - 只抽色值 + 字体、不找 logo / 产品图 / UI → **违反本协议** - 用 CSS 剪影/SVG 手画替代真实产品图 → **违反本协议**（生成的就是「通用科技动画」，任何品牌都长一样） - 找不到资产不告诉用户、也不 AI 生成，硬做 → **违反本协议** - 宁可停下问用户要素材，也不要用 generic 填充 ##### 5 步硬流程（每步有 fallback，绝不静默跳过） ##### Step 1 · 问（资产清单一次问全） 不要只问「有 brand guidelines 吗？」——太宽泛，用户不知道该给什么。按清单逐项问： ``` 关于 <brand/product>，你手上有以下哪些资料？我按优先级列： 1. Logo（SVG / 高清 PNG）—— 任何品牌必备 2. 产品图 / 官方渲染图 —— 实体产品必备（如 DJI Pocket 4 的产品照） 3. UI 截图 / 界面素材 —— 数字产品必备（如 App 主要页面截图） 4. 色值清单（HEX / RGB / 品牌色盘） 5. 字体清单（Display / Body） 6. Brand guidelines PDF / Figma design system / 品牌官网链接 有的直接发我，没有的我去搜/抓/生成。 ``` ##### Step 2 · 搜官方渠道（按资产类型） | 资产 | 搜索路径 | |---|---| | **Logo** | `<brand>.com/brand` · `<brand>.com/press` · `<brand>.com/press-kit` · `brand.<brand>.com` · 官网 header 的 inline SVG | | **产品图/渲染图** | `<brand>.com/<product>` 产品详情页 hero image + gallery · 官方 YouTube launch film 截帧 · 官方新闻稿附图 | | **UI 截图** | App Store / Google Play 产品页截图 · 官网 screenshots section · 产品官方演示视频截帧 | | **色值** | 官网 inline CSS / Tailwind config / brand guidelines PDF | | **字体** | 官网 `<link rel="stylesheet">` 引用 · Google Fonts 追踪 · brand guidelines | `WebSearch` 兜底关键词： - Logo 找不到 → `<brand> logo download SVG`、`<brand> press kit` - 产品图找不到 → `<brand> <product> official renders`、`<brand> <product> product photography` - UI 找不到 → `<brand> app screenshots`、`<brand> dashboard UI` ##### Step 3 · 下载资产 · 按类型三条兜底路径 **3.1 Logo（任何品牌必需）** > ⚠️ **别只试 `curl <brand>.com/logo.svg` 就放弃**——现在的官网大多是 SPA，直连静态路径基本返回空壳 HTML（2026-06-06 实测 Trae 官网 5 条直连路径全是空壳）。**数字产品 / SaaS / AI 工具优先用图标聚合源**，命中率最高、直出干净 SVG。 按成功率递减： 0. **图标聚合源（知名数字产品/SaaS/AI 工具首选，命中率最高）**： ```bash unset ALL_PROXY HTTP_PROXY HTTPS_PROXY all_proxy http_proxy https_proxy # 清代理，否则 TLS 易炸 # svgl —— AI/开发者品牌覆盖最全（Claude/Cursor/OpenAI/Copilot/Anthropic/Vercel…），含 light/dark + wordmark curl -s "https://api.svgl.app?search=<brand>" # 返回 JSON，取 route(.light/.dark) 的 svg URL 再下载 # simpleicons —— 单色 glyph，可直接按品牌色上色 curl -o logo.svg "https://cdn.simpleicons.org/<slug>/<hexcolor>" ``` 1. 独立 SVG/PNG 文件 / 官方 brand 页（如 `<brand>.com/brand`、`/press`）： ```bash curl -A "Mozilla/5.0" -L -o assets/<brand>-brand/logo.svg "<official-logo-url>" ``` 2. 官网 HTML 全文提取 inline SVG： ```bash curl -A "Mozilla/5.0" -L https://<brand>.com -o assets/<brand>-brand/homepage.html # 然后 grep <svg>...</svg> 提取 logo 节点 ``` 3. **Google favicon 服务（站点真实 mark 兜底，几乎不失败）**： ```bash curl -o logo.png "https://www.google.com/s2/favicons?domain=<brand-domain>&sz=256" # 256px 官方站点图标 ``` 4. 官方社交媒体 avatar（最后手段）：GitHub/Twitter/LinkedIn 的公司头像通常是 400×400 或 800×800 透明底 PNG 下载后**逐个核对**：`file <logo>` 确认是真 SVG/PNG（不是 106 字节占位或 HTML 空壳），`head -c 90 <logo.svg>` 看是否 `<svg`。 **3.2 产品图/渲染图（实体产品必需）** 按优先级： 1. **官方产品页 hero image**（最高优先级）：右键查看图片地址 / curl 获取。分辨率通常 2000px+ 2. **官方 press kit**：`<brand>.com/press` 常有高清产品图下载 3. **官方 launch video 截帧**：用 `yt-dlp` 下载 YouTube 视频，ffmpeg 抽几帧高清图 4. **Wikimedia Commons**：公共领域常有 5. **AI 生成兜底**（nano-banana-pro）：把真实产品图作为参考发给 AI，让它生成符合动画场景的变体。**不要用 CSS/SVG 手画代替** ```bash # 示例：下载 DJI 官网产品 hero image curl -A "Mozilla/5.0" -L "<hero-image-url>" -o assets/<brand>-brand/product-hero.png ``` **3.3 UI 截图（数字产品必需）** - App Store / Google Play 的产品截图（注意：可能是 mockup 而非真实 UI，要对比） - 官网 screenshots section - 产品演示视频截帧 - 产品官方 Twitter/X 的发布截图（常是最新版本） - 用户有账号时，直接截屏真实产品界面 **3.4 · 素材质量门槛「5-10-2-8」原则（铁律）** > **Logo 的规则不同于其他素材**。Logo 有就必须用（没有就停下问用户）；其他素材（产品图/UI/参考图/配图）遵循「5-10-2-8」质量门槛。 > > 2026-04-20 花叔原话：「我们的原则是搜索 5 轮，找到 10 个素材，选择 2 个好的。每个需要评分 8/10 以上，宁可少一些，也不为了完成任务滥竽充数。」 | 维度 | 标准 | 反模式 | |---|---|---| | **5 轮搜索** | 多渠道交叉搜（官网 / press kit / 官方社媒 / YouTube 截帧 / Wikimedia / 用户账号截屏），不是一轮抓前 2 个就停 | 第一页结果直接用 | | **10 个候选** | 至少凑 10 个备选才开始筛 | 只抓 2 个，没得选 | | **选 2 个好的** | 从 10 个里精选 2 个作为最终素材 | 全都用 = 视觉过载 + 品位稀释 | | **每个 8/10 分以上** | 不够 8 分**宁可不用**，用诚实 placeholder（灰块+文字标签）或 AI 生成（nano-banana-pro 以官方参考为基底）| 凑数 7 分素材进 brand-spec.md | **8/10 评分维度**（打分时记录在 `brand-spec.md`）： 1. **分辨率** · ≥2000px（印刷/大屏场景 ≥3000px） 2. **版权清晰度** · 官方来源 > 公共领域 > 免费素材 > 疑似盗图（疑似盗图直接 0 分） 3. **与品牌气质契合度** · 和 brand-spec.md 里的「气质关键词」一致 4. **光线/构图/风格一致性** · 2 个素材放一起不打架 5. **独立叙事能力** · 能单独表达一个叙事角色（不是装饰） **为什么这个门槛是铁律**： - 花叔的哲学：**宁缺毋滥**。滥竽充数的素材比没有更糟——污染视觉品味、传递「不专业」信号 - **「一个细节做到 120%，其他做到 80%」的量化版**：8 分是"其他 80%" 的底线，真正 hero 素材要 9-10 分 - 消费者看作品时，每一个视觉元素都在**积分或扣分**。7 分素材 = 扣分项，不如留空 **Logo 例外**（重申）：有就必须用，不适用「5-10-2-8」。因为 logo 不是「多选一」问题，而是「识别度根基」问题——就算 logo 本身只有 6 分，也比没有 logo 强 10 倍。 ##### Step 4 · 验证 + 提取（不只是 grep 色值） | 资产 | 验证动作 | |---|---| | **Logo** | 文件存在 + SVG/PNG 可打开 + 至少两个版本（深底/浅底用）+ 透明背景 | | **产品图** | 至少一张 2000px+ 分辨率 + 去背或干净背景 + 多个角度（主视角、细节、场景） | | **UI 截图** | 分辨率真实（1x / 2x）+ 是最新版本（不是旧版）+ 无用户数据污染 | | **色值** | `grep -hoE '#[0-9A-Fa-f]{6}' assets/<brand>-brand/*.{svg,html,css} \| sort \| uniq -c \| sort -rn \| head -20`，过滤黑白灰 | **警惕示范品牌污染**：产品截图里常有用户 demo 的品牌色（如某工具截图演示喜茶红），那不是该工具的色。**同时出现两种强色时必须区分**。 **品牌多切面**：同一品牌的官网营销色和产品 UI 色经常不同（Lovart 官网暖米+橙，产品 UI 是 Charcoal + Lime）。**两套都是真的**——根据交付场景选合适的切面。 ##### Step 5 · 固化为 `brand-spec.md` 文件（模板必须覆盖所有资产） ```markdown # <Brand> · Brand Spec > 采集日期：YYYY-MM-DD > 资产来源：<列出下载来源> > 资产完整度：<完整 / 部分 / 推断> ## 🎯 核心资产（一等公民） ### Logo - 主版本：`assets/<brand>-brand/logo.svg` - 浅底反色版：`assets/<brand>-brand/logo-white.svg` - 使用场景：<片头/片尾/角落水印/全局> - 禁用变形：<不能拉伸/改色/加描边> ### 产品图（实体产品必填） - 主视角：`assets/<brand>-brand/product-hero.png`（2000×1500） - 细节图：`assets/<brand>-brand/product-detail-1.png` / `product-detail-2.png` - 场景图：`assets/<brand>-brand/product-scene.png` - 使用场景：<特写/旋转/对比> ### UI 截图（数字产品必填） - 主页：`assets/<brand>-brand/ui-home.png` - 核心功能：`assets/<brand>-brand/ui-feature-<name>.png` - 使用场景：<产品展示/Dashboard 渐现/对比演示> ## 🎨 辅助资产 ### 色板 - Primary: #XXXXXX <来源标注> - Background: #XXXXXX - Ink: #XXXXXX - Accent: #XXXXXX - 禁用色: <品牌明确不用的色系> ### 字型 - Display: <font stack> - Body: <font stack> - Mono（数据 HUD 用）: <font stack> ### 签名细节 - <哪些细节是「120% 做到」的> ### 禁区 - <明确不能做的：比如 Lovart 不用蓝色、Stripe 不用低饱和暖色> ### 气质关键词 - <3-5 个形容词> ``` **写完 spec 后的执行纪律（硬要求）**： - 所有 HTML 必须**引用** `brand-spec.md` 里的资产文件路径，不允许用 CSS 剪影/SVG 手画代替 - Logo 作为 `<img>` 引用真实文件，不重画 - 产品图作为 `<img>` 引用真实文件，不用 CSS 剪影代替 - CSS 变量从 spec 注入：`:root { --brand-primary: ...; }`，HTML 只用 `var(--brand-*)` - 这让品牌一致性从「靠自觉」变成「靠结构」——想临时加色要先改 spec ##### 全流程失败的兜底 按资产类型分别处理： | 缺失 | 处理 | |---|---| | **Logo 完全找不到** | **停下问用户**，不要硬做（logo 是品牌识别度的根基） | | **产品图（实体产品）找不到** | 优先 nano-banana-pro AI 生成（以官方参考图为基底）→ 次选向用户索取 → 最后才是诚实 placeholder（灰块+文字标签，明确标注"产品图待补"） | | **UI 截图（数字产品）找不到** | 向用户索取自己账号的截屏 → 官方演示视频截帧。不用 mockup 生成器凑 | | **色值完全找不到** | 按「设计方向顾问模式」走，向用户推荐 3 个方向并标注 assumption | **禁止**：找不到资产就静默用 CSS 剪影/通用渐变硬做——这是协议最大的反 pattern。**宁可停下问，也不要凑**。 ##### 反例（真实踩过的坑） - **Kimi 动画**：凭记忆猜「应该是橙色」，实际 Kimi 是 `#1783FF` 蓝色——返工一遍 - **Lovart 设计**：把产品截图里演示品牌的喜茶红当成 Lovart 自己的色——差点毁整个设计 - **DJI Pocket 4 发布动画（2026-04-20，触发本协议升级的真实案例）**：走了旧版只抽色值的协议，没下载 DJI logo、没找 Pocket 4 产品图，用 CSS 剪影代替产品——做出来是「通用黑底+橙 accent 的科技动画」，没有大疆识别度。花叔原话：「否则，我们在表达什么呢？」→ 协议升级。 - 抽完色没写进 brand-spec.md，第三页就忘了主色数值，临场加了个「接近但不是」的 hex——品牌一致性崩溃 - **五大 Coding Agent 对比 PPT（2026-06-06，触发触发条件扩展的真实案例）**：agent 把任务判成「PPT + 没风格参考」走 Fallback 设计方向顾问，只抽了五家品牌色就 spawn 三套设计逻辑，**五个产品 logo（Claude Code / Cursor / Codex / Copilot / Trae）一个没取**——被花叔抓现行「我们为什么没去取这些产品的 logo」。根因：把「对比 / 榜单 deck」误判为不触发 §1.a（以为 §1.a 只管「为单一客户做物料」），且 Fallback 路径里没有任何 logo 检查点。→ 修复：①触发条件扩成两类（含「设计里点名/并列真实产品」）②Fallback 不豁免取 logo ③Phase 3.5 加「具名产品 logo 子门」spawn 前必过 ④Step 3.1 补 svgl/simpleicons/Google favicon 可靠取图链。 ##### 协议代价 vs 不做代价 | 场景 | 时间 | |---|---| | 正确走完协议 | 下载 logo 5 min + 下载 3-5 张产品图/UI 10 min + grep 色值 5 min + 写 spec 10 min = **30 分钟** | | 不做协议的代价 | 做出没识别度的通用动画 → 用户返工 1-2 小时，甚至重做 | **这是稳定性最便宜的投资**。尤其对商单/发布会/重要客户项目，30 分钟的资产协议是保命钱。 -
camera-language.md 22.7 KB
# Camera Language · 运镜导演体系 > **何时读本文件**：画面里出现任何「镜头级」运动之前——zoom / pan / orbit / parallax / > 转场 / 定场谢幕，只要动的是「镜头」而不是「元素」，先读这里再写 timeline。 > 元素怎么动（入场/stagger/物理感）归 `animation-best-practices.md`； > 本文件回答的是**镜头什么时候动、动多大、动多久、镜头之间怎么接**。 > GSAP 侧的可运行实现（rig 容器、PageCam 翻译、对数时长 helper）见 > `gsap-recipes.md` 的「Camera Rig 配方」节，本文只给设计判断和公式。 > > 参数出处标注约定：**(HuaRec)** = 花录 Studio 运镜导演系统实测参数； > **(shotcraft)** = video-shotcraft 106 卡镜头体系；**(实测)** = 本 skill 项目实战； > **(推测)** = 通用电影语汇借鉴，参数待实测校准。 --- ## §0 · 立论 · 运镜是预算制，不是特效制 大多数 AI 生成动画的运镜是「特效制」思维：哪里能加 zoom 就加 zoom，镜头动得越多越「高级」。 这是晕和廉价感的共同来源。正确的心智模型来自两条公理 (HuaRec)： - **A1 可见性不变量**：任意时刻，观众该看的东西必须在可视区内（含 8% 安全边距）。 违反的镜头宁可降倍率、并镜或不拍。 - **A2 舒适预算**：每次镜头变化都是一笔注意力消费，必须预算化管理。 预算花完了，再好的镜头也不拍。 | 预算项 | 典型值 | 调节手感 | |---|---|---| | 相邻镜头变化间隔 | ≥2.6-3.0s（克制档 5.0s） | 低于 2.6s 观众开始晕；MTV 式快剪不适用于产品演示 (HuaRec) | | 任意 15s 窗口内镜头变化 | ≤4-5 次（克制档 3 次） | 超了就砍最弱动机的那一镜，不是压缩间隔 (HuaRec) | | 推进倍率下限 | 1.25x | 低于 1.25x 的 zoom 视觉变化感知不足，纯属晃动，不拍（定场 1.06x 是唯一例外）(HuaRec) | | 推进倍率上限 | 2.3x（克制档 1.8x） | 再高像素密度撑不住，先换素材再谈倍率 (HuaRec) | | 每分钟镜头数 | 克制 ≤4 镜/分，常规 ≤6 镜/分 | 「留呼吸，不是 MTV」(HuaRec) | 再叠两条风格公理 (shotcraft)： 1. **电影感 = 运镜 × 光影 × 节奏 × 声音，不等于炫技动画**。四个维度各自及格，胜过一个维度拉满。 2. **节奏偏好单向：宁慢勿快**。历史用户反馈全部指向「放慢/停留」，没有一条指向「加快」。 拿不准时长时，选长的那个；拿不准要不要动镜时，选不动。 这两条与 best-practices §0.2 的「礼让观众」同源：镜头是替观众的眼睛做决定， 决定做得越少、越准，观众越信任你。 --- ## §1 · 镜头语言词汇表 · 运镜动机决策表 每个镜头动作先问动机：**这一镜替观众回答了什么问题？** 答不上来就不动。 | 镜头 | 动机（什么时候给） | 参数区间 | 禁忌 | |---|---|---|---| | **push in 推近** | 「接下来看这里」：聚焦一个具体 UI 元素 / 数据 / 关键词；紧张度爬升 | 倍率 1.3 / 1.45 / 1.8 / 2.3 档（见 §4）；时长走对数公式；提前 0.15s 进镜 (HuaRec) | <1.25x 不推；滚动 / 切页 / 播视频等全屏级变化期间不推（「滚动时推近会晕」）；旁白中段不动镜（见 §6 move on pause）(HuaRec) | | **pull out 拉远** | 揭示全貌与上下文：「原来它属于一个更大的系统」；收尾谢幕 | 时长同对数公式；谢幕拉出 0.55s + ≥0.8s 全景停顿 (HuaRec) | 禁「出-进-出」泵动：镜间空隙小于过渡时长时直接接下一镜，不回 1x（见 §5）(HuaRec) | | **pan 平移** | 两个中距焦点之间转移（归一化距离 0.22-0.45）；一镜扫过多个并列元素 | 联合倍率 ≥1.25 才值得平移；斜向 pan 用双频正弦（X/Y 频率比 0.22:0.35，振幅 30-40px）(HuaRec / 本 skill 既有) | 焦点距离 >0.45 不平移（对角横跳），弃镜；纯单轴 pan 有机械感，优先斜向 | | **orbit 环绕** | 单主角质感特写，「实体感」最强的一镜；hero 元素立传 | rotY 主导 + persp 1100-1200px；实测机位 rotX46/rotY−30/rotZ9 → rotX42/rotY26/rotZ−7 (shotcraft) | 一种手法全片只当一次主角 (shotcraft)；信息密集画面禁用（机位服务可读性，文字多就正视） | | **dolly zoom** | 「世界观反转」的揭示瞬间：主体不变、语境剧变 | 伪配方见 §8：主体钉死，背景 scale 1→2.0-2.5 + opacity ≤0.6 (shotcraft) | 全片最多一次；无叙事落差时用它 = 纯炫技 | | **静止** | 文字阅读、真人速度交互演示、信息密集镜头；预算不足时的默认答案 | 品牌字标落定 hold ≥1s；批量动效收尾 0.5s 静止；开场主体动作弧 ≥3s (shotcraft) | 无。静止不动永远是合法选择，「不给镜头」本身就是导演决定 | 两条横向规则： - **速度感来自加速度，不是匀速快** (shotcraft)。匀速运动读作廉价 PPT； 想要「快」的感觉，用短促的加速段 + 长缓冲，不是把整段 duration 砍半。 - **机位服务可读性** (shotcraft)：信息密集镜头正视；文字特写用侧向水平机位 （rotY 主导、rotX 很小）；禁全局一刀切倾斜；产品宣传片默认不加手持抖动。 --- ## §2 · zoom vs dolly 选型 · 3D 真假裁决 「推近」有两种实现，观感完全不同，先选型再写代码： | 维度 | zoom（scale 缩放） | dolly（perspective + translateZ 前移） | |---|---|---| | 视差 | 无。所有层等比放大，画面是「一张图被放大」 | 有。近层快、远层慢，画面是「镜头在空间里前进」 | | 观感 | 干净、信息型，适合 UI 特写 / 数据聚焦 | 空间感、电影感，适合 hero 展示 / 氛围段落 | | 成本 | 低：单个 transform | 高：需要分层结构 + preserve-3d，且有栅格化发糊问题（§3.4） | | 选型规则 | 内容是平面信息（界面、文档、图表）→ zoom | 内容有明确的「前景/主体/背景」层次，且这层次值得被看见 → dolly | **3D 真假裁决**（化解本 skill 两处旧文矛盾的边界线）： - 参与 3D 的元素 **≤8 个** → 用真 translateZ 分层（best-practices §4.7 的黄金角配方照用） - 元素 **≥20 个** → 放弃真 3D，用 shadow / blur / 明度差做假深度（hero-case-study 的立场） - 8-20 之间 → 问一个问题：这段镜头需要视差吗？需要才上真 3D，不需要就假深度。 真 3D 的成本不在写，在调：每加一层就多一组「透视失真 + 文字发糊 + 层级穿插」要排查。 --- ## §3 · Camera Rig 实现约定 镜头运动和元素动画**不许抢同一个 transform**。所有镜头级运动收口到一个专职容器上。 ### 3.1 分层容器结构 ```html <div id="viewport"> <!-- 固定视口，overflow: hidden，持有 perspective --> <div id="camera"> <!-- 镜头层：只承载相机 transform，别的什么都不干 --> <div id="world"> <!-- 世界层：所有画面内容住这里，元素动画只动 world 内部 --> ...场景内容... </div> </div> <div id="hud"> <!-- 字幕 / 角标 / chrome：与 #camera 平级，天然不跟镜头动 --> </div> </div> ``` 分工铁律： - `#camera` 上只出现镜头 tween（translate / scale / rotate / zoom 属性），元素入场、stagger、 hover 态一律写在 `#world` 内部的元素上。两层互不知晓，镜头随时可以整体重排而不碰元素动画 - 字幕和 chrome **首选放 `#hud`**，零成本保持静止；只有「必须跟着 world 里某元素走、 但字号要恒定」的标注（如跟随 tooltip），才在该元素上做 counter-transform： `scale(1/zoom)` 反向抵消镜头缩放，每帧与相机同步更新 - **transform-origin 就是推进目标点**：平面 zoom 把 origin 设到目标元素中心再 scale， 等价于「镜头对准它推近」。PageCam 模式下由 cx/cy 承担同一职责 ### 3.2 PageCam 关键帧模型（shotcraft，2.5D 相机数学） 把镜头状态定义成关键帧对象，镜头运动 = 关键帧之间插值： ``` { frame, cx, cy, zoom, rotX, rotY, rotZ, persp } ``` cx/cy 是**世界坐标系里镜头对准的点**，zoom 是倍率。以 1920×1080 画布为例 （其他尺寸把 960/540 换成 W/2、H/2）： **平面模式**（无旋转，纯 zoom + pan）： ``` transform: translate(960 − cx·zoom, 540 − cy·zoom) scale(zoom) transform-origin: 0 0 ``` **3D 模式**（有 rotX/rotY/rotZ）： ``` 外层（#camera）: perspective: persp·zoom; perspective-origin: 960px 540px 内层（#world）: zoom: {zoom}; /* 注意是 CSS zoom 属性，见 §3.4 */ Tx = 960/zoom − cx; Ty = 540/zoom − cy transform: translate(Tx, Ty) rotateY() rotateX() rotateZ() transform-origin: cx cy transform-style: preserve-3d ``` 典型机位参数 (shotcraft 实测)：全页 zoom 0.78 → 特写 2.6； 侧拍 rotY34 / rotX8 / persp1200（侧拍优于俯拍，rotY 主导 + rotX 只给一点）； orbit 起止机位见 §1 表。 ### 3.3 rig 施工注意（镜头专属坑） - **pan 露边**：`#world` 必须比视口大（四周外扩 bleed ≥ 最大 pan 振幅 + 8% 边距）， 否则平移时露出画布外的空白。这是 A1 可见性公理的反面：不该看的也不能看见 - **perspective 被打断**：`#camera` 与 `#world` 之间的任何中间层加了 `overflow: hidden`、`filter`、`opacity <1` 都会创建新 stacking context， 杀掉 preserve-3d，3D 分层瞬间变平。3D 模式下滤镜效果只加在最内层元素上 - **逐帧越界兜底** (HuaRec)：镜头焦点跟随动点时，每帧检查目标是否越出可视区， 越出则保持倍率、只沿越界轴做最小修正拉回边界。宁可镜头「让一步」，不许目标出画 ### 3.4 CSS zoom 栅格化技法 · 根治 3D 文字发糊（全库最贵知识，shotcraft） **问题**：3D 模式下用 `transform: scale()` 放大页面，Chromium 按元素的布局尺寸栅格化， 再把位图放大，文字必糊。倍率越高糊得越狠，2x 以上不可交付。 **解法**：放大不走 `transform: scale`，走 **CSS `zoom` 属性**。`zoom` 是布局级缩放， Chromium 按放大后的尺寸重新 layout 并栅格化，文字在任意倍率下保持矢量级锐利。 §3.2 的 3D 模式公式里内层写 `zoom: {zoom}` 而不是 `scale({zoom})`，正是为此。 配套要点： | 要点 | 做法 | 出处 | |---|---|---| | 坐标补偿 | `zoom` 改变布局坐标系，translate 量要除以 zoom：`Tx = 960/zoom − cx`（§3.2 公式已含） | (shotcraft) | | 与 reflow 禁令的关系 | gsap-recipes §6.2 禁 tween 布局属性是因为整数 snap 抖动；`zoom` 是整页级缩放，snap 量不可感，且文字锐利收益远大于。**此技法是 §6.2 的唯一合法例外，只用于 `#world` 相机层** | (实测) | | 渲染环境 | HyperFrames / Playwright 离线逐帧 seek 渲染下完全适用：每帧重 layout 的耗时不影响产物，只影响渲染时长。实时浏览器 preview 可能掉帧，属正常，以渲染产物为准 | (shotcraft) | | 位图素材增强 | 全页截图用 2x 采样；特写元素另备 4x 单独截图，在推进期用 6f 交叉淡入盖住低倍纹理 | (shotcraft) | | 景深氛围 | DoF 只做氛围：顶部渐变带 blur + mask，不做逐层真实景深 | (shotcraft) | --- ## §4 · 镜头缓动与时长 ### 4.1 缓动词汇 | 场景 | easing | 调节手感 | |---|---|---| | 主动运镜（推近/拉远，有明确起止点） | `cubic-bezier(0.65,0,0.35,1)` = GSAP `power3.inOut` | 两端都稳，「导演给镜头」的感觉；**绝不线性、绝不弹簧过冲** (HuaRec) | | 跟随式运镜（镜头追一个已开始的动作） | `cubic-bezier(0.33,0,0.15,1)` | 出发轻快、刹车极长，镜头像「跟上去」而不是「切过去」；shotcraft 相机默认 | | 持续漂移（idle drift、匀速巡览） | `sine.inOut` yoyo 或 `none` | 唯一允许相机匀速的场景（gsap-recipes §1 既有规则）；有起止点的动作禁用 | | 光标/焦点跟随平滑 | `quickTo` + ~0.15s 平滑；路径插值 Catmull-Rom | 前向+后向 EMA 的零相位思路：跟得紧但不抖 (HuaRec) | 两套默认冲突时的裁决：单次推拉信 HuaRec（power3.inOut），复合移动、 多段连续镜头信 shotcraft（0.33,0,0.15,1）。 ### 4.2 zoom 时长对数公式（固定 duration 是业余感的来源） 所有推拉时长由倍率变化量决定，保证任何幅度的 zoom「视觉速度」一致： ``` duration = 0.55 × |ln(zoom₂ / zoom₁)| / ln 2 clamp 到 [0.30, 0.94] 秒 ``` 1→2x 推近正好 0.55s；1→1.3x 约 0.30s（触底）；0.78→2.6x 触顶 0.94s。(HuaRec) 大景别过渡更久、小景别更短，防「一蹿到位」也防「拖沓」。 ### 4.3 zoom 档位表 | 档位 | 倍率 | 用途 | 调节手感 | |---|---|---|---| | 定场微推 | 1.06x | 仅用于开场定场（§6），观众感知不到 zoom、只感知到「画面活着」 | 唯一允许低于 1.25x 的档位 (HuaRec) | | 轻推 | 1.3x | 提示性聚焦：不打断全局阅读，只是「注意这一片」 | | | 中推 | 1.45x | 标准 UI 特写：一个面板 / 一段代码 | | | 重推 | 1.8x | 单元素特写：一个按钮 / 一个数字 | 克制档的上限 (HuaRec) | | 上限 | 2.3x | 极限特写，素材必须扛得住（2x 截图 / 4x 切片，§3.4） | 超过就换素材，不硬推 (HuaRec) | 定景公式 (HuaRec)：`scale = 0.8 / max(目标包围盒归一化宽, 高)`，再夹到档位区间。 内容占可视区 80%，留 20% 呼吸，不顶格。 ### 4.4 节奏预算（与 §0 预算表联动） - 相邻镜头变化间隔 ≥2.6-3.0s；15s 窗口 ≤4-5 次 (HuaRec) - 动作前 0.15s 进镜（镜头先到，动作后发生），动作结束后停留 1.2s 再走 (HuaRec) - 时长 <1.2s 的孤立小动作不值得单独给镜头，防「点一下泵一下」(HuaRec) --- ## §5 · 镜间语法 · 防晕核心 **晕不是单个镜头造成的，是镜头之间的接法造成的。** 「出-进-出」泵动和远焦点连续横跳 贡献了绝大多数眩晕感 (HuaRec)。对相邻两镜（间隔 <1.5s），按焦点距离三分： | 焦点归一化距离 | 接法 | 说明 | |---|---|---| | <0.22（近） | **并镜** | 合并为一镜：取两目标的联合包围盒重算倍率，一镜看完 | | 0.22-0.45（中） | **改平移** | 宁可倍率广一点（联合倍率 ≥1.25），一镜平移过去，不做「出再进」 | | >0.45（远/对角） | **弃镜** | 砍掉动机更弱的那一镜。**绝不连拍两个远焦点**，对角横跳是最晕的一种接法 | 补两条时序规则 (HuaRec)： - **间隙短则直接对接**：相邻镜头空隙小于过渡时长时，不回 1.0x，直接从当前倍率过渡到 下一镜的倍率和焦点。回 1x 再推是「泵动感」的直接来源 - **间隙 ≥1.5s 才允许「拉出再推进」**：观众有足够时间在全景里重新定位，出-进才不晕 --- ## §6 · 电影开闭幕 · 定场、谢幕、move on pause 三条语法成本极低，作品感提升明显 (HuaRec)： 1. **定场（establishing shot）**：片长 >14s 且首个正式镜头在 7s 之后时， 开场插入 [0, 3.0s] 的 **1.06x 中心微推**：开机即处于轻推近态，3 秒内缓出落回全景。 观众的第一感受是「镜头是活的」，而不是「PPT 开始播放了」 2. **全景谢幕铁律**：末镜提前收口，留出 0.55s 拉出过渡 + **≥0.8s 全景停顿**。 成片永远以全景静止收尾，**绝不在推近态戛然而止**。与 best-practices「戛然而止 + hold」 收尾完全兼容：hold 的那一帧必须是全景 3. **Move on pause**：cut on action, move on pause。有旁白的动画里，镜头移动如果撞在 说话中段，向早处吸附到最近的语音静默点（最多前移 0.8s，**只提前不推后**）。 观众在听觉空档移动视线的认知成本最低。解说 pipeline（voiceover-pipeline.md）排镜头时 直接拿 narration 的分句间隙当吸附点 --- ## §7 · 转场语法表 · 三层词汇 转场是独立层：接缝按**能量落差**选型，一个接缝只用一式，转场帧从相邻镜头预算里划走。 「公认优秀的发布片全程没有一次裸切」(shotcraft)。 ### 7.1 shot-transitions 六式（有存在感的转场，用于能量落差大的接缝） | 式 | 适用能量落差 | 参数 | 坑 | |---|---|---|---| | 流白 flash-wash | 高→高，段落强转 | 白场 2-4f 峰值，两侧各 5f 渐变 | 白闪只盖切点，不当装饰反复用 | | 穿暗场 dip-to-dark | 高→低，情绪降档 | 压暗到 rgba(20,20,20,0.9) 量级，总长 ≤0.6s | 暗场里别停留，观众以为片子结束 | | 虚焦接力 defocus-handoff | 中→中，平级话题切换 | 出镜 blur 0→8px 与入镜 blur 8px→0 交叠 ≥8f | blur 大面积 ≤24px（DoF 性能约束） | | 黑场字卡 title-card | 章节级分隔 | 字卡 hold ≥1s，前后各 0.3s 过渡 | 全片 ≤2 张，多了像幻灯片 | | whip-pan 甩镜 | 低→高，能量急升 | 两端 hold ≥20f → 8f 甩 1.5 屏，峰值 ≥300px/f 才糊得透 (shotcraft) | 慢了就是普通 pan，糊不透反而露拙 | | mask-wipe 穿窗 | 空间转移，「穿过一个界面进入另一个」 | 遮罩缘 easing `(0.4,0,0.6,1)` (shotcraft) | 遮罩形状必须来自画面内已有元素（窗口/卡片圆角），凭空的形状是 slop | ### 7.2 hidden-cut 三式（观众察觉不到切过的转场） | 式 | 做法 | 出处 | |---|---|---| | flash-cut 白闪跨切 | 白闪跨骑硬切点，两侧各 5f，只盖切点 | (shotcraft，实证参数) | | 前景遮挡切 | 一个前景元素（卡片/面板/光标手）扫过全屏的瞬间换景 | (推测：通用电影语汇，参数待实测) | | 运动糊切 | 高速运动峰值帧上硬切，两侧运动方向一致，motion blur 吞掉切点 | (推测：通用电影语汇，参数待实测) | ### 7.3 travel 两式（空间连续的转场，能量不落差、场景在移动） | 式 | 做法 | 坑 | |---|---|---| | 共享元素归位 | 前镜的某元素（logo/卡片）连续运动到后镜中它的新位置，FLIP 思路的镜头版 | 元素在两镜中必须同一身份，形变过大就断了「同一个东西」的认知 | | 字腔穿越 | 镜头推进穿过大字的字腔（O/口/0 的空洞）进入下一场景 | 字腔尺寸要够（≥1/3 屏高），穿越段 zoom 走对数时长上限 0.94s | 选型速查：能量落差大 → 六式挑一；不想被察觉 → hidden-cut；两个场景空间上连续 → travel。 硬切不是禁用，是「必须被上述任意一层包装过」。 --- ## §8 · 多层 parallax 配方 · 伪 dolly-zoom ### 8.1 parallax 层速度系数 (shotcraft) | 参数 | 典型值 | 调节手感 | |---|---|---| | 层速度系数 | 远景 0.35 / 中景 0.7 / 近景 1.4（相机位移的倍数） | 相邻层速比 **≥2 倍**才可辨，1.2 倍的差异观众读不出来 | | 层数 | ≤4 层 | 超过 4 层的视差没人看得出来，纯浪费预算 | | 实现 | 各层根据同一个相机 x/y 乘各自系数 translate | 全部由相机状态推导，seek-safe；别给每层独立 tween | ### 8.2 伪 dolly-zoom（纯 CSS，无需真 3D） ``` 主体：钉死不动（或只做 ≤1.02x 的呼吸） 背景：scale 1 → 2.0-2.5，同时 opacity 降到 ≤0.6 ``` 主体不变、背景涌向观众，产生「世界在逼近而主角凝固」的反转感 (shotcraft)。 时长给足（≥1.2s），用途见 §1：全片最多一次，留给真正的揭示瞬间。 --- ## §9 · 运动派生信号 · blur / 跟随 / 余震 镜头的「速度感」不靠更快的 duration，靠从速度**派生**出来的次级信号 (shotcraft / HuaRec)： | 信号 | 公式 | 参数 | |---|---|---| | 速度驱动 blur | `v = velocityAt(f)`（中央差分：`(pos(f+1)−pos(f−1))/2`），blur 强度 ∝ v | zoom 速度 >0.6/s 才触发，强度 `min(10, v×5)`px。**只在动的瞬间有模糊，静止帧永远锐利** (HuaRec) | | lagged 跟随层 | 跟随层 = 主体在 `f − delay` 处采样 | 阴影滞后 2f、残影滞后 4f (shotcraft)。残影平替 motion blur：5% 路径滞后 + blur(6px) + opacity 0.25·(1−t) | | dampedSettle 余震 | `e^(−d·t) · sin(2π·f·t)`，f≈0.1、damping≈0.15 | 镜头急停后的 1-2 个微小残摆，幅度 ≤3px；主动运镜（§4.1 inOut 族）不加，只给 whip-pan / 急刹类 | 三者全部是时间的纯函数（差分、延迟采样、闭式衰减），天然 seek-safe， 符合 gsap-recipes §6 的确定性要求。 --- ## §10 · 运镜自检清单（写完 timeline 后 60 秒） - [ ] 每个镜头动作都答得出「替观众回答了什么问题」？答不出的删了吗？ - [ ] 没有 <1.25x 的 zoom（定场 1.06x 除外）？ - [ ] 相邻镜头间隔 ≥2.6s，15s 窗口 ≤4-5 次？ - [ ] 所有推拉时长走对数公式，没有拍脑袋的固定 duration？ - [ ] 推拉 easing 是 power3.inOut，没有 linear / 弹簧过冲？ - [ ] 相邻镜头按焦点距离做过三分裁决（并镜/平移/弃镜）？没有两连远焦点横跳？ - [ ] 间隙短的镜头直接对接，没有回 1x 的泵动？ - [ ] 片长 >14s 且首镜晚于 7s：加了 1.06x 定场微推？ - [ ] 结尾是全景静止 ≥0.8s，不在推近态收尾？ - [ ] 有旁白：镜头移动吸附到了语音间隙（只提前 ≤0.8s）？ - [ ] 镜头运动全部收口在 `#camera` 层，没和元素动画抢 transform？ - [ ] 3D 文字特写走了 CSS zoom 栅格化，没有 scale 放大发糊？ - [ ] 每个转场接缝只用一式，全片没有裸切？ - [ ] parallax 相邻层速比 ≥2 倍、≤4 层？ - [ ] blur 只出现在运动瞬态，静止帧全部锐利？ --- ## §11 · 与其他 reference 的关系 | reference | 分工 | 边界 | |---|---|---| | `animation-best-practices.md` | 元素怎么动、叙事节奏、品味标准 | 它管「演员」，本文件管「摄影机」；S4 爆发段的「镜头拉远」按本文件 §4 定参数 | | `gsap-recipes.md` | 本文件所有规则的 GSAP 可运行实现 | 「Camera Rig 配方」节：rig 容器、PageCam 翻译、对数时长 helper、counter-transform | | `animation-pitfalls.md` | 踩坑清单 | 镜头专属坑（scale 发糊 / perspective 被打断 / pan 露边）§3.3-3.4 已覆盖设计侧，pitfalls 收技术侧复现 | | `hyperframes-backend.md` | 渲染后端契约 | CSS zoom 技法在离线逐帧渲染下的适用性见 §3.4 | | `voiceover-pipeline.md` | 解说驱动长视频 | move on pause（§6.3）的静默点数据从 narration 分句间隙来 | | `ai-video-review.md` | 成片评审 | 评审 checklist 的转场分类按 §7 三层词汇扩展 | **调用顺序**：导演稿 / 分镜阶段读 §0-§2 定预算和词汇 → 写 timeline 前读 §3-§7 定实现约定 与接缝 → 交付前过 §10 清单。 -
cinematic-patterns.md 10.8 KB
# Cinematic Patterns · Workflow Demo 的 Best Practice > 从「PPT 动画」升级到「发布会级 cinematic」的 5 个关键 pattern。 > 蒸馏自 2026-04 「聊聊 skill」 deck 的两个 cinematic demo（Nuwa workflow + Darwin workflow），实测可复现。 --- ## 0 · 这份文档解决什么问题 当你需要做「演示一个工作流的 demo 动画」时（典型场景：skill 工作流、产品 onboarding、API 调用流程、agent 任务执行），有两种常见做法： | 范式 | 长什么样 | 后果 | |---|---|---| | **PPT 动画**（差） | step 1 fade in → step 2 fade in → step 3 fade in，4 个 box 同屏排列 | 观众感觉「就是一个 PPT 加了 fade 效果」，没有 wow moment | | **Cinematic**（好） | scene-based，一次只 focus 一件事，scene 之间是 dissolve / focus pull / morph | 观众感觉「这是一个产品发布会片段」，会想截图分享 | 差异的根源**不是动画技术**，是**叙事范式**。本文档讲怎么从前者升级到后者。 --- ## 1 · 五个核心 pattern ### Pattern A · Dashboard + Cinematic Overlay 双层结构 **问题**：单纯的 cinematic 默认是黑屏 + 一个 ▶ 按钮，用户翻到这页如果没点，什么都看不到。 **解决**： ``` DEFAULT 状态 (永远显示)：完整静态 workflow dashboard └── 观众一眼看清这个 skill / 工作流怎么跑 POINT ▶ 触发 (overlay 浮上来)：22 秒 cinematic └── 跑完自动 fade 回 DEFAULT ``` **实现要点**： - `.dash` 默认 visible，`.cinema` 默认 `opacity: 0; pointer-events: none` - `.play-cta` 是右下角金色小按钮（不是中央大覆盖） - 点击 → `cinema.classList.add('show')` + `dash.classList.add('hide')` - 用 `requestAnimationFrame` 跑一次（不是循环），结束后 `endCinematic()` reverse 状态 **反 pattern**：默认 = 中央大 ▶ overlay 覆盖一切，没点之前页面是空白的。 --- ### Pattern B · Scene-based, NOT Step-based **问题**：把动画拆成「step 1 显示 → step 2 显示 → ...」就是 PPT 思维。 **解决**：拆成 5 个 scene，每个 scene 是**独立的镜头**，全屏只 focus 一件事： | Scene 类型 | 职责 | 时长 | |---|---|---| | 1 · Invoke | 用户输入触发（终端 typewriter）| 3-4s | | 2 · Process | 核心工作流的可视化（独特视觉语言）| 5-6s | | 3 · Result/Insight | 提炼出的关键产物（可视化）| 4-5s | | 4 · Output | 实际产物展示（文件 / diff / 数字）| 3-4s | | 5 · Hero Reveal | 收尾 hero moment（大字 + 价值主张）| 4-5s | **总时长 ≈ 22 秒**——这是经过测试的黄金长度： - 短于 18 秒：PM 还没进入状态就结束了 - 长于 25 秒：失去耐心 - 22 秒刚好够「钩住 → 展开 → 收束 → 留下印象」 **实现要点**： - `T = { DURATION: 22.0, s1_in: [0, 0.7], s2_in: [3.8, 4.6], ... }` 全局时间轴 - 单个 `requestAnimationFrame(render)` 跑所有 scene 的 opacity / transform 计算 - 不要用 setTimeout 链（容易断掉、难调试） - Easing 必用 `expoOut` / `easeOut` / cubic-bezier，**禁止 linear** --- ### Pattern C · 每个 demo 的视觉语言必须独立 **问题**：做完第一个 cinematic 后，做第二个时偷懒复用同一个模板（同样的 orbit + pentagon + typewriter + hero 大字），只换了文案。 **后果**：观众发现两个 skill「长得一模一样」，等于在说「这两个 skill 没区别」。 **解决**：每个工作流的核心隐喻不同，视觉语言就必须不同。 **对照案例**： | 维度 | Nuwa（蒸馏人）| Darwin（优化 skill）| |---|---|---| | 核心隐喻 | 收集 → 提炼 → 写 | 循环 → 评估 → 棘轮 | | 视觉运动 | 漂浮 / 辐射 / pentagon | 循环 / 上升 / 对比 | | Scene 2 | 3D Orbit · 8 张档案在透视椭圆漂浮 | Spin Loop · token 沿 6 节点圆环跑 5 圈 | | Scene 3 | Pentagon · 5 token 从中央辐射 | v1 vs v5 · 并列 diff（红版 vs 金版） | | Scene 4 | SKILL.md typewriter | Hill-Climb · 全屏曲线绘制 | | Scene 5 hero | 「21 分钟」serif italic 大字 | 旋转齿轮 ⚙ + 「KEPT +1.1」金色 tag | **判断标准**：盖住文案，只看视觉，能不能区分这是哪个 demo？区分不了就是偷懒。 --- ### Pattern D · 用 AI 生成的真实素材，不要 emoji 或 SVG 手画 **问题**：3D orbit / gallery 里需要素材碎片漂浮，emoji（📚🎤）丑且无品牌、SVG 手画书脊永远不像真书。 **解决**：用 `huashu-gpt-image` 跑一张 4×2 grid 大图（8 件主题相关物品 · 白底 · 60px breathing space · unified style），用 `extract_grid.py --mode bbox` 抠成 8 张独立透明 PNG。 **Prompt 要点**（详细 prompt patterns 见 `huashu-gpt-image` skill）： - IP 锚定（"1960s Caltech archive aesthetic" / "Hearthstone-style consistent treatment"） - 白底（便于抠图，灰底氛围好但抠透明背景困难） - 4×2 不要 5×5（避免末行压缩 bug） - Persona finishing（"You are a Wired magazine curator preparing an exhibition photo"） **反 pattern**：用 emoji 当 icon、用 CSS 剪影代替产品图。 --- ### Pattern E · BGM + SFX 双轨制 **问题**：只有动画没有声音，观众潜意识感觉「这玩意像个穷酸 demo」。 **解决**：BGM 长音 + 11 个 SFX cues。 **通用 SFX cue 配方**（适用于工作流 demo）： | 时点 | SFX | 触发场景 | |---|---|---| | 0.10s | whoosh | 终端从下方升起 | | 3.0s | enter | typewriter 完成、按 enter | | 4.0s | slide-in | scene 2 元素入场 | | 5-9s × 5 次 | sparkle | 关键过程节点（每代 / 每个 token / 每个数据点）| | 14s | click | 切换到 output scene | | 17.8s | logo-reveal | hero reveal 时刻 | | typewriter | type | 每 2 字符触发一次（密度别太高）| **频段隔离**：BGM volume 0.32（低频底噪），SFX volume 0.55（中高频 punch），sparkle 0.7（要醒目），logo-reveal 0.85（最强 hero moment）。 **用户控制**： - 必须有 ▶ 启动覆盖（浏览器 autoplay 限制） - 右上角小 mute 按钮（用户随时切静音） - 不要做成「翻到这页就强制响」 --- ## 2 · 静态 Dashboard 设计要点 Dashboard 是双层结构的 Layer 1，PM 不点 ▶ 也能看懂这个 skill。 **布局**：3 列 grid（或 1 大 + 2 小），每个 panel 解决一个问题： | Panel 类型 | 解决什么问题 | 案例 | |---|---|---| | **Pipeline / Flow Diagram** | 「这个 skill 的工作流程是什么？」| Nuwa 4 阶段 pipeline · Darwin autoresearch loop | | **Snapshot / State** | 「跑出来的真实数据长什么样？」| Darwin 8 维 rubric snapshot | | **Trajectory / Evolution** | 「多次运行后怎么变化？」| Darwin 5 代 hill-climb 曲线 | | **Examples / Gallery** | 「已经产出过哪些东西？」| Nuwa 21 personas gallery | | **Strip · Example I/O** | 「输入什么 → 输出什么」| Nuwa example strip：`› nuwa 蒸馏 费曼 → feynman.skill (21 min)` | **关键约束**： - 信息密度要够（每个 panel 都要承载差异化信息） - 但不能塞数据 slop（每个数字都要有意义） - 配色与 cinematic 一致（同色系，方便切换不突兀） --- ## 3 · 调试与开发工具 任何长动画必须配三个 dev 工具，否则调试会爆炸。 ### 工具 1 · `?seek=N` 冻结到第 N 秒 ```js const seek = parseFloat(params.get('seek')); if (!isNaN(seek)) { started = true; muted = true; frozenT = seek; // render() 用这个 t 而不是 elapsed cinema.classList.add('show'); dash.classList.add('hide'); } // render() 里： let t = frozenT !== null ? frozenT : (elapsed % T.DURATION); ``` 用法：`http://.../slide.html?seek=12` 直接看第 12 秒画面，不用等播放。 ### 工具 2 · `?autoplay=1` 跳过 ▶ overlay 方便 playwright 自动截图测试，也方便嵌入 iframe 时 force 启动。 ### 工具 3 · 手动 REPLAY 按钮 右上角小按钮，用户/调试时可以重播任意次。CSS： ```css .replay{position:absolute;top:18px;right:18px;background:rgba(212,165,116,0.1); border:1px solid rgba(212,165,116,0.3);color:#D4A574; font-family:monospace;font-size:10px;letter-spacing:.28em;text-transform:uppercase; padding:6px 12px;border-radius:1px;cursor:pointer;backdrop-filter:blur(6px);z-index:6} ``` --- ## 4 · iframe 嵌入坑（如果 cinematic 嵌在 deck 里） ### 坑 1 · 父窗口的 click zone 拦截 iframe 内按钮 如果 deck index.html 加了「左右 22vw 透明 click zone 翻页」，会**覆盖到 iframe 内的 ▶ play 按钮**——用户点按钮被吞成「下一页」。 **修复**：click zone 加 `top: 12vh; bottom: 25vh`，给顶部和底部 25% 不拦截，让 iframe 内的中央 ▶ 和右下角 ▶ 都能点。 ### 坑 2 · iframe 抢焦点后键盘事件丢失 用户点过 iframe 后，焦点在 iframe 里，父窗口的 ←/→ 键盘事件收不到。 **修复**： ```js iframe.addEventListener('load', () => { // 注入键盘转发器 const doc = iframe.contentDocument; doc.addEventListener('keydown', (e) => { window.dispatchEvent(new KeyboardEvent('keydown', { key: e.key, ... })); }); // 点击后焦点拽回父窗口 doc.addEventListener('click', () => setTimeout(() => window.focus(), 0)); }); ``` ### 坑 3 · file:// vs https:// 行为差异 本地 file:// 测好的 cinematic 部署后可能崩，因为： - file:// 下 iframe contentDocument 同源 - https:// 下也同源（如果同 host），但 audio autoplay 限制更严格 **修复**： - 部署前用 `python3 -m http.server` 起本地 HTTP 测试一遍 - BGM 必须等用户点击 ▶ 后再 `bgm.play()`，不要 page-load 立刻播 --- ## 5 · 反 pattern 速查表 | ❌ 反 pattern | ✅ 正 pattern | |---|---| | 默认 = 黑屏 ▶ overlay | 默认 = 静态 dashboard，▶ 是辅助 | | 4 个 step 横排同屏 fade in | 5 个 scene 全屏切换，每场只 focus 一件事 | | 复用模板换文案做不同 demo | 每个 demo 独立视觉语言（盖文案能区分） | | emoji / SVG 手画当素材 | gpt-image-2 大图 + extract_grid 抠图 | | 无 BGM 无 SFX | BGM + 11 SFX cues 双轨制 | | 用 setTimeout 链 schedule | requestAnimationFrame + 全局时间轴 T 对象 | | linear 动画 | Expo / cubic-bezier easing | | 没有 dev 工具 | `?seek=N` + `?autoplay=1` + REPLAY 按钮 | | iframe 内的按钮被父 click zone 吞 | click zone 加 top/bottom margin 给按钮让位 | --- ## 6 · 时间预算 按这套 pattern，一个完整 cinematic demo（含 dashboard）： | 任务 | 时间 | |---|---| | 设计 5-scene narrative + 视觉语言 | 30 分钟（要慎重，决定独立性）| | Dashboard 静态布局 + 内容 | 1 小时 | | Cinematic 5 scenes 实现 | 1.5 小时 | | Audio cues 调时序 + replay 按钮 | 30 分钟 | | Playwright 截图验证 5 个关键时刻 | 15 分钟 | | **单个 demo 总计** | **3-4 小时** | 第二个 demo 复用框架但**视觉语言必须独立**，时间约 2-3 小时。 -
content-guidelines.md 8.2 KB
# Content Guidelines：反AI slop、内容准则、Scale规范 AI设计里最容易掉进去的陷阱。这是一份「不做什么」的清单，比「做什么」更重要——因为AI slop是默认值，你不主动避免就会发生。 ## AI Slop 完整黑名单 ### 视觉陷阱 **❌ 激进渐变背景** - 紫色 → 粉色 → 蓝色 全屏渐变（AI生成网页的典型味道） - 任何方向的rainbow gradient - Mesh gradient铺满背景 - ✅ 如果要用渐变：subtle、单色系、有意图地点缀（比如button hover） **❌ 圆角卡片 + 左border accent色** ```css /* 这是AI味卡片的典型签名 */ .card { border-radius: 12px; border-left: 4px solid #3b82f6; padding: 16px; } ``` 这种卡片在AI生成的Dashboard里泛滥。想做强调？用更有设计感的方式：背景色对比、字重/字号对比、plain分隔线、或者干脆不分卡片。 **❌ Emoji 装饰** 除非品牌本身使用emoji（比如Notion、Slack），否则不要在UI上放emoji。**尤其不要**： - 标题前的 🚀 ⚡️ ✨ 🎯 💡 - Feature列表的 ✅ - CTA按钮里的 →（箭头单独出现OK，emoji箭头不行） 没图标用真icon库（Lucide/Heroicons/Phosphor），或者用placeholder。 **❌ SVG 画 imagery** 不要试图用SVG画：人物、场景、设备、物品、抽象艺术。AI画的SVG imagery一眼就是AI味，幼稚且廉价。**一个灰色矩形+"插画位 1200×800"的文字标签，比一个拙劣的SVG hero illustration强100倍**。 唯一可以用SVG的场景： - 真正的icon（16×16到32×32级别） - 几何图形做装饰元素 - Data viz的chart **❌ 过多iconography** 不是每个标题/feature/section都需要icon。滥用icon会让界面像toy。Less is more。 **❌ "Data slop"** 编造的stats装饰： - "10,000+ happy customers" （你都不知道有没有） - "99.9% uptime" （没有真数据就别写） - 用图标+数字+词组成的装饰"metric cards" - Mock table里的假数据装点得花里胡哨 如果没真数据，留placeholder或问用户要。 **❌ "Quote slop"** 编造的用户评价、名人名言装饰页面。留placeholder问用户要真quote。 ### 字体陷阱 **❌ 避免这些烂大街字体**： - Inter（AI生成的网页默认） - Roboto - Arial / Helvetica - 纯system font stack - Fraunces（AI发现了这个就用滥了） - Space Grotesk（最近AI的最爱） **✅ 用有特点的display+body配对**。灵感方向： - 衬线display + 无衬线body（editorial feel） - Mono display + sans body（technical feel） - Heavy display + light body（contrast） - Variable font做hero的粗细动画 字体资源： - Google Fonts的冷门好选项（Instrument Serif、Cormorant、Bricolage Grotesque、JetBrains Mono） - 开源字体站（Fraunces的兄弟字体、Adobe Fonts） - 不要凭空发明字体名 ### 色彩陷阱 **❌ 凭空发明颜色** 不要从头设计一整套不熟悉的色彩。这通常不和谐。 **✅ 策略**： 1. 有品牌色 → 用品牌色，缺的color token用oklch插值 2. 没有品牌色但有参考 → 从参考产品截图吸色 3. 完全从零 → 选一个known的配色系统（Radix Colors / Tailwind默认palette / Anthropic brand），不要自己调 **oklch定义色彩**是最现代的做法： ```css :root { --primary: oklch(0.65 0.18 25); /* 温暖的terracotta */ --primary-light: oklch(0.85 0.08 25); /* 同色系浅色 */ --primary-dark: oklch(0.45 0.20 25); /* 同色系深色 */ } ``` oklch能保证调整亮度时色相不漂移，比hsl好用。 **❌ 夜间模式随手加反色** 不是简单invert颜色。好的dark mode需要重新调整饱和度、对比度、accent色。不想做dark mode就别做。 ### Layout陷阱 **❌ Bento grid 过度泛滥** 每个AI生成的landing page都想搞bento。除非你的信息structure确实适合bento，否则用其他layout。 **❌ 大hero + 3-column features + testimonials + CTA** 这个landing page模板被用烂了。想创新就真创新。 **❌ Card grid里每个card长一样** Asymmetric、不同大小的cards、有的带image有的只有文字、有的跨列——这才像真设计师做的。 ## 内容准则 ### 1. Don't add filler content 每个元素都必须earn its place。空白是设计问题，用**构图**解决（对比、节奏、留白），**不是**靠内容填满。 **判断filler的问题**： - 如果去掉这段内容，设计会变差吗？答案若是"不会"，就去掉。 - 这个元素解决了什么真问题？如果是"让页面不那么空"，删掉。 - 这个stats/quote/feature有真数据支持吗？没有就不要凭空写。 「One thousand no's for every yes」。 ### 2. Ask before adding material 你觉得多加一段/一页/一个section会更好？先问用户，不要单方面加。 原因： - 用户知道他的受众比你清楚 - 加内容有成本，用户可能不想要 - 单方面加内容违反了"junior designer汇报工作"的关系 ### 3. Create a system up front 探索完design context后，**先口头说出你要用的系统**，让用户确认： ```markdown 我的设计系统： - 色彩：#1A1A1A主体 + #F0EEE6背景 + #D97757 accent（来自你的品牌） - 字型：Instrument Serif做display + Geist Sans做body - 节奏：section title用full-bleed彩色背景 + 白字；普通section用白背景 - 图像：hero用full-bleed照片，feature section用placeholder等你提供 - 最多用2种背景色，避免杂乱 确认这个方向我就开始做。 ``` 用户确认后再动手。这个check-in能避免"做完一半发现方向错"。 ## Scale 规范 ### 幻灯片（1920×1080） - 正文最小 **24px**，理想 28-36px - 标题 60-120px - Section title 80-160px - Hero headline 可以用 180-240px 的大字 - 永远不要用 <24px 的字放幻灯片 ### 印刷文档 - 正文最小 **10pt**（≈13.3px），理想 11-12pt - 标题 18-36pt - Caption 8-9pt ### Web和移动端 - 正文最小 **14px**（老年人友好用16px） - 移动端正文 **16px**（避免iOS自动缩放） - Hit target（可点击元素）最小 **44×44px** - 行高 1.5-1.7（中文1.7-1.8） ### 对比度 - 正文 vs 背景 **至少 4.5:1**（WCAG AA） - 大字 vs 背景 **至少 3:1** - 用Chrome DevTools的accessibility工具检查 ## CSS 神器 **高级CSS特性**是设计师的好朋友，大胆用： ### 排版 ```css /* 让标题换行更自然，不会最后一行孤单单一个词 */ h1, h2, h3 { text-wrap: balance; } /* 正文换行，避免寡孀和孤儿 */ p { text-wrap: pretty; } /* 中文排版神器：标点挤压、行首行尾控制 */ p { text-spacing-trim: space-all; hanging-punctuation: first; } ``` ### Layout ```css /* CSS Grid + named areas = 可读性爆表 */ .layout { display: grid; grid-template-areas: "header header" "sidebar main" "footer footer"; grid-template-columns: 240px 1fr; grid-template-rows: auto 1fr auto; } /* Subgrid对齐卡片内容 */ .card { display: grid; grid-template-rows: subgrid; } ``` ### 视觉效果 ```css /* 有设计感的滚动条 */ * { scrollbar-width: thin; scrollbar-color: #666 transparent; } /* 玻璃拟态（克制使用） */ .glass { backdrop-filter: blur(20px) saturate(150%); background: color-mix(in oklch, white 70%, transparent); } /* View transitions API让页面切换丝滑 */ @view-transition { navigation: auto; } ``` ### 交互 ```css /* :has()选择器让条件样式变容易 */ .card:has(img) { padding-top: 0; } /* 有图片的卡片无顶padding */ /* container queries让组件真的响应式 */ @container (min-width: 500px) { ... } /* 新的color-mix函数 */ .button:hover { background: color-mix(in oklch, var(--primary) 85%, black); } ``` ## 决策速查：当你犹豫时 - 想加个渐变？→ 大概率不加 - 想加个emoji？→ 不加 - 想给卡片加圆角+border-left accent？→ 不加，换其他方式 - 想用SVG画个hero插画？→ 不画，用placeholder - 想加一段quote装饰？→ 先问用户有没有真quote - 想加一排icon features？→ 先问要不要icon，可能不需要 - 用Inter？→ 换一个更有特点的 - 用紫色渐变？→ 换一个有根据的配色 **当你觉得"加一下会更好看"的时候——那通常是AI slop的征兆**。先做最简的版本，只在用户要求时加。 -
critique-guide.md 8.8 KB
# 设计评审深度指南 > Phase 7 的详细参考。提供评分标准、场景侧重点、常见问题清单。 --- ## 评分标准详解 ### 0. 概念/立意（Concept）· 权重最高 先问「这个设计有没有一个idea」，再看做得好不好。为什么放第0位：执行是放大器，放大一个空洞的概念只会更空洞。 | 分数 | 标准 | |------|------| | 9-10 | 有一个从用户内容里长出来的独有idea，视觉母题不可替换 | | 7-8 | 有明确立意，母题与内容相关但换个近似主题也勉强能用 | | 5-6 | 只有风格没有概念：好看，但没说任何东西 | | 3-4 | 通用模板套皮，概念层为零 | | 1-2 | 连风格都没选对，纯装饰堆砌 | **核心问题清单**： - 这个设计说了什么？能用一句话讲出它的idea吗？讲不出来就没有 - 盖住所有文字和logo，还认得出主题吗？认不出说明视觉没承担表达（文字即母题的排版设计除外，改问：这套文字处理换个主题还成立吗） - 换个客户名/产品名还成立吗？**成立=模板，本维度直接≤5分** - form有没有来自内容的独有视觉母题？（呼应SKILL.md的form推导：形式该从内容推出来，不是从风格库里抽） **一票否决规则**：概念≤5分时，总评封顶6.0（良好档下限）。后面5个维度全是execution，execution再精致也拉不回一个没有idea的设计——那只是把模板打磨得更亮。 ### 1. 哲学一致性（Philosophy Alignment） | 分数 | 标准 | |------|------| | 9-10 | 设计完美体现了选定哲学的核心精神，每个细节都有哲学依据 | | 7-8 | 整体方向正确，核心特征到位，个别细节偏离 | | 5-6 | 能看出意图，但执行时混入了其他风格元素，不够纯粹 | | 3-4 | 仅在表面模仿，未理解哲学内核 | | 1-2 | 与选定哲学基本无关 | **评审要点**： - 是否使用了该设计师/机构的标志性手法？ - 色彩、字体、布局是否符合该哲学体系？ - 有没有「自相矛盾」的元素？（如选了Kenya Hara却塞满内容） ### 2. 视觉层级（Visual Hierarchy） | 分数 | 标准 | |------|------| | 9-10 | 用户视线自然沿设计者意图流动，信息获取零摩擦 | | 7-8 | 主次关系清晰，偶有1-2处层级模糊 | | 5-6 | 能分出标题和正文，但中间层级混乱 | | 3-4 | 信息平铺，没有明确的视觉入口 | | 1-2 | 混乱，用户不知道先看哪里 | **评审要点**： - 标题与正文的字号对比是否足够？（至少2.5倍） - 颜色/粗细/大小是否建立了3-4个清晰层级？ - 留白是否在引导视线？ - 「眯眼测试」：眯起眼看，层级是否仍然清晰？ ### 3. 细节执行（Craft Quality） | 分数 | 标准 | |------|------| | 9-10 | 像素级精确，对齐、间距、颜色无任何瑕疵 | | 7-8 | 整体精致，有1-2处微小对齐/间距问题 | | 5-6 | 基本对齐，但间距不统一，颜色使用不够系统 | | 3-4 | 明显的对齐错误、间距混乱、颜色过多 | | 1-2 | 粗糙，看起来像草稿 | **评审要点**： - 是否使用了统一的间距系统（如8pt网格）？ - 同类元素的间距是否一致？ - 颜色数量是否受控？（通常不超过3-4种） - 字体家族是否统一？（通常不超过2种） - 边缘对齐是否精确？ ### 4. 功能性（Functionality） | 分数 | 标准 | |------|------| | 9-10 | 每个设计元素都服务于目标，零冗余 | | 7-8 | 功能导向明确，有少量可删减的装饰 | | 5-6 | 基本可用，但有明显的装饰性元素分散注意力 | | 3-4 | 形式大于功能，用户需要努力寻找信息 | | 1-2 | 完全被装饰淹没，失去了传达信息的能力 | **评审要点**： - 删掉任何一个元素，设计会变差吗？（如果不会，就应该删） - CTA/关键信息是否在最显眼的位置？ - 是否有「因为好看所以加上去」的元素？ - 信息密度与载体是否匹配？（PPT不宜太密，PDF可以更密） ### 5. 创新性（Originality） | 分数 | 标准 | |------|------| | 9-10 | 令人耳目一新，在该哲学框架内找到了独特表达 | | 7-8 | 有自己的想法，不是简单的模板套用 | | 5-6 | 中规中矩，看起来像模板 | | 3-4 | 大量使用了cliché（如渐变圆球代表AI） | | 1-2 | 完全是模板或素材拼凑 | **评审要点**： - 是否避免了常见cliché？（见下方「常见问题清单」） - 在遵循设计哲学的同时是否有个人表达？ - 是否有「意想不到但很合理」的设计决策？ --- ## 场景评审侧重 不同输出类型的评审重点不同（概念维不在表内：它对所有场景都是第一道关，不参与侧重取舍）： | 场景 | 最重要维度 | 次重要 | 可放宽 | |------|-----------|--------|--------| | 公众号封面/配图 | 创新性、视觉层级 | 哲学一致性 | 功能性（单图不涉及交互） | | 信息图 | 功能性、视觉层级 | 细节执行 | 创新性（准确优先） | | PPT/Keynote | 视觉层级、功能性 | 细节执行 | 创新性（清晰优先） | | PDF/白皮书 | 细节执行、功能性 | 视觉层级 | 创新性（专业优先） | | 落地页/官网 | 功能性、视觉层级 | 创新性 | —（全面要求） | | App UI | 功能性、细节执行 | 视觉层级 | 哲学一致性（可用性优先） | | 小红书配图 | 创新性、视觉层级 | 哲学一致性 | 细节执行（氛围优先） | --- ## 常见设计问题 Top 10 ### 1. AI科技cliché **问题**：渐变圆球、数字雨、蓝色电路板、机器人脸 **为什么是问题**：用户已经对这些视觉疲劳，无法区分你和其他人 **修复**：用抽象隐喻替代直白符号（如用「对话」的隐喻而非聊天气泡图标） ### 2. 字号层级不足 **问题**：标题和正文差距太小（<2.5倍） **为什么是问题**：用户无法快速定位关键信息 **修复**：标题至少为正文的3倍（如正文16px → 标题48-64px） ### 3. 颜色过多 **问题**：使用5种以上颜色，没有主次 **为什么是问题**：视觉混乱，品牌感弱 **修复**：限制为1个主色+1个辅色+1个强调色+灰阶 ### 4. 间距不统一 **问题**：元素间距随意，没有系统 **为什么是问题**：看起来不专业，视觉节奏混乱 **修复**：建立8pt网格系统（间距只用8/16/24/32/48/64px） ### 5. 留白不足 **问题**：所有空间都被内容填满 **为什么是问题**：信息拥挤导致阅读疲劳，反而降低信息传达效率 **修复**：留白至少占总面积40%（极简风格60%+） ### 6. 字体过多 **问题**：使用3种以上字体 **为什么是问题**：视觉噪音，削弱统一感 **修复**：最多2种字体（1种标题+1种正文），用字重和大小创造变化 ### 7. 对齐不一致 **问题**：有的左对齐，有的居中，有的右对齐 **为什么是问题**：破坏视觉秩序感 **修复**：选定一种对齐方式（推荐左对齐），全局统一 ### 8. 装饰大于内容 **问题**：背景图案/渐变/阴影抢了主要内容的风头 **为什么是问题**：本末倒置，用户来看信息不是看装饰 **修复**：「如果删掉这个装饰，设计会变差吗？」如果不会，就删 ### 9. 赛博霓虹滥用 **问题**：深蓝底(#0D1117) + 霓虹色发光效果 **为什么是问题**：默认审美禁区（本 skill 的品位基线），且已成为最大 cliché 之一——用户可按自己品牌 override **修复**：选择更有辨识度的配色方案（参考20种风格的色彩系统） ### 10. 信息密度与载体不匹配 **问题**：PPT里放了一整页文字 / 封面图里塞了10个元素 **为什么是问题**：不同载体的最佳信息密度不同 **修复**： - PPT：每页1个核心观点 - 封面图：1个视觉焦点 - 信息图：分层展示 - PDF：可以更密，但需要清晰的导航 --- ## 评审输出模板 ``` ## 设计评审报告 **总体评分**：X.X/10 [优秀(8+)/良好(6-7.9)/需改进(4-5.9)/不合格(<4)] （概念≤5时总评封顶6分，先修概念再谈执行） **分项评分**： - 概念/立意：X/10 [这个设计的idea是什么？一句话讲出来] - 哲学一致性：X/10 [一句话说明] - 视觉层级：X/10 [一句话说明] - 细节执行：X/10 [一句话说明] - 功能性：X/10 [一句话说明] - 创新性：X/10 [一句话说明] ### 优点（Keep） - [具体指出做得好的地方，用设计语言描述] ### 问题（Fix） [按严重程度排序] **1. [问题名称]** — ⚠️致命 / ⚡重要 / 💡优化 - 当前：[描述现状] - 问题：[为什么这是问题] - 修复：[具体操作，含数值] ### 快速修复清单（Quick Wins） 如果只有5分钟，优先做这3件事： - [ ] [最有影响力的修复] - [ ] [第二重要的修复] - [ ] [第三重要的修复] ``` --- **版本**：v1.0 **更新日期**：2026-02-13 -
design-context.md 6.5 KB
# Design Context：从已有上下文出发 **这是这个skill最重要的one thing。** 好的hi-fi设计一定是从已有design context长出来的。**凭空做hi-fi是last resort，一定会产出generic的作品**。所以每次设计任务开始，先问：有没有可以参考的东西？ ## 什么是Design Context 按优先级从高到低： ### 1. 用户的Design System/UI Kit 用户自己产品已有的组件库、色彩token、字型规范、icon系统。**最完美的情况**。 ### 2. 用户的Codebase 如果用户给了代码库，里面就有活生生的组件实现。Read那些组件文件： - `theme.ts` / `colors.ts` / `tokens.css` / `_variables.scss` - 具体的组件（Button.tsx、Card.tsx） - Layout scaffold（App.tsx、MainLayout.tsx） - Global stylesheets **读代码抄exact values**：hex codes、spacing scale、font stack、border radius。不要凭记忆重画。 ### 3. 用户已发布的产品 如果用户有上线的产品但没给代码，用Playwright或让用户提供截图。 ```bash # 用Playwright截图一个公开URL npx playwright screenshot https://example.com screenshot.png --viewport-size=1920,1080 ``` 让你看到真实的视觉vocabulary。 ### 4. 品牌指南/Logo/已有素材 用户可能有：Logo文件、品牌色规范、营销物料、slide模板。这些都是context。 ### 5. 竞品参考 用户说"像XX网站那样"——让他提供URL或截图。**不要**凭你训练数据里的模糊印象做。 ### 6. 已知的design system（fallback） 如果以上都没有，用公认的设计系统作为base： - Apple HIG - Material Design 3 - Radix Colors（配色） - shadcn/ui（组件） - Tailwind默认palette 明确告诉用户你用的什么，让他知道这是起点不是定稿。 ## 获取Context的流程 ### Step 1：问用户 任务开始时的必问清单（来自`workflow.md`）： ```markdown 1. 你有现成的design system/UI kit/组件库吗？在哪？ 2. 有品牌指南、色彩/字体规范吗？ 3. 可以给我现有产品的截图或URL吗？ 4. 有codebase我可以读吗？ ``` ### Step 2：用户说"没有"时，帮他找 别直接放弃。尝试： ```markdown 让我看看有没有线索： - 你之前的项目有相关设计吗？ - 公司的marketing网站用什么色彩/字型？ - 你产品的Logo什么风格？能给我一张吗？ - 有什么你欣赏的产品作为参考？ ``` ### Step 3：Read所有能找到的context 如果用户给了codebase路径，你读： 1. **先list文件结构**：找style/theme/component相关的文件 2. **读theme/token文件**：lift具体的hex/px values 3. **读2-3个代表性组件**：看视觉vocabulary（hover state、shadow、border、padding node pattern） 4. **读global stylesheet**：基础重置、font loading 5. **如果有Figma链接/截图**：看图，但**更相信代码** **重要**：**不要**看了一眼就凭印象做。读下来有30+个具体values才真的lift到了。 ### Step 4：Vocalize你要用的系统 看完context后，告诉用户你要用的系统： ```markdown 根据你的codebase和产品截图，我提炼的设计系统： **色彩** - Primary: #C27558（从tokens.css） - Background: #FDF9F0 - Text: #1A1A1A - Muted: #6B6B6B **字型** - Display: Instrument Serif（从global.css的@font-face） - Body: Geist Sans - Mono: JetBrains Mono **Spacing**（来自你的scale系统） - 4, 8, 12, 16, 24, 32, 48, 64 **Shadow pattern** - `0 1px 2px rgba(0,0,0,0.04)`（subtle card） - `0 10px 40px rgba(0,0,0,0.1)`（elevated modal） **Border-radius** - 小组件 4px，卡片 12px，按钮 8px **component vocabulary** - Button：filled primary，outlined secondary，ghost tertiary，全部圆角8px - Card：白色背景，subtle shadow，无border 我按这套系统开始做。确认没问题？ ``` 用户确认后再动手。 ## 凭空做设计（没Context时的 fallback） **强烈警告**：这种情况下的产出质量会显著下降。明确告诉用户。 ```markdown 你没有design context，我就只能基于通用直觉做。 产出会是"看起来OK但缺乏独特性"的东西。 你愿意继续，还是先补一些参考材料？ ``` 用户执意要你做，按这个顺序做决策： ### 1. 选一个aesthetic direction 不要给generic结果。挑一个明确方向： - brutally minimal - editorial/magazine - brutalist/raw - organic/natural - luxury/refined - playful/toy - retro-futuristic - soft/pastel 告诉用户你选了哪个。 ### 2. 选一个known design system作为骨架 - 用Radix Colors做配色（https://www.radix-ui.com/colors） - 用shadcn/ui做组件vocabulary（https://ui.shadcn.com） - 用Tailwind spacing scale（4的倍数） ### 3. 选有特点的字体配对 不要用Inter/Roboto。建议组合（从Google Fonts白嫖）： - Instrument Serif + Geist Sans - Cormorant Garamond + Inter Tight - Bricolage Grotesque + Söhne（付费） - Fraunces + Work Sans（注意Fraunces已经被AI用烂） - JetBrains Mono + Geist Sans（technical feel） ### 4. 每个关键决策都有reasoning 不要默默选。在HTML的comment里写： ```html <!-- Design decisions: - Primary color: warm terracotta (oklch 0.65 0.18 25) — fits the "editorial" direction - Display: Instrument Serif for humanist, literary feel - Body: Geist Sans for cleanness contrast - No gradients — committed to minimal, no AI slop - Spacing: 8px base, golden ratio friendly (8/13/21/34) --> ``` ## Import策略（用户给了codebase） 如果用户说"import这个codebase做参考"： ### 小型（<50文件） 全部Read，把context内化。 ### 中型（50-500文件） Focus在： - `src/components/` 或 `components/` - 所有styles/tokens/theme相关的文件 - 2-3个代表性的整页组件（Home.tsx、Dashboard.tsx） ### 大型（>500文件） 让用户指明focus： - "我要做settings页面" → 读现有的settings相关 - "我要做一个新的feature" → 读整体shell + 最接近的参考 - 不求全，求准 ## 和Figma/设计稿的配合 如果用户给了Figma链接： - **不要**期望你能直接"转Figma为HTML"——那需要额外工具 - Figma链接通常不公开可访问 - 让用户：导出为**截图**发给你 + 告诉你具体的color/spacing values 如果只给了Figma截图，告诉用户： - 我能看到视觉，但取不到精确values - 关键数字（hex、px）请告诉我，或者export as code（Figma支持） ## 最后的提醒 **一个项目的设计质量上限，由你拿到的context质量决定**。 花10分钟收集context，比花1小时凭空画hi-fi更有价值。 **遇到没context的情况，优先问用户要，而不是硬上**。 -
design-styles.md 61.4 KB
# 设计风格库：网页 20 种 + PPT 20 种 + 信息图 20 种（HTML 原生优先） > **2026-06 重构**。基于对全球 10 大网站类型 + 10 大演示类型、各 top5 公认最佳设计（共 100 个真实案例）的调研反推。 > 旧版 20 种「平面/装置设计师哲学」库的致命问题：大胆风格几乎全是 AI-生成-only（粒子/光影/手绘），**用户默认无生图能力、default 全走 HTML 时，大胆半场直接清零，只剩极简——这是「default 千篇一律」的根因**。本库每一种都标了「纯 HTML/CSS 无生图」下的**还原度**。 > > ⚖️ **但记住定位**：这是**「没思路时翻的弹药」，不是「必须从这里选」的清单**。用户给了内容/品牌/参考，设计就从那里展开，别套库。skill 的职责是帮用户规避最差，不是规定好设计长什么样——好设计从用户的真实需求里长出来。 ## 这个库怎么用 1. **先按输出类型选分区（三选一，不是两选一）**：做网页/落地页/官网 → 网页 20 种；做 PPT/deck/演示 → PPT 20 种；做信息图/数据可视化/单张长图 → 信息图 20 种。 - 判据是**产出形态不是题材**：可点击的站点走网页区，要翻页的走 PPT 区，**一张(或一组)以数据为主角、能脱离交互独立阅读的图走信息图区**。 - 拿不准的两个常见情形：Dashboard 原型走网页区（它是产品界面）；一页 deck 里嵌的数据页仍走 PPT 区（它要翻页）。 2. **温度体系**：每种标了 `大胆 / 中性 / 安静`。**故意让大胆款占多数**——模型的确定性偏差天然偏安静极简，库的配比要把它往大胆推。 - 方向 A（稳妥底盘）从安静/中性里按需求选；方向 B 取不同温度拉反差；**方向 C 由 SKILL 的「秒数轮盘」强制注入大胆款**。 - ❌ 三个方向不要都落在「米白+留白+一个点缀色」——那是最常见的失败模式。 3. **还原度**：≥90% 闭眼做；70-90% 主体可做、个别细节降级；<70%（如 Memphis 做旧纹理）必须在产出里**明确标注哪部分用纯色块降级**，不假装能做出原版质感。 4. **字体**：每种给了开源替代（Inter/Geist/Manrope/Space Grotesk/Fraunces/Playfair 等），不要写付费字体（Söhne/Circular 等）。 5. 配套：SKILL「设计方向顾问」Phase 3-5 用本库推 3 方向；`assets/showcases/` 有预制截图画廊。 --- ## 色彩推导协议（用任何风格前先走这三步） > ⚠️ **以下所有风格条目里的 hex 是示例锚点，不是配方。** 同一风格用于不同内容，应通过本协议推导出不同色值——直接复制条目 hex，只是在生产品味更好的 slop。为什么：写死配方让 100 个用户拿到 100 份同色产出，色彩的信息量归零；推导让色彩成为「这个内容独有」的证据。 > > **字体同理**：条目里的字体名也是示例锚点。选定风格后，display+body 配对先过 `references/typography.md` 的配对逻辑与「已被用烂名单」——**名单与条目冲突时以 typography.md 为准**（如条目写 Fraunces，按名单换 Newsreader 等平替）。 ### 三步法：采样 → 收敛 → 论证 | 步骤 | 做什么 | 为什么 | |------|--------|--------| | **1. 采样** | 主色从三个来源取，不凭空发明：①品牌资产（logo/已有 VI 直接吸色）②内容真图（产品截图/摄影素材里的主导色）③文化语境（内容主题自带的色彩记忆，见下表） | 凭空选色=从模型先验里抽签，抽出来的永远是那几个网红色；从内容里采的色天然带「为什么」 | | **2. 收敛** | 用 oklch 把调色板压到 **2-3 个有彩色 + 1 组中性色**。中性色写成明度序列（如 L 0.15/0.35/0.65/0.92/0.98），有彩色之间拉开 oklch 色相角 H ≥60° 或明度 L 差 ≥0.3 | 色多必乱；oklch 的 L 通道感知均匀，明度序列写出来就是层级系统，比一堆孤立 hex 可推理 | | **3. 论证** | 一句话写出「为什么是这个色」，写进产出注释或交付说明。例：「主色取自用户 logo 的赭石，压低 chroma 到 0.08 模拟油墨」 | **写不出这句话=你在抄配方。** 论证是防 slop 的自检门，不是仪式 | ### 印刷色质感：为什么低饱和比纯屏幕色高级 油墨印在纸上永远达不到屏幕 RGB 的最大饱和度——CMYK 色域更窄、纸张吸墨、环境光反射，都会把颜色「压灰」。人眼几十年被印刷品训练出的「高级感」，本质是这层物理灰度。所以屏幕设计里刻意压 chroma，等于借用印刷的质感记忆。 | 用途 | oklch chroma 参考 | 效果 | |------|------------------|------| | 大面积底色 | 0.01–0.04 | 纸感、不刺眼 | | 品牌主色/强调 | 0.08–0.15 | 油墨感，够醒目但不塑料 | | 小面积点睛（按钮/链接） | 0.15–0.22 | 保留活力，仅限小面积 | | >0.25 满版铺 | 慎用 | 屏幕荧光感，只适合 Wrapped/糖果这类刻意「电子原生」的风格 | ### 文化语境速查：同一色相，不同语境 选色不只是选色相，是选它背后的文化坐标。同是「红」，落点差之千里： | 色相 | 语境 A | 语境 B | 差在哪 | |------|--------|--------|--------| | 红 | 故宫朱红（偏橙、带灰，oklch 低 L 低 C，比可乐红更暗更浊）→ 传统/庄重 | 可乐红（高饱和正红）→ 消费/兴奋 | chroma 一降，从货架跳到宫墙 | | 蓝 | 日本蓝染/琉璃绀（深、偏紫灰）→ 手工/沉静 | 科技蓝 #0066FF 系 → SaaS/效率 | 后者是模型最爱的默认蓝，用之前先问自己是不是在抽签 | | 绿 | 抹茶/苔绿（黄相、低饱和）→ 自然/日式 | 荧光绿 #39FF14 → 终端/hacker | 同为绿，一个喝茶一个敲代码 | | 黄 | 藤黄/芥末（带棕灰）→ 复古印刷 | 警示黄/Mailchimp 黄 → 醒目/玩味 | 灰度决定它是旧书页还是安全帽 | | 白 | 奶油纸白 #F5F0E8 → 出版物/暖 | 纯白 #FFF → 实验室/瑞士 | 底色的 2% 色温差就是气质分野 | --- ## 网页风格库(20种) #### 大胆派 **媒体级粗野主义 Editorial Brutalism（巨号Helvetica压小正文）** `大胆·还原98%` - 参考:Bloomberg Businessweek（Richard Turley 2010-2014 改版，Code and Theory操刀）；Neue Haas Grotesk谱系 - 适配:媒体/内容出版、AI产品发布、品牌官网hero、调研报告封面、观点型长文头图 - 视觉DNA:配色纯黑#000+纯白#FFF+超链接蓝#0000EE，点缀信号橙红#FF433D/终端绿#00A33E。字体Helvetica/Neue Haas Grotesk，120px+巨号headline左对齐紧字距直接压住14px小正文，极端字号反差。布局模块化网格+1px规则线分栏切割，高信息密度刻意不留白。标志元素：rule line分栏、超链接蓝下划线、黑白底大色块。 - HTML实现:纯CSS可1:1还原。CSS Grid做模块网格+border做规则线分栏，clamp()做超大响应式字号+letter-spacing收紧，系统Helvetica/Arial栈或Inter兜底，超链接直接#0000EE下划线。零素材依赖。 - 字体:Inter（替Helvetica/Neue Haas Grotesk），代码用Geist Mono **新粗野主义撞色信息流 Neo-Brutalism（粗黑描边卡片+高饱和撞色）** `大胆·还原95%` - 参考:The Verge 2022 redesign（in-house team，PolySans + Mānuka） - 适配:媒体/内容站、AI产品聚合页、活动landing、社区榜单页、小红书风信息卡 - 视觉DNA:配色电光紫#5200FF~品红#E1306C高饱和主色+亮黄#F8E000强调+纯黑#08080D+白，大面积撞色块刻意不柔和。字体几何无衬线大标题+衬线正文反差。布局卡片化feed流、2-4px粗黑描边、硬色块分区、近乎无圆角。标志元素：粗描边卡片hover撞色翻转、未完成界面气质。 - HTML实现:纯CSS强项。border:3px solid #000粗描边+box-shadow硬投影偏移(4px 4px 0 #000)+grid/flex卡片流+:hover切换background撞色翻转。无3D/光影障碍。 - 字体:Space Grotesk（替PolySans）+ 任一衬线如Fraunces **孟菲斯复古拼贴最大化 Memphis Maximalism（撞色块+错位叠放+复古字体）** `大胆·还原72%` - 参考:Gucci Vault概念店（Alessandro Michele）；Memphis设计运动 / Sagmeister叛逆基因 - 适配:电商概念店、创意活动页、品牌实验campaign、Y2K复古主题、节日营销页 - 视觉DNA:配色复古红/芥末黄/宝蓝/紫/橄榄绿大面积撞色并置+做旧米色暖底，浓烈刻意不和谐。字体复古衬线+装饰字混用、印刷质感、打破网格错位叠放。布局反网格拼贴策展、模块大小不一错落叠压、像逛数字房间。标志元素：撞色块、错位叠放、非常规导航彩蛋。 - HTML实现:transform:rotate()做错位叠放+position:absolute叠压+高饱和background撞色块+复古Google Fonts。真实做旧纹理无法CSS还原，降级为纯色块+mix-blend-mode/contrast滤镜模拟肌理，几何拼贴版成立、archival做旧版会降级。 - 字体:DM Serif Display + Bungee（装饰）+ Space Mono **糖果色凸起立体按钮游戏化 Friendly Geometric Candy** `大胆·还原85%` - 参考:Duolingo（Johnson Banks + Monotype，Feather Bold字体）；反硅谷极简 - 适配:教育语言学习、消费级App landing、游戏化产品、面向大众亲和产品、活动报名页 - 视觉DNA:配色Duo绿#58CC02+鸭子黄#FFC800+天蓝#1CB0F6糖果高饱和+白底，圆润友好。字体超粗圆体（Feather Bold感）。布局大圆角卡片、凸起3D按钮（底部硬阴影=可按压感）、吉祥物位+进度气泡。标志元素：3px实底阴影立体按钮、按下位移动画、超圆角。 - HTML实现:纯CSS。box-shadow:0 4px 0生硬底阴影做凸起按钮+:active translateY(4px)消阴影模拟按压，border-radius大圆角，纯色块。吉祥物无生图时用CSS几何形或emoji占位（轻微降级）。 - 字体:Baloo 2 / Nunito（超粗圆体替Feather） **纯CSS几何插画+响应式变形彩蛋 Pure-CSS Art** `大胆·还原80%` - 参考:Lynn Fisher（lynnandtonic.com，纯CSS艺术传奇，Adobe专文报道） - 适配:个人主页、创意404/彩蛋页、品牌玩味landing、技术博客头图、设计师自我展示 - 视觉DNA:配色2-4色高对比扁平面（每个breakpoint换调色）。字体粗几何无衬线标题。布局核心是「图随视口变形」——一组CSS形状在不同断点重组成不同画面（如建筑随屏宽变换层数）。标志元素：纯CSS绘制的几何插画、断点驱动的重排彩蛋、零图片。 - HTML实现:纯CSS的炫技战场，零素材是优势。div+border-radius/clip-path/transform/box-shadow堆叠几何形，@media断点改变形状尺寸位置实现变形。难度在设计构思而非技术，但需要精心手搓每个形状。 - 字体:Rubik / Archivo（粗几何替自定义） **巨型字黑白高对比时装大字报 Bold Big-Type Editorial** `大胆·还原88%` - 参考:Jacquemus官网 / Rik Oostenbroek / Domestika；时装杂志大字报 - 适配:电商时尚、作品集、媒体专题、品牌宣言页、视频课程封面、调研报告大字版 - 视觉DNA:配色极简黑白+单一克制点缀色（裸粉#E8C4C0或正红）。字体超大Display无衬线/高反差衬线，标题占满整屏。布局全幅网格、巨字与负空间博弈、图文1:1分割。标志元素：屏占比巨型headline、奢侈级留白、左右对位排版。 - HTML实现:纯CSS完美还原。clamp()巨号字+CSS Grid全幅分割+大量padding留白+vh单位让标题占满视口。无图时用纯色块/文字块替代时装大片占位（轻降级但版式成立）。 - 字体:Archivo Expanded / Anton（Display）+ Playfair Display（高反差衬线） **复古未来太空图录 Cosmic Retro-Futurism** `大胆·还原75%` - 参考:Perplexity Comet浏览器发布站（The Brand Identity：Black/Blue/Cream；《2001太空漫游》气质） - 适配:AI产品发布站、科技品牌宣言页、活动倒计时页、未来感landing、概念发布会 - 视觉DNA:配色纯黑#0A0A0A+奶油纸白cream#F0EAD8+一抹钴蓝-孔雀蓝#2B4F91，低饱和像老式天文图录。字体高反差衬线（古典天文图册感）+留白。布局线描轨道/抛物线SVG、行星圆点、奶油底压黑字、古籍式排印。标志元素：SVG天体轨道线、奶油+蓝+黑三色、复古衬线大字、天文图录质感。 - HTML实现:纯CSS+SVG还原静态版八成气质。SVG path画轨道抛物线+CSS径向定位行星圆点+三色变量+高反差衬线。缺口是「太空落到地球」的全屏视频转场（灵魂部分）——降级为CSS scroll视差+SVG轨道旋转近似。 - 字体:Cormorant Garamond / EB Garamond（高反差衬线）+ Space Mono **电影感声波可视化 Cinematic Sound-Viz Dark** `大胆·还原72%` - 参考:ElevenLabs；电影片头title sequence（Saul Bass式极简动态）× 音频工程界面 - 适配:音频/语音AI产品、音乐科技站、播客平台、媒体发布页、影院级品牌hero - 视觉DNA:配色纯黑#000底+纯白文字+蓝紫渐变accent波形。字体大号无衬线标题Saul Bass式极简。布局全幅暗场、声波/频谱可视化贯穿、巨标题压波形、卡片功能区。标志元素：彩色audio-waveform波形带、电影片头式极简、高对比黑白+单渐变、声音可视化母题。 - HTML实现:纯CSS+SVG还原70%气质（骨架完美，波形是降级点）。SVG polyline画静态波形或多条不等高div柱阵+CSS animation做『假波形』跳动近似。缺口：随声音实时跳动的Web Audio/Canvas频谱不可纯CSS还原，静态版像、动态灵魂还不了。 - 字体:Inter / Sora（大号无衬线） **像素游戏横版叙事 Pixel-Game Side-Scroller** `大胆·还原70%` - 参考:Robby Leonardi交互简历（8/16-bit平台动作游戏叙事，致敬任天堂SNES） - 适配:创意简历/作品集、品牌玩味campaign、游戏化landing、活动彩蛋页、个人趣味主页 - 视觉DNA:配色复古游戏多段分区——森林绿#4CAF50草地+天蓝#5DADE2，过渡太空紫#2C2A4A、火山橙红#E8743B、海底青#1ABC9C，每『关卡』换一套高饱和卡通调色。字体像素字体（8-bit感）+粗无衬线。布局横版/纵向滚动分关卡场景、视差分层、scroll触发位移。标志元素：分关卡换色、像素美学、视差滚动、游戏HUD式UI。 - HTML实现:纯CSS+少量JS还原骨架（原作就是HTML+CSS+jQuery无WebGL）。视差分层position+scroll位移、image-rendering:pixelated、CSS逐帧background-position做sprite动画、分段背景色。缺口：原创角色/场景手绘像素插画——无生图时用CSS方块拼简易像素图标替代（美术降级，技术不降）。 - 字体:Press Start 2P / VT323（像素字）+ Inter #### 中性派 **包豪斯几何标志+扁平插画系统 Bauhaus Geometric** `中性·还原90%` - 参考:Khan Academy rebrand（六边形+花瓣logomark + Wonder Blocks设计系统）；Bauhaus几何构成 - 适配:教育课程站、品牌logo系统、信息图、儿童亲和向产品、活动KV - 视觉DNA:配色三原色谱系——包豪斯红#E63946/黄#FFB703/蓝#0077B6+黑白，纯色块拼接。字体几何无衬线（圆润几何感）。布局圆/三角/方基本几何单元搭建插画，对齐栅格、模块化拼图。标志元素：纯几何形态logomark、扁平无渐变插画、原色块构成。 - HTML实现:纯CSS几何全能。border-radius:50%做圆、clip-path/border三角形、方块div拼几何插画，CSS Grid栅格对齐，纯色fill无需素材。插画用CSS形状或内联SVG几何路径手搓。 - 字体:Poppins / Manrope（几何圆润替Wonder Blocks） **暗色双色侧栏开发者作品集 Dark Editorial（深底+单荧光accent+等宽字）** `中性·还原96%` - 参考:Brittany Chiang（brittanychiang.com v4，dev portfolio事实标准） - 适配:作品集个人主页、开发者向产品、技术品牌站、简历页、AI工具landing - 视觉DNA:配色深墨绿/海军底#0A192F+板岩灰文字#8892B0+单一荧光青绿accent#64FFDA。字体无衬线正文+等宽字（编号/标签）。布局左固定侧栏导航+右滚动主区双栏，section编号01/02、链接hover下划线滑入。标志元素：单accent色、等宽编号标签、侧栏锚点高亮。 - HTML实现:纯CSS完全还原。position:sticky做固定侧栏+CSS Grid双栏+单accent变量+等宽字标签+:hover下划线transform滑入。零素材，纯版式与微交互。 - 字体:Inter + JetBrains Mono（等宽） **暖色出版物 Warm Editorial（奶油纸底+赤陶橙+衬线无衬线混排）** `中性·还原97%` - 参考:Anthropic / Claude（DBCo + Geist Studio，Styrene×Tiempos）；Penguin/Pelican平装书排印 - 适配:AI产品站、品牌官网、长文阅读页、橙皮书电子书、调研报告、培训材料 - 视觉DNA:配色奶油纸底#F5F0E8+赤陶橙#CC785C/#D97757点缀+近黑文字#191919，温暖低饱和。字体衬线标题（Tiempos感）×无衬线正文（Styrene感）混排。布局书籍式单栏阅读流、舒适行高、节制分隔线。标志元素：纸感暖底、赤陶橙、出版级排印节奏。 - HTML实现:纯CSS 100%还原，零素材。背景色变量+衬线无衬线字体栈混排+max-width限制阅读宽度+line-height 1.7舒适行高。这是Anthropic赤陶橙暖色版的安全主场。 - 字体:Fraunces / Newsreader（替Tiempos衬线）+ Inter（替Styrene） **Linear暗色发光+Bento网格 Glassmorphism Bento** `中性·还原85%` - 参考:Linear / Cursor（'The Linear Look'现象级流派，Frontend Horse有代码配方） - 适配:SaaS/AI产品站、开发者工具、技术品牌hero、产品功能展示、深色dashboard演示 - 视觉DNA:配色近黑底#08090A+去饱和蓝紫品牌#5E6AD2+低饱和青紫微光渐变#4EA7FC→#B59AFF。字体几何无衬线负字距紧凑。布局便当盒bento网格分块、发丝分割线、玻璃拟态卡片。标志元素：暗底发光渐变边框、bento分块、流光streamer、磨砂玻璃。 - HTML实现:纯CSS强还原。box-shadow/filter blur+radial-gradient做发光晕，backdrop-filter:blur玻璃拟态，conic/linear-gradient边框，CSS Grid拼bento。缺口仅「真实产品UI截图」——用色块+文字拼简化假UI替代（这部分降级）。 - 字体:Inter / Geist（负字距）+ Geist Mono **斜切流体渐变带 Angled Fluid Gradient** `中性·还原92%` - 参考:Stripe（标志性angled gradient banner，Klim定制Söhne字体） - 适配:SaaS/Fintech落地页、品牌官网hero、产品发布页、活动banner、AI产品营销页 - 视觉DNA:配色多色流体渐变（靛蓝#635BFF→青→粉→橙暖调）做hero背景+纯白内容区+近黑文字。字体精致无衬线（Söhne感）。布局倾斜分割色块（skew切角分区）、渐变hero压结构化栅格正文。标志元素：angled斜切边界、多色流体渐变、理性栅格压表达渐变。 - HTML实现:纯CSS。transform:skewY()或clip-path:polygon()做斜切分区，linear-gradient多色叠加（可加CSS animation缓慢流动）做流体渐变带，Grid做下方结构化正文。零素材。 - 字体:Inter / Hanken Grotesk（替Söhne） **实用主义彩虹分类文档 Utility-First Colorful Docs** `中性·还原98%` - 参考:Tailwind CSS Docs（Sky/Cyan品牌色+功能分类彩虹色相条） - 适配:技术文档、API参考、设计系统站、教程站、开发者knowledge base、SaaS帮助中心 - 视觉DNA:配色Sky蓝#38BDF8品牌+teal→cyan→sky青蓝渐变+Slate灰阶#0F172A/#64748B/#F8FAFC，文档用彩虹色相条区分功能分类（粉#EC4899/紫#A855F7/绿#10B981/橙）。字体清爽无衬线+等宽代码。布局左侧栏导航+中正文+右TOC三栏，彩色高亮代码块、分类色标。标志元素：青蓝渐变hero、彩虹分类色、三栏文档骨架、语法高亮代码块。 - HTML实现:纯CSS 98%还原（它本身就是CSS框架文档）。Grid三栏+linear-gradient青蓝hero+分类色变量+代码块语法色用span着色。Inter开源，唯暗色切换/copy需轻量JS。零光影/3D/手绘。 - 字体:Inter + JetBrains Mono / Fira Code（代码） **终端核软未来 Terminal-Core Soft-Futurism（等宽字+等距立方）** `中性·还原80%` - 参考:Cursor (Anysphere)；开发者终端美学 × Teenage Engineering工业极简 - 适配:AI编程工具站、CLI产品landing、开发者基础设施、技术品牌hero、终端类产品 - 视觉DNA:配色炭黑#0B0D14底+暖白文字#F2F0EF+克制蓝紫渐变accent点缀按钮与光晕。字体等宽字为主角（命令行感）+无衬线辅助。布局命令行/代码块前景、bento分区、2.5D等距cube示意。标志元素：等宽字命令行、等距投影立方体、暖白×炭黑、克制渐变光晕、工业极简。 - HTML实现:纯CSS 80%还原。等宽字代码块+暗色bento+box-shadow光晕；2.5D等距cube用CSS 3D transform(rotateX/Y+skew)或SVG等距投影手搓。缺口：可点击切换的多界面demo需JS+假UI拼接。无WebGL刚需。 - 字体:Geist Mono / JetBrains Mono（主角）+ Inter（辅助） #### 安静派 **功能主义网格社区 Functional Brutalism（灰线分割+系统字+蓝链接）** `安静·还原98%` - 参考:Are.na / Lobsters / Quartz；Müller-Brockmann栅格数字落地 + Tufte信息密度 - 适配:社区/UGC平台、内容聚合站、文档知识库、移动优先内容流、极客向产品 - 视觉DNA:配色近白底#FBFBFB+黑文字+1px灰分割线#E0E0E0+经典链接蓝#0000EE/已访问紫。字体系统字栈（-apple-system/无装饰）。布局高密度信息列表、细灰线分栏、极小留白、紧凑行距。标志元素：发丝灰分割线、蓝链接、系统字、信息密度优先。 - HTML实现:纯CSS最易还原，这是Brutalist Web的本色。border-bottom:1px灰线列表+system-ui字栈+紧凑padding+蓝链接。几乎不需要任何素材或JS，纯结构。 - 字体:system-ui系统字栈 / IBM Plex Sans（兜底） **深色画廊裱框 Gallery Dark（深黑负空间+单列大图+EXIF小字）** `安静·还原75%` - 参考:Glass (glass.photo) / Bottega Veneta；美术馆暗房 + Apple Photos内容至上 - 适配:摄影作品集、奢侈品电商、视觉内容沉浸展示、个人画廊页、高端产品陈列 - 视觉DNA:配色纯黑底#0A0A0A+作品图本身提供唯一色彩+极淡灰EXIF小字#666。字体极细无衬线小字。布局单列居中大图、巨幅负空间裱框、图下metadata小字。标志元素：暗房黑底、内容至上UI退隐、EXIF式小字注脚、大图独占视口。 - HTML实现:纯CSS还原版式骨架。纯黑底+居中max-width单列+巨幅padding裱框留白+小字metadata。缺口是「真实摄影作品」本身——用占位图/纯色块代替则失灵魂，但暗房氛围与版式100%可搭。 - 字体:Inter（细字重300）/ Cormorant（衬线奢侈感可选） **Swiss极致黑白 Swiss Monochrome（Vercel式纯黑白+Geist+锐利边角）** `安静·还原98%` - 参考:Vercel / Next.js Docs（自研Geist已开源）；Massimo Vignelli少即是多 - 适配:开发者工具文档、技术品牌官网、AI产品站、SaaS落地页、极简调研报告 - 视觉DNA:配色纯黑#000+纯白#FFF+灰阶#888，零彩色或仅一抹蓝链接。字体Geist几何无衬线+Geist Mono。布局锐利直角（无圆角或极小）、高对比、精密栅格、克制留白。标志元素：纯黑白、锐利边角、Geist字体、三角/箭头几何标记。 - HTML实现:纯CSS 100%还原，Geist开源可直接引。CSS Grid精密栅格+纯黑白变量+border-radius:0锐角+发丝边框。这是HTML最舒适的极简主场，零素材依赖。 - 字体:Geist + Geist Mono（Vercel开源原版） **日式留白白盒画廊 Kenya Hara White Gallery** `安静·还原80%` - 参考:Cosmos (cosmos.so) / Aesop伊索官网；原研哉『白』的空寂 + 瑞士网格混血 - 适配:高端电商、创意画廊、内容策展平台、设计师作品集、品牌精品店、moodboard站 - 视觉DNA:配色近全白#FAFAFA底+纯黑文字#0A0A0A+极淡灰分割#EFEFEF，内容图提供全部色彩、UI退到背景。字体极简系统/几何无衬线小字、大字距。布局masonry瀑布网格、极致留白、淡灰发丝分隔、东方空寂。标志元素：白盒美学、奢侈留白、内容至上UI隐退、瀑布流策展。 - HTML实现:纯CSS还原静态版式（与暗色画廊区分在『白』）。CSS columns或Grid做masonry+近白变量+大padding留白+淡灰分隔。缺口是Lenis/GSAP丝滑惯性滚动与图片入场缓动（高级感60%在此），CSS仅基础transition，动效层降级。 - 字体:Inter（细字重）/ Cooper Hewitt（Aesop同款开源） ## PPT风格库(20种) #### 大胆派 **新瑞士大字报 / Neo-Swiss Billboard Editorial** `大胆·还原98%` - 参考:Scribe $75M、Flock Safety $47M 等 AI/SaaS 路演 deck 的 Big-Number Editorial 流派；Bloomberg Businessweek 信息图；Pentagram - 适配:融资路演、QBR/业务回顾、年度趋势复盘、产品发布关键页 - 视觉DNA:配色=纯白(#FFFFFF)或近黑(#0A0A0A)底+单一高饱和强调色(电光蓝#2D5BFF/荧光绿#00E676/品牌橙#FF6B2C)+中性网格线#E5E5E5。字体=超大粗体无衬线，标题占半屏，数字tabular-nums等宽收紧字距。母版=①大色块章节页一个词②巨型数字占半屏(3.2x)+小注③左右分栏对比④全幅扁平折线/柱状。标志=billboarding大字、严格基线网格、大色块章节页 - HTML实现:超大数字用clamp()；严格网格用CSS Grid；大色块章节页background-color；折线柱状用纯div+CSS或内联SVG(比贴图更锐利)；数字对齐font-variant-numeric:tabular-nums。零插画零3D - 字体:Inter / Geist / Söhne替代Neue Haas Grotesk；数字配Geist Mono **黑底巨型数字剧场 / Black Big-Number Stage** `大胆·还原97%` - 参考:Steve Jobs 2007 iPhone Keynote、小米SU7 Ultra雷军发布会、Spotify Wrapped、Presentation Zen(Garr Reynolds) - 适配:产品发布主题演讲、思想演示、全员town hall、情绪向年度回顾 - 视觉DNA:配色=纯黑#000000底+纯白#FFFFFF字高反差，一页只一个品牌强调色高亮(小米橙#FF6900/Spotify绿#1ED760/Apple蓝#2997FF)。字体=几何无衬线粗体，一屏一词或一个超大数字占满视野，字距收紧。母版=①标题页黑底居中一行大字②数据高潮页巨型数字+单位+一行注③左右参数对比双栏(强调色vs灰)④slogan单页。大量负空间 - HTML实现:黑底白字几行CSS；巨型数字clamp()+flex居中；强调色highlight单独span；左右对比CSS Grid两列+条形高亮；tabular-nums。去掉产品照改纯文字反而更接近Zen本质 - 字体:Geist / Inter / 思源黑替代SF Pro **高饱和单色品牌撞色海报 / Mono-Brand Type-as-Hero** `大胆·还原96%` - 参考:Spotify Wrapped视觉系统、Mailchimp Brand Book(Collins)、Netflix红黑现代复刻、COLLINS品牌系统 - 适配:品牌/营销策略、campaign宣讲、town hall文化页、活动主视觉 - 视觉DNA:配色=单一品牌主色满版铺底(Spotify绿#1ED760/Mailchimp黄#FFE01B/Netflix红#E50914)+黑或白反差字，撞色两层。字体=超大字体即主视觉(type-as-hero)顶天立地。母版=①满色块底+反白巨字②双色块上下/左右分割③巨型数字撑满。标志=单色满版、字体当图、高对比撞色 - HTML实现:满版background-color；超大字clamp()占满；双色用两个100vh色块；字体当图靠font-weight900+负letter-spacing。纯色块零素材，HTML原生最爽 - 字体:Inter / Manrope / Archivo(超粗)替代Circular/Cavendish **全幅渐变宣言版式 / Full-Bleed Gradient Manifesto** `大胆·还原82%` - 参考:Zuora『Tell a Different Story』销售deck(Andy Raskin拆解)、Nike『Just Do It』campaign、National Geographic跨页 - 适配:销售提案愿景页、品牌宣言、keynote转折页、使命愿景单页 - 视觉DNA:配色=满版CSS渐变(暖橙→品红/深蓝→青)或纯色出血+反白宣言大字+hashtag口号(#shifthappens)。字体=厚重无衬线全大写标语横贯。母版=①满幅渐变+居中反白宣言②应许之地愿景页③客户logo墙。标志=full-bleed出血、反白大标语、hashtag口号 - HTML实现:linear-gradient/radial-gradient满版(不做粒子/光影，纯CSS渐变是允许的)；反白字position居中；logo墙用grid灰度SVG/文字占位。原本靠纪实大照片的部分降级为CSS渐变铺底+大字，照片缺失这一项还原度降约15% - 字体:Archivo / Anton / Manrope(超粗) **CS50单概念糖果舞台 / Candy-Color Lecture Stage** `大胆·还原94%` - 参考:Harvard CS50(David Malan)、Lessig Method/高桥流、Presentation Zen - 适配:教育课件、技术讲座、概念解释、代码教学 - 视觉DNA:配色=深黑底#0A0A0A+高饱和糖果色大字轮换(品红#FF2D95/青#00E5FF/明黄#FFD500/绿#39FF14)。字体=无衬线超大字漂浮居中，一屏一概念，文字极少。母版=①深黑底单个糖果色大词②等宽代码块语法高亮③舞台聚光感大字。标志=深黑漂浮糖果色大字、等宽代码高亮、强舞台聚光、极少文字 - HTML实现:深黑背景+单色超大字clamp()居中；代码块用pre+等宽字+span上色做语法高亮；聚光感用极淡radial-gradient暗角(非粒子光效)。还原度高 - 字体:Inter超粗 + JetBrains Mono(代码) **玩味手绘极简 / Playful Maximalist Editorial (Collins式)** `大胆·还原75%` - 参考:Mailchimp Brand Book(Collins 2018)、New Yorker漫画气质、Cooper圆润衬线、Cavendish荧光黄 - 适配:有态度的品牌deck、创意机构提案、文化向town hall、反SaaS极简的营销页 - 视觉DNA:配色=Cavendish荧光黄#FFE01B大面积+黑+少量撞色，反SaaS极简。字体=Cooper式圆润衬线大标题(playful)+杂志式留白编排。母版=①荧光黄满底+怪诞标题②杂志式不规则留白排版③大字玩梗文案。标志=荧光黄、圆润衬线、playful编排、怪诞手绘气质(降级为几何色块/emoji替代真插画) - HTML实现:荧光黄background；圆润衬线font-family；杂志留白用非对称Grid。手绘猩猩/插画这一核心元素无AI生图无法做，降级为CSS几何色块+大号emoji+不规则transform旋转的文字块替代，插画缺失还原度降约20% - 字体:Fraunces(可调圆润)/ Bree Serif替代Cooper；正文Inter **不羁玩梗流行版 / Irreverent Pop (Reddit式)** `大胆·还原80%` - 参考:Reddit Ads销售deck(被Dock列为最有性格)、David Carson式不羁排版、90年代web复古、Memphis玩味 - 适配:Z世代品牌、玩梗营销deck、社区/创作者向、敢于不正经的提案 - 视觉DNA:配色=Reddit橙红#FF4500+撞色，90s web复古色。字体=混排/打破网格的David Carson式排版，玩梗口语文案。母版=①fun页玩梗大字②facts页节奏转折严肃数据③口语标题。标志=打破网格混排、橙红、玩梗口语、fun→facts节奏反转、复古web质感 - HTML实现:故意打破网格用transform旋转/重叠定位/混合字号；橙红+撞色块；复古质感用粗黑边border+硬阴影box-shadow(无blur)。自定义meme插画降级为emoji+几何拼贴，但混排排版本身HTML可还原 - 字体:Archivo / Space Grotesk + 混搭Inter制造对比 **Y2K膨胀大字 / Maximalist 3D-Type (Wrapped式)** `大胆·还原78%` - 参考:Spotify Wrapped 2022/2023/2025、Memphis撞色、Y2K/Maximalism、duotone人像渐变 - 适配:年度回顾(情绪出圈向)、个性化数据卡、社交分享竖屏卡、品牌年终 - 视觉DNA:配色=高饱和撞色满版背景(品红+青+橙)+Spotify绿点睛+duotone双色渐变。字体=顶天立地巨型数字，年份/数字做3D膨胀/金属质感。母版=①撞色满版+巨型膨胀数字②duotone人像/色块底+反白大字③竖屏可分享卡。标志=巨型膨胀3D数字、撞色满版、duotone渐变、年份金属质感、竖屏story卡 - HTML实现:撞色满版background；3D膨胀数字用CSS text-shadow多层叠加+transform:perspective或SVG+stroke制造立体(非真3D渲染)；duotone用mix-blend-mode+渐变叠在灰度图占位块上。金属质感降级为渐变填充文字background-clip:text，还原度降约15% - 字体:Archivo Black / Anton超粗 + 数字Clash Display #### 中性派 **Bento便当格模块网格 / Bento Grid** `中性·还原95%` - 参考:Apple Keynote Bento Grid时代、新一代MBB Bento/Big-Type deck(2024-2026)、Stripe年报指标卡矩阵、Pitch.com QBR模板 - 适配:产品功能汇总、咨询/QBR数据汇报、销售成果页、town hall指标页 - 视觉DNA:配色=浅灰/奶白底(#F5F5F7/cream)或近黑底+品牌主色+1-2强调色，卡片浅色分区底+圆角+微描边/微阴影。字体=超大display标题+常规正文，字重对比强烈，KPI数字tabular figures。母版=①标题页巨型单句+留白②bento页2×2/3列不等高卡片每卡一洞见(数字/线性icon/sparkline)③one-insight超大数字页。标志=不等高卡片网格、圆角微描边、呼吸感 - HTML实现:CSS Grid的grid-template-areas做不等高bento；卡片border-radius+box-shadow微阴影+1px hairline；sparkline用内联SVG；线性icon用inline SVG stroke。零贴图 - 字体:Inter / Geist + 数字Geist Mono **Neo-Swiss暗色终端美学 / Dark Hairline Terminal** `中性·还原94%` - 参考:Linear pitch deck、Vercel设计语言、CS50深黑舞台课件；字体Inter Tight+JetBrains Mono - 适配:开发者工具/技术产品发布、技术路演、工程向汇报 - 视觉DNA:配色=近黑底(#0D0D0F/#111113)+hairline细线#262629网格+单一紫蓝强调(#5B5BD6/#7C7CFF)。字体=Inter Tight大标题+JetBrains Mono做标签/数据。母版=①极简标题页一句话+mono小标②hairline分隔的数据网格③mono标签的特性列表。标志=1px细线网格、mono单等宽标签、极致留白、近黑非纯黑 - HTML实现:近黑背景+border:1px solid的hairline网格；mono标签用等宽font-family；微光用极淡box-shadow/border highlight而非真光效(降级避开赛博霓虹禁区)。注意避开#0D1117深蓝禁区，用中性近黑 - 字体:Inter Tight + JetBrains Mono / IBM Plex Mono **双字体咨询版 / Two-Font Consulting (Bower式)** `中性·还原90%` - 参考:McKinsey 2019品牌系统(Wolff Olins设计，Bower衬线+无衬线)、BCG Executive Perspectives、深蓝细线pattern - 适配:咨询报告、高管汇报、行业研究、权威机构提案 - 视觉DNA:配色=深蓝(#051C2C/McKinsey深蓝)×白二元+单一品牌色高亮(BCG绿#00805A)，暖灰底带呼吸感。字体=characterful衬线大标题(Bower式)与无衬线正文高对比并置。母版=①左上角结论式action-title②蓝色细线pattern装饰③杂志式左右分工(结论文字+视觉)④大数字data-point卡。标志=衬线×无衬线高对比、深蓝细线pattern、action-title、暖灰高级感 - HTML实现:双字体font-family并置(衬线标题+无衬线正文)；细线pattern用repeating-linear-gradient或SVG line；data-point卡纯CSS；照片灰度处理这一项无照片可省。蓝紫edge shimmer降级为纯色边 - 字体:Playfair Display / Fraunces衬线标题 + Inter正文(替代Bower) **图谱箭头企业版 / Diagram-Driven Isotype** `中性·还原88%` - 参考:Salesforce销售deck、Isotype(Otto Neurath)谱系、Gene Zelazny《Say It With Charts》、Hans Rosling/Gapminder - 适配:平台/架构讲解、客户旅程、流程方法论、生态地图 - 视觉DNA:配色=企业蓝色块+产品线分色区分+图标化能力网格。字体=清晰无衬线。母版=①横向客户旅程箭头流②分层平台架构图③图标化能力网格④2×2/瀑布/金字塔结构图。标志=箭头流程、分层架构盒、Isotype图标网格、流程即叙事 - HTML实现:箭头流程用Flexbox+CSS clip-path三角或SVG arrow；架构分层用嵌套带边框div；图标用inline SVG stroke统一描边；瀑布/金字塔用Grid+斜切。气泡图可用CSS圆形+定位。纯矢量绘制 - 字体:Inter / IBM Plex Sans(图表友好) **单图母图概念图解 / Diagrammatic Minimalism** `中性·还原95%` - 参考:Simon Sinek黄金圆环(Golden Circle)TED、Bauhaus几何抽象、信息建筑『一图定全场』 - 适配:理论框架讲解、TED式思想传播、模型/方法论可视化、单概念keynote - 视觉DNA:配色=极简白/浅底+黑+1个强调色，几何纯色。字体=无衬线，标签大写嵌入图形。母版=①唯一几何母图(同心圆/三角/矩阵)承载全部概念②由内向外箭头③对比案例。标志=单一几何母图、嵌套同心圆/三角、大写标签、一图承载概念 - HTML实现:同心圆用border-radius:50%嵌套div或SVG circle；三角用clip-path/SVG polygon；箭头SVG marker；标签absolute定位贴在图形上。纯几何，HTML完美还原 - 字体:Manrope / Futura系(Jost开源替代)几何感 **Sparkline叙事波形 / Narrative Sparkline (Duarte式)** `中性·还原91%` - 参考:Nancy Duarte《Resonate》Sparkline叙事图谱、Al Gore《An Inconvenient Truth》、Duarte Inc.数据叙事 - 适配:演讲结构设计、变革叙事、before/after对照、数据故事弧线 - 视觉DNA:配色=深底或白底+品牌橙强调转折点+灰化对照。字体=无衬线，annotation标注点。母版=①横贯全屏的振荡波形线②波形上text标注点③上下并置对照波形④全黑底孤悬一条数据线⑤逐步reveal。标志=横贯波形线、波形标注点、橙色转折、对照波形、爬出画面的曲线 - HTML实现:波形线用内联SVG path(平滑贝塞尔)；标注点用SVG circle+text定位；对照波形上下两条path；reveal用CSS动画stroke-dashoffset。纯SVG绘制无素材 - 字体:Inter + 数字Geist Mono #### 安静派 **断言-证据 / Tufte信息设计** `安静·还原93%` - 参考:Michael Alley Assertion-Evidence(Penn State实证)、McKinsey/BCG action-title、Edward Tufte数据墨水比、Barbara Minto金字塔原理 - 适配:学术/工程汇报、数据严谨型咨询页、政策研报、技术评审 - 视觉DNA:配色=白/极浅灰底+黑正文+单一克制强调色(深蓝/砖红)。字体=整句话标题(非名词短语)，标题下独占一张图，文字标注嵌进图里。母版=①整句action-title②标题下单图证据③零bullet。标志=整句标题、单图证据、嵌入式标注、零chartjunk、高数据墨水比 - HTML实现:整句标题靠排版层级；图表用纯CSS/内联SVG画极简折线散点(去网格线去图例，标注直接text定位在数据点旁)；零装饰。Tufte的克制正是HTML强项 - 字体:Source Serif / Lora标题 + Inter正文(双字体阅读级) **瑞士机构极简 / Institutional Swiss Minimal** `安静·还原96%` - 参考:Sequoia官方10页pitch模板、Airbnb 2009种子轮deck、Müller-Brockmann网格、Massimo Vignelli - 适配:投资路演、标准商业提案、问题-解法叙事、品牌去装饰提案 - 视觉DNA:配色=纯白底+黑灰正文+单一品牌强调色(Airbnb珊瑚红#FF5A3C/中性蓝)。字体=Helvetica系无衬线，标题中号粗体一句话，正文短句大间距。母版=①居中logo+slogan②顶部一句话标题带+下方3栏对仗(Problem/Solution三点)③TAM大数字分层④2×2竞品矩阵。标志=顶部标题带、三栏对仗、单色强调、2×2矩阵 - HTML实现:Flexbox三栏对仗；2×2矩阵纯CSS Grid+border画；TAM分层用嵌套div或同心方块；一页一信息。几乎纯排版网格，HTML理想对象 - 字体:Inter / Helvetica Now替代Helvetica；正文Inter **杂志编辑长文流 / Editorial Longform** `安静·还原95%` - 参考:Stripe Annual Letter($1.9T)、Amazon六页叙事备忘录、Benedict Evans『X eats the world』、Stripe Press - 适配:年度信/复盘叙事、深度思想长文、内部更新、研报型阅读物 - 视觉DNA:配色=奶白/米白底(#FBFAF8)+深墨字+品牌色点睛(Stripe紫#635BFF)。字体=衬线或高品质无衬线，散文体段落+内联数据卡，超大display数字穿插。母版=①刊头大标题②多栏散文+内联指标卡③超大数字段落锚点。标志=出版物阅读节奏、内联数据卡、克制留白、散文体而非bullet - HTML实现:多栏column-count或Grid；内联数据卡float/inline-block嵌入正文；衬线正文max-width控制行宽65ch；超大数字穿插。纯排版，零素材 - 字体:Newsreader / Source Serif正文 + Inter辅助；数字tabular **人文圆角卡片 / Humanist Rounded Cards (Khan式)** `安静·还原80%` - 参考:Khan Academy Wonder Blocks设计系统、Source Serif Pro衬线、森林绿品牌、友善人文主义 - 适配:教育产品、亲和力课件、公益/非盈利deck、温暖品牌提案 - 视觉DNA:配色=森林绿#14BF96/#0A5C4B+米白底+暖色辅助，柔和不刺眼。字体=Source Serif衬线标题(人文气)+无衬线正文。母版=①圆角卡片组件组②衬线标题+亲和正文③真实摄影位(降级为绿色系几何/圆角色块)。标志=森林绿、衬线标题、大圆角卡片、人文温暖、不完美亲和质感 - HTML实现:大圆角border-radius卡片+柔和box-shadow；衬线标题font-family；暖米白底。真实师生摄影这一项无AI生图，降级为绿色系几何插画块/大圆角纯色占位+emoji人物，照片缺失还原度降约18% - 字体:Source Serif 4标题 + Nunito Sans / Inter正文(Nunito圆润呼应人文) **研报密集图表 / Dense Research Report (Meeker式)** `安静·还原92%` - 参考:Mary Meeker《Internet Trends》(BOND)、CB Insights《State of AI》、McKinsey Global Institute《Year in Charts》、FT/Bloomberg数据新闻 - 适配:趋势研报、行业数据复盘、密集数据汇报、市场地图 - 视觉DNA:配色=白底+品牌色(BOND/CB Insights亮蓝#0066FF)阶梯单色高亮其余灰化，几乎零留白。字体=结论式句子标题，每页1图密度，极小来源脚注。母版=①结论句标题+满页单图②logo网格market map③大数字KPI卡④密集多图网格+脚注。标志=结论句标题、零留白研报感、单色阶梯高亮、logo市场地图、来源脚注规范 - HTML实现:密集图表全用纯CSS/内联SVG画(柱/折线/堆叠/散点)；logo market map用Grid+文字/SVG占位格；KPI卡CSS；脚注小字。极致信息密度正是HTML擅长，零素材 - 字体:Inter + IBM Plex Sans + 数字tabular Geist Mono **纯文字宣言备忘录 / All-Text Manifesto (Netflix/Amazon式)** `安静·还原97%` - 参考:Netflix Culture Deck(2009，125页)、Amazon六页叙事备忘录(Bezos)、Tufte反PowerPoint主张、Matthew Carter阅读级排印 - 适配:文化宣言、价值观宣讲、深度备忘录、反PPT的纯文档演示 - 视觉DNA:配色=纯白或纯黑底+单一强调色(Netflix红#E50914)做唯一高亮，极致克制。字体=阅读级排印，一页一观点金句断言/纯散文零bullet零图。母版=①满版底+金句断言②口语化坦诚段落③制度名词高亮(Keeper Test)④六页散文+附录表。标志=纯文字一页一观点、零图零bullet、单色高亮金句、口语坦诚、silent-read文档感 - HTML实现:纯排版：金句用大字clamp()左对齐层级；散文max-width控制行宽；唯一强调色span高亮关键短语；附录用极简table。零素材零图，纯文字是HTML最稳的还原 - 字体:Newsreader / Source Serif(阅读级)或Inter(宣言式)；标题可Archivo超粗 --- ## 信息图风格库(20种) > **2026-08 新增**。此前本库只有网页与 PPT 两个半区，但「信息图/可视化」在 SKILL 里是四大适用场景之一——做信息图时轮盘只能落进网页半区，抽到的是社区站/落地页的风格，硬套上去。这个半区补的就是这个洞。 > 判据：**产出是一张(或一组)以数据为主角、可脱离交互独立阅读的图**，就走这里；是可点击的站点走网页分区，是要翻页的走 PPT 分区。 #### 大胆派 **个人数据印刷年报 / Personal Annual Report（Feltron式）** `大胆·还原94%` - 参考:Nicholas Felton《Feltron Annual Report》2005–2014（2006-2011 卷入 MoMA 永久馆藏）；Stefanie Posavec；Bloomberg Businessweek 年度特辑 - 适配:个人或团队年度总结、quantified-self、产品年度回顾、Wrapped 类复盘、长周期自我审计 - 视觉DNA:配色=未涂布纸暖白底+单一朱红做贯穿accent+石板蓝第二数据序列+第三色只绑一个语义绝不复用。字体=Helvetica系紧排，巨号数字压顶，小字注脚密集。母版四件套：①巨数字模块条 ②极坐标周期图(24h/12月) ③日历热力格 ④贯穿全幅的时间或地理带。标志=把私人琐碎数据当企业年报做的反差、模块化印刷网格、1px分割线、黑白打印仍可读 - HTML实现:CSS Grid分模块+1px border切网格；极坐标图内联SVG手算极角(不引图表库)；日历用Grid+子元素高度填充。纯排版+SVG，零素材，HTML极强项 - 字体:Archivo / Helvetica Neue(紧排巨数字) + Inter(小字注脚) **解释性图解 / Explanation Graphics（Nigel Holmes式）** `大胆·还原76%` - 参考:Nigel Holmes(1978–1994任TIME图表总监，1994创立Explanation Graphics)；主张用图画与幽默解释抽象数字，也是chartjunk之争的靶心 - 适配:科普解释、把复杂概念讲给外行、大众媒体专栏配图、儿童与教育向 - 视觉DNA:配色=高饱和平涂三四色+黑描边。字体=圆润无衬线+手写感标注。母版=把图表本体画成实物隐喻(钞票摞成柱、温度计当量表、跑道当进度条)。标志=拟物化图表、幽默、小人像、粗描边、零渐变 - HTML实现:图表骨架CSS/SVG可做，**灵魂在手绘插画**——纯HTML下只能降级为几何色块，须明确标注降级；有生图能力时用huashu-gpt-image生插画元素再合成 - 字体:Nunito / Baloo 2(圆润) + Caveat(手写标注) **巨幅剖面手绘 / Cross-Section Epic（SCMP Arranz式）** `大胆·还原55%` - 参考:Adolfo Arranz(SCMP资深图表编辑，Malofiej国际信息图奖多枚金奖，代表作《City of Anarchy》九龙城寨剖面)；Malofiej被称为信息图界的普利策 - 适配:建筑/历史/器物解剖、单张读十分钟的长卷、博物馆级科普 - 视觉DNA:配色=暗底(深墨/深褐)+暖色高光+做旧纸质感。构图=单张巨幅、等距或正剖视角、密集引线标注环绕主体。标志=手绘细节、引线标注、剖面视角、一张图讲完整个故事 - HTML实现:🔴 **纯HTML做不出手绘剖面**——本风格必须有插画素材，无素材时不要假装。HTML只承担引线标注层与缩放滚动交互。拿不到素材就换风格 - 字体:Source Serif(标题) + Inter(标注) **杂志撞色数据页 / Magazine Pop Data（Businessweek式）** `大胆·还原90%` - 参考:Bloomberg Businessweek(Richard Turley时期)、WIRED图表页、The Economist的Graphic Detail专栏 - 适配:商业/科技媒体图表、观点专栏配图、社媒方图、公众号内嵌数据图 - 视觉DNA:配色=撞色双主色(荧光黄+黑、品红+藏青)+纸白留白，不用第三色调和。字体=超粗压缩体大标题+极小说明字，字号对比10倍以上。母版=一图一个论点、图表本身就是版式主角、标题直接说结论。标志=极端字号对比、撞色、图表出血到版心外、结论式标题 - HTML实现:纯CSS可完全还原；图表用内联SVG或CSS Grid条；出血靠负margin。零素材 - 字体:Archivo Black / Anton(压缩粗体) + IBM Plex Sans(说明) **ISOTYPE图形统计 / Neurath–Arntz** `大胆·还原88%` - 参考:Otto Neurath与Gerd Arntz于1920s维也纳创立的ISOTYPE国际图形教育系统 - 适配:人口/社会/公共政策数据、面向低识字门槛的公共传播、教育海报 - 视觉DNA:配色=有限套色(黑+红+蓝+土黄)平涂，无渐变无阴影。母版=同一图标重复N次表示数量——**放大图标表示更多是错的**，这是该体系最核心的规矩。标志=剪影图标阵列、横向排列、左侧文字标签、极强秩序感 - HTML实现:图标用内联SVG剪影+CSS repeat布局，HTML天然适配。图标可自绘几何剪影，不需外部素材 - 字体:Jost / Archivo(Futura替代) **数据人文主义手绘图谱 / Data Humanism（Lupi式）** `大胆·还原80%` - 参考:Giorgia Lupi(Pentagram合伙人)与Stefanie Posavec《Dear Data》；Lupi的Data Humanism宣言主张「数据是人不是数字」 - 适配:个人化情感化数据、小样本深描、把私人经验做成可读图谱、非量化维度多的题材 - 视觉DNA:配色=手账米白底+4-5个各自绑定语义的柔和色(珊瑚/松绿/芥黄/墨紫)，**没有一个颜色是装饰**。母版=①先定一套视觉语言(大小/形状/刺/尾巴各编码一维)②必配一张图例教读者解码③元素沿有机路径排布不用网格。标志=可解码的自定义符号、必带图例、有机排布 - HTML实现:符号用内联SVG参数化生成(半径/刺数/尾长绑数据字段)；路径用贝塞尔曲线穿点。纯SVG零素材，唯一做不出的是真手绘笔触 - 字体:Georgia / Source Serif(标题) + Inter(图例) **滚动叙事数据长卷 / Scrollytelling（The Pudding式）** `大胆·还原85%` - 参考:The Pudding(数据新闻杂志)、NYT The Upshot、Reuters Graphics滚动专题 - 适配:需要一步步揭示的复杂论证、长篇数据故事、网页端专题 - 视觉DNA:配色随章节切换但保持单一accent贯穿。母版=左侧文字步进、右侧图形随scroll变形；每一屏只推进一个变量。标志=图形不换只变形、文字与图形严格绑定、章节色变、结尾给完整全景 - HTML实现:IntersectionObserver触发状态切换+CSS transition或SVG属性插值，纯前端可完整还原。⚠️ 交付形态必须是网页，**导PDF/PNG会丢掉全部叙事**——用户要静态图时不要选它 - 字体:Inter / Source Serif(长文可读性优先) **地图即主角 / Cartographic Lead（Stamen式）** `大胆·还原65%` - 参考:Stamen Design(2001年Eric Rodenbeck于旧金山创立，客户含National Geographic)，其Watercolor/Toner地图砖是公开经典 - 适配:地理分布数据、城市/交通/环境题材、位置即叙事的内容 - 视觉DNA:配色=地图底图定调(水彩或单色Toner)+数据层用高对比点线。母版=地图占满版心、数据以点密度或流线叠加、图例极小压角。标志=底图本身有作者性、数据层克制、地理形状即构图 - HTML实现:🔴 **需要真实地理数据(GeoJSON)与底图**，纯HTML无法凭空生成正确地形——拿不到数据就换风格，**绝不手绘假地图**。有数据时可用内联SVG投影绘制 - 字体:Inter / IBM Plex Sans(地名标注需大量小字) #### 中性派 **数据新闻图表规范 / Newsroom Chart System（FT式）** `中性·还原96%` - 参考:Financial Times的Chart Doctor团队与公开的Visual Vocabulary(按Deviation/Correlation/Ranking/Distribution/Change-over-Time/Part-to-Whole/Magnitude/Spatial分类选图表) - 适配:财经与行业数据、「选对图表类型」比「好看」更重要的场合、系列图表需统一规范时 - 视觉DNA:配色=标志性粉橘报纸底+一组有序色阶(单色渐变表连续量、对比双色表偏离)。母版=①标题即结论②副标题说明口径③图表本体去边框去网格④左下角必标数据来源。标志=先按数据关系选图型再谈美感、来源标注不可省、坐标轴极简 - HTML实现:纯CSS/SVG画折线柱状；关键是**先查Visual Vocabulary选对图型**再动手。零素材 - 字体:Inter / Source Sans(正文) + 等宽体标数字 **计算式数据肖像 / Computational Portrait（Fathom式）** `中性·还原78%` - 参考:Ben Fry与其波士顿工作室Fathom Information Design(Fry为Processing联合创造者、《Visualizing Data》作者，作品曾入Whitney双年展) - 适配:超大规模数据集、需要「让数据自己长出形状」的题材、基因/交通/时间序列 - 视觉DNA:配色=白或近黑底+极细线条+单色透明度叠加出密度。母版=不做摘要做全量呈现，用海量细元素的叠加密度形成图形。标志=发丝线、透明度堆叠、无装饰、形状由算法而非版式决定 - HTML实现:Canvas或大量SVG path程序化绘制，数据量大时必须Canvas。**要求真实全量数据**，小样本做不出这个风格的密度感 - 字体:Inter / Roboto Mono(数据标注) **美丽信息 / Beautiful Information（McCandless式）** `中性·还原90%` - 参考:David McCandless《Information is Beautiful》与其同名网站，以「把大数据集做成一眼可比的彩色图形」著称 - 适配:科普对比、榜单、大众向数据聚合、社媒传播型图表 - 视觉DNA:配色=多色但同明度同饱和的和谐色环(不是随机撞色)。母版=气泡图/树状图/桑基图等「面积即数量」的图型为主，标签直接压在色块上。标志=面积编码、同调多色、图例内嵌、一张图容纳几十个条目 - HTML实现:树状图与气泡用CSS Grid或SVG计算布局(需自己写简单装箱算法)；桑基图用SVG贝塞尔。零素材 - 字体:Nunito Sans / Inter **学术开放数据 / Open Research Data（Our World in Data式）** `中性·还原94%` - 参考:Our World in Data(牛津Global Change Data Lab)，准则是图表可交互、口径写清楚、数据可下载 - 适配:严谨议题、需要经得起质疑的数据展示、长期趋势对比 - 视觉DNA:配色=白底+一组区分度高但不刺眼的分类色+灰色做非重点系列。母版=①一句话结论标题②口径与时间范围写在副标题③图内直接在线末标标签(不用图例)④底部注来源与许可。标志=线末标签替代图例、灰化非重点、口径透明、克制 - HTML实现:纯SVG折线+末端text定位，HTML最稳的一类。零素材 - 字体:Inter / Lato **东方思辨科技图 / Speculative Tech Diagram（Takram式）** `中性·还原84%` - 参考:Takram(东京与伦敦的设计工程工作室，横跨设计与工程的speculative design实践) - 适配:技术概念图、未来场景推演、研究型白皮书配图、产品架构叙事 - 视觉DNA:配色=米灰砂色基底+低饱和自然色(苔绿/陶土)+一处金属灰。字体=细字重、大字距、中英混排考究。母版=图表被当作艺术品排布、大量留白、几何图形有精密感。标志=柔和科技感、精密几何、克制的自然色、图表如装置 - HTML实现:纯CSS/SVG可还原；关键在留白比例与线宽克制(0.5-1px)。零素材 - 字体:Inter(细字重) / Noto Sans JP + Cormorant(标题可选) **系统图标化图解 / Pictogram System（Otl Aicher式）** `中性·还原92%` - 参考:Otl Aicher为1972慕尼黑奥运设计的图标系统与Ulm学派栅格方法 - 适配:流程图、导视与指南类信息图、多语言场景、需要一整套图标保持一致时 - 视觉DNA:配色=一套受限色板(奥运版为浅蓝/绿/银)+黑。母版=所有图标共用同一网格与同一笔画角度(仅0/45/90°)、图标与短标签成对出现。标志=严格角度约束、系统一致性、无衬线短标签、栅格可见 - HTML实现:图标用内联SVG按45°约束自绘；栅格用CSS Grid。零素材，但要自己守住角度纪律 - 字体:Jost / Archivo(Univers替代) #### 安静派 **Tufte小倍数矩阵 / Small Multiples** `安静·还原95%` - 参考:Edward Tufte《Envisioning Information》的small multiples与sparkline概念 - 适配:多维度横向对比、时间序列分组、一个变量在几十个切片上的表现 - 视觉DNA:配色=白底+黑线+一个强调色标异常项。母版=同一张小图重复N次只换数据，**共用坐标轴范围——范围不统一就失去可比性，这是本流派唯一的致命错误**；标签极小压在图旁。标志=网格化重复小图、共享刻度、零图例、零网格线、高数据墨水比 - HTML实现:CSS Grid排小图+每格内联SVG折线。务必统一domain。零素材 - 字体:Source Serif(标题) + Inter(小标签) **拓扑简化路网图 / Topological Transit Map（Beck/Vignelli式）** `安静·还原86%` - 参考:Harry Beck 1933年伦敦地铁图、Massimo Vignelli 1972年纽约地铁图 - 适配:流程与关系网络、组织架构、系统拓扑、任何「连接关系比真实距离重要」的图 - 视觉DNA:配色=白或浅底+每条线一个高饱和纯色。母版=所有线段只走0/45/90°、站点等距——**牺牲地理准确性换可读性**是本流派的立身之本；换乘点用空心圆。标志=八方向约束、等距节点、纯色线、空心节点 - HTML实现:内联SVG polyline严格约束角度；节点用circle。纯几何，HTML完美适配 - 字体:Jost / Inter(站名可全大写) **白之留白信息图 / Ma & Emptiness（原研哉式）** `安静·还原82%` - 参考:原研哉《白》与无印良品视觉体系，「留白不是空，是容纳想象的容器」 - 适配:品牌年报、慢节奏叙事、少量但重要的数据、需要庄重感的场合 - 视觉DNA:配色=纯白或宣纸白+极浅灰+一处极小的墨色或朱色点。母版=一屏一个数据、巨幅留白、元素靠边缘或黄金位置放置、绝不填满。标志=极端留白、单点强调、细若无物的线、东方式的「间」 - HTML实现:纯CSS排版。🔴 **本库风险最高的一种**——留白必须是构图(有明确视觉锚点)，做过头就是「页面渲染坏了」；正文仍须≥14px，不许为了气质缩字号 - 字体:Noto Serif SC / Source Han Serif + Inter **书籍级信息排印 / Bookcraft Data（Irma Boom式）** `安静·还原80%` - 参考:Irma Boom(荷兰书籍设计师，作品入MoMA永久馆藏，以极端排印与材质实验著称) - 适配:长篇数据报告、需要被当作出版物收藏的年报、图文混排的深度内容 - 视觉DNA:配色=纸色+一到两种油墨色，色块大面积压版。字体=排印本身即主角，字号跨度极大、页边距非对称、文字可竖排或旋转。母版=把数据嵌进文本流、章节页用满版色块分隔。标志=非对称版心、极端字号跨度、排印实验、出版物质感 - HTML实现:CSS多栏+writing-mode可做竖排；非对称版心用Grid。**做不到的是纸张材质与裁切**，屏幕上须靠排印张力补偿 - 字体:Fraunces / EB Garamond + Archivo(对比) **科学期刊图版 / Scientific Figure Plate** `安静·还原96%` - 参考:Nature与Science的figure规范、USGS与NASA的公开科学图版 - 适配:研究结论、方法对比、需要同行审阅质感的严谨数据、多子图组合 - 视觉DNA:配色=白底+色盲友好色板(用蓝橙对比而非红绿)+灰阶。母版=子图用(a)(b)(c)标号、图注在图下方成段、误差棒与样本量必标、坐标轴带刻度线。标志=子图编号、图下长图注、误差棒、色盲安全、零装饰 - HTML实现:CSS Grid排子图+SVG画图与误差棒；图注用小字段落。零素材，HTML完全胜任 - 字体:Inter / Source Sans + Roboto Mono(数字) **瑞士网格年报 / Swiss Grid Report（Müller-Brockmann式）** `安静·还原97%` - 参考:Josef Müller-Brockmann《Grid Systems in Graphic Design》、Ulm学派、瑞士国际主义年报传统 - 适配:企业年报、机构报告、需要长期沿用一套版式的系列文档 - 视觉DNA:配色=白底+黑+单一强调色。母版=严格模块网格(常12栏)、所有元素吸附栏线、左对齐齐头不齐尾、大量呼吸性留白但不空。标志=可见的网格逻辑、Helvetica系、非居中排版、层级靠字号与间距而非装饰 - HTML实现:CSS Grid直接映射栏网格，是本库与HTML最同构的一种。零素材 - 字体:Inter / Archivo(Helvetica替代) --- ## ⚠️ AI 生图专用风格（仅在确认用户有生图能力� -
editable-pptx.md 18.1 KB
# 可编辑 PPTX 导出：HTML 硬约束 + 尺寸决策 + 常见错误 本文档讲的是**用 `scripts/html2pptx.js` + `pptxgenjs` 把 HTML 逐元素翻译成真·可编辑 PowerPoint 文本框**的路径，也是 `export_deck_pptx.mjs` 唯一支持的路径。 > ## 🔴 先选路：这份文档只讲两条路里的一条 > > | 情况 | 走哪条 | > |---|---| > | **HTML 还没写**，从头做 deck | **本文**（按 4 条硬约束写 → `html2pptx.js`）。结构最干净，最适合后续编辑 | > | **HTML 已经写好**，是视觉驱动的（flex / 居中 / 裸文字 / 背景图 / SVG 图表） | → `references/pptx-from-rendered-html.md`（读渲染后坐标，**零改造**） | > | **甲方要求「必须用我们的模板」** | → 同上，**只能走那条**。pptxgenjs 无法以现有 pptx 为基底继承母版 | > > 两条路不要在同一个项目里混用。下面的 4 条约束只对本文这条路成立—— > 已经写好的视觉稿**不需要**为了转 PPTX 去重写成合规结构。 > > **核心前提**：要走这条路，HTML 必须从第一行就按下面 4 条约束写。**不是写完再转**——事后补救会触发 2-3 小时返工（2026-04-20 期权私董会项目实测踩坑）。 --- ## 画布尺寸：用 960×540pt（LAYOUT_WIDE） PPTX 单位是 **inch**（物理尺寸），不是 px。决策原则：body 的 computedStyle 尺寸要**匹配 presentation layout 的 inch 尺寸**（±0.1"，由 `html2pptx.js` 的 `validateDimensions` 强制检查）。 ### 3 个候选尺寸对比 | HTML body | 物理尺寸 | 对应 PPT layout | 何时选 | |---|---|---|---| | **`960pt × 540pt`** | **13.333″ × 7.5″** | **pptxgenjs `LAYOUT_WIDE`** | ✅ **默认推荐**（现代 PowerPoint 16:9 标配） | | `720pt × 405pt` | 10″ × 5.625″ | 自定义 | 仅当用户指定「老版 PowerPoint Widescreen」模板时 | | `1920px × 1080px` | 20″ × 11.25″ | 自定义 | ❌ 走本文这条路时是非标尺寸，投影后字体显得异常小。⚠️ 但**继承甲方模板时画布必须跟模板走**（实测遇到过 26.67″×15″），那条路见 `pptx-from-rendered-html.md` | **别把 HTML 尺寸当分辨率想。** PPTX 是矢量文档，body 尺寸决定的是**物理尺寸**不是清晰度。超大 body（20″×11.25″）不会让文字更清晰——只会让字号 pt 相对画布变小，投影/打印时反而更难看。 ### body 写法三选一（等价） ```css body { width: 960pt; height: 540pt; } /* 最清晰，推荐 */ body { width: 1280px; height: 720px; } /* 等价，px 习惯 */ body { width: 13.333in; height: 7.5in; } /* 等价，英寸直觉 */ ``` 配套的 pptxgenjs 代码： ```js const pptx = new pptxgen(); pptx.layout = 'LAYOUT_WIDE'; // 13.333 × 7.5 inch, 无需自定义 ``` --- ## 4 条硬约束（违反会直接报错） `html2pptx.js` 对 DOM 做一次遍历，按标签和 computed style 把每个元素分类成「文本框 / 形状 / 图片 / 忽略」。分类规则背后是 PowerPoint 文件格式本身的限制，投射到 HTML 上就是下面 4 条——写的时候脑子里过一遍，能省掉转出来再逐页返工的时间。 ### 规则 1：DIV 里不能直接躺文字 — 用 `<p>` 或 `<h1>`-`<h6>` 包一层 ```html <!-- ❌ 错误：文字是 div 的直接子文本节点 --> <div class="metric">日活 12.4 万，环比 +8%</div> <!-- ✅ 正确：文字包进 <p>/<h1>-<h6>，div 只负责定位/背景 --> <div class="metric"><p>日活 12.4 万，环比 +8%</p></div> ``` **判定方式**：脚本检查的是 div 的**直接子节点**里有没有非空白的文本节点——嵌套在 `<p>`/`<h1>`-`<h6>` 里的文字不算，只有「字直接贴在 div 上」才算违规。报错里会带上违规文字的前 50 个字（超出用 `...`收尾），方便定位是哪一段。 **span 同理不能单独顶用**：span 是行内元素，脚本只会把它当成 `<p>`/`<h1>`-`<h6>` 内部的一段局部样式覆盖（加粗、换色、下划线），不会把它单独提成一个文本框。想要一段独立可编辑的文字，外面必须有 `<p>`/`<h1>`-`<h6>`。 ### 规则 2：不支持 CSS 渐变（本质是「不支持 background-image」的一种） ```css /* ❌ 错误：linear-gradient/radial-gradient 都算 background-image */ .banner { background: linear-gradient(135deg, #FF6B6B, #4ECDC4); } /* ✅ 正确：纯色 */ .banner { background: #FF6B6B; } /* ✅ 需要多色过渡观感，用几个纯色 flex 子块错位排列，靠透明度或色阶模拟渐变感 */ .banner { display: flex; } .banner div { flex: 1; } .banner .c1 { background: #FF6B6B; } .banner .c2 { background: #FF9B6B; } .banner .c3 { background: #4ECDC4; } ``` **为什么**：脚本对 div 的校验只看 computed `background-image` 是不是 `none`——只要不是 `none`，不管里面是一张图还是一个 CSS 渐变函数，都会被拦下来（渐变本质上就是一种特殊的 background-image）。PowerPoint 的原生 shape fill 只有纯色这一种是 pptxgenjs 稳定支持的，渐变需要单独一套 OOXML 结构，工具链目前没做。 ### 规则 3：背景/边框/阴影只能挂在 DIV 上，文字标签（含 `<ul>`/`<ol>`）一概不行 ```html <!-- ❌ 错误：<h2> 自己带了背景和圆角 --> <h2 style="background: #FFD700; border-radius: 6pt; padding: 6pt 10pt;">核心结论</h2> <!-- ✅ 正确：外层 div 扛背景/边框，<h2> 只管文字 --> <div style="background: #FFD700; border-radius: 6pt; padding: 6pt 10pt;"> <h2>核心结论</h2> </div> ``` **为什么**：脚本对每一个 `<p>`/`<h1>`-`<h6>`/`<ul>`/`<ol>`（以及它们内部收编的 `<li>`）都会先单独检查一遍自身的 background/border/box-shadow——三者任意一个非空就直接报错，连是不是同时命中"占位符"（`class` 里带 `placeholder`）这类其它规则都不管，直接判定为违规。这条检查发生在所有其它分类之前，因为 PowerPoint 里"能画背景/边框/阴影的 shape"和"能装文字的 text frame"是两种不同对象，`<p>`/`<h*>` 只会被翻成后者，没有地方安放前者的属性。 ### 规则 4：DIV 不能用 `background-image` — 图片一律用 `<img>` 标签 ```html <!-- ❌ 错误 --> <div style="background-image: url('trend.png'); width: 300pt; height: 200pt;"></div> <!-- ✅ 正确 --> <img src="trend.png" style="position: absolute; left: 60pt; top: 80pt; width: 300pt; height: 200pt;" /> ``` **为什么**：脚本只从 `<img>` 元素读取（浏览器解析后的）绝对 `src` 来生成图片对象；它完全不解析 div 的 `background-image` 属性里那个 `url(...)`。命中这条时脚本不会连累这个 div 的子孙——`div` 自己不产出任何东西，但内部如果还包了 `<p>`/`<img>` 等，仍会各自继续被单独处理，只是这层背景图没了。想要图片和文字叠在一起，就把 `<img>` 和文字层分别摆成两个独立元素，靠定位对齐。 --- ## 合并文本框（`data-pptx-merge`） **默认行为**：HTML 里每个 `<p>`/`<h1>`-`<h6>` 在 PPTX 里都是**独立文本框**。卡片里写 3 个 `<p>` → PPT 里 3 个文本框摞着，编辑时不能整段回车换行加段，得逐个改字号/对齐。 **解决方法**：给外层 div 加 `data-pptx-merge="true"`，容器内的所有 `<p>/<h*>` 会合并为**一个可编辑文本框**，每段之间用段落分隔符隔开，PPT 里就是一段一段连续编辑。 ```html <!-- ✅ 合并写法：4 段全部在一个文本框里 --> <div class="card" data-pptx-merge="true" style="position: absolute; top: 60pt; left: 60pt; width: 420pt; background: #1A4A8A; border-radius: 8pt; padding: 20pt 24pt;"> <h2 style="font-size: 24pt; color: #FFFFFF;">标题</h2> <p style="font-size: 14pt; color: #DDEEFF;">第一段正文。</p> <p style="font-size: 14pt; color: #FFD166;">第二段：换颜色作为强调。</p> <p style="font-size: 14pt; color: #DDEEFF;">第三段：同一个文本框里继续写。</p> </div> ``` **保留的样式**（per-paragraph 作为 run options 写入）：`font-size`、`color`、`font-family`、`font-weight`（bold）、`font-style`（italic）、`text-decoration: underline`、`<b>/<i>/<u>/<strong>/<em>/<span>` 内联样式。 **取自第一段、整框统一**：`text-align`、`line-height`。因为 PowerPoint 的对齐和行距是 paragraph/textbox 级别——一框里只能有一种对齐。如果几段对齐不同，请别用 merge，让它们各自独立。 **容器自身的 `background`/`border`/`box-shadow`/`border-radius`** 照常作为 shape 渲染，行为和普通 div 完全一样——也就是说蓝色卡片底 + 文本仍然是「shape + text frame」两层，只是文本层从 3-4 个文本框塌缩成 1 个。 **限制**： - 不能嵌套 `data-pptx-merge`（会报错）。 - 容器不能用 `background-image`（同 4 条硬约束规则 4）。 - 容器内不要再放有 `background`/`border` 的子 div——它们仍会被当作独立 shape 渲染，但里面的文字已被合并走了，可能产生视觉错位。 **什么时候用**：内容会反复改、要在 PPT 里继续编辑的场景。一次性导出归档的不用加，行为一致。 --- ## Path A HTML 模板骨架 每张 slide 一个独立 HTML 文件，彼此作用域隔离（避开单文件 deck 的 CSS 污染）。 ```html <!DOCTYPE html> <html lang="zh-CN"> <head> <meta charset="UTF-8"> <style> * { margin: 0; padding: 0; box-sizing: border-box; } body { width: 960pt; height: 540pt; /* ⚠️ 匹配 LAYOUT_WIDE */ font-family: system-ui, -apple-system, "PingFang SC", sans-serif; background: #FEFEF9; /* 纯色，不能渐变 */ overflow: hidden; } /* DIV 负责布局/背景/边框 */ .card { position: absolute; background: #1A4A8A; /* 背景在 DIV 上 */ border-radius: 4pt; padding: 12pt 16pt; } /* 文字标签只负责字体样式，不加背景/边框 */ .card h2 { font-size: 24pt; color: #FFFFFF; font-weight: 700; } .card p { font-size: 14pt; color: rgba(255,255,255,0.85); } </style> </head> <body> <!-- 标题区：外层 div 定位，内层文字标签 --> <div style="position: absolute; top: 40pt; left: 60pt; right: 60pt;"> <h1 style="font-size: 36pt; color: #1A1A1A; font-weight: 700;">标题用断言句，不是主题词</h1> <p style="font-size: 16pt; color: #555555; margin-top: 10pt;">副标题补充说明</p> </div> <!-- 内容卡片：div 负责背景，h2/p 负责文字 --> <div class="card" style="top: 130pt; left: 60pt; width: 240pt; height: 160pt;"> <h2>要点一</h2> <p>简短说明文字</p> </div> <!-- 列表：使用 ul/li，不用手动 • 符号 --> <div style="position: absolute; top: 320pt; left: 60pt; width: 540pt;"> <ul style="font-size: 16pt; color: #1A1A1A; padding-left: 24pt; list-style: disc;"> <li>第一条要点</li> <li>第二条要点</li> <li>第三条要点</li> </ul> </div> <!-- 插图：用 <img> 标签，不用 background-image --> <img src="illustration.png" style="position: absolute; right: 60pt; top: 110pt; width: 320pt; height: 240pt;" /> </body> </html> ``` --- ## 常见错误速查 | 错误信息 | 原因 | 修复方法 | |---------|------|---------| | `<div> 里直接写了文字「XXX」` | div 里有裸文字 | 把文字包进 `<p>` 或 `<h1>`-`<h6>` | | `<div> 背景不能用 CSS 渐变` | 用了 linear/radial-gradient | 改为纯色，或用 flex 子元素分段 | | `文字标签 <p> 上设置了 background…` | `<p>` 标签加了背景色 | 外套 `<div>` 承载背景，`<p>` 只写文字 | | `<div> 不能用 background-image` | div 用了 background-image | 改为 `<img>` 标签 | | `内容纵向超出页面 Xpt` | 内容超出 540pt | 减少内容或缩小字号，或 `overflow: hidden` 截断 | | `页面尺寸不一致` | body 尺寸和 pres layout 对不上 | body 用 `960pt × 540pt` 配 `LAYOUT_WIDE`；或 defineLayout 自定义尺寸 | | `文本框「XXX」离页面底边只有…` | 大字号 `<p>` 距离 body 底边 < 0.5 inch | 往上挪，留足下边距；PPT 底部本身就会被遮住一部分 | --- ## 基本工作流（3 步出 PPTX） ### Step 1：按约束写每页独立 HTML ``` 我的Deck/ ├── slides/ │ ├── 01-cover.html # 每个文件都是完整 960×540pt HTML │ ├── 02-agenda.html │ └── ... └── illustration/ # 所有 <img> 引用的图片 ├── chart1.png └── ... ``` ### Step 2：写 build.js 调用 `html2pptx.js` ```js const pptxgen = require('pptxgenjs'); const html2pptx = require('../scripts/html2pptx.js'); // 本 skill 脚本 (async () => { const pres = new pptxgen(); pres.layout = 'LAYOUT_WIDE'; // 13.333 × 7.5 inch，匹配 HTML 的 960×540pt const slides = ['01-cover.html', '02-agenda.html', '03-content.html']; for (const file of slides) { await html2pptx(`./slides/${file}`, pres); } await pres.writeFile({ fileName: 'deck.pptx' }); })(); ``` ### Step 3：打开检查 - PowerPoint/Keynote 打开导出 PPTX - 双击任意文字应能直接编辑（如果是图片说明第 1 条违反了） - 验证 overflow：每页应该在 body 范围内，没有被截 --- ## 这条路径 vs 其他选项（什么时候选什么） | 需求 | 选什么 | |------|------| | 同事会改 PPTX 里的文字 / 发给非技术人员继续编辑 | **本文路径**（editable，需从头按 4 条约束写 HTML） | | 只是演讲用 / 发存档，不再改 | `export_deck_pdf.mjs`（多文件）或 `export_deck_stage_pdf.mjs`（单文件 deck-stage），出矢量 PDF | | 视觉自由度优先（动画、web component、CSS 渐变、复杂 SVG），接受不可编辑 | **PDF**（同上）——PDF 既保真又跨平台，比「图片 PPTX」更合适 | **绝不要在视觉自由写好的 HTML 上硬跑 html2pptx**——实测视觉驱动的 HTML pass 率 < 30%，剩下的逐页改造比重写还慢。这种场景应该出 PDF，不是硬挤 PPTX。 --- ## Fallback：已有视觉稿但用户坚持要 editable PPTX 偶尔会遇到这个场景：你/用户已经写好一份视觉驱动的 HTML（渐变、web component、复杂 SVG 都用上了），本来出 PDF 最合适，但用户明确说「不行，必须是可编辑的 PPTX」。 **不要硬跑 `html2pptx` 期待它 pass**——实测视觉驱动 HTML 在 html2pptx 上 pass 率 <30%，剩下 70% 会报错或走样。 > 🔴 **2026-09 起，先试第三条路再考虑下面的 A/B**：`scripts/pptx_from_rendered.py` 读的是浏览器 > **渲染完之后**的坐标，不是源码，所以视觉驱动的 HTML 可以零改造直接转（实测 20 页全过）， > 也不必让用户在「丢视觉」和「丢可编辑」之间二选一。见 `references/pptx-from-rendered-html.md`。 > 下面的 A/B 只在那条路也不适用时才提。 正确的 fallback 是： ### Step 1 · 先告知局限性（透明沟通） 一句话跟用户说清三件事： > 「你现在的 HTML 用了 [具体列出：渐变 / web component / 复杂 SVG / ...]，直接转 editable PPTX 会 fail。我有两个方案： > - A. **出 PDF**（推荐）——视觉 100% 保留，接收方能看能印但不能改文字 > - B. **以视觉稿为蓝本，重写一版 editable HTML**（保留色彩/布局/文案的设计决策，但按 4 条硬约束重新组织 HTML 结构，**牺牲**渐变、web component、复杂 SVG 等视觉能力）→ 再导出 editable PPTX > > 你选哪个？」 不要把 B 方案说得云淡风轻——明确告知**会丢失什么**。让用户做取舍。 ### Step 2 · 如果用户选 B：AI 主动改写，不要求用户自己写 这里的 doctrine 是：**用户给的是设计意图，你负责翻译成合规实现**。不是让用户去学 4 条硬约束然后自己重写。 改写时的遵循原则： - **保留**：色彩系统（主色/辅色/中性色）、信息层级（标题/副标题/正文/注解）、核心文案、layout 骨架（上中下 / 左右分栏 / 网格）、页面节奏 - **降级**：CSS 渐变 → 纯色或 flex 分段、web component → 段落级 HTML、复杂 SVG → 简化的 `<img>` 或纯色几何、阴影 → 删除或降为极弱、自定义字体 → 向系统字体靠齐 - **重写**：裸文字 → 包进 `<p>` / `<h*>`、`background-image` → `<img>` 标签、`<p>` 上的背景边框 → 外层 div 承载 ### Step 3 · 产出对照清单（透明交付） 改写完成后给用户一份 before/after 对照，让他知道哪些视觉细节被简化了： ``` 原设计 → editable 版调整 - 标题区紫色渐变 → 主色 #5B3DE8 纯色背景 - 数据卡片阴影 → 删除（改为 2pt 描边区分） - 复杂 SVG 折线图 → 简化为 <img> PNG（从 HTML 截图生成） - Hero 区 web component 动效 → 静态首帧（web component 无法翻译） ``` ### Step 4 · 导出 & 双格式交付 - `editable` 版 HTML → 跑 `scripts/export_deck_pptx.mjs` 出可编辑 PPTX - **建议同时保留**原视觉稿 → 跑 `scripts/export_deck_pdf.mjs` 出高保真 PDF - 双格式交付给用户：视觉稿的 PDF + 可编辑的 PPTX，各司其职 ### 什么情况下直接拒绝 B 方案 个别场景下改写代价过高，应该劝用户放弃 editable PPTX： - HTML 核心价值是动画或交互（改写后只剩静态首帧，信息量损失 50%+） - 页数 > 30，改写成本超过 2 小时 - 视觉设计深度依赖精确 SVG / 自定义 filter（改写后和原图几乎无关） 此时告诉用户：「这个 deck 改写代价过高，建议出 PDF 而不是 PPTX。如果接收方确实要 pptx 格式，就接受视觉会大幅朴素化——要不要换成 PDF？」 --- ## 为什么 4 条约束不是 Bug 而是物理约束 这 4 条不是 `html2pptx.js` 作者偷懒——它们是 **PowerPoint 文件格式（OOXML）本身的约束**投射到 HTML 上的结果： - PPTX 里文字必须在 text frame（`<a:txBody>`），对应段落级 HTML 元素 - PPTX 的 shape 和 text frame 是两个对象，无法在同一 element 上同时画背景和写文字 - PPTX 的 shape fill 对 gradient 支持有限（仅某些 preset gradients，不支持 CSS 任意角度渐变） - PPTX 的 picture 对象必须引用真实图片文件，不是 CSS 属性 理解这点后，**不要期待工具变聪明** —— 是 HTML 写法要适配 PPTX 格式，不是反过来。 -
gsap-recipes.md 34.8 KB
# GSAP Recipes · 设计语言到 GSAP Timeline 的翻译层 > 本文件只做一件事：把 huashu-design 已沉淀的动画设计语言 > （`animation-best-practices.md` 的五段叙事、easing 体系、运动语言 8 条、场景配方， > 以及 `cinematic-patterns.md` 的 22 秒 5-scene 模板）翻译成可直接粘贴的 > GSAP timeline 实现配方，跑在 HyperFrames 渲染后端上。 > > **设计判断以本 skill 自己的 references 为准，GSAP 只是实现工具。** > 什么时候该悬停、该用哪种叙事弧线、什么算美，去读 `animation-best-practices.md` §0； > 本文件回答的只是「这条规则用 GSAP 怎么写」。 > HyperFrames 的合成契约（composition root 属性、`.clip` 标记、渲染命令、check 审计） > 见 `references/hyperframes-backend.md`，本文只引用不复述。 --- ## 0 · 基础样板（每个合成都从这里开始） ```html <script src="https://cdn.jsdelivr.net/npm/gsap@3.14.2/dist/gsap.min.js"></script> <script> window.__timelines = window.__timelines || {}; const tl = gsap.timeline({ paused: true, // 必须。HyperFrames 负责 seek defaults: { ease: "expo.out", duration: 0.6 }, // 本 skill 的主 easing（见 §1） }); // ... 所有 tween 都挂在这条 timeline 上 ... window.__timelines["main"] = tl; // key 必须等于合成根的 data-composition-id </script> ``` 硬约束（违反任何一条，渲染结果不确定）： - timeline 必须 `paused: true`，**永远不调用 `tl.play()`** 做渲染关键动画 - timeline 必须在同步代码里建好，不放进 async / 定时器 / 事件回调 - 渲染时长来自合成根的 `data-duration`，不是 timeline 长度。不要用空 tween 垫长度 - 禁 `repeat: -1`。循环动作用可见时长算出有限的 repeat 次数 - 注意：`defaults: { ease: "expo.out" }` 与 hyperframes-animation 文档里的 `power3.out` house default 不同。那是它的品味，本 skill 的既有规则是 「expoOut 是默认主 easing」，翻译层遵循自家设计语言 --- ## 1 · Easing 映射表 · 自研 Easing → GSAP `assets/animations.jsx` 里的自研 Easing 函数，逐个对应到 GSAP 写法。 前三个是数学上**完全同一条曲线**，不是近似。 | 自研 Easing | 数学定义 | GSAP 写法 | 关系 | 用途（既有规则） | |---|---|---|---|---| | `expoOut` | `1 - 2^(-10t)` | `"expo.out"` | 完全一致 | **默认主 easing**。卡片 rise-in、面板入场、Terminal fade、focus overlay | | `overshoot` | easeOutBack，c1=1.70158 | `"back.out"`（默认 1.70158）或 `"back.out(1.7)"` | 完全一致 | Toggle 切换、按钮弹出、强调交互 | | `spring` | easeOutElastic，周期 2π/3 | `"elastic.out(1, 0.3)"`（即默认 `"elastic.out"`） | 完全一致 | 几何体归位、物理落位、UI 抖弹 | | `easeIn` | `t²` | `"power1.in"` | 完全一致 | 出场、Anticipation 预备段 | | `easeOut` | `1-(1-t)²` | `"power1.out"` | 完全一致 | 次要元素的轻动作（说明文字 fade 等） | | `easeInOut` | quad inOut | `"power1.inOut"` | 完全一致 | 持续运动（鼠标轨迹插值等对称运动） | | `linear` | `t` | `"none"` | 完全一致 | 只用于 proxy 驱动 / 相机匀速运动。**禁止用在元素动效上** | | `anticipation` | 分段曲线，先下探 -0.3 再回升 | 无内置等价，用函数 ease（见下） | | 带预备动作的入场 | ### 1.1 anticipation · 函数 ease GSAP 接受任意 `(p) => number` 作为 ease，把自研定义原样搬过来即可： ```js // 与 animations.jsx 的 Easing.anticipation 逐点一致 const anticipation = (t) => { if (t < 0.2) return -0.3 * (t / 0.2) * (t / 0.2); // 前 20%：反向下探 const a = (t - 0.2) / 0.8; return -0.012 + 1.012 * a * a * (3 - 2 * a); // 后 80%：smoothstep 回升 }; tl.fromTo("#card", { y: 40 }, { y: 0, duration: 0.7, ease: anticipation }, "s2"); ``` 注意：这条曲线会越过 0（负值区），**只能用在 transform 上**（y / scale / rotation）， 不要用在 opacity 或颜色上（会推出合法范围）。 ### 1.2 spring 的另一个选项 · 烤制弹簧（seek-safe 真物理） `"elastic.out(1, 0.3)"` 是自研 spring 的精确等价，直接用它没问题。 当你想要**可调阻尼**的真弹簧手感（比如「落位几乎不过冲、只是尾巴长」）， 用 hyperframes-animation 提供的 `springEase` 闭式解（`adapters/gsap-easing-and-stagger.md` 有完整 40 行实现，闭式解是时间的纯函数，seek-safe）： ```js // dampingFraction 1.0 = 无过冲的沉稳落位；0.6-0.7 ≈ 自研 spring 的弹跳感 const settle = springEase({ response: 0.4, dampingFraction: 0.65 }); tl.fromTo("#hero", { scale: 0 }, { scale: 1, duration: settle.duration, ease: settle.ease }, "s4"); // duration 必须一起用，它是物理的一部分 ``` **禁止**引入任何实时弹簧库（react-spring 等积分器）：状态逐帧累积，无法确定性 seek。 --- ## 2 · 五段叙事骨架 · Slow-Fast-Boom-Stop（15/15/40/20/10%） 为什么：均匀节奏的动画是技术演示，有节奏的动画才是叙事（best-practices §1）。 带 label 的 timeline 骨架模板，改 `D` 即可适配任意总时长： ```js const D = 15; // 总时长（秒），与合成根 data-duration 保持一致 const at = (p) => D * p; const tl = gsap.timeline({ paused: true, defaults: { ease: "expo.out", duration: 0.6 }, }); // ── 五段 label，比例 15 / 15 / 40 / 20 / 10 ────────────────── tl.addLabel("s1_trigger", at(0)); // 慢 · 触发：给人类反应时间，建立真实感 tl.addLabel("s2_generate", at(0.15)); // 中 · 生成：视觉惊艳点出现 tl.addLabel("s3_process", at(0.30)); // 快 · 过程：展示可控性/密度/细节 tl.addLabel("s4_boom", at(0.70)); // Boom · 爆发：拉远/3D pop-out/多面板涌现 tl.addLabel("s5_hold", at(0.90)); // 静 · 落幅：Logo 形变 + 戛然而止 // ── S1 触发（节奏慢：单个动作 + 大量留白）───────────────────── tl.fromTo("#terminal", { y: 48, autoAlpha: 0 }, { y: 0, autoAlpha: 1, duration: 0.8 }, "s1_trigger+=0.1"); // ── S2 生成（一个明确的惊艳点，不堆动作）───────────────────── tl.fromTo("#result-panel", { scale: 0.92, autoAlpha: 0 }, { scale: 1, autoAlpha: 1, duration: 0.7 }, "s2_generate"); // ── S3 过程（密度最高：stagger、typewriter、focus 切换都在这）── tl.fromTo(".row", { y: 10, autoAlpha: 0 }, { y: 0, autoAlpha: 1, duration: 0.4, stagger: 0.03 }, "s3_process"); // ── S4 爆发（镜头级动作：拉远 / rotationX / 多元素涌现）─────── tl.to("#stage", { scale: 0.82, rotationX: 8, duration: 1.2, ease: "expo.inOut" }, "s4_boom"); // ── S5 落幅（Logo 形变收束，见 §3.6；之后什么都不发生）──────── // 最后 ~0.5s 是有意的静止 hold：不加任何 tween，也绝不 fade to black window.__timelines["main"] = tl; ``` 要点： - **S5 之后留白**：`data-duration` 覆盖到最后，但 timeline 上没有 tween， 画面 hold 在最终帧。这就是「戛然而止」的实现（禁 fade out 收尾） - 22 秒 5-scene 模板（cinematic-patterns Pattern B）同构：把比例换成 Invoke 3-4s / Process 5-6s / Insight 4-5s / Output 3-4s / Hero 4-5s，label 同法 - scene 之间的全屏切换用 autoAlpha 交叠 + 位移，不用 display 切换 （`display` / 裸 `visibility` 是渲染器禁区，show/hide 一律 `autoAlpha`） --- ## 3 · 运动语言 8 条 · 逐条翻译 ### 3.1 底色不用纯黑纯白 非 timeline 规则：底色是静态 CSS，带色温的中性色，具体色值走品牌 spec。 唯一的 GSAP 关联：scene 之间要变底色时，tween `backgroundColor`（在允许列表内）， 且两个 scene 的底色应同色系（cinematic-patterns §2 的配色一致约束）： ```js tl.to("#stage", { backgroundColor: "#F4EFE6", duration: 0.8, ease: "sine.inOut" }, "s4_boom"); ``` ### 3.2 Easing 绝不是 linear 为什么：`linear` 让数字元素像机器，`expoOut` 给物理重量感（best-practices §2）。 实现：timeline `defaults` 写 `ease: "expo.out"`（见 §0 样板）， 个别 tween 按 §1 映射表覆盖。`ease: "none"` 只允许出现在两处： proxy 驱动 tween（§7）和刻意的机械运动（相机匀速 pan）。 ### 3.3 Slow-Fast-Boom-Stop 见 §2 骨架，不重复。 ### 3.4 展示「过程」而非「魔法结果」 为什么：产品是协作者不是魔术师，展示 tweak / 报错修复 / redline 打击「一键魔法」 的 AI slop（best-practices §3.4）。 两个最常用的「过程感」配方： **Chunk Reveal（模拟 token 流式输出）**。原配方用 `setTimeout + Math.random`， 两者在 seek 渲染下都非法。翻译成「预计算时刻表 + proxy 驱动」，双向 seek 安全： ```js // 为什么不用 tl.call()：回调不可逆，preview 里往回拖会残留状态 const rand = mulberry32(42); // 种子随机，见 §7.4 const text = "为你生成了三个候选方案，第一个最激进。"; const chunks = text.split(/(?=[，。、；])|(?<=[，。、；])/); // 中文按标点切 chunk const times = []; let acc = 0; chunks.forEach(() => { acc += 0.04 + rand() * 0.08; times.push(acc); }); // 不规律 40-120ms const tw = { t: 0 }; tl.to(tw, { t: acc, duration: acc, ease: "none", onUpdate: () => { // 每帧从 t 重算完整可见文本：纯函数，回拖也正确 let n = 0; while (n < times.length && times[n] <= tw.t) n++; document.querySelector("#stream").textContent = chunks.slice(0, n).join(""); }, }, "s2_generate+=0.3"); ``` **数字 counter（展示真实数据在涨）**： ```js // snap 保证整数；innerText 是 HyperFrames 认可的 counter 写法 tl.fromTo("#metric", { innerText: 0 }, { innerText: 237, snap: { innerText: 1 }, duration: 1.2, ease: "expo.out" }, "s3_process"); ``` 带千分位 / 后缀格式化时改用 proxy + onUpdate（`tw.v` 推导 `toLocaleString`），套路同上。 ### 3.5 鼠标轨迹 · 弧线 + 手抖 为什么：直线插值的鼠标有潜意识机器感，真人是「加速、弧线、减速修正」 （best-practices §3.5）。 贝塞尔弧线没法用普通属性 tween 表达，用 proxy 驱动。手抖不用 Perlin （原实现依赖运行时噪声），用两条不可通约频率的正弦叠加，确定性等效： ```js const mouse = { p: 0 }; const P0 = [100, 100]; // 起点 const P2 = [tx, ty]; // 终点（点击目标） const P1 = [tx - 200, ty + 80]; // 控制点：偏离中点，制造弧线 tl.to(mouse, { p: 1, duration: 1.1, ease: "power1.inOut", // 对称 easing：起步加速 + 到达减速 onUpdate: () => { const t = mouse.p; let x = (1-t)*(1-t)*P0[0] + 2*(1-t)*t*P1[0] + t*t*P2[0]; let y = (1-t)*(1-t)*P0[1] + 2*(1-t)*t*P1[1] + t*t*P2[1]; x += Math.sin(t * 47.13) * 2 * (1 - t); // ±2px 手抖，接近目标时收敛 y += Math.sin(t * 33.7 + 1.3) * 2 * (1 - t); gsap.set("#cursor", { x, y }); // 一切由 p 推导，seek-safe }, }, "s1_trigger+=0.5"); // 点击反馈：Anticipation 缩小再回弹 tl.to("#cursor", { scale: 0.85, duration: 0.08, ease: "power1.in" }, ">"); tl.to("#cursor", { scale: 1, duration: 0.25, ease: "back.out" }, ">"); ``` ### 3.6 Logo 形变收束（Morph） 为什么：Logo 淡入没有叙事收束感，要让前一个视觉元素「坍缩」再「膨胀」成 Logo， 让叙事在品牌点上坍缩（best-practices §3.6）。 blur 走 CSS 变量（`filter` 是 paint-only、seek-safe，官方 depth-of-field-blur rule 认可的做法）： ```css #lastVisual, #logo { --blur: 0px; filter: blur(var(--blur)); will-change: filter; } ``` ```js tl.addLabel("morph", "s5_hold-=0.3"); // 坍缩：前一个视觉元素缩成色块，motion blur 升起 tl.to("#lastVisual", { scale: 0.1, "--blur": "6px", duration: 0.5, ease: "expo.out" }, "morph"); // 膨胀：Logo 从色块中心弹出，blur 收敛到锐利 tl.fromTo("#logo", { scale: 0.1, "--blur": "6px", autoAlpha: 0 }, { scale: 1, "--blur": "0px", autoAlpha: 1, duration: 0.6, ease: "back.out" }, "morph+=0.35"); // 150ms 量级交叠 = 快切 tl.to("#lastVisual", { autoAlpha: 0, duration: 0.15 }, "morph+=0.5"); // 之后：hold，无 tween，戛然而止 ``` ### 3.7 衬线 + 无衬线双字体 非 timeline 规则：静态 CSS，字体选择走品牌 spec。 HyperFrames 编译器会自动抓取 Google Fonts 并注入确定性 @font-face （Phase 0 实测，自研管线的字体时序坑在新后端不存在），CSS 里正常引 Google Fonts 即可。 ### 3.8 焦点切换 = 背景减弱 + 前景锐化 + Flash 引导 为什么：只降 opacity 时非焦点元素还是锐利的，必须加 blur 才真的退到后景 （best-practices §3.8）。 filter 三件套全部走 CSS 变量，GSAP tween 变量本身： ```css .tile { --f: 0; /* focusIntensity 0→1 */ filter: brightness(calc(1 - 0.5 * var(--f))) saturate(calc(1 - 0.3 * var(--f))) blur(calc(var(--f) * 4px)); /* ← 关键：blur 让非焦点真的退后 */ will-change: filter; } ``` ```js tl.addLabel("focus", "s3_process+=1.5"); // 非焦点元素：三滤镜 + dim 一次 tween 完成 tl.to(".tile:not(.focus-target)", { "--f": 1, opacity: 0.4, duration: 0.5, ease: "expo.out", }, "focus"); // Flash highlight 引导视线回流。 // 注意：原配方用 element.animate()（WAAPI），那走墙钟，seek 下不确定，必须翻译成 tween tl.fromTo("#focusFlash", { backgroundColor: "rgba(255,255,255,0.3)" }, { backgroundColor: "rgba(255,255,255,0)", duration: 0.15, ease: "power1.out" }, "focus+=0.5"); // 焦点释放：settle sharp。交给下一个 scene 前必须把 blur 收回 0， // 停在半虚化状态会被观众读成「渲染出 bug 了」 tl.to(".tile", { "--f": 0, opacity: 1, duration: 0.5, ease: "power2.inOut" }, "focus+=2.5"); ``` 性能约束（来自官方 DoF rule）：blur 半径大面积元素上 ≤24px；优先「dim + 适度 blur」 而不是把 blur 拉满；`will-change: filter` 只加在真的动 blur 的元素上。 --- ## 4 · 具体运动技巧 · §4 代码片段的 GSAP 版 ### 4.1 FLIP / Shared Element（按钮膨胀成输入框） 为什么：同一个元素在两种状态间过渡，不是两个元素 cross-fade（best-practices §4.1）。 原配方用 Framer Motion layoutId，GSAP 侧不引入 Flip 插件（在 HyperFrames 下未验证）， 直接手算：合成的视口是固定的（data-width/height），两个状态的几何都是设计稿常量， 用 fromTo 写死即可。位移缩放全走 transform，元素保持在最终布局位置： ```css /* 元素以「终态」布局，起态由 transform 表达 */ #search-box { width: 560px; height: 56px; } /* 静态终态，不 tween 尺寸 */ ``` ```js // 起态几何：按钮 120x44 在 (400, 300)，终态输入框 560x56 在 (200, 300) tl.fromTo("#search-box", { x: 200, y: 0, scaleX: 120/560, scaleY: 44/56, transformOrigin: "left top" }, { x: 0, y: 0, scaleX: 1, scaleY: 1, duration: 0.6, ease: "expo.out" }, "s2_generate"); // 内层文字反向补偿或延后进场，避免被 scaleX 拉伸（同 §4.2 的处理） tl.fromTo("#search-box .placeholder", { autoAlpha: 0 }, { autoAlpha: 1, duration: 0.3 }, "s2_generate+=0.4"); ``` ### 4.2 呼吸式展开（先展开、再注水） 为什么：面板不该同时拉 width 和 height，先横向展开再纵向撑起才像物理世界 （best-practices §4.2）。 原配方直接 tween width/height，这在 HyperFrames 是 reflow 禁区（整数像素 snap， 慢速段肉眼可见抖动，§7.2）。翻译成 scaleX/scaleY，时间错位保持不变： ```js // L = 展开总时长；前 40% 拉横、30% 处开始撑纵，两段交叠 const L = 0.9; tl.fromTo("#panel", { scaleX: 0, scaleY: 0.12, transformOrigin: "left top" }, { scaleX: 1, duration: 0.4 * L, ease: "expo.out" }, "open"); tl.to("#panel", { scaleY: 1, duration: 0.7 * L, ease: "expo.out" }, "open+=" + 0.3 * L); // 内容在壳展开完成后才浮现：既符合「先展开再注水」的意象， // 又让 scale 过程中的内容拉伸变形不可见 tl.fromTo("#panel .content", { autoAlpha: 0, y: 8 }, { autoAlpha: 1, y: 0, duration: 0.35 }, "open+=" + 0.75 * L); ``` 注意 scale 版不是逐像素忠实（圆角和边框会随比例变形）。展开壳是纯色 / 大圆角面板时 不可察觉；如果面板边框细节重要，改用「壳固定 + 内容 clip-path 揭示」的方案并实测截帧。 ### 4.3 Staggered Fade-up（30ms stagger） 为什么：列表挨个入场比整块出现更有「物体感」，30ms 是既定间隔（best-practices §4.3）。 ```js tl.fromTo(".row", { y: 10, autoAlpha: 0 }, { y: 0, autoAlpha: 1, duration: 0.4, ease: "expo.out", stagger: 0.03 }, "s3_process"); // 变体：从中心向两侧涌现（S4 爆发的多面板涌现常用） tl.fromTo(".panel", { y: 24, autoAlpha: 0, scale: 0.96 }, { y: 0, autoAlpha: 1, scale: 1, duration: 0.5, ease: "expo.out", stagger: { each: 0.03, from: "center" } }, "s4_boom"); ``` 用 `fromTo` 不用 `from`：sub-composition 会被反复 re-seek，`from` 在注册时刻 快照起始状态，回拖后可能错位；`fromTo` 两端显式声明，永远一致。 ### 4.4 关键结果前悬停 0.5s 为什么：机器执行快且连贯，但人脑需要反应时间，关键结果前停 0.5 秒是礼让观众 （best-practices §4.4，§0.2 核心信念第 3 条）。 GSAP 里「悬停」就是 position 参数上的一段空档，用 label 把停顿写成显式设计决策： ```js // 生成完成的时刻 tl.addLabel("generated", "s2_generate+=1.2"); // loading 态停住 0.5s：这 0.5s 内没有任何 tween，观众盯着加载状态 tl.addLabel("reveal", "generated+=0.5"); tl.fromTo("#result", { scale: 0.94, autoAlpha: 0 }, { scale: 1, autoAlpha: 1, duration: 0.7, ease: "expo.out" }, "reveal"); ``` ### 4.5 Anticipation → Action → Follow-through 为什么：只有 Action 的动画是 PowerPoint 动画，Disney 三段给动作生命感 （best-practices §4.6）。 三段顺序 tween，easing 按 §1 映射（预备 power1.in、主动 expo.out、回弹 elastic）： ```js tl.addLabel("pop", "s2_generate+=0.2"); tl.to("#card", { scale: 0.95, duration: 0.12, ease: "power1.in" }, "pop"); // 预备 tl.to("#card", { scale: 1.05, duration: 0.30, ease: "expo.out" }, ">"); // 主动 tl.to("#card", { scale: 1.00, duration: 0.35, ease: "elastic.out(1, 0.3)" }, ">"); // 回弹 ``` 单 tween 版：`ease: anticipation`（§1.1）一步完成「预备 + 主动」，回弹再补一段。 ### 4.6 3D Perspective + translateZ 分层 为什么：rotateX 8° / rotateY -4° 模拟镜头在桌面左上角俯视的 natural angle （best-practices §4.7）。 透视和分层是静态 CSS（照抄原配方，perspective / translateZ 不需要动）； 动的部分（入场时立起来、S4 拉远）用 GSAP 的 3D transform 别名： ```css .stage-wrap { perspective: 2400px; perspective-origin: 50% 30%; } .card-grid { transform-style: preserve-3d; } .card:nth-child(3n) { transform: translateZ(30px); } .card:nth-child(5n) { transform: translateZ(-20px); } .card:nth-child(7n) { transform: translateZ(60px); } ``` ```js // 入场：从正视缓慢立到黄金角 tl.fromTo("#card-grid", { rotationX: 0, rotationY: 0 }, { rotationX: 8, rotationY: -4, duration: 1.4, ease: "expo.out" }, "s2_generate"); ``` ### 4.7 斜向 Pan · 同时动 XY，频率不同 为什么：X 和 Y 用不同频率避免 Lissajous 循环规则化，模拟手持镜头的斜向漂移 （best-practices §4.8）。 原配方是 `Math.sin(flowT * ...)` 逐帧算，GSAP 版用两条不同 duration 的 yoyo tween 叠加（GSAP 对 x / y 独立追踪，两条 tween 不打架）。repeat 必须有限： ```js // 周期不同（4.6s vs 2.9s）= 频率不同，路径不闭合 // repeat 数从可见时长算出：Math.ceil(D / dur) 保证覆盖全片 tl.to("#stage", { x: 40, duration: 4.6, ease: "sine.inOut", yoyo: true, repeat: Math.ceil(D / 4.6) }, 0); tl.to("#stage", { y: 30, duration: 2.9, ease: "sine.inOut", yoyo: true, repeat: Math.ceil(D / 2.9) }, 0); ``` ### 4.8 戛然而止收尾 为什么：fade out 没有决定感，最后一帧要清晰、肯定（best-practices §0.3 留白）。 实现上是「不写代码」：S5 的 Logo 落位后，timeline 上不再有任何 tween， `data-duration` 比最后一个 tween 的结束时刻长 0.5-1s，画面 hold 在终态。 如果有 BGM，用 volume tween 在尾部收音（volume 在允许列表内）： ```js tl.to("#bgm", { volume: 0, duration: 0.4 }, "s5_hold+=0.8"); // 音频截停，画面不动 ``` --- ## 5 · 场景配方 A/B/C · timeline 结构要点 设计判断（选哪种、SFX 密度、BGM 风格）见 best-practices §5，这里只给 timeline 侧的差异。 ### 配方 A · Apple Keynote 戏剧式 - 骨架：§2 五段结构原样，S4 的 Boom 做足 - defaults：`ease: "expo.out"`，强调交互处覆盖 `"back.out"` - S4 标志动作：镜头急拉远 + drop。`tl.to("#stage", { scale: 0.78, y: -40, duration: 1.1, ease: "expo.inOut" }, "s4_boom")` - S5：Logo Morph（§3.6）+ 空灵单音 + hold ### 配方 B · 一镜到底工具式 - 骨架：**不用**五段峰值结构，一条持续 flow。label 按 BGM 小节打： `tl.addLabel("bar1", 0); tl.addLabel("bar2", 60/88*4);`（88 BPM，一小节 ≈ 2.73s） - 关键 UI 动作的 position 参数直接写在 kick/snare 时刻上，音乐律动即交互音效 - easing：`springEase`（§1.2）+ `"expo.out"`，落位感多于爆发感 - 没有 S4 式 Boom，收尾同样戛然而止 ### 配方 C · 办公效率叙事式 - 骨架：多 scene 硬切。每个 scene 一个 label，scene 间 autoAlpha 快切（0.15s） 而不是长交叠；配合 Dolly In/Out： `tl.fromTo("#scene2", { scale: 1.06 }, { scale: 1, duration: 1.2, ease: "expo.out" }, "sc2")` - toggle 类交互一律 `"back.out"`，面板一律 `"expo.out"` - 全片必有一处高光：3D pop-out（§4.6 的 rotationX + translateZ 元素浮起）， 只做一次，到处炫技是廉价信号（§0.3 克制） --- ## 6 · seek 安全规则（Phase 0 实测，全部踩过） HyperFrames 渲染是逐帧 seek + 截屏。任何不是「时间的纯函数」的状态都会在 渲染里出现不确定结果，而且**preview 里看起来往往是好的**，只有渲染产物才暴露。 ### 6.1 禁 CSS transition + class 切换 · 一律用 tween 表达 CSS transition 走浏览器墙钟，不走时间轴。逐帧 seek 时每帧都是一次「状态突变」， transition 要么不触发、要么起点错乱，Phase 0 迁移 c3 时实测中招。 ```css /* ✗ 旧写法：JS 里 classList.add('lit')，靠 transition 过渡 */ .capsule { transition: transform 0.3s ease; } .capsule.lit { transform: scale(1.06); } ``` ```js // ✓ 新写法：状态变化本身是 timeline 上的一段 tween tl.to("#capsule", { scale: 1.06, duration: 0.3, ease: "expo.out" }, "lit_at"); tl.to("#capsule", { scale: 1.0, duration: 0.3, ease: "expo.out" }, "lit_at+=1.2"); ``` 同类禁区：`element.animate()`（WAAPI，同样走墙钟，§3.8 的 Flash 已给翻译）、 CSS `@keyframes` animation 用于渲染关键动画。 交付前扫一遍：`grep -n "transition:\|animation:\|\.animate(" index.html`， 命中的每一处要么删掉、要么翻译成 tween。 ### 6.2 禁 animate 触发 reflow 的属性 · 用 transform 代替 layout 属性在浏览器 layout 阶段 snap 到整数设备像素。快速 tween 看不出来； 慢速 ease-out 尾巴上每帧移动不足 1px，就会「憋几帧、跳 1px」，肉眼可见的抖动。 Phase 0 的 lint 当场抓到 letterSpacing 逐帧抖动，正是这类无报警视觉 bug。 | ✗ 禁 tween | ✓ 忠实替代 | |---|---| | `width` / `height` | `scaleX` / `scaleY` + `transformOrigin`（内容处理见 §4.2） | | `top` / `left` / `right` / `bottom` | 元素停在 CSS 终态位，tween `x` / `y` 偏移量 | | `fontSize` | `scale`（视觉等价，sub-pixel 平滑） | | `letterSpacing` / `wordSpacing` | 逐字 split 后 tween 每个字符的 `x`（uniform scale 不是同一个效果，它缩放字形而不是字距） | | `margin*` / `padding*` | 布局写死，动 `x` / `y` | 修复原则：**重现同一个视觉，只去掉抖动**。过 lint 不是标准，和原动画逐帧对比才是。 ### 6.3 t=0 时 onUpdate 不触发 · 代理 tween 必须手动补首帧 timeline seek 到 0 时 proxy tween 的 `onUpdate` 可能不触发，首帧就是白屏 / 初始 DOM。 所有 proxy 驱动的场景（§3.4 chunk reveal、§3.5 鼠标、§7 老 demo 适配器）， 注册完 timeline 后手动调一次： ```js window.__timelines["main"] = tl; render(0); // 首帧保险：把 t=0 的画面显式画出来 ``` ### 6.4 禁 Math.random / Date.now · 随机用种子函数 同一帧每次 seek 必须得到同一画面。运行时随机 = 每次渲染不同 = 无法逐帧渲染。 需要「随机感」（粒子、抖动、不规律间隔）时用 mulberry32，**建 timeline 前** 一次性生成所有随机值（Phase 0 的 3D 粒子 demo 实测写法）： ```js function mulberry32(seed) { return function () { seed |= 0; seed = (seed + 0x6d2b79f5) | 0; let t = Math.imul(seed ^ (seed >>> 15), 1 | seed); t = (t + Math.imul(t ^ (t >>> 7), 61 | t)) ^ t; return ((t ^ (t >>> 14)) >>> 0) / 4294967296; }; } const rand = mulberry32(20260717); // 种子写死，改种子 = 换一版随机 // 用法：预生成，不在 onUpdate 里现抽 const offsets = Array.from({ length: 40 }, () => (rand() - 0.5) * 24); ``` 同理禁用：`Date.now()`、`performance.now()`、任何事件驱动状态（渲染模式没有输入事件）。 --- ## 7 · 老 demo 适配器配方 · render(t) 挂进 GSAP 21 个自研引擎老 demo 的动画核心都是 `render(t)` 纯函数。迁移不重写动画逻辑， 用一个代理 tween 把 render(t) 挂到 GSAP timeline 上（Phase 0 实测：单个 demo 20-30 分钟，动画代码一行不改，c3 电影级 demo 1134 行验证通过）。 ### 7.1 代理 tween 模板（12 行，c3 实测原版） ```js // =============== HyperFrames adapter =============== // 代理 tween 驱动原 render(t)。每一帧都是时间轴时间的纯函数： // 无 rAF、无时钟、无输入状态。 window.__timelines = window.__timelines || {}; const proxy = { t: 0 }; const tl = gsap.timeline({ paused: true }); tl.to(proxy, { t: T.DURATION, // 老 demo 的总时长常量 duration: T.DURATION, ease: "none", // 时间必须匀速映射，easing 在 render(t) 内部 onUpdate: () => render(proxy.t), }, 0); window.__timelines["main"] = tl; // 首帧保险（timeline 停在 t=0 时 onUpdate 不触发，§6.3） render(0); ``` ### 7.2 迁移四步 1. **包 root / clip**：给最外层容器加合成根属性 （`data-composition-id="main"` + `data-duration` + 尺寸）， 舞台元素加 `.clip` 及 `data-start` / `data-duration` / `data-track-index`。 完整契约见 `hyperframes-backend.md` 2. **删自驱**：删掉 rAF 循环、`setInterval`、自动 play 逻辑、 `performance.now()` 起点。`render(t)` 只吃参数 t，不再自己找时间 3. **挂 proxy**：粘 §7.1 模板，`T.DURATION` 对上 `data-duration`，末尾 `render(0)` 4. **扫 transition**：`grep -n "transition:\|animation:\|\.animate(\|Math.random\|Date.now\|performance.now"` 逐条清零。class 切换类效果按 §6.1 改成 t 的纯函数（老 demo 最常见的残留 就是「classList.add + transition」组合） 迁完跑一次 `npx hyperframes check`（暗色 cinematic 用 `--no-contrast`， 其余四门必须 0 error），再抽 3-4 个关键时刻截帧和老版对比。 ### 7.3 什么时候不用适配器 适配器是**存量迁移**方案。新写的动画直接用本文件 §0-§5 的原生 timeline 写法： label 可读、stagger 声明式、GSAP inspector 能逐 tween 检查， proxy 大黑盒里的动画对审计工具是不透明的。 --- ## 8 · 交付前自检（GSAP 侧，补充 best-practices §7 清单) - [ ] timeline `paused: true`，注册 key 等于 `data-composition-id`？ - [ ] defaults 是 `expo.out`，没有裸 `linear` / `ease` 出现在元素动效上？ - [ ] 五段 label 齐全，S5 之后有 hold 留白（没有 fade out）？ - [ ] `grep "transition:\|\.animate(\|Math.random\|Date.now"` 结果为 0？ - [ ] 没有 tween width / height / top / left / letterSpacing / fontSize？ - [ ] 所有 `repeat` 是有限数？ - [ ] proxy 场景末尾补了 `render(0)`？ - [ ] blur / filter 全部走 CSS 变量，动过 blur 的元素有 `will-change: filter`？ - [ ] sub-composition 里入场全用 `fromTo` 不用 `from`？ - [ ] `npx hyperframes check` 通过（暗色片 `--no-contrast`，其余 0 error）？ --- ## 9 · Camera Rig 配方 · 镜头运动的实现层 为什么：镜头运动和元素动画抢同一个 transform 是运镜混乱的技术根源 （camera-language.md §3）。所有镜头级 tween 收口到专职 rig 容器， 相机状态用一个 proxy 对象承载，每帧由它推导出全部相机 DOM 状态，seek-safe。 ### 9.1 rig 容器结构（静态骨架） ```html <div id="viewport"> <!-- 固定视口 --> <div id="camera"> <!-- 镜头层：只有相机 transform --> <div id="world">...</div> <!-- 世界层：元素动画只发生在这里面 --> </div> <div id="hud">...</div> <!-- 字幕/角标：#camera 的兄弟，天然静止 --> </div> ``` ```css #viewport { position: relative; width: 1920px; height: 1080px; overflow: hidden; } #camera { position: absolute; inset: 0; perspective-origin: 960px 540px; } #world { position: absolute; transform-origin: 0 0; will-change: transform; } /* pan 露边保险：#world 尺寸 ≥ 视口 + 最大 pan 振幅 + 8% 边距（camera-language §3.3） */ ``` ### 9.2 相机 proxy + PageCam 关键帧翻译 相机是一个普通对象，GSAP tween 它的字段，`onUpdate` 里把状态写进 DOM。 一切由 cam 推导，回拖也正确（同 §3.4 chunk reveal 的 proxy 思路）： ```js const cam = { cx: 960, cy: 540, zoom: 1, rotX: 0, rotY: 0, rotZ: 0, persp: 1200 }; const camEl = document.querySelector("#camera"); const world = document.querySelector("#world"); // ── 平面模式（纯 zoom + pan，无旋转）────────────────────────── function applyCam() { world.style.transform = `translate(${960 - cam.cx * cam.zoom}px, ${540 - cam.cy * cam.zoom}px) scale(${cam.zoom})`; applyCounter(); } // ── 3D 模式（有 rotX/rotY/rotZ）· 放大走 CSS zoom 属性，不走 scale ── // 布局级缩放让 Chromium 按放大后尺寸栅格化，根治 3D 下文字发糊 // （camera-language §3.4，全库最贵知识）。zoom 改变坐标系，translate 要除以 zoom。 function applyCam3d() { camEl.style.perspective = `${cam.persp * cam.zoom}px`; world.style.zoom = cam.zoom; world.style.transformOrigin = `${cam.cx}px ${cam.cy}px`; world.style.transform = `translate(${960 / cam.zoom - cam.cx}px, ${540 / cam.zoom - cam.cy}px)` + ` rotateY(${cam.rotY}deg) rotateX(${cam.rotX}deg) rotateZ(${cam.rotZ}deg)`; applyCounter(); } ``` 注意：CSS `zoom` 每帧触发 re-layout，是 §6.2 reflow 禁令的**唯一合法例外**， 只允许用在 `#world` 相机层。HyperFrames / Playwright 离线逐帧渲染下单帧耗时不影响产物； 实时 preview 掉帧属正常，以渲染产物为准。 ### 9.3 对数时长 helper（固定 duration 是业余感的来源） ```js // camera-language §4.2：1→2x 正好 0.55s，任何幅度的 zoom 视觉速度一致 function zoomDur(z1, z2) { return gsap.utils.clamp(0.30, 0.94, 0.55 * Math.abs(Math.log(z2 / z1)) / Math.LN2); } ``` ### 9.4 镜头段落写法（推近 → hold → 平移 → 谢幕拉出） 镜头 tween 全部驱动 cam，easing 按 camera-language §4.1： 主动推拉 `power3.inOut`，跟随式 `cubic-bezier(0.33,0,0.15,1)`（自定义 ease 见下）。 ```js const followEase = gsap.parseEase("0.33,0,0.15,1"); // shotcraft 相机默认 // 定场微推：开机即 1.06x，3s 缓出回全景（片长 >14s 且首镜 >7s 时才加） tl.fromTo(cam, { zoom: 1.06 }, { zoom: 1, duration: 3.0, ease: "power2.out", onUpdate: applyCam }, 0); // 推近特写：目标点 (1240, 430)，1 → 1.8x，时长由公式给 tl.to(cam, { cx: 1240, cy: 430, zoom: 1.8, duration: zoomDur(1, 1.8), ease: "power3.inOut", onUpdate: applyCam }, "s2_generate"); // 镜头到位后 hold ≥1.2s 再走（不写 tween 就是 hold） // 中距焦点转移：不回 1x，直接平移过去（镜间语法：0.22-0.45 改平移） tl.to(cam, { cx: 880, cy: 620, duration: 0.7, ease: followEase, onUpdate: applyCam }, "s3_process+=1.5"); // 谢幕：0.55s 拉出 + ≥0.8s 全景停顿，data-duration 覆盖到停顿末尾 tl.to(cam, { cx: 960, cy: 540, zoom: 1, duration: 0.55, ease: "power3.inOut", onUpdate: applyCam }, "s5_hold"); window.__timelines["main"] = tl; applyCam(); // 首帧保险：timeline 停在 t=0 时 onUpdate 不触发（§6.3） ``` 镜头预算不写在代码里，写在排镜时：相邻镜头 tween 起点间隔 ≥2.6s、 15s 窗口 ≤4-5 个、<1.25x 的 zoom 不排（camera-language §0/§4.4）。 ### 9.5 counter-transform · 跟随字幕/标注保持字号恒定 字幕和 chrome 首选放 `#hud`（不跟镜头，零成本）。必须挂在 world 内、 跟着元素走但字号要恒定的标注，反向抵消镜头缩放： ```js const counters = gsap.utils.toArray(".cam-counter"); // 需要恒定字号的标注 function applyCounter() { const inv = 1 / cam.zoom; counters.forEach((el) => { el.style.transform = `scale(${inv})`; }); } ``` `.cam-counter` 自身的入场动画写在其**子元素**上，避免和 counter scale 抢 transform。 ### 9.6 多层 parallax · 全部由 cam 推导 每层不给独立 tween，速度系数乘同一个相机位移（层间系数比 ≥2 倍、≤4 层， camera-language §8.1），天然同步、天然 seek-safe： ```js const LAYERS = [ { el: document.querySelector("#bg"), k: 0.35 }, { el: document.querySelector("#mid"), k: 0.7 }, { el: document.querySelector("#fg"), k: 1.4 }, ]; function applyParallax() { const dx = 960 - cam.cx, dy = 540 - cam.cy; // 相机位移 LAYERS.forEach(({ el, k }) => { el.style.transform = `translate(${dx * k}px, ${dy * k}px)`; }); } // 把 applyParallax() 追加进 applyCam() 末尾即可 ``` ### 9.7 Camera Rig 自检（追加到 §8 清单） - [ ] 镜头 tween 只动 cam proxy，`#world` 内元素没有被相机 tween 碰过？ - [ ] 注册 timeline 后补了 `applyCam()` 首帧？ - [ ] 3D 文字特写用了 CSS `zoom`，没有 `scale()` 放大发糊？ - [ ] `zoom` 属性只出现在 `#world` 上（reflow 例外不扩散）？ - [ ] 推拉时长全部来自 `zoomDur()`，没有手写常数？ - [ ] 谢幕拉出后有 ≥0.8s 无 tween 的全景 hold？ -
hero-animation-case-study.md 11.1 KB
# Gallery Ripple + Multi-Focus · 场景编排哲学 > 从 huashu-design hero 动画 v9（25 秒，8 场景）里提炼出的**一种可复用的视觉编排结构**。 > 不是动画制作流水线，是**什么场景下这种编排是"对的"**。 > 实战参考：[demos/hero-animation-v9.mp4](../demos/hero-animation-v9.mp4) · [https://www.huasheng.ai/huashu-design-hero/](https://www.huasheng.ai/huashu-design-hero/) ## 一句话先行 > **当你有 20+ 同质视觉素材、场景需要"表达规模感和深度"时，优先考虑 Gallery Ripple + Multi-Focus 这套编排，而不是堆砌排版。** 通用 SaaS feature 动画、产品发布会、skill 推广、系列作品集展示——只要素材数量够、风格一致，这套结构几乎都能出效果。 --- ## 这个手法究竟在表达什么 不是"秀素材"——是通过**两个节奏变化**讲一个叙事： **第一拍 · Ripple 展开（~1.5s）**：从中心向四周扩散出 48 张卡片，观众被"量"震住——「哦，这东西有这么多产出」。 **第二拍 · Multi-Focus（~8s，4 次循环）**：镜头在慢速 pan 的同时，4 次把背景 dim + desaturate，把某一张卡单独放大到屏幕中央——观众从"量的冲击"切换到"质的凝视"，每次 1.7s 节奏稳定。 **核心叙事结构**：**规模（Ripple） → 凝视（Focus × 4） → 淡出（Walloff）**。这三拍组合起来表达的是「Breadth × Depth」——不只是能做很多，每一个还都值得停下来看。 对比一下反例： | 做法 | 观众感知 | |------|---------| | 48 张卡静态排列（没有 Ripple）| 好看但无叙事，像一张 grid screenshot | | 一张一张快切（没有 Gallery context）| 像 slideshow，失去"规模感" | | 只有 Ripple 没有 Focus | 震住了但没让人记住任何具体一张 | | **Ripple + Focus × 4（本配方）** | **先震撼于量，再凝视于质，最后平静淡出——完整情绪弧线** | --- ## 前置条件（必须全部满足） 这套编排**不是万能的**，下面 4 条缺一不可： 1. **素材规模 ≥ 20 张，最好 30+** 少于 20 张 Ripple 会显得"空"——48 格里每格都在动才有密度感。v9 用了 48 格 × 32 张图（循环填充）。 2. **素材视觉风格一致** 全是 16:9 slide 预览 / 全是 app 截图 / 全是封面设计——长宽比、色调、版式得像是"一套"。混搭会让 Gallery 看起来像剪贴板。 3. **素材单独放大后仍有可读信息** Focus 是把某张卡放大到 960px 宽，如果原图放大后糊了或信息稀薄，Focus 这一拍就废了。反向验证：能不能从 48 张里挑出 4 张作为"最有代表性"的？挑不出来就说明素材质量不齐。 4. **场景本身是 landscape 或 square，不是竖屏** Gallery 的 3D 倾斜（`rotateX(14deg) rotateY(-10deg)`）需要横向延伸感，竖屏会让倾斜效果看起来窄且别扭。 **缺条件的后备路径**： | 缺什么 | 退化为什么 | |-------|-----------| | 素材 < 20 张 | 改用「3-5 张并排静态展示 + 逐个 focus」 | | 风格不一致 | 改用「封面 + 3 章节大图」的 keynote-style | | 信息稀薄 | 改用「data-driven dashboard」或「金句 + 大字」 | | 竖屏场景 | 改用「vertical scroll + sticky cards」 | --- ## 技术配方（v9 实战参数） ### 4-Layer 结构 ``` viewport (1920×1080, perspective: 2400px) └─ canvas (4320×2520, 超大 overflow) → 3D tilt + pan └─ 8×6 grid = 48 cards (gap 40px, padding 60px) └─ img (16:9, border-radius 9px) └─ focus-overlay (absolute center, z-index 40) └─ img (matches selected slide) ``` **关键**：canvas 比 viewport 大 2.25 倍，这样 pan 才有"窥视更大世界"的感觉。 ### Ripple 展开（距离延迟算法） ```js // 每张卡的入场时间 = 距中心的距离 × 0.8s 延迟 const col = i % 8, row = Math.floor(i / 8); const dc = col - 3.5, dr = row - 2.5; // 到中心的 offset const dist = Math.hypot(dc, dr); const maxDist = Math.hypot(3.5, 2.5); const delay = (dist / maxDist) * 0.8; // 0 → 0.8s const localT = Math.max(0, (t - rippleStart - delay) / 0.7); const opacity = expoOut(Math.min(1, localT)); ``` **核心参数**： - 总时长 1.7s（`T.s3_ripple: [8.3, 10.0]`） - 最大延迟 0.8s（中心最早出，角落最晚） - 每张卡入场时长 0.7s - Easing: `expoOut`（爆发感，不是平滑） **同时做的事**：canvas scale 从 1.25 → 0.94（zoom out to reveal）—— 配合出现的同步推远感。 ### Multi-Focus（4 次节奏） ```js T.focuses = [ { start: 11.0, end: 12.7, idx: 2 }, // 1.7s { start: 13.3, end: 15.0, idx: 3 }, // 1.7s { start: 15.6, end: 17.3, idx: 10 }, // 1.7s { start: 17.9, end: 19.6, idx: 16 }, // 1.7s ]; ``` **节奏规律**：每个 focus 1.7s，间隔 0.6s 喘息。总计 8s（11.0–19.6s）。 **每次 focus 内部**： - In ramp: 0.4s（`expoOut`） - Hold: 中间 0.9s（`focusIntensity = 1`） - Out ramp: 0.4s（`easeOut`） **背景变化（这是关键）**： ```js if (focusIntensity > 0) { const dimOp = entryOp * (1 - 0.6 * focusIntensity); // dim to 40% const brt = 1 - 0.32 * focusIntensity; // brightness 68% const sat = 1 - 0.35 * focusIntensity; // saturate 65% card.style.filter = `brightness(${brt}) saturate(${sat})`; } ``` **不只是 opacity——同时 desaturate + darken**。这让前景 overlay 的色彩"跳出来"，而不是只是"变亮一点"。 **Focus overlay 尺寸动画**： - 从 400×225（入场）→ 960×540（hold 态） - 外围有 3 层 shadow + 3px accent 色 outline ring，呈现"被框住的感觉" ### Pan（持续感让静止不无聊） ```js const panT = Math.max(0, t - 8.6); const panX = Math.sin(panT * 0.12) * 220 - panT * 8; const panY = Math.cos(panT * 0.09) * 120 - panT * 5; ``` - 正弦波 + 线性 drift 双层运动——不是纯循环，每个时刻位置都不同 - X/Y 频率不同（0.12 vs 0.09）避免视觉上看出"规律循环" - clamp 在 ±900/500px 防止漂出 **为什么不用纯线性 pan**：纯线性观众会"预测"下一秒在哪；正弦+drift 让每一秒都是新的，3D 倾斜下产生"微晕船感"（好的那种），注意力被拉住。 --- ## 5 个可复用模式（从 v6→v9 迭代中蒸馏） ### 1. **expoOut 作为主 easing，不是 cubicOut** `easeOut = 1 - (1-t)³`（平滑）vs `expoOut = 1 - 2^(-10t)`（爆发后迅速收敛）。 **选择理由**：expoOut 的前 30% 很快达到 90%，更像物理阻尼，符合"重的东西落地"的直觉。特别适合： - 卡片入场（重量感） - Ripple 扩散（冲击波） - Brand 浮起（落定感） **什么时候仍用 cubicOut**：focus out ramp、对称的微动效。 ### 2. **纸感底色 + 赤陶橙 accent（Anthropic 血统）** ```css --bg: #F7F4EE; /* 暖纸 */ --ink: #1D1D1F; /* 几乎黑 */ --accent: #D97757; /* 赤陶橙 */ --hairline: #E4DED2; /* 暖线条 */ ``` **为什么**：温暖底色在 GIF 压缩后依然有"呼吸感"，不像纯白会显得"屏幕感"。赤陶橙作为唯一 accent 贯穿 terminal prompt、dir-card 选中、cursor、brand hyphen、focus ring——所有视觉锚点都被这一个色串起来。 **v5 教训**：加了 noise overlay 以模拟"纸纹"，结果 GIF 帧压缩全废（每帧都不同）。v6 改为"只用底色 + 暖 shadow"，纸感保留 90%，GIF 体积缩小 60%。 ### 3. **两档 Shadow 模拟深度，不用真 3D** ```css .gallery-card.depth-near { box-shadow: 0 32px 80px -22px rgba(60,40,20,0.22), ... } .gallery-card.depth-far { box-shadow: 0 14px 40px -16px rgba(60,40,20,0.10), ... } ``` 用 `sin(i × 1.7) + cos(i × 0.73)` 确定性算法给每张卡分配 near/mid/far 三档 shadow——**视觉上有"三维堆叠"感，但每帧 transform 完全不变，GPU 消耗 0**。 **真 3D 的代价**：每个 card 单独 `translateZ`，GPU 每帧都在算 48 个 transform + shadow blur。v4 试过，Playwright 录制 25fps 都吃力。v6 的两档 shadow 肉眼效果差距 <5%，但成本差 10 倍。 ### 4. **字重变化（font-variation-settings）比字号变化更电影感** ```js const wght = 100 + (700 - 100) * morphP; // 100 → 700 over 0.9s wordmark.style.fontVariationSettings = `"wght" ${wght.toFixed(0)}`; ``` Brand wordmark 从 Thin → Bold 用 0.9s 渐变，配合 letter-spacing 微调（-0.045 → -0.048em）。 **为什么比放大缩小好**： - 放大缩小观众看过太多，预期固化 - 字重变化是"内在的充实感"，像气球被吹满，而不是"被推近" - variable fonts 是 2020+ 才普及的特性，观众下意识感觉"现代" **限制**：必须用支持 variable font 的字体（Inter/Roboto Flex/Recursive 等）。普通静态字体只能拟态（切换几个固定 weight 有跳变）。 ### 5. **Corner Brand 低强度持续签名** Gallery 阶段左上角有个 `HUASHU · DESIGN` 小标识，16% opacity 色值，12px 字号，宽字距。 **为什么加这个**： - Ripple 爆发后观众容易"失焦"不记得在看什么，左上角轻标示帮助 anchor - 比全屏大 logo 更高级——做品牌的人知道，品牌签名不需要喊 - 在 GIF 被截屏分享时仍留下归属信号 **规则**：只在中段（画面 busy）出现，开场关闭（不遮 terminal），结尾关闭（brand reveal 是主角）。 --- ## 反例：什么时候不要用这套编排 **❌ 产品演示（要展示功能的）**：Gallery 让每一张都一闪而过，观众记不住任何一个功能。改用「单屏 focus + tooltip 标注」。 **❌ 数据驱动内容**：观众要读数字，Gallery 的快速节奏不给时间读。改用「数据图表 + 逐项 reveal」。 **❌ 故事叙事**：Gallery 是"并列"结构，故事需要"因果"。改用 keynote 章节切换。 **❌ 素材只有 3-5 张**：Ripple 密度不够，看起来像"补丁"。改用「静态排列 + 逐张高亮」。 **❌ 竖屏（9:16）**：3D tilt 需要横向延伸，竖屏会让倾斜感觉"歪"而不是"展开"。 --- ## 如何判断自己的任务适用这套编排 三步快速检查： **Step 1 · 素材数量**：数一下你有多少同类视觉素材。< 15 → 停；15-25 → 凑；25+ → 直接用。 **Step 2 · 一致性测试**：把 4 张随机素材并排放，是否像「一套」？不像 → 先统一风格再做，或改方案。 **Step 3 · 叙事匹配**：你要表达的是「Breadth × Depth」（量 × 质）吗？还是「流程」「功能」「故事」？不是前者就别硬套。 三步都 yes，直接 fork v6 HTML，改 `SLIDE_FILES` 数组和时间轴就能复用。调色板改 `--bg / --accent / --ink`，整体换皮不换骨。 --- ## 相关 Reference - 完整技术流程：[references/animations.md](animations.md) · [references/animation-best-practices.md](animation-best-practices.md) - 动画导出流水线：[references/video-export.md](video-export.md) - 音频配置（BGM + SFX 双轨）：[references/audio-design-rules.md](audio-design-rules.md) - Apple 画廊风格的横向参考：[references/apple-gallery-showcase.md](apple-gallery-showcase.md) - 源 HTML（v6 + 音频集成版）：`www.huasheng.ai/huashu-design-hero/index.html` -
hyperframes-backend.md 7.3 KB
# HyperFrames 渲染后端 · 选型边界与操作手册 > 2026-07-17 实测验证通过后引入（工具链/中文字体/代理环境/迁移/3D 五项全过，关键数据已内嵌本文）。 > HyperFrames 是 HeyGen 开源的 HTML→视频框架（Apache 2.0）：纯 HTML + 暂停的 GSAP timeline，headless 浏览器逐帧 seek 确定性渲染。 ## 选型边界（先看这张表再开工） | 场景 | 用哪条渲染路线 | |---|---| | 新动画项目（默认） | **HyperFrames**。审计套件白送、3D/GSAP/Lottie/shader 全解锁 | | 需要 3D / 粒子 / 物理惯性 / shader 转场 | HyperFrames（自研 Stage 做不到） | | 老 Stage demo 要复用/改版 | 顺手迁移（适配器配方见下，20-30 分钟/个）；只重渲不改就仍用 render-video-seek.js | | 弱 runtime（无 npm / 无法装依赖 / 单文件交付给用户双击打开） | 自研 Stage（assets/animations.jsx），老流程不变 | | 交互演示（用户要在浏览器里玩，不导出视频） | 自研 Stage 或普通 HTML，HyperFrames 是渲染管线不是交互框架 | | 带解说长视频（Step 9.5，narration_stage 驱动） | **自研 narration 管线**（voiceover-pipeline.md + render-narration.sh），暂不走 HyperFrames——双时间源/字幕/TTS timeline 深度耦合自研 Stage；与「动画默认 HyperFrames」两行同时命中时按本行裁决 | | 批量参数化视频（千人千面/模板换字） | Remotion（见规划方向5，独立于本 skill 主流程） | **设计语言永远是甲方**：叙事结构、easing 体系、SFX/BGM 双轨制照旧全部生效（animation-best-practices.md / audio-design-rules.md），HyperFrames 只是实现和渲染工具。GSAP 实现配方见 `references/gsap-recipes.md`。 ## 项目脚手架 > ⚠️ 安装预警：`hyperframes init` 除了生成项目文件，还会把 **19 个 hyperframes skill 安装到 > `~/.claude/skills/`**（渲染后端的合成契约文档，纯文档无可执行 hook）。介意的话先跑 > `npx hyperframes docs` 看本地文档清单再决定是否 init。 ```bash npx -y hyperframes init 项目名 --example blank # 非交互必须带 --example cd 项目名 && npm install ``` 生成 index.html / hyperframes.json / meta.json / package.json（pin 了 CLI 版本）+ 项目级 CLAUDE.md。init 会把 19 个 hyperframes skill 装到 `~/.claude/skills/`（本机已装）。合成写法契约读 hyperframes-core skill 的 SKILL.md（init 装到各 runtime 的 skill 目录，Claude Code 默认 `~/.claude/skills/`；无 skill 机制的 runtime 直接读 `npx hyperframes docs` 本地文档替代），本地文档 `npx hyperframes docs <topic>`（data-attributes / gsap / rendering / troubleshooting）。 **版本策略**：项目 package.json 会 pin 精确版本（当前实测过的是 0.7.61）。它迭代极快（300+ releases），升级先 `npx hyperframes@latest upgrade --project . --check` 看 delta，跑一遍回归 demo 再动。 ## 合成契约速查（完整版读 hyperframes-core） - 根容器：`data-composition-id` + `data-start` + `data-duration` + `data-width/height` - 每个计时元素：`class="clip"` + `data-start` + `data-duration` + `data-track-index` - timeline 必须 paused 并注册：`window.__timelines["合成id"] = gsap.timeline({paused:true})` - 视频素材用 `muted`，音轨单独 `<audio>` 元素 - **只允许确定性逻辑**：禁 `Date.now()` / `Math.random()` / 运行时网络 fetch；随机用种子函数 - 字体：Google Fonts 会被编译器自动抓取并注入确定性 @font-face（缓存 `~/.cache/hyperframes/fonts/`）；纯系统字体（PingFang SC 等）加一行 `@font-face { font-family:"PingFang SC"; src: local("PingFang SC"); }` 过 lint - Three.js 走 `hf-seek` 事件适配器（`~/.claude/skills/hyperframes-animation/adapters/three.md`），根容器必须显式 `data-duration` ## 老 demo 迁移 · 适配器配方（实测 20-30 分钟/个） 自研 Stage/纯 render(t) 动画不用重写，四步： 1. **包容器**：外套 `#root` 带合成 data 属性；整个 `.stage` 作为唯一 clip 最省事（`class="stage clip"` + data-start/duration/track-index）；`.stage` 从 fixed 居中改 absolute inset:0，html/body 定死 1920×1080 2. **删自驱**：rAF tick 循环、fitStage/resize 监听、replay 按钮、`__ready/__setTime/__seek` 协议全删（渲染器不需要） 3. **挂代理 tween**（核心 12 行）： ```js const proxy = { t: 0 }; const tl = gsap.timeline({ paused: true }); tl.to(proxy, { t: DURATION, duration: DURATION, ease: "none", onUpdate: () => render(proxy.t) }, 0); window.__timelines = window.__timelines || {}; window.__timelines["main"] = tl; render(0); // 必须：timeline 停在 t=0 时 onUpdate 不触发，不补这句首帧可能未初始化 ``` 4. **扫 transition**：全文搜 `transition:` 声明。CSS transition + class 切换走墙钟，逐帧 seek 下不确定，必须改成 render(t) 里对 t 的纯函数（lerp） ## 校验与渲染 ```bash npm run check # lint+runtime+layout+motion+contrast 五门审计 npx hyperframes check --no-contrast # 暗色电影风专用（见下） npx -y hyperframes@<pin版本> render --fps 60 # 终渲；默认 30fps ``` - **check 必须 0 error 才渲染**（contrast 门除外）。lint 能拦 letterSpacing 抖动、字体缺失、非确定性等一整类「无报警视觉 bug」 - **contrast 门取舍**：它按 WCAG 4.5:1 检查，和暗色电影风的低对比水印/装饰文字（16-40% 透明度）根本冲突，且无逐元素豁免。暗色 cinematic 产出统一 `--no-contrast`，其余四门仍必须 0 error。亮底信息型产出不要跳，contrast 报错通常是真问题 - **两级渲染**：先默认 30fps 快速出片，肉眼+截帧检查通过后再 `--fps 60` 终渲。60fps 600 帧 1080p 实测约 20 秒 - 渲染产物侧校验（audio stream / 黑帧 / 响度 / 时长）用 `scripts/verify-video.sh`（见 verification.md） ## 透明通道（overlay花字/贴片直接叠剪辑轨） `npx hyperframes render --format mov` 输出 ProRes 4444（yuva444p12le，带alpha，2026-07-17实测叠色底连软阴影都正确半透）；`--format webm` 同样带透明、体积小；`--format png-sequence` 出RGBA帧序列给AE/达芬奇。合成侧要点：html/body背景设 `transparent`、不铺底色。花字/角标/lower-third这类overlay素材从此直接进剪辑轨，不用抠像。注意MOV体积大（ProRes无损级，4秒15MB量级），交付剪辑用；网络传输用webm。 ## 音频 HyperFrames 合成里 `<audio>` 元素可直接进时间轴（BGM/解说随片渲染）。当前音频流程不变：SFX/BGM 双轨制照 audio-design-rules.md，用 add-music.sh / mix-voiceover.sh 后期混流也可以。哪条路更好在实战中定，先不强制。SFX打点用 `scripts/sfx-cues.sh <视频> <cue表.tsv> <输出>`（cue表=秒数/sfx路径/音量dB三列，B00实战沉淀，改表重跑10秒出片）。 ## pitfalls 增量（相对自研管线） 自研管线 pitfalls（animation-pitfalls.md §7/10/12/13 录制协议类、§6 字体时序、§15/17 网络类）在 HyperFrames 后端上**不适用**：录制协议由框架内部处理，字体编译期抓取，CDN 实测代理下可通。新增的坑共四条，已录入 animation-pitfalls.md §18-21：CSS transition 非确定性、代理 tween 首帧、contrast 门冲突、fromTo immediateRender 幻影。 -
launch-film-director-notes.md 14.5 KB
# Launch Film 工作流：先写万字 director's notes，再做动画 > 高规格视觉作品（≥ 20 秒、含品牌叙事、含 slogan reveal、可能上 X / 公众号 / B 站推广）的标准工作流。 > > 触发条件：任务是「产品升级宣传片 / 品牌 launch film / launch trailer / superbowl-tier ad / brand campaign / hero animation video」，且**用户对质量有明确预期**（如「超级碗品质感」「10x 细节」「Apple 级别」）。 > > 反触发：不要在「快速做个动画 demo」「简单 motion graphic」「单个图标动画」时用这条流程——会过度工程化。 --- ## 1. 为什么先写 director's notes 实战教训（2026-05-11 huashu-md-html v2.0 项目）： 第一轮直接动手写 HTML，产出的是「程序员视角的动画」——每个 capability 平均用力、节奏匀速、slogan 撞在一起、缺少叙事弧。 第二轮接到用户「停下，先按苹果导演视角写 1 万字分镜脚本」的指令，写了 v5-director-notes.md（11500 字、13 镜 shot-by-shot spec），然后按脚本实施——一次过、每帧 pause 都耐看、节奏起伏有 climax。 **核心差异**：写脚本是 think，写 HTML 是 execute。先 think 透了，execute 就是机械翻译。先 execute，每个 shot 都是临场决策，必然乱。 写 director's notes 不是「装」，是把所有视觉决策**在动手之前**沉淀成文档——每一镜都已经在脑里 visualize 过、reasoning 过、和上下文 trace 过。HTML 实施时不需要再做创意决策，只需要忠实翻译。 --- ## 2. 触发判断（先问自己 3 个问题） 启动 launch film 工作流前问： 1. **这支片承担品牌叙事吗？**（有 thesis / slogan reveal / 升级仪式感）—— 是 → 走 director's notes 流程 2. **观众会暂停看吗？**（可能截图、做 X 海报、做封面、慢速 review）—— 是 → 每帧要耐看 3. **客户/用户有「我希望像 XXX 那样」的参照？**（Apple / Anthropic / Nike / Penguin / 某导演）—— 是 → 必须明确视觉语境 任一为「是」就走流程。三个都「否」就跳过，直接用 [animations.md](animations.md) 的标准流程。 > 🔴 **前置门（先于本流程）**：launch film 也必须先过 SKILL.md 的三方向硬门——每方向一张「方向板」（hero 关键帧真实静帧 + 色板 + 气质句 + 参照），用户选定方向后，万字 director's notes 才围绕选定方向展开。指定了「Apple 级」等风格词不豁免（2026-07-18 HuaStudio 实锤）。 --- ## 3. Director's Notes 的 5 大部分结构 万字（10000-12000 字中文 / 等量英文）director's notes 必须包含这 5 大部分。**任一部分缺失都属于不完整，质量会受影响**。 ### Part I · Director's Statement（创作论，约 1500-2000 字） 回答 5 个问题： 1. **这部片不是什么？**（明确排除——如「这不是功能介绍片」「不是 demo」） 2. **核心 thesis 一行**——观众看完只记一句话是哪句？ 3. **跟谁的语境对话？**——列出 5-8 个视觉参照（导演 / 设计师 / 品牌 / 摄影师 / 作品名 + 年份），说明每个参照学了什么 4. **三类观众画像 + 对每类的承诺**：主受众 / 次受众 / 外受众，各对应一段 5. **节奏哲学**——慢拍 / 加速 / 顶峰 / 缓收的曲线说明 + emotional climax 在第几秒（**不一定是最后一秒**） 最后加一段 anti-slop checklist：**这部片不做的事**（具体列出，不模糊）。 ### Part II · Visual System（视觉系统全谱，约 1500-2500 字） 这是工程化的视觉 spec。完整后任何执行者拿到都能产出一致的视觉。 必含子节： - **完整色板**：至少 8-10 色，每色含 HEX + 功能定义 + 占画面比例上限 - **字体系统**：至少 6 个字号层级，每层级含字体名 + weight + size + letter-spacing + 用途 - **网格系统**：画布尺寸 + 外边距 + column grid + baseline grid + 关键安全区 + 黄金分割锚点 - **动画系统**：easing 库（4 条以内）+ duration 字典 + stagger 法则 + scene 过渡规则 - **Chrome 元素**：贯穿全片的小细节（counter / chip / ticker / watermark / texture），每个含位置 + 入退场时机 - **音频系统**：BGM 30 秒走向曲线（分层）+ SFX 字典（10+ cues 含时间码 + 音量 + 频段隔离） - **反 AI slop checklist**：per-shot 自检表（10-15 项） 铁律：**所有视觉决策都从 Visual System 推导，不要在 shot list 里临时发明新值**。 ### Part III · Story Arc（故事弧，约 500-800 字） 三幕结构 + 情绪曲线： - **Act I · SETUP**（0 → 第 1/5 时长，e.g. 0-6s for 30s）：观众进入，问题被提出 - **Act II · ESCALATION**（中间 2/3）：答案展开，主题铺陈 - **Act III · PAYOFF**（最后 1/4）：升华、slogan reveal、品牌印章 含 ASCII 情绪曲线图 + emotional climax 时刻标记。 **关键决策**：climax 不一定在末尾。30s 片子 climax 通常在 22-25s（不是 29s）——最后几秒是 resolution / decay，不是 peak。这条规则违反必然让作品「虎头蛇尾」。 ### Part IV · Shot-by-Shot Storyboard（分镜脚本，约 5000-7000 字 · 占 60% 篇幅） 每镜含 11 个字段（缺一不可）： ``` SHOT NN · NAME [TIMECODE] 起止时间 + 时长 [FUNCTION] 这一镜在故事弧中的功能（一句话） [VISUAL] 画面构图 + 元素位置 + 运动方向 [CAMERA] 景别（远/全/中/近/特，对应 zoom 档位）+ 运镜动作 + 一句动机；「静止」也要写为什么静止；push-in 必须写具象锚点（词汇与预算见 camera-language.md，景别体系见 storyboard-basics.md §3） [TYPE] 排版 spec（字体 / 字号 / 字距 / 行高 / 颜色 / 对齐） [ANIM] 每元素 in/out 时机 + easing + duration + stagger + delay [AUDIO] music beat + SFX cue（每镜对应 BGM 节奏 + 必含 SFX 时间表） [CHROME] 四角元素状态（哪些 chrome 在 / 哪些 fade in/out / 哪个 pulse） [ANTI-SLOP] 这一镜通过了哪些自检项 + 有什么 120% 细节签名 [WHY] 承接上一镜的逻辑 + 推进下一镜的钩子 ``` **字段平均 30-80 字 → 每镜 400-700 字 → 12-15 镜 → 5000-7000 字**。 实战经验：写完 storyboard 后**自己读一遍**——任意一镜删掉，整支片是否还成立？如果可以删，那镜就是多余的，删掉。 ### Part V · Production Manifest（制作清单，约 800-1200 字） 工程交付清单： - 字体加载 URL（含 preconnect） - CSS 变量（直接可粘贴） - BGM 来源选择标准 + Suno/Udio prompt 关键词 + 备选库 - SFX 字典（按时间码逐 cue 列出文件路径 + 音量） - **关键帧验证计划**：12-15 张 pause-and-check 关键帧时间码，每帧验证项列出（fonts / positions / chrome state） - 录制参数（fps / codec / bitrate / preset） - ffmpeg 音频混合命令（含 audio stream 验证） - 交付物清单（mp4 / mp4-60fps / gif / poster.png / silent.mp4 / shot-list.csv） - 全链路时间估算（小时级精度） --- ## 4. 写 director's notes 的 5 条建议 **4.1 用导演的口吻，不用 PM 的口吻** ❌「This shot displays the product features.」 ✅「This is the hero shot — if the audience pauses anywhere, I want it to be here.」 导演笔记是给执行者读的，但也是给未来的自己读的。第一人称 + judgment 表达比 description 表达留更多决策线索。 **4.2 引用具体作品（含年份），不只是流派名** ❌「Apple-inspired」 ✅「Apple 'Designed by Apple in California' (2013, dir. Mark Romanek) — 学的是慢拍 + 衬线 + 大白底」 引用具体作品的好处：(a) 任何观众都能上网搜到对照 (b) 你逼自己想清楚学的是什么具体技术 (c) 防止「灵感模糊」。 **4.3 每个决策都 trace 回 first principle** 整支片有一句 first principle（如 "Markdown is the new typewriter."）。每个具体决策——配色 / 字体 / 节奏 / chrome——都要能 trace 回这句话。 trace 不上的决策就是装饰，删掉。 **4.4 写 anti-slop 比写 do-this 更重要** 「这部片不做的事」清单（紫渐变 / emoji / Lorem ipsum / Inter display / SVG 画人物 / 圆角卡 + 左 border accent）比「这部片做的事」清单更能保护质量。 正向决策无穷多，负向 checklist 是有限的——但负向 checklist 一旦违反就是 slop。 **4.5 写完不要立即实施——隔 30 分钟再读一遍** 写作时大脑在「生产模式」，看不见 inconsistency。隔 30 分钟读自己写的 storyboard，会发现： - 某两镜功能重复（删一个） - 某镜叙事跳跃太大（加过渡） - emotional climax 位置错（移动） - chrome 元素和 shot 数量不匹配（重新对齐） 这 30 分钟省下的是后期 2 小时的返工。 --- ## 5. Director's Notes → HTML 实施流程 写完 director's notes 后，HTML 实施步骤： 1. **复用 starter components**（`assets/animations.jsx` 的 Stage/Sprite/Easing/interpolate）— 不重新发明 2. **CSS 变量直接从 Visual System Part II 粘贴** — 不在 HTML 里临时改色 3. **按 Sprite start/end 时间轴对照 Part IV 时间码** — 不擅自加镜 4. **chrome 元素抽成独立组件**（ChromeA/B/C/D），用 useTime() 驱动状态切换 5. **destination cards 内容必须真实可读**（不是 fake bar lines）—— 这是 v5 项目里最被反复提及的 120% 细节签名 6. **每写完一镜就立即截关键帧验证**（用 `?t=NN` URL 参数 + Playwright），不要写完全片再统一验证 --- ## 6. 关键帧验证流程 URL 参数实现（必须在 Stage 组件加）： ```js const urlMatch = window.location.search.match(/[?&]t=([\d.]+)/); const frozenTime = urlMatch ? parseFloat(urlMatch[1]) : null; const [time, setTime] = useState(frozenTime != null ? frozenTime : 0); const [playing, setPlaying] = useState(frozenTime == null); ``` → 这样 `file:///path/animation.html?t=14.5` 直接 freeze 在 14.5 秒。 批量截图： ```bash for t in 0.5 2.5 4.9 7.0 10.5 13.5 16.5 19.0 21.5 23.4 25.5 28.0 29.9; do npx -y playwright screenshot \ "file://$PWD/animation.html?t=$t" \ "keyframes/t-$t.png" \ --viewport-size=1920,1136 \ --wait-for-timeout=2500 done ``` 每张截图必须验证： - [ ] 元素无溢出 1920×1080 canvas - [ ] 字距、行高 visually correct（不挤、不散） - [ ] 关键 typography 细节（句点颜色 / em-dash / italic / small caps）可识别 - [ ] chrome 元素位置 + 状态正确 - [ ] 反 AI slop checklist 通过 - [ ] 「pause 时值得看」的 120% 细节存在 --- ## 7. 多视角并行策略（advanced） 复杂项目（如 launch film 选不出方向 / 想看多个美学差异 / 客户没拍板风格）可以**启动多个 subagent 并行做不同导演视角的版本**。 实战配置（2026-05-11 huashu-md-html 项目，并行 6 个版本）： ``` v5 · 基线（Anthropic / Penguin Classics 出版社品位） v5a · Wes Anderson（对称 + 复古 + 章节卡片） v5b · Saul Bass（剪纸 + 60s 大字 + 几何切割） v5c · 王家卫（中文衬线 + 慢动作 + 怀旧） v5d · Massimo Vignelli（现代主义 grid + 红黑） v5e · 原研哉 Kenya Hara（极简日式 + 留白） v5f · 草间彌生 Yayoi Kusama（圆点 + 重复 + 单一强色） ``` 每个 subagent 接到独立 brief： - 项目背景（同一份） - 必读参考（同一份 v5-director-notes.md 作为方法论模板） - **指定的艺术家 DNA**（色板 / 字体 / 视觉语言 / 节奏 / 招牌元素 / 反 slop 强化版本，每条 30-50 字） - 统一任务清单（director-notes.md + animation.html + keyframes/ + README.md） - 统一约束（30s / 1920×1080 / file:// / Google Fonts） 并行启动 + 后台运行，约 30-60 分钟出 6 套完整版本。 完成后审校对比： 1. 各版本核心美学决策表 2. 关键帧并排对比（每版同时刻一帧） 3. 投票：哪个最贴合用户的真实需求 **关键**：不要让 subagent 之间相互参考——它们必须独立产出，否则就会撞到「平均值」。每个 subagent 的指令里要明说「不要重复 v5 的美学」。 --- ## 8. 触发的几种典型场景 | 用户场景 | 是否触发 | 备注 | |---------|---------|------| | 「做个 SaaS 升级宣传片」 | ✅ 触发 | 默认走完整流程 | | 「Apple 级别 / 超级碗品质感的视频」 | ✅ 触发 + 升级 | 强力推荐多视角并行 | | 「30 秒品牌 launch film」 | ✅ 触发 | | | 「这个项目 1 万字脚本再做动画」 | ✅ 触发 | 用户明确指明 | | 「简单 motion graphic，logo 转一下」 | ❌ 不触发 | 用 animations.md 标准流程 | | 「做个 onboarding 动画 demo」 | ❌ 不触发 | 用 animations.md | | 「教程视频带配音」 | ❌ 不触发 | 走 voiceover-pipeline.md | | 「单个 hero animation」 | ⚠️ 看复杂度 | 如果是高规格 hero，触发；普通 hero 用 hero-animation-case-study.md | --- ## 9. 参考样本 完整 director's notes 参考样本（self-contained，本 skill 内）： `assets/director-notes-samples/launch-film-30s-sample.md`（约 78KB · 11500 字 · 13 镜 · 5 大部分齐全） 原始项目位置（含对应实施 HTML + 关键帧）： - v5-director-notes.md（director's notes，作者本地，未随仓库分发） - v5-six-forms.html（HTML 实施，作者本地，未随仓库分发） - v5-keyframes/（关键帧验证截图，作者本地，未随仓库分发） 写新项目时强烈建议**先 Read 这份样本**，理解工作量和细节密度，再决定要不要全套走流程。 --- ## 10. 反模式（不要这样做） ❌ **写 1000 字的精简版 director's notes 就动手** → 精简版必然漏 Visual System 的某个子项，导致 HTML 实施时不停回头补 spec。要做就做万字级，要省就直接跳过。 ❌ **storyboard 只写 5-8 镜** → 30 秒片至少 12-15 镜（每镜 2-3 秒）。镜少 = 节奏匀速 = 没 climax。 ❌ **director's notes 写完就交付，不做实施** → 文档不是交付物，动画才是。文档 + 动画一起交付，文档作为「设计依据」附录。 ❌ **多视角并行时让 subagent 看其他版本** → 各 subagent 必须独立，否则趋同。审校阶段才对比。 ❌ **跳过关键帧验证直接录 MP4** → 必然返工。关键帧验证是最便宜的 quality gate。 ❌ **把动画细节决策推迟到「等我录的时候再想」** → 录制阶段是机械执行，不能做创意决策。所有决策必须在 director's notes 写死。 --- *最后修订：2026-05-11* *真实案例：huashu-md-html v2.0 launch film（v5-director-notes.md）* -
multi-perspective-parallel-case-study.md 10.8 KB
# 多视角并行实验 · Case Study > huashu-md-html v2.0 launch film 项目 · 2026-05-11 > 6 位艺术家视角的并行 director's notes + HTML + 关键帧实验 --- ## 背景 用户要求「为 huashu-md-html v2.0 制作 30 秒升级宣传片」时，主线程先产出了 v5 基线（Anthropic / Penguin Classics 出版社品位）。但用户认为可以做得更好，给了 critical instruction： > 「调用不同的 subagent 分别再去生成 6 个全然不同的表达方式和视觉设计的版本。你可以试试启用不同的导演和艺术家。然后全都完成后，再评判审校。」 这是首次系统化的「多视角并行 director's notes」实验，验证了一套可复用的工作流。 --- ## 6 个视角的选择逻辑 不要随便选 6 个 designer——他们必须**视觉差异度极高**，避免趋同。 最终选择的 6 个视角（含选择理由）： | 视角 | 流派 | 美学锚点 | 跟其他视角的差异 | |------|------|---------|----------------| | **v5 基线** | 现代出版社 | Anthropic 赤陶橙 + Penguin Classics 衬线 + Vignelli grid | 安全的「品位」选择 | | **v5a Wes Anderson** | 电影章节美学 | The French Dispatch 杂志感 + 1960 Olivetti 工业目录 | 对称构图 + 章节卡片 + 装饰边框 | | **v5b Saul Bass** | 60s 影片标题艺术 | cut-paper + Trajan caps + 流动几何 | 剪纸 silhouette + 大字 + 强对角线 | | **v5c 王家卫** | 港式新浪潮 | 《花样年华》《2046》 letterboxing + 中文衬线 | 慢拍 + 雾化光晕 + 中文为主 | | **v5d Massimo Vignelli** | 1970 现代主义 | Knoll identity manual + NYC Subway map | 严格 grid + 3 色铁律 + 拒绝装饰 | | **v5e Kenya Hara** | 极简日式 | MUJI 海报 + 《白》 | 留白哲学 + 无 chrome + ma 间 | | **v5f Yayoi Kusama** | 装置艺术 | Infinity Mirror Rooms + Polka Dot Obsession | obsessive 重复 + 单一强色 + 圆点 | **选择原则**： 1. **3 个不同地理文化**（西方电影 / 日本设计 / 港式中文） 2. **3 个不同年代**（1960s / 1970s / 2010s+） 3. **3 个不同载体**（电影 / 平面设计 / 装置艺术） 4. **每个都有「跟训练语料里通用 SaaS 美学完全相反」的视觉签名** --- ## 实施流程 ### Step 1 · 为每个视角写独立 brief（约 15 分钟） 每个 brief 包含 8 个固定字段： ``` 1. 项目背景（同一份） 2. 必读参考（同一份 v5-director-notes.md 作方法论模板） 3. 你要做的事（4 项交付清单） 4. 该艺术家 DNA（核心字段 6 项）： - 色板（具体 HEX） - 字体（具体名字 + 替代方案） - 视觉语言（核心几条） - 招牌元素（identifiable signatures） - 节奏（区别其他视角） - 反 AI slop 强化版（在该风格语境下的禁区） 5. 30 秒结构参考（4-6 个 shot 草拟） 6. destination cards 设计要求（保持真实可读） 7. 关键约束（30s / 1920×1080 / file:// / Google Fonts CDN） 8. 输出验证清单 + 完成报告格式 ``` **关键**：每个 brief 必须强调「**不要重复 v5 的美学**」——否则 subagent 会被 v5 director-notes 影响而趋同。 ### Step 2 · 并行启动 6 个 subagent（同一 message 中 6 个 Agent tool calls） ```js Agent({ subagent_type: "general-purpose", run_in_background: true, name: "v5a-anderson", ... }) Agent({ subagent_type: "general-purpose", run_in_background: true, name: "v5b-bass", ... }) // ... 6 个 ``` 后台运行，预期 30-60 分钟。 ### Step 3 · 等待期间的 idle work 不要 polling agent 状态。subagent 完成会自动 task-notification。等待期间做： - 修主线程的 v5 基线 bug - 写 review framework（每个版本要打的分维度 / Q&A） - 沉淀方法论到 skill（这正是这份 case study 的来源） - 准备 final summary 文档骨架 ### Step 4 · 失败处理（约 16% 失败率，可接受） 实战观测：6 个 subagent 中约 1 个会因网络或 token 超限失败（Bass 首轮 socket error）。处理： 1. 收到 completion notification 时**立即检查**该 agent 的输出文件夹 2. 缺少关键交付物 → 重启该 agent（同样 brief，可标注「上次失败，请重新执行」） 3. 部分完成（如有 html 没截图）→ 主线程补 Playwright 截图，不重启 agent ### Step 5 · 6 版本完成后系统审校 审校 framework（5 维度 + 3 顶层问 + use case 分配）： ``` 5 维度评分（每维 1-10）： - Distinctiveness 视觉差异化 - Coherence 美学一致性 - Anti-slop 反 AI slop 执行 - Story arc 节奏与故事弧 - Pause-and-look 细节密度 3 顶层问： - Q1 截图分享？（能在社交平台触发暂停） - Q2 记一句话？（能留下命题级记忆） - Q3 跨时代？（5 年后回看不显廉价） use case 分配（按平台和受众）： - 公众号 / X / B 站 / 朋友圈 / Dribbble / 客户演示 / 私域 / ... ``` 详见 `assets/director-notes-samples/launch-film-30s-sample.md` 的同目录 REVIEW.md。 --- ## 实验产出（事实） ### 文档量 - v5 基线 director-notes：11500 字 - 6 视角 director-notes 各 4000-12000 字 - 总文档量：约 55000-70000 字 - 5 大部分结构齐全：6/6 版本 ### HTML 实施 - 每版独立 animation.html，30 秒，1920×1080 - 文件大小 28-74KB - 全部 file:// 可打开（不依赖 server） ### 关键帧 - 每版 10-18 张 PNG，覆盖完整 30 秒故事弧 - 总截图量：80+ 张 - 平均每张 PNG 大小：100-200KB ### 时长 - 6 个 subagent 并行运行：约 12-15 分钟（duration_ms 显示） - 主线程并行 idle work（修 v5 + 写方法论）：同期完成 - 整体「从启动 6 视角到所有 deliverable 到位」：约 60 分钟 --- ## 关键洞察（写给 huashu-design 的未来用户） ### 洞察 1 · 「先写万字 director's notes」方法论**完全 reproducible** 6 个 subagent 都按 5 大部分结构产出了 4000-12000 字的完整 spec，且实施 HTML 时都达到了 marketing-ready 质量。这证明方法论本身不依赖单一执行者的天赋——**只要 brief 给得清楚，多个独立执行者能产出一致的高质量结果**。 ### 洞察 2 · 「视角」必须具体到「作品 + 年份」 每个 brief 里都列出具体作品对话： - Anderson → *The French Dispatch* (2021) + *Moonrise Kingdom* (2012) + Penguin Classics dust jackets + 1960s Olivetti catalogues - WKW → *In the Mood for Love* (2000) + *2046* (2004) - Vignelli → 1972 NYC Subway map + Knoll identity manual + *The Vignelli Canon* - Hara → MUJI brand 1995-2023 + 《白》 + Junya Ishigami transparency - Kusama → Infinity Mirrored Rooms (2013-2023) + Polka Dot Obsession 装置 **实战结果**：所有 subagent 都准确捕捉到了该作品的核心 visual DNA，而不是流派的「平均值」。 ### 洞察 3 · 反 AI slop 的「风格强化版本」是关键 通用 anti-slop（紫渐变 / emoji / SVG 人物）适用所有版本。但**每个风格还要写「专属 anti-slop」**： - Bass: 不用 Helvetica（太干净，Bass 是粗犷） - Vignelli: 不用圆角（所有 corner 90°） - Hara: 不用任何渐变 + 不用 sans display - Kusama: 不用现代 SaaS look - Anderson: 不用 cyber 配色 - WKW: 不用 Inter（WKW 用衬线） 加了这些后，6 个版本风格纯度极高，无一相互趋同。 ### 洞察 4 · 多视角的真正价值不是「选 winner」 最初设想是 A/B test 选最好的版本。实际审校时发现：**6 个版本各自有清晰 use case**： - v5 基线 → 产品页 / 微信读书（信息密度高） - Anderson → 公众号长文头图（翻杂志感强） - WKW → B 站 / 中文文化向（怀旧温度） - Vignelli → 设计圈 / Dribbble（每帧都是印刷海报） - Hara → 客户演示 / 静态截图（极简哲学） - Kusama → X 短视频 / 病毒传播（视觉冲击） **结论**：marketing 不是 single-shot，是 platform-specific multiplex。6 视角并行的真正价值是**让一个项目有 6 个差异化武器**，不是让 5 个版本上不了台面。 ### 洞察 5 · subagent 的失败率 ~16% 是可接受的 6 个里 1 个失败（Bass 首轮 socket error）。处理代价：重启 + 5 分钟简化版 brief，再等 12-15 分钟。**对比 vs. 等 1 个 agent 顺序跑 6 个版本（90+ 分钟）**——并行 + 重试明显更经济。 ### 洞察 6 · 主线程在等待期间必须做 substantive idle work subagent 完成需要 12-15 分钟。这段时间主线程绝不该空闲： - **修主版本 bug**（用户已经反馈的） - **写 review framework**（等审校时填） - **沉淀方法论到 skill**（如这份 case study） - **准备 final summary**（用户回来一目了然） 这是 parallel multi-agent workflow 的「主线程职责」——不是 PM 等结果，是 orchestrator 同步推进。 --- ## 何时启用「多视角并行」 | 场景 | 是否启用 | 原因 | |------|---------|------| | 用户明确说「想看不同方向」「再多做几个版本」 | ✅ 立刻启用 | 直接需求 | | 第一版做出来用户不满意但说不清要啥 | ✅ 启用 | A/B 选优于「我猜你要啥」 | | 项目准备多平台分发（X / 公众号 / B 站 / 朋友圈） | ✅ 启用 | 每平台一个版本 | | 客户没拍板风格但有预算（time + token） | ✅ 启用 | 反复改 = 5 倍代价 | | 用户已经给了明确风格参考且只要 1 个版本 | ❌ 不启用 | 浪费 | | 任务是简单 motion graphic / icon 动画 | ❌ 不启用 | 过度工程化 | | 时间紧 < 30 分钟 | ❌ 不启用 | subagent 跑不完 | --- ## 完整方法论流程图 ``` 用户 brief（含质量预期） ↓ [主线程] 写 v5 基线 director's notes（万字级 5 大部分） ↓ [主线程] 实施 v5 HTML + 截关键帧（marketing baseline） ↓ [决策点] 是否启用多视角？ ↓ YES [主线程] 选 6 个差异化视角 + 写 6 份独立 brief（每份 8 字段） ↓ [6 subagents 并行] ├── v5a brief → director-notes + html + keyframes + README ├── v5b brief → ... ├── v5c brief → ... ├── v5d brief → ... ├── v5e brief → ... └── v5f brief → ... ↓ [主线程同步做] 修 v5 bug · 写 review framework · 沉淀方法论 ↓ [全 6 通知到达] ↓ [主线程] 失败检测 + 重试 / 补截图 ↓ [主线程] 5 维度评分 + 3 顶层问 + use case 分配 ↓ [主线程] 写 final REVIEW.md ↓ [交付] 6 完整版本 + review + 平台分发推荐 ``` --- ## 相关文档 - 完整方法论：`references/launch-film-director-notes.md` - 单视角样本：`assets/director-notes-samples/launch-film-30s-sample.md`（v5 基线） - 实战项目位置：作者本地 demos 目录（含 6 + 1 视角全套文件，未随仓库分发） - 审校 review：作者本地 REVIEW.md（未随仓库分发） --- *Last updated: 2026-05-11* *Real case study: huashu-md-html v2.0 launch film 6-perspective parallel experiment* -
pptx-from-rendered-html.md 9.3 KB
# 视觉稿 HTML → 可编辑 PPTX：读渲染结果，不改 HTML `references/editable-pptx.md` 讲的是 **html2pptx 那条路**：HTML 从第一行就按 4 条硬约束写， 写完才转得动。那份文档里有一句结论——「**绝不要在视觉自由写好的 HTML 上硬跑 html2pptx**， 实测 pass 率 < 30%」，并给出两个 fallback：出 PDF，或者重写一版 editable HTML。 **这份文档讲第三条路，它把那个 fallback 变成了不必要。** 核心差别一句话：**html2pptx 读的是源码，本脚本读的是浏览器渲染完之后的坐标。** flex、居中、自动换行，浏览器都已经算成绝对位置了，所以「div 里有裸文字」「用了 flex」 「p 上有背景」这些写法根本不构成问题——它们在 `getBoundingClientRect` 眼里都只是一个矩形。 --- ## 先选路：三选一 | 情况 | 走哪条 | 为什么 | |---|---|---| | **HTML 还没写**，你从头做 deck | `scripts/html2pptx.js`（见 `editable-pptx.md`） | 按 4 条约束写出来的 PPTX 结构最干净，文本框合并、段落层级都更适合后续编辑 | | **HTML 已经写好**，是视觉驱动的（flex / 居中 / 裸文字 / 背景图 / SVG 图表） | **`scripts/pptx_from_rendered.py`（本文）** | 零改造直接转。重写 20 页 HTML 去迁就约束，成本远高于直接量 | | **甲方要求「必须用我们的模板」** | **只能走本文这条** | pptxgenjs 从零创建文件，无法以现有 pptx 为基底继承母版；python-pptx 可以 | ⚠️ **不要在同一个项目里混用两条路。** 选定一条走到底，否则两套坐标体系会打架。 --- ## 用法 ```bash python3 scripts/pptx_from_rendered.py deck.html -o deck.pptx --selector ".slide" ``` 继承甲方官方模板时（最常见的商单场景）： ```bash python3 scripts/pptx_from_rendered.py deck.html -o deck.pptx \ --selector ".slide" \ --template 客户官方模板.pptx \ --layout "内页" \ --skip-class logo \ --bg 05070B ``` 依赖：`playwright`（含 chromium）、`python-pptx`、`Pillow`。 加 `--dump-json dom.json` 可以把量到的元素清单落盘，排查位置问题时很有用。 --- ## 继承甲方模板：让他们改母版能整体生效 商单里最常见的返工理由不是「不好看」，是「**你没用我们的模板**」。 甲方说这句话时，他要的通常是两件具体的事：① logo 是最新版； ② **他改母版的时候，你这些页要跟着变**。 每页一张整幅图的 PPT 两件都做不到；即使做成文本框，用 pptxgenjs 从零建的文件 也没有他们的母版。做法是拿他们的 `.pptx` 当基底： 1. `Presentation(客户模板.pptx)` 打开 2. **删掉模板自带的示例页**，母版 / 版式 / 主题 / 色板一个不动（`strip_slides`） 3. 每页 `add_slide(官方版式)`，并把版式带来的空占位符从页面上删掉 4. **logo 之类的公共元素不要画进内容层**——让版式去提供。渲染时用 `--skip-class logo` 把 HTML 里那个 logo 跳过，页面上就只剩你的内容，logo 由版式给。 这样甲方改母版/版式，全部页面整体跟着变。 ⚠️ **坑：版式里可能藏着一个铺满全屏的纯色矩形**，和版式底色同色同尺寸（冗余遮罩）。 留着它，页面上任何放在它下面的东西都会被挡住。脚本的 `unblock_layout` 会删掉它， 删掉不改变版式的外观。 **画布尺寸跟模板走，别跟 `editable-pptx.md` 的 960×540pt 走。** 甲方模板是多大就多大 （实测遇到过 26.67×15 inch），尺寸不一致的话合并文件时会被整体缩放。脚本会自动按 `幻灯片宽pt ÷ HTML画布宽px` 算缩放比；HTML 画布 1920px 配 1920pt 时这个比正好是 1.0， **1 CSS px = 1 PowerPoint pt**，心算都不用。 --- ## 六个排版陷阱（每一个都出过事） 这些都是 `editable-pptx.md` 没有覆盖的，因为它假设 HTML 是按约束新写的。 读渲染结果时，下面每一条不处理都会直接翻车： ### 1. HTML 源码的换行缩进，会变成 PPTX 里的真换行 ```html <div> <em>68</em> <span>个项目，我装了每天的数据采集</span> </div> ``` 标签之间的换行和缩进是**真实的文本节点**。浏览器按 `white-space:normal` 把它折叠掉 （连续空白→一个空格，行首行尾丢弃），PPTX 没有这套规则——那个 `\n` 原样搬过去， 在 PowerPoint 里就是一个真换行，把后面整段推到下一行去压住别的元素。 **修法**：在提取时就做 HTML 的空白折叠，并丢弃折叠后为空的 run。 ### 2. 容器的 font-size 往往是继承来的，不能拿它算余量和行距 上面那个 div 的 `computedStyle.fontSize` 可能只有 16px（从 body 继承）， 里面却是 132px 的数字。拿 16px 去算文本框余量、行距，全是错的。 **修法**：基准字号取 `runs` 里的**最大**字号。 ### 3. 数行数不能拿矩形的 top 去重 `Range.getClientRects()` 对同一行里字号不同的 run 会返回多个矩形——它们基线对齐， 但顶边差一大截。按 `top` 去重，一行会被数成好几行（实测一行被数成 4 行）。 **修法**：按 y 区间是否重叠来聚类。 ### 4. 一个框里多段不同字号，不能套同一个行距 PowerPoint 的行距是**段落级**的，而视觉稿经常把不同字号的行放进同一个 div： ```html <div>我投入最多的那个<br>做了一周多，四万行代码<br><em class="big">没跑出来</em></div> ``` 整框套一个行距，小字那几行被撑开、大字那行被压，实测相邻两行会直接叠在一起。 **修法**：**按 `<br>` 分段，每段单独成一个文本框**，各用各的位置和行高。 文本框数量会变多（实测 137 → 175），但这是正确性的必要代价。 ### 5. flex 收缩包裹的框零余量，最后一个字会掉行 `align-items:center` 的 flex 子元素宽度收缩到文字实际宽度，**一点余量都没有**。 换到 PowerPoint 只要字体度量差一点点，最后一个字就被挤到下一行 （实测「⋯⋯被用起来了」的「了」、「稀缺的是判断力」的「力」都掉过）。 **修法**：量出这一段在 HTML 里到底折没折行；本来就是单行的，在 PPT 里**直接关掉自动换行** （`word_wrap = False`），从根上不可能折行。实测 175 个框里有 150 个属于这类。 ### 6. 单行段落不要设精确行距 量到的行盒高度比实际行间距大（那是**字体行盒**，不是 CSS 行距；实测 185 vs 148）。 拿它当 exact line spacing，会把文字整体压下去。 **修法**：只给「自己折了行」的段落设行距；单行段落交给 PowerPoint 按字号自然排， 文字紧贴框顶，位置反而最准。 --- ## 🔴 验证：先验证你的验证工具 **这是这条路最大的教训，价值高于上面所有技术细节。** 同一个 PPTX，不同渲染器给出的结果可以完全不同。用错工具，上面 1、3、4、6 号坑 **一个都不会暴露**——20 页看起来全对，甲方一打开就是重叠的。 | 工具 | 能不能信 | 说明 | |---|---|---| | **macOS `qlmanage -t` 缩略图** | ❌ **不能** | 走的是简化渲染路径，对行距比真 PowerPoint 宽容得多。实测它放过了 4 个会导致文字重叠的 bug | | **LibreOffice（macOS）** | ⚠️ 版面可信，中文可能全丢 | 它取不到 macOS 的系统中文字体，渲出来是豆腐块甚至空白 | | **Keynote + AppleScript** | ✅ **可自动化的首选** | 真正的演示引擎排版；能脚本化导 PDF 再逐页出图 | | **WPS / PowerPoint 打开** | ✅ **最终确认** | 甲方多半用这一类。人工看 | **Keynote 自动化（本机唯一能全自动又可信的路子）**： ```bash osascript <<'EOF' tell application "Keynote" activate set d to open POSIX file "/abs/path/deck.pptx" delay 4 export d to POSIX file "/abs/path/out.pdf" as PDF close d saving no quit end tell EOF pdftoppm -png -r 54 out.pdf page # 再逐页和 HTML 原版并排比对 ``` **判断渲染器可不可信，用对照实验**：把**甲方模板原件**丢给同一个渲染器。 如果它渲染官方模板时中文也全丢，那是环境问题不是你的文件问题——这一步能省掉 几小时在错误方向上的排查。 ⚠️ **不要用 System Events 注入按键去翻页截图。** 键会打到用户当前正在输入的窗口里去。 **另外跑一遍机械校验**（不依赖任何渲染器）： - 文字逐字比对：从 `--dump-json` 的清单和生成的 pptx 各抽一份文字，`re.sub(r'\s+','')` 后必须完全相等 - 数量比对：图片数、形状数逐页对齐 --- ## 字体：交付字体 ≠ 排版字体 甲方规范常指定一个你本机没有的字体（例如微软雅黑，那是随 Windows 授权分发的商业字体）。 **不要为了它把 HTML 的 `font-family` 也改掉**——本机没装，预览和 PDF 会 fallback， **排版当场就跑掉**（实测整行数字被挤到下一行）。 正确做法是**两边分开**： - HTML / PDF 用本机真实装着的字体排版，所见即所得 - PPTX 里写甲方规范指定的字体名（他们的机器上有） **能分开的前提是中文全角等宽**——换字体不改变每行的字数和换行位置，差异只在西文和标点。 中文为主的稿子可以放心分开；西文为主的稿子要另行验证。 -
react-setup.md 9.5 KB
# React + Babel 项目规范 用HTML+React+Babel做原型时必须遵守的技术规范。不遵守会炸。 ## Pinned Script Tags（必须用这些版本） 在HTML的`<head>`里放这三个script tag，用**固定版本+integrity hash**： ```html <script src="https://unpkg.com/react@18.3.1/umd/react.development.js" integrity="sha384-hD6/rw4ppMLGNu3tX5cjIb+uRZ7UkRJ6BPkLpg4hAu/6onKUg4lLsHAs9EBPT82L" crossorigin="anonymous"></script> <script src="https://unpkg.com/react-dom@18.3.1/umd/react-dom.development.js" integrity="sha384-u6aeetuaXnQ38mYT8rp6sbXaQe3NL9t+IBXmnYxwkUI2Hw4bsp2Wvmx4yRQF1uAm" crossorigin="anonymous"></script> <script src="https://unpkg.com/@babel/standalone@7.29.0/babel.min.js" integrity="sha384-m08KidiNqLdpJqLq95G/LEi8Qvjl/xUYll3QILypMoQ65QorJ9Lvtp2RXYGBFj1y" crossorigin="anonymous"></script> ``` **不要**用`react@18`或`react@latest`这种unpinned版本——会出现版本漂移/缓存问题。 **不要**省略`integrity`——CDN一旦被劫持或篡改，这是防线。 ## 文件结构 ``` 项目名/ ├── index.html # 主HTML ├── components.jsx # 组件文件（type="text/babel"加载） ├── data.js # 数据文件 └── styles.css # 额外CSS（可选） ``` HTML里加载方式： ```html <!-- 先React+Babel --> <script src="https://unpkg.com/react@18.3.1/..."></script> <script src="https://unpkg.com/react-dom@18.3.1/..."></script> <script src="https://unpkg.com/@babel/standalone@7.29.0/..."></script> <!-- 然后你的组件文件 --> <script type="text/babel" src="components.jsx"></script> <script type="text/babel" src="pages.jsx"></script> <!-- 最后主入口 --> <script type="text/babel"> const root = ReactDOM.createRoot(document.getElementById('root')); root.render(<App />); </script> ``` **不要**用`type="module"`——会和Babel冲突。 ## 三条不可违反的规矩 ### 规矩1：styles 对象必须用唯一命名 **错误**（多组件时必炸）： ```jsx // components.jsx const styles = { button: {...}, card: {...} }; // pages.jsx ← 同名覆盖！ const styles = { container: {...}, header: {...} }; ``` **正确**：每个组件文件的styles用唯一前缀。 ```jsx // terminal.jsx const terminalStyles = { screen: {...}, line: {...} }; // sidebar.jsx const sidebarStyles = { container: {...}, item: {...} }; ``` **或者用inline styles**（小组件推荐）： ```jsx <div style={{ padding: 16, background: '#111' }}>...</div> ``` 这条是**非协商**的。每次写`const styles = {...}`都必须replace成specific命名，否则多组件加载时全栈报错。 ### 规矩2：Scope 不共享，需手动export **关键认知**：每个`<script type="text/babel">`被Babel独立编译，它们之间**scope不通**。`components.jsx`里定义的`Terminal`组件，在`pages.jsx`里**默认是undefined**。 **解决方式**：在每个组件文件末尾，把要共享的组件/工具export到`window`： ```jsx // components.jsx 末尾 function Terminal(props) { ... } function Line(props) { ... } const colors = { green: '#...', red: '#...' }; Object.assign(window, { Terminal, Line, colors, // 所有你要在别处用的都列在这里 }); ``` 然后`pages.jsx`就能直接用`<Terminal />`，因为JSX会去`window.Terminal`找。 ### 规矩3：不要用 scrollIntoView `scrollIntoView`会把整个HTML容器往上推，搞坏web harness的布局。**永远不要用**。 替代方案： ```js // 滚到容器内某个位置 container.scrollTop = targetElement.offsetTop; // 或者用element.scrollTo container.scrollTo({ top: targetElement.offsetTop - 100, behavior: 'smooth' }); ``` ## 调 Claude API（HTML内） 部分原生 design-agent 环境（如 Claude.ai Artifacts）有免配置的 `window.claude.complete`，但大部分 agent 环境（Claude Code / Codex / Cursor / Trae / etc.）本地里**没有**。 如果你的 HTML 原型需要调用 LLM 做 demo（比如做个聊天 interface），两个选项： ### 选项A：不真调，用mock Demo场景推荐。写一个假helper，返回预设的response： ```jsx window.claude = { async complete(prompt) { await new Promise(r => setTimeout(r, 800)); // 模拟延迟 return "这是一个mock响应。真部署时请替换为真API。"; } }; ``` ### 选项B：真调Anthropic API（不推荐，仅限本地演示） 需要API key，用户必须在HTML里填入自己的key才能跑。**永远不要把key硬编码在HTML里**。 ⚠️ 安全边界：这个方案只适合本地`file://`打开、用完即关的演示。key会留在DOM/内存里—— **不要部署这个页面、不要带着填了key的页面截图/录屏传播**。生产场景一律走本地proxy后端转发， 浏览器端不碰key。默认优先选项A/C（完全不需要key）。 ```html <input id="api-key" placeholder="粘贴你的Anthropic API key" /> <script> window.claude = { async complete(prompt) { const key = document.getElementById('api-key').value; const res = await fetch('https://api.anthropic.com/v1/messages', { method: 'POST', headers: { 'x-api-key': key, 'anthropic-version': '2023-06-01', 'content-type': 'application/json', }, body: JSON.stringify({ model: 'claude-haiku-4-5', max_tokens: 1024, messages: [{ role: 'user', content: prompt }] }) }); const data = await res.json(); return data.content[0].text; } }; </script> ``` **注意**：浏览器直接调Anthropic API会遇到CORS问题。如果用户给你的预览环境不支持CORS bypass，这条路不通。这时候用选项A mock，或者告诉用户需要一个proxy后端。 ### 选项 C：用 agent 侧的 LLM 能力生成 mock 数据 如果只是本地演示用，可以在当前 agent 会话里临时调用该 agent 的 LLM 能力（或用户装的 multi-model 类 skill）先生成 mock 响应数据，再硬编码写进 HTML。这样 HTML 运行时完全不依赖任何 API。 ## 典型 HTML 起手模板 拷贝这个模板作为React原型的骨架： ```html <!DOCTYPE html> <html lang="zh-CN"> <head> <meta charset="UTF-8"> <meta name="viewport" content="width=device-width, initial-scale=1.0"> <title>Your Prototype Name</title> <!-- React + Babel pinned --> <script src="https://unpkg.com/react@18.3.1/umd/react.development.js" integrity="sha384-hD6/rw4ppMLGNu3tX5cjIb+uRZ7UkRJ6BPkLpg4hAu/6onKUg4lLsHAs9EBPT82L" crossorigin="anonymous"></script> <script src="https://unpkg.com/react-dom@18.3.1/umd/react-dom.development.js" integrity="sha384-u6aeetuaXnQ38mYT8rp6sbXaQe3NL9t+IBXmnYxwkUI2Hw4bsp2Wvmx4yRQF1uAm" crossorigin="anonymous"></script> <script src="https://unpkg.com/@babel/standalone@7.29.0/babel.min.js" integrity="sha384-m08KidiNqLdpJqLq95G/LEi8Qvjl/xUYll3QILypMoQ65QorJ9Lvtp2RXYGBFj1y" crossorigin="anonymous"></script> <style> * { box-sizing: border-box; margin: 0; padding: 0; } html, body { height: 100%; width: 100%; } body { font-family: -apple-system, 'SF Pro Text', sans-serif; background: #FAFAFA; color: #1A1A1A; } #root { min-height: 100vh; } </style> </head> <body> <div id="root"></div> <!-- 你的组件文件 --> <script type="text/babel" src="components.jsx"></script> <!-- 主入口 --> <script type="text/babel"> const { useState, useEffect } = React; function App() { return ( <div style={{padding: 40}}> <h1>Hello</h1> </div> ); } const root = ReactDOM.createRoot(document.getElementById('root')); root.render(<App />); </script> </body> </html> ``` ## 常见报错及解决 **`styles is not defined` 或 `Cannot read property 'button' of undefined`** → 你在一个文件里定义了`const styles`，另一个文件覆盖了。给每个改成specific命名。 **`Terminal is not defined`** → 跨文件引用时scope不通。在定义Terminal的文件末尾加`Object.assign(window, {Terminal})`。 **整个页面白屏，控制台没错误** → 多半是JSX语法错误但Babel没报在控制台。把`babel.min.js`临时换成`babel.js`非压缩版，错误信息更清晰。 **ReactDOM.createRoot is not a function** → 版本不对。确认用了react-dom@18.3.1（而不是17或其他）。 **`Objects are not valid as a React child`** → 你渲染了一个对象而不是JSX/字符串。通常是`{someObj}`写成了`{someObj.name}`。 ## 大项目怎么拆文件 **>1000行的单文件**难维护。分拆思路： ``` 项目/ ├── index.html ├── src/ │ ├── primitives.jsx # 基础元素：Button、Card、Badge... │ ├── components.jsx # 业务组件：UserCard、PostList... │ ├── pages/ │ │ ├── home.jsx # 首页 │ │ ├── detail.jsx # 详情页 │ │ └── settings.jsx # 设置页 │ ├── router.jsx # 简单路由（React state切换） │ └── app.jsx # 入口组件 └── data.js # mock data ``` HTML里按顺序加载： ```html <script type="text/babel" src="src/primitives.jsx"></script> <script type="text/babel" src="src/components.jsx"></script> <script type="text/babel" src="src/pages/home.jsx"></script> <script type="text/babel" src="src/pages/detail.jsx"></script> <script type="text/babel" src="src/pages/settings.jsx"></script> <script type="text/babel" src="src/router.jsx"></script> <script type="text/babel" src="src/app.jsx"></script> ``` **每个文件末尾**都要`Object.assign(window, {...})`导出要共享的东西。 -
scene-templates.md 7 KB
# 场景模板库：按输出类型组织 > 与 design-styles.md 的「提示词DNA」组合使用。 > 公式：`[风格提示词DNA] + [场景模板] + [具体内容描述]` --- ## 1. 公众号封面 / 文章题图 **规格**： - 封面图：2.35:1（900×383px 或 1200×510px） - 正文插图：16:9（1200×675px）或 4:3（1200×900px） **关键设计要素**： - 视觉冲击力优先（用户在信息流中快速扫过） - 文字极少或无文字（公众号标题会覆盖在上面） - 色彩饱和度适中（微信阅读环境偏白） - 避免过度细节（缩略图也要可辨识） **推荐风格**：01 Pentagram / 11 Build / 12 Sagmeister / 18 Kenya Hara / 07 Field.io **场景提示词模板**： ``` [风格DNA插入此处] - Article cover image for WeChat subscription - Landscape format, 2.35:1 aspect ratio - Bold visual impact, minimal or no text - Moderate color saturation for white reading environment - Must remain recognizable as thumbnail - Clean composition with clear focal point ``` --- ## 2. 正文配图 / 概念插画 **规格**： - 16:9（1200×675px）最通用 - 1:1（800×800px）适合强调 - 4:3（1200×900px）适合信息密集 **关键设计要素**： - 服务于文章论点，不是装饰 - 与上下文形成视觉节奏 - 简洁表达一个核心概念 - AI生成优先，HTML截图仅在精确数据表格时用 **推荐风格**：根据文章调性选择，常用 01/04/10/17/18 **场景提示词模板**： ``` [风格DNA插入此处] - Article illustration, concept visualization - [16:9 / 1:1 / 4:3] aspect ratio - Single clear concept: [描述核心概念] - Serve the argument, not decoration - [Light/Dark] background to match article tone ``` --- ## 3. 信息图 / 数据可视化 **规格**： - 竖版长图：1080×1920px（手机阅读） - 横版：1920×1080px（文章内嵌） - 方形：1080×1080px（社交媒体） **关键设计要素**： - 信息层级清晰（标题 → 核心数据 → 细节） - 数据准确，不编造 - 视觉引导线（用户阅读路径） - 适当使用图标/图表辅助理解 **推荐风格**：04 Fathom / 10 Müller-Brockmann / 02 Stamen / 17 Takram **场景提示词模板**： ``` [风格DNA插入此处] - Infographic / data visualization - [Vertical 1080x1920 / Horizontal 1920x1080 / Square 1080x1080] - Clear information hierarchy: title → key data → details - Visual flow guiding reader's eye path - Icons and charts for comprehension - Data-accurate, no decorative distortion ``` --- ## 4. PPT / Keynote 演示 **规格**： - 标准：16:9（1920×1080px） - 宽屏：16:10（1920×1200px） **关键设计要素**： - 每页一个核心信息（不堆砌） - 字号层级明确（标题40pt+ / 正文24pt+ / 注释16pt+） - 大量留白，投影时更清晰 - 图文比例至少 60:40 - 一致的视觉系统（颜色、字体、间距） **推荐风格**：01 Pentagram / 10 Müller-Brockmann / 11 Build / 18 Kenya Hara / 04 Fathom **场景提示词模板**： ``` [风格DNA插入此处] - Presentation slide design, 16:9 - One core message per slide - Clear type hierarchy (title 40pt+, body 24pt+) - Generous whitespace for projection clarity - Consistent visual system throughout - [Light/Dark] theme ``` --- ## 5. PDF 白皮书 / 技术报告 **规格**： - A4 纵向（210×297mm / 595×842pt） - Letter 纵向（216×279mm / 612×792pt） **关键设计要素**： - 长文阅读优化（行宽66字符、行高1.5-1.8） - 清晰的章节导航系统 - 页眉/页脚/页码的统一设计 - 图表与正文的优雅共存 - 引用/注释系统 - 封面页设计精致 **推荐风格**：10 Müller-Brockmann / 04 Fathom / 03 Information Architects / 17 Takram / 19 Irma Boom **场景提示词模板**： ``` [风格DNA插入此处] - PDF document / white paper design - A4 portrait format (210×297mm) - Long-form reading optimized (66 char line width, 1.5 line height) - Clear chapter navigation system - Elegant header/footer/page number design - Charts integrated with body text - Professional cover page ``` --- ## 6. 落地页 / 产品官网 **规格**： - Desktop: 1440px 宽度设计（响应至320px） - 首屏高度：100vh **关键设计要素**： - 首屏5秒内传达核心价值 - 清晰的CTA（行动按钮） - 滚动叙事结构（问题→方案→证明→行动） - 移动端适配 - 加载速度 **推荐风格**：05 Locomotive / 01 Pentagram / 11 Build / 08 Resn / 06 Active Theory **场景提示词模板**： ``` [风格DNA插入此处] - Landing page / product website - Desktop 1440px width, responsive - Hero section 100vh, core value in 5 seconds - Clear CTA button design - Scroll narrative: problem → solution → proof → action - Modern web aesthetic ``` --- ## 7. App UI / 原型界面 **规格**： - iOS: 390×844pt（iPhone 15） - Android: 360×800dp - 平板: 1024×1366pt（iPad Pro） **关键设计要素**： - 触摸友好（最小点击区44×44pt） - 系统设计语言一致性 - 状态栏/导航栏/Tab栏的标准处理 - 信息密度适中（移动端不宜过密） **推荐风格**：17 Takram / 11 Build / 03 Information Architects / 01 Pentagram **场景提示词模板**： ``` [风格DNA插入此处] - Mobile app UI design - iOS [390×844pt] / Android [360×800dp] - Touch-friendly (44pt minimum tap targets) - Consistent design system - Standard status bar / navigation / tab bar - Moderate information density ``` --- ## 8. 小红书配图 **规格**： - 竖版：3:4（1080×1440px）最佳 - 方形：1:1（1080×1080px） - 首图决定点击率 **关键设计要素**： - 视觉吸引力第一（在瀑布流中竞争） - 可以有少量文字（但不超过画面20%） - 色彩鲜明但不俗 - 生活感/质感/氛围感 **推荐风格**：12 Sagmeister / 11 Build / 20 Neo Shen / 09 Experimental Jetset **场景提示词模板**： ``` [风格DNA插入此处] - Social media image for Xiaohongshu (RED) - Vertical 3:4 (1080×1440px) - Eye-catching in waterfall feed - Minimal text overlay (under 20% of area) - Vivid but tasteful colors - Lifestyle/texture/atmosphere feel ``` --- ## 组合示例 **场景**：公众号封面，介绍一款AI编程工具，想要专业但有温度 **Step 1**：选风格 → 17 Takram（专业+温度） **Step 2**：取Takram提示词DNA + 公众号封面模板 ``` Takram Japanese speculative design: - Elegant concept prototypes and diagrams - Soft tech aesthetic (rounded corners, gentle shadows) - Charts and diagrams as art pieces - Modest sophistication - Neutral natural colors (beige, soft gray, muted green) - Design as philosophical inquiry Article cover image for WeChat subscription - Landscape format, 2.35:1 aspect ratio (1200×510px) - Bold visual impact, minimal text - Moderate color saturation for white reading environment - Must remain recognizable as thumbnail - Clean composition with clear focal point Content: An AI coding assistant tool, showing the concept of human-AI collaboration in software development, warm and professional atmosphere ``` --- **版本**：v1.0 **更新日期**：2026-02-13 -
sfx-library.md 9.5 KB
# SFX Library · huashu-design > 全部由 ElevenLabs Sound Generation API 生成，苹果发布会级音质。 > 产品级 SFX 资产库，覆盖花叔动画/演示/产品 Demo 全场景。 **资产位置**：`assets/sfx/<category>/<name>.mp3` **总数**：37 个 SFX（30 批量生成 + 7 个 v7b 保留） **生成模型**：ElevenLabs Sound Generation API（prompt_influence 0.4） **音质**：44.1kHz MP3，苹果发布会级清晰度，无额外混响 --- ## 目录结构 ``` assets/sfx/ ├── keyboard/ type, type-fast, delete-key, space-tap, enter ├── ui/ click, click-soft, focus, hover-subtle, tap-finger, toggle-on ├── transition/ whoosh, whoosh-fast, swipe-horizontal, slide-in, dissolve ├── container/ card-snap, card-flip, stack-collapse, modal-open ├── feedback/ success-chime, error-tone, notification-pop, achievement ├── progress/ loading-tick, complete-done, generate-start ├── impact/ logo-reveal, logo-reveal-v2, brand-stamp, drop-thud ├── magic/ sparkle, ai-process, transform └── terminal/ command-execute, output-appear, cursor-blink ``` --- ## 快速索引 ### ⌨️ Keyboard（键盘输入） | 文件 | 时长 | 用途 | Prompt 要点 | |---|---|---|---| | `sfx/keyboard/type.mp3` | 0.5s | 单键敲击（mechanical keyboard single key） | mechanical keyboard single key press | | `sfx/keyboard/type-fast.mp3` | 1.5s | 连续快速打字（演示输入提示词） | fast continuous typing rhythm, apple magic keyboard | | `sfx/keyboard/delete-key.mp3` | 0.5s | backspace 回删 | single backspace key, low pitched thud | | `sfx/keyboard/space-tap.mp3` | 0.5s | 空格键轻击 | soft spacebar tap, wide flat | | `sfx/keyboard/enter.mp3` | 0.5s | 回车确认（v7b 保留） | enter key press, crisp tactile | ### 🎯 UI（界面交互） | 文件 | 时长 | 用途 | Prompt 要点 | |---|---|---|---| | `sfx/ui/click.mp3` | 0.5s | 标准 UI 点击（v7b 保留） | crisp modern interface click | | `sfx/ui/click-soft.mp3` | 0.5s | 柔和 UI click（次要按钮/链接） | soft gentle button click, mid pitched | | `sfx/ui/focus.mp3` | 0.5s | 元素聚焦/选中（v7b 保留） | subtle focus tone, element highlight | | `sfx/ui/hover-subtle.mp3` | 0.5s | 悬停提示（微秒级反馈） | barely audible tick, air whisper | | `sfx/ui/tap-finger.mp3` | 0.5s | 移动端 tap（iOS 界面） | finger tap on touchscreen, muted thud | | `sfx/ui/toggle-on.mp3` | 0.5s | 开关打开 | ios toggle switch flip, satisfying click | ### 🌊 Transition（过渡） | 文件 | 时长 | 用途 | Prompt 要点 | |---|---|---|---| | `sfx/transition/whoosh.mp3` | 0.5s | 标准 whoosh（v7b 保留） | air whoosh transition | | `sfx/transition/whoosh-fast.mp3` | 0.6s | 快速 whoosh（标题闪入、标签切换） | quick fast air whoosh, cinematic | | `sfx/transition/swipe-horizontal.mp3` | 0.7s | 横向滑动（轮播、tab 切换） | smooth left-to-right air movement | | `sfx/transition/slide-in.mp3` | 0.6s | 元素滑入（side panel、抽屉） | smooth soft whoosh with arrival | | `sfx/transition/dissolve.mp3` | 0.8s | 柔化融化（图片淡出淡入） | soft dissolve, airy shimmer | ### 🃏 Container（卡片/容器） | 文件 | 时长 | 用途 | Prompt 要点 | |---|---|---|---| | `sfx/container/card-snap.mp3` | 0.5s | 卡片吸附/定位（v7b 保留） | card snap into place | | `sfx/container/card-flip.mp3` | 0.7s | 卡片翻转（前后面切换） | playing card flip, crisp snap | | `sfx/container/stack-collapse.mp3` | 0.8s | 堆叠合拢（列表聚合） | cards stacking, paper taps collapsing | | `sfx/container/modal-open.mp3` | 0.6s | 模态框打开 | modal popping open, whoosh + thud | ### 🔔 Feedback（通知/反馈） | 文件 | 时长 | 用途 | Prompt 要点 | |---|---|---|---| | `sfx/feedback/success-chime.mp3` | 1.0s | 成功提示（支付成功、任务完成） | two ascending bell tones, ios-style | | `sfx/feedback/error-tone.mp3` | 0.7s | 错误提示（警告、失败） | descending two-note warning, soft | | `sfx/feedback/notification-pop.mp3` | 0.6s | 消息弹出（toast、通知） | notification bloop, ios message alert | | `sfx/feedback/achievement.mp3` | 1.5s | 成就达成（里程碑、徽章） | triumphant rising arpeggio, game-style | ### ⏳ Progress（进度/状态） | 文件 | 时长 | 用途 | Prompt 要点 | |---|---|---|---| | `sfx/progress/loading-tick.mp3` | 0.5s | 加载计时（进度条节拍） | soft short pulse, minimal ambient | | `sfx/progress/complete-done.mp3` | 0.8s | 完成确认（step 完成） | two ascending satisfying tones | | `sfx/progress/generate-start.mp3` | 0.8s | AI 开始生成 | soft rising shimmer, magical whoosh | ### 💥 Impact（品牌/冲击） | 文件 | 时长 | 用途 | Prompt 要点 | |---|---|---|---| | `sfx/impact/logo-reveal.mp3` | 0.7s | Logo impact（v7b 保留） | logo reveal thud | | `sfx/impact/logo-reveal-v2.mp3` | 1.5s | 更长的 Logo impact（电影感） | cinematic bass hit with shimmer tail | | `sfx/impact/brand-stamp.mp3` | 1.0s | 印章重击（认证、盖章） | rubber stamp thud, paper contact | | `sfx/impact/drop-thud.mp3` | 0.7s | 物件落地（插入、放置） | heavy thud, wood surface contact | ### ✨ Magic（AI 变换） | 文件 | 时长 | 用途 | Prompt 要点 | |---|---|---|---| | `sfx/magic/sparkle.mp3` | 0.8s | 魔法闪光（AI 高亮、惊喜） | bright twinkling stars, fairy dust | | `sfx/magic/ai-process.mp3` | 1.2s | AI 处理音（thinking 状态） | modulating digital hum with shimmer | | `sfx/magic/transform.mp3` | 1.0s | 变换过渡（morph 效果） | rising shimmer whoosh with sparkle tail | ### 💻 Terminal（命令行） | 文件 | 时长 | 用途 | Prompt 要点 | |---|---|---|---| | `sfx/terminal/command-execute.mp3` | 0.5s | 命令执行 | crisp digital beep with tick, hacker ui | | `sfx/terminal/output-appear.mp3` | 0.6s | 输出出现 | rapid digital ticks, retro printout | | `sfx/terminal/cursor-blink.mp3` | 0.5s | 光标闪烁 | subtle soft digital pulse, rhythmic | --- ## 按场景推荐搭配 ### 💻 Terminal 交互演示 ``` type (0.5s) → enter (0.5s) → command-execute (0.5s) → output-appear (0.6s) ``` 循环元素：`cursor-blink` 作为 idle 时的环境音。 ### 🃏 卡片选择流程 ``` hover-subtle (0.5s, UI悬停) → click-soft (0.5s, 点击) → card-snap (0.5s, 定位) ``` 或进阶版：`card-flip` 做前后面切换。 ### 🤖 AI 生成全流程 ``` generate-start (0.8s, 启动) → ai-process (1.2s, 处理) → sparkle (0.8s, 闪现) → complete-done (0.8s, 完成) ``` 错误时用 `error-tone` 替代 `complete-done`。 ### 🎬 Logo Reveal（品牌时刻） ``` whoosh-fast (0.6s, 铺垫) → logo-reveal-v2 (1.5s, 落点) → sparkle (0.8s, 尾韵) ``` 简版：`whoosh → logo-reveal`（直接 v7b 两件套）。 ### 📱 UI 交互演示（移动端） ``` tap-finger (0.5s, 点击) → slide-in (0.6s, 面板滑入) → toggle-on (0.5s, 开关) ``` 完成后：`success-chime` 或 `notification-pop`。 ### 📊 数据可视化/仪表盘 ``` loading-tick (0.5s, 节拍) × N → complete-done (0.8s, 数据到位) → achievement (1.5s, 惊艳落点) ``` ### 🎯 表单提交流程 ``` click-soft (0.5s) → loading-tick ×2 (1.0s) → success-chime (1.0s) ``` 失败分支：`error-tone (0.7s)`。 ### 🪄 Magic Transform 场景 ``` whoosh-fast (0.6s) → transform (1.0s) → sparkle (0.8s) ``` 适合：元素变形、效果前后对比、"AI 重写"等演示。 --- ## 使用规范 ### 音量建议（来自 apple-gallery-showcase.md 音频双轨制） - **SFX 主轨**：`1.0`（不做衰减） - **BGM 背景轨**：`0.4 ~ 0.5`（SFX 明显穿透） - **多 SFX 叠加**：用 `amix=inputs=N:duration=longest:normalize=0` 保留动态范围 ### ffmpeg 拼接模板 ```bash # 单 SFX 对齐时间点： ffmpeg -i video.mp4 -itsoffset 2.5 -i sfx/ui/click.mp3 \ -filter_complex "[0:a][1:a]amix=inputs=2:duration=longest:normalize=0[a]" \ -map 0:v -map "[a]" output.mp4 # 多 SFX + BGM： ffmpeg -i video.mp4 \ -itsoffset 1.0 -i sfx/transition/whoosh-fast.mp3 \ -itsoffset 1.6 -i sfx/impact/logo-reveal-v2.mp3 \ -i bgm.mp3 \ -filter_complex "[3:a]volume=0.4[bgm];[0:a][1:a][2:a][bgm]amix=inputs=4:normalize=0[a]" \ -map 0:v -map "[a]" output.mp4 ``` ### 选型决策树 1. **有 tactile 动作**（打字/点击/滑动）→ `keyboard/` or `ui/` 2. **元素进场/出场** → `transition/` 3. **容器层操作**（卡片/模态） → `container/` 4. **状态反馈**（成功/失败/通知） → `feedback/` 5. **进度/时间流逝** → `progress/` 6. **品牌落点/重要时刻** → `impact/` 7. **AI 魔法/变换** → `magic/` 8. **命令行/代码演示** → `terminal/` ### 避免叠音堆积 - 同一个时间点 `max 2 个 SFX` 并发 - BGM 降到 0.3 以下时可以放 3 个 - 品牌 impact 时清空其他 SFX（留空 0.2s 再落点） --- ## Prompt 撰写原则（供复用） 参考风格：`apple keynote, tight, minimal, no reverb unless ambient, crisp, elegant` **好 prompt 的三要素**： 1. **声音物理描述**：什么物体、什么动作（"mechanical keyboard single key press"） 2. **质感/风格限定**：apple-style / ios-style / cinematic / retro 3. **反例排除**：no reverb / clean studio / minimal ❌ "click sound" ✅ "crisp ui button click, clean modern interface sound, apple-style, high pitched" ❌ "magic" ✅ "bright twinkling stars sound, high pitched glittery chime, fairy dust" --- ## 详见 - 音频双轨制与 ffmpeg 拼接：`apple-gallery-showcase.md` - 原始生成脚本：`/tmp/gen_sfx_batch.sh`（一次性批量生成器） -
slide-decks.md 35.3 KB
# Slide Decks：HTML幻灯片制作规范 做幻灯片是设计工作的高频场景。这份文档说明怎么做好HTML幻灯片——从架构选型、单页设计，到 PDF/PPTX 导出的完整路径。 **本 skill 的能力覆盖**： - **HTML 演示版（基础产物，永远默认必做）** → 每页独立 HTML + `assets/deck_index.html` 聚合，浏览器里键盘翻页、全屏演讲 - HTML → PDF 导出 → `scripts/export_deck_pdf.mjs` / `scripts/export_deck_stage_pdf.mjs` - HTML → 可编辑 PPTX 导出 → `references/editable-pptx.md` + `scripts/html2pptx.js` + `scripts/export_deck_pptx.mjs`（要求 HTML 按 4 条硬约束写） > **⚠️ HTML 是基础，PDF/PPTX 是衍生物。** 不管最终交付什么格式，都**必须**先做 HTML 聚合演示版（`index.html` + `slides/*.html`），它是幻灯片作品的「源」。PDF/PPTX 是从 HTML 一行命令导出的快照。 > > **为什么 HTML 优先**： > - 演讲/演示现场最好用（投影仪 / 共享屏幕直接全屏，键盘翻页，不依赖 Keynote/PPT 软件） > - 开发过程中每页可单独双击打开验证，不用每次重新跑导出 > - 是 PDF/PPTX 导出的唯一上游（避免「导出后才发现要改 HTML 又要重出」的死循环） > - 交付物可以是「HTML + PDF」或「HTML + PPTX」双份，接收方爱用哪个用哪个 > > 2026-04-22 moxt brochure 实测：做完 13 页 HTML + index.html 聚合后，`export_deck_pdf.mjs` 一行导出 PDF，零改动。HTML 版本身就是可直接浏览器演讲的交付物。 --- ## 🛑 开工前先确认交付格式（最硬的 checkpoint） **这个决策比「单文件还是多文件」更先。** 2026-04-20 期权私董会项目实测：**不在动手前确认交付格式 = 2-3 小时返工。** ### 决策树（HTML-first 架构） 所有交付都从同一套 HTML 聚合页（`index.html` + `slides/*.html`）开始。交付格式只决定 **HTML 的写法约束** 和 **导出命令**： ``` 【永远默认 · 必做】 HTML 聚合演示版（index.html + slides/*.html） │ ├── 只要浏览器演讲 / 本地 HTML 存档 → 到这里已经完成，HTML 视觉自由度最大 │ ├── 还要 PDF（打印 / 发群 / 存档） → 跑 export_deck_pdf.mjs 一键出 │ HTML 写法自由，视觉无约束 │ └── 还要可编辑 PPTX（同事要改文字） → 从第一行 HTML 就按 4 条硬约束写 跑 export_deck_pptx.mjs 一键出 牺牲渐变 / web component / 复杂 SVG ``` ### 开工话术（抄走即用） > 不管最后交付是 HTML、PDF 还是 PPTX，我都会先做一个可在浏览器里切换和演讲的 HTML 聚合版（`index.html` 加键盘翻页）——这是永远的默认基础产物。在此之上再问你要不要额外出 PDF / PPTX 的快照。 > > 你需要哪个导出格式？ > - **只要 HTML**（演讲/存档）→ 视觉完全自由 > - **还要 PDF** → 同上，加一条导出命令 > - **还要可编辑 PPTX**（同事会在 PPT 里改文字）→ 我必须从第一行 HTML 就按 4 条硬约束写，会牺牲一些视觉能力（无渐变、无 web component、无复杂 SVG）。 ### 为什么「要 PPTX 就得从头走 4 条硬约束」 PPTX 可编辑的前提是 `html2pptx.js` 能把 DOM 逐元素翻译为 PowerPoint 对象。它需要 **4 条硬约束**： 1. body 固定 960pt × 540pt（匹配 `LAYOUT_WIDE`，13.333″ × 7.5″，不是 1920×1080px） 2. 所有文字包在 `<p>`/`<h1>`-`<h6>` 里（禁止 div 直接放文字，禁止用 `<span>` 承载主文字） 3. `<p>`/`<h*>` 自身不能有 background/border/shadow（放外层 div） 4. `<div>` 不能用 `background-image`（用 `<img>` 标签） 5. 不用 CSS gradient、不用 web component、不用复杂 SVG 装饰 **本 skill 默认的 HTML 视觉自由度高**——大量 span、嵌套 flex、复杂 SVG、web component（如 `<deck-stage>`）、CSS 渐变——**几乎没有一条能天然过 html2pptx 的约束**（实测视觉驱动的 HTML 直接上 html2pptx，pass 率 < 30%）。 ### 两条真实路径的代价对比（2026-04-20 真实踩坑） | 路径 | 做法 | 结果 | 代价 | |------|------|------|------| | ❌ **先自由写 HTML，事后补救 PPTX** | 单文件 deck-stage + 大量 SVG/span 装饰 | 要可编辑 PPTX 只剩两条路：<br>A. 手写 pptxgenjs 几百行 hardcode 坐标<br>B. 重写 17 页 HTML 成 Path A 格式 | 2-3 小时返工，且手写版**维护成本永续**（HTML 改一个字，PPTX 要再人肉同步） | | ✅ **从第一步按 Path A 约束写** | 每页独立 HTML + 4 条硬约束 + 960×540pt | 一条命令导出 100% 可编辑 PPTX，同时也能浏览器全屏演讲（Path A HTML 就是浏览器可播放的标准 HTML） | 写 HTML 时多花 5 分钟想「文字怎么包进 `<p>`」，零返工 | ### 混合交付怎么办 用户说「我要 HTML 演讲 **和** 可编辑 PPTX」——**这不是混合**，是 PPTX 需求覆盖 HTML 需求。按 Path A 写出来的 HTML 本身就能浏览器全屏演讲（加个 `deck_index.html` 拼接器就行）。**没有额外代价。** 用户说「我要 PPTX **和** 动画 / web component」——**这是真矛盾**。告诉用户：要可编辑 PPTX 就得牺牲这些视觉能力。让他做取舍，不要偷偷做手写 pptxgenjs 方案（会变成永续维护债）。 ### 事后才知道要 PPTX 怎么办（紧急补救） 极个别情况：HTML 已经写好了才发现要 PPTX。推荐走 **fallback 流程**（完整说明见 `references/editable-pptx.md` 末尾「Fallback：已有视觉稿但用户坚持要 editable PPTX」）： 1. **首选：改出 PDF**（视觉 100% 保留，跨平台，接收方能看能印）—— 如果接收方实际需求是「演讲/存档」，PDF 就是最佳交付物 2. **次选：AI 以视觉稿为蓝本，重写一版 editable HTML** → 导出 editable PPTX —— 保留色彩/布局/文案的设计决策，牺牲渐变、web component、复杂 SVG 等视觉能力 3. **不推荐：手写 pptxgenjs 重建**——位置、字体、对齐都要手调，维护成本高，且后续 HTML 改一个字都得再人肉同步一次 永远把选择告诉用户，让他决定。**永远不要第一反应就开始手写 pptxgenjs**——那是最后的兜底手段。 --- ## 🛑 批量制作前：先做 2 页 showcase 定 grammar **只要 deck ≥ 5 页，绝对不能从第 1 页直接写到最后一页。** 2026-04-22 moxt brochure 实战验证的正确顺序： 1. 选 **2 个视觉差异最大的页面类型**先做 showcase（如「封面」+「情绪/引用页」，或「封面」+「产品展示页」） 2. 截图让用户确认 grammar（masthead / 字体 / 色 / 间距 / 结构 / 中英双语比例） 3. 方向通过了再批量推剩下 N-2 页，每页复用已建立的 grammar 4. 全部完成后一起合成 HTML 聚合 + PDF / PPTX 衍生物 **为什么**：直接写 13 页到底 → 用户说「方向不对」= 返工 13 次。先做 2 页 showcase → 方向错 = 返工 2 次。视觉 grammar 一旦确立，后续 N 页的决策空间大幅收窄，只剩「内容怎么放进去」。 **showcase 页选择原则**：选视觉结构最不一样的两页。这两页过了 = 其他中间态都能过。 | Deck 类型 | 推荐 showcase 页组合 | |-----------|---------------------| | B2B brochure / 产品宣发 | 封面 + 内容页（理念/情感页） | | 品牌发布 | 封面 + 产品特色页 | | 数据报告 | 数据大图页 + 分析结论页 | | 教程课件 | 章节封页 + 具体知识点页 | --- ## 📐 出版物 grammar 模板（moxt 实测可复用） 适合 B2B brochure / 产品宣发 / 长报告类 deck。每页复用这套结构 = 13 页视觉完全一致、0 返工。 ### 每页骨架 ``` ┌─ masthead（顶部 strip + 横线）────────────┐ │ [logo 22-28px] · A Product Brochure Issue · Date · URL │ ├──────────────────────────────────────────┤ │ │ │ ── kicker（绿色短横 + uppercase 标签） │ │ CHAPTER XX · SECTION NAME │ │ │ │ H1（中文 Noto Serif SC 900） │ │ 重点词单独上品牌主色 │ │ │ │ English subtitle (Lora italic，副标题) │ │ ─────────── 分隔线 ────────── │ │ │ │ [具体内容：双栏 60/40 / 2x2 grid / 列表] │ │ │ ├──────────────────────────────────────────┤ │ section name XX / total │ └──────────────────────────────────────────┘ ``` ### 样式约定（直接抄走） - **H1**：中文 Noto Serif SC 900，字号 80-140px 看信息量，重点词单独上品牌主色（不要全文堆色） - **英文副**：Lora italic 26-46px，品牌签名词（如 "AI team"）粗体 + 主色斜体 - **正文**：Noto Serif SC 17-21px，line-height 1.75-1.85 - **accent 高亮**：正文里用主色加粗标注关键词，每页不超过 3 处（过多就失去锚点作用） - **背景**：暖米底 #FAFAFA + 极淡 radial-gradient noise（`rgba(33,33,33,0.015)`）增加纸感 ### 视觉主角必须差异化 13 页如果全是「文字 + 一张截图」就太单调。**每页的视觉主角类型轮换**： | 视觉类型 | 适合的 section | |---------|---------------| | 封面排版（大字 + masthead + pillar） | 首页 / 篇章封 | | 单角色 portrait（超大单只 momo 等） | 介绍单个概念/角色 | | 多角色合影 / 头像卡并排 | 团队 / 用户案例 | | 时间轴卡片递进 | 展示「长期关系」「演进」 | | 知识图谱 / 连接节点图 | 展示「协作」「流动」 | | Before/After 对比卡 + 中间箭头 | 展示「改变」「差异」 | | 产品 UI 截图 + 描边设备框 | 具体功能展示 | | 大引号 big-quote（半页大字） | 情绪页 / 问题页 / 引文页 | | 真人头像 + 引言卡（2×2 或 1×4） | 用户见证 / 使用场景 | | 大字封底 + URL 椭圆按钮 | CTA / 结尾 | --- ## ⚠️ 常见踩坑（moxt 实战总结） ### 1. Emoji 在 Chromium / Playwright 导出时不渲染 Chromium 默认不带彩色 emoji 字体，`page.pdf()` 或 `page.screenshot()` 时 emoji 显示为空方框。 **对策**：用 Unicode 文字符号（`✦` `✓` `✕` `→` `·` `—`）替代，或直接改纯文字（「Email · 23」而不是「📧 23 emails」）。 ### 2. `export_deck_pdf.mjs` 报错 `Cannot find package 'playwright'` 原因：ESM 模块解析从脚本所在位置向上找 `node_modules`。脚本在 `~/.claude/skills/huashu-design/scripts/`，那里没依赖。 **对策**：把脚本复制到 deck 项目目录（例如 `brochure/build-pdf.mjs`），在项目根跑 `npm install playwright pdf-lib`，然后 `node build-pdf.mjs --slides slides --out output/deck.pdf`。 ### 3. Google Fonts 没加载完就截图 → 中文显示为系统默认黑体 Playwright 截图/PDF 前至少 `wait-for-timeout=3500` 让 webfont 下载并 paint。或者把字体 self-host 到 `shared/fonts/` 减少网络依赖。 ### 4. 信息密度失衡：内容页塞太多 moxt philosophy 页第一版用 2×2 = 4 段 + 底部 3 信条 = 7 块内容，挤压且重复。改成 1×3 = 3 段后呼吸感立刻回来。 **对策**：每页控制在「1 个核心信息 + 3-4 个辅助点 + 1 个视觉主角」，超过就拆到新页。**少即是多**——观众一页看 10 秒，给他 1 个记忆点比 4 个记忆点更容易记住。 --- ## 🛑 先定架构：单文件 还是 多文件？ **这个选择是做幻灯片的第一步，错了会反复踩坑。先读完这一节再动手。** ### 两种架构对比 | 维度 | 单文件 + `deck_stage.js` | **多文件 + `deck_index.html` 拼接器** | |------|--------------------------|--------------------------------------| | 代码结构 | 一个 HTML，所有 slide 是 `<section>` | 每页独立 HTML，`index.html` 用 iframe 拼接 | | CSS 作用域 | ❌ 全局，一页的样式可能影响所有页 | ✅ 天然隔离，iframe 各自一片天 | | 验证粒度 | ❌ 要 JS goTo 才能切到某页 | ✅ 单页文件双击就能在浏览器看 | | 并行开发 | ❌ 一个文件，多 agent 改会冲突 | ✅ 多 agent 可并行做不同页，零冲突 merge | | 调试难度 | ❌ 一处 CSS 出错，全 deck 翻车 | ✅ 一页出错只影响自己 | | 内嵌交互 | ✅ 跨页共享状态很简单 | 🟡 iframe 间需 postMessage | | 打印 PDF | ✅ 内置 | ✅ 拼接器 beforeprint 遍历 iframe | | 键盘导航 | ✅ 内置 | ✅ 拼接器内置 | ### 选哪个？（决策树） ``` │ 问：deck 预计有多少页？ ├── ≤10 页、需要 in-deck 动画或跨页交互、pitch deck → 单文件 └── ≥10 页、学术讲座、课件、长 deck、多 agent 并行 → 多文件（推荐） ``` **默认走多文件路径**。它不是「备选」，是**长 deck 和团队协作的主路径**。原因：单文件架构的每一个优势（键盘导航、打印、scale）多文件都有，而多文件的作用域隔离和可验证性是单文件补不回来的。 ### 为什么这条规则这么硬？（真实事故记录） 单文件架构曾经在 AI心理学讲座 deck 制作中连踩四坑： 1. **CSS 特异性覆盖**：`.emotion-slide { display: grid }` (特异性 10) 干翻 `deck-stage > section { display: none }` (特异性 2)，导致所有页同时渲染叠加。 2. **Shadow DOM slot 规则被外层 CSS 压制**：`::slotted(section) { display: none }` 挡不住 outer rule 的覆盖，sections 不肯隐藏。 3. **localStorage + hash 导航竞态**：刷新后不是跳到 hash 位置，而是停在 localStorage 记录的旧位置。 4. **验证成本高**：必须 `page.evaluate(d => d.goTo(n))` 才能截某页，比直接 `goto(file://.../slides/05-X.html)` 慢一倍，还常报错。 全部根因是**单一全局命名空间**——多文件架构从物理层面把这些问题消除了。 --- ## 路径 A（默认）：多文件架构 ### 目录结构 ``` 我的Deck/ ├── index.html # 从 assets/deck_index.html 复制来，改 MANIFEST ├── shared/ │ ├── tokens.css # 共享设计 token（色板/字号/常用 chrome） │ └── fonts.html # <link> 引入 Google Fonts（每页 include） └── slides/ ├── 01-cover.html # 每个文件都是完整 1920×1080 HTML ├── 02-agenda.html ├── 03-problem.html └── ... ``` ### 每张 slide 的模板骨架 ```html <!DOCTYPE html> <html lang="zh-CN"> <head> <meta charset="UTF-8"> <title>P05 · Chapter Title</title> <link href="https://fonts.googleapis.com/css2?family=..." rel="stylesheet"> <link rel="stylesheet" href="../shared/tokens.css"> <style> /* 这一页独有的样式。用任何 class 名都不会污染别的页。*/ body { padding: 120px; } .my-thing { ... } </style> </head> <body> <!-- 1920×1080 的内容（由 body 的 width/height 在 tokens.css 里锁定）--> <div class="page-header">...</div> <div>...</div> <div class="page-footer">...</div> </body> </html> ``` **关键约束**： - `<body>` 就是画布，直接在上面布局。不要包 `<section>` 或其他 wrapper。 - `width: 1920px; height: 1080px` 由 `shared/tokens.css` 里的 `body` 规则锁定。 - 引 `shared/tokens.css` 共享设计 token（色板、字号、page-header/footer 等）。 - 字体 `<link>` 每页自己写（fonts 单独 import 不贵，且保证每页独立可打开）。 ### 拼接器：`deck_index.html` **直接从 `assets/deck_index.html` 复制**。你只需要改一处——`window.DECK_MANIFEST` 数组，按顺序列出所有 slide 文件名和人类可读标签： ```js window.DECK_MANIFEST = [ { file: "slides/01-cover.html", label: "封面" }, { file: "slides/02-agenda.html", label: "目录" }, { file: "slides/03-problem.html", label: "问题陈述" }, // ... ]; ``` 拼接器已内置：键盘导航（←/→/Home/End/数字键/P 打印）、scale + letterbox、右下计数器、localStorage 记忆、hash 跳页、打印模式（遍历 iframe 按页输出 PDF）。 #### 两种概览模式（自适应 + 防踩坑，2026-06 重写） 打开 deck 默认进**概览**，用户未指定时按秒数随机：**网格 grid 60% / 无限画廊 gallery 40%**（可用 URL `?ov=grid|gallery` 或 `window.DECK_OVERVIEW='grid'|'gallery'` 固定）。 - **网格 grid（默认主力）**：用 **iframe 渲染真实子页面**（清晰、所见即所得、无需缩略图）。**自适应**：能一屏放下→对角倾斜居中铺满；页多放不下→卡片保持舒适大小、**竖向滚动**（绝不把几十页硬塞一屏缩成邮票）。 - **无限画廊 gallery**：所有页**无缝无限平铺 + 缓慢漂移 + 轻微呼吸缩放**，一个 tile 含全部页（洗牌排布，看完所有页才重复）。瓦片多，**必须用 `<img>` 缩略图**扛性能（见下），没 thumb 时回退 iframe。 🛑 **三条来自实战的硬约束（改这个文件前必读，否则会重蹈覆辙）**： 1. **概览墙绝不用 `transform-style: preserve-3d` 做卡片墙**。preserve-3d 的 3D 场景里浏览器对「往后退的卡片」（顶排）命中测试不可靠 → 顶排点不到、中排时好时坏。**正解**：整墙作**单个被 3D 倾斜的平面**（不开 preserve-3d），所有卡片共面，点击反投影到一个平面 → 可靠。hover 用 2D `scale` 不用 `translateZ`。 2. **任意页数都要自适应**：固定列数 + 给整墙写死强倾斜，页一多就溢出塌角/透视失真。必须按页数+视口算列数、行多则倾斜变平、一屏放不下就滚动。 3. **缩略图分辨率别太低**：画廊缩略图 < 1000px，hover 放大后发虚。默认 1600px。 **为画廊生成缩略图**：用 `scripts/gen_deck_thumbs.mjs`（playwright 截每页 + sharp 降采样）： ```bash npm install playwright sharp node gen_deck_thumbs.mjs --slides slides --out thumbs --width 1600 ``` 然后给 MANIFEST 每项加 `thumb: "thumbs/<同名>.jpg"`。网格模式忽略 thumb（始终 iframe），只有画廊模式用它。 ### 单页验证（这是多文件架构的杀手级优势） 每张 slide 都是独立 HTML。**做完一张就在浏览器双击打开看**： ```bash open slides/05-personas.html ``` Playwright 截图也是直接 `goto(file://.../slides/05-personas.html)`，不需要 JS 跳页，也不会被别的页的 CSS 干扰。这让「改一点验一点」的工作流成本接近零。 ### 并行开发 把每张 slide 的任务拆给不同 agent，同时跑——HTML 文件彼此独立，merge 时没有冲突。长 deck 用这种并行方式能把制作时间压到 1/N。 ### `shared/tokens.css` 该放什么 只放**真正跨页共用**的东西： - CSS 变量（色板、字号阶、间距阶） - `body { width: 1920px; height: 1080px; }` 这样的 canvas 锁定 - `.page-header` / `.page-footer` 这种每页都用一模一样的 chrome **不要**把单页的布局 class 塞进来——那会退化回单文件架构的全局污染问题。 --- ## 路径 B（小 deck）：单文件 + `deck_stage.js` 适用于 ≤10 页、需要跨页共享状态（比如一个 React tweaks 面板要操控所有页）、或者做 pitch deck demo 这种要求极度紧凑的场景。 ### 基本用法 1. 从 `assets/deck_stage.js` 读取内容，嵌入 HTML 的 `<script>`（或 `<script src="deck_stage.js">`） 2. 在 body 里用 `<deck-stage>` 包 slide 3. 🛑 **script 标签必须放在 `</deck-stage>` 之后**（见下方硬约束） ```html <body> <deck-stage> <section> <h1>Slide 1</h1> </section> <section> <h1>Slide 2</h1> </section> </deck-stage> <!-- ✅ 正确：script 在 deck-stage 之后 --> <script src="deck_stage.js"></script> </body> ``` ### 🛑 Script 位置硬约束（2026-04-20 真实踩坑） **不能把 `<script src="deck_stage.js">` 放在 `<head>` 里。** 即使它在 `<head>` 里能定义 `customElements`，parser 在解析到 `<deck-stage>` 开始标签时就会触发 `connectedCallback`——此时子 `<section>` 还没被 parse，`_collectSlides()` 拿到空数组，counter 显示 `1 / 0`，所有页同时叠加渲染。 **三条合规写法**（任选其一）： ```html <!-- ✅ 最推荐：script 在 </deck-stage> 之后 --> </deck-stage> <script src="deck_stage.js"></script> <!-- ✅ 也可：script 在 head 但加 defer --> <head><script src="deck_stage.js" defer></script></head> <!-- ✅ 也可：module 脚本天然 defer --> <head><script src="deck_stage.js" type="module"></script></head> ``` `deck_stage.js` 本身已内置 `DOMContentLoaded` 延迟收集防御，即使 script 放 head 也不会彻底炸掉——但 `defer` 或放 body 底部仍然是更干净的做法，避免依赖防御分支。 ### ⚠️ 单文件架构的 CSS 陷阱（务必阅读） 单文件架构最常见的坑——**`display` 属性被单页样式偷走**。 常见错误姿势 1（直接写 display: flex 到 section）： ```css /* ❌ 外部 CSS 特异性 2，覆盖了 shadow DOM 的 ::slotted(section){display:none}（也是 2）*/ deck-stage > section { display: flex; /* 所有页会同时叠加渲染！ */ flex-direction: column; padding: 80px; ... } ``` 常见错误姿势 2（section 有特异性更高的 class）： ```css .emotion-slide { display: grid; } /* 特异性: 10，更糟 */ ``` 两种都会让 **所有 slide 同时叠加渲染**——counter 可能显示 `1 / 10` 假装正常，但视觉上第一页盖着第二页盖着第三页。 ### ✅ Starter CSS（开工直接 copy，不踩坑） **section 自身**只管「可见/不可见」；**layout（flex/grid 等）写到 `.active` 上**： ```css /* section 只定义非 display 的通用样式 */ deck-stage > section { background: var(--paper); padding: 80px 120px; overflow: hidden; position: relative; /* ⚠️ 不要在这里写 display! */ } /* 锁死「非激活即隐藏」——特异性+权重双保险 */ deck-stage > section:not(.active) { display: none !important; } /* 激活页才写需要的 display + layout */ deck-stage > section.active { display: flex; flex-direction: column; justify-content: center; } /* 打印模式：所有页都要显示，覆盖 :not(.active) */ @media print { deck-stage > section { display: flex !important; } deck-stage > section:not(.active) { display: flex !important; } } ``` 替代方案：**把单页的 flex/grid 写到内部 wrapper `<div>` 上**，section 本身永远只是 `display: block/none` 的切换器。这是最干净的做法： ```html <deck-stage> <section> <div class="slide-content flex-layout">...</div> </section> </deck-stage> ``` ### 自定义尺寸 ```html <deck-stage width="1080" height="1920"> <!-- 9:16 竖版 --> </deck-stage> ``` --- ## Slide Labels Deck_stage 和 deck_index 都会给每页打标签（计数器显示）。给它们**更有意义**的 label： **多文件**：在 `MANIFEST` 里写 `{ file, label: "04 问题陈述" }` **单文件**：在 section 上加 `<section data-screen-label="04 Problem Statement">` **关键：Slide 编号从 1 开始，不要从 0**。 用户说"slide 5"时，他指的是第 5 张，永远不是数组位置 `[4]`。人类不说 0-indexed。 --- ## Speaker Notes **默认不加**，只在用户明确要求时才加。 加了 speaker notes 你就可以把 slide 上的文字减少到最小，focus on impactful visuals——notes 承载完整 script。 ### 格式 **多文件**：在 `index.html` 的 `<head>` 里写： ```html <script type="application/json" id="speaker-notes"> [ "第1张的 script...", "第2张的 script...", "..." ] </script> ``` **单文件**：同上位置。 ### Notes 写作要点 - **完整**：不是提纲，是真要讲的话 - **对话式**：像平时说话，不是书面语 - **对应**：数组第 N 个对应第 N 张 slide - **长度**：200-400 字最佳 - **情绪线**：标注重音、停顿、强调点 --- ## Slide 设计模式 ### 1. 建立一个系统（必做） 探索完 design context 后，**先口头说你要用的系统**： ```markdown Deck系统： - 背景色：最多2种（90% 白 + 10% 深色 section divider） - 字型：display 用 Instrument Serif，body 用 Geist Sans - 节奏：section divider 用 full-bleed 彩色 + 白字，普通 slide 白底 - 图像：hero slide 用 full-bleed 照片，data slide 用 chart 我按这个系统做，有问题告诉我。 ``` 用户确认后再往下做。 ### 2. 常用 slide layouts - **Title slide**：纯色背景 + 巨大标题 + 副标题 + 作者/日期 - **Section divider**：彩色背景 + 章节号 + 章节标题 - **Content slide**：白底 + 标题 + 1-3 bullet points - **Data slide**：标题 + 大图表/数字 + 简短说明 - **Image slide**：full-bleed 照片 + 底部小 caption - **Quote slide**：留白 + 巨大 quote + attribution - **Two-column**：左右对比（vs / before-after / problem-solution） 一个 deck 里最多用 4-5 种 layout。 ### 3. Scale（再次强调） - 正文最小 **24px**，理想 28-36px - 标题 **60-120px** - Hero 字 **180-240px** - 幻灯片是给 10 米外看的，字要够大 ### 4. 视觉节奏 Deck 需要 **intentional variety**： - 颜色节奏：大部分白底 + 偶尔彩色 section divider + 偶尔 dark 片段 - 密度节奏：几张 text-heavy 的 + 几张 image-heavy 的 + 几张 quote 留白 - 字号节奏：正常标题 + 偶尔巨型 hero 文字 **不要每张 slide 长一样**——那是 PPT 模板，不是设计。 ### 5. 空间呼吸（数据密集页必读） **新手最容易踩的坑**：把所有能放的信息都塞进一页。 信息密度 ≠ 有效信息传达。学术/演讲类 deck 尤其要克制： - 列表/矩阵页：不要把 N 个元素都画成同一大小。用 **主次分层**——今天要聊的 5 个放大做主角，剩下 16 个缩小做背景 hint。 - 大数字页：数字本身是视觉主角。周围的 caption 不要超过 3 行，否则观众眼球来回跳。 - 引用页：引语和 attribution 之间要有留白隔开，不要贴在一起。 对照「数据是不是主角」「文字有没有挤在一起」两条自我审查，改到留白让你有点不安为止。 --- ## 打印为 PDF **多文件**：`deck_index.html` 已处理 `beforeprint` 事件，按页输出 PDF。 **单文件**：`deck_stage.js` 同样处理。 打印样式已写好，不需要额外写 `@media print` CSS。 --- ## 导出为 PPTX / PDF（自助脚本） HTML 优先是第一公民。但用户经常需要 PPTX/PDF 交付。提供两个通用脚本，**任何多文件 deck 都能用**，位于 `scripts/` 下： ### `export_deck_pdf.mjs` — 导出矢量 PDF（多文件架构） ```bash node scripts/export_deck_pdf.mjs --slides <slides-dir> --out deck.pdf ``` **特点**： - 文字**保留矢量**（可复制、可搜索） - 视觉 100% 保真（Playwright 内嵌 Chromium 渲染后打印） - **不需要改 HTML 任何一个字** - 每个 slide 独立 `page.pdf()`，再用 `pdf-lib` 合并 **依赖**：`npm install playwright pdf-lib` **限制**：PDF 不能再编辑文字——要改回到 HTML 改。 ### `export_deck_stage_pdf.mjs` — 单文件 deck-stage 架构专用 ⚠️ **什么时候用**：deck 是单 HTML 文件 + `<deck-stage>` web component 包裹 N 个 `<section>`（即路径 B 架构）。此时 `export_deck_pdf.mjs` 那套「每个 HTML 一次 `page.pdf()`」走不通，需要走这个专用脚本。 ```bash node scripts/export_deck_stage_pdf.mjs --html deck.html --out deck.pdf ``` **为什么不能复用 export_deck_pdf.mjs**（2026-04-20 真实踩坑记录）： 1. **Shadow DOM 赢过 `!important`**：deck-stage 的 shadow CSS 里有 `::slotted(section) { display: none }`（只 active 的那张 `display: block`）。即使在 light DOM 用 `@media print { deck-stage > section { display: block !important } }` 也压不住——`page.pdf()` 触发 print 媒体后 Chromium 最终渲染只有 active 那一张，结果**整个 PDF 只有 1 页**（当前 active slide 的重复）。 2. **循环 goto 每页还是只出 1 页**：直觉解法「对每个 `#slide-N` navigate 一次再 `page.pdf({pageRanges:'1'})`」也失败——因为 print CSS 在 shadow DOM 之外也有 `deck-stage > section { display: block }` 规则被 override 后，最终渲染永远是 section 列表的第一个（不是你 navigate 到的那一页）。结果 17 次循环得到 17 张 P01 封面。 3. **absolute 子元素跑到下一页**：即使成功让所有 section 渲染出来，section 本身若 `position: static`，其 absolute 定位的 `cover-footer`/`slide-footer` 会相对 initial containing block 定位——当 section 被 print 强制为 1080px 高度，absolute footer 可能被推到下一页（表现为 PDF 比 section 数量多 1 页，多出来的那页只含 footer 孤儿）。 **修复策略**（脚本已实现）： ```js // 打开 HTML 后，用 page.evaluate 把 section 从 deck-stage slot 中提出来， // 直接挂到 body 下一个普通 div 里，并内联 style 确保 position:relative + 固定尺寸 await page.evaluate(() => { const stage = document.querySelector('deck-stage'); const sections = Array.from(stage.querySelectorAll(':scope > section')); document.head.appendChild(Object.assign(document.createElement('style'), { textContent: ` @page { size: 1920px 1080px; margin: 0; } html, body { margin: 0 !important; padding: 0 !important; } deck-stage { display: none !important; } `, })); const container = document.createElement('div'); sections.forEach(s => { s.style.cssText = 'width:1920px!important;height:1080px!important;display:block!important;position:relative!important;overflow:hidden!important;page-break-after:always!important;break-after:page!important;background:#F7F4EF;margin:0!important;padding:0!important;'; container.appendChild(s); }); // 最后一页禁分页，避免尾部空白页 sections[sections.length - 1].style.pageBreakAfter = 'auto'; sections[sections.length - 1].style.breakAfter = 'auto'; document.body.appendChild(container); }); await page.pdf({ width: '1920px', height: '1080px', printBackground: true, preferCSSPageSize: true }); ``` **为什么这能 work**： - 把 section 从 shadow DOM slot 拔到 light DOM 的普通 div——彻底绕过 `::slotted(section) { display: none }` 规则 - 内联 `position: relative` 让 absolute 子元素相对 section 定位，不会溢出 - `page-break-after: always` 让浏览器 print 时每 section 独立一页 - `:last-child` 不分页避免尾部空白页 **用 `mdls -name kMDItemNumberOfPages` 验证时注意**：macOS 的 Spotlight metadata 有缓存，PDF 重写后要跑 `mdimport file.pdf` 强制刷新，否则显示旧的页数。用 `pdfinfo` 或 `pdftoppm` 数文件数才是真数。 --- ### `export_deck_pptx.mjs` — 导出可编辑 PPTX ```bash # 唯一模式：文本框原生可编辑（字体会回落到系统字体） node scripts/export_deck_pptx.mjs --slides <dir> --out deck.pptx ``` 工作原理：`html2pptx` 逐元素读 computedStyle 把 DOM 翻译成 PowerPoint 对象（text frame / shape / picture）。文字变成真文本框，PPT 里双击即可编辑。 **硬性约束**（HTML 必须满足，否则该页 skip，详细说明见 `references/editable-pptx.md`）： - 所有文字必须在 `<p>`/`<h1>`-`<h6>`/`<ul>`/`<ol>` 里（禁止裸文本 div） - `<p>`/`<h*>` 标签自身不能有 background/border/shadow（放外层 div） - 不用 `::before`/`::after` 插入装饰文字（伪元素提不出来） - inline 元素（span/em/strong）不能有 margin - 不用 CSS gradient（不可渲染） - div 不用 `background-image`（用 `<img>`） 脚本已内置**自动预处理器**——把 "叶子 div 里的裸文本" 自动包成 `<p>`（保留 class）。这解决了最常见的违规（裸文本）。但其他违规（p 上有 border、span 上有 margin 等）仍需 HTML 源头合规。 **字体回落 caveat**： - Playwright 用 webfont 测量 text-box 尺寸；PowerPoint/Keynote 用本机字体渲染 - 两者不同时会有**溢出或错位**——每页都要肉眼过 - 建议目标机器装好 HTML 里用的字体，或 fallback 到 `system-ui` **视觉优先场景不要走这条路径** → 改用 `export_deck_pdf.mjs` 出 PDF。PDF 视觉 100% 保真、矢量、跨平台、文字可搜——是视觉优先 deck 的真正归宿，不是什么「不可编辑的妥协」。 ### 从一开始就让 HTML 对导出友好 对性能最稳的 deck：**从写 HTML 时就按 editable 的 4 条硬约束写**。这样 `export_deck_pptx.mjs` 可以直接全部 pass。额外成本不大： ```html <!-- ❌ 不好 --> <div class="title">关键发现</div> <!-- ✅ 好（p 包裹，class 继承） --> <p class="title">关键发现</p> <!-- ❌ 不好（border 在 p 上） --> <p class="stat" style="border-left: 3px solid red;">41%</p> <!-- ✅ 好（border 在外层 div） --> <div class="stat-wrap" style="border-left: 3px solid red;"> <p class="stat">41%</p> </div> ``` ### 何时选哪个 | 场景 | 推荐 | |------|------| | 给主办方/档案存档 | **PDF**（通用、高保真、文字可搜） | | 发给协作者让他们微调文字 | **PPTX editable**（接受字体回落） | | 要现场演讲、不改内容 | **PDF**（矢量保真，跨平台） | | HTML 是首选呈现媒介 | 直接浏览器播放，导出只是备份 | ## 导出为可编辑 PPTX 的深度路径（仅长期项目） 如果你的 deck 会长期维护、反复修改、团队协作——建议**一开始就按 html2pptx 约束写 HTML**，这样 `export_deck_pptx.mjs` 可以直接全部 pass。详见 `references/editable-pptx.md`（4 条硬约束 + HTML 模板 + 常见错误速查 + 已有视觉稿的 fallback 流程）。 --- ## 常见问题 **多文件：iframe 里的页打不开 / 白屏** → 检查 `MANIFEST` 的 `file` 路径是否相对 `index.html` 正确。用浏览器 DevTools 看 iframe 的 src 能否直接访问。 **多文件：某页样式和别页冲突** → 不可能（iframe 隔离）。如果感觉冲突，那是缓存——Cmd+Shift+R 强刷。 **单文件：多 slide 同时渲染叠加** → CSS 特异性问题。看上面「单文件架构的 CSS 陷阱」一节。 **单文件：缩放看起来不对** → 检查是否所有 slide 直接挂在 `<deck-stage>` 下作为 `<section>`。中间不能包 `<div>`。 **单文件：想跳到特定 slide** → URL 加 hash：`index.html#slide-5` 跳到第 5 张。 **两种架构都适用：字在不同屏幕下位置不一致** → 用固定尺寸（1920×1080）和 `px` 单位，不要用 `vw`/`vh` 或 `%`。缩放统一处理。 --- ## 验证检查清单（做完 deck 必过） 1. [ ] 浏览器直接打开 `index.html`（或主 HTML），检查首页无破图、字体已加载 2. [ ] 按 → 键翻到每一页，没有空白页、没有布局错位 3. [ ] 按 P 键打印预览，每页恰好一张 A4（或 1920×1080）且无裁切 4. [ ] 随机选 3 页 Cmd+Shift+R 强刷，localStorage 记忆正常工作 5. [ ] Playwright 批量截图（单页架构：遍历 `slides/*.html`；单文件架构：用 goTo 切换），人工肉眼过一遍 6. [ ] 搜一下 `TODO` / `placeholder` 残留，确认都清理了 -
storyboard-basics.md 23.4 KB
# Storyboard Basics · 轻量分镜与画面构图 > 任何动画开工前的分镜方法，不论 5 秒还是 50 秒。核心一句话：**每一镜先是一张会动的封面**。 > > 方法论来源：花叔配图库 300+ 张封面实测提炼的定格帧规则（S1-S11）、video-shotcraft 106 张镜头卡的能量骨架判例、HuaRec Studio 运镜导演系统的镜头预算公理。 --- ## 0 · 定位：与 launch-film 导演稿的分工 本文件是 `launch-film-director-notes.md` 的**日常轻量版**。launch film 万字导演稿是重装流程，日常动画不需要那套，但**分镜这道工序本身不能省**——省掉的结果是时间表思维（第几秒出什么元素），不是画面思维（这一帧长什么样）。 | 片长 / 类型 | 分镜要求 | 依据 | |---|---|---| | < 20s 动画、motion graphic、demo | 本文件的**轻量分镜卡**（§5，每镜一行） | 20s 以下不值得写万字，但每镜的画面构图必须先想清楚 | | ≥ 20s 动画 | Gate 文件协议要求的 `导演稿.md`，**最低要求 = 本文件的分镜卡格式**（§5 八字段一个不能少），在此之上自由加厚 | SKILL.md「Gate 文件协议」 | | launch film / 品牌宣传片 /「Apple 级」预期 | 在分镜卡基线上升级为万字 director's notes | `launch-film-director-notes.md`，它的 Part IV 每镜 10 字段是本文件八字段的重装版 | 触发边界：用户说「快速做个动画」「简单 demo」时不要甩出万字流程，但**分镜卡照画**。分镜卡的成本是十几分钟，跳过它的成本是整片返工（2026-07-17 B00 实测：跳过画面设计直接写代码，动效全绿、视觉被一票打回）。 与既有文件的关系： - `animation-best-practices.md` 管「怎么动」（节奏、easing、运动语言），本文件管「每一帧长什么样、镜头之间怎么排」，两者正交 - `cinematic-patterns.md` 的 Scene-based 叙事是本文件的前提：先有 scene 划分，才谈每个 scene 的定格帧 - 运镜的实现参数（camera rig、zoom 与 dolly 的区别、镜头缓动）→ `camera-language.md`，本文件只在设计层引用它的词汇 --- ## 1 · 核心立论：每一镜先是一张会动的封面 配图库做了 300+ 张封面后沉淀出一个判断：**一张好封面 = 1 个具象主角 + ≤3 个活跃元素 + 1 条清晰的视线引导**。动画的每一镜，先按这个标准设计成一张静态封面，再让它动起来。 **封面 = 分镜定格**。检验方式极其具体：随机暂停成片的任何一帧，这一帧应该能直接当封面用。过不了封面测试的帧，说明这一镜的构图没设计，只是元素在时间轴上各自运动的叠加。 为什么动画反而更容易违反这条：动画会用「元素是分时出现的」自我辩护，前一个还没退场后一个已经入场，结果每一帧都拥挤。静态封面没有这个借口，所以封面的纪律恰好是动画最缺的纪律（配图库实测核心启发 #1）。 顺序也因此定死：**先摆定格帧，再编排运动**。§6 的 thumbnail pass 就是这个顺序的可执行版本。 --- ## 2 · 定格帧十一律 配图库 S1-S11 规则的动画语境改写。这是本文件的心脏，每一镜的构图设计逐条过。 ### 律一 · 封面测试（S1） 每个 scene 的定格帧必须有：**1 个具象主角 + ≤3 个活跃元素 + 1 个清晰视觉焦点**。 「≤3」是**每一帧的不变量**，不是每个 scene 的总量。新元素入场，旧元素必须退场（淡出、退到后景、blur+dim 都算退场），同屏活跃元素预算恒定。写时间轴时对每个时间点数一遍同屏元素，超了就砍入场或提前退场。 > 自检：随手挑三个时间点暂停，数同屏活跃元素，有没有一帧超过 3？ ### 律二 · zoom 终点必须是具象锚点（S2） push-in / zoom 的终点只能是：品牌 logo、关键数字、UI 里的那个按钮、那行代码、人物表情。**背景纹理、氛围元素、装饰图形不配 zoom**。推近一个没有信息的东西，等于告诉观众「这里其实没什么可看的」。 HuaRec 判例补一刀：**倍率 < 1.25x 的 zoom 不值得做**（视觉变化感知不足，纯属晃动；唯一例外是开场 1.06x 定场微推）。设计分镜时每个 [CAMERA] 推近动作都写明锚点是什么，写不出锚点就删掉这次运镜。 > 自检：这一镜 push-in 的终点能用一个名词说出来吗（那个按钮 / 那个数字 / 那个 logo）？说不出就删运镜。 ### 律三 · 视线与箭头 = 镜头运动脚本（S3） 静态封面里「人物视线朝向主体物、一张图只放一个箭头」的规则，翻译到动画就是：**定格帧里的引导线，就是这一镜的镜头运动指令**。镜头跟着视线走、沿着箭头推、顺着 UI 的阅读方向 pan。 一个 scene 只有 1 条引导线。定格帧里找不到引导线，说明这一镜根本不知道该怎么动。此时不要硬编一个运镜，回去修构图（配图库核心启发 #3）。 > 自检：把定格帧给人看 3 秒，他的视线路径和你计划的镜头运动一致吗？ ### 律四 · 字画分工，两条轨（S4 + 配图库 C 系列） 文字轨和画面轨是两条独立时间轴，分工不重叠： | 规则 | 内容 | 出处 | |---|---|---| | 字扛钩子 | 每镜大字 2-6 字硬上限，主文案 2-4 字最佳；字说钩子，画面扛氛围，不让画面硬演文字 | 配图库 C1/C3 实测 | | 两拍入场 | 大字入场节奏固定两拍：**动作词先砸，定语色块后补**（「实测」满屏砸下，「Claude 4.8」色块随后贴上） | 配图库 C5 | | 字落负空间 | 文字永远落在构图预留的负空间，不压主角、不压焦点 | 配图库 C2 | | 实心强色 | 花字必须实心强色；**空心白字 + 彩色描边绝对禁用** | 配图库 G 禁区 | > 自检：遮掉画面只留字，钩子还在吗；遮掉字只留画面，构图还成立吗？两问都过才算分工干净。 ### 律五 · 百分比空间语言（S5） 分镜卡里的构图描述必须写到百分比粒度：「产品截图右上 60% 带透视、人物左下 25%、大字压截图顶部边缘、距四边 10% 安全区」。 这不是仪式感，是工程接口：**百分比语言直接映射 CSS/GSAP 布局参数**，实现 agent 拿到就能翻译，不需要再做构图决策。写「左边放产品右边放字」这种粒度等于没写（gbro 构图模板对比实测：百分比粒度的 prompt 和模糊描述的产出差一个档次）。 > 自检：这一镜的构图描述里有没有至少 3 个百分比数字？没有就还是文学描述，不是 spec。 ### 律六 · 前中后景 = parallax 三层（S6） 定格帧设计时显式写出前景 / 中景 / 后景各是什么、谁遮挡谁。这个分层就是天然的 parallax 素材：三层三个速度，遮挡关系的变化就是深度感的来源。 实现参数直接抄 shotcraft 判例：视差层速度系数 0.35 / 0.7 / 1.4，**层间速度比 ≥2 倍才可辨**，层数 ≤4。 > 自检：说得出这一帧的前中后景各是什么、谁遮挡谁吗？说不出就还没分层。 ### 律七 · setup → payoff，开场帧摆悬念（S7） 每个 scene 的开场定格帧留一个缺口（未完成的桥、还没揭晓的数字、半屏空白），这一镜的运动负责闭合它。「从 A 到 B」的结构天然就是转场叙事：上一镜的 payoff 可以直接是下一镜的 setup。 反面是「开场帧已经把所有信息摆全，然后元素原地做动效」：那是会动的海报，不是镜头。 > 自检：这一镜的开场帧和结束帧并排放，观众能说出「什么被兑现了」吗？ ### 律八 · 物化 + 过程感选意象（S8） 抽象概念必须物化成可见的实物动作，且**优先挑有过程感的动作**：「连接」= 桥一段段搭起来、「降价」= 价格牌 $89 逐字划掉变 $29、「AI 味重」= 稿纸上 stagger 长满整齐的灰方块。 动作本身就是动画脚本：选对了意象，画面焦点和镜头运动会从意象里自己长出来，不需要另外发明动效。方法是先做费曼式翻译（这个概念怎么「发生」？），翻译完再谈画风（配图库核心启发 #4）。 > 自检：这个意象能用一个动词概括吗（搭、划、长、落）？只能用名词描述的意象没有过程感，换一个。 ### 律九 · 风格 × 构图正交（S9） 配图库最重要的架构认知，原样迁移：**风格皮肤全片定一次**（色板、字体、材质、背景逻辑），**构图模板逐 scene 换**（这一镜居中特写、下一镜三列网格、再下一镜对角双区）。 scene 切换 = 构图切换，绝不是风格切换。全片换风格是灾难，全片一个构图是催眠。与三方向门的衔接：用户选定的方向板就是那张「定一次」的风格皮肤。 > 自检：任取两镜对比，风格（色板 / 字体 / 材质）应该认不出差别，构图应该一眼不同。反过来了就是架构错了。 ### 律十 · 禁区继承（S10） 配图库审美禁区全部继承，且要特别警惕动画的职业病：**发光粒子、数据流、全息 HUD、赛博霓虹是 motion graphics 最顺手的偷懒素材，恰好全在花叔禁区**。做动画时手比做静态图更痒，管住。 科技感的正解 = 真实 UI 截图（3D 悬浮卡片形态）+ 干净大字 + 亮底。深蓝底 #0D1117 + 霓虹 glow 这个组合照旧禁用（细则同 SKILL.md §6.2）。 > 自检：画面里有没有任何元素在「发光」？有就先怀疑自己在用职业病偷懒，逐个论证去留。 ### 律十一 · 3 米测试（S11） 任何一帧暂停，画面里最大的词 3 米外可读。**不因为「反正会动」而缩小字号**——观众看动画时给每帧的注意力比看静图更少，字号只能更大不能更小。这条和 `animation-best-practices.md` §6.5 视觉密度条款互为上下限：密度条款防空旷，3 米测试防拥挤时牺牲可读性。 > 自检：把关键帧截图缩到手机屏大小，最大的词还能读吗？ --- ## 3 · 景别体系：五档 zoom 映射 传统影视的远全中近特五档，在 HTML 动画里对应五个 zoom 档位（档位数值与 `camera-language.md` §4.3 一致，实现细节以它为准）： | 景别 | zoom 档位 | 看什么 | 典型用途 | 出处 | |---|---|---|---|---| | 远景 | 0.78x | 全局 + 环境留白 | 开场 establishing、收尾全家福 | shotcraft 全页机位 0.78 | | 全景 | 1x（定场微推 1.06x） | 完整界面 / 完整场景 | 叙事基准面，多数镜头的家 | HuaRec 定场 1.06x 判例 | | 中景 | 1.3-1.45x | 一个功能区块 | 功能演示的主力景别 | HuaRec 轻推 / 中推档 | | 近景 | 1.8x | 单个组件 / 单条数据 | 强调具体交互 | HuaRec 重推档 | | 特写 | 2.3x（上限） | 律二的具象锚点 | 关键数字、那个按钮、logo | HuaRec 倍率上限 2.3x | 两点说明： - 同一个档位可以用 zoom（scale，无视差）也可以用 dolly（perspective + translateZ，有视差）实现，气质完全不同；两者的选型规则和 camera rig 写法在 `camera-language.md`，分镜层只需要在 [CAMERA] 列写清档位和动机 - 档位是设计词汇不是枷锁：1.5x、2.0x 都合法，档位的作用是让「中景」「特写」这些词在分镜表里有确定的数值含义 ### 相邻镜头的景别节奏 | 规则 | 内容 | 依据 | |---|---|---| | 避免同景别连切 | 相邻两镜同档位，切换没有变化感，读作「画面跳了一下」而不是「换镜头了」；至少差一档 | HuaRec「倍率 <1.25x 不值得拍」推广到镜间 | | 避免两级跳 | 远景直切特写（0.78x → 2.3x）会晕；要跳必须是有意为之的 punch-in，且配转场（白闪 / whip-pan）垫住 | HuaRec 舒适预算 | | 焦点近则并镜 | 相邻两镜焦点距离很近，合并成一镜，联合包围盒重新定档 | HuaRec 镜间语法 | | 焦点中距则平移 | 宁可用低一档的景别一镜平移过去，不做「拉出再推进」的泵动 | HuaRec「改平移」判例 | | 焦点远则弃镜 | 对角横跳的两个焦点，绝不连拍两个 zoom，砍掉一个或插全景过渡 | HuaRec「弃镜」判例 | | 时长随幅度伸缩 | 景别切换的过渡时长不是常数：`duration = 0.55 × |ln(zoomTo/zoomFrom)| / ln2`，clamp [0.30, 0.94]s；固定 duration 是业余感来源 | HuaRec 对数伸缩公式 | | 节奏预算 | 相邻镜头变化间隔 ≥2.6s，任意 15s 窗口内景别变化 ≤4-5 次 | HuaRec 舒适预算 A2 | | 谢幕铁律 | 成片永远以全景 / 远景收尾，结尾前 ≥0.8s 全景停顿；**绝不在推近态戛然而止** | HuaRec 谢幕判例 | --- ## 4 · 能量骨架：先划走 hold 预算，再排动效 多镜头片子（≥10s）的镜头排列不是平均分配，套 shotcraft 的 promo-energy-arc 四段位骨架： | 段位 | 时长占比 | 能量 | 内容 | 硬指标 | |---|---|---|---|---| | ① 开场 | 8-12% | 低 | 品牌 / 主题亮相 | 字标落定 hold ≥1s | | ② 单主角立传 | 12-15% | 低中 · 全片最慢 | 主角一个完整动作弧（入场 → 悬停 → 落位） | 动作弧 ≥3s，质感最高的一段 | | ③ 功能爬升 | 55-65% | 中高 ⇄ 低交替 | 每镜绑一个独特功能，能量高低交替排列 | 每 1-2 个功能镜头后插一张**呼吸字卡**（低能量、大留白、2-6 字） | | ④ 收场 | 13-16% | 全片峰值 | 全家福 + sign-off | 收尾 hold，谢幕回全景（§3 铁律） | **排片纪律：先划走 hold / rest 帧预算，再排动效**（shotcraft 填空流程判例）。具体顺序： 1. 列功能清单，数出镜头数 N 2. 先把不可侵犯的静止时间从总预算里划走：字标 hold ≥1s、批量动效收尾 0.5s 静止、开场动作弧 ≥3s、结尾 ≥0.8s 全景停顿、关键结果前 0.5s 悬停（best-practices §4.4） 3. 剩下的时间才分给动效，能量高低交替排列，不许连续两镜高能 4. 逐接缝选转场（§7），转场帧从相邻镜头的预算里划走，不另外加时 呼吸字卡的构图也有定式：2-6 字大字 + 全屏负空间 + 零装饰，它本身就是一张过封面测试的定格帧（活跃元素 = 1），作用是给功能爬升段降能量、给观众消化时间。别把呼吸字卡做成又一个信息镜头，那等于没插。 与 `animation-best-practices.md` §1 五段叙事的关系：Slow-Fast-Boom-Stop 是**单场 / 短片**（≤15s 一口气）的节奏曲线，promo-energy-arc 是**多镜头片**的骨架；15s 以下二选一即可，20s 以上用能量骨架排镜、每一镜内部再用五段叙事的手感。 --- ## 5 · 轻量分镜卡：本文件的交付物 每镜一行，八个字段一个不能少。shotcraft 的四列表（#|时间|镜头|关键动效）是最低配，这里扩到八列，其中 [CAMERA] 独立成列（launch film 导演稿的 10 字段后续同步扩为 11，新增的就是这个字段）： ``` | # | 时间 | 景别 | [CAMERA] 运镜+动机 | 画面构图（百分比语言） | 关键动效 | 转场到下一镜 | 验收帧号 | ``` 字段写法要求： - **时间**：起止秒 + 隐含时长；转场时间含在本镜预算内，不另列（§4 排片纪律第 4 条） - **景别**：§3 五档之一 + zoom 数值 - **[CAMERA]**：运镜动作 + 一句动机；「静止」也是合法运镜，但要写为什么静止；每个 push-in 必须写锚点（律二） - **画面构图**：百分比语言（律五），含前中后景分层（律六） - **关键动效**：这一镜只讲一个动效（shotcraft「一镜一动效」判例） - **转场到下一镜**：§7 决策表选型，不许留空、不许写「直接切」（裸切要写成有意为之的 hidden-cut 才合法） - **验收帧号**：**每镜预写 1-2 个帧号**，实现完成后就截这几帧自检（shotcraft「每镜三读 + 预写验收帧号」判例）。预写的意义：验收标准在动手前就定死，不给实现后「看起来还行」的模糊空间 ### 示例：12s 产品动画完整分镜表 假想产品：截图整理工具 PicSort。1920×1080 · 30fps · 360 帧。 | # | 时间 | 景别 | [CAMERA] 运镜+动机 | 画面构图（百分比语言） | 关键动效 | 转场到下一镜 | 验收帧号 | |---|---|---|---|---|---|---|---| | 1 | 0-2.0s | 全景 1x | 静止，末 0.3s 轻推至 1.06x · 定场 + 埋悬念 | 桌面乱截图堆占中部 70%，大字「3000 张截图」落顶部 20% 负空间，距四边 10% 安全区；前景 2 张截图微遮挡中景堆 | 截图 30ms stagger 落桌；大字两拍入场（「3000 张」砸下，「截图」色块后补） | 虚焦接力（乱堆 blur 化开） | f30 / f55 | | 2 | 2.0-3.5s | 特写 2.3x | push-in 1x→2.3x · 锚点 = 一张截图右下角的日期角标 | 单张截图占 80% 居中带 2° 透视，日期角标右下 15%；其余截图退后景 blur | 推近同步后景 blur+dim（焦点切换三件套） | 共享元素归位（这张截图缩小飞入下一镜输入框旁） | f85 | | 3 | 3.5-6.0s | 中景 1.4x | 水平 pan 跟随光标 · 引导线 = 光标弧线轨迹 | 产品 UI 占 85% 带透视，logo 左上 10%，搜索框水平居中占 55%；光标从左下 25% 弧线入场 | 打字 3f/字符 + 结果 Chunk Reveal；打完呼吸 0.4s | mask-wipe（结果面板边缘展开成下一镜网格） | f130 / f165 | | 4 | 6.0-8.5s | 全景 1x | pull-out 1.4x→1x · 动机 = 展示整理后的规模 | 分类网格 3 列占 85%，每列头部一条色签；顶部 15% 负空间留给下一镜数字 | 卡片按列 stagger 入列（列间 30ms），满板后静止 0.5s | 流白 | f210 / f250 | | 5 | 8.5-10.5s | 近景 1.8x | 静止 · 关键结果 hold，不抢数字的戏 | 「3000 → 12 类」占中部 60%，动作词最大、定语色块；四周大负空间 | digit-roll 落位（tabular-nums），落定后 hold 0.6s | 共享元素归位（数字缩小上移让位 logo） | f290 | | 6 | 10.5-12s | 全景 1x | 静止 · 谢幕，全景收尾 | logo 居中占 12%，slogan 一行在下方 8%，其余全留白 | logo 形变收束（前元素坍缩 → 展开），末帧 hold ≥1s | 无（片尾） | f330 / f359 | 对照检查这张表能看到骨架：镜 1 是设置悬念的 setup（律七），镜 2-4 是功能爬升的景别交替（特写 → 中 → 全，无同档连切、无两级跳），镜 5 是能量峰值 + hold 预算，镜 6 全景谢幕。每镜同屏活跃元素 ≤3。 --- ## 6 · Thumbnail Pass：动手写正式代码前的灰盒验证 分镜表是文字，thumbnail pass 把它变成看得见的构图验证。成本半小时以内，返工成本的保险。 **Step 1 · 搭灰盒 HTML**：一个临时 HTML，每个关键帧一个 1920×1080 的 `<section>`。只用纯色块 + 文字标签摆构图：主角一个深灰块标「产品UI 85%」、文字区一个色块标「大字：3000张截图」、前景元素浅灰块。不写任何动效、不选字体、不调色，就是把分镜卡的百分比语言变成可见的块。 灰盒阶段禁止调美（选字体、配色、加阴影都不许）：美是方向板已经定掉的事，灰盒只验证构图和节奏。开始调美 = 开始逃避构图问题。 **Step 2 · 只做 3-5 张关键帧**：不是每镜都做，挑能量骨架的关键节点：开场 setup 帧、立传段 hero 帧、爬升段一张代表帧、峰值帧、谢幕帧。 **Step 3 · Playwright 批量截图**： ```bash for i in 1 2 3 4 5; do npx -y playwright screenshot "file://$PWD/thumbnails.html#f$i" \ "thumbs/f$i.png" --viewport-size=1920,1080 done ``` **Step 4 · 验收三问**（对着并排缩略图问）： 1. **盖住所有文字标签，5 张图的构图差异还看得出来吗？** 看不出 = 节奏没做出来，逐 scene 换构图模板没执行（律九；best-practices §1 的 thumbnail 自检同源） 2. **每一张单独过封面测试吗？**（律一：1 主角 + ≤3 元素 + 1 焦点） 3. **每一张的引导线指得出来吗？** 指不出来的那镜回去修构图，不要往下走（律三） **Step 5 · 过了再写正式代码**。灰盒 HTML 留在项目目录里当构图基准，实现跑偏时回来对照。 **与三方向门的关系**：三方向硬门的「方向板」（hero 关键帧真实静帧 + 色板 + 气质句）本质就是**首版 thumbnail**。用户选定方向后，thumbnail pass 是把那一张方向板扩展成整片的关键帧序列：方向板定风格皮肤，thumbnail pass 定逐镜构图，正好是律九的两层正交。 --- ## 7 · 转场决策表：按叙事关系选型 转场不是装饰，是接缝处的叙事逻辑。先判断相邻两镜的**叙事关系**，再选型。转场词汇的实现参数（时长、easing、遮罩写法）见 `camera-language.md` §7 的三层转场词汇。 | 相邻两镜的叙事关系 | 首选转场 | 备选 | 判例依据 | |---|---|---|---| | 时间跳跃（「三天后」「整理完成后」） | 黑场字卡 / 流白 | whip-pan | shotcraft 六式：大落差用白 / 黑垫 | | 空间平移（同一界面的不同区域） | **一镜平移，根本不切** | hidden-cut | HuaRec「中距离改平移」：宁可广一档一镜过去，不做出-进泵动 | | 概念对比（before/after、A vs B） | mask-wipe | 分屏后硬切 + 白闪 | shotcraft mask-wipe 穿窗判例 | | 递进 / 因果（setup 的答案在下一镜） | 共享元素归位（上一镜元素飞成下一镜主角） | morph | shotcraft travel 两式；voiceover-pipeline「hero 跨 scene morph 不切」铁律同源 | | 能量落差大（呼吸字卡 → 高能镜头） | 流白 / 白闪 FlashCut | whip-pan | shotcraft：接缝按能量落差选型 | | 能量落差小（爬升段相邻功能镜） | 虚焦接力 / 交叉淡化 ≥8f | hidden-cut | shotcraft graze-face-tour「段间交叉淡化防黑闪」 | 三条纪律： 1. **一个接缝只用一式**，不叠加（白闪 + whip-pan 一起上是 slop） 2. **转场帧从相邻镜头预算划走**，不凭空加时长；分镜表的时间列已含转场 3. **全片零裸切**。shotcraft 判例原话：公认优秀的发布片全程没有一次裸切。要「切」的效果就用 hidden-cut（借满屏元素 / 白帧 / 运动峰值藏切点），那是设计过的切，不是没设计的切 带解说的片子多一条：**move on pause**（HuaRec 判例）。镜头切换和转场吸附到语音间隙，只提前不推后，上限 0.8s，因为观众在听觉空档移动视线的认知成本最低。走 voiceover-pipeline 时用 timeline.json 的真实间隙定切点。 --- ## 8 · 开工 checklist（分镜完成的定义） 写代码之前，确认以下全部存在： - [ ] 分镜表：每镜一行、八字段齐全，存进项目目录（≥20s 时就是 `导演稿.md` 的核心节） - [ ] 每镜定格帧过了十一律里适用的条目，至少显式检查律一（封面测试）、律三（引导线）、律五（百分比构图） - [ ] 景别列没有同档连切、没有两级跳（§3） - [ ] hold / rest 预算先划走了，呼吸字卡插了（§4） - [ ] 每个接缝的转场选型写在表里，全片零裸切（§7） - [ ] thumbnail pass 的 3-5 张灰盒截图过了验收三问（§6） - [ ] 每镜预写了验收帧号，等实现后逐帧对照（§5） 七项全过，分镜阶段结束，进入实现。实现被打回时先分层定位：动效骨架的问题还是视觉工艺的问题（best-practices §6.5 的修复定式），分镜表本身通常不用重写。 --- *成文：2026-07-23 · 来源：配图库 S1-S11 定格帧规则 + video-shotcraft 能量骨架判例 + HuaRec 运镜预算公理* *姊妹文件：`camera-language.md`（运镜实现层）· `launch-film-director-notes.md`（重装版）* -
tweaks-system.md 8.8 KB
# Tweaks：设计变体实时调参 Tweaks是这个skill里很核心的能力——让用户不改代码就能实时切换variations/调整参数。 **跨 agent 环境适配**：某些 design-agent 原生环境（如 Claude.ai Artifacts）依赖 host 的 postMessage 把 tweak 值回写源码做持久化。本 skill 采用**纯前端 localStorage 方案**——效果一致（刷新保留状态），但持久化发生在浏览器 localStorage 而不是源码文件。这个方案在任何 agent 环境（Claude Code / Codex / Cursor / Trae / etc.）都能工作。 ## 何时加 Tweaks - 用户明确要求"能调参"/"多个版本切换" - 设计有多个variations需要对比时 - 用户没明说，但你主观判断**加几个有启发性的tweaks能帮用户看到可能性** 默认推荐：**每个设计都加2-3个tweaks**（颜色主题/字号/layout变体）即使用户没要求——让用户看到可能性空间是设计服务的一部分。 ## 实现方式（纯前端版） ### 基本结构 ```jsx const TWEAK_DEFAULTS = { "primaryColor": "#D97757", "fontSize": 16, "density": "comfortable", "dark": false }; function useTweaks() { const [tweaks, setTweaks] = React.useState(() => { try { const stored = localStorage.getItem('design-tweaks'); return stored ? { ...TWEAK_DEFAULTS, ...JSON.parse(stored) } : TWEAK_DEFAULTS; } catch { return TWEAK_DEFAULTS; } }); const update = (patch) => { const next = { ...tweaks, ...patch }; setTweaks(next); try { localStorage.setItem('design-tweaks', JSON.stringify(next)); } catch {} }; const reset = () => { setTweaks(TWEAK_DEFAULTS); try { localStorage.removeItem('design-tweaks'); } catch {} }; return { tweaks, update, reset }; } ``` ### Tweaks面板UI 右下角浮动面板。可折叠： ```jsx function TweaksPanel() { const { tweaks, update, reset } = useTweaks(); const [open, setOpen] = React.useState(false); return ( <div style={{ position: 'fixed', bottom: 20, right: 20, zIndex: 9999, }}> {open ? ( <div style={{ background: 'white', border: '1px solid #e5e5e5', borderRadius: 12, padding: 20, boxShadow: '0 10px 40px rgba(0,0,0,0.12)', width: 280, fontFamily: 'system-ui', fontSize: 13, }}> <div style={{ display: 'flex', justifyContent: 'space-between', alignItems: 'center', marginBottom: 16, }}> <strong>Tweaks</strong> <button onClick={() => setOpen(false)} style={{ border: 'none', background: 'none', cursor: 'pointer', fontSize: 16, }}>×</button> </div> {/* 颜色 */} <label style={{ display: 'block', marginBottom: 12 }}> <div style={{ marginBottom: 4, color: '#666' }}>主色</div> <input type="color" value={tweaks.primaryColor} onChange={e => update({ primaryColor: e.target.value })} style={{ width: '100%', height: 32 }} /> </label> {/* 字号slider */} <label style={{ display: 'block', marginBottom: 12 }}> <div style={{ marginBottom: 4, color: '#666' }}>字号 ({tweaks.fontSize}px)</div> <input type="range" min={12} max={24} step={1} value={tweaks.fontSize} onChange={e => update({ fontSize: +e.target.value })} style={{ width: '100%' }} /> </label> {/* 密度选项 */} <label style={{ display: 'block', marginBottom: 12 }}> <div style={{ marginBottom: 4, color: '#666' }}>密度</div> <select value={tweaks.density} onChange={e => update({ density: e.target.value })} style={{ width: '100%', padding: 6 }} > <option value="compact">紧凑</option> <option value="comfortable">舒适</option> <option value="spacious">宽松</option> </select> </label> {/* 暗黑模式toggle */} <label style={{ display: 'flex', alignItems: 'center', gap: 8, marginBottom: 16, }}> <input type="checkbox" checked={tweaks.dark} onChange={e => update({ dark: e.target.checked })} /> <span>暗黑模式</span> </label> <button onClick={reset} style={{ width: '100%', padding: '8px 12px', background: '#f5f5f5', border: 'none', borderRadius: 6, cursor: 'pointer', fontSize: 12, }}>重置</button> </div> ) : ( <button onClick={() => setOpen(true)} style={{ background: '#1A1A1A', color: 'white', border: 'none', borderRadius: 999, padding: '10px 16px', fontSize: 12, cursor: 'pointer', boxShadow: '0 4px 12px rgba(0,0,0,0.15)', }} >⚙ Tweaks</button> )} </div> ); } ``` ### 应用Tweaks 在主组件里用Tweaks： ```jsx function App() { const { tweaks } = useTweaks(); return ( <div style={{ '--primary': tweaks.primaryColor, '--font-size': `${tweaks.fontSize}px`, background: tweaks.dark ? '#0A0A0A' : '#FAFAFA', color: tweaks.dark ? '#FAFAFA' : '#1A1A1A', }}> {/* 你的内容 */} <TweaksPanel /> </div> ); } ``` CSS里用变量： ```css button.cta { background: var(--primary); color: white; font-size: var(--font-size); } ``` ## 典型 Tweak 选项 给不同类型的设计加什么tweaks： ### 通用 - 主色（color picker） - 字号（slider 12-24px） - 字型（select：display font vs body font） - 暗黑模式（toggle） ### 幻灯片deck - 主题（light/dark/brand） - 背景样式（solid/gradient/image） - 字体对比（更装饰 vs 更克制） - 信息密度（minimal/standard/dense） ### 产品原型 - 布局变体（layout A / B / C） - 交互速度（animation speed 0.5x-2x） - 数据量（mock数据条数 5/20/100） - 状态（empty/loading/success/error） ### 动画 - 速度（0.5x-2x） - 循环（once/loop/ping-pong） - Easing（linear/easeOut/spring） ### Landing page - Hero风格（image/gradient/pattern/solid） - CTA文案（几种变体） - 结构（single column / two column / sidebar） ## Tweaks设计原则 ### 1. 有意义的选项，不是折腾人的 每个tweak必须展示**真实的设计选项**。别加那种谁都不会真切换的tweak（比如border-radius 0-50px的slider——用户调完发现所有中间值都丑）。 好的tweak暴露**离散的、有思考的variations**： - "圆角风格"：无圆角 / 微圆角 / 大圆角（三个选项） - 不是："圆角"：0-50px slider ### 2. 少即是多 一个设计的Tweaks面板**最多5-6个**选项。再多就变成"配置页面"，失去了快速探索variations的意义。 ### 3. 默认值是完成设计 Tweaks是**锦上添花**。默认值必须本身就是一个完整、可发布的设计。用户关闭Tweaks面板后看到的就是产出。 ### 4. 合理分组 选项多时分组显示： ``` ---- 视觉 ---- 主色 | 字号 | 暗黑模式 ---- 布局 ---- 密度 | 侧栏位置 ---- 内容 ---- 显示数据量 | 状态 ``` ## 向前兼容源码级持久化 host 如果你以后想把设计上传到支持源码级 tweaks（如 Claude.ai Artifacts）的环境也能跑，保留 **EDITMODE 标记块**： ```jsx const TWEAK_DEFAULTS = /*EDITMODE-BEGIN*/{ "primaryColor": "#D97757", "fontSize": 16, "density": "comfortable", "dark": false }/*EDITMODE-END*/; ``` 标记块在 localStorage 方案里**无作用**（只是个普通注释），但在支持源码回写的 host 里会被读取，实现源码级持久化。加上这个对当前环境无害，同时保持向前兼容。 ## 常见问题 **Tweaks面板挡住设计内容** → 让它可关闭。默认关闭，显示一个小按钮，用户点了才展开。 **用户切换tweaks后还要重复设置** → 已经用localStorage。如果刷新后不持久，检查localStorage是否可用（无痕模式会失败，要catch）。 **多个HTML页面想共享tweaks** → 给localStorage key加project name：`design-tweaks-[projectName]`。 **我想让tweak之间有联动关系** → 在`update`里加逻辑： ```jsx const update = (patch) => { let next = { ...tweaks, ...patch }; // 联动：选dark mode时自动切换字体配色 if (patch.dark === true && !patch.textColor) { next.textColor = '#F0EEE6'; } setTweaks(next); localStorage.setItem(...); }; ``` -
typography.md 17.9 KB
# Typography：排印推理系统 > **这不是字体清单，是配对与排版的推理规则。** `design-styles.md` 已经给了 60 种风格各自的字体名；本文回答的是「为什么这样配」「拿到任意内容怎么推导出字号/行长/字重」。目标：同一个风格标签，落到不同内容上，能推导出不同的排印结果，而不是每次都抄同一套字号。 > > 前置纪律不变：有 design context 先 lift 用户自己的字体（见 `design-context.md`），本文的一切只在「用户没有字体规范」时启用。 ## 0. 排印决策顺序 拿到内容后按这个顺序推，每一步都由上一步决定，不许跳到「直接选个好看的字体」： 1. **内容类型** → 长文阅读 / 数据密集 / 营销大字 / UI 界面，决定音阶比例和正文字号 2. **语言构成** → 纯中文 / 中西混排 / 纯西文，决定 fallback 链写法和行高基准 3. **风格温度**（对齐 `design-styles.md` 的安静/中性/大胆三档）→ 决定字体配对的对比度来源 4. **最后才是字体名** → 从下面第 3 章配对表选，或从风格库对应条目取 为什么：先选字体名的做法，会让「内容是什么」对排印零影响，这正是千人一面的病根。 ## 1. 字号音阶（modular scale） 字号不是拍脑袋，是从正文字号乘一个固定比例逐级推出来的。比例决定页面的「戏剧性」： | 比例 | 名字 | 性格 | 适用 | |------|------|------|------| | 1.2 | 小三度 | 平缓、层级多而不吵 | dashboard、文档站、信息密集 UI | | 1.25 | 大三度 | 通用、安全 | 大多数网页、产品落地页 | | 1.333 | 纯四度 | 标题明显跳出 | editorial 长文、营销页、报告 | | 1.5 | 纯五度 | 戏剧性、层级极少 | 大字报、slides、hero 一屏一句 | **推导规则**：正文定 16-18px（中文正文建议 17-18px，汉字笔画密、同字号比西文显挤），然后按比例上推标题、下推 caption。层级超过 5 档就是失控，砍掉。 | 档位 | 1.25 比例下的参考值 | 用途 | |------|--------------------|------| | caption | 12-13px | 图注、meta 信息、EXIF 式小字 | | small | 14px | 辅助说明、表格 | | body | 16-18px | 正文，一切的基准 | | h3 | ≈1.25x | 小节标题 | | h2 | ≈1.56x | 章节标题 | | h1 | ≈1.95x | 页面标题 | | display | 3x-8x，脱离音阶自由发挥 | hero 巨字，由版面而非音阶决定 | **流式字号写法**（display 档必用，避免大屏死板小屏溢出）： ```css /* clamp(最小值, 首选值, 最大值)：首选值 = 基础rem + 视口系数 */ h1 { font-size: clamp(2rem, 1.2rem + 3.5vw, 4.5rem); } .display { font-size: clamp(3rem, 1rem + 9vw, 9rem); } /* 正文不要 clamp 出大幅波动，16→18 的窄区间即可 */ body { font-size: clamp(1rem, 0.95rem + 0.3vw, 1.125rem); } ``` 为什么 display 脱离音阶：hero 巨字是版面元素不是文本层级，它的尺寸由「占视口几成」决定，用 vw 推导比用音阶推导更合理。 ## 2. 行长与行高 ### 行长（比字体选择更影响可读性） | 语言 | 舒适区 | CSS 实现 | |------|--------|----------| | 西文正文 | 45-75 字符，最佳 66 | `max-width: 65ch` | | 中文正文 | 一行 22-38 字，最佳 28-32 字 | `max-width: 36em`（em 随字号缩放） | | 图注/侧栏 | 更短，中文 15-20 字 | 窄容器天然限制 | 为什么中文更短：汉字是无空格的致密方块字，同宽度下承载的信息量明显高于西文，同样的眼跳次数中文读进更多内容，行太长回行时找不到下一行开头。 ### 行高随行长联动 行高不是常数，是行长的函数。行越长，眼睛回行距离越远，需要更大的行间距当「轨道」： | 场景 | 西文 | 中文 | |------|------|------| | display 大字（1-2 行） | 0.95-1.1 | 1.1-1.25 | | 标题（h1-h3） | 1.1-1.3 | 1.3-1.4 | | 短行正文（<30 字/行） | 1.4-1.5 | 1.6-1.7 | | 长行正文（接近上限） | 1.6 | 1.8-2.0 | 中文全线比西文高 0.2 左右：汉字是满格方块，没有西文小写字母之间的天然空隙，行距不足会糊成一片。 ### text-wrap（2024+ 浏览器都支持了，白拿的排印质量） ```css h1, h2, h3 { text-wrap: balance; } /* 标题多行时各行长度均衡，消灭孤字行 */ p { text-wrap: pretty; } /* 正文消灭行尾孤词（西文效果明显，中文轻微） */ ``` balance 只用于 ≤4 行的标题（算法限制 6 行且有性能成本）；pretty 全局给正文无副作用。 ## 3. 十组开源字体配对（西文） 配对的三种对比度来源，配之前先想清楚用哪种： - **形式对比**：衬线 display x 无衬线 body（最经典，但要 x-height 咬合，否则视觉字号跳） - **同族咬合**：superfamily 同一设计骨架（零风险，代价是平淡） - **时代对比**：古典字形 x 现代字形（谱系差 200 年以上才有张力，差 50 年只显得乱） | # | 配对（display + body） | 配对逻辑 | 温度 | 获取 | |---|------------------------|----------|------|------| | 1 | Newsreader + Geist | 形式对比：屏显优化的过渡衬线，x-height 高、与 Geist 咬合好；**Fraunces 的正牌平替** | 安静 | Google Fonts / Vercel 官方仓库 | | 2 | Source Serif 4 + Source Sans 3 | 同族咬合：Adobe 同设计系统，字高字重节奏完全对齐，报告和文档零翻车 | 安静 | Google Fonts | | 3 | EB Garamond + IBM Plex Sans | 时代对比：16 世纪法国老衬线 x 2017 理性 grotesque，差 400 年的张力；注意 Garamond x-height 低，同行混用需字号补偿（+8% 是经验起点，系统解法用 `font-size-adjust`，见第 4 章） | 安静·文气 | Google Fonts | | 4 | Lora + Hanken Grotesk | 形式对比：Lora 笔刷感衬线中等反差，屏显耐看；Hanken 是 Söhne 气质的开源近亲 | 中性 | Google Fonts | | 5 | Instrument Serif + Geist | 形式对比：只有 400 一档字重，天生 display-only，正文必须交给 sans。⚠️ 正在被 AI 工具用烂的路上，2026 年慎用于「想显得独特」的场合 | 中性 | Google Fonts | | 6 | Schibsted Grotesk + Source Serif 4 | 反转结构：grotesque 当 display、衬线当正文，媒体感；**Space Grotesk 泛滥后的平替**（挪威 Schibsted 报业定制开源，带新闻血统） | 中性 | Google Fonts | | 7 | Bricolage Grotesque + Newsreader | 形式对比：Bricolage 的 ink trap 和不规则细节在大字号才显现，天生 display；配安静衬线正文形成粗野 x 文雅 | 大胆 | Google Fonts | | 8 | Archivo（Expanded/Black）+ Inter | 大字报结构：Archivo 宽体黑重压场，Inter 只当 14-16px 正文工蜂（这是 Inter 的正确用法，见反模式） | 大胆 | Google Fonts | | 9 | Cormorant Garamond + Work Sans | 高反差奢侈感：Cormorant 笔画极细，**必须 ≥40px 才成立**，小字号笔画会断；适合时尚/太空图录风 | 大胆 | Google Fonts | | 10 | Geist Mono / JetBrains Mono + Geist | 等宽当主角：命令行感、工程感；等宽只用于标签/编号/代码，整段正文用等宽是灾难（行长膨胀 30%） | 中性·技术 | Vercel / JetBrains 官方，均 OFL | **已被用烂名单**（AI 生成页面的指纹，用了等于自曝）： | 烂大街 | 为什么烂 | 平替 | |--------|----------|------| | Fraunces 当 display | 2023-2025 所有 AI 设计工具的默认「有品位」选项 | Newsreader、Libre Caslon Text | | Inter 当 display | Inter 是为 UI 小字设计的，大字号下匀质无表情 | Archivo、Anton、Schibsted Grotesk | | Space Grotesk | 「科技感」的偷懒答案，泛滥于加密/AI 落地页 | Schibsted Grotesk、Familjen Grotesk | | Playfair Display | 「优雅」的偷懒答案，婚礼请柬既视感 | Cormorant（更极端）、DM Serif Display（更憨） | ## 4. 中文排印（本文最重的一章） 西文排印有百年成熟工具链，中文没有。AI 设计工具在中文上集体摆烂（默认交给系统字体、直接套西文规则），这里是差异化所在。 ### 4.1 开源/免费商用中文字体地图 | 字体 | 类别 | 气质 | 温度 | 获取 | |------|------|------|------|------| | 思源宋体（Noto Serif SC） | 宋体 | 出版正统、7 字重齐全，Heavy 可当 display | 安静-中性 | Google Fonts，OFL | | 思源黑体（Noto Sans SC） | 黑体 | 中文界的 Inter：可靠、无表情，当默认正文没错但没个性 | 全温度兜底 | Google Fonts，OFL | | 霞鹜文楷 | 楷体 | 手写温度、亲切，适合文艺/教育/个人博客正文与引文 | 安静·暖 | GitHub lxgw/LxgwWenKai，OFL | | 霞鹜新晰黑 | 黑体 | 比思源黑更瘦更透气的屏显黑，正文久读不累 | 安静 | GitHub lxgw/LxgwNeoXiHei | | 得意黑 Smiley Sans | 斜黑体 | **中文世界罕见的原生斜体**，运动感、标题专用；正文用它会晕 | 大胆 | GitHub atelier-anchor/smiley-sans，OFL | | 汇文明朝体 | 旧字形明朝 | 老印刷铅字气、复古出版，适合书封/文化类 display | 中性-大胆·复古 | 猫啃网/GitHub，免费商用 | | 京华老宋体 | 老宋 | 笔画方硬的标题宋，报头感 | 大胆·复古 | 猫啃网，免费商用 | | 源流明体/源样明体 | 明朝体（繁向） | 思源宋改刻，保留传统字形细节，繁体内容首选 | 安静·古典 | GitHub ButTaiwan，OFL | | 未来荧黑 Glow Sans | 几何黑 | 思源黑衍生的现代几何黑，多宽度（Compressed 可做窄长 display） | 中性-大胆·现代 | GitHub welai/glow-sans，OFL | | MiSans / HarmonyOS Sans / OPPO Sans | 厂商 UI 黑 | 比思源黑略有性格的 UI 黑，App 原型合适 | 中性 | 各厂官网，免费商用 | 选型推理：**正文只在宋/黑/楷里选**（其余都是 display 字体，整段用会累）；display 想要个性时才去动得意黑/老宋/明朝体。中文字体一个顶西文十个（单文件 5-15MB），一页最多两个中文字体家族，为加载和统一性两个原因。 ### 4.2 中西混排规则 **fallback 链是第一杠杆**：中文字体自带的西文字符普遍难看（思源黑的拉丁字母呆板），把西文字体放在前面，拉丁字符和数字被它接住，汉字自动落到后面的中文字体： ```css /* 西文在前，中文在后，系统中文兜底，泛型收尾 */ font-family: "Geist", "Noto Sans SC", "PingFang SC", "Microsoft YaHei", sans-serif; /* 衬线同理 */ font-family: "Newsreader", "Noto Serif SC", "Songti SC", serif; ``` 为什么这个顺序：font-family 是逐字符匹配的，西文字体不含 CJK 码位，汉字自然穿透到中文字体。反过来写（中文在前）西文字符全被中文字体吃掉，等于白配。 **字号补偿**：同字号下西文小写视觉偏小（x-height 只占字身一半，汉字占满）。两种解法： ```css /* 解法一：font-size-adjust 让 fallback 字体按 x-height 归一（Chrome 127+/FF/Safari 17+） */ :root { font-size-adjust: from-font; } /* 解法二：选 x-height 高的西文体（Geist/Inter/Source Sans 都高），混排天然齐 */ ``` **baseline 对齐**：中西 baseline 不一致时症状是英文单词在中文行里「下沉」。优先换 x-height 更高的西文体；个别 display 场景用 `vertical-align: -0.02em~-0.06em` 微调西文 span，正文别这么修（维护成本大于收益）。 **数字规则**：数字一律走西文字体（fallback 链已保证），数据表格必须加 `font-variant-numeric: tabular-nums`，否则 1 和 8 宽度不同，列会抖。 **中英之间不加空格**：这是本仓库规范（花叔明确不用盘古之白），靠 fallback 链的字体本身留白，不靠手动敲空格。 ### 4.3 中文没有斜体 中文字形没有 italic 传统，浏览器遇到 `font-style: italic` 会机械倾斜汉字（faux italic），笔画变形、极丑。强调手段替换表： | 西文习惯 | 中文替代 | CSS | |----------|----------|-----| | italic 强调 | 换字重 | `font-weight: 600`（前提：字体真有这档字重） | | italic 书名/引用 | 底色高亮 | `background: linear-gradient(transparent 60%, #FFE9A8 60%)` 荧光笔式 | | italic 引文块 | 换字体 | 引文整段换霞鹜文楷，楷体本身就是中文的「引用语气」 | | italic 专名 | 颜色/着重号 | `text-emphasis: dot`（着重号，中文原生强调，支持度已可用） | 保险丝：`font-synthesis: none;` 全局禁掉合成斜体和合成加粗，宁可不强调也不接受变形字。 ### 4.4 标点规范 | 规则 | 做法 | 为什么 | |------|------|--------| | 引号 | 直角引号「」『』，不用弯引号 "" | 弯引号在中文字体里是全角占位但形状是西文的，视觉漂浮；「」是本仓库硬规范 | | 避头尾 | `line-break: strict;` | 禁止句号逗号出现在行首、开引号出现在行尾，这是中文排版的底线 | | 标点悬挂 | `hanging-punctuation: first allow-end;`（仅 Safari）；跨浏览器用 `text-indent: -0.5em` 处理段首开引号 | 段首的开引号不悬挂会让首行看起来缩进了半格，视觉左边缘不齐 | | 连续标点挤压 | `font-feature-settings: "halt";`（行尾挤压）或 `"palt"`（全比例宽度，需配合 letter-spacing） | 全角标点连排（如「）。」）会出现一个半字宽的空洞，halt 收窄它 | ### 4.5 中文 letter-spacing 区间 | 场景 | 区间 | 为什么 | |------|------|--------| | 正文 | 0 至 0.05em | 微加字距提升透气度；超过 0.05em 词的完形被打散，读速下降 | | 标题（24-48px） | 0 | 汉字方块字距天然均匀，不需要西文式 tracking 调整 | | display 巨字（>60px） | -0.02em 至 0 | 大字号下字面之间的空隙被放大，微收更紧凑；再负就笔画相撞 | | 全大写西文小标签 | 0.08-0.15em | 唯一需要大正字距的场景，且只对西文大写生效 | **中文永远不要用西文那套「display 收 -0.05em」**：汉字是满格设计，负字距直接笔画打架。 ### 4.6 中文 display 大字 中文没有西文那种 Ultra Thin 到 Black 的 display 字体生态，大字的戏剧性要靠推理制造： - **字重对比是主武器**：思源宋 Heavy 900 压 Light 300，同一字体两个极端字重同屏，比换字体更有张力且零加载成本 - **笔画密度决定可用字号下限**：笔画细/反差大的字体（宋体细横、Cormorant 式）只在大字号成立；小于 24px 细笔画开始断笔，正文必须回到黑体/中等笔画 - **反向也成立**：笔画重的字（黑体 Black、老宋）在超大字号下墨量过大，「一」和「灥」墨量差被放大，密度不均的标题考虑换低一档字重 - **竖排是中文独有的 display 武器**：`writing-mode: vertical-rl` 做书脊式标题、诗词、目录，西文做不到；注意竖排里的西文和数字用 `text-orientation: upright` 或 `text-combine-upright: all`（两位数字合体直立） ## 5. 反模式清单 | ❌ 反模式 | 为什么错 | |-----------|----------| | 全场 Inter（display+body 一把梭） | Inter 是 UI 小字工具，当 display 匀质无表情；这是「AI 生成页面」的头号指纹 | | 中文交给 `sans-serif` 系统默认 | Windows 落到中易宋体/雅黑、macOS 落到苹方，同一页面跨设备完全两张脸，等于没做设计 | | faux italic / faux bold | 浏览器合成变形：斜体扭曲汉字，合成加粗把笔画糊成墨团；用 `font-synthesis: none` 断根 | | 大标题字距过松 | 西文 display 需要收紧（大字号空隙被放大），AI 常反着来加 +0.05em，标题松垮像临时占位 | | 行长失控（无 max-width） | 大屏上一行 60 个汉字，读者回行必迷路；可读性问题里行长失控排第一，比字体选错伤害大 | | 字号档位 >6 档 | 层级贬值，读者分不清什么重要；音阶的意义就是强制克制 | | 只有 400/700 两档字重 | 层级全靠字号撑，页面平；variable font 时代 300-900 都是免费的表达维度 | | 表格/数据不用 tabular-nums | 数字宽度不等，列左右抖动，数据可信感直接打折 | | 中文正文用 display 字体（得意黑/老宋整段排） | display 字体的个性在正文里变成阅读阻力，200 字后就累 | | 中西混排中文字体放 fallback 链最前 | 拉丁字符全被中文字体自带的难看西文吃掉，配好的西文体永远轮不到出场 | ## 6. CSS 实现要点 ```css :root { /* 1. fallback 链：西文 → 中文 → 系统中文 → 泛型（顺序即规则，见 4.2） */ --font-body: "Geist", "Noto Sans SC", "PingFang SC", "Microsoft YaHei", sans-serif; --font-display: "Newsreader", "Noto Serif SC", "Songti SC", serif; /* 2. 禁合成：不接受浏览器伪造的斜体/加粗（中文场景必开） */ font-synthesis: none; /* 3. 中文断行底线 */ line-break: strict; /* 避头尾 */ overflow-wrap: break-word; /* 长 URL/英文串不撑破容器 */ } body { font-family: var(--font-body); font-size: 17px; /* 中文正文基准，见第 1 章 */ line-height: 1.8; /* 中文行高基准，见第 2 章 */ /* 正文开启标准连字，关闭花哨特性 */ font-feature-settings: "liga" 1, "calt" 1; } /* 数据场景：等宽数字 + 斜杠零（0 和 O 不混淆） */ .data, table { font-variant-numeric: tabular-nums slashed-zero; } /* 西文小标签：全大写 + 大字距的唯一合法场景 */ .label { text-transform: uppercase; letter-spacing: 0.1em; font-size: 12px; } /* 标点挤压：中文 display 大字里全角标点的空洞收窄 */ .display-cjk { font-feature-settings: "halt" 1; } ``` **中文字体加载**（单文件 5-15MB，直接引全量会毁掉首屏）： - 首选 Google Fonts 的 Noto SC 系（已按 unicode-range 自动切成上百个分片，浏览器只下用到的字） - self-host 个性字体（霞鹜/得意黑等）必须先子集化：`cn-font-split` 或 fonttools 的 `pyftsubset`，正文字体按常用 3500 字切，display 字体按实际出现的字符切（一张海报往往只有 20 个字，子集能压到 50KB 以内） - `font-display: swap` 保底，中文字体下载慢，白屏等字体是最差体验 -
ui-demo-animation.md 28.4 KB
# 产品UI展示动画 Playbook > **这是「宣传的产品有UI界面」时的单一入口。** 商单、发布动画、功能演示，只要画面主角是一个界面，先读这份文件再动手。 > > 核心主张一句话：**产品动画的质感最大来源是「真实UI + 电影运镜」，不是特效。** 科技感靠让观众认出「这就是那个产品」，靠镜头怎么看它，而不是靠粒子、辉光、赛博渐变。一张真实截图配一次克制的推近，胜过十层手搓的假界面。 > > 参数出处标注约定：（shotcraft·卡名）= video-shotcraft 镜头卡实测值；（huarec）= 花录 Studio 运镜导演系统；（best-practices §x）（gsap-recipes §x）= 本 skill 既有 reference。30fps 语境，1f ≈ 33ms。 > > 分工：本文件管「UI 这个主角怎么演」；镜头词汇与运镜动机见 `camera-language.md`；元素级运动语法（easing、stagger、FLIP、Chunk Reveal）见 `animation-best-practices.md`，本文只引用不复写。 --- ## §0 两条公理（凌驾于八式所有参数） | 公理 | 内容 | 出处 | |---|---|---| | **可见性不变量** | 任意时刻，光标与正在发生的 UI 操作必须在可视区内（含 8% 安全边距）。违反的镜头宁可降倍率、并镜或不拍 | huarec A1 | | **视觉语言从产品生长** | 先提取产品自己的设计 tokens（字体/圆角/色板/栅格），全片只准复用或克制扩展。镜头卡只继承运动语法和节奏，皮肤按目标产品重蒙 | shotcraft 公理 1 | --- ## §1 决策树：真实UI截图运镜 vs HTML重建UI 这是本文件里**最影响工作量的一个决策**，两条路差一个量级。默认从最省的路径开始判断： ``` 产品UI要出场 │ ├─ 界面只需要「被看」（推近/巡览/悬浮/对比）？ │ └─ 是 → 【路径一】截图装frame + 2.5D运镜。到此为止，别重建 │ ├─ 只有少数几个元素需要单独动（一张卡浮起、一行数据滚动）？ │ └─ 是 → 【路径三】混合：截图当底 + 关键元素切片重建 │ └─ 界面本身是叙事主体，元素要逐个登场/响应操作/改状态？ └─ 是 → 【路径二】HTML重建。走 build-up 八式② ``` | 路径 | 做法 | 工作量 | 适用判据 | |---|---|---|---| | 一 · 截图运镜 | 真实截图放进 `browser_window.jsx` / `macos_window.jsx` 设备框，容器上做 zoom/rotate/pan | 小时级 | 界面是「被观看的对象」；观众不需要看到界面内部产生变化 | | 二 · HTML重建 | 按截图逐像素重建可动的 DOM 结构 | 天级 | 元素需要独立时间轴：逐步生成、typing、状态切换、hover 响应 | | 三 · 混合 | 全页截图当底层纹理，要动的元素抠成透明底切片叠在原坐标上动 | 半天级 | 90% 画面静态、10% 元素要活。**多数商单的正确答案** | **混合策略的关键**：切片元素动完必须归位到截图上的真实槽位。目标卡若悬浮在网格上方不落回布局，观众立刻读出「假」（shotcraft·type-and-filter，Q9 判例曾因此近乎整文件重写）。 混合路径的五步操作： 1. 全页 2x 截图铺底，装进设备框（网页产品用 `browser_window.jsx`，桌面 App 用 `macos_window.jsx`） 2. 要动的元素按 layout.json 坐标抠成透明底切片 3. 截图底层在切片原位铺「页面底色补丁」盖掉烤入的原元素（spotlight-hero-card 的原位补丁手法：卡起飞后原位铺底色补丁 + 强调色呼吸描边，落地瞬间增亮消失） 4. 切片叠在补丁上做动画，终点回到 layout.json 槽位 5. 特写推进段用 4x 高清切片 6f 交叉淡入盖住低倍纹理（shotcraft·PageCam 配套技法） **设备框选择**：框是「这是真软件」的语境信号，裸截图悬在画布上像贴图。但框也吃掉画面面积，特写推进到 zoom 2x 以上时框已出画，此时可直接用无框切片。 ### 素材三件套（走路径一/三之前先采齐） shotcraft pipeline 阶段 1 的标准采集物（shotcraft·六阶段 pipeline）： | 素材 | 规格 | 用途 | |---|---|---| | 全页 2x 截图 | 设备像素比 2 起，长页整页截 | 底层纹理；推近后不糊的下限 | | 元素透明底切片 | 要单独动的元素逐个抠出，4x 更佳 | 混合路径的「演员」；特写推进期 6f 交叉淡入盖住低倍纹理 | | layout.json 坐标表 | 每个切片在全页坐标系里的 `{x,y,w,h}` | 动完归位的「真实槽位」依据；标注/高亮框的定位锚 | 截图来源走 `brand-asset-protocol.md` 的 UI 截图采集协议（App Store 截图、官网 screenshots、演示视频截帧、用户账号实截），质量门槛同样适用「5-10-2-8」。推近特写下文字发糊的根治办法（CSS `zoom` 布局级缩放替代 transform scale）见 `camera-language.md`。 --- ## §2 UI展示八式 · 总览 | # | 式 | 一句话 | 路径 | 来源卡 | |---|---|---|---|---| | ① | 3D展示台 / hero特写 | 一张卡立成全片主角：聚光→推近→悬浮→归位 | 一/三 | spotlight-hero-card | | ② | 界面逐步生成 build-up | 界面从无到有：骨架→内容→数据，登场即叙事 | 二 | skeleton-reveal / row-embed / document-typewriter-reveal | | ③ | 用户 typing 模拟 | 真人手速打字，光标常亮转闪烁 | 二/三 | type-and-filter | | ④ | 光标操作叙事 | 光标当演员：弧线移动、点击 ripple、hover 联动 | 全部 | type-and-filter / collab-cursor-moves | | ⑤ | UI状态转场时间轴化 | tab/modal/路由切换写成时间轴上的一段戏 | 二 | command-palette-summon | | ⑥ | 界面3D巡览 | 长界面斜置滑过，或镜头贴脸游览 | 一 | steep-tilt-glide / graze-face-tour | | ⑦ | 长页滚动叙事 | 长页快滚急刹，停在目标行 | 一/三 | scroll-brake-moves | | ⑧ | feature callout 标注 | 标注线生长、高亮框、说明卡、before/after 对比 | 全部 | before-after-slider-scrub 等 | 选型纪律：**一个镜头只讲一式，一式全片只当一次主角**（shotcraft 公理 5）。八式可以在一支片子里出现多式，但各占各的镜头。 --- ## §3 八式详解 ### ① 3D展示台 / hero特写 把一个核心对象（卡片/面板/模块）立成产品的原子单位。质感最高、节奏最慢的一镜，适合放在开场后的「单主角立传」段。 | 参数 | 典型值 | 调节手感 | |---|---|---| | 相机机位 | rotY 34° 主导 + rotX 仅 8°，perspective 1200px | 侧拍优于俯拍，「从左侧拍摄而不是从下方」；rotX 一大就变成看桌面 | | 推进 | 全页 zoom 0.78 静止一拍，再 16f 推进到 zoom 2.6 | 推进前的静止是「让观众先看到全局」；直接开推没有空间感 | | 动作弧 | rise 10f（`cubic-bezier(0.2,1.25,0.3,1)` 过冲）→ 悬停 54f（sin bob 振幅 4px 周期 40f，translateZ 110px）→ reseat 18f 落地 press scale 0.997 | 锁定到落地约 3.3s，质感镜头就要慢到这个量级；初版几乎总是偏快 | | 轮廓光束 | SVG rounded-rect 描边跑两圈：第一圈 14f 快而亮，第二圈 20f 慢而弱（opacity 0.62） | 两圈快慢有别才读作「持续扫描」，一圈是眨眼；光束全片只给主角一次 | | 双层影 | `0 8·lift px …, 0 46·lift px 90·lift px` 随悬浮高度生长 | 影子不随高度长，悬浮就不成立 | | 聚光灯引导 | 游走光经 4 个中间站锁定卡心，光池半径 620→420→360 收拢，锁定瞬间 +6% 脉冲；外部 vignette 0.16→0.42 压暗 | 中间站让「随机照射」可信，直奔目标读作程序化；vignette 是聚光灯的另一半 | | 悬空注记（可选） | 卡侧浮现两行衬线注记，translateZ 92px + bob 周期 44f（与卡 40f 相近但不同步） | 「共感」而非镜像同步；注记必须活在同一 3D 空间同一台相机透视，平面叠字会破坏空间统一 | （以上全部 shotcraft·spotlight-hero-card 实测值） 已知坑：收尾禁「zoom 2.6→2.58」一类尾漂，呼吸必须是真静止；开场多卡群舞撑不起第一印象，直接从单主角+完整动作弧起稿；逐卡 glint 被判例两次否决，光效严格只给主角。 搭配运镜：dolly-in 推近 + 锁定后静止 hold（见 `camera-language.md`）。倍率跨度大于 2x 时长按对数伸缩，禁弹簧过冲（huarec）。 ### ② 界面逐步生成 build-up 界面「从无到有」的登场叙事。**build 顺序有语法**：chrome（窗口框/标题栏）→ 骨架（灰条占位）→ 内容块 stagger → 数据（数字/图表最后活）。观众对 skeleton screen 有免费预期，灰条一出现就知道内容要来。 三张来源卡按对象分工：**一个界面**逐级变真用 skeleton-reveal；**一组行/卡片**嵌入列表用 row-embed；**一份文档**被写出来用 document-typewriter-reveal。 | 参数 | 典型值 | 调节手感 | |---|---|---| | 三级显影 | 涂鸦（每 5f 换种子「煮沸」）→ 换真一拍 8f 加速缩退 + 骨架 spring 弹入 → 骨架行错峰 6f 滚入 → 显影行错峰 13f、行内 12f | 换真一拍必须快而果断，拖长成 crossfade「跃迁」就没了；三级布局必须严格同构，错位读作换了个页面 | | 逐词进场 | 2.5f/词 上浮 14px；末行末词 +14f 晚半拍 | 晚半拍是「加载完成」的句号；全部齐落平淡 | | 行嵌入 | 第 i 行 cue = 12 + i·9，飞行 12f；`perspective(900px) translateY(−120·air) rotateX(16°·air)` | **rotateX 收平是「嵌入」的关键读感**，纯 translateY 只是「落下」 | | 嵌入强调缝 | 底边 2px 强调色缝从中心 5f 展开、8f 淡出 | 给每次嵌入一个确认点，但要淡得快 | | 文档逐块 | 第 g 块 cue = 6 + g·3.5，每块 wipe 8f；强调色 caret 只跟最新块 | **「块数×节拍先对预算」是核心算术**，块多了先砍块不加速；「永远只有一个笔尖」，两个 caret 同时闪就是两个作者 | （skeleton-reveal / row-embed / document-typewriter-reveal 三卡实测值） 已知坑：真内容层贴产品截图时，骨架灰条行高与槽位要按截图量，别按想象排；涂鸦级别不画细节，太像 UI 第一级和第二级就没差了；mock 文案不出现客户/成员真名。 搭配运镜：显影段配 1→1.34 缓推（给「凑近看清」的视线动机）；build 全程别加镜头横移，界面在变的时候镜头要稳（huarec：全屏级变化不推）。 ### ③ 用户 typing 模拟 模拟真人在输入框/终端打字。与已有的 **Chunk Reveal（AI 流式输出）是两回事**：AI 输出是不规律 chunk 涌现（best-practices §4.5、gsap-recipes §3.4，那套继续用，不在这里复写）；用户输入是逐字符、匀稳、带犹豫的人手节奏。写错场景是高频事故：把用户打字做成 chunk 会读作「输入框自己在生成」。 | 参数 | 典型值 | 调节手感 | |---|---|---| | 打字速度 | 正文 3f/字符；终端 2f/字符；装饰性小字 0.7f/字符 | 「初版嫌快返工后的定稿值」；交互演示按真人操作速度，这是判例级铁律 | | 光标状态机 | 打字时**常亮**，打完转 8f 周期闪烁 | 打字中闪烁读作卡顿；常亮→闪烁的切换本身就是「打完了」的信号 | | 退格修正 | 偶发一次：多打 1-2 字符，停 4-6f，退格，再打对 | 「人会打错」是最便宜的真实感；但必须预写进脚本（帧确定性），不是运行时随机 | | 确认停顿 | 打完到页面响应留 11f（0.37s）呼吸 | 打完立刻响应读作机器自动，观众跟不上因果 | | 代码打字 | 终端 2f/字符；语法高亮随打字渐进上色（当前 token 打完即着色），不是打完整段再统一变色 | 统一变色是「粘贴」不是「写代码」；高亮延迟半个 token 内观众无感 | | 截图上打字 | 底色补丁盖掉截图里烤入的 placeholder（保留图标），文字层叠上去打 | 直接叠字会和烤入的 placeholder 重影 | （shotcraft·type-and-filter 实测值） 退格修正的确定性写法（预写脚本，不是运行时抽签）： ```js // 把「打错→停→退→改」编译成字符事件表，时间轴只是回放 const script = typeScript("nano-lab", { perChar: 3 / 30, // 3f/字符 typo: { at: 5, wrong: "0", pauseF: 5 } // 第5字符处打错一个"0"，停5f再退 }); // script = [{t:0, text:"n"}, {t:0.1, text:"na"}, ... {t, text:"nano-0"}, // {t+0.17, text:"nano-"}, {t+0.27, text:"nano-l"}, ...] // 渲染层按 t 查表取 text，双向 seek 安全 ``` 搭配运镜：打字前相机先上移/推近到输入框（先给镜头再动手，可见性公理）；打字期间镜头锁死。 ### ④ 光标操作叙事 光标是 UI 演示里唯一的「人」。组件用 `assets/cursor.jsx`（CursorSprite / ClickRipple / hover 联动 hook，两种时钟驱动，API 见该文件头注释）。 轨迹算法不在此复写：贝塞尔弧线 + 收敛手抖见 best-practices §3.5，GSAP proxy 写法见 gsap-recipes §3.5。本式补齐的是**点击与联动的参数**： | 参数 | 典型值 | 调节手感 | |---|---|---| | 双圈 ripple | 两圈同心，**起点差 3f**，半径 14→54 / 14→78px | 单圈太轻看不见；差 3f 是「一次点击的涟漪」，差多了像点了两下 | | 扩散/消散解耦 | 扩散 out-cubic 22f，消散线性 26f | 扩散要冲、消散要匀；同一条曲线管两件事会「闪一下就没」。紧凑场景可压到各 10f（type-and-filter 用的就是压缩版） | | 点击预备 | 光标 scale 0.85（power1.in 约 3f）→ back.out 回弹 | Anticipation 让点击有「按下去」的重量（gsap-recipes §3.5 同款） | | hover 联动 | 光标进入目标区，目标同帧亮起（brightness +6% 或 hairline 描边浮现），光标离开即撤 | 目标不响应，光标就只是贴图；联动窗口按轨迹进度声明，不做运行时命中检测 | | 光标角色分工 | 操作光标（点击有 payload）vs 表演光标（位移即剧情，具名协作光标双人舞/群演） | 光标要点东西时用本式；纯叙事的协作光标是另一场戏（shotcraft·collab-cursor-moves），同片可共存但别混 | 表演光标两式速查（协作/多人主题时用，参数出自 collab-cursor-moves）： | 式 | 机制 | 关键参数 | |---|---|---| | dialogue-duet 双人舞 | 蓝/绿两枚具名光标靠近对话、上下分弧绕位交换（R≈270px）、名牌一亮一暗灯光交接、绿光标 easeIn 放大数十倍成转场遮挡 | 全部三次贝塞尔位移，无 linear；两枚同弧同向会有相撞感，上下分弧是「礼让」 | | cast-ensemble 群演 | 5 枚彩色光标 delay 0/5/9/13/17f 错峰 spring 飞入，双频正弦漂移驻场（0.055/0.021 rad/f、幅度 ±46/30px），一枚打字 cameo | 名牌晚 12f 淡入才是「人到了自报家门」；聚拢后漂移衰减到 25% 保留，完全静止的光标群读作死机 | 已知坑：光标移动全程必须遵守可见性公理，目标在画面外就先动镜头再动光标；协作光标的名牌颜色=身份编码，全片一致，中途换色观众以为换了人；漂移光标永远不许盖住正在阅读的主内容。 搭配运镜：点击确认后相机 16f 推进（zoom≈2.2）穿透进详情页，是「点击→进入」的标准交棒（type-and-filter）；转场接法见 `camera-language.md`。 ### ⑤ UI状态转场时间轴化 tab 切换、modal 弹出、页面路由推入。**时间轴驱动的重放和可交互原型是两种代码形态**，从原型改渲染稿时逐项翻译： | | 可交互原型 | 时间轴重放（渲染用） | |---|---|---| | 触发 | `addEventListener('click')` | timeline 上的 label / position 参数 | | 状态切换 | `classList.add` + CSS transition | 显式 tween（gsap-recipes §6.1 禁区规则） | | 打开/关闭 | `display: none` 切换 | `autoAlpha` tween | | hover | `:hover` 伪类 | 按轨迹进度声明的联动窗口（八式④） | | 随机 | `Math.random()` | mulberry32 种子预生成（gsap-recipes §6.4） | 改稿后 `grep "addEventListener\|classList\|transition:"` 逐条清零。状态必须是时间的纯函数，preview 里看着正常、渲染才穿帮的 bug 全部源于此。 | 参数 | 典型值 | 调节手感 | |---|---|---| | modal / 命令面板 | 背景 10f 压暗至 rgba(20,20,20,0.45) + blur 10px；面板 −20px→过冲 +8px（9f）→落回（6f）；候选行错峰 i·4f | 背景不压暗，面板就没有「浮在上面」；过冲量 8px 是「轻落」，再大变玩具 | | tab 切换 | 指示条用 FLIP 滑移（best-practices §4.1），旧内容 5f 淡出下沉 8px，新内容 8f 淡入上浮 | 指示条和内容不同步是廉价感来源：条先走、内容跟半拍 | | 路由推入 | 新页从右侧整页推入 12-16f，旧页同向退 30% 距离 + 变暗 | 旧页退小距离（视差）比等距推读感深；等距是「传送带」 | （modal 参数为 shotcraft·command-palette-summon 实测值） 已知坑：状态转场是「一镜一动效」的重灾区，一次转场里 tab 又切、toast 又弹、数据又滚，观众什么都没看清；一镜只演一次状态变化。 搭配运镜：状态切换瞬间镜头必须静止，切完再动（huarec 镜间语法：变化是注意力消费，别和镜头运动叠加消费）。 ### ⑥ 界面3D巡览 展示一个长界面/多屏界面的「空间感」镜头。双卡分工明确，选错卡是这一式的主要事故： | 卡 | 机制 | 适用 | |---|---|---| | steep-tilt-glide | **镜头静、页面动**：页面斜置 rotateY −60°，自己匀速滑过画面 | 页面当「展品」列队走过；内容不需要读清，看的是体量和质感 | | graze-face-tour | **镜头动、页面静**：页面群悬浮定住，镜头贴脸游览 | 要在巡览中看清局部内容；镜头有「参观者」人格 | | 参数 | 典型值 | 调节手感 | |---|---|---| | 斜置角 | rotateY −60°，实战裁决区 55-65° | −45° 被判「不够斜」，>−70° 内容读不清 | | 悬浮高度 | 120-180px（graze-face-tour） | 低了贴地没有「陈列」感，高了影子断联 | | 群体错峰 | 错开起点但下落重叠并行 | 完全顺序落是「排队打卡」，重叠才是「一批到场」 | | 段间衔接 | 交叉淡化 ≥8f | 硬切会黑闪；巡览是连续空间，不许跳切 | （shotcraft·steep-tilt-glide / graze-face-tour 实测值） 多页同屏陈列的第三变体（shotcraft·page-waterfall-wall）：3 列页面瀑布墙，rotateX 20° + perspective 1000px，相邻列 loop 周期差 ≥25%（如 12/9/14s）且中列反向。适合收场段「产品有很多页面」的体量陈述，内容不需要读清。周期差小于 25% 时三列会周期性对齐，「墙」瞬间变成「表格」。 已知坑：两卡机制不可混用，页面和镜头同时动，观众失去参照系（晕）；巡览用的页面纹理必须 2x 起，斜置放大后糊得最快。 搭配运镜：这一式本身就是运镜主角，前后镜头要静（能量交替）；镜头路径与 orbit 词汇见 `camera-language.md`。 ### ⑦ 长页滚动叙事 长落地页/文档/时间线的「快滚急刹」。滚动本身不是内容，**刹车点才是**。 | 参数 | 典型值 | 调节手感 | |---|---|---| | 刹车曲线 | `Easing.out(Easing.exp)` 一条曲线 50f 走完全程 | 分段减速会「泵」；一条 expo 曲线天然是「猛滚渐停」 | | 运动模糊 | blur 由帧间位移差分驱动，速度大糊、停即锐 | 恒定 blur 是「镜头脏了」；只在动的瞬间有模糊，静止帧永远锐利（huarec 同款结论） | | 目标行强调 | 停位后目标行 scale 1.03，其余退暗 0.38 | 退暗别到 0，上下文要在；1.03 是「呼吸」不是「弹出」 | （shotcraft·scroll-brake-moves 实测值） 多刹车点的预算管理（huarec 舒适预算，直接搬）：相邻两次「滚动+刹车」间隔 ≥2.6-3.0s；任意 15s 窗口内 ≤4-5 次；每个刹车点停留 ≥1.2s 再开滚。刹车点是注意力消费，比滚动本身贵。 已知坑：滚动期间禁推近，「滚动时推近会晕」（huarec：全屏级变化不推镜头）；刹车点没有内容强调（目标行不抬升、其余不退暗）时，观众不知道为什么停在这。 搭配运镜：急刹后可接一次轻推近（1.3x 档）进目标行，但必须在完全停稳之后；档位表见 `camera-language.md`。 ### ⑧ feature callout 标注 在真实截图上「指给观众看」。四个子配方，共同原则：**标注是导览员，不是界面的一部分**，风格上要和产品 UI 拉开一层（衬线字/手写感/强调色）。 | 子配方 | 参数 | 调节手感 | |---|---|---| | 标注线生长 | SVG 路径 stroke-dashoffset 描线，12-18f，out-cubic；先线后字，字在线到达后 5f 淡入 | 线字同出读作贴纸；线是「手指划过去」的时间 | | 高亮框 | 目标区 rounded-rect 描边 8f 展开 + 框外压暗 0.3 | 只描边不压暗，视线不聚；压暗超过 0.5 变审讯灯 | | 放大镜 | 圆形 loupe 内嵌 2-3x 高清切片（不是 CSS 放大截图底），描边 2px + 软影，8f overshoot 弹出，跟随目标 10-14f 缓移 | loupe 里必须是高分辨率切片，放大糊纹理等于自曝素材差；一镜最多一只 loupe | | 连线说明卡 | 说明卡浮在 3D 空间里，translateZ 90px 量级 + bob 周期与主体相近但不同步 | 同一 3D 空间同一台相机；平面叠字被判例否决（spotlight-hero-card 悬空注记同款约束） | | before/after slider | 快甩 12f（out-cubic 8%→76% 过冲回弹到 70%）→ 停 18f → 慢扫 48f 到 40% 定格；速度比 5:1；after 层 clip-path 跟杆；手柄速度差分驱动 scaleX 微拉伸峰值 1.18 | 速度比 <3:1 节奏对比不可感；快甩宣告「变了」，慢扫证明「变在哪」；慢扫停 40% 让 after 留在定格里 | （slider 为 shotcraft·before-after-slider-scrub 实测值） 已知坑：before/after 两版必须同布局同机位，否则读作两个页面；before 用真实旧态（注入旧数据/关闭功能），不手搓「故意丑」的假 before；角标放内容区，别压侧栏头像。 搭配运镜：标注出现前镜头先推到 1.3-1.45x 档让目标区占屏（huarec：内容占可视区 80%），标注期间镜头锁死。 --- ## §3.9 八式在全片能量骨架里的落位 单式只是镜头，成片要按 promo-energy-arc 四段位排（shotcraft·导演层三件套；分镜纪律「hold/rest 帧预算先划走再排动效」同样适用）： | 能量段 | 时长占比 | 放哪几式 | 理由 | |---|---|---|---| | ① 品牌开场 | 8-12% | 不放 UI 式 | 字标 hold ≥1s，UI 别抢开场 | | ② 单主角立传 | 12-15% | ①hero特写 或 ②build-up | 质感最高节奏最慢的一镜，全片只有一个位置 | | ③ 功能爬升 | 55-65% | ③④⑤⑦⑧ 交替，每镜绑一个独特功能 | 中高低能量交替；⑧callout 是低能量呼吸位的好填充 | | ④ 发布会收场 | 13-16% | ⑥3D巡览（全家福变体） | 全片能量峰值，多屏同框陈列后 sign-off | 声音钩子速查（画面锁定后才做，钉帧写相对表达式，shotcraft 阶段 5）： | 式 | 钉什么音 | |---|---| | ① hero特写 | 弹起 whoosh-big、光束 sparkle、reseat 一声 snap，三动作三专属音 | | ② build-up | 换真一拍 pop，逐行显影各一声极轻 tick，末词晚半拍处轻 chime 收束 | | ③ typing | keyboard 音与打字段严格等长（按字符数截）；不足截、超长裁 | | ④ 点击 | click 是全片最响的一声（响度分层的顶），ripple 无声 | | ⑤ 状态转场 | modal 弹出一声柔 pop，路由推入一声 whoosh-fast | | ⑥⑦ 巡览/滚动 | 匀速段无声或极轻 hum，急刹一声闷 thud | | ⑧ callout | 标注线生长配极轻 draw 摩擦音；slider 快甩 whoosh + 回弹 tick，慢扫无声 | --- ## §4 节奏铁律（从 shotcraft 判例继承，UI 演示专用） 1. **交互演示按真人操作速度走。** 打字 3f/字符、点击前有移动、响应前有呼吸。交互镜头的第一版几乎总是偏快，起稿就按人速（判例 R3，type-and-filter 因此返工）。 2. **批量动效收尾 0.5s 静止。** 网格收敛完、列表嵌完、面板落完，满板静止半秒再走下一镜。 3. **退场必须错峰。** 非目标元素按阅读序 0.4f 间隔错峰淡出，「同时消失读作页面崩溃」，哪怕只差 0.4f 也够（type-and-filter）。 4. **一镜一动效。** 一个镜头只讲一个 UI 行为；同屏两个动效在抢戏，观众两个都没看见。 5. **收尾真静止。** 呼吸位、hold 帧里禁任何尾漂（zoom 微变、opacity 微调都算）；「静」是设计出来的一拍，不是没排到动作。 --- ## §5 与三方向门 / 资产协议的衔接 **三方向板怎么出**：产品 UI 动画的三方向不是三套视觉皮肤，而是**同一份 UI 素材的三种镜头叙事诠释**。素材三件套采集一次，三个方向复用。例如同一张产品截图：方向 A 走八式①（单主角 hero 特写立传）、方向 B 走八式②（build-up 从无到有讲生成能力）、方向 C 走八式⑥+⑦（巡览+滚动叙事讲体量）。方向板各附 2-3 帧关键帧 thumbnail，让花叔选的是「怎么讲这个界面」，不是「哪张图好看」。三方向门是 100% 硬门，指定风格也不豁免（SKILL.md 既有规则）。 **UI 截图取材走 `brand-asset-protocol.md`**：数字产品的 UI 截图在该协议里就是一等公民资产（识别度贡献极高），采集渠道、5-10-2-8 质量门槛、brand-spec.md 固化全部照走。本文件的增量只有一条：采集时按 §1 的素材三件套规格执行（2x 全页 + 透明底切片 + layout.json），一次采齐，运镜和重建两条路径都够用。 **禁手搓假 UI**：找不到真实截图时按协议兜底（向用户索取实截 / 官方演示视频截帧），不用 mockup 生成器凑，不用 CSS 画一个「像那么回事」的界面。我们在表达的是这个产品，不是「一个产品」。 **例外只有一个**：走了路径二 HTML 重建时，重建稿本身就是「以真实截图为基准的复刻」，必须对照截图逐区块校（字体、圆角、间距、图标都从截图量），重建完成后与截图并排截帧对比。重建出一个「大概像」的界面，比直接用截图更伤，观众对自己天天用的产品界面误差极敏感。 --- ## §6 交付前自检（UI 演示专项，补充 best-practices §7） - [ ] 走了 §1 决策树？没有在「截图就够」的场景里重建 HTML？ - [ ] 切片元素动完归位到 layout.json 的真实槽位？ - [ ] 光标与操作全程在可视区内（含 8% 边距）？ - [ ] 用户打字是逐字符 3f 节奏，AI 输出才是 Chunk Reveal，两者没用混？ - [ ] 光标打字时常亮、打完才闪？点击有双圈 ripple？ - [ ] 状态转场里没有残留 addEventListener / classList / CSS transition？ - [ ] 批量退场错峰 ≥0.4f，收尾满板静止 0.5s？ - [ ] 全片只有一个镜头用了轮廓光/glint，且只给主角？ - [ ] before/after 同布局同机位，before 是真实旧态？ - [ ] 三方向板是同一 UI 素材的三种镜头诠释，不是三套皮肤？ --- ## §7 常见失败模式速查 | 症状 | 根因 | 回哪节 | |---|---|---| | 「科技感不够」于是加粒子/辉光 | 方向就错了，质感缺口在真实 UI 和运镜 | 开篇主张 + §1 | | 界面像贴图悬在画布上 | 没装设备框、没有影子语言 | §1 设备框 + 八式①双层影 | | 推近后文字发糊 | 截图倍率不足或栅格化分辨率问题 | §1 三件套 + camera-language.md | | 交互「像脚本不像人」 | 打字/点击/响应全按机器速度跑 | 八式③④ + §4 铁律 1 | | preview 正常、渲染穿帮 | 事件驱动状态混进了时间轴 | 八式⑤对照表 + gsap-recipes §6 | | 观众说「有点晕」 | 镜头和页面同时动，或刹车点超预算 | 八式⑥⑦ + huarec 预算 | --- ## 附 · 与其他文件的关系 | 文件 | 关系 | |---|---| | `camera-language.md` | 镜头词汇、运镜动机、camera rig 实现。本文件说「配什么镜头」，那边说「镜头怎么做」 | | `animation-best-practices.md` | 元素级运动语法总纲。§3.5 鼠标轨迹、§4.1 FLIP、§4.5 Chunk Reveal 被本文件引用 | | `gsap-recipes.md` | 实现层翻译。§3.4/§3.5 proxy 配方、§6 seek 安全规则是本文件所有配方的执行前提 | | `brand-asset-protocol.md` | UI 截图的取材协议。本文件 §1 三件套是它的规格化扩展 | | `assets/cursor.jsx` | 八式④的组件实现，配合 `browser_window.jsx` / `macos_window.jsx` 使用 | | `apple-gallery-showcase.md` | 多产出同屏陈列走那边；单产品 UI 叙事走本文件 | -
verification.md 6.8 KB
# Verification：输出验证流程 一些 design-agent 原生环境（如 Claude.ai Artifacts）有内置的 `fork_verifier_agent` 起 subagent 用 iframe 截图检查。大部分 agent 环境（Claude Code / Codex / Cursor / Trae / 等）里没有这个内置能力——用 Playwright 手动做就能覆盖相同的验证场景。 ## 🔴 第 0 条：先验证你的验证工具 **在相信任何渲染结果之前，先确认这个渲染器本身能正确渲染。** 这条排在所有验证之前， 因为工具不可信时，后面每一步都在给你假的绿灯。 两个实测翻车（2026-09，一次带甲方模板的 PPTX 交付）： - **macOS `qlmanage -t` 生成的缩略图放过了 4 个会导致文字重叠的 bug**。它走的是简化 渲染路径，对行距的处理比真 PowerPoint 宽容得多——20 页逐页看过去全对，用户在 WPS 里 一打开就是文字压文字。**缩略图不是渲染，别拿它当验收依据。** - **LibreOffice 在 macOS 上渲染中文 PPTX 全是豆腐块**，一度让人以为是文件坏了。 **怎么判断是工具的问题还是产物的问题：做对照实验。** 把一个**已知正确的同类文件**丢给同一个渲染器——上面第二例里，把甲方的官方模板原件 拿去渲染，它的中文同样全部消失，当场就能判定这是环境问题、不是你的文件问题。 这一步能省掉几小时在错误方向上的排查。 **可信度排序（macOS）**： | 工具 | 能不能信 | |---|---| | `qlmanage -t` 缩略图 | ❌ 不能当验收依据 | | LibreOffice headless | ⚠️ 版面可信，字体/中文可能整体丢失 | | Keynote + AppleScript 导 PDF | ✅ 可自动化的首选，真排版引擎 | | 目标软件本体（PowerPoint / WPS）打开 | ✅ 最终确认，人工看 | ⚠️ **不要用 System Events 注入按键**去驱动 GUI 翻页截图——按键会打到用户当前正在 输入的窗口里去。要么用 AppleScript 的文档级 API（如 Keynote 的 `export`），要么人工看。 **再配一道不依赖任何渲染器的机械校验**：文字逐字比对（源数据 vs 产物， `re.sub(r'\s+','')` 后必须完全相等）、元素数量逐页比对。渲染器骗得了眼睛，骗不过计数。 --- ## 验证清单 每次产出HTML后，按这个清单做一遍： ### 1. 浏览器渲染检查（必做） 最基础：**HTML能不能打开**？在macOS上： ```bash open -a "Google Chrome" "/path/to/your/design.html" ``` 或者用Playwright截图（下一节）。 ### 2. 控制台错误检查 HTML文件里最常见的问题是JS报错导致白屏。用Playwright跑一遍： ```bash python ~/.claude/skills/huashu-design/scripts/verify.py path/to/design.html ``` 这个脚本会： 1. 用headless chromium打开HTML 2. 截图保存到项目目录 3. 抓取控制台错误 4. 报告status 详见`scripts/verify.py`。 ### 3. 多视口检查 如果是响应式设计，抓多个viewport： ```bash python verify.py design.html --viewports 1920x1080,1440x900,768x1024,375x667 ``` ### 4. 交互检查 Tweaks、动画、按钮切换——默认的静态截图看不到。**建议让用户自己开浏览器点一遍**，或者用Playwright录屏： ```python page.video.record('interaction.mp4') ``` ### 5. 幻灯片逐页检查 Deck类HTML，一张张截： ```bash python verify.py deck.html --slides 10 # 截前10张 ``` 生成 `deck-slide-01.png`、`deck-slide-02.png`... 方便快速浏览。 ## Playwright Setup 首次使用需要： ```bash # 如果还没装 npm install -g playwright npx playwright install chromium # 或者Python版 pip install playwright playwright install chromium ``` 如果用户已经全局安装 Playwright，直接用即可。 ## 截图最佳实践 ### 截完整页面 ```python page.screenshot(path='full.png', full_page=True) ``` ### 截viewport ```python page.screenshot(path='viewport.png') # 默认只截可见区域 ``` ### 截特定元素 ```python element = page.query_selector('.hero-section') element.screenshot(path='hero.png') ``` ### 高清截图 ```python page = browser.new_page(device_scale_factor=2) # retina ``` ### 等动画结束再截 ```python page.wait_for_timeout(2000) # 等2秒让动画settle page.screenshot(...) ``` ## 把截图发给用户 ### 本地截图直接打开 ```bash open screenshot.png ``` 用户会在自己的 Preview/Figma/VSCode/浏览器 里看。 ### 上传图床分享链接 如果需要给远程协作者看（比如 Slack/飞书/微信），让用户用自己的图床工具或 MCP 上传截图，拿到一个永久链接，可以粘贴到任何地方。 ## 验证出错时 ### 页面白屏 控制台一定有错。先检查： 1. React+Babel script tag的integrity hash对不对（见`react-setup.md`） 2. 是不是`const styles = {...}`命名冲突 3. 跨文件的组件有没有export到`window` 4. JSX语法错误（babel.min.js不报错，换babel.js非压缩版） ### 动画卡 - 用Chrome DevTools Performance tab录一段 - 找layout thrashing（频繁的reflow） - 动效优先用`transform`和`opacity`（GPU加速） ### 字体不对 - 检查`@font-face`的url是否可访问 - 检查fallback字体 - 中文字体加载慢：先显示fallback，加载完再切换 ### 布局错位 - 检查`box-sizing: border-box`是否全局应用 - 检查`* margin: 0; padding: 0`reset - Chrome DevTools里打开gridlines看实际布局 ## 验证=设计师的第二双眼 **永远要自己过一遍**。AI写代码时经常出现： - 看起来对但interaction有bug - 静态截图好但scroll时错位 - 宽屏好看但窄屏崩 - Dark mode忘了测 - Tweaks切换后某些组件没响应 **最后1分钟的验证可以省1小时的返工**。 ## 常用验证脚本命令 ```bash # 基础：打开+截图+抓错 python verify.py design.html # 多viewport python verify.py design.html --viewports 1920x1080,375x667 # 多slide python verify.py deck.html --slides 10 # 输出到指定目录 python verify.py design.html --output ./screenshots/ # headless=false，打开真实浏览器给你看 python verify.py design.html --show ``` ## 视频产物硬校验（verify-video.sh） 渲染出的 MP4/成片不靠肉眼过，用脚本硬校验（HTML 合成侧的校验由 `hyperframes check` 五门审计负责，这个脚本只管产物侧）： ```bash # 成品（默认要求有音轨） bash scripts/verify-video.sh final.mp4 --duration=22 --fps=60 --width=1920 --height=1080 # 无声中间产物 bash scripts/verify-video.sh raw.mp4 --duration=10 --fps=60 --no-audio # 刻意黑场开场的电影风 bash scripts/verify-video.sh film.mp4 --duration=30 --fps=60 --allow-black-open ``` 检查项：分辨率/帧率、时长误差（±2%）、audio stream 存在性（无音轨=半成品铁律的机器执行）、首尾黑帧（blackdetect，录制起点偏移/loop 回跳的典型症状）、LUFS 响度（成品目标 -14±4）。exit code 非 0 就不许交付。 -
video-export.md 11.3 KB
# Video Export：HTML 动画导出为 MP4/GIF 动画 HTML 完成后，用户常想「能导出视频吗」。这份指南给出完整流程。 ## 何时导出 **导出时机**： - 动画完整跑通、视觉验证过（Playwright 截图确认各时间点状态正确） - 用户在浏览器里看过至少一次，表示效果 OK - **不要**在动画 bug 没修完的阶段导出——导出到视频后改起来更贵 **用户可能说的触发语**： - 「能导出成视频吗」 - 「转成 MP4」 - 「做成 GIF」 - 「60fps」 ## 产出规格 默认一次给三种格式，让用户选： | 格式 | 规格 | 适合场景 | 典型大小（30s） | |---|---|---|---| | MP4 25fps | 1920×1080 · H.264 · CRF 18 | 公众号嵌入、视频号、YouTube | 1-2 MB | | MP4 60fps | 1920×1080 · 默认帧复制（兼容稳）· H.264 · CRF 18；高质量插帧需显式 `--minterpolate`；走 Stage 时钟的用 render-video-seek.js 直录真 60fps | 高帧率展示、B站、作品集 | 1.5-3 MB | | GIF | 960×540 · 15fps · palette 优化 | Twitter/X、README、Slack 预览 | 2-4 MB | ## 工具链 两个脚本在 `scripts/`： ### 1. `render-video.js` — HTML → MP4 录一个 25fps 的 MP4 基础版本。依赖全局 playwright。 ```bash NODE_PATH=$(npm root -g) node /path/to/claude-design/scripts/render-video.js <html文件> ``` 可选参数： - `--duration=30` 动画时长（秒） - `--width=1920 --height=1080` 分辨率 - `--trim=2.2` 从视频开头裁掉的秒数（去掉 reload + 字体加载时间） - `--fontwait=1.5` 字体加载等待时间（秒），字体多时调高 输出：与 HTML 同目录，同名 `.mp4`。 ### 2. `add-music.sh` — MP4 + BGM → MP4 给无声 MP4 混入背景音乐，按场景（mood）从内置 BGM 库里选，也可自带音频。自动匹配时长、加淡入淡出。 ```bash bash add-music.sh <input.mp4> [--mood=<name>] [--music=<path>] [--out=<path>] ``` **内置 BGM 库**（在 `assets/bgm-<mood>.mp3`）： | `--mood=` | 风格 | 适配场景 | |-----------|------|---------| | `tech`（默认） | Apple Silicon / 苹果发布会，极简合成器+钢琴 | 产品发布、AI工具、Skill 宣传 | | `ad` | upbeat 现代电子，有 build + drop | 社交媒体广告、产品预告、促销片 | | `educational` | 温暖明亮、轻吉他/电钢琴，inviting | 科普、教程介绍、课程预告 | | `educational-alt` | 同类备选，换一首试试 | 同上 | | `tutorial` | lo-fi 环境音，几乎无存在感 | 软件演示、编程教程、长演示 | | `tutorial-alt` | 同类备选 | 同上 | **行为**： - 音乐按视频时长裁剪 - 0.3s 淡入 + 1s 淡出（避免硬切） - 视频流 `-c:v copy` 不重编码，音频 AAC 192k - `--music=<path>` 优先级高于 `--mood`，可以直接指定任意外部音频 - 传错 mood 名会列出所有可用选项，不会静默失败 **典型流水线**（动画导出三件套 + 配乐）： ```bash node render-video.js animation.html # 录屏 bash convert-formats.sh animation.mp4 # 派生 60fps + GIF bash add-music.sh animation-60fps.mp4 # 加默认 tech BGM # 或针对不同场景： bash add-music.sh tutorial-demo.mp4 --mood=tutorial bash add-music.sh product-promo.mp4 --mood=ad --out=promo-final.mp4 ``` ### 3. `convert-formats.sh` — MP4 → 60fps MP4 + GIF 从已有 MP4 生成 60fps 版本和 GIF。 ```bash bash /path/to/claude-design/scripts/convert-formats.sh <input.mp4> [gif_width] [--minterpolate] ``` 输出（与输入同目录）： - `<name>-60fps.mp4` — 默认用 `fps=60` 帧复制（兼容性广）；加 `--minterpolate` 启用高质量插帧 - `<name>.gif` — palette 优化的 GIF（默认 960 宽，可改） **60fps 模式选择**： | 模式 | 命令 | 兼容性 | 使用场景 | |---|---|---|---| | 帧复制（默认）| `convert-formats.sh in.mp4` | QuickTime/Safari/Chrome/VLC 全通 | 通用交付、上传平台、社交媒体 | | minterpolate 插帧 | `convert-formats.sh in.mp4 --minterpolate` | macOS QuickTime/Safari 可能拒打 | B站等需要真插帧的展示场景，**交付前必须本地测**目标播放器 | 为什么默认改成帧复制？minterpolate 输出的 H.264 elementary stream 有 known compat bug——之前默认 minterpolate 时多次踩到「macOS QuickTime 打不开」的问题。详见 `animation-pitfalls.md` §14。 `gif_width` 参数： - 960（默认）—— 社交平台通用 - 1280 —— 更清晰但文件更大 - 600 —— Twitter/X 优先加载 ### 4. `render-video-seek.js` — 真 60fps / 确定性渲染（推荐高质量交付） `render-video.js` 的 recordVideo 路径有三个固有限制：帧率被 Chromium compositor 锁死 25fps、开头有加载黑帧需 trim、60fps 只能靠事后 minterpolate 插帧（有 ghosting + macOS QuickTime 兼容 bug，见 `animation-pitfalls.md §14`）。需要**真 60fps、确定性输出、或交付 B站/作品集**时，改用 seek 渲染。 它逐帧 seek 到时间戳截图、再用 ffmpeg 把 PNG 序列编码成 MP4。技术内核借鉴 HeyGen HyperFrames（Apache 2.0）的「冻结时钟 + seek 截图」思路，但不引入任何第三方包——只用本 skill 已有的 playwright + ffmpeg，runtime 中立。 ```bash NODE_PATH=$(npm root -g) node /path/to/claude-design/scripts/render-video-seek.js <html文件> --fps=60 ``` 参数：`--duration` · `--fps`（默认 60）· `--width` · `--height` · `--concurrency`（默认 4 个 worker 并行）· `--settle`（seek 后等几个 rAF 再截图，默认 2，重 layout 动画可调高）· `--keep-chrome`。输出与 HTML 同目录、同名 `.mp4`。 正面解决 recordVideo 三死结： - **真原生任意帧率**：`--fps=60` 出真 60fps（每帧都是真实 seek 画面），不再经 `convert-formats.sh` 的 minterpolate 插帧，绕开 ghosting + macOS 兼容 bug - **无开头黑帧**：不录屏，根本没有加载期黑帧，不需要 `--trim` / `--fontwait` - **确定性**：seek 到时间戳截图，同输入同输出，不受机器负载/丢帧影响 **适用边界（重要）**：只支持走 Stage 时钟的动画——`assets/animations.jsx` 的 `<Stage>` 或 `narration_stage.jsx` 的 `<NarrationStage>`，它们会响应 `window.__seekRender` 冻结自驱时钟并暴露 `window.__seek(t)`。纯 CSS `@keyframes` / Lottie / 手写非 Stage 动画不吃 `__seek`，这类继续用 `render-video.js`（脚本检测不到 `__seek` 会报错并提示）。 **代价**：逐帧截图，长视频总耗时可能比 recordVideo 实时录更久（靠 `--concurrency` 多 worker 缓解）；大量临时 PNG 占盘，渲染前建议关其他大内存 App。 **二选一策略**：默认仍用 `render-video.js`（零风险、覆盖所有动画类型）；需要真 60fps / 确定性 / 高质量交付、且动画走 Stage 时钟时，用 `render-video-seek.js`。带解说的长动画用 `render-narration.sh --seek` 一键走 seek 渲染 + 混音。 ## 完整流程（标准推荐） 用户说「导出视频」后： ```bash cd <项目目录> # 假设 $SKILL 指向本 skill 的根目录（自行按安装位置替换） # 1. 录 25fps 基础 MP4 NODE_PATH=$(npm root -g) node "$SKILL/scripts/render-video.js" my-animation.html # 2. 派生 60fps MP4 和 GIF bash "$SKILL/scripts/convert-formats.sh" my-animation.mp4 # 产出清单： # my-animation.mp4 (25fps · 1-2 MB) # my-animation-60fps.mp4 (60fps · 1.5-3 MB) # my-animation.gif (15fps · 2-4 MB) ``` ## 技术细节（排错用） ### Playwright recordVideo 的坑 - 帧率固定 25fps，无法直接录 60fps（Chromium headless 的 compositor 上限） - 从 context 创建就开始录，必须用 `trim` 裁掉前面的加载时间 - 默认 webm 格式，需要 ffmpeg 转 H.264 MP4 才能通用播放 `render-video.js` 已处理以上问题。 ### ffmpeg minterpolate 参数 当前配置：`minterpolate=fps=60:mi_mode=mci:mc_mode=aobmc:me_mode=bidir:vsbmc=1` - `mi_mode=mci` — motion compensation interpolation（运动补偿） - `mc_mode=aobmc` — adaptive overlapped block motion compensation - `me_mode=bidir` — 双向运动估计 - `vsbmc=1` — 可变 size block motion compensation 对 CSS **transform 动画**（translate/scale/rotate）效果好。 对**纯 fade** 可能产生轻微 ghosting——如果用户嫌弃，退化为简单帧复制： ```bash ffmpeg -i input.mp4 -r 60 -c:v libx264 ... output.mp4 ``` ### GIF palette 为何要两阶段 GIF 只能 256 色。一次 pass 的 GIF 会把全动画色彩压到 256 色通用 palette，对米色底+橙色这种细腻配色会糊。 两阶段： 1. `palettegen=stats_mode=diff` —— 先扫描全片，生成**针对此动画的 optimal palette** 2. `paletteuse=dither=bayer:bayer_scale=5:diff_mode=rectangle` —— 用这个 palette 编码，rectangle diff 只更新变化区域，大幅减小文件 对 fade 过渡用 `dither=bayer` 比 `none` 更平滑，但文件大一点。 ## Pre-flight check（导出前） 导出前 30 秒自检： - [ ] HTML 在浏览器里完整跑过一遍，无控制台错误 - [ ] 动画第 0 帧是完整初始状态（不是空白加载中） - [ ] 动画最后一帧是稳定的收尾状态（不是半截） - [ ] 字体/图片/emoji 全部正常渲染（参考 `animation-pitfalls.md`） - [ ] Duration 参数与 HTML 里的实际动画时长匹配 - [ ] HTML 中 Stage 检测 `window.__recording` 强制 loop=false（手写 Stage 必查；用 `assets/animations.jsx` 自带） - [ ] 结尾 Sprite 的 `fadeOut={0}`（视频末帧不淡出） - [ ] 含「Created by Huashu-Design」水印（仅动画场景必加；第三方品牌作品加「非官方出品 · 」前缀。详见 SKILL.md §「Skill 推广水印」） ## 交付时附带的说明 导出完成后给用户的标准说明格式： ``` **完整交付** | 文件 | 格式 | 规格 | 大小 | |---|---|---|---| | foo.mp4 | MP4 | 1920×1080 · 25fps · H.264 | X MB | | foo-60fps.mp4 | MP4 | 1920×1080 · 60fps（默认帧复制；插帧版会注明）· H.264 | X MB | | foo.gif | GIF | 960×540 · 15fps · palette 优化 | X MB | **说明** - 60fps 默认帧复制（兼容性好）；显式要求时才用 minterpolate 插帧（transform 动画效果好，复杂画面易出伪影）；真 60fps 用 render-video-seek.js 逐帧 seek 直录 - GIF 用 palette 优化，30s 动画可压到 3MB 左右 要换尺寸或帧率说一声。 ``` ## 常见用户追加需求 | 用户说 | 应对 | |---|---| | 「太大了」 | MP4：提高 CRF 到 23-28；GIF：降分辨率到 600 或 fps 到 10 | | 「GIF 太糊」 | 提高 `gif_width` 到 1280；或者建议用 MP4 代替（微信朋友圈也支持） | | 「要竖屏 9:16」 | 改 HTML 源的 `--width=1080 --height=1920`，重新录 | | 「加水印」 | ffmpeg 加 `-vf "drawtext=..."` 或 `overlay=` 一个 PNG | | 「要透明背景」 | MP4 不支持 alpha；用 WebM VP9 + alpha 或 APNG | | 「要无损」 | CRF 改 0 + preset veryslow（文件会大 10 倍） | ## Skill 推广水印模板（仅动画导出用） SKILL.md 规定动画 MP4/GIF 默认带水印，模板如下（深底改用 `rgba(255,255,255,0.35)`；第三方品牌动画前缀「非官方出品 · 」）： ```jsx <div style={{ position: 'absolute', bottom: 24, right: 32, fontSize: 11, color: 'rgba(0,0,0,0.4)', letterSpacing: '0.15em', fontFamily: 'monospace', pointerEvents: 'none', zIndex: 100, }}> Created by Huashu-Design </div> ``` -
voiceover-pipeline.md 19.6 KB
# Voiceover Pipeline · 解说驱动动画 > 把动画从「无声画面 + 后期配音」升级为「**先有解说词，再按音频实测时长驱动画面**」的工作流。 > 适用：5-20 分钟概念解说视频、教程视频、长篇知识科普。 > > 配套 `references/animation-best-practices.md` 使用——本文件管 **怎么把解说和画面对上**， > animation-best-practices 管 **每一帧画面怎么动**。 --- ## 🛑 铁律 · 在写一行代码之前必读 > **强调多少遍都不够：解说动画的失败模式 #1 是做成了带配音的 PowerPoint。** ### 第一条 · 整片是一个连续的运动叙事，不是一组独立场景 PowerPoint 是 7 张幻灯片。我们做的是 **1 段持续 X 分钟的电影**。 **身份切换**： - ❌ 你不是「在做 7 个 scene 的内容」 - ✅ 你是「在屏幕上让一个或几个 hero element 演 X 分钟的戏」 **视觉骨架 = 一个或几个贯穿全片的 hero element**： - 它从 t=0 出现，到结束才离场 - 每个 cue 是它的**状态变化**（位置 / 大小 / 颜色 / 透视 / 形态），不是「换一个新元素」 - scene 边界在剧本里有，**在画面里不应该有**——观众看不出"这是第 3 个 scene"，只看到一段连续的运动 **反例（本 skill v1 实战踩坑 · 2026-05-10）**： - 7 个 `<Scene>` 各自独立 layout，scene 切换 = 整页 opacity 1→0 切到下一页 - 每个 cue = `opacity: p, transform: translateY((1-p)*30px)`（fade-up 单调使用） - 结果：观众看完第一反应「像一页页 keynote」，整片质感归零 **正确模式**： - 选定 1-2 个 hero element（如本文章 demo 应选「md」「html」两个字符作为骨架） - 这两个字符**从片头到片尾**一直在屏幕上 - 每段「scene」实际是 hero element 的一次状态变化 - opening：两字符在屏幕中央对峙 - md-side：md 变大变粗占据画面，html 退到角落小字；数据围绕 md 涌入 - html-side：html 反转为主角；md 退到角落 - the-real-question：两字符回到中央，但中间出现「≠」分隔 - the-split：两字符向两侧推开，中间空白展开 - activity-proof：两字符在 timeline 上交替闪烁 - closing：两字符落地为最终答案位置 - 这样整片是「md 和 html 在屏幕上演了 X 分钟」，不是 7 张独立 PPT **最小实现骨架**（直接抄改）： ```jsx // ── Step 1: 定义 hero 在每个 scene 的目标状态（位置/大小/不透明度）── const HERO_KEYS = { opening: { md: { x: 50, y: 35, scale: 1.0, opacity: 1 }, html: { x: 50, y: 65, scale: 1.0, opacity: 1 } }, 'md-side': { md: { x: 78, y: 50, scale: 1.6, opacity: 1 }, html: { x: 92, y: 8, scale: 0.25, opacity: 0.4 } }, 'html-side':{ md: { x: 8, y: 8, scale: 0.25, opacity: 0.4 }, html: { x: 22, y: 50, scale: 1.6, opacity: 1 } }, // ... 每段一个 entry，连贯的运动从前一段的 final → 本段的 from }; // ── Step 2: easing + lerp 工具 ── const expoOut = t => t === 1 ? 1 : 1 - Math.pow(2, -10 * t); const lerp = (a, b, t) => a + (b - a) * t; const lerpPos = (from, to, t) => ({ x: lerp(from.x, to.x, t), y: lerp(from.y, to.y, t), scale: lerp(from.scale, to.scale, t), opacity: lerp(from.opacity ?? 1, to.opacity ?? 1, t), }); // ── Step 3: HeroAnchor 组件 —— 直接挂在 <NarrationStage> 子级，不放进 <Scene> ── const HeroAnchor = () => { const { time, scene, timeline } = useNarration(); if (!scene) return null; const idx = timeline.scenes.findIndex(s => s.id === scene.id); const prevId = idx > 0 ? timeline.scenes[idx - 1].id : scene.id; const from = HERO_KEYS[prevId]; const to = HERO_KEYS[scene.id]; // 段内前 ~45% 时间用于从 prev 状态 morph 到本段状态，剩余 hold const transitionDur = Math.min(2.0, scene.duration * 0.45); const t = expoOut(Math.min(1, (time - scene.start) / transitionDur)); const md = lerpPos(from.md, to.md, t); const html = lerpPos(from.html, to.html, t); // 加 subtle breathing 让任意一帧都有运动（对应铁律第三条） const breath = 1 + Math.sin(time * 0.6) * 0.012; const renderHero = (label, pos, color) => ( <div style={{ position: 'absolute', left: `${pos.x}%`, top: `${pos.y}%`, transform: `translate(-50%, -50%) scale(${pos.scale * breath})`, opacity: pos.opacity, color, fontSize: 360, fontWeight: 800, lineHeight: 1, willChange: 'transform, opacity', pointerEvents: 'none', }}>{label}</div> ); return <> {renderHero('md', md, '#1B4965')} {renderHero('html', html, '#C04A1A')} </>; }; // ── Step 4: 主组件 —— hero 在 NarrationStage 子级，scene 内辅助元素另外管 ── const App = () => ( <NarrationStage timeline={TIMELINE} audioSrc="_narration/voiceover.mp3" width={1920} height={1080}> <HeroAnchor /> {/* ← 跨 scene 持续存在，整片视觉骨架 */} {/* scene 内辅助元素用 useSceneFade 控制软淡入淡出，不要硬切 */} <MdSideAux /> <HtmlSideAux /> {/* ... */} </NarrationStage> ); ``` **完整可运行参考**：`demos/md-html-narration/md-html-demo.html`（3 分 21 秒，7 段，21 cue，已实战验证） ### 第二条 · 场景之间不能「硬切」 | 错误模式（PowerPoint slop） | 正确模式（电影感） | |---|---| | scene A 整体 `opacity 1→0` 同时 scene B `opacity 0→1` | scene A 的核心元素 **morph 进** B（位置/大小/颜色平滑变换） | | 每个 scene 独立 layout，元素出现/消失 | 元素在屏幕上**持续存在**，只是位置和形态在变 | | `keepMounted=false`，scene 切换瞬间组件被卸载 | hero 用 `keepMounted=true`，跨 scene 共享 DOM 节点 | | 字幕条/数据卡片各自 fade in fade out | 字幕条作为画面唯一的"非 hero" 入场，hold 后**配合 hero 的运动一起退出** | 实现层面： - **共享元素跨 scene** → 把 hero 提到 `<NarrationStage>` 直接子级，**不放在任何 `<Scene>` 里** - 用 `useNarration()` hook 在 hero 里读 `time`、`scene`、`isCueTriggered`，自己根据当前时间决定形态 - `<Scene>` 只用来管那些只在该段出现的辅助元素（数据卡、引用块等），并且**这些辅助元素也不要硬切**——出场用 expoOut + stagger，退场用 fade overlap 跟下一段叠 ### 第三条 · 每一帧画面都必须有运动 **自检方法**：在录制中**任意截一帧**（不是 cue 触发那一秒）。 - 如果画面看起来「**完全静止**」→ 错。回去加底层运动（background drift / hero subtle scale / camera pan / parallax） - 永远有一个**底层运动**在跑（即使不是焦点）： - hero element 的 `scale: 1 ↔ 1.02` 5 秒呼吸循环 - 背景 `translateX: 0 ↔ -20px` 缓慢漂移 - 数据卡片入场后保留 `translateY` 微抖（Perlin noise） - 一个完全静止的画面 = PowerPoint slop ### 第四条 · Easing / Stagger / Hold 是底线 | 项 | 必须 | 禁止 | |---|---|---| | Easing | `expoOut` 主轴（`cubic-bezier(0.16, 1, 0.3, 1)`），`overshoot` 强调，`spring` 落位 | `linear`、`ease`、CSS 默认 | | 多元素入场 | 30ms stagger（每个晚 30ms 进） | 一刀切全部出现 | | 关键 cue 前 | hold 0.3-0.5s 让观众"看见"（前一段元素先静止 0.3s，再触发 cue） | 一段说完无缝切下一段 | | 收尾 | 戛然而止，最后一帧 hold 1s | fade to black | 详细规则参考 `animation-best-practices.md` 的 §1-§4。 ### 自检 · 第一观众反应 做完拿给一个没看过的人看（或自己 24 小时后再看），**他们的第一反应**是什么？ | 反应 | 评级 | 行动 | |---|---|---| | 「这是带配音的 PPT」 | 失败 | 回去重做 | | 「画面跟着声音在切换」 | 不及格 | 缺连续叙事，hero element 不存在或没贯穿 | | 「这个东西在动」 | 合格 | 但没记忆点 | | 「我想看完」 | 良 | 节奏对了 | | 「这一段我想截图」 | great | 你做到了 | --- ## 工作流（高层） ``` ┌──────────────────────────┐ │ 解说稿 .md（## scene + │ │ [[cue:xx]] 标关键句） │ └──────────────┬───────────┘ │ narrate-pipeline.mjs │ ▼ ┌──────────────────────────────┐ │ voiceover.mp3 (拼接的整段) │ │ timeline.json (实测时长) │ └──────────────┬───────────────┘ │ ┌────────────┴────────────┐ ▼ ▼ ┌─────────────────┐ ┌──────────────────┐ │ HTML 动画 │ │ 录制 MP4 + 混音 │ │ (NarrationStage)│ │ render-narration │ │ 实播带 audio 同步│ │ → 最终发布 MP4 │ └─────────────────┘ └──────────────────┘ 交付形态 1 交付形态 2 ``` ## 解说稿格式 放在项目目录下任意位置，文件名建议 `script.md`： ```markdown --- title: 什么是 LLM voice: S_JSdgdWk22 # 可选，覆盖 .env 默认音色 speed: 1.0 # 可选，0.5-2.0 gap: 0.4 # 段间静音秒数，默认 0.3 --- ## intro 大家好，今天我们 5 分钟讲清楚 LLM 是什么。 ## what-is LLM 全称 Large Language Model，[[cue:bigmodel]]它是一个有几千亿参数的神经网络。 本质是一个文字接龙的预测器。 ## demo 比如你输入「今天天气」，[[cue:input]]模型会预测下一个字最可能是什么。 [[cue:predict]]也许是「真好」，也许是「不错」。 ``` **规则**： - 段标题 `## scene-id` 是英文/数字 + 连字符（如 `## what-is`、`## scene-1`） - `[[cue:xx]]` 标在**关键句中间**——脚本运行时会在该位置切割文本，cue 之后那一刻就是画面的触发点 - cue id 在动画 HTML 里用 `<Cue id="xx">` 监听 - 写解说时**关注节奏 + 短句**，长句 TTS 出来会平淡 ## timeline.json schema ```ts { title: string, voice: string | null, speed: number, gap: number, totalDuration: number, // 整段 voiceover.mp3 的实测秒数 voiceover: 'voiceover.mp3', // 相对 timeline.json 的路径 scenes: [ { id: string, start: number, // 该段在整段音频里的开始时间 end: number, duration: number, audio: 'audio/<id>.mp3', // 该段单独音频（合并前的子段已 concat） text: string, // 已剥离 [[cue:xx]] 标记的整段文本 // chunks 是字幕显示的源——每个 chunk 是被 cue 切开的子段，含 TTS 实测时间窗 chunks: [ { text: string, // 子段文本 start: number, // 段内相对时间 end: number, absoluteStart: number, // 整轨绝对时间（对齐 voiceover.mp3） absoluteEnd: number, // words: 字级时间戳（TTS enable_subtitle 实测返回，默认带；--no-timestamps 关闭） // 注意 text 是 TN 后文本（"2025"→"二零二五"），标点附在前一个字上 words: [ { text: string, start: number, end: number, absoluteStart: number, absoluteEnd: number } ], } ], cues: [ { id: string, offset: number, // 段内相对时间 absoluteTime: number, // 整段时间轴上的绝对时间 } ] } ] } ``` `absoluteTime` 和 `absoluteStart/End` 都是**真实测出来的**——pipeline 把段内文本按 cue 切成子段分别 TTS，时间 = 累加前面子段的实测时长。**不是按字符数线性估算的近似值**。 ## 字幕（Subtitles） > **字幕是默认带的**——长解说视频没字幕，留存率会显著下降。NarrationStage 提供 `<Subtitles />` 开箱即用。 ### 用法（一行） ```jsx const { NarrationStage, Subtitles } = NarrationStageLib; <NarrationStage timeline={TIMELINE} audioSrc="..."> {/* 你的 hero / scene 内容 */} <Subtitles /> {/* ← 自动从 timeline.scenes[].chunks 取活动文本 */} </NarrationStage> ``` ### 视觉规则（B 站风 · 反 PowerPoint） | 项 | 规则 | 反例 | |---|---|---| | 背景 | **无背景**（不要黑色横条不要 backdrop-blur）| 半透明黑底 + blur = 字幕条压住画面 = PPT 感 | | 字色 | **浅底用深墨 `#1a1a1a` + 白光晕**；深底用白字 + 黑光晕 | 浅底白字+黑描边 = 字糊 | | 字号 | 32px（1080p 视频）| <24px 看不清，>40px 抢主视觉 | | 字体 | `PingFang SC` / `Noto Sans SC`（无衬线，B 站标准）| 衬线字体 = 像电影字幕 | | 位置 | bottom: 90px（不贴边）| 贴底边显得廉价 | | 单行长度 | **≤ 12-13 字**（中英混合时英文按 0.5 字算）| >15 字一行手机端读不完 | | 切句规则 | **绝不跨句号截断**：先按 `。！？` 切句，每句再按 `，、；：` 合并到 ≤maxLen | 按字数硬切，把「这是好的」切成「这是好」+「的」 | `<Subtitles />` 默认按以上规则跑，不需要传 props。深底场景：`<Subtitles color="#fff" haloColor="rgba(0,0,0,0.85)" />`。 ### 卡拉OK模式（字级高亮） ```jsx <Subtitles karaoke /> {/* 读到哪个字哪个字变品牌橙 #e8590c */} <Subtitles karaoke karaokeColor="#0a84ff" /> {/* 自定义高亮色 */} ``` - 依赖 timeline chunks 里的 `words` 字级时间戳（narrate-pipeline.mjs 默认输出；豆包 TTS v3 `enable_subtitle`，需 2.0 资源，仅中英文） - 整行显示、逐字变色，行切分复用 ≤maxLen + 不跨句号规则（由 words 拼行，与发音严格对齐） - chunk 没有 words 时自动回落普通 chunk 模式，调用方无需判断 ### 切句算法（已在 narration_stage.jsx 内置） ```js splitChunkToLines(text, maxLen = 13) // 1. 强标点切句（。！？\n） // 2. 每句 ≤ maxLen 直接保留 // 3. 否则按弱标点（，、；：）切片，合并到 ≤ maxLen // 4. 兜底硬切（罕见） // 中英混合：英文/数字按 0.5 字算视觉宽度 ``` 如果 chunk 切完后某行明显太长或太短，**改解说稿里 cue 位置**（cue 把段切得更细），不要在前端调切句逻辑。 ## NarrationStage API ```jsx import 'assets/narration_stage.jsx'; const { NarrationStage, Scene, Cue, useNarration } = NarrationStageLib; <NarrationStage timeline={TIMELINE} // timeline.json 内容 audioSrc="_narration/voiceover.mp3" // 相对当前 HTML 的路径 width={1920} height={1080} background="#f5f1e8" controls={true} // 实播时显示底部播放条 > {/* hero element：跨 scene 持续存在 —— 直接放在 NarrationStage 子级 */} <HeroAnchor /> {/* scene 内辅助元素：只在该段出现 */} <Scene id="intro"> <Cue id="bigmodel">{(triggered, progress) => ( <SomeElement style={{ opacity: progress }} /> )}</Cue> </Scene> </NarrationStage> ``` **Hooks**： - `useNarration()` 返回 `{ time, scene, sceneTime, isCueTriggered, cueProgress }` - 在自定义组件里直接读，不需要传 props **Scene 组件**： - 默认只在 `scene.id === id` 时挂载 - 加 `keepMounted` 持续挂载（跨 scene 动画连续时用） **Cue 组件**： - children 必须是 `(triggered, progress) => ReactNode` - progress 是 cue 触发后 0→1 的渐进值（默认 0.6s ramp） ## 时间源（双轨） NarrationStage 自动检测 `window.__recording`： - **实播模式**（默认）：跟随 audio 元素的 currentTime，用户暂停/拖动 seek 都能同步 - **录视频模式**（render-video.js 设置 `window.__recording = true`）：rAF wall-clock 自驱动从 0 开始，暴露 `window.__seek(t)` 给 render-video.js 复位 ## 三个脚本 | 脚本 | 输入 | 输出 | |---|---|---| | `scripts/cloud/tts-doubao.mjs` | 单段文本 | 单个 mp3 + 实测时长 | | `scripts/narrate-pipeline.mjs` | 解说稿 .md | voiceover.mp3 + timeline.json | | `scripts/mix-voiceover.sh` | 视频 + voiceover.mp3 [+ BGM] | 带音频的 MP4 | | `scripts/render-narration.sh` | 解说 HTML + timeline.json | 最终 MP4（录制 + 混音一条龙）| ## .env 配置 > ⚠️ TTS 是可选云能力：解说稿文本会发送到豆包 TTS 官方接口（openspeech.bytedance.com）， > 使用你自己的 key。脚本首次调用需 `--yes` 或 `HUASHU_CLOUD_OK=1` 显式确认， > endpoint 强制校验字节官方域名白名单。数据流向声明见仓库根 `SECURITY.md`。 skill 根目录下 `.env`（已 gitignore）： ``` DOUBAO_TTS_API_KEY=<your_api_key> DOUBAO_TTS_VOICE_ID=zh_female_xiaohe_uranus_bigtts DOUBAO_TTS_ENDPOINT=https://openspeech.bytedance.com/api/v3/tts/unidirectional ``` 也可使用控制台的 App ID + Access Token 鉴权： ``` DOUBAO_APP_ID=<your_app_id> DOUBAO_ACCESS_KEY=<your_access_token> DOUBAO_TTS_VOICE_ID=zh_female_xiaohe_uranus_bigtts ``` `DOUBAO_TTS_RESOURCE_ID` 默认按音色自动推断：`S_` 克隆音色使用 `seed-icl-1.0`，`uranus` 官方音色使用 `seed-tts-2.0`，其他官方音色使用 `seed-tts-1.0`。 ## 标准工作流（10 步） 1. **写解说稿**：解说稿是源代码。先把整段口播写完整，标段标题 `## scene-id`，关键句前加 `[[cue:xx]]` 2. **跑 narrate-pipeline**：`node scripts/narrate-pipeline.mjs --script script.md --out-dir _narration --yes`（`--yes`=确认文本发送豆包TTS） 3. **听整段 voiceover.mp3**：节奏不对回去改稿。**这一步决定整片质量上限** 4. **🛑 设计前先回答铁律**：hero element 是什么？它在每段是什么状态？跨场景怎么 morph？答不上不要写代码 5. **写动画 HTML**：用 NarrationStage + 一个或几个 hero element 跨 scene 演戏 6. **实播预览**：浏览器打开 HTML，点 ▶ Play，听画面+解说同步 7. **第一观众自检**：用上面「自检 · 第一观众反应」表打分。失败回到 Step 4 重做 8. **录视频**：`bash scripts/render-narration.sh demo.html --timeline=_narration/timeline.json`（自动录无声 MP4 + 混入 voiceover） 9. **可选 BGM**：在 render-narration 加 `--bgm-mood=educational`（或 tech / tutorial 等） 10. **交付**：浏览器 HTML（实时演示用）+ 最终 MP4（发布用） ## 异常处理 | 问题 | 解决 | |---|---| | TTS API 报错 | 检查 .env 里 `DOUBAO_TTS_API_KEY`，或 `DOUBAO_APP_ID` + `DOUBAO_ACCESS_KEY` 是否正确 | | 某段音频明显比脚本长/短 | 该段文本里有奇怪标点或 emoji，TTS 解析异常 → 改稿 | | cue absoluteTime 不准 | 段内子段拼接时 ffmpeg 有问题 → 检查 mp3 编码一致性 | | 录视频结果有黑屏 | render-video.js 没拿到 `window.__ready` 信号 → 检查 NarrationStage 是否正常挂载 | | 录视频画面卡顿 | 动画里有重 layout（大量 box-shadow / blur）→ 简化或预合成 | | 实播音画不同步 | audio 元素加载延迟 → 加 `preload="auto"` 或本地预加载 | ## 何时不用这套 pipeline - **<60s 短动画**：直接做无声动画 + 后期配音（add-music.sh + 一段单独 TTS）即可，不需要 timeline 驱动 - **纯 BGM 视频**：用 `add-music.sh` 加预设 BGM - **真人录音替换 TTS**：把 `voiceover.mp3` 替换成真人录音，timeline 自己手写或用 ffprobe 测段时长 + 工具脚本生成 → 流程其余部分通用 --- **最后一次提醒**：写代码前回到铁律。**别做带配音的 PowerPoint**。 -
workflow.md 6.9 KB
# Workflow：从接到任务到交付 你是用户的junior designer。用户是manager。按这个流程工作，能产出好设计的概率会显著提升。 ## 问问题的艺术 大多数情况下，开工前要问至少10个问题。不是走过场，是真的要把需求摸清。 **什么时候必须问**：新任务、模糊任务、没有design context、用户只说了一句模糊的要求。 **什么时候可以不问**：小修小补、follow-up任务、用户已经给了明确PRD+截图+上下文。 **怎么问**：大部分 agent 环境没有结构化问题 UI，在对话里用 markdown 清单问即可。**一次性把问题列完让用户批量答**，不要一来一回一个个问——那会浪费用户时间、打断用户思路。 ## 必问清单 每个设计任务都必须问清这5类问题： ### 1. Design Context（最重要） - 有没有现成的design system、UI kit、组件库？在哪？ - 有没有品牌指南、色彩规范、字体规范？ - 有没有可以参考的现有产品/页面截图？ - 有没有codebase可以读？ **如果用户说"没有"**： - 帮他找——翻项目目录、看有没有参考品牌 - 还没有？明确说："我会基于通用直觉做，但这通常做不出符合你品牌的作品。你考虑下是否先提供一些参考？" - 实在要做，就按`references/design-context.md`的fallback策略办 ### 2. Variations维度 - 想要几种variations？（推荐3+） - 在哪些维度上变？视觉/交互/色彩/布局/文案/动画？ - 希望variations都"接近预期"还是"一张地图，从保守到疯狂"？ ### 3. Fidelity和Scope - 多高保真？线框图 / 半成品 / 真实data的full hi-fi？ - 覆盖多少flow？一屏 / 一个flow / 整个产品？ - 有没有具体的「必须包含」元素？ ### 4. Tweaks - 希望能实时调整哪些参数？（颜色/字号/间距/layout/文案/feature flag） - 用户自己要不要在做完后继续调？ ### 5. 问题专属（至少4个） 针对具体任务问4+个细节。例如： **做landing page**： - 目标转化动作是什么？ - 主要受众？ - 竞品参考？ - 文案谁提供？ **做iOS App onboarding**： - 几步？ - 需要用户做什么？ - 跳过路径？ - 目标留存率？ **做动画**： - 时长？ - 最终用途（视频素材/官网/社交）？ - 节奏（快/慢/分段）？ - 必须出现的关键帧？ ## 问题模板示例 遇到新任务时，可以抄这个结构在对话里问： ```markdown 开始前想跟你对齐几个问题，一次列齐你批量回答就行： **Design Context** 1. 有设计系统/UI kit/品牌规范吗？如果有在哪？ 2. 有可以参考的现有产品或竞品截图吗？ 3. 项目里有codebase可以读吗？ **Variations** 4. 想要几种variations？在哪些维度上变（视觉/交互/色彩/...）？ 5. 希望都是"接近答案"还是从保守到疯狂的一张地图？ **Fidelity** 6. 保真度：线框 / 半成品 / 带真数据full hi-fi？ 7. Scope：一屏 / 一整个flow / 整个产品？ **Tweaks** 8. 希望做完后能实时调哪些参数？ **具体任务** 9. [任务专属问题1] 10. [任务专属问题2] ... ``` ## Junior Designer模式 这是整个workflow最重要的环节。**不要接到任务就闷头冲**。步骤： ### Pass 1：Assumptions + Placeholders（5-15分钟） HTML文件头部先写你的**assumptions+reasoning comments**，像junior给manager汇报： ```html <!-- 我的假设： - 这是给XX受众看的 - 整体tone我理解为XX（基于用户说的"专业但不严肃"） - 主要flow是A→B→C - 色彩我想用品牌蓝+暖灰，不确定你想不想要accent色 未解的问题： - 第3步的数据从哪里来？先用placeholder - 背景图用抽象几何还是真照片？先占位 如果你看到这里觉得方向不对，现在是成本最低的时候改。 --> <!-- 然后是带placeholder的结构 --> <section class="hero"> <h1>[主标题位 - 等用户提供]</h1> <p>[副标题位]</p> <div class="cta-placeholder">[CTA按钮]</div> </section> ``` **保存 → show用户 → 等反馈再走下一步**。 ### Pass 2：真实组件+Variations（主力工作量） 用户批准方向后，开始填充。这时： - 写React组件替换placeholder - 做variations（用design_canvas或Tweaks） - 如果是幻灯片/动画，用starter components起手 **做到一半再show一次**——不要等全做完。设计方向错了，晚show等于白做。 ### Pass 3：细节打磨 用户满意整体后，打磨： - 字号/间距/对比度微调 - 动画timing - 边界case - Tweaks面板完善 ### Pass 4：验证+交付 - 用Playwright截图（见`references/verification.md`） - 打开浏览器肉眼确认 - 总结**极简**：只说caveats和next steps ## Variations的深度逻辑 给variations不是给用户制造选择困难，是**探索可能性空间**。让用户mix and match出最终版本。 ### 好的variations长什么样 - **维度明确**：每个variation在不同维度上变（A vs B只换配色，C vs D只换layout） - **有梯度**：从「by-the-book保守版」到「大胆novel版」逐级递进 - **有记号**：每个variation有短label说明它在探索什么 ### 实现方式 **纯视觉对比**（静态）： → 用`assets/design_canvas.jsx`，网格布局并排展示。每个cell带label。 **多选项/交互差异**： → 做完整原型，用Tweaks切换。例如做登录页，"布局"是tweak的一个选项： - 左文案右表单 - 顶部logo+中央表单 - 背景全屏图+浮层表单 用户开关Tweaks就能切换，不需要打开多个HTML文件。 ### 探索矩阵思考 每次设计，脑内过一遍这些维度，挑2-3个来给variations： - 视觉：minimal / editorial / brutalist / organic / futuristic / retro - 色彩：monochrome / dual-tone / vibrant / pastel / high-contrast - 字型：sans-only / sans+serif对比 / 全衬线 / 等宽 - Layout：对称 / 非对称 / 不规则grid / full-bleed / 窄栏 - Density：稀疏呼吸 / 中等 / 信息密集 - 交互：极简hover / 丰富micro-interaction / 夸张大动画 - 材质：flat / 有阴影层次 / 纹理 / noise / 渐变 ## 遇到不确定的情况 - **不知道怎么做**：坦白说你不确定，问用户，或先做个placeholder继续。**不要编**。 - **用户的描述矛盾**：指出矛盾，让用户选一个方向。 - **任务太大一次吃不下**：拆成steps，先做第一步让用户看，再推进。 - **用户要求的效果技术上很难**：说清技术边界，提供替代方案。 ## 总结规则 交付时，summary **极短**： ```markdown ✅ 幻灯片已完成（10张），带Tweaks可切换"夜/日模式"。 注意： - 第4页的数据是假的，等你提供真数据我替换 - 动画用了CSS transition，不需要JS 下一步建议：先你浏览器打开看一遍，有问题告诉我哪页哪处。 ``` 不要： - 罗列每一页的内容 - 重复讲你用了什么技术 - 夸自己设计多好 Caveats + next steps，结束。
-
-
scripts
-
cloud
-
ai-review-video.py 20 KB
#!/usr/bin/env python3 # /// script # requires-python = ">=3.10" # dependencies = [ # "requests>=2.28.0", # ] # /// """ AI看片评审闭环 —— 渲染出的动画MP4喂给视频理解模型（seed-2.0-lite）， 按固定checklist逐段送审 + 全片低清扫一遍，汇总成结构化markdown评审报告。 ⚠️ 可选云能力：会把压缩后的成片片段发送到火山方舟官方接口（ark.cn-beijing.volces.com） 做视频理解评审，使用你自己的 ARK_API_KEY。首次调用需 --yes 或 HUASHU_CLOUD_OK=1 显式确认。数据流向声明见仓库根 SECURITY.md。本地免费替代：scripts/verify-video.sh 截帧人工看。 Usage: uv run ai-review-video.py --video 成片.mp4 --yes uv run ai-review-video.py --video 成片.mp4 --context 导演稿.md --yes uv run ai-review-video.py --video 成片.mp4 --segment-len 60 --output 报告.md --yes 调用链路： 1. ffprobe 探测时长/音轨 2. 有音轨 → ffmpeg silencedetect 提取音效onset时间表（模型听不到视频音轨， 实测2026-07-17：input_video只送画面。音画对位检查=本地onset+模型画面核对） 3. 按 --segment-len 切段并压缩（1280宽/15fps/crf28，扁平动画约0.5MB/分钟） 4. 逐段送审（checklist①-⑧），每段prompt标注原片时间范围 5. 全片再压一版低清（960宽/10fps）单独送审，专查跨段叙事连贯/hero贯穿 6. 文本汇总call：按checklist逐项合并，产出最终报告；分段原始发现保留在附录 API key：优先读环境变量 ARK_API_KEY，其次读 skill 根目录 .env（只提取这一个变量），绝不硬编码。 代理：requests session 关闭 trust_env（不继承本机代理配置），免疫 ALL_PROXY 之类残留代理导致的 TLS 报错。 """ import argparse import json import os import re import subprocess import sys import tempfile import time from base64 import b64encode from pathlib import Path import requests API_URL = "https://ark.cn-beijing.volces.com/api/v3/responses" DEFAULT_MODEL = "doubao-seed-2-0-lite-260215" ENV_PATH = Path(__file__).resolve().parents[2] / ".env" # skill 根目录 .env（已 gitignore） MAX_SEGMENT_MB = 8 # 单段压缩产物超过这个值就再压一档 CHECKLIST = """\ ① 黑帧/空窗/渲染残缺：整帧或大面积黑屏、白屏、元素未渲染出来、明显破图 ② 文字问题：字卡/标签被裁切、溢出容器、错字、乱码、字叠字 ③ 元素重叠遮挡：不该重叠的元素互相遮挡、层级错误、穿模 ④ 叙事连贯性：场景过渡分三类——硬切（前后帧整页突变，无任何衔接）、 交叉淡入淡出（旧场景透明度渐隐）、morph（元素连续变形/位移到新场景）。 报告时必须写明你看到的是哪一类，不要把淡入淡出误报成硬切； 硬切=⚡，淡入淡出在导演稿要求morph时=💡「过渡偷懒」 ⑤ hero/主体贯穿性：如果有贯穿全片的主体元素，它是否在场景切换中断裂、消失、突变位置 ⑥ 节奏死段：见下方「静止段客观检测表」（ffmpeg逐帧检测，≥3秒完全静止的区间）。 你的任务不是找死段，而是对表中每个区间判断：是刻意hold（字卡阅读/弹幕停留/收尾定格） 还是真死段（画面无信息可读还停着）。刻意hold=不报或💡，真死段=⚡ ⑦ 音效打点（见下方onset时间表）：核对每个音效时间点画面是否有对应事件 ⑧ 构图：明显失衡、大片无意义空白、重要元素贴边或被挤到角落""" SEVERITY_RULE = """\ 严重度分三级： - ⚠️致命：交付前必须修（黑帧、错字、文字被裁、元素叠死、明显破图） - ⚡重要：观感明显受损（硬切感、hero断裂、超3秒死段、构图明显失衡） - 💡建议：锦上添花的改进点""" def log(msg): print(msg, file=sys.stderr, flush=True) def load_api_key(): key = os.getenv("ARK_API_KEY") if not key and ENV_PATH.exists(): # 只提取 ARK_API_KEY 一个变量，不把 .env 整文件灌进环境 for line in ENV_PATH.read_text(encoding="utf-8").splitlines(): line = line.strip() if line.startswith("ARK_API_KEY") and "=" in line: key = line.split("=", 1)[1].strip().strip("'\"") break if not key or key.startswith("your_"): sys.exit("Error: ARK_API_KEY 未配置（skill 根目录 .env 或环境变量），拒绝继续。不编造评审结果。") return key def run(cmd): r = subprocess.run(cmd, capture_output=True, text=True) if r.returncode != 0: raise RuntimeError(f"命令失败: {' '.join(cmd)}\n{r.stderr[-2000:]}") return r def probe(video: Path): r = run(["ffprobe", "-v", "error", "-show_entries", "format=duration", "-show_entries", "stream=codec_type", "-of", "json", str(video)]) info = json.loads(r.stdout) duration = float(info["format"]["duration"]) has_audio = any(s.get("codec_type") == "audio" for s in info.get("streams", [])) return duration, has_audio def detect_audio_onsets(video: Path, noise_db=-45, min_silence=0.3): """silencedetect反推音效onset。返回原片秒数列表。""" r = subprocess.run( ["ffmpeg", "-i", str(video), "-af", f"silencedetect=noise={noise_db}dB:d={min_silence}", "-f", "null", "-"], capture_output=True, text=True) onsets = [round(float(m), 1) for m in re.findall(r"silence_end:\s*([\d.]+)", r.stderr)] # 片头非静音（开场即有声）时补0 starts = re.findall(r"silence_start:\s*([\d.-]+)", r.stderr) if starts and float(starts[0]) > min_silence: onsets.insert(0, 0.0) return onsets def detect_static_segments(video: Path, noise=0.001, min_dur=3.0): """freezedetect找≥min_dur秒完全静止的区间。返回[(start,end)]原片秒。""" r = subprocess.run( ["ffmpeg", "-i", str(video), "-vf", f"freezedetect=n={noise}:d={min_dur}", "-f", "null", "-"], capture_output=True, text=True) starts = re.findall(r"freeze_start:\s*([\d.]+)", r.stderr) durs = re.findall(r"freeze_duration:\s*([\d.]+)", r.stderr) return [(round(float(s), 1), round(float(s) + float(d), 1)) for s, d in zip(starts, durs)] def compress(src: Path, dst: Path, ss=None, t=None, width=1280, fps=15, crf=28): cmd = ["ffmpeg", "-y", "-v", "error"] if ss is not None: cmd += ["-ss", str(ss)] if t is not None: cmd += ["-t", str(t)] cmd += ["-i", str(src), "-vf", f"scale={width}:-2,fps={fps}", "-c:v", "libx264", "-crf", str(crf), "-preset", "veryfast", "-pix_fmt", "yuv420p", "-an", str(dst)] run(cmd) def fmt_ts(sec: float) -> str: return f"{int(sec) // 60}:{int(sec) % 60:02d}" def ask_model(session, api_key, model, prompt, video_path: Path | None = None, retries=1): content = [] if video_path is not None: b64 = b64encode(video_path.read_bytes()).decode() content.append({"type": "input_video", "video_url": f"data:video/mp4;base64,{b64}"}) content.append({"type": "input_text", "text": prompt}) payload = {"model": model, "input": [{"role": "user", "content": content}]} last_err = None for attempt in range(retries + 1): try: resp = session.post( API_URL, json=payload, timeout=600, headers={"Authorization": f"Bearer {api_key}", "Content-Type": "application/json"}) if resp.status_code != 200: last_err = f"API {resp.status_code}: {resp.text[:500]}" continue data = resp.json() usage = data.get("usage", {}) text = "" out = data.get("output") if isinstance(out, list): for item in out: if isinstance(item, dict) and item.get("type") == "message": for c in item.get("content", []): if isinstance(c, dict) and c.get("type") == "output_text": text += c.get("text", "") elif isinstance(out, str): text = out if not text: choices = data.get("choices", []) if choices: text = choices[0].get("message", {}).get("content", "") if text: return text, usage last_err = f"响应无文本: {json.dumps(data, ensure_ascii=False)[:500]}" except requests.RequestException as e: last_err = f"网络错误: {e}" if attempt < retries: log(f" 重试（{last_err[:120]}）...") time.sleep(3) raise RuntimeError(last_err) def segment_prompt(seg_start, seg_end, duration, context_text, onsets_in_seg, statics_in_seg): p = [f"你是动画成片质检员，任务是严格挑毛病，不夸片子。", f"这段视频是一部总长{fmt_ts(duration)}的动画成片的一个片段，" f"对应原片 {fmt_ts(seg_start)}–{fmt_ts(seg_end)}。" f"片段内第t秒 = 原片第{fmt_ts(seg_start)}+t秒，报告里一律用原片时间（分:秒）。"] if context_text: p.append("以下是全片导演稿（评审上下文，用来判断叙事意图和该出现什么）：\n" "<导演稿>\n" + context_text + "\n</导演稿>") p.append("逐项检查以下checklist，只报本片段内的发现：\n" + CHECKLIST) if statics_in_seg: ts = "、".join(f"{fmt_ts(a)}–{fmt_ts(b)}（{b - a:.1f}s）" for a, b in statics_in_seg) p.append(f"⑥的静止段客观检测表（本段内，原片时间）：{ts}。逐个判断刻意hold还是真死段。") else: p.append("本片段内无≥3秒静止段，⑥直接写「未发现」。") if onsets_in_seg: ts = "、".join(f"{fmt_ts(t)}({t}s)" for t in onsets_in_seg) p.append(f"⑦的onset时间表（本段内音效实际出现的原片时间）：{ts}。" f"你听不到声音，只需核对这些时间点画面上是否有值得配音效的事件" f"（转场/字卡落定/撞击/元素出现），没有对应事件的时间点=音效打空，要报。") else: p.append("本片段内没有检测到音效onset，⑦跳过；但如果本段有强烈画面事件" "（撞击/字卡/转场）却无音效覆盖，可在⑦下用💡提出。") p.append(SEVERITY_RULE) p.append("输出格式：markdown。按①-⑧逐项，每项下用列表：\n" "- [原片分:秒] 严重度emoji 具体描述\n" "该项无问题就写「未发现」。只报你真正看到的，不确定的标「存疑」，不编造。") return "\n\n".join(p) def global_prompt(duration, context_text): p = ["你是动画成片质检员。这是一部动画成片的全片低清版（评审用压缩，画质低是正常的，" "不要报画质/清晰度问题），总长" + fmt_ts(duration) + "。"] if context_text: p.append("导演稿：\n<导演稿>\n" + context_text + "\n</导演稿>") p.append("只做三件事（细节问题已有分段评审负责，你不用管）：\n" "A. 叙事连贯性：从头到尾看，哪些时间点是PowerPoint式硬切（整页突变无过渡）？\n" "B. hero/主体贯穿性：贯穿全片的主体元素在哪些切换处断裂、消失或突变？\n" "C. 整体节奏：哪些区间拖（长时间无新信息）、哪些区间赶？\n\n" + SEVERITY_RULE + "\n\n输出markdown，A/B/C三节，发现带[分:秒]时间点。无问题写「未发现」。不编造。") return "\n\n".join(p) def synthesis_prompt(duration, seg_reports, global_report): parts = ["你是评审报告主编。下面是同一部" + fmt_ts(duration) + "动画成片的分段评审 + 全片评审原始记录，把它们合并成一份最终报告正文。", "要求：\n" "1. 按checklist①-⑧逐项组织，每项下按时间顺序列发现：- [分:秒] 严重度 描述\n" "2. 同一问题被多段重复报的合并成一条；分段与全片评审矛盾时两说并存标「存疑」\n" "3. 保留每条发现的时间点和严重度emoji（⚠️/⚡/💡），不新增原始记录里没有的发现\n" "4. 开头给一个「问题总数：⚠️x ⚡y 💡z」的统计行和三句话以内的总评\n" "5. 只输出报告正文markdown，不要客套话", "<全片评审>\n" + global_report + "\n</全片评审>"] for (s, e, text) in seg_reports: parts.append(f"<分段评审 原片{fmt_ts(s)}–{fmt_ts(e)}>\n{text}\n</分段评审>") return "\n\n".join(parts) def main(): ap = argparse.ArgumentParser(description="AI看片评审：动画MP4 → checklist结构化评审报告") ap.add_argument("--video", required=True, help="成片路径（mp4）") ap.add_argument("--context", help="导演稿/分幕说明md路径（可选，作为评审上下文）") ap.add_argument("--segment-len", type=int, default=60, help="分段长度秒（默认60）") ap.add_argument("--model", default=DEFAULT_MODEL, help=f"模型（默认{DEFAULT_MODEL}）") ap.add_argument("--output", "-o", help="报告路径（默认视频同目录<视频名>-AI评审.md）") ap.add_argument("--yes", action="store_true", help="确认将压缩后的视频段发送到火山方舟官方接口（或设 HUASHU_CLOUD_OK=1）") args = ap.parse_args() video = Path(args.video).resolve() if not video.exists(): sys.exit(f"Error: 视频不存在 {video}") if not args.yes and os.getenv("HUASHU_CLOUD_OK") != "1": sys.exit( f"[云能力确认] 本次将把 {video.name} 压缩后分段发送到 ark.cn-beijing.volces.com" "（火山方舟官方接口，使用你自己的 ARK_API_KEY 做视频理解评审）。\n" "确认无误请重跑并加 --yes，或设置环境变量 HUASHU_CLOUD_OK=1。" "数据流向声明见 SECURITY.md；本地免费替代：scripts/verify-video.sh。") out_path = Path(args.output) if args.output else video.parent / f"{video.stem}-AI评审.md" context_text = "" if args.context: ctx = Path(args.context) if not ctx.exists(): sys.exit(f"Error: 上下文文件不存在 {ctx}") context_text = ctx.read_text(encoding="utf-8")[:12000] api_key = load_api_key() session = requests.Session() session.trust_env = False # 免疫 ALL_PROXY 等代理坑 duration, has_audio = probe(video) log(f"视频 {fmt_ts(duration)}，音轨={'有' if has_audio else '无'}") onsets = detect_audio_onsets(video) if has_audio else [] if has_audio: log(f"音效onset检测：{len(onsets)}个 → {['%.1f' % t for t in onsets]}") # 静止段客观检测（相邻区间合并） raw_statics = detect_static_segments(video) statics = [] for a, b in raw_statics: if statics and a - statics[-1][1] < 0.2: statics[-1] = (statics[-1][0], b) else: statics.append((a, b)) log(f"静止段检测（≥3s）：{len(statics)}个 → " f"{[f'{a:.0f}-{b:.0f}s' for a, b in statics]}") total_usage = {"input_tokens": 0, "output_tokens": 0} def add_usage(u): for k in total_usage: total_usage[k] += u.get(k, 0) or 0 seg_reports, failures = [], [] with tempfile.TemporaryDirectory(prefix="ai-review-") as tmp: tmp = Path(tmp) # 分段 bounds = [] t0 = 0.0 while t0 < duration - 1: bounds.append((t0, min(t0 + args.segment_len, duration))) t0 += args.segment_len log(f"分段：{len(bounds)}段 × ≤{args.segment_len}s") for i, (s, e) in enumerate(bounds, 1): seg = tmp / f"seg{i}.mp4" compress(video, seg, ss=s, t=e - s) if seg.stat().st_size > MAX_SEGMENT_MB * 1024 * 1024: compress(video, seg, ss=s, t=e - s, width=960, fps=10, crf=32) mb = seg.stat().st_size / 1048576 onsets_in = [t for t in onsets if s <= t < e] statics_in = [(a, b) for a, b in statics if a < e and b > s] log(f"段{i} {fmt_ts(s)}–{fmt_ts(e)}（{mb:.1f}MB，onset×{len(onsets_in)}，" f"静止段×{len(statics_in)}）送审...") try: text, usage = ask_model(session, api_key, args.model, segment_prompt(s, e, duration, context_text, onsets_in, statics_in), seg) add_usage(usage) seg_reports.append((s, e, text)) except RuntimeError as err: log(f" 段{i}送审失败：{err}") failures.append((s, e, str(err))) # 全片低清pass log("全片低清版送审（叙事/hero/节奏）...") full = tmp / "full.mp4" compress(video, full, width=960, fps=10, crf=30) global_report, global_fail = "", None try: global_report, usage = ask_model(session, api_key, args.model, global_prompt(duration, context_text), full) add_usage(usage) except RuntimeError as err: global_fail = str(err) log(f" 全片pass失败：{err}") if not seg_reports and not global_report: sys.exit("Error: 所有送审调用均失败，无法产出报告。不编造评审结果。\n" + "\n".join(f"{fmt_ts(s)}–{fmt_ts(e)}: {m}" for s, e, m in failures)) # 汇总 log("汇总最终报告...") try: body, usage = ask_model(session, api_key, args.model, synthesis_prompt(duration, seg_reports, global_report or "（全片pass调用失败，无记录）")) add_usage(usage) except RuntimeError as err: log(f"汇总call失败（{err}），退化为原始记录拼接") body = "> 汇总call失败，以下为各pass原始记录直接拼接。\n\n" + \ (global_report or "") + "\n\n" + \ "\n\n".join(f"## 分段 {fmt_ts(s)}–{fmt_ts(e)}\n{t}" for s, e, t in seg_reports) lines = [f"# {video.name} · AI评审报告", "", f"> 模型：{args.model} | 评审时间：{time.strftime('%Y-%m-%d %H:%M')} | " f"片长：{fmt_ts(duration)} | 分段：{len(seg_reports)}成功/{len(failures)}失败 | " f"音效onset：{len(onsets)}个 / 静止段≥3s：{len(statics)}个" f"（均为本地ffmpeg客观检测；模型不闻声，音画对位=onset+画面核对） | " f"tokens：in {total_usage['input_tokens']} / out {total_usage['output_tokens']}", ""] if failures: lines.append("> ⚠️ 以下时间段送审失败，未被评审覆盖：" + "；".join(f"{fmt_ts(s)}–{fmt_ts(e)}（{m[:100]}）" for s, e, m in failures)) lines.append("") if global_fail: lines.append(f"> ⚠️ 全片连贯性pass调用失败：{global_fail[:200]}") lines.append("") lines.append(body) lines.append("\n\n---\n\n## 附录 · 客观检测数据（ffmpeg，非模型判断）\n") lines.append("静止段≥3s：" + ("、".join( f"{fmt_ts(a)}–{fmt_ts(b)}（{b - a:.1f}s）" for a, b in statics) or "无")) lines.append("\n音效onset：" + ("、".join(fmt_ts(t) for t in onsets) or "无/无音轨")) lines.append("\n## 附录 · 各段原始评审记录\n") if global_report: lines.append("### 全片pass（叙事/hero/节奏）\n\n" + global_report + "\n") for s, e, t in seg_reports: lines.append(f"### 分段 原片{fmt_ts(s)}–{fmt_ts(e)}\n\n{t}\n") out_path.write_text("\n".join(lines), encoding="utf-8") log(f"报告已写入: {out_path}") print(out_path) if __name__ == "__main__": main() -
tts-doubao.mjs 9.8 KB · in bundle
-
-
add-music.sh 4.1 KB
#!/usr/bin/env bash # Mix a BGM track into an MP4 video. # # Usage: # bash add-music.sh <input.mp4> [--mood=<name>] [--music=<path>] [--out=<path>] # # Mood library (in ../assets/, matching bgm-<mood>.mp3): # tech — Apple Silicon / product keynote vibe, minimal synth+piano (default) # ad — upbeat modern, clear build + drop, social-media ad energy # educational — warm, patient, inviting learning tone # educational-alt — alternate take of educational # tutorial — lo-fi background, stays out of voiceover's way # tutorial-alt — alternate take of tutorial # # Flags (all optional): # --mood=<name> pick a preset from the library (default: tech) # --music=<path> override with your own audio file (wins over --mood) # --out=<path> output path (default: <input-basename>-bgm.mp4) # # Legacy positional form still works: bash add-music.sh in.mp4 music.mp3 out.mp4 # # Behavior: # - Music is trimmed to match video duration # - 0.3s fade in, 1.0s fade out (avoids hard cuts) # - Video stream copied (no re-encode), audio AAC 192k # # Examples: # bash add-music.sh my.mp4 # default: tech mood # bash add-music.sh my.mp4 --mood=ad # switch mood # bash add-music.sh my.mp4 --mood=educational --out=final.mp4 # bash add-music.sh my.mp4 --music=~/Downloads/song.mp3 # bring your own # set -e SCRIPT_DIR="$(cd "$(dirname "$0")" && pwd)" ASSETS_DIR="$SCRIPT_DIR/../assets" # ── Parse args ─────────────────────────────────────────────────────── INPUT="" MOOD="tech" CUSTOM_MUSIC="" OUTPUT="" POSITIONAL=() for arg in "$@"; do case "$arg" in --mood=*) MOOD="${arg#*=}" ;; --music=*) CUSTOM_MUSIC="${arg#*=}" ;; --out=*) OUTPUT="${arg#*=}" ;; *) POSITIONAL+=("$arg") ;; esac done # Legacy positional: <input> [music] [output] INPUT="${POSITIONAL[0]}" [ -z "$CUSTOM_MUSIC" ] && [ -n "${POSITIONAL[1]}" ] && CUSTOM_MUSIC="${POSITIONAL[1]}" [ -z "$OUTPUT" ] && [ -n "${POSITIONAL[2]}" ] && OUTPUT="${POSITIONAL[2]}" if [ -z "$INPUT" ] || [ ! -f "$INPUT" ]; then echo "Usage: bash add-music.sh <input.mp4> [--mood=<name>] [--music=<path>] [--out=<path>]" >&2 echo "Moods available: $(ls "$ASSETS_DIR" | grep -E '^bgm-.*\.mp3$' | sed 's/^bgm-//;s/\.mp3$//' | tr '\n' ' ')" >&2 exit 1 fi # ── Resolve music source: --music wins, else --mood ───────────────── if [ -n "$CUSTOM_MUSIC" ]; then MUSIC="$CUSTOM_MUSIC" SOURCE_LABEL="custom: $MUSIC" else MUSIC="$ASSETS_DIR/bgm-${MOOD}.mp3" SOURCE_LABEL="mood: $MOOD" fi if [ ! -f "$MUSIC" ]; then echo "✗ Music not found: $MUSIC" >&2 echo " Available moods: $(ls "$ASSETS_DIR" | grep -E '^bgm-.*\.mp3$' | sed 's/^bgm-//;s/\.mp3$//' | tr '\n' ' ')" >&2 exit 1 fi # ── Resolve output path ───────────────────────────────────────────── INPUT_DIR="$(cd "$(dirname "$INPUT")" && pwd)" INPUT_NAME="$(basename "$INPUT" .mp4)" [ -z "$OUTPUT" ] && OUTPUT="$INPUT_DIR/$INPUT_NAME-bgm.mp4" # ── Measure video duration, compute fade-out start ────────────────── DURATION=$(ffprobe -v error -show_entries format=duration -of default=noprint_wrappers=1:nokey=1 "$INPUT") if [ -z "$DURATION" ]; then echo "✗ Could not read video duration" >&2 exit 1 fi FADE_OUT_START=$(awk "BEGIN { d = $DURATION - 1; if (d < 0) d = 0; print d }") echo "▸ Mixing BGM into video" echo " input: $INPUT" echo " music: $SOURCE_LABEL" echo " duration: ${DURATION}s" echo " output: $OUTPUT" ffmpeg -y -loglevel error \ -i "$INPUT" \ -i "$MUSIC" \ -filter_complex "[1:a]atrim=0:${DURATION},asetpts=PTS-STARTPTS,afade=t=in:st=0:d=0.3,afade=t=out:st=${FADE_OUT_START}:d=1[a]" \ -map 0:v -map "[a]" \ -c:v copy -c:a aac -b:a 192k -shortest \ "$OUTPUT" SIZE=$(du -h "$OUTPUT" | cut -f1) echo "✓ Done: $OUTPUT ($SIZE)" -
convert-formats.sh 2.9 KB
#!/bin/bash # Convert MP4 animations to 60fps MP4 and optimized GIF. # # Usage: # ./convert-formats.sh input.mp4 [gif_width] [--minterpolate] # # Produces next to the input: # <name>-60fps.mp4 (1920x1080, 60fps, frame-duplicated by default) # <name>.gif (scaled width, 15fps, palette-optimized) # # Flags: # --minterpolate Enable motion-compensated interpolation (high quality # but elementary stream has known QuickTime/Safari # compat issues — only use if your player handles it). # # Default 60fps mode: simple `fps=60` filter (frame duplication). Wide # compatibility, plays in QuickTime / Safari / Chrome / VLC. The 60fps # label is for upload-platform optics; perceived smoothness is identical # to the source 25fps for most CSS-driven motion. # # When to enable --minterpolate: heavy translate/scale motion where you # want true 60fps interpolation. WARN: macOS QuickTime sometimes refuses # to open minterpolate output. Test before delivering. # # GIF uses two-pass palette: # pass 1: palettegen with stats_mode=diff (per-video optimal palette) # pass 2: paletteuse with bayer dither + rectangle diff # This keeps 30s/1080p animations GIF under ~4MB with good color fidelity. set -e INPUT="" GIF_WIDTH="960" USE_MINTERPOLATE=0 for arg in "$@"; do case "$arg" in --minterpolate) USE_MINTERPOLATE=1 ;; --*) echo "Unknown flag: $arg" >&2; exit 1 ;; *) if [ -z "$INPUT" ]; then INPUT="$arg" else GIF_WIDTH="$arg" fi ;; esac done [ -z "$INPUT" ] && { echo "Usage: $0 input.mp4 [gif_width] [--minterpolate]" >&2; exit 1; } DIR=$(dirname "$INPUT") BASE=$(basename "$INPUT" .mp4) OUT60="$DIR/$BASE-60fps.mp4" OUTGIF="$DIR/$BASE.gif" PAL="$DIR/.palette-$BASE.png" if [ "$USE_MINTERPOLATE" = "1" ]; then echo "▸ 60fps interpolate (minterpolate, high quality): $OUT60" VFILTER="minterpolate=fps=60:mi_mode=mci:mc_mode=aobmc:me_mode=bidir:vsbmc=1" else echo "▸ 60fps frame-duplicate (compat mode): $OUT60" VFILTER="fps=60" fi # -profile:v high -level 4.0 → broad H.264 compatibility (QuickTime, Safari, mobile) # -movflags +faststart → moov atom upfront, streamable / instant-play ffmpeg -y -loglevel error -i "$INPUT" \ -vf "$VFILTER" \ -c:v libx264 -pix_fmt yuv420p -profile:v high -level 4.0 \ -crf 18 -preset medium -movflags +faststart \ "$OUT60" MP4_SIZE=$(du -h "$OUT60" | cut -f1) echo " ✓ $MP4_SIZE" echo "▸ GIF (${GIF_WIDTH}w, 15fps, palette-optimized): $OUTGIF" # Pass 1: generate palette tailored to this video ffmpeg -y -loglevel error -i "$INPUT" \ -vf "fps=15,scale=${GIF_WIDTH}:-1:flags=lanczos,palettegen=stats_mode=diff" \ "$PAL" # Pass 2: apply palette with dithering ffmpeg -y -loglevel error -i "$INPUT" -i "$PAL" \ -lavfi "fps=15,scale=${GIF_WIDTH}:-1:flags=lanczos[x];[x][1:v]paletteuse=dither=bayer:bayer_scale=5:diff_mode=rectangle" \ "$OUTGIF" rm -f "$PAL" GIF_SIZE=$(du -h "$OUTGIF" | cut -f1) echo " ✓ $GIF_SIZE" -
design-gate-hook.sh 3.4 KB
#!/bin/bash # design-gate-hook.sh — PreToolUse(Bash) hook：长片渲染前检查设计流程gate文件 # # 铁律背景（2026-07-17花叔立）：huashu-design做设计前必须①资产协议(brand-spec.md) # ②三方向真实视觉给用户选(direction-approved.md记录选择或豁免理由)。 # B00(210s)实测：跳过方向确认直接渲全片→整片返工。此hook把教训变成机器约束： # **时长≥45秒的合成，缺direction-approved.md就不许渲**——长片返工的代价远大于停一下。 # # 放行条件（任一）： # - 合成时长<45s或无法判定（短片/实验低摩擦，靠SKILL.md gate协议约束） # - 项目目录（或上两级）存在 direction-approved.md # - 命令里显式带 SKIP_DESIGN_GATE=1（花叔明说跳过时用，可审计） # # 安全声明：本hook**不会被skill自动安装**——SKILL.md/README没有任何写入settings.json的 # 指令，只有你手动把它配进settings.json后才生效。行为上限：对匹配的长片渲染命令exit 2 # 阻止执行并打印原因，无网络请求、无文件写入、无删除。见仓库根SECURITY.md。 # # settings.json配置：PreToolUse / matcher "Bash" / command指向本脚本 INPUT=$(cat) CMD=$(printf '%s' "$INPUT" | python3 -c "import json,sys;print(json.load(sys.stdin).get('tool_input',{}).get('command',''))" 2>/dev/null) CWD=$(printf '%s' "$INPUT" | python3 -c "import json,sys;print(json.load(sys.stdin).get('cwd',''))" 2>/dev/null) # 谈论命令的命令（echo/grep等）直接放行，防纯文本误伤（QA Bug1） FIRST=$(echo "$CMD" | sed -E 's/^[[:space:]]*//' | cut -d' ' -f1) case "$FIRST" in echo|printf|grep|cat|ls|head|tail|wc|sed|awk) exit 0;; esac # 只管渲染命令（含npm run render与解说长片渲染） echo "$CMD" | grep -qE "hyperframes(@[0-9.]+)? +render|render-video(-seek)?\.js|render-narration\.sh|npm +run +render\b" || exit 0 # 显式跳过（可审计的逃生门） echo "$CMD" | grep -q "SKIP_DESIGN_GATE=1" && exit 0 # 定位项目目录：命令中cd的目标 > hook cwd DIR="$CWD" CDDIR=$(echo "$CMD" | grep -oE 'cd +"[^"]+"|cd +[^ &;]+' | head -1 | sed -E 's/^cd +//; s/"//g') [ -n "$CDDIR" ] && [ -d "$CDDIR" ] && DIR="$CDDIR" # 取合成时长：hyperframes项目读index.html的data-duration；render-video-seek读--duration参数 DUR="" D_ARG=$(echo "$CMD" | grep -oE '\-\-duration=[0-9]+' | head -1 | cut -d= -f2) [ -n "$D_ARG" ] && DUR="$D_ARG" if [ -z "$DUR" ] && [ -f "$DIR/index.html" ]; then DUR=$(grep -oE 'data-duration="[0-9.]+"' "$DIR/index.html" | head -1 | grep -oE '[0-9.]+' | cut -d. -f1) fi # 判不出时长或短片 → 放行 [ -z "$DUR" ] && exit 0 [ "$DUR" -lt 45 ] 2>/dev/null && exit 0 # 长片：查gate文件（项目目录及上两级） for d in "$DIR" "$DIR/.." "$DIR/../.."; do [ -f "$d/direction-approved.md" ] && exit 0 done cat >&2 << EOF 🛑 设计流程gate：该合成时长${DUR}s（≥45s长片），但项目内未找到 direction-approved.md。 huashu-design铁律：长片渲染前必须完成「三方向真实视觉给用户选择」（或用户明示豁免），并把选择/豁免记录写入项目目录的 direction-approved.md（含：展示了哪几版、截图路径、用户的选择原话）。 补齐后重渲；用户当面明说跳过时，在命令前加 SKIP_DESIGN_GATE=1 显式放行。 （依据：2026-07-17 B00实测，跳过方向确认渲210s全片→整片视觉返工） EOF exit 2 -
export_deck_pdf.mjs 3.1 KB · in bundle
-
export_deck_pptx.mjs 3.7 KB · in bundle
-
export_deck_stage_pdf.mjs 4.7 KB · in bundle
-
fetch_images.py 4.3 KB
#!/usr/bin/env python3 """ 从 Wikimedia Commons 抓真实图片（公共领域 / CC），供 huashu-design「内容型设计取真图」用（Phase 3.5）。 为什么有这个脚本：内容型设计（鹦鹉/咖啡/马来西亚…）必须用真图，不能 CSS 色块糊弄。 每次让模型现写抓图逻辑既慢又容易漏坑（忘清代理→TLS 炸 / 忘合规 UA→429）。这里固化好，下次只改关键词。 用法： python3 scripts/fetch_images.py --query "Petronas Towers" "Langkawi beach" "George Town street" \ --out 项目/assets/img --count 2 --width 1600 每个 query 取前 count 张、缩放到 width、下载到 out，并打印清单（路径 | 许可 | 作者 | 来源页）便于诚实性核对。 全部抓不到 → 退出码 1，提示走 Phase 3.5 取图三级兜底（Unsplash/Pexels → 生图 → 诚实 placeholder）。 """ import argparse, json, os, re, sys, urllib.parse, urllib.request # ① 清代理：本机 curl/urllib 走代理会 TLS 炸（见 memory feedback_gemini_proxy） for _k in ("ALL_PROXY", "all_proxy", "HTTP_PROXY", "http_proxy", "HTTPS_PROXY", "https_proxy"): os.environ.pop(_k, None) API = "https://commons.wikimedia.org/w/api.php" # ② 合规 User-Agent 是硬性要求，否则 Wikimedia 返 429 UA = "huashu-design-image-fetcher/1.0 (https://huasheng.ai; skill contact)" def _api_get(params): url = API + "?" + urllib.parse.urlencode(params) req = urllib.request.Request(url, headers={"User-Agent": UA}) with urllib.request.urlopen(req, timeout=30) as r: return json.load(r) def _safe(name): return re.sub(r"[^\w\-.]", "_", name)[:60] def fetch(query, out, count, width): params = { "action": "query", "format": "json", "generator": "search", "gsrsearch": query, "gsrnamespace": 6, "gsrlimit": count, "prop": "imageinfo", "iiprop": "url|extmetadata", "iiurlwidth": width, } try: data = _api_get(params) except Exception as e: print(f"[FAIL search] {query}: {e}", file=sys.stderr) return [] pages = (data.get("query", {}) or {}).get("pages", {}) got = [] for p in list(pages.values())[:count]: ii = (p.get("imageinfo") or [{}])[0] thumb = ii.get("thumburl") or ii.get("url") if not thumb: continue meta = ii.get("extmetadata", {}) or {} lic = (meta.get("LicenseShortName", {}) or {}).get("value", "?") artist = re.sub("<[^>]+>", "", (meta.get("Artist", {}) or {}).get("value", "?")).strip() ext = os.path.splitext(thumb)[1].split("?")[0] or ".jpg" fn = _safe(query) + "_" + _safe(p.get("title", "img").replace("File:", "")) fn = os.path.splitext(fn)[0][:55] + ext path = os.path.join(out, fn) try: req = urllib.request.Request(thumb, headers={"User-Agent": UA}) with urllib.request.urlopen(req, timeout=60) as r, open(path, "wb") as f: f.write(r.read()) got.append(path) print(f"[OK] {path} | {lic} | {artist} | {ii.get('descriptionurl','')}") except Exception as e: print(f"[FAIL dl] {thumb}: {e}", file=sys.stderr) if not got: print(f"[EMPTY] 「{query}」没抓到——换关键词，或走 Phase 3.5 兜底", file=sys.stderr) return got def main(): ap = argparse.ArgumentParser(description="Wikimedia Commons 真图抓取（huashu-design Phase 3.5）") ap.add_argument("--query", nargs="+", required=True, help="一个或多个英文关键词（英文命中率高）") ap.add_argument("--out", required=True, help="输出目录（建议 项目/assets/img）") ap.add_argument("--count", type=int, default=2, help="每个关键词抓几张（默认 2）") ap.add_argument("--width", type=int, default=1600, help="缩放宽度 px（默认 1600）") a = ap.parse_args() os.makedirs(a.out, exist_ok=True) allgot = [] for q in a.query: allgot += fetch(q, a.out, a.count, a.width) print(f"\n=== 共下载 {len(allgot)} 张到 {a.out} ===") print("⚠️ 诚实性核对：去掉每张图信息是否有损？许可是否允许用途？不合适的删掉。") if not allgot: print("❌ 全部失败 → 走 Phase 3.5 取图三级兜底（Unsplash/Pexels → 生图 → 诚实 placeholder，不卡流程）", file=sys.stderr) sys.exit(1) if __name__ == "__main__": main() -
gen_deck_thumbs.mjs 3 KB · in bundle
-
html2pptx.js 33.7 KB
// Copyright (c) 2026 alchaincyf (花叔). MIT License. // // 独立实现：按一份只描述输入、输出和可观察行为的规格从零编写，实现过程中没有 // 查看其他 html2pptx 的源码。依赖 Playwright 与 pptxgenjs 两个公开库。 // // 职责：把一页 960pt×540pt（约定俗成，实际以 body 尺寸为准）的 HTML，用 Playwright // 起一个真实 Chromium 打开、量出每个元素的渲染结果（位置/尺寸/computed style）， // 翻译成 pptxgenjs 的原生可编辑对象（文本框 / 形状 / 线条 / 图片）。 'use strict'; const path = require('path'); const { chromium } = require('playwright'); // ---- 单位换算常量 ---- const PT_PER_PX = 0.75; // CSS px -> pt const IN_PER_PX = 1 / 96; // CSS px -> inch const EMU_PER_INCH = 914400; function toPt(px) { return px * PT_PER_PX; } function toIn(px) { return px * IN_PER_PX; } // ============================================================================ // 浏览器内提取逻辑：作为字符串函数整体交给 page.evaluate 执行，运行在页面上下文里， // 不能依赖外层闭包变量（Playwright 序列化 Function.toString() 后在浏览器里重新求值）。 // ============================================================================ function extractPageDataInBrowser() { const PT_PER_PX = 0.75; function toPt(px) { return px * PT_PER_PX; } function toIn(px) { return px / 96; } const SINGLE_WEIGHT_FONTS = ['impact']; const INLINE_TAGS = new Set(['SPAN', 'B', 'STRONG', 'I', 'EM', 'U']); const TEXT_TAG_BG_CHECK = new Set(['P', 'H1', 'H2', 'H3', 'H4', 'H5', 'H6', 'UL', 'OL', 'LI']); const TEXT_ELEMENT_TAGS = new Set(['P', 'H1', 'H2', 'H3', 'H4', 'H5', 'H6', 'LI']); const MANUAL_BULLET_CHARS_VALIDATE = ['•', '-', '*', '▪', '▸', '○', '●', '◆', '◇', '■', '□']; const MANUAL_BULLET_CHARS_STRIP = ['•', '-', '*', '▪', '▸']; const errors = []; const elements = []; const placeholders = []; const consumed = new Set(); // ---- 基础工具 ---- function parsePx(v) { const n = parseFloat(v); return isNaN(n) ? 0 : n; } function rectOf(el) { const r = el.getBoundingClientRect(); return { x: r.left, y: r.top, w: r.width, h: r.height }; } function truncate(str, max) { if (str.length <= max) return str; return str.slice(0, max) + '...'; } function collapseWs(s) { return s.replace(/[\t\n\r ]+/g, ' '); } function parseColorString(str) { if (!str) return null; const m = /rgba?\(\s*([\d.]+)\s*,\s*([\d.]+)\s*,\s*([\d.]+)\s*(?:,\s*([\d.]+)\s*)?\)/i.exec(str); if (!m) return null; const r = Math.max(0, Math.min(255, Math.round(parseFloat(m[1])))); const g = Math.max(0, Math.min(255, Math.round(parseFloat(m[2])))); const b = Math.max(0, Math.min(255, Math.round(parseFloat(m[3])))); const hasAlpha = m[4] !== undefined; const alpha = hasAlpha ? parseFloat(m[4]) : 1; const hex = [r, g, b].map((v) => v.toString(16).padStart(2, '0')).join(''); return { hex, alpha, hasAlpha }; } function isVisibleColor(c) { return !!c && c.alpha > 0; } // {color, transparency?} —— 只有解析出显式 alpha 通道时才带 transparency function fillFieldOf(c) { const out = { color: c.hex }; if (c.hasAlpha) out.transparency = Math.round((1 - c.alpha) * 100); return out; } function firstFontFamily(v) { if (!v) return ''; const first = v.split(',')[0].trim(); return first.replace(/^["']|["']$/g, ''); } function isSingleWeightFont(fontFace) { return SINGLE_WEIGHT_FONTS.indexOf((fontFace || '').toLowerCase()) !== -1; } function normalizeAlign(v) { return v === 'start' ? 'left' : v; } function parseLineHeightPt(lineHeightStr, fontSizePt) { const v = parseFloat(lineHeightStr); if (!isNaN(v) && /px\s*$/.test(String(lineHeightStr).trim())) { return v * PT_PER_PX; } // 防御性兜底：真实 Chromium 的 computed line-height 基本总是已解析的 px 值， // 这里的 fontSize*1.2 分支理论上不会命中。 return fontSizePt * 1.2; } function applyTextTransform(str, tt) { if (tt === 'uppercase') return str.toUpperCase(); if (tt === 'lowercase') return str.toLowerCase(); if (tt === 'capitalize') return str.replace(/\b\w/g, (c) => c.toUpperCase()); return str; } function getBordersInfo(cs) { return { top: { w: parsePx(cs.borderTopWidth), c: cs.borderTopColor }, right: { w: parsePx(cs.borderRightWidth), c: cs.borderRightColor }, bottom: { w: parsePx(cs.borderBottomWidth), c: cs.borderBottomColor }, left: { w: parsePx(cs.borderLeftWidth), c: cs.borderLeftColor }, }; } function computeRectRadius(cs, widthPx, heightPx) { const raw = (cs.borderTopLeftRadius || '0px').trim(); const m = /^(-?[\d.]+)(px|pt|%)?$/.exec(raw); if (!m) return 0; const val = parseFloat(m[1]); const unit = m[2] || 'px'; if (!val) return 0; if (unit === '%') { if (val >= 50) return 1; return ((val / 100) * Math.min(widthPx, heightPx)) / 96; } if (unit === 'pt') return val / 72; return val / 96; } function parseBoxShadow(str) { if (!str || str === 'none') return null; if (/inset/i.test(str)) return null; const colorMatch = str.match(/rgba?\([^)]+\)/i); const colorParsed = colorMatch ? parseColorString(colorMatch[0]) : null; const withoutColor = colorMatch ? str.replace(colorMatch[0], '') : str; const nums = withoutColor.match(/-?[\d.]+px/g) || []; if (nums.length < 2) return null; const vals = nums.map((s) => parseFloat(s)); const offsetX = vals[0]; const offsetY = vals[1]; const blur = vals[2] || 0; const offsetPt = Math.hypot(offsetX, offsetY) * PT_PER_PX; let angleDeg = (Math.atan2(offsetY, offsetX) * 180) / Math.PI; angleDeg = ((angleDeg % 360) + 360) % 360; const blurPt = blur * PT_PER_PX; const color = colorParsed ? colorParsed.hex : '000000'; const opacity = colorParsed && colorParsed.hasAlpha ? colorParsed.alpha : 0.5; return { type: 'outer', angle: angleDeg, blur: blurPt, color, offset: offsetPt, opacity }; } function violationOf(el) { const cs = getComputedStyle(el); const bg = parseColorString(cs.backgroundColor); if (isVisibleColor(bg)) return 'background'; const b = getBordersInfo(cs); if (b.top.w > 0 || b.right.w > 0 || b.bottom.w > 0 || b.left.w > 0) return 'border'; if (cs.boxShadow && cs.boxShadow !== 'none') return 'shadow'; return null; } // ---- 旋转角度 + 位置/尺寸（4.5 节） ---- function computeRotationDeg(cs) { let angle = 0; if (cs.writingMode === 'vertical-rl') angle += 90; else if (cs.writingMode === 'vertical-lr') angle += 270; const t = cs.transform; if (t && t !== 'none') { const rm = /rotate\(([-\d.]+)deg\)/.exec(t); if (rm) { angle += parseFloat(rm[1]); } else { const mm = /matrix\(([^)]+)\)/.exec(t); if (mm) { const parts = mm[1].split(',').map((s) => parseFloat(s.trim())); angle += (Math.atan2(parts[1], parts[0]) * 180) / Math.PI; } } } return ((angle % 360) + 360) % 360; } function computeGeometryPx(el, rotationDeg) { const r = el.getBoundingClientRect(); if (rotationDeg === 90 || rotationDeg === 270) { const cx = r.left + r.width / 2; const cy = r.top + r.height / 2; const w = r.height; const h = r.width; return { x: cx - w / 2, y: cy - h / 2, w, h }; } if (rotationDeg !== 0) { const cx = r.left + r.width / 2; const cy = r.top + r.height / 2; const w = el.offsetWidth; const h = el.offsetHeight; return { x: cx - w / 2, y: cy - h / 2, w, h }; } return { x: r.left, y: r.top, w: r.width, h: r.height }; } // ---- 4.5.3 内联富文本通用解析 ---- function hasInlineFormatting(el) { return !!el.querySelector('span,b,strong,i,em,u,br'); } function buildRuns(containerEl, marginErrsOut) { const rawRuns = []; function styleOf(el) { const cs = getComputedStyle(el); const fontSizePt = parseFloat(cs.fontSize) * PT_PER_PX; const fontFace = firstFontFamily(cs.fontFamily); let bold = cs.fontWeight === 'bold' || parseInt(cs.fontWeight, 10) >= 600; if (isSingleWeightFont(fontFace)) bold = false; const italic = cs.fontStyle === 'italic'; const deco = cs.textDecorationLine || cs.textDecoration || ''; const underline = deco.indexOf('underline') !== -1; const colorParsed = parseColorString(cs.color); const textTransform = cs.textTransform; return { fontSizePt, bold, italic, underline, colorParsed, textTransform }; } function sameStyle(a, b) { if (!a || !b) return false; return ( a.fontSizePt === b.fontSizePt && a.bold === b.bold && a.italic === b.italic && a.underline === b.underline && a.textTransform === b.textTransform && JSON.stringify(a.colorParsed) === JSON.stringify(b.colorParsed) ); } function append(text, style) { if (text === '') return; const last = rawRuns[rawRuns.length - 1]; if (last && sameStyle(last.style, style)) { last.text += text; } else { rawRuns.push({ text, style }); } } function checkInlineMargins(el, tag) { const cs = getComputedStyle(el); ['Left', 'Right', 'Top', 'Bottom'].forEach((dir) => { const v = parsePx(cs['margin' + dir]); if (v !== 0) { marginErrsOut.push( `Inline element <${tag.toLowerCase()}> has a non-zero margin-${dir.toLowerCase()} (inline elements do not support margin — remove it).` ); } }); } function walk(node) { if (node.nodeType === 3) { const collapsed = collapseWs(node.textContent); if (collapsed === '') return; const style = styleOf(node.parentElement); append(applyTextTransform(collapsed, style.textTransform), style); return; } if (node.nodeType !== 1) return; const tag = node.tagName; if (tag === 'BR') { const style = styleOf(node.parentElement); append('\n', style); return; } if (INLINE_TAGS.has(tag)) { const text = node.textContent; if (!text || !text.trim()) return; checkInlineMargins(node, tag); Array.from(node.childNodes).forEach(walk); return; } // 不认识的标签（比如 <code>）：整段忽略，文字从输出里消失（既有行为，不扩展）。 } Array.from(containerEl.childNodes).forEach(walk); if (rawRuns.length > 0) { rawRuns[0].text = rawRuns[0].text.replace(/^ +/, ''); rawRuns[rawRuns.length - 1].text = rawRuns[rawRuns.length - 1].text.replace(/ +$/, ''); } // pptxgenjs 的 TextProps 要求 { text, options }：options 里只放和继承样式不同的 // 覆盖项，缺省项交给 pptxgenjs 自己按顶层/上一个 run 的默认值处理。 return rawRuns .filter((r) => r.text !== '') .map((r) => { const options = { fontSize: r.style.fontSizePt }; if (r.style.bold) options.bold = true; if (r.style.italic) options.italic = true; if (r.style.underline) options.underline = true; const c = r.style.colorParsed; const isPureBlack = c && c.hex === '000000' && !c.hasAlpha; if (c && !isPureBlack) { options.color = c.hex; if (c.hasAlpha) options.transparency = Math.round((1 - c.alpha) * 100); } return { text: r.text, options }; }); } function stripLeadingManualBullet(run) { for (const ch of MANUAL_BULLET_CHARS_STRIP) { if (run.text.indexOf(ch) === 0) { run.text = run.text.slice(1).replace(/^\s+/, ''); return; } } } // ---- 4.2 占位符 ---- function processPlaceholder(el) { consumed.add(el); Array.from(el.querySelectorAll('*')).forEach((d) => consumed.add(d)); const rect = rectOf(el); if (rect.w === 0 || rect.h === 0) { const dim = rect.w === 0 ? 'width' : 'height'; const id = el.id || 'unnamed'; errors.push(`占位区 #${id} 渲染出来的${dim === 'width' ? '宽度' : '高度'}是 0，检查它的 CSS 布局`); return; } const id = el.id || 'placeholder-' + placeholders.length; placeholders.push({ id, x: toIn(rect.x), y: toIn(rect.y), w: toIn(rect.w), h: toIn(rect.h) }); } // ---- 4.3 图片 ---- function processImage(el) { const rect = rectOf(el); if (rect.w === 0 || rect.h === 0) return; elements.push({ type: 'image', src: el.src, x: toIn(rect.x), y: toIn(rect.y), w: toIn(rect.w), h: toIn(rect.h) }); } // ---- 4.4 div ---- function buildBorderLines(rect, b) { const out = []; const sides = [ { info: b.top, geo: () => ({ x: rect.x, y: rect.y + b.top.w / 2, w: rect.w, h: 0 }) }, { info: b.right, geo: () => ({ x: rect.x + rect.w - b.right.w / 2, y: rect.y, w: 0, h: rect.h }) }, { info: b.bottom, geo: () => ({ x: rect.x, y: rect.y + rect.h - b.bottom.w / 2, w: rect.w, h: 0 }) }, { info: b.left, geo: () => ({ x: rect.x + b.left.w / 2, y: rect.y, w: 0, h: rect.h }) }, ]; sides.forEach((s) => { if (s.info.w > 0) { const g = s.geo(); const c = parseColorString(s.info.c); out.push({ type: 'line', x: toIn(g.x), y: toIn(g.y), w: toIn(g.w), h: toIn(g.h), color: c ? c.hex : '000000', widthPt: toPt(s.info.w), }); } }); return out; } function processDiv(div) { // 1: 裸文字校验（永远执行，不因为后面的 background-image 违规而跳过） const rawDirectText = Array.from(div.childNodes) .filter((n) => n.nodeType === 3) .map((n) => n.textContent) .join('') .trim(); if (rawDirectText) { errors.push( `<div> 里直接写了文字「${truncate(rawDirectText, 50)}」，PPT 里不会出现——请用 <p>、<h1>-<h6>、<ul>/<ol> 包起来` ); } // 2: background-image 校验（命中时不产出 shape/line，但不消费该节点，子孙继续遍历） const cs = getComputedStyle(div); if (cs.backgroundImage && cs.backgroundImage !== 'none') { if (/gradient/i.test(cs.backgroundImage)) { errors.push( '<div> 背景不能用 CSS 渐变：换成纯色 background-color，或把渐变先导出成 PNG 再用 <img> / slide.addImage() 放上去' ); } else { errors.push( '<div> 不能用 background-image：图片请改成 <img> 标签，或用 slide.addImage() 单独叠一层' ); } return; } const rect = rectOf(div); if (rect.w === 0 || rect.h === 0) return; const bgColor = parseColorString(cs.backgroundColor); const hasBg = isVisibleColor(bgColor); const b = getBordersInfo(cs); const hasBorder = b.top.w > 0 || b.right.w > 0 || b.bottom.w > 0 || b.left.w > 0; const hasUniformBorder = hasBorder && b.top.w === b.right.w && b.right.w === b.bottom.w && b.bottom.w === b.left.w; let shapeEl = null; let lineEls = []; if (hasBorder && !hasUniformBorder) { lineEls = buildBorderLines(rect, b); } if (hasBg || hasBorder) { if (hasBg || hasUniformBorder) { const shadow = parseBoxShadow(cs.boxShadow); shapeEl = { type: 'shape', x: toIn(rect.x), y: toIn(rect.y), w: toIn(rect.w), h: toIn(rect.h), fill: hasBg ? fillFieldOf(bgColor) : null, line: hasUniformBorder ? { color: parseColorString(b.top.c).hex, width: toPt(b.top.w) } : null, rectRadius: computeRectRadius(cs, rect.w, rect.h), shadow, }; } consumed.add(div); } if (shapeEl) elements.push(shapeEl); lineEls.forEach((l) => elements.push(l)); } // ---- 4.1 data-pptx-merge 容器 ---- function processMergeContainer(container) { const rect = rectOf(container); if (rect.w === 0 || rect.h === 0) { consumed.add(container); return; } const nested = container.querySelectorAll('[data-pptx-merge="true"]'); if (nested.length > 0) { errors.push('data-pptx-merge containers cannot be nested. Remove the inner data-pptx-merge="true" attribute.'); consumed.add(container); return; } const cs = getComputedStyle(container); if (cs.backgroundImage && cs.backgroundImage !== 'none') { if (/gradient/i.test(cs.backgroundImage)) { errors.push( 'CSS gradients are not supported on data-pptx-merge containers. Use a solid background-color, or overlay the gradient with slide.addImage().' ); } else { errors.push( 'data-pptx-merge containers do not support background-image. Use a solid background-color/border, or overlay the picture with slide.addImage().' ); } consumed.add(container); return; } const paragraphs = Array.from(container.querySelectorAll('p,h1,h2,h3,h4,h5,h6')); if (paragraphs.length === 0) { errors.push( 'data-pptx-merge container has no mergeable text elements. Remove data-pptx-merge or add <p>/<h1>-<h6> text inside it.' ); consumed.add(container); return; } const bgColor = parseColorString(cs.backgroundColor); const hasBg = isVisibleColor(bgColor); const b = getBordersInfo(cs); const hasUniformBorder = b.top.w > 0 && b.top.w === b.right.w && b.right.w === b.bottom.w && b.bottom.w === b.left.w; let shapeEl = null; if (hasBg || hasUniformBorder) { const shadow = parseBoxShadow(cs.boxShadow); shapeEl = { type: 'shape', x: toIn(rect.x), y: toIn(rect.y), w: toIn(rect.w), h: toIn(rect.h), fill: hasBg ? fillFieldOf(bgColor) : null, line: hasUniformBorder ? { color: parseColorString(b.top.c).hex, width: toPt(b.top.w) } : null, rectRadius: computeRectRadius(cs, rect.w, rect.h), shadow, }; } // 框级基准样式取第一个文字后代 const baseEl = paragraphs[0]; const baseCs = getComputedStyle(baseEl); const baseFontSizePt = parseFloat(baseCs.fontSize) * PT_PER_PX; const baseFontFace = firstFontFamily(baseCs.fontFamily); const baseColorParsed = parseColorString(baseCs.color); const baseAlign = normalizeAlign(baseCs.textAlign); const baseLineSpacingPt = parseLineHeightPt(baseCs.lineHeight, baseFontSizePt); const marginArr = [ toPt(parsePx(cs.paddingLeft)), toPt(parsePx(cs.paddingRight)), toPt(parsePx(cs.paddingBottom)), toPt(parsePx(cs.paddingTop)), ]; paragraphs.forEach((p) => consumed.add(p)); consumed.add(container); const allRuns = []; paragraphs.forEach((p, idx) => { const marginErrs = []; const runs = buildRuns(p, marginErrs); errors.push(...marginErrs); if (runs.length === 0) return; if (idx < paragraphs.length - 1) { runs[runs.length - 1].options.breakLine = true; } allRuns.push(...runs); }); if (allRuns.length === 0) return; if (shapeEl) elements.push(shapeEl); elements.push({ type: 'merged-text', x: toIn(rect.x), y: toIn(rect.y), w: toIn(rect.w), h: toIn(rect.h), fontSize: baseFontSizePt, fontFace: baseFontFace, color: baseColorParsed ? baseColorParsed.hex : null, transparency: baseColorParsed && baseColorParsed.hasAlpha ? Math.round((1 - baseColorParsed.alpha) * 100) : null, align: baseAlign, lineSpacing: baseLineSpacingPt, marginArr, items: allRuns, }); } // ---- 4.6 列表 ---- function processList(listEl) { const rect = rectOf(listEl); if (rect.w === 0 || rect.h === 0) return; const cs = getComputedStyle(listEl); const paddingLeftPt = toPt(parsePx(cs.paddingLeft)); const half = paddingLeftPt / 2; const liEls = Array.from(listEl.querySelectorAll('li')); liEls.forEach((li) => consumed.add(li)); consumed.add(listEl); if (liEls.length === 0) return; const baseCs = getComputedStyle(liEls[0]); const baseFontSizePt = parseFloat(baseCs.fontSize) * PT_PER_PX; const baseFontFace = firstFontFamily(baseCs.fontFamily); const baseColorParsed = parseColorString(baseCs.color); const baseAlign = normalizeAlign(baseCs.textAlign); const baseLineSpacingPt = parseLineHeightPt(baseCs.lineHeight, baseFontSizePt); const paraSpaceAfterPt = toPt(parsePx(baseCs.marginBottom)); const allRuns = []; liEls.forEach((li, idx) => { const marginErrs = []; const runs = buildRuns(li, marginErrs); errors.push(...marginErrs); if (runs.length === 0) return; stripLeadingManualBullet(runs[0]); runs[0].options.bullet = { indent: half }; if (idx < liEls.length - 1) { runs[runs.length - 1].options.breakLine = true; } allRuns.push(...runs); }); if (allRuns.length === 0) return; elements.push({ type: 'list', x: toIn(rect.x), y: toIn(rect.y), w: toIn(rect.w), h: toIn(rect.h), fontSize: baseFontSizePt, fontFace: baseFontFace, color: baseColorParsed ? baseColorParsed.hex : null, transparency: baseColorParsed && baseColorParsed.hasAlpha ? Math.round((1 - baseColorParsed.alpha) * 100) : null, align: baseAlign, lineSpacing: baseLineSpacingPt, paraSpaceAfter: paraSpaceAfterPt, marginArr: [half, 0, 0, 0], items: allRuns, }); } // ---- 4.5 单个文本标签（含 4.5 preamble 提到的 li 兜底分支）---- function processTextElement(el) { const tag = el.tagName; const rect = rectOf(el); const collapsedFull = collapseWs(el.textContent).trim(); if (rect.w === 0 || rect.h === 0 || collapsedFull === '') return; if (tag !== 'LI') { const m = /^([•\-*▪▸○●◆◇■□])\s/.exec(collapsedFull); if (m) { errors.push( `<${tag.toLowerCase()}> 开头手打了项目符号「${truncate(collapsedFull, 20)}」——列表请用 <ul>/<ol>，不要自己打圆点` ); return; } } const cs = getComputedStyle(el); const rotation = computeRotationDeg(cs); const geomPx = computeGeometryPx(el, rotation); const fontSizePt = parseFloat(cs.fontSize) * PT_PER_PX; const fontFace = firstFontFamily(cs.fontFamily); const colorParsed = parseColorString(cs.color); const align = normalizeAlign(cs.textAlign); const lineSpacingPt = parseLineHeightPt(cs.lineHeight, fontSizePt); const marginTopPt = toPt(parsePx(cs.marginTop)); const marginBottomPt = toPt(parsePx(cs.marginBottom)); const paddingArr = [ toPt(parsePx(cs.paddingLeft)), toPt(parsePx(cs.paddingRight)), toPt(parsePx(cs.paddingBottom)), toPt(parsePx(cs.paddingTop)), ]; const hasPadding = paddingArr.some((v) => v !== 0); let boldBase = cs.fontWeight === 'bold' || parseInt(cs.fontWeight, 10) >= 600; if (isSingleWeightFont(fontFace)) boldBase = false; const italicBase = cs.fontStyle === 'italic'; const decoBase = cs.textDecorationLine || cs.textDecoration || ''; const underlineBase = decoBase.indexOf('underline') !== -1; let textOut; let effectiveLineSpacing = lineSpacingPt; if (hasInlineFormatting(el)) { const marginErrs = []; const runs = buildRuns(el, marginErrs); errors.push(...marginErrs); if (runs.length === 0) return; textOut = runs; const maxRunFontSize = Math.max.apply( null, runs.map((r) => r.options.fontSize) ); if (maxRunFontSize > fontSizePt) { effectiveLineSpacing = maxRunFontSize * (lineSpacingPt / fontSizePt); } } else { textOut = applyTextTransform(collapsedFull, cs.textTransform); } // 几何补偿（6.6）：给单个 p/h1-h6 文本框的宽度加宽 2%，补偿 pptxgenjs/PowerPoint // 对文字宽度的测量比浏览器偏窄这个已知误差。 const heightIn = geomPx.h / 96; let xIn = geomPx.x / 96; let yIn = geomPx.y / 96; let wIn = geomPx.w / 96; let hIn = heightIn; { const widen = wIn * 0.02; if (align === 'right') { xIn -= widen; wIn += widen; } else if (align === 'center') { xIn -= widen / 2; wIn += widen; } else { wIn += widen; } } const outEl = { type: tag.toLowerCase(), x: xIn, y: yIn, w: wIn, h: hIn, fontSize: fontSizePt, fontFace, color: colorParsed ? colorParsed.hex : null, transparency: colorParsed && colorParsed.hasAlpha ? Math.round((1 - colorParsed.alpha) * 100) : null, align, lineSpacing: effectiveLineSpacing, paraSpaceBefore: marginTopPt, paraSpaceAfter: marginBottomPt, marginArr: hasPadding ? paddingArr : null, rotate: rotation !== 0 ? rotation : null, text: textOut, }; if (typeof textOut === 'string') { outEl.bold = boldBase; outEl.italic = italicBase; outEl.underline = underlineBase; } elements.push(outEl); } // ---- 背景 ---- function extractBackground() { const cs = getComputedStyle(document.body); if (cs.backgroundImage && cs.backgroundImage !== 'none') { const m = /url\((['"]?)(.*?)\1\)/.exec(cs.backgroundImage); if (m) return { type: 'image', value: m[2] }; } const c = parseColorString(cs.backgroundColor); if (isVisibleColor(c)) return { type: 'color', value: c.hex }; return null; } // ---- 主遍历 ---- const allNodes = Array.from(document.body.querySelectorAll('*')); for (const el of allNodes) { const tag = el.tagName; if (TEXT_TAG_BG_CHECK.has(tag)) { const v = violationOf(el); if (v) { errors.push( `文字标签 <${tag.toLowerCase()}> 上设置了 ${v}：背景、边框、阴影只能加在 <div> 上，请在外面套一层 <div>` ); continue; } } if (consumed.has(el)) continue; const classAttr = el.getAttribute('class') || ''; if (el.getAttribute('data-pptx-merge') === 'true') { processMergeContainer(el); continue; } if (classAttr.indexOf('placeholder') !== -1) { processPlaceholder(el); continue; } if (tag === 'IMG') { processImage(el); continue; } if (tag === 'DIV') { processDiv(el); continue; } if (tag === 'UL' || tag === 'OL') { processList(el); continue; } if (TEXT_ELEMENT_TAGS.has(tag)) { processTextElement(el); continue; } // 其它任何元素：忽略，不产出、不报错 } const bodyCs = getComputedStyle(document.body); return { background: extractBackground(), elements, placeholders, errors, body: { width: parseFloat(bodyCs.width), height: parseFloat(bodyCs.height), scrollWidth: document.body.scrollWidth, scrollHeight: document.body.scrollHeight, }, }; } // ============================================================================ // Node 侧：写入 pptxgenjs // ============================================================================ function stripFileProtocol(p) { return p.replace(/^file:\/\//, ''); } function previewTextOf(el) { if (typeof el.text === 'string') return el.text; const arr = Array.isArray(el.text) ? el.text : Array.isArray(el.items) ? el.items : []; for (const r of arr) { if (r && typeof r.text === 'string' && r.text.trim() !== '') return r.text; } return ''; } function writeElement(slide, pres, el) { switch (el.type) { case 'image': { slide.addImage({ path: stripFileProtocol(el.src), x: el.x, y: el.y, w: el.w, h: el.h }); break; } case 'line': { slide.addShape(pres.ShapeType.line, { x: el.x, y: el.y, w: el.w, h: el.h, line: { color: el.color, width: el.widthPt }, }); break; } case 'shape': { const shapeName = el.rectRadius > 0 ? pres.ShapeType.roundRect : pres.ShapeType.rect; const opts = { x: el.x, y: el.y, w: el.w, h: el.h, shape: shapeName }; if (el.fill) opts.fill = el.fill; if (el.line) opts.line = el.line; if (el.rectRadius > 0) opts.rectRadius = el.rectRadius; if (el.shadow) opts.shadow = el.shadow; slide.addText('', opts); break; } case 'list': { const opts = { x: el.x, y: el.y, w: el.w, h: el.h, fontSize: el.fontSize, fontFace: el.fontFace, color: el.color, align: el.align, valign: 'top', lineSpacing: el.lineSpacing, paraSpaceBefore: 0, paraSpaceAfter: el.paraSpaceAfter, margin: el.marginArr, }; if (el.transparency != null) opts.transparency = el.transparency; slide.addText(el.items, opts); break; } case 'merged-text': { const opts = { x: el.x, y: el.y, w: el.w, h: el.h, fontSize: el.fontSize, fontFace: el.fontFace, color: el.color, align: el.align, valign: 'top', lineSpacing: el.lineSpacing, paraSpaceBefore: 0, paraSpaceAfter: 0, margin: el.marginArr, }; if (el.transparency != null) opts.transparency = el.transparency; slide.addText(el.items, opts); break; } default: { // p / h1-h6 / (兜底的 li)：单个文本框 const opts = { x: el.x, y: el.y, w: el.w, h: el.h, fontSize: el.fontSize, fontFace: el.fontFace, color: el.color, align: el.align, valign: 'top', lineSpacing: el.lineSpacing, paraSpaceBefore: el.paraSpaceBefore, paraSpaceAfter: el.paraSpaceAfter, inset: 0, }; if (typeof el.text === 'string') { opts.bold = el.bold; opts.italic = el.italic; opts.underline = el.underline; } if (el.marginArr) opts.margin = el.marginArr; if (el.rotate) opts.rotate = el.rotate; if (el.transparency != null) opts.transparency = el.transparency; slide.addText(el.text, opts); break; } } } module.exports = async function html2pptx(htmlFile, pres, options) { options = options || {}; const absHtmlPath = path.isAbsolute(htmlFile) ? htmlFile : path.resolve(process.cwd(), htmlFile); const tmpDir = options.tmpDir || process.env.TMPDIR || '/tmp'; function finalizeError(rawMessage) { let message = rawMessage; if (!message.startsWith(htmlFile)) { message = `${htmlFile}: ${message}`; } return new Error(message); } let browser; let extraction; try { const launchOptions = { env: Object.assign({}, process.env, { TMPDIR: tmpDir }) }; if (process.platform === 'darwin') launchOptions.channel = 'chrome'; browser = await chromium.launch(launchOptions); const page = await browser.newPage(); await page.goto('file://' + absHtmlPath); const initialBodySize = await page.evaluate(() => { const cs = getComputedStyle(document.body); return { width: parseFloat(cs.width), height: parseFloat(cs.height) }; }); await page.setViewportSize({ width: Math.max(1, Math.round(initialBodySize.width)), height: Math.max(1, Math.round(initialBodySize.height)), }); extraction = await page.evaluate(extractPageDataInBrowser); } finally { if (browser) await browser.close(); } // ---- 整页级校验（第 5 节），和提取阶段收集到的错误合并 ---- const errors = extraction.errors.slice(); const widthOverflowPx = Math.max(0, extraction.body.scrollWidth - extraction.body.width - 1); const heightOverflowPx = Math.max(0, extraction.body.scrollHeight - extraction.body.height - 1); if (widthOverflowPx > 0) { errors.push(`内容横向超出页面 ${(widthOverflowPx * PT_PER_PX).toFixed(1)}pt`); } if (heightOverflowPx > 0) { errors.push( `内容纵向超出页面 ${(heightOverflowPx * PT_PER_PX).toFixed(1)}pt（页面底部要留出 0.5 英寸空白）` ); } let slideHeightIn = null; if (pres.presLayout) { const layoutWIn = pres.presLayout.width / EMU_PER_INCH; const layoutHIn = pres.presLayout.height / EMU_PER_INCH; const bodyWIn = extraction.body.width * IN_PER_PX; const bodyHIn = extraction.body.height * IN_PER_PX; if (Math.abs(bodyWIn - layoutWIn) > 0.1 || Math.abs(bodyHIn - layoutHIn) > 0.1) { errors.push( `页面尺寸不一致：HTML 的 body 是 ${bodyWIn.toFixed(1)}×${bodyHIn.toFixed(1)} 英寸，PPT 版式是 ${layoutWIn.toFixed(1)}×${layoutHIn.toFixed(1)} 英寸` ); } slideHeightIn = layoutHIn; } if (slideHeightIn != null) { const CHECK_TYPES = new Set(['p', 'h1', 'h2', 'h3', 'h4', 'h5', 'h6', 'list', 'merged-text']); for (const el of extraction.elements) { if (!CHECK_TYPES.has(el.type)) continue; if (!(el.fontSize > 12)) continue; const distance = slideHeightIn - (el.y + el.h); if (distance < 0.5) { const preview = previewTextOf(el).slice(0, 50); errors.push(`文本框「${preview}」离页面底边只有 ${distance.toFixed(2)} 英寸，至少要留 0.5 英寸`); } } } if (errors.length > 0) { let message; if (errors.length === 1) { message = errors[0]; } else { message = `发现 ${errors.length} 处问题：\n` + errors.map((e, i) => ` ${i + 1}. ${e}`).join('\n'); } throw finalizeError(message); } // ---- 写入 slide ---- const slide = options.slide || pres.addSlide(); if (extraction.background) { if (extraction.background.type === 'image') { slide.background = { path: stripFileProtocol(extraction.background.value) }; } else { slide.background = { color: extraction.background.value }; } } for (const el of extraction.elements) { writeElement(slide, pres, el); } return { slide, placeholders: extraction.placeholders }; }; -
mix-voiceover.sh 4.4 KB
#!/usr/bin/env bash # mix-voiceover.sh · Mix voiceover (人声主轨) + optional BGM into an MP4 # # Usage: # bash mix-voiceover.sh <video.mp4> --voiceover=<voice.mp3> [options] # # Required: # --voiceover=<path> Path to voiceover mp3 (人声主轨, 来自 narrate-pipeline.mjs) # # Optional: # --bgm=<path> BGM mp3 path (overrides --bgm-mood) # --bgm-mood=<name> Pick a preset BGM from assets/ (educational / tech / tutorial / ...) # --bgm-volume=<0-1> BGM 静态音量, 默认 0.18 (相对人声) # --no-ducking 关闭 sidechain ducking（默认开启：人声响时 BGM 自动让路） # --voice-volume=<0-2> 人声音量倍率, 默认 1.0 # --out=<path> 输出路径, 默认 <input>-voiced.mp4 # # Behavior: # - 视频流 stream copy（不重编码，快） # - 人声始终是主轨，必带；BGM 可选 # - 默认开 ducking：人声响时 BGM 压到约 -10dB，人声停时回升 # - 输出长度 = 视频长度（人声/BGM 较短就尾静音；较长就截断） # # Examples: # bash mix-voiceover.sh anim.mp4 --voiceover=narration/voiceover.mp3 # bash mix-voiceover.sh anim.mp4 --voiceover=v.mp3 --bgm-mood=educational # bash mix-voiceover.sh anim.mp4 --voiceover=v.mp3 --bgm=~/Music/song.mp3 --bgm-volume=0.12 # bash mix-voiceover.sh anim.mp4 --voiceover=v.mp3 --bgm-mood=tech --no-ducking # set -e SCRIPT_DIR="$(cd "$(dirname "$0")" && pwd)" ASSETS_DIR="$SCRIPT_DIR/../assets" INPUT="" VOICEOVER="" BGM="" BGM_MOOD="" BGM_VOLUME="0.18" VOICE_VOLUME="1.0" DUCKING="1" OUTPUT="" for arg in "$@"; do case "$arg" in --voiceover=*) VOICEOVER="${arg#*=}" ;; --bgm=*) BGM="${arg#*=}" ;; --bgm-mood=*) BGM_MOOD="${arg#*=}" ;; --bgm-volume=*) BGM_VOLUME="${arg#*=}" ;; --voice-volume=*) VOICE_VOLUME="${arg#*=}" ;; --no-ducking) DUCKING="0" ;; --out=*) OUTPUT="${arg#*=}" ;; -*) echo "未知参数：$arg" >&2; exit 1 ;; *) INPUT="$arg" ;; esac done if [ -z "$INPUT" ] || [ ! -f "$INPUT" ]; then echo "Usage: bash mix-voiceover.sh <video.mp4> --voiceover=<v.mp3> [--bgm=<b.mp3> | --bgm-mood=<name>]" >&2 exit 1 fi if [ -z "$VOICEOVER" ] || [ ! -f "$VOICEOVER" ]; then echo "✗ 缺 --voiceover=<path>" >&2 exit 1 fi # 解析 BGM 来源 if [ -z "$BGM" ] && [ -n "$BGM_MOOD" ]; then BGM="$ASSETS_DIR/bgm-${BGM_MOOD}.mp3" fi if [ -n "$BGM" ] && [ ! -f "$BGM" ]; then echo "✗ BGM 文件不存在: $BGM" >&2 echo " 可用 mood: $(ls "$ASSETS_DIR" 2>/dev/null | grep -E '^bgm-.*\.mp3$' | sed 's/^bgm-//;s/\.mp3$//' | tr '\n' ' ')" >&2 exit 1 fi # 输出路径 if [ -z "$OUTPUT" ]; then base="${INPUT%.*}" OUTPUT="${base}-voiced.mp4" fi echo "─ mix-voiceover ──────────────" echo " 视频: $INPUT" echo " 人声: $VOICEOVER (vol=$VOICE_VOLUME)" if [ -n "$BGM" ]; then echo " BGM: $BGM (vol=$BGM_VOLUME, ducking=$DUCKING)" else echo " BGM: （无）" fi echo " 输出: $OUTPUT" echo "──────────────────────────────" # ── ffmpeg filter graph ───────────────────────────────────── if [ -z "$BGM" ]; then # 仅人声 ffmpeg -y -i "$INPUT" -i "$VOICEOVER" \ -filter_complex "[1:a]volume=${VOICE_VOLUME}[a]" \ -map 0:v -map "[a]" \ -c:v copy -c:a aac -b:a 192k -shortest \ "$OUTPUT" elif [ "$DUCKING" = "1" ]; then # 人声 + BGM + sidechain ducking ffmpeg -y -i "$INPUT" -i "$VOICEOVER" -i "$BGM" \ -filter_complex " [1:a]volume=${VOICE_VOLUME}[voice]; [2:a]volume=${BGM_VOLUME},aloop=loop=-1:size=2e9[bgm_lo]; [bgm_lo][voice]sidechaincompress=threshold=0.04:ratio=8:attack=5:release=300:makeup=1[bgm_ducked]; [voice][bgm_ducked]amix=inputs=2:duration=first:dropout_transition=0,afade=t=out:st=0:d=0.5:curve=tri[a] " \ -map 0:v -map "[a]" \ -c:v copy -c:a aac -b:a 192k -shortest \ "$OUTPUT" else # 人声 + BGM 静态混合 ffmpeg -y -i "$INPUT" -i "$VOICEOVER" -i "$BGM" \ -filter_complex " [1:a]volume=${VOICE_VOLUME}[voice]; [2:a]volume=${BGM_VOLUME},aloop=loop=-1:size=2e9[bgm]; [voice][bgm]amix=inputs=2:duration=first:dropout_transition=0[a] " \ -map 0:v -map "[a]" \ -c:v copy -c:a aac -b:a 192k -shortest \ "$OUTPUT" fi echo "✓ 完成：$OUTPUT" -
narrate-pipeline.mjs 12.2 KB · in bundle
-
pptx_from_rendered.py 24.7 KB
#!/usr/bin/env python3 """把「已经写好的视觉稿 HTML」直接转成可编辑 PPTX —— 不要求 HTML 满足任何硬约束。 和 html2pptx.js 的分工（别混用，见 references/editable-pptx.md 顶部的决策表）： html2pptx.js HTML 还没写 → 按 4 条硬约束写出来，导出的文本框结构最干净 本脚本 HTML 已经写好且是视觉驱动的（flex / 居中 / 裸文字 / 背景图） → 零改造直接转；要继承甲方官方模板母版时也只能走这条 为什么能绕开那 4 条硬约束：它读的不是源码，是**浏览器渲染完之后**的 getBoundingClientRect。flex、居中、自动换行浏览器都已经算成绝对坐标了， 所以「div 里有裸文字」「用了 flex」这些写法根本不构成问题。 四类元素对应 PowerPoint 的四种对象： text → 文本框（按 <br> 分段，每段一个框，各带自己的 runs 和行高） shape → 矩形 / 圆角矩形（卡片底、色条、分隔线、行内装饰块） img → 图片（CSS 圆角会烤进 alpha 通道） svg → 截成 PNG 的图片（图表拆成几百个矩形反而没法编辑，留图更实用） 用法： python3 pptx_from_rendered.py deck.html -o deck.pptx python3 pptx_from_rendered.py deck.html -o deck.pptx \\ --template 客户模板.pptx --layout "内页" --skip-class logo 依赖：playwright（含 chromium）、python-pptx、Pillow """ import argparse, asyncio, json, os, re, sys from PIL import Image, ImageDraw from pptx import Presentation from pptx.dml.color import RGBColor from pptx.enum.shapes import MSO_SHAPE from pptx.enum.text import MSO_ANCHOR, PP_ALIGN from pptx.oxml.ns import qn from pptx.util import Emu, Pt EMU_PER_PT = 12700 # ───────────────────────────────────────────────────────────── # 一、在浏览器里量：把渲染结果拆成元素清单 # ───────────────────────────────────────────────────────────── JS = r""" (selector) => { const INLINE = ['em','b','i','strong','span','small','br','sup','sub','a','code','mark']; const px = v => parseFloat(v) || 0; // 把一段节点拆成 runs（每段连续同样式的文字一个 run）。 // // ⚠️ 必须在这里做 HTML 的空白折叠。源码里的换行和缩进会变成真实的文本节点， // 浏览器按 white-space:normal 折叠掉（连续空白→一个空格，行首行尾丢弃）， // 但 PPTX 没有这套规则——原样搬过去，那个 \n 在 PowerPoint 里就是一个真换行， // 会把后面的内容整段推到下一行去压住别的元素。 const runsOf = (root) => { const out = []; let atLineStart = true, pendingSpace = false; const push = (node, styleEl) => { let t = node.textContent; if (!t) return; t = t.replace(/\s+/g, ' '); if (t === ' ') { if (!atLineStart) pendingSpace = true; return; } if (atLineStart) t = t.replace(/^ /, ''); if (pendingSpace && !t.startsWith(' ')) t = ' ' + t; pendingSpace = false; if (!t) return; atLineStart = false; const cs = getComputedStyle(styleEl); out.push({ t, fs: px(cs.fontSize), fw: cs.fontWeight, color: cs.color, ls: cs.letterSpacing === 'normal' ? 0 : px(cs.letterSpacing), italic: cs.fontStyle === 'italic', under: cs.textDecorationLine.includes('underline'), }); }; const walk = (node, styleEl) => { for (const n of node.childNodes) { if (n.nodeType === 3) push(n, styleEl); else if (n.tagName && n.tagName.toLowerCase() === 'br') { out.push({br: true}); atLineStart = true; pendingSpace = false; } else if (n.nodeType === 1) walk(n, n); } }; walk(root, root); for (let i = out.length - 1; i >= 0 && !out[i].br; i--) { if (out[i].t) { out[i].t = out[i].t.replace(/ $/, ''); break; } } return out.filter(r => r.br || r.t); }; // 量一组节点占的位置和行数。 // 数行数不能拿每个矩形的 top 去重——同一行里字号不同的 run（一个 132px 的数字挨着 // 62px 的说明）基线对齐、顶边却差一大截，会被当成两行。按 y 区间是否重叠来聚类。 const measure = (nodes) => { const rng = document.createRange(); rng.setStartBefore(nodes[0]); rng.setEndAfter(nodes[nodes.length - 1]); const bb = rng.getBoundingClientRect(); const rects = [...rng.getClientRects()] .filter(q => q.width > 0.5 && q.height > 0.5) .sort((a, b) => a.top - b.top); const rows = []; for (const q of rects) { const last = rows[rows.length - 1]; if (last && q.top < last.bottom - 2) last.bottom = Math.max(last.bottom, q.bottom); else rows.push({top: q.top, bottom: q.bottom}); } return {bb, lines: Math.max(1, rows.length)}; }; const pages = [...document.querySelectorAll(selector)]; return pages.map((pg) => { const pb = pg.getBoundingClientRect(); const out = []; let svgSeq = 0; const walk = (el) => { const cs = getComputedStyle(el); const r = el.getBoundingClientRect(); const tag = el.tagName.toLowerCase(); if (cs.display === 'none' || cs.visibility === 'hidden' || cs.opacity === '0') return; const cls = (typeof el.className === 'string' ? el.className : ''); const base = {tag, cls, x: r.left - pb.left, y: r.top - pb.top, w: r.width, h: r.height}; if (tag === 'img') { out.push({...base, kind: 'img', src: el.getAttribute('src'), radius: px(cs.borderRadius), shadow: cs.boxShadow}); return; } if (tag === 'svg' || tag === 'canvas') { out.push({...base, kind: 'svg', seq: svgSeq++, tagName: tag}); return; } const hasText = el.innerText && el.innerText.trim().length > 0; const onlyInline = [...el.children].every(c => INLINE.includes(c.tagName.toLowerCase())); const bg = cs.backgroundColor; const painted = (bg !== 'rgba(0, 0, 0, 0)' && bg !== 'transparent'); const bdw = px(cs.borderTopWidth); if (painted || bdw > 0) { // 背景/描边先出矩形，画在文字之下 out.push({...base, kind: 'shape', bg, bdw, bdc: cs.borderTopColor, radius: px(cs.borderRadius), shadow: cs.boxShadow, rot: 0}); } if (hasText && onlyInline) { // 按 <br> 分段，每段单独出一个文本框。 // // 为什么不整块出一个框：PowerPoint 的行距是段落级的，而视觉稿经常把不同字号的行 // 放进同一个 div。整块套一个行距，小字那几行会被撑开、大字那行会被压， // 实测会出现相邻两行直接叠在一起。分段之后每段用自己的实际行高，就不会互相牵连。 const groups = [[]]; for (const n of el.childNodes) { if (n.nodeType === 1 && n.tagName.toLowerCase() === 'br') groups.push([]); else groups[groups.length - 1].push(n); } for (const g of groups) { const nodes = g.filter(n => n.nodeType !== 3 || n.textContent.trim()); if (!nodes.length) continue; const {bb, lines} = measure(nodes); if (!bb.height) continue; const tmp = document.createElement('div'); for (const n of g) tmp.appendChild(n.cloneNode(true)); tmp.style.cssText = 'position:absolute;visibility:hidden'; el.appendChild(tmp); const rs = runsOf(tmp); tmp.remove(); if (!rs.length) continue; const fsMax = Math.max(px(cs.fontSize), ...rs.filter(r => !r.br).map(r => r.fs)); out.push({ tag, cls, kind: 'text', // x/w 用容器的：居中的段落要靠容器宽度维持居中语义， // 用段落自己收缩后的宽度会在换字体后左右飘。 x: base.x, w: base.w, y: bb.top - pb.top, h: bb.height, fs: px(cs.fontSize), fsMax, fw: cs.fontWeight, color: cs.color, ls: cs.letterSpacing === 'normal' ? 0 : px(cs.letterSpacing), ta: cs.textAlign, lhEff: bb.height / lines, lines, wrap: lines > 1, runs: rs, }); } // 行内的纯装饰色块（压在字上的删除线、高亮条）不能跟着文字被吞掉， // 单独出形状，且要画在文字之上。 for (const c of el.children) { const ccs = getComputedStyle(c); const cbg = ccs.backgroundColor; if (c.textContent.trim() === '' && cbg !== 'rgba(0, 0, 0, 0)' && cbg !== 'transparent') { const cr = c.getBoundingClientRect(); let rot = 0; const m = ccs.transform.match(/matrix\(([^)]+)\)/); if (m) { const [a, b] = m[1].split(',').map(parseFloat); rot = Math.round(Math.atan2(b, a) * 180 / Math.PI * 10) / 10; } out.push({tag: c.tagName.toLowerCase(), cls: '', kind: 'shape', x: cr.left - pb.left, y: cr.top - pb.top, w: cr.width, h: cr.height, bg: cbg, bdw: px(ccs.borderTopWidth), bdc: ccs.borderTopColor, radius: px(ccs.borderRadius), shadow: ccs.boxShadow, rot}); } } return; } for (const c of el.children) walk(c); }; for (const c of pg.children) walk(c); return {w: pb.width, h: pb.height, els: out}; }); } """ async def render(html, selector, asset_dir, scale): from playwright.async_api import async_playwright os.makedirs(asset_dir, exist_ok=True) async with async_playwright() as p: br = await p.chromium.launch() pg = await br.new_page(viewport={"width": 1920, "height": 1080}, device_scale_factor=scale) await pg.goto("file://" + os.path.abspath(html)) await pg.wait_for_timeout(2500) pages = await pg.evaluate(JS, selector) for pi, page in enumerate(pages): # SVG / canvas 单独截成 PNG for e in page["els"]: if e["kind"] == "svg": name = f"p{pi+1:02d}_{e['tagName']}{e['seq']}.png" await pg.locator(selector).nth(pi).locator(e["tagName"]).nth(e["seq"]) \ .screenshot(path=os.path.join(asset_dir, name), omit_background=True) e["file"] = os.path.join(asset_dir, name) await br.close() return pages # ───────────────────────────────────────────────────────────── # 二、翻译成 PowerPoint 对象 # ───────────────────────────────────────────────────────────── ALIGN = {"left": PP_ALIGN.LEFT, "center": PP_ALIGN.CENTER, "start": PP_ALIGN.LEFT, "right": PP_ALIGN.RIGHT, "end": PP_ALIGN.RIGHT, "justify": PP_ALIGN.JUSTIFY} def parse_color(css): """'rgb(r,g,b)' / 'rgba(r,g,b,a)' → (RGBColor, alpha)。""" m = re.findall(r"[\d.]+", css or "") if len(m) < 3: return None, 0.0 r, g, b = (int(float(v)) for v in m[:3]) return RGBColor(r, g, b), (float(m[3]) if len(m) > 3 else 1.0) def _alpha(clr_el, alpha): a = clr_el.makeelement(qn("a:alpha"), {}) a.set("val", str(int(alpha * 100000))) clr_el.append(a) class Builder: def __init__(self, cfg): self.cfg = cfg self.round_dir = os.path.join(cfg.asset_dir, "_round") # ── 文本 ────────────────────────────────────────────── def set_run_font(self, run, r): f = run.font f.size = Pt(r["fs"] * self.k) fw = str(r["fw"]) f.bold = int(fw) >= 600 if fw.isdigit() else fw in ("bold", "bolder") f.italic = r.get("italic", False) f.underline = r.get("under", False) f.name = self.cfg.font_latin # 只设了 latin，中文要另外指定 col, alpha = parse_color(r["color"]) if col: f.color.rgb = col rPr = run._r.get_or_add_rPr() for tag, val in (("a:ea", self.cfg.font_ea), ("a:cs", self.cfg.font_latin)): el = rPr.find(qn(tag)) if el is None: el = rPr.makeelement(qn(tag), {}) rPr.append(el) el.set("typeface", val) if r.get("ls"): rPr.set("spc", str(int(round(r["ls"] * self.k * 100)))) # 单位 1/100 pt if col and alpha < 1: solid = rPr.find(qn("a:solidFill")) if solid is not None and solid.find(qn("a:srgbClr")) is not None: _alpha(solid.find(qn("a:srgbClr")), alpha) def add_text(self, slide, e): """一个段落 → 一个文本框。 宽度要放余量：视觉稿里这些框常是 flex 收缩包裹的，宽度恰好等于文字宽度， 换到 PowerPoint 只要字体度量差一点点，最后一个字就会被挤到下一行。 本来就是单行的段落直接关掉自动换行，从根上不可能折行。 """ k = self.k wrap = e.get("wrap", True) fs = e.get("fsMax") or e["fs"] # 容器字号常常是继承来的小值，余量要按最大的字算 pad = (fs * 0.25) if wrap else max(12.0, fs * 0.8) x, w = e["x"], e["w"] + pad ta = e.get("ta") if ta in ("center",): x -= pad / 2 # 居中框两边一起放，视觉中心不动 elif ta in ("right", "end"): x -= pad box = slide.shapes.add_textbox(Pt(x * k), Pt(e["y"] * k), Pt(w * k), Pt(e["h"] * k)) tf = box.text_frame tf.word_wrap = wrap tf.auto_size = None tf.vertical_anchor = MSO_ANCHOR.TOP tf.margin_left = tf.margin_right = tf.margin_top = tf.margin_bottom = 0 paras = [[]] for r in e["runs"]: paras.append([]) if r.get("br") else paras[-1].append(r) paras = [p for p in paras if p] or [[]] for i, runs in enumerate(paras): p = tf.paragraphs[0] if i == 0 else tf.add_paragraph() p.alignment = ALIGN.get(ta, PP_ALIGN.LEFT) # 行距只对「这一段自己折了行」的框设。单行段落不设：量到的行盒高度比实际行间距 # 大（那是字体行盒不是 CSS 行距），拿它当精确行距会把文字整体压下去； # 单行时交给 PowerPoint 按字号自然排，文字紧贴框顶，位置最准。 if e.get("lines", 1) > 1 and e.get("lhEff"): p.line_spacing = Pt(e["lhEff"] * k) for r in runs: run = p.add_run() run.text = r["t"] self.set_run_font(run, r) return box # ── 形状 ────────────────────────────────────────────── def add_shape(self, slide, e): k = self.k rounded = e.get("radius", 0) >= 4 shp = slide.shapes.add_shape( MSO_SHAPE.ROUNDED_RECTANGLE if rounded else MSO_SHAPE.RECTANGLE, Pt(e["x"] * k), Pt(e["y"] * k), Pt(e["w"] * k), Pt(e["h"] * k)) shp.shadow.inherit = False col, alpha = parse_color(e.get("bg")) if col and alpha > 0: shp.fill.solid() shp.fill.fore_color.rgb = col if alpha < 1: sf = shp.fill._xPr.find(qn("a:solidFill")) _alpha(sf.find(qn("a:srgbClr")), alpha) else: shp.fill.background() bcol, balpha = parse_color(e.get("bdc")) if e.get("bdw", 0) > 0 and bcol and balpha > 0: shp.line.color.rgb = bcol shp.line.width = Pt(e["bdw"] * k) else: shp.line.fill.background() if e.get("rot"): shp.rotation = -e["rot"] # CSS 逆时针为负，PowerPoint 顺时针为正 if rounded and e["w"] and e["h"]: # PowerPoint 的圆角是「短边的百分比」，换算回 CSS 的 px 半径 shp.adjustments[0] = min(0.5, e["radius"] / min(e["w"], e["h"])) return shp # ── 图片 ────────────────────────────────────────────── def round_corners(self, path, radius_px, box_w): """PowerPoint 的图片没有圆角，把圆角烤进 PNG 的 alpha 通道。""" os.makedirs(self.round_dir, exist_ok=True) out = os.path.join(self.round_dir, f"{abs(hash((path, radius_px, box_w))) % 10**10}.png") if os.path.exists(out): return out im = Image.open(path).convert("RGBA") scale = im.width / box_w if box_w else 1 r = int(min(radius_px * scale, min(im.size) / 2)) mask = Image.new("L", im.size, 0) ImageDraw.Draw(mask).rounded_rectangle([0, 0, im.width - 1, im.height - 1], radius=r, fill=255) im.putalpha(mask) im.save(out) return out def add_img(self, slide, e): k = self.k src = e.get("file") or e["src"] if not src or src.startswith("data:"): return None path = src if os.path.isabs(src) else os.path.normpath(os.path.join(self.html_dir, src)) if not os.path.exists(path): print(f" ⚠️ 找不到图片 {src}") return None if e.get("radius", 0) >= 2: path = self.round_corners(path, e["radius"], e["w"]) pic = slide.shapes.add_picture(path, Pt(e["x"] * k), Pt(e["y"] * k), Pt(e["w"] * k), Pt(e["h"] * k)) # box-shadow: rgba(...) 0 0 0 Npx 在视觉稿里通常是硬描边，翻译成图片边框 m = re.match(r"rgba?\(([^)]+)\)\s+0px\s+0px\s+0px\s+([\d.]+)px", e.get("shadow") or "") if m: col, alpha = parse_color("rgba(" + m.group(1) + ")") if col and alpha > 0: pic.line.color.rgb = col pic.line.width = Pt(float(m.group(2)) * k) return pic # ── 装配 ────────────────────────────────────────────── def run(self, pages): cfg = self.cfg self.html_dir = os.path.dirname(os.path.abspath(cfg.html)) if cfg.template: prs = Presentation(cfg.template) strip_slides(prs) # 模板自带的示例页删掉，母版/版式一个不动 else: prs = Presentation() pw, ph = pages[0]["w"], pages[0]["h"] prs.slide_width, prs.slide_height = Pt(pw), Pt(ph) # 1 CSS px = 1 pt # HTML 画布宽 → 幻灯片宽 的比例。画布 1920px 配 26.667in(=1920pt) 时正好是 1.0。 self.k = (prs.slide_width / EMU_PER_PT) / pages[0]["w"] if cfg.layout: layout = next((l for l in prs.slide_layouts if l.name == cfg.layout), None) if layout is None: names = " / ".join(l.name for l in prs.slide_layouts) sys.exit(f"❌ 模板里没有版式「{cfg.layout}」。可选：{names}") killed = unblock_layout(layout, prs.slide_width, prs.slide_height) else: layout = prs.slide_layouts[6] if len(prs.slide_layouts) > 6 else prs.slide_layouts[0] killed = [] n_text = n_shape = n_img = 0 for page in pages: slide = prs.slides.add_slide(layout) for sh in list(slide.shapes): # 版式带来的空占位符不留在页面上 sh._element.getparent().remove(sh._element) if cfg.bg: set_bg(slide, cfg.bg) for e in page["els"]: if cfg.skip_class and cfg.skip_class in (e.get("cls") or "").split(): continue if e["kind"] == "shape": self.add_shape(slide, e); n_shape += 1 elif e["kind"] == "text": self.add_text(slide, e); n_text += 1 else: if self.add_img(slide, e) is not None: n_img += 1 prs.save(cfg.out) mb = os.path.getsize(cfg.out) / 1024 / 1024 print(f"✅ {len(prs.slides)} 页 → {os.path.basename(cfg.out)}（{mb:.1f}MB）") print(f" 文本框 {n_text} · 形状 {n_shape} · 图片 {n_img}" + (f" · 清掉版式遮罩 {killed}" if killed else "")) print(f" 画布 {prs.slide_width/914400:.3f}×{prs.slide_height/914400:.3f} inch" f"（缩放 {self.k:.4f}）") # ───────────────────────────────────────────────────────────── # 三、模板相关的三个小手术 # ───────────────────────────────────────────────────────────── def strip_slides(prs): """删掉模板自带的示例页；母版、版式、主题、色板一个不动。""" lst = prs.slides._sldIdLst for sld in list(lst): prs.part.drop_rel(sld.rId) lst.remove(sld) def unblock_layout(layout, W, H): """删掉版式里铺满全屏的纯色矩形。 有些官方模板的版式里放着一个和版式底色同色同尺寸的全屏矩形（冗余遮罩）。 留着它，页面上任何放在它下面的东西都会被挡住；删掉不改变版式的外观。 """ killed = [] for sp in list(layout.shapes): full = (sp.left == 0 and sp.top == 0 and sp.width and sp.height and sp.width >= W and sp.height >= H) if full and b"<a:solidFill>" in sp._element.xml.encode(): sp._element.getparent().remove(sp._element) killed.append(sp.name) return killed def set_bg(slide, rgb_hex): bg = slide._element.makeelement(qn("p:bg"), {}) pr = slide._element.makeelement(qn("p:bgPr"), {}) fill = slide._element.makeelement(qn("a:solidFill"), {}) clr = slide._element.makeelement(qn("a:srgbClr"), {"val": rgb_hex.lstrip("#").upper()}) fill.append(clr); pr.append(fill) pr.append(slide._element.makeelement(qn("a:effectLst"), {})) bg.append(pr) slide._element.find(qn("p:cSld")).insert(0, bg) # ───────────────────────────────────────────────────────────── def main(): ap = argparse.ArgumentParser(description="视觉稿 HTML → 可编辑 PPTX（读渲染后坐标，不改 HTML）") ap.add_argument("html") ap.add_argument("-o", "--out", required=True, help="输出 .pptx") ap.add_argument("--selector", default=".slide, .s, section", help="每一页的 CSS 选择器（默认 '.slide, .s, section'）") ap.add_argument("--template", help="以这个 .pptx 为基底，继承它的母版/版式/主题/色板") ap.add_argument("--layout", help="每页套用的版式名（配合 --template）") ap.add_argument("--skip-class", help="跳过带这个 class 的元素，例如 logo 由版式提供时填 logo") ap.add_argument("--font-latin", default="Microsoft YaHei", help="西文字体名") ap.add_argument("--font-ea", default="微软雅黑", help="东亚字体名") ap.add_argument("--bg", help="每页底色，如 05070B；不给则用版式底色") ap.add_argument("--asset-dir", help="SVG/圆角图的落地目录（默认 输出同级 _pptx_assets/）") ap.add_argument("--scale", type=int, default=3, help="SVG 截图倍数（默认 3）") ap.add_argument("--dump-json", help="把量到的元素清单写出来，便于排查") cfg = ap.parse_args() cfg.out = os.path.abspath(cfg.out) cfg.asset_dir = cfg.asset_dir or os.path.join(os.path.dirname(cfg.out), "_pptx_assets") if cfg.layout and not cfg.template: sys.exit("❌ --layout 需要配合 --template 使用") pages = asyncio.run(render(cfg.html, cfg.selector, cfg.asset_dir, cfg.scale)) if not pages: sys.exit(f"❌ 选择器 '{cfg.selector}' 一页都没匹配到") if cfg.dump_json: json.dump(pages, open(cfg.dump_json, "w"), ensure_ascii=False, indent=1) kinds = {} for p in pages: for e in p["els"]: kinds[e["kind"]] = kinds.get(e["kind"], 0) + 1 print(f"📐 量到 {len(pages)} 页 {kinds}") Builder(cfg).run(pages) if __name__ == "__main__": main() -
render-narration.sh 5.3 KB
#!/usr/bin/env bash # render-narration.sh · 一条龙：HTML 解说动画 → 最终 MP4（带人声） # # 流水线： # 1. render-video.js 录无声 MP4（按 timeline.totalDuration） # 2. mix-voiceover.sh 混入 voiceover.mp3（可选 BGM） # 3. 输出 <basename>-narrated.mp4 # # Usage: # bash render-narration.sh <html> --timeline=<path> [options] # # Required: # <html> 解说动画的 HTML（应内嵌 NarrationStage + recording 模式 rAF 自驱） # --timeline=<path> timeline.json 路径（自动读 totalDuration 和 voiceover.mp3 路径） # # Optional: # --bgm-mood=<name> BGM 预设（educational / tech / tutorial / ...） # --bgm=<path> 自定义 BGM 文件 # --bgm-volume=<0-1> BGM 静态音量，默认 0.18 # --no-ducking 关 sidechain ducking # --keep-silent 保留中间产物（无声 MP4），便于 debug # --seek 用 render-video-seek.js 逐帧 seek 渲染（真 60fps·确定性·无黑帧） # --seek-fps=<n> seek 渲染帧率，默认 60，需配合 --seek # --out=<path> 输出路径，默认 <html-basename>-narrated.mp4 # --width=<px> 视频宽度（默认 1920） # --height=<px> 视频高度（默认 1080） # # Examples: # bash render-narration.sh demo.html --timeline=_narration/timeline.json # bash render-narration.sh demo.html --timeline=_narration/timeline.json --bgm-mood=educational # set -e SCRIPT_DIR="$(cd "$(dirname "$0")" && pwd)" SKILL_ROOT="$SCRIPT_DIR/.." HTML="" TIMELINE="" BGM_MOOD="" BGM="" BGM_VOLUME="0.18" NO_DUCKING="" KEEP_SILENT="" USE_SEEK="" SEEK_FPS="60" OUT="" WIDTH="1920" HEIGHT="1080" for arg in "$@"; do case "$arg" in --timeline=*) TIMELINE="${arg#*=}" ;; --bgm-mood=*) BGM_MOOD="${arg#*=}" ;; --bgm=*) BGM="${arg#*=}" ;; --bgm-volume=*) BGM_VOLUME="${arg#*=}" ;; --no-ducking) NO_DUCKING="--no-ducking" ;; --keep-silent) KEEP_SILENT="1" ;; --seek) USE_SEEK="1" ;; --seek-fps=*) SEEK_FPS="${arg#*=}" ;; --out=*) OUT="${arg#*=}" ;; --width=*) WIDTH="${arg#*=}" ;; --height=*) HEIGHT="${arg#*=}" ;; -*) echo "未知参数：$arg" >&2; exit 1 ;; *) HTML="$arg" ;; esac done if [ -z "$HTML" ] || [ ! -f "$HTML" ]; then echo "Usage: bash render-narration.sh <html> --timeline=<path> [options]" >&2 exit 1 fi if [ -z "$TIMELINE" ] || [ ! -f "$TIMELINE" ]; then echo "✗ 缺 --timeline=<path>（timeline.json 由 narrate-pipeline.mjs 生成）" >&2 exit 1 fi # ── 从 timeline.json 读 totalDuration 和 voiceover 路径 ── TIMELINE_DIR="$(cd "$(dirname "$TIMELINE")" && pwd)" TOTAL_DURATION=$(node -e "console.log(JSON.parse(require('fs').readFileSync('$TIMELINE','utf8')).totalDuration)") VOICEOVER_REL=$(node -e "console.log(JSON.parse(require('fs').readFileSync('$TIMELINE','utf8')).voiceover || 'voiceover.mp3')") VOICEOVER="$TIMELINE_DIR/$VOICEOVER_REL" if [ ! -f "$VOICEOVER" ]; then echo "✗ voiceover.mp3 不存在: $VOICEOVER" >&2 exit 1 fi # 录制时长 = 总时长 + 1s 安全缓冲 RECORD_DURATION=$(node -e "console.log(Math.ceil($TOTAL_DURATION + 1))") HTML_ABS="$(cd "$(dirname "$HTML")" && pwd)/$(basename "$HTML")" HTML_DIR="$(dirname "$HTML_ABS")" HTML_BASE="$(basename "$HTML" .html)" SILENT_MP4="$HTML_DIR/$HTML_BASE.mp4" if [ -z "$OUT" ]; then OUT="$HTML_DIR/$HTML_BASE-narrated.mp4" fi echo "═══ render-narration ═══════════════════" echo " HTML: $HTML_ABS" echo " Timeline: $TIMELINE" echo " Voiceover: $VOICEOVER" echo " Total dur: ${TOTAL_DURATION}s (录 ${RECORD_DURATION}s)" echo " 尺寸: ${WIDTH}×${HEIGHT}" [ -n "$BGM_MOOD" ] && echo " BGM mood: $BGM_MOOD" [ -n "$BGM" ] && echo " BGM: $BGM" echo " 最终输出: $OUT" echo "════════════════════════════════════════" # ── Step 1: 录无声 MP4 ────────────────────── echo "" if [ -n "$USE_SEEK" ]; then echo "▸ Step 1/2 · 逐帧 seek 渲染 HTML 动画 (无声 · ${SEEK_FPS}fps 确定性)" NODE_PATH=$(npm root -g) node "$SCRIPT_DIR/render-video-seek.js" "$HTML_ABS" \ --duration="$RECORD_DURATION" \ --fps="$SEEK_FPS" \ --width="$WIDTH" \ --height="$HEIGHT" else echo "▸ Step 1/2 · 录制 HTML 动画 (无声)" NODE_PATH=$(npm root -g) node "$SCRIPT_DIR/render-video.js" "$HTML_ABS" \ --duration="$RECORD_DURATION" \ --width="$WIDTH" \ --height="$HEIGHT" fi if [ ! -f "$SILENT_MP4" ]; then echo "✗ 无声 MP4 没生成: $SILENT_MP4" >&2 exit 1 fi # ── Step 2: 混入人声 ────────────────────── echo "" echo "▸ Step 2/2 · 混入人声" MIX_ARGS=("$SILENT_MP4" "--voiceover=$VOICEOVER" "--out=$OUT") [ -n "$BGM_MOOD" ] && MIX_ARGS+=("--bgm-mood=$BGM_MOOD") [ -n "$BGM" ] && MIX_ARGS+=("--bgm=$BGM") [ -n "$BGM_MOOD$BGM" ] && MIX_ARGS+=("--bgm-volume=$BGM_VOLUME") [ -n "$NO_DUCKING" ] && MIX_ARGS+=("$NO_DUCKING") bash "$SCRIPT_DIR/mix-voiceover.sh" "${MIX_ARGS[@]}" # 清理中间产物 if [ -z "$KEEP_SILENT" ]; then rm -f "$SILENT_MP4" fi echo "" echo "✓ 完成: $OUT" [ -n "$KEEP_SILENT" ] && echo " (中间产物保留: $SILENT_MP4)" -
render-video-seek.js 9.5 KB
#!/usr/bin/env node /** * HTML animation → MP4 via deterministic frame-by-frame SEEK (Playwright + ffmpeg). * * 这是 render-video.js（Playwright recordVideo）的逐帧替代渲染器。技术内核借鉴 * HeyGen HyperFrames（Apache 2.0）的「冻结时钟 + seek 到时间戳截图」思路，但不引入 * 任何第三方包——只用本 skill 已有的 playwright + ffmpeg，runtime 中立。 * * 相比 render-video.js 解决的三个死结（见 references/video-export.md §「seek 渲染」）： * 1. 帧率不再被 Chromium headless compositor 锁死 25fps —— --fps 原生任意帧率 * 2. 不再需要 convert-formats.sh 的 minterpolate 事后插帧（有 ghosting + macOS * QuickTime 兼容 bug，见 animation-pitfalls §14）—— 每帧都是真实 seek 画面 * 3. 不录屏 → 无开头黑帧 → 不需要 --trim / --fontwait / __ready 偏移那套逻辑 * 额外：seek 到时间戳截图，同输入同输出 deterministic（recordVideo 是实时录制非确定性） * * 前提：动画必须走 Stage 时钟（assets/animations.jsx 的 <Stage> 或 narration_stage.jsx * 的 <NarrationStage>），它们会响应 window.__seekRender 冻结自驱时钟、并暴露 * window.__seek(t)。纯 CSS @keyframes / Lottie / 非 Stage 驱动的动画不吃 __seek， * 这类请继续用 render-video.js。 * * Requires: global playwright (`npm install -g playwright`), ffmpeg on PATH. * * Usage: * NODE_PATH=$(npm root -g) node render-video-seek.js <html-file> \ * [--duration=30] [--fps=60] [--width=1920] [--height=1080] \ * [--concurrency=4] [--settle=2] [--keep-chrome] * * Output: next to the HTML file, same basename with .mp4 suffix. */ const { chromium } = require('playwright'); const path = require('path'); const fs = require('fs'); const { spawnSync } = require('child_process'); function arg(name, def) { const p = process.argv.find(a => a.startsWith('--' + name + '=')); return p ? p.slice(name.length + 3) : def; } function hasFlag(name) { return process.argv.includes('--' + name); } const HTML_FILE = process.argv[2]; if (!HTML_FILE || HTML_FILE.startsWith('--')) { console.error('Usage: node render-video-seek.js <html-file>'); console.error('Example: NODE_PATH=$(npm root -g) node render-video-seek.js my-animation.html --fps=60'); process.exit(1); } const DURATION = parseFloat(arg('duration', '30')); const FPS = parseFloat(arg('fps', '60')); // 原生任意帧率，默认真 60fps const WIDTH = parseInt(arg('width', '1920')); const HEIGHT = parseInt(arg('height', '1080')); const CONCURRENCY = Math.max(1, parseInt(arg('concurrency', '4'))); // 并行 worker 数（每个一个 page） const SETTLE = Math.max(1, parseInt(arg('settle', '2'))); // seek 后等几个 rAF 再截图 const READY_TIMEOUT = parseFloat(arg('readytimeout', '8')); const KEEP_CHROME = hasFlag('keep-chrome'); const HTML_ABS = path.resolve(HTML_FILE); const BASENAME = path.basename(HTML_FILE, path.extname(HTML_FILE)); const DIR = path.dirname(HTML_ABS); const TMP_DIR = path.join(DIR, '.seek-tmp-' + Date.now() + '-' + process.pid); const MP4_OUT = path.join(DIR, BASENAME + '.mp4'); // 与 render-video.js 完全一致的 chrome 隐藏规则（保证两条链路出片外观一致） const HIDE_CHROME_CSS = ` .no-record, .progress, .progress-bar, .counter, .tCur, .phases, .phase-label, .phase, .replay, button.replay, .masthead, .kicker, .title, .footer, [data-role="chrome"], [data-record="hidden"] { display: none !important; } `; const TOTAL_FRAMES = Math.round(FPS * DURATION); console.log(`▸ Seek-rendering: ${HTML_FILE}`); console.log(` size: ${WIDTH}x${HEIGHT} · ${FPS}fps · duration: ${DURATION}s · frames: ${TOTAL_FRAMES} · workers: ${CONCURRENCY}`); console.log(` output: ${MP4_OUT}`); // 在 page 上下文里运行：等 SETTLE 个 rAF（让 React/Babel commit + 布局稳定后再截图） async function waitRaf(page, n) { await page.evaluate((count) => new Promise(resolve => { let i = 0; const step = () => { i++; (i >= count) ? resolve() : requestAnimationFrame(step); }; requestAnimationFrame(step); }), n); } // 一个 worker：开一个 page，goto，等 __seek 就绪，渲染分配给它的帧 async function renderFrames(context, url, frames) { const page = await context.newPage(); await page.goto(url, { waitUntil: 'load', timeout: 60000 }); // Stage / NarrationStage 在 __seekRender 模式下会暴露 window.__seek 并冻结自驱时钟 await page.waitForFunction( () => window.__ready === true && typeof window.__seek === 'function', { timeout: READY_TIMEOUT * 1000 }, ); for (const f of frames) { const t = f / FPS; await page.evaluate((tt) => window.__seek(tt), t); await waitRaf(page, SETTLE); await page.screenshot({ path: path.join(TMP_DIR, 'frame-' + String(f).padStart(6, '0') + '.png'), clip: { x: 0, y: 0, width: WIDTH, height: HEIGHT }, }); } await page.close(); } (async () => { fs.mkdirSync(TMP_DIR, { recursive: true }); const browser = await chromium.launch(); const url = 'file://' + HTML_ABS; const context = await browser.newContext({ viewport: { width: WIDTH, height: HEIGHT }, deviceScaleFactor: 1, }); // 关键信号：__seekRender 让 Stage / NarrationStage 冻结 wall-clock rAF，改由外部 __seek 推帧 // __recording 沿用，让 Stage 强制 loop=false（复用既有约定） await context.addInitScript(() => { window.__recording = true; window.__seekRender = true; }); if (!KEEP_CHROME) { // 与 render-video.js 同款 chrome 隐藏（CSS + 固定栏启发式） await context.addInitScript(css => { const HIDE_MARK = 'data-video-hidden'; function injectStyle() { const style = document.createElement('style'); style.setAttribute('data-inject', 'render-video-chrome-hide'); style.textContent = css; (document.head || document.documentElement).appendChild(style); } function hideChromeBars() { const vh = window.innerHeight; document.querySelectorAll('div, nav, header, footer, section, aside') .forEach(el => { if (el.hasAttribute(HIDE_MARK)) return; if (el.dataset.recordKeep === 'true') return; const s = getComputedStyle(el); if (s.position !== 'fixed' && s.position !== 'sticky') return; const r = el.getBoundingClientRect(); if (r.height > vh * 0.25) return; const atBottom = r.bottom >= vh - 30; const atTop = r.top <= 30 && r.height < 80; if (!atBottom && !atTop) return; const txt = el.textContent || ''; const hasBtn = !!el.querySelector('button, [role="button"]'); const hasCtrls = /[⏸▶⏮⏭↻↺↩↪]|\d+\.\d+\s*s/.test(txt); if (hasBtn || hasCtrls) { el.style.setProperty('display', 'none', 'important'); el.setAttribute(HIDE_MARK, '1'); } }); } const start = () => { injectStyle(); hideChromeBars(); const obs = new MutationObserver(hideChromeBars); obs.observe(document.body, { childList: true, subtree: true }); setTimeout(() => obs.disconnect(), 6000); }; if (document.readyState === 'loading') { document.addEventListener('DOMContentLoaded', start, { once: true }); } else { start(); } }, HIDE_CHROME_CSS); } // 把帧 round-robin 分给 CONCURRENCY 个 worker（每个 page 独立 window，seek 互不干扰） const buckets = Array.from({ length: CONCURRENCY }, () => []); for (let f = 0; f < TOTAL_FRAMES; f++) buckets[f % CONCURRENCY].push(f); console.log(`▸ Capturing ${TOTAL_FRAMES} frames across ${CONCURRENCY} workers…`); try { await Promise.all(buckets.map(b => b.length ? renderFrames(context, url, b) : Promise.resolve())); } catch (e) { const msg = String(e && e.message || e); if (/__seek|__ready/.test(msg)) { console.error(''); console.error('✗ 动画没有暴露 window.__seek（或未就绪）。'); console.error(' seek 渲染只支持走 Stage 时钟的动画（assets/animations.jsx 的 <Stage>'); console.error(' 或 narration_stage.jsx 的 <NarrationStage>）。纯 CSS @keyframes / Lottie /'); console.error(' 手写非 Stage 动画请改用 render-video.js。'); console.error(''); } await browser.close(); fs.rmSync(TMP_DIR, { recursive: true, force: true }); console.error(msg.slice(0, 500)); process.exit(1); } await browser.close(); const pngCount = fs.readdirSync(TMP_DIR).filter(f => f.endsWith('.png')).length; if (pngCount === 0) { console.error('✗ 没有截到任何帧'); process.exit(1); } console.log(`▸ Captured ${pngCount}/${TOTAL_FRAMES} frames. Encoding H.264…`); // PNG 序列 → MP4。无 trim（本来就没黑帧），输入输出帧率都设 FPS。 const ffmpeg = spawnSync('ffmpeg', [ '-y', '-framerate', String(FPS), '-i', path.join(TMP_DIR, 'frame-%06d.png'), '-c:v', 'libx264', '-pix_fmt', 'yuv420p', '-crf', '18', '-preset', 'medium', '-r', String(FPS), '-movflags', '+faststart', MP4_OUT, ], { stdio: ['ignore', 'ignore', 'pipe'] }); if (ffmpeg.status !== 0) { console.error('✗ ffmpeg failed:\n' + ffmpeg.stderr.toString().slice(-2000)); process.exit(1); } fs.rmSync(TMP_DIR, { recursive: true, force: true }); const mp4Size = (fs.statSync(MP4_OUT).size / 1024 / 1024).toFixed(1); console.log(`✓ Done: ${MP4_OUT} (${mp4Size} MB · ${FPS}fps native)`); })(); -
render-video.js 12 KB
#!/usr/bin/env node /** * HTML animation → MP4 via Playwright recordVideo + ffmpeg. * * Requires: global playwright (`npm install -g playwright`), ffmpeg on PATH. * * Usage: * NODE_PATH=$(npm root -g) node render-video.js <html-file> \ * [--duration=30] [--width=1920] [--height=1080] \ * [--trim=<seconds>] [--fontwait=1.5] [--readytimeout=8] \ * [--keep-chrome] * * Design: * 1. Warmup context (no record) — caches fonts/assets, closes cleanly * 2. Record context (fresh, recordVideo ON) — WebM starts writing at * context creation. Babel-standalone compile + React mount + * fonts.ready can take 1.5-3s, during which WebM writes black frames. * We measure this by waiting for window.__ready (set by animations.jsx * Stage component after first paint), then trim exactly that offset. * 3. addInitScript injects CSS hiding "chrome" elements (progress bar, * replay button, masthead, footer, etc.) that are fine for human * debugging but shouldn't appear in exported video. * * Animation-ready signal: * Set `window.__ready = true` in your HTML after first paint. This tells * the recorder "animation has started rendering — treat now as t=0". * If you use animations.jsx, Stage does this automatically. Otherwise * add: `document.fonts.ready.then(() => requestAnimationFrame(() => { window.__ready = true }));` * after your first render call. * * Without __ready, falls back to --fontwait=1.5s (may leave 1-2s of black * at the start). Pass --trim=<seconds> to override manually. * * Chrome elements hidden by default (all common class names + `.no-record` * convention). Pass --keep-chrome to disable this and see raw HTML. * * Output: next to the HTML file, same basename with .mp4 suffix. */ const { chromium } = require('playwright'); const path = require('path'); const fs = require('fs'); const { spawnSync } = require('child_process'); function arg(name, def) { const p = process.argv.find(a => a.startsWith('--' + name + '=')); return p ? p.slice(name.length + 3) : def; } function hasFlag(name) { return process.argv.includes('--' + name); } const HTML_FILE = process.argv[2]; if (!HTML_FILE || HTML_FILE.startsWith('--')) { console.error('Usage: node render-video.js <html-file>'); console.error('Example: NODE_PATH=$(npm root -g) node render-video.js my-animation.html'); process.exit(1); } const DURATION = parseFloat(arg('duration', '30')); const WIDTH = parseInt(arg('width', '1920')); const HEIGHT = parseInt(arg('height', '1080')); const TRIM_OVERRIDE = arg('trim', null); // manual override (seconds). If unset, auto-detected. const FONT_WAIT = parseFloat(arg('fontwait', '1.5')); // fallback when no __ready signal const READY_TIMEOUT = parseFloat(arg('readytimeout', '8')); const KEEP_CHROME = hasFlag('keep-chrome'); const HTML_ABS = path.resolve(HTML_FILE); const BASENAME = path.basename(HTML_FILE, path.extname(HTML_FILE)); const DIR = path.dirname(HTML_ABS); const TMP_DIR = path.join(DIR, '.video-tmp-' + Date.now() + '-' + process.pid); const MP4_OUT = path.join(DIR, BASENAME + '.mp4'); // CSS to hide "chrome" elements during recording. // Covers class-name conventions seen across skill-built animations, // plus a `.no-record` explicit opt-out class. const HIDE_CHROME_CSS = ` .no-record, .progress, .progress-bar, .counter, .tCur, .phases, .phase-label, .phase, .replay, button.replay, .masthead, .kicker, .title, .footer, [data-role="chrome"], [data-record="hidden"] { display: none !important; } `; console.log(`▸ Rendering: ${HTML_FILE}`); console.log(` size: ${WIDTH}x${HEIGHT} · duration: ${DURATION}s · hide-chrome: ${!KEEP_CHROME}`); console.log(` output: ${MP4_OUT}`); (async () => { fs.mkdirSync(TMP_DIR, { recursive: true }); const browser = await chromium.launch(); const url = 'file://' + HTML_ABS; // ── Phase 1: WARMUP (no recording, caches fonts/assets) ───────────── console.log('▸ Warmup (caching fonts)…'); const warmupCtx = await browser.newContext({ viewport: { width: WIDTH, height: HEIGHT }, }); const warmupPage = await warmupCtx.newPage(); // 'load' not 'networkidle' — unpkg/Google Fonts can keep connections alive // past our 30s budget even after all critical resources are in. __ready // flag + FONT_WAIT handle animation-readiness properly. await warmupPage.goto(url, { waitUntil: 'load', timeout: 60000 }); await warmupPage.waitForTimeout(FONT_WAIT * 1000); await warmupCtx.close(); // ── Phase 2: RECORD (fresh context, animation from t=0) ───────────── console.log('▸ Recording (clean start)…'); const recordCtx = await browser.newContext({ viewport: { width: WIDTH, height: HEIGHT }, deviceScaleFactor: 1, recordVideo: { dir: TMP_DIR, size: { width: WIDTH, height: HEIGHT }, }, }); // Tell the page it's being recorded — animations.jsx Stage reads this // and forces loop=false so the export ends on the final frame instead of // capturing the start of the next cycle. Hand-written Stage components // should also honor this signal (see animation-pitfalls.md §13). await recordCtx.addInitScript(() => { window.__recording = true; }); // Inject CSS + JS heuristic to hide "chrome" elements. // Two layers: // A. CSS selectors for common class-name conventions (cheap) // B. JS heuristic for fixed-position bars containing buttons or time // readouts (catches inline-styled chrome like <Stage> controls) // Persists across reloads via addInitScript. if (!KEEP_CHROME) { await recordCtx.addInitScript(css => { const HIDE_MARK = 'data-video-hidden'; function injectStyle() { const style = document.createElement('style'); style.setAttribute('data-inject', 'render-video-chrome-hide'); style.textContent = css; (document.head || document.documentElement).appendChild(style); } function hideChromeBars() { const vh = window.innerHeight; document.querySelectorAll('div, nav, header, footer, section, aside') .forEach(el => { if (el.hasAttribute(HIDE_MARK)) return; if (el.dataset.recordKeep === 'true') return; const s = getComputedStyle(el); if (s.position !== 'fixed' && s.position !== 'sticky') return; const r = el.getBoundingClientRect(); // Only skinny bars (not full-screen overlays) if (r.height > vh * 0.25) return; const atBottom = r.bottom >= vh - 30; const atTop = r.top <= 30 && r.height < 80; if (!atBottom && !atTop) return; // Chrome-like: contains button or scrubber/time glyphs const txt = el.textContent || ''; const hasBtn = !!el.querySelector('button, [role="button"]'); const hasCtrls = /[⏸▶⏮⏭↻↺↩↪]|\d+\.\d+\s*s/.test(txt); if (hasBtn || hasCtrls) { el.style.setProperty('display', 'none', 'important'); el.setAttribute(HIDE_MARK, '1'); } }); } const start = () => { injectStyle(); hideChromeBars(); // Re-run as React/Vue commits DOM changes const obs = new MutationObserver(hideChromeBars); obs.observe(document.body, { childList: true, subtree: true }); setTimeout(() => obs.disconnect(), 6000); }; if (document.readyState === 'loading') { document.addEventListener('DOMContentLoaded', start, { once: true }); } else { start(); } }, HIDE_CHROME_CSS); } // Record context opens page. The WebM starts writing the moment the // context is created — so we track T0 here and measure how many seconds // elapse before the animation is actually ready (Babel compile + React // mount + fonts.ready). That elapsed time = exact trim offset. const T0 = Date.now(); const page = await recordCtx.newPage(); await page.goto(url, { waitUntil: 'load', timeout: 60000 }); // Wait for animation ready signal. Stage component (animations.jsx) sets // window.__ready = true on its first rAF after mount + fonts.ready. // Fallback: if HTML doesn't set __ready within READY_TIMEOUT, use fontwait. let animationStartSec; const hasReady = await page.waitForFunction( () => window.__ready === true, { timeout: READY_TIMEOUT * 1000 }, ).then(() => true).catch(() => false); if (hasReady) { // 第二道防线：主动把动画 time 归零——对付 HTML 不严格遵守 starter tick 模板 // 的情况（例如 lastTick 用 performance.now() 导致字体加载时间被算进首帧 dt） // 详见 references/animation-pitfalls.md §12 const seekCorrected = await page.evaluate(() => { if (typeof window.__seek === 'function') { window.__seek(0); return true; } return false; }); if (seekCorrected) { // 等两个 rAF 让 seek 生效并渲染出 t=0 的画面 await page.evaluate(() => new Promise(r => requestAnimationFrame(() => requestAnimationFrame(r)))); } animationStartSec = (Date.now() - T0) / 1000; console.log(`▸ Ready at ${animationStartSec.toFixed(2)}s (from window.__ready${seekCorrected ? ' + __seek(0) correction' : ''})`); } else { await page.waitForTimeout(FONT_WAIT * 1000); animationStartSec = (Date.now() - T0) / 1000; // Fallback offset is unreliable: animation may have started in raf loop // already, so trim could land mid-cycle. Add 0.5s safety margin (see // animation-pitfalls.md §13). Loud warning so user knows to fix the HTML. console.log(''); console.log(` ⚠️ WARNING: window.__ready signal not detected within ${READY_TIMEOUT}s`); console.log(` Recording will use fallback trim of ${animationStartSec.toFixed(2)}s + 0.5s safety margin.`); console.log(` This is UNRELIABLE — your video may start mid-animation or skip frames.`); console.log(''); console.log(` FIX: in your HTML's animation tick (or rAF first frame), add:`); console.log(` window.__ready = true;`); console.log(` animations.jsx-based HTML does this automatically. If you wrote your`); console.log(` own Stage, see references/animation-pitfalls.md §12 for the pattern.`); console.log(''); } // Now let the animation play out its full duration await page.waitForTimeout(DURATION * 1000 + 300); await page.close(); await recordCtx.close(); await browser.close(); const webmFiles = fs.readdirSync(TMP_DIR).filter(f => f.endsWith('.webm')); if (webmFiles.length === 0) { console.error('✗ No webm produced'); process.exit(1); } const webmPath = path.join(TMP_DIR, webmFiles[0]); console.log(`▸ WebM: ${(fs.statSync(webmPath).size / 1024 / 1024).toFixed(1)} MB`); // Resolve final trim offset: // - manual --trim=X → use X (explicit user override) // - hasReady → animationStartSec + 0.05s (Babel-commit nudge) // - fallback (no __ready) → animationStartSec + 0.5s safety margin (raf // loop may have started running already; without // this we'd capture mid-cycle frames) const resolvedTrim = TRIM_OVERRIDE !== null ? parseFloat(TRIM_OVERRIDE) : animationStartSec + (hasReady ? 0.05 : 0.5); console.log(`▸ ffmpeg: trim=${resolvedTrim.toFixed(2)}s${TRIM_OVERRIDE !== null ? ' (manual)' : ' (auto)'}, encode H.264…`); const ffmpeg = spawnSync('ffmpeg', [ '-y', '-ss', String(resolvedTrim), '-i', webmPath, '-t', String(DURATION), '-c:v', 'libx264', '-pix_fmt', 'yuv420p', '-crf', '18', '-preset', 'medium', '-movflags', '+faststart', MP4_OUT, ], { stdio: ['ignore', 'ignore', 'pipe'] }); if (ffmpeg.status !== 0) { console.error('✗ ffmpeg failed:\n' + ffmpeg.stderr.toString().slice(-2000)); process.exit(1); } fs.rmSync(TMP_DIR, { recursive: true, force: true }); const mp4Size = (fs.statSync(MP4_OUT).size / 1024 / 1024).toFixed(1); console.log(`✓ Done: ${MP4_OUT} (${mp4Size} MB)`); })(); -
sfx-cues.sh 1.6 KB
#!/bin/bash # sfx-cues.sh — 按cue表给无声视频打SFX点（B00阶跃b-roll实战沉淀，2026-07-17） # # 用法：bash sfx-cues.sh <无声视频.mp4> <cue表.tsv> <输出.mp4> [--dur=秒] # # cue表格式（TSV，#开头为注释）： # 秒数<TAB>sfx相对路径（相对assets/sfx/）<TAB>音量dB # 例：63.0 impact/brand-stamp.mp3 -13 # # 音量基准（轻SFX垫口播下）：whoosh类-16 / tick类-15 / impact类-12；纯动画成品可整体+4dB # cue密度参考 audio-design-rules.md 配方（b-roll垫底≈1个/9s，只打结构性节点） set -e SFX_DIR="$(cd "$(dirname "$0")/../assets/sfx" && pwd)" IN="${1:?用法: bash sfx-cues.sh in.mp4 cues.tsv out.mp4 [--dur=210]}" TABLE="${2:?缺cue表}" OUT="${3:?缺输出路径}" DUR="" for a in "$@"; do case "$a" in --dur=*) DUR="${a#*=}";; esac; done [ -z "$DUR" ] && DUR=$(ffprobe -v error -show_entries format=duration -of csv=p=0 "$IN" | cut -d. -f1) INPUTS=(-i "$IN") FILTER=""; MIX=""; i=1 while IFS=$'\t' read -r t f db; do [ -z "$t" ] && continue case "$t" in \#*) continue;; esac [ ! -f "$SFX_DIR/$f" ] && { echo "✗ SFX不存在: $f"; exit 1; } INPUTS+=(-i "$SFX_DIR/$f") ms=$(python3 -c "print(int(float('$t')*1000))") FILTER+="[$i:a]adelay=${ms}:all=1,volume=${db}dB[s$i];" MIX+="[s$i]" i=$((i+1)) done < "$TABLE" N=$((i-1)) [ "$N" = "0" ] && { echo "✗ cue表为空"; exit 1; } ffmpeg -y -loglevel error "${INPUTS[@]}" \ -filter_complex "${FILTER}${MIX}amix=inputs=${N}:normalize=0,apad=whole_dur=${DUR}[aout]" \ -map 0:v -map "[aout]" -c:v copy -c:a aac -b:a 192k -shortest "$OUT" echo "✓ ${N}个cue → $OUT" -
verify-video.sh 4.9 KB
#!/bin/bash # verify-video.sh — 渲染产物侧硬校验（PASS/FAIL，不靠agent目测） # # 检查项：分辨率/fps、时长误差、audio stream存在性、首尾黑帧、LUFS响度、体积 # 合成侧的校验（lint/layout/motion/contrast）由 hyperframes check 负责，此脚本只管产物。 # # Usage: # bash verify-video.sh video.mp4 [--duration=10] [--fps=60] [--width=1920] [--height=1080] # [--no-audio] # 明确无音频的中间产物，跳过audio+响度检查 # [--allow-black-open] # 片头刻意黑场开场时跳过片头黑帧检查 # # Exit code: 0 = 全PASS；1 = 有FAIL set -u FILE="${1:-}" if [ -z "$FILE" ] || [ ! -f "$FILE" ]; then echo "Usage: bash verify-video.sh video.mp4 [--duration=N] [--fps=N] [--width=N] [--height=N] [--no-audio] [--allow-black-open]" exit 1 fi shift || true EXP_DURATION=""; EXP_FPS=""; EXP_W=""; EXP_H=""; NO_AUDIO=0; ALLOW_BLACK_OPEN=0 for a in "$@"; do case "$a" in --duration=*) EXP_DURATION="${a#*=}" ;; --fps=*) EXP_FPS="${a#*=}" ;; --width=*) EXP_W="${a#*=}" ;; --height=*) EXP_H="${a#*=}" ;; --no-audio) NO_AUDIO=1 ;; --allow-black-open) ALLOW_BLACK_OPEN=1 ;; esac done FAILS=0 pass() { echo " ✓ PASS $1"; } fail() { echo " ✗ FAIL $1"; FAILS=$((FAILS+1)); } warn() { echo " ⚠ WARN $1"; } echo "▸ verify-video: $FILE" # ---------- 基本流信息 ---------- INFO=$(ffprobe -v error -select_streams v:0 -show_entries stream=width,height,avg_frame_rate -show_entries format=duration,size -of default=noprint_wrappers=1 "$FILE" 2>/dev/null) W=$(echo "$INFO" | grep '^width=' | cut -d= -f2) H=$(echo "$INFO" | grep '^height=' | cut -d= -f2) FPS_RAW=$(echo "$INFO" | grep '^avg_frame_rate=' | cut -d= -f2) DUR=$(echo "$INFO" | grep '^duration=' | cut -d= -f2) SIZE=$(echo "$INFO" | grep '^size=' | cut -d= -f2) FPS=$(python3 -c "print(round(eval('${FPS_RAW:-0}' if '${FPS_RAW:-0}'!='0/0' else '0'),2))" 2>/dev/null || echo "?") [ -z "$W" ] && { fail "无法读取视频流（文件损坏或非视频）"; echo "✗ 1项FAIL"; exit 1; } echo " info: ${W}x${H} · ${FPS}fps · ${DUR%.*}s · $((SIZE/1024))KB" # ---------- 分辨率 / fps ---------- if [ -n "$EXP_W" ]; then [ "$W" = "$EXP_W" ] && [ "$H" = "$EXP_H" ] && pass "分辨率 ${W}x${H}" || fail "分辨率 ${W}x${H}，期望 ${EXP_W}x${EXP_H}" fi if [ -n "$EXP_FPS" ]; then python3 -c "exit(0 if abs($FPS-$EXP_FPS)<=0.5 else 1)" 2>/dev/null && pass "帧率 ${FPS}fps" || fail "帧率 ${FPS}fps，期望 ${EXP_FPS}fps" fi # ---------- 时长误差（±2% 或 ±0.2s 取大者）---------- if [ -n "$EXP_DURATION" ]; then python3 -c " d=float('$DUR'); e=float('$EXP_DURATION') tol=max(e*0.02,0.2) exit(0 if abs(d-e)<=tol else 1)" 2>/dev/null && pass "时长 ${DUR%.*}s（期望 ${EXP_DURATION}s）" || fail "时长 ${DUR}s，期望 ${EXP_DURATION}s（容差2%）" fi # ---------- audio stream ---------- HAS_AUDIO=$(ffprobe -v error -select_streams a -show_entries stream=codec_type -of csv=p=0 "$FILE" 2>/dev/null | head -1) if [ "$NO_AUDIO" = "1" ]; then [ -z "$HAS_AUDIO" ] && pass "无音轨（--no-audio 中间产物）" || warn "声明--no-audio但存在音轨" else if [ -n "$HAS_AUDIO" ]; then pass "audio stream 存在" # ---------- LUFS 响度（成品参考 -14 LUFS ±4）---------- LUFS=$(ffmpeg -i "$FILE" -af loudnorm=print_format=summary -f null - 2>&1 | grep 'Input Integrated' | grep -oE '\-?[0-9]+\.?[0-9]*') if [ -n "$LUFS" ]; then python3 -c "exit(0 if -18<=float('$LUFS')<=-10 else 1)" 2>/dev/null \ && pass "响度 ${LUFS} LUFS（目标区间 -18~-10）" \ || warn "响度 ${LUFS} LUFS 偏离 -14±4 区间，检查混音增益" fi else fail "无 audio stream——skill铁律：动画默认交付形态是带SFX+BGM的MP4，无声=半成品" fi fi # ---------- 首尾黑帧 ---------- BLACK=$(ffmpeg -i "$FILE" -vf "blackdetect=d=0.1:pix_th=0.10" -an -f null - 2>&1 | grep -oE 'black_start:[0-9.]+ black_end:[0-9.]+' ) if [ -n "$BLACK" ]; then HEAD_BLACK=$(echo "$BLACK" | awk -F'[: ]' '$2<0.3{print}' | head -1) TOTAL=${DUR%.*} TAIL_BLACK=$(echo "$BLACK" | awk -F'[: ]' -v t="$TOTAL" '$4>t-0.3{print}' | head -1) if [ -n "$HEAD_BLACK" ] && [ "$ALLOW_BLACK_OPEN" = "0" ]; then fail "片头黑帧（$HEAD_BLACK）——录制起点偏移的典型症状；刻意黑场开场用 --allow-black-open" else [ -n "$HEAD_BLACK" ] && pass "片头黑场（--allow-black-open 已声明）" fi [ -n "$TAIL_BLACK" ] && fail "片尾黑帧（$TAIL_BLACK)——loop回跳或时长超录的典型症状" [ -z "$HEAD_BLACK" ] && [ -z "$TAIL_BLACK" ] && warn "片中存在黑帧段（如是刻意转场可忽略）：$(echo "$BLACK" | head -2 | tr '\n' ' ')" else pass "无黑帧" fi # ---------- 汇总 ---------- echo "" if [ "$FAILS" = "0" ]; then echo "◇ verify-video: 全部PASS" exit 0 else echo "✗ verify-video: ${FAILS}项FAIL" exit 1 fi -
verify.py 5.3 KB
#!/usr/bin/env python3 """ verify.py — Playwright封装，用于验证claude-design产出的HTML Usage: python verify.py path/to/design.html # 基础：打开+截图+抓控制台错误 python verify.py design.html --viewports 1920x1080,375x667 # 多viewport python verify.py deck.html --slides 10 # 幻灯片逐页截（前10张） python verify.py design.html --output ./screenshots/ # 输出目录 python verify.py design.html --show # 非headless，打开真实浏览器 依赖： pip install playwright playwright install chromium """ import argparse import sys import os import time from pathlib import Path def parse_viewport(s): w, h = s.split('x') return {'width': int(w), 'height': int(h)} def verify_html(html_path, viewports=None, slides=0, output_dir=None, show=False, wait=2000): try: from playwright.sync_api import sync_playwright except ImportError: print("ERROR: playwright未安装。") print("运行: pip install playwright && playwright install chromium") sys.exit(1) html_path = Path(html_path).resolve() if not html_path.exists(): print(f"ERROR: 文件不存在: {html_path}") sys.exit(1) if output_dir is None: output_dir = html_path.parent / 'screenshots' output_dir = Path(output_dir) output_dir.mkdir(parents=True, exist_ok=True) file_url = html_path.as_uri() stem = html_path.stem if viewports is None: viewports = [{'width': 1440, 'height': 900}] console_errors = [] page_errors = [] with sync_playwright() as p: browser = p.chromium.launch(headless=not show) for viewport in viewports: context = browser.new_context(viewport=viewport, device_scale_factor=2) page = context.new_page() page.on("console", lambda msg: console_errors.append(f"[{msg.type}] {msg.text}") if msg.type in ("error", "warning") else None) page.on("pageerror", lambda err: page_errors.append(str(err))) print(f"\n→ 打开 {file_url} @ {viewport['width']}x{viewport['height']}") page.goto(file_url, wait_until='networkidle') page.wait_for_timeout(wait) if slides > 0: for i in range(slides): screenshot_path = output_dir / f"{stem}-slide-{str(i + 1).zfill(2)}.png" page.screenshot(path=str(screenshot_path), full_page=False) print(f" ✓ slide {i+1} → {screenshot_path.name}") if i < slides - 1: page.keyboard.press('ArrowRight') page.wait_for_timeout(500) else: suffix = f"-{viewport['width']}x{viewport['height']}" if len(viewports) > 1 else "" screenshot_path = output_dir / f"{stem}{suffix}.png" page.screenshot(path=str(screenshot_path), full_page=False) print(f" ✓ 截图 → {screenshot_path.name}") full_path = output_dir / f"{stem}{suffix}-full.png" page.screenshot(path=str(full_path), full_page=True) print(f" ✓ 完整页 → {full_path.name}") if show: print(" (浏览器窗口保持打开，按Enter关闭...)") input() context.close() browser.close() print("\n" + "=" * 50) print("验证报告") print("=" * 50) if page_errors: print(f"\n❌ Page Errors ({len(page_errors)}):") for e in page_errors: print(f" - {e}") else: print("\n✅ 无JavaScript错误") if console_errors: print(f"\n⚠️ Console Errors/Warnings ({len(console_errors)}):") for e in console_errors[:20]: print(f" - {e}") if len(console_errors) > 20: print(f" ... 还有{len(console_errors) - 20}条") else: print("✅ Console干净") print(f"\n📸 截图保存至: {output_dir}") return 0 if not page_errors else 1 def main(): parser = argparse.ArgumentParser( description="Verify HTML design outputs with Playwright", formatter_class=argparse.RawDescriptionHelpFormatter, ) parser.add_argument("html_path", help="HTML file path") parser.add_argument("--viewports", default="1440x900", help="逗号分隔的viewport列表，格式 WxH（默认 1440x900）") parser.add_argument("--slides", type=int, default=0, help="幻灯片模式：截取前N张（需要HTML支持ArrowRight翻页）") parser.add_argument("--output", default=None, help="输出目录（默认HTML所在目录的screenshots/）") parser.add_argument("--show", action="store_true", help="非headless，打开真实浏览器窗口") parser.add_argument("--wait", type=int, default=2000, help="打开页面后等待的毫秒数（默认2000）") args = parser.parse_args() viewports = [parse_viewport(v) for v in args.viewports.split(",")] return verify_html( html_path=args.html_path, viewports=viewports, slides=args.slides, output_dir=args.output, show=args.show, wait=args.wait, ) if __name__ == "__main__": sys.exit(main())
-
-
.env.example 463 B · in bundle
-
.gitignore 844 B · in bundle
-
LICENSE 1.1 KB · in bundle
-
package-lock.json 27.9 KB
{ "name": "huashu-design", "lockfileVersion": 3, "requires": true, "packages": { "": { "dependencies": { "pdf-lib": "^1.17.1", "playwright": "^1.59.1", "pptxgenjs": "^4.0.1", "sharp": "^0.34.5" } }, "node_modules/@emnapi/runtime": { "version": "1.10.0", "resolved": "https://registry.npmjs.org/@emnapi/runtime/-/runtime-1.10.0.tgz", "integrity": "sha512-ewvYlk86xUoGI0zQRNq/mC+16R1QeDlKQy21Ki3oSYXNgLb45GV1P6A0M+/s6nyCuNDqe5VpaY84BzXGwVbwFA==", "license": "MIT", "optional": true, "dependencies": { "tslib": "^2.4.0" } }, "node_modules/@emnapi/runtime/node_modules/tslib": { "version": "2.8.1", "resolved": "https://registry.npmjs.org/tslib/-/tslib-2.8.1.tgz", "integrity": "sha512-oJFu94HQb+KVduSUQL7wnpmqnfmLsOA/nAh6b6EH0wCEoK0/mPeXU6c3wKDV83MkOuHPRHtSXKKU99IBazS/2w==", "license": "0BSD", "optional": true }, "node_modules/@img/colour": { "version": "1.1.0", "resolved": "https://registry.npmjs.org/@img/colour/-/colour-1.1.0.tgz", "integrity": "sha512-Td76q7j57o/tLVdgS746cYARfSyxk8iEfRxewL9h4OMzYhbW4TAcppl0mT4eyqXddh6L/jwoM75mo7ixa/pCeQ==", "license": "MIT", "engines": { "node": ">=18" } }, "node_modules/@img/sharp-darwin-arm64": { "version": "0.34.5", "resolved": "https://registry.npmjs.org/@img/sharp-darwin-arm64/-/sharp-darwin-arm64-0.34.5.tgz", "integrity": "sha512-imtQ3WMJXbMY4fxb/Ndp6HBTNVtWCUI0WdobyheGf5+ad6xX8VIDO8u2xE4qc/fr08CKG/7dDseFtn6M6g/r3w==", "cpu": [ "arm64" ], "license": "Apache-2.0", "optional": true, "os": [ "darwin" ], "engines": { "node": "^18.17.0 || ^20.3.0 || >=21.0.0" }, "funding": { "url": "https://opencollective.com/libvips" }, "optionalDependencies": { "@img/sharp-libvips-darwin-arm64": "1.2.4" } }, "node_modules/@img/sharp-darwin-x64": { "version": "0.34.5", "resolved": "https://registry.npmjs.org/@img/sharp-darwin-x64/-/sharp-darwin-x64-0.34.5.tgz", "integrity": "sha512-YNEFAF/4KQ/PeW0N+r+aVVsoIY0/qxxikF2SWdp+NRkmMB7y9LBZAVqQ4yhGCm/H3H270OSykqmQMKLBhBJDEw==", "cpu": [ "x64" ], "license": "Apache-2.0", "optional": true, "os": [ "darwin" ], "engines": { "node": "^18.17.0 || ^20.3.0 || >=21.0.0" }, "funding": { "url": "https://opencollective.com/libvips" }, "optionalDependencies": { "@img/sharp-libvips-darwin-x64": "1.2.4" } }, "node_modules/@img/sharp-libvips-darwin-arm64": { "version": "1.2.4", "resolved": "https://registry.npmjs.org/@img/sharp-libvips-darwin-arm64/-/sharp-libvips-darwin-arm64-1.2.4.tgz", "integrity": "sha512-zqjjo7RatFfFoP0MkQ51jfuFZBnVE2pRiaydKJ1G/rHZvnsrHAOcQALIi9sA5co5xenQdTugCvtb1cuf78Vf4g==", "cpu": [ "arm64" ], "license": "LGPL-3.0-or-later", "optional": true, "os": [ "darwin" ], "funding": { "url": "https://opencollective.com/libvips" } }, "node_modules/@img/sharp-libvips-darwin-x64": { "version": "1.2.4", "resolved": "https://registry.npmjs.org/@img/sharp-libvips-darwin-x64/-/sharp-libvips-darwin-x64-1.2.4.tgz", "integrity": "sha512-1IOd5xfVhlGwX+zXv2N93k0yMONvUlANylbJw1eTah8K/Jtpi15KC+WSiaX/nBmbm2HxRM1gZ0nSdjSsrZbGKg==", "cpu": [ "x64" ], "license": "LGPL-3.0-or-later", "optional": true, "os": [ "darwin" ], "funding": { "url": "https://opencollective.com/libvips" } }, "node_modules/@img/sharp-libvips-linux-arm": { "version": "1.2.4", "resolved": "https://registry.npmjs.org/@img/sharp-libvips-linux-arm/-/sharp-libvips-linux-arm-1.2.4.tgz", "integrity": "sha512-bFI7xcKFELdiNCVov8e44Ia4u2byA+l3XtsAj+Q8tfCwO6BQ8iDojYdvoPMqsKDkuoOo+X6HZA0s0q11ANMQ8A==", "cpu": [ "arm" ], "libc": [ "glibc" ], "license": "LGPL-3.0-or-later", "optional": true, "os": [ "linux" ], "funding": { "url": "https://opencollective.com/libvips" } }, "node_modules/@img/sharp-libvips-linux-arm64": { "version": "1.2.4", "resolved": "https://registry.npmjs.org/@img/sharp-libvips-linux-arm64/-/sharp-libvips-linux-arm64-1.2.4.tgz", "integrity": "sha512-excjX8DfsIcJ10x1Kzr4RcWe1edC9PquDRRPx3YVCvQv+U5p7Yin2s32ftzikXojb1PIFc/9Mt28/y+iRklkrw==", "cpu": [ "arm64" ], "libc": [ "glibc" ], "license": "LGPL-3.0-or-later", "optional": true, "os": [ "linux" ], "funding": { "url": "https://opencollective.com/libvips" } }, "node_modules/@img/sharp-libvips-linux-ppc64": { "version": "1.2.4", "resolved": "https://registry.npmjs.org/@img/sharp-libvips-linux-ppc64/-/sharp-libvips-linux-ppc64-1.2.4.tgz", "integrity": "sha512-FMuvGijLDYG6lW+b/UvyilUWu5Ayu+3r2d1S8notiGCIyYU/76eig1UfMmkZ7vwgOrzKzlQbFSuQfgm7GYUPpA==", "cpu": [ "ppc64" ], "libc": [ "glibc" ], "license": "LGPL-3.0-or-later", "optional": true, "os": [ "linux" ], "funding": { "url": "https://opencollective.com/libvips" } }, "node_modules/@img/sharp-libvips-linux-riscv64": { "version": "1.2.4", "resolved": "https://registry.npmjs.org/@img/sharp-libvips-linux-riscv64/-/sharp-libvips-linux-riscv64-1.2.4.tgz", "integrity": "sha512-oVDbcR4zUC0ce82teubSm+x6ETixtKZBh/qbREIOcI3cULzDyb18Sr/Wcyx7NRQeQzOiHTNbZFF1UwPS2scyGA==", "cpu": [ "riscv64" ], "libc": [ "glibc" ], "license": "LGPL-3.0-or-later", "optional": true, "os": [ "linux" ], "funding": { "url": "https://opencollective.com/libvips" } }, "node_modules/@img/sharp-libvips-linux-s390x": { "version": "1.2.4", "resolved": "https://registry.npmjs.org/@img/sharp-libvips-linux-s390x/-/sharp-libvips-linux-s390x-1.2.4.tgz", "integrity": "sha512-qmp9VrzgPgMoGZyPvrQHqk02uyjA0/QrTO26Tqk6l4ZV0MPWIW6LTkqOIov+J1yEu7MbFQaDpwdwJKhbJvuRxQ==", "cpu": [ "s390x" ], "libc": [ "glibc" ], "license": "LGPL-3.0-or-later", "optional": true, "os": [ "linux" ], "funding": { "url": "https://opencollective.com/libvips" } }, "node_modules/@img/sharp-libvips-linux-x64": { "version": "1.2.4", "resolved": "https://registry.npmjs.org/@img/sharp-libvips-linux-x64/-/sharp-libvips-linux-x64-1.2.4.tgz", "integrity": "sha512-tJxiiLsmHc9Ax1bz3oaOYBURTXGIRDODBqhveVHonrHJ9/+k89qbLl0bcJns+e4t4rvaNBxaEZsFtSfAdquPrw==", "cpu": [ "x64" ], "libc": [ "glibc" ], "license": "LGPL-3.0-or-later", "optional": true, "os": [ "linux" ], "funding": { "url": "https://opencollective.com/libvips" } }, "node_modules/@img/sharp-libvips-linuxmusl-arm64": { "version": "1.2.4", "resolved": "https://registry.npmjs.org/@img/sharp-libvips-linuxmusl-arm64/-/sharp-libvips-linuxmusl-arm64-1.2.4.tgz", "integrity": "sha512-FVQHuwx1IIuNow9QAbYUzJ+En8KcVm9Lk5+uGUQJHaZmMECZmOlix9HnH7n1TRkXMS0pGxIJokIVB9SuqZGGXw==", "cpu": [ "arm64" ], "libc": [ "musl" ], "license": "LGPL-3.0-or-later", "optional": true, "os": [ "linux" ], "funding": { "url": "https://opencollective.com/libvips" } }, "node_modules/@img/sharp-libvips-linuxmusl-x64": { "version": "1.2.4", "resolved": "https://registry.npmjs.org/@img/sharp-libvips-linuxmusl-x64/-/sharp-libvips-linuxmusl-x64-1.2.4.tgz", "integrity": "sha512-+LpyBk7L44ZIXwz/VYfglaX/okxezESc6UxDSoyo2Ks6Jxc4Y7sGjpgU9s4PMgqgjj1gZCylTieNamqA1MF7Dg==", "cpu": [ "x64" ], "libc": [ "musl" ], "license": "LGPL-3.0-or-later", "optional": true, "os": [ "linux" ], "funding": { "url": "https://opencollective.com/libvips" } }, "node_modules/@img/sharp-linux-arm": { "version": "0.34.5", "resolved": "https://registry.npmjs.org/@img/sharp-linux-arm/-/sharp-linux-arm-0.34.5.tgz", "integrity": "sha512-9dLqsvwtg1uuXBGZKsxem9595+ujv0sJ6Vi8wcTANSFpwV/GONat5eCkzQo/1O6zRIkh0m/8+5BjrRr7jDUSZw==", "cpu": [ "arm" ], "libc": [ "glibc" ], "license": "Apache-2.0", "optional": true, "os": [ "linux" ], "engines": { "node": "^18.17.0 || ^20.3.0 || >=21.0.0" }, "funding": { "url": "https://opencollective.com/libvips" }, "optionalDependencies": { "@img/sharp-libvips-linux-arm": "1.2.4" } }, "node_modules/@img/sharp-linux-arm64": { "version": "0.34.5", "resolved": "https://registry.npmjs.org/@img/sharp-linux-arm64/-/sharp-linux-arm64-0.34.5.tgz", "integrity": "sha512-bKQzaJRY/bkPOXyKx5EVup7qkaojECG6NLYswgktOZjaXecSAeCWiZwwiFf3/Y+O1HrauiE3FVsGxFg8c24rZg==", "cpu": [ "arm64" ], "libc": [ "glibc" ], "license": "Apache-2.0", "optional": true, "os": [ "linux" ], "engines": { "node": "^18.17.0 || ^20.3.0 || >=21.0.0" }, "funding": { "url": "https://opencollective.com/libvips" }, "optionalDependencies": { "@img/sharp-libvips-linux-arm64": "1.2.4" } }, "node_modules/@img/sharp-linux-ppc64": { "version": "0.34.5", "resolved": "https://registry.npmjs.org/@img/sharp-linux-ppc64/-/sharp-linux-ppc64-0.34.5.tgz", "integrity": "sha512-7zznwNaqW6YtsfrGGDA6BRkISKAAE1Jo0QdpNYXNMHu2+0dTrPflTLNkpc8l7MUP5M16ZJcUvysVWWrMefZquA==", "cpu": [ "ppc64" ], "libc": [ "glibc" ], "license": "Apache-2.0", "optional": true, "os": [ "linux" ], "engines": { "node": "^18.17.0 || ^20.3.0 || >=21.0.0" }, "funding": { "url": "https://opencollective.com/libvips" }, "optionalDependencies": { "@img/sharp-libvips-linux-ppc64": "1.2.4" } }, "node_modules/@img/sharp-linux-riscv64": { "version": "0.34.5", "resolved": "https://registry.npmjs.org/@img/sharp-linux-riscv64/-/sharp-linux-riscv64-0.34.5.tgz", "integrity": "sha512-51gJuLPTKa7piYPaVs8GmByo7/U7/7TZOq+cnXJIHZKavIRHAP77e3N2HEl3dgiqdD/w0yUfiJnII77PuDDFdw==", "cpu": [ "riscv64" ], "libc": [ "glibc" ], "license": "Apache-2.0", "optional": true, "os": [ "linux" ], "engines": { "node": "^18.17.0 || ^20.3.0 || >=21.0.0" }, "funding": { "url": "https://opencollective.com/libvips" }, "optionalDependencies": { "@img/sharp-libvips-linux-riscv64": "1.2.4" } }, "node_modules/@img/sharp-linux-s390x": { "version": "0.34.5", "resolved": "https://registry.npmjs.org/@img/sharp-linux-s390x/-/sharp-linux-s390x-0.34.5.tgz", "integrity": "sha512-nQtCk0PdKfho3eC5MrbQoigJ2gd1CgddUMkabUj+rBevs8tZ2cULOx46E7oyX+04WGfABgIwmMC0VqieTiR4jg==", "cpu": [ "s390x" ], "libc": [ "glibc" ], "license": "Apache-2.0", "optional": true, "os": [ "linux" ], "engines": { "node": "^18.17.0 || ^20.3.0 || >=21.0.0" }, "funding": { "url": "https://opencollective.com/libvips" }, "optionalDependencies": { "@img/sharp-libvips-linux-s390x": "1.2.4" } }, "node_modules/@img/sharp-linux-x64": { "version": "0.34.5", "resolved": "https://registry.npmjs.org/@img/sharp-linux-x64/-/sharp-linux-x64-0.34.5.tgz", "integrity": "sha512-MEzd8HPKxVxVenwAa+JRPwEC7QFjoPWuS5NZnBt6B3pu7EG2Ge0id1oLHZpPJdn3OQK+BQDiw9zStiHBTJQQQQ==", "cpu": [ "x64" ], "libc": [ "glibc" ], "license": "Apache-2.0", "optional": true, "os": [ "linux" ], "engines": { "node": "^18.17.0 || ^20.3.0 || >=21.0.0" }, "funding": { "url": "https://opencollective.com/libvips" }, "optionalDependencies": { "@img/sharp-libvips-linux-x64": "1.2.4" } }, "node_modules/@img/sharp-linuxmusl-arm64": { "version": "0.34.5", "resolved": "https://registry.npmjs.org/@img/sharp-linuxmusl-arm64/-/sharp-linuxmusl-arm64-0.34.5.tgz", "integrity": "sha512-fprJR6GtRsMt6Kyfq44IsChVZeGN97gTD331weR1ex1c1rypDEABN6Tm2xa1wE6lYb5DdEnk03NZPqA7Id21yg==", "cpu": [ "arm64" ], "libc": [ "musl" ], "license": "Apache-2.0", "optional": true, "os": [ "linux" ], "engines": { "node": "^18.17.0 || ^20.3.0 || >=21.0.0" }, "funding": { "url": "https://opencollective.com/libvips" }, "optionalDependencies": { "@img/sharp-libvips-linuxmusl-arm64": "1.2.4" } }, "node_modules/@img/sharp-linuxmusl-x64": { "version": "0.34.5", "resolved": "https://registry.npmjs.org/@img/sharp-linuxmusl-x64/-/sharp-linuxmusl-x64-0.34.5.tgz", "integrity": "sha512-Jg8wNT1MUzIvhBFxViqrEhWDGzqymo3sV7z7ZsaWbZNDLXRJZoRGrjulp60YYtV4wfY8VIKcWidjojlLcWrd8Q==", "cpu": [ "x64" ], "libc": [ "musl" ], "license": "Apache-2.0", "optional": true, "os": [ "linux" ], "engines": { "node": "^18.17.0 || ^20.3.0 || >=21.0.0" }, "funding": { "url": "https://opencollective.com/libvips" }, "optionalDependencies": { "@img/sharp-libvips-linuxmusl-x64": "1.2.4" } }, "node_modules/@img/sharp-wasm32": { "version": "0.34.5", "resolved": "https://registry.npmjs.org/@img/sharp-wasm32/-/sharp-wasm32-0.34.5.tgz", "integrity": "sha512-OdWTEiVkY2PHwqkbBI8frFxQQFekHaSSkUIJkwzclWZe64O1X4UlUjqqqLaPbUpMOQk6FBu/HtlGXNblIs0huw==", "cpu": [ "wasm32" ], "license": "Apache-2.0 AND LGPL-3.0-or-later AND MIT", "optional": true, "dependencies": { "@emnapi/runtime": "^1.7.0" }, "engines": { "node": "^18.17.0 || ^20.3.0 || >=21.0.0" }, "funding": { "url": "https://opencollective.com/libvips" } }, "node_modules/@img/sharp-win32-arm64": { "version": "0.34.5", "resolved": "https://registry.npmjs.org/@img/sharp-win32-arm64/-/sharp-win32-arm64-0.34.5.tgz", "integrity": "sha512-WQ3AgWCWYSb2yt+IG8mnC6Jdk9Whs7O0gxphblsLvdhSpSTtmu69ZG1Gkb6NuvxsNACwiPV6cNSZNzt0KPsw7g==", "cpu": [ "arm64" ], "license": "Apache-2.0 AND LGPL-3.0-or-later", "optional": true, "os": [ "win32" ], "engines": { "node": "^18.17.0 || ^20.3.0 || >=21.0.0" }, "funding": { "url": "https://opencollective.com/libvips" } }, "node_modules/@img/sharp-win32-ia32": { "version": "0.34.5", "resolved": "https://registry.npmjs.org/@img/sharp-win32-ia32/-/sharp-win32-ia32-0.34.5.tgz", "integrity": "sha512-FV9m/7NmeCmSHDD5j4+4pNI8Cp3aW+JvLoXcTUo0IqyjSfAZJ8dIUmijx1qaJsIiU+Hosw6xM5KijAWRJCSgNg==", "cpu": [ "ia32" ], "license": "Apache-2.0 AND LGPL-3.0-or-later", "optional": true, "os": [ "win32" ], "engines": { "node": "^18.17.0 || ^20.3.0 || >=21.0.0" }, "funding": { "url": "https://opencollective.com/libvips" } }, "node_modules/@img/sharp-win32-x64": { "version": "0.34.5", "resolved": "https://registry.npmjs.org/@img/sharp-win32-x64/-/sharp-win32-x64-0.34.5.tgz", "integrity": "sha512-+29YMsqY2/9eFEiW93eqWnuLcWcufowXewwSNIT6UwZdUUCrM3oFjMWH/Z6/TMmb4hlFenmfAVbpWeup2jryCw==", "cpu": [ "x64" ], "license": "Apache-2.0 AND LGPL-3.0-or-later", "optional": true, "os": [ "win32" ], "engines": { "node": "^18.17.0 || ^20.3.0 || >=21.0.0" }, "funding": { "url": "https://opencollective.com/libvips" } }, "node_modules/@pdf-lib/standard-fonts": { "version": "1.0.0", "resolved": "https://registry.npmjs.org/@pdf-lib/standard-fonts/-/standard-fonts-1.0.0.tgz", "integrity": "sha512-hU30BK9IUN/su0Mn9VdlVKsWBS6GyhVfqjwl1FjZN4TxP6cCw0jP2w7V3Hf5uX7M0AZJ16vey9yE0ny7Sa59ZA==", "license": "MIT", "dependencies": { "pako": "^1.0.6" } }, "node_modules/@pdf-lib/upng": { "version": "1.0.1", "resolved": "https://registry.npmjs.org/@pdf-lib/upng/-/upng-1.0.1.tgz", "integrity": "sha512-dQK2FUMQtowVP00mtIksrlZhdFXQZPC+taih1q4CvPZ5vqdxR/LKBaFg0oAfzd1GlHZXXSPdQfzQnt+ViGvEIQ==", "license": "MIT", "dependencies": { "pako": "^1.0.10" } }, "node_modules/@types/node": { "version": "22.19.19", "resolved": "https://registry.npmjs.org/@types/node/-/node-22.19.19.tgz", "integrity": "sha512-dyh/xO2Fh5bYrfWaaqGrRQQGkNdmYw6AmaAUvYeUMNTWQtvb796ikLdmTchRmOlOiIJ1TDXfWgVx1QkUlQ6Hew==", "license": "MIT", "dependencies": { "undici-types": "~6.21.0" } }, "node_modules/core-util-is": { "version": "1.0.3", "resolved": "https://registry.npmjs.org/core-util-is/-/core-util-is-1.0.3.tgz", "integrity": "sha512-ZQBvi1DcpJ4GDqanjucZ2Hj3wEO5pZDS89BWbkcrvdxksJorwUDDZamX9ldFkp9aw2lmBDLgkObEA4DWNJ9FYQ==", "license": "MIT" }, "node_modules/detect-libc": { "version": "2.1.2", "resolved": "https://registry.npmjs.org/detect-libc/-/detect-libc-2.1.2.tgz", "integrity": "sha512-Btj2BOOO83o3WyH59e8MgXsxEQVcarkUOpEYrubB0urwnN10yQ364rsiByU11nZlqWYZm05i/of7io4mzihBtQ==", "license": "Apache-2.0", "engines": { "node": ">=8" } }, "node_modules/fsevents": { "version": "2.3.2", "resolved": "https://registry.npmjs.org/fsevents/-/fsevents-2.3.2.tgz", "integrity": "sha512-xiqMQR4xAeHTuB9uWm+fFRcIOgKBMiOBP+eXiyT7jsgVCq1bkVygt00oASowB7EdtpOHaaPgKt812P9ab+DDKA==", "hasInstallScript": true, "license": "MIT", "optional": true, "os": [ "darwin" ], "engines": { "node": "^8.16.0 || ^10.6.0 || >=11.0.0" } }, "node_modules/https": { "version": "1.0.0", "resolved": "https://registry.npmjs.org/https/-/https-1.0.0.tgz", "integrity": "sha512-4EC57ddXrkaF0x83Oj8sM6SLQHAWXw90Skqu2M4AEWENZ3F02dFJE/GARA8igO79tcgYqGrD7ae4f5L3um2lgg==", "license": "ISC" }, "node_modules/image-size": { "version": "1.2.1", "resolved": "https://registry.npmjs.org/image-size/-/image-size-1.2.1.tgz", "integrity": "sha512-rH+46sQJ2dlwfjfhCyNx5thzrv+dtmBIhPHk0zgRUukHzZ/kRueTJXoYYsclBaKcSMBWuGbOFXtioLpzTb5euw==", "license": "MIT", "dependencies": { "queue": "6.0.2" }, "bin": { "image-size": "bin/image-size.js" }, "engines": { "node": ">=16.x" } }, "node_modules/immediate": { "version": "3.0.6", "resolved": "https://registry.npmjs.org/immediate/-/immediate-3.0.6.tgz", "integrity": "sha512-XXOFtyqDjNDAQxVfYxuF7g9Il/IbWmmlQg2MYKOH8ExIT1qg6xc4zyS3HaEEATgs1btfzxq15ciUiY7gjSXRGQ==", "license": "MIT" }, "node_modules/inherits": { "version": "2.0.4", "resolved": "https://registry.npmjs.org/inherits/-/inherits-2.0.4.tgz", "integrity": "sha512-k/vGaX4/Yla3WzyMCvTQOXYeIHvqOKtnqBduzTHpzpQZzAskKMhZ2K+EnBiSM9zGSoIFeMpXKxa4dYeZIQqewQ==", "license": "ISC" }, "node_modules/isarray": { "version": "1.0.0", "resolved": "https://registry.npmjs.org/isarray/-/isarray-1.0.0.tgz", "integrity": "sha512-VLghIWNM6ELQzo7zwmcg0NmTVyWKYjvIeM83yjp0wRDTmUnrM678fQbcKBo6n2CJEF0szoG//ytg+TKla89ALQ==", "license": "MIT" }, "node_modules/jszip": { "version": "3.10.1", "resolved": "https://registry.npmjs.org/jszip/-/jszip-3.10.1.tgz", "integrity": "sha512-xXDvecyTpGLrqFrvkrUSoxxfJI5AH7U8zxxtVclpsUtMCq4JQ290LY8AW5c7Ggnr/Y/oK+bQMbqK2qmtk3pN4g==", "license": "(MIT OR GPL-3.0-or-later)", "dependencies": { "lie": "~3.3.0", "pako": "~1.0.2", "readable-stream": "~2.3.6", "setimmediate": "^1.0.5" } }, "node_modules/lie": { "version": "3.3.0", "resolved": "https://registry.npmjs.org/lie/-/lie-3.3.0.tgz", "integrity": "sha512-UaiMJzeWRlEujzAuw5LokY1L5ecNQYZKfmyZ9L7wDHb/p5etKaxXhohBcrw0EYby+G/NA52vRSN4N39dxHAIwQ==", "license": "MIT", "dependencies": { "immediate": "~3.0.5" } }, "node_modules/pako": { "version": "1.0.11", "resolved": "https://registry.npmjs.org/pako/-/pako-1.0.11.tgz", "integrity": "sha512-4hLB8Py4zZce5s4yd9XzopqwVv/yGNhV1Bl8NTmCq1763HeK2+EwVTv+leGeL13Dnh2wfbqowVPXCIO0z4taYw==", "license": "(MIT AND Zlib)" }, "node_modules/pdf-lib": { "version": "1.17.1", "resolved": "https://registry.npmjs.org/pdf-lib/-/pdf-lib-1.17.1.tgz", "integrity": "sha512-V/mpyJAoTsN4cnP31vc0wfNA1+p20evqqnap0KLoRUN0Yk/p3wN52DOEsL4oBFcLdb76hlpKPtzJIgo67j/XLw==", "license": "MIT", "dependencies": { "@pdf-lib/standard-fonts": "^1.0.0", "@pdf-lib/upng": "^1.0.1", "pako": "^1.0.11", "tslib": "^1.11.1" } }, "node_modules/playwright": { "version": "1.59.1", "resolved": "https://registry.npmjs.org/playwright/-/playwright-1.59.1.tgz", "integrity": "sha512-C8oWjPR3F81yljW9o5OxcWzfh6avkVwDD2VYdwIGqTkl+OGFISgypqzfu7dOe4QNLL2aqcWBmI3PMtLIK233lw==", "license": "Apache-2.0", "dependencies": { "playwright-core": "1.59.1" }, "bin": { "playwright": "cli.js" }, "engines": { "node": ">=18" }, "optionalDependencies": { "fsevents": "2.3.2" } }, "node_modules/playwright-core": { "version": "1.59.1", "resolved": "https://registry.npmjs.org/playwright-core/-/playwright-core-1.59.1.tgz", "integrity": "sha512-HBV/RJg81z5BiiZ9yPzIiClYV/QMsDCKUyogwH9p3MCP6IYjUFu/MActgYAvK0oWyV9NlwM3GLBjADyWgydVyg==", "license": "Apache-2.0", "bin": { "playwright-core": "cli.js" }, "engines": { "node": ">=18" } }, "node_modules/pptxgenjs": { "version": "4.0.1", "resolved": "https://registry.npmjs.org/pptxgenjs/-/pptxgenjs-4.0.1.tgz", "integrity": "sha512-TeJISr8wouAuXw4C1F/mC33xbZs/FuEG6nH9FG1Zj+nuPcGMP5YRHl6X+j3HSUnS1f3at6k75ZZXPMZlA5Lj9A==", "license": "MIT", "dependencies": { "@types/node": "^22.8.1", "https": "^1.0.0", "image-size": "^1.2.1", "jszip": "^3.10.1" } }, "node_modules/process-nextick-args": { "version": "2.0.1", "resolved": "https://registry.npmjs.org/process-nextick-args/-/process-nextick-args-2.0.1.tgz", "integrity": "sha512-3ouUOpQhtgrbOa17J7+uxOTpITYWaGP7/AhoR3+A+/1e9skrzelGi/dXzEYyvbxubEF6Wn2ypscTKiKJFFn1ag==", "license": "MIT" }, "node_modules/queue": { "version": "6.0.2", "resolved": "https://registry.npmjs.org/queue/-/queue-6.0.2.tgz", "integrity": "sha512-iHZWu+q3IdFZFX36ro/lKBkSvfkztY5Y7HMiPlOUjhupPcG2JMfst2KKEpu5XndviX/3UhFbRngUPNKtgvtZiA==", "license": "MIT", "dependencies": { "inherits": "~2.0.3" } }, "node_modules/readable-stream": { "version": "2.3.8", "resolved": "https://registry.npmjs.org/readable-stream/-/readable-stream-2.3.8.tgz", "integrity": "sha512-8p0AUk4XODgIewSi0l8Epjs+EVnWiK7NoDIEGU0HhE7+ZyY8D1IMY7odu5lRrFXGg71L15KG8QrPmum45RTtdA==", "license": "MIT", "dependencies": { "core-util-is": "~1.0.0", "inherits": "~2.0.3", "isarray": "~1.0.0", "process-nextick-args": "~2.0.0", "safe-buffer": "~5.1.1", "string_decoder": "~1.1.1", "util-deprecate": "~1.0.1" } }, "node_modules/safe-buffer": { "version": "5.1.2", "resolved": "https://registry.npmjs.org/safe-buffer/-/safe-buffer-5.1.2.tgz", "integrity": "sha512-Gd2UZBJDkXlY7GbJxfsE8/nvKkUEU1G38c1siN6QP6a9PT9MmHB8GnpscSmMJSoF8LOIrt8ud/wPtojys4G6+g==", "license": "MIT" }, "node_modules/semver": { "version": "7.8.2", "resolved": "https://registry.npmjs.org/semver/-/semver-7.8.2.tgz", "integrity": "sha512-c8jsqUZm3omBOI66G90z1Dyw5z622G8oLG+omfsHBJf3CWQTlOcwOjvOG6wtiNfW6anKm/eA39LMwMtMez2TiQ==", "license": "ISC", "bin": { "semver": "bin/semver.js" }, "engines": { "node": ">=10" } }, "node_modules/setimmediate": { "version": "1.0.5", "resolved": "https://registry.npmjs.org/setimmediate/-/setimmediate-1.0.5.tgz", "integrity": "sha512-MATJdZp8sLqDl/68LfQmbP8zKPLQNV6BIZoIgrscFDQ+RsvK/BxeDQOgyxKKoh0y/8h3BqVFnCqQ/gd+reiIXA==", "license": "MIT" }, "node_modules/sharp": { "version": "0.34.5", "resolved": "https://registry.npmjs.org/sharp/-/sharp-0.34.5.tgz", "integrity": "sha512-Ou9I5Ft9WNcCbXrU9cMgPBcCK8LiwLqcbywW3t4oDV37n1pzpuNLsYiAV8eODnjbtQlSDwZ2cUEeQz4E54Hltg==", "hasInstallScript": true, "license": "Apache-2.0", "dependencies": { "@img/colour": "^1.0.0", "detect-libc": "^2.1.2", "semver": "^7.7.3" }, "engines": { "node": "^18.17.0 || ^20.3.0 || >=21.0.0" }, "funding": { "url": "https://opencollective.com/libvips" }, "optionalDependencies": { "@img/sharp-darwin-arm64": "0.34.5", "@img/sharp-darwin-x64": "0.34.5", "@img/sharp-libvips-darwin-arm64": "1.2.4", "@img/sharp-libvips-darwin-x64": "1.2.4", "@img/sharp-libvips-linux-arm": "1.2.4", "@img/sharp-libvips-linux-arm64": "1.2.4", "@img/sharp-libvips-linux-ppc64": "1.2.4", "@img/sharp-libvips-linux-riscv64": "1.2.4", "@img/sharp-libvips-linux-s390x": "1.2.4", "@img/sharp-libvips-linux-x64": "1.2.4", "@img/sharp-libvips-linuxmusl-arm64": "1.2.4", "@img/sharp-libvips-linuxmusl-x64": "1.2.4", "@img/sharp-linux-arm": "0.34.5", "@img/sharp-linux-arm64": "0.34.5", "@img/sharp-linux-ppc64": "0.34.5", "@img/sharp-linux-riscv64": "0.34.5", "@img/sharp-linux-s390x": "0.34.5", "@img/sharp-linux-x64": "0.34.5", "@img/sharp-linuxmusl-arm64": "0.34.5", "@img/sharp-linuxmusl-x64": "0.34.5", "@img/sharp-wasm32": "0.34.5", "@img/sharp-win32-arm64": "0.34.5", "@img/sharp-win32-ia32": "0.34.5", "@img/sharp-win32-x64": "0.34.5" } }, "node_modules/string_decoder": { "version": "1.1.1", "resolved": "https://registry.npmjs.org/string_decoder/-/string_decoder-1.1.1.tgz", "integrity": "sha512-n/ShnvDi6FHbbVfviro+WojiFzv+s8MPMHBczVePfUpDJLwoLT0ht1l4YwBCbi8pJAveEEdnkHyPyTP/mzRfwg==", "license": "MIT", "dependencies": { "safe-buffer": "~5.1.0" } }, "node_modules/tslib": { "version": "1.14.1", "resolved": "https://registry.npmjs.org/tslib/-/tslib-1.14.1.tgz", "integrity": "sha512-Xni35NKzjgMrwevysHTCArtLDpPvye8zV/0E4EyYn43P7/7qvQwPh9BGkHewbMulVntbigmcT7rdX3BNo9wRJg==", "license": "0BSD" }, "node_modules/undici-types": { "version": "6.21.0", "resolved": "https://registry.npmjs.org/undici-types/-/undici-types-6.21.0.tgz", "integrity": "sha512-iwDZqg0QAGrg9Rav5H4n0M64c3mkR59cJ6wQp+7C4nI0gsmExaedaYLNO44eT4AtBBwjbTiGPMlt2Md0T9H9JQ==", "license": "MIT" }, "node_modules/util-deprecate": { "version": "1.0.2", "resolved": "https://registry.npmjs.org/util-deprecate/-/util-deprecate-1.0.2.tgz", "integrity": "sha512-EPD5q1uXyFxJpCrLnCc1nHnq3gOa6DZBocAIiI2TaSCA7VCJ1UJDMagCzIkXNsUYfD1daK//LTEQ8xiIbrHtcw==", "license": "MIT" } } } -
package.json 133 B
{ "dependencies": { "pdf-lib": "^1.17.1", "playwright": "^1.59.1", "pptxgenjs": "^4.0.1", "sharp": "^0.34.5" } } -
README.en.md 18.3 KB
<sub>🌐 <a href="README.md">中文</a> · <b>English</b></sub> <div align="center"> # Huashu Design > *"Type. Hit enter. A finished design lands in your lap."* > *「打字。回车。一份能交付的设计。」* [](LICENSE) [](https://skills.sh) [](https://skills.sh) <br> **Say one sentence to your agent — Claude Code, Cursor, Codex, OpenClaw, Hermes all work.** <br> 3 to 30 minutes — you ship a **product launch animation**, a clickable App prototype, an editable PPT deck, a print-grade infographic. Not "decent for AI" quality — it looks like a real design team made it. Give the skill your brand assets (logo, colors, UI screenshots) and it reads your brand's voice; give it nothing and the built-in 20 design vocabularies still keep you out of AI slop territory. **Every animation in this README was made by huashu-design itself.** No Figma, no After Effects — just a sentence + skill run. Next product launch needs a promo video? You can make it too. ``` npx skills add alchaincyf/huashu-design ``` > 📣 **Now MIT-licensed.** As of 2026-05-14 this skill is fully open-source under the [MIT License](LICENSE) — free for personal **and** commercial use, no authorization required. ([what changed](#license)) [See it work](#demo-gallery) · [Install](#install) · [What it does](#what-it-does) · [How it works](#core-mechanics) · [vs. Claude Design](#vs-claude-design) > 📖 **Note for English readers**: this skill is built by a Chinese-speaking developer. The skill's agent prompts (`SKILL.md`, `references/*.md`) are in Chinese but the agent is bilingual — works fine with English tasks. The demos below are the English parallel versions; the Chinese ones are in the default [Chinese README](README.md). > > 📖 **致中文读者**：这个 skill 由花叔（@AlchainHust）开发。一句话能让 agent 在 3–30 分钟内交付**产品发布动画 / 可点击 App 原型 / 可编辑 PPT / 印刷级信息图**。完整中文介绍见 [README.md](README.md)（默认中文）。 </div> --- <p align="center"> <video src="https://github.com/alchaincyf/huashu-design/releases/download/v2.0/hero-animation-v10-en.mp4" autoplay muted loop playsinline width="100%"> Your browser doesn't support inline video. <a href="https://github.com/alchaincyf/huashu-design/releases/download/v2.0/hero-animation-v10-en.mp4">Download MP4</a>. </video> </p> <p align="center"><sub>▲ 10-second hero animation showing what huashu-design does (<a href="https://github.com/alchaincyf/huashu-design/releases/download/v2.0/hero-animation-v10-en.mp4">download MP4</a> if autoplay doesn't work)</sub></p> --- ## Install ```bash npx skills add alchaincyf/huashu-design ``` > **Verify after install**: this skill is more than a single SKILL.md — the `references/`, `assets/`, `scripts/`, and `demos/` subdirectories hold 99 referenced recipes, scripts, and assets that the skill depends on. After installing, check the install path (e.g. `~/.claude/skills/huashu-design/`); if you only see SKILL.md and none of those subdirectories, your `skills` CLI is too old (≤1.5.15 had a bug that synced only the single file, fixed in 1.5.19). Upgrade and reinstall: > > ```bash > npm i -g skills@latest # or npx skills@latest add alchaincyf/huashu-design > ``` > > If it's still wrong after upgrading, fall back to a `git clone` install — clone the repo into any skills directory: > > ```bash > git clone https://github.com/alchaincyf/huashu-design.git ~/.claude/skills/huashu-design > ``` Then just talk to Claude Code: ``` "Make a keynote for AI psychology. Give me 3 style directions to pick from." "Build an iOS prototype for a Pomodoro app — 4 screens, actually clickable." "Turn this logic into a 60-second animation. Export MP4 and GIF." "Run a 5-dimension expert review on this design." ``` No buttons, no panels, no Figma plugin. Agent-agnostic — drops into Claude Code, Cursor, Trae, Hermes, OpenClaw, or any markdown-skill-capable agent. --- ## Star History <p align="center"> <a href="https://star-history.com/#alchaincyf/huashu-design&Date"> <img src="https://api.star-history.com/svg?repos=alchaincyf/huashu-design&type=Date" alt="huashu-design Star History" width="80%"> </a> </p> --- ## What it does | Capability | Deliverable | Typical time | |---|---|---| | Interactive prototype (App / Web) | Single-file HTML · real iPhone bezel · clickable · Playwright-verified | 10–15 min | | Slide decks | HTML deck (browser presentation) + editable PPTX (text frames preserved) | 15–25 min | | Motion design | MP4 (25fps / 60fps interpolation) + GIF (palette-optimized) + BGM | 8–12 min | | Design variations | 3+ side-by-side · Tweaks live params · cross-dimension exploration | 10 min | | Infographic / data viz | Print-quality typography · exports to PDF/PNG/SVG | 10 min | | Design direction advisor | 5 schools × 20 philosophies · 3 directions recommended · Demos generated in parallel | 5 min | | 5-dimension expert critique | Radar chart + Keep/Fix/Quick Wins · actionable punch list | 3 min | --- ## Demo Gallery > English parallel versions of the demos. Chinese versions live at the default filenames (see the Chinese README). ### Design Direction Advisor The fallback for vague briefs: pick 3 differentiated directions from 5 schools × 20 philosophies, generate all 3 demos in parallel, let the user choose. <p align="center"><img src="https://github.com/alchaincyf/huashu-design/releases/download/v2.0/w3-fallback-advisor-en.gif" width="100%"></p> ### iOS App Prototype Pixel-accurate iPhone 15 Pro body (Dynamic Island / status bar / Home Indicator) · state-driven multi-screen navigation · real images pulled from Wikimedia/Met/Unsplash · Playwright click tests before delivery. <p align="center"><img src="https://github.com/alchaincyf/huashu-design/releases/download/v2.0/c1-ios-prototype-en.gif" width="100%"></p> ### Motion Design Engine Stage + Sprite time-slice model · `useTime` / `useSprite` / `interpolate` / `Easing` — four APIs cover every animation need · one command exports MP4 / GIF / 60fps-interpolated / BGM-scored finals. <p align="center"><img src="https://github.com/alchaincyf/huashu-design/releases/download/v2.0/c3-motion-design-en.gif" width="100%"></p> ### HTML Slides → Editable PPTX HTML decks for browser presentation · `html2pptx.js` reads DOM computed styles and translates each element into real PowerPoint objects · exports are **actual text frames**, not image-bed fakes. <p align="center"><img src="https://github.com/alchaincyf/huashu-design/releases/download/v2.0/c2-slides-pptx-en.gif" width="100%"></p> ### Tweaks · Live Variation Switching Colors / typography / information density parameterized · side panel toggle · pure-frontend + `localStorage` persistence · survives reload. <p align="center"><img src="https://github.com/alchaincyf/huashu-design/releases/download/v2.0/c4-tweaks-en.gif" width="100%"></p> ### Infographic / Data Viz Magazine-grade typography · precise CSS Grid columns · `text-wrap: pretty` typographic details · driven by real data · exports to vector PDF / 300dpi PNG / SVG. <p align="center"><img src="https://github.com/alchaincyf/huashu-design/releases/download/v2.0/c5-infographic-en.gif" width="100%"></p> ### 5-Dimension Expert Critique Philosophical coherence · visual hierarchy · execution craft · functionality · innovation — each scored 0–10 · radar-chart visualization · outputs Keep / Fix / Quick Wins punch list. <p align="center"><img src="https://github.com/alchaincyf/huashu-design/releases/download/v2.0/c6-expert-review-en.gif" width="100%"></p> ### Junior Designer Workflow No heroic one-shot attempts: start with assumptions + placeholders + reasoning, show it to the user early, then iterate. Fixing a misunderstanding early is 100× cheaper than fixing it late. <p align="center"><img src="https://github.com/alchaincyf/huashu-design/releases/download/v2.0/w2-junior-designer-en.gif" width="100%"></p> ### Core Asset Protocol · 5-step hard process Mandatory whenever the task involves a specific brand: ask → search → download (three fallback paths) → verify + extract → write `brand-spec.md` covering **logo, product shots, UI screenshots, colors, fonts** — all required assets, not just colors. <p align="center"><img src="https://github.com/alchaincyf/huashu-design/releases/download/v2.0/w1-brand-protocol-en.gif" width="100%"></p> --- ## Core Mechanics ### Core Asset Protocol The hardest rule in the skill. When the task touches a specific brand (Stripe, Linear, Anthropic, DJI, your own company, etc.), five steps are enforced: | Step | Action | Purpose | |---|---|---| | 1 · Ask | Checklist of 6 asset types: logo / product shots / UI screenshots / color palette / fonts / brand guidelines | Respect existing resources | | 2 · Search official channels | `<brand>.com/brand` · `<brand>.com/press` · `brand.<brand>.com` · product pages · launch films | Find authoritative assets | | 3 · Download by asset type | Logo (SVG → inline-SVG in HTML → social avatar) · Product shots (hero → press kit → launch video frames → AI-generated from reference) · UI (App Store screenshots → official video frames) | Three fallback paths per asset type | | 4 · Verify + extract | Check logo fidelity · product image resolution · UI freshness · grep color hex from real assets | **Never guess from memory** | | 5 · Freeze to spec | Write `brand-spec.md` with logo paths, product image paths, UI screenshot paths, CSS variables for colors/fonts | Un-frozen knowledge evaporates | **Ranking of asset importance** (from the skill's internal rubric): 1. Logo — mandatory for any brand 2. Product renders — mandatory for physical products 3. UI screenshots — mandatory for digital products 4. Color values — auxiliary 5. Fonts — auxiliary A/B-tested (v1 vs v2, 6 agents each): **v2 reduced stability variance by 5×**. Stability of stability — that's the real moat. ### Design Direction Advisor (Fallback) Triggered when the brief is too vague to execute: - Don't run on generic intuition — enter Fallback mode - Recommend 3 differentiated directions from 5 schools × 20 philosophies, each **from a different school** - Each comes with flagship works, gestalt keywords, representative designer - Generate 3 visual demos in parallel, let the user choose - Once chosen, continue into the Junior Designer main flow ### Junior Designer Workflow The default working mode across every task: - Send the full question set in one batch, wait for all answers before moving - Write assumptions + placeholders + reasoning comments directly into the HTML - Show it to the user early (even if just gray blocks) - Fill in real content → variations → Tweaks — show at each of these three steps - Manually eyeball the browser with Playwright before delivery ### Fact Verification First (Principle #0) The highest-priority rule, added after a real failure mode: when the task mentions a specific product / technology / event (e.g., "DJI Pocket 4", "Nano Banana Pro", "Gemini 3 Pro"), the first action **must** be a `WebSearch` to confirm existence, release status, current version, and specs. No claims from training-corpus memory. Cost of a search: ~10 seconds. Cost of a wrong assumption: 1–2 hours of rework. ### Anti AI-slop Rules Avoid the visual common denominator of AI output (purple gradients / emoji icons / rounded-corner + left border accent / SVG humans / Inter-as-display / **CSS silhouettes standing in for real product shots**). Use `text-wrap: pretty` + CSS Grid + carefully chosen serif display faces + oklch colors. --- ## vs. Claude Design I'll be upfront: the Core Asset Protocol's philosophy was lifted from system prompts Anthropic wrote for Claude Design. That prompt hammers home a single idea — **great hi-fi design doesn't start from a blank page, it grows from existing design context**. That one principle is the difference between a 65-point design and a 90-point design. Positioning differences: | | Claude Design | huashu-design | |---|---|---| | Form | Web product (used in browser) | Skill (used in Claude Code) | | Quota | Subscription quota | API usage · parallel agents unblocked | | Output | Canvas + Figma export | HTML / MP4 / GIF / editable PPTX / PDF | | Interaction | GUI (click, drag, edit) | Conversation (tell agent, wait) | | Complex animation | Limited | Stage + Sprite timeline · 60fps export | | Agent compatibility | Claude.ai only | Claude Code / Cursor / Trae / Hermes / OpenClaw | Claude Design is a **better graphics tool**. Huashu-design makes **the graphics-tool layer disappear**. Two paths, different audiences. --- ## Security & Data Flow The core pipeline (design → render → MP4/PDF/PPTX export) runs **100% locally — zero network calls, zero API keys**. Cloud features (Doubao TTS narration, AI video review) are isolated in `scripts/cloud/`, fully optional: your own keys, official vendor APIs only, and an explicit `--yes` consent gate before anything leaves your machine. No telemetry; nothing is ever sent to any author-controlled server. Every outbound host, credential touchpoint, and deletion boundary is exhaustively declared in [SECURITY.md](SECURITY.md) — point your agent at it and verify against the code. --- ## Limitations - **No layer-editable PPTX-to-Figma round-trip.** The output is HTML — screenshottable, recordable, image-exportable, but not draggable into Keynote for text-position tweaks. - **Framer-Motion-tier complex animations are out of scope.** 3D, physics simulation, particle systems exceed the skill's boundaries. - **Brand-from-zero design quality drops to 60–65 points.** Drawing hi-fi from nothing was always a last resort. This is an 80-point skill, not a 100-point product. For people unwilling to open a graphical UI, an 80-point skill beats a 100-point product. --- ## Repository Structure ``` huashu-design/ ├── SKILL.md # Main doc (read by agent, Chinese) ├── README.md # Chinese README (default) ├── README.en.md # English README (this file) ├── assets/ # Starter Components │ ├── animations.jsx # Stage + Sprite + Easing + interpolate │ ├── ios_frame.jsx # iPhone 15 Pro bezel │ ├── android_frame.jsx │ ├── macos_window.jsx │ ├── browser_window.jsx │ ├── deck_stage.js # HTML deck engine │ ├── deck_index.html # Multi-file deck assembler │ ├── design_canvas.jsx # Side-by-side variation display │ ├── showcases/ # 24 prebuilt samples (8 scenes × 3 styles) │ └── bgm-*.mp3 # 6 scene-specific background tracks ├── references/ # Drill-down docs by task (Chinese) │ ├── animation-pitfalls.md │ ├── design-styles.md # 20 design philosophies in detail │ ├── slide-decks.md │ ├── editable-pptx.md │ ├── critique-guide.md │ ├── video-export.md │ └── ... ├── scripts/ # Export toolchain │ ├── render-video.js # HTML → MP4 │ ├── convert-formats.sh # MP4 → 60fps + GIF │ ├── add-music.sh # MP4 + BGM │ ├── export_deck_pdf.mjs │ ├── export_deck_pptx.mjs │ ├── html2pptx.js │ └── verify.py └── demos/ # Capability demos referenced by this README ``` --- ## Origin Story The day Anthropic launched Claude Design I played with it until 4 a.m. A few days later I realized I hadn't opened it once since — not because it's bad (it's the most polished product in the category) but because I'd rather have an agent work in my terminal than open any graphical UI. So I had an agent deconstruct Claude Design itself (including the system prompts circulating in the community, the brand asset protocol, the component mechanics), distill it into a structured spec, then write it as a skill installed in my own Claude Code. Thanks to Anthropic for writing the Claude Design prompts so clearly. This kind of derivative work inspired by other products is the new form of open-source culture in the AI era. --- ## Available Languages Community-maintained translations of this skill. Translation quality and license terms are the responsibility of each maintainer — please check the linked repo before relying on it. | Language | Maintainer | Repository | |---|---|---| | English | [@namandhakad712](https://github.com/namandhakad712) | [namandhakad712/huashu-design-en](https://github.com/namandhakad712/huashu-design-en) | | 한국어 (Korean) | [@ktkarchive](https://github.com/ktkarchive) | [ktkarchive/ktk-design](https://github.com/ktkarchive/ktk-design) | | Tiếng Việt (Vietnamese) | [@letrquan](https://github.com/letrquan) | [letrquan/huashu-design](https://github.com/letrquan/huashu-design) | Want to add your language? Fork the repo, translate `SKILL.md` + `README.md`, and open an issue here so we can link it. --- ## License **Relicensed to MIT on 2026-05-14.** This skill was previously released under a Personal Use License that restricted commercial use. That restriction is now removed. Under the [MIT License](LICENSE) you are free to **use, modify, and distribute** this skill for any purpose, **including commercial use** — inside companies, in client deliverables, as part of a paid product, anywhere. No prior authorization, no licensing fee, no notification required. Attribution is appreciated but not required. --- ## Connect · Huasheng (Huashu) Huasheng is an AI-native coder, independent developer, and AI content creator. Notable work: Cat Fill Light (App Store Top 1 in Paid category), *A Book on DeepSeek*, Nüwa.skill (GitHub 21k+ stars). Combined 300k+ followers across platforms. | Platform | Handle | Link | |---|---|---| | X / Twitter | @AlchainHust | https://x.com/AlchainHust | | WeChat Official Account | 花叔 | Search "花叔" in WeChat | | Bilibili | 花叔 | https://space.bilibili.com/14097567 | | YouTube | 花叔 | https://www.youtube.com/@Alchain | | Xiaohongshu | 花叔 | https://www.xiaohongshu.com/user/profile/5abc6f17e8ac2b109179dfdf | | Official Site | huasheng.ai | https://www.huasheng.ai/ | | Developer Hub | bookai.top | https://bookai.top | For collaborations or sponsored content, DM on any of the above. -
README.md 19.3 KB
<sub>🌐 <b>中文</b> · <a href="README.en.md">English</a></sub> <div align="center"> # Huashu Design > *「打字。回车。一份能交付的设计。」* > *"Type. Hit enter. A finished design lands in your lap."* [](LICENSE) [](https://skills.sh) [](https://skills.sh) <br> **在你的 agent 里打一句话，拿回一份能交付的设计。** <br> 3 到 30 分钟，你能 ship 一段**产品发布动画**、一个能点击的 App 原型、一套能编辑的 PPT、一份印刷级的信息图。 不是「AI 做的还行」那种水平——是看起来像大厂设计团队做的。给 skill 你的品牌资产（logo、色板、UI 截图），它会读懂你的品牌气质；什么都不给，**三套逻辑顾问 + 60 种 HTML 原生风格库**也能兜底到不出 AI slop。 **你看到这篇 README 里的每一个动画，都是 huashu-design 自己做的。** 不是 Figma，不是 AE，就是一句话 prompt + skill 跑通。下次产品发布要做宣传片？现在你也能做。 ``` npx skills add alchaincyf/huashu-design ``` 跨 agent 通用——Claude Code、Cursor、Codex、OpenClaw、Hermes 都能装。 > 📣 **已改为 MIT 协议。** 自 2026-05-14 起本 skill 完全开源（[MIT License](LICENSE)），个人和**商用都免费**，无需事先授权。原「个人使用免费、企业商用需授权」的条款已作废。([查看变更](#license)) [看效果](#demo-画廊) · [安装](#装上就能用) · [能做什么](#能做什么) · [核心机制](#核心机制) · [和 Claude Design 的关系](#和-claude-design-的关系) </div> --- <p align="center"> <img src="https://github.com/alchaincyf/huashu-design/releases/download/v2.0/hero-animation-v10-en.gif" alt="huashu-design Hero · 打字 → 选方向 → 画廊展开 → 聚焦 → 品牌显形" width="100%"> </p> <p align="center"><sub> ▲ 25 秒 · Terminal → 4 方向 → Gallery ripple → 4 次 Focus → Brand reveal<br> 👉 <a href="https://www.huasheng.ai/huashu-design-hero/">访问带音效的 HTML 互动版</a> · <a href="https://github.com/alchaincyf/huashu-design/releases/download/v2.0/hero-animation-v10-en.mp4">下载 MP4（含 BGM+SFX · 10MB）</a> </sub></p> --- ## 📺 新手教程（花叔亲录） 不知道怎么用？看花叔录的 huashu-design 上手教程： <p align="center"> <a href="https://www.youtube.com/watch?v=m-_BlUdcIvw"><img src="https://img.youtube.com/vi/m-_BlUdcIvw/maxresdefault.jpg" alt="huashu-design 使用教程" width="70%"></a> </p> <p align="center"><sub>👉 <a href="https://www.youtube.com/watch?v=m-_BlUdcIvw">在 YouTube 观看完整教程</a></sub></p> --- ## 装上就能用 ```bash npx skills add alchaincyf/huashu-design ``` > **装完先自检**：这个 skill 不只是 SKILL.md 一个文件，`references/`、`assets/`、`scripts/`、`demos/` 四个子目录里有 99 处被引用的配方、脚本、素材，缺一不可。装完看一眼安装目录（如 `~/.claude/skills/huashu-design/`），如果只有 SKILL.md、没有那几个子目录，说明你的 `skills` CLI 版本太旧（≤1.5.15 有个只同步单文件的 bug，已在 1.5.19 修复）。升级后再装一次即可： > > ```bash > npm i -g skills@latest # 或 npx skills@latest add alchaincyf/huashu-design > ``` > > 升级后仍异常，就用 `git clone` 兜底安装，把仓库克隆到任意 skills 目录即可： > > ```bash > git clone https://github.com/alchaincyf/huashu-design.git ~/.claude/skills/huashu-design > ``` 然后在 Claude Code / Codex / Cursor 等任意支持 skills 的 agent 里直接说话： ``` 「做一份 AI 心理学的演讲 PPT，推荐 3 个风格方向让我选」 「做个 AI 番茄钟 iOS 原型，4 个核心屏幕要真能点击」 「把这段逻辑做成 60 秒动画，导出 MP4 和 GIF」 「帮我对这个设计做一个 5 维度评审」 ``` 没有按钮、没有面板、没有 Figma 插件。 --- ## Star 趋势 <p align="center"> <a href="https://star-history.com/#alchaincyf/huashu-design&Date"> <img src="https://api.star-history.com/svg?repos=alchaincyf/huashu-design&type=Date" alt="huashu-design Star History" width="80%"> </a> </p> --- ## 能做什么 | 能力 | 交付物 | 典型耗时 | |------|--------|----------| | 交互原型（App / Web） | 单文件 HTML · 真 iPhone bezel · 可点击 · Playwright 验证 | 10–15 min | | 演讲幻灯片 | HTML deck（浏览器演讲）+ 可编辑 PPTX（文本框保留） | 15–25 min | | 时间轴动画 | MP4（25fps / 60fps 插帧）+ GIF（palette 优化）+ BGM | 8–12 min | | 设计变体 | 3+ 并排对比 · Tweaks 实时调参 · 跨维度探索 | 10 min | | 信息图 / 可视化 | 印刷级排版 · 可导 PDF/PNG/SVG | 10 min | | 设计方向顾问 | **三套逻辑并行**（秒数轮盘 + 现实参照获奖站 + 最佳设计师）· 直接出 3 版真实视觉 | 5 min | | 5 维度专家评审 | 雷达图 + Keep/Fix/Quick Wins · 可操作修复清单 | 3 min | --- ## Demo 画廊 ### 设计方向顾问 模糊需求时的 fallback：**三套互补逻辑并行**——秒数轮盘（20 选 1 打破惯性）+ 现实参照（世界级获奖网站迁移）+ 最佳设计师（顶级工作室哲学），直接出 3 版**真实视觉**让你看着选，不让你在文字里盲选风格。背后是 **60 种 HTML 原生风格库**（网页 20 + PPT 20 + 信息图 20，纯 CSS 无需生图）。 <p align="center"><img src="https://github.com/alchaincyf/huashu-design/releases/download/v2.0/w3-fallback-advisor.gif" width="100%"></p> ### iOS App 原型 iPhone 15 Pro 精确机身（灵动岛 / 状态栏 / Home Indicator）· 状态驱动多屏切换 · 真图从 Wikimedia/Met/Unsplash 取 · Playwright 自动点击测试。 <p align="center"><img src="https://github.com/alchaincyf/huashu-design/releases/download/v2.0/c1-ios-prototype.gif" width="100%"></p> ### Motion Design 引擎 Stage + Sprite 时间片段模型 · `useTime` / `useSprite` / `interpolate` / `Easing` 四 API 覆盖所有动画需求 · 一条命令导出 MP4 / GIF / 60fps 插帧 / 带 BGM 的成片。 <p align="center"><img src="https://github.com/alchaincyf/huashu-design/releases/download/v2.0/c3-motion-design.gif" width="100%"></p> ### HTML Slides → 可编辑 PPTX HTML deck 浏览器演讲 · `html2pptx.js` 读 DOM 的 computedStyle 逐元素翻译成 PowerPoint 对象 · 导出的是**真文本框**，PPT 里双击即可编辑。 <p align="center"><img src="https://github.com/alchaincyf/huashu-design/releases/download/v2.0/c2-slides-pptx.gif" width="100%"></p> ### Tweaks · 实时变体切换 配色 / 字型 / 信息密度等参数化 · 侧边面板切换 · 纯前端 + `localStorage` 持久化 · 刷新不丢。 <p align="center"><img src="https://github.com/alchaincyf/huashu-design/releases/download/v2.0/c4-tweaks.gif" width="100%"></p> ### 信息图 / 数据可视化 杂志级排版 · CSS Grid 精准分栏 · `text-wrap: pretty` 排印细节 · 真数据驱动 · 可导 PDF 矢量 / PNG 300dpi / SVG。 <p align="center"><img src="https://github.com/alchaincyf/huashu-design/releases/download/v2.0/c5-infographic.gif" width="100%"></p> ### 5 维度专家评审 哲学一致性 · 视觉层级 · 细节执行 · 功能性 · 创新性 各 0–10 分 · 雷达图可视化 · 输出 Keep / Fix / Quick Wins 清单。 <p align="center"><img src="https://github.com/alchaincyf/huashu-design/releases/download/v2.0/c6-expert-review.gif" width="100%"></p> ### Junior Designer 工作流 不闷头做大招：先写 assumptions + placeholders + reasoning，尽早 show 给你，再迭代。理解错了早改比晚改便宜 100 倍。 <p align="center"><img src="https://github.com/alchaincyf/huashu-design/releases/download/v2.0/w2-junior-designer.gif" width="100%"></p> ### 品牌资产协议 5 步硬流程 涉及具体品牌时强制执行：问 → 搜 → 下载（三条兜底）→ grep 色值 → 写 `brand-spec.md`。 <p align="center"><img src="https://github.com/alchaincyf/huashu-design/releases/download/v2.0/w1-brand-protocol.gif" width="100%"></p> --- ## Showcase · 真实案例 ### 鹦鹉进化史网站 · 设计方向顾问三套逻辑实战（2.0） > **Live demo · [https://www.huasheng.ai/parrots/](https://www.huasheng.ai/parrots/)** 一句「做个介绍鹦鹉进化史的网站」、零额外要求，skill 自动跑完整 2.0 顾问流程：先判断图片是内容必需 → 抓公共领域博物插画（Edward Lear / John Gould 的鹦鹉图录）→ **三套逻辑并行**（秒数轮盘 + 现实参照获奖站 + 原研哉「白」哲学）各出一版真实视觉。**素材齐了再设计，不是边设计边用色块占位。** ### 「聊聊 skill」 · PM after-party 演讲 deck > **Live demo · [https://skill-huasheng.vercel.app](https://skill-huasheng.vercel.app)** 13 页 HTML deck，**全部用 huashu-design 完成**： - 黑底极简衬线视觉系统（cover / about / hook / what / why / closing） - 2 个带 BGM + SFX 的 22 秒 cinematic demo（Nuwa skill workflow + Darwin skill workflow），各采用**完全独立的视觉语言**： - **Nuwa**：3D 知识 orbit + Pentagon 提炼 + SKILL.md typewriter + 「21 分钟」hero reveal - **Darwin**：autoresearch loop spin + v1/v5 并列 diff + Hill-Climb 全屏曲线 + Ratchet gear lock - 每个 cinematic 默认显示**完整静态 workflow dashboard**（观众随时能看清 skill 怎么跑），点 ▶ 才触发动画，跑完自动 fade 回 dashboard - 嵌入 huasheng.ai 的 25 秒 hero 动画（iframe 本地化兜底） - 真实数据：14,495 stargazers 真实曲线（gh API 拉取）+ DeepSeek V4 真实 specs（WebSearch 验证） - 真实 AI 素材：用 `huashu-gpt-image` 跑 4×2 grid 大图，`extract_grid.py` 抠出 8 张独立透明 PNG，做 3D orbit 漂浮 **适合参考的页面**： - `/slides/slide-04b-nuwa-flow.html` · 静态 dashboard + cinematic overlay 双层架构 - `/slides/slide-06b-darwin-flow.html` · 完全独立视觉语言的对照案例 - `/slides/slide-03b-deepseek-cover.html` · AI slop vs 真实设计师视角的对比页 详细 cinematic patterns 见 `references/cinematic-patterns.md`。 --- ## 核心机制 ### 品牌资产协议 skill 里最硬的一段规则。涉及具体品牌（Stripe、Linear、Anthropic、自家公司等）时强制执行 5 步： | 步骤 | 动作 | 目的 | |------|------|------| | 1 · 问 | 用户有 brand guidelines 吗？ | 尊重已有资源 | | 2 · 搜官方品牌页 | `<brand>.com/brand` · `brand.<brand>.com` · `<brand>.com/press` | 抓权威色值 | | 3 · 下载资产 | SVG 文件 → 官网 HTML 全文 → 产品截图取色 | 三条兜底，前一条失败立刻走下一条 | | 4 · grep 提取色值 | 从资产里抓所有 `#xxxxxx`，按频率排序，过滤黑白灰 | **绝不从记忆猜品牌色** | | 5 · 固化 spec | 写 `brand-spec.md` + CSS 变量，所有 HTML 引用 `var(--brand-*)` | 不固化就会忘 | A/B 测试（v1 vs v2，各跑 6 agent）：**v2 的稳定性方差比 v1 低 5 倍**。稳定性的稳定性，这是 skill 真正的护城河。 ### 设计方向顾问（Fallback） 当用户需求模糊到无法着手时触发（2.0 重做）： - 先对话澄清 + 主动索要参考（名字 / logo / 品牌色 / 喜欢的参考站） - 取齐内容必需的真图（公共领域 / 免版权，脚本一键抓），再开工 - **三套互补逻辑并行 subagent**，各出一版**真实视觉**：① 秒数轮盘（`date +%S` 取秒，20 选 1，打破模型偷选极简的惯性）② 现实参照（世界级获奖网站 / PPT / iOS 原型迁移）③ 最佳设计师（预算无上限时最适合的工作室哲学） - **绝不让你在没看到视觉时盲选风格**——三版摆出来，看着选 - 选定后进入主干 Junior Designer 流程 - 底层是 **60 种 HTML 原生风格库**（网页 20 + PPT 20 + 信息图 20，按大胆 / 中性 / 安静分级，纯 CSS 无需生图）作弹药，不是教条 ### Junior Designer 工作流 默认工作模式，贯穿所有任务： - 开工前 show 问题清单一次性发给用户，等批量答完再动手 - HTML 里先写 assumptions + placeholders + reasoning comments - 尽早 show 给用户（哪怕只是灰色方块） - 填充实际内容 → variations → Tweaks 这三步分别再 show 一次 - 交付前用 Playwright 肉眼过一遍浏览器 ### 反 AI slop 规则 避免一眼 AI 的视觉最大公约数（紫渐变 / emoji 图标 / 圆角+左 border accent / SVG 画人脸 / Inter 做 display）。用 `text-wrap: pretty` + CSS Grid + 精心选择的 serif display 和 oklch 色彩。 --- ## 和 Claude Design 的关系 我大方承认：品牌资产协议的哲学是从 Claude Design 流传出来的提示词里偷师的。那份提示词反复强调**好的高保真设计不是从白纸开始，而是从已有的设计上下文长出来**。这个原则是 65 分作品和 90 分作品的分水岭。 定位差异： | | Claude Design | huashu-design | |---|---|---| | 形态 | 网页产品（浏览器里用） | skill（Claude Code 里用） | | 配额 | 订阅 quota | API 消耗 · 并行跑 agent 不受 quota 限 | | 交付物 | 画布内 + 可导 Figma | HTML / MP4 / GIF / 可编辑 PPTX / PDF | | 操作方式 | GUI（点、拖、改） | 对话（说话、等 agent 做完） | | 复杂动画 | 有限 | Stage + Sprite 时间轴 · 60fps 导出 | | 跨 agent | 专属 Claude.ai | 任意 skill 兼容 agent | Claude Design 是**更好的图形工具**，huashu-design 是**让图形工具这层消失**。两条路，不同受众。 --- ## 安全与数据流 核心链路（设计→渲染→MP4/PDF/PPTX导出）**100%本地运行，零网络零key**。云能力（豆包TTS配音、AI看片评审）全部隔离在 `scripts/cloud/`，完全可选：用你自己的key、只发对应厂商官方API、首次调用需 `--yes` 显式确认。无telemetry，没有任何数据发往作者服务器。全部出站域名、密钥处理、删除边界的穷举声明见 [SECURITY.md](SECURITY.md)，欢迎用你的agent对着代码逐条核验。 --- ## Limitations - **不支持图层级可编辑的 PPTX 到 Figma**。产出 HTML，可截图、录屏、导图，但不能拖进 Keynote 改文字位置。 - **Framer Motion 级别的复杂动画不行**。3D、物理模拟、粒子系统超出 skill 边界。 - **完全空白的品牌从零设计质量会掉到 60–65 分**。凭空画 hi-fi 本来就是 last resort。 这是一个 80 分的 skill，不是 100 分的产品。对不愿意打开图形界面的人，80 分的 skill 比 100 分的产品好用。 --- ## 仓库结构 ``` huashu-design/ ├── SKILL.md # 主文档（给 agent 读） ├── README.md # 中文 README（默认，本文件） ├── README.en.md # 英文 README ├── assets/ # Starter Components │ ├── animations.jsx # Stage + Sprite + Easing + interpolate │ ├── ios_frame.jsx # iPhone 15 Pro bezel │ ├── android_frame.jsx │ ├── macos_window.jsx │ ├── browser_window.jsx │ ├── deck_stage.js # HTML 幻灯片引擎 │ ├── deck_index.html # 多文件 deck 拼接器 │ ├── design_canvas.jsx # 并排变体展示 │ ├── showcases/ # 24 个预制样例（8 场景 × 3 风格） │ └── bgm-*.mp3 # 6 首场景化背景音乐 ├── references/ # 按任务深入读的子文档 │ ├── animation-pitfalls.md │ ├── design-styles.md # 60 种 HTML 原生风格库（网页 20 + PPT 20 + 信息图 20） │ ├── slide-decks.md │ ├── editable-pptx.md │ ├── critique-guide.md │ ├── video-export.md │ └── ... ├── scripts/ # 导出工具链 │ ├── render-video.js # HTML → MP4 │ ├── convert-formats.sh # MP4 → 60fps + GIF │ ├── add-music.sh # MP4 + BGM │ ├── export_deck_pdf.mjs │ ├── export_deck_pptx.mjs │ ├── html2pptx.js │ └── verify.py └── demos/ # 9 个能力演示 (c*/w*)，中英双版 GIF/MP4/HTML + hero v10 ``` --- ## 起源 Anthropic 发布 Claude Design 那天我玩到凌晨四点。几天之后发现自己再也没点开过它，不是它不好——它是这个赛道目前最成熟的产品——是我宁愿让 agent 在终端里帮我干活，也不愿意打开任何图形界面。 于是让 agent 拆解 Claude Design 本身（包括社区流传的系统提示词、品牌资产协议、组件机制），蒸馏成结构化 spec，再写成 skill 装进自己的 Claude Code。 感谢 Anthropic 把 Claude Design 的提示词写得清晰。这种基于其他产品灵感的二次创作，是开源文化在 AI 时代的新形态。 --- ## 用 huashu-design 做的产品 **[FanBox · Coding Agent 的驾驶舱](https://github.com/alchaincyf/fanbox)** 的三套界面皮肤，就是用 huashu-design 设计的。指挥 Claude Code / Codex 干活，看清它碰过的每个文件、每一行改动。 [](https://github.com/alchaincyf/fanbox) --- ## 社区翻译版本 社区维护的翻译版本。翻译质量与各版本 license 条款由对应维护者负责，使用前请先确认。 | 语言 | 维护者 | 仓库 | |---|---|---| | English | [@namandhakad712](https://github.com/namandhakad712) | [namandhakad712/huashu-design-en](https://github.com/namandhakad712/huashu-design-en) | | 한국어（韩语） | [@ktkarchive](https://github.com/ktkarchive) | [ktkarchive/ktk-design](https://github.com/ktkarchive/ktk-design) | | Tiếng Việt（越南语） | [@letrquan](https://github.com/letrquan) | [letrquan/huashu-design](https://github.com/letrquan/huashu-design) | 想加你的语言？fork 仓库、翻译 `SKILL.md` + `README.md`，然后回这边开个 issue，我会把链接加进来。 --- ## License **2026-05-14 起改为 MIT 协议。** 此前版本采用「个人使用免费、企业商用需授权」的 Personal Use License，对商用做了限制——现在这层限制完全解除。 按 [MIT License](LICENSE)，你可以**自由使用、修改、分发**本 skill，**包括商业用途**——公司内部用、客户商单交付、做成付费产品对外卖，都没问题。无需事先授权、无需付费、无需打招呼。注明出处不强制，但欢迎。 --- ## Connect · 花生（花叔） 花生是 AI Native Coder、独立开发者、AI 自媒体博主。代表作：小猫补光灯（AppStore 付费榜 Top 1）、《一本书玩转 DeepSeek》、女娲 .skill（GitHub 12000+ star）。自媒体全平台 30 万+ 粉丝。 | 平台 | 账号 | 链接 | |---|---|---| | X / Twitter | @AlchainHust | https://x.com/AlchainHust | | 公众号 | 花叔 | 微信搜索「花叔」 | | B 站 | 花叔 | https://space.bilibili.com/14097567 | | YouTube | 花叔 | https://www.youtube.com/@Alchain | | 小红书 | 花叔 | https://www.xiaohongshu.com/user/profile/5abc6f17e8ac2b109179dfdf | | 官网 | huasheng.ai | https://www.huasheng.ai/ | | 开发者主页 | bookai.top | https://bookai.top | 合作咨询、自媒体约稿 → 以上任一平台私信花生即可。 -
SECURITY.md 5.1 KB
# Security & Data-Flow Statement This document exhaustively declares every network destination, credential touchpoint, subprocess, and deletion this skill can perform, so that users and automated security reviewers can verify the claims against the code. **TL;DR: the core pipeline (HTML design → render → MP4/PDF/PPTX export) runs 100% locally with zero network calls and zero API keys. All cloud-touching code is isolated in `scripts/cloud/`, is strictly optional, uses only keys you supply, sends data only to the corresponding vendor's official API, and refuses to run without explicit consent (`--yes` flag or `HUASHU_CLOUD_OK=1`). There is no telemetry. No data is ever sent to any server controlled by the skill author.** ## Complete list of network destinations | Host | Where | What is sent | When | |---|---|---|---| | `ark.cn-beijing.volces.com` (Volcengine Ark, ByteDance official API) | `scripts/cloud/ai-review-video.py` | Compressed segments of **your own rendered video**, for AI quality review, authenticated with **your own** `ARK_API_KEY` | Only when you run it, and only after the consent gate | | `openspeech.bytedance.com` (ByteDance official TTS API) | `scripts/cloud/tts-doubao.mjs` (also invoked by `scripts/narrate-pipeline.mjs`) | The narration text you want synthesized, with **your own** key. The endpoint is validated against a hardcoded hostname allowlist (`*.bytedance.com` / `*.volces.com`) — a tampered `.env` cannot redirect your key or text elsewhere | Only when you run it, and only after the consent gate | | `commons.wikimedia.org` (official Wikimedia API) | `scripts/fetch_images.py` | Image search keywords; downloads CC/public-domain images with license info printed for review | Only when the agent fetches stock imagery for a content design | | Brand official websites, `simpleicons.org`, Google favicon service | `references/brand-asset-protocol.md` (instructions, no script) | Plain GET requests to download publicly served logos/brand assets | Only when you ask for a brand-specific design | | `fonts.googleapis.com`, `unpkg.com` and similar CDNs | Static `<link>`/`<script>` tags inside demo/output HTML | Standard browser font/library fetches when *you* open a generated HTML file | Browser-side only; render scripts work offline-first | That is the entire list. `grep -rn "https://" --include="*.py" --include="*.mjs" --include="*.js" --include="*.sh" scripts/` to verify. ## API keys - No key is hardcoded anywhere; the repo ships only `.env.example` placeholders (`.env` is gitignored). - Keys are read from the **skill's own root `.env`** or process environment — never from files elsewhere on your machine. `ai-review-video.py` extracts only the single `ARK_API_KEY` variable; it does not load the rest of the file into the environment. - Keys are transmitted exclusively to the corresponding vendor's official endpoint listed above, over HTTPS, as auth headers. - `references/react-setup.md` option B (pasting an Anthropic key into a demo page input) is explicitly marked local-demo-only and not recommended; the default options require no key at all. ## Explicit consent gate Both cloud scripts print exactly what will be sent to which host and exit before any network call unless you pass `--yes` or set `HUASHU_CLOUD_OK=1`. Everything else in this skill never needs the gate because it never leaves your machine. ## Subprocesses All subprocess calls invoke local media tools only: `ffmpeg`, `ffprobe`, `ffplay`, Playwright/Chromium for HTML rendering and screenshots. No shell-to-network combinations, no curl-pipe-sh patterns. ## File deletion Recursive deletion is limited to temp directories the scripts themselves create with unique timestamp+PID names (`.video-tmp-*`, `.seek-tmp-*`, `_narration/.tmp`, Python `tempfile.TemporaryDirectory`). No script ever deletes user data or anything outside its own scratch space. ## Dependencies Mainstream registry packages only (`playwright`, `sharp`, `pptxgenjs`, `pdf-lib`, `requests`), installed via standard `npm`/`pip`/`uv` — no binary downloads from arbitrary URLs. One documented exception to be aware of: `npx hyperframes init` (optional animation backend, see `references/hyperframes-backend.md`) installs 19 hyperframes documentation skills into `~/.claude/skills/`. This is called out with a warning in the docs before the command. ## Hooks `scripts/design-gate-hook.sh` is **never installed automatically** — nothing in this skill writes to `settings.json`. If you manually opt in, its entire behavior is: block long-video render commands (exit 2) until a design-approval file exists. It makes no network calls, writes nothing, deletes nothing. ## Proxy handling note `fetch_images.py` and `ai-review-video.py` disable inheriting proxy environment variables (`trust_env = False` / clearing `ALL_PROXY` etc.) for their own requests. This exists to survive stale local proxy configurations that break TLS — not to evade monitoring. If you need these requests to go through your proxy, set it explicitly in the script invocation. ## Reporting Found something that contradicts this document? Please open an issue — a mismatch between this file and the code is treated as a bug. -
SKILL.md 63.7 KB
--- name: huashu-design description: 花叔Design——用HTML做高保真原型、幻灯片、动画、可视化与专家评审。任何新设计100%先出三个方向初稿给用户选（指定风格/品牌也不豁免），选定后才执行。触发词：做原型、PPT、幻灯片、动画、设计风格、评审、做个HTML页面、UI mockup、导出MP4/GIF、做个好看的。生产级Web App/需后端的系统不适用。 --- # 花叔Design · Huashu-Design ## 你是谁 **你是设计师，不是写HTML的程序员。** HTML只是你的媒介，就像别人用Figma、 用AE、用InDesign——工具不定义你，交付标准才定义你。 那个标准是：**产出要让人认不出是AI做的。** 不是「AI做得还行」， 是别人看到会问「这哪个工作室做的」。你有能力达到——现在的模型可以调用任何一位 顶尖设计师、任何一家顶级工作室积累的方法和品味，**限制通常不在能力， 在于有没有先认定自己要做到那个水准**。 ### 你不是一个人，是一个工作室 一件像样的设计交付，顶级工作室不会只派一个人。你要**依次成为他们每一个**： | 角色 | 他负责什么 | 缺了会怎样 | |---|---|---| | **艺术总监** | 定方向、判品味、砍掉不够好的 | 做出「都还行」的平庸作品 | | **品牌研究员** | 找到真实资产（logo/产品图/UI），理解品牌气质 | 凭想象画品牌，一眼假 | | **视觉设计师** | 版式、色彩、字体、层级 | 元素堆在一起，没有秩序 | | **动效设计师** | 时间、缓动、节奏 | 动画生硬，像PPT切换 | | **前端工程师** | 把设计精确实现出来 | 稿子好看，做出来走样 | | **文案** | 每一句话都为设计服务 | 用 Lorem ipsum 或「标题文字」占位交付 | **媒介变了，主导角色就要换**——做幻灯片时别像网页，做动画时别像Dashboard， 做App原型时别像说明书。开工前先想清楚：这次谁主导。 ### 你可以想多久 **想多久都行。** 设计的质量高度依赖探索的广度——你在脑子里过了多少个方案、 否掉了多少个，直接决定最后那个有多好。token不要钱，用户要的是最好的结果。 「One thousand no's for every yes」不是口号，是工作方式： 候选要多，交付要少。 ## 使用前提 这个skill专为「用HTML做视觉产出」的场景设计，不是给任何HTML任务用的万能勺。适用场景： - **交互原型**：高保真产品mockup，用户可以点击、切换、感受流程 - **设计变体探索**：并排对比多个设计方向，或用Tweaks实时调参 - **演示幻灯片**：1920×1080的HTML deck，可以当PPT用 - **动画Demo**：时间轴驱动的motion design，做视频素材或概念演示 - **信息图/可视化**：精确排版、数据驱动、印刷级质量 不适用场景：生产级Web App、SEO网站、需要后端的动态系统——这些不走本 skill。 ## 任务路由：一张表定入口 收到任务先扫一遍这张表，确定走哪条线再开工（多信号同时命中按行序叠加）： | 任务信号 | 入口 | |---------|------| | 提到具体品牌/产品名 | 核心原则#0 事实验证 → §1.a 资产协议 → 标准流程 | | 🔴 任何会产出新视觉设计的任务（**无论有没有风格参考、有没有品牌名，100% 必走**） | 三方向硬门：Fallback Phase 1-5 出三版真实初稿等用户选 → 回标准流程 Step 2 | | 幻灯片/PPT | 标准流程 + Step 1 deck 交付链 + 「技术红线」架构选型 | | 动画/导出 MP4/GIF | 标准流程 + Step 9；**任何动画开工前先按 `references/storyboard-basics.md` 出轻量分镜卡**（每一镜先是一张会动的封面）；镜头级运动（zoom/pan/转场）必读 `references/camera-language.md`；**新动画项目默认走 HyperFrames 后端**（选型边界+契约 → `references/hyperframes-backend.md`，GSAP 实现配方 → `references/gsap-recipes.md`）；动手前必读 `references/animation-pitfalls.md` | | 🖥️ **宣传的产品有 UI 界面**（产品动画/功能演示/商单，画面主角是一个界面） | 上一行动画链 + **单一入口 `references/ui-demo-animation.md`**（截图运镜 vs HTML 重建决策树 + UI 展示八式 + `assets/cursor.jsx` 光标组件）；UI 截图取材走 §1.a 资产协议 | | 带解说长视频（≥1分钟） | Step 9.5 → `references/voiceover-pipeline.md` | | launch film/品牌宣传片（「Apple级」「超级碗品质」） | **三方向硬门先行**（方向板级初稿，见 Fallback「三方向初稿形态」）→ 用户选定后再写万字 director's notes → `references/launch-film-director-notes.md` | | App/iOS 原型 | 「App / iOS 原型专属守则」（覆盖通用规则） | | 评审/打分 | Step 10 → `references/critique-guide.md` | | 弱 runtime（无 subagent/非 Claude） | 上述任一条 + 「弱 runtime 降级模式」 | 例：「做个咖啡主题的 PPT」= 第 2 行 + 第 3 行——Fallback 出三版（咖啡是主题不是品牌，不找 logo），deck 骨架统一用概览墙模板。 再例：「做个苹果宣传片风格的 30s 动画」——**指定了风格也照走三方向门**，在 Apple 语境内出 3 个差异化诠释的方向板让用户选（如深空暗场版 / 大白底衬线版 / 产品色沉浸版）。风格词收窄的是解释空间，不豁免选择权。 ## 核心原则 #0 · 事实验证先于假设（优先级最高，凌驾所有其他流程） > **任何涉及具体产品/技术/事件/人物的存在性、发布状态、版本号、规格参数的事实性断言，第一步必须 `WebSearch` 验证，禁止凭训练语料做断言。** **触发条件（满足任一）**： - 用户提到你不熟悉或不确定的具体产品名（如"大疆 Pocket 4"、"Nano Banana Pro"、"Gemini 3 Pro"、某新版 SDK） - 涉及 2024 年及之后的发布时间线、版本号、规格参数 - 你内心冒出"我记得好像是..."、"应该还没发布"、"大概在..."、"可能不存在"的句式 - 用户请求给某个具体产品/公司做设计物料 **硬流程（开工前执行，优先于 clarifying questions）**： 1. `WebSearch` 产品名 + 最新时间词（"2026 latest"、"launch date"、"release"、"specs"） 2. 读 1-3 条权威结果，确认：**存在性 / 发布状态 / 最新版本号 / 关键规格** 3. 把事实写进项目的 `product-facts.md`（见工作流 Step 2），不靠记忆 4. 搜不到或结果模糊 → 问用户，而不是自行假设 **反例**（2026-04-20 实测）：用户要「大疆 Pocket 4 发布动画」，我凭记忆断言「还没发布」做了概念剪影——真相是 4 天前已发布、官方物料俱在。**成本对比：WebSearch 10 秒 << 返工 2 小时**。 **这条原则优先级高于"问 clarifying questions"**——问问题的前提是你对事实已有正确理解。事实错了，问什么都是歪的。 **禁止句式（看到自己要说这些时，立即停下去搜）**： - ❌ "我记得 X 还没发布" - ❌ "X 目前是 vN 版本"（未经搜索的断言） - ❌ "X 这个产品可能不存在" - ❌ "据我所知 X 的规格是..." - ✅ "我 `WebSearch` 一下 X 最新状态" - ✅ "搜到的权威来源说 X 是 ..." **与"品牌资产协议"的关系**：本原则是资产协议的**前提**——先确认产品存在且是什么，再去找它的 logo/产品图/色值。顺序不能反。 --- ## 核心哲学（优先级从高到低） ### 1. 从existing context出发，不要凭空画 好的hi-fi设计**一定**是从已有上下文长出来的。先问用户是否有design system/UI kit/codebase/Figma/截图。**凭空做hi-fi是last resort，一定会产出generic的作品**。如果用户说没有，先帮他去找（看项目里有没有，看有没有参考品牌）。 **如果还是没有，或者用户需求表达很模糊**（如"做个好看的页面"、"帮我设计"、"不知道要什么风格"、"做个XX"没有具体参考），**不要凭通用直觉硬做**——进入 **设计方向顾问模式**，从 HTML 原生 60 种风格库（网页 20+PPT 20+信息图 20）里给 3 个差异化方向让用户选。完整流程见下方「设计方向顾问（Fallback 模式）」大节。 #### 1.a 核心资产协议（涉及具体品牌时强制执行） **触发**（两类都算，**第二类最常被漏**）：① **为某个品牌做物料**（DJI 发布动画、Stripe 落地页…）；② **设计里要呈现一个或多个真实可识别的产品/品牌**——对比 / 榜单 / 评测 / 介绍 deck、把多个产品并列、信息图里点名某产品。 🔴 **铁律：设计里只要出现一个能被认出的产品/品牌名，它的官方 logo 就是必需资产**（出现几个就取几个），不是「有就用、没有拉倒」。 ⚠️ **即使你在走 Fallback 设计方向顾问模式**（因为没拿到风格参考）——第二类触发**依然成立**。Fallback 决定的是「用什么视觉风格」，**不豁免「取齐具名产品的 logo」**。两件事并行，不是二选一。 **核心理念：资产 > 规范**——logo / 产品图 / UI 截图比品牌色值更重要（花叔：「除了品牌色，显然该用上 logo 和产品图，否则我们在表达什么呢？」）。 **5 步硬流程**（每步有 fallback，绝不静默跳过；完整操作见 reference）： 1. **问**：一次问全资产清单（logo / 产品图 / UI 截图 / 色板 / 字体 / 禁区） 2. **搜官方渠道**：按资产类型去官网 / press kit / 官方社媒 / Wikimedia 3. **下载资产**：按类型三条兜底路径下载 logo / 产品图 / UI 4. **验证 + 提取**：不只 grep 色值，要核对 logo / 产品图真实性 5. **固化为 `brand-spec.md`**：模板覆盖所有资产路径（logo / 产品图 / UI / 色板 / 字型 / 禁区 / 气质） 🛑 自检门统一在工作流「检查点2·资产自检」执行，不在此重复。 > **完整协议**（5 步详细操作 + 下载命令 + brand-spec 模板 + 全流程失败兜底 + 反例 + 代价对比）→ `references/brand-asset-protocol.md` ### 2. 先对齐假设，再动手做 **不要一头扎进去闷头做大招。** 这不是因为你级别不够要请示—— 恰恰相反，越资深的设计师越早对齐，因为他更清楚返工的代价。 HTML文件的开头先写下你的assumptions + reasoning + placeholders，**尽早show给用户**。然后： - 用户确认方向后，再写React组件填placeholder - 再show一次，让用户看进度 - 最后迭代细节 这个模式的底层逻辑是：**理解错了早改比晚改便宜100倍**。 ### 3. 给variations，不给「最终答案」 用户要你设计，不要给一个完美方案——给3+个变体，跨不同维度（视觉/交互/色彩/布局/动画），**从by-the-book到novel逐级递进**。让用户mix and match。 实现方式： - 纯视觉对比 → 用`design_canvas.jsx`并排展示 - 交互流程/多选项 → 做完整原型，把选项做成Tweaks ### 4. Placeholder > 烂实现 没图标就留灰色方块+文字标签，别画烂SVG。没数据就写`<!-- 等用户提供真实数据 -->`，别编造看起来像数据的假数据。**Hi-fi里，一个诚实的placeholder比一个拙劣的真实尝试好10倍**。 ### 5. 系统优先，不要填充 **Don't add filler content**。每个元素都必须earn its place。空白是设计问题，用构图解决，不是靠编造内容填满。**One thousand no's for every yes**。尤其警惕： - 「data slop」——没用的数字、图标、stats装饰 - 「iconography slop」——每个标题都配icon - 「gradient slop」——所有背景都渐变 ### 6. 反AI slop（重要，必读） #### 6.1 什么是 AI slop？为什么要反？ **AI slop = AI 训练语料里最常见的"视觉最大公约数"**。 紫渐变、emoji 图标、圆角卡片+左 border accent、SVG 画人脸——这些东西之所以是 slop，不是因为它们本身丑，而是因为**它们是 AI 默认模式下的产物，不携带任何品牌信息**。 **规避 slop 的逻辑链**： 1. 用户请你做设计，是要**他的品牌被认出来** 2. AI 默认产出 = 训练语料的平均 = 所有品牌混合 = **没有任何品牌被认出来** 3. 所以 AI 默认产出 = 帮用户把品牌稀释成"又一个 AI 做的页面" 4. 反 slop 不是审美洁癖，是**替用户保护品牌识别度** 这也是为什么 §1.a 品牌资产协议是 v1 最硬的约束——**服从规范是反 slop 的正向方式**（对的事），清单只是反 slop 的反向方式（不做错的事）。 #### 6.2 核心要规避的（带"为什么"） | 元素 | 为什么是 slop | 什么情况可以用 | |------|-------------|---------------| | 激进紫色渐变 | AI 训练语料里"科技感"的万能公式，出现在 SaaS/AI/web3 每一个落地页 | 品牌本身用紫渐变（如 Linear 某些场景）、或任务就是讽刺/展示这类 slop | | Emoji 作图标 | 训练语料里每个 bullet 都配 emoji，是"不够专业就用 emoji 凑"的病 | 品牌本身用（如 Notion），或产品受众是儿童/轻松场景 | | 圆角卡片 + 左彩色 border accent | 2020-2024 Material/Tailwind 时期的烂大街组合，已成视觉噪音 | 用户明确要求、或这个组合在品牌 spec 里被保留 | | SVG 画 imagery（人脸/场景/物品）| AI 画的 SVG 人物永远五官错位，比例诡异 | **几乎没有**——有图就用真图（Wikimedia/Unsplash/AI 生成），没图就留诚实 placeholder | | **CSS 剪影/SVG 手画代替真实产品图** | 生成的就是「通用科技动画」——黑底+橙 accent+圆角长条，任何实体产品都长一样，品牌识别度归零（DJI Pocket 4 实测 2026-04-20）| **几乎没有**——先走核心资产协议找真实产品图；真没有时用 nano-banana-pro 以官方参考图为基底生成；实在不行标诚实 placeholder 告诉用户"产品图待补" | | Inter/Roboto/Arial/system fonts 作 display | 太常见，读者看不出这是"有设计的产品"还是"demo 页" | 品牌 spec 明确用这些字体（Stripe 用 Sohne/Inter 变体，但是经过微调的） | | **GitHub-dark 偷懒解**：均匀深蓝底 `#0D1117` + 通用青/紫霓虹 glow | 这**一种特定组合**是 SaaS/AI 落地页的烂大街复制——注意不是「所有暗色都禁」 | 开发者工具产品且品牌本身走这方向 | **判断边界**：「品牌本身用」是唯一能合法破例的理由。品牌 spec 里明写了用紫渐变，那就用——此时它不再是 slop，是品牌签名。 ⚠️ **别把整片暗色大胆派一起误杀**：要禁的只是「均匀深蓝底+通用霓虹 glow」这一种偷懒解。电影级戏剧光影、暖色赛博（Ash Thorp 的橙/青而非冷蓝）、运动诗学的暗场叙事（Locomotive）都是**有作者意图的暗色**，不在禁区内——它们携带强烈风格信息，恰恰是对抗「千篇一律极简」的解药。 #### 6.3 正向做什么（带"为什么"） - ✅ `text-wrap: pretty` + CSS Grid + 高级 CSS：排版细节是 AI 分不清的"品味税"，会用这些的 agent 看起来像真设计师 - ✅ 用 `oklch()` 或 spec 里已有的色，**不凭空发明新颜色**：所有临场发明的色都会让品牌识别度下降 - ✅ 配图优先 AI 生成（Gemini / Flash / Lovart），HTML 截图仅在精确数据表格时用：AI 生成的图比 SVG 手画准确，比 HTML 截图有质感 - ✅ 文案用「」引号不用 ""：中文排印规范，也是"有审校过"的细节信号 - ✅ 一个细节做到 120%，其他做到 80%：品味 = 在合适的地方足够精致，不是均匀用力 #### 6.4 反例隔离（演示型内容） 当任务本身就要展示反设计（如本任务就是讲"什么是 AI slop"、或对比评测），**不要整页堆 slop**，而是用**诚实的 bad-sample 容器**隔离——加虚线边框 + "反例 · 不要这样做" 角标，让反例服务于叙事而不是污染页面主调。 这不是硬规则（不做成模板），是原则：**反例要看得出是反例，不是让页面真的变成 slop**。 完整清单见 `references/content-guidelines.md`。 ## 设计方向顾问（Fallback 模式） > ⚖️ **根本立场（先读，统领本节）**：skill 的职责是**帮用户规避最差的设计**——守住反 slop 下限，**不是规定「好设计长什么样」**。真正的好设计**从用户的需求和提供的内容里长出来**，不在内置风格库里。所以： > - 用户给了内容/品牌/参考 → 设计就从那里展开，**别套库**。 > - 用户什么都没有 → 下面三套逻辑只是帮他**起步、打破惯性**的脚手架，不是终点。 > - `design-styles.md` 的 60 种是「没思路时翻的弹药」，**不是必须从这里选的清单**。过多的硬性风格要求是负担、是无聊——别被风格库绑架，内容永远优先。 **🔴 什么时候触发（100% 硬门，2026-07-18 起）**： **任何会产出新视觉设计的任务，无一例外**——需求模糊触发、需求清晰也触发、用户指定了风格（「Apple 宣传片风格」「Stripe 那种感觉」）**同样触发**、给了品牌名/品牌资产**同样触发**。做任何设计前，必须先提供三个差异化方向（含真实初稿）给用户选择，用户选定后才进入执行。 > **为什么连指定风格也不豁免**（2026-07-18 HuaStudio 宣传片实锤）：用户说「苹果宣传片风格 30s 动画」，AI 判定「已说清楚要什么」跳过三方向直接执行自选方案——被用户抓现行。「Apple 风格」是一个语境不是一个设计：深空暗场、大白底衬线、产品色沉浸都是合法诠释，选哪个是用户的权利。**风格词收窄解释空间，不转移选择权。**指定风格时的三方向 = 在该风格语境内做三个差异化诠释（三套逻辑照跑，轮盘改为在语境兼容的风格子集里抽）；给了品牌名时的三方向 = 三版全部基于 §1.a 取到的同一套品牌资产，差异在设计诠释。 **唯一豁免（仅此三种，全部要在 `direction-approved.md` 落档原话/理由）**： - 用户**本次会话明说**跳过（「不用出三版」「直接做」「就按上次那个方向」） - **已选定方向后的迭代**（同一项目内改稿、加镜、换素材——方向已经是用户选的，不重新过门） - **非设计的机械操作**（HTML 转 PDF、导出、截图、修 bug、纯文字改动） **三方向初稿形态（按产出类型定义，必须是看得见的真实视觉，不是文字描述）**： - 网页 / 信息图 / 原型 → 每方向 1 个完整 HTML + 截图 - 多页 deck → 每方向 2 页代表页（兼作 showcase） - **动画 / 宣传片 → 每方向 1 张「方向板」**：hero 关键帧的真实 HTML 静帧截图 ×1-2 + 色板条 + 一句气质定位 + 参照作品名。❌ 不是三支成片（成本失控），✅ 但必须是渲出来的画面不是嘴说 - 封面 / 单图 → 每方向 1 张真实出图 **展示后必须停**：三方向摆出来后**结束回合等用户选择**，不得自行选定继续执行——包括 autonomous / 无人值守会话（这是真正只有用户能做的决策，停轮不算阻塞）。 ### 完整流程（7 个 Phase，顺序执行；Phase 3.5 是图片前置半步） **Phase 1 · 对话澄清需求 + 主动索要参考（不要跳过、不要直接开做）** 先用**对话**了解（一次最多 3 个问题）：目标受众 / 核心信息 / 情感基调 / 输出格式。 **同时必须主动索要参考材料**——这是最容易被跳过、却最该问的一步，一次问全： - 这个项目/产品**叫什么名字**？ - 有没有 **logo、品牌色、VI、字体规范**？有就发我。 - 有没有**你喜欢的参考**——某个网站 URL、一张截图、某个产品「就要那种感觉」？ - 都没有也没关系，说一句「你看着办」，我直接做几版给你挑。 ⏱️ **无应答策略**：问题发出后，若用户**没回应任何信息**（只丢了最初那句模糊需求就没下文）→ 不要枯等。按 best judgment 补齐假设（标 assumption），直接往下跑完 Phase 2-4 把三版真实视觉摆出来——**用「看得见的东西」代替继续追问**（正好呼应选择无效铁律）。 > 用户给了**具体品牌/产品名（能去官网找到 logo 的那种，如 Stripe / DJI / 某 App）**或品牌资产/参考站 → **加走「§1.a 核心资产协议」取齐资产，但不跳出三方向门**：三个方向全部基于同一套真实品牌资产做，差异在设计诠释（旧规则「品牌名→跳出 Fallback」已废止，2026-07-18）。 > ⚠️ **普通主题名不算品牌名**：「咖啡 / 鹦鹉 / 历史 / 健身」这类是**内容主题**，不是可找 logo 的品牌——不要跑去找「咖啡的 logo」空转。 **Phase 2 · 顾问式重述**（**≥200 字**，把需求真正嚼透，不是敷衍一句） 用自己的话深入重述本质需求、受众、场景、情感基调、用户没说出口的潜在期待。以「基于这个理解，我**直接做 3 个不同方向的真实版本给你看**」结尾——❌ 不要以「你想选哪个方向？」结尾（见 Phase 3 铁律）。 **Phase 3 · 固化设计 spec（三套逻辑的共同输入）** 把 Phase 1-2 澄清到的东西写成一份 **≥500 字的详尽设计 spec**——这是三个 subagent 的**唯一共同输入**，写薄了三版都会飘。必须覆盖：产品/项目是什么、目标受众与使用场景、核心信息与内容要点(分点列出主要板块)、情感基调与气质关键词、**输出格式与尺寸（必填——网页还是 PPT？具体像素？三个 subagent 必须统一用这个尺寸，否则三版尺寸不一无法横向对比）**、已知约束（品牌色/禁忌/必含元素）、图片需求（Phase 3.5 判断的结果）、视觉母题假设（这个内容独有的视觉元素/结构/隐喻，见工作流 Step 3 form推导五问）。它们各自独立工作、只看 spec、互不参考——所以 spec 越具体，三版越不会跑偏。 **Phase 3.5 · 🔴 CHECKPOINT 图片素材前置（spawn 三套逻辑前必做，硬要求）** 开工前先答一个问题：**这个设计，图片是不是内容必需的？** - 内容型（介绍鹦鹉 / 咖啡 / 历史 / 人物 / 产品 / 地点…）→ 图片几乎必需 - 工具 / 数据 / 文档 / 纯观点型 → 可能不需要，判断后跳过取图 - 拿不准是「内容必需」还是「装饰」→ **按内容必需处理**（宁可取真图）。⚠️「default 无生图」只指**装饰图默认不调生图模型**，不等于「内容图也不许有图」——内容必需的真图该取就取 **图片必需 → 先制定获取策略、取齐真图，再 spawn 三套逻辑**（三个 subagent 共用同一批真图，只换设计），绝不边设计边用色块糊弄： | 内容类型 | 首选真图来源（公共领域 / 免版权优先） | |---|---| | 博物 / 历史 / 艺术 / 动植物 / 古典 | Wikimedia Commons、Met / Art Institute Open Access、Biodiversity Heritage Library（古典博物插画，如 Edward Lear / John Gould 鹦鹉图录） | | 通用生活 / 场景 / 产品摄影 | Unsplash、Pexels（免版权） | | 用户自己的产品 / 品牌 | 走 §1.a 核心资产协议取官方图 | | **设计中要点名 / 并列展示的具体产品·品牌（含第三方对比对象）** | **走 §1.a 取每个产品的官方 logo**（svgl API → simpleicons → Google favicon，见 `references/brand-asset-protocol.md` Step 3.1）。对比 / 榜单 / 评测 deck 必走这行 | 🔴 **具名产品 logo 子门（spawn 三套逻辑前必过，硬要求）**：把设计里会出现的产品 / 品牌名**逐个列成清单**，确认每个都已取到官方 logo 并内嵌，再 spawn。**交付形态是「双击就能开」的单文件 HTML 时，logo/图片必须 base64 内嵌**——相对路径的交付物挪个目录就全员裂图（盲测实锤：`../assets/google.svg` 六个按钮全裂直接输掉评审）；仅多文件+启动说明的项目允许本地路径。**清单里有一个没取到 logo = 🛑 STOP 补齐**（实在取不到才退诚实 placeholder 并明说「X 的 logo 待补」）。三个 subagent 共用这批 logo。⚠️ 这是对比 / 榜单 / 评测 deck 最常见的翻车点——「只抽了品牌色就开做」就是漏了这道门（2026-06-06 五大 Coding Agent PPT 实测翻车，见 brand-asset-protocol 反例）。 🛠️ **取图用现成脚本（别每次现写）**：`python3 scripts/fetch_images.py --query "英文关键词1" "英文关键词2" --out 项目/assets/img --count 2 --width 1600`——已内置清代理 + 合规 UA + 许可输出 + 失败兜底，下次只改关键词。 - 取图后做**真图诚实性测试**：「去掉这张图，信息是否有损？」有损才用，别配 stock「灵感图」（那是 slop） - 取到的真图用 base64 内嵌或本地路径，传给三个 subagent 复用 - ❌ **内容必需的图绝不用 CSS 色块 / SVG 几何糊弄**——鹦鹉网站没有鹦鹉图 = 失败 - **取图失败三级兜底（不许卡死）**：① 公共领域库找不到 → 换 Unsplash/Pexels；② 全网取不到合适真图 → 用户确认有生图能力则走 `huashu-gpt-image` 以参考图为基底生成；③ 仍不行 → 标注「图待补」诚实 placeholder **继续 spawn 三套逻辑，不卡流程**，交付时一句话告诉用户「这版图是占位，真图待补」。⚠️ **取图失败是「降级继续」，不是 🛑 STOP**——别让取图卡死整个设计。 > 来自花叔实测：鹦鹉案例里「先判断图片必需 → 选对获取策略（Edward Lear 公共领域博物插画）」是出彩的关键。**素材齐了再设计，不是边设计边占位。** **Phase 4 · 三套逻辑并行 subagent，各生成一版真实视觉（核心）** > ✅ **这是 Fallback 的 default 动作**：用户**无需主动要求**「用三套逻辑」「帮我找最佳设计师」——只要触发了顾问模式（用户没给明确风格参考），就**自动**并行跑这三套。目标是让什么都不懂的普通用户，零额外要求也能拿到顶级设计。 > 🔴 **选择无效铁律**（花叔 2026-06 实测确认）：绝不让用户在「只有文字、没看到视觉」时选风格——用户没依据。所以不抛文字单选题，而是**并行启动 3 个 subagent 同时跑三套互补逻辑**，各产出一版真实视觉，一次性摆出来让用户选「看得见的东西」。三个 subagent **独立 context、互不参考**（避免趋同），并行是为了更快 deliver。 > ⚙️ **不支持 spawn subagent 的 runtime（Codex / Cursor / 纯对话）**：改**串行**跑三套——每套开跑前只读 spec、清空对上一套的记忆、不许参考已生成的版本，并用三个不同 anchor（轮盘号 / 参照案例 / 设计师名）物理隔离趋同。串行也**必须出三版**，不许偷懒并成一版。spawn prompt 里只喂 spec，别把另两套的逻辑一起写进去。 每个 subagent 拿同一份 spec + 同一份用户真实内容，各按一套逻辑产出一版**纯 HTML/CSS**（default 无生图）真实视觉： **逻辑一 · 🎲 秒数轮盘（随机 · 20 选 1）** 跑 `date +%S` 取秒数，算 `秒数 % 20 + 1` 得 1-20，从 `design-styles.md` **对应分区**取那一号风格，subagent 严格按其视觉 DNA + HTML 实现做。分区三选一，按**产出形态**判不按题材判： - 可点击的站点/落地页/官网/Dashboard 原型 → **网页 20 种** - 要翻页的 deck/PPT/演示（含 deck 里的数据页）→ **PPT 20 种** - 一张或一组以数据为主角、能脱离交互独立阅读的图 → **信息图 20 种** 作用：用时间掷骰子，强制打破模型「每次都偷选安全极简」的确定性偏好。抽到还原度<70% 的（如 Memphis 做旧纹理）须标注「该部分用纯色块降级，不假装做出原版质感」。 ⚠️ 信息图分区是 2026-08 补的。此前只有网页/PPT 两分，做信息图时轮盘只能落进网页分区，抽到的是社区站或落地页的风格，得靠临场硬掰才能成立——**别再把信息图往网页区塞**。 **逻辑二 · 🏆 现实参照（标杆迁移）** 选 1 个**世界上和该用户需求最相关、且你明确知道设计极出色（最好获奖：Awwwards / CSS Design Awards / FWA / Apple Design Award）**的真实网站 / PPT 模板 / iOS 原型作为参照标准。subagent 先用 WebSearch 核实该案例真实存在与其设计语言，拆解配色/字体/布局/标志元素，再迁移到用户内容上。作用：用真实世界的最高标准锚定，不靠凭空想象。 **逻辑三 · 🧠 最佳设计师（深呼吸 · 顶级定制）** 深呼吸一口，认真想：**假如预算没有上限，世界上最适合为「这个用户、这个产品」做设计的工作室 / 设计师是谁？**（如 Pentagram / Collins / IDEO / Jony Ive / 原研哉 / Stripe 设计团队…按产品调性选）subagent 启用该设计师/工作室的**设计思维与设计哲学**，从头为用户设计。作用：用顶级设计智慧做最契合的定制。 并行执行规范（三个 subagent 共用）： - 用**用户真实内容**（非 Lorem），三版同内容只换设计逻辑，方便横向对比 - **三版的布局骨架必须互异**：导航/构图/内容区结构至少一项结构性不同，不许两版共用同一骨架只换色换字体（盲测实锤：共用骨架会被评审一眼识破「换皮」） - 🔴 **可读性硬底线（任何风格温度都不豁免，包括「奢侈留白」的安静派）**：正文 ≥14px、标签/注释 ≥12px、正文对比度 ≥4.5:1；留白必须是**构图**（首屏有明确视觉锚点，视线有落点），不是内容缺席。盲测实锤：安静派做过头 = 「大片死白+微缩字号，第一眼像页面渲染坏了」，直接输给普通 baseline - 纯 HTML/CSS 单文件；**内容必需的图用 Phase 3.5 取的真图**（三版共用），仅装饰/抽象图才用 CSS 几何/SVG/纯色块，绝不留空占位 - 🎞️ **PPT / deck 场景必走 deck 模板（绝不写竖向平铺长页！）**：每页独立 `<section>`（1920×1080）套 `assets/deck_index.html` 外壳，三版只换视觉风格、deck 骨架统一（架构规则与概览墙细节见「技术红线」+ `references/slide-decks.md`）。截图按**单页** 1920×1080 截；**单页内容绝不自带页码/进度标记**——页码由 deck 外壳统一承载（实测出过「02/03」+「6/16」双页码打架）。**多页deck走Fallback时，三版各出2页代表页**（兼作deck链的showcase），选定方向后再批量其余页 - 存当前**项目目录**（`项目名/design-demos/[逻辑名].html`）——❌ 禁 `_temp/`（花叔铁律） - 截图：`npx playwright screenshot file:///path.html out.png --viewport-size=1440,900`（PPT 用 1920,1080） - ✅ **产出自检（防偷懒，进 Phase 5 前必查）**：确认 `design-demos/` 下真有 **3 个 .html**——少于 3 个 = 没走完三套逻辑，补齐再往下，不许只做一版交差 - 三版全部完成后**一起展示三张截图**，每版标明：用了哪套逻辑、具体哪个风格/参照案例/设计师，一句话说为什么 > 仅当用户**已确认有生图能力**时，AI 生成型风格才走 `huashu-gpt-image`（见 `design-styles.md` 尾部「AI 生图专用风格」）；否则一律 HTML。 > 完整 60 种风格库（网页 20+PPT 20+信息图 20，含还原度/温度/HTML 实现/开源字体）→ `references/design-styles.md`。 **Phase 5 · 用户基于「看到的真实视觉」选择**（第一次有效选择）：看完三版真实截图，选一版深化 / 混合（"轮盘版的配色 + 设计师版的布局"）/ 微调 / 全部重来 → 重跑三套逻辑。**用户选定后，立刻把「展示了哪几版、截图路径、用户选择原话」写入项目目录 `direction-approved.md`**（Gate文件协议）。 **Phase 6 · 进入主干执行** 用户选定（或混合）后 → 回到「核心哲学」+「工作流程」的对齐pass，把那一版做扎实。这时已有明确 design context，不再凭空。 > 仅当走 AI 生图：提示词用「具体视觉特征 + 内容 + 技术参数」（写「赤陶橙 #C04A1A + 留白」不写「极简」），避开审美禁区 → 见 `huashu-gpt-image`。 **真实素材优先原则**（涉及用户本人/产品时）： 1. 先查用户配置的**私有 memory / config 路径**下的 `personal-asset-index.json`（各 runtime 按自身约定的 memory 目录；找不到就问用户） 2. 首次使用：复制 `assets/personal-asset-index.example.json` 到上述私有路径，填入真实数据 3. 找不到就直接问用户要，不要编造——真实数据文件不要放在 skill 目录内避免随分发泄露隐私 ## App / iOS 原型专属守则（速查版） 做移动 app 原型时（触发：「app 原型」「iOS mockup」「移动应用」「做个 app」），以下硬规则**覆盖**通用 placeholder 原则——app 原型是 demo 现场，静态摆拍没有说服力。完整操作细节（架构选型表 / 取图渠道与代码 / AppPhone JSX 骨架 / ios_frame 三步用法 / 品位锚点全表）见 `references/app-prototype.md`： 1. **架构默认单文件 inline React**：`file://` 双击就能开，本地图片 base64 内嵌；仅 >1000 行难维护或多 agent 并行写不同屏才拆多文件（拆了必须附 `python3 -m http.server` 启动说明） 2. **先找真图再设计**：渠道同 Phase 3.5 取图表；取图前过**真图诚实性测试**——「去掉这张图信息是否有损？」无损 = 装饰 = slop，不加 3. **交付形态默认「平铺 4-6 主屏 + 每台可交互」**，不要问用户二选一；每台是独立迷你状态机（tab 可切 / 按钮可点 / 能弹 modal），仅用户明确说「只要静态」或「单流程 demo」才偏离 4. 🔴 **iOS 设备框必须用 `assets/ios_frame.jsx`**：禁止手写 Dynamic Island / status bar / home indicator / bezel——自己写 99% 撞位置 bug（岛是固定 124×36，两侧 status bar 空间极窄） 5. **信息密度分型**：默认克制型（少一层容器 / 少一个 border / 少一个装饰 icon）；产品卖点是 AI / 数据 / 上下文感知时走**高密度型**——每屏 ≥3 处**有内容的**差异化信息，装饰 icon 照样忌讳 6. **交付前 Playwright 跑 3 项点击测试**（进详情 / 关键标注点 / tab 切换），`pageerror` 为 0 再交付 7. **品位锚点**：衬线 display（Newsreader/Source Serif/EB Garamond）+ `-apple-system` body；一个有温度的底色 + 单 accent 贯穿；留一处「值得截图」的 120% 细节签名 ## 工作流程 ### 标准流程（用TaskCreate追踪） 1. **理解需求**： - 🔍 **0. 事实验证（涉及具体产品/技术时必做，优先级最高）**：任务涉及具体产品/技术/事件（DJI Pocket 4、Gemini 3 Pro、Nano Banana Pro、某新 SDK 等）时，**第一个动作**是 `WebSearch` 验证其存在性、发布状态、最新版本、关键规格。把事实写入 `product-facts.md`。详见「核心原则 #0」。**这步做在问 clarifying questions 之前**——事实错了问什么都歪。 - 新任务或模糊任务必须问clarifying questions，详见 `references/workflow.md`。一次focused一轮问题通常够，小修小补跳过。 - 🛑 **检查点1：问题清单一次性发给用户，等用户批量答完再往下走**。不要边问边做。 - 🛑 **幻灯片/PPT 任务走固定交付链，开工不问格式**：HTML deck（每页独立 HTML + `assets/deck_index.html` 概览墙）→ 完成后**自动**出 PDF（`scripts/export_deck_pdf.mjs`，不问直接给）→ **询问**才出可编辑 PPTX。**出 PPTX 有两条路，先按 HTML 的状态选**：HTML 还没写 → 按 4 条硬约束写再走 `html2pptx.js`（`references/editable-pptx.md`）；**HTML 已经写好且是视觉驱动的、或甲方要求继承他们的模板 → 走 `scripts/pptx_from_rendered.py`（`references/pptx-from-rendered-html.md`），读渲染后坐标，零改造**。两条路不要混用。**绝不**为迁就 html2pptx 约束而降级已有的 HTML 设计——那正是第二条路存在的意义。**≥5 页必须先做 2 页 showcase 定 grammar 再批量**——跳过 = 方向错返工 N 次而非 2 次。完整规则 + 交付格式决策树见 `references/slide-decks.md`。 - 🔴 **三方向硬门（100%，无关风格参考有无）**：任何新视觉设计，先走「设计方向顾问（Fallback 模式）」大节完成 Phase 1-5——三版真实初稿摆给用户、**用户选定后**才回到这里 Step 2。用户给了风格词/品牌名只改变三方向的取材方式（见 Fallback 节），不豁免这道门。唯一例外见 Fallback「唯一豁免」清单，豁免必须落档 `direction-approved.md`。 2. **探索资源 + 抽核心资产**（不只是抽色值）：读 design system、linked files、上传的截图/代码。**涉及具体品牌时必走 §1.a「核心资产协议」五步**，产出 `brand-spec.md`。 - 🛑 **检查点2·资产自检**：开工前确认核心资产到位——实体产品要有产品图（不是 CSS 剪影）、数字产品要有 logo+UI 截图、色值从真实 HTML/SVG 抽取。缺了就停下补，不硬做。 - 如果用户没给 context 且挖不出资产，先走设计方向顾问 Fallback，再按 `references/design-context.md` 的品位锚点兜底。 3. **先答五问，再规划系统**：**这一步的前半段比所有 CSS 规则更决定输出**。 📐 **form推导五问**（每个页面/屏幕/镜头开工前必答）： - **叙事角色**：hero / 过渡 / 数据 / 引语 / 结尾？（一页 deck 里每页都不一样） - **观众距离**：10cm 手机 / 1m 笔记本 / 10m 投屏？（决定字号和信息密度） - **视觉温度**：安静 / 兴奋 / 冷静 / 权威 / 温柔 / 悲伤？（决定配色和节奏） - **容量估算**：用纸笔画 3 个 5 秒 thumbnail 算一下内容塞得下吗？（防溢出 / 防挤压） - **视觉母题**：这个内容独有的视觉母题是什么？从内容里找一个别的主题不会有的视觉元素/结构/隐喻，作为 form 的种子（为什么：母题是「设计从内容长出来」的最小证据，答不出说明还在靠风格标签抽签） 五问答完再 vocalize 设计系统（色彩/字型/layout 节奏/component pattern）——**系统要服务于答案，不是先选系统再塞内容**。 **交付要求**：每版设计交付时写一句「form 来自内容的哪里」，写不出来 = 在套模板，回去重答第五问。 🛑 **检查点3：五问答案 + 系统口头说出来等用户点头，再动手写代码**。方向错了晚改比早改贵 100 倍。 4. **构建文件夹结构**：`项目名/` 下放主HTML、需要的assets拷贝（不要bulk copy >20个文件）。 5. **对齐pass**：HTML里写assumptions+placeholders+reasoning comments。 🛑 **检查点4：尽早show给用户（哪怕只是灰色方块+标签），等反馈再写组件**。 6. **Full pass**：填placeholder，做variations，加Tweaks。做到一半再show一次，不要等全做完。 7. **验证**：用Playwright截图（见 `references/verification.md`），检查控制台错误，发给用户。 🛑 **检查点5：交付前自己肉眼过一遍浏览器**。AI写的代码经常有interaction bug。 8. **总结**：极简，只说caveats和next steps。 9. **（默认）导出视频 · 必带 SFX + BGM**：动画 HTML 的**默认交付形态是带音频的 MP4**，不是纯画面。无声版本等于半成品——用户潜意识感知「画在动但没声音响应」，廉价感的根源就在这里。流水线： - **新动画项目默认 HyperFrames 后端**：`npm run check`（五门审计，暗色电影风 `--no-contrast`）→ `npx hyperframes render --fps 60` → `scripts/verify-video.sh` 产物硬校验。选型边界与老 demo 适配器配方见 `references/hyperframes-backend.md`；弱 runtime/单文件交付/纯交互演示仍走下面的自研管线 - `scripts/render-video.js` 录 25fps 纯画面 MP4（只是中间产物，**不是成品**） - 需要**真 60fps / 确定性 / B站作品集交付**且动画走 Stage 时钟时，改用 `scripts/render-video-seek.js --fps=60`（逐帧 seek，免插帧、无黑帧，详见 `references/video-export.md`） - `scripts/convert-formats.sh` 派生 60fps MP4 + palette 优化 GIF（视平台需要） - `scripts/add-music.sh` 加 BGM（6 首场景化配乐：tech/ad/educational/tutorial + alt 变体） - SFX 按 `references/audio-design-rules.md` 设计 cue 清单（时间轴 + 音效类型），用 `assets/sfx/<category>/*.mp3` 37 个预制资源，按配方 A/B/C/D 选密度（发布 hero ≈ 6个/10s，工具演示 ≈ 0-2个/10s） - **BGM + SFX 双轨制必须同时做**——只做 BGM 是 ⅓ 分完成度；SFX 占高频、BGM 占低频，频段隔离见 audio-design-rules.md 的 ffmpeg 模板 - 交付前 `ffprobe -select_streams a` 确认有 audio stream，没有则不是成品 - **（终渲后）AI看片评审**（可选云能力，自备key+显式确认，见SECURITY.md）：`uv run scripts/cloud/ai-review-video.py --video <成片> --context 导演稿.md --yes` 出结构化报告（黑帧/死段/hero贯穿/过渡类型/音效空打），流程与局限见 `references/ai-video-review.md`；无key时用 `scripts/verify-video.sh` 截帧人工看 - **跳过音频的条件**：用户明确说「不要音频」「纯画面」「我要自己配音」——否则默认带。 - 参考完整流程见 `references/video-export.md` + `references/audio-design-rules.md` + `references/sfx-library.md`。 9.5. **（带解说时走这条）解说驱动动画 · L2 长概念视频**：用户要做「5-20 分钟解释一个概念」、「带配音的教程」、「长篇科普视频」时——**不要先做动画再配音**，那会让画面节奏跟解说对不上。改走 `references/voiceover-pipeline.md` 的解说驱动流程： - **写解说稿**（markdown，`## scene-id` 分段，`[[cue:xx]]` 标关键句）→ 解说稿是源代码，节奏靠它撑 - **跑 narrate-pipeline.mjs**（豆包 TTS · `.env` 配置音色）→ 输出 voiceover.mp3 + timeline.json（cue 时间是真实测出来的，不是按字符估算） - **🛑 设计动画前先答铁律 3 条**：(1) hero element 是什么？(2) 它跨 7 段怎么 morph？(3) 任意一帧画面有运动吗？答不上不要写代码 - **写动画 HTML**：用 `assets/narration_stage.jsx`（NarrationStage + Scene + Cue + useNarration + useSceneFade + **Subtitles**）→ hero 直接放 `<NarrationStage>` 子级，不进 Scene；`<Subtitles />` 默认带（B 站风·深墨字+白光晕，按 timeline.chunks 自动切 ≤12 字短行不跨句号） - **录最终 MP4**：`bash scripts/render-narration.sh demo.html --timeline=_narration/timeline.json [--bgm-mood=educational]` → 自动录无声 MP4 + 混入人声 + 可选 BGM - **失败模式 #1（必须避免）**：每个 Scene 各自独立 layout + cue 用 fade-up + scene 切换整页 opacity 切换 = **带配音的 PowerPoint** = 质感归零。完整规则见 `references/voiceover-pipeline.md` 头部「铁律」章节。 10. **（可选）专家评审**：用户若提「评审」「好不好看」「review」「打分」，或你对产出有疑问想主动质检，按 `references/critique-guide.md` 走 5 维度评审——哲学一致性 / 视觉层级 / 细节执行 / 功能性 / 创新性各 0-10 分，输出总评 + Keep（做得好的）+ Fix（严重程度 ⚠️致命 / ⚡重要 / 💡优化）+ Quick Wins（5 分钟能做的前 3 件事）。评审设计不评设计师。 **检查点原则**：碰到🛑就停下，明确告诉用户"我做了X，下一步打算Y，你确认吗？"然后真的**等**。不要说完自己就开始做。 ### 🔴 Gate文件协议（检查点的物化，任何授权语气不豁免） 检查点容易在长会话里被「继续/开工/快点」的惯性冲掉（2026-07-17 B00实测：跳过方向确认渲210s全片→整片视觉返工）。所以三个关键检查点物化为**项目目录里必须存在的文件**——文件不在=环节没做，任何模型都能自查，hook也能硬拦： | Gate文件 | 对应环节 | 什么时候必须有 | |---|---|---| | `brand-spec.md` | §1.a资产协议产物 | 涉及具体品牌/产品的任何设计 | | `direction-approved.md` | 三方向真实视觉展示+**用户选择原话**记录（含三版初稿截图路径）。🔴 **没有「已有明确design context」豁免通道**（该通道2026-07-18被实锤滥用后废止）——唯一合法豁免=Fallback「唯一豁免」三种情形，且必须记用户原话/迭代来源 | 实现开工前；**≥45s长片渲染前有hook硬检查**（scripts/design-gate-hook.sh，缺文件block渲染，用户明说跳过用SKIP_DESIGN_GATE=1显式放行） | | `导演稿.md`/director's notes | 长片/launch film的分镜与**视觉密度条款**（标准+参照标杆+氛围层清单，见animation-best-practices §6.5）。**最低要求=storyboard-basics.md §5的轻量分镜卡格式**（八字段/镜，含[CAMERA]列与验收帧号）| ≥20s动画开工前；<20s动画不强制导演稿但分镜卡照画（storyboard-basics §0）；launch film级（品牌宣传片/「Apple级」预期）在此基线上按launch-film-director-notes.md升级为万字notes——分镜卡是底线，万字notes是launch film的加强版，不是两套并行要求 | **「用户说继续」授权的是进入下一步，不是跳过该步内部的gate**。跳过必须用户明说，且把「用户明示跳过」写进对应gate文件。**弱runtime降级模式不豁免gate文件**——降级第5条允许把检查点问答换成assumption清单，但三个gate文件本身照写（写文件不耗上下文），assumption清单就写进对应gate文件里。 **两套检查点的衔接**：主干用 🛑 检查点1-5，Fallback 用 🔴 CHECKPOINT（Phase 3.5 图片前置 + logo 子门）。从 Fallback Phase 1-5 走完回到主干 Step 2 时，检查点1（问题清单）已被 Phase 1 的澄清覆盖，**跳过不重复问**；检查点2 起照常执行。 ### 问问题的要点 必问（用`references/workflow.md`里的模板）： - design system/UI kit/codebase有吗？没有的话先去找 - 想要几种variations？在哪些维度上变？ - 关心flow、copy、还是visuals？ - 希望Tweak什么？ ## 异常处理 流程假设用户配合、环境正常。实操常遇以下异常，预定义fallback： | 场景 | 触发条件 | 处理动作 | |------|---------|---------| | 需求模糊到无法着手 | 用户只给一句模糊描述（如"做个好看的页面"） | 主动列3个可能方向让用户选（如"落地页 / Dashboard / 产品详情页"），而不是直接问10个问题 | | 用户拒绝回答问题清单 | 用户说"不要问了，直接做" | **拒答问题≠跳过三方向**：问题可以不问（自己补assumption），方向门照走——直接出三版初稿摆给用户选。仅当用户明说「别出三版/一版就行」才降为1主+1变体，并在`direction-approved.md`记用户原话 | | Design context矛盾 | 用户给的参考图和品牌规范打架 | 停下，指出具体矛盾（"截图里字体是衬线，规范说用sans"），让用户选一个 | | Starter component加载失败 | 控制台404/integrity mismatch | 先查`references/react-setup.md`常见报错表；还不行降级纯HTML+CSS不用React，保证产出可用 | | 时间紧迫要快交付 | 用户说"30分钟内要" | 跳过对齐pass直接Full pass，只做1个方案，交付时**明确标注"未经early validation"**，提醒用户质量可能打折 | | SKILL.md体积超限 | 新写HTML>1000行 | 按`references/react-setup.md`的拆分策略拆成多jsx文件，末尾`Object.assign(window,...)`共享 | | 克制原则 vs 产品所需密度冲突 | 产品核心卖点是 AI 智能 / 数据可视化 / 上下文感知（如番茄钟、Dashboard、Tracker、AI agent、Copilot、记账、健康监测）| 按「品位锚点」表格走**高密度型**信息密度：每屏 ≥ 3 处产品差异化信息。装饰性 icon 照样忌讳——加的是**有内容的**密度，不是装饰 | **原则**：异常时**先告诉用户发生了什么**（1句话），再按表处理。不要静默决策。 ## 反AI slop速查（补充项） 静态设计的完整反slop规则见「核心哲学 §6」（字体/色彩/容器/图像的避免与采用都在 §6.2-6.3，字体配对逻辑见 `references/typography.md`）。以下只列 §6 没覆盖的补充项： | 类别 | 避免 | 采用 | |------|------|------| | 图标 | **装饰性** icon 每处都配（撞 slop）| **承载差异化信息**的密度元素必须保留——不要把产品特色也一并减掉 | | 填充 | 编造stats/quotes装饰 | 留白，或问用户要真内容 | | 动画 | 散落的微交互 | 一次well-orchestrated的page load | | 动画-伪chrome | 画面内画底部进度条/时间码/版权署名条（与 Stage scrubber 撞车） | 画面只放叙事内容，进度/时间交给 Stage chrome（详见 `references/animation-pitfalls.md` §11） | | 动画-PowerPoint 切换 | 每个 scene 独立 layout + cue 用 fade-up + scene 切换整页 opacity 切换（= 带配音的 PowerPoint）| **整片是一个连续的运动叙事**：选 1-2 个 hero element 跨 scene 持续存在，每段是 hero 的状态变化（位置/大小/形态），scene 之间 morph 不切（详见 `references/voiceover-pipeline.md` 「铁律」章节）| ## 技术红线（必读 references/react-setup.md） **React+Babel项目**必须用pinned版本（见`react-setup.md`）。三条不可违反： 1. **never** 写 `const styles = {...}`——多组件时命名冲突会炸。**必须**给唯一名字：`const terminalStyles = {...}` 2. **scope不共享**：多个`<script type="text/babel">`之间组件不通，必须用`Object.assign(window, {...})`导出 3. **never** 用 `scrollIntoView`——会搞坏容器滚动，用其他DOM scroll方法 4. **手写 Stage / Sprite**（不用 `assets/animations.jsx`）必须实现两件事：(a) tick 第一帧同步设 `window.__ready = true` (b) 检测 `window.__recording === true` 时强制 loop=false——否则录视频必出问题 **固定尺寸内容**（幻灯片/视频）必须自己实现JS缩放，用auto-scale + letterboxing。 **幻灯片架构选型（必先决定）**： - 🔴 **默认且强烈推荐：多文件 + 概览墙**（几乎所有 PPT——培训/路演/科普/课件/汇报）→ 每页独立 HTML + `assets/deck_index.html` 拼接器。**这是 PPT 的默认交付形态**：自带**两种自适应 3D 概览**（网格 iframe / 无限画廊图片，按秒数 60/40 随机）+ 任意页数自适应（少页倾斜居中、多页舒适大卡滚动）+ 统一页码。**直接用，别重写概览**（倾斜/点击命中/裁切三个坑已内建解决，见 slide-decks.md）。 - **单文件**（仅 ≤5 页极简 pitch、且明确不需要概览墙、或需跨页共享 JS 状态）→ `assets/deck_stage.js`。 - 🛑 **不要默认选单文件而绕过概览墙**——北大 13 页 deck 实测踩坑：选了单文件 = 丢了概览墙，违背 PPT 默认交付形态。选单文件前先确认「这真的是 ≤5 页、且不需要概览墙」。 先读 `references/slide-decks.md` 的「🛑 先定架构」一节，错了会反复踩 CSS 特异性/作用域的坑。 ## Starter Components（assets/下） 造好的起手组件，直接copy进项目使用： | 文件 | 何时用 | 提供 | |------|--------|------| | `deck_index.html` | **幻灯片的默认基础产物** | **直接复制为 `index.html`、编辑 MANIFEST 即用，不要重写概览逻辑**（三个坑已内建解决）。自带两种自适应概览（网格 iframe 60% / 画廊 40%，画廊需 `thumb` 字段 + 先跑 `scripts/gen_deck_thumbs.mjs`）+ 键盘翻页 + scale + 计数器 + 打印合并。要改先读 `references/slide-decks.md` 三条硬约束 | | `scripts/gen_deck_thumbs.mjs` | **给无限画廊概览生成缩略图**（网格 iframe 模式不需要）| playwright 截每页 + sharp 降采样 1600px JPEG：`npm i playwright sharp && node gen_deck_thumbs.mjs --slides slides --out thumbs`，再给 MANIFEST 每项加 `thumb`。分辨率别 <1000px 否则 hover 发虚 | | `deck_stage.js` | 做幻灯片（单文件架构，≤10页） | web component：auto-scale + 键盘导航 + slide counter + localStorage + speaker notes ⚠️ **script 必须放在 `</deck-stage>` 之后，section 的 `display: flex` 必须写到 `.active` 上**，详见 `references/slide-decks.md` 的两个硬约束 | | `scripts/export_deck_pdf.mjs` | **HTML→PDF 导出（多文件架构）** · 每页独立 HTML 文件，playwright 逐个 `page.pdf()` → pdf-lib 合并。文字保留矢量可搜。依赖 `playwright pdf-lib` | | `scripts/export_deck_stage_pdf.mjs` | **HTML→PDF 导出（单文件 deck-stage 架构专用）** · 2026-04-20 新增。处理 shadow DOM slot 导致的「只出 1 页」、absolute 子元素溢出等坑。详见 `references/slide-decks.md` 末节。依赖 `playwright` | | `scripts/export_deck_pptx.mjs` | **HTML→可编辑 PPTX（路线 A：HTML 还没写时用）** · 调 `html2pptx.js` 导出原生可编辑文本框。**HTML 必须符合 4 条硬约束**（见 `references/editable-pptx.md`）。已经写好的视觉稿别硬跑它，改走下面一行。依赖 `playwright pptxgenjs sharp` | | `scripts/pptx_from_rendered.py` | **HTML→可编辑 PPTX（路线 B：HTML 已写好、或要继承甲方模板）** · 读浏览器渲染后的 `getBoundingClientRect`，视觉驱动的 HTML（flex/居中/裸文字/背景图/SVG）零改造直接转；能以甲方 `.pptx` 为基底继承母版与版式，让他们改母版对全部页面生效（pptxgenjs 做不到）。见 `references/pptx-from-rendered-html.md`。依赖 `playwright python-pptx Pillow` | | `scripts/html2pptx.js` | **HTML→PPTX 元素级翻译器** · 读 computedStyle 把 DOM 逐元素翻译成 PowerPoint 对象（text frame / shape / picture）。`export_deck_pptx.mjs` 内部调用。要求 HTML 严格满足 4 条硬约束 | | `design_canvas.jsx` | 并排展示≥2个静态variations | 带label的网格布局 | | `animations.jsx` | 任何动画HTML | Stage + Sprite + useTime + Easing + interpolate | | `ios_frame.jsx` | iOS App mockup | iPhone bezel + 状态栏 + 圆角 | | `android_frame.jsx` | Android App mockup | 设备bezel | | `macos_window.jsx` | 桌面App mockup | 窗口chrome + 红绿灯 | | `browser_window.jsx` | 网页在浏览器里的样子 | URL bar + tab bar | | `cursor.jsx` | 产品UI演示里的光标操作叙事 | macOS光标4形状 + CursorSprite弧线轨迹（Catmull-Rom+收敛手抖）+ ClickRipple双圈解耦 + hover联动 + GSAP/Stage双驱动，帧确定性 | 用法：读取对应 assets 文件内容 → inline 进你的 HTML `<script>` 标签 → slot 进你的设计。 ## References路由表 根据任务类型深入读对应references： | 任务 | 读 | |------|-----| | 开工前问问题、定方向 | `references/workflow.md` | | **App/iOS 原型完整守则**（架构表/取图代码/AppPhone骨架/ios_frame用法） | `references/app-prototype.md` | | 反AI slop、内容规范、scale | `references/content-guidelines.md` | | 字体排印/字体配对/中文排印 | `references/typography.md` | | React+Babel项目setup | `references/react-setup.md` | | 做幻灯片 | `references/slide-decks.md` + `assets/deck_index.html`（默认多文件概览墙）+ `scripts/gen_deck_thumbs.mjs`（画廊缩略图）+ `assets/deck_stage.js`（仅 ≤5 页单文件） | | 导出可编辑 PPTX · 路线 A（HTML 还没写，按 4 条硬约束写） | `references/editable-pptx.md` + `scripts/html2pptx.js` | | 导出可编辑 PPTX · 路线 B（**HTML 已写好的视觉稿**、**甲方要求用他们的模板**、或 A 转不出来） | `references/pptx-from-rendered-html.md` + `scripts/pptx_from_rendered.py` | | **验证 PPTX/渲染产物时「先验证验证工具」** | `references/pptx-from-rendered-html.md` 的「验证」节 + `references/verification.md` | | 做动画/motion（**先读 pitfalls**）| `references/animation-pitfalls.md` + `references/animations.md` + `assets/animations.jsx` | | ⭐ **动画分镜/画面构图**（任何动画开工前；每一镜先是一张会动的封面：定格帧十一律+景别体系+能量骨架+轻量分镜卡） | `references/storyboard-basics.md`（launch-film 导演稿是它的重装版） | | ⭐ **镜头语言/运镜**（zoom/pan/orbit/parallax/转场；预算制+镜间语法+PageCam 相机数学+CSS zoom 栅格化） | `references/camera-language.md`（设计判断）+ `gsap-recipes.md` §9 Camera Rig（实现） | | ⭐ **产品UI展示动画**（画面主角是一个界面：截图vs重建决策树+UI展示八式+typing+光标+3D巡览） | `references/ui-demo-animation.md` + `assets/cursor.jsx` | | **HyperFrames 渲染后端**（新动画默认；选型边界/合成契约/老demo迁移/check流程） | `references/hyperframes-backend.md` | | **设计语言的 GSAP 实现配方**（easing 映射/运动语言8条/五段叙事骨架/seek 安全规则） | `references/gsap-recipes.md` | | **动画的正向设计语法**（Anthropic 级叙事/运动/节奏/表达风格）| `references/animation-best-practices.md`（5 段叙事+Expo easing+运动语言 8 条+3 种场景配方）| | **带解说的长动画 / 长概念视频**（5-20 分钟带配音、解说驱动画面、TTS 实测时长生成 timeline）| `references/voiceover-pipeline.md`（铁律：连续运动叙事、禁 PowerPoint 切换）+ `assets/narration_stage.jsx` + `scripts/cloud/tts-doubao.mjs`（可选云TTS，自备key，见SECURITY.md）+ `scripts/narrate-pipeline.mjs` + `scripts/{mix-voiceover,render-narration}.sh` | | 做Tweaks实时调参 | `references/tweaks-system.md` | | 没有design context怎么办 | `references/design-context.md`（薄 fallback） 或 `references/design-styles.md`（厚 fallback：HTML 原生 60 种风格库，网页 20+PPT 20+信息图 20，按温度分级） | | **需求模糊要推荐风格方向** | `references/design-styles.md`（60 种 HTML 原生风格库，含还原度/温度/开源字体）+ `assets/showcases/INDEX.md`（预制截图画廊） | | **按输出类型查场景模板**（封面/PPT/信息图） | `references/scene-templates.md` | | 输出完后验证 | `references/verification.md` + `scripts/verify.py` | | **设计评审/打分**（设计完成后可选） | `references/critique-guide.md`（5 维度评分+常见问题清单） | | **动画导出MP4/GIF/加BGM** | `references/video-export.md` + `scripts/render-video.js`（默认25fps）/ `scripts/render-video-seek.js`（真60fps·确定性·无黑帧，走Stage时钟时用）+ `scripts/convert-formats.sh` + `scripts/add-music.sh` | | **动画加音效SFX**（苹果发布会级，37个预制） | `references/sfx-library.md` + `assets/sfx/<category>/*.mp3` | | **动画音频配置规则**（SFX+BGM双轨制、黄金配比、ffmpeg模板、场景配方） | `references/audio-design-rules.md` | | **Apple画廊展示风格**（3D倾斜+悬浮卡片+缓慢pan+焦点� -
test-prompts.json 2.7 KB
[ { "id": 1, "prompt": "我想做一个SaaS产品的登录页面，给我3个风格方向对比看看", "expected": "触发clarifying questions问design context/brand；产出3个variation的design_canvas；不用紫渐变/emoji/Inter等AI slop；有具体理由说明每个variation的差异维度", "tests": "workflow问问题 + variations逻辑 + 反AI slop清单 + design_canvas使用" }, { "id": 2, "prompt": "帮我做一份10页的产品pitch deck，讲一个AI工具的创业项目", "expected": "用deck_stage.js起手；先口头vocalize设计系统（色彩/字型/layout节奏）等确认；Section divider/content/data/quote多种layout交替；字号≥24px；1-indexed labels", "tests": "Junior Designer先汇报再做 + deck_stage使用 + 视觉节奏 + scale规范" }, { "id": 3, "prompt": "做个30秒的HTML动画，讲神经网络怎么工作", "expected": "用animations.jsx的Stage+Sprite；先写时间轴再写组件；入场easeOut出场easeIn；分phase讲故事而不是堆动画；文字停留≥3秒", "tests": "animations工作流 + easing正确 + 节奏设计 + 时长控制" }, { "id": 4, "prompt": "做一个 Habit Tracker App 原型", "expected": "问用户要 overview 平铺 or flow demo（默认走 overview）；用 assets/ios_frame.jsx，不手写 Dynamic Island；Tracker 属高密度型，每屏 ≥ 3 处信息密度元素（习惯完成率、连续天数、趋势曲线、成就badge等，非装饰）；至少 5-7 屏并排（首页/新建习惯/详情/统计/设置）", "tests": "overview/flow 形态路由 + ios_frame 硬绑定 + 信息密度分型（高密度型）+ 多屏并排" }, { "id": 5, "prompt": "做一个读书笔记 App 原型", "expected": "overview 平铺为主；ios_frame.jsx；读书笔记偏内容展示类，信息密度要求不如 Tracker 极端，但笔记列表页仍需 ≥ 3 层信息（书籍、引文、标签、进度）；至少 4-6 屏（首页书架/笔记详情/标注高亮/搜索/笔记本管理）；字体优先 serif display", "tests": "overview 默认 + ios_frame + 信息层次 + 内容为主的视觉节奏" }, { "id": 6, "prompt": "做一个跑步记录 App 原型", "expected": "overview 平铺；ios_frame.jsx；跑步 App 属高密度型（地图、配速曲线、心率区间、每公里分段数据），每屏 ≥ 3 处产品差异化信息；至少 5 屏（今日总览/跑步中实时数据/路线地图/历史记录/月度统计）；避免撞 AI slop（不用紫渐变、不堆装饰 icon，但数据可视化 icon 允许保留）", "tests": "overview + ios_frame + 高密度型数据可视化 + 地图/图表混排 + slop 边界条件" } ]
Comments (0)
Sign in to join the conversation.
Reviews (0)
No reviews yet.
No comments yet.