First-run onboarding guides new users through setup with dialogs, checklist panels, and progressive disclosure. Compose with Dialog, static panels, and Button — keep one focus per step.
What this pattern covers
Onboarding appears after signup or first login:
Welcome Dialog — short value prop + primary action
Checklist panel — static Column surface with completed steps
Start with a controlled Dialog — not a full-page modal route. One headline, two sentences, one Button:
<Dialog
isOpen={showWelcome}
onClose={() => setShowWelcome(false)}
title="Welcome to your workspace"
footer={
<Row gap="12">
<Button onClick={startTour}>Get started</Button>
<Button variant="secondary" onClick={() => setShowWelcome(false)}>
Skip for now
</Button>
</Row>
}
>
<Column gap="16">
<Text variant="body-default-m" onBackground="neutral-weak">
Connect your repo, invite teammates, and ship your first page in under ten minutes.
</Text>
</Column>
</Dialog>
Persist showWelcome in user preferences or localStorage so returning users are not blocked.
Checklist panel
Replace interactive Cards with a static surface panel listing setup steps:
Describe in prose: wire ProgressBar below the heading when you want a completion percentage — pass value as 0–100 based on done count.
Empty dashboard with guided CTA
When data is empty because the user has not finished setup, use onboarding copy — not generic “No data”:
Differentiate from Empty & error states: onboarding empty states assume the user is new; filtered-empty uses “Clear filters” instead.
Profile completion nudge
In Settings & split panels, highlight incomplete fields with Feedback at the top of the active section:
Dismiss the Feedback when required fields validate. Do not stack multiple Feedback rows — one nudge per section.
Multi-step vs checklist
Pattern
When
Surface
Checklist panel
Parallel tasks, any order
Static Column on dashboard
Stacked dialogs
Sequential wizard, 3–4 steps
Controlled Dialog per step
Inline empty state
Single critical first action
Centered Column in main area
For stacked dialogs, see Dialog & modal — advance step state in the parent and swap Dialog body content. Keep footer actions consistent: Back (secondary) + Continue (primary).
Agent checklist
When generating onboarding from settings or auth task bundles:
Welcome Dialog is dismissible — never trap users
Checklist uses static panels, not Card without onClick
Empty dashboard copy explains the next action, not the absence of data
One Feedback nudge per settings section
Progress tracked in parent state, not inside presentational components
Write this / not this
✅ Once UI way
❌ Common mistake
Dismissible welcome Dialog
Full-screen blocking overlay with no skip
Checklist in surface Column
Card rows without interaction
“Create first X” onboarding copy
Generic “No results” on first visit
One primary action per step
Three competing Buttons in welcome modal
Check yourself
Welcome dialog can be skipped and stays dismissed
Checklist steps show done vs pending with Icon affordance
Empty dashboard CTA matches the actual first-run flow
<Column fillWidth center padding="48" gap="16" maxWidth="xs">
<Icon name="rocket" size="l" onBackground="brand-medium" />
<Heading variant="heading-strong-s" align="center">
Create your first project
</Heading>
<Text variant="body-default-s" onBackground="neutral-weak" align="center">
Projects appear here once you import a repo or start from a template.
</Text>
<Button arrowIcon>New project</Button>
</Column>
<Column gap="24">
<Feedback
title="Complete your profile"
description="Add a photo and display name so teammates recognize you."
variant="info"
/>
{/* profile form fields */}
</Column>
