Módulo 1.3 — web-artifacts-builder | Skill Design

🧩 O que é / o que faz

Definição precisa

O web-artifacts-builder é uma suite de ferramentas para criar artifacts claude.ai elaborados e multi-componente usando tecnologias modernas de frontend: React 18 + TypeScript + Tailwind CSS + shadcn/ui. Não é para HTML simples — é para quando você precisa de estado, rotas, modais, tabs, sliders e toda a riqueza de componentes Radix UI.

✓ O que faz

✓ Inicializa projeto React+TS via init-artifact.sh
✓ Disponibiliza 40+ componentes shadcn/ui pré-instalados
✓ Configura path aliases (@/) automaticamente
✓ Empacota tudo num único bundle.html via Parcel + html-inline
✓ Gera artifact self-contained pronto para colar no claude.ai

✗ O que NÃO é

✗ Não é para HTML/JSX single-file simples
✗ Não é para artifacts estáticos sem interatividade
✗ Não substitui o skill frontend-design para páginas HTML/Tailwind diretas
✗ Não é para deploy em servidor — gera artifact para claude.ai

Stack completo

React 18UI engine

TypeScriptvia Vite

Tailwind 3.4.1+ shadcn theming

Parcelbundling

artifact

HTML self-contained

multi-componente

shadcn/ui + Radix

bundle.html

tudo inline

context: fork

skill local

🎣 Quando dispara

Regra de ouro

Use web-artifacts-builder sempre que o artifact precisar de estado (useState/useReducer), rotas, ou componentes shadcn/ui. Para HTML simples com Tailwind embutido, use diretamente o skill frontend-design.

Fluxo de decisão: preciso do web-artifacts-builder?

O artifact tem múltiplas telas ou abas com estado próprio?

→ SIM: use web-artifacts-builder

Precisa de componentes shadcn/ui (Dialogs, Tooltips, Selects, Toasts)?

→ SIM: use web-artifacts-builder

É uma visualização interativa com dados (dashboards, charts, formulários complexos)?

→ Provavelmente SIM

É uma landing page, card, modal simples ou HTML estático?

→ NÃO: use frontend-design ou HTML direto

✓ Usar quando...

• Pedido menciona "dashboard", "app", "wizard", "stepper"
• Artifact terá autenticação simulada ou multi-step
• Cliente quer componentes Radix (Accordion, Command, etc.)
• Projeto complexo com muitos arquivos .tsx

✗ Não usar quando...

• Artifact é um único bloco JSX sem estado
• Pedido é "crie um card bonito" ou "estilize esse HTML"
• Não há manipulação de estado ou eventos complexos
• Prazo é curto e HTML/Tailwind simples resolve

gatilho

estado + shadcn

multi-tela

rotas / steps

elaborado

não single-file

complexidade

critério central

🚀 Como melhora seus artifacts

🏗️

Estrutura real de app

Ao invés de JSX num único arquivo, você tem componentes separados, hooks customizados e uma arquitetura escalável — o Claude Code gerencia cada arquivo individualmente.

🎨

UI de produção

Os 40+ componentes shadcn/ui garantem consistência visual e acessibilidade sem esforço. Radix UI por baixo resolve focus trap, ARIA e keyboard navigation.

📦

Entrega limpa

O bundle.html gerado pelo Parcel + html-inline é completamente self-contained — zero dependências externas para o usuário do artifact.

Guideline de design incluída

O SKILL.md traz uma diretriz crítica: "To avoid what is often referred to as 'AI slop', avoid using excessive centered layouts, purple gradients, uniform rounded corners, and Inter font." O resultado são artifacts com identidade visual mais forte e menos genérica.

✓ Resultados que você obtém

✓ Dashboards com charts, filtros e estado persistente
✓ Wizards multi-step com validação por etapa
✓ Data tables com sorting, pagination, search
✓ Command palettes, drawers, sheets do shadcn
✓ Dark/light mode com tokens CSS corretos

✗ Sem o skill você teria

✗ Arquivo JSX único de 800+ linhas impossível de editar
✗ CDN do React sem bundling — sem tree shaking
✗ Componentes Radix implementados do zero
✗ Layout genérico "AI slop" sem identidade

shadcn/ui

40+ componentes

Radix UI

acessibilidade

anti-slop

guideline design

tree shaking

Parcel otimiza

⚙️ Como funciona por dentro

Pipeline completo em 5 passos

init-artifact.sh <project-name>

Cria projeto React+TS via Vite, instala Tailwind 3.4.1 com sistema de theming do shadcn, configura @/ como path alias, pré-instala 40+ componentes shadcn e todas as dependências Radix UI. Auto-detecta Node 18+ e pina versão do Vite se necessário.

Desenvolvimento dos componentes

Claude Code edita os arquivos .tsx normalmente. Cada componente fica em arquivo próprio. Importações usam @/components/ui/.... Tailwind e shadcn tokens CSS disponíveis globalmente.

bundle-artifact.sh

Instala dependências de bundling (parcel, @parcel/config-default, parcel-resolver-tspaths, html-inline). Cria .parcelrc com suporte a path aliases. Compila com Parcel sem source maps. Usa html-inline para embutir todo JS/CSS no HTML final.

bundle.html → Claude.ai artifact

O arquivo resultante bundle.html é completamente self-contained — nenhuma requisição externa. Claude Code apresenta o artifact diretamente para o usuário.

(Opcional) Testar com Playwright/Puppeteer

Passo opcional — só execute se houver problemas ou se o usuário pedir. Evitar upfront pois adiciona latência desnecessária antes da entrega.

Dependências reais do projeto gerado

Build

vite (auto-version)
parcel
html-inline
parcel-resolver-tspaths

react@18
tailwindcss@3.4.1
shadcn/ui (40+)
@radix-ui/*

Config

.parcelrc
tsconfig.json (paths)
tailwind.config.js
components.json

Vite

dev server TS

Parcel

bundling final

html-inline

embed assets

.parcelrc

path aliases

💬 Exemplo prático + PROMPT pronto

Cenário: dashboard de métricas com filtros e gráfico

Você quer um artifact com: sidebar de filtros, linha do tempo interativa, cards de KPI e um modal de detalhes. Estado compartilhado entre componentes, dark mode nativo. Claramente um caso para web-artifacts-builder.

PROMPT — cole no Claude Code web-artifacts-builder

Crie um artifact claude.ai com dashboard de métricas de produto.

Requisitos:
- Sidebar com filtros de período (7d / 30d / 90d)
- 4 cards de KPI (usuários, sessões, conversão, receita)
- Gráfico de linha de tendência (simulado com dados mock)
- Modal de detalhes ao clicar num KPI
- Dark mode nativo com tokens shadcn/ui

Use o skill web-artifacts-builder:
1. Inicialize com scripts/init-artifact.sh dashboard-metricas
2. Crie os componentes em src/components/
3. Use shadcn/ui: Card, Dialog, Button, Select, Badge
4. Gere o bundle final com scripts/bundle-artifact.sh
5. Apresente o bundle.html como artifact

Dica: structure do projeto gerado

dashboard-metricas/
├── src/
│   ├── App.tsx
│   ├── components/
│   │   ├── ui/           ← shadcn/ui (40+ componentes)
│   │   ├── Sidebar.tsx
│   │   ├── KPICard.tsx
│   │   └── DetailModal.tsx
│   └── main.tsx
├── index.html            ← obrigatório para bundle
├── tailwind.config.js
└── .parcelrc             ← gerado pelo bundle-artifact.sh

Atenção: index.html obrigatório

O bundle-artifact.sh requer que exista um index.html na raiz do projeto. O init-artifact.sh cria automaticamente — não delete.

prompt claro

lista componentes

mock data

sem API real

shadcn list

cite os componentes

bundle final

sempre no final

🧬 Combina com / limites

🎨 + frontend-design

O combo mais poderoso da Trilha 1. Use frontend-design para definir a linguagem visual — grid, tipografia, espaçamento, paleta — e web-artifacts-builder para executar essa visão em React. O design-designer pode especificar o sistema de design antes do build.

frontend-design → sistema visual
web-artifacts-builder → implementação React

🎨 + theme-factory

O theme-factory (Trilha 2) gera tokens de cor, tipografia e shadow consistentes. Esses tokens podem ser importados diretamente no tailwind.config.js do projeto gerado pelo web-artifacts-builder, garantindo identidade de marca no artifact.

theme-factory → tokens de marca
web-artifacts-builder → aplica no Tailwind config

Posição no ecossistema de skills

ANTES (Trilha 1)

frontend-design — define estética

impeccable — refina qualidade visual

VOCÊ ESTÁ AQUI

web-artifacts-builder

implementação React multi-componente

COMBINA COM (Trilha 2)

theme-factory — tokens de cor

brand-guidelines — identidade

Limites reais do skill

✗ Não gera deploy — apenas artifact local
✗ Bundle pode ser pesado para artifacts muito grandes
✗ Requer Node 18+ na máquina do usuário

✗ Não suporta chamadas de API reais (artifact sandboxed)
✗ context: fork — skill local, não cloud
✗ Não é adequado para artifacts simples (overhead desnecessário)

Design-designer como especificador

O skill design-designer (Módulo 1.4 desta trilha) define a especificação visual antes da implementação. Fluxo recomendado para artifacts de alta qualidade: design-designer (moodboard + spec) → frontend-design (revisão) → web-artifacts-builder (build React).

frontend-design

T1 complementar

theme-factory

tokens Tailwind

design-designer

spec antes do build

context: fork

local apenas

📋 Resumo do Módulo 1.3

O que você aprendeu

✓ web-artifacts-builder é uma suite para artifacts React multi-componente no claude.ai
✓ Stack: React 18 + TypeScript + Vite + Tailwind 3.4.1 + shadcn/ui + Parcel
✓ Pipeline: init-artifact.sh → dev → bundle-artifact.sh → bundle.html
✓ 40+ componentes shadcn/ui e todas as dependências Radix UI pré-instaladas
✓ Só usar para artifacts complexos — HTML simples não justifica o overhead
✓ Combina com frontend-design (estética), theme-factory (tokens) e design-designer (spec)

Próximo módulo

🎯

1.4 — design-designer

Especifique sistemas de design completos antes de construir

Aprenda a usar o design-designer para criar moodboards, definir grids, tipografia e paletas — a base visual que potencializa todos os outros skills da Trilha 1.

← Voltar para Trilha 1 Próximo Módulo: 1.4 design-designer →