LifeOS Webdesign 设计交接：从 Claude Design Bundle 导出到生产级前端代码的完整管线

LifeOS Webdesign 设计交接从 Claude Design Bundle 导出到生产级前端代码的完整管线【免费下载链接】LifeOS⛰️ The Life Operating System — an intent engineering platform that moves you from your current state to your ideal state, in life and work.项目地址: https://gitcode.com/GitHub_Trending/pe/LifeOS导读本文讲解 LifeOS 仓库中 Webdesign 技能的核心工作流ExportToCodeExportToCode.md如何把 Claude Design 网页画布上完成的设计原型以标准化的 handoff bundle设计交接包形式导出经ProcessHandoffBundle解析为结构化简报再交给frontend-design插件生成生产级前端代码最后完成视觉保真校验与无障碍a11y门禁。读完本文你将掌握一套可复制的设计 → 代码六步管线理解交接包内部结构与三个配套工具的真实实现并能据此规避框架错配、跳过验证等典型陷阱。前置说明该工作流属于 Webdesign 技能的Path 3ClaudeDesign via Interceptor是网页画布场景下的后备路径。若环境中存在原生/design-sync命令Path 2官方优先推荐使用其确定性的同步路径见 NativeDesignSync.md本路径在仓库文档中被明确标注为 experimental其依赖的interceptor-test浏览器配置档当前未登录 claude.ai从未端到端运行过见 SKILL.md。1. 工作流定位与触发入口ExportToCode 在 Webdesign 技能的工作流路由表中对应触发短语export to code、ship to code、send to Claude Code、process handoff bundle、turn this into a component从 SKILL.md 的路由表可以看到该工作流与前后的 CreatePrototype.md设计原型、IntegrateIntoApp.md集成进现有应用、DeployDesign.md部署上线共同构成一条完整的设计交付链CreatePrototype → ExportToCode → IntegrateIntoApp / DeployDesign。ExportToCode 处于链条中设计 → 代码的转换枢纽位置。1.1 输入要求工作流接受两类输入二选一均为必填活跃的 Claude Design 会话画布上已有可导出的原型已有的 handoff bundle一个先前从 Claude Design 导出的目录注意交接包是目录而非单个文件这是仓库 Gotchas 中反复强调的单位概念。可选输入框架目标Framework target覆盖交接包默认的框架输出目录Output directory生成代码的落盘位置。1.2 前置条件PreflightSKILL.md 的 Prerequisites 明确指出以下检查仅适用于 Path 3Interceptor 技能可用——which interceptor能返回路径否则需先完成Skill(Interceptor)的安装已认证的 claude.ai 会话——interceptor-testChrome 配置档必须已登录 claude.ai未登录时会命中营销墙而非应用Claude Design 访问权——订阅需包含 Claude DesignPro、Max、Team 或经管理员开启的 EnterpriseIntegrateIntoApp额外要求——父项目路径 框架标识next / astro / vitepress / vite-react / vue / vanilla。前置条件缺失时须显式停下并给出修复步骤文档规定绝不静默降级Never silently fall back。2. 第一步从 Claude Design 导出 Bundle如果原型还在画布上先用DriveClaudeDesign.ts导出交接包OUT${LIFEOS_DOWNLOADS_DIR:-$HOME/Downloads}/webdesign/export/$(date %Y%m%d-%H%M%S) mkdir -p $OUT bun ~/.claude/skills/Webdesign/Tools/DriveClaudeDesign.ts export bundle $OUT/bundlebundle格式会产出一个包含以下内容的目录PROMPT.md——Claude Design 撰写的结构化交接简报tokens.json——设计令牌颜色、排版、间距components/——组件脚手架如适用assets/——图片、字体、图标preview.html——静态参考渲染。2.1 源码视角DriveClaudeDesign.ts的 bundle 子命令查看 DriveClaudeDesign.ts 的commandBundle实现可还原导出过程的底层行为通过 Interceptor 读取当前页面的无障碍树interceptor tree --json用标签启发式匹配 handoff 入口正则/Claude Code|handoff|Send to Claude/i命中后click该节点若未命中则把整棵无障碍树 dump 到/tmp/claude-design-tree-ts.json并以退出码 3 中止等待 3 秒后在~/Downloads中查找最近 20 秒内下载的.zip文件newestDownload(20, /\.zip$/i)unzip -q解压到目标目录并清理压缩包。该工具同时支持open、prompt brief、screenshot out-path以及export html|pdf|pptx|canva|url out-dir等子命令——注意export的合法格式列表在源码中硬编码为[html, pdf, pptx, canva, url]bundle与tokens是单独的子命令。UI 定位完全依赖无障碍树启发式composer 按roletextbox/contenteditable 匹配发送按钮按/send|submit|arrow/匹配导出按钮按/export/i匹配这正是仓库文档将其标注为未经验证、依赖测试配置档登录的原因——移动的按钮不是阻塞点缺失的认证与原生 CLI 的取代才是。2.2 导出格式选择矩阵ExportFormats.md 给出了完整决策矩阵核心结论是只要代码是最终目的地Bundle 就是唯一正确的导出格式。June 2026 更新虽然把导出面板扩展到了 Adobe、Base44、Canva、Gamma、Lovable、Miro、Replit、Vercel、Wix 等直连目的地但那些是交给非 LifeOS 工具的平台交接不是落进自己仓库的代码路径。对于把原型转成自己的代码应走Bundle → ExportToCode → DeployDesign或Bundle → IntegrateIntoApp。3. 第二步解析交接包并生成集成简报bun ~/.claude/skills/Webdesign/Tools/ProcessHandoffBundle.ts $OUT/bundle $OUT/bundle.json bun ~/.claude/skills/Webdesign/Tools/ProcessHandoffBundle.ts $OUT/bundle --brief $OUT/integration-brief.md--brief标志会产出一份 Markdown 摘要可直接喂给下一个 Agentfrontend-design插件。3.1 交接包规范Bundle SpecHandoffBundleSpec.md 定义了交接包的标准结构当前 schema 版本为1bundle-root/ ├── PROMPT.md # 必填。给 frontend-design 插件的结构化简报 ├── tokens.json # 必填。JSON 设计令牌 ├── preview.html # 必填。静态预览渲染 ├── README.md # 推荐。交接包元数据 ├── manifest.json # 推荐。框架 版本元数据 ├── components/ # 可选。组件脚手架 │ └── component.{tsx,jsx,vue,astro,html} ├── pages/ # 可选。页面脚手架多页交接包 │ └── route.{tsx,jsx,vue,astro,html} ├── assets/ # 可选。二进制资源 │ ├── images/ │ ├── fonts/ │ ├── icons/ │ └── logos/ └── integration/ # 可选。框架特定配置 ├── tailwind.config.ts ├── astro.config.mjs └── ...PROMPT.md 是交接包的心脏它由 frontmatter 结构化 Markdown 正文组成是 Claude Design 与代码消费方之间的首要契约。frontmatter 包含generated_by、generated_at、claude_design_session、framework、design_system、handoff_typefull | partial | token-only等字段正文则依次覆盖 Project Purpose、Audience、Aesthetic Direction、Framework Target、Sections页面逐区块或组件的 Props/变体/状态、Component Inventory、Integration Notes、Must-Preserve、Must-NOT 等章节。当交接包喂给 Claude Code 时插件先读 PROMPT.md其余文件都是上下文。tokens.json 是机器可读的设计令牌采用框架无关的 JSON schema消费方负责翻译成自己的格式{ $schema: https://claude.ai/design/tokens.schema.json, version: 1, metadata: { name: design-system-name, source: claude-design, generated_at: ISO8601 }, color: { primary: { 50: #f0f9ff, 500: #0ea5e9, 900: #0c4a6e }, neutral: { 0: #ffffff, 50: #fafafa, 100: #f5f5f5, 900: #111111, 1000: #000000 }, accent: { 500: #f59e0b }, semantic: { success: #10b981, warning: #f59e0b, error: #ef4444, info: #3b82f6 } }, typography: { display: { family: Fraunces, weights: [400, 600, 800], scale: { sm: 24, md: 32, lg: 48, xl: 64, 2xl: 96 } }, body: { family: Inter Tight, weights: [400, 500, 700], scale: { xs: 12, sm: 14, md: 16, lg: 18, xl: 20 }, lineHeight: { tight: 1.2, normal: 1.5, loose: 1.75 } }, mono: { family: JetBrains Mono, weights: [400, 500], scale: { sm: 12, md: 14, lg: 16 } } }, spacing: { unit: 4, scale: [0, 4, 8, 12, 16, 20, 24, 32, 40, 48, 64, 80, 96, 128] }, radius: { none: 0, sm: 2, md: 6, lg: 12, xl: 24, full: 9999 }, shadow: { sm: 0 1px 2px rgba(0,0,0,0.05), md: 0 4px 8px rgba(0,0,0,0.08), lg: 0 12px 24px rgba(0,0,0,0.12) }, motion: { duration: { fast: 150, normal: 250, slow: 400 }, easing: { standard: cubic-bezier(0.4, 0, 0.2, 1), enter: cubic-bezier(0, 0, 0.2, 1), exit: cubic-bezier(0.4, 0, 1, 1) } } }Tailwind 配置、Styled Components 主题、CSS 自定义属性都可以从此文件派生。manifest.json则记录框架名与版本约束、必需依赖如tailwindcss 3.4.0、组件/页面数量、资源总字节数与 claude.ai 会话链接。3.2 源码视角ProcessHandoffBundle.ts的解析逻辑查看 ProcessHandoffBundle.ts其parseBundle的校验/分类逻辑与规范一一对应硬性存在性校验PROMPT.md缺失时直接process.exit(2)并输出{error: no-prompt-md, ...}--brief之外的多余参数同样以退出码 2 报 usage 错误按扩展名分类资源图片png/jpg/jpeg/webp/gif/svg/avif、字体woff/woff2/ttf/otf/eot、组件tsx/jsx/vue/svelte、代码ts/js/mjs/cjs/css/scss/html文件名匹配/logo|mark|brand/i的图片额外归入logosREADME.md/HANDOFF.md/NOTES.md归入notestokens.json 解析JSON 解析失败时不会崩溃而是把错误写入tokensError字段安全上限目录遍历深度限制为 6 层、文件数上限 5000超出即抛file-count-cap-exceeded输出结构默认模式输出{ bundleDir, promptFrontmatter, promptBody, assets, summary }的完整 JSON--brief模式渲染一份人读简报包含 frontmatter 键值对、各分类文件数与示例文件名、集成注意事项并附一句可直接交给前端构建上下文的单行指令Integrate the assets inbundle-dirusingtokens.json(if present) and components/ directory as the design reference.4. 第三步交接给 frontend-design 插件Anthropic 的frontend-design插件会在 Claude Code 收到前端构建请求时自动激活仓库 Gotchas 强调插件已装于官方 marketplace切勿手动调用。把交接包与简报一起喂给它Build the frontend from this handoff bundle: $OUT/bundle. Follow the integration brief at $OUT/integration-brief.md. Target framework: $FRAMEWORK. Place output in $OUT/code/.插件负责实际的代码生成——大胆的美学、有辨识度的排版、协调的调色板、生产级质量——全部基于交接包携带的 tokens 与 prompt。4.1 框架特定输出交接包的framework字段决定产出的脚手架形态ExportToCode.md 给出了完整的框架对照表框架Bundle 产出典型后续调整React Vitesrc/含组件、tailwind.config.ts、package.json按需加路由、状态管理Next.jsapp/含页面、布局、服务端组件接入数据获取、鉴权Astrosrc/pages/、src/components/含 Astro React islands在astro.config.mjs配置集成VitePress.vitepress/theme/覆写 自定义布局组件受限——仅静态内容Vuesrc/components/Vue 3 组合式 API按需加 Pinia/routerVanilla HTML单个index.htmlstyles.cssscript.js最容易落到静态托管HandoffBundleSpec.md 的框架脚手架章节进一步列出了各框架的主文件与配置文件组合如 astro 产pages/*.astroastro.config.mjsnext 产app/*/page.tsxnext.config.js等可作为上表的补充依据。5. 第四步验证生成代码视觉保真门禁# 启动本地预览取决于框架 cd $OUT/code bun install bun dev DEV_PID$! sleep 3 # 对运行中的应用截图 bun ~/.claude/skills/Webdesign/Tools/VerifyDesign.ts http://localhost:5173 $OUT/verify kill $DEV_PID将$OUT/verify/screenshot.png与$OUT/bundle/preview.html对比——保真度应在视觉容忍范围内任何回归都要标记出来。5.1 源码视角VerifyDesign.ts的校验机制查看 VerifyDesign.ts其核心是围绕 Interceptor 构建的薄冒烟检查参数url-or-path out-dir [--viewport WIDTHxHEIGHT] [--a11y|--no-a11y]viewport 默认1440x900校验范围[320, 7680]输入既可以是 URL 也可以是本地路径本地路径经pathToFileURL转成file://执行序列interceptor open→interceptor wait-stable→interceptor screenshot out/ISO时间戳.png若which interceptor找不到则退出码 127 并提示先安装 Interceptor 技能结果契约输出 JSON 含url、resolvedUrl、viewport、screenshot、a11y、pass、timestamppass为截图成功且 a11y 通过时为真最终process.exit(pass ? 0 : 1)——脚本退出码本身就是校验结果可直接接入 CI 门禁。值得注意的是源码注释的两处诚实声明viewport 会被校验和报告但不实际生效因为 Interceptor 不暴露 viewport 动词a11y 检查是无障碍树启发式而非 axe-core且存在明确的局限清单不做对比度检查、不做动态 aria-live 检查、不解析 CSS。6. 第五步无障碍a11y检查bun ~/.claude/skills/Webdesign/Tools/VerifyDesign.ts --a11y http://localhost:5173 $OUT/a11y任何critical 或 serious级别的 a11y 违规都会阻塞发布必须先修复代码再继续。6.1 a11y 启发式具体检查什么a11yFromTree对无障碍树做全量遍历walkTree检查五类违规并汇总为{ type, count, examples[] }违规类型判定条件img-altroleimg且无 name/altbutton-namerolebutton且无可访问名link-namerolea且无名称或无 hrefform-labeltextbox/combobox/spinbutton无标签heading-order首个标题不是 h1或标题级别跳跃超过 1 级输出中的engine固定为interceptor-tree-heuristiclimitations数组明确列出三项盲区无对比度检查、无动态 aria-live 检查、无 CSS 解析检查pass仅当违规列表为空时为真——即任何违规哪怕一条都会让校验不通过。7. 第六步交接给下一步导出与验证完成后按目标形态分派集成进现有应用→ 走 IntegrateIntoApp.md以$OUT/code为源。该工作流把原型作为框架感知的 diff而非绿地脚手架落进现有代码库包含十步审计目标项目探测框架、抓取现有 tokens 文件、定位组件目录→ 提取应用设计系统ExtractDesignSystem防止 Claude Design 发明一套竞争调色板→ 编写带硬约束的集成简报 → 框架翻译 →diff -urN生成补丁 →人工审查 diff关键门禁→ 建分支git checkout -b webdesign-integration-date后patch -p1应用 → 上下文内验证 → 跑bun test bun run typecheck bun run lint→ 交还调用方。集成模式分为merge默认、replace显式授权覆盖、token-only只更新 tokens。独立部署→ 走 DeployDesign.md以$OUT/code为源。预检bun install bun run build、rg -i API_KEY|SECRET|PRIVATE_KEY|sk_live|sk_test扫密钥、确认 wrangler/vercel/netlify/gh 已装→ 构建 → 按托管商部署Cloudflare Pagesbunx wrangler pages deploy dist --project-name $PROJECT、Vercelvercel deploy、Netlifynetlify deploy --dir dist、GitHub Pagesgh workflow run pages.yml、S3aws s3 sync dist s3://$BUCKET --delete→ 线上验证截图 → a11y Lighthouse 探测 → 汇报含回滚命令。文档规定非平凡改动永远先部署 preview 再上 production。8. 框架特定注意事项上表第 4.1 节已经覆盖了六种框架的产出形态。三个需要刻意留意的点VitePress 能力受限只适合静态内容动态路由与数据请求不在其能力范围内Astro 需要显式配置集成astro.config.mjs中的 React islands 集成不会自动发生Vanilla HTML 最容易部署三件套index.htmlstyles.cssscript.js可无配置直落任意静态托管。若 bundle 是为 React 导出的却被喂给 Astro 项目结果会漂移——要么用正确框架重新导出要么走 IntegrateIntoApp.md 做翻译见第 9 节框架错配。9. 常见陷阱Common Pitfalls仓库文档明确列出四条高频失败模式跳过ProcessHandoffBundle——直接把原始交接包喂给frontend-design插件虽然能用但会丢失结构化简报。永远先生成 brief框架错配——为 React 导出的 bundle 喂给 Astro 项目会导致结果漂移。用正确框架重新导出或走IntegrateIntoApp做翻译把 preview.html 当作生产代码——preview.html是静态一次性渲染不是生产代码没有响应式纵深也没有框架集成。必须跑真实的框架构建HandoffBundleSpec.md同样强调preview 只适合视觉 diff、翻译失败的兜底与邮件附件NOT suitable as production code不做验证——应该能用的导出代码常有细微问题缺依赖、坏导入、a11y 回归。交给下游前必须验证。若再结合IntegrateIntoApp的陷阱清单还应补充跳过目标项目审计、跳过ExtractDesignSystemClaude Design 一定会凭空发明 tokens、绕过 diff 人工审查、应用后不跑测试、直接合并进 main——这些都在各自的工位上有对应的防错机制。10. 时间预估Bundle 解析 插件交接2–5 分钟验证 a11y 检查追加 2–10 分钟对照参考完整单组件/单页面集成15–45 分钟复杂多路由集成应拆分为多次会话每次一个集成目标IntegrateIntoApp.md。11. 总结什么时候用这条管线ExportToCode 是 Webdesign 三路径体系中Path 3的导出环节其价值在于把视觉画布上的设计无损翻译成代码库里的生产代码核心资产是结构化的交接包PROMPT.md 契约 tokens.json 令牌 preview.html 参照 框架脚手架。管线的每一步都有工具支撑与源码可查环节工具源码位置导出 bundleDriveClaudeDesign.ts bundleDriveClaudeDesign.ts解析与简报ProcessHandoffBundle.ts [--brief]ProcessHandoffBundle.ts代码生成frontend-design插件自动激活—视觉/运行验证VerifyDesign.ts [--viewport]VerifyDesign.ts无障碍门禁VerifyDesign.ts --a11y同上a11yFromTree五类启发式最后回到仓库文档的立场对于一切以代码为落点的设计工作优先使用原生/design-syncPath 2——确定性、免浏览器自动化、免认证配置档Path 3 的 bundle 管线作为从网页画布出发的文档化后备路径保留。读者在使用本管线前应先核对 SKILL.md 的 Preflight 清单Interceptor 可用、interceptor-test配置档已登录、订阅含 Claude Design并对 Path 3 当前未经验证的状态有清醒预期。【免费下载链接】LifeOS⛰️ The Life Operating System — an intent engineering platform that moves you from your current state to your ideal state, in life and work.项目地址: https://gitcode.com/GitHub_Trending/pe/LifeOS创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考