Huashu Design 输出验证指南给设计 HTML 与视频产物做「交付前体检」【免费下载链接】huashu-designHuashu Design · HTML-native design skill for Claude Code · Claude Code 里 HTML 原生的设计 skill · 高保真原型 / 幻灯片 / 动画 20 设计哲学 5 维评审 MP4 导出 · Agent-agnostic项目地址: https://gitcode.com/gh_mirrors/hu/huashu-design本指南围绕 Huashu Design 项目中的 references/verification.md 展开系统讲解在无内置 verifier 的 agent 环境下如何用 Playwright 封装脚本verify.py对设计 HTML 做渲染、控制台、视口、交互、幻灯片五维检查并用verify-video.sh对导出的 MP4 做分辨率、帧率、时长、音轨、黑帧、响度的硬校验。读完你会掌握一套可复制的「打开 → 截图 → 抓错 → 上报」交付前检查流程以及每类常见问题的排障路径。为什么需要一条独立的验证流程部分 design-agent 原生环境如 Claude.ai Artifacts内置了fork_verifier_agent可以自动起 subagent 用 iframe 截图检查产出。但大多数 agent 环境——Claude Code、Codex、Cursor、Trae 等——没有这个内置能力。Huashu Design 的做法很直接用 Playwright 手动驱动浏览器就能覆盖相同的验证场景且不依赖任何特定 agent 平台。这与 SKILL.md 里定义的工作流是严格对齐的标准流程第 7 步就是「验证用 Playwright 截图见references/verification.md检查控制台错误发给用户」并在检查点 5 要求「交付前自己肉眼过一遍浏览器」因为「AI 写的代码经常有 interaction bug」见 SKILL.md。验证不是可选动作而是交付链路中固定的一个环节。验证清单每次产出 HTML 后的五步检查1. 浏览器渲染检查必做最基础的问题HTML 能不能打开在 macOS 上直接唤起浏览器open -a Google Chrome /path/to/your/design.html或者直接用 Playwright 截图见下一节。这一步成本最低能第一时间排除「文件路径错误」「编码问题」「资源引用失效」这类低级故障。2. 控制台错误检查HTML 文件里最常见的问题是JS 报错导致白屏。用仓库自带的 Playwright 封装脚本跑一遍python ~/.claude/skills/huashu-design/scripts/verify.py path/to/design.html这个脚本scripts/verify.py实际做四件事用 headless chromium 打开 HTMLpage.goto(file_url, wait_untilnetworkidle)截图保存到项目目录默认输出到 HTML 所在目录的screenshots/子目录抓取控制台错误——从源码看它通过page.on(console, ...)捕获error和warning级别的 console 消息通过page.on(pageerror, ...)捕获未捕获的页面异常scripts/verify.py报告 status——page_errors非空时脚本以 exit code 1 退出全干净则返回 0scripts/verify.py一个值得注意的实现细节脚本在创建浏览器 context 时固定使用device_scale_factor2scripts/verify.py相当于 retina 2x 截图方便在高分屏上检查细节。3. 多视口检查响应式设计必须抓多个 viewport一次跑完python verify.py design.html --viewports 1920x1080,1440x900,768x1024,375x667--viewports参数接收逗号分隔的WxH列表默认值是1440x900scripts/verify.py。注意两个行为细节多视口模式下每张截图文件名带-宽x高后缀如design-375x667.png避免相互覆盖scripts/verify.py每个视口除了 viewport 截图还会额外生成一张full_pageTrue的完整页面截图{stem}{suffix}-full.png用于检查滚动后区域是否有错位scripts/verify.py。4. 交互检查Tweaks、动画、按钮切换这类交互——默认的静态截图看不到。两种做法让用户自己开浏览器点一遍最真实用 Playwright 录屏把交互过程录下来page.video.record(interaction.mp4)对带 Tweaks 面板配色/字型/信息密度参数化切换或动画的页面静态截图永远验证不了「切换后组件是否响应」这一步不能省。5. 幻灯片逐页检查Deck 类 HTML幻灯片需要一张张截python verify.py deck.html --slides 10 # 截前 10 张生成deck-slide-01.png、deck-slide-02.png……方便快速浏览。从源码看slide 模式会每页截图后按ArrowRight键翻页、等 500ms 再截下一页scripts/verify.py——这意味着deck 页面必须支持键盘 ArrowRight 翻页否则逐页检查会失效scripts/verify.py 的参数帮助里也明确写了这一前提。Playwright 环境搭建首次使用需要安装# Node 版 npm install -g playwright npx playwright install chromium # 或者 Python 版 pip install playwright playwright install chromium如果用户已经全局安装过 Playwright直接用即可。verify.py在 import 失败时会给出明确提示并退出scripts/verify.py不会静默挂起。截图最佳实践五种截图模式场景代码说明完整页面page.screenshot(pathfull.png, full_pageTrue)一次截整个滚动长度viewportpage.screenshot(pathviewport.png)默认只截可见区域特定元素element page.query_selector(.hero-section)element.screenshot(pathhero.png)只截某组件定位问题更聚焦高清page browser.new_page(device_scale_factor2)retina 2x细节看得清等动画结束page.wait_for_timeout(2000)page.screenshot(...)等 2 秒让动画 settle 再截最后一条对 Huashu Design 尤其重要产出的动画页面大量使用 GSAP/Stage 时间轴动画截图时机早了会拿到动画中间帧产生「看起来像 bug」的假象。verify.py也内置了--wait参数默认 2000 毫秒来统一控制这个等待scripts/verify.py。把截图发给用户本地截图直接打开open screenshot.png用户会在自己的 Preview / Figma / VSCode / 浏览器里看。如果需要给远程协作者看Slack / 飞书 / 微信让用户用自己的图床工具或 MCP 上传截图拿到一个永久链接后粘贴到任何地方。验证产出属于交付物的一部分应该随 HTML 一起呈现给用户而不是留在 agent 的临时目录里。验证出错时的四类排障手册页面白屏白屏时控制台一定有错按顺序排查React Babel script tag 的 integrity hash 对不对——见 references/react-setup.md该文档要求固定版本 integrity hashreact18.3.1 / babel/standalone7.29.0哈希不匹配会直接导致脚本被浏览器拒绝加载是不是const styles {...}命名冲突——多 JSX 文件共用同名styles对象会互相覆盖react-setup.md 将其列为「非协商」规矩必须用唯一前缀命名跨文件的组件有没有 export 到window——每个script typetext/babel被 Babel 独立编译、scope 不通组件文件末尾必须Object.assign(window, {...})JSX 语法错误——babel.min.js不报错临时换成babel.js非压缩版就能看到清晰报错。动画卡用 Chrome DevTools 的 Performance tab 录一段找 layout thrashing频繁 reflow 导致的重排风暴动效优先用transform和opacity走 GPU 合成层不触发布局。字体不对检查font-face的 url 是否可访问尤其 CDN 被墙或本地file://场景检查 fallback 字体是否配置中文字体加载慢先显示 fallback加载完再切换避免 FOIT 白屏。布局错位检查box-sizing: border-box是否全局应用检查* { margin: 0; padding: 0 }reset 是否生效在 Chrome DevTools 里打开 gridlines 看实际布局网格。验证 设计师的第二双眼永远要自己过一遍。AI 写代码时经常出现看起来对但 interaction 有 bug静态截图好但 scroll 时错位宽屏好看但窄屏崩Dark mode 忘了测Tweaks 切换后某些组件没响应。这些恰恰是静态截图验证不了的维度——所以验证清单里才有「多视口」「交互检查」「录屏」这些环节。最后 1 分钟的验证可以省 1 小时的返工这是把「看起来对」升级为「真的对」的唯一手段。常用验证脚本命令速查# 基础打开 截图 抓错 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/ # headlessfalse打开真实浏览器给你看 python verify.py design.html --show参数全集与 scripts/verify.py 的 argparse 定义一致参数默认值说明html_path位置参数必填待验证的 HTML 文件路径--viewports1440x900逗号分隔的WxH列表--slides0幻灯片模式截前 N 张需支持 ArrowRight 翻页--outputHTML 同目录screenshots/截图输出目录自动创建--show关闭非 headless打开真实浏览器窗口按 Enter 关闭--wait2000打开页面后等待的毫秒数让动画 settle视频产物硬校验verify-video.sh渲染出的 MP4 / 成片不靠肉眼过用脚本硬校验。HTML 合成侧的校验由 HyperFrames 的npm run check五门审计lint / runtime / layout / motion / contrast负责verify-video.sh只管产物侧scripts/verify-video.sh。# 成品默认要求有音轨 bash scripts/verify-video.sh final.mp4 --duration22 --fps60 --width1920 --height1080 # 无声中间产物 bash scripts/verify-video.sh raw.mp4 --duration10 --fps60 --no-audio # 刻意黑场开场的电影风 bash scripts/verify-video.sh film.mp4 --duration30 --fps60 --allow-black-open脚本实际执行的检查项对应 scripts/verify-video.sh 源码分辨率 / 帧率用ffprobe读取视频流width/height/avg_frame_rate与期望值比对帧率容差 ±0.5fpsscripts/verify-video.sh时长误差±2% 或 ±0.2s 取大者tolmax(e*0.02, 0.2)防止时长不符或录制提前截断scripts/verify-video.shaudio stream 存在性默认必须有音轨没有即 FAIL——这是「动画默认交付形态是带 SFXBGM 的 MP4无声半成品」铁律的机器执行--no-audio用于明确无音频的中间产物跳过该检查scripts/verify-video.sh首尾黑帧用ffmpeg的blackdetectd0.1:pix_th0.10滤镜检测黑帧段片头 0.3s 内的黑帧是「录制起点偏移」的典型症状刻意黑场开场用--allow-black-open豁免片尾黑帧是「loop 回跳或时长超录」的典型症状scripts/verify-video.shLUFS 响度成品目标-14 ± 4LUFS源码中区间写为 -18 ~ -10偏离时警告「检查混音增益」scripts/verify-video.sh。exit code 非 0 就不许交付——任何一项 FAIL整个脚本以 exit 1 结束scripts/verify-video.sh可以在 CI 或 agent 工作流中直接当作交付闸门。验证在完整流水线中的位置在 Huashu Design 的默认导出流水线中验证是收尾的硬闸门npm run checkHyperFrames 五门审计合成侧 → npx hyperframes render --fps 60终渲 → scripts/verify-video.sh产物侧硬校验新动画项目默认走 HyperFrames 后端时合成侧审计和产物侧校验是两条互补的防线详见 references/hyperframes-backend.md走自研 Stage 管线时则用render-video.js录屏 →convert-formats.sh派生格式 →add-music.sh混 BGM最后同样落到verify-video.sh详见 references/video-export.md。整个验证体系的核心哲学是一致的能机器校验的绝不靠肉眼能让用户自己过一遍的绝不替用户默认跳过——对 HTML 用verify.py对视频产物用verify-video.sh两套脚本覆盖了设计产出的两端形成完整的交付质量闭环。【免费下载链接】huashu-designHuashu Design · HTML-native design skill for Claude Code · Claude Code 里 HTML 原生的设计 skill · 高保真原型 / 幻灯片 / 动画 20 设计哲学 5 维评审 MP4 导出 · Agent-agnostic项目地址: https://gitcode.com/gh_mirrors/hu/huashu-design创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
Huashu Design 输出验证指南：给设计 HTML 与视频产物做「交付前体检」
Huashu Design 输出验证指南给设计 HTML 与视频产物做「交付前体检」【免费下载链接】huashu-designHuashu Design · HTML-native design skill for Claude Code · Claude Code 里 HTML 原生的设计 skill · 高保真原型 / 幻灯片 / 动画 20 设计哲学 5 维评审 MP4 导出 · Agent-agnostic项目地址: https://gitcode.com/gh_mirrors/hu/huashu-design本指南围绕 Huashu Design 项目中的 references/verification.md 展开系统讲解在无内置 verifier 的 agent 环境下如何用 Playwright 封装脚本verify.py对设计 HTML 做渲染、控制台、视口、交互、幻灯片五维检查并用verify-video.sh对导出的 MP4 做分辨率、帧率、时长、音轨、黑帧、响度的硬校验。读完你会掌握一套可复制的「打开 → 截图 → 抓错 → 上报」交付前检查流程以及每类常见问题的排障路径。为什么需要一条独立的验证流程部分 design-agent 原生环境如 Claude.ai Artifacts内置了fork_verifier_agent可以自动起 subagent 用 iframe 截图检查产出。但大多数 agent 环境——Claude Code、Codex、Cursor、Trae 等——没有这个内置能力。Huashu Design 的做法很直接用 Playwright 手动驱动浏览器就能覆盖相同的验证场景且不依赖任何特定 agent 平台。这与 SKILL.md 里定义的工作流是严格对齐的标准流程第 7 步就是「验证用 Playwright 截图见references/verification.md检查控制台错误发给用户」并在检查点 5 要求「交付前自己肉眼过一遍浏览器」因为「AI 写的代码经常有 interaction bug」见 SKILL.md。验证不是可选动作而是交付链路中固定的一个环节。验证清单每次产出 HTML 后的五步检查1. 浏览器渲染检查必做最基础的问题HTML 能不能打开在 macOS 上直接唤起浏览器open -a Google Chrome /path/to/your/design.html或者直接用 Playwright 截图见下一节。这一步成本最低能第一时间排除「文件路径错误」「编码问题」「资源引用失效」这类低级故障。2. 控制台错误检查HTML 文件里最常见的问题是JS 报错导致白屏。用仓库自带的 Playwright 封装脚本跑一遍python ~/.claude/skills/huashu-design/scripts/verify.py path/to/design.html这个脚本scripts/verify.py实际做四件事用 headless chromium 打开 HTMLpage.goto(file_url, wait_untilnetworkidle)截图保存到项目目录默认输出到 HTML 所在目录的screenshots/子目录抓取控制台错误——从源码看它通过page.on(console, ...)捕获error和warning级别的 console 消息通过page.on(pageerror, ...)捕获未捕获的页面异常scripts/verify.py报告 status——page_errors非空时脚本以 exit code 1 退出全干净则返回 0scripts/verify.py一个值得注意的实现细节脚本在创建浏览器 context 时固定使用device_scale_factor2scripts/verify.py相当于 retina 2x 截图方便在高分屏上检查细节。3. 多视口检查响应式设计必须抓多个 viewport一次跑完python verify.py design.html --viewports 1920x1080,1440x900,768x1024,375x667--viewports参数接收逗号分隔的WxH列表默认值是1440x900scripts/verify.py。注意两个行为细节多视口模式下每张截图文件名带-宽x高后缀如design-375x667.png避免相互覆盖scripts/verify.py每个视口除了 viewport 截图还会额外生成一张full_pageTrue的完整页面截图{stem}{suffix}-full.png用于检查滚动后区域是否有错位scripts/verify.py。4. 交互检查Tweaks、动画、按钮切换这类交互——默认的静态截图看不到。两种做法让用户自己开浏览器点一遍最真实用 Playwright 录屏把交互过程录下来page.video.record(interaction.mp4)对带 Tweaks 面板配色/字型/信息密度参数化切换或动画的页面静态截图永远验证不了「切换后组件是否响应」这一步不能省。5. 幻灯片逐页检查Deck 类 HTML幻灯片需要一张张截python verify.py deck.html --slides 10 # 截前 10 张生成deck-slide-01.png、deck-slide-02.png……方便快速浏览。从源码看slide 模式会每页截图后按ArrowRight键翻页、等 500ms 再截下一页scripts/verify.py——这意味着deck 页面必须支持键盘 ArrowRight 翻页否则逐页检查会失效scripts/verify.py 的参数帮助里也明确写了这一前提。Playwright 环境搭建首次使用需要安装# Node 版 npm install -g playwright npx playwright install chromium # 或者 Python 版 pip install playwright playwright install chromium如果用户已经全局安装过 Playwright直接用即可。verify.py在 import 失败时会给出明确提示并退出scripts/verify.py不会静默挂起。截图最佳实践五种截图模式场景代码说明完整页面page.screenshot(pathfull.png, full_pageTrue)一次截整个滚动长度viewportpage.screenshot(pathviewport.png)默认只截可见区域特定元素element page.query_selector(.hero-section)element.screenshot(pathhero.png)只截某组件定位问题更聚焦高清page browser.new_page(device_scale_factor2)retina 2x细节看得清等动画结束page.wait_for_timeout(2000)page.screenshot(...)等 2 秒让动画 settle 再截最后一条对 Huashu Design 尤其重要产出的动画页面大量使用 GSAP/Stage 时间轴动画截图时机早了会拿到动画中间帧产生「看起来像 bug」的假象。verify.py也内置了--wait参数默认 2000 毫秒来统一控制这个等待scripts/verify.py。把截图发给用户本地截图直接打开open screenshot.png用户会在自己的 Preview / Figma / VSCode / 浏览器里看。如果需要给远程协作者看Slack / 飞书 / 微信让用户用自己的图床工具或 MCP 上传截图拿到一个永久链接后粘贴到任何地方。验证产出属于交付物的一部分应该随 HTML 一起呈现给用户而不是留在 agent 的临时目录里。验证出错时的四类排障手册页面白屏白屏时控制台一定有错按顺序排查React Babel script tag 的 integrity hash 对不对——见 references/react-setup.md该文档要求固定版本 integrity hashreact18.3.1 / babel/standalone7.29.0哈希不匹配会直接导致脚本被浏览器拒绝加载是不是const styles {...}命名冲突——多 JSX 文件共用同名styles对象会互相覆盖react-setup.md 将其列为「非协商」规矩必须用唯一前缀命名跨文件的组件有没有 export 到window——每个script typetext/babel被 Babel 独立编译、scope 不通组件文件末尾必须Object.assign(window, {...})JSX 语法错误——babel.min.js不报错临时换成babel.js非压缩版就能看到清晰报错。动画卡用 Chrome DevTools 的 Performance tab 录一段找 layout thrashing频繁 reflow 导致的重排风暴动效优先用transform和opacity走 GPU 合成层不触发布局。字体不对检查font-face的 url 是否可访问尤其 CDN 被墙或本地file://场景检查 fallback 字体是否配置中文字体加载慢先显示 fallback加载完再切换避免 FOIT 白屏。布局错位检查box-sizing: border-box是否全局应用检查* { margin: 0; padding: 0 }reset 是否生效在 Chrome DevTools 里打开 gridlines 看实际布局网格。验证 设计师的第二双眼永远要自己过一遍。AI 写代码时经常出现看起来对但 interaction 有 bug静态截图好但 scroll 时错位宽屏好看但窄屏崩Dark mode 忘了测Tweaks 切换后某些组件没响应。这些恰恰是静态截图验证不了的维度——所以验证清单里才有「多视口」「交互检查」「录屏」这些环节。最后 1 分钟的验证可以省 1 小时的返工这是把「看起来对」升级为「真的对」的唯一手段。常用验证脚本命令速查# 基础打开 截图 抓错 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/ # headlessfalse打开真实浏览器给你看 python verify.py design.html --show参数全集与 scripts/verify.py 的 argparse 定义一致参数默认值说明html_path位置参数必填待验证的 HTML 文件路径--viewports1440x900逗号分隔的WxH列表--slides0幻灯片模式截前 N 张需支持 ArrowRight 翻页--outputHTML 同目录screenshots/截图输出目录自动创建--show关闭非 headless打开真实浏览器窗口按 Enter 关闭--wait2000打开页面后等待的毫秒数让动画 settle视频产物硬校验verify-video.sh渲染出的 MP4 / 成片不靠肉眼过用脚本硬校验。HTML 合成侧的校验由 HyperFrames 的npm run check五门审计lint / runtime / layout / motion / contrast负责verify-video.sh只管产物侧scripts/verify-video.sh。# 成品默认要求有音轨 bash scripts/verify-video.sh final.mp4 --duration22 --fps60 --width1920 --height1080 # 无声中间产物 bash scripts/verify-video.sh raw.mp4 --duration10 --fps60 --no-audio # 刻意黑场开场的电影风 bash scripts/verify-video.sh film.mp4 --duration30 --fps60 --allow-black-open脚本实际执行的检查项对应 scripts/verify-video.sh 源码分辨率 / 帧率用ffprobe读取视频流width/height/avg_frame_rate与期望值比对帧率容差 ±0.5fpsscripts/verify-video.sh时长误差±2% 或 ±0.2s 取大者tolmax(e*0.02, 0.2)防止时长不符或录制提前截断scripts/verify-video.shaudio stream 存在性默认必须有音轨没有即 FAIL——这是「动画默认交付形态是带 SFXBGM 的 MP4无声半成品」铁律的机器执行--no-audio用于明确无音频的中间产物跳过该检查scripts/verify-video.sh首尾黑帧用ffmpeg的blackdetectd0.1:pix_th0.10滤镜检测黑帧段片头 0.3s 内的黑帧是「录制起点偏移」的典型症状刻意黑场开场用--allow-black-open豁免片尾黑帧是「loop 回跳或时长超录」的典型症状scripts/verify-video.shLUFS 响度成品目标-14 ± 4LUFS源码中区间写为 -18 ~ -10偏离时警告「检查混音增益」scripts/verify-video.sh。exit code 非 0 就不许交付——任何一项 FAIL整个脚本以 exit 1 结束scripts/verify-video.sh可以在 CI 或 agent 工作流中直接当作交付闸门。验证在完整流水线中的位置在 Huashu Design 的默认导出流水线中验证是收尾的硬闸门npm run checkHyperFrames 五门审计合成侧 → npx hyperframes render --fps 60终渲 → scripts/verify-video.sh产物侧硬校验新动画项目默认走 HyperFrames 后端时合成侧审计和产物侧校验是两条互补的防线详见 references/hyperframes-backend.md走自研 Stage 管线时则用render-video.js录屏 →convert-formats.sh派生格式 →add-music.sh混 BGM最后同样落到verify-video.sh详见 references/video-export.md。整个验证体系的核心哲学是一致的能机器校验的绝不靠肉眼能让用户自己过一遍的绝不替用户默认跳过——对 HTML 用verify.py对视频产物用verify-video.sh两套脚本覆盖了设计产出的两端形成完整的交付质量闭环。【免费下载链接】huashu-designHuashu Design · HTML-native design skill for Claude Code · Claude Code 里 HTML 原生的设计 skill · 高保真原型 / 幻灯片 / 动画 20 设计哲学 5 维评审 MP4 导出 · Agent-agnostic项目地址: https://gitcode.com/gh_mirrors/hu/huashu-design创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
