Build a first-run checklist that gets a new operator to their first real action

Overview

A persistent checklist that lives in the corner of the app shell. Each item is a real task the user can click to start, and each item auto-ticks itself when the underlying app state changes.

The first 20 minutes of a new operator's session decide whether they ever come back. The job of the checklist is to point at the next concrete action — "connect a bank so payouts work" — not to walk them through a guided tour. SMB software wins by getting the user to a useful action fast; the checklist is the cheapest way to surface what "useful" means for your product.

Never show 0 / 5. The "create your account" step is already done by the time the user sees the checklist — so day one starts at 1 / 5, with momentum. Zero feels like work; one feels like progress.

Auto-detection beats a manual "Mark done" button every time. If the user invited a teammate via Settings, the checklist ticks the row on its own — no second-class "I did it" button. The only manual tick is "Dismiss this checklist", which is permanent and per-user.

Skip this recipe if your app has one job and no setup. A barcode scanner that opens straight to the scan view doesn't need a checklist — the only first action is "scan".

What you'll build

Three states: first open (1 of 5), partway through (3 of 5), and the only screen we let confetti onto — 5 of 5.

Required pieces

Everything this recipe pulls from @corelithzw/react.

@corelithzw/react exports used here: Stack, Checklist, Checkbox, Button, Alert. Checklist is a thin block that renders progress + items; everything below composes it.

Step-by-step build

The checklist is a list of Task records, each with an isDone predicate that reads from app state. The component renders the list — it never branches per task. That way adding a sixth task is one line, not one component.

Dismissing the checklist is a per-user, per-device preference. A round trip to the server to write a single boolean is wasted bytes. Read once on mount, write once on dismiss, and never mention it to the API.

Progress lives at the top so the user sees the trend before they see the list. The "n of m" counter is always n ≥ 1 — that's the opinion: a 0-of-5 checklist looks like an unread inbox.

Confetti on partial progress trains the user to dismiss every micro-win. Save the celebration for complete === true, run it once, and then hide the checklist on the next render. The dismissal-on-completion is auto so users don't have to think about cleaning up.

Final composition

The whole OnboardingChecklist, assembled. Task list + auto-detection + dismissal + celebration.

Variations

Three common forks. Each is a small diff from the final composition.

// Add a role gate to each task
const ROLE_TASKS: Record<Role, string[]> = {
  owner:  ['email','team','bank','tax'],
  clerk:  ['email','sale'],
};
const visible = TASKS.filter(t =>
  ROLE_TASKS[role].includes(t.id));

// Replace useDismiss with a hook
const { mutate } = useUserPrefs();
const dismiss = () => mutate({
  checklistDismissed: true,
});
// Initial value from server-loaded user
const dismissed = user.prefs.checklistDismissed;

// In the parent
{!complete && (
  <OnboardingChecklist ... />
)}
{complete && <Dashboard />}
// Inside, drop the dismiss button

Accessibility

What this recipe takes care of for you.

• Progress is announced. The progress bar uses role="progressbar" with aria-valuenow/aria-valuemax so screen readers read "3 of 5 done" when focus enters the panel.
• Done items are read as done. Each Checklist.Item uses aria-checked="true" on its disc icon, not a strikethrough alone — strikethroughs are visual only.
• CTAs are real links/buttons. The "Connect" button is a Button as="a" with href so screen readers describe the destination, and middle-click works.
• The celebration is a live region. role="status" + aria-live="polite" on the success alert — the announcement lands once, not on every re-render.
• Dismiss is keyboard reachable. The "Hide this checklist" button is a real Button in tab order, not an overlay X.
• Confetti respects motion preferences. The fire-and-forget animation skips when prefers-reduced-motion: reduce is set.

Related recipes

The other recipes that pair well with first-run setup.