raft-ui

--- name: feedback description: "Feedback and status surfaces: Banner vs toast vs NotificationCenter, Skeleton vs Spinner vs Progress, Badge vs Status, and the inconsistent intent names." --- # Feedback and status ## Contents - Intent names are inconsistent — check every time - Banner vs Toast vs NotificationCenter - Skeleton vs Spinner vs Progress - Badge vs Status - EmptyState - Per-component norms --- ## Intent names are inconsistent — check every time The same intent has different spellings across components. This is the most reliable way to get a runtime-silent styling bug, because an unknown variant value simply falls back to the default. | Component | negative | informational | | ---------------------------- | ---------------------------------- | -------------------------------- | | `Button` | `variant="danger"` | `variant="information"` | | `Badge` | `variant="danger"` | `variant="information"` | | `Status` | `variant="danger"` | `variant="information"` | | `Progress` | `variant="danger"` | `variant="information"` | | `Banner` | `status="destructive"` | `status="info"` | | toast command / object | `toast.error()` or `type: "error"` | `toast.info()` or `type: "info"` | | `NotificationCenterItemIcon` | `status="error"` | `status="info"` | Three different words for the same intent: `danger`, `destructive`, `error`. Two for informational: `information`, `info`. Rule: **never carry a variant value from one component to another.** Confirm it against the component you are actually using. Note also that `Button` alone has three negative variants — `danger` (solid), `danger-secondary`, and `danger-outline` — matching its `primary` / `default` / `outline` ladder. --- ## Banner vs Toast vs NotificationCenter All three deliver a message. They differ in lifetime and ownership. | | `Banner` | `Toast` | `NotificationCenter` | | ------------------- | ------------------------------ | ---------------------- | --------------------------------- | | Lives in | the page flow | a floating viewport | an inbox popup | | Lifetime | as long as the condition holds | seconds | until read or cleared | | Caused by | page state | the user's last action | something that happened elsewhere | | Survives navigation | yes, if the state does | no | yes | | Can be missed | no | yes | no | **Decision rule:** if missing the message would leave the user confused, it must not be a toast. - Quota exceeded, connection lost, read-only mode, unsaved changes → `Banner`. The condition is still true, so the message must still be visible. - Saved, copied, message sent, invite revoked → `toast.info()`, `toast.success()`, `toast.warning()`, or `toast.error()`. The user just did it and already knows the context. - Someone mentioned you, a task was assigned, a build finished → `NotificationCenter`. It happened out of band and needs to persist. **Incorrect** — a persistent condition announced once: ```tsx if (isReadOnly) toast.info("This channel is read-only"); ``` The user scrolls away, the toast expires, and the disabled composer now has no explanation. **Correct:** ```tsx { isReadOnly && ( <Banner status="info"> <BannerDescription>This channel is read-only.</BannerDescription> </Banner> ); } ``` **`Banner`** — `status` is `default` `destructive` `warning` `info` `success`; `size` is `sm` `md` `lg`. Compose `BannerTitle`, `BannerDescription`, `BannerAction`. Use a `BannerAction` when there is a way out of the condition. **`Toast`** — wrap the application in `ToastProvider`, then fire the default manager with `toast.info()`, `toast.success()`, `toast.warning()`, `toast.error()`, or `toast.add()`. Dismiss with `toast.dismiss()`. Configure the provider's default viewport with `viewportPlacement` (`bottom-center`, `bottom-right`, `top-center`, or `top-right`) and `viewportStrategy` (`fixed` or `absolute`). For custom anatomy, set `renderViewport={false}`, compose `ToastPortal` and `ToastViewport`, and put `layout="stacked"` or `layout="inline"` on `ToastRoot`. `placement="none"` is available only on `ToastViewport` for anchored/custom positioning. Call `useToastManager()` inside a provider when custom anatomy needs the provider's manager. Create a scoped manager with `createToastManager()`, pass it to `ToastProvider`, and add or close scoped toasts through that manager instead of the default `toast` commands. Never put a destructive confirmation in a toast. Confirmation is `AlertDialog`. --- ## Skeleton vs Spinner vs Progress | | Use when | | ---------- | -------------------------------------------------------------------------------------- | | `Skeleton` | The layout is known and the content is arriving. Prevents the reflow a spinner causes. | | `Spinner` | Work is happening, duration unknown, and there is no layout to reserve. | | `Progress` | You know the percentage. | Prefer `Skeleton` for first paint of a list, card, or panel — it holds the space. Use `Spinner` inside a button, next to an inline action, or in a small region where a skeleton would look wrong. `Skeleton` variants are `line` `block` `circle`. Match the shape of what is loading: `circle` for an avatar, `line` for text rows, `block` for a card or image. A skeleton that does not match the final layout is worse than a spinner. `Spinner` sizes are `xs` `sm` `md` `lg`; `variant` is `default` or `inverse` — use `inverse` on a solid/dark fill. Do not put a `Spinner` in a `Button` by hand — `Button` has `loading` and `loadingLabel` props. `Progress` variants are `primary` `information` `accent` `success` `warning` `danger`; sizes `sm` `md` `lg`. Compose `ProgressHeader`, `ProgressLabel`, `ProgressValue`, `ProgressTrack`, `ProgressIndicator`. If you cannot compute a real percentage, use `Spinner` rather than a fake animated bar. --- ## Badge vs Status Both are small. They say different things. | | `Badge` | `Status` | | -------- | ------------------------------------------------- | -------------------------------------------------------- | | Shape | a pill with text | a dot | | Says | what something _is_ — a label, count, or category | what state something is _in_ — online, healthy, failing | | Has text | yes | no; add an `aria-label` or pair it with text when needed | Use `Status` for presence, health, and liveness. Its `pulse` boolean enables the theme's live-activity treatment; `attention` adds extra emphasis in the elegant theme. Do not animate a dot yourself. Use `Badge` for counts, tags, roles, and environment labels. `appearance` is `solid` `soft` `outline`: - `soft` — ambient metadata, the common case. - `solid` — the badge is the primary signal in its row. - `outline` — the surface is already busy or already tinted. `uppercase` is a boolean; do not `.toUpperCase()` the string yourself. --- ## EmptyState For a surface with nothing to show. Inside `EmptyState`, group `EmptyStateIcon`, `EmptyStateTitle`, and `EmptyStateDescription` in `EmptyStateContent`; place `EmptyStateActions` after that content group. An empty state should say why it is empty and what to do next. Include `EmptyStateActions` whenever the user can act. Distinguish three cases and do not use the same copy for them: - Nothing created yet → invite the first action. - A filter or search matched nothing → offer to clear the filter. - Loading → this is not an empty state, use `Skeleton`. `NotificationCenterEmptyState` is the inbox-specific variant; use it inside `NotificationCenter` rather than the generic one. --- ## Per-component norms **`NotificationCenter`** — set `viewport="desktop" | "mobile"` and `size="sm" | "md" | "lg"` on `NotificationCenterPopup`. Pass `read` to `NotificationCenterItem`, `status="error" | "warning" | "info" | "success"` to `NotificationCenterItemIcon`, and `variant="primary" | "secondary"` to `NotificationCenterActionButton`. Compose item structure from `NotificationCenterItemRow`, `NotificationCenterItemIcon`, `NotificationCenterItemContent`, `NotificationCenterItemTitle`, `NotificationCenterItemBody`, and `NotificationCenterItemActions`. Own read state in the application. **`Status`** — variants are `default` `primary` `information` `muted` `accent` `success` `warning` `danger`; sizes `xs` `sm` `md` `lg`. **`Progress`** — always give it an accessible label through `ProgressLabel`, even when the design shows only the bar.