render-as-html · design system

Canonical reference for the render-as-html skill. Components, patterns, and the principles behind them. Copy patterns from here rather than re-deriving CSS — generated artifacts should feel like one system.

v2 · 2026-05-11 · informed by Thariq's "unreasonable effectiveness of HTML"

Philosophy

Apple-quality typography and color, Linear/Stripe density.

Page shapes

Different content wants different bones. Pick the shape FIRST from content signals, then design inside it.

The 8 information dimensions (Thariq)

HTML can express state, interaction, layout, and visual relationships inside the file itself. Aim for at least 4 of these dimensions; if you only used 1-2, redesign before saving.

The bar (read this every time)

Color tokens

All colors via CSS variables; both modes via prefers-color-scheme. Text-use colors meet WCAG AA on light backgrounds.

Typography

One display, one body, one mono. Display and body use the system font stack, so generated artifacts stay self-contained.

Static components

Read-only display primitives. None of these are clickable — for interactive editing use the controls in the next section.

Stat tiles

Status pills — display only, NEVER interactive

Callouts

Visual diff (old → new)

Dense table

Real controls for real actions

If the user is supposed to toggle, edit, pick, or trigger something, use a control that LOOKS like a control. Never invent gestures on decorative elements.

Search input

Filter chips — every filter needs a visible clear path

Native checkboxes — the editing affordance

Toggle buttons

Copy-as-prompt — the killer pattern

Thariq's two-way loop: tune values in the browser → click a button → paste-able prompt for Claude Code that applies the changes back to the HTML artifact. Try the live demo below.

// Read state from your controls, format as instruction
async function copyPrompt() {
  const h = +$('#hue').value, s = +$('#sat').value, l = +$('#lig').value;
  const prompt = `In ${ARTIFACT_PATH}, update --accent to hsl(${h} ${s}% ${l}%)`;
  $('#prompt-output').value = prompt;
  try {
    await navigator.clipboard.writeText(prompt);
  } catch {
    $('#prompt-output').focus();
    $('#prompt-output').select();
  }
}
$('#copy-btn').onclick = copyPrompt;

// The prompt MUST:
// - name the HTML artifact file (so Claude knows what to edit)
// - state deltas, not the full HTML
// - read naturally when pasted as a user message
// - remain selectable when clipboard access is blocked

Per-section copy — document-shape pattern

For document-shape artifacts, every h2 should have a quiet "copy section" button that lands the section's HTML on the clipboard for reuse or follow-up edits.

<section id="workstreams">
  <h2>Workstreams <button class="copy-section" data-section="workstreams">copy section</button></h2>
  ...
</section>
<textarea id="copy-fallback" hidden readonly></textarea>

$$('.copy-section').forEach(btn => btn.onclick = () => {
  const html = $('#' + btn.dataset.section).outerHTML;
  navigator.clipboard.writeText(html).catch(() => {
    $('#copy-fallback').hidden = false;
    $('#copy-fallback').value = html;
    $('#copy-fallback').focus();
    $('#copy-fallback').select();
  });
});

Charts & diagrams

All hand-written inline SVG. No chart libraries — they cost weight and produce generic-looking output.

Donut chart

<!-- r=15.9 → circumference ≈ 100, so stroke-dasharray uses percentages directly -->
<circle r="15.9" cx="21" cy="21" fill="transparent"
        stroke="var(--accent)" stroke-width="6"
        stroke-dasharray="20 80"   <!-- 20% slice -->
        stroke-dashoffset="-10"/> <!-- offset after previous slice -->

Topology / workflow pattern

Solid = wired/sync, dashed = wireless/async. Fill = category soft, border = category full. Make nodes clickable to cross-highlight rows in the data table.

Anti-patterns

• Narrow centered column on data. Studio Displays exist. Default wide; narrow only for prose.
• Styled prose. If flattening to static text loses nothing but the SVG, the artifact failed. ≥3 HTML-native features.
• Invented gestures on decorative elements. Don't put click handlers on pills, badges, stat tiles. They read as static info. If editing needed, add a real checkbox/button.
• Hidden keyboard modifiers (shift-click, alt-click) for primary actions. Undiscoverable. Use visible controls instead.
• Filter without a clear path. Every activate gesture must also deactivate, AND show an explicit "× clear" affordance while filtered.
• Generous whitespace as taste. Information density is a feature.
• Emoji explosion. 1-3 per doc, not 1 per heading.
• Tailwind utility soup. Hand-written CSS reads better, renders the same.
• "Key Insights" decoration. Avoid generic AI-report ornamentation unless it adds real structure.
• Drop shadows on everything. Reserve for floating elements (copy button, modals).
• Skipping the HTML-native check. Name 3 features that die outside HTML before saving. Can't? Redesign.

Using this file