@momoi-labs/kiso 0.1.0

package/kiso/docs/components/modal-dialog.md

@@ -0,0 +1,82 @@
+# Modal / Dialog
+
+A focused overlay for a task or decision that temporarily blocks the page.
+
+## Purpose
+
+Modal/Dialog interrupts the current flow only when the person must complete,
+confirm, or cancel a focused task before returning. It traps focus and makes
+the page behind it inert. On small viewports, content that needs more room may
+use [Drawer](drawer.md) instead.
+
+## Anatomy
+
+```
+Dialog Root
+├── Trigger
+├── Overlay
+└── Content
+    ├── Title (required)
+    ├── Description (required when the title is insufficient)
+    ├── body
+    ├── actions
+    └── Close control
+```
+
+Content uses `--color-elevated-surface`, `--color-foreground`,
+`--color-border`, `--radius-lg`, `--spacing-lg` padding, and `--shadow-md`.
+Overlay transitions use `--motion-duration-normal` and
+`--motion-easing-standard`.
+
+## Variants
+
+Two behavioral variants: task Dialog (default) and Alert Dialog for a
+confirmation that must prevent outside dismissal. Both keep the same labelled,
+modal focus behavior; an in-page Alert is not a Dialog variant.
+
+## Sizes
+
+One responsive size. Content uses a readable bounded width and becomes
+viewport-limited when space is tight; use Drawer when the task needs a distinct
+small-viewport presentation instead of adding `sm` / `lg` Dialog sizes.
+
+## States
+
+| State | Behavior |
+| --- | --- |
+| closed (default) | Content is absent; trigger remains available. |
+| hover | Trigger and child controls own hover. |
+| focus | Opening moves focus inside; `--color-focus` remains visible on controls. |
+| active/open | Page behind is inert; focus is trapped in Content. |
+| disabled | A disabled trigger does not open; the Dialog itself is not disabled. |
+| loading | Keep close/cancel available when safe, mark the task `aria-busy="true"`, and prevent duplicate submission. |
+| error | Show recoverable error next to the affected action or field; keep the Dialog open. |
+
+## Accessibility
+
+Use `role="dialog"`, `aria-modal="true"`, `aria-labelledby`, and when needed
+`aria-describedby` (Radix supplies these from Title/Description). Opening moves
+focus to the first meaningful element, not always the close icon. `Tab` and
+`Shift+Tab` cycle inside; `Escape` closes unless a destructive operation cannot
+safely be interrupted. Closing returns focus to the trigger or the next logical
+control. Clicking the overlay may close only when losing work is impossible.
+
+## When to use
+
+- A short focused task, confirmation, or decision that blocks page work.
+- Content that needs explicit completion or cancellation.
+
+## When NOT to use
+
+- Persistent information; use an in-page [Alert](alert.md).
+- A transient confirmation; use [Toast](toast.md).
+- Rich contextual content anchored to a control; use [Popover](popover.md).
+- Long or navigation-heavy workflows; use a page, or Drawer when viewport
+  adaptation is the real need.
+
+## Radix/shadcn mapping
+
+Maps to Radix Dialog / shadcn Dialog (`Root`, `Trigger`, `Portal`, `Overlay`,
+`Content`, `Title`, `Description`, `Close`). Use Radix Alert Dialog only for
+confirmations that require its stricter outside-dismiss behavior; it is not
+Kiso's in-page Alert.

package/kiso/docs/components/navigation.md

@@ -0,0 +1,68 @@
+# Navigation
+
+A semantic container for a coherent set of Links to major destinations.
+
+## Purpose
+
+Navigation supplies landmark and grouping semantics without choosing a layout.
+[Header](header.md) and [Sidebar](sidebar.md) are specific layout roles that
+compose Navigation; Navigation itself is not a visual menu or overlay.
+
+## Anatomy
+
+```
+Navigation
+├── accessible label
+└── list
+    └── Link(s)
+```
+
+Presentation inherits its host. Links use `--color-foreground`,
+`--color-primary`, and `--color-focus`. Items use `--spacing-sm` block and
+`--spacing-md` inline spacing plus the five property-qualified label typography
+tokens.
+
+## Variants
+
+No visual variants. Navigation is semantic structure and inherits horizontal,
+vertical, or other presentation from its Header, Sidebar, footer, or section.
+
+## Sizes
+
+No sizes of its own. The host controls layout and spacing; Links keep the sizes
+defined by their component guidance.
+
+## States
+
+| State | Behavior |
+| --- | --- |
+| default | Destinations are exposed as native Links. |
+| hover | Link owns hover feedback. |
+| focus | Focused Link shows `--color-focus`. |
+| active | Current destination uses `aria-current="page"`. |
+| disabled | Navigation is never disabled; omit unavailable destinations or follow Link guidance. |
+
+## Accessibility
+
+Use `<nav aria-label="…">` and preferably a list of Links. Each navigation
+landmark on the page needs a distinct label (“Primary”, “Breadcrumb”,
+“Pagination”). Do not add menu roles: application navigation keeps native Link
+semantics and `Tab` order. `Enter` follows a Link.
+
+## When to use
+
+- To group destinations in Header, Sidebar, footer, or a local section.
+- When assistive-technology users should be able to jump to the link set as a
+  landmark.
+
+## When NOT to use
+
+- A group of commands or Buttons.
+- Tabs that switch within-page panels.
+- Breadcrumb or Pagination, which need their more specific labels and rules.
+
+## Radix/shadcn mapping
+
+No primitive is needed: use native `<nav>` + list + Kiso Link. Radix Navigation
+Menu / shadcn Navigation Menu is only a behavioral reference for genuinely
+compound disclosure navigation, not the default implementation.

package/kiso/docs/components/page-header.md

@@ -0,0 +1,70 @@
+# PageHeader
+
+Introduces one page with its title, supporting context, and primary actions.
+
+## Purpose
+
+PageHeader gives every route a clear content heading and a predictable place
+for page-scoped actions. It composes title + optional subtitle + action
+[Buttons](button.md); it is distinct from the application [Header](header.md).
+
+## Anatomy
+
+```
+PageHeader
+├── title (required h1)
+├── subtitle (optional)
+└── actions (optional)
+    └── Button(s)
+```
+
+Title uses `--type-role-heading-font-family`, `--type-role-heading-font-size`,
+`--type-role-heading-font-weight`, `--type-role-heading-letter-spacing`, and
+`--type-role-heading-line-height` with `--color-foreground`; subtitle uses the
+five property-qualified body typography tokens and `--color-muted-foreground`.
+Layout uses `--spacing-lg` between regions and `--spacing-sm` between title and
+subtitle. Actions retain Button tokens and behavior.
+
+## Variants
+
+No visual variants. Subtitle and actions are optional anatomy; their presence
+does not create separate PageHeader variants.
+
+## Sizes
+
+One size. The title keeps the page-heading type role; responsive wrapping is a
+compact state, while child Buttons retain their own sizes.
+
+## States
+
+| State | Behavior |
+| --- | --- |
+| default | Title leads; subtitle and actions support it. |
+| hover | No container hover; Buttons own hover. |
+| focus | Focus lands on actions, never on the layout container by default. |
+| active | N/A for the container; child Buttons own active state. |
+| disabled | PageHeader is never disabled; individual actions may be. |
+| compact | On narrow viewports, actions wrap below text without changing reading or focus order. |
+
+## Accessibility
+
+Use the page's single `<h1>` for the title. Keep DOM order title, subtitle,
+then actions even when visual layout places actions beside the title. Button
+labels must state their actions. Do not put navigation controls here merely to
+fill space.
+
+## When to use
+
+- At the start of a routed page or a primary workspace view.
+- When page-specific actions need a consistent location.
+
+## When NOT to use
+
+- For global product chrome; use Header.
+- Inside every Card or nested section; use the correct heading level.
+- When it would create a second `<h1>` on the page.
+
+## Radix/shadcn mapping
+
+No Radix or shadcn PageHeader primitive. Compose semantic HTML and Kiso Button;
+do not treat shadcn CardHeader as a page-level substitute.

package/kiso/docs/components/pagination.md

@@ -0,0 +1,129 @@
+# Pagination
+
+Moves through explicit pages or indicates progress through a bounded sequence.
+
+## Purpose
+
+Pagination exposes position and direct page navigation when page numbers help
+the person reason about a dataset. It composes with Table/DataTable; it does
+not replace filtering or Search. Its step indicator variant exposes position
+in a sequential workflow without making progress itself.
+
+## Anatomy
+
+```
+Pagination navigation
+├── Previous control
+├── page Link(s)
+├── ellipsis (optional, non-interactive)
+├── Next control
+└── result summary (optional)
+```
+
+Use Link for URL-addressable pages and Button only for a client-side dataset
+whose URL intentionally does not change. Apply `--color-primary`,
+`--color-foreground`, `--color-border`, `--color-disabled`, and
+`--color-focus`, `--spacing-xs` between controls, `--spacing-sm` block and
+inline control padding, and the five property-qualified label typography
+tokens.
+
+## Variants
+
+No visual variants. Pagination uses the numbered model shown above; optional
+ellipsis and result summary are composition choices, not variants.
+
+## Sizes
+
+One size. Page controls keep one consistent target and label treatment; use
+semantic spacing rather than introducing `sm` or `lg` pagination.
+
+## States
+
+| State | Behavior |
+| --- | --- |
+| default | Page destinations and previous/next are available. |
+| hover | Interactive page control owns hover feedback. |
+| focus | Focused control shows `--color-focus`. |
+| active | Current page has `aria-current="page"`; activation loads the target page. |
+| disabled | Previous/next at a boundary is unavailable and uses `--color-disabled`; page Links are never disabled. |
+| loading | Keep position visible, mark the results region `aria-busy="true"`, and prevent duplicate requests without erasing controls. |
+
+## Accessibility
+
+Use `<nav aria-label="Pagination">`. Give controls names such as “Go to page
+4”, “Previous page”, and “Next page”; the visible numeral alone is not enough.
+Ellipses are not focusable. After a page change, move focus to the results
+heading or announce the updated range in a polite live region. Native Link or
+Button keyboard behavior applies.
+
+## Step indicator variant
+
+Pagination supports a step indicator variant for a bounded, sequential flow,
+as required by user story 17 in
+[epic #3](https://github.com/momoi-labs/blueprint/issues/3). This variant reuses
+Pagination's ordered navigation shape and tokens, but steps are workflow
+states, not dataset pages. It does not add a separate multi-step pattern.
+
+### Semantics and anatomy
+
+```
+Step indicator navigation
+└── ordered list
+    └── step (one or more)
+        ├── position or status marker
+        ├── label
+        └── supporting text (optional)
+```
+
+Keep every step visible so the person can understand their position and the
+remaining work. Use concise task labels rather than page numbers alone. The
+indicator communicates progress; Button controls such as “Back” and
+“Continue” perform the workflow actions and remain outside it.
+
+### States
+
+| State | Behavior |
+| --- | --- |
+| upcoming | Identifies work not yet reached. It is non-interactive unless the flow explicitly allows skipping ahead. |
+| current | Identifies the active step with `aria-current="step"`; only one step is current. |
+| completed | Identifies a successfully completed step. It may be interactive when revisiting completed work is safe. |
+| error | Identifies a visited step that needs attention without relying on color alone. |
+| disabled | An unavailable step remains legible but cannot be activated; prefer non-interactive text over a disabled Link. |
+
+Do not infer completion from the current position: a person may return to a
+completed step, and a visited step may contain an error. Pair icons and colors
+with text or accessible names such as “Completed: Account details”.
+
+### Accessibility and keyboard behavior
+
+Wrap the ordered list in `<nav aria-label="Form progress">` and expose the
+current item with `aria-current="step"`. Include the step position in its
+accessible name when it is useful, for example “Step 2 of 4: Permissions,
+current step”. Decorative connectors and status icons are hidden from
+assistive technology.
+
+Render navigable steps as native Links when each step has a URL, or Buttons
+when navigation is intentionally client-side. `Tab` moves through only those
+interactive steps; `Enter` activates a Link, and `Enter` or `Space` activates
+a Button. Non-interactive current, upcoming, and disabled steps do not enter
+the tab order. Do not add arrow-key behavior unless the indicator is built
+from another component whose documented semantics require it. After a step
+change, move focus to the new step's heading and announce validation errors
+before blocking “Continue”.
+
+## When to use
+
+- A known dataset where people benefit from page position or direct jumps.
+- Table/DataTable results that are expensive or impractical to load at once.
+- A bounded multi-step flow where people benefit from seeing their progress.
+
+## When NOT to use
+
+- An unbounded activity stream; use incremental loading.
+- A small dataset that fits comfortably on one page.
+- To hide missing Search or filtering.
+
+## Radix/shadcn mapping
+
+No Radix Pagination primitive. Use shadcn Pagination as a structural reference
+with native Links and Kiso tokens; do not copy utility colors or raw sizes.

package/kiso/docs/components/popover.md

@@ -0,0 +1,74 @@
+# Popover
+
+An anchored overlay for rich contextual content, including interactive
+controls.
+
+## Purpose
+
+Popover adds context or a small task beside its trigger without blocking the
+whole page. Unlike [Tooltip](tooltip.md), it may contain Buttons, Links, or
+inputs and can hold more than a short hint.
+
+## Anatomy
+
+```
+Popover
+├── Trigger
+└── Content
+    ├── heading/label (when needed)
+    ├── contextual content or controls
+    └── Arrow (optional)
+```
+
+Content uses `--color-elevated-surface`, `--color-foreground`,
+`--color-border`, `--radius-md`, `--spacing-md` padding, and `--shadow-md`.
+Placement offset uses `--spacing-xs`, collision padding uses `--spacing-md`,
+and motion uses `--motion-duration-fast` with `--motion-easing-standard`.
+
+## Variants
+
+No visual variants. Side, alignment, collision flipping, and an optional Arrow
+are placement/composition options, not separate Popover variants.
+
+## Sizes
+
+One content-sized treatment with a readable maximum width. Do not add named
+sizes; content that needs substantially more room belongs in Dialog or Drawer.
+
+## States
+
+| State | Behavior |
+| --- | --- |
+| closed (default) | Content is absent and trigger has `aria-expanded="false"`. |
+| hover | Trigger owns hover; hover alone does not open interactive content. |
+| focus | Trigger/children show `--color-focus`; opening may move focus to content when the task requires it. |
+| active/open | Trigger has `aria-expanded="true"`; Content flips or shifts on collision. |
+| disabled | Disabled trigger does not open. |
+| loading/error | Represent these inside Content with the relevant component; keep the Popover stable. |
+
+## Accessibility
+
+The trigger is a Button or other appropriate control with `aria-expanded` and
+an accessible name. `Enter`/`Space` opens; `Escape` closes and returns focus to
+the trigger. `Tab` moves through interactive content and then onward; Popover
+does not trap focus like a Dialog. Close on outside interaction only when doing
+so cannot lose unsaved work. Supply a heading/label when Content needs one.
+
+## When to use
+
+- Contextual details, filters, compact forms, or rich previews anchored to a
+  control.
+- Content with interactive elements that cannot live in Tooltip.
+
+## When NOT to use
+
+- A short, non-essential text hint; use Tooltip.
+- A blocking decision or focus trap; use Modal/Dialog.
+- A list of actions only; use DropdownMenu.
+- Essential information that disappears without a clear way to reopen it.
+
+## Radix/shadcn mapping
+
+Maps to Radix Popover / shadcn Popover (`Root`, `Trigger`, `Portal`, `Content`,
+optional `Arrow`). Radix collision and focus behavior are the behavioral
+reference; restyle with Kiso tokens.

package/kiso/docs/components/search.md

@@ -0,0 +1,147 @@
+# Search
+
+A standalone field that filters or finds within a visible collection. It does
+not navigate the app or run global commands.
+
+## Purpose
+
+Search narrows what the person already has in view — rows in a
+[Table / DataTable](table.md), items in a list, entries in a panel. The
+collection owns the data; Search only supplies the query string (and optional
+clear).
+
+User stories #9 and #19.
+
+### Choose the right finder
+
+| Need | Control | Why |
+| --- | --- | --- |
+| Filter visible / listed content | **Search** | Query stays scoped to this collection. |
+| Global actions, jump-to, command runner | **[CommandPalette](command-palette.md)** | App-wide; keyboard-first command UI. |
+| Single-line form value that happens to be a query stored as data | [Input](input.md) `type="search"` inside FormField | Persisted field, not live filtering chrome. |
+| One value from a known set | [Select](select.md) | Not free-text filter. |
+
+Search composes *with* lists and tables; it is **not** built into them
+(user story #9).
+
+## Anatomy
+
+```
+Search
+├── leading icon (optional; decorative magnifying glass)
+├── Input (type="search"; required)
+├── Clear (optional IconButton; visible when value non-empty)
+└── Spinner (optional; while results are resolving)
+```
+
+Label is usually visually hidden but programmatically present ("Filter
+replicas", "Search queries") — either a `<label>` or `aria-label` on the
+input. Do not rely on placeholder alone as the name.
+
+HelperText / [ValidationMessage](validation-message.md) are uncommon for
+live filters; if the query can be invalid (regex mode, etc.), wrap with
+FormField patterns.
+
+## Variants
+
+| Variant | Behavior |
+| --- | --- |
+| `instant` (default) | Filters as the person types (debounced). Good for client-side or fast indexes. |
+| `submit` | Applies on Enter or an explicit "Search" Button. Good for expensive server queries. |
+
+Appearance follows Input: `--color-surface`, `--color-border`,
+`--color-foreground`, placeholder `--color-subtle-foreground`. Leading icon
+`--color-muted-foreground`.
+
+Do not add a "global" variant — that is CommandPalette.
+
+## Sizes
+
+Align with [Input](input.md):
+
+| Size | Use |
+| --- | --- |
+| `sm` | Table toolbars, dense chrome. |
+| `md` (default) | Most collection filters. |
+| `lg` | Rare; full-page find entry points. |
+
+Width is a layout concern (toolbar flex): prefer filling the filter slot,
+not a fixed pixel width.
+
+## States
+
+| State | Behavior | Tokens / notes |
+| --- | --- | --- |
+| default | Empty or valued; ready to type. | Input default tokens. |
+| hover | Quiet border emphasis; no layout shift. | |
+| focus | Visible `--color-focus` ring on the input. | |
+| active | Native caret / selection. | |
+| disabled | Native `disabled`; not focusable. | `--color-disabled`. |
+| loading | Value remains; show Spinner; `aria-busy` on the search region or input when results are in flight. Do not clear the query. | Distinct from disabled. |
+| error | Rare. `aria-invalid` + [ValidationMessage](validation-message.md) only when the query syntax itself is invalid — not when there are zero hits. | Zero hits → collection [EmptyState](empty-state.md) `no-results`, not Search error. |
+
+Clear control: [IconButton](icon-button.md) `ghost` `sm`, `aria-label`
+"Clear search". After clear, keep focus in the input and refresh results.
+
+## Accessibility
+
+- Accessible name always present (`label` / `aria-label` / `aria-labelledby`).
+  Placeholder is not the name.
+- Use native `type="search"` so platform clear and semantics work where
+  available; if a custom Clear is used, keep it named and keyboard reachable.
+- Debounced instant search should update results without trapping focus.
+  When results update, prefer updating the collection region; use a polite
+  status only when the change would otherwise be silent ("12 replicas").
+- Do not move focus into the table on every keystroke.
+- Submit variant: Enter submits; a visible Button must also exist if Enter
+  is not obvious in context.
+
+### Keyboard
+
+| Key | Action |
+| --- | --- |
+| Printable keys | Edit the query. |
+| `Enter` | `submit` variant: apply query. `instant`: may force an immediate apply (flush debounce); do not navigate away. |
+| `Escape` | Optional: clear the query if non-empty, or leave unchanged — pick one per surface and keep it consistent. Does not open CommandPalette. |
+| `Tab` / `Shift+Tab` | Move to Clear (if present) and the rest of the page. |
+
+`⌘K` / `Ctrl+K` is **not** Search's shortcut — that belongs to
+[CommandPalette](command-palette.md) unless the product explicitly documents
+a different global binding.
+
+## When to use
+
+- Filtering rows in a Table/DataTable toolbar.
+- Filtering a list or catalog panel.
+- Any "narrow what I see here" affordance (user stories #9, #19).
+
+## When NOT to use
+
+- **Global jump / run command.** CommandPalette.
+- **Contextual actions on one element.** [DropdownMenu](dropdown-menu.md).
+- **Choosing one known option.** Select.
+- **Storing a search string as form data** without live filtering — Input in
+  FormField may be enough; do not force Search chrome.
+- **Replacing empty or error states.** EmptyState / Alert on the collection.
+
+## Tokens
+
+Same semantic set as Input: `--color-surface`, `--color-foreground`,
+`--color-subtle-foreground`, `--color-muted-foreground`, `--color-border`,
+`--color-focus`, `--color-disabled`, `--spacing-sm` block and `--spacing-md`
+inline padding, `--radius-md`, the five property-qualified body typography
+tokens, `--motion-duration-fast`, and `--motion-easing-standard`.
+Spinner and IconButton bring their own tokens. No raw hex/px.
+
+## Radix/shadcn mapping
+
+No Radix Search primitive.
+
+| Kiso | Reference |
+| --- | --- |
+| Field | Native `input type="search"` styled like shadcn [Input](https://ui.shadcn.com/docs/components/input) |
+| Clear / icon chrome | Compose Kiso IconButton + decorative icon; shadcn Input with icon examples as layout reference only |
+| In toolbars | shadcn Data Table toolbar filter input → restyle to Kiso tokens |
+
+Do **not** map Search to shadcn [Command](https://ui.shadcn.com/docs/components/command)
+or cmdk. That reference is [CommandPalette](command-palette.md).

package/kiso/docs/components/select.md

@@ -0,0 +1,105 @@
+# Select
+
+## Purpose
+
+Select lets a person choose exactly one value from a predefined set. It hides
+the option list until opened, so use it when showing every option at once would
+create unnecessary noise.
+
+## Anatomy
+
+1. **Trigger** — displays the selected value or placeholder and opens the list.
+2. **Value** — current selection.
+3. **Icon** — indicates that the list can open; decorative when the trigger is
+   already named.
+4. **Content** — elevated option surface positioned relative to the trigger.
+5. **Viewport** — scrollable option container.
+6. **Item** — one selectable value, with optional selection indicator.
+7. **Group and group label (optional)** — organizes a long, meaningful set.
+8. **Scroll controls (optional)** — reveal overflow without replacing ordinary
+   scrolling.
+
+## Variants
+
+- **Default** — flat list of mutually exclusive options.
+- **Grouped** — labeled groups where categories help scanning.
+- **Required** — placeholder is not a valid submitted value.
+- **Disabled options** — exceptional choices that are visible but unavailable;
+  prefer omitting irrelevant options when their absence is not confusing.
+
+Select is not Switch or Checkbox: Select chooses one value from many; Switch
+changes one immediate on/off setting; Checkbox represents an independent
+boolean or membership in a multi-select set.
+
+## Sizes
+
+- **Small** — dense toolbars and compact forms.
+- **Medium** — default.
+- **Large** — rare, high-emphasis selection.
+
+Trigger sizes align with Input sizes. Content width is at least sufficient for
+its items and may match the trigger. Use spacing and size tokens, not raw values.
+
+## States
+
+| State | Behavior |
+| --- | --- |
+| Default | Closed trigger shows selection or placeholder. |
+| Hover | Trigger and enabled item show a quiet interactive emphasis. |
+| Focus | Trigger or focused item has a visible `--color-focus` indicator. |
+| Active/open | Trigger exposes `data-state="open"`; content is visible and the current keyboard item is distinct from the selected item. |
+| Disabled | Trigger cannot open; disabled items cannot be selected. Uses `--color-disabled`. |
+| Loading | Trigger remains stable, shows Spinner/status, and does not present stale options as ready. |
+| Error | Trigger uses `aria-invalid="true"`, danger treatment, and linked ValidationMessage. |
+
+Loading is not disabled. Loading says options are being resolved; disabled says
+selection is unavailable. If loading prevents opening, announce why and retain
+the current value.
+
+## Accessibility
+
+- Associate the trigger with Label through `for`/`id` where the implementation
+  supports it, or an equivalent `aria-labelledby` relationship without
+  duplicating the accessible name.
+- The Radix implementation supplies button/listbox semantics, active descendant
+  management, portalling, and typeahead. Preserve them.
+- Link HelperText and ValidationMessage via `aria-describedby`; expose invalid,
+  required, disabled, and busy states programmatically.
+- Keyboard: `Enter`, `Space`, or supported arrow keys open; arrows move through
+  options; typeahead searches; `Enter`/`Space` selects; `Escape` closes and
+  returns focus; `Home`/`End` move to bounds where supported.
+- Focus returns to the trigger after selection or dismissal. Selection is not
+  committed merely by moving focus through items.
+
+## When to use
+
+- For one choice from a known set where a collapsed list saves meaningful space.
+- When options are short, comparable labels.
+- When Radix Select's custom presentation is needed consistently across themes.
+
+## When NOT to use
+
+- Do not use for multiple choices; use Checkbox controls or a dedicated
+  multi-select pattern.
+- Do not use for one boolean setting; use Switch.
+- Do not hide two or three important options when visible choices would be
+  faster to compare.
+- Do not use as autocomplete for a very large or remote dataset without a
+  dedicated combobox/search pattern.
+
+## Tokens
+
+Trigger uses the Input token mapping. Content uses `--color-elevated-surface`,
+`--color-foreground`, `--color-border`, `--shadow-sm`, and `--radius-md`;
+focused/selected items use `--color-accent` or `--color-primary` according to
+hierarchy, focus uses `--color-focus`, and error uses `--color-danger`. List
+padding uses `--spacing-xs`, item padding uses `--spacing-sm` block and
+`--spacing-md` inline, and transitions use `--motion-duration-fast` with
+`--motion-easing-standard`.
+
+## Radix/shadcn mapping
+
+Maps to [Radix Select](https://www.radix-ui.com/primitives/docs/components/select)
+and [shadcn/ui Select](https://ui.shadcn.com/docs/components/select). Keep the
+Radix parts and behavior as the reference contract; shadcn supplies the common
+composition and styling baseline.