ui-audit-guide

Audit running web applications for UI/UX issues using Playwright MCP browser automation.

1|1|Updated Dec 18, 2025
One-click install
npx skills add https://github.com/nexuslabs-ai/nexus --skill ui-audit-guide-nexuslabs-ai
Or copy as Structured Prompt for Agent▼
Please help me install this Agent Skill.
Skill: ui-audit-guide
Source: https://github.com/nexuslabs-ai/nexus/tree/main/.agents/skills/ui-audit-guide
Command: npx skills add https://github.com/nexuslabs-ai/nexus --skill ui-audit-guide-nexuslabs-ai

SYSTEM DOCUMENTATION & REQUIREMENTS

What problem does it solve? Manually reviewing a web application for UI/UX regressions is slow and inconsistent, and visual quality issues often slip through code review. This Skill automates structured UI audits by driving a real browser through user flows, capturing screenshots and accessibility snapshots, and reporting issues categorized by severity. ## Core Features & Use Cases - Flow-Based Functional Audit: Navigates user flows with Playwright MCP, capturing screenshots and a11y-tree snapshots at each state, then checks states, accessibility, content, interactions, and layout. - Visual Direction Evaluation: Runs a separate holistic pass scoring focal point, type scale, spacing rhythm, primary action clarity, and intentionality on a 1-5 scale, flagging low scores for human design review. - Severity-Categorized Reporting: Outputs a structured Markdown report grouping issues into Critical, Moderate, and Minor tables, plus positives and per-flow results. - Use Case: Before opening a PR for a new settings page, run the audit at mobile and desktop viewports to catch missing loading states, unlabeled controls, and weak visual hierarchy before reviewers do. ## Quick Start Audit the app running at localhost:3000 on mobile viewport and report all UI/UX issues by severity.

Frequently Asked Questions about ui-audit-guide

High-intent search queries and answers about installing and using this skill.

FAQPage Schema
How do I audit a web app for UI/UX issues with Playwright MCP?▼

Provide the running app's URL and target viewport, then the audit navigates each user flow using browser_snapshot and browser_click, capturing screenshots at every state. Findings are grouped into Critical, Moderate, and Minor severity tables in a structured Markdown report.

What does the visual direction evaluation check?▼

It scores five dimensions on a 1-5 scale: squint test (focal point), type scale hierarchy, spacing rhythm, primary action clarity, and intentionality. Any dimension scoring 2 or below is flagged for human design review rather than treated as a code bug.

Does this audit work with Radix UI or shadcn components?▼

Yes. Playwright MCP interacts through the accessibility tree, so browser_click targets elements by role and label, which works reliably with Radix and shadcn components without special workarounds.

What prerequisites are needed to run a Playwright MCP UI audit?▼

You need a Playwright MCP server configured (providing the mcp__playwright__ browser tools) and the application running at a known URL. The repo's default .mcp.json ships chrome-devtools, so Playwright MCP may need separate configuration.

Why are low visual direction scores not filed as code issues?▼

Scores of 2 or below reflect design direction judgment calls, not implementable bugs. The audit flags them as 'recommend human design review' so designers, not engineers, decide on hierarchy and aesthetic changes.