---
name: Onboarding Flow (Figma)
description: First-time user onboarding for a web or desktop product — welcome screens, guided tour, progressive disclosure checklist. Gets a new user to their first meaningful action.
triggers:
  - onboarding
  - onboarding flow
  - user onboarding
  - getting started
  - product tour
  - welcome flow
  - first-run
cd:
  mode: flow
  platform: figma-responsive
  scenario: product
  preview: figma_frames
  fidelity: high
  speaker_notes: false
  animations: false
  featured: true
  design_system:
    requires: true
    sections: [palette, type, spacing, components]
  craft:
    requires:
      - typography
      - typography-hierarchy
      - color
      - anti-ai-slop
      - accessibility-baseline
      - state-coverage
      - laws-of-ux
  inputs:
    - product (one-line)
    - first meaningful action (the "aha" moment — what should the user accomplish in ≤ 3 minutes?)
    - prerequisite data (what the product needs to know about the user before activation)
  parameters:
    - canvas (default 1440 desktop; also 375 mobile)
    - style (default checklist + in-app tour; alternatives: fullscreen wizard, empty-state prompts)
  outputs:
    primary: figma_frames
    capabilities_required:
      - figma_execute
  default_for:
    - onboarding
    - getting-started
  example_prompt: "Onboarding for a team collaboration tool — 4-step checklist + 2 in-app tooltips, aha moment is 'first message sent in a channel'"
---

## The aha moment is the whole brief

Every onboarding design is answering one question: **how do we get the user from signup to the first moment this product actually helps them — as fast and unambiguously as possible?** Write that moment down before touching Figma. If you can't articulate it in one sentence, onboarding is the wrong problem to solve; come back after the product team defines activation.

A good onboarding flow removes ceremony. Every screen, step, and tooltip either shortens the path to the aha moment or gets cut.

## Three styles — pick one deliberately

Don't stack them. Each has a right brief:

- **Fullscreen wizard** (3–5 modal screens covering the full viewport) — use when the product can't work without setup data (workspace name, team invites, initial integration). Feels heavy; reserve for genuine blockers.
- **In-app checklist** (persistent 4–6 item list, usually in a side panel or a dismissible card) — use when the user can explore freely but benefits from a "here's where to start" nudge. The default for most SaaS.
- **Empty-state prompts** (each empty section of the product has a specific CTA + short explainer) — use when the product has many entry points and onboarding should be contextual. Pair with a minimal welcome screen if it's the user's very first visit.

Hybrid: welcome screen → skip-able wizard for the 1–2 required setup questions → persistent checklist for everything else. That's what Linear, Notion, and Height ship.

## Canvas

- Desktop: 1440 wide. Modal wizards: 560–640 wide centered cards. Checklist: 320–360 wide side panel or 480-wide dismissible card in the empty product shell.
- Mobile: 375 wide. Wizards become fullscreen; checklist becomes a collapsible sheet.

Render each state, not just the happy first screen.

## Wizard screen anatomy

If using the fullscreen or modal wizard style:

- Progress: dots or numbered "Step 2 of 4" at top. Always visible.
- One clear decision per screen — name the workspace, invite teammates, pick a first project. Don't bundle two decisions.
- Skip affordance: text link, bottom-left, unambiguous ("Skip for now"). Users who skip are fine — they'll get the checklist later.
- Primary CTA bottom-right ("Continue" / "Create workspace"). Disabled when required fields are empty.
- A back arrow in the top-left. Always.

Never more than 5 wizard steps. Four is the upper bound for most products. If you think you need more, move the extras into the post-wizard checklist.

## Checklist anatomy

A good checklist is visible, scoped, and finite:

- Title: "Get set up" or product-specific ("Ship your first deploy"). Not "Welcome".
- 4–6 items, no more. Each item is a single short verb phrase ("Invite a teammate", "Connect your repo").
- Each item has 3 states: incomplete (circle + label), in-progress (half-filled circle if applicable), done (checkmark + struck-through label, muted).
- Optional progress bar at the top showing N/6 complete.
- Collapsible so users who don't want the nag can hide it. Hidden state shows a small "Setup 4/6" indicator.
- Auto-dismiss when 100% complete. Don't leave a fully checked list sitting there forever.

Items link into the product — clicking "Invite a teammate" opens the teammates modal with onboarding-aware empty state ("Invite your first teammate to…").

## Welcome screen

If there's exactly one welcome screen before the product:

- Headline: personal and specific ("Welcome, Amina. Let's set up your workspace."). Not "Welcome to Product."
- Sub-headline: sets the expectation — how long this takes, what they'll accomplish ("Takes ~2 minutes. You'll create a workspace and invite teammates.").
- CTA: one verb ("Get started"). Optional secondary link ("Skip the tour").
- No feature showcase. This is not a landing page.

## Progressive disclosure

Don't teach everything upfront. Teach-as-you-go:

- First time the user opens a new area, show a small tooltip or empty-state prompt explaining its purpose. Dismiss once, never again.
- Advanced features stay hidden until the user's behaviour suggests they're ready.
- Never cover the product with a multi-step tour that darkens the UI. It feels like a tax.

## Tooltip discipline

If you use tooltips as part of onboarding:

- 1–2 sentences max per tooltip. A verb-led headline + one explanation.
- Pointer (arrow) attached to the specific element. No floating tooltips that point at nothing.
- "Got it" dismissal button; optional "Show me" CTA that performs the action for the user.
- Queue tooltips — one at a time. Stacked tooltips are a failure mode.

## Copy discipline

Onboarding copy sets the voice for the whole product. Key rules:

- Human, not "we welcome you to the Product Family." Say "Welcome" once if at all.
- Specific: "Connect your GitHub repo to see deploys here." not "Set up integrations to unlock powerful features."
- Actionable: every step title is a verb phrase the user performs, not a noun.
- Never marketing-copy: no "revolutionise", no "unlock", no "unleash your productivity."

## Anti-patterns

- 6-step tour that dims the whole UI at each step. Users click through on autopilot and learn nothing.
- A welcome modal that can't be closed. Always provide an escape.
- Faux-personal copy with a fake user's name ("Great choice, Alex!"). If you don't know the name, don't fake it.
- Onboarding that requires setup steps the user can't yet do ("Connect your Slack workspace" before the user has a workspace).
- A checklist with 10+ items. You're listing features, not onboarding.
- Confetti / celebration animation on every single checkbox complete. One celebration at 100% is enough; more is noise.
- Invented social proof ("Join 50,000+ teams already set up!") unless the brief supplied the number.

## State coverage

Render every major state in the Figma file:

1. **First-visit welcome** (if applicable).
2. **Wizard step 1, step N, and success** — not just the middle screen.
3. **Checklist at 0/6, 3/6, and 6/6 (dismissed)**.
4. **Empty-state prompt** for one typical product area with the onboarding pointer active.
5. **Dismissed / hidden onboarding** — what the product looks like once the user has completed or hidden everything.

## Accessibility

- Keyboard-navigable wizard (tab through fields, Enter to advance, Escape to skip).
- Tour tooltips trap focus until dismissed.
- Progress indicators announced (aria-live="polite" on the step counter) — documented in Figma notes.
- Minimum tap target 44×44 for all onboarding controls.

## Quality bar

Read the flow without the brief. Can a stranger figure out what the product does and what they're supposed to do first, using only the onboarding copy and CTAs? That's the test. Run `craft_lint` across all wizard and checklist copy before replying.
