@capra/core 1.5.3 → 1.6.0

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

@@ -0,0 +1,62 @@
+# Core/DateRangePickerField - Usage
+
+| Prop | Type | Required | Default | Description |
+| --- | --- | --- | --- | --- |
+| `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. |
+| `placeholder` | `unknown` | No | `--` | Placeholders for empty start and end, shown with a swap icon between them when the group is not focus-within. |
+| `granularity` | `'day' \| 'second'` | No | `--` | Smallest date/time unit shown in the fields. Only `day` and `second` are supported. |
+| `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. |
+| `canClear` | `boolean` | No | `--` | When true, shows a clear control to the left of the calendar button while the field has a value. |
+| `disabled` | `boolean` | No | `--` | Disables the field. |
+| `id` | `string` | No | `--` | Optional id for the root; associates the label and field. |
+| `readOnly` | `boolean` | No | `--` | Read-only field. |
+| `required` | `boolean` | No | `--` | Required field. |
+| `isInvalid` | `boolean` | No | `--` | Invalid value; `appearance="danger"` also forces an invalid state for display. |
+
+## Props reference
+
+### Field layout and presentation
+
+| Prop               | Type                                 | Description                                                                                            |
+| ------------------ | ------------------------------------ | ------------------------------------------------------------------------------------------------------ |
+| `label`            | `string`                             | Visible label text; pair with `required` or assistive naming when the visible label is not sufficient. |
+| `helperText`       | `string`                             | Descriptive or error text below the field (rendered in the description slot).                          |
+| `layout`           | `'vertical' \| 'horizontal'`         | Label placement relative to the control.                                                               |
+| `appearance`       | `'default' \| 'danger' \| 'warning'` | Visual status; `danger` also marks the field invalid for accessibility.                                |
+| `size`             | `'sm' \| 'md'`                       | Height and density of the input shell.                                                                 |
+| `leadingSlot`      | `ReactNode`                          | Optional content before the segmented inputs (same pattern as `TextInput`).                            |
+| `placeholder`      | `readonly [string, string]`          | Start and end placeholders when both bounds are empty and the group is not focus-within.               |
+| `id`               | `string`                             | Optional id for the root; associates the label and field.                                              |
+| `FORCE__className` | `string`                             | Escape hatch: extra class on the field shell; see `StylingOverrideProps` in source.                    |
+| `disabled`         | `boolean`                            | Disables the control.                                                                                  |
+| `readOnly`         | `boolean`                            | Read-only mode.                                                                                        |
+| `required`         | `boolean`                            | Marks the field required for forms and assistive technologies.                                         |
+| `isInvalid`        | `boolean`                            | Marks the value invalid; combined with `appearance === 'danger'`.                                      |
+
+### Value, format, overlay, and change events
+
+| Prop                  | Type                                                      | Description                                                                               |
+| --------------------- | --------------------------------------------------------- | ----------------------------------------------------------------------------------------- |
+| `value`               | `RangeValue<T> \| null`                                   | Controlled range (`T` is a `DateValue` generic, defaulting to the library `DateValue`).   |
+| `defaultValue`        | `RangeValue<T> \| null`                                   | Initial range when uncontrolled.                                                          |
+| `onChange`            | `(value: RangeValue<MappedDateValue<T>> \| null) => void` | Fired when the committed range changes.                                                   |
+| `granularity`         | `'day' \| 'hour' \| 'minute' \| 'second'`                 | Smallest unit shown in the fields (default follows value type, e.g. day for plain dates). |
+| `shouldCloseOnSelect` | `boolean \| () => boolean`                                | Whether the popover closes after a calendar interaction.                                  |
+
+`MappedDateValue<T>` preserves time and calendar types aligned with `T` (for example `CalendarDate` vs `CalendarDateTime`).
+
+For selecting a new range entirely inside the calendar without the overlay closing between the first and second date,
+set `shouldCloseOnSelect={false}` (as in the example stories).
+
+Use `isInvalid` and `helperText` for invalid feedback in Capra layouts. Validation behavior is fixed to ARIA-associated messaging for this shell (not configurable).
+
+### Props not supported or intentionally fixed
+
+| Prop                                           | Notes                                                                                        |
+| ---------------------------------------------- | -------------------------------------------------------------------------------------------- |
+| `children`                                     | Ignored; structure (label, inputs, calendar) is fixed.                                       |
+| `style`                                        | Not part of the public styling contract; use design tokens and `FORCE__className` if needed. |
+| `validationBehavior`                           | Not configurable; the implementation always uses ARIA-associated validation for this shell.  |
+| `description`, `errorMessage` (slot-style API) | Not part of the public props surface; use `helperText` and validation props instead.         |

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

@@ -0,0 +1,35 @@
+# Core/Divider - Design
+
+Divider separates and groups content. Use horizontal dividers between sections; use vertical dividers between inline items. A horizontal divider can optionally display a label. Dividers are static and not keyboard focusable.
+
+## Usage
+
+Use Collapse to structure readable content, separate regions, or group related information. Pair it with shared spacing, typography, and surface rules. Do not stretch it into an interaction pattern that already has a dedicated component.
+
+## Properties
+
+### Label
+
+A horizontal divider can be given a label to provide context to a grouping. When possible, avoid labeled dividers and use headings instead. When you do use a label, ensure it has the proper semantic level (e.g. pass an `<h2>` or `<h3>` as children) so it is announced as a heading by assistive technologies.
+
+## Best Practices
+
+Do:
+
+* Do use Divider to separate semantically distinct groups.
+* Do use a label when the divider introduces a new conceptual group.
+
+Don't:
+
+* Don't use Divider between every list item in a dense list.
+* Don't use Divider as pure decoration.
+
+## Accessibility
+
+* Dividers are static and not keyboard focusable.
+* Unlabeled horizontal dividers render as an `<hr>` (a thematic break between content).
+* When a horizontal divider has a label, prefer a real heading element as children (for example, `Text` with `as="h2"` or `as="h3"`) when the label introduces a new section, so the label is announced with the correct level. When possible, avoid labeled dividers and use headings instead.
+
+## Related components
+
+* [Collapse](?path=/docs/core-collapse--design)

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

@@ -0,0 +1,8 @@
+# Core/Divider - Usage
+
+Divider separates and groups content. Use horizontal dividers between sections; use vertical dividers between inline items. A horizontal divider can optionally display a label. Dividers are static and not keyboard focusable.
+
+| 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. |
+| `type` | `string` | No | 'horizontal' | `--` |

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

@@ -0,0 +1,87 @@
+# Core/Drawer - Design
+
+## Behavior
+
+### Modality
+
+A contextual sheet can be **modal** or **non-modal**.
+
+**Modal** sheets use a scrim to block interaction with the main page.
+
+**Non-modal** sheets allow simultaneous interaction with the sheet and main page surfaces.
+Non-modal sheets are best used for experiences that require a persistent but dismissible sheet that benefits from
+interacting with the main page, like viewing location details on a map.
+
+### Navigation
+
+Navigating within a context sheet should be avoided where possible. If navigating is necessary, keep it shallow –
+no more than 1 level deep.
+
+When presenting a secondary view in a context sheet, the primary view content is replaced. The secondary view is
+dismissed by making a selection or pressing a backward navigation button.
+
+### Dismissing
+
+Context sheets are dismissed by:
+
+1. Pressing the close button
+2. Confirming or cancelling the drawer
+3. Interacting with the scrim (when present)
+4. Pressing the escape key when the general sheet container is focused
+
+In code, wire footer actions and other dismiss paths to `onClose`. A scrim is shown when the drawer
+is **modal** (`modal`).
+
+## Screen size
+
+### Small screens
+
+On small screens, the vertical height of a context sheet defaults up to 50% of the screen height. Scrolling the
+sheet first slides it to full height before the content area scrolls.
+
+### Medium and large screens
+
+On larger screens, drawers are fixed to the **trailing** edge of the screen. Content that extends beyond the
+vertical bounds of the drawer scrolls. Do not scroll horizontally. The drawer header and footer are pinned above the
+scrolled content. Drawers have a min-width of 400px and max-width of 80% of the parent viewport.
+
+## Best practices
+
+### Stacking
+
+**Do**
+
+Keep interactions within context sheets on the sheet surface. Use inline progressive disclosure to reveal
+additional or optional content.
+
+**Don't**
+
+Launch other context sheets over a context sheet.
+
+### In-sheet navigation
+
+**Do**
+
+Keep navigation to a minimum within context sheets. Keep the navigation stack shallow when necessary, no more than
+1 level.
+
+**Don't**
+
+Add deep or multi-level navigation stacks inside a single context sheet; prefer replacing content or using shallow
+steps instead.
+
+## Accessibility
+
+### Keyboard interaction
+
+| Key                 | Function                                                                                                                                       |
+| ------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------- |
+| `Tab` / `Shift+Tab` | In **modal** mode, focus stays within the drawer while open. In **non-modal** mode, focus can move freely between the sheet and the main page. |
+| `Escape`            | Closes the drawer whether focus is on the dialog surface or inside it (capture-phase listener).                                                |
+
+### Roles and properties
+
+* The panel uses `role="dialog"` with `aria-labelledby` (title) or `aria-label` as needed. While open, `aria-modal` is `true` for modal drawers and `false` for non-modal drawers.
+* **Modal** mode: focus is trapped; `usePreventScroll` locks page scrolling. **Non-modal** mode: no focus containment or scroll lock on the document.
+* The close control exposes an accessible name (“Close drawer”).
+* When you add `Breadcrumbs` in the title, the trail is an ordered list with an `aria-label` of “Breadcrumb” by default; the last crumb should represent the current page (typically without an `href`).

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

@@ -0,0 +1,9 @@
+# Core/Drawer - Usage
+
+### Implementation
+
+The drawer UI is rendered in a **portal** (default `document.body`), with `position: fixed` and `top`/`bottom` anchoring so the sheet fills the **layout viewport** (the browser window on a real site; the Storybook **preview iframe** in docs/canvas). In the **Story** canvas, a decorator stretches the preview document so the iframe can grow with the panel; that shell is **skipped in Docs** so embedded previews are not forced to full-viewport height. The open drawer still fills the iframe, not the inline story box—resize the preview panel if you need a taller canvas.
+
+### Header
+
+The header is the `title` slot: a string for a single heading, or a composition with `Drawer.Heading`, optional `Drawer.Description`, `Drawer.ExpandedTitleLayout`, and the shared `Breadcrumbs` components (matching the `Modal` pattern). The header stays pinned while the body scrolls.

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

@@ -0,0 +1,45 @@
+# Core/EmptyState - Design
+
+The EmptyState component is used to display a message when there is no data to display. Illustrations are lazy-loaded and support light/dark themes via the theme prop.
+
+## Properties
+
+### Title
+
+All empty states have a title. Titles provide a brief summary of the reason an empty state is shown.
+
+### Description
+
+All empty states have a description. Descriptions provide the details and instructions on next steps the user can take.
+
+### Action (optional)
+
+A call to action can be used to provide quick access to relevant next steps. Full page empty states use a primary button. Smaller empty states use a secondary button.
+
+### Illustration
+
+All empty states have an illustration. Pass an illustration slug (e.g. `EmptyFolder`, `PizzaBox`) via the `illustration` prop.
+
+Use the `theme` prop (`light` or `dark`) to switch between light/dark variants when the illustration supports them. Illustrations are lazy-loaded for optimal bundle size.
+
+## Content
+
+### Title / explanation format
+
+This format allows empty states to provide both a catchy main title and a more detailed explanation. The title should provide the broad action with the explanation providing additional detail.
+
+Titles should be in sentence format with no ending punctuation. Descriptions should be in sentence format with ending punctuation.
+
+### Call to action
+
+A call to action enables users to easily move forward from an empty state. It can take the form of a link embedded within the description to send the user to another page, or a button to perform an action.
+
+Full page empty states (`size="lg"`) should use a primary button, as the action is the primary next step for the user. Smaller empty states should use a secondary button if the action is already present elsewhere on the page.
+
+### Description wrapping
+
+Descriptions will wrap if the parent container is small enough, but strings should be kept short when possible.
+
+### Graphs
+
+When using graph tiles, an empty state should be smaller to match the size of the graph tile.

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

@@ -0,0 +1,13 @@
+# Core/EmptyState - Usage
+
+The EmptyState component is used to display a message when there is no data to display. Illustrations are lazy-loaded and support light/dark themes via the theme prop.
+
+| Prop | Type | Required | Default | Description |
+| --- | --- | --- | --- | --- |
+| `illustration` | `(typeof illustrationSlugs)[number]` | No | `--` | The illustration to display, identified by slug. Use theme to switch between light/dark variants when available. @default "EmptyFolder" |
+| `theme` | `'light' \| 'dark'` | No | `--` | The theme for the illustration. Determines which variant to show when light/dark variants exist. @default "light" |
+| `size` | `'md' \| 'lg'` | No | `--` | The size of the empty state. `lg` is for large components or the whole pages. @default "md" |
+| `title` | `string` | Yes | `--` | The title to display in the empty state. |
+| `description` | `string` | No | `--` | The description to display in the empty state. Please do not skip this property without a good reason. |
+| `children` | `React.ReactNode` | No | `--` | Generic use for adding a button or other action elements below the 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. |

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

@@ -0,0 +1,30 @@
+# Core/HelperText - Design
+
+Helper text for inputs.
+
+:::warning
+
+Prefer Capra field components—such as `TextField`, `NumberField`, `PasswordField`, `TextArea`, `DatePicker`, `DateRangePicker`, or `AutocompleteField`—which
+include helper text in the standard field layout. Use standalone `HelperText` only when you are building a
+custom field or a layout that those components do not cover.
+
+:::
+
+## Accessibility
+
+### Error and warning content
+
+For `appearance="danger"`, the helper region uses `role="alert"` so critical validation
+messages are exposed promptly to assistive technologies. Warning and default appearances do not use `alert`;
+ensure critical errors use `danger` when this behavior is desired.
+
+### Live regions
+
+When `countText` is present, it is wrapped with `aria-live="polite"` so changes (for example
+remaining characters) are announced without interrupting the user.
+
+### Relationship to the field
+
+For custom compositions, associate helper copy with the control using `aria-describedby` on the input
+pointing at an `id` on the helper element, or use patterns documented on the field component you wrap.
+Capra built-in fields handle these relationships when you pass their `helperText` props.

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

@@ -0,0 +1,11 @@
+# Core/HelperText - Usage
+
+Helper text for inputs.
+
+| Prop | Type | Required | Default | Description |
+| --- | --- | --- | --- | --- |
+| `appearance` | `(typeof appearances)[number]` | No | `--` | Appearance of the input.<br>@default 'default' |
+| `children` | `string` | No | `--` | Main text. Use for hints, requirements, disclaimers, etc. |
+| `countText` | `string` | No | `--` | Text to display on the right side of the helper text. Is marked as a live content area via `aria-live`. |
+| `disabled` | `boolean` | No | `--` | Whether the input the helper text applies to is disabled. |
+| `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-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. |