Variants

Why Variants?

The default <HintHotspot> dot ships at 12×12 px, which can be hard to spot on busy interfaces. The three named variants below are opinionated presets that solve the most common discovery patterns:

• variant="badge" — count-bearing high-contrast circle (notification-style).
• variant="beacon-with-label" — pulsing dot plus an adjacent label.
• variant="what-s-new-pill" — sparkle pill that fades after the first interaction.

Each preset renders at ≥24×24 px (above the WCAG 2.5.5 minimum touch target), passes WCAG 2.1 AA contrast on light and dark backgrounds, and respects prefers-reduced-motion: reduce.

badge

A 24×24 circular badge with an optional count slot. Values above 99 clamp to "99+".

import { HintHotspot } from '@tour-kit/hints';

<HintHotspot
  variant="badge"
  count={3}
  targetRect={anchor.getBoundingClientRect()}
  position="top-right"
/>

Props

beacon-with-label

A pulsing dot adjacent to a short label. The label is aria-hidden because the button already exposes an aria-label, so screen readers don't double-read.

<HintHotspot
  variant="beacon-with-label"
  label="New"
  side="right"
  targetRect={anchor.getBoundingClientRect()}
  position="top-right"
/>

The beacon pulses via motion-safe:animate-tour-pulse. Under prefers-reduced-motion: reduce, the useReducedMotion() JS gate strips the animation entirely (tier 3 of the reduced-motion contract).

Props

what-s-new-pill

A pill with an inline sparkle icon plus a label. After the first pointerdown or focus, the pill fades to opacity: 0 over 200ms.

<HintHotspot
  variant="what-s-new-pill"
  label="What's new"
  targetRect={anchor.getBoundingClientRect()}
  position="top-right"
/>

Props

Reduced-motion contract

Every variant participates in the three-tier reduced-motion defense:

1. motion-safe: Tailwind prefix strips animation classes when the OS pref is reduce.
2. @media (prefers-reduced-motion: reduce) wraps every custom @keyframes (e.g. tour-pulse).
3. useReducedMotion() JS gate drives render-time branches — e.g. what-s-new-pill returns null (instead of opacity: 0) under reduce so the element is fully removed.

Mock the hook in tests:

import { vi } from 'vitest';

vi.mock('@tour-kit/core', async (orig) => ({
  ...(await orig<typeof import('@tour-kit/core')>()),
  useReducedMotion: vi.fn(() => true),
}));

Composing the lower-level components

The three variant components are exported for advanced composition:

import { HintBadge, HintBeaconWithLabel, HintWhatsNewPill } from '@tour-kit/hints';

The recommended path is the discriminated variant prop on <HintHotspot> — it auto-narrows the variant-specific extras (count, label, side) at the call site.

Related

• <HintHotspot> reference — base component these variants extend.
• @tour-kit/hints overview — when to use hints vs. tours vs. announcements.
• Headless hint primitives — build a fully custom variant from scratch.
• Reduced motion guide — three-tier defense the variants participate in.
• Hint types reference — HintConfig, HotspotPosition, and variant prop types.