@adia-ai/web-components 0.6.37 → 0.6.39

package/components/tour/tour.class.js

@@ -0,0 +1,309 @@
+/**
+ * `<tour-ui>` — spotlight-driven product tour / guided walkthrough.
+ *
+ * Orchestrates a sequence of `<tour-step>` children, each declaring a
+ * target element via CSS selector. When active, dims the page with a
+ * scrim, cuts a "hole" around the current step's target, and renders
+ * a popover next to it with step content + Skip / Previous / Next.
+ *
+ * Architecture:
+ *   - Host is `display: contents` (no chrome).
+ *   - On start, mounts two surfaces into `document.body`:
+ *     1. [data-tour-spotlight] — transparent rect with huge box-shadow
+ *        scrim. Position via top/left, size via width/height (animated).
+ *     2. [data-tour-popover] — manual popover with step content + nav,
+ *        anchored to the target via core/anchor.js (same mechanism as
+ *        menu-ui / context-menu-ui / popover-ui).
+ *   - Spotlight repositions on window resize/scroll while active.
+ *
+ * @see ../../core/anchor.js
+ * @see ../onboarding-checklist/ — peer onboarding primitive (user-paced).
+ */
+
+import { UIElement } from '../../core/element.js';
+import { anchorPopover } from '../../core/anchor.js';
+
+export class UITour extends UIElement {
+  static properties = {
+    active:        { type: Boolean, default: false, reflect: true },
+    step:          { type: Number,  default: 0,     reflect: false },
+    autoStart:     { type: Boolean, default: false, reflect: true, attribute: 'auto-start' },
+    storageKey:    { type: String,  default: '',    reflect: true, attribute: 'storage-key' },
+  };
+
+  static template = () => null;
+
+  #spotlight = null;
+  #popover = null;
+  #anchorCleanup = null;
+  #onResize = null;
+  #onScroll = null;
+  #onKeydown = null;
+
+  connected() {
+    super.connected();
+    if (this.autoStart && !this.#alreadyDone()) {
+      // Defer one frame so consumer targets (which may also mount on the
+      // same tick) have a chance to land in the DOM first.
+      requestAnimationFrame(() => {
+        if (this.isConnected && this.autoStart) this.start();
+      });
+    }
+  }
+
+  disconnected() {
+    super.disconnected();
+    this.#teardown();
+  }
+
+  /* ── Public API ──────────────────────────────────────────────────── */
+
+  start() {
+    if (this.active) return;
+    if (!this.#steps.length) {
+      // eslint-disable-next-line no-console
+      console.warn('[tour-ui] start() called with no <tour-step> children — nothing to render.');
+      return;
+    }
+    this.step = 0;
+    this.active = true;
+    this.#mount();
+    this.#renderStep();
+    this.dispatchEvent(new CustomEvent('tour-start', {
+      bubbles: true,
+      detail: { step: 0 },
+    }));
+  }
+
+  next() {
+    if (!this.active) return;
+    const total = this.#steps.length;
+    if (this.step >= total - 1) { this.finish(); return; }
+    const from = this.step;
+    this.step = from + 1;
+    this.#renderStep();
+    this.dispatchEvent(new CustomEvent('tour-step-change', {
+      bubbles: true,
+      detail: { from, to: this.step, totalSteps: total },
+    }));
+  }
+
+  previous() {
+    if (!this.active) return;
+    if (this.step <= 0) return;
+    const from = this.step;
+    this.step = from - 1;
+    this.#renderStep();
+    this.dispatchEvent(new CustomEvent('tour-step-change', {
+      bubbles: true,
+      detail: { from, to: this.step, totalSteps: this.#steps.length },
+    }));
+  }
+
+  skip() {
+    if (!this.active) return;
+    const total = this.#steps.length;
+    const at = this.step;
+    this.#recordDone();
+    this.active = false;
+    this.#teardown();
+    this.dispatchEvent(new CustomEvent('tour-skip', {
+      bubbles: true,
+      detail: { step: at, totalSteps: total },
+    }));
+  }
+
+  finish() {
+    if (!this.active) return;
+    const total = this.#steps.length;
+    this.#recordDone();
+    this.active = false;
+    this.#teardown();
+    this.dispatchEvent(new CustomEvent('tour-finish', {
+      bubbles: true,
+      detail: { totalSteps: total },
+    }));
+  }
+
+  /* ── Internals ───────────────────────────────────────────────────── */
+
+  get #steps() {
+    return [...this.querySelectorAll(':scope > tour-step-ui')];
+  }
+
+  #alreadyDone() {
+    if (!this.storageKey) return false;
+    try { return localStorage.getItem(this.storageKey) === 'done'; }
+    catch { return false; }
+  }
+
+  #recordDone() {
+    if (!this.storageKey) return;
+    try { localStorage.setItem(this.storageKey, 'done'); }
+    catch { /* quota / privacy mode — silently ignore */ }
+  }
+
+  #mount() {
+    if (!this.#spotlight) {
+      const sp = document.createElement('div');
+      sp.setAttribute('data-tour-spotlight', '');
+      sp.setAttribute('aria-hidden', 'true');
+      document.body.appendChild(sp);
+      this.#spotlight = sp;
+    }
+    if (!this.#popover) {
+      const pop = document.createElement('div');
+      pop.setAttribute('data-tour-popover', '');
+      pop.setAttribute('popover', 'manual');
+      pop.setAttribute('role', 'dialog');
+      pop.setAttribute('aria-modal', 'false');
+      pop.tabIndex = -1;
+      pop.style.outline = 'none';
+      pop.addEventListener('click', this.#onPopoverClick);
+      document.body.appendChild(pop);
+      this.#popover = pop;
+    }
+
+    // Reposition spotlight on viewport changes while active. anchorPopover
+    // (called per-step in #renderStep) handles popover repositioning.
+    this.#onResize = () => this.#positionSpotlight();
+    this.#onScroll = () => this.#positionSpotlight();
+    window.addEventListener('resize', this.#onResize);
+    window.addEventListener('scroll', this.#onScroll, true /* capture */);
+
+    // Keyboard navigation
+    this.#onKeydown = (e) => {
+      if (!this.active) return;
+      if (e.key === 'Escape') { e.preventDefault(); this.skip(); }
+      else if (e.key === 'ArrowRight') { e.preventDefault(); this.next(); }
+      else if (e.key === 'ArrowLeft')  { e.preventDefault(); this.previous(); }
+    };
+    document.addEventListener('keydown', this.#onKeydown);
+  }
+
+  #teardown() {
+    this.#anchorCleanup?.();
+    this.#anchorCleanup = null;
+    if (this.#onResize) window.removeEventListener('resize', this.#onResize);
+    if (this.#onScroll) window.removeEventListener('scroll', this.#onScroll, true);
+    if (this.#onKeydown) document.removeEventListener('keydown', this.#onKeydown);
+    this.#onResize = this.#onScroll = this.#onKeydown = null;
+    try { this.#popover?.hidePopover?.(); } catch { /* noop */ }
+    this.#popover?.removeEventListener('click', this.#onPopoverClick);
+    this.#popover?.remove();
+    this.#popover = null;
+    this.#spotlight?.remove();
+    this.#spotlight = null;
+  }
+
+  #renderStep() {
+    const step = this.#steps[this.step];
+    if (!step) return;
+
+    const total = this.#steps.length;
+    const isLast = this.step === total - 1;
+    const isFirst = this.step === 0;
+    const title = step.getAttribute('title') || '';
+    const placement = step.getAttribute('placement') || 'bottom';
+    const targetSel = step.getAttribute('target') || '';
+    const target = targetSel ? document.querySelector(targetSel) : null;
+
+    // Spotlight position
+    this.#currentTarget = target;
+    this.#positionSpotlight();
+
+    // Popover content
+    const indicator = `${this.step + 1} of ${total}`;
+    const bodyHTML = step.innerHTML;
+    this.#popover.innerHTML = `
+      <div data-tour-header>
+        <span data-tour-indicator>${indicator}</span>
+        <span></span>
+      </div>
+      <h3 data-tour-title>${escapeHtml(title)}</h3>
+      <div data-tour-body>${bodyHTML}</div>
+      <div data-tour-footer>
+        <button-ui data-tour-skip variant="ghost" size="sm" text="Skip"></button-ui>
+        <div data-tour-nav>
+          ${isFirst ? '' : '<button-ui data-tour-previous variant="outline" size="sm" text="Back"></button-ui>'}
+          <button-ui data-tour-next variant="primary" size="sm" text="${isLast ? 'Done' : 'Next →'}"></button-ui>
+        </div>
+      </div>
+    `;
+
+    // Open the popover (idempotent) + position it.
+    try { this.#popover.showPopover(); } catch { /* popover API unavailable */ }
+    this.#anchorCleanup?.();
+    if (target) {
+      this.#anchorCleanup = anchorPopover(target, this.#popover, { placement, gap: 12 });
+    } else {
+      // No target — center the popover in the viewport
+      this.#popover.style.position = 'fixed';
+      this.#popover.style.top = '50%';
+      this.#popover.style.left = '50%';
+      this.#popover.style.transform = 'translate(-50%, -50%)';
+    }
+
+    // Move focus to the popover so keyboard nav works immediately
+    queueMicrotask(() => this.#popover?.focus?.());
+  }
+
+  #currentTarget = null;
+
+  #positionSpotlight() {
+    if (!this.#spotlight) return;
+    const target = this.#currentTarget;
+    if (!target) {
+      this.#spotlight.setAttribute('data-tour-no-target', '');
+      return;
+    }
+    this.#spotlight.removeAttribute('data-tour-no-target');
+    const rect = target.getBoundingClientRect();
+    // Add halo padding around the target
+    const cs = getComputedStyle(this);
+    const halo = parseFloat(cs.getPropertyValue('--tour-spotlight-padding')) || 8;
+    const top  = Math.max(0, rect.top - halo);
+    const left = Math.max(0, rect.left - halo);
+    const w = rect.width + halo * 2;
+    const h = rect.height + halo * 2;
+    this.#spotlight.style.top = `${top}px`;
+    this.#spotlight.style.left = `${left}px`;
+    this.#spotlight.style.width = `${w}px`;
+    this.#spotlight.style.height = `${h}px`;
+  }
+
+  #onPopoverClick = (e) => {
+    const t = e.target;
+    if (!t || !t.closest) return;
+    if (t.closest('[data-tour-skip]')) { this.skip(); return; }
+    if (t.closest('[data-tour-previous]')) { this.previous(); return; }
+    if (t.closest('[data-tour-next]')) { this.next(); return; }
+  };
+}
+
+/**
+ * `<tour-step>` — data carrier for a single step inside `<tour-ui>`.
+ *
+ * Renders nothing on its own (`display: none` via tour.css). tour-ui
+ * reads target / title / placement / body content from it on activation.
+ */
+export class UITourStep extends UIElement {
+  static properties = {
+    target:    { type: String, default: '',       reflect: true },
+    title:     { type: String, default: '',       reflect: true },
+    placement: { type: String, default: 'bottom', reflect: true },
+  };
+
+  static template = () => null;
+
+  // No connected/disconnected behavior needed — pure data carrier.
+}
+
+function escapeHtml(s) {
+  return String(s ?? '')
+    .replace(/&/g, '&amp;')
+    .replace(/</g, '&lt;')
+    .replace(/>/g, '&gt;')
+    .replace(/"/g, '&quot;')
+    .replace(/'/g, '&#39;');
+}

package/components/tour/tour.css

@@ -0,0 +1,135 @@
+@scope (tour-ui) {
+  :where(:scope) {
+    --tour-scrim-default:             var(--a-scrim-dialog);
+    --tour-spotlight-padding-default: var(--a-space-2);
+    --tour-spotlight-radius-default:  var(--a-radius-md);
+  }
+
+  :scope {
+    /* Behavioral wrapper — no chrome. Tour-step children are hidden;
+       the orchestrator clones their content into the popover surface. */
+    display: contents;
+  }
+
+  :scope > tour-step-ui {
+    display: none;
+  }
+}
+
+/* The spotlight + popover surfaces are NOT scoped to tour-ui — they're
+   appended to document.body (top-layer via Popover API), outside the
+   @scope (tour-ui) boundary. Mirror the menu-ui / context-menu-ui
+   pattern: chrome lives in the global scope keyed off a data-attribute. */
+
+/* ── Spotlight ──
+   A position:fixed transparent rectangle with a huge box-shadow that
+   produces the dimmed scrim everywhere outside its bounds. Single
+   element, no clip-path / SVG mask. Animated via top/left/width/height
+   transitions when the step changes. */
+[data-tour-spotlight] {
+  position: fixed;
+  inset: 0 auto auto 0;            /* anchor at viewport top-left; top/left set imperatively */
+  width: 0;
+  height: 0;
+  pointer-events: none;
+  border-radius: var(--tour-spotlight-radius, var(--a-radius-md));
+  background: transparent;
+  box-shadow: 0 0 0 9999px var(--tour-scrim, var(--a-scrim-dialog));
+  z-index: 1000;
+  transition:
+    top var(--a-duration) var(--a-easing-out),
+    left var(--a-duration) var(--a-easing-out),
+    width var(--a-duration) var(--a-easing-out),
+    height var(--a-duration) var(--a-easing-out);
+}
+
+[data-tour-spotlight][data-tour-no-target] {
+  /* No target match — fall back to a non-cutout full-viewport scrim */
+  inset: 0;
+  width: 100vw;
+  height: 100vh;
+  box-shadow: none;
+  background: var(--tour-scrim, var(--a-scrim-dialog));
+  border-radius: 0;
+}
+
+@media (prefers-reduced-motion: reduce) {
+  [data-tour-spotlight] { transition: none; }
+}
+
+/* ── Step popover ── */
+[data-tour-popover] {
+  margin: 0;
+  padding: var(--a-space-4);
+  border: 1px solid var(--tour-popover-border, var(--a-border-subtle));
+  border-radius: var(--tour-popover-radius, var(--a-radius-lg));
+  background: var(--tour-popover-bg, var(--a-bg-subtle));
+  box-shadow: var(--tour-popover-shadow, var(--a-shadow-lg));
+  min-width: var(--tour-popover-min-width, 18rem);
+  max-width: var(--tour-popover-max-width, 22rem);
+  font-family: inherit;
+  font-size: var(--a-ui-size);
+  color: var(--a-fg);
+  /* Above the spotlight (1000) so the user can read + click it */
+  z-index: 1001;
+  opacity: 1;
+  translate: 0 0;
+  transition:
+    opacity var(--a-duration-fast) var(--a-easing-out),
+    translate var(--a-duration-fast) var(--a-easing-out);
+}
+
+[data-tour-popover]:popover-open {
+  @starting-style {
+    opacity: 0;
+    translate: 0 -4px;
+  }
+}
+
+[data-tour-popover]:not(:popover-open) {
+  display: none !important;
+}
+
+@media (prefers-reduced-motion: reduce) {
+  [data-tour-popover] { transition: none; }
+}
+
+/* Layout of the popover internal content (set by the orchestrator). */
+[data-tour-popover] [data-tour-header] {
+  display: flex;
+  align-items: center;
+  justify-content: space-between;
+  gap: var(--a-space-3);
+  margin-block-end: var(--a-space-2);
+}
+
+[data-tour-popover] [data-tour-indicator] {
+  font-size: var(--a-ui-sm);
+  color: var(--a-fg-muted);
+  font-variant-numeric: tabular-nums;
+}
+
+[data-tour-popover] [data-tour-title] {
+  margin: 0;
+  font-size: var(--a-text-lg);
+  font-weight: 600;
+}
+
+[data-tour-popover] [data-tour-body] {
+  margin: 0 0 var(--a-space-4);
+  font-size: var(--a-ui-size);
+  color: var(--a-fg);
+  line-height: 1.5;
+}
+
+[data-tour-popover] [data-tour-footer] {
+  display: flex;
+  align-items: center;
+  justify-content: space-between;
+  gap: var(--a-space-2);
+}
+
+[data-tour-popover] [data-tour-nav] {
+  display: flex;
+  gap: var(--a-space-2);
+}

package/components/tour/tour.d.ts

@@ -0,0 +1,78 @@
+/**
+ * `<tour-ui>` — Spotlight-driven product tour / guided walkthrough. Hosts a sequence
+of `<tour-step>` children, each targeting an element via CSS selector.
+When active, dims the page with a scrim, cuts a "hole" around the
+current step's target, and renders a popover next to it with step
+content + Skip / Previous / Next navigation.
+
+Use for first-run onboarding tours, feature introductions after a
+release, and inline walkthroughs the user opts into ("Take the tour").
+Distinct from `<onboarding-checklist-ui>` (persistent todo-list of
+setup steps the user works through at their own pace) and from
+`<tooltip-ui>` (single hover hint with no orchestration).
+
+Architecture: tour-ui is a behavioral wrapper (`display: contents`)
+that reads target / title / content from `<tour-step>` children. On
+start, mounts a spotlight + popover surface into `document.body`
+(top-layer via Popover API). The spotlight is a transparent
+position:fixed element with a huge box-shadow that produces the
+dimmed scrim outside its bounds (single-element backdrop, no clip-path
+or SVG mask needed). The popover is anchored to the target via the
+same `core/anchor.js` pattern used by menu-ui / context-menu-ui /
+popover-ui.
+
+ *
+ * @see https://ui-kit.exe.xyz/site/components/tour
+ *
+ * Type declarations generated by scripts/build/dts-codegen.mjs from
+ * the component's `.a2ui.json` sidecar(s). Edit the source `.yaml`,
+ * run `npm run build:components`, then `npm run codegen:dts` to
+ * regenerate; or hand-author this file fully if rich event types are
+ * needed beyond what the yaml `events:` block can express.
+ */
+
+import { UIElement } from '../../core/element.js';
+
+export type TourFinishEvent = CustomEvent<unknown>;
+export type TourSkipEvent = CustomEvent<unknown>;
+export type TourStartEvent = CustomEvent<unknown>;
+export type TourStepChangeEvent = CustomEvent<unknown>;
+
+export class UITour extends UIElement {
+  /** Whether the tour is currently running. Setting to `true` mounts
+the spotlight + popover; setting to `false` tears down.
+ */
+  active: boolean;
+  /** Current step index (0-based). Setting this property advances the
+tour to that step (updating spotlight + popover position).
+ */
+  step: number;
+
+  addEventListener<K extends keyof HTMLElementEventMap>(
+    type: K,
+    listener: (this: UITour, ev: HTMLElementEventMap[K]) => unknown,
+    options?: boolean | AddEventListenerOptions,
+  ): void;
+  addEventListener(type: 'tour-finish', listener: (ev: TourFinishEvent) => unknown, options?: boolean | AddEventListenerOptions): void;
+  addEventListener(type: 'tour-skip', listener: (ev: TourSkipEvent) => unknown, options?: boolean | AddEventListenerOptions): void;
+  addEventListener(type: 'tour-start', listener: (ev: TourStartEvent) => unknown, options?: boolean | AddEventListenerOptions): void;
+  addEventListener(type: 'tour-step-change', listener: (ev: TourStepChangeEvent) => unknown, options?: boolean | AddEventListenerOptions): void;
+}
+
+export class UITourStep extends UIElement {
+  /** Step heading rendered in the popover. */
+  title: string;
+  /** Preferred popover placement relative to the target. Same vocabulary
+as `core/anchor.js` (`top`, `bottom`, `left`, `right`,
+`bottom-start`, `bottom-end`, etc.). Auto-flips on viewport overflow
+via position-try-fallbacks.
+ */
+  placement: 'top' | 'bottom' | 'left' | 'right' | 'top-start' | 'top-end' | 'bottom-start' | 'bottom-end' | 'left-start' | 'left-end' | 'right-start' | 'right-end';
+  /** CSS selector for the element to spotlight when this step is
+active. Resolved via `document.querySelector(target)` at step
+activation time. If the selector matches nothing, the spotlight
+falls back to viewport-center and the popover anchors to the
+page (no halo cutout).
+ */
+  target: string;
+}

package/components/tour/tour.js

@@ -0,0 +1,13 @@
+/**
+ * `<tour-ui>` + `<tour-step>` — auto-registers both tags on import.
+ *
+ * @see ../../USAGE.md#registration--auto-vs-explicit
+ */
+
+import { defineIfFree } from '../../core/register.js';
+import { UITour, UITourStep } from './tour.class.js';
+
+defineIfFree('tour-ui', UITour);
+defineIfFree('tour-step-ui', UITourStep);
+
+export { UITour, UITourStep };

package/components/tour/tour.yaml

@@ -0,0 +1,161 @@
+$schema: ../../../../scripts/schemas/component.yaml.schema.json
+name: UITour
+tag: tour-ui
+status: stable
+component: Tour
+category: feedback
+version: 1
+description: |
+  Spotlight-driven product tour / guided walkthrough. Hosts a sequence
+  of `<tour-step>` children, each targeting an element via CSS selector.
+  When active, dims the page with a scrim, cuts a "hole" around the
+  current step's target, and renders a popover next to it with step
+  content + Skip / Previous / Next navigation.
+
+  Use for first-run onboarding tours, feature introductions after a
+  release, and inline walkthroughs the user opts into ("Take the tour").
+  Distinct from `<onboarding-checklist-ui>` (persistent todo-list of
+  setup steps the user works through at their own pace) and from
+  `<tooltip-ui>` (single hover hint with no orchestration).
+
+  Architecture: tour-ui is a behavioral wrapper (`display: contents`)
+  that reads target / title / content from `<tour-step>` children. On
+  start, mounts a spotlight + popover surface into `document.body`
+  (top-layer via Popover API). The spotlight is a transparent
+  position:fixed element with a huge box-shadow that produces the
+  dimmed scrim outside its bounds (single-element backdrop, no clip-path
+  or SVG mask needed). The popover is anchored to the target via the
+  same `core/anchor.js` pattern used by menu-ui / context-menu-ui /
+  popover-ui.
+composes:
+  - button-ui
+  - tour-step-ui
+props:
+  active:
+    description: |
+      Whether the tour is currently running. Setting to `true` mounts
+      the spotlight + popover; setting to `false` tears down.
+    type: boolean
+    default: false
+    reflect: true
+  step:
+    description: |
+      Current step index (0-based). Setting this property advances the
+      tour to that step (updating spotlight + popover position).
+    type: number
+    default: 0
+    reflect: false
+  auto-start:
+    description: |
+      Start the tour automatically when the element connects. Useful for
+      first-run flows gated by a storage flag on the consumer side.
+    type: boolean
+    default: false
+    reflect: true
+  storage-key:
+    description: |
+      Optional localStorage key. When set, the tour records its
+      completion state (`"done"`) to that key on finish/skip — and
+      refuses to auto-start on subsequent loads if the key is "done".
+      Useful for "show this tour once per user" flows.
+    type: string
+    default: ''
+    reflect: true
+events:
+  tour-start:
+    description: 'Fired when the tour starts (after spotlight + popover mount). detail = { step }. Bubbles.'
+  tour-step-change:
+    description: 'Fired when the active step changes. detail = { from, to, totalSteps }. Bubbles.'
+  tour-skip:
+    description: 'Fired when the user skips the tour mid-way. detail = { step, totalSteps }. Bubbles.'
+  tour-finish:
+    description: 'Fired when the user completes the last step. detail = { totalSteps }. Bubbles.'
+slots:
+  default:
+    description: '<tour-step> children — each declares target + title + body content.'
+states:
+  - name: idle
+    description: Tour is dormant; no scrim / popover rendered.
+  - name: active
+    description: Tour is running; scrim dims the page, current target is spotlighted.
+  - name: complete
+    description: Last step reached (Done is shown instead of Next).
+traits: []
+tokens:
+  --tour-scrim:
+    description: Backdrop scrim color (everything outside the spotlight).
+    default: var(--a-scrim-dialog)
+  --tour-spotlight-padding:
+    description: Padding around the target bounding box (the spotlight's "halo").
+    default: var(--a-space-2)
+  --tour-spotlight-radius:
+    description: Border radius of the spotlight cutout.
+    default: var(--a-radius-md)
+  --tour-popover-bg:
+    description: Background of the step-content popover.
+    default: var(--a-bg-subtle)
+  --tour-popover-border:
+    description: Border color of the popover.
+    default: var(--a-border-subtle)
+  --tour-popover-shadow:
+    description: Shadow of the popover.
+    default: var(--a-shadow-lg)
+  --tour-popover-radius:
+    description: Border-radius of the popover.
+    default: var(--a-radius-lg)
+  --tour-popover-min-width:
+    description: Minimum width of the popover (so step text wraps reasonably).
+    default: 18rem
+  --tour-popover-max-width:
+    description: Maximum width of the popover.
+    default: 22rem
+a2ui:
+  rules:
+    - rule: 'Use tour-ui for spotlight-driven product tours / walkthroughs — sequence of steps each targeting a CSS-selector-resolved element.'
+      reason: 'Primary use case — guided feature introduction.'
+    - rule: 'Children are <tour-step target="..." title="..."> with body content as the default slot. tour-ui reads them in DOM order.'
+      reason: 'Authoring contract.'
+    - rule: 'Set [auto-start] for first-run flows (paired with [storage-key] so it only shows once). Otherwise call .start() programmatically from a "Take the tour" button.'
+      reason: 'Activation contract.'
+    - rule: 'Distinct from <onboarding-checklist-ui> (persistent setup todo-list, user-paced) and <tooltip-ui> (single hover hint, no orchestration).'
+      reason: 'Sibling-component boundary.'
+    - rule: 'Listen to `tour-finish` for "user completed the tour" analytics; `tour-skip` for "user opted out". Both fire once per session.'
+      reason: 'Event-handling contract.'
+anti_patterns:
+  - wrong: '<tour-ui><div>step 1 content</div><div>step 2 content</div></tour-ui>'
+    why: 'Bare divs have no target / title — tour-ui can''t position the spotlight.'
+    fix: '<tour-ui><tour-step target="#dashboard" title="Dashboard">Tour the dashboard…</tour-step>…</tour-ui>'
+  - wrong: '<tour-step target="dashboard">'
+    why: 'target is a CSS selector — bare "dashboard" matches a <dashboard> element, NOT an id; use the # prefix.'
+    fix: '<tour-step target="#dashboard">'
+examples:
+  - name: basic-tour
+    description: A 3-step product tour anchored to selector-resolved elements.
+    a2ui: |
+      [
+        { "id": "tour", "component": "Tour", "auto-start": true, "children": ["s1", "s2", "s3"] },
+        { "id": "s1", "component": "TourStep", "target": "#dashboard", "title": "Your dashboard", "textContent": "Here's where you'll see your latest activity." },
+        { "id": "s2", "component": "TourStep", "target": "#filters", "title": "Filters", "textContent": "Narrow results by status, owner, or date." },
+        { "id": "s3", "component": "TourStep", "target": "#export", "title": "Export", "textContent": "Download a CSV of the current view." }
+      ]
+keywords:
+  - tour
+  - product-tour
+  - walkthrough
+  - guided-tour
+  - spotlight
+  - coachmark
+  - feature-introduction
+synonyms:
+  tour:
+    - product-tour
+    - guided-tour
+    - walkthrough
+    - feature-intro
+  spotlight:
+    - coachmark
+    - feature-highlight
+related:
+  - tooltip
+  - popover
+  - onboarding-checklist