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 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. Each pairs a self-contained HTML template (with placeholder tokens and a sample dataset for standalone testing) with a deterministic renderer script that fills in live data.