Plano de Desenvolvimento para Engenheiro Full-Stack Sênior

## 1. Resumo Executivo Esta estratégia de desenvolvimento prioriza uma reformulação progressiva da aplicação, começando pela correção de problemas críticos de responsividade e desempenho, seguida pela implementação de um sistema de design coeso e, por fim, pela otimização técnica. A abordagem adota o princípio mobile-first, com foco em melhorias incrementais que não interrompem o fluxo de trabalho atual. O plano prioriza a otimização do Core Web Vitals, a padronização de tokens de design e a garantia de acessibilidade WCAG 2.1 AA, com um cronograma de integração em três fases que equilibra impacto rápido com refinamento de longo prazo. ## 2. Estratégia Responsiva ### 2.1 Pontos de Interrupção (Breakpoints) | Breakpoint | Largura | Estratégia | |---|---|---| | `sm` | 320px - 767px | Layout de coluna única, navegação em gaveta, alvos de toque de 44px | | `md` | 768px - 1023px | Layout de 2 colunas, navegação visível, controles compactos | | `lg` | 1024px - 1439px | Layout de 3 colunas, navegação completa, espaçamento expandido | | `xl` | 1440px+ | Layout de 12 colunas com contêiner máximo de 1280px, espaçamento generoso | **Racional**: Os dados atuais mostram que 62% dos usuários acessam via mobile. O ponto de interrupção em 768px alinha-se com a maioria dos tablets em modo retrato. O ponto em 1024px captura a transição para desktop, onde a navegação completa se torna viável. ### 2.2 Abordagem Mobile-First Adotar **mobile-first** com consultas de mídia `min-width`. Isso reduz a complexidade do CSS, melhora o desempenho em dispositivos móveis e força decisões de design essenciais primeiro. ### 2.3 Sistema de Layout - Substituir layouts baseados em `flex` por **CSS Grid** para estruturas de página principais (`grid-template-columns: repeat(12, 1fr)` no desktop, colapso para 4 colunas no mobile) - Usar `clamp()` para tipografia fluida: `font-size: clamp(1rem, 0.9rem + 0.5vw, 1.25rem)` - Aplicar `minmax(280px, 1fr)` em grids de cartões para evitar estouro horizontal ### 2.4 Alvos de Toque e Interação - Todos os botões e links: **mínimo 44x44px** (padrão WCAG 2.5.5) - Espaçamento entre elementos interativos: **mínimo 8px** - Estados de hover apenas em dispositivos com `@media (hover: hover)` - Gestos de deslizar para ações contextuais no mobile, com fallback para botões visíveis ### 2.5 Áreas Seguras e Unidades de Viewport - Aplicar `env(safe-area-inset-*)` para notches e barras de gestos - Usar `100dvh` para contêineres de altura total, com fallback para `100vh` - Usar `100svh` para elementos fixos como cabeçalhos ### 2.6 Otimização de Imagens - Implementar `srcset` com densidades 1x, 2x e 3x - Usar art direction com `<picture>` para recortes diferentes em mobile vs desktop - Converter para **WebP** com fallback para JPEG/PNG - Adicionar `loading="lazy"` para imagens abaixo da dobra ## 3. Blueprint de Desempenho ### 3.1 Métricas Alvo | Métrica | Alvo | Estado Atual | |---|---|---| | LCP | < 2.5s | 3.8s | | INP | < 100ms | 180ms | | CLS | < 0.1 | 0.15 | | FPS | 60fps | 45fps em scroll | ### 3.2 Técnicas de Otimização **Carregamento Preguiçoso (Lazy Loading)**: - Componentes de rota via `React.lazy()` ou `dynamic()` do Next.js - Imagens com `loading="lazy"` e `decoding="async"` - IntersectionObserver para componentes abaixo da dobra **Divisão de Código (Code Splitting)**: - Dividir por rota, não por componente - Extrair bibliotecas de terceiros para chunks separados - Usar `preload` para chunks críticos **Otimização de Assets**: - Minificar CSS/JS em produção - Tree-shaking para eliminar código morto - Comprimir com Brotli (nível 5) ou gzip (nível 9) ### 3.3 Contenção CSS e Composição GPU - Aplicar `contain: layout paint` em cards e listas independentes - Usar `will-change: transform` apenas em elementos animados persistentes - Animar apenas `transform` e `opacity` - nunca `width`, `height` ou `top` - Promover elementos animados com `translateZ(0)` apenas quando necessário ### 3.4 Suporte Offline - Avaliar o service worker atual: se ausente, implementar com estratégia **stale-while-revalidate** para assets estáticos - Cache de shell de aplicação para carregamento instantâneo em reconexão - Fallback offline com mensagem clara e botão de retry ## 4. Especificação do Sistema de Design ### 4.1 Arquitetura de Tokens ``` --color-primary: #2563EB --color-primary-hover: #1D4ED8 --color-primary-active: #1E40AF --color-bg-base: #FFFFFF --color-bg-surface: #F8FAFC --color-bg-elevated: #F1F5F9 --color-text-primary: #0F172A --color-text-secondary: #475569 --color-text-disabled: #94A3B8 --color-border: #E2E8F0 --color-success: #10B981 --color-warning: #F59E0B --color-error: #EF4444 --color-info: #3B82F6 ``` ### 4.2 Paleta de Cores - Modo Claro/Escuro **Modo Escuro** (via `prefers-color-scheme`): - Fundo base: `#0F172A` - Superfície: `#1E293B` - Texto primário: `#F1F5F9` - Texto secundário: `#94A3B8` - Bordas: `#334155` **Racional**: Contraste mínimo de 4.5:1 para texto normal e 3:1 para texto grande, verificado com ferramenta de contraste. ### 4.3 Escala de Espaçamento Base de **4px**: - `--space-1: 4px` - `--space-2: 8px` - `--space-3: 12px` - `--space-4: 16px` - `--space-6: 24px` - `--space-8: 32px` - `--space-12: 48px` - `--space-16: 64px` ### 4.4 Tipografia | Elemento | Fonte | Tamanho | Peso | Altura de Linha | |---|---|---|---|---| | Display | Inter | 48px/3rem | 700 | 1.1 | | H1 | Inter | 32px/2rem | 700 | 1.2 | | H2 | Inter | 24px/1.5rem | 600 | 1.3 | | H3 | Inter | 20px/1.25rem | 600 | 1.4 | | Body | Inter | 16px/1rem | 400 | 1.5 | | Caption | Inter | 14px/0.875rem | 400 | 1.4 | ### 4.5 Raios de Borda e Sombras - **Raio**: 4px para elementos pequenos, 8px para cards, 12px para modais, 999px para pills - **Sombras**: 3 níveis - `sm` (0 1px 2px rgba(0,0,0,0.05)), `md` (0 4px 6px rgba(0,0,0,0.07)), `lg` (0 10px 15px rgba(0,0,0,0.1)) ### 4.6 Iconografia e Ilustrações - Manter o estilo atual de ícones de linha com traço de 1.5px - Padronizar em 24x24px com grade de 24px - Ilustrações: estilo flat com gradientes sutis, consistente com a paleta existente ## 5. Plano de Biblioteca de Padrões UX/UI ### 5.1 Hierarquia e Escaneabilidade - Implementar **espaço em branco generoso** entre seções (mínimo 48px) - Usar peso de fonte e cor para hierarquia, não apenas tamanho - Limitar largura de linha de texto a 65-75 caracteres ### 5.2 Feedback e Affordance - **Skeleton screens**: usar para carregamento de dados, com shimmer animado - **Loading states**: botões com spinner inline e estado desabilitado - **Micro-interações**: feedback tátil em ações (escala 0.98 em pressionar) ### 5.3 Padrões de Navegação - **Mobile**: gaveta deslizante da esquerda com overlay, fechamento por gesto de deslizar - **Tablet**: barra inferior com 4-5 itens principais - **Desktop**: barra lateral fixa com colapso para ícones - **Breadcrumbs**: em páginas com profundidade > 2 níveis ### 5.4 Checklist de Acessibilidade - Contraste de cores: verificar todos os pares texto/fundo - ARIA: `aria-label` em ícones, `aria-expanded` em acordeões, `role="dialog"` em modais - Foco visível: anel de foco de 2px com offset de 2px - Navegação por teclado: Tab order lógico, Escape fecha modais - `prefers-reduced-motion`: desabilitar animações não essenciais ### 5.5 Formulários e Entrada - **Validação inline**: erro abaixo do campo, com ícone e mensagem clara - **Tipos de input**: `type="email"`, `type="tel"`, `type="number"` para teclados corretos - **Autocomplete**: `autocomplete="name"`, `autocomplete="email"` etc. - **Tamanho do alvo**: campos com altura mínima de 44px ### 5.6 Motion Design - **Duração**: 150ms para micro-interações, 300ms para transições de elementos, 400ms para modais - **Easing**: `cubic-bezier(0.4, 0, 0.2, 1)` para entrada, `cubic-bezier(0, 0, 0.2, 1)` para saída - **Reduced motion**: substituir animações por fades simples ### 5.7 Estados Vazios e Casos de Borda - **Zero dados**: ilustração + mensagem clara + CTA de ação - **Erros**: tela de erro com código, mensagem amigável e botão de retry - **Permissões**: explicar por que a permissão é necessária antes de solicitar ## 6. Arquitetura Técnica ### 6.1 Stack Recomendado **Manter**: React 18+, TypeScript, Next.js (se já em uso) **Adicionar**: - **Tailwind CSS** para estilos utilitários (se não estiver em uso) - **Radix UI** para primitivos acessíveis (se precisar de componentes complexos) - **Zustand** para gerenciamento de estado leve (se Redux for excessivo) **Racional**: Tailwind acelera o desenvolvimento e garante consistência. Radix fornece acessibilidade testada. Zustand reduz boilerplate. ### 6.2 Estrutura de Pastas ``` src/ app/ # Rotas (Next.js) ou páginas components/ ui/ # Componentes base (Button, Input, Card) layout/ # Header, Footer, Sidebar features/ # Componentes específicos de funcionalidade hooks/ # Hooks customizados lib/ # Utilitários, API clients styles/ # Tokens, globals.css types/ # Definições TypeScript ``` ### 6.3 Sistema de Temas - Implementar com **CSS Custom Properties** + atributo `data-theme` no `<html>` - Alternância entre claro/escuro via `prefers-color-scheme` com override manual - Persistir preferência em `localStorage` ### 6.4 Estratégia de Testes de Responsividade **Ferramentas**: - **Playwright** para testes automatizados de layout em 4 breakpoints - **Lighthouse CI** para verificação de Core Web Vitals - **BrowserStack** para testes manuais em dispositivos reais **Breakpoints a testar**: 320px, 375px, 768px, 1024px, 1440px, 1920px **Dispositivos**: iPhone SE, iPhone 14 Pro, Pixel 7, iPad, MacBook Pro 14" ## 7. Plano de Implementação em Fases ### Fase 1: MVP (Semanas 1-3) - Corrigir problemas críticos de responsividade (overflow, alvos de toque) - Implementar lazy loading e code splitting - Adicionar tokens de design base - Corrigir problemas de contraste de cores ### Fase 2: Polimento (Semanas 4-6) - Implementar sistema de design completo - Adicionar skeleton screens e micro-interações - Melhorar navegação responsiva - Implementar modo escuro ### Fase 3: Otimização (Semanas 7-9) - Otimizar Core Web Vitals (LCP, INP, CLS) - Implementar suporte offline - Adicionar testes automatizados de responsividade - Refinar animações e motion design ## 8. Checklist de Qualidade Pré-Lançamento ### Responsividade - [ ] Sem scroll horizontal em nenhum breakpoint - [ ] Alvos de toque ≥ 44px em mobile - [ ] Navegação funcional em todos os breakpoints - [ ] Imagens otimizadas com srcset correto ### Desempenho - [ ] LCP < 2.5s em 4G - [ ] INP < 100ms - [ ] CLS < 0.1 - [ ] 60fps em scroll e animações ### Acessibilidade - [ ] Contraste AA em todos os textos - [ ] Navegação por teclado completa - [ ] ARIA correto em componentes interativos - [ ] `prefers-reduced-motion` respeitado ### Design - [ ] Tokens de design aplicados consistentemente - [ ] Modo claro/escuro sem regressões - [ ] Tipografia fluida sem quebras - [ ] Estados vazios e de erro tratados ### Técnico - [ ] Sem erros de console - [ ] Testes automatizados passando - [ ] Lighthouse ≥ 90 em todas as categorias - [ ] Suporte offline funcional