Gerador de Documento de Entrega de Design com Foco em IA

# Especificação de Implementação - ${name} ## Instruções para o Agente de Implementação de IA 1. Leia este documento por completo antes de escrever qualquer código. 2. Implemente na ordem especificada na SEÇÃO 1 (Mapa de Implementação). 3. Consulte o CLAUDE.md para valores de tokens. Se um token referenciado aqui não estiver no CLAUDE.md, sinalize-o e use o valor de fallback fornecido. 4. Cada valor neste documento é intencional. Não substitua por valores "aproximados". `gap-6` significa `gap-6`, não `gap-5`. 5. Cada estado deve ser implementado. Se um estado não for especificado para um componente, isso é uma lacuna na especificação - sinalize, não adivinhe. 6. Após implementar cada componente, percorra sua matriz de estados e verifique se todos os estados funcionam antes de passar para o próximo componente. 7. Ao encontrar ambiguidade, prefira a interpretação mais explícita. Se ainda assim for ambíguo, adicione um comentário TODO: "// HANDOFF-AMBIGUIDADE: [descrição]" --- ## SEÇÃO 1: MAPA DE IMPLEMENTAÇÃO | Ordem | Componente/Seção | Caminho do Arquivo | Dependências | Complexidade | Notas | |-------|------------------|-------------------|--------------|--------------|-------| | 1 | Configuração de tokens de design | `tailwind.config.ts` | Nenhuma | Baixa | Deve ser o primeiro - todos os outros componentes referenciam estes | | 2 | Componentes de tipografia | `src/components/ui/Text.tsx` | Tokens | Baixa | Variantes Heading, Body, Caption, Label | | 3 | Botão | `src/components/ui/Button.tsx` | Tokens, Tipografia | Média | 3 variantes × 3 tamanhos × 6 estados | | 4 | Container | `src/components/ui/Container.tsx` | Tokens | Baixa | Aplica larguras máximas e paddings de quebra | | 5 | Campo de entrada | `src/components/ui/Input.tsx` | Tokens, Tipografia | Média | Estados: padrão, foco, erro, sucesso, desabilitado | | 6 | Modal | `src/components/ui/Modal.tsx` | Tokens, Botão | Alta | Foco preso, bloqueio de rolagem, fechar por clique externo | | 7 | Toast | `src/components/ui/Toast.tsx` | Tokens | Média | Pilha de notificações, auto-dispensa | | 8 | Skeleton | `src/components/ui/Skeleton.tsx` | Tokens | Baixa | Formas: retângulo, círculo, card | | 9 | Navegação | `src/components/layout/Navigation.tsx` | Tokens, Botão | Alta | Horizontal ≥1024px, gaveta deslizante <1024px | | 10 | Rodapé | `src/components/layout/Footer.tsx` | Tokens | Baixa | Layout estático | | 11 | Página: ${page_name} | `src/app/${route}/page.tsx` | Todos os anteriores | Alta | Orquestra todas as seções | --- ## SEÇÃO 2: ESPECIFICAÇÕES GLOBAIS ### 2.1 Pontos de Quebra ``` BREAKPOINTS { mobile: 0px - 767px tablet: 768px - 1023px desktop: 1024px - 1279px wide: 1280px - ∞ } ``` | Breakpoint | Largura máx. do container | Padding do container | Tamanho base da fonte | Modo de navegação | |------------|---------------------------|----------------------|----------------------|-------------------| | mobile | 100% | `px-4` (16px) | 16px | Ícone de hambúrguer | | tablet | 100% | `px-6` (24px) | 16px | Ícone de hambúrguer | | desktop | `max-w-[1280px]` | `px-8` (32px) | 16px | Horizontal | | wide | `max-w-[1280px]` | `px-8` (32px) | 16px | Horizontal | ### 2.2 Padrões de Transição ``` TRANSITIONS { padrão: duration-200 ease-out lenta: duration-300 ease-in-out mola: duration-500 cubic-bezier(0.34, 1.56, 0.64, 1) nenhuma: duration-0 } REGRAS: Todo elemento interativo usa `padrão`, salvo indicação contrária neste documento. REGRAS: As transições se aplicam a: background-color, color, border-color, opacity, transform, box-shadow. Nunca a: width, height, padding, margin (causam recálculo de layout). ``` ### 2.3 Escala de Z-Index ``` Z-INDEX { base: 0 dropdown: 10 sticky: 20 overlay: 30 modal: 40 toast: 50 tooltip: 60 } REGRAS: Nenhum valor de z-index fora desta escala. Nunca. ``` ### 2.4 Estilo de Foco ``` FOCUS { estilo: ring-2 ring-offset-2 ring-brand-500 aplica-se: a todo elemento interativo (botões, links, entradas, seleções, caixas de seleção) visível: apenas na navegação por teclado (use focus-visible, não focus) } ``` --- ## SEÇÃO 3: ESPECIFICAÇÕES DE PÁGINA ### Página: ${page_name} **Rota:** `/exact-route-path` **Layout:** ${which_layout_wrapper_to_use} **Requisitos de dados:** [quais dados esta página precisa, de onde] #### Estrutura da Página (de cima para baixo) ``` ESTRUTURA DA PÁGINA: ${page_name} ├── Seção: Hero │ ├── Componente: Heading (h1) │ ├── Componente: Subheading (p) │ ├── Componente: Botão CTA (primário, lg) │ └── Componente: HeroImage ├── Seção: Recursos │ ├── Componente: SectionHeading (h2) │ └── Componente: FeatureCard × 3 (grade) ├── Seção: Depoimentos │ └── Componente: TestimonialSlider └── Seção: CTA ├── Componente: Heading (h2) └── Componente: Botão CTA (primário, lg) ``` #### Especificações Seção por Seção **${section_name}** ``` LAYOUT { container: max-w-[1280px] mx-auto px-6 (mobile: px-4) direção: flex-col (mobile) → flex-row (desktop) gap: gap-8 (32px) padding: py-16 (64px) (mobile: py-10) fundo: bg-white } CONTEÚDO { heading { texto: "${exact_heading_text_or_content_source}" elemento: h2 classe: text-3xl font-bold text-gray-900 (mobile: text-2xl) largura-máx: max-w-[640px] } corpo { texto: "${exact_body_text_or_content_source}" classe: text-lg text-gray-600 leading-relaxed (mobile: text-base) largura-máx: max-w-[540px] } } GRADE (se aplicável) { colunas: grid-cols-3 (tablet: grid-cols-2) (mobile: grid-cols-1) gap: gap-6 (24px) itens: ${what_component_renders_in_each_cell} alinhamento: items-start } ANIMAÇÃO (se aplicável) { tipo: fade-up ao rolar gatilho: quando a seção entra no viewport (limiar: 0.2) escalonamento: cada filho atrasa 100ms após o anterior duração: duration-500 easing: ease-out execuções: uma vez (não re-disparar ao rolar para cima) } ``` --- ## SEÇÃO 4: ESPECIFICAÇÕES DE COMPONENTES ### Componente: ${componentname} **Arquivo:** `src/components/${path}/${componentname}.tsx` **Finalidade:** [uma frase - o que este componente faz] #### Interface de Props ```typescript interface ${componentname}Props { variant: 'primary' | 'secondary' | 'ghost' // estilo visual size: 'sm' | 'md' | 'lg' // dimensões disabled?: boolean // padrão: false loading?: boolean // padrão: false icon?: React.ReactNode // ícone opcional à esquerda children: React.ReactNode // conteúdo do rótulo onClick?: () => void // manipulador de clique } ``` #### Matriz Variante × Tamanho Defina valores exatos para cada combinação: ``` VARIANTE: primary TAMANHO: sm altura: h-8 (32px) padding: px-3 (12px) fonte: text-sm font-medium (14px) fundo: bg-brand-500 (#2563EB) texto: text-white (#FFFFFF) borda: nenhuma raio-da-borda: rounded-md (6px) sombra: nenhuma TAMANHO: md altura: h-10 (40px) padding: px-4 (16px) fonte: text-sm font-medium (14px) fundo: bg-brand-500 (#2563EB) texto: text-white (#FFFFFF) borda: nenhuma raio-da-borda: rounded-lg (8px) sombra: shadow-sm TAMANHO: lg altura: h-12 (48px) padding: px-6 (24px) fonte: text-base font-semibold (16px) fundo: bg-brand-500 (#2563EB) texto: text-white (#FFFFFF) borda: nenhuma raio-da-borda: rounded-lg (8px) sombra: shadow-sm VARIANTE: secondary [mesma estrutura, valores diferentes] VARIANTE: ghost [mesma estrutura, valores diferentes] ``` #### Especificações de Estado Cada estado deve ser definido para cada variante: ``` ESTADOS (aplicam-se a TODAS as variantes, salvo substituição): hover { fundo: ${token} - escurecer um passo do padrão transform: nenhum (sem escala/translação no hover) sombra: ${token_ou_nenhum} cursor: pointer transição: padrão (duration-200 ease-out) } active { fundo: ${token} - escurecer dois passos do padrão transform: scale-[0.98] transição: duration-75 } focus-visible { anel: ring-2 ring-offset-2 ring-brand-500 todo o resto: igual ao estado padrão } disabled { opacidade: opacity-50 cursor: not-allowed pointer-events: none TODOS os estados hover/active/focus: não se aplicam } loading { conteúdo: substituir children por spinner (16px, animate-spin) largura: manter a mesma largura do estado sem loading (evitar mudança de layout) pointer-events: none opacidade: opacity-80 } ``` #### Comportamento do Ícone ``` REGRAS DE ÍCONE { posição: à esquerda do texto do rótulo (sempre) tamanho: 16px (sm), 16px (md), 20px (lg) gap: gap-1.5 (sm), gap-2 (md), gap-2 (lg) cor: herda a cor do texto (currentColor) ao carregar: o ícone fica oculto, o spinner ocupa sua posição somente-ícone: se não houver children, o componente fica quadrado (largura = altura) adicionar requisito de prop aria-label } ``` --- ## SEÇÃO 5: FLUXOS DE INTERAÇÃO ### Fluxo: [Nome do Fluxo, ex., "Usuário se Cadastra"] ``` GATILHO: usuário clica no botão "Cadastrar" no cabeçalho PASSO 1: Modal abre animação: fade-in (opacidade 0→1, duration-200) fundo: bg-black/50, clique fora fecha o modal foco: prender o foco dentro do modal, autofocar o primeiro campo corpo: bloqueio de rolagem (impedir rolagem do fundo) PASSO 2: Usuário preenche o formulário campos: ${list_exact_fields_with_validation_rules} validação: no blur (não no change - reduz ruído) campo: email { tipo: email obrigatório: true validar: padrão regex + "deve conter @ e domínio" erro: "Isso não parece um email - verifique se há erros de digitação" sucesso: ícone de checkmark verde aparece (fade-in, duration-150) } campo: senha { tipo: senha (com alternância mostrar/ocultar) obrigatório: true validar: mínimo 8 caracteres, 1 maiúscula, 1 número erro: mostrar lista de verificação de requisitos, destacar não atendidos força: mostrar barra de força (fraca/média/forte) } PASSO 3: Usuário envia botão: mostra estado de loading (ver especificação do componente Botão) requisição: POST /api/auth/signup duração: esperar 1-3 segundos PASSO 4a: Sucesso modal: conteúdo transita para mensagem de sucesso (crossfade, duration-200) mensagem: "Conta criada! Verifique seu email para confirmar." ação: botão "Entendi" fecha o modal redirecionar: após fechar, redirecionar para /dashboard toast: nenhum (o modal JÁ é a confirmação) PASSO 4b: Erro - email existe campo: campo de email mostra estado de erro mensagem: "Este email já possui uma conta - deseja entrar?" ação: link "Entrar" alterna o modal para o formulário de login botão: retorna ao estado padrão (sem loading) PASSO 4c: Erro - falha de rede exibição: banner de erro no topo do modal (não um toast) mensagem: "Algo deu errado em nosso servidor. Tentar novamente?" ação: botão "Tentar novamente" re-envia botão: retorna ao estado padrão PASSO 4d: Erro - limite de taxa exibição: banner de erro mensagem: "Muitas tentativas. Aguarde 60 segundos e tente novamente." botão: desabilitado por 60 segundos com contagem regressiva visível ``` --- ## SEÇÃO 6: REGRAS DE COMPORTAMENTO RESPONSIVO Não descreva o que muda - especifique as regras exatas: ``` REGRAS RESPONSIVAS: Regra 1: Navegação ≥1024px: navegação horizontal, todos os itens visíveis <1024px: ícone de hambúrguer, gaveta deslizante da direita largura-da-gaveta: 80vw (max-w-[320px]) animação: translate-x (duration-300 ease-out) fundo: bg-black/50, clique fora fecha Regra 2: Seções de Grade ≥1024px: grid-cols-3 768-1023px: grid-cols-2 (último item ocupa largura total se contagem for ímpar) <768px: grid-cols-1 Regra 3: Seção Hero ≥1024px: duas colunas (texto à esquerda, imagem à direita) - divisão 55/45 <1024px: coluna única (texto em cima, imagem embaixo) altura-máx-da-imagem: 400px, object-cover Regra 4: Escala de Tipografia ≥1024px: h1=text-5xl, h2=text-3xl, h3=text-xl, corpo=text-base <1024px: h1=text-3xl, h2=text-2xl, h3=text-lg, corpo=text-base Regra 5: Escala de Espaçamento ≥1024px: padding-da-seção: py-16, padding-do-container: px-8 768-1023px: padding-da-seção: py-12, padding-do-container: px-6 <768px: padding-da-seção: py-10, padding-do-container: px-4 Regra 6: Alvos de Toque <1024px: todos os elementos interativos com área de toque mínima de 44×44px se o tamanho visual < 44px, usar padding invisível para atingir 44px Regra 7: Imagens todas as imagens: usar next/image com prop sizes responsiva hero: sizes="(max-width: 1024px) 100vw, 50vw" itens de grade: sizes="(max-width: 768px) 100vw, (max-width: 1024px) 50vw, 33vw" ``` --- ## SEÇÃO 7: CASOS LIMITE E CONDIÇÕES DE FRONTEIRA Esta seção previne os problemas de "mas o que acontece quando...": ``` CASOS LIMITE: Estouro de Texto { headings: máx. 2 linhas, depois truncar com text-ellipsis (adicionar atributo title para o texto completo) texto do corpo: permitir quebra natural, sem truncamento rótulos de botão: linha única apenas, máx. 30 caracteres, sem truncamento (restrição de design) itens de navegação: linha única, truncar se >16 caracteres no mobile células de tabela: truncar com tooltip no hover } Estados Vazios { listas/grades com 0 itens: mostrar componente ${emptystate} - ilustração: ${describe_or_reference_asset} - heading: "${exact_text}" - corpo: "${exact_text}" - CTA: "${exact_text}" → ${action} avatar de usuário ausente: mostrar iniciais em fundo colorido - fundo: gerar a partir do hash do nome do usuário (determinístico) - iniciais: primeira letra do primeiro + último nome, maiúsculas - fonte: text-sm font-medium text-white falha ao carregar imagem: mostrar placeholder cinza com ícone de imagem - fundo: bg-gray-100 - ícone: ImageOff do lucide-react, text-gray-400, 24px } Estados de Loading { carregamento de página: skeleton de página inteira (não spinner) carregamento de componente: skeleton no nível do componente correspondendo às dimensões finais ação de botão: spinner inline no botão (ver especificação do Botão) lista infinita: linha de skeleton × 3 na parte inferior ao buscar a próxima página estilo do skeleton: bg-gray-200 rounded animate-pulse regra do skeleton: a forma do skeleton deve corresponder à forma do conteúdo final (retângulo para texto, círculo para avatares, rounded-lg para cards) } Estados de Erro { erro de API (500): mostrar banner de erro inline com botão de tentar novamente erro de rede: mostrar banner "Você parece estar offline" no topo (dispensar automaticamente ao reconectar) conteúdo 404: mostrar componente 404 personalizado (não o padrão do Next.js) permissão negada: redirecionar para /login com parâmetro de URL de retorno validação de formulário: inline por campo (ver especificações de fluxo), nunca alert() } Extremos de Dados { nome de usuário com 1 caractere: exibir normalmente nome de usuário com 50 caracteres: truncar em 20 na navegação, completo no perfil preço $0.00: mostrar "Grátis" preço $999.999,99: garantir que o layout não quebre (testar com número formatado) lista com 1 item: mesmo layout de múltiplos (sem caso especial) lista com 500 itens: paginar em 20, mostrar botão "Carregar mais" data de hoje: mostrar "Hoje" em vez da data data deste ano: mostrar "13 mar" em vez de "13 mar, 2026" data de outro ano: mostrar "13 mar, 2025" } ``` --- ## SEÇÃO 8: LISTA DE VERIFICAÇÃO DE VERIFICAÇÃO DE IMPLEMENTAÇÃO Após a implementação, o agente de IA (ou desenvolvedor humano) deve verificar: ``` VERIFICAÇÃO: ☐ Cada componente corresponde exatamente à matriz variante × tamanho ☐ Cada estado (hover, active, focus, disabled, loading) funciona ☐ A ordem de tabulação segue a ordem visual em todas as páginas ☐ O anel de focus-visible aparece na navegação por teclado, não no clique do mouse ☐ Todas as transições usam duração e easing especificados (não o padrão do navegador) ☐ Sem mudança de layout durante o carregamento da página (verificar CLS) ☐ Estados de skeleton correspondem às dimensões do conteúdo final ☐ Todos os casos limite da Seção 7 são tratados ☐ Alvos de toque ≥ 44×44px nos breakpoints mobile ☐ Sem rolagem horizontal em nenhum breakpoint ☐ Todas as imagens usam next/image com prop sizes correta ☐ Valores de z-index usam apenas a escala definida ☐ Estados de erro exibem corretamente (testar com throttling de rede) ☐ Estados vazios exibem corretamente (testar com dados vazios) ☐ Truncamento de texto funciona nos comprimentos limite ☐ Tokens de modo escuro (se aplicável) estão todos mapeados ```