逆向Claude Design：huashu-design-深度解析

1. 概述
   1.1 项目背景与定位
   1.2 核心价值主张
   1.3 适用场景与边界
2. 核心架构
   2.1 仓库结构
   2.2 核心机制总览
   2.3 工作流管线
3. 源码分析
   3.1 SKILL.md — Skill 入口与规则引擎
   3.2 动画引擎 animations.jsx
   3.3 幻灯片外壳 deck_stage.js
   3.4 视频渲染管线 render-video.js
   3.5 设计哲学库 design-styles.md
4. 功能详解
   4.1 品牌资产协议
   4.2 设计方向顾问
   4.3 Junior Designer 工作流
   4.4 Motion Design 引擎
   4.5 Tweaks 实时变体系统
   4.6 HTML 幻灯片与 PPTX 导出
   4.7 5 维度专家评审
5. 技术亮点
   5.1 反 AI Slop 规则
   5.2 录屏与导出的工程化方案
   5.3 跨 Agent 兼容设计
   5.4 16 条动画踩坑实录
6. 实践指南
   6.1 快速安装
   6.2 典型使用场景
   6.3 常见问题与排障
7. 总结

1.1 项目背景与定位

huashu-design（花叔Design）是一个面向 AI Coding Agent 的 HTML 原生设计 Skill。它的核心理念是：在你的 agent 里打一句话，拿回一份能交付的设计。不需要 Figma、不需要 After Effects，只需一行 prompt，3 到 30 分钟内就能产出一个产品发布动画、一个可点击的 App 原型、一套可编辑的 PPT 或一份印刷级的信息图。
该项目由独立开发者花生（花叔 / Alchain）创建，基于 skills.sh 生态分发，支持 Claude Code、Cursor、Codex、OpenClaw、Hermes 等主流 Agent 环境。项目的 GitHub 仓库已获得 1.2k+ Star，定位为 Agent 生态中的"设计能力插件"。

1.2 核心价值主张

• 一句话交付：从模糊需求到可交付的设计产出，全程对话驱动
• HTML 原生：所有产出物均为 HTML 文件，双击即用，不依赖特定工具链
• 多格式导出：支持 MP4（25fps/60fps）、GIF、PPTX、PDF、PNG、SVG
• 设计哲学驱动：内置 5 流派 × 20 种设计哲学，避免 AI 生成的视觉同质化
• Agent-Agnostic：不绑定特定 Agent，任何支持 skills.sh 的环境均可使用

1.3 适用场景与边界

适用场景：

• 交互原型（高保真 App/Web mockup）
• 设计变体探索（并排对比多个设计方向）
• 演示幻灯片（1920×1080 HTML deck）
• 时间轴动画（motion design，视频素材）
• 信息图/数据可视化（印刷级排版）
• 设计方向顾问与专家评审
  不适用场景：生产级 Web App、SEO 网站、需要后端的动态系统

2.1 仓库结构

huashu-design/├── SKILL.md # Skill 入口文件（规则引擎）├── README.md # 项目说明文档├── assets/ # 预置资源与组件│   ├── animations.jsx           # Stage + Sprite 动画引擎│   ├── deck_stage.js            # 幻灯片外壳 Web Component│   ├── design_canvas.jsx        # 设计变体并排展示画布│   ├── ios_frame.jsx            # iPhone 15 Pro 精确机身框架│   ├── browser_window.jsx       # 浏览器窗口框架│  ├──bgm-*.mp3 # 6 首场景化 BGM│  ├──sfx/ # 音效库（28 个分类音效）│  └──showcases/ # 24 个预制 showcase（8 场景 × 3 风格）├── references/ # 参考文档（设计哲学与工程规范）│   ├── design-styles.md         # 20 种设计哲学详细库│  ├──workflow.md # Junior Designer 工作流│   ├── animation-pitfalls.md    # 16 条动画踩坑实录│   ├── video-export.md          # 视频导出完整指南│   ├── tweaks-system.md         # 实时变体调参系统│  └──... # 其他参考文档├── scripts/ # 工具脚本│   ├── render-video.js          # HTML → MP4 录制│   ├── convert-formats.sh       # MP4 → 60fps + GIF│  ├──add-music.sh # MP4 + BGM 混音│  └──html2pptx.js # HTML → 可编辑 PPTX└── demos/ # 演示 HTML 文件

2.2 核心机制总览

huashu-design 的核心由四大机制构成，形成从需求到交付的完整闭环：

• 品牌资产协议：涉及具体品牌时强制执行的 5 步硬流程，确保品牌色值和资产从权威来源获取
• 设计方向顾问：需求模糊时的 Fallback 模式，从 20 种设计哲学中推荐 3 个差异化方向
• Junior Designer 工作流：默认工作模式，先写假设再迭代的渐进式设计流程
• 反 AI Slop 规则：避免一眼 AI 的视觉最大公约数

2.3 工作流管线

流程执行说明：

• 阶段一：品牌资产确认（步骤 3-5）。如果用户需求涉及具体品牌，Skill 强制执行品牌资产协议，确保色值来自权威来源而非 AI 记忆
• 阶段二：设计方向选择（步骤 6-9）。当需求模糊时，Skill 从 5 流派 × 20 种设计哲学中推荐 3 个差异化方向，并行生成 Demo 让用户选择
• 阶段三：渐进式设计（步骤 10-12）。进入 Junior Designer 模式，先写假设和占位符，尽早获取用户反馈，再逐步填充真实内容
• 阶段四：交付与验证（步骤 13-14）。Playwright 自动截图验证，确保浏览器实际渲染与预期一致

3.1 SKILL.md — Skill 入口与规则引擎

SKILL.md 是整个项目的核心，它定义了 Agent 在设计任务中必须遵守的所有规则。文件大小约 56KB，包含完整的设计规则体系。

frontmatter 元数据：

---name: huashu-designdescription: 花叔Design（Huashu-Design）——用HTML做高保真原型、交互Demo...---

核心规则层级：

• 原则 #0（最高优先级）：事实验证先于假设。涉及具体产品/技术/规格参数时，必须先 WebSearch 验证，禁止凭训练语料做断言
• 品牌资产协议：5 步硬流程（问 → 搜 → 下载 → grep 色值 → 写 spec）
• 设计方向顾问：从 5 流派 × 20 种设计哲学推荐 3 个差异化方向
• Junior Designer 工作流：4 轮迭代（Assumptions → 真实组件 → 细节打磨 → 验证交付）
• 反 AI Slop 规则：避免紫渐变、emoji 图标、Inter 做 display font 等 AI 视觉通病

3.2 动画引擎 animations.jsx

动画引擎采用 Stage + Sprite 时间片段模型，借鉴 Remotion 但轻量化实现。核心导出 API 挂载到 window.Animations：

Stage 组件 — 动画容器，提供全局时间轴控制：

• 管理播放/暂停/跳转状态
• 自动缩放画布以适配视口
• 等待字体加载完成后才启动时钟（避免首帧字体跳变）
• 支持 window.__recording 信号，录制时自动禁用循环

Sprite 组件 — 时间片段，定义元素在时间轴上的可见区间：

• 通过 start/end 属性定义时间窗口
• 提供本地进度 t（0→1）和已过时间 elapsed
• 时间窗口外自动返回 null（不渲染）

核心 API：

• useTime() — 读取全局时间（秒）
• useSprite() — 读取本地进度 { t, elapsed, duration }
• interpolate(t, [inStart, inEnd], [outStart, outEnd], easing) — 线性插值
• Easing — 预置缓动函数：linear、easeIn、easeOut、easeInOut、expoOut、overshoot、spring、anticipation

缓动函数设计哲学：expoOut 使用 cubic-bezier(0.16, 1, 0.3, 1)，给数字元素"物理重量感"——迅速启动 + 缓慢刹车。spring 用于 toggle/按钮弹出的弹性效果。anticipation 模拟动画预备动作（先回拉再弹出）。

3.3 幻灯片外壳 deck_stage.js

deck_stage.js 实现为 Web Component <deck-stage>，提供完整的幻灯片播放体验：

核心功能：

• 固定尺寸画布（默认 1920×1080）+ 自适应缩放 + Letterbox
• 键盘导航（←/→/Space/Home/End）和点击区域导航
• localStorage 持久化当前 slide（刷新不丢失位置）
• Hash 导航（#slide-5 直接跳转到第 5 张）
• Speaker Notes 通过 postMessage 通知外层
• Cmd+P 打印为 PDF 支持（一页一 slide）
• 使用 Shadow DOM 隔离样式

设计亮点：初始化时根据 document.readyState 判断是否需要等待 DOM 解析完成。如果文档还在 loading 状态，延迟到 DOMContentLoaded 事件后再收集 <section> 元素，避免 parser 时序问题导致子节点为空。

3.4 视频渲染管线 render-video.js

render-video.js 是 HTML 动画导出为 MP4 的核心脚本，采用 Playwright headless 浏览器录制：

两阶段录制架构：

• Phase 1: Warmup（无录制）— 预加载字体和资源，然后关闭上下文
• Phase 2: Record（全新上下文）— 干净状态开始，动画从 t=0 录制

录制同步机制：

• HTML 端在 tick 首帧设置 window.__ready = true
• 脚本端 waitForFunction 等待此信号，精确计算 trim 偏移
• 额外调用 window.__seek(0) 作为第二道防线，强制归零
• 通过 addInitScript 注入 window.__recording = true，告知 HTML 禁用循环

Chrome 元素隐藏：

• 注入 CSS 隐藏 .progress、.counter、.replay 等调试元素
• JS 启发式检测固定位置的底部/顶部工具栏并隐藏
• MutationObserver 监听 DOM 变化，捕获 React/Vue 动态插入的 chrome 元素

3.5 设计哲学库 design-styles.md

这是整个 Skill 最具特色的部分之一——20 种完整的设计哲学体系，分为 5 大流派：

每种风格都提供：哲学内核、核心特征、提示词 DNA（可直接用于 AI 生成）、代表作和搜索关键词。更重要的是，文档包含一个风格×场景×执行路径速查表，标注每种风格在不同场景（网页/PPT/信息图/封面）下的适配度，以及推荐执行路径（HTML 渲染 / AI 生成 / 混合）。

4.1 品牌资产协议

品牌资产协议是 Skill 中最硬的一段规则。涉及具体品牌时（如 Stripe、Linear、Anthropic），强制执行 5 步流程：

根据作者提供的 A/B 测试数据，v2 版本（5 步硬流程）的稳定性方差比 v1 低 5 倍。品牌色值的准确获取是高质量品牌设计的基础，也是 65 分作品和 90 分作品的分水岭。

4.2 设计方向顾问

当用户需求模糊到无法直接着手时，Skill 触发设计方向顾问模式：

• 从 5 流派 × 20 种设计哲学中推荐 3 个必须来自不同流派的差异化方向
• 每个方向配有代表作、气质关键词和代表设计师
• 并行生成 3 个视觉 Demo（24 个预制 showcase 覆盖 8 场景 × 3 风格）
• 用户选定后进入主干 Junior Designer 流程

这种设计的核心思路是：不凭通用直觉硬做，而是系统性地探索可能性空间。

4.3 Junior Designer 工作流

这是 Skill 的默认工作模式，核心理念是"不要接到任务就闷头冲"：

Pass 1：Assumptions + Placeholders — 在 HTML 文件头部写假设和推理注释，用占位符构建结构，然后立刻展示给用户。这是成本最低的纠错时机。

Pass 2：真实组件 + Variations — 用户批准方向后，用 React 组件替换占位符，开始做变体探索。

Pass 3：细节打磨 — 微调字号、间距、对比度、动画 timing。

Pass 4：验证 + 交付 — Playwright 截图验证，浏览器肉眼确认。

工作流的精髓在于频繁的反馈循环——做到一半再展示一次，不要等全做完。设计方向错了，晚展示等于白做。

4.4 Motion Design 引擎

动画引擎基于 Stage + Sprite 模型，提供声明式的时间轴动画创作方式。

使用示例：

<Stage duration={10}>  <Sprite start={0} end={3}>    <Title />  </Sprite>  <Sprite start={2} end={5}>    <Subtitle />  </Sprite></Stage>

在 Sprite 子组件中通过 useSprite() 读取当前片段的本地进度，通过 interpolate() 实现基于时间的属性插值。Stage 组件内置完整的播放控制面板（播放/暂停/进度条/时间码），录制时自动隐藏。

导出流程：

• render-video.js 录制 25fps MP4 基础版
• convert-formats.sh 派生 60fps 版本和 GIF
• add-music.sh 混入场景化 BGM（6 首内置音乐覆盖 tech/ad/educational/tutorial 等场景）

4.5 Tweaks 实时变体系统

Tweaks 系统允许用户在不修改代码的情况下实时调整设计参数。采用纯前端 localStorage 方案，跨 Agent 环境兼容。

实现原理：

• useTweaks() Hook 从 localStorage 读取持久化的参数值
• 右下角浮动面板提供颜色选择器、滑块、下拉框等控件
• 参数变更通过 CSS 变量实时反映到设计中
• 刷新页面不丢失配置

设计原则：

• 每个 tweak 展示真实的设计选项，不是无意义的微调
• 面板最多 5-6 个选项，超过就变成配置页面
• 默认值本身必须是一个完整、可发布的设计

4.6 HTML 幻灯片与 PPTX 导出

幻灯片功能通过 <deck-stage> Web Component 实现。每个 <section> 标签代表一张 slide，支持键盘导航、进度显示、打印为 PDF。html2pptx.js 脚本读取 DOM 的 computedStyle，逐元素翻译成 PowerPoint 对象，导出的是真文本框而非图片铺底，确保用户可以在 PowerPoint 中编辑内容。

4.7 5 维度专家评审

交付后可选的评审功能，从 5 个维度对设计打分（0-10 分）：

• 哲学一致性：设计是否贯彻了选定的设计哲学
• 视觉层级：信息层级是否清晰
• 细节执行：字距、对齐、色彩精度等
• 功能性：交互是否完整、状态是否覆盖
• 创新性：是否突破了模板化思维

评审结果以雷达图可视化，输出 Keep（保持）/ Fix（修复）/ Quick Wins（快速改进）清单。

5.1 反 AI Slop 规则

Skill 内置了一套系统的反 AI 视觉通病规则，避免生成的作品"一眼 AI"：

禁止模式：

• 紫渐变背景
• emoji 作为图标
• 圆角 + 左 border accent 组合
• SVG 画人脸
• Inter 字体做 display font

推荐替代：

• text-wrap: pretty 排印细节
• CSS Grid 精准布局
• 精心选择的 serif display 字体
• oklch 色彩空间

5.2 录屏与导出的工程化方案

视频导出是 huashu-design 工程化程度最高的部分，解决了大量边缘问题：

Warmup + Record 两阶段架构：预热阶段（无录制）缓存字体和资源，录制阶段（全新上下文）从干净状态开始。这避免了 Playwright recordVideo 从 context 创建就开始写入 WebM 的问题。

__ready 同步协议：HTML 端在 tick 首帧设置 window.__ready = true，脚本端精确等待此信号作为录制起点。配合 window.__seek(0) 作为第二道防线，确保动画时间轴精确归零。

__recording 录制信号：脚本注入 window.__recording = true，HTML 端检测后强制禁用循环，确保视频结尾停在清晰的最后一帧。

60fps 兼容性：默认使用帧复制模式（fps=60），兼容 QuickTime/Safari/Chrome/VLC 全平台。minterpolate 插帧作为可选高质量模式，但需本地测试目标播放器。

5.3 跨 Agent 兼容设计

Skill 在多处采用了跨 Agent 兼容的设计策略：

• Tweaks 系统使用纯前端 localStorage，不依赖宿主的 postMessage 回写
• 所有组件为纯 HTML/JS/CSS，不依赖特定构建工具
• 使用 Babel Standalone 在浏览器端编译 JSX，双击 HTML 即可运行
• EDITMODE-BEGIN/END 标记块保留向前兼容性

5.4 16 条动画踩坑实录

animation-pitfalls.md 记录了 16 条来自真实失败案例的动画规则，每条都包含踩坑描述、根因分析和修复方案。以下是几个典型例子：

叠层布局陷阱：包含 position: absolute 子元素的容器必须显式 position: relative，否则 absolute 子元素以错误的祖先为坐标系。

Pure Render 原则：render(t) 应为纯函数——给定 t 输出唯一 DOM 状态。使用 setTimeout 触发动画会导致无法 seek 回跳。正确做法是用 fired Set 配合显式 reset。

字体加载前测量：依赖 DOM 测量的布局代码必须包在 document.fonts.ready.then() 里，否则 fallback 字体宽度与实际字体不一致，导致永久偏移。

录制时禁止 loop：录制脚本和 HTML 之间需要"我在录制"的握手协议（window.__recording），否则视频结尾会突然跳回第一帧。

跨 scene 反色上下文：跨多 scene 复用的元素（chapter 标签/水印/编号）禁止硬编码颜色，否则在反色底 scene 上会隐形。

6.1 快速安装

npx skills add alchaincyf/huashu-design

安装后在 Claude Code 中直接对话即可使用。支持所有 skills.sh 兼容的 Agent 环境。

6.2 典型使用场景

做演讲 PPT：

「做一份 AI 心理学的演讲 PPT，推荐 3 个风格方向让我选」

Skill 会推荐 3 个不同流派的设计方向，生成 Demo 供选择，然后按选定方向生成完整的 HTML 幻灯片。

做 App 原型：

「做个 AI 番茄钟 iOS 原型，4 个核心屏幕要真能点击」

使用 ios_frame.jsx 精确的 iPhone 15 Pro 机身框架，包含灵动岛/状态栏/Home Indicator，支持状态驱动的多屏切换。

做动画并导出视频：

「把这段逻辑做成 60 秒动画，导出 MP4 和 GIF」

使用 Stage + Sprite 引擎制作动画，然后通过 render-video.js 录制 MP4，convert-formats.sh 生成 60fps 版本和 GIF。

6.3 常见问题与排障

视频开头有空白：检查 HTML 中是否在 tick 首帧正确设置 window.__ready = true。使用 assets/animations.jsx 的 Stage 组件会自动处理。

60fps MP4 无法播放：默认的帧复制模式应兼容所有播放器。如果使用了 --minterpolate 插帧，尝试去掉此参数。

双击 HTML 黑屏：如果是动画 HTML，检查 animations.jsx 是否内联在 <script type="text/babel"> 标签内。file:// 协议下外部 .jsx 文件会触发 CORS 错误。

GIF 文件太大：降低 gif_width 参数到 600，或降低 fps 到 10。

huashu-design 作为一个面向 AI Agent 的设计 Skill，其核心价值在于将专业设计知识（设计哲学、品牌规范、动画工程）编码为 Agent 可执行的规则，从而让非设计背景的用户也能通过对话获取高质量的设计产出。

关键要点：

• 品牌资产协议解决了 AI 设计中"猜品牌色"的顽疾，A/B 测试显示稳定性提升 5 倍
• 20 种设计哲学库 + 设计方向顾问，系统性避免了 AI 视觉同质化
• Stage + Sprite 动画引擎 + 完整的录制导出管线，解决了 HTML 动画到视频的全链路问题
• 16 条动画踩坑实录，是项目最珍贵的工程知识沉淀
• 跨 Agent 兼容设计，基于纯前端方案而非特定宿主 API

适用人群：需要在 AI Agent 中快速获取高质量设计产出的开发者、产品经理、独立开发者。适合做原型验证、产品发布素材、演讲幻灯片、概念动画等场景。

未来展望：随着 AI Agent 生态的发展，Skill 这种"能力插件"模式会成为 Agent 能力扩展的标准方式。huashu-design 展示了如何将专业领域知识系统化地编码为可复用的 Agent 能力——这可能是 AI 设计工具的一个新范式。

[1] huashu-design GitHub 仓库：https://github.com/alchaincyf/huashu-design

[2] skills.sh - AI Agent Skills 生态：https://skills.sh

[3] Playwright 浏览器自动化文档：https://playwright.dev/

[4] Remotion - React 视频框架（Stage + Sprite 模型的灵感来源）：https://www.remotion.dev/

[5] Pentagram 设计工作室：https://pentagram.com/

[6] Kenya Hara《设计中的设计》：https://book.douban.com/subject/21126747/