# Docent

> Docent is a guided product tour library for the web: it dims the page, spotlights one element, and explains it in a small popover. A tour is a JSON document, so tours can be written by hand, generated, stored in a repo or served from an API. The engine (@docentjs/core) has no DOM code; the web renderer (@docentjs/dom) draws, positions and handles keyboard and focus; thin adapters exist for React, Vue and Svelte. Everything visual is data: arrows, spotlight shape and ring, overlay style, the step counter, the line above the title, theme tokens and presets, so a whole look is one JSON file.

## Working with tours

- A tour is `{ id, steps }` plus optional `trigger`, `conditions` and `options`. Every field is documented at https://docentjs.dev/reference/schema/.
- Point a `.tour.json` file at https://docentjs.dev/schema/tour-v1.json with `$schema` for completion and checking.
- Check tour files from a terminal or CI with `npx @docentjs/cli validate "tours/*.json"`; it exits 1 on errors and `--json` gives machine-readable output.
- Check a tour before shipping it: `import { validateTour } from '@docentjs/dom/validate'`. It reports unknown values, misspelled fields, wrong types and duplicate step ids, each with a path such as `steps[2].arrow` and the value that was probably meant. `createTour` and `createDocent` run the same check automatically in development.
- A beacon is a tour with `trigger: { type: 'beacon' }`: a small mark on the first step's target that opens the tour on click, or on hover with `open: 'hover'`. Its look is `options.beacon` (`style`: pulse, dot, ring, badge or none; `position`; `offset`; `size`; `text`) and its colour the `beacon` theme token. Beacons need the manager (`createDocent` or `useDocent`), not `createTour`.
- Prefer `target: { name: "save" }` with `data-docent="save"` in the markup over CSS selectors: names survive redesigns.
- Visual changes belong in the tour JSON (`options.theme`, `options.arrow`, `options.progress`, `options.eyebrow`, `options.spotlight`, `options.overlay`, `options.appearance`), not in CSS, so they travel with the tour.
- A whole look is one JSON file: a theme. Add one with `npx @docentjs/cli theme add <name>` (or a URL), then `renderer: { template: theme }`. Ready-made ones are at https://docentjs.dev/customize/themes/. Reach for `slots` (functions) only when no field covers what is needed, because a look with functions in it can no longer be published or edited as data.

## Documentation Sets

- [Abridged documentation](https://docentjs.dev/llms-small.txt): a compact version of the documentation for Docent, with non-essential content removed
- [Complete documentation](https://docentjs.dev/llms-full.txt): the full documentation for Docent

## Notes

- The complete documentation includes all content from the official documentation
- The content is automatically generated from the same source as the official documentation

## Optional

- [Tour JSON Schema](https://docentjs.dev/schema/tour-v1.json): Machine-readable schema for a tour document.
- [Source](https://github.com/FgrReloaded/docentjs): Repository, issues and changelogs.