artifact-design

Page contract — read before your first publish

These are the Artifact tool's own rules for the file you publish; the design guidance below builds on them.

Format: Always author the page as .html. Publish a .md file only when a loaded skill explicitly instructs it. When the user shares a markdown document or asks to turn one into an artifact, author an HTML page based on its content — preserve its substance, and design the page as you would any other artifact rather than transcribing the markdown one-to-one.

Skeleton: The file is wrapped in a <!doctype html>…<head>…</head><body> skeleton at publish time, so write the page content directly — no <!DOCTYPE>, <html>, <head>, or <body> tags of your own. Its head carries only a charset and viewport meta (with viewport-fit=cover) plus a small reset — light color-scheme, :root padded top and bottom by the phone's safe-area insets, zero body margin with a 14px system font, img{max-width:100%}, and [hidden]{display:none!important} (toggle visibility with el.hidden, not style.display) — so put your own <title> and <style> at the top of the file. Keep the :root padding. Put <meta name="claude:viewport-fit-sides" content="cover"> at the top of the file beside your <title>: it promises that the side gutter uses the two max() paddings given under Responsive, so the tag goes in only together with both paddings, never alone. An edit of an older page that has neither leaves both out, unless the ask redoes the page's layout. With it the page also runs under a system bar at the phone's side, where backgrounds reach that edge while the gutter keeps text and controls clear. Anything fixed to a screen edge stays at 0 and adds that edge's env(safe-area-inset-*, 0px) to its own padding (one that spans the width takes the side gutter too), a floating or absolutely placed control adds the nearby edges' insets to its offsets, and a sticky page header uses top: env(safe-area-inset-top, 0px), not 0, with the band above it painted by a fixed body::before (content: ""; position: fixed; inset: 0 0 auto; height: env(safe-area-inset-top, 0px); z-index: 10) in its background, or in the page's where it starts lower.

Title: Put a <title> at the top of the HTML; only the first 8KB of the file is scanned for it. It is the artifact's name in the browser tab and the gallery, so write a name, not a summary: a short noun phrase, typically two to four words, specific enough to pick this page out among many, the way an app or a document is named. When the user already has a specific name for the thing, use that name for the title rather than coining a new one. Never use a generic category label alone, and never append an explainer after a dash or colon. If you shorten a title that pairs the name with a generic word, keep the name, not the generic word. A multi-word title that already reads as one specific name is finished; do not shorten it further. The explanation goes in the one-sentence description parameter, which becomes the gallery card's subtitle. The title parameter fills in only when an HTML file has no <title> tag (Markdown pages keep their filename). Keep the title stable across redeploys.

External resources — CDN allowlist (CSP-enforced): external scripts load ONLY from https://cdnjs.cloudflare.com (preferred), https://cdn.jsdelivr.net/npm/, https://unpkg.com, https://cdn.tailwindcss.com (Tailwind's play-CDN script) and https://code.jquery.com; external stylesheets ONLY from https://fonts.googleapis.com, with the font files they pull from https://fonts.gstatic.com (give every face a real fallback stack). Everything else is blocked, with no visible error: every other host (esm.sh included) and, even on those CDNs, anything but a script — stylesheets, images, media, fetch/XHR/WebSocket, a library's runtime fetches. So inline all other CSS and JS and embed assets as data: URIs. How to load a library: <script src="https://cdnjs.cloudflare.com/ajax/libs/<lib>/<exact version>/<file>"> — pick the UMD build, which defines a global (e.g. react/18.3.1/umd/react.production.min.js, then react-dom) — placed BEFORE any inline <script> that uses it. Pin every library URL to an exact version ([email protected] on jsDelivr or unpkg, react/18.3.1/… on cdnjs, cdn.tailwindcss.com/3.4.17), never a bare name, a range or a tag (react, react@18, @latest). Choose a version at least two weeks old. Any version you knew before this conversation is old enough; if you look versions up, skip any published in the last two weeks. The viewer's sandbox also blocks any download the page starts itself — <a download> links (data:/blob: hrefs included) and script-driven saves are inert for viewers — so never offer a file through a plain link. Links to other websites (https://…) open in a new tab, but email, phone and app links (mailto:, tel:, sms:, other custom schemes) are unreliable inside an artifact: for many viewers (for example anyone outside the user's organization, or anyone viewing through a public link) following one, by link or by script, often does not work, and the page cannot tell whether it did. So show the address or number itself as selectable text (a copy button helps), treat such a link as a convenience that may do nothing, and never tell the viewer a message was sent or a call placed because the viewer tapped one. Artifacts render mermaid diagrams natively — markdown via ```mermaid fences, HTML via <pre class="mermaid"> blocks — no library needed, don't load one. The viewer never shows alert(), confirm() or prompt() dialogs — confirm() returns false and prompt() returns null immediately — so build any confirmation step into the page itself.