Crafting HTML Artifacts

HTML is the right medium for share-once expository content. It carries information density that markdown cannot match (tables with design, SVG diagrams, color-coded annotations, syntax-highlighted code blocks, expandable sections, mobile-responsive layout), it shares as a link without rendering tools, and it supports two-way interaction (sliders, copy-as-prompt buttons, drag-and-drop editors). Markdown's editability advantage does not apply to artifacts the reader does not edit.

This skill differs from frontend-design. frontend-design builds UI and components, where the artifact is part of a product. This skill produces single-file expository HTML documents, where the artifact is a communication.

When NOT to use this skill

• Specs: use workbench:writing-spec.
• Plans: use workbench:writing-plans.
• Brainstorm summaries: use workbench:brainstorming.
• Debug reports: use workbench:systematic-debugging.
• Research reports: use research:research.
• Multi-slide presentations with a deck-stage engine and presenter mode: use workbench:crafting-presentations. The references/09-slide-deck.html template here is the quick single-file fallback for one-off decks.
• UI or component code: use frontend-design.

Five categories of HTML artifacts

references/index.html is the upstream's gallery index page, kept as the 21st file for reference; it is not assigned to a category.

Universal patterns

• Single-file HTML5; no external dependencies.
• Inline <style> block; no separate CSS files or CDN imports.
• Mobile-responsive viewport meta tag; layout works at narrow widths.
• Semantic HTML (<section>, <article>, <nav>, <aside>, <figure>).
• Inline <svg> for diagrams.
• For two-way interaction, include copy-link or copy-as-prompt buttons.
• No U+2014 or U+2013 codepoints in body copy. HTML entity forms (—, —, –, –) are permitted.
• Realistic placeholder content; do not leave Lorem ipsum or empty sections.

How to use the references

Read one reference file matching the artifact type before generating. Do not load all 21 references; each is self-contained and roughly 10 to 25 KB. The category map above is the index. The host agent reads references/<file>.html on demand, not proactively.

Output Format

Applying a design system

Before emitting HTML, check for an active design system and inline its overrides into the artifact's <style> block:

1. Resolve the design-system name: per-prompt override (e.g., "render with the brand-2026 design system"), then .workbench/config.md ## Design system Name:, then no override.
2. Locate the directory: .workbench/design-systems/<name>/ (project scope), then ~/.claude/workbench/design-systems/<name>/ (user scope). If a name resolves but no directory is found at either scope, report the missing path to the user and emit with template defaults; do not fabricate a substitute.
3. Inline colors.css (and typography.css if present) after the template's own :root declarations, so the design system's values win the cascade.
4. For any referenced component, paste components/<n>.html markup and scoped style into the artifact body.
5. For any referenced image, base64-encode (base64 -w 0 <file>) and inline as data:image/<type>;base64,<payload>. SVG is text and can be inlined directly. Use relative paths only when the artifact and the design system co-exist in the same git tree and the artifact will not travel.

crafting-html references vary in their CSS variable surface; inspect the chosen reference template's :root to know which design-system variables apply.

To create or edit a design system, see workbench:crafting-design-systems.