Setup guide
NewThe steps that activate an account, kept in the app’s header: a Welcome button with a ring of the whole setup, and a guide of steps whose rings fill as tasks are done.
setup-guide/setup-guide.tsxThe live component, numbered part by part. Every measurement is read from it as it is drawn. Point at a row to outline its part, or at a part to find its row.
The choices it offers, each value drawn live and the default marked, with how to pick one.
When to use
- Activating a new account that needs a few things done before it is useful: a profile, a first download, a form, a connection.
- Steps people finish over several visits, so the guide has to stay within reach without blocking the page: a button in the header, with its progress on it.
- Steps made of small tasks that can be done in any order, where a count per step and a ring for the whole setup tell people how far they are.
- Products where some people will never want the guide: Skip all puts it away, and it can come back.
When not to use
- A tour of the interface. Use coach marks or a product tour that points at the parts of the screen; this lists work to do, not places to look.
- One required step before anything works. Ask for it in the flow itself, or with a blocking dialog; a header button is easy to leave for later.
- Long projects with dates, owners and dependencies. Use a task list or a project board; the guide is for a handful of steps one person finishes.
- Steps the product can check on its own and never needs the person to tick. Show their status, but don’t ask people to mark them done.
Counting progress
- A step’s count is its tasks done over its tasks,
1/4, and turns into Done with the last one. - The header’s ring is every task done over every task, so a step of eight tasks weighs more than one of three.
- Tasks can be ticked in any order and unticked again: the guide counts them either way. Mark next done ticks the first one left.
- Save on every change:
onTaskTogglehands over every task done, andonStepCompleteandonCompletemark the milestones.
Skipping, finishing and coming back
- Skip all asks first, and says how to bring the guide back. Confirmed, it leaves a quiet Resume setup button that keeps the ring.
- The account menu can hide the guide, show it again or start it over, so skipping is never final.
- Finishing every step plays a burst of confetti and turns the button into All set, with × to dismiss it for good.
Each one drawn with the component itself, used well or badly.
The guide is read in a glance from the header: the button names the setup, the steps say what is left to do.
- Step titles are outcomes, a verb and its object:
Complete your account,Download at least one file. - Task names are a few words, short enough for a column of about 150 px:
Add your name,Pick a format. - The intro says why in one sentence (
intro): what finishing the steps gets people. - The button’s word (
label) is a greeting or a call to start; All set replaces it at the end. - Sentence case, with no full stops in titles, tasks or the button.
You can add this component with the shadcn CLI or by hand:
Into components/setup-guide of any React project, with no setup:
npx shadcn@latest add https://brunodelorence.com/r/setup-guide.json- Copy the component files
Copy these files into one folder of your project, keeping their relative imports together, or download them as a ZIP:
- Import it
As shown under Usage, below.
Either way it needs React 19 and a bundler that supports CSS Modules, such as Next.js or Vite. It has a dark colour scheme: it follows your page’s color-scheme, light unless the page sets one, or its colorScheme prop, with nothing to configure. Browsers without light-dark() show it light.
Usage
import { SetupGuide } from './setup-guide';export function AppHeader({ done }: { done: string[] }) { return ( <SetupGuide defaultDone={done} onTaskToggle={(id, isDone, all) => saveProgress(all)} onComplete={() => console.log('Account active')} onSkip={() => console.log('Guide skipped')} autoplay={false} /> );}Each state below is a live instance, locked so you can study it.
The pieces it is built from, each with its measurements read live.
Below are variations of this component, each live, with its code.
New workspace
Four steps of setting up a team workspace under Get started, one task done, with Connect your storage open.
One task left
Fourteen of fifteen tasks done: the download form open on its last task, a tick away from the celebration.
Skipped for now
The guide put away behind Resume setup, its ring still showing the progress, with German picked.
All set
Every step done: All set with its dismiss button, and the account menu open on Hide setup guide and Start setup over.
An app’s header on a green band: a search field, a green Welcome button carrying a ring of the whole setup, notifications, a language picker and the account. Welcome opens Missing steps under it: a row per step with a ring of its tasks and a count (Done, 1/4, 4/8). A row opens its tasks in place; tick them in any order or Mark next done, and the rings ease to their new share while the counts roll. Skip all asks first and leaves a Resume setup button; finishing every step plays a burst of confetti and turns Welcome into All set, which can be dismissed. The search and the notifications open the guide on a step. Light and dark.
- Progress is a set of task ids. A step’s count is its tasks in the set, the header’s ring every task in the set over every task, so a step with eight small tasks weighs more than one with three.
- Each ring is two SVG circles: a track, and an arc whose dash offset is the share left. The offset is a custom property that CSS eases, so a ring glides to its new share; full, the arc fades and a disc with a check springs in, its stroke drawn by its dash offset.
- A count rolls: the number is keyed by its text, so a new value mounts and slides in from below when it grows, from above when it shrinks. The last task turns the count into Done.
- A row is a disclosure button. Its tasks sit in a grid row that eases from 0fr to 1fr, inert while closed; they are checkboxes in two columns, and Mark next done ticks the first left and names it.
- The guide is a non-modal dialog hung under Welcome with their right edges lined up, measured in the window’s own px (offsets, not screen rects) so it stays put when a gallery card scales the stage. On a phone it takes the window’s width, and its list scrolls inside it when the window is short.
- Skip all swaps the steps for a question first. Confirmed, the guide leaves the header for an outlined Resume setup button that keeps the ring; the account menu can also hide it, show it or start it over.
- The last task fires a burst of confetti from the button and the guide: eighteen pieces with their own flight, turn and delay, moved with the translate, rotate and scale properties. Welcome becomes All set with × beside it; dismissed, the slot closes.
- While on screen and untouched, a demo pointer opens the guide, opens Download at least one file, ticks a task and Mark next done, closes the step and the guide. Any real input hands it over; it comes back after 7 s of quiet.
| Prop | Type | Default | Description |
|---|---|---|---|
steps | Step[] | three steps | The steps in order, each an id, a title and its tasks (an id and a label). |
defaultDone | string[] | eight of fifteen tasks | Task ids done at first. |
title | string | 'Missing steps' | The guide’s heading while steps are left. |
intro | string | — | The line under the heading. |
label | string | 'Welcome' | The header button’s word while steps are left; All set once they are done. |
person | Person | — | Who is signed in: a name, an email and two initials for the drawn avatar. |
notices | Notice[] | two notices | The notifications; one with a step opens the guide there. |
languages | { code: string; name: string }[] | five languages | What the language picker offers; defaultLanguage picks the first. |
searchPlaceholder | string | 'Search the library' | The search field’s placeholder. |
supportHref | string | '#support' | Where Support goes. |
defaultState | SetupGuideState | — | Opens locked in a moment, with the demo off: the guide open, a step open, Skip all asking, skipped or dismissed, a menu or search held open, or the burst of a finished setup. |
onTaskToggle | (taskId: string, done: boolean, all: string[]) => void | — | Called when a task is ticked or unticked, with every task done. |
onStepComplete | (step: Step) => void | — | Called when the last task of a step is ticked. |
onComplete | () => void | — | Called when every step is done. |
onSkip | () => void | — | Called when Skip all is confirmed. |
onDismiss | () => void | — | Called when the finished guide is dismissed from the header. |
onLanguageChange | (code: string) => void | — | Called with the language picked. |
autoplay | boolean | true | While on screen and untouched, a demo pointer works through a step. Any real input stops it. |
colorScheme | 'light' | 'dark' | 'system' | — | Light or dark colours, or the reader’s; without it, the page’s color-scheme. |
className | string | — | Classes for the stage. |
Keyboard
- Welcome opens the guide and moves focus to the first step with tasks left; Escape closes it and hands focus back to Welcome.
- Up and Down arrows move between the step rows; Enter or Space opens a step’s tasks, and Space or Enter ticks a task.
- While Skip all is asking, Escape goes back to the steps, with focus on Skip all.
- Closed steps’ tasks are
inert, so Tab never lands on a task that can’t be seen.
Screen readers
- Welcome is named with its progress,
Welcome: setup 53% done, and opens a dialog (aria-haspopup="dialog",aria-expanded). - The guide is a non-modal dialog named by its heading. Each row is a disclosure button with
aria-expanded; each task a checkbox witharia-checked. - Every tick is read out in a polite status region,
Pick a format done. Download at least one file: 3 of 4., as are skipping and finishing (WCAG 4.1.3, Status messages).
Search
The search field is a combobox over a listbox of steps and tasks: arrows move through the results, Enter opens the guide on that step and focuses the row or the task, Escape closes the results.
Targets and motion
Tasks are at least 32 px tall and step rows at least 58 px; the smallest header button, the × beside All set, is 32 × 38 px on a phone. All are above the 24 × 24 px minimum (WCAG 2.5.8, AA). With reduced motion the rings, counts and drawers change at once and the confetti doesn’t play.
Colour and contrast
Every text measures at least 4.5 to 1 on what it sits on, in light and dark: the white Welcome on its green, the grey counts and ticked task names, the hints and placeholders (WCAG 1.4.3). Checkbox edges, rings’ arcs against their tracks and the white checks measure at least 3 to 1 (WCAG 1.4.11). A step’s state is also in its count and a ticked task’s in its check, so colour isn’t the only cue (WCAG 1.4.1).
In this build
- Welcome is a button with aria-haspopup="dialog" and aria-expanded, named with the share done (“Welcome: setup 53% done”); the guide is a non-modal dialog labelled by its heading. Opening it moves the focus to the first step left; Escape or a press outside closes it, with the focus back on the button.
- Each step is a disclosure button with aria-expanded and aria-controls; ↑ and ↓ move between steps. Its tasks are role="checkbox" buttons, and a closed step’s tasks are inert.
- The rings, the confetti and the avatar are hidden from assistive technology; a polite live region says each task ticked with the step’s count, a step done, the setup complete, a skip and a language change.
- Skip all opens an inline question with Keep going focused; confirming moves the focus to Resume setup. The search is a combobox with a listbox of steps and tasks, moved with the arrows and chosen with Enter. Notifications, language and account are menu buttons whose menus move with the arrows, Home and End, and close with Escape.
- Under reduced motion nothing eases, rolls, springs or flies and the demo never plays. The demo pointer is decorative.
The complete source behind this demo. Open source under the MIT license, © 2026 Bruno Delorence: copy it, change it, ship it.
// Copyright (c) 2026 Bruno Delorence. MIT License.'use client';import { useCallback, useEffect, useEffectEvent, useId, useLayoutEffect, useMemo, useRef, useState, type CSSProperties, type KeyboardEvent as ReactKeyboardEvent,} from 'react';import { DONE, LANGUAGES, NOTICES, PERSON, STEPS, countDone, type Notice,/* Setup guide (setup-guide.tsx): an app window on a green band, its header carrying the guide. The window runs off the stage at the left and the bottom, as a crop of a larger screen; its body is a skeleton of empty cards. The guide, the menus and the search results hang under their triggers (placed in the window's px by menu.tsx). Under 600 px of stage the search drops to a row of its own under the header's buttons, the band thins and the guide takes the window's width. Colours are the tokens below, light-dark(light, dark) where the two differ: the component takes the color-scheme it inherits from the page, or the one its colorScheme prop sets (data-color-scheme). Text measures at least 4.5:1 on the surface it sits on, white on the green fills included, and the checkboxes' edges and the rings' arcs at least 3:1, in both schemes. */.root { --band: #318b6c; --window: #ffffff; --page: #f2f2f2; --skeleton: #e6e6e6; --line: #e4e4e4; --field: #ffffff; --field-edge: #e2e2e2; --ink: #232323; --ink-2: #555555; --ink-3: #6d6d6d;// Copyright (c) 2026 Bruno Delorence. MIT License./* * What the setup guide shows by default: the steps that activate an account in an assets * library, each made of small tasks, and who is signed in. A step is done when all its tasks are. */export type Task = { id: string; label: string };export type Step = { id: string; title: string; /** Done one after another, or in any order: the guide counts them either way. */ tasks: Task[];};export type Person = { name: string; email: string; /** Two letters for the drawn avatar. */ initials: string;};export type Notice = {// Copyright (c) 2026 Bruno Delorence. MIT License./* * The guide's line icons and its progress ring, drawn on a 24-unit grid. The icons take the * text colour; the ring its tokens (--ring-track, --ring-fill, --ring-check). */export type IconName = 'search' | 'bell' | 'chevronDown' | 'chevronRight' | 'info' | 'close' | 'check';const PATHS: Record<IconName, string> = { search: 'M10.5 17a6.5 6.5 0 1 0 0-13 6.5 6.5 0 0 0 0 13zM15.3 15.3 20 20', bell: 'M6 16.5V11a6 6 0 0 1 12 0v5.5l1.6 1.8H4.4zM10 20.3a2.2 2.2 0 0 0 4 0', chevronDown: 'm6.5 9.5 5.5 5.5 5.5-5.5', chevronRight: 'm9.5 6 6 6-6 6', info: 'M12 21a9 9 0 1 0 0-18 9 9 0 0 0 0 18zM12 11v6M12 7.6v.1', close: 'M7 7l10 10M17 7 7 17', check: 'm6.5 12.5 3.6 3.6 7.4-8',};export function Icon({ name, width = 1.7, className,// Copyright (c) 2026 Bruno Delorence. MIT License.'use client';import { useEffect, useLayoutEffect, useRef, useState, type CSSProperties, type KeyboardEvent as ReactKeyboardEvent, type ReactNode, type RefObject,} from 'react';import styles from './setup-guide.module.css';/* * Placement and the header's menus. Everything that opens from the header (the guide, the * notifications, the languages, the account) hangs under its trigger with their right edges * lined up, kept inside the window, in the window's own px: a gallery card may scale the whole * stage, so offsets are read from offsetLeft/offsetTop, never from the screen. *//** Where `box` goes under `anchor`, inside their common offsetParent; null until measured. */// Copyright (c) 2026 Bruno Delorence. MIT License.'use client';import { useCallback, useEffect, useRef, useState } from 'react';/* * When a demo may play on its own: while part of it is on screen and the tab is visible, never * under reduced motion, and not while the reader is using it. `take()` hands it to the reader; it * takes back over `idle` ms after their last input. */export function useAutoplay<T extends HTMLElement>(idle = 6000) { const ref = useRef<T>(null); const [visible, setVisible] = useState(false); const [reduced, setReduced] = useState(true); const [taken, setTaken] = useState(false); const timer = useRef(0); useEffect(() => { const element = ref.current; if (!element) return; let onScreen = false; const update = () => setVisible(onScreen && !document.hidden); const observer = new IntersectionObserver(// Copyright (c) 2026 Bruno Delorence. MIT License.'use client';import type { CSSProperties, Ref } from 'react';/* * The demo's pointer, and the steps that move it. A demo is a script of awaited steps: wait, or * glide the pointer somewhere. Stopping the demo (the reader takes over, or it scrolls away) ends * the step in progress at once: its promise rejects, which ends the script right there, and the * pointer fades out. * * Each glide is a curved flight played by the Web Animations API, so nothing runs frame by frame. * The points of the flight are handed to whoever wants to move along with it. The arrow and the * hand are HTML boxes * that swap by their visibility: a change of style inside an SVG would lay the SVG out again. */export type Point = { x: number; y: number };/** A glide's path and timing, for an animation that plays along with it. */export type Flight = { points: Point[]; timing: KeyframeAnimationOptions };export type Demo = {