---
name: basic-ux-audit
description: Audit a website, screen or agent-driven product against BASIC UX, the five UX principles (Beauty, Accessibility, Simplicity, Intuitiveness, Consistency) applied to both of a system's users, people and AI agents. Drives Playwright to capture screenshots for the people lens and the accessibility tree, raw HTML, robots.txt, llms.txt, structured data and WebMCP tools for the agent lens, then scores each principle twice. Use when asked to review or improve UX, "run a BASIC UX audit", check accessibility, check whether AI agents can use a site ("is this agent-ready", "is it agent-friendly"), grade a design, or hold AI-built UI to a standard. Optionally checks a company style guide (brand.json).
license: MIT
compatibility: Needs an agent that can run terminal commands, plus Node.js 18 or later and Playwright with Chromium.
---

# BASIC UX audit

BASIC UX (basicux.com, first published in UX Magazine in 2016) is five
principles with questions to ask under each. Most systems now have two kinds of
user: people, who look at the screen, and AI agents, who read the
accessibility tree, the HTML and whatever machine paths the site offers. The
same five principles hold for both. The questions differ.

| Principle | People | Agents |
| --- | --- | --- |
| Beauty | Is it aesthetically pleasing? | Is it well formed? |
| Accessibility | Can everyone use it? | Can an agent read and use it? |
| Simplicity | Does it make life easier? | Does it take the fewest steps? |
| Intuitiveness | Is it easy to learn? | Does it say what it does? |
| Consistency | Does it match the system? | Does it act the same every time? |

`PRINCIPLES.md` has every question for both lenses, plus the questions for
products that put an agent to work on a person's behalf.

## Setup (once)

```bash
cd scripts && npm install         # installs Playwright and Chromium
```

## Run

```bash
node scripts/assess.mjs <url> [--brand brand.json] [--out ./basic-ux-report] [--width 1440]
```

- `<url>` can be live or local, such as `http://localhost:3000`.
- `--brand brand.json` checks palette and fonts for the "does it follow the
  style guide?" question. See `brand.example.json`.
- Every run also loads the page at a 390px phone width, saves
  `mobile-view.png`, and checks for sideways scrolling and small tap targets
  there. (`--mobile` is still accepted and changes nothing.)

It writes to the output folder:

- `report.md`: both scorecards, the evidence behind every score, and the
  questions to ask.
- `report.json`: every metric, machine-readable.
- `agent-view.yaml`: the page's accessibility tree, the roles and names a
  browser agent reads instead of pixels (Playwright MCP works from exactly
  this snapshot).
- `desktop-view.png`, `desktop-full.png`, `mobile-view.png`.

## Finish the audit (required)

The script scores what it can measure. Three things need your judgement.

1. **People lens.** Open `desktop-full.png` and `mobile-view.png`. Judge Beauty
   (composition, hierarchy, polish, on brand) and Intuitiveness (is the main
   action obvious, are the patterns familiar). Adjust those two scores.
2. **Agent lens.** Read `agent-view.yaml` as if it were all you could see.
   Name the page's main task and the exact control you would use to do it. If
   you cannot find it, or two controls share a name, or the content you need
   is missing from the tree, that is the top finding. Adjust the agent scores.
3. **Agents inside the product.** If the product itself runs an agent for its
   users (a chat that books, buys, sends or edits), score the questions under
   "When an agent acts for a person" in `PRINCIPLES.md` by using the product.
   The script cannot see these.

Then report the ten scores and the top five fixes, ordered by impact. Cite the
evidence for each one, such as "2.8:1 contrast, needs 4.5:1" or "button with
no name at line 41 of agent-view.yaml". Do not invent findings. If you can edit
the code, fix the top issues and re-run to show both scores went up.

## Works with basic-ux-design

basic-ux-design is the companion skill. It holds the build rules and the code
patterns for both users, filed under the same five principles as this audit.
Design with it, measure with this, fix each finding with the matching rule
there, and re-run until both scores reach 90. If the design skill is not
installed, the fixes below cover the common cases.

## Common fixes, by what they help

- Both users: real `<button>` and `<a href>` elements instead of clickable
  `div`s, a label on every field, descriptive link text instead of "read
  more", one `h1` and a clean heading outline, content in the HTML rather than
  painted in by JavaScript.
- People: contrast at 4.5:1 for text, alt text, tap targets of 24px or more,
  one spacing scale and one type scale.
- People who read with ADHD, dyslexia or little schooling: reading grade 6 or
  below, about 15 words a sentence and none over 25, paragraphs of 1 to 3
  sentences, headings of 8 words or fewer. The audit measures all four on the
  page's prose.
- Agents: a short `/llms.txt`, valid JSON-LD, a canonical URL, a status
  region (`role="status"`) that says what happened after a form submits, no
  CAPTCHA in front of a public task, robots.txt that lets user-directed agents
  such as ChatGPT-User and Claude-User in, and WebMCP tools for the main tasks
  where the browser supports them.

## Using it in different agents

- **Claude Code:** put this folder in `~/.claude/skills/basic-ux-audit/` or a
  project's `.claude/skills/`. It loads by description.
- **Cursor, Codex and others:** keep the folder in the repo and add a rule:
  "to review UX, run `node scripts/assess.mjs <url>` from the basic-ux-audit
  skill and follow its SKILL.md." Codex reads `AGENTS.md`, so the rule can go
  there.
- **Any CLI agent:** it is Node and Playwright. Run `assess.mjs` and read
  `report.md`.

## Customise it

Generate both skills with your company's palette, fonts and example sites at
basicux.com/skills.html, or copy `brand.example.json` to `brand.json` and edit
it.