Even well-designed applications can become difficult to understand when their main workflows involve multiple controls, pages, or unfamiliar interaction patterns. Expecting users to discover these features on their own may lead to frustration, abandoned tasks, and additional support requests. Kirigami-Addons' onboarding module addresses this problem by presenting contextual guidance directly in the user interface, highlighting relevant elements and explaining them when they matter. When implemented through reusable and non-intrusive components, it can improve the user experience without requiring substantial changes to the existing application code.Kirigami-Addons' onboarding module provides a complete set of features for defining and running contextual walkthroughs in Kirigami applications:Declarative steps: attach guidance text directly to existing QML elements without restructuring the interface.Source areas: define the UI region covered by a walkthrough and containing its onboarding steps.Automatic sequencing: visit steps according to their declaration order.Walkthrough groups: create multiple onboarding flows, such as basic and advanced tutorials, over the same interface.Conditional steps: disable individual steps dynamically; disabled or destroyed elements are skipped automatically.Visual highlighting: outline the current element while dimming and blurring the surrounding interface.Configurable appearance: adjust the highlight padding and the intensity and quality of the background blur.Adaptive tooltips: position guidance above, below, or within the available space around the highlighted element.Navigation controls: move forward or backward, or cancel the walkthrough, using buttons, keyboard shortcuts, or QML methods.Lifecycle hooks: prepare or restore the interface before a walkthrough or individual step is displayed.Dynamic interface support: navigate between pages, tabs, views, dialogs, or other containers before highlighting their elements.Custom content: add application-specific metadata and present images, animations, videos, or other QML content inside the onboarding tooltip.Responsive geometry tracking: keep the highlight synchronized when elements move, resize, or change parents’ positions.State monitoring: observe the active walkthrough, source, current step, guidance text, geometry, and navigation availability.Accessible navigation: provide accessible button labels, keyboard operation, right-to-left layout support, and platform-consistent styling.Adding Onboarding to Your Kirigami ApplicationThis section explains how you can add onboarding features to your Kirigami appplication.Basic onboarding declarationBasic usage of Kirigami-Addons' onboarding moduleAfter importing the onboarding module, mark a common ancestor of the UI elements with Onboarding.isSource. This source defines the area where the module creates its overlay, applies the background effect, and searches for onboarding steps. Steps are declared directly on descendant elements using attached properties. Here, Onboarding.texts associates guidance with the Create project button, while Onboarding.start() begins the walkthrough. Steps are presented in declaration order, allowing onboarding to be added with minimal changes to the existing QML structure. You can use Onboarding attached properties to highlight/explain individual controls, layouts/groups, and even sub-controls.Defining multiple onboarding workflowsDefining multiple onboarding workflowsThe Onboarding.sourceGroups property declares the workflows available from a source area. The empty string represents the default workflow started by Onboarding.start(), while named groups, such as advanced, are started by passing their name to Onboarding.start().Each step uses Onboarding.groups to select the workflows in which it participates. The entries in Onboarding.texts correspond by position to those groups, allowing the same UI element to provide different guidance in each workflow. In this example, Create project belongs to both workflows, while Enable version control appears only in the advanced one.Extending onboarding tooltips with additional dataUsing additional custom data in onboarding tooltipsThe Onboarding.additionalData property associates application-specific metadata with a step. In this example, the metadata provides an animated WebP and its caption. A custom component reads the current step through Onboarding.currentItem.additionalData and displays this content using AnimatedImage and Label. Finally, binding the component to Onboarding.additionalDataComponent inserts it into the default tooltip between the guidance text and navigation controls, allowing applications to enrich onboarding steps without replacing the complete tooltip implementation.ExamplesThis is the example tutorial included in the Kirigami Addons repository. It demonstrates how the onboarding module can highlight individual controls, groups of controls such as layouts, and even sub-controls. It also shows how to attach additional data to onboarding steps, such as a video and its caption, and how to define multiple onboarding workflows within the same application.And this is the onboarding module in Minuet: a short guided walkthrough that highlights the most important parts of the exercise screen, explains what each control does, and helps new users understand the flow without leaving the application.The onboarding module provides a declarative and non-intrusive way to introduce users to important controls and workflows in Kirigami applications. With support for multiple workflows, dynamic interfaces, custom tooltip content, lifecycle hooks, and configurable visual effects, it can address both simple guidance and more advanced onboarding scenarios.A possible direction for future work is allowing each onboarding step to wait for a specific user interaction before continuing. Instead of relying only on the Next button, a step could advance after the user clicks a highlighted control, changes a value, or completes an expected action. This would extend the module beyond explanatory walkthroughs and enable fully guided, interactive tutorials in which users learn application workflows by performing the actual operations.Give the module a try in your application and share your experience, suggestions, and use cases. Feedback is especially welcome while these APIs are still being refined for an upcoming Kirigami Addons release.