Skip to content

[2026-02-14] Redesign: FTUE Tutorial Gate + Guided First Log

Task Metadata

  • 📆 Date: 2026-02-14
  • 🚥 Status: Plan Approved
  • Beads Issue: 2512_genai_food_tracking-5w8 (in progress)
  • Depends On: docs/project_management/logs/features/2026-01-17_design_first_log_ux.md

The current first-log onboarding still assumes too much Sidecar intuition from a brand-new user. The product technically works, but the user still has to infer:

  • why ChatKcal sends them to another AI app
  • what the AI app is supposed to produce
  • which button matters first
  • what to do when they return

The previous implementation also failed review for a more structural reason: onboarding was additive. It stacked explanation cards beside the real controls instead of turning the first-log journey itself into a guided flow.

Updated user direction (2026-03-08):

  • many first-time users will not naturally understand the Sidecar model
  • if they confirm they are first-time, the product should teach them with a short animated SVG onboarding sequence
  • after the tutorial, the app should make the next click extremely obvious with a guided first-log workflow

Goal: replace additive first-time copy with a more seamless FTUE that teaches the Sidecar model once, then guides the user through the live first-log controls without duplicating the dashboard UI.

Core Product Principle

  • Teach in one contained FTUE surface.
  • Guide in the real dashboard controls.
  • Remove onboarding chrome as soon as the user reaches the actual meal-confirm flow.

Entry Rules

  • Fast-return path: if a valid deep-link meal is already staged, or a pending meal is already present, skip the FTUE gate and land directly in the confirm flow.
  • First-time manual path: if firstLogProgress.totalMeals === 0, no pending meal exists, no valid deep-link meal is staged, and no FTUE decision exists for the current user scope, ask whether this is their first time.
  • Skip-tutorial path: if the user selects I know how, do not auto-open the tutorial. Immediately land in guided_step_copy with compact helper copy and a replay help link.
  • Expert path: if the current scope already records a prior successful first log, migrated FTUE completion, or authenticated cloud-history evidence, skip both gate and guided FTUE and render the standard dashboard action surface with replay help only.

FTUE Gate

  • Show a small first-run modal or sheet on the manual first-log path.
  • Prompt: First time logging with ChatKcal?
  • Primary action: Yes, show me
  • Secondary action: I know how
  • Persistence: store the answer per user scope so the gate is not shown repeatedly.

Tutorial Flow (Animated SVG, 3-4 screens max)

  • The tutorial should be short, visual, and concrete.
  • Each screen answers one question:
    • Screen 1: What does the AI app do?
      • Animated SVG: food photo/text goes into an AI app, structured JSON comes out.
      • Message: the AI app estimates the meal.
    • Screen 2: What does ChatKcal do with that?
      • Animated SVG: JSON flows back into ChatKcal and becomes a saved meal card.
      • Message: ChatKcal stores and organizes the log.
    • Screen 3: What do I bring back?
      • Animated SVG: highlight only the JSON code block, not the surrounding chat text.
      • Message: copy only the JSON result back into ChatKcal.
    • Screen 4: What do I tap first?
      • Animated SVG: highlight Copy Prompt, then show app switch, then return to Paste Meal JSON.
      • CTA: Start first log
  • Motion should use inline SVG + CSS transitions, with a reduced-motion fallback.

Guided First-Log Workflow

  • After tutorial completion, the dashboard enters a dedicated guidedFirstLogMode.
  • This mode must not render the current quickstart card, resumable handoff card, and generic help copy as separate parallel surfaces.
  • Instead, it attaches one compact step header directly to the live action area.

Guided Step Contract

  • Step 1: Copy Prompt
    • Header copy: Step 1: Copy the prompt into your AI app
    • Primary emphasized control: Copy Prompt
    • Secondary escape hatch: Already have JSON? Paste instead
  • Step 2: Use any AI app
    • After prompt copy, reveal quick-switch app targets.
    • Header copy: Step 2: Paste the prompt, add a photo or description, then come back
    • Copy Prompt remains available but becomes secondary.
  • Step 3: Paste Meal JSON
    • On return, or when the user indicates they have the result, move emphasis to Paste Meal JSON
    • Header copy: Step 3: Paste the JSON result here
    • Supporting copy must explicitly remind the user to paste only the JSON result from the AI app.
  • Confirm flow
    • Once a pending meal is staged, onboarding chrome collapses and the normal confirm card takes over.

State Transition Contract

  • gate -> tutorial on Yes, show me
  • gate -> guided_step_copy on I know how
  • tutorial -> guided_step_copy on Start first log or Done
  • guided_step_copy -> guided_step_handoff on successful Copy Prompt
  • guided_step_handoff -> guided_step_paste on:
    • explicit I have JSON action
    • browser/tab return signal
    • any paste attempt
  • guided_step_paste -> confirm on successful meal staging
  • guided_step_paste -> guided_step_paste on invalid paste, with inline recovery only
  • confirm -> guided_step_paste if the user cancels the pending meal while firstLogProgress.totalMeals === 0
  • guided_step_* -> expert immediately after first successful log
  • resume TTL expiry resets guided_step_handoff or guided_step_paste back to guided_step_copy; it must never reopen the tutorial automatically

Resume + Replay Rules

  • Preserve first-log step state after Copy Prompt so a returning user can resume where they left off.
  • If the user returns within 24 hours, still has zero meals, and no pending meal is staged, restore them into the Step 3 paste state instead of showing the full tutorial again.
  • If guest data is promoted into an authenticated account, migrate any FTUE decision and tutorial-complete state from guest scope into the resolved auth scope so the same person is not re-taught immediately after sign-in.
  • If authenticated cloud-history evidence exists, suppress the FTUE gate even if browser-local storage has been cleared.
  • Add a subtle replay affordance near the action area:
    • How do I log again? This should reopen the tutorial, not create a third always-visible onboarding module.

Minimal-Surface Rules (Non-Negotiable)

  • Never show tutorial copy card + handoff card + action buttons simultaneously in first-time state.
  • Never duplicate the same instruction in more than one visible onboarding surface.
  • Never make a textarea or "prepare meal" module part of the default first-log path.
  • Help should replay the tutorial or clarify the current step, not compete with the main CTA.
  • In guided mode, show at most:
    • one primary CTA
    • one secondary action cluster
  • On small viewports, quick-switch app choices must collapse into a compact app launcher or overflow pattern; do not render a three-button app grid plus replay/help affordance in the same guided state.
  • Registration prompts and Trigger B optimization tips must stay suppressed until after the first successful log.

Implementation Strategy

  • Add a scoped local state helper for FTUE decisions and guided-step progress.
    • Tentative key: first_log_ftue_v2:${scopeKey}
    • Tentative fields:
      • gateAnsweredAt
      • selfIdentifiedFirstTimer
      • tutorialCompletedAt
      • activeStep
      • lastPromptCopiedAt
      • migratedFromGuestAt
  • Reuse existing firstLogProgress and handoffResume semantics where possible instead of creating a conflicting second persistence model.
  • Explicitly migrate FTUE-complete and gate-answer state from guest scope to auth scope during promotion.
  • Replace current quickstart/handoff rendering in Dashboard with one derived surface state:
    • gate
    • tutorial
    • guided_step_copy
    • guided_step_handoff
    • guided_step_paste
    • confirm
    • expert
  • Convert HelpModal into the replayable tutorial surface, or replace it with a shared FtueTutorialModal, so the product has one tutorial implementation instead of two.

Non-Goals

  • No backend or schema changes.
  • No redesign of post-first-log registration prompts in this iteration.
  • No change to valid deep-link fast path beyond ensuring it bypasses the FTUE gate cleanly.
  • Pros: teaches the Sidecar model explicitly; makes the next click obvious; preserves a minimal dashboard once the user begins logging; keeps expert and deep-link paths fast.
  • Risks: modal fatigue; first-time detection false positives; FTUE replay across guest/auth/browser boundaries; too much motion; guided mode still becoming visually heavy on mobile.
  • Mitigations:
    • keep tutorial to 3-4 screens maximum
    • allow permanent skip via I know how
    • treat I know how as a concrete path to guided_step_copy, not an undefined expert mode
    • migrate FTUE state across guest -> auth promotion and suppress FTUE when cloud-history evidence exists
    • explicitly teach "copy only JSON" in both tutorial and guided paste state
    • respect prefers-reduced-motion
    • enforce one active onboarding surface at a time
    • keep the guided header attached to the real CTA row rather than as a separate large card
    • enforce a one-primary / one-secondary action budget in guided mode
  • Finalize tutorial screen copy and SVG scene contracts.
  • Finalize gate conditions, including deep-link, skip-tutorial, authenticated-history, and pending-meal bypass rules.
  • Finalize the explicit state transition matrix for copy, return, invalid paste, cancel, and TTL-expiry behavior.
  • Implement scoped FTUE state for gate answer, tutorial completion, and guided-step resume.
  • Implement guest -> auth FTUE-state migration and authenticated replay suppression rules.
  • Replace current quickstart/handoff first-time surfaces with a single guided first-log UI contract in Dashboard.
  • Consolidate tutorial replay into one shared modal component.
  • Update tests:
    • unit: FTUE state helpers and step resolver
    • e2e: gate appears once, tutorial skip path, guided first-log step progression, deep-link bypass
    • visual: first-time guided state and tutorial modal coverage
  • 2026-02-14: Initial tutorial-gate draft created after the first implemented onboarding still felt unclear for brand-new users.
  • 2026-03-08 (Refinement): User clarified that a passive Sidecar explanation is still too unnatural for many first-time users. The preferred direction is:
    • explicit first-time confirmation
    • animated SVG tutorial screens
    • then a guided first-log workflow that makes the next button obvious
  • 2026-03-08 (Constraint): The redesign now treats "single live action surface" as the hard constraint. Education can exist, but it must hand off into the real controls instead of living beside them as additive dashboard chrome.
  • 2026-03-08 (Senior Review Hardening): Tightened the draft to close design gaps around:
    • I know how skip-path destination
    • guest -> auth FTUE state migration
    • explicit step-transition triggers
    • mandatory "copy only JSON" teaching
    • guided-mode action-density budget on mobile
  • 2026-03-10 (Approve): User approved the proposed FTUE tutorial + guided first-log approach and requested implementation to begin, with execution findings and surprises recorded in this log along the way.
  • 2026-03-10 (Implementation): Added scoped FTUE persistence, a replayable FtueTutorialModal, guest -> auth FTUE migration, and a guided first-log dashboard surface that replaces the old additive quickstart/handoff stack for first-time manual entry.
  • 2026-03-10 (Surprise): The first FTUE implementation introduced a React hook-order regression because new effects were added below the settings-loading early return in Dashboard. Playwright caught it immediately; the fix was to move the loading/error return guards below the full hook block so render order stays stable across settings fetch transitions.
  • 2026-03-10 (Surprise): Existing guest E2E flows assumed I know how restored the old expert dashboard surface. The approved spec does not do that; it lands in guided_step_copy. Tests had to be updated to drive the compact guided paste path explicitly instead of relying on the retired shortcut.
  • 2026-03-15 (Review Feedback - Missed in First Design): The first FTUE SVG concept still explained the Sidecar flow too abstractly. What was missing is a simplified but recognizable version of the ChatKcal UI itself, with the key controls highlighted step-by-step so the tutorial teaches the actual product interaction rather than only the data flow.
  • 2026-03-15 (Review Feedback - Missed in First Design): The tutorial also needs to show the outbound AI-app action more concretely: open a recognizable assistant app surface (for example ChatGPT), place the prompt into the composer, and visually show the user pressing Send before returning with the JSON result.
  • 2026-03-15 (Review Feedback - Missed in First Design): The current guided action cluster around Copy Prompt is too messy and choice-heavy (Open ChatGPT, Other Apps, I have JSON). The first pass exposed too many sibling actions at once instead of giving the user one obvious next move.
  • 2026-03-15 (Pivot): The guided first-log surface should move toward a more fluid progressive-disclosure pattern:
    • start with one strong primary action such as Log Meal
    • on interaction, animate that control into a smaller launcher state
    • reveal a compact row of destination actions using icons only for:
      • ChatGPT
      • Gemini
      • Claude
      • clipboard / copy prompt
    • keep the visual emphasis on one expanding interaction rather than a disorganized stack of buttons and escape hatches
  • 2026-03-15 (Design Implication): This means the FTUE flow should teach both:
    • which in-product control starts the journey
    • which external-app action completes the handoff The SVG scenes and live CTA choreography should now be treated as one connected interaction design problem rather than separate tutorial art and button-layout tasks.
  • 2026-03-15 (Review Feedback - Refinement): The tutorial screens should use a simplified ChatKcal mock rather than abstract flow diagrams, so users learn the real control locations and sequence directly from the product-shaped UI.
  • 2026-03-15 (Review Feedback - Refinement): External assistant scenes should use a generic AI-app interface with recognizable app icons rather than full replicas of ChatGPT, Gemini, or Claude home screens. The icons should carry the brand recognition; the surrounding UI should stay simplified and instructional.
  • 2026-03-15 (Review Feedback - Refinement): The primary first action should be framed as Log Meal, not Copy Prompt. That label better matches user intent and supports the progressive-disclosure launcher pattern where the single CTA shrinks to reveal app choices.
  • 2026-03-15 (Review Feedback - Refinement): Copy throughout the FTUE should avoid internal product or architecture jargon such as Sidecar. Tutorial language should stay plain and procedural, focused on what the user should tap, paste, send, copy, and return with.
  • 2026-03-15 (Asset Research): Staged official assistant-brand assets for launcher use in frontend/public/brand-assets/:
    • Gemini: frontend/public/brand-assets/gemini/gemini-icon-64.webp
    • Claude: frontend/public/brand-assets/claude/claude-icon-94.png
  • 2026-03-15 (Asset Research): Gemini was sourced from a Google-hosted product-marketing asset URL surfaced through Google's brand resources and product pages. The file served by Google is an official small icon image, but it is distributed as WebP, not SVG.
  • 2026-03-15 (Asset Research): Claude was harder to source because no public official SVG pack was found. The best official icon-only asset discovered was Anthropic's own support-surface favicon (https://intercom.help/anthropic-6f71807d7c3e/assets/favicon), which resolves to a 94x94 PNG of the Claude burst mark.
  • 2026-03-15 (Asset Suitability): These assets are suitable for the compact launcher row because they function as small supporting identifiers rather than hero branding. That fits the FTUE direction: keep the tutorial and launcher visually grounded in ChatKcal, use the assistant marks only to help users recognize destination choices quickly.
  • 2026-03-15 (Asset Constraint): We still do not have a public official Claude SVG. If the launcher or motion system later requires vector-only assets, Claude may need a follow-up asset pass or a manually approved vector redraw before final polish.
  • 2026-03-15 (Implementation): Applied the revised onboarding direction in the live FTUE:
    • the primary guided entry action now uses Log Meal
    • the cluttered handoff cluster was replaced with a compact launcher row for ChatGPT, Gemini, Claude, and clipboard
    • Grok was removed from the FTUE app choices in favor of Claude
    • the tutorial modal scenes were redrawn around the concrete tap -> paste -> send -> copy JSON -> paste loop
  • 2026-03-15 (Implementation): Updated FTUE copy to use simpler language and avoid internal jargon. The tutorial and guided flow now describe user actions directly instead of referring to product-internal concepts.
  • 2026-03-15 (Refinement): The 5-screen tutorial was still too heavy for a first-time user. The flow was compressed to 3 screens:
    • start with Log Meal
    • use the AI app and press Send
    • come back and press Paste Meal Result The detailed sub-actions still exist, but they now live inside the live UI instead of taking over the tutorial itself.
  • 2026-03-15 (Refinement): Added a short plain-language explanation of why the flow uses an external AI app: the AI app can understand meal details and photos, while ChatKcal focuses on saving and tracking the result over time.
  • 2026-03-15 (Refinement): The final tutorial screen now shows the actual Paste Meal Result button so the return step points at the concrete in-app action the user should take next.
  • 2026-03-10 (Constraint): There is still no reliable authenticated cross-device cloud history signal available in the current frontend state. FTUE suppression now uses local first-log progress, migrated guest state, and meals visible in the loaded session, but true "this returning signed-in user already has remote history on a fresh browser" detection remains partial without additional backend/user-history evidence.
  • 2026-03-10 (Copy Cleanup): Clipboard failure messaging still referenced a manual paste UI that no longer exists. During implementation, that copy was corrected to tell the user to copy the JSON block in their AI app and retry Paste Meal JSON.
  • 2026-03-10 (Verification): The updated flow passes Playwright guest coverage on both functional-desktop and functional-mobile, including the new FTUE tutorial path and the legacy guest actions that now route through guided first-log state. Targeted Vitest utility tests are still blocked in this environment by the existing Bun/Vitest/jsdom worker startup failure (Class extends value undefined is not a constructor or null).

STOP: Do not implement until you approve the Proposed Approach and Execution Plan above.