@capra/core 1.13.0 → 1.14.1

package/docs/core-alert--design.md

@@ -105,6 +105,6 @@ Don't:
 
 ## Related components
 
-* [Toast](?path=/docs/core-toast--design) — For non-blocking, auto-dismissing notifications.
-* [Pill](?path=/docs/core-pill--design) — For inline semantic status indicators without body copy.
-* [Modal](?path=/docs/core-modal--design) — When the error or warning requires an immediate blocking decision.
+* [Toast](/llms/core-toast--design.txt) — For non-blocking, auto-dismissing notifications.
+* [Pill](/llms/core-pill--design.txt) — For inline semantic status indicators without body copy.
+* [Modal](/llms/core-modal--design.txt) — When the error or warning requires an immediate blocking decision.

package/docs/core-autocompletefield--design.md

@@ -39,7 +39,7 @@ space is limited.
 
 ## Layout and spacing
 
-* Input renders identically to [TextField](?path=/docs/core-textfield--design).
+* Input renders identically to [TextField](/llms/core-textfield--design.txt).
 * Suggestions are presented using a ListBox.
 
 ## Behavior
@@ -70,8 +70,8 @@ Do:
 
 Don't:
 
-* Don't use AutocompleteField for small mutually exclusive sets (about seven or fewer visible options) — use [RadioGroup](?path=/docs/core-radiogroup--design) or Select.
-* Don't use AutocompleteField for plain freeform text with no list validation — use [TextField](?path=/docs/core-textfield--design).
+* Don't use AutocompleteField for small mutually exclusive sets (about seven or fewer visible options) — use [RadioGroup](/llms/core-radiogroup--design.txt) or Select.
+* Don't use AutocompleteField for plain freeform text with no list validation — use [TextField](/llms/core-textfield--design.txt).
 * Don't require picking from the list while still allowing arbitrary text without explaining that behavior.
 
 ## Accessibility
@@ -87,5 +87,5 @@ Don't:
 
 ## Related components
 
-* [TextField](?path=/docs/core-textfield--design) — For freeform text without suggestions.
-* [RadioGroup](?path=/docs/core-radiogroup--design) — For small mutually exclusive option sets.
+* [TextField](/llms/core-textfield--design.txt) — For freeform text without suggestions.
+* [RadioGroup](/llms/core-radiogroup--design.txt) — For small mutually exclusive option sets.

package/docs/core-badge--design.md

@@ -16,6 +16,10 @@ Badges support `md` and `sm` sizes. Use `sm` when composing with smaller control
 
 Use a dot to show notifications without a count.
 
+### Decorative
+
+Use `decorative` when the badge is purely visual and its meaning is already conveyed nearby, such as adjacent text. Decorative badges are removed from the accessibility tree and must not be combined with `aria-label` or `aria-labelledby`.
+
 ### Appearance
 
 Badges can be colored based on their status. The `attention` appearance is the general purpose color used for numbered badges and does not necessarily communicate severity.
@@ -49,6 +53,7 @@ Do:
 * Do cap displayed values at 99 with a "99+" label.
 * Do use the dot variant for simple presence indicators.
 * Do associate interactive anchors with badge count context using `aria-describedby`.
+* Do use `decorative` when the badge is redundant with nearby text or another accessible name.
 
 Don't:
 
@@ -57,12 +62,15 @@ Don't:
 * Don't place Badge on non-interactive decorative elements.
 * Don't use Badge colors as the only method to communicate status.
 * Don't include badge count context in the anchor's `aria-label`.
+* Don't combine `decorative` with `aria-label` or `aria-labelledby`.
 
 ## Accessibility
 
-* Badge requires an accessible label via `aria-label` or `aria-labelledby` that describes the count or status (e.g., "76 unread").
+* Named badges require `aria-label` or `aria-labelledby` that describes the count or status (e.g., "76 unread").
+* Counter badges use `role="status"` so naming attributes are valid and the visible count is not presentational. Dot badges use `role="img"` because they have no text.
+* Use `decorative` when the badge is purely presentational and the meaning is already available to assistive technology. Decorative badges omit the role and accessible name and set `aria-hidden`. Do not combine `decorative` with `aria-label` or `aria-labelledby`.
 * When composing with interactive controls such as `Button` or `IconButton`, set `aria-describedby` on the anchor to the badge's `id`. Keep the anchor's accessible name limited to the control action or label (e.g., "Messages"), not the badge content.
-* Use `aria-live="polite"` on the parent for dynamic badge updates.
+* Counter badges are a polite live region via `role="status"`. Use `aria-live="polite"` on a parent only when you need to announce grouped updates beyond the badge itself.
 
 ## Content
 
@@ -71,5 +79,5 @@ Don't:
 
 ## Related components
 
-* [Pill](?path=/docs/core-pill--design) — For semantic status labels.
-* [Tag](?path=/docs/core-tag--design) — For removable text chips.
+* [Pill](/llms/core-pill--design.txt) — For semantic status labels.
+* [Tag](/llms/core-tag--design.txt) — For removable text chips.

package/docs/core-badge--usage.md

@@ -13,4 +13,10 @@ Badges display an indicator/counter on an associated component.
 | `className` | `never` | No | `--` | Use `FORCE__className` instead. |
 | `style` | `never` | No | `--` | Inline styles are not supported; use component props or `FORCE__className`. |
 | `FORCE__className` | `string` | No | `--` | 🚨 This prop is meant to be an escape hatch. 🚨<br><br>If the desired style cannot be achieved using component props, use this as a last resort. The inner workings of Capra components are implementation details and this escape hatch gives one access to those implementation details. We cannot make any guarantees that styles will applied correctly across version updates. Please use it responsibly.<br><br>Add a CSS class to the component. |
-| `aria-live` | `React.AriaAttributes['aria-live']` | No | `--` | `--` |
+| `aria-live` | `React.AriaAttributes['aria-live']` | No | `--` | `--` |
+
+## Accessibility
+
+Named badges require `aria-label` or `aria-labelledby`. Counter badges expose `role="status"` so the visible count is not treated as presentational. Dot badges expose `role="img"` because they have no text.
+
+Use `decorative` when the badge is purely presentational and the meaning is already conveyed nearby. Decorative badges omit the role and accessible name and set `aria-hidden`. Do not combine `decorative` with `aria-label` or `aria-labelledby`.

package/docs/core-breadcrumbs--design.md

@@ -62,4 +62,4 @@ Don't:
 
 ## Related components
 
-* [TabNav](?path=/docs/core-tabnav--design) — For in-page section navigation.
+* [TabNav](/llms/core-tabnav--design.txt) — For in-page section navigation.

package/docs/core-button--design.md

@@ -76,9 +76,9 @@ Do:
 
 Don't:
 
-* Don't use a Button for navigation to another page — use [Link](?path=/docs/core-link--design) or [Anchor](?path=/docs/core-anchor--design).
-* Don't use a Button for text-only inline navigation — use [Link](?path=/docs/core-link--design).
-* Don't use a Button for icon-only actions — use [IconButton](?path=/docs/core-iconbutton--design).
+* Don't use a Button for navigation to another page — use [Link](/llms/core-link--design.txt) or [Anchor](/llms/core-anchor--design.txt).
+* Don't use a Button for text-only inline navigation — use [Link](/llms/core-link--design.txt).
+* Don't use a Button for icon-only actions — use [IconButton](/llms/core-iconbutton--design.txt).
 * Don't use two primary buttons side by side.
 * Don't truncate button labels.
 * Don't disable a button without explaining why (use `aria-disabled` with a tooltip).
@@ -86,12 +86,12 @@ Don't:
 ## Accessibility
 
 * Always provide a visible text label; if the design requires a short label, add `aria-label` for context.
-* For icon-only use cases, use [IconButton](?path=/docs/core-iconbutton--design) instead (which enforces an accessible label).
+* For icon-only use cases, use [IconButton](/llms/core-iconbutton--design.txt) instead (which enforces an accessible label).
 * Tab / Shift+Tab to focus. Enter or Space to activate.
 * The pending state must be communicated to assistive technology (e.g., `aria-label="Saving..."` when `pending` is true).
 
 ## Related components
 
-* [IconButton](?path=/docs/core-iconbutton--design) — For icon-only actions.
-* [Link](?path=/docs/core-link--design) — For inline text navigation.
-* [Modal](?path=/docs/core-modal--design) — Buttons typically appear in modal footers for confirm/cancel patterns.
+* [IconButton](/llms/core-iconbutton--design.txt) — For icon-only actions.
+* [Link](/llms/core-link--design.txt) — For inline text navigation.
+* [Modal](/llms/core-modal--design.txt) — Buttons typically appear in modal footers for confirm/cancel patterns.

package/docs/core-buttonlink--design.md

@@ -2,6 +2,6 @@
 
 Primary interactive element displaying text and supporting leading and trailing icons.
 
-`ButtonLink` follows the design guidelines for [`Button`](?path=/docs/core-button--design) and uses [`Link`](?path=/docs/core-link--design) interally. Use it when you need a link styled as a button.
+`ButtonLink` follows the design guidelines for [`Button`](/llms/core-button--design.txt) and uses [`Link`](/llms/core-link--design.txt) interally. Use it when you need a link styled as a button.
 
 See those pages for more details on the properties and usage of `ButtonLink`.

package/docs/core-card--design.md

@@ -69,7 +69,7 @@ Treat the card as a container: put links and buttons inside slots rather than ma
 ## Behavior
 
 * Cards are static containers by default.
-* If the entire card is interactive (e.g., a selectable card), use `role="button"` with keyboard support. Prefer [RadioTile](?path=/docs/core-radiotile--design) for selection scenarios.
+* If the entire card is interactive (e.g., a selectable card), use `role="button"` with keyboard support. Prefer [RadioTile](/llms/core-radiotile--design.txt) for selection scenarios.
 
 ## Content
 
@@ -86,7 +86,7 @@ Do:
 
 Don't:
 
-* Don't make the entire card surface the only navigation affordance — put a [Link](?path=/docs/core-link--design) or [Button](?path=/docs/core-button--design) inside the content.
+* Don't make the entire card surface the only navigation affordance — put a [Link](/llms/core-link--design.txt) or [Button](/llms/core-button--design.txt) inside the content.
 * Don't use Card for tabular data — use a table.
 
 ## Accessibility
@@ -96,5 +96,5 @@ Don't:
 
 ## Related components
 
-* [RadioTile](?path=/docs/core-radiotile--design) — For selectable card options.
-* [Modal](?path=/docs/core-modal--design) — For focused overlay containers.
+* [RadioTile](/llms/core-radiotile--design.txt) — For selectable card options.
+* [Modal](/llms/core-modal--design.txt) — For focused overlay containers.

package/docs/core-checkbox--design.md

@@ -62,5 +62,5 @@ Don't:
 
 ## Related components
 
-* [Switch](?path=/docs/core-switch--design) — For immediate binary settings.
-* [RadioGroup](?path=/docs/core-radiogroup--design) — For mutually exclusive selections.
+* [Switch](/llms/core-switch--design.txt) — For immediate binary settings.
+* [RadioGroup](/llms/core-radiogroup--design.txt) — For mutually exclusive selections.

package/docs/core-checkbox--usage.md

@@ -8,6 +8,7 @@ Checkbox component for capturing boolean user input. Supports controlled and unc
 | `checked` | `boolean` | No | `--` | Controlled checked state. Use with onChange for controlled component. |
 | `defaultChecked` | `boolean` | No | `--` | Default checked state for uncontrolled component. |
 | `children` | `string \| React.ReactNode` | No | `--` | The label for the checkbox. |
+| `slot` | `string \| null` | No | `--` | Slot name for React Aria context wiring (e.g. "selection" in Table). |
 | `className` | `never` | No | `--` | Use `FORCE__className` instead. |
 | `style` | `never` | No | `--` | Inline styles are not supported; use component props or `FORCE__className`. |
 | `FORCE__className` | `string` | No | `--` | 🚨 This prop is meant to be an escape hatch. 🚨<br><br>If the desired style cannot be achieved using component props, use this as a last resort. The inner workings of Capra components are implementation details and this escape hatch gives one access to those implementation details. We cannot make any guarantees that styles will applied correctly across version updates. Please use it responsibly.<br><br>Add a CSS class to the component. |

package/docs/core-collapse--design.md

@@ -24,5 +24,5 @@ Use Collapse to structure readable content, separate regions, or group related i
 
 ## Related components
 
-* [Card](?path=/docs/core-card--design)
-* [Divider](?path=/docs/core-divider--design)
+* [Card](/llms/core-card--design.txt)
+* [Divider](/llms/core-divider--design.txt)

package/docs/core-divider--design.md

@@ -32,4 +32,4 @@ Don't:
 
 ## Related components
 
-* [Collapse](?path=/docs/core-collapse--design)
+* [Collapse](/llms/core-collapse--design.txt)

package/docs/core-link--design.md

@@ -54,5 +54,5 @@ Links inherit the standard focus indicator standard to all focusable elements.
 
 ## Related components
 
-* [Button](?path=/docs/core-button--design)
-* [Anchor](?path=/docs/core-anchor--design)
+* [Button](/llms/core-button--design.txt)
+* [Anchor](/llms/core-anchor--design.txt)

package/docs/core-selectfield--design.md

@@ -5,7 +5,7 @@
 1. **Label**: describes the field and carries the required marker when needed.
 2. **Trigger**: matches Capra text-input sizing and state treatments.
 3. **Popover**: contains the option list and optional search field.
-4. **ListBox items**: support single-select rows or multi-select rows with checkmarks.
+4. **ListBox items**: selected rows are marked with a checkmark in both single- and multiple-select modes.
 5. **Sections**: optional grouped options with a non-selectable header label.
 
 ## Properties

package/docs/core-table--design.md

@@ -0,0 +1,17 @@
+# Core/Table - Design
+
+A component for rendering tabular data
+
+## Properties
+
+### Density
+
+Tables have 3 different row sizes: `default`, `compact`, and `tight`.
+
+### Appearance
+
+Striped rows (aka: Zebra striping) provide contrast between rows by alternating the background color. This can be disabled with `appearance="flat"`.
+
+### Loading
+
+When tables are in a loading state the content is replaced with 5 rows of skeleton content that represents the general shape of the data.

package/docs/core-table--usage.md

@@ -0,0 +1,198 @@
+# Core/Table - Usage
+
+A component for rendering tabular data
+
+## Basic usage
+
+```tsx
+import { Table } from '@capra/core';
+
+type User = {
+  id: string;
+  name: string;
+};
+
+const userColumns = defineColumns<User>([
+  { id: 'name', label: 'Name', allowsSorting: true },
+])
+
+const users = [
+  {
+    id: 1,
+    name: 'Alice Johnson',
+  },
+  {
+    id: 2,
+    name: 'Bob Williams',
+  },
+];
+
+<Table
+  columns={userColumns}
+  visibleColumns={['name']}
+  items={users}
+/>
+```
+
+## Props
+
+| Prop | Type | Required | Default | Description |
+| --- | --- | --- | --- | --- |
+| `items` | `ItemRecord[]` | Yes | `--` | The data to render as rows in the Table |
+| `density` | `'default' \| 'compact' \| 'tight'` | No | 'default' | The density of the table, affects row height |
+| `appearance` | `'zebra' \| 'flat'` | No | 'zebra' | Whether to apply zebra-striping to rows |
+| `sortDescriptor` | `SortDescriptor` | No | `--` | Key and direction for sorting the Table |
+| `onSortChange` | `(sortDescriptor: SortDescriptor) => void` | No | `--` | Callback function fired when a the sorting configuration is changed |
+| `columns` | `ColumnConfig<ColumnKey, ItemRecord>[]` | Yes | `--` | The columns to render in the Table |
+| `visibleColumns` | `ColumnKey[]` | Yes | `--` | Which columns should be visible |
+| `isLoading` | `boolean` | No | false | Whether the table is in a loading state |
+| `enableDragAndDrop` | `boolean` | No | false | Whether drag-and-dropping rows is enabled |
+| `renderActionColumn` | `(item: ItemRecord) => React.ReactNode` | No | `--` | todo: is this prop needed? |
+| `selectionMode` | `SelectionMode` | No | `--` | Mode of row selection<br>@default 'none' |
+| `selectedKeys` | `Selection` | No | `--` | The currently selected keys (controlled) |
+| `onSelectionChange` | `(keys: Selection) => void` | No | `--` | Callback fired when selection changes |
+| `className` | `never` | No | `--` | Use `FORCE__className` instead. |
+| `style` | `never` | No | `--` | Inline styles are not supported; use component props or `FORCE__className`. |
+| `FORCE__className` | `string` | No | `--` | 🚨 This prop is meant to be an escape hatch. 🚨<br><br>If the desired style cannot be achieved using component props, use this as a last resort. The inner workings of Capra components are implementation details and this escape hatch gives one access to those implementation details. We cannot make any guarantees that styles will applied correctly across version updates. Please use it responsibly.<br><br>Add a CSS class to the component. |
+
+## Examples
+
+### Sorting
+
+```tsx
+import { Table } from '@capra/core';
+
+const userColumns = defineColumns<User>([
+  { id: 'name', label: 'Name', allowsSorting: true },
+  // ...
+])
+
+function SortableTable() {
+  const [sortDescriptor, setSortDescriptor] = useState<SortDescriptor | undefined>({
+    column: 'name',
+    direction: 'ascending',
+  });
+  const sortedItems = useMemo(() => sortItems(items, sortDescriptor), [sortDescriptor, items]);
+  return (
+    <Table
+      {...props}
+      items={sortedItems}
+      sortDescriptor={sortDescriptor}
+      onSortChange={setSortDescriptor}
+      visibleColumns={reverseColumns ? visibleColumns.toReversed() : visibleColumns}
+    />
+  );
+}
+```
+
+### Selection
+
+Use the `selectionMode` prop to enable `single` or `multiple` selection of rows.
+
+```tsx
+<Table
+  columns={userColumns}
+  visibleColumns={['name', 'email', 'balance', 'enabled', 'description', 'trend']}
+  items={sortedItems}
+  selectionMode="multiple"
+/>
+```
+
+### Filter toolbar
+
+Use the `FilterToolbar` component to support filtering and/or bulk editing.
+
+Note: `FilterToolbar` is only supported instances of `Table` with controlled selection.
+
+```tsx
+import { FilterToolbar, Table } from '@capra/core';
+
+function TableWithToolbar() {
+  const [filterString, setFilterString] = useState('');
+  const [selectedKeys, setSelectedKeys] = useState<Selection>(new Set());
+  const sortedItems = useMemo(() => sortItems(users, sortDescriptor), [sortDescriptor] );
+  const filteredItems = filterUsers(sortedItems, filterString)
+  const selectableCount = sortedItems.filter((item) => !item.isDisabled).length;
+  const selectedCount = selectedKeys === 'all' ? selectableCount : selectedKeys.size;
+
+  return (
+    <div style={{ display: 'flex', gap: '8px', flexDirection: 'column' }}>
+      <TableToolbar
+        filterInputProps={{
+          onChange: (value: string) => setFilterString(value)
+        }}
+        renderActions={() => (
+          <Button size="sm" variant="primary">Add user</Button>
+        )}
+        renderBulkEditText={() => (
+          <Text>
+            {selectedCount} of {sortedItems.length} users selected
+          </Text>
+        )}
+        renderBulkEditActions={() => (
+          <div style={{ display: 'flex', gap: '8px' }}>
+            <Button appearance="neutral" size="sm">
+              Delete
+            </Button>
+            <Button appearance="neutral" variant="tertiary" size="sm">
+              Cancel
+            </Button>
+          </div>
+        )}
+        selectedKeys={selectedKeys}
+      />
+      <Table
+        columns={userColumns}
+        visibleColumns={['name', 'email', 'balance']}
+        items={filteredItems}
+        selectionMode="multiple"
+        selectedKeys={selectedKeys}
+        onSelectionChange={setSelectedKeys}
+      />
+    </div>
+  );
+}
+```
+
+### Custom cell rendering
+
+```tsx
+import { Table } from '@capra/core';
+
+type User = {
+  id: string;
+  name: string;
+  email: string;
+};
+
+const userColumns = defineColumns<User>([
+  { id: 'name', label: 'Name', allowsSorting: true },
+  {
+    id: 'email',
+    label: 'Email',
+    allowsSorting: true,
+    render(value) {
+      return <Link href={`mailto:${value as string}`}>{value as string}</Link>;
+    },
+  },
+])
+
+const users = [
+  {
+    id: 1,
+    name: 'Alice Johnson',
+    email: 'alice@example.com',
+  },
+  {
+    id: 2,
+    name: 'Bob Williams',
+    email: 'bob@example.com',
+  },
+];
+
+<Table
+  columns={userColumns}
+  visibleColumns={['name', 'email']}
+  items={users}
+/>
+```

package/docs/core-textinput--usage.md

@@ -4,7 +4,7 @@ TextInput component for single-line text entry. Backwards compatible with Ant De
 
 :::warning[Internal only]
 
-`TextInput` is not exported from the public `@capra/core` API. For single-line text entry in product code, use [`TextField`](?path=/docs/core-textfield--design).
+`TextInput` is not exported from the public `@capra/core` API. For single-line text entry in product code, use [`TextField`](/llms/core-textfield--design.txt).
 
 :::
 

package/docs/core-togglebuttongroup--design.md

@@ -0,0 +1,89 @@
+# Core/ToggleButtonGroup - Design
+
+A group of toggle buttons for choosing one or more options from a set.
+
+## When to use
+
+Toggle button groups behave similarly to radio buttons, providing selection between multiple mutually exclusive options. They are also used to switch views, such as between list and grid view.
+
+Toggle button groups affect section-level views and are not a replacement for tabs.
+
+## Properties
+
+### Size
+
+The default size for toggle button groups is medium, which should be used in most cases. A small size is also available when the group appears inline with another component.
+
+### Label
+
+Labels should be short and succinct. For longer labels, consider a [Radio](/llms/core-radio--design.txt) or [SelectField](/llms/core-selectfield--design.txt).
+
+### Icon
+
+Icons may appear with a label as part of each button. All buttons within a group should have an icon, or none should.
+
+## Behavior
+
+### Control count
+
+Toggle button groups can have between 2 and 4 buttons.
+
+### View switching
+
+Toggle button groups can be used to switch the view of data at the section level, such as between a list view and grid view.
+
+Views should be presented in a consistent order:
+
+* List
+* Grid
+* Graph / Chart
+* Metrics
+
+### Filtering
+
+Toggle button groups can be used to filter data at the section level, such as a data range within a graph.
+
+## Best practices
+
+### Count
+
+**Do**
+
+Do consider a toggle button group if you have 2 to 4 succinct choices.
+
+**Don't**
+
+Don't use more than 4 buttons in a single group. Consider a [SelectField](/llms/core-selectfield--design.txt) if more than 4 choices are needed.
+
+### Wording
+
+**Do**
+
+Do keep labels short.
+
+**Don't**
+
+Don't use long, multi-word labels.
+
+### Consistent layout
+
+**Do**
+
+Do keep icons consistent and unchanged when a button becomes active.
+
+**Don't**
+
+Don't replace icons when in an active state.
+
+## Accessibility
+
+### Keyboard interaction
+
+| Key                             | Function                                                                                                                                                                                                                               |
+| ------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `Tab`<br />`Shift + Tab`        | Move focus into and out of the button group. When focus moves into a button group:<br />- if a button is checked, focus is set on the checked button;<br />- if no buttons are checked, focus is set on the first button in the group. |
+| `Enter`<br />`Space`            | Checks the focused button if not already selected.                                                                                                                                                                                     |
+| `Right Arrow`<br />`Down Arrow` | Move focus to the next button in the group.                                                                                                                                                                                            |
+| `Left Arrow`<br />`Up Arrow`    | Move focus to the previous button in the group.                                                                                                                                                                                        |
+
+Icon-only items require an `aria-label` because there is no visible text label. The group itself requires an `aria-label` (or `aria-labelledby`) so assistive technologies can identify the control set.

package/docs/core-togglebuttongroup--usage.md

@@ -0,0 +1,113 @@
+# Core/ToggleButtonGroup - Usage
+
+A group of toggle buttons for choosing one or more options from a set.
+
+## Basic usage
+
+```tsx
+import { useState } from 'react';
+import { ToggleButtonGroup, type Key } from '@capra/core';
+
+function Example() {
+  const [selectedKeys, setSelectedKeys] = useState<Set<Key>>(new Set(['day']));
+  return (
+    <ToggleButtonGroup
+      aria-label="Time period"
+      selectedKeys={selectedKeys}
+      onSelectionChange={setSelectedKeys}
+      items={[
+        { key: 'day', text: 'Day' },
+        { key: 'week', text: 'Week' },
+        { key: 'month', text: 'Month' },
+      ]}
+    />
+  )
+}
+```
+
+## Props
+
+| Prop | Type | Required | Default | Description |
+| --- | --- | --- | --- | --- |
+| `items` | `ToggleButtonGroupItem[]` | Yes | `--` | Items to render as toggle buttons. |
+| `size` | `Extract<ButtonSize, 'sm' \| 'md'>` | No | 'md' | Size forwarded to every rendered button. Defaults to `md`. |
+| `disabled` | `boolean` | No | false | Whether the entire group is disabled. |
+| `selectionMode` | `'single' \| 'multiple'` | No | 'single' | Whether single or multiple selection is enabled. Defaults to `single`. |
+| `selectedKeys` | `Iterable<Key>` | No | `--` | Controlled selected keys. |
+| `defaultSelectedKeys` | `Iterable<Key>` | No | `--` | Uncontrolled initial selected keys. |
+| `onSelectionChange` | `(keys: Set<Key>) => void` | No | `--` | Handler called when the selection changes. |
+| `disallowEmptySelection` | `boolean` | No | `--` | Whether the group must always have at least one selected item. |
+| `className` | `never` | No | `--` | Use `FORCE__className` instead. |
+| `style` | `never` | No | `--` | Inline styles are not supported; use component props or `FORCE__className`. |
+| `FORCE__className` | `string` | No | `--` | 🚨 This prop is meant to be an escape hatch. 🚨<br><br>If the desired style cannot be achieved using component props, use this as a last resort. The inner workings of Capra components are implementation details and this escape hatch gives one access to those implementation details. We cannot make any guarantees that styles will applied correctly across version updates. Please use it responsibly.<br><br>Add a CSS class to the component. |
+
+## Examples
+
+### Icons
+
+Buttons can display icons in addition to text, or replace text entirely.
+
+```tsx
+<ToggleButtonGroup
+  aria-label="Time period"
+  items={[
+    { key: 'align-left', text: 'Align left', icon: AlignLeft },
+    { key: 'align-center', text: 'Align center', icon: AlignCenter },
+    { key: 'align-right', text: 'Align right', icon: AlignRight },
+  ]}
+```
+
+When using icons only, `aria-label` is required.
+
+```tsx
+<ToggleButtonGroup
+  aria-label="Time period"
+  items={[
+    { key: 'align-left', icon: AlignLeft, 'aria-label': 'Align left' },
+    { key: 'align-center', icon: AlignCenter, 'aria-label': 'Align center' },
+    { key: 'align-right', icon: AlignRight, 'aria-label': 'Align right' },
+  ]}
+```
+
+### Multi-select
+
+```tsx
+<ToggleButtonGroup
+  aria-label="Time period"
+  selectionMode="multiple"
+  items={[
+    { key: 'day', text: 'Day' },
+    { key: 'week', text: 'Week' },
+    { key: 'month', text: 'Month' },
+  ]}
+/>
+```
+
+### Disabled state
+
+The entire `ToggleButtonGroup` can be disabled by setting the `disabled` prop.
+
+```tsx
+<ToggleButtonGroup
+  aria-label="Time period"
+  disabled
+  items={[
+    { key: 'day', text: 'Day' },
+    { key: 'week', text: 'Week' },
+    { key: 'month', text: 'Month' },
+  ]}
+/>
+```
+
+Alternatively, individual buttons can be disabled by setting the `disabled` prop on the individual item.
+
+```tsx
+<ToggleButtonGroup
+  aria-label="Time period"
+  items={[
+    { key: 'day', text: 'Day', disabled: true },
+    { key: 'week', text: 'Week' },
+    { key: 'month', text: 'Month' },
+  ]}
+/>
+```