@urbicon-ui/design-content 6.1.8

package/content/blocks/components/guide/llm.txt

@@ -0,0 +1,49 @@
+
+---
+
+## Guide
+The guided-tour renderer — the deliberately opt-in, intrusive Guide surface
+(§6, low priority). Renders the active tour the controller drives (`startTour`/`next`/`prev`/
+`skip`/`finish`): a spotlight that dims everything but a cut-out hole over the current step's
+target (the one *subtractive* Guide treatment, D5) plus an anchored bubble with the step
+title, body, dot progress, and Back / Next / Skip controls. Mount once inside `GuideProvider`;
+it renders nothing until a tour starts. Top-layer (native popover), so it clears app stacking
+contexts; it steps aside (pauses) when a foreign modal stacks above it. A step with no `target`
+renders centered over a full scrim. Renders inert without a `GuideProvider`.
+
+**Import:** `import { Guide } from '@urbicon-ui/blocks';`
+
+### Examples
+```svelte
+<script>
+  import { GuideProvider, Guide, GuideController } from '@urbicon-ui/blocks';
+  const guide = new GuideController();
+  const tour = {
+    id: 'welcome',
+    steps: [
+      { target: 'save-button', title: 'Save', body: 'Persist your changes here.' },
+      { target: 'filter-control', title: 'Filter', body: 'Narrow the list.', interactive: true }
+    ]
+  };
+</script>
+
+<GuideProvider controller={guide}>
+  <Guide />
+  <button onclick={() => guide.startTour(tour)}>Take the tour</button>
+</GuideProvider>
+```
+
+### Api
+| Prop | Type | Required | Default | Description |
+| --- | --- | :---: | --- | --- |
+| arrow | `boolean` | no | true | Render the bubble's pointer arrow on anchored steps. |
+| class | `string` | no |  | Additional classes on the bubble. |
+| padding | `number` | no | 8 | Padding in px between the step target and the spotlight hole edge. Also frames the additive highlight ring the engine paints on the target. |
+| placement | `Placement` | no | 'bottom' | Preferred bubble placement when a step omits its own `placement`. |
+| preset | `string` | no |  | Apply a named preset registered via `<BlocksProvider presets={{ Guide: {...} }}>`. |
+| radius | `number` | no |  | Spotlight hole corner radius in px. When omitted, it follows the target's own border-radius (plus `padding`), clamped to the hole size. Set a number to force it. |
+| slotClasses | `Partial<Record<'container' | 'scrim' | 'bubble' | 'arrow' | 'title' | 'body' | 'progress' | 'dots' | 'dot' | 'dotActive' | 'stepText' | 'footer' | 'spacer' | 'skip' | 'prev' | 'next', string>>` | no |  | Per-slot class overrides. |
+| unstyled | `boolean` | no | false | Strip all default styles. |
+
+### Slots (slotClasses keys)
+`container`, `scrim`, `bubble`, `arrow`, `title`, `body`, `progress`, `dots`, `dot`, `dotActive`, `stepText`, `footer`, `spacer`, `skip`, `prev`, `next`

package/content/blocks/components/guide-article/llm.txt

@@ -0,0 +1,30 @@
+
+---
+
+## GuideArticle
+A single help article inside a `GuidePanel`. Registers itself in the panel's
+list (by `title`) and renders its content only when it is the active article
+(`controller.activeArticle === id`). Use `GuideMention` inside to link back to UI elements.
+
+**Import:** `import { GuideArticle } from '@urbicon-ui/blocks';`
+
+### Examples
+```svelte
+<GuideArticle id="seats" title="Seats & billing">
+  <p>Each <GuideMention for="seat-count">seat</GuideMention> is one team member.</p>
+</GuideArticle>
+```
+
+### Api
+| Prop | Type | Required | Default | Description |
+| --- | --- | :---: | --- | --- |
+| id | `string` | yes |  | Unique article id — referenced by `GuideMarker` and `openPanel(id)`. |
+| title | `string` | yes |  | Title shown in the panel list and header. |
+| children | `Snippet` | no |  | Content to render inside the GuideArticle component |
+| class | `string` | no |  | Additional classes on the article root. |
+| preset | `string` | no |  | Apply a named preset registered via `<BlocksProvider presets={{ GuideArticle: {...} }}>`. |
+| slotClasses | `Partial<Record<'article', string>>` | no |  | Per-slot class overrides. |
+| unstyled | `boolean` | no | false | Strip all default styles. |
+
+### Slots (slotClasses keys)
+`article`

package/content/blocks/components/guide-beacon/llm.txt

@@ -0,0 +1,38 @@
+
+---
+
+## GuideBeacon
+A waiting, pulsing hotspot that invites the user into an opt-in guided tour (§6.3)
+— the gentlest tour entry point, the opposite of an auto-starting tour. A real `<button>` the
+consumer positions (inline, or absolutely over a feature corner); on activation it starts the
+given `tour` and/or calls `onActivate`. Hides itself once that tour has been seen. The pulse
+halts under `prefers-reduced-motion` (static dot). Renders inert without a `GuideProvider`.
+
+**Import:** `import { GuideBeacon } from '@urbicon-ui/blocks';`
+
+### Examples
+```svelte
+<span class="relative">
+  New feature
+  <GuideBeacon class="absolute -right-3 -top-1" {tour} />
+</span>
+```
+
+### Variants
+- size: md, sm (default: md)
+
+### Api
+| Prop | Type | Required | Default | Description |
+| --- | --- | :---: | --- | --- |
+| class | `string` | no |  | Additional classes on the beacon button (use for absolute positioning over a target). |
+| label | `string` | no | i18n `guide.startTour` | Accessible label for the button. |
+| onActivate | `() => void` | no |  | Called on activation (click / Enter / Space), after `tour` is started when both are set. |
+| once | `boolean` | no | true | Hide the beacon once its `tour` has been seen (and while that tour is running). Needs `tour`. |
+| preset | `string` | no |  | Apply a named preset registered via `<BlocksProvider presets={{ GuideBeacon: {...} }}>`. |
+| size | `GuideBeaconVariants['size']` | no | 'md' | Visual size of the hotspot. |
+| slotClasses | `Partial<Record<'beacon' | 'ping' | 'dot', string>>` | no |  | Per-slot class overrides. |
+| tour | `GuideTour` | no |  | The tour to start when the beacon is activated. When set, the beacon also hides itself once the tour has been seen (subject to `once`). Omit to drive everything from `onActivate`. |
+| unstyled | `boolean` | no | false | Strip all default styles. |
+
+### Slots (slotClasses keys)
+`beacon`, `ping`, `dot`

package/content/blocks/components/guide-hint/llm.txt

@@ -0,0 +1,41 @@
+
+---
+
+## GuideHint
+A contextual, non-blocking hint anchored to a `data-guide` element via
+`floating.ts` (flip/shift/arrow), rendered in the native popover top-layer. Waits at the
+right element rather than interrupting: shows on mount (or when `open` for `trigger="manual"`),
+persists "seen" so it appears once (`once`), and steps aside while a foreign modal or guided
+tour is open. Dismissable; announces itself via `aria-live`. Renders inert without a provider.
+
+**Import:** `import { GuideHint } from '@urbicon-ui/blocks';`
+
+### Examples
+```svelte
+<button data-guide="export">Export</button>
+
+<GuideHint for="export" title="New: scheduled exports">
+  You can now export on a schedule from here.
+</GuideHint>
+```
+
+### Api
+| Prop | Type | Required | Default | Description |
+| --- | --- | :---: | --- | --- |
+| for | `string` | yes |  | `data-guide` id of the element to anchor to. Required — a hint with no anchor has nothing to point at. |
+| arrow | `boolean` | no | true | Render the pointer arrow. |
+| children | `Snippet` | no |  | Content to render inside the GuideHint component |
+| class | `string` | no |  | Additional classes on the hint root. |
+| once | `boolean` | no | true | When dismissed, persist a "seen" flag (via the controller's StorageAdapter) so the hint does not reappear on later mounts. Mirrors the tour's "mark seen on end" rule — a hint shown but never dismissed may show again. Set `false` to always show. |
+| onDismiss | `() => void` | no |  | Called when the hint is dismissed (close button or Escape). |
+| open | `boolean` | no | false | Manual visibility for `trigger="manual"` (the on-route / on-condition strategy). Ignored for `trigger="mount"`. Re-raising it to `true` after a dismiss re-surfaces the hint (subject to `once`). |
+| placement | `Placement` | no | 'bottom' | Preferred placement relative to the target. |
+| preset | `string` | no |  | Apply a named preset registered via `<BlocksProvider presets={{ GuideHint: {...} }}>`. |
+| seenId | `string` | no | the `for` id | Persistence key for the "seen once" state, decoupled from the anchor (this is *not* a DOM id — the popover gets none). Override only to track two hints on one element independently, or to keep a stable key across a renamed anchor. |
+| slotClasses | `Partial<Record<'hint' | 'title' | 'body' | 'dismiss' | 'arrow', string>>` | no |  | Per-slot class overrides. |
+| title | `string` | no |  | Optional bold heading above the body. |
+| trigger | `'mount' | 'manual'` | no | 'mount' | When the hint may appear: `'mount'` shows it as soon as it mounts; `'manual'` waits for `open` to become `true` (the consumer's route/condition logic). |
+| unstyled | `boolean` | no | false | Strip all default styles. |
+
+### Slots (slotClasses keys)
+`hint`, `title`, `body`, `dismiss`, `arrow`

package/content/blocks/components/guide-marker/llm.txt

@@ -0,0 +1,36 @@
+
+---
+
+## GuideMarker
+Direction A of the bidirectional link (UI → Guide): a discreet "ⓘ" trigger
+that sits on a UI element and opens the `GuidePanel` at the matching article. A real
+`<button>` with `aria-controls`/`aria-expanded` — deliberately *not* a status `Badge`
+(which is a non-interactive label, not a trigger). Renders inert without a `GuideProvider`,
+or when the topic's direction excludes UI→Guide (`'to-ui'`).
+
+**Import:** `import { GuideMarker } from '@urbicon-ui/blocks';`
+
+### Examples
+```svelte
+<h3>Billing <GuideMarker for="billing" article="billing-help" /></h3>
+```
+
+### Variants
+- size: md, sm (default: md)
+
+### Api
+| Prop | Type | Required | Default | Description |
+| --- | --- | :---: | --- | --- |
+| article | `string` | no |  | Article to open in the panel. Overrides the topic meta's `article`; falls back to `for`. |
+| children | `Snippet` | no |  | Custom trigger content, replacing the default "ⓘ" icon. |
+| class | `string` | no |  | Additional classes on the marker button. |
+| direction | `GuideDirection` | no | the topic's `direction`, or `'both'` | Override the topic's link direction. The marker is live unless this resolves to `'to-ui'`. |
+| for | `string` | no |  | `data-guide` topic id this marker explains. Resolves the article (from topic meta) and the link direction. Optional (unlike `GuideMention.for`) because `article` can stand alone — supply one of the two. With neither, the marker opens the panel index. |
+| label | `string` | no | i18n `guide.infoAbout` (with the topic's label) or `guide.info` | Accessible label for the icon button. |
+| preset | `string` | no |  | Apply a named preset registered via `<BlocksProvider presets={{ GuideMarker: {...} }}>`. |
+| size | `GuideMarkerVariants['size']` | no | 'md' | Size variant that controls dimensions and spacing of the GuideMarker |
+| slotClasses | `Partial<Record<'marker' | 'icon', string>>` | no |  | Per-slot class overrides. |
+| unstyled | `boolean` | no | false | Strip all default styles. |
+
+### Slots (slotClasses keys)
+`marker`, `icon`

package/content/blocks/components/guide-mention/llm.txt

@@ -0,0 +1,31 @@
+
+---
+
+## GuideMention
+Direction B of the bidirectional link (Guide → UI): an inline reference inside a
+`GuideArticle` that highlights the matching UI element on hover *and* focus (keyboard parity).
+Additive `outline` ring, no scrim, no layout shift (D5); clicking also scrolls the element into
+view (reduced-motion-aware). A real `<button>`; degrades to plain inline text without a
+`GuideProvider` or when the topic's direction excludes Guide→UI (`'to-guide'`).
+
+**Import:** `import { GuideMention } from '@urbicon-ui/blocks';`
+
+### Examples
+```svelte
+<p>Click the <GuideMention for="save-button">Save button</GuideMention> to persist.</p>
+```
+
+### Api
+| Prop | Type | Required | Default | Description |
+| --- | --- | :---: | --- | --- |
+| for | `string` | yes |  | `data-guide` id of the UI element to highlight. Required (unlike `GuideMarker.for`): a mention with no target has nothing to highlight. |
+| children | `Snippet` | no |  | Content to render inside the GuideMention component |
+| class | `string` | no |  | Additional classes on the mention. |
+| direction | `GuideDirection` | no | the topic's `direction`, or `'both'` | Override the topic's link direction. The mention is interactive unless this resolves to `'to-guide'`. |
+| preset | `string` | no |  | Apply a named preset registered via `<BlocksProvider presets={{ GuideMention: {...} }}>`. |
+| scroll | `boolean` | no | true | Scroll the target into view on click (reduced-motion-aware). |
+| slotClasses | `Partial<Record<'mention', string>>` | no |  | Per-slot class overrides. |
+| unstyled | `boolean` | no | false | Strip all default styles. |
+
+### Slots (slotClasses keys)
+`mention`

package/content/blocks/components/guide-panel/llm.txt

@@ -0,0 +1,42 @@
+
+---
+
+## GuidePanel
+Non-modal help panel for the Guide system. Slides in (default from the right)
+without a backdrop or focus trap, so the app stays interactive behind it — this is what lets
+a `GuideMention` highlight a UI element while the panel is open (D1). Visibility is driven by
+the controller (`openPanel`/`closePanel`), not a local prop. Place `GuideArticle` children
+inside: the panel shows a list of them, or the active article's content with a back button.
+
+**Import:** `import { GuidePanel } from '@urbicon-ui/blocks';`
+
+### Examples
+```svelte
+<GuidePanel title="Help">
+  <GuideArticle id="saving" title="Saving your work">
+    <p>Use the Save button to persist your changes.</p>
+  </GuideArticle>
+</GuidePanel>
+```
+
+### Variants
+- size: lg, md, sm (default: md)
+- placement: left, right (default: right)
+
+### Api
+| Prop | Type | Required | Default | Description |
+| --- | --- | :---: | --- | --- |
+| children | `Snippet` | no |  | `GuideArticle` children and any custom content. |
+| class | `string` | no |  | Additional classes on the panel root. |
+| closeOnEscape | `boolean` | no | true | Close the panel when Escape is pressed. |
+| footer | `Snippet` | no |  | Optional footer content. |
+| id | `string` | no | auto-generated (`guide-panel-<id>`) | Stable DOM id for the panel root. `GuideMarker`s reference it via `aria-controls`. |
+| placement | `GuidePanelVariants['placement']` | no | 'right' | Side the panel docks to. |
+| preset | `string` | no |  | Apply a named preset registered via `<BlocksProvider presets={{ GuidePanel: {...} }}>`. |
+| size | `GuidePanelVariants['size']` | no | 'md' | Size variant that controls dimensions and spacing of the GuidePanel |
+| slotClasses | `Partial<Record<'panel' | 'header' | 'backButton' | 'title' | 'closeButton' | 'body' | 'list' | 'listItem' | 'footer', string>>` | no |  | Per-slot class overrides. |
+| title | `string` | no | i18n `guide.openHelp` | Heading shown when no article is open. |
+| unstyled | `boolean` | no | false | Strip all default styles. |
+
+### Slots (slotClasses keys)
+`panel`, `header`, `backButton`, `title`, `closeButton`, `body`, `list`, `listItem`, `footer`

package/content/blocks/components/guide-provider/llm.txt

@@ -0,0 +1,31 @@
+
+---
+
+## GuideProvider
+Root provider for the Guide help system. Instantiates a `GuideController`
+and shares it via context with all Guide surfaces (Panel, Marker, Mention, Hint, Tour).
+Place once near the app root. The context is optional — a surface used without a provider
+renders inert rather than throwing.
+
+**Import:** `import { GuideProvider } from '@urbicon-ui/blocks';`
+
+### Examples
+```svelte
+<script>
+  import { GuideProvider, GuideController } from '@urbicon-ui/blocks';
+  const guide = new GuideController();
+</script>
+
+<GuideProvider controller={guide}>
+  <App />
+</GuideProvider>
+
+<button onclick={() => guide.startTour(welcomeTour)}>Take the tour</button>
+```
+
+### Api
+| Prop | Type | Required | Default | Description |
+| --- | --- | :---: | --- | --- |
+| children | `Snippet` | yes |  | App subtree wired to the Guide context. |
+| controller | `GuideController` | no |  | Supply a pre-created `GuideController` for programmatic access from outside the provider (start tours, open the panel, query `hasSeen`). When omitted, the provider creates one internally and shares it via context. When supplied, `storage` is ignored. |
+| storage | `GuideStorageAdapter` | no | localStorage-backed adapter | Persistence adapter for "seen" state (tours/hints). |

package/content/blocks/components/line-chart/llm.txt

@@ -0,0 +1,45 @@
+
+---
+
+## LineChart
+Line chart for trends over an ordered category axis. One path
+per series on the design-token palette; zero-dependency SVG, responsive,
+dark-mode aware, with optional points, gridlines, legend, and a screen-
+reader data-table fallback.
+
+**Import:** `import { LineChart } from '@urbicon-ui/blocks';`
+
+### Examples
+```svelte
+<LineChart
+  data={[
+    { label: 'Mon', values: [12] },
+    { label: 'Tue', values: [18] },
+    { label: 'Wed', values: [9] }
+  ]}
+/>
+```
+
+### Api
+| Prop | Type | Required | Default | Description |
+| --- | --- | :---: | --- | --- |
+| data | `CartesianDatum[]` | yes |  | Ordered categories with per-series values. |
+| ...HTMLAttributes<HTMLElement> | `HTMLAttributes` | no |  | HTML attributes (excluding: 'children') |
+| ariaLabel | `string` | no |  | Accessible label; a summary is generated when omitted. |
+| class | `string` | no |  | Extra classes merged onto the wrapper. |
+| formatValue | `(value: number) => string` | no |  | Format values for axis labels, tooltips, and the data table. |
+| height | `number` | no | 240 | Height property for the LineChart component |
+| includeZero | `boolean` | no | false | Start the value axis at zero instead of framing the data range. |
+| locale | `string` | no |  | BCP-47 locale for the default number formatter. |
+| margin | `ChartMargin` | no |  | Plot margins; merged over the defaults. |
+| preset | `string` | no |  | Apply a named preset registered on `<BlocksProvider>`. |
+| series | `ChartSeries[]` | no |  | Series metadata (labels + colors); defaults to one per value column. |
+| showGrid | `boolean` | no | true | Render horizontal gridlines. |
+| showLegend | `boolean` | no | true | Show the series legend (only renders with >1 series). |
+| showPoints | `boolean` | no | true | Render a dot at each data point. |
+| slotClasses | `ChartSlotClasses` | no |  | Per-slot class overrides. |
+| unstyled | `boolean` | no |  | Remove all default tv classes. |
+| width | `number` | no |  | Fixed width in px; omit for responsive width. |
+
+Inherited from:
+- Omit<HTMLAttributes<HTMLElement>, 'children'> (omit-pattern)

package/content/blocks/components/locale-switcher/llm.txt

@@ -0,0 +1,44 @@
+
+---
+
+## LocaleSwitcher
+Convenience wrapper around Select to switch UI locales.
+Single-select only — locale is always exactly one value. Options, value,
+form integration, multi-select, and null-option are all owned internally
+and intentionally not forwarded to the underlying Select.
+
+**Import:** `import { LocaleSwitcher } from '@urbicon-ui/blocks';`
+
+### Examples
+```svelte
+<LocaleSwitcher />
+```
+
+```svelte
+<LocaleSwitcher showFlag variant="filled" size="sm" />
+```
+
+### Api
+| Prop | Type | Required | Default | Description |
+| --- | --- | :---: | --- | --- |
+| locales | `Locale[]` | no |  | Restrict the displayed locales. Defaults to all locales registered in i18n. |
+| onLocaleChange | `(locale: Locale) => void` | no |  | Called after the locale has been changed successfully. |
+| showFlag | `boolean` | no | true | Show flag emoji alongside locale name. |
+
+Inherited from:
+- Omit<
+    SelectSingleProps<string>,
+    // Owned by LocaleSwitcher's internal options/value pipeline:
+    | 'options'
+    | 'groups'
+    | 'value'
+    | 'onValueChange'
+    | 'multiple'
+    | 'multiPlaceholder'
+    | 'nullOption'
+    | 'closeOnSelect'
+    | 'name'
+    | 'label'
+    | 'helper'
+    | 'error'
+  > (omit-pattern)

package/content/blocks/components/planner/llm.txt

@@ -0,0 +1,68 @@
+
+---
+
+## Planner
+Date-indexed planning board — a week, month or custom-range grid
+whose cells hold YOUR domain content (meals, shifts, bookings, content slots)
+via a generic `cell` snippet. Buckets `items` by calendar day, then handles
+navigation, ISO week numbers, keyboard a11y and a responsive column→stack
+layout. For timed appointments, multi-day spans or recurrence use `Calendar`
+instead.
+
+**Import:** `import { Planner } from '@urbicon-ui/blocks';`
+
+### Examples
+```svelte
+<Planner view="week" items={entries} getDate={(e) => e.date}
+sort={(a, b) => MEAL_ORDER[a.mealType] - MEAL_ORDER[b.mealType]}
+bind:value={referenceDate} onNavigate={(_, range) => loadWeek(range.start)}>
+{#snippet cell({ items, isoDate })}
+{#each items as entry (entry.id)}
+<MealCard {entry} />
+{/each}
+<Button variant="ghost" size="sm" onclick={() => openAdd(isoDate)}>Add meal</Button>
+{/snippet}
+</Planner>
+```
+
+### Variants
+- variant: bordered, default, ghost (default: default)
+- size: lg, md, sm (default: md)
+
+### Api
+| Prop | Type | Required | Default | Description |
+| --- | --- | :---: | --- | --- |
+| getDate | `(item: T) => Date | string` | yes |  | Map an item to its calendar day. Return a `Date`, or a local date string (`'2026-06-16'`) taken verbatim — never UTC-parsed, so a plain date never shifts across timezones. A date-*time* string is bucketed by its written date part too; if your value is a UTC instant whose local day matters (`'…T23:00:00Z'`), return `new Date(value)` so the local timezone applies. Required. |
+| ...HTMLAttributes<HTMLDivElement> | `HTMLAttributes` | no |  | HTML attributes (excluding: 'children') |
+| ...PlannerVariants | `VariantProps` | no |  | Styling variants from PlannerVariants |
+| animated | `boolean` | no | true | Slide-transition the grid on navigate (respects reduced-motion). |
+| cell | `Snippet<[PlannerCellContext<T>]>` | no |  | Render a day's content — the core of the API. Receives bucketed `items: T[]`. Called for **every** day, including empty ones (`items: []`) — unless an `empty` snippet is given, which then handles empty days instead. Put an "add" affordance here to keep it available on empty days. |
+| class | `string` | no |  | Extra classes merged onto the root element. |
+| dayHeader | `Snippet<[PlannerDayContext]>` | no |  | Customise each weekday/column header. |
+| disabled | `boolean` | no | false | Disable navigation and selection. |
+| empty | `Snippet<[PlannerCellContext<T>]>` | no |  | Placeholder rendered **instead of** `cell` for days with no items. Omit it to let `cell` render empty days too. |
+| header | `Snippet<[PlannerHeaderContext]>` | no |  | Replace the default toolbar (prev/next/today/title/week). |
+| highlightToday | `boolean` | no | true | Visually mark today's cell. |
+| highlightWeekend | `boolean` | no | false | Tint Saturday/Sunday cells. |
+| items | `T[]` | no |  | The items to lay out. Each is bucketed onto a day via . |
+| locale | `string` | no | 'de-DE' | BCP 47 locale for the title and weekday names. |
+| onDateSelect | `(date: Date) => void` | no |  | Fires when a day cell is activated (click / Enter / Space). |
+| onNavigate | `(date: Date, range: PlannerRange) => void` | no |  | Fires after navigation. Receives the new reference date and visible range — load data here. |
+| preset | `string` | no |  | Apply a named preset registered via `<BlocksProvider presets={{ Planner: {...} }}>`. |
+| rangeEnd | `Date` | no |  | End of the window for `view="range"`. |
+| rangeStart | `Date` | no |  | Start of the window for `view="range"`. |
+| selectedDate | `Date` | no |  | The active highlighted day. Supports `bind:selectedDate`. |
+| showWeekNumber | `boolean` | no | false | Show the ISO week-number column on the left. |
+| size | `'sm' | 'md' | 'lg'` | no | 'md' | Density of the grid and header. |
+| slotClasses | `Partial<Record<PlannerSlotName, string>>` | no |  | Per-slot class overrides merged with tv() styles. |
+| sort | `(a: T, b: T) => number` | no |  | Comparator for items within a day cell (e.g. by meal type or start label). |
+| swipeable | `boolean` | no | true | Enable horizontal swipe-to-navigate on touch. |
+| unstyled | `boolean` | no | false | Remove all default tv() classes — only user-provided classes apply. |
+| value | `Date` | no | today | Reference date the view is anchored on. Supports `bind:value`. |
+| variant | `'default' | 'bordered' | 'ghost'` | no | 'default' | Visual style variant for the Planner component |
+| view | `PlannerView` | no | 'week' | View property for the Planner component |
+| weekStartsOn | `0 | 1 | 2 | 3 | 4 | 5 | 6` | no | 1 | First day of the week (0=Sun … 6=Sat). |
+
+Inherited from:
+- Omit<PlannerVariants, 'view'> (omit-pattern)
+- Omit<HTMLAttributes<HTMLDivElement>, 'children'> (omit-pattern)

package/content/blocks/components/sankey/llm.txt

@@ -0,0 +1,72 @@
+
+---
+
+## Sankey
+Flow diagram (Sankey) for visualizing multi-stage data or value
+pipelines. Nodes are split into layers; paths are rendered as cubic Bezier
+curves with value-proportional width. The layout algorithm is embedded (no
+d3-sankey dependency, ISC license attributed).
+
+Hovering/focusing a node or path highlights the connected paths and
+neighboring nodes. A ResizeObserver adapts the width responsively. An
+sr-only table provides a screen-reader fallback with source/target/value.
+
+**Import:** `import { Sankey } from '@urbicon-ui/blocks';`
+
+### Examples
+```svelte
+<Sankey
+  nodes={[
+    { id: 'gas',  label: 'Gas',     intent: 'primary' },
+    { id: 'pot',  label: 'Pool',    intent: 'neutral' },
+    { id: 'heat', label: 'Heating', intent: 'success' }
+  ]}
+  links={[
+    { source: 'gas', target: 'pot',  value: 220609 },
+    { source: 'pot', target: 'heat', value: 220609 }
+  ]}
+  formatValue={(v) => formatCurrency(v)}
+  height={400}
+/>
+```
+
+### Variants
+- intent: danger, neutral, primary, secondary, success, warning (default: neutral)
+
+### Api
+| Prop | Type | Required | Default | Description |
+| --- | --- | :---: | --- | --- |
+| links | `SankeyLink[]` | yes |  | Links property for the Sankey component |
+| nodes | `SankeyNode[]` | yes |  | Nodes property for the Sankey component |
+| ...HTMLAttributes<HTMLDivElement> | `HTMLAttributes` | no |  | HTML attributes (excluding: 'children') |
+| ...SankeyVariants | `VariantProps` | no |  | Styling variants from SankeyVariants |
+| class | `string` | no |  | Extra classes merged onto the wrapper. |
+| defaultOpacity | `number` | no | 0.45 | Default stroke opacity of paths without hover. |
+| dimmedOpacity | `number` | no | 0.25 | Hover opacity of the non-focused paths. |
+| formatPercent | `(percent: number) => string` | no |  | Format function for percentages (tooltip). |
+| formatValue | `(value: number) => string` | no |  | Format function for values (tooltip + sr-only table). |
+| height | `number | 'auto'` | no | 400 | Height of the diagram. Accepts a fixed pixel number or `'auto'`.  `'auto'` scales with the node count: roughly `nodes.length × (12 + nodePadding)`, clamped to `[280, 800]`. Useful when the number of nodes varies at runtime and a fixed pixel value would be too small or too large. |
+| highlightedOpacity | `number` | no | 0.7 | Stroke opacity of the highlighted paths. |
+| highlightOnHover | `boolean` | no | true | Hover highlight (paths + connected nodes). |
+| intent | `SankeyIntent` | no | 'neutral' | Default intent for nodes without their own `intent`. |
+| iterations | `number` | no | 6 | Number of relaxation iterations in the layout. |
+| linkContent | `Snippet<[link: SankeyLaidOutLinkWithMeta]>` | no |  | Custom snippet for path rendering (instead of the default cubic Bezier). |
+| nodeAlign | `'left' | 'right' | 'center' | 'justify'` | no | 'justify' | NodeAlign property for the Sankey component |
+| nodeContent | `Snippet<[node: SankeyLaidOutNodeWithMeta]>` | no |  | Custom snippet for node content (inside the SVG, instead of the label). |
+| nodePadding | `number` | no | 16 | Vertical gap between nodes within a layer. |
+| nodeWidth | `number` | no | 24 | Pixel width of a node. |
+| onLinkClick | `(link: SankeyLaidOutLinkWithMeta) => void` | no |  | Click callback for a path. |
+| onNodeClick | `(node: SankeyLaidOutNodeWithMeta) => void` | no |  | Click callback for a node. |
+| preset | `string` | no |  | Preset property for the Sankey component |
+| showValues | `boolean` | no | false | Persistently display values next to node labels (instead of only in the hover tooltip). Useful for print, PDF attachments, static screenshots, or tenant- and client-facing statements where hovering is not possible. Uses `formatValue` for formatting. |
+| slotClasses | `Partial<Record<'wrapper' | 'svg' | 'node' | 'nodeRect' | 'nodeLabel' | 'nodeValue' | 'link' | 'tooltip' | 'tooltipLabel' | 'tooltipDetail', string>>` | no |  | Per-slot class overrides. |
+| tooltip | `Snippet<[datum: SankeyLaidOutNodeWithMeta | SankeyLaidOutLinkWithMeta, kind: 'node' | 'link']>` | no |  | Custom tooltip content for node or path. |
+| unstyled | `boolean` | no |  | Remove default classes. |
+| width | `number` | no |  | Optional fixed width. Default: derived from the container via ResizeObserver. Set a value only if you need SSR-stable layouts and are willing to give up responsiveness. |
+
+Inherited from:
+- Omit<SankeyVariants, never> (omit-pattern)
+- Omit<HTMLAttributes<HTMLDivElement>, 'children'> (omit-pattern)
+
+### Slots (slotClasses keys)
+`wrapper`, `svg`, `node`, `nodeRect`, `nodeLabel`, `nodeValue`, `link`, `tooltip`, `tooltipLabel`, `tooltipDetail`

package/content/blocks/components/sidebar-layout/llm.txt

@@ -0,0 +1,87 @@
+
+---
+
+## SidebarLayout
+App-shell layout that wires a `<Sidebar>` to a main content
+region and an optional mobile header. Use this whenever you want a
+permanent sidebar on desktop with a hamburger overlay on mobile — it
+resolves the CSS-variable scoping so the main content offset works without
+boilerplate.
+
+The component renders the sidebar internally; consumers configure it via
+`sidebarHeader`, `sidebar`, and `sidebarFooter` snippets and bind `open`
+for the mobile overlay (or for collapsible mode at all viewports).
+
+For non-shell sidebars (right-side detail panels, drawers inside a page),
+keep using the `<Sidebar>` primitive directly.
+
+**Import:** `import { SidebarLayout } from '@urbicon-ui/blocks';`
+
+### Examples
+```svelte
+<script>
+import { SidebarLayout, Button, MenuIcon } from '@urbicon-ui/blocks';
+let sidebarOpen = $state(false);
+</script>
+
+<SidebarLayout bind:open={sidebarOpen} sidebarWidth="16rem">
+{#snippet sidebarHeader()}
+<a href="/" class="font-semibold">My App</a>
+{/snippet}
+
+{#snippet sidebar()}
+<nav class="flex flex-col gap-1 p-3">
+<a href="/dashboard">Dashboard</a>
+<a href="/settings">Settings</a>
+</nav>
+{/snippet}
+
+{#snippet mobileHeader({ openSidebar })}
+<Button variant="ghost" size="sm" onclick={openSidebar} aria-label="Open menu">
+<MenuIcon />
+</Button>
+<span class="font-semibold">My App</span>
+{/snippet}
+
+<h1>Page content</h1>
+</SidebarLayout>
+```
+
+```svelte
+<SidebarLayout bind:open={sidebarOpen} mode="collapsible" sidebarWidth="16rem">
+{#snippet sidebarHeader()}<span class="font-semibold">App</span>{/snippet}
+{#snippet sidebar()}<nav class="p-3"><!-- … --></nav>{/snippet}
+
+<Button onclick={() => (sidebarOpen = !sidebarOpen)}>Toggle</Button>
+<!-- main content -->
+</SidebarLayout>
+```
+
+### Variants
+- contentMaxWidth: 2xl, lg, md, none, sm, xl (default: xl)
+- side: left, right (default: left)
+
+### Api
+| Prop | Type | Required | Default | Description |
+| --- | --- | :---: | --- | --- |
+| ...HTMLAttributes<HTMLDivElement> | `HTMLAttributes` | no |  | HTML attributes (excluding: 'children') |
+| children | `Snippet` | no |  | Page content rendered inside the centered main column. |
+| class | `string` | no |  | Additional CSS classes applied to the root wrapper. |
+| closeOnBackdropClick | `boolean` | no | true | Close the mobile sidebar overlay when clicking the backdrop. |
+| closeOnEscape | `boolean` | no | true | Close the mobile sidebar overlay when pressing Escape. |
+| contentMaxWidth | `SidebarLayoutVariants['contentMaxWidth']` | no | 'xl' | Maximum width of the centered content column. |
+| mobileHeader | `Snippet<[MobileHeaderContext]>` | no |  | Mobile header bar, hidden on desktop in `responsive` mode. Receives a helper to open the sidebar so a hamburger button needs no extra wiring. If omitted, no mobile header is rendered. |
+| mode | `'responsive' | 'collapsible'` | no | 'responsive' | Sidebar mode. - `responsive` (default): permanent on desktop (≥1024px), slide-in overlay on mobile. - `collapsible`: toggleable at all viewports — width animation on desktop, overlay on mobile. |
+| onOpenChange | `(open: boolean) => void` | no |  | Fires when the sidebar open state changes. |
+| open | `boolean` | no | false | Sidebar visibility. In `responsive` mode this only affects the mobile overlay. In `collapsible` mode it controls visibility at all viewports. Supports `bind:open`. |
+| preset | `string` | no |  | Apply a named preset registered via `<BlocksProvider presets={{ SidebarLayout: {...} }}>`. Use this to share a branded shell look across the app instead of repeating class overrides. |
+| side | `SidebarLayoutVariants['side']` | no | 'left' | Which edge the sidebar attaches to. |
+| sidebar | `Snippet` | no |  | Sidebar main content — typically a `<nav>`. |
+| sidebarFooter | `Snippet` | no |  | Sidebar footer (below the scrollable nav). |
+| sidebarHeader | `Snippet` | no |  | Sidebar header (above the scrollable nav). |
+| sidebarWidth | `string` | no | '16rem' | Sidebar panel width. Single source of truth — the layout exposes it as `--sidebar-width` (constant) and `--sidebar-effective-width` (animates to `0` when collapsed) on the layout root, so the main content offset stays in sync automatically. |
+| slotClasses | `Partial<Record<SidebarLayoutSlot, string>>` | no |  | Per-slot class overrides. `sidebar*` slots are forwarded to the embedded `<Sidebar>` component (mapped to its `slotClasses.panel`/`header`/...). |
+| unstyled | `boolean` | no |  | Strip all default styles. Combine with `slotClasses` for a custom layout. |
+
+Inherited from:
+- Omit<HTMLAttributes<HTMLDivElement>, 'children'> (omit-pattern)