Plano Gerador de Desenvolvimento de Aplicativo Web Responsivo

## 1. Resumo Executivo Este plano apresenta uma abordagem mobile-first e progressivamente aprimorada para construir uma aplicação web responsiva de alto desempenho. A estratégia central combina um sistema de design tokenizado com uma arquitetura de componentes atômicos, priorizando Core Web Vitals rigorosos (LCP <2.5s, INP <100ms, CLS <0.1) e acessibilidade WCAG 2.1 AA. A implementação segue uma ordem de fases que entrega um MVP funcional rapidamente, seguido de refinamentos de UX e otimizações de performance, garantindo uma experiência consistente e elegante em dispositivos de 320px a 1440px+. ## 2. Estratégia Responsiva ### Abordagem: Mobile-First **Justificativa:** A base mobile-first força a priorização de conteúdo e funcionalidades essenciais, resultando em um núcleo mais enxuto e performático. A complexidade visual e de layout é adicionada progressivamente via `min-width` media queries, o que é mais eficiente em termos de CSS e evita regras de "desfazer" estilos mobile em telas maiores. ### Pontos de Quebra (Breakpoints) | Breakpoint | Largura | Estratégia | | :--- | :--- | :--- | | **Base** | 320px - 767px | Layout de coluna única, navegação em gaveta (hambúrguer), alvos de toque de 44x44px. | | **Tablet (md)** | 768px - 1023px | Layout de 2 colunas, navegação com ícones + texto, uso de `dvh` para altura total. | | **Desktop (lg)** | 1024px - 1439px | Layout de 3 colunas, navegação completa visível, hover states ativos, atalhos de teclado. | | **Large (xl)** | 1440px+ | Layout de 12 colunas com container centralizado (max-width: 1440px), espaçamento generoso, tipografia fluida em escala. | **Racional:** Estes pontos de quebra são baseados em padrões de uso comuns e transições de layout naturais (ex: quando uma sidebar deixa de caber ao lado do conteúdo principal). Não nos baseamos em dispositivos específicos, mas em mudanças de layout. ### Sistema de Layout - **CSS Grid** para o layout da página e componentes complexos (ex: dashboard, listas de produtos). - **Flexbox** para componentes unidimensionais (ex: barras de navegação, grupos de botões, cartões). - **Container Queries** para componentes que precisam se adaptar ao seu container, não à viewport (ex: um widget de gráfico que pode estar em uma coluna estreita ou larga). ### Escala Fluida - **Tipografia Fluida:** Usar `clamp()` para dimensionar a fonte. Exemplo: `font-size: clamp(1rem, 0.8rem + 0.5vw, 1.25rem);` para texto de corpo. Isso garante uma transição suave entre breakpoints sem saltos bruscos. - **Espaçamento Fluido:** Usar `clamp()` para `padding` e `margin` em elementos-chave. Exemplo: `padding: clamp(1rem, 0.5rem + 2vw, 2rem);`. - **Unidades de Viewport Dinâmicas:** Usar `100dvh` para elementos de altura total (ex: hero sections, modais em tela cheia) para evitar problemas com barras de endereço dinâmicas em mobile. Fallback para `100vh` para navegadores mais antigos. ### Considerações Específicas - **Alvos de Toque:** Mínimo de 44x44px para todos os elementos interativos em touch. Em desktop, o hover state deve ser um aprimoramento, nunca a única forma de interação. - **Gestos de Toque:** Implementar *swipe* para carrosséis e listas, mas sempre com uma alternativa visível (ex: botões de seta). Usar a API Pointer Events para unificar mouse/touch/caneta. - **Hover States:** Em telas touch, hover não existe. Usar `@media (hover: hover)` para aplicar estilos de hover apenas em dispositivos que suportam. - **Navegação por Teclado:** Garantir uma ordem de tabulação lógica (`tabindex="0"` para elementos interativos), um indicador de foco visível (ex: `outline: 2px solid blue`) e suporte para teclas como Enter e Espaço. - **Notches e Safe Areas:** Usar `env(safe-area-inset-*)` para adicionar `padding` em elementos fixos (ex: barras de navegação inferior) em dispositivos com notch. - **Otimização de Imagens:** Usar `srcset` e `sizes` para servir imagens em diferentes resoluções. Para art direction (ex: cortar uma imagem de forma diferente em mobile), usar o elemento `<picture>` com múltiplas tags `<source>`. ## 3. Blueprint de Performance ### Metas (Core Web Vitals) - **LCP (Largest Contentful Paint):** < 2.5s (alvo: < 1.8s) - **INP (Interaction to Next Paint):** < 100ms (alvo: < 50ms) - **CLS (Cumulative Layout Shift):** < 0.1 (alvo: < 0.05) ### Técnicas e Estratégias - **Lazy Loading:** - **Imagens:** `loading="lazy"` para imagens abaixo da dobra. `fetchpriority="high"` para a imagem LCP. - **Componentes:** `React.lazy()` ou `dynamic()` (Next.js) para code splitting em nível de rota e para componentes pesados (ex: gráficos, editores de texto). - **Code Splitting:** Dividir o bundle principal em chunks menores. Separar o código de vendors (bibliotecas de terceiros) do código da aplicação. - **Otimização de Assets:** - **Imagens:** Usar formatos modernos (WebP/AVIF). Comprimir com ferramentas como `sharp` ou `imagemin`. - **CSS/JS:** Minificar e tree-shake. Usar `PurgeCSS` para remover CSS não utilizado. - **Fontes:** Usar `font-display: swap` para evitar FOIT (Flash of Invisible Text). Pré-carregar a fonte principal com `<link rel="preload">`. - **CSS Containment:** Usar `content-visibility: auto` em seções abaixo da dobra para pular a renderização inicial. Usar `contain: layout paint` em componentes isolados para limitar o escopo de reflows. - **Animations & Compositing:** - Animar apenas `transform` e `opacity` para garantir que as animações rodem na GPU. - Usar `will-change: transform` com moderação, apenas em elementos que serão animados e para evitar criar novas camadas de composição desnecessariamente. - Evitar animar `width`, `height`, `top`, `left`, que causam reflow. - **Offline Support / Degradação Graciosa:** - **Service Worker:** Implementar um service worker para cache de assets estáticos e shell da aplicação (App Shell model). Isso permite que a aplicação carregue instantaneamente em visitas repetidas e funcione offline. - **Fallback:** Se o service worker não for suportado, garantir que a aplicação degrade graciosamente com uma mensagem de "sem conexão" e um botão de retry. ### Ferramentas - **Lighthouse** para auditorias de performance, acessibilidade e SEO. - **WebPageTest** para testes de performance em diferentes dispositivos e conexões. - **Bundle Analyzer** (ex: `webpack-bundle-analyzer`) para identificar chunks grandes. ## 4. Especificação do Sistema de Design ### Arquitetura de Tokens Os tokens são a fonte única de verdade para decisões de design. Eles são definidos em um arquivo JSON/JS e consumidos por todas as plataformas. ```json { "color": { "bg": { "primary": "#FFFFFF", "secondary": "#F8F9FA" }, "text": { "primary": "#212529", "secondary": "#6C757D" }, "accent": { "primary": "#0D6EFD", "hover": "#0B5ED7" }, "status": { "success": "#198754", "warning": "#FFC107", "error": "#DC3545" } }, "spacing": { "xs": "4px", "sm": "8px", "md": "16px", "lg": "24px", "xl": "32px", "xxl": "48px" }, "typography": { "fontFamily": { "sans": "'Inter', sans-serif", "mono": "'JetBrains Mono', monospace" }, "fontSize": { "xs": "0.75rem", "sm": "0.875rem", "base": "1rem", "lg": "1.125rem", "xl": "1.25rem", "2xl": "1.5rem", "3xl": "1.875rem", "4xl": "2.25rem" }, "fontWeight": { "regular": 400, "medium": 500, "semibold": 600, "bold": 700 }, "lineHeight": { "tight": 1.2, "normal": 1.5, "relaxed": 1.75 } }, "elevation": { "sm": "0 1px 2px rgba(0,0,0,0.05)", "md": "0 4px 6px -1px rgba(0,0,0,0.1)", "lg": "0 10px 15px -3px rgba(0,0,0,0.1)" }, "motion": { "duration": { "fast": "150ms", "normal": "300ms", "slow": "500ms" }, "easing": { "standard": "cubic-bezier(0.4, 0, 0.2, 1)", "decelerate": "cubic-bezier(0, 0, 0.2, 1)", "accelerate": "cubic-bezier(0.4, 0, 1, 1)" } }, "breakpoints": { "md": "768px", "lg": "1024px", "xl": "1440px" } } ``` ### Estratégia de Cores (Light/Dark Mode) - **Light Mode:** Fundo branco (`#FFFFFF`) com texto quase preto (`#212529`). Usar azul (`#0D6EFD`) como cor de ação primária. - **Dark Mode:** Fundo escuro (`#212529`) com texto claro (`#F8F9FA`). A cor de ação primária deve ser mais clara (`#6EA8FE`) para manter o contraste. - **Implementação:** Usar a propriedade `color-scheme` e variáveis CSS. Alternar tokens de cor via `[data-theme="dark"]` no elemento `<html>`. ### Racional de Tipografia - **Fonte Principal:** **Inter** - Uma fonte sans-serif moderna, altamente legível em telas de baixa resolução e excelente para interfaces de usuário. Sua neutralidade permite que o conteúdo se destaque. - **Fonte Monoespaçada:** **JetBrains Mono** - Usada para código, números e dados técnicos. Ajuda a distinguir claramente esses elementos do texto regular. - **Escala:** Usar uma escala tipográfica modular (ex: 1.25) para criar uma hierarquia clara. A escala é definida nos tokens `fontSize`. ### Escala de Espaçamento - **Base:** 8px. Todos os espaçamentos são múltiplos de 8px (4px para espaçamentos menores). Isso cria um ritmo visual consistente. - **Uso:** `padding`, `margin`, `gap` em grids e flexbox. ### Filosofia de Raio de Borda - **Pequeno (4px):** Botões, inputs, chips. - **Médio (8px):** Cards, modais, dropdowns. - **Grande (16px):** Elementos de destaque, como um hero section ou um grande painel. - **Filosofia:** Raios pequenos para elementos funcionais e raios maiores para elementos de conteúdo. Isso cria uma hierarquia visual sutil. ### Sistema de Sombras - **sm:** Para elevação sutil, como cards em um fundo plano. - **md:** Para elementos que flutuam sobre o conteúdo, como dropdowns e popovers. - **lg:** Para modais e elementos de foco máximo. - **Filosofia:** Usar sombras para indicar profundidade e hierarquia, não como decoração. ### Iconografia - **Estilo:** Usar uma biblioteca de ícones de linha (outline) consistente, como **Lucide** ou **Heroicons**. Ícones de linha são mais limpos e escaláveis. - **Tamanho:** 16px para ícones inline, 20px para ícones em botões, 24px para ícones de navegação. - **Acessibilidade:** Todos os ícones decorativos devem ter `aria-hidden="true"`. Ícones com significado devem ter um `aria-label` ou texto associado. ### Imagens e Ilustrações - **Estilo:** Ilustrações planas com gradientes sutis e uma paleta de cores consistente com a marca. Evitar texturas complexas que aumentem o tamanho do arquivo. - **Fotografia:** Usar imagens de alta qualidade, otimizadas para a web. Aplicar um overlay sutil para garantir contraste com o texto sobreposto. ### Regras de Consistência de Componentes - **Estados:** Todo componente interativo deve ter estados definidos: `default`, `hover`, `focus`, `active`, `disabled`, `loading`, `error`. - **Hierarquia:** Botões primários (preenchidos), secundários (contorno) e terciários (texto). Usar a hierarquia para guiar a ação do usuário. - **Consistência:** Um botão deve ter a mesma aparência em toda a aplicação. Variações são criadas via props, não via CSS customizado. ## 5. Plano de Padrões de UX/UI ### Hierarquia e Escaneabilidade - **Padrão F:** Para páginas de conteúdo e leitura. Colocar o logo no topo esquerdo, navegação principal no topo, e o conteúdo mais importante no canto superior esquerdo. - **Padrão Z:** Para páginas de marketing e landing pages. Colocar o logo no topo esquerdo, CTA no topo direito, e seguir um fluxo visual em Z até o CTA final. - **Peso Visual:** Usar tamanho, cor e contraste para criar hierarquia. Elementos mais importantes são maiores e mais escuros. - **Estratégia de Espaço em Branco:** Usar espaçamento generoso para separar seções e grupos de conteúdo. O espaço em branco melhora a legibilidade e reduz a carga cognitiva. ### Feedback e Affordance - **Loading States:** Para ações que demoram mais de 300ms, mostrar um spinner ou skeleton screen. - **Skeleton Screens:** Usar placeholders que imitam a estrutura do conteúdo que está carregando. Isso reduz a percepção de tempo de espera e evita layout shift. - **Micro-interações:** Animações sutis que confirmam a ação do usuário (ex: um botão que muda de cor ao ser clicado, um item que é marcado como "favorito" com uma animação de coração). - **Error States:** Mensagens de erro claras e específicas, colocadas próximas ao elemento que causou o erro. Usar ícones e cores para chamar a atenção. ### Padrões de Navegação - **Mobile (<768px):** Menu hambúrguer que abre uma gaveta lateral. A gaveta deve ter uma sobreposição escura para focar a atenção no menu. - **Tablet (768px - 1023px):** Navegação inferior com ícones e rótulos para as 3-5 seções principais. Isso melhora a acessibilidade com o polegar. - **Desktop (1024px+):** Barra de navegação superior horizontal com links de texto. Usar breadcrumbs para páginas internas. - **Wayfinding:** O item de navegação ativo deve ser claramente destacado (ex: cor de fundo diferente ou um sublinhado). ### Acessibilidade (WCAG 2.1 AA) - **Contraste:** Garantir contraste de 4.5:1 para texto normal e 3:1 para texto grande (18pt+). Usar ferramentas de verificação de contraste. - **ARIA:** Usar roles e propriedades ARIA para elementos dinâmicos (ex: `role="dialog"` para modais, `aria-expanded` para menus). - **Gerenciamento de Foco:** Ao abrir um modal, mover o foco para dentro dele. Ao fechar, retornar o foco ao elemento que o abriu. Usar `focus-trap` para manter o foco dentro do modal. - **Suporte a Leitor de Tela:** Usar HTML semântico (`<nav>`, `<main>`, `<button>`, etc.). Fornecer `aria-label` para elementos que não têm texto visível. ### Formulários e Inputs - **Validação:** Validar em tempo real (on blur) para dar feedback imediato. Mostrar mensagens de erro inline, abaixo do campo. - **Tipos de Input:** Usar `type="email"`, `type="tel"`, `type="number"` para acionar o teclado correto no mobile. - **Autofill:** Usar `autocomplete` attributes (ex: `autocomplete="email"`, `autocomplete="given-name"`) para melhorar a experiência de preenchimento. - **UX de Erro:** A mensagem de erro deve explicar o que está errado e como corrigir (ex: "Digite um e-mail válido, como nome@exemplo.com"). ### Motion Design - **Propósito:** Animações devem ter um propósito claro: guiar a atenção, mostrar relação entre elementos, ou fornecer feedback. - **Duração:** Usar tokens de duração (150ms, 300ms, 500ms). Animações mais curtas para micro-interações, mais longas para transições de página. - **Easing:** Usar easing tokens. `decelerate` para elementos que entram na tela, `accelerate` para elementos que saem, `standard` para a maioria das interações. - **Reduced Motion:** Respeitar `prefers-reduced-motion: reduce`. Desabilitar animações não essenciais e transições suaves. ### Empty States e Edge Cases - **Zero Data:** Mostrar uma ilustração amigável, uma mensagem clara ("Nenhum resultado encontrado") e uma ação para o usuário tomar (ex: "Limpar filtros"). - **Erros:** Mostrar uma mensagem de erro clara, com um ícone e um botão de "Tentar novamente". - **Timeouts:** Se uma requisição demorar muito, mostrar um indicador de progresso e uma opção de cancelar. - **Permission Denied:** Explicar por que a permissão é necessária e como o usuário pode concedê-la (ex: "Ative a localização nas configurações do seu navegador"). ## 6. Arquitetura Técnica ### Stack Recomendado - **Framework:** **Next.js (App Router)** - Oferece SSR/SSG para performance e SEO, além de uma estrutura de rotas e code splitting automático. - **Linguagem:** **TypeScript** - Adiciona tipagem estática, melhorando a manutenibilidade e reduzindo erros. - **CSS:** **Tailwind CSS** - Utilitário-first, permite um desenvolvimento rápido e consistente. Usamos `@apply` para criar componentes customizados e manter a base de estilos limpa. - **State Management:** **Zustand** - Leve e escalável para estado global (ex: carrinho de compras, preferências do usuário). Para estado de servidor (dados da API), usar **TanStack Query**. - **Testes:** **Vitest** para testes unitários, **React Testing Library** para testes de componentes, **Playwright** para testes E2E e de responsividade. ### Arquitetura de Componentes Usar **Atomic Design** como base, mas adaptado para a realidade de uma aplicação web: - **Atoms:** Elementos básicos e indivisíveis (ex: `Button`, `Input`, `Label`, `Icon`). - **Molecules:** Combinações de atoms que formam uma unidade funcional (ex: `SearchBar`, `FormField`). - **Organisms:** Combinações de molecules e atoms que formam uma seção distinta da interface (ex: `Header`, `ProductCard`, `CheckoutForm`). - **Templates:** Combinações de organisms que formam uma página inteira (ex: `ProductListingPage`, `CheckoutPage`). - **Pages:** Instâncias específicas de templates com dados reais. ### Estrutura de Pastas ``` src/ ├── app/ # Rotas da aplicação (Next.js App Router) │ ├── layout.tsx │ ├── page.tsx │ └── ... ├── components/ │ ├── atoms/ │ ├── molecules/ │ ├── organisms/ │ └── templates/ ├── hooks/ # Custom hooks (ex: useLocalStorage, useMediaQuery) ├── lib/ # Utilitários e funções auxiliares ├── store/ # Zustand stores ├── styles/ # Tokens de design, configuração do Tailwind └── types/ # TypeScript types e interfaces ``` ### Implementação do Sistema de Theming - **Tailwind Config:** Estender o `tailwind.config.js` com os tokens de design (cores, fontes, espaçamentos). - **Dark Mode:** Usar a estratégia de classe do Tailwind (`darkMode: 'class'`). Alternar a classe `dark` no elemento `<html>` com base na preferência do usuário ou no tema do sistema. - **CSS Variables:** Para valores que precisam ser dinâmicos (ex: cores de um tema customizado), usar CSS variables definidas no `:root` e sobrescritas em `[data-theme="dark"]`. ### Estratégia de Testes de Responsividade - **Ferramentas:** **Playwright** para testes E2E. Ele permite emular dispositivos, testar em diferentes viewports e capturar screenshots. - **Breakpoints a Testar:** 320px, 375px, 768px, 1024px, 1440px. - **Dispositivos:** iPhone SE, iPhone 12/13, iPad, Desktop 1080p, Desktop 1440p. - **O que Testar:** - Layout não quebra (sem overflow horizontal). - Navegação funciona (menu hambúrguer abre/fecha). - Alvos de toque são grandes o suficiente. - Imagens carregam corretamente. - Formulários são utilizáveis. - Core Web Vitals estão dentro dos limites. ## 7. Plano de Implementação em Fases ### Fase 1: MVP (Semanas 1-2) - **Objetivo:** Entregar uma aplicação funcional e navegável em todos os dispositivos. - **Tarefas:** - Configurar o projeto Next.js + TypeScript + Tailwind. - Definir os tokens de design base (cores, tipografia, espaçamento). - Implementar o layout principal (header, footer, navegação). - Criar os componentes atômicos essenciais (Button, Input, Card). - Implementar as páginas principais com dados mockados. - Garantir que o layout seja responsivo (mobile-first). - Configurar testes E2E básicos para verificar a responsividade. ### Fase 2: Polimento de UX/UI (Semanas 3-4) - **Objetivo:** Refinar a experiência do usuário com foco em feedback, acessibilidade e motion design. - **Tarefas:** - Implementar estados de loading (skeletons, spinners). - Implementar estados de erro e empty states. - Adicionar micro-interações (hover, focus, active). - Implementar dark mode. - Auditar e corrigir problemas de acessibilidade (contraste, ARIA, foco). - Adicionar suporte a `prefers-reduced-motion`. ### Fase 3: Otimização de Performance (Semanas 5-6) - **Objetivo:** Atingir as metas de Core Web Vitals. - **Tarefas:** - Implementar lazy loading para imagens e componentes. - Otimizar assets (imagens, fontes, CSS, JS). - Implementar code splitting. - Adicionar um service worker para cache e suporte offline. - Auditar com Lighthouse e WebPageTest e corrigir gargalos. ### Fase 4: Lançamento e Iteração (Semana 7+) - **Objetivo:** Lançar a aplicação e iterar com base no feedback dos usuários. - **Tarefas:** - Testes finais em dispositivos reais. - Monitoramento de performance e erros em produção. - Coleta de feedback dos usuários. - Iterar no design e na funcionalidade com base nos dados. ## 8. Checklist de Qualidade Pré-Lançamento ### Responsividade - [ ] Layout não quebra em 320px, 375px, 768px, 1024px, 1440px. - [ ] Nenhum overflow horizontal em nenhum viewport. - [ ] Alvos de toque têm pelo menos 44x44px em mobile. - [ ] Navegação é utilizável em todos os dispositivos. - [ ] Imagens são responsivas e não distorcidas. - [ ] Formulários são utilizáveis em touch e teclado. ### Performance - [ ] LCP < 2.5s em conexão 4G. - [ ] INP < 100ms. - [ ] CLS < 0.1. - [ ] Nenhuma imagem acima da dobra é carregada com `loading="lazy"`. - [ ] Animações rodam a 60fps. ### Acessibilidade - [ ] Contraste de cor atende WCAG 2.1 AA. - [ ] Navegação por teclado funciona em toda a aplicação. - [ ] Todos os elementos interativos têm um estado de foco visível. - [ ] Modais e diálogos gerenciam o foco corretamente. - [ ] Leitor de tela consegue navegar e entender o conteúdo. - [ ] `prefers-reduced-motion` é respeitado. ### Design System - [ ] Todos os componentes usam tokens de design. - [ ] Dark mode é consistente e legível. - [ ] Tipografia é fluida e legível em todos os tamanhos. - [ ] Espaçamento é consistente. ### UX/UI - [ ] Todos os estados (loading, error, empty) são implementados. - [ ] Micro-interações são sutis e têm propósito. - [ ] Hierarquia visual é clara e guia o usuário. - [ ] Navegação é intuitiva e consistente. ### Técnico - [ ] Código é tipado com TypeScript. - [ ] Testes unitários e E2E passam. - [ ] Não há erros de console. - [ ] A aplicação funciona offline (ou degrada graciosamente).