O que Layout Witness faz?
Torce a página mais fácil de escanear e usar. Dê a elementos relacionados um agrupamento claro, mantenha componentes repetidos consistentes e preserve essas relações conforme o conteúdo e o tamanho da viewport mudam. Use os guias para decidir o que corrigir enquanto edita.
Use a extensão Chrome na aba de desenvolvimento existente. Emparelhe sua conexão de agente local para controlar guias e ler medições de página e elementos como JSON no terminal. Use a CLI opcional do Playwright para capturas não supervisionadas em contextos de navegador frescos.
Conectar-se à aba existente
Carregue o diretório completo da habilidade layout-witness como uma extensão não empacotada em chrome://extensions. Use Chrome 116 ou posterior.
- Defina
WITNESS_DIRcomo o diretório da habilidade instalada. Execute(cd "$WITNESS_DIR" && npm ci --omit=dev)uma vez, depois inicienode "$WITNESS_DIR/scripts/agent.mjs" serveem um terminal persistente. - Abra o Layout Witness na barra de ferramentas na aba de desenvolvimento. Em Agent access, cole a URL de emparelhamento impressa pelo terminal e escolha Connect agent. Isso autoriza a aba. Se o acesso estiver ausente, peça ao usuário para emparelhar essa aba uma vez.
- Use a CLI de qualquer terminal na mesma máquina. Mantenha o servidor local em execução durante as edições.
node "$WITNESS_DIR/scripts/agent.mjs" start
node "$WITNESS_DIR/scripts/agent.mjs" select 'header [aria-label="Search"]'
node "$WITNESS_DIR/scripts/agent.mjs" measure
# Edite o CSS do projeto e aguarde o servidor de desenvolvimento aplicá-lo.
node "$WITNESS_DIR/scripts/agent.mjs" measure
measure imprime regiões da página, resultados de verificação e o elemento atualmente selecionado quando disponível. Esse elemento pode incluir sua caixa renderizada, margem, borda, preenchimento, valores de grade e gap, tipografia (incluindo linha de base Y da viewport quando mensurável) e geometria SVG. Use um seletor que corresponda a um elemento visível. Mantenha a seleção enquanto edita e leia seu JSON novamente depois que o navegador aplicar a alteração.
Use status para verificar a conexão, clear para remover apenas o guia do elemento, pick para seleção manual por clique, import <rules.json> para carregar regras do projeto e defaults para restaurar regras padrão. Use stop para remover ambos os guias e limpar a seleção para uma revisão limpa. Use start e select para retomar. Use disconnect quando terminar se a aba deve parar de aceitar comandos. Recarregamentos de mesma origem podem restaurar guias e uma seleção na mesma rota. Uma origem diferente ou fechamento da aba encerra o emparelhamento.
Para revisão manual, use Start guides, Inspect element e Stop guides no pop-up da barra de ferramentas. Download report está disponível quando você deseja salvar uma cópia.
Trabalhar com os guias ativos
- Defina o layout esperado. Leia as regras de layout e componente do projeto, depois verifique os tokens existentes e componentes irmãos aceitos. Anote as relações que importam para a tarefa, como uma borda de leitura compartilhada, um gap entre grupos de navegação ou o preenchimento inline de um botão. Em uma nova página, escolha essas relações a partir do briefing e registre suas suposições. Trate a grade padrão da extensão como um guia exploratório.
- Inspecione da página ao elemento. Inicie os guias antes de editar. Capture o ponto de partida renderizado e selecione o elemento que possui o problema. Use o relatório para medições exatas quando os rótulos estiverem sobrepostos. Para uma nova página, inicie assim que a estrutura for renderizada e mantenha os guias ativos enquanto adiciona seções e controles.
- Edite o código-fonte com a seleção ativa. Compare o valor medido com o esperado. Corrija o CSS ou componente compartilhado que possui a relação. Quando o servidor de desenvolvimento aplicar a edição, verifique os guias e medições do mesmo elemento antes de escolher outro. Se um recarregamento substituir o elemento, confirme que a seleção restaurada ainda se refere ao controle pretendido. Registre o valor real, o valor esperado e o resultado medido.
- Revise a renderização limpa. Capture o guia corrigido primeiro, depois desligue os guias e inspecione a página real. Verifique agrupamento, hierarquia, alinhamento, quebra de linha e foco visível nas larguras onde o layout muda. Inclua rótulos longos ou conteúdo traduzido e estados relevantes abertos, recolhidos ou densos. Relate problemas restantes e as larguras e estados que você verificou.
| Escopo | O que inspecionar |
|---|---|
| Estrutura da página | Use os guias da página para verificar bordas de leitura compartilhadas, margens externas e como o cabeçalho, barra lateral, área principal e rodapé se adaptam nos breakpoints. Na renderização limpa, verifique se as ações recorrentes permanecem fáceis de encontrar e a tarefa principal recebe a ênfase visual mais forte. |
| Grupos e componentes repetidos | Use trilhas de grade locais para verificar alinhamento e extensões dentro de uma região. Compare o espaço entre grupos separadamente do preenchimento e gaps dentro de cada componente. Mantenha itens relacionados visivelmente agrupados e verifique a ordem de leitura quando os grupos empilham. |
| Elementos individuais | Selecione o controle para inspecionar sua caixa, preenchimento e gap entre ícone e rótulo. Compare a altura da linha e a linha de base entre rótulos que devem se alinhar. Revise o tamanho do ícone e traço dentro da mesma família, depois julgue o equilíbrio óptico no tamanho renderizado. Meça o destino interativo separadamente do seu glifo. |
Para uma barra lateral congestionada, primeiro verifique se links relacionados são lidos como um grupo e se seções adjacentes têm um gap claro. Em seguida, selecione uma linha e compare seu recuo e gap entre ícone e rótulo com linhas equivalentes. Se o componente compartilhado exige 16 px em cada lado e o guia mostra 8 px em um lado, restaure o token e remeça a mesma seleção. Desligue o guia para verificar a barra lateral expandida e recolhida no contexto.
Use verificações rigorosas para expectativas explícitas como valores de tokens, alinhamento entre bordas nomeadas e overflow. Julgue hierarquia e equilíbrio óptico na página renderizada. Use a escala tipográfica do projeto para decidir se uma linha de base deve se alinhar.
Referências de design
- Adobe Spectrum 2 explica como a proximidade sinaliza relacionamentos, como o espaçamento difere por escopo e como revisar espaçamento e traço de ícones dentro de uma família. Espaçamento · Fundamentos de ícones
- Figma mostra como escolher guias para a página, regiões aninhadas, preenchimento de componentes e linhas de base de texto. Grades de layout
- A reformulação do design do Linear é um estudo de caso em ações de cabeçalho previsíveis e hierarquia visual em um espaço de trabalho denso. Reformulação do design
Quando acessibilidade estiver no escopo, use WCAG para verificar reflow, substituições de espaçamento de texto do usuário e alvos de ponteiro reais, incluindo exceções aplicáveis. Reflow · Espaçamento de texto · Tamanho do alvo
Capturas não supervisionadas opcionais
Use a CLI quando a automação precisar de contextos de navegador frescos em diferentes larguras de viewport ou temas. Requer Node.js 22+ e Playwright Chromium. Defina WITNESS_DIR como o diretório da habilidade instalada e instale suas dependências lá:
(cd "$WITNESS_DIR" && npm ci && npx --no-install playwright install chromium)
Execute a CLI a partir do projeto para que seu caminho de configuração e saída sejam resolvidos lá:
node "$WITNESS_DIR/scripts/witness.mjs" capture http://localhost:3000 \
--config ./layout-witness.json --width 1440 --width 390 --strict \
--out .layout-witness/review
Leia a sobreposição gerada e o relatório JSON. O modo de captura abre uma nova página para cada largura e tema. Consulte a referência de regras para definições de região e verificação. Use watch para o fluxo de trabalho interativo da CLI.