@capra/core 1.5.3 → 1.6.0

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. |

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

@@ -0,0 +1,7 @@
+# Core/PasswordField - Design
+
+Password field with a trailing control to show or hide the value. Composes {@link TextField}; visibility toggles the underlying input between `password` and `text`.
+
+## Accessibility
+
+`PasswordField` is a thin wrapper around `TextField` with `type="password"` and a visibility toggle. It inherits the same keyboard support, focus management, and labeling expectations as `TextField`: associate a visible label, keep error text programmatically linked, and ensure the toggle remains reachable and operable via keyboard.

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

@@ -0,0 +1,3 @@
+# Core/PasswordField - Usage
+
+Password field with a trailing control to show or hide the value. Composes {@link TextField}; visibility toggles the underlying input between `password` and `text`.

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

@@ -0,0 +1,94 @@
+# Core/Pill - Design
+
+## Variants
+
+### Default
+
+Default pills communicate information neutral of intent.
+
+### Info
+
+Information pills communicate general information or an important property.
+
+### Danger
+
+Danger pills communicate problems that require action to be resolved.
+
+### Warning
+
+Warning pills can communicate information that is time-sensitive, or trending towards an 'attention' state.
+
+### Success
+
+Success pills communicate successful states or completed actions.
+
+### Highlight
+
+Highlight pills bring special attention to metadata without communicating status.
+
+## Other properties
+
+### Label
+
+Labels should use short and clear messaging, in one or two words. Labels are required.
+
+### Icon
+
+An optional icon is available. Use solid icons.
+
+## Style
+
+### Bold
+
+Pills have a bold and muted style.
+
+* **Bold**: Can be used for isolated pills, such as when in the header of an object details page. Use bold pills with caution, since they can easily distract from the primary content. Be cautious with multiple bold pills on a single page, and absolutely avoid multiple bold pills in close proximity.
+* **Muted**: Used when pills are inline with other content, such as table cells.
+
+### Muted
+
+Pills have a bold and muted style.
+
+* **Bold**: Can be used for isolated pills, such as when in the header of an object details page. Use bold pills with caution, since they can easily distract from the primary content. Be cautious with multiple bold pills on a single page, and absolutely avoid multiple bold pills in close proximity.
+* **Muted**: Used when pills are inline with other content, such as table cells.
+
+### Hollow
+
+Pills have a bold and muted style.
+
+* **Bold**: Can be used for isolated pills, such as when in the header of an object details page. Use bold pills with caution, since they can easily distract from the primary content. Be cautious with multiple bold pills on a single page, and absolutely avoid multiple bold pills in close proximity.
+* **Muted**: Used when pills are inline with other content, such as table cells.
+
+## Best Practices
+
+**Do**
+
+<img src="pill-bestpractices-label-do.png" />
+
+<p>
+  Do provide label that succinctly communicates the pill's messaging.
+</p>
+
+**Don't**
+
+<img src="pill-bestpractices-label-dont.png" />
+
+<p>
+  Don't us a pill with just an icon.
+</p>
+
+**Do**
+
+<img src="pill-bestpractices-interaction-do.png" />
+
+<p>
+  Do use pills to message and inform the user.
+</p>
+
+**Don't**
+
+<img src="pill-bestpractices-interaction-dont.png" />
+
+<p>
+  Don't use a tooltip or make a pill interactive.
+</p>

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

@@ -0,0 +1,10 @@
+# Core/Pill - Usage
+
+| Prop | Type | Required | Default | Description |
+| --- | --- | --- | --- | --- |
+| `children` | `string` | Yes | `--` | The label text to display in the pill. The label should use short and clear messaging, in one or two words. Labels are required. |
+| `icon` | `React.ReactNode` | No | `--` | Overrides the default icon shown based on the pill appearance and variant.<br><br><b>To use this prop you will need a design review!</b> |
+| `variant` | `'bold' \| 'muted' \| 'outline'` | No | 'bold' | A variant to apply to the pill. Only applies when the appearance is not 'default'.<br><br><ul><br>  <li><br>    'bold' - Can be used for isolated pills, such as when in the header of an object details page.<br>    Use bold pills with caution, since they can easily distract from the primary content.<br>    Be cautious with multiple bold pills on a single page, and absolutely avoid multiple bold pills in close proximity.<br>  </li><br>  <li>'muted' - Used when pills are inline with other content, such as table cells.</li><br></ul><br><br>@default 'bold' |
+| `appearance` | `'default' \| 'info' \| 'danger' \| 'warning' \| 'success' \| 'highlight'` | No | 'default' | The appearance of the pill, which determines its color and severity.<br><br><ul><br>  <li>'info' - Information pills communicate general information or an important property.</li><br>  <li>'danger' - Danger pills communicate problems that require action to be resolved.</li><br>  <li>'warning' - Warning pills can communicate information that is time-sensitive, or trending towards a danger state.</li><br>  <li>'success' - Success pills communicate successful states or completed actions.</li><br>  <li>'highlight' - Highlight pills bring special attention to metadata without communicating status.</li><br></ul><br><br>@default 'default' |
+| `inline` | `boolean` | No | false | Whether to render the pill as an inline element. This is useful when the pill is used in a heading or other inline context.<br><br>By default, the pill will be rendered as a block element.<br><br>@default false |
+| `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-popover--design.md

@@ -0,0 +1,25 @@
+# Core/Popover - Design
+
+A popover component that renders a trigger and popover content.
+
+### Placement
+
+The popover can be positioned relative to the trigger element in 12 different directions. The default
+placement is `top`.
+
+## Accessibility
+
+### Keyboard interaction
+
+| Key      | Function                                                                                                                      |
+| -------- | ----------------------------------------------------------------------------------------------------------------------------- |
+| `Escape` | Closes the popover and returns focus to the trigger.                                                                          |
+| `Tab`    | Moves focus to the next focusable element. If the popover contains focusable elements, they are included in the tab sequence. |
+
+### WAI-ARIA Roles, States, and Properties
+
+* The popover container has `role="dialog"`.
+* The trigger has `aria-expanded` set to `true` when the popover is open, and `false` otherwise.
+* The trigger has `aria-controls` set to the ID of the popover content.
+* The popover has `aria-hidden` set to `false` when open, and `true` when hidden (unless removed from DOM).
+* The popover has `aria-describedby` pointing to the content element.

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

@@ -0,0 +1,8 @@
+# Core/Popover - Usage
+
+A popover component that renders a trigger and popover content.
+
+| Prop | Type | Required | Default | Description |
+| --- | --- | --- | --- | --- |
+| `content` | `React.ReactNode` | Yes | `--` | The popover content to be displayed. |
+| `children` | `React.ReactNode` | Yes | `--` | The visible trigger element. This can be a single element or a component tree, but there MUST be a `Button` or `IconButton` in the tree. Only Capra buttons will trigger the popover. |

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

@@ -0,0 +1,39 @@
+# Core/Radio - Design
+
+A presentational radio button component. You will typically use this component within a RadioGroup component.
+
+## Properties
+
+### Label
+
+A label is required for all radio buttons. They should be as short as possible. If a label is not visible ensure the proper aria labels are set.
+
+## Behavior
+
+### Label Wrapping
+
+Labels will wrap if they are wider than the parent container. The radio button remains aligned to the top of the text box.
+
+### Radio groups
+
+Radio buttons cannot be standalone. They should always be contained within a set of at least two items. The group title is required to clarify how the options are related and what decision is being made.
+
+## Best Practices
+
+### Logical defaults
+
+Whenever possible, a radio button group should have a logical default set.
+
+### Single Selection
+
+**Do**
+
+<p>
+  Radio buttons should only be used when a single element can be selected.
+</p>
+
+**Don't**
+
+<p>
+  Don’t use radio buttons when multiple options can be applied simultaneously.
+</p>

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

@@ -0,0 +1,8 @@
+# Core/Radio - Usage
+
+A presentational radio button component. You will typically use this component within a RadioGroup component.
+
+| Prop | Type | Required | Default | Description |
+| --- | --- | --- | --- | --- |
+| `value` | `string \| null` | Yes | `--` | The value of the radio 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-radiogroup--design.md

@@ -0,0 +1,5 @@
+# Core/RadioGroup - Design
+
+A control wrapper for a group of radio buttons.
+
+No content available yet. Check back soon!

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

@@ -0,0 +1,12 @@
+# Core/RadioGroup - Usage
+
+A control wrapper for a group of radio buttons.
+
+| Prop | Type | Required | Default | Description |
+| --- | --- | --- | --- | --- |
+| `name` | `string` | No | `--` | The name of the radio group, this will act as a default name if one is not provided to the child radio components. |
+| `required` | `boolean` | No | `--` | Whether the radios in the group are required |
+| `disabled` | `boolean` | No | `--` | Whether the radios in the group are disabled |
+| `value` | `string \| null` | No | `--` | The current value of the radio group |
+| `layout` | `'vertical' \| 'horizontal'` | No | 'horizontal' | Whether the radio buttons should be displayed vertically or horizontally<br>@default 'horizontal' |
+| `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-radiotile--design.md

@@ -0,0 +1,5 @@
+# Core/RadioTile - Design
+
+A card variation of a radio button component. You will typically use this component within a RadioGroup component.
+
+No content available yet. Check back soon!

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

@@ -0,0 +1,10 @@
+# Core/RadioTile - Usage
+
+A card variation of a radio button component. You will typically use this component within a RadioGroup component.
+
+| Prop | Type | Required | Default | Description |
+| --- | --- | --- | --- | --- |
+| `description` | `React.ReactNode` | No | `--` | Optional description text displayed below the main label in the tile. |
+| `children` | `React.ReactNode` | Yes | `--` | The main label for the tile. |
+| `icon` | `React.ReactNode` | No | `--` | Optional icon to display in the tile. |
+| `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-ribbon--design.md

@@ -0,0 +1,39 @@
+# Core/Ribbon - Design
+
+A ribbon component used to highlight new features that exist in a 'preview' state. Ribbons communicate that users may encounter errors when using these features.
+
+## Properties
+
+### Color
+
+Ribbons use the 'decorative' palette by default. Use the `color` prop for preset colors (teal, green, purple). For the rare case where you need to use a custom color, use `FORCE__className` with a class that sets the `--_ribbon-background-color` CSS variable.
+
+### Label
+
+Labels highlight features of the UI.
+
+## Content
+
+### Label
+
+Use a simple short sentence, fewer than 5 words, in sentence case.
+
+## Best Practices
+
+### Preview features
+
+Use ribbons to highlight new features that are in a 'preview' state. These features may not be fully completed and users may encounter unexpected errors.
+
+## Accessibility
+
+### Keyboard interaction
+
+A ribbon is a static element, associated with other user interface controls (e.g. a card). It is not keyboard focusable by itself.
+
+### Labeling
+
+A ribbon adds context which must be announced in addition to the parent component's label. For example, "\[parent identifier], \[ribbon string]".
+
+### Color contrast
+
+When using custom colors via `FORCE__className` (e.g. setting `--_ribbon-background-color`), ensure the background color meets WCAG 2.2 Level AA contrast requirements (4.5:1 ratio) against the white foreground text.

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

@@ -0,0 +1,12 @@
+# Core/Ribbon - Usage
+
+A ribbon component used to highlight new features that exist in a 'preview' state. Ribbons communicate that users may encounter errors when using these features.
+
+| 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. |
+| `children` | `string` | Yes | `--` | The label text to display. |
+| `color` | `(typeof ribbonColors)[number]` | No | 'teal' | The color of the ribbon. One of the predefined colors (teal, green, purple).<br>For custom colors, use FORCE__className with CSS that sets --_ribbon-background-color.<br>@default 'teal' |
+| `leadingIcon` | `SvgIcon` | No | `--` | Icon to display before the ribbon text. |
+| `position` | `(typeof ribbonPositions)[number]` | No | 'right' | The position of the ribbon tail (left or right).<br>@default 'right' |
+| `trailingIcon` | `SvgIcon` | No | `--` | Icon to display after the ribbon text. |