Sistema de UI para Blocos de Código
Propósito
O Sistema de UI para Blocos de Código fornece um framework de layout padronizado, acessível e de alta legibilidade para exibir snippets de código-fonte, cargas úteis de requisição/resposta de API, exemplos de código multifile, linhas de comando do terminal e comparações de diff de código. Blocos de código são componentes críticos de interação em documentação técnica, sites de marketing de ferramentas de desenvolvedor, portais de API, blogs de engenharia e plataformas SaaS.
Projetar interfaces de código eficazes requer equilibrar legibilidade da tipografia monoespaçada, destaque de tokens de sintaxe com alto contraste em temas claro e escuro, barras de ferramentas de ação fixas no topo (insígnias de linguagem, navegação por abas de arquivos, gatilhos de copiar para área de transferência), numeração de linhas, destaque/foco em nível de linha, comportamentos de quebra vs. rolagem horizontal e experiências acessíveis para leitores de tela. Esta habilidade estabelece regras espaciais, padrões de cores de tokens, mecânicas de interação e diretrizes de conformidade WCAG AA para apresentação de UI de código.
Casos de Uso
- Documentação de Desenvolvedor e Portais de Referência de API: Apresentar exemplos de SDK multilíngues (por exemplo, cURL, Node.js, Python, Go, Rust) e respostas de API.
- Landing Pages de Ferramentas de Desenvolvedor: Exibir snippets de código principais, comandos de instalação via CLI e blocos de demonstração interativa do produto.
- Blogs de Engenharia e Tutoriais: Renderizar exemplos de código inline e em bloco com chamadas de linhas específicas, destaques de código passo a passo e anotações inline.
- Interface de Revisão de Código e Controle de Versão: Exibir diffs de código (adições
+, deleções-), comentários inline e snippets de commit. - Ferramentas de Compartilhamento de Snippets e Playground de Código: Estruturar editores de arquivo com múltiplas abas, painéis de visualização e cartões de snippet incorporáveis.
Quando NÃO Usar
- Editores de Código Completos no Navegador (IDE): Para IDEs web interativas complexas que exigem renderização em canvas, árvores AST virtualizadas, edição com múltiplos cursores e integrações com Language Server Protocol (LSP) (por exemplo, Monaco Editor, CodeMirror), use implementações de editores dedicadas.
- Campos de Texto de Formulário Genéricos: Para campos de texto simples de múltiplas linhas sem destaque de sintaxe ou números de linha, use
form-design-system. - Insígnias de Código Inline: Para referências de código curtas e de uma única palavra dentro de parágrafos em prosa (por exemplo,
npm install), use a estilização inline<code>dentro dearticle-layout-system. - Tabelas de Dados Estruturados: Para dados tabulares de chave-valor ou consultas de banco de dados formatadas como linhas e colunas, use
data-table-ui-systemouproperty-and-attribute-system.
Entradas
- Conteúdo de Código e Tipos de Sintaxe: A taxonomia de linguagem (por exemplo, TypeScript, JSON, Bash, YAML, GraphQL, SQL) e características estruturais (arquivo único, abas multifile, diff).
- Contexto do Tema: Tokens da paleta de cores ativos para fundos de superfície, bordas e tokens de sintaxe no modo claro e modo escuro (de
accessible-color-systemedark-theme-design-system). - Tokens de Tipografia Monoespaçada: Pilha de fontes preferida (por exemplo,
ui-monospace, SFMono-Regular, Menlo, Monaco, Consolas, "Liberation Mono", "Courier New", monospace), tamanhos de fonte e alturas de linha (defluid-typography-system). - Gatilhos de Ação: Capacidades interativas específicas necessárias por bloco (por exemplo, botão Copiar com 1 clique, alternância de números de linha, alternância de quebra de linha, expansão para tela cheia, link externo para sandbox).
Saídas
- Especificação do Contêiner de Código e Barra de Ferramentas do Cabeçalho: Layouts espaciais para contêineres de bloco de código, barras de cabeçalho fixas, indicadores de linguagem, abas de caminho de arquivo e grupos de botões de ação.
- Paleta de Cores de Tokens de Sintaxe Acessível: Mapeamento de cores de tokens com contraste WCAG AA (mínimo 4,5:1) para palavras-chave, strings, funções, variáveis, comentários, operadores e tipos nos temas claro e escuro.
- Sistema de Hierarquia e Anotação em Nível de Linha: Projeto para numeração de linhas, destaque/sobreposição de foco de linha, indicadores de diff (
+/-) e vinculação de âncora em nível de linha. - Modelo Acessível de Leitor de Tela e Navegação por Teclado: Atributos de função ARIA, rotas de foco do teclado, mascaramento de números de linha (
aria-hidden="true") e anúncios de status de cópiaaria-live. - Estratégia de Estouro e Rolagem Responsiva: Regras para barras de rolagem horizontais, barras de ferramentas de ação fixas, alternâncias de quebra de palavra e adaptações para viewports móveis.
Fluxo de Trabalho
1. Estruturar o Invólucro do Bloco de Código e a Barra de Cabeçalho
Projete o contêiner e a barra de ação do cabeçalho como uma unidade coesa e unificada:
- Arquitetura do Contêiner: Defina um contêiner arredondado (
border-radius: 8px; border: 1px solid var(--border-subtle); overflow: hidden; background: var(--surface-code);). Use um fundo de superfície distinto (normalmente modo escuro por padrão ou correspondente ao tema da superfície). - Layout da Barra de Ferramentas do Cabeçalho: Renderize uma barra de cabeçalho fixa no topo (
display: flex; align-items: center; justify-content: space-between; padding: 8px 16px; background: var(--surface-code-header); border-bottom: 1px solid var(--border-subtle);). - Seção Esquerda do Cabeçalho (Abas e Metadados):
- Arquivo Único: Mostre o caminho/nome do arquivo (por exemplo,
src/auth/jwt.ts) com um ícone de tipo de arquivo sutil, ou uma insígnia de linguagem em maiúsculas (por exemplo,TYPESCRIPT). - Multifile / Multilíngue: Renderize botões em aba (
role="tablist"). A aba ativa deve ter texto de alto contraste e um indicador de borda inferior/pílula (border-bottom: 2px solid var(--brand-primary)).
- Arquivo Único: Mostre o caminho/nome do arquivo (por exemplo,
- Seção Direita do Cabeçalho (Ações): Agrupe gatilhos de ação de utilitário:
- Botão Copiar: Botão de ícone 32x32px (
aria-label="Copiar código para a área de transferência") com um ícone de cópia claro e rótulo em viewports mais largos. - Alternância Quebrar/Rolar (Opcional): Botão de ícone para alternar entre quebra suave (
white-space: pre-wrap) e rolagem horizontal (white-space: pre). - Link Expandir/Sandbox (Opcional): Gatilho para abrir snippet no StackBlitz, CodeSandbox ou em tela cheia.
- Botão Copiar: Botão de ícone 32x32px (
2. Estabelecer Tipografia Monoespaçada e Grade de Layout
Garanta legibilidade ideal para leitura técnica e varredura de código:
- Pilha de Fontes: Defina uma pilha de fontes monoespaçadas limpa e de alta legibilidade:
ui-monospace, SFMono-Regular, Menlo, Monaco, Consolas, "Liberation Mono", "Courier New", monospace. Garanta que as configurações de recursos de fonte permitam distinção clara entre0(zero) eO(o maiúsculo), e1(um),l(L minúsculo) eI(i maiúsculo). - Tamanho da Fonte e Altura da Linha: Defina
font-size: 0.875rem(14px) com uma altura de linha generosa (line-height: 1.6/ 22.4px). Evite alturas de linha apertadas que fazem com que colchetes e operadores de código colidam. - Contêiner do Corpo do Código: Use
<pre class="code-block"><code class="language-typescript">comdisplay: block; overflow-x: auto; padding: 16px 0; margin: 0; font-family: var(--font-mono);.
3. Projetar Números de Linha, Destaques de Linha e Diffs
Estruture elementos em nível de linha sem degradar o comportamento de copiar-colar ou o leitor de tela:
- Estrutura da Linha: Formate cada linha como um contêiner de bloco distinto (
display: table-row;oudisplay: flex; width: 100%;). - Números de Linha: Renderize os números de linha em uma calha esquerda (
display: table-cell; text-align: right; width: 40px; padding-right: 16px; user-select: none; color: var(--text-code-muted);).- Regra de Acessibilidade: Envolva os números de linha em
<span aria-hidden="true">ou use conteúdo de contador CSS (content: counter(line)) para que os números de linha não sejam copiados ao selecionar texto e não sejam lidos em voz alta pelos leitores de tela entre as instruções de código.
- Regra de Acessibilidade: Envolva os números de linha em
- Linhas Destacadas / Focadas: Para chamar a atenção para linhas-chave em um tutorial ou diff:
- Aplique um fundo de destaque de linha explícito (
background: var(--surface-code-highlight); border-left: 3px solid var(--brand-primary);). - Garanta que a sobreposição de destaque se estenda por toda a largura rolável do contêiner de código (
min-width: 100%).
- Aplique um fundo de destaque de linha explícito (
- Linhas de Visualização Diff (Adição
+/ Deleção-):- Linha Adicionada: Fundo verde sutil (
background: rgba(34, 197, 94, 0.15); border-left: 3px solid var(--color-success);). Mostre um símbolo+na calha envolto em<span class="sr-only">Adicionado:</span>para leitores de tela. - Linha Removida: Fundo vermelho sutil (
background: rgba(239, 68, 68, 0.15); border-left: 3px solid var(--color-danger);). Mostre um símbolo-na calha envolto em<span class="sr-only">Removido:</span>para leitores de tela.
- Linha Adicionada: Fundo verde sutil (
4. Criar Paleta de Cores de Tokens de Sintaxe Acessível
Os tokens de sintaxe devem satisfazer as taxas de contraste WCAG AA (mínimo 4,5:1) contra o fundo do bloco de código (var(--surface-code)):
- Texto Base / Variáveis: Luz neutra (por exemplo,
#E2E8F0sobre#0F172A; proporção ~12,5:1). - Palavras-chave (
const,import,return,async): Roxo/magenta vibrante (por exemplo,#C084FC; proporção ~7,2:1). - Funções e Métodos (
fetchData,useState): Azul/ciano brilhante (por exemplo,#38BDF8; proporção ~8,5:1). - Strings (
"https://api.example.com"): Verde/verde-esmeralda suave (por exemplo,#4ADE80; proporção ~9,1:1). - Números e Booleanos (
404,true): Laranja/âmbar quente (por exemplo,#FB923C; proporção ~7,8:1). - Comentários (
// Manipular resposta do token): Cinza frio suave com conformidade WCAG AA (por exemplo,#94A3B8; proporção ~5,1:1). Nunca use cinzas de baixo contraste (por exemplo, 2:1) para comentários. - Operadores e Pontuação (
=>,{,},;): Neutro médio (por exemplo,#CBD5E1; proporção ~10,2:1).
5. Criar Estados de Feedback de Copiar para a Área de Transferência e Ação
Fornecer feedback instantâneo para ações de cópia evita cliques duplicados e frustração do usuário:
- Estado Padrão: Exiba o botão de ícone com ícone de cópia (dois retângulos sobrepostos) e rótulo opcional ("Copiar").
- Estado Hover / Foco: Fundo de superfície elevado ou destaque de borda (
background: var(--surface-hover); outline: 2px solid var(--focus-ring)). - Estado Ativo / Sucesso: Ao clicar, mude o ícone para um ícone de visto, atualize o rótulo do botão para "Copiado!" e aplique uma tonalidade de cor de sucesso (
color: var(--color-success)). - Notificação do Leitor de Tela: Anuncie o status da cópia dinamicamente por meio de uma região
aria-live="polite"invisível: "Código copiado para a área de transferência". - Redefinição por Tempo Limite: Redefina o botão para o estado padrão após 2000ms.
6. Adaptação Móvel e Responsiva
Garanta que snippets de código longos permaneçam funcionais em viewports pequenos:
- Contenção de Rolagem Horizontal: Permita rolagem horizontal (
overflow-x: auto) para linhas longas em dispositivos móveis sem acionar estouros de barra de rolagem horizontal no nível da página. - Barra de Ferramentas do Cabeçalho Fixa: Mantenha a barra de ferramentas do cabeçalho fixa (
position: sticky; top: 0; z-index: 10;) para que o botão copiar e a aba de arquivo ativa permaneçam acessíveis mesmo ao rolar por 100+ linhas de código. - Alvos de Toque Móvel: Garanta que os botões de cópia, alternâncias de quebra e abas multifile atendam a um alvo de toque mínimo de 44x44px em dispositivos touch.
Regras de Decisão
Contraste de Tokens de Sintaxe e Modos de Tema
| Categoria de Sintaxe | Papel de Token Recomendado | Cor do Tema Claro (on #F8FAFC) | Cor do Tema Escuro (on #0F172A) | Taxa de Contraste Mínima |
|---|---|---|---|---|
| Palavras-chave | --token-keyword | Violeta Escuro (#6B21A8) | Violeta Brilhante (#C084FC) | ≥ 4,5:1 |
| Funções | --token-function | Ciano Escuro (#0369A1) | Azul Celeste (#38BDF8) | ≥ 4,5:1 |
| Strings | --token-string | Verde Floresta (#15803D) | Esmeralda Brilhante (#4ADE80) | ≥ 4,5:1 |
| Números / Booleanos | --token-number | Âmbar Escuro (#C2410C) | Âmbar Brilhante (#FB923C) | ≥ 4,5:1 |
| Comentários | --token-comment | Ardósia Suave (#475569) | Ardósia Suave (#94A3B8) | ≥ 4,5:1 |
| Base / Variáveis | --token-base | Carvão (#0F172A) | Luz Nítida (#F8FAFC) | ≥ 7,0:1 |
Estratégia de Quebra vs. Rolagem Horizontal
- Rolagem Horizontal (
white-space: pre) (Padrão Recomendado): Preserva a integridade do layout do código, alinhamentos de indentação e formatação multilinha. Essencial para Python, YAML e diffs de código onde a indentação transmite estrutura semântica. - Quebra Suave de Palavra (
white-space: pre-wrap) (Modo Opcional): Recomendado para strings longas de saída de terminal, exemplos de linha de comando ou widgets de barra lateral estreitos onde a rolagem horizontal interrompe o fluxo de leitura.
Restrições
- Acessibilidade (WCAG 2.1 AA):
- SC 1.4.3 Contraste (Mínimo): Todas as cores de tokens de destaque de sintaxe e comentários devem atingir uma taxa de contraste mínima de 4,5:1 contra o fundo do código.
- SC 2.1.1 Teclado: Os usuários devem poder navegar e ativar os botões do cabeçalho do bloco de código (abas, botão copiar) usando
TabeEspaço/Enter. - SC 4.1.3 Mensagens de Status: O feedback do botão copiar deve anunciar para a tecnologia assistiva por meio de uma região
aria-live="polite". - SC 1.3.1 Informações e Relações: Os números de linha devem estar ocultos dos leitores de tela (
aria-hidden="true"ou contadores CSS) para evitar dígitos intercalados durante a leitura.
- Seleção e Cópia de Texto: Selecionar texto dentro do bloco de código nunca deve selecionar números de linha ou marcadores de diff (
+/-) no buffer da área de transferência. - Prevenção de Mudança de Layout: Expandir abas multifile ou alternar a quebra de linha deve especificar alturas de linha fixas ou limites de contêiner para evitar Mudança Cumulativa de Layout (CLS).
Padrões Comuns de Falha
- Comentários Ilegais de Baixo Contraste: Usar texto cinza claro (por exemplo,
#4A5568sobre#1A202C, contraste 2,8:1) para comentários, assumindo que os comentários são sem importância, violando as diretrizes WCAG AA. - Copiar Números de Linha: Renderizar números de linha como texto bruto dentro de
<pre>, fazendo com que a cópia e colagem produza snippets de código inválidos prefixados com1 2 3 4. - Ações de Cópia Não Anunciadas: Alterar ícones visuais do botão copiar sem atualizar o
aria-labelou enviar um anúncioaria-live, deixando os usuários de leitor de tela incertos se a ação foi bem-sucedida. - Estouros no Nível da Página: Não definir
max-width: 100%eoverflow-x: autoem<pre>, fazendo com que linhas de código de 120 caracteres estourem o layout da página em telas móveis. - Armadilhas de Foco Inacessíveis na Rolagem Horizontal: Colocar
tabindex="0"no bloco de código rolável sem indicadores claros de contorno visual do teclado, fazendo com que usuários de teclado fiquem presos dentro de blocos de código longos.
Critérios de Validação
- O bloco de código possui um contêiner estruturado com uma barra de ferramentas de cabeçalho fixa exibindo a linguagem, o arquivo...