Add guided onboarding flow for first-time users#1
Merged
Conversation
The tool dropped every visitor straight into the expert dashboard (~15 numeric
fields per car), which is hostile to anyone without car knowledge, and it had no
honest way to compare "I've lost my car — buy an EV or another petrol/diesel?"
because the model hard-coded baseline = keep your current car.
- model.js: key assetValue0() and upfrontCash() off which value field is present
(purchasePrice vs currentValue) rather than role === "baseline", so a pure
buy-vs-buy comparison depreciates each option from its purchase price and reports
each option's own upfront cash. compare() now also returns baselineUpfront so the
verdict can show the cash gap. Kept-car scenarios are unaffected.
- onboarding.js (new): a small, no-free-text step machine. Asks the situation
(keep / replace a lost car / buying next / compare two cars), then a few plain
questions (how far you drive, where you'd charge, rough budget) and builds a
loadTemplate-shaped state from the existing car presets. Shown only on a clean
first visit; shared #c= links skip it. Reopenable via a "Start here" button; Esc
or "Skip — I know my numbers" dismisses it.
- templates.js: new replace-lost-car template (three all-purchase scenarios).
- cars.js: applyCarToScenario gains an { asPurchase } option for bought baselines.
- app.js: wire the overlay, re-key valueField off purchasePrice, and rewrite the
verdict to read in plain language for both keep-vs-switch and buy-vs-buy.
- styles.css: overlay styling reusing the existing design tokens.
- tests: cover field-presence asset value, bought-baseline upfront cash, the kept
baseline regression, and compare()'s baselineUpfront. 17/17 pass.
Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_0189Ph72ijDpwJ5GJrW9S3ui
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
2 participants
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
Introduces a guided "Start here" onboarding overlay that helps first-time users set up a sensible car comparison through plain-language questions, without requiring car knowledge. The flow adapts based on the user's situation (keeping a car, replacing a lost one, buying next, or comparing two specific cars).
Key Changes
New onboarding module (
js/onboarding.js): A step machine that collects answers through fixed buttons and dropdowns (no free-text inputs), then builds a comparison state object matching the existing template shape. Supports four situations with context-specific follow-up questions about mileage, charging, and budget.New "replace-lost-car" template (
js/templates.js): A buy-vs-buy comparison template where all scenarios carrypurchasePrice(nocurrentValue), enabling comparisons between multiple purchase options rather than keeping vs. switching.Updated asset value and cash logic (
js/model.js,js/cars.js): ChangedassetValue0()andupfrontCash()to key off field presence rather than role, so a bought baseline (e.g., replacing a lost car) correctly depreciates from purchase price and reports its own upfront cash instead of £0. UpdatedapplyCarToScenario()to support anasPurchaseoption for baselines that represent a car to buy rather than one already owned.Enhanced verdict messaging (
js/app.js): RefactoredrenderVerdict()to use a newverdictCopy()function that generates context-aware headlines and descriptions for both "keep vs. switch" and "buy vs. buy" scenarios, with proper HTML escaping.UI integration (
index.html,css/styles.css): Added onboarding overlay with styled choice buttons, car selection dropdowns, and navigation controls. Integrated "Start here" button in the header and "Lost your car?" template button. Overlay is shown on clean first visits (no shared URL hash) and can be reopened via the header button.First-visit detection (
js/app.js): Modified initialization to open the onboarding overlay only when no shared comparison is present in the URL, preserving direct links to specific comparisons.Notable Implementation Details
loadTemplate()returns, so the existing rendering pipeline handles it seamlessly.https://claude.ai/code/session_0189Ph72ijDpwJ5GJrW9S3ui