@urbicon-ui/blocks 6.28.0 → 6.29.0

package/README.md

@@ -121,6 +121,8 @@ bun run test                                  # Run tests (from root)
 
 ## Related
 
-- [docs/ARCHITECTURE.md](../../docs/ARCHITECTURE.md) — Token system, Mint, Preset-System, i18n
-- [docs/COMPONENT-API-CONVENTIONS.md](../../docs/COMPONENT-API-CONVENTIONS.md) — Props, callbacks, styling patterns
-- [docs/ComponentStructureStandard.md](../../docs/ComponentStructureStandard.md) — File structure, index.ts, variants.ts
+- [docs/GUIDE.md](./docs/GUIDE.md) — Guide system (help panel, hints, UI↔guide linking, guided tour): architecture + as-built contract. Ships in this package.
+- [docs/MIGRATION-v5.md](./docs/MIGRATION-v5.md) — v4 → v5 consumer migration guide. Ships in this package.
+- [docs/ARCHITECTURE.md](../../docs/ARCHITECTURE.md) — Token system, Mint, Preset-System, i18n (monorepo only)
+- [docs/COMPONENT-API-CONVENTIONS.md](../../docs/COMPONENT-API-CONVENTIONS.md) — Props, callbacks, styling patterns (monorepo only)
+- [docs/ComponentStructureStandard.md](../../docs/ComponentStructureStandard.md) — File structure, index.ts, variants.ts (monorepo only)

package/docs/GUIDE.md

@@ -0,0 +1,480 @@
+# Guide System
+
+The **`Guide`** component family is a bidirectional in-app help system: a non-modal help
+panel, contextual hints, UI↔guide links, and an opt-in guided tour — all over *one* headless
+engine. Shipped in **v5.8.0**, stability **beta**. Lives on `@urbicon-ui/blocks` (no separate
+package).
+
+This is the living architecture/usage reference, shipped in the npm tarball
+(`docs/GUIDE.md`). The monorepo's broader conventions (token system, component
+families, decision matrices, Svelte 5 patterns) live in the repo's `docs/`
+directory; where a decision below depends on one of them, the relevant rule is
+restated in place.
+
+---
+
+## 1. What it is
+
+`Guide` is the library's first **sequential, system-driven** overlay pattern. Every other
+overlay (Tooltip, Popover, Dialog, Menu) is *spatial and event-driven* — the user clicks,
+something appears *there*. `Guide` inverts that: the system decides *when*, *in what order*,
+and *in which mode* help appears.
+
+The value is **not** the tour mechanic (product tours are rightly distrusted) but three design
+principles:
+
+1. **Helpful, not intrusive.** The defaults are the *callable* help panel and the *waiting*
+   hint — not a modal forced tour. The scrim-modal guided tour is the most aggressive mode and
+   stays **opt-in**.
+2. **One shared namespace.** Every UI spot with a help identity carries `data-guide="<topic-id>"`.
+   Tours, markers, hints, and article references all resolve through that one namespace — it
+   connects the modes instead of duplicating them.
+3. **Bidirectional.** UI ↔ Guide is linkable in both directions (§4) — the actual
+   differentiator versus Joyride/driver.js/Shepherd.
+
+### Modes (surfaces over one engine)
+
+| Mode | Intrusiveness | Purpose |
+|---|---|---|
+| **Sidebar help panel** (`GuidePanel`) | callable, self-directed | Structured in-app reference (the main focus) |
+| **Contextual hint** (`GuideHint`) | waiting, non-blocking | Micro-help at the right element at the right time |
+| **Bidirectional link** (`GuideMarker` ↔ `GuideMention`) | passive | UI explains itself; the article points back at the UI |
+| **Guided tour + spotlight** (`Guide`, `GuideBeacon`) | modal/blocking | Critical first-run flows, **opt-in** |
+
+---
+
+## 2. Architecture
+
+### Headless engine + swappable surfaces
+
+```
+            ┌──────────────────────────────────────────────┐
+            │  GuideController  (utils/guide.svelte.ts)     │
+            │  Class · $state · untrack · SvelteMap/Set     │
+            │                                               │
+            │  #targets: SvelteMap<id, RegisteredTarget>    │
+            │  activeTour · stepIndex · highlightedId       │
+            │  panelOpen · activeArticle · panelId · #seen  │
+            │                                               │
+            │  registerTarget()/target() · resolveTarget()  │
+            │  startTour() next() prev() skip() finish()    │
+            │  stopTour() · reapplyStepHighlight()          │
+            │  highlight(id) / clearHighlight()             │
+            │  openPanel(article?) / closePanel()           │
+            │  hasSeen()/markSeen()/resetSeen() ← Storage    │
+            └───────────────────────┬──────────────────────┘
+                       createOptionalContext<GuideController>()
+                                     ▼
+   Surfaces (consume the controller via context):
+     • GuidePanel + GuideArticle  — non-modal help panel (main focus)
+     • GuideMarker                — direction A: UI → panel (ⓘ trigger)
+     • GuideMention               — direction B: article → UI highlight (additive ring)
+     • GuideHint                  — contextual, waiting hint
+     • Guide + GuideBeacon        — guided tour + spotlight (opt-in)
+```
+
+- **Engine** (`packages/blocks/src/lib/utils/guide.svelte.ts`) is a `class` modeled on
+  `overlay-stack.svelte.ts` (`$state` + `untrack`, no string context keys). **Completely
+  UI-free** and unit-tested in isolation (`guide.svelte.test.ts`, node env). This is the
+  valuable part.
+- **Surfaces** are thin views in `packages/blocks/src/lib/components/Guide/*` that consume the
+  engine via `createOptionalContext` — a surface used **without** a `GuideProvider` renders
+  inert (or as plain text for `GuideMention`) instead of throwing `missing_context`.
+- **No separate package.** The UI depends fundamentally on `floating`/`Portal`/`overlay-stack`
+  (all in `blocks`); a separate package would only create peer-dependency friction (same reason
+  `CommandPalette` stayed in `blocks`).
+
+### Boundary: engine/UI in the library, content in the consumer app
+
+The library ships **engine + presentation**. The guide *definition* (which steps, which texts,
+which selectors, which articles) belongs in the **consumer app**. This keeps consumer i18n
+content out of the library and prevents over-engineering. `GuideTour` / `GuideStep` /
+`GuideArticle` content is authored by the consumer.
+
+### Reused building blocks (zero-dependency contract)
+
+`packages/blocks` has no runtime dependencies, so an external tour library (driver.js, Shepherd)
+is out — and unnecessary, because the expensive parts already exist:
+
+| Guide needs… | Existing building block |
+|---|---|
+| Anchor a bubble/hint to a target (flip/shift/arrow) | `utils/floating.ts` (`computePosition` + `autoUpdate`) |
+| Coexist with / pause around foreign overlays | `utils/overlay-stack.svelte.ts` (`depth`, `isTop`, `register`) |
+| Position the panel as a sidebar | `Sidebar` mechanics + `Drawer` styling (D1) |
+| Localize next/prev/skip/done | `@urbicon-ui/i18n` (runes-based, keys under `guide.*`) |
+| Engine state (class + `$state` + `untrack`) | model: `overlay-stack.svelte.ts` |
+
+**Genuinely new:** only the **engine/registry** (state machine + topic resolution + persistence)
+and the **spotlight mask** for the tour. Everything else is composition.
+
+---
+
+## 3. The `data-guide` namespace
+
+Two ways to mark an element as a guide target, both feeding the **same** registry — so a tour
+step, a hint, a marker, and a mention can all point at one id:
+
+1. **`data-guide="topic-id"`** — declarative, framework-agnostic, robust, placeable even on
+   elements the consumer doesn't render itself. Resolved via `querySelector` fallback.
+2. **`{@attach controller.target('topic-id', { label, article, direction })}`** — programmatic,
+   carries metadata, reactive binding, auto-cleanup (`{@attach}`, **not** `use:`).
+
+A single `highlight(topicId)` in the engine serves **both** tour steps **and** the Mention→UI
+hover — one mechanism, multiple surfaces.
+
+**Two layers (D3).** The `data-guide` anchors are the **anchor layer** (*where* an element is —
+necessarily declarative & distributed). On top sits an optional, typed **structure layer**: a
+`defineGuide([...])` manifest describing *which* tours/articles exist in *what* order, referencing
+`data-guide` ids as a string union. The manifest does **not** resolve targets itself — that
+separation is what makes the DEV-mode warning valuable (manifest names id X, engine can't find X
+in the DOM → warning). Repo precedent: `TypedColumnBuilder` (table columns), `createPackageI18n`
+(i18n).
+
+**Resilience.** In DEV, any tour step / mention / highlight pointing at an id that can't be
+resolved logs a warning instead of failing silently. A lazily-rendered target is observed and
+re-anchored once it appears; a vanished one falls back gracefully (§6).
+
+---
+
+## 4. Bidirectional link (the differentiator)
+
+Both directions share the `data-guide` namespace and the same `highlight()` primitive.
+Per topic/surface configurable: `direction?: 'to-guide' | 'to-ui' | 'both'` (default `both`) —
+so uni- or bidirectional is a deliberate option, resolved by `resolveDirection(id, override?)`
+(a surface-level override wins over the topic's registered direction).
+
+**Direction A — UI → Guide** (`GuideMarker`): a discreet "ⓘ" trigger on a UI element. Activation
+(click/Enter/Space) opens the `GuidePanel` at the matching article. A real `<button>` with
+`aria-controls` (the panel's published id) + `aria-expanded`. Inert when the direction is
+`'to-ui'`. → *"I see this element and want to know what it does."*
+
+**Direction B — Guide → UI** (`GuideMention`): an inline reference inside a `GuideArticle`. Hover
+**or focus** (keyboard parity) highlights the real element (`[data-guide="…"]`) with a light
+ring/glow + optional scroll-into-view; clicking scrolls it into view. Degrades to plain text when
+the direction is `'to-guide'`. → *"I'm reading the article and want to see where the element is."*
+
+**Article → article** (`GuideRef`): an inline link inside a `GuideArticle` body that navigates the
+panel to another article (`setArticle`) — the help-internal analogue of `GuideMention`. It is *not*
+a `data-guide`/highlight link: it resolves against the panel's article registry (`hasArticle`), so
+it degrades to plain text for an unknown article id (or without a provider/panel). → *"I'm reading
+this article and want to jump to a related one."*
+
+**Highlight principle (D5):** **Tour = subtractive** (full scrim, the surroundings disappear)
+· **Highlight = additive** (an `outline` ring + soft glow, the target is emphasized, nothing is
+dimmed). Direction B uses only the additive ring via `outline` (not `border` → no layout shift at
+the target), `prefers-reduced-motion`-aware. The full scrim is reserved for the spotlight tour.
+
+---
+
+## 5. Component inventory
+
+| Name | `@tag`s | Role |
+|---|---|---|
+| `GuideProvider` | overlay, feedback | Context root; instantiates `GuideController`, injects the StorageAdapter (analogous to `BlocksProvider`) |
+| `GuidePanel` | overlay, navigation | Callable, **non-modal** sidebar help panel |
+| `GuideArticle` | display | Structured article in the panel (contains `GuideMention`s); optional `group` buckets it under a section header in the index |
+| `GuideMention` | navigation | Inline article→UI reference (direction B) |
+| `GuideRef` | navigation | Inline article→article link inside an article body (panel-internal navigation) |
+| `GuideMarker` | action, feedback | "ⓘ" UI→panel trigger (direction A) — *not* a status `Badge` |
+| `GuideHint` | overlay, feedback | Contextual, non-blocking hint at an element |
+| `Guide` | overlay, feedback | Tour renderer: bubble (`floating.ts`) + spotlight mask |
+| `GuideBeacon` | feedback, action | Waiting hotspot — unobtrusive tour entry point |
+
+Plus `controller.target(id, meta?)` — the attachment that registers/binds an element
+programmatically.
+
+Every `*Props` interface carries the mandatory JSDoc (`@description`, `@tag`, `@related`,
+`@stability beta`) — the single source for the MCP server, `llms.txt`, and the docs site.
+The eight surfaces additionally carry `@standalone`, which gives each its own MCP-catalog
+entry and `llm.txt` (`find_components("guide")` lists all nine; `get_component("guide-panel")`
+etc. work) despite the family sharing one `index.ts` and one docs page — unlike compound
+subcomponents (TabItem, MenuItem), which stay folded into their directory component's entry.
+
+**Family classification (D6):** Guide is a standalone **component family** (like `CommandPalette`,
+`DatePicker`) — deliberately **not** a row in the six-family primitives taxonomy (the monorepo's
+COMPONENT-FAMILIES.md, which assigns border-token source + tier behaviour per family). The
+surfaces carry `@tag`s; the architecture lives here.
+
+---
+
+## 6. Tokens, z-index & top-layer discipline
+
+`Dialog` uses a native `<dialog>` → a real top layer. A portaled tour bubble with an ordinary
+z-index would vanish *behind* an open dialog. Therefore:
+
+- Active tours/spotlight register in the `overlayStack`.
+- The engine **pauses/dims** (`paused` getter) when `overlayStack.depth` grows from a *foreign*
+  overlay; non-modal surfaces (`GuideHint`) hide while `overlayDepth > 0`.
+- z-index is token-only. **`--z-guide: 1550`** (D4), between `--z-popover` (1500) and
+  `--z-skiplink` (1600), drives the spotlight tour. `GuidePanel` inherits `--z-sidebar` (1350),
+  `GuideHint` `--z-popover` (1500). The stacking guarantee versus a native `<dialog>` (browser
+  top layer) comes from the `overlayStack.depth` pause, **not** from z-index.
+
+Tunable tokens (defined in `blocks/src/lib/style/interaction.css`, the `[data-guide-highlight]`
+rule in `index.css`):
+
+- `--blocks-guide-scrim` (default `oklch(0 0 0 / 0.5)`) — the tour's dimming backdrop.
+- `--blocks-guide-highlight-ring` (default `--color-primary`) — the additive Mention→UI ring.
+
+---
+
+## 7. Key decisions (D1–D6)
+
+- **D1 — Panel placement: a standalone, *non-modal* `GuidePanel`.** It takes the `Sidebar`
+  mechanics (coexists with the app) and only the `Drawer` styling/`slotClasses` pattern. `Drawer`
+  is modal (`<dialog>.showModal()`, backdrop, focus trap) — that would break direction B (§4),
+  which must hover a mention *and simultaneously* highlight the element behind the panel.
+- **D2 — Marker naming: `GuideMarker`.** The interactive "ⓘ" is **not** a "Badge" (collision with
+  the non-interactive status `Badge` primitive). It may still *look* like "ⓘ".
+- **D3 — Topic definition: declarative anchors + a typed manifest (both, layered).** Anchors stay
+  declarative & distributed; structure (tours/articles/order) comes from an optional typed
+  `defineGuide([...])` manifest referencing `data-guide` ids (§3).
+- **D4 — z-index: token `--z-guide: 1550`** for the spotlight bubble; stacking vs. native
+  `<dialog>` comes from the `overlayStack.depth` pause, not z-index (§6).
+- **D5 — Direction-B highlight: additive `outline` ring, no scrim.** Tour = subtractive, highlight
+  = additive; `outline` (not `border`) → no layout shift; reduced-motion-aware (§4).
+- **D6 — Family: standalone component family, not a row in the primitives table** (§5).
+
+---
+
+## 8. As-built contract (deviations now part of the API)
+
+The build deviated from the original plan in ways that are now the intended contract:
+
+- **`createOptionalContext`** (not `createContext`): surfaces render inert without a provider.
+- **Controller-driven panel visibility** (`panelOpen`), not `bind:open` — single source of truth.
+  The panel uses `inert` (not `aria-hidden`) when closed, and focus-sensitive Escape (non-modal
+  courtesy). Closing from *within* returns focus to the opener (`aria-labelledby` on the header).
+- **Native Popover API top-layer** (not `Portal`) for `GuideHint` and `Guide` — mirrors
+  `Tooltip`/`Popover`. The tour is one `popover="manual"` shell (`pointer-events:none`) with an
+  SVG even-odd scrim **and** the bubble inside.
+- **`GuideMarker` opens on activation** (click/Enter/Space), not on bare focus (tab-friendly).
+  `GuideMention` has **no** `aria-describedby` (the visible text is the accessible name).
+- **Tour progress = dot row + "Step X of Y"** (not the `Stepper` primitive — too heavy for a
+  ~22rem bubble). Step announcement via an always-present polite `aria-live` region (a sibling of
+  the popover, so the first step is announced as a content *change*). Interactive steps use a
+  two-zone Tab cycle (bubble ⇄ target) so the spotlit target stays keyboard-reachable; `aria-modal`
+  is dropped on those steps.
+- **Spotlight = SVG even-odd hole** following the target via `autoUpdate`; a non-interactive step
+  lays a transparent blocker `<rect>` over the hole, an interactive step leaves it click-through.
+- **Analytics hooks** on `GuideTour`: `onStep` / `onComplete` / `onSkip` (the real business value —
+  the onboarding funnel + drop-off). Fired from the engine, defensively (a throwing callback can't
+  corrupt tour state). `stopTour()` is analytics-silent (programmatic teardown, e.g. route change).
+- **Action-gated steps** (`GuideStep.advance: 'action'`, default `'user'`): learning-by-doing —
+  the footer's Next is rendered `aria-disabled` (still focusable, with an `aria-describedby`
+  screen-reader hint, i18n `guide.actionRequired`) and ArrowRight is inert; the app advances
+  imperatively via `controller.next()` once the user performed the real action (pair with
+  `interactive: true`). The gate lives purely in the `Guide` renderer — the engine's `next()`
+  is never blocked. Back/Skip stay available; the live region announces the gate per step.
+- **Phase-8 hardening:** `observeTargetResolution` (rAF-coalesced MutationObserver) +
+  `reapplyStepHighlight()` re-anchor and re-spotlight a target that renders *after* a step begins,
+  and fall back to the centered scrim when one vanishes. The tour exit fades via a
+  `view = liveView ?? heldView` snapshot that holds the last step's content through the popover
+  transition. `GuidePanel` returns focus to its opener on close.
+- **Declarative cross-route touring** (`GuideStep.route` + `GuideControllerOptions.navigate`,
+  also forwarded by `GuideProvider.navigate`): a step can name the route it lives on, and the
+  controller navigates there (via the injected, framework-agnostic hook) **before** the spotlight,
+  re-anchoring through the same `reapplyStepHighlight` once the target appears. All the logic lives
+  in the engine — the renderer is unchanged. A tour-internal navigation (tracked via an internal
+  `expectedRoute`) keeps the tour running; a foreign one stops it analytics-silent (`stopTour`), so
+  the manual-`goto` recipe is preserved by subscribing to navigation **only** for tours that declare
+  a `route`. The current path + navigation events come from an injectable `navigationSource`
+  (default: Navigation API with a `popstate` fallback; the escape hatch for a base path / custom
+  router). `prev()` navigates back symmetrically; a missing hook or a never-appearing target DEV-warns
+  without hanging or crashing (§9).
+- **Panel index scales with the catalog:** `GuideArticle.group` buckets the index under section
+  headers (a `<ul aria-labelledby>` per section in first-occurrence order; ungrouped articles in
+  one headerless block; a flat list when no article sets a group — unchanged for existing
+  consumers). `GuidePanel.searchable` adds an opt-in case-insensitive title filter that runs
+  *before* grouping (non-empty sections keep their headers, empty ones disappear; an empty result
+  shows the i18n `guide.noResults` status). `GuideRef` (§4) is the inline article→article link,
+  resolving against the panel's article registry (`hasArticle`) so it degrades to plain text for an
+  unknown id — hydration-safe because the registry is empty during SSR and the first client render
+  alike, then reactively upgrades the `<span>` to a `<button>`.
+
+---
+
+## 9. Cross-route tours
+
+Tours survive client-side navigation by construction: the controller lives in the layout's
+`GuideProvider` and outlives route components; an unresolved step target falls back gracefully to
+the centered, full-scrim bubble; and the `MutationObserver` in `Guide.svelte` re-anchors as soon
+as the new route's `data-guide` element appears (the lazy-target hardening, §8). On top of that,
+a step can declare the route it lives on and let the library drive the navigation.
+
+### Declarative (`GuideStep.route` + `navigate` hook) — the supported pattern
+
+Give the step its `route` and wire a `navigate` hook once (UIB stays framework-agnostic, so it
+never imports your router). When a step becomes active and its `route` differs from the current
+location, the controller navigates **before** the spotlight, then re-anchors once the target
+appears on the new page:
+
+```svelte
+<script lang="ts">
+  import { goto } from '$app/navigation';
+  import { GuideProvider, Guide, GuideController, type GuideTour } from '@urbicon-ui/blocks';
+
+  // Wire the router once. (Equivalently: <GuideProvider navigate={(route) => goto(route)}>.)
+  const guide = new GuideController({ navigate: (route) => goto(route) });
+
+  const tour: GuideTour = {
+    id: 'cross-route-onboarding',
+    steps: [
+      { target: 'dash-overview', route: '/dashboard', title: 'Your dashboard', body: '…' },
+      { target: 'dash-filter', route: '/dashboard', title: 'Filter', body: '…' },
+      { target: 'billing-plan', route: '/settings/billing', title: 'Your plan', body: '…' }
+    ]
+  };
+</script>
+
+<GuideProvider controller={guide}>
+  <Guide />
+  <!-- … app … -->
+</GuideProvider>
+```
+
+How it behaves:
+
+- **Tour-internal vs. foreign navigation.** A navigation the tour itself triggers (a `step.route`)
+  keeps it running. A *foreign* navigation — the user leaving the flow on their own, or a
+  youngest-gesture-wins race during a pending step navigation — stops it via `stopTour()`
+  (analytics-silent, so it can surface again; no `onSkip`). The engine subscribes to navigation
+  only for tours that declare at least one `route`, so a tour that does its own routing (below) is
+  never second-guessed.
+- **`prev()` is symmetric.** Stepping back across a route boundary navigates back too — the target
+  step carries its own `route`.
+- **The navigation gap is covered.** Between the `navigate(...)` call and the new route's
+  `data-guide` element mounting, the step renders centered over the full scrim; once the target
+  appears, the bubble re-anchors and the spotlight ring lands (via the existing
+  `reapplyStepHighlight`). If the target never appears, the step still shows centered (it never
+  hangs) and DEV warns.
+- **Missing hook is safe.** A `route` step with no `navigate` wired DEV-warns and stays on the
+  current route — no crash.
+- **Path comparison.** `route` is compared against `window.location.pathname` by default, so use a
+  normalized path (no query/hash, preferably the router's *actual* landed path). An asynchronously
+  observed landing that is merely a normalized form of the step's route (trailing slash, base/locale
+  prefix) is recognized as the tour's own — the tour keeps running, DEV-warned so you can make the
+  route exact; an unrelated landing (e.g. an auth redirect) stops the tour as foreign. A
+  synchronous, re-entrant `navigationSource` (the `afterNavigate` one below) doesn't need the
+  heuristic — a same-tick report is recognized as the tour's own by *timing*, not by path.
+
+> **Reliable foreign-navigation detection.** The default `navigationSource` observes navigations via
+> the Navigation API, which catches link clicks, `goto`, and back/forward in Chromium and recent
+> Safari. In a browser without it the source falls back to `popstate` — back/forward only, **not**
+> `pushState` — so a foreign *forward* navigation (an in-app link click) may go unobserved and the
+> tour won't stop (it DEV-warns once when it takes the fallback). For detection that works in every
+> browser, inject a `navigationSource` backed by your router. SvelteKit (`afterNavigate` fires for
+> every client navigation):
+>
+> ```svelte
+> <script lang="ts">
+>   import { afterNavigate, goto } from '$app/navigation';
+>   import { page } from '$app/state';
+>   import { GuideController, type GuideNavigationSource } from '@urbicon-ui/blocks';
+>
+>   let notify: ((path: string) => void) | null = null;
+>   const navigationSource: GuideNavigationSource = {
+>     current: () => page.url.pathname,
+>     subscribe: (cb) => {
+>       notify = cb;
+>       return () => {
+>         notify = null;
+>       };
+>     }
+>   };
+>   afterNavigate(() => notify?.(page.url.pathname));
+>
+>   const guide = new GuideController({ navigate: goto, navigationSource });
+> </script>
+> ```
+>
+> This source fires **synchronously inside `goto`** — re-entrant, while the controller's own
+> `navigate` hook is still on the stack. The engine treats such a same-tick report as the tour's own
+> navigation (recognized by *timing*, not by path), so a plain synchronous `notify` is correct — no
+> `queueMicrotask` deferral is needed. Because the match is by timing, a router-normalized landing
+> (trailing slash, base/locale prefix) keeps the tour running; a synchronous *redirect* off the
+> step's route also keeps it running (DEV-warned, not stopped), so stop the tour explicitly from a
+> router guard if a redirect should end it.
+
+### Manual (`onStep` + `goto`) — the escape hatch
+
+For routing that the declarative `route` can't express — chosen at runtime from tour state or user
+answers — navigate imperatively in `onStep` instead. A tour with no `step.route` is never
+subscribed to navigation, so its own `goto` is not mistaken for a foreign navigation:
+
+```svelte
+<script lang="ts">
+  import { goto } from '$app/navigation';
+  import { page } from '$app/state';
+  import type { GuideTour } from '@urbicon-ui/blocks';
+
+  const stepRoutes: Record<number, string> = { 0: '/dashboard', 2: '/settings/billing' };
+
+  const tour: GuideTour = {
+    id: 'cross-route-onboarding',
+    steps: [
+      { target: 'dash-overview', title: 'Your dashboard', body: '…' },
+      { target: 'dash-filter', title: 'Filter', body: '…' },
+      { target: 'billing-plan', title: 'Your plan', body: '…' }
+    ],
+    onStep: ({ index }) => {
+      const route = stepRoutes[index];
+      if (route && route !== page.url.pathname) goto(route);
+    }
+  };
+</script>
+```
+
+Rules of thumb (both patterns):
+
+- **Mount `<Guide />` (and the provider) in the layout, not in a route.** A route-local renderer
+  unmounts on navigation, and its unmount cleanup calls `stopTour()` — the tour would silently end
+  mid-flight before it could re-anchor on the destination.
+- **`stopTour()` when navigation invalidates the tour** (logout, the user abandons the flow) — it
+  tears down without marking the tour seen and stays analytics-silent, so it can surface again. The
+  declarative pattern does this for foreign navigation automatically.
+- Steps that land right after a navigation pair well with `advance: 'action'` (§8) when the
+  navigation itself *is* the action being taught — together they yield learning-by-doing across
+  routes.
+
+---
+
+## 10. Non-goals / v2
+
+Deliberately **out** of the first cut (avoiding over-engineering):
+
+- Branching / conditional steps (branched tours by user answer)
+- Cross-route **resume state** (surviving a full page reload / deep-link into the middle of a
+  tour) — client-side cross-route touring *is* supported now, both declaratively (`GuideStep.route`
+  + the `navigate` hook) and imperatively (the `onStep` recipe), §9; persisting progress across a
+  hard reload is what stays out
+- WYSIWYG tour editor / no-code authoring
+- Built-in analytics persistence (we ship only the hooks, no backend)
+- Server-driven remote guides (content from a CMS) — an adapter is conceivable, not v1
+
+---
+
+## 11. Where things live & how it's tested
+
+| Concern | Location |
+|---|---|
+| Engine (state machine, registry, persistence, analytics) | `packages/blocks/src/lib/utils/guide.svelte.ts` |
+| Lazy/vanishing-target watcher | `packages/blocks/src/lib/utils/observe-target.ts` |
+| Surfaces | `packages/blocks/src/lib/components/Guide/*.svelte` |
+| Context + panel context | `components/Guide/guide.context.ts`, `guide-panel.context.ts` |
+| Variants | `components/Guide/guide.variants.ts` |
+| Tokens / highlight CSS | `blocks/src/lib/style/{interaction,index,foundation}.css` |
+| i18n keys (`guide.*`) | `blocks/src/lib/translations/{en,de}.ts` |
+| Doc page (live examples) | `apps/docs/src/routes/blocks/components/guide/` |
+| Recipe (Onboarding Flow + live analytics log) | `apps/docs/src/routes/recipes/onboarding-flow/` |
+| MCP pattern | `design-system/patterns/onboarding-guide.md` |
+
+**Tests.** Engine logic is node-unit-tested (`utils/guide.svelte.test.ts`,
+`utils/observe-target.test.ts`). Component behaviour + a11y (axe) + light/dark visual snapshots
+run via Playwright against `apps/docs/src/routes/test-fixtures/guide/`
+(`e2e/guide.spec.ts`); the visual baselines are CI-optional (`e2e/snapshots/guide.spec.ts-snapshots/`).
+
+**docs-gen caveat.** docs-gen extracts only local `*Props`/`*Variants`, not types imported from
+`utils`. So `GuideController` / `GuideTour` / `GuideStep` / the analytics-event payloads are **not**
+auto-expanded into the generated `api.ts` / `llms.txt`; the hand-authored API tables on the doc
+page are the source of truth for them until docs-gen does cross-file type resolution.

package/docs/MIGRATION-v5.md

@@ -0,0 +1,118 @@
+# Migration Guide: v4 → v5
+
+The v5.0.0 release ("Lighter design refactor") introduces a quieter visual
+language across the library: hairline borders, surface-tinted in-page zones,
+fewer chrome layers. Most consumer code is unaffected — the renames listed
+below are the only typed-API breakages.
+
+> Released `2026-05-21` as commit `8ac07ca` (`feat!`). All four breaking
+> blocks below were declared in the commit's `BREAKING CHANGE:` footers but
+> are surfaced here because git-cliff's default template renders only the
+> commit subject in the CHANGELOG.
+
+## 1. Card variants
+
+| Before              | After                | Notes                                         |
+| ------------------- | -------------------- | --------------------------------------------- |
+| `variant="elevated"` (default) | `variant="quiet"` (default) | New default — surface-quiet tint, no shadow   |
+| `variant="filled"`  | _removed_            | Replaced by `quiet`                           |
+| `variant="glass"`   | _removed_            | No drop-in replacement; build with `unstyled` |
+| `variant="outlined"` | _unchanged_         | —                                             |
+| `variant="elevated"` | _unchanged_         | Still available, no longer the default        |
+| —                   | `variant="floating"` | New — popover-family weight (shadow-lg)       |
+
+The `dividers` prop now defaults to **false** (was implicit `true` via
+header/footer borders). Set `dividers={true}` to restore traditional
+card-with-header look.
+
+```svelte
+<!-- v4 -->
+<Card variant="elevated">…</Card>
+<!-- v5 — keeps the elevated look explicitly -->
+<Card variant="elevated">…</Card>
+<!-- v5 — pick up the new default, no shadow -->
+<Card>…</Card>
+```
+
+## 2. Alert + Accordion variant renames
+
+| Component   | Before                | After                  |
+| ----------- | --------------------- | ---------------------- |
+| `Alert`     | `variant="outlined"`  | `variant="inline"`     |
+| `Accordion` | `variant="bordered"`  | `variant="separated"`  |
+
+`Alert.inline` is a memo-style with a left accent border (`border-l-2`),
+no surrounding box. `Accordion.separated` renders items as a stacked
+card list with `surface-quiet` tint and `space-y-2`.
+
+```svelte
+<!-- v4 -->
+<Alert variant="outlined" intent="warning">…</Alert>
+<Accordion variant="bordered">…</Accordion>
+<!-- v5 -->
+<Alert variant="inline" intent="warning">…</Alert>
+<Accordion variant="separated">…</Accordion>
+```
+
+## 3. Table chrome
+
+The Table no longer renders a frame by default. The new `appearance` prop
+controls the container chrome:
+
+| `appearance` | Effect                                                       |
+| ------------ | ------------------------------------------------------------ |
+| `flush` (default) | No frame; the table sits inline in the reading flow.    |
+| `surface`    | Quiet tinted zone — `bg-surface-quiet`.                      |
+| `framed`     | Border + `rounded-contain` + shadow — closest to v4 default. |
+
+The dead `tableVariants` export is removed (was unused in any consumer).
+
+```svelte
+<!-- v4 — implicit frame -->
+<Table data={rows} columns={cols} />
+<!-- v5 — explicit equivalent -->
+<Table data={rows} columns={cols} appearance="framed" />
+<!-- v5 — new editorial default -->
+<Table data={rows} columns={cols} />
+```
+
+## 4. Dialog + Drawer intent
+
+Dialog and Drawer no longer draw a coloured `border-t-[3px]` accent for
+non-neutral intents. Intent is exposed on the panel as a data attribute:
+
+```html
+<div data-intent="warning" …>…</div>
+```
+
+Consumers can re-introduce a coloured accent via CSS, a preset, or a
+custom snippet on `header`/`title`:
+
+```css
+[data-intent='warning'] {
+  border-top: 3px solid var(--color-warning);
+}
+```
+
+No prop renames — `intent="warning"` still works; only the default visual
+changed.
+
+## Container-component border tokens
+
+Many container surfaces (Card, Alert, Dialog, Drawer, Popover, Menu, Toast,
+Sidebar, Collapsible, FileUpload, Sankey, CompositionBar, CommandPalette,
+SidebarLayout, Calendar) migrated from `border-subtle` to
+`border-hairline` (~8 % alpha at light, 6 % at dark). Form primitives
+(Input, Select, Combobox, Textarea, Checkbox, RadioGroup) kept
+`border-subtle` as an input affordance — consumers see no API change but
+the visual difference is real. Override per-component via `class` /
+`slotClasses` if a heavier border is desired.
+
+## New tokens consumers can use directly
+
+- `bg-surface-quiet` — softly tinted in-page zone (was `bg-surface-subtle`-equivalent)
+- `border-hairline` — container divider (auto-upgrades under
+  `prefers-contrast: more`)
+
+Both are exposed as semantic Tailwind utilities and via CSS custom
+properties (`--color-surface-quiet`, `--color-border-hairline`).

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@urbicon-ui/blocks",
-  "version": "6.28.0",
+  "version": "6.29.0",
   "description": "Svelte 5 UI component library with Tailwind CSS 4, OKLCH design tokens and zero runtime dependencies",
   "license": "MIT",
   "repository": {
@@ -35,6 +35,8 @@
   },
   "files": [
     "LICENSE",
+    "docs/GUIDE.md",
+    "docs/MIGRATION-v5.md",
     "dist",
     "!dist/**/*.test.*",
     "!dist/**/*.spec.*",
@@ -92,8 +94,8 @@
     "@sveltejs/package": "^2.5.8",
     "@sveltejs/vite-plugin-svelte": "^7.0.0",
     "@tailwindcss/vite": "^4.3.1",
-    "@urbicon-ui/i18n": "6.28.0",
-    "@urbicon-ui/shared-types": "6.28.0",
+    "@urbicon-ui/i18n": "6.29.0",
+    "@urbicon-ui/shared-types": "6.29.0",
     "prettier": "^3.8.4",
     "prettier-plugin-svelte": "^4.1.1",
     "prettier-plugin-tailwindcss": "^0.8.0",