web-artifacts-builder-v2

Web Artefacts Builder

要构建前端 claude.ai artefact，请按以下步骤操作：

1. 使用 scripts/init-artifact.sh 初始化前端仓库
2. 从 resources/themes.css 中选择一个主题并应用（参见下文“主题”）
3. 编辑生成的代码，开发你的 artefact
4. 使用 scripts/bundle-artifact.sh 打包为单个 HTML 文件
5. 将打包后的 artefact 分享给用户
6. （可选）测试 artefact

技术栈：React 19 + TypeScript + Vite 8 + Tailwind CSS v4 + shadcn/ui（new-york 风格）+ lucide-react。使用 vite-plugin-singlefile 打包。需要 Node 20.19+ 或 22.12+。

设计原则

这些原则改编自 html-design-examples skill。当你需要针对特定 artefact 意图（状态报告、代码审查、PR 文档、设计系统页面、编辑器等）的设计模式时，请同时加载该 skill；其中的渲染目录 resources/index.html 收录了 20 个单文件参考示例。

• 沉静、编辑式的美感。 克制地使用强调色，留出充足的留白，让内容本身成为焦点。避免使用主视觉渐变、营销式光泽效果和仪表板式装饰，除非 artefact 本身就是仪表板。
• 重视字体，而非装饰。 优先通过字重、字号和行距建立层次，再考虑边框、背景或彩色条。参考示例中常见的搭配是衬线标题与无衬线正文字体；如果没有其他线索，这是可靠的选择。默认只使用 Inter 会显得像 AI 生成的内容——请根据所选主题的字体说明挑选搭配。
• 让强调色发挥应有价值。 大多数主题仅提供一种强调色，应当珍惜使用。将它用于页面上最需要吸引注意力的元素（主要操作、链接、焦点状态），除此之外尽量少用。
• 在合适时充分利用宽度。 内容涉及表格、比较或空间布局时，不要将其塞进居中的窄列。对于非长篇文本内容，带有结构化列的宽幅布局比 720px 的文本栏更易读。
• 导出交互状态。 如果 artefact 是编辑器、看板或任何供用户开展工作的界面，请加入“复制为 JSON”或“复制为提示词”按钮，让结果能够回到 Agent 工作流中。可参考 html-design-examples 中的 18-editor-triage-board.html 示例。

避免俗套的规则

仅当颜色或样式表达了特定信息（例如我明确指定的状态、类别、严重程度或优先级）时，才使用视觉强调（彩色边框条纹、着色背景的提示框、卡片上的强调色条）。不要为了装饰而添加视觉强调，不要在同级项目间轮换使用调色板中的颜色来制造变化，也不要默认用带彩色条的着色提示框来标记补充说明。如果你打算添加强调元素，先想想移除它是否会导致信息丢失；如果不会，就删掉它，改用纯粹的字体层次来呈现。

其他应避免的设计，因为它们看起来像 AI 默认生成的内容：过多的居中布局、紫色渐变、所有元素都采用统一的圆角、玻璃拟态、表情符号项目符号，以及图标相同的三卡片网格主视觉。同样要避免状态永不变化的状态徽标或脉动圆点（“Active”“Verified”）、复述提示词或技术栈的文案（“Built with...”）、伪系统式命名（// 分隔符、SCREAMING_SNAKE 标签、版本胶囊、字母间距拉开的等宽字体眉题），以及工作界面中的落地页装饰（夸张的副标题、炫耀式统计数据条、将标题中的一个词设为强调色）。通过测量计算后的边界框，检查 SVG、ASCII 艺术和时间线标记的对齐情况。

主题

resources/themes.css 提供五种命名主题。开始编写组件前先选定一种——事后调整配色远比提前选好主题费力。

主题	风格	适用场景
Editorial paper	温暖的纸张色、墨色、赭黄色点缀	长篇说明、计划、报告、复盘
Technical mono	近乎单色，搭配单一绿色点缀	代码审查、系统图、状态页面、调试
Warm desaturated	沙色、陶土棕、低饱和赤陶色	与品牌相近的素材、设计页面，以及任何需要温暖感但不想过于浓烈的场景
Cool muted	沉静的石板色、低彩度的蓝绿色	仪表板、状态报告、技术文档
Nordic dark	极夜灰、霜蓝色	事故复盘、调试转储、优先考虑深色模式的开发者工具

应用主题：

1. 阅读 resources/themes.css，复制所选主题的 :root { ... } 和 .dark { ... } 代码块。
2. 替换项目 src/index.css 中现有的 :root 和 .dark 代码块。保留 @theme inline 和 @layer base 代码块——它们负责将变量接入 Tailwind 工具类。
3. 添加建议的字体栈（每个主题上方的注释块中都列有字体栈）——可以在 index.html 中通过 Google Fonts 的 <link rel="stylesheet"> 标签添加，也可以在 src/index.css 中设置 body { font-family: ... }。

如果用户已有品牌或设计系统，请优先遵循，而不是从主题库中选择。

快速开始

步骤 1：初始化项目

bash scripts/init-artifact.sh <project-name>
cd <project-name>

这会创建一个已配置好的项目，其中包括：

• React 19 + TypeScript，通过 Vite 8 构建
• Tailwind CSS v4（在 src/index.css 中采用 CSS 优先配置，无需 tailwind.config.js）
• src/components/ui/ 中的 40 多个 shadcn/ui 组件
• radix-ui 聚合包和 lucide-react
• 在 tsconfig.json 和 vite.config.ts 中配置的路径别名 @/
• 可供你编辑的精简版 App.tsx 占位文件

步骤 2：应用主题

参见上文“主题”。

步骤 3：开发素材

编辑 src/App.tsx，并根据需要添加组件。组件从 @/components/ui/<name> 导入。cn() 辅助函数位于 @/lib/utils。

开发过程中预览：

pnpm dev

步骤 4：打包为单个 HTML 文件

bash scripts/bundle-artifact.sh

这会生成 bundle.html——一个包含所有内联 JS、CSS 和素材的独立文件。该脚本会：

• 将 vite-plugin-singlefile 添加为开发依赖
• 编写 vite.config.bundle.ts，扩展你的配置以加入单文件插件和内联选项
• 运行 vite build --config vite.config.bundle.ts
• 将 dist/index.html 重命名为 bundle.html

该素材在运行时无需任何依赖——直接交给用户即可。

步骤 5：分享给用户

将 bundle.html 交给用户，作为该素材。

步骤 6：测试（可选）

只有在用户提出要求，或素材包含你不希望带着故障交付的交互逻辑时，才在分享前测试。使用 Playwright 或在本地打开文件。否则，优先快速交付，再根据反馈迭代。

参考资料

• shadcn/ui 组件：https://ui.shadcn.com/docs/components
• Tailwind CSS v4 文档：https://tailwindcss.com/docs
• 设计模式配套技能：html-design-examples