artifact-design

Artifact design

An artifact is any .html/.htm/.md/.markdown/.png/.jpg/.jpeg/.gif/.svg/.webp file the agent produces. Writing one through write_file/edit_file surfaces it automatically in the web UI's Artifacts panel; a file built some other way (a script, a build step, a download) needs one show_artifact call with its absolute path. This skill is about what to put inside the HTML — read it before writing the first line.

If the page contains any chart, graph, plot, heatmap, sparkline, or stat tile, read references/charts.md before writing the chart — chart-type selection, the color system (with a validated default palette in references/palette.md), legend/axis/tooltip conventions, and chart legibility at the panel's docked width.

How the panel actually works — design within these constraints

• The page runs on its own origin — a real one, not the app's. HTML renders from http://<token>.artifacts.localhost:<port>/ inside a frame, so everything a normal web page can do locally works: localStorage and IndexedDB persist, <a download> saves a file, requestFullscreen() and pointer lock work, WebGL and Web Audio work. Its network is fenced by a Content-Security-Policy: the page may load from and talk to its own origin and the allowlisted CDN hosts below, and nothing else — no fetch to other APIs, no images or media from other hosts, no reaching octo's /api. Data the page needs must be in the page or in a file beside it; do not write code that calls external services or octo's API from inside the page.
• Files beside the page load by relative path. <script src="./app.js">, <link href="./style.css">, <img src="./chart.png">, loader.load('./model.glb'), fonts, audio and video in the same directory (or a subdirectory) are served with the page. Only page-asset types are: images, .css/.js/.mjs/.json/.wasm/.csv/.txt/.xml, .glb/ .gltf/.bin/.obj/.mtl/.hdr, .woff/.woff2/.ttf/.otf, .mp3/.wav/.ogg/.mp4/.webm. A second .html is not — one entry page per artifact. A single file is still the simplest artifact; split into sibling files when the page has a real script or a binary asset (a model, a font, a recording) that would be absurd to inline.
• External references are allowlist-gated, and the allowlist is enforced. A <script src=…> / <link rel="stylesheet" href=…> pointing at another host may only use these CDN hosts; anything else is stripped before rendering, under a banner saying how many were removed: cdnjs.cloudflare.com, cdn.jsdelivr.net, unpkg.com, fonts.googleapis.com, fonts.gstatic.com, and the mainland-China mirrors cdn.bootcdn.net, cdn.staticfile.org, cdn.staticfile.net, registry.npmmirror.com. Pin exact versions; if the user is in mainland China, prefer the CN mirrors. Reach for a CDN only when the page needs a real library (React, ECharts, Chart.js, three.js, …) — a page that depends on one shows nothing when that host is unreachable. Relative references are not external and are never stripped.
• The default viewport is narrow. The panel is a 420px-wide docked sidebar by default; the user can maximize it to min(900px, 75vw), but don't design for that as the common case. Build the layout to read cleanly at ~380–420px first, then let it use extra space gracefully above that — not the other way around. This is the opposite of most artifact platforms, where the canvas starts wide. Multi-column layouts, wide tables, and side-by-side diagram lanes need an explicit @media (max-width: 720px) (or tighter) fallback to a single column, or they'll clip or force horizontal scroll in the default view.
• Theme support is one-directional. Only @media (prefers-color-scheme: dark) is a live signal in octo today — the panel does not push its own light/dark toggle state into the iframe (unlike some other artifact hosts). Still write :root[data-theme="dark"] / :root[data-theme="light"] overrides alongside the media query — they're free, harmless if unused, and correct if that wiring ever lands — but don't rely on them being live; the media query is what actually renders today for most users.
• Update in place, not by versioning. Re-running write_file/edit_file against the same absolute path updates that same panel entry rather than creating a new one. If you're iterating on a diagram, keep writing the same file.
• No title/gallery metadata to set. The panel derives the display name from the file's basename and its type label from the extension — there is no favicon or description field to populate. A <title> tag is harmless but cosmetically inert here.
• Markdown gets code-block styling for free (the panel inlines a highlight.js theme for .md previews) — don't hand-roll code-fence CSS in a Markdown artifact; that's only a concern for HTML artifacts.