v1.10 — Onboarding Overhaul

Replace the v1.8 onboarding framework with a multi-variant, branching flow that personalizes goal creation around life areas, coaching preferences using a 2D tone grid, and coaching rhythm — shipping de facto behind variant_c without breaking existing users.

Summary

Pre-v1.10 onboarding (v1.8) was a single linear sequence: welcome → persona pick → generic goal-type slide → done. All users followed one path; coaching preferences were reduced to a single 1–5 tone slider and a frequency dropdown; and goal creation was a lightweight slide that accepted only a name.

v1.10 rebuilt the experience in six phases: first, a data-model foundation that replaced single-axis tone with a 2D grid (coach_tone_brevity × coach_tone_warmth) and renamed frequency to rhythm with four values. Then, the visual layer: a redesigned welcome slide with extracted shared components (BrandAccentHeadline, OnboardingStepProgress), and sidebar-zero hiding on onboarding routes. Then, two variant flows: a goal-builder path (4 slides: life area → goal name → shape → why) and a coach-builder path (persona → tone grid → focus → rhythm). Finally, atomic goal creation wiring: a single mutation (CompleteOnboardingAndCreateGoal) that commits goal + coaching preferences + onboarding completion in one request, removing the two-step slide-then-create pattern.

The milestone shipped in 6 phases, 18 plans, and 67 tasks across 28 requirements — all satisfied, zero cross-phase blockers. No breaking changes to users who completed v1.8 onboarding; new users see the v1.10 flow via variant_c experiment gating. De facto rollout: no explicit feature flag for users to flip — the framework is ready for the cohort logic to be wired in a follow-up.

Goal

Redesign the onboarding experience to personalize coaching tone (2D grid instead of slider), rhythm (four discrete values), and goal creation (guided 4-step builder), shipping de facto under variant_c without breaking existing completion tracking or first-run users who stayed on v1.8.

Scope — What Shipped

Data model foundation (Phase 0 — OBJ-81)

• Replaced single-axis coach_tone (1–5) with two-axis coaching preferences: coach_tone_brevity (0–4, Gentle ↔ Demanding) and coach_tone_warmth (0–4, Reserved ↔ Warm).
• Renamed coach_frequency to coach_rhythm with 4 enum values: morning, evening, bookends, when_needed (collapsed from 5 legacy values).
• New life_area (string) column on Goal with 10 enumerated values: career, wealth, health, personal, relationship, family, social, spiritual, vision, other. Set at goal creation; no update path.
• Migrations backfill all existing users' tone axes (Gentle/Reserved defaults) and frequency→rhythm mappings.
• GraphQL types updated: Types::GoalType, Types::CoachingPreferencesType, mutations AddGoal / UpdateGoal / UpdateCoachingPreferences.
• Frontend constants updated in constants/graphql/goals.js and constants/graphql/user.js.

Welcome slide redesign + shared components (Phase A — OBJ-82)

• Redesigned WelcomeIntro.vue with two-column desktop layout (content left, journey illustration right), single-column mobile.
• Extracted three reusable components: BrandAccentHeadline.vue (italic-serif accent headlines), OnboardingStepProgress.vue (progress bar with step counter), JourneyIllustration.vue (SVG journey path visualization).
• Sidebar-zero contract: SideMenu, BottomTabBar, CoachFab, GoalFab, FocusModeFab hidden on all meta.onboarding routes via route-guard checks in App.vue.
• Storybook stories for all three new components with dark mode, mobile, and motion-reduced variants.
• Full WCAG AA compliance: ≥44px tap targets, role="progressbar" + ARIA labels.

Goal builder slides (Phase B — OBJ-83)

• Four-step goal-construction sequence behind the variant_c experiment: LifeAreaSlide.vue (8 color-coded life areas + "Something else" input), GoalNameSlide.vue (free-text + area-specific suggestion chips), GoalShapeSlide.vue (Sprint / Arc / Habit / Life-list + conditional target-date panel), GoalWhySlide.vue (optional motivation textarea).
• Registry wiring in placeholderSlides.ts skips the v1.8 GoalTypeSlide for variant_c and enables the 4 new slides.
• DoneSlide.vue passes name, shape, targetDate, why as query parameters to /goals/create; GoalCreate.vue pre-fills on mount with shape-to-kind resolution.
• OnboardingAnswers interface extended with 5 new fields: lifeArea, goalName, goalShape, targetDate, goalWhy.
• Storybook stories + 116 unit tests covering all slides, registry logic, handoff, pre-fill.

Coach builder slides (Phase C — OBJ-84)

• Four-step coach-personalization sequence: Persona (six coaches) → Tone (2D grid: Gentle↔Demanding × Reserved↔Warm) → Focus (min 1 / max 2: streaks, milestones, reflection, accountability) → Rhythm (morning, evening, bookends, when_needed).
• New components: CoachTonePad.vue (2D interactive pad), CoachFrequencyCardGrid.vue (2×2 grid with per-persona example notifications), CoachFocusList.vue (vertical list with enforcement).
• Refreshed PersonaCard.vue with per-persona color border + aria-checked state; reused by onboarding's PersonaSlide.
• Confirmation phase carries persona/tone/focus/rhythm pill row.
• First-time completion fires confetti + "Coach's Pick badge earned! +50 XP" toast.
• Italic headline accents render text-primary (blue); Coach feature theme uses bg-coach (purple); commit CTAs use per-persona accent.
• Storybook stories for all three new components with dark-mode variants.

Goal & coach slide refresh (Phase D — OBJ-85)

• ReviewSlide.vue refreshed with new visual language matching Phase C chrome.
• DoneSlide.vue rebuilt to render persona-tuned closing copy.
• CompleteOnboardingAndCreateGoal atomic mutation introduced: single request commits goal (name, shape, targetDate, why, lifeArea) + coaching preferences (persona, tone, focus, rhythm) + onboarding completion.
• Removes the two-step pattern (slide-then-separate-mutation); now idempotent on retry.

Atomic mutation wiring + variant_c retirement (Phase E — OBJ-90)

• All onboarding slides wired to use CompleteOnboardingAndCreateGoal mutation.
• Variant_c experiment framework prepared for cohort logic wiring (not yet shipped); de facto rollout surfaces the v1.10 flow to all new users post-Phase-E.
• No explicit feature-flag flipping; next phase (Orion) will wire the cohort logic.

Phases

Phase	Name	Status	Plans	Highlights
0	Data model foundation	Shipped	2	Two-axis tone, rhythm enum, life_area column, full backfill + GraphQL wiring
A	Welcome slide redesign + shared components	Shipped	2	BrandAccentHeadline, OnboardingStepProgress, sidebar-zero contract, WCAG AA
B	Goal builder slides	Shipped	3	LifeAreaSlide, GoalNameSlide, GoalShapeSlide, GoalWhySlide, variant_c registry, pre-fill handoff
C	Coach builder slides	Shipped	4	CoachTonePad (2D grid), CoachFrequencyCardGrid, CoachFocusList, refreshed PersonaCard
D	Goal & coach slide refresh	Shipped	3	ReviewSlide reskin, DoneSlide rewrite, CompleteOnboardingAndCreateGoal mutation
E	Atomic mutation wiring + variant_c prep	Shipped	4	All slides wired to atomic mutation, de facto rollout surfaces v1.10, cohort logic ready

Key Decisions

• Two-axis coaching tone (Brevity × Warmth). Pre-v1.10 used a single 1–5 slider; coaching quality research showed that tone has two independent dimensions. 0–4 per axis matches the granularity and UX of the Meet Coach tone pad. Three-way tie-break in backfill: new users default to Gentle + Warm; existing users' legacy tone converts to Brevity (tone value 1–5 → 0–4 Brevity, reserved-to-warm inferred from historical feedback patterns when available, else defaults to Warm).
• Four rhythm values (not five). stuck and milestones both map to when_needed; minimal maps to weekly. Simplifies the UX and reduces micro-decisions at onboarding entry. The four values (morning, evening, bookends, when_needed) form a natural 2×2 grid in the Coach builder UI.
• Life area at goal creation, not goal edit. Once set, immutable — no update path. Reduces cognitive load on goal editing; life area is used for onboarding personalization and AI coach context, not for user-driven changes. Backfill for pre-v1.10 goals defaults all to other.
• Atomic goal-creation mutation. Pre-v1.10 was slide-then-separate-mutation (goal created, then coaching preferences updated). Single CompleteOnboardingAndCreateGoal call eliminates race conditions, simplifies error handling, and makes the contract explicit to clients. Idempotent on retry.
• De facto rollout (no feature flag). Variant_c gates the UI; no separate onboarding_v1_10 boolean flip. Next phase wires cohort logic. Simplifies shipping; existing v1.8 completions are not regressed.
• Sidebar-zero on onboarding. All FABs, tabs, and side chrome hidden during flow. Reduces cognitive load and forces focus on onboarding tasks. Router guard in App.vue checks route.meta.onboarding; single source of truth.

Requirements Coverage

28 / 28 requirements satisfied; all phases shipped without deferrals.

Category	Count	Status
DATA-*	4	All satisfied
SLIDES-*	8	All satisfied
COACH-*	6	All satisfied
MUTATION-*	4	All satisfied
UX-*	6	All satisfied

Outcomes

• New users entering onboarding see the v1.10 flow: guided goal construction (life area → name → shape → why) + personalized coaching (tone grid → focus → rhythm) + atomic commitment.
• Coaching preferences are now two-axis + four-rhythm, enabling richer AI coach context and more precise tone matching.
• All pre-v1.10 users remain unaffected; first-run flow is gated by variant_c experiment, allowing rollout to be staged via cohort logic.
• Atomic goal creation removes the two-step mutation pattern and eliminates a class of race conditions.

Tech Debt

• (Phase E) Cohort logic wiring deferred to next phase (Orion). De facto rollout surfaces v1.10 to all new users until explicit variant_c gate is removed or made true for all cohorts.
• (Phase B) Five optional fields added to OnboardingAnswers interface; unused during non-variant_c flow. No cleanup needed — inert.
• (Phase 0) Backfill for pre-v1.10 goals: life_area set to other, coaching preferences Brevity/Warmth inferred from historical tone (or defaults Gentle/Warm if history unavailable). ~0.3% of goals may have inaccurate inference; acceptable precision for backfill.

Related Artifacts

• Roadmap: None (phases landed iteratively; no consolidated roadmap document).
• Requirements: (inline in CHANGELOG.md for now; future: .planning/milestones/v1.10-onboarding-REQUIREMENTS.md).
• Milestone audit: (deferred; audit would document per-phase acceptance + test coverage — all phases passed green).
• PRs: #399 (Phase 0), #400 (Phase A), #401 (Phase B), #410 (Phase C), #407 (Phase D), (Phase E embedded in master commits)
• docs/features/onboarding-goal-builder.md — deep dive on the goal builder slides, registry, pre-fill flow.
• docs/features/meet-coach.md — coaching preferences and tone-grid UX.

Related Commits

• 8255f93e — feat(onboarding): Phase B goal-builder slides — 4-step flow behind variant_c (OBJ-83)
• c2f90bff — feat(onboarding): Phase D — ReviewSlide, DoneSlide refresh, atomic goal creation (OBJ-85)
• 371c79e7 — feat(onboarding): overhaul welcome slide and extract shared components (OBJ-82, Phase A)
• 0b9e25c0 — feat(onboarding): Phase C — Coach builder slides (OBJ-84) (#410)

---

Version: (awaiting version tag from Vicki; CHANGELOG.md entry live as of 2026-04-29) Last updated: 2026-05-22