Do Figma ao pixel: validando o front-end com Playwright e um relatório de confiança
Playwright é o framework de automação de navegadores mantido pela Microsoft, conhecido principalmente por testes end-to-end. No CarStore, um SPA em Vue 3 com PrimeVue e Tailwind CSS v4 servido por um host ASP.NET Core 10, ele tem um papel mais específico: renderizar cada componente entregue, fotografar o resultado e compará-lo com o frame do Figma. O que sai desse processo é um relatório offline que responde, com medição e imagem, se a tela implementada está de fato igual ao design.
A motivação é simples. Comparar uma tela com o Figma "no olho" funciona até o primeiro botão com 2px a menos de padding ou o primeiro cinza que é `#6b7280` no design e `#64748b` no código. Essas diferenças passam em code review, passam no build e só aparecem quando o designer abre a aplicação. A ideia aqui foi transformar a pergunta "está igual ao Figma?" em algo que pode ser medido, classificado e auditado.




Todo esse fluxo roda no GitHub Copilot, dentro do VS Code, e tem três atores bem separados. Um orquestrador (uma pessoa ou o próprio GitHub Copilot em modo agent) abre um ticket, o `frontend-agent` implementa e o `qa-agent` valida. Os dois são custom agents definidos em `.github/agents/`, cada um com as ferramentas que pode usar: o `frontend-agent` tem acesso aos MCP servers `primevue` e `figma-mcp`, e o `qa-agent` soma a eles o `playwright`. Um detalhe importante é que nenhum dos dois chama o outro: quem implementa nunca roda o Playwright, e quem valida nunca edita código de produção. O orquestrador é quem leva os artefatos de uma etapa para a próxima.
Imagem: diagrama do fluxo ticket, frontend-agent, qa-agent e rodadas de correção

Tudo começa com a skill `create-frontend-ticket`, que gera um arquivo `ticket-frontend-<slug>.md` na raiz do repositório. O ticket descreve requisitos verificáveis (elementos visíveis, textos em pt-BR, estados de loading, vazio e erro, temas claro e escuro), referencia o Figma quando existe e já carrega o ciclo de implementação e QA com no máximo três rodadas de correção. Ele é o contrato: os agentes recebem o ticket e as notas do vault, não o histórico da conversa.
Com uma URL do Figma em mãos, o `frontend-agent` roda a skill `figma-discovery`, que consulta o Figma MCP server através das ferramentas `get_metadata`, `get_screenshot`, `get_design_context` e `get_variable_defs`. A regra principal dessa etapa é nunca adivinhar valores a partir de um screenshot. As cores esperadas vêm de `get_variable_defs`, porque os hex que aparecem no código gerado por `get_design_context` são apenas fallbacks das variáveis, e não o modo aplicado ao frame.
Imagem: frame "Central da frota" aberto no Figma com as variáveis de cor visíveis no painel lateral

O resultado da descoberta fica em cache em `.figma-cache/<fileKey>/<nodeId>/`, com o relatório, o contexto bruto, as variáveis e o screenshot do nó. Cada nó é lido do MCP uma única vez por ticket, e o `qa-agent` e as rodadas de correção reaproveitam a mesma pasta. Além de economizar chamadas, isso garante que implementação e validação trabalham sobre exatamente a mesma versão do design.
Com o relatório pronto, a skill `primevue-component-build` traduz o design para os padrões do projeto: tokens como `text-muted-color` e `bg-surface-0` no lugar de hex soltos, ícones Lucide, estilos via `pt` do PrimeVue e reaproveitamento de peças como `DataTableCommon.vue` e `dialogShellPt()`. Antes de devolver a entrega, o agente roda a verificação completa dentro de `Src/CarStore.Web/ClientApp`.
npm run verifyEsse script executa `vue-tsc --noEmit`, depois `scripts/check-conventions.mjs` (que barra PrimeIcons, hex fora de token, resquícios de Bootstrap e `alert`) e por fim o `vite build`. A entrega termina com um resumo estruturado contendo `arquivos`, `componentes`, `estados`, `larguras`, `figma`, `figma-cache` e `lacunas`, que é exatamente o que o `qa-agent` exige como entrada.
É aqui que o Playwright entra. O `qa-agent` usa um harness versionado em `ClientApp/visual/` que monta componentes reais em isolamento, com mocks determinísticos da API, e compara três versões de cada cenário. A versão anterior é o mesmo cenário renderizado a partir do commit base, a atual é a working tree e a terceira é a referência do Figma, composta por um PNG e um arquivo de spec. Nada desse harness vai para produção, já que o `vite.config.ts` só compila `src/main.ts` e o `style.css` exclui a pasta do scan do Tailwind.
Cada tela validada é descrita como um cenário. Este é o cenário real da Home, a "Central da frota":
const VIEWPORT = { ...DESKTOP, deviceScaleFactor: 1 }
function homeDashboard(theme: 'light' | 'dark'): VisualScenario {
const light = theme === 'light'
return {
id: `home-dashboard-${theme}`,
componentPath: 'Src/CarStore.Web/ClientApp/src/components/Home.vue',
component: () => import('../../src/components/Home.vue'),
route: { path: '/' },
routeNames: ['home', 'cars', 'brands', 'customers'],
viewport: VIEWPORT,
mountWidth: pageWidth(VIEWPORT.width),
theme,
locale: 'pt-BR',
device: 'desktop',
captureSelector: '#preview-root > .home-ready',
mocks: homeMocks({ cars, brands, customers: figmaCustomers }),
actions: [
{ type: 'expect-count', selector: '.home-ready', count: 1 },
{ type: 'wait', ms: 800 },
],
baselineActions: [{ type: 'wait', ms: 3000 }],
renderChecks: [
{ label: 'Título da página', selector: 'h1', text: 'Central da frota' },
{ label: 'Quatro cartões de KPI', selector: '.grid.xl\\:grid-cols-4 > .p-card', count: 4 },
{ label: 'Tabela de clientes recentes com 5 linhas', selector: '.p-datatable-tbody > tr', count: 5 },
],
...(light
? {
figmaNode: {
nodeId: '2005:5266',
name: 'Tela · Central da frota',
url: 'https://www.figma.com/design/EOvtzuJAvw1UnoH9tsYmiO/?node-id=2005-5266',
},
}
: {
referenceNote: 'Sem frame escuro no Figma: o tema escuro é revisado por contraste e legibilidade, sem paridade de design',
}),
}
}
export default [homeDashboard('light'), homeDashboard('dark')]homeDashboard()
Gera o par de cenários claro e escuro a partir da mesma definição, já que o harness bloqueia PASS quando um cenário claro não tem o irmão escuro.
mountWidth: pageWidth(VIEWPORT.width)
Monta a página com a largura que ela tem em produção (viewport menos a sidebar e o padding do shell), porque o `App.vue` não é montado no preview.
mocks
Declara todas as chamadas `/api/*` que a Home faz, usando fixtures que são snapshots da API semeada.
actions e baselineActions
Esperam o estado real da tela antes da captura; a versão base usa uma espera simples porque o hook `.home-ready` pode não existir naquele commit.
renderChecks
Verificam requisitos de texto e contagem na renderização atual, independentemente do Figma.
figmaNode e reference
Note
O primeiro torna a evidência do Figma obrigatória para o tema claro; o segundo explica no relatório por que o tema escuro não tem referência.
Para que a comparação seja confiável, a mesma tela precisa gerar exatamente os mesmos pixels em qualquer máquina e em qualquer dia. O harness intercepta toda requisição do contexto com `context.route()` (https://playwright.dev/docs/mock) antes da primeira navegação:
await context.route('**/*', async (route: Route) => {
const request = route.request()
const url = request.url()
const mock = mocks.find((m) => matchesMock(m, url))
if (mock) {
const count = responseCounts.get(mock) ?? 0
responseCounts.set(mock, count + 1)
const response = mock.responses?.[Math.min(count, mock.responses.length - 1)] ?? mock
const body = typeof response.body === 'string' ? response.body : JSON.stringify(response.body)
fulfilled.push(sanitizeUrl(url))
await route.fulfill({
status: response.status,
contentType: response.contentType,
body,
})
return
}
if (isApiRequest(url)) {
blocked.push({
url: sanitizeUrl(url),
method: request.method(),
resourceType: request.resourceType(),
reason: 'unmocked-api',
})
await route.abort('blockedbyclient')
return
}
if (!isSameOrigin(url, origin)) {
blocked.push({
url: sanitizeUrl(url),
method: request.method(),
resourceType: request.resourceType(),
reason: 'external-origin',
})
await route.abort('blockedbyclient')
return
}
await route.continue()
})
await context.clock.setFixedTime(new Date(scenario.now ?? FIXED_NOW))context.route()
Responde cada chamada declarada com o mock correspondente, aborta qualquer `/api` não declarada e qualquer requisição para outra origem, registrando ambas como bloqueadas no relatório.
context.clock.setFixedTime()
Fixa o `Date` do navegador em `FIXED_NOW` (`2026-11-10T12:00:00Z`) usando a Clock API, o que importa porque o gráfico de novos clientes mostra os 12 meses anteriores a "hoje".
Somam-se a isso o timezone em `UTC`, `reducedMotion: 'reduce'`, screenshots com `animations: 'disabled'`, service workers bloqueados e apenas Chromium. O `playwright.config.ts` justifica essa última escolha: o relatório é uma revisão de paridade de design, não uma matriz cross-browser, e um segundo engine deixaria cada imagem de referência ambígua. Também não é preciso subir o `dotnet run`, porque o próprio Playwright inicia o servidor de preview via `webServer` na porta 5175.
A referência do Figma tem duas partes, ambas em `visual/references/`. O PNG `<id>.png` é o `get_screenshot` do nó recortado no mesmo elemento que o cenário captura. O arquivo `<id>.figma.json` é uma spec com o nó de origem, a árvore do frame, os textos esperados e, principalmente, os `checks`, que são propriedades medidas no DOM e comparadas com o valor do Figma:
{
"nodeId": "I2005:5302;363:2793",
"nodeName": "page-header / title",
"selector": ":scope > div:nth-child(1) h1",
"text": "Central da frota",
"props": {
"fontSize": 24,
"fontWeight": 600,
"lineHeight": 32,
"letterSpacing": 0,
"color": "#1f2937",
"fontFamily": "Inter"
}
}Cada check é medido com `getBoundingClientRect` e `getComputedStyle` no mesmo estado de página do screenshot, com tolerância padrão de ±1px para medidas e ±2 por canal de cor. A spec da Home tem 30 checks; a listagem de carros passa de 120. A regra que dá sentido a tudo isso é que os valores esperados vêm sempre do Figma, nunca da renderização atual, e um screenshot do harness nunca pode ser promovido a referência. A spec também roda contra a versão base, o que mostra se uma mudança aproximou ou afastou a tela do design.
Ao lado da spec, o harness compara os pixels. A função `compareImages()` em `visual/lib/compare.ts` usa o pixelmatch:
if (refDims.width !== actDims.width || refDims.height !== actDims.height) {
return {
status: 'dimension-mismatch',
algorithm: 'pixelmatch',
threshold: PIXELMATCH_THRESHOLD,
mismatchTolerance: MISMATCH_RATIO_TOLERANCE,
reference: refDims,
actual: actDims,
mismatchedPixels: null,
comparedPixels: null,
mismatchRatio: null,
diffImage: null,
sideBySideImage: sideBySidePath,
findings: [`Dimension mismatch: reference is ${refDims.width}x${refDims.height}, actual is ${actDims.width}x${actDims.height}.`],
}
}
const diff = new PNG({ width: refDims.width, height: refDims.height })
const mismatchedPixels = pixelmatch(
reference.data,
actual.data,
diff.data,
refDims.width,
refDims.height,
{ threshold: PIXELMATCH_THRESHOLD, includeAA: false },
)
const comparedPixels = refDims.width * refDims.height
const mismatchRatio = comparedPixels === 0 ? 0 : mismatchedPixels / comparedPixels
const passed = mismatchRatio <= MISMATCH_RATIO_TOLERANCEVerificação de dimensões
Se a referência e a captura têm tamanhos diferentes, a comparação para ali e vira um achado; as imagens nunca são redimensionadas, porque isso esconderia justamente a diferença que se quer medir.
pixelmatch()
Conta os pixels divergentes com `threshold` 0.1 e ignorando anti-aliasing, e gera o `diff.png` que destaca as diferenças em vermelho.
MISMATCH_RATIO_TOLERANCE
Define o limite de 0,1% de pixels divergentes para um cenário passar automaticamente na comparação visual.
Como o `get_screenshot` do Figma MCP exporta o nó no tamanho natural (1x), os cenários comparados com o Figma capturam com `deviceScaleFactor: 1`, por isso o `VIEWPORT` da Home sobrescreve esse valor.
A terceira coluna da comparação, a versão anterior, vem de um git worktree. O launcher faz checkout do commit base em `.visual-baseline/<sha12>`, sobrepõe o harness atual sem tocar no código de produção da base, reaproveita o `node_modules` quando o lockfile é o mesmo e captura cada cenário na porta 5174 com os mesmos mocks, viewport, tema e relógio. Diferença contra a base aparece no relatório como "mudança visual em relação à base" e nunca reprova a execução, mas é ela que permite separar uma mudança intencional de uma regressão.
Para rodar a validação de uma tela, o comando padrão compara tudo contra o merge-base com `main`:
cd Src/CarStore.Web/ClientApp
npm run visual:compare -- home-dashboard-light,home-dashboard-darkQuando o trabalho ainda não foi commitado, a base passa a ser o último commit, e o script `visual:ids` monta a lista de cenários de uma tela inteira:
VISUAL_BASELINE_REF=HEAD npm run visual:compare -- $(npm run -s visual:ids -- cars)Cada execução gera um bundle em `qa-results/<timestamp>-<tela>/`. Dentro dele ficam o `index.html` offline (CSS e JS inline, imagens relativas, nenhuma chamada de rede), o `report.json` no schema `carstore-visual-check/6`, o `findings.md` com a decisão de QA e as pastas `actual/`, `baseline/`, `reference/` e `comparison/`, separadas por tentativa (`attempt-01`, `attempt-02` e assim por diante).
Imagem: Aba Resumo do index.html com o status de cada cenário e as abas Light, Dark e Outros estados

A peça mais útil para a revisão é o tríptico, que coloca lado a lado a versão anterior, a atual e o Figma, sem redimensionar nenhuma delas. Quando um painel não existe, ele é omitido em vez de ser substituído por um placeholder que poderia ser confundido com um screenshot.
Um ponto que faz esse relatório ser "de confiança" é que a captura sozinha não aprova nada. Um `8 passed` do Playwright significa apenas que as capturas foram concluídas. Toda execução nasce com status BLOCKED no `findings.md`, e cada diferença medida precisa ser classificada pelo `qa-agent` em uma destas categorias: `defeito`, `backend`, `decisao-design`, `artefato-harness`, `intencional` ou `conteudo-dinamico`. A decisão é registrada em um JSON e aplicada por um CLI:
npm run visual:verdict -- verdict.json /abs/path/qa-results/<run>{
"result": "PASS",
"criteria": [{ "text": "Requested state renders in both themes", "status": "pass",
"evidence": ["actual/attempt-01/home-dashboard-light.png", "actual/attempt-01/home-dashboard-dark.png"] }],
"diferencas": [],
"minimas": [],
"bloqueios": [],
"notes": ["Images reviewed against the requested layout."]
}resultO
veredito que o QA pede, que o CLI pode rebaixar.
criteria
Os requisitos do ticket, cada um com status e com os arquivos do bundle que servem de evidência.
diferencas
As diferenças medidas, referenciadas pelo `id` gerado, com categoria, motivo e imagem.
minimas
Diferenças pequenas aceitas por julgamento explícito, restritas a pixels e a linhas isoladas de spacing, radius ou tracking.
O CLI não aceita o PASS por confiança. Ele rebaixa o resultado quando um arquivo de evidência não existe, quando falta o irmão escuro de um cenário claro, quando um cenário com `figmaNode` não tem PNG e spec, quando sobra algum item `nao-classificado` ou quando existe qualquer item `decisao-design`, `backend` ou `artefato-harness`. Elementos ausentes, texto errado, overflow, contraste e estados quebrados nunca podem ser marcados como diferença mínima. Uma divergência do Figma só vira `intencional` com aprovação explícita de quem é dono do design, e essa aprovação fica escrita no motivo.
Um exemplo real ajuda a ver como isso fica na prática. Na validação da listagem de carros, a quarta tentativa terminou com PASS, e o `findings.md` registra cada concessão com número e justificativa. O botão Editar do diálogo de detalhes mede 96,83px contra 98px no Figma e foi classificado como `conteudo-dinamico`, porque padding, ícone e gap conferem e a diferença vem da métrica do texto Inter no Chromium. A Home diverge 1,033% em pixels do Figma, mas a spec passa e a captura tem 0px de diferença contra o HEAD e contra a tentativa anterior, o que isola a causa nas datas do fixture e na rasterização da fonte. Já o menu de linha aberto para cima com gap de 4,5px está como `intencional`, com a anotação de que a exceção foi aprovada pelo usuário.
Imagem: Findings.md da listagem de carros com status PASS e as tabelas diferencas e minimas

Quando o veredito é FAIL, entram as rodadas de correção. O orquestrador repassa ao `frontend-agent` apenas os itens `defeito` que não são mínimos, e o agente corrige só esses itens e roda `npm run verify` de novo. Em seguida o `qa-agent` executa o recheck sobre o mesmo bundle:
npm run visual:recheck -- /abs/path/qa-results/<run>O recheck acrescenta uma nova tentativa, reaproveita o commit base do bundle e imprime um JSON com os defeitos `resolvido` ou `persiste`, os achados novos, a lista `abrir[]` com as únicas imagens que valem ser abertas e um `verdictDraft` com o julgamento anterior menos os itens resolvidos. Se nada persiste e não há achados novos, o rascunho registra PASS sem abrir nenhuma imagem. Para uma análise mais fina existem `visual:measure`, que abre o cenário exatamente como foi capturado e imprime caixas e estilos computados de um seletor, `visual:crop`, que amplia a mesma região de duas imagens lado a lado, e `visual:attempt-diff`, que mostra o que uma correção mudou entre duas tentativas.
O ciclo tem limite de três rodadas e também para antes quando não há mais defeitos, quando algo bloqueia ou quando uma rodada não reduz a contagem de defeitos. O primeiro QA é exaustivo, cobrindo todos os cenários nos dois temas para que os defeitos apareçam de uma vez, enquanto correções e rechecks são estreitos e não voltam a consultar o Figma nem as instruções. Ao final, o orquestrador executa a skill `vault-write` uma única vez para registrar no vault Obsidian os componentes alterados, os nós do Figma e qualquer novo mapeamento de token. No commit da entrega vão o código, o `wwwroot/dist/` reconstruído e os arquivos de julgamento do bundle; os screenshots ficam apenas na máquina local.
O resultado desse fluxo é que "está igual ao Figma" deixa de ser uma opinião. Cada tela entregue tem uma spec derivada do design, uma comparação de pixels sem redimensionamento, uma referência da versão anterior e um veredito que só passa quando toda diferença foi medida, classificada e justificada.
Você já pode baixar o projeto por esse link, e não esquece de me seguir no LinkedIn!
Links e Docs:











Até a próxima, abraços!linke


