# Interactive Guides

Interactive guides are in-app, step-by-step tours that highlight key UI elements
and explain workflows. They complement the video tutorials by giving users a
hands-on walkthrough.

## How It Works

- Guides are defined as structured steps with titles, content, and target
  selectors.
- The `GuideProvider` manages state and exposes `startGuide` and navigation
  actions.
- `GuideOverlay` renders the tooltip, spotlight, and progress UI.

## Step Types

- `modal`: Centered step without a target element.
- `tooltip`: Anchored tooltip with a highlight ring on the target.
- `highlight`: Spotlight cutout that dims everything except the target.

## Default Guide: Welcome Tour

Location: `apps/web/src/lib/guides.ts`

Selectors used:

- `[data-tour="dashboard-main"]` (Welcome page container)
- `[data-tour="main-nav"]` (Header navigation)
- `[data-tour="create-button"]` (New Project button)
- `[data-tour="user-menu"]` (Profile menu)

## Adding a New Guide

1. Define a new guide in `apps/web/src/lib/guides.ts`.
2. Add the guide to `APP_GUIDES`.
3. Add `data-tour` attributes to the target components.
4. Trigger the guide with `useGuide().startGuide('guide-id')`.

## Accessibility Notes

- Keyboard shortcuts: `Esc` to exit, `Enter`/`Right Arrow` to advance,
  `Left Arrow` to go back.
- The overlay uses `role="dialog"` and `aria-modal="true"`.
