# React Tourlight

> Free React product guidance with a visual Studio, portable JSON documents, headless engine, and local agent tools. MIT licensed.

Use one versioned TourDocument across product-team visual edits, developer code review, and agent-authored changes. Studio is an optional entry at react-tourlight/studio; it does not enter player bundles. The existing React API remains supported.

Runtime: React 18/19, route-aware tours, persistence and resume, real interactive steps, beacons, light/dark themes, custom tooltips, keyboard navigation, focus management, and headless react-tourlight/core. Styled runtime peer: @floating-ui/react-dom. Test accessibility in your application.

Agent workflow: read the skill, generate data using the JSON Schema, validate with the CLI, inspect current-page targets, and run real browser scenarios. JSON content is plain text; application capabilities use named registry entries. Never put executable code or secrets in tour documents. A generated test is not evidence that it passed.

## Entry points

- [Portable agent skill](https://react-tourlight.vercel.app/tourlight-skill.md): Integration and authoring workflow
- [TourDocument JSON Schema](https://react-tourlight.vercel.app/tour.schema.json): Version 1 data contract
- [Complete documentation](https://react-tourlight.vercel.app/llms-full.txt): Concatenated source guides
- [Visual Studio](https://react-tourlight.vercel.app/studio): Local-draft authoring playground
- [Source repository](https://github.com/btahir/react-tourlight): Package, CLI, tests, and separate MCP workspace

## Documentation

- [Accessibility](https://react-tourlight.vercel.app/docs/accessibility): Focus management, keyboard behavior, ARIA semantics, reduced motion, and what to verify in your integration.
- [Build with agents](https://react-tourlight.vercel.app/docs/agents): Give your coding agent a guide format it can understand, validate, and hand back to your team.
- [API Reference](https://react-tourlight.vercel.app/docs/api-reference): Complete reference for all react-tourlight components, hooks, and types.
- [Async Elements](https://react-tourlight.vercel.app/docs/async-elements): Handle dynamically loaded content, lazy components, and elements that appear after mount.
- [Beacons](https://react-tourlight.vercel.app/docs/beacons): Pulsing hotspots that let users opt into a tour or a "what's new" callout instead of being interrupted.
- [Customization](https://react-tourlight.vercel.app/docs/customization): Customize themes, tooltips, labels, transitions, and overlay appearance to match your brand.
- [Tour documents](https://react-tourlight.vercel.app/docs/documents): One portable guide format for product people, developers, and agents.
- [Checklists & guide launcher](https://react-tourlight.vercel.app/docs/guidance): Let people discover, start, and revisit useful guides at their own pace.
- [Headless Core](https://react-tourlight.vercel.app/docs/headless): Build a fully custom tour UI with react-tourlight/core — the unstyled engine with no CSS and no Floating UI.
- [Single-Element Highlights](https://react-tourlight.vercel.app/docs/highlight): Highlight individual elements for "what's new" callouts and feature announcements without a full tour.
- [Introduction](https://react-tourlight.vercel.app/docs): Choose visual authoring, portable documents, or the React API to build your first guide.
- [Interactive Steps](https://react-tourlight.vercel.app/docs/interactive): Let users interact with the real highlighted element and auto-advance the tour when they do.
- [Migrating from React Joyride](https://react-tourlight.vercel.app/docs/migration): Step-by-step guide to migrate from React Joyride to react-tourlight.
- [Multi-Page Tours](https://react-tourlight.vercel.app/docs/multi-page): Build tours that survive SPA navigation and full page reloads with built-in route-aware steps, navigation, and persistence.
- [Self-hosting](https://react-tourlight.vercel.app/docs/self-hosting): Run Studio locally, embed it in your app, or host the documentation and playground yourself.
- [Visual Studio](https://react-tourlight.vercel.app/docs/studio): Build and edit guides in the application they explain. No Tourlight account required.
- [Testing & diagnostics](https://react-tourlight.vercel.app/docs/testing): Separate a valid guide document, a ready target, and a successful real-user journey.
- [Multi-Step Tours](https://react-tourlight.vercel.app/docs/tour): Build guided walkthroughs with multi-step tours, lifecycle hooks, conditional steps, and interactive elements.
- [Troubleshooting & FAQ](https://react-tourlight.vercel.app/docs/troubleshooting): Common issues, browser compatibility, and frequently asked questions.
- [Tracking Tour Completion](https://react-tourlight.vercel.app/docs/recipes/analytics): Track tour completion, skip events, and step-level drop-off with analytics providers.
- [Next.js Integration](https://react-tourlight.vercel.app/docs/recipes/nextjs): Set up react-tourlight with Next.js App Router, including client component wrappers and SSR considerations.
- [React Router](https://react-tourlight.vercel.app/docs/recipes/react-router): Wire react-tourlight to React Router for multi-page, route-aware tours with persistence.
- [Remix Integration](https://react-tourlight.vercel.app/docs/recipes/remix): Set up react-tourlight with Remix, including client-only rendering considerations.
- [shadcn/ui Themed Tooltip](https://react-tourlight.vercel.app/docs/recipes/shadcn): Build a custom tooltip styled with shadcn/ui components to match your app's design system.

## Boundaries

No Tourlight account, telemetry backend, model API key, or hosted service is required. Live picking works within the app where Studio is mounted, not on arbitrary third-party websites. The optional MCP server uses local stdio; clients requiring a remote HTTPS transport need a separate authenticated deployment. Read the current source/release notes before assuming unreleased workspace features are on npm.