Interaction Feedback

---
name: interaction-feedback
description: This skill should be used when the user wants clear visual feedback for async actions and state changes — triggers like "add loading and error states", "show a success message", "add a toast/notification", "inline form validation", "optimistic UI", "empty state for this list", "this button gives no feedback", or "add a skeleton loader". It implements loading/empty/error/success states, toasts, micro-interactions, and their accessibility announcements, adapted to the detected stack.
version: 0.1.0
---

# 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).