@momoi-labs/kiso 0.1.0

package/kiso/docs/components/table.md

@@ -0,0 +1,255 @@
+# Table / DataTable
+
+A dense, scannable grid of records. Rows are entities; columns are
+comparable fields. DataTable is the same component with sorting, filtering
+composition, pagination, and row selection switched on.
+
+## Purpose
+
+Table is the primary surface for Momoi's data-heavy products: replicas,
+queries, metrics series, config keys, log lines. The person scans, compares,
+sorts, selects, and acts on many similar items.
+
+User stories #3 and #21.
+
+**Table** is the structural grid (header, body, optional footer).
+**DataTable** is Table plus the interactive behaviors listed below. Prefer the
+name DataTable in product UI copy when those behaviors are present; the
+spec is one component.
+
+### Composition
+
+| Concern | Compose with | Notes |
+| --- | --- | --- |
+| Loading rows | [Skeleton](skeleton.md) | Skeleton *text* cells inside rows; keep chrome. |
+| Empty dataset | [EmptyState](empty-state.md) | Replaces the body; keep column headers when helpful. |
+| Error loading | [Alert](alert.md) | Above or in place of the body; retry via Button. |
+| Filter visible rows | [Search](search.md) | Standalone; not built into Table. User story #9. |
+| Page through known sets | [Pagination](pagination.md) | Known total / page size. User story #11. |
+| Row actions | [DropdownMenu](dropdown-menu.md) or [IconButton](icon-button.md) | Per-row contextual actions. |
+| Bulk actions | [Button](button.md) in a selection toolbar | Appear when one or more rows are selected. |
+
+Do not invent a second "table kit". Loading, empty, and error are *states of
+this component*, expressed by composing the pieces above.
+
+## Anatomy
+
+```
+DataTable
+├── Toolbar (optional)
+│   ├── Search (filter; optional)
+│   ├── Filters / view controls (optional)
+│   └── Bulk action Buttons (when rows selected)
+├── Table
+│   ├── Caption (optional; accessible name for the table)
+│   ├── Header (thead)
+│   │   └── HeaderRow
+│   │       ├── SelectionHeaderCell (optional checkbox)
+│   │       └── ColumnHeaderCell × N
+│   │           ├── Sort control (optional)
+│   │           └── Resize handle (optional)
+│   ├── Body (tbody)
+│   │   ├── DataRow × N
+│   │   │   ├── SelectionCell (optional checkbox)
+│   │   │   ├── DataCell × N
+│   │   │   └── RowActionsCell (optional)
+│   │   ├── SkeletonRow × N (loading only)
+│   │   └── Empty / Error region (replaces DataRows)
+│   └── Footer (tfoot; optional totals / summary)
+└── Pagination (optional; below the table)
+```
+
+- **Caption.** Visible or visually hidden. Required accessible name for the
+  table (`<caption>` or `aria-labelledby`).
+- **ColumnHeaderCell.** Column title. Sortable headers are buttons (or have a
+  nested button), not plain text.
+- **DataCell.** One value. Prefer plain text; [Badge](badge.md) for status;
+  [Link](link.md) only when the cell navigates.
+- **SelectionCell.** [Checkbox](checkbox.md) for multi-select membership.
+- **RowActionsCell.** Usually a DropdownMenu trigger (kebab / more), not a
+  pile of Buttons.
+- **Toolbar.** Outside the `<table>`. Owns Search, filters, and bulk actions.
+- **Pagination.** Sibling below the table, not a table row (navigation slice).
+
+## Variants
+
+| Variant | Behavior |
+| --- | --- |
+| `plain` | Structural table only: no sort, selection, or pagination. Rare; prefer DataTable. |
+| `data` (default) | Sort, optional row selection, Search composition, Pagination when the set is paged. |
+
+Density is a presentation choice, not a named color variant:
+
+| Density | Use | Tokens |
+| --- | --- | --- |
+| `comfortable` | Default for most product tables. | Cell padding `--spacing-sm` block, `--spacing-md` inline. All five body typography properties. |
+| `compact` | Ops dashboards, wide schemas, log-like grids. | Cell padding `--spacing-xs` block, `--spacing-sm` inline. Same five body typography properties (do not shrink below readable). |
+
+Header background `--color-surface`. Body rows `--color-surface` on
+`--color-background` page canvas, or zebra with alternating
+`--color-elevated-surface` / `--color-surface` when it aids scanning — never
+raw stripes. Borders `--color-border`. Text `--color-foreground`; secondary
+cell metadata `--color-muted-foreground`.
+
+### Column behaviors
+
+| Behavior | Spec |
+| --- | --- |
+| **Sortable** | Header exposes sort control. One primary sort column at a time unless the product explicitly supports multi-sort (rare; document in the screen). Cycle: unsorted → ascending → descending → unsorted (or omit unsorted if a default sort is required). |
+| **Sticky header** | Header stays visible while the body scrolls inside a scrollport. Use when the table is taller than the viewport. Sticky uses the same `--color-surface` as the header so rows do not show through. |
+| **Column resize** | Optional. Drag handle on the header edge. Persist width in product state when useful. Minimum width must keep the header label readable; do not specify px — use ch, the label typography properties, and `--spacing-sm`. |
+| **Virtualization** | Guidance, not a separate variant. For large client-side sets (thousands of rows), virtualize the body so only visible rows mount. Keep header, selection model, and keyboard navigation correct. Prefer server-side Pagination when the dataset is known and paged; virtualize when scrolling one large loaded set. |
+
+Filtering is **not** a Table variant. [Search](search.md) (and optional
+filter chips) live in the Toolbar and feed the data query or client filter.
+
+## Sizes
+
+Table has no `sm` / `md` / `lg` control scale like Button. Size comes from:
+
+| Axis | Token / rule |
+| --- | --- |
+| Type | All five property-qualified body typography tokens for cells; all five property-qualified label typography tokens for headers. |
+| Cell padding | Density table above (`--spacing-xs`, `--spacing-sm`, and `--spacing-md`). |
+| Radius | Outer wrapper `--radius-md` when the table sits in a framed panel; internal cells are square. |
+| Checkbox / IconButton in cells | `sm` controls so row height stays dense. |
+
+Do not invent a fourth density. Do not set row height in raw pixels.
+
+## States
+
+The table as a whole has mutually exclusive *data* states. Interactive
+chrome (headers, checkboxes, row actions) still has control states.
+
+### Data states (user story #3)
+
+| State | Presentation | Behavior |
+| --- | --- | --- |
+| **Loading** | Keep header (and toolbar if already meaningful). Body shows Skeleton rows matching column count and approximate page size. Region `aria-busy="true"` with a polite status ("Loading replicas"). | Do not show EmptyState or stale rows next to Skeletons. Do not disable the whole page. |
+| **Empty** | Body replaced by [EmptyState](empty-state.md). Headers may remain so column meaning is clear. | Empty means *zero matching records*, not "still loading". If Search/filters are active, EmptyState copy should say no matches and offer clear-filters when applicable. |
+| **Error** | Remove Skeletons. Show [Alert](alert.md) `error` with retry. Optionally keep headers. | Do not leave an empty table that looks like success. After retry, return to loading then populated/empty. |
+| **Populated** | DataRows + optional Pagination. | Default happy path. |
+
+Loading vs empty vs error must never be ambiguous: Skeleton ≠ EmptyState ≠
+Alert.
+
+### Interaction states
+
+| State | Where | Behavior |
+| --- | --- | --- |
+| default | Rows, headers, cells | Interactive affordances at rest. |
+| hover | DataRow, sortable header, resize handle | Quiet emphasis (`--color-elevated-surface` or border). Cursor indicates affordance. Transition `--motion-duration-fast` / `--motion-easing-standard`. |
+| focus | Sort button, Checkbox, row action, Pagination | Visible `--color-focus` ring. Row focus for roving tabindex patterns follows the keyboard model below. |
+| active | Sort control, Checkbox, menu trigger | Pressed / open as for those controls. |
+| disabled | Individual Checkbox, sort, or action | Native/disabled semantics with `--color-disabled`. Prefer hiding irrelevant actions over a sea of disabled controls. |
+| loading | Whole table data state, or a single row action | Table-level: Skeleton rows. Row action: Button/IconButton loading ([Spinner](spinner.md)). |
+| selected | DataRow | One or more rows selected. Background `--color-elevated-surface` or a left accent border using `--color-primary` (not a filled primary row — primary is a text/action role). Selection Header Checkbox reflects none / some / all. |
+| sorted | ColumnHeaderCell | `aria-sort="ascending"` \| `"descending"` \| `"none"`. Visible sort indicator (icon); do not rely on color alone. |
+
+### Sorting
+
+- Sort changes the **order of the current result set** (client) or the
+  **query** (server). Document which on the screen.
+- Announce sort changes politely when they are not obvious from focus
+  ("Sorted by name, ascending").
+- Unsortable columns have no sort control and no `aria-sort`.
+
+### Pagination
+
+- Use Pagination when the dataset size is known or page-shaped (user story
+  #11). Infinite scroll is a pattern (Epic #4), not a Table state — and is
+  usually wrong for ops tables where "page 7 of 40" matters.
+- Changing page keeps selection policy explicit: either clear selection or
+  keep a cross-page selection model — pick one per product surface and say so.
+- While a page fetch runs, prefer Skeleton rows inside the body over blanking
+  the chrome.
+
+### Row selection
+
+- Multi-select via Checkbox in the leading column. Header Checkbox toggles
+  all rows **on the current page** (or all loaded rows if virtualized without
+  pages) unless the product defines "select all matching query" — that needs
+  explicit copy and a confirmation.
+- Selected count appears in the Toolbar ("3 selected") with bulk actions.
+- Single-select (radio-like) is rare; if needed, one selected row at a time
+  and no Header Checkbox.
+- Do not use row click alone for selection when the row also navigates; keep
+  Checkbox as the selection affordance and Link/Button for navigation/actions.
+
+## Accessibility
+
+- Use a real `<table>` with `<thead>`, `<tbody>`, and `<th scope="col">`
+  (and `scope="row"` when row headers exist). Do not fake a table with CSS
+  grids for tabular data.
+- Accessible name via `<caption>` or `aria-labelledby`.
+- Sortable headers: the sort control is a button; set `aria-sort` on the
+  `<th>`.
+- Selection Checkboxes: each has an accessible name ("Select row {name}" /
+  "Select all rows on this page"). Indeterminate Header Checkbox uses the
+  Checkbox indeterminate state.
+- Loading: `aria-busy="true"` on the table region; Skeletons `aria-hidden`.
+  See [Skeleton](skeleton.md).
+- Empty: EmptyState is the content; do not leave an empty `<tbody>` with no
+  explanation.
+- Error Alert: follow [Alert](alert.md) focus guidance on failure after a
+  user-initiated refresh.
+- Do not put essential meaning in zebra color alone.
+- Sticky header: ensure focus order still follows visual order; do not trap
+  focus under a sticky layer.
+
+### Keyboard
+
+| Key | Action |
+| --- | --- |
+| `Tab` / `Shift+Tab` | Move through interactive controls: toolbar, sort buttons, Checkboxes, row actions, Pagination. |
+| `Enter` / `Space` | Activate the focused control (sort, Checkbox, menu trigger, Button). |
+| Arrow keys | Within DropdownMenu / composite widgets per those specs. Optional grid navigation inside the table body is allowed when implemented as a composite; if so, document `aria-activedescendant` or roving tabindex and keep one tab stop into the grid. |
+| `Escape` | Closes an open row DropdownMenu; does not clear selection unless the product defines that. |
+
+## When to use
+
+- Many similar records with comparable fields (user story #21).
+- The person needs to sort, page, select, or scan columns.
+- Ops and data tools: databases, jobs, configs, metrics inventories.
+
+## When NOT to use
+
+- **One or two fields about a single entity.** Use a definition list, Card,
+  or PageHeader — not a one-row table.
+- **Hierarchical location.** Breadcrumb (navigation slice).
+- **Free-form layout.** Cards or a custom panel; tables imply comparison.
+- **Charts.** Deferred to v2; do not stretch Table into a graph.
+- **Global actions / jump-to.** [CommandPalette](command-palette.md), not a
+  table of commands.
+- **Filtering UI embedded as magic columns.** Use Search + filters in the
+  Toolbar.
+
+## Tokens
+
+Consume only semantic roles: `--color-background`, `--color-surface`,
+`--color-elevated-surface`, `--color-foreground`, `--color-muted-foreground`,
+`--color-border`, `--color-primary`, `--color-focus`, `--color-disabled`,
+`--color-danger` (via Alert on error); the five property-qualified body and
+label typography tokens; `--spacing-xs`, `--spacing-sm`, `--spacing-md`;
+`--radius-md`; `--motion-duration-fast`; and `--motion-easing-standard`. No
+palette primitives, no raw hex/px.
+
+## Radix/shadcn mapping
+
+There is no Radix Table primitive for the grid itself. Behavior for menus and
+checkboxes comes from those primitives; the table is semantic HTML.
+
+| Kiso | Reference |
+| --- | --- |
+| Markup and structure | shadcn [Table](https://ui.shadcn.com/docs/components/table) (`Table`, `TableHeader`, `TableBody`, `TableRow`, `TableHead`, `TableCell`, `TableCaption`, `TableFooter`) |
+| DataTable patterns (sort, selection, toolbar) | shadcn [Data Table](https://ui.shadcn.com/docs/components/data-table) (TanStack Table examples) — adopt interaction patterns; restyle with Kiso tokens |
+| Row / header Checkbox | Radix / shadcn Checkbox → Kiso [Checkbox](checkbox.md) |
+| Row actions menu | Radix / shadcn Dropdown Menu → Kiso [DropdownMenu](dropdown-menu.md) |
+| Loading rows | shadcn Skeleton "Table" example → Kiso [Skeleton](skeleton.md) |
+| Empty | Compose [EmptyState](empty-state.md); do not use a blank shadcn row |
+| Pagination | Kiso [Pagination](pagination.md), using shadcn Pagination as its structural reference |
+
+Map shadcn Data Table examples by *intent*: sorting state, row selection,
+toolbar bulk actions. Replace every utility color and pixel size with Kiso
+semantic tokens. Do not copy example row heights or `h-10` / `w-[100px]`
+literals.

package/kiso/docs/components/tabs.md

@@ -0,0 +1,69 @@
+# Tabs
+
+Switches between related panels within the same page.
+
+## Purpose
+
+Tabs organize peer views without changing the person's hierarchical location.
+They answer “which view of this page?”; [Breadcrumb](breadcrumb.md) answers
+“where am I in the product?”
+
+## Anatomy
+
+```
+Tabs
+├── TabList
+│   └── Tab (one or more)
+└── TabPanel (one per Tab)
+```
+
+Tabs use `--color-foreground`, `--color-muted-foreground`,
+`--color-primary`, `--color-border`, and `--color-focus`; `--spacing-sm` block
+and `--spacing-md` inline tab padding; the five property-qualified label
+typography tokens; `--motion-duration-fast`; and `--motion-easing-standard`.
+
+## Variants
+
+Two orientations: horizontal (default) and vertical. Orientation changes the
+TabList layout and arrow-key axis, not the selection or panel semantics.
+
+## Sizes
+
+One size. Tabs use a single label and spacing treatment; do not add compact or
+large scales. The host layout controls available panel width.
+
+## States
+
+| State | Behavior |
+| --- | --- |
+| default | One Tab is selected and its panel is visible. |
+| hover | An enabled Tab signals selection availability. |
+| focus | Focused Tab shows `--color-focus`; focus and selection may differ during keyboard movement. |
+| active | Selected Tab has `aria-selected="true"` and controls the visible panel. |
+| disabled | Tab remains identifiable with `aria-disabled="true"` and `--color-disabled`, but cannot be selected. |
+
+## Accessibility
+
+Use `tablist`, `tab`, and `tabpanel` roles with `aria-controls` /
+`aria-labelledby`. One Tab is in the tab sequence. Arrow keys move between
+Tabs; `Home`/`End` move to the first/last; `Tab` enters the active panel.
+Prefer automatic activation when panel changes are immediate; use
+`Enter`/`Space` for manual activation when loading is costly. Orientation
+determines the arrow-key axis.
+
+## When to use
+
+- Two or more peer panels within one page or object.
+- Content where switching is frequent and labels are short.
+
+## When NOT to use
+
+- Product hierarchy or ancestors; use Breadcrumb.
+- Routes that need independent history/bookmarking unless the selected Tab is
+  encoded in the URL without losing tab semantics.
+- A sequential workflow; use explicit steps instead.
+
+## Radix/shadcn mapping
+
+Maps to Radix Tabs / shadcn Tabs (`Root`, `List`, `Trigger`, `Content`). Keep
+Radix keyboard behavior and restyle only with Kiso semantic tokens.

package/kiso/docs/components/textarea.md

@@ -0,0 +1,91 @@
+# Textarea
+
+## Purpose
+
+Textarea collects multi-line free-form text. It is for content whose line
+breaks or length make a single-line Input inappropriate.
+
+## Anatomy
+
+1. **Native textarea** — editable multi-line value.
+2. **Resize affordance (optional)** — browser-provided, usually vertical only.
+3. **Character count (optional)** — supporting status when a meaningful limit
+   exists; it does not replace validation.
+4. **Loading affordance (optional)** — Spinner that does not cover the value.
+
+Label, HelperText, and ValidationMessage are composed by FormField.
+
+## Variants
+
+- **Default** — multi-line entry with a useful initial row count.
+- **Auto-growing** — expands to content up to a documented maximum, without
+  causing uncontrolled page jumps.
+- **Fixed-height** — scrolls internally when layout stability is essential.
+- **Read-only** — focusable and selectable, but not editable.
+
+## Sizes
+
+- **Small** — compact notes with a small expected amount of text.
+- **Medium** — default.
+- **Large** — longer authored content.
+
+Size controls minimum block size and padding through semantic tokens. Authors
+may set a content-driven `rows` value; do not encode raw dimensions in the
+component contract.
+
+## States
+
+| State | Behavior |
+| --- | --- |
+| Default | Surface, text, border, and placeholder use their semantic color roles. |
+| Hover | Border emphasis may increase without moving content. |
+| Focus | Visible `--color-focus` ring around the whole control. |
+| Active | Native editing, selection, scrolling, and resize behavior. |
+| Disabled | Native `disabled`; unavailable and uses `--color-disabled`. |
+| Loading | Value remains legible; shows status and avoids resize/layout shifts. |
+| Error | `aria-invalid="true"`, `--color-danger` treatment, and linked ValidationMessage. |
+
+Loading communicates ongoing work; disabled communicates unavailability. Use
+both only when the control truly cannot accept edits during that work, and keep
+the loading status independently perceivable.
+
+## Accessibility
+
+- Associate Label using matching `for` and `id`.
+- Use native `textarea` behavior and appropriate `name`, `autocomplete`,
+  `required`, `minlength`, and `maxlength` attributes.
+- Link HelperText, character-count guidance, and ValidationMessage with
+  `aria-describedby`; add `aria-invalid` only for an invalid value.
+- Announce a changing character count only near a limit and without noisy
+  updates on every keystroke.
+- Preserve standard keyboard editing, selection, undo, paste, scrolling, and
+  platform shortcuts. `Enter` inserts a line break; do not submit implicitly.
+
+## When to use
+
+- For descriptions, notes, queries, or other multi-line text.
+- When line breaks are meaningful or expected.
+- In FormField when contextual help or validation is present.
+
+## When NOT to use
+
+- Do not use for a single short value; use Input.
+- Do not use as a code editor when syntax, line numbers, or editor commands are
+  required; that needs a specialized component.
+- Do not prevent paste or ordinary keyboard editing.
+- Do not use placeholder text as the only label or instruction.
+
+## Tokens
+
+Use the same exact mapping as Input: `--color-surface`, `--color-foreground`,
+`--color-subtle-foreground`, `--color-border`, `--color-focus`,
+`--color-disabled`, `--color-danger`; all five body typography properties;
+`--spacing-sm` block and `--spacing-md` inline padding; `--radius-md`;
+`--motion-duration-fast`; and `--motion-easing-standard`. No primitive colors
+or raw values.
+
+## Radix/shadcn mapping
+
+Maps to [shadcn/ui Textarea](https://ui.shadcn.com/docs/components/textarea),
+which styles native `textarea`. Radix has no Textarea primitive; Kiso preserves
+the native element's interaction and accessibility model.

package/kiso/docs/components/toast.md

@@ -0,0 +1,80 @@
+# Toast
+
+A transient system notification that confirms an outcome without blocking the
+current task.
+
+## Purpose
+
+Toast reports brief, non-essential outcomes such as “Copied” or “Saved”. It is
+time-limited and appears outside page flow. [Alert](alert.md) is persistent,
+in-page, and appropriate when the condition or recovery must remain visible.
+
+## Anatomy
+
+```
+Toast Provider
+├── Viewport
+└── Toast
+    ├── Title (required)
+    ├── Description (optional)
+    ├── Action (optional)
+    └── Dismiss (optional IconButton)
+```
+
+Use `--color-elevated-surface`, `--color-foreground`,
+`--color-muted-foreground`, `--color-border`, `--color-info`, `--color-success`,
+`--color-warning`, or `--color-danger` where severity must be shown;
+`--spacing-md` padding; `--spacing-sm` gap; `--radius-md`; and `--shadow-md`.
+
+## Variants
+
+Four semantic variants: `neutral` (default), `success`, `warning`, and `error`.
+Status variants change the announcement urgency and semantic accent only; they
+do not turn the whole Toast into a status-colored surface.
+
+## Sizes
+
+One compact size. Toast has no `sm` / `lg` scales; title, optional description,
+and at most one Action must remain brief enough for the standard treatment.
+
+## States
+
+| State | Behavior |
+| --- | --- |
+| closed (default) | Not present in the viewport. |
+| open | Visible long enough to read; polite announcement for normal notices. |
+| hover/focus | Pause auto-dismiss while pointer or keyboard focus is within. |
+| active | Action runs once; dismiss follows when appropriate. |
+| disabled | Toast is never disabled; an unavailable Action follows Button rules. |
+| loading | Do not toast indefinite progress; show progress in the initiating region. |
+| error | Only for brief, already recoverable failures; persistent/blocking errors are Alert. |
+
+## Accessibility
+
+Use a managed live region: `role="status"` / polite for ordinary outcomes and
+assertive announcement only for urgent errors. Do not move focus to a newly
+appearing Toast. `F8` may move focus to the Toast viewport (Radix convention);
+`Tab` reaches Action/Dismiss after focus enters it; `Escape` dismisses. Pause
+the timer on hover, focus, and page blur. Never make Toast the only copy of an
+essential error, completed record, or required recovery step.
+
+## When to use
+
+- Brief confirmation of a completed, non-blocking action.
+- A background event whose details remain available elsewhere.
+- An optional undo action that is also recoverable through normal product UI.
+
+## When NOT to use
+
+- A condition that must remain visible or blocks progress; use Alert.
+- Field validation; use ValidationMessage.
+- A confirmation that requires a decision; use Modal/Dialog.
+- Long content, multiple actions, or ongoing progress.
+
+## Radix/shadcn mapping
+
+Behavior maps to Radix Toast (`Provider`, `Viewport`, `Root`, `Title`,
+`Description`, `Action`, `Close`). shadcn currently recommends Sonner; it is
+acceptable when configured to preserve the live-region, pause, keyboard, and
+semantic-token rules above. Do not copy library hard-coded colors or timing
+values.

package/kiso/docs/components/tooltip.md

@@ -0,0 +1,162 @@
+# Tooltip
+
+A short, non-essential hint on hover or keyboard focus. Progressive
+enhancement only.
+
+## Purpose
+
+Tooltip clarifies a control the person can already use: the accessible name
+of an [IconButton](icon-button.md), a keyboard shortcut, an abbreviated
+column header. If the person cannot succeed without the Tooltip, the UI is
+wrong — put the information on the screen.
+
+User story #10: **do not use Tooltip on touch**, and **never put essential
+information in a Tooltip**.
+
+Tooltip is not [Alert](alert.md), not field help (HelperText), and not a
+rich overlay (Popover, later slice).
+
+## Anatomy
+
+```
+Tooltip.Provider   (once per app)
+└── Tooltip
+    ├── Trigger (the existing control: usually IconButton, sometimes a
+    │   truncated string)
+    └── Content (short text; optional keyboard hint)
+        └── Arrow (optional; skip if it adds noise)
+```
+
+- **Trigger.** Almost always an existing control that already has a name.
+  Tooltip does not *become* the name.
+- **Content.** A few words that match or slightly expand the name. Optional
+  shortcut, written as the keys themselves ("⌘K"), not as a sentence.
+- **Arrow.** Optional. Prefer none; alignment and `--spacing-xs` offset are
+  enough.
+
+## Variants
+
+One variant. No color-coded "error tooltips". Errors are ValidationMessage
+or Alert, and they are essential — they cannot live in a Tooltip.
+
+| Treatment | Tokens |
+| --- | --- |
+| Default | Background `--color-elevated-surface`, text `--color-foreground`, border `--color-border`, radius `--radius-sm`, padding `--spacing-xs` `--spacing-sm`, all five property-qualified metadata typography tokens, shadow `--shadow-sm`. |
+
+Keyboard shortcut inside Content uses `--type-role-code-font-family`,
+`--type-role-code-font-size`, `--type-role-code-font-weight`,
+`--type-role-code-letter-spacing`, and `--type-role-code-line-height`.
+
+Placement: `top` by default, flip on collision (`side` + `align` from the
+Radix reference). Offset `--spacing-xs` from the trigger. Do not specify
+the offset in raw pixels.
+
+## Sizes
+
+One size: `--type-role-metadata-font-family`, `--type-role-metadata-font-size`,
+`--type-role-metadata-font-weight`, `--type-role-metadata-letter-spacing`, and
+`--type-role-metadata-line-height`. Content wraps; max width is a reading
+measure of a short phrase (about three or four words per line, a couple of
+lines). If you need a paragraph, you need HelperText, Alert, or Popover.
+
+## States
+
+| State | Behavior |
+| --- | --- |
+| closed (default) | Content not shown. Trigger is usable. |
+| delayed-open | Pointer hover still; waiting the delay. |
+| open | Content visible. |
+| hover (trigger) | Starts the open delay. |
+| focus (trigger) | Opens without the pointer delay (keyboard). |
+| active (trigger) | Activation **closes** the Tooltip and runs the control. |
+| disabled trigger | Native disabled controls do not hover. If a disabled [Button](button.md) must explain *why*, that explanation is adjacent copy or HelperText — **not** a Tooltip on a wrapper span. Disabled-why is essential, so Tooltip is the wrong place. |
+| loading | N/A for Tooltip itself. |
+| error | N/A. |
+
+**Touch / coarse pointer:** do not open. `pointer: coarse` (and the absence
+of hover) means the Content never appears. The trigger must remain fully
+usable. This is a hard rule, not a nice-to-have.
+
+**Delay:** follow the Radix Provider default (open delay, skip-delay when
+moving between triggers). Do not open instantly on pointer hover — that
+flickers. Keyboard focus opens without the pointer delay.
+
+Motion: fade/scale with `--motion-duration-fast` and
+`--motion-easing-standard`. Reduced motion: show and hide with no travel.
+
+## Accessibility
+
+- Content has `role="tooltip"` and is referenced from the trigger with
+  `aria-describedby` when open (Radix does this).
+- The trigger's **accessible name** stays on the trigger (`aria-label` on
+  IconButton, visible text on Button). Tooltip is a description, not a
+  name. If the Tooltip text *is* the name, it must duplicate `aria-label`,
+  not replace it.
+- Content is plain text. No Buttons, no Links, no inputs. Interactive
+  content is Popover.
+- Do not set `aria-hidden` on Content while it is shown.
+- Never the only path to a label, an error, a shortcut that is required,
+  or a destructive-consequence warning.
+- Touch: because Content does not open, anything that was only in the
+  Tooltip is unavailable — another reason it cannot be essential.
+
+### Keyboard
+
+From Radix Tooltip:
+
+| Key | Action |
+| --- | --- |
+| `Tab` | Focus on the trigger opens the Tooltip without delay; focus away closes it. |
+| `Escape` | Closes without delay. |
+| `Enter` / `Space` | Activate the trigger; Tooltip closes. |
+
+There is no Tooltip-specific tab stop. Content is not focused.
+
+## When to use
+
+- Repeating an IconButton's `aria-label` for pointer users.
+- Showing a keyboard shortcut next to a named control.
+- Expanding a truncated string (filename, query) where the full value is
+  also available by expanding the row or focusing a cell — the Tooltip is a
+  shortcut to read it, not the only copy.
+
+## When NOT to use
+
+- **Touch as a primary environment for that control.** If the product's
+  use of the control is touch-first, put a visible label on the screen.
+- **Essential information.** Errors, permissions, destructive consequences,
+  how to complete the task. User story #10.
+- **Field help.** HelperText, always visible or available next to the
+  field.
+- **In-page conditions.** [Alert](alert.md).
+- **Rich or interactive content.** Popover (overlay slice).
+- **Disabled-button explanations.** Visible copy; see States.
+- **A substitute for `aria-label`.** IconButton already requires a name.
+- **Delaying first-time discovery of a primary action.** If people need a
+  Tooltip to find "Save", the label is missing.
+
+## Radix/shadcn mapping
+
+This is the component with a real Radix primitive. Implement against it.
+
+| Kiso | Reference |
+| --- | --- |
+| Behavior, delay, keyboard, `role="tooltip"` | Radix [Tooltip](https://www.radix-ui.com/primitives/docs/components/tooltip) (`Provider`, `Root`, `Trigger`, `Portal`, `Content`) |
+| Styling conventions | shadcn [Tooltip](https://ui.shadcn.com/docs/components/tooltip) restyled to the tokens above |
+
+Provider wraps the app once. Do not nest Providers per control.
+
+shadcn's "Disabled Button" example wraps a disabled Button in a span to
+force a Tooltip. **Do not use that pattern in Kiso.** A disabled-why
+message is essential and must be visible without hover.
+
+shadcn (and newer Base UI ports) may differ in API names (`TooltipTrigger`,
+`TooltipContent`). Map parts 1:1 to Radix anatomy; keep Radix keyboard and
+delay behavior as the behavioral source of truth.
+
+Skip the arrow if the shadcn default includes one and it adds decoration
+without helping placement.
+
+On coarse pointers, do not mount/open Content. Radix will still open on
+long-press in some browsers — suppress that. Long-press is not a Tooltip
+affordance in Kiso; it is a platform selection gesture.