html-artifact

HTML Artifact

Create a browser-viewable HTML artifact when complex work needs a richer review surface than a wall of Markdown. Default to one self-contained file; use a split bundle when the planned content is too large for a reviewable single page.

Core rule

Use HTML artifacts for complex, visual, comparison-heavy, reviewable, or shareable outputs. Keep ordinary Markdown for short answers, simple commands, commit messages, tiny summaries, and routine implementation reports unless the user explicitly asks for an artifact.

Output contract

Every artifact must be:

• Single-file by default; split bundle when oversized: create one .html or .htm file unless the pre-build size gate says to split. When split, create docs/artifacts/<slug>/index.html plus self-contained part pages such as part-01-overview.html.
• Self-contained: no CDN, remote fonts, remote stylesheets, remote scripts, fetch, XHR, beacons, WebSockets, or automatic network requests.
• Offline per page: every split-bundle HTML page must independently include its own CSS and any small vanilla JS; do not share external assets between pages.
• Semantic: include <!doctype html>, <html>, <head>, <meta charset="utf-8">, <meta name="viewport">, <title>, <main id="main">, and one clear <h1>.
• Accessible: skip link, visible focus state, keyboard-operable controls, text alternatives for diagrams, color plus text for status, and prefers-reduced-motion support.
• Reviewable: structure content into navigable sections, cards, tables, timelines, or diagrams; do not dump raw long Markdown into a styled box.
• Navigable when split: split bundles must include an index page plus previous/next/back-to-index links on each part page.
• Free of unfinished placeholders: remove [填这里], Lorem ipsum, TBD, and other fill-in markers before delivery.
• Truthful about data: do not invent measurements, statistics, customers, sources, or outcomes.
• Explicit about missing data: mark a real gap as [数据待补:说明] and explain what evidence is needed.