Skip to content

Finish setting up card

The admin home page card that tells a merchant what the features their shop uses still need, with matching badges on the Settings tiles. What it checks and how it works are in Finish Setting Up. This page records the design decisions.

Decisions

  • Worked out on demand, never stored by a job. A site could be set up halfway with nothing to say so. The Clatter demo had till staff with no Terminal location, no Stripe and central sign-in on without a client. A scheduled job would keep a stored list that goes stale between runs. Instead, each feature has a check that reads the live state every time someone looks. The only stored data is the merchant's "Not needed" choice. If weekly emails or a cross-site superadmin view are added later, they should call the same service rather than keep a copy.
  • Only the features the shop uses. A shop that doesn't seat guests never sees dining items, so the list is short and every line applies to that shop.
  • Above the sales figures, full width. A new shop's sales figures are all zero, so setup is the most useful thing on the page. The card goes away once nothing is outstanding, rather than staying as a "you're all set" card.
  • One sentence per item, then the fix. Each item has a small uppercase feature label, then one plain sentence saying what's missing and what it stops working, then a button that goes straight to the screen that fixes it. Only the first item's button is primary, so the page has one obvious next step.
  • Waiting items show, without a button. An item that depends on another (a card reader before the Terminal link) shows greyed with a lock and "Waiting: …". Hiding it would make the list look shorter than the work really is.
  • "Not needed" rather than a hard rule. Some checks can't tell a mistake from a choice: a café on Tap to Pay has no reader to register, and blank tip suggestions may be deliberate. A dismissed item moves under "Show done" with Put back, and no longer counts.
  • Progress counts done against done plus outstanding, leaving out dismissed items, so dismissing something doesn't look like progress.
  • Plain forms, no script. The fold is a native <details>. Not needed and Put back are plain POST forms that return to /admin/home#setup.
  • Settings badges use the same items. A tile shows "N to set up" (bx-badge--warning), and the section's page lists its items in a warning callout at the top, so someone who starts from Settings sees the same list.

Rules a later change must keep

  • No item text names a class, config key or internal status. A merchant has to understand it.
  • Every to-do item has an action that goes to the screen that fixes it, not to a help page.
  • Checks read through services and stay cheap. Anything that calls Stripe or another outside service is cached for minutes, and a failed call leaves the item out rather than showing it wrong.
  • The card is only for people who can change settings (AdminAccess.settings()).

Mock-ups

  • 2026-10-26, Claude artifact "Finish setting up card": the admin home card with three to-do items, one waiting and the done fold, plus the Settings tiles with badges. The shipped card follows it, except that the header gives a count instead of the mock-up's line about card payments.