UI Quality Workbench

O que UI Quality Workbench faz?

Use esta skill para executar o módulo local de UI 走查. Ele compara uma imagem de design com uma captura de tela da implementação em um Worker do navegador, agrupa diferenças visíveis em candidatos a revisão e oferece suporte à confirmação humana e exportação.

O analisador é heurístico. Chame sua saída de candidatos ou possíveis incompatibilidades até que uma pessoa verifique o design pretendido, a rota, o estado, o conteúdo e a janela de visualização. Nunca apresente um resultado não revisado como um defeito confirmado.

Iniciar o workbench

1. Resolva o diretório desta skill a partir do SKILL.md selecionado. Não presuma a raiz do repositório nem codifique um local de instalação.

2. Verifique o bundle e a bridge de origem local antes do primeiro lançamento em uma sessão:

   python3 <diretorio-da-skill>/scripts/serve_workbench.py --check
   

3. Inicie o servidor como um processo de longa duração:

   python3 <diretorio-da-skill>/scripts/serve_workbench.py
   

   O lançador imprime uma linha JSON com event: "ready", protocol: 2, uma URL de loopback dinâmica e metadados do processo. Use a URL retornada exatamente; seu fragmento carrega o token por lançamento usado pelo aplicativo do navegador.

4. Se o controle do navegador estiver disponível e o usuário quiser a interface aberta, navegue até essa URL. Caso contrário, forneça a URL ao usuário.

5. Mantenha o processo em execução enquanto o workbench estiver em uso. Pare-o com Ctrl+C quando o usuário solicitar o fechamento ou a sessão não precisar mais dele.

Se a inicialização falhar com EPERM ou uma restrição explícita de socket de loopback, solicite permissão de execução local e repita o mesmo comando. Não altere o endereço de bind, substitua por uma cópia hospedada ou faça upload de imagens locais para outro lugar.

Escolher fontes

O workbench precisa de uma imagem de design e uma imagem de implementação. Cada alteração de fonte invalida resultados anteriores; execute a auditoria novamente após substituir qualquer fonte.

• Imagem local: clique para selecionar ou arraste um PNG, JPEG ou WebP para a área de design/implementação correspondente. A decodificação, comparação de raster e agrupamento permanecem na sessão local do navegador.
• Frame do Figma: forneça uma URL design ou file do Figma contendo um node-id, mais um token de acesso pessoal (PAT), ou inicie o lançador com FIGMA_ACCESS_TOKEN. Isso importa uma renderização PNG desse frame por meio da API do Figma; não navega pelo arquivo nem herda um login do Figma.
• Captura web: forneça uma URL HTTP(S), dimensões da janela de visualização e tempo de espera de renderização opcional. A bridge inicia um perfil temporário do Chrome/Chromium/Edge headless e captura essa janela de visualização. Não herda o perfil do navegador do usuário, cookies, extensões ou sessão autenticada.

Leia references/source-imports.md antes de operar ou solucionar problemas de importação do Figma ou captura web.

Executar e revisar uma auditoria

1. Confirme que ambas as fontes representam a mesma rota, estado da UI, localidade, conteúdo, janela de visualização e posição de rolagem o mais próximo possível.
2. Verifique a prévia de normalização exibida. O mecanismo usa a fonte mais larga como a largura alvo, mantém-na em 1×, amplia proporcionalmente apenas a fonte mais estreita para essa largura e alinha ambas as imagens no canto superior esquerdo. Ele não estica ou corta nenhuma fonte, e uma diferença de altura restante na parte inferior permanece na comparação.
3. Inicie a auditoria. Antes da classificação local, o Worker verifica se os rasters normalizados são adequados para comparação direta. Um par de baixa comparabilidade para sem gerar candidatos; um par de média comparabilidade continua com um aviso explícito. Esta é uma porta heurística conservadora, não uma probabilidade ou um julgamento semântico sobre qual imagem está correta.
4. Inspecione os candidatos na comparação visual, na lista e no painel de detalhes. O conteúdo transparente unilateral é relatado apenas como uma diferença de presença de região/layout. Alterações ambíguas de mídia ou conteúdo usam redação neutra em vez de serem forçadas a defeitos de cor, texto, ícone ou geometria. Verifique se o anti-aliasing, o carregamento de fontes, a animação, os dados dinâmicos, o comportamento responsivo ou o design desatualizado explicam a diferença.
5. Confirme apenas os candidatos verificados. Exija um motivo para ignorar intencionalmente uma diferença real ou descartar um falso positivo.
6. Atribua severidade e prioridade independentemente e, em seguida, exporte a lista revisada. Não infira prioridade com base na área de pixel ou distância de cor sozinha.

Leia references/audit-model.md ao classificar, priorizar, alterar o status da revisão ou decidir o que exportar. Leia references/v0-boundaries.md antes de explicar privacidade, integrações suportadas, comportamento de captura ou limitações analíticas.

Manter alegações precisas

• O mecanismo de comparação é adaptado de SemineChen/yangao no commit fixo beac836ba3c81b9a1d40bac8fe75af08444ab742, com a permissão do autor conforme relatado pelo usuário. Veja THIRD_PARTY_NOTICES.md.
• A importação do Figma requer um PAT e acesso de saída ao Figma. Não é OAuth, vinculação de conta, extração de token de design ou análise geral de arquivos do Figma.
• A captura web é uma captura de tela isolada da janela de visualização atual. Não é costura de página inteira, navegação interativa, herança de estado de login, inspeção de DOM ou extração de estilo computado.
• O processamento local do navegador não é uma certificação de segurança. A importação do Figma necessariamente envia o PAT para o Figma e baixa o frame selecionado; a captura de página da web necessariamente solicita a URL fornecida.
• A porta de comparabilidade não tem OCR, DOM ou semântica de produto. Ela pode parar entradas amplamente incompatíveis e alertar sobre alterações localizadas, mas não pode provar que duas telas representam a mesma rota/estado nem identificar o lado autoritativo.
• UI 走查 é o módulo implementado. Não afirme que os módulos de interação-experiência, acessibilidade ou colaboração planejados já estão em execução.