banhaten 0.1.2 → 0.2.0

package/docs/design-system/components/empty-state.md

@@ -0,0 +1,72 @@
+# Empty State
+
+Empty State is a reusable result-state composition for no-results, first-run, or cleared workflow moments. It uses a neutral tokenized icon halo, 17px semibold title text, 15px regular supporting copy, and optional Banhaten Button actions.
+
+## API
+
+```tsx
+<EmptyState
+  title="No results found"
+  description="Try adjusting your search or filters"
+  actions={[
+    { label: "Reset filters", variant: "secondary" },
+    { label: "Create item" },
+  ]}
+/>
+```
+
+| Prop | Values | Default |
+| --- | --- | --- |
+| `title` | `ReactNode` | required |
+| `description` | `ReactNode` | none |
+| `icon` | `ReactNode` | `SearchIcon` |
+| `iconLabel` | `string` | decorative icon |
+| `actions` | `EmptyStateAction[]` | `[]` |
+| `align` | `center`, `start` | `center` |
+| `size` | `default`, `compact` | `default` |
+| `dir` | `ltr`, `rtl`, `auto` | `ltr` |
+
+## Token Contract
+
+- Icon halo: `--bh-bg-neutral-subtle`, `--bh-bg-neutral-soft`, `--bh-radius-full`
+- Title: `--bh-text-heading-xs-semibold-*`, `--bh-content-default`
+- Description: `--bh-text-body-md-regular-*`, `--bh-content-subtle`
+- Spacing and sizing: `--bh-space-*`
+- Actions: existing `Button` component variants and token contract
+
+## RTL Rules
+
+`EmptyState` inherits logical alignment through `dir`. Text uses `dir="auto"` so Arabic and English copy resolve naturally, while the action row preserves logical order in RTL containers.
+
+## Install
+
+```bash
+npx banhaten add empty-state
+```
+
+## Examples
+
+Primary registry example: `examples/expanded/empty-state-demo.tsx`.
+
+Open the live component page or run `npx banhaten docs empty-state` to inspect source files, install command, and examples.
+
+## Accessibility
+
+Keep native semantics, accessible names, keyboard reachability, focus-visible treatment, and status/error announcements intact when composing this component.
+
+<!-- registry-contract:start -->
+## Registry Contract
+
+This table is generated from `registry/index.json`; edit the component-owned source under `registry/catalog/components/`, not this table or the compiled index.
+`supportedExports` is the exhaustive runtime import contract grouped by source module. `parts` is an ordered, non-exhaustive anatomy list.
+
+| Field | Values |
+| --- | --- |
+| `supportedExports` | `components/expanded/EmptyState.tsx: EmptyState` |
+| `parts` | `EmptyState` |
+| `registryDependencies` | `button` |
+| `alignments` | `center`, `start` |
+| `features` | `neutral icon halo`, `title and description copy`, `primary and secondary actions`, `custom icon`, `RTL` |
+| `sizes` | `default`, `compact` |
+| `tokens` | `--bh-bg-neutral-subtle`, `--bh-content-default`, `--bh-content-subtle`, `--bh-empty-state-icon-stroke-width`, `--bh-font-family`, `--bh-radius-full`, `--bh-space-10xl-80`, `--bh-space-13xl-160`, `--bh-space-16xl-256`, `--bh-space-19xl-384`, `--bh-space-3xl-16`, `--bh-space-5xl-24`, `--bh-space-6xl-32`, `--bh-space-9xl-64`, `--bh-space-xl-12`, `--bh-space-xs-4`, `--bh-text-base-letter-spacing`, `--bh-text-body-md-regular-font-size`, `--bh-text-body-md-regular-font-weight`, `--bh-text-body-md-regular-letter-spacing`, `--bh-text-body-md-regular-line-height`, `--bh-text-heading-xs-semibold-font-size`, `--bh-text-heading-xs-semibold-font-weight`, `--bh-text-heading-xs-semibold-letter-spacing`, `--bh-text-heading-xs-semibold-line-height` |
+<!-- registry-contract:end -->

package/docs/design-system/components/field.md

@@ -0,0 +1,86 @@
+# Field
+
+Field composes labels, controls, descriptions, and validation errors into accessible form rows. It gives Banhaten a shared form anatomy without forcing a validation library.
+
+## API
+
+```tsx
+<Field invalid>
+  <FieldLabel>Email</FieldLabel>
+  <FieldControl>
+    <Input state="error" />
+  </FieldControl>
+  <FieldError>Enter a valid email address.</FieldError>
+</Field>
+```
+
+| Part | Purpose |
+| --- | --- |
+| `Field` | row context, ids, invalid and disabled state |
+| `FieldLabel` | label connected to the control id |
+| `FieldControl` | `asChild` slot that wires id and ARIA state |
+| `FieldDescription` | helper text |
+| `FieldError` | validation message with alert role |
+| `FieldSet`, `FieldLegend`, `FieldGroup`, `FieldContent` | grouped form layout |
+
+## Validation Pattern
+
+Use native state for plain forms, or map your validation library state into `invalid`, `FieldError`, and the child control state.
+
+```tsx
+<Field invalid={Boolean(errors.email)}>
+  <FieldLabel>Email</FieldLabel>
+  <FieldControl>
+    <Input state={errors.email ? "error" : "default"} />
+  </FieldControl>
+  {errors.email ? <FieldError>{errors.email.message}</FieldError> : null}
+</Field>
+```
+
+## Token Contract
+
+Field uses Banhaten spacing, content, danger, field, typography, and disabled tokens. Child controls keep ownership of their own surface tokens.
+
+## RTL
+
+Field uses logical grid and text-start alignment. Horizontal and responsive orientations mirror naturally under inherited `dir`.
+
+## Install
+
+```bash
+npx banhaten add field
+```
+
+## Examples
+
+Primary registry example: `examples/field-demo.tsx`.
+
+Open the live component page or run `npx banhaten docs field` to inspect source files, install command, and examples.
+
+## RTL Rules
+
+- `inheritsDirection`: true
+- `layout`: Vertical, horizontal, and responsive layouts use CSS grid and logical text alignment so field rows mirror naturally.
+- `textDirection`: Labels, descriptions, and errors use dir="auto" through Label and field text parts.
+- `semantics`: FieldControl wires the generated control id, invalid state, disabled announcement, and description/error ids into the child control.
+
+## Accessibility
+
+This component relies on `@radix-ui/react-slot` for its base accessibility behavior. Keep required labels, titles, descriptions, and focusable trigger/content relationships intact when composing it.
+
+<!-- registry-contract:start -->
+## Registry Contract
+
+This table is generated from `registry/index.json`; edit the component-owned source under `registry/catalog/components/`, not this table or the compiled index.
+`supportedExports` is the exhaustive runtime import contract grouped by source module. `parts` is an ordered, non-exhaustive anatomy list.
+
+| Field | Values |
+| --- | --- |
+| `supportedExports` | `components/field.tsx: Field, FieldContent, FieldControl, FieldDescription, FieldError, FieldGroup, FieldLabel, FieldLegend, FieldSet` |
+| `parts` | `Field`, `FieldLabel`, `FieldControl`, `FieldDescription`, `FieldError`, `FieldGroup`, `FieldSet`, `FieldLegend`, `FieldContent` |
+| `registryDependencies` | `label` |
+| `features` | `generated ids`, `control slot`, `description text`, `error text`, `field groups`, `validation mapping` |
+| `orientations` | `vertical`, `horizontal`, `responsive` |
+| `states` | `default`, `invalid`, `disabled` |
+| `tokens` | `--bh-content-danger-default`, `--bh-content-default`, `--bh-content-subtle`, `--bh-space-17xl-288`, `--bh-space-3xl-16`, `--bh-space-md-8`, `--bh-space-xs-4`, `--bh-text-body-md-semibold-font-size`, `--bh-text-body-md-semibold-font-weight`, `--bh-text-body-md-semibold-letter-spacing`, `--bh-text-body-md-semibold-line-height`, `--bh-text-body-xs-regular-font-size`, `--bh-text-body-xs-regular-font-weight`, `--bh-text-body-xs-regular-letter-spacing`, `--bh-text-body-xs-regular-line-height` |
+<!-- registry-contract:end -->

package/docs/design-system/components/file-upload.md

@@ -0,0 +1,199 @@
+# File Upload
+
+`FileUpload` lets people drag files into a drop zone, browse for files, and review queued upload items. Use it when the workflow supports one or more files and the user needs clear per-file status feedback.
+
+Figma reference: `File upload`, node `254:3195`.
+
+## Variants
+
+The Figma component defines these top-level variants:
+
+| Size | Direction |
+| --- | --- |
+| `lg` | LTR |
+| `sm` | LTR |
+| `lg` | RTL |
+| `sm` | RTL |
+
+Queued file rows define these states:
+
+| State | Meaning |
+| --- | --- |
+| `uploaded` | The file finished uploading successfully. |
+| `uploading` | The file is uploading and progress is unknown. |
+| `uploading-progress` | The file is uploading and exposes a progress bar. |
+| `error` | The file failed and needs a retry or removal action. |
+
+## API
+
+Use semantic names in code and let the implementation map them to the current appearance preset.
+
+```ts
+type FileUploadSize = "lg" | "sm";
+type FileUploadVariant = "default" | "button";
+type FileUploadDropzoneState = "default" | "hover";
+type FileUploadItemStatus = "uploaded" | "uploading" | "uploading-progress" | "error";
+
+type FileUploadFile = {
+  id: string;
+  name: string;
+  sizeLabel: string;
+  versionLabel?: string;
+  progress?: number;
+  progressLabel?: string;
+  extensionLabel?: string;
+  status: FileUploadItemStatus;
+  errorLabel?: string;
+  uploadedLabel?: string;
+  uploadLabel?: string;
+};
+
+type FileUploadProps = {
+  size?: FileUploadSize;
+  variant?: FileUploadVariant;
+  dropzoneState?: FileUploadDropzoneState;
+  dir?: "ltr" | "rtl" | "auto";
+  files?: FileUploadFile[];
+  title?: string;
+  prompt?: string;
+  browseLabel?: string;
+  helperText?: string;
+  disabled?: boolean;
+  accept?: string;
+  multiple?: boolean;
+  onBrowse?: () => void;
+  onDrop?: (files: FileList) => void;
+  onMore?: (fileId: string) => void;
+  onCancel?: (fileId: string) => void;
+  onRemove?: (fileId: string) => void;
+  onRetry?: (fileId: string) => void;
+};
+```
+
+`files` controls whether the queued file list renders. Do not expose a separate `hasFilesQueued` prop in production code; the rendered state should follow from the file array.
+
+## Layout
+
+- The root stacks the drop zone and queued file list vertically.
+- Large width is 500px in the Figma source; small width is 343px. Implementations may use `width: 100%` with those values as max-widths.
+- The default drop zone is 500px by 180px; the title-plus-button variant is 500px by 256px.
+- The drop zone is centered, uses a 2px dashed border, and hover strengthens the border without changing the surface.
+- The upload icon container is 48px square with a subtle border and the current control radius.
+- Large file rows use 16px padding, a 40px file icon, and 12px gaps.
+- Small file rows use 12px padding, a 32px file icon, and 8px gaps.
+- Row actions are icon-only: more, close/cancel, and trash.
+- The queued list uses a 12px vertical gap.
+- RTL mode mirrors visual order and aligns file metadata to the end while preserving logical reading order.
+
+## Tokens
+
+The Figma source uses design tokens such as `bg/raised`, `interactive/secondary/default`, `border/subtle`, `border/danger/strong`, `space/*`, and `radius/*`. Implementations should map those to the design system's semantic token contract.
+
+```ts
+export const fileUploadTokens = {
+  dropzoneBackground: "background.subtle",
+  dropzoneBorder: "border.default",
+  dropzoneIconBackground: "background.default",
+  dropzoneIconBorder: "border.subtle",
+  rowBackground: "background.card",
+  rowBorder: "border.subtle",
+  rowErrorBorder: "border.danger",
+  rowElevation: "elevation.card",
+  textColor: "content.default",
+  helperTextColor: "content.subtle",
+  linkColor: "content.link",
+  successColor: "content.success",
+  dangerColor: "content.danger",
+  rowRadiusLarge: "shape.card",
+  rowRadiusSmall: "shape.control",
+};
+```
+
+Do not hard-code the Figma fallback values in component code. For example, the error state should resolve through `border.danger` and `content.danger`, not through the Figma fallback hex values.
+
+## Behavior
+
+- Clicking the browse text or drop zone should open the platform file picker.
+- Dragging files over the drop zone should show the same target without changing the component API.
+- `uploading` rows should expose a close/cancel action.
+- `uploading-progress` rows should expose a real progress bar and percent label.
+- `uploaded` rows should expose remove and overflow actions when the product has secondary file actions.
+- `error` rows should expose remove and retry actions.
+- The component should support both single-file and multi-file use through the `multiple` prop or equivalent platform API.
+
+## Accessibility
+
+- Use a real file input or a button connected to a file input.
+- Preserve keyboard access for browse, cancel, remove, retry, and overflow actions.
+- Announce upload status changes through an accessible live region when status changes after initial render.
+- Keep file names as real text and avoid icon-only status communication.
+- Icon-only actions need accessible labels such as `Cancel upload`, `Remove file`, `Retry upload`, and `More file actions`.
+- The drop zone should not be the only way to select files.
+
+## Usage
+
+```tsx
+<FileUpload
+  files={[
+    { id: "1", name: "file-name.pdf", sizeLabel: "32mb", versionLabel: "v1.2.2", status: "uploaded" },
+    { id: "2", name: "file-name.pdf", sizeLabel: "32mb", versionLabel: "v1.2.2", status: "uploading" },
+    { id: "3", name: "file-name.pdf", sizeLabel: "32 KB", progress: 40, status: "uploading-progress" },
+    { id: "4", name: "file-name.pdf", sizeLabel: "32mb", versionLabel: "v1.2.2", status: "error" },
+  ]}
+  multiple
+/>
+
+<FileUpload size="sm" files={[{ id: "1", name: "file-name.pdf", sizeLabel: "32 KB", status: "uploaded" }]} />
+
+<FileUpload dir="rtl" size="lg" />
+```
+
+## Preset Impact
+
+- `default`: white rows on a subtle drop-zone background, modest radius, quiet shadow, and balanced spacing.
+- `rounded`: softer drop-zone and row corners, slightly more padding, and gentler borders.
+- `sharp`: square or near-square row treatment, denser spacing, stronger borders, and minimal row elevation.
+
+## Implementation Notes
+
+- Keep the drop zone and file row primitives separate so rows can be reused in compact upload summaries.
+- Prefer existing icon components for upload, file type, success, loading, close, more, trash, and warning actions.
+- Use a real progress indicator when the product can report upload progress; use the `uploading` label when progress is unknown.
+- Truncate long file names in the middle or end, but keep the full file name available to assistive technology and tooltips.
+- Avoid coupling RTL behavior to translated strings. Direction should come from `dir` or document context.
+
+## Install
+
+```bash
+npx banhaten add file-upload
+```
+
+## Examples
+
+Primary registry example: `examples/expanded/file-upload-demo.tsx`.
+
+Open the live component page or run `npx banhaten docs file-upload` to inspect source files, install command, and examples.
+
+## Token Contract
+
+Component styles must resolve through Banhaten semantic tokens, component aliases, or documented exception-ledger values.
+Do not add raw colors, pixel values, opacity utilities, z-index values, durations, or shadow literals directly to component source.
+Covered source files: `components/expanded/fileUpload.css`, `components/expanded/FileUpload.tsx`.
+
+## RTL Rules
+
+This component has no special RTL contract beyond inherited document direction and logical spacing.
+
+<!-- registry-contract:start -->
+## Registry Contract
+
+This table is generated from `registry/index.json`; edit the component-owned source under `registry/catalog/components/`, not this table or the compiled index.
+`supportedExports` is the exhaustive runtime import contract grouped by source module. `parts` is an ordered, non-exhaustive anatomy list.
+
+| Field | Values |
+| --- | --- |
+| `supportedExports` | `components/expanded/FileUpload.tsx: FileUpload` |
+| `parts` | `FileUpload` |
+| `registryDependencies` | `button` |
+| `tokens` | `--bh-bg-accent-amber-default`, `--bh-bg-accent-aqua-default`, `--bh-bg-accent-blue-default`, `--bh-bg-accent-fuchsia-default`, `--bh-bg-accent-golden-default`, `--bh-bg-accent-green-default`, `--bh-bg-accent-lime-default`, `--bh-bg-accent-purple-default`, `--bh-bg-accent-red-default`, `--bh-bg-accent-rose-default`, `--bh-bg-accent-sky-base`, `--bh-bg-default`, `--bh-bg-dim`, `--bh-bg-neutral-default`, `--bh-bg-neutral-subtle`, `--bh-bg-raised`, `--bh-bg-subtle`, `--bh-bg-success-default`, `--bh-border-danger-strong`, `--bh-border-default`, `--bh-border-disabled`, `--bh-border-focus`, `--bh-border-strong`, `--bh-border-subtle`, `--bh-border-width-default`, `--bh-border-width-strong`, `--bh-content-brand-default`, `--bh-content-danger-default`, `--bh-content-default`, `--bh-content-disabled`, `--bh-content-link`, `--bh-content-link-hover`, `--bh-content-on-color`, `--bh-content-subtle`, `--bh-content-success-default`, `--bh-duration-fast`, `--bh-easing-standard`, `--bh-file-upload-content-max-width`, `--bh-file-upload-root-max-width`, `--bh-file-upload-spin-duration`, `--bh-focus-ring-width`, `--bh-font-family`, `--bh-font-weight-bold`, `--bh-font-weight-medium`, `--bh-font-weight-regular`, `--bh-font-weight-semibold`, `--bh-icon-stroke-200`, `--bh-icon-stroke-220`, `--bh-radius-2xl-12`, `--bh-radius-full`, `--bh-radius-lg-8`, `--bh-radius-sm-4`, `--bh-space-13xl-160`, `--bh-space-16xl-256`, `--bh-space-3xl-16`, `--bh-space-4xl-20`, `--bh-space-5xl-24`, `--bh-space-6xl-32`, `--bh-space-7xl-40`, `--bh-space-8xl-48`, `--bh-space-9xl-64`, `--bh-space-lg-10`, `--bh-space-md-8`, `--bh-space-none`, `--bh-space-sm-6`, `--bh-space-xl-12`, `--bh-space-xs-4`, `--bh-space-xxs-2`, `--bh-space-xxxs-1`, `--bh-text-base-letter-spacing`, `--bh-text-body-lg-semibold-font-size`, `--bh-text-body-lg-semibold-line-height`, `--bh-text-body-md-medium-font-size`, `--bh-text-body-md-medium-line-height`, `--bh-text-body-md-regular-font-size`, `--bh-text-body-md-regular-line-height`, `--bh-text-body-sm-medium-font-size`, `--bh-text-body-sm-medium-line-height`, `--bh-text-body-sm-regular-font-size`, `--bh-text-body-sm-regular-line-height`, `--bh-text-body-xs-regular-font-size`, `--bh-text-body-xs-regular-line-height`, `--bh-underline-offset-default`, `--shadow-component-default`, `--shadow-xs` |
+<!-- registry-contract:end -->

package/docs/design-system/components/hover-card.md

@@ -0,0 +1,61 @@
+# Hover Card
+
+Hover Card wraps Radix HoverCard for rich preview content on hover and focus.
+
+## API
+
+```tsx
+<HoverCard>
+  <HoverCardTrigger>Workspace profile</HoverCardTrigger>
+  <HoverCardContent>Preview content</HoverCardContent>
+</HoverCard>
+```
+
+| Part | Purpose |
+| --- | --- |
+| `HoverCard`, `HoverCardTrigger`, `HoverCardPortal` | Radix shell |
+| `HoverCardContent` | tokenized preview surface |
+
+## Token Contract
+
+Hover Card uses Banhaten raised background, popover shadow, radius, spacing, and content tokens.
+
+## RTL
+
+Content inherits direction and uses logical text alignment.
+
+## Accessibility
+
+Radix manages hover/focus timing and content relationships.
+
+## Install
+
+```bash
+npx banhaten add hover-card
+```
+
+## Examples
+
+Primary registry example: `examples/hover-card-demo.tsx`.
+
+Open the live component page or run `npx banhaten docs hover-card` to inspect source files, install command, and examples.
+
+## RTL Rules
+
+- `inheritsDirection`: true
+- `textDirection`: Content inherits direction and uses logical text alignment.
+
+<!-- registry-contract:start -->
+## Registry Contract
+
+This table is generated from `registry/index.json`; edit the component-owned source under `registry/catalog/components/`, not this table or the compiled index.
+`supportedExports` is the exhaustive runtime import contract grouped by source module. `parts` is an ordered, non-exhaustive anatomy list.
+
+| Field | Values |
+| --- | --- |
+| `supportedExports` | `components/hover-card.tsx: HoverCard, HoverCardContent, HoverCardPortal, HoverCardTrigger` |
+| `parts` | `HoverCard`, `HoverCardTrigger`, `HoverCardContent`, `HoverCardPortal` |
+| `registryDependencies` | None |
+| `features` | `hover preview`, `focus preview`, `open delay`, `close delay` |
+| `tokens` | `--bh-bg-raised`, `--bh-content-default`, `--bh-radius-2xl-12`, `--bh-space-18xl-320`, `--bh-space-3xl-16`, `--bh-space-md-8`, `--bh-z-popover`, `--shadow-popover` |
+<!-- registry-contract:end -->

package/docs/design-system/components/icons.md

@@ -0,0 +1,48 @@
+# Icons
+
+Icons is an expanded-tier explorer for reviewing open-source icon packs, semantic mappings, shortlist comparisons, and Iconify catalog options.
+
+## API
+
+```tsx
+<IconExplorer />
+```
+
+| Feature | Notes |
+| --- | --- |
+| Icon pack review | compares candidate open-source packs |
+| Semantic mapping | maps product concepts to icon candidates |
+| Shortlist comparison | supports side-by-side review |
+| Iconify inspection | loads Iconify catalog data at runtime |
+
+## Runtime
+
+The explorer may load `https://code.iconify.design/iconify-icon/3.0.0/iconify-icon.min.js` and query `https://api.iconify.design`.
+
+## Token Contract
+
+The explorer uses expanded-tier CSS plus Banhaten surface, typography, border, spacing, focus, and content tokens. Product components should still use their local icon contracts instead of depending on this explorer.
+
+## RTL
+
+Explorer layout should inherit page direction for navigation, labels, and comparison rows. Icon glyphs themselves should only mirror when they are directional.
+
+## Accessibility
+
+Icon candidates must be reviewed for accessible usage. Decorative icons should be hidden with `aria-hidden`; actionable icon-only controls need clear accessible names.
+
+## Install
+
+```bash
+npx banhaten add icons
+```
+
+## Examples
+
+Primary registry example: `examples/expanded/icons-demo.tsx`.
+
+Open the live component page or run `npx banhaten docs icons` to inspect source files, install command, and examples.
+
+## RTL Rules
+
+This component has no special RTL contract beyond inherited document direction and logical spacing.

package/docs/design-system/components/input-group.md

@@ -0,0 +1,73 @@
+# Input Group
+
+Input Group provides a tokenized shell for text inputs with protocol add-ons, prefixes, suffixes, and inline actions.
+
+## API
+
+```tsx
+<InputGroup>
+  <InputGroupAddon>https://</InputGroupAddon>
+  <InputGroupInput aria-label="Workspace URL" />
+  <InputGroupButton>Save</InputGroupButton>
+</InputGroup>
+```
+
+| Part | Purpose |
+| --- | --- |
+| `InputGroup` | shared input shell |
+| `InputGroupAddon` | prefix or suffix content |
+| `InputGroupInput` | native input |
+| `InputGroupButton` | inline action |
+
+| Prop | Values |
+| --- | --- |
+| `size` | `md`, `lg` |
+| `variant` | `default`, `soft` |
+| `state` | `default`, `error` |
+
+## Token Contract
+
+Input Group reuses Banhaten input width, height, radius, border, shadow, typography, and focus tokens.
+
+## RTL
+
+Use logical add-on order. Border placement uses logical inline sides.
+
+## Accessibility
+
+Give `InputGroupInput` an accessible label through `aria-label`, `aria-labelledby`, or a surrounding Field.
+
+## Install
+
+```bash
+npx banhaten add input-group
+```
+
+## Examples
+
+Primary registry example: `examples/input-group-demo.tsx`.
+
+Open the live component page or run `npx banhaten docs input-group` to inspect source files, install command, and examples.
+
+## RTL Rules
+
+- `inheritsDirection`: true
+- `spacing`: Add-ons and input segments use logical borders and inherited direction.
+- `textDirection`: Input text uses text-start so mixed Arabic and English values align naturally.
+
+<!-- registry-contract:start -->
+## Registry Contract
+
+This table is generated from `registry/index.json`; edit the component-owned source under `registry/catalog/components/`, not this table or the compiled index.
+`supportedExports` is the exhaustive runtime import contract grouped by source module. `parts` is an ordered, non-exhaustive anatomy list.
+
+| Field | Values |
+| --- | --- |
+| `supportedExports` | `components/input-group.tsx: InputGroup, InputGroupAddon, InputGroupButton, InputGroupInput, inputGroupVariants` |
+| `parts` | `InputGroup`, `InputGroupInput`, `InputGroupAddon`, `InputGroupButton` |
+| `registryDependencies` | `button` |
+| `sizes` | `md`, `lg` |
+| `states` | `default`, `error` |
+| `tokens` | `--bh-border-danger-strong`, `--bh-border-disabled`, `--bh-border-input`, `--bh-border-width-default`, `--bh-content-default`, `--bh-content-disabled`, `--bh-content-muted`, `--bh-content-subtle`, `--bh-input-border`, `--bh-input-lg-height`, `--bh-input-lg-padding-x`, `--bh-input-md-height`, `--bh-input-radius`, `--bh-input-width`, `--bh-interactive-input-default`, `--bh-interactive-input-disabled`, `--bh-interactive-input-soft`, `--bh-space-sm-6`, `--bh-space-xl-12`, `--bh-space-xs-4`, `--bh-text-body-md-regular-font-size`, `--bh-text-body-md-regular-font-weight`, `--bh-text-body-md-regular-letter-spacing`, `--bh-text-body-md-regular-line-height`, `--bh-text-body-sm-medium-font-size`, `--bh-text-body-sm-medium-font-weight`, `--bh-text-body-sm-medium-letter-spacing`, `--bh-text-body-sm-medium-line-height`, `--shadow-component-default`, `--shadow-input`, `--shadow-input-focus-ring` |
+| `variants` | `default`, `soft` |
+<!-- registry-contract:end -->

package/docs/design-system/components/input-otp.md

@@ -0,0 +1,73 @@
+# Input OTP
+
+Input OTP captures one-time passcodes and short verification codes. It reuses the Banhaten Input surface and typography while adding grouped slots, paste distribution, hidden form value, masking, custom length, and RTL-aware keyboard navigation.
+
+## API
+
+```tsx
+<InputOTP
+  label="Verification code"
+  length={6}
+  name="code"
+  onValueChange={setCode}
+/>
+```
+
+| Prop | Values |
+| --- | --- |
+| `value`, `defaultValue` | controlled or uncontrolled string |
+| `length` | slot count |
+| `groupPattern` | array of slot group sizes |
+| `masked` | `boolean` |
+| `variant` | `default`, `soft` |
+| `size` | `md`, `lg` |
+| `state` | `default`, `filled`, `error`, `disabled` |
+
+## Token Contract
+
+Input OTP uses Input field tokens for surfaces, typography, focus, border, error, helper text, labels, slot gaps, and disabled states.
+
+## RTL
+
+Slot groups inherit direction. Arrow navigation mirrors in RTL so visual previous and next follow the rendered direction.
+
+## Accessibility
+
+Provide a clear label and helper text describing how many digits are expected. The hidden form value lets the component participate in standard form submission.
+
+## Install
+
+```bash
+npx banhaten add input-otp
+```
+
+## Examples
+
+Primary registry example: `examples/input-otp-demo.tsx`.
+
+Open the live component page or run `npx banhaten docs input-otp` to inspect source files, install command, and examples.
+
+## RTL Rules
+
+- `inheritsDirection`: true
+- `keyboard`: Arrow navigation mirrors for RTL: visual previous and next follow the inherited direction.
+- `spacing`: Slot groups, separators, labels, and helper text use inherited direction plus Input spacing tokens.
+- `composition`: Each slot reuses the Banhaten Input surface and control typography instead of a separate field style.
+
+<!-- registry-contract:start -->
+## Registry Contract
+
+This table is generated from `registry/index.json`; edit the component-owned source under `registry/catalog/components/`, not this table or the compiled index.
+`supportedExports` is the exhaustive runtime import contract grouped by source module. `parts` is an ordered, non-exhaustive anatomy list.
+
+| Field | Values |
+| --- | --- |
+| `supportedExports` | `components/input-otp.tsx: InputOTP, InputOTPSeparator` |
+| `parts` | `InputOTP`, `InputOTPSeparator` |
+| `registryDependencies` | `input` |
+| `features` | `controlled value`, `uncontrolled value`, `paste distribution`, `hidden form value`, `masked slots`, `custom length`, `custom grouping` |
+| `sizes` | `md`, `lg` |
+| `states` | `default`, `filled`, `error`, `disabled` |
+| `tokens` | `--bh-bg-brand-soft`, `--bh-border-default`, `--bh-content-danger-default`, `--bh-content-default`, `--bh-content-muted`, `--bh-content-subtle`, `--bh-input-helper-gap`, `--bh-input-inline-gap`, `--bh-input-label-gap`, `--bh-input-lg-height`, `--bh-input-otp-group-gap`, `--bh-input-otp-separator-height`, `--bh-input-otp-separator-width`, `--bh-input-otp-slot-comfortable-width`, `--bh-input-otp-slot-gap`, `--bh-input-otp-slot-lg-width`, `--bh-input-otp-slot-md-width`, `--bh-input-otp-width`, `--bh-input-width`, `--bh-radius-full`, `--bh-space-none`, `--bh-text-body-md-medium-font-weight`, `--bh-text-body-sm-medium-font-size`, `--bh-text-body-sm-medium-font-weight`, `--bh-text-body-sm-medium-letter-spacing`, `--bh-text-body-sm-medium-line-height`, `--bh-text-body-xs-regular-font-size`, `--bh-text-body-xs-regular-font-weight`, `--bh-text-body-xs-regular-letter-spacing`, `--bh-text-body-xs-regular-line-height` |
+| `variants` | `default`, `soft` |
+<!-- registry-contract:end -->