static-web-artifacts-builder

Static Web Artifacts Builder

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

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

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

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.

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.

Quick Start

Step 1: Initialize Project

Run the initialization script to create a new static project:

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

Step 2: Develop Your Artifact

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

Step 3: Validate and Finalize

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

Step 4: Share Artifact with User

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

---

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	—
Static architecture/topology diagram, editable afterward in Figma/Illustrator	No	architecture-diagram — produces real vector SVG, not this skill's interactive HTML
Simple concept illustration or icon-style image	No	concept-to-image
Slide deck or multi-page presentation	No	html-presentation
Single-page visual where CSS Grid layout control is critical	Yes	—
Artifact must be screenshot-ready via Playwright	Yes (with caveat — see Limitations)	—

---

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

---

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.