# @ziyarago/ui

> ZiyaraGo UI — glass design system for Umrah and Hajj products. OKLCH tokens, two palettes, dark and light, RTL, Thmanyah. One framework-neutral core with Vue 3, Nuxt and React adapters, 184 components and 17 page templates.

Version 0.6.1. Docs: https://ziyara.vip . Manifest (machine readable): https://ziyara.vip/manifest.json

## Setup
- import { UiButton } from '@ziyarago/ui/vue'
- import { UiButton } from '@ziyarago/ui/react'
- modules: ['@ziyarago/ui/nuxt']
- import '@ziyarago/ui/style.css'
- import { useUiTheme } from '@ziyarago/ui/theme'

## Conventions
- Component names are Ui<Name>. Vue and React share names and props.
- Controlled inputs: Vue v-model, React modelValue + onChange(value). Components that read value/page use :value + @change (React onChange).
- Slots: Vue named slots; React props with the same name, default slot = children.
- Sizes: size="xs|sm|md|lg|xl" (default md) where documented.
- Style only with tokens: var(--zg-*). Theme: data-theme dark|light, data-palette gold|tamam, dir ltr|rtl.
- Cards: variant default|inverse|gradient (tone, intensity soft|vivid).

## UiHeading  (typography)
Semantic heading h1-h6 with a responsive type scale; use for page and section titles.
Props:
- `level`: 1 | 2 | 3 | 4 | 5 | 6 = 2. HTML heading level (h1-h6). Clamped to 1-6.
- `size`: 'xs' | 'sm' | 'md' | 'lg' | 'xl' | '2xl' = "lg". Visual size, independent of the semantic level.
- `brand`: boolean = false. Colors the heading with the brand text color.
Slots:
- default: Heading content.
Notes:
- Pick level for document structure and size for looks; they are independent.

## UiText  (typography)
Body text paragraph (or any inline/block tag via as) with size, tone and truncation.
Props:
- `as`: string = "p". HTML tag to render, for example span, div, label.
- `size`: 'xs' | 'sm' | 'md' | 'lg' | 'xl' = "md". Font size: xs 12px, sm 14px, md 16px, lg 18px, xl 20px.
- `tone`: 'muted' | 'subtle' | 'brand'. Text color. Omit for the primary text color.
- `bold`: boolean = false. Semi-bold weight.
- `truncate`: boolean = false. Single line with ellipsis overflow.
Slots:
- default: Text content.
Notes:
- truncate needs a parent with a constrained width (for example min-width: 0 in a flex row).

## UiCode  (typography)
Code block with a header (title or language) and a copy button; use for snippets and commands.
Props:
- `code` (required): string. Source text shown in the block and copied by the button.
- `title`: string. Header label. Takes priority over language.
- `language`: string. Header label when no title is given. Display only, no syntax highlighting.
- `size`: 'xs' | 'sm' | 'md' | 'lg' | 'xl' = "md". Block padding and font size.
Notes:
- The header falls back to the text "code" when neither title nor language is set.
- No syntax highlighting: the code is rendered as plain monospace text.

## UiKbd  (typography)
Keyboard key cap for shortcuts such as Ctrl or K.
Props:
- `size`: 'xs' | 'sm' | 'md' | 'lg' | 'xl' = "md". Key cap size.
Slots:
- default: Key label.
Notes:
- Render one Kbd per key and combine them in a row for chords.

## UiLink  (typography)
Styled anchor for in-text and standalone links, with optional external-link behavior.
Props:
- `href`: string = "#". Link target.
- `external`: boolean = false. Opens in a new tab with rel="noopener noreferrer" and shows an external-link icon.
- `plain`: boolean = false. Removes the underline styling.
- `size`: 'xs' | 'sm' | 'md' | 'lg' | 'xl' = "md". Font size relative to the surrounding text (0.8em to 1.25em).
Slots:
- default: Link content.
Events:
- click: Native click event.
Notes:
- Without href the link points to "#"; for SPA routing use onClick and prevent default.

## UiBox  (layout)
Generic container with optional padding and glass background.
Props:
- `p`: number | string. Padding. Numbers are pixels, strings any CSS value.
- `glass`: boolean = false. Applies the glass surface style.
- `as`: string = "div". HTML tag to render.
- `style`: Record<string, string | number>. Inline styles merged over the component styles.
Slots:
- default: Box content.

## UiCenter  (layout)
Centers its children horizontally and vertically.
Props:
- `as`: string = "div". HTML tag to render.
- `style`: Record<string, string | number>. Inline styles merged over the component styles.
Slots:
- default: Centered content.

## UiHStack  (layout)
Horizontal flex row with a configurable gap.
Props:
- `gap`: number | string = 12. Gap between children. Numbers are pixels, strings any CSS length.
- `align`: string. CSS align-items value, for example center, flex-start, stretch.
- `justify`: string. CSS justify-content value, for example space-between, center.
- `wrap`: boolean = false. Allows children to wrap onto several lines.
- `as`: string = "div". HTML tag to render.
- `style`: Record<string, string | number>. Inline styles merged over the component styles.
Slots:
- default: Items laid out in a row.

## UiVStack  (layout)
Vertical flex column with a configurable gap.
Props:
- `gap`: number | string = 12. Gap between children. Numbers are pixels, strings any CSS length.
- `align`: string. CSS align-items value, for example center, flex-start, stretch.
- `justify`: string. CSS justify-content value, for example space-between, center.
- `wrap`: boolean = false. Allows children to wrap onto several lines.
- `as`: string = "div". HTML tag to render.
- `style`: Record<string, string | number>. Inline styles merged over the component styles.
Slots:
- default: Items laid out in a column.

## UiGrid  (layout)
CSS grid with a fixed column count or auto-fit columns of a minimum width.
Props:
- `cols`: number. Fixed number of equal columns. When set, min is ignored.
- `min`: number | string = 240. Minimum column width for auto-fit layout (used when cols is not set).
- `gap`: number | string = 16. Gap between cells. Numbers are pixels, strings any CSS length.
- `as`: string = "div". HTML tag to render.
- `style`: Record<string, string | number>. Inline styles merged over the component styles.
Slots:
- default: Grid items.

## UiDivider  (layout)
Horizontal separator line with an optional centered label.
Props:
- `label`: string. Text shown in the middle of the line.
- `size`: 'xs' | 'sm' | 'md' | 'lg' | 'xl' = "md". Label font size and spacing.
Notes:
- Renders role="separator".

## UiScrollArea  (layout)
Vertically scrollable container with a max height and styled scrollbar.
Props:
- `maxHeight`: string = "240px". CSS max-height; content scrolls beyond it. Must be a string with a unit.
Slots:
- default: Scrollable content.

## UiSplitLayout  (layout)
Two-column layout with configurable column widths; use for master-detail or side-by-side content.
Props:
- `columns`: string = "1fr 1fr". CSS grid-template-columns value, for example "280px 1fr".
Slots:
- left: First column. Falls back to the first child.
- right: Second column. Falls back to the second child.
Notes:
- Exactly two columns; extra children beyond the second are ignored.

## UiAppShell  (layout)
Application frame with a top or side navigation and a main content area.
Props:
- `nav`: 'top' | 'side' = "top". Navigation placement: TopNav or SideNav.
- `brand`: VNode | string. Brand/logo content shown in the navigation.
- `items`: { value: string; label: string; icon?: string }[]. Navigation items, passed to TopNav or SideNav.
- `value`: string. Value of the active navigation item. Changed via the change event.
- `actions`: VNode. Right side of the top navigation (nav="top" only).
- `collapsed`: boolean. Controlled collapsed state of the side navigation. Uncontrolled (internal state, initially false) when omitted.
- `collapsible`: boolean = true. Shows the collapse toggle in the side navigation. Set false to hide it.
- `collapseLabel`: string. Label of the collapse toggle in the side navigation.
- `frame`: boolean = false. Renders the shell as a framed block instead of full viewport (useful in previews).
Slots:
- default: Main page content.
- footer: Bottom area of the side navigation (nav="side" only).
Events:
- change: Called with the value of the clicked navigation item.
- collapse: Called with the new collapsed boolean when the toggle is pressed.
Notes:
- The footer slot and collapse props apply only to nav="side".

## UiPageHeader  (layout)
Page title block with optional breadcrumbs, subtitle and an actions area.
Props:
- `title` (required): string. Page title (rendered as h1).
- `subtitle`: string. Secondary text below the title.
- `crumbs`: { label: string; href?: string }[]. Breadcrumb items shown above the title.
- `size`: 'xs' | 'sm' | 'md' | 'lg' | 'xl' = "md". Title and subtitle size.
Slots:
- actions: Right side of the header, usually buttons.

## UiAuthLayout  (layout)
Centered card layout for sign-in and sign-up pages.
Props:
- `title` (required): string. Heading inside the card.
- `subtitle`: string. Text below the title.
- `logo`: VNode. Logo element shown at the top of the card.
- `style`: Record<string, string | number>. Inline styles merged over the component styles.
Slots:
- default: Card body, usually a form.

## UiSettingsSection  (layout)
Settings block with a title and description on the left and fields below.
Props:
- `title` (required): string. Section title.
- `description`: string. Helper text under the title.
- `size`: 'xs' | 'sm' | 'md' | 'lg' | 'xl' = "md". Padding, title and field spacing.
Slots:
- default: Fields and controls of the section.

## UiLiquidGlass  (layout)
Frosted liquid-glass panel with adjustable corner radius and blur.
Props:
- `radius`: number | string = 24. Corner radius. Numbers are pixels.
- `blur`: number | string = 18. Backdrop blur radius. Numbers are pixels.
- `size`: 'xs' | 'sm' | 'md' | 'lg' | 'xl' = "md". Inner padding.
Slots:
- default: Panel content.
Notes:
- Backdrop blur is visible only over a colorful or image background.

## UiFooter  (layout)
Page footer with a copyright line and a row of links.
Props:
- `copyright`: string = "© 2026 ZiyaraGo". Copyright text.
- `links`: { label: string; href?: string }[] = "[]". Footer links; href defaults to "#".
- `size`: 'xs' | 'sm' | 'md' | 'lg' | 'xl' = "md". Padding and font size.
Slots:
- default: Extra content after the links.

## UiSortable  (layout)
Drag-and-drop reorderable list with grip handles and up/down buttons.
Props:
- `items` (required): { id?: string | number; label: string }[] = "[]". Items in current order. id is used as the key, falling back to the index.
- `render`: (item, index) => VNode. Custom item renderer. Defaults to the bold item label.
- `size`: 'xs' | 'sm' | 'md' | 'lg' | 'xl' = "md". Row padding, gap and font size.
Events:
- change: Called with the reordered items array after a drop or up/down click.
Notes:
- Controlled: the parent must store the array from change and pass it back as items.
- Keyboard-friendly reordering is available through the up/down buttons.

## UiPortal  (layout)
Renders its children outside the component tree, for example into document.body.
Props:
- `to`: string | HTMLElement. Target element or CSS selector. The adapter default (body) is used when omitted.
Slots:
- default: Content to teleport.
Notes:
- Renders nothing when the framework adapter provides no portal.

## UiButton  (actions)
Primary action control with visual variants, tones, sizes, icons and a loading state.
Props:
- `variant`: 'primary' | 'secondary' | 'ghost' | 'danger' | 'inverse' | 'tonal' | 'outlined' | 'text' | 'elevated' = "secondary". Visual emphasis. primary is the main call to action, danger is destructive, inverse is for dark surfaces.
- `tone`: 'brand' | 'sky' | 'success' | 'warning' | 'danger' | 'neutral'. Accent color applied to tonal, outlined, text and elevated variants.
- `size`: 'xs' | 'sm' | 'md' | 'lg' | 'xl' = "md". Button height: xs 28px, sm 32px, md 40px, lg 48px, xl 56px.
- `icon`: string. Icon shown before the label.
- `iconRight`: string. Icon shown after the label.
- `loading`: boolean = false. Shows a spinner instead of the icon and disables the button.
- `disabled`: boolean = false. Blocks interaction and dims the button.
- `block`: boolean = false. Stretches the button to the full width of its container.
- `type`: 'button' | 'submit' | 'reset' = "button". Native button type. Use submit inside a form.
- `iconOnly`: boolean = false. Square button (width equals height) with no horizontal padding, for a lone icon. Pass an aria-label.
- `title`: string. Native tooltip text.
Slots:
- default: Button label.
Events:
- click: Native click event. Not fired while disabled or loading.
Notes:
- Renders type="button" unless type is set, so it never submits a form by itself.

## UiIconButton  (actions)
Square button with only an icon; use for toolbars and compact actions.
Props:
- `icon` (required): string. Icon name.
- `label` (required): string. Accessible name (aria-label). Required because there is no visible text.
- `size`: 'xs' | 'sm' | 'md' | 'lg' | 'xl' = "md". Button size: xs 28px, sm 32px, md 40px, lg 48px, xl 56px.
- `ghost`: boolean = false. Transparent background until hover.
Events:
- click: Native click event.

## UiPressable  (actions)
Unstyled pressable wrapper that makes any content a button with press feedback.
Props:
- `as`: string = "button". HTML tag. type="button" is set only when this is button.
- `label`: string. Accessible name (aria-label).
- `disabled`: boolean = false. Blocks interaction.
Slots:
- default: Pressable content.
Events:
- click: Native click event.
Notes:
- For a non-button tag add role and keyboard handling yourself.

## UiFab  (actions)
Floating action button for the main action of a screen; extended when a label is given.
Props:
- `icon`: string = "plus". Icon name.
- `label`: string. Text next to the icon (extended FAB) and the accessible name.
- `size`: 'xs' | 'sm' | 'md' | 'lg' | 'xl' = "md". Button height: xs 36px, sm 44px, md 56px, lg 64px, xl 72px.
Events:
- click: Native click event.
Notes:
- Always pass label: it is the accessible name. Without it the button falls back to the icon name as aria-label (for example "plus"), which is rarely a good description.

## UiCopyButton  (actions)
Button that copies a value to the clipboard and briefly confirms with a check icon, or reports a failure.
Props:
- `value` (required): string. Text copied to the clipboard.
- `label`: string. Button text. Defaults to "Copy", then "Copied" for 1.5s after a click.
- `variant`: 'primary' | 'secondary' | 'ghost' | 'danger' | 'inverse' | 'tonal' | 'outlined' | 'text' | 'elevated' = "secondary". Button variant, same values as Button.
- `size`: 'xs' | 'sm' | 'md' | 'lg' | 'xl' = "sm". Button size.
Events:
- copy: Called with the value after it was written to the clipboard.
- error: Called with the error when the clipboard is unavailable or rejects the write. The button turns red with "Copy failed" for 1.5s.
Notes:
- Needs a secure context (https or localhost) for navigator.clipboard. The result ("Copied" or "Copy failed") is announced through an aria-live region.

## UiToggleGroup  (actions)
Group of toggle buttons with single or multiple selection, optionally icon-only.
Props:
- `options` (required): { value: string; label: string; icon?: string }[] = "[]". Buttons to render. label is also used as the tooltip.
- `modelValue`: string | string[] [v-model]. Selected value, or array of values when multiple.
- `multiple`: boolean = false. Allows several pressed buttons; modelValue becomes an array.
- `iconOnly`: boolean = false. Hides labels and shows only icons.
- `allowEmpty`: boolean = false. Single mode only: clicking the pressed button deselects it and emits null.
- `size`: 'xs' | 'sm' | 'md' | 'lg' | 'xl' = "md". Control size.
Events:
- change: Called with the new value (string), null when deselected with allowEmpty, or the new array when multiple.
Notes:
- Each button exposes aria-pressed. In single mode clicking the active option keeps it selected.

## UiSegmentedControl  (actions)
Segmented switch for choosing exactly one of a few options.
Props:
- `items` (required): { value: string; label: string; icon?: string; disabled?: boolean }[] = "[]". Segments to render. icon is an icon name; disabled: true dims one segment.
- `modelValue`: string [v-model]. Value of the selected segment.
- `size`: 'xs' | 'sm' | 'md' | 'lg' | 'xl' = "md". Control size. sm and md also have a dedicated compact style.
- `block`: boolean = false. Stretches the control to the container width with equal-width segments.
- `iconOnly`: boolean = false. Hides labels of segments that have an icon; the label stays as tooltip and aria-label.
- `ariaLabel`: string. Accessible name of the group.
Events:
- change: Called with the value of the clicked segment.

## UiFilterChips  (actions)
Row of selectable filter chips with single or multiple selection.
Props:
- `items` (required): { value: string; label: string }[] = "[]". Chips to render.
- `modelValue`: string | string[] [v-model]. Selected value, or array of values when multi.
- `multi`: boolean = false. Allows several selected chips; modelValue becomes an array.
- `size`: 'xs' | 'sm' | 'md' | 'lg' | 'xl' = "md". Chip size.
Events:
- change: Called with the new value, or the new array when multi. Toggles chips off in multi mode only.

## UiChip  (actions)
Compact label with optional icon and remove button; use for statuses, filters and attributes.
Props:
- `variant`: 'tonal' | 'outlined' | 'solid' = "tonal". Visual style.
- `tone`: 'brand' | 'sky' | 'success' | 'warning' | 'danger' | 'neutral' = "brand". Accent color. Unknown values fall back to brand.
- `size`: 'xs' | 'sm' | 'md' | 'lg' | 'xl' = "md". Chip height: xs 22px, sm 26px, md 32px, lg 38px, xl 46px.
- `pill`: boolean = false. Fully rounded corners.
- `icon`: string. Icon shown before the label.
Slots:
- default: Chip label.
Events:
- close: Canonical. Called when the remove button is clicked. The button is shown only when close or remove is provided.
- remove: Alias of close, matching Tag.

## UiTag  (actions)
Small pill label, optionally removable; use for keywords and selected values.
Props:
- `size`: 'xs' | 'sm' | 'md' | 'lg' | 'xl' = "md". Tag height: xs 22px, sm 24px, md 28px, lg 34px, xl 40px.
Slots:
- default: Tag label.
Events:
- remove: Called when the x button is clicked. The button is shown only when remove or close is provided.
- close: Alias of remove, matching Chip. Use one name across both components in your app (close is the canonical one).

## UiBadge  (actions)
Status badge with a colored tone and optional dot.
Props:
- `tone`: 'brand' | 'success' | 'warning' | 'danger' | 'info' | 'inverse'. Color. inverse is a solid high-contrast badge (dark on light themes, light on dark). Omit for the neutral style.
- `dot`: boolean = false. Shows a status dot before the content.
- `shape`: 'pill' | 'square' = "pill". square uses small rounded corners instead of a full pill.
- `size`: 'xs' | 'sm' | 'md' | 'lg' | 'xl' = "md". Badge height: xs 18px, sm 20px, md 24px, lg 28px, xl 32px.
Slots:
- default: Badge content.
Notes:
- Badge uses info for blue; Chip and Button use the tone name sky instead.

## UiActionRail  (actions)
Floating vertical or horizontal rail of icon buttons with a highlighted active item.
Props:
- `items` (required): { value?: string; icon?: string; label?: string; separator?: boolean }[] = "[]". Rail entries. An item with separator: true renders a divider instead of a button.
- `value`: string. Value of the active item. Changed via the change event.
- `size`: 'xs' | 'sm' | 'md' | 'lg' | 'xl' = "md". Button size inside the rail.
Events:
- change: Called with the value of the clicked item.
Notes:
- Items other than the active one are shown as ghost buttons; label is the accessible name.

## UiActionCard  (actions)
Card with a title and built-in collapse, refresh and remove controls.
Props:
- `title` (required): string. Card title.
- `subtitle`: string. Text under the title.
- `collapsed`: boolean. Controlled collapsed state. When omitted the card keeps it internally.
- `loading`: boolean. Controlled refresh spinner. When omitted, Refresh shows the spinner for 1.8s by itself.
- `size`: 'xs' | 'sm' | 'md' | 'lg' | 'xl' = "md". Card padding and font size.
Slots:
- default: Card body. Hidden while collapsed.
Events:
- collapse: Called with the new collapsed boolean when the collapse button is clicked.
- refresh: Refresh button clicked. Pass loading to show your own spinner.
- remove: Remove button clicked; the card hides itself afterwards.
Notes:
- With collapsed set, update it from the collapse event, otherwise the card will not toggle.
- Removing hides the card until the component is remounted; also remove it from your data on the remove event.

## UiNotificationBell  (actions)
Bell icon button with an unread counter and a dropdown list of notifications.
Props:
- `items`: { id: string | number; title: string; message?: string; time?: string; read?: boolean }[] = "[]". Notifications. Items without read: true count as unread and show a dot.
- `size`: 'xs' | 'sm' | 'md' | 'lg' | 'xl' = "md". Bell button size.
Events:
- read: Called with the item id when an unread item is clicked.
- markAllRead: Called when "Mark all read" is clicked (shown while something is unread).
- select: Called with the item when any item is clicked.
Notes:
- If you handle read or markAllRead the component is controlled: it trusts only the read flags in items, so update them in your state. Without these handlers it marks items read internally.
- The dropdown opens and closes internally, and closes on outside click or Escape.

## UiTextField  (forms)
Single-line text input with label, icon, suffix, hint and error. Use for any short free-text or typed value (email, url, number as text).
Props:
- `modelValue`: string = "" [v-model]. Current value.
- `label`: string. Label shown above the control.
- `placeholder`: string. Placeholder text.
- `hint`: string. Helper text under the control. Hidden while error is set.
- `error`: string. Error message under the control. Turns the control red and is announced with role="alert".
- `type`: string = "text". Native input type: text, email, tel, url, number, date, etc.
- `icon`: string. Leading icon name.
- `suffix`: VNode | string. Trailing content inside the field (unit, button, icon).
- `variant`: 'filled' | 'underlined' | 'solo'. Alternative field style. Omit for the default outlined look.
- `density`: 'compact' | 'default' = "default". compact uses the small control height.
- `disabled`: boolean = false. Disables the control.
- `readonly`: boolean = false. Makes the input read-only.
- `required`: boolean = false. Adds a red asterisk to the label and the native required attribute (browser validation inside a form).
- `name`: string. Native name attribute of the input.
- `autocomplete`: string. Native autocomplete hint, for example "email" or "new-password".
- `min`: number | string. Native min for number, date and time types.
- `max`: number | string. Native max for number, date and time types.
- `step`: number | string. Native step for number, date and time types.
- `maxlength`: number. Maximum number of characters.
- `minlength`: number. Minimum number of characters (native validation).
- `inputmode`: string. Virtual keyboard hint: numeric, decimal, tel, email, url, search or none.
- `pattern`: string. Native validation pattern.
- `spellcheck`: boolean. Enables or disables spell checking.
- `autofocus`: boolean. Focuses the input on mount.
- `autocapitalize`: string. Native autocapitalize hint.
- `size`: 'xs' | 'sm' | 'md' | 'lg' | 'xl' = "md". Control height, font and padding scale.
Slots:
- prefix: Content before the input (icon or text). Replaces the icon prop. React: prefix prop.
- suffix: Content after the input (button, unit). Same as the suffix prop. React: suffix prop.
Events:
- change: Called with the new string on every keystroke.
- blur: Native blur of the input (Vue @blur, React onBlur).
- focus: Native focus of the input.
- keydown: Native keydown of the input; modifiers like @keydown.enter work in Vue.
- input: Native input event (after change), receives the Event.
Notes:
- Wrapped in a label, so clicking the label focuses the input.
- Native attributes (name, autocomplete, min, max, step, maxlength, inputmode, pattern ...) and the blur, focus, keydown, keyup and paste listeners are forwarded to the inner input. id, class, style, aria-* and data-* land on the root label.

## UiTextarea  (forms)
Multi-line text input. Use for comments, descriptions and other long text.
Props:
- `modelValue`: string = "" [v-model]. Current value.
- `label`: string. Label shown above the control.
- `placeholder`: string. Placeholder text.
- `hint`: string. Helper text under the control. Hidden while error is set.
- `error`: string. Error message under the control. Turns the control red and is announced with role="alert".
- `disabled`: boolean = false. Disables the control.
- `rows`: number = 4. Visible text rows.
- `maxlength`: number. Maximum number of characters.
- `readonly`: boolean = false. Makes the textarea read-only.
- `required`: boolean = false. Adds a red asterisk to the label and the native required attribute.
- `autoResize`: boolean = false. Grows with the content (CSS field-sizing: content, Chromium and Safari).
- `resize`: boolean = true. false removes the manual resize handle.
- `showCount`: boolean = false. Shows the character count under the field, as "n / maxlength" when maxlength is set.
- `name`: string. Native name attribute.
- `size`: 'xs' | 'sm' | 'md' | 'lg' | 'xl' = "md". Control height, font and padding scale.
Events:
- change: Called with the new string on every keystroke.
- input: Native input event (after change), receives the Event.
- blur: Native blur.
- focus: Native focus.

## UiNumberInput  (forms)
Numeric stepper with minus and plus buttons and a typed value. Use for quantities, guest counts and small integers.
Props:
- `modelValue`: number | null [v-model]. Current number, or null/undefined when the field is empty.
- `placeholder`: string. Shown while the field is empty.
- `min`: number. Lower bound. Default is unbounded.
- `max`: number. Upper bound. Default is unbounded.
- `step`: number = 1. Amount added or subtracted by the buttons.
- `label`: string. Label shown above the control.
- `hint`: string. Helper text under the control. Hidden while error is set.
- `error`: string. Error message under the control. Turns the control red and is announced with role="alert".
- `size`: 'xs' | 'sm' | 'md' | 'lg' | 'xl' = "md". Control height, font and padding scale.
Events:
- change: Called with the new number, or null when the field is cleared. Typed values are emitted as-is and clamped to min and max on blur; the buttons clamp immediately. Text that is not a number is not emitted and reverts to the last valid value on blur.
Notes:
- The field can be fully cleared (null); the + and - buttons start from 0 when empty.
- Decimal separators . and , are both accepted.

## UiPasswordInput  (forms)
Password field with a show/hide toggle. Use for sign-in and password change forms.
Props:
- `modelValue`: string = "" [v-model]. Current password.
- `label`: string. Label shown above the control.
- `placeholder`: string. Placeholder text.
- `hint`: string. Helper text under the control. Hidden while error is set.
- `error`: string. Error message under the control. Turns the control red and is announced with role="alert".
- `autocomplete`: string = "current-password". Native autocomplete token. Use "new-password" on sign-up and password-change forms so managers offer to generate one.
- `size`: 'xs' | 'sm' | 'md' | 'lg' | 'xl' = "md". Control height, font and padding scale.
Events:
- change: Called with the new string on every keystroke.
Notes:
- autocomplete defaults to "current-password"; pass "new-password" for sign-up forms.

## UiSearchInput  (forms)
Compact search field with a clear button and an Enter-to-search event. Use above lists and tables.
Props:
- `modelValue`: string = "" [v-model]. Current query.
- `placeholder`: string. Placeholder text. Defaults to "Search".
- `size`: 'xs' | 'sm' | 'md' | 'lg' | 'xl' = "md". Field height and font size.
Events:
- change: Called with the new query on every keystroke and with "" when cleared.
- search: Called with the current query when Enter is pressed.
Notes:
- Filtering is up to you: react to change for live search or to search for submit-on-enter.

## UiPhoneInput  (forms)
Phone field with a country code dropdown. Use for contact numbers where the dial code matters.
Props:
- `modelValue`: { code?: string; number?: string } = "{}" [v-model]. Object with the dial code (e.g. "+998") and the national number as typed.
- `countries`: { value: string | number; label: string; disabled?: boolean }[] = "[{ value: '+966', label: 'SA +966' }, { value: '+998', label: 'UZ +998' }, { value: '+7', label: 'RU +7' }, { value: '+90', label: 'TR +90' }, { value: '+20', label: 'EG +20' }]". Dial code options. value is the code, label is what the dropdown shows.
- `label`: string. Label shown above the control.
- `placeholder`: string. Placeholder of the number field. Defaults to "90 123 45 67".
- `hint`: string. Helper text under the control. Hidden while error is set.
- `error`: string. Error message under the control. Turns the control red and is announced with role="alert".
- `size`: 'xs' | 'sm' | 'md' | 'lg' | 'xl' = "md". Control height, font and padding scale.
Events:
- change: Called with a new { code, number } object when either part changes.
Notes:
- When code is missing the first entry of countries is shown but not written to the model until the user picks one.

## UiCodeInput  (forms)
One-time code input rendered as separate digit cells. Use for SMS or email verification codes.
Props:
- `modelValue`: string = "" [v-model]. Digits entered so far.
- `length`: number = 6. Number of cells and maximum digits.
- `label`: string = "Code". Accessible name of the hidden input (not rendered visibly).
- `size`: 'xs' | 'sm' | 'md' | 'lg' | 'xl' = "md". Cell size.
Events:
- change: Called with the digits only (non-digits stripped), at most length characters.
- complete: Called once with the full code when the last cell gets filled (also on paste).
Notes:
- Sets autocomplete="one-time-code" so mobile keyboards offer the SMS code.

## UiChipInput  (forms)
Input that turns typed text into removable chips. Use for tags, keywords and email lists.
Props:
- `modelValue`: string[] = "[]" [v-model]. Current chips.
- `maxItems`: number. Maximum number of chips. Extra entries are ignored.
- `label`: string. Label shown above the control.
- `placeholder`: string. Placeholder, shown only while there are no chips.
- `hint`: string. Helper text under the control. Hidden while error is set.
- `error`: string. Error message under the control. Turns the control red and is announced with role="alert".
- `size`: 'xs' | 'sm' | 'md' | 'lg' | 'xl' = "md". Control height, font and padding scale.
Events:
- change: Called with the new array when a chip is added or removed.
Notes:
- Enter or comma adds a chip, Backspace on empty input removes the last one. Duplicates are ignored.

## UiInlineEdit  (forms)
Text that turns into an input on click. Use for renaming and quick edits without a form.
Props:
- `modelValue`: string = "" [v-model]. Current text.
- `emptyText`: string = "Click to edit". Shown when the value is empty.
- `size`: 'xs' | 'sm' | 'md' | 'lg' | 'xl' = "md". Control height, font and padding scale.
Events:
- change: Called with the edited text on Enter or on the save button. Escape cancels.

## UiRichEditor  (forms)
Rich text editor with a formatting toolbar, built on contenteditable. Use for formatted descriptions and notes.
Props:
- `modelValue`: string = "" [v-model]. HTML string.
- `label`: string = "Editor". Label above the editor. Also the accessible name.
- `placeholder`: string. Placeholder shown when empty. Defaults to "Write something…".
- `sanitize`: boolean = false. Strip script, style, iframe, object, embed and similar tags plus on* and javascript: attributes from the emitted HTML, using a small allowlist sanitizer.
- `size`: 'xs' | 'sm' | 'md' | 'lg' | 'xl' = "md". Control height, font and padding scale.
Events:
- change: Called with the editor innerHTML on every edit or toolbar action (sanitized when sanitize is set).
Notes:
- The editor only rewrites its content when modelValue differs from what is already in the DOM, so the caret is kept while typing.
- sanitize is a best-effort allowlist, not a full XSS guarantee: sanitize on the server too before storing or rendering the HTML elsewhere.
- Toolbar: bold, italic, underline, strikethrough, alignment, lists, quote and code block.

## UiSelect  (forms)
Single-choice dropdown. Use when the user picks one value from a known list.
Props:
- `modelValue`: string | number [v-model]. Value of the selected option.
- `options` (required): { value: string | number; label: string; disabled?: boolean }[] = "[]". Available options. An option with disabled: true is dimmed and cannot be chosen.
- `label`: string. Label shown above the control.
- `placeholder`: string. Shown when nothing is selected. Defaults to "—".
- `hint`: string. Helper text under the control. Hidden while error is set.
- `error`: string. Error message under the control. Turns the control red and is announced with role="alert".
- `required`: boolean = false. Adds a red asterisk to the label. Does not validate.
- `name`: string. Renders a hidden input with this name and the selected value, so the control posts with a native form.
- `disabled`: boolean = false. Disables the control.
- `size`: 'xs' | 'sm' | 'md' | 'lg' | 'xl' = "md". Control height, font and padding scale.
Events:
- change: Called with the value of the chosen option.
Notes:
- The popup closes on outside click and on Escape (focus returns to the trigger).

## UiMultiSelect  (forms)
Dropdown with checkboxes for choosing several values. Use for filters and multi-valued fields.
Props:
- `modelValue`: (string | number)[] = "[]" [v-model]. Values of the selected options.
- `options`: { value: string | number; label: string; disabled?: boolean }[] = "[]". Available options. An option with disabled: true cannot be toggled.
- `label`: string. Label shown above the control.
- `placeholder`: string. Shown when nothing is selected. Defaults to "—".
- `disabled`: boolean = false. Disables the control.
- `size`: 'xs' | 'sm' | 'md' | 'lg' | 'xl' = "md". Control height, font and padding scale.
Events:
- change: Called with the new array of values after toggling an option.
Notes:
- The trigger shows "N selected"; the list stays open while picking and closes on outside click or Escape.

## UiGroupedSelect  (forms)
Single-choice dropdown with option groups under headings. Use for long lists that have natural categories.
Props:
- `modelValue`: string | number [v-model]. Value of the selected option.
- `groups`: { label: string; options: { value: string | number; label: string; disabled?: boolean }[] }[] = "[]". Groups with a heading and their options. Option values must be unique across groups. An option with disabled: true cannot be chosen.
- `label`: string. Label shown above the control.
- `placeholder`: string. Shown when nothing is selected. Defaults to "—".
- `disabled`: boolean = false. Disables the control.
- `size`: 'xs' | 'sm' | 'md' | 'lg' | 'xl' = "md". Control height, font and padding scale.
Events:
- change: Called with the value of the chosen option.
Notes:
- The popup closes on outside click and on Escape.

## UiCombobox  (forms)
Searchable single-choice dropdown. Use for long option lists where typing to filter is faster than scrolling.
Props:
- `modelValue`: string | number [v-model]. Value of the selected option.
- `options`: { value: string | number; label: string; disabled?: boolean }[] = "[]". Available options. Filtering is a case-insensitive match on label. An option with disabled: true cannot be chosen.
- `label`: string. Label shown above the control.
- `hint`: string. Helper text under the control. Hidden while error is set.
- `error`: string. Error message under the control. Turns the control red and is announced with role="alert".
- `placeholder`: string. Defaults to "Search…".
- `emptyText`: string = "—". Shown when no option matches the query.
- `clearable`: boolean = false. Shows a clear (x) button while a value is selected; it calls change with null.
- `filter`: (option, query) => boolean. Custom matcher. Default is a case-insensitive substring match on label.
- `disabled`: boolean = false. Disables the control.
- `size`: 'xs' | 'sm' | 'md' | 'lg' | 'xl' = "md". Control height, font and padding scale.
Events:
- change: Called with the value of the chosen option.
Notes:
- Selecting from the list is the only way to set a value: free text is never emitted.
- The list closes on outside click and on Escape.

## UiTreeSelect  (forms)
Dropdown with a searchable tree. Use for hierarchical choices such as regions, categories or org units.
Props:
- `modelValue`: string | number [v-model]. id of the selected node.
- `nodes`: { id: string | number; label: string; children?: Node[]; disabled?: boolean }[] = "[]". Tree nodes. A node with disabled: true cannot be clicked. Top level is expanded by default.
- `selectGroups`: boolean = false. Allow selecting nodes that have children. By default clicking a parent only expands it.
- `label`: string. Label shown above the control.
- `placeholder`: string. Shown when nothing is selected. Defaults to "—".
- `disabled`: boolean = false. Disables the control.
- `size`: 'xs' | 'sm' | 'md' | 'lg' | 'xl' = "md". Control height, font and padding scale.
Events:
- change: Called with the id of the chosen node.
Notes:
- Typing in the search box expands all matching branches.
- The popup closes on outside click and on Escape.

## UiPillSelect  (forms)
Small pill-shaped dropdown button. Use for inline filters and sort controls in toolbars.
Props:
- `modelValue`: string | number [v-model]. Value of the selected option.
- `value`: string | number. Alias of modelValue, used when modelValue is not set.
- `options`: { value: string | number; label: string; disabled?: boolean }[] = "[]". Available options. A missing list renders an empty menu. An option with disabled: true cannot be chosen.
- `placeholder`: string. Shown when value matches no option.
- `disabled`: boolean = false. Disables the control.
- `size`: 'xs' | 'sm' | 'md' | 'lg' | 'xl' = "md". Pill height and font size.
Events:
- change: Called with the value of the chosen option.
Notes:
- The menu closes on outside click and on Escape.

## UiCheckbox  (forms)
Boolean checkbox with an inline label. Use for opt-ins and independent yes/no choices.
Props:
- `modelValue`: boolean = false [v-model]. Checked state.
- `label`: string. Text next to the box.
- `hint`: string. Second line under the label.
- `error`: string. Error message under the label (announced with role="alert"); a boolean or empty string shows nothing.
- `indeterminate`: boolean = false. Shows a dash instead of a check (aria-checked="mixed"). Clicking calls change with true.
- `disabled`: boolean = false. Disables the control.
- `size`: 'xs' | 'sm' | 'md' | 'lg' | 'xl' = "md". Box and label size.
Events:
- change: Called with the toggled boolean.
Notes:
- Rendered as a button with role="checkbox". When disabled it is dimmed, shows a not-allowed cursor and ignores clicks.

## UiSwitch  (forms)
On/off toggle with an inline label. Use for settings that apply immediately.
Props:
- `modelValue`: boolean = false [v-model]. On state.
- `label`: string. Text next to the toggle.
- `hint`: string. Second line under the label.
- `error`: string. Error message under the label (announced with role="alert").
- `labelLeft`: boolean = false. Places the label before the toggle instead of after it.
- `disabled`: boolean = false. Disables the control.
- `size`: 'xs' | 'sm' | 'md' | 'lg' | 'xl' = "md". Track and label size.
Events:
- change: Called with the toggled boolean.
Notes:
- Rendered as a button with role="switch". When disabled it is dimmed, shows a not-allowed cursor and ignores clicks.

## UiRadioGroup  (forms)
Group of radio options with optional hints. Use for a short single-choice list that should stay visible.
Props:
- `modelValue`: string | number [v-model]. Value of the selected option.
- `options`: { value: string | number; label: string; hint?: string; disabled?: boolean }[] = "[]". Radio options. hint is a second line under the label; disabled: true disables that option only.
- `label`: string. Label shown above the control.
- `hint`: string. Helper text under the control. Hidden while error is set.
- `error`: string. Error message under the control. Turns the control red and is announced with role="alert".
- `orientation`: 'vertical' | 'horizontal' = "vertical". horizontal lays the options out in a wrapping row under the label.
- `disabled`: boolean = false. Disables the control.
- `size`: 'xs' | 'sm' | 'md' | 'lg' | 'xl' = "md". Control height, font and padding scale.
Events:
- change: Called with the value of the chosen option.

## UiOptionCard  (forms)
Selectable card with title, description, price and optional image or icon. Usually rendered by OptionCards.
Props:
- `title`: string. Main text.
- `desc`: string. Secondary text under the title.
- `price`: string. Right-aligned price or value text.
- `image`: string. Image URL shown on the left. Takes priority over icon.
- `icon`: string. Icon name shown in a tile on the left.
- `checked`: boolean = false. Selected state.
- `multiple`: boolean = false. Checkbox look and role instead of radio.
- `size`: 'xs' | 'sm' | 'md' | 'lg' | 'xl' = "md". Control height, font and padding scale.
Events:
- click: Called when the card is pressed. Toggle checked yourself.

## UiOptionCards  (forms)
Grid of selectable OptionCards, single or multiple choice. Use for plans, room types and delivery options.
Props:
- `modelValue`: string | number | (string | number)[] [v-model]. Selected value, or an array of values when multiple is true.
- `options`: { value: string | number; title: string; desc?: string; price?: string; image?: string; icon?: string }[] = "[]". Cards to show. Fields are passed to OptionCard.
- `multiple`: boolean = false. Allow several selected cards. modelValue becomes an array.
- `min`: number = 220. Minimum card width in px before the grid wraps.
- `label`: string. Label shown above the control.
- `size`: 'xs' | 'sm' | 'md' | 'lg' | 'xl' = "md". Control height, font and padding scale.
Events:
- change: Called with the value (single) or the new array of values (multiple).

## UiSlider  (forms)
Single-handle range slider with a value readout. Use for picking one number in a bounded range.
Props:
- `modelValue`: number [v-model]. Current value. Defaults to min.
- `min`: number = 0. Lowest value.
- `max`: number = 100. Highest value.
- `step`: number = 1. Step between values.
- `showValue`: boolean = true. Show the current value to the right of the track.
- `formatValue`: (value: number) => string. Formats the readout, e.g. v => v + " $".
- `label`: string. Label shown above the control.
- `hint`: string. Helper text under the control. Hidden while error is set.
- `error`: string. Error message under the control. Turns the control red and is announced with role="alert".
- `size`: 'xs' | 'sm' | 'md' | 'lg' | 'xl' = "md". Track and thumb size.
Events:
- change: Called with the new number while dragging.

## UiRangeSlider  (forms)
Two-handle slider for a min-max range. Use for price, duration or date-number filters.
Props:
- `modelValue`: [number, number] [v-model]. Tuple [from, to]. Defaults to [min, max].
- `min`: number = 0. Lowest value.
- `max`: number = 100. Highest value.
- `step`: number = 1. Step between values.
- `formatValue`: (value: number) => string. Formats both ends in the readout.
- `label`: string. Label shown above the control.
- `size`: 'xs' | 'sm' | 'md' | 'lg' | 'xl' = "md". Track and thumb size.
Events:
- change: Called with a new [from, to] tuple; the handles cannot cross.

## UiRating  (forms)
Star rating input. Use for reviews and quick feedback.
Props:
- `modelValue`: number = 0 [v-model]. Number of filled stars.
- `max`: number = 5. Number of stars.
- `readonly`: boolean = false. Disables the stars, for display only.
- `label`: string = "Rating". Accessible name of the group (not rendered visibly).
- `size`: 'xs' | 'sm' | 'md' | 'lg' | 'xl' = "md". Star size: 14, 18, 20, 26 or 32 px. A number is used as the pixel size directly.
Events:
- change: Called with the clicked star count (1..max). Clicking the current value does not reset it.

## UiColorPicker  (forms)
Swatch row for choosing a color from presets. Use for tags, labels and theme accents.
Props:
- `modelValue`: string [v-model]. Selected color, same string as in presets.
- `presets`: string[] = "['#BC926A', '#5FAACC', '#3FD13F', '#E26E5F', '#E8B964', '#A98BD6', '#1B1919']". CSS colors offered as swatches.
- `label`: string. Label shown above the control.
- `size`: 'xs' | 'sm' | 'md' | 'lg' | 'xl' = "md". Swatch size.
Events:
- change: Called with the clicked color string.
Notes:
- Preset-only: there is no free color input.

## UiCalendar  (forms)
Month grid for picking one date. Use inline, or inside a popover via DatePicker.
Props:
- `modelValue`: Date | string | number [v-model]. Selected date: a Date, ISO string or timestamp. Also sets the visible month. A date-only string like "2026-10-21" is read as a local date, so the day does not shift with the time zone.
- `locale`: string = "en-GB". BCP 47 locale for month and weekday names.
- `weekStartsOn`: number = 1. First day of the week: 0 = Sunday, 1 = Monday.
- `min`: Date | string | number. Earliest selectable day; earlier days are disabled.
- `max`: Date | string | number. Latest selectable day; later days are disabled.
- `disabledDate`: (date: Date) => boolean. Return true to disable a specific day.
- `events`: Record<string, string> = "{}". Marked days: keys are YYYY-MM-DD, values are the tooltip text.
- `size`: 'xs' | 'sm' | 'md' | 'lg' | 'xl' = "md". Day cell and header size.
Events:
- change: Called with a Date object (local time) for the clicked day.
Notes:
- The event payload is a Date, not a string: convert to ISO yourself if the model is a string.

## UiRangeCalendar  (forms)
Month grid for picking a date range with hover preview. Use for stays, trips and report periods.
Props:
- `modelValue`: [Date | string | number | null, Date | string | number | null] [v-model]. Controlled range [start, end]; either end may be null. Date-only ISO strings are read as local dates. When omitted the selection is kept internally.
- `start`: Date | string | number. Month to show initially when no range is set. Does not preselect a range.
- `locale`: string = "en-GB". BCP 47 locale for month and weekday names.
- `weekStartsOn`: number = 1. First day of the week: 0 = Sunday, 1 = Monday.
- `size`: 'xs' | 'sm' | 'md' | 'lg' | 'xl' = "md". Day cell and header size.
Events:
- change: Called with [start, end] Date objects. In controlled mode (modelValue set) it also fires after the first click with [start, null]; uncontrolled it fires once the second date is picked.
Notes:
- Pass modelValue to control the selection; pick a date earlier than the start to restart the range.

## UiDatePicker  (forms)
Field with a calendar popup for choosing a date. Use in forms where a single date is needed.
Props:
- `modelValue`: string | Date | number [v-model]. Selected date (ISO string recommended, e.g. 2026-10-21).
- `locale`: string = "en-GB". BCP 47 locale used for the trigger text and the calendar.
- `weekStartsOn`: number = 1. First day of the week: 0 = Sunday, 1 = Monday.
- `clearable`: boolean = false. Shows a clear (x) button while a date is set; it calls change with null.
- `min`: Date | string | number. Earliest selectable day, forwarded to the calendar.
- `max`: Date | string | number. Latest selectable day, forwarded to the calendar.
- `disabledDate`: (date: Date) => boolean. Return true to disable a specific day, forwarded to the calendar.
- `required`: boolean = false. Adds a red asterisk to the label. Does not validate.
- `label`: string. Label shown above the control.
- `hint`: string. Helper text under the control. Hidden while error is set.
- `error`: string. Error message under the control. Turns the control red and is announced with role="alert".
- `placeholder`: string. Shown when no date is set. Defaults to "Select date".
- `disabled`: boolean = false. Disables the control.
- `size`: 'xs' | 'sm' | 'md' | 'lg' | 'xl' = "md". Control height, font and padding scale.
Events:
- change: Called with a Date object (local midnight) for the chosen day. The popup closes after picking.
Notes:
- The event payload is a Date, not a string: convert to ISO yourself if the model is a string.
- The popup closes on outside click and on Escape.

## UiTimePicker  (forms)
Hour and minute selects for a time of day. Use for opening hours and appointment times.
Props:
- `modelValue`: string = "09:00" [v-model]. Time as "HH:mm" (24 hour).
- `minuteStep`: number = 15. Step of the minute options in minutes (1 to 60). 15 gives 00, 15, 30, 45; 5 gives 00, 05, ... 55.
- `label`: string. Label shown above the control.
- `disabled`: boolean = false. Disables the control.
- `size`: 'xs' | 'sm' | 'md' | 'lg' | 'xl' = "md". Control height, font and padding scale.
Events:
- change: Called with a new "HH:mm" string. Minute options follow minuteStep.
Notes:
- A model value outside the minute grid (e.g. 09:07) is added to the minute list so it still displays.
- Both selects close on outside click and on Escape.

## UiFileUpload  (forms)
Drop-zone style file picker. Use for documents and attachments.
Props:
- `title`: string = "Drop files here or browse". Main text in the zone.
- `hint`: string = "PDF, JPG up to 10 MB". Secondary text in the zone. Purely informational: use accept and maxSize to enforce limits.
- `accept`: string. Accepted types as in the native attribute, e.g. ".pdf,image/*". Also applied to dropped files.
- `maxSize`: number. Maximum size of one file in bytes. Larger files are rejected.
- `multiple`: boolean = false. Allow selecting several files.
- `image`: boolean = false. Use the image icon instead of the upload icon.
- `label`: string. Label shown above the control.
- `error`: string. Error message under the control. Turns the control red and is announced with role="alert".
- `size`: 'xs' | 'sm' | 'md' | 'lg' | 'xl' = "md". Control height, font and padding scale.
Events:
- change: Called with the array of accepted File objects, from the picker or a drop. Without multiple only the first one is kept.
- reject: Called as (file, reason) for each refused file; reason is "type" (not in accept), "size" (over maxSize) or "count" (extra file when multiple is off).
Notes:
- Click, Enter or Space opens the picker; files can also be dropped onto the zone, which highlights while dragging.
- Stateless: the component does not list the chosen files, render them yourself.

## UiImageUpload  (forms)
Image picker with a live preview, square or circular. Use for avatars, covers and logos.
Props:
- `modelValue`: string [v-model]. Image URL or data URL to show before the user picks a new file.
- `shape`: 'square' | 'circle' = "square". circle gives a round avatar-style crop, otherwise rounded corners.
- `aspect`: string = "1/1". CSS aspect-ratio of the box, e.g. "16/9".
- `hint`: string = "Upload". Text shown in the empty state.
- `label`: string. Label shown above the control.
- `size`: 'xs' | 'sm' | 'md' | 'lg' | 'xl' = "md". Maximum width: 112, 128, 160, 192 or 224 px. A number is used as px directly.
Events:
- change: Called with (dataUrl, file): the picked image as a data URL and the original File.
Notes:
- The preview is kept in internal state, so it updates even without updating modelValue.

## UiFormField  (forms)
Label, required marker, hint and error wrapper around any control. Use to build a field from custom inputs.
Props:
- `label`: string. Label shown above the control.
- `required`: boolean = false. Appends a red asterisk to the label. Does not validate.
- `hint`: string. Helper text under the control. Hidden while error is set.
- `error`: string. Error message under the control. Turns the control red and is announced with role="alert".
- `size`: 'xs' | 'sm' | 'md' | 'lg' | 'xl' = "md". Only marks the wrapper with data-size; sizes never leak into children by design, so set size on the inner control too.
Slots:
- default: The control(s) to wrap.
Notes:
- Does not link label and control by id: put the control inside a label or pass an aria-label yourself.

## UiValidatedField  (forms)
TextField (or PasswordInput) with built-in validation rules. Use for simple client-side validation without a form library.
Props:
- `modelValue`: string = "" [v-model]. Current value.
- `rules`: ((value: string) => true | string)[] = "[]". Validators run in order; return true when valid or an error message. The first failure is shown.
- `type`: 'text' | 'password' | string = "text". "password" renders PasswordInput, any other value is passed to TextField as the input type.
- `error`: string. External error. Takes priority over rules.
- `label`: string. Label shown above the control.
- `placeholder`: string. Placeholder text.
- `hint`: string. Helper text under the control. Hidden while error is set.
- `icon`: string. Leading icon name (TextField only).
- `disabled`: boolean = false. Disables the control.
- `size`: 'xs' | 'sm' | 'md' | 'lg' | 'xl' = "md". Control height, font and padding scale.
Events:
- change: Called with the new string on every keystroke.
Notes:
- Rules start running after the first edit, so an untouched field shows no error.
- All other props are forwarded to TextField / PasswordInput.

## UiLoginForm  (forms)
Ready sign-in form with login, password, remember-me, forgot link and submit button. Use as the body of an auth page.
Props:
- `error`: string. Failure message shown in a danger alert above the fields.
- `loading`: boolean = false. Disables the submit button and shows a spinner.
- `showForgot`: boolean = true. Show the "Forgot password?" link.
- `submitLabel`: string = "Sign in". Submit button text. Wins over labels.submit.
- `labels`: { email?: string; password?: string; remember?: string; forgot?: string; submit?: string } = "{ email: 'Email or phone', password: 'Password', remember: 'Remember device', forgot: 'Forgot password?', submit: 'Sign in' }". Texts of the form; any missing key keeps its English default.
- `size`: 'xs' | 'sm' | 'md' | 'lg' | 'xl' = "md". Control height, font and padding scale.
Events:
- submit: Called with { email, password, remember } when the form is submitted.
- forgot: Called when "Forgot password?" is clicked.
Notes:
- Field values live inside the component: read them from the submit payload.
- Translate the texts with labels; the "email" value holds an email or phone.

## UiStepForm  (forms)
Multi-step form shell: stepper, current step content and Back/Next buttons. Use for wizards and onboarding.
Props:
- `steps`: { label: string; content: VNode }[] = "[]". Steps in order. content is rendered while the step is active.
- `finishLabel`: string = "Finish". Text of the Next button on the last step.
- `size`: 'xs' | 'sm' | 'md' | 'lg' | 'xl' = "md". Also sets the size of the Back/Next buttons.
Events:
- finish: Called when Next is pressed on the last step.
Notes:
- The current step is internal; Next never validates, so guard the content yourself.

## UiStepper  (forms)
Horizontal progress indicator with numbered steps. Use to show position in a multi-step flow.
Props:
- `steps`: string[] = "[]". Step labels in order.
- `current` (required): number. Zero-based index of the active step. Earlier steps show a check mark.
- `size`: 'xs' | 'sm' | 'md' | 'lg' | 'xl' = "md". Step circle and label size.

## UiCard  (data)
Glass surface container with an optional title header, used to group related content.
Props:
- `title`: string. Header title. The header renders only when title or the actions slot is set.
- `subtitle`: string. Muted line under the title.
- `variant`: 'inverse' | 'gradient' | 'outline'. inverse is a dark card regardless of the page theme; gradient is a tinted gradient card colored by tone; outline is transparent with a border. Omit for the default glass card.
- `tone`: 'brand' | 'sky' | 'success' | 'warning' | 'danger' | 'neutral' | 'rose' | 'violet' = "brand". Gradient color. Used only with variant="gradient".
- `intensity`: 'vivid'. With variant="gradient", fills the card with a saturated color instead of a soft tint.
- `padding`: 'none'. none removes the inner padding (for full-bleed tables or images). Other paddings come from size.
- `interactive`: boolean = false. Adds a pointer cursor and hover lift. With a click handler the card also becomes keyboard focusable (Enter activates).
- `size`: 'xs' | 'sm' | 'md' | 'lg' | 'xl' = "md". Padding, gap and title size.
Slots:
- default: Card body.
- actions: Right side of the header, for buttons or menus.
- header: Replaces the whole title/actions header with custom content.
- footer: Row under the body, for buttons or meta.
Events:
- click: Native click on the card. Combine with interactive.
Notes:
- Vue slot names are React props (actions) and children (default).

## UiDataTable  (data)
Table with sortable columns, custom cell rendering and optional row selection checkboxes.
Props:
- `columns` (required): { key: string; label: string; sortable?: boolean; num?: boolean; align?: "left" | "center" | "right"; width?: string; render?: (value, row, h) => VNode | string }[] = []. Column definitions. key reads row[key]; num right-aligns numbers; render customizes the cell; sortable shows a sort button in the header.
- `rows` (required): ({ id: string | number; [key: string]: any })[] = []. Row objects. Every row needs a unique id; missing cell values render as an em dash.
- `selected`: (string | number)[] = []. Ids of selected rows. Checkboxes show only when the select event is handled.
- `sortKey`: string. Key of the column currently sorted. The component does not sort rows itself.
- `sortDir`: 'asc' | 'desc' = "asc". Direction of the current sort, shown by the header arrow and aria-sort.
- `empty`: string = "—". Text shown when rows is empty.
- `labels`: { selectAll?: string; selectRow?: string } = "{ selectAll: 'Select all', selectRow: 'Select row' }". Accessible names of the selection checkboxes.
- `size`: 'xs' | 'sm' | 'md' | 'lg' | 'xl' = "md". Row density and font size.
Slots:
- empty: Replaces the empty text with custom content when rows is empty.
Events:
- rowClick: Called with (row, index) when a body row is clicked. Rows get a pointer cursor.
- select: Called with the new array of selected row ids. Handling it enables the checkbox column and select-all.
- sort: Called with (key, dir) where dir is "asc" or "desc". Sort the rows yourself and pass sortKey/sortDir back.
Notes:
- Sorting and selection are fully controlled: the table never reorders rows or stores selection.
- render receives (value, row) and, in React/Vue, the h function as third argument.

## UiDataGroup  (data)
Table whose rows are collapsed into labeled groups, with optional per-row expandable details.
Props:
- `columns` (required): { key: string; label: string; num?: boolean; render?: (value, row) => VNode | string }[] = []. Column definitions, same shape as DataTable without sorting.
- `groups` (required): { label: string; rows: ({ id: string | number; [key: string]: any })[] }[] = []. Groups shown as collapsible header rows with a row count. Group labels must be unique.
- `expand`: (row) => VNode | string. Renders the detail panel under a row. When set, an expand chevron column appears.
- `size`: 'xs' | 'sm' | 'md' | 'lg' | 'xl' = "md". Row density and font size.
Notes:
- Open/collapsed state is internal; groups start expanded.

## UiDescriptions  (data)
Definition list of label and value pairs for record details.
Props:
- `items` (required): { label: string; value?: string | number | VNode }[] = []. Pairs rendered as dt/dd. Missing value renders an em dash.
- `size`: 'xs' | 'sm' | 'md' | 'lg' | 'xl' = "md". Font size and spacing.

## UiTimeline  (data)
Vertical list of events connected by a line, for activity history and status progress.
Props:
- `items` (required): { title: string; text?: string; time: string }[] = []. Events from top to bottom. title is bold, text is optional detail, time is the caption.
- `size`: 'xs' | 'sm' | 'md' | 'lg' | 'xl' = "md". Dot, spacing and font size.

## UiTreeView  (data)
Expandable tree of nodes for hierarchies such as folders, categories or regions.
Props:
- `nodes` (required): { id: string; label: string; icon?: string; children?: Node[] }[] = []. Root nodes. children nest recursively; icon is an icon name. Ids must be unique.
- `selected`: string. Id of the highlighted node.
- `size`: 'xs' | 'sm' | 'md' | 'lg' | 'xl' = "md". Row height and font size.
Events:
- select: Called with the node id when a node is clicked. Nodes with children also toggle open.
Notes:
- The first level is open by default; deeper levels start collapsed.

## UiCalendarView  (data)
Month calendar that marks days with events, wrapping Calendar with a list-style events prop.
Props:
- `events`: { date: string; label: string }[] = []. Marked days. date is "YYYY-MM-DD"; label shows as the day tooltip.
- `modelValue`: string | number | Date [v-model]. Selected date. Vue v-model, React modelValue + onChange.
- `locale`: string = "en-GB". BCP 47 locale for month and weekday names.
- `weekStartsOn`: 0 | 1 | 2 | 3 | 4 | 5 | 6 = 1. First day of the week, 0 is Sunday and 1 is Monday.
Events:
- change: Called with the clicked Date (local time). Forwarded to Calendar.

## UiKpiTile  (data)
Key metric tile with a label, large value and optional delta, for dashboards.
Props:
- `label` (required): string. Metric name.
- `value` (required): string | number. Main value, shown large.
- `sub`: string. Small text next to the delta.
- `delta`: string. Change indicator such as "+12%" or "-3.4%". A leading "-" renders as a decrease, anything else as an increase.
- `variant`: 'brand' | 'inverse'. Filled brand tile or dark inverse tile. Omit for the default glass tile.
- `size`: 'xs' | 'sm' | 'md' | 'lg' | 'xl' = "md". Padding and value size.

## UiKpiInline  (data)
Compact inline metric with a label, value and delta, for toolbars and card headers.
Props:
- `label` (required): string. Metric name.
- `value` (required): string | number. Main value.
- `delta`: string. Change indicator such as "+12%" or "-3.4%". A leading "-" renders as a decrease, anything else as an increase.
- `size`: 'xs' | 'sm' | 'md' | 'lg' | 'xl' = "md". Value font size.

## UiStatsCard  (data)
Metric card with an optional icon, value and an up or down trend.
Props:
- `label` (required): string. Metric name.
- `value` (required): string | number. Main value.
- `icon`: string. Icon name shown before the label.
- `delta`: string. Change text such as "12%". The arrow is added automatically from trend.
- `trend`: 'up' | 'down' = "up". Direction and color of the delta.
- `size`: 'xs' | 'sm' | 'md' | 'lg' | 'xl' = "md". Padding and value size.

## UiStatRow  (data)
List row with an icon tile, title, subtitle and a right-aligned value with delta.
Props:
- `title` (required): string. Primary text.
- `sub`: string. Muted secondary text.
- `value`: string | number. Right-aligned value.
- `delta`: string. Change shown under the value. A leading "-" is a decrease; the sign is stripped and an arrow added.
- `icon`: string. Icon name for the leading tile.
- `tone`: 'brand' | 'sky' | 'success' | 'warning' | 'danger' | 'neutral' = "brand". Color of the icon tile. Unknown values fall back to brand.
- `size`: 'xs' | 'sm' | 'md' | 'lg' | 'xl' | number = "md". Row height and icon tile size. Named sizes map to a 28/34/40/48/56 px tile; a number is used as the tile size in px.

## UiStatLine  (data)
Card with a large value, icon tile, label and an accent bar, for a single headline number.
Props:
- `label` (required): string. Metric name under the value.
- `value` (required): string | number. Main value.
- `icon`: string. Icon name for the tile.
- `tone`: 'brand' | 'sky' | 'success' | 'warning' | 'danger' | 'neutral' = "brand". Accent color of the tile and bar. Unknown values fall back to brand.
- `delta`: string. Change indicator such as "+12%" or "-3.4%". A leading "-" renders as a decrease, anything else as an increase.
- `size`: 'xs' | 'sm' | 'md' | 'lg' | 'xl' | number = "md". Icon tile size. Named sizes map to 28/34/40/48/56 px; a number is used in px.

## UiStatStrip  (data)
Horizontal strip of several icon, value and label stats in one card.
Props:
- `items` (required): { icon?: string; tone?: 'brand' | 'sky' | 'success' | 'warning' | 'danger' | 'neutral'; value: string | number; label: string }[] = []. Stats shown side by side. tone defaults to brand.
- `size`: 'xs' | 'sm' | 'md' | 'lg' | 'xl' | number = "md". Icon tile size. Named sizes map to 30/36/44/52/60 px; a number is used in px.

## UiCountryRow  (data)
Row with a country code badge, amount, country name and a percentage change.
Props:
- `code` (required): string. Short code shown in the circle, such as "UZ".
- `name` (required): string. Country name.
- `amount` (required): string | number. Formatted amount shown in bold.
- `pct`: string. Percentage change such as "+8%" or "-2%".

## UiVersusBar  (data)
Head-to-head comparison of two values with a proportional two-color bar.
Props:
- `left` (required): { label: string; value: number }. Left side. Its share of the bar is value / (left.value + right.value) in the brand color.
- `right` (required): { label: string; value: number }. Right side, filling the remainder of the bar in sky.
- `size`: 'xs' | 'sm' | 'md' | 'lg' | 'xl' = "md". Value font size and bar thickness.
Notes:
- A missing side renders an empty label and 0; with both at 0 the bar is split with no brand share.

## UiSegBar  (data)
Single stacked bar split into proportional segments with a legend, for distributions.
Props:
- `segments` (required): { label: string; value: number; color?: string }[] = []. Segments; widths are value / sum of values. color is any CSS color; the default cycles brand, sky, green, amber, red.

## UiMiniChart  (data)
Tiny sparkline in bar or line form for trends inside cards and tables.
Props:
- `values` (required): number[] = []. Non-negative data points, scaled to the maximum value.
- `type`: 'bar' | 'line' = "bar". Bar columns or a single line.
- `highlightLast`: boolean = false. Bar type only: paints the last bar in the brand color.
- `height`: number. Height in px. Overrides size when set.
- `size`: 'xs' | 'sm' | 'md' | 'lg' | 'xl' = "md". Preset height: xs 28, sm 36, md 48, lg 64, xl 80 px.
Notes:
- The chart is decorative (no axes or values); pair it with a visible number.

## UiChartCard  (data)
Card shell for a chart with title, subtitle and an optional overflow menu; put the chart in the default slot.
Props:
- `title` (required): string. Card title.
- `subtitle`: string. Muted line under the title.
- `menu`: string[]. Labels of overflow menu items shown behind a three-dot button. An item named "Delete" is styled as danger.
- `size`: 'xs' | 'sm' | 'md' | 'lg' | 'xl' = "md". Padding, gap and title size.
Slots:
- default: Chart or any content shown below the header.
Events:
- menu: Called with the clicked menu item label (the string from menu); the menu closes afterwards.

## UiRing  (data)
Circular progress gauge with a percentage in the center and a tick scale around it.
Props:
- `value` (required): number = 0. Progress from 0 to 100; values are clamped.
- `label`: string. Caption under the percentage.
- `color`: string = "var(--zg-brand)". Any CSS color for the arc and ticks.
- `thickness`: number. Stroke width in px. Defaults to about 8% of the diameter, minimum 8.
- `ticks`: boolean = true. Shows the outer 60-tick scale; false removes it and enlarges the arc.
- `valueSize`: number. Percentage font size in px. Defaults to 22% of the diameter.
- `size`: 'xs' | 'sm' | 'md' | 'lg' | 'xl' | number = "md". Diameter: xs 72, sm 120, md 180, lg 240, xl 300 px; a number is used as px.

## UiOccupancyChart  (data)
Bar chart of percentages by label, such as hotel occupancy per day or month.
Props:
- `values` (required): number[] = []. Percentages from 0 to 100, one per bar. Values above 90 are highlighted in brand color.
- `labels`: string[] = []. Axis label under each bar, matched by index.

## UiSalesFunnel  (data)
Horizontal funnel of steps with bars scaled to the largest value, for conversion flows.
Props:
- `steps` (required): { label: string; value: number }[] = []. Steps from top to bottom. Bars scale to the max value; the last step is highlighted in brand color.

## UiSystemStatus  (data)
List of services with a status dot and a value such as uptime or latency.
Props:
- `items` (required): { name: string; value: string; state?: 'ok' | 'warn' | 'down' }[] = []. Services. state sets the color: ok green (default), warn amber, down red.

## UiUserCell  (data)
Avatar with a name and optional subtitle, for table cells and lists of people.
Props:
- `name` (required): string. Display name, also used for avatar initials.
- `sub`: string. Muted line under the name, such as an email or role.
- `src`: string. Avatar image URL. Initials are shown without it.
- `size`: 'xs' | 'sm' | 'md' | 'lg' | 'xl' | number = "md". Avatar diameter: xs 24, sm 30, md 36, lg 44, xl 56 px; a number is used as px.

## UiIconTile  (data)
Square or circular tinted tile holding an icon, used as a leading visual in lists and cards.
Props:
- `icon`: string = "circle". Icon name.
- `tone`: 'brand' | 'sky' | 'success' | 'warning' | 'danger' | 'neutral' = "brand". Tint color. Unknown values fall back to brand.
- `shape`: 'square' | 'circle' = "square". Rounded square or full circle. Only "circle" changes the shape.
- `size`: 'xs' | 'sm' | 'md' | 'lg' | 'xl' | number = "md". Tile size: xs 28, sm 32, md 40, lg 48, xl 56 px; a number is used as px. The icon is half the tile.

## UiStatusIcon  (data)
Round tinted icon with a hover and focus tooltip, for compact status markers.
Props:
- `icon`: string = "circle". Icon name.
- `tone`: 'brand' | 'sky' | 'success' | 'warning' | 'danger' | 'neutral' = "brand". Tint color. Unknown values fall back to brand.
- `tip`: string. Tooltip text shown on hover and keyboard focus.
- `size`: 'xs' | 'sm' | 'md' | 'lg' | 'xl' | number = "md". Diameter: xs 24, sm 30, md 36, lg 44, xl 52 px; a number is used as px.
Notes:
- Focusable (tabindex 0) so the tooltip works from the keyboard; the icon itself is aria-hidden, so put the meaning in tip.

## UiHeroBanner  (data)
Wide promotional banner with title, text, a big value, optional action and a background image.
Props:
- `title` (required): string. Banner heading.
- `text`: string. Supporting paragraph.
- `value`: string | number. Large number or price shown under the text.
- `cta`: string. Label of the primary button. The button renders only when set.
- `image`: string. Image URL shown on the right side.
Slots:
- default: Extra content placed before the button.
Events:
- cta: Called when the call-to-action button is clicked.

## UiTabTiles  (data)
Row of icon tiles that work as tabs, with an optional add button.
Props:
- `items` (required): { value: string; label: string; icon?: string }[] = []. Tiles. icon defaults to circle.
- `value`: string. Value of the active tile. Controlled; change it in the change handler.
- `addable`: boolean = false. Shows a trailing plus tile that fires the add event.
Events:
- change: Called with the value of the clicked tile.
- add: Called when the plus tile is clicked.
Notes:
- Active state is exposed as aria-pressed on buttons, not as a tablist.

## UiPricingCard  (data)
Pricing plan card with price, feature list and a select button.
Props:
- `name` (required): string. Plan name.
- `price` (required): string | number. Price text, shown large.
- `period`: string. Suffix after the price, such as "/mo".
- `features`: string[] = []. Feature bullets with check icons.
- `badge`: string. Brand badge next to the name, such as "Popular".
- `featured`: boolean = false. Highlights the card and makes the button primary.
- `cta`: string = "Choose". Button label.
- `size`: 'xs' | 'sm' | 'md' | 'lg' | 'xl' = "md". Card padding and title size.
Events:
- select: Called when the button is clicked.

## UiIntegrationCard  (data)
Card for a third-party integration showing its connection status and a connect or manage button.
Props:
- `name` (required): string. Integration name.
- `description`: string. Short explanation under the name.
- `status`: 'connected' | 'error' | 'off' = "off". Connection state. Sets the badge (Connected, Error, Not linked) and button (Manage, Reconnect, Link).
- `labels`: { connected?: string; error?: string; off?: string; manage?: string; reconnect?: string; link?: string } = "{ connected: 'Connected', error: 'Error', off: 'Not linked', manage: 'Manage', reconnect: 'Reconnect', link: 'Link' }". Badge and button texts per status; missing keys keep the English defaults.
- `size`: 'xs' | 'sm' | 'md' | 'lg' | 'xl' = "md". Card padding and title size.
Events:
- toggle: Called when the button is clicked, for connecting, reconnecting or managing.
Notes:
- Translate badge and button texts with labels.
- Unknown status values behave as "off".

## UiAlert  (feedback)
Inline message block with a tone icon, optional title and close button; use for form errors, notices and results inside a page.
Props:
- `tone`: 'info' | 'success' | 'warning' | 'danger' = "info". Color and icon: info, check, triangle-alert or circle-alert.
- `title`: string. Bold first line above the message.
- `size`: 'xs' | 'sm' | 'md' | 'lg' | 'xl' = "md". Scale of padding, icon and text.
- `banner`: boolean = false. Removes the border radius so the alert spans the full width like a Banner.
- `hideIcon`: boolean = false. Hides the leading tone icon (the icon slot is hidden too).
Slots:
- default: Message text.
- title: Replaces the title prop with custom content.
- icon: Replaces the tone icon inside the icon tile.
- actions: Row under the message for buttons or links.
Events:
- close: Called when the close button is clicked. The button is rendered only when this handler is set.
Notes:
- Has role="alert", so screen readers announce it when it appears.
- Not self-dismissing: hide it yourself in the close handler.

## UiBanner  (feedback)
Full-width Alert without rounded corners; use at the top of a page or section for system-wide notices.
Props:
- `tone`: 'info' | 'success' | 'warning' | 'danger' = "info". Color and icon: info, check, triangle-alert or circle-alert.
- `title`: string. Bold first line above the message.
- `size`: 'xs' | 'sm' | 'md' | 'lg' | 'xl' = "md". Scale of padding, icon and text.
Slots:
- default: Message text.
Events:
- close: Called when the close button is clicked. The button is rendered only when this handler is set.
Notes:
- Same as Alert with banner enabled; all Alert props are forwarded.

## UiToast  (feedback)
Static toast card with a tone icon, title and text; use for transient confirmations rendered in your own toast stack.
Props:
- `tone`: 'info' | 'success' | 'warning' | 'danger' = "info". Color and icon.
- `title`: string. Bold first line.
- `size`: 'xs' | 'sm' | 'md' | 'lg' | 'xl' = "md". Scale of padding, icon, text and max width.
Slots:
- default: Message text.
Notes:
- Presentational only: it has no timer, close button or positioning. Mount and unmount it yourself.
- Has role="status".

## UiSnackbar  (feedback)
Compact dark bar with a message and one optional action; use for undo and short confirmations at the bottom of the screen.
Props:
- `tone`: 'brand' | 'sky' | 'success' | 'warning' | 'danger' | 'neutral' = "brand". Accent color; affects the tonal background (and the action color: green for success, red otherwise).
- `variant`: 'solid' | 'tonal' = "solid". Solid inverse background or a tone-tinted one.
- `action`: string. Label of the action button. The button is rendered only when set.
- `size`: 'xs' | 'sm' | 'md' | 'lg' | 'xl' = "md". Scale of height, padding and text.
Slots:
- default: Message text.
Events:
- action: Called when the action button is clicked.
- close: Called when the close icon is clicked. The icon is rendered only when this handler is set.
Notes:
- Presentational only: no timer or positioning.

## UiProgress  (feedback)
Horizontal progress bar with optional label and meta text; use for uploads, quotas and completion.
Props:
- `value`: number = 0. Progress from 0 to 100; clamped to this range.
- `tone`: 'success' | 'warning' | 'danger'. Bar color. Omit for the brand color.
- `label`: string. Text above the bar on the left.
- `meta`: string. Monospace text above the bar on the right, e.g. "64%" or "3 / 5".
- `size`: 'xs' | 'sm' | 'md' | 'lg' | 'xl' = "md". Scale of bar height and label text.
Notes:
- Exposes role="progressbar" with aria-valuenow; the label is not linked via aria-labelledby.

## UiSpinner  (feedback)
Inline loading indicator; use inside buttons, cards or next to a loading label.
Props:
- `size`: 'xs' | 'sm' | 'md' | 'lg' | 'xl' | number = "md". Preset (14, 16, 20, 28, 36 px) or a number of pixels.
Notes:
- Has role="status" and aria-label="Loading".

## UiSkeleton  (feedback)
Shimmering placeholder for content that is loading; use text lines, circles or rectangles that match the final layout.
Props:
- `variant`: 'text' | 'circle' | 'rect' = "text". Shape of the placeholder.
- `lines`: number = 1. Number of stacked lines. The last of several lines is 60% wide.
- `width`: string = "100%". CSS width of each line or rect.
- `height`: string. CSS height. Text lines take the height from size.
- `size`: 'xs' | 'sm' | 'md' | 'lg' | 'xl' | number = "md". Text line height and gap; for variant "circle" the diameter (24, 32, 40, 56, 72 px) or a number of pixels.
Notes:
- Purely visual and not announced to assistive tech; pair it with aria-busy on the container.

## UiEmptyState  (feedback)
Centered icon (or image), title and description with optional actions; use when a list, search or section has no content.
Props:
- `title` (required): string. Bold heading.
- `description`: string. Supporting text under the title.
- `icon`: string = "inbox". Icon name shown in the tile. Ignored when image is set.
- `image`: string. Image URL shown instead of the icon.
- `size`: 'xs' | 'sm' | 'md' | 'lg' | 'xl' = "md". Scale of padding, icon tile and text.
Slots:
- default: Actions (buttons) shown under the text.

## UiErrorPage  (feedback)
Full-page error with a large code, title and description; use for 404, 500 and similar screens.
Props:
- `code`: string = "404". Large number shown on top.
- `title`: string = "Page not found". Heading.
- `description`: string = "The page may have moved. Check the address or go back.". Supporting text.
Slots:
- default: Actions (buttons) shown under the text.

## UiStatusPage  (feedback)
Ready-made full-page status screen (404, 401, maintenance, coming soon) with one action button.
Props:
- `kind`: '404' | '401' | 'maintenance' | 'soon' = "404". Preset that sets the code or icon, default title, description and button label.
- `title`: string. Overrides the preset heading.
- `description`: string. Overrides the preset text.
- `actionLabel`: string. Overrides the button text of the 404, 401 and maintenance presets (default "Back to home").
- `notifyLabel`: string = "Notify me". Button text for kind "soon".
- `emailLabel`: string = "name@email.com". Placeholder of the email field for kind "soon".
- `codeNode`: VNode. Replaces the big code or icon. Used by PageStatus for its code slot.
- `messageNode`: VNode. Replaces heading and description. Used by PageStatus for its message slot.
- `actionNode`: VNode. Replaces the button or email form. Used by PageStatus for its action slot.
Slots:
- default: Extra content rendered after the button.
Events:
- action: Called when the main button is clicked (not used for kind "soon").
- notify: Called with the typed email string when the Notify button of kind "soon" is clicked.
Notes:
- The email is not validated: check it in your onNotify handler.

## UiDataState  (feedback)
Switches between loading, empty, error, offline and the real content based on one state value; wrap any data-driven block with it.
Props:
- `state`: 'ready' | 'loading' | 'empty' | 'error' | 'offline' = "ready". Which view to show. "ready" renders the children.
- `title`: string. Overrides the default heading of the non-ready views ("Loading…", "Nothing here yet", "Something went wrong", "No internet").
- `description`: string. Supporting text for empty, error and offline views (offline defaults to "Saved guides still work.").
- `retryLabel`: string. Retry button label for error ("Retry") and offline ("Try again").
Slots:
- default: Content shown when state is "ready".
Events:
- retry: Called when the retry button of the error or offline view is clicked.

## UiLoadingOverlay  (feedback)
Wrapper that dims its content and shows a spinner on top while loading; use over cards, tables or forms during a refresh.
Props:
- `loading`: boolean = false. Shows the overlay with the spinner.
- `label`: string. Text shown under the spinner.
Slots:
- default: Content covered by the overlay.

## UiModal  (overlay)
Centered dialog with a title, close button, body and optional footer; use for forms and focused tasks that block the page.
Props:
- `open`: boolean = false. Shows the dialog when true; renders nothing when false.
- `title`: string. Header text and aria-label of the dialog.
- `subtitle`: string. Muted line under the title in the header.
- `closable`: boolean = true. false hides the close (x) button in the header.
- `closeOnBackdrop`: boolean = true. false ignores clicks on the scrim.
- `closeOnEsc`: boolean = true. false ignores the Escape key (focus trap stays active).
- `width`: string. CSS max-width of the dialog, for example "960px". Overrides the width of size.
- `size`: 'xs' | 'sm' | 'md' | 'lg' | 'xl' = "md". Scale of width (320 to 720 px max), padding and text.
Slots:
- default: Dialog body.
- footer: Footer area, usually action buttons. Rendered only when provided.
- title: Replaces the title prop with custom header content.
- subtitle: Replaces the subtitle prop.
Events:
- close: Called on the close button, a click on the scrim or the Escape key. Set open to false in the handler.
Notes:
- Has role="dialog" and aria-modal. Escape calls close; on open focus moves into the dialog, Tab is trapped inside it and focus returns to the previously focused element on close.
- Put data-autofocus on an element to choose which one receives initial focus (default: first focusable).
- Closed state renders nothing, so inner state is lost on close.

## UiDrawer  (overlay)
Side panel that slides over the page; use for filters, details and secondary forms.
Props:
- `open`: boolean = false. Shows the drawer when true; renders nothing when false.
- `title`: string. Header text and aria-label.
- `side`: 'start' | 'end' = "end". Edge the drawer attaches to; start and end follow text direction.
- `size`: 'xs' | 'sm' | 'md' | 'lg' | 'xl' = "md". Scale of width (280 to 640 px).
Slots:
- default: Drawer body.
- footer: Footer area, usually action buttons. Rendered only when provided.
Events:
- close: Called on the close button, a click on the scrim or the Escape key.
Notes:
- Has role="dialog" and aria-modal. Escape calls close; on open focus moves into the dialog, Tab is trapped inside it and focus returns to the previously focused element on close.

## UiConfirmDialog  (overlay)
Small Modal with a message and Cancel/Confirm buttons; use to confirm destructive or irreversible actions.
Props:
- `open`: boolean = false. Shows the dialog when true; renders nothing when false.
- `title`: string. Dialog heading.
- `description`: string. Explanation shown in the body.
- `tone`: 'default' | 'danger' = "default". Danger turns the confirm button red; any other value gives the primary button.
- `confirmLabel`: string = "Confirm". Confirm button text.
- `cancelLabel`: string = "Cancel". Cancel button text.
- `loading`: boolean = false. Shows a spinner on the confirm button.
- `size`: 'xs' | 'sm' | 'md' | 'lg' | 'xl' = "md". Scale of dialog width and padding.
Events:
- confirm: Called when the confirm button is clicked.
- cancel: Called on Cancel, the close icon, the Escape key or a click on the scrim.
Notes:
- Close handling goes through cancel, there is no separate close event.
- The dialog does not close itself: set open to false in both handlers.

## UiPopconfirm  (overlay)
Button that opens a small confirmation popover with cancel/confirm buttons (No/Yes by default); use for quick inline confirmation of a single action.
Props:
- `label`: string. Text of the trigger button.
- `title`: string. Question shown in the popover.
- `variant`: 'primary' | 'secondary' | 'ghost' | 'danger' | 'inverse' | 'tonal' | 'outlined' | 'text' | 'elevated' = "danger". Button variant of the trigger.
- `confirmLabel`: string = "Yes". Text of the confirm button.
- `cancelLabel`: string = "No". Text of the cancel button.
- `size`: 'xs' | 'sm' | 'md' | 'lg' | 'xl' = "sm". Scale of trigger button and popover.
Events:
- confirm: Called when the confirm button is clicked; the popover closes first.
Notes:
- Open state is internal. The popover closes on outside click and on Escape.

## UiStepDialog  (overlay)
Wide Modal with a vertical step list on the left and Previous/Next buttons; use for multi-step wizards.
Props:
- `open`: boolean = false. Shows the dialog when true; renders nothing when false.
- `title`: string. Header text and aria-label.
- `steps`: { title: string; sub?: string }[] = "[]". Steps in the left rail; sub is a hint under the title.
- `current`: number. Zero-based index of the active step. Earlier steps are shown as done.
- `size`: 'xs' | 'sm' | 'md' | 'lg' | 'xl' = "md". Scale of dialog width (640 to 1100 px) and padding.
Slots:
- default: Content of the current step.
Events:
- back: Previous button; disabled on the first step.
- next: Next button; labelled "Submit" on the last step, so also handle submit here.
- close: Close icon, scrim click or the Escape key.
Notes:
- You own the current index: update it in the back and next handlers.
- Has aria-modal. Escape calls close; on open focus moves into the dialog, Tab is trapped inside it and focus returns to the previously focused element on close.

## UiFullscreenDialog  (overlay)
Full-screen dialog with a close button, title and Save action in the header; use for long editing flows on mobile.
Props:
- `open`: boolean = false. Shows the dialog when true; renders nothing when false.
- `title`: string. Header text and aria-label.
- `saveLabel`: string = "Save". Text of the save button in the header.
Slots:
- default: Dialog content.
Events:
- close: Called on the close icon button or the Escape key.
- save: Called on the header save button.
Notes:
- Has aria-modal. Escape calls close; on open focus moves into the dialog, Tab is trapped inside it and focus returns to the previously focused element on close.

## UiBottomSheet  (overlay)
Panel anchored to the bottom of the screen with a grab handle; use for mobile pickers and short forms.
Props:
- `open`: boolean = false. Shows the sheet when true; renders nothing when false.
- `title`: string. Optional heading; also the aria-label.
- `maxHeight`: string | number = "85vh". Maximum height: a CSS length or a number of pixels.
- `size`: 'xs' | 'sm' | 'md' | 'lg' | 'xl' = "md". Scale of sheet width (360 to 800 px) and padding.
Slots:
- default: Sheet content.
- footer: Sticky footer, e.g. buttons. Rendered only when provided.
Events:
- close: Called on a click on the scrim or the Escape key.
Notes:
- The handle is decorative: it does not support dragging.
- There is no close button; always handle close (scrim click and Escape). Escape calls close; on open focus moves into the dialog, Tab is trapped inside it and focus returns to the previously focused element on close.

## UiActionsheet  (overlay)
Bottom sheet with a list of actions and a Cancel button; use for mobile "more actions" menus.
Props:
- `open`: boolean = false. Shows the sheet when true; renders nothing when false.
- `title`: string. Optional heading.
- `items`: { label: string; icon?: string; tone?: 'danger'; disabled?: boolean; onClick?: () => void }[] = "[]". Actions. Each item runs its own onClick, then select, then the sheet closes. Tone "danger" colors it red.
- `cancelLabel`: string = "Cancel". Text of the cancel row.
- `size`: 'xs' | 'sm' | 'md' | 'lg' | 'xl' = "md". Scale of sheet width and padding.
Events:
- select: Called with the whole clicked item after its onClick.
- close: Called after any item is chosen, on Cancel, on the Escape key and on a scrim click.

## UiPopover  (overlay)
Button that toggles a floating panel with arbitrary content; use for small forms and extra info next to a control.
Props:
- `label`: string. Text of the trigger button.
- `size`: 'xs' | 'sm' | 'md' | 'lg' | 'xl' = "md". Scale of trigger button and panel padding.
Slots:
- default: Panel content.
Notes:
- Open state is internal and toggled by the trigger. The panel closes on outside click and on Escape (focus returns to the trigger).

## UiHoverCard  (overlay)
Rich card shown on hover or keyboard focus of a trigger; use for previews of users, links or entities.
Props:
- `trigger`: string | VNode. Content that triggers the card.
- `size`: 'xs' | 'sm' | 'md' | 'lg' | 'xl' = "md". Scale of card width (200 to 400 px) and padding.
Slots:
- default: Card content.
Notes:
- The wrapper is focusable (tabIndex 0), so the card also opens on focus.

## UiTooltip  (overlay)
Short text bubble shown on hover or focus of the wrapped element; use for icon-only controls and hints.
Props:
- `text` (required): string. Tooltip text.
- `placement`: 'top' | 'bottom' | 'left' | 'right' = "top". Side of the wrapped element where the bubble appears.
- `size`: 'xs' | 'sm' | 'md' | 'lg' | 'xl' = "md". Scale of bubble padding and font.
Slots:
- default: The element the tooltip is attached to.
Notes:
- Pure CSS bubble; it cannot contain markup. For rich content use HoverCard.

## UiDropdown  (overlay)
Button that opens a menu of actions; use for "more" menus and action lists.
Props:
- `label`: string. Text of the trigger button.
- `icon`: string. Icon name before the label.
- `items`: { label: string; value?: string; icon?: string; shortcut?: string; tone?: 'danger'; disabled?: boolean; onClick?: (item) => void; separator?: boolean }[] = "[]". Menu entries. Item fields: label, value (passed to select), icon (icon name), shortcut (kbd hint on the right), tone "danger" (red), disabled true (dimmed, not clickable), onClick (called with the item when clicked, before the select event), separator true (renders a divider; other fields ignored).
- `disabled`: boolean = false. Disables the trigger button so the menu cannot open.
- `size`: 'xs' | 'sm' | 'md' | 'lg' | 'xl' = "md". Scale of trigger button and menu.
Events:
- select: Called with the item value when an entry is clicked. The menu closes first.
Notes:
- Each item may also have its own onClick and disabled. Open state is internal; the menu closes on outside click and on Escape.

## UiMenu  (overlay)
Static vertical list of actions rendered inline; use in sidebars and custom popovers.
Props:
- `items`: { label: string; value?: string; icon?: string; shortcut?: string; tone?: 'danger'; disabled?: boolean; onClick?: (item) => void; separator?: boolean }[] = "[]". Menu entries. Item fields: label, value (passed to select), icon (icon name), shortcut (kbd hint on the right), tone "danger" (red), disabled true (dimmed, not clickable), onClick (called with the item when clicked, before the select event), separator true (renders a divider; other fields ignored).
- `open`: boolean. Optional. false renders nothing, true shows the menu; leave unset for an always visible menu.
- `size`: 'xs' | 'sm' | 'md' | 'lg' | 'xl' = "md". Scale of row height and text.
Events:
- select: Called with the item value when an entry is clicked.
- close: Called on outside click or Escape while open is true. Pass it as onClose.
Notes:
- Always visible unless open is set. For a self-toggling menu use Dropdown, for a right-click menu use ContextMenu.

## UiContextMenu  (overlay)
Wraps an area and shows a menu at the cursor on right click; use for row and canvas actions.
Props:
- `items`: { label: string; value?: string; icon?: string; shortcut?: string; tone?: 'danger'; disabled?: boolean; onClick?: (item) => void; separator?: boolean }[] = "[]". Menu entries. Item fields: label, value (passed to select), icon (icon name), shortcut (kbd hint on the right), tone "danger" (red), disabled true (dimmed, not clickable), onClick (called with the item when clicked, before the select event), separator true (renders a divider; other fields ignored).
- `size`: 'xs' | 'sm' | 'md' | 'lg' | 'xl' = "md". Scale of row height and text.
Slots:
- default: The area that reacts to right click.
Events:
- select: Called with the item value when an entry is clicked. The menu closes first.
Notes:
- The native context menu is prevented inside the area. Clicking outside, right-clicking again or pressing Escape closes it.
- The menu is clamped to the viewport using a rough 42 px per row.

## UiCommandBar  (overlay)
Floating glass toolbar of icon buttons; use for selection actions or editor tools.
Props:
- `items`: { id: string; icon?: string; label: string; disabled?: boolean; separator?: boolean }[] = "[]". Buttons. label is the tooltip and aria-label, icon defaults to "circle", separator true draws a divider.
- `size`: 'xs' | 'sm' | 'md' | 'lg' | 'xl' = "md". Scale of button size and padding.
Events:
- action: Called with the item id when a button is clicked.

## UiCommandPalette  (overlay)
Searchable list of commands in a top-aligned dialog; use for a Cmd+K launcher.
Props:
- `open`: boolean = false. Shows the palette when true; renders nothing when false.
- `commands`: { id: string; label: string; icon?: string; shortcut?: string; keywords?: string }[] = "[]". Commands. Filtering is a case-insensitive substring match on label plus keywords.
- `placeholder`: string = "Type a command…". Search input placeholder.
- `size`: 'xs' | 'sm' | 'md' | 'lg' | 'xl' = "md". Scale of dialog max width (400 to 720 px).
Events:
- run: Called with the command id on click or Enter; the palette then requests close.
- close: Called on a scrim click, the Escape key and after a command runs.
Notes:
- Keyboard: ArrowDown/ArrowUp move the active command (wraps around, aria-selected), Enter runs it, Escape closes. The active item resets to the first one when the query changes.
- The input receives focus on open and Tab stays inside the dialog. There is no global hotkey; bind Cmd+K yourself.

## UiImageViewer  (overlay)
Full-screen lightbox for one or several images with previous/next buttons and a counter.
Props:
- `open`: boolean = false. Shows the viewer when true; renders nothing when false.
- `images`: string[] = "[]". Image URLs.
- `index`: number = 0. Index of the image to start on.
- `alt`: string. Alt text of the image and aria-label of the dialog (default "Image viewer").
Events:
- close: Called on the close button or a click on the backdrop.
Notes:
- Navigation buttons appear only when there is more than one image.

## UiTour  (overlay)
Guided product tour that dims the page, highlights a target element and shows a step popover.
Props:
- `open`: boolean = false. Shows the tour when true; renders nothing when false.
- `steps`: { target?: string; title: string; text: string }[] = "[]". Steps. target is a CSS selector of the element to highlight; without it the step is shown centered over a full dim.
- `step`: number. Controlled zero-based step index. When omitted the tour keeps it internally (reset to 0 on close). Update it from the step event.
Events:
- close: Called on the close icon, the Escape key and after Finish on the last step.
- step: Called with the new zero-based step index on Next, Back and the arrow keys.
Notes:
- Keyboard: ArrowRight/ArrowLeft go to the next/previous step (reversed in RTL), Escape closes. Focus is not moved, so the page stays usable.
- Targets are looked up with document.querySelector and scrolled into view.
- The internal step resets to 0 whenever the tour closes.

## UiTourPopover  (overlay)
Step card of a tour with title, text, step counter and Back/Next buttons; used by Tour and usable standalone.
Props:
- `title`: string. Step heading.
- `text`: string. Step body text.
- `step`: string. Counter text such as "2 / 5".
- `last`: boolean = false. Changes the Next button label to "Finish".
Events:
- back: Back button; the button is rendered only when this handler is set.
- next: Next or Finish button.
- close: Close icon.

## UiScreensaver  (overlay)
Full-screen idle screen with a large clock, date and the brand mark; show it after inactivity.
Props:
- `open`: boolean = false. Shows the screensaver when true; renders nothing when false.
- `locale`: string = "en-GB". BCP 47 locale for the date line.
- `hint`: string. Small hint under the date, e.g. "Tap to continue".
- `idleMs`: number = 0. When greater than 0 and the screensaver is closed, a hidden sentinel listens for pointer, key, wheel and touch activity and calls idle after this many milliseconds without any. 0 disables it.
Events:
- close: Called on click or any key (including Escape) while open.
- idle: Called once the idleMs period passes without activity while closed; set open to true in the handler.
Notes:
- The clock re-renders from one interval created when the screensaver opens and cleared when it closes; the idle timer is re-armed on each interaction. Nothing runs during server rendering.

## UiTopNav  (navigation)
Horizontal app header with a brand area, navigation items and an actions area.
Props:
- `brand`: string | VNode. Logo or product name on the left.
- `items`: { value: string; label: string; icon?: string; count?: string | number }[] = "[]". Navigation entries. count renders a small counter after the label.
- `value`: string. Value of the active item (aria-current="page").
- `size`: 'xs' | 'sm' | 'md' | 'lg' | 'xl' = "md". Scale of header padding, item height and text.
Slots:
- actions: Right side of the header (buttons, avatar). React also accepts an actions prop.
Events:
- change: Called with the value of the clicked item.
Notes:
- Controlled: update value yourself in the change handler.
- Items use count; SubNav uses badge for the same purpose.

## UiSideNav  (navigation)
Vertical sidebar with a brand, grouped navigation items, a footer and an optional collapse toggle.
Props:
- `brand`: string | VNode. Logo or product name at the top.
- `items`: ({ value: string; label: string; icon?: string; count?: string | number } | { group: string })[] = "[]". Entries. An object with group renders a section heading (hidden when collapsed); others are links with an optional icon and count.
- `value`: string. Value of the active item (aria-current="page").
- `collapsed`: boolean = false. Icon-only mode; labels move to the title tooltip.
- `collapseLabel`: string = "Collapse". Label of the collapse button.
- `size`: 'xs' | 'sm' | 'md' | 'lg' | 'xl' = "md". Scale of width (216 to 336 px), padding and item height.
Slots:
- footer: Bottom area above the collapse button, e.g. user card. React also accepts a footer prop.
Events:
- change: Called with the value of the clicked item.
- toggle: Called when the collapse button is clicked. The button is rendered only when this handler is set.
Notes:
- Collapsing is controlled: flip collapsed in the toggle handler.
- Group entries are keyed by their title, so keep group names unique.

## UiSubNav  (navigation)
Compact vertical list of sections with an optional title; use for settings and secondary page navigation.
Props:
- `title`: string. Small heading above the list; also the aria-label.
- `items`: { value: string; label: string; icon?: string; badge?: string | number }[] = "[]". Entries. badge renders a counter on the right.
- `value`: string. Value of the active item (aria-current="page").
- `size`: 'xs' | 'sm' | 'md' | 'lg' | 'xl' = "md". Scale of item height and text.
Events:
- change: Called with the value of the clicked item.

## UiTabs  (navigation)
Underlined tab strip for switching between views of the same page.
Props:
- `modelValue`: string [v-model]. Value of the selected tab. Vue v-model, React modelValue + onChange.
- `items`: { value: string; label: string }[] = "[]". Tabs.
- `size`: 'xs' | 'sm' | 'md' | 'lg' | 'xl' = "md". Scale of tab height and text.
Events:
- change: Called with the value of the clicked tab.
Notes:
- Renders only the tab buttons (role="tablist"); you show the matching panel yourself.

## UiPillTabs  (navigation)
Pill-style tab buttons with optional icons, horizontal or vertical; use for settings and profile sections.
Props:
- `items`: { value: string; label: string; icon?: string }[] = "[]". Tabs.
- `value`: string. Value of the selected tab. Changed via the change event.
- `vertical`: boolean = false. Stacks the tabs in a column.
- `size`: 'xs' | 'sm' | 'md' | 'lg' | 'xl' = "md". Scale of button height, gap and text.
Events:
- change: Called with the value of the clicked tab.
Notes:
- Renders only the tab buttons; you show the matching panel yourself.

## UiBreadcrumbs  (navigation)
Path trail with chevron separators; the last item is the current page.
Props:
- `items`: { label: string; href?: string }[] = "[]". Trail from root to current. All but the last render as links (href defaults to "#"); the last is bold with aria-current="page".
- `size`: 'xs' | 'sm' | 'md' | 'lg' | 'xl' = "md". Scale of text and separator size.
- `separator`: 'chevron' | 'slash' | 'dot' = "chevron". Glyph between items.

## UiPagination  (navigation)
Page navigation with numbered buttons, ellipsis windowing and previous/next; use under tables and lists.
Props:
- `page`: number. Current page, 1-based. Changed via the change event.
- `pages`: number = 1. Total number of pages.
- `siblings`: number = 1. Page buttons shown on each side of the current page. First and last page are always shown; gaps become an ellipsis.
- `label`: string = "Pagination". Accessible name of the navigation landmark.
- `hideArrows`: boolean = false. Hides the previous and next buttons.
- `labels`: { prev?: string; next?: string; page?: string } = "{ prev: 'Previous page', next: 'Next page', page: 'Page' }". Accessible names of the arrow buttons and of each page button ("Page 3").
- `size`: 'xs' | 'sm' | 'md' | 'lg' | 'xl' = "md". Scale of button size and text.
Events:
- change: Called with the clicked page number (also from the previous and next buttons).
Notes:
- Shows first, last and current plus or minus siblings with an ellipsis for gaps, so it scales to hundreds of pages. A gap of a single page shows that page instead of an ellipsis.
- Previous and next buttons carry aria-label "Previous page" and "Next page" and are disabled at the ends; the current page has aria-current="page".

## UiAccordion  (navigation)
Vertical list of collapsible sections where one is open at a time; use for FAQs and grouped details.
Props:
- `items`: { id: string; title: string; body: string | VNode }[] = "[]". Sections. id must be unique; body is shown when the section is open.
- `size`: 'xs' | 'sm' | 'md' | 'lg' | 'xl' = "md". Scale of header padding and text.
Notes:
- Open state is internal and single: opening one closes the others, all start closed.

## UiAvatar  (media)
Round user picture that falls back to initials when there is no image.
Props:
- `name`: string. Full name. Shown as the tooltip and used for up to two initials; "?" when empty.
- `src`: string. Image URL. Initials are shown without it.
- `initials`: string. Explicit initials (up to 3 characters, uppercased) instead of the ones derived from name.
- `tone`: 'brand' | 'sky' | 'success' | 'warning' | 'danger' | 'neutral' = "brand". Background color of the initials avatar.
- `shape`: 'circle' | 'rounded' = "circle". rounded gives a squircle with a 30% corner radius.
- `ring`: boolean = false. Adds a background-colored ring so overlapping avatars stay separated.
- `status`: 'online' | 'offline' | 'away' | 'busy'. Shows a presence dot in the bottom corner.
- `size`: 'xs' | 'sm' | 'md' | 'lg' | 'xl' | number = "md". Diameter: xs 24, sm 32, md 40, lg 56, xl 72 px. A number is used directly as px.
Notes:
- Avatar sizes differ from other components (lg 56, xl 72), and a number gives any custom size.

## UiIcon  (media)
Renders a named icon from the library at a chosen size.
Props:
- `name`: string = "circle". Icon name from the library, for example "check" or "map-pin".
- `size`: 'xs' | 'sm' | 'md' | 'lg' | 'xl' | number = "md". Pixel size: xs 14, sm 16, md 20, lg 24, xl 32. A number is used directly as px.
Notes:
- The icon is aria-hidden; add a label on the surrounding control for accessibility.
- Icons load lazily, so the glyph may appear a moment after first render.

## UiLazyImage  (media)
Image box with a fixed aspect ratio and rounded corners, rendered as a background image.
Props:
- `src`: string. Image URL. An empty placeholder is shown without it.
- `alt`: string = "". Accessible description, exposed as aria-label on role="img".
- `aspectRatio`: string = "16/9". CSS aspect-ratio value such as "1/1" or "4/3".
- `rounded`: number = 20. Corner radius in px.

## UiGallery  (media)
Large image with a counter and a thumbnail strip for browsing a set of photos.
Props:
- `images` (required): string[] = []. Image URLs. The first one is shown initially; clicking a thumbnail switches the main image.
- `alt`: string = "". Accessible description of the main image.
- `index`: number. Controlled active image index. When set, the gallery only changes image when you update it from onChange; when omitted it keeps its own state starting at 0.
- `labels`: { photo?: string } = "{ photo: 'Photo' }". Override the thumbnail aria-label prefix.
- `size`: 'xs' | 'sm' | 'md' | 'lg' | 'xl' = "md". Thumbnail strip size.
Events:
- change: Called with the new image index when a thumbnail is clicked.
Notes:
- An empty or missing images array renders an empty frame (no counter, no thumbnails). Invalid index values are clamped to the available range.

## UiCarousel  (media)
Slideshow of image slides with captions, arrows and dot pagination.
Props:
- `items` (required): { image?: string; title: string; sub?: string }[] = []. Slides. title and sub form the caption over the image.
- `index`: number. Controlled active slide index. When set, the carousel only changes slide when you update it from onChange; when omitted it keeps its own state starting at 0.
- `autoplay`: number | boolean. Advance automatically every N milliseconds (true = 5000). Starts only in the browser, pauses while the pointer is over or focus is inside the carousel and while the tab is hidden, and is disabled for prefers-reduced-motion and data-motion="off". Needs at least 2 slides.
- `label`: string. Accessible name of the carousel region.
- `labels`: { prev?: string; next?: string; slide?: string } = "{ prev: 'Previous', next: 'Next', slide: 'Slide' }". Override the aria-labels of the arrows and dots.
- `size`: 'xs' | 'sm' | 'md' | 'lg' | 'xl' = "md". Slide aspect ratio and caption size: xs 16/6, sm 16/7, md 16/8, lg 16/9, xl 16/10.
Events:
- change: Called with the new slide index on arrow, dot, keyboard (left and right arrows) and autoplay changes.
Notes:
- Arrows wrap around at both ends and are hidden with fewer than 2 slides; an empty items array renders an empty frame.
- Autoplay has no visible pause button; hover or focus pauses it. Prefer a manual carousel for essential content.

## UiMap  (media)
Interactive raster map with panning, zoom buttons and clickable markers, using OpenStreetMap data via CARTO tiles.
Props:
- `lat`: number = 21.4225. Initial center latitude.
- `lon`: number = 39.8262. Initial center longitude.
- `zoom`: number = 14. Initial zoom level; the zoom buttons clamp it to 3..18.
- `markers`: { lat: number; lon: number; label?: string; icon?: string; tone?: 'brand' | 'sky' | 'success' | 'warning' | 'danger' | 'neutral' }[] = []. Pins. label is the tooltip, icon defaults to "map-pin".
- `width`: number = 640. Pixel width used to compute which tiles to load; the map element itself fills its container.
- `height`: number = 360. Height in px.
- `theme`: 'light' | 'dark'. Tile theme. If omitted, dark is used when the page is inside a dark data-theme.
- `style`: string. CARTO tile style path, for example "light_all" or "dark_all". Overrides theme.
- `label`: string = "Map". aria-label of the map region.
- `labels`: { zoomIn?: string; zoomOut?: string } = "{ zoomIn: 'Zoom in', zoomOut: 'Zoom out' }". Accessible names of the zoom buttons.
Events:
- select: Called with the marker object when a marker is clicked.
- move: Called with { lat, lon, zoom } while the user pans or zooms (drag, touch, wheel, double click or the +/- buttons).
- zoom: Called with the new zoom level when it changes.
Notes:
- The center and zoom props are initial values; user panning and zooming is kept in internal state. Listen to move/zoom to track it.
- Drag or touch to pan, wheel or double click to zoom around the pointer. The tile theme follows the page data-theme after mount (light tiles on the server render) unless theme or style is set.
- Tiles come from a third-party CDN, so it needs network access.

## UiProfileHeader  (media)
Profile card with a cover image, large avatar, name and a row of meta items.
Props:
- `name` (required): string. Person or organization name.
- `src`: string. Avatar image URL; initials are shown without it.
- `cover`: string. Cover image URL.
- `meta`: { icon: string; label: string }[] = []. Facts under the name such as location or join date. label must be unique.
Slots:
- default: Extra content on the right of the name row, usually action buttons.

## UiChatAi  (media)
Chat panel with message bubbles, a typing indicator and an input, for AI assistant UIs.
Props:
- `messages` (required): { role: 'user' | 'ai'; text: string }[] = []. Conversation in order. Any role other than "user" renders as an assistant bubble.
- `loading`: boolean = false. Shows the typing dots and disables sending.
- `title`: string = "Assistant". Header title; also the aria-label. The header renders only when set.
- `subtitle`: string. Muted text next to the title.
- `placeholder`: string = "Ask anything…". Input placeholder.
Events:
- send: Called with the trimmed message text when the user presses Enter or the send button. The component does not append it to messages.
Notes:
- Append the user message and the reply to messages yourself; set loading while waiting.

## UiHotelCard  (domain)
Hotel listing card with photo, tags, stars, distance, rating and nightly price; use in catalogs and search results.
Props:
- `name` (required): string. Hotel name.
- `image`: string. Photo URL, used as the card background image.
- `tags`: string[] = "[]". Brand badges over the photo, e.g. "Haram view".
- `stars`: number = 0. Star class 0-5, rendered as repeated stars.
- `distance`: string. Distance caption next to the stars, e.g. "120 m to the Haram".
- `rating`: string | number. Guest rating shown in a green badge, e.g. 9.2.
- `price`: number. Price per unit, formatted with thousand separators; the currency label is fixed to SAR.
- `night`: string = "night". Unit after "SAR /", e.g. "night".
- `size`: 'xs' | 'sm' | 'md' | 'lg' | 'xl' = "md". Scales padding, text and avatars.
Notes:
- Currency is hard-coded to SAR.
- Wrap in a clickable element yourself; the card has no click handler.

## UiTourCard  (domain)
Tour or virtual-tour card with session count and a seat-occupancy bar.
Props:
- `name` (required): string. Tour title.
- `city`: string. City shown in the subtitle.
- `sessions`: number. Number of sessions, shown as "N sessions".
- `booked` (required): number. Seats already booked.
- `seats` (required): number. Total seats; the bar shows booked / seats.
- `size`: 'xs' | 'sm' | 'md' | 'lg' | 'xl' = "md". Scales padding, text and avatars.
Slots:
- actions: Footer actions, usually Buttons.
Notes:
- A fixed "360°" badge is always shown.
- With seats = 0 or missing the bar is empty (0%) and the meta reads "0/0".

## UiPrayerTimes  (domain)
Row of daily prayer times with the upcoming prayer highlighted.
Props:
- `items`: { name: string; time: string }[] = "[]". Prayers in display order; time is shown as-is, e.g. "05:12".
- `next`: number. Index in items of the next prayer; sets aria-current on it.
- `size`: 'xs' | 'sm' | 'md' | 'lg' | 'xl' = "md". Scales padding, text and avatars.

## UiRamadanTracker  (domain)
Thirty-day Ramadan progress strip; the last ten days and odd nights are marked.
Props:
- `day` (required): number. Current day 1-30. Earlier days render as past, later days as upcoming.
- `size`: 'xs' | 'sm' | 'md' | 'lg' | 'xl' = "md". Scales padding, text and avatars.
Notes:
- Exposed as role="img" with aria-label "Day N of 30".

## UiBookingCard  (domain)
Compact booking summary: code, status, guest, hotel, dates and total.
Props:
- `code` (required): string. Booking reference, monospaced.
- `status`: 'Confirmed' | 'Pending' | 'Cancelled' | string. Status text. Confirmed is green, Pending amber, Cancelled red; any other value gets a neutral badge.
- `guest`: string. Guest name, also drives the avatar initials.
- `hotel`: string. Hotel name under the guest.
- `dates`: string. Preformatted date range, e.g. "12-19 Mar".
- `amount`: number. Total, formatted as "SAR 1 200".
- `size`: 'xs' | 'sm' | 'md' | 'lg' | 'xl' = "md". Scales padding, text and avatars.

## UiGuestCard  (domain)
Guest profile card with avatar, country, stay length and tags.
Props:
- `name` (required): string. Guest name.
- `country`: string. Country shown in the subtitle.
- `nights`: number. Number of nights, shown as "N nights".
- `vip`: boolean = false. Shows a VIP badge.
- `tags`: string[] = "[]". Preference tags, e.g. "Halal", "Late check-in".
- `size`: 'xs' | 'sm' | 'md' | 'lg' | 'xl' = "md". Scales padding, text and avatars.

## UiRoomGrid  (domain)
Tile grid of rooms colored by housekeeping status; use for front-desk room selection.
Props:
- `rooms`: { no: string; type: string; status: "occupied" | "clean" | "dirty" | "blocked" }[] = "[]". Rooms; no is the room number and the unique key, type is the room class label, status sets the tile color (any other value renders neutral).
- `statusTones`: Record<string, 'brand' | 'sky' | 'success' | 'warning' | 'danger' | 'neutral'> = "{ occupied: 'brand', clean: 'success', dirty: 'warning', blocked: 'danger' }". Maps a room status to a tile tone. Merged over the defaults, so you can add custom statuses (e.g. { maintenance: "sky" }) or recolor known ones. Statuses without a tone render neutral.
- `size`: 'xs' | 'sm' | 'md' | 'lg' | 'xl' = "md". Scales padding, text and avatars.
Events:
- select: Called with the room number (room.no) of the clicked tile.
Notes:
- Each tile is a button; status is conveyed by color only, so add a legend.

## UiRoomCalendar  (domain)
Gantt-style occupancy calendar: rooms as rows, days as columns, bookings as bars.
Props:
- `rooms`: { no: string; bookings?: { from: number; nights: number; guest: string }[] }[] = "[]". Rooms with their bookings; from is the zero-based day index of check-in, nights its length. guest is the cell tooltip.
- `days`: number = 14. Number of day columns, labelled 1..days.
- `size`: 'xs' | 'sm' | 'md' | 'lg' | 'xl' = "md". Scales padding, text and avatars.
Notes:
- Day headers are plain numbers 1..days; offset them yourself for a month view.

## UiLeadCard  (domain)
CRM lead card with avatar, code, phone and amount.
Props:
- `name` (required): string. Lead name.
- `code`: string. Lead or deal code under the name, monospaced.
- `tag`: string. Optional badge text, e.g. a source or status.
- `tone`: 'default' | 'brand' | 'success' | 'warning' | 'danger' | 'info'. Badge tone for tag; neutral when omitted.
- `phone`: string. Phone number with a phone icon.
- `amount`: string | number. Amount shown on the right, rendered as given (format it yourself).
- `size`: 'xs' | 'sm' | 'md' | 'lg' | 'xl' = "md". Scales padding, text and avatars.

## UiDealCard  (domain)
CRM deal card with stage badge, amount, win probability and owner; the card type inside PipelineBoard.
Props:
- `title` (required): string. Deal title.
- `stage`: string. Stage badge text; no badge when omitted.
- `tone`: 'default' | 'brand' | 'success' | 'warning' | 'danger' | 'info' = "info". Badge tone for the stage.
- `amount`: string | number. Large amount, rendered as given.
- `probability`: number = 0. Win probability 0-100, shown as a progress bar and percent.
- `owner`: string. Owner name with avatar.
- `due`: string. Due date caption, right aligned.
- `size`: 'xs' | 'sm' | 'md' | 'lg' | 'xl' = "md". Scales padding, text and avatars.

## UiPipelineBoard  (domain)
Horizontally scrolling kanban pipeline of stage columns filled with DealCards.
Props:
- `stages`: { id: string | number; title: string; cards: DealCardProps[] }[] = "[]". Columns in order; cards take the DealCard props (title, stage, tone, amount, probability, owner, due). The column count badge is cards.length. Give cards an id so onMove can report which one moved (the index is used otherwise).
- `size`: 'xs' | 'sm' | 'md' | 'lg' | 'xl' = "md". Scales padding, text and avatars.
Events:
- move: Called with { id, from, to } (card id, source stage id, target stage id) when a card is dropped on another stage. The board does not reorder itself: update stages in your state.
Notes:
- Drag and drop is enabled only when a move handler is passed; without it the board renders and behaves as before.
- Uses HTML5 drag and drop (mouse and desktop browsers); there is no keyboard alternative, so also offer a stage select on the card if you need one.
- Cards are fixed to DealCard; for custom cards compose KanbanColumn and KanbanCard.

## UiContactPanel  (domain)
Contact detail card with avatar, role, contact fields and Call / Message buttons.
Props:
- `name` (required): string. Contact name.
- `role`: string. Role or company under the name.
- `phone`: string. Phone row.
- `telegram`: string. Telegram handle row.
- `email`: string. Email row.
- `city`: string. City row.
- `labels`: { call?: string; message?: string }. Override built-in English strings.
- `size`: 'xs' | 'sm' | 'md' | 'lg' | 'xl' = "md". Scales padding, text and avatars.
Events:
- call: Called with no arguments when Call is clicked.
- message: Called with no arguments when Message is clicked.

## UiKanbanColumn  (domain)
Single kanban column with a title, count badge and stacked cards.
Props:
- `title` (required): string. Column heading.
- `count`: number. Count badge; defaults to the number of children.
- `size`: 'xs' | 'sm' | 'md' | 'lg' | 'xl' = "md". Scales padding, text and avatars.
Slots:
- default: Cards, usually KanbanCard or DealCard. React passes them as children.

## UiKanbanCard  (domain)
Simple kanban card with title, subtitle, free content and an optional tag.
Props:
- `title` (required): string. Card title.
- `sub`: string. Subtitle under the title.
- `tag`: string. Badge at the bottom.
- `tone`: 'default' | 'brand' | 'success' | 'warning' | 'danger' | 'info'. Badge tone for tag.
- `size`: 'xs' | 'sm' | 'md' | 'lg' | 'xl' = "md". Scales padding, text and avatars.
Slots:
- default: Extra content between the subtitle and the tag. React passes it as children.

## UiCallRow  (domain)
One-line call log row with avatar, status, duration and a play button.
Props:
- `name` (required): string. Caller name.
- `status`: string. Status text before the duration, e.g. "Answered".
- `duration`: number. Duration in seconds, formatted as "3 m 05 s" (units from durUnits); shows a dash when missing.
- `durUnits`: { m?: string; s?: string } = "{ m: 'm', s: 's' }". Minute and second unit labels for localized durations, e.g. { m: "min", s: "sec" }.
- `labels`: { play?: string }. Override built-in English strings. play is the aria-label of the play button.
- `size`: 'xs' | 'sm' | 'md' | 'lg' | 'xl' = "md". Scales padding, text and avatars.
Events:
- play: Called with no arguments when the play button is clicked.

## UiCallCard  (domain)
Call recording card with status badge, a playback progress bar and duration.
Props:
- `name` (required): string. Caller name.
- `phone`: string. Phone number.
- `status`: 'Answered' | 'Missed' | 'Voicemail' | 'Busy' | 'Declined' | string. Badge text. Known statuses (case-insensitive): Answered green, Missed and Declined red, Voicemail and Busy amber, Ringing blue. Any other value is neutral. The badge is hidden when empty.
- `statusTones`: Record<string, 'success' | 'danger' | 'warning' | 'info' | 'brand'>. Extra or overriding status to tone mapping, e.g. { "No answer": "warning" }.
- `progress`: number = 0. Playback progress 0-100.
- `duration`: number. Duration in seconds.
- `durUnits`: { m?: string; s?: string } = "{ m: 'm', s: 's' }". Minute and second unit labels for the duration.
- `labels`: { play?: string }. Override built-in English strings. play is the aria-label of the play button.
- `size`: 'xs' | 'sm' | 'md' | 'lg' | 'xl' = "md". Scales padding, text and avatars.
Events:
- play: Called with no arguments when the play button is clicked.

## UiIncomingCall  (domain)
Glass banner for an incoming call with Decline and Answer buttons.
Props:
- `name` (required): string. Caller name.
- `phone`: string. Caller number.
- `label`: string = "Incoming call". Caption above the name.
- `onDecline`: () => void. Decline button click.
- `onAnswer`: () => void. Answer button click.
- `size`: 'xs' | 'sm' | 'md' | 'lg' | 'xl' = "md". Scales padding, text and avatars.
Events:
- decline: Decline button clicked.
- answer: Answer button clicked.

## UiAuthSplit  (domain)
Two-column sign-in layout with a brand panel on the left and the form on the right.
Props:
- `title` (required): string. Form heading.
- `subtitle`: string. Text under the heading.
- `logo`: VNode. Logo node above the heading.
- `aside`: VNode. Content of the left brand panel (hidden on narrow screens).
Slots:
- default: Form content under the heading. React passes it as children.
Notes:
- logo and aside are props in both Vue and React (pass a VNode / element).

## UiAuthShowcase  (domain)
Sign-in layout with a media panel: dark photo card with floating avatars, light gradient card with a social-proof pill, or a tinted panel with a glass caption. The default slot is the form.
Props:
- `variant`: 'photo' | 'light' | 'tint' = "photo". 'photo': one framed card, media on the left. 'light': gradient form card, proof pill below, glass caption on the media. 'tint': like light, with a coloured panel, a heading on the media and cyan accent.
- `title` (required): string. Form heading.
- `subtitle`: string. Text under the heading.
- `logo`: VNode. Logo node above the heading.
- `footer`: VNode. Content under the fields, for example "No account? Sign up".
- `image`: string. URL of the media image. Without it the panel shows an accent gradient.
- `headline`: string. Large text on the media panel (photo and tint).
- `caption`: string. Small text on the media panel (photo) or inside the glass bar (light, tint).
- `quote`: string. Line at the bottom of the media panel; photo only.
- `chips`: string[]. Pill labels inside the glass bar; light and tint.
- `people`: { name: string; src?: string }[]. Avatars: floating on the photo, stacked in the proof pill.
- `proof`: string. Social-proof title, e.g. "Join 20k+ users"; light and tint. Shows the pill under the form.
- `proofHint`: string. Second line of the proof pill.
Slots:
- default: Form fields and buttons. React passes them as children.
Notes:
- logo, footer, image, people are props in both Vue and React. The media panel is hidden below the form on narrow screens (stacks under it).

## UiSocialAuth  (domain)
Continue with Google and Apple buttons with an "or" divider. Place it under the sign-in form.
Props:
- `providers`: ('google' | 'apple')[] = "['google', 'apple']". Which buttons to show, in order.
- `variant`: 'stack' | 'icons' = "stack". 'stack': full-width buttons with a label, one per row. 'icons': a row of square icon buttons.
- `divider`: boolean = "true". Show the "or" line above the buttons.
- `labels`: { google?: string; apple?: string }. Provider names inserted into "Continue with {provider}".
- `onSelect`: (provider: 'google' | 'apple') => void. Called with the clicked provider. Start your OAuth flow here.
- `size`: 'xs' | 'sm' | 'md' | 'lg' | 'xl' = "md". Scales padding, text and avatars.
Events:
- select: A provider button was clicked; payload is "google" or "apple".
Notes:
- The kit only renders the buttons. The OAuth flow itself is yours.

## UiPageDashboard  (pages)
Dashboard template: greeting hero, KPI tiles, occupancy chart, sales funnel, top list and activity feed.
Props:
- `title`: string. Page heading. The built-in header renders only when title is set and the header slot is empty.
- `subtitle`: string. Caption under the heading.
- `crumbs`: { label: string; href?: string }[]. Breadcrumb trail above the title.
Slots:
- header: Custom page header; replaces the built-in title/subtitle/crumbs header.
- actions: Buttons on the right of the built-in header. With a title they sit beside it; without a title they render alone, right-aligned (unless the header slot is filled).
- hero: Large greeting/plan block; Card variant="inverse" with Ring and a Button.
- kpis: Four key figures; KpiTile, StatsCard or KpiInline.
- occupancy: Per-day occupancy chart; OccupancyChart or MiniChart.
- funnel: Inquiry-to-payment funnel; SalesFunnel.
- top: Revenue leaderboard; DataTable with Progress share bars.
- activity: Recent actions, newest first; Timeline.
Notes:
- Place inside AppShell; fill only the slots you need.
- hero and kpis share a row, as do occupancy/funnel and top/activity; they wrap on narrow screens.

## UiPagePatterns  (pages)
Showcase template combining twelve recurring dashboard card patterns (banner, strips, stat lines, charts, lists).
Props:
- `title`: string. Page heading. The built-in header renders only when title is set and the header slot is empty.
- `subtitle`: string. Caption under the heading.
- `crumbs`: { label: string; href?: string }[]. Breadcrumb trail above the title.
Slots:
- header: Custom page header; replaces the built-in title/subtitle/crumbs header.
- actions: Buttons on the right of the built-in header. With a title they sit beside it; without a title they render alone, right-aligned (unless the header slot is filled).
- hero: Large banner; HeroBanner.
- strip: One card with four metrics; StatStrip with IconTile.
- statlines: Row of toned stat lines; StatLine (tone brand, sky, success, warning, danger).
- chartcard: Titled chart with menu and period select; ChartCard with PillSelect and OccupancyChart or MiniChart.
- tiles: Selectable tiles plus an add tile; TabTiles.
- listrows: Icon, title and value rows; StatRow.
- countries: Country amount rows; CountryRow.
- versus: Two values with a share bar; VersusBar.
- segbar: Composition bar with legend; SegBar.
- activity: Timeline of events; Timeline.
- actioncard: Card with collapse, refresh and close actions; ActionCard.
Notes:
- Place inside AppShell; fill only the slots you need.

## UiPageCrm  (pages)
CRM template: summary tiles, filters, pipeline board and call queue.
Props:
- `title`: string. Page heading. The built-in header renders only when title is set and the header slot is empty.
- `subtitle`: string. Caption under the heading.
- `crumbs`: { label: string; href?: string }[]. Breadcrumb trail above the title.
Slots:
- header: Custom page header; replaces the built-in title/subtitle/crumbs header.
- actions: Buttons on the right of the built-in header. With a title they sit beside it; without a title they render alone, right-aligned (unless the header slot is filled).
- summary: Tiles above the board (leads, amount, conversion, overdue); StatsCard or KpiTile.
- filters: Status tabs, search and period switch; Tabs, SearchInput, SegmentedControl, FilterChips.
- board: Stage columns with deal cards; PipelineBoard, KanbanColumn, DealCard.
- calls: Recent call queue; CallRow, CallCard, IncomingCall.
Notes:
- Place inside AppShell; fill only the slots you need.

## UiPageBookings  (pages)
Bookings list template: stats, toolbar, bulk-action bar, table and pagination.
Props:
- `title`: string. Page heading. The built-in header renders only when title is set and the header slot is empty.
- `subtitle`: string. Caption under the heading.
- `crumbs`: { label: string; href?: string }[]. Breadcrumb trail above the title.
Slots:
- header: Custom page header; replaces the built-in title/subtitle/crumbs header.
- actions: Buttons on the right of the built-in header. With a title they sit beside it; without a title they render alone, right-aligned (unless the header slot is filled).
- stats: Booking figures for the period; StatsCard.
- toolbar: Search, quick filters and export menu above the table; SearchInput, FilterChips, Dropdown.
- bulk: Selection bar shown when rows are selected; Alert with Buttons. Render it conditionally.
- table: Sortable, selectable table; DataTable.
- pager: Page numbers below the table; Pagination.
Notes:
- Place inside AppShell; fill only the slots you need.

## UiPageCatalog  (pages)
Catalog template with a filter sidebar and a card grid (hotels, tours).
Props:
- `title`: string. Page heading. The built-in header renders only when title is set and the header slot is empty.
- `subtitle`: string. Caption under the heading.
- `crumbs`: { label: string; href?: string }[]. Breadcrumb trail above the title.
Slots:
- header: Custom page header; replaces the built-in title/subtitle/crumbs header.
- actions: Buttons on the right of the built-in header. With a title they sit beside it; without a title they render alone, right-aligned (unless the header slot is filled).
- filters: Left filter column (price, rating, services); Slider, Rating, RadioGroup, Checkbox.
- toolbar: Search, view switch and sort above the grid; SearchInput, ToggleGroup, Select.
- grid: Responsive grid of cards; HotelCard or TourCard.
- pager: Pagination at the bottom; Pagination.
Notes:
- Place inside AppShell; fill only the slots you need.
- The filter column is 260 px wide; on phones put filters in a Drawer yourself.

## UiPageDetail  (pages)
Detail page template (hotel, tour): gallery, summary, tabs, history and a booking side card.
Props:
- `title`: string. Page heading. The built-in header renders only when title is set and the header slot is empty.
- `subtitle`: string. Caption under the heading.
- `crumbs`: { label: string; href?: string }[]. Breadcrumb trail above the title.
Slots:
- header: Custom page header; replaces the built-in title/subtitle/crumbs header.
- actions: Buttons on the right of the built-in header. With a title they sit beside it; without a title they render alone, right-aligned (unless the header slot is filled).
- gallery: Main photo with thumbnails; Gallery, Carousel, LazyImage.
- summary: Name, stars, rating, badges; Card with Badge and Rating.
- tabs: Description, amenities, reviews; Tabs with Descriptions or Accordion.
- history: What changed (status, notes, price); Timeline.
- booking: Right-hand booking card with dates, guests, price and CTA; Card, Select, NumberInput, Button.
Notes:
- Place inside AppShell; fill only the slots you need.
- gallery, summary, tabs and history are the main column; booking is the side column.

## UiPageSettings  (pages)
Settings template with a section sub-navigation and stacked settings sections.
Props:
- `title`: string. Page heading. The built-in header renders only when title is set and the header slot is empty.
- `subtitle`: string. Caption under the heading.
- `crumbs`: { label: string; href?: string }[]. Breadcrumb trail above the title.
Slots:
- header: Custom page header; replaces the built-in title/subtitle/crumbs header.
- actions: Buttons on the right of the built-in header. With a title they sit beside it; without a title they render alone, right-aligned (unless the header slot is filled).
- subnav: Left section menu; SubNav or Tabs.
- profile: Profile section; SettingsSection with TextField, PhoneInput.
- notifications: Delivery channels; SettingsSection with Switch.
- integrations: Service cards (connected, off, error); IntegrationCard.
- danger: Irreversible actions; Alert, red Button, ConfirmDialog.
Notes:
- Place inside AppShell; fill only the slots you need.

## UiPageUserList  (pages)
User or customer list template: stats, filters, toolbar, table and a right-hand add/edit drawer.
Props:
- `title`: string. Page heading. The built-in header renders only when title is set and the header slot is empty.
- `subtitle`: string. Caption under the heading.
- `crumbs`: { label: string; href?: string }[]. Breadcrumb trail above the title.
Slots:
- header: Custom page header; replaces the built-in title/subtitle/crumbs header.
- actions: Buttons on the right of the built-in header. With a title they sit beside it; without a title they render alone, right-aligned (unless the header slot is filled).
- stats: Figures above the table; StatStrip.
- filters: Filter selects in a card; Select.
- toolbar: Page size, search, export and Add button; Select, SearchInput, Button.
- table: Users table with checkboxes and actions; DataTable with UserCell, Chip, IconButton.
- drawer: Side panel rendered in the side column; Drawer with TextField, Select, Button.
Notes:
- Place inside AppShell; fill only the slots you need.

## UiPageProfile  (pages)
User profile template: cover header, tabs and two columns of about, activity and plan cards.
Props:
- `title`: string. Page heading. The built-in header renders only when title is set and the header slot is empty.
- `subtitle`: string. Caption under the heading.
- `crumbs`: { label: string; href?: string }[]. Breadcrumb trail above the title.
Slots:
- header: Custom page header; replaces the built-in title/subtitle/crumbs header.
- actions: Buttons on the right of the built-in header. With a title they sit beside it; without a title they render alone, right-aligned (unless the header slot is filled).
- profile: Cover with avatar, name and meta; ProfileHeader.
- tabs: Section tabs; PillTabs.
- about: Left column key-value info; Card with Descriptions.
- activity: Right column activity feed; Timeline.
- plan: Right column plan card and upgrade button; Card, Badge, Progress, Button.
Notes:
- Place inside AppShell; fill only the slots you need.

## UiPageForm  (pages)
Create/edit form template: main column, media, side column and header actions.
Props:
- `title`: string. Page heading. The built-in header renders only when title is set and the header slot is empty.
- `subtitle`: string. Caption under the heading.
- `crumbs`: { label: string; href?: string }[]. Breadcrumb trail above the title.
Slots:
- header: Custom page header; replaces the built-in title/subtitle/crumbs header.
- actions: Discard, Save draft and Publish buttons in the top-right of the built-in header; Button. Rendered right-aligned on their own when title is not set.
- main: Main column cards (info, options); Card, TextField, Textarea.
- media: Below main; upload dropzone; FileUpload or Gallery.
- side: Side column cards (price, status, tags); Card, NumberInput, Select, ChipInput.
Notes:
- Place inside AppShell; fill only the slots you need.

## UiPageOrder  (pages)
Order/booking details template: status chips, items table, timeline and side info cards.
Props:
- `title`: string. Page heading. The built-in header renders only when title is set and the header slot is empty.
- `subtitle`: string. Caption under the heading.
- `crumbs`: { label: string; href?: string }[]. Breadcrumb trail above the title.
Slots:
- header: Custom page header; replaces the built-in title/subtitle/crumbs header.
- actions: Buttons on the right of the built-in header. With a title they sit beside it; without a title they render alone, right-aligned (unless the header slot is filled).
- status: Payment and fulfillment chips; Chip (tone success, warning, danger).
- items: Items table with totals; DataTable.
- shipping: Event timeline; Timeline.
- side: Customer, address and payment cards; UserCell, Descriptions, Button.
Notes:
- Place inside AppShell; fill only the slots you need.

## UiPageAccount  (pages)
Account settings template with pill tabs and a swappable panel.
Props:
- `title`: string. Page heading. The built-in header renders only when title is set and the header slot is empty.
- `subtitle`: string. Caption under the heading.
- `crumbs`: { label: string; href?: string }[]. Breadcrumb trail above the title.
Slots:
- header: Custom page header; replaces the built-in title/subtitle/crumbs header.
- actions: Buttons on the right of the built-in header. With a title they sit beside it; without a title they render alone, right-aligned (unless the header slot is filled).
- tabs: Section tabs (account, security, billing, notifications); PillTabs.
- panel: Content of the active tab; Card or SettingsSection with Switch and TextField.
Notes:
- Place inside AppShell; fill only the slots you need.
- The template does not switch panels by itself: keep the active tab in your own state (PillTabs v-model) and render only that tab content in the panel slot.

## UiPagePricing  (pages)
Pricing template: billing-period toggle, plan cards and an FAQ.
Props:
- `title`: string. Page heading. The built-in header renders only when title is set and the header slot is empty.
- `subtitle`: string. Caption under the heading.
- `crumbs`: { label: string; href?: string }[]. Breadcrumb trail above the title.
Slots:
- header: Custom page header; replaces the built-in title/subtitle/crumbs header.
- actions: Buttons on the right of the built-in header. With a title they sit beside it; without a title they render alone, right-aligned (unless the header slot is filled).
- toggle: Monthly/annual switch with a savings badge; Switch, Chip.
- plans: Plan cards, one marked featured; PricingCard.
- faq: Questions accordion; Accordion.
Notes:
- Place inside AppShell; fill only the slots you need.

## UiPageFaq  (pages)
Help center template: search, categories, answers accordion and a contact block.
Props:
- `title`: string. Page heading. The built-in header renders only when title is set and the header slot is empty.
- `subtitle`: string. Caption under the heading.
- `crumbs`: { label: string; href?: string }[]. Breadcrumb trail above the title.
Slots:
- header: Custom page header; replaces the built-in title/subtitle/crumbs header.
- actions: Buttons on the right of the built-in header. With a title they sit beside it; without a title they render alone, right-aligned (unless the header slot is filled).
- search: Large search field; SearchInput.
- cats: Category list on the left; vertical PillTabs.
- answers: Answers on the right; Accordion.
- contact: Contact cards below; Card, IconTile, Button.
Notes:
- Place inside AppShell; fill only the slots you need.

## UiPageAuth  (pages)
Sign-in page template without the app shell, as a centered card or a split layout.
Props:
- `layout`: 'card' | 'split' | 'photo' | 'light' | 'tint' = "card". 'split' uses AuthSplit with a side panel. 'photo', 'light' and 'tint' use AuthShowcase with a media panel. Anything else renders a centered AuthLayout card over the background.
- `image`: string. Media image URL; photo, light and tint layouts.
- `headline`: string. Large text on the media panel; photo and tint.
- `caption`: string. Small text on the media panel or glass bar.
- `quote`: string. Bottom line of the media panel; photo only.
- `chips`: string[]. Pill labels in the glass bar; light and tint.
- `people`: { name: string; src?: string }[]. Avatars on the media panel or in the proof pill.
- `proof`: string. Social-proof title under the form; light and tint.
- `proofHint`: string. Second line of the proof pill.
- `title`: string. Form heading.
- `subtitle`: string. Text under the heading.
Slots:
- background: Decorative glows behind the card; card layout only.
- logo: Logo above the heading.
- aside: Brand panel on the left; split layout only, hidden below 820 px.
- form: Sign-in fields and button; LoginForm, TextField, PasswordInput, CodeInput, Button.
- footer: Links such as help, create account, back to login.
Notes:
- Designed for the dark theme and used without AppShell.

## UiPageStatus  (pages)
Full-page status screen (404, 401, maintenance, coming soon) with one action.
Props:
- `kind`: '404' | '401' | 'maintenance' | 'soon' = "404". Preset screen; selects default texts, the big code or icon, and the button label. Filled into every part whose slot is empty.
- `title`: string. Overrides the preset heading.
- `description`: string. Overrides the preset description.
- `onAction`: () => void. Primary button click.
- `actionLabel`: string. Overrides the preset button text (404, 401, maintenance).
- `notifyLabel`: string = "Notify me". Button text for kind "soon".
- `emailLabel`: string = "name@email.com". Placeholder of the email field for kind "soon".
Slots:
- code: Large code or icon; replaces the preset code only.
- message: Heading and description; replaces title and description.
- action: The primary button or an email form; replaces the preset action (onAction and actionLabel are then unused).
Events:
- action: Preset primary button clicked (not fired when the action slot is filled).
- notify: Called with the typed email when the Notify button of kind "soon" is clicked (not fired when the action slot is filled).
Notes:
- Slots replace only their own part: fill message and the preset code and button remain; kind, title, description, onAction and actionLabel apply to the parts whose slot is empty.
- kind="soon" shows an email field and a Notify me button; handle onNotify(email) to collect the address.