@capra/core 1.5.2 → 1.6.0

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

@@ -0,0 +1,110 @@
+# Core/Alert - Design
+
+Alerts are used to communicate important information to the user.
+
+## Usage
+
+Use an Alert to surface contextual feedback in the page: the outcome of an action (success or failure), a condition that needs attention before the user continues, or information that should stay visible while they keep working in the same view.
+
+Keep alerts scoped to the page or region they refer to. Prefer one alert per region so the message stays easy to scan; when several conditions apply at once, combine them into a single alert when it makes sense.
+
+## Properties
+
+### Appearances
+
+### Info
+
+General information like recommend actions to accelerate a user's workflow, helpful information, or tips.
+
+### Error
+
+Problems that must be resolved before the user can complete a task, such as an error on a form.
+
+### Warning
+
+Notify users of cautionary/temporary information affecting the user's workflow, but does not block a user from
+completing the action or workflow.
+
+### Success
+
+Brings special attention to the user that an action has been completed, or a status has been updated.
+
+### Layout
+
+### Section
+
+Section notifications communicate the status of a section to the user.
+
+### Inline
+
+Inline notifications are low-priority messages about a single element, like a tile or row item.
+
+### Additional properties
+
+### Title
+
+A title is recommended, but optional. Use a title to quickly summarize the purpose of the notification. Keep titles
+short, no more than 60 characters, and avoid repeating the body text.
+
+### Body
+
+The body text is required for all notifications. If the notification is actionable, the text should inform the user
+of the next step.
+
+### Action
+
+Actionable notifications are recommended to help the user resolve the issue.
+
+### Dismiss
+
+Alert banners can include a dismiss button that removes the notice from the page layout. Error banners can not be
+dismissed.
+
+## Layout and spacing
+
+* Alerts span the full width of their container.
+
+## Behavior
+
+* Alerts are static by default; they do not auto-dismiss.
+* If the user triggers an action that resolves the alert condition, remove the alert programmatically.
+* When an alert is injected into the DOM, announce it to screen readers via `aria-live`.
+
+## Content
+
+* Title: sentence case, no trailing punctuation, max 60 characters.
+* Body: one to two sentences. State the problem and the resolution path. Use punctuation.
+* Action label: verb-first, 1-3 words (e.g., "Retry", "View details").
+* Avoid technical jargon in user-facing alert text.
+
+## Best Practices
+
+Do:
+
+* Do use `appearance="danger"` for blocking error states.
+* Do provide an action when the user has a clear path to resolution.
+
+Don't:
+
+* Don't use Alert for transient, auto-dismissing notifications — use Toast.
+* Don't use Alert for individual form field validation errors — use the field's error state.
+* Don't use Alert when the message isn't tied to the current page or task context.
+* Don't stack Alerts in the same region.
+* Don't make `appearance="danger"` Alerts dismissable — the component prevents this automatically.
+
+## Accessibility
+
+* Use `role="alert"` for errors and warnings so they are announced immediately by screen readers.
+* Use `role="status"` for informational and success alerts, which are announced at a lower priority.
+* Don't rely solely on color to convey alert type — the icon and/or title must distinguish the appearance.
+* Ensure the dismiss button has an accessible label (e.g., `aria-label="Dismiss alert"`).
+
+### Keyboard interaction
+
+* Alerts exist in the page's natural tab sequence, their actions reachable via `tab` and `shift`+`tab` keys.
+
+## Related components
+
+* [Toast](?path=/docs/core-toast--design) — For non-blocking, auto-dismissing notifications.
+* [Pill](?path=/docs/core-pill--design) — For inline semantic status indicators without body copy.
+* [Modal](?path=/docs/core-modal--design) — When the error or warning requires an immediate blocking decision.

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

@@ -0,0 +1,13 @@
+# Core/Alert - Usage
+
+Alerts are used to communicate important information to the user.
+
+| Prop | Type | Required | Default | Description |
+| --- | --- | --- | --- | --- |
+| `layout` | `(typeof layouts)[number]` | No | 'section' | The layout of the alert.<br><br>@default 'section'<br><br><ul><br>  <li>'section' - The alert is displayed in a full width container.</li><br>  <li>'compact' - @deprecated Use 'section' instead. Will be removed in a future version.</li><br>  <li>'inline' - Inline notifications are low-priority messages about a single element, like a tile or row item.</li><br></ul> |
+| `appearance` | `(typeof appearances)[number]` | No | 'info' | The appearance of the alert.<br><br>@default 'info'<br><br><ul><br>  <li>'info' - Informational alerts provide general information or an important property.</li><br>  <li>'warning' - Warning alerts notify users of cautionary information.</li><br>  <li>'danger' - Danger alerts indicate problems that must be resolved.</li><br>  <li>'success' - Success alerts confirm an action has been completed.</li><br></ul> |
+| `title` | `string` | No | `--` | The title of the alert. This is optional. |
+| `children` | `React.ReactNode` | Yes | `--` | The description of the alert. This is required.<br><br>@required |
+| `action` | `{     label: string;     onClick: (e: React.MouseEvent<HTMLButtonElement>) => void;   } \| React.ReactElement` | No | `--` | The configuration of the action button. The object must contain a label displayed on the button and an onClick callback function. This is optional.<br><br>When the object is not provided, the alert will not render the action button. |
+| `onDismiss` | `true \| (() => void)` | No | `--` | Optional function to call when the user dismisses the alert.<br><br>If this is not provided, the alert will not render the dismiss button.<br><br>Alerts with `appearance="danger"` cannot be dismissed and will not render the dismiss button.<br><br>**Integration note:** while the `Alert` will handle its own dismissal, this is non-persistent.<br>Persistent dismissal should be handled by the parent component. |
+| `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-anchor--design.md

@@ -0,0 +1,39 @@
+# Core/Anchor - Design
+
+## Usage
+
+Anchors are used to navigate users to a different section within the current page.
+
+## Properties
+
+### Label
+
+Labels should be concise and descriptive, m Use title case (e.g., "Dashboard", "Settings"). Labels should ideally be
+less than 12 characters, with a maximum of 32 characters.atching the destination heading.
+
+## Best Practices
+
+Do:
+
+* Do match the label to the section heading the anchor points to.
+* Do use the active state for the current page in a navigation region.
+* Do use the disabled state when navigation is temporarily unavailable.
+
+Don't:
+
+* Don't mark more than one anchor as active in the same navigation context.
+* Don't hide anchors instead of disabling them when a destination exists but is unavailable.
+* Don't use confuse Anchor with Tab.
+
+## Accessibility
+
+### Keyboard interaction
+
+| Key     | Function                                                              |
+| ------- | --------------------------------------------------------------------- |
+| `Tab`   | Moves focus to the anchor when navigating through focusable elements. |
+| `Enter` | Activates the anchor when focused.                                    |
+
+### ARIA attributes
+
+* `aria-current="page"`: Applied when the anchor is active, indicating the current page in navigation.

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

@@ -0,0 +1,39 @@
+# Core/Anchor - Usage
+
+| Prop | Type | Required | Default | Description |
+| --- | --- | --- | --- | --- |
+| `children` | `React.ReactNode` | Yes | `--` | The label text to display in the anchor. Anchor labels should be one or two words, using title case (Tab Label). Labels should be less than 12 characters, with a maximum of 32 characters. |
+| `href` | `string` | No | `--` | The href attribute of the anchor. |
+| `isActive` | `boolean` | No | `--` | Whether the anchor is active. |
+| `isDisabled` | `boolean` | No | `--` | Whether the anchor is disabled. |
+| `as` | `As` | No | `--` | The underlying element rendered by the anchor. Defaults to `a`. |
+| `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. |
+
+## Usage
+
+```tsx
+import { Anchor } from '@cribl/capra-core';
+
+// Basic usage
+<Anchor href="/dashboard">Dashboard</Anchor>
+
+// Active state
+<Anchor href="/settings" isActive>Settings</Anchor>
+
+// Disabled state
+<Anchor href="/admin" isDisabled>Admin</Anchor>
+
+// Polymorphic - render as button
+<Anchor as="button" onClick={handleClick}>Action</Anchor>
+```
+
+## Polymorphic Component
+
+The Anchor component supports the `as` prop, allowing it to be rendered as different HTML elements or custom components. This is particularly useful when integrating with routing libraries like React Router.
+
+```tsx
+import { Link } from 'react-router-dom';
+
+// Using with React Router
+<Anchor as={Link} to="/dashboard">Dashboard</Anchor>
+```

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

@@ -0,0 +1,91 @@
+# Core/AutocompleteField - Design
+
+AutocompleteField combines a text field with a suggestions list. Consumers can supply static `AutocompleteField.Item` children or an `items` collection with an optional default item renderer. The field allows custom values that are not in the list.
+
+## Anatomy
+
+1. **Text input** — Entry is through a standard text input. The field keeps focus while the list is open so typing and keyboard
+   navigation stay in one place.
+2. **ListBox** — Filtered results appear in a ListBox under the field.
+
+## Properties
+
+### Label
+
+A label is required for input fields and succinctly describes the field’s purpose. If another text element is acting
+as the label, like a section title, ensure the proper aria relationships are linked.
+
+### Placeholder text
+
+<p>
+  Placeholder text is visible until a character is entered.
+</p>
+
+<p>
+  Because the placeholder text disappears, putting instructions or requirements as placeholder text is not
+  accessible. Helper text is the preferred method to convey this information.
+</p>
+
+### Helper text
+
+Helper text is placed below the field and informs the user of any requirements, disclaimers, and errors. Helper text
+is shown persistently but is replaced by error text when an error occurs.
+
+### Layout
+
+There are two layouts available for text fields, vertical and horizontal. Vertical labels are the preferred layout,
+appearing above the field. Horizontal labels appear on the leading side of the field, and should only be used when
+space is limited.
+
+## Layout and spacing
+
+* Input renders identically to [TextField](?path=/docs/core-textfield--design).
+* Suggestions are presented using a ListBox.
+
+## Behavior
+
+### Autocomplete vs. Select
+
+<p>
+  **Autocomplete** is an input box with text hints that users can type freely into. Hints are presented and refined
+  ina selection list as the user types. Freeform entry is allowed.
+</p>
+
+<p>
+  **Select**
+
+   allows selecting options only among a given set of choices.
+</p>
+
+### Filtering
+
+As the user types into the text field options are filtered based on the value.
+
+## Best Practices
+
+Do:
+
+* Do show a "no results" message when the filter returns nothing.
+* Do support keyboard-only navigation of suggestions.
+
+Don't:
+
+* Don't use AutocompleteField for small mutually exclusive sets (about seven or fewer visible options) — use [RadioGroup](?path=/docs/core-radiogroup--design) or Select.
+* Don't use AutocompleteField for plain freeform text with no list validation — use [TextField](?path=/docs/core-textfield--design).
+* Don't require picking from the list while still allowing arbitrary text without explaining that behavior.
+
+## Accessibility
+
+* `role="combobox"` on the input, `aria-expanded` reflects list open state.
+* `aria-controls` references the suggestion list `id`.
+* `aria-activedescendant` references the currently focused suggestion.
+* Suggestion list: `role="listbox"`, each suggestion: `role="option"`.
+
+### Keyboard interaction
+
+* Keyboard interactions follow Select and ListBox.
+
+## Related components
+
+* [TextField](?path=/docs/core-textfield--design) — For freeform text without suggestions.
+* [RadioGroup](?path=/docs/core-radiogroup--design) — For small mutually exclusive option sets.

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

@@ -0,0 +1,18 @@
+# Core/AutocompleteField - Usage
+
+AutocompleteField combines a text field with a suggestions list. Consumers can supply static `AutocompleteField.Item` children or an `items` collection with an optional default item renderer. The field allows custom values that are not in the list.
+
+| Prop | Type | Required | Default | Description |
+| --- | --- | --- | --- | --- |
+| `canClear` | `boolean` | No | `--` | Whether to show a clear button for the input. |
+| `children` | `React.ReactNode \| ((     values: T & {       defaultChildren: React.ReactNode \| undefined;     },   ) => React.ReactNode)` | No | `--` | The children to render in the dropdown. |
+| `itemFilter` | `(textValue: string, inputValue: string) => boolean` | No | `--` | A function that filters the items based on the input value. |
+| `onChange` | `(value: string) => void` | No | `--` | A callback function that is called when the input value changes. |
+| `onOpenChange` | `(isOpen: boolean) => void` | No | `--` | A callback function that is called when the dropdown is opened or closed. |
+| `items` | `AutocompleteItem[]` | No | `--` | The items to display in the dropdown. |
+| `value` | `AutocompleteItem['value']` | No | `--` | The value of the input. |
+| `shouldAutoSizeDropdown` | `boolean` | No | `--` | Whether to automatically size the dropdown to the width of the input. Defaults to `true` |
+| `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. |
+| `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-badge--design.md

@@ -0,0 +1,70 @@
+# Core/Badge - Design
+
+Badges display an indicator/counter on an associated component.
+
+## Properties
+
+### Label
+
+A label is required to indicate the number of notifications.
+
+### Size
+
+Badges come in 3 sizes to support ones, tens, and values above 100.
+
+### Dot
+
+Use a dot to show notifications without a count.
+
+### Appearance
+
+Badges can be colored based on their status. The `attention` appearance is the general purpose color used for numbered badges and does not necessarily communicate severity.
+
+Using color as the only means to communicate status should be avoided (WCAG SC 1.4.1: Use of Color, Level A). Badges that communicate status must be accompanied by supplementary information that clearly communicates the status.
+
+## Behavior
+
+### Corner attachment
+
+Badges are placed in the top-right of the parent component to avoid obscuring the parent content.
+
+### Inline
+
+When used with text labels, badges are placed on the trailing side and vertically aligned to the text's line height.
+
+## Content
+
+### Maximum
+
+The maximum number shown in 99. When there are more than 99 notifications a "+" is appended to the label.
+
+## Best Practices
+
+Do:
+
+* Do cap displayed values at 99 with a "99+" label.
+* Do use the dot variant for simple presence indicators.
+* Do include count context in the parent's accessible label.
+
+Don't:
+
+* Don't use Badge for semantic status text — use Pill.
+* Don't use Badge for labels or tags — use Tag.
+* Don't place Badge on non-interactive decorative elements.
+* Don't use Badge colors as the only method to communicate status.
+
+## Accessibility
+
+* The badge is a nested static element; it is announced as part of its parent.
+* The parent element's accessible label should include the count context (e.g., "Notifications, 5 unread").
+* Use `aria-live="polite"` on the parent for dynamic badge updates.
+
+## Content
+
+* Numeric only.
+* Max displayed value: 99; use "99+" for larger counts.
+
+## Related components
+
+* [Pill](?path=/docs/core-pill--design) — For semantic status labels.
+* [Tag](?path=/docs/core-tag--design) — For removable text chips.

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

@@ -0,0 +1,13 @@
+# Core/Badge - Usage
+
+Badges display an indicator/counter on an associated component.
+
+| Prop | Type | Required | Default | Description |
+| --- | --- | --- | --- | --- |
+| `variant` | `'counter' \| 'dot'` | No | `--` | The variant of the badge. 'counter' displays a count, 'dot' displays only a dot.<br>@default 'counter' |
+| `appearance` | `'danger' \| 'info' \| 'success' \| 'warning'` | No | 'danger' | Controls the Badge color.<br>@default 'danger' |
+| `count` | `number` | No | 0 | The number to display in the badge. Default is 0. |
+| `showZero` | `boolean` | No | false | Whether to display the badge when the count is zero. Default is false. |
+| `overflowCount` | `number` | No | 99 | The number to display in the badge when the count is greater than the overflow count. Default is 99. |
+| `FORCE__className` | `string` | No | `--` | 🚨 This prop is meant to be an escape hatch. 🚨<br><br>If the desired style cannot be achieved using component props, use this as a last resort. The inner workings of Capra components are implementation details and this escape hatch gives one access to those implementation details. We cannot make any guarantees that styles will applied correctly across version updates. Please use it responsibly.<br><br>Add a CSS class to the component. |
+| `aria-live` | `React.AriaAttributes['aria-live']` | No | `--` | `--` |

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

@@ -0,0 +1,65 @@
+# Core/Breadcrumbs - Design
+
+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`).
+
+## Usage
+
+Use Breadcrumbs on views that sit deeper than the home or root level so people see where they are in the hierarchy and can jump to ancestors.
+
+Place them above the page title, keep labels aligned with each destination's title, and render every segment except the current page as a link.
+
+## Layout and spacing
+
+* Place above the page heading.
+
+## Behavior
+
+* Current page item is not a link (no click interaction).
+
+## Content
+
+* Use the same label as the page heading for each item.
+* Title case.
+* Keep each label concise (1-3 words).
+
+## Best Practices
+
+Do:
+
+* Do make all items except the last one clickable links.
+* Do mark the current page with `aria-current="page"`.
+
+Don't:
+
+* Don't show breadcrumbs on top-level pages — there is no trail to show.
+* Don't use breadcrumbs when the IA is flat and would produce a single segment.
+* Don't use custom separator text that is read by screen readers.
+
+## Accessibility
+
+* Wrap in a `<nav aria-label="breadcrumb">` element.
+* Current page item uses `aria-current="page"`.
+* Separator characters are `aria-hidden="true"`.
+
+### Keyboard interaction
+
+| Key           | Function                                                                                                                                                                                                |
+| ------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `Tab`         | Move focus forward along the breadcrumb trail.                                                                                                                                                          |
+| `Shift + Tab` | Move focus back along the breadcrumb trail.                                                                                                                                                             |
+| `Enter`       | Activates the currently focused link. If a dropdown crumb has focus, opens the menu and gives focus to the currently selected option. If a menu item has focus, activates the item and closes the menu. |
+| `Space`       | If a dropdown crumb has focus, opens the menu and gives focus to the currently selected option.                                                                                                         |
+| `Down Arrow`  | If a dropdown crumb has focus, opens the menu and gives focus to the currently selected option. If a menu item has focus, moves focus to the next item.                                                 |
+| `Up Arrow`    | If a menu item has focus, moves focus to the previous item.                                                                                                                                             |
+| `Esc`         | If a dropdown crumb is open, closes the menu and returns focus to the trigger.                                                                                                                          |
+
+* If a dropdown crumb is open: the `tab` and `shift`+`tab` keys do not navigate.
+
+### Labeling
+
+* Breadcrumbs represent a hierarchy and need to announce themselves accordingly. Using `aria-label`, a crumb should identify itself and its parents.
+* Use `aria-current=”page”` to indicate the last page in the breadcrumb order.
+
+## Related components
+
+* [TabNav](?path=/docs/core-tabnav--design) — For in-page section navigation.

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