building-web-artifacts

---

构建 Web Artifact

要构建强大的前端 opencode artifact，请按以下步骤操作：

1. 使用 scripts/init-artifact.sh 初始化前端仓库
2. 编辑生成的代码来开发 artifact
3. 使用 scripts/bundle-artifact.sh 将所有代码打包成单个 HTML 文件
4. 保存 artifact 文件，并告知用户文件所在位置 5.（可选）测试 artifact

技术栈：React 18 + TypeScript + Vite + Parcel（打包）+ Tailwind CSS + shadcn/ui

设计与样式指南

必需的子技能： 编写组件前，请使用 designing-frontend-interfaces。先编写设计简述并锁定 token 块——shadcn 的默认设置只是起点，并非设计；不加修改地直接使用，会产出本节所警示的千篇一律的结果。

发布前也必须使用：用于覆盖状态的 designing-user-experience，以及用于支持键盘和屏幕阅读器的 building-accessible-interfaces。

需要避免的典型平庸风格： 所有内容都居中并使用 max-w-4xl、白色背景上的紫色／紫罗兰色→蓝色渐变、所有表面统一使用 rounded-lg、到处使用 shadow-md、将 Inter 或 system-ui 用作展示字体、正文使用 text-gray-500，以及“主视觉区 → 三张功能卡片 → CTA”的固定框架。

配置 Tailwind，不要照单全收

Tailwind 的默认值只是一组默认配色——直接使用它们，会让 artifact 的外观趋于雷同。请使用设计简述中的 token 块覆盖默认值：

// tailwind.config.js
export default {
  theme: {
    extend: {
      colors: {
        base: "#f7f6f0", surface: "#fffffb", line: "#dcded1",
        ink: { DEFAULT: "#1a271a", 2: "#4a5a46", 3: "#79876f" },
        accent: { DEFAULT: "#2f6b3c", ink: "#f4fbf5" },
      },
      fontFamily: {
        display: ['"Young Serif"', "Georgia", "serif"],
        text: ['"Work Sans"', "system-ui", "sans-serif"],
      },
      borderRadius: { DEFAULT: "2px" },   // ONE radius
    },
  },
};

现在，bg-base、text-ink-2、border-line、font-display 都承载着明确的语义，而且只需修改一个文件即可切换主题。applying-themes 技能提供十种经过对比度验证、可直接用于此处的配色方案。

如果你决定使用其他圆角值，也要禁用 shadcn 的默认圆角变量——globals.css 中的 --radius 会悄然应用于每个组件。

组件与状态要求

artifact 中每个由数据驱动的组件都需要覆盖完整的状态集合——状态矩阵请参阅 designing-user-experience。在自包含的 artifact 中，这些状态很容易被遗漏，因为通常没有真实后端来强制处理它们。

if (error)          return <ErrorState onRetry={refetch} message={...} />;
if (loading)        return <Skeleton />;              // matching the real layout
if (!items.length)  return query ? <NoResults query={query} onClear={...} />
                                 : <FirstRun onCreate={...} />;
return <List items={items} />;

这两种空状态并不相同，而且都不可或缺。生成的 artifact 最常见的捷径，就是两者都显示 No data。

Artifact 的无障碍访问

shadcn/ui 构建于 Radix 之上，因此只要按预期使用，其基础组件就具备无障碍访问能力。问题出在你添加的部分：

• 仅包含图标的按钮需要 aria-label——Radix 无法推断其内容
• 自定义的 <div onClick> 处理程序会绕过 Radix 提供的所有功能；请使用 <Button>
• 移除焦点环的 className 覆盖（例如使用 focus:outline-none，却未提供替代焦点环）会破坏键盘导航
• 图表和画布需要文本替代内容——用说明文字陈述其结论
• 更换主题后请验证对比度；Radix 不会检查你的颜色

性能

artifact 是完全自包含的单个文件，因此整个加载时间取决于打包文件的大小。

• 将字体以内联 base64 woff2 的形式嵌入，并仅包含所用字符。完整的 TTF 文件可能比其余整个包还大。
• 不要导入图标库。 import { X } from "lucide-react" 可能会引入整个图标集，具体取决于 tree-shaking。请粘贴所需的单个 SVG。
• 对超过约 200 行的列表进行虚拟化。 渲染数千个 DOM 节点会让浏览器标签页卡死。
• 对大型列表中的行使用 React.memo；保持 key 稳定。
• 不要发起外部请求。 artifact 经常运行在会阻止 CDN、远程字体和 fetch 的 CSP 下。所有内容都必须内联。

验证

展示 artifact 前，请打开 bundle.html 并进行检查：

python3 -c "
from playwright.sync_api import sync_playwright
with sync_playwright() as p:
    b = p.chromium.launch(); pg = b.new_page(viewport={'width':1440,'height':900})
    errs=[]; pg.on('console', lambda m: m.type=='error' and errs.append(m.text))
    pg.on('pageerror', lambda e: errs.append(str(e)))
    pg.goto('file://$PWD/bundle.html'); pg.wait_for_timeout(1200)
    pg.screenshot(path='/tmp/artifact.png', full_page=True)
    pg.set_viewport_size({'width':390,'height':844})
    pg.screenshot(path='/tmp/artifact-mobile.png', full_page=True)
    print('CONSOLE ERRORS:', errs); b.close()"

然后查看两张截图。打包成功并不代表渲染正常——缺失的内联资源、CSP 违规或延迟渲染分支中的运行时错误，都可能导致构建成功却只显示空白页面。

快速入门

步骤 1：初始化项目

运行初始化脚本以创建新的 React 项目：

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

这将创建一个完整配置的项目，其中包含：

• ✅ React + TypeScript（通过 Vite）
• ✅ Tailwind CSS 3.4.1 和 shadcn/ui 主题系统
• ✅ 已配置路径别名（@/）
• ✅ 预装 40 多个 shadcn/ui 组件
• ✅ 包含所有 Radix UI 依赖项
• ✅ 已配置 Parcel 以进行打包（通过 .parcelrc）
• ✅ 兼容 Node 18+（自动检测并固定 Vite 版本）

步骤 2：开发你的产物

要构建产物，请编辑生成的文件。请参阅下方的常见开发任务以获取指导。

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

要将 React 应用打包为单个 HTML 产物：

bash scripts/bundle-artifact.sh

这将生成 bundle.html，这是一个独立的产物，其中内联了所有 JavaScript、CSS 和依赖项。此文件可作为产物直接分享到与 Agent 的对话中。

要求：项目根目录中必须有一个 index.html。

脚本执行的操作：

• 安装打包依赖项（parcel、@parcel/config-default、parcel-resolver-tspaths、html-inline）
• 创建支持路径别名的 .parcelrc 配置
• 使用 Parcel 构建（不生成源映射）
• 使用 html-inline 将所有资源内联到单个 HTML 文件中

步骤 4：与用户分享产物

最后，在对话中与用户分享打包后的 HTML 文件，让他们可以将其作为产物查看。

步骤 5：测试/预览产物（可选）

注意：此步骤完全可选。仅在必要或用户要求时执行。

要测试/预览产物，请使用可用工具（包括其他 Skills 或 Playwright、Puppeteer 等内置工具）。一般来说，请避免预先测试产物，因为这会增加用户看到最终产物的等待时间。如果用户提出要求或出现问题，可在展示产物后再进行测试。

参考

• shadcn/ui 组件：https://ui.shadcn.com/docs/components