Coach marks

Overview

A coach mark is a 280 px popover anchored to a target element. The surface is the inverse accent — pure black — so it reads as a deliberate interruption of the ordinary page chrome. One title, one short body, an optional preview, and an optional two-button action row. Nothing else.

Anatomy

Five parts. Title, body, optional preview, optional action row, and the arrow that anchors the whole thing to a target.

Arrow positions

The popover always sits below its target. Three horizontal arrow positions place the tip directly above the element being described, regardless of where the popover itself lands. Pick the position that puts the arrow under the visual centre of the target.

Content variants

Title + body is the floor. Preview and actions earn their place one at a time, never reflexively.

Multi-step tour

A guided tour stitches a sequence of coach marks together — each one anchored to the next target. The action row carries Back / Next; the secondary button on step one becomes Skip. A small dash progress indicator sits below the row so the user can see how many steps are left.

Behavior

• 01Click outside dismisses. Anywhere outside the popover closes it. The interaction is non-modal — the user can keep working with the page underneath. This is the default reflex for coach marks; if you need to block the user, you wanted a Modal.
• 02Once-per-user, by default. Persist a flag against the user account when the coach mark is dismissed or its primary action is taken. Don't show it again on the next visit; that's how an introduction becomes a nag.
• 03One coach mark on screen at a time. Multiple coach marks at once is a UI emergency — the user has no idea where to look. In a tour, the previous mark must animate out before the next one animates in.
• 04Anchor with a 16 px gap. The arrow tip sits 16 px below the bottom edge of the target. Closer than that the arrow looks pasted on; further away the user has to track to find what the popover is pointing at.
• 05Reposition before flipping. When the popover would clip the viewport, shift it horizontally first (and update the arrow position to match). Only flip to above the target if there's no horizontal room either.
• 06Reduced motion respected. The default entrance is a 120 ms 4 px rise + opacity. Under prefers-reduced-motion: reduce the popover appears in place with opacity only.

Accessibility

• Roles: the popover is role="dialog" with aria-modal="false" (the user is not blocked) and aria-labelledby pointing at the title element.
• Focus management:open the popover and move focus to the primary action (or the close button if there are no actions). Trap focus inside the popover until it's dismissed; restore focus to the target on close.
• Keyboard: Escape dismisses; Tab / Shift+Tab cycles through the actions; in a tour, → advances and ← goes back when no action button has focus.
• Contrast: the dark surface gives text.inverse on background.accent.inverse.subtlest an effective contrast of 21 : 1 — well past the AA requirement. The body text runs at 92% opacity (~16.5 : 1) so it still clears AA at small sizes.
• Announcement: on open, an off-screen aria-live="polite" region announces “Tip: {title}” so screen-reader users know a coach mark has appeared without losing their place.
• Touch targets: the action buttons are 48 px tall — the platform tap-target floor. The arrow is decorative and not focusable.

Code

The component composes from a single CoachMark primitive and a positioning hook (useCoachMark) that handles anchoring, dismissal, and the once-per-user flag.

import { CoachMark, useCoachMark } from "@flatpay-dk/ui";

// Single-shot — anchors to the ref, persists dismissal under "required-questions"
const { ref, open, dismiss } = useCoachMark({
  id: "required-questions",
  showOnce: true,
});

return (
  <>
    <button ref={ref}>Required</button>
    {open ? (
      <CoachMark
        position="right"
        title="Required questions"
        body="Add a Required tag to a question to block the order until the customer answers."
        primaryLabel="Got it"
        secondaryLabel="Skip"
        onPrimary={dismiss}
        onSecondary={dismiss}
      />
    ) : null}
  </>
);

// Multi-step tour
const tour = useCoachTour({
  id: "burger-config",
  steps: [
    { target: pattyRef, title: "Required questions", body: "..." },
    { target: tempRef,  title: "Defaults",           body: "..." },
    { target: extraRef, title: "Optional toppings",  body: "..." },
  ],
});

return (
  <CoachMark
    position={tour.position}
    title={tour.step.title}
    body={tour.step.body}
    secondaryLabel={tour.isFirst ? "Skip" : "Back"}
    primaryLabel={tour.isLast ? "Done" : "Next"}
    onSecondary={tour.back}
    onPrimary={tour.next}
  />
);

Best practices

Coach marks are easy to abuse. The questions below catch the most common misuses before they reach the screen.

Props

Related