Visualização de Dados com React e Next.js

O que Visualização de Dados com React e Next.js faz?

Visão Geral

Use esta skill quando a visualização estiver dentro de uma superfície de produto React ou Next.js. O foco não é apenas renderizar gráficos. O foco é ownership de componentes, segurança de hidratação, limites entre cliente e servidor, estratégia de bundle e integração limpa entre o React e a camada de visualização que está realmente desenhando as marcas.

Premissa padrão: O React deve ser responsável pela estrutura, layout e estado da aplicação, enquanto a camada de visualização gerencia escalas, geometria e renderização imperativa de escopo restrito.

Se a solicitação principal for sobre teste de screenshot, regressão visual, dados de gráfico simulados ou estratégia de cobertura E2E, roteie primeiro para ../testing-data-visualizations/SKILL.md e retorne a esta skill apenas para detalhes de implementação específicos do React ou Next.js.

Escolha Esta Skill Quando

• o usuário estiver construindo gráficos dentro de componentes React
• o aplicativo estiver usando Next.js, o App Router, ou limites entre componentes servidor e cliente
• o gráfico usar D3, Canvas, SVG, Vega-Lite, Plot, WebGL, deck.gl, PixiJS, Sigma.js ou Three.js dentro de uma superfície React
• a superfície usar Mermaid, React Flow, Cytoscape.js, Sprotty, JointJS, GoJS, ELK, Dagre, Graphviz/WASM, D2 ou outro renderizador de diagramas UML
• hidratação, SSR, carregamento dinâmico ou APIs exclusivas do navegador afetarem a implementação
• tamanho do bundle, carregamento em nível de rota e integração do produto forem importantes
• a página for uma história visual editorial que combina layout React, estados de scroll, parallax, gráficos fixos (sticky), assets gerados, camadas SVG/Canvas/D3/WebGL/Three.js, partículas, animação de fluxo e fallbacks de acessibilidade

Padrão de Trabalho

1. Decida quais partes são seguras para servidor e quais devem ser executadas no navegador.
2. Mantenha carregamento de dados, transformação, configuração do gráfico e preocupações da camada de renderização separados.
3. Estime quantas instâncias de gráfico podem estar visíveis em uma página ao mesmo tempo e se o trabalho caro pode ser compartilhado entre elas.
4. Deixe o React gerenciar layout, controles, estado de roteamento, affordances de persistência e resumos de estado ativo.
5. Deixe D3, Canvas, embeds de Vega-Lite, Plot, bibliotecas WebGL ou Three.js gerenciarem a renderização em nível de marca.
6. Modele o estado da visualização apoiado por URL explicitamente antes de conectar os controles: filtros, intervalo, métrica, comparação, entidade selecionada, aba ativa, limites do mapa, zoom, alvo da câmera e caminho de drill-down.
7. Use localStorage apenas para pequenas preferências pessoais; use IndexedDB ou armazenamento remoto para visualizações salvas maiores, rascunhos, fatias em cache, anotações personalizadas ou workspaces compartilhados/dispositivos cruzados. O estado da URL de entrada deve sobrescrever os padrões persistidos.
8. Use carregamento dinâmico ou limites exclusivos de cliente intencionalmente para código de visualização exclusivo do navegador.
9. Se o gráfico tiver interações de roda, pinça ou arrasto, torne o contrato do navegador explícito. Use um listener nativo não passivo ou hook de biblioteca quando a rolagem padrão precisar ser cancelada, e não presuma que o onWheel do framework é suficiente.
10. Para superfícies editoriais ou infográficas, mantenha o título da percepção (insight), modo de artefato, subtítulo, plano de anotação, nota de fonte, layout de tela grande, layout retrato móvel, layout paisagem móvel opcional e camada de renderização do gráfico como responsabilidades explícitas de componente. Use ../../references/foundations/mobile-first-responsive-visualization.md para decisões de toque, teclado, viewport visual, conexão instável e capacidade do dispositivo.
11. Para scrollytelling ou parallax, use ../scrollytelling-and-parallax-data-visualization/SKILL.md para o contrato da história. Modele cenas como estado tipado em vez de matemática de scroll ad hoc. Cada cena deve definir camadas visíveis, texto de anotação, assets de mídia, estado da câmera ou transformação, intervalo de gatilho/progresso, quadro-chave estático e fallback de movimento reduzido.
12. Para trabalho editorial avançado, relatório, deck, imagem gerada, animação ou integração em páginas existentes, use ../../references/foundations/meaning-preserving-visual-design-workflow.md e ../../references/foundations/mobile-first-responsive-visualization.md antes da implementação. Aplique o workflow compartilhado para imagens conceituais, variantes de tela grande/móvel, aprovação ou iteração, e o contrato de design semântico vinculante que o React deve implementar.
13. Para imagens geradas ou ilustrações, mantenha os assets em caminhos públicos determinísticos ou módulos importáveis, e mantenha rótulos/sobreposições de dados em camadas editáveis de propriedade do React.
14. Para WebGL, mantenha o ciclo de vida do renderizador, redimensionamento, perda de contexto, descarte e loops de animação dentro de um limite de componente restrito ao cliente. O React deve passar versões de dados e props, não mutar objetos GPU em toda a árvore.
15. Para diagramas UML interativos, ERD, dependência, máquina de estados, fluxo ou arquitetura, use ../uml-and-software-architecture-visualization/SKILL.md primeiro; o React deve gerenciar estado da aplicação, painéis, controles, roteamento e persistência enquanto a camada de diagrama gerencia detalhes de layout/renderização.
16. Para workspaces operacionais, use ../../references/foundations/operational-visualization-workspaces.md antes da decomposição de componentes. O React deve gerenciar estado do shell, barras de comando, gavetas, trilhos, resumos ativos, estado da URL e sincronização do inspetor enquanto a camada de visualização gerencia geometria, layout e seleção.

Orientação para Next.js

• Prefira Componentes Servidor para busca de dados, conteúdo de enquadramento e layout quando o gráfico não precisar de APIs do navegador ali.
• Use Componentes Cliente para gráficos interativos, medição de contêineres, eventos de ponteiro ou bibliotecas exclusivas do navegador.
• Use imports dinâmicos quando o runtime de gráfico não for necessário no caminho inicial ou deve evitar SSR.
• Mantenha assets do gráfico e caminhos de exportação determinísticos quando a mesma visualização precisar aparecer em relatórios ou documentos.
• Use parâmetros de rota ou parâmetros de busca como entrada canônica para estado de visualização compartilhável sempre que possível. Analise e normalize-os antes de inicializar o estado do gráfico restrito ao cliente para que visualizações vinculadas não pisquem através de padrões não relacionados.
• Use navegação do tipo replace para alterações transitórias de alta frequência e navegação do tipo push para seleções confirmadas, filtros aplicados, etapas de drill-down e transições de visualização salva.
• Para páginas de estilo de publicação, projete composições para desktop e móvel como estados irmãos, não como um único SVG comprimido.
• No móvel, mantenha a visualização principal primeiro ou imediatamente disponível. Coloque filtros secundários, inspetores e configurações em painéis recolhíveis, gavetas, bottom sheets ou controles em linha que preservem resumos de estado ativo e retornem o foco/scroll ao gráfico após Aplicar, Cancelar, Resetar ou fechar.
• Para workspaces densos, prefira um trilho de controle/outline no desktop, viewport central e trilho de inspetor; use uma barra de comando móvel com painéis de outline, filtro e detalhes em vez de empilhar os trilhos do desktop acima da visualização.
• Use window.visualViewport ou manipulação de redimensionamento equivalente para controles intensivos em teclado, para que fluxos de busca, filtro e anotação não ocultem a única ação crítica ou obscureçam permanentemente a visualização.
• Use Eventos de Ponteiro para interações personalizadas de toque/caneta/mouse sempre que possível, com touch-action explícito, áreas de toque ampliadas, alternativas de arrasto, controles de reset e nenhuma evidência exclusiva de hover.
• Use IntersectionObserver, Scrollama, useScroll do Motion, ScrollTrigger do GSAP, timelines CSS de scroll ou controles de passo explícitos com moderação e acessibilidade. A visualização padrão ainda deve comunicar a afirmação.
• Prefira scroll nativo e position: sticky para seções de história fixadas. Evite sequestro de scroll e mantenha o comportamento da roda, toque, barra de rolagem e teclado previsível.
• Use prefers-reduced-motion para alternar histórias animadas para layouts de estado final, quadro-chave ou escalonados.
• Carregue com lazy loading assets pesados de WebGL, 3D, vídeo ou geração de imagem sem causar mudança de layout (layout shift). Reserve proporções de aspecto e faixas de rótulos.
• Pause loops de animação WebGL quando fora da tela, oculto pela rota, em aba inativa ou com movimento reduzido ativo.

Expectativas de Saída

• Nomeie o limite de ownership entre React e a camada de visualização.
• Para trabalho explicativo, nomeie o título da percepção, modo de artefato, camada de anotação, estratégia de rótulo direto e caminho de leitura móvel.
• Para trabalho móvel, nomeie o layout retrato móvel, se paisagem é suportado, como os controles evitam cobrir o gráfico, como o teclado na tela se comporta e como interações de toque/pinça mapeiam para seleção, zoom, pan e reset.
• Para workspaces operacionais, nomeie os componentes do shell, estado selecionado padrão, comportamento sincronizado de outline/busca/filtro/inspetor, regra de limpeza de seleção em superfície vazia, painéis de comando móveis e estado do workspace apoiado por URL.
• Para trabalho com direção de arte, nomeie assets gerados ou ilustrados, estados de scroll/animação, comportamento de movimento reduzido e fallback de quadro estático.
• Para superfícies conceituadas, use o workflow de design compartilhado para imagens conceituais, status de aprovação, referências aprovadas, contrato de design semântico vinculante, elementos bloqueados e flexíveis, camadas de dados de propriedade do React, camadas de propriedade do renderizador, continuação móvel/paisagem e desvios aprovados.
• Para scrollytelling ou parallax, nomeie o controlador de scroll, contrato de cena, intervalos de gatilho/progresso, layout fixo (sticky), fallback móvel e quadros-chave estáticos.
• Para WebGL ou partículas, nomeie o renderizador, limite dados-para-buffer, clock de animação, caminho de limpeza/descarte, comportamento de movimento reduzido e fallback estático.
• Destaque qualquer código exclusivo de cliente ou sensível à hidratação explicitamente.
• Destaque qualquer interação que deva suprimir a rolagem nativa do navegador ou o encadeamento de scroll.
• Destaque qual estado é apoiado por URL, persistido localmente, apoiado por IndexedDB, salvo remotamente ou intencionalmente efêmero.
• Destaque o comportamento de copiar link, visualização salva, reset, refresh, voltar/avançar e estado de URL inválido.
• Destaque quais áreas de controle ou detalhes estão recolhidas por padrão ou podem ser fechadas, e como o estado ativo permanece visível.
• Destaque o comportamento da conexão de dados ao vivo no móvel: estado obsoleto, reconexão, dados offline/parciais, modo de largura de banda reduzida e estratégia de alerta/notificação quando relevante.
• Indique se o gráfico é adequado para SSR, renderização exclusiva de cliente ou carregamento dinâmico.
• Para trabalho novo, inclua uma seção de design técnico cobrindo contagem de instâncias simultâneas, desempenho por instância versus nível de página e implicações de manutenção do padrão de integração escolhido.
• Mantenha o tamanho do bundle, necessidades de exportação e acessibilidade visíveis no design.

Referências

• Teoria compartilhada:
  • ../../references/foundations/editorial-infographic-system.md
  • ../../references/foundations/art-directed-interactive-visual-stories.md
  • ../../references/foundations/meaning-preserving-visual-design-workflow.md
  • ../../references/foundations/task-abstraction-and-chart-selection.md
  • ../../references/foundations/perception-color-and-encoding.md
  • ../../references/foundations/shareable-state-and-persistence.md
  • ../../references/foundations/mobile-first-responsive-visualization.md
  • ../../references/foundations/operational-visualization-workspaces.md
  • ../../references/foundations/implementation-design-and-tradeoffs.md
• Referências da skill:
  • ./references/react-component-patterns.md
  • ./references/d3-canvas-and-grammar-in-react.md
  • ./references/nextjs-client-server-boundaries.md
  • ./references/lazy-loading-ssr-and-bundle-strategy.md
  • ../uml-and-software-architecture-visualization/SKILL.md
  • ../scrollytelling-and-parallax-data-visualization/SKILL.md
  • ../testing-data-visualizations/SKILL.md

Prompts Representativos

• "Como devo integrar este gráfico em um aplicativo React?"
• "Qual é o padrão React correto para D3, Canvas ou Vega-Lite aqui?"
• "Faça esta visualização funcionar de forma limpa no Next.js App Router."
• "Construa uma história de scrollytelling em React com gráficos fixos e fallback de movimento reduzido."
• "Este gráfico deve ser um Componente Cliente ou usar import dinâmico?"
• "Ajude-me a evitar problemas de hidratação e SSR com esta visualização."
• "Construa um diagrama interativo React UML, ERD, fluxo, máquina de estados, dependência ou arquitetura."