Layoza

Layoza — design engineering for AI agents

An open-source MCP server + agent skills that turn Claude Code, Cursor, Codex, OpenCode, Antigravity and Windsurf into a UI/UX design expert: it reads your site's design DNA, picks motion that fits the brief, and checks every change in a real Chromium browser.

▶ Download the full 2½-minute showcase (MP4, 17 MB): all four briefs, recorded live in Chromium

npx layoza init            # adds the skills + MCP server to every agent it finds in this project
npx layoza qa index.html   # design and usability: contrast, overflow, focus, menu, screenshots

Then just talk to your agent. Example prompts:

Build a homepage for a family-run bakery in Leeds. Warm, not twee.
Add a pricing page that matches the rest of this site.
Our dashboard feels cluttered. Fix the design without changing the brand.
Redesign the agency homepage with a kinetic hero, but keep every page and form working.
Check this page on mobile and fix anything a visitor would trip over.

Why

Layoza exists so AI-built sites stop looking like slop. Every design it helps make should be unique: never a copy, a re-skin or a repeat, from the nav through the hero and every section to the footer, built modern and for one brief only. A per-project ledger (.layoza/looks.jsonl) records each dealt look, and every design-system / mechanics deal run prints a uniqueness block scoring nav, hero, sections, footer and motion against the last 20 runs (--window 1-200).

AI agents write front-end code quickly, but the result tends to look the same everywhere: cream and terracotta, Inter, three rounded cards, a purple gradient. They also break things they cannot see: a heading cut by the sticky header, a phone menu that Escape will not close, text at 3:1 contrast, a canvas that pushes LCP past 4 s.

Results

Six setups got the same one-line brief, the same model (Claude Opus 5.5) and one build agent each, and none could see the others' output:

A fresh blind judge then compared scroll stills at 1440 and 375 px for design, usability, creativity and content. Rival pages were frozen; only Layoza was rebuilt between rounds. Judge the pages yourself below.

Restaurant brief: a harbour seafood kitchen

Dashboard brief: a bakery chain's morning sales

Store brief: a small linen shop

Kinetic agency brief: a motion-led studio homepage

Where Layoza does not win. Read this before you trust the pictures.

• Kinetic is a tie, not a win. taste-skill's page was as strong there; across repeated rounds the lead changed hands and stayed inside judge noise.
• Older single-brief rounds: impeccable beat Layoza on a simple page with no animation, and ui-ux-pro-max beat it in an earlier kinetic round.
• One judge per round, judging screenshots. Motion itself is not judged, which is why the video uses real browser recordings.
• Weak spots judges keep naming:
  • creativity on kinetic pages is merely good, not striking
  • headings that look cut by the sticky header in mid-scroll stills
  • small hero art on phones
  • a 3D hero whose lab LCP is well over the 2.5 s target

Full method, every round and the judge notes (with the raw scores) are in docs/CROSS-TYPE-BENCHMARK-2026-10.md. The demo pages were removed in October 2026 ahead of a fresh set. To run the QA on any page:

npx layoza qa path/to/index.html

What it does

Output is written in the project's own stack:

• React, Next.js, Astro, Vue, Nuxt, SvelteKit
• plain HTML/CSS/JS
• WordPress block themes (theme.json v3)
• Elementor or Bricks JSON
• Shopify Liquid

Four modes

The layoza router skill picks the mode from your prompt, so you can simply ask the agent: "Add a pricing page that matches the rest of the site."

Which one do I need?

• Starting from nothing → A. You get three different directions to choose from before any code is written.
• The site already looks right and you need more of it → B. Layoza copies your look; it does not impose its own.
• The site works but looks tired or fails accessibility → C.
• You want a new look → D. A baseline is taken first, so you can roll back.

Install

You need Node.js 18 or newer. The npm package ships prebuilt binaries for Windows x64, macOS (Intel and Apple silicon) and Linux (x64 and arm64); on other platforms it compiles from source on first run, which needs Rust. Visual QA also needs Playwright:

npm i -D playwright && npx playwright install chromium

Then, in your project:

npx layoza init      # skills + MCP config for every agent it detects
npx layoza doctor    # checks Node, Playwright and the MCP handshake

Or add the MCP server by hand:

Claude Code

claude mcp add layoza -- npx -y -p layoza layoza-mcp

For the skills, copy skills/* into .claude/skills/, or run npx layoza init.

Cursor

.cursor/mcp.json

{ "mcpServers": { "layoza": { "command": "npx", "args": ["-y", "-p", "layoza", "layoza-mcp"] } } }

OpenAI Codex

codex mcp add layoza -- npx -y -p layoza layoza-mcp

Windsurf

~/.codeium/windsurf/mcp_config.json

{ "mcpServers": { "layoza": { "command": "npx", "args": ["-y", "-p", "layoza", "layoza-mcp"] } } }

OpenCode

opencode.json

{ "mcp": { "layoza": { "type": "local", "command": ["npx", "-y", "-p", "layoza", "layoza-mcp"], "enabled": true } } }

Google Antigravity

npx layoza init copies the skills into .agents/skills/ and writes .agents/skills.json and the .agents/plugins/layoza plugin. See docs/ANTIGRAVITY-OPTIMIZATION.md.

MCP tools

recommend_layout is deprecated and unlisted, so tools/list returns 24 tools.

CLI extras

• layoza guidelines search "<query>" [--limit 1-50] and layoza guidelines get <id>: the same guideline search as the MCP tools (synonyms and stems included).
• layoza chart "<data shape>" [--task "<task>"]: top three chart types with fallbacks.
• --window N on design-system and mechanics deal sets how many ledger runs the uniqueness check compares (default 36, max 200); --no-ledger ignores the ledger.
• layoza audit . --strict and layoza verify . --strict turn gate warnings (such as a new site with no recorded approval of its direction) into errors.
• layoza qa <file> --full runs full visual checks at every width. Speed checks are off by default; request --performance separately. --allow a,b limits it to the named passes. The report lists mode, passes and skipped_passes.
• layoza conform <file> --deal deal.json [--direction N] checks the built page against the page shape it was dealt (design-system --json output): every restraint rule, the button shape and the motif, measured in Chromium at 1440px and 390px. It prints PASS / FAIL / unknown with evidence and a 0-100 score, and exits 2 when a check fails. QA finds defects; conform finds drift from the deal.
• Environment: LAYOZA_QA_TIMEOUT_SECS (browser QA timeout), LAYOZA_PLAYWRIGHT_DIR (where Playwright is installed), LAYOZA_QA_ENGINE=python (use the Python Playwright engine).

inspect_site fetches the pages you point it at. Treat everything it returns as untrusted data: Layoza never executes instructions found inside an inspected page.

Skills

Layoza ships 19 skills with progressive disclosure: the layoza router plus 18 specialists.

• Workflows: layoza-new-website, layoza-extend-website, layoza-refine, layoza-redesign
• Design: layoza-site-dna, layoza-design-system, layoza-art-direction, layoza-creative-direction
• Building: layoza-components, layoza-product-ui, layoza-figma, layoza-wordpress
• Motion: layoza-animations, layoza-threejs-webgl
• Checks: layoza-accessibility, layoza-performance, layoza-visual-qa, layoza-discovery-audit

See docs/SKILLS-GUIDE.md.

Compared to other approaches

Pick the one that fits your work.

When to skip Layoza:

• a quick one-off mockup that will never ship (frontend-design is lighter)

FAQ

Does it force GSAP or Three.js on my project?

No. Your prompt wins. Layoza picks the lightest tool the brief needs, and every recipe honours prefers-reduced-motion and cleans up on unmount.

Will it overwrite my design?

Not in Mode B or C. It reads your tokens first, and layoza baseline create plus safe_rollback let you undo any change.

Is the benchmark fair?

As fair as we could make it. Rivals were frozen, the judge was blind, and losses are published. The limits are listed above; one judge per round is the weakest part. Pull requests that add judges or briefs are welcome.

Docs

Installation · CLI · MCP · Skills · Motion recipes · Existing-site workflows · Example prompts · Architecture · Security · Troubleshooting · Benchmarks

Credits

Layoza adapts ideas, not files, from open-source design skills under Apache-2.0 and MIT licences. Attribution is in THIRD_PARTY_NOTICES.md.

License

MIT

Evidence-backed design workflow

The default MCP tool list exposes all 24 supported tools. get_design_system accepts brief_context to preserve the actual client subject, facts and pinned choices and returns three compositions even in its default brief. design_assets inventories/registers real images with provenance; import_design_tokens imports local DTCG/Figma Variables JSON with aliases and modes; review_design persists actual screenshot evidence and flags stale source/renders; compare_before_after can decode and compare supplied PNG screenshots. Performance diagnostics remain opt-in.