ui-states-and-feedback

UI states and feedback

Most of a screen's code is the happy path; most of its defects are not. This skill governs everything a screen shows when there is no data yet, no data at all, no data matching the filter, a failure, or a write that just returned — and which surface each of those is allowed to use. The first-frame/cold-start path belongs to app-startup-and-bootstrap; the error values belong to error-handling-typed-results. This skill is only about how they are rendered and announced.

Non-negotiable rules

1. One state, resolved in one place. A screen renders exactly one of loading / empty / error / content, chosen by a single switch over an AsyncValue or a sealed view state. Never a triple of isLoading, error, items booleans. WHY: separate flags make impossible states representable — loading and error, empty and loading — and every such combination eventually renders.
2. The ViewModel decides the state; the View renders it. No FutureBuilder or StreamBuilder wrapped around a repository call in the middle of a widget tree. WHY: state scattered across the tree cannot be tested without pumping widgets, and rebuilds re-fire the future. See state-management-riverpod, widget-composition.
3. Empty, filtered-empty, and error are three different screens. "You haven't added anything yet" (offer the primary action), "Nothing matches this filter" (offer to clear it), and "We couldn't load this" (offer retry) answer three different user questions. WHY: showing "no items" for a failed load teaches the user their data is gone.
4. Never render an exception. No e.toString(), no stack trace, no failure class name in the UI. Map the typed Failure.code to a localized message via ARB. WHY: a raw exception is untranslatable, unactionable, and often leaks paths or ids.
5. Every error state offers a next action. Retry (ref.invalidate(provider)), go back, or change the input — and retry must preserve scroll position, filters, and entered text. WHY: a dead-end error screen turns a transient failure into an uninstall.
6. A refresh never blanks the screen. While reloading, keep the previous content and show a subtle indicator (AsyncValue.when's skipLoadingOnRefresh default, or valueOrNull + isRefreshing). WHY: replacing a list with a spinner loses the user's place and reads as data loss.
7. Loading is a delayed skeleton shaped like the result — not a centered spinner. Suppress it for roughly the first 150–300 ms so a fast load does not flash, and match the final layout so nothing jumps when content arrives. WHY: a flash and a reflow are two separate perceived defects; both are free to avoid. (Every duration in this skill is a behavioral threshold, not a value to hardcode — the numbers themselves belong to the duration tokens in design-system-structure.)
8. An in-flight action shows progress on its own control, not over the app. Disable the button, show progress in it, keep the rest interactive. A full-screen modal barrier is earned only when continuing would corrupt state. WHY: a blocking barrier over a 200 ms write is the most common self-inflicted "the app froze".
9. Pick the surface by the ladder: inline < snackbar < banner < dialog. Take the lowest one that works (table below). A modal is earned only by a decision that must resolve before the user can continue. WHY: every step up the ladder takes control away from the user, and dialogs are the only one that also blocks.
10. Information the user must act on never lives only in a snackbar. It auto-dismisses, it can be missed entirely, and a screen reader may never reach it. Use a banner or an inline state for anything that still matters in ten seconds.
11. Prefer soft delete + Undo over a confirmation dialog. Confirm only what is genuinely irreversible, and then name the consequence ("Delete 12 notes permanently") rather than asking "Are you sure?", with barrierDismissible: false. WHY: Undo is faster for the 99% who meant it and safer for the 1% who did not. See error-handling-typed-results for the soft-delete write path.
12. showDialog/showModalBottomSheet return Future<T?> — null means dismissed, and it is its own outcome. Switch over a sealed result and handle dismissal explicitly; never ?? true. WHY: ?? true silently converts a tap outside the dialog into a confirmed deletion.
13. Capture ScaffoldMessenger/Navigator before the await, guard mounted after. Then show the snackbar. WHY: the BuildContext may be gone when the write returns — this is the exact use_build_context_synchronously hole (async-safety).
14. Announce what only the eye can see. A result that appears (saved, deleted, retried, filtered) is announced with liveRegion: true or SemanticsService.announce, and auto-dismissal is lengthened or removed when MediaQuery.accessibleNavigationOf(context) is true. WHY: a 4-second snackbar is invisible to a screen-reader user mid-sentence. Announcements are best-effort per platform — never the only channel for something important.