Add interactive onboarding tour

[d-koppenhagen]

Add interactive onboarding tour

Description

Add an interactive onboarding tour that introduces first-time users to the main functionality and navigation of practica11y.

The tour should guide users through the application by highlighting relevant UI elements and displaying short contextual explanations. The currently focused element should be visually emphasized while the rest of the interface is dimmed.

The goal is to make it easier for new users to understand how practica11y works without requiring them to read separate documentation first.

Proposed behaviour

On the first visit, users are presented with the option to start a short guided tour.

The tour could introduce the following areas:

1. Welcome

   • Briefly explain the purpose of practica11y.
   • Explain that the application contains interactive accessibility challenges.

2. Navigation

   • Highlight the main navigation.
   • Explain how users can move between the different areas/challenges.

3. Challenge overview

   • Highlight the challenge list/overview.
   • Explain what the different challenges represent.

4. Challenge details

   • Highlight the main challenge content.
   • Explain where the accessibility issue is demonstrated.

5. Interaction

   • Highlight the relevant interactive elements.
   • Explain what the user is expected to investigate or interact with.

6. Accessibility information

   • Point out where users can find additional information or hints about the accessibility issue.

7. Completion

   • Explain how to finish a challenge and move on to the next one.

UX requirements

• The tour should be skippable at any time.
• Users should be able to navigate back and forth between steps.
• The currently explained element should receive a clear visual focus/spotlight.
• The explanatory tooltip should be positioned close to the highlighted element.
• The tour should work with keyboard navigation.
• Focus should be managed correctly while the tour is active.
• The tour must not introduce new accessibility issues itself.
• The tour should not be shown automatically on every visit.
• Users should have a way to restart the tour later, e.g. through a "Start tour" / "Show introduction" action.

Accessibility considerations

Since practica11y is specifically focused on accessibility, the onboarding component should itself follow accessibility best practices.

In particular:

• Use appropriate semantics for the tour/dialog.
• Ensure keyboard users can operate the complete tour.
• Manage focus when opening, navigating and closing the tour.
• Provide an accessible name and description for each step.
• Do not rely on colour alone to indicate the highlighted element.
• Ensure sufficient contrast for the overlay and tooltip.
• Allow users to exit the tour using the Escape key.
• Respect reduced-motion preferences where animations are used.
• Ensure screen-reader users receive the same essential information as visual users.

Technical considerations

The implementation could either use a small custom component or an existing onboarding-tour library (ideally Angular specific maintained lib).
The important requirement is that the implementation remains accessible and does not make the application dependent on mouse interaction.

A typical implementation would consist of:

• Tour / OnboardingTour component
• reusable TourStep definition
• spotlight/overlay
• tooltip/popover
• keyboard and focus management
• persistent state indicating whether the user has already completed/skipped the tour

Acceptance criteria

• A first-time user can start an onboarding tour.
• The tour highlights relevant UI elements step by step.
• Each highlighted element has a concise explanation.
• Users can go to the next and previous steps.
• Users can skip/close the tour.
• The tour can be started again after it has been completed.
• The complete tour is keyboard accessible.
• Focus is correctly managed throughout the tour.
• Screen-reader users can understand and operate the tour.
• The tour does not introduce accessibility violations.
• The tour works on different viewport sizes.
• The tour respects prefers-reduced-motion.

Open questions

• Should the tour start automatically or should users explicitly opt in?
• Which parts of the application should be covered in the first version?
• Should there be one short general tour or separate tours for different areas?
• Should completing the tour be persisted locally?
• Should the tour be available from the application's help/settings area?