@capra/core 1.5.3 → 1.7.0

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

@@ -0,0 +1,87 @@
+# Core/IconButton - Design
+
+Interactive element displaying a single icon.
+
+## Properties
+
+### Icon
+
+<p>
+  Icon buttons are used to quickly identify available actions.
+</p>
+
+<p>
+  Common actions, like save or search, can omit titles and use the icon alone. Avoid using an icon alone when the meaning is ambiguous, unclear, or unfamiliar.
+</p>
+
+<p>
+  View available icons in the Icon library.
+</p>
+
+### Size
+
+<p>
+  Buttons are available in small, medium, and large sizes. Medium is the default size and is preferred in most situations.
+</p>
+
+<p>
+  Small buttons are primarily used when buttons appear inline with over components, such as in a popover and to conserve space.
+</p>
+
+### Loading
+
+<p>
+  Buttons can show a loading state for actions that take longer to respond.
+</p>
+
+<p>
+  The loading spinner is shown in the leading icon slot, replacing an icon if present. Button text should be updated to indicate the action currently taking place. Further interaction is disabled until the action is complete. 
+</p>
+
+## Behavior
+
+### Tooltips
+
+<p>
+  Icon buttons reveal the label in a tooltip on hover or long-press.
+</p>
+
+<img src="images/guidelines/iconbutton/behavior-tooltip.png" />
+
+### Loading delay
+
+<p>
+  Buttons can show a loading state for actions that take longer to respond.
+</p>
+
+<p>
+  The loading spinner is shown in place of the icon. Further interaction is disabled until the action is complete.
+</p>
+
+### State
+
+<p>
+  Buttons use a color shift between palette indexes for interaction states. The available sates are enabled, hover, active, focused, disabled, and pending.
+</p>
+
+<img src="images/guidelines/iconbutton/behavior-state.png" />
+
+## Accessibility
+
+### Keyboard interaction
+
+All buttons exist in the page’s natural tab sequence, reachable via TAB and SHIFT+TAB keys. Pressing SPACEBAR or ENTER activates the focused button.
+
+### Labeling
+
+<p>
+  For buttons with an icon and text, if the icon reinforces the text, do not add any description of the icon as it would be redundant.
+</p>
+
+<p>
+  If the icon adds important information that is not explained in the text, then the label of the button must begin with the text with any extra information about the icon following the text.  This order supports users who control their device with speech.
+</p>
+
+<p>
+  Icon buttons without text must have an easily identifiable (for speech users) accessible label, such as “Download.”
+</p>

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

@@ -0,0 +1,15 @@
+# Core/IconButton - Usage
+
+Interactive element displaying a single icon.
+
+| Prop | Type | Required | Default | Description |
+| --- | --- | --- | --- | --- |
+| `icon` | `SvgIcon` | Yes | `--` | Icon to display in the button. |
+| `aria-label` | `string` | Yes | `--` | Accessibility label to apply to the button. |
+| `variant` | `(typeof variants)[number]` | No | 'secondary' | Which button style to use. Defaults to `secondary`. |
+| `appearance` | `(typeof appearances)[number]` | No | 'default' | Appearance to apply to the button. Defaults to `default`. |
+| `size` | `(typeof sizes)[number]` | No | 'md' | Size of the button. Defaults to `md`. |
+| `disabled` | `boolean` | No | false | Whether the button is disabled. |
+| `pending` | `boolean` | No | false | Whether the button is in a pending state. |
+| `onClick` | `React.ComponentProps<'button'>['onClick']` | No | `--` | Click handler for the button. |
+| `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-inputrow--design.md

@@ -0,0 +1,85 @@
+# Core/InputRow - Design
+
+## Overview
+
+`InputRow` is a horizontal container that visually merges one primary input with optional prefix and
+suffix segments so the whole group reads as a single control. Use it for URLs, currency amounts, units, fixed
+labels (for example `https://` or `.com`), and similar patterns where the value only makes
+sense together with its neighbors.
+
+## `InputRow`
+
+### Role and labeling
+
+The root is a `div` laid out as a flex row. When you pass `aria-label` or `aria-labelledby`, the row defaults to `role="group"` so assistive technologies can treat
+the children as one related set. Give the row a short name that describes the combined value (for example
+“Web address” or “Price”).
+
+Order children left-to-right: leading segment, primary field, trailing segment. Capra field wrappers use `display: contents` when they are **direct** children of the row, so the inner input
+participates in the flex layout and border-joining rules; keep fields and addons as immediate children of `InputRow`.
+
+### Visual treatment
+
+Only the outer corners of the group use the standard field radius; shared edges between segments stay square
+so borders overlap cleanly instead of doubling. Adjacent borders are collapsed with a small negative margin;
+the segment that contains focus is raised in the stacking order so its focus ring stays visible.
+
+## `InputRow.Addon`
+
+### Static segments
+
+`InputRow.Addon` is for **non-editable** content: fixed text, symbols, or decorative
+icons. String children are rendered with the typography `Text` component; pass arbitrary nodes for
+icons or richer content.
+
+Addons are flex-shrink-safe strips with a muted surface and field-aligned borders so they match `TextInput` height and baseline. Place one or more addons before and/or after the field; the
+primary input should remain the flexible segment in the middle when you have both sides.
+
+### Size
+
+The `size` prop on `InputRow.Addon` (`md` by default, or `sm`)
+controls minimum height and typography so the addon lines up with an adjacent `TextField` or `NumberField` using the same `size`.
+
+## Composing with Capra `*Field` components
+
+### Which fields to use
+
+`TextField` and `NumberField` are the usual primary controls inside a row. Other Capra
+field roots that expose `data-capra-field-root` (for example `AutocompleteField`, `DatePicker`, or `DateRangePicker`) use the same layout hook: the wrapper does not create
+an extra flex box, so the inner control can share borders with addons like a plain `TextInput`.
+
+Prefer one primary editable control per row. Pair it with `InputRow.Addon` for fixed text or icons,
+or with another bordered control as a leading/trailing segment when the design calls for a separate control
+(for example a unit or scheme picker), keeping that control a direct child so border overlap still applies.
+
+### Labels, helper text, and slots
+
+Do not pass `label`, `helperText`, or `layout` props on Capra field wrappers
+inside an `InputRow`. Those patterns reserve vertical space for label and helper rows and break the
+single horizontal group.
+
+Put the visible label (if any) *outside* the row—for example a standalone `Label` or
+surrounding copy tied with `aria-labelledby` on `InputRow`. For validation or hints,
+show helper text below the whole row, not on the nested field.
+
+Avoid `leadingSlot` and `trailingSlot` on `TextField` when the same concern is
+already expressed with `InputRow.Addon`; slots are meant for compact adornments on the input itself,
+not for full row segments.
+
+### Accessible names
+
+When `label` is omitted on nested fields, each focusable control still needs a name: use `aria-label` or `aria-labelledby` on `TextField`, `NumberField`, or
+the inner input as documented for that component. The row-level `aria-label` names the group; each
+control should have its own short name (“Domain”, “Amount”, “Unit”, and so on) where several tab stops exist.
+
+## Accessibility
+
+### Grouping
+
+When the row combines multiple inputs or segments that share one label, put `aria-label` or `aria-labelledby` on `InputRow` and ensure each focusable control still has a distinct
+accessible name where needed.
+
+### Addons
+
+Treat `InputRow.Addon` as presentational unless the text is essential; decorative icons should use `aria-hidden`. If addon text conveys meaning not duplicated elsewhere, leave it in the accessibility
+tree.

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

@@ -0,0 +1,6 @@
+# Core/InputRow - Usage
+
+| Prop | Type | Required | Default | Description |
+| --- | --- | --- | --- | --- |
+| `children` | `React.ReactNode` | No | `--` | `--` |
+| `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-label--design.md

@@ -0,0 +1,27 @@
+# Core/Label - Design
+
+Label text and optional required indicator for form fields, aligned with Capra field layouts.
+
+:::warning
+
+Prefer Capra field components—such as `TextField`, `NumberField`, `PasswordField`, `TextArea`, `DatePicker`, `DateRangePicker`, or `AutocompleteField`—which
+wire labels, inputs, and helper text together with consistent layout and accessibility. Use standalone `Label` only when you are composing a custom field or integrating with primitives that do not ship a built-in label.
+
+:::
+
+## Accessibility
+
+### Association
+
+<p>
+  Pair `Label` with its control using `htmlFor` on the label and a matching `id` on
+  the input (or equivalent association pattern for custom widgets). Every form control should have an accessible name;
+  a visible `Label` is one straightforward way to provide it.
+</p>
+
+### Required fields
+
+<p>
+  The visual asterisk for <code>required</code> is marked <code>aria-hidden</code> so it is not double-announced; the
+  required state is also conveyed with visually hidden text for screen readers.
+</p>

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

@@ -0,0 +1,17 @@
+# Core/Label - Usage
+
+Label text and optional required indicator for form fields, aligned with Capra field layouts.
+
+| Prop | Type | Required | Default | Description |
+| --- | --- | --- | --- | --- |
+| `children` | `string` | No | `--` | Text to display in the label. |
+| `required` | `boolean` | No | `--` | Whether the field the label is labeling is required (shows asterisk after label). |
+| `trailingSlot` | `React.ReactNode` | No | `--` | Content after the label text. |
+| `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. |
+
+## React Aria
+
+<p>
+  The component uses <code>useContextProps</code> with React Aria’s <code>LabelContext</code>, so when it sits inside
+  compatible React Aria structures, label props can be supplied by context as well as passed directly.
+</p>

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

@@ -0,0 +1,58 @@
+# Core/Link - Design
+
+Links are navigational elements that take users to a new page.
+
+## Properties
+
+### Text
+
+The text representing the link should describe its destination.
+
+### isExternal
+
+External links display an icon at the trailing end of the link. They navigate to a page outside the product and open
+in a new tab.
+
+### Client-side Routing
+
+Links support client-side routing out of the box when Capra's `RouterProvider` is used. See the
+[Conventions](/docs/conventions--docs#client-side-routing) page for more details.
+
+## Best Practices
+
+**Do**
+
+<p>
+  Do clearly indicate the destination of a link through its text.
+</p>
+
+**Don't**
+
+<p>
+  Don't use vague instructions, such as “click here”, for links.
+</p>
+
+## Accessibility
+
+### Keyboard interaction
+
+All links exist in the page's natural tab sequence, reachable via TAB and SHIFT+TAB keys. Pressing ENTER activates
+the focused link.
+
+### External links
+
+External links should announce themselves as opening in a new tab. For example: "Link text, opens in a new tab."
+
+### Keyboard focus indicator
+
+Links inherit the standard focus indicator standard to all focusable elements.
+
+## Accessibility
+
+* Meaningful link text: describe the destination, not "click here" or "read more".
+* External links: announce the new-tab behavior in the link text or `aria-label` (e.g., "Opens in new tab").
+
+## Related components
+
+* [Button](?path=/docs/core-button--design)
+* [Anchor](?path=/docs/core-anchor--design)

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

@@ -0,0 +1,16 @@
+# Core/Link - Usage
+
+Links are navigational elements that take users to a new page.
+
+| Prop | Type | Required | Default | Description |
+| --- | --- | --- | --- | --- |
+| `as` | `As` | No | `--` | The underlying element rendered by the component. Defaults to `a`. |
+| `isExternal` | `boolean` | No | false | Whether the Link points to an external resource.<br><br>When `true` and `as="a"`, applies `target="_blank"` and `rel="noopener noreferrer"`.<br><br>Defaults to `false`. |
+| `href` | `unknown` | No | `--` | A URL to link to. See [MDN](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/a#href). |
+| `hrefLang` | `string` | No | `--` | Hints at the human language of the linked URL. See[MDN](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/a#hreflang). |
+| `target` | `HTMLAttributeAnchorTarget` | No | `--` | The target window for the link. See [MDN](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/a#target). |
+| `rel` | `string` | No | `--` | The relationship between the linked resource and the current page. See [MDN](https://developer.mozilla.org/en-US/docs/Web/HTML/Attributes/rel). |
+| `download` | `boolean \| string` | No | `--` | Causes the browser to download the linked URL. A string may be provided to suggest a file name. See [MDN](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/a#download). |
+| `referrerPolicy` | `HTMLAttributeReferrerPolicy` | No | `--` | How much of the referrer to send when following the link. See [MDN](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/a#referrerpolicy). |
+| `routerOptions` | `unknown` | No | `--` | Options for the configured client side router. |
+| `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-listitem--design.md

@@ -0,0 +1,70 @@
+# Core/ListItem - Design
+
+## Properties
+
+### Leading
+
+Leading slots are commonly used for icons, avatars, or checkboxes.
+
+### Label
+
+A label is required for all list items. Their length may vary based on application but should always be succinct.
+
+### Description
+
+The description slot is used to display the description of the list item.
+
+### Suffix
+
+A suffix provides space for information such as item counts.
+
+### Trailing
+
+Trailing slots are most often used for components providing supplementary information, such as Pills, or controls for menus.
+
+## Behavior
+
+### Spacing
+
+### Overflow
+
+Labels will wrap if they are wider than the parent container. The list item remains aligned to the top of the text
+box.
+
+## Best Practices
+
+**Do**
+
+<p>
+  Do maintain consistent with usage of leading and trailing slots.
+</p>
+
+**Don't**
+
+<p>
+  Don't mix items with and without slots.
+</p>
+
+**Do**
+
+<p>
+  Do keep interaction to single action per row.
+</p>
+
+**Don't**
+
+<p>
+  Avoid having multiple interactive elements in a list row.
+</p>
+
+**Do**
+
+<p>
+  Do omit unnecessary visual clutter, such as dividers.
+</p>
+
+**Don't**
+
+<p>
+  Don't include dividers when using a list group.
+</p>

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

@@ -0,0 +1,6 @@
+# Core/ListItem - Usage
+
+| Prop | Type | Required | Default | Description |
+| --- | --- | --- | --- | --- |
+| `as` | `As` | No | `--` | `--` |
+| `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-menu--design.md

@@ -0,0 +1,106 @@
+# Core/Menu - Design
+
+## Properties
+
+### Label
+
+A label is required for all menu items. Their length may vary based on application but should always be succinct.
+
+### Description
+
+Descriptions can provide secondary information to menu items.
+
+### Icon
+
+Capra does not suggest the use of icons in menu items, but an optional slot is available when an icon adds significant recognition.
+
+### Shortcut
+
+Shortcuts enable users to more easily access common commands. If available, shortcuts to a command should be shown at the right. A menu does not need to be open for a shortcut to work.
+
+### Indent
+
+Use `Menu.Section` to group `Menu.Item` rows. Add an optional `Menu.Header` inside the section to label the group; items in that section indent automatically to show hierarchy. A `Menu.Header` outside a section is only a label and does not indent following items—wrap the header and its items in `Menu.Section` when you want indentation. Sections without a header must be named for assistive technology with `aria-label` or `aria-labelledby`. You can still set `indent` on an item to override the default.
+
+## Content
+
+### Ellipsis
+
+Use ellipsis to indicate when the menu item leads to additional steps. This is normally followed by a modal.
+
+### Divider
+
+Dividers provide subtle separation between list items. They can be used to group items when a header is not necessary. Use `Menu.Divider` between menu items to create visual separation.
+
+## Selection
+
+### Single selection
+
+Single selection items act as radio buttons within a menu. Use the `active` prop to indicate the current page or selected item.
+
+### Multiple selection
+
+Multiple selection items act as checkboxes within a menu. Users can select more than one item. Use the `active` prop on each `Menu.Item` to indicate selected items. Manage selection state in your application.
+
+### Section-level selection
+
+When single and/or multiple section options are used alongside other option types, use Sections to group each selection type.
+
+## Behavior
+
+### Focus containment (`trapFocus`)
+
+Set **`trapFocus`** on **`Menu`** when keyboard focus must stay inside the menu panel while it is open—for example horizontal **`TabNav`** flyouts that sit next to other tab stops. The popover stays **non-modal**, so outside pointer dismiss still works. Focus **containment** turns on once focus has entered the panel (so the trigger can still move focus into the menu on open); **`restoreFocus`** returns focus to the trigger when the menu closes.
+
+When **`trapFocus`** is omitted (**default `false`**), focus follows the usual tab sequence for a non-modal overlay.
+
+### Submenu
+
+Use `Menu.Submenu` for nested flyouts: Capra requires `SubmenuTrigger` → `Popover` → `Menu` so the nested panel is positioned to the side (not stacked under the trigger). The parent row shows a trailing chevron; hover or keyboard opens the submenu. The `parent` prop on `Menu.Item` only adds the chevron for labels without a submenu.
+
+### Minimum and maximum width
+
+Menu items have a minimum width of 152px and maximum width of 256px. Content that extends beyond the maximum width is truncated. An ellipsis is *not* added due to the special meaning of the ellipsis following an item label. Care should be taken to ensure menu item labels remain short and succinct to avoid running over the maximum width.
+
+## Best Practices
+
+### Menu Size
+
+**Do**
+
+<img className="w-full" src="images/guidelines/menu/bestpractices-size-do.png" alt="Menu with appropriate number of items" />
+
+<p>
+  Do keep menus to as few items as possible, aim for no more than 5 items.
+</p>
+
+**Don't**
+
+<img className="w-full" src="images/guidelines/menu/bestpractices-size-dont.png" alt="Overly long menu" />
+
+<p>
+  Don't overload menu item choices.
+</p>
+
+## Accessibility
+
+### Keyboard interaction
+
+| Key                   | Function                                                                                                                                                  |
+| --------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `Tab` / `Shift + Tab` | Moves focus to, or away from, the trigger. If the menu is open, focus shifts away from the trigger and the menu closes.                                   |
+| `Enter`               | If the trigger has focus: opens the menu and focuses the first item. If a menu item has focus: activates that item and closes the menu.                   |
+| `Space`               | If the trigger has focus, opens the menu and focuses the first item.                                                                                      |
+| `Down Arrow`          | If the trigger has focus: opens the menu and focuses the first item. If a menu item has focus: moves focus to the next item, wrapping from last to first. |
+| `Up Arrow`            | If a menu item has focus: moves focus to the previous item, wrapping from first to last.                                                                  |
+| `Esc`                 | Closes the menu and returns focus to the trigger.                                                                                                         |
+| `[a-z]`               | Move focus to the next item whose label begins with that printable character.                                                                             |
+
+### Aria considerations
+
+* Triggers must have an accessible name (`aria-label` or `aria-labelledby`) or label.
+* Triggers must have `aria-haspopup="menu"` and use `aria-expanded="true|false"`.
+* Use `role="menu"` on menu container.
+* Use `role="menuitem"` on each menu item.
+* Use `role="separator"` if a separator is used.
+* Group related items with `Menu.Section` (`role="group"`). When the section includes `Menu.Header`, the section is named via `aria-labelledby` (the header gets an id). Headerless sections must expose a name with `aria-label` or `aria-labelledby`.

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

@@ -0,0 +1,16 @@
+# Core/Menu - Usage
+
+| Prop | Type | Required | Default | Description |
+| --- | --- | --- | --- | --- |
+| `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. |
+| `trigger` | `React.ReactElement` | Yes | `--` | Single element that toggles the menu (e.g. button). Rendered as the menu trigger; must forward refs to a focusable DOM node (wrapped with React Aria {@link Pressable} internally). |
+| `children` | `React.ReactNode` | No | `--` | Menu content. Use Menu.Item, Menu.Section, Menu.Header, Menu.Divider. |
+| `contentProps` | `React.HTMLAttributes<HTMLDivElement>` | No | `--` | Optional props for the element wrapping the menu panel (e.g. pointer handlers when bridging trigger and menu). |
+| `open` | `boolean` | No | `--` | Controlled open state. Omit for uncontrolled usage. |
+| `onOpenChange` | `(open: boolean) => void` | No | `--` | Called when the menu should open or close. |
+| `itemHoverAppearance` | `'default' \| 'accent'` | No | 'default' | Hover/selected styling for items. `accent`: TabNav submenu treatment per Tab Nav \| Vertical \| Item (Figma)—hover uses primary background + accent-hover text; selected uses accent-selected background, accent text, semibold label, inline-end accent bar. `default`: neutral grey hover only.<br>@default 'default' |
+| `itemActiveAccentBar` | `boolean` | No | true | When `itemHoverAppearance` is `accent`, whether the active/selected row shows the inline-end accent bar (vertical TabNav indicator). Set to `false` for horizontal TabNav flyout menus where selection should not show that bar.<br>@default true |
+| `itemActiveLabelSemibold` | `boolean` | No | true | When `itemHoverAppearance` is `accent`, whether the active/selected row uses a semibold label. Set to `false` for TabNav horizontal submenus where the active item should match normal menu weight.<br>@default true |
+| `panelPadding` | `'default' \| 'none'` | No | 'default' | Inset of the menu panel (`role="menu"`). `none` uses a minimal inset so focus rings are not clipped under scroll/overflow; use for flyouts that should sit close to the popover edge (e.g. TabNav submenu).<br>@default 'default' |
+| `popoverOffset` | `number` | No | 0 | Gap along the main axis between the trigger and the menu panel (React Aria `Popover` `offset`).<br>Use a small value (e.g. 1) when the panel should clear a trigger underline/border (e.g. horizontal TabNav).<br>@default 0 |
+| `trapFocus` | `boolean` | No | false | When `true`, focus is contained in the menu panel while it is open (Tab cycles within the panel; focus restores on close).<br>The popover stays non-modal so outside pointer dismiss still works. Use for patterns that must not move focus to sibling controls until the menu closes (e.g. horizontal TabNav flyouts).<br>@default false |

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

@@ -0,0 +1,39 @@
+# Core/Modal - Design
+
+## Properties
+
+### Size
+
+Modals come in three sizes: small, medium, and large. Medium is the default size.
+The height of the modal adjusts to the content, up to a maximum height.
+
+### Layered modals
+
+Modals automatically stack such that the most recent modal is interactive while preserving the
+backdrop of previous layers.
+
+:::warning
+
+Modals should never be layered. This causes accessibility and usability issues. Open modals should be closed before new ones are opened.
+
+Current instances of layered modals in the product should be refactored to no longer be layered.
+
+:::
+
+## Accessibility
+
+### Keyboard interaction
+
+| Key                    | Function                                                                                                |
+| ---------------------- | ------------------------------------------------------------------------------------------------------- |
+| `Tab`<br />`Shift-Tab` | Moves focus to the next/previous focusable element within the modal. Focus is trapped within the modal. |
+| `Escape`               | Closes the modal.                                                                                       |
+| `Enter`<br />`Space`   | Activates the focused element (e.g., buttons in the footer).                                            |
+
+### WAI-ARIA Roles, States, and Properties
+
+* The modal container has `role="dialog"` and `aria-modal="true"`.
+* The modal title has a unique ID and the modal container has `aria-labelledby` set to that ID.
+* The modal overlay has `role="button"` and acts as a backdrop that can close the modal when clicked (if configured).
+* Focus is automatically moved to the modal when it opens and restored to the trigger when it closes.
+* The `body` element has `overflow: hidden` applied when the modal is open to prevent background scrolling.

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

@@ -0,0 +1,11 @@
+# Core/Modal - Usage
+
+### Modal
+
+| Prop | Type | Required | Default | Description |
+| --- | --- | --- | --- | --- |
+| `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. |
+| `size` | `string` | No | 'md' | `--` |
+| `isDismissible` | `boolean` | No | true | `--` |
+| `confirmButtonText` | `string` | No | 'OK' | `--` |
+| `cancelButtonText` | `string` | No | 'Cancel' | `--` |

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

@@ -0,0 +1,12 @@
+# Core/NumberField - Design
+
+Number field built on React Aria `NumberField`, with custom increment/decrement controls (native spinners hidden).
+
+## Anatomy
+
+Single-line numeric field with custom increment/decrement controls. Use `min`, `max`, and `step` for native constraint and stepping behavior.
+
+## Accessibility
+
+* The input is a text field with `aria-roledescription` of “Number field”. Keyboard users can adjust values with arrow keys where supported.
+* Set `aria-invalid` via `appearance="danger"`, and `aria-required` when `required` is set.

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

@@ -0,0 +1,14 @@
+# Core/NumberField - Usage
+
+Number field built on React Aria `NumberField`, with custom increment/decrement controls (native spinners hidden).
+
+| Prop | Type | Required | Default | Description |
+| --- | --- | --- | --- | --- |
+| `onChange` | `(value: number) => void` | No | `--` | Called with the unformatted number value when the number changes. |
+| `formatOptions` | `Intl.NumberFormatOptions` | No | `--` | Locale-aware display and parsing for the displayed value (see https://react-aria.adobe.com/NumberField#format-options) |
+| `min` | `number` | No | `--` | Minimum value |
+| `max` | `number` | No | `--` | Maximum value |
+| `step` | `number` | No | `--` | Step increment. When omitted, defaults to `1` (same as native `input type="number"`). |
+| `helperText` | `string` | No | `--` | Helper text below the field. Replaced by error message when status is error. Use for requirements, disclaimers. |
+| `label` | `string` | No | `--` | Label for the field. Required for accessibility; use aria-label if another element acts as label. |
+| `layout` | `'vertical' \| 'horizontal'` | No | `--` | Label and field layout: vertical (label above) or horizontal (label on leading side). Prefer vertical; use horizontal when space is limited. |

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

@@ -0,0 +1,30 @@
+# Core/Pagination - Design
+
+Pagination component for navigating through paged content. Renders prev/next buttons and a page number input with total pages indicator.
+
+## Properties
+
+### Total Pages
+
+The total number of pages.
+
+## Behavior
+
+### Page Updates
+
+Page updates occur immediately when clicking the forward or backward buttons. Entering a value in the input field
+will update when pressing Enter or when focus is moved.
+
+## Accessibility
+
+### Keyboard interaction
+
+| Key                      | Function                                                                                                                                                        |
+| ------------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `Tab`<br />`Shift + Tab` | - Moves focus to the next/previous focusable element.                                                                                                           |
+| `Enter`                  | - If an action button is focused: activates that button.<br />- If the page input field is focused: updates the entered page. Focus remains on the input field. |
+
+### Aria considerations
+
+* Use the `nav` element to wrap the pagination.
+* The `nav` element must have an accessible name (`aria-label` or `aria-labelledby`) or label.

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

@@ -0,0 +1,13 @@
+# Core/Pagination - Usage
+
+Pagination component for navigating through paged content. Renders prev/next buttons and a page number input with total pages indicator.
+
+| Prop | Type | Required | Default | Description |
+| --- | --- | --- | --- | --- |
+| `total` | `number` | Yes | `--` | Total number of data items. Used with `pageSize` to compute total pages. |
+| `current` | `number` | Yes | `--` | Current page number (1-based). |
+| `pageSize` | `number` | No | 10 | Number of items per page. Defaults to `10`. |
+| `onChange` | `(page: number, pageSize: number) => void` | No | `--` | Callback when page changes. |
+| `disabled` | `boolean` | No | false | Whether the pagination is disabled. |
+| `aria-label` | `string` | Yes | `--` | Accessible name for the navigation. Required for accessibility. |
+| `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. |