# Accordion

A disclosure list built entirely on native `<details>`/`<summary>` elements — zero JavaScript, zero
ARIA reinvention. The browser supplies the disclosure role, `aria-expanded`, Enter/Space toggling,
focus, and find-in-page expansion for free. Single-open (exclusive) mode uses the platform
exclusive-accordion feature (Baseline 2024): every `<details>` shares one auto-generated `name`, so
the browser closes siblings when one opens. `multiple` drops the shared `name` so each item opens
independently.

The examples are organised by **layer**: the [class reference](https://oriui.vercel.app/#classes&#x29; is the standalone
&#x2A;*`@oriui/css`** layer, and the [Framework API](https://oriui.vercel.app/#framework-api&#x29; is the &#x2A;*`@oriui/vue`** component. Every
example is live — flip its code between **HTML** (the standalone classes, also your htmx / Astro / Svelte /
plain-HTML usage), **Vue**; HTML is the default.

## Classes

The accordion is a block class plus single-class token utilities — one class repoints one token, no
base class needed. The Vue props in [Framework API](https://oriui.vercel.app/#framework-api) map 1:1 to these.

::class-table
---
rows:
  - class: ori-accordion
    type: Block
    description: The accordion container — a wrapper <code><div></code> that carries
      the colour and optional radius utilities; hairline border with clipped
      corners.
  - class: ori-color_*
    type: Color
    description: <b>primary</b> · secondary · success · warn · danger · info · surface
  - class: ori-size-radius_*
    type: Radius
    description: zero · xs · sm · md · lg · xl · rounded
  - class: ori-accordion__item
    type: Part
    description: A native <code><details></code> element, one per item. Open state
      is the native <code>open</code> attribute, styled via
      <code>details[open]</code>.
  - class: ori-accordion__trigger
    type: Part
    description: The native <code><summary></code>; the default marker is suppressed
      and a custom chevron added; focus ring via <code>:focus-visible</code>.
  - class: ori-accordion__title
    type: Part
    description: The item title text; takes the accent colour when its item is open.
  - class: ori-accordion__icon
    type: Part
    description: The decorative chevron <code><svg></code>
      (<code>aria-hidden</code>); rotates when its item is open.
  - class: ori-accordion__panel
    type: Part
    description: The disclosure body wrapper that holds the panel content.
  - class: aria-disabled + tabindex
    type: State
    description: A disabled trigger carries real <code>aria-disabled</code> and
      <code>tabindex=-1</code> attributes, not classes.
---
::

## Anatomy

```text
div.ori-accordion                     (wrapper; carries the color + optional radius utilities)
  details.ori-accordion__item         (one per item; browser owns open attribute)
    summary.ori-accordion__trigger
      span.ori-accordion__title       (heading text)
      svg.ori-accordion__icon         (decorative chevron; aria-hidden)
    div.ori-accordion__panel          (default scoped slot body)
```

## Basic

A single-open accordion (default). Opening one item closes the previous one — enforced natively by
the shared `name` attribute, no JavaScript required.

::example
  :::ori-accordion
  ---
  items:
    - value: one
      title: What is oriUI?
    - value: two
      title: How do I install it?
    - value: three
      title: Does it work without Vue?
  ---
  :::

#vue
```vue
<OriAccordion
    :items="[
        { value: 'one', title: 'What is oriUI?' },
        { value: 'two', title: 'How do I install it?' },
        { value: 'three', title: 'Does it work without Vue?' }
    ]"
>
    <template #default="{ item }">
        <p v-if="item.value === 'one'">oriUI is a layered Vue 3 component library.</p>
        <p v-else-if="item.value === 'two'">Run <code>npm i @oriui/vue</code>.</p>
        <p v-else>Yes — import <code>@oriui/css</code> and use the ori-* classes anywhere.</p>
    </template>
</OriAccordion>
```

#html
```html
<!-- Single-open: give every <details> the same name. -->
<div class="ori-accordion ori-color_primary">
    <details class="ori-accordion__item" name="faq">
        <summary class="ori-accordion__trigger">
            <span class="ori-accordion__title">What is oriUI?</span>
            <svg class="ori-accordion__icon" viewBox="0 0 24 24" aria-hidden="true" xmlns="http://www.w3.org/2000/svg">
                <path d="m6 9 6 6 6-6" />
            </svg>
        </summary>
        <div class="ori-accordion__panel">
            <p>oriUI is a layered Vue 3 component library.</p>
        </div>
    </details>
    <!-- repeat for each item, same name="faq" -->
</div>
```
::

## Multiple open

`multiple` lets any number of items be open simultaneously — each `<details>` opens and closes
independently.

::example
  :::ori-accordion
  ---
  items:
    - value: step1
      title: Step 1 — Install
    - value: step2
      title: Step 2 — Configure
    - value: step3
      title: Step 3 — Deploy
  multiple: true
  ---
  :::

#vue
```vue
<OriAccordion
    multiple
    :items="[
        { value: 'step1', title: 'Step 1 — Install' },
        { value: 'step2', title: 'Step 2 — Configure' },
        { value: 'step3', title: 'Step 3 — Deploy' }
    ]"
>
    <template #default="{ item }">
        <p>Details for {{ item.title }}.</p>
    </template>
</OriAccordion>
```

#html
```html
<!-- Multiple: omit the shared name so items open independently. -->
<div class="ori-accordion ori-color_primary">
    <details class="ori-accordion__item">
        <summary class="ori-accordion__trigger">
            <span class="ori-accordion__title">Step 1 — Install</span>
            <svg class="ori-accordion__icon" viewBox="0 0 24 24" aria-hidden="true" xmlns="http://www.w3.org/2000/svg">
                <path d="m6 9 6 6 6-6" />
            </svg>
        </summary>
        <div class="ori-accordion__panel"><p>Details for Step 1 — Install.</p></div>
    </details>
    <!-- repeat without name for each item -->
</div>
```
::

## Colors

Every semantic role. The accent color is applied to the open item's title and the rotating chevron.

::example
  :::ori-accordion
  ---
  items:
    - value: a
      title: Primary accent
  color: primary
  ---
  :::

  :::ori-accordion
  ---
  items:
    - value: a
      title: Secondary accent
  color: secondary
  ---
  :::

  :::ori-accordion
  ---
  items:
    - value: a
      title: Success accent
  color: success
  ---
  :::

  :::ori-accordion
  ---
  items:
    - value: a
      title: Danger accent
  color: danger
  ---
  :::

  :::ori-accordion
  ---
  items:
    - value: a
      title: Info accent
  color: info
  ---
  :::

#vue
```vue
<OriAccordion color="primary" :items="items" />
<OriAccordion color="secondary" :items="items" />
<OriAccordion color="success" :items="items" />
<OriAccordion color="danger" :items="items" />
<OriAccordion color="info" :items="items" />
```

#html
```html
<!-- swap the color class: ori-color_primary → _secondary / _success / _danger / _info -->
<div class="ori-accordion ori-color_success">…</div>
```
::

## Radius

Corner rounding via the `radius` prop. When omitted, the container uses the baked default `md` (the
`.ori-accordion` block bakes `--ori-size-radius: md`, so a bare block is never square).

::example
  :::ori-accordion
  ---
  items:
    - value: a
      title: zero — no rounding
  radius: zero
  ---
  :::

  :::ori-accordion
  ---
  items:
    - value: a
      title: sm — subtle rounding
  radius: sm
  ---
  :::

  :::ori-accordion
  ---
  items:
    - value: a
      title: md — medium rounding
  radius: md
  ---
  :::

  :::ori-accordion
  ---
  items:
    - value: a
      title: lg — large rounding
  radius: lg
  ---
  :::

  :::ori-accordion
  ---
  items:
    - value: a
      title: xl — extra-large rounding
  radius: xl
  ---
  :::

#vue
```vue
<OriAccordion radius="zero" :items="items" />
<OriAccordion radius="md" :items="items" />
<OriAccordion radius="xl" :items="items" />
```

#html
```html
<!-- attach the radius class: ori-size-radius_md -->
<div class="ori-accordion ori-color_primary ori-size-radius_md">…</div>
```
::

## Disabled items

Set `disabled: true` on individual items in the `items` array to block interaction on those
triggers. Disabled items render `aria-disabled="true"` and `tabindex="-1"` on their `<summary>`.

::example
  :::ori-accordion
  ---
  items:
    - value: billing
      title: Billing
    - value: security
      title: Security (restricted)
      disabled: true
    - value: notifications
      title: Notifications
  ---
  :::

#vue
```vue
<OriAccordion
    :items="[
        { value: 'billing', title: 'Billing' },
        { value: 'security', title: 'Security (restricted)', disabled: true },
        { value: 'notifications', title: 'Notifications' }
    ]"
/>
```

#html
```html
<!-- disabled trigger: aria-disabled + tabindex=-1 on the <summary> -->
<details class="ori-accordion__item" name="settings">
    <summary class="ori-accordion__trigger" aria-disabled="true" tabindex="-1">
        <span class="ori-accordion__title">Security (restricted)</span>
        <svg class="ori-accordion__icon" viewBox="0 0 24 24" aria-hidden="true" xmlns="http://www.w3.org/2000/svg">
            <path d="m6 9 6 6 6-6" />
        </svg>
    </summary>
    <div class="ori-accordion__panel"></div>
</details>
```
::

## Common patterns

Colors, radius, and rich slot content together — a common FAQ or settings pattern.

::example
  :::ori-accordion
  ---
  items:
    - value: cost
      title: Is oriUI free to use?
    - value: framework
      title: Which frameworks are supported?
    - value: theming
      title: How does theming work?
  color: secondary
  radius: md
  ---
  :::

#vue
```vue
<OriAccordion
    color="secondary"
    radius="md"
    :items="[
        { value: 'cost', title: 'Is oriUI free to use?' },
        { value: 'framework', title: 'Which frameworks are supported?' },
        { value: 'theming', title: 'How does theming work?' }
    ]"
>
    <template #default="{ item }">
        <p v-if="item.value === 'cost'">
            Yes — MIT licensed. Use it in personal and commercial projects.
        </p>
        <p v-else-if="item.value === 'framework'">
            Vue 3 via <code>@oriui/vue</code>; any framework or plain HTML via
            <code>@oriui/css</code>.
        </p>
        <p v-else>
            Zero-runtime: toggle a class or attribute and a CSS custom property does the rest.
        </p>
    </template>
</OriAccordion>
```

#html
```html
<div class="ori-accordion ori-color_secondary ori-size-radius_md">
    <details class="ori-accordion__item" name="faq">
        <summary class="ori-accordion__trigger">
            <span class="ori-accordion__title">Is oriUI free to use?</span>
            <svg class="ori-accordion__icon" viewBox="0 0 24 24" aria-hidden="true" xmlns="http://www.w3.org/2000/svg">
                <path d="m6 9 6 6 6-6" />
            </svg>
        </summary>
        <div class="ori-accordion__panel">
            <p>Yes — MIT licensed. Use it in personal and commercial projects.</p>
        </div>
    </details>
    <!-- repeat for each item -->
</div>
```
::

## Accessibility

The accessibility contract holds across every layer — the standalone classes and the Vue component
render the same attributes and keyboard behaviour.

- Built entirely on native `<details>`/`<summary>`: the browser supplies `role="group"` on the
  `<details>` and `role="button"` with `aria-expanded` on the `<summary>` — no ARIA reinvention.
- Single-open mode is enforced by the platform exclusive-accordion (shared `name` attribute,
  Baseline 2024), not script — the browser closes siblings automatically.
- Disabled items use `aria-disabled="true"` and `tabindex="-1"` on the `<summary>` (state via real
  attributes, styled with attribute selectors).
- The chevron SVG is `aria-hidden="true"` — it is purely decorative; the title text is the
  accessible name for each section.
- Focus is always visible via `:focus-visible` on the `<summary>` trigger (inset outline so it
  shows on the row); hover is gated behind `@media (hover: hover)`.

| Key     | Action                                                                   |
| ------- | ------------------------------------------------------------------------ |
| `Enter` | Toggles the focused disclosure item open or closed (native).             |
| `Space` | Toggles the focused disclosure item open or closed (native).             |
| `Tab`   | Moves focus to the next focusable element inside or after the accordion. |

## Framework API

The props, events, slots, and standalone CSS surface of the **Vue** component. The standalone CSS
layer has no component API — its surface is the [classes](https://oriui.vercel.app/#classes) above. (Svelte bindings are
planned.)

### Props

| Prop       | Type                                                                   | Default     | Description                                                                                                                                                                                         |
| ---------- | ---------------------------------------------------------------------- | ----------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `color`    | `ThemeColor`                                                           | `'primary'` | Accent color for the open item's title and the rotating chevron. Repoints `--ori-color` via the `ori-color_<color>` utility class on the wrapper.                                                   |
| `items`    | `Array<{ value: string | number; title: string; disabled?: boolean }>` | —           | **Required.** The disclosure items. `value` is used as the `:key`; `title` is the summary text; `disabled` sets `aria-disabled="true"` + `tabindex="-1"` and blocks pointer events on that trigger. |
| `multiple` | `boolean`                                                              | `false`     | `false` = exclusive single-open (shared `name`, browser closes siblings). `true` = each item opens/closes independently (no shared `name`).                                                         |
| `radius`   | `RadiusSize`                                                           | `'md'`      | Optional corner radius for the accordion container. Attaches `ori-size-radius_<radius>` when set; the bare block bakes in `md` as its default.                                                      |

### Events & attributes

`OriAccordion` declares **no custom emits**. Open state is owned by the browser's native
`<details>` mechanism — there is no `v-model` and no Vue toggle. The component does not set
`inheritAttrs: false`, so extra attributes (`class`, `data-*`, `id`, …) fall through to the root
`div.ori-accordion`.

### Slots

| Slot      | Scope                                                                     | Description                                                                                                                                             |
| --------- | ------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `title`   | `{ item: { value: string | number; title: string; disabled?: boolean } }` | Scoped per-item trigger content, rendered inside each item's `.ori-accordion__title`. Receives the current item; falls back to the `item.title` string. |
| `default` | `{ item: { value: string | number; title: string; disabled?: boolean } }` | Scoped per-item panel body, rendered inside each item's `.ori-accordion__panel`. Receives the current item; falls back to an empty panel if unused.     |


# Alert

A styled, accessible notification banner. Its live-region politeness is derived from the color —
urgent `danger` / `warn` render `role="alert"` (assertive), everything else `role="status"` (polite) —
so a non-urgent banner isn't announced assertively (override with the `live` prop). It supports an
optional icon, a title, body text, an actions row, and a dismiss button.

The examples are organised by **layer**: the [class reference](https://oriui.vercel.app/#classes&#x29; is the standalone
&#x2A;*`@oriui/css`** layer, and the [Framework API](https://oriui.vercel.app/#framework-api&#x29; is the &#x2A;*`@oriui/vue`** component. Every
example is live — flip its code between **HTML** (the standalone classes, also your htmx / Astro / Svelte /
plain-HTML usage), **Vue**; HTML is the default.

## Classes

An alert is a block class plus single-class token utilities — one class repoints one token; no base
class needed. The Vue props in [Framework API](https://oriui.vercel.app/#framework-api) map 1:1 to these.

::class-table
---
rows:
  - class: ori-alert
    type: Block
    description: Required base class. The Vue component sets role=alert
      (danger/warn) or role=status (otherwise); standalone markup picks the role
      itself.
  - class: ori-variant_*
    type: Style
    description: fill · <b>tonal</b> · outline · text · plain
  - class: ori-color_*
    type: Color
    description: primary · secondary · success · warn · danger · <b>info</b> ·
      surface · background
  - class: ori-size-radius_*
    type: Radius
    description: zero · xs · sm · <b>md</b> · lg · xl · rounded
  - class: ori-font-size_*
    type: Size
    description: xs · sm · <b>md</b> · lg · xl · xxl — scales the body text
  - class: ori-alert__icon · ori-alert__content · ori-alert__title · ori-alert__body
      · ori-alert__actions · ori-alert__close
    type: Part
    description: internal layout elements
---
::

Like Button, the non-fill variants (the default `tonal` included) paint the body text with the
AA-safe `--ori-color-text` tone rather than the raw role — see
[Design tokens](https://oriui.vercel.app/guides/design-tokens#text-the-on-surface-foreground).

## Variants

Five visual styles, all driven by the `ori-variant_*` utility. `tonal` is the default.

::example
:ori-alert{color="info" text="Fill alert" variant="fill"}

:ori-alert{color="info" text="Tonal alert" variant="tonal"}

:ori-alert{color="info" text="Outline alert" variant="outline"}

:ori-alert{color="info" text="Text alert" variant="text"}

:ori-alert{color="info" text="Plain alert" variant="plain"}

#vue
```vue
<OriAlert text="Fill alert" variant="fill" color="info" />
<OriAlert text="Tonal alert" variant="tonal" color="info" />
<OriAlert text="Outline alert" variant="outline" color="info" />
<OriAlert text="Text alert" variant="text" color="info" />
<OriAlert text="Plain alert" variant="plain" color="info" />
```

#html
```html
<div class="ori-alert ori-variant_tonal ori-color_info" role="status">
    <div class="ori-alert__content">
        <div class="ori-alert__body">Tonal alert</div>
    </div>
</div>
<!-- swap the variant: ori-variant_tonal → ori-variant_fill / ori-variant_outline / ori-variant_text / ori-variant_plain -->
```
::

## Colors

Every semantic role. Use `success`, `warn`, `danger`, and `info` for status messages.

::example
:ori-alert{color="primary" text="Primary"}

:ori-alert{color="secondary" text="Secondary"}

:ori-alert{color="success" text="Success"}

:ori-alert{color="warn" text="Warning"}

:ori-alert{color="danger" text="Danger"}

:ori-alert{color="info" text="Info"}

#vue
```vue
<OriAlert text="Primary" color="primary" />
<OriAlert text="Success" color="success" />
<OriAlert text="Warning" color="warn" />
<OriAlert text="Danger" color="danger" />
<OriAlert text="Info" color="info" />
```

#html
```html
<!-- swap the color: ori-color_info → ori-color_success / ori-color_warn / ori-color_danger / ori-color_primary -->
<div class="ori-alert ori-variant_tonal ori-color_danger" role="alert">
    <div class="ori-alert__content">
        <div class="ori-alert__body">Danger</div>
    </div>
</div>
```
::

Variant and color compose freely — e.g. an outline danger alert:

::example
:ori-alert{color="danger" text="Something went wrong. Please try again." variant="outline"}

:ori-alert{color="success" text="Your changes have been saved." variant="fill"}

#vue
```vue
<OriAlert text="Something went wrong. Please try again." variant="outline" color="danger" />
<OriAlert text="Your changes have been saved." variant="fill" color="success" />
```

#html
```html
<div class="ori-alert ori-variant_outline ori-color_danger" role="alert">
    <div class="ori-alert__content">
        <div class="ori-alert__body">Something went wrong. Please try again.</div>
    </div>
</div>
```
::

## With title

Pass `title` to add a bold heading above the body text.

::example
:ori-alert{color="warn" text="Please sign in again to continue." title="Session expired"}

#vue
```vue
<OriAlert title="Session expired" text="Please sign in again to continue." color="warn" />
```

#html
```html
<div class="ori-alert ori-variant_tonal ori-color_warn" role="alert">
    <div class="ori-alert__content">
        <div class="ori-alert__title">Session expired</div>
        <div class="ori-alert__body">Please sign in again to continue.</div>
    </div>
</div>
```
::

## With icon

Pass an SVG path to `icon` to prepend a visual cue.

::example
  :::ori-alert
  ---
  color: success
  icon: M9 16.17 4.83 12l-1.42 1.41L9 19 21 7l-1.41-1.41z
  text: Your profile has been updated.
  title: Success
  ---
  :::

  :::ori-alert
  ---
  color: warn
  icon: M1 21h22L12 2 1 21zm12-3h-2v-2h2v2zm0-4h-2v-4h2v4z
  text: Disk space is running low.
  title: Warning
  ---
  :::

  :::ori-alert
  ---
  color: danger
  icon: M12 2C6.48 2 2 6.48 2 12s4.48 10 10 10 10-4.48 10-10S17.52 2 12 2zm1
    15h-2v-2h2v2zm0-4h-2V7h2v6z
  text: Failed to load data.
  title: Error
  ---
  :::

#vue
```vue
<!-- success -->
<OriAlert
    title="Success"
    text="Your profile has been updated."
    color="success"
    icon="M9 16.17 4.83 12l-1.42 1.41L9 19 21 7l-1.41-1.41z"
/>
<!-- warning -->
<OriAlert
    title="Warning"
    text="Disk space is running low."
    color="warn"
    icon="M1 21h22L12 2 1 21zm12-3h-2v-2h2v2zm0-4h-2v-4h2v4z"
/>
```

#html
```html
<div class="ori-alert ori-variant_tonal ori-color_success" role="status">
    <div class="ori-alert__icon">
        <i class="ori-icon" aria-hidden="true">
            <svg viewBox="0 0 24 24"><path d="M9 16.17 4.83 12l-1.42 1.41L9 19 21 7l-1.41-1.41z" /></svg>
        </i>
    </div>
    <div class="ori-alert__content">
        <div class="ori-alert__title">Success</div>
        <div class="ori-alert__body">Your profile has been updated.</div>
    </div>
</div>
```
::

## Dismissible

`closable` adds a close button in the top-right corner. Handle the `close` event to remove or hide
the alert. The button label defaults to `"Dismiss"` and is configurable via `closeLabel`.

::example
  :::ori-alert
  ---
  closable: true
  color: info
  text: A new version is ready to install.
  title: Update available
  ---
  :::

#vue
```vue
<script setup lang="ts">
import { ref } from 'vue';
const visible = ref(true);
</script>

<template>
    <OriAlert
        v-if="visible"
        title="Update available"
        text="A new version is ready to install."
        color="info"
        closable
        @close="visible = false"
    />
</template>
```

#html
```html
<div class="ori-alert ori-variant_tonal ori-color_info" role="status">
    <div class="ori-alert__content">
        <div class="ori-alert__title">Update available</div>
        <div class="ori-alert__body">A new version is ready to install.</div>
    </div>
    <button type="button" class="ori-alert__close" aria-label="Dismiss">
        <!-- close icon -->
    </button>
</div>
```
::

## Sizes

`size` scales the body text from `xs` to `xxl`. The default is `md`.

::example
:ori-alert{color="info" size="xs" text="Extra small alert"}

:ori-alert{color="info" size="sm" text="Small alert"}

:ori-alert{color="info" size="md" text="Medium alert (default)"}

:ori-alert{color="info" size="lg" text="Large alert"}

#vue
```vue
<OriAlert text="Extra small alert" size="xs" color="info" />
<OriAlert text="Small alert" size="sm" color="info" />
<OriAlert text="Medium alert (default)" size="md" color="info" />
<OriAlert text="Large alert" size="lg" color="info" />
```

#html
```html
<!-- swap the font-size: ori-font-size_md → ori-font-size_xs / ori-font-size_sm / ori-font-size_lg / ori-font-size_xl / ori-font-size_xxl -->
<div class="ori-alert ori-font-size_lg ori-variant_tonal ori-color_info" role="status">
    <div class="ori-alert__content">
        <div class="ori-alert__body">Large alert</div>
    </div>
</div>
```
::

## Radius

From `zero` (sharp corners) to `rounded` (pill). Default is `md`.

::example
:ori-alert{color="info" radius="zero" text="No radius"}

:ori-alert{color="info" radius="sm" text="Small radius"}

:ori-alert{color="info" radius="md" text="Medium radius (default)"}

:ori-alert{color="info" radius="lg" text="Large radius"}

:ori-alert{color="info" radius="rounded" text="Rounded"}

#vue
```vue
<OriAlert text="No radius" radius="zero" color="info" />
<OriAlert text="Medium radius (default)" radius="md" color="info" />
<OriAlert text="Rounded" radius="rounded" color="info" />
```

#html
```html
<!-- swap the radius: ori-size-radius_md → ori-size-radius_zero / ori-size-radius_sm / ori-size-radius_lg / ori-size-radius_xl / ori-size-radius_rounded -->
<div class="ori-alert ori-size-radius_rounded ori-variant_tonal ori-color_info" role="status">
    <div class="ori-alert__content">
        <div class="ori-alert__body">Rounded</div>
    </div>
</div>
```
::

## Common patterns

A form submission result and a persistent banner with actions — the everyday compositions.

::example
  :::ori-alert
  ---
  closable: true
  color: danger
  icon: M12 2C6.48 2 2 6.48 2 12s4.48 10 10 10 10-4.48 10-10S17.52 2 12 2zm1
    15h-2v-2h2v2zm0-4h-2V7h2v6z
  text: Your card was declined. Check your details and try again.
  title: Payment failed
  variant: outline
  ---
  :::

#vue
```vue
<!-- form error banner -->
<OriAlert
    title="Payment failed"
    text="Your card was declined. Check your details and try again."
    color="danger"
    variant="outline"
    icon="M12 2C6.48 2 2 6.48 2 12s4.48 10 10 10 10-4.48 10-10S17.52 2 12 2zm1 15h-2v-2h2v2zm0-4h-2V7h2v6z"
    closable
    @close="handleDismiss"
/>

<!-- alert with an actions slot -->
<OriAlert
    title="New terms of service"
    text="We have updated our terms. Please review before continuing."
    color="warn"
    variant="tonal"
>
    <template #actions>
        <OriButton text="Review" size="sm" variant="tonal" color="warn" />
        <OriButton text="Dismiss" size="sm" variant="text" color="warn" />
    </template>
</OriAlert>
```

#html
```html
<!-- form error banner -->
<div class="ori-alert ori-variant_outline ori-color_danger" role="alert">
    <div class="ori-alert__icon">
        <i class="ori-icon" aria-hidden="true">
            <svg viewBox="0 0 24 24">
                <path
                    d="M12 2C6.48 2 2 6.48 2 12s4.48 10 10 10 10-4.48 10-10S17.52 2 12 2zm1 15h-2v-2h2v2zm0-4h-2V7h2v6z"
                />
            </svg>
        </i>
    </div>
    <div class="ori-alert__content">
        <div class="ori-alert__title">Payment failed</div>
        <div class="ori-alert__body">Your card was declined. Check your details and try again.</div>
    </div>
    <button type="button" class="ori-alert__close" aria-label="Dismiss"><!-- icon --></button>
</div>

<!-- alert with actions row -->
<div class="ori-alert ori-variant_tonal ori-color_warn" role="alert">
    <div class="ori-alert__content">
        <div class="ori-alert__title">New terms of service</div>
        <div class="ori-alert__body">We have updated our terms. Please review before continuing.</div>
        <div class="ori-alert__actions">
            <button class="ori-button ori-variant_tonal ori-color_warn …">Review</button>
            <button class="ori-button ori-variant_text ori-color_warn …">Dismiss</button>
        </div>
    </div>
</div>
```
::

## Accessibility

The accessibility contract holds across every layer — the standalone classes and the Vue component
render the same attributes.

- The **live-region politeness is derived from the color** so non-urgent content isn't announced
  assertively: urgent colors (`danger` / `warn`) render `role="alert"` (`aria-live="assertive"` —
  interrupts the screen reader), and everything else (the `info` default, `success`, …) renders
  `role="status"` (`aria-live="polite"` — announced at the next pause). Override with the `live` prop
  (`assertive` / `polite` / `off`); `off` removes the live region entirely (for content that is part of
  the static page and shouldn't be announced as it appears).
- Icons inside the alert are decorative (`aria-hidden="true"` on the `ori-icon`); the alert text itself
  is the accessible announcement.
- The dismiss button has an `aria-label` (default `"Dismiss"`, configurable via `closeLabel`) so its
  purpose is clear without visible text.
- The dismiss button has a visible `:focus-visible` ring. No other keyboard interaction is required;
  the alert itself is not focusable.
- For a **live** announcement, insert (or reveal) the element with its content already in place — some
  screen readers announce only content present when the region appears. For content that is part of the
  page on load, prefer `live="off"` (or a non-urgent color) so it isn't announced as the page renders.

| Key     | Action                                          |
| ------- | ----------------------------------------------- |
| `Tab`   | Moves focus to the dismiss button (if present). |
| `Enter` | Activates the focused dismiss button.           |
| `Space` | Activates the focused dismiss button.           |

## Framework API

The props, events, slots, and slots of the **Vue** component. The standalone CSS layer has no
component API — its surface is the [classes](https://oriui.vercel.app/#classes) above. (Svelte bindings are planned.)

### Props

| Prop         | Type                                              | Default     | Description                                                                                                                                                     |
| ------------ | ------------------------------------------------- | ----------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `closable`   | `boolean`                                         | `false`     | Renders a dismiss button; emit `close` to remove the alert.                                                                                                     |
| `closeLabel` | `string`                                          | `'Dismiss'` | `aria-label` on the dismiss button.                                                                                                                             |
| `color`      | `ThemeColor`                                      | `'info'`    | Semantic role: primary · secondary · success · warn · danger · info · surface · background.                                                                     |
| `icon`       | `string`                                          | —           | SVG path for the leading icon. Use the `icon` slot for custom markup.                                                                                           |
| `live`       | `'assertive' | 'polite' | 'off'`                  | *derived*   | Live-region politeness. Defaults to `assertive` (`role="alert"`) for `danger` / `warn` and `polite` (`role="status"`) otherwise; `off` removes the live region. |
| `radius`     | `RadiusSize`                                      | `'md'`      | Corner radius (`zero` · xs · sm · md · lg · xl · `rounded`).                                                                                                    |
| `size`       | `ActionSize`                                      | `'md'`      | Body font scale (`xs`–`xxl`).                                                                                                                                   |
| `text`       | `string`                                          | —           | Body text. Use the `default` slot for richer markup.                                                                                                            |
| `title`      | `string`                                          | —           | Bold heading above the body. Use the `title` slot for richer markup.                                                                                            |
| `variant`    | `'fill' | 'tonal' | 'outline' | 'text' | 'plain'` | `'tonal'`   | Visual style.                                                                                                                                                   |

`ThemeColor`: `'primary' | 'secondary' | 'success' | 'warn' | 'danger' | 'info' | 'surface' | 'background'`

`ActionSize`: `'text' | 'xs' | 'sm' | 'md' | 'lg' | 'xl' | 'xxl'`

`RadiusSize`: `'zero' | 'xs' | 'sm' | 'md' | 'lg' | 'xl' | 'rounded'`

### Events & attributes

| Event   | Payload | Description                                                                     |
| ------- | ------- | ------------------------------------------------------------------------------- |
| `close` | —       | Emitted when the dismiss button is clicked. Use it to hide or remove the alert. |

OriAlert does not set `inheritAttrs: false`, so extra attributes (`class`, `style`, `data-*`, …)
fall through to the root `<div>` (whose `role` is `alert` / `status` / none per the `live` rule above).

### Slots

| Slot      | Description                                                                                                                            |
| --------- | -------------------------------------------------------------------------------------------------------------------------------------- |
| `default` | Body content. Replaces the `text` prop; renders inside `ori-alert__body`.                                                              |
| `icon`    | Custom icon markup. Replaces the `icon` prop; renders inside `ori-alert__icon`.                                                        |
| `title`   | Custom title markup. Replaces the `title` prop; renders inside `ori-alert__title`.                                                     |
| `actions` | Action controls (buttons, links) rendered in a flex row below the body (`ori-alert__actions`). Only mounted when the slot is provided. |


# Avatar

A data-display component that shows an image, or initials derived from `text` when there is no
image (or while it loads). Supports a title / subtitle column for list and profile UIs.

The examples are organised by **layer**: the [class reference](https://oriui.vercel.app/#classes&#x29; is the standalone
&#x2A;*`@oriui/css`** layer, and the [Framework API](https://oriui.vercel.app/#framework-api&#x29; is the &#x2A;*`@oriui/vue`** component. Every
example is live — flip its code between **HTML** (the standalone classes, also your htmx / Astro / Svelte /
plain-HTML usage), **Vue**; HTML is the default.

## Classes

An avatar is a block class plus single-class token utilities — one class repoints one token; no
separate base class is needed. The Vue props in [Framework API](https://oriui.vercel.app/#framework-api) mirror these — font
size and the titled layout are derived from `size` and `title` / `subtitle`. There is no variant;
an optional `color` tints the initials backdrop.

::class-table
---
rows:
  - class: ori-avatar
    type: Block
    description: Required base class.
  - class: ori-color_*
    type: Color
    description: primary · secondary · success · warn · danger · info · surface ·
      background — tints the initials backdrop
  - class: ori-avatar_* (size)
    type: Size
    description: xs · sm · md · <b>lg</b> · xl · xxl
  - class: ori-size-action-space_*
    type: Size
    description: adds margin around the avatar when <code>spaced</code> is set
  - class: ori-size-radius_*
    type: Radius
    description: zero · xs · sm · md · lg · xl · <b>rounded</b>
  - class: ori-font-size_*
    type: Font
    description: scales the initials text with the avatar size
  - class: ori-avatar__image · ori-avatar__backdrop · ori-avatar__text ·
      ori-avatar__title · ori-avatar__subtitle
    type: Part
    description: image / initials fallback / text column / title / subtitle
  - class: ori-avatar_inline · ori-avatar_titled · ori-avatar_reverse
    type: Layout
    description: inline flow · title+subtitle layout · reversed image/text order
---
::

## Image & initials

`src` (and any other image attribute) falls through via `$attrs` to the `<img>` element. When no
`src` is present — or while the image loads — the initials backdrop is shown instead, computing up
to two letters from the first two words of `text`.

::example
:ori-avatar{src="https://oriui.vercel.app/image-example.jpg" text="Marcus Tullius Cicero"}

:ori-avatar{text="Marcus Tullius Cicero"}

:ori-avatar{text="Ada Lovelace"}

#vue
```vue
<OriAvatar src="/portrait.jpg" text="Marcus Tullius Cicero" />
<!-- no src — initials "MT" are derived from text -->
<OriAvatar text="Marcus Tullius Cicero" />
<!-- two words — initials "AL" -->
<OriAvatar text="Ada Lovelace" />
```

#html
```html
<!-- with image — bare .ori-avatar is already lg + rounded (defaults baked in) -->
<div class="ori-avatar">
    <img class="ori-avatar__image" src="/portrait.jpg" alt="Marcus Tullius Cicero" />
</div>

<!-- initials fallback: backdrop is aria-hidden -->
<div class="ori-avatar">
    <div class="ori-avatar__backdrop" aria-hidden="true">MT</div>
</div>
```
::

## Colors

An optional `color` tints the initials backdrop using the standard semantic token. Has no effect
when an image is showing.

::example
:ori-avatar{color="primary" text="Primary"}

:ori-avatar{color="secondary" text="Secondary"}

:ori-avatar{color="success" text="Success"}

:ori-avatar{color="warn" text="Warn Color"}

:ori-avatar{color="danger" text="Danger"}

:ori-avatar{color="info" text="Info"}

:ori-avatar{color="surface" text="Surface"}

:ori-avatar{color="background" text="Background"}

#vue
```vue
<OriAvatar text="Primary" color="primary" />
<OriAvatar text="Danger" color="danger" />
<OriAvatar text="Info" color="info" />
<OriAvatar text="Surface" color="surface" />
<OriAvatar text="Background" color="background" />
```

#html
```html
<div class="ori-avatar ori-color_danger">
    <div class="ori-avatar__backdrop" aria-hidden="true">D</div>
</div>
```
::

## Sizes

`xs` → `xxl`. The size drives the box dimensions (`ori-avatar_*`) and the initials scale
(`ori-font-size_*`). Default is `lg`.

::example
:ori-avatar{size="xs" text="Extra Small"}

:ori-avatar{size="sm" text="Small"}

:ori-avatar{size="md" text="Medium"}

:ori-avatar{size="lg" text="Large"}

:ori-avatar{size="xl" text="Extra Large"}

:ori-avatar{size="xxl" text="Double Extra"}

#vue
```vue
<OriAvatar text="Small" size="sm" />
<OriAvatar text="Large" size="lg" />
<OriAvatar text="Extra Large" size="xl" />
```

#html
```html
<div class="ori-avatar ori-avatar_sm ori-font-size_sm">
    <div class="ori-avatar__backdrop" aria-hidden="true">S</div>
</div>
<div class="ori-avatar ori-avatar_xl ori-font-size_xl">
    <div class="ori-avatar__backdrop" aria-hidden="true">EL</div>
</div>
```
::

## Radius

From `zero` (square) to the default `rounded` (full pill / circle).

::example
:ori-avatar{radius="zero" text="Zero"}

:ori-avatar{radius="sm" text="Small"}

:ori-avatar{radius="md" text="Medium"}

:ori-avatar{radius="lg" text="Large"}

:ori-avatar{radius="rounded" text="Rounded"}

#vue
```vue
<OriAvatar text="Zero" radius="zero" />
<OriAvatar text="Rounded" radius="rounded" />
```

#html
```html
<div class="ori-avatar ori-size-radius_zero">
    <div class="ori-avatar__backdrop" aria-hidden="true">Z</div>
</div>
```
::

## With title & subtitle

Pass `title` and/or `subtitle` to show a text column beside the image or initials. The root
element switches to `max-content` width via `ori-avatar_titled`.

::example
  :::ori-avatar
  ---
  src: https://oriui.vercel.app/image-example.jpg
  subtitle: statesman · lawyer · writer · orator
  text: Marcus Tullius Cicero
  title: Marcus Tullius Cicero
  ---
  :::

  :::ori-avatar
  ---
  color: secondary
  subtitle: mathematician · first programmer
  text: Ada Lovelace
  title: Ada Lovelace
  ---
  :::

#vue
```vue
<OriAvatar
    src="/portrait.jpg"
    text="Marcus Tullius Cicero"
    title="Marcus Tullius Cicero"
    subtitle="statesman · lawyer · writer · orator"
/>
<!-- initials with title -->
<OriAvatar text="Ada Lovelace" color="secondary" title="Ada Lovelace" subtitle="mathematician · first programmer" />
```

#html
```html
<!-- ori-avatar_titled activates the text column layout -->
<div class="ori-avatar ori-avatar_titled">
    <img class="ori-avatar__image" src="/portrait.jpg" alt="Marcus Tullius Cicero" />
    <div class="ori-avatar__text">
        <div class="ori-avatar__title">Marcus Tullius Cicero</div>
        <div class="ori-avatar__subtitle">statesman · lawyer · writer · orator</div>
    </div>
</div>
```
::

## Reversed

`reverse` flips the layout so the text column appears before the image.

::example
  :::ori-avatar
  ---
  reverse: true
  color: primary
  subtitle: mathematician
  text: Ada Lovelace
  title: Ada Lovelace
  ---
  :::

#vue
```vue
<OriAvatar text="Ada Lovelace" color="primary" title="Ada Lovelace" subtitle="mathematician" reverse />
```

#html
```html
<div class="ori-avatar ori-avatar_titled ori-avatar_reverse ori-color_primary">
    <div class="ori-avatar__text">
        <div class="ori-avatar__title">Ada Lovelace</div>
        <div class="ori-avatar__subtitle">mathematician</div>
    </div>
    <div class="ori-avatar__backdrop" aria-hidden="true">AL</div>
</div>
```
::

## Inline

`inline` renders the avatar as `inline-flex` with a small margin, so it flows inside a sentence or
a tag list.

::example
  :::ori-avatar{inline size="xs" text="Ada Lovelace"}
  :::

  :::ori-avatar
  ---
  inline: true
  color: secondary
  size: xs
  text: Marcus Tullius
  ---
  :::

#vue
```vue
<OriAvatar text="Ada Lovelace" size="xs" inline />
<OriAvatar text="Marcus Tullius" size="xs" color="secondary" inline />
```

#html
```html
<div class="ori-avatar ori-avatar_inline ori-avatar_xs ori-font-size_xs">
    <div class="ori-avatar__backdrop" aria-hidden="true">AL</div>
</div>
```
::

## Spaced

`spaced` adds padding around the avatar via `ori-size-action-space`, useful when the avatar sits
inside a container that provides no gap of its own.

::example
  :::ori-avatar{spaced text="Ada Lovelace"}
  :::

  :::ori-avatar{spaced color="secondary" text="Marcus Tullius"}
  :::

#vue
```vue
<OriAvatar text="Ada Lovelace" spaced />
<OriAvatar text="Marcus Tullius" color="secondary" spaced />
```

#html
```html
<div class="ori-avatar ori-size-action-space_lg">
    <div class="ori-avatar__backdrop" aria-hidden="true">AL</div>
</div>
```
::

## Common patterns

A user-list row and a comment header — the everyday compositions.

::example
  :::ori-avatar
  ---
  src: https://oriui.vercel.app/image-example.jpg
  subtitle: Admin
  text: Marcus Tullius Cicero
  title: Marcus Tullius Cicero
  ---
  :::

  :::ori-avatar
  ---
  color: secondary
  subtitle: Editor
  text: Ada Lovelace
  title: Ada Lovelace
  ---
  :::

  :::ori-avatar
  ---
  color: surface
  subtitle: Guest
  text: Unknown User
  title: Unknown User
  ---
  :::

#vue
```vue
<!-- user list row -->
<ul style="display: flex; flex-direction: column; gap: 0.75rem; list-style: none; padding: 0">
    <li v-for="user in users" :key="user.id">
        <OriAvatar
            :src="user.avatar"
            :text="user.name"
            :title="user.name"
            :subtitle="user.role"
        />
    </li>
</ul>
```

#html
```html
<ul style="display: flex; flex-direction: column; gap: 0.75rem; list-style: none; padding: 0">
    <li>
        <div class="ori-avatar ori-avatar_titled">
            <img class="ori-avatar__image" src="/portrait.jpg" alt="Marcus Tullius Cicero" />
            <div class="ori-avatar__text">
                <div class="ori-avatar__title">Marcus Tullius Cicero</div>
                <div class="ori-avatar__subtitle">Admin</div>
            </div>
        </div>
    </li>
</ul>
```
::

## Accessibility

The accessibility contract holds across every layer — the standalone classes and the Vue component
render the same attributes.

- The `<img>` `alt` is always set — to the `text` prop value, or `''` (empty, decorative) when
  `text` is omitted. Do not pass a separate `alt` via `$attrs`; it will be overridden.
- The initials backdrop is `aria-hidden="true"` — it is a visual fallback, not semantic content.
- The `<img>` is revealed only after the `load` event fires (`v-show`), preventing a flash of a
  broken-image icon while the initials are still visible.
- There is no interactive behaviour; the component has no keyboard contract of its own. Wrap it in a
  `<button>` or `<a>` when it needs to be activatable, and supply an `aria-label` on the wrapper.

| Attribute            | Element      | Notes                                                            |
| -------------------- | ------------ | ---------------------------------------------------------------- |
| `alt` (from `text`)  | `<img>`      | Set automatically; omit `alt` in `$attrs` — it will be replaced. |
| `aria-hidden="true"` | `__backdrop` | Initials are decorative; screen readers read the image `alt`.    |

## Framework API

The props, events, and slots of the **Vue** component. The standalone CSS layer has no component
API — its surface is the [classes](https://oriui.vercel.app/#classes) above. (Svelte bindings are planned.)

### Props

| Prop       | Type         | Default     | Description                                                                                                               |
| ---------- | ------------ | ----------- | ------------------------------------------------------------------------------------------------------------------------- |
| `color`    | `ThemeColor` | —           | Tints the initials backdrop: `primary` · `secondary` · `success` · `warn` · `danger` · `info` · `surface` · `background`. |
| `inline`   | `boolean`    | `false`     | Renders as `inline-flex` with a small margin for flowing inside text.                                                     |
| `radius`   | `RadiusSize` | `'rounded'` | Corner radius (`zero` · `xs` · `sm` · `md` · `lg` · `xl` · `rounded`).                                                    |
| `reverse`  | `boolean`    | `false`     | Reverses the flex direction so the text column appears before the image.                                                  |
| `size`     | `ActionSize` | `'lg'`      | Box size and initials scale (`xs` · `sm` · `md` · `lg` · `xl` · `xxl`).                                                   |
| `spaced`   | `boolean`    | `false`     | Adds padding around the avatar via `ori-size-action-space`.                                                               |
| `subtitle` | `string`     | —           | Secondary line in the text column; rendered whenever `title` or `subtitle` is set.                                        |
| `text`     | `string`     | —           | Drives the initials (up to two letters from the first two words) and the image `alt`.                                     |
| `title`    | `string`     | —           | Primary line in the text column; the text column appears when either `title` or `subtitle` is set.                        |

### Events & attributes

OriAvatar declares **no custom events**. It sets `inheritAttrs: false` and applies `v-bind="$attrs"`
directly to the `<img>` element — so `src`, `alt`, `width`, `height`, `loading`, `decoding`, and
any other image attribute or listener fall through to the image, not the wrapper `<div>`. Native
event listeners (`@error`, `@load`, …) follow the same path.

The `alt` attribute is overridden internally to the value of `text` (or `''` when `text` is not set)
so there is a single source of truth for the accessible name.

### Slots

Each slot overrides the content it names; leave it out and the component falls back to the derived
value or prop. The image itself is not slotted — it comes through `$attrs` (see above).

| Slot       | Falls back to                    | Description                                                                                                   |
| ---------- | -------------------------------- | ------------------------------------------------------------------------------------------------------------- |
| `fallback` | the initials derived from `text` | Imageless fallback content — e.g. a person icon or monogram — shown when there is no image or while it loads. |
| `title`    | `title` prop                     | Primary line in the text column.                                                                              |
| `subtitle` | `subtitle` prop                  | Secondary line in the text column.                                                                            |

The text column appears when any of `title` / `subtitle` (prop **or** slot) is set. The `#fallback`
slot fills the `aria-hidden` backdrop, so keep its content decorative — the accessible name still
comes from the image `alt`.


# Badge

A small status or count indicator. Attach it to any element as a floating pip, drop it inline next
to text, or render it standalone — all three modes share the same class surface.

The examples are organised by **layer**: the [class reference](https://oriui.vercel.app/#classes&#x29; is the standalone
&#x2A;*`@oriui/css`** layer, and the [Framework API](https://oriui.vercel.app/#framework-api&#x29; is the &#x2A;*`@oriui/vue`** component. Every
example is live — flip its code between **HTML** (the standalone classes, also your htmx / Astro / Svelte /
plain-HTML usage), **Vue**; HTML is the default.

## Classes

A badge is a block class plus single-class token utilities — one class repoints one token; no base
class is needed. The Vue props in [Framework API](https://oriui.vercel.app/#framework-api) map 1:1 to these. Two layout
modifiers (`ori-badge_dot`, `ori-badge_floating`) and the wrapper class (`ori-badge-anchor`)
complete the floating pattern.

::class-table
---
rows:
  - class: ori-badge
    type: Block
    description: "Required base class. Defaults baked in: fill variant, primary
      color, rounded radius."
  - class: ori-variant_*
    type: Style
    description: <b>fill</b> · tonal · outline · text · plain
  - class: ori-color_*
    type: Color
    description: <b>primary</b> · secondary · success · warn · danger · info ·
      surface · background
  - class: ori-size-radius_*
    type: Radius
    description: zero · xs · sm · md · lg · xl · <b>rounded</b>
  - class: ori-badge_dot
    type: Layout
    description: collapses the badge to a small filled circle; content is hidden
  - class: ori-badge_floating
    type: Layout
    description: positions the badge in the top-end corner of its anchor wrapper
  - class: ori-badge-anchor
    type: Wrapper
    description: position:relative wrapper required for floating badges
---
::

## Variants

Five visual styles, driven by the `ori-variant_*` single-class token.

::example
:ori-badge{content="Fill" variant="fill"}

:ori-badge{content="Tonal" variant="tonal"}

:ori-badge{content="Outline" variant="outline"}

:ori-badge{content="Text" variant="text"}

:ori-badge{content="Plain" variant="plain"}

#vue
```vue
<OriBadge content="Fill" variant="fill" />
<OriBadge content="Tonal" variant="tonal" />
<OriBadge content="Outline" variant="outline" />
<OriBadge content="Text" variant="text" />
<OriBadge content="Plain" variant="plain" />
```

#html
```html
<span class="ori-badge">Fill</span>
<!-- swap the variant: ori-variant_tonal / _outline / _text / _plain -->
<span class="ori-badge ori-variant_tonal">Tonal</span>
```
::

## Colors

All semantic roles. The badge inherits the shared `ori-color_*` token, so variant × color compose freely.

::example
:ori-badge{color="primary" content="primary"}

:ori-badge{color="secondary" content="secondary"}

:ori-badge{color="success" content="success"}

:ori-badge{color="warn" content="warn"}

:ori-badge{color="danger" content="danger"}

:ori-badge{color="info" content="info"}

:ori-badge{color="surface" content="surface"}

#vue
```vue
<OriBadge content="primary" color="primary" />
<OriBadge content="danger" color="danger" />
<OriBadge content="info" color="info" />
```

#html
```html
<span class="ori-badge ori-color_danger">danger</span>
```
::

Variant × color compose freely — e.g. a tonal success badge or an outline danger badge:

::example
:ori-badge{color="success" content="Approved" variant="tonal"}

:ori-badge{color="danger" content="Error" variant="outline"}

:ori-badge{color="info" content="Beta" variant="tonal"}

#vue
```vue
<OriBadge content="Approved" variant="tonal" color="success" />
<OriBadge content="Error" variant="outline" color="danger" />
<OriBadge content="Beta" variant="tonal" color="info" />
```

#html
```html
<span class="ori-badge ori-variant_tonal ori-color_success">Approved</span>
<span class="ori-badge ori-variant_outline ori-color_danger">Error</span>
```
::

## Radius

From `zero` (square) to the default `rounded` (pill).

::example
:ori-badge{content="zero" radius="zero"}

:ori-badge{content="sm" radius="sm"}

:ori-badge{content="md" radius="md"}

:ori-badge{content="lg" radius="lg"}

:ori-badge{content="rounded" radius="rounded"}

#vue
```vue
<OriBadge content="zero" radius="zero" />
<OriBadge content="rounded" radius="rounded" />
```

#html
```html
<span class="ori-badge ori-size-radius_zero">zero</span> <span class="ori-badge">rounded</span>
```
::

## Count & max

Pass a number to `content`. Set `max` to cap the display value — any number exceeding `max` renders
as `{max}+`.

::example
  :::ori-badge{:content='5'}
  :::

  :::ori-badge{:content='42'}
  :::

  :::ori-badge{:content='130' :max='99' color="danger"}
  :::

  :::ori-badge{:content='9' :max='9' color="success"}
  :::

#vue
```vue
<OriBadge :content="5" />
<OriBadge :content="42" />
<!-- 130 > 99 → renders "99+" -->
<OriBadge :content="130" :max="99" color="danger" />
```

#html
```html
<span class="ori-badge">5</span>
<!-- cap manually in your template when not using Vue -->
<span class="ori-badge ori-color_danger">99+</span>
```
::

## Dot

`dot` collapses the badge to a small filled circle. Content is hidden; it is always decorative
(`aria-hidden="true"`) unless you provide a `label`.

::example
  :::ori-badge{dot}
  :::

  :::ori-badge{dot color="danger"}
  :::

  :::ori-badge{dot color="success"}
  :::

  :::ori-badge{dot color="warn"}
  :::

#vue
```vue
<OriBadge dot />
<OriBadge dot color="danger" />
<OriBadge dot color="success" />
```

#html
```html
<!-- dot is always aria-hidden unless a label is provided -->
<span class="ori-badge ori-badge_dot ori-color_danger" aria-hidden="true"></span>
```
::

## Floating

The badge floats over **wrapped content** — `floating` needs the badge to wrap an anchor. In Vue, pass
the anchor into the **default slot** and add the `floating` prop (without a default slot `floating` has
nothing to position against and is ignored). In HTML, wrap the anchor in `ori-badge-anchor` and add
`ori-badge_floating` to the badge itself.

::example
:badge-demo

#vue
```vue
<!-- floating over a button -->
<OriBadge :content="3" floating color="danger">
    <button class="ori-button ori-variant_tonal ori-color_primary ori-size-radius_rounded">
        Inbox
    </button>
</OriBadge>

<!-- dot variant -->
<OriBadge dot floating color="danger">
    <button class="ori-button …">Notifications</button>
</OriBadge>
```

#html
```html
<!-- wrap anchor content in ori-badge-anchor, add ori-badge_floating to the badge -->
<span class="ori-badge-anchor">
    <button class="ori-button ori-variant_tonal ori-color_primary ori-size-radius_rounded">Inbox</button>
    <span class="ori-badge ori-badge_floating ori-color_danger" aria-label="3 unread">3</span>
</span>
```
::

## Common patterns

A notification bell, an avatar with a status pip, and a tab bar with unread counts.

::example
:badge-demo

:ori-badge{color="info" content="New" variant="tonal"}

#vue
```vue
<!-- notification bell -->
<OriBadge
    :content="notifications"
    :max="99"
    floating
    color="danger"
    aria-label="`${notifications} unread notifications`"
>
    <OriButton icon="M12 22c1.1 0 2-.9 2-2h-4a2 2 0 0 0 2 2zm6-6V11c0-3.07-1.64-5.64-4.5-6.32V4c0-.83-.67-1.5-1.5-1.5S10.5 3.17 10.5 4v.68C7.63 5.36 6 7.92 6 11v5l-2 2v1h16v-1l-2-2z" aria-label="Notifications" />
</OriBadge>

<!-- status dot on an avatar -->
<OriBadge dot floating color="success" label="Online">
    <OriAvatar text="Ada Lovelace" />
</OriBadge>

<!-- tab with unread count -->
<span style="display: inline-flex; align-items: center; gap: 0.5rem">
    Messages
    <OriBadge :content="5" variant="tonal" color="primary" />
</span>
```

#html
```html
<!-- notification bell -->
<span class="ori-badge-anchor">
    <button class="ori-button …" aria-label="Notifications"><!-- bell icon --></button>
    <span class="ori-badge ori-badge_floating ori-color_danger" aria-label="12 unread notifications">12</span>
</span>

<!-- status dot on avatar -->
<span class="ori-badge-anchor">
    <div class="ori-avatar …"><!-- avatar --></div>
    <span class="ori-badge ori-badge_dot ori-badge_floating ori-color_success" aria-label="Online"></span>
</span>

<!-- inline tab counter -->
<span style="display: inline-flex; align-items: center; gap: 0.5rem">
    Messages
    <span class="ori-badge ori-variant_tonal">5</span>
</span>
```
::

## Accessibility

The accessibility contract holds across every layer — the standalone classes and the Vue component
render the same attributes.

- A badge with visible text content (`content`) conveys that text to assistive technology directly.
- A pure dot badge — or an empty badge with no `label` — is marked `aria-hidden="true"` because it
  carries no information for screen readers.
- Supply a `label` whenever the badge conveys meaning that a sighted user can read but a screen
  reader cannot (e.g. a dot meaning "online", or a floating count with no textual fallback nearby).
- A floating count that visually annotates an already-labeled control (e.g. "Inbox (3 unread)")
  should carry `aria-label` on the badge element or be hidden with `aria-hidden="true"` if the
  parent label already includes the count.
- The badge is a `<span>` — it has no interactive role and no keyboard contract of its own. When a
  badge and its anchor together form an interactive control, apply focus management and ARIA to the
  outer interactive element.

| Attribute            | Condition                                             | Value       |
| -------------------- | ----------------------------------------------------- | ----------- |
| `aria-hidden="true"` | `dot` with no `label`, or empty badge with no `label` | `"true"`    |
| `aria-label`         | `label` prop is set                                   | label value |

## Framework API

The props, events, and slots of the **Vue** component. The standalone CSS layer has no component
API — its surface is the [classes](https://oriui.vercel.app/#classes) above. (Svelte bindings are planned.)

### Props

| Prop       | Type              | Default     | Description                                                                                                       |
| ---------- | ----------------- | ----------- | ----------------------------------------------------------------------------------------------------------------- |
| `color`    | `ThemeColor`      | `'primary'` | Semantic color role: `primary` · `secondary` · `success` · `warn` · `danger` · `info` · `surface` · `background`. |
| `content`  | `string | number` | —           | Text or number to display. Numbers are capped to `max+` when `max` is set.                                        |
| `dot`      | `boolean`         | `false`     | Collapses the badge to a small filled circle; content is hidden.                                                  |
| `floating` | `boolean`         | `false`     | Positions the badge in the top-end corner of the default-slot anchor (requires a default slot child).             |
| `label`    | `string`          | —           | Accessible name (`aria-label`). Required for dot badges or empty badges that convey meaning to sighted users.     |
| `max`      | `number`          | —           | When `content` is a number and exceeds `max`, the display value is capped to `{max}+`.                            |
| `radius`   | `RadiusSize`      | `'rounded'` | Corner radius: `zero` · `xs` · `sm` · `md` · `lg` · `xl` · `rounded`.                                             |
| `variant`  | `Variant`         | `'fill'`    | Visual style: `fill` · `tonal` · `outline` · `text` · `plain`.                                                    |

### Events & attributes

OriBadge declares **no custom events**. It sets `inheritAttrs: false` and applies `v-bind="$attrs"`
directly to the inner `.ori-badge` element — so `id`, `class`, `data-*`, and event listeners always
land on the badge element regardless of whether a default slot (the anchor wrapper) is present.

### Slots

| Slot      | Description                                                                                                                                                                                          |
| --------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `default` | The element the badge floats over. When provided, the component wraps both the slot content and the badge in an `ori-badge-anchor` span. When absent, the badge renders standalone.                  |
| `content` | Custom badge content, replacing the capped `content` value (`{max}+`) that renders by default. Only renders when not a `dot`. A badge that uses this slot is kept in the a11y tree (not decorative). |


# Button

A styled, accessible button. Dynamic state is expressed through real attributes — `disabled` becomes
a true `disabled` (or `aria-disabled` for link buttons), `loading` sets `aria-busy`, and it ships a
visible `:focus-visible` ring.

The examples are organised by **layer**: the [class reference](https://oriui.vercel.app/#classes&#x29; is the standalone
&#x2A;*`@oriui/css`** layer, and the [Framework API](https://oriui.vercel.app/#framework-api&#x29; is the &#x2A;*`@oriui/vue`** component. Every
example is live — flip its code between **HTML** (the standalone classes, also your htmx / Astro / Svelte /
plain-HTML usage), **Vue**; HTML is the default.

## Classes

A button is a block class plus single-class token utilities — one class repoints one token, no base
class needed. The Vue props in [Framework API](https://oriui.vercel.app/#framework-api) map 1:1 to these.

::class-table
---
rows:
  - class: ori-button
    type: Block
    description: Required base class.
  - class: ori-variant_*
    type: Style
    description: <b>fill</b> · tonal · outline · text · plain
  - class: ori-color_*
    type: Color
    description: <b>primary</b> · secondary · success · warn · danger · info · surface
  - class: ori-button_* (size)
    type: Size
    description: xs · sm · <b>md</b> · lg · xl · xxl
  - class: ori-font-size_*
    type: Font
    description: xs · sm · <b>md</b> · lg · xl · xxl (scales the label)
  - class: ori-size-radius_*
    type: Radius
    description: zero · xs · sm · md · lg · xl · <b>rounded</b>
  - class: ori-button_fluid · ori-button_icon
    type: Layout
    description: full-width · icon-only
  - class: ori-button__icon · ori-button__text
    type: Part
    description: icon / label elements
  - class: disabled · aria-busy · data-active
    type: State
    description: real attributes, not classes
---
::

The non-fill variants (`tonal` / `outline` / `text` / `plain`) paint the label with the AA-safe
`--ori-color-text` tone rather than the raw role; `fill` keeps `--ori-color-on` for its solid
background — see [Design tokens](https://oriui.vercel.app/guides/design-tokens#text-the-on-surface-foreground).

## Variants

Five visual styles, all driven by the `ori-variant_*` single-class token.

::example
:ori-button{text="Fill" variant="fill"}

:ori-button{text="Tonal" variant="tonal"}

:ori-button{text="Outline" variant="outline"}

:ori-button{text="Text" variant="text"}

:ori-button{text="Plain" variant="plain"}

#vue
```vue
<OriButton text="Fill" variant="fill" />
<OriButton text="Tonal" variant="tonal" />
<OriButton text="Outline" variant="outline" />
<OriButton text="Text" variant="text" />
<OriButton text="Plain" variant="plain" />
```

#html
```html
<button class="ori-button ori-variant_fill ori-color_primary">Fill</button>
<!-- swap the variant: ori-variant_fill → _tonal / _outline / _text / _plain -->
<button class="ori-button ori-variant_outline ori-color_primary">Outline</button>
```
::

## Colors

Every semantic role. `surface` / `background` are also available for neutral buttons.

::example
:ori-button{color="primary" text="primary"}

:ori-button{color="secondary" text="secondary"}

:ori-button{color="success" text="success"}

:ori-button{color="warn" text="warn"}

:ori-button{color="danger" text="danger"}

:ori-button{color="info" text="info"}

#vue
```vue
<OriButton text="primary" color="primary" />
<OriButton text="danger" color="danger" />
<OriButton text="info" color="info" />
```

#html
```html
<button class="ori-button ori-variant_fill ori-color_danger">danger</button>
```
::

Variant × color compose freely — e.g. a tonal danger button:

::example
:ori-button{color="danger" text="Delete" variant="tonal"}

:ori-button{color="success" text="Confirm" variant="outline"}

:ori-button{color="info" text="Note" variant="text"}

#vue
```vue
<OriButton text="Delete" variant="tonal" color="danger" />
<OriButton text="Confirm" variant="outline" color="success" />
```

#html
```html
<button class="ori-button ori-variant_tonal ori-color_danger">Delete</button>
```
::

## Sizes

`xs` → `xxl`. The size sugar `ori-button_*` drives the height; `ori-font-size_*` scales the label.

::example
:ori-button{size="xs" text="xs"}

:ori-button{size="sm" text="sm"}

:ori-button{size="md" text="md"}

:ori-button{size="lg" text="lg"}

:ori-button{size="xl" text="xl"}

#vue
```vue
<OriButton text="sm" size="sm" />
<OriButton text="xl" size="xl" />
```

#html
```html
<button class="ori-button ori-button_sm ori-font-size_sm">sm</button>
<button class="ori-button ori-button_xl ori-font-size_xl">xl</button>
```
::

## Radius

From `zero` to the default `rounded` (pill).

::example
:ori-button{radius="zero" text="zero"}

:ori-button{radius="sm" text="sm"}

:ori-button{radius="md" text="md"}

:ori-button{radius="lg" text="lg"}

:ori-button{radius="rounded" text="rounded"}

#vue
```vue
<OriButton text="zero" radius="zero" />
<OriButton text="rounded" radius="rounded" />
```

#html
```html
<button class="ori-button ori-size-radius_zero">zero</button>
```
::

## With icon

Pass an SVG path to `icon`. `iconPosition` places it. For an icon-only square, pass `icon` **without**`text` (give it an `aria-label`) — icon mode is triggered by the explicit `icon` prop, so a slot-only or
text button is never forced into a square.

::example
:ori-button{icon="M11 13H5v-2h6V5h2v6h6v2h-6v6h-2z" text="Add"}

:ori-button{icon="M12 4l-1.41 1.41L16.17 11H4v2h12.17l-5.58 5.59L12 20l8-8z" icon-position="right" text="Next"}

:ori-button{ariaLabel="Add" icon="M11 13H5v-2h6V5h2v6h6v2h-6v6h-2z" variant="tonal"}

#vue
```vue
<OriButton text="Add" icon="M11 13H5v-2h6V5h2v6h6v2h-6v6h-2z" />
<OriButton text="Next" icon="M12 4l-1.41…" iconPosition="right" />
<!-- icon-only square: pass `icon` with no `text`, add an accessible name -->
<OriButton icon="M11 13H5v-2h6V5h2v6h6v2h-6v6h-2z" aria-label="Add" variant="tonal" />
```

#html
```html
<button class="ori-button ori-button_icon ori-variant_tonal" aria-label="Add">
    <i class="ori-icon" aria-hidden="true"
        ><svg viewBox="0 0 24 24"><path d="M11 13H5v-2h6V5h2v6h6v2h-6v6h-2z" /></svg
    ></i>
</button>
```
::

## Loading

`loading` swaps the icon for a spinner, sets `aria-busy="true"`, and blocks interaction.

::example
  :::ori-button{loading text="Saving"}
  :::

  :::ori-button{loading text="Saving" variant="tonal"}
  :::

  :::ori-button
  ---
  loading: true
  ariaLabel: Saving
  icon: M11 13H5v-2h6V5h2v6h6v2h-6v6h-2z
  ---
  :::

#vue
```vue
<OriButton text="Saving" loading />
<OriButton icon="…" aria-label="Saving" loading />
```

#html
```html
<button class="ori-button" aria-busy="true">
    <span class="ori-spinner ori-spinner_inline" role="status" aria-hidden="true"></span>
    <span class="ori-button__text">Saving</span>
</button>
```
::

## States

`active` paints the pressed look (`data-active`); `disabled` is the real attribute.

::example
  :::ori-button{active text="Active"}
  :::

  :::ori-button{disabled text="Disabled"}
  :::

  :::ori-button{disabled text="Disabled outline" variant="outline"}
  :::

#vue
```vue
<OriButton text="Active" active />
<OriButton text="Disabled" disabled />
```

#html
```html
<button class="ori-button" data-active>Active</button> <button class="ori-button" disabled>Disabled</button>
```
::

## Block

`fluid` stretches the button to the full width of its container.

::example
  :::ori-button{fluid text="Full width"}
  :::

#vue
```vue
<OriButton text="Full width" fluid />
```

#html
```html
<button class="ori-button ori-button_fluid">Full width</button>
```
::

## Common patterns

A confirm / cancel pair and an icon toolbar — the everyday compositions.

::example
:ori-button{text="Cancel" variant="text"}

:ori-button{text="Save changes" variant="fill"}

#vue
```vue
<div style="display: flex; gap: 0.5rem">
    <OriButton text="Cancel" variant="text" />
    <OriButton text="Save changes" variant="fill" />
</div>
```

#html
```html
<div style="display: flex; gap: 0.5rem">
    <button class="ori-button ori-variant_text">Cancel</button>
    <button class="ori-button ori-variant_fill">Save changes</button>
</div>
```
::

## Accessibility

The accessibility contract holds across every layer — the standalone classes and the Vue component
render the same attributes and keyboard behaviour.

- Renders a real `<button type="button">` by default; `as="a"` (or a router link) switches the tag
  and uses `aria-disabled` + `tabindex="-1"` instead of the boolean `disabled`.
- `loading` sets `aria-busy="true"`; the spinner is `aria-hidden`. An icon-only button needs an
  `aria-label`.
- Visible `:focus-visible` outline; state lives in attributes, not classes.

| Key     | Action                              |
| ------- | ----------------------------------- |
| `Enter` | Activates the button.               |
| `Space` | Activates the button (native only). |

## Framework API

The props, events, slots, and polymorphism of the **Vue** component. The standalone CSS layer has no
component API — its surface is the [classes](https://oriui.vercel.app/#classes) above. (Svelte bindings are planned.)

### Props

| Prop           | Type                                              | Default     | Description                                                                                                    |
| -------------- | ------------------------------------------------- | ----------- | -------------------------------------------------------------------------------------------------------------- |
| `text`         | `string`                                          | —           | Label. A text (or slotted) button is a normal button, never an icon square.                                    |
| `variant`      | `'fill' | 'tonal' | 'outline' | 'text' | 'plain'` | `'fill'`    | Visual style.                                                                                                  |
| `color`        | `ThemeColor`                                      | `'primary'` | Semantic role: primary · secondary · success · warn · danger · info · surface.                                 |
| `size`         | `ActionSize`                                      | `'md'`      | Height + label scale (`xs`–`xxl`).                                                                             |
| `radius`       | `RadiusSize`                                      | `'rounded'` | Corner radius (`zero`–`rounded`).                                                                              |
| `icon`         | `string`                                          | —           | SVG path for an icon; hidden while `loading`. `icon` with no `text` → an icon-only square (`ori-button_icon`). |
| `iconPosition` | `'left' | 'right' | 'top' | 'bottom'`             | `'left'`    | Icon placement around the label.                                                                               |
| `loading`      | `boolean`                                         | `false`     | Shows a spinner, sets `aria-busy`, and blocks interaction.                                                     |
| `disabled`     | `boolean`                                         | `false`     | Real `disabled` (button) or `aria-disabled` + `tabindex="-1"` (other tags).                                    |
| `active`       | `boolean`                                         | `false`     | Pressed look via `data-active`.                                                                                |
| `fluid`        | `boolean`                                         | `false`     | Full-width (block) button.                                                                                     |
| `as`           | `string | Component`                              | `'button'`  | Element or component to render (e.g. `'a'`, a router link).                                                    |

### Events & attributes

OriButton declares **no custom events**. It doesn't set `inheritAttrs: false`, so native listeners
(`@click`, `@focus`, …) and attributes (`type`, `aria-label`, `name`, `form`, …) fall through to the
rendered element — the tag given by `as`.

### Slots

| Slot      | Description                                                                                      |
| --------- | ------------------------------------------------------------------------------------------------ |
| `default` | Replaces the built-in content (icon + text). Supply your own markup; you own its layout/spacing. |

### Polymorphic (`as`)

Render any tag or component. As a non-`<button>`, `disabled` becomes `aria-disabled` + `tabindex="-1"`
instead of the boolean attribute.

::example
  :::ori-button
  ---
  as: a
  href: https://oriui.vercel.app/#button
  text: Link button
  variant: outline
  ---
  :::

#vue
```vue
<!-- a real link… -->
<OriButton as="a" href="/docs" text="Link button" variant="outline" />
<!-- …or a router link -->
<OriButton :as="RouterLink" to="/docs" text="Go to docs" />
```

#html
```html
<a href="/docs" class="ori-button ori-variant_outline">Link button</a>
```
::


# Card

A surface container for grouping related content — a header (prepend slot · title · subtitle ·
append slot), a body, and optional action rows. It is the most *composed* styled component, yet the
standalone markup is just nested `.ori-card__*` elements, so it works without Vue.

The examples are organised by **layer**: the [class reference](https://oriui.vercel.app/#classes&#x29; is the standalone
&#x2A;*`@oriui/css`** layer, and the [Framework API](https://oriui.vercel.app/#framework-api&#x29; is the &#x2A;*`@oriui/vue`** component. Every
example is live — flip its code between **HTML** (the standalone classes, also your htmx / Astro / Svelte /
plain-HTML usage), **Vue**; HTML is the default.

## Classes

A card is a block class plus single-class token utilities — one class repoints one token, no base
class needed. The Vue props in [Framework API](https://oriui.vercel.app/#framework-api) map 1:1 to these.

::class-table
---
rows:
  - class: ori-card
    type: Block
    description: Required base class. Defaults bake in fill variant, surface color,
      and lg radius — a bare ori-card is valid.
  - class: ori-variant_*
    type: Style
    description: <b>fill</b> · tonal · outline · text · plain
  - class: ori-color_*
    type: Color
    description: primary · secondary · success · warn · danger · info ·
      <b>surface</b> · background
  - class: ori-size-radius_*
    type: Radius
    description: zero · xs · sm · md · <b>lg</b> · xl · rounded
  - class: ori-card_fluid
    type: Layout
    description: full-width card
  - class: ori-card_row
    type: Layout
    description: horizontal layout — header and body side by side
  - class: ori-card__header · ori-card__header-prepend · ori-card__headline ·
      ori-card__title · ori-card__subtitle · ori-card__header-append ·
      ori-card__body · ori-card__actions
    type: Part
    description: structural BEM elements — header row · leading area · headline
      wrapper · title · subtitle · trailing area · body · action row
  - class: ori-card__actions_reverse
    type: Layout
    description: reverses the flex direction of an action row
  - class: aria-disabled · aria-busy
    type: State
    description: real attributes, not classes (disabled / loading props)
---
::

## Anatomy

The card's slot structure from top to bottom. Each named slot falls back to a corresponding prop, so
simple use stays one-liner and complex layouts plug in via slots.

```text
ori-card
  └── [slot: actions-prepend]   ← prepended action row (order flipped by reversePrependedActions)
  └── ori-card__header
        └── ori-card__header-prepend  ← [slot: header-prepend] / prependAvatar / prependIcon
        └── ori-card__headline
              └── ori-card__title     ← [slot: title] / title prop
              └── ori-card__subtitle  ← [slot: subtitle] / subtitle prop
        └── ori-card__header-append   ← [slot: header-append] / appendAvatar / appendIcon
  └── ori-card__body            ← [slot: body] / text prop
  └── [slot: actions-append]    ← appended action row (order flipped by reverseAppendedActions)
```

## Variants

Five visual styles, all driven by the `ori-variant_*` utilities. The default is `fill` on `surface`.

::example
  :::ori-card
  ---
  color: surface
  text: Default fill on surface.
  title: Fill
  variant: fill
  ---
  :::

  :::ori-card
  ---
  color: surface
  text: Soft tonal wash.
  title: Tonal
  variant: tonal
  ---
  :::

  :::ori-card
  ---
  color: surface
  text: Bordered, transparent.
  title: Outline
  variant: outline
  ---
  :::

  :::ori-card
  ---
  color: surface
  text: No border, no background.
  title: Text
  variant: text
  ---
  :::

  :::ori-card
  ---
  color: surface
  text: Fully unstyled variant.
  title: Plain
  variant: plain
  ---
  :::

#vue
```vue
<OriCard variant="fill" title="Fill" text="Default fill on surface." />
<OriCard variant="tonal" title="Tonal" text="Soft tonal wash." />
<OriCard variant="outline" title="Outline" text="Bordered, transparent." />
<OriCard variant="text" title="Text" text="No border, no background." />
<OriCard variant="plain" title="Plain" text="Fully unstyled variant." />
```

#html
```html
<div class="ori-card ori-size-radius_lg ori-variant_fill ori-color_surface">
    <div class="ori-card__header">
        <div class="ori-card__headline"><div class="ori-card__title">Fill</div></div>
    </div>
    <div class="ori-card__body">Default fill on surface.</div>
</div>
<!-- swap the variant: ori-variant_fill → ori-variant_tonal / ori-variant_outline / ori-variant_text / ori-variant_plain -->
```
::

## Colors

Every semantic role composes with every variant. `surface` is the default — neutral elevation.

::example
:ori-card{color="primary" title="primary" variant="tonal"}

:ori-card{color="secondary" title="secondary" variant="tonal"}

:ori-card{color="success" title="success" variant="tonal"}

:ori-card{color="warn" title="warn" variant="tonal"}

:ori-card{color="danger" title="danger" variant="tonal"}

:ori-card{color="info" title="info" variant="tonal"}

:ori-card{color="surface" title="surface (default)" variant="tonal"}

:ori-card{color="background" title="background" variant="tonal"}

#vue
```vue
<OriCard variant="tonal" color="primary" title="primary" />
<OriCard variant="tonal" color="secondary" title="secondary" />
<OriCard variant="tonal" color="success" title="success" />
<OriCard variant="tonal" color="warn" title="warn" />
<OriCard variant="tonal" color="danger" title="danger" />
<OriCard variant="tonal" color="info" title="info" />
<OriCard variant="tonal" color="surface" title="surface (default)" />
<OriCard variant="tonal" color="background" title="background" />
```

#html
```html
<div class="ori-card ori-size-radius_lg ori-variant_tonal ori-color_danger">
    <div class="ori-card__header">
        <div class="ori-card__headline"><div class="ori-card__title">danger</div></div>
    </div>
</div>
<!-- swap the color: ori-color_danger → ori-color_primary / ori-color_secondary / ori-color_success / ori-color_warn / ori-color_info / ori-color_surface / ori-color_background -->
```
::

Variant × color compose freely — e.g. a filled danger card or an outlined info card:

::example
  :::ori-card
  ---
  color: danger
  text: This action is irreversible.
  title: Delete zone
  variant: fill
  ---
  :::

  :::ori-card
  ---
  color: info
  text: Extra context lives here.
  title: Note
  variant: outline
  ---
  :::

  :::ori-card
  ---
  color: success
  text: Everything looks good.
  title: All clear
  variant: tonal
  ---
  :::

#vue
```vue
<OriCard variant="fill" color="danger" title="Delete zone" text="This action is irreversible." />
<OriCard variant="outline" color="info" title="Note" text="Extra context lives here." />
<OriCard variant="tonal" color="success" title="All clear" text="Everything looks good." />
```

#html
```html
<div class="ori-card ori-size-radius_lg ori-variant_fill ori-color_danger">
    <div class="ori-card__header">
        <div class="ori-card__headline"><div class="ori-card__title">Delete zone</div></div>
    </div>
    <div class="ori-card__body">This action is irreversible.</div>
</div>
```
::

## Radius

From `zero` (sharp) to `rounded` (pill-like). The default is `lg`.

::example
:ori-card{radius="zero" text="No corner radius." title="zero"}

:ori-card{radius="sm" text="Subtle rounding." title="sm"}

:ori-card{radius="lg" text="Default rounding." title="lg (default)"}

:ori-card{radius="xl" text="Generous rounding." title="xl"}

:ori-card{radius="rounded" text="Maximum radius." title="rounded"}

#vue
```vue
<OriCard radius="zero" title="zero" text="No corner radius." />
<OriCard radius="lg" title="lg (default)" text="Default rounding." />
<OriCard radius="rounded" title="rounded" text="Maximum radius." />
```

#html
```html
<div class="ori-card ori-size-radius_zero ori-variant_fill ori-color_surface">
    <div class="ori-card__header">
        <div class="ori-card__headline"><div class="ori-card__title">zero</div></div>
    </div>
    <div class="ori-card__body">No corner radius.</div>
</div>
```
::

## With header media

`prependIcon` / `prependAvatar` populate the leading slot; `appendIcon` / `appendAvatar` populate
the trailing slot. Pass an SVG path to `prependIcon` or a URL to `prependAvatar`.

::example
:ori-card{prepend-icon="M12 2C6.48 2 2 6.48 2 12s4.48 10 10 10 10-4.48 10-10S17.52 2 12 2zm-2 14.5v-9l6 4.5-6 4.5z" subtitle="Leading icon via prependIcon" title="With icon"}

:ori-card{append-icon="M12 8c1.1 0 2-.9 2-2s-.9-2-2-2-2 .9-2 2 .9 2 2 2zm0 2c-1.1 0-2 .9-2 2s.9 2 2 2 2-.9 2-2-.9-2-2-2zm0 6c-1.1 0-2 .9-2 2s.9 2 2 2 2-.9 2-2-.9-2-2-2z" subtitle="Trailing icon via appendIcon" title="Trailing icon"}

#vue
```vue
<OriCard title="With icon" subtitle="Leading icon via prependIcon" prependIcon="M12 2C6.48 2 2 6.48 2 12s4.48 10 …" />
<OriCard title="Trailing icon" subtitle="Trailing icon via appendIcon" appendIcon="M12 8c1.1 0 2-.9 2-2 …" />
```

#html
```html
<div class="ori-card ori-size-radius_lg ori-variant_fill ori-color_surface">
    <div class="ori-card__header">
        <div class="ori-card__header-prepend">
            <i class="ori-icon ori-icon_sm" aria-hidden="true">
                <svg viewBox="0 0 24 24"><path d="M12 2C6.48 2 2 6.48 …" /></svg>
            </i>
        </div>
        <div class="ori-card__headline">
            <div class="ori-card__title">With icon</div>
            <div class="ori-card__subtitle">Leading icon via prependIcon</div>
        </div>
        <div class="ori-card__header-append"></div>
    </div>
</div>
```
::

## Row layout

`row` lays the header and body out horizontally — handy for compact list items or media objects.

::example
  :::ori-card
  ---
  row: true
  prepend-icon: M22,13H13V22H11V13H2V11H11V2H13V11H22V13Z
  subtitle: Header and body side by side
  title: Row layout
  ---
  :::

#vue
```vue
<OriCard
    :row="true"
    prependIcon="M22,13H13V22H11V13H2V11H11V2H13V11H22V13Z"
    title="Row layout"
    subtitle="Header and body side by side"
/>
```

#html
```html
<div class="ori-card ori-card_row ori-size-radius_lg ori-variant_fill ori-color_surface">
    <div class="ori-card__header">
        <div class="ori-card__header-prepend">
            <i class="ori-icon ori-icon_sm" aria-hidden="true">
                <svg viewBox="0 0 24 24"><path d="M22,13H13V22H11V13H2V11H11V2H13V11H22V13Z" /></svg>
            </i>
        </div>
        <div class="ori-card__headline">
            <div class="ori-card__title">Row layout</div>
            <div class="ori-card__subtitle">Header and body side by side</div>
        </div>
    </div>
</div>
```
::

## Block (fluid)

`fluid` stretches the card to the full width of its container.

::example
  :::ori-card{fluid text="This card fills its container." title="Full width"}
  :::

#vue
```vue
<OriCard :fluid="true" title="Full width" text="This card fills its container." />
```

#html
```html
<div class="ori-card ori-card_fluid ori-size-radius_lg ori-variant_fill ori-color_surface">
    <div class="ori-card__header">
        <div class="ori-card__headline"><div class="ori-card__title">Full width</div></div>
    </div>
    <div class="ori-card__body">This card fills its container.</div>
</div>
```
::

## States

`disabled` and `loading` are expressed as real attributes — `aria-disabled` and `aria-busy` — not
classes, matching the rest of the library.

::example
  :::ori-card
  ---
  disabled: true
  text: aria-disabled — dimmed, non-interactive.
  title: Disabled
  ---
  :::

  :::ori-card{loading text="aria-busy while content is fetched." title="Loading"}
  :::

#vue
```vue
<OriCard :disabled="true" title="Disabled" text="aria-disabled — dimmed, non-interactive." />
<OriCard :loading="true" title="Loading" text="aria-busy while content is fetched." />
```

#html
```html
<div class="ori-card ori-size-radius_lg ori-variant_fill ori-color_surface" aria-disabled="true">
    <div class="ori-card__header">
        <div class="ori-card__headline"><div class="ori-card__title">Disabled</div></div>
    </div>
    <div class="ori-card__body">aria-disabled — dimmed, non-interactive.</div>
</div>

<div class="ori-card ori-size-radius_lg ori-variant_fill ori-color_surface" aria-busy="true">
    <div class="ori-card__header">
        <div class="ori-card__headline"><div class="ori-card__title">Loading</div></div>
    </div>
    <div class="ori-card__body">aria-busy while content is fetched.</div>
</div>
```
::

## Common patterns

A profile card and a notification card with an action row — everyday compositions using slots.

::example
  :::ori-card
  ---
  prepend-icon: M12 12c2.21 0 4-1.79 4-4s-1.79-4-4-4-4 1.79-4 4 1.79 4 4 4zm0
    2c-2.67 0-8 1.34-8 4v2h16v-2c0-2.66-5.33-4-8-4z
  subtitle: Product designer
  text: Leading product design at oriUI — focused on accessible, expressive systems.
  title: Jane Smith
  ---
  :::

#vue
```vue
<!-- Profile card -->
<OriCard
    :prepend-icon="personPath"
    title="Jane Smith"
    subtitle="Product designer"
    text="Leading product design at oriUI — focused on accessible, expressive systems."
/>
```

#html
```html
<div class="ori-card ori-size-radius_lg ori-variant_fill ori-color_surface">
    <div class="ori-card__header">
        <div class="ori-card__header-prepend">
            <i class="ori-icon ori-icon_sm" aria-hidden="true">
                <svg viewBox="0 0 24 24"><path d="M12 12c2.21 0 4-1.79 4-4 …" /></svg>
            </i>
        </div>
        <div class="ori-card__headline">
            <div class="ori-card__title">Jane Smith</div>
            <div class="ori-card__subtitle">Product designer</div>
        </div>
    </div>
    <div class="ori-card__body">Leading product design at oriUI — focused on accessible, expressive systems.</div>
</div>
```
::

Notification card with an `actions-append` row. Use `:reverse-appended-actions="true"` to flip
the button order (e.g. destructive action on the right).

::example
#vue
```vue
<!-- Notification card with action row -->
<OriCard
    variant="outline"
    color="warn"
    title="Delete account?"
    text="This will permanently remove your data. This action cannot be undone."
>
    <template #actions-append>
        <OriButton variant="text">Cancel</OriButton>
        <OriButton variant="fill" color="danger">Delete</OriButton>
    </template>
</OriCard>

<!-- Reversed order (confirm on right) -->
<OriCard
    variant="fill"
    color="surface"
    title="Save changes?"
    text="You have unsaved edits. Would you like to save before leaving?"
    :reverse-appended-actions="true"
>
    <template #actions-append>
        <OriButton variant="text">Discard</OriButton>
        <OriButton variant="tonal" color="primary">Save</OriButton>
    </template>
</OriCard>
```

#html
```html
<!-- Notification card with action row -->
<div class="ori-card ori-size-radius_lg ori-variant_outline ori-color_warn">
    <div class="ori-card__header">
        <div class="ori-card__headline">
            <div class="ori-card__title">Delete account?</div>
        </div>
    </div>
    <div class="ori-card__body">This will permanently remove your data. This action cannot be undone.</div>
    <div class="ori-card__actions">
        <button class="ori-button ori-variant_text">Cancel</button>
        <button class="ori-button ori-variant_fill ori-color_danger">Delete</button>
    </div>
</div>

<!-- Reversed order: add ori-card__actions_reverse to flip flex direction -->
<div class="ori-card ori-size-radius_lg ori-variant_fill ori-color_surface">
    <div class="ori-card__header">
        <div class="ori-card__headline">
            <div class="ori-card__title">Save changes?</div>
        </div>
    </div>
    <div class="ori-card__body">You have unsaved edits. Would you like to save before leaving?</div>
    <div class="ori-card__actions ori-card__actions_reverse">
        <button class="ori-button ori-variant_text">Discard</button>
        <button class="ori-button ori-variant_tonal ori-color_primary">Save</button>
    </div>
</div>
```
::

## Accessibility

The accessibility contract holds across every layer — the standalone classes and the Vue component
render the same attributes.

- `disabled` maps to `aria-disabled="true"` + `pointer-events: none` — the card is dimmed but
  remains in the DOM and in the tab order (suitable for progressive-disclosure UIs).
- `loading` maps to `aria-busy="true"` — assistive technology announces that the region is
  updating. Combine with a visible spinner inside the `body` slot when appropriate.
- Decorative icons (`prependIcon`, `appendIcon`) are rendered via `<OriIcon>` which sets
  `aria-hidden="true"` automatically.
- Card does not manage focus itself. If the card triggers a navigation or dialog, add the
  appropriate role (`role="button"`, `tabindex="0"`) and keyboard handler to the root element via
  attribute fall-through.
- The body uses the `on-surface` token paired with the card's surface color, keeping text contrast
  WCAG AA on every skin.

## Framework API

The props, events, and slots of the **Vue** component. The standalone CSS layer has no component
API — its surface is the [classes](https://oriui.vercel.app/#classes) above. (Svelte bindings are planned.)

### Props

| Prop                      | Type         | Default     | Description                                                                                 |
| ------------------------- | ------------ | ----------- | ------------------------------------------------------------------------------------------- |
| `appendAvatar`            | `string`     | —           | URL for an avatar in the trailing header slot.                                              |
| `appendIcon`              | `string`     | —           | SVG path for an icon in the trailing header slot.                                           |
| `color`                   | `ThemeColor` | `'surface'` | Semantic role: primary · secondary · success · warn · danger · info · surface · background. |
| `disabled`                | `boolean`    | —           | Sets `aria-disabled="true"` and `pointer-events: none`.                                     |
| `fluid`                   | `boolean`    | —           | Stretches the card to full container width (`ori-card_fluid`).                              |
| `image`                   | `string`     | —           | Reserved for a hero image URL (not yet rendered by the template).                           |
| `loading`                 | `boolean`    | —           | Sets `aria-busy="true"` and `pointer-events: none`.                                         |
| `prependAvatar`           | `string`     | —           | URL for an avatar in the leading header slot.                                               |
| `prependIcon`             | `string`     | —           | SVG path for an icon in the leading header slot.                                            |
| `radius`                  | `RadiusSize` | `'lg'`      | Corner radius: `zero` · `xs` · `sm` · `md` · `lg` · `xl` · `rounded`.                       |
| `reverseAppendedActions`  | `boolean`    | —           | Reverses the flex direction of the `actions-append` row.                                    |
| `reversePrependedActions` | `boolean`    | —           | Reverses the flex direction of the `actions-prepend` row.                                   |
| `row`                     | `boolean`    | —           | Horizontal layout — header and body side by side (`ori-card_row`).                          |
| `subtitle`                | `string`     | —           | Subtitle below the title; falls back to the `subtitle` slot.                                |
| `text`                    | `string`     | —           | Body text; falls back to the `body` slot.                                                   |
| `title`                   | `string`     | —           | Primary heading; falls back to the `title` slot.                                            |
| `variant`                 | `Variant`    | `'fill'`    | Visual style: `fill` · `tonal` · `outline` · `text` · `plain`.                              |

### Events & attributes

OriCard declares **no custom events** and does not set `inheritAttrs: false`, so native attributes
(`id`, `class`, `style`, `data-*`, `aria-*`, event listeners, etc.) fall through to the root `<div>`.

### Slots

| Slot              | Falls back to                   | Description                                                                       |
| ----------------- | ------------------------------- | --------------------------------------------------------------------------------- |
| `default`         | —                               | Replaces the entire built-in card structure. You own the full interior markup.    |
| `actions-prepend` | *(nothing — slot must be used)* | Action row rendered before the header. `reversePrependedActions` flips its order. |
| `header-prepend`  | `prependAvatar` / `prependIcon` | Leading area of the header row (avatar, icon, or custom media).                   |
| `title`           | `title` prop                    | Primary heading inside the headline.                                              |
| `subtitle`        | `subtitle` prop                 | Secondary line below the title.                                                   |
| `header-append`   | `appendAvatar` / `appendIcon`   | Trailing area of the header row (avatar, icon, or custom control).                |
| `body`            | `text` prop                     | Main content area below the header.                                               |
| `actions-append`  | *(nothing — slot must be used)* | Action row rendered after the body. `reverseAppendedActions` flips its order.     |


# Checkbox

A styled, accessible checkbox built on a &#x2A;*real `<input type="checkbox">`** — kept in the DOM
(visually hidden over a custom box) so keyboard, focus, and native form submission work for free.
The accent color and `:focus-visible` ring are driven by the `ori-color` token; `invalid` sets
`aria-invalid`; `disabled` is the native attribute.

The examples are organised by **layer**: the [class reference](https://oriui.vercel.app/#classes&#x29; is the standalone
&#x2A;*`@oriui/css`** layer, and the [Framework API](https://oriui.vercel.app/#framework-api&#x29; is the &#x2A;*`@oriui/vue`** component. Every
example is live — flip its code between **HTML** (the standalone classes, also your htmx / Astro / Svelte /
plain-HTML usage), **Vue**; HTML is the default.

## Classes

A checkbox is a block class on the `<label>` wrapper plus single-class token utilities — one class
repoints one token; no paired base class is needed. The Vue props in [Framework API](https://oriui.vercel.app/#framework-api)
map 1:1 to these.

::class-table
---
rows:
  - class: ori-checkbox
    type: Block
    description: Required base class — applied to the label wrapper.
  - class: ori-color_*
    type: Color
    description: primary · secondary · success · warn · danger · info · surface · background
  - class: ori-font-size_*
    type: Size
    description: xs · sm · md · lg · xl · xxl · text (box and label scale together
      off the font size)
  - class: ori-checkbox__input
    type: Part
    description: the visually-hidden native input type=checkbox
  - class: ori-checkbox__box
    type: Part
    description: the visible styled square; aria-hidden
  - class: ori-checkbox__label
    type: Part
    description: the text label rendered next to the box
  - class: ori-checkbox_disabled
    type: State
    description: added by the component when disabled; dims the wrapper
  - class: disabled · aria-invalid
    type: State
    description: real attributes on the input, not classes
---
::

## Colors

Every semantic color role. The accent fill and focus ring track `ori-color`.

::example
:ori-checkbox{color="primary" label="Primary"}

:ori-checkbox{color="secondary" label="Secondary"}

:ori-checkbox{color="success" label="Success"}

:ori-checkbox{color="warn" label="Warn"}

:ori-checkbox{color="danger" label="Danger"}

:ori-checkbox{color="info" label="Info"}

#html
```html
<label class="ori-checkbox ori-color_primary" for="c1">
    <input id="c1" type="checkbox" class="ori-checkbox__input" />
    <span class="ori-checkbox__box" aria-hidden="true"></span>
    <span class="ori-checkbox__label">Primary</span>
</label>
<!-- swap the color class: ori-color_primary → ori-color_success / ori-color_danger / ori-color_info / … -->
```

#vue
```vue
<OriCheckbox v-model="checked" label="Primary" color="primary" />
<OriCheckbox v-model="checked" label="Success" color="success" />
<OriCheckbox v-model="checked" label="Danger" color="danger" />
<OriCheckbox v-model="checked" label="Info" color="info" />
```
::

## Sizes

`xs` → `xxl`. The box and label scale together because `ori-font-size` is set on the wrapper and
the box dimensions use `em` units.

::example
:ori-checkbox{label="xs" size="xs"}

:ori-checkbox{label="sm" size="sm"}

:ori-checkbox{label="md" size="md"}

:ori-checkbox{label="lg" size="lg"}

:ori-checkbox{label="xl" size="xl"}

#html
```html
<!-- box and label scale together off ori-font-size_* -->
<label class="ori-checkbox ori-font-size_sm" for="sm1">
    <input id="sm1" type="checkbox" class="ori-checkbox__input" />
    <span class="ori-checkbox__box" aria-hidden="true"></span>
    <span class="ori-checkbox__label">sm</span>
</label>
<label class="ori-checkbox ori-font-size_xl" for="xl1">
    <input id="xl1" type="checkbox" class="ori-checkbox__input" />
    <span class="ori-checkbox__box" aria-hidden="true"></span>
    <span class="ori-checkbox__label">xl</span>
</label>
```

#vue
```vue
<OriCheckbox v-model="checked" label="sm" size="sm" />
<OriCheckbox v-model="checked" label="md" size="md" />
<OriCheckbox v-model="checked" label="xl" size="xl" />
```
::

## States

`disabled` is the native attribute; `invalid` sets `aria-invalid="true"` on the input.

::example
:ori-checkbox{label="Default"}

  :::ori-checkbox{disabled label="Disabled"}
  :::

  :::ori-checkbox{invalid label="Invalid"}
  :::

  :::ori-checkbox{required label="Required"}
  :::

#html
```html
<label class="ori-checkbox ori-checkbox_disabled" for="d1">
    <input id="d1" type="checkbox" class="ori-checkbox__input" disabled />
    <span class="ori-checkbox__box" aria-hidden="true"></span>
    <span class="ori-checkbox__label">Disabled</span>
</label>

<label class="ori-checkbox" for="inv1">
    <input id="inv1" type="checkbox" class="ori-checkbox__input" aria-invalid="true" />
    <span class="ori-checkbox__box" aria-hidden="true"></span>
    <span class="ori-checkbox__label">Invalid</span>
</label>
```

#vue
```vue
<!-- disabled — native attribute, dims wrapper via ori-checkbox_disabled -->
<OriCheckbox v-model="checked" label="Disabled" disabled />

<!-- invalid — sets aria-invalid="true" on the <input> -->
<OriCheckbox v-model="checked" label="Invalid" invalid />

<!-- required — sets required on the <input> -->
<OriCheckbox v-model="checked" label="Required" required />
```
::

## Color × size

Color and size compose freely.

::example
:ori-checkbox{color="danger" label="Danger lg" size="lg"}

:ori-checkbox{color="success" label="Success sm" size="sm"}

:ori-checkbox{color="info" label="Info xl" size="xl"}

#html
```html
<label class="ori-checkbox ori-color_danger ori-font-size_lg" for="dl1">
    <input id="dl1" type="checkbox" class="ori-checkbox__input" />
    <span class="ori-checkbox__box" aria-hidden="true"></span>
    <span class="ori-checkbox__label">Danger lg</span>
</label>
```

#vue
```vue
<OriCheckbox v-model="checked" label="Danger lg" color="danger" size="lg" />
<OriCheckbox v-model="checked" label="Success sm" color="success" size="sm" />
<OriCheckbox v-model="checked" label="Info xl" color="info" size="xl" />
```
::

## Checkbox group (array v-model)

Pass `value` on each checkbox and bind a shared array model. The native checkbox group mechanism
handles checked state — no extra logic needed.

::example
:ori-checkbox{label="Option A" value="a"}

:ori-checkbox{label="Option B" value="b"}

:ori-checkbox{label="Option C" value="c"}

#html
```html
<!-- array binding is Vue-specific; in plain HTML use a name attribute for the group -->
<label class="ori-checkbox ori-color_primary" for="a">
    <input id="a" type="checkbox" class="ori-checkbox__input" name="opts" value="a" />
    <span class="ori-checkbox__box" aria-hidden="true"></span>
    <span class="ori-checkbox__label">Option A</span>
</label>
<label class="ori-checkbox ori-color_primary" for="b">
    <input id="b" type="checkbox" class="ori-checkbox__input" name="opts" value="b" />
    <span class="ori-checkbox__box" aria-hidden="true"></span>
    <span class="ori-checkbox__label">Option B</span>
</label>
```

#vue
```vue
<script setup>
import { ref } from 'vue';
const selected = ref([]);
</script>

<template>
    <OriCheckbox v-model="selected" label="Option A" value="a" />
    <OriCheckbox v-model="selected" label="Option B" value="b" />
    <OriCheckbox v-model="selected" label="Option C" value="c" />
    <p>Selected: {{ selected }}</p>
</template>
```
::

## Common patterns

A real-world terms-and-conditions gate — `required` + `invalid` give the user feedback before
submit.

::example
  :::ori-checkbox{required label="I agree to the terms and conditions"}
  :::

#html
```html
<form>
    <label class="ori-checkbox ori-color_primary" for="terms">
        <input id="terms" type="checkbox" class="ori-checkbox__input" required />
        <span class="ori-checkbox__box" aria-hidden="true"></span>
        <span class="ori-checkbox__label">I agree to the terms and conditions</span>
    </label>
    <button type="submit">Continue</button>
</form>
```

#vue
```vue
<script setup>
import { ref } from 'vue';
const agreed = ref(false);
const submitted = ref(false);

function submit() {
    submitted.value = true;
    if (agreed.value) {
        // proceed
    }
}
</script>

<template>
    <form @submit.prevent="submit">
        <OriCheckbox
            v-model="agreed"
            label="I agree to the terms and conditions"
            required
            :invalid="submitted && !agreed"
        />
        <button type="submit">Continue</button>
    </form>
</template>
```
::

## Accessibility

The accessibility contract holds across every layer — the standalone classes and the Vue component
render the same attributes and keyboard behaviour.

- A real `<input type="checkbox">` drives all keyboard and form behavior; the visual `__box` is
  `aria-hidden="true"`.
- The wrapping `<label>` has its `for` attribute linked to the input `id` (auto-generated via
  `useId()`, overridable with the `id` prop) — clicking anywhere on the label or its text toggles
  the checkbox.
- Focus is visible via `:focus-visible` on the `__box` (2 px outline using `var(--ori-color)`); the
  ring never appears on mouse click.
- `disabled` is the real native attribute — the input is excluded from tab order and form submission
  automatically; the wrapper dims via `ori-checkbox_disabled`.
- `invalid` sets `aria-invalid="true"` on the input; pair it with an `aria-describedby` pointing at
  visible error text for a complete a11y contract.

| Key     | Action                                   |
| ------- | ---------------------------------------- |
| `Tab`   | Moves focus to / away from the checkbox. |
| `Space` | Toggles the checked state.               |

## Framework API

The props, events, and slots of the **Vue** component. The standalone CSS layer has no component
API — its surface is the [classes](https://oriui.vercel.app/#classes) above. (Svelte bindings are planned.)

### Props

| Prop       | Type              | Default     | Description                                                                                    |
| ---------- | ----------------- | ----------- | ---------------------------------------------------------------------------------------------- |
| `color`    | `ThemeColor`      | `'primary'` | Accent color for the checked fill and focus ring.                                              |
| `disabled` | `boolean`         | `false`     | Native `disabled` on the input; adds `ori-checkbox_disabled` (opacity) to the wrapper.         |
| `id`       | `string`          | —           | Overrides the auto-generated `useId()` for the input/label pair.                               |
| `invalid`  | `boolean`         | —           | Sets `aria-invalid="true"` on the input to signal a validation error.                          |
| `label`    | `string`          | —           | Visible text rendered inside `ori-checkbox__label`. Omit when providing your own slot content. |
| `required` | `boolean`         | —           | Sets the native `required` attribute on the input.                                             |
| `size`     | `ActionSize`      | `'md'`      | Font (and therefore box) scale: `xs` · `sm` · `md` · `lg` · `xl` · `xxl` · `text`.             |
| `value`    | `string | number` | —           | Bound to the array model for a native checkbox group; omit for a single boolean `v-model`.     |

### Events & attributes

OriCheckbox sets `inheritAttrs: false` and forwards `$attrs` directly to the `<input>` element
with `v-bind="$attrs"`. This means native listeners and HTML attributes bind to the real input, not
the outer `<label>`:

- `@change`, `@focus`, `@blur` — fire on the `<input>`
- `name`, `form`, `autocomplete`, `aria-describedby` — forwarded to the `<input>`

The two-way binding is handled by `defineModel` — use `v-model` for boolean (single) or array
(group) state; the component emits `update:modelValue` internally.

### Slots

| Slot      | Description                                                                                                                                                                                               |
| --------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `default` | Rich label content, rendered in place of the `label` prop (which is the fallback). It stays inside the native `<label>`, so the `for`/`id` association holds — use it for an inline link or other markup. |


# Color picker

An accessible color picker: a 2D **saturation × brightness** area, a **hue** slider, a **hex** field, and
optional **preset** swatches — an inline panel you compose into an [OriPopover](https://oriui.vercel.app/components/popover) for a
swatch-triggered flow. Behaviour lives in the framework-agnostic `useColorPicker` (a zero-dependency sRGB +
2D-area engine, no adapter or machine); the styled component reuses [OriSlider](https://oriui.vercel.app/components/slider) for the
hue channel and [OriInput](https://oriui.vercel.app/components/input) for the hex field. `v-model` carries a lowercase color
**string**; the internal working model is HSVA, so the hue survives when you drag into a corner and back.

The 2D area is built from &#x2A;*two visually-hidden native `<input type="range">`** — one per axis — so the
browser supplies `role="slider"`, focus, and value announcements; the area's keydown routes the arrows in
2D. See [Accessibility](https://oriui.vercel.app/#accessibility).

## Classes

The panel is a block wrapper plus BEM parts. The swatch and each preset read an inline `--ori-color`
(an arbitrary color, not a `ori-color_*` role token); the area reads an inline `--ori-hue`.

::class-table
---
rows:
  - class: ori-color-picker
    type: Block
    description: Required base class (wrapper). Fixed width via
      <code>--ori-color-picker-size</code> (15rem).
  - class: ori-color-picker__area
    type: Part
    description: The 2D saturation×brightness surface; reads the inline
      <code>--ori-hue</code> gradient base.
  - class: ori-color-picker__area-thumb
    type: Part
    description: The area indicator, positioned by inline <code>left</code> /
      <code>top</code>.
  - class: ori-color-picker__channel
    type: Part
    description: The two visually-hidden <code><input type=range></code>
      (saturation, brightness) — the a11y surface.
  - class: ori-color-picker__controls
    type: Part
    description: "Flex row: the preview swatch, the hue (and optional alpha) slider,
      and the optional eyedropper button."
  - class: ori-color-picker__sliders
    type: Part
    description: Column holding the hue slider and, when <code>alpha</code> is set,
      the alpha slider.
  - class: ori-color-picker__swatch
    type: Part
    description: Current-color preview; reads inline <code>--ori-color</code>
      (background) and <code>--ori-ink</code> (readable content color).
  - class: ori-color-picker__swatch_alpha
    type: Modifier
    description: On the swatch when <code>alpha</code> is set — adds the
      transparency checkerboard behind the (semi-transparent) current color.
  - class: ori-color-picker__hex
    type: Part
    description: The hex OriInput field.
  - class: ori-color-picker__eyedropper
    type: Part
    description: The eyedropper OriButton — shown only when <code>eyedropper</code>
      is set and the browser supports the EyeDropper API.
  - class: ori-color-picker__presets
    type: Part
    description: A single-select roving listbox of preset swatches.
  - class: ori-color-picker__preset
    type: Part
    description: A preset chip (button); reads inline <code>--ori-color</code>.
      Selected via <code>aria-selected</code>.
  - class: ori-slider_hue
    type: Modifier
    description: On the hue OriSlider — repaints the track as the full spectrum.
  - class: ori-slider_alpha
    type: Modifier
    description: On the alpha OriSlider — a transparent→color gradient over a
      checkerboard (transparency grid).
  - class: data-disabled
    type: State
    description: Set on the wrapper when <code>disabled</code>; dims the panel and
      blocks pointer events.
---
::

## Live demo

Drag inside the area, move the hue slider, type a hex, or pick a preset. Each control drives the same
color; `v-model` is the lowercase hex string.

::example
  :::ori-color-picker
  ---
  presets:
    - "#ef4444"
    - "#f59e0b"
    - "#10b981"
    - "#3b82f6"
    - "#8b5cf6"
    - "#111827"
  label: Brand color
  model-value: "#3366ff"
  ---
  :::

#vue
```vue
<script setup>
import { ref } from 'vue';
const color = ref('#3366ff');
const palette = ['#ef4444', '#f59e0b', '#10b981', '#3b82f6', '#8b5cf6', '#111827'];
</script>

<template>
    <OriColorPicker v-model="color" label="Brand color" :presets="palette" />
</template>
```
::

## In a popover (swatch trigger)

The panel is open-state-agnostic — drop it inside [OriPopover](https://oriui.vercel.app/components/popover) and reuse its
`#trigger`. This is the fill/stroke-color pattern for a toolbar.

```vue
<script setup>
import { ref } from 'vue';
const color = ref('#3366ff');
</script>

<template>
    <OriPopover>
        <template #trigger>
            <button
                type="button"
                aria-label="Stroke color"
                :style="{ background: color, width: '1.5rem', height: '1.5rem', borderRadius: '50%' }"
            />
        </template>
        <OriColorPicker v-model="color" label="Stroke color" />
    </OriPopover>
</template>
```

## Output format

`format` selects the emitted string; the default is `hex`. `rgb` and `hsl` emit function notation. All
output is **lowercase** (a common validator constraint).

::example
:ori-color-picker{label="hex (default)" model-value="#10b981"}

:ori-color-picker{format="rgb" label="rgb" model-value="rgb(16, 185, 129)"}

#vue
```vue
<OriColorPicker v-model="a" format="hex" />
<OriColorPicker v-model="b" format="rgb" />
<OriColorPicker v-model="c" format="hsl" />
```
::

## Alpha (transparency)

`alpha` adds an alpha channel — a checkerboard slider and a swatch that shows the transparency, plus
`#rrggbbaa` output (or `rgba()` / `hsla()` per `format`). The picker also parses 8-digit hex / `rgba()`
input, so `v-model` round-trips transparency.

::example
  :::ori-color-picker{alpha label="Fill color" model-value="#3366ff80"}
  :::

#vue
```vue
<!-- color round-trips as e.g. "#3366ff80" -->
<OriColorPicker v-model="color" :alpha="true" label="Fill color" />
```
::

## Eyedropper

`eyedropper` shows a pick-from-screen trigger built on the
[EyeDropper API](https://developer.mozilla.org/en-US/docs/Web/API/EyeDropper){rel="&#x22;nofollow&#x22;"}. It is **feature-detected** —
the trigger is hidden where the browser lacks it (currently Chromium-only), so it is never a dead button.
A picked color keeps the current alpha.

::example
  :::ori-color-picker{eyedropper label="Brand color" model-value="#3366ff"}
  :::

#vue
```vue
<OriColorPicker v-model="color" :eyedropper="true" label="Brand color" />
```
::

## Commit on release

Like [OriSlider](https://oriui.vercel.app/components/slider#commit-on-release), `update:modelValue` streams the color **live** on
every interaction tick (drag, arrow, hue move), while `change` fires **once** on release / keyboard
settle — so a whole drag records a single undo entry. Bind `v-model` for the live value and `@change` for
the commit.

```vue
<template>
    <!-- v-model tracks the live color; @change commits the settled value (one undo entry) -->
    <OriColorPicker v-model="color" label="Fill" @change="pushUndo" />
</template>
```

## Form submission

Set `name` to submit the picker in a native form: it renders a hidden input carrying the current color, so
the picker joins form submission like `<input type="color">`. Unlike a [combobox](https://oriui.vercel.app/components/combobox), a
color control has **no empty state** — it always submits a color (its current one, default black), even
before the user interacts. The submitted string uses the emitted [`format`](https://oriui.vercel.app/#output-format); a disabled
picker is excluded from submission (matching a native disabled control). Pass `form` to associate the
hidden input with a `<form>` by id when the picker sits outside it.

```vue
<template>
    <form>
        <OriColorPicker v-model="color" name="brand" label="Brand color" />
    </form>
</template>
```

## Accessibility

- The 2D area is &#x2A;*two visually-hidden native `<input type="range">`** (saturation, brightness), each a
  real `role="slider"` with its own `aria-label` and `aria-valuetext` (`"60%"`) — focusable, announced,
  and form-associable, with no hand-rolled slider ARIA. The area's keydown routes the arrow keys across
  the two axes (a single native range can't span both).
- The hue slider is an `OriSlider` (a native range → `role="slider"` + the full keyboard contract). The
  hex field is an `OriInput` — a bad or partial hex flips it to `aria-invalid` and is rejected on commit.
- The preview swatch is `role="img"` named by the current color; presets are a single-select `role="listbox"`
  with roving tabindex (one tab stop; `aria-selected` marks the active color).
- `label` names the whole control (`role="group"`). `disabled` dims the panel, blocks pointer events, and
  disables the channel + hex inputs.

**Area keyboard** (focus is on a channel input):

| Key                        | Action                                                    |
| -------------------------- | --------------------------------------------------------- |
| `ArrowLeft` / `ArrowRight` | Decrease / increase **saturation** by 1% (`Shift` = 10%). |
| `ArrowDown` / `ArrowUp`    | Decrease / increase **brightness** by 1% (`Shift` = 10%). |
| `PageDown` / `PageUp`      | Decrease / increase **brightness** by 10%.                |
| `Home` / `End`             | Jump **saturation** to 0% / 100%.                         |

## Framework API

The props, events, and slots of the **Vue** component. Behaviour comes from `useColorPicker`
(`@oriui/headless/vue`); the standalone CSS layer renders the panel statically from the
[classes](https://oriui.vercel.app/#classes) (interactivity is JS). (Svelte bindings are planned.)

### Props

| Prop         | Type                    | Default | Description                                                                                     |
| ------------ | ----------------------- | ------- | ----------------------------------------------------------------------------------------------- |
| `alpha`      | `boolean`               | —       | Add an alpha channel: a checkerboard slider + `#rrggbbaa` (or `rgba()` / `hsla()`) output.      |
| `disabled`   | `boolean`               | —       | Dims the panel, blocks pointer events, and disables the channel + hex inputs.                   |
| `eyedropper` | `boolean`               | —       | Show a pick-from-screen trigger (EyeDropper API; auto-hidden where the browser lacks it).       |
| `form`       | `string`                | —       | Associate the hidden value input with a `<form>` by id (when the picker sits outside it).       |
| `format`     | `'hex' | 'rgb' | 'hsl'` | `'hex'` | Output format of the emitted string. Always lowercase.                                          |
| `label`      | `string`                | —       | Accessible name for the whole control (→ `aria-label` on the `role="group"` root).              |
| `modelValue` | `string`                | —       | Controlled color; bind with `v-model`. Parsed loosely (hex, `rgb()/rgba()`, `hsl()/hsla()`).    |
| `name`       | `string`                | —       | Submit the current color under this field name via a hidden input (a color always has a value). |
| `presets`    | `string[]`              | —       | Preset swatch colors, rendered as a single-select roving listbox.                               |

### Events

| Event               | Payload  | Description                                                                                            |
| ------------------- | -------- | ------------------------------------------------------------------------------------------------------ |
| `update:modelValue` | `string` | Fired **live** on every interaction tick (drag / arrow / hue / hex commit / preset); drives `v-model`. |
| `change`            | `string` | Fired once when the color is **committed** (pointer release / keyboard settle) — one undo entry.       |

### Slots

| Slot      | Props                         | Description                                                                                   |
| --------- | ----------------------------- | --------------------------------------------------------------------------------------------- |
| `#swatch` | —                             | Overlay content for the preview swatch (e.g. an icon). The swatch color/ink render behind it. |
| `#preset` | `{ preset, index, selected }` | Per-preset content (the singular of `presets`). Fallback: the chip shows its color.           |

## See also

- [useColorPicker](https://oriui.vercel.app/headless/use-color-picker) — the headless composable (sRGB + 2D-area engine) behind this component.
- [OriSlider](https://oriui.vercel.app/components/slider) · [OriInput](https://oriui.vercel.app/components/input) · [OriPopover](https://oriui.vercel.app/components/popover) — the primitives it reuses.


# Combobox

A filterable single-select listbox — type to filter, navigate with the keyboard, pick one. It is the
first component driven end-to-end by &#x2A;*`@oriui/headless`**: the state machine + prop-getters own the
behaviour (open/close, filtering, the active-descendant highlight, selection, and the full
WAI-ARIA keyboard), and `OriCombobox` renders the styled shell on top. Unlike the pure-CSS
components, the behaviour needs JavaScript — the standalone classes give you the look, and
[`useCombobox`](https://oriui.vercel.app/#headless-usecombobox) gives you the behaviour for any UI.

State is expressed on real elements: `role="combobox"` with `aria-expanded` / `aria-controls` /
`aria-activedescendant` on the input, `role="listbox"` + `role="option"` + `aria-selected` on the
popup. `v-model` holds the selected option's `value`.

## Classes

The block is a labelled control wrapping a positioned listbox popup. The input reuses
[`.ori-input__field`](https://oriui.vercel.app/components/input) for its box, so the field look stays in one place.

::class-table
---
rows:
  - class: ori-combobox
    type: Block
    description: Required base class (wrapper div).
  - class: ori-combobox_* (size)
    type: Size
    description: xs · sm · <b>md</b> · lg · xl · xxl field height.
  - class: ori-color_*
    type: Color
    description: <b>primary</b> · … (focus ring + highlight + selected accent).
  - class: ori-combobox__control · __input · __trigger · __clear · __listbox ·
      __option · __empty
    type: Part
    description: control wrap / input / chevron / clear / popup / option / no-results.
  - class: ori-combobox__label · __required · __hint · __error
    type: Part
    description: label / required-asterisk / helper / error.
  - class: ori-combobox_fluid
    type: Layout
    description: full-width (stretches wrapper to 100 %).
  - class: role=combobox · aria-expanded · aria-activedescendant · aria-selected ·
      data-highlighted
    type: State
    description: real ARIA + data attributes, not classes.
---
::

## Basic

Pass `options` (`{ label, value, disabled? }[]`) and bind `v-model`. Type to filter; the list opens
as you type.

::example
  :::ori-combobox
  ---
  options:
    - label: Apple
      value: apple
    - label: Banana
      value: banana
    - label: Cherry
      value: cherry
    - label: Grape
      value: grape
    - label: Mango
      value: mango
  hint: Type to filter.
  label: Fruit
  placeholder: Search a fruit…
  ---
  :::

#vue
```vue
<script setup>
import { ref } from 'vue';
const fruit = ref(null);
const options = [
    { label: 'Apple', value: 'apple' },
    { label: 'Banana', value: 'banana' },
    { label: 'Cherry', value: 'cherry' },
    { label: 'Grape', value: 'grape' },
    { label: 'Mango', value: 'mango' }
];
</script>

<template>
    <OriCombobox
        v-model="fruit"
        :options="options"
        label="Fruit"
        placeholder="Search a fruit…"
        hint="Type to filter."
    />
</template>
```

#svelte
```svelte
<script>
    import { useCombobox } from '@oriui/headless/svelte';

    // The full state machine + WAI-ARIA listbox keyboard — the same engine as Vue, as Svelte stores.
    // (No styled Svelte component yet: compose @oriui/headless/svelte with the .ori-* classes.)
    const { items, rootProps, labelProps, controlProps, inputProps, listboxProps, getOptionProps, getOptionState } =
        useCombobox({
            id: 'fruit',
            options: [
                { label: 'Apple', value: 'apple' },
                { label: 'Banana', value: 'banana' },
                { label: 'Cherry', value: 'cherry' },
                { label: 'Grape', value: 'grape' },
                { label: 'Mango', value: 'mango' }
            ]
        });
</script>

<div {...$rootProps} class="ori-combobox ori-color_primary ori-font-size_md">
    <label {...$labelProps} class="ori-combobox__label">Fruit</label>
    <div {...$controlProps} class="ori-combobox__control">
        <input {...$inputProps} class="ori-input__field ori-combobox__input ori-size-radius_md" placeholder="Search a fruit…" />
        <ul {...$listboxProps} class="ori-combobox__listbox ori-anchored ori-anchored_bottom-start">
            {#each $items as item, i}
                <li
                    {...$getOptionProps(item, i)}
                    class="ori-combobox__option"
                    class:ori-combobox__option_selected={$getOptionState(item).selected}
                >
                    {item.label}
                </li>
            {/each}
        </ul>
    </div>
</div>
```
::

## Clearable

`clearable` shows a clear button while there is a selection. Keyboard users clear with **Escape** when
the listbox is closed (the button itself is a pointer affordance) — so the selection is always removable
without a mouse.

::example
  :::ori-combobox
  ---
  clearable: true
  options:
    - label: Apple
      value: apple
    - label: Banana
      value: banana
    - label: Grape
      value: grape
  label: Fruit
  placeholder: Pick one
  ---
  :::

#vue
```vue
<OriCombobox v-model="fruit" :options="options" label="Fruit" clearable placeholder="Pick one" />
```
::

## Sizes

`xs` → `xxl`, like the other field controls.

::example
  :::ori-combobox
  ---
  options:
    - label: Apple
      value: apple
    - label: Banana
      value: banana
  label: Small
  placeholder: sm
  size: sm
  ---
  :::

  :::ori-combobox
  ---
  options:
    - label: Apple
      value: apple
    - label: Banana
      value: banana
  label: Large
  placeholder: lg
  size: lg
  ---
  :::

#vue
```vue
<OriCombobox v-model="a" :options="options" label="Small" size="sm" />
<OriCombobox v-model="b" :options="options" label="Large" size="lg" />
```
::

## States

`disabled` blocks the control; `error` renders a `role="alert"` message and flips `aria-invalid`;
`required` adds the asterisk and guards the *selection* — via `aria-required` plus custom validity, so
typing an unmatched query can't satisfy it and the form is blocked until a real option is chosen. A disabled option is skipped during keyboard
navigation and can't be selected.

::example
  :::ori-combobox
  ---
  disabled: true
  options:
    - label: Apple
      value: apple
    - label: Banana
      value: banana
  label: Disabled
  placeholder: Cannot edit
  ---
  :::

  :::ori-combobox
  ---
  options:
    - label: Apple
      value: apple
    - label: Banana
      value: banana
  error: Please choose a fruit.
  label: With error
  placeholder: Required
  ---
  :::

#vue
```vue
<OriCombobox v-model="a" :options="options" label="Disabled" disabled />
<OriCombobox v-model="b" :options="options" label="With error" error="Please choose a fruit." required />
```
::

## Headless (`useCombobox`)

The behaviour ships separately in `@oriui/headless`, so you can build a fully custom combobox UI on
the same state machine + ARIA contract. `useCombobox` returns ready-to-`v-bind` prop bags and the
visible (filtered) items.

```vue
<script setup>
import { useCombobox } from '@oriui/headless/vue';

const { items, inputProps, listboxProps, getOptionProps, getOptionState } = useCombobox(() => ({
    options: [
        { label: 'Apple', value: 'apple' },
        { label: 'Banana', value: 'banana' }
    ]
}));
</script>

<template>
    <div>
        <input v-bind="inputProps" />
        <ul v-bind="listboxProps">
            <li
                v-for="(item, i) in items"
                :key="item.value"
                v-bind="getOptionProps(item, i)"
                :data-selected="getOptionState(item).selected"
            >
                {{ item.label }}
            </li>
        </ul>
    </div>
</template>
```

The same behaviour in Svelte 5 via `@oriui/headless/svelte` — the composable returns stores (auto-subscribe
with `$`), and the item prop-getters are a store of a function (`$getOptionProps(item, i)`):

```svelte
<script>
    import { useCombobox } from '@oriui/headless/svelte';

    const { items, inputProps, listboxProps, getOptionProps, getOptionState } = useCombobox({
        options: [
            { label: 'Apple', value: 'apple' },
            { label: 'Banana', value: 'banana' }
        ]
    });
</script>

<div>
    <input {...$inputProps} />
    <ul {...$listboxProps}>
        {#each $items as item, i}
            <li {...$getOptionProps(item, i)} data-selected={$getOptionState(item).selected}>
                {item.label}
            </li>
        {/each}
    </ul>
</div>
```

Options are a `MaybeReactive` — pass a Svelte store instead of a plain object to react to a changing
option list or `disabled`.

Pass a `filter` (`(item, query) => boolean`) to override the default case-insensitive substring
match — for fuzzy matching, async results, or server-side filtering.

## Accessibility

Implements the WAI-ARIA **combobox with listbox popup** pattern.

- The input is `role="combobox"` with `aria-autocomplete="list"`, `aria-expanded`, and
  `aria-controls` pointing at the listbox; the highlighted option is referenced by
  `aria-activedescendant` (focus stays on the input — no roving tabindex needed).
- Options are `role="option"` with `aria-selected`; the popup is `role="listbox"` labelled by the
  field label. A disabled option carries `aria-disabled` and is skipped by navigation.
- `hint` / `error` are wired through `aria-describedby` (error supersedes hint); `error` also sets
  `aria-invalid="true"` and `role="alert"`. `required` sets `aria-required` and blocks submission until a value is selected.
- The list dismisses on blur and on `Escape`; selecting an option returns focus context to the input.

| Key            | Action                                        |
| -------------- | --------------------------------------------- |
| `↓` / `↑`      | Open the list and move the highlight (wraps). |
| `Home` / `End` | Highlight the first / last option.            |
| `Enter`        | Select the highlighted option.                |
| `Escape`       | Close the list.                               |
| `Tab`          | Move focus away (closes the list).            |
| Type           | Filter the options.                           |

## Framework API

### Props

| Prop            | Type                       | Default        | Description                                                          |
| --------------- | -------------------------- | -------------- | -------------------------------------------------------------------- |
| `clearable`     | `boolean`                  | `false`        | Show a clear button while there is a selection.                      |
| `color`         | `ThemeColor`               | `'primary'`    | Accent for the focus ring, highlight, and selected option.           |
| `describedby`   | `string`                   | —              | Extra id(s) appended to `aria-describedby`.                          |
| `disabled`      | `boolean`                  | `false`        | Disable the control.                                                 |
| `error`         | `string`                   | —              | Error message (`role="alert"`); sets `aria-invalid="true"`.          |
| `filter`        | `(item, query) => boolean` | substring      | Override the default case-insensitive label filter.                  |
| `fluid`         | `boolean`                  | `false`        | Full-width.                                                          |
| `form`          | `string`                   | —              | Associate the hidden value input with a form by `id`.                |
| `hint`          | `string`                   | —              | Helper text; hidden while `error` is shown.                          |
| `id`            | `string`                   | —              | Explicit base id; auto-generated via `useId` when omitted.           |
| `invalid`       | `boolean`                  | `false`        | Set `aria-invalid` without a message.                                |
| `label`         | `string`                   | —              | Visible label, wired to the input via `for` / `id`.                  |
| `name`          | `string`                   | —              | Submit the selected **value** under this field name (hidden input).  |
| `noResultsText` | `string`                   | `'No results'` | Shown when the filter matches nothing.                               |
| `options`       | `ComboboxItem[]`           | **required**   | `{ label, value, disabled? }[]`.                                     |
| `placeholder`   | `string`                   | —              | Native placeholder.                                                  |
| `radius`        | `RadiusSize`               | `'md'`         | Field + popup corner radius.                                         |
| `required`      | `boolean`                  | `false`        | Asterisk + `aria-required`; blocks submit until a value is selected. |
| `size`          | `ActionSize`               | `'md'`         | Field height + text scale.                                           |

### v-model

`v-model` binds the selected option's `value` (`string | null`) via `defineModel`. Selecting an
option emits `update:modelValue`; clearing emits `null`.

### Slots

| Slot     | Scope                       | Description                                                                                                                           |
| -------- | --------------------------- | ------------------------------------------------------------------------------------------------------------------------------------- |
| `label`  | none                        | Rich label content (an icon + text, markup). Falls back to the `label` prop; keeps the for/id + listbox `aria-labelledby` wiring.     |
| `option` | `{ item, index, selected }` | Per-option content — rich options such as an avatar + email or a leading icon. Rendered for every option. Falls back to `item.label`. |
| `empty`  | none                        | No-results content, shown when the filter matches nothing. Falls back to the `noResultsText` prop.                                    |


# Dialog

A modal dialog — the library's first genuinely **interactive** component, built on the native
`<dialog>` element. Unlike the styled-only components, a dialog *needs behaviour*: focus trap, scroll
lock, `Esc`-to-close, click-outside dismissal, and the full WAI-ARIA keyboard contract. All of it comes
from the platform via `showModal()` — no state-machine dependency and no adapter to wire. The styled
`OriDialog` supplies only the markup and tokens.

The examples are organised by **layer**: the [class reference](https://oriui.vercel.app/#classes&#x29; is the standalone
&#x2A;*`@oriui/css`** layer, and the [Framework API](https://oriui.vercel.app/#framework-api&#x29; is the &#x2A;*`@oriui/vue`** component. Every
example is live — flip its code between **HTML** (the standalone classes, also your htmx / Astro / Svelte /
plain-HTML usage), **Vue**, and **Svelte** (`@oriui/headless/svelte`); HTML is the default.

## Classes

A dialog is a set of part classes hung on a native `<dialog>` element — there is no single block class
that drives variant tokens. Each part class maps to a structural element produced by the component.

::class-table
---
rows:
  - class: ori-dialog
    type: Block
    description: "The native <code><dialog></code> panel: max-width 460 px, rounded,
      surface-coloured. Its <code>::backdrop</code> pseudo-element is the dimmed
      overlay."
  - class: ori-dialog__content
    type: Layout
    description: Padding wrapper inside the dialog that holds the header and body.
  - class: ori-dialog__header
    type: Part
    description: Flex row — title on the left, close button on the right.
  - class: ori-dialog__title
    type: Part
    description: <code>h2</code> heading; its <code>id</code> is wired to
      <code>aria-labelledby</code> on the dialog.
  - class: ori-dialog__close
    type: Part
    description: Bare close button (<code>aria-label=Close</code>); styled via opacity.
  - class: ori-dialog__body
    type: Part
    description: Body copy region below the header.
---
::

## Anatomy

The component renders its parts in this order:

```text
#trigger slot (caller-supplied open control)
  └─ <dialog class="ori-dialog">         (native element; ::backdrop is the overlay)
       └─ .ori-dialog__content           (padding wrapper)
            ├─ .ori-dialog__header
            │    ├─ .ori-dialog__title    (h2; #title slot or `title` prop)
            │    └─ .ori-dialog__close    (× button, aria-label="Close")
            └─ .ori-dialog__body          (default slot — body copy)
```

The `<dialog>` is rendered inline; `showModal()` promotes it to the browser's top layer, so it escapes
any stacking context without `<Teleport>`. A closed `<dialog>` is hidden, so SSR markup stays stable.

## Basic

Open the dialog, tab through its controls, press `Esc`, and observe that focus returns to the
trigger. Page scroll is locked while it is open.

::example
:dialog-demo

#vue
```vue
<OriDialog title="Hello, oriUI">
    <template #trigger="{ props }">
        <OriButton v-bind="props" text="Open dialog" />
    </template>
    <p>This modal traps focus, closes on Escape, and locks page scroll.</p>
</OriDialog>
```

#html
```html
<!-- Structure only — drive it with dialog.showModal() to get the trap / ::backdrop. -->
<dialog class="ori-dialog" aria-labelledby="dlg-title">
    <div class="ori-dialog__content">
        <header class="ori-dialog__header">
            <h2 id="dlg-title" class="ori-dialog__title">Hello, oriUI</h2>
            <button class="ori-dialog__close" aria-label="Close">×</button>
        </header>
        <div class="ori-dialog__body">
            <p>This modal traps focus, closes on Escape, and locks page scroll.</p>
        </div>
    </div>
</dialog>
```

#svelte
```svelte
<script>
    import { useDialog } from '@oriui/headless/svelte';

    // No styled Svelte component yet — drive a native <dialog> with @oriui/headless/svelte.
    let dialogEl;
    const { open, triggerProps, dialogProps, titleProps, closeTriggerProps } = useDialog({ id: 'greet' });

    // The platform gives the focus trap, Esc and ::backdrop; we only toggle showModal()/close() on `open`.
    $effect(() => {
        if (!dialogEl) return;
        if ($open) dialogEl.showModal();
        else if (dialogEl.open) dialogEl.close();
    });
</script>

<button {...$triggerProps} class="ori-button ori-variant_fill ori-color_primary">Open dialog</button>

<dialog {...$dialogProps} bind:this={dialogEl} class="ori-dialog">
    <div class="ori-dialog__content">
        <header class="ori-dialog__header">
            <h2 {...$titleProps} class="ori-dialog__title">Hello, oriUI</h2>
            <button {...$closeTriggerProps} class="ori-dialog__close" aria-label="Close">×</button>
        </header>
        <div class="ori-dialog__body">
            <p>This modal traps focus and closes on Escape or a backdrop click.</p>
        </div>
    </div>
</dialog>
```
::

## Non-modal

Set `modal` to `false` for a non-modal dialog (opened with `show()` instead of `showModal()` — no scroll
lock, no focus trap, no `::backdrop`, no click-outside dismiss).

::example
:dialog-demo

#vue
```vue
<OriDialog title="Non-modal hint" :modal="false">
    <template #trigger="{ props }">
        <OriButton v-bind="props" text="Open non-modal" variant="outline" />
    </template>
    <p>Page is still scrollable and click-outside does not close this dialog.</p>
</OriDialog>
```

#html
```html
<!-- Structure only — open with dialog.show() for non-modal. -->
<dialog class="ori-dialog" aria-modal="false" aria-labelledby="dlg-title">
    <!-- content -->
</dialog>
```
::

## Initially open

Pass `defaultOpen` to open the dialog on first mount — useful for confirmation prompts that appear on
page load.

::example
:dialog-demo

#vue
```vue
<OriDialog title="Welcome back" :defaultOpen="true">
    <template #trigger="{ props }">
        <OriButton v-bind="props" text="Re-open" variant="tonal" />
    </template>
    <p>This dialog was open on first render.</p>
</OriDialog>
```

#html
```html
<!-- Structure only — call dialog.showModal() on mount to open it. -->
<dialog class="ori-dialog" aria-labelledby="dlg-title" open>
    <!-- content -->
</dialog>
```
::

## Controlled open

Bind `v-model:open` to drive the dialog from your own state — a confirmation prompt opened by a host
action, with no `#trigger` slot. The dialog still emits `update:open` (keeping `v-model` in sync when
the user closes via `Esc`, the backdrop, or the × button) and `close` for one-shot reactions.

```vue
<script setup lang="ts">
import { ref } from 'vue';
import { OriButton, OriDialog } from '@oriui/vue';

const open = ref(false);

function onConfirm() {
    // …run the destructive action…
    open.value = false;
}
</script>

<template>
    <OriButton text="Delete account" color="danger" variant="tonal" @click="open = true" />

    <OriDialog v-model:open="open" title="Delete account?">
        <p>This permanently deletes your account. This cannot be undone.</p>
        <div style="display: flex; justify-content: flex-end; gap: 0.5rem; margin-top: 1rem">
            <OriButton text="Cancel" variant="text" @click="open = false" />
            <OriButton text="Yes, delete" color="danger" @click="onConfirm" />
        </div>
    </OriDialog>
</template>
```

Reach for the uncontrolled form (`defaultOpen` + the `#trigger` slot, above) when the dialog owns a
single self-contained flow; reach for `v-model:open` when a host already holds the state — a store, a
route guard, or a shared "unsaved changes?" prompt.

## Custom title via slot

Omit the `title` prop and supply markup in the `#title` slot when you need rich heading content.

::example
:dialog-demo

#vue
```vue
<OriDialog>
    <template #trigger="{ props }">
        <OriButton v-bind="props" text="Rich title" variant="tonal" color="info" />
    </template>
    <template #title>
        <span>Delete <strong>project-x</strong>?</span>
    </template>
    <p>This action is permanent and cannot be undone.</p>
</OriDialog>
```

#html
```html
<!-- Structure only — not functional on its own. -->
<h2 id="dlg-title" class="ori-dialog__title">Delete <strong>project-x</strong>?</h2>
```
::

## Common patterns

A confirm / cancel pair inside a dialog, wired to an async action.

::example
:dialog-demo

#vue
```vue
<OriDialog title="Delete account?">
    <template #trigger="{ props }">
        <OriButton v-bind="props" text="Delete account" variant="tonal" color="danger" />
    </template>
    <p>This will permanently delete your account and all its data. This cannot be undone.</p>
    <div style="display: flex; justify-content: flex-end; gap: 0.5rem; margin-top: 1rem">
        <!-- Close via the adapter's close mechanism or a custom event -->
        <OriButton text="Cancel" variant="text" />
        <OriButton text="Yes, delete" color="danger" variant="fill" />
    </div>
</OriDialog>
```

#html
```html
<!-- Structure only — not functional on its own. -->
<dialog class="ori-dialog" aria-labelledby="dlg-title">
    <div class="ori-dialog__content">
        <header class="ori-dialog__header">
            <h2 id="dlg-title" class="ori-dialog__title">Delete account?</h2>
            <button class="ori-dialog__close" aria-label="Close">×</button>
        </header>
        <div class="ori-dialog__body">
            <p>This will permanently delete your account and all its data.</p>
            <div style="display:flex; justify-content:flex-end; gap:.5rem; margin-top:1rem">
                <button class="ori-button ori-variant_text">Cancel</button>
                <button class="ori-button ori-variant_fill ori-color_danger">Yes, delete</button>
            </div>
        </div>
    </div>
</dialog>
```
::

## Accessibility

The accessibility contract holds across both layers — the classes and the Vue component render the
same attributes. The interactive behaviour, however, must be driven by JavaScript: a static HTML
`<dialog>` is markup only until `showModal()` opens it.

- The `<dialog>` is `role="dialog"`, `aria-modal="true"` (modal mode), and labelled by the title
  element via `aria-labelledby`.
- The close button has `aria-label="Close"`.
- The `#trigger` slot's `props` object includes the `aria-*` attributes for the trigger element; bind
  them with `v-bind="props"`.
- `showModal()` provides the live behaviour — focus trap, scroll lock, `::backdrop`, and returning focus
  to the trigger on close — straight from the platform.

| Key         | Action                                                                  |
| ----------- | ----------------------------------------------------------------------- |
| `Escape`    | Closes the dialog and returns focus to the trigger (native `<dialog>`). |
| `Tab`       | Cycles focus among interactive elements inside the dialog (focus trap). |
| `Shift+Tab` | Cycles focus backwards inside the dialog.                               |

## Framework API

The props, events, slots, and headless wiring of the **Vue** component. The standalone CSS layer has
no component API — its surface is the [classes](https://oriui.vercel.app/#classes) above, and the behaviour is yours to wire.
(Svelte bindings are planned.)

### Props

| Prop                     | Type      | Default | Description                                                                |
| ------------------------ | --------- | ------- | -------------------------------------------------------------------------- |
| `closeOnEscape`          | `boolean` | `true`  | Whether `Esc` closes the dialog.                                           |
| `closeOnInteractOutside` | `boolean` | `true`  | Whether a click on the `::backdrop` closes the dialog.                     |
| `defaultOpen`            | `boolean` | `false` | Whether the dialog is open on first mount.                                 |
| `modal`                  | `boolean` | `true`  | Modal mode: `showModal()` (trap + scroll lock + `::backdrop`) vs `show()`. |
| `open`                   | `boolean` | —       | Controlled open state for `v-model:open`. Omit for an uncontrolled dialog. |
| `title`                  | `string`  | —       | Heading text. Overridden by the `#title` slot when provided.               |

### Events & attributes

| Event         | Payload   | Description                                                                     |
| ------------- | --------- | ------------------------------------------------------------------------------- |
| `update:open` | `boolean` | Fires on every open/close transition — enables `v-model:open`.                  |
| `close`       | —         | Fires whenever the dialog closes (trigger, `Esc`, backdrop, × button, or host). |

Bind `v-model:open` to control the dialog from a host ref (see [Controlled open](https://oriui.vercel.app/#controlled-open)).
Both events fire in the uncontrolled (`defaultOpen` + `#trigger`) mode too, so a host can react to a
close without owning the state. The `#trigger` slot also exposes `props` and `open` — bind
`v-bind="props"` on the trigger element; `open` reflects the current state if you need it in the
template.

Controlled mode is **optimistic**: a user-initiated close (`Esc`, the backdrop, or the × button)
always closes the dialog and *then* emits — treat `update:open(false)` / `close` as authoritative and
mirror them into your state. The dialog can't be held open by ignoring the event (a native `<dialog>`
closes on `Esc` regardless — set `:closeOnEscape="false"` to disable that one path).

`OriDialog` renders a fragment (the `#trigger` slot *plus* the `<dialog>`), so stray attributes placed
directly on `<OriDialog>` are **not** auto-inherited onto a single root — put attributes meant for the
trigger on the trigger element via the `#trigger` slot's `props` instead.

### Slots

| Slot      | Scope                              | Description                                                                                |
| --------- | ---------------------------------- | ------------------------------------------------------------------------------------------ |
| `trigger` | `{ props: object, open: boolean }` | The control that opens the dialog. Bind `:props` on your trigger element.                  |
| `title`   | —                                  | Replaces the heading text; receives no scope. Falls back to the `title` prop when omitted. |
| `default` | —                                  | Body content rendered inside `.ori-dialog__body`.                                          |

### Headless & adapter

`OriDialog` calls [`useDialog()`](https://oriui.vercel.app/headless/use-dialog) from `@oriui/headless/vue`, which defaults to the native
`<dialog>` engine — the focus trap, scroll lock, `Esc` handling, `::backdrop` and focus-return are the
platform's job, so **no adapter and no extra dependency are required**.

The `OriHeadless` contract is still available as a hedge: register a custom engine (e.g. a Zag-backed
adapter for a genuinely hard widget) only if a project needs one — the markup never changes.

```ts
// main.ts — optional; the native engine is used when nothing is registered.
import { createApp } from 'vue';
import { OriHeadless } from '@oriui/headless/vue';
import { myDialog } from './headless/my-dialog'; // optional custom adapter

const app = createApp(App);
app.use(OriHeadless, { dialog: myDialog });
app.mount('#app');
```

See [useDialog](https://oriui.vercel.app/headless/use-dialog) for the full control contract.


# Divider

A horizontal (default) or vertical rule that separates content. An optional centered label turns it
into a visual break like the classic "OR" between form sections. A pure layout/structure primitive —
no interactive behaviour, no variants, no size scale.

The examples are organised by **layer**: the [class reference](https://oriui.vercel.app/#classes&#x29; is the standalone
&#x2A;*`@oriui/css`** layer, and the [Framework API](https://oriui.vercel.app/#framework-api&#x29; is the &#x2A;*`@oriui/vue`** component. Every
example is live — flip its code between **HTML** (the standalone classes, also your htmx / Astro / Svelte /
plain-HTML usage), **Vue**; HTML is the default.

## Classes

A divider is a block class plus an optional modifier and a color utility. The Vue props in
[Framework API](https://oriui.vercel.app/#framework-api) map 1:1 to these. There is no variant or size scale — the line
inherits thickness and gap from the surrounding context via `--ori-size-gap`.

::class-table
---
rows:
  - class: ori-divider
    type: Block
    description: Required base class. Renders a subtle horizontal rule using a 25%
      currentcolor mix.
  - class: ori-divider_vertical
    type: Modifier
    description: "Switches to a vertical rule. Needs a flex/grid parent that
      provides height; the divider aligns-self: stretch."
  - class: ori-divider_text
    type: Modifier
    description: Auto-applied when a label is present. Splits the line into two
      segments around the centered label.
  - class: ori-divider__label
    type: Part
    description: The centered label span. Rendered inside the block when text or a
      default slot is supplied.
  - class: ori-color_*
    type: Color
    description: primary · secondary · success · warn · danger · info · surface ·
      background — repoints --ori-color to a full role color. Omit for the
      default subtle 25% currentcolor mix.
---
::

## Plain rule

A bare horizontal divider with no label — the most common use: separating sections of a page or a
card body.

::example
:ori-divider

#vue
```vue
<OriDivider />
```

#html
```html
<div class="ori-divider" role="separator"></div>
```
::

## With label

Pass `text` to insert a centered label. The block class gains `ori-divider_text` automatically and
the line splits around a `<span class="ori-divider__label">`.

::example
:ori-divider{text="OR"}

#vue
```vue
<OriDivider text="OR" />
```

#html
```html
<div class="ori-divider ori-divider_text" role="separator">
    <span class="ori-divider__label">OR</span>
</div>
```
::

## Slot label

The default slot overrides `text` when you need richer content inside the label — an icon, a badge,
or styled text.

::example
  :::ori-divider
  Section break
  :::

#vue
```vue
<OriDivider>Section break</OriDivider>
```

#html
```html
<div class="ori-divider ori-divider_text" role="separator">
    <span class="ori-divider__label">Section break</span>
</div>
```
::

## Colors

An optional `color` repoints `--ori-color` to a full semantic role, making the line more prominent.
Omit for the default subtle mix.

::example
:ori-divider{color="primary"}

:ori-divider{color="secondary"}

:ori-divider{color="success"}

:ori-divider{color="warn"}

:ori-divider{color="danger"}

:ori-divider{color="info"}

#vue
```vue
<OriDivider color="primary" />
<OriDivider color="secondary" />
<OriDivider color="success" />
<OriDivider color="warn" />
<OriDivider color="danger" />
<OriDivider color="info" />
```

#html
```html
<!-- swap the color class: ori-color_primary → _secondary / _success / _warn / _danger / _info -->
<div class="ori-divider ori-color_primary" role="separator"></div>
```
::

A colored label divider:

::example
:ori-divider{color="primary" text="Continue with"}

#vue
```vue
<OriDivider text="Continue with" color="primary" />
```

#html
```html
<div class="ori-divider ori-divider_text ori-color_primary" role="separator">
    <span class="ori-divider__label">Continue with</span>
</div>
```
::

## Vertical

`vertical` renders a column rule that stretches to the parent's cross-axis height. The parent must
be a flex or grid container with a defined height — the divider uses `align-self: stretch` to fill
it. Spacing around the vertical rule comes from `margin-inline` (driven by `--ori-size-gap`).

::example
  :::ori-stack{cluster gap="sm"}
  :ori-button{text="Item one" variant="text"}

    ::::ori-divider{vertical}
    ::::

  :ori-button{text="Item two" variant="text"}

    ::::ori-divider{vertical}
    ::::

  :ori-button{text="Item three" variant="text"}
  :::

#vue
```vue
<div style="display: flex; align-items: center; height: 3rem">
    <span>Item one</span>
    <OriDivider vertical />
    <span>Item two</span>
    <OriDivider vertical />
    <span>Item three</span>
</div>
```

#html
```html
<div style="display: flex; align-items: center; height: 3rem">
    <span>Item one</span>
    <div class="ori-divider ori-divider_vertical" role="separator" aria-orientation="vertical"></div>
    <span>Item two</span>
    <div class="ori-divider ori-divider_vertical" role="separator" aria-orientation="vertical"></div>
    <span>Item three</span>
</div>
```
::

## Common patterns

A sign-in form with an "OR" break and a toolbar that uses vertical rules between action groups.

::example
:ori-divider{text="OR"}

#vue
```vue
<!-- sign-in form: email/password block → divider → social login -->
<form style="display: flex; flex-direction: column; gap: 1rem; max-width: 22rem">
    <input type="email" placeholder="Email" />
    <input type="password" placeholder="Password" />
    <OriButton text="Sign in" variant="fill" fluid />
    <OriDivider text="OR" />
    <OriButton text="Continue with Google" variant="outline" fluid />
</form>
```

#html
```html
<form style="display: flex; flex-direction: column; gap: 1rem; max-width: 22rem">
    <input type="email" placeholder="Email" />
    <input type="password" placeholder="Password" />
    <button class="ori-button ori-button_fluid ori-variant_fill ori-color_primary">Sign in</button>

    <div class="ori-divider ori-divider_text" role="separator">
        <span class="ori-divider__label">OR</span>
    </div>

    <button class="ori-button ori-button_fluid ori-variant_outline ori-color_primary">Continue with Google</button>
</form>
```
::

## Accessibility

The accessibility contract holds across every layer — the standalone classes and the Vue component
render the same attributes.

- Renders `<div role="separator">` — the correct ARIA landmark for a thematic break between content
  regions.
- `aria-orientation="vertical"` is set only when `vertical` is `true`. For the default horizontal
  orientation the attribute is omitted (horizontal is the implied default per the ARIA spec).
- The line itself is purely decorative. When a label is present it is plain text inside a `<span>`;
  no additional ARIA is needed — the `role="separator"` communicates structure, not the label.
- The component is not interactive and is never focusable. No keyboard contract applies.

| Attribute                     | Element      | Notes                                                                 |
| ----------------------------- | ------------ | --------------------------------------------------------------------- |
| `role="separator"`            | Root `<div>` | Always present; communicates a thematic break.                        |
| `aria-orientation="vertical"` | Root `<div>` | Set only when `vertical` is `true`; omitted for horizontal (default). |

## Framework API

The props, events, and slots of the **Vue** component. The standalone CSS layer has no component
API — its surface is the [classes](https://oriui.vercel.app/#classes) above. (Svelte bindings are planned.)

### Props

| Prop       | Type         | Default | Description                                                                                                                                    |
| ---------- | ------------ | ------- | ---------------------------------------------------------------------------------------------------------------------------------------------- |
| `color`    | `ThemeColor` | —       | Semantic color role. Omit to use the default subtle 25% `currentcolor` mix.                                                                    |
| `text`     | `string`     | —       | Centered label. Adds `ori-divider_text` and renders `<span class="ori-divider__label">`. Overridden by the default slot when both are present. |
| `vertical` | `boolean`    | `false` | Renders a vertical rule. Requires a flex or grid parent with a defined height; the rule stretches to fill it.                                  |

`ThemeColor`: `'primary' | 'secondary' | 'success' | 'warn' | 'danger' | 'info' | 'surface' | 'background'`

### Events & attributes

OriDivider declares **no custom events** and does not set `inheritAttrs: false`, so any extra
attributes you pass (`class`, `style`, `data-*`, …) fall through to the root `<div role="separator">`.

### Slots

| Slot      | Description                                                                                                                             |
| --------- | --------------------------------------------------------------------------------------------------------------------------------------- |
| `default` | Centered label content. Overrides `text` when both are supplied. Adds `ori-divider_text` and wraps the content in `ori-divider__label`. |


# Field

The shared shell for form controls — **one source of truth** for the `label` / `hint` / `error` /
`required` contract that [Input](https://oriui.vercel.app/components/input), [Select](https://oriui.vercel.app/components/select),
[Textarea](https://oriui.vercel.app/components/textarea), [Combobox](https://oriui.vercel.app/components/combobox), [Slider](https://oriui.vercel.app/components/slider),
[RadioGroup](https://oriui.vercel.app/components/radio), and [ColorPicker](https://oriui.vercel.app/components/color-picker) otherwise each wire
by hand. Wrap a control in `OriField` and it adopts the field's id, `aria-describedby`,
`aria-invalid`, `required`, `disabled`, and `size` — and stops rendering its own label and helper, so
there is exactly one of each, wired identically every time. Group and composite controls (RadioGroup,
Combobox's listbox, ColorPicker) name themselves via `aria-labelledby` pointing at the field's label.

Any control works: an Ori control nested inside wires up automatically (via `provide`/`inject`); a
raw `<input>` or htmx markup wires up through the scoped-slot `controlAttrs`. The standalone
&#x2A;*HTML / `@oriui/css`** path is the same `.ori-field` shell around any `.ori-*` field element.

## Classes

The field is a wrapper that owns the label, the required asterisk, and the hint / error line; the
control sits in between. One class repoints one token — the `ori-font-size_*` scale drives the label
and helper text (and is inherited by a nested control).

::class-table
---
rows:
  - class: ori-field
    type: Block
    description: Required base class (wrapper div).
  - class: ori-font-size_*
    type: Font
    description: xs · sm · <b>md</b> · lg · xl · xxl — label + hint + error scale
      (and the nested control).
  - class: ori-field__label · ori-field__required · ori-field__hint · ori-field__error
    type: Part
    description: label / required-asterisk / helper / error elements.
  - class: ori-field_fluid
    type: Layout
    description: full-width (stretches the field to 100 %).
  - class: for · id · aria-describedby · aria-invalid
    type: State
    description: real attributes on the control, not classes — shared with the label
      and helper.
---
::

## With a control

Wrap any Ori control. The field renders the label and helper; the control renders just its field
element and inherits the wiring.

::example
  :::ori-field{hint="We never share it." label="Email"}
  :ori-input{placeholder="you@example.com" type="email"}
  :::

#vue
```vue
<OriField label="Email" hint="We never share it.">
    <OriInput v-model="email" type="email" placeholder="you@example.com" />
</OriField>
```

#html
```html
<div class="ori-field ori-font-size_md">
    <label class="ori-field__label" for="email">Email</label>
    <input
        id="email"
        type="email"
        placeholder="you@example.com"
        aria-describedby="email-hint"
        class="ori-input ori-input__field ori-size-radius_md"
    />
    <p id="email-hint" class="ori-field__hint">We never share it.</p>
</div>
```
::

## Required & error

`required` adds the asterisk (hidden from assistive tech) and the native `required` on the control.
`error` renders a `role="alert"` message, flips the control to `aria-invalid`, and supersedes the
hint — there is never a dangling `aria-describedby`.

::example
  :::ori-field{required error="Enter a valid email address." label="Email"}
  :ori-input{placeholder="you@example.com" type="email"}
  :::

#vue
```vue
<OriField label="Email" required error="Enter a valid email address.">
    <OriInput v-model="email" type="email" placeholder="you@example.com" />
</OriField>
```

#html
```html
<div class="ori-field ori-font-size_md">
    <label class="ori-field__label" for="email">
        Email<span class="ori-field__required" aria-hidden="true">*</span>
    </label>
    <input
        id="email"
        type="email"
        required
        aria-invalid="true"
        aria-describedby="email-error"
        class="ori-input ori-input__field ori-size-radius_md"
    />
    <p id="email-error" class="ori-field__error" role="alert">Enter a valid email address.</p>
</div>
```
::

## Any control

The same shell wraps a [Select](https://oriui.vercel.app/components/select) or [Textarea](https://oriui.vercel.app/components/textarea) — each drops
its own label and helper and reads the field's wiring instead.

::example
  :::ori-field{hint="Pick one." label="Favourite fruit"}
    ::::ori-select
    ---
    options:
      - label: Apple
        value: apple
      - label: Banana
        value: banana
    placeholder: Choose…
    ---
    ::::
  :::

  :::ori-field{hint="A short introduction." label="Bio"}
    ::::ori-textarea{:rows='3' placeholder="Tell us about yourself"}
    ::::
  :::

#vue
```vue
<OriField label="Favourite fruit" hint="Pick one.">
    <OriSelect v-model="fruit" :options="options" placeholder="Choose…" />
</OriField>

<OriField label="Bio" hint="A short introduction.">
    <OriTextarea v-model="bio" :rows="3" placeholder="Tell us about yourself" />
</OriField>
```
::

## Sizes

`size` lives on the field and propagates to controls that have a size scale (Input, Select, Textarea,
Combobox, RadioGroup), so the label, helper, and control share one scale. `xs` → `xxl`. Size-less
controls (Slider, ColorPicker) keep their fixed dimensions — only the label + helper scale.

::example
  :::ori-field{hint="size = sm" label="Small" size="sm"}
  :ori-input{placeholder="sm"}
  :::

  :::ori-field{hint="size = lg" label="Large" size="lg"}
  :ori-input{placeholder="lg"}
  :::

#vue
```vue
<OriField label="Small" size="sm" hint="size = sm">
    <OriInput v-model="a" placeholder="sm" />
</OriField>

<OriField label="Large" size="lg" hint="size = lg">
    <OriInput v-model="b" placeholder="lg" />
</OriField>
```
::

## Raw controls (CSS layer / htmx)

Without Vue, the field is still just markup: the `.ori-field` shell around any `.ori-*` field
element, with the `for` / `id` / `aria-describedby` written by hand. In Vue, a non-Ori control reads
the same values from the scoped-slot `controlAttrs`.

::example
  :::ori-field{hint="Letters and numbers only." label="Username"}
  :ori-input{placeholder="ori_user"}
  :::

#vue
```vue
<!-- a non-Ori control: spread the field's wiring with v-bind -->
<OriField v-slot="field" label="Username" hint="Letters and numbers only.">
    <input v-bind="field.controlAttrs" class="ori-input ori-input__field ori-size-radius_md" />
</OriField>
```

#html
```html
<div class="ori-field ori-font-size_md">
    <label class="ori-field__label" for="username">Username</label>
    <input id="username" aria-describedby="username-hint" class="ori-input ori-input__field ori-size-radius_md" />
    <p id="username-hint" class="ori-field__hint">Letters and numbers only.</p>
</div>
```
::

## Accessibility

The contract holds across every layer — the standalone classes and the Vue component render the same
attributes and ARIA wiring.

- **Labelable controls** (Input, Select, Textarea, the Combobox input, the Slider range) are tied to
  the `label` by `for` / `id`; the id is auto-generated (`useId`) when you don't pass one, and the
  nested control adopts it. **Group / composite controls** (RadioGroup, ColorPicker, the Combobox
  listbox) can't be targeted by `for`, so they name themselves via `aria-labelledby` pointing at the
  field's label instead.
- `hint` and `error` are wired through `aria-describedby`, referencing only the element actually
  rendered (`error` supersedes `hint`). Pass extra ids with `describedby` for a shared note.
- `error` sets `aria-invalid="true"` and announces via `role="alert"`; `invalid` flips
  `aria-invalid` on its own for external validation.
- `required` and `disabled` set the real native attributes on the control.
- A control nested in a field renders **no** label or helper of its own — exactly one of each, so
  there is never a duplicate label or a dangling description.

| Key   | Action                                  |
| ----- | --------------------------------------- |
| `Tab` | Moves focus to / away from the control. |

## Framework API

The props and slots of the **Vue** component. The standalone CSS layer has no component API — its
surface is the [classes](https://oriui.vercel.app/#classes) above. (Svelte bindings are planned.)

### Props

| Prop          | Type         | Default | Description                                                                                |
| ------------- | ------------ | ------- | ------------------------------------------------------------------------------------------ |
| `describedby` | `string`     | —       | Extra element id(s) appended to `aria-describedby` (e.g. a shared form note).              |
| `disabled`    | `boolean`    | `false` | Drives the nested control's native `disabled`.                                             |
| `error`       | `string`     | —       | Error message rendered below the control (`role="alert"`); sets `aria-invalid="true"`.     |
| `fluid`       | `boolean`    | `false` | Full-width — stretches the field to 100 % of its container.                                |
| `hint`        | `string`     | —       | Helper text below the control; hidden while `error` is shown.                              |
| `id`          | `string`     | —       | Explicit shared id; auto-generated via `useId` when omitted.                               |
| `invalid`     | `boolean`    | `false` | Sets `aria-invalid="true"` without an error message (for external validation).             |
| `label`       | `string`     | —       | Visible `<label>` text, wired to the control via `for` / `id`.                             |
| `required`    | `boolean`    | `false` | Renders the asterisk and sets the control's native `required`.                             |
| `size`        | `ActionSize` | `'md'`  | Label + helper scale, propagated to the nested control (`xs` · sm · md · lg · xl · `xxl`). |

### Slots

The `label`, `hint`, and `error` slots each override the matching prop with custom content while
keeping the full wiring — the `label` slot preserves the `for` / `id` association and the trailing
required asterisk, and a slot-only `#error` still sets `role="alert"` and flips the field to
`aria-invalid` (exactly as the prop does). The default slot is the control.

| Slot      | Falls back to | Description                                                                                  |
| --------- | ------------- | -------------------------------------------------------------------------------------------- |
| `default` | —             | The control. Receives the scoped props below for wiring a non-Ori control.                   |
| `label`   | `label` prop  | Label content, inside the `<label>` — keeps the `for` / `id` link and the required asterisk. |
| `hint`    | `hint` prop   | Helper text below the control; hidden while an error is shown.                               |
| `error`   | `error` prop  | Error message below the control; sets `aria-invalid` and `role="alert"`, superseding `hint`. |

The default slot receives scoped props for wiring a non-Ori control — Ori controls ignore them and
read the context directly.

| Slot prop      | Type      | Description                                                                     |
| -------------- | --------- | ------------------------------------------------------------------------------- |
| `controlAttrs` | `object`  | Ready-to-`v-bind` `{ id, aria-describedby, aria-invalid, disabled, required }`. |
| `id`           | `string`  | The shared field id.                                                            |
| `describedby`  | `string`  | The resolved `aria-describedby` (or `undefined`).                               |
| `invalid`      | `boolean` | Whether the field is in an invalid state.                                       |


# Icon

A styled, accessible SVG icon. Decorative by default — renders with `aria-hidden="true"` and no
role. Pass a `label` to expose it to assistive technology as an image: the icon switches to
`role="img"` + `aria-label` automatically.

The examples are organised by **layer**: the [class reference](https://oriui.vercel.app/#classes&#x29; is the standalone
&#x2A;*`@oriui/css`** layer, and the [Framework API](https://oriui.vercel.app/#framework-api&#x29; is the &#x2A;*`@oriui/vue`** component. Every
example is live — flip its code between **HTML** (the standalone classes, also your htmx / Astro / Svelte /
plain-HTML usage), **Vue**; HTML is the default.

## Classes

An icon is a block class plus single-class token utilities — one class repoints one token; no
separate base class is needed. The Vue props in [Framework API](https://oriui.vercel.app/#framework-api) map 1:1 to these.
There is no variant or radius — an icon takes a size, an optional color, and optional layout
modifiers.

::class-table
---
rows:
  - class: ori-icon
    type: Block
    description: Required base class. Default size (text) and spacing are baked in —
      a bare block is valid.
  - class: ori-icon_* (size sugar)
    type: Size
    description: text (inherits) · xs · sm · md · lg · xl · xxl — <b>text</b> is the default
  - class: ori-color_*
    type: Color
    description: primary · secondary · success · warn · danger · info · surface ·
      background — omit to inherit
  - class: ori-size-action-space_*
    type: Layout
    description: adds margin equal to the action-space scale for the active size
      (the spaced opt-in); pair with a size modifier
  - class: ori-icon_inline
    type: Layout
    description: switches to inline-flex with a small em-based margin for flow text
  - class: aria-hidden · role=img
    type: State
    description: decorative by default (aria-hidden=true); a label switches to
      role=img + aria-label
---
::

## Sizes

`xs` → `xxl`. The default `text` means the icon inherits the current font size — use `text` to keep
an icon visually matched to surrounding copy.

::example
:ori-icon{icon="M22,13H13V22H11V13H2V11H11V2H13V11H22V13Z" size="xs"}

:ori-icon{icon="M22,13H13V22H11V13H2V11H11V2H13V11H22V13Z" size="sm"}

:ori-icon{icon="M22,13H13V22H11V13H2V11H11V2H13V11H22V13Z" size="md"}

:ori-icon{icon="M22,13H13V22H11V13H2V11H11V2H13V11H22V13Z" size="lg"}

:ori-icon{icon="M22,13H13V22H11V13H2V11H11V2H13V11H22V13Z" size="xl"}

:ori-icon{icon="M22,13H13V22H11V13H2V11H11V2H13V11H22V13Z" size="xxl"}

The `text` default inherits the surrounding font size — the icon below sits inside a sentence and tracks the
paragraph's `font-size` with no explicit size prop:

  :::ori-icon{inline icon="M22,13H13V22H11V13H2V11H11V2H13V11H22V13Z"}
  :::

#html
```html
<!-- ori-icon_xs / _md / _xxl drive the icon box; aria-hidden because decorative -->
<i class="ori-icon ori-icon_xs" aria-hidden="true">
    <svg viewBox="0 0 24 24"><path d="M22,13H13V22H11V13H2V11H11V2H13V11H22V13Z" /></svg>
</i>
<i class="ori-icon ori-icon_md" aria-hidden="true">
    <svg viewBox="0 0 24 24"><path d="M22,13H13V22H11V13H2V11H11V2H13V11H22V13Z" /></svg>
</i>
<i class="ori-icon ori-icon_xxl" aria-hidden="true">
    <svg viewBox="0 0 24 24"><path d="M22,13H13V22H11V13H2V11H11V2H13V11H22V13Z" /></svg>
</i>
<!-- no size modifier: inherits font size (text default) -->
<i class="ori-icon ori-icon_inline" aria-hidden="true">
    <svg viewBox="0 0 24 24"><path d="M22,13H13V22H11V13H2V11H11V2H13V11H22V13Z" /></svg>
</i>
```

#vue
```vue
<OriIcon icon="M22,13H13V22H11V13H2V11H11V2H13V11H22V13Z" size="xs" />
<OriIcon icon="M22,13H13V22H11V13H2V11H11V2H13V11H22V13Z" size="md" />
<OriIcon icon="M22,13H13V22H11V13H2V11H11V2H13V11H22V13Z" size="xxl" />
<!-- default size="text": icon box matches the current font size -->
<OriIcon icon="M22,13H13V22H11V13H2V11H11V2H13V11H22V13Z" inline />
```
::

## Colors

Every semantic role. `surface` / `background` are also available. Omit `color` to inherit `currentcolor` from the parent.

::example
:ori-icon{color="primary" icon="M22,13H13V22H11V13H2V11H11V2H13V11H22V13Z" size="lg"}

:ori-icon{color="secondary" icon="M22,13H13V22H11V13H2V11H11V2H13V11H22V13Z" size="lg"}

:ori-icon{color="success" icon="M22,13H13V22H11V13H2V11H11V2H13V11H22V13Z" size="lg"}

:ori-icon{color="warn" icon="M22,13H13V22H11V13H2V11H11V2H13V11H22V13Z" size="lg"}

:ori-icon{color="danger" icon="M22,13H13V22H11V13H2V11H11V2H13V11H22V13Z" size="lg"}

:ori-icon{color="info" icon="M22,13H13V22H11V13H2V11H11V2H13V11H22V13Z" size="lg"}

#html
```html
<!-- ori-color_<role> repoints the color token in one class -->
<i class="ori-icon ori-icon_lg ori-color_primary" aria-hidden="true">
    <svg viewBox="0 0 24 24"><path d="M22,13H13V22H11V13H2V11H11V2H13V11H22V13Z" /></svg>
</i>
<i class="ori-icon ori-icon_lg ori-color_danger" aria-hidden="true">
    <svg viewBox="0 0 24 24"><path d="M22,13H13V22H11V13H2V11H11V2H13V11H22V13Z" /></svg>
</i>
```

#vue
```vue
<OriIcon icon="…" color="primary" size="lg" />
<OriIcon icon="…" color="success" size="lg" />
<OriIcon icon="…" color="danger" size="lg" />
<OriIcon icon="…" color="warn" size="lg" />
```
::

## Inline

`inline` switches the icon to `inline-flex` with a small `em`-based margin so it flows naturally
inside a sentence or a label without a wrapper element.

::example
  :::ori-icon
  ---
  inline: true
  icon: M13,9H11V7H13M13,17H11V11H13M12,2A10,10 0 0,0 2,12A10,10 0 0,0 12,22A10,10
    0 0,0 22,12A10,10 0 0,0 12,2Z
  size: md
  ---
  :::

#html
```html
<p>
    Read the
    <i class="ori-icon ori-icon_inline ori-icon_md" aria-hidden="true">
        <svg viewBox="0 0 24 24"><path d="M13,9H11V7H13…" /></svg>
    </i>
    note carefully.
</p>
```

#vue
```vue
<p>
    Read the
    <OriIcon icon="M13,9H11V7H13M13,17H11V11H13M12,2A10,10…" inline size="md" />
    note carefully.
</p>
```
::

## Spaced

`spaced` adds a margin around the icon equal to the action-space scale for the active size — useful
when the icon floats in open space rather than inside a button or label.

::example
  :::ori-icon
  ---
  spaced: true
  color: primary
  icon: M22,13H13V22H11V13H2V11H11V2H13V11H22V13Z
  size: lg
  ---
  :::

#html
```html
<i class="ori-icon ori-icon_lg ori-size-action-space_lg ori-color_primary" aria-hidden="true">
    <svg viewBox="0 0 24 24"><path d="M22,13H13V22H11V13H2V11H11V2H13V11H22V13Z" /></svg>
</i>
```

#vue
```vue
<OriIcon icon="…" spaced size="lg" color="primary" />
```
::

## Accessible (labelled)

Pass `label` to make the icon meaningful. The component sets `role="img"` and `aria-label`
automatically and removes `aria-hidden`.

::example
:ori-icon{icon="M12,2A10,10 0 0,0 2,12A10,10 0 0,0 12,22A10,10 0 0,0 22,12A10,10 0 0,0 12,2M12,20A8,8 0 0,1 4,12A8,8 0 0,1 12,4A8,8 0 0,1 20,12A8,8 0 0,1 12,20M13,10H17V8H11V13H13V10M13,14H11V16H13V14Z" label="Warning" size="lg"}

#html
```html
<!-- note: no aria-hidden; role="img" + aria-label carry the name -->
<i class="ori-icon ori-icon_lg" role="img" aria-label="Warning">
    <svg viewBox="0 0 24 24"><path d="M12,2A10,10…" /></svg>
</i>
```

#vue
```vue
<!-- standalone icon with meaning: add a label -->
<OriIcon icon="…" size="lg" label="Warning" />
```
::

## Custom SVG slot

Omit `icon` and place your own SVG (or any content) in the default slot. The slot content is sized
to 100% × 100% and filled with `currentcolor`.

::example
:ori-icon{color="primary" size="lg"}

#html
```html
<i class="ori-icon ori-icon_lg ori-color_primary" aria-hidden="true">
    <svg viewBox="0 0 24 24">
        <circle cx="12" cy="12" r="10" />
        <path d="M12 8v4l3 3" stroke="white" stroke-width="2" fill="none" />
    </svg>
</i>
```

#vue
```vue
<!-- custom multi-path SVG -->
<OriIcon size="lg" color="primary">
    <svg viewBox="0 0 24 24">
        <circle cx="12" cy="12" r="10" />
        <path d="M12 8v4l3 3" stroke="white" stroke-width="2" fill="none" />
    </svg>
</OriIcon>
```
::

## Common patterns

An icon placed beside a status badge — size matches the action row, color follows the semantic role.

::example
:ori-icon{color="success" icon="M21,7L9,19L3.5,13.5L4.91,12.09L9,16.17L19.59,5.59L21,7Z" size="md"}

:ori-icon{color="warn" icon="M13,13H11V7H13M13,17H11V15H13M12,2A10,10 0 0,0 2,12A10,10 0 0,0 12,22A10,10 0 0,0 22,12A10,10 0 0,0 12,2Z" size="md"}

:ori-icon{color="danger" icon="M19,6.41L17.59,5L12,10.59L6.41,5L5,6.41L10.59,12L5,17.59L6.41,19L12,13.41L17.59,19L19,17.59L13.41,12L19,6.41Z" size="md"}

#html
```html
<div style="display: flex; align-items: center; gap: 0.5rem">
    <i class="ori-icon ori-icon_md ori-color_success" aria-hidden="true">
        <svg viewBox="0 0 24 24"><path d="M21,7L9,19L3.5,13.5…" /></svg>
    </i>
    <span>Deployed</span>
</div>
```

#vue
```vue
<!-- status row: icon + label, icon is decorative (the text carries the meaning) -->
<div style="display: flex; align-items: center; gap: 0.5rem">
    <OriIcon icon="M21,7L9,19L3.5,13.5…" color="success" size="md" />
    <span>Deployed</span>
</div>
<div style="display: flex; align-items: center; gap: 0.5rem">
    <OriIcon icon="M13,13H11V7H13…" color="warn" size="md" />
    <span>Pending review</span>
</div>
<div style="display: flex; align-items: center; gap: 0.5rem">
    <OriIcon icon="M19,6.41L17.59,5…" color="danger" size="md" />
    <span>Build failed</span>
</div>
```
::

## Accessibility

The accessibility contract holds across every layer — the standalone classes and the Vue component
render the same attributes.

- **Decorative by default**: renders `<i aria-hidden="true">` with no role. Use this mode when the
  icon sits beside visible text that already communicates its meaning (status rows, labelled buttons,
  list items with text).
- **Meaningful icon**: pass `label` — the component adds `role="img"` and `aria-label` and removes
  `aria-hidden`. Use this mode for standalone icons that carry meaning not expressed in nearby text
  (e.g. a lone star meaning "favourited").
- When used inside an `OriButton` (or any control with its own accessible name), the icon is always
  decorative — let the button's own label or `aria-label` carry the name.
- `:focus-visible` is not applicable — OriIcon is a presentational element, not interactive.

| Attribute            | When set                                 |
| -------------------- | ---------------------------------------- |
| `aria-hidden="true"` | Default; no `label` prop.                |
| `role="img"`         | `label` prop is provided.                |
| `aria-label`         | Equal to the `label` prop when provided. |

## Framework API

The props, events, and slots of the **Vue** component. The standalone CSS layer has no component
API — its surface is the [classes](https://oriui.vercel.app/#classes) above. (Svelte bindings are planned.)

### Props

| Prop     | Type         | Default  | Description                                                                                      |
| -------- | ------------ | -------- | ------------------------------------------------------------------------------------------------ |
| `color`  | `ThemeColor` | —        | Semantic color role. Omit to inherit `currentcolor` from the parent.                             |
| `icon`   | `string`     | —        | SVG `<path d>` string. Renders inside a `24 × 24` viewBox. Omit to use the default slot instead. |
| `inline` | `boolean`    | `false`  | Switches to `inline-flex` with an `em`-based margin for use inside text flow.                    |
| `label`  | `string`     | —        | Accessible name. When set, adds `role="img"` and `aria-label`; removes `aria-hidden`.            |
| `size`   | `ActionSize` | `'text'` | Icon box size (`xs` · `sm` · `md` · `lg` · `xl` · `xxl`). `text` inherits the current font size. |
| `spaced` | `boolean`    | `false`  | Adds action-space margin scaled to the active `size`. Has no effect when `size` is not set.      |

### Events & attributes

OriIcon declares **no custom events** and does not set `inheritAttrs: false`, so native attributes
(`class`, `style`, `data-*`, event listeners, …) fall through directly to the rendered `<i>` element.
A fall-through `aria-label` alone does **not** name the icon: when the `label` prop is unset the
component always sets `aria-hidden="true"`, which removes the element from the accessibility tree and
causes assistive technology to ignore any `aria-label` on it. The `label` prop is the only correct
way to name an icon — it sets `role="img"`, `aria-label`, and removes `aria-hidden` together.

### Slots

| Slot      | Description                                                                                                            |
| --------- | ---------------------------------------------------------------------------------------------------------------------- |
| `default` | Custom icon content. When provided, the `icon` prop is ignored. Slot content is sized 100% × 100% via `.ori-icon > *`. |


# Input

A labelled, accessible text field with `v-model`. State is expressed through real attributes — the
native `disabled`, `aria-invalid` when there is an error, and an `aria-describedby` that points at
the rendered hint or error. The label is wired to the field with `for`/`id` (auto-generated via
`useId` when you don't pass one), and arbitrary native attributes (`name`, `autocomplete`,
`inputmode`, …) fall through to the underlying `<input>`.

This page is laid out by **layer*&#x2A;. The live demos are the &#x2A;*`@oriui/css`** layer — their code
defaults to **HTML** (the standalone classes, also your htmx / Astro / Svelte / plain-HTML usage),
with **Vue** one tab away; the [Framework API](https://oriui.vercel.app/#framework-api&#x29; documents the
&#x2A;*`@oriui/vue`** component. Input is pure CSS — there is no behaviour layer in between.

## Classes

A field is a block wrapper with single-class token utilities — one class repoints one token; no
separate base class is needed. The `ori-color_*` accent drives the focus ring; the idle border is a
neutral, theme-aware blend. The Vue props in [Framework API](https://oriui.vercel.app/#framework-api) map 1:1 to these.

::class-table
---
rows:
  - class: ori-input
    type: Block
    description: Required base class (wrapper div).
  - class: ori-input_*
    type: Style
    description: <b>outline</b> · fill
  - class: ori-color_*
    type: Color
    description: <b>primary</b> · secondary · success · warn · danger · info ·
      surface · background (focus ring accent)
  - class: ori-input_* (size)
    type: Size
    description: xs · sm · <b>md</b> · lg · xl · xxl field height (size sugar on the
      wrapper)
  - class: ori-size-radius_*
    type: Radius
    description: zero · xs · sm · <b>md</b> · lg · xl · rounded (field corners)
  - class: ori-font-size_*
    type: Font
    description: xs · sm · <b>md</b> · lg · xl · xxl (label + field text scale)
  - class: ori-input__label · ori-input__required · ori-input__field ·
      ori-input__hint · ori-input__error
    type: Part
    description: label / required-asterisk / input / helper / error elements
  - class: ori-input_fluid
    type: Layout
    description: full-width (stretches wrapper to 100 %)
  - class: disabled · aria-invalid · aria-describedby
    type: State
    description: real attributes, not classes
---
::

## Variants

Two visual styles — `outline` (default, border visible at rest) and `fill` (tinted background, no
border).

::example
:ori-input{label="Outline" placeholder="Type here" variant="outline"}

:ori-input{label="Fill" placeholder="Type here" variant="fill"}

#vue
```vue
<OriInput v-model="value" label="Outline" placeholder="Type here" variant="outline" />
<OriInput v-model="value" label="Fill" placeholder="Type here" variant="fill" />
```

#html
```html
<div class="ori-input ori-color_primary ori-font-size_md ori-input_outline">
    <label class="ori-input__label" for="f1">Outline</label>
    <input id="f1" placeholder="Type here" class="ori-input__field ori-size-radius_md" />
</div>

<!-- swap the variant: ori-input_outline → ori-input_fill -->
```
::

## Colors

The `ori-color_*` class controls the focus ring (and the danger color inherits for error text).

::example
:ori-input{color="primary" label="primary" placeholder="primary"}

:ori-input{color="secondary" label="secondary" placeholder="secondary"}

:ori-input{color="success" label="success" placeholder="success"}

:ori-input{color="danger" label="danger" placeholder="danger"}

#vue
```vue
<OriInput v-model="value" label="primary" color="primary" />
<OriInput v-model="value" label="danger" color="danger" />
```

#html
```html
<div class="ori-input ori-color_danger ori-font-size_md ori-input_outline">
    <label class="ori-input__label" for="f2">danger</label>
    <input id="f2" class="ori-input__field ori-size-radius_md" />
</div>
```
::

## Sizes

`xs` → `xxl`. The size drives both the field height (`ori-input_*` size sugar on the wrapper) and
the text scale (`ori-font-size_*`).

::example
:ori-input{label="xs" placeholder="Extra small" size="xs"}

:ori-input{label="sm" placeholder="Small" size="sm"}

:ori-input{label="md" placeholder="Medium" size="md"}

:ori-input{label="lg" placeholder="Large" size="lg"}

:ori-input{label="xl" placeholder="Extra large" size="xl"}

#vue
```vue
<OriInput v-model="value" label="sm" size="sm" />
<OriInput v-model="value" label="xl" size="xl" />
```

#html
```html
<!-- size sugar on the wrapper (ori-input_xl); the field inherits the height via --ori-size-action -->
<div class="ori-input ori-color_primary ori-font-size_xl ori-input_outline ori-input_xl">
    <label class="ori-input__label" for="f3">xl</label>
    <input id="f3" class="ori-input__field ori-size-radius_md" />
</div>

<!-- a bare ori-input wrapper is already a valid md field — no size class needed for the default -->
```
::

## Radius

From `zero` (square) through the default `md` to `rounded` (pill-shaped field).

::example
:ori-input{label="zero" placeholder="Square" radius="zero"}

:ori-input{label="sm" placeholder="Small" radius="sm"}

:ori-input{label="md" placeholder="Medium" radius="md"}

:ori-input{label="lg" placeholder="Large" radius="lg"}

:ori-input{label="rounded" placeholder="Pill" radius="rounded"}

#vue
```vue
<OriInput v-model="value" label="zero" radius="zero" />
<OriInput v-model="value" label="rounded" radius="rounded" />
```

#html
```html
<input class="ori-input__field ori-size-radius_zero" />
```
::

## Label, hint & required

`label` renders a `<label>` linked to the field. `hint` renders a helper line below. `required`
adds the real HTML attribute and a visual asterisk (hidden from assistive tech).

::example
  :::ori-input
  ---
  required: true
  hint: We never share it.
  label: Email
  placeholder: you@example.com
  type: email
  ---
  :::

#vue
```vue
<OriInput v-model="email" type="email" label="Email" placeholder="you@example.com" hint="We never share it." required />
```

#html
```html
<div class="ori-input ori-color_primary ori-font-size_md ori-input_outline">
    <label class="ori-input__label" for="email">
        Email<span class="ori-input__required" aria-hidden="true">*</span>
    </label>
    <input
        id="email"
        type="email"
        required
        placeholder="you@example.com"
        aria-describedby="email-hint"
        class="ori-input__field ori-size-radius_md"
    />
    <p id="email-hint" class="ori-input__hint">We never share it.</p>
</div>
```
::

## States

`disabled` uses the real attribute. `error` renders a `role="alert"` message and sets
`aria-invalid`. `invalid` flips `aria-invalid` without a message (for external validation).

::example
  :::ori-input{disabled label="Disabled" placeholder="Cannot edit"}
  :::

  :::ori-input
  ---
  invalid: true
  label: Invalid (no message)
  placeholder: Flagged externally
  ---
  :::

  :::ori-input
  ---
  error: Enter a valid email address.
  label: With error
  placeholder: you@example.com
  type: email
  ---
  :::

#vue
```vue
<OriInput v-model="value" label="Disabled" disabled />
<OriInput v-model="value" label="Invalid (no message)" invalid />
<OriInput v-model="email" label="With error" error="Enter a valid email address." />
```

#html
```html
<!-- disabled -->
<input class="ori-input__field …" disabled />

<!-- invalid without message -->
<input class="ori-input__field …" aria-invalid="true" />

<!-- error: message gets role=alert and is referenced by aria-describedby -->
<input class="ori-input__field …" aria-invalid="true" aria-describedby="email-error" />
<p id="email-error" class="ori-input__error" role="alert">Enter a valid email address.</p>
```
::

## Fluid

`fluid` stretches the wrapper to the full width of its container.

::example
  :::ori-input{fluid label="Full width" placeholder="Stretches to container"}
  :::

#vue
```vue
<OriInput v-model="value" label="Full width" fluid />
```

#html
```html
<div class="ori-input ori-input_fluid …">…</div>
```
::

## Input types

`type` maps directly to the native `<input type="">` — use `email`, `password`, `search`, `tel`,
`url`, `number`, etc.

::example
:ori-input{label="Password" placeholder="Enter password" type="password"}

:ori-input{label="Search" placeholder="Search…" type="search"}

:ori-input{label="Number" placeholder="0" type="number"}

#vue
```vue
<OriInput v-model="password" type="password" label="Password" placeholder="Enter password" />
<OriInput v-model="query" type="search" label="Search" placeholder="Search…" />
```

#html
```html
<input type="password" class="ori-input__field …" /> <input type="search" class="ori-input__field …" />
```
::

## Common patterns

A real-world sign-in form — label, type, hint, required, and error compose freely.

::example
  :::ori-input
  ---
  required: true
  label: Email
  placeholder: you@example.com
  type: email
  ---
  :::

  :::ori-input
  ---
  required: true
  hint: Use a mix of letters, numbers and symbols.
  label: Password
  placeholder: Min 8 characters
  type: password
  ---
  :::

#vue
```vue
<form style="display: flex; flex-direction: column; gap: 1rem; max-width: 24rem">
    <OriInput v-model="email" type="email" label="Email" placeholder="you@example.com" required />
    <OriInput
        v-model="password"
        type="password"
        label="Password"
        placeholder="Min 8 characters"
        hint="Use a mix of letters, numbers and symbols."
        required
    />
</form>
```

#html
```html
<form style="display: flex; flex-direction: column; gap: 1rem; max-width: 24rem">
    <div class="ori-input ori-color_primary ori-font-size_md ori-input_outline">
        <label class="ori-input__label" for="si-email">
            Email<span class="ori-input__required" aria-hidden="true">*</span>
        </label>
        <input
            id="si-email"
            type="email"
            required
            placeholder="you@example.com"
            class="ori-input__field ori-size-radius_md"
        />
    </div>
    <div class="ori-input ori-color_primary ori-font-size_md ori-input_outline">
        <label class="ori-input__label" for="si-pw">
            Password<span class="ori-input__required" aria-hidden="true">*</span>
        </label>
        <input
            id="si-pw"
            type="password"
            required
            placeholder="Min 8 characters"
            aria-describedby="si-pw-hint"
            class="ori-input__field ori-size-radius_md"
        />
        <p id="si-pw-hint" class="ori-input__hint">Use a mix of letters, numbers and symbols.</p>
    </div>
</form>
```
::

## Accessibility

The accessibility contract holds across every layer — the standalone classes and the Vue component
render the same attributes and ARIA wiring.

- `label` is associated with the field via `for`/`id`; the id is auto-generated (`useId`) when you
  don't pass one, so the association holds even without an explicit `id` prop.
- `hint` and `error` are wired through `aria-describedby`, referencing only the element that is
  actually rendered (`error` supersedes `hint`). Pass extra ids with `describedby` to reference
  additional descriptions (e.g. a shared form note).
- `error` sets `aria-invalid="true"` and announces via `role="alert"`; `invalid` flips
  `aria-invalid` on its own for external validation flows.
- Uses the real `disabled` attribute and native `required`; the focus ring is always visible and
  switches to the `danger` color when invalid.
- All native attributes (`name`, `autocomplete`, `inputmode`, `maxlength`, …) fall through to the
  underlying `<input>` — OriInput stays out of the way.

| Key   | Action                                |
| ----- | ------------------------------------- |
| `Tab` | Moves focus to / away from the field. |

## Framework API

The props, events, and slots of the **Vue** component. The standalone CSS layer has no component
API — its surface is the [classes](https://oriui.vercel.app/#classes) above. (Svelte bindings are planned.)

### Props

| Prop          | Type                 | Default     | Description                                                                                               |
| ------------- | -------------------- | ----------- | --------------------------------------------------------------------------------------------------------- |
| `color`       | `ThemeColor`         | `'primary'` | Accent color for focus ring: primary · secondary · success · warn · danger · info · surface · background. |
| `describedby` | `string`             | —           | Extra element id(s) appended to `aria-describedby` (e.g. a shared form note).                             |
| `disabled`    | `boolean`            | `false`     | Real `disabled` attribute; blocks interaction and dims the field.                                         |
| `error`       | `string`             | —           | Error message rendered below the field (`role="alert"`); also sets `aria-invalid="true"`.                 |
| `fluid`       | `boolean`            | `false`     | Full-width — stretches wrapper to 100 % of its container.                                                 |
| `hint`        | `string`             | —           | Helper text below the field; hidden while `error` is shown.                                               |
| `id`          | `string`             | —           | Explicit id for the `<input>`; auto-generated via `useId` when omitted.                                   |
| `invalid`     | `boolean`            | `false`     | Sets `aria-invalid="true"` without rendering an error message (for external validation).                  |
| `label`       | `string`             | —           | Visible `<label>` text, wired to the field via `for`/`id`.                                                |
| `placeholder` | `string`             | —           | Native placeholder text.                                                                                  |
| `radius`      | `RadiusSize`         | `'md'`      | Corner radius of the field (`zero` · xs · sm · md · lg · xl · rounded).                                   |
| `required`    | `boolean`            | `false`     | Native `required` attribute; also renders a visual asterisk (`aria-hidden`).                              |
| `size`        | `ActionSize`         | `'md'`      | Field height + text scale (`xs` · sm · md · lg · xl · `xxl`).                                             |
| `type`        | `string`             | `'text'`    | Native input type (`text`, `email`, `password`, `search`, `tel`, `url`, `number`, …).                     |
| `variant`     | `'fill' | 'outline'` | `'outline'` | Visual style: `outline` (border) or `fill` (tinted background).                                           |

### Events & attributes

`v-model` binds to a `string` via `defineModel<string>()` — it reads the `modelValue` prop and emits
`update:modelValue` on input, so you use it like any controlled field:

```vue
<OriInput v-model="myValue" label="Name" />
```

OriInput sets `inheritAttrs: false` and spreads `$attrs` onto the underlying `<input>`, so native
attributes and listeners pass through directly to the field element — not the wrapper `<div>`:

- Attributes: `name`, `autocomplete`, `inputmode`, `maxlength`, `minlength`, `pattern`,
  `spellcheck`, `readonly`, …
- Listeners: `@input`, `@change`, `@focus`, `@blur`, `@keydown`, …

### Slots

OriInput exposes no named slots.

| Slot   | Description           |
| ------ | --------------------- |
| (none) | No slots are defined. |


# Join

A thin wrapper that collapses the shared radii and borders of adjacent controls so they read as one
segmented unit — button groups, input+button combos, segmented toolbars. No visual styling of its
own: all colour, size, and variant tokens live on the children.

The examples are organised by **layer**: the [class reference](https://oriui.vercel.app/#classes&#x29; is the standalone
&#x2A;*`@oriui/css`** layer, and the [Framework API](https://oriui.vercel.app/#framework-api&#x29; is the &#x2A;*`@oriui/vue`** component. Every
example is live — flip its code between **HTML** (the standalone classes, also your htmx / Astro / Svelte /
plain-HTML usage), **Vue**; HTML is the default.

## Classes

::class-table
---
rows:
  - class: ori-join
    type: Block
    description: Required base class. inline-flex container; collapses shared radii
      and borders between adjacent children.
  - class: ori-join_vertical
    type: Modifier
    description: Stack children vertically instead of horizontally. Collapses block
      edges instead of inline edges.
  - class: role=group
    type: Semantics
    description: Always present on the root element. Wrap logically related
      controls; supply aria-label or aria-labelledby so screen readers announce
      the group purpose.
---
::

## Horizontal button group

Three outline buttons joined into one segmented control. The shared interior borders collapse to a
single 1 px line; the outer corners keep their radius.

::example
  :::ori-join{ariaLabel="Text alignment"}
  :ori-button{text="Left" variant="outline"}

  :ori-button{text="Center" variant="outline"}

  :ori-button{text="Right" variant="outline"}
  :::

#vue
```vue
<OriJoin aria-label="Text alignment">
    <OriButton variant="outline" text="Left" />
    <OriButton variant="outline" text="Center" />
    <OriButton variant="outline" text="Right" />
</OriJoin>
```

#html
```html
<div class="ori-join" role="group" aria-label="Text alignment">
    <button class="ori-button ori-variant_outline ori-color_primary">Left</button>
    <button class="ori-button ori-variant_outline ori-color_primary">Center</button>
    <button class="ori-button ori-variant_outline ori-color_primary">Right</button>
</div>
```
::

## Input + button (search)

An input field joined with a submit button — the canonical search-box pattern. The shared border
between the field and the button merges into one line.

::example
  :::ori-join{ariaLabel="Search"}
  :ori-input{ariaLabel="Search query" placeholder="Search…"}

  :ori-button{text="Go" variant="fill"}
  :::

#vue
```vue
<OriJoin aria-label="Search">
    <OriInput placeholder="Search…" aria-label="Search query" />
    <OriButton variant="fill" text="Go" />
</OriJoin>
```

#html
```html
<div class="ori-join" role="group" aria-label="Search">
    <input class="ori-input" type="search" placeholder="Search…" aria-label="Search query" />
    <button class="ori-button ori-variant_fill ori-color_primary">Go</button>
</div>
```
::

## Vertical

`vertical` stacks children in a column and collapses the block edges instead of the inline edges.

::example
  :::ori-join{vertical ariaLabel="View mode"}
  :ori-button{text="List" variant="outline"}

  :ori-button{text="Grid" variant="outline"}

  :ori-button{text="Table" variant="outline"}
  :::

#vue
```vue
<OriJoin :vertical="true" aria-label="View mode">
    <OriButton variant="outline" text="List" />
    <OriButton variant="outline" text="Grid" />
    <OriButton variant="outline" text="Table" />
</OriJoin>
```

#html
```html
<div class="ori-join ori-join_vertical" role="group" aria-label="View mode">
    <button class="ori-button ori-variant_outline ori-color_primary">List</button>
    <button class="ori-button ori-variant_outline ori-color_primary">Grid</button>
    <button class="ori-button ori-variant_outline ori-color_primary">Table</button>
</div>
```
::

## Common patterns

A tonal colour swatch group and a quantity stepper — two everyday compositions showing how variant
and color on the children drive all the visual weight.

### Colour swatch group

::example
  :::ori-join{ariaLabel="Highlight colour"}
  :ori-button{color="danger" text="Red" variant="tonal"}

  :ori-button{color="warn" text="Amber" variant="tonal"}

  :ori-button{color="success" text="Green" variant="tonal"}

  :ori-button{color="info" text="Blue" variant="tonal"}
  :::

#vue
```vue
<!-- Colour swatch toolbar — tonal buttons, each its own semantic colour -->
<OriJoin aria-label="Highlight colour">
    <OriButton variant="tonal" color="danger" text="Red" />
    <OriButton variant="tonal" color="warn" text="Amber" />
    <OriButton variant="tonal" color="success" text="Green" />
    <OriButton variant="tonal" color="info" text="Blue" />
</OriJoin>
```

#html
```html
<div class="ori-join" role="group" aria-label="Highlight colour">
    <button class="ori-button ori-variant_tonal ori-color_danger">Red</button>
    <button class="ori-button ori-variant_tonal ori-color_warn">Amber</button>
    <button class="ori-button ori-variant_tonal ori-color_success">Green</button>
    <button class="ori-button ori-variant_tonal ori-color_info">Blue</button>
</div>
```
::

### Quantity stepper

::example
  :::ori-join{ariaLabel="Quantity"}
  :ori-button{ariaLabel="Decrease quantity" text="−" variant="outline"}

    ::::ori-input{:value='1' ariaLabel="Current quantity"}
    ::::

  :ori-button{ariaLabel="Increase quantity" text="+" variant="outline"}
  :::

#vue
```vue
<!-- Quantity stepper: decrement · value display · increment -->
<OriJoin aria-label="Quantity">
    <OriButton variant="outline" text="−" aria-label="Decrease quantity" />
    <OriInput :value="1" aria-label="Current quantity" style="width: 4rem; text-align: center" />
    <OriButton variant="outline" text="+" aria-label="Increase quantity" />
</OriJoin>
```

#html
```html
<div class="ori-join" role="group" aria-label="Quantity">
    <button class="ori-button ori-variant_outline ori-color_primary" aria-label="Decrease quantity">−</button>
    <input
        class="ori-input"
        type="number"
        value="1"
        aria-label="Current quantity"
        style="width: 4rem; text-align: center"
    />
    <button class="ori-button ori-variant_outline ori-color_primary" aria-label="Increase quantity">+</button>
</div>
```
::

## Accessibility

The accessibility contract holds across every layer — the standalone classes and the Vue component
render the same markup.

- The root element always carries `role="group"`. A group that contains multiple controls **should**
  have an accessible name so screen readers announce its purpose. Pass `aria-label` (or
  `aria-labelledby` referencing a visible heading) directly on `<OriJoin>` — it falls through to the
  root element unchanged.
- Children keep their own roles, labels, and keyboard behaviour. The join wrapper adds no tab stop
  and intercepts no keys.
- When a child is focused or hovered its `z-index` is raised to `1` so its full `:focus-visible`
  ring is not clipped by the adjacent collapsed border.
- Icon-only children still need their own `aria-label`.

| Key        | Action                                            |
| ---------- | ------------------------------------------------- |
| `Tab`      | Moves focus between child controls.               |
| `Enter`    | Activates the focused child control.              |
| `Space`    | Activates a focused button child.                 |
| Arrow keys | Within a radiogroup child, moves between options. |

## Framework API

The props, events, and slots of the **Vue** component. The standalone CSS layer has no component
API — its surface is the [classes](https://oriui.vercel.app/#classes) above.

### Props

| Prop       | Type              | Default | Description                                                                         |
| ---------- | ----------------- | ------- | ----------------------------------------------------------------------------------- |
| `as`       | `string | object` | `'div'` | Element or component to render. Accepts any HTML tag name or a Component reference. |
| `vertical` | `boolean`         | `false` | Stack children in a column and collapse block edges instead of inline edges.        |

### Events & attributes

OriJoin declares **no custom events** and does not set `inheritAttrs: false`, so native attributes
(`aria-label`, `aria-labelledby`, `id`, `class`, `style`, `data-*`) fall through to the root
element. Pass `aria-label` here to name the group.

### Slots

| Slot      | Description                                                                                              |
| --------- | -------------------------------------------------------------------------------------------------------- |
| `default` | The controls to group — buttons, inputs, or any element that carries `ori-button` / `ori-input` classes. |

### Polymorphic (`as`)

Render any tag or component. Useful when the join is semantically a toolbar (`role="toolbar"` via
`aria-label` on an `<OriJoin as="div">`) or when a router wrapper is needed.

```vue
<!-- Use a semantic toolbar role for a group of action buttons -->
<OriJoin as="div" role="toolbar" aria-label="Formatting options">
    <OriButton variant="outline" text="Bold" aria-pressed="false" />
    <OriButton variant="outline" text="Italic" aria-pressed="false" />
    <OriButton variant="outline" text="Underline" aria-pressed="false" />
</OriJoin>
```


# Kbd

A keyboard-key chip — a semantic `<kbd>` element styled as a monospace bordered chip. Use it to
represent individual keys, modifier keys, or multi-key shortcuts inline in prose or UI hints.

The examples are organised by **layer**: the [class reference](https://oriui.vercel.app/#classes&#x29; is the standalone
&#x2A;*`@oriui/css`** layer, and the [Framework API](https://oriui.vercel.app/#framework-api&#x29; is the &#x2A;*`@oriui/vue`** component. Every
example is live — flip its code between **HTML** (the standalone classes, also your htmx / Astro / Svelte /
plain-HTML usage), **Vue**; HTML is the default.

## Classes

A kbd chip is a single block class. There are no size, color, or variant utilities — the chip
inherits its color from the surrounding text and its radius from the baked `sm` default.

::class-table
---
rows:
  - class: ori-kbd
    type: Block
    description: Required base class. Renders as an inline-flex monospace chip with
      a bottom-heavy border and sm radius baked in.
---
::

## Single key

Pass the key label via the `text` prop or the default slot.

::example
:ori-kbd{text="Esc"}

:ori-kbd{text="Enter"}

:ori-kbd{text="Tab"}

:ori-kbd{text="Space"}

#vue
```vue
<OriKbd text="Esc" />
<OriKbd text="Enter" />
<OriKbd text="Tab" />
<OriKbd text="Space" />
```

#html
```html
<kbd class="ori-kbd">Esc</kbd>
<kbd class="ori-kbd">Enter</kbd>
<kbd class="ori-kbd">Tab</kbd>
<kbd class="ori-kbd">Space</kbd>
```
::

## Shortcut combo

Compose multiple chips to represent a keyboard shortcut. Separate them with a literal `+` in
between.

::example
:ori-kbd{text="Ctrl"} + :ori-kbd{text="K"}

#vue
```vue
<OriKbd text="Ctrl" />
+
<OriKbd text="K" />
```

#html
```html
<kbd class="ori-kbd">Ctrl</kbd> + <kbd class="ori-kbd">K</kbd>
```
::

::example
:ori-kbd{text="Ctrl"} + :ori-kbd{text="Shift"} + :ori-kbd{text="P"}

#vue
```vue
<OriKbd text="Ctrl" />
+
<OriKbd text="Shift" />
+
<OriKbd text="P" />
```

#html
```html
<kbd class="ori-kbd">Ctrl</kbd> + <kbd class="ori-kbd">Shift</kbd> + <kbd class="ori-kbd">P</kbd>
```
::

## Inline in text

The chip is `inline-flex` and tracks the surrounding font size, so it flows naturally inside a
sentence or tooltip hint.

::example
Press :ori-kbd{text="Esc"} to close the dialog.

#vue
```vue
<p>Press <OriKbd text="Esc" /> to close the dialog.</p>
```

#html
```html
<p>Press <kbd class="ori-kbd">Esc</kbd> to close the dialog.</p>
```
::

## Via slot

When the key label is dynamic or needs rich content, use the default slot instead of the `text`
prop. The slot replaces the prop — if both are supplied the slot wins.

::example
:ori-kbd{text="⌘"}

:ori-kbd{text="⇧"}

:ori-kbd{text="⌥"}

#vue
```vue
<!-- slot form — useful when the label is dynamic -->
<OriKbd>⌘</OriKbd>
<OriKbd>⇧</OriKbd>
<OriKbd>⌥</OriKbd>
```

#html
```html
<kbd class="ori-kbd">⌘</kbd>
<kbd class="ori-kbd">⇧</kbd>
<kbd class="ori-kbd">⌥</kbd>
```
::

## Common patterns

### Command palette hint

A two-column shortcut list — the pattern used in command palettes and help overlays.

::example
:ori-kbd{text="Ctrl"} + :ori-kbd{text="K"} opens the command palette.

:ori-kbd{text="Ctrl"} + :ori-kbd{text="/"} toggles comments.

:ori-kbd{text="Ctrl"} + :ori-kbd{text="S"} saves the file.

#vue
```vue
<p><OriKbd text="Ctrl" /> + <OriKbd text="K" /> opens the command palette.</p>
<p><OriKbd text="Ctrl" /> + <OriKbd text="/" /> toggles comments.</p>
<p><OriKbd text="Ctrl" /> + <OriKbd text="S" /> saves the file.</p>
```

#html
```html
<p><kbd class="ori-kbd">Ctrl</kbd> + <kbd class="ori-kbd">K</kbd> opens the command palette.</p>
<p><kbd class="ori-kbd">Ctrl</kbd> + <kbd class="ori-kbd">/</kbd> toggles comments.</p>
<p><kbd class="ori-kbd">Ctrl</kbd> + <kbd class="ori-kbd">S</kbd> saves the file.</p>
```
::

## Accessibility

The accessibility contract holds across every layer — the standalone classes and the Vue component
render the same markup.

- Renders a real `<kbd>` element by default. The `<kbd>` element is the correct semantic choice for
  keyboard input and is recognized by assistive technology as user input / a key name.
- The chip is purely presentational — it carries no `role`, `tabindex`, or ARIA attributes of its
  own. The surrounding text provides context.
- When representing a multi-key shortcut, each key gets its own `<kbd>` element — this is the
  pattern specified by the HTML spec for chords.
- No keyboard interaction is defined; the chip is not interactive.

## Framework API

The props, events, and slots of the **Vue** component. The standalone CSS layer has no component
API — its surface is the [classes](https://oriui.vercel.app/#classes) above. (Svelte bindings are planned.)

### Props

| Prop   | Type              | Default | Description                                                                                     |
| ------ | ----------------- | ------- | ----------------------------------------------------------------------------------------------- |
| `as`   | `string | object` | `'kbd'` | HTML tag name or component to render. Override only when wrapping a non-`<kbd>` element.        |
| `text` | `string`          | —       | Key label. Fallback content for the default slot — if the slot is provided it takes precedence. |

### Events & attributes

OriKbd declares **no custom events** and does not set `inheritAttrs: false`, so native attributes
(`class`, `style`, `id`, `data-*`, event listeners, …) fall through to the rendered element.

### Slots

| Slot      | Description                                                                        |
| --------- | ---------------------------------------------------------------------------------- |
| `default` | Key label. When provided, replaces the `text` prop. Accepts text or inline markup. |


# Link

An inline prose link — the right choice when a destination lives in running text. Distinct from
`OriButton` rendered `as="a"`: a button that navigates is still a button; a link in a sentence is
`OriLink`. Underlined by default (the affordance survives without color), with a `_hover` mode that
hides the underline at rest and reveals it on hover. A visible `:focus-visible` ring uses the same
color as the text.

The examples are organised by **layer**: the [class reference](https://oriui.vercel.app/#classes&#x29; is the standalone
&#x2A;*`@oriui/css`** layer, and the [Framework API](https://oriui.vercel.app/#framework-api&#x29; is the &#x2A;*`@oriui/vue`** component. Every
example is live — flip its code between **HTML** (the standalone classes, also your htmx / Astro / Svelte /
plain-HTML usage), **Vue**; HTML is the default.

## Classes

A link is a block class plus single-class token utilities — one class repoints one token, no base
class needed. The Vue props in [Framework API](https://oriui.vercel.app/#framework-api) map 1:1 to these.

::class-table
---
rows:
  - class: ori-link
    type: Block
    description: Required base class. Underlined, inherits currentcolor, cursor pointer.
  - class: ori-color_*
    type: Color
    description: primary · secondary · success · warn · danger · info · surface —
      omit to inherit currentcolor from the parent
  - class: ori-link_hover
    type: Modifier
    description: Removes the underline at rest; adds it on hover (pointer device only).
---
::

## Default

An unstyled link in running text — inherits `currentcolor` from the parent, always underlined.

::example
  :::ori-link{href="https://oriui.vercel.app/overview/introduction"}
  Read the introduction
  :::

#vue
```vue
<OriLink href="/overview/introduction">Read the introduction</OriLink>
```

#html
```html
<a class="ori-link" href="/overview/introduction">Read the introduction</a>
```
::

## Colors

Apply a semantic role with `ori-color_*`. The color drives both the text and the focus ring.

::example
  :::ori-link{color="primary" href="https://oriui.vercel.app/#"}
  primary
  :::

  :::ori-link{color="secondary" href="https://oriui.vercel.app/#"}
  secondary
  :::

  :::ori-link{color="success" href="https://oriui.vercel.app/#"}
  success
  :::

  :::ori-link{color="warn" href="https://oriui.vercel.app/#"}
  warn
  :::

  :::ori-link{color="danger" href="https://oriui.vercel.app/#"}
  danger
  :::

  :::ori-link{color="info" href="https://oriui.vercel.app/#"}
  info
  :::

#vue
```vue
<OriLink href="#" color="primary">primary</OriLink>
<OriLink href="#" color="secondary">secondary</OriLink>
<OriLink href="#" color="success">success</OriLink>
<OriLink href="#" color="warn">warn</OriLink>
<OriLink href="#" color="danger">danger</OriLink>
<OriLink href="#" color="info">info</OriLink>
```

#html
```html
<!-- swap the color class: ori-color_primary → _secondary / _success / _warn / _danger / _info -->
<a class="ori-link ori-color_primary" href="#">primary</a>
<a class="ori-link ori-color_danger" href="#">danger</a>
```
::

## Hover underline

`hover` (/ `ori-link_hover`) removes the underline at rest and reveals it only when the pointer
hovers. Useful in navigation clusters or card bodies where a permanent underline feels noisy.

::example
  :::ori-link{hover color="primary" href="https://oriui.vercel.app/#"}
  Underline only on hover
  :::

#vue
```vue
<OriLink href="#" color="primary" hover>Underline only on hover</OriLink>
```

#html
```html
<a class="ori-link ori-link_hover ori-color_primary" href="#">Underline only on hover</a>
```
::

## External link

`external` sets `target="_blank"` and `rel="noopener noreferrer"` automatically — no attributes
to remember.

::example
  :::ori-link{external color="primary" href="https://github.com"}
  oriUI on GitHub
  :::

#vue
```vue
<OriLink href="https://github.com" color="primary" external>oriUI on GitHub</OriLink>
```

#html
```html
<a class="ori-link ori-color_primary" href="https://github.com" target="_blank" rel="noopener noreferrer">
    oriUI on GitHub
</a>
```
::

## Common patterns

A prose paragraph with inline links — the everyday composition.

::example
  :::ori-link
  ---
  color: primary
  href: https://oriui.vercel.app/overview/introduction
  ---
  Get started
  :::

  :::ori-link
  ---
  external: true
  hover: true
  color: primary
  href: https://github.com
  ---
  View on GitHub
  :::

#vue
```vue
<p>
    Read the
    <OriLink href="/overview/introduction" color="primary">Get started</OriLink>
    guide, or browse the source on
    <OriLink href="https://github.com" color="primary" external hover>GitHub</OriLink>.
</p>
```

#html
```html
<p>
    Read the
    <a class="ori-link ori-color_primary" href="/overview/introduction">Get started</a>
    guide, or browse the source on
    <a
        class="ori-link ori-link_hover ori-color_primary"
        href="https://github.com"
        target="_blank"
        rel="noopener noreferrer"
        >GitHub</a
    >.
</p>
```
::

## Accessibility

The accessibility contract holds across every layer — the standalone classes and the Vue component
render the same attributes.

- Renders a real `<a>` by default; `as` accepts any tag or component (e.g. a router link). Pass
  `href` so the element is keyboard-reachable and announced as a link by assistive technology. A
  link without `href` is not focusable by default — add `tabindex="0"` if needed.
- `external` injects `rel="noopener noreferrer"` for security (prevents the opened page from
  accessing `window.opener`) alongside `target="_blank"`.
- Visible `:focus-visible` outline uses `var(--ori-color)` (same as the text) with a `2px` offset
  so it contrasts the surrounding text surface.
- Color is never the sole differentiator — the default underline ensures the link is perceivable
  without relying on hue alone (WCAG 1.4.1).

| Key     | Action                        |
| ------- | ----------------------------- |
| `Enter` | Follows the link.             |
| `Tab`   | Moves focus to the next link. |

## Framework API

The props, events, and slots of the **Vue** component. The standalone CSS layer has no component
API — its surface is the [classes](https://oriui.vercel.app/#classes) above. (Svelte bindings are planned.)

### Props

| Prop       | Type              | Default | Description                                                                        |
| ---------- | ----------------- | ------- | ---------------------------------------------------------------------------------- |
| `as`       | `string | object` | `'a'`   | HTML tag name or component to render (e.g. `'a'`, a router-link component).        |
| `color`    | `ThemeColor`      | —       | Semantic color role. Omit to inherit `currentcolor` from the parent.               |
| `external` | `boolean`         | `false` | Sets `target="_blank"` and `rel="noopener noreferrer"` on the rendered element.    |
| `hover`    | `boolean`         | `false` | Hides the underline at rest; shows it only on hover (`ori-link_hover`).            |
| `href`     | `string`          | —       | The link destination. Required for the element to be keyboard-focusable as a link. |

`ThemeColor`: `'primary' | 'secondary' | 'success' | 'warn' | 'danger' | 'info' | 'surface' | 'background'`

### Events & attributes

OriLink declares **no custom events** and does not set `inheritAttrs: false`, so native listeners
(`@click`, `@focus`, …) and attributes (`aria-label`, `download`, `data-*`, …) fall through to the
rendered element — the tag given by `as`.

### Slots

| Slot      | Description                      |
| --------- | -------------------------------- |
| `default` | The link text or inline content. |

### Polymorphic (`as`)

Render any tag or component. The most common alternative is a router-link (Vue Router or
NuxtLink) — pass the component reference and use its own navigation props alongside `href`.

::example
  :::ori-link
  ---
  hover: true
  color: primary
  href: https://oriui.vercel.app/components/button
  ---
  Go to Components
  :::

#vue
```vue
<!-- plain anchor (default) -->
<OriLink href="/components/button" color="primary">Go to Components</OriLink>

<!-- with a router link -->
<OriLink :as="RouterLink" to="/components/button" color="primary">Go to Components</OriLink>
```

#html
```html
<a class="ori-link ori-color_primary" href="/components/button">Go to Components</a>
```
::


# Menu

A WAI-ARIA menu button: a trigger opens a **roving-tabindex*&#x2A; action list. Unlike the Popover, open/close,
focus movement, and click-outside dismissal are driven entirely by the **`@oriui/headless` menu
machine** in JavaScript, not the Popover API — so the panel is not top-layer and carries a z-index. The
panel is still placed with the same **CSS Anchor Positioning** primitive as the Popover (`ori-anchored`),
zero positioning JS.

The examples are organised by **layer**: the [class reference](https://oriui.vercel.app/#classes&#x29; is the standalone
&#x2A;*`@oriui/css`** layer, and the [Framework API](https://oriui.vercel.app/#framework-api&#x29; is the &#x2A;*`@oriui/vue`** component. Every
example is live — flip its code between **HTML** (the standalone classes, also your htmx / Astro / Svelte /
plain-HTML usage), **Vue**, and **Svelte** (`@oriui/headless/svelte`); HTML is the default.

## Classes

A menu is the `.ori-menu` surface class plus the shared `.ori-anchored` placement primitive (and one
placement modifier); items are `.ori-menu__item`. The `.ori-anchored*` classes are the same primitive
documented on the [Popover page](https://oriui.vercel.app/components/popover#classes) — placement, the collision flip, and the
`--ori-anchor` / `--ori-anchored-gap` custom props are shared, not duplicated here.

::class-table
---
rows:
  - class: ori-menu
    type: Block
    description: "The panel surface: sizing, padding, border, surface background +
      ori-shadow-lg + a z-index (not top-layer, unlike Popover). Composed with
      .ori-anchored for placement."
  - class: ori-anchored / ori-anchored_*
    type: Placement base
    description: Shared floating-panel placement primitive — see the Popover class
      reference for the full modifier list.
  - class: ori-menu__item
    type: Part
    description: One action row (role=menuitem). Highlight follows roving focus /
      pointer hover via [data-highlighted].
  - class: aria-disabled / data-highlighted
    type: State
    description: real attributes, not classes — a disabled item is skipped by roving
      navigation.
---
::

## Basic

Open the menu and use the Arrow keys — focus moves between items with **roving tabindex** (one item is
`tabindex=0` at a time), not `aria-activedescendant`. Click an item, or press `Enter`/`Space` on the
highlighted one, to select and close.

::example
:menu-demo

#vue
```vue
<OriMenu
    :items="[
        { value: 'new', label: 'New file' },
        { value: 'open', label: 'Open…' },
        { value: 'delete', label: 'Delete' }
    ]"
    @select="onSelect"
>
    <template #trigger="{ props }">
        <OriButton v-bind="props" text="Actions" variant="tonal" />
    </template>
</OriMenu>
```

#html
```html
<!-- Structure only — the JS engine (roving tabindex, open/close, click-outside) is not shown here. -->
<button
    id="menu-1-trigger"
    type="button"
    style="anchor-name: --menu-1"
    aria-haspopup="menu"
    aria-controls="menu-1"
    aria-expanded="false"
>
    Actions
</button>
<div
    id="menu-1"
    role="menu"
    tabindex="-1"
    class="ori-menu ori-anchored ori-anchored_bottom-start"
    style="--ori-anchor: --menu-1"
    aria-labelledby="menu-1-trigger"
    hidden
>
    <div role="menuitem" tabindex="-1" class="ori-menu__item">New file</div>
    <div role="menuitem" tabindex="-1" class="ori-menu__item">Open…</div>
    <div role="menuitem" tabindex="-1" class="ori-menu__item">Delete</div>
</div>
```

#svelte
```svelte
<script>
    import { useMenu } from '@oriui/headless/svelte';

    // No styled Svelte component yet — drive the roving-tabindex menu with @oriui/headless/svelte.
    let contentEl;
    const { open, highlightedValue, items, triggerProps, contentProps, getItemProps } = useMenu({
        id: 'actions',
        items: [
            { value: 'new', label: 'New file' },
            { value: 'open', label: 'Open…' },
            { value: 'delete', label: 'Delete' }
        ],
        onSelect: (value) => console.log(value)
    });

    // Roving tabindex: move real DOM focus to the highlighted item (a projection can't touch the DOM).
    // Full parity also wires click-outside + focus-return — see OriMenu for the complete host.
    $effect(() => {
        if ($open && $highlightedValue != null) contentEl?.querySelector('[data-highlighted]')?.focus();
    });
</script>

<button {...$triggerProps} class="ori-button ori-variant_tonal ori-color_primary" style="anchor-name: --actions">
    Actions
</button>

<div
    {...$contentProps}
    bind:this={contentEl}
    class="ori-menu ori-anchored ori-anchored_bottom-start"
    style="--ori-anchor: --actions"
>
    {#each $items as item, i}
        <div {...$getItemProps(item, i)} class="ori-menu__item">{item.label ?? item.value}</div>
    {/each}
</div>
```
::

## Placements

Twelve placements — `bottom-start` is the default. A bare side (`top` / `bottom` / `left` / `right`)
centers on the cross axis; `-start` / `-end` align to the trigger's start / end edge (logical,
RTL-aware). Same placement classes and collision-flip logic as the Popover, since both compose
`.ori-anchored`.

::example
:menu-demo{placement="top"}

:menu-demo{placement="bottom"}

:menu-demo{placement="right"}

#vue
```vue
<OriMenu :items="items" placement="top" @select="onSelect">
    <template #trigger="{ props }">
        <OriButton v-bind="props" text="top" variant="tonal" />
    </template>
</OriMenu>
<OriMenu :items="items" placement="right" @select="onSelect">
    <template #trigger="{ props }">
        <OriButton v-bind="props" text="right" variant="tonal" />
    </template>
</OriMenu>
```

#html
```html
<!-- swap the modifier: ori-anchored_top / _top-start / _top-end / _bottom / _bottom-start / _bottom-end / _left / _left-start / _left-end / _right / _right-start / _right-end -->
<div
    id="menu-2"
    role="menu"
    tabindex="-1"
    class="ori-menu ori-anchored ori-anchored_top"
    style="--ori-anchor: --menu-2"
    hidden
>
    <div role="menuitem" tabindex="-1" class="ori-menu__item">New file</div>
</div>
```
::

## Disabled item

A disabled item is `aria-disabled`, styled dimmed, and skipped by roving navigation and typeahead — it
can't be highlighted or selected.

::example
:menu-demo

#vue
```vue
<OriMenu
    :items="[
        { value: 'new', label: 'New file' },
        { value: 'rename', label: 'Rename', disabled: true },
        { value: 'delete', label: 'Delete' }
    ]"
    @select="onSelect"
>
    <template #trigger="{ props }">
        <OriButton v-bind="props" text="Actions" variant="tonal" />
    </template>
</OriMenu>
```

#html
```html
<div role="menuitem" tabindex="-1" class="ori-menu__item" aria-disabled="true">Rename</div>
```
::

## Custom item content

Override the `#item` slot for icons, shortcuts, or any richer row content — the default renders
`label ?? value`.

::example
:menu-demo

#vue
```vue
<OriMenu :items="items" @select="onSelect">
    <template #trigger="{ props }">
        <OriButton v-bind="props" text="Actions" variant="tonal" />
    </template>
    <template #item="{ item }">
        <span style="display: flex; justify-content: space-between; width: 100%">
            <span>{{ item.label }}</span>
            <span style="opacity: 0.6; font-size: 0.85em" aria-hidden="true">⌘K</span>
        </span>
    </template>
</OriMenu>
```
::

## Common patterns

A toolbar "more actions" button — a typical menu-button use case.

::example
:menu-demo{placement="bottom-end"}

#vue
```vue
<OriMenu
    :items="[
        { value: 'edit', label: 'Edit' },
        { value: 'duplicate', label: 'Duplicate' },
        { value: 'archive', label: 'Archive' },
        { value: 'delete', label: 'Delete' }
    ]"
    placement="bottom-end"
    @select="onAction"
>
    <template #trigger="{ props }">
        <OriButton v-bind="props" icon="M12 8a2 2 0 100-4 2 2 0 000 4zm0 6a2 2 0 100-4 2 2 0 000 4zm0 6a2 2 0 100-4 2 2 0 000 4z" aria-label="More actions" variant="text" />
    </template>
</OriMenu>
```

#html
```html
<!-- Structure only — see Basic above for the full markup shape. -->
<button
    id="menu-more-trigger"
    type="button"
    style="anchor-name: --menu-more"
    aria-haspopup="menu"
    aria-controls="menu-more"
    aria-expanded="false"
    aria-label="More actions"
>
    ⋮
</button>
```
::

## Accessibility

The accessibility contract holds across every layer — the standalone classes and the Vue component
render the same attributes. Unlike the Popover, the interactive behaviour here is **not** free from the
platform: open/close, focus movement, and dismissal are driven by the `@oriui/headless` menu machine in
JavaScript.

- **The trigger MUST be a real `<button>`** (or a component that renders one, e.g. `OriButton`) and
  needs an accessible name (visible text or `aria-label`).
- The trigger carries `aria-haspopup="menu"`, `aria-controls` pointing at the panel id, and a live
  `aria-expanded` that tracks open state (unlike Popover, this one **is** managed — the engine owns
  `open`, not the platform).
- The panel is `role="menu"`, `aria-labelledby` the trigger, and `aria-orientation="vertical"`. Items
  are `role="menuitem"`.
- **Roving tabindex**: exactly one item (the highlighted one) is `tabindex="0"`; the rest are
  `tabindex="-1"`. Real DOM focus moves to the highlighted item as you navigate — there is no
  `aria-activedescendant`.
- A disabled item is `aria-disabled="true"` and is skipped by Arrow/Home/End navigation and selection.
- Selecting an item (click, or `Enter`/`Space` while highlighted) fires `select` and closes the menu,
  returning focus to the trigger. `Escape`, `Tab`, and an outside click also close it and return focus.

| Key                            | Action                                                           |
| ------------------------------ | ---------------------------------------------------------------- |
| `Enter` / `Space` (on trigger) | Opens the menu and highlights the first item.                    |
| `↓` (on trigger)               | Opens the menu and highlights the first item.                    |
| `↑` (on trigger)               | Opens the menu and highlights the last item.                     |
| `↓` / `↑`                      | Moves the highlight to the next / previous enabled item (wraps). |
| `Home` / `End`                 | Highlights the first / last enabled item.                        |
| `Enter` / `Space` (on item)    | Activates the highlighted item — fires `select`, then closes.    |
| `Escape`                       | Closes the menu and returns focus to the trigger.                |
| `Tab`                          | Closes the menu and moves focus onward (does not trap focus).    |
| Outside click                  | Closes the menu and returns focus to the trigger.                |

## Framework API

The props, events, and slots of the **Vue** component. The standalone CSS layer has no component
API — its surface is the [classes](https://oriui.vercel.app/#classes) above; the roving-tabindex keyboard and open/close
behaviour is JavaScript you'd need to author yourself, or get from [`useMenu`](https://oriui.vercel.app/headless/core) in
`@oriui/headless/vue`. (Svelte bindings are planned.)

### Props

| Prop        | Type                                                                | Default          | Description                                                                        |
| ----------- | ------------------------------------------------------------------- | ---------------- | ---------------------------------------------------------------------------------- |
| `items`     | `MenuItem[]`                                                        | **required**     | `{ value: string; label?: string; disabled?: boolean }[]`, in render order.        |
| `disabled`  | `boolean`                                                           | `false`          | Disables the trigger and blocks opening the menu.                                  |
| `placement` | `'top' | 'bottom' | 'left' | 'right'` (each also `-start` / `-end`) | `'bottom-start'` | Placement relative to the trigger. Drives the `ori-anchored_<placement>` modifier. |

### Events & attributes

| Event    | Payload  | Fired when                                                                                                                          |
| -------- | -------- | ----------------------------------------------------------------------------------------------------------------------------------- |
| `select` | `string` | An item is activated (click, or `Enter`/`Space` on the highlighted item) — carries the item's `value`. The menu closes right after. |

It sets `inheritAttrs: false`; attributes placed on `<OriMenu>` fall through to the panel element, not
the trigger.

### Slots

| Slot      | Scope                | Description                                                                                                             |
| --------- | -------------------- | ----------------------------------------------------------------------------------------------------------------------- |
| `trigger` | `{ props: object }`  | The control that opens the menu. Spread `v-bind="props"` on your own `<button>` (or `OriButton`) — it must be a button. |
| `item`    | `{ item: MenuItem }` | Replaces one item's content. Falls back to `item.label ?? item.value` when omitted.                                     |

There is no default slot — menu content is driven entirely by `items` + the `#item` slot.


# Popover

A positioned overlay for supplementary content — a menu, a filter panel, a rich hint — tethered to a
trigger. It runs entirely on the platform: the trigger opens the panel through the **Popover API**
(top-layer, light-dismiss, `Esc` — zero JS), and the panel is placed with **CSS Anchor Positioning**
(`anchor-name` / `position-anchor` + `position-area`, with a collision flip via
`position-try-fallbacks`) — zero positioning JS, no scroll/resize listeners. Baseline 2026, with
graceful degradation: an older engine still opens the panel and places it, just without the
collision-aware flip.

The examples are organised by **layer**: the [class reference](https://oriui.vercel.app/#classes&#x29; is the standalone
&#x2A;*`@oriui/css`** layer, and the [Framework API](https://oriui.vercel.app/#framework-api&#x29; is the &#x2A;*`@oriui/vue`** component. Every
example is live — flip its code between **HTML** (the standalone classes, also your htmx / Astro / Svelte /
plain-HTML usage), **Vue**; HTML is the default.

## Classes

A popover is the `.ori-popover` surface class plus the shared `.ori-anchored` placement primitive (and
one placement modifier). There is no variant or color axis — the panel takes its surface from the shared
surface tokens.

:class-table{\:rows=' [{"class":"ori-popover","type":"Block","description":"The panel surface: sizing, padding, border, surface background + ori-shadow-lg. Composed with .ori-anchored for placement; requires the native popover attribute for top-layer + light-dismiss."},{"class":"ori-anchored","type":"Placement base","description":"Shared floating-panel placement primitive — position\:fixed + position-anchor + collision flip. Add alongside the surface class."},{"class":"ori-anchored\_ :side[","type":"Placement","description":"top / bottom / left / right of the trigger, centered on the cross axis."},{"class":"ori-anchored\_ :side[-start / -end","type":"Placement","description":"Same four sides, aligned to the trigger's start / end edge instead of centered (logical, RTL-aware)."},{"class":"--ori-anchored-gap","type":"Custom prop","description":"Gap between trigger and panel on the facing side. Default 0.25rem."},{"class":"--ori-anchor","type":"Custom prop","description":"The anchor-name linking the panel to its trigger; set per-instance by the component (or by you in plain HTML)."}]]] '}

## Basic

Open the popover and observe it track the trigger with no JS positioning — the panel is a `[popover]`
element placed via `anchor-name` / `position-anchor`. Click outside, or press `Esc`, to dismiss (both
native to the Popover API).

::example
:popover-demo

#vue
```vue
<OriPopover aria-labelledby="popover-title">
    <template #trigger="{ props }">
        <OriButton v-bind="props" text="Open popover" variant="tonal" />
    </template>
    <div style="padding: 0.35rem">
        <strong id="popover-title">Weave a popover</strong>
        <p>Positioned with CSS Anchor Positioning, toggled by the Popover API.</p>
    </div>
</OriPopover>
```

#html
```html
<!-- The trigger's popovertarget links it to the panel id; anchor-name / position-anchor tether them. -->
<button popovertarget="pop-1" style="anchor-name: --pop-1" aria-haspopup="dialog" aria-controls="pop-1">
    Open popover
</button>
<div
    id="pop-1"
    popover
    role="dialog"
    class="ori-popover ori-anchored ori-anchored_bottom-start"
    style="--ori-anchor: --pop-1"
    aria-labelledby="popover-title"
>
    <strong id="popover-title">Weave a popover</strong>
    <p>Positioned with CSS Anchor Positioning, toggled by the Popover API.</p>
</div>
```
::

## Placements

Twelve placements — `bottom-start` is the default. A bare side (`top` / `bottom` / `left` / `right`)
centers on the cross axis; `-start` / `-end` align to the trigger's start / end edge (logical,
RTL-aware). Each sets a `position-area` on the trigger's anchor grid plus the gap margin on the facing
side; `position-try-fallbacks` flips it on overflow.

::example
:popover-demo{placement="top"}

:popover-demo{placement="bottom"}

:popover-demo{placement="left"}

:popover-demo{placement="right"}

#vue
```vue
<OriPopover placement="top">
    <template #trigger="{ props }">
        <OriButton v-bind="props" text="top" variant="tonal" />
    </template>
    <p>Above the trigger.</p>
</OriPopover>
<OriPopover placement="bottom-end">
    <template #trigger="{ props }">
        <OriButton v-bind="props" text="bottom-end" variant="tonal" />
    </template>
    <p>Below, aligned to the trigger's end edge.</p>
</OriPopover>
```

#html
```html
<!-- swap the modifier: ori-anchored_top / _top-start / _top-end / _bottom / _bottom-start / _bottom-end / _left / _left-start / _left-end / _right / _right-start / _right-end -->
<div id="pop-2" popover role="dialog" class="ori-popover ori-anchored ori-anchored_top" style="--ori-anchor: --pop-2">
    <p>Above the trigger.</p>
</div>
```
::

## Common patterns

A filter panel opened from a toolbar button — a typical non-modal popover use case.

::example
:popover-demo{placement="bottom-end"}

#vue
```vue
<OriPopover placement="bottom-end" aria-labelledby="filters-title" role="dialog">
    <template #trigger="{ props }">
        <OriButton v-bind="props" text="Filters" icon="M10 18h4v-2h-4v2zM3 6v2h18V6H3zm3 7h12v-2H6v2z" variant="outline" />
    </template>
    <div style="display: flex; flex-direction: column; gap: 0.5rem; padding: 0.35rem; min-width: 12rem">
        <strong id="filters-title">Filters</strong>
        <OriCheckbox label="In stock only" />
        <OriCheckbox label="On sale" />
        <OriButton text="Apply" size="sm" />
    </div>
</OriPopover>
```

#html
```html
<button
    popovertarget="pop-filters"
    style="anchor-name: --pop-filters"
    aria-haspopup="dialog"
    aria-controls="pop-filters"
>
    Filters
</button>
<div
    id="pop-filters"
    popover
    role="dialog"
    class="ori-popover ori-anchored ori-anchored_bottom-end"
    style="--ori-anchor: --pop-filters"
    aria-labelledby="filters-title"
>
    <strong id="filters-title">Filters</strong>
    <!-- filter controls -->
</div>
```
::

## Accessibility

The accessibility contract holds across every layer — the standalone classes and the Vue component
render the same attributes. The interactive behaviour, however, comes from the platform: the Popover
API and CSS Anchor Positioning drive open/close and placement with no state to keep in sync.

- **The trigger MUST be a real `<button>`** (or a component that renders one, e.g. `OriButton`) — the
  Popover API's declarative `popovertarget` association only works from a button.
- **Give the panel an accessible name** with `aria-label` or `aria-labelledby` — undeclared attributes
  fall through to the panel (`inheritAttrs: false` + `v-bind="$attrs"`), so pass either directly on
  `<OriPopover>`.
- `role` defaults to `'dialog'` (a non-modal popup); pass `'menu'`, `'listbox'`, or another role that
  matches the panel's actual content.
- **The expanded state is unmanaged.** The Popover API opens and closes the panel entirely in the
  browser with no JS state to reflect, so there is no live `aria-expanded` to toggle. The `#trigger`
  slot's `props` bag instead conveys the popup relationship **statically**: `aria-haspopup` mirrors the
  panel's `role`, and `aria-controls` points at the panel's id.
- `Esc` and outside-click dismissal, and returning focus to the trigger, come from the platform via the
  Popover API — no focus-trap or dismiss handler to wire.

| Key      | Action                                                           |
| -------- | ---------------------------------------------------------------- |
| `Enter`  | Activates the trigger and opens the panel (native `<button>`).   |
| `Space`  | Activates the trigger and opens the panel (native `<button>`).   |
| `Escape` | Closes the panel and returns focus to the trigger (Popover API). |

## Framework API

The props, events, and slots of the **Vue** component. The standalone CSS layer has no component
API — its surface is the [classes](https://oriui.vercel.app/#classes) above, and you wire `popovertarget` / `anchor-name`
yourself. (Svelte bindings are planned.)

### Props

| Prop        | Type                                                                | Default          | Description                                                                                        |
| ----------- | ------------------------------------------------------------------- | ---------------- | -------------------------------------------------------------------------------------------------- |
| `placement` | `'top' | 'bottom' | 'left' | 'right'` (each also `-start` / `-end`) | `'bottom-start'` | Placement relative to the trigger. Drives the `ori-anchored_<placement>` modifier.                 |
| `role`      | `string`                                                            | `'dialog'`       | ARIA role for the panel — `'dialog'` (default), `'menu'`, `'listbox'`, … per the content it holds. |

### Events & attributes

OriPopover declares **no custom emits** — open/close is owned by the platform (the Popover API), not
component state. It sets `inheritAttrs: false`; attributes placed on `<OriPopover>` (`aria-label`,
`aria-labelledby`, `id`, …) fall through to the panel `<div popover>`, not the trigger.

### Slots

| Slot      | Scope               | Description                                                                                                              |
| --------- | ------------------- | ------------------------------------------------------------------------------------------------------------------------ |
| `trigger` | `{ props: object }` | The control that opens the panel. Spread `v-bind="props"` on your own `<button>` (or `OriButton`) — it must be a button. |
| `default` | —                   | Panel content, rendered inside the `[popover]` element.                                                                  |


# Progress

A horizontal progress bar that communicates task completion. It supports a determinate mode (a
known `value` out of a `max`) and an indeterminate mode (animated sweep) for tasks with no
measurable progress. State is expressed through ARIA attributes — `aria-valuenow` is omitted when
indeterminate, giving screen readers the correct cue automatically.

The examples are organised by **layer**: the [class reference](https://oriui.vercel.app/#classes&#x29; is the standalone
&#x2A;*`@oriui/css`** layer, and the [Framework API](https://oriui.vercel.app/#framework-api&#x29; is the &#x2A;*`@oriui/vue`** component. Every
example is live — flip its code between **HTML** (the standalone classes, also your htmx / Astro / Svelte /
plain-HTML usage), **Vue**; HTML is the default.

## Classes

A progress bar is a block class plus single-class token utilities. The Vue props in
[Framework API](https://oriui.vercel.app/#framework-api) map 1:1 to these.

::class-table
---
rows:
  - class: ori-progress
    type: Block
    description: "Required base class. Renders full-width. Defaults baked in: color
      primary, radius rounded, height 8 px."
  - class: ori-progress_sm · ori-progress_md · ori-progress_lg
    type: Size
    description: "Track height: 4 px (sm) · 8 px (md, default) · 12 px (lg).
      ori-progress_* (size sugar)."
  - class: ori-color_*
    type: Color
    description: primary · secondary · success · warn · danger · info · surface —
      one class repoints the color token; no base class needed.
  - class: ori-size-radius_*
    type: Radius
    description: zero · xs · sm · md · lg · xl · rounded (default) — one class
      repoints the radius token; no base class needed.
  - class: ori-progress__track
    type: Part
    description: Inner track element (tinted background).
  - class: ori-progress__indicator
    type: Part
    description: Fill element; width driven by inline style or data-indeterminate animation.
  - class: data-indeterminate
    type: State
    description: Present on the indicator when no value is known; triggers the sweep
      animation.
---
::

## Determinate

Pass a `value` (0–`max`). The fill width and `aria-valuenow` update together.

::example
  :::ori-progress{:value='25' color="primary"}
  :::

  :::ori-progress{:value='50' color="primary"}
  :::

  :::ori-progress{:value='75' color="primary"}
  :::

  :::ori-progress{:value='100' color="primary"}
  :::

#vue
```vue
<OriProgress :value="25" color="primary" />
<OriProgress :value="50" color="primary" />
<OriProgress :value="75" color="primary" />
<OriProgress :value="100" color="primary" />
```

#html
```html
<!-- width is set via inline style on the indicator -->
<div
    class="ori-progress ori-color_primary"
    role="progressbar"
    aria-label="Loading"
    aria-valuemin="0"
    aria-valuemax="100"
    aria-valuenow="50"
>
    <div class="ori-progress__track">
        <div class="ori-progress__indicator" style="width: 50%"></div>
    </div>
</div>
```
::

## Indeterminate

Omit `value` (or pass `:indeterminate="true"`) when progress cannot be measured. The indicator
sweeps continuously and `aria-valuenow` is not set.

::example
  :::ori-progress{indeterminate color="primary"}
  :::

#vue
```vue
<OriProgress indeterminate color="primary" />
```

#html
```html
<div
    class="ori-progress ori-color_primary"
    role="progressbar"
    aria-label="Loading"
    aria-valuemin="0"
    aria-valuemax="100"
>
    <div class="ori-progress__track">
        <div class="ori-progress__indicator" data-indeterminate></div>
    </div>
</div>
```
::

## Colors

Every semantic role. `color` defaults to `primary`; set it to any role to recolor the indicator.

::example
  :::ori-progress{:value='60' color="primary"}
  :::

  :::ori-progress{:value='60' color="secondary"}
  :::

  :::ori-progress{:value='60' color="success"}
  :::

  :::ori-progress{:value='60' color="warn"}
  :::

  :::ori-progress{:value='60' color="danger"}
  :::

  :::ori-progress{:value='60' color="info"}
  :::

#vue
```vue
<OriProgress :value="60" color="primary" />
<OriProgress :value="60" color="secondary" />
<OriProgress :value="60" color="success" />
<OriProgress :value="60" color="warn" />
<OriProgress :value="60" color="danger" />
<OriProgress :value="60" color="info" />
```

#html
```html
<!-- swap the color class: ori-color_primary → _secondary / _success / _warn / _danger / _info -->
<div
    class="ori-progress ori-color_danger"
    role="progressbar"
    aria-label="Loading"
    aria-valuemin="0"
    aria-valuemax="100"
    aria-valuenow="60"
>
    <div class="ori-progress__track">
        <div class="ori-progress__indicator" style="width: 60%"></div>
    </div>
</div>
```
::

## Sizes

Three track heights — `sm` (4 px), `md` (8 px, default), and `lg` (12 px).

::example
  :::ori-progress{:value='50' color="primary" size="sm"}
  :::

  :::ori-progress{:value='50' color="primary" size="md"}
  :::

  :::ori-progress{:value='50' color="primary" size="lg"}
  :::

#vue
```vue
<OriProgress :value="50" size="sm" color="primary" />
<OriProgress :value="50" size="md" color="primary" />
<OriProgress :value="50" size="lg" color="primary" />
```

#html
```html
<!-- swap the size modifier: ori-progress_sm / ori-progress_md / ori-progress_lg -->
<div
    class="ori-progress ori-progress_lg ori-color_primary"
    role="progressbar"
    aria-label="Loading"
    aria-valuemin="0"
    aria-valuemax="100"
    aria-valuenow="50"
>
    <div class="ori-progress__track">
        <div class="ori-progress__indicator" style="width: 50%"></div>
    </div>
</div>
```
::

## Radius

From `zero` (square) to `rounded` (pill, default).

::example
  :::ori-progress
  ---
  value: 60
  color: primary
  radius: zero
  size: lg
  ---
  :::

  :::ori-progress
  ---
  value: 60
  color: primary
  radius: sm
  size: lg
  ---
  :::

  :::ori-progress
  ---
  value: 60
  color: primary
  radius: md
  size: lg
  ---
  :::

  :::ori-progress
  ---
  value: 60
  color: primary
  radius: rounded
  size: lg
  ---
  :::

#vue
```vue
<OriProgress :value="60" radius="zero" size="lg" color="primary" />
<OriProgress :value="60" radius="sm" size="lg" color="primary" />
<OriProgress :value="60" radius="rounded" size="lg" color="primary" />
```

#html
```html
<!-- swap the radius class: ori-size-radius_zero → _sm / _md / _rounded -->
<div
    class="ori-progress ori-progress_lg ori-size-radius_zero ori-color_primary"
    role="progressbar"
    aria-label="Loading"
    aria-valuemin="0"
    aria-valuemax="100"
    aria-valuenow="60"
>
    <div class="ori-progress__track">
        <div class="ori-progress__indicator" style="width: 60%"></div>
    </div>
</div>
```
::

## Custom max

`max` defaults to `100`. Pass any positive number and supply `value` in the same unit — the
component calculates the fill percentage.

::example
  :::ori-progress
  ---
  max: 10
  value: 3
  color: success
  label: Step 3 of 10
  ---
  :::

#vue
```vue
<OriProgress :value="3" :max="10" color="success" label="Step 3 of 10" />
```

#html
```html
<div
    class="ori-progress ori-color_success"
    role="progressbar"
    aria-label="Step 3 of 10"
    aria-valuemin="0"
    aria-valuemax="10"
    aria-valuenow="3"
>
    <div class="ori-progress__track">
        <div class="ori-progress__indicator" style="width: 30%"></div>
    </div>
</div>
```
::

## Common patterns

An upload bar with a label and a multi-step wizard indicator.

::example
  :::ori-progress
  ---
  value: 68
  color: primary
  label: Uploading file
  size: sm
  ---
  :::

  :::ori-progress
  ---
  max: 5
  value: 2
  color: secondary
  label: Step 2 of 5
  ---
  :::

  :::ori-progress{indeterminate color="info" label="Fetching results"}
  :::

#vue
```vue
<!-- upload progress -->
<div style="display: flex; flex-direction: column; gap: 0.25rem">
    <span style="font-size: 0.875rem">Uploading… 68 %</span>
    <OriProgress :value="68" color="primary" size="sm" label="Uploading file" />
</div>

<!-- wizard step indicator -->
<OriProgress :value="2" :max="5" color="secondary" label="Step 2 of 5" />

<!-- indeterminate fetch -->
<OriProgress indeterminate color="info" label="Fetching results" />
```

#html
```html
<div style="display: flex; flex-direction: column; gap: 0.25rem">
    <span style="font-size: 0.875rem">Uploading… 68 %</span>
    <div
        class="ori-progress ori-progress_sm ori-color_primary"
        role="progressbar"
        aria-label="Uploading file"
        aria-valuemin="0"
        aria-valuemax="100"
        aria-valuenow="68"
    >
        <div class="ori-progress__track">
            <div class="ori-progress__indicator" style="width: 68%"></div>
        </div>
    </div>
</div>

<div
    class="ori-progress ori-color_secondary"
    role="progressbar"
    aria-label="Step 2 of 5"
    aria-valuemin="0"
    aria-valuemax="5"
    aria-valuenow="2"
>
    <div class="ori-progress__track">
        <div class="ori-progress__indicator" style="width: 40%"></div>
    </div>
</div>
```
::

## Accessibility

The accessibility contract holds across every layer — the standalone classes and the Vue component
render the same attributes.

- Renders a `<div role="progressbar">` with `aria-valuemin="0"`, `aria-valuemax`, and
  `aria-valuenow` set from `value` and `max`.
- In indeterminate mode `aria-valuenow` is omitted — the WAI-ARIA spec says a progressbar without
  `aria-valuenow` is implicitly indeterminate, which assistive technology announces accordingly.
- The `label` prop sets `aria-label`. Always supply a meaningful label so screen readers can
  distinguish multiple bars on the same page (e.g. `"Uploading avatar"` vs `"Saving settings"`).
- The fill animation respects `prefers-reduced-motion`: the transition on the determinate indicator
  is removed and the indeterminate sweep freezes to a fully-filled bar.
- The component is not interactive — no keyboard interaction is defined.

## Framework API

The props, events, and slots of the **Vue** component. The standalone CSS layer has no component
API — its surface is the [classes](https://oriui.vercel.app/#classes) above. (Svelte bindings are planned.)

### Props

| Prop            | Type                 | Default     | Description                                                                                                                                     |
| --------------- | -------------------- | ----------- | ----------------------------------------------------------------------------------------------------------------------------------------------- |
| `color`         | `ThemeColor`         | `'primary'` | Semantic color role for the indicator. (The standalone `.ori-progress` class inherits `currentcolor` when no `ori-color_*` utility is applied.) |
| `indeterminate` | `boolean`            | `false`     | Enables the animated sweep; omits `aria-valuenow` from the rendered element.                                                                    |
| `label`         | `string`             | `'Loading'` | `aria-label` read by assistive technology. Use a descriptive message per-bar.                                                                   |
| `max`           | `number`             | `100`       | Upper bound. `value` is clamped to this range before the percentage is computed.                                                                |
| `radius`        | `RadiusSize`         | `'rounded'` | Corner radius of the track and indicator (`zero` · `xs` · `sm` · `md` · `lg` · `xl` · `rounded`).                                               |
| `size`          | `'sm' | 'md' | 'lg'` | `'md'`      | Track height: `sm` = 4 px, `md` = 8 px, `lg` = 12 px.                                                                                           |
| `value`         | `number`             | `0`         | Current progress value, clamped to `[0, max]`. Ignored when `indeterminate` is `true`.                                                          |

`ThemeColor`: `'primary' | 'secondary' | 'success' | 'warn' | 'danger' | 'info' | 'surface' | 'background'`

`RadiusSize`: `'zero' | 'xs' | 'sm' | 'md' | 'lg' | 'xl' | 'rounded'`

### Events & attributes

OriProgress declares **no custom events** and does not set `inheritAttrs: false`, so any extra
attributes you pass (`class`, `style`, `data-*`) fall through to the root `<div role="progressbar">`.
The ARIA attributes (`aria-label`, `aria-valuemin`, `aria-valuemax`, `aria-valuenow`) are bound
directly from props — set them through props rather than as fall-through attributes.

### Slots

OriProgress has **no slots**. Its visual output is a CSS-driven track and fill bar controlled
entirely by props.


# RadioGroup

A "choose one" compound control. A `role="radiogroup"` container names the set via
`aria-labelledby`; each option is a real `<input type="radio">` sharing a single `name` — so the
browser enforces single-select and native form submission — visually hidden behind a styled circle.
Pass the options as an array; per-option `disabled` is supported.

The examples are organised by **layer**: the [class reference](https://oriui.vercel.app/#classes&#x29; is the standalone
&#x2A;*`@oriui/css`** layer, and the [Framework API](https://oriui.vercel.app/#framework-api&#x29; is the &#x2A;*`@oriui/vue`** component. Every
example is live — flip its code between **HTML** (the standalone classes, also your htmx / Astro / Svelte /
plain-HTML usage), **Vue**; HTML is the default.

## Classes

The group is a block class plus single-class token utilities — one class repoints one token, no base
class needed. The Vue props in [Framework API](https://oriui.vercel.app/#framework-api) map 1:1 to these.

::class-table
---
rows:
  - class: ori-radio-group
    type: Block
    description: Required base class on the container; carries role=radiogroup.
  - class: ori-color_*
    type: Color
    description: <b>primary</b> · secondary · success · warn · danger · info · surface
  - class: ori-font-size_*
    type: Size
    description: xs · sm · <b>md</b> · lg · xl · xxl — scales all option labels.
  - class: ori-radio-group_inline
    type: Layout
    description: Lays options out in a row (flex-wrap) instead of a column.
  - class: ori-radio-group__label
    type: Part
    description: Group label element; referenced by aria-labelledby.
  - class: ori-radio-group__options
    type: Part
    description: Options wrapper; flex column (or row when _inline).
  - class: ori-radio
    type: Part
    description: Wrapping <label> for each option. Add ori-radio_disabled when disabled.
  - class: ori-radio__input · ori-radio__circle · ori-radio__label
    type: Part
    description: Hidden native input / styled circle indicator / visible label text.
  - class: disabled · aria-required
    type: State
    description: Real attributes on the native input / container, not extra classes.
---
::

## Anatomy

```text
div.ori-radio-group  [role="radiogroup", aria-labelledby]
  div.ori-radio-group__label          ← group heading (optional)
  div.ori-radio-group__options
    label.ori-radio                   ← one per option
      input.ori-radio__input          ← visually hidden real radio
      span.ori-radio__circle          ← styled indicator (aria-hidden)
      span.ori-radio__label           ← visible label text
```

## Basic

::example
  :::ori-radio-group
  ---
  options:
    - label: Free
      value: free
    - label: Pro
      value: pro
    - label: Team
      value: team
  label: Choose a plan
  ---
  :::

#vue
```vue
<OriRadioGroup
    v-model="plan"
    label="Choose a plan"
    :options="[
        { label: 'Free', value: 'free' },
        { label: 'Pro', value: 'pro' },
        { label: 'Team', value: 'team' }
    ]"
/>
```

#html
```html
<div class="ori-radio-group ori-color_primary ori-font-size_md" role="radiogroup" aria-labelledby="plan-label">
    <div id="plan-label" class="ori-radio-group__label">Choose a plan</div>
    <div class="ori-radio-group__options">
        <label class="ori-radio">
            <input class="ori-radio__input" type="radio" name="plan" value="free" />
            <span class="ori-radio__circle" aria-hidden="true"></span>
            <span class="ori-radio__label">Free</span>
        </label>
        <!-- one <label class="ori-radio"> per option, all sharing the same name -->
    </div>
</div>
```
::

## Colors

Every semantic role. The accent color is shared by the checked circle and the focus ring.

::example
  :::ori-radio-group
  ---
  options:
    - label: Option A
      value: a
    - label: Option B
      value: b
  color: primary
  label: Primary
  ---
  :::

  :::ori-radio-group
  ---
  options:
    - label: Option A
      value: a
    - label: Option B
      value: b
  color: success
  label: Success
  ---
  :::

  :::ori-radio-group
  ---
  options:
    - label: Option A
      value: a
    - label: Option B
      value: b
  color: danger
  label: Danger
  ---
  :::

#vue
```vue
<OriRadioGroup v-model="val" label="Primary" color="primary" :options="opts" />
<OriRadioGroup v-model="val" label="Success" color="success" :options="opts" />
<OriRadioGroup v-model="val" label="Danger" color="danger" :options="opts" />
```

#html
```html
<!-- swap the color: ori-color_primary → _success / _danger / _warn / _info -->
<div class="ori-radio-group ori-color_success ori-font-size_md" role="radiogroup">…</div>
```
::

## Sizes

`xs` → `xxl`. The size class controls `font-size`, which scales the circle and the gap uniformly
via `em` units.

::example
  :::ori-radio-group
  ---
  options:
    - label: Option A
      value: a
    - label: Option B
      value: b
  label: xs
  size: xs
  ---
  :::

  :::ori-radio-group
  ---
  options:
    - label: Option A
      value: a
    - label: Option B
      value: b
  label: sm
  size: sm
  ---
  :::

  :::ori-radio-group
  ---
  options:
    - label: Option A
      value: a
    - label: Option B
      value: b
  label: md (default)
  size: md
  ---
  :::

  :::ori-radio-group
  ---
  options:
    - label: Option A
      value: a
    - label: Option B
      value: b
  label: lg
  size: lg
  ---
  :::

#vue
```vue
<OriRadioGroup v-model="val" label="xs" size="xs" :options="opts" />
<OriRadioGroup v-model="val" label="md (default)" size="md" :options="opts" />
<OriRadioGroup v-model="val" label="lg" size="lg" :options="opts" />
```

#html
```html
<!-- swap the size: ori-font-size_md → _xs / _sm / _lg / _xl / _xxl -->
<div class="ori-radio-group ori-color_primary ori-font-size_lg" role="radiogroup">…</div>
```
::

## Inline

`inline` lays the options out in a wrapping row instead of a column — useful for short label sets.

::example
  :::ori-radio-group
  ---
  inline: true
  options:
    - label: All
      value: all
    - label: Mentions
      value: mentions
    - label: None
      value: none
  label: Notifications
  ---
  :::

#vue
```vue
<OriRadioGroup v-model="notify" label="Notifications" inline :options="notifyOptions" />
```

#html
```html
<!-- add ori-radio-group_inline to the container -->
<div
    class="ori-radio-group ori-radio-group_inline ori-color_primary ori-font-size_md"
    role="radiogroup"
    aria-labelledby="notify-label"
>
    <div id="notify-label" class="ori-radio-group__label">Notifications</div>
    <div class="ori-radio-group__options">
        <label class="ori-radio">…</label>
        <label class="ori-radio">…</label>
        <label class="ori-radio">…</label>
    </div>
</div>
```
::

## Disabled — whole group

Pass `disabled` to lock all options at once.

::example
  :::ori-radio-group
  ---
  disabled: true
  options:
    - label: Free
      value: free
    - label: Pro
      value: pro
    - label: Team
      value: team
  label: Plan (locked)
  ---
  :::

#vue
```vue
<OriRadioGroup v-model="plan" label="Plan (locked)" disabled :options="planOptions" />
```

#html
```html
<div class="ori-radio-group ori-color_primary ori-font-size_md" role="radiogroup">
    <div class="ori-radio-group__label">Plan (locked)</div>
    <div class="ori-radio-group__options">
        <!-- each label gets ori-radio_disabled; each input gets the disabled attribute -->
        <label class="ori-radio ori-radio_disabled">
            <input class="ori-radio__input" type="radio" name="plan" value="free" disabled />
            <span class="ori-radio__circle" aria-hidden="true"></span>
            <span class="ori-radio__label">Free</span>
        </label>
    </div>
</div>
```
::

## Disabled — per option

Set `disabled: true` on individual items in the `options` array to lock only those choices.

::example
  :::ori-radio-group
  ---
  options:
    - label: Free
      value: free
    - label: Pro
      value: pro
    - label: Enterprise (contact us)
      value: enterprise
      disabled: true
  label: Choose a plan
  ---
  :::

#vue
```vue
<OriRadioGroup
    v-model="plan"
    label="Choose a plan"
    :options="[
        { label: 'Free', value: 'free' },
        { label: 'Pro', value: 'pro' },
        { label: 'Enterprise (contact us)', value: 'enterprise', disabled: true }
    ]"
/>
```

#html
```html
<!-- only the disabled option's label + input get the modifier/attribute -->
<label class="ori-radio ori-radio_disabled">
    <input class="ori-radio__input" type="radio" name="plan" value="enterprise" disabled />
    <span class="ori-radio__circle" aria-hidden="true"></span>
    <span class="ori-radio__label">Enterprise (contact us)</span>
</label>
```
::

## Required

`required` sets `aria-required="true"` on the group and the `required` attribute on each input.

::example
  :::ori-radio-group
  ---
  options:
    - label: Email
      value: email
    - label: Phone
      value: phone
    - label: Post
      value: post
  required: true
  label: Preferred contact
  ---
  :::

#vue
```vue
<OriRadioGroup v-model="contact" label="Preferred contact" required :options="contactOptions" />
```

#html
```html
<div
    class="ori-radio-group ori-color_primary ori-font-size_md"
    role="radiogroup"
    aria-labelledby="contact-label"
    aria-required="true"
>
    <div id="contact-label" class="ori-radio-group__label">Preferred contact</div>
    <div class="ori-radio-group__options">
        <label class="ori-radio">
            <input class="ori-radio__input" type="radio" name="contact" value="email" required />
            …
        </label>
    </div>
</div>
```
::

## Common patterns

Color, size, inline layout, and per-option disabled in a compact panel.

::example
  :::ori-radio-group
  ---
  inline: true
  options:
    - label: Light
      value: light
    - label: Dark
      value: dark
    - label: System
      value: system
  color: secondary
  label: Theme
  size: sm
  ---
  :::

#vue
```vue
<OriRadioGroup
    v-model="theme"
    label="Theme"
    inline
    color="secondary"
    size="sm"
    :options="[
        { label: 'Light', value: 'light' },
        { label: 'Dark', value: 'dark' },
        { label: 'System', value: 'system' }
    ]"
/>
```

#html
```html
<div
    class="ori-radio-group ori-radio-group_inline ori-color_secondary ori-font-size_sm"
    role="radiogroup"
    aria-labelledby="theme-label"
>
    <div id="theme-label" class="ori-radio-group__label">Theme</div>
    <div class="ori-radio-group__options">
        <label class="ori-radio">
            <input class="ori-radio__input" type="radio" name="theme" value="light" />
            <span class="ori-radio__circle" aria-hidden="true"></span>
            <span class="ori-radio__label">Light</span>
        </label>
        <!-- … Dark, System -->
    </div>
</div>
```
::

## Accessibility

The accessibility contract holds across every layer — the standalone classes and the Vue component
render the same attributes and keyboard behaviour.

- The root element carries `role="radiogroup"`. When `label` is provided, `aria-labelledby` points
  at the rendered label element; without a `label`, pass `aria-label` as a fallthrough attribute.
- Every option is a real `<input type="radio">` sharing one `name` (auto-generated via `useId`
  when omitted). The browser natively enforces single-select, arrow-key navigation between options
  in the group, and form submission — no JS needed.
- The visual `ori-radio__circle` is `aria-hidden="true"`; the accessible name comes from the
  adjacent `ori-radio__label` text, wired through the `<label>` wrapper.
- `disabled` (group-level or per-option) sets the native `disabled` attribute on the `<input>`.
- `required` sets both the native `required` attribute on each input and `aria-required="true"` on
  the group container.
- Focus is always visible via `:focus-visible` on the hidden `<input>`, reflected onto the
  `ori-radio__circle` with a 2 px `outline` in the group's accent color.

| Key          | Action                                            |
| ------------ | ------------------------------------------------- |
| `Tab`        | Moves focus into / out of the radio group.        |
| `Arrow keys` | Cycles between options within the group (native). |
| `Space`      | Selects the focused option (native).              |

## Framework API

The props, events, and slots of the **Vue** component. The standalone CSS layer has no component
API — its surface is the [classes](https://oriui.vercel.app/#classes) above. (Svelte bindings are planned.)

### Props

| Prop       | Type            | Default     | Description                                                                          |
| ---------- | --------------- | ----------- | ------------------------------------------------------------------------------------ |
| `color`    | `ThemeColor`    | `'primary'` | Accent color for the checked circle and focus ring.                                  |
| `disabled` | `boolean`       | `false`     | Disables all options; per-option disable is also supported via `options[].disabled`. |
| `inline`   | `boolean`       | `false`     | Lays options out in a wrapping row (`ori-radio-group_inline`).                       |
| `label`    | `string`        | —           | Group heading. When present the container is `aria-labelledby` this element.         |
| `name`     | `string`        | —           | Shared `name` for all radio inputs. Auto-generated via `useId` when omitted.         |
| `options`  | `RadioOption[]` | `[]`        | Array of `{ label, value, disabled? }` objects — the full options-array API.         |
| `required` | `boolean`       | `false`     | Sets `aria-required="true"` on the group and `required` on each input.               |
| `size`     | `ActionSize`    | `'md'`      | Font size scale (`xs`–`xxl`); the circle and gap scale with it via `em` units.       |

`RadioOption` shape: `{ label: string; value: string | number; disabled?: boolean }`.

### Events & attributes

`v-model` is the public state binding — prop `modelValue` holds the currently selected `value`, and
the component emits `update:modelValue` when the user picks another option. The `name` attribute is
shared across all native inputs; omit it to let the component auto-generate a unique id via `useId`.

The component does **not** set `inheritAttrs: false`, so extra attributes (e.g. `aria-label`,
`class`, `data-*`) fall through to the root `div.ori-radio-group`. An unlabelled group should
pass `aria-label` this way:

```vue
<OriRadioGroup v-model="val" aria-label="Sort order" :options="sortOptions" />
```

### Slots

| Slot     | Props        | Description                                                                                                                                                                            |
| -------- | ------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `option` | `{ option }` | Scoped, rendered once per option to customise its label markup — card-style or leading-icon radios. `option` is the `{ label, value, disabled? }` entry; falls back to `option.label`. |


# Select

A native-first styled select control with `v-model`. The browser owns the dropdown, full keyboard
interaction, type-ahead, and all ARIA semantics — oriUI only styles the closed control and draws a
decorative chevron. It shares the form-control contract of [Input](https://oriui.vercel.app/components/input) and
[Textarea](https://oriui.vercel.app/components/textarea): a built-in `label`, `hint`, `error`, and `required` asterisk, all
wired for accessibility. State is expressed through real attributes — native `disabled` and
`aria-invalid="true"` (not classes) — and arbitrary native attrs (`name`, `autocomplete`, …) fall
through to the `<select>` via `inheritAttrs:false`.

The examples are organised by **layer**: the [class reference](https://oriui.vercel.app/#classes&#x29; is the standalone
&#x2A;*`@oriui/css`** layer, and the [Framework API](https://oriui.vercel.app/#framework-api&#x29; is the &#x2A;*`@oriui/vue`** component. Every
example is live — flip its code between **HTML** (the standalone classes, also your htmx / Astro / Svelte /
plain-HTML usage), **Vue**; HTML is the default.

## Classes

A select is a block wrapper plus single-class token utilities — one class repoints one token, no base
class needed. The `ori-color_*` accent drives the focus ring; the idle border is a neutral,
theme-aware blend. The Vue props in [Framework API](https://oriui.vercel.app/#framework-api) map 1:1 to these.

::class-table
---
rows:
  - class: ori-select
    type: Block
    description: Column wrapper (label, control, hint/error); carries the ori-color
      and ori-font-size utility classes.
  - class: ori-color_*
    type: Color
    description: primary (default) · secondary · success · warn · danger · info ·
      surface (focus ring accent).
  - class: ori-select_* (size)
    type: Size
    description: xs · sm · md (default) · lg · xl · xxl (control height sugar on the
      wrapper).
  - class: ori-size-radius_*
    type: Radius
    description: zero · xs · sm · md (default) · lg · xl · rounded (control corners,
      on the inner select element).
  - class: ori-font-size_*
    type: Font
    description: xs · sm · md (default) · lg · xl · xxl (text scale, driven by size prop).
  - class: ori-select__control
    type: Part
    description: The native select element; carries ori-size-radius utility.
  - class: ori-select__chevron
    type: Part
    description: Decorative aria-hidden chevron (inline SVG), absolutely positioned
      at inset-inline-end.
  - class: ori-select__label · ori-select__required · ori-select__control-wrap ·
      ori-select__hint · ori-select__error
    type: Part
    description: label / required asterisk / control+chevron wrapper / helper text /
      error message (role=alert).
  - class: ori-select_fluid
    type: Layout
    description: Stretches the wrapper to full width of its container.
  - class: disabled · aria-invalid
    type: State
    description: real attributes, not classes
---
::

## Colors

The `ori-color_*` class controls the focus ring accent.

::example
  :::ori-select
  ---
  options:
    - label: Primary
      value: primary
  color: primary
  ---
  :::

  :::ori-select
  ---
  options:
    - label: Secondary
      value: secondary
  color: secondary
  ---
  :::

  :::ori-select
  ---
  options:
    - label: Success
      value: success
  color: success
  ---
  :::

  :::ori-select
  ---
  options:
    - label: Warn
      value: warn
  color: warn
  ---
  :::

  :::ori-select
  ---
  options:
    - label: Danger
      value: danger
  color: danger
  ---
  :::

  :::ori-select
  ---
  options:
    - label: Info
      value: info
  color: info
  ---
  :::

#vue
```vue
<OriSelect v-model="value" color="primary" :options="options" />
<OriSelect v-model="value" color="danger" :options="options" />
<OriSelect v-model="value" color="info" :options="options" />
```

#html
```html
<!-- swap the color: ori-color_primary → _secondary / _success / _warn / _danger / _info -->
<div class="ori-select ori-color_danger">
    <div class="ori-select__control-wrap">
        <select class="ori-select__control ori-size-radius_md">
            <option value="danger">Danger</option>
        </select>
        <span class="ori-select__chevron" aria-hidden="true"><!-- chevron SVG --></span>
    </div>
</div>
```
::

## Sizes

`xs` → `xxl`. The size drives both the control height (`ori-select_*` sugar on the wrapper) and the
text scale (`ori-font-size_*`).

::example
  :::ori-select
  ---
  options:
    - label: Extra small
      value: xs
  size: xs
  ---
  :::

  :::ori-select
  ---
  options:
    - label: Small
      value: sm
  size: sm
  ---
  :::

  :::ori-select
  ---
  options:
    - label: Medium
      value: md
  size: md
  ---
  :::

  :::ori-select
  ---
  options:
    - label: Large
      value: lg
  size: lg
  ---
  :::

  :::ori-select
  ---
  options:
    - label: Extra large
      value: xl
  size: xl
  ---
  :::

#vue
```vue
<OriSelect v-model="value" size="sm" :options="options" />
<OriSelect v-model="value" size="xl" :options="options" />
```

#html
```html
<!-- ori-select_* drives height; ori-font-size_* scales the text; both use the same size token -->
<div class="ori-select ori-color_primary ori-select_xl ori-font-size_xl">
    <div class="ori-select__control-wrap">
        <select class="ori-select__control ori-size-radius_md">
            <option value="xl">Extra large</option>
        </select>
        <span class="ori-select__chevron" aria-hidden="true"><!-- chevron SVG --></span>
    </div>
</div>
```
::

## Radius

From `zero` (square) through the default `md` to `rounded` (pill-shaped control).

::example
  :::ori-select
  ---
  options:
    - label: Zero
      value: zero
  radius: zero
  ---
  :::

  :::ori-select
  ---
  options:
    - label: Small
      value: sm
  radius: sm
  ---
  :::

  :::ori-select
  ---
  options:
    - label: Medium
      value: md
  radius: md
  ---
  :::

  :::ori-select
  ---
  options:
    - label: Large
      value: lg
  radius: lg
  ---
  :::

  :::ori-select
  ---
  options:
    - label: Rounded
      value: rounded
  radius: rounded
  ---
  :::

#vue
```vue
<OriSelect v-model="value" radius="zero" :options="options" />
<OriSelect v-model="value" radius="rounded" :options="options" />
```

#html
```html
<select class="ori-select__control ori-size-radius_zero">
    …
</select>
```
::

## Placeholder

A `placeholder` renders a disabled, non-reselectable first option that acts as a prompt. It carries
`disabled` so it cannot be chosen after the user has made a selection.

::example
  :::ori-select
  ---
  options:
    - label: France
      value: fr
    - label: Germany
      value: de
    - label: Japan
      value: jp
  placeholder: Choose a country
  ---
  :::

#vue
```vue
<OriSelect
    v-model="country"
    placeholder="Choose a country"
    :options="[
        { label: 'France', value: 'fr' },
        { label: 'Germany', value: 'de' },
        { label: 'Japan', value: 'jp' }
    ]"
/>
```

#html
```html
<div class="ori-select ori-color_primary">
    <div class="ori-select__control-wrap">
        <select class="ori-select__control ori-size-radius_md">
            <option value="" disabled selected>Choose a country</option>
            <option value="fr">France</option>
            <option value="de">Germany</option>
            <option value="jp">Japan</option>
        </select>
        <span class="ori-select__chevron" aria-hidden="true"><!-- chevron SVG --></span>
    </div>
</div>
```
::

## Options prop

Pass a flat array of `{ label, value, disabled? }` objects. The component renders them as `<option>`
elements, with disabled items available but not selectable.

::example
  :::ori-select
  ---
  options:
    - label: Free
      value: free
    - label: Pro
      value: pro
    - label: Enterprise (contact us)
      value: ent
      disabled: true
  placeholder: Pick a plan
  ---
  :::

#vue
```vue
<OriSelect
    v-model="plan"
    placeholder="Pick a plan"
    :options="[
        { label: 'Free', value: 'free' },
        { label: 'Pro', value: 'pro' },
        { label: 'Enterprise (contact us)', value: 'ent', disabled: true }
    ]"
/>
```

#html
```html
<select class="ori-select__control …">
    <option value="" disabled selected>Pick a plan</option>
    <option value="free">Free</option>
    <option value="pro">Pro</option>
    <option value="ent" disabled>Enterprise (contact us)</option>
</select>
```
::

## Default slot

Provide hand-written `<option>` / `<optgroup>` markup as the default slot. When the slot is used it
replaces the `options`-prop rendering; the placeholder option (if any) still renders before the slot.

::example
:ori-select{placeholder="Pick a city"}

#vue
```vue
<OriSelect v-model="city" placeholder="Pick a city">
    <optgroup label="Europe">
        <option value="par">Paris</option>
        <option value="ber">Berlin</option>
    </optgroup>
    <optgroup label="Asia">
        <option value="tok">Tokyo</option>
        <option value="bkk">Bangkok</option>
    </optgroup>
</OriSelect>
```

#html
```html
<div class="ori-select ori-color_primary">
    <div class="ori-select__control-wrap">
        <select class="ori-select__control ori-size-radius_md">
            <option value="" disabled selected>Pick a city</option>
            <optgroup label="Europe">
                <option value="par">Paris</option>
                <option value="ber">Berlin</option>
            </optgroup>
            <optgroup label="Asia">
                <option value="tok">Tokyo</option>
                <option value="bkk">Bangkok</option>
            </optgroup>
        </select>
        <span class="ori-select__chevron" aria-hidden="true"><!-- chevron SVG --></span>
    </div>
</div>
```
::

## States

`disabled` uses the real native attribute. `invalid` sets `aria-invalid="true"` and switches the
border and focus ring to the danger color.

::example
  :::ori-select
  ---
  disabled: true
  options:
    - label: Cannot change
      value: x
  ---
  :::

  :::ori-select
  ---
  invalid: true
  options:
    - label: Option A
      value: a
    - label: Option B
      value: b
  placeholder: Required
  ---
  :::

#vue
```vue
<OriSelect v-model="value" disabled :options="options" />
<OriSelect v-model="value" invalid placeholder="Required" :options="options" />
```

#html
```html
<!-- disabled -->
<select class="ori-select__control …" disabled>
    …
</select>

<!-- invalid -->
<select class="ori-select__control …" aria-invalid="true">
    …
</select>
```
::

## Label, hint & error

Like [Input](https://oriui.vercel.app/components/input) and [Textarea](https://oriui.vercel.app/components/textarea), the select has built-in form
wiring — a `label` (rendered `<label for>`, no external label needed), a `hint`, an `error`
(`role="alert"`, flips `aria-invalid`, wired through `aria-describedby`), and a `required` asterisk.

::example
  :::ori-select
  ---
  options:
    - label: France
      value: fr
    - label: Germany
      value: de
  required: true
  hint: Where the order ships
  label: Country
  placeholder: Select…
  ---
  :::

  :::ori-select
  ---
  options:
    - label: Free
      value: free
    - label: Pro
      value: pro
  error: Please choose a plan
  label: Plan
  placeholder: Select…
  ---
  :::

#vue
```vue
<OriSelect v-model="country" label="Country" required hint="Where the order ships" :options="countries" />

<OriSelect v-model="plan" label="Plan" error="Please choose a plan" :options="plans" />
```

#html
```html
<div class="ori-select ori-color_primary">
    <label for="country" class="ori-select__label"
        >Country<span class="ori-select__required" aria-hidden="true">*</span></label
    >
    <div class="ori-select__control-wrap">
        <select id="country" required aria-describedby="country-hint" class="ori-select__control ori-size-radius_md">
            <option value="fr">France</option>
            <option value="de">Germany</option>
        </select>
        <span class="ori-select__chevron" aria-hidden="true"><!-- chevron SVG --></span>
    </div>
    <p id="country-hint" class="ori-select__hint">Where the order ships</p>
</div>
```
::

## Common patterns

A shipping-address form row — color, size, radius, placeholder, and required fall through together.

::example
  :::ori-select
  ---
  options:
    - label: France
      value: fr
    - label: Germany
      value: de
    - label: Japan
      value: jp
  placeholder: Country
  ---
  :::

  :::ori-select
  ---
  options:
    - label: Île-de-France
      value: idf
    - label: Bavaria
      value: bay
  placeholder: State / Province
  ---
  :::

#vue
```vue
<div style="display: flex; gap: 0.75rem; flex-wrap: wrap">
    <OriSelect
        v-model="country"
        placeholder="Country"
        name="country"
        required
        :options="countryOptions"
    />
    <OriSelect
        v-model="state"
        placeholder="State / Province"
        name="state"
        :options="stateOptions"
    />
</div>
```

#html
```html
<div style="display: flex; gap: 0.75rem; flex-wrap: wrap">
    <div class="ori-select ori-color_primary">
        <div class="ori-select__control-wrap">
            <select name="country" required class="ori-select__control ori-size-radius_md">
                <option value="" disabled selected>Country</option>
                <option value="fr">France</option>
                <option value="de">Germany</option>
                <option value="jp">Japan</option>
            </select>
            <span class="ori-select__chevron" aria-hidden="true"><!-- chevron SVG --></span>
        </div>
    </div>
    <div class="ori-select ori-color_primary">
        <div class="ori-select__control-wrap">
            <select name="state" class="ori-select__control ori-size-radius_md">
                <option value="" disabled selected>State / Province</option>
                <option value="idf">Île-de-France</option>
                <option value="bay">Bavaria</option>
            </select>
            <span class="ori-select__chevron" aria-hidden="true"><!-- chevron SVG --></span>
        </div>
    </div>
</div>
```
::

## Accessibility

The accessibility contract holds across every layer — the standalone classes and the Vue component
render the same attributes.

- The control is a native `<select>`, so the browser provides the complete dropdown, full keyboard
  interaction (arrow keys, type-ahead, Home/End), and all ARIA semantics — no custom widget needed.
- State is real attributes: native `disabled` and `aria-invalid="true"` (not classes), styled with
  attribute selectors (`:disabled`, `[aria-invalid='true']`).
- The built-in `label` renders a `<label for>` bound to the control's `useId()`-based `id`, so the
  select is named without any external markup. (You can still supply an external `<label for>` using
  the control's `id`, or pass `aria-label` / `aria-labelledby` for labelless contexts — they fall
  through to the `<select>`.)
- `hint` and `error` are wired to the control via `aria-describedby`; `error` also renders `role="alert"`
  and flips the control to `aria-invalid="true"`. `required` sets the native `required` attribute.
- The chevron is `aria-hidden="true"` and `pointer-events: none` — it is never announced and never
  intercepts clicks or keyboard events.
- The placeholder renders as a `disabled` `<option>` so it cannot be re-selected once the user makes
  a choice.
- Arbitrary native attrs (`name`, `required`, `autocomplete`, `aria-label`, `aria-labelledby`, …)
  fall through via `inheritAttrs: false` + `v-bind="$attrs"` directly to the `<select>` element.
- Focus is always visible: `:focus` shows a tokenized border + `box-shadow` ring reading
  `--ori-color` (the control sits on the page, not on a fill surface). When `invalid`, the ring uses
  the danger color.

| Key                 | Action                                              |
| ------------------- | --------------------------------------------------- |
| `Tab` / `Shift+Tab` | Moves focus to / away from the control.             |
| `Space` / `Enter`   | Opens the dropdown (browser-native).                |
| `Arrow Up` / `Down` | Cycles through options; navigates the open list.    |
| `Home` / `End`      | Jumps to the first / last option.                   |
| Type-ahead          | Selects the first option beginning with typed char. |
| `Escape`            | Closes the dropdown without changing selection.     |

## Framework API

The props, events, slots, and attribute passthrough of the **Vue** component. The standalone CSS
layer has no component API — its surface is the [classes](https://oriui.vercel.app/#classes) above. (Svelte bindings are
planned.)

### Props

| Prop          | Type                                                                   | Default     | Description                                                                                                                                     |
| ------------- | ---------------------------------------------------------------------- | ----------- | ----------------------------------------------------------------------------------------------------------------------------------------------- |
| `color`       | `ThemeColor`                                                           | `'primary'` | Accent that drives the focus-ring/border color via the ori-color utility (repoints `--ori-color`).                                              |
| `describedby` | `string`                                                               | —           | Extra element id(s) appended to `aria-describedby` (e.g. a shared form note).                                                                   |
| `disabled`    | `boolean`                                                              | `false`     | Disables the control via the real native `disabled` attribute (styled with `:disabled`).                                                        |
| `error`       | `string`                                                               | —           | Error message rendered below the control (`role="alert"`); flips the control to `aria-invalid` and wires `aria-describedby`. Replaces the hint. |
| `fluid`       | `boolean`                                                              | `false`     | Stretches the control to the full width of its container.                                                                                       |
| `hint`        | `string`                                                               | —           | Helper text below the control, wired via `aria-describedby`. Hidden while an error is shown.                                                    |
| `id`          | `string`                                                               | `useId()`   | Id applied to the native `<select>`; defaults to an SSR-safe `useId()` so the `label` (or an external `<label for>`) can target it.             |
| `invalid`     | `boolean`                                                              | `false`     | Marks the control invalid via `aria-invalid="true"`; styled with a danger border and ring. (`error` also sets this.)                            |
| `label`       | `string`                                                               | —           | Built-in `<label>` rendered above the control and wired to it via `for`.                                                                        |
| `options`     | `Array<{ label: string; value: string | number; disabled?: boolean }>` | `[]`        | Options rendered as `<option>` elements. Ignored when a default slot is provided.                                                               |
| `placeholder` | `string`                                                               | —           | Renders a disabled, selected-by-default first `<option value="">` as a non-selectable prompt.                                                   |
| `radius`      | `RadiusSize`                                                           | `'md'`      | Border radius via the `ori-size-radius_*` single-class token (`zero` · xs · sm · md · lg · xl · rounded).                                       |
| `required`    | `boolean`                                                              | `false`     | Sets the native `required` attribute and renders a `*` after the label.                                                                         |
| `size`        | `ActionSize`                                                           | `'md'`      | Control height (`ori-select_*` size sugar) and font-size (`ori-font-size_*`) (`xs`–`xxl`).                                                      |

### Events & attributes

`v-model` binds to a `string | number` via `defineModel<string | number>()` — it reads the
`modelValue` prop and emits `update:modelValue` on change:

```vue
<OriSelect v-model="selected" :options="options" />
```

OriSelect sets `inheritAttrs: false` and spreads `$attrs` onto the underlying `<select>`, so native
attributes and listeners pass through directly to the field element — not the wrapper `<div>`:

- Attributes: `name`, `required`, `autocomplete`, `aria-label`, `aria-labelledby`, …
- Listeners: `@change`, `@focus`, `@blur`, …

### Slots

| Slot      | Scope | Description                                                                                                                                           |
| --------- | ----- | ----------------------------------------------------------------------------------------------------------------------------------------------------- |
| `default` | none  | Hand-written `<option>` / `<optgroup>` markup. When present it replaces the `options`-prop rendering; the placeholder option still renders before it. |


# Skeleton

A loading placeholder that signals content is on its way. An animated shimmer sweep sweeps across the
block; on devices that request reduced motion the shimmer stops and the tinted block alone signals the
loading state. Size it with an inline `style` or a utility class — the skeleton itself carries no
intrinsic width or height beyond a `1em` minimum height.

The examples are organised by **layer**: the [class reference](https://oriui.vercel.app/#classes&#x29; is the standalone
&#x2A;*`@oriui/css`** layer, and the [Framework API](https://oriui.vercel.app/#framework-api&#x29; is the &#x2A;*`@oriui/vue`** component. Every
example is live — flip its code between **HTML** (the standalone classes, also your htmx / Astro / Svelte /
plain-HTML usage), **Vue**; HTML is the default.

## Classes

A skeleton is a single block class. Radius is a single-class token utility — one class repoints
`--ori-size-radius`, no base class needed. The Vue props in [Framework API](https://oriui.vercel.app/#framework-api) map 1:1
to these. There is no variant or color — a skeleton reads `currentcolor` from its parent for both the
tinted base and the shimmer highlight.

::class-table
---
rows:
  - class: ori-skeleton
    type: Block
    description: Required base class. Renders a tinted, animated shimmer block.
  - class: ori-size-radius_*
    type: Radius
    description: zero · xs · <b>sm</b> · md · lg · xl · rounded — <b>sm</b> is the
      default; repoints --ori-size-radius on the element.
  - class: aria-hidden=true
    type: State
    description: Always present. The skeleton is decorative; the loading region that
      owns the announcement should carry aria-busy on the consumer side.
---
::

## Text line

A single line — size it to match the text it is standing in for.

::example
:ori-skeleton{style="width: 12rem; height: 1rem"}

#vue
```vue
<OriSkeleton style="width: 12rem; height: 1rem" />
```

#html
```html
<div class="ori-skeleton" aria-hidden="true" style="width: 12rem; height: 1rem"></div>
```
::

## Circle (avatar)

`radius="rounded"` produces a pill / circle. Pair equal width and height for a round avatar
placeholder.

::example
:ori-skeleton{radius="rounded" style="width: 3rem; height: 3rem"}

#vue
```vue
<OriSkeleton radius="rounded" style="width: 3rem; height: 3rem" />
```

#html
```html
<div class="ori-skeleton ori-size-radius_rounded" aria-hidden="true" style="width: 3rem; height: 3rem"></div>
```
::

## Stacked text lines

Simulate a paragraph with a few lines of varying width.

::example
  :::ori-stack{gap="xs"}
  :ori-skeleton{style="width: 100%; height: 1rem"}

  :ori-skeleton{style="width: 80%; height: 1rem"}

  :ori-skeleton{style="width: 90%; height: 1rem"}

  :ori-skeleton{style="width: 60%; height: 1rem"}
  :::

#vue
```vue
<OriStack gap="xs">
    <OriSkeleton style="width: 100%; height: 1rem" />
    <OriSkeleton style="width: 80%; height: 1rem" />
    <OriSkeleton style="width: 90%; height: 1rem" />
    <OriSkeleton style="width: 60%; height: 1rem" />
</OriStack>
```

#html
```html
<div class="ori-stack ori-size-gap_xs" aria-busy="true" aria-label="Loading">
    <div class="ori-skeleton" aria-hidden="true" style="width: 100%; height: 1rem"></div>
    <div class="ori-skeleton" aria-hidden="true" style="width: 80%; height: 1rem"></div>
    <div class="ori-skeleton" aria-hidden="true" style="width: 90%; height: 1rem"></div>
    <div class="ori-skeleton" aria-hidden="true" style="width: 60%; height: 1rem"></div>
</div>
```
::

## Card composition

Combine a circle avatar, a title line, and a body block to stand in for a card while its data loads.
The wrapping region carries `aria-busy`.

::example
  :::ori-stack
  ---
  gap: md
  style: "max-width: 20rem; padding: 1rem; border-radius: 0.5rem; background:
    color-mix(in srgb, currentcolor 5%, transparent)"
  ---
    ::::ori-stack{cluster gap="sm" style="align-items: center"}
    :ori-skeleton{radius="rounded" style="width: 2.5rem; height: 2.5rem; flex-shrink: 0"}

      :::::ori-stack{gap="xs" style="flex: 1"}
      :ori-skeleton{style="width: 60%; height: 0.875rem"}

      :ori-skeleton{style="width: 40%; height: 0.75rem"}
      :::::
    ::::
  :::
::

:ori-skeleton{style="width: 100%; height: 6rem; margin-top: 0.25rem"}

\::

\#vue

```vue
<OriStack gap="md" style="max-width: 20rem" aria-busy="true" aria-label="Loading card">
    <!-- header: avatar + two title lines -->
    <OriStack cluster gap="sm" style="align-items: center">
        <OriSkeleton radius="rounded" style="width: 2.5rem; height: 2.5rem; flex-shrink: 0" />
        <OriStack gap="xs" style="flex: 1">
            <OriSkeleton style="width: 60%; height: 0.875rem" />
            <OriSkeleton style="width: 40%; height: 0.75rem" />
        </OriStack>
    </OriStack>
    <!-- body block -->
    <OriSkeleton style="width: 100%; height: 6rem" />
</OriStack>
```

\#html

```html
<div class="ori-stack ori-size-gap_md" style="max-width: 20rem" aria-busy="true" aria-label="Loading card">
    <!-- header: avatar + two title lines -->
    <div class="ori-cluster ori-size-gap_sm" style="align-items: center">
        <div
            class="ori-skeleton ori-size-radius_rounded"
            aria-hidden="true"
            style="width: 2.5rem; height: 2.5rem; flex-shrink: 0"
        ></div>
        <div class="ori-stack ori-size-gap_xs" style="flex: 1">
            <div class="ori-skeleton" aria-hidden="true" style="width: 60%; height: 0.875rem"></div>
            <div class="ori-skeleton" aria-hidden="true" style="width: 40%; height: 0.75rem"></div>
        </div>
    </div>
    <!-- body block -->
    <div class="ori-skeleton" aria-hidden="true" style="width: 100%; height: 6rem"></div>
</div>
```

\::

## Radius scale

The default `sm` gives a subtle rounded corner. Use `rounded` for circles and pill shapes; `zero` for
a perfectly square placeholder.

::example
:ori-skeleton{radius="zero" style="width: 4rem; height: 2rem"}

:ori-skeleton{radius="xs" style="width: 4rem; height: 2rem"}

:ori-skeleton{radius="sm" style="width: 4rem; height: 2rem"}

:ori-skeleton{radius="md" style="width: 4rem; height: 2rem"}

:ori-skeleton{radius="lg" style="width: 4rem; height: 2rem"}

:ori-skeleton{radius="xl" style="width: 4rem; height: 2rem"}

:ori-skeleton{radius="rounded" style="width: 4rem; height: 2rem"}

#vue
```vue
<OriSkeleton radius="zero" style="width: 4rem; height: 2rem" />
<OriSkeleton radius="xs" style="width: 4rem; height: 2rem" />
<OriSkeleton radius="sm" style="width: 4rem; height: 2rem" />
<OriSkeleton radius="md" style="width: 4rem; height: 2rem" />
<OriSkeleton radius="lg" style="width: 4rem; height: 2rem" />
<OriSkeleton radius="xl" style="width: 4rem; height: 2rem" />
<OriSkeleton radius="rounded" style="width: 4rem; height: 2rem" />
```

#html
```html
<!-- swap the radius class: ori-size-radius_zero → _xs / _sm / _md / _lg / _xl / _rounded -->
<div class="ori-skeleton ori-size-radius_zero" aria-hidden="true" style="width: 4rem; height: 2rem"></div>
<div class="ori-skeleton ori-size-radius_rounded" aria-hidden="true" style="width: 4rem; height: 2rem"></div>
```
::

## Accessibility

The accessibility contract holds across every layer — the standalone classes and the Vue component
render the same attributes.

- The skeleton is **decorative** — it renders `aria-hidden="true"` on every instance. A skeleton by
  itself makes no announcement.
- **The consumer owns the loading announcement.** Place `aria-busy="true"` and an `aria-label` (e.g.
  `"Loading"`) on the container that wraps one or more skeletons. Screen readers then announce the
  label when the region appears and again when `aria-busy` is removed once data arrives.
- When `prefers-reduced-motion: reduce` is active the shimmer animation is suppressed (`animation: none`). The tinted base block remains visible and continues to communicate that content is loading.
- No keyboard interaction is required; the skeleton is not focusable.

## Framework API

The props, events, and slots of the **Vue** component. The standalone CSS layer has no component
API — its surface is the [classes](https://oriui.vercel.app/#classes) above. (Svelte bindings are planned.)

### Props

| Prop     | Type              | Default | Description                                                           |
| -------- | ----------------- | ------- | --------------------------------------------------------------------- |
| `as`     | `string | object` | `'div'` | HTML tag name or component reference to render.                       |
| `radius` | `RadiusSize`      | `'sm'`  | Corner radius: `zero` · `xs` · `sm` · `md` · `lg` · `xl` · `rounded`. |

`RadiusSize`: `'zero' | 'xs' | 'sm' | 'md' | 'lg' | 'xl' | 'rounded'`

### Events & attributes

OriSkeleton declares **no custom events** and does not set `inheritAttrs: false`, so extra attributes
(`style`, `class`, `data-*`) fall through to the rendered root element. `aria-hidden="true"` is bound
directly in the template and is always present; do not override it.

### Slots

OriSkeleton has **no slots**. Size it via an inline `style` or a utility class on the element — the
skeleton expands to whatever dimensions you give it.


# Slider

A styled, accessible range control built on a native `<input type="range">`. Because the
underlying element is real HTML, the browser supplies `role="slider"`, the full keyboard contract
(arrow keys, Home/End, PageUp/PageDown), and screen-reader value announcements for free — no
JavaScript bridge needed. Colour and the filled-track portion are driven by CSS custom properties;
`v-model` carries a `number`.

The examples are organised by **layer**: the [class reference](https://oriui.vercel.app/#classes&#x29; is the standalone
&#x2A;*`@oriui/css`** layer, and the [Framework API](https://oriui.vercel.app/#framework-api&#x29; is the &#x2A;*`@oriui/vue`** component. Every
example is live — flip its code between **HTML** (the standalone classes, also your htmx / Astro / Svelte /
plain-HTML usage), **Vue**; HTML is the default.

## Classes

A slider is a block wrapper plus BEM part classes. The `ori-color_*` utility repoints the one token
the component reads everywhere (`--ori-color`). The Vue props in [Framework API](https://oriui.vercel.app/#framework-api)
map 1:1 to these.

::class-table
---
rows:
  - class: ori-slider
    type: Block
    description: Required base class (wrapper div). Full-width by default.
  - class: ori-color_*
    type: Color
    description: <b>primary</b> · secondary · success · warn · danger · info · surface
  - class: ori-slider__label
    type: Part
    description: Flex row wrapping the visible label text and optional current value.
  - class: ori-slider__value
    type: Part
    description: Current value badge inside the label row; tabular-nums, slightly dimmed.
  - class: ori-slider__input
    type: Part
    description: The native <code><input type=range></code>; receives the inline
      <code>--ori-slider-pct</code> custom property.
  - class: data-disabled
    type: State
    description: Set on the wrapper when <code>disabled</code> is true; dims the
      control and changes the cursor to not-allowed.
---
::

## Live demo

Drag either handle to see `v-model` update in real time. The two sliders share no state — each
drives its own `ref`.

::example
:slider-demo

#vue
```vue
<script setup>
import { ref } from 'vue';
const volume = ref(60);
const brightness = ref(40);
</script>

<template>
    <div style="display: flex; flex-direction: column; gap: 1.5rem; width: 100%; max-width: 24rem">
        <OriSlider v-model="volume" label="Volume" :show-value="true" />
        <OriSlider v-model="brightness" label="Brightness" color="warn" :show-value="true" :max="200" />
    </div>
</template>
```

#html
```html
<!--
  The filled portion is an inline CSS custom property — set --ori-slider-pct
  to ((value - min) / (max - min)) * 100 from your own script.
-->
<div class="ori-slider ori-color_primary" style="--ori-slider-pct: 60%">
    <label class="ori-slider__label" for="vol">
        <span>Volume</span>
        <span class="ori-slider__value">60</span>
    </label>
    <input id="vol" type="range" class="ori-slider__input" min="0" max="100" step="1" value="60" />
</div>
```
::

## Colors

Every semantic role. The filled track, the thumb, and the focus ring all read `--ori-color`.

::example
  :::ori-slider{:model-value='60' color="primary" label="primary"}
  :::

  :::ori-slider{:model-value='60' color="secondary" label="secondary"}
  :::

  :::ori-slider{:model-value='60' color="success" label="success"}
  :::

  :::ori-slider{:model-value='60' color="warn" label="warn"}
  :::

  :::ori-slider{:model-value='60' color="danger" label="danger"}
  :::

  :::ori-slider{:model-value='60' color="info" label="info"}
  :::

#vue
```vue
<OriSlider :model-value="60" color="primary" label="primary" />
<OriSlider :model-value="60" color="secondary" label="secondary" />
<OriSlider :model-value="60" color="warn" label="warn" />
<OriSlider :model-value="60" color="danger" label="danger" />
```

#html
```html
<!-- swap ori-color_primary for any semantic role -->
<div class="ori-slider ori-color_danger" style="--ori-slider-pct: 60%">
    <label class="ori-slider__label" for="s-danger"><span>danger</span></label>
    <input id="s-danger" type="range" class="ori-slider__input" min="0" max="100" step="1" value="60" />
</div>
```
::

## Range (min / max / step)

`min`, `max`, and `step` map directly to the native `<input>` attributes. The component recomputes
`--ori-slider-pct` from these, so the filled portion stays accurate.

::example
  :::ori-slider
  ---
  max: 10
  min: 0
  model-value: 4
  show-value: true
  step: 1
  label: Rating
  ---
  :::

  :::ori-slider
  ---
  max: 200
  min: 0
  model-value: 80
  show-value: true
  step: 10
  color: warn
  label: Brightness
  ---
  :::

  :::ori-slider
  ---
  max: 50
  min: -50
  model-value: 0
  show-value: true
  step: 5
  color: secondary
  label: Balance
  ---
  :::

#vue
```vue
<!-- 0–10 in whole steps -->
<OriSlider v-model="rating" :min="0" :max="10" :step="1" label="Rating" :show-value="true" />

<!-- 0–200 in steps of 10 -->
<OriSlider v-model="brightness" :min="0" :max="200" :step="10" label="Brightness" color="warn" :show-value="true" />

<!-- negative range -->
<OriSlider v-model="balance" :min="-50" :max="50" :step="5" label="Balance" color="secondary" :show-value="true" />
```

#html
```html
<div class="ori-slider ori-color_primary" style="--ori-slider-pct: 40%">
    <label class="ori-slider__label" for="rating">
        <span>Rating</span>
        <span class="ori-slider__value">4</span>
    </label>
    <input id="rating" type="range" class="ori-slider__input" min="0" max="10" step="1" value="4" />
</div>
```
::

## Show value

`show-value` renders the current number on the trailing end of the label row in a tabular-nums span.
Useful when the exact value matters to the user.

::example
  :::ori-slider{:model-value='72' show-value label="Volume"}
  :::

  :::ori-slider{:model-value='72' :show-value='false' label="Volume"}
  :::

#vue
```vue
<!-- value visible -->
<OriSlider v-model="vol" label="Volume" :show-value="true" />

<!-- value hidden (default) -->
<OriSlider v-model="vol" label="Volume" />
```

#html
```html
<!-- with value -->
<div class="ori-slider ori-color_primary" style="--ori-slider-pct: 72%">
    <label class="ori-slider__label" for="sv1">
        <span>Volume</span>
        <span class="ori-slider__value">72</span>
    </label>
    <input id="sv1" type="range" class="ori-slider__input" min="0" max="100" step="1" value="72" />
</div>

<!-- without value — omit the span -->
<div class="ori-slider ori-color_primary" style="--ori-slider-pct: 72%">
    <label class="ori-slider__label" for="sv2"><span>Volume</span></label>
    <input id="sv2" type="range" class="ori-slider__input" min="0" max="100" step="1" value="72" />
</div>
```
::

## Disabled

`disabled` sets the native `disabled` attribute on the `<input>` and adds `data-disabled` on the
wrapper, which applies 50 % opacity and a `not-allowed` cursor.

::example
  :::ori-slider{disabled :model-value='30' label="Locked"}
  :::

  :::ori-slider
  ---
  disabled: true
  model-value: 30
  color: danger
  label: Locked
  ---
  :::

#vue
```vue
<OriSlider :model-value="30" disabled label="Locked" />
```

#html
```html
<div class="ori-slider ori-color_primary" data-disabled style="--ori-slider-pct: 30%">
    <label class="ori-slider__label" for="dis"><span>Locked</span></label>
    <input id="dis" type="range" class="ori-slider__input" min="0" max="100" step="1" value="30" disabled />
</div>
```
::

## Commit on release

`update:modelValue` fires on every tick of a drag — ideal for a live preview, but it would flood an
undo history (or re-run an expensive effect) on every intermediate value. `change` fires **once**, when
the user releases the thumb or commits a keyboard step, carrying the settled `number`. Bind both:
`v-model` for the live value, `@change` for the commit.

```vue
<script setup>
import { ref } from 'vue';

const opacity = ref(100);
const undoStack = [];

function commit(value) {
    // record ONE undo step for the whole drag — not one per tick
    undoStack.push({ opacity: value });
}
</script>

<template>
    <!-- v-model tracks the live drag (thumb + fill); @change commits the settled value -->
    <OriSlider v-model="opacity" label="Opacity" :show-value="true" :min="0" :max="100" @change="commit" />
</template>
```

A drag from 100 → 40 streams `update:modelValue` the whole way, so the fill animates live — but
`change` emits a single `40` on release, so history gets one entry, not sixty. Keyboard adjustments
commit per step, though: each arrow-key press is its own `change` (one undo entry per press), since the
browser settles the value on every keystroke.

## Common patterns

A settings panel with labelled sliders — the most common real-world composition.

::example
  :::ori-slider{:model-value='75' show-value label="Volume"}
  :::

  :::ori-slider
  ---
  max: 100
  min: -100
  model-value: 50
  show-value: true
  step: 5
  color: secondary
  label: Balance
  ---
  :::

  :::ori-slider
  ---
  max: 40
  model-value: 20
  show-value: true
  color: info
  label: Bass boost
  ---
  :::

#vue
```vue
<div style="display: flex; flex-direction: column; gap: 1.25rem; max-width: 24rem">
    <OriSlider v-model="volume" label="Volume" :show-value="true" />
    <OriSlider v-model="balance" label="Balance" color="secondary" :show-value="true" :min="-100" :max="100" :step="5" />
    <OriSlider v-model="bass" label="Bass boost" color="info" :show-value="true" :max="40" />
</div>
```

#html
```html
<div style="display: flex; flex-direction: column; gap: 1.25rem; max-width: 24rem">
    <div class="ori-slider ori-color_primary" style="--ori-slider-pct: 75%">
        <label class="ori-slider__label" for="p-vol">
            <span>Volume</span><span class="ori-slider__value">75</span>
        </label>
        <input id="p-vol" type="range" class="ori-slider__input" min="0" max="100" step="1" value="75" />
    </div>
    <div class="ori-slider ori-color_secondary" style="--ori-slider-pct: 75%">
        <label class="ori-slider__label" for="p-bal">
            <span>Balance</span><span class="ori-slider__value">50</span>
        </label>
        <input id="p-bal" type="range" class="ori-slider__input" min="-100" max="100" step="5" value="50" />
    </div>
</div>
```
::

## Accessibility

The accessibility contract holds across every layer — the standalone classes and the Vue component
render the same attributes and keyboard behaviour.

- Renders a real `<input type="range">`, so the browser supplies `role="slider"`, the accessible
  value (`aria-valuenow`, `aria-valuemin`, `aria-valuemax`), and value announcements to screen
  readers with no extra ARIA needed.
- The `label` prop renders a `<label>` linked to the input via `for`/`id` (auto-generated via
  `useId()`). Without a `label`, pass an `aria-label` or `aria-labelledby` attribute — OriSlider sets
  `inheritAttrs: false` and binds `$attrs` to the `<input>`, so the name lands on the real control.
  `showValue` is a visual supplement, not a name source — pair it with `label` or `aria-label`.
- `disabled` is the real native attribute; the wrapper receives `data-disabled` for CSS only.
- The focus ring appears on the thumb (`:focus-visible`) and uses `--ori-color`, so it always
  matches the active colour role.
- For the HTML layer, set `--ori-slider-pct` inline to `((value - min) / (max - min)) * 100%` so
  the WebKit gradient fill reflects the current value; Firefox reads `::-moz-range-progress`
  directly from the element value and needs no custom property.

| Key          | Action                                                 |
| ------------ | ------------------------------------------------------ |
| `ArrowRight` | Increases value by one `step`.                         |
| `ArrowUp`    | Increases value by one `step`.                         |
| `ArrowLeft`  | Decreases value by one `step`.                         |
| `ArrowDown`  | Decreases value by one `step`.                         |
| `Home`       | Jumps to `min`.                                        |
| `End`        | Jumps to `max`.                                        |
| `PageUp`     | Increases value by a larger step (browser-determined). |
| `PageDown`   | Decreases value by a larger step (browser-determined). |

## Framework API

The props, events, and slots of the **Vue** component. The standalone CSS layer has no component
API — its surface is the [classes](https://oriui.vercel.app/#classes) above. (Svelte bindings are planned.)

### Props

| Prop         | Type         | Default     | Description                                                                      |
| ------------ | ------------ | ----------- | -------------------------------------------------------------------------------- |
| `color`      | `ThemeColor` | `'primary'` | Semantic accent: primary · secondary · success · warn · danger · info · surface. |
| `disabled`   | `boolean`    | —           | Sets native `disabled` on the input and `data-disabled` on the wrapper.          |
| `label`      | `string`     | —           | Visible `<label>` text, linked to the input via `for`/`id`.                      |
| `max`        | `number`     | `100`       | Maximum value — maps to the native `max` attribute.                              |
| `min`        | `number`     | `0`         | Minimum value — maps to the native `min` attribute.                              |
| `modelValue` | `number`     | —           | Controlled value; bind with `v-model`. Defaults to `min` when omitted.           |
| `showValue`  | `boolean`    | —           | Renders the current value in an `ori-slider__value` span beside the label.       |
| `step`       | `number`     | `1`         | Increment per arrow-key press — maps to the native `step` attribute.             |

### Events & attributes

| Event               | Payload  | Description                                                                                                                                                                                                                                          |
| ------------------- | -------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `update:modelValue` | `number` | Fired **live** on every `input` (each drag tick / arrow press); drives `v-model`.                                                                                                                                                                    |
| `change`            | `number` | Fired once when the value is **committed** — pointer release, or a keyboard step. Use it to record undo history or run a per-release side effect that must not fire per tick (see [Commit on release](https://oriui.vercel.app/#commit-on-release)). |

```vue
<OriSlider v-model="volume" label="Volume" :show-value="true" />
```

`@change` carries the committed **number**, not a DOM `Event` — it is a declared emit, so it no longer
falls through to the `<input>`. If you need the raw native event (e.g. `event.target.validity`), attach
a listener to the underlying `<input>` via a template ref.

OriSlider sets `inheritAttrs: false`, so undeclared native attributes (`aria-label`,
`aria-describedby`, `name`, `id&#x60;, …) fall through to the &#x2A;*`<input>`**, not the wrapper — they name,
describe, and submit the real control. `label` auto-generates the input `id` via `useId()`, so an
explicit `id` is only needed to override it.

### Slots

| Slot    | Description                                                                                                |
| ------- | ---------------------------------------------------------------------------------------------------------- |
| `label` | Rich label content (an icon + text, markup). Falls back to the `label` prop; keeps the for/id a11y wiring. |


# Spinner

An accessible loading indicator — renders `role="status"` with an `aria-label` (default `"Loading"`)
so assistive technology announces the busy state without any extra work. Use it standalone for a
page-level or section-level loader, or embed it inline inside a button or label.

The examples are organised by **layer**: the [class reference](https://oriui.vercel.app/#classes&#x29; is the standalone
&#x2A;*`@oriui/css`** layer, and the [Framework API](https://oriui.vercel.app/#framework-api&#x29; is the &#x2A;*`@oriui/vue`** component. Every
example is live — flip its code between **HTML** (the standalone classes, also your htmx / Astro / Svelte /
plain-HTML usage), **Vue**; HTML is the default.

## Classes

A spinner is a single block class. Each axis is one class that repoints one token — no base class
needed. The Vue props in [Framework API](https://oriui.vercel.app/#framework-api) map 1:1 to these. There is no variant or
radius — a spinner only takes a size and an optional color.

::class-table
---
rows:
  - class: ori-spinner
    type: Block
    description: Required base class.
  - class: ori-spinner_* (size)
    type: Size
    description: text (inherits) · xs · sm · md · lg · xl · xxl — <b>text</b> is the
      default; bare ori-spinner without a size modifier inherits its size from
      the surrounding font
  - class: ori-color_*
    type: Color
    description: primary · secondary · success · warn · danger · info · surface ·
      background — inherits <code>currentcolor</code> when omitted
  - class: ori-spinner_inline
    type: Layout
    description: switches to <code>inline-block</code> with a small margin so it
      sits in a line of text
  - class: role=status · aria-label
    type: State
    description: live region that announces the busy state; label defaults to <b>Loading</b>
---
::

## Sizes

`xs` → `xxl`, plus the default `text` which inherits its size from the surrounding font.

::example
:ori-spinner{color="primary" size="xs"}

:ori-spinner{color="primary" size="sm"}

:ori-spinner{color="primary" size="md"}

:ori-spinner{color="primary" size="lg"}

:ori-spinner{color="primary" size="xl"}

:ori-spinner{color="primary" size="xxl"}

#vue
```vue
<OriSpinner size="xs" color="primary" />
<OriSpinner size="sm" color="primary" />
<OriSpinner size="md" color="primary" />
<OriSpinner size="lg" color="primary" />
<OriSpinner size="xl" color="primary" />
<OriSpinner size="xxl" color="primary" />
```

#html
```html
<!-- ori-spinner_<size> sets the ring diameter; omit the size modifier to inherit from text -->
<div class="ori-spinner ori-spinner_sm ori-color_primary" role="status" aria-label="Loading"></div>
<div class="ori-spinner ori-spinner_xl ori-color_primary" role="status" aria-label="Loading"></div>
```
::

## Colors

Every semantic role. Omit `color` entirely to inherit `currentcolor` from the parent.

::example
:ori-spinner{color="primary" size="lg"}

:ori-spinner{color="secondary" size="lg"}

:ori-spinner{color="success" size="lg"}

:ori-spinner{color="warn" size="lg"}

:ori-spinner{color="danger" size="lg"}

:ori-spinner{color="info" size="lg"}

#vue
```vue
<OriSpinner color="primary" size="lg" />
<OriSpinner color="secondary" size="lg" />
<OriSpinner color="success" size="lg" />
<OriSpinner color="warn" size="lg" />
<OriSpinner color="danger" size="lg" />
<OriSpinner color="info" size="lg" />
```

#html
```html
<!-- swap the color class: ori-color_primary → _secondary / _success / _warn / _danger / _info -->
<div class="ori-spinner ori-spinner_lg ori-color_danger" role="status" aria-label="Loading"></div>
```
::

## Inline

`inline` switches the spinner to `inline-block` with a small margin so it flows in a sentence or
sits beside a label without breaking layout.

::example
  :::ori-spinner{inline color="primary" size="sm"}
  :::

#vue
```vue
<OriSpinner inline size="sm" color="primary" />
```

#html
```html
<div class="ori-spinner ori-spinner_inline ori-spinner_sm ori-color_primary" role="status" aria-label="Loading"></div>
```
::

## Custom label

Override the default `"Loading"` with a more descriptive message for the current context.

::example
:ori-spinner{color="primary" label="Saving your changes" size="md"}

#vue
```vue
<OriSpinner size="md" color="primary" label="Saving your changes" />
```

#html
```html
<div class="ori-spinner ori-spinner_md ori-color_primary" role="status" aria-label="Saving your changes"></div>
```
::

## Common patterns

A full-page loader and a button-level spinner — the everyday compositions.

::example
:ori-spinner{color="primary" label="Loading page" size="xl"}

#vue
```vue
<!-- page-level loader, centred by the parent -->
<div style="display: flex; justify-content: center; padding: 2rem">
    <OriSpinner size="xl" color="primary" label="Loading page" />
</div>

<!-- spinner hidden inside a labelled button (parent owns the announcement) -->
<button class="ori-button …" aria-busy="true">
    <OriSpinner :inline="true" size="sm" aria-hidden="true" />
    <span>Saving</span>
</button>
```

#html
```html
<!-- page-level -->
<div style="display: flex; justify-content: center; padding: 2rem">
    <div class="ori-spinner ori-spinner_xl ori-color_primary" role="status" aria-label="Loading page"></div>
</div>

<!-- inside a loading button: spinner is decorative, parent carries the announcement -->
<button class="ori-button …" aria-busy="true">
    <div class="ori-spinner ori-spinner_inline ori-spinner_sm" role="status" aria-hidden="true"></div>
    <span class="ori-button__text">Saving</span>
</button>
```
::

## Accessibility

The accessibility contract holds across every layer — the standalone classes and the Vue component
render the same attributes.

- Renders a `<div role="status">` — a polite live region that announces its `aria-label` to
  screen readers when it appears.
- The default `aria-label` is `"Loading"`. Use the `label` prop to provide a more specific
  message (`"Saving your changes"`, `"Fetching results"`, …).
- When the spinner is decorative — e.g. inside an `aria-busy` button that already carries the
  announcement — pass `aria-hidden="true"` as a fall-through attribute so it is invisible to
  assistive technology.
- No keyboard interaction is required; the spinner is not focusable.

## Framework API

The props, events, and slots of the **Vue** component. The standalone CSS layer has no component
API — its surface is the [classes](https://oriui.vercel.app/#classes) above. (Svelte bindings are planned.)

### Props

| Prop     | Type         | Default     | Description                                                                   |
| -------- | ------------ | ----------- | ----------------------------------------------------------------------------- |
| `color`  | `ThemeColor` | —           | Semantic color role. Omit to inherit `currentcolor` from the parent.          |
| `inline` | `boolean`    | `false`     | Renders as `inline-block` with a small margin for use inside text or buttons. |
| `label`  | `string`     | `'Loading'` | `aria-label` text read by assistive technology.                               |
| `size`   | `ActionSize` | `'text'`    | Ring size (`xs`–`xxl`). Default `'text'` inherits its size from the font.     |

`ThemeColor`: `'primary' | 'secondary' | 'success' | 'warn' | 'danger' | 'info' | 'surface' | 'background'`

`ActionSize`: `'text' | 'xs' | 'sm' | 'md' | 'lg' | 'xl' | 'xxl'`

### Events & attributes

OriSpinner declares **no custom events** and does not set `inheritAttrs: false`, so any extra
attributes you pass (e.g. `class`, `style`, `data-*`) fall through to the root `<div>`. The
`aria-label` is set from the `label` prop (the template binds `:aria-label="label"` directly);
change it via that prop, not as a fall-through attribute.

When the spinner is embedded inside a control that already has an accessible name (a loading
button, for example), set `aria-hidden="true"` on the spinner — because `aria-hidden` is not
explicitly bound in the template it does fall through to the root element, so the live region
will be hidden from assistive technology.

### Slots

OriSpinner has **no slots**. Its visual output is a pure CSS ring driven entirely by class and
attribute props.


# Stack

The workhorse layout primitive — two flex modes in one component. A **stack** (`ori-stack`) is a
flex column: children flow top-to-bottom with a consistent gap. A **cluster** (`ori-cluster`) is a
wrapping flex row: children flow left-to-right, wrap onto new lines, and are centered on the
cross-axis — ideal for tag clouds, button groups, and badge sets.

The examples are organised by **layer**: the [class reference](https://oriui.vercel.app/#classes&#x29; is the standalone
&#x2A;*`@oriui/css`** layer, and the [Framework API](https://oriui.vercel.app/#framework-api&#x29; is the &#x2A;*`@oriui/vue`** component. Every
example is live — flip its code between **HTML** (the standalone classes, also your htmx / Astro / Svelte /
plain-HTML usage), **Vue**; HTML is the default.

## Classes

Stack and cluster each have one block class. Gap is a single-class token utility —
one class repoints `--ori-size-gap`, no cascade conflict. The Vue props in
[Framework API](https://oriui.vercel.app/#framework-api) map 1:1 to these.

::class-table
---
rows:
  - class: ori-stack
    type: Block
    description: Flex column. Children stack top-to-bottom, separated by the gap token.
  - class: ori-cluster
    type: Block
    description: Flex row that wraps. Children flow left-to-right and wrap;
      cross-axis centered by default.
  - class: ori-size-gap_*
    type: Gap
    description: zero · xs · sm · <b>md</b> · lg · xl — repoints --ori-size-gap on
      the container.
---
::

## Vertical stack

Children laid out in a column, separated by `gap`. Default gap is `md` when the `gap` prop is
provided; without a gap class the gap is whatever `--ori-size-gap` resolves to at that scope.

::example
  :::ori-stack{gap="md"}
  :ori-button{text="First item" variant="outline"}

  :ori-button{text="Second item" variant="outline"}

  :ori-button{text="Third item" variant="outline"}
  :::

#vue
```vue
<OriStack gap="md">
    <OriButton text="First item" variant="outline" />
    <OriButton text="Second item" variant="outline" />
    <OriButton text="Third item" variant="outline" />
</OriStack>
```

#html
```html
<div class="ori-stack ori-size-gap_md">
    <button class="ori-button ori-variant_outline">First item</button>
    <button class="ori-button ori-variant_outline">Second item</button>
    <button class="ori-button ori-variant_outline">Third item</button>
</div>
```
::

## Cluster (wrapping row)

Set `cluster` to switch to the wrapping row. Tags, chips, and button groups all fit here — the
cluster wraps gracefully at narrow widths.

::example
  :::ori-stack{cluster gap="sm"}
  :ori-button{text="Vue 3" variant="tonal"}

  :ori-button{text="TypeScript" variant="tonal"}

  :ori-button{text="Vite" variant="tonal"}

  :ori-button{text="Nuxt" variant="tonal"}

  :ori-button{text="Vitest" variant="tonal"}

  :ori-button{text="axe-core" variant="tonal"}
  :::

#vue
```vue
<OriStack cluster gap="sm">
    <OriButton text="Vue 3" variant="tonal" />
    <OriButton text="TypeScript" variant="tonal" />
    <OriButton text="Vite" variant="tonal" />
    <OriButton text="Nuxt" variant="tonal" />
    <OriButton text="Vitest" variant="tonal" />
    <OriButton text="axe-core" variant="tonal" />
</OriStack>
```

#html
```html
<div class="ori-cluster ori-size-gap_sm">
    <button class="ori-button ori-variant_tonal">Vue 3</button>
    <button class="ori-button ori-variant_tonal">TypeScript</button>
    <button class="ori-button ori-variant_tonal">Vite</button>
    <button class="ori-button ori-variant_tonal">Nuxt</button>
    <button class="ori-button ori-variant_tonal">Vitest</button>
    <button class="ori-button ori-variant_tonal">axe-core</button>
</div>
```
::

## Gap scale

`zero` collapses the gap entirely; `xl` spreads items wide. The `gap` prop emits a single
`ori-size-gap_<size>` class — the token does the rest.

::example
  :::ori-stack{gap="zero"}
  :ori-button{size="sm" text="zero" variant="fill"}

  :ori-button{size="sm" text="zero" variant="fill"}
  :::

  :::ori-stack{gap="xs"}
  :ori-button{size="sm" text="xs" variant="tonal"}

  :ori-button{size="sm" text="xs" variant="tonal"}
  :::

  :::ori-stack{gap="sm"}
  :ori-button{size="sm" text="sm" variant="outline"}

  :ori-button{size="sm" text="sm" variant="outline"}
  :::

  :::ori-stack{gap="md"}
  :ori-button{size="sm" text="md" variant="tonal"}

  :ori-button{size="sm" text="md" variant="tonal"}
  :::

  :::ori-stack{gap="lg"}
  :ori-button{size="sm" text="lg" variant="outline"}

  :ori-button{size="sm" text="lg" variant="outline"}
  :::

  :::ori-stack{gap="xl"}
  :ori-button{size="sm" text="xl" variant="fill"}

  :ori-button{size="sm" text="xl" variant="fill"}
  :::

#vue
```vue
<OriStack gap="zero"> … </OriStack>
<OriStack gap="xs"> … </OriStack>
<OriStack gap="sm"> … </OriStack>
<OriStack gap="md"> … </OriStack>
<OriStack gap="lg"> … </OriStack>
<OriStack gap="xl"> … </OriStack>
```

#html
```html
<!-- swap the gap class: ori-size-gap_zero → _xs / _sm / _md / _lg / _xl -->
<div class="ori-stack ori-size-gap_lg">…</div>
```
::

## Alignment

`align` maps to CSS `align-items` and `justify` to `justify-content`, applied as inline styles.
Useful for centering a cluster horizontally, or stretching stack children to full width.

::example
  :::ori-stack{cluster gap="sm" justify="center"}
  :ori-button{text="Centered" variant="fill"}

  :ori-button{text="Cluster" variant="tonal"}

  :ori-button{text="Row" variant="outline"}
  :::

#vue
```vue
<!-- Cluster with centered main axis -->
<OriStack cluster gap="sm" justify="center">
    <OriButton text="Centered" variant="fill" />
    <OriButton text="Cluster" variant="tonal" />
    <OriButton text="Row" variant="outline" />
</OriStack>

<!-- Stack with cross-axis centering (children narrower than the container) -->
<OriStack gap="md" align="center">
    <OriButton text="Narrow A" variant="outline" />
    <OriButton text="Narrow B" variant="outline" />
</OriStack>
```

#html
```html
<!-- justify-content via inline style -->
<div class="ori-cluster ori-size-gap_sm" style="justify-content: center">
    <button class="ori-button ori-variant_fill">Centered</button>
    <button class="ori-button ori-variant_tonal">Cluster</button>
    <button class="ori-button ori-variant_outline">Row</button>
</div>

<!-- align-items via inline style -->
<div class="ori-stack ori-size-gap_md" style="align-items: center">
    <button class="ori-button ori-variant_outline">Narrow A</button>
    <button class="ori-button ori-variant_outline">Narrow B</button>
</div>
```
::

## Polymorphic (`as`)

Stack renders a `<div>` by default. Pass `as` to use any tag — `ul` / `ol` for semantic lists,
`section` for document structure, or a router component.

::example
  :::ori-stack{as="ul" gap="sm"}
  :ori-card{text="List item rendered in a stack." title="Item one"}

  :ori-card{text="Same gap, semantic ul element." title="Item two"}
  :::

#vue
```vue
<!-- Semantic list: each child would be an <li> in a real component -->
<OriStack as="ul" gap="sm">
    <OriCard title="Item one" text="List item rendered in a stack." />
    <OriCard title="Item two" text="Same gap, semantic ul element." />
</OriStack>
```

#html
```html
<ul class="ori-stack ori-size-gap_sm">
    <li>…</li>
    <li>…</li>
</ul>
```
::

## Common patterns

### Form field column

A vertical stack holding labeled inputs — the most common use in forms.

::example
  :::ori-stack{gap="lg"}
  :ori-input{label="Full name" placeholder="Jane Smith"}

  :ori-input{label="Email" placeholder="jane@example.com"}

    ::::ori-stack{cluster gap="sm" justify="flex-end"}
    :ori-button{text="Cancel" variant="text"}

    :ori-button{text="Save" variant="fill"}
    ::::
  :::
::

\::

\#vue

```vue
<OriStack gap="lg">
    <OriInput label="Full name" placeholder="Jane Smith" />
    <OriInput label="Email" placeholder="jane@example.com" />
    <OriStack cluster gap="sm" justify="flex-end">
        <OriButton text="Cancel" variant="text" />
        <OriButton text="Save" variant="fill" />
    </OriStack>
</OriStack>
```

\#html

```html
<div class="ori-stack ori-size-gap_lg">
    <!-- inputs -->
    <div class="ori-cluster ori-size-gap_sm" style="justify-content: flex-end">
        <button class="ori-button ori-variant_text">Cancel</button>
        <button class="ori-button ori-variant_fill">Save</button>
    </div>
</div>
```

\::

### Card grid with a cluster header

A cluster for the header actions above a stack of cards.

::example
  :::ori-stack{gap="md"}
    ::::ori-stack
    ---
    cluster: true
    align: center
    gap: sm
    justify: space-between
    ---
    :ori-button{text="Filter" variant="outline"}

    :ori-button{text="New" variant="fill"}
    ::::
  :::
::

:ori-card{text="Design system refactor — in progress." title="Project Alpha"}

:ori-card{text="Accessibility audit — review pending." title="Project Beta"}

\::

\#vue

```vue
<OriStack gap="md">
    <OriStack cluster gap="sm" justify="space-between" align="center">
        <OriButton text="Filter" variant="outline" />
        <OriButton text="New" variant="fill" />
    </OriStack>
    <OriCard title="Project Alpha" text="Design system refactor — in progress." />
    <OriCard title="Project Beta" text="Accessibility audit — review pending." />
</OriStack>
```

\#html

```html
<div class="ori-stack ori-size-gap_md">
    <div class="ori-cluster ori-size-gap_sm" style="justify-content: space-between; align-items: center">
        <button class="ori-button ori-variant_outline">Filter</button>
        <button class="ori-button ori-variant_fill">New</button>
    </div>
    <div class="ori-card ori-size-radius_lg ori-variant_fill ori-color_surface">
        <div class="ori-card__header">
            <div class="ori-card__headline"><div class="ori-card__title">Project Alpha</div></div>
        </div>
        <div class="ori-card__body">Design system refactor — in progress.</div>
    </div>
    <div class="ori-card ori-size-radius_lg ori-variant_fill ori-color_surface">
        <div class="ori-card__header">
            <div class="ori-card__headline"><div class="ori-card__title">Project Beta</div></div>
        </div>
        <div class="ori-card__body">Accessibility audit — review pending.</div>
    </div>
</div>
```

\::

## Accessibility

Stack and cluster are **purely presentational containers**. They carry no ARIA role, no
`tabindex`, and no focusable state of their own — they are transparent to assistive technology.

- Use a semantically appropriate `as` tag when the layout conveys document structure: `as="ul"` /
  `as="ol"` for lists, `as="section"` for landmark regions (add `aria-label`), `as="nav"` for
  navigation clusters.
- No keyboard interaction is defined for the container itself; keyboard behavior is owned entirely
  by the children.

## Framework API

The props, events, and slots of the **Vue** component. The standalone CSS layer has no component
API — its surface is the [classes](https://oriui.vercel.app/#classes) above. (Svelte bindings are planned.)

### Props

| Prop      | Type              | Default | Description                                                                                    |
| --------- | ----------------- | ------- | ---------------------------------------------------------------------------------------------- |
| `align`   | `string`          | —       | CSS `align-items` value applied as an inline style on the container.                           |
| `as`      | `string | object` | `'div'` | HTML tag name or component reference to render (e.g. `'ul'`, `'section'`, a router component). |
| `cluster` | `boolean`         | `false` | Switches from a flex column (`ori-stack`) to a wrapping flex row (`ori-cluster`).              |
| `gap`     | `GapSize`         | —       | Gap between children: `zero` · `xs` · `sm` · `md` · `lg` · `xl`. Emits `ori-size-gap_<size>`.  |
| `justify` | `string`          | —       | CSS `justify-content` value applied as an inline style on the container.                       |

`GapSize = 'zero' | 'xs' | 'sm' | 'md' | 'lg' | 'xl'`

### Events & attributes

OriStack declares **no custom events** and does not set `inheritAttrs: false`, so extra attributes
(`id`, `class`, `style`, `data-*`, event listeners, etc.) fall through to the rendered root element.

### Slots

| Slot      | Description                                      |
| --------- | ------------------------------------------------ |
| `default` | The children to lay out in the stack or cluster. |


# Surface

An **elevated floating surface** — a lifted panel with a surface background, an optional hairline, a
corner radius, and a mode-aware shadow, and **nothing else**. No padding, no header/title semantics: it
is just the box, and the caller owns the layout inside. It's the building block for chrome that floats
over content — a toolbar island, a zoom control, a side panel, a menu popout's container — and the
**elevation** counterpart to [Card](https://oriui.vercel.app/components/card), which is a *content* card (padding + header /
title / body / actions).

The examples are organised by **layer**: the [class reference](https://oriui.vercel.app/#classes&#x29; is the standalone
&#x2A;*`@oriui/css`** layer, and the [Framework API](https://oriui.vercel.app/#framework-api&#x29; is the &#x2A;*`@oriui/vue`** component.

## Classes

A block class plus two single-class axes — the elevation modifier and the shared `.ori-size-radius_*`
utility. Bordered is a modifier; the surface colour is fixed (it's chrome).

::class-table
---
rows:
  - class: ori-surface
    type: Block
    description: Required base class. Surface background + on-surface text + lg
      radius; a block-level box with no padding of its own.
  - class: ori-surface_elevation-sm | -md | -lg
    type: Modifier
    description: "Shadow depth, mapped to the mode-aware --ori-shadow-{sm,md,lg}
      tokens (light: tinted ink; dark: deeper shadow). Default lg."
  - class: ori-surface_bordered
    type: Modifier
    description: Adds a hairline border (a color-mix of on-surface). Present by
      default via the bordered prop; drop it for a shadow-only surface.
  - class: ori-size-radius_*
    type: Radius
    description: Repoints --ori-size-radius (zero · xs · sm · md · lg · xl ·
      rounded). The block bakes lg as the default.
---
::

## Elevation

Three depths, mode-aware. Drag the theme toggle and the shadow re-tunes automatically (tinted ink in
light, deeper shadow in dark).

::example
  :::ori-surface{elevation="sm" style="padding: 1rem"}
  Small
  :::

  :::ori-surface{elevation="md" style="padding: 1rem"}
  Medium
  :::

  :::ori-surface{elevation="lg" style="padding: 1rem"}
  Large (default)
  :::

#vue
```vue
<OriSurface elevation="sm" style="padding: 1rem">Small</OriSurface>
<OriSurface elevation="md" style="padding: 1rem">Medium</OriSurface>
<OriSurface elevation="lg" style="padding: 1rem">Large (default)</OriSurface>
```

#html
```html
<div class="ori-surface ori-surface_elevation-md ori-surface_bordered ori-size-radius_lg" style="padding: 1rem">
    Medium
</div>
```
::

## Radius & border

`radius` repoints the shared radius token; `bordered="false"` drops the hairline for a shadow-only
surface.

::example
  :::ori-surface{radius="sm" style="padding: 1rem"}
  Tight corners
  :::

  :::ori-surface{:bordered='false' style="padding: 1rem"}
  No border — shadow only
  :::

#vue
```vue
<OriSurface radius="sm" style="padding: 1rem">Tight corners</OriSurface>
<OriSurface :bordered="false" style="padding: 1rem">No border — shadow only</OriSurface>
```
::

## Composing chrome

The intended use: wrap floating chrome — a [toolbar](https://oriui.vercel.app/components/toolbar), a control cluster — so it
lifts off the content beneath. `OriSurface` supplies the box; the toolbar supplies the behaviour.

::example
  :::ori-surface{style="padding: 0.5rem; display: inline-block"}
    ::::ori-toolbar{label="Format"}
    :ori-toolbar-button{text="Bold"}

    :ori-toolbar-button{text="Italic"}

    :ori-toolbar-separator

    :ori-toolbar-button{color="primary" text="Link"}
    ::::
  :::
::

\::

\#vue

```vue
<OriSurface style="padding: 0.5rem; display: inline-block">
    <OriToolbar label="Format">
        <OriToolbarButton text="Bold" />
        <OriToolbarButton text="Italic" />
        <OriToolbarSeparator />
        <OriToolbarButton text="Link" color="primary" />
    </OriToolbar>
</OriSurface>
```

\::

## Framework API

The props of the **Vue** component. The standalone CSS layer's surface is the [classes](https://oriui.vercel.app/#classes)
above.

### Props

| Prop        | Type                 | Default | Description                                                                                 |
| ----------- | -------------------- | ------- | ------------------------------------------------------------------------------------------- |
| `as`        | `string | object`    | `'div'` | Element / component to render as.                                                           |
| `bordered`  | `boolean`            | `true`  | A hairline border around the surface. Set `false` for a shadow-only surface.                |
| `elevation` | `'sm' | 'md' | 'lg'` | `'lg'`  | Shadow depth → `--ori-shadow-{sm,md,lg}` (mode-aware).                                      |
| `radius`    | `RadiusSize`         | `'lg'`  | Corner radius; repoints `--ori-size-radius` via the utility (zero · xs · sm · md · lg · …). |

### Slots

| Slot      | Description                                                                 |
| --------- | --------------------------------------------------------------------------- |
| `default` | The surface content — the caller's own layout (OriSurface adds no padding). |

## Accessibility

`OriSurface` is a **presentational container** — by default a plain `<div>` with no role, so it adds
nothing to the accessibility tree (correct for pure chrome). If the surface is a **landmark** (a
complementary panel, a region worth navigating to), give it the semantics yourself: render `as="aside"`,
or add `role="region"` / `role="complementary"` with an `aria-label` — attributes fall through to the
element. Don't add a role without a name; an unnamed `region` is a nuisance to screen-reader users.


# Switch

An on/off toggle built on a &#x2A;*real `<input type="checkbox" role="switch">`** — kept in the DOM
(visually hidden over a track + thumb) so keyboard, focus, and form submission work for free, and
assistive technology announces it as a switch. `v-model` is a boolean. The "on" track color and the
`:focus-visible` ring both come from the `ori-color` token; the track and thumb scale with
`ori-font-size` so size is a single prop.

The examples are organised by **layer**: the [class reference](https://oriui.vercel.app/#classes&#x29; is the standalone
&#x2A;*`@oriui/css`** layer, and the [Framework API](https://oriui.vercel.app/#framework-api&#x29; is the &#x2A;*`@oriui/vue`** component. Every
example is live — flip its code between **HTML** (the standalone classes, also your htmx / Astro / Svelte /
plain-HTML usage), **Vue**; HTML is the default.

## Classes

A switch is a block class on the `<label>` wrapper plus two single-class token utilities — one class
per axis, no base class needed. The Vue props in [Framework API](https://oriui.vercel.app/#framework-api) map 1:1 to these.

::class-table
---
rows:
  - class: ori-switch
    type: Block
    description: Required base class — placed on the wrapping <code><label></code>.
  - class: ori-color_*
    type: Color
    description: <b>primary</b> · secondary · success · warn · danger · info · surface
  - class: ori-font-size_*
    type: Size
    description: xs · sm · <b>md</b> · lg · xl · xxl — the track and thumb scale with this.
  - class: ori-switch__input
    type: Part
    description: The visually-hidden native <code><input type=checkbox role=switch></code>.
  - class: ori-switch__track
    type: Part
    description: The visible pill track; <code>aria-hidden</code>.
  - class: ori-switch__thumb
    type: Part
    description: The sliding circle inside the track; <code>aria-hidden</code>.
  - class: ori-switch__label
    type: Part
    description: Optional visible text label beside the track.
  - class: ori-switch_disabled
    type: State
    description: Added by the component when <code>disabled</code> is true; also
      sets the native <code>disabled</code> attribute on the input.
---
::

## Colors

Every semantic color role. The track fill and the focus ring both use `--ori-color`.

::example
:ori-switch{color="primary" label="Primary (off)"}

  :::ori-switch{model-value color="primary" label="Primary (on)"}
  :::

:ori-switch{color="secondary" label="Secondary"}

:ori-switch{color="success" label="Success"}

:ori-switch{color="warn" label="Warn"}

:ori-switch{color="danger" label="Danger"}

:ori-switch{color="info" label="Info"}

#html
```html
<label class="ori-switch ori-color_primary ori-font-size_md" for="s1">
    <input id="s1" type="checkbox" role="switch" class="ori-switch__input" />
    <span class="ori-switch__track" aria-hidden="true"><span class="ori-switch__thumb"></span></span>
    <span class="ori-switch__label">Primary</span>
</label>
<!-- swap the color class: ori-color_primary → ori-color_danger / ori-color_success / ori-color_warn / ori-color_info -->
```

#vue
```vue
<OriSwitch v-model="on" label="Primary" color="primary" />
<OriSwitch v-model="on" label="Danger" color="danger" />
<OriSwitch v-model="on" label="Info" color="info" />
```
::

## Sizes

`xs` → `xxl`. A single `ori-font-size_*` class scales both the label text and the track/thumb geometry.

::example
:ori-switch{label="xs" size="xs"}

:ori-switch{label="sm" size="sm"}

:ori-switch{label="md" size="md"}

:ori-switch{label="lg" size="lg"}

:ori-switch{label="xl" size="xl"}

#html
```html
<!-- track and thumb scale off ori-font-size_* -->
<label class="ori-switch ori-color_primary ori-font-size_sm" for="sm">
    <input id="sm" type="checkbox" role="switch" class="ori-switch__input" />
    <span class="ori-switch__track" aria-hidden="true"><span class="ori-switch__thumb"></span></span>
    <span class="ori-switch__label">sm</span>
</label>
<label class="ori-switch ori-color_primary ori-font-size_xl" for="xl">
    <input id="xl" type="checkbox" role="switch" class="ori-switch__input" />
    <span class="ori-switch__track" aria-hidden="true"><span class="ori-switch__thumb"></span></span>
    <span class="ori-switch__label">xl</span>
</label>
```

#vue
```vue
<OriSwitch v-model="on" label="sm" size="sm" />
<OriSwitch v-model="on" label="xl" size="xl" />
```
::

## States

`disabled` sets the native `disabled` on the `<input>` and adds `ori-switch_disabled` (reduced
opacity + `not-allowed` cursor) on the wrapper. `invalid` sets `aria-invalid="true"` on the input.
`required` sets the native `required`.

::example
  :::ori-switch{disabled label="Disabled off"}
  :::

  :::ori-switch{disabled model-value label="Disabled on"}
  :::

#html
```html
<label class="ori-switch ori-switch_disabled ori-color_primary ori-font-size_md" for="d1">
    <input id="d1" type="checkbox" role="switch" class="ori-switch__input" disabled />
    <span class="ori-switch__track" aria-hidden="true"><span class="ori-switch__thumb"></span></span>
    <span class="ori-switch__label">Disabled off</span>
</label>
<label class="ori-switch ori-switch_disabled ori-color_primary ori-font-size_md" for="d2">
    <input id="d2" type="checkbox" role="switch" class="ori-switch__input" disabled checked />
    <span class="ori-switch__track" aria-hidden="true"><span class="ori-switch__thumb"></span></span>
    <span class="ori-switch__label">Disabled on</span>
</label>
```

#vue
```vue
<OriSwitch v-model="on" label="Disabled off" disabled />
<!-- pass a true initial value to show the on state -->
<OriSwitch :modelValue="true" label="Disabled on" disabled />
```
::

## Invalid

`invalid` wires `aria-invalid="true"` so screen readers announce the error state.

::example
  :::ori-switch{invalid color="danger" label="Required field"}
  :::

#html
```html
<label class="ori-switch ori-color_danger ori-font-size_md" for="inv">
    <input id="inv" type="checkbox" role="switch" class="ori-switch__input" aria-invalid="true" required />
    <span class="ori-switch__track" aria-hidden="true"><span class="ori-switch__thumb"></span></span>
    <span class="ori-switch__label">Required field</span>
</label>
```

#vue
```vue
<OriSwitch v-model="accepted" label="Required field" :invalid="!accepted" color="danger" required />
```
::

## Without a label

Pass no `label` prop to render the track alone. Always pair a label-less switch with an external
`aria-label` or a visible text element connected via `aria-labelledby`.

::example
:ori-switch{ariaLabel="Dark mode"}

#html
```html
<label class="ori-switch ori-color_primary ori-font-size_md" for="dm">
    <input id="dm" type="checkbox" role="switch" class="ori-switch__input" aria-label="Dark mode" />
    <span class="ori-switch__track" aria-hidden="true"><span class="ori-switch__thumb"></span></span>
</label>
```

#vue
```vue
<OriSwitch v-model="darkMode" aria-label="Dark mode" />
```
::

## Common patterns

A settings row — switch on the right aligned to a description — is the most common real-world use.

::example
:ori-switch{color="primary" label="Email notifications" size="md"}

:ori-switch{color="secondary" label="Dark mode" size="md"}

  :::ori-switch{disabled label="Auto-save" size="md"}
  :::

#html
```html
<div style="display: flex; flex-direction: column; gap: 0.75rem">
    <label class="ori-switch ori-color_primary ori-font-size_md" for="p1">
        <input id="p1" type="checkbox" role="switch" class="ori-switch__input" />
        <span class="ori-switch__track" aria-hidden="true"><span class="ori-switch__thumb"></span></span>
        <span class="ori-switch__label">Email notifications</span>
    </label>
    <label class="ori-switch ori-color_secondary ori-font-size_md" for="p2">
        <input id="p2" type="checkbox" role="switch" class="ori-switch__input" />
        <span class="ori-switch__track" aria-hidden="true"><span class="ori-switch__thumb"></span></span>
        <span class="ori-switch__label">Dark mode</span>
    </label>
    <label class="ori-switch ori-switch_disabled ori-color_primary ori-font-size_md" for="p3">
        <input id="p3" type="checkbox" role="switch" class="ori-switch__input" disabled />
        <span class="ori-switch__track" aria-hidden="true"><span class="ori-switch__thumb"></span></span>
        <span class="ori-switch__label">Auto-save</span>
    </label>
</div>
```

#vue
```vue
<div style="display: flex; flex-direction: column; gap: 0.75rem">
    <OriSwitch v-model="emailNotifs" label="Email notifications" color="primary" />
    <OriSwitch v-model="darkMode" label="Dark mode" color="secondary" />
    <OriSwitch v-model="autoSave" label="Auto-save" disabled />
</div>
```
::

## Accessibility

The accessibility contract holds across every layer — the standalone classes and the Vue component
render the same attributes and keyboard behaviour.

- Renders a real `<input type="checkbox" role="switch">` so keyboard interaction, form submission,
  and screen-reader announcements work without any JavaScript bridges.
- The wrapping `<label>` is linked to the input by `for`/`id` (auto-generated via `useId()` unless
  `id` is supplied) — clicking the label text or the track both toggle the switch.
- The visual track and thumb are `aria-hidden="true"`; the input is the only element in the
  accessibility tree.
- `disabled` is the real native attribute (not a class); `invalid` sets `aria-invalid="true"`.
- A label-less switch must receive an accessible name via `aria-label` or `aria-labelledby` passed
  as an attribute (it falls through to the `<input>`).
- `:focus-visible` outline appears on the track (using `--ori-color`) so the focus indicator is
  always visible without disrupting the unfocused appearance.

| Key     | Action                     |
| ------- | -------------------------- |
| `Space` | Toggles the switch on/off. |
| `Tab`   | Moves focus to the switch. |

## Framework API

The props, events, and slots of the **Vue** component. The standalone CSS layer has no component
API — its surface is the [classes](https://oriui.vercel.app/#classes) above. (Svelte bindings are planned.)

### Props

| Prop       | Type         | Default     | Description                                                                                        |
| ---------- | ------------ | ----------- | -------------------------------------------------------------------------------------------------- |
| `color`    | `ThemeColor` | `'primary'` | Semantic color for the "on" track fill and the focus ring.                                         |
| `disabled` | `boolean`    | `false`     | Disables the control — sets native `disabled` and adds `ori-switch_disabled` on the wrapper.       |
| `id`       | `string`     | —           | Overrides the auto-generated `useId()` id that links the `<label>` to the `<input>`.               |
| `invalid`  | `boolean`    | —           | Sets `aria-invalid="true"` on the input; pair with a visible error message.                        |
| `label`    | `string`     | —           | Visible text label rendered beside the track. Omit to render the track alone.                      |
| `required` | `boolean`    | —           | Sets the native `required` attribute on the input.                                                 |
| `size`     | `ActionSize` | `'md'`      | Controls both label text size and track/thumb geometry (`xs` · `sm` · `md` · `lg` · `xl` · `xxl`). |

### Events & attributes

OriSwitch uses `defineModel<boolean>()` for two-way binding — bind with `v-model` to read the
checked state and emit `update:modelValue` when it toggles.

```vue
<OriSwitch v-model="enabled" label="Notifications" />
```

Because `inheritAttrs: false` is set and `v-bind="$attrs"` is forwarded to the `<input>`, all
native input attributes and listeners fall through to the real control:

- `@change`, `@focus`, `@blur` land on the `<input>`.
- `name`, `form`, `aria-describedby`, `aria-label`, `data-*` pass through transparently.

### Slots

| Slot      | Falls back to | Description                                                                                                     |
| --------- | ------------- | --------------------------------------------------------------------------------------------------------------- |
| `default` | `label` prop  | Visible text label rendered inside the native `<label>`, beside the track. Omit both to render the track alone. |


# Tabs

An accessible tabs widget with automatic activation. The tablist holds a roving tabindex so
`Tab` / `Shift+Tab` enter and leave the group as a single keyboard stop; arrow keys move between
tabs and immediately select them. State is expressed through real ARIA attributes — `aria-selected`
drives both the active indicator and the label colour; `disabled` is the native button attribute.

The examples are organised by **layer**: the [class reference](https://oriui.vercel.app/#classes&#x29; is the standalone
&#x2A;*`@oriui/css`** layer, and the [Framework API](https://oriui.vercel.app/#framework-api&#x29; is the &#x2A;*`@oriui/vue`** component. Every
example is live — flip its code between **HTML** (the standalone classes, also your htmx / Astro / Svelte /
plain-HTML usage), **Vue**; HTML is the default.

## Classes

A tabs widget is a block class plus single-class token utilities — one class repoints one token, no
base class needed. The Vue props in [Framework API](https://oriui.vercel.app/#framework-api) map 1:1 to these.

::class-table
---
rows:
  - class: ori-tabs
    type: Block
    description: Required base class. Root flex container; column layout
      (horizontal) or row layout (vertical). Baked default accent is primary;
      override with ori-color_* to change the indicator and ring.
  - class: ori-tabs_vertical
    type: Modifier
    description: "Vertical orientation: row flex layout, column tablist, right
      side-bar indicator instead of bottom underline."
  - class: ori-color_*
    type: Color
    description: <b>primary</b> · secondary · success · warn · danger · info ·
      surface — indicator and focus ring accent.
  - class: ori-tabs__list
    type: Part
    description: The role=tablist container; bottom border in horizontal layout,
      right border in vertical layout.
  - class: ori-tabs__tab
    type: Part
    description: A real button with role=tab. Active state via aria-selected=true
      (indicator scales in, label colour shifts). Disabled via native disabled
      attribute.
  - class: ori-tabs__panel
    type: Part
    description: A role=tabpanel with tabindex=0 and aria-labelledby its tab. Only
      the active panel is shown.
  - class: aria-selected · disabled
    type: State
    description: Real attributes, not classes. aria-selected=true scales the after
      indicator; disabled dims and blocks.
---
::

The selected tab's label reads the AA-safe `--ori-color-text` tone (not the raw role) — see
[Design tokens](https://oriui.vercel.app/guides/design-tokens#text-the-on-surface-foreground).

## Anatomy

```text
div.ori-tabs  [ori-color_primary]
  div.ori-tabs__list  [role=tablist, aria-orientation]
    button.ori-tabs__tab  [role=tab, aria-selected, aria-controls, tabindex]  × N
  div.ori-tabs__panel  [role=tabpanel, aria-labelledby, tabindex=0]  × N
```

## Basic

::example
  :::ori-tabs
  ---
  tabs:
    - value: overview
      label: Overview
    - value: specs
      label: Specs
    - value: reviews
      label: Reviews
  ---
  :::

#vue
```vue
<OriTabs
    v-model="active"
    :tabs="[
        { value: 'overview', label: 'Overview' },
        { value: 'specs', label: 'Specs' },
        { value: 'reviews', label: 'Reviews' }
    ]"
>
    <template #overview>Overview content goes here.</template>
    <template #specs>Technical specifications.</template>
    <template #reviews>Customer reviews.</template>
</OriTabs>
```

#html
```html
<div class="ori-tabs ori-color_primary">
    <div class="ori-tabs__list" role="tablist" aria-orientation="horizontal">
        <button
            id="tabs-1-tab-0"
            class="ori-tabs__tab"
            type="button"
            role="tab"
            aria-selected="true"
            aria-controls="tabs-1-panel-0"
            tabindex="0"
        >
            Overview
        </button>
        <button
            id="tabs-1-tab-1"
            class="ori-tabs__tab"
            type="button"
            role="tab"
            aria-selected="false"
            aria-controls="tabs-1-panel-1"
            tabindex="-1"
        >
            Specs
        </button>
        <button
            id="tabs-1-tab-2"
            class="ori-tabs__tab"
            type="button"
            role="tab"
            aria-selected="false"
            aria-controls="tabs-1-panel-2"
            tabindex="-1"
        >
            Reviews
        </button>
    </div>
    <div id="tabs-1-panel-0" class="ori-tabs__panel" role="tabpanel" aria-labelledby="tabs-1-tab-0" tabindex="0">
        Overview content goes here.
    </div>
    <div id="tabs-1-panel-1" class="ori-tabs__panel" role="tabpanel" aria-labelledby="tabs-1-tab-1" tabindex="0" hidden>
        Technical specifications.
    </div>
    <!-- … -->
</div>
```
::

## Colors

Every semantic role. The accent color is shared by the active indicator and the focus ring.

::example
  :::ori-tabs
  ---
  tabs:
    - value: a
      label: Tab A
    - value: b
      label: Tab B
  color: primary
  ---
  :::

  :::ori-tabs
  ---
  tabs:
    - value: a
      label: Tab A
    - value: b
      label: Tab B
  color: secondary
  ---
  :::

  :::ori-tabs
  ---
  tabs:
    - value: a
      label: Tab A
    - value: b
      label: Tab B
  color: success
  ---
  :::

  :::ori-tabs
  ---
  tabs:
    - value: a
      label: Tab A
    - value: b
      label: Tab B
  color: danger
  ---
  :::

#vue
```vue
<OriTabs color="primary" :tabs="tabs" />
<OriTabs color="secondary" :tabs="tabs" />
<OriTabs color="success" :tabs="tabs" />
<OriTabs color="danger" :tabs="tabs" />
```

#html
```html
<!-- swap the color: ori-color_primary → _secondary / _success / _danger / _warn / _info -->
<div class="ori-tabs ori-color_secondary">…</div>
```
::

## Vertical orientation

`orientation="vertical"` stacks the tablist in a column to the left with a right side-bar indicator.
Arrow axis switches to Up / Down.

::example
  :::ori-tabs
  ---
  tabs:
    - value: general
      label: General
    - value: security
      label: Security
    - value: notifications
      label: Notifications
  orientation: vertical
  ---
  :::

#vue
```vue
<OriTabs
    v-model="section"
    orientation="vertical"
    :tabs="[
        { value: 'general', label: 'General' },
        { value: 'security', label: 'Security' },
        { value: 'notifications', label: 'Notifications' }
    ]"
>
    <template #general>General settings.</template>
    <template #security>Security settings.</template>
    <template #notifications>Notification preferences.</template>
</OriTabs>
```

#html
```html
<!-- add ori-tabs_vertical; list gets aria-orientation="vertical" -->
<div class="ori-tabs ori-tabs_vertical ori-color_primary">
    <div class="ori-tabs__list" role="tablist" aria-orientation="vertical">
        <button class="ori-tabs__tab" role="tab" aria-selected="true" tabindex="0">General</button>
        <button class="ori-tabs__tab" role="tab" aria-selected="false" tabindex="-1">Security</button>
        <button class="ori-tabs__tab" role="tab" aria-selected="false" tabindex="-1">Notifications</button>
    </div>
    <div class="ori-tabs__panel" role="tabpanel" tabindex="0">General settings.</div>
    <!-- … -->
</div>
```
::

## Disabled tabs

Set `disabled: true` on individual tab items to lock those tabs. Disabled tabs are real `<button disabled>` — they are removed from tab order, unreachable by keyboard nav, and visually dimmed.

::example
  :::ori-tabs
  ---
  tabs:
    - value: active
      label: Active
    - value: locked
      label: Locked
      disabled: true
    - value: another
      label: Another
  ---
  :::

#vue
```vue
<OriTabs
    v-model="active"
    :tabs="[
        { value: 'active', label: 'Active' },
        { value: 'locked', label: 'Locked', disabled: true },
        { value: 'another', label: 'Another' }
    ]"
/>
```

#html
```html
<button class="ori-tabs__tab" role="tab" aria-selected="false" tabindex="-1" disabled>Locked</button>
```
::

## Panel slots — per-tab content

Use a named slot matching the tab's `value` to give each panel its own markup. A scoped `#default="{ tab }"` slot is the fallback for shared/uniform content across all panels.

::example
  :::ori-tabs
  ---
  tabs:
    - value: preview
      label: Preview
    - value: code
      label: Code
    - value: docs
      label: Docs
  ---
  :::

#vue
```vue
<!-- Primary: a named slot per value — distinct markup per panel -->
<OriTabs v-model="tab" :tabs="tabs">
    <template #preview>
        <p>Rendered preview of the component.</p>
    </template>
    <template #code>
        <pre>const x = 1;</pre>
    </template>
    <template #docs>
        <p>Documentation and API reference.</p>
    </template>
</OriTabs>

<!-- Fallback: one shared template that reads the active tab from scope -->
<OriTabs v-model="tab" :tabs="tabs">
    <template #default="{ tab }">
        <p>Content for: {{ tab.label }}</p>
    </template>
</OriTabs>
```

#html
```html
<!-- Panels are arbitrary markup inside each ori-tabs__panel -->
<div class="ori-tabs__panel" role="tabpanel" tabindex="0">
    <p>Rendered preview of the component.</p>
</div>
```
::

## Uncontrolled (no v-model)

When `v-model` is omitted, the component auto-selects the first non-disabled tab immediately and stays self-contained. If the active value ever points at a missing or disabled tab, it self-heals to the first non-disabled tab.

::example
  :::ori-tabs
  ---
  tabs:
    - value: one
      label: First
    - value: two
      label: Second
    - value: three
      label: Third
  ---
  :::

#vue
```vue
<!-- No v-model — the component manages its own active state -->
<OriTabs
    :tabs="[
        { value: 'one', label: 'First' },
        { value: 'two', label: 'Second' },
        { value: 'three', label: 'Third' }
    ]"
/>
```

#html
```html
<!-- Same markup; the first tab gets aria-selected="true" by default -->
<div class="ori-tabs ori-color_primary">…</div>
```
::

## Common patterns

Vertical orientation, a non-default color, and named panel slots — a common settings sidebar pattern.

::example
  :::ori-tabs
  ---
  tabs:
    - value: profile
      label: Profile
    - value: account
      label: Account
    - value: privacy
      label: Privacy
  color: secondary
  orientation: vertical
  ---
  :::

#vue
```vue
<OriTabs
    v-model="settingsSection"
    orientation="vertical"
    color="secondary"
    :tabs="[
        { value: 'profile', label: 'Profile' },
        { value: 'account', label: 'Account' },
        { value: 'privacy', label: 'Privacy' }
    ]"
>
    <template #profile>
        <h2>Profile settings</h2>
        <p>Update your name, avatar, and bio.</p>
    </template>
    <template #account>
        <h2>Account settings</h2>
        <p>Manage your email address and password.</p>
    </template>
    <template #privacy>
        <h2>Privacy settings</h2>
        <p>Control who can see your activity.</p>
    </template>
</OriTabs>
```

#html
```html
<div class="ori-tabs ori-tabs_vertical ori-color_secondary">
    <div class="ori-tabs__list" role="tablist" aria-orientation="vertical">
        <button class="ori-tabs__tab" role="tab" aria-selected="true" tabindex="0">Profile</button>
        <button class="ori-tabs__tab" role="tab" aria-selected="false" tabindex="-1">Account</button>
        <button class="ori-tabs__tab" role="tab" aria-selected="false" tabindex="-1">Privacy</button>
    </div>
    <div class="ori-tabs__panel" role="tabpanel" tabindex="0">
        <h2>Profile settings</h2>
        <p>Update your name, avatar, and bio.</p>
    </div>
    <!-- … -->
</div>
```
::

## Accessibility

The accessibility contract holds across every layer — the standalone classes and the Vue component
render the same attributes and keyboard behaviour.

- Full WAI-ARIA Tabs pattern, driven by the headless [`useTabs`](https://oriui.vercel.app/headless/use-tabs) composable (the
  shared Vue + Svelte behaviour). `role="tablist"` on the list with `aria-orientation` reflecting the
  `orientation` prop.
- Each tab is a real `<button role="tab">` with a `useId()`-derived stable id, `aria-selected`
  (`"true"` / `"false"`), `aria-controls` pointing at its panel id, and a **roving tabindex**
  (selected = `0`, others = `-1`) so `Tab` / `Shift+Tab` enter and leave the group as a single stop.
- Each panel is `role="tabpanel"` with `tabindex="0"` and `aria-labelledby` its owning tab — the
  panel is focusable so keyboard users can reach its content.
- Activation is **automatic** — focus move also selects. Arrow keys move to the previous/next
  non-disabled tab with wrap-around.
- Disabled tabs are real `<button disabled>` — removed from tab order, not focusable, not selectable,
  and skipped by arrow-key navigation.
- Focus is always visible: `:focus-visible` on both the tab button and the panel, using
  `var(--ori-color, currentcolor)` so the ring colour matches the active indicator.
- Tab/panel id pairs are SSR-safe via `useId()`.

| Key                        | Action                                                                   |
| -------------------------- | ------------------------------------------------------------------------ |
| `Tab`                      | Moves focus into the tablist (to the selected tab) or past it.           |
| `Shift+Tab`                | Moves focus out of the tablist (or from the panel back before the list). |
| `ArrowRight` / `ArrowLeft` | Horizontal: selects and focuses the next / previous non-disabled tab.    |
| `ArrowDown` / `ArrowUp`    | Vertical: selects and focuses the next / previous non-disabled tab.      |
| `Home`                     | Selects and focuses the first non-disabled tab.                          |
| `End`                      | Selects and focuses the last non-disabled tab.                           |

## Framework API

The props, events, and slots of the **Vue** component. The standalone CSS layer has no component
API — its surface is the [classes](https://oriui.vercel.app/#classes) above. (Svelte bindings are planned.)

### Props

| Prop          | Type                                                                   | Default                      | Description                                                                                                                |
| ------------- | ---------------------------------------------------------------------- | ---------------------------- | -------------------------------------------------------------------------------------------------------------------------- |
| `color`       | `ThemeColor`                                                           | `'primary'`                  | Active-tab accent: drives the indicator (underline / side-bar), the active tab label colour, and the focus ring.           |
| `label`       | `string`                                                               | —                            | Accessible name for the tablist (→ `aria-label`). WAI-ARIA recommends naming a tablist, especially with several on a page. |
| `modelValue`  | `string | number`                                                      | first non-disabled tab value | Active tab value (`v-model`). Auto-defaults to the first non-disabled tab; self-heals if the value becomes invalid.        |
| `orientation` | `'horizontal' | 'vertical'`                                            | `'horizontal'`               | Layout + keyboard axis. `horizontal` = row tablist with underline; `vertical` = column tablist with right side-bar.        |
| `tabs`        | `Array<{ value: string | number; label: string; disabled?: boolean }>` | — (**required**)             | The set of tabs. Each item: `value` (unique key), `label` (visible text), optional `disabled`.                             |

### Events & attributes

| Event               | Payload           | Description                                                                           |
| ------------------- | ----------------- | ------------------------------------------------------------------------------------- |
| `update:modelValue` | `string | number` | Emitted when the user activates a tab (via click or keyboard). Use `v-model` to bind. |

OriTabs does not set `inheritAttrs: false`, so extra attributes (`class`, `data-*`, …) fall through
to the root `div.ori-tabs`.

### Slots

| Slot      | Scope                                                                    | Description                                                                                                                                                              |
| --------- | ------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `tab`     | `{ tab: { value: string | number; label: string; disabled?: boolean } }` | **Tab trigger.** Custom content for the tab button — icon, count badge, and the like. Applies to every tab; read the per-tab item from scope. Falls back to `tab.label`. |
| `<value>` | `{ tab: { value: string | number; label: string; disabled?: boolean } }` | **Primary.** A per-value named slot — name the slot by the tab's value (e.g. `#account` for value `'account'`). Numeric values are stringified for the slot name.        |
| `default` | `{ tab: { value: string | number; label: string; disabled?: boolean } }` | **Fallback.** A scoped default slot rendered for any tab that has no matching named slot — one shared template for uniform content. Read the per-panel tab from scope.   |


# Tag

A compact label for categorising, filtering, or annotating content — status chips, keyword
badges, and removable filter pills. State is expressed through real attributes: `aria-disabled`
disables the tag and its close button without removing it from the DOM.

The examples are organised by **layer**: the [class reference](https://oriui.vercel.app/#classes&#x29; is the standalone
&#x2A;*`@oriui/css`** layer, and the [Framework API](https://oriui.vercel.app/#framework-api&#x29; is the &#x2A;*`@oriui/vue`** component. Every
example is live — flip its code between **HTML** (the standalone classes, also your htmx / Astro / Svelte /
plain-HTML usage), **Vue**; HTML is the default.

## Classes

A tag is a block class plus single-class token utilities — one class repoints one token, no base
class needed. The Vue props in [Framework API](https://oriui.vercel.app/#framework-api) map 1:1 to these.

::class-table
---
rows:
  - class: ori-tag
    type: Block
    description: Required base class.
  - class: ori-variant_*
    type: Style
    description: fill · <b>tonal</b> · outline · text · plain
  - class: ori-color_*
    type: Color
    description: <b>primary</b> · secondary · success · warn · danger · info · surface
  - class: ori-font-size_*
    type: Size
    description: xs · <b>sm</b> · md · lg · xl · xxl — drives the label scale
  - class: ori-size-radius_*
    type: Radius
    description: zero · xs · sm · md · lg · xl · <b>rounded</b>
  - class: ori-tag__icon
    type: Part
    description: icon element (prepend or append)
  - class: ori-tag__text
    type: Part
    description: label text element
  - class: ori-tag__close · ori-tag__close-icon
    type: Part
    description: close button and its icon (present when closable)
  - class: aria-disabled=true
    type: State
    description: real attribute — dims the tag and blocks pointer events
---
::

Like Button, the non-fill variants (the default `tonal` included) paint the label with the AA-safe
`--ori-color-text` tone rather than the raw role — see
[Design tokens](https://oriui.vercel.app/guides/design-tokens#text-the-on-surface-foreground).

## Variants

Five visual styles, all driven by the `ori-variant_*` single-class token.

::example
:ori-tag{text="Fill" variant="fill"}

:ori-tag{text="Tonal" variant="tonal"}

:ori-tag{text="Outline" variant="outline"}

:ori-tag{text="Text" variant="text"}

:ori-tag{text="Plain" variant="plain"}

#vue
```vue
<OriTag text="Fill" variant="fill" />
<OriTag text="Tonal" variant="tonal" />
<OriTag text="Outline" variant="outline" />
<OriTag text="Text" variant="text" />
<OriTag text="Plain" variant="plain" />
```

#html
```html
<span class="ori-tag ori-variant_fill ori-color_primary ori-font-size_sm ori-size-radius_rounded">
    <span class="ori-tag__text">Fill</span>
</span>
<!-- swap the variant: ori-variant_fill → _tonal / _outline / _text / _plain -->
<span class="ori-tag ori-variant_tonal ori-color_primary ori-font-size_sm ori-size-radius_rounded">
    <span class="ori-tag__text">Tonal</span>
</span>
```
::

## Colors

Every semantic role. Variant and color compose freely.

::example
:ori-tag{color="primary" text="primary"}

:ori-tag{color="secondary" text="secondary"}

:ori-tag{color="success" text="success"}

:ori-tag{color="warn" text="warn"}

:ori-tag{color="danger" text="danger"}

:ori-tag{color="info" text="info"}

:ori-tag{color="surface" text="surface"}

#vue
```vue
<OriTag text="primary" color="primary" />
<OriTag text="secondary" color="secondary" />
<OriTag text="success" color="success" />
<OriTag text="warn" color="warn" />
<OriTag text="danger" color="danger" />
<OriTag text="info" color="info" />
<OriTag text="surface" color="surface" />
```

#html
```html
<span class="ori-tag ori-variant_tonal ori-color_danger ori-font-size_sm ori-size-radius_rounded">
    <span class="ori-tag__text">danger</span>
</span>
```
::

Variant x color compose freely — e.g. a filled success tag or an outlined danger one:

::example
:ori-tag{color="success" text="Published" variant="fill"}

:ori-tag{color="danger" text="Blocked" variant="outline"}

:ori-tag{color="info" text="Beta" variant="tonal"}

:ori-tag{color="warn" text="Draft" variant="text"}

#vue
```vue
<OriTag text="Published" variant="fill" color="success" />
<OriTag text="Blocked" variant="outline" color="danger" />
<OriTag text="Beta" variant="tonal" color="info" />
<OriTag text="Draft" variant="text" color="warn" />
```

#html
```html
<span class="ori-tag ori-variant_fill ori-color_success ori-font-size_sm ori-size-radius_rounded">
    <span class="ori-tag__text">Published</span>
</span>
```
::

## Sizes

`xs` → `xxl`. The size drives the label scale via `ori-font-size_*`. Default is `sm`.

::example
:ori-tag{size="xs" text="xs"}

:ori-tag{size="sm" text="sm"}

:ori-tag{size="md" text="md"}

:ori-tag{size="lg" text="lg"}

:ori-tag{size="xl" text="xl"}

#vue
```vue
<OriTag text="xs" size="xs" />
<OriTag text="sm" size="sm" />
<OriTag text="md" size="md" />
<OriTag text="lg" size="lg" />
<OriTag text="xl" size="xl" />
```

#html
```html
<span class="ori-tag ori-variant_tonal ori-color_primary ori-font-size_xs ori-size-radius_rounded">
    <span class="ori-tag__text">xs</span>
</span>
<span class="ori-tag ori-variant_tonal ori-color_primary ori-font-size_lg ori-size-radius_rounded">
    <span class="ori-tag__text">lg</span>
</span>
```
::

## Radius

From `zero` (square) to the default `rounded` (pill).

::example
:ori-tag{radius="zero" text="zero"}

:ori-tag{radius="sm" text="sm"}

:ori-tag{radius="md" text="md"}

:ori-tag{radius="lg" text="lg"}

:ori-tag{radius="rounded" text="rounded"}

#vue
```vue
<OriTag text="zero" radius="zero" />
<OriTag text="sm" radius="sm" />
<OriTag text="md" radius="md" />
<OriTag text="rounded" radius="rounded" />
```

#html
```html
<span class="ori-tag ori-variant_tonal ori-color_primary ori-font-size_sm ori-size-radius_zero">
    <span class="ori-tag__text">zero</span>
</span>
```
::

## With icons

`prependIcon` places an icon before the label; `appendIcon` places one after. Both accept an SVG
path string. They can be used together.

::example
:ori-tag{prepend-icon="M9 16.2 4.8 12l-1.4 1.4L9 19 21 7l-1.4-1.4z" text="Verified"}

:ori-tag{append-icon="M19 19H5V5h7V3H5a2 2 0 0 0-2 2v14a2 2 0 0 0 2 2h14a2 2 0 0 0 2-2v-7h-2v7zM14 3v2h3.59l-9.83 9.83 1.41 1.41L19 6.41V10h2V3h-7z" color="info" text="External"}

  :::ori-tag
  ---
  color: warn
  prepend-icon: M1 21h22L12 2 1 21zm12-3h-2v-2h2v2zm0-4h-2v-4h2v4z
  text: Warning
  variant: fill
  ---
  :::

#vue
```vue
<OriTag text="Verified" prependIcon="M9 16.2 4.8 12l-1.4 1.4L9 19 21 7l-1.4-1.4z" />
<OriTag text="External" appendIcon="M19 19H5V5h7V3H5…" color="info" />
<OriTag text="Warning" prependIcon="M1 21h22L12 2…" color="warn" variant="fill" />
```

#html
```html
<span class="ori-tag ori-variant_tonal ori-color_primary ori-font-size_sm ori-size-radius_rounded">
    <i class="ori-icon ori-tag__icon" aria-hidden="true">
        <svg viewBox="0 0 24 24"><path d="M9 16.2 4.8 12l-1.4 1.4L9 19 21 7l-1.4-1.4z" /></svg>
    </i>
    <span class="ori-tag__text">Verified</span>
</span>
```
::

## Closable

`closable` appends a close button. Clicking it emits a `close` event — your handler removes the tag.
`closeLabel` sets the button's `aria-label` (default `Remove`).

::example
  :::ori-tag{closable text="React"}
  :::

  :::ori-tag{closable color="success" text="Vue"}
  :::

  :::ori-tag
  ---
  closable: true
  color: danger
  text: Svelte
  variant: outline
  ---
  :::

#vue
```vue
<OriTag v-for="tag in tags" :key="tag" :text="tag" closable @close="removeTag(tag)" />
```

#html
```html
<span class="ori-tag ori-variant_tonal ori-color_primary ori-font-size_sm ori-size-radius_rounded">
    <span class="ori-tag__text">React</span>
    <button type="button" class="ori-tag__close" aria-label="Remove">
        <i class="ori-icon ori-tag__close-icon" aria-hidden="true">
            <svg viewBox="0 0 24 24">
                <path d="M6.4 19 5 17.6l5.6-5.6L5 6.4 6.4 5l5.6 5.6L17.6 5 19 6.4 13.4 12l5.6 5.6-1.4 1.4-5.6-5.6Z" />
            </svg>
        </i>
    </button>
</span>
```
::

## Disabled

`disabled` applies `aria-disabled="true"` to the root span, dimming the tag and blocking pointer
events including the close button.

::example
  :::ori-tag{disabled text="Archived"}
  :::

  :::ori-tag{disabled text="Archived" variant="outline"}
  :::

  :::ori-tag{closable disabled text="Archived"}
  :::

#vue
```vue
<OriTag text="Archived" disabled />
<OriTag text="Archived" disabled variant="outline" />
<OriTag text="Archived" disabled closable />
```

#html
```html
<span class="ori-tag ori-variant_tonal ori-color_primary ori-font-size_sm ori-size-radius_rounded" aria-disabled="true">
    <span class="ori-tag__text">Archived</span>
</span>
```
::

## Common patterns

A filter chip list and a status badge in a table row — the everyday compositions.

::example
  :::ori-tag
  ---
  closable: true
  color: success
  prepend-icon: M2 3h3.5L12 15l6.5-12H22L12 21z
  text: Vue
  ---
  :::

  :::ori-tag
  ---
  closable: true
  color: info
  prepend-icon: M3 3h18v18H3V3zm10.71 14.29a3 3 0 0 0 4.24 0l-1.41-1.42a1 1 0 0
    1-1.42 1.42 1 1 0 0 1 0-1.42l-1.41-1.41a3 3 0 0 0 0 4.24z
  text: TypeScript
  ---
  :::

  :::ori-tag{closable color="warn" text="Vite"}
  :::

#vue
```vue
<!-- filter chip list -->
<div style="display: flex; flex-wrap: wrap; gap: 0.5rem">
    <OriTag
        v-for="filter in activeFilters"
        :key="filter.value"
        :text="filter.label"
        :color="filter.color"
        closable
        @close="removeFilter(filter.value)"
    />
</div>
```

#html
```html
<!-- filter chip list -->
<div style="display: flex; flex-wrap: wrap; gap: 0.5rem">
    <span class="ori-tag ori-variant_tonal ori-color_success ori-font-size_sm ori-size-radius_rounded">
        <span class="ori-tag__text">Vue</span>
        <button type="button" class="ori-tag__close" aria-label="Remove">
            <i class="ori-icon ori-tag__close-icon" aria-hidden="true">
                <svg viewBox="0 0 24 24">
                    <path
                        d="M6.4 19 5 17.6l5.6-5.6L5 6.4 6.4 5l5.6 5.6L17.6 5 19 6.4 13.4 12l5.6 5.6-1.4 1.4-5.6-5.6Z"
                    />
                </svg>
            </i>
        </button>
    </span>
</div>
```
::

## Accessibility

The accessibility contract holds across every layer — the standalone classes and the Vue component
render the same attributes.

- The root element is a `<span>` (non-interactive). When the tag is purely decorative or
  informational, no additional role is required.
- `disabled` sets `aria-disabled="true"` (not the boolean `disabled`) on the root span — the tag
  stays in the accessibility tree. The nested close `<button>` gets the boolean `disabled`
  attribute so it is unreachable via keyboard when the tag is disabled.
- The close button has an explicit `aria-label` (default `Remove`); it is a real `<button type="button">` with a visible `:focus-visible` ring.
- Icon elements inside the tag carry `aria-hidden="true"` — they are decorative.
- When tags are part of an interactive group (e.g. a filter chip list), wrap the group in an element
  with `role="group"` and an `aria-label` describing the set (e.g. `aria-label="Active filters"`).

| Key     | Element      | Action                                    |
| ------- | ------------ | ----------------------------------------- |
| `Tab`   | Close button | Moves focus to the close button.          |
| `Enter` | Close button | Activates the close button (emits close). |
| `Space` | Close button | Activates the close button (native).      |

## Framework API

The props, events, slots, and attributes of the **Vue** component. The standalone CSS layer has no
component API — its surface is the [classes](https://oriui.vercel.app/#classes) above. (Svelte bindings are planned.)

### Props

| Prop          | Type                                              | Default     | Description                                                                                  |
| ------------- | ------------------------------------------------- | ----------- | -------------------------------------------------------------------------------------------- |
| `appendIcon`  | `string`                                          | —           | SVG path for an icon rendered after the label.                                               |
| `closable`    | `boolean`                                         | `false`     | Shows a close button that emits `close` when clicked.                                        |
| `closeLabel`  | `string`                                          | `'Remove'`  | `aria-label` for the close button.                                                           |
| `color`       | `ThemeColor`                                      | `'primary'` | Semantic role: `primary` · `secondary` · `success` · `warn` · `danger` · `info` · `surface`. |
| `disabled`    | `boolean`                                         | `false`     | Sets `aria-disabled="true"` on the root and `disabled` on the close button.                  |
| `prependIcon` | `string`                                          | —           | SVG path for an icon rendered before the label.                                              |
| `radius`      | `RadiusSize`                                      | `'rounded'` | Corner radius (`zero` · `xs` · `sm` · `md` · `lg` · `xl` · `rounded`).                       |
| `size`        | `ActionSize`                                      | `'sm'`      | Label scale (`xs` · `sm` · `md` · `lg` · `xl` · `xxl`).                                      |
| `text`        | `string`                                          | —           | Tag label. Alternatively use the `default` slot.                                             |
| `variant`     | `'fill' | 'tonal' | 'outline' | 'text' | 'plain'` | `'tonal'`   | Visual style.                                                                                |

### Events & attributes

| Event   | Payload | Description                                               |
| ------- | ------- | --------------------------------------------------------- |
| `close` | —       | Emitted when the close button is clicked (closable only). |

OriTag does not set `inheritAttrs: false`, so any extra attributes (`class`, `data-*`,
`aria-label`, …) fall through to the root `<span>`.

### Slots

| Slot      | Description                                                                                 |
| --------- | ------------------------------------------------------------------------------------------- |
| `prepend` | Decorator before the label. Falls back to the `prependIcon` `<ori-icon>` when not provided. |
| `default` | Replaces the text prop content. Rendered inside `ori-tag__text`; use for rich labels.       |
| `append`  | Decorator after the label. Falls back to the `appendIcon` `<ori-icon>` when not provided.   |


# Textarea

A labelled, accessible multiline text field with `v-model`. State is expressed through real
attributes — the native `disabled`, `aria-invalid` when there is an error, and an `aria-describedby`
that points at the rendered hint or error. The label is wired to the field with `for`/`id`
(auto-generated via `useId` when you don't pass one). Unlike a single-line input the field has no
fixed height — it grows from a `rows`-based min-height and stays user-resizable.

The examples are organised by **layer**: the [class reference](https://oriui.vercel.app/#classes&#x29; is the standalone
&#x2A;*`@oriui/css`** layer, and the [Framework API](https://oriui.vercel.app/#framework-api&#x29; is the &#x2A;*`@oriui/vue`** component. Every
example is live — flip its code between **HTML** (the standalone classes, also your htmx / Astro / Svelte /
plain-HTML usage), **Vue**; HTML is the default.

## Classes

A textarea is a block wrapper plus single-class token utilities — one class repoints one token, no
base class needed. The `ori-color_*` accent drives the focus ring; the idle border is a neutral,
theme-aware blend. The Vue props in [Framework API](https://oriui.vercel.app/#framework-api) map 1:1 to these.

::class-table
---
rows:
  - class: ori-textarea
    type: Block
    description: Required base class (wrapper div).
  - class: ori-textarea_*
    type: Style
    description: <b>outline</b> · fill
  - class: ori-color_*
    type: Color
    description: <b>primary</b> · secondary · success · warn · danger · info ·
      surface · background (focus ring accent)
  - class: ori-textarea_* (size)
    type: Size
    description: xs · sm · <b>md</b> · lg · xl · xxl (sets min-height on wrapper via
      --ori-size-action)
  - class: ori-size-radius_*
    type: Radius
    description: zero · xs · sm · <b>md</b> · lg · xl · rounded (field corners)
  - class: ori-font-size_*
    type: Font
    description: xs · sm · <b>md</b> · lg · xl · xxl (label + field text scale)
  - class: ori-textarea__label · ori-textarea__required · ori-textarea__field ·
      ori-textarea__hint · ori-textarea__error
    type: Part
    description: label / required-asterisk / textarea / helper / error elements
  - class: ori-textarea_fluid
    type: Layout
    description: full-width (stretches wrapper to 100 %)
  - class: disabled · aria-invalid · aria-describedby
    type: State
    description: real attributes, not classes
---
::

## Variants

Two visual styles — `outline` (default, border visible at rest) and `fill` (tinted background, no
border).

::example
:ori-textarea{label="Outline" placeholder="Type here..." variant="outline"}

:ori-textarea{label="Fill" placeholder="Type here..." variant="fill"}

#vue
```vue
<OriTextarea v-model="value" label="Outline" placeholder="Type here..." variant="outline" />
<OriTextarea v-model="value" label="Fill" placeholder="Type here..." variant="fill" />
```

#html
```html
<!-- default: bare ori-textarea is already outline + primary + md -->
<div class="ori-textarea ori-textarea_outline">
    <label class="ori-textarea__label" for="t1">Outline</label>
    <textarea id="t1" rows="3" placeholder="Type here..." class="ori-textarea__field"></textarea>
</div>

<!-- swap the variant: ori-textarea_outline → ori-textarea_fill -->
<div class="ori-textarea ori-textarea_fill">
    <label class="ori-textarea__label" for="t1b">Fill</label>
    <textarea id="t1b" rows="3" placeholder="Type here..." class="ori-textarea__field"></textarea>
</div>
```
::

## Colors

The `ori-color_*` class controls the focus ring (and the danger color inherits for error text).

::example
:ori-textarea{color="primary" label="primary" placeholder="primary"}

:ori-textarea{color="secondary" label="secondary" placeholder="secondary"}

:ori-textarea{color="success" label="success" placeholder="success"}

:ori-textarea{color="danger" label="danger" placeholder="danger"}

#vue
```vue
<OriTextarea v-model="value" label="primary" color="primary" />
<OriTextarea v-model="value" label="danger" color="danger" />
```

#html
```html
<div class="ori-textarea ori-color_danger">
    <label class="ori-textarea__label" for="t2">danger</label>
    <textarea id="t2" rows="3" class="ori-textarea__field"></textarea>
</div>
```
::

## Sizes

`xs` → `xxl`. The size drives both the field min-height (via `ori-textarea_*` size sugar on the
wrapper) and the text scale (`ori-font-size_*`).

::example
:ori-textarea{label="xs" placeholder="Extra small" size="xs"}

:ori-textarea{label="sm" placeholder="Small" size="sm"}

:ori-textarea{label="md" placeholder="Medium" size="md"}

:ori-textarea{label="lg" placeholder="Large" size="lg"}

:ori-textarea{label="xl" placeholder="Extra large" size="xl"}

#vue
```vue
<OriTextarea v-model="value" label="sm" size="sm" />
<OriTextarea v-model="value" label="xl" size="xl" />
```

#html
```html
<!-- ori-textarea_xl sets min-height on the wrapper; ori-font-size_xl scales the text -->
<div class="ori-textarea ori-textarea_xl ori-font-size_xl">
    <label class="ori-textarea__label" for="t3">xl</label>
    <textarea id="t3" rows="3" class="ori-textarea__field"></textarea>
</div>
```
::

## Radius

From `zero` (square) through the default `md` to `rounded` (heavily rounded corners).

::example
:ori-textarea{label="zero" placeholder="Square" radius="zero"}

:ori-textarea{label="sm" placeholder="Small" radius="sm"}

:ori-textarea{label="md" placeholder="Medium" radius="md"}

:ori-textarea{label="lg" placeholder="Large" radius="lg"}

:ori-textarea{label="rounded" placeholder="Rounded" radius="rounded"}

#vue
```vue
<OriTextarea v-model="value" label="zero" radius="zero" />
<OriTextarea v-model="value" label="rounded" radius="rounded" />
```

#html
```html
<textarea class="ori-textarea__field ori-size-radius_zero"></textarea>
```
::

## Rows

`rows` controls the initial visible height (and acts as the min-height). The field still grows as
the user types and remains manually resizable.

::example
  :::ori-textarea{:rows='2' label="2 rows" placeholder="Two rows of visible text"}
  :::

  :::ori-textarea
  ---
  rows: 5
  label: 5 rows
  placeholder: Five rows of visible text
  ---
  :::

#vue
```vue
<OriTextarea v-model="value" label="2 rows" :rows="2" />
<OriTextarea v-model="value" label="5 rows" :rows="5" />
```

#html
```html
<textarea rows="2" class="ori-textarea__field …"></textarea>
<textarea rows="5" class="ori-textarea__field …"></textarea>
```
::

## Label, hint & required

`label` renders a `<label>` linked to the field. `hint` renders a helper line below. `required`
adds the real HTML attribute and a visual asterisk (hidden from assistive tech).

::example
  :::ori-textarea
  ---
  required: true
  hint: Markdown is supported.
  label: Bio
  placeholder: Tell us about yourself...
  ---
  :::

#vue
```vue
<OriTextarea v-model="bio" label="Bio" placeholder="Tell us about yourself..." hint="Markdown is supported." required />
```

#html
```html
<div class="ori-textarea">
    <label class="ori-textarea__label" for="bio">
        Bio<span class="ori-textarea__required" aria-hidden="true">*</span>
    </label>
    <textarea
        id="bio"
        rows="3"
        required
        placeholder="Tell us about yourself..."
        aria-describedby="bio-hint"
        class="ori-textarea__field"
    ></textarea>
    <p id="bio-hint" class="ori-textarea__hint">Markdown is supported.</p>
</div>
```
::

## States

`disabled` uses the real attribute (also disables the resize handle). `error` renders a
`role="alert"` message and sets `aria-invalid`. `invalid` flips `aria-invalid` without a message
(for external validation).

::example
  :::ori-textarea{disabled label="Disabled" placeholder="Cannot edit"}
  :::

  :::ori-textarea
  ---
  invalid: true
  label: Invalid (no message)
  placeholder: Flagged externally
  ---
  :::

:ori-textarea{error="Message must be at least 20 characters." label="With error" placeholder="Your message"}

#vue
```vue
<OriTextarea v-model="value" label="Disabled" disabled />
<OriTextarea v-model="value" label="Invalid (no message)" invalid />
<OriTextarea v-model="value" label="With error" error="Message must be at least 20 characters." />
```

#html
```html
<!-- disabled -->
<textarea class="ori-textarea__field …" disabled></textarea>

<!-- invalid without message -->
<textarea class="ori-textarea__field …" aria-invalid="true"></textarea>

<!-- error: message gets role=alert and is referenced by aria-describedby -->
<textarea class="ori-textarea__field …" aria-invalid="true" aria-describedby="msg-error"></textarea>
<p id="msg-error" class="ori-textarea__error" role="alert">Message must be at least 20 characters.</p>
```
::

## Fluid

`fluid` stretches the wrapper to the full width of its container.

::example
  :::ori-textarea{fluid label="Full width" placeholder="Stretches to container"}
  :::

#vue
```vue
<OriTextarea v-model="value" label="Full width" fluid />
```

#html
```html
<div class="ori-textarea ori-textarea_fluid …">…</div>
```
::

## Common patterns

A real-world support form — label, required, hint, error, and fluid compose freely.

::example
  :::ori-textarea
  ---
  fluid: true
  required: true
  label: Subject
  placeholder: Briefly describe the issue
  ---
  :::

  :::ori-textarea
  ---
  fluid: true
  required: true
  rows: 6
  hint: Attachments can be added on the next step.
  label: Message
  placeholder: Provide as much detail as you can...
  ---
  :::

#vue
```vue
<form style="display: flex; flex-direction: column; gap: 1rem; max-width: 32rem">
    <OriTextarea v-model="subject" label="Subject" placeholder="Briefly describe the issue" required fluid />
    <OriTextarea
        v-model="message"
        label="Message"
        placeholder="Provide as much detail as you can..."
        hint="Attachments can be added on the next step."
        :rows="6"
        required
        fluid
    />
</form>
```

#html
```html
<form style="display: flex; flex-direction: column; gap: 1rem; max-width: 32rem">
    <div class="ori-textarea ori-textarea_fluid">
        <label class="ori-textarea__label" for="sub">
            Subject<span class="ori-textarea__required" aria-hidden="true">*</span>
        </label>
        <textarea
            id="sub"
            rows="3"
            required
            placeholder="Briefly describe the issue"
            class="ori-textarea__field"
        ></textarea>
    </div>
    <div class="ori-textarea ori-textarea_fluid">
        <label class="ori-textarea__label" for="msg">
            Message<span class="ori-textarea__required" aria-hidden="true">*</span>
        </label>
        <textarea
            id="msg"
            rows="6"
            required
            placeholder="Provide as much detail as you can..."
            aria-describedby="msg-hint"
            class="ori-textarea__field"
        ></textarea>
        <p id="msg-hint" class="ori-textarea__hint">Attachments can be added on the next step.</p>
    </div>
</form>
```
::

## Accessibility

The accessibility contract holds across every layer — the standalone classes and the Vue component
render the same attributes and ARIA wiring.

- `label` is associated with the field via `for`/`id`; the id is auto-generated (`useId`) when you
  don't pass one, so the association holds even without an explicit `id` prop.
- `hint` and `error` are wired through `aria-describedby`, referencing only the element that is
  actually rendered (`error` supersedes `hint`). Pass extra ids with `describedby` to reference
  additional descriptions (e.g. a shared form note).
- `error` sets `aria-invalid="true"` and announces via `role="alert"`; `invalid` flips
  `aria-invalid` on its own for external validation flows.
- Uses the real `disabled` attribute and native `required`; the focus ring is always visible and
  switches to the `danger` color when invalid.
- All native attributes (`name`, `autocomplete`, `maxlength`, `wrap`, `spellcheck`, …) fall through
  to the underlying `<textarea>` — OriTextarea stays out of the way.

| Key   | Action                                |
| ----- | ------------------------------------- |
| `Tab` | Moves focus to / away from the field. |

## Framework API

The props, events, and slots of the **Vue** component. The standalone CSS layer has no component
API — its surface is the [classes](https://oriui.vercel.app/#classes) above. (Svelte bindings are planned.)

### Props

| Prop          | Type                 | Default     | Description                                                                                               |
| ------------- | -------------------- | ----------- | --------------------------------------------------------------------------------------------------------- |
| `color`       | `ThemeColor`         | `'primary'` | Accent color for focus ring: primary · secondary · success · warn · danger · info · surface · background. |
| `describedby` | `string`             | —           | Extra element id(s) appended to `aria-describedby` (e.g. a shared form note).                             |
| `disabled`    | `boolean`            | `false`     | Real `disabled` attribute; blocks interaction, dims the field, and disables the resize handle.            |
| `error`       | `string`             | —           | Error message rendered below the field (`role="alert"`); also sets `aria-invalid="true"`.                 |
| `fluid`       | `boolean`            | `false`     | Full-width — stretches wrapper to 100 % of its container.                                                 |
| `hint`        | `string`             | —           | Helper text below the field; hidden while `error` is shown.                                               |
| `id`          | `string`             | —           | Explicit id for the `<textarea>`; auto-generated via `useId` when omitted.                                |
| `invalid`     | `boolean`            | `false`     | Sets `aria-invalid="true"` without rendering an error message (for external validation).                  |
| `label`       | `string`             | —           | Visible `<label>` text, wired to the field via `for`/`id`.                                                |
| `placeholder` | `string`             | —           | Native placeholder text.                                                                                  |
| `radius`      | `RadiusSize`         | `'md'`      | Corner radius of the field (`zero` · xs · sm · md · lg · xl · rounded).                                   |
| `required`    | `boolean`            | `false`     | Native `required` attribute; also renders a visual asterisk (`aria-hidden`).                              |
| `rows`        | `number`             | `3`         | Visible rows of text — sets the field min-height; the field still grows and is resizable.                 |
| `size`        | `ActionSize`         | `'md'`      | Field min-height + text scale (`xs` · sm · md · lg · xl · `xxl`).                                         |
| `variant`     | `'fill' | 'outline'` | `'outline'` | Visual style: `outline` (border) or `fill` (tinted background).                                           |

### Events & attributes

`v-model` binds to a `string` via `defineModel<string>()` — it reads the `modelValue` prop and
emits `update:modelValue` on input, so you use it like any controlled field:

```vue
<OriTextarea v-model="myValue" label="Message" />
```

OriTextarea sets `inheritAttrs: false` and spreads `$attrs` onto the underlying `<textarea>`, so
native attributes and listeners pass through directly to the field element — not the wrapper `<div>`:

- Attributes: `name`, `autocomplete`, `maxlength`, `minlength`, `wrap`, `spellcheck`, `readonly`, …
- Listeners: `@input`, `@change`, `@focus`, `@blur`, `@keydown`, …

### Slots

OriTextarea exposes no named slots.

| Slot   | Description           |
| ------ | --------------------- |
| (none) | No slots are defined. |


# Toast

An imperative notification system. Push a toast from anywhere with `useToast()` and render
`<OriToaster />` once near the app root to display the queue. No event bus, no Vuex, no provide/inject —
just a module-level reactive queue that every call site shares.

The live demo below fires real toasts into the docs page (an `<OriToaster />` is already mounted in
the docs layout). The appearance examples further down use the static `<OriToast>` component to
show the look without triggering a notification.

## Classes

::class-table
---
rows:
  - class: ori-toaster
    type: Block
    description: "Fixed portal container (pointer-events: none so it never blocks
      the page). Rendered by OriToaster via Teleport to body."
  - class: ori-toaster_top-right
    type: Position
    description: Anchors the stack to the top-right corner (default).
  - class: ori-toaster_top-left
    type: Position
    description: Anchors the stack to the top-left corner.
  - class: ori-toaster_top-center
    type: Position
    description: Anchors the stack to the top-center.
  - class: ori-toaster_bottom-right
    type: Position
    description: Anchors the stack to the bottom-right corner.
  - class: ori-toaster_bottom-left
    type: Position
    description: Anchors the stack to the bottom-left corner.
  - class: ori-toaster_bottom-center
    type: Position
    description: Anchors the stack to the bottom-center.
  - class: ori-toast
    type: Block
    description: "Single notification card: surface background, role-coloured
      left-border accent, elevation shadow."
  - class: ori-color_*
    type: Color
    description: Repoints --ori-color to drive the accent. Applied by useToast()
      severity shortcuts (success / danger / warn / info). Plain toast has no
      color class.
  - class: ori-toast__icon
    type: Part
    description: Leading icon element; coloured by --ori-color.
  - class: ori-toast__body
    type: Part
    description: Flex column holding the title and text.
  - class: ori-toast__title
    type: Part
    description: Bold heading above the body text.
  - class: ori-toast__text
    type: Part
    description: Body message; slightly muted opacity.
  - class: ori-toast__close
    type: Part
    description: Dismiss button (aria-label=Dismiss notification); shown when
      closable is true.
  - class: role=alert
    type: State
    description: Applied when color=danger (assertive live region). All other colors
      use role=status (polite).
---
::

## Live demo

Click a button to fire a real toast. The queue is shared: rapid-clicking stacks multiple
notifications; each auto-dismisses after 4 seconds unless sticky.

::example
:toast-demo

#vue
```vue
<script setup lang="ts">
import { useToast } from '@oriui/vue';

const { success, error, warn, info, toast } = useToast();

const checkIcon = 'M9 16.17 4.83 12l-1.42 1.41L9 19 21 7l-1.41-1.41z';
</script>

<template>
    <div style="display: flex; flex-wrap: wrap; gap: 0.5rem">
        <OriButton
            variant="outline"
            color="success"
            text="Success"
            @click="success({ title: 'Saved', text: 'Your changes were saved.', icon: checkIcon })"
        />
        <OriButton
            variant="outline"
            color="danger"
            text="Error"
            @click="error({ title: 'Upload failed', text: 'The file could not be uploaded.' })"
        />
        <OriButton variant="outline" color="warn" text="Warning" @click="warn('Your session expires in 5 minutes.')" />
        <OriButton variant="outline" color="info" text="Info" @click="info('A new version is available.')" />
        <OriButton variant="outline" text="Plain" @click="toast('Just a plain notification.')" />
        <OriButton
            variant="outline"
            text="Sticky"
            @click="toast({ text: 'I stay until you dismiss me.', duration: 0, closable: true })"
        />
    </div>
</template>
```
::

## Severity / colors

Four severity shortcuts preset a color; the plain `toast()` call has no color class (neutral surface accent).

::example
:ori-toast{color="success" text="Your changes have been saved."}

:ori-toast{color="danger" text="Upload failed. Please try again."}

:ori-toast{color="warn" text="Your session expires in 5 minutes."}

:ori-toast{color="info" text="A new version is available."}

:ori-toast{text="Just a plain notification."}

#vue
```vue
<script setup lang="ts">
import { useToast } from '@oriui/vue';

const { success, error, warn, info, toast } = useToast();
</script>

<template>
    <!-- each call returns the toast id -->
    <OriButton text="Success" @click="success('Your changes have been saved.')" />
    <OriButton text="Error" @click="error('Upload failed. Please try again.')" />
    <OriButton text="Warning" @click="warn('Your session expires in 5 minutes.')" />
    <OriButton text="Info" @click="info('A new version is available.')" />
    <OriButton text="Plain" @click="toast('Just a plain notification.')" />
</template>
```

#html
```html
<!-- Static appearance — no auto-dismiss or queue without JS. -->
<div class="ori-toast ori-color_success" role="status">
    <div class="ori-toast__body">
        <div class="ori-toast__text">Your changes have been saved.</div>
    </div>
</div>
<div class="ori-toast ori-color_danger" role="alert">
    <div class="ori-toast__body">
        <div class="ori-toast__text">Upload failed. Please try again.</div>
    </div>
</div>
<!-- plain: no ori-color_* class -->
<div class="ori-toast" role="status">
    <div class="ori-toast__body">
        <div class="ori-toast__text">Just a plain notification.</div>
    </div>
</div>
```
::

## Titles and icons

Pass `title` for a bold heading and `icon` (SVG path) for a coloured leading icon.

::example
  :::ori-toast
  ---
  color: success
  icon: M9 16.17 4.83 12l-1.42 1.41L9 19 21 7l-1.41-1.41z
  text: Your changes were saved successfully.
  title: Saved
  ---
  :::

:ori-toast{color="danger" text="The file could not be uploaded. Check your connection and try again." title="Upload failed"}

:ori-toast{color="info" text="A new version is available." title="Heads up"}

#vue
```vue
<script setup lang="ts">
import { useToast } from '@oriui/vue';

const { success, error, info } = useToast();

const checkIcon = 'M9 16.17 4.83 12l-1.42 1.41L9 19 21 7l-1.41-1.41z';
</script>

<template>
    <OriButton
        text="Fire"
        @click="success({ title: 'Saved', text: 'Your changes were saved successfully.', icon: checkIcon })"
    />
    <OriButton text="Error" @click="error({ title: 'Upload failed', text: 'The file could not be uploaded.' })" />
    <OriButton text="Info" @click="info({ title: 'Heads up', text: 'A new version is available.' })" />
</template>
```

#html
```html
<div class="ori-toast ori-color_success" role="status">
    <i class="ori-icon ori-toast__icon" aria-hidden="true">
        <svg viewBox="0 0 24 24"><path d="M9 16.17 4.83 12l-1.42 1.41L9 19 21 7l-1.41-1.41z" /></svg>
    </i>
    <div class="ori-toast__body">
        <div class="ori-toast__title">Saved</div>
        <div class="ori-toast__text">Your changes were saved successfully.</div>
    </div>
</div>
```
::

## Closable

`closable: true` (the default when called via `useToast()`) renders a dismiss button. Pass `closable: false`
to suppress it — useful for short-lived toasts that auto-dismiss quickly.

::example
  :::ori-toast{closable color="info" text="Dismiss me whenever you like."}
  :::

  :::ori-toast
  ---
  closable: false
  color: success
  text: I auto-dismiss — no button needed.
  ---
  :::

#vue
```vue
<script setup lang="ts">
import { useToast } from '@oriui/vue';

const { info } = useToast();
</script>

<template>
    <!-- closable: true is the default from useToast() -->
    <OriButton text="Closable" @click="info({ text: 'Dismiss me.', closable: true })" />
    <!-- suppress the button for quick notifications -->
    <OriButton text="No button" @click="info({ text: 'Gone in 4 s.', closable: false })" />
</template>
```

#html
```html
<!-- with dismiss button -->
<div class="ori-toast ori-color_info" role="status">
    <div class="ori-toast__body">
        <div class="ori-toast__text">Dismiss me whenever you like.</div>
    </div>
    <button type="button" class="ori-toast__close" aria-label="Dismiss notification">×</button>
</div>
```
::

## Duration and sticky

The default auto-dismiss delay is **4000 ms**. Pass `duration: 0` to make a toast sticky — it stays
until the user clicks the dismiss button or you call `dismiss(id)` / `clear()` manually.

::example
  :::ori-toast
  ---
  closable: true
  color: info
  text: I auto-dismiss after 4 s (default duration).
  ---
  :::

  :::ori-toast{closable color="warn" text="I stay until dismissed (duration: 0)."}
  :::

#vue
```vue
<script setup lang="ts">
import { useToast } from '@oriui/vue';

const { toast, warn } = useToast();
</script>

<template>
    <!-- default: auto-dismiss after 4000 ms -->
    <OriButton text="Default" @click="toast('Gone in 4 s.')" />

    <!-- custom duration -->
    <OriButton text="8 s" @click="toast({ text: 'Gone in 8 s.', duration: 8000 })" />

    <!-- sticky: pass duration: 0 -->
    <OriButton text="Sticky" @click="warn({ text: 'I stay until dismissed.', duration: 0, closable: true })" />
</template>
```
::

## Positions

Place `<OriToaster>` once (typically in the app root layout) and set its `position` prop. The
six positions are anchored with CSS — no re-ordering of the queue required. Bottom stacks grow
upward (`flex-direction: column-reverse`).

```vue
<!-- top-right is the default -->
<OriToaster position="top-right" />

<!-- other positions -->
<OriToaster position="top-left" />
<OriToaster position="top-center" />
<OriToaster position="bottom-left" />
<OriToaster position="bottom-right" />
<OriToaster position="bottom-center" />
```

## Programmatic dismiss

`toast()` and the severity shortcuts all return the toast id. Pass it to `dismiss(id)` to remove
a specific toast early, or call `clear()` to flush the entire queue.

```vue
<script setup lang="ts">
import { useToast } from '@oriui/vue';

const { toast, dismiss, clear } = useToast();

async function saveAndConfirm() {
    const id = toast({ text: 'Saving…', duration: 0 });
    await save();
    dismiss(id);
    toast({ text: 'Saved!', color: 'success' });
}
</script>
```

## Accessibility

Toast follows the ARIA live-region pattern — content is announced without moving keyboard focus.

- **`role="alert"` (assertive)** — used when `color="danger"`. The announcement interrupts the
  screen reader immediately. Reserve this for genuine errors.
- **`role="status"` (polite)** — used for every other color, including the plain/neutral toast.
  The announcement waits for the reader to finish its current utterance.
- The dismiss button carries `aria-label="Dismiss notification"` so its purpose is clear with no
  visible text.
- Toasts are **non-modal**: they never trap focus and do not require keyboard interaction to
  proceed. They appear and disappear without a focus change.
- Content must be present when the element is inserted — some screen readers announce only the
  content that is in the live region at the moment it is added to the DOM. `useToast()` pushes
  a fully-constructed item, so the rendered `<OriToast>` already contains its text on mount.
- Set `duration: 0` and `closable: true` for toasts that contain interactive content or links,
  so keyboard users can reach them before auto-dismiss removes the element.
- The `<OriToaster>` uses a `<TransitionGroup>` with `prefers-reduced-motion` support — the
  slide animation is disabled for users who opt out; only the fade remains.

| Key     | Action                                        |
| ------- | --------------------------------------------- |
| `Tab`   | Moves focus to the dismiss button (if shown). |
| `Enter` | Activates the focused dismiss button.         |
| `Space` | Activates the focused dismiss button.         |

## Framework API

### `useToast()`

The composable is a module-level singleton — every call returns the same reactive queue. Import
it anywhere; no Vue injection or plugin registration required. Its behaviour is the framework-agnostic
[`useToast`](https://oriui.vercel.app/headless/use-toast) — the same imperative API ships from `@oriui/headless/vue` and
`@oriui/headless/svelte`; this `@oriui/vue` re-export is unchanged.

```ts
import { useToast } from '@oriui/vue';

const { toasts, toast, success, error, warn, info, dismiss, clear } = useToast();
```

| Return value | Type / signature                             | Description                                                                    |
| ------------ | -------------------------------------------- | ------------------------------------------------------------------------------ |
| `toasts`     | `ToastItem[]` (reactive)                     | The live queue; rendered by `<OriToaster>`. Read-only — mutate via push/clear. |
| `toast`      | `(options: ToastOptions | string) => number` | Push a plain notification; returns the toast id.                               |
| `success`    | `(options: ToastOptions | string) => number` | Push with `color="success"` preset.                                            |
| `error`      | `(options: ToastOptions | string) => number` | Push with `color="danger"` preset.                                             |
| `warn`       | `(options: ToastOptions | string) => number` | Push with `color="warn"` preset.                                               |
| `info`       | `(options: ToastOptions | string) => number` | Push with `color="info"` preset.                                               |
| `dismiss`    | `(id: number) => void`                       | Remove a specific toast by its id and clear its timer.                         |
| `clear`      | `() => void`                                 | Remove all toasts and clear all pending timers.                                |

Passing a plain `string` is shorthand for `{ text: string }`.

### `ToastOptions`

| Option     | Type         | Default | Description                                                    |
| ---------- | ------------ | ------- | -------------------------------------------------------------- |
| `closable` | `boolean`    | `true`  | Renders a dismiss button on the toast.                         |
| `color`    | `ThemeColor` | —       | Semantic color role; preset by severity shortcuts.             |
| `duration` | `number`     | `4000`  | Auto-dismiss delay in ms. `0` keeps the toast until dismissed. |
| `icon`     | `string`     | —       | SVG path for a leading icon.                                   |
| `text`     | `string`     | —       | Body message.                                                  |
| `title`    | `string`     | —       | Bold heading above the body text.                              |

`ThemeColor`: `'primary' | 'secondary' | 'success' | 'warn' | 'danger' | 'info' | 'surface' | 'background'`

### `<OriToaster>` props

Place this component **once** near the app root (e.g. in the main layout). It Teleports to `<body>`
and is gated behind an `onMounted` check so SSR markup stays stable.

| Prop       | Type                                                                                         | Default       | Description                  |
| ---------- | -------------------------------------------------------------------------------------------- | ------------- | ---------------------------- |
| `position` | `'top-left' | 'top-right' | 'top-center' | 'bottom-left' | 'bottom-right' | 'bottom-center'` | `'top-right'` | Screen corner for the stack. |

`OriToaster` declares no custom events. It drives itself from the shared queue returned by
`useToast()` and calls `dismiss(id)` internally when a toast emits `close`.

### `<OriToast>` props

The single-toast card component. Used internally by `<OriToaster>` but also usable standalone
to display a static notification embedded in a page.

| Prop       | Type         | Default     | Description                                                      |
| ---------- | ------------ | ----------- | ---------------------------------------------------------------- |
| `closable` | `boolean`    | `false`     | Renders a dismiss button (`aria-label="Dismiss notification"`).  |
| `color`    | `ThemeColor` | `'surface'` | Semantic color role — drives the accent border and icon color.   |
| `icon`     | `string`     | —           | SVG path for a leading icon; rendered with `aria-hidden="true"`. |
| `text`     | `string`     | —           | Body message. Use the `default` slot for richer markup.          |
| `title`    | `string`     | —           | Bold heading above the body text.                                |

### Events

| Event   | Payload | Description                                                                                 |
| ------- | ------- | ------------------------------------------------------------------------------------------- |
| `close` | —       | Emitted when the dismiss button is clicked. Use it to call `dismiss(id)` or hide the toast. |

`OriToast` does not set `inheritAttrs: false`, so extra attributes (`class`, `style`, `data-*`)
fall through to the root `<div role="status/alert">`.

### Slots

| Slot      | Description                                                                        |
| --------- | ---------------------------------------------------------------------------------- |
| `default` | Body content. Replaces the `text` prop; renders inside `.ori-toast__text`.         |
| `icon`    | Leading icon. Replaces the `icon` prop render; falls back to it when not provided. |
| `title`   | Title content. Replaces the `title` prop; renders inside `.ori-toast__title`.      |


# Toolbar

A WAI-ARIA toolbar: a set of related controls that share a **single Tab stop**, navigated internally
with the arrow keys via **roving tabindex** (real DOM focus, not `aria-activedescendant`). Five
components make it up — `OriToolbar` (the root, `role="toolbar"`), `OriToolbarButton` (an item —
composes `OriButton`), `OriToolbarSeparator` (a perpendicular divider), and a paired
`OriToolbarToggleGroup` / `OriToolbarToggleItem` for a segmented single- or multi-select toggle.
Unlike the data-driven `OriMenu` (an `items` array plus a machine), a toolbar is **compositional** —
you assemble it from slotted components in whatever order and combination you need — so the behaviour
underneath, [`useToolbar`](https://oriui.vercel.app/#headless-usetoolbar) from `@oriui/headless`, is a provide/inject
roving-focus context rather than a state machine over an array.

The examples are organised by **layer**: the [class reference](https://oriui.vercel.app/#classes&#x29; is the standalone
&#x2A;*`@oriui/css`** layer, and the [Framework API](https://oriui.vercel.app/#framework-api&#x29; is the &#x2A;*`@oriui/vue`** component. Every
example is live — flip its code between **HTML** (the standalone classes, also your htmx / Astro / Svelte /
plain-HTML usage), **Vue**; HTML is the default. Because the roving-tabindex focus movement is real
JavaScript (there is no CSS-only affordance for it), the **HTML** tab in every example below is
**structure only** — a snapshot of the markup `OriToolbar` renders — while the **Vue** tab is the live,
fully interactive version.

## Classes

::class-table
---
rows:
  - class: ori-toolbar
    type: Block
    description: Required base class (OriToolbar). Unstyled flex grouping container
      - row layout, gap - with no variant or color axis of its own; all visual
      weight lives on the buttons inside it.
  - class: ori-toolbar_vertical
    type: Modifier
    description: Column layout instead of row; children stretch on the cross axis.
      Pair with the orientation prop (or aria-orientation=vertical by hand) for
      correct semantics.
  - class: ori-toolbar__group
    type: Part
    description: OriToolbarToggleGroup - a tighter cluster of related toggle
      buttons; same flex and gap as the bar, column instead of row when the
      toolbar is vertical.
  - class: ori-toolbar__separator
    type: Part
    description: "OriToolbarSeparator - a hairline rule, perpendicular to the bar: a
      vertical line inside a horizontal toolbar, a horizontal line inside a
      vertical one."
  - class: ori-button
    type: Part
    description: OriToolbarButton and OriToolbarToggleItem render the same
      ori-button classes documented on the Button page. Toolbar items default to
      ori-variant_text - a low-emphasis look - rather than the fill default
      OriButton itself uses standalone.
  - class: data-ori-toolbar-item
    type: State
    description: Internal marker attribute the roving-focus script uses to find
      items in DOM order. OriToolbarButton and OriToolbarToggleItem carry it
      automatically - not meant to be set or styled by hand.
  - class: role=toolbar / role=group / role=separator
    type: Semantics
    description: role=toolbar on the root, role=group on a toggle group,
      role=separator on the separator - always present, real attributes, not
      classes.
  - class: tabindex / aria-pressed / aria-disabled
    type: State
    description: Real attributes, not classes. Exactly one item is tabindex=0 at a
      time (roving); aria-pressed on a toggle item reflects the toggle group
      selection; aria-disabled keeps an item focusable while blocking
      activation.
---
::

## Anatomy

`OriToolbar` is a **compositional** container — there is no fixed per-instance template the way
`OriDialog` has one. The tree below shows a representative composition; assemble the five pieces in
whatever order and combination your toolbar needs.

```text
div.ori-toolbar                      [role=toolbar, aria-label|aria-labelledby, aria-orientation]   OriToolbar
  button.ori-button                  [data-ori-toolbar-item, tabindex]                              OriToolbarButton
  button.ori-button                  [data-ori-toolbar-item, tabindex, aria-pressed]                 OriToolbarButton (pressed)
  div.ori-toolbar__separator         [role=separator, aria-orientation]                              OriToolbarSeparator
  div.ori-toolbar__group             [role=group, aria-label]                                        OriToolbarToggleGroup
    button.ori-button                [data-ori-toolbar-item, tabindex, aria-pressed]  × N            OriToolbarToggleItem
```

Every item component requires an ancestor `OriToolbar` — used standalone, there is no roving context
to register with, so its `tabindex` stays `-1` forever (permanently unreachable by keyboard); the
orientation-only pieces (the separator, the toggle group) degrade gracefully to horizontal instead of
breaking. When `tooltip` is set, `OriToolbarButton` / `OriToolbarToggleItem` additionally wrap the
button in an `OriTooltip` (see the [Tooltip class reference](https://oriui.vercel.app/components/tooltip#classes)); if a `label`
also names the button, the tooltip is wired as its `aria-describedby` description (otherwise the tooltip
text is the accessible name — see [Accessibility](https://oriui.vercel.app/#accessibility)).

## Basic

A toolbar is one keyboard stop, however many controls it holds. Tab into it once — focus lands on the
first item — then use the arrow keys to move between New, Open, Save, and Delete without Tab ever
leaving the bar; Tab again moves past the whole thing.

::example
  :::ori-toolbar{label="File"}
  :ori-toolbar-button{text="New"}

  :ori-toolbar-button{text="Open"}

  :ori-toolbar-button{text="Save"}

  :ori-toolbar-separator

  :ori-toolbar-button{color="danger" text="Delete"}
  :::

#vue
```vue
<OriToolbar label="File">
    <OriToolbarButton text="New" />
    <OriToolbarButton text="Open" />
    <OriToolbarButton text="Save" />
    <OriToolbarSeparator />
    <OriToolbarButton text="Delete" color="danger" />
</OriToolbar>
```

#html
```html
<!-- Structure only — the roving-tabindex focus movement is JavaScript, not shown here. -->
<div class="ori-toolbar" role="toolbar" aria-label="File">
    <button class="ori-button ori-variant_text" data-ori-toolbar-item tabindex="0">New</button>
    <button class="ori-button ori-variant_text" data-ori-toolbar-item tabindex="-1">Open</button>
    <button class="ori-button ori-variant_text" data-ori-toolbar-item tabindex="-1">Save</button>
    <div class="ori-toolbar__separator" role="separator" aria-orientation="vertical"></div>
    <button class="ori-button ori-variant_text ori-color_danger" data-ori-toolbar-item tabindex="-1">Delete</button>
</div>
```
::

## Orientation, loop & direction

Three props reshape the roving keyboard model without touching a single item component.
`orientation` switches the arrow axis (and the flex direction) between horizontal (Left/Right) and
vertical (Up/Down); `loop` decides whether navigation wraps at the ends; `dir` swaps which physical
arrow key means "next" in a horizontal bar.

::example
  :::ori-toolbar{label="View" orientation="vertical"}
  :ori-toolbar-button{text="List"}

  :ori-toolbar-button{text="Grid"}

  :ori-toolbar-button{text="Table"}
  :::

#vue
```vue
<OriToolbar label="View" orientation="vertical">
    <OriToolbarButton text="List" />
    <OriToolbarButton text="Grid" />
    <OriToolbarButton text="Table" />
</OriToolbar>
```

#html
```html
<!-- Structure only. -->
<div class="ori-toolbar ori-toolbar_vertical" role="toolbar" aria-label="View" aria-orientation="vertical">
    <button class="ori-button ori-variant_text" data-ori-toolbar-item tabindex="0">List</button>
    <button class="ori-button ori-variant_text" data-ori-toolbar-item tabindex="-1">Grid</button>
    <button class="ori-button ori-variant_text" data-ori-toolbar-item tabindex="-1">Table</button>
</div>
```
::

`loop` (default `true`) wraps arrow navigation from the last item back to the first, and vice versa —
matching the WAI-ARIA APG reference toolbar. Set it to `false` to stop at the ends instead.

::example
  :::ori-toolbar{label="Wraps by default"}
  :ori-toolbar-button{text="1"}

  :ori-toolbar-button{text="2"}

  :ori-toolbar-button{text="3"}
  :::

  :::ori-toolbar{:loop='false' label="Stops at the ends"}
  :ori-toolbar-button{text="1"}

  :ori-toolbar-button{text="2"}

  :ori-toolbar-button{text="3"}
  :::

#vue
```vue
<!-- default: loop is true — End then ArrowRight wraps back to item 1 -->
<OriToolbar label="Wraps by default">
    <OriToolbarButton text="1" />
    <OriToolbarButton text="2" />
    <OriToolbarButton text="3" />
</OriToolbar>

<!-- loop is false — ArrowRight stops at item 3 instead of wrapping -->
<OriToolbar label="Stops at the ends" :loop="false">
    <OriToolbarButton text="1" />
    <OriToolbarButton text="2" />
    <OriToolbarButton text="3" />
</OriToolbar>
```

#html
```html
<!-- Structure only — loop is a JavaScript-only behaviour flag; no class or attribute marks it. -->
<div class="ori-toolbar" role="toolbar" aria-label="Stops at the ends">…</div>
```
::

`dir="rtl"` swaps which physical arrow key means "next" in a horizontal bar (`ArrowLeft` becomes
next, `ArrowRight` becomes previous) — it is a purely JavaScript signal. Vue excludes a declared prop
from attrs fallthrough, so `dir` never becomes a native `dir` HTML attribute on the rendered element;
pair it with your own RTL layout (an ancestor `dir="rtl"`, or `direction: rtl` in your CSS) so the
keyboard direction matches what is visually left and right.

```vue
<!-- Visual mirroring is your own HTML/CSS dir — the component prop only swaps the JS key mapping. -->
<div dir="rtl">
    <OriToolbar label="RTL toolbar" dir="rtl">
        <OriToolbarButton text="One" />
        <OriToolbarButton text="Two" />
        <OriToolbarButton text="Three" />
    </OriToolbar>
</div>
```

## Separator

`OriToolbarSeparator` is `role="separator"`, non-focusable, and always perpendicular to the bar it
sits in — a vertical rule inside a horizontal toolbar, a horizontal rule inside a vertical one. It
never claims a roving stop (no `data-ori-toolbar-item`), so arrow navigation skips straight over it.

::example
  :::ori-toolbar{label="Horizontal, with a separator"}
  :ori-toolbar-button{text="A"}

  :ori-toolbar-button{text="B"}

  :ori-toolbar-separator

  :ori-toolbar-button{text="C"}

  :ori-toolbar-button{text="D"}
  :::

  :::ori-toolbar{label="Vertical, with a separator" orientation="vertical"}
  :ori-toolbar-button{text="A"}

  :ori-toolbar-button{text="B"}

  :ori-toolbar-separator

  :ori-toolbar-button{text="C"}

  :ori-toolbar-button{text="D"}
  :::

#vue
```vue
<OriToolbar label="Horizontal, with a separator">
    <OriToolbarButton text="A" />
    <OriToolbarButton text="B" />
    <OriToolbarSeparator />
    <OriToolbarButton text="C" />
    <OriToolbarButton text="D" />
</OriToolbar>

<OriToolbar label="Vertical, with a separator" orientation="vertical">
    <OriToolbarButton text="A" />
    <OriToolbarButton text="B" />
    <OriToolbarSeparator />
    <OriToolbarButton text="C" />
    <OriToolbarButton text="D" />
</OriToolbar>
```

#html
```html
<!-- Structure only. The separator orientation is always the opposite of the toolbar orientation. -->
<div class="ori-toolbar" role="toolbar" aria-label="Horizontal, with a separator">
    <button class="ori-button ori-variant_text" data-ori-toolbar-item tabindex="0">A</button>
    <button class="ori-button ori-variant_text" data-ori-toolbar-item tabindex="-1">B</button>
    <div class="ori-toolbar__separator" role="separator" aria-orientation="vertical"></div>
    <button class="ori-button ori-variant_text" data-ori-toolbar-item tabindex="-1">C</button>
    <button class="ori-button ori-variant_text" data-ori-toolbar-item tabindex="-1">D</button>
</div>
```
::

## Toggle buttons (pressed)

`OriToolbarButton` takes a plain `pressed` boolean for a standalone toggle — for controls like Bold
and Italic that are not mutually exclusive, and so do not belong in a group. `aria-pressed` is
omitted entirely when `pressed` is not passed at all, so a genuinely plain action button never gets
it; pass `true` or `false` explicitly to make an item a toggle.

::example
  :::ori-toolbar{label="Text style"}
    ::::ori-toolbar-button
    ---
    pressed: true
    icon: M15.6 10.79c.97-.67 1.65-1.77 1.65-2.79 0-2.26-1.75-4-4-4H7v14h7.04c2.09 0
      3.71-1.7 3.71-3.79 0-1.52-.86-2.82-2.15-3.42zM10 6.5h3c.83 0 1.5.67 1.5
      1.5s-.67 1.5-1.5 1.5h-3v-3zm3.5 9H10v-3h3.5c.83 0 1.5.67 1.5 1.5s-.67 1.5-1.5
      1.5z
    label: Bold
    ---
    ::::

    ::::ori-toolbar-button
    ---
    pressed: false
    icon: M10 4v3h2.21l-3.42 8H6v3h8v-3h-2.21l3.42-8H18V4h-8z
    label: Italic
    ---
    ::::

  :ori-toolbar-separator

  :ori-toolbar-button{text="Clear formatting"}
  :::

#vue
```vue
<script setup lang="ts">
import { ref } from 'vue';

const bold = ref(true);
const italic = ref(false);
</script>

<template>
    <OriToolbar label="Text style">
        <!-- `pressed` is a plain prop — wire your own ref + @click to make it interactive -->
        <OriToolbarButton :icon="boldIcon" label="Bold" :pressed="bold" @click="bold = !bold" />
        <OriToolbarButton :icon="italicIcon" label="Italic" :pressed="italic" @click="italic = !italic" />
        <OriToolbarSeparator />
        <!-- no `pressed` prop at all — a plain action button, aria-pressed is never rendered -->
        <OriToolbarButton text="Clear formatting" @click="clearFormatting" />
    </OriToolbar>
</template>
```

#html
```html
<!-- Structure only. -->
<button
    class="ori-button ori-button_icon ori-variant_text"
    data-ori-toolbar-item
    tabindex="0"
    aria-pressed="true"
    aria-label="Bold"
>
    …
</button>
<button
    class="ori-button ori-button_icon ori-variant_text"
    data-ori-toolbar-item
    tabindex="-1"
    aria-pressed="false"
    aria-label="Italic"
>
    …
</button>
<div class="ori-toolbar__separator" role="separator" aria-orientation="vertical"></div>
<!-- a plain action button — no aria-pressed attribute at all -->
<button class="ori-button ori-variant_text" data-ori-toolbar-item tabindex="-1">Clear formatting</button>
```
::

## Disabled item

A disabled button or toggle item is `aria-disabled`, not the native `disabled` attribute — the
WAI-ARIA toolbar pattern keeps disabled controls focusable and reachable by roving navigation, and
only blocks activation. Tab to it, or arrow onto it, and it is still the roving stop; clicking it, or
pressing `Enter` / `Space` on it, does nothing.

::example
  :::ori-toolbar{label="Edit"}
  :ori-toolbar-button{text="Cut"}

  :ori-toolbar-button{text="Copy"}

    ::::ori-toolbar-button{disabled text="Paste"}
    ::::
  :::

#vue
```vue
<OriToolbar label="Edit">
    <OriToolbarButton text="Cut" />
    <OriToolbarButton text="Copy" />
    <OriToolbarButton text="Paste" :disabled="true" />
</OriToolbar>
```

#html
```html
<!-- Structure only — the click/Enter/Space block is JavaScript; CSS pointer-events alone only stops the mouse. -->
<button class="ori-button ori-variant_text" data-ori-toolbar-item tabindex="-1" aria-disabled="true">Paste</button>
```
::

## Tooltip-wired buttons

Pass `tooltip` and `OriToolbarButton` (or `OriToolbarToggleItem`) wraps itself in an `OriTooltip`. When
the button also carries a `label`, the tooltip is wired as its **description** (`aria-describedby` on the
real button) — the manual step the standalone [Tooltip](https://oriui.vercel.app/components/tooltip#accessibility) component
normally asks of a consumer, done for you. When there is **no** `label`, the tooltip text becomes the
button's accessible **name** instead, and `aria-describedby` is omitted so a screen reader doesn't
announce the same text twice.

::example
  :::ori-toolbar{label="Actions"}
  :ori-toolbar-button{icon="M11 13H5v-2h6V5h2v6h6v2h-6v6h-2z" tooltip="Add item"}

  :ori-toolbar-button{icon="M12 8a2 2 0 100-4 2 2 0 000 4zm0 6a2 2 0 100-4 2 2 0 000 4zm0 6a2 2 0 100-4 2 2 0 000 4z" tooltip="More options"}
  :::

#vue
```vue
<OriToolbar label="Actions">
    <!-- no `label` — the accessible name falls back to the tooltip text -->
    <OriToolbarButton icon="M11 13H5v-2h6V5h2v6h6v2h-6v6h-2z" tooltip="Add item" />
    <OriToolbarButton
        icon="M12 8a2 2 0 100-4 2 2 0 000 4zm0 6a2 2 0 100-4 2 2 0 000 4zm0 6a2 2 0 100-4 2 2 0 000 4z"
        tooltip="More options"
    />
</OriToolbar>
```

#html
```html
<!-- Structure only. -->
<span class="ori-tooltip">
    <!-- OriTooltip's own wrapper always carries aria-describedby, but it is not focusable — inert alone -->
    <span class="ori-tooltip__trigger" aria-describedby="tip-1">
        <!-- OriToolbarButton additionally wires the SAME id onto the real, focusable button — this is what announces -->
        <button
            class="ori-button ori-button_icon ori-variant_text"
            data-ori-toolbar-item
            tabindex="0"
            aria-label="Add item"
            aria-describedby="tip-1"
        >
            …
        </button>
    </span>
    <span id="tip-1" class="ori-tooltip__bubble ori-anchored ori-anchored_top" role="tooltip">Add item</span>
</span>
```
::

## Single-select toggle group

`type="single"` keeps at most one value selected, and is deselectable — clicking the pressed item
again clears it, like a Radix-style single toggle group. A natural fit for paragraph alignment, where
"none" can also be a valid state — try it below: click Align left again and every item reports
`aria-pressed="false"`. Items stay part of the same flat roving order as everything else in the bar —
the group itself does not add a stop.

::example
  :::ori-toolbar{label="Paragraph"}
    ::::ori-toolbar-toggle-group{label="Text alignment" type="single"}
    :ori-toolbar-toggle-item{icon="M4 6h16v2H4z M4 11h10v2H4z M4 16h13v2H4z" tooltip="Align left" value="left"}

    :ori-toolbar-toggle-item{icon="M4 6h16v2H4z M7 11h10v2H7z M5.5 16h13v2H5.5z" tooltip="Align center" value="center"}

    :ori-toolbar-toggle-item{icon="M4 6h16v2H4z M10 11h10v2H10z M7 16h13v2H7z" tooltip="Align right" value="right"}
    ::::
  :::
::

\::

\#vue

```vue
<script setup lang="ts">
import { ref } from 'vue';

const align = ref('left');
</script>

<template>
    <OriToolbar label="Paragraph">
        <OriToolbarToggleGroup v-model="align" type="single" label="Text alignment">
            <OriToolbarToggleItem value="left" :icon="alignLeftIcon" tooltip="Align left" />
            <OriToolbarToggleItem value="center" :icon="alignCenterIcon" tooltip="Align center" />
            <OriToolbarToggleItem value="right" :icon="alignRightIcon" tooltip="Align right" />
        </OriToolbarToggleGroup>
    </OriToolbar>
</template>
```

\#html

```html
<!-- Structure only. -->
<div class="ori-toolbar" role="toolbar" aria-label="Paragraph">
    <div class="ori-toolbar__group" role="group" aria-label="Text alignment">
        <button
            class="ori-button ori-button_icon ori-variant_text"
            data-ori-toolbar-item
            tabindex="0"
            aria-pressed="true"
            aria-label="Align left"
        >
            …
        </button>
        <button
            class="ori-button ori-button_icon ori-variant_text"
            data-ori-toolbar-item
            tabindex="-1"
            aria-pressed="false"
            aria-label="Align center"
        >
            …
        </button>
        <button
            class="ori-button ori-button_icon ori-variant_text"
            data-ori-toolbar-item
            tabindex="-1"
            aria-pressed="false"
            aria-label="Align right"
        >
            …
        </button>
    </div>
</div>
```

\::

## Multi-select toggle group

`type="multiple"` keeps a set instead of a single value — any number of items can be pressed at
once. Bold, italic, and underline are the canonical case: independent, freely combinable styles.

::example
  :::ori-toolbar{label="Character"}
    ::::ori-toolbar-toggle-group{label="Text style" type="multiple"}
    :ori-toolbar-toggle-item{icon="M15.6 10.79c.97-.67 1.65-1.77 1.65-2.79 0-2.26-1.75-4-4-4H7v14h7.04c2.09 0 3.71-1.7 3.71-3.79 0-1.52-.86-2.82-2.15-3.42zM10 6.5h3c.83 0 1.5.67 1.5 1.5s-.67 1.5-1.5 1.5h-3v-3zm3.5 9H10v-3h3.5c.83 0 1.5.67 1.5 1.5s-.67 1.5-1.5 1.5z" tooltip="Bold" value="bold"}

    :ori-toolbar-toggle-item{icon="M10 4v3h2.21l-3.42 8H6v3h8v-3h-2.21l3.42-8H18V4h-8z" tooltip="Italic" value="italic"}

    :ori-toolbar-toggle-item{icon="M12 17c3.31 0 6-2.69 6-6V3h-2.5v8c0 1.93-1.57 3.5-3.5 3.5S8.5 12.93 8.5 11V3H6v8c0 3.31 2.69 6 6 6zm-7 2v2h14v-2H5z" tooltip="Underline" value="underline"}
    ::::
  :::
::

\::

\#vue

```vue
<script setup lang="ts">
import { ref } from 'vue';

const styles = ref<string[]>([]);
</script>

<template>
    <OriToolbar label="Character">
        <OriToolbarToggleGroup v-model="styles" type="multiple" label="Text style">
            <OriToolbarToggleItem value="bold" :icon="boldIcon" tooltip="Bold" />
            <OriToolbarToggleItem value="italic" :icon="italicIcon" tooltip="Italic" />
            <OriToolbarToggleItem value="underline" :icon="underlineIcon" tooltip="Underline" />
        </OriToolbarToggleGroup>
    </OriToolbar>
    <!-- styles is e.g. ['bold', 'underline'] -->
</template>
```

\#html

```html
<!-- Structure only. -->
<div class="ori-toolbar__group" role="group" aria-label="Text style">
    <button
        class="ori-button ori-button_icon ori-variant_text"
        data-ori-toolbar-item
        tabindex="0"
        aria-pressed="false"
        aria-label="Bold"
    >
        …
    </button>
    <!-- repeat for Italic, Underline -->
</div>
```

\::

## Color & size passthrough

`color`, `variant`, `size`, and `radius` are not toolbar concerns — `OriToolbarButton` and
`OriToolbarToggleItem` forward them straight to the underlying `OriButton` (see the
[Button](https://oriui.vercel.app/components/button) page for the full axis reference).

::example
  :::ori-toolbar{label="Quick actions"}
  :ori-toolbar-button{size="sm" text="Export" variant="outline"}

  :ori-toolbar-button{color="danger" text="Delete" variant="tonal"}
  :::

#vue
```vue
<OriToolbar label="Quick actions">
    <OriToolbarButton text="Export" variant="outline" size="sm" />
    <OriToolbarButton text="Delete" variant="tonal" color="danger" />
</OriToolbar>
```

#html
```html
<!-- Structure only. -->
<button class="ori-button ori-variant_outline ori-button_sm" data-ori-toolbar-item tabindex="0">Export</button>
<button class="ori-button ori-variant_tonal ori-color_danger" data-ori-toolbar-item tabindex="-1">Delete</button>
```
::

## Common patterns

A formatting toolbar: two independent `pressed` toggles for Bold and Italic (not mutually exclusive,
so a plain `OriToolbarButton` and your own ref is the right tool, not a group), a separator, and a
single-select `OriToolbarToggleGroup` for paragraph alignment — every piece on this page composed
into one bar with a single Tab stop.

::example
:toolbar-demo

#vue
```vue
<script setup lang="ts">
import { ref } from 'vue';

const bold = ref(false);
const italic = ref(false);
const align = ref('left');
</script>

<template>
    <OriToolbar label="Formatting">
        <OriToolbarButton
            :pressed="bold"
            tooltip="Bold"
            icon="M15.6 10.79c.97-.67 1.65-1.77 1.65-2.79 0-2.26-1.75-4-4-4H7v14h7.04c2.09 0 3.71-1.7 3.71-3.79 0-1.52-.86-2.82-2.15-3.42zM10 6.5h3c.83 0 1.5.67 1.5 1.5s-.67 1.5-1.5 1.5h-3v-3zm3.5 9H10v-3h3.5c.83 0 1.5.67 1.5 1.5s-.67 1.5-1.5 1.5z"
            @click="bold = !bold"
        />
        <OriToolbarButton
            :pressed="italic"
            tooltip="Italic"
            icon="M10 4v3h2.21l-3.42 8H6v3h8v-3h-2.21l3.42-8H18V4h-8z"
            @click="italic = !italic"
        />

        <OriToolbarSeparator />

        <OriToolbarToggleGroup v-model="align" type="single" label="Text alignment">
            <OriToolbarToggleItem value="left" tooltip="Align left" icon="M4 6h16v2H4z M4 11h10v2H4z M4 16h13v2H4z" />
            <OriToolbarToggleItem
                value="center"
                tooltip="Align center"
                icon="M4 6h16v2H4z M7 11h10v2H7z M5.5 16h13v2H5.5z"
            />
            <OriToolbarToggleItem
                value="right"
                tooltip="Align right"
                icon="M4 6h16v2H4z M10 11h10v2H10z M7 16h13v2H7z"
            />
        </OriToolbarToggleGroup>
    </OriToolbar>
</template>
```

#html
```html
<!-- Structure only — the interactive Bold/Italic state and the alignment selection are JavaScript. -->
<div class="ori-toolbar" role="toolbar" aria-label="Formatting">
    <button class="ori-button ori-button_icon ori-variant_text" aria-pressed="false" aria-label="Bold">…</button>
    <button class="ori-button ori-button_icon ori-variant_text" aria-pressed="false" aria-label="Italic">…</button>
    <div class="ori-toolbar__separator" role="separator" aria-orientation="vertical"></div>
    <div class="ori-toolbar__group" role="group" aria-label="Text alignment">
        <button class="ori-button ori-button_icon ori-variant_text" aria-pressed="true" aria-label="Align left">
            …
        </button>
        <button class="ori-button ori-button_icon ori-variant_text" aria-pressed="false" aria-label="Align center">
            …
        </button>
        <button class="ori-button ori-button_icon ori-variant_text" aria-pressed="false" aria-label="Align right">
            …
        </button>
    </div>
</div>
```
::

## Accessibility

The accessibility contract holds across every layer — the standalone classes and the Vue components
render the same attributes and keyboard behaviour, though the roving-tabindex focus movement itself
is JavaScript (there is no CSS-only affordance for it).

- `role="toolbar"` needs a **required** accessible name — `label` (→ `aria-label`) or your own
  `aria-labelledby` attribute (falls through). A nameless toolbar fails axe / WCAG 4.1.2; in
  development, omitting both logs a console warning.
- `aria-orientation` reflects `orientation`, omitted for the implicit horizontal default and set
  only for `vertical` — the same convention as the separator below.
- Roving tabindex: exactly one item is `tabindex="0"` at a time (the last-focused one, defaulting to
  the first registered item); every other item is `tabindex="-1"`. Real DOM focus moves as you
  navigate — there is no `aria-activedescendant`. Navigation is resolved by DOM order
  (`querySelectorAll('[data-ori-toolbar-item]')`), so it stays correct even when items are
  conditionally rendered or reordered.
- Every item component (`OriToolbarButton` / `OriToolbarSeparator` / `OriToolbarToggleGroup` /
  `OriToolbarToggleItem`) requires an ancestor `OriToolbar` — used standalone, there is no roving
  context to register with, so the item's `tabindex` stays `-1` forever (unreachable by keyboard).
  The orientation-only pieces degrade gracefully to horizontal instead of breaking.
- `disabled` on a button or toggle item is `aria-disabled`, **not** the native `disabled` attribute —
  the WAI-ARIA toolbar pattern keeps disabled controls **focusable**, so they stay discoverable by
  roving navigation; only activation (click, `Enter`, `Space`) is blocked. This differs from
  `OriButton`'s own `disabled`, which removes a control from the tab order entirely.
- `pressed` → `aria-pressed` on `OriToolbarButton` is entirely omitted when the prop is not passed —
  a plain action button has no `aria-pressed` at all. `OriToolbarToggleItem`'s `aria-pressed` is
  always rendered (`true` / `false`), derived from the enclosing `OriToolbarToggleGroup`'s selection.
- `tooltip` on `OriToolbarButton` / `OriToolbarToggleItem` renders an `OriTooltip`. The accessible name
  is `label ?? tooltip` — a `label` wins when present, else the tooltip text names the button. When a
  `label` IS present, the tooltip is additionally wired as a supplementary **description**
  (`aria-describedby` on the real `<button>`, done for you — the manual step the standalone Tooltip asks
  of a consumer); when the tooltip is serving as the **name** (no label), `aria-describedby` is omitted so
  name and description aren't the same text (no double-announce). Either way an icon-only item ends up
  named — and in dev, a nameless one (icon, no `label` / `tooltip` / `text`) logs a console warning.
- `OriToolbarSeparator` is `role="separator"`, always perpendicular to the bar, non-focusable, and
  skipped by roving navigation (no `data-ori-toolbar-item` marker).
- `OriToolbarToggleGroup` is `role="group"` with its own `aria-label` — a second, independent
  accessible name from the toolbar's own. It adds no roving stop of its own; its
  `OriToolbarToggleItem` children are ordinary toolbar items, reached by the same flat arrow
  navigation as everything else in the bar.
- A composite child that owns its own arrow keys — a text field, a native range/spin control, or a
  `role=radiogroup` / `menu` / `listbox` / `combobox` / `textbox` widget placed inside the bar — is
  never hijacked; the toolbar's keydown handler yields to it entirely.

| Key                                        | Action                                                                                                                                                                                         |
| ------------------------------------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `Tab`                                      | Moves focus into the toolbar (landing on the roving-active item) or past it — the whole toolbar is a single stop.                                                                              |
| `Shift+Tab`                                | Moves focus out of the toolbar, backwards, as a single stop.                                                                                                                                   |
| `ArrowRight` / `ArrowLeft`                 | Horizontal toolbars: moves the roving stop to the next / previous item (wraps first⇄last when `loop`, the default). Swapped under `dir="rtl"`.                                                 |
| `ArrowDown` / `ArrowUp`                    | Vertical toolbars: moves the roving stop to the next / previous item (wraps when `loop`).                                                                                                      |
| `Home` / `End`                             | Moves the roving stop to the first / last item, in either orientation.                                                                                                                         |
| `Enter` / `Space`                          | Activates the focused button (native); toggles a toggle item's selection; no-ops on an `aria-disabled` item.                                                                                   |
| Arrow keys, focus inside a composite child | Not intercepted — an `input`, `textarea`, `select`, `[contenteditable]`, or an element with role slider/spinbutton/radiogroup/menu/listbox/combobox/textbox keeps its own arrow-key behaviour. |

## Framework API

The props, events, and slots of the **Vue** components — five of them, composed together. The
standalone CSS layer has no component API — its surface is the [classes](https://oriui.vercel.app/#classes) above, and the
roving-tabindex keyboard behaviour is JavaScript you would need to author yourself, or get from
[`useToolbar`](https://oriui.vercel.app/#headless-usetoolbar) in `@oriui/headless/vue`. (Svelte bindings are planned.)

### OriToolbar

**Props**

| Prop          | Type                        | Default        | Description                                                                                                                                                                                                               |
| ------------- | --------------------------- | -------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `dir`         | `'ltr' | 'rtl'`             | `'ltr'`        | Text direction for the horizontal arrow mapping — `rtl` swaps `ArrowLeft`/`ArrowRight`. A purely JavaScript signal; pair it with your own RTL layout (see [above](https://oriui.vercel.app/#orientation-loop-direction)). |
| `label`       | `string`                    | —              | Accessible name → `aria-label`. **Required**, unless you supply your own `aria-labelledby` attribute instead (it falls through onto the root element) — a nameless `role="toolbar"` fails axe.                            |
| `loop`        | `boolean`                   | `true`         | Whether arrow navigation wraps first⇄last at the ends.                                                                                                                                                                    |
| `orientation` | `'horizontal' | 'vertical'` | `'horizontal'` | Layout and arrow-key axis. `horizontal` = row, Left/Right; `vertical` = column, Up/Down.                                                                                                                                  |

**Events & attributes**

`OriToolbar` declares no custom emits. It does not set `inheritAttrs: false`, so extra attributes —
most notably `aria-labelledby`, but also `class`, `id`, `data-*` — fall through to the root
`div.ori-toolbar` alongside its own `role` / `aria-label` / `aria-orientation`. In development, a
toolbar with neither `label` nor an `aria-label` / `aria-labelledby` attribute logs a console
warning.

**Slots**

| Slot      | Scope | Description                                                                                              |
| --------- | ----- | -------------------------------------------------------------------------------------------------------- |
| `default` | —     | The toolbar's items — any mix of `OriToolbarButton`, `OriToolbarSeparator`, and `OriToolbarToggleGroup`. |

### OriToolbarButton

**Props**

| Prop       | Type         | Default  | Description                                                                                                                                                                                                            |
| ---------- | ------------ | -------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `color`    | `ThemeColor` | —        | Semantic color, forwarded to the underlying `OriButton`. Unset falls back to `OriButton`'s own default (`primary`).                                                                                                    |
| `disabled` | `boolean`    | `false`  | `aria-disabled`, **not** the native `disabled` attribute — the item stays focusable and reachable by roving navigation; only activation (click, `Enter`, `Space`) is blocked.                                          |
| `icon`     | `string`     | —        | SVG path, forwarded to `OriButton`. `icon` with no `text` renders an icon-only square.                                                                                                                                 |
| `label`    | `string`     | —        | Accessible name for an icon-only button (→ `aria-label`); falls back to `tooltip` when omitted.                                                                                                                        |
| `pressed`  | `boolean`    | —        | Toggle state → `aria-pressed`. Omit entirely for a plain action button (no `aria-pressed` rendered); pass `true` / `false` for a standalone toggle (e.g. Bold, Italic) that is not part of an `OriToolbarToggleGroup`. |
| `radius`   | `RadiusSize` | —        | Corner radius, forwarded. Unset falls back to `OriButton`'s own default (`rounded`).                                                                                                                                   |
| `size`     | `ActionSize` | —        | Height and text scale, forwarded. Unset falls back to `OriButton`'s own default (`md`).                                                                                                                                |
| `text`     | `string`     | —        | Visible label, forwarded to `OriButton`.                                                                                                                                                                               |
| `tooltip`  | `string`     | —        | Wraps the button in an `OriTooltip`; wires `aria-describedby` onto the real `<button>` when a `label` also names it, otherwise the tooltip text becomes the accessible name.                                           |
| `variant`  | `Variant`    | `'text'` | Visual style, forwarded. Toolbar items default to the low-emphasis `text` look rather than `OriButton`'s own `fill` default.                                                                                           |

**Events & attributes**

`OriToolbarButton` sets `inheritAttrs: false` and manually re-merges `$attrs` alongside its own
computed bindings onto the real `OriButton` (and, in turn, the `<button>`), so a native listener like
`@click` reaches the real element and fires normally. It declares no custom emits of its own.

**Slots**

| Slot      | Scope | Description                                                                                                                                                                                                           |
| --------- | ----- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `default` | —     | Custom button content, forwarded to the underlying `OriButton`. Falls back to the `icon` / `text` props when omitted — slot in a multi-path SVG or a custom icon component in place of the single-path `icon` string. |

### OriToolbarSeparator

**Props**

None. Orientation is not a prop — it is read from the enclosing `OriToolbar` via
`useToolbarOrientation()`, so the separator is automatically perpendicular to the bar with no wiring
required.

**Events & attributes**

No custom emits. Does not set `inheritAttrs: false`, so extra attributes fall through to the root
`div.ori-toolbar__separator`.

**Slots**

None.

### OriToolbarToggleGroup

**Props**

| Prop    | Type                    | Default    | Description                                                                                                                                                       |
| ------- | ----------------------- | ---------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `label` | `string`                | —          | Accessible name for the group (→ `aria-label`) — a `role="group"` needs one.                                                                                      |
| `type`  | `'single' | 'multiple'` | `'single'` | `single` keeps at most one value, and is deselectable (clicking the pressed item clears it). `multiple` keeps a set — any number of items can be pressed at once. |

**v-model**

`v-model` binds the selection via `defineModel<string \| string[]>()` — a `string` (or `undefined`)
for `type="single"`, a `string[]` for `type="multiple"`. Selecting an item emits
`update:modelValue`. Used standalone with no `v-model` bound at all, as in the bare examples on this
page, `defineModel` falls back to a local ref, so the group still manages its own selection.

**Events & attributes**

No manually-declared emits beyond the `v-model`-generated `update:modelValue`. Does not set
`inheritAttrs: false`, so extra attributes fall through to the root `div.ori-toolbar__group`
alongside its own `role` / `aria-label`. (`role="group"` takes no `aria-orientation` — it isn't in that
role's ARIA contract; the group is a named cluster over the toolbar's flat roving order.)

**Slots**

| Slot      | Scope | Description                                  |
| --------- | ----- | -------------------------------------------- |
| `default` | —     | The group's `OriToolbarToggleItem` children. |

### OriToolbarToggleItem

**Props**

| Prop       | Type         | Default      | Description                                                                      |
| ---------- | ------------ | ------------ | -------------------------------------------------------------------------------- |
| `color`    | `ThemeColor` | —            | Same forwarding as `OriToolbarButton`.                                           |
| `disabled` | `boolean`    | `false`      | Same `aria-disabled`, still-focusable semantics as `OriToolbarButton`.           |
| `icon`     | `string`     | —            | SVG path, forwarded to `OriButton`.                                              |
| `label`    | `string`     | —            | Accessible name for an icon-only item (→ `aria-label`); falls back to `tooltip`. |
| `radius`   | `RadiusSize` | —            | Forwarded; falls back to `OriButton`'s own default (`rounded`).                  |
| `size`     | `ActionSize` | —            | Forwarded; falls back to `OriButton`'s own default (`md`).                       |
| `text`     | `string`     | —            | Visible label, forwarded.                                                        |
| `tooltip`  | `string`     | —            | Same baked `aria-describedby` wiring as `OriToolbarButton`.                      |
| `value`    | `string`     | **required** | The value this item contributes to the enclosing group's `v-model`.              |
| `variant`  | `Variant`    | `'text'`     | Forwarded; same `text` default as `OriToolbarButton`.                            |

There is no `pressed` prop — unlike `OriToolbarButton`, press state is always derived from the
enclosing `OriToolbarToggleGroup`'s selection, so `aria-pressed` is always rendered (`true` / `false`),
never omitted.

**Events & attributes**

`OriToolbarToggleItem` sets `inheritAttrs: false`; its bindings are merged with your `$attrs` via Vue's
`mergeProps`.

> A caller's `@click` / `@focus` **compose** with the item's internal handlers — the toggle (which flips
> the value in the group) and the roving-active tracker — because they're combined with `mergeProps`, so
> both run. Prefer reacting to a selection change through the group's `v-model` / `update:modelValue`; an
> extra `@click` is additive, not a replacement, and `disabled` still blocks activation (a separate
> capture-phase guard).

**Slots**

| Slot      | Scope | Description                                                                                                                                                                                                            |
| --------- | ----- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `default` | —     | Custom item content, forwarded to the underlying `OriButton` — same as `OriToolbarButton`. Falls back to the `icon` / `text` props when omitted — slot in a multi-path SVG or a custom icon component if you need one. |

## Headless (`useToolbar`)

`OriToolbar` and its four companions are a thin styled shell around `useToolbar` (and
`useToolbarItem` / `useToolbarOrientation` / `useToolbarToggleGroup` / `useToolbarToggleItem`) from
`@oriui/headless/vue` — the same roving-tabindex engine, so you can build a fully custom-styled
toolbar UI on the same keyboard contract. Unlike `useDialog` / `useCombobox` / `useMenu`, `useToolbar`
does not go through the swappable `OriHeadless` adapter contract — a toolbar's behaviour is DOM order
plus Vue `provide` / `inject` composition, not a state machine, so there is nothing to swap.

```vue
<script setup lang="ts">
import { useToolbar, useToolbarItem } from '@oriui/headless/vue';

// The same engine OriToolbar / OriToolbarButton are built on — useToolbarItem() registers the
// calling component with the roving context and returns its tabindex plus the DOM marker the root's
// keydown handler navigates by.
const { toolbarRef, toolbarProps } = useToolbar({ label: () => 'Custom toolbar' });
</script>

<template>
    <div ref="toolbarRef" v-bind="toolbarProps">
        <MyToolbarButton text="Cut" />
        <MyToolbarButton text="Copy" />
        <MyToolbarButton text="Paste" />
    </div>
</template>
```

```vue
<!-- MyToolbarButton.vue -->
<script setup lang="ts">
import { useToolbarItem } from '@oriui/headless/vue';

defineProps<{ text: string }>();
const { itemProps } = useToolbarItem();
</script>

<template>
    <button v-bind="itemProps">{{ text }}</button>
</template>
```

`useToolbarItem` is inert outside a `useToolbar` root (see [Anatomy](https://oriui.vercel.app/#anatomy)) — `itemProps.tabindex`
stays `-1` forever with no context to register with. `useToolbarOrientation()` reads the enclosing
orientation for a custom separator or group (defaults to `horizontal` outside a toolbar).
`useToolbarToggleGroup` / `useToolbarToggleItem` layer selection state on top of the same roving
context — see the [OriToolbarToggleGroup](https://oriui.vercel.app/#oritoolbartogglegroup) /
[OriToolbarToggleItem](https://oriui.vercel.app/#oritoolbartoggleitem) sections above for the exact shape, or read the
component source directly (`packages/vue/src/components/toolbar/`).

The pure index/key math — `rovingIntent(key, orientation, dir)` and
`resolveRovingIndex(intent, from, count, loop)` — lives in the framework-agnostic core
(`@oriui/headless`, no framework import) and is reusable for any roving-tabindex widget; it is the
same helper a future Svelte adapter would share.


# Tooltip

A CSS-driven tooltip that shows additional context when a control is focused or hovered. The bubble
is always in the DOM (so the `aria-describedby` reference is never dangling) and shown/hidden
entirely in CSS — no JS state machine, no positioning engine. Show is pure `:focus-within` (keyboard)
and `:hover` wrapped in `@media (hover: hover)` (pointer, without sticking open on touch).

The examples are organised by **layer**: the [class reference](https://oriui.vercel.app/#classes&#x29; is the standalone
&#x2A;*`@oriui/css`** layer, and the [Framework API](https://oriui.vercel.app/#framework-api&#x29; is the &#x2A;*`@oriui/vue`** component. Every
example is live — flip its code between **HTML** (the standalone classes, also your htmx / Astro / Svelte /
plain-HTML usage), **Vue**; HTML is the default.

## Classes

A tooltip is a wrapper block plus a bubble element that composes the shared `.ori-anchored` placement
primitive — the same primitive documented on the [Popover page](https://oriui.vercel.app/components/popover#classes). There
are no variant or size utilities; the bubble adapts to its content.

::class-table
---
rows:
  - class: ori-tooltip
    type: Block
    description: "Wrapper: inline-flex. Sets --ori-anchor (a shared default
      anchor-name pairing the bubble with its own trigger, so no per-instance
      wiring is needed) plus local tokens (--ori-tooltip-bg,
      --ori-tooltip-color, --ori-tooltip-gap, --ori-tooltip-arrow). Carries
      ori-color_* on the wrapper only when the color prop is set."
  - class: ori-tooltip__trigger
    type: Part
    description: Inline-flex wrapper around the trigger slot; carries
      aria-describedby referencing the bubble id and the anchor-name that pairs
      it with the bubble.
  - class: ori-tooltip__bubble
    type: Part
    description: The tooltip surface, role=tooltip. Always in the DOM but
      visibility:hidden + opacity:0 + pointer-events:none until shown. Composed
      with .ori-anchored for placement. Background var(--ori-tooltip-bg), shadow
      var(--ori-shadow-md), radius var(--ori-tooltip-radius). Arrow via ::after,
      shown only where anchor positioning is supported.
  - class: ori-anchored / ori-anchored_*
    type: Placement base
    description: "Shared floating-panel placement primitive: position:fixed +
      position-anchor + collision-aware flip via position-try-fallbacks. See the
      Popover class reference for the full 12-value modifier list."
  - class: ori-color_*
    type: Color
    description: Applied on the wrapper when color is set; repoints --ori-color /
      --ori-color-on for the bubble fill + contrast text. Omit for the default
      neutral inverse chip (dark in light mode).
---
::

## Placements

Twelve placements are available via the shared `.ori-anchored` primitive — a bare side (`top` /
`bottom` / `left` / `right`) centers on the cross axis, `-start` / `-end` align to the trigger's start
/ end edge (logical, RTL-aware; see the [Popover class reference](https://oriui.vercel.app/components/popover#classes) for the
full list) — though a tooltip typically only needs the four centered sides shown below. `top` is the
default. The bubble is viewport-anchored (`position: fixed`) and collision-aware: `position-try-fallbacks`
flips it to the opposite side when the viewport would clip it. An engine without CSS Anchor
Positioning support lands the bubble at its fixed origin next to the trigger — unplaced, but still
readable.

::example
:ori-tooltip{content="Above the trigger" placement="top"}

:ori-tooltip{content="Below the trigger" placement="bottom"}

:ori-tooltip{content="Left of trigger" placement="left"}

:ori-tooltip{content="Right of trigger" placement="right"}

#vue
```vue
<OriTooltip content="Above the trigger" placement="top">
    <button>top</button>
</OriTooltip>
<OriTooltip content="Below the trigger" placement="bottom">
    <button>bottom</button>
</OriTooltip>
<OriTooltip content="Left of trigger" placement="left">
    <button>left</button>
</OriTooltip>
<OriTooltip content="Right of trigger" placement="right">
    <button>right</button>
</OriTooltip>
```

#html
```html
<!-- top (default) -->
<span class="ori-tooltip">
    <span class="ori-tooltip__trigger" aria-describedby="tip-1">
        <button>top</button>
    </span>
    <span id="tip-1" class="ori-tooltip__bubble ori-anchored ori-anchored_top" role="tooltip"> Above the trigger </span>
</span>

<!-- swap the modifier: ori-anchored_top → _bottom / _left / _right -->
```
::

## Colors

Omit `color` for the default neutral inverse chip (dark in light mode). Pass any semantic color to
tint the bubble with the matching role palette.

::example
:ori-tooltip{content="Default neutral" placement="bottom"}

:ori-tooltip{color="primary" content="Primary" placement="bottom"}

:ori-tooltip{color="danger" content="Danger" placement="bottom"}

:ori-tooltip{color="success" content="Success" placement="bottom"}

:ori-tooltip{color="info" content="Info" placement="bottom"}

:ori-tooltip{color="warn" content="Warn" placement="bottom"}

#vue
```vue
<!-- default (neutral inverse chip) -->
<OriTooltip content="Default neutral" placement="bottom">
    <button>default</button>
</OriTooltip>

<!-- semantic colors -->
<OriTooltip content="Primary" color="primary" placement="bottom">
    <button>primary</button>
</OriTooltip>
<OriTooltip content="Danger" color="danger" placement="bottom">
    <button>danger</button>
</OriTooltip>
```

#html
```html
<!-- default — no color class -->
<span class="ori-tooltip">
    <span class="ori-tooltip__trigger" aria-describedby="tip-2"><button>default</button></span>
    <span id="tip-2" class="ori-tooltip__bubble ori-anchored ori-anchored_bottom" role="tooltip">Default neutral</span>
</span>

<!-- colored — add ori-color_<role> on the wrapper -->
<span class="ori-tooltip ori-color_danger">
    <span class="ori-tooltip__trigger" aria-describedby="tip-3"><button>danger</button></span>
    <span id="tip-3" class="ori-tooltip__bubble ori-anchored ori-anchored_bottom" role="tooltip">Danger</span>
</span>
```
::

## Rich content

When plain text is not enough, use the `#content` slot instead of the `content` prop. Slot content
takes precedence over the prop.

::example
:ori-tooltip{placement="bottom"}

#vue
```vue
<OriTooltip placement="bottom">
    <button>hover me</button>
    <template #content>
        Keyboard shortcut: <kbd>Ctrl</kbd> + <kbd>S</kbd>
    </template>
</OriTooltip>
```

#html
```html
<span class="ori-tooltip">
    <span class="ori-tooltip__trigger" aria-describedby="tip-4">
        <button>hover me</button>
    </span>
    <span id="tip-4" class="ori-tooltip__bubble ori-anchored ori-anchored_bottom" role="tooltip">
        Keyboard shortcut: <kbd>Ctrl</kbd> + <kbd>S</kbd>
    </span>
</span>
```
::

## With icon-only button

A common pattern: supplement an icon-only button with a tooltip so the action is discoverable via
keyboard focus.

::example
:ori-tooltip{content="Add item" placement="right"}

#vue
```vue
<OriTooltip content="Add item" placement="right">
    <OriButton icon="M11 13H5v-2h6V5h2v6h6v2h-6v6h-2z" aria-label="Add item" variant="tonal" />
</OriTooltip>
```

#html
```html
<span class="ori-tooltip">
    <span class="ori-tooltip__trigger" aria-describedby="tip-5">
        <button class="ori-button ori-button_icon ori-variant_tonal ori-color_primary" aria-label="Add item">
            <i class="ori-icon" aria-hidden="true">
                <svg viewBox="0 0 24 24"><path d="M11 13H5v-2h6V5h2v6h6v2h-6v6h-2z" /></svg>
            </i>
        </button>
    </span>
    <span id="tip-5" class="ori-tooltip__bubble ori-anchored ori-anchored_right" role="tooltip"> Add item </span>
</span>
```
::

## Common patterns

Three icon buttons in a toolbar, each with a labeled tooltip — a typical editor or action-bar
pattern.

::example
:ori-tooltip{content="Bold (Ctrl+B)" placement="bottom"}

:ori-tooltip{content="Italic (Ctrl+I)" placement="bottom"}

:ori-tooltip{content="Underline (Ctrl+U)" placement="bottom"}

#vue
```vue
<div style="display: flex; gap: 0.25rem" role="toolbar" aria-label="Text formatting">
    <OriTooltip content="Bold (Ctrl+B)" placement="bottom">
        <OriButton icon="M15.6 10.79c.97-.67 1.65-1.77 1.65-2.79 0-2.26-1.75-4-4-4H7v14h7.04c2.09 0 3.71-1.7 3.71-3.79 0-1.52-.86-2.82-2.15-3.42zM10 6.5h3c.83 0 1.5.67 1.5 1.5s-.67 1.5-1.5 1.5h-3v-3zm3.5 9H10v-3h3.5c.83 0 1.5.67 1.5 1.5s-.67 1.5-1.5 1.5z" aria-label="Bold" variant="plain" />
    </OriTooltip>
    <OriTooltip content="Italic (Ctrl+I)" placement="bottom">
        <OriButton icon="M10 4v3h2.21l-3.42 8H6v3h8v-3h-2.21l3.42-8H18V4h-8z" aria-label="Italic" variant="plain" />
    </OriTooltip>
    <OriTooltip content="Underline (Ctrl+U)" placement="bottom">
        <OriButton icon="M12 17c3.31 0 6-2.69 6-6V3h-2.5v8c0 1.93-1.57 3.5-3.5 3.5S8.5 12.93 8.5 11V3H6v8c0 3.31 2.69 6 6 6zm-7 2v2h14v-2H5z" aria-label="Underline" variant="plain" />
    </OriTooltip>
</div>
```

#html
```html
<div style="display: flex; gap: 0.25rem" role="toolbar" aria-label="Text formatting">
    <span class="ori-tooltip">
        <span class="ori-tooltip__trigger" aria-describedby="tip-bold">
            <button class="ori-button ori-button_icon ori-variant_plain …" aria-label="Bold">
                <!-- bold icon -->
            </button>
        </span>
        <span id="tip-bold" class="ori-tooltip__bubble ori-anchored ori-anchored_bottom" role="tooltip">
            Bold (Ctrl+B)
        </span>
    </span>
    <!-- repeat for Italic, Underline -->
</div>
```
::

## Limitations

OriTooltip is a CSS-only implementation. The following features would require JavaScript and are
out of scope for this component:

- **Esc-to-dismiss** — the CSS model dismisses on blur / pointer-leave only.
- **The arrow does not track a collision flip** — the bubble itself repositions via
  `position-try-fallbacks`, but the decorative arrow is keyed to the requested `placement` class (a
  pure-CSS pseudo-element cannot observe which fallback fired), so it keeps pointing at the requested
  side — correct in the common, uncollided case.
- **Show/hide delay** — no hover-intent debounce; the bubble appears immediately on hover/focus.

## Accessibility

The accessibility contract holds across every layer — the standalone classes and the Vue component
render the same attributes.

- The bubble has `role="tooltip"` and a `useId()`-generated id, exposed on the **default slot scope**
  as `bubbleId`. The bubble stays in the DOM permanently (not `v-if`) so the reference is never
  dangling — a pointed-at id that does not exist is ignored by assistive technology.
- **To announce the tooltip to screen readers, put `aria-describedby="<bubbleId>"` on your own focusable
  control.** `aria-describedby` is announced when the element *bearing* it is focused, and the
  `.ori-tooltip__trigger` wrapper is a non-focusable `<span>` — so the wrapper's own `aria-describedby`
  does not produce the announcement on its own (it only guarantees the id resolves). The component can't
  augment arbitrary slot content without JS, so this wiring is the consumer's to add (see the trade-off
  below). Icon-only controls should still carry their own `aria-label`.
- The trigger's native `:focus-visible` ring is not overridden — the real control inside keeps its
  own focus indicator.
- The decorative arrow is a `::after` pseudo-element — invisible to assistive technology, no
  `aria-hidden` needed.
- Color is applied only on the wrapper, not on the bubble directly, so the `ori-color_*` utility
  is never shadowed (a NOTES.md gotcha confirmed for OriProgress and OriTooltip alike).

> **Design / a11y trade-off:** a pure-CSS tooltip can't inject `aria-describedby` onto arbitrary slot
> content without JS, so the component puts it on the `.ori-tooltip__trigger` wrapper (which only
> guarantees the bubble id resolves) and exposes `bubbleId` on the slot scope. For the description to
> actually be **announced**, the consumer binds `:aria-describedby="bubbleId"` on their own focusable
> control — `aria-describedby` announces on focus of the element bearing it, and the wrapper isn't
> focusable. `:focus-within` governs the bubble's CSS visibility, not the ARIA announcement; the two are
> independent.

| Key         | Action                                                        |
| ----------- | ------------------------------------------------------------- |
| `Tab`       | Focuses the trigger control; shows the tooltip.               |
| `Shift+Tab` | Blurs the trigger control; hides the tooltip.                 |
| `Escape`    | Not supported (CSS-only model — blur the trigger to hide it). |

## Framework API

The props, events, slots, and polymorphism of the **Vue** component. The standalone CSS layer has no
component API — its surface is the [classes](https://oriui.vercel.app/#classes) above. (Svelte bindings are planned.)

### Props

| Prop        | Type                | Default | Description                                                                                                                                                                                                                           |
| ----------- | ------------------- | ------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `color`     | `ThemeColor`        | —       | Bubble fill color. Adds `ori-color_<color>` on the wrapper, repointing `--ori-color` / `--ori-color-on`. Omit for the default neutral inverse chip (dark in light mode).                                                              |
| `content`   | `string`            | —       | Tooltip text. For rich content use the `#content` slot instead — it takes precedence over this prop.                                                                                                                                  |
| `placement` | `AnchoredPlacement` | `'top'` | Placement relative to the trigger — `'top' | 'bottom' | 'left' | 'right'`, each also `-start` / `-end` (12 values total). Drives the `ori-anchored_<placement>` modifier on the bubble; collision-aware via `position-try-fallbacks`. |

### Events & attributes

OriTooltip declares **no custom emits**. It does not set `inheritAttrs: false`, so attributes placed
directly on `<OriTooltip>` fall through to the root `<span class="ori-tooltip">` wrapper.

### Slots

| Slot      | Scope | Description                                                                                                                                                                                                 |
| --------- | ----- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `default` | —     | The trigger. Rendered inside `.ori-tooltip__trigger`, which carries `aria-describedby`. Should contain a real focusable control (button or link) so keyboard focus reveals the tooltip via `:focus-within`. |
| `content` | —     | Rich tooltip content. Overrides the `content` prop when provided. Use for markup beyond plain text (e.g. `<kbd>`).                                                                                          |


# Using the CSS layer

oriUI is three independent layers woven around one set of design tokens. The &#x2A;*`@oriui/css`** layer is
just standalone `.ori-*` classes plus the token theming — **no Vue, no build step, no Tailwind**. You
ship the stylesheet and write classes. This is how oriUI works with **htmx, Astro, or plain HTML** —
the DaisyUI niche, minus Tailwind.

The live previews below are rendered from **raw HTML** (no Vue component) — flip to the **HTML** tab to
see the exact markup.

## Setup

From a bundler, import the stylesheet once:

```ts
import '@oriui/css';
```

Or drop it in with no build step at all:

```html
<link rel="stylesheet" href="https://unpkg.com/@oriui/css/dist/styles.css" />
```

## How the classes compose

Every component is a **block class** plus **single-class token utilities** — one class repoints one
token, no paired base class: `ori-<name>_<size>` (size sugar), `ori-size-radius_*` (corners),
`ori-font-size_*`, `ori-variant_*` (style), and `ori-color_*` (color). The block **bakes sensible
defaults**, so a bare block is already valid — you add a class only to override an axis:

```html
<!-- a bare block is a valid filled, primary, rounded, md button -->
<button class="ori-button">Button</button>

<!-- override only what differs -->
<button class="ori-button ori-button_lg ori-variant_tonal ori-color_danger">Button</button>
```

Swap `ori-variant_fill` → `_tonal`, or `ori-color_primary` → `ori-color_danger`, and nothing else
changes — each class repoints exactly one CSS variable the component reads. It is the **same markup**
whether rendered from Vue, Svelte, htmx, Astro, or hand-written HTML. Dynamic state is real
**attributes**, not classes (`disabled`, `aria-busy="true"`, `aria-pressed`), so it stays accessible
and identical across every layer.

> **Why single-class?** Every utility lives in the last cascade layer (`@layer ori.utilities`) and
> sets one token — e.g. `.ori-color_danger { --ori-color: … }` — so it wins over the block's baked
> default by layer order, not specificity. There is no "base + value" pair to remember (forgetting
> the base used to be a silent no-op). **Size** is the one axis with a component-scoped sugar
> (`ori-button_lg`, `ori-input_md`, `ori-avatar_xs`) because it is the most-swapped; under the hood it
> repoints the same `--ori-size-action` token, so `<input class="ori-input__field ori-size-action_lg">`
> works too.

> Per-component class tables and live examples (each with an **HTML** tab — the canonical,
> copy-pasteable markup) live on the component pages, e.g. [Button](https://oriui.vercel.app/components/button). This guide
> covers only the cross-cutting concerns below: setup, theming, and where each layer fits.

## Theming — zero runtime

Theme and skin are just attributes on `<html>`; flipping them reskins everything through CSS custom
properties, with **no JavaScript**:

```html
<html class="dark" data-ori-skin="cyber">
    ...
</html>
```

- `class="dark"` → dark mode (omit for light).
- `data-ori-skin="sumi | indigo | tech | health | luxury | neutral | cyber"` → a preset skin (omit for
  the default **Ori** skin).

A three-line inline script is enough to persist a user's choice, or the server can set the attributes
per request. With **htmx**, fragments you swap in are already themed — CSS transitions compose with
`hx-swap`, no hydration.

## Where each layer fits

The **CSS layer works everywhere** — that's the whole point. Vue and the headless layer need a JS
framework; the classes don't. Only complex behavior (focus traps, menus, comboboxes) needs the
headless layer, which is Vue today; a vanilla adapter (via Zag) is planned for the no-framework
targets. For the full cross-layer breakdown (Vue / Svelte / htmx / Astro / plain HTML / Capacitor),
see the [applicability matrix](https://oriui.vercel.app/overview/introduction#where-each-layer-fits) in the Introduction.

Per-component class references live on each component page — flip any example to the **HTML** tab;
that standalone markup is exactly what you'd use in htmx, Astro, or plain HTML.


# Customization

Make it yours — without authoring a whole skin. Most products need one thing: *their* brand color and
*their* corner radius on top of accessible, ready-made components. oriUI lets you do that by repointing
a handful of design tokens — a few CSS custom properties in your own stylesheet, no rewrite, no fork.
This is the **prototype fast, scale without rewriting** payoff: the same `<OriButton>` you shipped on
day one becomes *on-brand* by the time you ship to users, and nothing about the component changes.

For **color** there are exactly three levels, ordered from safest to most manual: the **props**
(semantic roles with a contrast guarantee — the recommended default), a **global brand override**
(repoint the token sources once, the whole app follows), and **per-instance variables** (the escape
hatch for a one-off). Around them this page covers **styling one instance**, **scoping an override to
a subtree**, a **5-minute brand walkthrough**, and how customized color reaches **icons** and
**JS-painted canvases**. Authoring a complete named skin and switching modes is
[Theming](https://oriui.vercel.app/guides/theming); the exhaustive token inventory is
[Design tokens](https://oriui.vercel.app/guides/design-tokens); the standalone-class story is [Using the CSS layer](https://oriui.vercel.app/guides/css).

## 1 · Start with the props — the semantic roles

Before overriding anything, say what you mean. The styled components take a `color` **role** —
`primary` · `secondary` · `surface` · `background` · `success` · `warn` · `danger` · `info` — and,
where a surface can be painted more than one way, a `variant` **mapping** that decides *how* the role
is painted: `fill` (role as background, its `on-` color as text), `tonal` / `outline` / `text` /
`plain` (role as tint / border / text). Color is the *role*, variant is the *mapping* — the
background-and-text pairing is never yours to hand-assemble.

::example
:ori-button{color="primary" text="Save" variant="fill"}

:ori-button{color="danger" text="Delete" variant="outline"}

:ori-button{color="success" text="Done" variant="tonal"}

#vue
```vue
<OriButton text="Save" color="primary" variant="fill" />
<OriButton text="Delete" color="danger" variant="outline" />
<OriButton text="Done" color="success" variant="tonal" />
```

#html
```html
<button class="ori-button ori-variant_fill ori-color_primary">Save</button>
<button class="ori-button ori-variant_outline ori-color_danger">Delete</button>
<button class="ori-button ori-variant_tonal ori-color_success">Done</button>
```
::

Why this is the recommended default: every role ships with a contrast-checked `on-` partner, and that
pairing is **asserted, not hoped for** — an automated guard (`tests/tokens.contrast.test.ts`) parses
the token CSS and fails the suite if any role / `on-role` pair drops below &#x2A;*WCAG AA (4.5:1)** for
body text, across light and dark and every preset skin. Stay on the props and accessible contrast is
a build-time guarantee, and your palette keeps following every skin and mode switch for free.

The honest trade-off: the props only speak **roles**. There is deliberately no `text-color` or
`bg-color` prop — when a component must be a color that isn't a role, that's the
[escape hatch](https://oriui.vercel.app/#_4-the-escape-hatch-per-instance-color-variables) below, and the *why* lives there too.

## Why an override just works — the `@layer` cascade

oriUI ships every token and utility inside `@layer`, in a fixed order — the canonical list lives on
[Design tokens](https://oriui.vercel.app/guides/design-tokens#the-cascade-layer-order). The rule that makes customization
painless: **unlayered styles always beat layered ones**, regardless of specificity. Your own
`:root { … }` — written in your app's stylesheet, outside any `@layer` — wins over oriUI's
`@layer ori.tokens` declaration of the same token. You never fight specificity, and you never reach for
`!important`.

```css
/* oriUI ships this (inside @layer ori.tokens) */
@layer ori.tokens {
    :root {
        --ori-color-primary-light: #0369a1; /* the default azure */
    }
}

/* You write this in your own stylesheet — UNLAYERED, so it wins */
:root {
    --ori-color-primary-light: #16a34a; /* your green */
}
```

Both are `:root` (specificity `0,1,0`) — a tie on specificity. The unlayered rule wins purely because it
sits outside the layers. Every button, switch, and focus ring that resolves `--ori-color-primary` now
reads your green. &#x2A;*That is the whole mechanism.** Override the source token, and the light/dark
machinery and the per-component aliases resolve on top of your value automatically.

> For a **global** brand color, override the `*-light` / `*-dark` **source** tokens (e.g.
> `--ori-color-primary-light`) in `:root` — not the resolved alias `--ori-color-primary`, which the mode
> selectors repoint per mode (overwrite it at `:root` and you flatten dark mode). For a **single element
> or a region**, it is the reverse — you target the resolved alias (sections 4 and 5).

## 2 · Rebrand globally — override the token sources

Drop a `:root` block anywhere in your app's CSS (after importing oriUI). A color role is two source
tokens per mode — the color and its contrast-checked `on-` text color. Set both light and dark so the
brand holds in either mode:

```css
:root {
    /* light mode */
    --ori-color-primary-light: #16a34a;
    --ori-color-on-primary-light: #ffffff;
    /* dark mode */
    --ori-color-primary-dark: #4ade80;
    --ori-color-on-primary-dark: #052e16;
}
```

The `on-` token is the label/icon color that sits *on* the filled color — keep the pair at WCAG AA
(≥ 4.5:1) yourself, the way the built-in skins do. The contrast test guards the palette the library
*ships*; your own sources are your responsibility, and both modes need their own check because dark
inverts the pairing.

This works because the active alias `--ori-color-primary` is declared &#x2A;*and resolved at `:root`** — it
reads `var(--ori-color-primary-light)` there (see
[`_themes-color-tokens.css`](https://oriui.vercel.app/guides/design-tokens#colour-three-tiers)). Override the source at `:root`
and the alias re-resolves, inheriting your value into every component. Overriding all four skinnable
roles (plus their `on-` pairs, per mode) is the same move at scale — at that point consider
[authoring a named skin](https://oriui.vercel.app/guides/theming#authoring-a-custom-skin) instead.

### Text tone — override only to fine-tune

A role's hue above is engineered as a **fill background** — a component paints it as text (the
non-fill button variants, the selected tab, alert, tag) through a separate, dedicated token,
`--ori-color-<role>-text`, so that a light or saturated role never has to double as body text. It
already derives an AA-safe tone automatically — a **relative color** that keeps the role's hue and
chroma and clamps only its lightness, so the text reads as the same colour as the fill, just darker
(light theme) or lighter (dark theme):

```css
/* :root — the light default */
--ori-color-primary-text: oklch(from var(--ori-color-primary) min(l, 0.42) c h);

/* .ori-theme_dark / :root.dark — re-declared with the opposite clamp */
--ori-color-primary-text: oklch(from var(--ori-color-primary) max(l, 0.86) c h);
```

Because each theme declares its own clamp — light caps lightness at 0.42, dark floors it at 0.86 —
the tone tracks the **active theme** automatically. And because both formulas read
`var(--ori-color-primary)`, the tone also tracks any **skin**'s role override, or your own — rebrand
`primary` above, or [author a whole custom skin](https://oriui.vercel.app/guides/theming#authoring-a-custom-skin), and its
non-fill text tone is AA-safe **for free**. Override the derived value only to fine-tune the exact
hue:

- **Global**, every mode and skin: `:root { --ori-color-warn-text: #b45309 }`. A flat override value
  is theme-agnostic — unlike oriUI's own formula above, it needs no light/dark split — so your
  unlayered `:root` rule beats both oriUI's light default and its dark re-declaration, and one
  declaration covers both modes. Nest it inside `.ori-theme_dark` / `:root.dark` too if you want a
  different dark-mode value.
- **Per skin**: `[data-ori-skin='brand'] { --ori-color-primary-text: … }` — the same selector shape as
  [authoring a skin](https://oriui.vercel.app/guides/theming#authoring-a-custom-skin).
- **Per instance or subtree**: repoint the resolved alias, `--ori-color-text`, on a wrapper — the same
  escape hatch as `--ori-color` / `--ori-color-on` (section 4 below).

This replaces the old workaround of targeting a component's fill token directly (e.g.
`.ori-button { --ori-color: … }`) to patch up text contrast — that also repaints the `fill` variant's
background, since `--ori-color` feeds both. `--ori-color-text` is the sanctioned point: it only ever
feeds the non-fill / selected-text axis — and now the `outline&#x60; variant's border too, so the ring and
the label match. &#x2A;(Full per-role token reference:
[Design tokens](https://oriui.vercel.app/guides/design-tokens#text-the-on-surface-foreground).)*

### Radius and font-size — the same pattern

The size scales live at `:root` too (`--ori-size-radius_*`, `--ori-font-size_*`), so the same
unlayered block rebrands them. `--ori-size-radius_md` anchors the whole scale — `xs` / `sm` / `lg` /
`xl` are `calc()`-derived from it, so one override moves every derived step proportionally (`zero`
and the `9999px` `rounded` pill stay fixed). The font ladder pivots on `--ori-font-size_md` the same
way, in fixed ±`0.125rem` (2px at the browser default) steps:

```css
:root {
    --ori-size-radius_md: 4px; /* sm/lg/xl re-derive — cards (lg) tighten along */
    --ori-font-size_md: 15px; /* the control ladder shifts around the new md */
}
```

> A repoint only moves components that resolve a **derived** step. Several controls pin a fixed step
> on purpose — buttons, badges, tags, and avatars default to `rounded` (the `9999px` pill) — so an
> `_md` repoint doesn't square a default button. Bring such a control onto your house radius per
> instance: the `radius="md"` prop / `ori-size-radius_md` class.

## 3 · Style one instance

When you want to change *one* component, not the whole library, reach for the utility classes (CSS) or
the matching props (Vue) — no token override needed. Every utility is **single-class**: one class
repoints one token, no paired base class.

| Axis    | Utility class                                 | Vue prop  |
| ------- | --------------------------------------------- | --------- |
| Color   | `ori-color_*`                                 | `color`   |
| Variant | `ori-variant_*`                               | `variant` |
| Size    | `ori-<name>_*` sugar (or `ori-size-action_*`) | `size`    |
| Radius  | `ori-size-radius_*`                           | `radius`  |

This table is a quick orientation map; the full per-component class reference lives on each component
page — see [Button](https://oriui.vercel.app/components/button) for the canonical list.

::example
:ori-button{color="primary" text="Brand" variant="fill"}

:ori-button{color="danger" text="Danger" variant="tonal"}

:ori-button{radius="sm" text="Squared" variant="outline"}

:ori-button{size="lg" text="Large" variant="fill"}

#vue
```vue
<OriButton text="Brand" color="primary" variant="fill" />
<OriButton text="Danger" color="danger" variant="tonal" />
<OriButton text="Squared" radius="sm" variant="outline" />
<OriButton text="Large" size="lg" variant="fill" />
```

#html
```html
<button class="ori-button ori-variant_fill ori-color_primary">Brand</button>
<button class="ori-button ori-variant_tonal ori-color_danger">Danger</button>
<button class="ori-button ori-size-radius_sm ori-variant_outline">Squared</button>
<button class="ori-button ori-button_lg ori-variant_fill">Large</button>
```
::

## 4 · The escape hatch — per-instance color variables

When the color you need isn't one of the eight roles — a data-series swatch, a partner logo tint, one
marketing CTA — repoint the **resolved alias pair** on the element itself. `--ori-color` (the accent)
and `--ori-color-on` (its legible partner) are what every variant actually reads:

```vue
<OriButton text="One teal button" style="--ori-color: teal; --ori-color-on: white" />
```

```html
<button class="ori-button ori-variant_fill" style="--ori-color: teal; --ori-color-on: white">One teal button</button>
```

Because you repoint the alias the variants are built on, **all the machinery keeps working**:

- every variant maps your accent correctly — `fill` paints it as the background with `--ori-color-on`
  text; `tonal`'s tint derives from `--ori-color`; `outline`'s border reads `--ori-color-text`, the
  same tone as its label;
- hover and active states stay right, because they are `color-mix()` **derivations of the alias**
  (a filled button hovers to `color-mix(in srgb, var(--ori-color), white 15%)`) — there is no second
  "hover color" to supply;
- the focus ring (`outline: 2px solid var(--ori-color)`) follows;
- state styling is untouched — it keys off real attributes (`disabled`, `aria-busy`, `data-active`),
  never off the palette.

**On a non-fill variant** (`tonal` / `outline` / `text` / `plain`), the label reads a *third* alias,
`--ori-color-text` — not `--ori-color` directly (see
[Text — the on-surface foreground](https://oriui.vercel.app/guides/design-tokens#text-the-on-surface-foreground)). CSS custom
properties don't re-substitute on inheritance: setting only `--ori-color` here does **not** also
recompute `--ori-color-text` for you, because nothing on this element redeclares it. Set it alongside
the pair when you need a non-fill variant on a one-off color, mirroring the derived formula (the light
clamp shown here; nest a `max(l, 0.86)` version under `.ori-theme_dark` / `:root.dark` for a
dark-safe one-off too):

```vue
<OriButton
    text="One teal button"
    variant="tonal"
    style="--ori-color: teal; --ori-color-on: white; --ori-color-text: oklch(from teal min(l, 0.42) c h)"
/>
```

(The `.ori-color_*` utility classes handle this for you — they set all three aliases together, which
is why they're the recommended path over the escape hatch whenever the color *is* one of the eight
roles.)

This channel is *why* there are no `text-color` / `bg-color` props. A prop pair like that would bypass
the variant mapping and re-introduce the manual "pick a background AND a matching text" pairing the
roles abstract away — silently stepping around the AA-asserted pairing from level 1 — and it wouldn't
stop at two props (`border-color`, `hover-color`, …). The variable pair is strictly more powerful: one
declaration, every variant, every derived state
([the recorded decision](https://github.com/markgrushevski/oriui/blob/main/DECISIONS.md){rel="&#x22;nofollow&#x22;"}).

The honest trade-off: &#x2A;*contrast responsibility shifts to you.** The contrast test asserts the shipped
role pairs, not your inline values — always set `--ori-color-on` together with `--ori-color`, and pick
a pair that clears 4.5:1 (`white` on `teal` above is \~4.8:1). One more sharp edge: don't set
`--ori-color-primary-light` on the element here — nothing on the element reads it. That source token
only re-resolves into the alias up at `:root` (section 2); set directly on the element it is inert.

## 5 · Scope an override to a subtree

To restyle a *region* — a marketing section, a settings panel, an embedded widget — set inherited tokens
(or a mode class) on a wrapper. Everything inside inherits; everything outside is untouched. The rule
for *which* token to set: a wrapper can only feed tokens its descendants **substitute locally**.

**Color:** components bind the pair per element (`.ori-color_primary` reads
`var(--ori-color-primary)` right on the component), so repoint the **resolved role alias** on the
wrapper and every descendant that resolves primary picks it up:

```html
<section
    class="promo"
    style="--ori-color-primary: #16a34a; --ori-color-on-primary: #ffffff; --ori-color-primary-text: oklch(from #16a34a min(l, 0.42) c h)"
>
    <!-- buttons / cards in here render with the green primary; the rest of the page does not -->
</section>
```

Repoint `--ori-color-<role>-text` alongside the pair, as above — CSS custom properties don't
re-substitute on inheritance, so a descendant's `.ori-color_primary` (which reads
`var(--ori-color-primary-text)` for its non-fill/selected text) keeps the **page's** primary text tone
unless the wrapper also overrides `-text` itself; the fill background/on-color, by contrast, follows
the wrapper fine because the descendant reads `--ori-color-primary` directly.

Repointing a `*-light` / `*-dark` **source** token on the wrapper does nothing — the alias was already
resolved up at `:root`, so the wrapper's source value is never read. Setting the alias directly pins it
for the region in **both** modes; to keep a region mode-aware, wrap it in `.ori-theme_light` /
`.ori-theme_dark` and repoint the `*-light` / `*-dark` source there — that re-resolves the alias on the
wrapper, per mode.

**Radius and font-size** scope the other way around: their alias is substituted **on each component**
from the raw step (a card reads `var(--ori-size-radius_lg)` on itself), so on a wrapper you repoint
the **raw step**, not the alias:

```html
<div style="--ori-size-radius_md: 4px; --ori-font-size_md: 15px">
    <!-- panels, menus, inputs in here tighten; buttons keep their pinned `rounded` step -->
</div>
```

Or scope **mode** to a subtree with `.ori-theme_light` / `.ori-theme_dark` — the same selectors the global
`html.dark` toggle uses, but on any element:

```html
<!-- a dark callout inside an otherwise-light page -->
<aside class="ori-theme_dark">
    <!-- surface, primary, shadows all resolve to their dark values here -->
</aside>
```

To switch the whole palette to a named skin (Sumi, Cyber, …), that's a page-level toggle and a Theming
concern — see [Theming](https://oriui.vercel.app/guides/theming#scoping-a-skin-or-mode-to-a-subtree). (Skins are authored on
`:root[data-ori-skin='…']`, so `data-ori-skin` on a non-root wrapper matches nothing today; mode scoping
via `.ori-theme_*` works anywhere.)

## 6 · Five-minute brand walkthrough

The entire job, start to finish: &#x2A;*set your primary (light + dark), and a radius if you want one.** Same
components, no rewrite.

Import oriUI once (the stylesheet, or the Vue package which includes it):

```ts
import '@oriui/css'; // or: import '@oriui/vue' for the Vue components
```

Then add one `:root` block to your stylesheet:

```css
:root {
    /* your brand primary, both modes, with legible on-colors */
    --ori-color-primary-light: #7c3aed;
    --ori-color-on-primary-light: #ffffff;
    --ori-color-primary-dark: #a78bfa;
    --ori-color-on-primary-dark: #1e1035;

    /* your house radius — the derived scale (xs–xl) follows proportionally */
    --ori-size-radius_md: 6px;
}
```

That's it. Every primary button, focus ring, switch, and accent across the library is now your violet, in
light **and** dark — and it stays accessible, because state is real attributes and the `on-` pairing
carries the contrast. The radius change reaches every control on a **derived** step (cards, panels,
inputs); controls pinned to another step (buttons default to `rounded`) keep theirs until you set their
`radius` prop / `ori-size-radius_md` class to `md`. No component was edited, no class was added, nothing
was forked. Start with the defaults to prototype; drop in this block when you're ready to ship — that's
*scale without rewriting*.

## Icons follow the text color

There is no separate icon-color token — an icon **is text**, as far as color flows. `.ori-icon`
resolves its color from `currentcolor`, and everything inside it paints along
(`.ori-icon > * { fill: currentcolor }`), so whatever colors the text colors the icon: a role class, a
themed button, the escape-hatch pair above, or a plain CSS `color:` on any wrapper. Inside a filled
button the icon automatically renders in the `on-` color; a standalone icon takes the same `color`
prop / `ori-color_*` class as everything else:

```html
<span style="color: teal">
    <i class="ori-icon" aria-hidden="true"><svg viewBox="0 0 24 24">…</svg></i>
    teal text, teal icon — one declaration
</span>
```

## Reading tokens from JS

CSS variables stop at the canvas edge: Konva, ECharts, WebGL painters draw outside the CSS cascade, and
`getComputedStyle().getPropertyValue('--x')` only returns the *unresolved* `var()` chain. The headless
package ships the bridge — `useToken` / `useThemeColor` from `@oriui/headless/vue` resolve a token to
its computed value and re-resolve on every skin / mode flip:

```ts
import { useThemeColor } from '@oriui/headless/vue';

const brand = useThemeColor('primary'); // resolved --ori-color-primary; '' until mounted (SSR-safe)
watch(brand, (c) => engine.setColor(c || fallback)); // skin/mode flips re-push automatically
```

Colors-only for now — the probe resolves through the `color` property, so the token must resolve to a
`<color>`. The full pattern (seeding a canvas engine on mount, the framework-agnostic `resolveToken` /
`observeTheme` primitives, the Svelte twin) is in the
[`@oriui/headless` README](https://github.com/markgrushevski/oriui/blob/main/packages/headless/README.md#reading-tokens-from-js){rel="&#x22;nofollow&#x22;"}.

## See also

- [Design tokens](https://oriui.vercel.app/guides/design-tokens) — the full token catalog: the neutral ramp, every role, the
  size / radius / gap / font scales, and the canonical `@layer` order.
- [Theming](https://oriui.vercel.app/guides/theming) — switching whole palettes (named skins) and modes at runtime, and authoring
  your own skin.
- [Using the CSS layer](https://oriui.vercel.app/guides/css) — branding without Vue, in htmx, Astro, or plain HTML.
- [Get started](https://oriui.vercel.app/overview/get-started) · [Button](https://oriui.vercel.app/components/button) — the per-component class reference.


# Design tokens

oriUI is three independent layers woven around **one set of design tokens**. This page is the
catalog — every token, and the resolution model that turns a raw value into the colour a component
paints. The chain is short and deliberate: &#x2A;*a primitive feeds a semantic role, a role feeds a
per-instance alias, and components read only the alias.** That indirection is what lets a single
class repoint a single token — the whole zero-runtime theming story rests on it.

Two axes resolve slightly differently. **Colour is three-tier** (primitive → role → alias);
**size, radius, gap, and font-size are two-tier** (raw scale → alias). Everything here is plain CSS
custom properties under `@layer` — no JavaScript, no build step.

> This page is the reference. To **switch** skin and mode see [Theming](https://oriui.vercel.app/guides/theming); to
> **override or brand** see [Customization](https://oriui.vercel.app/guides/customization); for the standalone class story
> see [Using the CSS layer](https://oriui.vercel.app/guides/css).

## The cascade — `@layer` order

Every token and utility lives inside a layer, declared once in source order:

```css
@layer ori.reset, ori.tokens, ori.base, ori.components, ori.utilities;
```

Later layers win. `ori.tokens` holds the raw scales and role tokens at `:root`; `ori.utilities`
holds the `.ori-*_<step>` classes that repoint aliases. Because the order is fixed and explicit,
the cascade is predictable and **any unlayered consumer style wins over all of it** — overriding is
trivial, never a `!important` fight. The utility modifiers use a flat compound selector
(`.ori-color.ori-color_primary`), so their specificity stays low and consistent — layer order, not a
specificity contest, is what decides the cascade.

The contract for components is one line: &#x2A;*read the resolved alias, never a raw scale token, never a
hardcoded hex.**

## Colour — three tiers

### Tier 1 — primitives: the neutral ramp

A single slate-like ramp is the source of truth for neutral surfaces and text. Role tokens and skins
reference it instead of duplicating hex, so one neutral lives in exactly one place.

| Token               | Value     |
| ------------------- | --------- |
| `--ori-neutral-50`  | `#f8fafc` |
| `--ori-neutral-100` | `#f1f5f9` |
| `--ori-neutral-200` | `#e2e8f0` |
| `--ori-neutral-300` | `#cbd5e1` |
| `--ori-neutral-400` | `#94a3b8` |
| `--ori-neutral-500` | `#64748b` |
| `--ori-neutral-600` | `#475569` |
| `--ori-neutral-700` | `#334155` |
| `--ori-neutral-800` | `#1e293b` |
| `--ori-neutral-900` | `#0f172a` |
| `--ori-neutral-950` | `#020617` |

### Tier 2 — semantic role tokens (light/dark-aware)

Each role ships **four source tokens** — a light and dark value, each paired with a contrast-checked
`on-` colour (the legible foreground for text on that surface). The `on-` pairing is not decorative:
it is asserted by an executable WCAG-AA contrast test, so a filled surface always has readable text.
Values below are the default **Ori** skin.

| Role       | `*-light` | `on-*-light` | `*-dark`  | `on-*-dark` |
| ---------- | --------- | ------------ | --------- | ----------- |
| primary    | `#0369a1` | `#ffffff`    | `#38bdf8` | `#06131f`   |
| secondary  | `#e0f2fe` | `#0c4a6e`    | `#14384e` | `#e6f3fb`   |
| surface    | `#ffffff` | `#0a2233`    | `#0e2536` | `#e6f3fb`   |
| background | `#f3f8fc` | `#0a2233`    | `#06131f` | `#e6f3fb`   |

Above those sit **active aliases** — declared on `:root` and defaulting to the light source. These
are the "currently selected" role value:

```css
--ori-color-primary: var(--ori-color-primary-light);
--ori-color-on-primary: var(--ori-color-on-primary-light);
/* …secondary, surface, background, each defaulting to its -light source */
```

Each alias defaults to its `*-light` source; flipping mode repoints all eight at once to the matching
`*-dark&#x60; (or back) source, and a skin overrides only those source tokens for the four roles — so a
component reading the alias never changes. &#x2A;(How to flip mode and skin →
[Theming](https://oriui.vercel.app/guides/theming).)*

### Status tokens — shared, own hues

Status colours carry their own meaning across every theme. They are **not** repointed by mode and
**not** overridden by skins — `success` is green everywhere.

| Token                    | Value                    |
| ------------------------ | ------------------------ |
| `--ori-color-success`    | `#15803d`                |
| `--ori-color-on-success` | `#ffffff`                |
| `--ori-color-warn`       | `#f59e0b`                |
| `--ori-color-on-warn`    | `var(--ori-neutral-950)` |
| `--ori-color-danger`     | `#b91c1c`                |
| `--ori-color-on-danger`  | `#ffffff`                |
| `--ori-color-info`       | `#1d4ed8`                |
| `--ori-color-on-info`    | `#ffffff`                |

### Tier 3 — the per-instance component alias

Components never read a role token directly. They read **three** resolved aliases — `--ori-color`
(the surface), `--ori-color-on` (its legible foreground when the role is painted as a **fill**), and
`--ori-color-text` (its legible foreground when the role is painted as **text on the surrounding
surface**, covered next). All three default to a neutral, role-agnostic value so non-skinned use (an
avatar, an icon, bare text) stays sensible — `currentColor` for the first two, the on-surface ink for
the third:

```css
--ori-color: currentColor;
--ori-color-on: currentColor;
--ori-color-text: var(--ori-color-on-surface);
```

A role-specific `--ori-color-text` (below) is layered on by the `.ori-color_*` utility, or by a block
that bakes a role (Button, Tabs, Tag, …) — this `:root` default only ever surfaces for bare,
un-skinned usage.

A `.ori-color_*` utility class is what binds that triplet to a role — the same **base class plus a
scale value** pair (`ori-color` + `ori-color_<name>`) that the component pages use. Each sets all
three aliases at once:

| Class                   | `--ori-color` →               | `--ori-color-on` →               | `--ori-color-text` →              |
| ----------------------- | ----------------------------- | -------------------------------- | --------------------------------- |
| `.ori-color_primary`    | `var(--ori-color-primary)`    | `var(--ori-color-on-primary)`    | `var(--ori-color-primary-text)`   |
| `.ori-color_secondary`  | `var(--ori-color-secondary)`  | `var(--ori-color-on-secondary)`  | `var(--ori-color-secondary-text)` |
| `.ori-color_surface`    | `var(--ori-color-surface)`    | `var(--ori-color-on-surface)`    | `var(--ori-color-on-surface)`     |
| `.ori-color_background` | `var(--ori-color-background)` | `var(--ori-color-on-background)` | `var(--ori-color-on-background)`  |
| `.ori-color_success`    | `var(--ori-color-success)`    | `var(--ori-color-on-success)`    | `var(--ori-color-success-text)`   |
| `.ori-color_warn`       | `var(--ori-color-warn)`       | `var(--ori-color-on-warn)`       | `var(--ori-color-warn-text)`      |
| `.ori-color_danger`     | `var(--ori-color-danger)`     | `var(--ori-color-on-danger)`     | `var(--ori-color-danger-text)`    |
| `.ori-color_info`       | `var(--ori-color-info)`       | `var(--ori-color-on-info)`       | `var(--ori-color-info-text)`      |

So the full colour chain reads: &#x2A;*neutral ramp / role source → active alias → `--ori-color` /
`--ori-color-text` → the component.** Switching a colour is one class swap — `ori-color_primary` →
`ori-color_danger` — and every layer above resolves through `var()` with nothing recomputed.

All eight role pairs resolving live — each swatch is the same `.ori-color_*&#x60; utility, only the role
changes. &#x2A;(For the per-component usage of these classes, see [Button](https://oriui.vercel.app/components/button).)*

::example
:ori-button{color="primary" text="primary"}

:ori-button{color="secondary" text="secondary"}

:ori-button{color="surface" text="surface"}

:ori-button{color="background" text="background"}

:ori-button{color="success" text="success"}

:ori-button{color="warn" text="warn"}

:ori-button{color="danger" text="danger"}

:ori-button{color="info" text="info"}
::

### Text — the on-surface foreground

A role's `--ori-color-<role>` hue is engineered as a **fill background** — light or saturated,
paired with a legible `--ori-color-on-<role>` ink for text painted **on** that fill. Used the other
way round — as **text sitting on the surrounding surface** (the non-fill button variants, the
selected tab, alert, tag) — a light or saturated role can drop below the WCAG AA 4.5:1 body-text bar
(amber `warn` is the worst case). `--ori-color-<role>-text` is the dedicated on-surface tone for
exactly that — a **relative color** that keeps the role's own hue and chroma and clamps only its
lightness, so the text reads as the *same* colour as the fill, just darker (light theme) or lighter
(dark theme) — one hue, only lightness varies, not the muddier, different-looking colour a mix toward
a neutral ink would give:

| Role      | `--ori-color-<role>-text` — light default                 | `--ori-color-<role>-text` — dark override                 |
| --------- | --------------------------------------------------------- | --------------------------------------------------------- |
| primary   | `oklch(from var(--ori-color-primary) min(l, 0.42) c h)`   | `oklch(from var(--ori-color-primary) max(l, 0.86) c h)`   |
| secondary | `oklch(from var(--ori-color-secondary) min(l, 0.42) c h)` | `oklch(from var(--ori-color-secondary) max(l, 0.86) c h)` |
| success   | `oklch(from var(--ori-color-success) min(l, 0.42) c h)`   | `oklch(from var(--ori-color-success) max(l, 0.86) c h)`   |
| warn      | `oklch(from var(--ori-color-warn) min(l, 0.42) c h)`      | `oklch(from var(--ori-color-warn) max(l, 0.86) c h)`      |
| danger    | `oklch(from var(--ori-color-danger) min(l, 0.42) c h)`    | `oklch(from var(--ori-color-danger) max(l, 0.86) c h)`    |
| info      | `oklch(from var(--ori-color-info) min(l, 0.42) c h)`      | `oklch(from var(--ori-color-info) max(l, 0.86) c h)`      |

`oklch(from <color> L c h)` is CSS relative-color syntax: it derives a new color from an existing one,
carrying forward whichever channels you name bare. Naming `c` and `h` (chroma, hue) bare keeps them
exactly as the role's; only `L` (lightness) is replaced — clamped to `min(l, 0.42)` in light (never
lighter than 0.42) or `max(l, 0.86)` in dark (never darker than 0.86). Those are the tightest bounds
that clear WCAG AA (≥ 4.5:1) for every role × skin × text kind, including the tonal hover/active tint
(min \~4.55:1) — verified in real Chromium by `e2e/text-contrast.spec.ts`.

`surface` and `background` don't get their own `-text` token — their `on-` pair already **is** the
on-surface ink, so `.ori-color_surface` / `.ori-color_background` point `--ori-color-text` straight
at `--ori-color-on-surface` / `--ori-color-on-background` (see the table above).

The formula is declared **twice** — once at `:root` (the light default, shown above) and again inside
the dark theme selectors (`:root.dark`, `.ori-theme_dark`, with the opposite clamp) — so it tracks the
**active theme** automatically. Because both declarations read `var(--ori-color-<role>)`, the tone
also tracks any **skin*&#x2A;'s role override, or a brand's own override, at any nesting — a custom skin
gets an AA-safe text tone for free, no extra work required. &#x2A;(To override it — globally, per skin, or
per instance — see [Customization](https://oriui.vercel.app/guides/customization).)*

The `.ori-variant_outline` border (below) reads this same `-text` tone instead of the raw role, so an
outline button's border and label read as one colour.

## Variants

A variant is a small token group — border, opacity, background, text — set from the resolved
`--ori-color` / `--ori-color-on` / `--ori-color-text` triplet. Because variants read the alias,
**colour and variant compose freely**: any colour × any variant, no extra rules.

The base `.ori-variant` defaults to a transparent, full-opacity surface inheriting `currentColor`.
Each `.ori-variant_*` repoints the group:

| Variant    | background                                              | text                    | border                  | opacity |
| ---------- | ------------------------------------------------------- | ----------------------- | ----------------------- | ------- |
| `_fill`    | `var(--ori-color)`                                      | `var(--ori-color-on)`   | transparent             | `1`     |
| `_tonal`   | `color-mix(in srgb, var(--ori-color), transparent 75%)` | `var(--ori-color-text)` | transparent             | `1`     |
| `_outline` | transparent                                             | `var(--ori-color-text)` | `var(--ori-color-text)` | `1`     |
| `_text`    | transparent                                             | `var(--ori-color-text)` | transparent             | `1`     |
| `_plain`   | transparent                                             | `var(--ori-color-text)` | transparent             | `0.5`   |

`fill` keeps `--ori-color-on` — the ink tuned for its own solid background. Every non-fill mapping
instead reads `--ori-color-text` for its label, the AA-safe on-surface tone from
[Text — the on-surface foreground](https://oriui.vercel.app/#text-the-on-surface-foreground) above, because at those
opacities/borders the role is painted as **text on the page**, not as a fill. `outline`'s border reads
that same tone instead of the raw `--ori-color`, so the ring and the label read as one colour, and it
clears the WCAG 1.4.11 non-text 3:1 minimum for pale roles too.

Interaction state is derived from these same tokens, not stored — hover and `[data-active]` deepen
the `color-mix` per variant. (See the live behaviour on [Button](https://oriui.vercel.app/components/button).)

::example
:ori-button{text="Fill" variant="fill"}

:ori-button{text="Tonal" variant="tonal"}

:ori-button{text="Outline" variant="outline"}

:ori-button{text="Text" variant="text"}

:ori-button{text="Plain" variant="plain"}
::

## Sizes — two tiers

The size axis drops the role tier. A family has a **raw scale** of fixed values and a single
**resolved alias** that components read; a `.ori-<family>_<step>` utility class repoints the alias
to one scale value. That is the entire pattern — `raw scale → alias → component`, switched by a
class.

### Action (control height)

`md` is `2.75rem` — 44px at the browser-default 16px root, meeting the iOS HIG ≥44pt and Android
Material ≥48dp touch-target minimums; `xs` / `sm` are compact opt-ins for dense or icon-only UI. The
alias `--ori-size-action` defaults to `var(--ori-size-action_text)` (`1em`, i.e. font-driven).

| Token / step             | Value     |
| ------------------------ | --------- |
| `--ori-size-action_text` | `1em`     |
| `--ori-size-action_xs`   | `1.25rem` |
| `--ori-size-action_sm`   | `1.5rem`  |
| `--ori-size-action_md`   | `2.75rem` |
| `--ori-size-action_lg`   | `3rem`    |
| `--ori-size-action_xl`   | `3.75rem` |
| `--ori-size-action_xxl`  | `4.25rem` |

### Action-space (control padding)

Padding scale paired with action height; alias `--ori-size-action-space` defaults to
`var(--ori-size-action-space_text)` (`0`).

| Token / step                   | Value      |
| ------------------------------ | ---------- |
| `--ori-size-action-space_text` | `0`        |
| `--ori-size-action-space_xs`   | `0.625rem` |
| `--ori-size-action-space_sm`   | `0.75rem`  |
| `--ori-size-action-space_md`   | `0.625rem` |
| `--ori-size-action-space_lg`   | `0.75rem`  |
| `--ori-size-action-space_xl`   | `0.625rem` |
| `--ori-size-action-space_xxl`  | `0.75rem`  |

### Radius

Corners, computed from `md` (`0.5rem`) by a `0.125rem` step. Alias `--ori-size-radius` defaults to
`var(--ori-size-radius_md)`. Like the other scales, the raw values live at `:root`; the
`.ori-size-radius_*` utilities (in `ori.utilities`) only repoint the alias. There is no `_xxl`.

| Token / step                | Value (computed) |
| --------------------------- | ---------------- |
| `--ori-size-radius_zero`    | `0`              |
| `--ori-size-radius_xs`      | `0.125rem`       |
| `--ori-size-radius_sm`      | `0.25rem`        |
| `--ori-size-radius_md`      | `0.5rem`         |
| `--ori-size-radius_lg`      | `0.75rem`        |
| `--ori-size-radius_xl`      | `1rem`           |
| `--ori-size-radius_rounded` | `9999px`         |

### Gap

Spacing between items, same `md`/step derivation as radius. Alias `--ori-size-gap` defaults to
`var(--ori-size-gap_md)`. The `_xxl` raw token (`1.5rem`) exists but has **no repointing utility
class** — it is reachable only by reading the token directly.

| Token / step          | Value (computed)    |
| --------------------- | ------------------- |
| `--ori-size-gap_zero` | `0`                 |
| `--ori-size-gap_xs`   | `0.125rem`          |
| `--ori-size-gap_sm`   | `0.25rem`           |
| `--ori-size-gap_md`   | `0.5rem`            |
| `--ori-size-gap_lg`   | `0.75rem`           |
| `--ori-size-gap_xl`   | `1rem`              |
| `--ori-size-gap_xxl`  | `1.5rem` (no class) |

### Screen (breakpoints)

Pure constants for `@media` queries and consumer use — &#x2A;*no alias, no utility class.** You read these
directly.

| Token                   | Value    |
| ----------------------- | -------- |
| `--ori-size-screen_xs`  | `600px`  |
| `--ori-size-screen_sm`  | `840px`  |
| `--ori-size-screen_md`  | `1200px` |
| `--ori-size-screen_lg`  | `1600px` |
| `--ori-size-screen_xl`  | `1920px` |
| `--ori-size-screen_xxl` | `2560px` |

## Fonts — font-size

The type scale follows the same two-tier pattern, derived from `md` (`1rem`) by a `0.125rem` step. The
raw scale lives at `:root` and the `.ori-font-size_*` utilities repoint the alias; `--ori-font-size`
defaults to `var(--ori-font-size_text)` (`1em`, i.e. inherit).

| Token / step           | Value (computed) |
| ---------------------- | ---------------- |
| `--ori-font-size_text` | `1em`            |
| `--ori-font-size_xs`   | `0.75rem`        |
| `--ori-font-size_sm`   | `0.875rem`       |
| `--ori-font-size_md`   | `1rem`           |
| `--ori-font-size_lg`   | `1.125rem`       |
| `--ori-font-size_xl`   | `1.25rem`        |
| `--ori-font-size_xxl`  | `1.375rem`       |

Nothing pins the root: the size/font scales are `rem`, so they resolve against the user's browser
font-size setting (16px by default — at which the scales compute to their historical px values).

## Elevation — shadow tokens

Soft, cool-tinted shadows, **theme-aware**. Light tints with the neutral ink ramp at low alpha; dark
leans on deeper black plus a hairline highlight ring. Components read these directly.

Light (`:root`) — tinted with the neutral ink ramp at low alpha (`color-mix(in srgb, …, transparent)`):

| Token               | Value                                                            |
| ------------------- | ---------------------------------------------------------------- |
| `--ori-shadow-sm`   | `0 1px 2px (neutral-900 8%)`                                     |
| `--ori-shadow-md`   | `0 1px 2px (neutral-900 6%), 0 6px 16px -4px (neutral-900 12%)`  |
| `--ori-shadow-lg`   | `0 2px 4px (neutral-900 6%), 0 14px 36px -8px (neutral-900 18%)` |
| `--ori-shadow-ring` | `0 0 0 1px (neutral-900 8%)`                                     |

Dark (`:root.dark`, `.ori-theme_dark`) — deeper `#000000` shadow at higher alpha, and a `#ffffff 9%`
hairline highlight ring instead of an ink ring:

| Token               | Value                                               |
| ------------------- | --------------------------------------------------- |
| `--ori-shadow-sm`   | `0 1px 2px (#000 45%)`                              |
| `--ori-shadow-md`   | `0 1px 2px (#000 45%), 0 8px 24px -6px (#000 60%)`  |
| `--ori-shadow-lg`   | `0 2px 4px (#000 45%), 0 16px 40px -8px (#000 70%)` |
| `--ori-shadow-ring` | `0 0 0 1px (#fff 9%)`                               |

*(Alpha pairs are shorthand for `color-mix(in srgb, <color> <pct>, transparent)` — see the styles
source for the literal declarations.)*

## Why this enables zero-runtime theming

Every value above resolves through `var()` indirection, and components read **only the resolved
alias** — so the whole catalog is repointed by a class or attribute toggle, never by JavaScript. The
zero-runtime mechanics that ride on that — flipping mode, switching skins, and one-off overrides —
live in [Theming](https://oriui.vercel.app/guides/theming) and [Customization](https://oriui.vercel.app/guides/customization). The same tokens feed
the styled Vue components, the standalone [CSS layer](https://oriui.vercel.app/guides/css), and the
[headless core](https://oriui.vercel.app/headless/core), so you can move between layers, or reskin all of them, without a
rewrite.

## See also

- [Theming](https://oriui.vercel.app/guides/theming) — switch whole palettes and modes, and author a new named skin.
- [Customization](https://oriui.vercel.app/guides/customization) — one-off token overrides and per-instance tweaks, without
  authoring a whole skin.
- [Using the CSS layer](https://oriui.vercel.app/guides/css) — applying these tokens with the standalone `.ori-*` classes in
  htmx, Astro, or plain HTML.
- [Get started](https://oriui.vercel.app/overview/get-started) · [Button](https://oriui.vercel.app/components/button) · [Headless core](https://oriui.vercel.app/headless/core)


# Skin gallery

A **skin** is a named palette — a set of token overrides applied with one attribute on `<html>`
(`data-ori-skin`). Every skin repoints only the four skinnable roles (`primary` · `secondary` ·
`surface` · `background`, each with a `-light` and `-dark` source); the status hues (`success` ·
`warn` · `danger` · `info`) stay shared, and every pairing targets **WCAG AA** for body text. Switching
a skin is a single attribute write — zero runtime, no recompute, no flash.

The default skin is **Ori** (織り) — luminous azure and cyan. Seven presets ship alongside it; click any
card below to apply it across this whole site, and toggle light / dark to see both modes.

:skin-gallery

## How it works

Each preset lives in `@oriui/css` as a block of source-token overrides keyed on the attribute:

```css
:root[data-ori-skin='sumi'] {
    --ori-color-primary-light: #2b2d42;
    --ori-color-on-primary-light: #f4f1de;
    --ori-color-primary-dark: #f4f1de;
    /* …secondary / surface / background, light + dark… */
}
```

The [light / dark machinery](https://oriui.vercel.app/guides/theming#light-and-dark) then resolves the active
`--ori-color-*` aliases from whichever `*-light` / `*-dark` source the skin set. Because skins override
the **source** tokens (not the resolved aliases), they compose cleanly with the mode selectors — one
skin attribute × one mode class covers every combination.

> **Scope:** skins are **page-level** — the selector is `:root[data-ori-skin]`, so a skin applies to the
> whole document, not a subtree (the active alias resolves at `:root`; see
> [Design tokens](https://oriui.vercel.app/guides/design-tokens)). Light / dark, by contrast, *can* be scoped to a subtree with
> `.ori-theme_light` / `.ori-theme_dark`.

## Authoring a skin

A new skin is one CSS block — no build step, no JavaScript. See
[Theming → authoring a new named skin](https://oriui.vercel.app/guides/theming) for the full walkthrough, and
[Design tokens](https://oriui.vercel.app/guides/design-tokens) for the token catalog each skin repoints.


# Theming

A theme is a **mode** (light or dark) layered over a **skin** (a named palette). Both are pure
attribute toggles on `<html>` — flipping either repoints the active `--ori-color-*` aliases through
CSS custom properties, so everything reskins at once with **no JavaScript, no recompute, no flash**.
This is the same zero-runtime story across every layer: a Vue app, the standalone `@oriui/css`
classes, htmx fragments, or hand-written HTML all theme identically.

This guide covers **switching whole palettes and modes** and **authoring a new named skin**. The
token catalog itself lives in [Design tokens](https://oriui.vercel.app/guides/design-tokens); one-off token overrides and
per-instance tweaks live in [Customization](https://oriui.vercel.app/guides/customization).

## Light and dark

Every semantic role ships a `*-light` and a `*-dark` source token. The active alias the components
read — `--ori-color-primary`, `--ori-color-surface`, and so on — defaults to the light source on a
bare `:root`. Two explicit selectors repoint all eight active aliases and set `color-scheme`:

| Mode  | Selector                          | Effect                                                      |
| ----- | --------------------------------- | ----------------------------------------------------------- |
| Light | `:root.light`, `.ori-theme_light` | `color-scheme: light` + every alias → its `*-light` source. |
| Dark  | `:root.dark`, `.ori-theme_dark`   | `color-scheme: dark` + every alias → its `*-dark` source.   |

So dark mode is one class on the root element:

```html
<html class="dark">
    ...
</html>
```

`color-scheme` is part of the contract — it makes native form controls, scrollbars, and the
`prefers-color-scheme` UA defaults match the theme. The **status hues** (`success` · `warn` ·
`danger` · `info`) and the `--ori-color` / `--ori-color-on` component aliases are **not** touched by
the mode selectors — only the four skinnable roles repoint. Elevation shadows are mode-aware too: the
dark theme swaps the tinted-ink shadows for deeper black plus a hairline highlight ring.

## Built-in skins

A skin overrides only the `--ori-color-<role>-<light|dark>` **source** tokens for the four skinnable
roles — `primary`, `secondary`, `surface`, `background` (plus their `on-` pairs). It touches nothing
else: the light/dark machinery above resolves on top, so **every skin works in both modes** for free,
and the status hues stay shared across all skins.

Switching is a **single attribute** on `<html>` — zero runtime:

```html
<html data-ori-skin="cyber">
    ...
</html>
```

The default skin is **Ori** (luminous azure → glowing cyan) — applied when **no** `data-ori-skin`
attribute is present. Seven presets ship alongside it:

| `data-ori-skin` | Skin    | Palette                                                      |
| --------------- | ------- | ------------------------------------------------------------ |
| *(omitted)*     | Ori     | Luminous azure on ink and cool white — the default.          |
| `sumi`          | Sumi    | Graphite ink on warm washi paper (墨). Strict WCAG AA.        |
| `indigo`        | Indigo  | Calm indigo on cool grey — oriUI's previous default.         |
| `tech`          | Tech    | Cool cyan on slate — SaaS / developer-tool register.         |
| `health`        | Health  | Calm emerald on mint — medical / wellness.                   |
| `luxury`        | Luxury  | Deep gold on warm paper / charcoal — editorial / premium.    |
| `neutral`       | Neutral | Pure grays, monochrome accent — chrome for colorful content. |
| `cyber`         | Cyber   | Neon fuchsia on near-black — bold / nightlife.               |

Mode and skin compose — set both at once:

```html
<html class="dark" data-ori-skin="luxury">
    ...
</html>
```

Skinned color flows straight into the styled components and the `.ori-*` classes — a primary button
under `data-ori-skin="cyber"` is neon fuchsia, with its contrast-checked `on-` text following
automatically:

::example
:ori-button{color="primary" text="Primary"}

:ori-button{color="secondary" text="Secondary" variant="tonal"}

:ori-button{color="surface" text="Surface" variant="outline"}

#vue
```vue
<!-- skin + mode are set on <html>; components inherit the active palette -->
<OriButton text="Primary" color="primary" />
<OriButton text="Secondary" color="secondary" variant="tonal" />
<OriButton text="Surface" color="surface" variant="outline" />
```

#html
```html
<!-- skin + mode live on <html>; only the color pair changes per button -->
<button class="ori-button ori-variant ori-variant_fill ori-color ori-color_primary">Primary</button>
<button class="ori-button ori-variant ori-variant_tonal ori-color ori-color_secondary">Secondary</button>
<button class="ori-button ori-variant ori-variant_outline ori-color ori-color_surface">Surface</button>
```
::

## Scoping a skin or mode to a subtree

The mode and skin selectors come in two forms on purpose. The `:root.dark` / `:root[data-ori-skin]`
form is the page-level switch on `<html>`. The parallel `.ori-theme_dark` / `.ori-theme_light` class
repoints the active aliases on **any** element, so you can theme a region — a dark hero, a preview
card, an email-compose pane — without touching the page:

```html
<!-- the whole page is light; this panel renders dark -->
<section class="ori-theme_dark">
    <div class="ori-card … ori-color ori-color_surface">Always-dark panel</div>
</section>
```

One caveat: &#x2A;*skins are page-level today.** The active color alias resolves at `:root`, so
`data-ori-skin` only takes effect on the root element — you can scope a **mode** to a subtree, but not
yet a different **skin** per subtree (that needs a `light-dark()` restructure and is planned). Mode
scoping works anywhere.

## Setting the initial theme — no hydration flash

Because theming is just attributes, the **server can set them per request** from a cookie or user
preference, and the markup arrives already themed — nothing to hydrate, no flash. For a client-only
app, a tiny **pre-paint inline script** in `<head>` (before any stylesheet paints) reads the saved
choice and sets the attributes synchronously:

```html
<script>
    // runs before first paint — no flash of the wrong theme
    // (the storage keys are yours to choose — these mirror this site's convention)
    var skin = localStorage.getItem('ori-skin');
    var theme = localStorage.getItem('ori-theme'); // 'auto' | 'light' | 'dark' | null
    // RESOLVE the setting — it may be 'auto' (or unset); don't just test for 'dark'.
    var dark = theme === 'dark' || ((!theme || theme === 'auto') && matchMedia('(prefers-color-scheme: dark)').matches);
    document.documentElement.classList.add(dark ? 'ori-theme_dark' : 'ori-theme_light');
    if (skin) document.documentElement.setAttribute('data-ori-skin', skin);
</script>
```

Setting the attributes **before** first render is always safe — there is no rendered tree to update
yet. Runtime switches are the case that needs one small helper (below).

## Switching the mode at runtime

When a user flips dark mode *after* the page has rendered, `@oriui/headless` ships `applyTheme` (and
the `useTheme` composable on top). &#x2A;*Prefer them over a bare `classList.toggle`** — they flip the
class *and* work around a browser quirk:

> **Why not just toggle the class?** In current Chromium, changing the theme class at runtime can leave
> already-rendered components painting the **previous** theme's colours until they next re-render — the
> engine misses a style invalidation for the element-scoped custom properties every oriUI component
> bakes. `applyTheme` forces the affected subtree to re-resolve in the same tick, so the switch is
> correct immediately. (Setting the theme before first paint — server or the inline script above — never
> hits this: nothing is rendered yet.)

In a **Vue** app, `useTheme` owns the reactive state, persistence, and `auto` (live OS scheme), and
applies each change through the fix:

```vue
<script setup lang="ts">
import { useTheme } from '@oriui/headless/vue';

const { resolvedTheme, setTheme, toggleTheme, cycleTheme } = useTheme({
    storageKey: 'ori-theme', // persisted to localStorage; null to disable
    default: 'auto' // 'auto' follows prefers-color-scheme live; or 'light' / 'dark'
});
</script>

<template>
    <button @click="cycleTheme">Theme: {{ resolvedTheme }}</button>
</template>
```

`resolvedTheme` is the applied `'light'` / `'dark'`; `theme` is the setting (`'auto'` included).
`setTheme(mode)` pins a choice, `toggleTheme()` flips light ⇄ dark, `cycleTheme()` goes
`auto → light → dark`. A Svelte store twin ships at `@oriui/headless/svelte` (`$theme.resolvedTheme`

- the same setters). For **SSR** (e.g. Nuxt), keep the inline head script for the first paint — the
  composable is inert on the server and takes over on the client.

Have your own theme store, or vanilla JS? Call the low-level &#x2A;*`applyTheme`** exactly where you would
have toggled the class:

```ts
import { applyTheme } from '@oriui/headless';

// sets ori-theme_{dark,light} on <html> AND re-resolves the components — the drop-in for classList.toggle
applyTheme(isDark ? 'dark' : 'light');
```

The same invalidation applies to **any** runtime change of an inherited colour token: if you switch
`data-ori-skin` at runtime, call `flushThemeInvalidation(document.body)` (also from `@oriui/headless`)
right after the attribute write, for the same reason. Changing the skin **before** render never needs
it.

With **htmx** or server-rendered fragments, swapped-in HTML inherits the root attributes and is themed
on arrival — the fresh nodes resolve correctly on insertion, so there's nothing extra to call there
either.

## Authoring a custom skin

A skin is a plain CSS block that overrides the four role source tokens for both modes. Follow the
built-in pattern: scope it to `:root[data-ori-skin='<id>']`, set the eight `*-light` tokens and the
eight `*-dark` tokens (each role plus its `on-` pair), and let the light/dark machinery above resolve
the rest. You don't redefine status hues, elevation, or component aliases — they're inherited.

```css
/* a "brand" skin — emerald brand color on a warm-neutral page */
:root[data-ori-skin='brand'] {
    /* --- light --- */
    --ori-color-primary-light: #0f766e;
    --ori-color-on-primary-light: #ffffff;
    --ori-color-secondary-light: #ccfbf1;
    --ori-color-on-secondary-light: #134e4a;
    --ori-color-surface-light: #ffffff;
    --ori-color-on-surface-light: #14302c;
    --ori-color-background-light: #f3f8f6;
    --ori-color-on-background-light: #14302c;

    /* --- dark --- */
    --ori-color-primary-dark: #2dd4bf;
    --ori-color-on-primary-dark: #04201c;
    --ori-color-secondary-dark: #134e4a;
    --ori-color-on-secondary-dark: #d6fbf3;
    --ori-color-surface-dark: #0e2623;
    --ori-color-on-surface-dark: #d6fbf3;
    --ori-color-background-dark: #061513;
    --ori-color-on-background-dark: #d6fbf3;
}
```

Drop that anywhere in your own stylesheet (it can live outside oriUI's `@layer` blocks — unlayered
rules win the cascade), set `data-ori-skin="brand"` on `<html>`, and every component and `.ori-*`
class picks it up in both modes. Nothing else changes.

### Contrast is a contract, not a hope

Every role pairs a background token with an `on-` text token, and the pair must clear **WCAG AA — a
contrast ratio of at least 4.5:1** for normal text. The defaults are checked: Ori's light primary is
white on azure `#0369a1` (\~5.9:1), its dark primary is ink `#06131f` on cyan `#38bdf8` (\~8.7:1), and
every built-in skin is held to WCAG AA for body text. Pick your `on-` colors deliberately — a
near-white on a mid-tone brand color often misses, and the dark variant needs its own check because
it inverts.

This isn't on the honor system. The repo ships an **automated contrast test**
(`tests/tokens.contrast.test.ts`) that parses the skin CSS and asserts every role / `on-role` pair
meets AA across both modes — it has already caught a real failure (a Sumi `secondary-dark` pairing at
4.18:1). If you add a skin to the library, add it to that guard.

## See also

- [Design tokens](https://oriui.vercel.app/guides/design-tokens) — the full token catalog: the neutral ramp, every role, the
  size / radius / gap / font scales.
- [Customization](https://oriui.vercel.app/guides/customization) — one-off token overrides and per-instance tweaks, without
  authoring a whole skin.
- [Using the CSS layer](https://oriui.vercel.app/guides/css) — applying themes with the standalone `.ori-*` classes in htmx,
  Astro, or plain HTML.
- [Get started](https://oriui.vercel.app/overview/get-started) · [Button](https://oriui.vercel.app/components/button) · [Headless core](https://oriui.vercel.app/headless/core)


# @oriui/headless

The framework-agnostic heart of the headless layer: a **behaviour contract** plus a zero-dependency
**native engine**, written in vanilla TypeScript. Every framework binding consumes the same contract,
so a primitive behaves identically wherever it runs — and the behaviour stays swappable per primitive,
without touching markup.

This is the **agnostic** layer. It has no Vue, no Svelte, no CSS. For the concrete composable API, see
the Vue binding pages — [useDisclosure](https://oriui.vercel.app/headless/use-disclosure) and [useDialog](https://oriui.vercel.app/headless/use-dialog),
with the rest linked from [The core toolkit](https://oriui.vercel.app/#the-core-toolkit) below; for the standalone styling layer
see the [CSS guide](https://oriui.vercel.app/guides/css).

## The layered idea

The headless layer is split along a framework axis. The behaviour lives once, in the core; each
binding is a thin adapter from the core contract to a framework's reactivity.

| Package                  | What it is                                                                                                                                                                  | Framework    |
| ------------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------ |
| `@oriui/headless`        | Behaviour contract + native engine                                                                                                                                          | **agnostic** |
| `@oriui/headless/vue`    | Vue bindings — the composables (`useDisclosure` / `useDialog` / `useCombobox` / `useMenu` / `useToolbar`) + the `useToken` / `useTheme` bridges, as `ComputedRef`s / `Ref`s | Vue          |
| `@oriui/headless/svelte` | The same composables as Svelte stores                                                                                                                                       | Svelte       |

## The contract

Each primitive exposes a **control shape**: reactive open state, ARIA-correct **prop bags**, and
imperative handlers. A component spreads the prop bags onto its markup — it never hand-rolls focus,
keyboard, or ARIA. For the native disclosure engine the shape is `DisclosureApi`:

```ts
import { disclosure, createNormalizer } from '@oriui/headless';

// `connect()` lives in core but the prop normalizer is per-framework. A binding
// imports its own (Vue's `normalizeProps` from @oriui/headless/vue); here we build a
// minimal pass-through to keep the example self-contained.
const normalizeProps = createNormalizer((props) => props);

const service = disclosure.machine({ id: 'demo', defaultOpen: false });
const api = disclosure.connect(service, normalizeProps);

api.open; // boolean
api.getRootProps(); // { data-scope, data-part, data-state }
api.getTriggerProps(); // { data-scope, data-part, id, type, aria-controls, aria-expanded, onClick, … }
api.getContentProps(); // { data-scope, data-part, id, role: 'region', aria-labelledby, hidden, data-state }
api.setOpen(true);
api.toggle();
```

Every part bag (root, trigger, content) carries the anatomy's `data-scope` / `data-part` attrs, and
the content bag is a landmark `region` (`role: 'region'`). The prop bags are framework-neutral **plain
objects**. `connect()` is a pure projection of machine state to prop-getters; the binding supplies a
`normalizeProps` transform (Vue keeps `onClick`, Svelte lowercases it to `onclick`) and re-invokes
`connect()` on every state change, wrapping the result in the framework's reactivity primitive — a Vue
`ComputedRef` or a Svelte store. The same engine, the same ARIA, expressed once.

Three small building blocks back every primitive:

| Export          | Role                                                                                          |
| --------------- | --------------------------------------------------------------------------------------------- |
| `createMachine` | A tiny reducer-based state container with a `subscribe` seam — the only place a binding taps  |
| `createScope`   | Deterministic, SSR-stable element ids derived from one base `id` (`getId('trigger')`)         |
| `createAnatomy` | Names a component's parts and emits the `data-scope` / `data-part` attrs + matching selectors |
| `mergeProps`    | Type-aware left-to-right merge so a consumer can layer a handler / `class` / `style` on a bag |

## The core toolkit

Beyond the disclosure engine above, `@oriui/headless` ships the behaviour every binding composes —
state machines, pure roving-focus math, and the theme / token bridges. All framework-agnostic; the Vue
and Svelte adapters consume them without re-implementing anything.

| Export                                                            | What it is                                                                                                                                                                         | Vue binding                                                                                                                                                                               |
| ----------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `disclosure` · `combobox` · `menu`                                | Namespaced state machines — each a `{ machine, connect, anatomy }` (mirroring Zag's `import * as disclosure`): the reducer plus the pure prop-getter projection for the widget.    | [useDisclosure](https://oriui.vercel.app/headless/use-disclosure) · [useCombobox](https://oriui.vercel.app/headless/use-combobox) · [useMenu](https://oriui.vercel.app/headless/use-menu) |
| `rovingIntent` · `resolveRovingIndex` · `ownsArrowKeys`           | Roving-tabindex toolkit — pure key→intent and intent→index math (`roving`), plus the "yield the arrows to a composite child" DOM predicate (`roving-dom`). &#x2A;*Not a machine.** | [useToolbar](https://oriui.vercel.app/headless/use-toolbar)                                                                                                                               |
| `resolveToken` · `observeTheme`                                   | Token bridge — resolve an `--ori-*` token to its computed value from JS (`''` when unresolvable or on the server) and subscribe to skin / mode changes.                            | [useToken](https://oriui.vercel.app/headless/use-token)                                                                                                                                   |
| `applyTheme` · `createThemeController` · `flushThemeInvalidation` | Theme controller — apply + persist light / dark, and the workaround for the Chromium runtime-toggle invalidation bug.                                                              | [useTheme](https://oriui.vercel.app/headless/use-theme)                                                                                                                                   |

Only the top row is a state machine — disclosure, combobox, and menu follow the `machine` + `connect`
projection shown above. The other three rows are deliberately **not** machines: the roving helpers are
pure functions a widget composes itself (the toolbar is a `provide` / `inject` roving **context**, not a
machine behind an adapter — see [useToolbar](https://oriui.vercel.app/headless/use-toolbar)), and the token / theme bridges read
and react to the DOM cascade rather than projecting reducer state.

## Adapters

Behaviour is chosen per primitive — provided once at the app root, never threaded through markup.

- **Disclosure** — a native, zero-dependency engine ships from `@oriui/headless` as the default. Nothing
  to wire; it just works.
- **Dialog** — runs on the native `<dialog>` element (`showModal()`), so the focus trap, scroll lock,
  focus return, `::backdrop` and `aria-modal` come from the platform. It is the **default**, with no
  adapter or dependency required. See [useDialog](https://oriui.vercel.app/headless/use-dialog).
- **Combobox** / **Menu** — no native platform primitive, so the default is the in-house `core` state
  machine (the WAI-ARIA listbox / menu keyboard). Swappable through the same contract. See
  [useCombobox](https://oriui.vercel.app/headless/use-combobox) · [useMenu](https://oriui.vercel.app/headless/use-menu).

Each defaults to a zero-dependency engine. The `OriHeadless` plugin (from `@oriui/headless/vue`) is the hedge for
swapping an engine per primitive — e.g. a custom or Zag-backed adapter for a genuinely hard widget —
without changing a component's template:

```ts
import { OriHeadless } from '@oriui/headless/vue';

// Each defaults to native; register an adapter only to override the one you want.
app.use(OriHeadless, { dialog: myDialog, combobox: myCombobox });
```

## Frameworks

The same core powers each binding, so a primitive behaves the same everywhere.

- **Vue** — the full set of composables: [useDisclosure](https://oriui.vercel.app/headless/use-disclosure), [useDialog](https://oriui.vercel.app/headless/use-dialog), [useCombobox](https://oriui.vercel.app/headless/use-combobox), [useMenu](https://oriui.vercel.app/headless/use-menu), [useToolbar](https://oriui.vercel.app/headless/use-toolbar), [useColorPicker](https://oriui.vercel.app/headless/use-color-picker), plus the [useToken](https://oriui.vercel.app/headless/use-token) / [useTheme](https://oriui.vercel.app/headless/use-theme) bridges. (useToolbar / useColorPicker are compositional helpers — pure core math + a composable — rather than the swappable adapter contract.)
- **Svelte** — `@oriui/headless/svelte` consumes the identical contract, returning Svelte stores (lowercased event handlers, `MaybeReactive` options); no behaviour is re-implemented.

## See also

- The Vue composables — [useDisclosure](https://oriui.vercel.app/headless/use-disclosure) · [useDialog](https://oriui.vercel.app/headless/use-dialog) ·
  [useCombobox](https://oriui.vercel.app/headless/use-combobox) · [useMenu](https://oriui.vercel.app/headless/use-menu) ·
  [useToolbar](https://oriui.vercel.app/headless/use-toolbar) · [useColorPicker](https://oriui.vercel.app/headless/use-color-picker) ·
  [useToken](https://oriui.vercel.app/headless/use-token) · [useTheme](https://oriui.vercel.app/headless/use-theme).
- [Dialog](https://oriui.vercel.app/components/dialog) — a styled component that consumes a headless contract (every component
  page shows the same pattern).
- [CSS layer](https://oriui.vercel.app/guides/css) — the other framework-agnostic layer: standalone `.ori-*` classes + tokens.


# useColorPicker

A headless **sRGB color picker** — a 2D **saturation × brightness** area, a **hue** channel, an optional
**alpha** channel, a **hex** field, and optional **preset** swatches, assembled from ready-to-bind
prop-getters. It owns the working color as an internal **HSVA** object (so the hue survives a grayscale
round-trip when you drag into a corner and back) and composes a zero-dependency sRGB engine plus pure
2D-area math from the core: `parseColor` / `formatColor` (loose parse in, lowercase string out),
`hsvToRgb` / `rgbToHex` / `rgbToHsl` (hex / rgb / hsv / hsl conversion), `readableInk` (WCAG-luminance
ink over a swatch), and `resolveAreaPosition` / `stepAreaPosition` (pointer → coordinate and keyboard
stepping across the two axes).

This is the **Vue** binding; the framework-agnostic core lives in [`@oriui/headless`](https://oriui.vercel.app/headless/core),
and the styled [`OriColorPicker`](https://oriui.vercel.app/components/color-picker) is built on it. Like
[`useToolbar`](https://oriui.vercel.app/headless/use-toolbar), this is a **compositional** helper — deterministic sRGB + 2D-area
math exposed as prop-getters and setters — **not** the OriHeadless adapter contract: a color picker has
no swappable engine and no async state to project, so (unlike [`useDialog`](https://oriui.vercel.app/headless/use-dialog)'s
machine-behind-a-swappable-adapter shape) there is nothing to swap. It does reuse the same core **roving**
helpers as the toolbar (`rovingIntent` / `resolveRovingIndex`) for the preset listbox — see the
[roving taxonomy](https://oriui.vercel.app/headless/use-toolbar) framing.

## Import

```ts
import { useColorPicker } from '@oriui/headless/vue';
```

## Options

`useColorPicker(options)` takes its options as a **getter** — `useColorPicker(() => ({ … }))`, like
[`useToolbar`](https://oriui.vercel.app/headless/use-toolbar) / [`useMenu`](https://oriui.vercel.app/headless/use-menu) — so `value` / `format` /
`disabled` stay reactive. The color crosses the boundary as a **lowercase string** (bind to `v-model`),
with the dual-event convention: `onInput` streams live on every interaction tick, `onChange` commits once
on release / keyboard settle (one undo entry).

| Option       | Type                     | Default | Description                                                                                                      |
| ------------ | ------------------------ | ------- | ---------------------------------------------------------------------------------------------------------------- |
| `value`      | `string | undefined`     | —       | The controlled color (the `v-model` value). Parsed loosely: hex, `rgb()/rgba()`, `hsl()/hsla()`.                 |
| `format`     | `'hex' | 'rgb' | 'hsl'`  | `'hex'` | Output format of the emitted string (`ColorFormat`). `rgb` / `hsl` emit function notation; output is lowercase.  |
| `alpha`      | `boolean`                | `false` | Include an alpha channel — the emitted string carries it (`#rrggbbaa` / `rgba()` / `hsla()`).                    |
| `eyedropper` | `boolean`                | `false` | Expose an eyedropper action (the `EyeDropper` API); `eyedropperSupported` is `false` where the browser lacks it. |
| `label`      | `string`                 | —       | Accessible name for the whole control (→ `aria-label` on the root `role="group"`).                               |
| `disabled`   | `boolean`                | `false` | Blocks the area pointer drag / keyboard and disables the channel inputs.                                         |
| `presets`    | `string[]`               | —       | Preset swatch colors, rendered as a single-select roving listbox.                                                |
| `onInput`    | `(next: string) => void` | —       | **Required.** Live value on every interaction tick — wire to `update:modelValue`.                                |
| `onChange`   | `(next: string) => void` | —       | **Required.** Committed value on pointer-release / keyboard settle — wire to `change` (one undo entry).          |

## Returns

Reactive state, prop-getters (spread with `v-bind`), and imperative setters. `HSVA` is
`{ h, s, v, a }` (h ∈ \[0, 360), s / v / a ∈ [0, 1] ); `RGB` is `{ r, g, b }` (0–255).

### Reactive state

| Property              | Type                                 | Description                                                                                                                                                                         |
| --------------------- | ------------------------------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `hsva`                | `ComputedRef<HSVA>`                  | The working color — the source of truth during interaction (hue preserved across a grayscale trip).                                                                                 |
| `rgb`                 | `ComputedRef<RGB>`                   | The working color as RGB (0–255), derived from `hsva`.                                                                                                                              |
| `hex`                 | `ComputedRef<string>`                | The hex the field shows: `#rrggbbaa` when `alpha` is on, else `#rrggbb`.                                                                                                            |
| `value`               | `ComputedRef<string>`                | The current color in the emitted `format` — the value a form submits; matches `v-model` after any emit (an initial value in another format still reports in `format`). Never empty. |
| `hue`                 | `ComputedRef<number>`                | The current hue, 0–360 (bind to the hue slider).                                                                                                                                    |
| `alpha`               | `ComputedRef<number>`                | The current alpha, 0–1 (bind to the alpha slider).                                                                                                                                  |
| `swatchColor`         | `ComputedRef<string>`                | The preview color — carries alpha, so a checkerboard shows through.                                                                                                                 |
| `opaqueColor`         | `ComputedRef<string>`                | The opaque current color, for the alpha slider's transparent → color track.                                                                                                         |
| `ink`                 | `ComputedRef<'#000000' | '#ffffff'>` | Readable ink over the current color, per WCAG luminance (`readableInk`).                                                                                                            |
| `hueColor`            | `ComputedRef<string>`                | The fully-saturated hue color — the area's `--ori-hue` gradient anchor.                                                                                                             |
| `eyedropperSupported` | `boolean`                            | Whether the `EyeDropper` API exists (a plain, non-reactive boolean — gate the eyedropper trigger on it).                                                                            |

### Prop-getters

| Property                        | Type                                          | Description                                                                                                                                                                                      |
| ------------------------------- | --------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `areaProps`                     | `ComputedRef<object>`                         | The 2D area's bag: `role="group"`, `aria-label="Saturation and brightness"`, `aria-disabled`, the inline `--ori-hue` style, and the drag `onPointerdown` + 2D `onKeydown`.                       |
| `areaThumbStyle`                | `ComputedRef<{ left: string; top: string }>`  | Inline position for the area thumb: `left` = saturation, `top` = inverted value (1 = top).                                                                                                       |
| `getChannelInputProps(channel)` | `(channel: 'saturation' | 'value') => object` | Props for one of the two visually-hidden `<input type="range">` (the a11y surface): `type="range"`, `min`/`max`/`step`, `value` (0–100), `aria-label`, `aria-valuetext`, `onInput`.              |
| `presetGroupProps`              | `ComputedRef<object>`                         | The preset listbox bag: `role="listbox"`, `aria-label="Preset colors"`, `aria-orientation="horizontal"`.                                                                                         |
| `getPresetProps(color, index)`  | `(color: string, index: number) => object`    | Props for one preset chip: `data-ori-preset`, `type="button"`, `role="option"`, `aria-label`, `aria-selected`, the roving `tabindex`, the inline `--ori-color` style, and `onClick` / `onFocus`. |
| `onPresetKeydown`               | `(event: KeyboardEvent) => void`              | The roving arrow-key handler for the preset listbox — bind to the group's `@keydown`.                                                                                                            |

### Setters & actions

| Property                   | Type                             | Description                                                                                                                            |
| -------------------------- | -------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------- |
| `setHue(h)`                | `(h: number) => void`            | Set the hue (wrapped into \[0, 360)); emits `onInput`.                                                                                 |
| `setAlpha(a)`              | `(a: number) => void`            | Set alpha (clamped 0–1); emits `onInput`.                                                                                              |
| `setSaturationValue(s, v)` | `(s: number, v: number) => void` | Set saturation + value (0–1 each); emits `onInput`. The area's pointer / keyboard math calls this.                                     |
| `setColor(next)`           | `(next: string) => boolean`      | Parse a full color string (hex entry, preset click) and apply — a commit (emits `onInput` + `onChange`). Returns whether it parsed.    |
| `setHex`                   | `(next: string) => boolean`      | Alias of `setColor` — the name the hex field reads by.                                                                                 |
| `openEyeDropper()`         | `() => Promise<void>`            | Open the `EyeDropper`; on pick, apply the color (keeping the current alpha) and commit. No-op when unsupported / disabled / dismissed. |
| `commit()`                 | `() => void`                     | Commit the current color (emits `onChange`) — one undo entry per pointer-release / keyboard settle.                                    |

## Usage

The picker is assembled from the parts you spread its getters onto — exactly what the styled
[`OriColorPicker`](https://oriui.vercel.app/components/color-picker) wraps. Bind `areaProps` on the 2D surface with its two
visually-hidden range inputs, drive a slider off `hue` / `setHue`, feed the hex field through `setHex`,
and render `presets` as the roving listbox.

```vue
<script setup lang="ts">
import { ref, watch } from 'vue';
import { useColorPicker } from '@oriui/headless/vue';
import type { ColorFormat } from '@oriui/headless/vue';

const { format = 'hex', presets } = defineProps<{ format?: ColorFormat; presets?: string[] }>();

const model = defineModel<string>();
const emit = defineEmits<{ change: [value: string] }>();

// Options are a GETTER, so value / format stay reactive. onInput drives v-model (live),
// onChange commits (one undo entry).
const cp = useColorPicker(() => ({
    value: model.value,
    format,
    presets,
    onInput: (next) => {
        model.value = next;
    },
    onChange: (next) => emit('change', next)
}));

// The hex field holds a local draft so a partial entry isn't reformatted mid-type; cp.hex re-seeds it.
const hexDraft = ref(cp.hex.value);
watch(
    () => cp.hex.value,
    (hex) => {
        hexDraft.value = hex;
    }
);
</script>

<template>
    <div role="group" :aria-label="label">
        <!-- 2D saturation × value area. The two visually-hidden range inputs are the a11y surface
             (role=slider, focusable, form value); the area's keydown routes the arrows across both axes. -->
        <div v-bind="cp.areaProps.value">
            <span :style="cp.areaThumbStyle.value" aria-hidden="true"></span>
            <input class="sr-only" v-bind="cp.getChannelInputProps('saturation')" />
            <input class="sr-only" v-bind="cp.getChannelInputProps('value')" />
        </div>

        <!-- Preview swatch — role=img named by the current color, ink chosen for contrast. -->
        <span
            role="img"
            :aria-label="cp.hex.value"
            :style="{ background: cp.swatchColor.value, color: cp.ink.value }"
        />

        <!-- Hue slider — a native range in [0, 360); commit on release. -->
        <input
            type="range"
            :min="0"
            :max="360"
            :step="1"
            :value="cp.hue.value"
            aria-label="Hue"
            @input="cp.setHue(Number(($event.target as HTMLInputElement).value))"
            @change="cp.commit"
        />

        <!-- Hex field — setHex parses and commits, returning false on a bad hex. -->
        <input
            :value="hexDraft"
            aria-label="Hex color"
            spellcheck="false"
            @input="hexDraft = ($event.target as HTMLInputElement).value"
            @blur="cp.setHex(hexDraft)"
            @keydown.enter="cp.setHex(hexDraft)"
        />

        <!-- Presets — a single-select roving listbox (one tab stop; arrows move focus). -->
        <div v-if="presets?.length" v-bind="cp.presetGroupProps.value" @keydown="cp.onPresetKeydown">
            <button v-for="(preset, i) in presets" :key="preset" v-bind="cp.getPresetProps(preset, i)"></button>
        </div>
    </div>
</template>
```

Passing `alpha: true` adds the alpha channel (bind a second slider to `alpha` / `setAlpha`, using
`opaqueColor` for its track), and `eyedropper: true` enables `openEyeDropper` (gate its trigger on
`cp.eyedropperSupported`) — see how the styled [`OriColorPicker`](https://oriui.vercel.app/components/color-picker) wires both.

The **Svelte** binding is the store twin (`@oriui/headless/svelte`) over the same core engine — the prop
bags are `Readable` stores you auto-subscribe with `$`, the per-part getters are **stores of functions**
(`$getChannelInputProps('saturation')`, `$getPresetProps(color, i)`), and event handlers are lowercased
(`onpointerdown` / `onkeydown` / `oninput` / `onclick` / `onfocus`). Options are a plain object or a store:

```svelte
<!-- MyColorPicker.svelte -->
<script>
    import { writable } from 'svelte/store';
    import { useColorPicker } from '@oriui/headless/svelte';

    export let color = '#3366ff';
    // Pass a STORE (not a snapshot object) so an external `color` change re-syncs into the picker — a plain
    // object becomes a constant store (`toReadable`) and would only seed the initial value.
    const options = writable({ value: color, onInput: (v) => (color = v), onChange: (v) => (color = v) });
    $: options.set({ value: color, onInput: (v) => (color = v), onChange: (v) => (color = v) });

    const cp = useColorPicker(options);
    const { areaProps, areaThumbStyle, getChannelInputProps, hue, hex } = cp;
</script>

<div {...$areaProps}>
    <span style:left={$areaThumbStyle.left} style:top={$areaThumbStyle.top} aria-hidden="true"></span>
    <input {...$getChannelInputProps('saturation')} />
    <input {...$getChannelInputProps('value')} />
</div>
<input type="range" min="0" max="359" value={$hue} on:input={(e) => cp.setHue(+e.currentTarget.value)} on:change={cp.commit} />
<input value={$hex} aria-label="Hex color" on:blur={(e) => cp.setHex(e.currentTarget.value)} />
```

## Accessibility

The prop-getters carry the ARIA and keyboard contract; nothing is hand-rolled that a native control
already provides.

- **The 2D area is two visually-hidden native `<input type="range">`** — one per axis
  (`getChannelInputProps('saturation')` / `('value')`). Each is a real `role="slider"` with its own
  `aria-label` and `aria-valuetext` (`"60%"`), focusable, announced, and form-associable. The arrow keys
  are routed across both axes by `areaProps`' `onKeydown` (a single native range spans only one axis); it
  `preventDefault`s the navigation keys and bubbles from the focused channel input. `getChannelInputProps`'
  own `onInput` still covers an assistive technology that sets a channel value directly.
- **The preview swatch is `role="img"`**, named by the current color; `ink` picks black or white content
  for WCAG contrast over it.
- **Presets are a single-select `role="listbox"`** (`presetGroupProps`) with **roving tabindex** — one tab
  stop, arrow keys move real DOM focus (`onPresetKeydown`, wrapping), `aria-selected` marks the active
  color. Each chip is a `role="option"` button labelled by its color.
- **`label`** names the whole control (`role="group"&#x60;); &#x2A;*`disabled`** blocks the area drag / keyboard and
  disables the channel inputs.

**Area keyboard** (focus is on a channel input; the area routes the key):

| Key                        | Action                                                    |
| -------------------------- | --------------------------------------------------------- |
| `ArrowLeft` / `ArrowRight` | Decrease / increase **saturation** by 1% (`Shift` = ×10). |
| `ArrowDown` / `ArrowUp`    | Decrease / increase **brightness** by 1% (`Shift` = ×10). |
| `PageDown` / `PageUp`      | Decrease / increase **brightness** by 10%.                |
| `Home` / `End`             | Jump **saturation** to 0% / 100%.                         |

## See also

- [@oriui/headless](https://oriui.vercel.app/headless/core) — the framework-agnostic core: the zero-dependency sRGB engine and the
  pure 2D-area math behind this binding.
- [Color picker](https://oriui.vercel.app/components/color-picker) — the styled `OriColorPicker` built on this composable.
- [Slider](https://oriui.vercel.app/components/slider) — the native-range primitive the styled picker reuses for the hue / alpha channels.
- [Popover](https://oriui.vercel.app/components/popover) — compose the inline picker into a popover for a swatch-triggered flow.


# useCombobox

A headless **combobox** primitive — an editable text input paired with a popup listbox — implementing
the WAI-ARIA *combobox with listbox popup* pattern: type to filter, navigate with the keyboard via
active-descendant, and pick a single option. It owns the behaviour (open/close, filtering, the
highlight, selection, and the full keyboard) and the ARIA wiring as ready-to-bind prop bags; **you own
the markup and styles**.

This is the **Vue** binding; the framework-agnostic core lives in [`@oriui/headless`](https://oriui.vercel.app/headless/core),
and the styled [`OriCombobox`](https://oriui.vercel.app/components/combobox) is built on it. Unlike
[`useDialog`](https://oriui.vercel.app/headless/use-dialog) / [`useDisclosure`](https://oriui.vercel.app/headless/use-disclosure) lean on a
zero-dependency native platform default; a combobox has no native primitive, so `useCombobox`'s
**default** is the core **state machine + prop-getters**. Like the overlays it still resolves through the
[`OriHeadless`](https://oriui.vercel.app/headless/core) contract, so an app can swap a custom / Zag-backed engine — the native
core adapter is simply the default. It is the first behavior to fully exercise the
[`@oriui/headless`](https://oriui.vercel.app/headless/core) engine.

## Import

```ts
import { useCombobox } from '@oriui/headless/vue';
```

## Options

Pass an options object — or a getter returning one, to stay reactive (the styled component passes
`() => ({ … })`). `options`, `disabled`, and `filter` are read live; `id` and the initial `value` /
`inputValue` are read once at setup.

| Option       | Type                                             | Default        | Description                                                                                     |
| ------------ | ------------------------------------------------ | -------------- | ----------------------------------------------------------------------------------------------- |
| `options`    | `ComboboxItem[]`                                 | **required**   | The full option list. Reactive — filtering re-runs when it changes.                             |
| `id`         | `string`                                         | auto (`useId`) | Stable base id for the part ARIA wiring; auto-generated when omitted (pass one for stable SSR). |
| `value`      | `string | null`                                  | `null`         | Initial selected value (uncontrolled).                                                          |
| `inputValue` | `string`                                         | `''`           | Initial input text (uncontrolled).                                                              |
| `disabled`   | `boolean`                                        | `false`        | Disable the control; also closes the listbox.                                                   |
| `filter`     | `(item: ComboboxItem, query: string) => boolean` | substring      | Filter predicate; default = case-insensitive substring on the label. Swap for fuzzy / async.    |

Each option is a `ComboboxItem` — `value` is the stable identity, `label` is what the input shows:

```ts
interface ComboboxItem {
    value: string;
    label: string;
    disabled?: boolean;
}
```

## Returns

A control object — the reactive state plus the prop bags you bind to each part. Every `*Props` value is
a `ComputedRef`; bind it with `v-bind`. The `get*` / `set*` and the action members are plain functions.

| Property                      | Type                                                                  | Description                                                                                                                                       |
| ----------------------------- | --------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------- |
| `open`                        | `ComputedRef<boolean>`                                                | Whether the listbox is open.                                                                                                                      |
| `value`                       | `ComputedRef<string | null>`                                          | The selected option's `value`, or `null`.                                                                                                         |
| `inputValue`                  | `ComputedRef<string>`                                                 | The current input text.                                                                                                                           |
| `highlightedValue`            | `ComputedRef<string | null>`                                          | The active (keyboard-highlighted) option's `value`, or `null`.                                                                                    |
| `items`                       | `ComputedRef<ComboboxItem[]>`                                         | The visible (filtered) options — render these, and pass their index into `getOptionProps`.                                                        |
| `rootProps`                   | `ComputedRef<object>`                                                 | The wrapper element (`data-state`).                                                                                                               |
| `labelProps`                  | `ComputedRef<object>`                                                 | The `<label>` wiring (`id` / `for` → the input).                                                                                                  |
| `controlProps`                | `ComputedRef<object>`                                                 | The control wrapper around input + triggers (`data-state` / `data-disabled`).                                                                     |
| `inputProps`                  | `ComputedRef<object>`                                                 | The `role="combobox"` input: `aria-autocomplete` / `aria-expanded` / `aria-controls` / `aria-activedescendant` plus the input & keydown handlers. |
| `triggerProps`                | `ComputedRef<object>`                                                 | The open/close toggle button (`tabindex="-1"`, `aria-expanded` / `aria-controls`).                                                                |
| `clearTriggerProps`           | `ComputedRef<object>`                                                 | The clear button (`tabindex="-1"`).                                                                                                               |
| `listboxProps`                | `ComputedRef<object>`                                                 | The `role="listbox"` popup (`aria-labelledby`, `hidden` while closed).                                                                            |
| `getOptionProps(item, index)` | `(item: ComboboxItem, index: number) => object`                       | Per-option prop bag (`role="option"`, `aria-selected`, `data-highlighted`, click / pointermove). `index` must be the position in `items`.         |
| `getOptionState(item)`        | `(item: ComboboxItem) => { highlighted: boolean; selected: boolean }` | The `{ highlighted, selected }` state for the item — for conditional classes.                                                                     |
| `setOpen(open)`               | `(open: boolean) => void`                                             | Open / close the listbox imperatively.                                                                                                            |
| `setInputValue(next)`         | `(next: string) => void`                                              | Set the input text (filters and opens).                                                                                                           |
| `select(item)`                | `(item: ComboboxItem) => void`                                        | Commit a selection — reflects its `label` into the input and closes.                                                                              |
| `clear()`                     | `() => void`                                                          | Clear the selection and the input.                                                                                                                |

## Usage

Bind each part's prop bag with `v-bind`, render `items`, and pass the same `index` you iterate with into
`getOptionProps`:

```vue
<script setup lang="ts">
import { useCombobox } from '@oriui/headless/vue';

const cb = useCombobox(() => ({
    options: [
        { label: 'Apple', value: 'apple' },
        { label: 'Banana', value: 'banana' },
        { label: 'Cherry', value: 'cherry' }
    ]
}));
</script>

<template>
    <div v-bind="cb.rootProps.value">
        <label v-bind="cb.labelProps.value">Fruit</label>

        <div v-bind="cb.controlProps.value">
            <input v-bind="cb.inputProps.value" placeholder="Search a fruit…" @blur="cb.setOpen(false)" />
            <button v-bind="cb.triggerProps.value">▾</button>

            <ul v-bind="cb.listboxProps.value">
                <li
                    v-for="(item, index) in cb.items.value"
                    :key="item.value"
                    v-bind="cb.getOptionProps(item, index)"
                    :data-selected="cb.getOptionState(item).selected"
                >
                    {{ item.label }}
                </li>
            </ul>
        </div>
    </div>
</template>
```

The machine keeps no notion of validation, `v-model`, or blur-to-close — those live in the consumer. The
styled [`OriCombobox`](https://oriui.vercel.app/components/combobox) wraps exactly this pattern and layers the form contract
(label / hint / error / `required`), `v-model` sync, and `@blur="setOpen(false)"` on top.

The **Svelte** binding is the same — the composable returns stores (auto-subscribe with `$`), and the
item prop-getters are a store of a function (`$getOptionProps(item, i)`):

```svelte
<script>
    import { useCombobox } from '@oriui/headless/svelte';

    const { items, rootProps, labelProps, controlProps, inputProps, triggerProps, listboxProps, getOptionProps, getOptionState, setOpen } =
        useCombobox({
            options: [
                { label: 'Apple', value: 'apple' },
                { label: 'Banana', value: 'banana' },
                { label: 'Cherry', value: 'cherry' }
            ]
        });
</script>

<div {...$rootProps}>
    <label {...$labelProps}>Fruit</label>

    <div {...$controlProps}>
        <input {...$inputProps} placeholder="Search a fruit…" on:blur={() => setOpen(false)} />
        <button {...$triggerProps}>▾</button>

        <ul {...$listboxProps}>
            {#each $items as item, i}
                <li {...$getOptionProps(item, i)} data-selected={$getOptionState(item).selected}>
                    {item.label}
                </li>
            {/each}
        </ul>
    </div>
</div>
```

In Svelte the options are a `MaybeReactive` — pass a store instead of a plain object to react to a
changing option list or `disabled`.

## Accessibility

Implements the WAI-ARIA **combobox with listbox popup** pattern; the prop bags carry the wiring.

- `inputProps` set `role="combobox"` with `aria-autocomplete="list"`, `autocomplete="off"`,
  `aria-expanded`, and `aria-controls` pointing at the listbox; the highlighted option is referenced by
  `aria-activedescendant` — focus never leaves the input, so no roving `tabindex` is needed.
- `listboxProps` set `role="listbox"`, `aria-labelledby` (the element you bind `labelProps` to), and
  `hidden` while closed. Options from `getOptionProps` are `role="option"` with `aria-selected`; a
  disabled item carries `aria-disabled` and is skipped by keyboard navigation. Each option also exposes
  `data-highlighted` (active) and `data-state="checked|unchecked"` for styling.
- `triggerProps` / `clearTriggerProps` are `tabindex="-1"` buttons (the input keeps focus) with
  accessible labels ("Open / Close suggestions", "Clear selection"); the trigger also carries
  `aria-expanded` / `aria-controls`.
- Selecting an option reflects its `label` into the input and closes the list. The machine does **not**
  dismiss on blur — wire `setOpen(false)` on the input's `blur` yourself (as the example and the styled
  component do); `Tab` therefore moves focus away but does not itself close the list.
- Option ids are derived from the position in `items`, so always pass the same `index` you iterate
  `items` with into `getOptionProps(item, index)`, or `aria-activedescendant` will point at the wrong row.

| Key            | Action                                                                                          |
| -------------- | ----------------------------------------------------------------------------------------------- |
| `↓` / `↑`      | Open the list (if closed) and move the highlight to the next / previous enabled option (wraps). |
| `Home` / `End` | Highlight the first / last enabled option (when open).                                          |
| `Enter`        | Select the highlighted option (when open).                                                      |
| `Escape`       | Close the list (when open).                                                                     |
| Type           | Filter the options and (re)open the list.                                                       |

## See also

- [@oriui/headless](https://oriui.vercel.app/headless/core) — the framework-agnostic contract and the core state machine.
- [OriCombobox](https://oriui.vercel.app/components/combobox) — the styled component built on this primitive.
- [useDialog](https://oriui.vercel.app/headless/use-dialog) · [useDisclosure](https://oriui.vercel.app/headless/use-disclosure) ·
  [useTheme](https://oriui.vercel.app/headless/use-theme) — the other headless primitives.
- [CSS layer](https://oriui.vercel.app/guides/css) — the standalone `.ori-combobox` classes for the parts.


# useDialog

A headless **modal dialog** primitive built on the native `<dialog>` element — focus trap, scroll lock,
`Escape` to close, focus return, and `aria-modal` semantics all come from the platform via
`showModal()`. It owns the open state and the ARIA wiring as ready-to-bind prop bags; **you own the
markup and styles** (you render the `<dialog>` and drive `showModal()` / `close()` from `open`).

This is the **Vue** binding; the engine-agnostic contract lives in [`@oriui/headless`](https://oriui.vercel.app/headless/core), and the
styled [`OriDialog`](https://oriui.vercel.app/components/dialog) is built on it. Like [`useDisclosure`](https://oriui.vercel.app/headless/use-disclosure),
a dialog now has a **zero-dependency native default** — the browser's `<dialog>` supplies the focus trap,
`::backdrop`, top-layer and focus-return that used to require a heavyweight engine. No adapter is required.

## Import

```ts
import { useDialog } from '@oriui/headless/vue';
```

No adapter needs to be registered — `useDialog` resolves the native engine by default. Swapping a custom
engine is optional; see [Adapter](https://oriui.vercel.app/#adapter).

## Options

Pass an options object (or a getter returning one, to stay reactive):

| Option                   | Type                      | Default | Description                               |
| ------------------------ | ------------------------- | ------- | ----------------------------------------- |
| `defaultOpen`            | `boolean`                 | `false` | Initial open state (uncontrolled).        |
| `modal`                  | `boolean`                 | `true`  | `showModal()` (trap + inert) vs `show()`. |
| `closeOnEscape`          | `boolean`                 | `true`  | `Escape` closes the dialog.               |
| `closeOnInteractOutside` | `boolean`                 | `true`  | Click on the `::backdrop` closes it.      |
| `onOpenChange`           | `(open: boolean) => void` | —       | Fires whenever the open state changes.    |
| `id`                     | `string`                  | auto    | Base id for the part ARIA wiring.         |

## Returns

A `DialogControl` — the open state plus the prop bags you bind to each part. Every `*Props` value is a
`ComputedRef`; bind it with `v-bind`.

| Property            | Type                      | Description                                                                                                                             |
| ------------------- | ------------------------- | --------------------------------------------------------------------------------------------------------------------------------------- |
| `open`              | `ComputedRef<boolean>`    | Current open state.                                                                                                                     |
| `setOpen(open)`     | `(open: boolean) => void` | Open / close imperatively.                                                                                                              |
| `toggle()`          | `() => void`              | Flip the open state.                                                                                                                    |
| `triggerProps`      | `ComputedRef<object>`     | The control that opens the dialog.                                                                                                      |
| `dialogProps`       | `ComputedRef<object>`     | The `<dialog>` element: `role`, `aria-modal`, labelling, and the `close` / `cancel` / backdrop-click handlers that keep `open` in sync. |
| `titleProps`        | `ComputedRef<object>`     | Wires the accessible name (`aria-labelledby`).                                                                                          |
| `descriptionProps`  | `ComputedRef<object>`     | Wires the accessible description (`aria-describedby`).                                                                                  |
| `closeTriggerProps` | `ComputedRef<object>`     | The close control.                                                                                                                      |

## Usage

Render a real `<dialog>`, bind `dialogProps`, and drive `showModal()` / `close()` from `open`:

```vue
<script setup lang="ts">
import { useTemplateRef, watchPostEffect } from 'vue';
import { useDialog } from '@oriui/headless/vue';

const dlg = useDialog(() => ({ modal: true }));

const dialogEl = useTemplateRef<HTMLDialogElement>('dialog');
watchPostEffect(() => {
    const el = dialogEl.value;
    if (!el) return;
    if (dlg.open.value && !el.open) el.showModal();
    else if (!dlg.open.value && el.open) el.close();
});
</script>

<template>
    <button v-bind="dlg.triggerProps.value">Open</button>

    <dialog ref="dialog" v-bind="dlg.dialogProps.value">
        <h2 v-bind="dlg.titleProps.value">Title</h2>
        <p v-bind="dlg.descriptionProps.value">Body copy.</p>
        <button v-bind="dlg.closeTriggerProps.value">Close</button>
    </dialog>
</template>
```

No `<Teleport>` and no mounted-ref gating are needed: a modal `<dialog>` renders in the browser's top
layer regardless of where it sits in the DOM, and a closed `<dialog>` is hidden, so the SSR markup stays
stable. The styled [`OriDialog`](https://oriui.vercel.app/components/dialog) wraps exactly this pattern.

The **Svelte** binding is the same — drive `showModal()` / `close()` from `$open` in an `$effect`:

```svelte
<script>
    import { useDialog } from '@oriui/headless/svelte';

    let dialogEl;
    const { open, triggerProps, dialogProps, titleProps, descriptionProps, closeTriggerProps } = useDialog({
        modal: true
    });

    $effect(() => {
        if (!dialogEl) return;
        if ($open && !dialogEl.open) dialogEl.showModal();
        else if (!$open && dialogEl.open) dialogEl.close();
    });
</script>

<button {...$triggerProps}>Open</button>

<dialog bind:this={dialogEl} {...$dialogProps}>
    <h2 {...$titleProps}>Title</h2>
    <p {...$descriptionProps}>Body copy.</p>
    <button {...$closeTriggerProps}>Close</button>
</dialog>
```

## Adapter

`useDialog` defaults to the native `<dialog>` engine — the focus trap, scroll lock, `Esc`, `::backdrop`
and focus-return are the platform's job now, so no dependency is required. The `OriHeadless` contract is
still there as a **hedge**: register a custom engine per primitive only if a project needs one (for
example a Zag-backed adapter for a genuinely hard widget), without touching your markup.

```ts
// main.ts
import { createApp } from 'vue';
import { OriHeadless } from '@oriui/headless/vue';
import { myDialog } from './headless/my-dialog'; // optional custom adapter

const app = createApp(App);
app.use(OriHeadless, { dialog: myDialog });
app.mount('#app');
```

`useDialog` resolves that adapter (or one from `provideHeadless` inside a subtree), falling back to the
native engine when none is wired. Any adapter produces the same `DialogControl` shape, so your markup
never changes.

## Accessibility

The native `<dialog>` carries the WAI-ARIA dialog contract; the prop bags complete the wiring.

- `dialogProps` set `role="dialog"`, `aria-modal` (per the `modal` option), `aria-labelledby` pointing at
  the element you bind `titleProps` to, and the `close` / `cancel` handlers that keep `open` in sync when
  the browser closes the dialog (Esc, backdrop click).
- `triggerProps` carry the `aria-*` attributes the open control needs.
- `closeTriggerProps` carry the close control's wiring; give it an accessible name (e.g.
  `aria-label="Close"`).
- The live behaviour — focus trap, scroll lock, returning focus to the trigger on close — comes from
  `showModal()`. A non-modal `show()` (`modal: false`) does not trap focus or block the page.

| Key         | Action                                                                     |
| ----------- | -------------------------------------------------------------------------- |
| `Escape`    | Closes the dialog and returns focus to the trigger (when `closeOnEscape`). |
| `Tab`       | Cycles focus among interactive elements inside the dialog (focus trap).    |
| `Shift+Tab` | Cycles focus backwards inside the dialog.                                  |

## See also

- [@oriui/headless](https://oriui.vercel.app/headless/core) — the framework-agnostic contract and the native engine.
- [useDisclosure](https://oriui.vercel.app/headless/use-disclosure) — the sibling show / hide primitive (also native by default).
- [OriDialog](https://oriui.vercel.app/components/dialog) — the styled component built on this primitive.
- [CSS layer](https://oriui.vercel.app/guides/css) — the standalone `.ori-*` classes for the dialog parts.


# useDisclosure

A headless **show / hide** primitive for disclosure widgets — expandable panels, accordions, menus,
the collapsible sidebar groups on this very site. It owns the open state, the WAI-ARIA wiring, and the
toggle handler; **you own the markup and the styles**.

This is the **Vue** binding of the headless layer; the framework-agnostic contract lives in
[@oriui/headless](https://oriui.vercel.app/headless/core). Behaviour is swappable per primitive through the `OriHeadless` adapter,
and a zero-dependency native engine ships as the default — so it works with no setup.

## Import

```ts
import { useDisclosure } from '@oriui/headless/vue';
```

## Options

Pass an options object — or a getter returning one, to keep it reactive:

| Option        | Type      | Default | Description                                    |
| ------------- | --------- | ------- | ---------------------------------------------- |
| `defaultOpen` | `boolean` | `false` | Initial open state (uncontrolled).             |
| `disabled`    | `boolean` | `false` | Ignore toggles while true.                     |
| `id`          | `string`  | auto    | Base id for the trigger / content ARIA wiring. |

## Returns

`useDisclosure` returns a `DisclosureControl` — reactive state, ARIA-correct prop bags to spread onto
your markup, and imperative handlers.

| Property        | Type                      | Description                                                                       |
| --------------- | ------------------------- | --------------------------------------------------------------------------------- |
| `open`          | `ComputedRef<boolean>`    | Current open state.                                                               |
| `rootProps`     | `ComputedRef<object>`     | Bind to the root wrapper (`data-state`).                                          |
| `triggerProps`  | `ComputedRef<object>`     | Bind to the toggle control (`aria-expanded`, `aria-controls`, click, `disabled`). |
| `contentProps`  | `ComputedRef<object>`     | Bind to the collapsible content (`id`, `role`, `aria-labelledby`, `hidden`).      |
| `setOpen(open)` | `(open: boolean) => void` | Imperatively set the state.                                                       |
| `toggle()`      | `() => void`              | Flip the state.                                                                   |

## Usage

Spread the prop bags onto your own elements — the primitive supplies the behaviour, you supply the
look:

```vue
<script setup lang="ts">
import { useDisclosure } from '@oriui/headless/vue';

const { open, triggerProps, contentProps } = useDisclosure(() => ({ defaultOpen: false }));
</script>

<template>
    <button v-bind="triggerProps">Details {{ open ? '▲' : '▼' }}</button>
    <div v-bind="contentProps">…content…</div>
</template>
```

The **Svelte** binding is the same primitive as stores — auto-subscribe with `$` and spread the bags:

```svelte
<script>
    import { useDisclosure } from '@oriui/headless/svelte';

    const { open, triggerProps, contentProps } = useDisclosure({ defaultOpen: false });
</script>

<button {...$triggerProps}>Details {$open ? '▲' : '▼'}</button>
<div {...$contentProps}>…content…</div>
```

## Adapter

The behaviour resolves through the `OriHeadless` contract. With nothing wired, `useDisclosure` falls
back to the **native** `@oriui/headless` engine — zero dependencies, no setup. To swap in a different
engine (Zag, or your own), provide a `disclosure` adapter once at the app root:

```ts
import { OriHeadless } from '@oriui/headless/vue';
import { myDisclosureAdapter } from './headless/my-disclosure';

app.use(OriHeadless, { disclosure: myDisclosureAdapter });
```

The adapter must satisfy the `DisclosureAdapter` contract — same `DisclosureControl` shape — so your
markup never changes when you swap engines. To scope an adapter to one subtree instead of the whole
app, call `provideHeadless({ disclosure: … })` inside that subtree's `setup`.

## Accessibility

The prop bags carry the full WAI-ARIA Disclosure pattern, so the wiring is correct as long as you bind
them:

- **`triggerProps`** renders a real `<button type="button">` with `aria-expanded` reflecting the open
  state and `aria-controls` pointing at the content. When `disabled`, it sets the real `disabled`
  attribute (plus `data-disabled` for styling).
- **`contentProps`** sets `role="region"`, `aria-labelledby` back to the trigger (so the region takes
  its accessible name from the toggle), and a real `hidden` attribute while collapsed — the content is
  removed from the accessibility tree and tab order when closed.
- Clicking the trigger toggles the state; activation is the native button behaviour, so `Enter` and
  `Space` both work with no extra handlers.
- `rootProps`, `triggerProps`, and `contentProps` each expose a `data-state` of `open` / `closed` as a
  styling hook for transitions.

| Key     | Action                                  |
| ------- | --------------------------------------- |
| `Enter` | Toggles the disclosure (native button). |
| `Space` | Toggles the disclosure (native button). |

## See also

- [@oriui/headless](https://oriui.vercel.app/headless/core) — the framework-agnostic contract and the native engine behind this binding.
- [useDialog](https://oriui.vercel.app/headless/use-dialog) — the modal counterpart; the hard-behaviour case delegated to an adapter.
- [CSS layer](https://oriui.vercel.app/guides/css) — standalone `.ori-*` classes for styling the markup you bind these props to.


# useDismissable

A headless **dismiss layer** — the "close the overlay on an outside interaction" glue a non-platform
overlay needs, the pattern Radix `DismissableLayer` / Floating-UI `useDismiss` standardise. While
`enabled`, it attaches `document` listeners and calls `onDismiss()` when an interaction lands **outside**
the overlay's own elements. Each overlay picks the strategy that fits it:

- a **menu** (no single focus anchor) closes on **pointerdown outside** (`pointerDownOutside`);
- a **combobox** (focus lives on its input) closes on **focus-out** (`focusOutside`).

`OriMenu` and `OriCombobox` use this internally. (An `OriPopover` / `OriDialog` get dismiss for free from
the native `[popover]` / `<dialog>` top-layer, and Escape lives in the core connects — so they don't need
it.) The pure `isTargetOutside(target, elements)` predicate it's built on is exported from
[`@oriui/headless`](https://oriui.vercel.app/headless/core).

## Import

```ts
import { useDismissable } from '@oriui/headless/vue';
```

## Options

`useDismissable(() => ({ … }))` takes its options as a getter (Svelte: a plain object or a store) so
`enabled` / `elements` stay reactive.

| Option               | Type                                       | Default | Description                                                                                         |
| -------------------- | ------------------------------------------ | ------- | --------------------------------------------------------------------------------------------------- |
| `enabled`            | `boolean`                                  | —       | Attach the listeners only while this is true — typically the overlay's `open`.                      |
| `elements`           | `() => (HTMLElement | null | undefined)[]` | —       | The overlay's own elements (content + trigger). An interaction inside ANY of them does NOT dismiss. |
| `onDismiss`          | `() => void`                               | —       | Called to dismiss — typically `() => setOpen(false)`.                                               |
| `pointerDownOutside` | `boolean`                                  | `false` | Close on a `pointerdown` outside `elements`.                                                        |
| `focusOutside`       | `boolean`                                  | `false` | Close when focus lands outside `elements`.                                                          |

It returns nothing — it just manages the listeners (removed when `enabled` flips false or the scope
disposes). Attach happens after the render flush, so the interaction that opened the overlay can't
immediately dismiss it.

## Usage

Pass the overlay's `open`, its element refs, and a close callback — pick the strategy for your widget:

```vue
<!-- MyMenu.vue — pointerdown-outside (a menu has no single focus anchor) -->
<script setup lang="ts">
import { ref } from 'vue';
import { useDismissable } from '@oriui/headless/vue';

const open = ref(false);
const content = ref<HTMLElement>();
const trigger = ref<HTMLElement>();

useDismissable(() => ({
    enabled: open.value,
    elements: () => [content.value, trigger.value],
    onDismiss: () => (open.value = false),
    pointerDownOutside: true
}));
</script>
```

The **Svelte** binding is the same — options are a plain object or a store, and it wires the identical
listeners over the shared `isTargetOutside`:

```svelte
<script>
    import { writable, derived } from 'svelte/store';
    import { useDismissable } from '@oriui/headless/svelte';

    export let controlEl; // bound to the combobox control
    const open = writable(false);

    // focus-out for a combobox (focus lives on its input)
    useDismissable(derived(open, ($open) => ({
        enabled: $open,
        elements: () => [controlEl],
        onDismiss: () => open.set(false),
        focusOutside: true
    })));
</script>
```

## Accessibility

- Dismiss is one half of an overlay's a11y contract; the other keys live elsewhere — **Escape** is handled
  by the [Menu](https://oriui.vercel.app/headless/use-menu) / [Combobox](https://oriui.vercel.app/headless/use-combobox) core connects, and roving focus by
  their own machines. `useDismissable` only adds the outside-interaction close.
- `pointerDownOutside` fires on `pointerdown` (before `click`), so the overlay closes as the outside press
  begins — matching native menus. `focusOutside` closes when focus genuinely leaves the widget (Tab-away or
  a click that moves focus out), so a screen-reader user Tabbing past a combobox closes its list.

## See also

- [@oriui/headless](https://oriui.vercel.app/headless/core) — the `isTargetOutside` predicate the composables share.
- [useMenu](https://oriui.vercel.app/headless/use-menu) · [useCombobox](https://oriui.vercel.app/headless/use-combobox) — the overlays that consume it.
- [Popover](https://oriui.vercel.app/components/popover) · [Dialog](https://oriui.vercel.app/components/dialog) — the platform overlays that dismiss without it.


# useMenu

A headless **menu button** primitive built on the WAI-ARIA menu-button pattern — a trigger that opens a
popup menu of actions, with **roving tabindex**, arrow / `Home` / `End` navigation, and `Enter` / `Space`
activation. It owns the open state and the highlighted item and exposes the ARIA wiring as ready-to-bind
prop bags; **you own the markup, the styles, and the DOM focus** (roving needs real focus, and
click-outside / focus-return are host concerns a state projection can't reach).

This is the **Vue** binding; the framework-agnostic core lives in [`@oriui/headless`](https://oriui.vercel.app/headless/core), and
the styled [`OriMenu`](https://oriui.vercel.app/components/menu) is built on it. Like [`useDialog`](https://oriui.vercel.app/headless/use-dialog) /
[`useDisclosure`](https://oriui.vercel.app/headless/use-disclosure), `useMenu` resolves through the swappable
[`OriHeadless`](https://oriui.vercel.app/headless/core) contract — its default is a thin projection of the core menu **state
machine** (no adapter to register unless you want to swap one), and the composable hands you `open` /
`highlightedValue` to watch so the UI can move real DOM focus itself.

## Import

```ts
import { useMenu, type MenuItem } from '@oriui/headless/vue';
```

## Options

Pass an options object (or a getter returning one, to stay reactive):

| Option     | Type                      | Default        | Description                                                                      |
| ---------- | ------------------------- | -------------- | -------------------------------------------------------------------------------- |
| `items`    | `MenuItem[]`              | **required**   | The menu items, in render order. Reactive — navigation re-syncs when it changes. |
| `id`       | `string`                  | auto (`useId`) | Stable base id for the trigger / content / item ARIA wiring. Pass one for SSR.   |
| `disabled` | `boolean`                 | `false`        | Disables the trigger and blocks opening the menu.                                |
| `onSelect` | `(value: string) => void` | —              | Fired when an item is activated (click / `Enter` / `Space`); the menu closes.    |

Each `MenuItem` is a plain object — `value` is the stable identity and the `onSelect` payload:

```ts
interface MenuItem {
    value: string; // stable identity + the value passed to onSelect
    label?: string; // display text; falls back to value
    disabled?: boolean; // skipped by roving navigation and selection
}
```

## Returns

The open / highlight state plus the prop bags you bind to each part. Every `*Props` value is a
`ComputedRef`, and `getItemProps` returns a bag — bind each with `v-bind`.

| Property                    | Type                                           | Description                                                                                                                                            |
| --------------------------- | ---------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `open`                      | `ComputedRef<boolean>`                         | Whether the menu is open.                                                                                                                              |
| `highlightedValue`          | `ComputedRef<string | null>`                   | The roving-highlighted item's `value`, or `null`. Watch it to move real DOM focus to the active item.                                                  |
| `items`                     | `ComputedRef<MenuItem[]>`                      | The current item list (echoes the `items` option) — convenient to `v-for` over.                                                                        |
| `triggerProps`              | `ComputedRef<object>`                          | The menu button: `type`, `aria-haspopup="menu"`, `aria-controls`, live `aria-expanded`, `data-state`, and the click / keydown handlers.                |
| `contentProps`              | `ComputedRef<object>`                          | The `role="menu"` panel: `aria-labelledby`, `aria-orientation="vertical"`, `tabindex="-1"`, `hidden` while closed, and the navigation keydown handler. |
| `separatorProps`            | `ComputedRef<object>`                          | A `role="separator"` divider (`aria-orientation="horizontal"`) for grouping items.                                                                     |
| `getItemProps(item, index)` | `(item: MenuItem, index: number) => object`    | Per-item bag: `role="menuitem"`, roving `tabindex`, `data-highlighted`, `aria-disabled`, and the click / pointermove handlers.                         |
| `getItemState(item)`        | `(item: MenuItem) => { highlighted: boolean }` | The item's derived state — currently just whether it is highlighted — for your own styling.                                                            |
| `setOpen(open)`             | `(open: boolean) => void`                      | Open / close imperatively (the host uses this to close on outside click).                                                                              |
| `highlight(value)`          | `(value: string | null) => void`               | Set the highlighted item by `value`; `null` clears the highlight.                                                                                      |
| `highlightFirst()`          | `() => void`                                   | Highlight the first enabled item.                                                                                                                      |
| `highlightLast()`           | `() => void`                                   | Highlight the last enabled item.                                                                                                                       |

Every prop bag also carries `data-scope="menu"` and a `data-part` (`trigger` / `content` / `item` /
`separator`) styling hook.

## Usage

The composable projects state to prop bags; the **host** moves real DOM focus to the highlighted item
(roving requires it), returns focus to the trigger on close, and wires the outside-click dismissal —
things a framework-agnostic projection can't do itself:

```vue
<script setup lang="ts">
import { nextTick, onBeforeUnmount, useTemplateRef, watch } from 'vue';
import { useMenu, type MenuItem } from '@oriui/headless/vue';

const items: MenuItem[] = [
    { value: 'new', label: 'New file' },
    { value: 'open', label: 'Open…' },
    { value: 'delete', label: 'Delete', disabled: true }
];

const m = useMenu(() => ({ items, onSelect: (value) => console.log(value) }));

const contentRef = useTemplateRef<HTMLElement>('content');
const triggerEl = (): HTMLElement | null => {
    const id = m.triggerProps.value.id as string | undefined;
    return id ? document.getElementById(id) : null;
};

// Roving tabindex: move real DOM focus to the highlighted item whenever it changes while open.
watch(
    () => m.highlightedValue.value,
    async () => {
        if (!m.open.value) return;
        await nextTick();
        contentRef.value?.querySelector<HTMLElement>('[data-highlighted]')?.focus();
    }
);

// On open, focus the menu and wire outside-click; on close, return focus to the trigger.
const onOutside = (event: PointerEvent): void => {
    const target = event.target as Node;
    if (contentRef.value?.contains(target) || triggerEl()?.contains(target)) return;
    m.setOpen(false);
};
watch(
    () => m.open.value,
    async (open) => {
        if (open) {
            await nextTick();
            if (m.highlightedValue.value === null) contentRef.value?.focus();
            document.addEventListener('pointerdown', onOutside);
        } else {
            document.removeEventListener('pointerdown', onOutside);
            triggerEl()?.focus();
        }
    }
);
onBeforeUnmount(() => document.removeEventListener('pointerdown', onOutside));
</script>

<template>
    <button v-bind="m.triggerProps.value">Actions</button>

    <div v-bind="m.contentProps.value" ref="content" class="ori-menu">
        <div
            v-for="(item, index) in items"
            :key="item.value"
            v-bind="m.getItemProps(item, index)"
            class="ori-menu__item"
        >
            {{ item.label ?? item.value }}
        </div>
    </div>
</template>
```

The styled [`OriMenu`](https://oriui.vercel.app/components/menu) wraps exactly this pattern — the roving-focus watch, the
open / close focus-return, and the outside-click listener — behind a `#trigger` slot and CSS Anchor
Positioning.

The **Svelte** binding is the same — auto-subscribe the stores with `$`, and move DOM focus in an
`$effect` (`getItemProps` is a store of a function, so call `$getItemProps(item, i)`):

```svelte
<script>
    import { useMenu } from '@oriui/headless/svelte';

    let contentEl;
    const { open, highlightedValue, items, triggerProps, contentProps, getItemProps } = useMenu({
        id: 'actions',
        items: [
            { value: 'new', label: 'New file' },
            { value: 'open', label: 'Open…' },
            { value: 'delete', label: 'Delete', disabled: true }
        ],
        onSelect: (value) => console.log(value)
    });

    // Roving tabindex: a projection can't touch the DOM, so move real focus to the highlighted item.
    $effect(() => {
        if ($open && $highlightedValue != null) contentEl?.querySelector('[data-highlighted]')?.focus();
    });
</script>

<button {...$triggerProps}>Actions</button>

<div {...$contentProps} bind:this={contentEl} class="ori-menu">
    {#each $items as item, i}
        <div {...$getItemProps(item, i)} class="ori-menu__item">{item.label ?? item.value}</div>
    {/each}
</div>
```

## Accessibility

The prop bags carry the full WAI-ARIA menu-button contract; the host completes it by moving real focus.

- **The trigger MUST be a real `<button>`** (or a component rendering one) with an accessible name.
  `triggerProps` set `type="button"`, `aria-haspopup="menu"`, `aria-controls` (the panel id), and a
  live `aria-expanded` that tracks `open` — the machine owns `open`, so this stays in sync.
- `contentProps` set `role="menu"`, `aria-labelledby` the trigger, `aria-orientation="vertical"`,
  `tabindex="-1"`, and `hidden` while closed. Items get `role="menuitem"` from `getItemProps`.
- **Roving tabindex**: exactly one item (the highlighted one) is `tabindex="0"` and carries
  `data-highlighted`; the rest are `tabindex="-1"`. There is no `aria-activedescendant` — the host moves
  real DOM focus to the highlighted item as you navigate, driven by watching `highlightedValue`.
- A disabled item (`disabled: true`) is `aria-disabled="true"` and is skipped by Arrow / `Home` / `End`
  navigation and by selection.
- Selecting an item (click, or `Enter` / `Space` on the highlighted one) fires `onSelect` with its
  `value` and closes the menu; the host returns focus to the trigger. `Escape`, `Tab`, and an outside
  click also close it — the machine sends `CLOSE` on `Escape` / `Tab`, and the host calls `setOpen(false)`
  on the outside click.

| Key                            | Action                                                           |
| ------------------------------ | ---------------------------------------------------------------- |
| `Enter` / `Space` (on trigger) | Opens the menu and highlights the first enabled item.            |
| `↓` (on trigger)               | Opens the menu and highlights the first enabled item.            |
| `↑` (on trigger)               | Opens the menu and highlights the last enabled item.             |
| `↓` / `↑` (in menu)            | Moves the highlight to the next / previous enabled item (wraps). |
| `Home` / `End` (in menu)       | Highlights the first / last enabled item.                        |
| `Enter` / `Space` (on item)    | Activates the highlighted item — fires `onSelect`, then closes.  |
| `Escape`                       | Closes the menu (the host returns focus to the trigger).         |
| `Tab`                          | Closes the menu and moves focus onward (does not trap focus).    |

## See also

- [@oriui/headless](https://oriui.vercel.app/headless/core) — the framework-agnostic core: the menu state machine + the `connect`
  projection behind this binding.
- [OriMenu](https://oriui.vercel.app/components/menu) — the styled component built on this composable.
- [useDialog](https://oriui.vercel.app/headless/use-dialog) · [useDisclosure](https://oriui.vercel.app/headless/use-disclosure) — the sibling headless
  overlay / show-hide primitives.
- [CSS layer](https://oriui.vercel.app/guides/css) — the standalone `.ori-menu` / `.ori-menu__item` classes for the menu parts.


# useTabs

A headless **WAI-ARIA tabs** widget with **automatic activation** — a `tablist` of tabs behind a single
Tab stop, navigated with the arrow keys via **roving tabindex** (real DOM focus, not
`aria-activedescendant`), where moving focus also selects. It is **data-driven**: you pass the `tabs`
array plus the selected value, and it returns the `tablist` prop bag plus per-tab and per-panel
prop-getters (ids, `aria-selected`, `aria-controls`, `aria-labelledby`, roving `tabindex`, `hidden`).

This is the **Vue** binding; the framework-agnostic core (the pure roving index/key math) lives in
[`@oriui/headless`](https://oriui.vercel.app/headless/core), and the styled [`OriTabs`](https://oriui.vercel.app/components/tabs) is built on it. Like
[`useColorPicker`](https://oriui.vercel.app/headless/use-color-picker) and unlike the compositional
[`useToolbar`](https://oriui.vercel.app/headless/use-toolbar) (arbitrary slotted items behind a `provide` / `inject` context),
Tabs is driven by a data array — there is no context and no state machine, just the shared roving
helpers plus a defensive selection resolver.

## Import

```ts
import { useTabs } from '@oriui/headless/vue';
```

## Options

`useTabs(() => ({ … }))` takes its options as a **getter** — like
[`useColorPicker`](https://oriui.vercel.app/headless/use-color-picker) / [`useCombobox`](https://oriui.vercel.app/headless/use-combobox) — so `tabs` /
`value` / `orientation` stay reactive.

| Option        | Type                               | Default        | Description                                                                                           |
| ------------- | ---------------------------------- | -------------- | ----------------------------------------------------------------------------------------------------- |
| `tabs`        | `TabItem[]`                        | —              | The set of tabs, in order. `TabItem` is `{ value: string | number; disabled?: boolean }` (behaviour). |
| `value`       | `string | number | undefined`      | —              | The controlled selection (bind to `v-model`). Resolves to the first enabled tab when unset.           |
| `orientation` | `'horizontal' | 'vertical'`        | `'horizontal'` | Arrow-key axis: `horizontal` navigates Left/Right, `vertical` Up/Down.                                |
| `label`       | `string`                           | —              | Accessible name for the tablist → `aria-label` (WAI-ARIA recommends naming a tablist).                |
| `labelledby`  | `string`                           | —              | Accessible name by element id → `aria-labelledby` (use instead of `label`).                           |
| `idBase`      | `string`                           | `useId()`      | SSR-stable base for the derived `${base}-tab-${i}` / `-panel-${i}` ids.                               |
| `onChange`    | `(value: string | number) => void` | —              | Commit the next selected value (wire to your `v-model`).                                              |

## Returns

| Property        | Type                                       | Description                                                                                                                                                                                      |
| --------------- | ------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `selectedValue` | `ComputedRef<string | number | undefined>` | The effective selection: `value` when it points at a real, enabled tab; otherwise the first enabled tab (recovers from an unset / missing / disabled value).                                     |
| `select`        | `(tab: TabItem) => void`                   | Commit a tab (no-op when `tab.disabled`); calls `onChange`.                                                                                                                                      |
| `tablistProps`  | `ComputedRef<object>`                      | The `tablist` element's bag: `role="tablist"`, `aria-orientation`, and the roving `onKeydown`. Bind with `v-bind`; no element ref — the handler resolves the tablist from `event.currentTarget`. |
| `getTabProps`   | `(tab, index) => object`                   | Per-tab `<button>` bag: `id`, `role="tab"`, `aria-selected`, `aria-controls`, the roving `tabindex` (`0` for the selected tab, `-1` otherwise), `disabled`, and an `onClick` that selects it.    |
| `getPanelProps` | `(tab, index) => object`                   | Per-panel bag: `id`, `role="tabpanel"`, `aria-labelledby` (its tab), `hidden` when not selected, and `tabindex="0"`.                                                                             |

## Usage

Spread `tablistProps` on the list, then `v-for` the `tabs` — a `<button>` per tab with
`getTabProps(tab, i)`, and a panel per tab with `getPanelProps(tab, i)`. This is exactly what the styled
[`OriTabs`](https://oriui.vercel.app/components/tabs) wraps.

```vue
<!-- MyTabs.vue -->
<script setup lang="ts">
import { useTabs } from '@oriui/headless/vue';

const { tabs } = defineProps<{
    tabs: { value: string; label: string; disabled?: boolean }[];
}>();
const model = defineModel<string>();

const { tablistProps, getTabProps, getPanelProps } = useTabs(() => ({
    tabs,
    value: model.value,
    onChange: (value) => {
        model.value = value as string;
    }
}));
</script>

<template>
    <div>
        <!-- No element ref: the keydown handler resolves the tablist from event.currentTarget. -->
        <div v-bind="tablistProps">
            <button v-for="(tab, i) in tabs" :key="tab.value" v-bind="getTabProps(tab, i)">{{ tab.label }}</button>
        </div>

        <div v-for="(tab, i) in tabs" :key="tab.value" v-bind="getPanelProps(tab, i)">
            <slot :name="tab.value" />
        </div>
    </div>
</template>
```

The **Svelte** binding is the same — the prop bags are `Readable` stores you auto-subscribe with `$`, the
item / panel getters are **stores of functions** (`$getTabProps(tab, i)`), event handlers are lowercased
(`onkeydown` / `onclick`), and options are a plain object (or a store), not a getter:

```svelte
<!-- MyTabs.svelte -->
<script>
    import { useTabs } from '@oriui/headless/svelte';

    export let tabs;
    let value;
    $: t = useTabs({ tabs, value, onChange: (v) => (value = v) });
    $: ({ tablistProps, getTabProps, getPanelProps } = t);
</script>

<div {...$tablistProps}>
    {#each tabs as tab, i (tab.value)}
        <button {...$getTabProps(tab, i)}>{tab.label}</button>
    {/each}
</div>

{#each tabs as tab, i (tab.value)}
    <div {...$getPanelProps(tab, i)}><slot name={tab.value} /></div>
{/each}
```

## Accessibility

The prop bags carry the WAI-ARIA [Tabs](https://www.w3.org/WAI/ARIA/apg/patterns/tabs/){rel="&#x22;nofollow&#x22;"} pattern with
**automatic activation** (arrows move focus and select in one step); the keyboard behaviour is the
roving `onKeydown` on the tablist.

- `tablistProps` set `role="tablist"` + `aria-orientation`, plus `aria-label` / `aria-labelledby` from the
  `label` / `labelledby` options — name the tablist (WAI-ARIA recommends it), especially with more than one
  on a page. Each `getTabProps` bag is a
  `role="tab"` with `aria-selected`, `aria-controls` → its panel id, and the roving `tabindex`; each
  `getPanelProps` bag is a `role="tabpanel"` with `aria-labelledby` → its tab id, `hidden` when
  inactive, and `tabindex="0"` (the panel is focusable so keyboard users can reach its content).
- **Roving tabindex.** Exactly one tab is `tabindex="0"` — the selected one; every other tab is
  `tabindex="-1"`. Real DOM focus moves as you navigate; there is no `aria-activedescendant`.
- **DOM-order navigation.** The keydown handler resolves tabs by `querySelectorAll('[role="tab"]')` in
  document order, so navigation stays correct even when tabs are conditionally rendered or reordered.
- **Disabled tabs are skipped.** A `disabled` tab uses the native `disabled` attribute; arrow navigation
  steps **over** it (the core `resolveRovingIndex` skip predicate — "the Tabs model") and `selectedValue`
  recovers to the first enabled tab if a disabled/missing value is bound.

| Key                        | Action                                                                                            |
| -------------------------- | ------------------------------------------------------------------------------------------------- |
| `Tab` / `Shift+Tab`        | Move focus onto the selected tab, or past the tablist to the panel — the tablist is one tab stop. |
| `ArrowRight` / `ArrowLeft` | Horizontal: select + focus the next / previous enabled tab (wraps first⇄last, skipping disabled). |
| `ArrowDown` / `ArrowUp`    | Vertical (`orientation="vertical"`): select + focus the next / previous enabled tab.              |
| `Home` / `End`             | Select + focus the first / last enabled tab.                                                      |

## See also

- [@oriui/headless](https://oriui.vercel.app/headless/core) — the framework-agnostic core: the pure roving index/key math
  (`rovingIntent` / `resolveRovingIndex`, with the skip-disabled predicate), shared with the Svelte twin.
- [Tabs](https://oriui.vercel.app/components/tabs) — the styled `OriTabs` built on this composable.
- [useToolbar](https://oriui.vercel.app/headless/use-toolbar) — the sibling roving primitive (compositional, slotted items).
- [CSS layer](https://oriui.vercel.app/guides/css) — the standalone `.ori-tabs` classes for the tabs parts.


# useTheme

A headless **light / dark theme controller** — it owns the mode setting, resolves `auto` against the OS
scheme live, persists the choice, and applies it to the DOM. It applies through `applyTheme`, which sets
the `ori-theme_{light,dark}` class (removing the opposite — exactly one is on at a time) **and** works
around a bug in current Chromium where a runtime theme toggle otherwise leaves styled components
painting the previous theme's colours until they re-render.

This is the **Vue** binding; the framework-agnostic core (`createThemeController`, `applyTheme`) lives
in [`@oriui/headless`](https://oriui.vercel.app/headless/core), and a Svelte store twin ships at `@oriui/headless/svelte`.
Theming is DOM + state, so — unlike [`useDisclosure`](https://oriui.vercel.app/headless/use-disclosure) /
[`useDialog`](https://oriui.vercel.app/headless/use-dialog) — there is no swappable adapter.

For the conceptual guide — skins, subtree scoping, and the flash-free initial theme — see
[Theming](https://oriui.vercel.app/guides/theming).

## Import

```ts
import { useTheme } from '@oriui/headless/vue';
```

## Options

All optional; forwarded to `createThemeController`.

| Option        | Type                        | Default           | Description                                                                           |
| ------------- | --------------------------- | ----------------- | ------------------------------------------------------------------------------------- |
| `default`     | `'auto' | 'light' | 'dark'` | `'auto'`          | Setting when nothing is persisted. `auto` follows `prefers-color-scheme` live.        |
| `storageKey`  | `string | null`             | `'ori-theme'`     | `localStorage` key the setting reads from / writes to. `null` disables persistence.   |
| `root`        | `HTMLElement`               | `documentElement` | Element the `ori-theme_*` class is set on (defaults to `<html>`).                     |
| `flushTarget` | `HTMLElement | null`        | `document.body`   | Subtree force-restyled to defeat the invalidation bug above. `null` skips the flush.  |
| `classPrefix` | `string`                    | `'ori-theme_'`    | The applied class is `${classPrefix}${mode}` — override to theme with your own class. |

## Returns

Reactive state plus imperative setters.

| Property            | Type                                           | Description                                                      |
| ------------------- | ---------------------------------------------- | ---------------------------------------------------------------- |
| `theme`             | `Ref<'auto' | 'light' | 'dark'>`               | The current SETTING (reactive).                                  |
| `resolvedTheme`     | `Ref<'light' | 'dark'>`                        | The theme actually on the DOM; tracks the OS scheme when `auto`. |
| `setTheme(setting)` | `(setting: 'auto' | 'light' | 'dark') => void` | Set the setting (`auto` re-follows the OS), apply, and persist.  |
| `toggleTheme()`     | `() => void`                                   | Flip the resolved theme light ⇄ dark (pins an explicit setting). |
| `cycleTheme()`      | `() => void`                                   | Cycle `auto → light → dark → auto`.                              |

## Usage

```vue
<script setup lang="ts">
import { useTheme } from '@oriui/headless/vue';

// setTheme(mode) and toggleTheme() are also returned — see Returns.
const { theme, resolvedTheme, cycleTheme } = useTheme({
    storageKey: 'ori-theme',
    default: 'auto'
});
</script>

<template>
    <button @click="cycleTheme">Theme: {{ theme }} ({{ resolvedTheme }})</button>
</template>
```

The controller applies the persisted / default theme in `setup`, **before mount** — so there's no flash
between mount and the applied theme — and tears its OS-scheme listener down on scope dispose. (A
client-only SPA can still flash on the very first paint before JS runs; the pre-paint script below
closes that gap.)

The **Svelte** twin is the same controller as a readable store (auto-subscribe with `$`) plus the
setters:

```svelte
<script>
    import { useTheme } from '@oriui/headless/svelte';

    const theme = useTheme({ storageKey: 'ori-theme', default: 'auto' });
</script>

<button on:click={theme.cycleTheme}> Theme: {$theme.theme} ({$theme.resolvedTheme}) </button>
```

## Lower-level

`useTheme&#x60; wraps two exports you can use directly. If you already own the mode state — your own store,
or plain JS — call &#x2A;*`applyTheme`** exactly where you'd toggle the class; it carries the fix:

```ts
import { applyTheme } from '@oriui/headless';

// sets ori-theme_{dark,light} on <html> AND re-resolves the components
applyTheme(isDark ? 'dark' : 'light');
```

`createThemeController(options)` is the vanilla engine behind `useTheme` (same options →
`{ get, resolved, set, toggle, cycle, subscribe, destroy }`), and `flushThemeInvalidation(el)` is the
bare workaround — call it after any runtime change of an inherited colour token you apply yourself (e.g.
switching `data-ori-skin`). See [`@oriui/headless`](https://oriui.vercel.app/headless/core).

## SSR & the initial theme

`useTheme` is inert on the server (no `document`) and applies on the client in `setup`. To avoid a flash
of the wrong theme on the very first paint (SSR/Nuxt, or a persisted SPA), set the `ori-theme_*` class
in a tiny inline `<head>` script before any stylesheet paints:

```html
<script>
    // runs before first paint. useTheme persists the SETTING, which may be 'auto' — RESOLVE it,
    // don't just test for the 'dark' string (matches default: 'auto').
    var s = localStorage.getItem('ori-theme'); // 'auto' | 'light' | 'dark' | null
    var dark = s === 'dark' || ((!s || s === 'auto') && matchMedia('(prefers-color-scheme: dark)').matches);
    document.documentElement.classList.add(dark ? 'ori-theme_dark' : 'ori-theme_light');
</script>
```

Applying the theme before render never needs the invalidation flush; only runtime switches do.

## Accessibility

- `default: 'auto'` respects the user's `prefers-color-scheme` and follows OS changes live — the
  accessible default; `setTheme` / `toggleTheme` let a user override it explicitly, and the choice
  persists.
- `color-scheme` (native controls, scrollbars, UA defaults) and WCAG-AA contrast in both modes are
  guaranteed by oriUI's theme selectors and the token contract — see the [Theming guide](https://oriui.vercel.app/guides/theming).

## See also

- [Theming](https://oriui.vercel.app/guides/theming) — the full mode + skin guide: skins, subtree scoping, the flash-free
  initial theme, and authoring a custom skin.
- [@oriui/headless](https://oriui.vercel.app/headless/core) — the framework-agnostic contract and the native engine.
- [useDisclosure](https://oriui.vercel.app/headless/use-disclosure) · [useDialog](https://oriui.vercel.app/headless/use-dialog) — the other headless
  primitives.


# useToast

A headless **toast queue** — an imperative notification store you call from anywhere (`toast('Saved')`)
and render once near the app root. The behaviour is a framework-agnostic engine (a plain array + a `Set`
of listeners + auto-dismiss timers) projected into the host framework's reactivity: a Vue **reactive
array** and a Svelte **readable store**. It is a client-side **singleton** — every `useToast()` call
shares the one queue, so a push from anywhere reaches the single renderer.

This is the **Vue** binding; the framework-agnostic engine lives in
[`@oriui/headless`](https://oriui.vercel.app/headless/core) (kept out of the core barrel so it never weighs on the core budget),
and the styled [`OriToaster`](https://oriui.vercel.app/components/toast) + `OriToast` render the queue. Unlike the roving /
machine composables, a toast queue has no ARIA prop-getters — the live-region roles live on the styled
`OriToast` (`role="status"` / `role="alert"` by color).

## Import

```ts
import { useToast } from '@oriui/headless/vue';
```

`@oriui/vue` re-exports the same `useToast`, so `import { useToast } from '@oriui/vue'` is equivalent (and
shares the one queue).

## Options

`toast(options)` (and the severity shortcuts) take either a **string** (its text) or a `ToastOptions`
object:

| Option     | Type         | Default | Description                                                                        |
| ---------- | ------------ | ------- | ---------------------------------------------------------------------------------- |
| `text`     | `string`     | —       | Body message. (`toast('hi')` is shorthand for `toast({ text: 'hi' })`.)            |
| `title`    | `string`     | —       | Optional bold heading above the text.                                              |
| `color`    | `ToastColor` | —       | Semantic role — drives the accent and the live-region assertiveness on `OriToast`. |
| `duration` | `number`     | `4000`  | Auto-dismiss delay in ms; `0` keeps the toast until it is dismissed.               |
| `closable` | `boolean`    | `true`  | Show a dismiss button on the toast.                                                |
| `icon`     | `string`     | —       | SVG path for a leading icon.                                                       |

`ToastColor` is `'primary' | 'secondary' | 'surface' | 'background' | 'success' | 'warn' | 'danger' | 'info'`.

## Returns

| Property                              | Type                                                   | Description                                                                                                                 |
| ------------------------------------- | ------------------------------------------------------ | --------------------------------------------------------------------------------------------------------------------------- |
| `toasts`                              | `ToastItem[]` (Vue) · `Readable<ToastItem[]>` (Svelte) | The live queue the renderer iterates. `ToastItem` is `ToastOptions` + a numeric `id`.                                       |
| `toast(options)`                      | `(options: ToastOptions | string) => number`           | Push a toast; returns its numeric `id` (pass to `dismiss`).                                                                 |
| `success` / `error` / `warn` / `info` | `(options: ToastOptions | string) => number`           | Severity shortcuts — set `color` to `success` / `danger` / `warn` / `info` (an explicit `color` in the options still wins). |
| `dismiss(id)`                         | `(id: number) => void`                                 | Remove a toast (and cancel its timer); a no-op for an unknown id.                                                           |
| `clear()`                             | `() => void`                                           | Empty the queue and cancel every timer.                                                                                     |

## Usage

Call `toast()` from anywhere, and render the queue once. The styled
[`OriToaster`](https://oriui.vercel.app/components/toast) does the rendering for you; to build your own, iterate `toasts`:

```vue
<!-- MyToaster.vue — render the queue (what OriToaster wraps) -->
<script setup lang="ts">
import { useToast } from '@oriui/headless/vue';

const { toasts, dismiss } = useToast();
</script>

<template>
    <div class="my-toaster">
        <div v-for="t in toasts" :key="t.id" role="status">
            {{ t.text }}
            <button v-if="t.closable" @click="dismiss(t.id)">×</button>
        </div>
    </div>
</template>
```

```ts
// anywhere — a component, a store, an interceptor
import { useToast } from '@oriui/headless/vue';

const { toast, success, error } = useToast();
success('Saved');
error({ title: 'Upload failed', text: 'Try again', duration: 0 }); // 0 = stay until dismissed
```

The **Svelte** binding is the same imperative API; `toasts` is a `readable` store you subscribe with `$`:

```svelte
<!-- MyToaster.svelte -->
<script>
    import { useToast } from '@oriui/headless/svelte';

    const { toasts, dismiss } = useToast();
</script>

{#each $toasts as t (t.id)}
    <div role="status">
        {t.text}
        {#if t.closable}<button on:click={() => dismiss(t.id)}>×</button>{/if}
    </div>
{/each}
```

## Accessibility

- The queue itself carries no roles — the **styled** [`OriToast`](https://oriui.vercel.app/components/toast) is the live region:
  `role="alert"` for `color="danger"` (assertive), `role="status"` otherwise (polite). If you render your
  own, put the same roles on each toast so a screen reader announces it.
- Auto-dismiss is timer-based; keep `duration` generous (or `0` for important messages) so a screen-reader
  user has time to read it, and always offer `closable` for manual dismissal.

## See also

- [@oriui/headless](https://oriui.vercel.app/headless/core) — the framework-agnostic layer (the queue engine ships from the
  `./vue` / `./svelte` adapters, not the core barrel).
- [Toast](https://oriui.vercel.app/components/toast) — the styled `OriToast` + `OriToaster` (positioning, transitions, roles).


# useToken

A reactive **token bridge** — it resolves an `--ori-*` design token to its computed value in JS, for
canvas / WebGL / chart painters (Konva, ECharts, …) that draw outside the CSS cascade yet must follow the
active skin. It reads through a hidden probe, because the obvious API is a trap: `getComputedStyle(el)``.getPropertyValue('--x')` hands back the unresolved `var()` chain (oriUI aliases chain), not a color —
substitution only happens at a real property's computed-value time.

This is the **Vue** binding; the framework-agnostic core (`resolveToken`, `observeTheme`) lives in
[`@oriui/headless`](https://oriui.vercel.app/headless/core), and a Svelte store twin ships at `@oriui/headless/svelte`. Like
[`useTheme`](https://oriui.vercel.app/headless/use-theme), this is DOM + state — a read-only reactive **value**, not a widget — so
there are no prop bags and no swappable adapter. It re-resolves on every skin / mode flip, and is a
**colors-only MVP**: the token must resolve to a `<color>`.

## Import

```ts
import { useToken, useThemeColor } from '@oriui/headless/vue';
```

## Arguments

`useToken` takes the custom-property name; `useThemeColor` is sugar that takes a color **role** and
expands it to `--ori-color-<role>`. Pass a getter / ref (Vue) or a store (Svelte) to re-resolve when the
argument changes — a plain string is a fixed snapshot.

| Argument (composable)     | Vue type                   | Svelte type             | Description                                                           |
| ------------------------- | -------------------------- | ----------------------- | --------------------------------------------------------------------- |
| `token` — `useToken`      | `MaybeRefOrGetter<string>` | `MaybeReactive<string>` | The `--ori-*` custom property to resolve, e.g. `--ori-color-primary`. |
| `color` — `useThemeColor` | `MaybeRefOrGetter<string>` | `MaybeReactive<string>` | A color role name; resolves `--ori-color-<color>` (e.g. `primary`).   |

## Returns

Both return a single **read-only reactive value** — the token's resolved computed color (e.g.
`'rgb(3, 105, 161)'`), or `''` until it resolves.

| Composable             | Vue                     | Svelte             | Value                                                         |
| ---------------------- | ----------------------- | ------------------ | ------------------------------------------------------------- |
| `useToken(token)`      | `Readonly<Ref<string>>` | `Readable<string>` | The resolved computed value of the `--ori-*` custom property. |
| `useThemeColor(color)` | `Readonly<Ref<string>>` | `Readable<string>` | Sugar: the resolved value of `--ori-color-<color>`.           |

The value is `''` during SSR and before mount (Vue) — server and first client render match — resolving
on mount; re-resolves when the token argument changes (only if you passed a getter / ref / store) and on
every theme change — skin class / style toggles **and** OS `prefers-color-scheme` flips — via the core
`observeTheme`. The observer is torn down on scope dispose (Vue component unmount). An unresolvable token
returns `''` too, and in dev builds warns once naming the token (so the SSR-`''` and failed-`''` cases are
distinguishable).

## Usage

There is no styled component — the consumer is a JS painter. Create the engine in `onMounted` (this
composable's own `onMounted` ran first, so `brand.value` is already resolved), seed it with the resolved
value, then `watch` — theme flips re-push automatically:

```vue
<script setup lang="ts">
import { onMounted, useTemplateRef, watch } from 'vue';
import { useThemeColor } from '@oriui/headless/vue';

const canvasEl = useTemplateRef<HTMLCanvasElement>('canvas');
const brand = useThemeColor('primary'); // resolved --ori-color-primary; '' until mounted (SSR-safe)

let engine: Engine | undefined;
onMounted(() => {
    engine = createEngine(canvasEl.value);
    engine.setColor(brand.value || null); // seed the initial resolved color
});
watch(brand, (c) => engine?.setColor(c || null)); // '' (SSR/unresolved) -> engine default
</script>

<template>
    <canvas ref="canvas" />
</template>
```

The **Svelte** binding is the same — a lazy readable store (resolution and the theme observer start with
the first subscriber and tear down with the last). Create the engine in `onMount`, then `subscribe`: it
fires immediately with the current value (seeding the engine) and again on every theme flip. (In markup
you can auto-subscribe with `$brand` instead.)

```svelte
<script>
    import { onMount } from 'svelte';
    import { useThemeColor } from '@oriui/headless/svelte';

    let canvas;
    const brand = useThemeColor('primary');

    onMount(() => {
        const engine = createEngine(canvas);
        const stop = brand.subscribe((c) => engine.setColor(c || null)); // fires immediately, then on theme flips
        return () => stop();
    });
</script>

<canvas bind:this={canvas} />
```

## Lower-level

Both composables wrap two core exports you can call directly (no framework). `resolveToken(token, options?)`
is the one-shot probe — it appends a hidden element whose `color` is `var(<token>)`, reads
`getComputedStyle(probe).color`, and removes it, returning `''` when the token is unresolvable or
`document` is undefined (SSR). `observeTheme(callback, options?)` is the invalidation signal — a
`MutationObserver` on the target's `class` / `style` plus a `matchMedia('(prefers-color-scheme: dark)')`
change listener (so an `auto`-skin OS flip re-resolves without any attribute mutating); it returns an
unsubscribe.

```ts
import { resolveToken, observeTheme } from '@oriui/headless';

let color = resolveToken('--ori-color-primary'); // 'rgb(3, 105, 161)' | '' if unresolvable / SSR
const stop = observeTheme(() => {
    color = resolveToken('--ori-color-primary'); // re-resolve on skin/mode flip
});
// later: stop();
```

Each takes an optional `element` (`ResolveTokenOptions` / `ObserveThemeOptions`), defaulting to
`document.documentElement` — pass a wrapper to resolve within (or watch) a scoped subtree's cascade
context. `resolveToken` is synchronous and allocation-light but touches the DOM, so cache per frame if you
resolve many tokens in a render loop. See [`@oriui/headless`](https://oriui.vercel.app/headless/core).

## Accessibility

There is no interactive surface here — the value the bridge hands a painter is where accessibility lives.

- It re-resolves on skin / style toggles **and** OS `prefers-color-scheme` flips (`observeTheme` listens
  to `matchMedia`), so a canvas / chart honours the user's live light / dark preference and explicit theme
  choice exactly like CSS-cascade content — no stale colors after a theme switch.
- Resolving the role tokens (`useThemeColor('primary')`, its `on-` partner) inherits oriUI's
  contrast-checked pairing rather than a hand-picked color; the WCAG-AA guarantee that the
  [contrast test](https://oriui.vercel.app/guides/customization#_1-start-with-the-props-the-semantic-roles) asserts for the
  shipped roles carries through into your painter.
- SSR-safe by design: `''` until mounted means server and first client render agree (no hydration
  mismatch) — seed the engine's own default (`c || null`) until the real color resolves.

## See also

- [Customization → Reading tokens from JS](https://oriui.vercel.app/guides/customization#reading-tokens-from-js) — the guide
  section this bridge backs, with the full canvas-painter pattern.
- [@oriui/headless](https://oriui.vercel.app/headless/core) — the framework-agnostic `resolveToken` / `observeTheme` primitives.
- [useTheme](https://oriui.vercel.app/headless/use-theme) — the light / dark controller whose flips these tokens re-resolve
  against.


# useToolbar

A headless **WAI-ARIA toolbar** — a set of related controls behind a **single Tab stop**, navigated
internally with the arrow keys via **roving tabindex** (real DOM focus, not `aria-activedescendant`).
The root owns orientation / loop / direction and a single keydown handler; each item registers itself
and receives its roving `tabindex`, so a toolbar is assembled from arbitrary **slotted** components
rather than a fixed data array.

This is the **Vue** binding; the framework-agnostic core (the pure roving index/key math) lives in
[`@oriui/headless`](https://oriui.vercel.app/headless/core), and the styled [`OriToolbar`](https://oriui.vercel.app/components/toolbar) is built on it.
Unlike [`useDialog`](https://oriui.vercel.app/headless/use-dialog) (a state machine behind a swappable adapter) or
[`useMenu`](https://oriui.vercel.app/headless/use-menu) (a state-machine projection with no adapter), a toolbar is a
compositional `provide` / `inject` roving **context** — real DOM order plus `.focus()`, with no
alternative engine to swap. It composes the pure roving helpers from the core rather than wrapping a
state machine.

## Import

```ts
import {
    useToolbar,
    useToolbarItem,
    useToolbarOrientation,
    useToolbarToggleGroup,
    useToolbarToggleItem
} from '@oriui/headless/vue';
```

The module exports five composables. `useToolbar` is the root — its options and return are below; the
four companions (`useToolbarItem`, `useToolbarOrientation`, `useToolbarToggleGroup`,
`useToolbarToggleItem`) follow in [Item & selection composables](https://oriui.vercel.app/#item--selection-composables).

## Options

`useToolbar(options?)` — every option is optional and accepts a plain value, a `ref`, or a getter
(`MaybeRefOrGetter`) so it can change reactively.

| Option        | Type                        | Default        | Description                                                                                                                |
| ------------- | --------------------------- | -------------- | -------------------------------------------------------------------------------------------------------------------------- |
| `orientation` | `'horizontal' | 'vertical'` | `'horizontal'` | Arrow-key axis: `horizontal` navigates with Left/Right, `vertical` with Up/Down. Only `vertical` emits `aria-orientation`. |
| `loop`        | `boolean`                   | `true`         | Whether arrow navigation wraps first⇄last at the ends (the WAI-ARIA APG reference example wraps).                          |
| `dir`         | `'ltr' | 'rtl'`             | `'ltr'`        | Text direction — `rtl` swaps the horizontal Left/Right mapping. Vertical navigation is direction-independent.              |
| `label`       | `string`                    | —              | Accessible name → `aria-label`. A toolbar MUST be named — via this or an `aria-labelledby` you pass through.               |

## Returns

| Property       | Type                  | Description                                                                                                                                                                                                                                 |
| -------------- | --------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `toolbarProps` | `ComputedRef<object>` | The toolbar element's bag: `role="toolbar"`, `aria-orientation` (vertical only), `aria-label`, and the roving `onKeydown` handler. Bind with `v-bind`; no element ref is needed — the handler resolves the root from `event.currentTarget`. |

## Item & selection composables

Every prop bag these four return is a `ComputedRef` you bind with `v-bind`. `useToolbarItem` — and the
roving half of `useToolbarToggleItem` — registers with the `useToolbar` root: **outside a root there is
no context to join**, so its `tabindex` stays `-1` (unreachable by keyboard). `useToolbarToggleGroup` and
the **selection** half of `useToolbarToggleItem` (`aria-pressed` / `onChange`) run on their own
toggle-group context, independent of any toolbar root — only the roving tabindex depends on `useToolbar`.

### useToolbarItem

`useToolbarItem()` — registers the calling component as a toolbar item and returns its roving props.
Takes no arguments. Outside a `useToolbar` root there is nothing to register with, so `tabindex` stays
`-1` forever (unreachable by keyboard).

| Property    | Type                   | Description                                                                                                                                                                                                                   |
| ----------- | ---------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `itemProps` | `ComputedRef<object>`  | Spread on the focusable element (a `<button>`): the `data-ori-toolbar-item` marker the root navigates by, the roving `tabindex` (`0` when active, `-1` otherwise), and an `onFocus` that makes this item the active tab stop. |
| `isActive`  | `ComputedRef<boolean>` | Whether this item is the current roving tab stop (`tabindex="0"`).                                                                                                                                                            |

### useToolbarOrientation

`useToolbarOrientation()` — reads the enclosing toolbar's orientation, used by a custom separator or
group to render perpendicular / matching. It returns the getter **directly** (not a prop bag).

| Returns                | Type                      | Description                                                                                                                                                                           |
| ---------------------- | ------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| the orientation getter | `() => RovingOrientation` | Reads the enclosing orientation (`'horizontal' | 'vertical'`); defaults to `'horizontal'` outside a toolbar. (The Svelte twin returns a `Readable<RovingOrientation>` store instead.) |

### useToolbarToggleGroup

`useToolbarToggleGroup(options)` — provides a toggle-selection context to nested
`useToolbarToggleItem`s. It is a `role="group"` layered over the flat toolbar roving order: its items
remain ordinary toolbar items, reached by the same arrow navigation, so the group adds no stop of its
own. Wire `value` / `onChange` to your `v-model`. All three `UseToolbarToggleGroupOptions` fields are
required:

| Option     | Type                                             | Description                                                                                        |
| ---------- | ------------------------------------------------ | -------------------------------------------------------------------------------------------------- |
| `type`     | `MaybeRefOrGetter<'single' | 'multiple'>`        | `single` keeps one value and is deselectable (re-selecting clears it); `multiple` keeps a set.     |
| `value`    | `() => string | string[] | undefined`            | Getter for the current value: a string (or `undefined`) for `single`, a `string[]` for `multiple`. |
| `onChange` | `(value: string | string[] | undefined) => void` | Commit the next value (wire to your `v-model`).                                                    |

| Property     | Type                  | Description                                                                                    |
| ------------ | --------------------- | ---------------------------------------------------------------------------------------------- |
| `groupProps` | `ComputedRef<object>` | The group element's bag: `role="group"`. Bind with `v-bind`, and give it its own `aria-label`. |

### useToolbarToggleItem

`useToolbarToggleItem(value)` — composes `useToolbarItem` (roving) with the toggle-group selection
context. Pass the item's `value` (`MaybeRefOrGetter<string>`). Requires a surrounding
`useToolbarToggleGroup`.

| Property    | Type                   | Description                                                                                                                                                  |
| ----------- | ---------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `itemProps` | `ComputedRef<object>`  | `useToolbarItem`'s bag plus `aria-pressed` (derived from the group's selection) and an `onClick` that toggles this `value` in the group. Bind with `v-bind`. |
| `pressed`   | `ComputedRef<boolean>` | Whether this item is currently selected in the group.                                                                                                        |
| `isActive`  | `ComputedRef<boolean>` | Whether this item is the current roving tab stop.                                                                                                            |

## Usage

A toolbar is two pieces: a **root** that spreads `toolbarProps` (and owns the roving keydown), and
**items** that each call `useToolbarItem` to register and spread `itemProps`. This is exactly what the
styled [`OriToolbar`](https://oriui.vercel.app/components/toolbar) / `OriToolbarButton` wrap.

```vue
<!-- MyToolbar.vue — the root: owns orientation / loop / dir + the roving keydown handler -->
<script setup lang="ts">
import { useToolbar } from '@oriui/headless/vue';

const { label = 'Formatting', orientation = 'horizontal' } = defineProps<{
    label?: string;
    orientation?: 'horizontal' | 'vertical';
}>();

// Pass getters so orientation / label stay reactive (vue/no-setup-props-reactivity-loss).
const { toolbarProps } = useToolbar({
    label: () => label,
    orientation: () => orientation
});
</script>

<template>
    <!-- No element ref: the keydown handler resolves the root from event.currentTarget. -->
    <div v-bind="toolbarProps">
        <slot></slot>
    </div>
</template>
```

```vue
<!-- MyToolbarButton.vue — an item: registers with the roving context, spreads itemProps -->
<script setup lang="ts">
import { useToolbarItem } from '@oriui/headless/vue';

defineProps<{ text: string }>();

// itemProps carries data-ori-toolbar-item + the roving tabindex + onFocus.
const { itemProps } = useToolbarItem();
</script>

<template>
    <button v-bind="itemProps">{{ text }}</button>
</template>
```

```vue
<MyToolbar label="Formatting">
    <MyToolbarButton text="New" />
    <MyToolbarButton text="Open" />
    <MyToolbarButton text="Save" />
</MyToolbar>
```

**A toggle group** layers selection state on the same roving context — a `useToolbarToggleGroup` root
plus `useToolbarToggleItem` children (`OriToolbarToggleGroup` / `OriToolbarToggleItem` wrap this):

```vue
<!-- MyToggleGroup.vue -->
<script setup lang="ts">
import { useToolbarToggleGroup } from '@oriui/headless/vue';

const { type = 'single' } = defineProps<{ type?: 'single' | 'multiple' }>();
const model = defineModel<string | string[]>();

const { groupProps } = useToolbarToggleGroup({
    type: () => type,
    value: () => model.value,
    onChange: (value) => {
        model.value = value;
    }
});
</script>

<template>
    <div v-bind="groupProps" aria-label="Text style">
        <slot></slot>
    </div>
</template>
```

```vue
<!-- MyToggleItem.vue -->
<script setup lang="ts">
import { useToolbarToggleItem } from '@oriui/headless/vue';

const { value } = defineProps<{ value: string }>();

// itemProps = roving props + aria-pressed (from the group) + the toggling onClick.
const { itemProps } = useToolbarToggleItem(() => value);
</script>

<template>
    <button v-bind="itemProps"><slot></slot></button>
</template>
```

The **Svelte** binding is the same — a `setContext` roving context, the prop bags as `Readable` stores
you auto-subscribe with `$`, and lowercased event handlers (`onkeydown` / `onfocus`). Options are a
plain object (or a store), not getters:

```svelte
<!-- MyToolbar.svelte -->
<script>
    import { useToolbar } from '@oriui/headless/svelte';

    export let label = 'Formatting';
    const { toolbarProps } = useToolbar({ label });
</script>

<div {...$toolbarProps}>
    <slot />
</div>
```

```svelte
<!-- MyToolbarButton.svelte -->
<script>
    import { useToolbarItem } from '@oriui/headless/svelte';

    export let text;
    const { itemProps } = useToolbarItem();
</script>

<button {...$itemProps}>{text}</button>
```

## Accessibility

The prop bags carry the WAI-ARIA [Toolbar](https://www.w3.org/WAI/ARIA/apg/patterns/toolbar/){rel="&#x22;nofollow&#x22;"} pattern;
the keyboard behaviour is the roving `onKeydown` on the root.

- `toolbarProps` set `role="toolbar"`, `aria-orientation` (emitted only for `vertical` — `horizontal`
  is the ARIA implicit default), `aria-label` (from `label`), and the roving `onKeydown`. A
  `role="toolbar"` **must** have an accessible name — pass `label`, or pass your own `aria-labelledby`
  through onto the element.
- **Roving tabindex.** Exactly one item is `tabindex="0"` at a time — the active one, defaulting to the
  first registered item; every other item is `tabindex="-1"`. Real DOM focus moves as you navigate;
  there is no `aria-activedescendant`. `itemProps`' `onFocus` makes the focused item the active stop.
- **DOM-order navigation.** The keydown handler resolves items by
  `root.querySelectorAll('[data-ori-toolbar-item]')` in document order, so navigation stays correct
  even when items are conditionally rendered or reordered — no order-stable ref array required.
- **Focusable disabled.** Navigation visits every registered item, so implement a disabled item as
  `aria-disabled` (leaving the element focusable and carrying the `data-ori-toolbar-item` marker)
  rather than the native `disabled` attribute — the WAI-ARIA toolbar keeps disabled controls
  discoverable, blocking only activation. (The styled `OriToolbarButton` does exactly this.)
- **Composite-child yield.** When focus sits on a control that owns the arrow keys, the toolbar's
  keydown yields entirely and does not steal them. That covers a native `input` (every type **except**`checkbox` / `button` — so a native radio yields), `textarea`, `select`, or `[contenteditable]`; an
  element whose **own** `role` is `slider` / `spinbutton` / `radiogroup` / `menu` / `listbox` /
  `combobox` / `textbox`; or any element **inside an ancestor** with `role` `radiogroup` / `menu` /
  `listbox` / `grid` / `tree`. Per the APG, include at most one such control and place it last.

| Key                                    | Action                                                                                                                               |
| -------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------ |
| `Tab` / `Shift+Tab`                    | Move focus into the toolbar (landing on the active item) or past it — the whole toolbar is a single tab stop.                        |
| `ArrowRight` / `ArrowLeft`             | Horizontal: move the roving stop to the next / previous item (wraps first⇄last when `loop`, the default). Swapped under `dir="rtl"`. |
| `ArrowDown` / `ArrowUp`                | Vertical: move the roving stop to the next / previous item (wraps when `loop`).                                                      |
| `Home` / `End`                         | Jump the roving stop to the first / last item, in either orientation.                                                                |
| `Enter` / `Space`                      | Activate the focused item — native for a `<button>`; a toggle item's `onClick` flips its value in the group.                         |
| Arrow keys, focus in a composite child | Not intercepted — the focused input / composite widget keeps its own arrow-key behaviour.                                            |

## See also

- [@oriui/headless](https://oriui.vercel.app/headless/core) — the framework-agnostic core: the pure roving index/key math
  (`rovingIntent` / `resolveRovingIndex`) and the arrow-yield predicate, shared with the Svelte twin.
- [Toolbar](https://oriui.vercel.app/components/toolbar) — the styled `OriToolbar` (+ Button / Separator / ToggleGroup /
  ToggleItem) built on these composables.
- [useDialog](https://oriui.vercel.app/headless/use-dialog) · [useDisclosure](https://oriui.vercel.app/headless/use-disclosure) — the sibling headless
  primitives (the machine-behind-a-swappable-adapter shape).
- [CSS layer](https://oriui.vercel.app/guides/css) — the standalone `.ori-toolbar` classes for the toolbar parts.


# Accessibility

Accessibility in oriUI is **structural, not a coat of polish on top**. The same decisions that make
the components correct for assistive technology also make them themeable and framework-agnostic — they
are the same source of truth, not a separate effort.

## State lives in attributes, not classes

Every dynamic state is a real DOM attribute, styled with attribute selectors — never a JavaScript-only
class:

- `disabled` / `aria-disabled` for disabled controls,
- `aria-busy="true"` for loading,
- `aria-pressed` / `data-active` for toggles,
- `aria-expanded` + `aria-controls` for disclosures.

This is the accessible source of truth, and because it is plain markup it is **identical across all
three layers** — a styled `OriButton`, a hand-written `.ori-button`, and a headless prop bag all expose
the same attributes to a screen reader.

## Color meets WCAG AA — and it's tested

Color comes in **role / on-role pairs** (`primary` / `on-primary`, …), so foreground always has a
matching, legible background. That contract is **executable**: `tests/tokens.contrast.test.ts` parses
every skin's CSS and asserts each role/on-role pair clears the **WCAG AA** contrast ratio — in CI, for
every skin and both light and dark. It has already caught a real contrast failure in a skin during
development.

## Keyboard and focus

- Controls render **native elements** (`<button>`, `<input>`) wherever possible, so keyboard
  activation (`Enter` / `Space`), tab order, and form semantics come for free.
- Focus rings ride &#x2A;*`:focus-visible`**, so they show for keyboard users without flashing on every
  mouse click.
- Hover styling is wrapped in `@media (hover: hover)`, so there is **no sticky hover** on touch.
- The headless layer owns the hard keyboard behavior — `useDialog`'s focus trap, `Escape` to close,
  and focus return to the trigger. See [@oriui/headless](https://oriui.vercel.app/headless/core).

## Touch targets

The default control size (`md`) is a **44px** target — a comfortable tap area on touch, matching the
mobile-first sizing of the token scale. Use the larger `lg` size where a screen calls for it.

## Per-component contracts

Every component page has its own **Accessibility** section spelling out roles, states, and the keyboard
map, and each component ships axe-core assertions in the test suite. Start with
[Button](https://oriui.vercel.app/components/button#accessibility).


# Applicability

oriUI is three independently-consumable layers woven around one token contract. The promise is
**prototype fast, scale without rewriting**: reach for the styled Vue components first, drop to the
headless behaviour when you need control, or drop to the standalone CSS when you leave Vue entirely —
without changing your design tokens. This page maps each layer to where it runs.

## Layer × environment

| Layer                            | Vue 3 | Svelte 5 | Astro | htmx / plain HTML |
| -------------------------------- | :---: | :------: | :---: | :---------------: |
| `@oriui/css` (classes + tokens)  |   ✅   |     ✅    |   ✅   |         ✅         |
| `@oriui/headless` (core engine)  |   ✅¹  |    ✅¹    |  ⚠️²  |        ⚠️²        |
| `@oriui/headless/vue`            |   ✅   |     —    |  ⚠️³  |         —         |
| `@oriui/headless/svelte`         |   —   |     ✅    |  ⚠️³  |         —         |
| `@oriui/vue` (styled components) |   ✅   |     —    |  ⚠️³  |         —         |

✅ first-class · ⚠️ works with a caveat · — use a different layer instead.

1. Through the matching adapter — `@oriui/headless/vue` (Vue `ComputedRef`s) or `@oriui/headless/svelte`
   (Svelte stores). The core itself imports no framework.
2. The core is framework-agnostic building blocks (state machine + prop-getters), so it runs anywhere
   JavaScript does — but you wire the DOM binding yourself. A no-framework / htmx adapter is deferred
   (see [ROADMAP](https://github.com/markgrushevski/oriui/blob/main/ROADMAP.md){rel="&#x22;nofollow&#x22;"}); until then, use the
   `.ori-*` classes for the look and hand-roll the small amount of behaviour.
3. Inside an [Astro island](https://docs.astro.build/en/guides/framework-components/){rel="&#x22;nofollow&#x22;"} for that framework
   (`client:load` / `client:visible`); Astro renders the Vue or Svelte component as usual.

## Runtimes follow their framework

The columns above are the **rendering environments**. The **runtime shells** below just host one of
them, so they inherit that column's support:

| Runtime                | Inherits         | Notes                                                                                                         |
| ---------------------- | ---------------- | ------------------------------------------------------------------------------------------------------------- |
| **Nuxt** / Vite SSR    | Vue 3            | `@oriui/vue` is SSR-safe: SSR-stable ids (`useId`), native `<dialog>` (no `<Teleport>` gymnastics).           |
| **SvelteKit**          | Svelte 5         | `@oriui/headless/svelte` seeds stores from the machine's initial state; pass an explicit `id` for stable SSR. |
| **Capacitor** (hybrid) | Vue 3 / Svelte 5 | A web app in a native shell — whatever your web framework supports.                                           |
| **Electron**           | Vue 3 / Svelte 5 | Same: a web renderer, so the framework column applies unchanged.                                              |

## Zero-runtime everywhere

Theming is the one guarantee that holds across **every** cell: skin and light/dark are pure attribute
toggles on `<html>` that repoint CSS custom properties, so a Vue app, a Svelte island, an htmx fragment,
and a plain HTML page all reskin identically — no JavaScript, no recompute. See
[Theming](https://oriui.vercel.app/guides/theming) and the [Skin gallery](https://oriui.vercel.app/guides/skins).


# Cheat sheet

Everything in one page — install, the class model, every component, and the design tokens. For the
machine-readable version (e.g. to paste into an AI), fetch [`/llms.txt`](https://oriui.vercel.app/llms.txt) (index) or
[`/llms-full.txt`](https://oriui.vercel.app/llms-full.txt) (every page concatenated).

## Install

```bash
npm install @oriui/vue      # styled Vue components
npm install @oriui/css     # standalone CSS layer (no framework)
npm install @oriui/headless     # headless composables (focus / keyboard / ARIA)
```

```ts
import '@oriui/css'; // the stylesheet, once (e.g. in your entry file)
import { OriButton } from '@oriui/vue';
```

## Two ways to use it

```vue
<!-- Vue component -->
<OriButton text="Save" variant="tonal" color="primary" size="lg" />
```

```html
<!-- Standalone CSS (htmx / Astro / Svelte / plain HTML) — same tokens, no Vue -->
<button class="ori-button ori-button_lg ori-variant_tonal ori-color_primary">Save</button>
```

## The class model

A **block class** plus **single-class token utilities** — one class repoints one token, no paired base
class. The block bakes sensible defaults, so a **bare block is valid**; add a class only to override an
axis. Dynamic state is real **attributes** (`disabled`, `aria-busy="true"`, `aria-pressed`), never
classes.

| Axis                   | Class               | Values                                                                                      |
| ---------------------- | ------------------- | ------------------------------------------------------------------------------------------- |
| Color (the role)       | `ori-color_*`       | `primary` · `secondary` · `success` · `warn` · `danger` · `info` · `surface` · `background` |
| Variant (the mapping)  | `ori-variant_*`     | `fill` · `tonal` · `outline` · `text` · `plain`                                             |
| Size (component sugar) | `ori-<name>_<size>` | `xs` · `sm` · `md` · `lg` · `xl` · `xxl`                                                    |
| Radius                 | `ori-size-radius_*` | `zero` · `xs` · `sm` · `md` · `lg` · `xl` · `rounded`                                       |
| Font                   | `ori-font-size_*`   | `xs` · `sm` · `md` · `lg` · `xl` · `xxl`                                                    |

`color` is the **role**, `variant` is the **mapping** — `fill` paints the accent as background (with the
on-color text), `outline`/`text` paint it as border/text — so there is no separate `bg-color`. The
low-level size utility `ori-size-action_<size>` works too; the `ori-<name>_<size>` sugar is the friendly
shape. Full detail: [Using the CSS layer](https://oriui.vercel.app/guides/css).

## Components at a glance

Each links to its full page (class table, props, slots, a11y). Props listed are the common ones — see
the page for the complete set.

| Component                                                       | Vue                | Key props                                                                                            |
| --------------------------------------------------------------- | ------------------ | ---------------------------------------------------------------------------------------------------- |
| [Button](https://oriui.vercel.app/components/button)            | `<OriButton>`      | `text` `icon` `variant` `color` `size` `radius` `as` `loading` `disabled` `fluid`                    |
| [Card](https://oriui.vercel.app/components/card)                | `<OriCard>`        | `variant` `color` `radius` `title` `prependIcon` `row` `fluid` `disabled` `loading`                  |
| [Avatar](https://oriui.vercel.app/components/avatar)            | `<OriAvatar>`      | `src` `text` `size` `radius` `color` `title` `subtitle` `inline` `spaced`                            |
| [Icon](https://oriui.vercel.app/components/icon)                | `<OriIcon>`        | `icon` `size` `color` `label` `inline` `spaced`                                                      |
| [Spinner](https://oriui.vercel.app/components/spinner)          | `<OriSpinner>`     | `size` `color` `inline`                                                                              |
| [Badge](https://oriui.vercel.app/components/badge)              | `<OriBadge>`       | `color` `variant` `radius` `dot` (default slot is the anchor)                                        |
| [Tag](https://oriui.vercel.app/components/tag)                  | `<OriTag>`         | `text` `color` `variant` `radius` `size` `closable` `prependIcon` `disabled`                         |
| [Alert](https://oriui.vercel.app/components/alert)              | `<OriAlert>`       | `title` `text` `color` `variant` `radius` `size` `icon` `closable` `live`                            |
| [Progress](https://oriui.vercel.app/components/progress)        | `<OriProgress>`    | `value` `color` `radius` `size` `indeterminate` `label`                                              |
| [Tooltip](https://oriui.vercel.app/components/tooltip)          | `<OriTooltip>`     | `content` `placement` `color`                                                                        |
| [Accordion](https://oriui.vercel.app/components/accordion)      | `<OriAccordion>`   | `items` `multiple` `radius` `color`                                                                  |
| [Tabs](https://oriui.vercel.app/components/tabs)                | `<OriTabs>`        | `tabs` `color` `orientation` (`v-model` = selected)                                                  |
| [Divider](https://oriui.vercel.app/components/divider)          | `<OriDivider>`     | `color` `text` `vertical` (default slot = centered label)                                            |
| [Stack](https://oriui.vercel.app/components/stack)              | `<OriStack>`       | `align` `as` `cluster` `gap` `justify` (`.ori-stack` column · `.ori-cluster` wrapping row)           |
| [Join](https://oriui.vercel.app/components/join)                | `<OriJoin>`        | `as` `vertical` — collapses children's shared radii/borders (add `aria-label`)                       |
| [Input](https://oriui.vercel.app/components/input)              | `<OriInput>`       | `label` `type` `color` `size` `radius` `variant` `hint` `error` `required` `disabled` (`v-model`)    |
| [Textarea](https://oriui.vercel.app/components/textarea)        | `<OriTextarea>`    | `label` `color` `size` `radius` `variant` `rows` `hint` `error` `required` (`v-model`)               |
| [Select](https://oriui.vercel.app/components/select)            | `<OriSelect>`      | `label` `options` `color` `size` `radius` `hint` `error` `required` (`v-model`)                      |
| [Field](https://oriui.vercel.app/components/field)              | `<OriField>`       | `label` `hint` `error` `required` `disabled` `size` — shared form shell; wraps any control           |
| [Combobox](https://oriui.vercel.app/components/combobox)        | `<OriCombobox>`    | `options` `label` `color` `size` `radius` `clearable` `hint` `error` `required` `filter` (`v-model`) |
| [Checkbox](https://oriui.vercel.app/components/checkbox)        | `<OriCheckbox>`    | `label` `color` `size` `value` `disabled` `invalid` `required` (`v-model`)                           |
| [Radio](https://oriui.vercel.app/components/radio)              | `<OriRadioGroup>`  | `label` `options` `color` `size` `inline` `disabled` `required` (`v-model`)                          |
| [Switch](https://oriui.vercel.app/components/switch)            | `<OriSwitch>`      | `label` `color` `size` `disabled` `invalid` (`v-model` boolean)                                      |
| [Dialog](https://oriui.vercel.app/components/dialog)            | `<OriDialog>`      | `open` (`v-model:open`) `defaultOpen` `modal` — native `<dialog>`, focus-trap + `Esc` for free       |
| [Menu](https://oriui.vercel.app/components/menu)                | `<OriMenu>`        | `items` `placement` `disabled` — roving menu from a `#trigger`; `useMenu` behavior                   |
| [Popover](https://oriui.vercel.app/components/popover)          | `<OriPopover>`     | `placement` `role` — anchored panel; `#trigger` + default slot (the OriPopover ADR)                  |
| [Link](https://oriui.vercel.app/components/link)                | `<OriLink>`        | `as` `color` `external` `hover` `href` (inline prose link; underline-on-hover)                       |
| [Skeleton](https://oriui.vercel.app/components/skeleton)        | `<OriSkeleton>`    | `as` `radius` — shimmer placeholder; size via width/height; honors reduced-motion                    |
| [Kbd](https://oriui.vercel.app/components/kbd)                  | `<OriKbd>`         | `as` `text` (default slot = key) — keyboard-key chip                                                 |
| [Toast](https://oriui.vercel.app/components/toast)              | `<OriToaster>`     | imperative `useToast()` push API + `<OriToaster position>` — transient notifications                 |
| [Slider](https://oriui.vercel.app/components/slider)            | `<OriSlider>`      | `color` `disabled` `label` `min` `max` `step` `showValue` (`v-model` number; native range)           |
| [Surface](https://oriui.vercel.app/components/surface)          | `<OriSurface>`     | `as` `bordered` `elevation` `radius` — elevated surface primitive                                    |
| [Toolbar](https://oriui.vercel.app/components/toolbar)          | `<OriToolbar>`     | `label` `orientation` `loop` `dir` — roving toolbar (`<OriToolbarButton/ToggleGroup/Separator>`)     |
| [ColorPicker](https://oriui.vercel.app/components/color-picker) | `<OriColorPicker>` | `format` `alpha` `eyedropper` `presets` `label` `disabled` (`v-model` string; `change` commits)      |

## Theming & tokens

Theme and skin are attributes on `<html>` — flipping them reskins everything through CSS variables,
zero-runtime:

```html
<html class="dark" data-ori-skin="cyber">
    …
</html>
```

- `class="dark"` → dark mode (omit for light).
- `data-ori-skin="sumi | indigo | tech | health | luxury | neutral | cyber"` → a preset skin (omit for
  the default **Ori** skin).

Tokens are two-tier: a raw scale (`--ori-size-action_md`, `--ori-color-primary`) and a resolved alias
(`--ori-size-action`, `--ori-color`) that a utility repoints and the component reads. Override one token
on a scope to retune a whole subtree:

```css
.dense-toolbar {
    --ori-size-action: 32px;
} /* every action-sized control inside shrinks */
```

More: [Design tokens](https://oriui.vercel.app/guides/design-tokens) · [Theming](https://oriui.vercel.app/guides/theming) ·
[Customization](https://oriui.vercel.app/guides/customization).


# Idea & comparisons

oriUI's one-line idea — **prototype fast, scale without rewriting** — falls out of a single
architectural choice: **three layers woven around one token contract**, so you can change *depth*
(styled → headless → CSS) without changing your *design system*. This page sets that idea next to the
libraries oriUI learns from, and is honest about where it does and doesn't compete.

If you just want the mechanics, start with the [Introduction](https://oriui.vercel.app/overview/introduction) and the
[Applicability matrix](https://oriui.vercel.app/overview/applicability); this page is the *why* and the *positioning*.

## What oriUI is — and isn't

**It is:**

- A **token-first** system: the design tokens are the theming API, shared identically by every layer.
- **Three depths of one stack** — `@oriui/vue` (styled) · `@oriui/headless` (behaviour) · `@oriui/css`
  (standalone classes) — each usable alone or composed.
- **Zero-runtime**: skins, light/dark, size, and variant are CSS custom-property toggles — never JS.
- **Multi-framework at the behaviour layer**: one framework-agnostic core, thin Vue **and** Svelte
  adapters.

**It isn't:**

- A **race on catalog size**. The reference libraries below are mined for ideas, not chased on count.
- A **Tailwind plugin**. The CSS layer is plain, prefixed, `@layer`-scoped classes; Tailwind is an
  optional preset, never a requirement.
- A **single-framework headless kit** or a **build-time CSS-in-JS** engine.

## The design axes

oriUI is built around five properties. The table compares on **those** axes — it reflects each
project's *primary design intent*, not a feature-by-feature scorecard, and every project below is
excellent at what it set out to do.

| Project             | Layered (styled + headless + CSS) | Zero-runtime token theming | Standalone CSS (no framework / build) |    Multi-framework headless    | No Tailwind dependency |
| ------------------- | :-------------------------------: | :------------------------: | :-----------------------------------: | :----------------------------: | :--------------------: |
| **oriUI**           |                 ✅                 |              ✅             |                   ✅                   |    ✅ Vue + Svelte, one core    |            ✅           |
| daisyUI             |            — (CSS only)           |    \~ CSS vars, Tailwind   |            — needs Tailwind           |                —               |      — is Tailwind     |
| Ark UI + Zag        |          \~ headless only         |        n/a unstyled        |                   —                   | ✅ Vue / React / Solid / Svelte |            ✅           |
| Reka UI             |       \~ headless, Vue only       |             n/a            |                   —                   |           — Vue only           |            ✅           |
| Radix / Headless UI |          \~ headless only         |             n/a            |                   —                   |     — mostly per-framework     |            ✅           |
| Panda / shadcn/ui   |          — styling system         |  \~ build-time extraction  |                   —                   |                —               |            ✅           |
| Vuetify / PrimeVue  |           — styled only           |       \~ theme config      |                   —                   |           — Vue only           |            ✅           |

✅ core design · \~ partial / with caveats · — not a goal · n/a not applicable

The point isn't any single column — it's the **combination**. Plenty of libraries own one or two of
these; oriUI's bet is that a token contract shared across *all* of them is what lets you start fast and
deepen without a rewrite.

## Category by category

### Headless libraries — Ark UI (+ Zag), Reka, Radix, Headless UI

The closest neighbours to oriUI's behaviour layer, and the ones it borrows the most from: the
`useMachine → connect(service, normalize) → spread prop-getters` seam is modelled on **Zag** / **Ark
UI** (verified against their source). The difference is scope: for oriUI, headless is *one depth of a
stack*, not the whole product — stay styled, drop to headless, or drop to CSS, all on the same tokens.
oriUI's core stays hand-rolled and tiny (a reducer + prop-getters), with the contract deliberately
shaped so a real `@zag-js/<x>` machine can be dropped behind it for a genuinely hard widget. **Reka UI**
(ex-Radix-Vue) and **Radix** are Vue-only / React-only respectively; oriUI's one core drives Vue and
Svelte from the same code.

### CSS / Tailwind kits — daisyUI

daisyUI is the ergonomic model for the CSS layer — semantic component classes over utilities. oriUI
matches that "just classes" feel but **without a Tailwind build dependency**: `.ori-*` are plain,
`@layer`-scoped classes that ship to htmx, Astro, or hand-written HTML as-is, themed by CSS custom
properties. And there's a real Vue component layer on top when a prototype graduates.

### Token & distribution systems — Open Props, Panda, shadcn/ui

**Open Props** is the spiritual sibling for the token side — design tokens as plain custom properties.
**Panda** is a build-time CSS-in-JS engine and **shadcn/ui** a copy-paste component registry; both are
great distribution models, but they're a *styling/build* system, not a layered component stack. oriUI's
theming needs no build step and no JS runtime — one attribute on `<html>` reskins everything.

### Full component libraries — Vuetify, PrimeVue, Element Plus

The batteries-included Vue kits. oriUI is lighter and unopinionated about styling: the **token contract
is the theming API**, so customization is CSS custom properties, not a framework-specific theme-config
object — and you can leave the styled layer entirely and keep the classes.

### Positioning — Floating UI

For overlays, oriUI leans on the **platform** (CSS Anchor Positioning + the Popover API) rather than a
JS positioner like **Floating UI** — zero-JS placement and collision-flip via `.ori-anchored`. Floating
UI remains the fallback model if a target needs to support browsers without anchor positioning.

## We mine, we don't race

oriUI is **not** trying to out-catalog daisyUI or out-adapt Ark. Those projects are reference points to
periodically **mine** — for API shape, a11y patterns, state names, class names — with findings landing
in the [backlog](https://github.com/markgrushevski/oriui/blob/main/IDEAS.md){rel="&#x22;nofollow&#x22;"}, never auto-adopted. The
bar for pulling anything in is one question: &#x2A;*does a real screen need it?** That keeps the surface
small, the tokens coherent, and the "scale without rewriting" promise honest.


# Get started

oriUI is a layered Vue 3 UI library. Install it and import only what you need.

## Install

```bash
npm install @oriui/vue
```

## Use a styled component

```vue
<script setup>
import { OriButton } from '@oriui/vue';
</script>

<template>
    <OriButton text="Click me" variant="tonal" color="primary" />
</template>
```

Import the stylesheet once, for example in your entry file:

```ts
import '@oriui/css';
```

That is all — components are themeable through design tokens, with light/dark and swappable
skins out of the box. See them live on the [component pages](https://oriui.vercel.app/components/button).

Need the CSS-only layer, the headless composables, or per-target setup? See
[Installation](https://oriui.vercel.app/overview/installation).


# Installation

oriUI is three layers in two packages. Install only the layer you need — they share one token
contract, so you can add another later without reworking what you built.

## Requirements

- **Node ≥ 22** and a bundler (Vite, webpack, Nuxt, …) for the Vue layers.
- **Vue 3.5+** for the styled and headless layers (the components use reactive props destructure).
- The **CSS layer needs none of the above** — it is a plain stylesheet and classes.

## Styled components — `@oriui/vue`

The full experience: ready Vue components, themed through tokens.

```bash
npm install @oriui/vue
```

Import a component where you use it, and the stylesheet **once** at your app entry:

```vue
<script setup lang="ts">
import { OriButton } from '@oriui/vue';
</script>

<template>
    <OriButton text="Click me" variant="tonal" color="primary" />
</template>
```

```ts
// main.ts — once, anywhere in your entry
import '@oriui/css';
```

That single import ships the tokens, the base styles, and every component's classes. Theme and skin
are then just attributes on `<html>` — see [Theming](https://oriui.vercel.app/guides/theming).

## The CSS layer — `@oriui/css`

No framework, no build step: ship the stylesheet and write `.ori-*` classes. This is how oriUI works
with **htmx, Astro, or plain HTML**.

From a bundler:

```ts
import '@oriui/css';
```

Or straight from a CDN, no install at all:

```html
<link rel="stylesheet" href="https://unpkg.com/@oriui/css/dist/styles.css" />
```

The full class reference and copy-pasteable markup live in [Using the CSS layer](https://oriui.vercel.app/guides/css) and on
each component page — flip any example to its **HTML** tab.

## The headless layer — `@oriui/headless/vue`

Behavior without markup: composables for open state, keyboard, focus, and ARIA. Installing `@oriui/vue`
already pulls this in transitively, but you can install it on its own:

```bash
npm install @oriui/headless
```

```ts
import { useDisclosure } from '@oriui/headless/vue';
```

Both `useDisclosure` and `useDialog` work out of the box on zero-dependency native engines — no
adapter, no extra install. `useDialog` runs on the native `<dialog>` element, so the focus trap,
`Esc`, `::backdrop`, top-layer and focus-return come from the platform via `showModal()`.

The swap is **optional**: register a custom engine per primitive only if you need it — for example a
Zag-backed adapter for a genuinely hard widget — without touching your markup:

```ts
// main.ts
import { OriHeadless } from '@oriui/headless/vue';
import { myDialog } from './headless/my-dialog'; // optional custom adapter

app.use(OriHeadless, { dialog: myDialog });
```

See [@oriui/headless](https://oriui.vercel.app/headless/core) for the contract and [useDialog](https://oriui.vercel.app/headless/use-dialog) for the full
control surface.

## Next

- [Get started](https://oriui.vercel.app/overview/get-started) — your first component, end to end.
- [Introduction](https://oriui.vercel.app/overview/introduction) — the layered idea and where each layer fits.


# Introduction

**oriUI** (織り, *ori* — "weaving") is a layered Vue 3 UI library. The idea in one line:
&#x2A;*prototype fast, scale without rewriting.** Start with ready-made styled components; when you need
more control, drop down to the behavior or the raw CSS — without throwing away your work, because
every layer is woven around the **same design tokens**.

## Three layers, one token contract

oriUI ships as three independently consumable layers. Use just one, or compose them:

| Layer        | Package               | What it gives you                                                                 |
| ------------ | --------------------- | --------------------------------------------------------------------------------- |
| **Styled**   | `@oriui/vue`          | Ready components — `<OriButton variant="tonal" />`. Behavior + style composed.    |
| **Headless** | `@oriui/headless/vue` | Behavior only — composables for state, keyboard, focus, and ARIA. You own markup. |
| **CSS**      | `@oriui/css`          | Standalone `.ori-*` classes + tokens. No Vue, no build step, no Tailwind.         |

These are not three separate products — they are **three depths of one system**. A styled `OriButton`
is the CSS layer's `.ori-button` classes plus token theming; a styled `OriDialog` is the headless
`useDialog` plus markup plus those same classes. Reach for the depth a screen needs, and the tokens
keep everything visually consistent.

## What makes it different

- **Zero-runtime theming.** Skins, light/dark, sizes, and variants are CSS custom properties —
  switching them is a class or attribute toggle, never JavaScript. See [Design tokens](https://oriui.vercel.app/guides/design-tokens).
- **No Tailwind dependency.** The CSS layer is plain, prefixed, `@layer`-scoped classes you can ship to
  htmx, Astro, or hand-written HTML. Tailwind is an *optional* preset, not a requirement.
- **Swappable behavior.** The headless layer runs on a tiny zero-dependency native engine by default,
  and you can swap in a battle-tested one (Zag) per primitive behind one contract — without touching
  your markup. See [@oriui/headless](https://oriui.vercel.app/headless/core).
- **Accessibility is structural.** State lives in real attributes (`disabled`, `aria-busy`,
  `aria-expanded`), color pairs are contrast-checked in CI, and focus rings ride `:focus-visible`.
  See [Accessibility](https://oriui.vercel.app/overview/accessibility).

## How it compares

oriUI deliberately sits between the usual categories:

- **vs. Tailwind component kits (DaisyUI, …)** — the same "just classes" ergonomics for the CSS layer,
  but **without** a Tailwind build dependency, and with a real Vue component layer on top when you want
  it.
- **vs. headless libraries (Radix / Reka, Headless UI)** — oriUI has a headless layer too, but it is
  one depth of a stack, not the whole story: stay styled, go headless, or drop to CSS — all reusing the
  same tokens.
- **vs. full component libraries (Vuetify, PrimeVue)** — lighter and unopinionated about styling: the
  token contract *is* the theming API, so customization is CSS, not a framework-specific config object.

For a deeper, library-by-library take, see [Idea & comparisons](https://oriui.vercel.app/overview/comparisons).

## Where each layer fits

The CSS layer works **everywhere**; the styled layer is Vue, and the headless layer ships **Vue and
Svelte** adapters over one core. See the full [Applicability matrix](https://oriui.vercel.app/overview/applicability) for the
per-environment breakdown (Vue / Svelte / Astro / htmx, plus the Nuxt / SvelteKit / Capacitor / Electron
shells). A vanilla / htmx headless adapter is still planned.

## Status

oriUI is in **alpha** (the `1.0.0-alpha.*` line). The token contract, the CSS layer, and the styled components
under [Components](https://oriui.vercel.app/components/button) are solid enough to build with; the catalog is still growing and
the public API may shift before `1.0`.

## Next

- [Get started](https://oriui.vercel.app/overview/get-started) — a styled component on screen in a minute.
- [Installation](https://oriui.vercel.app/overview/installation) — install each layer, for each target.
- [Accessibility](https://oriui.vercel.app/overview/accessibility) — the a11y guarantees, and where they come from.