coastdigitalgroup/coastai-skills

Sistema de UI para Tabelas de Dados

Propósito

O skill Sistema de UI para Tabelas de Dados fornece uma metodologia para organizar e apresentar dados estruturados e multi-atributo. Ele garante que grandes conjuntos de dados sejam fáceis de escanear, comparar e manipular, estabelecendo regras claras para alinhamento, espaçamento, hierarquia e elementos interativos dentro de um formato tabular.

Casos de Uso

• Projetar painéis SaaS para inventário, gerenciamento de usuários ou faturamento.
• Criar matrizes de comparação de produtos para sites de e-commerce ou marketing.
• Implementar visualizadores de logs ou trilhas de auditoria para aplicações técnicas.
• Organizar dados financeiros ou métricas de desempenho em uma visualização estruturada.
• Estabelecer um padrão de biblioteca de componentes para "Tabelas de Dados" ou "Grades de Dados".

Quando NÃO Usar

• Pares Simples Chave/Valor: Se você tem apenas duas colunas (ex.: Rótulo: Valor), use uma Lista de Descrição (<dl>) ou uma lista simples.
• Conteúdo Narrativo: Texto longo ou histórias devem usar tipografia padrão e estruturas de seção, não tabelas.
• Grades de Layout: Use sistema-de-grade-responsiva para layout de página; tabelas são estritamente para dados.
• Cartões com Poucos Dados: Se os dados são altamente visuais e têm poucos atributos, use sistema-de-ui-de-cartoes para melhor engajamento.

Entradas

1. Esquema de Dados: Os tipos de dados a serem exibidos (strings, números, datas, booleanos, ações).
2. Prioridade de Coluna: Quais atributos são essenciais para identificação vs. detalhes secundários.
3. Tarefas do Usuário: O usuário precisa encontrar uma linha específica, comparar valores entre linhas ou realizar ações em massa?
4. Expectativas de Volume: Quantas linhas e colunas são esperadas em uma visualização típica?

Saídas

1. Especificação da Anatomia da Tabela: Regiões definidas (Cabeçalho, Linha, Célula, Rodapé) e seus espaçamentos internos.
2. Matriz de Alinhamento: Regras para alinhamento horizontal baseado no tipo de dado.
3. Variantes de Densidade: Definições para alturas de linha Compacta, Padrão e Confortável.
4. Mapa de Interação: Comportamento para classificação, filtragem, seleção de linhas e ações inline.

Fluxo de Trabalho

1. Definir Tipos de Coluna e Alinhamento

Aplique a "Regra de Ouro de Alinhamento" para garantir escaneabilidade:

• Texto/Padrão: Alinhado à esquerda (ajuda o olho a seguir o início da palavra).
• Números/Métricas: Alinhados à direita (alinha pontos decimais e permite comparação rápida de magnitude).
• Datas/Rótulos de Status: Centralizados ou Alinhados à esquerda (dependendo da largura da coluna).
• Ações: Alinhadas à direita (geralmente a coluna final).

2. Estabelecer Hierarquia Visual (O Cabeçalho)

O cabeçalho da tabela deve se distinguir claramente dos dados:

• Estilo: Use uma cor de fundo diferente, peso negrito ou tratamento em maiúsculas para elementos <th>.
• Persistência: Para tabelas longas, use um cabeçalho fixo para que os usuários não percam o contexto ao rolar.

3. Definir Densidade e Ritmo da Linha

Escolha um nível de densidade baseado no caso de uso:

• Compacta: Alta densidade de dados (ex.: altura de 32px). Melhor para usuários avançados e painéis.
• Padrão: Equilibrada (ex.: altura de 48px). Melhor para uso geral.
• Confortável: Baixa densidade (ex.: altura de 64px). Melhor para marketing ou listas simples. Use listras zebradas ou bordas sutis para separar linhas e reduzir "pulos de linha".

4. Projetar para Dados Interativos

Defina como os usuários manipulam os dados:

• Classificação: Adicione indicadores (chevrons) nos cabeçalhos que suportam classificação.
• Estados da Linha: Defina estados de Hover, Selecionado e Foco para as linhas.
• Ações em Massa: Se necessário, adicione uma coluna de caixa de seleção na extrema esquerda.

5. Planejar para Variação de Conteúdo

Lide com casos de borda no comprimento dos dados:

• Truncamento: Use reticências para texto longo que não é crítico para identificação.
• Quebra de Linha: Permita quebra de linha para texto descritivo importante.
• Larguras Fixas: Atribua larguras fixas a colunas estáveis (ex.: Status, Data) e larguras fluidas a identificadores primários (ex.: Nome).

Regras de Decisão

• A Regra da Escaneabilidade: A primeira coluna deve sempre ser o identificador mais importante (ex.: Nome, ID) para servir como âncora da linha.
• Alinhamento de Números: Se comparar valores é a tarefa principal, use fontes monoespaçadas para números para manter os dígitos perfeitamente alinhados.
• Listras Zebradas vs. Bordas: Use listras zebradas para tabelas muito largas para ajudar o olho a rastrear horizontalmente; use bordas para tabelas mais curtas e simples.
• Posicionamento de Ações: Agrupe ações na coluna final ou use um menu "Mais" visível para manter a interface limpa.
• Células Vazias: Nunca deixe uma célula em branco. Use um traço (—) ou "N/A" para confirmar que os dados estão faltando, e não apenas um erro de carregamento.

Restrições

• Acessibilidade: Deve usar tags semânticas <table>. Os cabeçalhos devem ter scope="col". Legendas devem ser usadas para contexto. Cabeçalhos fixos não devem obscurecer o indicador de foco de células ou ações de linha roladas abaixo deles (WCAG 2.2 SC 2.4.11). Botões/links de ação inline devem atender ao tamanho mínimo de 24x24px (SC 2.5.8).
• Responsividade: As tabelas devem seguir padrões de tabelas-de-dados-responsivas (Rolar, Empilhar ou Alternar) quando as viewports diminuírem.
• Contraste: O texto do cabeçalho e os indicadores de status devem atender ao WCAG AA (4.5:1).

Padrões Comuns de Falha

• Números Desalinhados: Alinhar números à esquerda torna impossível comparar magnitudes rapidamente.
• O "Muro de Texto": Usar linhas de alta densidade sem listras zebradas ou distinção clara do cabeçalho, causando "fadiga ocular".
• Cabeçalhos Invisíveis: Cabeçalhos que se parecem muito com os dados, dificultando saber o que as colunas representam.
• Falta de Intuitividade em Ações: Botões ou links dentro de células que são pequenos demais para tocar ou não parecem interativos.
• Nenhum Estado Vazio: Mostrar uma tabela em branco sem uma mensagem "Nenhum resultado encontrado".

Critérios de Validação

• O alinhamento das colunas segue as regras de tipo de dado (Texto=Esquerda, Números=Direita).
• Os cabeçalhos da tabela são visualmente distintos dos dados das linhas.
• O identificador primário está ancorado na primeira coluna.
• HTML semântico (<table>, <th>, scope) é usado para a estrutura.
• Células vazias usam um placeholder (ex.: —) em vez de ficarem em branco.
• Estados interativos (Hover/Selecionado) estão claramente definidos.
• O design lida com conteúdo longo de maneira graciosa (truncamento ou quebra de linha).
• Cabeçalhos fixos nunca obscurecem indicadores de foco em linhas ou ações de célula (WCAG 2.2 SC 2.4.11).
• Ações de linha atendem ao tamanho mínimo de 24x24px (WCAG 2.2 SC 2.5.8).