HTML artifacts

HTML artifacts

save_plan, output_iframe, and slack_attach_html all publish a self-contained HTML artifact, and one contract covers all three.

Write the page content directly. When you omit <html>, <head>, and <body>, the tool wraps your content in that skeleton with a minimal CSS reset. Write a <title> yourself — a specific 2–4 word name for this page, not a summary or a category label. A Slack attachment is opened as a standalone file, so include the full skeleton there.

Design plan first

Sketch a compact plan before writing HTML, then follow it:

• Color: 4–6 named hex values grounded in the subject, including deliberately tinted neutrals. A pure mid-grey reads as unconsidered; a grey biased toward the accent reads as chosen.
• Type: at least a display and a body role, plus a utility/data face when useful. Google Fonts may be linked directly; every face needs a real fallback stack.
• Layout: the layout concept in one or two sentences. A plan or memo is polished and utilitarian — most pages need no oversized landing-page hero.

Derive every color and type decision in the page from that plan.

Runtime

Inline CSS and JavaScript, Canvas, WebGL, and inline SVG all run — prefer Canvas or WebGL over hand-authored SVG path data for generative graphics. Google Fonts stylesheets are the only permitted external resource; inline or data-URI every other asset.

Assume no network at runtime: no CDN scripts, fetch, or XHR. The viewer frames have an opaque origin, so localStorage, sessionStorage, and cookies throw on access — wrap any use in try/catch and render correctly with no stored value.

Theming

Default user-facing HTML to the viewer's system light/dark preference using prefers-color-scheme; provide both palettes unless the user explicitly requests a single theme. Honor an explicit viewer theme supplied by the dashboard over the system preference.

The dashboard stamps data-theme="light" or data-theme="dark" on <html>, so :root[data-theme="dark"] is the authoritative dark layer and must be complete on its own.

:root { /* the full light palette, as tokens */ }
@media (prefers-color-scheme: dark) {
  :root:not([data-theme="light"]) { /* redefine only the tokens */ }
}
:root[data-theme="dark"] { /* redefine them again — this layer wins */ }

Declare color-scheme in each layer too (light on :root, dark in both dark layers) so scrollbars, form controls, and UA defaults follow the artifact instead of staying light under a dark palette. The dashboard seeds it from the viewer's theme; your own declaration wins.

The media-query layer covers surfaces that stamp nothing, such as a downloaded file or a Slack attachment. Paint body with an explicit token background and style components only through tokens: a color whose only definition sits inside a media or [data-theme] block is the classic unreadable-artifact bug. Give the second theme the same care as the first — don't naively invert; keep contrast legible and the accent working on both grounds. Only a user-requested single-theme artifact may omit both dark layers, and every background and foreground must still be explicit.