Building blocks

Hands-on tutorials have three key states: tutorials list, tutorial launched, and tutorial completed.

Shows a list of all existing tutorials within the service. This is the first state that users see.


Help panel

A help panel is a container that appears on the right side of the App Layout. It displays help content that relates to a concept, term, setting, option, or task on the corresponding console page.

Tutorial panel

A tutorial panel is a container that appears on the right side of the App layout. It contains contextual hands-on tutorials that help users learn how to achieve objectives within the service.

The tutorial panel lists all existing tutorials for a service.

The tutorials relevant to the current page are displayed at the top of the list.


When a tutorial is launched, users can switch between the tutorial and help panel for additional information.

Info links - optional

Info links allow users to switch between the help panel and the tutorial panel when a tutorial is active. Switching to the help panel doesn’t dismiss the tutorial.

Hands-on tutorials logic

Hands-on tutorials keep track of the status of tasks, not progress of individual steps

  • Each tutorial is composed of tasks, and each task is composed of steps. A task is achieved when users complete a series of steps.

    • For example:

      • Task - Creating a resource

      • Step - Naming the resource during resource creation

  • The hands-on tutorials pattern relies on page level validation for validating data on the page and surfacing an error message if needed

    • For example: When a required field is left empty.

  • The status of each tutorial is either pending or completed. If users dismiss a tutorial before finishing it, its status will be tracked as pending.

Whenever a new tutorial is introduced, keep the tutorial panel open by default

  • Display the tutorial panel as open by default whenever a new tutorial is introduced. The panel should remain open on all pages, until manually closed. Once closed, the panel should remain closed.

  • When a tutorial is launched, keep the tutorial panel open through all relevant pages as users move through the workflow.

  • When first introducing the tutorial panel, add a “-new” label to the tab header and keep it for 30 days. See the guidance for announcing new features

  • Additionally, add the “-new” label to the title of any new tutorial and keep it for 30 days. 

An open tutorial panel with the “-new” label to indicate that this is a new feature. 

Don't prevent users from selecting configurations that are different from the tutorial's recommendation. Instead, inform users about potential consequences, if any.

In general, allow users to select configurations that are different from what is recommended, and still proceed with the tutorial. There might be some instances where selecting a non-recommended configuration can prevent users from achieving the goal they want. In such a case, add a warning alert to the annotation popover to communicate potential consequences.

Don't add the warning alert for steps where selecting a non-recommended configuration doesn't affect the end goal.

A warning alert within an announcement popover.

Key UX concepts

Hands-on tutorials are not a replacement for the help system

Hands-on tutorials serve the specific purpose of providing actionable suggestions at decision points in a particular workflow. Any help content that relates to explaining general terms or concepts within the interface should be clarified by using the elements of the help system. Information presented in the hands-on tutorials should require minimal effort to read and act upon. See the guidance for onboarding.

Don’t introduce tutorials for very simple flows

Tutorials create additional clicks and can be more obtrusive than helpful if used for very simple flows. Tutorials should be introduced to improve comprehension and add value that can’t be achieved with the use of existing UI elements in complex flows.

General guidelines


  • If a tutorial includes a step that needs to be completed in another service, provide guidance for users to navigate to the correct service and return back to the tutorial after the step is completed. The underlying service should open in a new tab.
  • When introducing multiple tutorials, have the most relevant tutorials at the top of the list, with their cards expanded by default. Have all other tutorial cards collapsed at the bottom of the list.
  • Surface hotspots only when a tutorial is active. When the tutorial is dismissed, remove the hotspots and display the tutorials list state.


  • Avoid repeating concepts that should be handled by other UI elements on the page. See guidance for help system.
  • Don’t display multiple annotation popovers at once. The previous popover closes when a new one is opened.
  • Avoid providing guidance for optional actions within the flow, unless completing that action can be beneficial to the user’s overall comprehension of the service.
  • Don't hide tutorials that can't be launched yet. Use an alert to communicate prerequisites for launching the tutorial instead.

Writing guidelines

General writing guidelines

  • Keep labels and descriptions clear and concise.

  • Use parallel sentence structure.

  • Use sentence case for all text. Don’t use title case.

  • Use terminal punctuation (periods, exclamation points, question marks).

  • Use present-tense verbs and active voice wherever possible.

  • Don't use "please," "thank you," or Latinisms such as "e.g.," "i.e.," or "etc."

Tutorial panel

See the guidance for Tutorial panel.

Annotation popover

See the guidance for Annotation context.

Accessibility guidelines

General accessibility guidelines

  • Follow the guidelines on alternative text and Accessible Rich Internet Applications (ARIA) regions for each component.

  • Make sure to define ARIA labels aligned with the language context of your application.

  • Don't add unnecessary markup for roles and landmarks. Follow the guidelines for each component.

  • Provide keyboard functionality to all available content in a logical and predictable order. The flow of information should make sense.

  • Make sure you define ARIA labels for the selection inputs that are aligned with the language context of your application.

Related patterns

The help system pattern allows users to easily and quickly access help within the interface and current workflow.
The tutorial panel houses contextual Hands-on tutorials that help users learn how to use a service.
The annotation context is an invisible layer on top of the interface. It tracks the progress of a launched tutorial and feeds dynamic content to the Tutorial panel in Hands-on tutorials. It also renders annotation popovers and hotspot icons.