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 is a real web page. HTML renders inside a frame from a path on octo's own address, so everything a normal web page can do works: localStorage persists (the page's keys are kept apart from octo's own and from other pages'), <a download> saves a file, requestFullscreen() and pointer lock work, WebGL and Web Audio work, and fetch can reach public APIs. Do not write code that calls octo's own 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'), fetch('./data.json'), fonts, audio, video and other .html pages in the same directory (or a subdirectory) are served with the page. Never start such a path with /: the page lives under a path prefix, and an absolute path lands outside it. 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 resources load from anywhere — which is why to be sparing. Pin exact versions; if the user is in mainland China, prefer a mirror reachable there (cdn.bootcdn.net, cdn.staticfile.net, registry.npmmirror.com). 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, and a saved Light App has to keep working for years.
• 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.
• The theme arrives on the URL — read it. octo loads the page with ?theme=dark or ?theme=light: the palette the user picked in the Web UI, which is not necessarily the OS's. Nothing applies it for you, so a page that only watches prefers-color-scheme follows the OS and becomes the one dark rectangle on a light screen the moment the two disagree. Apply it at startup and key the palette off data-theme, keeping the media query as the fallback for a page opened bare in a browser tab: