Interaction feedback

Interaction feedback

Tell users what happened. Every view that depends on data or an async action must communicate its state — loading, empty, error, success — and confirm the result of every interaction. Never leave a dead state where the UI silently does nothing.

When to use

Use this skill for requests such as:

• "Add loading and error states" / "add a skeleton loader" / "add a spinner"
• "Show a success message" / "add a toast / notification"
• "Inline form validation" / "show validation errors"
• "Optimistic UI" / "update immediately and roll back on failure"
• "Empty state for this list"
• "This button gives no feedback when clicked"

The core model: handle every state

Any component backed by data or an async action must explicitly handle four states, plus partial/optimistic transitions:

1. Empty — no data yet (first run, cleared filters, new account).
2. Loading — request in flight.
3. Error — the request or action failed.
4. Success / ideal — data is present, action confirmed.

Treat "no design for this state" as a bug. A blank screen during loading, a list that shows nothing with no explanation, or a button that does nothing on click are all dead states.

Patterns

1. Loading

   • Skeletons for content whose layout is known (cards, tables, profiles) — they preserve layout and reduce perceived wait.
   • Spinners for short, indeterminate waits where layout is unknown.
   • Inline button-busy (disabled + aria-busy + label like "Saving…") for in-place actions; keep the button's size stable to avoid layout shift.
   • Delay spinners ~200–300ms so fast responses don't flash a spinner. Reserve space so content doesn't jump when it arrives.

2. Success

   • Prefer in-context confirmation (the row updates, a checkmark appears, the field shows saved) over a detached message.
   • Use a toast for transient, low-importance confirmations ("Copied", "Saved").
   • Keep it brief and don't block the next action.

3. Error

   • Place errors near the cause (inline at the field/section), not only in a global banner.
   • Make them actionable and recoverable: say what went wrong and offer a next step (Retry, Edit, Contact support). Never a dead-end.
   • Preserve the user's input on failure.

4. Empty

   • Explain the value of the area and offer a primary action ("No projects yet — create your first project"). Don't just print "No data".
   • Distinguish first-use empty from filtered/cleared empty (offer "Clear filters").

5. Optimistic UI

   • Update the UI immediately on the user's action, then reconcile with the server.
   • On failure, roll back to the prior state and show a clear, recoverable message ("Couldn't save — changes reverted. Retry?").
   • Use only where the action is very likely to succeed and rollback is cheap and clear.

6. Toasts / status messages

   • Announce via aria-live: polite for routine status, assertive / role="alert" for errors and urgent messages.
   • Auto-dismiss neutral toasts (~4–6s); don't auto-dismiss errors the user must read or act on.
   • Never put a critical or only action inside a toast — toasts disappear and aren't reliably reachable by keyboard/screen-reader users.

7. Micro-interactions

   • Provide :hover, :active, and :focus-visible feedback on interactive elements.
   • Tie transitions/animation to motion tokens (duration, easing).
   • Always gate non-essential motion behind @media (prefers-reduced-motion: reduce) — disable or reduce animation, never make it required to understand state.

Accessibility of feedback

• Announce changes screen readers can't otherwise perceive: wrap status text in role="status" / aria-live="polite", and errors in role="alert" / aria-live="assertive". Live regions must exist in the DOM before their content updates.
• Move focus on error to the first invalid field (or an error summary linking to fields) on submit, so keyboard users land at the problem.
• Don't rely on color alone — pair red/green with an icon and text.
• Disabled vs busy: use aria-busy="true" for in-progress controls rather than fully removing them from the tab order; use disabled only when the control genuinely cannot be used.
• Mark invalid fields with aria-invalid="true" and associate the message via aria-describedby.

Adapt to the stack

Read ../ux-foundations/references/stack-detection.md and run that procedure before writing code; report the detected framework, styling, and language in one line. With no project, fall back to the framework-agnostic pattern in examples/toast-aria-live.html.

Reuse what exists. Before adding dependencies, check for existing toast/notification libraries (e.g. react-hot-toast, sonner, vue-toastification, svelte-french-toast), form/validation libraries (react-hook-form, zod, vee-validate, formik), and state/data libraries (@tanstack/react-query, swr, redux-toolkit, Pinia) — they often already model loading/error/success states. Wire feedback into those rather than introducing parallel systems. Style via design tokens, not hardcoded values.

References and examples

• references/states-and-feedback.md — decision table (situation → pattern → a11y mechanism → timing), the four states in depth, toast accessibility, validation timing, skeleton vs spinner, optimistic rollback UX, reduced-motion, and an anti-patterns list.
• examples/toast-aria-live.html — working framework-agnostic accessible toast system (polite status region + assertive alert region, pause-on-hover, reduced-motion aware).