Onboarding

Setting something up: stations along a groove (done ones with their lamp lit, the current one a raised cap) and a checklist of check keys with a progress slot.

Element: <ol> · <section>
Needs: kit.css + kit.mjs
Rules: onboarding.rules.md · 5
Finishes: Aluminium · Graphite · Porcelain · Black
Volumes: Tactile · Quiet

On this page

Variants
Every state, at once
API
Markup
Accessibility
How it’s built
Rules
Related parts

Variants

Accountdone
Hubcurrent step
Doneto do

Three steps

Accountdone
Hubdone
Meterdone
Tariffdone
Batterydone

Five steps · all done

Accountdone
Hubdone
Meterdone
Tariffcurrent step
Batteryto do

Narrow · only the current name

Set up Hearth

All 3 done

Pair the hubIt found meter 2291 on the board.
Name your circuitsTwelve found; four still say “Circuit”.
Choose your tariffSo the battery charges when power is cheapest.

Checklist · all done

Every state, at once

Both finishes, side by side. Hover, pressed and focus are forced with .is-hover, .is-down and .is-focus; checked and disabled are real.

Aluminium

Part	Start	Under way	All done
Track	Hubcurrent step Meterto do Tariffto do Batteryto do	Hubdone Meterdone Tariffcurrent step Batteryto do	Hubdone Meterdone Tariffdone Batterydone
Checklist	Set up Hearth 0 of 4 done	Set up Hearth 2 of 4 done	Set up Hearth All 4 done

Graphite

Part	Start	Under way	All done
Track	Hubcurrent step Meterto do Tariffto do Batteryto do	Hubdone Meterdone Tariffcurrent step Batteryto do	Hubdone Meterdone Tariffdone Batterydone
Checklist	Set up Hearth 0 of 4 done	Set up Hearth 2 of 4 done	Set up Hearth All 4 done

API

Name	Kind	Values	What it does
.tui-onboarding__steps	class	on <ol>	The track: stations spread evenly, a groove between each pair. Give it an aria-label.
.tui-onboarding__step · data-state	class · attribute	"done" · "current" · "upcoming"	A station. Done: a green lamp in its socket. Current: a raised cap. Upcoming: an empty socket.
aria-current="step"	attribute	on the current <li>	Announces where you are.
.tui-onboarding__station	class	aria-hidden	The socket or cap, printed with the step’s number.
.tui-onboarding__name	class	a noun	The step’s name; a <small> inside adds a second line. Narrow tracks keep only the current one’s.
.tui-onboarding__state	class	visually hidden	“done”, “current step” or “to do”, for screen readers; setOnboardingStep rewrites it.
data-onboarding-go · aria-controls	attribute	"next" · "back"	On any key: steps the track it names.
.tui-onboarding	class	on <section>	The checklist: a head, a progress slot, the tasks.
.tui-onboarding__head · __title · __count	class	—	The title and “2 of 5 done”, rewritten as tasks are ticked.
.tui-progress[role=progressbar]	class	the kit’s	The slot: --v and aria-valuenow follow the count.
.tui-onboarding__task · data-next	class · attribute	on <li>	A task: a .tui-check, its label (b title + span detail) and a key. Only the next task shows its key.
.tui-onboarding__action	class	on a .tui-key	The next task’s key: the contrast key of the surface.
setOnboardingStep(ol, n) · updateOnboarding(section)	function	kit.mjs	Move the track to step n (steps + 1 = all done); recount a checklist.
tui-onboarding	event	detail: step or done, of	Fired on the track or the checklist after a change.
Space · Tab	keyboard	—	Tick a task with Space; the track is read, not operated: its keys step it.

Markup

<ol class="tui-onboarding__steps" aria-label="Setting up Hearth">
  <li class="tui-onboarding__step" data-state="done">
    <span class="tui-onboarding__station" aria-hidden="true">1</span>
    <span class="tui-onboarding__name">Account</span>
    <span class="tui-onboarding__state">done</span>
  </li>
  <li class="tui-onboarding__step" data-state="current" aria-current="step">
    <span class="tui-onboarding__station" aria-hidden="true">2</span>
    <span class="tui-onboarding__name">Hub</span>
    <span class="tui-onboarding__state">current step</span>
  </li>
  <li class="tui-onboarding__step" data-state="upcoming">…</li>
</ol>

<section class="tui-onboarding" aria-label="Set up Hearth">
  <div class="tui-onboarding__head">
    <p class="tui-onboarding__title">Set up Hearth</p>
    <span class="tui-onboarding__count">1 of 3 done</span>
  </div>
  <div class="tui-progress" role="progressbar" aria-label="Set up Hearth"
       aria-valuemin="0" aria-valuemax="100" aria-valuenow="33" style="--v:.333"></div>
  <ul class="tui-onboarding__list">
    <li class="tui-onboarding__task">
      <input type="checkbox" class="tui-check" id="t1" checked>
      <label for="t1"><b>Pair the hub</b><span>It found meter 2291.</span></label>
    </li>
    <li class="tui-onboarding__task" data-next>
      <input type="checkbox" class="tui-check" id="t2">
      <label for="t2"><b>Choose your tariff</b><span>So the battery charges cheaply.</span></label>
      <button class="tui-key tui-key--primary tui-key--sm tui-onboarding__action">Choose tariff</button>
    </li>
  </ul>
</section>

import { setOnboardingStep, updateOnboarding } from '/kit/kit.mjs';

setOnboardingStep(document.querySelector('.tui-onboarding__steps'), 3);
// Check keys inside a .tui-onboarding recount by themselves; after changing tasks:
updateOnboarding(document.querySelector('.tui-onboarding'));
document.addEventListener('tui-onboarding', (e) => save(e.detail));

Needs kit.css and kit.mjs. How to install the kit.

The track is an ordered list with aria-current="step" on where you are, and each station says “done”, “current step” or “to do” in words.
Done is a lit lamp and the word; current is a raised cap and aria-current: never the lamp alone.
Tasks are real checkboxes with labels; the progress slot is a progressbar whose value follows them.
Only the next task shows its key, so there is one contrast key on the surface and one obvious thing to do.
Reduced motion stops the ink running along the groove; the track shows the same.

How it’s built

The track is a grid of equal columns, so the stations space themselves; each station after the first draws the groove back to the one before (its ::before, the kit’s recess) and the ink along it (its ::after, scaled from 0 to 1 over 220ms when the step is reached). The done lamp and the raised cap are the kit’s lamp and key, drawn on the station. The checklist is the kit’s check keys and progress slot; onboarding.mjs recounts on every change and moves data-next.

Rules

onboarding.rules.mdIn the brain

Five steps at most, named as nouns; the checklist gives a key only to the next task, and a task counts as done when it is done.

5 rules in this file, with the foundations they rest on and the anti-patterns that break them. Full rules ship in the brain with the Pass.

See the Founder Pass How agents use the brain