/artifact

The artifact tool renders a self-contained HTML/Tailwind/SVG fragment inside a sandboxed tab themed with Metaphor's design tokens, and places a compact card in chat.

Before your first artifact call in a turn, load the matching module skill with use_skill alongside this core guide:

What the user is asking	Module skill to load	kind
"How does X work?" (physical, biological, protocol, algorithm, engine)	artifact-diagram (illustrative metaphor)	diagram
"Architecture / components / layers of X"	artifact-diagram (structural containment)	diagram
"Steps / pipeline / request trace / lifecycle"	artifact-diagram (flowchart / sequence)	diagram
"Database schema / tables / foreign keys"	artifact-diagram (lib:mermaid erDiagram)	diagram
"What happens when I vary X? / Tradeoff calculator / Simulation"	artifact-interactive (+ artifact-chart if plotted)	interactive
"Compare A vs B vs C / Form / UI mockup / Data record"	artifact-mockup	mockup
"Plot / benchmark / distribution / time series"	artifact-chart	chart
"Digest / structured reference / learnings report"	(this core skill)	doc

---

Core philosophy

1. Seamless with the host. Artifacts live inside Metaphor's monochrome + single-accent workbench. Never hardcode light/dark backgrounds or hex text colors in HTML or SVG. Always use the host CSS variables, Tailwind token classes (bg-surface2, text-neutral6, border-border1), or c-* color ramp classes so light and dark themes work automatically.
2. Quiet chrome, expressive content. The frame stays flat: 0.5px borders, subtle surface elevation (bg-surface2), zero box-shadows, zero decorative gradients (a single 2-stop SVG <linearGradient> is fine when it encodes a continuous quantity like heat or pressure), zero emoji. The content is where you spend creativity — see "Make it memorable" below.
3. Explainers are self-contained lessons. For teaching, the artifact holds the narrative and the visuals together: a hook line at the top, then each beat as a short section (<h3> + 1–3 sentences, max ~60 words) with its diagram or control directly underneath, then a one-line takeaway. No essays — the visuals carry the idea and the text names what to look at. Captions and readouts update live when a control changes. Write maths as plain text or HTML, never LaTeX.
4. One subject per artifact. Keep one topic in one artifact; only split when there are genuinely two subjects (for example the system overview and a separate deep-dive).
5. Update in place by reusing title. Calling artifact again with the same title publishes a new revision (v2, v3) in the same tab.

---

Make it memorable (do this every time)

A grid of labelled boxes is the floor, not the goal. Before writing markup, decide in one sentence what the reader should see happen, then pick at least two of these:

1. A physical metaphor. Draw the mechanism as something with a shape: a queue is a conveyor with parcels on it, a cache is a shelf in front of a warehouse, backpressure is a pipe narrowing, a lock is a turnstile, a retry is a loop that comes back around. Real names go on the parts; the metaphor carries the intuition.
2. Motion that means something. Show data moving, not just existing. The host ships these classes:
   • class="arr flow" on a <line>/<path> makes dashes stream along it (data in transit).
   • <circle r="5" class="token"><animateMotion dur="2.4s" repeatCount="indefinite" path="M60 80 H320 V160"/></circle> sends a request dot along a route. Use one token per concurrent thing, staggered with begin="0.8s".
   • class="arr draw" style="--mx-len: 420" draws a path in once (set --mx-len to roughly the path length).
   • class="pulse" on the one element that is waiting, hot, or failing.
   • class="reveal" on sibling cards or <g> groups makes them rise in, one after another. Motion is automatically disabled for users who prefer reduced motion. Animate at most 2–3 things at once; the eye must know where to look.
3. Direct manipulation. If the real system has a knob (rate, size, timeout, count), give the reader that knob: a slider or toggle that changes the picture live (queue fills up, bar turns red, path reroutes). Pair it with a one-line readout of the consequence ("p99 ≈ 340 ms — the queue never drains").
4. A stepper through state. For a lifecycle or trace, draw the whole system once and let Prev / Next buttons light up one stage at a time while a caption explains why that step exists. Keep untouched parts visible but dimmed (opacity: 0.35).
5. One focal point and an annotation. Exactly one element uses a strong c-* ramp or .token accent; everything else stays c-gray or .box. Point at the surprising part with a .leader line and a short .ts note ("this is where the 30 s goes").
6. Before / after. Show the naive design and the fixed design side by side, or let a toggle flip between them, with the broken spot marked in c-red.

Quick check before calling artifact: if you replaced every label with "Box", would the picture still say something? If not, the shape is not doing any work yet.

---

Complexity budget (hard limits)

• Typography: 2 font weights only (400 regular, 500 medium — never 600/700). Sentence case everywhere (never ALL CAPS labels or text-transform: uppercase).
• Grid density: At most 4 cards or nodes per row. Minimum 12px (gap-3) between cards; 60px between diagram boxes.
• Color budget: At most 2 categorical c-* ramps per artifact unless encoding semantic status (green/amber/red). Include a 1-line legend whenever color encodes meaning.
• Fragment rules: Pass only the inner markup in html — never <!DOCTYPE>, <html>, <head>, or <body>. Never use position: fixed or fixed (the iframe auto-sizes to its content). No external http(s): scripts, stylesheets, fonts, or images.

---

What the host injects for you (artifact-host.css + Tailwind v4)

You do not need to write boilerplate CSS for controls, cards, or SVG nodes. The host automatically provides:

1. CSS variables & Tailwind token classes

• Surfaces: var(--color-bg-primary) (bg-surface1), var(--color-bg-secondary) (bg-surface2), var(--color-bg-tertiary) (bg-surface3), var(--color-bg-info|success|warning|danger)
• Text: var(--color-text-primary) (text-neutral6 / text-fg), var(--color-text-secondary) (text-neutral4 / text-fg-subtle), var(--color-text-tertiary) (text-neutral3 / text-fg-subtlest), var(--color-text-info|success|warning|danger)
• Borders & Radii: var(--color-border-tertiary) (border-border1), var(--color-border-secondary) (border-border2), var(--border-radius-md) (rounded-md, 6px), var(--border-radius-lg) (rounded-lg, 8px), var(--border-radius-xl) (rounded-xl, 12px)
• Short aliases for inline styles: var(--p) (primary text), var(--s) (secondary text), var(--t) (tertiary text), var(--bg2) (secondary surface), var(--b) (subtle border)

2. Pre-styled bare HTML elements & card classes

• Bare <button>, <select>, <input type="text|number">, <input type="range">, <table>, <code>, <pre> are pre-styled to match Metaphor.
• .metric-card — flat bg-surface2 card (padding: 1rem; border-radius: 6px; border: none).
• .raised-card — bordered bg-surface1 card (border: 0.5px solid var(--color-border-tertiary); border-radius: 8px; padding: 1rem 1.25rem).

3. SVG diagram classes & shared arrow marker

• Every <svg> automatically receives <defs><marker id="arrow" ... context-stroke .../></defs> — just use marker-end="url(#arrow)" on <line> or <path>.
• .t (14px primary text), .ts (12px secondary subtitle), .th (14px medium 500 title).
• .box (neutral node fill + 0.5px border), .node (clickable pointer + hover opacity), .arr (1.5px connector line, fill: none), .leader (0.5px dashed leader line).
• 9 color ramps: .c-purple, .c-teal, .c-coral, .c-pink, .c-gray, .c-blue, .c-green, .c-amber, .c-red. Apply class="node c-teal" on <g> and its child <rect>, .th/.t, and .ts automatically get matching light/dark fill, stroke, and text contrast!

4. Bundled offline scripts & host bridge

• <script src="lib:chart"></script> — inlines offline Chart.js (window.Chart).
• <script src="lib:mermaid"></script> — inlines offline Mermaid (window.mermaid, for erDiagram only).
• sendPrompt("...") — sends a follow-up prompt to the chat when clicked (buttons calling sendPrompt automatically get a trailing ↗).
• openFile("packages/harness/src/session/runner.ts", 42) or <a href="packages/harness/src/session/runner.ts:42"> — opens the file at that line in Metaphor's editor! Always wire real code nodes and file references to openFile(path, line) when explaining repository code.

---

Anti-bloat "tells" to avoid (frontend-design rules)

Never emit any of these AI-generated page tells:

• Purple-to-blue gradients, neon glow shadows, or glassmorphism blur cards.
• All-caps tracking headers (OVERVIEW, KEY METRICS) or numbered 01 / 02 / 03 badges on non-sequential items.
• Centered hero banners with marketing taglines inside an engineering explainer.
• Emoji prefixes on headings or card titles (🚀 Performance, 🔒 Security).
• Wrapping a single SVG or chart inside a redundant outer bordered card with a duplicate title (the Artifact tab toolbar already renders the title and kind badge).
• Invented benchmark numbers or fabricated metrics — every plotted number must come from code, a command output, a formula, or a cited source.