/ux-best-practices

name: ux-best-practices
description: Design, audit and improve UX for websites, mobile apps, SaaS, forms, onboarding, navigation, search, data tables, checkout and AI features. Use for UX/UI reviews of screenshots, prototypes, specs or code; user flows and interface states; accessibility against WCAG 2.2 AA; UX writing; usability validation; or when asked to "review my UI", "audit design", "review UX", "check accessibility", "check my site against best practices" or for Vercel Web Interface Guidelines compliance. Grounds findings in Laws of UX, WCAG, platform guidance and research, and separates confirmed defects from risks and hypotheses. Not for legal compliance certification or page-speed tuning.
argument-hint: <file-or-pattern>

UX Best Practices

Help a person complete their task: understand the options, choose an action, get the result and recover from errors. Answer in the user's language. When asked to implement, make the changes and verify them instead of stopping at recommendations.

• **UX audit, flow design or improvement:** follow the workflow below.
• **Quick code-level check of specific files:** use [Vercel Web Interface Guidelines](#vercel-web-interface-guidelines).

1. Set Context and Evidence Limits

Extract the core task, audience and experience; platform, input methods and language; cost of error and success criterion; the existing design system; available evidence (screenshot, prototype, DOM/code, analytics, research). Proceed with stated assumptions when details are missing; ask only when the answer materially changes the decision. Never invent personas, user quotes, product metrics or test results.

Scope: for a local fix, check the affected flow; for an audit, walk the key tasks end to end; for a new product, first describe the minimal working flow.

2. Load Only the References You Need

Include accessibility in every interface audit or implementation, sized to your access.

| Task | Read (under `references/`) | |---|---| | Hierarchy, cognitive load, navigation, onboarding, Laws of UX | `cognitive-principles.md`, then the relevant primary source linked in `sources.md` | | Forms, errors, states, modals, tables, responsive layout, microcopy | `interaction-patterns.md` | | Keyboard, semantics, target size, contrast, zoom, authentication | `accessibility.md` | | AI features and agents: trust, control, recovery | `ai-ux.md` | | Catalog, product search, checkout, transaction terms | `commerce.md` | | Loading, responsiveness, stability, speed metrics | `performance.md` | | Research method, metrics, verifying findings | `research-and-validation.md` | | Formats: audit, flow spec, validation plan | `output-templates.md` | | Source, version, date and scope of a claim | `sources.md` | | Decisioning workflow, anchors, information scaffold | `audit/00-core-framework.md`, `01-anchors.md`, `02-information-scaffold.md` | | New interface; fidelity, visual style, originality checklists | `audit/10-` to `13-checklist-*.md` | | Component patterns (chunking, disclosure, hierarchy, feedback, errors, navigation and more) | `audit/20-` to `31-patterns-*.md` |

Where `audit/` and a topical reference disagree, the topical reference wins: it carries the exact criteria and sources.

3. Walk the Flow and Its States

Start from the user's intent. For each significant step check:

1. **Discovery:** is it clear where to start and which option fits the task? 2. **Understanding:** is it clear what is needed, why, and what happens next? 3. **Action:** can it be done with the available input method, without needless memorization? 4. **Feedback:** are waiting, saving, completion and failure distinguishable? 5. **Recovery:** can the person fix input, go back, undo or retry safely?

Pick the applicable states: initial, loading, populated, empty, no-results, validation-error, service-error, permission-restricted, success; add offline, stale, partial, cancelled and destructive-confirmation where the flow has them. Do not demand every state of every component. Trace how input, filters, context and focus survive transitions. Check content order, window size, text zoom and input methods; a shrunken desktop layout is not an adaptation.

4. Ground Every Finding

| Basis | How to use it | |---|---| | Normative criterion | Name the standard, number, level, applicability and exceptions. For web, target WCAG 2.2 AA unless the project sets another. | | Official guidance | Respect platform and version. GOV.UK, Carbon, Apple or Android conventions are not universal obligations. | | Research | Check task, audience, method and limits of generalization. Do not promise another benchmark's effect. | | Heuristic or expert article | Use it to find a possible problem; confirm by observation or a testable hypothesis. | | Own synthesis | Label it; explain the causal link and how to verify it. |

Mark each finding **confirmed**, **likely risk** or **not verified**. From a screenshot judge only visible properties; absence from the frame is not proof of absence. Never claim keyboard, screen-reader, reflow, speed, conversion or whole-flow checks you had no access to. In a conflict, clarify applicability and keep required accessibility and safety. A newer article is not automatically stronger evidence. If several plausible solutions remain, offer a testable alternative with its trade-off.

5. Propose a Concrete Change

For each significant problem write: **observation → affected task → likely consequence → change → basis → verification.** Give the button or error text, step order, behavior rule or component change, never "make it more intuitive". Keep useful familiar patterns and the design system.

Rate severity on the S0–S3 scale in `references/output-templates.md` (S3: a key task is impossible or data loss is possible; S0: polish) and keep it apart from reach and cost of fix. Order fixes by consequence, reach, confidence, dependencies and effort; do not inflate a backlog for a small task.

6. Verify i