First-run Checklist

• After sign-up and setup, inside the product: a handful of first actions (a project, an invite, an integration) people do in the real UI, not in a wizard.
• When the actions happen in different places and in any order, so each must tick where it really happens.
• When progress should survive a reload and the checklist should get out of the way, folded into a ring, until it is done.

• Questions to answer before the product is usable: a step-by-step flow on Onboarding Shell, such as Workspace Setup.
• A list on a settings or home page that ticks when its own button is pressed: Onboarding Checklist on its own.
• Pointing at one control at a time: a tour with a spotlight.

import { FirstRunChecklist, useFirstRunChecklist } from "@/components/eased/first-run-checklist/first-run-checklist";const ITEMS = [  { id: "project", title: "Create your first project", description: "Projects hold your issues and docs.", action: "New project", minutes: 1 },  { id: "invite", title: "Invite your team", action: "Invite people", minutes: 1 },  { id: "github", title: "Connect GitHub", action: "Connect GitHub", minutes: 2 },] as const;export function GettingStarted() {  const router = useRouter();  const checklist = useFirstRunChecklist({    items: ITEMS,    persist: { key: `lumen:first-run:${user.id}` },    onComplete: () => api.markSetUp(),  });  // Wherever the action really happens: checklist.complete("project")  useEvent("project.created", () => checklist.complete("project"));  return (    <FirstRunChecklist      checklist={checklist}      onOpen={(id) => router.push(`/start/${id}`)}      next={[{ id: "cycles", label: "Plan your first cycle", onSelect: () => router.push("/cycles") }]}      className="fixed bottom-4 end-4"    />  );}

Share the controller through context or your store, so the page where a project is created can call complete("project").

Start folded

Show the ring button first, and let people open the list when they want it.

<FirstRunChecklist checklist={checklist} defaultCollapsed className="fixed bottom-4 end-4" />

Keep the done state on your server

persist takes any StepsStorage, so progress can follow someone across devices.

useFirstRunChecklist({  items: ITEMS,  persist: {    key: user.id,    storage: { get: (k) => api.getProgress(k), set: (k, v) => api.saveProgress(k, v), remove: (k) => api.clearProgress(k) },  },});

useFirstRunChecklist

Returns { flow, done, complete(id), undo(id) }. flow is the useSteps flow underneath: complete is its mark(id, "complete"), and it calls finish() when the last item lands.

FirstRunChecklist

• The panel is a labelled region; each item's tick is a checkbox named by its label, so it can be marked done by hand.
• The line under the title ("3 steps left, about 4 min") is a polite live region, so a tick made elsewhere in the app is announced.
• The folded button says how many are done ("Get started, 2 of 5 done") and is aria-expanded="false"; folding and opening move focus between it and the hide button.
• An item's action leaves focus alone, so your onOpen can move it into the part of the app it opened; the item stays open until you call complete.

The signature is the checklist reacting to the app: when an action happens elsewhere, the matching item's tick draws, its label strikes through left to right, the ring fills on smooth and the count rolls, with the next item unfolding. The panel and the ring button swap from the bottom corner (rise 6px from 0.97 on the enter curve; leave 3px to 0.98 in 100ms), and the folded ring keeps filling. Once everything is done the list folds into its Done pill, the title swaps to "You’re set up" and what's next opens under it on a height spring. Reduced motion: states change at once and the swaps fade.

Use it inside the product after setup. Call complete(id) where each action really happens (the create handler, the invite response, the OAuth callback), never from onOpen. Give persist a key per person.

Don't rebuild the list, ring or ticks: they are Onboarding Checklist's. Don't put it in a dialog or a page; it is a floating dock, positioned with className.

• Onboarding Checklist: the list, ring and ticks under this dock.
• Workspace Setup: the flow before it.
• Onboarding Shell: the step engine and frame for wizard-style flows.
• Onboarding set: Workspace Setup, Team Invite and this checklist chained into one first run.