screenwright

The wedge is the eyes. Generating UI is solved; verifying the render against a brand + accessibility bar, in a loop is not. screenwright paints one self-contained HTML surface, then renders → screenshots → audits → fixes until it passes, and hands the result back. It does the painting and verification; it does not ship a runtime or convert to a framework — that's the host's job.

Agents write frontend blind: the markup looks right but misses the small obvious things — a 4px misalignment, a missing focus ring, text that overflows on a long name, a mobile layout that never got built. screenwright gives the agent eyes.

Two stacked gates, asymmetric:

• axe a11y — machine, deterministic, always blocks. The defensible core.
• Visual fidelity — judgment from the screenshot. Blocks only when a reference image exists; advisory otherwise (no reference = no ground truth to gate on).

Phase 0 — Capability gate (run first)

screenwright renders through the Playwright MCP. It is a hard dependency — gate on its presence, not on which agent you are (capability-gated, not vendor-gated).

• If Playwright MCP tools (browser_navigate, browser_run_code_unsafe, browser_take_screenshot) are not available → stop. Tell the user screenwright needs the Playwright MCP, give install instructions (claude mcp add playwright npx '@playwright/mcp@latest' or the host's equivalent), and do not attempt a degraded render. A skill that paints without seeing is the problem it exists to solve.
• If available → proceed.

Then confirm this is a screenwright job (a UI surface to build/fix with the render checked), not one of the anti-triggers in the frontmatter. When in doubt, one question.

Phase 1 — Intake

Classify the mode from what the user gave you, gather the brief, ask only what you can't infer. Full classifier + the gap-question set: references/intake.md.

Match-vs-fix is load-bearing (it flips the verification path). If an image is provided but intent is ambiguous, ask exactly one question. Default lean: a polished mock → match; a rough/broken render described with problems → fix.

Mode V is read-only. Use it when another skill authored the surface and screenwright only checks the render. It never edits the surface and never writes a DESIGN.md: Phase 2 reads the spec path it was given (no bootstrap), Phases 3 and 5 are skipped, and Phase 4 runs once over a fixed matrix — axe in light and dark (page.emulateMedia({ colorScheme })), desktop and phone width, the 320px reflow pass, and print (page.emulateMedia({ media: 'print' })). Phase 6 returns the mode V output contract in references/playwright-loop.md § Mode V — never HTML; every finding goes back to the author to fix. A URL is rendered with browser_navigate instead of setContent. 0 axe violations is necessary, not sufficient — the screenshots are part of the result. Exact steps and the sub-agent brief: references/playwright-loop.md § Mode V; manifest shape: references/verification.md.

Unit of work = one surface: a page, a mobile screen, or a component. Not a flow, not an app. Batch your gap-questions, default aggressively, let the user correct the draft — never interrogate.

Phase 2 — Resolve brand (the ladder)

Stop at the first rung that hits. Full heuristics + fetch details: references/brand-ladder.md. Schema: references/design-md-schema.md.

1. DESIGN.md exists → use it.
2. In a project, no DESIGN.md → infer tokens from the repo's styles → persist a DESIGN.md so later surfaces stay consistent.
3. Greenfield / outside a project → either a named template (fetch one from github.com/VoltAgent/awesome-design-md, 73 ready-made DESIGN.md files) or imply from the user's described vibe (by judgment) → persist a DESIGN.md.

screenwright is both a consumer and a bootstrapper of DESIGN.md — same Google Labs design.md format either way, extended with two custom keys (a11y, breakpoints) that screenwright defaults when absent. If a fetch fails or you're offline, fall back to imply-from-description — the ladder never dead-ends.

Phase 3 — Paint

One author writes the whole file. Do not split generation across sub-agents by aspect (a11y, layout, interactions) — they're cross-cutting concerns over the same markup, and splitting them guarantees merge conflicts and an internally-inconsistent file.

Output contract — one self-contained HTML file:

• Inline <style>, inline SVG, no external requests (no CDN, no web fonts, no <script src>). It must render offline and port cleanly to any stack.
• Semantic HTML with the a11y target woven in (aria, labels, focus order) — not bolted on.
• Generate what the brief implies, don't wait for it: if the mock is desktop-only, build the mobile layout too (and vice-versa); add the states the surface needs (empty / loading / error) and interaction end-states (focus / hover / active / disabled). Implied surfaces are verified later but never silently dropped.

Anti-slop (capability-gated): if a taste-skill variant with dials (v1 or v2-experimental) is installed, apply its visual dials (DESIGN_VARIANCE, VISUAL_DENSITY) to push away from generic AI defaults; the default taste-skill has no dials and instead measures a page with inspect.mjs / lint.mjs. Clamp MOTION_INTENSITY low / ignore its GSAP skeletons — motion is out of screenwright's gate and its libraries break self-containment. If not installed, suggest it and proceed on judgment; do not synthesize the dials.

Phase 4 — Verify (in a sub-agent)

Run the render→audit→screenshot→fix loop inside one sub-agent — it's verbose (screenshots, axe dumps, iterations) and you want it out of the main thread. The sub-agent returns the final HTML (or a path) + the manifest, nothing else. Briefing conventions and the no-nested-sub-agents invariant live in sub-agent-coordinator. Exact Playwright calls and the axe-injection mechanic: references/playwright-loop.md. Gate definitions, the 8 dimensions, axe rulesets per surface type: references/verification.md.

Per cycle, for each in-scope viewport and state:

1. Render — page.setContent(html) (the MCP blocks file://; do not use it).
2. Audit — inject axe-core (addScriptTag({path})), run with the WCAG tags from a11y.wcag. Collect violations by impact.
3. Screenshot — capture for the fidelity critique.
4. Judge against the two gates over the quality set.

After the in-scope viewports pass, run one reflow pass at 320 CSS-px (WCAG 1.4.10, BLOCK): a horizontal scrollbar there = clipped content. Snippet + the optional text-spacing (1.4.12) override: references/playwright-loop.md.

Phase 5 — Loop (bounded)

• Fix blocking violations, re-render, re-audit. Cap at ~3 cycles.
• If a cycle doesn't reduce the blocking count, cheapen the loop before grinding: re-read the brief, attack the single highest-impact violation in isolation, don't re-paint the whole surface.
• After the cap, if blockers remain, stop and report honestly in the manifest — do not claim a pass you didn't reach.

Phase 6 — Handoff

Render needs only a transient target (the setContent call) — no durable file is required. Decide delivery by project-context (not by guessing agent-vs-user, which you can't detect). Details: references/handoff.md.

• In a project → deliver the final HTML inline so the host agent can port it; write a temp file and hand the path instead only if the artifact is large. Leave the repo clean.
• Non-project / interactive user → write a durable named .html and return the path. The file is the deliverable.

Always attach the verification manifest: what was checked hard (axe pass per viewport/state), what was checked soft (fidelity vs a reference, if any), and what is unverified (derived viewports, advisory dimensions, a11y if axe couldn't run). Honesty about confidence is the point.

The quality set — tight gate

screenwright owns a quality dimension only if (1) the eyes can verify it by screenshot AND (2) it survives the handoff to a real stack. That filter answers every "should we check X?" — motion fails (2); performance / Core Web Vitals / Lighthouse-perf / flows / copy fail entirely (they need a running app at a URL screenwright doesn't have — see "What this skill is NOT").

Advisory dimensions inform fixes and appear in the manifest; they never block the loop. Visual fidelity vs a reference image blocks only in mode A1, for the viewport the reference actually shows.

What this skill is NOT

• Not a multi-page / app builder — one surface, then handoff. No routing, no flows.
• Not a framework converter — outputs portable HTML; the host ports it to React/Vue/etc.
• Not a motion/animation system, performance auditor, or copywriter — out of scope by the verify-and-survive filter. Copy → ghostwriter; brand identity → brand-workshop; illustration → pixel-art.
• Not a runtime / Core Web Vitals / Lighthouse-perf / SEO auditor — those need a running app at a real URL (TTFB, network waterfall, async loading, INP); screenwright renders self-contained HTML via setContent, so those numbers would be fiction. Run web-quality-skills against the served build instead. Lighthouse's a11y category is axe (already our gate). AMP is deprecated and conflicts with self-contained output — not supported.
• Not a runtime — it drives the host's Playwright MCP; it ships no server.

Cross-skill integration

Slash invocation

/agent-skills:screenwright (or natural language matching the triggers). Optional argument: a mode hint or a path/URL to a mockup or code file. With no argument, screenwright asks the one or two intake questions it can't infer, then proceeds.