---
name: ux-design
description: Design, implement, or review user-facing interfaces for usability, state handling, responsiveness, accessibility, performance, and trust. Apply to new flows and changes to existing interfaces.
---

# UX Design

Use these instructions while implementing an interface and apply the UX Review
before reporting it complete. Rendering correctly is only one part of completion.

## Establish the flow

- Prefer the simplest interface that lets users complete their task confidently.
  When options meet the same need, choose fewer concepts, choices, and controls.
  Add complexity only for a concrete user need; preserve essential information,
  accessibility, and recovery rather than hiding them to make a screen look minimal.
- Identify the user's primary task, successful outcome, and shortest appropriate
  path to that outcome before choosing layouts or controls.
- Inspect comparable product flows, components, navigation, terminology, and
  visual conventions. Reuse established patterns when they solve the same problem.
  Prefer familiar interactions over novelty. Introduce a new component, pattern,
  or term only for a concrete unmet need; document that reason.
- When a generic recommendation conflicts with an established product convention,
  inspect and follow the convention unless there is a concrete reason to change it.
  Do not impose a framework, component library, or visual style.

## Make actions understandable

- Design mobile-first: make the primary task work on a small screen before
  adapting it to larger screens. Make the primary action visually obvious.
- Use hierarchy and recognizable affordances to show what matters, what is
  interactive, what is happening, and what will happen next.
- Minimize steps, unnecessary elements, decoration, and cognitive load. Keep
  secondary, advanced, or rarely used information behind progressive disclosure
  without hiding information needed for the primary task.
- Treat copy as interface design: use clear, specific, consistent terms and
  action labels. Improve an unclear interaction before adding explanatory prose.
- Keep navigation, interactions, terminology, and visual conventions consistent
  across the product, including responsive variants.
- Preserve user input and context, including selections and the user's place in
  a flow, whenever possible. Never unexpectedly navigate, submit, delete,
  refresh, or modify user data.
- Give users appropriate control, such as cancel, back, retry, or recovery.
  Prefer undo or recovery for reversible actions. Reserve confirmation dialogs
  for destructive, irreversible, consequential, or difficult-to-recover actions;
  explain the action and its consequences clearly.
- Never make hover, color alone, or gestures the only way to discover or perform
  an important action. Provide visible, accessible alternatives.

## Design states and feedback

Treat screens and components as stateful systems. Identify relevant states before
implementation: initial, loading, populated, empty, partial, success, error,
disabled, permission-restricted, and offline. Use judgment; do not add states
that the actual component or flow cannot encounter.

- Make transitions understandable and preserve context through them. Distinguish
  an empty result from data that is still loading or failed to load.
- Give immediate, meaningful feedback after important actions. Distinguish work
  in progress from confirmed success so users never have to guess the outcome.
- Explain errors specifically: what went wrong and, when possible, the recovery
  action. Keep user input after errors whenever possible and make retries usable.
- Explain disabled actions and access restrictions when needed to proceed,
  without disclosing information the user is not authorized to see.

## Adapt and make accessible

- Intentionally adapt layout, navigation, density, and interactions to available
  space; do not just shrink a desktop layout. Preserve hierarchy and primary
  actions across relevant viewport sizes and avoid unnecessary horizontal scroll.
- Check realistic long content, translations where relevant, and text scaling;
  do not validate only short placeholders.
- Build accessibility into each state: readable text, sufficient contrast,
  adequate touch targets, visible focus, and meaningful accessible names and
  states. Check against applicable project and platform accessibility requirements.
- Support keyboard navigation and screen-reader interaction where applicable.
  Verify focus order, activation, and feedback through the actual flow, including
  errors and state changes. Never convey important information by color alone.

## Preserve performance and trust

- Provide appropriate progress feedback for operations that are not immediate.
  Avoid unnecessary loading states, layout shifts, and blocking unrelated actions.
- Use optimistic updates only when safe, with reliable reconciliation and a
  recovery path if the operation fails. Do not present an unconfirmed operation
  as a confirmed outcome.
- Never expose sensitive information unnecessarily, including in errors, loading
  placeholders, and permission-related states.

## UX Review

Walk the changed flow with realistic content and applicable states. Record checks
performed and any gaps; do not mark applicable unmet criteria as complete.

### Usability

- [ ] Can a new user understand the screen's purpose, primary task, and primary
  action without external explanation?
- [ ] Are interactive elements recognizable, and can the user tell what is
  happening and what will happen next?
- [ ] Are steps appropriate, with unnecessary interaction and cognitive load removed?
- [ ] Is this the simplest usable solution, with each added concept, choice, or
  control serving a concrete user need?
- [ ] Does the flow follow existing product patterns and consistent terminology,
  with a concrete reason for any departure?
- [ ] Can users recover from errors, with input and context preserved where appropriate?
- [ ] Are destructive or irreversible actions handled appropriately, with user
  control and undo, recovery, or confirmation suited to the consequences?

### States and responsiveness

- [ ] Are all relevant states implemented, including loading, empty, error,
  success, disabled, and permission-related states where applicable?
- [ ] Are transitions understandable and context preserved?
- [ ] Does the flow work well on mobile and across relevant viewport sizes with
  realistic content lengths and text scaling?

### Accessibility and performance

- [ ] Are applicable accessibility requirements satisfied, with understandable,
  accessible controls, names, states, focus, and keyboard/screen-reader behavior?
- [ ] Are important actions discoverable without relying on hover, color, or gestures?
- [ ] Do slow operations provide appropriate feedback, without unnecessary
  loading states, layout shifts, or blocked interactions?

This checklist assesses design. For full UI completion, also verify the project's
observability requirements; a usable rendered screen alone does not establish a
measurable user outcome.