Background
In T397532 We'll be introducing a new interface element for logged-in readers on the main article namespace: a bookmark icon in the main toolbar for adding articles to a reading list.
We would like to draw people attention to this icon the first time they encounter it, in order to explain what it's for.
Part 2 and 3 of this work is captured in T406923 and T406922
User story
As a logged-in reader, I'd like to be notified about the new Reading List feature only once
Acceptance criteria
- The onboarding dialogs should only ever be showed once for users in the experiment
- The onboarding dialog follow the technical notes
- Ensure we do not add a performance burden for all users (e.g. load the entirety of Codex on page load)
Other notes
- Can GuidedTour be used here?
- Given that we only want to trigger one of the onboarding modals after a user interaction, and without the dark background, it seems simpler to use a custom Codex Popover component instead.
- Are there any accessibility considerations?
- No accessibility concerns have been raised so far.
Technical Notes
- The onboarding dialogs should be created as a custom Vue.js app that loads the Codex Popover component.
- The initial dialog should be shown if the user is bucketed in the experiment, has zero saved items, and has not seen the dialog previously. That item could will be available on the client as a data attribute on the bookmark icon.
- The shown state of the dialog should be stored in local storage.
- The dialog and it's dependencies (Vue, Codex) should be loaded dynamically on the client via mw.load() after checking the user is in the experiment, has zero saved lists, and hasn't seen the dialog before.
- The dialog should be loaded after a small timeout after pageload to minimize performance concerns, and to draw user attention to the dialog. 500ms or 1s after pageload.
- The second dialog, after user saves an item, can be overridden in bookmark.js
- The second dialog does not have to appear on the sticky header, only in the user overflow menu or user menu at smaller resolutions.
Requirement
Scope: Desktop web (Vector 2022).
- Introduce an onboarding dialog that notifies users of the new Reading List feature when the experiment launches.
- The onboarding dialog must only display once per user (tracked via local storage).
- The dialog is shown if the user:
- Is in the Reading List experiment treatment group.
- Has zero saved items.
- Has not previously seen the onboarding dialog.
- The dialog must use a custom Vue.js app implementing a Codex Popover component (not GuidedTour).
- The dialog loads asynchronously using mw.loader after confirming eligibility.
- It must load dynamically after a short delay (500–1000 ms after page load) to reduce performance impact and draw attention to the Save icon.
- Accessibility parity with Codex components is required, but no new concerns have been identified.
- The dialog and dependencies (Vue, Codex) must not increase load time for users outside the experiment.
BDD
Feature: Onboarding dialog for new Reading List feature
Scenario: Showing onboarding dialog to eligible users
Given I am a logged-in user in the Reading List experiment treatment group
And I have zero saved items
And I have not seen the onboarding dialog before
When I load an article page
Then the onboarding dialog appears 500–1000 ms after page load
And it explains the new Reading List feature
And it appears near the bookmark icon
Scenario: Suppressing the onboarding dialog after it’s been shown
Given I have already seen the onboarding dialog once
When I load subsequent article pages
Then the onboarding dialog does not appear again
Scenario: Excluding ineligible users
Given I am not in the treatment group
Or I have one or more saved items
When I load an article page
Then the onboarding dialog does not appearTest Steps
Test Case 1: Verify onboarding dialog appears for eligible users
- Log in as a user enrolled in the Reading List experiment (treatment group).
- Confirm the user has zero saved Reading List items.
- Clear local storage to simulate first-time exposure.
- Load an article page using Vector 2022.
- Wait 500–1000 ms.
- AC1: The onboarding dialog appears near the bookmark icon.
- AC2: The dialog text describes the Reading List feature.
Test Case 2: Verify dialog persistence logic
- Close or dismiss the dialog.
- Refresh the page or visit another article.
- AC4: The dialog does not reappear (local storage stores “shown” state).
Test Case 3: Verify performance and exclusion behavior
- Log in as a user outside the treatment group or with existing saved items.
- Load an article page.
- AC5: The onboarding dialog does not appear.
QA Results - Beta
| AC | Status | Details |
|---|---|---|
| 1 | ✅ | T400366#11343157 |
| 2 | ✅ | T400366#11343157 |
| 3 | ✅ | T400366#11343157 |
| 4 | ✅ | T400366#11343157 |
| 5 | ⬜ | T400366#11343157 |
This task was created by Version 1.0.0 of the Reader Experience team task template using phabulous.
