FRD-062: Feature Spotlight Tooltip Widget

Field	Value
Owner	David Holmes
Status	Draft
Last Updated	2026-05-26
Target Release	v2.0.0 (P2)
T-Shirt Size	M
Type	Widget

---

Document Summary

A sequential coach-mark system that spotlights UI elements one at a time with a tooltip overlay, dimmed backdrop, and navigation controls. Used for feature onboarding, product tours, and contextual help. Supports dismiss, skip-all, and persistence of completion state via callbacks.

---

Introduction

Overview

Product tours and feature spotlights are a standard onboarding pattern for SaaS applications. This widget provides a step-by-step coach-mark system that highlights target elements, displays contextual tooltips, and tracks completion state through consumer-provided callbacks.

Goals

• Sequential spotlight steps targeting DOM elements by ref or CSS selector.
• Tooltip with title, body, step counter, and navigation (back/next/skip/done).
• Dimmed backdrop with a cutout around the spotlighted element.
• Scroll-into-view for off-screen targets.
• Persistence of completion/dismissal via onComplete and onDismiss callbacks.
• Ship Storybook stories demonstrating multi-step tours.

Non-Goals

• Built-in persistence layer (localStorage, cookies, or API).
• Analytics event tracking (consumer instruments via callbacks).
• Video or animated content inside tooltips.
• Branching/conditional step logic.

---

Scope

In Scope

Item	Description
FeatureSpotlight component	Orchestrates the tour: backdrop, cutout, tooltip positioning
SpotlightStep type	Data shape for each step (target, title, body, placement)
Backdrop overlay	Semi-transparent overlay with cutout around the target element
Tooltip	Positioned tooltip with step content and navigation controls
Navigation	Back, Next, Skip All, and Done buttons
Scroll behavior	Auto-scrolls target into view when advancing steps
Storybook stories	ThreeStepTour, SingleStep, SkipAll, DismissAndResume

Out of Scope

Item	Rationale
Persistence	Consumer decides storage mechanism
Conditional steps	Adds complexity; can filter steps array externally
Inline/embedded mode	Focus on overlay spotlight; inline tips are a separate pattern

---

Users and Pain Points

User	Pain Point
Product managers	No reusable onboarding tour component; teams build ad-hoc solutions
Developers	Positioning logic and backdrop cutouts are error-prone to implement
End users	Missing contextual guidance for new features

---

Definitions

Term	Definition
Coach mark	A UI overlay that highlights a specific element with explanatory content
Spotlight	The visual cutout in the backdrop that draws attention to the target
Tour	A sequence of spotlight steps presented in order
Persistence	Remembering that a user has completed or dismissed a tour

---

Current State

No spotlight or coach-mark component exists in the design system. The Tooltip primitive exists for hover tooltips but does not support sequential tours, backdrops, or step navigation.

---

Proposed Solution

Create a FeatureSpotlight widget at src/components/widgets/feature-spotlight.tsx that:

1. Accepts an array of SpotlightStep objects defining targets, content, and placement.
2. Renders a full-viewport backdrop with a CSS/SVG cutout around the current target.
3. Positions a tooltip adjacent to the cutout using Floating UI (or manual calculation).
4. Provides Back, Next, Skip All, and Done navigation.
5. Scrolls off-screen targets into view before showing the spotlight.
6. Fires onStepChange, onComplete, and onDismiss callbacks for consumer instrumentation and persistence.

---

Requirements

The spotlight must handle dynamic layouts (targets may move on resize), clean up on unmount, and not interfere with the target element’s interactivity when the spotlight is active.

---

Functional Requirements

ID	Requirement	Priority
FR-01	Render a semi-transparent backdrop with a cutout around the target element	Must
FR-02	Display a tooltip with title, body text, and step counter (e.g., “2 of 5”)	Must
FR-03	Position tooltip relative to target using configurable placement (top/bottom/left/right)	Must
FR-04	Provide Next and Back navigation buttons	Must
FR-05	Provide a Skip All button to dismiss the entire tour	Must
FR-06	Show a Done button on the final step	Must
FR-07	Scroll the target element into view when it is off-screen	Must
FR-08	Call onStepChange(stepIndex) when the active step changes	Must
FR-09	Call onComplete() when the user finishes the tour	Must
FR-10	Call onDismiss(stepIndex) when the user skips or closes the tour	Must
FR-11	Update cutout position on window resize and scroll	Should
FR-12	Allow the target element to remain interactive (clickable) during spotlight	Should

---

Non-Functional Requirements

ID	Requirement
NFR-01	Backdrop renders without causing layout reflow
NFR-02	Cutout repositions within 100 ms of resize/scroll events
NFR-03	Full light/dark theme support for the tooltip
NFR-04	Bundle size under 4 KB gzipped

---

API / Interface Requirements

interface SpotlightStep {
  target: string | React.RefObject<HTMLElement>;  // CSS selector or ref
  title: string;
  body?: string | ReactNode;
  placement?: "top" | "bottom" | "left" | "right";  // default "bottom"
  spotlightPadding?: number;  // pixels around target cutout; default 8
}

interface FeatureSpotlightProps {
  steps: SpotlightStep[];
  active?: boolean;              // default true
  initialStep?: number;          // default 0
  onStepChange?: (index: number) => void;
  onComplete?: () => void;
  onDismiss?: (stepIndex: number) => void;
  backdropOpacity?: number;      // default 0.5
  skipLabel?: string;            // default "Skip tour"
  nextLabel?: string;            // default "Next"
  backLabel?: string;            // default "Back"
  doneLabel?: string;            // default "Done"
}

---

Accessibility Requirements

ID	Requirement
A11Y-01	Tooltip has role="dialog" with aria-label describing the tour step
A11Y-02	Focus moves to the tooltip when a new step activates
A11Y-03	Escape key dismisses the tour (calls onDismiss)
A11Y-04	Navigation buttons are keyboard-accessible
A11Y-05	Step counter is announced to screen readers
A11Y-06	Backdrop does not trap focus away from the tooltip and target

---

Content and Documentation Requirements

• Storybook doc page with usage, props, and integration patterns.
• Stories: ThreeStepTour, SingleStep, SkipAll, CustomPlacement, DarkMode.
• Guidance on persistence patterns (localStorage example in docs).
• JSDoc on all exported types.

---

Dependencies

Dependency	Type	Notes
Floating UI or manual positioning	External/Internal	Tooltip placement relative to target
Button	Internal	Navigation controls
Portal	Internal/React	Render backdrop at document root

---

Risks and Tradeoffs

Risk	Impact	Mitigation
Target element not in DOM when tour starts	Spotlight renders incorrectly	Validate target existence; skip step with console warning
Dynamic layouts shift targets	Cutout misaligned	Recalculate on resize/scroll with throttled observer
Z-index conflicts	Backdrop hidden behind modals	Use a high z-index (configurable) and document layering guidance

---

Open Questions

1. Should the widget support hotspot-only mode (no sequential navigation)?
2. Do we need support for tooltip media (images, GIFs) inside steps?
3. Should the target element receive a temporary highlight ring in addition to the cutout?

---

Acceptance Criteria

• Backdrop renders with a cutout around the target element.
• Tooltip displays step content with correct placement.
• Navigation (Back, Next, Skip, Done) works correctly.
• Off-screen targets scroll into view.
• onStepChange, onComplete, and onDismiss callbacks fire at correct times.
• Escape key dismisses the tour.
• All Storybook stories render without errors.
• Passes axe accessibility audit with zero violations.
• Unit tests cover step navigation, skip, complete, and dismiss flows.

---

LLM Handoff Instructions

When implementing this FRD:

1. Create src/components/widgets/feature-spotlight.tsx.
2. Use a Portal to render the backdrop overlay at the document root.
3. Calculate target bounding rect for cutout positioning; use ResizeObserver and scroll listeners to keep it updated.
4. Use CSS clip-path or an SVG mask for the backdrop cutout.
5. Create src/components/widgets/feature-spotlight.stories.tsx. For stories, use mock target elements within a Storybook decorator.
6. Create src/components/widgets/feature-spotlight.test.tsx.
7. Use scrollIntoView({ behavior: "smooth", block: "center" }) for off-screen targets.

---

Decision Log

Date	Decision	Rationale
2026-05-26	Target via CSS selector or ref	Selector is convenient for quick tours; ref is type-safe for component-owned elements
2026-05-26	No built-in persistence	Persistence mechanisms vary (localStorage, API, cookie); consumer decides

---

Document History

Date	Version	Author	Changes
2026-05-26	0.1	David Holmes	Initial draft