--- 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.