static-web-artifacts-builder

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Static Web Artifacts Builder

静态Web产物构建器

To build high-density static infographic artifacts, follow these steps:

Initialize the project scaffold using
```
scripts/init-artifact.sh
```
Develop your artifact by editing the generated HTML file(s)
Validate and finalize using
```
scripts/bundle-artifact.sh
```
Display artifact to user

Stack: Vanilla HTML5 + CSS3 (Grid/Flexbox) + inline SVG — zero runtime dependencies

如需构建高密度静态信息图产物，请遵循以下步骤：

使用
```
scripts/init-artifact.sh
```
初始化项目脚手架
编辑生成的HTML文件来开发你的产物
使用
```
scripts/bundle-artifact.sh
```
验证并完成打包
向用户展示产物

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

Design & Style Guidelines

设计与样式指南

VERY IMPORTANT: To avoid what is often referred to as "AI slop", avoid excessive centered layouts, purple gradients, uniform rounded corners, and Inter font.

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

Infographic-Specific Constraints

信息图特定约束

Density: Content-to-whitespace ratio ≥ 70:30. Maximize signal per pixel.
Geometry: Layered/nested containers, shaped regions (clip-path, border-radius variations), gradient fills, subtle box-shadows — not flat uniform boxes.
Iconography: Inline SVG icons for every major concept. No naked text labels.
Color: Purposeful palette (3-4 hues + neutrals), encoding meaning (category, flow direction, severity). Define as CSS custom properties.
Flows: Directional connectors with SVG arrowheads, curved paths, labeled edges. Architecture diagrams = layered tiers with bidirectional data flows, not flat node graphs.
Layout math: CSS Grid with explicit
```
grid-template-columns
```
/
```
grid-template-rows
```
fractional allocations. No auto-spacing defaults. Every margin/padding intentional.

密度：内容与留白比例≥70:30，最大化每像素的信息价值。
几何设计：分层/嵌套容器、异形区域（clip-path、差异化border-radius）、渐变填充、微妙的盒子阴影——不要使用扁平统一的方框。
图标规范：所有核心概念都搭配内联SVG图标，不要使用纯文本标签。
色彩规范：有明确用途的调色板（3-4种主色调+中性色），色彩要承载含义（分类、流向、严重程度），通过CSS自定义属性定义。
流程表达：带SVG箭头的定向连接器、曲线路径、带标签的连线。架构图需要为带双向数据流的分层结构，而非扁平的节点关系图。
布局规则：使用CSS Grid显式定义
```
grid-template-columns
```
/
```
grid-template-rows
```
的比例分配，不要使用默认自动间距，所有外边距/内边距都需要有明确设计意图。

Quick Start

快速开始

Step 1: Initialize Project

步骤1：初始化项目

Run the initialization script to create a new static project:

bash

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

This creates a minimal scaffold with:

✅ Template HTML with CSS custom properties (theming)
✅ CSS Grid + Flexbox layout utilities (inline
```
<style>
```
)
✅ Print-ready viewport meta configuration
✅ No node_modules, no package.json, no build toolchain

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

bash

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

该命令会创建极简脚手架，包含：

✅ 带CSS自定义属性（主题）的HTML模板
✅ 内联
```
<style>
```
形式的CSS Grid + Flexbox布局工具类
✅ 适配打印的视口元配置
✅ 无node_modules、无package.json、无构建工具链

Step 2: Develop Your Artifact

步骤2：开发你的产物

Edit the generated

index.html

directly. Each HTML file = one page = one clear message.

Key patterns:

Use CSS Grid
```
grid-template-areas
```
for named region layouts
Use
```
fr
```
units for proportional spatial allocation
Embed SVG icons inline (not as external references)
Use CSS custom properties (
```
--color-primary
```
,
```
--color-accent
```
, etc.) for palette cohesion
Use
```
clip-path
```
,
```
border-radius
```
, gradients, and
```
box-shadow
```
for visual depth

直接编辑生成的

index.html

即可，每个HTML文件对应一个页面、一个明确的传递信息。

核心开发模式：

使用CSS Grid的
```
grid-template-areas
```
实现命名区域布局
使用
```
fr
```
单位实现空间的比例分配
直接内联嵌入SVG图标（不要作为外部资源引用）
使用CSS自定义属性（
```
--color-primary
```
、
```
--color-accent
```
等）保证调色板一致性
使用
```
clip-path
```
、
```
border-radius
```
、渐变和
```
box-shadow
```
实现视觉深度

Step 3: Validate and Finalize

步骤3：验证与最终打包

bash

bash scripts/bundle-artifact.sh

This validates the artifact is fully self-contained:

Checks for zero external resource references (no CDN links, no external stylesheets/scripts)
Verifies inline SVG presence
Reports file size
Copies validated output to
```
bundle.html
```

bash

bash scripts/bundle-artifact.sh

该命令会验证产物是完全自包含的：

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

Step 4: Share Artifact with User

步骤4：向用户分享产物

Share the validated HTML file in conversation with the user so they can view it as an artifact.

在对话中向用户分享验证后的HTML文件，方便他们查看该产物。

When to Use This Skill vs Other Visual Skills

本技能与其他可视化技能的适用场景对比

Task	Use This Skill	Use Instead
Rich infographic with multiple sections, high data density	Yes	—
Self-contained dashboard with interactive tabs or toggles	Yes	—
Architecture diagram with bidirectional flows and layered tiers	Yes	`architecture-diagram` for auto-generated from code
Simple concept illustration or icon-style image	No	`concept-to-image`
Slide deck or multi-page presentation	No	`html-presentation`
Architecture diagram generated from existing codebase	No	`architecture-diagram`
Single-page visual where CSS Grid layout control is critical	Yes	—
Artifact must be screenshot-ready via Playwright	Yes (with caveat — see Limitations)	—

任务	适用本技能	应使用其他技能
多区块、高数据密度的丰富信息图	是	—
带交互标签页或开关的自包含看板	是	—
带双向数据流和分层结构的架构图	是	从代码自动生成时用 `architecture-diagram`
简单概念插图或图标类图片	否	`concept-to-image`
幻灯片或多页演示文稿	否	`html-presentation`
从现有代码库生成的架构图	否	`architecture-diagram`
需要严格控制CSS Grid布局的单页可视化内容	是	—
需要支持通过Playwright生成截图的产物	是（有附加限制，见局限性说明）	—

Error Handling

错误处理

Error	Cause	Resolution
CDN link detected by `bundle-artifact.sh`	External stylesheet or script reference in HTML	Inline all CSS and JS — no external URLs allowed in output
Content overflow / clipping in browser	Viewport too small or fixed heights with overflow:hidden	Use `min-height` instead of `height` ; test at 1440px wide; use `overflow: auto` on scroll regions
Playwright screenshot cuts off content	Page height exceeds screenshot viewport	Set `page.setViewportSize` to match content dimensions; use `fullPage: true`
`bundle-artifact.sh` reports missing inline SVG	SVG loaded via `<img src>` or external ref	Replace with inline `<svg>` block directly in HTML
File size too large to share as artifact	Embedded base64 images or verbose SVG	Optimize SVG paths; avoid embedding raster images

错误	原因	解决方案
`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路径；避免嵌入光栅图片

Limitations

局限性

Browser required for screenshots: Rendering and Playwright-based screenshot capture require a browser runtime. The HTML file itself has no server-side dependency, but visual validation needs a browser.
No server-side rendering: Output is purely client-side. Dynamic data, API calls, or server-computed content are not supported.
No persistent state: The artifact has no backend. User interactions (form inputs, toggles) reset on page reload and cannot be saved.
File size guidance: Aim for under 500KB. Artifacts above 1MB may not render as inline conversation artifacts in some Claude interfaces.
Font availability: System fonts only (or inline base64-encoded web fonts). Do not reference Google Fonts or other external font CDNs.
Print fidelity: CSS print media queries are supported but browser print rendering varies. Test
```
@media print
```
explicitly if print output is a requirement.

截图需要浏览器环境：渲染和基于Playwright的截图捕获需要浏览器运行时。HTML文件本身没有服务端依赖，但视觉校验需要浏览器。
无服务端渲染：输出为纯客户端内容，不支持动态数据、API调用或服务端计算内容。
无持久化状态：产物没有后端，用户交互（表单输入、开关切换）会在页面重载时重置，无法保存。
文件大小建议：尽量控制在500KB以下，超过1MB的产物可能无法在部分Claude界面中作为对话内联产物渲染。
字体可用性：仅支持系统字体（或内联base64编码的Web字体），不要引用Google Fonts或其他外部字体CDN。
打印保真度：支持CSS打印媒体查询，但不同浏览器的打印渲染效果存在差异，如有打印需求请显式测试
```
@media print
```
规则。