Iniciando um projeto React web
Leia primeiro web-craft; suas regras se aplicam aqui. As decisões existentes do projeto prevalecem sobre qualquer padrão abaixo.
1. Intake
Leia o que já foi fornecido: descrição do produto, repositório existente, páginas, sistema de design, STACK.md, DESIGN.md, contratos de API. Em seguida, preencha as lacunas com references/intake.md: tipo de superfície (landing, editorial, catálogo, aplicativo de consumo, admin, portal do cliente ou misto), usuário e ação principal, densidade de conteúdo ou operação, dispositivos, necessidades de SEO, idiomas agora e no futuro, RTL, autenticação, backend (Node.js, API de terceiros, CMS, mock ou estático).
Pergunte apenas o que altera uma decisão de produto ou arquitetura. Declare o restante como suposições.
2. Decida o perfil técnico
Escreva cada decisão com uma justificativa de uma linha. Não gere todas as telas antes que a direção seja escolhida.
| Decisão | Padrão e onde a justificativa reside |
|---|---|
| Framework e renderização | Público, com foco em SEO ou CMS e multilíngue → Next.js App Router. Atrás de um login e altamente interativo → React + Vite ou o Next.js existente. Superfície estática simples → a coisa mais simples que funciona. references/framework-choice.md |
| Kit UI | Produto com marca distinta → shadcn/ui. Admin com muitos formulários/tabelas → Ant Design. Produto estilo Material ou já usando MUI → Material UI. Sistema existente → mantenha-o. Um kit principal por superfície do aplicativo. references/kit-choice.md |
| Estilização | Segue o kit: shadcn → Tailwind (exigido pelo shadcn); Ant Design ou MUI → tema do kit, mais CSS Modules para peças personalizadas; personalizado ou editorial → CSS Modules. Nunca misture Tailwind e CSS Modules como sistemas iguais em uma superfície. references/styling-choice.md |
| i18n | Next.js → next-intl; Vite → i18next + react-i18next. Registro de localidade, fallback, política de URL e carregamento de catálogo são decididos no primeiro dia. references/i18n-setup.md |
| Animação | Transições CSS para estado simples; Motion para React quando montagem/desmontagem, layout ou orquestração são necessários. Tokens de duração e easing; movimento reduzido tratado em um único lugar. references/motion-setup.md |
| Formulários e dados | react-hook-form + Zod; TanStack Query ou o modelo de dados do framework; mantenha o que existe. |
| Tema | Claro/Escuro/Sistema para produtos interativos; um tema único pode ser uma decisão de produto para um site de marketing institucional. |
| Testes | Typecheck, lint (com eslint-plugin-web-craft e eslint-plugin-jsx-a11y), testes de unidade/componente onde reside o comportamento, Playwright para fluxos críticos. |
| Linguagem e ferramentas | TypeScript estrito, Yarn fixado por projeto, um lockfile. |
Verifique as versões estáveis atuais de cada pacote escolhido nas fontes oficiais no dia, fixe versões que funcionam juntas e registre-as em STACK.md. Nunca copie números de versão da memória ou deste skill.
3. Escreva os documentos do projeto
STACK.md: framework, renderização, kit, estilização, mecanismo de i18n, ferramentas de dados e formulários, versões, ambientes, scripts. Modelo:references/stack-template.md.DESIGN.md: caráter do produto, princípios extraídos das referências, layout, tokens (cor, tipo, espaçamento, raio, elevação, animação), regras de copy, matriz de animação, notas de i18n. Modelo:references/design-template.md.- A lista de localidades e tipos vêm da configuração de código. Os documentos descrevem; não são uma segunda fonte da verdade.
- Não crie quatro novos documentos para cada pequena alteração.
4. Estruture o projeto
Estrutura baseada em funcionalidades, limites claro entre servidor/cliente, uma camada de API, um lugar para tokens e providers: references/structure.md.
5. Prove o esqueleto
Antes de construir mais telas, um pequeno fluxo deve funcionar de ponta a ponta:
- A localidade resolve corretamente na primeira renderização (sem flash de idioma); a troca mantém a rota.
- O tema segue a escolha do usuário e o sistema, sem flash no carregamento.
- Um formulário valida no blur, rola para o primeiro erro ao enviar, mapeia um erro do servidor para seu campo.
- Um diálogo anima para entrar e sair, prende o foco e o retorna; movimento reduzido remove o movimento grande.
- Uma lista ou gráfico mostra um esqueleto, um estado vazio e um erro com retry.
- O uso apenas com teclado funciona; nenhum erro no console ou de hidratação.
Em seguida, construa uma fatia vertical representativa (conteúdo real, segundo idioma, estados de carregamento e erro) e verifique em um navegador nas larguras mobile e desktop antes de expandir para outras telas.
6. Scripts
dev, build, start (Next.js), typecheck, lint, test, test:e2e. Adicione analyze quando os orçamentos de bundle forem importantes.
Fontes
Links oficiais usados para esses padrões, com a data em que foram revisados: references/sources.md. Re-verifique-os para a versão que você instalar.