static-html-artifacts

name	static-html-artifacts
description	Use when you need to explore design variations, preview content layouts, compare alternatives visually, or explain a concept through a rendered artifact rather than prose. Triggers include: "show me variations", "what would this look like", "generate options", "I don't know what I want but I'll know it when I see it", or any design/content decision where verbal description is insufficient.

Static HTML Artifacts

Overview

Generate a single self-contained HTML file as a disposable decision surface. The artifact is not the end product — it is a selection and judgment mechanism. Use it any time the right answer is easier to recognize visually than to specify in words.

Core principle: Extract → Generate Variants → Inspect → Choose → Reintegrate

When to Use

• Design exploration: you need to see options, not describe them
• Content preview: compare how copy, posts, or layouts actually render
• Concept explanation: make an idea tangible with diagrams and structure
• Alternative comparison: pick the best from N distinct options
• Any time you'd say "I'll know it when I see it"

Do NOT use when:

• You already know exactly what you want (just build it)
• The decision is purely logical/non-visual
• You need live data or real-time updates (use Layer 2 or 3 instead)

The Workflow

1. Identify a component, output, or concept that is hard to specify verbally
2. Ask Claude Code to isolate it into a single HTML artifact
3. Generate multiple distinct variations (N = 5–20 depending on breadth)
4. Open in browser — inspect visually
5. Choose the winner (or note what to combine)
6. Instruct Claude to merge the chosen variant back into the main application

Prompt Templates

Design Variations

For the [component name, e.g. "Retrieval Settings card"], can you give me [N] 
variations in a single HTML file, one after another, each fairly distinct. 
Follow the same [light/dark] theme. Show each variation clearly labeled.

Ray's exact approach from the video:

"hey, so for the Retrieval Settings card, can you give me like 10 variations on an HTML file, one after another, each one should be fairly distinct and follow the same light theme."

iOS / Mobile Settings Screen

I'm designing [app name]'s settings screen. Generate 10 distinct variations of 
the settings UI in a single HTML file. Each variation should be clearly 
separated and labeled. Simulate an iOS/Android look and feel with a 
[light/dark] theme.

Content Preview (e.g. LinkedIn Post)

Take the following LinkedIn post draft and render it as a realistic HTML 
preview of how it would appear on LinkedIn (desktop view). Include the 
profile avatar placeholder, name, headline, and post body with formatting.

[paste post content here]

Interactive Concept Explainer (Static)

Create a single HTML file that explains [concept, e.g. "row-level security"] 
visually. Use diagrams, color-coded sections, and clear labels. 
Structure it at 3 different levels of depth so I can read as much as I need.
Do not use external libraries — everything inline.

Design Variations Skill (reusable)

Turn this into a reusable Claude Code skill by saving:

---
name: design-variations
description: Generate N distinct HTML design variations for a component
argument-hint: "<component description> [N variations]"
---

Extract the described component from the codebase, generate $ARGUMENTS variations 
in a single self-contained HTML file, one per section with a labeled heading. 
Each variation must be visually distinct while respecting the app's existing 
color scheme and typography. Open the file automatically when done.

Save to ~/.claude/skills/design-variations/SKILL.md and invoke with:

/design-variations the bottom-right enrollment card on the landing page 20 variations

Complete Example: Design Variations

Scenario: You have a card component in your web app and don't like how it looks, but can't describe what "better" means.

Step 1 — Ask Claude:

For the PricingCard component in src/components/PricingCard.tsx, extract the 
visual structure and generate 15 HTML variations in a single file. Each 
variation should be clearly labeled (Variation 1, Variation 2, etc.). 
Keep the light theme. Make them visually distinct — try different layouts, 
typography scales, spacing approaches, and visual hierarchies. 
No external dependencies.

Step 2 — Claude generates pricing-card-variations.html and opens it.

Step 3 — You inspect. Scan through. Mark the ones that catch your eye.

I like variations 3 and 11. Variation 3 has the right hierarchy but 
too much whitespace. Variation 11 has the right density but wrong 
typography weight. Can you create a final version combining the layout 
of 3 with the typography of 11, then apply it back to PricingCard.tsx?

Step 4 — Claude merges the winning design back into the real component.

Complete Example: LinkedIn Post Preview

Step 1 — Provide the draft:

Here's a LinkedIn post I wrote. Can you render it as a realistic HTML preview 
of what it looks like on LinkedIn? Include a placeholder profile photo, 
my name "Simon", headline "Builder", and show it in desktop view.

---
Just shipped a new feature that cut our API response time by 40%.

The key insight: we were serializing the entire user object on every request 
when we only needed 3 fields.

Sometimes the fix isn't clever architecture — it's asking "what do we 
actually need here?"

#engineering #performance #lessismore
---

Step 2 — Review the HTML preview. Adjust copy directly in Claude:

The hashtags look cluttered at the end. Can you move them inline and 
also make the opening line punchier? Show me 3 alternative first-line options 
below the main preview.

Complete Example: Concept Explainer

Scenario: Claude Code added row-level security to your codebase and you need to understand it.

Step 1:

Can you make me a single HTML artifact explaining what row-level security (RLS) 
is? Structure it at 3 levels: beginner (what problem does it solve?), 
intermediate (how does it work in Postgres?), and advanced (performance 
implications and common patterns). Add a simple diagram showing what 
happens with and without RLS on a database query. Everything inline, 
no external libraries.

What Claude produces: A structured HTML page with expandable sections, a diagram, color-coded SQL examples, and a summary table.

Merging Back Into the App

Once you have a winning variant, use this pattern:

Variation [N] from pricing-card-variations.html is the winner. 
Please apply that design to src/components/PricingCard.tsx. 
Preserve all existing props and logic — only change the visual structure 
and styling. Show me a diff of what changed.

Tips

• Ask for 10–20 variations — with fewer you won't see the design space; with more the file gets unwieldy
• Keep constraints tight (same theme, same data) so variations differ only in design, not content
• Name the file descriptively: retrieval-settings-variations.html, not output.html
• Label each variation clearly (Variation 1 / Option A / Dark Compact) so you can refer back to them by name
• Ask for inline CSS only — external fonts/CDN links break when offline

Common Mistakes

Mistake	Fix
Asking for 1–2 variations	Ask for 10+; you need the design space explored
Vague component description	Reference file path + describe specific element
Not telling Claude to merge back	Explicitly ask: "apply variation N back to [file]"
Using external CDN links	Always say "no external dependencies, everything inline"
Treating artifact as deliverable	It's a selection tool. The deliverable is the merged component.