@capra/core 1.5.3 → 1.7.0

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

@@ -0,0 +1,145 @@
+# Core/Switch - Design
+
+## Properties
+
+### Label
+
+Switches must be paired with an accessible label, using text that clearly describes the action being performed in 1
+to 3 words. The language of the label should be phrased in a way that a response of “on”/“off” or “yes”/”no” makes
+sense to the user.
+
+<img src="images/guidelines/switch/example-1.png" />
+
+### Size
+
+Switches come in two different sizes. Medium is the default and preferred size for most situations. Small size is
+used when a switch is inline with another element, such as a table or popover.
+
+<img src="images/guidelines/switch/example-2.png" />
+
+### Selected
+
+Switches appear as either selected (on) or unselected (off). Switches cannot be in an indefinite state.
+
+<img src="images/guidelines/switch/example-3.png" />
+
+### Disabled
+
+Switches can be disabled in either a selected or unselected state if there is a prerequisite to altering its state.
+
+<img src="images/guidelines/switch/example-4.png" />
+
+## Behavior
+
+### Immediate
+
+Switches immediately update the state of the application or UI when their state changes. If a delay is necessary, a
+loading indicator should be used to inform the user that the process is taking longer.
+
+<img src="images/guidelines/switch/example-5.png" />
+
+### Labels
+
+Avoid using the words “on” or “off” within the label. Switches imply an on/off state so including it in the label is
+redundant.
+
+<img src="images/guidelines/switch/example-6.png" />
+
+## Best Practices
+
+### Labels
+
+**Do**
+
+<img src="images/guidelines/switch/example-7.png" />
+
+Do use clear and concise labels.
+
+**Don't**
+
+<img src="images/guidelines/switch/example-8.png" />
+
+Avoid using action-related verbs with “on” or “off” when adding labels to controls. Switches imply an on/off state
+so including it in the label is redundant.
+
+### Placement
+
+**Do**
+
+<img src="images/guidelines/switch/example-9.png" />
+
+Do use switches as trailing elements.
+
+**Don't**
+
+<img src="images/guidelines/switch/example-10.png" />
+
+Don’t use switches as leading elements.
+
+**Do**
+
+<img src="images/guidelines/switch/example-11.png" />
+
+Do ensure switches are either aligned with the grid or with each other when multiple switches are stacked.
+
+**Don't**
+
+<img src="images/guidelines/switch/example-12.png" />
+
+Don't misalign switches by placing them immediately after labels when multiple switches are stacked, as this can
+affect legibility.
+
+### Checkbox vs Switch
+
+**Do**
+
+<img src="images/guidelines/switch/example-13.png" />
+
+If the action is part of a larger form, use a checkbox instead. The items will be submitted with the rest of the
+form details.
+
+**Don't**
+
+<img src="images/guidelines/switch/example-14.png" />
+
+Switches apply changes immediately and don't require the user to submit anything. If you need to include the data in
+form content, use a checkbox set.
+
+### Radio vs Switch
+
+**Do**
+
+<img src="images/guidelines/switch/example-15.png" />
+
+Switches are used for activation, not selection. If you are selecting between two available options, use a radio set
+instead.
+
+**Don't**
+
+<img src="images/guidelines/switch/example-16.png" />
+
+Switches should not be used to choose between opposing or discrete options. Instead, use switches for on/off
+situations.
+
+## Accessibility
+
+### Keyboard interaction
+
+| Key                    | Function                                                      |
+| ---------------------- | ------------------------------------------------------------- |
+| `Tab`<br />`Shift-Tab` | Moves focus into/out of the switch.                           |
+| `Space`                | When focus is on the switch, changes the state of the switch. |
+
+### WAI-ARIA Roles, States, and Properties
+
+* The switch has `role=switch`.
+* The switch has an accessible label provided by one of the following:
+  * Visible text content contained within the element with `role=switch`.
+  * A visible label referenced by the value of `aria-labelledby` set on the element with `role=switch`.
+  * `aria-label` set on the element with `role=switch`.
+* When on, the switch element has state `aria-checked` set to true.
+* When off, the switch element has state `aria-checked` set to false.
+* If a set of switches is presented as a logical group with a visible label, either:
+  * The switches are included in an element with `role=group` that has the property `aria-labelledby` set to the ID of the element containing the group label.
+  * The set is contained in an HTML `<fieldset>` and the label for the set is contained in an HTML `<legend>` element.
+* If the presentation includes additional descriptive static text relevant to a switch or switch group, the switch or switch group has the property `aria-describedby` set to the ID of the element containing the description.

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

@@ -0,0 +1,8 @@
+# Core/Switch - Usage
+
+### Switch
+
+| Prop | Type | Required | Default | Description |
+| --- | --- | --- | --- | --- |
+| `size` | `'sm' \| 'md'` | 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-tabnav--design.md

@@ -0,0 +1,77 @@
+# Core/TabNav - Design
+
+TabNav provides a horizontal or vertical navigation styled as tabs. Tab items are links that redirect to URLs. With `subItems`, horizontal tabs open a dropdown menu; vertical tabs use an inline indented list (Tab Nav | Vertical in Figma).
+
+Tabs and TabNav organize and manage content allowing users to navigate between different sections within the current context.
+
+* **Tabs** organize content sections to be displayed at one time. They are displayed in Modals, Drawers, and other content panels.
+* **TabNav** is a navigation menu with links, styled as tabs. They are used in Page Headers and other places where navigation is needed.
+
+## Properties
+
+### Label
+
+Every tab must have a brief but descriptive label.
+
+### Variant
+
+TabNav has two variants:
+
+* **Default**: a single navigational link.
+* **Dropdown**: a dropdown menu that displays a ListBox with additional navigational links.
+
+## Content
+
+### Labels
+
+Tab 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.
+
+## Best Practices
+
+**Do**
+
+<p>
+  Do follow the maximum character length of tab labels.
+</p>
+
+**Don't**
+
+<p>
+  Don't exceed the 32 maximum character length.
+</p>
+
+**Do**
+
+<p>
+  Do keep tab labels short and concise.
+</p>
+
+**Don't**
+
+<p>
+  Don't wrap tab labels.
+</p>
+
+## Accessibility
+
+### Keyboard interaction
+
+| Key                          | Function                                                                                                                                                                   |
+| ---------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `Tab` / `Shift + Tab`        | Moves focus into the tab list, putting focus onto the active tab. When the tab list has focus, moves focus to the next focusable element (generally within the tab panel). |
+| `Left Arrow` / `Up Arrow`    | Moves focus to, and activate, the previous tab. If focus is on the first tab, move focus to the last tab. Up performs the same action when `tabPlacement="vertical"`.      |
+| `Right Arrow` / `Down Arrow` | Moves focus to, and activate, the next tab. If focus is on the last tab, move focus to the first tab. Down performs the same action when `tabPlacement="vertical"`.        |
+| `Shift+F10`                  | Opens the menu for tabs with a dropdown.                                                                                                                                   |
+
+### ARIA considerations
+
+TabNav uses link-based navigation. The following apply:
+
+* The container has `role="navigation"` with an `aria-label` for the navigation.
+* Active nav links have `aria-current="page"` set.
+* Tabs that contain a dropdown use a button with `aria-haspopup="menu"` and `aria-expanded` set.
+* Dropdown menu items use the Menu component with appropriate roles.
+
+### Orientation
+
+Use `tabPlacement="horizontal"` (default) for a horizontal tab bar at the bottom, or `tabPlacement="vertical"` for a vertical tab bar on the left.

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

@@ -0,0 +1,63 @@
+# Core/TabNav - Usage
+
+TabNav provides a horizontal or vertical navigation styled as tabs. Tab items are links that redirect to URLs. With `subItems`, horizontal tabs open a dropdown menu; vertical tabs use an inline indented list (Tab Nav | Vertical in Figma).
+
+| 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. |
+| `activeKey` | `string` | No | `--` | Key of the currently active tab (for visual styling). Typically derived from the current URL. |
+| `onTabClick` | `(key: string, event: React.MouseEvent) => void` | No | `--` | Callback when a tab link is clicked (before navigation). |
+| `items` | `TabNavItemType[]` | Yes | `--` | Tab items configuration. |
+| `tabPlacement` | `(typeof tabNavPlacements)[number]` | No | 'horizontal' | Orientation of the tab bar: horizontal (bottom) or vertical (left).<br>@default 'horizontal' |
+| `centered` | `boolean` | No | false | Whether to center the tabs.<br>@default false |
+| `tabBarExtraSlot` | `React.ReactNode` | No | `--` | Slot for extra content in the tab bar (e.g. right side). |
+| `wrap` | `boolean` | No | true | Whether tab items can wrap to multiple lines.<br>@default true |
+| `aria-label` | `string` | No | 'Navigation' | `--` |
+
+## Usage
+
+```tsx
+import { TabNav } from '@capra/core';
+
+// Basic usage - tab items are links that redirect to URLs
+<TabNav
+  activeKey={currentPath}
+  items={[
+    { key: '1', name: 'Tab 1', href: '/tab1' },
+    { key: '2', name: 'Tab 2', href: '/tab2' },
+  ]}
+/>
+
+// Optional `name` (visible) + `aria-label` on the item when the accessible name differs
+<TabNav
+  activeKey="overview"
+  items={[
+    { key: 'overview', name: 'Overview', 'aria-label': 'Tab 1, 1 of 3, selected', href: '/overview' },
+  ]}
+/>
+
+// With icons and disabled tab
+<TabNav
+  activeKey="1"
+  items={[
+    { key: '1', name: 'Search', icon: <SearchOutlined size="sm" />, href: '/search' },
+    { key: '2', name: 'Disabled', disabled: true, href: '/disabled' },
+  ]}
+/>
+
+// With subnav dropdown (tabs with subItems show a chevron and open a menu on click)
+<TabNav
+  activeKey="overview::summary"
+  items={[
+    {
+      key: 'overview',
+      name: 'Overview',
+      subItems: [
+        { key: 'summary', name: 'Summary', href: '/overview/summary' },
+        { key: 'details', name: 'Details', href: '/overview/details' },
+      ],
+    },
+    { key: 'settings', name: 'Settings', href: '/settings' },
+  ]}
+/>
+```

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

@@ -0,0 +1,21 @@
+# Core/Tag - Design
+
+A tag component for displaying a label and an optional icon.
+
+## Accessibility
+
+### Keyboard interaction
+
+| Key                    | Function                                              |
+| ---------------------- | ----------------------------------------------------- |
+| `Tab`<br />`Shift-Tab` | Moves focus to the next/previous interactive element. |
+| `Space`                | If the tag's remove icon has focus, remove the tag.   |
+
+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.
+
+### Draggability
+
+The tag can be made draggable by setting the `draggable` prop to `true`. When the tag is draggable, the user can drag the tag to a new position in the list.
+The drag handle provides an onKeyDown handler that allows the user to drag the tag with the keyboard.
+
+NOTE: The keyboard accessibility of the drag functionality is not defined, and is not part of this component.

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

@@ -0,0 +1,11 @@
+# Core/Tag - Usage
+
+A tag component for displaying a label and an optional icon.
+
+| Prop | Type | Required | Default | Description |
+| --- | --- | --- | --- | --- |
+| `color` | `(typeof tagColors)[number]` | No | 'default' | The color of the tag. Defaults to `default`. |
+| `icon` | `SvgIcon \| SvgLogo` | No | `--` | The icon or logo to display in the tag. |
+| `children` | `string` | Yes | `--` | The label text to display in the tag. |
+| `onDelete` | `() => void` | No | `--` | The callback function for when the user clicks the delete 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-text--design.md

@@ -0,0 +1,32 @@
+# Core/Text - Design
+
+Component for displaying text. The visual display can be controlled via `variant`. The underlying HTML element can be controlled via the `as` prop, which defaults to a `span` tag.
+
+## Properties
+
+### Text
+
+A text component isn't very useful if you're not going to put some text in it.
+
+### Variant
+
+Variant describe the contextual purpose of the text. Text may be: heading, to create logic sections within the UI
+body, for regular text throughout the UI metric, to display in graphs and data visualizations code, to display
+monospace code snippets
+
+### Color
+
+Text inherits color from its container element. In some cases text color may be adjusted outside its container's intention.
+
+### As
+
+Gives semantic meaning to the Text variant (style), setting the underlying element rendered by the component.
+
+## Accessibility
+
+### Guidelines
+
+Key factors to follow for an accessible typography:
+
+* Color. Provide enough contrast between text and its background, check out the minimum recommended [WCAG 2.2 color contrast ratio](https://www.w3.org/TR/WCAG22/#contrast-minimum) (4.5:1).
+* Heading hierarchy. Based on the [W3 guidelines](https://www.w3.org/WAI/tutorials/page-structure/headings/), don't skip heading levels. Make sure to separate the semantics from the style.

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

@@ -0,0 +1,10 @@
+# Core/Text - Usage
+
+Component for displaying text. The visual display can be controlled via `variant`. The underlying HTML element can be controlled via the `as` prop, which defaults to a `span` tag.
+
+| Prop | Type | Required | Default | Description |
+| --- | --- | --- | --- | --- |
+| `variant` | `(typeof variants)[number]` | No | `--` | The text style variant. Defaults to `body`. |
+| `color` | `Color \| 'inherit'` | No | `--` | The text foreground color. Can be a theme color or inherited from the environment. Defaults to `inherit`.<br>@default inherit |
+| `as` | `As` | No | `--` | The underlying element rendered by the component. Defaults to `span`. |
+| `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-textarea--design.md

@@ -0,0 +1,74 @@
+# Core/TextArea - Design
+
+TextArea component for multi-line text entry.
+
+### Anatomy
+
+The text area is a multi-line field. When `resizable` is true, a resize handle allows vertical resizing. Use with
+`InputField` for labels, helper text, and validation messaging.
+
+## Properties
+
+### Value
+
+The value is submitted with the form. The value replaces any placeholder text in the field after the first character
+is entered.
+
+### Placeholder text
+
+Placeholder text is visible until a character is entered. 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.
+
+### Resizable
+
+When `resizable` is `true` (default) and `autoSize` is off, a resize handle is shown and the user can drag to change
+height vertically. When `autoSize` is on, manual resizing is disabled. When `resizable` is `false`, the height is
+fixed.
+
+### Auto size
+
+`autoSize` grows the height with content (Ant Design–style API). Pass `true` or `{ minRows?, maxRows? }`. When auto
+size is on, manual resize is disabled. Height follows content; optional `maxRows` caps growth and enables vertical
+scrolling for overflow.
+
+### Status
+
+`danger`: Used to indicate an error or invalid state.
+
+`warning`: Used to indicate a warning.
+
+Styling matches TextInput for consistent forms.
+
+## Behavior
+
+### Error messages
+
+When validation fails, the field border uses the attention styling and helper text shows an error message. Error
+messages should be concise and replace any previously visible helper text where appropriate.
+
+### Disabled
+
+Disabled fields cannot be modified and cannot receive focus. Values in a disabled field are not submitted as part of
+the form.
+
+### Read-only
+
+Read-only fields cannot be modified. The value of a read-only field is submitted as part of the form.
+
+## Accessibility
+
+### Keyboard interaction
+
+| Key                 | Function                               |
+| ------------------- | -------------------------------------- |
+| `Tab` / `Shift+Tab` | Moves focus into/out of the text area. |
+| `Arrow keys`        | Move the caret within the text.        |
+| `Enter`             | Inserts a new line.                    |
+
+### Labeling and validation
+
+The component renders a semantic `textarea` element. Provide an accessible name with `aria-label` or
+`aria-labelledby`, and associate helper or error text with `aria-describedby` when used inside `InputField` or your own
+layout. The component sets `aria-invalid` when `appearance` is `danger`. Ensure focus indicators are visible (at least
+2px, 3:1 contrast) and interactive targets meet at least 24×24 CSS pixels where applicable.

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

@@ -0,0 +1,18 @@
+# Core/TextArea - Usage
+
+TextArea component for multi-line text entry.
+
+| Prop | Type | Required | Default | Description |
+| --- | --- | --- | --- | --- |
+| `appearance` | `(typeof appearances)[number]` | No | `--` | Appearance of the text area.<br>@default 'default' |
+| `resizable` | `boolean` | No | `--` | Whether the text area can be vertically resized by the user.<br>@default true |
+| `autoSize` | `boolean \| { minRows?: number; maxRows?: number }` | No | `--` | Auto-growing height (Ant Design `Input.TextArea`–style).<br>`true` grows with content; use `{ minRows, maxRows }` to clamp height.<br>When enabled, manual vertical resize is disabled (`resize: none`). |
+| `showCount` | `boolean` | No | `--` | When true, shows a character count. |
+| `onChange` | `(value: string) => void` | No | `--` | Called with the new string value when the input changes. |
+| `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. |
+| `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. |
+
+Use `InputField` with `input={TextArea}` for label above the field, helper text, character count, and validation
+appearance. Use `layout="vertical"` (default) or `layout="horizontal"` on `InputField` to match TextInput layouts.

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

@@ -0,0 +1,81 @@
+# Core/TextField - Design
+
+Single-line text field with optional label and helper text.
+
+The following guidelines are common across text-based inputs ([Core Components — Inputs](https://www.figma.com/design/ejoPUMrdRDAlyc2vyDIWWe/Core-Components?node-id=21133-20423) in Figma).
+
+## 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.
+
+### Value
+
+The value is submitted with the form. The value replaces any placeholder text in the field after the first character
+is entered.
+
+### Placeholder text
+
+Placeholder text is visible until a character is entered. 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.
+
+### 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**. With vertical labels, the content
+will shift to keep the cursor in view as the user enters characters. When the field loses focus, the content will
+scroll to the beginning. Focusing on the field again returns the user to the end of the content. Horizontal labels
+appear on the leading side of the field, and should only be used when space is limited.
+
+## Behavior
+
+### Overflow
+
+Values overflow past the trailing edge of the field. While focused, the content will shift to keep the cursor in
+view as the user enters characters. When the field loses focus, the content will scroll to the beginning. Focusing
+on the field again returns the user to the end of the content. Generally, text fields should avoid overflow. Use a
+text area field for longer entries.
+
+## Content
+
+### Search and filter fields
+
+Search and Filter fields allow a user to enter and clear query strings.
+
+**Clear button:** The clear icon appears when a value is present in the text field. When cleared the icon disappears and
+the text input keeps focus.
+
+## Feedback
+
+### Error messages
+
+When a field fails validation, the field’s border displays the attention color. The helper text also displays an
+error message to help the user successfully fulfill the field requirements. Error messages are concise and direct,
+and replace any previously visible helper text. An error icon is prepended to the helper text to enhance
+discoverability.
+
+### Disabled
+
+Disabled fields cannot be modified and cannot gain focus. Values in a disabled field are not submitted as part of
+the form.
+
+### Read-only
+
+Read-only fields cannot be modified and cannot gain focus. The value of a read-only field is submitted as part of
+the form.
+
+## Accessibility
+
+* **Label:** Provide a visible `label` or associate another element via `aria-labelledby` / `aria-label` so the control has an accessible name. Do not rely on placeholder alone for the name.
+* **Instructions and requirements:** Prefer persistent `helperText` (or other visible, associated text) over placeholder for instructions; placeholder disappears and is easy to miss.
+* **Errors:** Use `appearance="danger"` with error content in `helperText` so validation state is exposed (`aria-invalid`) and messaging replaces prior helper text.
+* **Required:** Set `required` when the field is mandatory so required state is available to assistive technologies.
+* **Disabled:** Disabled fields are not interactive; their values are not submitted with native form submission.
+* **Read-only:** Read-only values are still submitted; the field is not editable. Native read-only inputs may remain focusable for selection and screen readers—align with your product pattern if focus should be limited.

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

@@ -0,0 +1,12 @@
+# Core/TextField - Usage
+
+Single-line text field with optional label and helper text.
+
+| Prop | Type | Required | Default | Description |
+| --- | --- | --- | --- | --- |
+| `onChange` | `(value: string) => void` | No | `--` | Called with the new string value when the input changes. |
+| `showCount` | `boolean` | No | `--` | When true, shows a character count. |
+| `value` | `string \| number \| undefined` | No | `--` | `--` |
+| `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-textinput--design.md

@@ -0,0 +1,72 @@
+# Core/TextInput - Design
+
+TextInput component for single-line text entry. Backwards compatible with Ant Design v5 Input.
+
+## Anatomy
+
+## Properties
+
+### Value
+
+The value is submitted with the form. The value replaces any placeholder text in the field after the first character
+is entered.
+
+### Placeholder text
+
+Placeholder text is visible until a character is entered. 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.
+
+### Size
+
+<p>
+  `md`
+
+  : Standard size used across the majority of the UI.
+</p>
+
+<p>
+  `sm`
+
+  : Used when an input is in a supporting position, such as directly above a table for filtering.
+</p>
+
+### Status
+
+`error`: Used to indicate that the input has an error.
+
+`warning`: Used to indicate that the input has a warning.
+
+## Behavior
+
+### Overflow
+
+Input values overflow past the trailing edge of the input container. While focused, the content will shift to keep
+the cursor in view as the user enters characters. When the field loses focus, the content will scroll to the
+beginning. Focusing on the field again returns the user to the end of the content. Generally, text fields should
+avoid overflow. Use a Text area field for longer entries.
+
+### Error messages
+
+When a field fails validation, the input's border displays the attention color. The helper text also displays
+an error message to help the user successfully fulfill the input requirements. Error messages are concise and
+direct, and replace any previously visible helper text. An error icon is prepended to the helper text to enhance
+discoverability.
+
+### Disabled
+
+Disabled fields can not be modified and can not gain focus. Values in a disabled field are not submitted as part of
+the form.
+
+### Read-only
+
+Read-only fields can not be modified. The value of a read-only field is submitted as part of the form.
+
+## Accessibility
+
+### Keyboard interaction
+
+| Key                 | Function                                                                                                         |
+| ------------------- | ---------------------------------------------------------------------------------------------------------------- |
+| `Tab` / `Shift+Tab` | Moves focus into/out of the input field.<br />For inputs with embedded actions, move to the next/previous action |
+| `Enter` / `Space`   | For inputs with embedded actions, activates the currently focused action.                                        |

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

@@ -0,0 +1,19 @@
+# Core/TextInput - Usage
+
+TextInput component for single-line text entry. Backwards compatible with Ant Design v5 Input.
+
+:::warning[Internal only]
+
+`TextInput` is not exported from the public `@capra/core` API. For single-line text entry in product code, use [`TextField`](?path=/docs/core-textfield--design).
+
+:::
+
+| Prop | Type | Required | Default | Description |
+| --- | --- | --- | --- | --- |
+| `appearance` | `(typeof appearances)[number]` | No | `--` | Appearance of the input.<br>@default 'default' |
+| `leadingSlot` | `React.ReactNode` | No | `--` | Content before the input (e.g. icon). |
+| `size` | `(typeof sizes)[number]` | No | `--` | Size of the input.<br>@default 'md' |
+| `trailingSlot` | `React.ReactNode` | No | `--` | Content after the input (e.g. icon or clear 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. |
+
+Use `layout="vertical"` (default) for label above the field; use `layout="horizontal"` for label on the leading side when space is limited.