# AdiaUI — Components

Every primitive is `<name>-ui`. 125 primitives + 4 app shells are
registered by `everything.min.js`. Reach for a tag before hand-building.
Full per-component docs + live demos: https://ui-kit.exe.xyz/site/components/<name>

## Picking a component

```
What are you placing?
├─ A whole app frame ........... a SHELL (admin / chat / editor / simple)
├─ A box grouping content ...... <card-ui>  (header / section / footer slots)
├─ Horizontal/vertical layout .. <row-ui> / <col-ui>  (gap="1".."6")
├─ A labelled input ............ <field-ui label=""> wrapping the control
├─ An action ................... <button-ui text="" variant="">
├─ Tabular data ................ <table-ui>   |  a list ... <list-ui>
├─ A metric/KPI ................ <stat-ui value="" label="">
├─ Inline status ............... <badge-ui text=""> | <tag-ui> | <alert-ui>
├─ Sidebar navigation .......... <nav-ui> + <nav-item-ui icon="" text="">
└─ Transient/overlay ........... <modal-ui> | <drawer-ui> | <toast-ui> | <tooltip-ui>
```

## Vocabulary by group

| Group | Tags |
|---|---|
| **Layout** | `row-ui` `col-ui` `grid-ui` `page-ui` `card-ui` `pane-ui` `block-ui` `divider-ui` `stack-ui` `section`(slot) |
| **Text** | `text-ui` `link-ui` `badge-ui` `tag-ui` `icon-ui` `code-ui` `kbd-ui` `mark-ui` `blockquote-ui` `relative-time-ui` `number-format-ui` |
| **Forms** | `input-ui` `textarea-ui` `select-ui` `combobox-ui` `check-ui` `radio-ui` `switch-ui` `slider-ui` `range-ui` `search-ui` `otp-input-ui` `tags-input-ui` `segmented-ui` `rating-ui` `color-input-ui` `field-ui` `fields-ui` `button-ui` |
| **Data** | `table-ui` `list-ui` `description-list-ui` `stat-ui` `chart-ui` `heatmap-ui` `timeline-ui` `feed-ui` `pagination-ui` `progress-ui` `progress-row-ui` `step-progress-ui` |
| **Feedback / overlay** | `alert-ui` `inline-message-ui` `toast-ui` `modal-ui` `drawer-ui` `tooltip-ui` `popover-ui` `empty-state-ui` `skeleton-ui` `spinner-ui` `loading-overlay-ui` |
| **Navigation** | `nav-ui` `nav-item-ui` `nav-group-ui` `menu-ui` `tabs-ui` `breadcrumb-ui` `command-ui` `context-menu-ui` `toolbar-ui` `segment-ui` `pagination-ui` `toc-ui` `skip-nav-ui` |
| **Media / misc** | `avatar-ui` `image-ui` `qr-code-ui` `swatch-ui` `swiper-ui` `accordion-ui` `stepper-ui` `tour-ui` `inline-edit-ui` `calendar-picker-ui` `date-range-picker-ui` `datetime-picker-ui` `time-picker-ui` |
| **Agent surfaces** | `agent-reasoning-ui` `agent-trace-ui` `agent-suggestions-ui` `agent-questions-ui` `agent-feedback-bar-ui` `agent-artifact-ui` `chat-thread-ui` |
| **Shells** | `admin-shell` `chat-shell` `editor-shell` `simple-shell` (+ their `admin-sidebar` / `admin-topbar` / `page-ui` / … children) |

## Component rules + examples

### `<button-ui>` — label via `text=`
Two independent attributes:
- **`variant`** (visual style): `solid` (default) · `outline` · `ghost`. `primary` is an alias of `solid`.
- **`color`** (semantic intent, composes with variant): `default` · `accent` · `info` · `success` · `warning` · `danger`.
- **`size`**: `sm` `md` `lg`. For a whole region denser or larger than the default, set `scale="ui-sm" … "content-lg"` on an ancestor — scale picks the table, size picks the row (six tiers; see the Density section below).

```html
<!-- CORRECT — variant + color compose; size is independent -->
<button-ui text="Save" variant="primary"></button-ui>
<button-ui text="Delete" variant="primary" color="danger"></button-ui>   <!-- solid danger -->
<button-ui text="Cancel"></button-ui>
<!-- WRONG — label is ignored; renders an empty button -->
<button-ui variant="primary">Save</button-ui>
<!-- WRONG — danger is a COLOR, not a variant; this gets no danger styling -->
<button-ui text="Delete" variant="danger"></button-ui>
```

### `<card-ui>` — header / section / footer slots
Body content MUST be inside `<section>`, or it loses inset padding.

```html
<!-- CORRECT -->
<card-ui>
  <header><h3>Plan</h3></header>
  <section><text-ui>Pro — $29/mo</text-ui></section>
  <footer><button-ui text="Upgrade" variant="primary"></button-ui></footer>
</card-ui>
<!-- WRONG — body bleeds to the edges -->
<card-ui><text-ui>Pro — $29/mo</text-ui></card-ui>
```

### `<field-ui>` — label + control + validation row
Wrap a single control. For 2+ `<radio-ui>`/`<check-ui>`, wrap them in `<col-ui gap="1">` inside the field, or they overlap.

```html
<field-ui label="Email"><input-ui type="email" required></input-ui></field-ui>
<field-ui label="Plan">
  <col-ui gap="1">
    <radio-ui name="plan" label="Free"></radio-ui>
    <radio-ui name="plan" label="Pro"></radio-ui>
  </col-ui>
</field-ui>
```

### `<nav-ui>` — sidebar navigation (NOT `<menu-ui>`)
```html
<nav-ui>
  <nav-item-ui icon="house" text="Home" selected></nav-item-ui>
  <nav-item-ui icon="gear" text="Settings"></nav-item-ui>
</nav-ui>
```
`<menu-ui>` is only for popover/dropdown action menus.

### `<stat-ui>` — metric/KPI
```html
<stat-ui value="$12.4k" label="Revenue" trend="up" change="+8%"></stat-ui>
```

### `<table-ui>` — never author `<tr>`/`<td>` by hand
The HTML parser strips table tags inside custom elements. Provide columns + data via attributes/JSON or `<col-def>`; don't write raw `<thead>/<tbody>/<tr>`.

### `<modal-ui>` / `<drawer-ui>` — `[text]` + `slot="footer"`
`<modal-ui>` titles via a `[text]`/heading attr and footer via `slot="footer"` — it does NOT use card-ui's header/section/footer. Check the live demo before authoring.

## App shell skeleton

```html
<admin-shell mode="rounded borderless">
  <admin-sidebar slot="leading" resizable collapsible>
    <admin-topbar slot="header"><span slot="heading">My App</span></admin-topbar>
    <section>
      <nav-ui>
        <nav-item-ui icon="house" text="Home" selected></nav-item-ui>
        <nav-item-ui icon="chart-bar" text="Reports"></nav-item-ui>
      </nav-ui>
    </section>
  </admin-sidebar>
  <admin-content>
    <admin-topbar><breadcrumb-ui><span>Dashboard</span></breadcrumb-ui></admin-topbar>
    <page-scroll>
      <page-ui band max-width="xwide" padding="10">
        <header-ui>
          <span slot="heading">Dashboard</span>
          <span slot="description">Welcome back.</span>
          <button-ui slot="action" text="Share" size="sm"></button-ui>
        </header-ui>
        <section-ui>
          <row-ui gap="3">
            <card-ui><section><stat-ui value="$12.4k" label="Revenue"></stat-ui></section></card-ui>
            <card-ui><section><stat-ui value="1,204" label="Users"></stat-ui></section></card-ui>
          </row-ui>
        </section-ui>
      </page-ui>
    </page-scroll>
  </admin-content>
</admin-shell>
```

Icon names (`icon="…"` / `<icon-ui name="…">`) are Phosphor names:
`house` `gear` `magnifying-glass` `plus` `trash` `chart-bar` `bell` `user`.