Iniciando un proyecto web React
Lee primero web-craft; sus reglas se aplican aquí. Las decisiones existentes del proyecto tienen prioridad sobre cualquier valor predeterminado que se indica a continuación.
1. Intake
Lee lo que ya está disponible: descripción del producto, repositorio existente, páginas, sistema de diseño, STACK.md, DESIGN.md, contratos de API. Luego completa los vacíos con references/intake.md: tipo de superficie (landing, editorial, catálogo, aplicación de consumo, administración, portal de clientes o una combinación), usuario principal y acción, densidad de contenido u operaciones, dispositivos, necesidades de SEO, idiomas ahora y en el futuro, RTL, autenticación, backend (Node.js, API de terceros, CMS, simulación o estático).
Pregunta solo aquello que cambie una decisión de producto o arquitectura. Indica el resto como suposiciones.
2. Decide el perfil técnico
Escribe cada decisión con una razón de una línea. No generes todas las pantallas antes de que se haya elegido la dirección.
| Decisión | Valor predeterminado y dónde reside el razonamiento |
|---|---|
| Framework y renderizado | Público, con mucho SEO o CMS, multilingüe → Next.js App Router. Detrás de un inicio de sesión y altamente interactivo → React + Vite o el Next.js existente. Superficie estática simple → lo más simple que funcione. references/framework-choice.md |
| Kit de UI | Producto con marca distintiva → shadcn/ui. Administración con muchas tablas/formularios → Ant Design. Producto con estilo Material o MUI ya en uso → Material UI. Sistema existente → mantenerlo. Un kit principal por superficie de aplicación. references/kit-choice.md |
| Estilos | Sigue al kit: shadcn → Tailwind (obligatorio para shadcn); Ant Design o MUI → el tema del kit, más CSS Modules para piezas personalizadas; personalizado o editorial → CSS Modules. Nunca mezcles Tailwind y CSS Modules como sistemas equivalentes en una sola superficie. references/styling-choice.md |
| i18n | Next.js → next-intl; Vite → i18next + react-i18next. El registro de locales, la configuración de fallback, la política de URL y la carga del catálogo se deciden desde el primer día. references/i18n-setup.md |
| Animación | Transiciones CSS para estados simples; Motion para React cuando se necesite montaje/desmontaje, layout u orquestación. Tokens de duración y easing; el reduced motion se maneja en un solo lugar. references/motion-setup.md |
| Formularios y datos | react-hook-form + Zod; TanStack Query o el modelo de datos del framework; mantener lo que existe. |
| Tema | Claro/Oscuro/Sistema para productos interactivos; un solo tema puede ser una decisión de producto para un sitio de marketing con marca. |
| Pruebas | Typecheck, lint (con eslint-plugin-web-craft y eslint-plugin-jsx-a11y), pruebas unitarias/de componente donde haya comportamiento, Playwright para flujos críticos. |
| Lenguaje y herramientas | TypeScript estricto, Yarn fijado por proyecto, un único lockfile. |
Verifica las versiones estables actuales de cada paquete elegido desde fuentes oficiales el mismo día, fija las versiones que funcionan juntas y regístralas en STACK.md. Nunca copies números de versión de memoria o de esta skill.
3. Escribe los documentos del proyecto
STACK.md: framework, renderizado, kit, estilos, motor i18n, herramientas de datos y formularios, versiones, entornos, scripts. Plantilla:references/stack-template.md.DESIGN.md: carácter del producto, principios tomados de las referencias, layout, tokens (color, tipografía, espaciado, radio, elevación, animación), reglas de copy, matriz de animación, notas de i18n. Plantilla:references/design-template.md.- La lista de locales y los tipos provienen de la configuración del código. Los documentos lo describen; no son una segunda fuente de verdad.
- No crees cuatro documentos nuevos por cada pequeño cambio.
4. Organiza el proyecto
Estructura basada en funcionalidades, límites servidor/cliente claros, una capa de API, un lugar para tokens y proveedores: references/structure.md.
5. Verifica el esqueleto
Antes de construir más pantallas, un flujo pequeño debe funcionar de extremo a extremo:
- El locale se resuelve correctamente en el primer renderizado (sin flash de idioma), al cambiar se mantiene la ruta.
- El tema sigue la elección del usuario y el sistema, sin parpadeo al cargar.
- Un formulario valida al perder el foco, se desplaza al primer error al enviar, mapea un error del servidor a su campo.
- Un diálogo se anima al entrar y salir, atrapa el foco y lo devuelve; el reduced motion elimina el movimiento grande.
- Una lista o gráfico muestra un esqueleto, un estado vacío y un error con reintento.
- El uso solo con teclado funciona; no hay errores de consola ni de hidratación.
Luego construye un slice vertical representativo (contenido realista, segundo idioma, estados de carga y error) y verifícalo en un navegador a anchos de móvil y escritorio antes de expandir a otras pantallas.
6. Scripts
dev, build, start (Next.js), typecheck, lint, test, test:e2e. Añade analyze cuando los presupuestos de bundle importen.
Fuentes
Enlaces oficiales utilizados para estos valores predeterminados, con la fecha en que se revisaron: references/sources.md. Vuelve a verificarlos para la versión que instales.