artifacts-builder

Artifacts 构建器

概述

生成自包含、达到生产质量的 HTML/CSS/JS 产物，无需构建步骤即可在任何现代浏览器中运行。每个产物都是一个单独文件（或最少数量的文件集），包含交互式演示、原型、数据可视化或实用工具所需的一切内容。重点关注渐进增强、响应式设计和整洁的代码。

阶段 1：范围定义

1. 明确产物的用途（演示、原型、工具、可视化）
2. 确定交互级别（静态、交互式、数据驱动）
3. 确定所需依赖项（无、通过 CDN 加载、嵌入）
4. 定义响应式要求（移动设备、桌面设备、两者兼顾）
5. 设定限制条件（文件大小、浏览器支持、离线能力）

停止 — 在做出架构决策前，与用户确认范围和限制条件。

产物类型决策表

用途	复杂度	依赖项	示例
静态演示	低	无	产品模型、落地页
交互式小组件	中	无或 Alpine.js	计算器、表单构建器
数据可视化	中到高	D3.js 或 Chart.js	仪表盘、图表浏览器
原型	中	Alpine.js 或 Petite-Vue	可点击的 UI 原型
实用工具	中到高	不定	JSON 格式化工具、颜色选择器
生成式艺术	中	无	Canvas 动画、图案生成器
演示文稿	中	无或 Mermaid	幻灯片、图表查看器

阶段 2：架构

1. 选择单文件或多文件方案
2. 选择 CDN 依赖项（如有）
3. 规划文件中的组件结构
4. 定义状态管理方案
5. 规划渐进增强层

停止 — 提交架构和依赖项选择，等待批准。

架构决策表

限制条件	单文件	多文件
便于分享（电子邮件、粘贴）	是	否
文件大小 < 100KB	是	均可
多个页面/视图	可行（SPA）	更合适
团队协作	困难	更合适
离线使用	是（自包含）	需要打包
SEO 要求	不适用	不适用（产物是工具）

依赖项决策表

需求	推荐方案	CDN URL	大小
轻量级响应式	Alpine.js	cdn.jsdelivr.net/npm/alpinejs@3	~15KB
精简版类 Vue 框架	Petite-Vue	unpkg.com/petite-vue	~6KB
图表	Chart.js	cdn.jsdelivr.net/npm/chart.js@4	~65KB
数据可视化	D3.js	cdn.jsdelivr.net/npm/d3@7	~90KB
图表	Mermaid	cdn.jsdelivr.net/npm/mermaid@10	~120KB
CSS 框架（原型）	Tailwind Play CDN	cdn.tailwindcss.com	运行时
图标	Lucide	unpkg.com/lucide@latest	按需加载
无需依赖项	Vanilla JS	不适用	0KB

CDN 使用规则

规则	原因
锁定主版本（@3、@7）	避免破坏性变更
最多使用 3 个 CDN 依赖项	保持产物轻量
添加 integrity 和 crossorigin	防范 CDN 被入侵
提供优雅降级	CDN 失效时仍可运行
优先选择更小的替代方案	选择 Alpine 而非 React，Petite-Vue 而非 Vue

阶段 3：实现

1. 构建语义化 HTML 结构
2. 添加 CSS（内联 <style> 或嵌入）
3. 实现 JavaScript 功能
4. 添加错误处理和回退方案
5. 在不同视口和浏览器中测试

停止 — 交付给用户前，确认产物运行正常。

模板结构

<!DOCTYPE html>
<html lang="en">
<head>
  <meta charset="UTF-8">
  <meta name="viewport" content="width=device-width, initial-scale=1.0">
  <title>[Artifact Title]</title>
  <style>
    /* Reset */
    *, *::before, *::after { box-sizing: border-box; margin: 0; padding: 0; }

    /* Design Tokens */
    :root {
      --color-bg: #ffffff;
      --color-text: #1a1a2e;
      --color-primary: #3b82f6;
      --color-border: #e2e8f0;
      --radius: 0.5rem;
      --space: 1rem;
      --font: system-ui, -apple-system, sans-serif;
    }

    @media (prefers-color-scheme: dark) {
      :root {
        --color-bg: #0f172a;
        --color-text: #e2e8f0;
        --color-primary: #60a5fa;
        --color-border: #334155;
      }
    }

    /* Base Styles */
    body {
      font-family: var(--font);
      background: var(--color-bg);
      color: var(--color-text);
      line-height: 1.6;
    }

    /* Component Styles */
    /* ... */
  </style>
</head>
<body>
  

  <script>
    // Application logic
    (function() {
      'use strict';
      // ...
    })();
  </script>
</body>
</html>

响应式设计模式

基于容器的布局

.container {
  width: min(100% - 2rem, 1200px);
  margin-inline: auto;
}

.grid {
  display: grid;
  grid-template-columns: repeat(auto-fit, minmax(min(300px, 100%), 1fr));
  gap: var(--space);
}

移动优先的媒体查询

/* Base: mobile */
.layout { display: flex; flex-direction: column; }

/* Tablet and up */
@media (min-width: 768px) {
  .layout { flex-direction: row; }
  .sidebar { width: 280px; flex-shrink: 0; }
}

渐进增强

层	用途	要求
HTML	内容易于访问且有意义	无 CSS 或 JS 时也能正常运行
CSS	视觉呈现和布局	无 JS 时也能正常运行
JavaScript	增强交互性	添加动态行为

特性检测

// Check before using modern APIs
if ('IntersectionObserver' in window) {
  // Use lazy loading
} else {
  // Load all images immediately
}

if (CSS.supports('backdrop-filter', 'blur(10px)')) {
  element.classList.add('glass-effect');
}

状态管理（无框架）

简单状态模式

function createStore(initialState) {
  let state = { ...initialState };
  const listeners = new Set();

  return {
    getState: () => ({ ...state }),
    setState(updates) {
      state = { ...state, ...updates };
      listeners.forEach(fn => fn(state));
    },
    subscribe(fn) {
      listeners.add(fn);
      return () => listeners.delete(fn);
    },
  };
}

基于 URL 的状态（用于可分享的产物）

function syncStateWithURL(store) {
  const params = new URLSearchParams(location.search);
  for (const [key, value] of params) {
    store.setState({ [key]: JSON.parse(value) });
  }
  store.subscribe(state => {
    const params = new URLSearchParams();
    Object.entries(state).forEach(([k, v]) => params.set(k, JSON.stringify(v)));
    history.replaceState(null, '', `?${params}`);
  });
}

导出格式

格式	使用场景	方法
单个 HTML 文件	分享、嵌入	自包含的 <style> 和 <script>
HTML + 资源	复杂产物	独立的 CSS/JS 文件
Data URL	内嵌	data:text/html;base64,...
截图/PNG	文档	html2canvas 或浏览器截图
PDF	打印/报告	使用打印样式的 window.print()

质量检查清单

• 有效的 HTML5（<!DOCTYPE html>、lang 属性）
• 响应式 viewport meta 标签
• 无需 JavaScript 也能正常工作（内容可见）
• 支持深色模式（prefers-color-scheme）
• 可通过键盘导航
• 无控制台错误
• 文件大小低于 100KB（不含图片）
• 已通过跨浏览器测试（Chrome、Firefox、Safari）
• 适用时包含打印样式
• 适当使用语义化 HTML 元素

反模式 / 常见错误

反模式	错误原因	替代做法
在单文件产物中使用 React/Vue/Angular	对简单交互而言开销过大	使用 Alpine.js 或原生 JS
简单 UI 却从 CDN 加载大型框架	加载缓慢、浪费带宽	让依赖的体量与需求相匹配
使用内联样式而非 CSS 自定义属性	无法切换主题，也不支持深色模式	使用 CSS 自定义属性（tokens）
不处理用户输入错误	错误输入会导致崩溃	验证输入并提供反馈
固定像素尺寸	在手机和平板上显示异常	使用响应式单位（%、rem、vw）
缺少 <meta viewport>	移动设备会以桌面缩放比例渲染	始终包含 viewport meta 标签
在 <head> 中使用阻塞式 <script>	延迟页面渲染	使用 defer 属性，或将其放在 body 末尾
脚本没有 IIFE 包装	污染全局作用域	使用 (function() { ... })() 包装
颜色硬编码且未使用 tokens	无法切换主题	使用 CSS 自定义属性

集成点

技能	集成方式
ui-ux-pro-max	样式选择和 UX 指南
ui-design-system	用于统一主题的设计 tokens
canvas-design	在产物中创建 Canvas/SVG 可视化
senior-frontend	复杂组件模式
mobile-design	适配移动设备的产物设计
planning	在规划阶段确定产物范围

技能类型

灵活 — 根据产物需求调整架构、依赖项和复杂度。简单演示应尽可能精简；复杂工具可以使用轻量级框架和多个 CDN 依赖项。