Skip to main content

Agentic UI Development Standards

Date: 2026-04-07 Status: Active

This document establishes the UI development loop for AI agents working within the SecurityV0 platform, focusing on moving from blind code generation to deterministic visual validation.

The Observe-Think-Act Loop for UI​

When Claude Code or any secondary agent modifies UI code within sv0-platform, the following strict validation workflow must be adhered to:

1. No Blind Fixes​

Agents must never assume a CSS or React structure fix is visually correct simply because it "looks right" in code.

2. Required Validation Step​

After pushing UI changes, agents must:

  • Start the UI dev server in headless mode.
  • Use the Playwright validation scripts (npm run qa:visual or tsx scripts/visual-validation.ts) to extract exact getComputedStyle() metrics.
  • Compare these numerical readouts against the precise specs extracted from the Figma MCP.

3. Strict Design Tokens​

Arbitrary CSS/Tailwind values (e.g., ml-[17px], text-[#FF0000]) are blocked at the linting level. Agents must utilize predefined design system tokens (e.g. ml-4, text-destructive).

4. CI Visual Regression​

Any UI PR will be blocked/alerted by the visual regression Playwright Action. Diffs generated by this pipeline indicate the change has drifted from the component baseline. Agents must download the playwright-report bounding box artifact and read it before proposing another fix.