coastdigitalgroup/coastai-skills

Sistema de Grade Masonry

Propósito

O Sistema de Grade Masonry fornece um framework de design padronizado e responsivo para exibir cartões de conteúdo não uniformes e de altura variável (como portfólios de fotografia, feeds de conteúdo gerado por usuário, cartões de mídia mista ou quadros editoriais de descoberta visual). Layouts padrão de CSS Grid forçam o alinhamento da altura das linhas, criando lacunas verticais desajeitadas quando os itens têm proporções de aspecto ou comprimentos de texto variados.

Projetar uma grade masonry eficaz requer resolver o desafio espacial de empacotar itens dinamicamente em colunas verticais paralelas, evitar Mudança de Layout Acumulativa (CLS) conforme os ativos de mídia carregam, garantir a degradação graciosa de colunas em dispositivos móveis e — criticamente — evitar que o layout visual quebre a ordem lógica de leitura do DOM e a sequência de navegação por foco do teclado (WCAG 2.1 SC 1.3.2 e SC 2.1.1).

Casos de Uso

• Portfólios de Fotografia e Mídia Visual: Exibir galerias de imagens com proporções de aspecto nativas variadas (retrato, paisagem, quadrado, panorama) em uma grade compacta e sem lacunas.
• Feeds de Atividade Social e UGC: Organizar cartões sociais mistos contendo atualizações curtas de texto, artigos completos, imagens incorporadas e teasers de vídeo.
• Paredes de Reviews UGC e E-Commerce: Apresentar fotos de reviews de clientes, posts do Instagram marcados e snippets de destaque de produto em um showcase dinâmico de descoberta.
• Quadros Editoriais de Descoberta e Pinboards: Construir moodboards, gerenciadores de favoritos e feeds de inspiração onde os cartões contêm elementos de conteúdo diversos com pegadas verticais variáveis.

Quando NÃO Usar

• Grades de Proporção de Aspecto Uniforme: Se todos os itens compartilham proporções de aspecto idênticas (por exemplo, cartões de vídeo padrão 16:9 ou catálogos de produto 1:1), use responsive-grid-system ou card-ui-system.
• Destaques Assimétricos 2D Estruturados: Para seções de herói curadas com regras explícitas de extensão retangular 2D (por exemplo, um recurso principal 2x2 junto com blocos de estatística 1x1), use bento-grid-layout-system.
• Dados Tabulares ou Alinhados Estritos: Quando os usuários precisam comparar valores entre linhas horizontais (por exemplo, tabelas de preços ou métricas financeiras), use data-table-ui-system ou comparison-matrix-system.
• Narrativa Sequencial e Artigos: Para narrativas lineares onde a ordem de leitura deve seguir estritamente um único fluxo vertical, use article-layout-system ou section-composition-system.

Entradas

1. Inventário de Conteúdo e Proporções de Aspecto: Tipos de mídia e conteúdo de texto (imagens, vídeos, snippets de texto, cartões de ação) e seu espectro de proporção de aspecto (de retrato 3:4 a paisagem 16:9).
2. Requisitos de Arquitetura de Coluna: Contagens de coluna alvo em diferentes tamanhos de tela (por exemplo, 4 colunas em desktop widescreen, 3 em desktop, 2 em tablet, 1 em mobile).
3. Requisitos de Interatividade e Foco: Elementos interativos dentro dos cartões (botões, lightboxes, toggles inline, links) que exigem acessibilidade por teclado.
4. Tokens Espaciais e de Tema: Gutters de coluna fluidos e lacunas entre linhas (gap: clamp(12px, 2vw, 24px)), preenchimentos de fundo do cartão, border-radii e tokens de anel de foco (de fluid-spacing-system e focus-indicator-design-system).

Saídas

1. Especificação da Arquitetura de Layout Masonry: Escolha estratégica e blueprint técnico entre fluxo CSS Multi-Column puro, extensão de linhas CSS Grid (grid-auto-rows) e empacotamento de coluna mais curta via JavaScript.
2. Matriz de Escalonamento Responsivo de Colunas: Definição de breakpoint para transições suaves de contagem de coluna e escalonamento de lacunas.
3. Mapa de Ordem de Leitura do DOM e Foco do Teclado: Arquitetura que garante que a navegação por teclado (Tab / Shift+Tab) siga a ordem visual natural de leitura, sem saltos caóticos entre colunas.
4. Regras de Estabilidade de Layout e Preservação de Proporção de Aspecto: Arquitetura CSS que previne Mudança de Layout Acumulativa (CLS) durante o carregamento de imagens e mídia.

---

Workflow

1. Selecionar a Estratégia Arquitetural

Escolha a técnica de layout apropriada com base na interatividade e nos requisitos de ordem de leitura:

• Opção A: Layout CSS Multi-Column puro (column-count)
  • Melhor para: Galerias estáticas, feeds com muitas imagens ou cartões não interativos onde a ordem de fluxo pode ir verticalmente pela coluna 1, depois coluna 2, etc.
  • Implementação: column-count: 4; column-gap: var(--space-m);. Defina break-inside: avoid; margin-bottom: var(--space-m); nos cartões filhos.
  • Trade-off: A ordenação vertical da fonte (de cima para baixo dentro das colunas) pode confundir usuários de teclado se os cartões contiverem controles interativos.
• Opção B: CSS Grid com Extensão de Linhas (grid-auto-rows & grid-row: span X)
  • Melhor para: Grades semiestáticas onde os passos de altura do cartão podem ser quantizados em unidades de linha de trilha fixa (por exemplo, trilhas base de 10px).
  • Implementação: display: grid; grid-template-columns: repeat(auto-fill, minmax(280px, 1fr)); grid-auto-rows: 10px; gap: 16px;. JavaScript calcula a altura do conteúdo e aplica grid-row: span Math.ceil(height / trackHeight).
  • Trade-off: A ordem horizontal nativa do DOM é preservada, mas requer cálculos menores de altura em JS ou container queries.
• Opção C: Distribuição por Container da Coluna Mais Curta via JavaScript
  • Melhor para: Feeds de mídia mista altamente interativos onde a ordem de leitura da esquerda para a direita é primordial e os cartões contêm links, botões e controles de formulário.
  • Implementação: Crie $N$ containers flex de coluna (display: flex; flex-direction: column; gap: var(--space-m);). Anexe cartões recebidos à coluna que atualmente tem a altura total renderizada mais curta.
  • Trade-off: Requer gerenciamento de containers DOM no lado do cliente, mas garante fluxo de foco DOM perfeito da esquerda para a direita e zero lacunas visuais verticais.

2. Definir Ritmo Espacial e Gutters de Coluna

Estabeleça tokens de espaçamento consistentes em todas as colunas e no preenchimento interno dos cartões:

• Gutters de Coluna: Use espaçamento de lacuna fluido (por exemplo, gap: clamp(16px, 2.5vw, 28px)). Garanta que as lacunas verticais entre cartões empilhados sejam iguais às lacunas horizontais entre colunas para manter densidade espacial uniforme.
• Preenchimento e Alinhamento Interno do Cartão: Padronize o preenchimento interno do cartão usando tokens fluidos (padding: var(--space-m)). Para cartões apenas de mídia (por exemplo, gatilhos de lightbox), permita que as imagens sangrem de borda a borda (padding: 0; overflow: hidden;).
• Sincronização de Raio de Canto: Aplique border-radius consistente nos containers externos do cartão (por exemplo, 12px a 16px). Garanta que os elementos internos (por exemplo, imagens no topo) herdem raios de canto concêntricos (border-top-left-radius: calc(var(--card-radius) - 1px)).

3. Prevenir Mudança de Layout (CLS) e Distorções de Imagem

Grades masonry são altamente suscetíveis a Mudança de Layout Acumulativa durante o carregamento de imagens:

• Caixas de Proporção de Aspecto: Declare explicitamente aspect-ratio nos containers de imagem (aspect-ratio: 4 / 5; object-fit: cover; width: 100%; display: block;) ou calcule proporções de preenchimento inline antes que a mídia seja resolvida.
• Placeholders Esqueleto: Renderize pulsos de fundo de esqueleto estilizados (background: var(--surface-subtle); animation: pulse 1.5s infinite;) correspondendo à proporção de aspecto esperada do cartão enquanto os ativos remotos carregam.
• Listeners de Carregamento de Imagem: Se usar cálculos de altura em JS, vincule ResizeObserver ou listeners de evento load de imagem para recalcular as alocações de altura das colunas assim que as imagens terminarem de renderizar.

4. Reconciliar Ordem de Leitura do DOM e Gerenciamento de Foco

Garanta conformidade com WCAG 1.3.2 (Sequência Significativa) e 2.1.1 (Teclado):

• Evite Desconexões Visual-DOM: Se usar CSS Columns onde o layout visual flui verticalmente pelas colunas, garanta que os indicadores de foco do teclado permaneçam distintos e lógicos. Se os cartões contiverem controles interativos, prefira distribuição por Coluna Mais Curta via JavaScript ou extensão de linhas CSS Grid para manter uma sequência natural de tabulação da esquerda para a direita, de cima para baixo (ordem da tecla Tab).
• Visibilidade do Indicador de Foco: Padronize indicadores de foco de alto contraste e não cortados (outline: 3px solid var(--focus-ring-color); outline-offset: 3px;). Evite overflow: hidden em cartões sem adicionar preenchimento suficiente para o indicador de foco dentro dos limites de recorte.
• Atalhos de Teclado para Lightboxes / Modais: Se clicar em um cartão masonry abrir uma sobreposição modal ou lightbox, prenda o foco do teclado dentro da sobreposição (focus-trap) e retorne o foco para o gatilho do cartão de origem ao dispensar (tecla Escape).

5. Implementar Escalonamento Responsivo de Colunas

Projete breakpoints para escalar graciosamente as contagens de coluna sem quebrar o equilíbrio do conteúdo:

• Desktop Widescreen (≥ 1440px): 4 Colunas (column-count: 4 ou 4 trilhas de coluna flex).
• Desktop Padrão (1024px – 1439px): 3 Colunas (column-count: 3 ou 3 trilhas de coluna flex).
• Tablet / Tela Pequena (640px – 1023px): 2 Colunas (column-count: 2 ou 2 trilhas de coluna flex).
• Mobile (< 640px): 1 Coluna (column-count: 1 ou pilha vertical única). Todos os itens empilham naturalmente com espaçamento vertical padrão.

---

Regras de Decisão

Matriz de Seleção Arquitetural

Tipo de Conteúdo e Interação	Estratégia Arquitetural Recomendada	Justificativa
Galeria de Imagens Puras (Gatilhos de Lightbox)	CSS Multi-Column (column-count)	Zero pegada JS, desempenho nativo de multi-coluna do navegador, masonry de imagem vertical limpa.
Cartões Interativos (Botões, Inputs, Links)	Distribuição Flex por Coluna Mais Curta via JS	Preserva ordem estrita de tabulação DOM da esquerda para a direita, prevenindo saltos de foco no leitor de tela e teclado.
Feed de Carregamento Dinâmico (Scroll Infinito)	Extensão de Linhas CSS Grid ou Distribuição via JS	Permite anexar novos cartões suavemente à coluna mais curta sem reformatar todo o layout da página.
Painel Editorial com Muito Texto	Extensão de Linhas CSS Grid (grid-auto-rows: 10px)	Mantém a ordem de leitura horizontal enquanto acomoda comprimentos de texto variáveis com precisão.

---

Restrições

• Acessibilidade (Conformidade WCAG 2.1 AA):
  • SC 1.3.2 Sequência Significativa: O arranjo visual dos cartões interativos deve estar alinhado logicamente com a ordem de navegação por tabulação do teclado (fluxo de foco tabindex="0").
  • SC 1.4.3 Contraste (Mínimo): Texto renderizado sobre superfícies de cartão ou sobreposições de imagem deve satisfazer uma taxa de contraste mínima de 4.5:1. Sobreposições de escuridão (background: linear-gradient(to top, rgba(0,0,0,0.8), transparent)) devem ser usadas para texto colocado diretamente sobre imagens.
  • SC 2.1.1 Teclado: Todos os elementos interativos do cartão (como botões, gatilhos de favoritos, links externos) devem ser totalmente operáveis via teclas Espaço e Enter.
  • SC 2.4.7 Foco Visível: Cartões e gatilhos interativos devem exibir um anel de foco distinto que não seja cortado por propriedades overflow: hidden do cartão pai.
  • SC 2.5.8 Tamanho do Alvo: Todos os alvos de toque dentro dos cartões masonry devem manter uma área interativa mínima de 24x24px (mínimo de 44x44px em viewports de toque/mobile).
• Desempenho de Mudança de Layout: Imagens dentro de cartões masonry devem ter proporções de aspecto intrínsecas explicitamente definidas ou reservas de dimensão para garantir que CLS permaneça abaixo de 0,1.

---

Padrões Comuns de Falha

• A Bagunça da Tabulação do Teclado: Usar CSS column-count para cartões interativos, fazendo com que a tecla Tab do teclado se mova verticalmente por toda a primeira coluna (do item 1 ao item 10) antes de pular de volta para o topo da coluna 2.
• Caos da Mudança de Layout Acumulativa (CLS): Inserir imagens sem estilo de proporção de aspecto ou esqueletos de carregamento, fazendo com que as colunas masonry reformatem e pulem repetidamente conforme cada imagem carrega.
• Anéis de Foco Cortados: Definir overflow: hidden em cartões masonry para forçar cantos de imagem arredondados, o que corta o anel de foco de contorno padrão de elementos interativos internos.
• Alturas de Coluna Não Restritas em Mobile: Falhar em colapsar grades masonry para uma única coluna em dispositivos móveis, resultando em cartões multi-coluna ultra-estreitos e comprimidos com quebra de texto ilegível.
• Contagens de Coluna Desiguais: Anexar novos itens em feeds dinâmicos sequencialmente pelas colunas (1, 2, 3, 1, 2, 3) em vez de verificar as alturas das colunas, criando enormes espaços em branco verticais na parte inferior das colunas mais curtas.

---

Critérios de Validação

• Alinhamento da Arquitetura: A estratégia selecionada (CSS Columns vs. CSS Grid Row-Span vs. JS Shortest-Column) corresponde aos requisitos de interatividade do cartão.
• Zero Lacunas Verticais Indesejadas: Os cartões se empacotam firmemente sem lacunas de espaço em branco de alinhamento horizontal.
• Navegação por Tabulação do Teclado: Cartões interativos seguem uma sequência visual lógica de tabulação (da esquerda para a direita, de cima para baixo).
• Prevenção de Mudança de Layout: Proporções de aspecto ou containers esqueleto previnem CLS (<0,1) conforme a mídia remota carrega.
• Adaptação de Breakpoint Responsivo: A grade escala suavemente de 4 colunas em widescreen para 1 coluna vertical única em mobile (<640px).
• Conformidade WCAG AA: Todo texto atende a contraste ≥4,5:1, alvos de toque atendem a ≥24x24px (≥44x44px em mobile), e anéis de foco são não cortados e claramente visíveis.