uiux-audit

Automated UI/UX quality audit tool for websites. Uses Playwright to load pages, runs programmatic checks (accessibility + layout), and optionally uses a vision model for visual review.

How It Works

The audit runs in two layers:

Layer 1: Programmatic checks (no API cost)

• Accessibility — axe-core checks for labels, landmarks, ARIA, contrast, and more (~90 rules)
• Layout — custom DOM checks for text overflow, element overlap, touch target size, viewport issues, and more

Layer 2: Visual review (requires --visual, uses a vision model API)

• General review — detects misalignment, inconsistent spacing, visual hierarchy issues, broken-looking layouts
• Design compliance — compares screenshots against a UI/UX design spec document (Markdown) to find deviations

Installation

git clone <repo-url> uiux-audit
cd uiux-audit
npm install
npx playwright install chromium
npm run build

Configuration

uiux-audit uses a layered configuration system. Higher-priority sources override lower ones:

| Priority | Source | Use case | |---|---|---| | 1 (highest) | CLI flags (--model-url, --model-name) | One-off overrides | | 2 | Environment variables (UIUX_AUDIT_*) | Production / CI / NPM global install | | 3 | .env file in working directory | Local development | | 4 (lowest) | Built-in defaults (火山引擎 Ark + Doubao-Seed-2.0-pro) | Zero-config usage |

API Key

The API key must always be provided via environment variable — never on the command line. Command-line arguments are visible in ps aux and shell history.

# Development: create a .env file in your project
echo 'UIUX_AUDIT_MODEL_KEY=your-key' > .env

# Production / CI: export the environment variable
export UIUX_AUDIT_MODEL_KEY=your-key

# One-off: inline environment variable
UIUX_AUDIT_MODEL_KEY=your-key uiux-audit http://localhost:5173 --visual

Default Model

By default, uiux-audit uses 豆包 (Doubao-Seed-2.0-pro) from 火山引擎 Ark. To use a different model:

# Via CLI flags
uiux-audit http://localhost:5173 --visual --model-url https://api.openai.com --model-name gpt-4o

# Via environment variables
export UIUX_AUDIT_MODEL_URL=https://api.openai.com
export UIUX_AUDIT_MODEL_NAME=gpt-4o

Quick Start

# Run accessibility + layout checks on a local site (no config needed)
node dist/index.js http://localhost:5173

# Save report as JSON
node dist/index.js http://localhost:5173 --output json --output-file report.json

# Save report and screenshots to a directory
node dist/index.js http://localhost:5173 --output json --output-dir ./audit-results

# Enable visual review (set API key via environment variable or .env)
UIUX_AUDIT_MODEL_KEY=your-key node dist/index.js http://localhost:5173 --visual

Usage

uiux-audit <url> [options]

Options

| Option | Description | Default | |---|---|---| | --visual | Enable visual review layer using a vision model | off | | --design-spec <path> | UI/UX design spec document (Markdown) for compliance review | — | | --model-url <url> | Vision model API base URL | https://ark.cn-beijing.volces.com/api/coding/v3 | | --model-name <name> | Vision model name | Doubao-Seed-2.0-pro | | --viewport <sizes> | Viewport sizes as WxH, comma-separated | 1440x900 | | --output <format> | Output format: json, markdown, table | table | | --output-file <path> | Write report to file instead of stdout | — | | --output-dir <dir> | Output directory for reports and screenshots; creates timestamped subdirectory by default | — | | --no-timestamp | With --output-dir, write directly to the directory instead of a timestamped subdirectory | — | | --no-a11y | Skip accessibility checks | — | | --no-layout | Skip layout checks | — | | --pages <urls> | Additional page URLs to audit (comma-separated) | — | | --journey <path> | Path to a journey file (YAML or JS) for login/setup before auditing | — |

Environment Variables

| Variable | Required | Description | |---|---|---| | UIUX_AUDIT_MODEL_KEY | Yes (for --visual) | Vision model API key. Never pass via CLI. | | UIUX_AUDIT_MODEL_URL | No | Vision model API base URL (default: https://ark.cn-beijing.volces.com/api/coding/v3) | | UIUX_AUDIT_MODEL_NAME | No | Vision model name (default: Doubao-Seed-2.0-pro) |

Examples

Basic audit (no API cost):

uiux-audit http://localhost:5173

Save report and screenshots to a directory:

# Creates ./audit-results/2026-04-28T15-30-00/report.json and screenshots/
uiux-audit http://localhost:5173 --output json --output-dir ./audit-results

# Write directly to ./audit-results/ (no timestamp subdirectory)
uiux-audit http://localhost:5173 --output json --output-dir ./audit-results --no-timestamp

Multiple viewports (desktop + mobile):

uiux-audit http://localhost:5173 --viewport 1440x900,375x812

Full audit with visual review:

# Set key via environment variable, then run
UIUX_AUDIT_MODEL_KEY=your-key uiux-audit http://localhost:5173 --visual \
  --output json --output-file /tmp/ux-report.json

Design compliance check:

UIUX_AUDIT_MODEL_KEY=your-key uiux-audit http://localhost:5173 --visual \
  --design-spec ./docs/UIUX.md

Using a different model provider:

UIUX_AUDIT_MODEL_KEY=sk-xxx uiux-audit http://localhost:5173 --visual \
  --model-url https://api.openai.com \
  --model-name gpt-4o

Audit multiple pages:

uiux-audit http://localhost:5173 --pages /about,/contact,/settings

Audit a page that requires login (journey):

uiux-audit http://localhost:5173 --journey ./login-journey.yaml

See Journey below for details.

What It Detects

Accessibility (axe-core)

Labels, landmarks, ARIA attributes, color contrast, heading order, image alt text, focus management, and more (~90 rules from axe-core).

Layout (programmatic)

| Issue | Severity | Detection | |---|---|---| | Text horizontal overflow | critical | scrollWidth > clientWidth with overflow: hidden/clip | | Text vertical overflow (clipped) | critical | scrollHeight > clientHeight with overflow-y: hidden/clip | | Element overlap | warning | getBoundingClientRect() intersection, non-parent-child | | Touch target too small | warning | Interactive element < 44px in width or height | | Element outside viewport | critical | Element bounding box outside window dimensions | | Image missing dimensions | info | <img> without explicit width/height | | Zero-size element with text | critical | clientWidth=0 && clientHeight=0 with text content |

Visual (vision model)

Misalignment, inconsistent spacing, visual hierarchy issues, color problems, content cut off, broken-looking layouts, styling inconsistencies, and design spec deviations.

Output Format

Each issue in the report contains:

| Field | Description | |---|---| | type | Issue category (e.g. label, overflow-x, visual-issue) | | severity | critical, warning, or info | | selector | CSS selector to locate the problematic element | | description | What the issue is | | evidence | Measurable evidence (dimensions, rule violations, etc.) | | fixSuggestion | How to fix the issue | | deviation | (Design compliance only) Which design rule is violated |

AI Agent Integration

uiux-audit is designed to work in a loop with AI coding agents:

1. Agent starts the dev server
2. Agent runs: uiux-audit http://localhost:PORT --output json --output-dir /tmp/audit-results
3. Agent reads the JSON report from /tmp/audit-results/<timestamp>/report.json and fixes issues using selector and fixSuggestion
4. Agent re-runs the audit
5. Repeat until critical and warning counts are zero

The JSON output is structured for machine parsing — agents can iterate over results[].issues[] and use selector to find the source code and fixSuggestion to apply fixes.

Journey

Journey files automate login and setup steps before auditing. Useful when the target page requires authentication or specific state.

YAML Journey

Create a YAML file with steps:

name: Standard login
steps:
  - goto: ${BASE_URL}/login
  - fill:
      selector: input[type="text"]
      value: ${LOGIN_EMAIL}
  - fill:
      selector: input[type="password"]
      value: ${LOGIN_PASSWORD}
  - click: button[type="submit"]
  - waitFor: body
  - wait: 1000

Run with:

uiux-audit http://localhost:5173 --journey ./login-journey.yaml

Supported Steps

| Step | Description | |---|---| | goto: <url> | Navigate to a URL (${BASE_URL} resolves to the audit target) | | fill: { selector, value } | Fill an input field | | click: <selector> | Click an element | | press: <key> | Press a keyboard key (e.g. Enter, Escape) | | select: { selector, value } | Select an option in a <select> | | check: <selector> | Check a checkbox | | uncheck: <selector> | Uncheck a checkbox | | wait: <ms> | Wait for a duration in milliseconds | | waitFor: <selector> or { selector, timeout? } | Wait for an element to appear | | waitForNavigation: <url> | Wait for navigation to a URL | | assert: { selector?, url?, title? } | Assert element existence, current URL, or page title | | screenshot: <filename> | Take a screenshot (saved to output directory) |

Environment variables like ${LOGIN_EMAIL} are substituted from the process environment.

JS Journey

For more complex flows, use a JavaScript file:

export default async function ({ page, resolveUrl, baseUrl }) {
  await page.goto(resolveUrl('/login'));
  await page.fill('input[type="text"]', process.env.LOGIN_EMAIL);
  await page.fill('input[type="password"]', process.env.LOGIN_PASSWORD);
  await page.click('button[type="submit"]');
  await page.waitForURL('**/dashboard');

  // Return paths to audit after login
  return ['/dashboard', '/settings'];
}

The session state (cookies, localStorage) is preserved across the journey and the audit.

CJK Font Support

Playwright's bundled Chromium may render CJK (Chinese, Japanese, Korean) characters as empty boxes on systems without CJK fonts installed. To fix this:

Debian/Ubuntu:

sudo apt install fonts-noto-cjk

RHEL/CentOS/OpenCloudOS:

sudo dnf install google-noto-sans-cjk-sc-fonts google-noto-sans-mono-cjk-sc-fonts

The tool sets locale: 'zh-CN' on all browser contexts to ensure Chromium selects CJK fonts correctly.

Vision Model API

Uses the OpenAI-compatible /v1/chat/completions endpoint. Works with any service that exposes this API:

• Default: 火山引擎 Ark (Doubao-Seed-2.0-pro) — zero config beyond API key
• OpenAI (gpt-4o, gpt-4o-mini)
• Azure OpenAI
• Any other OpenAI-compatible provider

To use a different provider, set UIUX_AUDIT_MODEL_URL and UIUX_AUDIT_MODEL_NAME.

License

MIT