@momoi-labs/kiso 0.1.0

package/kiso/docs/components/command-palette.md

@@ -0,0 +1,165 @@
+# CommandPalette
+
+A global, keyboard-first overlay for running actions and navigating the
+product by searching commands and destinations.
+
+## Purpose
+
+CommandPalette is the "do or go anywhere" surface: open a query editor, jump
+to a replica, switch project, run a frequent action — without hunting through
+menus. It is invoked by a documented shortcut, filters a command list as the
+person types, and is fully operable from the keyboard.
+
+User stories #5, #19, and #20.
+
+### Choose the right command surface
+
+| Need | Control | Why |
+| --- | --- | --- |
+| Global actions and navigation | **CommandPalette** | App-scoped; search-as-you-type commands. |
+| Filter items in a visible list/table | **[Search](search.md)** | Scoped to that collection; not an overlay of commands. |
+| Actions on one specific element | **[DropdownMenu](dropdown-menu.md)** | Anchored to that control; contextual, not global. |
+
+Search vs CommandPalette (user story #19): Search filters *content already
+in view*. CommandPalette finds *actions and destinations* across the app.
+
+DropdownMenu vs CommandPalette (user story #20): DropdownMenu is
+*contextual* to a trigger. CommandPalette is *global*.
+
+## Anatomy
+
+```
+CommandPalette
+├── Overlay / dialog surface (modal or non-modal per product; usually modal)
+├── Input (command filter; autofocused on open)
+├── List
+│   ├── Group (optional) × N
+│   │   ├── Group heading
+│   │   └── Item × N
+│   │       ├── Icon (optional)
+│   │       ├── Label (required)
+│   │       ├── Shortcut hint (optional; visual only if not a real keybinding)
+│   │       └── Description (optional)
+│   └── Empty message (no matching commands)
+└── Footer hints (optional; keyboard legend)
+```
+
+- **Input.** Filters commands; not a general document Search. Placeholder
+  like "Type a command or destination…".
+- **Item.** One command or destination. Activating runs the action or
+  navigates.
+- **Group.** Optional categories ("Navigation", "Replicas", "Settings").
+- **Empty.** In-palette message when the filter matches nothing — not the
+  page-level [EmptyState](empty-state.md).
+
+## Variants
+
+| Variant | Behavior |
+| --- | --- |
+| `commands` (default) | Mixed actions and destinations in one palette. |
+| `navigation` | Destinations only (rare; prefer one palette with groups). |
+
+Do not ship separate palettes per page unless the product truly scopes
+commands; default is one app-level palette.
+
+Surface: `--color-elevated-surface`, border `--color-border`, shadow
+`--shadow-sm`, radius `--radius-lg`. Input and items use foreground /
+muted-foreground roles. Active (highlighted) item uses `--color-surface` or
+a quiet `--color-primary` indicator without filling the row in primary ink.
+
+## Sizes
+
+One size. The palette is a centered (or top-anchored) elevated panel with
+max width from layout tokens / spacing rhythm — not Button `sm|md|lg`.
+Item row padding `--spacing-sm` block, `--spacing-md` inline. Type:
+the five body typography properties for items; the five label typography
+properties for group headings.
+
+## States
+
+| State | Behavior |
+| --- | --- |
+| default (closed) | Not in the tree, or inert. Shortcut available. |
+| open | Input focused; list visible; focus trapped within the palette while open (if modal). |
+| hover | Item under pointer highlighted; keyboard highlight is source of truth when last input was keyboard. |
+| focus | Input focus ring `--color-focus`. Highlighted item is the active descendant, not a second tab stop per row. |
+| active | Item activation (Enter / click) runs the command and usually closes the palette. |
+| disabled | Individual items may be disabled with `--color-disabled` and an explanation in description; prefer omitting unavailable commands. |
+| loading | Optional: Spinner in the list while command providers resolve. Keep the input usable. `aria-busy` on the list region. |
+| error | Provider failure: short in-palette message or Alert pattern inside the panel; do not fail silently to an empty list that looks like "no matches". |
+
+### Invocation (user story #5)
+
+| Mechanism | Behavior |
+| --- | --- |
+| Shortcut | Default recommendation: `⌘K` (macOS) / `Ctrl+K` (Windows/Linux), documented in product chrome. Do not bind Search fields to this shortcut. |
+| Explicit trigger | Optional Button/IconButton in the Header ("Search commands…") that opens the same palette. |
+| Search-as-you-type | Filter updates the list as the person types. |
+| Keyboard navigation | Arrow keys move the highlight; Enter activates; Escape closes. |
+
+## Accessibility
+
+- Prefer a modal dialog pattern (`role="dialog"`, `aria-modal="true"`) with
+  an accessible name ("Command palette" / product-specific).
+- Input has a visible or programmatically associated label.
+- List uses `role="listbox"` (or cmdk's list semantics) with items as options;
+  the active item is exposed via `aria-activedescendant` on the input **or**
+  an equivalent pattern preserved from the reference library — do not invent
+  a broken tab-per-item list.
+- Focus moves to the Input on open; on close, focus returns to the previously
+  focused element (or the trigger).
+- Shortcut hints in items are decorative unless they document real bindings;
+  real bindings must work even when the palette is closed (where claimed).
+- `Escape` closes without running a command.
+- Reduced motion: no gratuitous entrance animation beyond token durations.
+
+### Keyboard
+
+| Key | Action |
+| --- | --- |
+| `⌘K` / `Ctrl+K` | Toggle open/close (product default). |
+| Printable keys | Filter commands (input focused). |
+| `ArrowDown` / `ArrowUp` | Move highlight through items (and across groups). |
+| `Enter` | Activate highlighted item. |
+| `Escape` | Close without activating. |
+| `Tab` | Generally stays within the palette (focus trap) while open; do not tab into the page behind a modal palette. |
+
+## When to use
+
+- App-wide command and navigation entry (user stories #5, #19, #20).
+- Power-user shortcuts to frequent destinations in data tools.
+- Discoverability for actions that would otherwise hide in nested menus.
+
+## When NOT to use
+
+- **Filtering a table or list in place.** [Search](search.md).
+- **Actions on one row/button/avatar.** [DropdownMenu](dropdown-menu.md).
+- **Confirming a destructive action.** Modal/Dialog (overlay slice) after
+  the command is chosen, if confirmation is required.
+- **Form data entry.** Inputs and FormField — the palette is not a form.
+- **Teaching the only path to a critical action.** Palette is acceleration;
+  critical actions still need a visible control somewhere.
+
+## Tokens
+
+`--color-elevated-surface`, `--color-surface`, `--color-foreground`,
+`--color-muted-foreground`, `--color-subtle-foreground`, `--color-border`,
+`--color-primary` (highlight affordance only), `--color-focus`,
+`--color-disabled`, `--shadow-sm`, `--spacing-sm` / `--spacing-md`,
+`--radius-lg`, `--motion-duration-fast`, and `--motion-easing-standard`.
+Items use `--type-role-body-font-family`, `--type-role-body-font-size`,
+`--type-role-body-font-weight`, `--type-role-body-letter-spacing`, and
+`--type-role-body-line-height`; group headings use the equivalent five
+property-qualified label tokens. No raw hex/px.
+
+## Radix/shadcn mapping
+
+| Kiso | Reference |
+| --- | --- |
+| Behavior | [cmdk](https://cmdk.paco.me/) via shadcn [Command](https://ui.shadcn.com/docs/components/command) |
+| Dialog shell | shadcn Command Dialog example (Radix Dialog) for modal presentation |
+| Input + list + groups + items | `Command`, `CommandInput`, `CommandList`, `CommandEmpty`, `CommandGroup`, `CommandItem`, `CommandShortcut` |
+
+Preserve cmdk keyboard and filter behavior. Restyle surfaces and text to Kiso
+semantic tokens. Do not treat Command as Search, and do not use Command as a
+DropdownMenu replacement for row actions.

package/kiso/docs/components/drawer.md

@@ -0,0 +1,79 @@
+# Drawer
+
+A viewport-adaptive overlay that enters from an edge and can replace a Modal
+when a small viewport needs a more usable layout.
+
+## Purpose
+
+Drawer preserves context while giving forms, details, or focused tasks more
+vertical room. Use it as the small-viewport presentation of the same task that
+may appear in [Modal/Dialog](modal-dialog.md) on larger viewports; behavior and
+accessible name stay consistent across the switch.
+
+## Anatomy
+
+```
+Drawer Root
+├── Trigger
+├── Overlay
+└── Content
+    ├── handle (optional, decorative)
+    ├── Title
+    ├── Description (optional)
+    ├── body
+    ├── actions
+    └── Close control
+```
+
+Content uses `--color-elevated-surface`, `--color-foreground`,
+`--color-border`, `--spacing-lg` padding, `--radius-lg`, and `--shadow-md`.
+Entry/exit uses `--motion-duration-normal` and `--motion-easing-standard`, with
+no travel under reduced motion.
+
+## Variants
+
+Two placements: bottom (default for small-viewport task adaptation) and side
+for contextual detail or editing. Placement must not change Dialog semantics or
+the task's accessible name.
+
+## Sizes
+
+One responsive size per placement. Content is bounded by the viewport and the
+host layout; do not introduce `sm` / `md` / `lg` Drawer widths.
+
+## States
+
+| State | Behavior |
+| --- | --- |
+| closed (default) | Content is absent; trigger remains available. |
+| hover | Trigger and child controls own hover. |
+| focus | Opening moves focus inside; focused controls show `--color-focus`. |
+| active/open | Page behind is inert and focus is trapped. |
+| disabled | Disabled trigger does not open; Drawer itself is not disabled. |
+| dragging | Optional touch dismissal follows the pointer and cancels below the component's deliberate threshold. |
+| loading/error | Same task behavior as Modal/Dialog; do not dismiss on failure. |
+
+## Accessibility
+
+Use Dialog semantics (`role="dialog"`, `aria-modal="true"`, labelled title),
+focus trap, background inertness, and focus return. `Escape` closes when safe;
+`Tab` stays inside. Swipe/drag dismissal must have an equivalent Close Button,
+must not be the only way out, and must not discard work accidentally.
+
+## When to use
+
+- A Modal task that needs a small-viewport, edge-to-edge presentation.
+- Contextual detail or editing where retaining the underlying page matters.
+
+## When NOT to use
+
+- Merely because the design wants animation from an edge.
+- Primary application navigation that should remain persistent; use Sidebar.
+- A short anchored choice; use Popover or DropdownMenu.
+- A full workflow that deserves its own route.
+
+## Radix/shadcn mapping
+
+Maps behavior to Radix Dialog and presentation to shadcn Sheet. Keep Dialog
+focus management. A gesture-oriented drawer library may supply drag behavior,
+but it must preserve these semantics and semantic tokens.

package/kiso/docs/components/dropdown-menu.md

@@ -0,0 +1,178 @@
+# DropdownMenu
+
+A contextual menu of actions anchored to a specific control. It opens on
+demand, stays near its trigger, and closes after a choice or dismissal.
+
+## Purpose
+
+DropdownMenu offers actions *about this thing*: a row, an avatar, a kebab in
+a Card header, a column of overflow actions. The trigger owns the context;
+the menu does not search the whole app.
+
+User story #20.
+
+### Choose the right action menu
+
+| Need | Control | Why |
+| --- | --- | --- |
+| Actions on a specific element | **DropdownMenu** | Anchored; contextual. |
+| Global actions / navigation by query | **[CommandPalette](command-palette.md)** | Not anchored to one element. |
+| Single choice that sets a value | **[Select](select.md)** | Value selection, not a list of verbs. |
+| Navigate to a URL as primary affordance | **[Link](link.md)** | Real navigation; menu items may still contain links when appropriate. |
+
+DropdownMenu vs CommandPalette (user story #20): if the person must first
+find the object, then open its menu, use DropdownMenu. If they are running
+a global command without a local trigger, use CommandPalette.
+
+Header (navigation slice) may compose DropdownMenu for account or overflow
+actions. [Table / DataTable](table.md) uses it for row actions.
+
+## Anatomy
+
+```
+DropdownMenu
+├── Trigger (Button, IconButton, or other focusable control)
+└── Content (portaled elevated surface)
+    ├── Label (optional section label)
+    ├── Item × N
+    │   ├── leading icon (optional)
+    │   ├── label (required)
+    │   ├── shortcut hint (optional)
+    │   └── destructive styling (optional)
+    ├── Separator (optional)
+    ├── Checkbox item (optional; rare)
+    ├── Radio group (optional; rare)
+    └── Submenu (optional)
+        ├── Sub-trigger
+        └── Sub-content
+```
+
+- **Trigger.** Usually [IconButton](icon-button.md) (`ghost` `sm`) with an
+  accessible name ("Actions for {row}", "Open account menu"). Never an
+  unnamed icon.
+- **Item.** A verb or destination ("Edit", "Duplicate", "Delete", "View
+  logs"). Prefer verbs for actions.
+- **Separator.** Groups related items; decorative.
+- **Destructive item.** Irreversible actions; use danger treatment on the
+  item label/icon, not a filled danger panel. Confirm with Modal when stakes
+  are high (overlay slice).
+
+## Variants
+
+Presentation is one menu system; item *kinds* vary:
+
+| Kind | When |
+| --- | --- |
+| `action` (default) | Runs a command or opens a follow-on UI. |
+| `link` | Navigates; implement as a real link item when the reference supports it so open-in-new-tab works. |
+| `destructive` | Destructive/irreversible action. |
+| `checkbox` / `radio` | Rare in Kiso v1; only when the menu is the established pattern for a compact multi/one option set. Prefer Select/Checkbox in forms. |
+
+Trigger variants come from Button/IconButton — DropdownMenu does not define
+a parallel size/color system for the trigger.
+
+Content tokens: background `--color-elevated-surface`, border
+`--color-border`, text `--color-foreground`, muted hints
+`--color-muted-foreground`, destructive `--color-danger`, focus/highlight
+`--color-focus` / quiet `--color-surface` for the highlighted item. Radius
+`--radius-md`. Padding `--spacing-xs` around the list; item padding
+`--spacing-sm` / `--spacing-md`.
+
+## Sizes
+
+| Axis | Rule |
+| --- | --- |
+| Trigger | IconButton/Button `sm` in tables and dense chrome; `md` in headers. |
+| Content | Min width fits labels; match trigger width only when it helps. No raw px: measure from the body/label typography properties and add the `--spacing-md` inline item padding. |
+| Items | One density; do not ship `sm`/`lg` item scales. |
+
+## States
+
+| State | Behavior |
+| --- | --- |
+| default (closed) | Trigger at rest; content unmounted or hidden. |
+| hover | Trigger and highlighted item show quiet emphasis. |
+| focus | Trigger shows `--color-focus` when focused. Open content uses highlighted item semantics. |
+| open / active | `data-state="open"` on trigger; content visible; focus moves into the menu per Radix model. |
+| disabled | Trigger cannot open, or individual items disabled with `--color-disabled`. Prefer omitting unavailable items when absence is clear. |
+| loading | Rare on the menu itself. A trigger IconButton may show loading after an item was chosen and the menu has closed. Do not leave a stuck open menu in a loading limbo. |
+| error | Not a menu chrome state. Failures after an action use Alert/Toast (as appropriate) on the page. |
+
+### Open / close
+
+- Open on click / Enter / Space / ArrowDown on the trigger (per Radix).
+- Close on item select, `Escape`, focus loss outside, or opening another
+  overlay — preserve Radix dismiss behavior.
+- Pointer: hover may highlight items; selection commits on click, not merely
+  on hover.
+
+## Accessibility
+
+- Trigger must have an accessible name. Icon-only triggers use `aria-label`
+  or `aria-labelledby`.
+- Use Radix Dropdown Menu roles (`menu`, `menuitem`, etc.) — do not fake a
+  menu with a div list lacking keyboard support.
+- `aria-expanded` / `aria-controls` (or the library equivalents) reflect open
+  state.
+- Destructive items must not rely on color alone; include clear labeling
+  ("Delete replica").
+- Submenus: follow Radix focus movement; do not invent a second Escape
+  model.
+- Do not place essential instructions only inside a closed menu.
+
+### Keyboard
+
+| Key | Action |
+| --- | --- |
+| `Enter` / `Space` | Open from trigger; activate focused item when open. |
+| `ArrowDown` / `ArrowUp` | Open from trigger (where supported) or move between items. |
+| `Home` / `End` | Move to first / last item when supported. |
+| `ArrowRight` / `ArrowLeft` | Open / close submenu when present. |
+| `Escape` | Close menu; return focus to trigger. |
+| Typeahead | Focus the item matching typed characters when supported. |
+
+## When to use
+
+- Overflow / kebab actions on a table row, Card, or list item.
+- Account or session menus in Header chrome.
+- A small set of contextual verbs that would clutter the layout if always
+  visible (user story #20).
+
+## When NOT to use
+
+- **Global command search.** [CommandPalette](command-palette.md).
+- **Filtering visible content.** [Search](search.md).
+- **Primary page actions.** Prefer visible [Button](button.md)s in
+  PageHeader; menus are secondary/overflow.
+- **Choosing a single form value from many.** [Select](select.md).
+- **Navigation that should look like a menu of destinations as the main IA.**
+  Prefer Sidebar / Navigation (navigation slice); a DropdownMenu of links is
+  fine for compact account/overflow only.
+- **Tooltips.** Tooltips are non-essential hints ([Tooltip](tooltip.md));
+  menus are actionable.
+
+## Tokens
+
+`--color-elevated-surface`, `--color-surface`, `--color-foreground`,
+`--color-muted-foreground`, `--color-border`, `--color-danger`,
+`--color-focus`, `--color-disabled`, `--spacing-xs` list padding,
+`--spacing-sm` / `--spacing-md` item padding, `--radius-md`, `--shadow-sm`,
+the five property-qualified body typography tokens for items, the five label
+typography tokens for group labels, `--motion-duration-fast`, and
+`--motion-easing-standard`. Trigger consumes Button/IconButton tokens. No raw
+hex/px.
+
+## Radix/shadcn mapping
+
+| Kiso | Reference |
+| --- | --- |
+| Behavior | Radix [Dropdown Menu](https://www.radix-ui.com/primitives/docs/components/dropdown-menu) |
+| Styling / composition | shadcn [Dropdown Menu](https://ui.shadcn.com/docs/components/dropdown-menu) |
+| Trigger | Kiso [Button](button.md) / [IconButton](icon-button.md) via `asChild` / Slot when needed |
+| Destructive item | shadcn `destructive` item class → `--color-danger` text/icon, not filled |
+
+Preserve Radix focus management, typeahead, submenu behavior, and portal
+positioning. Restyle with Kiso semantic tokens only.
+
+Do **not** map row actions to Command/cmdk. Do **not** use Select to fake an
+action menu.

package/kiso/docs/components/empty-state.md

@@ -0,0 +1,142 @@
+# EmptyState
+
+A deliberate placeholder when a region has nothing to show. It explains
+why the space is empty and may offer a next action.
+
+## Purpose
+
+EmptyState replaces an expected list, table body, or collection when there
+are zero items — either because the person has never created any, or because
+filters/search matched none.
+
+User story #13: the action is **optional**. Informational-only EmptyStates are
+valid when there is nothing useful to do yet.
+
+### Choose the right empty
+
+| Situation | Control | Why |
+| --- | --- | --- |
+| Zero items in a collection / table body | **EmptyState** | Explains emptiness; optional create/clear action. |
+| Still loading | [Skeleton](skeleton.md) | Not empty — pending. |
+| Failed to load | [Alert](alert.md) | Error, not emptiness. |
+| A single field with no value | Placeholder / HelperText | Not a page-level empty. |
+
+[Table / DataTable](table.md) composes EmptyState for its empty data state.
+
+## Anatomy
+
+```
+EmptyState
+├── Illustration / icon (optional)
+├── Title (required)
+├── Description (optional; recommended when the title is not enough)
+└── Action (optional: Button or Link)
+```
+
+- **Illustration / icon.** Optional. Decorative (`aria-hidden`) when Title
+  carries the meaning. Prefer a simple icon over a large marketing
+  illustration in product UI.
+- **Title.** What is empty, in product language ("No replicas yet", "No
+  queries match"). Follow [voice-and-tone](../voice-and-tone.md).
+- **Description.** One or two short sentences: why, and what to do if there
+  is no Action control.
+- **Action.** Optional [Button](button.md) (create, import, clear filters)
+  or [Link](link.md) when the next step is navigation. Never required.
+
+## Variants
+
+| Variant | When | Action |
+| --- | --- | --- |
+| `first-run` | The collection has never had items. | Usually a primary Button ("Create replica"). |
+| `no-results` | Filters or Search exclude everything. | Often "Clear filters" (default/ghost) or adjust Search; not "Create". |
+| `informational` | Empty is expected and there is no useful action. | No Action. Title + Description only. |
+
+Do not add severity variants (info/warning/error). Emptiness is not an
+error — errors are Alert. Do not color the whole EmptyState with status
+tokens.
+
+Surface tokens: text `--color-foreground` / `--color-muted-foreground` on
+the surrounding `--color-surface` or `--color-background`. Icon uses
+`--color-muted-foreground` unless it is purely decorative brand chrome.
+
+## Sizes
+
+| Size | Use | Tokens |
+| --- | --- | --- |
+| `md` (default) | Table bodies, Card content, list panels. | Title uses the five heading typography properties, or the five label typography properties for label emphasis; description uses the five body typography properties; padding `--spacing-lg`; gap `--spacing-sm`. |
+| `sm` | Narrow side panels or compact nested regions. | Tighter padding `--spacing-md`; smaller icon; same type roles if readable. |
+
+Action Buttons use Button `md` by default; `sm` only inside `sm` EmptyState
+in dense chrome. Do not invent an `lg` EmptyState that competes with
+PageHeader.
+
+## States
+
+| State | Behavior |
+| --- | --- |
+| default | Visible empty region. |
+| hover / focus / active | EmptyState itself is not a control. Focus goes to Action if present. |
+| disabled | N/A. Hide the region or show a different state. |
+| loading | Do not show EmptyState while loading — use Skeleton. If the Action triggers creation, that Button may enter loading. |
+| error | Not an EmptyState state. Switch to Alert. |
+
+## Accessibility
+
+- EmptyState is a region with an accessible name from Title
+  (`aria-labelledby`) and optional `aria-describedby` for Description.
+- Prefer landmark/region semantics only when the empty area is a major
+  page section; inside a table body, keep table structure and place
+  EmptyState content in a single full-width cell or a documented
+  replacement region announced as the table's status.
+- Icon/illustration: `aria-hidden="true"` when Title is present.
+- Action is a real Button or Link with its own accessible name. Do not make
+  the entire EmptyState clickable.
+- When EmptyState appears because Search filtered everything, ensure the
+  Search field remains reachable and that the empty message is findable
+  by screen reader users (polite live update only if the change is not
+  obvious from focus).
+
+### Keyboard
+
+| Key | Action |
+| --- | --- |
+| `Tab` / `Shift+Tab` | Reach the Action if present. |
+| `Enter` / `Space` | Activate the focused Action. |
+
+## When to use
+
+- A list, table body, or collection has zero items to show.
+- First-run onboarding for a createable resource (with Action).
+- No Search/filter matches (with copy that reflects filters).
+- Informational empty when no action exists (user story #13).
+
+## When NOT to use
+
+- **Loading.** Skeleton (or Spinner for indeterminate non-layout waits).
+- **Errors.** Alert with retry.
+- **Permission denied.** Alert or a dedicated locked state — not "No items".
+- **Marketing empty.** Product EmptyState is operational, not a billboard.
+- **Replacing a whole app shell.** Page-level emptiness still sits inside the
+  shell; do not delete navigation to show EmptyState.
+
+## Tokens
+
+`--color-foreground`, `--color-muted-foreground`, `--color-surface` /
+`--color-background`, optional icon `--color-muted-foreground`, `--spacing-lg`
+padding (`--spacing-md` for `sm`), `--spacing-sm` gap, `--radius-md`, and
+`--motion-duration-fast` / `--motion-easing-standard`. Typography uses every
+property of the selected heading, label, and body roles named above. Action consumes Button/Link
+tokens. No raw hex/px.
+
+## Radix/shadcn mapping
+
+No Radix EmptyState primitive.
+
+| Kiso | Reference |
+| --- | --- |
+| Composition pattern | shadcn has no dedicated Empty component in core; compose layout + typography + [Button](button.md) like common "empty" blocks in shadcn Data Table examples |
+| Action | shadcn / Kiso [Button](button.md) or [Link](link.md) |
+| Inside tables | shadcn Data Table empty row patterns → replace with this anatomy |
+
+Do not copy illustration-heavy marketing empties. Keep Kiso EmptyState
+quiet and actionable.

package/kiso/docs/components/form-field.md

@@ -0,0 +1,115 @@
+# FormField
+
+## Purpose
+
+FormField is the standard composition for one labeled form control. It aligns
+identification, entry, guidance, and field-level feedback so their visual and
+accessible relationships remain intact. FormField is not a primitive and does
+not replace the semantics of its children.
+
+## Anatomy
+
+The canonical composition is:
+
+1. **Label** — required; names the control through matching `for`/`id`.
+2. **Input** — the default control in this composition. Textarea, Select,
+   Checkbox, or Switch may occupy the control slot when appropriate.
+3. **HelperText** — optional; provides persistent context, format, or scope.
+4. **ValidationMessage** — optional until invalid; explains a field-level error
+   and recovery.
+
+For the issue's foundational chain, read this literally as **Label + Input +
+HelperText + ValidationMessage**. FormField owns layout and ID wiring; each
+child retains its own behavior.
+
+```text
+Label
+Input
+HelperText
+ValidationMessage
+```
+
+## Variants
+
+- **Standard** — Label above Input, supporting text below.
+- **Required** — control exposes required semantics and the visible convention
+  is consistent across the form.
+- **Optional** — Label carries an “Optional” qualifier when useful.
+- **Horizontal** — Label and control columns for wide, dense settings pages;
+  collapses without changing reading order.
+- **Control substitution** — replaces Input with another Kiso form primitive
+  while preserving Label and description/error wiring.
+
+## Sizes
+
+- **Small** — inherits the small size of its control and compact semantic gaps.
+- **Medium** — default.
+- **Large** — inherits the large control size where that control supports it.
+
+FormField does not scale text independently. Label uses the five
+property-qualified label typography tokens; supporting text uses the five
+property-qualified metadata typography tokens. Use `--spacing-xs` between a
+control and supporting text and `--spacing-sm` between the label and control.
+
+## States
+
+| State | Behavior |
+| --- | --- |
+| Default | Label, control, and optional HelperText form one readable group. |
+| Hover | Delegated to the interactive control; layout does not change. |
+| Focus | Control owns the visible focus ring; supporting content remains stable. |
+| Active | Delegated to the control. |
+| Disabled | Control is disabled; Label and supporting text communicate unavailability without hiding context. |
+| Loading | Control exposes busy status and loading affordance while Label/help remain readable. |
+| Error | Control has `aria-invalid="true"`; ValidationMessage appears without removing useful HelperText. |
+
+Disabled and loading remain distinct at composition level. Loading is a live
+process; disabled is unavailable. Showing ValidationMessage must not cause the
+control, Label, or existing help to lose their associations.
+
+## Accessibility
+
+- Generate stable, collision-free IDs. Label `for` points to the control `id`.
+- HelperText and ValidationMessage each have an ID. The control's
+  `aria-describedby` contains the IDs of every present description, separated
+  by spaces; preserve HelperText when an error appears if it is still useful.
+- Invalid controls set `aria-invalid="true"`. ValidationMessage may use a live
+  region for errors introduced after interaction, but avoid duplicate
+  announcements caused by simultaneous alert and description behavior.
+- Required, disabled, read-only, and busy semantics belong on the control.
+- DOM reading order follows Label → control → HelperText → ValidationMessage,
+  even in a horizontal visual layout.
+- FormField adds no keyboard interaction. The contained control keeps its native
+  or Radix keyboard contract, and clicking Label targets that control.
+
+## When to use
+
+- For nearly every standalone labeled form control.
+- To make accessible ID wiring and vertical rhythm consistent.
+- When a control needs help, validation, required/optional status, or all three.
+
+## When NOT to use
+
+- Do not use as a generic layout wrapper or fieldset for unrelated controls.
+- Do not duplicate a Label or description already supplied by a composite
+  control.
+- Do not render an empty ValidationMessage merely to reserve space unless the
+  product has measured layout-stability needs.
+- Do not put form-level or page-level errors here; ValidationMessage is
+  field-level feedback.
+
+## Tokens
+
+FormField consumes `--spacing-xs`, `--spacing-sm`, and the label and metadata
+typography properties named above for layout. Its
+children own colors: foreground/muted text, surface/border, focus, disabled,
+and danger. The composition introduces no primitive token or raw value.
+
+## Radix/shadcn mapping
+
+There is no single Radix FormField primitive. The composition uses Radix Label
+and the relevant Radix control when one exists. It maps behaviorally to the
+[shadcn/ui Field](https://ui.shadcn.com/docs/components/field) composition and
+the form patterns documented by shadcn, while Kiso's explicit contract remains
+Label + Input + HelperText + ValidationMessage with deterministic IDs and ARIA
+wiring.