@capra/core 1.5.2 → 1.6.0

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.

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

@@ -0,0 +1,100 @@
+# Core/Toast - Design
+
+Renders a toast inline for documentation/preview. Not for use in production.
+
+## Anatomy
+
+### Status icon
+
+<span>
+  Indicates the type of message (info, success, warning, error)
+</span>
+
+### Body
+
+<span>
+  The message text informing the user what occurred
+</span>
+
+### Dismiss
+
+<span>
+  Close button to manually dismiss the toast
+</span>
+
+### Actions
+
+<span>
+  Optional action button relating to the notification (e.g. "Try again", "Undo")
+</span>
+
+## Properties
+
+### Type
+
+All toasts have a status of: information, attention, warning, success, and highlight. Choose the status depending on the type of message.
+
+### Body
+
+All toasts have body text, informing the user that something has occurred. The message should be as concise as possible, if a longer message is needed, consider an Alert Banner or Dialog.
+
+### Actions
+
+Toasts can have up to two action buttons, relating directly to the action taken that resulted in the notification. Examples include a link to a relevant list, or an action to try a failed submit.
+
+## Behavior
+
+### Timeout
+
+Toasts automatically close 6 seconds after they have fully loaded. The timer is paused if focus is brought into the toast by the user.
+
+### Placement
+
+Toasts appear in the right corner of the application—either top-right (default) or bottom-right. Use the <code>position</code> option when calling the Toast API to choose placement.
+
+### Width
+
+Toasts have a flexible width that sizes to content, with a minimum of 360px and maximum of 480px.
+
+### Overflow
+
+Long messages wrap within the toast width (360-480px). Craft messages to take up no more than two lines.
+
+## Best Practices
+
+**Do**
+
+<p>
+  Do use toasts for notifications that don't need to interrupt the user's workflow.
+</p>
+
+**Don't**
+
+<p>
+  Don't use toasts for destructive, high-impact decisions that require the user's full attention.
+</p>
+
+## Accessibility
+
+### Keyboard interaction
+
+If a toast is non-actionable it is not in the page's tab sequence.
+
+#### Actionable toasts
+
+When a toast has interactive elements (dismiss button, action button), the tab order is:
+
+1. Dismiss (close) button
+2. Action button (if present)
+
+### Live region
+
+The entire contents of the toast must be announced as it appears on screen. Toasts use `role="status"` for info/success and `role="alert"` for warning/error, with `aria-live` set to `polite` or `assertive` accordingly.
+
+### Reading order
+
+In order to give all users adequate time to find and reach the action button, the toast element must be placed immediately after the user's current element.
+
+### Time sensitive
+
+Toasts must remain on screen long enough for users to read the message and access any action buttons. The default duration is 6 seconds; the timer pauses if focus is brought into the toast.

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

@@ -0,0 +1,11 @@
+# Core/Toast - Usage
+
+Renders a toast inline for documentation/preview. Not for use in production.
+
+| Prop | Type | Required | Default | Description |
+| --- | --- | --- | --- | --- |
+| `type` | `(typeof toastTypes)[number]` | Yes | `--` | `--` |
+| `content` | `React.ReactNode` | Yes | `--` | `--` |
+| `closable` | `boolean` | No | true | `--` |
+| `action` | `ToastOptions['action']` | No | `--` | `--` |
+| `actionSecondary` | `ToastOptions['actionSecondary']` | No | `--` | `--` |

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

@@ -0,0 +1,61 @@
+# Core/Tooltip - Design
+
+A component to display additional information when hovering or focusing on an interactive element.
+
+## Properties
+
+### Title
+
+The text shown in the tooltip.
+
+### Shortcut
+
+The keyboard shortcut shown in the tooltip.
+
+## Behavior
+
+### Presentation
+
+Tooltips appear after a 500ms delay when hovering a trigger element. Focusing a trigger element will show the
+tooltip immediately.
+
+### Dismissing
+
+Tooltips disappear 500ms after the trigger element loses hover, immediately if focus is lost, or when another
+element receives hover or focus that reveals a tooltip.
+
+### Overflow
+
+Tooltip titles should avoid wrapping where possible. When required, the title wraps to a new line when extending
+beyond the width of the container.
+
+### Placement
+
+By default, tooltips appear below the trigger element. The tooltip will shift position if its placement places it
+outside the viewport.
+
+## Best Practices
+
+**Do**
+
+<p>
+  Do show only a single tooltip at a time.
+</p>
+
+**Don't**
+
+<img style={{ width: '256px', marginInline: 'auto', display: 'block' }} src="tooltip-bestpractices-multiple-dont.png" />
+
+<p>
+  Don't override tooltip behavior to show multiple at once.
+</p>
+
+## Accessibility
+
+### Interaction
+
+Tooltips are triggered on hover or focus, never on click. Tooltips do not contain interactive content.
+
+### Custom Trigger
+
+See the Usage page for more information on custom triggers.

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

@@ -0,0 +1,48 @@
+# Core/Tooltip - Usage
+
+A component to display additional information when hovering or focusing on an interactive element.
+
+## Custom Triggers
+
+:::warning
+
+**Custom triggers are an advanced feature and should be used with caution.** Tooltips should wrap interactive
+elements. The defaults provided in Capra ensure an accessible experience. When using custom triggers, the dev assumes
+responsibility for ensuring the tooltip trigger is accessible.
+
+:::
+
+By default, tooltips are triggered on for the `Button`, `IconButton`, `Link`, or `ButtonLink` components. For other elements, you can wrap them in a `CustomTooltipTrigger` to allow hover and focus to open the tooltip. The trigger still needs an appropriate ARIA role or semantic HTML element, and custom components should forward refs via `forwardRef` as well as spread props onto the underlying DOM node.
+
+```tsx
+import { Tooltip, CustomTooltipTrigger } from '@capra/core';
+
+function MyComponent() {
+  retur(
+    <Tooltip title="Tooltip content">
+      <CustomTooltipTrigger>
+        <span role="button" tabIndex={0} style={{ cursor: 'default', textDecoration: 'underline' }}>
+          Custom trigger (span)
+        </span>
+      </CustomTooltipTrigger>
+    </Tooltip>,
+  );
+}
+```
+
+**Important Notes**
+
+* The trigger element must have an appropriate ARIA role or semantic HTML element.
+* `CustomTooltipTrigger` only accepts a single child.
+
+## Props
+
+| Prop | Type | Required | Default | Description |
+| --- | --- | --- | --- | --- |
+| `children` | `React.ReactNode` | Yes | `--` | The visible trigger element. This can be a single element or a component tree, but there MUST be a focusable element (`Button`, `IconButton`, `Link`, or a custom trigger via `CustomTooltipTrigger`) in the tree. Nothing else will trigger the tooltip. |
+| `title` | `string` | Yes | `--` | The content of the tooltip. |
+| `shortcut` | `string` | No | `--` | Optional keyboard shortcut label shown next to the title (e.g. `⌘K`, `Ctrl+S`). |
+| `placement` | `(typeof placements)[number]` | No | 'bottom' | The position of the tooltip relative to the trigger element.<br>@default 'bottom' |
+| `isDisabled` | `boolean` | No | false | Whether the tooltip is disabled.<br>@default false |
+| `getContainer` | `() => HTMLElement \| null` | No | `--` | The container to mount the tooltip in.<br>@default document.body<br><br>**Warning**: This is an unsafe feature and may cause accessibility, keyboard navigation, and other issues. Only use if you know what you are doing. |
+| `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-topnav--design.md

@@ -0,0 +1,75 @@
+# Core/TopNav - Design
+
+## Properties
+
+### Logo
+
+The logo is required for all top navigation bars. It should link to the home page or main dashboard of the application.
+
+### Navigation items
+
+Navigation items represent the main sections of the application. They should be concise and clearly labeled. Use `TopNav.Item` for each navigation link.
+
+### Actions
+
+Actions are optional elements placed on the right side of the navigation bar. Common actions include search, notifications, user profile, and settings. Use `TopNav.Actions` to group these elements.
+
+## Best Practices
+
+### Navigation clarity
+
+**Do**
+
+<img className="w-full" src="images/guidelines/topnav/bestpractices-clarity-do.png" alt="Clear navigation labels" />
+
+<p>
+  Do use clear, descriptive labels for navigation items.
+</p>
+
+**Don't**
+
+<img className="w-full" src="images/guidelines/topnav/bestpractices-clarity-dont.png" alt="Unclear navigation labels" />
+
+<p>
+  Don't use vague or ambiguous labels that don't clearly indicate the destination.
+</p>
+
+### Action overload
+
+**Do**
+
+<img className="w-full" src="images/guidelines/topnav/bestpractices-actions-do.png" alt="Reasonable number of actions" />
+
+<p>
+  Do limit the number of actions to the most essential ones.
+</p>
+
+**Don't**
+
+<img className="w-full" src="images/guidelines/topnav/bestpractices-actions-dont.png" alt="Too many actions" />
+
+<p>
+  Don't overcrowd the actions area with too many buttons or icons.
+</p>
+
+## Accessibility
+
+### Landmark
+
+The top navigation uses `role="banner"` to identify it as the site-wide header landmark. This helps screen reader users quickly navigate to the main application header.
+
+### Banner
+
+The `TopNav` component is wrapped in a `<header>` element with `role="banner"`, which is the appropriate semantic HTML for site-wide navigation headers.
+
+### Keyboard interaction
+
+| Key               | Function                                                                         |
+| ----------------- | -------------------------------------------------------------------------------- |
+| `Tab`             | Moves focus through interactive elements in the navigation bar in logical order. |
+| `Enter` / `Space` | Activates focused links or buttons.                                              |
+| `Escape`          | Closes any open dropdowns or menus within the navigation.                        |
+
+### Targets
+
+All interactive elements in the top navigation meet the minimum 24×24 CSS pixel target size requirement for WCAG 2.2 Level AA compliance.

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

@@ -0,0 +1,6 @@
+# Core/TopNav - Usage
+
+| Prop | Type | Required | Default | Description |
+| --- | --- | --- | --- | --- |
+| `FORCE__className` | `string` | No | `--` | 🚨 This prop is meant to be an escape hatch. 🚨<br><br>If the desired style cannot be achieved using component props, use this as a last resort. The inner workings of Capra components are implementation details and this escape hatch gives one access to those implementation details. We cannot make any guarantees that styles will applied correctly across version updates. Please use it responsibly.<br><br>Add a CSS class to the component. |
+| `children` | `React.ReactNode` | No | `--` | `--` |

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

@@ -0,0 +1,31 @@
+# Core/VerticalNavigation - Design
+
+Vertical navigation shell with controlled and uncontrolled collapse support. Provides shared context for items, collapse toggle, and footer sections.
+
+## Properties
+
+### Layout
+
+VerticalNavigation consists of a list of items and an optional footer. It is typically placed on the left side of the screen.
+It supports a collapsed state to save space.
+
+### Items
+
+Navigation items can have icons and labels. Sub-items are indented and do not have icons.
+Items can be links (using `href`) or buttons (using `onClick`).
+
+## Accessibility
+
+### Keyboard interaction
+
+| Key                 | Function                                                                     |
+| ------------------- | ---------------------------------------------------------------------------- |
+| `Tab` / `Shift-Tab` | Moves focus through the interactive items (links, buttons, collapse toggle). |
+| `Enter` / `Space`   | Activates the focused item (follows link or triggers action).                |
+
+### WAI-ARIA Roles, States, and Properties
+
+* The navigation container has `role="navigation"` (implicit for `<nav>`).
+* The `aria-label` provides a descriptive name for the navigation region (default: "Cribl product navigation").
+* The collapse toggle has `aria-expanded` reflecting the collapsed state.
+* Active items use `aria-current="page"` to indicate the current page.

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

@@ -0,0 +1,17 @@
+# Core/VerticalNavigation - Usage
+
+Vertical navigation shell with controlled and uncontrolled collapse support. Provides shared context for items, collapse toggle, and footer sections.
+
+### VerticalNavigation
+
+| 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. |
+| `collapsed` | `boolean` | No | `--` | Controlled collapsed state. |
+| `onCollapseChange` | `(collapsed: boolean) => void` | No | `--` | Callback fired when the collapsed state changes. |
+| `defaultCollapsed` | `boolean` | No | false | Default collapsed state for uncontrolled mode.<br>@default false |
+| `aria-label` | `string` | No | 'Cribl product navigation' | `--` |
+
+### Examples
+
+Various product navigation configurations.

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

@@ -0,0 +1,87 @@
+# Core/VisuallyHidden - Design
+
+VisuallyHidden is a component that hides its children from the visual rendering, but still makes them available to screen readers.
+
+## Overview
+
+VisuallyHidden is a utility component that removes content from the visual flow while keeping it accessible to assistive technologies such as screen readers. It uses a well-established CSS technique that clips the element to a 1×1 pixel area without using `display: none` or `visibility: hidden`, which would remove it from the accessibility tree entirely.
+
+Use VisuallyHidden when you need to provide context or labels for screen reader users that would be redundant or unnecessary in the visual design.
+
+## Use Cases
+
+### Hidden labels for icon-only controls
+
+Icon-only buttons and controls must have accessible names. Wrap a text label in VisuallyHidden to provide one without affecting the visual design.
+
+### Supplementary link text
+
+Links like "Read more" lack context when read in isolation. Use VisuallyHidden to append descriptive text that screen readers announce.
+
+### Form labels
+
+When a form input has a visible placeholder but no visible label, use VisuallyHidden to associate a proper `<label>` element with the input.
+
+### Skip links
+
+Skip navigation links allow keyboard users to bypass repeated content. The link text can be visually hidden until it receives focus.
+
+## Best Practices
+
+**Do**
+
+<p>
+  Do use VisuallyHidden to provide accessible names for icon-only buttons and controls.
+</p>
+
+**Don't**
+
+<p>
+  Don't use VisuallyHidden to hide content that all users should see. If the content is meaningful, it should be visible.
+</p>
+
+**Do**
+
+<p>
+  Do use VisuallyHidden to add context to ambiguous links like "Read more" or "Learn more".
+</p>
+
+**Don't**
+
+<p>
+  Don't use 
+
+  `display: none`
+
+   or 
+
+  `visibility: hidden`
+
+   when content should remain available to assistive technologies.
+</p>
+
+## Accessibility
+
+### Purpose
+
+VisuallyHidden exists specifically to improve accessibility. It bridges the gap between visual design and the information needs of assistive technology users.
+
+### When to Use
+
+### WCAG 1.1.1 — Non-text Content (Level A)
+
+Provide text alternatives for non-text content such as icon-only buttons. VisuallyHidden allows you to add an accessible name without altering the visual design.
+
+### WCAG 2.4.4 — Link Purpose (Level A)
+
+Links should make sense out of context. When visual context makes the purpose clear but the link text alone is ambiguous (e.g., "Read more"), use VisuallyHidden to add clarifying text.
+
+### WCAG 2.4.6 — Headings and Labels (Level AA)
+
+Form inputs should have descriptive labels. When a visible label would be redundant with other visual cues, VisuallyHidden can provide a programmatic label for assistive technologies.
+
+### Important Notes
+
+* VisuallyHidden content **is not** hidden from screen readers — that is its entire purpose.
+* Do **not** use `aria-hidden="true"` on VisuallyHidden or its children, as this would negate its purpose.
+* Prefer `aria-label` or `aria-labelledby` when labeling a single element. Use VisuallyHidden when you need to provide more complex or multi-element content to assistive technologies.

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

@@ -0,0 +1,35 @@
+# Core/VisuallyHidden - Usage
+
+VisuallyHidden is a component that hides its children from the visual rendering, but still makes them available to screen readers.
+
+| Prop | Type | Required | Default | Description |
+| --- | --- | --- | --- | --- |
+| `children` | `React.ReactNode` | Yes | `--` | `--` |
+
+## Usage
+
+```tsx
+import { VisuallyHidden } from '@cribl/capra-core';
+
+// Accessible label for an icon-only button
+<button>
+  🔔 <VisuallyHidden>Notifications</VisuallyHidden>
+</button>
+
+// Descriptive link text
+<a href="/docs">
+  Read more<VisuallyHidden> about our API documentation</VisuallyHidden>
+</a>
+
+// Hidden form label
+<VisuallyHidden>
+  <label htmlFor="search">Search</label>
+</VisuallyHidden>
+<input id="search" type="search" placeholder="Search..." />
+```
+
+## How It Works
+
+The component renders a `<span>` element with CSS that clips it to a 1×1 pixel area using `clip-path: inset(100%)`. This keeps the content in the DOM and accessibility tree while removing it from the visual layout.
+
+The `:not(:focus):not(:active)` selector ensures that if a focusable element (like a skip link) is nested inside, it becomes visible when focused.