Do Figma ao pixel: validando o front-end com Playwright e um relatório de confiança

Do Figma ao pixel: validando o front-end com Playwright e um relatório de confiança

17 de novembro de 2026

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 verify

Esse 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_TOLERANCE

Verificaçã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-dark

Quando 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:

Installation | Playwright
Introduction
Vue.js
Vue.js - The Progressive JavaScript Framework
PrimeVue | Vue UI Component Library
The ultimate collection of design-agnostic, flexible and accessible Vue UI Components.
Tailwind CSS - Rapidly build modern websites without ever leaving your HTML.
Tailwind CSS is a utility-first CSS framework for rapidly building modern websites without ever leaving your HTML.
Build with AI in VS Code
Choose AI workflows, models, and agents in VS Code, from inline suggestions to remote sessions.
Custom agents in VS Code
Reuse, create, and manage custom agents in VS Code for specialized development roles and workflows.
Introduction | Developer Docs
The Figma MCP server brings Figma into your AI workflow. It gives AI agents the design context they need to generate code from your Figma files, and lets agents write native Figma content back to the canvas.
Mock APIs | Playwright
Introduction
Clock | Playwright
Introduction
Web server | Playwright
Introduction
GitHub - mapbox/pixelmatch: The smallest, simplest and fastest JavaScript pixel-level image comparison library
The smallest, simplest and fastest JavaScript pixel-level image comparison library - mapbox/pixelmatch
Git - git-worktree Documentation

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

Confira mais:

Fique por dentro das novidades

Assine nossa newsletter e receba as últimas atualizações e artigos diretamente em seu email.

Assinar gratuitamente