Usability Heuristics skill for Codex

Gives the Codex app a display name, a one-line description and a starter prompt for this skill.

interface:
  display_name: "Usability Heuristics"
  short_description: "Nielsen-based UX audits with evidence and fixes"
  default_prompt: "$usability-heuristics Do a heuristic evaluation of our signup and onboarding flow"

# Heuristic probe checklist

Use while walking each screen. Each heuristic lists probes (what to try or look for) and
the violation patterns that turn up most often in web and mobile products. A probe that
fails becomes a finding only with evidence.

## H1 Visibility of system status

Probes:
- Click every primary button. Is there feedback within 100 ms (pressed state, spinner)?
- Throttle the network to "Slow 4G". Does anything show progress after 1 s? Is there
  a percentage or step count for operations over 10 s?
- After save/send/delete, is the result visible where the user is looking?
- Is the current location shown (active nav item, page title, breadcrumb, step x of y)?
- Are background jobs (imports, exports, uploads) visible after leaving the page?

Common violations: silent saves; spinners with no timeout; disabled button with no
reason; upload progress lost on navigation; "Saved" shown before the request succeeds.

## H2 Match between system and the real world

Probes:
- Read every label aloud to an imagined target user. Any internal jargon, table names,
  enum values (`PENDING_REVIEW`), or developer terms?
- Are dates, money and units in the user's locale and format?
- Does the order of fields and steps match how the user thinks about the task
  (shipping before payment, name before email)?
- Do icons mean what the user expects without a tooltip?

Common violations: error codes as messages; "Entity", "Tenant", "Resource" in UI copy;
ISO timestamps; ambiguous icons (a gear for three different things).

## H3 User control and freedom

Probes:
- Can every modal be closed with Esc, a close button, and (on mobile) back?
- Is there undo for delete, archive, send, move? Or at least a confirmation for
  irreversible actions?
- Does browser back go where the user expects, without losing form input?
- Can a multi-step flow be left and resumed?

Common violations: wizard that resets on back; no undo after bulk actions; modal traps;
auto-advance carousels with no pause.

## H4 Consistency and standards

Probes:
- Same action, same label everywhere? ("Remove" vs "Delete" vs "Archive" for one action)
- Primary button style and position consistent across dialogs?
- Links look like links; buttons look like buttons; platform controls behave natively
  (date fields accept typing, selects open with keyboard)?
- Terminology matches the rest of the product and the industry.

Common violations: OK/Cancel order flips between dialogs; custom controls that break
platform keyboard behaviour; two different icons for the same concept.

## H5 Error prevention

Probes:
- Try invalid input: wrong formats, too long, empty, duplicates. Is it constrained or
  validated before submit?
- Are destructive actions separated from frequent ones and confirmed with specifics
  ("Delete 14 files?")?
- Are sensible defaults set? Are impossible options disabled with a reason, or hidden?
- Double-submit: click Pay/Send twice quickly.

Common violations: free-text where a picker fits; delete next to edit with equal weight;
double charges or duplicate records from double-clicks; confirmation dialogs that only
say "Are you sure?".

## H6 Recognition rather than recall

Probes:
- Does any step require remembering information from a previous screen?
- Are recent items, previous choices and search history offered?
- Are options visible, or hidden behind unlabeled icons and gestures?
- Do form fields keep visible labels after typing (no placeholder-only labels)?

Common violations: codes the user must copy between screens; icon-only toolbars; filters
whose active state is not shown.

## H7 Flexibility and efficiency of use

Probes:
- Can frequent users do the main task faster: keyboard shortcuts, bulk select, saved
  filters, duplicates, templates?
- Does the system remember preferences (sort, view, last workspace)?
- Is autofill supported (`autocomplete` attributes)?

Common violations: no bulk actions on lists; settings that reset each visit; paste
blocked in fields.

## H8 Aesthetic and minimalist design

Probes:
- On each screen, what is the one thing the user came for? Is it the most prominent?
- Remove each element mentally: would anyone miss it?
- Are secondary details progressively disclosed instead of shown all at once?

Common violations: promotional banners above the task; equal visual weight for every
action; dense tables with rarely used columns shown by default.

## H9 Help users recognise, diagnose and recover from errors

Probes:
- Trigger each error you can. Does the message say what happened, why, and what to do?
- Is the error placed next to the cause and announced to screen readers?
- Is user input preserved after an error?
- Are server and network failures distinguished from validation errors, with retry?

Common violations: "Something went wrong"; errors only at the top of long forms; form
cleared after a failed submit; 404 pages with no path forward.

## H10 Help and documentation

Probes:
- For complex fields, is there inline help (helper text, examples) rather than a link
  to a manual?
- Is help searchable and does it match the current UI?
- Is there a way to contact support from the place the user gets stuck?

Common violations: help center screenshots from an old UI; tooltips as the only
explanation on touch devices; no example values for formatted inputs.