feat(web): simpler, hand-drawn onboarding focused on Loom, recording and uploads

[richiemcilroy]

Replaces the five-step web onboarding (name, organization name and logo, custom domain upsell, seat pricing, desktop download) with a short flow built around what people came to do: move their videos from Loom, record a video, upload a video, or join a team they were invited to.

The new flow is: say your name, pick where to start, then do it. Each path page has a looping hand-drawn explainer in the same doodle style as #2312 (boiling ink outlines, strokes that draw themselves, and a demo cursor). The cursor acts out the task in three phases, and the three numbered steps beside it light up in sync, so it's clear what to do and what happens next. Everything works in light and dark, following the device setting, with a toggle in the header.

New account

The name step opens with "Hey, welcome to Cap" and a waving hand that waves twice on arrival and again on hover, with two small hand-drawn motion marks. It has a single field. Your organization is named after you automatically (you can rename it in settings), so the separate organization step is gone.

The preview on the right is a faithful miniature of a real Cap share page: a cap.link address bar, the title, a Copy link pill, and the owner row with your avatar and name filling in as you type. Below that, the player shows a sketched roadmap being walked through, a webcam bubble, and a playhead that moves. The only motion is what a real video would do: the presenter's cursor drifts to a card, circles it in ink, and the circle fades as the video plays on.

The start step offers three cards, Loom first, plus "I'll look around first". The Loom card says up front that you can paste one link or bring a whole library over with a CSV. People who sign up with Google already have a name, so they skip straight here. Until now they skipped onboarding entirely.

Bring videos from Loom

• The link is checked as soon as you paste it: a drawn tick when it's valid, a plain-language error when it isn't. The hint under the field explains where to find the link on Loom.
• Bulk import from a CSV is front and centre, so people with lots of videos aren't put off. The intro mentions it, and a "Moving lots of videos?" card explains you can import up to 500 links at a time from a spreadsheet, with a template, and send each video to the right person and space. Owners and admins get the button; members are told to ask an admin. Sign-ups that arrive from the CSV link see the card highlighted.
• Pro accounts import right on the page and get a success state, a hand-drawn circle and check, with "Go to my Caps" or "Import another".
• Loom import stays a Pro feature. Free accounts see an honest note with a link to record for free instead. Upgrading from this step returns to it with the link still filled in, and the page waits for the upgrade to confirm.
• Sign-ups that start from the "migrate from Loom" pages (/signup?next=/dashboard/import/loom?url=…) land on this step after the name step, with their link already filled in.

Record

"Record in your browser" is the fastest option and opens the browser recorder straight away (/dashboard/caps/record?recorder=browser). There's also the desktop app, with your platform detected and short install steps after you download, and the Chrome extension, shown only in Chrome. On phones the app card offers to copy the download link instead.

The explainer records the same sketched roadmap shown in the share preview, with the presenter circling a card while it records, so the pages tell one story.

Upload

The dropzone has a hand-drawn border and works with drag and drop, click or tap. Progress uses the squiggle line from #2312, and the finished state links straight to the new video. Uploads stay Pro-only, with the same upgrade-and-return behavior as Loom.

Joining a team

The invite page now matches the rest of onboarding and has its own explainer. When you're signed out, Join goes to sign-up and brings you back to the invite. When you're signed in as the invited address, it's one click and you land in onboarding with your team's name. When you're signed in as someone else, the page says so up front and offers to switch accounts, instead of failing with a toast after you press Accept. The invited address is partly masked.

Dark mode

• Onboarding and invites follow the device setting by default. The page is rendered on the server with data-theme="system" and a prefers-color-scheme rule, so there's no flash.
• The header has a hand-drawn sun or moon toggle. It saves the same theme cookie the dashboard uses, so your choice carries over. The icon and label are switched in CSS, so the server and client render the same markup.
• If you finish onboarding on a dark device without having picked a theme, the dashboard opens in dark too.
• While onboarding is open, body gets the resolved theme, so the upgrade dialog and toasts match.
• Every scene and component uses theme tokens: ink becomes warm off-white on charcoal paper, and ink buttons invert.

Phones and tablets

All steps were checked at 360, 390, 820, 1280, 1440 and 1920 px wide, in light and dark. On touch screens, hover effects are off and the dropzone says "Choose a video".

Reduced motion

With reduced motion turned on, every explainer and the share preview show one finished, readable frame instead of looping, and the waving hand stays still.

Design notes

• No decorative sparkles or tilted cards. Motion is reserved for things that would really move: a cursor demonstrating a step, a recording playing, a stroke being drawn.
• Webcam bubbles show a person silhouette rather than a cartoon face.
• Self-drawing strokes use stroke-dasharray: 1 2, so no round-cap dot shows before they start drawing.
• The flying video in the Loom explainer arcs above both windows instead of crossing their title bars.

Before

How it works

• Who sees it. New accounts are created with onboardingSteps.getStarted = false. The dashboard sends them to onboarding until they pick a start or choose to look around. Existing accounts never have this flag, so nobody already using Cap is pulled back into onboarding. Accounts without a name still get the name step, as before. SSO-provisioned accounts are unchanged.
• New getStarted RPC step. It marks the old step flags and onboarding_completed_at, creates an organization if the user has none (for example an invitee who declined), and renames a default "My Organization" after the person. Opening any path step marks onboarding done, so leaving to the dashboard never bounces you back. skipToDashboard sets the new flag too.
• Old URLs. /onboarding/organization-setup, /custom-domain and /invite-team redirect to the start step, and /download redirects to the record step.
• Remembered destinations. A remembered sign-up destination (cap_onboarding_next) routes Loom, upload and record links to the matching step. Any other dashboard destination is where "I'll look around first" goes. Invite links are ignored, and the cookie is cleared when an invite is accepted.
• Checkout return. UpgradeModal and /api/settings/billing/subscribe accept an optional returnPath, validated as a same-origin path. Success and cancel both come back to it.
• Recorder. WebRecorderDialog gets a defaultOpen prop. This touches the component signature that feat: bring desktop Studio UI and local playback to web #2312 also changes, so expect a one-line conflict.
• Upload toast. importMediaFile gets showSuccessToast so onboarding can show its own success state.
• Database. No migration; the only schema change is the TypeScript type of the JSON column.
• Removed. The old organization setup, custom domain, seat pricing and download steps. Custom domains and seats are still available in settings and billing.

Testing

• Unit tests for step routing, intent mapping, name splitting, email masking, theme resolution and checkout return URLs; getStarted backend tests for renaming, team members, and missing or deleted organizations. The full web unit suite passes (242 files, 3,429 tests).
• Biome on the touched files, tsc -b apps/web, and tsc for web-backend, web-domain and database.
• End-to-end with Playwright against a local stack (MySQL and MinIO), including a real Loom import of a public video and a real upload that plays on the share page. All 30 behavior checks pass:

Behavior checks

PASS  /onboarding redirects to /onboarding/start
PASS  /onboarding/welcome redirects to /onboarding/start
PASS  /onboarding/organization-setup redirects to /onboarding/start
PASS  /onboarding/custom-domain redirects to /onboarding/start
PASS  /onboarding/invite-team redirects to /onboarding/start
PASS  /onboarding/download redirects to /onboarding/record
PASS  /onboarding/nope redirects to /onboarding/start
PASS  named account still choosing a start is sent to the start step
PASS  existing account without the new flag stays on the dashboard
PASS  existing account part-way through the old flow stays on the dashboard
PASS  account without a name is asked for one
PASS  path steps wait until there's a name
PASS  new account that already has a name (Google) skips the name step
PASS  looking around first completes onboarding
PASS  completed account is not sent back to onboarding
PASS  new account is created with the get started flag
PASS  new account starts with its own organization
PASS  signing up from a Loom import link lands on the Loom step with the link filled in
PASS  the organization is named after the person
PASS  opening a path step marks onboarding complete
PASS  a non-Loom link shows a friendly error
PASS  reduced motion renders static explainer frames
PASS  follows the device when no theme was chosen
PASS  a dark device gets the dark paper
PASS  the rest of the app (dialogs, toasts) matches
PASS  the toggle switches to light and remembers it
PASS  the choice survives a reload with no flash
PASS  and back to dark
PASS  finishing onboarding on a dark device opens the dashboard in dark mode
PASS  dashboard renders dark