Pixel-Perfect Audits via Vision LLMs: Playwright vs Figma Designs

[ Figma REST API ]                      [ Playwright Headless ]
  |-- /v1/files/:key/nodes                |-- page.setViewportSize()
  |   (Extract Design Tokens)             |-- page.addStyleTag(freezeCSS)
  `-- /v1/images (Render Frame)           `-- page.screenshot()
              \                                    /
               \                                  /
                v                                v
      [ Figma Reference PNG ]           [ Browser Render PNG ]
                \                                /
                 +-------------+----------------+
                               |
                               v
               [ Vision LLM (Claude 3.7 / GPT-4o) ]
                               |
            <System Prompt + Design Tokens Manifest>
                               |
                               v
               [ Structured JSON Defect Report ]
                 |-- Severity: CRITICAL | WARNING
                 |-- Category: SPACING | TYPOGRAPHY | COLOR
                 |-- BoundingBox: [ymin, xmin, ymax, xmax]
                 `-- Remediation: Tailwind Class Patch

import { chromium, type Browser, type Page } from 'playwright';
import { generateObject } from 'ai';
import { openai } from '@ai-sdk/openai';
import { z } from 'zod';
import * as fs from 'fs/promises';

// 1. Схема строгого структурированного отчета о дефектах
export const VisualDefectSchema = z.object({
  id: z.string().describe('Уникальный идентификатор дефекта'),
  category: z.enum(['LAYOUT_SPACING', 'TYPOGRAPHY', 'COLOR_MISMATCH', 'ELEMENT_MISSING', 'CONTAINER_OVERFLOW']),
  severity: z.enum(['CRITICAL', 'WARNING', 'INFO']),
  description: z.string().describe('Инженерное описание несоответствия макету'),
  expectedToken: z.string().describe('Ожидаемое значение токена или параметра из Figma'),
  actualValue: z.string().describe('Фактическое значение, обнаруженное в рендере'),
  remediationClass: z.string().describe('Рекомендуемый класс Tailwind CSS для устранения дефекта'),
  boundingBox: z.object({
    ymin: z.number().describe('Верхняя граница в процентах [0-100]'),
    xmin: z.number().describe('Левая граница в процентах [0-100]'),
    ymax: z.number().describe('Нижняя граница в процентах [0-100]'),
    xmax: z.number().describe('Правая граница в процентах [0-100]'),
  }),
});

export const AuditReportSchema = z.object({
  componentName: z.string(),
  isPixelPerfect: z.boolean(),
  matchScore: z.number().min(0).max(100).describe('Оценка визуального соответствия от 0 до 100%'),
  defects: z.array(VisualDefectSchema),
  architecturalSummary: z.string().describe('Краткое резюме для Pull Request'),
});

export type VisualAuditReport = z.infer<typeof AuditReportSchema>;

interface FigmaNodeTokens {
  layoutMode?: string;
  itemSpacing?: number;
  paddingLeft?: number;
  paddingRight?: number;
  paddingTop?: number;
  paddingBottom?: number;
  fontFamily?: string;
  fontSize?: number;
  lineHeightPx?: number;
  backgroundColorHex?: string;
}

/**
 * Клиент взаимодействия с Figma REST API
 */
export class FigmaClient {
  private readonly baseUrl = 'https://api.figma.com/v1';

  constructor(private readonly apiToken: string) {}

  /**
   * Экспорт растрового эталона конкретного фрейма
   */
  async exportFrameImage(fileKey: string, nodeId: string): Promise<Buffer> {
    const url = `${this.baseUrl}/images/${fileKey}?ids=${encodeURIComponent(nodeId)}&format=png&scale=2`;
    const response = await fetch(url, {
      headers: { 'X-Figma-Token': this.apiToken },
    });

    if (!response.ok) {
      throw new Error(`Figma Image Export API error: ${response.status} ${response.statusText}`);
    }

    const data = await response.json();
    const imageUrl = data.images[nodeId];
    if (!imageUrl) {
      throw new Error(`Node ${nodeId} was not found in Figma export response`);
    }

    const imageResponse = await fetch(imageUrl);
    const arrayBuffer = await imageResponse.arrayBuffer();
    return Buffer.from(arrayBuffer);
  }

  /**
   * Извлечение проектных токенов из дерева узла Figma
   */
  async extractNodeTokens(fileKey: string, nodeId: string): Promise<FigmaNodeTokens> {
    const url = `${this.baseUrl}/files/${fileKey}/nodes?ids=${encodeURIComponent(nodeId)}`;
    const response = await fetch(url, {
      headers: { 'X-Figma-Token': this.apiToken },
    });

    if (!response.ok) {
      throw new Error(`Figma Nodes API error: ${response.status} ${response.statusText}`);
    }

    const data = await response.json();
    const node = data.nodes[nodeId]?.document;
    if (!node) {
      throw new Error(`Node ${nodeId} document structure not found`);
    }

    return {
      layoutMode: node.layoutMode,
      itemSpacing: node.itemSpacing,
      paddingLeft: node.paddingLeft,
      paddingRight: node.paddingRight,
      paddingTop: node.paddingTop,
      paddingBottom: node.paddingBottom,
      fontFamily: node.style?.fontFamily,
      fontSize: node.style?.fontSize,
      lineHeightPx: node.style?.lineHeightPx,
      backgroundColorHex: node.backgroundColor
        ? this.rgbaToHex(node.backgroundColor)
        : undefined,
    };
  }

  private rgbaToHex(c: { r: number; g: number; b: number; a: number }): string {
    const toHex = (n: number) => Math.round(n * 255).toString(16).padStart(2, '0');
    return `#${toHex(c.r)}${toHex(c.g)}${toHex(c.b)}`;
  }
}

/**
 * Захват детерминированного скриншота в браузере через Playwright
 */
export async function captureBrowserComponent(params: {
  url: string;
  selector: string;
  viewportWidth: number;
  viewportHeight: number;
}): Promise<Buffer> {
  const browser: Browser = await chromium.launch({ headless: true });
  const context = await browser.newContext({
    viewport: { width: params.viewportWidth, height: params.viewportHeight },
    deviceScaleFactor: 2, // Эквивалент scale=2 в экспорте Figma
  });

  const page: Page = await context.newPage();

  try {
    await page.goto(params.url, { waitUntil: 'networkidle' });

    // Отключение анимаций и переходов для обеспечения стабильности рендера
    await page.addStyleTag({
      content: `
        *, *::before, *::after {
          animation-duration: 0s !important;
          animation-delay: 0s !important;
          transition-duration: 0s !important;
          transition-delay: 0s !important;
          caret-color: transparent !important;
        }
      `,
    });

    // Ожидание полной загрузки всех веб-шрифтов через Document API
    await page.evaluate(async () => {
      await document.fonts.ready;
    });

    const targetLocator = page.locator(params.selector);
    await targetLocator.waitFor({ state: 'visible', timeout: 5000 });

    const screenshotBuffer = await targetLocator.screenshot({
      type: 'png',
      omitBackground: false,
    });

    return screenshotBuffer;
  } finally {
    await context.close();
    await browser.close();
  }
}

/**
 * Главный контур когнитивного аудита через Vision LLM
 */
export async function runSemanticVisualAudit(params: {
  componentName: string;
  figmaImage: Buffer;
  browserImage: Buffer;
  designTokens: FigmaNodeTokens;
}): Promise<VisualAuditReport> {
  const figmaBase64 = params.figmaImage.toString('base64');
  const browserBase64 = params.browserImage.toString('base64');

  const systemInstruction = `
Вы — ведущий инженер по визуальному тестированию дизайн-систем.
Ваша задача — сопоставить эталонный макет из Figma и фактический рендер компонента в браузере.
Вам также предоставлены официальные дизайн-токены узла Figma.

Правила анализа:
1. Игнорируйте шум субпиксельного антиалиасинга шрифтов и естественные артефакты растрирования.
2. Фокусируйтесь на семантических отклонениях:
   - Несоответствие отступов (padding, gap, margins).
   - Ошибки типографики (font-size, font-weight, line-height).
   - Несоответствие цветов (фона, границ, текста) токенам палитры.
   - Смещение элементов сетки и поломка выравнивания.
3. Для каждого дефекта укажите нормализованный Bounding Box [0-100] на фактическом скриншоте браузера и предложите точный класс Tailwind CSS v4.
4. Вычислите matchScore: 100 - идеальное соответствие, <85 - блокирующий дефект.
  `.trim();

  const userPrompt = `
Компонент: ${params.componentName}
Эталонные дизайн-токены Figma:
${JSON.stringify(params.designTokens, null, 2)}

Изображение 1: Эталонный макет из Figma (Reference).
Изображение 2: Фактический рендер из Playwright (Actual).

Проведите детальный аудит и верните строго структурированный JSON.
  `.trim();

  const { object } = await generateObject({
    model: openai('gpt-4o'),
    schema: AuditReportSchema,
    messages: [
      { role: 'system', content: systemInstruction },
      {
        role: 'user',
        content: [
          { type: 'text', text: userPrompt },
          { type: 'image', image: `data:image/png;base64,${figmaBase64}` },
          { type: 'image', image: `data:image/png;base64,${browserBase64}` },
        ],
      },
    ],
  });

  return object;
}