Saleor Dashboard Feedback

Saleor Dashboard Feedback

How merchants learn that something worked, failed, or needs attention — without offloading triage into toasts.

Inspired by Geist Toast and Vercel product UI discipline. Implement with macaw-ui-next + useNotifier / our toast queue — do not install Geist packages.

Also see: saleor-dashboard-entity-detail (page anatomy), saleor-dashboard-microcopy (hint copy), toast implementation under src/components/notifications/.

Principle

Feedback lives next to the problem when the merchant must act. Toasts acknowledge terminal, non-blocking outcomes of an action they just took.

If a toast is the only place the full error exists, the design is wrong.

Channel ladder (pick the lowest that fits)

Never use a toast alone for: billing/permission denials, multi-step triage, field validation, or setup blockers.

When to use a toast

Do toast

• Success after Save / create / delete / assign the merchant just triggered
• Short failure of that same action when the page already shows context (or a one-line recovery is enough)
• Undo-style confirmations with a single action (Undo)
• Terminal state of an async flow (one toast at the end — not start/middle/end)

Do not toast

• Narrating a multi-step mutation sequence (Saving… → Validating… → Saved)
• Dumping raw GraphQL / API payloads or stack traces
• Repeating the same error on every keystroke or every failed field
• Anything the merchant must still fix on this page without a matching inline/banner home
• N toasts for N row failures — aggregate (3 codes couldn’t be deleted)

Pairing rule (Geist)

For serious failures, prefer:

1. Short toast (≤ ~6 words in the title sense): Couldn’t save voucher
2. Persistent surface with the recovery step and enough identity to act

Toast:  Couldn’t save voucher
Page:   banner or field — “End date must be after start date.”

Toast quality bar

Our queue: max 3 visible, FIFO overflow, dedupe by status + title, dismiss-visible only when 2+ show. Errors and actionBtn stay until dismissed (getNotificationDuration → Infinity). See notificationQueue.tsx.

Copy

• Sentence case. Single-sentence success: no trailing period.
• Error: use Couldn’t for user/state issues; Failed to for system/infra — stay consistent in one flow.
• Match the button verb: Delete → … deleted, not … removed.
• Title carries the punch; description is optional context — not a paragraph.
• Prefer existing commonMessages / feature messages over one-off strings.

Length

Sonner/Geist do not ship show-more. Canonical fix is shorter copy.

• Default: title only, or title + ≤ 2 short lines of description.
• Our Toast clamps long descriptions (2 lines + chevron) as a safety net for legacy/API text — do not rely on it for new work.
• If the full message needs reading time, it belongs in a banner/dialog/checklist, not the toast.

Behavior

• One terminal toast per user action.
• Deduping replaces same status + title — update description if the detail changed; don’t spam.
• Bulk: one aggregated notify, not a toast per row.

useNotifier checklist

notify({
  status: "success", // or error | warning | info
  title: intl.formatMessage(messages.voucherSaved), // prefer explicit title
  // text: optional short description
  // actionBtn: only when a single recovery/undo is real
});

• Prefer explicit title; don’t lean on generic “Error” / “Success” defaults for product flows.
• Pass actionBtn only for a safe, single next step (Undo, Open settings) — not primary navigation dumps.
• On save failure: map GraphQL errors to fields/sections first; toast is the ack, not the encyclopedia.

Decision tree

Did the merchant just complete an action?
  no  → persistent UI only (banner / checklist / empty state). No toast.
  yes → Did it succeed?
          yes → success toast (short). Done.
          no  → Can they fix it on a specific field/section?
                  yes → inline/section error + short error toast (optional if inline is obvious).
                  no  → Is it a page-level / permission / readiness issue?
                          yes → banner or checklist + short error toast.
                          no  → short sticky error toast with recovery sentence;
                                file a follow-up if this keeps happening (wrong surface).

Dogfood: vouchers (first)

Use this skill when touching src/discounts/ voucher create/details/list.

Audit checklist

• Save success → one Voucher saved / Changes saved toast; no second toast from the same submit
• Field validation (dates, limits, codes) → inline / section errors; toast does not carry the full validation list
• Code bulk delete / generate failures → aggregated toast; row/section detail if the merchant must retry specifics
• Permission / channel blockers → banner or checklist, not toast-only
• No toast on every codes-table refetch or filter change
• Error toast copy: couldn’t/failed + recovery; sticky by default (or autohide when paired with inline/section); no raw API blob in text
• Action buttons on toasts only for real undo/recovery (not “Close”)

Anti-patterns to remove when found

// ❌ Toast-only validation
notify({ status: "error", text: errors.map(e => e.message).join(", ") });

// ❌ Narrating the flow
notify({ status: "info", text: "Saving voucher…" });
notify({ status: "success", text: "Voucher saved successfully." });

// ✅ Terminal ack + inline home for the problem
form.setError("endDate", { message: intl.formatMessage(messages.endBeforeStart) });
notify({
  status: "error",
  title: intl.formatMessage(messages.couldNotSaveVoucher),
  text: intl.formatMessage(messages.checkHighlightedFields),
  autohide: PAIRED_ERROR_NOTIFICATION_SHOW_TIME,
});

Implementation map

Restraint tests

Before shipping feedback:

1. Squint test — can you tell success vs failure in under a second?
2. Absent-toast test — if the toast never appeared, could the merchant still recover from on-page UI?
3. Tall-toast test — if description needs show-more, shorten the copy or move it out of the toast.
4. Stack test — would a slow merchant still see the important message with max 3 + FIFO? If not, it shouldn’t be toast-only.