企业官网建设流程全解析

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 技能的核心工作流ExportToCode（ExportToCode.md）：如何把 Claude Design 网页画布上完成的设计原型，以标准化的 handoff bundle（设计交接包）形式导出，经ProcessHandoffBundle解析为结构化简报，再交给frontend-design插件生成生产级前端代码，最后完成视觉保真校验与无障碍（a11y）门禁。读完本文，你将掌握一套可复制的"设计 → 代码"六步管线，理解交接包内部结构与三个配套工具的真实实现，并能据此规避框架错配、跳过验证等典型陷阱。

前置说明：该工作流属于 Webdesign 技能的Path 3（ClaudeDesign 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 前置条件（Preflight）

SKILL.md 的 Prerequisites 明确指出，以下检查仅适用于 Path 3：

1. Interceptor 技能可用——which interceptor能返回路径；否则需先完成Skill("Interceptor")的安装；
2. 已认证的 claude.ai 会话——interceptor-testChrome 配置档必须已登录 claude.ai，未登录时会命中营销墙而非应用；
3. Claude Design 访问权——订阅需包含 Claude Design（Pro、Max、Team 或经管理员开启的 Enterprise）；
4. IntegrateIntoApp额外要求——父项目路径 + 框架标识（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/bundle"

bundle格式会产出一个包含以下内容的目录：

• PROMPT.md——Claude Design 撰写的结构化交接简报；
• tokens.json——设计令牌（颜色、排版、间距）；
• components/——组件脚手架（如适用）；
• assets/——图片、字体、图标；
• preview.html——静态参考渲染。

2.1 源码视角：DriveClaudeDesign.ts的 bundle 子命令

查看 DriveClaudeDesign.ts 的commandBundle实现，可还原导出过程的底层行为：

1. 通过 Interceptor 读取当前页面的无障碍树（interceptor tree --json）；
2. 用标签启发式匹配 handoff 入口：正则/Claude Code|handoff|Send to Claude/i，命中后click该节点；若未命中则把整棵无障碍树 dump 到/tmp/claude-design-tree-<ts>.json并以退出码 3 中止；
3. 等待 3 秒后，在~/Downloads中查找最近 20 秒内下载的.zip文件（newestDownload(20, /\.zip$/i)）；
4. 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 按role=textbox/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 摘要，可直接喂给下一个 Agent（frontend-design插件）。

3.1 交接包规范（Bundle Spec）

HandoffBundleSpec.md 定义了交接包的标准结构（当前 schema 版本为1）：

<bundle-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_type（full | 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的图片额外归入logos，README.md/HANDOFF.md/NOTES.md归入notes；
• tokens.json 解析：JSON 解析失败时不会崩溃，而是把错误写入tokensError字段；
• 安全上限：目录遍历深度限制为 6 层、文件数上限 5000，超出即抛file-count-cap-exceeded；
• 输出结构：默认模式输出{ bundleDir, promptFrontmatter, promptBody, assets, summary }的完整 JSON；--brief模式渲染一份人读简报，包含 frontmatter 键值对、各分类文件数与示例文件名、集成注意事项，并附一句可直接交给前端构建上下文的单行指令：

  Integrate the assets in<bundle-dir>usingtokens.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 给出了完整的框架对照表：

HandoffBundleSpec.md 的框架脚手架章节进一步列出了各框架的主文件与配置文件组合（如 astro 产pages/*.astro+astro.config.mjs，next 产app/*/page.tsx+next.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、timestamp，pass为截图成功且 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[] }：

输出中的engine固定为"interceptor-tree-heuristic"，limitations数组明确列出三项盲区（无对比度检查、无动态 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 节）已经覆盖了六种框架的产出形态。三个需要刻意留意的点：

1. VitePress 能力受限：只适合静态内容，动态路由与数据请求不在其能力范围内；
2. Astro 需要显式配置集成：astro.config.mjs中的 React islands 集成不会自动发生；
3. Vanilla HTML 最容易部署：三件套（index.html+styles.css+script.js）可无配置直落任意静态托管。

若 bundle 是为 React 导出的却被喂给 Astro 项目，结果会漂移——要么用正确框架重新导出，要么走 IntegrateIntoApp.md 做翻译（见第 9 节"框架错配"）。

9. 常见陷阱（Common Pitfalls）

仓库文档明确列出四条高频失败模式：

1. 跳过ProcessHandoffBundle——直接把原始交接包喂给frontend-design插件虽然能用，但会丢失结构化简报。永远先生成 brief；
2. 框架错配——为 React 导出的 bundle 喂给 Astro 项目会导致结果漂移。用正确框架重新导出，或走IntegrateIntoApp做翻译；
3. 把 preview.html 当作生产代码——preview.html是静态一次性渲染，不是生产代码，没有响应式纵深也没有框架集成。必须跑真实的框架构建（HandoffBundleSpec.md同样强调：preview 只适合视觉 diff、翻译失败的兜底与邮件附件，NOT suitable as production code）；
4. 不做验证——"应该能用"的导出代码常有细微问题（缺依赖、坏导入、a11y 回归）。交给下游前必须验证。

若再结合IntegrateIntoApp的陷阱清单，还应补充：跳过目标项目审计、跳过ExtractDesignSystem（Claude 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 参照 + 框架脚手架）。管线的每一步都有工具支撑与源码可查：

最后回到仓库文档的立场：对于一切以代码为落点的设计工作，优先使用原生/design-sync（Path 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