| name | premium-onboarding |
| description | Implement or evolve a premium multi-step onboarding flow for SFK-first SwiftUI apps. Use when adding first-run setup, marketing → personalize → demo → permission → paywall sequences, onboarding progress flags, shared footers, or enum-driven onboarding CTAs. |
Premium Onboarding
When to use
- Building or refactoring first-run / resume onboarding
- Designing step order, shared footer CTAs, or presentation vs progress flags
- Wiring notifications / paywall steps after value is shown
- Porting the narrative shape to a new product
Non-goals
- Dumping Windfall/MoneyTracker source files into another app
- Replacing SFK onboarding primitives with one-off progress UI
- Product copy that belongs only in the host app's module doc
Read in order
- SFK primitives —
SwapFoundationKit/Docs/capabilities.yaml (onboarding domain) and SwapFoundationKit/Docs/guides/onboarding.md
- This kit's playbook —
../../product/onboarding.md
- Host app module map (if it exists), e.g.
Docs/modules/onboarding.md
Decision: prefer wrap_sfk — SFK owns progress/typography/cards/buttons; the host owns the story and state machine.
Invariants
- Narrative shape: Attract → Personalize → Validate → Demonstrate → Ask → Deliver
- Enum is the single source of truth for step order, scroll vs fixed layout, shared footer, CTA titles
- Presentation flags ≠ progress flags (launch / resume / debug / preview)
- Coordinators own sheets (account entry, system settings, pro paywall)
- Shared footer via bottom safe-area bar +
SFKButton; specialized steps may own their own CTA
- Ask for notifications / purchase only after value is visible
- Previews use
*PreviewSupport with explicit deps — no fake coordinator inits
- Full-screen onboarding exits through one opaque hosting surface; animated child
views never bypass the coordinator with production environment dismissal
- Timed progress and staged-card haptics share explicit animation phases, run in
cancellable tasks, and cannot replay because SwiftUI recomputed a view
Workflow
- Check SFK onboarding domain; reuse progress, typography, cards, buttons.
- Define
OnboardingStep (or equivalent) with computed chrome properties.
- Implement dual flags + presentation intent matrix from the playbook.
- Build the shared setup shell + footer; specialize only when permission/monetization/timing differ.
- Wire coordinator delegate methods for complete / dismiss / nested entry / pro sheet.
- Add the single-layer hosting-controller dismissal pattern from playbook §7.1
when the flow contains continuously rendered or UIKit-backed content.
- Add analytics funnel events and accessibility identifiers.
- Synchronize processing pulses and staged-card impacts with authored phases;
collapse the sequence for Reduce Motion.
- Walk the playbook migration checklist and definition of done.
Checklist
Use the checklists at the bottom of product/onboarding.md
(migration + DoD sections). Verify final and marketing-only dismissal frame by frame;
an accessibility-tree transition alone cannot detect orphaned render layers. Do not
mark onboarding done until those checks pass.
