@urbicon-ui/design-content 6.1.8

package/content/design-system/principles.md

@@ -0,0 +1,260 @@
+# Urbicon UI — Design Principles
+
+Design heuristics for building UIs with Urbicon UI. These principles guide the LLM in making design decisions — from individual component choices to full-page composition. They complement the token reference (`get_css_reference`) and component catalog (`find_components`).
+
+## Visual Hierarchy
+
+- Max 1 primary CTA per viewport. Additional actions use `intent="neutral"` or `variant="ghost"`.
+- Use the typography scale (text size + weight) for information hierarchy, never color alone.
+- Progressive disclosure: show a summary, let the user expand for detail (Accordion, Collapsible, "Show more").
+- 3 hierarchy levels max per view: heading, subheading, content. Deeper nesting signals a need for navigation.
+- Vary visual weight across Cards — not every Card needs `variant="outlined"` and `padding="lg"`. Mix quiet (no border, bg-surface-quiet) with prominent (outlined, elevated).
+- Text hierarchy: primary for key info, secondary for supporting, tertiary for metadata, quaternary for subtle labels. Never skip more than one level.
+- Use `intent` colors only for semantic meaning (success/danger/warning/info), never for decoration.
+
+## Interaction
+
+- Destructive actions always require explicit confirmation via `ConfirmDialog`.
+- Form validation: inline at the field via `FormField` error state, not a global error banner after submit.
+- Loading states belong on the triggering element (`Button` spinner), not a global page spinner.
+- Hover states: use `bg-surface-hover` for interactive surfaces, never raw opacity changes.
+- Focus: always `focus-visible:`, never `focus:` — keyboard-only focus rings.
+- Disabled elements: `bg-surface-disabled` + `text-text-disabled`, with `cursor-not-allowed`. Never hide disabled options — show them so users understand they exist.
+- Optimistic UI where safe (toggles, selections). Confirmation-dependent actions (delete, send) wait for server.
+- Toasts for non-blocking feedback (saved, copied). Alerts for persistent status (offline, quota reached).
+
+## Component Selection
+
+These heuristics map common UI needs to the right Urbicon UI component:
+
+| Need | Component | Why |
+|---|---|---|
+| 2-3 mutually exclusive options | `RadioGroup` | Visible at a glance |
+| 4-6 mutually exclusive options | `Select` | Compact, scrollable |
+| 7+ options or needs search | `Combobox` | Searchable, filterable |
+| Boolean on/off setting | `Toggle` | Immediate visual feedback |
+| Boolean agreement/consent | `Checkbox` | Conveys "I confirm" semantics |
+| Single action | `Button` | Clear affordance |
+| Multiple related actions | `ButtonGroup` | Visual grouping |
+| Contextual actions (right-click, "more") | `Menu` | Discoverable on demand |
+| Date selection | `DatePicker` | Constrained input with calendar |
+| Free text | `Input` or `Textarea` | Single-line vs. multi-line |
+| Currency amount | `CurrencyInput` | Locale-aware formatting |
+| Navigation between peer sections | `Tab` | Horizontal, same hierarchy |
+| Navigation between hierarchical sections | `Sidebar` | Vertical, nested groups |
+| Quick access to any page/action | `CommandPalette` | Keyboard-first, searchable |
+| Status indicator | `Badge` | Compact, intent-colored |
+| Step-by-step flow | `Stepper` | Shows progress + completion |
+| Blocking user decision | `Dialog` | Modal, focused |
+| Supplementary content panel | `Drawer` | Slide-in, non-blocking |
+| Contextual info on hover/focus | `Tooltip` | Ephemeral, no interaction |
+| Contextual content on click | `Popover` | Persistent, interactive |
+| Empty data state | `EmptyState` | Friendly, actionable |
+| Tabular data | `Table` | Sorting, filtering, selection |
+| Proportional breakdown | `CompositionBar` | Visual percentages |
+| Flow/relationship visualization | `Sankey` | Multi-level flows |
+| File selection | `FileUpload` | Drag-and-drop + browse |
+
+## Layout
+
+- Content max-width: 720px for readability. Wider only for data-dense views (tables, dashboards).
+- Use `Sidebar` for settings/admin navigation. Use `Tab` for peer sections within a page.
+- Group related content in `Card`s. Cards represent conceptual units, not individual items.
+- Sticky action bars (`Save`/`Cancel`) when forms exceed the viewport.
+- Empty states: always provide an action. "No results" alone is a dead end.
+- Page spacing rhythm: `gap-8` or `gap-10` between sections, `gap-4` or `gap-6` within sections.
+- Separator for visual breaks within a surface, not between Cards (Cards have their own boundaries).
+- Use `SidebarLayout` for app shells with persistent navigation. Use standalone `Sidebar` for in-page nav.
+
+## Accessibility
+
+- Every icon-only `Button` needs `aria-label`.
+- Form fields must be wrapped in `FormField` for automatic label + error + description association.
+- Keyboard navigation: all interactive elements reachable via Tab. Custom widgets implement arrow-key navigation (Menu, Select, Combobox, Table).
+- Color contrast: semantic tokens are pre-tuned for WCAG AA (4.5:1 for text, 3:1 for UI elements). Do not override with lower-contrast alternatives.
+- Motion: all animations respect `prefers-reduced-motion`. Interaction tokens collapse durations to 1ms automatically.
+- Skip links: include for long navigation sections.
+- Announce dynamic content (toast messages, live table updates) via aria-live regions.
+
+## Theming
+
+### The 5-Layer Token Hierarchy
+
+Understanding which layer to modify is the key to efficient design changes:
+
+| Layer | What it controls | Format | How changes propagate |
+|---|---|---|---|
+| 1. Foundation | Raw OKLCH color palettes, radius scale, z-index | CSS `@theme` | Automatically to all layers above |
+| 2. Semantic | Surface, text, border, intent, shadow tokens | CSS `@theme` with `light-dark()` | Automatically to components |
+| 3. Component | Variant defaults, slot classes, presets | `tv()` + `BlocksProvider` | Automatically to instances |
+| 4. Composition | Page layout, component arrangement, spacing | Markdown patterns (this system) | Via LLM knowledge |
+| 5. Principles | Design heuristics, selection rules | Markdown (this file) | Via LLM knowledge |
+
+**Layers 1-3 propagate through code.** Change a foundation token and every semantic token, component, and instance that references it adapts automatically. **Layers 4-5 propagate through knowledge.** Change a principle or pattern and the LLM applies it the next time it generates UI.
+
+### Design Change Decision Tree
+
+When asked to modify the design, identify the correct layer:
+
+**"Change the color / mood / brand"** → Layer 1 (Foundation)
+- Create a custom theme CSS file overriding `--color-primary-*` and `--color-secondary-*`
+- Use OKLCH: adjust hue (H) for color direction, chroma (C) for vibrancy, lightness (L) curve for contrast
+- Everything else adapts automatically — semantic tokens, components, dark mode
+- Optional: override `--blocks-shadow-tint` for cohesive shadows (warm brand → warm shadows)
+
+**"Adjust dark mode appearance"** → Layer 2 (Semantic)
+- Modify the `light-dark()` values in semantic tokens
+- Never use Tailwind `dark:` overrides — they bypass the token system
+- The 4-level surface ladder (quiet → base → elevated → overlay) and text hierarchy auto-resolve
+
+**"Make buttons / cards / inputs look different"** → Layer 3 (Component)
+- Use `BlocksProvider` `defaults` for global component overrides
+- Use `presets` for named looks (e.g., `preset="compact"`)
+- Use `slotClasses` on individual instances for one-off overrides
+- Use `unstyled` to strip all defaults and bring your own styling
+
+**"Change page layout / navigation structure"** → Layer 4 (Composition)
+- Update the composition pattern file (see `get_pattern()`)
+- LLM applies the updated pattern when generating new pages
+- Existing pages need manual migration
+
+**"Change design rules / component selection heuristics"** → Layer 5 (Principles)
+- Update this file
+- LLM applies updated rules going forward
+
+### Creating a Custom Theme
+
+A theme file overrides three foundation ramps: the two accents (`--color-primary-*`, `--color-secondary-*`) **and the neutral chassis** (`--color-neutral-*`). All semantic tokens — surfaces, text, borders, intents — inherit automatically. The chassis is the most-missed piece: surfaces/text/borders derive from `--color-neutral-*`, which defaults to a cool Hue 240. Re-tint it to your accent's temperature, or a warm brand color lands on cold grey surfaces (the classic "half-themed" look).
+
+```css
+/* app-theme.css — import AFTER base styles */
+@theme {
+  /* Primary palette — shift hue, adjust chroma for vibrancy */
+  --color-primary-50:  oklch(0.97 0.01 YOUR_HUE);
+  --color-primary-100: oklch(0.93 0.03 YOUR_HUE);
+  --color-primary-200: oklch(0.85 0.06 YOUR_HUE);
+  --color-primary-300: oklch(0.76 0.09 YOUR_HUE);
+  --color-primary-400: oklch(0.66 0.12 YOUR_HUE);
+  --color-primary-500: oklch(0.55 0.14 YOUR_HUE);
+  --color-primary-600: oklch(0.48 0.14 YOUR_HUE);
+  --color-primary-700: oklch(0.40 0.12 YOUR_HUE);
+  --color-primary-800: oklch(0.32 0.10 YOUR_HUE);
+  --color-primary-900: oklch(0.24 0.07 YOUR_HUE);
+  --color-primary-950: oklch(0.16 0.04 YOUR_HUE);
+
+  /* Secondary — complementary or analogous hue */
+  --color-secondary-50:  oklch(0.97 0.01 SEC_HUE);
+  /* ... same 50-950 scale ... */
+
+  /* Chassis — re-tint the neutral ramp to CHASSIS_HUE (≈ YOUR_HUE).
+     Keep lightness + chroma at the foundation values; only shift the hue,
+     so WCAG contrast is preserved. Set chroma to 0 for a true grayscale. */
+  --color-neutral-25:  oklch(0.99 0.002 CHASSIS_HUE);
+  --color-neutral-50:  oklch(0.98 0.005 CHASSIS_HUE);
+  /* ... 100-850 ... */
+  --color-neutral-900: oklch(0.15 0.012 CHASSIS_HUE);
+  --color-neutral-950: oklch(0.08 0.008 CHASSIS_HUE);
+}
+```
+
+**OKLCH parameter guide:**
+- **Hue (H):** 0-360 color wheel. 0=red, 30=orange, 60=yellow, 140=green, 220=blue, 280=purple, 340=pink
+- **Chroma (C):** 0=gray, 0.05=muted, 0.10=moderate, 0.15=vibrant, 0.20+=vivid. Stay under 0.18 for foundation accent scales; keep the neutral chassis ≤0.017 so it stays near-grey.
+- **Lightness (L):** 0=black, 1=white. The 50-950 scale should span L=0.97 (lightest) to L=0.16 (darkest). 500/600 are the "base" shades used in semantic intent tokens.
+
+> If you scope a theme to a class (e.g. a runtime-toggled `.theme-x`) instead of a global `@theme`/`:root` block, you must also re-declare the derived semantic tokens (`--color-primary`, surface/text/border) inside that class — inline/scoped `var()` won't re-substitute against the overridden ramp on its own. Global `@theme` themes don't hit this. See `apps/docs/src/lib/style/editorial.css` for a fully worked scoped example.
+
+### Built-in Themes
+
+Five pre-built themes are available, each shifting primary + secondary hues, re-tinting the neutral chassis to match the accent's temperature, re-tuning any intent ramp that would collide with the accent (plus a matching shadow tint), **and** re-tinting the neutral intent (`bg-neutral` / `text-neutral` / borders) via `--neutral-chrome-hue`. Non-colliding intents (success/warning/danger/info) stay at the library defaults; the Neutral theme inherits the cool default chrome.
+
+The neutral intent keeps the `--color-warm-neutral-*` ramp's lightness profile (tuned so white-on-fill and neutral-text both stay legible light/dark) and only takes its hue from `--neutral-chrome-hue` (`:root`, default 240). Set it per theme — `:root { --neutral-chrome-hue: 50; }` — to re-tint neutral controls without touching contrast. Don't repoint the neutral intent onto the chassis `--color-neutral-*` ramp; its surface lightness breaks the dual-role (fill vs. text) contrast balance.
+
+| Theme | Primary Hue | Secondary Hue | Chassis Hue | Re-tuned intents | Character |
+|---|---|---|---|---|---|
+| Default | 240 (indigo) | 280 (purple) | 240 (cool) | — | Professional, balanced |
+| Ocean | 220 (blue) | 190 (teal) | 220 (cool) | info → 255 (off brand blue) | Cool, trustworthy |
+| Forest | 155 (green) | 90 (lime) | 150 (stone) | success → 172, warning → 60 | Natural, calm |
+| Sunset | 55 (amber) | 25 (orange) | 50 (warm) | warning → 92, danger → 16 | Warm, energetic |
+| Rose | 350 (pink) | 310 (magenta) | 350 (warm) | danger → 34 | Soft, approachable |
+| Neutral | 240/minimal chroma | 240/minimal chroma | grayscale (chroma 0) | — | Content-focused, no brand color |
+
+### Semantic Radius Tiers
+
+Three radius tiers map to component families — override these, not individual component radii:
+
+| Tier | Token | Default | Components | Brand tuning |
+|---|---|---|---|---|
+| Commit | `--radius-commit` | `9999px` (pill) | Button, Badge, Toggle, SegmentGroup | Lower for less playful (e.g., `--radius-xl`) |
+| Modify | `--radius-modify` | `var(--radius-sm)` (4px) | Input, Textarea, Select, Combobox, Tab | Raise for softer (e.g., `--radius-md`) |
+| Contain | `--radius-contain` | `var(--radius-xs)` (2px) | Card, Dialog, Drawer, Alert, Tooltip | Raise for friendlier (e.g., `--radius-md`) |
+
+### Interaction Tuning
+
+Override timing and easing tokens for different personalities:
+
+| Token | Default | Subdued | Energetic |
+|---|---|---|---|
+| `--blocks-duration-fast` | 150ms | 200ms | 100ms |
+| `--blocks-duration-normal` | 250ms | 300ms | 180ms |
+| `--blocks-ease-gentle` | ease-out variant | keep | swap for springy |
+| `--blocks-mint-scale-intensity` | 1.04 | 1.02 or remove | 1.06 |
+
+### Mint (Micro-Interactions)
+
+Mint classes add playful polish: `blocks-mint-scale` (hover grow), `blocks-mint-glow` (color halo), `blocks-mint-bounce`, `blocks-mint-pulse`. Use sparingly — 1-2 mint effects per view. Glow color auto-adapts to intent (`blocks-intent-success` → green glow).
+
+## Design Paradigms
+
+When asked for a wholesale aesthetic shift, map the paradigm to specific changes across all layers:
+
+### Minimal (Default)
+The Urbicon UI baseline. Clean, functional, professional.
+- **Foundation:** moderate chroma (0.12-0.15), hue 240, default radius tiers
+- **Semantic:** neutral surfaces, subtle borders, standard shadows
+- **Interaction:** gentle easing, subtle mint (scale 1.04), standard durations
+- **Composition:** generous whitespace, content-focused, 720px max-width
+
+### Brutalist
+Raw, honest, structural. High contrast, visible grid.
+- **Foundation:** all radii to 0 (`--radius-commit: 0; --radius-modify: 0; --radius-contain: 0`), no shadows
+- **Semantic:** max border contrast (`border-emphasis` everywhere), monochrome surfaces
+- **Interaction:** `--blocks-duration-fast: 0ms` (instant), no mint effects, no easing
+- **Composition:** grid-heavy, high density, visible structural borders, monospace accents
+
+### Organic / Warm
+Friendly, natural, approachable. Warm palette, soft shapes.
+- **Foundation:** warm hue (H: 30-60), high chroma, generous radii (`--radius-contain: var(--radius-md)`), warm shadow tint (`--blocks-shadow-tint: 30 0.01 50`)
+- **Semantic:** warm neutrals for surfaces, soft borders (`border-subtle`), deeper shadows
+- **Interaction:** springy easing, scale + glow mint, slightly longer durations
+- **Composition:** flowing layouts, generous spacing (`gap-10`+), rounded Cards
+
+### Corporate / Enterprise
+Professional, data-dense, efficient. Neutral palette, compact layout.
+- **Foundation:** neutral theme (minimal chroma), tight radii, subtle shadows
+- **Semantic:** high text contrast for data readability, strong borders for tables
+- **Interaction:** confident easing (fast, no overshoot), minimal or no mint
+- **Composition:** dense layouts, prominent Tables, sidebar navigation, compact Cards
+
+### Playful / Friendly
+Fun, engaging, vibrant. Bold colors, bouncy motion.
+- **Foundation:** vivid hue with high chroma (0.16+), commit radii for everything (`--radius-modify: 9999px; --radius-contain: var(--radius-xl)`)
+- **Semantic:** colorful intent-subtle backgrounds, softer borders
+- **Interaction:** bouncy easing, all mint effects, generous durations (300ms+)
+- **Composition:** visual variety, Cards with color accents, generous spacing, illustrations over icons
+
+### Glassmorphism
+Translucent, layered, modern. Blurred backgrounds, glass surfaces.
+- **Foundation:** moderate radii (`--radius-contain: var(--radius-lg)`), prominent shadows
+- **Semantic:** surface tokens use `oklch(... / 0.7)` transparency, heavy backdrop blur (`--blocks-overlay-backdrop-blur: 12px`)
+- **Interaction:** smooth easing, glow mint, standard durations
+- **Composition:** layered Cards, depth via shadow + transparency, minimal borders (use shadow for separation)
+
+## Anti-Patterns
+
+- Never use raw Tailwind color classes (`bg-blue-500`). Always use semantic tokens (`bg-primary`, `bg-surface-base`).
+- Never add `dark:` overrides. Dark mode resolves automatically via `light-dark()`.
+- Never override individual component CSS. Use `slotClasses`, `presets`, or `BlocksProvider` `defaults`.
+- Never hardcode z-index values. Use token variables (`z-[var(--z-modal)]`).
+- Never set `border-radius` on individual components. Override the semantic radius tier token.
+- Never mix paradigms within a single app. Pick one and apply it consistently across all layers.

package/content/docs/components/api-reference/llm.txt

@@ -0,0 +1,32 @@
+
+---
+
+## ApiReference
+Structured API reference table for component documentation.
+Renders props via `@urbicon-ui/table` with per-column cell snippets
+and `Badge` indicators for source/required status.
+
+**Import:** `import { ApiReference } from '@urbicon-ui/docs';`
+
+### Examples
+```svelte
+<ApiReference props={componentData.props} />
+```
+
+### Api
+| Prop | Type | Required | Default | Description |
+| --- | --- | :---: | --- | --- |
+| props | `ApiProp[]` | yes |  | Array of prop definitions to display. |
+| ...ApiReferenceVariantProps | `VariantProps` | no |  | Styling variants from ApiReferenceVariantProps |
+| ...HTMLAttributes<HTMLElement> | `HTMLAttributes` | no |  | HTML attributes (excluding: 'children') |
+| class | `string` | no |  | Extra classes merged onto the root element. |
+| slotClasses | `Partial<Record<'base' | 'stats' | 'usageNotes', string>>` | no |  | Per-slot class overrides for the wrapper elements. |
+| unstyled | `boolean` | no |  | Remove all default tv styles from the wrapper and cell content. |
+| usageNotes | `Snippet` | no |  | Optional usage notes rendered below the table. |
+
+Inherited from:
+- ApiReferenceVariantProps (external)
+- Omit<HTMLAttributes<HTMLElement>, 'children'> (omit-pattern)
+
+### Slots (slotClasses keys)
+`base`, `stats`, `usageNotes`

package/content/docs/components/code-example/llm.txt

@@ -0,0 +1,44 @@
+
+---
+
+## CodeExample
+Code example with optional live preview, syntax highlighting, and copy-to-clipboard.
+Delegates code display to the shared CodePanel primitive.
+
+**Import:** `import { CodeExample } from '@urbicon-ui/docs';`
+
+### Examples
+```svelte
+<CodeExample title="Basic Usage" code={`<Button>Click me</Button>`} language="svelte">
+  <Button>Click me</Button>
+</CodeExample>
+```
+
+### Variants
+- size: lg, md, sm (default: md)
+- hasPreview: false, true (default: true)
+
+### Api
+| Prop | Type | Required | Default | Description |
+| --- | --- | :---: | --- | --- |
+| ...CodeExampleVariantProps | `VariantProps` | no |  | Styling variants from CodeExampleVariantProps |
+| children | `Snippet` | no |  | Live preview content rendered above the code block. |
+| class | `string` | no |  | Extra classes merged onto the root container element. |
+| code | `string` | no |  | Source code string to display with syntax highlighting. |
+| defaultExpanded | `boolean` | no |  | Override the default expanded state from the global code-visibility context. |
+| description | `string` | no |  | Short description shown between title and preview. |
+| isolate | `boolean` | no |  | Opt-in for the Vite plugin: children are auto-extracted as `code` at build time. |
+| language | `string` | no |  | Language for syntax highlighting (e.g. 'svelte', 'typescript', 'css'). |
+| preview | `boolean` | no | true | Render the live preview section above the code block. |
+| previewClass | `string` | no |  | CSS classes for the preview wrapper div when `isolate` is set. |
+| slotClasses | `Partial<Record<'container' | 'title' | 'description' | 'preview' | 'previewContent' | 'toolbar' | 'codeSection' | 'codeToggle' | 'codeChevron' | 'languageTag' | 'copyButton' | 'codeCollapse', string>>` | no |  | Per-slot class overrides for internal elements. |
+| title | `string` | no |  | Title displayed in the card header. |
+| unstyled | `boolean` | no |  | Remove all default tv styles from internal slots. |
+| size | `'lg' | 'md' | 'sm'` | no | md | Controls the dimensions, padding, and text size of the CodeExample. Affects the component's physical footprint. Available options: lg, md, sm. |
+| hasPreview | `'false' | 'true'` | no | true | Controls the hasPreview behavior and appearance of the CodeExample component. Available options: false, true. |
+
+Inherited from:
+- CodeExampleVariantProps (external)
+
+### Slots (slotClasses keys)
+`container`, `title`, `description`, `preview`, `previewContent`, `toolbar`, `codeSection`, `codeToggle`, `codeChevron`, `languageTag`, `copyButton`, `codeCollapse`

package/content/docs/components/code-panel/llm.txt

@@ -0,0 +1,26 @@
+
+---
+
+## CodePanel
+Shared code display primitive with Shiki syntax highlighting, collapsible panel, and copy-to-clipboard.
+
+**Import:** `import { CodePanel } from '@urbicon-ui/docs';`
+
+### Variants
+- size: lg, md, sm (default: md)
+
+### Api
+| Prop | Type | Required | Default | Description |
+| --- | --- | :---: | --- | --- |
+| code | `string` | yes |  | Source code string to display with syntax highlighting. |
+| ...CodePanelVariantProps | `VariantProps` | no |  | Styling variants from CodePanelVariantProps |
+| class | `string` | no |  | Extra classes merged onto the root element. |
+| expanded | `boolean` | no |  | Controlled expanded state. When omitted, the panel manages its own state. |
+| language | `string` | no | 'svelte' | Language for syntax highlighting and the toolbar language tag. |
+| onToggle | `() => void` | no |  | Called when the toggle button is clicked. Required when `expanded` is controlled. |
+| slotClasses | `Partial<Record<CodePanelSlotName, string>>` | no |  | Per-slot class overrides for internal elements. |
+| unstyled | `boolean` | no |  | Remove all default tv styles from internal slots. |
+| size | `'lg' | 'md' | 'sm'` | no | md | Controls the dimensions, padding, and text size of the CodePanel. Affects the component's physical footprint. Available options: lg, md, sm. |
+
+Inherited from:
+- CodePanelVariantProps (external)

package/content/docs/components/docs-layout/llm.txt

@@ -0,0 +1,61 @@
+
+---
+
+## DocsLayout
+Standard documentation page layout with optional table of contents.
+Provides a responsive two-column layout with a mobile ToC fallback.
+
+When `breadcrumbs` is provided, the layout uses a collapsing-hero pattern:
+a unified sticky bar shows breadcrumbs + code toggle initially, then
+transitions to a compact bar with title + scrollspy when the header
+scrolls out of view.
+
+**Import:** `import { DocsLayout } from '@urbicon-ui/docs';`
+
+### Examples
+```svelte
+<DocsLayout
+  title="Badge"
+  description="Status and labels"
+  breadcrumbs={[
+    { label: 'Blocks', href: '/blocks' },
+    { label: 'Primitives', href: '/blocks/primitives' }
+  ]}
+  showToc
+  navigation={nav}
+>
+  <Section id="examples">...</Section>
+</DocsLayout>
+```
+
+### Variants
+- centered: true (default: false)
+- maxWidth: 2xl, 7xl, lg, md, sm, xl (default: lg)
+- sidebar: true (default: false)
+
+### Api
+| Prop | Type | Required | Default | Description |
+| --- | --- | :---: | --- | --- |
+| ...DocsLayoutVariantProps | `VariantProps` | no |  | Styling variants from DocsLayoutVariantProps |
+| breadcrumbs | `BreadcrumbItem[]` | no |  | Structured breadcrumb trail (ancestors only, title is appended automatically). Enables the collapsing-hero sticky bar layout. |
+| children | `Snippet` | no |  | Content to render inside the DocsLayout component |
+| class | `string` | no |  | Extra classes merged onto the root container. |
+| description | `string` | no |  | Short description rendered below the title. |
+| navigation | `Array<{ id: string; title: string; order?: number }>` | no |  | Navigation items for the table of contents. |
+| related | `RelatedLink[]` | no |  | Optional related-links list — passed through to the TableOfContents as a `// RELATED` block below the page sections. Each entry needs a pre-resolved `href`; the layout does not call `resolve()` on it. |
+| showCodeToggle | `boolean` | no |  | Show the global code-visibility toggle for collapsing all code examples. Default: true. |
+| showToc | `boolean` | no |  | Show a sticky table of contents sidebar on desktop and a collapsible one on mobile. |
+| slotClasses | `Partial<Record<'container' | 'wrapper' | 'main' | 'header' | 'title' | 'subtitle' | 'content' | 'stickyBar' | 'pageToolbar', string>>` | no |  | Per-slot class overrides. |
+| sourceHref | `string` | no |  | GitHub blob URL for the component's source file — rendered as a `source ↗` link next to the stability badge when present. |
+| stability | `'experimental' | 'beta' | 'stable' | 'deprecated'` | no |  | Editorial stability badge — drives the `[STABLE]` / `[BETA]` / etc. stamp above the page title. When omitted, no badge renders; the default is applied upstream in docs-gen, so component pages receive `'stable'` automatically via `componentData?.stability`. |
+| title | `string` | no |  | Page title rendered as an h1 in the header area. |
+| unstyled | `boolean` | no |  | Remove all default tv styles. |
+| centered | `'true'` | no | false | Controls the centered behavior and appearance of the DocsLayout component. Available options: true. |
+| maxWidth | `'2xl' | '7xl' | 'lg' | 'md' | 'sm' | 'xl'` | no | lg | Controls the maxWidth behavior and appearance of the DocsLayout component. Available options: 2xl, 7xl, lg, and 3 more. |
+| sidebar | `'true'` | no | false | Controls the sidebar behavior and appearance of the DocsLayout component. Available options: true. |
+
+Inherited from:
+- DocsLayoutVariantProps (external)
+
+### Slots (slotClasses keys)
+`container`, `wrapper`, `main`, `header`, `title`, `subtitle`, `content`, `stickyBar`, `pageToolbar`

package/content/docs/components/info-card/llm.txt

@@ -0,0 +1,31 @@
+
+---
+
+## InfoCard
+Simple memo-style card for inline callouts or notes within docs content.
+
+**Import:** `import { InfoCard } from '@urbicon-ui/docs';`
+
+### Examples
+```svelte
+<InfoCard title="Tip" icon="lightbulb">Use variants to change tone.</InfoCard>
+```
+
+### Variants
+- intent: api, danger, example, info, neutral, playground, primary, secondary, success, warning (default: info)
+- size: lg, md, sm (default: md)
+
+### Api
+| Prop | Type | Required | Default | Description |
+| --- | --- | :---: | --- | --- |
+| ...InfoCardVariantProps | `VariantProps` | no |  | Styling variants from InfoCardVariantProps |
+| children | `Snippet` | no |  | Content to render inside the InfoCard component |
+| class | `string` | no |  | Additional CSS classes to apply to the InfoCard component |
+| href | `string` | no |  | Render the card as a link to this URL. Falls back to a plain `<div>` when omitted. |
+| icon | `string` | no |  | Icon property for the InfoCard component |
+| title | `string` | no |  | Title property for the InfoCard component |
+| intent | `'api' | 'danger' | 'example' | 'info' | 'neutral' | 'playground' | 'primary' | 'secondary' | 'success' | 'warning'` | no | info | Controls the color theme and semantic meaning of the InfoCard. Affects the overall appearance and user perception. Available options: api, danger, example, and 7 more. |
+| size | `'lg' | 'md' | 'sm'` | no | md | Controls the dimensions, padding, and text size of the InfoCard. Affects the component's physical footprint. Available options: lg, md, sm. |
+
+Inherited from:
+- InfoCardVariantProps (external)

package/content/docs/components/playground-configurator/llm.txt

@@ -0,0 +1,49 @@
+
+---
+
+## PlaygroundConfigurator
+Interactive playground configurator for component documentation.
+Renders a live preview, control panel for props, and generated code block.
+
+**Import:** `import { PlaygroundConfigurator } from '@urbicon-ui/docs';`
+
+### Examples
+```svelte
+<PlaygroundConfigurator
+  componentName="Button"
+  controls={controls}
+  values={values}
+>
+  {#snippet children(vals)}
+    <Button {...vals}>Click me</Button>
+  {/snippet}
+</PlaygroundConfigurator>
+```
+
+### Api
+| Prop | Type | Required | Default | Description |
+| --- | --- | :---: | --- | --- |
+| children | `Snippet<[Record<string, any>]>` | yes |  | Render snippet receiving the current values map. The argument is typed loosely (`Record<string, any>`) so consumers can spread it onto child components without type-asserting each variant key — the trade-off is that direct property access inside the snippet is also `any`. Use the `values` prop type for typed access.  The `any` here is a pragmatic exception to the project-wide ban: it enables docs-page playgrounds (`<Component {...values} />`) to compile without forcing every consumer to mirror the full prop union locally. |
+| controls | `ControlDefinition[]` | yes |  | Control definitions that drive the props panel (dropdown, toggle, text, etc.). |
+| values | `TValues` | yes |  | Current control values. Supports `bind:values` for two-way binding. |
+| ...HTMLAttributes<HTMLElement> | `HTMLAttributes` | no |  | HTML attributes (excluding: 'children') |
+| ...PlaygroundConfiguratorVariantProps | `VariantProps` | no |  | Styling variants from PlaygroundConfiguratorVariantProps |
+| class | `string` | no |  | Extra CSS classes merged onto the root element. |
+| codeGenerator | `(values: TValues) => string` | no |  | Custom code generator. Falls back to auto-generated Svelte tag syntax. |
+| componentName | `string` | no |  | Component name used in the auto-generated code output. |
+| onValuesChange | `(values: TValues) => void` | no |  | Fires after any control value changes with the full values map. |
+| propDocs | `Record<string, string>` | no |  | Hand-written prop descriptions (from JSDoc). Shown as tooltip behind an info icon. |
+| showHeader | `boolean` | no |  | Show the title/subtitle header above the playground. |
+| size | `'sm' | 'md' | 'lg'` | no |  | Controls the density of the playground layout – padding, grid columns, and text size. |
+| slotClasses | `Partial<Record<'root' | 'header' | 'title' | 'subtitle' | 'container' | 'preview' | 'previewContent' | 'controlsPanel' | 'controlsHeader' | 'controlsGrid' | 'controlItem' | 'controlLabel' | 'controlControl' | 'controlControlCompact' | 'controlHint' | 'actionsBar' | 'helpToggle' | 'codePanel' | 'codeToolbar' | 'codeDisplay', string>>` | no |  | Per-slot class overrides for internal elements. |
+| subtitle | `string` | no |  | Descriptive text below the title. |
+| title | `string` | no |  | Heading text above the playground panel. |
+| unstyled | `boolean` | no |  | Strip all default tv() styles from internal slots. |
+| variantKeys | `string[]` | no |  | Prop names originating from tailwind-variants. Shown with a "V" indicator. |
+
+Inherited from:
+- Omit<PlaygroundConfiguratorVariantProps, 'size'> (omit-pattern)
+- Omit<HTMLAttributes<HTMLElement>, 'children'> (omit-pattern)
+
+### Slots (slotClasses keys)
+`root`, `header`, `title`, `subtitle`, `container`, `preview`, `previewContent`, `controlsPanel`, `controlsHeader`, `controlsGrid`, `controlItem`, `controlLabel`, `controlControl`, `controlControlCompact`, `controlHint`, `actionsBar`, `helpToggle`, `codePanel`, `codeToolbar`, `codeDisplay`

package/content/docs/components/section/llm.txt

@@ -0,0 +1,46 @@
+
+---
+
+## Section
+Content section with title/subtitle, badges, and semantic footer.
+
+**Import:** `import { Section } from '@urbicon-ui/docs';`
+
+### Examples
+```svelte
+<Section id="usage" title="Usage" subtitle="Quick start">
+  <p>Install and import the component.</p>
+</Section>
+```
+
+### Variants
+- intent: default, hero, primary, secondary (default: default)
+- size: lg, md, sm, xl (default: lg)
+- centered: false, true (default: false)
+
+### Api
+| Prop | Type | Required | Default | Description |
+| --- | --- | :---: | --- | --- |
+| id | `string` | yes |  | Section ID for navigation anchors |
+| ...SectionVariantProps | `VariantProps` | no |  | Styling variants from SectionVariantProps |
+| badges | `Array<{
+    text: string;
+    variant?: 'soft' | 'filled';
+    intent?: 'primary' | 'secondary' | 'success' | 'warning' | 'danger';
+  }>` | no |  | Badges property for the Section component |
+| children | `Snippet` | no |  | Main content snippet |
+| class | `string` | no |  | Custom CSS class for the section element |
+| footerSnippet | `Snippet` | no |  | Optional footer snippet (renders a semantic <footer>) |
+| headingLevel | `1 | 2 | 3 | 4 | 5 | 6` | no | 2 | Heading level for the section title, clamped to 1..6 |
+| marker | `string` | no |  | Optional editorial marker before the title (e.g. `"01"` renders as a quieter monospace stamp). |
+| meta | `string` | no |  | Optional right-aligned monospace meta information in the title row (e.g. `"20 props"`, `"6 recipes"`). Renders as an editorial counter next to the title with `font-meta`, so the information stays visually subordinate to the section title. Lighter editorial polish (cluster A.3). |
+| subtitle | `string` | no |  | Subtitle text (property) |
+| subtitleSnippet | `Snippet` | no |  | Custom subtitle snippet (overrides subtitle prop) |
+| title | `string` | no |  | Title text (property) |
+| titleSnippet | `Snippet` | no |  | Custom title snippet (overrides title prop) |
+| intent | `'default' | 'hero' | 'primary' | 'secondary'` | no | default | Controls the color theme and semantic meaning of the Section. Affects the overall appearance and user perception. Available options: default, hero, primary, secondary. |
+| size | `'lg' | 'md' | 'sm' | 'xl'` | no | lg | Controls the dimensions, padding, and text size of the Section. Affects the component's physical footprint. Available options: lg, md, sm, xl. |
+| centered | `'false' | 'true'` | no | false | Controls the centered behavior and appearance of the Section component. Available options: false, true. |
+
+Inherited from:
+- SectionVariantProps (external)

package/content/docs/components/table-of-contents/llm.txt

@@ -0,0 +1,48 @@
+
+---
+
+## TableOfContents
+TableOfContents component
+
+**Import:** `import { TableOfContents } from '@urbicon-ui/docs';`
+
+### Examples
+```svelte
+<TableOfContents
+  navigation={[
+    { id: 'usage', title: 'Usage' },
+    { id: 'api', title: 'API', children: [{ id: 'props', title: 'Props' }] }
+  ]}
+/>
+```
+
+### Variants
+- position: left, right (default: right)
+- width: lg, md, sm (default: md)
+
+### Api
+| Prop | Type | Required | Default | Description |
+| --- | --- | :---: | --- | --- |
+| navigation | `Array<{
+    id: string;
+    title: string;
+    order?: number;
+    href?: string;
+    children?: Array<{ id: string; title: string; order?: number; href?: string }>;
+  }>` | yes |  | Navigation items with optional nested children. |
+| ...TableOfContentsVariantProps | `VariantProps` | no |  | Styling variants from TableOfContentsVariantProps |
+| class | `string` | no |  | Extra classes merged onto the root aside element. |
+| related | `RelatedLink[]` | no |  | Optional Editorial `// RELATED` block rendered below the main nav. Each entry needs a pre-resolved `href` (the TOC does not call `resolve()`, mirroring the existing nav behaviour). When omitted, the related block does not render at all. |
+| showCodeToggle | `boolean` | no | true | Render the Editorial `// CODE` block at the bottom of the TOC, hosting the global show-/hide-all-code toggle. Requires a host page that provided a `CodeVisibilityStore` via context — the block silently skips itself if no store is found, so callers outside of `DocsLayout` don't have to know about it. |
+| slotClasses | `Partial<Record<'aside' | 'title' | 'nav' | 'relatedTitle' | 'relatedNav' | 'relatedLink' | 'codeTitle' | 'codeToggle', string>>` | no |  | Per-slot class overrides. |
+| title | `string` | no |  | Heading rendered above the nav links. |
+| trackScroll | `boolean` | no |  | Enable scroll-based active section tracking. |
+| unstyled | `boolean` | no |  | Remove all default tv styles. |
+| position | `'left' | 'right'` | no | right | Controls the position behavior and appearance of the TableOfContents component. Available options: left, right. |
+| width | `'lg' | 'md' | 'sm'` | no | md | Controls the width behavior and appearance of the TableOfContents component. Available options: lg, md, sm. |
+
+Inherited from:
+- TableOfContentsVariantProps (external)
+
+### Slots (slotClasses keys)
+`aside`, `title`, `nav`, `relatedTitle`, `relatedNav`, `relatedLink`, `codeTitle`, `codeToggle`

package/content/docs/components/types-reference/llm.txt

@@ -0,0 +1,38 @@
+
+---
+
+## TypesReference
+Displays expandable type definitions extracted from component source,
+with inline code blocks, literal value badges, and cross-links to the API Reference.
+
+**Import:** `import { TypesReference } from '@urbicon-ui/docs';`
+
+### Examples
+```svelte
+<TypesReference
+  types={componentData.types}
+  title="Type Definitions"
+  description="Local types used by this component."
+/>
+```
+
+### Api
+| Prop | Type | Required | Default | Description |
+| --- | --- | :---: | --- | --- |
+| types | `LocalTypeDef[]` | yes |  | Array of type definitions to display. |
+| ...HTMLAttributes<HTMLElement> | `HTMLAttributes` | no |  | HTML attributes (excluding: 'children') |
+| ...TypesReferenceVariantProps | `VariantProps` | no |  | Styling variants from TypesReferenceVariantProps |
+| class | `string` | no |  | Extra CSS classes merged onto the root section element. |
+| description | `string` | no |  | Descriptive text below the title. |
+| emptyState | `Snippet` | no |  | Optional snippet rendered below the table when no types match the filter. |
+| size | `'sm' | 'md' | 'lg'` | no |  | Controls the density – text size, padding, badge size. |
+| slotClasses | `Partial<Record<'root' | 'header' | 'title' | 'description' | 'card' | 'toolbar' | 'codeBlock' | 'literalValues' | 'literalBadge' | 'usedBySection' | 'usedByLink', string>>` | no |  | Per-slot class overrides for internal elements. |
+| title | `string` | no |  | Section heading text. |
+| unstyled | `boolean` | no |  | Strip all default tv() styles from internal slots. |
+
+Inherited from:
+- Omit<TypesReferenceVariantProps, 'size'> (omit-pattern)
+- Omit<HTMLAttributes<HTMLElement>, 'children'> (omit-pattern)
+
+### Slots (slotClasses keys)
+`root`, `header`, `title`, `description`, `card`, `toolbar`, `codeBlock`, `literalValues`, `literalBadge`, `usedBySection`, `usedByLink`