sxchnge/skills/ux-design/SKILL.md

name, description

name	description
ux-design	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

• 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?
• 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.