@molecule/app-ui 1.3.4 → 1.3.6

package/README.md

@@ -3,7 +3,7 @@ AUTO-GENERATED — DO NOT EDIT THIS FILE.
 Generated by `mlcl sync-docs` from the package's src/index.ts JSDoc + mlcl/registry.json.
 Edits here are overwritten on the next commit (molecule's pre-commit hook regenerates).
 To change this document, edit the module-level JSDoc in src/index.ts.
-Generated: 2026-09-28T12:35:38.435Z
+Generated: 2026-10-16T00:52:21.894Z
 -->
 
 # @molecule/app-ui
@@ -44,421 +44,600 @@ npm install @molecule/app-ui @molecule/app-bond @molecule/app-i18n
 
 ### Interfaces
 
-#### `AccordionClassOptions`
+#### `UIProvider`
 
-Options for resolving accordion CSS classes via UIClassMap.
+Identifies the bonded UI styling library. Providers set `name`
+to indicate which library is active (e.g. `"tailwind"`, `"bootstrap"`).
 
 ```typescript
-interface AccordionClassOptions {
-  variant?: string
+interface UIProvider {
+  /**
+   * Identifier for the styling library (e.g. `"tailwind"`, `"ionic"`).
+   */
+  name: string
 }
 ```
 
-#### `AccordionItem`
+#### `MoleculeSpinnerTimings`
 
-A single item in an Accordion component.
+The mark's timings, in CSS duration strings. Swap cycle → glint cycle.
 
 ```typescript
-interface AccordionItem<T = string> {
-  /**
-   * Item value/id.
-   */
-  value: T
+interface MoleculeSpinnerTimings {
+  /** One full 3-phase atom-swap cycle (also drives bond fades + glints). */
+  dur: string
+  /** Whole-figure rotation. Keep at two swap cycles for the intended feel. */
+  spin: string
+  /** Bond gradient flow period (one full translate across the figure). */
+  flow: string
+}
+```
 
-  /**
-   * Item header/trigger.
-   */
-  header: Children
+#### `MoleculeSpinnerColors`
 
-  /**
-   * Item content.
-   */
-  content: Children
+Gradient-mode colors. Any CSS color string, including `var()` forms.
 
+```typescript
+interface MoleculeSpinnerColors {
+  /** Bond base / glint tail color. */
+  blue?: string
+  /** Flow highlight / glint head color at rest. */
+  light?: string
+  /** Glint ignition color while an atom is in flight. */
+  peach?: string
+}
+```
+
+#### `MoleculeSpinnerMarkOptions`
+
+Options for {@link moleculeSpinnerMarkSvg}.
+
+```typescript
+interface MoleculeSpinnerMarkOptions {
+  /** Motion timings; defaults to the shipped design (2.5s / 5s / 3s). */
+  timings?: Partial<MoleculeSpinnerTimings>
+  /** `gradient` (default) or `mono` — plain `currentColor` outline, no defs. */
+  paint?: 'gradient' | 'mono'
+  /** Gradient-mode colors; default the `var(--mol-spin-*, fallback)` set. */
+  colors?: MoleculeSpinnerColors
   /**
-   * Whether the item is disabled.
+   * Gradient id for url() references. Must be unique per rendered instance
+   * on a page. Defaults to `mol-spinner-gradient`.
    */
-  disabled?: boolean
+  gradientId?: string
+  /** Pixel size baked into width/height; omit when CSS sizes the svg. */
+  size?: number
+  /** Class attribute for the svg element. */
+  className?: string
+  /** Inline style attribute (already serialized, e.g. `color:re$d`). */
+  style?: string
+  /** Announce as `role="status"` with this label; omit for `aria-hidden`. */
+  ariaLabel?: string
 }
 ```
 
-#### `AccordionProps`
+#### `CSSProperties`
 
-Props for the Accordion component.
+Framework-agnostic CSS properties.
+Mirrors React.CSSProperties but without React dependency.
 
 ```typescript
-interface AccordionProps<T = string> extends BaseProps {
+interface CSSProperties {
+  [key: string]: string | number | undefined
+}
+```
+
+#### `BaseProps`
+
+Base props shared by all components.
+
+```typescript
+interface BaseProps {
   /**
-   * Accordion items.
+   * Additional CSS class name(s).
    */
-  items: AccordionItem<T>[]
+  className?: string
 
   /**
-   * Expanded item(s).
+   * Inline styles.
    */
-  value?: T | T[]
+  style?: CSSProperties
 
   /**
-   * Default expanded item(s).
+   * Test ID for automated testing.
    */
-  defaultValue?: T | T[]
+  testId?: string
 
   /**
-   * Change handler.
+   * Automation ID for AI agents and E2E tests. Maps to the `data-mol-id`
+   * HTML attribute. Use `molId()` from `./automation.js` to generate
+   * semantic IDs. (Tooling only — screen readers do not expose `data-*`
+   * attributes; accessible names come from labels/`aria-*`.)
    */
-  onChange?: (value: T | T[]) => void
+  automationId?: string
 
   /**
-   * Whether multiple items can be expanded.
+   * Whether the component is disabled.
    */
-  multiple?: boolean
+  disabled?: boolean
+}
+```
+
+#### `HTMLElementProps`
+
+Base props for HTML elements.
+Framework bindings should extend this with framework-specific attributes.
 
+```typescript
+interface HTMLElementProps extends BaseProps {
+  id?: string
+  title?: string
+  tabIndex?: number
+  role?: string
+  'aria-label'?: string
+  'aria-labelledby'?: string
+  'aria-describedby'?: string
+  'aria-hidden'?: boolean
+  'aria-disabled'?: boolean
+  'aria-expanded'?: boolean
+  'aria-selected'?: boolean
+  'aria-checked'?: boolean | 'mixed'
+  'aria-pressed'?: boolean | 'mixed'
+  'aria-invalid'?: boolean
+  'aria-required'?: boolean
+  'aria-readonly'?: boolean
+  'aria-busy'?: boolean
+  'aria-live'?: 'off' | 'polite' | 'assertive'
+  onClick?: MouseEventHandler
+  onDoubleClick?: MouseEventHandler
+  onMouseEnter?: MouseEventHandler
+  onMouseLeave?: MouseEventHandler
+  onFocus?: FocusEventHandler
+  onBlur?: FocusEventHandler
+  onKeyDown?: KeyboardEventHandler
+  onKeyUp?: KeyboardEventHandler
+  onKeyPress?: KeyboardEventHandler
+}
+```
+
+#### `InputElementProps`
+
+Base props for input elements.
+
+```typescript
+interface InputElementProps extends HTMLElementProps {
+  name?: string
+  value?: string | number | readonly string[]
+  defaultValue?: string | number | readonly string[]
+  placeholder?: string
+  required?: boolean
+  readOnly?: boolean
+  autoFocus?: boolean
+  autoComplete?: string
+  maxLength?: number
+  minLength?: number
+  pattern?: string
+  onChange?: ChangeEventHandler
+  onInput?: FormEventHandler
+}
+```
+
+#### `ButtonElementProps`
+
+Base props for button elements.
+
+```typescript
+interface ButtonElementProps extends HTMLElementProps {
   /**
-   * Whether items can be collapsed.
+   * Defaults to `'button'` in every framework binding, so a button never submits a
+   * form by accident. A form's primary action must set `type="submit"`: Enter then
+   * submits the form, and tests that select `button[type="submit"]` find it.
    */
-  collapsible?: boolean
+  type?: 'button' | 'submit' | 'reset'
+  name?: string
+  value?: string
+  form?: string
 }
 ```
 
-#### `AlertClassOptions`
+#### `TextareaElementProps`
 
-Options for resolving alert CSS classes via UIClassMap.
+Base props for textarea elements.
 
 ```typescript
-interface AlertClassOptions {
-  variant?: 'default' | 'info' | 'success' | 'warning' | 'error'
+interface TextareaElementProps extends HTMLElementProps {
+  name?: string
+  value?: string
+  defaultValue?: string
+  placeholder?: string
+  required?: boolean
+  readOnly?: boolean
+  autoFocus?: boolean
+  rows?: number
+  cols?: number
+  maxLength?: number
+  minLength?: number
+  wrap?: 'hard' | 'soft' | 'off'
+  onChange?: ChangeEventHandler
+  onInput?: FormEventHandler
 }
 ```
 
-#### `AlertProps`
+#### `SelectElementProps`
 
-Props for the Alert component.
+Base props for select elements.
 
 ```typescript
-interface AlertProps extends HTMLElementProps {
+interface SelectElementProps extends HTMLElementProps {
+  name?: string
+  required?: boolean
+  autoFocus?: boolean
+  multiple?: boolean
+  onChange?: ChangeEventHandler
+}
+```
+
+#### `FormElementProps`
+
+Base props for form elements.
+
+```typescript
+interface FormElementProps extends HTMLElementProps {
+  action?: string
+  method?: 'get' | 'post'
+  encType?: string
+  target?: string
+  noValidate?: boolean
+  autoComplete?: 'on' | 'off'
+  onSubmit?: FormEventHandler
+  onReset?: FormEventHandler
+}
+```
+
+#### `ButtonProps`
+
+Props for the Button component.
+
+```typescript
+interface ButtonProps extends ButtonElementProps {
   /**
-   * Alert content.
+   * Button content.
    */
   children?: Children
 
   /**
-   * Alert title.
+   * Visual variant.
    */
-  title?: string
+  variant?: ButtonVariant
 
   /**
-   * Alert status/type.
+   * Color scheme.
    */
-  status?: ColorVariant
+  color?: ColorVariant
 
   /**
-   * Alert variant.
+   * Button size.
    */
-  variant?: 'solid' | 'subtle' | 'outline' | 'left-accent'
+  size?: ButtonSize
 
   /**
-   * Whether the alert is dismissible.
+   * Whether the button is in a loading state.
    */
-  dismissible?: boolean
+  loading?: boolean
 
   /**
-   * Called when dismissed.
+   * Loading text to display.
    */
-  onDismiss?: () => void
+  loadingText?: string
 
   /**
-   * Icon to display.
+   * Whether the button takes full width.
    */
-  icon?: Children
+  fullWidth?: boolean
 
   /**
-   * Accessible label for the dismiss button.
-   * @default 'Dismiss'
+   * Icon to display before the label.
    */
-  dismissLabel?: string
+  leftIcon?: Children
+
+  /**
+   * Icon to display after the label.
+   */
+  rightIcon?: Children
 }
 ```
 
-#### `AvatarClassOptions`
+#### `InputProps`
 
-Options for resolving avatar CSS classes via UIClassMap.
+Props for the Input component (text field, email, password, etc.).
 
 ```typescript
-interface AvatarClassOptions {
+interface InputProps extends InputElementProps {
+  /**
+   * Input type.
+   */
+  type?: InputType
+
+  /**
+   * Input size.
+   */
   size?: Size
-}
-```
 
-#### `AvatarProps`
+  /**
+   * Horizontal text alignment inside the input (see
+   * {@link InputClassOptions.align}). Defaults to the bond's own style.
+   */
+  align?: 'left' | 'center'
+
+  /**
+   * Label text.
+   */
+  label?: string
 
-Props for the Avatar component.
+  /**
+   * Error message.
+   */
+  error?: string
 
-```typescript
-interface AvatarProps extends HTMLElementProps {
   /**
-   * Image source URL.
+   * Hint/help text.
    */
-  src?: string
+  hint?: string
 
   /**
-   * Alt text for the image.
+   * Element to display on the left.
    */
-  alt?: string
+  leftElement?: Children
 
   /**
-   * Name for fallback initials.
+   * Element to display on the right.
    */
-  name?: string
+  rightElement?: Children
 
   /**
-   * Avatar size.
+   * Whether to show a clear button.
    */
-  size?: Size | number
+  clearable?: boolean
 
   /**
-   * Whether the avatar is rounded.
+   * Called when the clear button is clicked.
    */
-  rounded?: boolean
+  onClear?: () => void
 
   /**
-   * Fallback element when no image.
+   * Accessible label for the clear button.
+   * @default 'Clear'
    */
-  fallback?: Children
+  clearLabel?: string
 }
 ```
 
-#### `BadgeClassOptions`
+#### `TextareaProps`
 
-Options for resolving badge CSS classes via UIClassMap.
+Props for the Textarea component.
 
 ```typescript
-interface BadgeClassOptions {
-  variant?: ColorVariant
+interface TextareaProps extends TextareaElementProps {
+  /**
+   * Text size tier (see {@link TextareaClassOptions.size}) — pass the same
+   * `size` as a neighboring Input for identical font sizes.
+   */
   size?: Size
-}
-```
 
-#### `BadgeProps`
-
-Props for the Badge component (status labels, counts, tags).
+  /**
+   * Label text.
+   */
+  label?: string
 
-```typescript
-interface BadgeProps extends HTMLElementProps {
   /**
-   * Badge content.
+   * Error message.
    */
-  children?: Children
+  error?: string
 
   /**
-   * Badge color.
+   * Hint/help text.
    */
-  color?: ColorVariant
+  hint?: string
 
   /**
-   * Badge variant.
+   * Whether the textarea auto-resizes.
    */
-  variant?: 'solid' | 'outline' | 'subtle'
+  autoResize?: boolean
 
   /**
-   * Badge size.
+   * Minimum number of rows.
    */
-  size?: Size
+  minRows?: number
 
   /**
-   * Whether the badge is rounded.
+   * Maximum number of rows.
    */
-  rounded?: boolean
+  maxRows?: number
 }
 ```
 
-#### `BaseProps`
+#### `SelectOption`
 
-Base props shared by all components.
+A single option in a Select dropdown.
 
 ```typescript
-interface BaseProps {
-  /**
-   * Additional CSS class name(s).
-   */
-  className?: string
-
+interface SelectOption<T = string> {
   /**
-   * Inline styles.
+   * Option value.
    */
-  style?: CSSProperties
+  value: T
 
   /**
-   * Test ID for automated testing.
+   * Display label.
    */
-  testId?: string
+  label: string
 
   /**
-   * Automation ID for AI agents and E2E tests. Maps to the `data-mol-id`
-   * HTML attribute. Use `molId()` from `./automation.js` to generate
-   * semantic IDs. (Tooling only — screen readers do not expose `data-*`
-   * attributes; accessible names come from labels/`aria-*`.)
+   * Whether the option is disabled.
    */
-  automationId?: string
+  disabled?: boolean
 
   /**
-   * Whether the component is disabled.
+   * Option group (for grouped selects).
    */
-  disabled?: boolean
-}
-```
-
-#### `ButtonClassOptions`
-
-Options for resolving button CSS classes via UIClassMap.
-
-```typescript
-interface ButtonClassOptions {
-  variant?: ButtonVariant
-  color?: ColorVariant
-  size?: ButtonSize
-  fullWidth?: boolean
-}
-```
-
-#### `ButtonElementProps`
-
-Base props for button elements.
-
-```typescript
-interface ButtonElementProps extends HTMLElementProps {
-  type?: 'button' | 'submit' | 'reset'
-  name?: string
-  value?: string
-  form?: string
+  group?: string
 }
 ```
 
-#### `ButtonProps`
+#### `SelectProps`
 
-Props for the Button component.
+Props for the Select dropdown component (single or multi-select).
 
 ```typescript
-interface ButtonProps extends ButtonElementProps {
+interface SelectProps<T = string> extends SelectElementProps {
   /**
-   * Button content.
+   * Select options.
    */
-  children?: Children
+  options: SelectOption<T>[]
 
   /**
-   * Visual variant.
+   * Current value.
    */
-  variant?: ButtonVariant
+  value?: T
 
   /**
-   * Color scheme.
+   * Change handler (with typed value).
    */
-  color?: ColorVariant
+  onValueChange?: (value: T) => void
 
   /**
-   * Button size.
+   * Select size.
    */
-  size?: ButtonSize
+  size?: Size
 
   /**
-   * Whether the button is in a loading state.
+   * Label text.
    */
-  loading?: boolean
+  label?: string
 
   /**
-   * Loading text to display.
+   * Placeholder text.
    */
-  loadingText?: string
+  placeholder?: string
 
   /**
-   * Whether the button takes full width.
+   * Error message.
    */
-  fullWidth?: boolean
+  error?: string
 
   /**
-   * Icon to display before the label.
+   * Hint/help text.
    */
-  leftIcon?: Children
+  hint?: string
 
   /**
-   * Icon to display after the label.
+   * Whether to allow clearing the selection.
    */
-  rightIcon?: Children
+  clearable?: boolean
 }
 ```
 
-#### `CardClassOptions`
+#### `CheckboxProps`
 
-Options for resolving card CSS classes via UIClassMap.
+Props for the Checkbox component.
 
 ```typescript
-interface CardClassOptions {
-  variant?: 'default' | 'elevated' | 'outline' | 'ghost'
-}
-```
-
-#### `CardProps`
-
-Props for the Card container component (elevated, outlined, or filled surface).
+interface CheckboxProps extends InputElementProps {
+  /**
+   * Checkbox label.
+   */
+  label?: Children
 
-```typescript
-interface CardProps extends HTMLElementProps {
   /**
-   * Card content.
+   * Whether the checkbox is checked.
    */
-  children?: Children
+  checked?: boolean
 
   /**
-   * Card variant.
+   * Whether the checkbox is in an indeterminate state.
    */
-  variant?: 'elevated' | 'outlined' | 'filled'
+  indeterminate?: boolean
 
   /**
-   * Whether the card is interactive (clickable).
+   * Checkbox size.
    */
-  interactive?: boolean
+  size?: Size
 
   /**
-   * Padding size.
+   * Error message.
    */
-  padding?: Size | 'none'
+  error?: string
 }
 ```
 
-#### `CheckboxClassOptions`
+#### `RadioOption`
 
-Options for resolving checkbox CSS classes via UIClassMap.
+A single option in a RadioGroup.
 
 ```typescript
-interface CheckboxClassOptions {
-  error?: boolean
+interface RadioOption<T = string> {
+  /**
+   * Option value.
+   */
+  value: T
+
+  /**
+   * Display label.
+   */
+  label: Children
+
+  /**
+   * Whether the option is disabled.
+   */
+  disabled?: boolean
 }
 ```
 
-#### `CheckboxProps`
+#### `RadioGroupProps`
 
-Props for the Checkbox component.
+Props for the RadioGroup component.
 
 ```typescript
-interface CheckboxProps extends InputElementProps {
+interface RadioGroupProps<T = string> extends BaseProps {
   /**
-   * Checkbox label.
+   * Radio options.
    */
-  label?: Children
+  options: RadioOption<T>[]
+
+  /**
+   * Current value.
+   */
+  value?: T
+
+  /**
+   * Change handler.
+   */
+  onChange?: (value: T) => void
+
+  /**
+   * Radio size.
+   */
+  size?: Size
 
   /**
-   * Whether the checkbox is checked.
+   * Group label.
    */
-  checked?: boolean
+  label?: string
 
   /**
-   * Whether the checkbox is in an indeterminate state.
+   * Shared `name` attribute for the group's radio inputs (used for native
+   * form submission). When omitted, a unique per-instance name is generated
+   * so separate groups never merge — the visible `label` is deliberately
+   * NOT used as the name, because two groups with the same label (e.g. two
+   * "Size" pickers) would otherwise form ONE native radio group and
+   * deselect each other.
    */
-  indeterminate?: boolean
+  name?: string
 
   /**
-   * Checkbox size.
+   * Layout direction.
    */
-  size?: Size
+  direction?: 'horizontal' | 'vertical'
 
   /**
    * Error message.
@@ -467,967 +646,854 @@ interface CheckboxProps extends InputElementProps {
 }
 ```
 
-#### `ContainerClassOptions`
-
-Options for container class resolution.
-
-```typescript
-interface ContainerClassOptions {
-  size?: Size | '2xl' | 'full'
-}
-```
-
-#### `ContainerProps`
+#### `SwitchProps`
 
-Props for the Container layout component.
+Props for the Switch/Toggle component.
 
 ```typescript
-interface ContainerProps extends HTMLElementProps {
+interface SwitchProps extends InputElementProps {
   /**
-   * Container content.
+   * Switch label.
    */
-  children?: Children
+  label?: Children
 
   /**
-   * Maximum width.
+   * Whether the switch is on.
    */
-  maxWidth?: 'sm' | 'md' | 'lg' | 'xl' | '2xl' | 'full' | string
+  checked?: boolean
 
   /**
-   * Whether to center the container.
+   * Switch size.
    */
-  centered?: boolean
+  size?: Size
 
   /**
-   * Horizontal padding.
+   * Color when on.
    */
-  paddingX?: Size | string
-}
-```
-
-#### `CSSProperties`
-
-Framework-agnostic CSS properties.
-Mirrors React.CSSProperties but without React dependency.
-
-```typescript
-interface CSSProperties {
-  [key: string]: string | number | undefined
+  color?: ColorVariant
 }
 ```
 
-#### `DropdownItem`
+#### `ModalProps`
 
-Dropdown menu item.
+Props for the Modal/Dialog component.
 
 ```typescript
-interface DropdownItem<T = string> {
+interface ModalProps extends HTMLElementProps {
   /**
-   * Item value/id.
+   * Whether the modal is open.
    */
-  value: T
+  open: boolean
 
   /**
-   * Display label.
+   * Called when the modal should close.
    */
-  label: Children
+  onClose: () => void
 
   /**
-   * Whether the item is disabled.
+   * Modal title.
    */
-  disabled?: boolean
+  title?: string
 
   /**
-   * Icon to display.
+   * Modal content.
    */
-  icon?: Children
+  children?: Children
 
   /**
-   * Keyboard shortcut display.
+   * Modal size.
    */
-  shortcut?: string
+  size?: ModalSize
 
   /**
-   * Whether this is a separator.
+   * Whether to show a close button.
    */
-  separator?: boolean
+  showCloseButton?: boolean
 
   /**
-   * Nested items (for submenus).
+   * Whether clicking the overlay closes the modal.
    */
-  items?: DropdownItem<T>[]
-}
-```
-
-#### `DropdownProps`
+  closeOnOverlayClick?: boolean
 
-Props for the Dropdown menu component.
+  /**
+   * Whether pressing Escape closes the modal.
+   */
+  closeOnEscape?: boolean
 
-```typescript
-interface DropdownProps<T = string> extends BaseProps {
   /**
-   * Dropdown trigger element.
+   * Footer content (typically action buttons).
    */
-  trigger: Children
+  footer?: Children
 
   /**
-   * Dropdown items.
+   * Whether the modal is centered vertically.
    */
-  items: DropdownItem<T>[]
+  centered?: boolean
 
   /**
-   * Called when an item is selected.
+   * Whether to prevent body scroll when open.
    */
-  onSelect?: (value: T) => void
+  preventScroll?: boolean
 
   /**
-   * Dropdown placement.
+   * Accessible label for the close button.
+   * @default 'Close'
    */
-  placement?:
-    'top' | 'top-start' | 'top-end' | 'bottom' | 'bottom-start' | 'bottom-end' | 'left' | 'right'
+  closeLabel?: string
+}
+```
+
+#### `SpinnerProps`
+
+Props for the Spinner/loading indicator component.
 
+```typescript
+interface SpinnerProps extends BaseProps {
   /**
-   * Whether the dropdown is open (controlled).
+   * Spinner size.
    */
-  open?: boolean
+  size?: Size
 
   /**
-   * Called when open state changes.
+   * Spinner color.
    */
-  onOpenChange?: (open: boolean) => void
+  color?: ColorVariant | string
 
   /**
-   * Menu alignment.
+   * Loading label (for accessibility).
    */
-  align?: 'start' | 'center' | 'end'
+  label?: string
 
   /**
-   * Menu width.
+   * Spinner thickness.
    */
-  width?: 'trigger' | 'auto' | number | string
+  thickness?: number
 }
 ```
 
-#### `EmptyStateProps`
+#### `AvatarProps`
 
-Props for the EmptyState component — shown when a list or section has no data.
+Props for the Avatar component.
 
 ```typescript
-interface EmptyStateProps extends BaseProps {
-  /** Icon or illustration to display. */
-  icon?: Children
-  /** Main heading text. */
-  title: string
-  /** Description text. */
-  description?: string
-  /** Primary action button (e.g., "Create first item"). */
-  action?: Children
-}
-```
+interface AvatarProps extends HTMLElementProps {
+  /**
+   * Image source URL.
+   */
+  src?: string
 
-#### `FlexClassOptions`
+  /**
+   * Alt text for the image.
+   */
+  alt?: string
 
-Options for flex class resolution.
+  /**
+   * Name for fallback initials.
+   */
+  name?: string
 
-```typescript
-interface FlexClassOptions {
-  direction?: 'row' | 'col' | 'row-reverse' | 'col-reverse'
-  align?: 'start' | 'center' | 'end' | 'stretch' | 'baseline'
-  justify?: 'start' | 'center' | 'end' | 'between' | 'around' | 'evenly'
-  wrap?: 'wrap' | 'nowrap' | 'wrap-reverse'
-  /** Named tokens or Tailwind spacing scale index (e.g. `3` → `gap-3`). */
-  gap?: 'none' | 'xs' | 'sm' | 'md' | 'lg' | 'xl' | number
+  /**
+   * Avatar size.
+   */
+  size?: Size | number
+
+  /**
+   * Whether the avatar is rounded.
+   */
+  rounded?: boolean
+
+  /**
+   * Fallback element when no image.
+   */
+  fallback?: Children
 }
 ```
 
-#### `FlexProps`
+#### `BadgeProps`
 
-Flex container props.
+Props for the Badge component (status labels, counts, tags).
 
 ```typescript
-interface FlexProps extends HTMLElementProps {
+interface BadgeProps extends HTMLElementProps {
   /**
-   * Flex content.
+   * Badge content.
    */
   children?: Children
 
   /**
-   * Flex direction.
-   */
-  direction?: 'row' | 'column' | 'row-reverse' | 'column-reverse'
-
-  /**
-   * Justify content.
+   * Badge color.
    */
-  justify?: 'start' | 'end' | 'center' | 'between' | 'around' | 'evenly'
+  color?: ColorVariant
 
   /**
-   * Align items.
+   * Badge variant.
    */
-  align?: 'start' | 'end' | 'center' | 'baseline' | 'stretch'
+  variant?: 'solid' | 'outline' | 'subtle'
 
   /**
-   * Flex wrap.
+   * Badge size.
    */
-  wrap?: 'wrap' | 'nowrap' | 'wrap-reverse'
+  size?: Size
 
   /**
-   * Gap between items.
+   * Whether the badge is rounded.
    */
-  gap?: Size | string | number
-}
-```
-
-#### `FormElementProps`
-
-Base props for form elements.
-
-```typescript
-interface FormElementProps extends HTMLElementProps {
-  action?: string
-  method?: 'get' | 'post'
-  encType?: string
-  target?: string
-  noValidate?: boolean
-  autoComplete?: 'on' | 'off'
-  onSubmit?: FormEventHandler
-  onReset?: FormEventHandler
+  rounded?: boolean
 }
 ```
 
-#### `FormFieldProps`
+#### `TooltipProps`
 
-Form field wrapper props.
+Props for the Tooltip component (hover/focus popover with informational text).
 
 ```typescript
-interface FormFieldProps extends HTMLElementProps {
-  /**
-   * Field content.
-   */
-  children?: Children
-
+interface TooltipProps extends HTMLElementProps {
   /**
-   * Field label.
+   * Tooltip content.
    */
-  label?: string
+  content: Children
 
   /**
-   * Field name.
+   * Element that triggers the tooltip.
    */
-  name?: string
+  children: Children
 
   /**
-   * Error message.
+   * Tooltip placement.
    */
-  error?: string
+  placement?: TooltipPlacement
 
   /**
-   * Hint/help text.
+   * Delay before showing (ms).
    */
-  hint?: string
+  delay?: number
 
   /**
-   * Whether the field is required.
+   * Whether the tooltip has an arrow.
    */
-  required?: boolean
+  hasArrow?: boolean
 }
 ```
 
-#### `FormProps`
+#### `CardProps`
 
-Props for the Form component (wraps inputs with submission handling and validation).
+Props for the Card container component (elevated, outlined, or filled surface).
 
 ```typescript
-interface FormProps extends FormElementProps {
+interface CardProps extends HTMLElementProps {
   /**
-   * Form content.
+   * Card content.
    */
   children?: Children
 
   /**
-   * Submit handler with form data.
+   * Card variant.
    */
-  onFormSubmit?: (data: Record<string, unknown>) => void | Promise<void>
+  variant?: 'elevated' | 'outlined' | 'filled'
 
   /**
-   * Whether the form is submitting.
+   * Whether the card is interactive (clickable).
    */
-  submitting?: boolean
-}
-```
-
-#### `GridClassOptions`
-
-Options for grid class resolution.
+  interactive?: boolean
 
-```typescript
-interface GridClassOptions {
-  cols?: number
-  /** Named tokens or Tailwind spacing scale index (e.g. `10` → `gap-10`). */
-  gap?: 'none' | 'xs' | 'sm' | 'md' | 'lg' | 'xl' | number
   /**
-   * Mobile-first responsive collapse. When omitted (the default), a grid of
-   * `cols >= 2` starts at a single column on small screens and steps up to
-   * `cols` at larger breakpoints, so cards don't overflow on mobile. Pass
-   * `false` for a FIXED `cols`-column grid at every viewport width. Ignored
-   * for `cols <= 1` (always single-column) and by ClassMap bonds without a
-   * breakpoint system (e.g. NativeWind).
+   * Padding size.
    */
-  responsive?: boolean
+  padding?: Size | 'none'
 }
 ```
 
-#### `GridProps`
+#### `ContainerProps`
 
-Grid container props.
+Props for the Container layout component.
 
 ```typescript
-interface GridProps extends HTMLElementProps {
+interface ContainerProps extends HTMLElementProps {
   /**
-   * Grid content.
+   * Container content.
    */
   children?: Children
 
   /**
-   * Number of columns.
-   */
-  columns?: number | string
-
-  /**
-   * Number of rows.
-   */
-  rows?: number | string
-
-  /**
-   * Gap between items.
+   * Maximum width.
    */
-  gap?: Size | string | number
+  maxWidth?: 'sm' | 'md' | 'lg' | 'xl' | '2xl' | 'full' | string
 
   /**
-   * Column gap.
+   * Whether to center the container.
    */
-  columnGap?: Size | string | number
+  centered?: boolean
 
   /**
-   * Row gap.
+   * Horizontal padding.
    */
-  rowGap?: Size | string | number
-}
-```
-
-#### `HTMLElementProps`
-
-Base props for HTML elements.
-Framework bindings should extend this with framework-specific attributes.
-
-```typescript
-interface HTMLElementProps extends BaseProps {
-  id?: string
-  title?: string
-  tabIndex?: number
-  role?: string
-  'aria-label'?: string
-  'aria-labelledby'?: string
-  'aria-describedby'?: string
-  'aria-hidden'?: boolean
-  'aria-disabled'?: boolean
-  'aria-expanded'?: boolean
-  'aria-selected'?: boolean
-  'aria-checked'?: boolean | 'mixed'
-  'aria-pressed'?: boolean | 'mixed'
-  'aria-invalid'?: boolean
-  'aria-required'?: boolean
-  'aria-readonly'?: boolean
-  'aria-busy'?: boolean
-  'aria-live'?: 'off' | 'polite' | 'assertive'
-  onClick?: MouseEventHandler
-  onDoubleClick?: MouseEventHandler
-  onMouseEnter?: MouseEventHandler
-  onMouseLeave?: MouseEventHandler
-  onFocus?: FocusEventHandler
-  onBlur?: FocusEventHandler
-  onKeyDown?: KeyboardEventHandler
-  onKeyUp?: KeyboardEventHandler
-  onKeyPress?: KeyboardEventHandler
+  paddingX?: Size | string
 }
 ```
 
-#### `InputClassOptions`
+#### `FlexProps`
 
-Options for resolving input CSS classes via UIClassMap.
+Flex container props.
 
 ```typescript
-interface InputClassOptions {
-  error?: boolean
-  size?: Size
+interface FlexProps extends HTMLElementProps {
   /**
-   * Horizontal text alignment inside the input. Bonds may default to a
-   * centered aesthetic (e.g. the Tailwind bond's floating-label style);
-   * `'left'` opts a specific field out — e.g. a form field sitting next to
-   * left-aligned textareas.
+   * Flex content.
    */
-  align?: 'left' | 'center'
-}
-```
-
-#### `InputElementProps`
-
-Base props for input elements.
-
-```typescript
-interface InputElementProps extends HTMLElementProps {
-  name?: string
-  value?: string | number | readonly string[]
-  defaultValue?: string | number | readonly string[]
-  placeholder?: string
-  required?: boolean
-  readOnly?: boolean
-  autoFocus?: boolean
-  autoComplete?: string
-  maxLength?: number
-  minLength?: number
-  pattern?: string
-  onChange?: ChangeEventHandler
-  onInput?: FormEventHandler
-}
-```
-
-#### `InputProps`
-
-Props for the Input component (text field, email, password, etc.).
+  children?: Children
 
-```typescript
-interface InputProps extends InputElementProps {
   /**
-   * Input type.
+   * Flex direction.
    */
-  type?: InputType
+  direction?: 'row' | 'column' | 'row-reverse' | 'column-reverse'
 
   /**
-   * Input size.
+   * Justify content.
    */
-  size?: Size
+  justify?: 'start' | 'end' | 'center' | 'between' | 'around' | 'evenly'
 
   /**
-   * Horizontal text alignment inside the input (see
-   * {@link InputClassOptions.align}). Defaults to the bond's own style.
+   * Align items.
    */
-  align?: 'left' | 'center'
+  align?: 'start' | 'end' | 'center' | 'baseline' | 'stretch'
 
   /**
-   * Label text.
+   * Flex wrap.
    */
-  label?: string
+  wrap?: 'wrap' | 'nowrap' | 'wrap-reverse'
 
   /**
-   * Error message.
+   * Gap between items.
    */
-  error?: string
+  gap?: Size | string | number
+}
+```
+
+#### `GridProps`
+
+Grid container props.
 
+```typescript
+interface GridProps extends HTMLElementProps {
   /**
-   * Hint/help text.
+   * Grid content.
    */
-  hint?: string
+  children?: Children
 
   /**
-   * Element to display on the left.
+   * Number of columns.
    */
-  leftElement?: Children
+  columns?: number | string
 
   /**
-   * Element to display on the right.
+   * Number of rows.
    */
-  rightElement?: Children
+  rows?: number | string
 
   /**
-   * Whether to show a clear button.
+   * Gap between items.
    */
-  clearable?: boolean
+  gap?: Size | string | number
 
   /**
-   * Called when the clear button is clicked.
+   * Column gap.
    */
-  onClear?: () => void
+  columnGap?: Size | string | number
 
   /**
-   * Accessible label for the clear button.
-   * @default 'Clear'
+   * Row gap.
    */
-  clearLabel?: string
-}
-```
-
-#### `LabelClassOptions`
-
-Options for label class resolution.
-
-```typescript
-interface LabelClassOptions {
-  required?: boolean
-}
-```
-
-#### `ModalClassOptions`
-
-Options for resolving modal/dialog CSS classes via UIClassMap.
-
-```typescript
-interface ModalClassOptions {
-  size?: ModalSize
+  rowGap?: Size | string | number
 }
 ```
 
-#### `ModalProps`
+#### `SpacerProps`
 
-Props for the Modal/Dialog component.
+Props for the Spacer layout component (adds whitespace between elements).
 
 ```typescript
-interface ModalProps extends HTMLElementProps {
-  /**
-   * Whether the modal is open.
-   */
-  open: boolean
-
+interface SpacerProps extends BaseProps {
   /**
-   * Called when the modal should close.
+   * Space size.
    */
-  onClose: () => void
+  size?: Size | string | number
 
   /**
-   * Modal title.
+   * Whether the spacer is horizontal.
    */
-  title?: string
+  horizontal?: boolean
+}
+```
+
+#### `FormProps`
+
+Props for the Form component (wraps inputs with submission handling and validation).
 
+```typescript
+interface FormProps extends FormElementProps {
   /**
-   * Modal content.
+   * Form content.
    */
   children?: Children
 
   /**
-   * Modal size.
+   * Submit handler with form data.
    */
-  size?: ModalSize
+  onFormSubmit?: (data: Record<string, unknown>) => void | Promise<void>
 
   /**
-   * Whether to show a close button.
+   * Whether the form is submitting.
    */
-  showCloseButton?: boolean
+  submitting?: boolean
+}
+```
+
+#### `FormFieldProps`
+
+Form field wrapper props.
 
+```typescript
+interface FormFieldProps extends HTMLElementProps {
   /**
-   * Whether clicking the overlay closes the modal.
+   * Field content.
    */
-  closeOnOverlayClick?: boolean
+  children?: Children
 
   /**
-   * Whether pressing Escape closes the modal.
+   * Field label.
    */
-  closeOnEscape?: boolean
+  label?: string
 
   /**
-   * Footer content (typically action buttons).
+   * Field name.
    */
-  footer?: Children
+  name?: string
 
   /**
-   * Whether the modal is centered vertically.
+   * Error message.
    */
-  centered?: boolean
+  error?: string
 
   /**
-   * Whether to prevent body scroll when open.
+   * Hint/help text.
    */
-  preventScroll?: boolean
+  hint?: string
 
   /**
-   * Accessible label for the close button.
-   * @default 'Close'
+   * Whether the field is required.
    */
-  closeLabel?: string
-}
-```
-
-#### `MoleculeSpinnerColors`
-
-Gradient-mode colors. Any CSS color string, including `var()` forms.
-
-```typescript
-interface MoleculeSpinnerColors {
-  /** Bond base / glint tail color. */
-  blue?: string
-  /** Flow highlight / glint head color at rest. */
-  light?: string
-  /** Glint ignition color while an atom is in flight. */
-  peach?: string
+  required?: boolean
 }
 ```
 
-#### `MoleculeSpinnerMarkOptions`
+#### `AlertProps`
 
-Options for {@link moleculeSpinnerMarkSvg}.
+Props for the Alert component.
 
 ```typescript
-interface MoleculeSpinnerMarkOptions {
-  /** Motion timings; defaults to the shipped design (2.5s / 5s / 3s). */
-  timings?: Partial<MoleculeSpinnerTimings>
-  /** `gradient` (default) or `mono` — plain `currentColor` outline, no defs. */
-  paint?: 'gradient' | 'mono'
-  /** Gradient-mode colors; default the `var(--mol-spin-*, fallback)` set. */
-  colors?: MoleculeSpinnerColors
+interface AlertProps extends HTMLElementProps {
   /**
-   * Gradient id for url() references. Must be unique per rendered instance
-   * on a page. Defaults to `mol-spinner-gradient`.
+   * Alert content.
    */
-  gradientId?: string
-  /** Pixel size baked into width/height; omit when CSS sizes the svg. */
-  size?: number
-  /** Class attribute for the svg element. */
-  className?: string
-  /** Inline style attribute (already serialized, e.g. `color:re$d`). */
-  style?: string
-  /** Announce as `role="status"` with this label; omit for `aria-hidden`. */
-  ariaLabel?: string
-}
-```
-
-#### `MoleculeSpinnerTimings`
-
-The mark's timings, in CSS duration strings. Swap cycle → glint cycle.
-
-```typescript
-interface MoleculeSpinnerTimings {
-  /** One full 3-phase atom-swap cycle (also drives bond fades + glints). */
-  dur: string
-  /** Whole-figure rotation. Keep at two swap cycles for the intended feel. */
-  spin: string
-  /** Bond gradient flow period (one full translate across the figure). */
-  flow: string
-}
-```
-
-#### `PageHeaderProps`
-
-Props for the PageHeader component — consistent page title area.
+  children?: Children
 
-```typescript
-interface PageHeaderProps extends BaseProps {
-  /** Page title. */
-  title: string
-  /** Page description. */
-  description?: string
-  /** Action buttons (e.g., "Create", "Export"). */
-  actions?: Children
-  /** Breadcrumb trail. */
-  breadcrumbs?: Array<{ label: string; href?: string }>
-}
-```
+  /**
+   * Alert title.
+   */
+  title?: string
 
-#### `PageShellProps`
+  /**
+   * Alert status/type.
+   */
+  status?: ColorVariant
 
-Props for the PageShell component — authenticated page wrapper with navigation.
+  /**
+   * Alert variant.
+   */
+  variant?: 'solid' | 'subtle' | 'outline' | 'left-accent'
 
-```typescript
-interface PageShellProps extends BaseProps {
-  /** Sidebar content (navigation links). */
-  sidebar?: Children
-  /** Top bar content (breadcrumbs, user menu). */
-  topbar?: Children
-  /** Whether the sidebar is collapsed. */
-  sidebarCollapsed?: boolean
-  /** Callback when sidebar toggle is clicked. */
-  onSidebarToggle?: () => void
-  /** Main content. */
-  children?: Children
-}
-```
+  /**
+   * Whether the alert is dismissible.
+   */
+  dismissible?: boolean
 
-#### `PaginationClassOptions`
+  /**
+   * Called when dismissed.
+   */
+  onDismiss?: () => void
 
-Options for pagination item class resolution.
+  /**
+   * Icon to display.
+   */
+  icon?: Children
 
-```typescript
-interface PaginationClassOptions {
-  active?: boolean
-  size?: Size
+  /**
+   * Accessible label for the dismiss button.
+   * @default 'Dismiss'
+   */
+  dismissLabel?: string
 }
 ```
 
-#### `PaginationProps`
+#### `ToastProps`
 
-Props for the Pagination component (page navigation with current page, total, page size, and change callbacks).
+Props for the Toast/notification component.
 
 ```typescript
-interface PaginationProps extends BaseProps {
+interface ToastProps extends HTMLElementProps {
   /**
-   * Current page (1-indexed).
+   * Toast content.
    */
-  page: number
+  children?: Children
 
   /**
-   * Total number of pages.
+   * Toast title.
    */
-  totalPages: number
+  title?: string
 
   /**
-   * Page change handler.
+   * Toast description.
    */
-  onChange: (page: number) => void
+  description?: string
 
   /**
-   * Number of sibling pages to show.
+   * Toast status/type.
    */
-  siblings?: number
+  status?: ColorVariant
 
   /**
-   * Number of boundary pages to show.
+   * Duration in milliseconds (0 for persistent).
    */
-  boundaries?: number
+  duration?: number
 
   /**
-   * Pagination size.
+   * Whether the toast is dismissible.
    */
-  size?: Size
+  dismissible?: boolean
 
   /**
-   * Whether to show first/last buttons.
+   * Called when dismissed.
    */
-  showFirstLast?: boolean
+  onDismiss?: () => void
 
   /**
-   * Whether to show previous/next buttons.
+   * Toast position.
    */
-  showPrevNext?: boolean
+  position?: 'top' | 'top-right' | 'top-left' | 'bottom' | 'bottom-right' | 'bottom-left'
 
   /**
-   * Accessible labels for pagination controls.
+   * Accessible label for the close button.
+   * @default 'Close'
    */
-  labels?: {
-    nav?: string
-    first?: string
-    previous?: string
-    next?: string
-    last?: string
-    goToPage?: (page: number) => string
-  }
+  closeLabel?: string
 }
 ```
 
-#### `RadioClassOptions`
+#### `TabItem`
 
-Options for resolving radio CSS classes via UIClassMap.
+A single tab in a Tabs component.
 
 ```typescript
-interface RadioClassOptions {
-  error?: boolean
+interface TabItem<T = string> {
+  /**
+   * Tab value/id.
+   */
+  value: T
+
+  /**
+   * Tab label.
+   */
+  label: Children
+
+  /**
+   * Tab content.
+   */
+  content?: Children
+
+  /**
+   * Whether the tab is disabled.
+   */
+  disabled?: boolean
+
+  /**
+   * Icon to display.
+   */
+  icon?: Children
 }
 ```
 
-#### `RadioGroupProps`
+#### `TabsProps`
 
-Props for the RadioGroup component.
+Props for the Tabs component (switchable tabbed content panels).
 
 ```typescript
-interface RadioGroupProps<T = string> extends BaseProps {
+interface TabsProps<T = string> extends BaseProps {
   /**
-   * Radio options.
+   * Tab items.
    */
-  options: RadioOption<T>[]
+  items: TabItem<T>[]
 
   /**
-   * Current value.
+   * Current active tab.
    */
   value?: T
 
   /**
-   * Change handler.
-   */
-  onChange?: (value: T) => void
-
-  /**
-   * Radio size.
+   * Default active tab.
    */
-  size?: Size
+  defaultValue?: T
 
   /**
-   * Group label.
+   * Change handler.
    */
-  label?: string
+  onChange?: (value: T) => void
 
   /**
-   * Shared `name` attribute for the group's radio inputs (used for native
-   * form submission). When omitted, a unique per-instance name is generated
-   * so separate groups never merge — the visible `label` is deliberately
-   * NOT used as the name, because two groups with the same label (e.g. two
-   * "Size" pickers) would otherwise form ONE native radio group and
-   * deselect each other.
+   * Tab variant.
    */
-  name?: string
+  variant?: 'line' | 'enclosed' | 'soft-rounded' | 'solid-rounded'
 
   /**
-   * Layout direction.
+   * Tab size.
    */
-  direction?: 'horizontal' | 'vertical'
+  size?: Size
 
   /**
-   * Error message.
+   * Whether tabs are fitted (take full width).
    */
-  error?: string
+  fitted?: boolean
 }
 ```
 
-#### `RadioOption`
+#### `AccordionItem`
 
-A single option in a RadioGroup.
+A single item in an Accordion component.
 
 ```typescript
-interface RadioOption<T = string> {
+interface AccordionItem<T = string> {
   /**
-   * Option value.
+   * Item value/id.
    */
   value: T
 
   /**
-   * Display label.
+   * Item header/trigger.
    */
-  label: Children
+  header: Children
 
   /**
-   * Whether the option is disabled.
+   * Item content.
+   */
+  content: Children
+
+  /**
+   * Whether the item is disabled.
    */
   disabled?: boolean
 }
 ```
 
-#### `SelectClassOptions`
+#### `AccordionProps`
 
-Options for resolving select CSS classes via UIClassMap.
+Props for the Accordion component.
 
 ```typescript
-interface SelectClassOptions {
-  error?: boolean
-  size?: Size
-}
-```
+interface AccordionProps<T = string> extends BaseProps {
+  /**
+   * Accordion items.
+   */
+  items: AccordionItem<T>[]
 
-#### `SelectElementProps`
+  /**
+   * Expanded item(s).
+   */
+  value?: T | T[]
 
-Base props for select elements.
+  /**
+   * Default expanded item(s).
+   */
+  defaultValue?: T | T[]
 
-```typescript
-interface SelectElementProps extends HTMLElementProps {
-  name?: string
-  required?: boolean
-  autoFocus?: boolean
+  /**
+   * Change handler.
+   */
+  onChange?: (value: T | T[]) => void
+
+  /**
+   * Whether multiple items can be expanded.
+   */
   multiple?: boolean
-  onChange?: ChangeEventHandler
+
+  /**
+   * Whether items can be collapsed.
+   */
+  collapsible?: boolean
 }
 ```
 
-#### `SelectOption`
+#### `TableColumn`
 
-A single option in a Select dropdown.
+Table column definition.
 
 ```typescript
-interface SelectOption<T = string> {
+interface TableColumn<T> {
   /**
-   * Option value.
+   * Column key (data property).
    */
-  value: T
+  key: keyof T | string
 
   /**
-   * Display label.
+   * Column header.
    */
-  label: string
+  header: Children
 
   /**
-   * Whether the option is disabled.
+   * Custom cell renderer.
    */
-  disabled?: boolean
+  render?: (value: unknown, row: T, index: number) => Children
 
   /**
-   * Option group (for grouped selects).
+   * Column width.
    */
-  group?: string
+  width?: string | number
+
+  /**
+   * Whether the column is sortable.
+   */
+  sortable?: boolean
+
+  /**
+   * Text alignment.
+   */
+  align?: 'left' | 'center' | 'right'
 }
 ```
 
-#### `SelectProps`
+#### `TableProps`
 
-Props for the Select dropdown component (single or multi-select).
+Props for the Table component.
 
 ```typescript
-interface SelectProps<T = string> extends SelectElementProps {
+interface TableProps<T> extends HTMLElementProps {
   /**
-   * Select options.
+   * Table data.
    */
-  options: SelectOption<T>[]
+  data: T[]
 
   /**
-   * Current value.
+   * Column definitions.
    */
-  value?: T
+  columns: TableColumn<T>[]
 
   /**
-   * Change handler (with typed value).
+   * Row key extractor.
    */
-  onValueChange?: (value: T) => void
+  rowKey?: keyof T | ((row: T) => string | number)
 
   /**
-   * Select size.
+   * Whether to show borders.
+   */
+  bordered?: boolean
+
+  /**
+   * Whether rows are striped.
+   */
+  striped?: boolean
+
+  /**
+   * Whether rows are hoverable.
+   */
+  hoverable?: boolean
+
+  /**
+   * Table size.
    */
   size?: Size
 
   /**
-   * Label text.
+   * Empty state content.
    */
-  label?: string
+  emptyContent?: Children
 
   /**
-   * Placeholder text.
+   * Loading state.
    */
-  placeholder?: string
+  loading?: boolean
 
   /**
-   * Error message.
+   * Sort configuration.
    */
-  error?: string
+  sort?: { key: string; direction: 'asc' | 'desc' }
 
   /**
-   * Hint/help text.
+   * Sort change handler.
    */
-  hint?: string
+  onSort?: (key: string, direction: 'asc' | 'desc') => void
 
   /**
-   * Whether to allow clearing the selection.
+   * Row click handler.
    */
-  clearable?: boolean
+  onRowClick?: (row: T, index: number) => void
 }
 ```
 
-#### `SeparatorClassOptions`
+#### `PaginationProps`
 
-Options for resolving separator CSS classes via UIClassMap.
+Props for the Pagination component (page navigation with current page, total, page size, and change callbacks).
 
 ```typescript
-interface SeparatorClassOptions {
-  orientation?: 'horizontal' | 'vertical'
-}
-```
+interface PaginationProps extends BaseProps {
+  /**
+   * Current page (1-indexed).
+   */
+  page: number
 
-#### `SeparatorProps`
+  /**
+   * Total number of pages.
+   */
+  totalPages: number
 
-Props for the Separator/Divider component.
+  /**
+   * Page change handler.
+   */
+  onChange: (page: number) => void
 
-```typescript
-interface SeparatorProps extends BaseProps {
   /**
-   * Separator orientation.
+   * Number of sibling pages to show.
    */
-  orientation?: 'horizontal' | 'vertical'
+  siblings?: number
 
   /**
-   * Whether the separator is decorative only.
+   * Number of boundary pages to show.
    */
-  decorative?: boolean
+  boundaries?: number
+
+  /**
+   * Pagination size.
+   */
+  size?: Size
+
+  /**
+   * Whether to show first/last buttons.
+   */
+  showFirstLast?: boolean
+
+  /**
+   * Whether to show previous/next buttons.
+   */
+  showPrevNext?: boolean
+
+  /**
+   * Accessible labels for pagination controls.
+   */
+  labels?: {
+    nav?: string
+    first?: string
+    previous?: string
+    next?: string
+    last?: string
+    goToPage?: (page: number) => string
+  }
 }
 ```
 
@@ -1464,388 +1530,331 @@ interface SkeletonProps extends BaseProps {
 }
 ```
 
-#### `SpacerProps`
+#### `SeparatorProps`
 
-Props for the Spacer layout component (adds whitespace between elements).
+Props for the Separator/Divider component.
 
 ```typescript
-interface SpacerProps extends BaseProps {
+interface SeparatorProps extends BaseProps {
   /**
-   * Space size.
+   * Separator orientation.
    */
-  size?: Size | string | number
+  orientation?: 'horizontal' | 'vertical'
 
   /**
-   * Whether the spacer is horizontal.
+   * Whether the separator is decorative only.
    */
-  horizontal?: boolean
-}
-```
-
-#### `SpinnerClassOptions`
-
-Options for resolving spinner CSS classes via UIClassMap.
-
-```typescript
-interface SpinnerClassOptions {
-  size?: Size
+  decorative?: boolean
 }
 ```
 
-#### `SpinnerProps`
+#### `DropdownItem`
 
-Props for the Spinner/loading indicator component.
+Dropdown menu item.
 
 ```typescript
-interface SpinnerProps extends BaseProps {
+interface DropdownItem<T = string> {
   /**
-   * Spinner size.
+   * Item value/id.
    */
-  size?: Size
+  value: T
 
   /**
-   * Spinner color.
+   * Display label.
    */
-  color?: ColorVariant | string
+  label: Children
 
   /**
-   * Loading label (for accessibility).
+   * Whether the item is disabled.
    */
-  label?: string
+  disabled?: boolean
 
   /**
-   * Spinner thickness.
+   * Icon to display.
    */
-  thickness?: number
-}
-```
+  icon?: Children
 
-#### `SwitchClassOptions`
+  /**
+   * Keyboard shortcut display.
+   */
+  shortcut?: string
 
-Options for switch class resolution.
+  /**
+   * Whether this is a separator.
+   */
+  separator?: boolean
 
-```typescript
-interface SwitchClassOptions {
-  size?: Size
   /**
-   * Color used for the checked/on track. Reuses the same semantic color
-   * scale as `ButtonClassOptions.color`/`BadgeClassOptions.variant`.
-   * @default 'primary'
+   * Nested items (for submenus).
    */
-  color?: ColorVariant
+  items?: DropdownItem<T>[]
 }
 ```
 
-#### `SwitchProps`
+#### `DropdownProps`
 
-Props for the Switch/Toggle component.
+Props for the Dropdown menu component.
 
 ```typescript
-interface SwitchProps extends InputElementProps {
-  /**
-   * Switch label.
-   */
-  label?: Children
-
+interface DropdownProps<T = string> extends BaseProps {
   /**
-   * Whether the switch is on.
+   * Dropdown trigger element.
    */
-  checked?: boolean
+  trigger: Children
 
   /**
-   * Switch size.
+   * Dropdown items.
    */
-  size?: Size
+  items: DropdownItem<T>[]
 
   /**
-   * Color when on.
+   * Called when an item is selected.
    */
-  color?: ColorVariant
-}
-```
-
-#### `TabItem`
-
-A single tab in a Tabs component.
+  onSelect?: (value: T) => void
 
-```typescript
-interface TabItem<T = string> {
   /**
-   * Tab value/id.
+   * Dropdown placement.
    */
-  value: T
+  placement?:
+    'top' | 'top-start' | 'top-end' | 'bottom' | 'bottom-start' | 'bottom-end' | 'left' | 'right'
 
   /**
-   * Tab label.
+   * Whether the dropdown is open (controlled).
    */
-  label: Children
+  open?: boolean
 
   /**
-   * Tab content.
+   * Called when open state changes.
    */
-  content?: Children
+  onOpenChange?: (open: boolean) => void
 
   /**
-   * Whether the tab is disabled.
+   * Menu alignment.
    */
-  disabled?: boolean
+  align?: 'start' | 'center' | 'end'
 
   /**
-   * Icon to display.
+   * Menu width.
    */
-  icon?: Children
+  width?: 'trigger' | 'auto' | number | string
 }
 ```
 
-#### `TableColumn`
+#### `PageShellProps`
 
-Table column definition.
+Props for the PageShell component — authenticated page wrapper with navigation.
 
 ```typescript
-interface TableColumn<T> {
-  /**
-   * Column key (data property).
-   */
-  key: keyof T | string
+interface PageShellProps extends BaseProps {
+  /** Sidebar content (navigation links). */
+  sidebar?: Children
+  /** Top bar content (breadcrumbs, user menu). */
+  topbar?: Children
+  /** Whether the sidebar is collapsed. */
+  sidebarCollapsed?: boolean
+  /** Callback when sidebar toggle is clicked. */
+  onSidebarToggle?: () => void
+  /** Main content. */
+  children?: Children
+}
+```
 
-  /**
-   * Column header.
-   */
-  header: Children
+#### `EmptyStateProps`
 
-  /**
-   * Custom cell renderer.
-   */
-  render?: (value: unknown, row: T, index: number) => Children
+Props for the EmptyState component — shown when a list or section has no data.
 
-  /**
-   * Column width.
-   */
-  width?: string | number
+```typescript
+interface EmptyStateProps extends BaseProps {
+  /** Icon or illustration to display. */
+  icon?: Children
+  /** Main heading text. */
+  title: string
+  /** Description text. */
+  description?: string
+  /** Primary action button (e.g., "Create first item"). */
+  action?: Children
+}
+```
 
-  /**
-   * Whether the column is sortable.
-   */
-  sortable?: boolean
+#### `PageHeaderProps`
 
-  /**
-   * Text alignment.
-   */
-  align?: 'left' | 'center' | 'right'
+Props for the PageHeader component — consistent page title area.
+
+```typescript
+interface PageHeaderProps extends BaseProps {
+  /** Page title. */
+  title: string
+  /** Page description. */
+  description?: string
+  /** Action buttons (e.g., "Create", "Export"). */
+  actions?: Children
+  /** Breadcrumb trail. */
+  breadcrumbs?: Array<{ label: string; href?: string }>
 }
 ```
 
-#### `TableProps`
+#### `ButtonClassOptions`
 
-Props for the Table component.
+Options for resolving button CSS classes via UIClassMap.
 
 ```typescript
-interface TableProps<T> extends HTMLElementProps {
-  /**
-   * Table data.
-   */
-  data: T[]
+interface ButtonClassOptions {
+  variant?: ButtonVariant
+  color?: ColorVariant
+  size?: ButtonSize
+  fullWidth?: boolean
+}
+```
 
-  /**
-   * Column definitions.
-   */
-  columns: TableColumn<T>[]
+#### `InputClassOptions`
 
-  /**
-   * Row key extractor.
-   */
-  rowKey?: keyof T | ((row: T) => string | number)
+Options for resolving input CSS classes via UIClassMap.
 
+```typescript
+interface InputClassOptions {
+  error?: boolean
+  size?: Size
   /**
-   * Whether to show borders.
+   * Horizontal text alignment inside the input. Bonds may default to a
+   * centered aesthetic (e.g. the Tailwind bond's floating-label style);
+   * `'left'` opts a specific field out — e.g. a form field sitting next to
+   * left-aligned textareas.
    */
-  bordered?: boolean
+  align?: 'left' | 'center'
+}
+```
 
-  /**
-   * Whether rows are striped.
-   */
-  striped?: boolean
+#### `TextareaClassOptions`
 
-  /**
-   * Whether rows are hoverable.
-   */
-  hoverable?: boolean
+Options for textarea class resolution.
 
+```typescript
+interface TextareaClassOptions {
+  error?: boolean
   /**
-   * Table size.
+   * Text size tier, matching {@link InputClassOptions.size} — a same-`size`
+   * input + textarea pair renders identical font sizes. Bonds default to
+   * their historic textarea size when omitted.
    */
   size?: Size
+}
+```
 
-  /**
-   * Empty state content.
-   */
-  emptyContent?: Children
+#### `SelectClassOptions`
 
-  /**
-   * Loading state.
-   */
-  loading?: boolean
+Options for resolving select CSS classes via UIClassMap.
 
-  /**
-   * Sort configuration.
-   */
-  sort?: { key: string; direction: 'asc' | 'desc' }
+```typescript
+interface SelectClassOptions {
+  error?: boolean
+  size?: Size
+}
+```
 
-  /**
-   * Sort change handler.
-   */
-  onSort?: (key: string, direction: 'asc' | 'desc') => void
+#### `CheckboxClassOptions`
 
-  /**
-   * Row click handler.
-   */
-  onRowClick?: (row: T, index: number) => void
+Options for resolving checkbox CSS classes via UIClassMap.
+
+```typescript
+interface CheckboxClassOptions {
+  error?: boolean
 }
 ```
 
-#### `TabsClassOptions`
+#### `RadioClassOptions`
 
-Options for resolving tabs (`tabsList`/`tabsTrigger`/`tabsContent`) CSS
-classes via UIClassMap. Active vs inactive trigger styling is NOT one of
-these options — it is expressed as `data-[state=active]` CSS attribute
-selectors baked into the returned class string, driven by the
-`data-state="active"|"inactive"` attribute the framework binding already
-sets on the trigger element (see `@molecule/app-ui-react`'s `Tabs`).
+Options for resolving radio CSS classes via UIClassMap.
 
 ```typescript
-interface TabsClassOptions {
-  /**
-   * Visual style: underline indicator, bordered/filled boxes, a soft-bg
-   * pill, or a solid-bg pill.
-   */
-  variant?: 'line' | 'enclosed' | 'soft-rounded' | 'solid-rounded'
-  size?: Size
+interface RadioClassOptions {
+  error?: boolean
 }
 ```
 
-#### `TabsProps`
+#### `SwitchClassOptions`
 
-Props for the Tabs component (switchable tabbed content panels).
+Options for switch class resolution.
 
 ```typescript
-interface TabsProps<T = string> extends BaseProps {
+interface SwitchClassOptions {
+  size?: Size
   /**
-   * Tab items.
+   * Color used for the checked/on track. Reuses the same semantic color
+   * scale as `ButtonClassOptions.color`/`BadgeClassOptions.variant`.
+   * @default 'primary'
    */
-  items: TabItem<T>[]
+  color?: ColorVariant
+}
+```
 
-  /**
-   * Current active tab.
-   */
-  value?: T
+#### `LabelClassOptions`
 
-  /**
-   * Default active tab.
-   */
-  defaultValue?: T
+Options for label class resolution.
 
-  /**
-   * Change handler.
-   */
-  onChange?: (value: T) => void
+```typescript
+interface LabelClassOptions {
+  required?: boolean
+}
+```
 
-  /**
-   * Tab variant.
-   */
-  variant?: 'line' | 'enclosed' | 'soft-rounded' | 'solid-rounded'
+#### `CardClassOptions`
 
-  /**
-   * Tab size.
-   */
-  size?: Size
+Options for resolving card CSS classes via UIClassMap.
 
-  /**
-   * Whether tabs are fitted (take full width).
-   */
-  fitted?: boolean
+```typescript
+interface CardClassOptions {
+  variant?: 'default' | 'elevated' | 'outline' | 'ghost'
 }
 ```
 
-#### `TextareaClassOptions`
+#### `BadgeClassOptions`
 
-Options for textarea class resolution.
+Options for resolving badge CSS classes via UIClassMap.
 
 ```typescript
-interface TextareaClassOptions {
-  error?: boolean
-  /**
-   * Text size tier, matching {@link InputClassOptions.size} — a same-`size`
-   * input + textarea pair renders identical font sizes. Bonds default to
-   * their historic textarea size when omitted.
-   */
+interface BadgeClassOptions {
+  variant?: ColorVariant
   size?: Size
 }
 ```
 
-#### `TextareaElementProps`
+#### `AlertClassOptions`
 
-Base props for textarea elements.
+Options for resolving alert CSS classes via UIClassMap.
 
 ```typescript
-interface TextareaElementProps extends HTMLElementProps {
-  name?: string
-  value?: string
-  defaultValue?: string
-  placeholder?: string
-  required?: boolean
-  readOnly?: boolean
-  autoFocus?: boolean
-  rows?: number
-  cols?: number
-  maxLength?: number
-  minLength?: number
-  wrap?: 'hard' | 'soft' | 'off'
-  onChange?: ChangeEventHandler
-  onInput?: FormEventHandler
+interface AlertClassOptions {
+  variant?: 'default' | 'info' | 'success' | 'warning' | 'error'
 }
 ```
 
-#### `TextareaProps`
+#### `AvatarClassOptions`
 
-Props for the Textarea component.
+Options for resolving avatar CSS classes via UIClassMap.
 
 ```typescript
-interface TextareaProps extends TextareaElementProps {
-  /**
-   * Text size tier (see {@link TextareaClassOptions.size}) — pass the same
-   * `size` as a neighboring Input for identical font sizes.
-   */
+interface AvatarClassOptions {
   size?: Size
+}
+```
 
-  /**
-   * Label text.
-   */
-  label?: string
+#### `ModalClassOptions`
 
-  /**
-   * Error message.
-   */
-  error?: string
+Options for resolving modal/dialog CSS classes via UIClassMap.
 
-  /**
-   * Hint/help text.
-   */
-  hint?: string
+```typescript
+interface ModalClassOptions {
+  size?: ModalSize
+}
+```
 
-  /**
-   * Whether the textarea auto-resizes.
-   */
-  autoResize?: boolean
+#### `SpinnerClassOptions`
 
-  /**
-   * Minimum number of rows.
-   */
-  minRows?: number
+Options for resolving spinner CSS classes via UIClassMap.
 
-  /**
-   * Maximum number of rows.
-   */
-  maxRows?: number
+```typescript
+interface SpinnerClassOptions {
+  size?: Size
 }
 ```
 
@@ -1859,90 +1868,100 @@ interface ToastClassOptions {
 }
 ```
 
-#### `ToastProps`
+#### `SeparatorClassOptions`
 
-Props for the Toast/notification component.
+Options for resolving separator CSS classes via UIClassMap.
 
 ```typescript
-interface ToastProps extends HTMLElementProps {
-  /**
-   * Toast content.
-   */
-  children?: Children
+interface SeparatorClassOptions {
+  orientation?: 'horizontal' | 'vertical'
+}
+```
 
-  /**
-   * Toast title.
-   */
-  title?: string
+#### `AccordionClassOptions`
 
-  /**
-   * Toast description.
-   */
-  description?: string
+Options for resolving accordion CSS classes via UIClassMap.
 
-  /**
-   * Toast status/type.
-   */
-  status?: ColorVariant
+```typescript
+interface AccordionClassOptions {
+  variant?: string
+}
+```
 
-  /**
-   * Duration in milliseconds (0 for persistent).
-   */
-  duration?: number
+#### `TabsClassOptions`
 
-  /**
-   * Whether the toast is dismissible.
-   */
-  dismissible?: boolean
+Options for resolving tabs (`tabsList`/`tabsTrigger`/`tabsContent`) CSS
+classes via UIClassMap. Active vs inactive trigger styling is NOT one of
+these options — it is expressed as `data-[state=active]` CSS attribute
+selectors baked into the returned class string, driven by the
+`data-state="active"|"inactive"` attribute the framework binding already
+sets on the trigger element (see `@molecule/app-ui-react`'s `Tabs`).
 
+```typescript
+interface TabsClassOptions {
   /**
-   * Called when dismissed.
+   * Visual style: underline indicator, bordered/filled boxes, a soft-bg
+   * pill, or a solid-bg pill.
    */
-  onDismiss?: () => void
+  variant?: 'line' | 'enclosed' | 'soft-rounded' | 'solid-rounded'
+  size?: Size
+}
+```
 
-  /**
-   * Toast position.
-   */
-  position?: 'top' | 'top-right' | 'top-left' | 'bottom' | 'bottom-right' | 'bottom-left'
+#### `PaginationClassOptions`
 
-  /**
-   * Accessible label for the close button.
-   * @default 'Close'
-   */
-  closeLabel?: string
+Options for pagination item class resolution.
+
+```typescript
+interface PaginationClassOptions {
+  active?: boolean
+  size?: Size
+}
+```
+
+#### `ContainerClassOptions`
+
+Options for container class resolution.
+
+```typescript
+interface ContainerClassOptions {
+  size?: Size | '2xl' | 'full'
 }
 ```
 
-#### `TooltipProps`
+#### `FlexClassOptions`
 
-Props for the Tooltip component (hover/focus popover with informational text).
+Options for flex class resolution.
 
 ```typescript
-interface TooltipProps extends HTMLElementProps {
-  /**
-   * Tooltip content.
-   */
-  content: Children
-
-  /**
-   * Element that triggers the tooltip.
-   */
-  children: Children
+interface FlexClassOptions {
+  direction?: 'row' | 'col' | 'row-reverse' | 'col-reverse'
+  align?: 'start' | 'center' | 'end' | 'stretch' | 'baseline'
+  justify?: 'start' | 'center' | 'end' | 'between' | 'around' | 'evenly'
+  wrap?: 'wrap' | 'nowrap' | 'wrap-reverse'
+  /** Named tokens or Tailwind spacing scale index (e.g. `3` → `gap-3`). */
+  gap?: 'none' | 'xs' | 'sm' | 'md' | 'lg' | 'xl' | number
+}
+```
 
-  /**
-   * Tooltip placement.
-   */
-  placement?: TooltipPlacement
+#### `GridClassOptions`
 
-  /**
-   * Delay before showing (ms).
-   */
-  delay?: number
+Options for grid class resolution.
 
+```typescript
+interface GridClassOptions {
+  cols?: number
+  /** Named tokens or Tailwind spacing scale index (e.g. `10` → `gap-10`). */
+  gap?: 'none' | 'xs' | 'sm' | 'md' | 'lg' | 'xl' | number
   /**
-   * Whether the tooltip has an arrow.
+   * Mobile-first responsive collapse. When omitted (the default), a grid of
+   * `cols >= 2` starts at a single column on small screens and steps up to
+   * `cols` at larger breakpoints, so cards don't overflow on mobile. Pass
+   * `false` for a FIXED `cols`-column grid at every viewport width. Ignored
+   * for `cols <= 1` (always single-column) and by ClassMap bonds without a
+   * breakpoint system (e.g. NativeWind).
    */
-  hasArrow?: boolean
+  responsive?: boolean
 }
 ```
 
@@ -2200,590 +2219,11 @@ interface UIClassMap {
 
   /** Native select arrow area. */
   selectNative: string
-
-  // ---- Label/Form sub-element tokens ----
-
-  /** Block label with bottom margin (for use above inputs). */
-  labelBlock: string
-  /** Form fieldset wrapper. */
-  formFieldset: string
-  /** Fieldset with display:contents — invisible wrapper for disabled state. */
-  formFieldsetContents: string
-  /** Form field group wrapper. */
-  formField: string
-  /** Flex column wrapper around control + error message. */
-  formFieldWrapper: string
-
-  // ---- Control (Checkbox/Switch/Radio) shared tokens ----
-
-  /** Control wrapper label (flex + gap + cursor). */
-  controlLabel: string
-  /** Inner control container (for checkbox/radio indicator). */
-  controlContainer: string
-  /** Control label text styling (font size, color, etc.). */
-  controlText: string
-  /** Disabled state for control wrappers. */
-  controlDisabled: string
-
-  // ---- Radio group tokens ----
-
-  /** Radio group label/legend. */
-  radioGroupLabel: string
-
-  // ---- Accordion sub-element tokens ----
-
-  /** Accordion trigger chevron icon (animated rotation). */
-  accordionChevron: string
-  /** Accordion trigger base (full-width, left-aligned). */
-  accordionTriggerBase: string
-
-  // ---- Tabs sub-element tokens ----
-
-  /** Tabs list fitted variant (full-width). */
-  tabsFitted: string
-  /** Tab trigger fitted variant (flex-1). */
-  tabTriggerFitted: string
-  /** Tab trigger icon spacing. */
-  tabTriggerIcon: string
-
-  // ---- Pagination tokens ----
-
-  /** Pagination button interactive classes (cursor). */
-  paginationInteractive: string
-
-  // ---- Progress sub-element tokens ----
-
-  /** Progress outer wrapper (full-width). */
-  progressWrapper: string
-  /** Progress label container (flex between). */
-  progressLabelContainer: string
-  /** Progress label text styling. */
-  progressLabelText: string
-  /** Progress indeterminate animation. */
-  progressIndeterminate: string
-
-  // ---- Table sub-element tokens ----
-
-  /** Table scrollable wrapper. */
-  tableWrapper: string
-  /** Table loading overlay. */
-  tableLoadingOverlay: string
-  /** Table empty state cell. */
-  tableEmptyCell: string
-  /** Table sort indicator wrapper. */
-  tableSortWrapper: string
-  /** Table sort icon spacing. */
-  tableSortIcon: string
-  /** Table striped row. */
-  tableRowStriped: string
-  /** Table hoverable row. */
-  tableRowHoverable: string
-  /** Table clickable row. */
-  tableRowClickable: string
-  /** Table sortable header. */
-  tableHeadSortable: string
-  /** Table bordered variant. */
-  tableBordered: string
-
-  // ---- Toast sub-element tokens ----
-
-  /** Toast icon wrapper (prevents shrinking). */
-  toastIconWrapper: string
-  /** Toast content wrapper (fills remaining space). */
-  toastContentWrapper: string
-
-  // ---- Dropdown sub-element tokens ----
-
-  /** Dropdown trigger wrapper. */
-  dropdownTrigger: string
-  /** Dropdown item icon spacing. */
-  dropdownItemIcon: string
-  /** Dropdown item label (fills remaining space). */
-  dropdownItemLabel: string
-  /** Dropdown item shortcut text. */
-  dropdownItemShortcut: string
-  /** Dropdown item disabled state. */
-  dropdownItemDisabled: string
-
-  // ---- Tooltip tokens ----
-
-  /** Tooltip trigger wrapper. */
-  tooltipTrigger: string
-
-  // ---- Avatar sub-element tokens ----
-
-  /** Avatar initials text styling. */
-  avatarInitials: string
-  /** Avatar fallback icon sizing. */
-  avatarFallbackIcon: string
-  /** Avatar square (non-rounded) variant. */
-  avatarSquare: string
-
-  // ---- Badge tokens ----
-
-  /** Badge square (non-rounded) variant. */
-  badgeSquare: string
-
-  // ---- Skeleton sub-element tokens ----
-
-  /** Skeleton text line container. */
-  skeletonTextContainer: string
-  /** Skeleton circle shape. */
-  skeletonCircle: string
-  /** Skeleton wave animation variant. */
-  skeletonWave: string
-  /** Skeleton no-animation variant. */
-  skeletonNone: string
-
-  // ---- Typography utility tokens ----
-
-  /** Right-aligned text. */
-  textRight: string
-
-  // ---- Theme surface tokens ----
-
-  /** Full-page background with default text color (light/dark aware). */
-  page: string
-  /** Card/panel surface background (light/dark aware). */
-  surface: string
-  /** Recessed/secondary surface background (e.g. tab bars, inputs, sidebars). */
-  surfaceSecondary: string
-  /** App header bar: surface + bottom border + subtle shadow. */
-  headerBar: string
-  /** Right-side drawer panel: fixed, full-height, scrollable. */
-  drawer: string
-
-  // ---- Text color tokens ----
-
-  /** De-emphasized text (e.g. labels, secondary info). */
-  textMuted: string
-  /** Very subtle text (e.g. footer, icon color). */
-  textSubtle: string
-  /** Primary brand color text (e.g. links, active labels). */
-  textPrimary: string
-  /**
-   * Readable text colour for content sitting on {@link bgPrimaryContainer}.
-   *
-   * The counterpart the theme guarantees contrast against — see the note on
-   * `bgPrimaryContainer`. Note it is NOT interchangeable with `textPrimary`:
-   * some themes build a dark primary container and give this a light value, so
-   * pairing it with a light tint inverts the problem (measured at 1.07:1 in one
-   * flagship). Always use the two together.
-   */
-  textOnPrimaryContainer: string
-  /** Success state text color. */
-  textSuccess: string
-  /** Warning state text color. */
-  textWarning: string
-  /** Error-state text color. */
-  textError: string
-
-  // ---- Border tokens ----
-
-  /** Bottom border in theme border color. */
-  borderB: string
-  /** Top border in theme border color. */
-  borderT: string
-  /** Right border in theme border color. */
-  borderR: string
-  /** Left border in theme border color. */
-  borderL: string
-  /** All-sides border in theme border color. */
-  borderAll: string
-  /** Primary-colored bottom border (e.g. active tab indicator). */
-  borderBPrimary: string
-  /** Primary-colored top border accent (e.g. highlighted pricing card). */
-  borderTPrimary: string
-
-  // ---- Background utility tokens ----
-
-  /** Subtle error background for banners/notifications. */
-  bgErrorSubtle: string
-  /** Border color used as element background (e.g. resize handles, separators). */
-  bgBorder: string
-  /** Subtle primary-tinted background (e.g. icon halo, callout banner). */
-  bgPrimarySubtle: string
-  /**
-   * Primary-tinted container background, paired with {@link textOnPrimaryContainer}.
-   *
-   * Use this pair — never `bgPrimarySubtle` + `textPrimary` — whenever TEXT sits
-   * on a primary tint. The brand colour as text on a 10% tint of itself is only
-   * legible when the brand is already dark: measured across the flagship themes,
-   * an amber brand scores 1.98:1 there and no shade of the hue fixes it, because
-   * darkening enough for the tint breaks the button fill it also has to serve.
-   * The container pair is defined per theme precisely so both sides move
-   * together, and it clears 4.5:1 in 130 of 133 flagship themes.
-   */
-  bgPrimaryContainer: string
-  /** Solid primary background (e.g. CTA fill). */
-  bgPrimary: string
-  /** Pure white background (uses `--color-surface-container-lowest` if defined). */
-  bgWhite: string
-
-  // ---- Premium typography utilities ----
-
-  /** Italic style for emphasized headlines (e.g. tier name in pricing card). */
-  italic: string
-  /** ALL CAPS letter transform for eyebrow labels. */
-  uppercase: string
-  /** Wide letter-spacing for caps eyebrow / button labels. */
-  trackingWide: string
-
-  // ---- Premium decoration tokens ----
-
-  /** Linear gradient using the app's primary color (e.g. hero CTAs). */
-  gradientPrimary: string
-  /** Soft elevation suitable for "lifted" cards (e.g. popular pricing tier). */
-  shadowLifted: string
-
-  // ---- Composite style tokens ----
-
-  /** Settings section heading (small, muted). */
-  sectionHeading: string
-  /** Standard form label (block, small, medium weight, bottom margin). */
-  formLabel: string
-  /** Small form label variant (extra-small, muted). */
-  formLabelSmall: string
-  /** Inline text link appearance (hover effect). */
-  link: string
-  /** Rich text / long-form prose content. */
-  prose: string
-  /** Thin horizontal divider line. */
-  dividerLine: string
-  /** Modal overlay backdrop. */
-  overlay: string
-  /** Fixed bottom footer bar. */
-  footerBar: string
-  /** Footer link styling (muted, hover highlight). */
-  footerLink: string
-  /** Footer button styling (borderless, muted, hover highlight). */
-  footerButton: string
-
-  // ---- Language selector tokens ----
-
-  /** Language selector grid container (responsive columns, scrollable). */
-  languageGrid: string
-  /** Language option item (default/inactive state). */
-  languageOption: string
-  /** Language option item (active/selected state). */
-  languageActive: string
-  /** Trigger button for `<LanguagePicker />` (globe icon + current locale name). */
-  languagePickerTrigger: string
-
-  // ---- Spacing utilities ----
-
-  /**
-   * Returns a spacing class for the given property and scale.
-   */
-  sp(property: SpacingProperty, scale: SpacingScale): string
-  /**
-   * Returns a style object resolved from a compound spacing spec.
-   * Use on the `style` prop — avoids CSS class ordering conflicts entirely.
-   * More specific properties override less specific ones (e.g. `pr` overrides `px` overrides `p`).
-   */
-  sp(overrides: SpacingOverrides): Record<string, string>
-  /**
-   * Returns vertical space-between class (e.g. `space-y-*` in Tailwind).
-   */
-  stack(scale: SpacingScale): string
-
-  // ---- Typography utilities ----
-
-  /**
-   * Returns font size class for the given scale.
-   */
-  textSize(size: TextScale): string
-  /**
-   * Returns font weight class for the given weight.
-   */
-  fontWeight(weight: FontWeightScale): string
-  /** Center-aligned text. */
-  textCenter: string
-
-  // ---- Sizing utilities ----
-
-  /**
-   * Returns width class — fractional (`'1/2'`), keyword (`'full'`), or numeric.
-   */
-  w(value: WidthValue | number): string
-  /**
-   * Returns height class — keyword (`'full'`, `'screen'`) or numeric.
-   */
-  h(value: HeightValue | number): string
-  /**
-   * Returns minimum height class.
-   */
-  minH(value: HeightValue): string
-  /**
-   * Returns maximum width constraint class.
-   */
-  maxW(value: MaxWidthScale): string
-  /** Prevent flex shrinking. */
-  shrink0: string
-
-  // ---- Touch / pointer utilities ----
-
-  /**
-   * Minimum interactive hit-area for touch (coarse-pointer) devices — WCAG 2.5.5
-   * "Target Size". Resolves to a `>=44x44px` minimum that applies ONLY on
-   * coarse-pointer devices, so fine-pointer (mouse) layouts keep their compact
-   * control sizing. Compose onto small icon buttons/controls that would otherwise
-   * be too small to tap reliably on phones/tablets (e.g. the preview toolbar's
-   * back/forward/refresh/open and device-frame buttons). On React Native (touch
-   * by definition) the bond applies the minimum unconditionally.
-   */
-  touchTarget: string
-
-  /**
-   * Compact coarse-pointer hit-area floor (`>=36x36px`) for inline CTAs inside
-   * dense surfaces — banner/notice-card action buttons, chat-card actions —
-   * where the full 44px {@link touchTarget} visibly overwhelms the strip or
-   * card that hosts them. 36px is still comfortably tappable; reserve the full
-   * 44px floor for standalone controls. Like {@link touchTarget} it applies
-   * only on coarse-pointer devices (unconditionally on React Native).
-   */
-  touchTargetCompact: string
-
-  // ---- Position utilities ----
-
-  // ---- Display utilities ----
-
-  /** Block display. */
-  displayBlock: string
-  /** Inline-block display. */
-  displayInlineBlock: string
-  /** Contents display (invisible wrapper). */
-  displayContents: string
-  /**
-   * Hidden on viewports NARROWER than the breakpoint; the element keeps its
-   * own display from the breakpoint up. Pair with {@link UIClassMap.hiddenFrom}
-   * to swap a desktop surface (a side column) for a phone one (a bottom bar)
-   * in CSS alone — correct in server-rendered HTML before any JavaScript runs.
-   */
-  hiddenBelow(breakpoint: ResponsiveBreakpoint): string
-  /** Hidden on viewports AT OR WIDER than the breakpoint (the phone-only half of the pair). */
-  hiddenFrom(breakpoint: ResponsiveBreakpoint): string
-
-  // ---- Layout utilities ----
-
-  /** Horizontal auto margin (centering). */
-  mxAuto: string
-  /** Pointer cursor. */
-  cursorPointer: string
-  /** Full border radius (circle). */
-  roundedFull: string
-
-  // ---- Grid utilities ----
-
-  /**
-   * Returns grid-template-rows class for the given row count.
-   */
-  gridRows(rows: number): string
-
-  // ---- Position utilities ----
-
-  /**
-   * Returns CSS position class for the given value.
-   */
-  position(value: 'relative' | 'absolute' | 'fixed' | 'sticky'): string
-  /** Full inset (inset: 0). */
-  inset0: string
-
-  // ---- Logo / brand identity tokens ----
-
-  /** Logo wordmark text styling (size, tracking, case). */
-  logoText: string
-  /** Logo icon color (primary brand color). */
-  logoIcon: string
-
-  // ---- Header layout tokens ----
-
-  /** Fixed header positioning (fixed, full-width, high z-index). */
-  headerFixed: string
-  /** Main header inner container (max-width, height, padding). */
-  headerInner: string
-
-  // ---- Auth page layout tokens ----
-
-  /** Auth page header inner container (full-width, no max-width). */
-  authHeaderInner: string
-  /** Auth page body: centered content area. */
-  authPageBody: string
-  /** Auth form narrow container (max-width, centered). */
-  authFormWrapper: string
-  /** Auth form field spacing (bottom margin). */
-  authField: string
-  /** Spacing after auth submit area (top margin). */
-  authAfterSubmit: string
-
-  // ---- Auth button layout tokens ----
-
-  /** Flex row container for auth form buttons. */
-  authButtonRow: string
-  /** Back button sizing in auth forms. */
-  authBackButton: string
-  /** Submit button sizing next to back button. */
-  authSubmitButton: string
-  /** Login page signup button (half-width, left). */
-  authLoginSignup: string
-  /** Login page submit button (half-width, right). */
-  authLoginSubmit: string
-  /** Login submit full-width (when logging in). */
-  authLoginSubmitFull: string
-  /** Hidden state for login signup button. */
-  authHidden: string
-  /** Forward arrow icon spacing. */
-  authArrowIcon: string
-
-  // ---- App layout tokens ----
-
-  /** Main app content padding (header/footer offsets). */
-  appLayout: string
-
-  /** Flex grow to fill available space (`flex: 1`). */
-  flex1: string
-
-  // ---- OAuth tokens ----
-
-  /** OAuth provider name label (fallback when no icon). */
-  oauthProviderLabel: string
-
-  // ---- Layout pattern tokens ----
-
-  /** PageShell root container (flex, full screen). */
-  pageShell: string
-  /** PageShell sidebar panel. */
-  pageShellSidebar: string
-  /** PageShell sidebar collapsed state (narrow width). */
-  pageShellSidebarCollapsed: string
-  /** PageShell top bar strip. */
-  pageShellTopbar: string
-  /** PageShell main content area (scrollable). */
-  pageShellContent: string
-  /** PageShell sidebar toggle button. */
-  pageShellSidebarToggle: string
-  /** EmptyState root container (centered column). */
-  emptyState: string
-  /** EmptyState icon/illustration wrapper. */
-  emptyStateIcon: string
-  /** EmptyState heading text. */
-  emptyStateTitle: string
-  /** EmptyState description text. */
-  emptyStateDescription: string
-  /** EmptyState action slot. */
-  emptyStateAction: string
-  /** PageHeader root container. */
-  pageHeader: string
-  /** PageHeader title text. */
-  pageHeaderTitle: string
-  /** PageHeader description text. */
-  pageHeaderDescription: string
-  /** PageHeader action buttons container. */
-  pageHeaderActions: string
-  /** PageHeader breadcrumb trail container. */
-  pageHeaderBreadcrumbs: string
-  /** PageHeader breadcrumb item link/text. */
-  pageHeaderBreadcrumbItem: string
-  /** PageHeader breadcrumb separator character. */
-  pageHeaderBreadcrumbSeparator: string
-
-  // ---- Search UI tokens (SearchBox, SearchResults, QuickSearch) ----
-
-  /** SearchBox field: the bordered bar holding the icon, the input and its actions; focus ring via focus-within. */
-  searchField: string
-  /** SearchBox leading icon slot. */
-  searchFieldIcon: string
-  /** SearchBox text input: borderless, fills the bar, left-aligned, visible placeholder. */
-  searchFieldInput: string
-  /** SearchBox trailing slot: the clear button and the shortcut hint. */
-  searchFieldActions: string
-  /** SearchBox icon-only clear button. */
-  searchFieldClear: string
-  /** SearchBox status row under the field: filter chips at the left, the count and tips at the right. */
-  searchStatusRow: string
-  /** SearchBox syntax tips line. */
-  searchTips: string
-  /** A key cap (`/`, `↵`). */
-  kbd: string
-  /** A removable filter chip (`category: auth ×`). */
-  filterChip: string
-  /** Added to a filter chip that EXCLUDES its value. */
-  filterChipNegated: string
-  /** The × inside a filter chip. */
-  filterChipRemove: string
-  /** SearchResults list container: bordered, rows divided. */
-  resultList: string
-  /** One result row. */
-  resultItem: string
-  /** Added to the keyboard- or pointer-active result row. */
-  resultItemActive: string
-  /** A result row's body: the link that fills the row. */
-  resultBody: string
-  /** A result row's title. */
-  resultTitle: string
-  /** Added to a result title that is code (a package name). */
-  resultTitleMono: string
-  /** A result row's meta line (type · category · related). */
-  resultMeta: string
-  /** A result row's description, clamped to two lines. */
-  resultDescription: string
-  /** A matched term inside a result. */
-  resultMark: string
-  /** A result row's trailing action slot. */
-  resultAction: string
-  /** A results empty state. */
-  resultEmpty: string
-}
-```
-
-#### `UIProvider`
-
-Identifies the bonded UI styling library. Providers set `name`
-to indicate which library is active (e.g. `"tailwind"`, `"bootstrap"`).
-
-```typescript
-interface UIProvider {
-  /**
-   * Identifier for the styling library (e.g. `"tailwind"`, `"ionic"`).
-   */
-  name: string
-}
+// … truncated — the full declaration is in node_modules/@molecule/app-ui/dist/types.d.ts
 ```
 
 ### Types
 
-#### `AccentTone`
-
-Tones of an accent bar: the semantic colors, the brand primary, or `custom` (the `--mol-accent` variable).
-
-```typescript
-type AccentTone = 'default' | 'primary' | 'info' | 'success' | 'warning' | 'error' | 'custom'
-```
-
-#### `ButtonSize`
-
-Button size variants (extends Size with 'icon' for square icon-only buttons).
-
-```typescript
-type ButtonSize = Size | 'icon'
-```
-
-#### `ButtonVariant`
-
-Button visual variant styles.
-
-```typescript
-type ButtonVariant = 'solid' | 'outline' | 'ghost' | 'link'
-```
-
-#### `ChangeEventHandler`
-
-Framework-agnostic change event handler.
-
-```typescript
-type ChangeEventHandler = EventHandler<Event>
-```
-
 #### `Children`
 
 Framework-agnostic child content.
@@ -2793,48 +2233,30 @@ Use `unknown` to allow any framework's node type (ReactNode, VNode, etc.).
 type Children = unknown
 ```
 
-#### `ClassMapOverrides`
-
-Overrides for extending a UIClassMap.
+#### `EventHandler`
 
-Can be a partial map of token replacements, or a function that receives
-the base ClassMap and returns overrides (useful for extending resolver
-functions while preserving the base behavior).
+Framework-agnostic event handler.
 
 ```typescript
-type ClassMapOverrides = Partial<UIClassMap> | ((base: UIClassMap) => Partial<UIClassMap>)
+type EventHandler<E = Event> = (event: E) => void
 ```
 
-#### `ClassMapValue`
-
-Class value types accepted by the UIClassMap `cn()` function.
-Supports strings, booleans, arrays, and conditional objects.
-
-```typescript
-type ClassMapValue =
-  | string
-  | number
-  | boolean
-  | undefined
-  | null
-  | ClassMapValue[]
-  | Record<string, boolean | undefined | null>
-```
+- `event` — The DOM event object.
 
-#### `ColorVariant`
+#### `MouseEventHandler`
 
-Semantic color variants used across components for status indication.
+Framework-agnostic mouse event handler.
 
 ```typescript
-type ColorVariant = 'primary' | 'secondary' | 'success' | 'warning' | 'error' | 'info'
+type MouseEventHandler = EventHandler<MouseEvent>
 ```
 
-#### `EventHandler`
+#### `KeyboardEventHandler`
 
-Framework-agnostic event handler.
+Framework-agnostic keyboard event handler.
 
 ```typescript
-type EventHandler<E = Event> = (event: E) => void
+type KeyboardEventHandler = EventHandler<KeyboardEvent>
 ```
 
 #### `FocusEventHandler`
@@ -2845,12 +2267,12 @@ Framework-agnostic focus event handler.
 type FocusEventHandler = EventHandler<FocusEvent>
 ```
 
-#### `FontWeightScale`
+#### `ChangeEventHandler`
 
-Font weight scale.
+Framework-agnostic change event handler.
 
 ```typescript
-type FontWeightScale = 'normal' | 'medium' | 'semibold' | 'bold' | 'extrabold'
+type ChangeEventHandler = EventHandler<Event>
 ```
 
 #### `FormEventHandler`
@@ -2861,62 +2283,54 @@ Framework-agnostic form event handler.
 type FormEventHandler = EventHandler<Event>
 ```
 
-#### `HeightValue`
+#### `Size`
 
-Height value — fractional, keyword, or numeric (mapped to spacing scale).
+Standard size scale used across all molecule UI components (buttons, inputs, badges, etc.).
 
 ```typescript
-type HeightValue =
-  'full' | 'screen' | 'auto' | '1/2' | '1/3' | '2/3' | '1/4' | '3/4' | TailwindArbitraryBracket
+type Size = 'xs' | 'sm' | 'md' | 'lg' | 'xl'
 ```
 
-#### `InputType`
+#### `ButtonSize`
 
-Allowed HTML input type attribute values for the Input component.
+Button size variants (extends Size with 'icon' for square icon-only buttons).
 
 ```typescript
-type InputType =
-  | 'text'
-  | 'email'
-  | 'password'
-  | 'number'
-  | 'tel'
-  | 'url'
-  | 'search'
-  | 'date'
-  | 'time'
-  | 'datetime-local'
+type ButtonSize = Size | 'icon'
 ```
 
-#### `KeyboardEventHandler`
+#### `ColorVariant`
 
-Framework-agnostic keyboard event handler.
+Semantic color variants used across components for status indication.
 
 ```typescript
-type KeyboardEventHandler = EventHandler<KeyboardEvent>
+type ColorVariant = 'primary' | 'secondary' | 'success' | 'warning' | 'error' | 'info'
 ```
 
-#### `MaxWidthScale`
+#### `ButtonVariant`
 
-Max-width scale for constraining content.
+Button visual variant styles.
 
 ```typescript
-type MaxWidthScale =
-  | 'none'
-  | 'xs'
-  | 'sm'
-  | 'md'
-  | 'lg'
-  | 'xl'
-  | '2xl'
-  | '3xl'
-  | '4xl'
-  | '5xl'
-  | '6xl'
-  | '7xl'
-  | 'full'
-  | 'screen-2xl'
-  | TailwindArbitraryBracket
+type ButtonVariant = 'solid' | 'outline' | 'ghost' | 'link'
+```
+
+#### `InputType`
+
+Allowed HTML input type attribute values for the Input component.
+
+```typescript
+type InputType =
+  | 'text'
+  | 'email'
+  | 'password'
+  | 'number'
+  | 'tel'
+  | 'url'
+  | 'search'
+  | 'date'
+  | 'time'
+  | 'datetime-local'
 ```
 
 #### `ModalSize`
@@ -2927,45 +2341,46 @@ Modal size variants including full-screen.
 type ModalSize = 'sm' | 'md' | 'lg' | 'xl' | 'full'
 ```
 
-#### `MouseEventHandler`
+#### `TooltipPlacement`
 
-Framework-agnostic mouse event handler.
+Position where a tooltip renders relative to its trigger element (top, bottom, left, right, and corner variants).
 
 ```typescript
-type MouseEventHandler = EventHandler<MouseEvent>
+type TooltipPlacement =
+  'top' | 'bottom' | 'left' | 'right' | 'top-start' | 'top-end' | 'bottom-start' | 'bottom-end'
 ```
 
-#### `ResponsiveBreakpoint`
+#### `ClassMapValue`
 
-Viewport breakpoints for responsive visibility (`hiddenBelow`/`hiddenFrom`):
-`sm` ≈ 640px, `md` ≈ 768px, `lg` ≈ 1024px, `xl` ≈ 1280px (each ClassMap
-bond maps them to its own breakpoints).
+Class value types accepted by the UIClassMap `cn()` function.
+Supports strings, booleans, arrays, and conditional objects.
 
 ```typescript
-type ResponsiveBreakpoint = 'sm' | 'md' | 'lg' | 'xl'
+type ClassMapValue =
+  | string
+  | number
+  | boolean
+  | undefined
+  | null
+  | ClassMapValue[]
+  | Record<string, boolean | undefined | null>
 ```
 
-#### `Size`
+#### `SpacingScale`
 
-Standard size scale used across all molecule UI components (buttons, inputs, badges, etc.).
+Abstract spacing scale. Each styling library maps these to its own units.
+For Tailwind: 0 → 0, 1 → 0.25rem, 4 → 1rem, 8 → 2rem, etc.
 
 ```typescript
-type Size = 'xs' | 'sm' | 'md' | 'lg' | 'xl'
+type SpacingScale = 0 | 0.5 | 1 | 1.5 | 2 | 2.5 | 3 | 4 | 5 | 6 | 8 | 10 | 12 | 16 | 20 | 24
 ```
 
-#### `SpacingOverrides`
-
-Compound spacing specification for conflict-free overrides.
-
-Pass to `sp()` to get a style object (for use on the `style` prop).
-More specific properties override less specific ones:
-`pr` overrides `px` overrides `p` (same cascade as CSS shorthand).
+#### `TailwindArbitraryBracket`
 
-Returns `Record<string, string>` so it is compatible with any framework's
-inline style API without requiring a React-specific import.
+Tailwind arbitrary value in bracket notation (e.g. `[440px]`, `[65%]`).
 
 ```typescript
-type SpacingOverrides = Partial<Record<SpacingProperty, SpacingScale>>
+type TailwindArbitraryBracket = `[${string}]`
 ```
 
 #### `SpacingProperty`
@@ -2977,21 +2392,29 @@ type SpacingProperty =
   'p' | 'px' | 'py' | 'pt' | 'pb' | 'pl' | 'pr' | 'm' | 'mx' | 'my' | 'mt' | 'mb' | 'ml' | 'mr'
 ```
 
-#### `SpacingScale`
+#### `SpacingOverrides`
 
-Abstract spacing scale. Each styling library maps these to its own units.
-For Tailwind: 0 → 0, 1 → 0.25rem, 4 → 1rem, 8 → 2rem, etc.
+Compound spacing specification for conflict-free overrides.
+
+Pass to `sp()` to get a style object (for use on the `style` prop).
+More specific properties override less specific ones:
+`pr` overrides `px` overrides `p` (same cascade as CSS shorthand).
+
+Returns `Record<string, string>` so it is compatible with any framework's
+inline style API without requiring a React-specific import.
 
 ```typescript
-type SpacingScale = 0 | 0.5 | 1 | 1.5 | 2 | 2.5 | 3 | 4 | 5 | 6 | 8 | 10 | 12 | 16 | 20 | 24
+type SpacingOverrides = Partial<Record<SpacingProperty, SpacingScale>>
 ```
 
-#### `TailwindArbitraryBracket`
+#### `ResponsiveBreakpoint`
 
-Tailwind arbitrary value in bracket notation (e.g. `[440px]`, `[65%]`).
+Viewport breakpoints for responsive visibility (`hiddenBelow`/`hiddenFrom`):
+`sm` ≈ 640px, `md` ≈ 768px, `lg` ≈ 1024px, `xl` ≈ 1280px (each ClassMap
+bond maps them to its own breakpoints).
 
 ```typescript
-type TailwindArbitraryBracket = `[${string}]`
+type ResponsiveBreakpoint = 'sm' | 'md' | 'lg' | 'xl'
 ```
 
 #### `TextScale`
@@ -3002,21 +2425,35 @@ Text size scale from extra-small to 4xl.
 type TextScale = 'xs' | 'sm' | 'base' | 'lg' | 'xl' | '2xl' | '3xl' | '4xl' | '5xl' | '6xl'
 ```
 
-#### `ToastPosition`
+#### `FontWeightScale`
 
-Toast position values for screen placement.
+Font weight scale.
 
 ```typescript
-type ToastPosition = 'top' | 'top-right' | 'top-left' | 'bottom' | 'bottom-right' | 'bottom-left'
+type FontWeightScale = 'normal' | 'medium' | 'semibold' | 'bold' | 'extrabold'
 ```
 
-#### `TooltipPlacement`
+#### `MaxWidthScale`
 
-Position where a tooltip renders relative to its trigger element (top, bottom, left, right, and corner variants).
+Max-width scale for constraining content.
 
 ```typescript
-type TooltipPlacement =
-  'top' | 'bottom' | 'left' | 'right' | 'top-start' | 'top-end' | 'bottom-start' | 'bottom-end'
+type MaxWidthScale =
+  | 'none'
+  | 'xs'
+  | 'sm'
+  | 'md'
+  | 'lg'
+  | 'xl'
+  | '2xl'
+  | '3xl'
+  | '4xl'
+  | '5xl'
+  | '6xl'
+  | '7xl'
+  | 'full'
+  | 'screen-2xl'
+  | TailwindArbitraryBracket
 ```
 
 #### `WidthValue`
@@ -3037,78 +2474,44 @@ type WidthValue =
   | TailwindArbitraryBracket
 ```
 
-### Functions
-
-#### `extendClassMap(base, overrides)`
-
-Creates a new UIClassMap by extending a base ClassMap with overrides.
-
-Overrides can be a plain object (for replacing specific tokens/resolvers)
-or a function that receives the base map (for extending resolvers while
-preserving base behavior).
-
-```typescript
-function extendClassMap(base: UIClassMap, overrides: ClassMapOverrides): UIClassMap
-```
-
-- `base` — The base UIClassMap to extend
-- `overrides` — Token overrides (object or function returning object)
-
-**Returns:** A new UIClassMap with overrides applied
-
-#### `getClassMap()`
-
-Retrieves the bonded UIClassMap, throwing if none is configured.
-Use this to resolve styling-agnostic class names in components.
-
-```typescript
-function getClassMap(): UIClassMap
-```
-
-**Returns:** The bonded UIClassMap implementation.
-
-#### `getProvider()`
+#### `HeightValue`
 
-Retrieves the bonded UI provider, or `undefined` if none is configured.
+Height value — fractional, keyword, or numeric (mapped to spacing scale).
 
 ```typescript
-function getProvider(): UIProvider | undefined
+type HeightValue =
+  'full' | 'screen' | 'auto' | '1/2' | '1/3' | '2/3' | '1/4' | '3/4' | TailwindArbitraryBracket
 ```
 
-**Returns:** The bonded UI provider, or `undefined`.
-
-#### `hasClassMap()`
+#### `ToastPosition`
 
-Checks whether a UIClassMap is currently bonded.
+Toast position values for screen placement.
 
 ```typescript
-function hasClassMap(): boolean
+type ToastPosition = 'top' | 'top-right' | 'top-left' | 'bottom' | 'bottom-right' | 'bottom-left'
 ```
 
-**Returns:** `true` if a UIClassMap is bonded.
-
-#### `hasProvider()`
+#### `AccentTone`
 
-Checks whether a UI provider is currently bonded.
+Tones of an accent bar: the semantic colors, the brand primary, or `custom` (the `--mol-accent` variable).
 
 ```typescript
-function hasProvider(): boolean
+type AccentTone = 'default' | 'primary' | 'info' | 'success' | 'warning' | 'error' | 'custom'
 ```
 
-**Returns:** `true` if a UI provider is bonded.
+#### `ClassMapOverrides`
 
-#### `moleculeSpinnerMarkSvg(options)`
+Overrides for extending a UIClassMap.
 
-The molecule spinner mark as a complete SVG element string (SMIL-animated,
-framework-agnostic). See the module docblock for usage and gotchas.
+Can be a partial map of token replacements, or a function that receives
+the base ClassMap and returns overrides (useful for extending resolver
+functions while preserving the base behavior).
 
 ```typescript
-function moleculeSpinnerMarkSvg(options?: MoleculeSpinnerMarkOptions): string
+type ClassMapOverrides = Partial<UIClassMap> | ((base: UIClassMap) => Partial<UIClassMap>)
 ```
 
-- `options` — Paint, timings, size, gradient id and a11y shape.
-
-**Returns:** A `<svg>…</svg>` markup string.
+### Functions
 
 #### `molId(component, context, qualifier)`
 
@@ -3161,6 +2564,36 @@ function molSelectorPrefix(prefix: string): string
 
 **Returns:** A CSS attribute prefix selector string.
 
+#### `setProvider(provider)`
+
+Registers a UI provider as the active singleton.
+
+```typescript
+function setProvider(provider: UIProvider): void
+```
+
+- `provider` — The UI provider implementation to bond.
+
+#### `getProvider()`
+
+Retrieves the bonded UI provider, or `undefined` if none is configured.
+
+```typescript
+function getProvider(): UIProvider | undefined
+```
+
+**Returns:** The bonded UI provider, or `undefined`.
+
+#### `hasProvider()`
+
+Checks whether a UI provider is currently bonded.
+
+```typescript
+function hasProvider(): boolean
+```
+
+**Returns:** `true` if a UI provider is bonded.
+
 #### `setClassMap(classMap)`
 
 Registers a UIClassMap as the active styling resolver. Called at
@@ -3172,15 +2605,56 @@ function setClassMap(classMap: UIClassMap): void
 
 - `classMap` — The UIClassMap implementation to bond.
 
-#### `setProvider(provider)`
+#### `getClassMap()`
 
-Registers a UI provider as the active singleton.
+Retrieves the bonded UIClassMap, throwing if none is configured.
+Use this to resolve styling-agnostic class names in components.
 
 ```typescript
-function setProvider(provider: UIProvider): void
+function getClassMap(): UIClassMap
 ```
 
-- `provider` — The UI provider implementation to bond.
+**Returns:** The bonded UIClassMap implementation.
+
+#### `hasClassMap()`
+
+Checks whether a UIClassMap is currently bonded.
+
+```typescript
+function hasClassMap(): boolean
+```
+
+**Returns:** `true` if a UIClassMap is bonded.
+
+#### `moleculeSpinnerMarkSvg(options)`
+
+The molecule spinner mark as a complete SVG element string (SMIL-animated,
+framework-agnostic). See the module docblock for usage and gotchas.
+
+```typescript
+function moleculeSpinnerMarkSvg(options?: MoleculeSpinnerMarkOptions): string
+```
+
+- `options` — Paint, timings, size, gradient id and a11y shape.
+
+**Returns:** A `<svg>…</svg>` markup string.
+
+#### `extendClassMap(base, overrides)`
+
+Creates a new UIClassMap by extending a base ClassMap with overrides.
+
+Overrides can be a plain object (for replacing specific tokens/resolvers)
+or a function that receives the base map (for extending resolvers while
+preserving base behavior).
+
+```typescript
+function extendClassMap(base: UIClassMap, overrides: ClassMapOverrides): UIClassMap
+```
+
+- `base` — The base UIClassMap to extend
+- `overrides` — Token overrides (object or function returning object)
+
+**Returns:** A new UIClassMap with overrides applied
 
 ### Constants
 
@@ -3228,6 +2702,9 @@ the ClassMap bond (`@molecule/app-ui-tailwind`), so swapping the styling library
 only the bond — a literal `"flex p-4"` in a component defeats that and is the #1 styling
 mistake.
 
+- **`Button` defaults to `type="button"`.** A form's primary action needs
+  `type="submit"`, or Enter does nothing and tests that select `button[type="submit"]`
+  miss it (X1 RealWorld runs failed 15 browser tests on one Settings button).
 - **Inline styles must not fight ClassMap.** An inline `style` has higher specificity and
   SILENTLY overrides the class controlling the same property (e.g. `style={{ background }}`
   kills `cm.surface`). Use inline only for what ClassMap can't express (a specific pixel