Skill

UI Validation (Validação de Interface)

Uma skill do ecossistema de agentic-best-practices desenhada para testar estresse visual e garantir consistência em interfaces web modernas.

A skill de Validação de Interface foi projetada para lidar com o problema comum em que Inteligências Artificiais alteram o CSS do projeto e quebram layouts indiretamente, devido à incapacidade nativa de visualizar a renderização exata do CSS moderno.

O Que a Skill Faz?

A skill (.claude/skills/ui-validation/SKILL.md) obriga o agente de IA a seguir um fluxo rigoroso antes de confirmar qualquer mudança visual:

1. Geração do Ambiente de Testes: Caso a página Kitchen Sink (style-guide-test.md) não exista, o Agente constrói ela automaticamente, populando-a com tabelas, citações, fórmulas em KaTeX e blocos de código aninhados para testar o CSS até o seu limite (Stress Test).
2. Setup do Playwright & Axe-core: A skill garante a instalação de ferramentas de inspeção de DOM e validação de acessibilidade automatizada (para verificar contraste entre cores no Tema Claro e Escuro).
3. Execução de Lint de Design: Sempre que ocorrer mudança de estilo, o agente precisa engatilhar o comando npm run lint:design, validando heurísticas listadas em google-labs-code/design.md.
4. Resolução de Erros: O agente corrige o código e re-executa a validação automaticamente ao encontrar quebras de contraste ou DOM corrompido.

Como Configurar o CLAUDE.md

Para ativar a skill de maneira fluída em seu repositório sem poluir as instruções mestre da IA, você deve manter o seu CLAUDE.md focado apenas no acionamento (gatilho).

No arquivo CLAUDE.md, na seção de Guias Específicos ou equivalente, adicione APENAS a seguinte linha:

## Guias Específicos

- **Validação de Interface:** Sempre que alterar o CSS ou for solicitado a validar estilos visuais, você deve seguir o processo ditado pela skill `Validação de Interface` e pelas heurísticas no `google-labs-code/design.md`.

Com isso, sempre que você mencionar “Estilos”, “CSS”, ou “Validar interface”, o agente automaticamente invocará o diretório .claude/skills/ui-validation/SKILL.md puxando toda a lógica de validação para o contexto atual dele, mantendo o custo de tokens e a sobrecarga cognitiva do bot baixa quando você estiver focado em escrever Backend ou outra tarefa alheia ao front-end!

O Código por trás da Mágica (Snippets)

Para referência técnica, abaixo estão os códigos que compõem o motor desta automatização visual:

1. O Arquivo SKILL.md (O cérebro do robô)

Localizado em .claude/skills/ui-validation/SKILL.md:

---
name: Validação de Interface (UI Validation)
description: Workflow rigoroso para validação de estilos CSS, renderização visual, testes de contraste de cores e uso do Playwright. Disparado quando ocorrem mudanças em CSS, estilos ou quando o usuário pede validação visual.
---

# Validação de Interface (UI Validation Skill)

Esta skill documenta o fluxo completo e obrigatório para validar qualquer alteração visual ou de design (ex: no `style.css`).

## 1. Pré-Requisitos (Setup)

Se o projeto não estiver com o ambiente de testes de UI configurado, você DEVE executar os passos abaixo:

1. **Guia de Estilos**: Verifique se existe a página `src/notas/style-guide-test.md`. Se não existir, você deve criá-la.
2. **Playwright e Axe**: Certifique-se de que `@playwright/cli` e `@axe-core/playwright` estejam instalados.
3. **Scripts de Lint**: O `package.json` deve conter `"lint:design": "node test-a11y.js"`.

## 2. Padrões Estéticos (Obrigatório)

Sempre baseie decisões estéticas (Cores, Tipografia, Espaçamentos) no documento `google-labs-code/design.md`.

## 3. O Fluxo de Validação

Sempre que o CSS for modificado:

1. Renderize a página `style-guide-test/`.
2. Rode o comando de lint visual usando `npm run lint:design`.
3. Este script executa testes automáticos em **Modo Claro** e **Modo Escuro**.
4. Qualquer erro de contraste (Exit Code 1) deve ser corrigido imediatamente.

2. O Script de Teste Axe-Core

Localizado em test-a11y.js e rodado via npm run lint:design:

const { chromium } = require("playwright");
const AxeBuilder = require("@axe-core/playwright").default;

(async () => {
  console.log("Iniciando validação de constraste de design (Axe-core)...");

  const browser = await chromium.launch();
  const context = await browser.newContext();
  const page = await context.newPage();

  const url = "http://localhost:5500/notas/style-guide-test/";

  try {
    await page.goto(url);

    console.log("Testando Tema Claro (Light Mode)...");
    await page.evaluate(() =>
      document.documentElement.setAttribute("data-theme", "light"),
    );

    let results = await new AxeBuilder({ page }).withRules("color-contrast").analyze();
    if (results.violations.length > 0) {
      console.error("❌ Falha de contraste no Tema Claro");
      process.exitCode = 1;
    }

    console.log("Testando Tema Escuro (Dark Mode)...");
    await page.evaluate(() => document.documentElement.removeAttribute("data-theme"));

    results = await new AxeBuilder({ page }).withRules("color-contrast").analyze();
    if (results.violations.length > 0) {
      console.error("❌ Falha de contraste no Tema Escuro");
      process.exitCode = 1;
    }
  } catch (error) {
    process.exitCode = 1;
  } finally {
    await browser.close();
  }
})();

Relacionadas: agentic-best-practices · frontend-testing-practices