目錄

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.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. 核心架構

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. 源碼分析

3.1 SKILL.md — Skill 入口與規則引擎

SKILL.md 是整個項目的核心，它定義了 Agent 在設計任務中必須遵守的所有規則。文件大小約 56KB，包含完整的設計規則體系。

frontmatter 元數據：

---
name: huashu-design
description: 花叔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. 功能詳解

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. 技術亮點

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. 實踐指南

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。

7. 總結

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/