Design a new user onboarding flow

Tor Browser's current onboarding template is a port of an older version from Firefox. We should explore alternatives here before deciding on a template, e.g. the practicality of modifying Firefox's current built-in format.

changed due date to October 28, 2022

changed milestone to %Sponsor 131 - Phase 2 - Privacy Browser

added Brand UX Team Next Sponsor 131 Q4 UX labels

assigned to @duncan

marked this issue as related to #41088 (moved)

mentioned in issue #41088 (moved)

ESR 102 includes the following onboarding slides, which have existed in Firefox for a while now:

Show all screenshots

I've seed a version of slides 1 & 2 appear unexpectedly in Tor Browser Nightly before (without the colorful background shapes and image), so I assume this exists in the codebase somewhere and we can take advantage of the format.

However even if it's technically doable, it'll be challenging to adapt these to our current onboarding content – which features illustrations and longer strings.

There's also a new onboarding experience & template currently being tested in Firefox Beta, which must have been added at some point between 103 and 106. The format is far closer to what we currently have in Tor Browser, and it would suit us perfectly in terms of format & content:

Show all screenshots

Unfortunately, both Tor Browser 12.0 and 12.5 are planned to be ESR 102 based. Bad timing.

A version of this without the background gradient appears to have reached Firefox stable in 106.0 (I think, although it's not mentioned in the release notes):

Show all screenshots:

It looks like a version of the smaller layout is still being maintained as well. You can see it in action on the Firefox View page, which is also brand new to 106.0:

Given the recent changes to Firefox's onboarding experience, I don't think it makes sense to consider doing something completely custom at all. Instead, our best options are to:

1. Use the old/smaller slide template that's currently available in esr102. This will require some degree of modification – since it doesn't include any imagery at present besides the application icon – and the strings used in each slide are typically quite short. We'll also need to decide whether we want to upgrade to the newer slide template next year when we hop on the next ESR, potentially doubling the work here.
2. In theory, we could backport the new/larger slide template to the ESR 102 based Tor Browser. This would need scoped out properly before we can estimate how easy it will be, however.

Here's a mockup of the first route with some of our current content applied (from the last slide about Onion Services):

Modifications include swapping the application icon for an illustration, and switching the primary color from blue-60 to purple-60. I'm a little nervous about the length of the string when localized though.

We could also consider updating the onboarding illustrations too, as they're starting to show their age a little.

And here's a dark theme version using content from the Circuit Display slide:

mentioned in issue #41290 (closed)

marked this issue as related to #41290 (closed)

added Backlog label and removed Next label

added Next label and removed Backlog label

Here's a mockup using the same content, but applied to the new onboarding template used by FF 106 onward instead:

And again, in dark theme:

added Backlog label and removed Next label

The bugzilla meta bug for the 106 onboarding is https://bugzilla.mozilla.org/show_bug.cgi?id=1772614

There's a lot of linked bugs. I'll look into whether we could backport the feature.

ok, I had a broad look over the code in this area and I asked in the mozilla matrix chat for an idea about the changes. It seems that between v100 and v106 they didn't change the underlying architecture, but mostly made visual changes to "about:welcome" and added in screens for the new firefox features (colorways and "Firefox View").

However, from my first look through their code, it is a lot more complex than I expected. And it uses React, SCSS, and other web-dev stuff that is not normally used in firefox UI, so if we wanted to add anything tor-related that is slightly complex we would need to learn and engage with the same stuff. For example, their language selector is written for React. So if we want to adapt this (looking at the code, we probably would) or add our own component (like English language spoofing for web pages, and tor connection config) we would have to implement and hook them up ourselves.

So whilst it seems we could backport the style changes to 102, I would expect it to be difficult mostly because this section of code is so different from what we normally deal with, so would be harder to understand. We might be better off using our own onboarding page if we only need something simple for tor browser and base browser.

Ack, thanks for investigating @henry!

However, from my first look through their code, it is a lot more complex than I expected. [...]

Just to add another note: it might be integrated with activity-stream, which we try to disable in tor-browser.

@henry so this means we likely won't be able to 'just reuse' the existing on-boarding framework and will need to roll our own? That gives us some design freedom but also means more dev work than expected.

@richard yeah I think so. Especially since I don't expect our onboarding to have much overlap with the firefox onboarding, so we would need to make our own custom additions and removals anyway.

That gives us some design freedom but also means more dev work than expected.

It might be easier for us to maintain as well, once it is done.

added Task label

A little note to add here for now until we have another issue. We probably want to handle application language selection and web content language selection in the onboarding. See !443 (comment 2853649)

The English spoofing dialog for web content comes from firefox, so we'll want to switch that off.

As an extra note on this point, I'm beginning to come around to the idea that Tor Browser's onboarding flow should be about set-up first, rather than user education. Parts of the current onboarding content that don't fit that model could be:

• migrated to the new /download page,
• added a special web page that opens in a new tab for first-time users (e.g. Welcome to Tor Browser!),
• or added to the redesigned about:tor as a series of did you knows (this is maybe the most fun option).

^ Onion browser has did you knows during bootstrapping, which is v cute but not ideal for a11y since the screen advances automatically when bootstrapping is complete.

added Desktop label

removed Q4 label

mentioned in issue #41333 (closed)

mentioned in issue mullvad-browser#4 (closed)

removed Backlog label

added Roadmap::Future label

added FF115-esr label

added Q2 label

added Backlog label and removed Roadmap::Future label

mentioned in issue #40414 (closed)

removed due date

removed Q2 label

added Q3 label

removed Backlog label

added Roadmap::Future label

added 13.5 stable label

mentioned in issue #41796 (closed)

unassigned @donuts

removed Q3 label

mentioned in issue #41556 (closed)

@donuts we currently still have some unused strings from the old onboarding in our browserOnboarding.properties file, plus a few we kept from mozilla.

Is there any chance that we would reuse the longer strings for the new onboarding? Otherwise we can just clean out the old file. I don't think we need to worry about the shorter strings since they'll be pretty easy to re-translate, and may even need to be different for some locales if the context changes.

removed FF115-esr label

marked this issue as related to #41987

assigned to @jag

removed Roadmap::Future label

added Backlog label

If we have time, it might be worth exploring adding a card for toggling window titles (#41988) in the onboarding as well.

added Next label and removed Backlog label

added Doing label and removed Next label

added Next label and removed Doing label