@d4gger/design-system 2.7.0

package/dist/docs/input-group.md

@@ -0,0 +1,227 @@
+---
+title: InputGroup
+status: canonical
+category: Components
+archetype: composite
+package_path: packages/d4gger-design-system/src/components/inputGroup/InputGroup.tsx
+css_path: packages/d4gger-design-system/src/styles/components/input-group.css
+props_path: packages/d4gger-design-system/src/components/inputGroup/inputGroup.props.ts
+test_path: packages/d4gger-design-system/src/test/components/InputGroup.test.tsx
+demo_path: apps/playground/app/(themeable)/docs/[component]/page.tsx
+playground_registry_path: apps/playground/lib/registry/forms.tsx
+playground_manifest_path: apps/playground/lib/component-manifest.ts
+depends_on:
+  - Input
+  - TextArea
+  - Button
+---
+
+# InputGroup
+
+> Source of truth: the package source at `package_path`. The spec file mirrors the source. Edits to the spec must land in the source in the same change, or the QA flags will fire.
+
+## Purpose
+
+A flexible wrapper that fuses an `Input` or `TextArea` with leading or trailing addons, inline buttons, and short text. The group collapses the shared border, flattens the inner radius, and lifts the focused or hovered child so the focus ring stays visible. The orientation switches between a horizontal row and a vertical stack without changing the slot API.
+
+## Anatomy & slots
+
+**Parent:** `InputGroup` (alias of `InputGroup.Root`).
+
+**Slots:**
+
+| Slot | Element | Renders | Notes |
+|---|---|---|---|
+| `InputGroup.Root` | `<div>` | flex container | Drives `data-orientation` and `data-size`. |
+| `InputGroup.Addon` | `<div>` | inline addon block | A small label or static affordance, typically for `$`, `https://`, or a unit. |
+| `InputGroup.Text` | `<span>` | inline text fragment | A quieter label than `Addon`; sits inline as a `span`. |
+| `InputGroup.Button` | `Button` | a `Button` reset to `size="sm"` and `variant="ghost"` by default | Inline submit or trigger button. |
+| `InputGroup.Input` | `Input` | the package `Input` primitive | Passes through all `InputProps`. |
+| `InputGroup.Textarea` | `TextArea` | the package `TextArea` primitive | Passes through all `TextareaProps` except `color`, which the group filters out. |
+
+## Props contract
+
+### `InputGroup.Root` props
+
+| Prop | Type | Default | Required | Description | Responsive |
+|---|---|---|---|---|---|
+| `orientation` | `'horizontal' \| 'vertical'` | `'horizontal'` | no | Stack direction. `'vertical'` switches the group to a column and rotates the inner radius/border-collapse rules. Drives `data-orientation`. | no |
+| `size` | `'sm' \| 'md' \| 'lg'` | `'md'` | no | Height token. Drives `data-size` and the children match via their own `data-size` hooks. | no |
+| `asChild` | `boolean` | `false` | no | Renders the root through `Slot` from `@radix-ui/react-slot`. | no |
+| `children` | `React.ReactNode` | `undefined` | no | Addon, Text, Button, Input, and Textarea children. | no |
+| Standard `<div>` props | `ComponentPropsWithoutRef<'div'>` | n/a | no | Forwarded. | no |
+
+### `InputGroup.Addon` props
+
+| Prop | Type | Default | Required | Description | Responsive |
+|---|---|---|---|---|---|
+| `asChild` | `boolean` | `false` | no | Renders the addon through `Slot`. | no |
+| `children` | `React.ReactNode` | `undefined` | no | Addon content. | no |
+| Standard `<div>` props | `ComponentPropsWithoutRef<'div'>` | n/a | no | Forwarded. | no |
+
+### `InputGroup.Text` props
+
+| Prop | Type | Default | Required | Description | Responsive |
+|---|---|---|---|---|---|
+| `asChild` | `boolean` | `false` | no | Renders the text through `Slot`. | no |
+| `children` | `React.ReactNode` | `undefined` | no | Inline text content. | no |
+| Standard `<span>` props | `ComponentPropsWithoutRef<'span'>` | n/a | no | Forwarded. | no |
+
+### `InputGroup.Button` props
+
+The `Button` defaults to `size="sm"` and `variant="ghost"` so the button blends into the group border. The consumer can override both. All other `ButtonProps` pass through.
+
+### `InputGroup.Input` props
+
+All `InputProps` pass through. The slot is a thin re-export of `Input`; the group does not add or filter props.
+
+### `InputGroup.Textarea` props
+
+All `TextareaProps` pass through except `'color'`, which the group omits to avoid clashing with future accent props. When `asChild` is set, the slot renders a `Slot`; otherwise it renders the `Textarea` primitive directly.
+
+## CSS class contract
+
+**Root class:** `dsx-input-group`
+
+**Modifier classes** (driven by `data-*` attributes written by the component):
+
+| Attribute | Allowed values | Class | CSS file |
+|---|---|---|---|
+| `data-orientation` | `horizontal`, `vertical` | `.dsx-input-group[data-orientation='vertical']` switches to `flex-direction: column` | `input-group.css` |
+| `data-size` | `sm`, `md`, `lg` | n/a (children match via their own `data-size` hooks) | `input-group.css` |
+
+**Slot classes:**
+
+| Slot | Class | CSS file |
+|---|---|---|
+| `InputGroup.Addon` | `dsx-input-group__addon` | `input-group.css` |
+| `InputGroup.Text` | `dsx-input-group__text` | `input-group.css` |
+| `InputGroup.Button` | `dsx-input-group__button` | `input-group.css` |
+| `InputGroup.Input` | n/a (renders the package `Input` with its own shell class) | n/a |
+| `InputGroup.Textarea` | `dsx-input-group__textarea` | `input-group.css` |
+
+**Responsive behavior:**
+
+- The component does not write `@media` rules. None of its prop defs are `responsive: true`. Size and orientation are single-value only.
+
+**Reduced motion:**
+
+- The component does not currently animate its own state. Children animate their own focus and hover states via the standard `Input` and `TextArea` motion tokens.
+
+## Token mapping
+
+Every CSS value the component paints is a `var(--dsx-*)` token.
+
+| Property | Token | Role |
+|---|---|---|
+| Container layout | `display: flex; align-items: stretch; width: 100%` | Cluster layout. |
+| Container isolation | `isolation: isolate` | Stacking context for focused-child lift. |
+| Vertical layout | `flex-direction: column` | Driven by `data-orientation='vertical'`. |
+| Inner shell/textarea growth | `flex: 1` on `.dsx-input-shell` and `.dsx-textarea` children | Inner control fills remaining space. |
+| Addon/Text padding | `var(--dsx-space-sm)` block, `var(--dsx-space-md)` inline | Inner gutter. |
+| Addon/Text color | `var(--dsx-color-on-surface-variant)` | Quiet label color. |
+| Addon/Text wrap | `white-space: nowrap` | Prevents multi-line addons. |
+| Button border | `var(--dsx-control-separator-color)` | Matches the group separator. |
+| Horizontal inner radius reset | `border-start-start-radius: 0; border-end-start-radius: 0` on every non-first child, `border-start-end-radius: 0; border-end-end-radius: 0` on every non-last child | Fuses the cluster. |
+| Horizontal border collapse | `margin-inline-start: calc(-1 * var(--dsx-border-width-sm, 1px))` | Merges the shared border. |
+| Vertical inner radius reset | `border-start-start-radius: 0; border-start-end-radius: 0` on every non-first child, `border-end-start-radius: 0; border-end-end-radius: 0` on every non-last child | Fuses the vertical stack. |
+| Vertical border collapse | `margin-block-start: calc(-1 * var(--dsx-border-width-sm, 1px))` | Merges the shared border. |
+| Focus lift | `z-index: 1` on `:focus-within` and `:hover` | Lifts the focused or hovered child above its siblings. |
+
+## Motion contract
+
+| Region | Token | Default | Reduced |
+|---|---|---|---|
+| Container | `none` | `none` | `none` |
+| Children | child-driven | `Input` and `TextArea` children animate their own focus state. The `Button` child animates its own hover state. | Children honor `prefers-reduced-motion` in their own CSS. |
+
+## Accessibility
+
+**Roles:**
+
+- The root is a plain `<div>`. The group does not introduce a new landmark; consumers wrap it in `Field.Root` when they need a labelled form row.
+
+**Keyboard:**
+
+| Key | Action |
+|---|---|
+| `Tab` | Moves focus into and out of the group, then between the slotted controls in DOM order. |
+| `Enter`, `Space` | Activates the focused child (submit, button toggle, etc.). The `Input` and `TextArea` children accept `Space` and `Enter` via the browser's default text-entry behavior. |
+
+**Focus:**
+
+- The group lifts the focused or hovered child to `z-index: 1` so the focus ring is fully visible even when adjacent children share a border.
+
+**Reduced motion:**
+
+- The group itself does not animate. Children honor their own `prefers-reduced-motion` rules.
+
+**Color and meaning:**
+
+- The group is structural. State meaning is communicated by the children, not the container.
+
+**Naming:**
+
+- The root has no implicit accessible name. Consumers should wrap the group in `Field.Root` with a `Field.Label` for accessible naming, or supply `aria-label` on the wrapped control.
+
+## Playground demo spec
+
+**Default story:**
+
+- Renders `InputGroup` with one `InputGroup.Input`. Asserts the root class is `dsx-input-group`, `data-orientation="horizontal"`, and `data-size="md"`.
+
+**Orientation story:**
+
+- Renders with `orientation="vertical"`. Asserts `data-orientation="vertical"`.
+- Renders with `orientation="horizontal"`. Asserts `data-orientation="horizontal"`.
+
+**Size story:**
+
+- Renders with `size="sm"`, `size="md"`, and `size="lg"`. Asserts the matching `data-size` attribute.
+
+**Composition story:**
+
+- Renders the group with `InputGroup.Addon` + `InputGroup.Input` + `InputGroup.Button`. Asserts all three slots render with their classes (`dsx-input-group__addon`, `dsx-input-group__button`) and the input retains its own shell class.
+
+**State story:**
+
+- Renders with a focused child. Asserts the focused child sits at `z-index: 1`.
+
+**A11y story:**
+
+- Uses `vitest-axe` against the rendered default group with an `aria-label` on the inner `Input`. Asserts no axe violations.
+
+**Props exposed in the playground controls:**
+
+| Prop | Control | Default |
+|---|---|---|
+| `orientation` | select | `horizontal` |
+| `size` | select | `md` |
+| `asChild` | boolean | `false` |
+
+## Wiring notes
+
+**Composes from:**
+
+- `Input`: the `InputGroup.Input` slot is a thin re-export.
+- `TextArea`: the `InputGroup.Textarea` slot is a thin re-export, with `color` filtered out.
+- `Button`: the `InputGroup.Button` slot is a `Button` preconfigured to `size="sm"` and `variant="ghost"`.
+- `@radix-ui/react-slot`: enables `asChild` on the root, addon, text, and textarea slots.
+
+**Used by:**
+
+- Search fields: `<InputGroup.Addon>🔍</InputGroup.Addon><InputGroup.Input />`.
+- URL fields: `<InputGroup.Addon>https://</InputGroup.Addon><InputGroup.Input /><InputGroup.Text>.com</InputGroup.Text>`.
+- Currency fields: `<InputGroup.Text>$</InputGroup.Text><InputGroup.Input type="number" />`.
+- Copy/share: `<InputGroup.Input readOnly value={url} /><InputGroup.Button>Copy</InputGroup.Button>`.
+- Form rows that wrap a `Field` and an `InputGroup` together.
+
+**State boundaries:**
+
+- Owned by InputGroup: the orientation and size attributes, the inner radius reset, the border collapse, the focus/hover lift, and the slot host elements.
+- Owned by the consumer: the value of the inner input or textarea, the onChange handler, the button's onClick, and the surrounding `Field` integration.
+
+**Boundary rules:**
+
+- App-owned data: the value, change handler, validation, and form context.
+- DS-owned visuals: the group container, the slot classes, the radius reset, the border collapse, and the focus lift.

package/dist/docs/input-otp.md

@@ -0,0 +1,306 @@
+---
+title: InputOtp
+status: canonical
+category: Components
+archetype: composite
+package_path: packages/d4gger-design-system/src/components/inputOtp/InputOtp.tsx
+css_path: packages/d4gger-design-system/src/styles/components/input-otp.css
+props_path: packages/d4gger-design-system/src/components/inputOtp/inputOtp.props.ts
+test_path: packages/d4gger-design-system/src/test/components/InputOtp.test.tsx
+demo_path: apps/playground/app/(themeable)/docs/[component]/page.tsx
+playground_registry_path: apps/playground/lib/registry/forms.tsx
+playground_manifest_path: apps/playground/lib/component-manifest.ts
+depends_on:
+  - input-otp (the `OTPInput` primitive, `OTPInputContext`, and the `RenderProps` type come from the `input-otp` package; the runtime is a thin DS wrapper around it)
+  - "_internal/baseInput.css (shared border, hover, focus, disabled, and autofill contract; the OTP shell imports it for parity with `Input`)"
+  - "@radix-ui/react-slot (asChild on the root and on the group slot)"
+---
+
+# InputOtp
+
+> Source of truth: the package source at `package_path`. The spec file mirrors the source. Edits to the spec must land in the source in the same change, or the QA flags will fire.
+
+## Purpose
+
+A verification-code and short-PIN entry control. The user types into a hidden absolute-positioned input that overlays a row of visible slots, one per character. Each slot reflects the active index, the typed character, and a blinking caret. Use `InputOtp` for one-time codes, short PINs, and any bounded multi-character input; for free-form text, use `Input`; for tag-style multi-value entry, use `TagsInput`.
+
+## Anatomy & slots
+
+**Parent:** `InputOtp` (alias of the `InputOtp` default export; `InputOtp.Group`, `InputOtp.Slot`, and `InputOtp.Separator` are attached via `Object.assign`).
+
+**Slots:**
+
+| Slot | Element | Renders | Notes |
+|---|---|---|---|
+| `InputOtp` (Root) | `OTPInput` from `input-otp` | The OTP container is a flex row of `dsx-input-otp__group` blocks. The root is a `dsx-input-otp` div with `data-size`, `data-radius`, `data-slot="input-otp-input"`. | The visible slots. Hosts a hidden absolute-positioned input. |
+| (hidden input) | `<input>` from `OTPInput` | `dsx-input-otp__hidden-input` | The actual text entry surface. Sits absolutely on top of the slots; consumers interact with it transparently. |
+| `InputOtp.Group` | `<div>` (or slotted host) | `dsx-input-otp__group`, plus `data-slot="input-otp-group"` | A row of slots. Use multiple groups to insert separators between segments. |
+| `InputOtp.Slot` | `<div>` | `dsx-input-otp__slot`, plus `data-slot="input-otp-slot"`, `data-active="true"`, and `data-filled="true"` as appropriate. When the slot is the active index, the runtime renders a `dsx-input-otp__caret-wrapper` with a `dsx-input-otp__caret` inside. | A single character slot. The slot's `index` prop is required and is the lookup key into the `OTPInputContext` `slots` array. |
+| `InputOtp.Separator` | `<div>` with `role="separator"` | `dsx-input-otp__separator` (with inner `dsx-input-otp__separator-dash`), plus `data-slot="input-otp-separator"`, `data-slot="input-otp-separator-dash"` on the inner dash. | Visual divider between groups. Has no semantic effect on the input. |
+
+## Props contract
+
+**Root props (`InputOtp`):**
+
+| Prop | Type | Default | Required | Description | Responsive |
+|---|---|---|---|---|---|
+| `asChild` | `boolean` | `false` | no | Renders the root through `Slot` from `@radix-ui/react-slot`. The `extractProps` step consumes the prop so the host element receives the class. | no |
+| `size` | `'sm' \| 'md' \| 'lg'` | `'md'` | no | Slot size. Writes `data-size` on the root. The CSS does not currently declare per-size rules; the attribute is the contract hook. | no |
+| `radius` | `'none' \| 'sm' \| 'md' \| 'lg' \| 'full'` | `'md'` | no | Slot corner roundness. Writes `data-radius`. | no |
+| `containerClassName` | `string` | `undefined` | no | Extra classes appended to `dsx-input-otp`. | no |
+| `className` | `string` | `undefined` | no | Extra classes appended to `dsx-input-otp__hidden-input`. | no |
+| `maxLength` | `number` | `6` | no | Maximum number of characters. The OTP input enforces the cap. The runtime forwards this to `OTPInput`. | no |
+| (other `OTPInput` props) | n/a | n/a | no | All other `OTPInput` props (except `children`, `maxLength`, and `render`, which the runtime owns) are forwarded. | no |
+
+`InputOTPProps` is `Omit<BaseOTPInputProps, 'children' \| 'maxLength' \| 'render'> & InputOTPOwnProps & { children: React.ReactNode; maxLength?: number }`. The runtime requires `children` (a slot tree of groups and slots) and provides its own `render` strategy through the slot composition.
+
+**`InputOtp.Group` props:** standard `React.ComponentPropsWithoutRef<'div'>` plus `asChild`.
+
+**`InputOtp.Slot` props:**
+
+| Prop | Type | Default | Required | Description | Responsive |
+|---|---|---|---|---|---|
+| `index` | `number` | `undefined` | no (but the runtime cannot render a meaningful slot without it) | The slot's index into the `OTPInputContext.slots` array. Drives `data-active`, `data-filled`, and the rendered character. | no |
+| (HTML div props) | n/a | n/a | no | All standard `<div>` attributes are forwarded. | no |
+
+When `index` is missing or the slot at `index` is not yet in the context, the slot renders an empty `dsx-input-otp__slot` with no `data-active`, no `data-filled`, and no caret.
+
+**`InputOtp.Separator` props:** standard `React.ComponentPropsWithoutRef<'div'>`.
+
+Rules:
+
+- The `asChild` flag is consumed by `extractProps` in the root and the group, then dropped from the forwarded bag.
+- The `extractProps` step on the slot does not currently route a prop bag (the slot's prop def is `{} satisfies Record<string, never>`). The slot only reads `className` and `index`.
+- The separator's prop def is also empty. It always renders the dash inside the `dsx-input-otp__separator` host.
+
+## CSS class contract
+
+**Root class:** `dsx-input-otp` (the OTP container; the hidden input has its own class).
+
+**Modifier classes** (driven by `data-*` attributes written by the component):
+
+| Attribute | Allowed values | Class | CSS file |
+|---|---|---|---|
+| `data-size` | `sm`, `md`, `lg` | (attribute written on root; no per-size CSS rule today) | `input-otp.css` |
+| `data-radius` | `none`, `sm`, `md`, `lg`, `full` | (attribute written on root; CSS reads `--dsx-radius-*` for the slot border-radius) | `input-otp.css` |
+| `data-active` | `true` | (attribute written on the active slot; CSS uses it to drive the focus border) | `input-otp.css` |
+| `data-filled` | `true` | (attribute written on filled slots) | `input-otp.css` |
+| `data-slot` | `input-otp-input`, `input-otp-group`, `input-otp-slot`, `input-otp-separator`, `input-otp-caret-wrapper`, `input-otp-caret`, `input-otp-separator-dash` | (attribute written for tooling) | `input-otp.css` |
+
+**Slot classes:**
+
+| Slot | Class | CSS file |
+|---|---|---|
+| `InputOtp` (Root) | `dsx-input-otp` | `input-otp.css` |
+| Hidden input | `dsx-input-otp__hidden-input` | `input-otp.css` |
+| `InputOtp.Group` | `dsx-input-otp__group` | `input-otp.css` |
+| `InputOtp.Slot` | `dsx-input-otp__slot` | `input-otp.css` |
+| Caret wrapper | `dsx-input-otp__caret-wrapper` | `input-otp.css` |
+| Caret | `dsx-input-otp__caret` | `input-otp.css` |
+| `InputOtp.Separator` | `dsx-input-otp__separator` | `input-otp.css` |
+| Separator dash | `dsx-input-otp__separator-dash` | `input-otp.css` |
+
+**Responsive behavior:**
+
+- The component does not write `@media` rules. None of the prop defs are `responsive: true`. Size and radius are single-value only.
+
+**Reduced motion:**
+
+- The caret has a `dsx-blink` keyframe animation driven by `var(--dsx-motion-duration-blink)`. A local `prefers-reduced-motion: reduce` rule removes the animation and fixes opacity at `1`, so the caret stays visible without blinking.
+
+## Token mapping
+
+Every CSS value the component paints is a `var(--dsx-*)` token.
+
+| Property | Token | Role |
+|---|---|---|
+| Container gap | `var(--dsx-space-sm)` | Gap between groups and separators. |
+| Group gap | `var(--dsx-space-xs)` | Gap between slots inside a group. |
+| Slot width | `var(--dsx-input-otp-slot-width)` | Slot width. |
+| Slot height | `var(--dsx-input-otp-slot-height)` | Slot height. |
+| Slot border | `1px` (hard-coded hairline) | Visual parity with `Input`. |
+| Slot typography | `var(--dsx-typography-body-large-*)` | Slot character ramp. |
+| Caret width | `var(--dsx-input-otp-caret-width)` | Caret width. |
+| Caret height | `var(--dsx-input-otp-caret-height)` | Caret height. |
+| Caret color | `var(--dsx-color-on-surface)` | Caret fill. |
+| Caret animation duration | `var(--dsx-motion-duration-blink)` | Blink cadence. |
+| Separator dash width | `var(--dsx-input-otp-separator-width)` | Separator dash width. |
+| Separator dash height | `var(--dsx-input-otp-separator-height)` | Separator dash height. |
+| Separator dash color | `var(--dsx-color-outline)` | Separator dash fill. |
+| Hidden input z-index | `var(--dsx-z-index-overlay-local)` | Hidden input stacking. |
+
+Rules:
+
+- The 1px slot border is the one intentional non-token value. The comment in the source (`Keep 1px hairline border for visual parity.`) calls it out as a deliberate parity choice.
+- The CSS file does not introduce motion durations or easing curves. The `dsx-blink` keyframe is the only animation; the rest of the contract is static.
+
+## Motion contract
+
+| Region | Token | Default | Reduced |
+|---|---|---|---|
+| Caret blink | `var(--dsx-motion-duration-blink)` | Step-end infinite blink | Local CSS sets `animation: none` and `opacity: 1`. |
+
+Rules:
+
+- The caret uses a CSS keyframe animation rather than a `MOTION_TRANSITIONS` preset. The runtime does not import `usePrefersReducedMotion`; the local media query is the authoritative reduced-motion behavior.
+- The OTP content has no other motion. The hidden input, slots, groups, and separators are static.
+
+## Accessibility
+
+**Roles:**
+
+- The hidden input is the actual form control. It carries the OTP input's accessible name. Consumers should set `aria-label` (or wrap with `<label>`) so the input has a name.
+- `InputOtp.Separator` carries `role="separator"`.
+- Each `InputOtp.Slot` is a styled `<div>`. The hidden input is the source of truth for assistive tech; the slots are visual markers.
+
+**Keyboard:**
+
+| Key | Action |
+|---|---|
+| `Tab` | Moves focus to or from the hidden input. |
+| Type | Inserts a character into the active slot and advances the cursor. |
+| `Backspace` | Clears the active slot and moves the cursor back. |
+| `Arrow keys` | Forwarded to the OTP input for cursor movement. |
+| `Cmd/Ctrl + A` | Selects all typed characters. |
+
+**Focus:**
+
+- The hidden input is the only focusable element. Its `:focus-visible` ring follows the `baseInput.css` contract.
+
+**Reduced motion:**
+
+- The caret blink animation is the only motion. The local stylesheet removes the blink while retaining a visible caret.
+
+**Color and meaning:**
+
+- The active slot is communicated by `data-active="true"` and by the visible caret. The filled state is communicated by the rendered character and `data-filled="true"`. Color is not the only signal.
+
+**Naming:**
+
+- Provide `aria-label` (or `<label>` association) on the root. The hidden input takes the `aria-label` and the OTP's `aria-label` flows through to assistive tech.
+
+## Playground demo spec
+
+**Default story:**
+
+- Renders `InputOtp` with `maxLength={6}` and one `InputOtp.Group` containing six `InputOtp.Slot` instances. Asserts the root class is `dsx-input-otp`, the hidden input is in the DOM, and the slot count matches `maxLength`.
+
+**Size story:**
+
+- Renders one `InputOtp` per `size` value (`sm`, `md`, `lg`). Asserts the matching `data-size` attribute is set on the root.
+
+**Radius story:**
+
+- Renders one `InputOtp` per `radius` value (`none`, `sm`, `md`, `lg`, `full`). Asserts the matching `data-radius` attribute is set on the root.
+
+**Composition story:**
+
+- Renders `InputOtp` with two `InputOtp.Group` blocks separated by `InputOtp.Separator`. Asserts the separator has `role="separator"`, the dash class is rendered, and the slot groups are split correctly.
+
+**State story:**
+
+- Renders `InputOtp` and types one character. Asserts the first slot has `data-filled="true"`, the second slot has `data-active="true"`, and the caret is visible inside the active slot.
+
+**A11y story:**
+
+- Uses `vitest-axe` against an `InputOtp` with an `aria-label`. Asserts there are no axe violations.
+
+**Props exposed in the playground controls:**
+
+| Prop | Control | Default |
+|---|---|---|
+| `size` | select | `md` |
+| `radius` | select | `md` |
+| `maxLength` | number | `6` |
+
+## Wiring notes
+
+**Composes from:**
+
+- `input-otp` (`OTPInput`, `OTPInputContext`, `RenderProps`): the state machine, the slot array, the cursor management, and the typing handler.
+- `_internal/baseInput.css`: the shared border, hover, focus, disabled, and autofill contract the OTP shell imports for parity with `Input`.
+- `@radix-ui/react-slot`: enables `asChild` on the root and on `InputOtp.Group`.
+
+**Used by:**
+
+- Verification and short-PIN flows. The roster does not list any DS consumer.
+
+**State boundaries:**
+
+- Owned by `InputOtp`: the slot index resolution, the `data-active` and `data-filled` attribute writes, the caret rendering inside the active slot, the separator dash, and the hidden input class.
+- Owned by the `input-otp` package: the cursor state, the typed value, the `OTPInputContext` provider, the paste handler, the keyboard navigation, and the max-length enforcement.
+- Owned by the consumer: the `value` / `onChange` (or the `defaultValue` and uncontrolled mode), the `maxLength`, the `aria-label`, and the form context.
+
+**Boundary rules:**
+
+- App-owned data: the typed value, the submission target, the validation predicate, the disabled reason, and the surrounding form context.
+- DS-owned visuals: token bindings, the `dsx-input-otp*` slot classes, the `data-*` attribute contract, the caret animation, the `data-slot` tool markers, and the 1px hairline border.
+
+## Penpot build recipe
+
+> Optional. Penpot is a visual reference, not a code authority. Keep this section when the component has a published Penpot asset, or when the spec needs to call out a visual decision the package does not encode. Skip the section when the component is utility or layout-primitive; the package code is the only authority.
+
+The package does not yet publish a Penpot asset for InputOtp. Recipe is visual reference only and tracks the CSS contract.
+
+### Root board
+
+- **Name**: `Components / InputOtp`.
+- **Dimensions**: `auto × auto` (sized by `data-size` and slot count).
+- **Layout**: `Flex` (row).
+- **Sizing**: `horizontalSizing = 'auto'`, `verticalSizing = 'auto'`.
+
+### Layer tree
+
+```
+<Root Board: InputOtp>
+  ├── <Frame: group>
+  │     ├── <Frame: slot × N>
+  │     │     ├── <Text: character (when filled)>
+  │     │     └── <Frame: caret wrapper (when active)>
+  │     │           └── <Frame: caret>
+  ├── <Frame: separator (between groups)>
+  │     └── <Frame: separator dash>
+  └── <Frame: group>
+        └── <Frame: slot × N>
+```
+
+### Token bindings (Penpot properties)
+
+| Shape | Property | Token | Token type | Penpot property name |
+|---|---|---|---|---|
+| Container | gap | `--dsx-space-sm` | Spacing | `gap` |
+| Group | gap | `--dsx-space-xs` | Spacing | `gap` |
+| Slot | width | `--dsx-input-otp-slot-width` | Sizing | `width` |
+| Slot | height | `--dsx-input-otp-slot-height` | Sizing | `height` |
+| Slot | border | `1px` (hairline) | Border | `border` |
+| Slot (active) | border | `--dsx-color-primary` | Color | `border` (state) |
+| Slot | typography | `--dsx-typography-body-large-*` | Typography | `typography` |
+| Caret | width | `--dsx-input-otp-caret-width` | Sizing | `width` |
+| Caret | height | `--dsx-input-otp-caret-height` | Sizing | `height` |
+| Caret | fill | `--dsx-color-on-surface` | Color | `fills` |
+| Caret | animation | `--dsx-motion-duration-blink` | Motion | `animation-duration` |
+| Separator dash | width | `--dsx-input-otp-separator-width` | Sizing | `width` |
+| Separator dash | height | `--dsx-input-otp-separator-height` | Sizing | `height` |
+| Separator dash | fill | `--dsx-color-outline` | Color | `fills` |
+
+### State transformations
+
+| State | Slot border | Caret visible | Slot text |
+|---|---|---|---|
+| `default` | `1px` hairline | hidden | empty |
+| `active` (focus) | `--dsx-color-primary` | shown | empty |
+| `filled` | hairline | hidden | typed character |
+
+### Variant model
+
+- `size`: `sm`, `md`, `lg`. Default `md`.
+- `radius`: `none`, `sm`, `md`, `lg`, `full`. Default `md`.
+- `maxLength`: integer. Default `6`.
+- Total members: 3 × 5 × N.
+
+### Validation checklist
+
+- [ ] Token bindings resolve at the values `DESIGN.md` describes.
+- [ ] Component is promoted to Main Component under `Components`.
+- [ ] `penpotUtils.shapeStructure(board, 3)` matches the expected hierarchy.
+- [ ] The 1px hairline border is baked in as a deliberate parity value, not as a Penpot token.