@urbicon-ui/design-content 6.1.8

package/content/design-system/patterns/dashboard.md

@@ -0,0 +1,55 @@
+# Dashboard
+
+Data-rich overview page with metrics, charts, and action shortcuts.
+
+## Layout
+
+- **Structure:** full-width content area, optionally within `SidebarLayout` for app navigation
+- **Grid:** CSS grid with responsive columns. Desktop: 3-4 columns for stat tiles, 2 columns for charts/tables. Mobile: single column stack.
+- **Content:** no max-width constraint (data-dense view). Cards fill available space.
+- **Spacing:** `gap-4` between grid items, `gap-6` between sections (stats row, charts row, table row)
+
+## Component Selection
+
+| UI Need | Component | Configuration |
+|---|---|---|
+| Stat/KPI tile | `Card` | Compact padding, prominent number + label + trend indicator |
+| Trend direction | `Badge` | `intent="success"` for up, `intent="danger"` for down |
+| Proportional data | `CompositionBar` | Horizontal bar with legend |
+| Flow visualization | `Sankey` | Multi-level relationship flows |
+| Data table | `Table` | With sorting, filtering; limit visible rows (5-10), link to full view |
+| Quick actions | `ButtonGroup` or `Toolbar` | Top-right of page or section |
+| Date range filter | `DatePicker` or `Select` | Top of page, controls all widgets below |
+| Empty widget | `EmptyState` | In Card, with action to configure/populate |
+| Loading state | `Skeleton` | Match widget dimensions, not generic spinners |
+| Notifications | `Alert` | Persistent, at page top, for system status |
+
+## Section Ordering
+
+1. **Page header:** title + date range filter + quick actions
+2. **Stat tiles:** 3-4 KPI cards in a single row
+3. **Charts / visualizations:** 2 cards side-by-side (e.g., CompositionBar + trend chart)
+4. **Activity table:** recent activity or transactions, with link to full view
+5. **Secondary widgets:** lower-priority info, may be collapsed or tabbed
+
+## Behavioral Rules
+
+- All widgets should show `Skeleton` during data loading, matching the widget's final dimensions.
+- Date range filter at the top controls all widgets — changing the range refreshes everything.
+- Stat tiles: show current value, trend (% change), and a subtle trend indicator (Badge with intent).
+- Tables: show only 5-10 rows on the dashboard. Provide a "View all" link to the full table view.
+- Auto-refresh: if data is live, use `Table` live-update capabilities (`pushInsert`, `pushUpdate`). Show a subtle timestamp ("Last updated: 2 min ago").
+- Error states: per-widget errors, not a page-level error. Show `Alert` within the `Card` that failed.
+
+## Anti-Patterns
+
+- Do not use full-featured `Table` with all controls (grouping, column reorder, etc.) on the dashboard. Keep it compact.
+- Do not mix different Card styles within the same section. Stat tiles should look uniform.
+- Do not stack more than 3 vertical sections without scroll anchoring or navigation.
+- Do not use `Dialog` for drill-down. Use `Drawer` or navigate to a detail page.
+- Do not show raw numbers without context. Always pair a number with a label and, where applicable, a trend.
+
+## Related
+
+- Recipe: `dashboard` — complete production-ready code example
+- Pattern: `settings-page` — for admin dashboards with settings navigation

package/content/design-system/patterns/form-page.md

@@ -0,0 +1,69 @@
+# Form Page
+
+Standalone form for data entry — registration, creation, multi-step wizards.
+
+## Layout
+
+- **Structure:** centered content area with constrained width
+- **Content:** max-width 560px for simple forms, 720px for complex forms with side context
+- **Spacing:** `gap-6` between form groups, `gap-4` between fields within a group
+- **Responsive:** single-column stack. On desktop, short related fields (first/last name, city/zip) can sit side-by-side in a 2-column grid.
+- **Actions:** bottom of form, right-aligned. Primary action first (right), secondary (Cancel/Back) second (left).
+
+## Component Selection
+
+| UI Need | Component | Configuration |
+|---|---|---|
+| Text input | `Input` | Wrapped in `FormField` |
+| Multi-line text | `Textarea` | Wrapped in `FormField`, with character count if limited |
+| Email/password | `Input` | `type="email"` / `type="password"`, wrapped in `FormField` |
+| Enum selection | `Select` or `RadioGroup` | Select for 4+, RadioGroup for 2-3 visible options |
+| Searchable selection | `Combobox` | 7+ options, wrapped in `FormField` |
+| Boolean consent | `Checkbox` | For agreements ("I accept the terms") |
+| Boolean toggle | `Toggle` | For preference settings within a form |
+| Date input | `DatePicker` | Wrapped in `FormField` |
+| Currency | `CurrencyInput` | Locale-aware, wrapped in `FormField` |
+| File | `FileUpload` | Drag-and-drop zone, clear accepted formats |
+| Form group | `Card` or visual separator | Card for distinct sections, `Separator` for light division |
+| Submit action | `Button intent="primary"` | Loading state during submission |
+| Multi-step | `Stepper` | Shows progress, validates per step |
+| Validation feedback | `FormField` error prop | Inline, under the field |
+| Submit feedback | `Toast` | Success/error after submission |
+
+## Validation Rules
+
+- Validate on blur for individual fields (immediate feedback).
+- Validate on submit for cross-field rules (password confirmation, date ranges).
+- Show error text below the field via `FormField` error prop, not in a `Toast` or `Alert`.
+- Required fields: mark optional fields with "(optional)" label suffix instead of marking required with asterisks.
+- Disable submit button only while submission is in-flight (spinner), not while fields are invalid — let users click and see validation errors.
+
+## Multi-Step Forms
+
+- Use `Stepper` to show progress.
+- Validate the current step before allowing navigation to the next.
+- Allow backward navigation without losing data.
+- Show a summary/review step before final submission for important forms.
+- Keep step count visible (e.g., "Step 2 of 4"), not just a progress bar.
+
+## Behavioral Rules
+
+- Pre-fill known data (from user profile, previous entries, URL params).
+- Persist draft state for long forms (localStorage or server-side draft).
+- Show unsaved-changes warning on navigation away (`ConfirmDialog`).
+- Group related fields together. Use `Card` with a heading for distinct sections (Personal Info, Payment, Shipping).
+- Place help text in `FormField` description, not in `Tooltip`. Tooltips are hidden by default.
+
+## Anti-Patterns
+
+- Do not use `Dialog` for forms with more than 3 fields. Use a dedicated page or `Drawer`.
+- Do not use horizontal multi-column layouts for unrelated fields. Side-by-side only for naturally paired fields (first + last name, city + zip).
+- Do not put the submit button above the form. Actions go at the bottom, where the user ends.
+- Do not use `placeholder` as the only label. Always use `FormField` with a visible label.
+- Do not auto-submit on field change without explicit user instruction.
+
+## Related
+
+- Recipe: `login` — login/registration form example
+- Recipe: `wizard` — multi-step form wizard example
+- Pattern: `settings-page` — for forms embedded in settings sections

package/content/design-system/patterns/onboarding-guide.md

@@ -0,0 +1,50 @@
+# Onboarding & In-App Help
+
+Guide a first-run user and keep help available in context, using the Guide system over one
+headless controller — without a modal wizard that blocks the app. Guide is the library's
+sequential, system-driven overlay pattern (it decides *when*, *in what order*, and *in what
+mode* help appears), unlike the spatial, event-driven overlays (`Dialog`, `Popover`, `Tooltip`).
+
+## Layout
+
+- **Provider:** one `GuideProvider` near the app root, holding one `GuideController` you create yourself for programmatic control.
+- **Tour renderer:** one `<Guide />` inside the provider — invisible until a tour starts; it owns the top-layer spotlight + bubble.
+- **Help panel:** one `GuidePanel` — non-modal, docks to a screen edge at `--z-sidebar`; the app stays interactive behind it.
+- **Entry point:** a `GuideBeacon` placed inline or absolutely over a "new" feature — the gentle, opt-in tour entry. Never auto-start.
+- **Targets:** mark each referenced element once with `data-guide="<id>"`; tours, hints, markers, and mentions all resolve through that one namespace.
+
+## Component Selection
+
+| UI Need | Component | Configuration |
+|---|---|---|
+| First-run walkthrough | `Guide` + a `GuideTour` | Opt-in, 3–5 steps; spotlight each step `target` |
+| Gentle tour entry | `GuideBeacon` | `tour={...}`; hides itself once the tour is seen |
+| Always-available help | `GuidePanel` + `GuideArticle` | Non-modal; controller-driven `openPanel(article?)` |
+| "What does this do?" affordance | `GuideMarker` | `for="<id>"` → opens the panel at the article (UI → guide) |
+| Point an article at the UI | `GuideMention` | `for="<id>"` inside an article; highlights on hover **and** focus (guide → UI) |
+| One-off contextual nudge | `GuideHint` | `trigger="mount"`, or `"manual"` + `open`; `once` persists "seen" |
+| Onboarding analytics | `onStep` / `onComplete` / `onSkip` | On the `GuideTour` — the funnel + drop-off signal |
+
+## Behavioral Rules
+
+- **Helpful, not intrusive.** Default to the callable panel and the waiting hint. The scrim tour is the most aggressive mode and stays opt-in (beacon or explicit button) — never auto-started.
+- **One controller, many surfaces.** Create the `GuideController`, pass it to `GuideProvider`, and drive everything (`startTour`, `openPanel`, `hasSeen`) from it.
+- **Persist "seen."** Tours and `once` hints mark themselves seen on end, so a returning user is not nagged. `stopTour()` (route change / unmount) deliberately does NOT mark seen and is analytics-silent.
+- **Track the funnel.** Wire `onStep` / `onComplete` / `onSkip` — `onStep.via` distinguishes `start` vs `next`/`prev`, and `onSkip.index` is the drop-off step. This is the real business value of onboarding.
+- **Cross-route tours are app-driven.** The controller survives client navigation and the renderer re-anchors once the new route's `data-guide` target appears; the app navigates in `tour.onStep` (e.g. `goto(stepRoutes[index])`). Mount `Guide` in the layout — a route-local renderer unmounts mid-tour. Full recipe: `docs/GUIDE.md` §9.
+- **Learning-by-doing steps:** `GuideStep.advance: 'action'` (paired with `interactive: true`) disables Next; the user performs the real action and the app advances via `controller.next()`.
+- **Content lives in the app**, not the library: steps, article text, and `data-guide` selectors are app-owned (and i18n'd by the app).
+- **Reduced motion** is honored automatically (panel slide, beacon pulse, step fade) — no extra work.
+
+## Anti-Patterns
+
+- Do not auto-start a tour on page load. Onboarding that hijacks the screen before the user acts is exactly why product tours earned a bad reputation.
+- Do not use a modal `Dialog` / `Drawer` as the help panel. The panel must be non-modal so a `GuideMention` can highlight a UI element while the panel is open (the bidirectional link breaks otherwise).
+- Do not build a multi-step **form wizard** with `Guide`. That is a `Stepper` + form pattern; `Guide` overlays *existing* UI, it does not collect input.
+- Do not invent `data-guide` ids with `Math.random()` — they are author-chosen, stable strings shared across surfaces.
+- Do not duplicate help copy across a tour step and an article; point both at the same `data-guide` topic instead.
+
+## Related
+
+- Recipe: `onboarding-flow` — complete production-ready Guide-system example
+- Guide: `docs/GUIDE.md` — full architecture and the cross-route tour recipe (§9)

package/content/design-system/patterns/planning-board.md

@@ -0,0 +1,46 @@
+# Planning Board
+
+Date-indexed board that lays domain items — meals, shifts, bookings, content slots — onto calendar days across a week, month or custom range.
+
+## Layout
+
+- **Structure:** `Planner` is the whole board. It buckets `items` by day and renders each cell via your `cell` snippet — no manual date math, no per-day grid.
+- **View:** `view="week"` for a column-per-day plan (the default), `view="month"` for a compact 6×7 overview, `view="range"` for an arbitrary span. Week stacks to one column per day on mobile automatically.
+- **Cells:** put a small stack of cards or rows inside `cell`. Keep each item to one or two lines (icon + label); the cell is narrow.
+- **Spacing:** week cells get `gap-1`–`gap-2` between items; month cells stay terse — show counts or 1–2 items, not the full list.
+- **Server alignment:** load the week on the server with `@urbicon-ui/blocks/date` (`startOfWeek` / `toIso`) so the SSR range and the client grid agree — no UTC drift.
+
+## Component Selection
+
+| UI Need | Component | Configuration |
+|---|---|---|
+| The board itself | `Planner` | `view`, `items`, `getDate`; `sort` for intra-day order |
+| Per-day content | `cell` snippet | Receives typed `items: T[]`, `isoDate`, `isToday`, `selectDate()` |
+| An item card | `Card` or a plain `div` | One per item, kept to a line or two |
+| Item category / status | `Badge` | `intent` per category (`success`/`warning`/`primary`…) |
+| Add-on-a-day affordance | `Button variant="ghost" size="sm"` | Inside `cell` — rendered for empty days too |
+| Empty-day placeholder | `empty` snippet | Optional; omit it to let `cell` handle empty days |
+| Custom toolbar | `header` snippet | Replaces prev/next/today/title |
+| Timed appointments instead | `Calendar` | Use Calendar, not Planner, when items have a clock time |
+
+## Behavioral Rules
+
+- `getDate` returns a `Date` or a local ISO date string (`'2026-06-16'`); strings are taken verbatim, so a day never shifts across timezones. Pass a `Date` for UTC instants.
+- The `cell` snippet runs for **every** day, empty ones included — keep the "add" button there so it is reachable on blank days.
+- Drive data loading from `onNavigate(date, range)`: fetch `range.start … range.end`, not the whole month.
+- `bind:value` is the reference date; `bind:selectedDate` is the active day. Clicking a cell's body selects its day; clicks on interactive cell content keep their own behaviour.
+- Sort within a day via `sort` (e.g. breakfast → lunch → dinner), not by reordering `items`.
+
+## Anti-Patterns
+
+- Do not reach for `Calendar` for uhrzeit-lose day content — its model is timed `CalendarEvent`s with bars and recurrence. Planner is single-date bucketing of your own type.
+- Do not rebuild the week/month grid by hand with `getWeekDates` + a `{#each}`. That is exactly what Planner removes.
+- Do not stuff a full item list into a month cell. Summarise (count or top item) and switch to `view="week"` for detail.
+- Do not parse a plain date string through `new Date()` before handing it to `getDate` — you reintroduce the UTC off-by-one Planner avoids.
+- Do not gate the add affordance behind "has items". Empty days are where you add most.
+
+## Related
+
+- Component: `Planner` — the board; see also `Calendar` for timed events
+- Recipe: `meal-planner` — complete production-ready weekly plan
+- Pattern: `dashboard` — when the board is one panel among analytics

package/content/design-system/patterns/settings-page.md

@@ -0,0 +1,48 @@
+# Settings Page
+
+Multi-section user preferences with sidebar navigation and grouped content areas.
+
+## Layout
+
+- **Structure:** `SidebarLayout` with sidebar navigation + scrollable content area
+- **Sidebar:** 240-280px width, grouped navigation links via `Sidebar` with `Accordion` for groups
+- **Content:** max-width 720px, vertically stacked sections
+- **Responsive:** below 768px, sidebar collapses; use a `Select` or horizontal scrollable navigation to switch sections
+- **Spacing:** `gap-8` between sections, `gap-4` within sections
+
+## Component Selection
+
+| UI Need | Component | Configuration |
+|---|---|---|
+| Section navigation | `Sidebar` + `Accordion` | Grouped links, highlight active section |
+| Section container | `Card` | `variant="outlined"` |
+| Section heading | Native `h2` | `text-text-primary font-semibold text-lg` |
+| Subsection heading | Native `h3` | `text-text-secondary font-medium text-base` |
+| Boolean setting | `Toggle` | With label, not `Checkbox` |
+| Enum setting (3-6) | `Select` | Labeled via `FormField` |
+| Enum setting (7+) | `Combobox` | Searchable, labeled via `FormField` |
+| Free text | `Input` or `Textarea` | Labeled via `FormField` |
+| Save/cancel | `Button` pair | Sticky bottom bar when form exceeds viewport |
+| Destructive action | `Button intent="danger"` | Separated at bottom, requires `ConfirmDialog` |
+| Status feedback | `Toast` | On save success/failure |
+
+## Behavioral Rules
+
+- Group related settings in Cards. One Card per conceptual group (Account, Notifications, Privacy).
+- Save button shows loading state (spinner) during save.
+- Warn on unsaved changes: intercept navigation, show `ConfirmDialog`.
+- Reset/Cancel returns to last saved state, not initial page load state.
+- Destructive settings (delete account, revoke access) separated at the bottom of the page, visually distinct from other settings.
+- Default values: show the active value, not "unchanged". Users should see what is currently configured.
+
+## Anti-Patterns
+
+- Do not use `Tab` for settings groups. Tabs imply peer sections at the same hierarchy; settings are hierarchical.
+- Do not put all settings in a single scrollable list without navigation.
+- Do not use modals for inline editing. Edit in place, save with the section's save action.
+- Do not auto-save without explicit user signal. Settings changes should be intentional.
+
+## Related
+
+- Recipe: `settings` — complete production-ready code example
+- Pattern: `form-page` — for standalone forms within settings sections

package/content/design-system/patterns/tab-navigation.md

@@ -0,0 +1,136 @@
+# Tab Navigation
+
+URL-based tab navigation for SvelteKit routes — each tab maps to a route segment.
+
+## When to Use
+
+Use this pattern when:
+- Peer sections of a detail view need their own URL (bookmarkable, shareable)
+- Each section has distinct content that justifies a separate route
+- The user navigates between sections without losing page context (e.g., project detail with Overview, Settings, Logs)
+
+Do NOT use when:
+- Sections share state that would be lost on navigation — use client-side `Tab` with `bind:value` instead
+- There are only 2 sections — consider a simple toggle or inline layout
+- Sections are hierarchical — use `Sidebar` navigation instead (see `settings-page` pattern)
+
+## Layout
+
+- **Structure:** shared layout (`+layout.svelte`) with `Tab` or `SegmentGroup` + nested `+page.svelte` per section
+- **Placement:** tabs directly below the page header / breadcrumb, above the content area
+- **Content:** each `+page.svelte` renders its own section content below the shared tab bar
+- **Responsive:** on mobile, consider horizontal scroll for the tab bar, or collapse to a `Select` dropdown for 5+ tabs
+
+## SvelteKit Route Structure
+
+```
+routes/
+  project/[id]/
+    +layout.svelte      ← shared tab bar
+    +page.svelte         ← "Overview" (default tab)
+    settings/
+      +page.svelte       ← "Settings" tab
+    logs/
+      +page.svelte       ← "Logs" tab
+    hooks/
+      +page.svelte       ← "Hooks" tab
+```
+
+## Implementation
+
+### Shared Layout with Tab Navigation
+
+```svelte
+<script lang="ts">
+  import { page } from '$app/state';
+  import { Tab } from '@urbicon-ui/blocks';
+
+  const { children } = $props();
+
+  const tabs = [
+    { label: 'Overview', href: `/project/${page.params.id}` },
+    { label: 'Settings', href: `/project/${page.params.id}/settings` },
+    { label: 'Logs', href: `/project/${page.params.id}/logs` },
+    { label: 'Hooks', href: `/project/${page.params.id}/hooks` },
+  ];
+
+  const activeTab = $derived(
+    tabs.findIndex((t) => page.url.pathname === t.href) ?? 0
+  );
+</script>
+
+<div class="flex flex-col gap-6">
+  <Tab.Root value={tabs[activeTab]?.label}>
+    {#each tabs as tab}
+      <Tab.Trigger value={tab.label}>
+        <a href={tab.href}>{tab.label}</a>
+      </Tab.Trigger>
+    {/each}
+  </Tab.Root>
+
+  {@render children()}
+</div>
+```
+
+### Alternative: SegmentGroup (Compact)
+
+For fewer tabs (2-4) where a more compact visual is preferred:
+
+```svelte
+<script lang="ts">
+  import { page } from '$app/state';
+  import { goto } from '$app/navigation';
+  import { SegmentGroup } from '@urbicon-ui/blocks';
+
+  const segments = [
+    { value: 'overview', label: 'Overview', href: `/project/${page.params.id}` },
+    { value: 'settings', label: 'Settings', href: `/project/${page.params.id}/settings` },
+  ];
+
+  const current = $derived(
+    segments.find((s) => page.url.pathname === s.href)?.value ?? 'overview'
+  );
+</script>
+
+<SegmentGroup
+  value={current}
+  onValueChange={(v) => {
+    const seg = segments.find((s) => s.value === v);
+    if (seg) goto(seg.href);
+  }}
+>
+  {#each segments as seg}
+    <SegmentGroup.Item value={seg.value}>{seg.label}</SegmentGroup.Item>
+  {/each}
+</SegmentGroup>
+```
+
+## Component Selection
+
+| UI Need | Component | When |
+|---|---|---|
+| 3+ peer sections | `Tab` | Standard horizontal tabs |
+| 2-4 compact options | `SegmentGroup` | Tighter visual, pill-style |
+| 5+ sections on mobile | `Select` | Dropdown fallback for narrow screens |
+| Hierarchical subsections | `Sidebar` | Use `settings-page` pattern instead |
+
+## Behavioral Rules
+
+- The default route (`+page.svelte` at the layout level) is the first/primary tab.
+- Active tab is derived from `page.url.pathname`, not from component state — the URL is the source of truth.
+- Use `<a href>` for navigation, not `goto()`, to preserve browser history and link behavior.
+- Breadcrumbs above the tab bar should show the entity context (e.g., "Projects / My Project"), not the tab name.
+- Each tab page should be independently loadable via URL (deep linking).
+
+## Anti-Patterns
+
+- Do not store active tab in `$state` — derive it from the URL. Client-side state and URL will drift.
+- Do not use `Tab` with `bind:value` for route-based navigation — use `<a href>` inside tab triggers.
+- Do not duplicate the tab bar in every `+page.svelte` — put it in the shared `+layout.svelte`.
+- Do not use this pattern for settings with save/cancel — use the `settings-page` pattern with `Sidebar` instead.
+
+## Related
+
+- Pattern: `settings-page` — for hierarchical settings navigation
+- Component: `Tab` — the underlying tab component API
+- Component: `SegmentGroup` — compact alternative for few sections