@capra/core 1.5.3 → 1.6.0

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

@@ -0,0 +1,16 @@
+# Core/Breadcrumbs - Usage
+
+Renders a breadcrumb trail with built-in support for collection behavior, keyboard support, and current-page semantics. Wrap items with {@link Breadcrumb}. The last item should represent the current page (typically without an `href`).
+
+:::warning[Partially implemented]
+
+The `Breadcrumbs` component is partially implemented and does not yet support dropdowns as items.
+
+:::
+
+| 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. |
+| `aria-label` | `string` | No | 'Breadcrumb' | Accessible name for the breadcrumb navigation landmark.<br>Defaults to `"Breadcrumb"`. |
+| `size` | `string` | No | 'md' | `--` |
+| `shouldEmpasizeCurrent` | `boolean` | No | true | `--` |

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

@@ -0,0 +1,97 @@
+# Core/Button - Design
+
+Primary interactive element displaying text and supporting leading and trailing icons.
+
+## Usage
+
+Use a Button when someone needs to submit a form, confirm an action, or move a workflow forward, and the action warrants a dedicated, labeled control.
+
+Use at most one primary (`variant="primary"`) button per view or modal for the main outcome. Pair it with a secondary (`variant="secondary"`) button for cancel or alternate paths. Use `appearance="danger"` with primary or secondary for destructive or irreversible actions.
+
+## Properties
+
+### Variant
+
+| Variant     | Usage                                                                 |
+| ----------- | --------------------------------------------------------------------- |
+| `primary`   | Highest visual weight. Use once per view for the main action.         |
+| `secondary` | Pairs with a primary button for cancel or alternative paths.          |
+| `tertiary`  | Lowest visual weight. Use for supplementary or de-emphasized actions. |
+
+### Label
+
+Labels should use a verb + noun structure to describe what the button will do when pressed.
+
+### Icon
+
+Buttons have two icon slots; a leading and a trailing icon. Use the leading icons to visually reinforce their meaning and draw attention.
+
+Trailing icons are used for disclosure and additional behavior indications.
+
+### Size
+
+Buttons come is three different sizes. Medium is the default and preferred size for most situations.
+
+Small size is used when a button is inline with another element, such as a table or popover.
+
+### Appearance
+
+| Appearance | Default | Usage                                                       |
+| ---------- | ------- | ----------------------------------------------------------- |
+| `default`  | ✓       | Standard interactive actions.                               |
+| `neutral`  |         | Lower-prominence secondary actions within a filled surface. |
+| `danger`   |         | Destructive or irreversible actions (delete, revoke).       |
+
+### Size
+
+| Size | Default | Usage                                               |
+| ---- | ------- | --------------------------------------------------- |
+| `sm` |         | Compact toolbars, table row actions, dense layouts. |
+| `md` | ✓       | Standard form actions, modal footers.               |
+| `lg` |         | Call-to-action in empty states, hero sections.      |
+| `xl` |         | Marketing or onboarding hero sections.              |
+
+## Content
+
+* Use verb-first labels: "Save changes", "Add item", "Delete record".
+* Title case for all button labels.
+* Keep labels to 1-3 words when possible. Never exceed 5 words.
+* Use "Add" not "New" (e.g., "Add source", not "New source").
+* Avoid vague labels like "OK" or "Submit" — be specific about the action.
+
+## Behavior
+
+* Activated with mouse click, Enter key, or Space key.
+* Pending state (`pending` prop): replaces the leading icon or prepends a spinner while an async action is in progress; preserve button width to avoid layout shift.
+* Disabled state: buttons with `disabled` prop are non-interactive and non-focusable; use `aria-disabled` if the button should remain focusable (e.g., with a tooltip explaining why it's disabled).
+
+## Best Practices
+
+Do:
+
+* Do use a single `variant="primary"` button per view.
+* Do pair primary with secondary for confirm/cancel patterns.
+* Do use `appearance="danger"` for destructive actions.
+* Do use verb-first, title-case labels.
+
+Don't:
+
+* Don't use a Button for navigation to another page — use [Link](?path=/docs/core-link--design) or [Anchor](?path=/docs/core-anchor--design).
+* Don't use a Button for text-only inline navigation — use [Link](?path=/docs/core-link--design).
+* Don't use a Button for icon-only actions — use [IconButton](?path=/docs/core-iconbutton--design).
+* Don't use two primary buttons side by side.
+* Don't truncate button labels.
+* Don't disable a button without explaining why (use `aria-disabled` with a tooltip).
+
+## Accessibility
+
+* Always provide a visible text label; if the design requires a short label, add `aria-label` for context.
+* For icon-only use cases, use [IconButton](?path=/docs/core-iconbutton--design) instead (which enforces an accessible label).
+* Tab / Shift+Tab to focus. Enter or Space to activate.
+* The pending state must be communicated to assistive technology (e.g., `aria-label="Saving..."` when `pending` is true).
+
+## Related components
+
+* [IconButton](?path=/docs/core-iconbutton--design) — For icon-only actions.
+* [Link](?path=/docs/core-link--design) — For inline text navigation.
+* [Modal](?path=/docs/core-modal--design) — Buttons typically appear in modal footers for confirm/cancel patterns.

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

@@ -0,0 +1,17 @@
+# Core/Button - Usage
+
+Primary interactive element displaying text and supporting leading and trailing icons.
+
+| Prop | Type | Required | Default | Description |
+| --- | --- | --- | --- | --- |
+| `children` | `string` | Yes | `--` | The `label` for 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. |
+| `leadingIcon` | `SvgIcon` | No | `--` | Icon to display before the button text. |
+| `trailingIcon` | `SvgIcon` | No | `--` | Icon to display after the button text. |
+| `block` | `boolean` | No | `--` | Whether to display the button as a block-level (full-width) component. Defaults to `false`. |
+| `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-buttonlink--design.md

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

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

@@ -0,0 +1,24 @@
+# Core/ButtonLink - Usage
+
+Primary interactive element displaying text and supporting leading and trailing icons.
+
+| Prop | Type | Required | Default | Description |
+| --- | --- | --- | --- | --- |
+| `children` | `string` | Yes | `--` | The `label` for the link. |
+| `variant` | `(typeof variants)[number]` | No | 'secondary' | Which visual style to use. Defaults to `secondary`. |
+| `appearance` | `(typeof appearances)[number]` | No | 'default' | Appearance to apply to the link. Defaults to `default`. |
+| `size` | `(typeof sizes)[number]` | No | 'md' | Size of the link. Defaults to `md`. |
+| `disabled` | `boolean` | No | false | Whether the link is disabled. |
+| `pending` | `boolean` | No | false | Whether the link is in a pending state. |
+| `leadingIcon` | `SvgIcon` | No | `--` | Icon to display before the link text. |
+| `trailingIcon` | `SvgIcon` | No | `--` | Icon to display after the link text. |
+| `block` | `boolean` | No | `--` | Whether to display the link as a block-level (full-width) component. Defaults to `false`. |
+| `as` | `As` | No | `--` | The underlying element rendered by the component. Defaults to `a`. |
+| `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-card--design.md

@@ -0,0 +1,100 @@
+# Core/Card - Design
+
+The base component for the card.
+
+## Usage
+
+Use a Card to group related content—title, optional description, body, actions, and footer—into one scannable unit, often in grids or lists of similar items.
+
+Treat the card as a container: put links and buttons inside slots rather than making the whole surface ambiguous.
+
+## Properties
+
+### Title
+
+<p>
+  All cards must have a title identifying their content purpose. Use sentence case.
+</p>
+
+<p>
+  Card titles are wrapped by an `h2` by default, but can change based on their hierarchy within the page. Be sure to
+  note the heading level in your design file. The header's visual presentation remains the same regardless of
+  heading level.
+</p>
+
+### Description
+
+<p>
+  Optional. The description gives additional context to the contexts of the card. Descriptions should be brief,
+  taking up no more than a single line.
+</p>
+
+### Actions
+
+<p>
+  Contextual actions act on the main content area but keep the user's workflow within the card. Common examples
+  would be controls that act upon data visualizations, such as a View Switcher and range selections.
+</p>
+
+<p>
+  Supporting, non-interactive, data can also be displayed in this space.
+</p>
+
+### Content
+
+<p>
+  The primary content of the card. This is generally "one thing", though that could be a complex element such as a
+  graph or form.
+</p>
+
+### Footer
+
+<p>
+  Place actions or supplementary information to the primary content in the card's footer.
+</p>
+
+<p>
+  Actions placed here (e.g., a submit button for a form) take the user's workflow out of the card. There should be
+  an explicit indication of completion within the context of the card when the action is taken.
+</p>
+
+## Layout and spacing
+
+* Padding: `spacing.xl` on all sides (standard), `spacing.lg` for compact cards.
+* Title and description: `spacing.sm` gap between them.
+* Title/description block and content: `spacing.lg` gap.
+* Border: `shape.border.default`, `shape.radius.xl`.
+* Background: `color.background.panel.solid`.
+
+## Behavior
+
+* Cards are static containers by default.
+* If the entire card is interactive (e.g., a selectable card), use `role="button"` with keyboard support. Prefer [RadioTile](?path=/docs/core-radiotile--design) for selection scenarios.
+
+## Content
+
+* Title: sentence case, noun phrase.
+* Description: optional; one short line, sentence case with punctuation if needed.
+* Action labels: verb-first, title case.
+
+## Best Practices
+
+Do:
+
+* Do include a title in every card.
+* Do use the footer slot for secondary metadata (timestamps, status).
+
+Don't:
+
+* Don't make the entire card surface the only navigation affordance — put a [Link](?path=/docs/core-link--design) or [Button](?path=/docs/core-button--design) inside the content.
+* Don't use Card for tabular data — use a table.
+
+## Accessibility
+
+* Card titles are typically wrapped at an `h2` by default; choose the heading level (`h2`–`h6`) to match the page outline. Note the intended level in design specs—the visual style stays the same across levels.
+* If the card is a landmark region, wrap with `<section aria-labelledby>`.
+
+## Related components
+
+* [RadioTile](?path=/docs/core-radiotile--design) — For selectable card options.
+* [Modal](?path=/docs/core-modal--design) — For focused overlay containers.

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

@@ -0,0 +1,5 @@
+# Core/Card - Usage
+
+The base component for the card.
+
+## Card

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

@@ -0,0 +1,66 @@
+# Core/Checkbox - Design
+
+Checkbox component for capturing boolean user input. Supports controlled and uncontrolled modes with proper accessibility.
+
+## Usage
+
+Use a Checkbox when people can turn several options on or off independently within a group, and those choices apply when the form is submitted (or in another explicit save step).
+
+Use a visible group heading and stack options so each label stays associated with its control. Use `indeterminate` on a parent checkbox when a tree or grouped list is partially selected.
+
+## Properties
+
+### Label
+
+A label is required for all checkboxes. They should be short and represent a value or yes/no decision. Ensure
+`aria-label` or `aria-labelledby` is used if the checkbox label is not immediately associated with the control.
+
+### Checked
+
+A checkbox can be unchecked, checked, or in an indeterminate state
+
+### Disabled
+
+A checkbox can be disabled in any state if there is a prerequisite to enable the selection.
+
+## Content
+
+* Sentence case labels.
+* Describe the option, not the action (e.g., "Send email notifications", not "Enable email").
+
+## Behaviour
+
+### Single choice
+
+A single discrete checkbox can be used for yes/no decisions within a form.
+
+### Overflow
+
+Labels will wrap if they are wider than the parent container. The checkbox remains aligned to the top of the text
+box.
+
+## Best Practices
+
+Do:
+
+* Do use checkboxes for multi-select form options.
+* Do use `indeterminate` for parent checkboxes in tree structures.
+* Do provide a group heading for checkbox groups.
+
+Don't:
+
+* Don't use Checkbox for settings that apply immediately without submit — use Switch.
+* Don't use Checkbox for mutually exclusive options — use RadioGroup.
+* Don't use a lone Checkbox as a single on/off setting that applies immediately — use Switch.
+
+## Accessibility
+
+* `role="checkbox"`, `aria-checked` (including "mixed" for indeterminate).
+* Associate label using `<label for>` or wrapping `<label>`.
+* Checkbox group must have a group heading using `role="group"` with `aria-labelledby`.
+* Keyboard: Tab / Shift+Tab moves focus; Space or Enter toggles state when the checkbox is focused.
+
+## Related components
+
+* [Switch](?path=/docs/core-switch--design) — For immediate binary settings.
+* [RadioGroup](?path=/docs/core-radiogroup--design) — For mutually exclusive selections.

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

@@ -0,0 +1,34 @@
+# Core/Checkbox - Usage
+
+Checkbox component for capturing boolean user input. Supports controlled and uncontrolled modes with proper accessibility.
+
+| Prop | Type | Required | Default | Description |
+| --- | --- | --- | --- | --- |
+| `indeterminate` | `boolean` | No | `--` | Whether the checkbox is in an indeterminate state. |
+| `checked` | `boolean` | No | `--` | Controlled checked state. Use with onChange for controlled component. |
+| `defaultChecked` | `boolean` | No | `--` | Default checked state for uncontrolled component. |
+| `children` | `string \| React.ReactNode` | No | `--` | The label for the checkbox. |
+| `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. |
+
+## Integration Notes
+
+### Ant Design Form Compatibility
+
+When using Checkbox inside an Ant Design `<Form>` component, the focus ring may appear incorrectly due to Ant Design's global CSS:
+
+```css
+.ant-form input[type='checkbox']:focus {
+  outline-offset: -2px;
+}
+```
+
+Capra's Checkbox includes `!important` on its focus styles to override this, but if you encounter issues, add a local override where you're using this component:
+
+```css
+.checkbox {
+  input[type='checkbox']:focus,
+  input[type='checkbox']:focus-visible {
+    outline-offset: 2px !important;
+  }
+}
+```

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

@@ -0,0 +1,28 @@
+# Core/Collapse - Design
+
+A collapsible disclosure section with an expandable header and panel. Pass **`title`** for the header label, optional **`headerTrailingContentSlot`** for trailing actions (switches, buttons), and the panel body via **`children`**.
+
+## 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 action pattern that already has a dedicated component.
+
+## Best Practices
+
+* Do use Collapse to support hierarchy, grouping, and readable scanning.
+* Don't turn Collapse into an action container when a dedicated interactive pattern exists.
+
+## Accessibility
+
+### Keyboard interaction
+
+| Key                | Function                                                                                                                                                                                         |
+| ------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
+| `Tab`, `Shift-Tab` | When contents are collapsed, focus moves to the next or previous collapse header. When contents are expanded, focus moves to the next or previous focusable element within the expanded content. |
+| `Enter`, `Space`   | When focus is on the accordion header, toggles the expanded/collapsed state.                                                                                                                     |
+
+* When receiving focus through the keyboard, the focus outline appears around the title of the collapse header.
+
+## Related components
+
+* [Card](?path=/docs/core-card--design)
+* [Divider](?path=/docs/core-divider--design)

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

@@ -0,0 +1,20 @@
+# Core/Collapse - Usage
+
+A collapsible disclosure section with an expandable header and panel. Pass **`title`** for the header label, optional **`headerTrailingContentSlot`** for trailing actions (switches, buttons), and the panel body via **`children`**.
+
+| 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. |
+| `title` | `string` | Yes | `--` | Plain string title rendered in the disclosure heading. |
+| `headerTrailingContentSlot` | `React.ReactNode` | No | `--` | Trailing header region for actions (switches, buttons, etc.). |
+| `children` | `React.ReactNode` | Yes | `--` | Content of the disclosure panel. |
+
+### `Collapse` root API
+
+Pass **`title`** (plain string) for the header label, optional **`headerTrailingContentSlot`** for trailing actions
+(switches, buttons), and the panel body via **`children`**.
+
+The root forwards these `Disclosure` props from `react-aria-components`:
+**`id`** (use when a parent **`DisclosureGroup`** controls expansion),
+**`defaultExpanded`**, **`isExpanded`**, **`onExpandedChange`**, and **`isDisabled`**. Use **`FORCE__className`** on the
+root as the style escape hatch.

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

@@ -0,0 +1,71 @@
+# Core/DatePickerField - Design
+
+## Anatomy
+
+The date picker combines a segmented date input with a calendar in a popover. Values use types from
+[`@internationalized/date`](https://react-spectrum.adobe.com/internationalized/date/) (for example `CalendarDate`).
+The visible format follows the user’s locale.
+
+## Properties
+
+### Label
+
+Provide a visible `label` so the control has a clear accessible name. If another element acts as the label, wire the
+relationship with `aria-labelledby` or `aria-label` instead.
+
+### Value
+
+Use `value` with `onChange` for a controlled value, or `defaultValue` for an uncontrolled initial value. The handler
+receives `null` when the field is cleared.
+
+### Placeholder
+
+`placeholder` shows a single string when the field is empty and not focused. Prefer `helperText` for requirements or
+instructions that must stay visible.
+
+### Helper text
+
+Helper text sits below the field for requirements, hints, or errors. Pair `appearance="danger"` with error copy so
+the invalid state is clear visually and to assistive technologies.
+
+### Layout
+
+`layout` can be **vertical** (label above) or **horizontal** (label on the leading side). Prefer vertical; use
+horizontal when horizontal space is tight.
+
+## Feedback
+
+### Appearance
+
+`appearance` supports **default**, **danger** (invalid / error), and **warning**. Danger also drives the invalid
+state for accessibility in addition to any explicit `isInvalid` flag.
+
+### Disabled
+
+Disabled fields cannot be edited and do not receive focus. Values are not submitted with native form submission.
+
+### Read-only
+
+Read-only fields cannot be edited; the value stays visible for reading and assistive technologies.
+
+## Accessibility
+
+### Keyboard and pointer behavior
+
+* **Tab** moves focus into the segmented field or calendar trigger; **Shift+Tab** moves out.
+* Arrow keys adjust focused segments; calendar grid follows standard date grid keyboard patterns when the popover is open.
+* **Space** / **Enter** on the calendar button opens the popover where supported by the platform pattern.
+
+### Labeling and instructions
+
+Provide a visible `label` or an accessible name via `aria-label` / `aria-labelledby`. Do not rely on `placeholder` alone
+for the accessible name. Prefer persistent `helperText` for requirements; placeholder disappears when the user types.
+
+### Validation and state
+
+Use `appearance="danger"` with error content in `helperText` for a consistent error treatment. Set `required` when the
+field is mandatory. Disabled fields are not interactive and are excluded from native submission; read-only fields keep
+their values visible but are not editable.
+
+Ensure focus indicators remain visible (at least 2px, 3:1 contrast) and interactive targets meet at least 24×24 CSS
+pixels where applicable.

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

@@ -0,0 +1,57 @@
+# Core/DatePickerField - 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. |
+| `granularity` | `'day' \| 'second'` | No | `--` | Smallest date/time unit shown in the field. 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 input (same pattern as `TextInput`).                             |
+| `placeholder`      | `string`                             | String placeholder when empty and 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, and change events
+
+| Prop           | Type                                          | Description                                                                              |
+| -------------- | --------------------------------------------- | ---------------------------------------------------------------------------------------- |
+| `value`        | `T \| null`                                   | Controlled value (`T` is a `DateValue` generic, defaulting to the library `DateValue`).  |
+| `defaultValue` | `T \| null`                                   | Initial value when uncontrolled.                                                         |
+| `onChange`     | `(value: MappedDateValue<T> \| null) => void` | Fired when the committed value changes.                                                  |
+| `granularity`  | `'day' \| 'hour' \| 'minute' \| 'second'`     | Smallest unit shown in the field (default follows value type, e.g. day for plain dates). |
+
+`MappedDateValue<T>` preserves time and calendar types aligned with `T` (for example `CalendarDate` vs `CalendarDateTime`).
+
+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, input, 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-daterangepickerfield--design.md

@@ -0,0 +1,76 @@
+# Core/DateRangePickerField - Design
+
+## Anatomy
+
+The date range picker combines two segmented date inputs (start and end) with a range calendar in a popover. Values use
+[`RangeValue`](https://react-spectrum.adobe.com/react-aria/DateRangePicker.html) over types from
+[`@internationalized/date`](https://react-spectrum.adobe.com/internationalized/date/) (for example `CalendarDate`). The
+visible format follows the user’s locale.
+
+## Properties
+
+### Label
+
+Provide a visible `label` so the control has a clear accessible name. If another element acts as the label, wire the
+relationship with `aria-labelledby` or `aria-label` instead.
+
+### Value
+
+Use `value` with `onChange` for a controlled range, or `defaultValue` for an uncontrolled initial range. The handler
+receives `null` when the field is cleared. Each bound is a `DateValue` consistent with your generic (for example
+both `CalendarDate`).
+
+### Placeholder
+
+`placeholder` is a pair of strings (`[start, end]`) shown when neither bound is set and the inputs are not
+focus-within, with a swap icon between them. Prefer `helperText` for requirements or instructions that must stay
+visible.
+
+### Helper text
+
+Helper text sits below the field for requirements, hints, or errors. Pair `appearance="danger"` with error copy so
+the invalid state is clear visually and to assistive technologies.
+
+### Layout
+
+`layout` can be **vertical** (label above) or **horizontal** (label on the leading side). Prefer vertical; use
+horizontal when horizontal space is tight.
+
+## Feedback
+
+### Appearance
+
+`appearance` supports **default**, **danger** (invalid / error), and **warning**. Danger also drives the invalid
+state for accessibility in addition to any explicit `isInvalid` flag.
+
+### Disabled
+
+Disabled fields cannot be edited and do not receive focus. Values are not submitted with native form submission.
+
+### Read-only
+
+Read-only fields cannot be edited; the range stays visible for reading and assistive technologies.
+
+## Accessibility
+
+### Keyboard and pointer behavior
+
+* **Tab** moves focus into the segmented fields or calendar trigger; **Shift+Tab** moves out.
+* Arrow keys adjust focused segments; the range calendar grid follows standard date grid and range selection patterns when
+  the popover is open.
+* **Space** / **Enter** on the calendar button opens the popover where supported by the platform pattern.
+
+### Labeling and instructions
+
+Provide a visible `label` or an accessible name via `aria-label` / `aria-labelledby`. Do not rely on `placeholder` alone
+for the accessible name. Prefer persistent `helperText` for requirements; the string placeholder hides when the user
+focuses or enters either bound.
+
+### Validation and state
+
+Use `appearance="danger"` with error content in `helperText` for a consistent error treatment. Set `required` when both
+bounds are mandatory. Disabled fields are not interactive and are excluded from native submission; read-only fields keep
+their values visible but are not editable.
+
+Ensure focus indicators remain visible (at least 2px, 3:1 contrast) and interactive targets meet at least 24×24 CSS
+pixels where applicable.