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

🧩 Qué es / qué hace

Definición precisa

O web-artifacts-builder es una suite de herramientas para crear artifacts de claude.ai elaborados y con varios componentes usando tecnologías modernas de frontend: React 18 + TypeScript + Tailwind CSS + shadcn/ui. No es para HTML simple: es para cuando necesitas estado, rutas, modales, tabs, sliders y toda la variedad de componentes Radix UI.

✓ Qué hace

✓ Inicializa un proyecto React+TS mediante init-artifact.sh
✓ Ofrece más de 40 componentes shadcn/ui preinstalados
✓ Configura alias de rutas (@/) automáticamente
✓ Empaqueta todo en un único bundle.html vía Parcel + html-inline
✓ Genera un artifact autocontenido, listo para pegar en claude.ai

✗ Lo que NO es

✗ No es para HTML/JSX simple de un solo archivo
✗ No es para artifacts estáticos sin interactividad
✗ No sustituye la skill frontend-design para páginas HTML/Tailwind directas
✗ No es para deploy en servidor: genera un artifact para claude.ai

Stack completo

React 18Motor de UI

TypeScriptvía Vite

Tailwind 3.4.1+ shadcn theming

Parcelbundling

artifact

HTML autocontenido

multicomponente

shadcn/ui + Radix

bundle.html

todo inline

context: fork

skill local

🎣 Cuándo se activa

Regla de oro

Usa web-artifacts-builder siempre que el artifact necesite estado (useState/useReducer), rutas o componentes shadcn/ui. Para HTML simple con Tailwind integrado, usa directamente el skill frontend-design.

Flujo de decisión: ¿necesito web-artifacts-builder?

¿El artifact tiene varias pantallas o pestañas con estado propio?

→ SÍ: usa web-artifacts-builder

¿Necesitas componentes shadcn/ui (Dialogs, Tooltips, Selects, Toasts)?

→ SÍ: usa web-artifacts-builder

¿Es una visualización interactiva con datos (dashboards, gráficos, formularios complejos)?

→ Probablemente SÍ

¿Es una landing page, una tarjeta, un modal simple o HTML estático?

→ NO: usa frontend-design o HTML directamente

✓ Usar cuando...

• La solicitud menciona "dashboard", "app", "wizard", "stepper"
• El artifact tendrá autenticación simulada o varios pasos
• El cliente quiere componentes Radix (Accordion, Command, etc.)
• Proyecto complejo con muchos archivos .tsx

✗ No usar cuando...

• El artifact es un único bloque JSX sin estado
• La solicitud es "crea una tarjeta bonita" o "dale estilo a este HTML"
• No hay manipulación de estado ni eventos complejos
• El plazo es corto y HTML/Tailwind simple resuelve el problema

disparador

estado + shadcn

mult pantalla

rutas / pasos

elaborado

no es de un solo archivo

complejidad

criterio central

🚀 Cómo mejora tus artifacts

🏗️

Estructura real de una app

En lugar de JSX en un solo archivo, tienes componentes separados, hooks personalizados y una arquitectura escalable — Claude Code gestiona cada archivo individualmente.

🎨

UI de producción

Los más de 40 componentes de shadcn/ui garantizan coherencia visual y accesibilidad sin esfuerzo. Radix UI se encarga de focus trap, ARIA y keyboard navigation.

📦

Entrega limpia

O bundle.html generado por Parcel + html-inline es completamente self-contained — cero dependencias externas para quien usa el artifact.

Incluye lineamientos de diseño

El SKILL.md incluye una directriz fundamental: "Para evitar lo que suele llamarse 'AI slop', evita usar demasiados diseños centrados, degradados morados, esquinas redondeadas uniformes y la fuente Inter." El resultado son artifacts con una identidad visual más sólida y menos genérica.

✓ Resultados que obtienes

✓ Dashboards con charts, filtros y estado persistente
✓ Wizards de varios pasos con validación por etapa
✓ Tablas de datos con sorting, pagination, search
✓ Paletas de comandos, drawers y sheets de shadcn
✓ Modo dark/light con tokens CSS correctos

✗ Sin el skill tendrías

✗ Archivo JSX único de 800+ líneas imposible de editar
✗ React desde CDN sin bundling — sin tree shaking
✗ Componentes Radix implementados desde cero
✗ Diseño genérico de «AI slop» sin identidad

shadcn/ui

40+ componentes

Radix UI

accesibilidad

anti-slop

guía de diseño

tree shaking

Parcel optimiza

⚙️ Cómo funciona por dentro

Pipeline completo en 5 pasos

init-artifact.sh <project-name>

Crea un proyecto React+TS con Vite, instala Tailwind 3.4.1 con el sistema de theming de shadcn, configura @/ como path alias, preinstala más de 40 componentes shadcn y todas las dependencias de Radix UI. Detecta automáticamente Node 18+ y fija la versión de Vite si es necesario.

Desarrollo de los componentes

Claude Code edita los archivos .tsx normalmente. Cada componente está en su propio archivo. Las importaciones usan @/components/ui/.... Tailwind y los tokens CSS de shadcn están disponibles globalmente.

bundle-artifact.sh

Instala dependencias de bundling (parcel, @parcel/config-default, parcel-resolver-tspaths, html-inline). Crea .parcelrc con soporte para path aliases. Compila con Parcel sin source maps. Usa html-inline para integrar todo el JS/CSS en el HTML final.

bundle.html → Claude.ai artifact

El archivo resultante bundle.html es completamente autocontenido — ninguna solicitud externa. Claude Code presenta el artifact directamente al usuario.

(Opcional) Probar con Playwright/Puppeteer

Paso opcional: ejecútalo solo si hay problemas o si el usuario lo pide. Evítalo de entrada porque añade latencia innecesaria antes de la entrega.

Dependencias reales del proyecto generado

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

alias de rutas

💬 Ejemplo práctico + PROMPT listo

Escenario: dashboard de métricas con filtros y gráfico

Quieres un artifact con: barra lateral de filtros, línea de tiempo interactiva, tarjetas KPI y un modal de detalles. Estado compartido entre componentes y modo oscuro nativo. Claramente, es un caso para web-artifacts-builder.

PROMPT — pégalo en 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

Consejo: estructura del proyecto generado

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

Atención: index.html obligatorio

O bundle-artifact.sh requiere que exista un index.html en la raíz del proyecto. El init-artifact.sh se crea automáticamente — no lo elimines.

prompt claro

lista componentes

datos de prueba

sin API real

shadcn list

indica los componentes

bundle final

siempre al final

🧬 Combina con / límites

🎨 + frontend-design

El combo más poderoso de la Ruta 1. Usa frontend-design para definir el lenguaje visual —grid, tipografía, espaciado, paleta— y web-artifacts-builder para ejecutar esa visión en React. El design-designer puede especificar el sistema de diseño antes del build.

frontend-design → sistema visual
web-artifacts-builder → implementación React

🎨 + theme-factory

O theme-factory (Ruta 2) genera tokens coherentes de color, tipografía y shadow. Puedes importar estos tokens directamente en tailwind.config.js del proyecto generado por web-artifacts-builder, garantizando la identidad de marca en el artifact.

theme-factory → tokens de marca
web-artifacts-builder → se aplica en la configuración de Tailwind

Posición en el ecosistema de skills

ANTES (Ruta 1)

frontend-design — define la estética

impeccable — refina la calidad visual

ESTÁS AQUÍ

web-artifacts-builder

implementación de varios componentes React

COMBINA CON (Ruta 2)

theme-factory — tokens de color

brand-guidelines — identidad

Límites reales de la skill

✗ No genera un deploy; solo un artifact local
✗ El bundle puede ser pesado para artifacts muy grandes
✗ Requiere Node 18+ en la máquina del usuario

✗ No admite llamadas reales a la API (artifact en sandbox)
✗ context: fork — skill local, no cloud
✗ No es adecuado para artifacts simples (sobrecarga innecesaria)

Design-designer como especificador

El skill design-designer (Módulo 1.4 de esta ruta) define la especificación visual antes de la implementación. Flujo recomendado para artifacts de alta calidad: design-designer (moodboard + spec) → frontend-design (revisión) → web-artifacts-builder (build React).

frontend-design

T1 complementaria

theme-factory

tokens Tailwind

design-designer

especificación antes de la construcción

context: fork

solo local

📋 Resumen del Módulo 1.3

Qué aprendiste

✓ web-artifacts-builder es una suite para artifacts React multicomponente en claude.ai
✓ Stack: React 18 + TypeScript + Vite + Tailwind 3.4.1 + shadcn/ui + Parcel
✓ Pipeline: init-artifact.sh → dev → bundle-artifact.sh → bundle.html
✓ Más de 40 componentes shadcn/ui y todas las dependencias de Radix UI preinstaladas
✓ Úsalo solo para artifacts complejos — el HTML simple no justifica el overhead
✓ Combina con frontend-design (estética), theme-factory (tokens) y design-designer (spec)

Próximo módulo

🎯

1.4 — design-designer

Especifica sistemas de diseño completos antes de construir

Aprende a usar design-designer para crear moodboards, definir grids, tipografía y paletas — la base visual que potencia todas las demás skills de la Trilha 1.

← Volver a la ruta 1 Próximo módulo: 1.4 design-designer →