` attributes are forwarded.
### Events
| Event | Handler type | Description |
| --- | --- | --- |
| `change` | `(e: CustomEvent<{ value: string \| string[] }>) => void` | Called with `{ value }` after a selection changes. |
The legacy `on:name` form is accepted for every event.
### Snippets
| Snippet | Type | Description |
| --- | --- | --- |
| `children` | `Snippet` | Content rendered inside the component. |
### Types
#### `ToggleGroupMode`
Selection behaviour of a toggle group.
```ts
type ToggleGroupMode = 'single' | 'multiple' | 'none';
```
#### `ToggleGroupItem`
A toggle description or a plain string label.
```ts
type ToggleGroupItem =
| string
| {
value: string;
label?: string;
icon?: Icon;
disabled?: boolean;
};
```
### Tokens used
`--iv_radius` · `--iv_radius-lg` · `--iv_radius-sm` · `--iv_tg-radius`
See the [token reference](https://iv-ui.vercel.app/foundations/tokens.md) for values.
### CSS hooks
`.iv-checked` · `.iv-disabled` · `.iv-lg` · `.iv-sm` · `.iv-toggle` · `.iv-toggle-group` · `.iv-vertical`
## Accessibility
| Keys | Action |
| --- | --- |
| `Tab` | Moves focus through the toggles. |
| `Space / Enter` | Toggles the focused item. |
- The container uses `role="group"` and is named by `label`.
- Each option is a button with `aria-pressed`.
- Selection is never changed by arrow keys, so every item stays reachable with Tab.
## Related
- [Toggle](https://iv-ui.vercel.app/components/toggle.md)
- [ButtonGroup](https://iv-ui.vercel.app/components/button-group.md)
- [Tabs](https://iv-ui.vercel.app/components/tabs.md)
- [Button](https://iv-ui.vercel.app/components/button.md)
---
# ButtonGroup
Joins related buttons into one segmented control.
## Import
```svelte
import { ButtonGroup } from '@elluzion/iv-ui';
```
## Preview
A segmented control with one active option.
```svelte
```
## Usage
- `mode="none"` is a plain toolbar; `single` and `multiple` track selection.
- Items may be strings or `{ value, label, icon, disabled }`.
- `variant` applies to every button; `size` keeps the row consistent.
## Examples
### Multiple
Toggle several options and read the array value.
```svelte
```
### Props
| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `items` | `ButtonGroupItem[]` | `[]` | Buttons to render. Items may be strings or `{ value, label, icon, disabled }`. |
| `mode` | `ButtonGroupMode` | `'none'` | Selection behaviour: one value, many values, or none. |
| `value` **bindable** | `string \| string[]` | `mode === 'multiple' ? [] : ''` | Selected value(s). Bind with `bind:value`. |
| `label` | `string` | `''` | Accessible name for the group. |
| `className` | `string` | `''` | Extra classes merged onto the root element. |
| `size` | `'sm' \| 'md' \| 'lg'` | `'md'` | Control size. |
| `variant` | `ButtonGroupVariant` | `'secondary'` | Visual emphasis for every button in the group. |
| `orientation` | `'horizontal' \| 'vertical'` | `'horizontal'` | Stacking direction. |
| `disabled` | `boolean` | `false` | Disables interaction and applies the disabled treatment. |
| `fullWidth` | `boolean` | `false` | Stretches the group to the container width. |
All native `
` attributes are forwarded.
### Events
| Event | Handler type | Description |
| --- | --- | --- |
| `change` | `(e: CustomEvent<{ value: string \| string[] }>) => void` | Called with `{ value }` after a selection changes. |
The legacy `on:name` form is accepted for every event.
### Snippets
| Snippet | Type | Description |
| --- | --- | --- |
| `children` | `Snippet` | Content rendered inside the component. |
### Types
#### `ButtonGroupMode`
Selection behaviour of a button group.
```ts
type ButtonGroupMode = 'single' | 'multiple' | 'none';
```
#### `ButtonGroupVariant`
Emphasis applied to every button in the group.
```ts
type ButtonGroupVariant = 'primary' | 'secondary' | 'outline' | 'ghost' | 'danger';
```
#### `ButtonGroupItem`
A button description or a plain string label.
```ts
type ButtonGroupItem =
| string
| {
value: string;
label?: string;
icon?: Icon;
disabled?: boolean;
};
```
### Tokens used
`--iv_cursor` · `--iv_radius-sm` · `--iv_reverse-bg` · `--iv_reverse-fg` · `--iv_reverse-hover` · `--iv_surface`
See the [token reference](https://iv-ui.vercel.app/foundations/tokens.md) for values.
### CSS hooks
`.iv-btn` · `.iv-btn-group` · `.iv-disabled` · `.iv-full-width` · `.iv-selected` · `.iv-vertical`
## Accessibility
| Keys | Action |
| --- | --- |
| `Tab` | Moves focus through the group. |
| `Space / Enter` | Activates the focused button. |
- The container uses `role="group"` and is named by `label`.
- Selectable options expose `aria-pressed`; toolbar mode leaves it off.
- `disabled` disables every button in the group.
## Related
- [Button](https://iv-ui.vercel.app/components/button.md)
- [ToggleGroup](https://iv-ui.vercel.app/components/toggle-group.md)
- [Toggle](https://iv-ui.vercel.app/components/toggle.md)
- [Tabs](https://iv-ui.vercel.app/components/tabs.md)
---
# Accordion
A stack of collapsible sections; one or several can be open.
## Import
```svelte
import { Accordion, AccordionItem } from '@elluzion/iv-ui';
```
## Preview
Opening one section closes the previous one.
```svelte
Node 22 on Linux, with the edge cache in front of every request.
Static output is prerendered; the rest is bundled on demand.
Three regions, one primary and two read replicas.
```
## Usage
- Each `AccordionItem` needs a unique `value`; the parent tracks the open values.
- Set `multiple` to keep several panels open at once.
- Bind `value` for controlled state, or use `defaultValue` for an uncontrolled accordion.
## Examples
### Multiple
`multiple` keeps every opened section open.
```svelte
Node 22 on Linux, with the edge cache in front of every request.
Static output is prerendered; the rest is bundled on demand.
Three regions, one primary and two read replicas.
```
### Custom trigger
The `trigger` snippet replaces the title content.
```svelte
{#snippet trigger()}
Access control
{/snippet}
Roles are inherited from the organization; overrides live on the project.
Every privileged action is recorded with the actor and the request id.
```
### Accordion
| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `multiple` | `boolean` | `false` | Allows several items to stay open at once. |
| `value` **bindable** | `AccordionValue` | — | Open item value(s). Bind with `bind:value` for controlled state. |
| `defaultValue` | `AccordionValue` | — | Item(s) open on first render. |
| `disabled` | `boolean` | `false` | Disables interaction and applies the disabled treatment. |
| `className` | `string` | `''` | Extra classes merged onto the root element. |
`class`, `id`, `style`, `aria-*`, and `data-*` are forwarded through rest props.
### Events — Accordion
| Event | Handler type | Description |
| --- | --- | --- |
| `change` | `(e: CustomEvent<{ value: AccordionValue }>) => void` | Called with `{ value }` after an item opens or closes. |
The legacy `on:name` form is accepted for every event.
### Snippets — Accordion
| Snippet | Type | Description |
| --- | --- | --- |
| `children` | `Snippet` | Content rendered inside the component. |
### Types — Accordion
#### `AccordionValue`
One open item, or several when `multiple` is set.
```ts
type AccordionValue = string | string[];
```
### Tokens used
`--iv_border` · `--iv_radius`
See the [token reference](https://iv-ui.vercel.app/foundations/tokens.md) for values.
### CSS hooks
`.iv-accordion` · `.iv-disabled`
### AccordionItem
| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `value` **required** | `string` | — | Unique value used by the parent accordion to track this item. |
| `title` | `string` | `''` | Trigger text. Use the `trigger` snippet for custom content. |
| `disabled` | `boolean` | `false` | Disables interaction and applies the disabled treatment. |
### Snippets — AccordionItem
| Snippet | Type | Description |
| --- | --- | --- |
| `children` | `Snippet` | Panel content revealed when the item is open. |
| `trigger` | `Snippet` | Custom trigger content replacing the title. |
### Tokens used
`--iv_border` · `--iv_disabled-opacity` · `--iv_ease-out` · `--iv_font-ui` · `--iv_foreground` · `--iv_foreground-dim` · `--iv_leading-base` · `--iv_outline-width` · `--iv_spacing-lg` · `--iv_spacing-xl` · `--iv_surface-overlay` · `--iv_surface-raised` · `--iv_text-body` · `--iv_text-btn` · `--iv_transition-fast`
See the [token reference](https://iv-ui.vercel.app/foundations/tokens.md) for values.
### CSS hooks
`.iv-chevron` · `.iv-disabled` · `.iv-item` · `.iv-open` · `.iv-panel` · `.iv-trigger` · `.iv-trigger-label`
## Accessibility
| Keys | Action |
| --- | --- |
| `Tab` | Moves focus to the next trigger. |
| `Enter / Space` | Opens or closes the focused section. |
- Triggers are native buttons with `aria-expanded` and `aria-controls`.
- Panels use `role="region"` and are labelled by their trigger.
- Opening and closing respects `prefers-reduced-motion`.
## Related
- [Collapsible](https://iv-ui.vercel.app/components/collapsible.md)
- [Tabs](https://iv-ui.vercel.app/components/tabs.md)
- [Card](https://iv-ui.vercel.app/components/card.md)
- [Separator](https://iv-ui.vercel.app/components/separator.md)
---
# Article
A readable page body with an optional title and standfirst.
## Import
```svelte
import { Article } from '@elluzion/iv-ui';
```
## Preview
Headings, paragraphs, lists, and code receive the typeset automatically.
```svelte
The focus ring now follows the keyboard on every overlay. Dialogs open with a short scale, and
the entry animation is skipped when reduced motion is requested.
Fixes
Select keeps the active option visible while filtering.
Toast timers no longer close a newer message.
showToast('Deployed to production', 'success');
```
## Usage
- Body content is wrapped in `iv-prose`, so plain HTML inherits the typeset.
- `title` and `description` render a centered header with a hairline rule.
- `maxWidth` narrows the body measure; the default is 880px.
## Examples
### Measure
`maxWidth` tightens the reading column without touching the header.
```svelte
The body column is narrowed independently of the header. Use it for release notes,
documentation, or any surface that is mostly prose. Headings, lists, and code keep the same
typeset.
Short lines are easier to scan; long lines lose the reader between returns.
```
### Props
| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `title` | `string` | `''` | Article heading. |
| `description` | `string` | `''` | Standfirst shown below the heading. |
| `maxWidth` | `number` | `880` | Maximum measure in pixels. |
| `className` | `string` | `''` | Extra classes merged onto the root element. |
`class`, `id`, `style`, `aria-*`, and `data-*` are forwarded through rest props.
### Snippets
| Snippet | Type | Description |
| --- | --- | --- |
| `children` | `Snippet` | Content rendered inside the component. |
### Tokens used
`--iv_article-width` · `--iv_border` · `--iv_font-sans` · `--iv_foreground` · `--iv_foreground-dim` · `--iv_leading-heading` · `--iv_leading-prose` · `--iv_spacing-2xl` · `--iv_spacing-sm` · `--iv_text-label` · `--iv_text-xl` · `--iv_tracking-tight` · `--iv_weight-bold`
See the [token reference](https://iv-ui.vercel.app/foundations/tokens.md) for values.
### CSS hooks
`.iv-article` · `.iv-body` · `.iv-description` · `.iv-header` · `.iv-title`
## Accessibility
- The component renders a semantic `
` element.
- Keep heading levels in order inside the body; `title` renders an `h1`.
- Links and code inside the body keep the prose focus and contrast treatment.
## Related
- [Card](https://iv-ui.vercel.app/components/card.md)
- [Tabs](https://iv-ui.vercel.app/components/tabs.md)
- [Accordion](https://iv-ui.vercel.app/components/accordion.md)
- [Separator](https://iv-ui.vercel.app/components/separator.md)
---
# Breadcrumb
Shows the path to the current page.
## Import
```svelte
import { Breadcrumb } from '@elluzion/iv-ui';
```
## Preview
Links for ancestors and plain text for the current page.
```svelte
```
## Usage
- The last item without `href` renders as the current page.
- Pass a `separator` snippet to replace the default chevron.
- `ariaLabel` names the navigation landmark.
## Examples
### Icons
Each item can carry an icon snippet before its label.
```svelte
{#snippet home()} {/snippet}
{#snippet folder()} {/snippet}
```
### Custom separator
The `separator` snippet replaces the chevron.
```svelte
{#snippet separator()}/ {/snippet}
```
### Props
| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `items` **required** | `BreadcrumbItem[]` | — | Trail entries. The last item is rendered as the current page. |
| `ariaLabel` | `string` | `'Breadcrumb'` | Accessible name for the navigation landmark. |
| `className` | `string` | `''` | Extra classes merged onto the root element. |
`class`, `id`, `style`, `aria-*`, and `data-*` are forwarded through rest props.
### Snippets
| Snippet | Type | Description |
| --- | --- | --- |
| `separator` | `Snippet` | Custom separator snippet; defaults to `/`. |
### Types
#### `BreadcrumbItem`
One entry in a breadcrumb trail.
```ts
type BreadcrumbItem = {
label: string;
href?: string;
icon?: Snippet;
};
```
### Tokens used
`--iv_breadcrumb-pad-x` · `--iv_ease-in-out` · `--iv_font-mono` · `--iv_foreground` · `--iv_foreground-dim` · `--iv_leading-base` · `--iv_radius-sm` · `--iv_ring` · `--iv_ring-width` · `--iv_spacing-xs` · `--iv_surface-overlay` · `--iv_text-sm` · `--iv_transition-base` · `--iv_weight-medium`
See the [token reference](https://iv-ui.vercel.app/foundations/tokens.md) for values.
### CSS hooks
`.iv-breadcrumb` · `.iv-breadcrumb-item` · `.iv-breadcrumb-sep`
## Accessibility
- The trail is a `` with an accessible name.
- The current page uses `aria-current="page"`.
- Separators are hidden from assistive technology.
## Related
- [Tabs](https://iv-ui.vercel.app/components/tabs.md)
- [Card](https://iv-ui.vercel.app/components/card.md)
- [Article](https://iv-ui.vercel.app/components/article.md)
- [Separator](https://iv-ui.vercel.app/components/separator.md)
---
# Card
A bordered surface for grouped content and actions.
## Import
```svelte
import { Card } from '@elluzion/iv-ui';
```
## Preview
A title, description, and body content.
```svelte
98.4% of requests were served from the nearest edge.
```
## Usage
- `title`, `description`, and `action` build the standard header; `header` replaces it.
- Providing `onclick` makes the whole card a keyboard-reachable button.
- `footer` renders below the body; `padding="none"` lets lists manage their own spacing.
## Examples
### Header action
`action` places a control at the trailing edge of the header.
```svelte
{#snippet action()}
refreshed++}>Refresh
{/snippet}
Refreshed {refreshed} times.
```
### Interactive
`onclick` adds the button role, tab stop, and keyboard activation.
```svelte
opened++}
>
Opened {opened} times.
```
### States
Selected, hoverable, and disabled treatments.
```svelte
Reverse-video border and cursor marker.
No button role, no tab stop.
{}}>
Still readable.
```
### Props
| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `title` | `string` | `''` | Title text. |
| `description` | `string` | `''` | Supporting text. |
| `padding` | `'sm' \| 'md' \| 'lg' \| 'none'` | `'md'` | Inner padding. `none` is useful for lists that manage their own spacing. |
| `radius` | `'md' \| 'lg'` | `'md'` | Corner radius step. |
| `hoverable` | `boolean` | `false` | Adds the hover treatment without making the card interactive. |
| `selected` | `boolean` | `false` | Renders the selected treatment. |
| `disabled` | `boolean` | `false` | Disables interaction and applies the disabled treatment. |
| `className` | `string` | `''` | Extra classes merged onto the root element. |
`class`, `id`, `style`, `aria-*`, and `data-*` are forwarded through rest props.
### Events
| Event | Handler type | Description |
| --- | --- | --- |
| `click` | `(e: MouseEvent) => void` | Makes the card interactive and called on activation. |
The legacy `on:name` form is accepted for every event.
### Snippets
| Snippet | Type | Description |
| --- | --- | --- |
| `children` | `Snippet` | Content rendered inside the component. |
| `action` | `Snippet` | Slot in the header, right of the title. |
| `header` | `Snippet` | Replaces the default header. |
| `footer` | `Snippet` | Content rendered below the body. |
### Tokens used
`--iv_accent` · `--iv_accent-surface` · `--iv_border` · `--iv_border-focus` · `--iv_border-hover` · `--iv_card-pad-x` · `--iv_card-pad-x-lg` · `--iv_card-pad-x-sm` · `--iv_card-pad-y` · `--iv_card-pad-y-lg` · `--iv_card-pad-y-sm` · `--iv_cursor` · `--iv_disabled-opacity` · `--iv_ease-in-out` · `--iv_font-sans` · `--iv_font-ui` · `--iv_foreground` · `--iv_foreground-dim` · `--iv_hazard-stripe` · `--iv_radius` · `--iv_radius-lg` · `--iv_ring` · `--iv_ring-width` · `--iv_spacing-lg` · `--iv_spacing-sm` · `--iv_spacing-xs` · `--iv_surface-raised` · `--iv_text-base` · `--iv_text-label` · `--iv_transition-base`
See the [token reference](https://iv-ui.vercel.app/foundations/tokens.md) for values.
### CSS hooks
`.iv-action` · `.iv-body` · `.iv-card` · `.iv-clickable` · `.iv-description` · `.iv-disabled` · `.iv-footer` · `.iv-header` · `.iv-header-text` · `.iv-hoverable` · `.iv-pad-lg` · `.iv-pad-none` · `.iv-pad-sm` · `.iv-radius-lg` · `.iv-selected` · `.iv-title`
## Accessibility
| Keys | Action |
| --- | --- |
| `Tab` | Moves focus to an interactive card. |
| `Enter / Space` | Activates an interactive card. |
- An interactive card gets `role="button"`, `tabindex="0"`, and `aria-disabled` when disabled.
- Do not place buttons or links inside a card that is itself clickable; move them to `action` or `footer` and keep the card static.
- `hoverable` changes only the visual treatment and does not make the card interactive.
## Related
- [Article](https://iv-ui.vercel.app/components/article.md)
- [Accordion](https://iv-ui.vercel.app/components/accordion.md)
- [EmptyState](https://iv-ui.vercel.app/components/empty-state.md)
- [Separator](https://iv-ui.vercel.app/components/separator.md)
---
# Collapsible
A single section that expands to reveal content.
## Import
```svelte
import { Collapsible } from '@elluzion/iv-ui';
```
## Preview
A titled section that starts closed.
```svelte
accept: application/json
x-request-id: 8f2c1a
```
## Usage
- Use for one-off disclosure; use `Accordion` when sections form a set.
- `open` is bindable; `defaultOpen` sets the uncontrolled initial state.
- `trigger` replaces the default title and chevron content.
## Examples
### Controlled
Bind `open` and drive it from outside the component.
```svelte
Timeout, retry budget, and the cache policy for this route.
(open = true)}>Open
(open = false)}>Close
```
### Custom trigger
The trigger snippet replaces the title with custom content.
```svelte
{#snippet trigger()}
Console
{/snippet}
Open the command palette with the shortcut shown above.
```
### Props
| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `title` | `string` | `''` | Trigger text. |
| `open` **bindable** | `boolean` | — | Open state. Bind with `bind:open`. |
| `defaultOpen` | `boolean` | `false` | Open on first render when uncontrolled. |
| `disabled` | `boolean` | `false` | Disables interaction and applies the disabled treatment. |
| `className` | `string` | `''` | Extra classes merged onto the root element. |
`class`, `id`, `style`, `aria-*`, and `data-*` are forwarded through rest props.
### Events
| Event | Handler type | Description |
| --- | --- | --- |
| `change` | `(e: CustomEvent<{ open: boolean }>) => void` | Called with `{ open }` after the panel toggles. |
The legacy `on:name` form is accepted for every event.
### Snippets
| Snippet | Type | Description |
| --- | --- | --- |
| `trigger` | `Snippet` | Custom trigger content. |
| `children` | `Snippet` | Content rendered inside the component. |
### Tokens used
`--iv_border` · `--iv_ease-out` · `--iv_font-ui` · `--iv_foreground` · `--iv_foreground-dim` · `--iv_leading-base` · `--iv_outline-width` · `--iv_radius` · `--iv_spacing-lg` · `--iv_spacing-md` · `--iv_surface-overlay` · `--iv_surface-raised` · `--iv_text-body` · `--iv_text-btn` · `--iv_transition-fast` · `--iv_weight-medium`
See the [token reference](https://iv-ui.vercel.app/foundations/tokens.md) for values.
### CSS hooks
`.iv-chevron` · `.iv-collapsible` · `.iv-open` · `.iv-panel` · `.iv-trigger` · `.iv-trigger-label`
## Accessibility
| Keys | Action |
| --- | --- |
| `Tab` | Moves focus to the trigger. |
| `Enter / Space` | Opens or closes the section. |
- The trigger is a native button with `aria-expanded` and `aria-controls`.
- The panel uses `role="region"` and is labelled by the trigger.
- Animation is skipped when reduced motion is requested.
## Related
- [Accordion](https://iv-ui.vercel.app/components/accordion.md)
- [Card](https://iv-ui.vercel.app/components/card.md)
- [Tabs](https://iv-ui.vercel.app/components/tabs.md)
- [Separator](https://iv-ui.vercel.app/components/separator.md)
---
# Separator
A hairline rule that separates content.
## Import
```svelte
import { Separator } from '@elluzion/iv-ui';
```
## Preview
The default rule between stacked blocks.
```svelte
Build finished in 42 seconds.
Deploy started from the release branch.
```
## Usage
- `orientation="vertical"` needs a parent with a defined height.
- Add `label` for a centered caption on a horizontal rule.
- `spacing` controls the margin around the line.
## Examples
### Labeled
A centered caption splits the line into two segments.
```svelte
Read access is inherited from the organization.
Members listed below can deploy and roll back.
```
### Vertical
A vertical rule between inline items; the row provides the height.
```svelte
Build 42s
Tests 118
Size 84 kB
```
### Props
| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `orientation` | `'horizontal' \| 'vertical'` | `'horizontal'` | Line direction. |
| `label` | `string` | `''` | Optional text rendered in the middle of the line. |
| `spacing` | `'sm' \| 'md' \| 'lg'` | `'md'` | Vertical margin around the line. |
| `className` | `string` | `''` | Extra classes merged onto the root element. |
`class`, `id`, `style`, `aria-*`, and `data-*` are forwarded through rest props.
### Tokens used
`--iv_border` · `--iv_font-mono` · `--iv_foreground-dim` · `--iv_separator-size` · `--iv_spacing-2xl` · `--iv_spacing-lg` · `--iv_spacing-md` · `--iv_spacing-sm` · `--iv_text-sm` · `--iv_tracking-wide`
See the [token reference](https://iv-ui.vercel.app/foundations/tokens.md) for values.
### CSS hooks
`.iv-horizontal` · `.iv-label-text` · `.iv-labeled` · `.iv-line` · `.iv-separator` · `.iv-spacing-lg` · `.iv-spacing-sm` · `.iv-vertical`
## Accessibility
- The element exposes `role="separator"` with the matching orientation.
- The label is visual text; it is not part of the accessible name.
- Decorative line segments are hidden from assistive technology.
## Related
- [Card](https://iv-ui.vercel.app/components/card.md)
- [Breadcrumb](https://iv-ui.vercel.app/components/breadcrumb.md)
- [Accordion](https://iv-ui.vercel.app/components/accordion.md)
- [Article](https://iv-ui.vercel.app/components/article.md)
---
# Tabs
Switches between panels that share one context.
## Import
```svelte
import { Tabs, TabList, Tab, TabPanel } from '@elluzion/iv-ui';
```
## Preview
An uncontrolled group with the first tab selected.
```svelte
Overview
Deployments
Settings
Runtime, regions, and the current release.
Every run, with the commit and the duration.
Access, retention, and the deploy key.
```
## Usage
- `Tabs` owns the value; `TabList` holds `Tab` buttons; `TabPanel` shows matching content.
- Bind `value` for controlled state, or set `defaultValue` for an uncontrolled group.
- `bordered` wraps the list and panel in one frame.
## Examples
### Bordered
`bordered` frames the list and panel as one surface.
```svelte
Logs
Trace
12:04:18 deploy started
build → test → publish (4.2s)
```
### Sizes
`sm` and `md` tab heights.
```svelte
One
Two
Small tab content.
Second panel.
One
Two
Medium tab content.
Second panel.
```
### Tabs
| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `value` **bindable** | `string` | — | Selected tab value. Bind with `bind:value`. |
| `defaultValue` | `string` | `''` | Selected tab value on first render when uncontrolled. |
| `size` | `'sm' \| 'md'` | `'md'` | Tab height and padding. |
| `bordered` | `boolean` | `false` | Draws a border around the tab list and panel. |
| `className` | `string` | `''` | Extra classes merged onto the root element. |
`class`, `id`, `style`, `aria-*`, and `data-*` are forwarded through rest props.
### Events — Tabs
| Event | Handler type | Description |
| --- | --- | --- |
| `change` | `(e: CustomEvent<{ value: string }>) => void` | Called with `{ value }` after a tab is selected. |
The legacy `on:name` form is accepted for every event.
### Snippets — Tabs
| Snippet | Type | Description |
| --- | --- | --- |
| `children` | `Snippet` | Content rendered inside the component. |
### Tokens used
`--iv_border` · `--iv_radius`
See the [token reference](https://iv-ui.vercel.app/foundations/tokens.md) for values.
### CSS hooks
`.iv-bordered` · `.iv-tabs`
### TabList
| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `label` | `string` | `''` | Accessible name for the tab list. |
| `className` | `string` | `''` | Extra classes merged onto the root element. |
`class`, `id`, `style`, `aria-*`, and `data-*` are forwarded through rest props.
### Snippets — TabList
| Snippet | Type | Description |
| --- | --- | --- |
| `children` | `Snippet` | The tab buttons. |
### Tokens used
`--iv_border` · `--iv_spacing-xs`
See the [token reference](https://iv-ui.vercel.app/foundations/tokens.md) for values.
### CSS hooks
`.iv-tab-list`
### Tab
| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `value` **required** | `string` | — | Unique value matched by a tab panel. |
| `disabled` | `boolean` | `false` | Prevents selection and removes the tab from the tab order. |
| `className` | `string` | `''` | Extra classes merged onto the root element. |
`class`, `id`, `style`, `aria-*`, and `data-*` are forwarded through rest props.
### Snippets — Tab
| Snippet | Type | Description |
| --- | --- | --- |
| `children` | `Snippet` | Tab label. |
### Tokens used
`--iv_cursor` · `--iv_disabled-opacity` · `--iv_ease-out` · `--iv_font-ui` · `--iv_foreground` · `--iv_foreground-dim` · `--iv_outline-width` · `--iv_radius-sm` · `--iv_reverse-bg` · `--iv_reverse-fg` · `--iv_spacing-md` · `--iv_spacing-sm` · `--iv_text-body` · `--iv_text-btn-sm` · `--iv_transition-fast`
See the [token reference](https://iv-ui.vercel.app/foundations/tokens.md) for values.
### CSS hooks
`.iv-active` · `.iv-md` · `.iv-sm` · `.iv-tab`
### TabPanel
| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `value` **required** | `string` | — | Value of the tab that controls this panel. |
| `className` | `string` | `''` | Extra classes merged onto the root element. |
`class`, `id`, `style`, `aria-*`, and `data-*` are forwarded through rest props.
### Snippets — TabPanel
| Snippet | Type | Description |
| --- | --- | --- |
| `children` | `Snippet` | Panel content. |
### Tokens used
`--iv_foreground` · `--iv_foreground-dim` · `--iv_leading-base` · `--iv_outline-offset` · `--iv_outline-width` · `--iv_spacing-xl` · `--iv_text-body`
See the [token reference](https://iv-ui.vercel.app/foundations/tokens.md) for values.
### CSS hooks
`.iv-bordered` · `.iv-tab-panel`
## Accessibility
| Keys | Action |
| --- | --- |
| `Tab` | Moves focus into the tab list. |
| `Arrow left / right` | Moves to the previous or next tab. |
| `Home / End` | Moves to the first or last tab. |
| `Enter / Space` | Selects the focused tab. |
- The list uses `role="tablist"`; each tab controls a panel through `aria-controls`.
- Only the active tab is in the tab order; arrow keys provide the rest of the navigation.
- Panels use `role="tabpanel"` and are labelled by their tab.
## Related
- [Accordion](https://iv-ui.vercel.app/components/accordion.md)
- [ToggleGroup](https://iv-ui.vercel.app/components/toggle-group.md)
- [ButtonGroup](https://iv-ui.vercel.app/components/button-group.md)
- [Card](https://iv-ui.vercel.app/components/card.md)
---
# AlertDialog
A blocking confirmation that returns a decision through an action.
## Import
```svelte
import { AlertDialog } from '@elluzion/iv-ui';
```
## Preview
A title, a message, and a cancel/confirm pair.
```svelte
Publish release
published {published} times
```
## Usage
- Mount ` ` once in the root layout, then open it with `showAlertDialog({ ... })`.
- `actions` defaults to a single `OK` button; give each action a `variant` that matches its weight.
- Set `closeOnClick: false` to keep the dialog open, then close it yourself when the work finishes.
## Examples
### Destructive
A danger action with the delete verb in the label.
```svelte
Delete project
{#if deleted}
project deleted
{/if}
```
### Custom actions
Several actions, each with its own variant and handler.
```svelte
Close editor
last choice: {last}
```
### Tokens used
`--iv_blur` · `--iv_border` · `--iv_dialog-gap` · `--iv_dialog-sm` · `--iv_font-sans` · `--iv_font-ui` · `--iv_foreground` · `--iv_foreground-dim` · `--iv_leading-base` · `--iv_overlay` · `--iv_radius-lg` · `--iv_shadow-lg` · `--iv_spacing-2xl` · `--iv_spacing-lg` · `--iv_spacing-md` · `--iv_spacing-sm` · `--iv_spacing-xl` · `--iv_surface-raised` · `--iv_text-xl` · `--iv_z-overlay`
See the [token reference](https://iv-ui.vercel.app/foundations/tokens.md) for values.
### CSS hooks
`.iv-alertdialog` · `.iv-alertdialog-actions` · `.iv-alertdialog-message` · `.iv-alertdialog-title` · `.iv-backdrop`
### Functions
| Name | Type | Description |
| --- | --- | --- |
| `showAlertDialog(config)` | `AlertDialogState` | Opens the dialog with the given title, message, and actions. |
| `alertDialogState` | `Writable` | Store holding the current dialog, or `null` when closed. |
### Config
Passed to `showAlertDialog`.
| Name | Type | Description |
| --- | --- | --- |
| `title` | `string` | Dialog title and accessible name. |
| `message` | `string` | Body text describing the decision. |
| `actions` | `AlertDialogAction[]` | Buttons rendered in order; defaults to one `OK` action. |
| `closeOnBackdrop` | `boolean` | Closes when the backdrop is clicked. Defaults to `true`. |
| `closeOnEscape` | `boolean` | Closes on Escape. Defaults to `true`. |
| `onclose` | `() => void` | Called after the dialog closes for any reason. |
### Action
| Name | Type | Description |
| --- | --- | --- |
| `label` | `string` | Button text. |
| `variant` | `'primary' \| 'secondary' \| 'outline' \| 'ghost' \| 'danger'` | Button emphasis. |
| `size` | `'sm' \| 'md' \| 'lg'` | Button size. |
| `disabled` | `boolean` | Disables the action. |
| `closeOnClick` | `boolean` | Closes the dialog after the handler runs. Defaults to `true`. |
| `onClick` | `() => void` | Runs before the dialog closes. |
## Accessibility
| Keys | Action |
| --- | --- |
| `Tab` | Moves focus between the actions. |
| `Escape` | Closes the dialog unless `closeOnEscape` is false. |
- The surface uses `role="alertdialog"` and `aria-modal="true"`.
- Focus is trapped while open and restored when the dialog closes.
- The title names the dialog; the message is linked through `aria-describedby`.
## Related
- [Dialog](https://iv-ui.vercel.app/components/dialog.md)
- [Sheet](https://iv-ui.vercel.app/components/sheet.md)
- [Toast](https://iv-ui.vercel.app/components/toast.md)
- [Button](https://iv-ui.vercel.app/components/button.md)
---
# ContextMenu
Opens a menu at the pointer or from the keyboard Menu key.
## Import
```svelte
import { ContextMenu } from '@elluzion/iv-ui';
```
## Preview
Right-click the panel, or focus it and press Shift+F10.
```svelte
Right-click this panel
or focus it and press Shift+F10
last action: {last}
```
## Usage
- Wrap the area that owns the menu; `entries` uses the same shape as `Menu`.
- Right-click opens on pointer devices; `touchTrigger` picks the touch gesture.
- Shift+F10 or the Menu key opens it from the keyboard, anchored to the trigger.
## Examples
### Submenu
A submenu opens on hover or with the right arrow key.
```svelte
Right-click for the record actions
last action: {last}
```
### Touch trigger
`touchTrigger="click"` opens the menu with a tap.
```svelte
Tap for workspace actions
last action: {last}
```
### Props
| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `entries` **required** | `MenuEntry[]` | — | Menu structure: headers, items, separators, and submenus. |
| `label` | `string` | `''` | Accessible name for the menu. |
| `id` | `string` | `''` | Element id. A generated id is used when omitted. |
| `className` | `string` | `''` | Extra classes merged onto the root element. |
| `touchTrigger` | `'longpress' \| 'dblclick' \| 'click'` | `'longpress'` | Gesture that opens the menu on touch devices. |
### Events
| Event | Handler type | Description |
| --- | --- | --- |
| `click` | `(e: MouseEvent, entry: MenuEntry) => void` | Called with the native event and the activated entry. |
| `open` | `() => void` | Called after the layer opens. |
| `close` | `() => void` | Called when the layer requests to close. |
The legacy `on:name` form is accepted for every event.
### Snippets
| Snippet | Type | Description |
| --- | --- | --- |
| `children` | `Snippet` | The area that owns the context menu. |
### Tokens used
`--iv_border` · `--iv_popover-max-w` · `--iv_popover-min-w` · `--iv_radius` · `--iv_shadow-md` · `--iv_spacing-xs` · `--iv_surface-raised` · `--iv_z-dropdown`
See the [token reference](https://iv-ui.vercel.app/foundations/tokens.md) for values.
### CSS hooks
`.iv-cm-panel` · `.iv-cm-trigger` · `.iv-longpress` · `.iv-menu` · `.iv-ready`
## Accessibility
| Keys | Action |
| --- | --- |
| `Shift+F10 / Menu` | Opens the menu at the trigger. |
| `Arrow up / down` | Moves between items. |
| `Arrow right / left` | Opens or closes a submenu. |
| `Enter / Space` | Activates the focused item. |
| `Escape` | Closes the menu and returns focus to the trigger. |
- The panel uses `role="menu"` and items use `role="menuitem"`.
- Opening moves focus to the first item; closing restores the previous focus.
- Clicks outside the panel close it.
## Related
- [Menu](https://iv-ui.vercel.app/components/menu.md)
- [Popover](https://iv-ui.vercel.app/components/popover.md)
- [Dialog](https://iv-ui.vercel.app/components/dialog.md)
- [Tooltip](https://iv-ui.vercel.app/components/tooltip.md)
---
# Dialog
A modal surface for focused tasks and confirmations.
## Import
```svelte
import { Dialog } from '@elluzion/iv-ui';
```
## Preview
A title, body content, and the close control.
```svelte
(open = true)}>Rename project
(open = false)}>
The new name appears in the switcher and in every deploy record.
```
## Usage
- `open` is required and not bindable; set it to false from `onclose` to complete the close.
- `footer` holds the actions; `size` caps the width.
- Focus is trapped while open and restored on close.
## Examples
### Sizes
One dialog with a switchable `sm`, `md`, or `lg` width.
```svelte
((size = 'sm'), (open = true))}>Small
((size = 'md'), (open = true))}
>Medium
((size = 'lg'), (open = true))}>Large
(open = false)}>
The width is capped at the chosen step; content wraps inside it.
```
### Footer
Cancel and primary actions rendered in the footer.
```svelte
(open = true)}>Edit retention
(open = false)}>
Logs older than the selected window are removed at the next sweep.
{#snippet footer()}
(open = false)}>Cancel
{
open = false;
saved = true;
}}>Save
{/snippet}
{#if saved}
policy saved
{/if}
```
### Props
| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `open` **required** | `boolean` | `false` | Whether the dialog is visible. Set it to false from `onclose` to complete the close. |
| `title` | `string` | `''` | Dialog title; also used as the accessible name. |
| `size` | `'sm' \| 'md' \| 'lg'` | `'md'` | Maximum dialog width. |
| `closeOnBackdrop` | `boolean` | `true` | Closes when the backdrop is clicked. |
| `closeOnEscape` | `boolean` | `true` | Closes on Escape. |
`class`, `id`, `style`, `aria-*`, and `data-*` are forwarded through rest props.
### Events
| Event | Handler type | Description |
| --- | --- | --- |
| `close` | `() => void` | Called when the dialog requests to close; set `open = false` in response. |
The legacy `on:name` form is accepted for every event.
### Snippets
| Snippet | Type | Description |
| --- | --- | --- |
| `children` | `Snippet` | Content rendered inside the component. |
| `icon` | `Snippet` | Icon rendered before the title. |
| `footer` | `Snippet` | Actions rendered below the body. |
### Tokens used
`--iv_blur` · `--iv_border` · `--iv_dialog-gap` · `--iv_dialog-lg` · `--iv_dialog-md` · `--iv_dialog-sm` · `--iv_ease-in-out` · `--iv_font-sans` · `--iv_foreground` · `--iv_foreground-dim` · `--iv_overlay` · `--iv_radius-lg` · `--iv_radius-sm` · `--iv_ring` · `--iv_ring-width` · `--iv_shadow-lg` · `--iv_spacing-2xl` · `--iv_spacing-lg` · `--iv_spacing-md` · `--iv_spacing-sm` · `--iv_spacing-xl` · `--iv_surface-raised` · `--iv_text-xl` · `--iv_transition-base` · `--iv_z-overlay`
See the [token reference](https://iv-ui.vercel.app/foundations/tokens.md) for values.
### CSS hooks
`.iv-backdrop` · `.iv-body` · `.iv-body-no-title` · `.iv-close-btn` · `.iv-dialog` · `.iv-dialog-lg` · `.iv-dialog-sm` · `.iv-footer` · `.iv-header` · `.iv-icon-slot` · `.iv-title-area`
## Accessibility
| Keys | Action |
| --- | --- |
| `Tab` | Cycles focus inside the dialog. |
| `Escape` | Closes the dialog unless `closeOnEscape` is false. |
- The surface uses `role="dialog"` and `aria-modal="true"`.
- `title` is used for `aria-labelledby`; the body is linked through `aria-describedby`.
- The backdrop click only closes when the click starts on the backdrop itself.
## Related
- [Sheet](https://iv-ui.vercel.app/components/sheet.md)
- [AlertDialog](https://iv-ui.vercel.app/components/alert-dialog.md)
- [Popover](https://iv-ui.vercel.app/components/popover.md)
- [Card](https://iv-ui.vercel.app/components/card.md)
---
# Menu
A vertical list of commands, options, or links.
## Import
```svelte
import { Menu } from '@elluzion/iv-ui';
```
## Preview
A header, items with shortcuts, and a separator.
```svelte
```
## Usage
- `entries` is a typed list of headers, items, separators, and submenus.
- `semantic="listbox"` switches the roles for selection menus; pair it with `multiselect`.
- `onclick` receives the native event and the activated entry.
## Examples
### Listbox
Selection semantics with selected rows and a multiple mode.
```svelte
selected: {selected.join(', ') || '—'}
```
### Submenu
A nested menu that opens on hover or the right arrow key.
```svelte
```
### Props
| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `entries` | `MenuEntry[]` | `[]` | Menu structure: headers, items, separators, and submenus. |
| `semantic` | `MenuSemantic` | `'menu'` | ARIA role: a command menu or a listbox. |
| `multiselect` | `boolean` | `false` | Allows several items to show as selected. |
| `emptyLabel` | `string` | `''` | Text shown when there are no entries. |
| `label` | `string` | `''` | Accessible name for the menu. |
| `id` | `string` | `''` | Element id. A generated id is used when omitted. |
| `className` | `string` | `''` | Extra classes merged onto the root element. |
### Events
| Event | Handler type | Description |
| --- | --- | --- |
| `click` | `(e: MouseEvent, entry: MenuEntry) => void` | Called with the native event and the activated entry. |
The legacy `on:name` form is accepted for every event.
### Types
#### `MenuSemantic`
ARIA role used for the menu container.
```ts
type MenuSemantic = 'menu' | 'listbox';
```
#### `MenuItem`
A single actionable menu row.
```ts
interface MenuItem {
label: string;
icon?: Icon;
shortcut?: string;
trailingIcon?: Icon;
disabled?: boolean;
dim?: boolean;
selected?: boolean;
active?: boolean;
onclick?: (e: MouseEvent) => void;
onmouseenter?: (e: MouseEvent) => void;
}
```
#### `MenuEntry`
One row of the menu structure, including headers and separators.
```ts
type MenuEntry =
| { type: 'header'; id: string; label: string }
| { type: 'separator'; id: string }
| { type: 'item'; id: string; item: MenuItem }
| {
type: 'submenu';
id: string;
label: string;
icon?: Icon;
children: MenuEntry[];
disabled?: boolean;
};
```
### Tokens used
`--iv_border` · `--iv_bracket` · `--iv_disabled-opacity` · `--iv_ease-out` · `--iv_font-mono` · `--iv_font-ui` · `--iv_foreground` · `--iv_foreground-dim` · `--iv_menu-lead-size` · `--iv_radius` · `--iv_radius-sm` · `--iv_reverse-bg` · `--iv_reverse-fg` · `--iv_shadow-sm` · `--iv_spacing-md` · `--iv_spacing-sm` · `--iv_spacing-xs` · `--iv_submenu-min-w` · `--iv_surface-hover` · `--iv_surface-raised` · `--iv_text-body` · `--iv_text-label` · `--iv_text-sm` · `--iv_text-xs` · `--iv_tracking-wide` · `--iv_transition-fast` · `--iv_z-dropdown`
See the [token reference](https://iv-ui.vercel.app/foundations/tokens.md) for values.
### CSS hooks
`.iv-active` · `.iv-checkbox` · `.iv-checked` · `.iv-dim` · `.iv-disabled` · `.iv-empty` · `.iv-item` · `.iv-label` · `.iv-leading` · `.iv-menu` · `.iv-section-header` · `.iv-selected` · `.iv-separator` · `.iv-shortcut` · `.iv-submenu` · `.iv-submenu-item` · `.iv-trailing`
## Accessibility
- Headers and separators are visual structure; items carry `menuitem` or `option`.
- Selected items expose `aria-checked` in menu mode and `aria-selected` in listbox mode.
- Items are not in the tab order by design — place the menu in `ContextMenu` or move focus yourself.
## Related
- [ContextMenu](https://iv-ui.vercel.app/components/context-menu.md)
- [Select](https://iv-ui.vercel.app/components/select.md)
- [Popover](https://iv-ui.vercel.app/components/popover.md)
- [Shortcut](https://iv-ui.vercel.app/components/shortcut.md)
---
# Popover
A floating panel anchored to an element.
## Import
```svelte
import { Popover } from '@elluzion/iv-ui';
```
## Preview
Click the trigger to toggle the panel; Escape or an outside click closes it.
```svelte
Filters
Active filters
Branch: main · Status: failed · Author: any
```
## Usage
- `anchor` takes an element or a selector; the panel is positioned against it.
- `showOn` and `hideOn` choose the trigger events; combine `hover` with `interactive` to keep the panel open while hovered.
- Bind `open` to control the panel from your own state.
## Examples
### Hover
Open on hover or focus and keep the panel interactive.
```svelte
Hover or focus me
The panel stays open while the pointer is inside it.
```
### Placement
Change the preferred side; the panel flips when space runs out.
```svelte
{#each ['top', 'bottom', 'left', 'right'] as side (side)}
(placement = side as PopoverPlacement)}
>
{side}
{/each}
Toggle panel
Preferred side: {placement}. The panel flips when space runs out.
```
### Props
| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `open` **bindable** | `boolean` | `false` | Whether the popover is open. Bind with `bind:open`. |
| `anchor` | `string \| HTMLElement \| null` | `null` | Element or selector the popover is positioned against. |
| `placement` | `PopoverPlacement` | `'bottom'` | Preferred side of the anchor. |
| `align` | `PopoverAlign` | `'center'` | Alignment along the chosen side. |
| `gap` | `number` | `8` | Distance from the anchor in pixels. |
| `closeOnOutside` | `boolean` | `true` | Closes when a click lands outside the popover. |
| `closeOnEscape` | `boolean` | `true` | Closes on Escape. |
| `interactive` | `boolean` | `true` | Keeps the popover open while it is hovered or focused. |
| `showOn` | `PopoverShowEvent[]` | `['click']` | Events that open the popover. |
| `hideOn` | `PopoverHideEvent[]` | `['click']` | Events that close the popover. |
| `className` | `string` | `''` | Extra classes merged onto the root element. |
### Events
| Event | Handler type | Description |
| --- | --- | --- |
| `open` | `() => void` | Called after the popover opens. |
| `close` | `() => void` | Called after the popover closes. |
| `click` | `(e: MouseEvent) => void` | Called when the element is activated. |
The legacy `on:name` form is accepted for every event.
### Snippets
| Snippet | Type | Description |
| --- | --- | --- |
| `children` | `Snippet` | Content rendered inside the component. |
### Types
#### `PopoverPlacement`
Side of the anchor the popover prefers.
```ts
type PopoverPlacement = 'top' | 'bottom' | 'left' | 'right';
```
#### `PopoverAlign`
Alignment along the popover edge.
```ts
type PopoverAlign = 'start' | 'center' | 'end';
```
#### `PopoverShowEvent`
Events that can open a popover.
```ts
type PopoverShowEvent = 'click' | 'hover' | 'focus';
```
#### `PopoverHideEvent`
Events that can close a popover.
```ts
type PopoverHideEvent = 'click' | 'hover' | 'blur';
```
### Tokens used
`--iv_border` · `--iv_font-mono` · `--iv_popover-max-w` · `--iv_popover-min-w` · `--iv_radius-sm` · `--iv_shadow-md` · `--iv_surface-raised` · `--iv_z-dropdown`
See the [token reference](https://iv-ui.vercel.app/foundations/tokens.md) for values.
### CSS hooks
`.iv-panel` · `.iv-root`
## Accessibility
| Keys | Action |
| --- | --- |
| `Enter / Space` | Toggles a click-triggered popover. |
| `Escape` | Closes the popover. |
- The anchor receives `aria-haspopup`, `aria-expanded`, and `aria-controls` while the panel is open.
- An interactive panel uses `role="dialog"` with `aria-modal="false"`.
- The panel is clamped to the viewport and repositioned on scroll and resize.
## Related
- [Tooltip](https://iv-ui.vercel.app/components/tooltip.md)
- [Menu](https://iv-ui.vercel.app/components/menu.md)
- [Dialog](https://iv-ui.vercel.app/components/dialog.md)
- [ContextMenu](https://iv-ui.vercel.app/components/context-menu.md)
---
# Sheet
A panel that slides in from an edge for secondary flows.
## Import
```svelte
import { Sheet } from '@elluzion/iv-ui';
```
## Preview
One sheet that slides in from any of the four edges.
```svelte
{#each ['left', 'right', 'top', 'bottom'] as edge (edge)}
{
side = edge as SheetSide;
open = true;
}}>{edge}
{/each}
The panel slides in from the chosen edge and traps focus until it closes.
```
## Usage
- `side` chooses the edge; `size` sets the width, or the height for top and bottom sheets.
- Bind `open`; the component closes itself and calls `onclose` when dismissed.
- Use for filters, details, or compact forms; use `Dialog` for a decision.
## Examples
### Sizes
`sm`, `md`, `lg`, and `full` width steps.
```svelte
{#each ['sm', 'md', 'lg', 'full'] as step (step)}
{
size = step as SheetSize;
open = true;
}}>{step}
{/each}
Width is capped by the size step; full takes the whole viewport.
```
### Footer
A sticky footer keeps the actions in reach.
```svelte
(open = true)}>Edit workspace
{#snippet footer()}
(open = false)}>Cancel
{
open = false;
saved = true;
}}>Save
{/snippet}
{#if saved}
saved {name}
{/if}
```
### Props
| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `open` **required** **bindable** | `boolean` | `false` | Whether the sheet is visible. Bind with `bind:open`. |
| `side` | `SheetSide` | `'bottom'` | Edge the sheet slides in from. |
| `size` | `SheetSize` | `'md'` | Sheet width (or height for top/bottom sheets). |
| `title` | `string` | `''` | Sheet title; also used as the accessible name. |
| `closeOnBackdrop` | `boolean` | `true` | Closes when the backdrop is clicked. |
| `closeOnEscape` | `boolean` | `true` | Closes on Escape. |
| `showCloseButton` | `boolean` | `true` | Shows the header close button. |
| `className` | `string` | `''` | Extra classes merged onto the root element. |
`class`, `id`, `style`, `aria-*`, and `data-*` are forwarded through rest props.
### Events
| Event | Handler type | Description |
| --- | --- | --- |
| `close` | `() => void` | Called when the sheet requests to close; set `open = false` in response. |
The legacy `on:name` form is accepted for every event.
### Snippets
| Snippet | Type | Description |
| --- | --- | --- |
| `children` | `Snippet` | Content rendered inside the component. |
| `icon` | `Snippet` | Icon rendered before the title. |
| `footer` | `Snippet` | Actions rendered below the body. |
### Types
#### `SheetSide`
Edge the sheet slides in from.
```ts
type SheetSide = 'left' | 'right' | 'top' | 'bottom';
```
#### `SheetSize`
Sheet width or height step.
```ts
type SheetSize = 'sm' | 'md' | 'lg' | 'full';
```
### Tokens used
`--iv_blur` · `--iv_border` · `--iv_ease-in-out` · `--iv_font-sans` · `--iv_foreground` · `--iv_foreground-dim` · `--iv_overlay` · `--iv_radius-lg` · `--iv_radius-sm` · `--iv_ring` · `--iv_ring-width` · `--iv_shadow-lg` · `--iv_sheet-lg` · `--iv_sheet-md` · `--iv_sheet-sm` · `--iv_spacing-2xl` · `--iv_spacing-lg` · `--iv_spacing-md` · `--iv_spacing-sm` · `--iv_spacing-xl` · `--iv_surface-raised` · `--iv_text-xl` · `--iv_transition-base` · `--iv_z-overlay`
See the [token reference](https://iv-ui.vercel.app/foundations/tokens.md) for values.
### CSS hooks
`.iv-backdrop` · `.iv-body` · `.iv-body-no-title` · `.iv-close-btn` · `.iv-footer` · `.iv-header` · `.iv-icon-slot` · `.iv-sheet` · `.iv-sheet-full` · `.iv-sheet-lg` · `.iv-sheet-sm` · `.iv-side-bottom` · `.iv-side-left` · `.iv-side-right` · `.iv-side-top` · `.iv-title-area`
## Accessibility
| Keys | Action |
| --- | --- |
| `Tab` | Cycles focus inside the sheet. |
| `Escape` | Closes the sheet unless `closeOnEscape` is false. |
- The surface uses `role="dialog"` and `aria-modal="true"`.
- The title names the sheet; the body is linked through `aria-describedby`.
- Focus is trapped while open and restored on close.
## Related
- [Dialog](https://iv-ui.vercel.app/components/dialog.md)
- [AlertDialog](https://iv-ui.vercel.app/components/alert-dialog.md)
- [Popover](https://iv-ui.vercel.app/components/popover.md)
- [Card](https://iv-ui.vercel.app/components/card.md)
---
# Toast
A single transient notification driven by the toast store.
## Import
```svelte
import { Toast } from '@elluzion/iv-ui';
```
## Preview
Info, success, and error; the last one is announced assertively.
```svelte
showToast('Build queued for main.', 'info')}>
Info
showToast('Deployed to production.', 'success')}>
Success
showToast('Deploy failed: exit code 1.', 'error')}>
Error
```
## Usage
- Mount ` ` once in the root layout.
- Call `showToast(message, type, durationMs)`; only one toast is visible at a time.
- `hideToast()` clears it immediately; an id guard stops an old timer from closing a newer toast.
## Examples
### Duration
The third argument sets the visible time in milliseconds.
```svelte
showToast('Quick confirmation', 'success', 2000)}>
2 seconds
showToast('Longer confirmation', 'info', 10000)}>
10 seconds
```
### Dismiss
`hideToast()` closes the current toast from your own control.
```svelte
showToast('Waiting for your response…', 'info', 30000)}>
Show
hideToast()}>Dismiss
```
### Tokens used
`--iv_border` · `--iv_error` · `--iv_error-dim` · `--iv_font-mono` · `--iv_foreground` · `--iv_info` · `--iv_outline-offset` · `--iv_outline-width` · `--iv_radius-sm` · `--iv_shadow-md` · `--iv_spacing-md` · `--iv_spacing-sm` · `--iv_success` · `--iv_surface-overlay` · `--iv_surface-raised` · `--iv_text-body` · `--iv_toast-close-size` · `--iv_toast-min-w` · `--iv_z-toast`
See the [token reference](https://iv-ui.vercel.app/foundations/tokens.md) for values.
### CSS hooks
`.iv-close` · `.iv-content` · `.iv-toast` · `.iv-toast-error` · `.iv-toast-info` · `.iv-toast-layer` · `.iv-toast-success`
### Functions
| Name | Type | Description |
| --- | --- | --- |
| `showToast(message, type?, durationMs?)` | `(message: string, type?: ToastType, durationMs?: number) => void` | Shows a toast, replacing the current one. The default duration is 5000 ms. |
| `hideToast(id?)` | `(id?: number) => void` | Hides the toast. With an id, only hides it when that toast is still active. |
| `toastState` | `Writable` | Store holding the active toast, or `null` when hidden. |
### Options
| Name | Type | Description |
| --- | --- | --- |
| `type` | `'info' \| 'success' \| 'error'` | Controls the icon and accent. Defaults to `info`. |
| `durationMs` | `number` | Visible time in milliseconds; clamped to at least 800 ms. |
## Accessibility
- The layer uses `role="status"` with `aria-live="polite"` for info and success.
- Errors use `role="alert"` with `aria-live="assertive"`.
- The dismiss control has an accessible name.
- Only one toast exists at a time, so messages do not stack up.
## Related
- [Alert](https://iv-ui.vercel.app/components/alert.md)
- [Dialog](https://iv-ui.vercel.app/components/dialog.md)
- [Popover](https://iv-ui.vercel.app/components/popover.md)
- [Badge](https://iv-ui.vercel.app/components/badge.md)
---
# Tooltip
A short label shown on hover or focus.
## Import
```svelte
import { Tooltip } from '@elluzion/iv-ui';
```
## Preview
The preferred side flips automatically when space runs out.
```svelte
{#each ['top', 'bottom', 'left', 'right'] as side (side)}
{side}
{/each}
```
## Usage
- Wrap the trigger; `label` is the tooltip text and the child stays the trigger.
- `delay` defaults to 300 ms; Escape hides an open tooltip.
- Tooltips supplement a visible label; they never replace one.
## Examples
### Delay
A short delay for dense toolbars, a longer one for prose.
```svelte
No delay
Long delay
```
### Custom content
The `content` snippet can hold a shortcut, a hint, or both.
```svelte
{#snippet content()}
Command palette
{/snippet}
Open palette
```
### Props
| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `label` | `string` | `''` | Tooltip text. |
| `position` | `TooltipPosition` | `'top'` | Preferred side of the trigger. |
| `delay` | `number` | `300` | Delay before showing, in milliseconds. |
| `disabled` | `boolean` | `false` | Disables interaction and applies the disabled treatment. |
| `className` | `string` | `''` | Extra classes merged onto the root element. |
### Snippets
| Snippet | Type | Description |
| --- | --- | --- |
| `content` | `Snippet` | Custom tooltip content replacing the label. |
| `children` | `Snippet` | The trigger element. |
### Types
#### `TooltipPosition`
Side of the trigger the tooltip prefers.
```ts
type TooltipPosition = 'top' | 'bottom' | 'left' | 'right';
```
### Tokens used
`--iv_border-hover` · `--iv_font-mono` · `--iv_foreground` · `--iv_leading-tight` · `--iv_radius-sm` · `--iv_shadow-md` · `--iv_spacing-md` · `--iv_spacing-xs` · `--iv_surface-elevated` · `--iv_text-body-sm` · `--iv_z-dropdown`
See the [token reference](https://iv-ui.vercel.app/foundations/tokens.md) for values.
### CSS hooks
`.iv-ready` · `.iv-root` · `.iv-tooltip`
## Accessibility
| Keys | Action |
| --- | --- |
| `Escape` | Hides an open tooltip. |
- The wrapper points at the tooltip with `aria-describedby` only while it is visible.
- Focus and hover both open the tooltip; leaving or blurring closes it.
- Touch devices do not show hover tooltips, so keep the information available in the interface.
## Related
- [Popover](https://iv-ui.vercel.app/components/popover.md)
- [Shortcut](https://iv-ui.vercel.app/components/shortcut.md)
- [Menu](https://iv-ui.vercel.app/components/menu.md)
- [Button](https://iv-ui.vercel.app/components/button.md)
---
# Alert
An inline message for information, success, warning, or error.
## Import
```svelte
import { Alert } from '@elluzion/iv-ui';
```
## Preview
Info, success, warning, and error share one layout.
```svelte
The edge network is read-only on Sunday from 02:00 to 03:00 UTC.
Version 0.2.0 is live in all three regions.
The deploy token expires in six days.
The type check reported two errors in the docs package.
```
## Usage
- `type` sets the icon and accent; `error` maps to `role="alert"`.
- `dismissible` adds a close button wired to `ondismiss`.
- Keep the body to a sentence or two; use `title` for the headline.
## Examples
### Dismissible
The close button calls `ondismiss`; the parent removes the alert.
```svelte
{#if visible}
(visible = false)}
>
Reload to pick up the latest build.
{:else}
(visible = true)}>Restore alert
{/if}
```
### Body only
A title is optional; children carry the message.
```svelte
This project uses 92% of its monthly build minutes.
```
### Props
| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `type` | `'info' \| 'success' \| 'warning' \| 'error'` | `'info'` | Status family; controls the icon and color treatment. |
| `title` | `string` | `''` | Short headline for the message. |
| `dismissible` | `boolean` | `false` | Shows a close button. |
| `className` | `string` | `''` | Extra classes merged onto the root element. |
`class`, `id`, `style`, `aria-*`, and `data-*` are forwarded through rest props.
### Events
| Event | Handler type | Description |
| --- | --- | --- |
| `dismiss` | `() => void` | Called when the close button is pressed. |
The legacy `on:name` form is accepted for every event.
### Snippets
| Snippet | Type | Description |
| --- | --- | --- |
| `children` | `Snippet` | Message body. |
### Tokens used
`--iv_border` · `--iv_error` · `--iv_error-surface` · `--iv_font-sans` · `--iv_font-ui` · `--iv_foreground` · `--iv_foreground-dim` · `--iv_info` · `--iv_info-surface` · `--iv_leading-base` · `--iv_leading-tight` · `--iv_outline-offset` · `--iv_outline-width` · `--iv_radius-sm` · `--iv_spacing-lg` · `--iv_spacing-md` · `--iv_spacing-sm` · `--iv_spacing-xl` · `--iv_success` · `--iv_success-surface` · `--iv_surface-overlay` · `--iv_surface-raised` · `--iv_text-body` · `--iv_text-sm` · `--iv_weight-semibold`
See the [token reference](https://iv-ui.vercel.app/foundations/tokens.md) for values.
### CSS hooks
`.iv-alert` · `.iv-alert-body` · `.iv-alert-close` · `.iv-alert-content` · `.iv-alert-error` · `.iv-alert-icon` · `.iv-alert-info` · `.iv-alert-success` · `.iv-alert-title` · `.iv-alert-warning`
## Accessibility
- Error alerts use `role="alert"`; the other types use `role="status"`.
- The icon is decorative and hidden from assistive technology.
- The close button has an accessible name and a visible focus ring.
## Related
- [Toast](https://iv-ui.vercel.app/components/toast.md)
- [EmptyState](https://iv-ui.vercel.app/components/empty-state.md)
- [Badge](https://iv-ui.vercel.app/components/badge.md)
- [Card](https://iv-ui.vercel.app/components/card.md)
---
# EmptyState
Explains why an area has no content and offers the next step.
## Import
```svelte
import { EmptyState } from '@elluzion/iv-ui';
```
## Preview
A title and one line of explanation.
```svelte
```
## Usage
- `title` states the condition; `description` says what to do next.
- `action` holds the primary button; `icon` takes a snippet.
- Use `children` for secondary detail below the description.
## Examples
### With action
The primary action sits below the description.
```svelte
{#snippet action()}
Create query
{/snippet}
```
### With icon
An icon snippet anchors the state without adding noise.
```svelte
{#snippet icon()} {/snippet}
```
### Props
| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `title` | `string` | `''` | Headline for the empty state. |
| `description` | `string` | `''` | Explanation of why the area is empty. |
| `className` | `string` | `''` | Extra classes merged onto the root element. |
### Snippets
| Snippet | Type | Description |
| --- | --- | --- |
| `icon` | `Snippet` | Illustration or icon shown above the title. |
| `action` | `Snippet` | Primary action, usually a button. |
| `children` | `Snippet` | Additional content below the action. |
### Tokens used
`--iv_border` · `--iv_font-sans` · `--iv_font-ui` · `--iv_foreground` · `--iv_foreground-dim` · `--iv_leading-base` · `--iv_leading-tight` · `--iv_radius-sm` · `--iv_spacing-2xl` · `--iv_spacing-sm` · `--iv_spacing-xs` · `--iv_surface-elevated` · `--iv_text-lg` · `--iv_text-sm` · `--iv_weight-semibold`
See the [token reference](https://iv-ui.vercel.app/foundations/tokens.md) for values.
### CSS hooks
`.iv-empty-action` · `.iv-empty-description` · `.iv-empty-icon` · `.iv-empty-state` · `.iv-empty-title`
## Accessibility
- The title renders as an `h3`, so place the state inside a section with a higher-level heading.
- Use a real button or link in `action`; the empty state itself is not interactive.
- Keep the description text readable at small sizes; it uses the UI mono voice.
## Related
- [Alert](https://iv-ui.vercel.app/components/alert.md)
- [Skeleton](https://iv-ui.vercel.app/components/skeleton.md)
- [Card](https://iv-ui.vercel.app/components/card.md)
- [Progress](https://iv-ui.vercel.app/components/progress.md)
---
# LoadingSpinner
An indeterminate indicator for short waits.
## Import
```svelte
import { LoadingSpinner } from '@elluzion/iv-ui';
```
## Preview
Small, default, and large diameters.
```svelte
```
## Usage
- `size` is the diameter in pixels; `color` defaults to the accent token.
- It announces itself as a status; add text when the wait may be long.
- For determinate work, use `Progress` instead.
## Examples
### Color
Pass any CSS color; the default is the brass accent.
```svelte
```
### Inline
The spinner sits on the text baseline inside a status row.
```svelte
Syncing the edge configuration…
```
### Props
| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `size` | `number` | `24` | Diameter in pixels. |
| `color` | `string` | `'var(--iv_accent)'` | Stroke color; defaults to the current text color. |
### Tokens used
`--iv_spin-duration` · `--iv_spin-easing` · `--iv_spinner-border`
See the [token reference](https://iv-ui.vercel.app/foundations/tokens.md) for values.
### CSS hooks
`.iv-spinner`
## Accessibility
- The spinner uses `role="status"` with the label `Loading`.
- It is decorative only in the sense of size; screen readers announce the status.
- Rotation stops when `prefers-reduced-motion` is set.
## Related
- [Progress](https://iv-ui.vercel.app/components/progress.md)
- [Skeleton](https://iv-ui.vercel.app/components/skeleton.md)
- [Button](https://iv-ui.vercel.app/components/button.md)
- [EmptyState](https://iv-ui.vercel.app/components/empty-state.md)
---
# Progress
Shows how much of a task is complete.
## Import
```svelte
import { Progress } from '@elluzion/iv-ui';
```
## Preview
A bar bound to a value on a 0–100 scale.
```svelte
```
## Usage
- Set `max` when the scale is not 0–100; the percentage is derived.
- `indeterminate` hides the value and animates the track.
- `label` names the bar; `showValue` prints the percentage.
## Examples
### Labeled
`label` and `showValue` add a header above the track.
```svelte
(completed = Math.max(0, completed - 10))}>−10
(completed = Math.min(100, completed + 10))}>+10
```
### Indeterminate
Use when progress is unknown but the work is running.
```svelte
```
### Sizes
`sm` for dense rows and `md` for page-level progress.
```svelte
```
### Props
| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `value` | `number` | `0` | Current progress value. |
| `max` | `number` | `100` | Value that represents completion. |
| `indeterminate` | `boolean` | `false` | Renders an animated unknown-progress state. |
| `label` | `string` | `''` | Visible label and accessible name. |
| `showValue` | `boolean` | `false` | Shows the percentage at the end of the track. |
| `size` | `'sm' \| 'md'` | `'md'` | Track thickness. |
| `className` | `string` | `''` | Extra classes merged onto the root element. |
`class`, `id`, `style`, `aria-*`, and `data-*` are forwarded through rest props.
### Tokens used
`--iv_cursor` · `--iv_ease-in-out` · `--iv_font-mono` · `--iv_font-ui` · `--iv_foreground` · `--iv_foreground-dim` · `--iv_progress-h-md` · `--iv_progress-h-sm` · `--iv_radius-sm` · `--iv_spacing-sm` · `--iv_surface-elevated` · `--iv_text-label` · `--iv_text-sm` · `--iv_transition-base` · `--iv_weight-medium`
See the [token reference](https://iv-ui.vercel.app/foundations/tokens.md) for values.
### CSS hooks
`.iv-fill` · `.iv-fill-wrap` · `.iv-indeterminate` · `.iv-label` · `.iv-progress` · `.iv-progress-header` · `.iv-sm` · `.iv-track` · `.iv-value`
## Accessibility
| Keys | Action |
| --- | --- |
| `Escape` | Not applicable; the bar is read-only. |
- The bar uses `role="progressbar"` with `aria-valuemin`, `aria-valuemax`, and `aria-valuenow`.
- Indeterminate bars omit the value and use `aria-valuetext="Indeterminate"`.
- `label` becomes the accessible name through `aria-labelledby`.
## Related
- [LoadingSpinner](https://iv-ui.vercel.app/components/loading-spinner.md)
- [Skeleton](https://iv-ui.vercel.app/components/skeleton.md)
- [Slider](https://iv-ui.vercel.app/components/slider.md)
- [Alert](https://iv-ui.vercel.app/components/alert.md)
---
# Skeleton
A pulsing placeholder that holds the shape of loading content.
## Import
```svelte
import { Skeleton } from '@elluzion/iv-ui';
```
## Preview
Rectangle, text line, and circle placeholders.
```svelte
```
## Usage
- `shape` picks rect, line, or circle; `width` and `height` accept numbers or CSS lengths.
- Match the dimensions of the content that replaces it to avoid layout shift.
- Combine several skeletons to sketch a list or card while data loads.
## Examples
### Card placeholder
A composition that mirrors the final card layout.
```svelte
```
### Props
| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `shape` | `'rect' \| 'line' \| 'circle'` | `'rect'` | Visual shape of the placeholder. |
| `width` | `string \| number` | — | Width; numbers are treated as pixels. |
| `height` | `string \| number` | — | Height; numbers are treated as pixels. |
| `className` | `string` | `''` | Extra classes merged onto the root element. |
### Tokens used
`--iv_avatar-md` · `--iv_ease-in-out` · `--iv_radius-sm` · `--iv_surface-elevated`
See the [token reference](https://iv-ui.vercel.app/foundations/tokens.md) for values.
### CSS hooks
`.iv-circle` · `.iv-line` · `.iv-rect` · `.iv-skeleton`
## Accessibility
- Skeletons are hidden from assistive technology.
- The pulse stops when `prefers-reduced-motion` is set.
- Announce loading elsewhere, for example with `role="status"` or an `Alert`.
## Related
- [LoadingSpinner](https://iv-ui.vercel.app/components/loading-spinner.md)
- [Progress](https://iv-ui.vercel.app/components/progress.md)
- [Card](https://iv-ui.vercel.app/components/card.md)
- [EmptyState](https://iv-ui.vercel.app/components/empty-state.md)
---
# Avatar
A circular identity image with initials and an optional presence dot.
## Import
```svelte
import { Avatar } from '@elluzion/iv-ui';
```
## Preview
`xs`, `sm`, `md`, and `lg` steps.
```svelte
```
## Usage
- `fallback` initials show when `src` is missing or fails to load.
- Pass an empty `alt` for decorative avatars; otherwise `alt` names the person.
- `status` adds a presence dot: neutral, success, error, info, or accent.
## Examples
### Fallback
Initials are used when there is no image or the image fails.
```svelte
```
### Status
A presence dot in the corner, with every status treatment.
```svelte
```
### Props
| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `src` | `string` | `''` | Image source. Falls back to `fallback` initials when missing or broken. |
| `alt` | `string` | `''` | Accessible name for the image. Use an empty string for decorative avatars. |
| `size` | `AvatarSize` | `'md'` | Control size. |
| `fallback` | `string` | `''` | Initials shown when there is no image. |
| `status` | `AvatarStatus` | — | Presence dot treatment. |
| `className` | `string` | `''` | Extra classes merged onto the root element. |
`class`, `id`, `style`, `aria-*`, and `data-*` are forwarded through rest props.
### Snippets
| Snippet | Type | Description |
| --- | --- | --- |
| `children` | `Snippet` | Custom avatar content replacing the image. |
### Types
#### `AvatarSize`
Avatar diameter steps.
```ts
type AvatarSize = 'xs' | 'sm' | 'md' | 'lg';
```
#### `AvatarStatus`
Presence dot treatments.
```ts
type AvatarStatus = 'neutral' | 'success' | 'error' | 'info' | 'accent';
```
### Tokens used
`--iv_accent` · `--iv_avatar-lg` · `--iv_avatar-md` · `--iv_avatar-sm` · `--iv_avatar-xs` · `--iv_border` · `--iv_error` · `--iv_foreground-dim` · `--iv_info` · `--iv_leading-none` · `--iv_radius-pill` · `--iv_spacing-sm` · `--iv_success` · `--iv_surface` · `--iv_surface-elevated` · `--iv_text-base` · `--iv_text-body-sm` · `--iv_text-sm` · `--iv_text-xs` · `--iv_weight-medium`
See the [token reference](https://iv-ui.vercel.app/foundations/tokens.md) for values.
### CSS hooks
`.iv-accent` · `.iv-avatar` · `.iv-avatar-fallback` · `.iv-avatar-img` · `.iv-avatar-overlay` · `.iv-avatar-status` · `.iv-error` · `.iv-info` · `.iv-lg` · `.iv-neutral` · `.iv-sm` · `.iv-success` · `.iv-xs`
## Accessibility
- When the image is present, `alt` is its accessible name.
- The initials fallback gets `role="img"` and the same name when `alt` is set.
- An empty `alt` makes the avatar decorative; use it when the name is already next to the avatar.
## Related
- [Badge](https://iv-ui.vercel.app/components/badge.md)
- [Card](https://iv-ui.vercel.app/components/card.md)
- [Shortcut](https://iv-ui.vercel.app/components/shortcut.md)
- [EmptyState](https://iv-ui.vercel.app/components/empty-state.md)
---
# Badge
A compact label for status, counts, or categories.
## Import
```svelte
import { Badge } from '@elluzion/iv-ui';
```
## Preview
Neutral, success, error, accent, and info.
```svelte
neutral
success
error
accent
info
```
## Usage
- `variant` colors the label; `neutral` stays monochrome.
- `dismissible` adds a remove button wired to `ondismiss`.
- Badges are not buttons; use `Toggle` for pressable chips.
## Examples
### Sizes
`sm` and `md` label heights.
```svelte
stable
stable
beta
beta
```
### Dismissible
A trailing remove button calls `ondismiss`.
```svelte
{#each tags as tag (tag)}
remove(tag)}>{tag}
{/each}
{#if tags.length === 0}no tags {/if}
{#if tags.length < 3}
(tags = ['edge', 'cache', 'read-only'])}>
Restore
{/if}
```
### Props
| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `variant` | `'neutral' \| 'success' \| 'error' \| 'accent' \| 'info'` | `'neutral'` | Status color. `neutral` is the default. |
| `size` | `'sm' \| 'md'` | `'md'` | Badge size. |
| `dismissible` | `boolean` | `false` | Shows a remove button. |
| `className` | `string` | `''` | Extra classes merged onto the root element. |
### Events
| Event | Handler type | Description |
| --- | --- | --- |
| `dismiss` | `() => void` | Called when the remove button is pressed. |
The legacy `on:name` form is accepted for every event.
### Snippets
| Snippet | Type | Description |
| --- | --- | --- |
| `children` | `Snippet` | Badge text. |
### Tokens used
`--iv_accent` · `--iv_badge-h-md` · `--iv_badge-h-sm` · `--iv_badge-pad-x-md` · `--iv_badge-pad-x-sm` · `--iv_border` · `--iv_error` · `--iv_font-mono` · `--iv_foreground` · `--iv_foreground-dim` · `--iv_info` · `--iv_outline-offset` · `--iv_outline-width` · `--iv_radius-sm` · `--iv_spacing-sm` · `--iv_spacing-xs` · `--iv_success` · `--iv_surface-elevated` · `--iv_surface-overlay` · `--iv_text-chips` · `--iv_text-xs` · `--iv_weight-semibold`
See the [token reference](https://iv-ui.vercel.app/foundations/tokens.md) for values.
### CSS hooks
`.iv-accent` · `.iv-badge` · `.iv-badge-content` · `.iv-badge-dismiss` · `.iv-dismissible` · `.iv-error` · `.iv-info` · `.iv-sm` · `.iv-success`
## Accessibility
- Color is not the only signal; the text carries the meaning.
- The dismiss control is a button with an accessible name.
- Keep labels short; the badge truncates instead of wrapping.
## Related
- [Avatar](https://iv-ui.vercel.app/components/avatar.md)
- [Alert](https://iv-ui.vercel.app/components/alert.md)
- [Shortcut](https://iv-ui.vercel.app/components/shortcut.md)
- [Card](https://iv-ui.vercel.app/components/card.md)
---
# Shortcut
Renders a keyboard combination as key caps.
## Import
```svelte
import { Shortcut } from '@elluzion/iv-ui';
```
## Preview
One key cap.
```svelte
Press to close the palette.
```
## Usage
- `keys` accepts a single key or an ordered array.
- `label` supplies the accessible name for the combination.
- Use inside menus, command palettes, and help panels.
## Examples
### Combinations
Modifier keys in order, with the accessible name spelled out.
```svelte
Command palette
Search files
Toggle sidebar
```
### Sizes
`sm` inside menus, `md` for help panels.
```svelte
```
### Props
| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `keys` **required** | `string \| string[]` | — | Key or keys to display, in order. |
| `label` | `string` | `''` | Accessible name for the combination. |
| `size` | `'sm' \| 'md'` | `'sm'` | Key cap size. |
| `className` | `string` | `''` | Extra classes merged onto the root element. |
### Tokens used
`--iv_border` · `--iv_font-mono` · `--iv_foreground-dim` · `--iv_leading-none` · `--iv_radius-sm` · `--iv_surface-elevated` · `--iv_text-sm` · `--iv_text-xs`
See the [token reference](https://iv-ui.vercel.app/foundations/tokens.md) for values.
### CSS hooks
`.iv-key` · `.iv-md` · `.iv-root`
## Accessibility
- The component renders `` elements, which assistive technology recognizes.
- Pass `label` when the visual key names are symbols rather than words.
- Keys are rendered in order; keep the platform convention, such as Control before K.
## Related
- [Menu](https://iv-ui.vercel.app/components/menu.md)
- [Tooltip](https://iv-ui.vercel.app/components/tooltip.md)
- [Badge](https://iv-ui.vercel.app/components/badge.md)
- [Button](https://iv-ui.vercel.app/components/button.md)
---
# Installation
Configure GitHub Packages, install the package, and import the theme once.
## Registry
iv-ui is published to GitHub Packages. Add the scoped registry to `.npmrc` and authenticate with a token that has `read:packages`.
**.npmrc**
```ini
@elluzion:registry=https://npm.pkg.github.com
//npm.pkg.github.com/:_authToken=${GITHUB_TOKEN}
```
> **CI** — Export `GITHUB_TOKEN` in CI. Locally, `gh auth token` works if the GitHub CLI is signed in.
## Install
```sh
bun add @elluzion/iv-ui @tabler/icons-svelte
```
`@tabler/icons-svelte` is a peer dependency and must be installed alongside the library.
## Theme
Import the full theme once, in the root layout. It bundles tokens, base styles, and the prose typeset.
**src/routes/+layout.svelte**
```svelte
{@render children()}
```
CSS can also be imported piecemeal: `tokens.css` (variables only), `base.css` (reset and base elements), `typeset.css` (prose styles).
## Mount the globals
`Toast` and `AlertDialog` listen to their stores, so each app mounts them once. Everything else is rendered where you use it.
**src/routes/+layout.svelte**
```svelte
{@render children()}
```
## Requirements
- **Svelte 5.20 or newer** — Components are authored with runes.
- **Node 18 or newer** — For the package build and SSR.
- **@tabler/icons-svelte** — Peer dependency used by menus, selects, and overlays.
## Related
- [Quickstart](https://iv-ui.vercel.app/docs/quickstart.md)
- [Theming](https://iv-ui.vercel.app/docs/theming.md)
- [For agents](https://iv-ui.vercel.app/docs/for-agents.md)
---
# Quickstart
From an empty SvelteKit route to a working form with feedback in five minutes.
## 1. Install
```sh
bun add @elluzion/iv-ui @tabler/icons-svelte
```
## 2. Root layout
Import the theme and mount the two store-driven globals.
**src/routes/+layout.svelte**
```svelte
{@render children()}
```
## 3. A form
Components are controlled with `bind:` or with explicit event handlers. Labels, helper text, and errors are part of the field components.
**src/routes/+page.svelte**
```svelte
```
> **Forms** — Field wraps any control and connects its label, helper text, and error to the control through `aria-describedby`.
## 4. An overlay
```svelte
(open = true)}>Delete project
This removes the project and every deployment. It cannot be undone.
{#snippet footer()}
Cancel
Delete
{/snippet}
```
> **Destructive actions** — For confirmation flows that must block the page, use `showAlertDialog` instead of a plain dialog. It mounts once at the root and handles focus and escape.
## Next
- Browse all [components](https://iv-ui.vercel.app/components) — every page lists props, events, and copyable examples.
- Read [theming](https://iv-ui.vercel.app/docs/theming) before overriding colors or spacing.
- Point an agent at [llms.txt](https://iv-ui.vercel.app/llms.txt) or the API corpus at [llms-api.txt](https://iv-ui.vercel.app/llms-api.txt).
## Related
- [Installation](https://iv-ui.vercel.app/docs/installation.md)
- [Theming](https://iv-ui.vercel.app/docs/theming.md)
- [Accessibility](https://iv-ui.vercel.app/docs/accessibility.md)
---
# Theming
Override semantic tokens once and every component follows — light, dark, and custom.
## Semantic tokens
Components never reference raw colors. They read `--iv_*` tokens, grouped as surface/foreground pairs. Overriding a token restyles every component that uses it.
Try it: the controls below write to `:root` immediately. Nothing is persisted.
## Override
**src/app.css**
```css
:root {
--iv_accent: #c7a24a;
--iv_accent-dim: #8a6f2f;
--iv_surface: #000000;
--iv_radius: 2px;
}
```
> **Specificity** — Import your overrides after `theme.css`, or scope them under `:root` — the theme uses `:root` and `[data-theme]`, so later declarations win.
## Dark and light
Dark is the default. Light is applied by the OS preference, or forced with `data-theme="light"` on ``. Set it before first paint to avoid a flash.
**src/app.html — before %sveltekit.head%**
```html
```
## Radius and density
`--iv_radius` derives the whole radius scale, so override `--iv_radius-lg` to change containers without touching the square controls. Spacing is a fixed 2–24px scale; `--iv_spacing-lg` sets the gap inside panels and forms.
```css
:root {
--iv_radius-lg: 4px;
--iv_spacing-lg: 20px;
}
```
## Typography
The UI voice is IBM Plex Mono; Sora is reserved for headings and prose. Point the font tokens at self-hosted faces to drop the Google Fonts request.
```css
@font-face {
font-family: 'Plex Mono Local';
src: url('/fonts/plex-mono.woff2') format('woff2');
font-display: swap;
}
:root {
--iv_font-mono: 'Plex Mono Local', monospace;
}
```
## Component scope
Tokens cascade. Set them on any container to theme a subtree, for example a dense panel.
```svelte
Save
```
## Related
- [Installation](https://iv-ui.vercel.app/docs/installation.md)
- [Tokens](https://iv-ui.vercel.app/foundations/tokens.md)
---
# Accessibility
What every component guarantees, and what your app still has to provide.
Every component ships with the same contract: accessible names, keyboard operation, visible focus, and reduced-motion handling. The library covers the mechanics; you provide the meaning.
## Contract
- **Keyboard complete** — Every control is reachable with Tab and operable with Enter, Space, or arrow keys.
- **Focus is visible** — Focus rings use `--iv_ring` and are never removed. Overlays trap focus and restore it on close.
- **Names come from content** — Labels, `aria-label`, and `aria-labelledby` are wired internally where the component renders text.
- **Reduced motion is respected** — Transitions collapse to 0.01ms when `prefers-reduced-motion: reduce` is set.
- **State is announced** — `aria-expanded`, `aria-selected`, `aria-busy`, `aria-invalid`, and live regions are set by the components.
## Your responsibilities
- Icon-only buttons need an `aria-label` — there is no text to derive a name from.
- Images and avatars need `alt`; decorative icons should be `aria-hidden="true"`.
- Color is never the only signal: badges and alerts also carry text.
- One `h1` per page, and headings in order. Component titles are `h2` in docs, but your app controls its own outline.
## Testing
The standalone Vitest browser suite renders components in Chromium, checks them with axe, and exercises their primary interactions with Testing Library. Violations fail the run; Storybook is only for browsing stories.
```sh
bun run test # axe + interaction tests
bun run storybook # inspect manually at :6006
```
## Reduced motion
Component transitions read the `reducedMotion` store. When you build custom motion, do the same with the CSS media query or the store.
```css
@media (prefers-reduced-motion: reduce) {
.animated {
transition: none;
}
}
```
## Related
- [Installation](https://iv-ui.vercel.app/docs/installation.md)
- [For agents](https://iv-ui.vercel.app/docs/for-agents.md)
---
# For agents
Machine-readable entry points: llms.txt, full corpus, API-only corpus, and JSON.
Every page has a Markdown twin and every component has a JSON API document. Both are generated from the same registry as this page, so they cannot drift.
## Entry points
| URL | Contents |
| --- | --- |
| `/llms.txt` | Index, install rules, and links to every page as Markdown. |
| `/llms-full.txt` | The complete documentation in one file. |
| `/llms-api.txt` | Imports and API tables only — no examples. |
| `/api/index.json` | Every component with slug, category, summary, and URL. |
| `/api/.json` | Structured props, events, snippets, types, tokens, and examples. |
| `/.md` | The Markdown twin of any page. |
| `/search.json` | The client search index, plain JSON. |
## Ground rules
- Svelte 5 runes only: `$props()`, `$state()`, `$derived()`, `$effect()`.
- Import from `@elluzion/iv-ui`; import `@elluzion/iv-ui/theme.css` once at the root.
- Never hardcode hex colors in app code — override `--iv_*` tokens.
- Mount ` ` and ` ` once; use `showToast()` and `showAlertDialog()`.
- Prefer the library component over a hand-built control.
- Pass `aria-label` for icon-only buttons and `alt` for avatars.
- All components forward `class`, `id`, `style`, `aria-*`, and `data-*` through rest props.
## Fetch
```sh
curl https://iv-ui.vercel.app/llms-api.txt
curl https://iv-ui.vercel.app/api/button.json
curl https://iv-ui.vercel.app/components/button.md
```
## What the API JSON contains
```json
{
"slug": "button",
"name": "Button",
"category": "Form & Input",
"summary": "Triggers an action or submits a form.",
"status": "stable",
"since": "0.1.0",
"import": "import { Button } from '@elluzion/iv-ui';",
"usage": ["…"],
"props": [{ "name": "variant", "type": "…", "default": "…", "description": "…", "required": false, "bindable": false }],
"events": [{ "name": "click", "type": "(e: MouseEvent) => void", "default": null, "description": "…", "required": false, "bindable": false }],
"snippets": [{ "name": "children", "type": "Snippet", "default": null, "description": "…", "required": true, "bindable": false }],
"types": [],
"manual": [],
"tokens": ["--iv_radius-sm"],
"cssHooks": [".iv-btn"],
"accessibility": { "keyboard": [["Tab", "…"]], "notes": ["…"] },
"related": [{ "title": "…", "summary": "…", "url": "/components/…", "kind": "Component" }],
"examples": [{ "id": "variants", "title": "Variants", "description": "…", "code": "…" }],
"markdown": "/components/button.md",
"page": "/components/button"
}
```
> **Canonical URLs** — Links inside `llms.txt` are absolute. Set `PUBLIC_SITE_URL` at build time when the docs move to a custom domain.
## Related
- [Installation](https://iv-ui.vercel.app/docs/installation.md)
- [Quickstart](https://iv-ui.vercel.app/docs/quickstart.md)
- [Accessibility](https://iv-ui.vercel.app/docs/accessibility.md)
---
# Tokens
Every design decision is a CSS custom property. This is the full generated list.
Tokens are the only source of color, type, space, and motion. Components reference them; apps override them. Values below are read from `tokens.css` at build time.
## Color
| Token | Dark | Light |
| --- | --- | --- |
| `--iv_accent` | `#c7a24a` | `#8a6f2f` |
| `--iv_accent-dim` | `#8a6f2f` | `#6b5523` |
| `--iv_accent-foreground` | `var(--iv_surface)` | `var(--iv_surface)` |
| `--iv_accent-surface` | `rgba(199, 162, 74, 0.12)` | `rgba(138, 111, 47, 0.1)` |
| `--iv_background` | `var(--iv_surface)` | `var(--iv_surface)` |
| `--iv_background-foreground` | `var(--iv_foreground)` | `var(--iv_foreground)` |
| `--iv_border` | `#26262a` | `#d4d3cf` |
| `--iv_border-error` | `#e0503a` | `#b33a22` |
| `--iv_border-focus` | `#4a4a50` | `#82817c` |
| `--iv_border-hover` | `#3a3a3f` | `#b3b2ad` |
| `--iv_bracket` | `var(--iv_accent-dim)` | `var(--iv_accent-dim)` |
| `--iv_card` | `var(--iv_surface-raised)` | `var(--iv_surface-raised)` |
| `--iv_card-foreground` | `var(--iv_foreground)` | `var(--iv_foreground)` |
| `--iv_card-pad-x` | `1rem` | `1rem` |
| `--iv_card-pad-x-lg` | `1.25rem` | `1.25rem` |
| `--iv_card-pad-x-sm` | `0.75rem` | `0.75rem` |
| `--iv_card-pad-y` | `0.875rem` | `0.875rem` |
| `--iv_card-pad-y-lg` | `1.25rem` | `1.25rem` |
| `--iv_card-pad-y-sm` | `0.625rem` | `0.625rem` |
| `--iv_caret` | `var(--iv_accent)` | `var(--iv_accent)` |
| `--iv_cursor` | `var(--iv_accent)` | `var(--iv_accent)` |
| `--iv_destructive` | `var(--iv_error)` | `var(--iv_error)` |
| `--iv_destructive-foreground` | `var(--iv_surface)` | `var(--iv_surface)` |
| `--iv_destructive-surface` | `var(--iv_error-surface)` | `var(--iv_error-surface)` |
| `--iv_error` | `#e0503a` | `#b33a22` |
| `--iv_error-dim` | `#b23c2a` | `#8c2c1a` |
| `--iv_error-surface` | `rgba(224, 80, 58, 0.12)` | `rgba(179, 58, 34, 0.1)` |
| `--iv_foreground` | `#f2f2f2` | `#141414` |
| `--iv_foreground-dim` | `#8a8a90` | `#6e6d68` |
| `--iv_foreground-hover` | `#dcdcdc` | `#232322` |
| `--iv_foreground-inverse` | `#000000` | `#ffffff` |
| `--iv_info` | `#5d8ee8` | `#2f5fc4` |
| `--iv_info-dim` | `#3a6fcc` | `#244a99` |
| `--iv_info-surface` | `rgba(93, 142, 232, 0.12)` | `rgba(47, 95, 196, 0.1)` |
| `--iv_input` | `var(--iv_surface-raised)` | `var(--iv_surface-raised)` |
| `--iv_muted` | `var(--iv_surface-elevated)` | `var(--iv_surface-elevated)` |
| `--iv_muted-foreground` | `var(--iv_foreground-dim)` | `var(--iv_foreground-dim)` |
| `--iv_overlay` | `rgba(0, 0, 0, 0.5)` | `rgba(0, 0, 0, 0.25)` |
| `--iv_popover` | `var(--iv_surface-elevated)` | `var(--iv_surface-elevated)` |
| `--iv_popover-foreground` | `var(--iv_foreground)` | `var(--iv_foreground)` |
| `--iv_popover-margin` | `4px` | `4px` |
| `--iv_popover-max-w` | `20rem` | `20rem` |
| `--iv_popover-min-w` | `10rem` | `10rem` |
| `--iv_primary` | `var(--iv_foreground)` | `var(--iv_foreground)` |
| `--iv_primary-foreground` | `var(--iv_surface)` | `var(--iv_surface)` |
| `--iv_primary-hover` | `var(--iv_foreground-hover)` | `var(--iv_foreground-hover)` |
| `--iv_reverse-bg` | `var(--iv_foreground)` | `var(--iv_foreground)` |
| `--iv_reverse-fg` | `var(--iv_surface)` | `var(--iv_surface)` |
| `--iv_reverse-hover` | `var(--iv_foreground-hover)` | `var(--iv_foreground-hover)` |
| `--iv_ring` | `rgba(255, 255, 255, 0.12)` | `rgba(0, 0, 0, 0.08)` |
| `--iv_ring-width` | `1px` | `1px` |
| `--iv_secondary` | `var(--iv_surface-elevated)` | `var(--iv_surface-elevated)` |
| `--iv_secondary-foreground` | `var(--iv_foreground)` | `var(--iv_foreground)` |
| `--iv_success` | `#7c9b7c` | `#3b6e3b` |
| `--iv_success-dim` | `#557255` | `#2c552c` |
| `--iv_success-surface` | `rgba(124, 155, 124, 0.12)` | `rgba(59, 110, 59, 0.1)` |
| `--iv_surface` | `#000000` | `#fcfcfc` |
| `--iv_surface-elevated` | `#18181a` | `#e8e8e8` |
| `--iv_surface-hover` | `#1f1f22` | `#dddcdb` |
| `--iv_surface-overlay` | `rgba(255, 255, 255, 0.08)` | `rgba(0, 0, 0, 0.04)` |
| `--iv_surface-raised` | `#101011` | `#f2f2f2` |
## Component
| Token | Dark | Light |
| --- | --- | --- |
| `--iv_article-width` | `880px` | `880px` |
| `--iv_avatar-lg` | `48px` | `48px` |
| `--iv_avatar-md` | `36px` | `36px` |
| `--iv_avatar-sm` | `28px` | `28px` |
| `--iv_avatar-xs` | `20px` | `20px` |
| `--iv_badge-h-md` | `26px` | `26px` |
| `--iv_badge-h-sm` | `20px` | `20px` |
| `--iv_badge-pad-x-md` | `12px` | `12px` |
| `--iv_badge-pad-x-sm` | `8px` | `8px` |
| `--iv_btn-pad-x` | `20px` | `20px` |
| `--iv_btn-pad-x-lg` | `26px` | `26px` |
| `--iv_btn-pad-x-sm` | `14px` | `14px` |
| `--iv_control-md` | `20px` | `20px` |
| `--iv_control-pad-x` | `15px` | `15px` |
| `--iv_control-pad-x-lg` | `18px` | `18px` |
| `--iv_control-pad-x-sm` | `12px` | `12px` |
| `--iv_control-pad-y` | `10px` | `10px` |
| `--iv_control-pad-y-lg` | `14px` | `14px` |
| `--iv_control-pad-y-sm` | `6px` | `6px` |
| `--iv_control-sm` | `16px` | `16px` |
| `--iv_dialog-lg` | `640px` | `640px` |
| `--iv_dialog-md` | `520px` | `520px` |
| `--iv_dialog-sm` | `400px` | `400px` |
| `--iv_disabled-opacity` | `0.5` | `0.5` |
| `--iv_hazard-angle` | `45deg` | `45deg` |
| `--iv_hazard-stripe` | `repeating-linear-gradient( var(--iv_hazard-angle), transparent 0 4px, var(--iv_surface-overlay) 4px 8px )` | `repeating-linear-gradient( var(--iv_hazard-angle), transparent 0 4px, var(--iv_surface-overlay) 4px 8px )` |
| `--iv_menu-lead-size` | `18px` | `18px` |
| `--iv_progress-h-md` | `6px` | `6px` |
| `--iv_progress-h-sm` | `4px` | `4px` |
| `--iv_radio-border` | `1.5px` | `1.5px` |
| `--iv_radio-dot` | `8px` | `8px` |
| `--iv_radio-dot-sm` | `5px` | `5px` |
| `--iv_select-dropdown-max-h` | `240px` | `240px` |
| `--iv_separator-size` | `1px` | `1px` |
| `--iv_sheet-lg` | `560px` | `560px` |
| `--iv_sheet-md` | `440px` | `440px` |
| `--iv_sheet-sm` | `320px` | `320px` |
| `--iv_skeleton-radius` | `var(--iv_radius)` | `var(--iv_radius)` |
| `--iv_slider-track` | `6px` | `6px` |
| `--iv_slider-track-sm` | `4px` | `4px` |
| `--iv_submenu-min-w` | `12rem` | `12rem` |
| `--iv_switch-h` | `22px` | `22px` |
| `--iv_switch-h-sm` | `18px` | `18px` |
| `--iv_switch-w` | `40px` | `40px` |
| `--iv_switch-w-sm` | `32px` | `32px` |
| `--iv_table-cell-pad-x` | `1rem` | `1rem` |
| `--iv_table-cell-pad-y` | `0.625rem` | `0.625rem` |
| `--iv_thumb-md` | `18px` | `18px` |
| `--iv_thumb-sm` | `14px` | `14px` |
| `--iv_toast-close-size` | `32px` | `32px` |
| `--iv_toast-min-w` | `260px` | `260px` |
| `--iv_tooltip-margin` | `4px` | `4px` |
## Layers
| Token | Dark | Light |
| --- | --- | --- |
| `--iv_blur` | `12px` | `12px` |
| `--iv_dialog-gap` | `4rem` | `4rem` |
| `--iv_scrollbar-size` | `8px` | `8px` |
| `--iv_tooltip-gap` | `4px` | `4px` |
| `--iv_z-dropdown` | `50` | `50` |
| `--iv_z-overlay` | `100` | `100` |
| `--iv_z-toast` | `110` | `110` |
## Motion
| Token | Dark | Light |
| --- | --- | --- |
| `--iv_ease-emphasized` | `cubic-bezier(0.2, 0, 0, 1)` | `cubic-bezier(0.2, 0, 0, 1)` |
| `--iv_ease-in` | `cubic-bezier(0.32, 0, 0.67, 0)` | `cubic-bezier(0.32, 0, 0.67, 0)` |
| `--iv_ease-in-out` | `cubic-bezier(0.65, 0, 0.35, 1)` | `cubic-bezier(0.65, 0, 0.35, 1)` |
| `--iv_ease-out` | `cubic-bezier(0.16, 1, 0.3, 1)` | `cubic-bezier(0.16, 1, 0.3, 1)` |
| `--iv_ease-snappy` | `cubic-bezier(0.3, 0.7, 0.7, 0.3)` | `cubic-bezier(0.3, 0.7, 0.7, 0.3)` |
| `--iv_ease-spring` | `cubic-bezier(0.34, 1.56, 0.64, 1)` | `cubic-bezier(0.34, 1.56, 0.64, 1)` |
| `--iv_motion-fade` | `0.28s` | `0.28s` |
| `--iv_motion-fly` | `0.34s` | `0.34s` |
| `--iv_motion-scale` | `0.36s` | `0.36s` |
| `--iv_motion-slide` | `0.38s` | `0.38s` |
| `--iv_motion-subtle` | `0.22s` | `0.22s` |
| `--iv_spin-duration` | `0.75s` | `0.75s` |
| `--iv_spin-easing` | `cubic-bezier(0.3, 0.7, 0.7, 0.3)` | `cubic-bezier(0.3, 0.7, 0.7, 0.3)` |
| `--iv_spinner-border` | `2px` | `2px` |
| `--iv_transition-base` | `0.32s` | `0.32s` |
| `--iv_transition-fast` | `0.2s` | `0.2s` |
| `--iv_transition-slow` | `0.48s` | `0.48s` |
## Shape
| Token | Dark | Light |
| --- | --- | --- |
| `--iv_outline-offset` | `3px` | `3px` |
| `--iv_outline-width` | `1px` | `1px` |
| `--iv_radius` | `4px` | `4px` |
| `--iv_radius-lg` | `calc(var(--iv_radius) + 4px)` | `calc(var(--iv_radius) + 4px)` |
| `--iv_radius-pill` | `999px` | `999px` |
| `--iv_radius-sm` | `calc(var(--iv_radius) - 4px)` | `calc(var(--iv_radius) - 4px)` |
| `--iv_shadow-lg` | `0 24px 60px rgba(0, 0, 0, 0.65), 0 2px 6px rgba(0, 0, 0, 0.45)` | `0 24px 60px rgba(0, 0, 0, 0.65), 0 2px 6px rgba(0, 0, 0, 0.45)` |
| `--iv_shadow-md` | `0 4px 20px rgba(0, 0, 0, 0.5), 0 1px 3px rgba(0, 0, 0, 0.45)` | `0 4px 20px rgba(0, 0, 0, 0.5), 0 1px 3px rgba(0, 0, 0, 0.45)` |
| `--iv_shadow-sm` | `0 1px 2px rgba(0, 0, 0, 0.55)` | `0 1px 2px rgba(0, 0, 0, 0.55)` |
## Space
| Token | Dark | Light |
| --- | --- | --- |
| `--iv_spacing-2xl` | `24px` | `24px` |
| `--iv_spacing-2xs` | `2px` | `2px` |
| `--iv_spacing-lg` | `16px` | `16px` |
| `--iv_spacing-md` | `12px` | `12px` |
| `--iv_spacing-sm` | `8px` | `8px` |
| `--iv_spacing-xl` | `20px` | `20px` |
| `--iv_spacing-xs` | `4px` | `4px` |
## Typography
| Token | Dark | Light |
| --- | --- | --- |
| `--iv_font-mono` | `'IBM Plex Mono', monospace` | `'IBM Plex Mono', monospace` |
| `--iv_font-sans` | `'Sora', system-ui, sans-serif` | `'Sora', system-ui, sans-serif` |
| `--iv_font-ui` | `var(--iv_font-mono)` | `var(--iv_font-mono)` |
| `--iv_leading-base` | `1.5` | `1.5` |
| `--iv_leading-heading` | `1.3` | `1.3` |
| `--iv_leading-loose` | `1.75` | `1.75` |
| `--iv_leading-none` | `1` | `1` |
| `--iv_leading-prose` | `1.6` | `1.6` |
| `--iv_leading-tight` | `1.25` | `1.25` |
| `--iv_text-base` | `1rem` | `1rem` |
| `--iv_text-body` | `0.9rem` | `0.9rem` |
| `--iv_text-body-sm` | `0.875rem` | `0.875rem` |
| `--iv_text-btn` | `0.95rem` | `0.95rem` |
| `--iv_text-btn-sm` | `0.825rem` | `0.825rem` |
| `--iv_text-caption` | `0.75rem` | `0.75rem` |
| `--iv_text-chips` | `10.5px` | `10.5px` |
| `--iv_text-chips-sm` | `13px` | `13px` |
| `--iv_text-display` | `2rem` | `2rem` |
| `--iv_text-h1` | `1.5rem` | `1.5rem` |
| `--iv_text-h2` | `1.25rem` | `1.25rem` |
| `--iv_text-h3` | `1.1rem` | `1.1rem` |
| `--iv_text-label` | `0.85rem` | `0.85rem` |
| `--iv_text-lg` | `1.05rem` | `1.05rem` |
| `--iv_text-sm` | `0.8rem` | `0.8rem` |
| `--iv_text-title` | `1rem` | `1rem` |
| `--iv_text-xl` | `1.1rem` | `1.1rem` |
| `--iv_text-xs` | `0.75rem` | `0.75rem` |
| `--iv_tracking-base` | `0` | `0` |
| `--iv_tracking-tight` | `-0.01em` | `-0.01em` |
| `--iv_tracking-wide` | `0.02em` | `0.02em` |
| `--iv_tracking-wider` | `0.05em` | `0.05em` |
| `--iv_typeset-flow` | `1.25em` | `1.25em` |
| `--iv_typeset-leading` | `1.6` | `1.6` |
| `--iv_typeset-measure` | `68ch` | `68ch` |
| `--iv_typeset-size` | `0.9rem` | `0.9rem` |
| `--iv_weight-bold` | `700` | `700` |
| `--iv_weight-medium` | `500` | `500` |
| `--iv_weight-normal` | `400` | `400` |
| `--iv_weight-semibold` | `600` | `600` |
> **Naming** — All tokens use the `--iv_` prefix. Color tokens come in pairs: a surface (`--iv_surface`, `--iv_accent-surface`) and a foreground (`--iv_foreground`, `--iv_accent`).
## Related
- [Color](https://iv-ui.vercel.app/foundations/colors.md)
- [Typography](https://iv-ui.vercel.app/foundations/typography.md)
- [Motion](https://iv-ui.vercel.app/foundations/motion.md)
---
# Color
A monochrome canvas with one brass accent and three status families.
The canvas is pure black in dark mode and near-white in light. Brass marks the cursor, selection, and the single most important action. Status colors are muted — never neon.
| Token | Dark | Light |
| --- | --- | --- |
| `--iv_accent` | `#c7a24a` | `#8a6f2f` |
| `--iv_accent-dim` | `#8a6f2f` | `#6b5523` |
| `--iv_accent-surface` | `rgba(199, 162, 74, 0.12)` | `rgba(138, 111, 47, 0.1)` |
| `--iv_border` | `#26262a` | `#d4d3cf` |
| `--iv_border-error` | `#e0503a` | `#b33a22` |
| `--iv_border-focus` | `#4a4a50` | `#82817c` |
| `--iv_border-hover` | `#3a3a3f` | `#b3b2ad` |
| `--iv_error` | `#e0503a` | `#b33a22` |
| `--iv_error-dim` | `#b23c2a` | `#8c2c1a` |
| `--iv_error-surface` | `rgba(224, 80, 58, 0.12)` | `rgba(179, 58, 34, 0.1)` |
| `--iv_foreground` | `#f2f2f2` | `#141414` |
| `--iv_foreground-dim` | `#8a8a90` | `#6e6d68` |
| `--iv_foreground-hover` | `#dcdcdc` | `#232322` |
| `--iv_foreground-inverse` | `#000000` | `#ffffff` |
| `--iv_info` | `#5d8ee8` | `#2f5fc4` |
| `--iv_info-dim` | `#3a6fcc` | `#244a99` |
| `--iv_info-surface` | `rgba(93, 142, 232, 0.12)` | `rgba(47, 95, 196, 0.1)` |
| `--iv_overlay` | `rgba(0, 0, 0, 0.5)` | `rgba(0, 0, 0, 0.25)` |
| `--iv_ring` | `rgba(255, 255, 255, 0.12)` | `rgba(0, 0, 0, 0.08)` |
| `--iv_success` | `#7c9b7c` | `#3b6e3b` |
| `--iv_success-dim` | `#557255` | `#2c552c` |
| `--iv_success-surface` | `rgba(124, 155, 124, 0.12)` | `rgba(59, 110, 59, 0.1)` |
| `--iv_surface` | `#000000` | `#fcfcfc` |
| `--iv_surface-elevated` | `#18181a` | `#e8e8e8` |
| `--iv_surface-hover` | `#1f1f22` | `#dddcdb` |
| `--iv_surface-overlay` | `rgba(255, 255, 255, 0.08)` | `rgba(0, 0, 0, 0.04)` |
| `--iv_surface-raised` | `#101011` | `#f2f2f2` |
## Pairs
Each surface has a matching foreground. Use the pair; do not mix a light surface with a dark-mode foreground.
| Surface | Foreground | Use |
| --- | --- | --- |
| `--iv_surface` | `--iv_foreground` | Page canvas and primary text. |
| `--iv_surface-raised` | `--iv_foreground` | Cards, panels, code blocks. |
| `--iv_surface-elevated` | `--iv_foreground` | Controls, menus, popovers. |
| `--iv_accent` | `--iv_foreground-inverse` | Brass cursor blocks and selection marks. |
| `--iv_error` | `--iv_surface` | Destructive actions and error text on raised surfaces. |
| `--iv_reverse-bg` | `--iv_reverse-fg` | Reverse-video selection and active rows. |
## Rules
- Brass is an accent, not a fill. One brass mark per view is usually enough.
- Never use color alone to signal state — pair it with text or an icon.
- Hardcoded hex values in app code break light mode. Override tokens instead.
- Status colors are tuned for 4.5:1 on their intended surface.
## Related
- [Tokens](https://iv-ui.vercel.app/foundations/tokens.md)
- [Theming](https://iv-ui.vercel.app/docs/theming.md)
- [Accessibility](https://iv-ui.vercel.app/docs/accessibility.md)
---
# Typography
IBM Plex Mono is the interface voice; Sora is reserved for headings and prose.
The UI is mono-forward: labels, buttons, tables, and metadata are all Plex Mono. Sora appears only where a document needs a headline or a paragraph.
| Token | Value |
| --- | --- |
| `--iv_font-mono` | `'IBM Plex Mono', monospace` |
| `--iv_font-sans` | `'Sora', system-ui, sans-serif` |
| `--iv_font-ui` | `var(--iv_font-mono)` |
| `--iv_leading-base` | `1.5` |
| `--iv_leading-heading` | `1.3` |
| `--iv_leading-loose` | `1.75` |
| `--iv_leading-none` | `1` |
| `--iv_leading-prose` | `1.6` |
| `--iv_leading-tight` | `1.25` |
| `--iv_text-base` | `1rem` |
| `--iv_text-body` | `0.9rem` |
| `--iv_text-body-sm` | `0.875rem` |
| `--iv_text-btn` | `0.95rem` |
| `--iv_text-btn-sm` | `0.825rem` |
| `--iv_text-caption` | `0.75rem` |
| `--iv_text-chips` | `10.5px` |
| `--iv_text-chips-sm` | `13px` |
| `--iv_text-display` | `2rem` |
| `--iv_text-h1` | `1.5rem` |
| `--iv_text-h2` | `1.25rem` |
| `--iv_text-h3` | `1.1rem` |
| `--iv_text-label` | `0.85rem` |
| `--iv_text-lg` | `1.05rem` |
| `--iv_text-sm` | `0.8rem` |
| `--iv_text-title` | `1rem` |
| `--iv_text-xl` | `1.1rem` |
| `--iv_text-xs` | `0.75rem` |
| `--iv_tracking-base` | `0` |
| `--iv_tracking-tight` | `-0.01em` |
| `--iv_tracking-wide` | `0.02em` |
| `--iv_tracking-wider` | `0.05em` |
| `--iv_weight-bold` | `700` |
| `--iv_weight-medium` | `500` |
| `--iv_weight-normal` | `400` |
| `--iv_weight-semibold` | `600` |
## Roles
| Token | Size | Role |
| --- | --- | --- |
| `--iv_text-xs` | 0.75rem | Metadata, badges, timestamps. |
| `--iv_text-sm` | 0.8rem | Helper text and dense labels. |
| `--iv_text-body` | 0.9rem | Default interface text. |
| `--iv_text-lg` | 1.05rem | Section titles. |
| `--iv_text-xl` | 1.1rem | Dialog titles. |
| `--iv_text-h1` | 1.5rem | Page titles. |
| `--iv_text-display` | 2rem | Reserved for large numerals. |
## Weights and tracking
- Three weights: 400 body, 500 medium labels, 600 headings. 700 is reserved for numerals.
- Tracking is tight (`-0.01em`) for headings, neutral for body, wide (`0.05em`) for uppercase micro-labels.
- Uppercase labels never exceed 0.75rem and always add tracking.
## Prose
Wrap rendered Markdown in `.iv-prose` (from `typeset.css`) to get container-aware type. Its three controls are `--iv_typeset-size`, `--iv_typeset-leading`, and `--iv_typeset-flow`.
```html
```
## Related
- [Tokens](https://iv-ui.vercel.app/foundations/tokens.md)
- [Color](https://iv-ui.vercel.app/foundations/colors.md)
---
# Motion
Short, decisive transitions — and an immediate stop when the user asks for less.
Motion explains where a layer came from. It never decorates, never bounces, and never delays an action. Durations are 200–480ms with a quint or cubic ease-out. Hover a row below to compare the durations, each easing curve, and the spinner.
| Token | Value |
| --- | --- |
| `--iv_ease-emphasized` | `cubic-bezier(0.2, 0, 0, 1)` |
| `--iv_ease-in` | `cubic-bezier(0.32, 0, 0.67, 0)` |
| `--iv_ease-in-out` | `cubic-bezier(0.65, 0, 0.35, 1)` |
| `--iv_ease-out` | `cubic-bezier(0.16, 1, 0.3, 1)` |
| `--iv_ease-snappy` | `cubic-bezier(0.3, 0.7, 0.7, 0.3)` |
| `--iv_ease-spring` | `cubic-bezier(0.34, 1.56, 0.64, 1)` |
| `--iv_motion-fade` | `0.28s` |
| `--iv_motion-fly` | `0.34s` |
| `--iv_motion-scale` | `0.36s` |
| `--iv_motion-slide` | `0.38s` |
| `--iv_motion-subtle` | `0.22s` |
| `--iv_spin-duration` | `0.75s` |
| `--iv_spin-easing` | `cubic-bezier(0.3, 0.7, 0.7, 0.3)` |
| `--iv_spinner-border` | `2px` |
| `--iv_transition-base` | `0.32s` |
| `--iv_transition-fast` | `0.2s` |
| `--iv_transition-slow` | `0.48s` |
## Token map
| Token | Value | Use |
| --- | --- | --- |
| `--iv_transition-fast` | 0.2s | Hover, color, border. |
| `--iv_transition-base` | 0.32s | Focus, selection, state. |
| `--iv_transition-slow` | 0.48s | Larger surface changes. |
| `--iv_motion-fade` | 0.28s | Backdrops and tooltips. |
| `--iv_motion-scale` | 0.36s | Dialogs entering. |
| `--iv_motion-fly` | 0.34s | Sheets and popovers. |
## Reduced motion
The `reducedMotion` store reads the OS preference and flips live. Component transitions use it; the token values also collapse to `0.01ms` under `prefers-reduced-motion: reduce`.
```svelte
…
```
## Related
- [Tokens](https://iv-ui.vercel.app/foundations/tokens.md)
- [Typography](https://iv-ui.vercel.app/foundations/typography.md)