@capra/core 1.5.3 → 1.7.0

package/dist/style.css

@@ -342,7 +342,7 @@
   position: absolute;
   overflow: hidden;
 }
-.capra-TextInput-module-I5TDpa-wrapper {
+.capra-TextInput-module-pTHfnG-wrapper {
   border: var(--cds2-border-default);
   border-color: var(--cds2-temporary-input-border-primary);
   border-radius: var(--cds2-radius-md);
@@ -371,7 +371,7 @@
     border-color: var(--cds2-temporary-input-border-disabled);
     color: var(--cds2-temporary-input-foreground-disabled);
 
-    & .capra-TextInput-module-I5TDpa-leadingSlot, & .capra-TextInput-module-I5TDpa-trailingSlot {
+    & .capra-TextInput-module-pTHfnG-leadingSlot, & .capra-TextInput-module-pTHfnG-trailingSlot {
       color: var(--cds2-temporary-input-foreground-disabled);
     }
   }
@@ -379,7 +379,7 @@
   &:has( > input:read-only) {
     cursor: default;
 
-    & .capra-TextInput-module-I5TDpa-input {
+    & .capra-TextInput-module-pTHfnG-input {
       cursor: default;
     }
   }
@@ -387,12 +387,12 @@
   &:has( > input:disabled) {
     cursor: not-allowed;
 
-    & .capra-TextInput-module-I5TDpa-input {
+    & .capra-TextInput-module-pTHfnG-input {
       cursor: not-allowed;
     }
   }
 
-  & .capra-TextInput-module-I5TDpa-input {
+  & .capra-TextInput-module-pTHfnG-input {
     min-width: 0;
     color: inherit;
     font: inherit;
@@ -408,26 +408,56 @@
   }
 
   &[data-size="sm"] {
-    padding-inline: var(--cds2-spacing-md);
     gap: var(--cds2-spacing-sm);
 
-    & .capra-TextInput-module-I5TDpa-input {
+    &:not(:has(.capra-TextInput-module-pTHfnG-leadingSlot)) .capra-TextInput-module-pTHfnG-input {
+      padding-inline-start: var(--cds2-spacing-md);
+    }
+
+    &:not(:has(.capra-TextInput-module-pTHfnG-trailingSlot)) .capra-TextInput-module-pTHfnG-input {
+      padding-inline-end: var(--cds2-spacing-md);
+    }
+
+    & .capra-TextInput-module-pTHfnG-input {
       height: calc(var(--cds2-dimension-component-sm) - 2px);
       font: var(--cds2-typography-body-sm-normal);
     }
+
+    & .capra-TextInput-module-pTHfnG-leadingSlot {
+      padding-inline-start: var(--cds2-spacing-md);
+    }
+
+    & .capra-TextInput-module-pTHfnG-trailingSlot {
+      padding-inline-end: var(--cds2-spacing-md);
+    }
   }
 
   &[data-size="md"] {
-    padding-inline: var(--cds2-spacing-md);
     gap: var(--cds2-spacing-md);
 
-    & .capra-TextInput-module-I5TDpa-input {
+    &:not(:has(.capra-TextInput-module-pTHfnG-leadingSlot)) .capra-TextInput-module-pTHfnG-input {
+      padding-inline-start: var(--cds2-spacing-md);
+    }
+
+    &:not(:has(.capra-TextInput-module-pTHfnG-trailingSlot)) .capra-TextInput-module-pTHfnG-input {
+      padding-inline-end: var(--cds2-spacing-md);
+    }
+
+    & .capra-TextInput-module-pTHfnG-input {
       height: calc(var(--cds2-dimension-component-md) - 2px);
       font: var(--cds2-typography-body-md-normal);
     }
+
+    & .capra-TextInput-module-pTHfnG-leadingSlot {
+      padding-inline-start: var(--cds2-spacing-md);
+    }
+
+    & .capra-TextInput-module-pTHfnG-trailingSlot {
+      padding-inline-end: var(--cds2-spacing-md);
+    }
   }
 
-  & .capra-TextInput-module-I5TDpa-leadingSlot, & .capra-TextInput-module-I5TDpa-trailingSlot {
+  & .capra-TextInput-module-pTHfnG-leadingSlot, & .capra-TextInput-module-pTHfnG-trailingSlot {
     align-items: center;
     gap: var(--cds2-spacing-xs);
     color: var(--cds2-color-foreground-subtle);
@@ -435,7 +465,7 @@
     display: inline-flex;
   }
 
-  & .capra-TextInput-module-I5TDpa-errorIndicator {
+  & .capra-TextInput-module-pTHfnG-errorIndicator {
     color: var(--cds2-color-foreground-danger-default);
     flex-shrink: 0;
     justify-content: center;
@@ -443,7 +473,7 @@
     display: inline-flex;
   }
 
-  & .capra-TextInput-module-I5TDpa-warningIndicator {
+  & .capra-TextInput-module-pTHfnG-warningIndicator {
     color: var(--cds2-color-foreground-warning-default);
     flex-shrink: 0;
     justify-content: center;
@@ -2232,15 +2262,15 @@ input:disabled + .capra-Radio-module-ZI7rzq-inner:after {
     color: var(--cds2-color-foreground-warning-default);
   }
 }
-.capra-Modal-module-5vfSOW-overlay {
+.capra-Modal-module-j-u8iq-overlay {
   background-color: var(--cds2-color-background-scrim);
-  animation: capra-Modal-module-5vfSOW-overlayShow var(--cds2-motion-duration-medium-1) var(--cds2-motion-easing-standard);
-  z-index: 1000;
+  animation: capra-Modal-module-j-u8iq-overlayShow var(--cds2-motion-duration-medium-1) var(--cds2-motion-easing-standard);
+  z-index: 10000;
   position: fixed;
   inset: 0;
 }
 
-.capra-Modal-module-5vfSOW-surface {
+.capra-Modal-module-j-u8iq-surface {
   background-color: var(--cds2-color-background-panel-solid);
   border-radius: var(--cds2-radius-lg);
   border: var(--cds2-border-default);
@@ -2248,7 +2278,7 @@ input:disabled + .capra-Radio-module-ZI7rzq-inner:after {
   box-shadow: var(--cds2-shadow-high-down);
   max-width: 100%;
   max-height: min(80vh, 100vh - 48px);
-  animation: capra-Modal-module-5vfSOW-contentShow var(--cds2-motion-duration-medium-1) var(--cds2-motion-easing-standard);
+  animation: capra-Modal-module-j-u8iq-contentShow var(--cds2-motion-duration-medium-1) var(--cds2-motion-easing-standard);
   flex-direction: column;
   padding: 0;
   display: flex;
@@ -2271,7 +2301,7 @@ input:disabled + .capra-Radio-module-ZI7rzq-inner:after {
   }
 }
 
-.capra-Modal-module-5vfSOW-header {
+.capra-Modal-module-j-u8iq-header {
   padding: var(--cds2-spacing-md) var(--cds2-spacing-lg);
   border-bottom: var(--cds2-border-default);
   border-color: var(--cds2-color-border-neutral-subtle);
@@ -2282,21 +2312,21 @@ input:disabled + .capra-Radio-module-ZI7rzq-inner:after {
   display: flex;
 }
 
-.capra-Modal-module-5vfSOW-headerLeading {
+.capra-Modal-module-j-u8iq-headerLeading {
   align-items: center;
   gap: var(--cds2-spacing-md);
   flex: 1;
   display: flex;
 }
 
-.capra-Modal-module-5vfSOW-expandedTitleLayout {
+.capra-Modal-module-j-u8iq-expandedTitleLayout {
   align-items: center;
   gap: var(--cds2-spacing-md);
   flex-direction: row;
   display: flex;
 }
 
-.capra-Modal-module-5vfSOW-content {
+.capra-Modal-module-j-u8iq-content {
   padding: var(--cds2-spacing-lg);
   flex-direction: column;
   flex: 1;
@@ -2304,14 +2334,14 @@ input:disabled + .capra-Radio-module-ZI7rzq-inner:after {
   overflow-y: auto;
 }
 
-.capra-Modal-module-5vfSOW-footer {
+.capra-Modal-module-j-u8iq-footer {
   padding: var(--cds2-spacing-md) var(--cds2-spacing-lg);
   border-top: var(--cds2-border-default);
   border-color: var(--cds2-color-border-neutral-subtle);
   background-color: var(--cds2-color-background-neutral-subtle);
 }
 
-.capra-Modal-module-5vfSOW-expandedFooterLayout {
+.capra-Modal-module-j-u8iq-expandedFooterLayout {
   justify-content: space-between;
   align-items: center;
   gap: var(--cds2-spacing-md);
@@ -2319,7 +2349,7 @@ input:disabled + .capra-Radio-module-ZI7rzq-inner:after {
   display: flex;
 }
 
-.capra-Modal-module-5vfSOW-footerActions {
+.capra-Modal-module-j-u8iq-footerActions {
   justify-content: flex-end;
   align-items: center;
   gap: var(--cds2-spacing-md);
@@ -2328,20 +2358,20 @@ input:disabled + .capra-Radio-module-ZI7rzq-inner:after {
   display: flex;
 }
 
-.capra-Modal-module-5vfSOW-confirmationSurface {
+.capra-Modal-module-j-u8iq-confirmationSurface {
   border-radius: var(--cds2-radius-md);
   width: min(400px, 100vw - 48px);
   box-shadow: var(--cds2-shadow-high-down);
   padding: var(--cds2-spacing-2xl) var(--cds2-spacing-2xl) var(--cds2-spacing-xl);
 }
 
-.capra-Modal-module-5vfSOW-confirmationLayout {
+.capra-Modal-module-j-u8iq-confirmationLayout {
   align-items: flex-start;
   gap: var(--cds2-spacing-lg);
   display: flex;
 }
 
-.capra-Modal-module-5vfSOW-confirmationIcon {
+.capra-Modal-module-j-u8iq-confirmationIcon {
   width: var(--cds2-dimension-component-sm);
   height: var(--cds2-dimension-component-sm);
   flex-shrink: 0;
@@ -2370,19 +2400,19 @@ input:disabled + .capra-Radio-module-ZI7rzq-inner:after {
   }
 }
 
-.capra-Modal-module-5vfSOW-confirmationBody {
+.capra-Modal-module-j-u8iq-confirmationBody {
   gap: var(--cds2-spacing-md);
   flex-direction: column;
   flex: 1;
   display: flex;
 }
 
-.capra-Modal-module-5vfSOW-confirmationMessage {
+.capra-Modal-module-j-u8iq-confirmationMessage {
   font: var(--cds2-typography-body-md-normal);
   margin: 0;
 }
 
-.capra-Modal-module-5vfSOW-confirmationActions {
+.capra-Modal-module-j-u8iq-confirmationActions {
   justify-content: flex-end;
   gap: var(--cds2-spacing-md);
   width: 100%;
@@ -2390,7 +2420,7 @@ input:disabled + .capra-Radio-module-ZI7rzq-inner:after {
   display: flex;
 }
 
-@keyframes capra-Modal-module-5vfSOW-overlayShow {
+@keyframes capra-Modal-module-j-u8iq-overlayShow {
   from {
     opacity: 0;
   }
@@ -2400,7 +2430,7 @@ input:disabled + .capra-Radio-module-ZI7rzq-inner:after {
   }
 }
 
-@keyframes capra-Modal-module-5vfSOW-contentShow {
+@keyframes capra-Modal-module-j-u8iq-contentShow {
   from {
     opacity: 0;
     transform: translate(-50%, -20px) scale(.96);

package/docs/conventions--docs.md

@@ -0,0 +1,186 @@
+# Conventions
+
+When building and consuming Capra components, we follow specific conventions to maintain a healthy codebase.
+
+### Semantic Properties
+
+Certain properties of Capra components have well-defined, consistent uses.
+
+| Prop         | Purpose                                                                                          | Possible Values                                                |
+| ------------ | ------------------------------------------------------------------------------------------------ | -------------------------------------------------------------- |
+| `appearance` | Change the colors of a component using semantic intent, e.g. a danger `Button` when deleting     | `default`, `info`, `danger`, `warning`, `success`, `highlight` |
+| `color`      | Change the color of a component to a specific color, e.g. a teal `Ribbon`                        | Component-specific                                             |
+| `layout`     | Alter the component's layout, e.g. a horizontal input field with label                           | Component-specific                                             |
+| `size`       | Specify the size of the component                                                                | `xs`, `sm`, `md`, `lg`, `xl`                                   |
+| `variant`    | Specify a different visual treatment for the component, e.g. a dot `Badge` vs. a counter `Badge` | Component-specific                                             |
+
+For props where the possible values are pre-defined, a component may utilize the full set or a subset of the possible values.
+
+### Styling Overrides
+
+Capra components are built according to our design system specifications. They should rarely need to be styled differently than what is provided out-of-the-box. In the event custom styling is required, we provide a consistent escape hatch across all of our components for passing a CSS class name: `FORCE__className`.
+
+In your application, you can apply a style override like this:
+
+```tsx
+import { Text } from '@capra/core';
+import styles from './Component.modules.css';
+
+export function Component(props) {
+  return <Text FORCE__className={styles.text}>Hello world</Text>;
+}
+```
+
+Note that using this prop should be a rarity. Adding styles here is also somewhat brittle. While we do provide this escape hatch, we make no guarantees that the styles applied will apply correctly across version updates, e.g. a style override targeting a specific HTML structure within a Capra component breaks because the component was refactored to use a different HTML structure. The inner workings of Capra components are implementation details and this escape hatch gives one access to those implementation details. Please use it responsibly.
+
+## Client-side Routing
+
+Capra components such as `Link` and `ButtonLink` render links that perform navigation when the user interacts with them. Each component that supports link behavior accepts an `href` prop, which is passed to the underlying `<a>` element.
+
+By default, links perform native browser navigation when they are interacted with. However, Capra supports overriding this behavior using a client-side router of your choice. Set this up once in the root of your app, and any Capra link component will automatically navigate using your router.
+
+Note that external links to different origins will not trigger client side routing, and will use native browser navigation. Additionally, if the link has a target other than `"_self"`, uses the `download` attribute, or the user presses modifier keys such as `Command` or `Alt` to change the default behavior, browser native navigation will occur instead of client side routing.
+
+### `RouterProvider`
+
+The `RouterProvider` component accepts two props: `navigate` and `useHref`. `navigate` should be set to a function received from your router for performing a client side navigation programmatically. `useHref` is an optional prop that converts a router-specific href to a native HTML href, e.g. prepending a base path. The following example shows the general pattern. Framework-specific examples are shown below.
+
+```tsx
+import {RouterProvider} from '@capra/core';
+import {useNavigate, useHref} from 'your-router';
+
+function App() {
+  const navigate = useNavigate();
+
+  return (
+    <RouterProvider navigate={navigate} useHref={useHref}>
+      {/* ... */}
+    </RouterProvider>
+  );
+}
+```
+
+### Router Options
+
+All Capra link components accept a `routerOptions` prop, which is an object that is passed through to the client side router's `navigate` function as the second argument. This can be used to control any router-specific behaviors, such as scrolling, replacing instead of pushing to the history, etc.
+
+```tsx
+<Link href="/login" routerOptions={{replace: true}}>{/* ...*/}</Link>
+```
+
+When using TypeScript, you can configure the `RouterConfig` type globally so that all link components have auto complete and type safety using a type provided by your router.
+
+```tsx
+import type {RouterOptions} from 'your-router';
+
+declare module '@capra/core' {
+  interface RouterConfig {
+    routerOptions: RouterOptions
+  }
+}
+```
+
+### React Router
+
+The [useNavigate](https://reactrouter.com/en/main/hooks/use-navigate) hook from `react-router-dom` returns a `navigate` function you can pass to `RouterProvider`. The [useHref](https://reactrouter.com/en/main/hooks/use-href) hook can also be provided if you're using React Router's `basename` option. Ensure that the component that calls `useNavigate` and renders `RouterProvider` is inside the router component (e.g. `BrowserRouter`) so that it has access to React Router's internal context. The React Router `<Routes>` element should also be defined inside Capra's `<RouterProvider>` so that links inside the rendered routes have access to the router.
+
+```tsx
+import {BrowserRouter, useNavigate, useHref, type NavigateOptions} from 'react-router-dom';
+import {RouterProvider} from '@capra/core';
+
+declare module '@capra/core' {
+  interface RouterConfig {
+    routerOptions: NavigateOptions
+  }
+}
+
+function App() {
+  const navigate = useNavigate();
+
+  return (
+    <RouterProvider navigate={navigate} useHref={useHref}>
+      {/* Your app here... */}
+      <Routes>
+        <Route path="/" element={<HomePage />} />
+        {/* ... */}
+      </Routes>
+    </RouterProvider>
+  );
+}
+
+<BrowserRouter>
+  <App />
+</BrowserRouter>
+```
+
+### Next.js App Router
+
+The [useRouter](https://nextjs.org/docs/app/api-reference/functions/use-router) hook from `next/navigation` returns a router object that can be used to perform navigation. `RouterProvider` should be rendered from a client component at the root of each page or layout that includes Capra links. You can create a new client component for this, or combine it with other top-level providers as described in the [Next.js docs](https://nextjs.org/docs/app/building-your-application/rendering/composition-patterns#using-context-providers).
+
+```tsx
+// app/provider.tsx
+"use client";
+
+import {useRouter} from 'next/navigation';
+import {RouterProvider} from '@capra/core';
+
+declare module '@capra/core' {
+  interface RouterConfig {
+    routerOptions: NonNullable<Parameters<ReturnType<typeof useRouter>['push']>[1]>
+  }
+}
+
+export function ClientProviders({children}) {
+  const router = useRouter();
+
+  return (
+    <RouterProvider navigate={router.push}>
+      {children}
+    </RouterProvider>
+  );
+}
+```
+
+Then, in your page or layout server component, wrap your app in the `ClientProviders` component that you defined.
+
+```tsx
+// app/layout.tsx
+import {ClientProviders} from './provider';
+
+export default function RootLayout({children}) {
+  return (
+    <html>
+      <body>
+        <ClientProviders>{children}</ClientProviders>
+      </body>
+    </html>
+  );
+}
+```
+
+### Next.js Pages Router
+
+The [useRouter](https://nextjs.org/docs/pages/api-reference/functions/use-router) hook from `next/router` returns a router object that can be used to perform navigation. `RouterProvider` should be rendered at the root of each page that includes Capra links, or in `pages/_app.tsx` to add it to all pages.
+
+```tsx
+// pages/_app.tsx
+import type { AppProps } from 'next/app';
+import {useRouter, type NextRouter} from 'next/router';
+import {RouterProvider} from '@capra/core';
+
+declare module '@capra/core' {
+  interface RouterConfig {
+    routerOptions: NonNullable<Parameters<NextRouter['push']>[2]>
+  }
+}
+
+export default function MyApp({Component, pageProps}: AppProps) {
+  const router = useRouter();
+
+  return (
+    <RouterProvider navigate={(href, opts) => router.push(href, undefined, opts)}>
+      <Component {...pageProps} />
+    </RouterProvider>
+  );
+}
+```

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>
+```