static-web-artifacts-builder

静态网页作品构建器

要构建高密度静态信息图作品，请按以下步骤操作：

1. 使用 scripts/init-artifact.sh 初始化项目脚手架
2. 编辑生成的 HTML 文件，开发你的作品
3. 使用 scripts/bundle-artifact.sh 验证并完成作品
4. 向用户展示作品

技术栈：原生 HTML5 + CSS3（Grid/Flexbox）+ 内联 SVG — 零运行时依赖

设计与样式指南

非常重要：为避免出现通常所说的“AI 垃圾内容”，请避免过度居中的布局、紫色渐变、统一的圆角和 Inter 字体。

信息图专属要求

• 密度：内容与留白比例 ≥ 70:30。尽可能提高每像素的信息量。
• 几何形态：使用分层／嵌套容器、异形区域（clip-path、不同的 border-radius）、渐变填充和细微的 box-shadow — 不要使用扁平统一的方框。
• 图标：为每个主要概念添加内联 SVG 图标。不要只用纯文本标签。
• 颜色：使用有明确目的的配色方案（3-4 种色相 + 中性色），通过颜色表达含义（类别、流向、严重程度）。使用 CSS 自定义属性定义颜色。
• 流程：使用带 SVG 箭头、曲线路径和标签的定向连接线。架构图应采用分层结构并展示双向数据流，而不是扁平的节点图。
• 布局计算：使用 CSS Grid，并通过 grid-template-columns/grid-template-rows 显式分配比例。不要使用自动间距默认值。每个 margin/padding 都应经过有意设计。

快速开始

步骤 1：初始化项目

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

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

这会创建一个精简的脚手架，其中包含：

• ✅ 带有 CSS 自定义属性（主题）的 HTML 模板
• ✅ CSS Grid + Flexbox 布局工具（内联 <style>）
• ✅ 可用于打印的视口 meta 配置
• ✅ 不包含 node_modules、package.json 或构建工具链

步骤 2：开发作品

直接编辑生成的 index.html。每个 HTML 文件对应一个页面，传达一个清晰的信息。

关键模式：

• 使用 CSS Grid grid-template-areas 定义命名区域布局
• 使用 fr 单位按比例分配空间
• 内联嵌入 SVG 图标（而不是引用外部文件）
• 使用 CSS 自定义属性（--color-primary、--color-accent 等）保持配色协调
• 使用 clip-path、border-radius、渐变和 box-shadow 增强视觉层次

步骤 3：验证并完成

bash scripts/bundle-artifact.sh

此步骤会验证作品是否完全自包含：

• 检查是否不存在外部资源引用（无 CDN 链接、外部样式表或脚本）
• 验证是否包含内联 SVG
• 报告文件大小
• 将通过验证的输出复制到 bundle.html

步骤 4：与用户分享作品

在对话中将通过验证的 HTML 文件分享给用户，以便他们将其作为作品查看。

---

何时使用此技能，何时使用其他视觉技能

任务	使用此技能	改用
包含多个部分、数据密度高的丰富信息图	是	—
包含交互式标签页或切换开关的独立仪表板	是	—
静态架构／拓扑图，之后可在 Figma/Illustrator 中编辑	否	architecture-diagram — 生成真正的矢量 SVG，而非此技能生成的交互式 HTML
简单的概念插画或图标风格图像	否	concept-to-image
幻灯片或多页演示文稿	否	html-presentation
CSS Grid 布局控制至关重要的单页视觉作品	是	—
成品必须可通过 Playwright 截图	是（但有注意事项，见限制）	—

---

错误处理

错误	原因	解决方案
bundle-artifact.sh 检测到 CDN 链接	HTML 中引用了外部样式表或脚本	将所有 CSS 和 JS 内联 — 输出中不允许包含外部 URL
浏览器中内容溢出／被裁切	视口过小，或固定高度搭配 overflow:hidden	使用 min-height 而非 height；在 1440px 宽度下测试；在可滚动区域使用 overflow: auto
Playwright 截图裁掉了内容	页面高度超出截图视口	将 page.setViewportSize 设为与内容尺寸一致；使用 fullPage: true
bundle-artifact.sh 报告缺少内联 SVG	SVG 通过 <img src> 或外部引用加载	直接在 HTML 中替换为内联 <svg> 块
文件过大，无法作为成品分享	嵌入了 base64 图像或 SVG 过于冗长	优化 SVG 路径；避免嵌入栅格图像

---

限制

• 截图需要浏览器：渲染和基于 Playwright 的截图捕获需要浏览器运行环境。HTML 文件本身不依赖服务器端，但视觉验证需要浏览器。
• 不支持服务器端渲染：输出完全在客户端运行。不支持动态数据、API 调用或服务器计算的内容。
• 不保留状态：成品没有后端。用户交互（表单输入、切换开关）会在页面重新加载时重置，且无法保存。
• 文件大小建议：尽量控制在 500KB 以下。超过 1MB 的成品在某些 Claude 界面中可能无法以内联对话成品的形式渲染。
• 字体可用性：仅使用系统字体（或内联的 base64 编码 Web 字体）。不要引用 Google Fonts 或其他外部字体 CDN。
• 打印保真度：支持 CSS 打印媒体查询，但浏览器的打印渲染效果各不相同。如果打印输出是必需项，请明确测试 @media print。