banhaten 0.3.0 → 0.5.0

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

@@ -1,60 +1,111 @@
-# Input
-
-Input is the text-entry field primitive for forms, filters, search, numeric entry, tags, shortcuts, add-ons, and action-adorned fields. It supports default and soft variants, md/lg sizing, helper and error text, and RTL-safe slot placement.
-
-## API
-
-```tsx
-<Input label="Email" placeholder="name@example.com" />
-<Input state="error" label="Amount" message="Enter a valid amount" />
-```
-
-| Prop | Type / values | Default | Notes |
-| --- | --- | --- | --- |
-| `kind` | `default`, `shortcut`, `add-on`, `inline-add-on`, `tags`, `inline-tags`, `trailing-dropdown`, `leading-dropdown`, `quantity`, `quantity-2`, `trailing-button`, `leading-button` | `default` | Selects the input composition. |
-| `variant` | `default`, `soft` | `default` | Selects the input surface. |
-| `size` | `md`, `lg` | `lg` | Selects the control height. |
-| `state` | `default`, `filled`, `error`, `disabled` | `default` | Selects the visual state. |
-| `label`, `message` | `ReactNode` | `null` | Their presence enables the corresponding text rows unless explicitly disabled. |
-| `hasLeadingIcon` | `boolean` | `false` | Set true to show the default at-sign icon. |
-| `leadingIcon` | `ReactNode \| false` | `null` | A node enables the leading slot; false always removes it. |
-| `hasInformationIcon` | `boolean` | `false` | Set true to show the default information icon. |
-| `trailingIcon` | `ReactNode \| false` | `null` | A node enables the trailing slot; false always removes it. |
-
-## Migration
-
-Input no longer adds the default at-sign or information icon when their props are omitted. Add `hasLeadingIcon` or `hasInformationIcon` to retain either previous default, or supply a custom `leadingIcon` or `trailingIcon` to enable that slot. Explicit `false` always removes the corresponding slot.
-
-## Token Contract
-
-Input consumes Banhaten field, control, typography, spacing, border, radius, content, disabled, error, and focus tokens. Add-on and button segments should use logical borders and shared field tokens.
-
-## RTL
-
-Input uses logical start/end slots and `text-start`. Labels, values, add-ons, tags, and helper text use `dir="auto"` where string copy is rendered.
-
-## Accessibility
-
-Connect labels and helper/error text through the component props when possible. Use `state="error"` with visible error copy instead of relying only on red borders.
-
-## Install
-
-```bash
-npx banhaten add input
-```
-
-## Examples
-
-Primary registry example: `examples/input-demo.tsx`.
-
-Open the live component page or run `npx banhaten docs input` to inspect source files, install command, and examples.
-
-## RTL Rules
-
-- `inheritsDirection`: true
-- `textAlignment`: Uses text-start and dir="auto" so Arabic and English labels, values, add-ons, tags, and helper text align naturally.
-- `spacing`: Uses logical start/end borders and inherited direction so leading and trailing segments mirror in RTL.
-
+# Input
+
+Input is the text-entry field primitive for forms, filters, search, numeric entry, tags, shortcuts, add-ons, and action-adorned fields. It supports default and soft variants, md/lg sizing, helper and error text, and RTL-safe slot placement.
+
+## API
+
+```tsx
+<Input label="Email" placeholder="name@example.com" />
+<Input label="Email" isRequired placeholder="name@example.com" />
+<Input state="error" label="Amount" message="Enter a valid amount" />
+```
+
+| Prop | Type / values | Default | Notes |
+| --- | --- | --- | --- |
+| `kind` | `default`, `shortcut`, `add-on`, `inline-add-on`, `tags`, `inline-tags`, `trailing-dropdown`, `leading-dropdown`, `quantity`, `quantity-2`, `trailing-button`, `leading-button` | `default` | Selects the input composition. |
+| `variant` | `default`, `soft` | `default` | Selects the input surface. |
+| `size` | `md`, `lg` | `lg` | Selects the control height. |
+| `state` | `default`, `filled`, `error`, `disabled` | `default` | Selects the visual state. |
+| `label`, `message` | `ReactNode` | `null` | Their presence enables the corresponding text rows unless explicitly disabled. |
+| `isRequired` | `boolean` | `false` | Shows the required marker and sets `aria-required="true"` without enabling native browser validation. Use the native `required` prop when constraint validation is intended. |
+| `hasLeadingIcon` | `boolean` | `false` | Set true to show the default at-sign icon. |
+| `leadingIcon` | `ReactNode \| false` | `null` | A node enables the 20px leading slot; direct SVG/image glyphs normalize to 16px. `false` removes it. |
+| `hasInformationIcon` | `boolean` | `false` | Set true to show the default information icon. |
+| `trailingIcon` | `ReactNode \| false` | `null` | A node enables the trailing slot; false always removes it. |
+| `shortcutKeys` | `readonly string[]` | `["Mod", "K"]` | For `kind="shortcut"`, renders one compact, platform-aware Shortcut chip. |
+| `shortcut` | `ReactNode` | `null` | Deprecated compact-chip content escape hatch; prefer `shortcutKeys`. |
+| `buttonProps` | `InputActionButtonProps` | `undefined` | Native button events, ref, disabled state, class name, and ARIA attributes for button and dropdown kinds. Defaults to `type="button"`. |
+| `decreaseButtonProps`, `increaseButtonProps` | `InputStepperButtonProps` | `undefined` | Native stepper-button props, excluding children and type. Override `aria-label` for localization. Calling `preventDefault()` in `onClick` cancels the step. |
+| `value`, `defaultValue`, `onChange` | Native input props | `undefined` | Quantity buttons and typing use the same `onChange` contract. Use `value` with `onChange` for controlled fields, or `defaultValue` for uncontrolled fields. |
+| `min`, `max`, `step` | Native number-input props | Native defaults | Quantity kinds always render `type="number"` and use browser stepping rules. With `step="any"`, the buttons step by one while typing remains unrestricted. |
+
+## Quantity and actions
+
+```tsx
+const [quantity, setQuantity] = React.useState("1")
+
+<Input
+  kind="quantity"
+  label="Quantity"
+  quantityLabel="Quantity"
+  min={0}
+  max={10}
+  step={1}
+  value={quantity}
+  onChange={(event) => setQuantity(event.currentTarget.value)}
+/>
+
+<Input
+  kind="trailing-button"
+  label="Search"
+  buttonLabel="Search"
+  value={query}
+  onChange={(event) => setQuery(event.currentTarget.value)}
+  buttonProps={{ onClick: () => runSearch(query) }}
+/>
+```
+
+Quantity buttons do not submit forms. They update uncontrolled values directly,
+notify `onInput` and `onChange`, and let the parent accept or reject a controlled
+change. Steps that cannot move within the bounds emit no change. `disabled`,
+`state="disabled"`, and `readOnly` disable both steppers; per-button `disabled`
+can restrict one direction.
+
+Dropdown kinds expose a trigger. Connect the popup action and its accessibility
+state through `buttonProps.onClick`, `aria-haspopup`, `aria-expanded`,
+`aria-controls`, and `ref`. For a menu library that composes its trigger with
+`asChild`, use `InputGroup` with `InputGroupButton` and the library's trigger.
+Button events bubble normally and retain button focus.
+
+## Migration
+
+Input no longer adds the default at-sign or information icon when their props are omitted. Add `hasLeadingIcon` or `hasInformationIcon` to retain either previous default, or supply a custom `leadingIcon` or `trailingIcon` to enable that slot. Explicit `false` always removes the corresponding slot.
+
+## Sizing rule
+
+Use Input without a `size` or `density` override in standard product UI. The inherited default is `lg` (36px), and it is the expected treatment for forms, search, filters, and verification flows. Use `density="compact"` only when the surrounding context is genuinely constrained, such as a dense desktop table or a compact toolbar, and apply the same semantic density to the other controls in that row. Do not reduce inputs merely to make a preview or card composition fit.
+
+## Token Contract
+
+Input consumes Banhaten field, control, typography, spacing, border, radius, content, disabled, error, and focus tokens. Its default size is `lg` (36px); shortcut Inputs use the Figma 8px inline padding, 20px icon slot, 16px glyph, and shared compact Shortcut. Add-on and button segments should use logical borders and shared field tokens.
+
+## RTL
+
+Input uses logical start/end slots and `text-start`. Labels, values, add-ons, tags, and helper text use `dir="auto"` where string copy is rendered.
+
+## Accessibility
+
+Connect labels and helper/error text through the component props when possible. `isRequired` communicates the required state to assistive technology without changing form-submission behavior; use native `required` when the browser should enforce the constraint. Use `state="error"` with visible error copy instead of relying only on red borders.
+
+## Install
+
+```bash
+npx banhaten add input
+```
+
+## Examples
+
+Primary registry example: `examples/input-demo.tsx`.
+Controlled quantity and action example: `examples/input-actions-demo.tsx`.
+
+Open the live component page or run `npx banhaten docs input` to inspect source files, install command, and examples.
+
+## RTL Rules
+
+- `inheritsDirection`: true
+- `textAlignment`: Uses text-start and dir="auto" so Arabic and English labels, values, add-ons, tags, and helper text align naturally.
+- `spacing`: Uses logical start/end borders and inherited direction so leading and trailing segments mirror in RTL.
+
 <!-- registry-contract:start -->
 ## Registry Contract
 
@@ -66,19 +117,24 @@ This table is generated from `registry/index.json`; edit the component-owned sou
 | `supportedExports` | `components/input-content.ts: getInputDefaultValue, getInputHelperText, getInputPlaceholder, getInputTags, inputCopy`, `components/input.tsx: Input, inputContent, inputControl, inputRoot, inputSurface` |
 | `parts` | `Input` |
 | `registryDependencies` | `kbd` |
+| `props.buttonProps` | `InputActionButtonProps; default null; Native button props for leading/trailing button and dropdown kinds, including onClick, keyboard handlers, ref, disabled, and ARIA attributes. Defaults to type=button; consumers supply the action or popup.` |
+| `props.decreaseButtonProps` | `InputStepperButtonProps; default null; Native props for the decrease button, excluding children and type. Supports localized aria-label, ref, and onClick; preventDefault cancels the step. Field disabled and readOnly always disable the stepper.` |
+| `props.increaseButtonProps` | `InputStepperButtonProps; default null; Native props for the increase button, excluding children and type. Supports localized aria-label, ref, and onClick; preventDefault cancels the step. Field disabled and readOnly always disable the stepper.` |
+| `props.onChange` | `React.ChangeEventHandler<HTMLInputElement>; default null; Receives native input changes from typing and quantity buttons. Quantity kinds use type=number, respect min/max/step, and support controlled value or uncontrolled defaultValue. step=any uses one-unit button increments.` |
 | `props.density` | `"compact" \| "default" \| "comfortable"; default "default"; Preferred cross-component sizing contract. Overrides the legacy size prop with 32px, 36px, or 40px control heights.` |
 | `props.hasLeadingIcon` | `boolean; default false; Deprecated compatibility alias for showAtSign.` |
-| `props.leadingIcon` | `React.ReactNode \| false; default null; Supplies and enables a custom leading icon; false always removes the leading slot.` |
+| `props.leadingIcon` | `React.ReactNode \| false; default null; Supplies and enables a custom 16px glyph inside the shared 20px leading slot; false always removes the slot.` |
 | `props.hasInformationIcon` | `boolean; default false; Deprecated compatibility alias for showInfo.` |
+| `props.isRequired` | `boolean; default false; Shows the required marker and exposes aria-required on the input without enabling native browser validation. Use the native required prop when constraint validation is intended.` |
 | `props.trailingIcon` | `React.ReactNode \| false; default null; Supplies and enables a custom trailing icon; false always removes the information slot.` |
 | `props.showAtSign` | `boolean; default false; Explicitly shows the semantic at-sign affordance when no leadingIcon is supplied.` |
 | `props.showInfo` | `boolean; default false; Explicitly shows the semantic information affordance when no trailingIcon is supplied.` |
-| `props.shortcutKeys` | `readonly string[]; default "Mod,K"; Renders the shortcut kind with shared Kbd keycaps. Use Mod for a platform-aware primary modifier.` |
-| `props.shortcut` | `React.ReactNode; default null; Deprecated single-keycap escape hatch. Prefer shortcutKeys for a structured shortcut chord.` |
+| `props.shortcutKeys` | `readonly string[]; default "Mod,K"; Renders the shortcut kind as one compact platform-aware Shortcut chip. Use Mod for the primary modifier.` |
+| `props.shortcut` | `React.ReactNode; default null; Deprecated compact-chip content escape hatch. Prefer shortcutKeys for a structured platform-aware chord.` |
 | `densities` | `compact`, `default`, `comfortable` |
 | `kinds` | `default`, `shortcut`, `add-on`, `inline-add-on`, `tags`, `inline-tags`, `trailing-dropdown`, `leading-dropdown`, `quantity`, `quantity-2`, `trailing-button`, `leading-button` |
 | `sizes` | `md`, `lg`, `comfortable` |
 | `states` | `default`, `filled`, `error`, `disabled` |
-| `tokens` | `--bh-border-danger-strong`, `--bh-border-default`, `--bh-border-disabled`, `--bh-border-input`, `--bh-border-width-default`, `--bh-content-danger-default`, `--bh-content-default`, `--bh-content-disabled`, `--bh-content-muted`, `--bh-content-subtle`, `--bh-control-md`, `--bh-icon-stroke-225`, `--bh-input-border`, `--bh-input-chevron-size`, `--bh-input-comfortable-height`, `--bh-input-comfortable-padding-x`, `--bh-input-content-gap`, `--bh-input-helper-gap`, `--bh-input-icon-size`, `--bh-input-info-icon-size`, `--bh-input-inline-gap`, `--bh-input-inline-tags-gap`, `--bh-input-label-gap`, `--bh-input-lg-height`, `--bh-input-lg-padding-x`, `--bh-input-md-height`, `--bh-input-md-padding-x`, `--bh-input-radius`, `--bh-input-segment-gap`, `--bh-input-segment-padding-x`, `--bh-input-stepper-icon-size`, `--bh-input-stepper-width`, `--bh-input-tag-height`, `--bh-input-tag-padding-x`, `--bh-input-width`, `--bh-interactive-input-default`, `--bh-interactive-input-disabled`, `--bh-interactive-input-soft`, `--bh-interactive-input-soft-disabled`, `--bh-interactive-secondary-default`, `--bh-interactive-secondary-disabled`, `--bh-interactive-secondary-hover`, `--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`, `--bh-text-body-xs-medium-font-size`, `--bh-text-body-xs-medium-font-weight`, `--bh-text-body-xs-medium-letter-spacing`, `--bh-text-body-xs-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`, `--bh-z-raised`, `--shadow-component-default`, `--shadow-input`, `--shadow-input-disabled-overlay`, `--shadow-input-focus-overlay`, `--shadow-input-focus-ring`, `--shadow-input-focus-surface`, `--shadow-input-overlay`, `--shadow-input-surface` |
+| `tokens` | `--bh-border-danger-strong`, `--bh-border-default`, `--bh-border-disabled`, `--bh-border-input`, `--bh-border-width-default`, `--bh-content-danger-default`, `--bh-content-default`, `--bh-content-disabled`, `--bh-content-muted`, `--bh-content-subtle`, `--bh-control-md`, `--bh-icon-stroke-225`, `--bh-input-border`, `--bh-input-chevron-size`, `--bh-input-comfortable-height`, `--bh-input-comfortable-padding-x`, `--bh-input-content-gap`, `--bh-input-helper-gap`, `--bh-input-icon-size`, `--bh-input-icon-slot-size`, `--bh-input-info-icon-size`, `--bh-input-inline-gap`, `--bh-input-inline-tags-gap`, `--bh-input-label-gap`, `--bh-input-lg-height`, `--bh-input-lg-padding-x`, `--bh-input-md-height`, `--bh-input-md-padding-x`, `--bh-input-radius`, `--bh-input-segment-gap`, `--bh-input-segment-padding-x`, `--bh-input-stepper-icon-size`, `--bh-input-stepper-width`, `--bh-input-tag-height`, `--bh-input-tag-padding-x`, `--bh-input-width`, `--bh-interactive-input-default`, `--bh-interactive-input-disabled`, `--bh-interactive-input-soft`, `--bh-interactive-input-soft-disabled`, `--bh-interactive-secondary-default`, `--bh-interactive-secondary-disabled`, `--bh-interactive-secondary-hover`, `--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`, `--bh-text-body-xs-medium-font-size`, `--bh-text-body-xs-medium-font-weight`, `--bh-text-body-xs-medium-letter-spacing`, `--bh-text-body-xs-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`, `--bh-z-raised`, `--elevation-component-default`, `--elevation-input`, `--elevation-input-disabled-overlay`, `--elevation-input-focus-overlay`, `--elevation-input-focus-ring`, `--elevation-input-focus-surface`, `--elevation-input-overlay`, `--elevation-input-surface` |
 | `variants` | `default`, `soft` |
 <!-- registry-contract:end -->

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

@@ -1,59 +1,61 @@
-# Item
-
-Item is Banhaten’s composable row primitive for lists, settings, search results, files, and compact summaries. It keeps media, copy, and actions on one logical layout contract without embedding product behavior or placeholder content.
-
-## API
-
-```tsx
-<ItemGroup aria-label="Recent documents">
-  <Item role="listitem" variant="outline">
-    <ItemMedia><FileTextIcon aria-hidden="true" /></ItemMedia>
-    <ItemContent>
-      <ItemTitle>Launch checklist</ItemTitle>
-      <ItemDescription>Updated five minutes ago</ItemDescription>
-    </ItemContent>
-    <ItemActions>{/* real controls */}</ItemActions>
-  </Item>
-</ItemGroup>
-```
-
-Use `asChild` when the whole row should be a native link or button. Interactive controls inside `ItemActions` must retain their own accessible names.
-
-## Variants
-
-| Prop | Values |
-| --- | --- |
-| `variant` | `default`, `muted`, `outline` |
-| `size` | `sm`, `md`, `lg` |
-| `disabled` | `boolean` |
-| `ItemMedia variant` | `icon`, `avatar`, `image` |
-
-## Install
-
-```bash
-npx banhaten add item
-```
-
-## Accessibility
-
-`ItemGroup` defaults to `role="list"`; give rows `role="listitem"` when using the default non-semantic `div`. Prefer native anchors or buttons through `asChild` for interactive rows. Disabled styling maps to `aria-disabled` and does not invent click behavior.
-
-## RTL Rules
-
-- `inheritsDirection`: true
-- `layout`: media, content, and actions follow logical flex order.
-- `textDirection`: title and description use `dir="auto"`.
-
-## Token Contract
-
-Every dimension, surface, color, radius, type style, focus treatment, and transition resolves through Banhaten tokens. Covered source file: `components/item.tsx`.
-
-## Examples
-
-Primary registry example: `examples/item-demo.tsx`.
-
-Open the live component page or run `npx banhaten docs item` to inspect source files, install command, and examples.
-
+# Item
+
+Item is Banhaten’s composable row primitive for lists, settings, search results, files, and compact summaries. It keeps media, copy, and actions on one logical layout contract without embedding product behavior or placeholder content.
+
+## API
+
+```tsx
+<ItemGroup aria-label="Recent documents">
+  <Item role="listitem" variant="outline">
+    <ItemMedia><FileTextIcon aria-hidden="true" /></ItemMedia>
+    <ItemContent>
+      <ItemTitle>Launch checklist</ItemTitle>
+      <ItemDescription>Updated five minutes ago</ItemDescription>
+    </ItemContent>
+    <ItemActions>{/* real controls */}</ItemActions>
+  </Item>
+</ItemGroup>
+```
+
+Use `asChild` when the whole row should be a native link or button. Interactive controls inside `ItemActions` must retain their own accessible names.
+
+## Variants
+
+| Prop | Values |
+| --- | --- |
+| `variant` | `default`, `muted`, `outline` |
+| `size` | `sm`, `md`, `lg` |
+| `disabled` | `boolean` |
+| `ItemMedia variant` | `icon`, `avatar`, `image` |
+
+Default `ItemMedia` glyphs are 18px while their 20px layout footprint remains stable inside the media container.
+
+## Install
+
+```bash
+npx banhaten add item
+```
+
+## Accessibility
+
+`ItemGroup` defaults to `role="list"`; give rows `role="listitem"` when using the default non-semantic `div`. Prefer native anchors or buttons through `asChild` for interactive rows. Disabled styling maps to `aria-disabled` and does not invent click behavior.
+
+## RTL Rules
+
+- `inheritsDirection`: true
+- `layout`: media, content, and actions follow logical flex order.
+- `textDirection`: title and description use `dir="auto"`.
+
+## Token Contract
+
+Every dimension, surface, color, radius, type style, focus treatment, and transition resolves through Banhaten tokens. Covered source file: `components/item.tsx`.
+
+## Examples
+
+Primary registry example: `examples/item-demo.tsx`.
+
+Open the live component page or run `npx banhaten docs item` to inspect source files, install command, and examples.
+
 <!-- registry-contract:start -->
 ## Registry Contract
 
@@ -67,6 +69,6 @@ This table is generated from `registry/index.json`; edit the component-owned sou
 | `registryDependencies` | None |
 | `features` | `media slot`, `content slots`, `action slot`, `asChild composition`, `disabled semantics` |
 | `sizes` | `sm`, `md`, `lg` |
-| `tokens` | `--bh-bg-default`, `--bh-bg-neutral-default`, `--bh-bg-neutral-soft`, `--bh-bg-neutral-subtle`, `--bh-bg-raised`, `--bh-bg-raised-hover`, `--bh-border-subtle`, `--bh-border-width-default`, `--bh-content-default`, `--bh-content-disabled`, `--bh-content-on-color`, `--bh-content-subtle`, `--bh-interactive-ghost-hover`, `--bh-item-actions-gap`, `--bh-item-content-gap`, `--bh-item-gap`, `--bh-item-group-gap`, `--bh-item-icon-size`, `--bh-item-media-radius`, `--bh-item-media-size`, `--bh-item-min-height-lg`, `--bh-item-min-height-md`, `--bh-item-min-height-sm`, `--bh-item-padding-x`, `--bh-item-padding-y`, `--bh-item-radius`, `--bh-radius-full`, `--bh-text-body-md-medium-font-size`, `--bh-text-body-md-medium-font-weight`, `--bh-text-body-md-medium-letter-spacing`, `--bh-text-body-md-medium-line-height`, `--bh-text-body-sm-regular-font-size`, `--bh-text-body-sm-regular-font-weight`, `--bh-text-body-sm-regular-letter-spacing`, `--bh-text-body-sm-regular-line-height`, `--shadow-button-focus` |
+| `tokens` | `--bh-bg-default`, `--bh-bg-neutral-default`, `--bh-bg-neutral-soft`, `--bh-bg-neutral-subtle`, `--bh-bg-raised`, `--bh-bg-raised-hover`, `--bh-border-subtle`, `--bh-border-width-default`, `--bh-content-default`, `--bh-content-disabled`, `--bh-content-on-color`, `--bh-content-subtle`, `--bh-interactive-ghost-hover`, `--bh-item-actions-gap`, `--bh-item-content-gap`, `--bh-item-gap`, `--bh-item-group-gap`, `--bh-item-icon-size`, `--bh-item-icon-slot-size`, `--bh-item-media-radius`, `--bh-item-media-size`, `--bh-item-min-height-lg`, `--bh-item-min-height-md`, `--bh-item-min-height-sm`, `--bh-item-padding-x`, `--bh-item-padding-y`, `--bh-item-radius`, `--bh-radius-full`, `--bh-text-body-md-medium-font-size`, `--bh-text-body-md-medium-font-weight`, `--bh-text-body-md-medium-letter-spacing`, `--bh-text-body-md-medium-line-height`, `--bh-text-body-sm-regular-font-size`, `--bh-text-body-sm-regular-font-weight`, `--bh-text-body-sm-regular-letter-spacing`, `--bh-text-body-sm-regular-line-height`, `--elevation-button-focus` |
 | `variants` | `default`, `muted`, `outline` |
 <!-- registry-contract:end -->

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

@@ -1,48 +1,52 @@
-# Kbd
-
-Kbd renders compact keyboard hints for shortcuts, command rows, and form help text.
-
-## API
-
-```tsx
-<Kbd>⌘</Kbd>
-<Kbd>K</Kbd>
-<Kbd size="md">Shift</Kbd>
-```
-
-| Prop | Values |
-| --- | --- |
-| `size` | `sm`, `md` |
-
-## Token Contract
-
-Kbd uses Banhaten border, soft interactive background, radius, body-xs typography, and button shadow tokens.
-
-## RTL
-
-Kbd is direction-neutral. Use surrounding text direction for shortcut descriptions.
-
-## Accessibility
-
-Use Kbd as supporting text, not as the only label for an action.
-
-## Install
-
-```bash
-npx banhaten add kbd
-```
-
-## Examples
-
-Primary registry example: `examples/kbd-demo.tsx`.
-
-Open the live component page or run `npx banhaten docs kbd` to inspect source files, install command, and examples.
-
-## RTL Rules
-
-- `inheritsDirection`: false
-- `semantics`: Kbd is direction-neutral and should be paired with surrounding text labels.
-
+# Kbd
+
+Kbd renders physical keyboard keys. Shortcut renders a compact combined hint for Inputs and constrained action rows, while KbdShortcut renders each physical key on its own surface.
+
+## API
+
+```tsx
+<Shortcut keys={["Mod", "K"]} />
+<KbdShortcut keys={["Mod", "K"]} />
+<Kbd>Esc</Kbd>
+<Kbd size="md">Shift</Kbd>
+```
+
+| Prop | Values |
+| --- | --- |
+| `dir` | `ltr` by default on Kbd; override only for localized non-shortcut key names |
+| `size` | `sm`, `md` |
+| `keys` | `readonly string[]`; use `Mod` for Command on Apple platforms and Control elsewhere |
+| `platform` | `auto`, `mac`, `windows`, `linux` |
+
+## Token Contract
+
+Kbd uses Banhaten border, soft interactive background, radius, body-xs typography, and button elevation tokens. Shortcut uses the Figma compact contract: 20px height/minimum width, 4px inline padding and radius, body-2xs medium typography, and no keycap elevation.
+
+## RTL
+
+Kbd defaults to `dir="ltr"` so physical modifiers and keys keep their canonical order inside RTL interfaces. Surrounding shortcut descriptions retain their own text direction; pass an explicit `dir` only for localized, non-shortcut key names.
+
+## Accessibility
+
+Use Kbd as supporting text, not as the only label for an action.
+
+## Install
+
+```bash
+npx banhaten add kbd
+```
+
+## Examples
+
+Primary registry example: `examples/kbd-demo.tsx`.
+
+Open the live component page or run `npx banhaten docs kbd` to inspect source files, install command, and examples.
+
+## RTL Rules
+
+- `inheritsDirection`: false
+- `semantics`: Kbd defaults to dir="ltr" so physical key order stays stable, while surrounding shortcut descriptions keep their own text direction.
+
 <!-- registry-contract:start -->
 ## Registry Contract
 
@@ -51,12 +55,13 @@ This table is generated from `registry/index.json`; edit the component-owned sou
 
 | Field | Values |
 | --- | --- |
-| `supportedExports` | `components/kbd.tsx: Kbd, KbdShortcut, kbdVariants` |
-| `parts` | `Kbd`, `KbdShortcut` |
+| `supportedExports` | `components/kbd.tsx: Kbd, KbdShortcut, Shortcut, kbdVariants, shortcutVariants` |
+| `parts` | `Kbd`, `KbdShortcut`, `Shortcut` |
 | `registryDependencies` | None |
-| `props.keys` | `readonly string[]; default null; Required by KbdShortcut. Each entry renders as its own keycap; use Mod for the platform primary modifier.` |
+| `props.dir` | `"ltr" \| "rtl" \| "auto"; default "ltr"; Keeps physical key and modifier order stable inside RTL interfaces. Override only for localized non-shortcut key names.` |
+| `props.keys` | `readonly string[]; default null; Used by KbdShortcut and Shortcut. Use Mod for the platform primary modifier; KbdShortcut separates keys while Shortcut combines them.` |
 | `props.platform` | `"auto" \| "mac" \| "windows" \| "linux"; default "auto"; Resolves Mod to Command on Apple platforms and Control elsewhere.` |
 | `props.disabled` | `boolean; default false; Uses disabled border, surface, content, and shadow tokens for shortcuts inside disabled controls.` |
 | `sizes` | `sm`, `md` |
-| `tokens` | `--bh-border-default`, `--bh-border-disabled`, `--bh-content-disabled`, `--bh-content-subtle`, `--bh-font-family`, `--bh-interactive-soft-default`, `--bh-interactive-soft-disabled`, `--bh-radius-md-6`, `--bh-space-5xl-24`, `--bh-space-6xl-32`, `--bh-space-md-8`, `--bh-space-sm-6`, `--bh-space-xs-4`, `--bh-space-xxs-2`, `--bh-text-body-xs-medium-font-size`, `--bh-text-body-xs-medium-font-weight`, `--bh-text-body-xs-medium-letter-spacing`, `--bh-text-body-xs-medium-line-height`, `--shadow-button-soft` |
+| `tokens` | `--bh-border-default`, `--bh-border-disabled`, `--bh-content-disabled`, `--bh-content-subtle`, `--bh-font-family`, `--bh-interactive-soft-default`, `--bh-interactive-soft-disabled`, `--bh-radius-md-6`, `--bh-radius-sm-4`, `--bh-space-4xl-20`, `--bh-space-5xl-24`, `--bh-space-6xl-32`, `--bh-space-md-8`, `--bh-space-sm-6`, `--bh-space-xs-4`, `--bh-space-xxs-2`, `--bh-text-body-2xs-medium-font-size`, `--bh-text-body-2xs-medium-font-weight`, `--bh-text-body-2xs-medium-letter-spacing`, `--bh-text-body-2xs-medium-line-height`, `--bh-text-body-xs-medium-font-size`, `--bh-text-body-xs-medium-font-weight`, `--bh-text-body-xs-medium-letter-spacing`, `--bh-text-body-xs-medium-line-height`, `--elevation-button-soft` |
 <!-- registry-contract:end -->

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

@@ -1,52 +1,52 @@
-# Label
-
-Label renders accessible control labels with Banhaten typography, required markers, optional text, tone variants, and RTL-safe copy. It is backed by Radix Label.
-
-## API
-
-```tsx
-<Label htmlFor="email" required>
-  Email address
-</Label>
-```
-
-| Prop | Values |
-| --- | --- |
-| `htmlFor` | target control id |
-| `tone` | `default`, `subtle`, `danger` |
-| `required` | `boolean` |
-| `optionalText` | `ReactNode` |
-
-## Token Contract
-
-Label consumes Banhaten body-sm, body-xs, content, danger, spacing, and disabled-state tokens.
-
-## RTL
-
-Label uses logical inline spacing and `dir="auto"` for label and optional text.
-
-## Accessibility
-
-Use `htmlFor` for native controls. For complete form rows with description and error text, use `Field`.
-
-## Install
-
-```bash
-npx banhaten add label
-```
-
-## Examples
-
-Primary registry example: `examples/label-demo.tsx`.
-
-Open the live component page or run `npx banhaten docs label` to inspect source files, install command, and examples.
-
-## RTL Rules
-
-- `inheritsDirection`: true
-- `textDirection`: Label and optional text use dir="auto" so Arabic and English labels resolve naturally.
-- `spacing`: Uses logical inline spacing between label text, required marker, and optional text.
-
+# Label
+
+Label renders accessible control labels with Banhaten typography, required markers, optional text, tone variants, and RTL-safe copy. It is backed by Radix Label.
+
+## API
+
+```tsx
+<Label htmlFor="email" required>
+  Email address
+</Label>
+```
+
+| Prop | Values |
+| --- | --- |
+| `htmlFor` | target control id |
+| `tone` | `default`, `subtle`, `danger` |
+| `required` | `boolean` |
+| `optionalText` | `ReactNode` |
+
+## Token Contract
+
+Label consumes Banhaten body-sm, body-xs, content, danger, spacing, and disabled-state tokens.
+
+## RTL
+
+Label uses logical inline spacing and `dir="auto"` for label and optional text.
+
+## Accessibility
+
+Use `htmlFor` for native controls. For complete form rows with description and error text, use `Field`.
+
+## Install
+
+```bash
+npx banhaten add label
+```
+
+## Examples
+
+Primary registry example: `examples/label-demo.tsx`.
+
+Open the live component page or run `npx banhaten docs label` to inspect source files, install command, and examples.
+
+## RTL Rules
+
+- `inheritsDirection`: true
+- `textDirection`: Label and optional text use dir="auto" so Arabic and English labels resolve naturally.
+- `spacing`: Uses logical inline spacing between label text, required marker, and optional text.
+
 <!-- registry-contract:start -->
 ## Registry Contract