DEV Community

VibeFoundry
VibeFoundry

Posted on AI-assisted

Why "npm run build" is not QA for AI-generated frontend code (8 browser traps and 72 UI craft rules)

AI coding agents are very good at making npm run build go green. They are much worse at noticing that the page they just built is broken in a real browser, or that it looks like every other AI-generated page on the internet.

I build and maintain three small open-source tools for this problem, so a disclosure first: everything below is about my own projects, and I wrote this with AI assistance. All three are MIT licensed and free.

What a green build actually tells you

tsc and npm run build answer one question: does this code compile and bundle? They say nothing about what happens when a browser runs it. In my experience, agent-written frontends fail in two ways that a compiler cannot see.

1. Runtime browser regressions.

  • React hydration mismatches, where the server HTML and the first client render disagree.
  • Horizontal overflow on a 375px wide phone viewport.
  • Touch targets smaller than 44x44px.
  • Text that is readable in light mode and nearly invisible in dark mode.
  • API calls that return a silent 500 while the UI renders an empty state, so nothing looks "broken" in the code.

2. Generic "AI slop" defaults.

Purple to indigo gradients, three centered feature cards, cards nested inside cards, arbitrary spacing values that break the scale, hardcoded colors instead of tokens, and marketing copy like "Unleash the power". None of it is a bug. All of it makes the product look interchangeable.

The agent says "done" because the only check it ran was the build. So I wanted to give it two more checks that it can run itself, plus a third one for security.

ghost-qa: a headless browser that checks what the browser experienced

ghost-qa launches headless Playwright Chromium against your running dev server, crawls the internal routes, and records what actually happened. It checks every page at three viewports (Desktop 1440x900, Tablet 768x1024, Mobile 375x812) in both light and dark color schemes.

npm run dev
npx playwright install chromium   # one-time
npx -y ghost-qa@latest test http://localhost:3000
Enter fullscreen mode Exit fullscreen mode

The engine is organized as eight traps, each one watching a different failure class:

  1. Console and framework runtime: uncaught exceptions, unhandled promise rejections, React hydration mismatches, duplicate key warnings and CSP violations.
  2. Network and asset integrity: 5xx and 4xx responses, failed fetches, CORS failures, broken images and oversized assets.
  3. Layout and geometry: horizontal overflow (with the offending elements named), overlapping interactive elements, touch targets under 44x44px and zero-size controls.
  4. Accessibility and keyboard focus: missing accessible names, images without alt text, inputs without labels, computed contrast ratios and simulated Tab order.
  5. Performance: Core Web Vitals estimates (TTFB, FCP, LCP, CLS), slow loads, large payloads and excessive DOM size.
  6. Links and interactive integrity: placeholder links, dead anchors and buttons inside forms with no type.
  7. SEO and metadata: title, description, canonical, OpenGraph tags and duplicate ids in the live DOM.
  8. Theme parity: every page is also rendered under dark and light emulation, and computed contrast is re-evaluated per scheme, so dark-on-dark text gets caught.

Each trap starts at 100 and loses points per finding, and the overall result is a QA Health Score with a letter grade. The part that matters for agents is the output: a structured report with exact selectors and bounding boxes, plus a patch prompt the agent can act on. ghost-qa compare before.json after.json then diffs two runs, so the agent can prove a fix worked without introducing regressions.

It also runs as an MCP server, so Claude Code, Cursor or Cline can call it as a tool instead of shelling out.

Some limits, because I would rather you know them: it is meant for localhost dev servers, its interaction runner only clicks ordinary controls and refuses destructive-looking ones (that is a word list, not magic), it is not a full WCAG audit, and it does not replace your own test suite.

unslop: 72 deterministic rules for UI craft

The second failure mode is harder to test, because "looks generic" is a taste problem. unslop takes the position that a lot of that taste can be written down as rules and checked deterministically.

npx -y unslop-mcp audit .
npx -y unslop-mcp refactor-plan . --report UNSLOP-REPORT.md
Enter fullscreen mode Exit fullscreen mode

It audits 72 rules across seven pillars: color and contrast, typography, layout and spatial rhythm, surface and elevation, copy, interaction and motion, and theme and token architecture. Every finding has a file:line:column location, and the result is a 0 to 100 craft score with a per-pillar scorecard. You can gate CI or an agent loop with --fail-under 95.

The refactor plan turns findings into concrete replacements, for example from-purple-500 via-pink-500 to-indigo-500 into a surface token, p-[13px] into a spacing token, and transition-all into transition-colors motion-reduce:transition-none.

It also installs one of ten built-in design archetypes (or extracts design DNA from CSS or a URL) and exports the tokens as a Tailwind v4 @theme block, a Tailwind v3 config fragment, plain CSS custom properties, or W3C design tokens JSON, so the agent builds on a token contract instead of inventing colors per component.

The honest limit: this is static analysis. It checks the source, not the rendered page, and the rules encode my own opinions about craft. A good score is not a good design, which is why the two tools are meant to be used together.

vibe-shield: the static security check

The third tool covers the part neither of the above looks at. vibe-shield is a static security scanner for AI-written code: server secrets behind NEXT_PUBLIC_ variables, mutation routes without a session check, IDOR shapes, tables without row level security, and poisoned MCP or skill configuration.

npx -y @vibefoundry/vibe-shield@latest scan .
Enter fullscreen mode Exit fullscreen mode

It is heuristic, so a clean score is not a security guarantee, but it catches the exact shapes agents tend to produce.

Putting them together

The loop I use with an agent is simple: after it writes a feature, it runs the static checks (unslop audit, vibe-shield scan), starts the dev server, runs ghost-qa test, fixes what comes back, and only then reports completion. Each tool exits non-zero on blocking findings, so "done" becomes an exit code instead of an opinion. init for each tool installs the instructions and MCP config for Claude Code, Cursor, Codex, Windsurf, Copilot, Cline and Zed.

The repos

GitHub logo avivgerz-hue / ghost-qa

Autonomous headless browser QA & self-healing verification loop for AI coding agents

πŸ‘» ghost-qa

Autonomous headless browser QA & self-healing verification loop for coding agents. v2.1.1 β€” the 8-Trap Deep Browser Inspection Engine: 3 viewports Γ— light/dark, QA Health Score (A+…F), interactive HTML dashboard, and regression diffing.

CI npm version npm downloads License: MIT Node >= 20 Powered by Playwright

⭐ If this tool helps your AI coding workflow, please give this repository a Star! It helps more developers discover the project.

🧰 The VibeFoundry Agent Suite

One command each β€” star all three and keep the whole suite free & maintained:

  • 🎨 unslop β€” UI Design DNA & Anti-Slop Engine (npx -y unslop-mcp@latest init)
  • πŸ›‘οΈ vibe-shield β€” Security Scanner for AI Code (npx -y @vibefoundry/vibe-shield@latest scan .)
  • πŸ‘» ghost-qa β€” Autonomous Headless Browser QA (npx -y ghost-qa@latest test http://localhost:3000)

Live Terminal Demo

npx -y ghost-qa@latest test http://localhost:3000
Enter fullscreen mode Exit fullscreen mode

ghost-qa terminal preview

Coding agents (Claude Code, Codex, Cursor, Windsurf) write code blind β€” then declare victory while the actual browser has React hydration errors, broken buttons…

GitHub logo avivgerz-hue / unslop

Studio-grade UI design systems, Design DNA extractor & Anti-Slop MCP server for AI coding agents (Claude Code, Codex, Cursor, Windsurf).

unslop v2.1.1

⭐ If this tool helps your AI coding workflow, please give this repository a Star! It helps more developers discover the project.

VibeFoundry Agent Suite: 🎨 unslop β€” UI Design DNA & Anti-Slop Engine (npx -y unslop-mcp@latest init) Β· πŸ›‘οΈ vibe-shield β€” Security Scanner for AI Code (npx -y @vibefoundry/vibe-shield@latest scan .) Β· πŸ‘» ghost-qa β€” Autonomous Headless Browser QA (npx -y ghost-qa@latest test http://localhost:3000)

npm version npm downloads CI Node.js 20.19+ MIT license

Live Terminal Demo

npx -y unslop-mcp@latest init
Enter fullscreen mode Exit fullscreen mode

Your agent can write the code. unslop gives it a measurable design engineering protocol.

unslop preview

unslop is a zero-runtime-dependency UI/UX Design Engineering CLI, native MCP Server, and AI Agent Skill. It audits 72 rules across seven design craft pillars, installs ten studio-grade archetypes, extracts Design DNA, exports four token formats, and turns every finding into an exact, prioritized transformation blueprint for JSX/TSX, HTML, Vue, Svelte, CSS, and Tailwind codebases.

Works natively with Claude…

GitHub logo avivgerz-hue / vibe-shield

92-rule static security scanner, Agent Skill & MCP server for AI-generated Next.js, Supabase & TypeScript apps (OWASP Top 10:2025 + MCP/Skill poisoning).

πŸ›‘οΈ vibe-shield

The security gate for AI-written code. Find exposed secrets, unguarded routes and missing RLS before you ship.

⭐ If this tool helps your AI coding workflow, please give this repository a Star! It helps more developers discover the project.

npm version npm downloads CI node license zero dependencies rules self-scan

Live Terminal Demo

npx -y @vibefoundry/vibe-shield@latest scan .
Enter fullscreen mode Exit fullscreen mode

Illustrative two-file scan; fixes are applied manually. Results vary by project. A clean score is not a security guarantee.

VibeFoundry Agent Suite

  • 🎨 unslop β€” UI Design DNA & Anti-Slop Engine Β· npx -y unslop-mcp@latest init
  • πŸ›‘οΈ vibe-shield β€” Security Scanner for AI Code Β· npx -y @vibefoundry/vibe-shield@latest scan .
  • πŸ‘» ghost-qa β€” Autonomous Headless Browser QA Β· npx -y ghost-qa@latest test http://localhost:3000

vibe-shield is a static security scanner plus an Agent Skill that helps Claude Code, Codex, Cursor and Windsurf audit before they say β€œdone”.


v2.0.0: eight defensive vectors

The v2 catalogue covers client exposure; auth and route protection; database/RLS; AI and…

If you try any of them on a real project, I would especially like to hear about false positives. Those are the most useful bug reports I can get.

Top comments (0)