---
name: basic-ux-design
description: Design and build websites and web apps that people find clear and good-looking and that AI agents (web agents, browser agents, computer-use agents) can read and operate. Turns the five BASIC UX principles (Beauty, Accessibility, Simplicity, Intuitiveness, Consistency) into build rules for both users, with code patterns for semantic HTML, accessible names, llms.txt, JSON-LD, robots.txt and WebMCP. Use when building, restyling or reviewing any page, site, component or web app; when asked to make something "look good", "modern", "AI native", "agent-ready" or "work with AI agents"; and together with the basic-ux-audit skill, which measures the result.
license: MIT
compatibility: Any agent that loads Agent Skills (SKILL.md). Instructions and code examples only; no scripts to run.
---

# BASIC UX design

BASIC UX (basicux.com, first published in UX Magazine in 2016) is five
principles with questions to ask under each. A site now has two kinds of user.
People look at the screen. AI agents read the accessibility tree, the HTML and
any machine paths the site offers. This skill turns the five principles into
build rules for both, so the page you ship is usable by people and agent-ready
in one build.

People come first. The agent rules never outrank the people rules, and there
is never a separate version for agents: same content, same prices, same labels.
Nearly every agent rule is also an accessibility rule, so doing it right helps
both.

## How it works with basic-ux-audit

1. **Design** with this skill. If a `brand.json` sits beside it, use its
   colours, fonts and notes as the style guide.
2. **Build** the page.
3. **Audit** it with the basic-ux-audit skill. From that skill's folder, run
   `node scripts/assess.mjs <url>`. It checks the page at desktop width and at
   a 390px phone width, scores each principle twice, for people and for
   agents, and lists every failed check.
4. **Fix** each finding with the matching rule below. Every audit finding is
   named by principle, and each principle here has both halves.
5. **Re-run** until both the people and the agent score are 90 or above, and
   the audit's judgement steps (screenshots and `agent-view.yaml`) pass.

## Beauty

People: is it aesthetically pleasing? Agents: is it well formed?

- One concept for the page in a sentence, before any styling. It picks the
  typeface, the accent and the imagery.
- Two typefaces at most, on a modular fluid scale. Body text 16px or larger,
  line height 1.5 to 1.7, 60 to 75 characters a line.
- One spacing scale on a 4 or 8px base. Every gap is a token.
- Mostly neutrals and one accent. Contrast 4.5:1 for text, 3:1 for large
  text and controls.
- One focal point per screen.
- Agents: one `h1`, no skipped heading levels, a unique `title`, a meta
  description, `lang`, a canonical URL and valid JSON-LD.
- Agents: a stable layout (CLS under 0.1), nothing covering a control, and
  visual order that matches source order.
- Depth: `references/visual-craft.md` for craft and the generic AI-design
  tells to avoid; `references/agent-ready.md` for the markup.

## Accessibility

People: can everyone use it? Agents: can an agent read and use it?

- Keyboard reachable, a visible `:focus-visible` style, alt text on every
  meaningful image, `prefers-reduced-motion` respected.
- Tap targets 24px at least, 44px for primary touch actions.
- Text a reader with ADHD, dyslexia or another learning difference can
  read, at a 6th grade reading level or below. See "Write for every reader".
- Nothing hidden from an automated browser. If content animates in on
  scroll, start it visible when JavaScript is off or `navigator.webdriver` is
  true.
- Real elements for controls: `<button>` for actions, `<a href>` for
  navigation. Never a clickable `div`.
- Every control has a name in the accessibility tree. An icon-only button
  gets an `aria-label`.
- Every field has a `<label>`. A placeholder is not a label.
- The content is in the HTML before JavaScript runs. Render on the server or
  at build time.
- robots.txt lets user-directed agents in (ChatGPT-User, Claude-User,
  Perplexity-User). No CAPTCHA in front of a public task. A sitemap exists.

## Simplicity

People: does it make life easier? Agents: does it take the fewest steps?

- One primary action per view. Few choices on the first screen.
- Cut every sentence that does not carry a fact. No filler copy.
- Short text: about 15 words a sentence or fewer, none over 25. One idea
  per sentence. Paragraphs of 1 to 3 sentences. An intro of 1 or 2.
- Agents: a `/llms.txt`, JSON-LD for the facts on the page, and alternate
  formats (`<link rel="alternate">` to Markdown or JSON) where they exist.
- Agents: WebMCP tools for the page's main tasks where it fits, one job per
  tool, named with a verb. A plain HTML form can become a tool with the
  `toolname` and `tooldescription` attributes. Add `toolautosubmit` only to
  forms that read (search, filter, look up); a form that books, buys, sends
  or contacts someone waits for the person to press submit.
- Agents: keep the accessibility tree short. No duplicated menus or hidden
  off-canvas copies of the page.

## Intuitiveness

People: is it easy to learn? Agents: does it say what it does?

- Familiar patterns: logo top left links home, navigation where people look
  for it, underlined or clearly styled links, buttons that look pressable.
- Link text names the destination. Button text is a verb and an object. No
  "click here", "learn more" or "read more" on their own.
- Text means what it says on the first read. Headings of 8 words or fewer
  that say what is under them. Every term explained the first time.
- Every form has a real submit button.
- After an action, the page says what happened in text that stays
  (`role="status"` or `role="alert"`), not a toast that disappears. The
  region is in the page from the start, empty, so screen readers announce
  the change. Never `display:none` it while it waits.
- Anything that cannot be undone is marked and confirmed.

## Consistency

People: does it match the system? Agents: does it act the same every time?

- One navigation model per menu. A menu either scrolls within the current
  page or opens other pages, never both. A link like `/#book` from another
  page counts as a page link, so on a multi-page site give "Book" its own
  page or put the form where the menu lands.
- Header, footer and page title block in the same place on every page.
- Reuse components and tokens. Forms share labels, validation and messages.
- Agents: people and agents get the same content, prices and labels. An
  `aria-label` contains the words on screen.
- Agents: the same name always leads to the same place. Stable URLs, filters
  and searches reflected in the URL.
- Agents: the API, the JSON-LD and llms.txt say what the screen says.

## Write for every reader

Write as if the reader has ADHD, dyslexia or another learning difference,
reads on a phone, and had the least schooling of anyone who might visit.
Many readers are like this at some point: tired, busy, or reading in a
second language. The basic-ux-audit skill measures the first four rules.

- Reading grade 6 or below.
- About 15 words a sentence on average. None over 25.
- Paragraphs of 1 to 3 sentences. A page or section intro of 1 or 2.
- Headings of 8 words or fewer, saying what is under them.
- One idea per sentence. Put the main fact first.
- Short, common words: use, not utilize; help, not facilitate.
- Literal words. No idioms or figures of speech ("move the needle", "under
  the hood"). Some readers take every word at face value.
- Explain each term the first time, in the same sentence. Then use it the
  same way every time. A new word for the same thing reads as a new thing.
- Digits for numbers a reader compares: 3 steps, 16 weeks, $9 a month.
- Lists for steps and choices, not long paragraphs.
- Describe what the thing does. Do not sell it: no "powerful", "seamless",
  "unlock" or "elevate".

Agents gain too. Short, literal text is easier for a model to read correctly
and costs fewer tokens.

Sources: W3C, "Making Content Usable for People with Cognitive and Learning
Disabilities" (https://www.w3.org/TR/coga-usable/), and WCAG 2.2 success
criteria 3.1.3 Unusual Words, 3.1.4 Abbreviations and 3.1.5 Reading Level.

## When the product has its own agent

For an AI-native app, where an agent acts for the user (books, buys, sends,
edits), add these. The audit cannot measure them, so check each by hand.

- Beauty: the agent's plan and results can be checked at a glance.
- Accessibility: the person can stop it, take over or say no at any moment.
- Simplicity: checking its work is easier than doing it, and it asks only
  when the answer matters.
- Intuitiveness: it shows the plan before it acts, and actions can be undone.
- Consistency: it always asks before anything permanent, paid or private,
  and always says it is an AI.

## Avoid the generated look

These mark a page as default AI output. Details in
`references/visual-craft.md`.

- Em dashes and long arrows in UI copy. Emoji used as icons.
- A centered hero with a badge above the H1 and two buttons side by side.
- Purple-to-blue gradients, gradient-clipped headings, glow blobs.
- Inter or a framework default as the whole type identity; untouched
  shadcn or Tailwind tokens.
- The same card grid, padding and radius on every section; a coloured stripe
  on the left or top of rounded cards; a Lucide icon in a tinted tile on
  every feature card.
- Fade-in-up on every element.
- Copy like "Empower your workflow" or "Seamlessly". Say the specific thing.

## Before calling it done

- Run basic-ux-audit. Both the people and the agent score 90 or above.
- Read `agent-view.yaml` and name the control an agent would use for the
  page's main task. If you cannot, fix that first.
- View the page at 390px (the audit saves `mobile-view.png`). The navigation
  collapses into a real menu and nothing scrolls sideways. The hero is
  reworked, not shrunk: restack or crop its picture for the narrow screen and
  keep one clear headline and one action in the first screen.
- `curl` the URL and check the main content, the title, the description and
  the canonical are in the response.
- Check every visible string: buttons, empty states, errors, success messages.
- Read the page as the reader in "Write for every reader". The audit reports
  the reading grade, long sentences, long paragraphs and long headings.

`PRINCIPLES.md` and `principles.json` hold every BASIC UX question for both
users.