html-artifact

/html - Self-Contained HTML Artifacts

Generate single self-contained .html files that replace markdown when the output needs color, interactivity, layout, or visualization. Auto-detect artifact shape from the request, load shape-specific patterns, generate, validate, deliver.

Core constraint: Every artifact is ONE .html file. All CSS in <style>, all JS in <script>. No CDN links, no frameworks, no build steps, no external dependencies. Works offline, opens in any browser.

Instructions

Overview

5-phase pipeline: DETECT SHAPE, LOAD CONTEXT, GENERATE, VALIDATE, DELIVER. Phase 1 classifies the request into one of 8 shapes via deterministic script. Phase 2 loads the Birchline design system plus shape-specific reference. Phase 3 dispatches a subagent to generate the HTML. Phase 4 validates structure. Phase 5 delivers the file path and offers browser preview. Phase 6 EXPORT (optional) renders to PDF when the user asks for one.

Phase 0: CHECK SAVED TEMPLATE (clone-first)

Before detecting a shape, check whether the request names or matches a saved template. A saved template is a frozen, human-authored layout; cloning it beats regenerating structure because the layout cannot drift.

Run: python3 skills/meta/html-artifact/scripts/fill-template.py --list

If the request names a listed template (e.g. "project kickoff", "business review", "system design") or clearly matches one:

1. Read templates/saved/<name>.slots.json to learn the slots.
2. Generate ONLY the slot content — never the layout, CSS, or chrome.
3. Write the slot values to a JSON file and run fill-template.py --template <name> --slots <file> --out <artifact>.
4. Skip Phases 1–3 (shape detection, assembly, generation). Go to Phase 4 VALIDATE.

The fill script fails loud on a missing required slot, an undeclared slot name, or a leftover marker. Fix the slot JSON; do not edit the template.

If no saved template matches, continue to Phase 1.

See "Fidelity & Authority" below for the content-vs-layout rule that governs clone mode.

Phase 1: DETECT SHAPE

Classify the user's request into one of 8 artifact shapes.

Run: python3 skills/meta/html-artifact/scripts/detect-shape.py --request "{user_request}"

The script outputs a shape name and confidence score.

Gate: Shape detected with medium+ confidence. -- because low-confidence classification produces artifacts that mix concerns and satisfy no shape well. Fallback to "report" (safest general-purpose shape) if confidence is low or ambiguous.

Hybrid Shapes

Real content often combines two shapes — a report with embedded diagrams, a spec with data-viz charts. When detect-shape.py returns a primary shape with medium/high confidence but the request also contains signals for a secondary shape, use the hybrid pattern:

Detection: After running detect-shape.py, check if the secondary_shape field is non-null. If so, load BOTH shape references in Phase 2.

Generation rule: Primary shape controls page layout (outer structure). Secondary shape provides embedded components (inner elements). The html-builder agent receives both shape patterns and uses primary for structure, secondary for visual elements within sections.

Example: "create a visual companion for my pipelines article with diagrams and explanations" → primary: report (explain, article), secondary: diagram (visual, diagrams). Load shape-report-research.md AND shape-diagram-illustration.md.

Phase 2: ASSEMBLE TEMPLATE + LOAD CONTEXT

Two parallel steps: (A) run the template assembler to produce a pre-filled HTML skeleton, and (B) load principle-focused reference files for the builder agent.

Step A -- Assemble template (deterministic):

Run: python3 skills/meta/html-artifact/scripts/assemble-template.py --shape {shape} --title "{title}" --components {components}

The script reads CSS/JS from templates/ and injects:

1. CSS reset (templates/base-reset.css)
2. Full theme tokens (templates/themes/{theme}.css)
3. Shape-specific layout CSS (templates/shapes/{shape}.css)
4. Component CSS + JS (templates/components/{name}.{css,js})

The assembler also emits a self-describing stamp as the FIRST CSS comment, so a later run can re-audit the build statelessly (recover shape/theme from output):

/* vexjoy-artifact: shape=<shape> theme=<name> contrast=<pass|fail|n/a> */

shape and theme come from this build's decisions. contrast=n/a at assembly time because the assembler runs no WCAG check; the stamp is a claim, not proof — Phase 4's slop scan verifies the rendered CSS independently rather than trusting it.

Select components based on shape needs:

Step B -- Load reference files (principles + guidance):

Always load:

1. references/design-system.md -- Theme selection, token architecture, accessibility checklist, SVG conventions, common mistakes
2. references/interaction-patterns.md -- Component descriptions, when-to-use guidance, accessibility rules, composition guide

Load per detected shape:

Gate: Template assembled + required references loaded. -- because the template provides deterministic CSS/JS injection, and references provide the judgment guidance the builder needs.

Phase 3: GENERATE

Dispatch the html-builder subagent with the pre-assembled template.

1. Read agents/html-builder.md for the subagent prompt
2. Dispatch with: pre-assembled template (from Step A), design system principles, interaction pattern guidance, shape-specific reference, user request
3. Agent fills in the content structure using CSS classes already defined in the template
4. Agent writes a single .html file to the project directory (or /tmp/html-artifacts/ if no project context)

Self-contained file constraints (inline here because they govern generation):

Constraint: No framework boilerplate. -- because React/Vue/Svelte require build steps and external imports that violate the single-file self-contained requirement. Vanilla JS handles all 8 shapes adequately.

Constraint: Generate HTML directly, never generate markdown then convert. -- because markdown-to-HTML conversion loses the shape-specific layout, interactivity, and visual structure that justifies using HTML in the first place.

Gate: .html file exists on disk. -- because Phase 4 validation reads the file; a missing file means generation failed silently.

Phase 4: VALIDATE

Run deterministic validation on the generated file.

Run: python3 skills/meta/html-artifact/scripts/validate-artifact.py {html_file_path}

The script checks:

The slop scan (vendored css_slop_rules.py) flags 7 rendered-CSS patterns — transition-all, universal-hover-scale, gradient-text-headline, focus-ring-fade, emoji-feature-icon, two-line-cta, contrast-canary. It is shape-agnostic (checks CSS/markup, not page structure), so it applies to all 8 shapes including hero-less ones. Findings surface as warnings and do not fail the build yet; promote a rule to error in css_slop_rules.py to make it blocking.

Gate: All validation checks pass. -- because an HTML file with external dependencies fails offline, missing meta tags render inconsistently across browsers, and missing structure breaks accessibility.

If validation fails: Read the specific failures from script output, fix the identified issues in the HTML file, re-run validation. Maximum 3 fix attempts before showing the user the remaining issues and asking for guidance.

Phase 5: DELIVER

1. Print the absolute file path
2. Print a 1-line summary of what was generated (shape + key features)
3. Ask user: "Open in browser?"
4. If yes: run open {file} (macOS) or xdg-open {file} (Linux)

Constraint: Detect headless/SSH environments before offering browser open. -- because xdg-open fails without a display server, producing confusing errors. Check $DISPLAY on Linux or $SSH_TTY presence. If headless, print path only and skip the open offer.

Phase 6: EXPORT (optional)

Render the generated HTML to PDF. Opt-in only — HTML stays the default deliverable.

Fires when the user message contains any of: "PDF", "export PDF", "make a PDF", "as PDF", "send as PDF", "save as PDF", "PDF version", "PDF export". Without one of those signals, this phase stays dormant.

Runs:

python3 skills/meta/html-artifact/scripts/to-pdf.py \
    --input <generated.html> \
    --output <generated.pdf> \
    --json

The script auto-detects shape from <body data-shape="..."> (the assembler adds it in Phase 2). Page size, orientation, and margins come from a per-shape map: deck renders 13.333in × 7.5in landscape with no margin; spec, code-review, prototype, data-viz, and diagram render Letter landscape; report and editor render Letter portrait. Falls back to Letter portrait when shape is unknown.

Delivers both file paths to the user. The JSON output reports {"output", "page_count", "shape", "bytes"} — page_count reflects slide count for decks, 0 otherwise.

If Playwright is unavailable, exit code 2 surfaces install instructions: pip install -e ".[pdf]" && playwright install chromium. Pass that hint along to the user instead of failing silently.

See references/pdf-export.md for the full page-size table, troubleshooting (font fallback, image timing, install failures), and per-shape print stylesheet inventory.

Phase 7: EXPORT-PPTX (optional)

Render the generated HTML deck to an editable Microsoft PowerPoint .pptx. Opt-in only — HTML stays the default deliverable. Mirrors Phase 6 EXPORT-PDF in shape: signal-triggered, deterministic, runs after the HTML is built.

Fires when the user message contains any of: "pptx", ".pptx", "powerpoint", "editable deck", "editable", "as pptx", "export pptx", "hand-off", "corporate template". Without one of those signals, this phase stays dormant.

Only valid when the detected shape is deck. Other shapes (report, spec, diagram, etc.) cannot be exported to PPTX — fall back to Phase 6 PDF if the user asks.

Runs:

python3 skills/meta/html-artifact/scripts/pptx-bridge/run-unified.py \
    --input <generated.html> \
    --format pptx \
    --out <generated.pptx> \
    --no-render

The bridge re-authors slides natively via python-pptx because no general HTML→PPTX converter preserves CSS-rich layout. Output is 13.333 × 7.5 in (16:9), dark navy theme, Aptos body / Cascadia Code mono. Each <section class="slide"> becomes one editable slide; up to 12 layout types (title, content, metric_grid, layer_rows, pipeline, code_block, compare_table_2col/3col, outcome_grid, split_narrow, closing) map 1:1 to native python-pptx builders.

--out accepts either a .pptx file path (single-file mode) or a directory (writes the .pptx plus slides.json, report.md, optional render/ siblings). --no-render skips the optional LibreOffice QA step; required on hosts without soffice.

If python-pptx is unavailable, exit code 1 surfaces install instructions: pip install python-pptx. Pass that hint along to the user instead of failing silently.

See references/pptx-export.md for the full layout table, THEME dict, CLI reference, validation criteria, and failure modes.

Error Handling

Preferred Patterns

Pattern 1: CDN and Framework Imports

What it looks like: <link href="https://cdn.jsdelivr.net/..."> or <script src="https://unpkg.com/react@18/..."> in the generated HTML.

Why wrong: Breaks the self-contained contract. File fails offline, introduces version drift, adds weight the user didn't ask for.

Do instead: Inline all CSS in <style>. Write vanilla JS in <script>. The Birchline design system in references/design-system.md provides the full token set.

Pattern 2: Markdown-to-HTML Conversion

What it looks like: Generating a markdown document first, then running it through a converter or wrapping it in <pre> tags.

Why wrong: Loses shape-specific layout, interactivity, SVG diagrams, and responsive grid structures. Produces "markdown in a browser" instead of a native HTML artifact.

Do instead: Generate HTML directly using shape-specific patterns from references. The HTML structure IS the output format, not a rendering layer on top of text.

Pattern 3: Monolithic Unstructured HTML

What it looks like: One giant <div> with inline styles on every element, no semantic structure, no comments.

Why wrong: Unreadable source, hard to debug, impossible for the user to modify. Accessibility tools cannot navigate it.

Do instead: Use semantic HTML (<header>, <main>, <section>, <footer>). Define CSS classes in <style>. Add section comments. Group related elements logically.

Pattern 4: Over-Engineering Simple Requests

What it looks like: Generating a full interactive dashboard when the user asked for a simple comparison table.

Why wrong: 2-4x generation time for features the user didn't request. Complexity without value.

Do instead: Match artifact complexity to request complexity. A comparison of 3 options needs a grid with cards, not a filterable dashboard with animations.

Anti-Rationalization

Reference Loading Table

Shared Patterns

This skill uses:

• Anti-Rationalization -- Prevents shortcut rationalizations
• Verification Checklist -- Pre-completion checks
• Gate Enforcement -- Phase transitions

Reference Files

• references/design-system.md: Theme selection, token architecture, accessibility checklist, SVG conventions, common mistakes
• references/interaction-patterns.md: Component descriptions, when-to-use guidance, accessibility rules, composition guide
• references/shape-spec-exploration.md: Spec shape -- layout, composition guide, common mistakes
• references/shape-code-review.md: Code review shape -- severity system, interaction patterns, section ordering
• references/shape-design-prototype.md: Prototype shape -- control types, export requirements, layout patterns
• references/shape-report-research.md: Report shape -- section ordering, TL;DR placement, metric patterns
• references/shape-custom-editor.md: Editor shape -- editor types, export bar rules, common mistakes
• references/shape-data-visualization.md: Data viz shape -- chart types, coordinate system, color scales
• references/shape-diagram-illustration.md: Diagram shape -- SVG construction rules, diagram types, interaction patterns
• references/shape-slide-deck.md: Deck shape -- slide types, navigation, print styles
• agents/html-builder.md: Subagent prompt for HTML generation
• references/scrollytelling-patterns.md: IntersectionObserver scroll animation patterns
• references/pdf-export.md: Phase 6 EXPORT — trigger conditions, page-size table, print stylesheet inventory, troubleshooting
• references/pptx-export.md: Phase 7 EXPORT-PPTX — trigger conditions, layout types, THEME dict, CLI reference, failure modes
• references/diagram-layering.md: SVG layer order, masking rect technique, dark design system constants, semantic color palette
• references/infographic-layouts.md: 21 layout types with structure and use guidance, 22 visual styles, content-type pairings
• scripts/detect-shape.py: Deterministic shape classification from user request
• scripts/assemble-template.py: Template assembly with theme, shape, and component CSS/JS injection
• scripts/validate-artifact.py: HTML structure, self-containment, and rendered-CSS slop validation
• scripts/css_slop_rules.py: vendored slop scanner (scan_css) — 7 rendered-CSS rules, dependency-free. Keep in sync with distinctive-frontend-design.
• scripts/to-pdf.py: Playwright-based PDF rendering with per-shape page sizing
• scripts/pptx-bridge/: HTML deck → editable PPTX (extract_slides.py, _pptx_engine.py, render_pptx.py, run-unified.py)
• templates/: CSS/JS template files organized by themes/, shapes/, components/, print/

Saved Templates

Pre-built, reusable artifact templates for recurring requests. Two renderer patterns:

• Specialized renderer — a script that fetches live data and fills a bespoke template (github-issues).
• Generic slot filler — scripts/fill-template.py clones any frozen template in templates/saved/ and substitutes caller-supplied slot values. One skill, many template files: add a layout, not a skill.

See templates/saved/README.md to add a template.

Fidelity & Authority

Governs clone mode (Phase 0). Adapted from the OpenAI curated-template skills, which keep on-brand output by cloning a fixed reference instead of regenerating it.

Clone, don't regenerate. When a saved template applies, clone its layout unchanged and fill only the content slots. Do not rebuild the structure, restyle the CSS, or "improve" the chrome. Regeneration is where visual drift and AI slop enter; a frozen template removes that risk.

Content-vs-layout authority. One rule resolves every "should I restyle this?" question:

User instructions control requested content and explicit deviations. The retained template controls layout and formatting where the user has not requested a change.

So: change layout only when the user asks for a layout change. Otherwise the template wins. fill-template.py enforces this mechanically — it substitutes slot values and touches nothing else.

Fail loud, don't degrade. If a required slot has no content, stop and get the content — do not silently ship a half-filled template. The fill script exits non-zero on a missing required slot, an undeclared slot, or a leftover marker.