coastdigitalgroup/coastai-skills

Sistema de Galeria de Imagens e Lightbox

Propósito

O Sistema de Galeria de Imagens e Lightbox fornece uma metodologia de design rigorosa para exibir coleções de mídia na web. Ele estrutura como um grupo de imagens ou vídeos é apresentado em uma grade estática (a galeria) e como esses ativos fazem a transição para uma sobreposição de alto impacto, livre de distrações e em tela cheia (o lightbox). Este sistema garante que portfólios visuais, zooms de produtos em e-commerce e estudos de caso permaneçam altamente responsivos, mantenham conformidade profunda de acessibilidade (WCAG AA) e suportem dispositivos físicos por meio de gestos de toque, controles de teclado e armadilhas de foco.

Casos de Uso

• Sites de portfólio exibindo fotografia, arte, designs arquitetônicos ou estudos de caso.
• Páginas de Detalhes de Produto (PDPs) de e-commerce que exigem exploração detalhada de imagens em grande escala.
• Sites de mídia ricos em conteúdo, onde artigos apresentam galerias de fotos interativas.
• Páginas de eventos e landing pages de marketing exibindo fotografia de eventos ou registros de depoimentos.
• Sites imobiliários apresentando propriedades com tours de alta resolução de interiores e exteriores.

Quando NÃO Usar

• Mídia Única de Fundo ou Inline: Para imagens de fundo únicas e não agrupadas ou diagramas inline simples de artigos que não se beneficiam de um zoom ou interação estilo carrossel.
• Visualizações de Painéis com Muitos Dados: Quando a tarefa principal é classificar ou analisar pontos de dados estruturados (por exemplo, tabelas ou gráficos) onde uma sobreposição em tela cheia interromperia o espaço de trabalho. Use data-table-ui-system.
• Documentos Complexos ou PDFs: Onde os usuários precisam ler documentos de texto com várias páginas; lightboxes são otimizados para mídia visual, não para ativos de leitura intensiva.
• Modais Contextuais Independentes: Quando o diálogo contém entradas de formulário, configurações ou aplicações interativas ricas, em vez de mídia estruturada. Use overlay-and-dialog-system ou settings-interface-system.

Entradas

1. Inventário de Mídia: Ativos de origem de alta resolução e variantes de miniaturas correspondentes de baixa resolução ou compactadas.
2. Metadados Contextuais: Títulos, descrições, informações de direitos autorais, legendas e texto alternativo (alt) de acessibilidade necessário.
3. Regras de Espaçamento Responsivo: Metas de gutters da grade, margens e regras de layout de colunas com base no responsive-grid-system e fluid-spacing-system estabelecidos do site.
4. Paleta de Contraste Interativa: Especificações de cores de texto e ícones acessíveis (atendendo ao contraste mínimo WCAG 4.5:1) para sobreposições de controle, botões de fechar e pontos de paginação.

Saídas

1. Especificação da Grade da Galeria: Layouts de colunas definidos, proporções de imagem, estados de hover e regras de preservação de ponto focal.
2. Blueprint da Anatomia do Lightbox: Estrutura da sobreposição em tela cheia, detalhando controles (Anterior, Próximo, Fechar), posições de legenda e layouts de tira de miniaturas.
3. Especificação de Gestos e Teclado: Uma matriz de interação completa mapeando eventos de teclado, zonas de toque e comportamentos de arrastar/deslizar.
4. Mapa de Marcos de Acessibilidade: Funções lógicas (dialog, group), rótulos (aria-label), regras de armadilha de foco e anúncios de estado em tempo real.

Fluxo de Trabalho

1. Construa a Fundação da Grade da Galeria

Comece estruturando a galeria principal da página para equilibrar a varredura e o espaço da tela:

• Padronização de Proporção de Aspecto: Agrupe as miniaturas da galeria usando uma proporção de aspecto uniforme (por exemplo, 1:1 quadrada ou 4:3 padrão) para estabelecer um ritmo ordenado. Use a propriedade CSS aspect-ratio para evitar saltos de layout.
• Lacunas e Gutters: Use tokens de fluid-spacing-system (tipicamente --space-s ou --space-m) para lacunas da grade.
• Indicações de Hover/Foco: Aplique as convenções de interactive-state-system. Quando um usuário passa o mouse ou foca em uma miniatura, acione uma mudança visual sutil (por exemplo, escala de zoom, sobreposição de contraste suave, cursor personalizado de pesquisa/zoom) para sinalizar que o item é clicável.
• HTML Semântico: Estruture a galeria usando um wrapper de lista (<ul> / <li>) com miniaturas marcadas como elementos button (ou links, se indexação/deep-linking for necessária) para garantir acessibilidade pelo teclado.

2. Projete o Fundo do Lightbox em Tela Cheia

O fundo do lightbox deve separar o visualizador do resto da página:

• Camada de Scrim: Sobreponha um fundo sólido ou levemente translúcido (por exemplo, #0a0a0a com 95% de opacidade ou um desfoque de fundo escuro) para eliminar distrações periféricas.
• Preservação de Proporção de Aspecto: Posicione a imagem ativa no centro absoluto da viewport. Certifique-se de que o contêiner escale dinamicamente com max-width: 90vw e max-height: 80vh para caber em qualquer viewport sem cortar ou distorcer a proporção de aspecto da origem.
• Estado de Carregamento: Construa um indicador visual centralizado (spinner, esqueleto de carregamento ou anel de progresso) que seja ciente de aria (aria-busy="true"), garantindo que os usuários saibam que os ativos de alta resolução estão sendo baixados.

3. Estabeleça Controles de Navegação e Sobreposição de Legendas

Posicione e estilize os elementos de sobreposição para otimizar a ergonomia em desktop e dispositivos móveis:

• Alvo de Fechar: Posicione o botão Fechar no canto superior direito. Ele deve ter um limite visual claro, atender a um tamanho mínimo de alvo de toque de 48x48px (ou 44x44px conforme WCAG) e manter um anel de foco de teclado claro.
• Setas Anterior e Próximo: Centralize as setas de navegação verticalmente nas margens esquerda e direita. Em dispositivos móveis, esconda essas setas ou recue-as ligeiramente para manter o foco totalmente nas ações de deslizar.
• Legendas e Indicador de Índice: Coloque legendas e índices semânticos (por exemplo, "Imagem 3 de 12") na parte inferior do contêiner. Use um contêiner aria-live para notificar leitores de tela sobre eventos de mudança quando o índice for atualizado.
• Tira de Miniaturas: Abaixo da imagem principal, exiba uma linha rolável de pequenas miniaturas. Destaque o item ativo com uma borda grossa e de alto contraste e um contorno :focus distinto.

4. Conecte os Mecanismos de Teclado e Gestos

O lightbox deve lidar com a interação periférica de desktop e gestos móveis com igual elegância:

• Mapeamentos de Teclado: Garanta suporte imediato para controles de tecla: Escape fecha o lightbox, ArrowRight/ArrowDown aciona "Próximo", e ArrowLeft/ArrowUp aciona "Anterior".
• Armadilha de Foco: Quando o lightbox abre, prenda o foco do teclado dentro dele. Os usuários não devem poder tabular de volta para a página de fundo. O primeiro elemento focado deve ser o contêiner principal do diálogo ou o botão Fechar.
• Restauração de Foco: Quando o lightbox fecha, restaure imediatamente o foco para o botão de miniatura específico que o acionou.
• Deslizar para Navegar: Suporte gestos suaves de deslizar para a esquerda e para a direita em telas sensíveis ao toque.
• Deslizar para Dispensar: Permita arrastar ou deslizar verticalmente (para cima ou para baixo) para dispensar rapidamente o lightbox, replicando padrões nativos de sistemas operacionais móveis.

5. Finalize a Acessibilidade e os Esboços do Documento

Aplique declarações ARIA avançadas para garantir uma experiência de leitor de tela compatível com WCAG AA:

• Funções e Rótulos: Marque o wrapper do lightbox com role="dialog", aria-modal="true", e rotule-o usando aria-label ou aria-labelledby referenciando o título/legenda.
• Oclusão de Fundo: Quando o lightbox estiver ativo, aplique aria-hidden="true" ao wrapper principal da página (<main> ou #app-root) para manter as varreduras do leitor de tela isoladas dentro da sobreposição.
• Atualizações em Tempo Real: Garanta que as alterações no título/legenda da imagem sejam anunciadas colocando-as dentro ou referenciando-as por meio de uma zona aria-live="polite".

Regras de Decisão

• A Divisão de Resolução: As miniaturas na grade da galeria devem ser fortemente compactadas e dimensionadas adequadamente (por exemplo, largura máxima de 600px). O lightbox deve carregar a variante master de alta resolução, mas apenas sob demanda (carregamento lento dos slides anterior e próximo) para economizar largura de banda móvel.
• Priorização de Teclado vs. Toque: Em viewports móveis (larguras < 768px), priorize o espaço da tela para a imagem. Esconda os controles de UI do desktop (setas Anterior/Próximo) em favor de gestos de deslizar, mas sempre mantenha um botão "Fechar" altamente visível.
• Loop Infinito vs. Parada Forçada:
  • Use Loop Infinito (carrossel volta ao 1 após o último item) ao exibir portfólios criativos, depoimentos ou produtos onde a varredura fluida é preferida.
  • Use Parada Forçada (seta Próximo desabilitada no último item) para tutoriais sequenciais passo a passo, conjuntos de instruções ou linhas do tempo cronológicas onde a direcionalidade é crítica.
• Legendas vs. Espaço de Sobreposição: Se uma imagem tiver uma descrição longa, não a sobreponha sobre a própria imagem. Coloque-a em uma barra inferior dedicada abaixo dos limites da imagem, permitindo que o texto role independentemente se transbordar o espaço vertical da tela.
• Indicação de Cursor no Desktop: Mude o cursor do desktop dinamicamente:
  • Passando o mouse sobre miniaturas da galeria: cursor: zoom-in
  • Imagem ativa do lightbox (com zoom): cursor: zoom-in (clicar expande para resolução total, mudando o cursor para cursor: zoom-out para pan).
  • Passando o mouse sobre o fundo do lightbox: cursor: pointer (clicar fecha a sobreposição).

Restrições

• Responsividade: As imagens nunca devem distorcer ou perder sua proporção de aspecto dentro do lightbox. Os contêineres devem usar unidades de viewport flexíveis (vw/vh) e CSS object-fit: contain para permanecer estritamente dentro dos limites da tela em todas as orientações do dispositivo.
• Taxas de Contraste: Os controles interativos Fechar, Navegação e Miniatura devem atender a uma taxa de contraste de pelo menos 4.5:1 contra o fundo e as sobreposições de imagem.
• Estados de Foco: Cada elemento de navegação ativo deve ter um anel :focus-visible visível. Os indicadores de foco nunca devem ser cortados por caixas delimitadoras ou elementos adjacentes.
• Alvos de Toque: Os alvos de toque em dispositivos móveis devem atender ao WCAG 2.2 SC 2.5.8 (pelo menos 24x24px, mas 44x44px é fortemente preferido para ações primárias como Fechar e Navegação).

Padrões Comuns de Falha

• A "Armadilha de Tabulação Infinita": Sair tabulando do lightbox aberto para a página de fundo, o que faz com que leitores de tela leiam conteúdo invisível e quebra a navegação pelo teclado.
• A "Ultrapassagem de Imagem": Imagens retratro alto se expandindo além da parte superior ou inferior da viewport móvel, tornando as setas de navegação ou botões de fechar completamente inalcançáveis.
• Perda de Ponto Focal: Miniaturas na galeria estática cortando o assunto principal (por exemplo, a cabeça de uma pessoa) devido ao corte centralizado absoluto. Resolva usando object-position ou corte responsivo personalizado.
• A "Saída Morta": Esquecer de conectar a tecla Escape, deixando usuários somente de teclado presos dentro da sobreposição modal sem uma maneira intuitiva de fechá-la.
• Mudança de Layout ao Abrir: A barra de rolagem do navegador desaparecendo quando o lightbox abre, fazendo com que toda a página de fundo trema ou mude lateralmente. Resolva adicionando uma gutter correspondente ou padding de bloqueio de rolagem.
• Nenhuma Restauração de Foco: Fechar o lightbox redefine o foco para o topo do sitemap ou para o body, forçando usuários de teclado a tabular por toda a navegação do cabeçalho novamente para retornar aonde estavam.

Critérios de Validação

• As miniaturas da galeria usam uma proporção de aspecto padronizada e têm indicadores claros de hover/foco.
• As imagens ativas do lightbox mantêm suas proporções de aspecto e cabem perfeitamente dentro dos limites da viewport (max-width: 90vw e max-height: 80vh).
• O botão Fechar e as setas atendem a uma taxa de contraste mínima de 4.5:1 contra a camada de fundo.
• A navegação pelo teclado está ativa: Escape fecha, ArrowRight avança, ArrowLeft retrocede.
• O foco é preso dentro do lightbox quando aberto e restaura perfeitamente para o elemento da galeria de origem ao fechar.
• Gestos de toque estão habilitados: deslizar para a esquerda/direita para navegar, deslizar para cima/baixo para dispensar em viewports móveis.
• O wrapper principal da página é marcado como aria-hidden="true" quando o modal do lightbox está ativo.
• O spinner de estado de carregamento está visível e marcado como aria-busy="true" quando os ativos de alta resolução estão carregando.