Artifacts Builder

# Artifacts Builder

Build production-quality Claude.ai artifacts — multi-component HTML/React UIs
that feel like real applications, not AI-generated demos.

## Keywords
artifact, claude.ai, react, jsx, tailwind, tailwindcss, shadcn, shadcn/ui, lucide,
recharts, frontend, single-file, web component, interactive UI, dashboard,
calculator, game, tool, form, simulator

## Core Truth

Default AI-generated UIs look the same: gray cards, blue buttons, lucide icons,
slate-500 text. Users see this and immediately know "AI made this." Quality
artifacts have visual identity — color, hierarchy, density, motion.

The artifact is single-file. CSS and JS must live with the component. shadcn
imports work but verify the component exists. Browser storage (localStorage,
sessionStorage) does NOT work — use React state.

---

## 1. When To Use

- Interactive tool the user will operate
- Visual data dashboard
- Calculator, converter, planner
- Mini-game or simulator
- Component library demo
- Decision tree or wizard

## 2. When NOT To Use

- Static content → use markdown
- Single chart → image_search or simple inline
- Document → use docx
- Long-form text → use markdown artifact

## 3. The Visual Identity Checklist

Before writing code, decide:
- **Palette** — pick 1 primary + 1 accent + neutrals. Not slate.
- **Density** — packed (admin tool) vs airy (consumer)?
- **Typography** — Inter for default, but consider monospace, serif for character
- **Motion** — transitions on hover, subtle slide-ins on state change
- **Edge** — sharp corners (technical), round (friendly), pill (playful)

Defaulting all of these makes "AI artifact" aesthetic.

## 4. The Stack

| Layer | What works |
|-------|-----------|
| Framework | React (default export, no required props) |
| Styling | Tailwind core utilities only — no compiler |
| Components | shadcn/ui via `@/components/ui/...` |
| Icons | lucide-react |
| Charts | recharts |
| State | useState, useReducer — NOT localStorage |
| Math | mathjs |
| Data | papaparse for CSV, SheetJS for Excel |

## 5. State Management Rules

- Local state via `useState` for component-scoped data
- Lifted state when siblings share data
- `useReducer` for complex state machines
- NO localStorage / sessionStorage — they fail in artifact sandbox
- NO IndexedDB
- Persist data via download (e.g., "Export to CSV") not storage

## 6. Component Composition

Single-file artifact pattern:
```jsx
import React, { useState } from 'react';
import { Button } from '@/components/ui/button';
import { Card } from '@/components/ui/card';
import { ChevronRight } from 'lucide-react';

// Sub-components
function Header({ title }) { /* ... */ }
function Sidebar() { /* ... */ }

// Main export
export default function App() {
  const [state, setState] = useState(initialState);
  return ( /* ... */ );
}
```

## 7. Common Pitfalls

| Problem | Cause | Fix |
|---------|-------|-----|
| Artifact fails to render | Used localStorage | Replace with useState |
| Tailwind class doesn't work | Used arbitrary value | Use core utility (no compiler) |
| Icon broken | Wrong lucide name | Verify at lucide.dev |
| Three.js missing geometry | Used r142+ feature | Stick to r128 features |
| shadcn component undefined | Wrong import path | `@/components/ui/[name]` |

## 8. Quality Bar

A finished artifact should:
- Work on first render without errors
- Look intentional, not default
- Have at least 2-3 interactive states
- Handle empty state and error state
- Be responsive (test at 320px width)

## 9. Key Questions Before Starting

- What does the user actually DO with this?
- What's the primary interaction (click, drag, input)?
- Is there state to preserve across rerender?
- What does success look like — what makes them say "this is great"?

## References
- `references/shadcn-components.md` — Verified working components
- `references/tailwind-safe-utilities.md` — Core utilities only
- `references/recharts-recipes.md` — Chart starters