---
name: visual-ui-auditor
description: "Master guide for multimodal vision UI auditing (Gemini 4 Argon/Pro Vision, Claude Sonnet 5.5 Vision, GPT-5.6 Sol Vision, Muse Wonder) against Anti-Slop Pillar 7, 1px crisp borders, 3-tier radius scales, tabular numerals, and WCAG 2.2 AA / Panduan utama audit visual UI berbasis vision multimodal."
author: "Roedy Rustam"
version: "4.4.2"
---

# Visual UI Auditor & Vision Quality Gate (2026 Sovereign Edition)

[English](#english) | [Bahasa Indonesia](#bahasa-indonesia)

---

<a name="english"></a>
## English

### Executive Directive & The Vision Imperative (2026 Shift)
Text-based code linters (ESLint, Biome, TypeScript) analyze syntax abstractly. They are completely blind to **spatial breathing room, optical balance, perceived elevation, color clashing, and visual degradation**. A React component can be 100% syntactically valid yet visually repulsive, violating brand aesthetics and suffering from lazy AI design tropes.

**The Visual UI Auditor** establishes an autonomous **Multimodal Vision Quality Gate**. By rendering components via Playwright or Headless Chrome, capturing high-DPI screenshots, and passing them to frontier vision models (Gemini 4 Argon/Pro Vision, Claude Sonnet 5.5 Vision, Muse Wonder), the auditor inspects rendered pixels against **Anti-Slop Pillar 7** and automatically synthesizes self-healing CSS diffs.

---

### Orchestration & Integration
- **Upstream Orchestrators**: Works under `brainstorming` and `zero-to-prod-orchestrator` (Phase 5/6 - Frontend Assembly & QA Gate).
- **Core Design & Anti-Slop Standards**: `anti-slop` (Pillar 7 Sovereign UI Craft), `design-system-architect`, `tailwind-expert`, `modern-css-native-expert`.
- **E2E Testing & Screen Capture**: `e2e-testing-expert`, `browser-automation-expert`, `screenshot-to-code-expert`.
- **A11y & Visual Compliance**: `accessibility-testing-expert`, `ui-ux-pro-max`, `hig`.

---

### Core Architectural Topologies

```
┌────────────────────────────────────────────────────────────────────────┐
│                   MULTIMODAL VISUAL UI AUDIT PIPELINE                  │
├────────────────────────────────────────────────────────────────────────┤
│ 1. Render Target UI Component (Playwright / Headless Browser)          │
│                                  │                                     │
│                                  ▼                                     │
│ 2. High-DPI Screenshot Capture (1080p Desktop & 390p Mobile)           │
│                                  │                                     │
│                                  ▼                                     │
│ 3. Frontier Vision LLM Audit (Gemini 4 Pro / Claude Sonnet 5.5 Vision) │
│    • Pillar 7 Visual Checklist  • 1px Crisp Borders  • Tabular-Nums    │
│    • 3-Tier Radius Compliance   • Ban Generic Slop Gradients / Orbs    │
│                                  │                                     │
│        ┌─────────────────────────┴─────────────────────────┐           │
│        ▼                                                   ▼           │
│  [Score >= 90: Passed]                               [Violations Found]│
│  Generate Audit Certificate                          Emit Exact Diff   │
│  Proceed to Production                               Patch Tailwind CSS│
│                                                            │           │
│                                                            ▼           │
│                                                  Re-render & Re-verify │
└────────────────────────────────────────────────────────────────────────┘
```

#### The 6 Non-Negotiable Visual Laws (Anti-Slop Pillar 7)
1. **1px Crisp Borders**: Elevated surfaces (dialogs, cards, dropdowns) must use crisp 1px borders (`border border-neutral-200/80 dark:border-neutral-800`). Heavy blurry box-shadows without borders are banned.
2. **Three-Tier Radius Contract**:
   - `rounded-lg` (8px) for buttons, inputs, badges.
   - `rounded-xl` (12px) for cards, dialog surfaces.
   - `rounded-2xl` (16px) for root modals, sheets.
   - `rounded-full` is strictly prohibited on standard rectangular buttons.
3. **Tabular Numerals (`tabular-nums`)**: Every monetary balance, price, counter, timestamp, and percentage MUST include `tabular-nums` to eliminate character jitter during live re-renders.
4. **Anti-Generic Gradients**: Purple-to-blue AI gradients (`from-purple-500 to-blue-500`) and glowing neon blur orbs are strictly prohibited.
5. **Mandatory 5-State Affordance**: Buttons and inputs must provide distinct visual styling for: `default`, `hover`, `active`, `focus-visible`, and `disabled`/`loading`.
6. **WCAG 2.2 AA Contrast Compliance**: Minimum 4.5:1 text contrast for body text and 3:1 for large headings across both Light and Dark themes.

---

### Production Implementation Blueprints

#### Blueprint 1: Multimodal Vision UI Audit Engine (`engine/visual-ui-auditor.ts`)
```typescript
import { generateObject } from 'ai';
import { google } from '@ai-sdk/google';
import { z } from 'zod';
import fs from 'node:fs/promises';

export const VisualViolationSchema = z.object({
  category: z.enum([
    'PILL_BUTTON_OBSESSION',
    'MISSING_1PX_BORDER',
    'MISSING_TABULAR_NUMS',
    'GENERIC_AI_GRADIENT',
    'CONTRAST_DEFECT',
    'SPATIAL_IMBALANCE',
  ]),
  description: z.string(),
  elementSelector: z.string(),
  suggestedTailwindFix: z.string(),
  severity: z.enum(['CRITICAL', 'WARNING', 'SUGGESTION']),
});

export const VisualAuditScorecardSchema = z.object({
  overallScore: z.number().min(0).max(100),
  pillar7Compliance: z.boolean(),
  wcagAaPassed: z.boolean(),
  summary: z.string(),
  violations: z.array(VisualViolationSchema),
  correctedCodePatch: z.string().optional(),
});

export type VisualAuditScorecard = z.infer<typeof VisualAuditScorecardSchema>;

export class VisualUiAuditor {
  public static async auditScreenshot(
    screenshotPath: string,
    componentSourceCode?: string
  ): Promise<VisualAuditScorecard> {
    const imageBuffer = await fs.readFile(screenshotPath);
    const base64Image = imageBuffer.toString('base64');

    const auditPrompt = [
      'You are the Master Visual UI Auditor enforcing Anti-Slop Pillar 7.',
      'Analyze the provided screenshot of the rendered web interface with pixel-level scrutiny.',
      '',
      'INSPECTION CRITERIA:',
      '1. Crisp 1px Borders: Ensure all cards, containers, and inputs have grounded 1px borders.',
      '2. Pill Button Ban: Flag any rectangular buttons utilizing rounded-full (pill addiction).',
      '3. Tabular Numerals: Ensure all prices, currency values, metrics, and dates use tabular-nums.',
      '4. Ban Generic AI Clichés: Flag any purple-blue gradients or blurry neon orbs.',
      '5. Spatial Hierarchy: Verify clean padding, balanced typography scales, and WCAG 2.2 AA contrast.',
      '',
      componentSourceCode ? `COMPONENT SOURCE CODE:\n${componentSourceCode}` : '',
    ].join('\n');

    // Invariant: If Gemini 4 Pro is unavailable/unprovisioned, gracefully fall back to Gemini 3.8 Flash
    try {
      const result = await generateObject({
        model: google('gemini-4-pro'),
        schema: VisualAuditScorecardSchema,
        messages: [
          {
            role: 'user',
            content: [
              { type: 'text', text: auditPrompt },
              {
                type: 'image',
                image: `data:image/png;base64,${base64Image}`,
              },
            ],
          },
        ],
      });

      return result.object;
    } catch (error) {
      console.warn('[VisualUiAuditor] Gemini 4 Pro unavailable. Falling back to Gemini 3.8 Flash:', error);
      const fallbackResult = await generateObject({
        model: google('gemini-3.8-flash'),
        schema: VisualAuditScorecardSchema,
        messages: [
          {
            role: 'user',
            content: [
              { type: 'text', text: auditPrompt },
              {
                type: 'image',
                image: `data:image/png;base64,${base64Image}`,
              },
            ],
          },
        ],
      });

      return fallbackResult.object;
    }
  }
}
```

---

#### Blueprint 2: Playwright Automated Visual Audit Test (`tests/visual-audit.spec.ts`)
```typescript
import { test, expect } from '@playwright/test';
import path from 'node:path';
import { VisualUiAuditor } from '../engine/visual-ui-auditor';

test.describe('Automated Visual UI Quality Gate', () => {
  test('audit dashboard against Anti-Slop Pillar 7 standards', async ({ page }) => {
    await page.goto('/dashboard');
    await page.waitForLoadState('networkidle');

    // 1. Capture High-DPI Screenshot
    const screenshotPath = path.resolve('test-results/dashboard-audit.png');
    await page.screenshot({ path: screenshotPath, fullPage: true });

    // 2. Execute Multimodal Vision Audit
    const scorecard = await VisualUiAuditor.auditScreenshot(screenshotPath);

    console.log(`[Visual Audit Score]: ${scorecard.overallScore}/100`);
    if (scorecard.violations.length > 0) {
      console.table(scorecard.violations);
    }

    // 3. Strict Quality Threshold
    expect(scorecard.overallScore).toBeGreaterThanOrEqual(90);
    expect(scorecard.pillar7Compliance).toBe(true);
  });
});
```

### Sovereign Execution, Token Efficiency & Invariants
| Dimension | Sovereign Mandate & Deterministic Contract |
| :--- | :--- |
| **Frontier Model Cascade** | Medium / High (`Gemini 4 Argon`, `Claude Sonnet 5.5 High`, `Muse Wonder High`, `Composer 2.5 Fast`) |
| **Availability Fallback** | `Gemini 4 Argon/Pro` -> `Gemini 3.8 Flash`; `Claude Opus 5.5` -> `Claude Opus 4.6` (Zero unhandled missing-model errors) |
| **KV-Cache & Token Protocol** | Pin static instructions & schemas at prompt prefix (`kv-cache-prefix-optimizer`); pass surgical `CONTEXT_MAP.md` slices (<250 tokens/call) during Swarm Fan-Out |
| **SaaT CLI & MCP Dispatch** | CLI: `vibes skill exec visual-ui-auditor <audit\|eval\|verify\|generate\|blueprint>` / MCP: `vibes_skill_dispatch`, `vibes_visual_audit`, `vibes_ast_query`, `vibes_verify_gate` |
| **NFR & Anti-Slop Invariants** | LCP < 1.8s, INP < 100ms, CLS < 0.05, 1px crisp borders, 3-tier radius (6px/8px/12px), `tabular-nums`, 5-state interactive contract; 100% complete zero-placeholder output verified via `node scripts/check-anti-slop.js --strict` |

---


---

<a name="bahasa-indonesia"></a>
## Bahasa Indonesia

### Direktif Eksekutif & Kebutuhan Audit Visual Multimodal (Pergeseran 2026)
Linter kode berbasis teks (ESLint, Biome, TypeScript) hanya memeriksa sintaksis secara abstrak. Mereka sama sekali buta terhadap **keseimbangan optik, pernapasan tata letak (*spatial breathing room*), elevasi permukaan, dan tabrakan warna**. Sebuah komponen React bisa saja lolos 100% dari galat kompilasi namun secara visual terlihat buruk dan dipenuhi klise AI murahan.

**Visual UI Auditor** menyediakan **Gerbang Kualitas Visual Multimodal** otonom. Dengan merender komponen melalui Playwright, menangkap tangkapan layar beresolusi tinggi, dan memeriksanya menggunakan model vision frontier (Gemini 4 Argon/Pro Vision, Claude Sonnet 5.5 Vision, Muse Wonder), auditor memeriksa setiap piksel terhadap **Pilar 7 Anti-Slop** serta menghasilkan rekomendasi perbaikan CSS secara otomatis.

---

### Integrasi Orkestrasi
- **Orkestrator Hulu**: Beroperasi di bawah arahan `brainstorming` dan `zero-to-prod-orchestrator` (Fase 5/6 - Perakitan Frontend & QA).
- **Standar Desain & Anti-Slop**: `anti-slop` (Pilar 7 Kerajinan UI Berdaulat), `design-system-architect`, `tailwind-expert`, `modern-css-native-expert`.
- **Pengujian E2E & Tangkapan Layar**: `e2e-testing-expert`, `browser-automation-expert`, `screenshot-to-code-expert`.
- **Aksesibilitas & Kepatuhan Visual**: `accessibility-testing-expert`, `ui-ux-pro-max`, `hig`.

---

### 6 Aturan Mutlak Visual (Pilar 7 Anti-Slop)
1. **Border 1px Tegas**: Seluruh kartu, kontainer, dan input wajib memiliki border 1px yang tegas (`border border-neutral-200/80 dark:border-neutral-800`). Bayangan kabur tebal tanpa border dilarang keras.
2. **Skala Radius 3-Tingkat**: `rounded-lg` (8px) untuk tombol/input, `rounded-xl` (12px) untuk kartu, dan `rounded-2xl` (16px) untuk modal utama. Dilarang memakai tombol pil (`rounded-full`) pada tombol aksi standar.
3. **Angka Tabular Wajib (`tabular-nums`)**: Seluruh nilai moneter, harga, saldo, kuantitas, dan tanggal wajib menerapkan `tabular-nums` untuk mencegah pergeseran teks saat data diperbarui.
4. **Larangan Gradien Klise AI**: Gradien ungu-ke-biru AI dan orb neon blur di belakang kartu dilarang keras.
5. **Kontrak 5-State Interaktif Wajib**: Elemen tombol dan kontrol wajib menyediakan visual untuk state: `default`, `hover`, `active`, `focus-visible`, dan `disabled`/`loading`.
6. **Kepatuhan Kontras WCAG 2.2 AA**: Rasio kontras teks minimal 4.5:1 untuk teks biasa dan 3:1 untuk judul besar pada mode terang maupun gelap.

---

### Topologi Arsitektur Audit Visual

```
┌────────────────────────────────────────────────────────────────────────┐
│               ALUR PIPA AUDIT UI VISUAL MULTIMODAL                     │
├────────────────────────────────────────────────────────────────────────┤
│ 1. Render Komponen UI Target (Playwright / Headless Browser)           │
│                                  │                                     │
│                                  ▼                                     │
│ 2. Tangkap Screenshot High-DPI (1080p Desktop & 390p Mobile)           │
│                                  │                                     │
│                                  ▼                                     │
│ 3. Audit Model Vision Frontier (Gemini 4 Argon/Pro / Claude Sonnet)    │
│    • Ceklis Visual Pilar 7      • Border 1px Tegas    • Tabular-Nums   │
│    • Skala Radius 3-Tingkat     • Larangan Gradien AI Klise & Neon Orb │
│                                  │                                     │
│        ┌─────────────────────────┴─────────────────────────┐           │
│        ▼                                                   ▼           │
│  [Skor >= 90: Lolos Audit]                           [Pelanggaran Ada] │
│  Terbitkan Sertifikat Audit                          Hasilkan Patch CSS│
│  Lanjutkan ke Produksi                               Terapkan Tailwind │
│                                                            │           │
│                                                            ▼           │
│                                                   Render Ulang & Uji   │
└────────────────────────────────────────────────────────────────────────┘
```

---

### Blueprint Implementasi Produksi

#### Blueprint 1: Mesin Audit UI Multimodal (`engine/visual-ui-auditor.ts`)
```typescript
import { generateObject } from 'ai';
import { google } from '@ai-sdk/google';
import { z } from 'zod';
import fs from 'node:fs/promises';

export const SkemaPelanggaranVisual = z.object({
  kategori: z.enum([
    'TOMBOL_PIL_BERLEBIHAN',
    'BORDER_1PX_HILANG',
    'ANGKA_TABULAR_HILANG',
    'GRADIEN_AI_KLISE',
    'CACAT_KONTRAS',
    'KETIDAKSEIMBANGAN_SPASIAL',
  ]),
  deskripsi: z.string(),
  selektorElemen: z.string(),
  saranPerbaikanTailwind: z.string(),
  tingkatKeparahan: z.enum(['KRITIS', 'PERINGATAN', 'SARAN']),
});

export const SkemaKartuSkorVisual = z.object({
  skorKeseluruhan: z.number().min(0).max(100),
  kepatuhanPilar7: z.boolean(),
  lolosWcagAa: z.boolean(),
  ringkasan: z.string(),
  pelanggaran: z.array(SkemaPelanggaranVisual),
  patchKodePerbaikan: z.string().optional(),
});

export type KartuSkorVisual = z.infer<typeof SkemaKartuSkorVisual>;

export class VisualUiAuditorId {
  public static async auditScreenshot(
    jalurScreenshot: string,
    kodeSumberKomponen?: string
  ): Promise<KartuSkorVisual> {
    const bufferGambar = await fs.readFile(jalurScreenshot);
    const gambarBase64 = bufferGambar.toString('base64');

    const promptAudit = [
      'Anda adalah Master Visual UI Auditor yang menegakkan Anti-Slop Pilar 7.',
      'Analisis screenshot antarmuka web yang diberikan dengan ketelitian piksel tinggi.',
      '',
      'KRITERIA PEMERIKSAAN:',
      '1. Border 1px Tegas: Pastikan seluruh kartu dan kontainer memiliki border 1px yang nyata.',
      '2. Larangan Tombol Pil: Tandai tombol persegi panjang yang memakai rounded-full.',
      '3. Angka Tabular: Pastikan harga, kuantitas, dan tanggal menggunakan tabular-nums.',
      '4. Larangan Klise AI: Tandai gradien ungu-biru murah dan efek neon blur orb.',
      '5. Hierarki Spasial: Periksa keselarasan padding, tipografi, dan kontras WCAG 2.2 AA.',
      '',
      kodeSumberKomponen ? `KODE SUMBER KOMPONEN:\n${kodeSumberKomponen}` : '',
    ].join('\n');

    // Invarian: Jika Gemini 4 Pro belum tersedia/unprovisioned, alihkan ke Gemini 3.8 Flash secara otomatis
    try {
      const hasil = await generateObject({
        model: google('gemini-4-pro'),
        schema: SkemaKartuSkorVisual,
        messages: [
          {
            role: 'user',
            content: [
              { type: 'text', text: promptAudit },
              {
                type: 'image',
                image: `data:image/png;base64,${gambarBase64}`,
              },
            ],
          },
        ],
      });

      return hasil.object;
    } catch (kesalahan) {
      console.warn('[VisualUiAuditorId] Gemini 4 Pro tidak tersedia. Mengalihkan ke Gemini 3.8 Flash:', kesalahan);
      const hasilCadangan = await generateObject({
        model: google('gemini-3.8-flash'),
        schema: SkemaKartuSkorVisual,
        messages: [
          {
            role: 'user',
            content: [
              { type: 'text', text: promptAudit },
              {
                type: 'image',
                image: `data:image/png;base64,${gambarBase64}`,
              },
            ],
          },
        ],
      });

      return hasilCadangan.object;
    }
  }
}
```

---

### Panduan Praktik Terbaik

1. **Jadikan Gerbang Kualitas Otomatis**: Integrasikan pengujian tangkapan layar Playwright ke alur CI/CD agar setiap PR yang memuat perubahan visual diverifikasi sebelum rilis.
2. **Prioritaskan Angka Tabular**: Selalu sertakan utilitas `tabular-nums` pada komponen tabel finansial, dashboard transaksi, dan penghitung mundur.
3. **Patuhi Batas Skor Minimum 90**: Tolak kode yang memiliki skor visual < 90 atau melanggar aturan border 1px dan larangan tombol pil.
4. **Protokol Fallback Ketersediaan**: Jika Gemini 4 Pro Vision belum terpasang atau mengalami pembatasan kuota, audit visual dialihkan secara otomatis ke Gemini 3.8 Flash Vision tanpa menghentikan pipeline CI.

### Matriks Eksekusi Berdaulat, Efisiensi Token & Invarian
| Dimensi | Mandat Berdaulat & Kontrak Deterministik |
| :--- | :--- |
| **Kaskade Model Frontier** | Medium / High (`Gemini 4 Argon`, `Claude Sonnet 5.5 High`, `Muse Wonder High`, `Composer 2.5 Fast`) |
| **Invarian Fallback Ketersediaan** | `Gemini 4 Argon/Pro` -> `Gemini 3.8 Flash`; `Claude Opus 5.5` -> `Claude Opus 4.6` (Bebas gagal saat model belum tersedia/kuota penuh) |
| **Protokol Hemat Token & KV-Cache** | Kunci instruksi & skema statis di prefix awal (`kv-cache-prefix-optimizer`); kirim potongan `CONTEXT_MAP.md` (<250 token/panggilan) saat Fan-Out |
| **Eksekusi SaaT CLI & MCP** | CLI: `vibes skill exec visual-ui-auditor <audit\|eval\|verify\|generate\|blueprint>` / MCP: `vibes_skill_dispatch`, `vibes_visual_audit`, `vibes_ast_query`, `vibes_verify_gate` |
| **Invarian NFR & Anti-Slop** | LCP < 1.8s, INP < 100ms, CLS < 0.05, border tegas 1px, radius 3-tier (6px/8px/12px), `tabular-nums`, kontrak interaktif 5-state; kode 100% tuntas tanpa placeholder diverifikasi melalui `node scripts/check-anti-slop.js --strict` |