Components · Teaching

Coachmark & spotlight

A coachmark points at one real thing on the page and explains it. In a Tour, each step lays a fixed spotlight over its target — a 2px accent ring plus a dim scrim that 0 0 0 9999px punches a hole around — and anchors the callout there: a caret at the target, a title, a body, and a Back / Got it nav over step dots. On its own it's a single anchored popover with a Got it and a top-right dismiss.

tour step · spotlight + anchored callout · step 2 of 4

Team console

Northside Foster Circle

14 active
  • MB
    Biscuit · beagle mix
    Intake 6 days ago · foster: M. Boone
    Vetting
  • JD
    Sadie · hound
    Intake 2 wks ago · foster: J. Duarte
    Adoptable
  • Pending pickup · Harborview AC
    2 dogs · transport needed by Fri
    Intake

The spotlight is a pointer-transparent box over the target's rect — ring:2px accent + a 0 0 0 9999px rgb(0 0 0/.55) scrim (clipped to the stage) darkens everything but the target, which stays lit above it. In a Tour the callout is dismissible=false: it drops the X and carries its own Skip / Back / Got it nav; the dots track Step 2 of 4. Primary is pinned .is-hover.

single coachmark · anchored, dismissible · side="right"

The single coachmark keeps the top-right dismiss (X) (dismissible=true) and skips the dots — just a Got it in the actions slot. The caret re-points per side: it sits on the left edge here because the popover opens to the right of its trigger.

spotlight
A fixed, pointer-transparent box over the target's getBoundingClientRect, padded by spotlightPadding (6px). It carries the ring-2 ring-accent highlight and doubles as the callout's anchor, so the caret points straight at the target.
dim scrim
One big spread shadow — 0 0 0 9999px rgb(0 0 0/.5) — on the spotlight box paints over the page outside the hole. The target stacks above it and stays lit; it's non-modal, so the page underneath is still visible.
callout
A TeachingPopover on the shared surface-3 Popover floor — --radius-md, overlay elevation + inner-glow, a re-pointing caret, a title and muted body, and an actions footer.
step nav
Tour supplies Skip / Back / Got it (next → done on the last step) beside step dots. Dots read done · current (pill) · pending; the container is aria-label="Step 2 of 4" and the counter is announced aria-live.
dismiss
A standalone coachmark shows the top-right X; a Tour step sets dismissible=false and drops it, since Skip / Esc / outside-press already exit the tour.
focus & motion
Base UI moves focus into each step and the Tour restores the pre-tour focus on exit. Re-measure on scroll / resize; the reposition + scroll-into-view honour prefers-reduced-motion. On mobile the step folds to a bottom-sheet card.

Source · TeachingPopover.tsx (coachmark over @phauna/ds Popover — title / body / actions / dismiss) + Tour.tsx (spotlight ring-2 ring-accent + shadow 0 0 0 9999px scrim, Back / Next / Done + Skip nav, focus return, reduced-motion) · design-system/teaching.