banhaten 0.1.2 → 0.2.0

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

@@ -0,0 +1,59 @@
+# Catalog Components
+
+Catalog Components is an expanded-tier showcase bundle for catalog-style product pages. It brings together breadcrumbs, catalog-only dividers, catalog tag previews, file upload states, and table previews.
+
+## API
+
+```tsx
+<CatalogComponentsShowcase dir="ltr" />
+```
+
+| Included part | Source |
+| --- | --- |
+| `Breadcrumbs` | expanded breadcrumbs component |
+| `CatalogContentDivider`, `CatalogDivider` | catalog divider visuals |
+| `Tag` | core tag component, previewed in the showcase |
+| `FileUpload` | expanded upload states |
+| `Table` | expanded table preview |
+
+## Token Contract
+
+The bundle uses expanded-tier CSS files plus Banhaten button, surface, border, spacing, typography, tag, upload, and table tokens. Treat this as a composition bundle, not a new primitive token namespace.
+
+## RTL
+
+Catalog examples include LTR and RTL states through the child components. Breadcrumbs, upload rows, table content, and tags should inherit direction from the wrapper.
+
+## Accessibility
+
+Use the individual child component docs for production semantics. This page is a bundled visual reference for catalog composition and component fit.
+
+## Install
+
+```bash
+npx banhaten add catalog-components
+```
+
+## Examples
+
+Primary registry example: `examples/expanded/catalog-components-demo.tsx`.
+
+Open the live component page or run `npx banhaten docs catalog-components` to inspect source files, install command, and examples.
+
+## 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/CatalogComponentsShowcase.tsx: CatalogComponentsShowcase`, `components/expanded/CatalogDivider.tsx: CatalogContentDivider, CatalogDivider` |
+| `parts` | `CatalogContentDivider`, `CatalogDivider`, `CatalogComponentsShowcase` |
+| `registryDependencies` | `breadcrumbs`, `button`, `file-upload`, `table`, `tag` |
+| `tokens` | `--bh-bg-raised`, `--bh-border-focus`, `--bh-border-subtle`, `--bh-catalog-file-grid-max`, `--bh-catalog-file-grid-min`, `--bh-catalog-file-preview-max`, `--bh-catalog-file-preview-min`, `--bh-content-default`, `--bh-content-muted`, `--bh-content-subtle`, `--bh-control-default`, `--bh-focus-ring-width`, `--bh-font-family`, `--bh-font-weight-medium`, `--bh-font-weight-regular`, `--bh-interactive-ghost-hover`, `--bh-interactive-soft-default`, `--bh-opacity-65`, `--bh-radius-lg-8`, `--bh-space-2xl-14`, `--bh-space-3xl-16`, `--bh-space-4xl-20`, `--bh-space-5xl-24`, `--bh-space-6xl-32`, `--bh-space-lg-10`, `--bh-space-md-8`, `--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-md-font-size`, `--bh-text-body-md-line-height`, `--bh-text-body-sm-regular-line-height`, `--bh-text-body-xs-regular-font-size`, `--bh-text-heading-xs-semibold-font-size`, `--bh-text-heading-xs-semibold-font-weight`, `--bh-text-heading-xs-semibold-line-height`, `--shadow-component-default` |
+<!-- registry-contract:end -->

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

@@ -0,0 +1,58 @@
+# Chart
+
+Chart provides Recharts wrappers with Banhaten chart tokens, responsive sizing, tooltip content, and legend content.
+
+## API
+
+```tsx
+<ChartContainer config={{ revenue: { color: "var(--bh-chart-1)" } }}>
+  <LineChart data={data}>
+    <ChartTooltip content={<ChartTooltipContent />} />
+    <Line dataKey="revenue" stroke="var(--color-revenue)" />
+  </LineChart>
+</ChartContainer>
+```
+
+## Token Contract
+
+Chart adds `--bh-chart-1` through `--bh-chart-5` via the token build. `ChartContainer` maps config entries to `--color-*` variables.
+
+## RTL
+
+Chart layout depends on the Recharts configuration. Surrounding labels and legends use logical layout.
+
+## Accessibility
+
+Pair charts with text summaries or tables for critical data. Tooltips are supplemental.
+
+## Install
+
+```bash
+npx banhaten add chart
+```
+
+## Examples
+
+Primary registry example: `examples/chart-demo.tsx`.
+
+Open the live component page or run `npx banhaten docs chart` to inspect source files, install command, and examples.
+
+## RTL Rules
+
+- `inheritsDirection`: true
+- `layout`: Chart labels and legends should use logical layout; chart geometry is controlled by Recharts.
+
+<!-- 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/chart.tsx: ChartContainer, ChartLegend, ChartLegendContent, ChartTooltip, ChartTooltipContent` |
+| `parts` | `ChartContainer`, `ChartTooltip`, `ChartTooltipContent`, `ChartLegend`, `ChartLegendContent` |
+| `registryDependencies` | None |
+| `features` | `responsive container`, `tooltip content`, `legend content`, `config colors` |
+| `tokens` | `--bh-bg-neutral-subtle`, `--bh-bg-raised`, `--bh-border-subtle`, `--bh-chart-categorical-aqua`, `--bh-chart-categorical-brand`, `--bh-chart-categorical-danger`, `--bh-chart-categorical-fuchsia`, `--bh-chart-categorical-information`, `--bh-chart-categorical-purple`, `--bh-chart-categorical-success`, `--bh-chart-categorical-warning`, `--bh-content-default`, `--bh-content-muted`, `--bh-content-subtle`, `--bh-radius-full`, `--bh-radius-lg-8`, `--bh-space-17xl-288`, `--bh-space-19xl-384`, `--bh-space-3xl-16`, `--bh-space-md-8`, `--bh-space-sm-6`, `--bh-space-xl-12`, `--bh-space-xs-4`, `--bh-text-body-xs-medium-font-size`, `--bh-text-body-xs-medium-font-weight`, `--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`, `--shadow-popover` |
+<!-- registry-contract:end -->

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

@@ -0,0 +1,68 @@
+# Checkbox
+
+Checkbox is the binary selection primitive for forms, preferences, batch actions, and card-style options. It includes the base Radix checkbox control plus `CheckboxCard` for labeled option rows.
+
+## API
+
+```tsx
+<Checkbox aria-label="Accept terms" />
+
+<CheckboxCard
+  title="Email updates"
+  description="Receive product and billing notifications."
+  controlPosition="start"
+/>
+```
+
+| Prop | Values |
+| --- | --- |
+| `checked` | Radix checkbox checked state |
+| `disabled` | `boolean` |
+| `CheckboxCard.controlPosition` | `start`, `end` |
+| `CheckboxCard.state` | default, selected, disabled |
+
+## Token Contract
+
+Checkbox consumes Banhaten control size, radius, component shadow, border, background, content, interactive, disabled, and typography tokens.
+
+## RTL
+
+`CheckboxCard` uses logical start/end control placement. Labels and descriptions use tokenized body text and `dir="auto"` for mixed Arabic and English copy.
+
+## Accessibility
+
+Use native labels or `aria-label` for standalone checkboxes. Prefer `CheckboxCard` when the selection target needs title and description text.
+
+## Install
+
+```bash
+npx banhaten add checkbox
+```
+
+## Examples
+
+Primary registry example: `examples/checkbox-demo.tsx`.
+
+Open the live component page or run `npx banhaten docs checkbox` to inspect source files, install command, and examples.
+
+## RTL Rules
+
+- `inheritsDirection`: true
+- `controlPlacement`: The card uses start/end control placement so the checkbox mirrors correctly in RTL.
+- `textDirection`: Labels and descriptions use dir="auto" and tokenized body-md/body-sm typography.
+
+<!-- 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/checkbox.tsx: Checkbox, CheckboxCard, checkboxCardVariants, checkboxVariants` |
+| `parts` | `Checkbox`, `CheckboxCard` |
+| `registryDependencies` | None |
+| `cardPositions` | `start`, `end` |
+| `states` | `unchecked`, `checked`, `indeterminate`, `selected`, `disabled` |
+| `tokens` | `--bh-bg-default`, `--bh-bg-disabled`, `--bh-bg-raised`, `--bh-bg-raised-hover`, `--bh-border-brand-strong`, `--bh-border-disabled`, `--bh-border-input`, `--bh-border-subtle`, `--bh-border-width-default`, `--bh-checkbox-card-border`, `--bh-checkbox-card-border-width`, `--bh-checkbox-card-border-width-active`, `--bh-checkbox-card-border-width-current`, `--bh-checkbox-card-content-gap`, `--bh-checkbox-card-gap`, `--bh-checkbox-card-label-gap`, `--bh-checkbox-card-media-icon-size`, `--bh-checkbox-card-padding`, `--bh-checkbox-card-radius`, `--bh-checkbox-card-text-gap`, `--bh-checkbox-card-width`, `--bh-checkbox-control-border`, `--bh-checkbox-control-radius`, `--bh-checkbox-control-size`, `--bh-checkbox-icon-size`, `--bh-checkbox-root-size`, `--bh-content-default`, `--bh-content-disabled`, `--bh-content-on-color`, `--bh-content-subtle`, `--bh-icon-stroke-300`, `--bh-interactive-checkbox-default`, `--bh-interactive-checkbox-hover`, `--bh-opacity-60`, `--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-checkbox-card`, `--shadow-checkbox-card-focus`, `--shadow-checkbox-control`, `--shadow-checkbox-focus`, `--shadow-component-default` |
+<!-- registry-contract:end -->

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

@@ -0,0 +1,63 @@
+# Collapsible
+
+Collapsible wraps Radix Collapsible for disclosure sections with Banhaten trigger and content styling.
+
+## API
+
+```tsx
+<Collapsible defaultOpen>
+  <CollapsibleTrigger>Workspace details</CollapsibleTrigger>
+  <CollapsibleContent>Billing and team settings.</CollapsibleContent>
+</Collapsible>
+```
+
+| Part | Purpose |
+| --- | --- |
+| `Collapsible` | Radix root |
+| `CollapsibleTrigger` | disclosure button |
+| `CollapsibleContent` | expandable content region |
+
+## Token Contract
+
+Collapsible uses Banhaten spacing, radius, body typography, ghost hover, focus, and content tokens.
+
+## RTL
+
+The trigger and content use logical text alignment and inherit document direction.
+
+## Accessibility
+
+Radix manages expanded state, trigger attributes, and content relationships.
+
+## Install
+
+```bash
+npx banhaten add collapsible
+```
+
+## Examples
+
+Primary registry example: `examples/collapsible-demo.tsx`.
+
+Open the live component page or run `npx banhaten docs collapsible` to inspect source files, install command, and examples.
+
+## RTL Rules
+
+- `inheritsDirection`: true
+- `textAlignment`: Trigger and content use logical text alignment and inherit direction.
+- `spacing`: Icon and label spacing uses flex gap so it mirrors with document direction.
+
+<!-- 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/collapsible.tsx: Collapsible, CollapsibleContent, CollapsibleTrigger` |
+| `parts` | `Collapsible`, `CollapsibleTrigger`, `CollapsibleContent` |
+| `registryDependencies` | None |
+| `features` | `controlled state`, `uncontrolled state`, `keyboard trigger`, `RTL` |
+| `tokens` | `--bh-content-default`, `--bh-content-subtle`, `--bh-icon-stroke-200`, `--bh-interactive-ghost-hover`, `--bh-radius-lg-8`, `--bh-space-3xl-16`, `--bh-space-lg-10`, `--bh-space-md-8`, `--bh-space-xl-12`, `--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` |
+<!-- registry-contract:end -->

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

@@ -0,0 +1,75 @@
+# Command
+
+Command is a cmdk-backed command menu with search input, grouped results, keyboard navigation, shortcuts, separators, and empty state.
+
+## API
+
+```tsx
+<Command>
+  <CommandInput />
+  <CommandList>
+    <CommandEmpty>No results found.</CommandEmpty>
+    <CommandGroup heading="Pages">
+      <CommandItem value="profile">
+        Profile
+        <CommandShortcut>⌘P</CommandShortcut>
+      </CommandItem>
+    </CommandGroup>
+  </CommandList>
+</Command>
+```
+
+| Part | Purpose |
+| --- | --- |
+| `Command` | cmdk root |
+| `CommandInput` | search input |
+| `CommandList` | result list |
+| `CommandEmpty` | empty state |
+| `CommandGroup` | grouped results |
+| `CommandItem` | selectable command |
+| `CommandSeparator`, `CommandShortcut` | supporting row UI |
+
+## Token Contract
+
+Command uses Banhaten raised surface, menu shadow, border, ghost hover, body typography, muted content, and radius tokens.
+
+## RTL
+
+Command inherits direction. Labels and shortcuts use logical spacing.
+
+## Accessibility
+
+cmdk handles keyboard navigation and selection. Provide stable `value` props for dynamic items.
+
+## Install
+
+```bash
+npx banhaten add command
+```
+
+## Examples
+
+Primary registry example: `examples/command-demo.tsx`.
+
+Open the live component page or run `npx banhaten docs command` to inspect source files, install command, and examples.
+
+## RTL Rules
+
+- `inheritsDirection`: true
+- `spacing`: Command rows and shortcuts use logical spacing so shortcut placement mirrors naturally.
+- `textDirection`: Command copy inherits document direction; individual row labels can use dir="auto" when needed.
+
+<!-- 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/command.tsx: Command, CommandEmpty, CommandGroup, CommandInput, CommandItem, CommandList, CommandSeparator, CommandShortcut` |
+| `parts` | `Command`, `CommandInput`, `CommandList`, `CommandEmpty`, `CommandGroup`, `CommandItem`, `CommandSeparator`, `CommandShortcut` |
+| `registryDependencies` | None |
+| `features` | `search filtering`, `keyboard navigation`, `grouped results`, `shortcut slot`, `empty state` |
+| `tokens` | `--bh-bg-raised`, `--bh-border-subtle`, `--bh-border-width-default`, `--bh-content-default`, `--bh-content-disabled`, `--bh-content-muted`, `--bh-content-subtle`, `--bh-icon-stroke-200`, `--bh-interactive-ghost-hover`, `--bh-radius-2xl-12`, `--bh-radius-lg-8`, `--bh-space-19xl-384`, `--bh-space-3xl-16`, `--bh-space-5xl-24`, `--bh-space-8xl-48`, `--bh-space-md-8`, `--bh-space-sm-6`, `--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`, `--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`, `--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-menu` |
+<!-- registry-contract:end -->

package/docs/design-system/components/context-menu.md

@@ -0,0 +1,59 @@
+# Context Menu
+
+Context Menu wraps Radix ContextMenu for right-click actions with labels, separators, submenus, checkboxes, radios, and shortcuts.
+
+## API
+
+```tsx
+<ContextMenu>
+  <ContextMenuTrigger>Right click</ContextMenuTrigger>
+  <ContextMenuContent>
+    <ContextMenuItem>Open</ContextMenuItem>
+  </ContextMenuContent>
+</ContextMenu>
+```
+
+## Token Contract
+
+Context Menu reuses Banhaten menu width, item height, raised surface, hover, shadow, spacing, and typography tokens.
+
+## RTL
+
+Items and shortcuts use logical spacing. Directional submenu icons flip in RTL.
+
+## Accessibility
+
+Radix manages keyboard navigation, focus movement, item state, and submenu behavior.
+
+## Install
+
+```bash
+npx banhaten add context-menu
+```
+
+## Examples
+
+Primary registry example: `examples/context-menu-demo.tsx`.
+
+Open the live component page or run `npx banhaten docs context-menu` to inspect source files, install command, and examples.
+
+## RTL Rules
+
+- `inheritsDirection`: true
+- `directionalIconFlip`: Submenu chevrons flip in RTL.
+- `spacing`: Items and shortcuts use 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/context-menu.tsx: ContextMenu, ContextMenuCheckboxItem, ContextMenuContent, ContextMenuGroup, ContextMenuItem, ContextMenuLabel, ContextMenuPortal, ContextMenuRadioGroup, ContextMenuRadioItem, ContextMenuSeparator, ContextMenuShortcut, ContextMenuSub, ContextMenuSubContent, ContextMenuSubTrigger, ContextMenuTrigger` |
+| `parts` | `ContextMenu`, `ContextMenuTrigger`, `ContextMenuContent`, `ContextMenuItem`, `ContextMenuCheckboxItem`, `ContextMenuRadioItem`, `ContextMenuLabel`, `ContextMenuSeparator`, `ContextMenuShortcut`, `ContextMenuSub`, `ContextMenuSubTrigger`, `ContextMenuSubContent` |
+| `registryDependencies` | None |
+| `features` | `right click trigger`, `submenus`, `checkbox items`, `radio items`, `shortcuts` |
+| `tokens` | `--bh-bg-raised`, `--bh-border-subtle`, `--bh-border-width-default`, `--bh-content-default`, `--bh-content-disabled`, `--bh-content-muted`, `--bh-menu-item-default-height`, `--bh-menu-item-hover-bg`, `--bh-menu-width`, `--bh-radius-md-6`, `--bh-radius-xl-10`, `--bh-space-3xl-16`, `--bh-space-5xl-24`, `--bh-space-8xl-48`, `--bh-space-md-8`, `--bh-space-sm-6`, `--bh-space-xs-4`, `--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`, `--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-z-popover`, `--shadow-menu` |
+<!-- registry-contract:end -->

package/docs/design-system/components/date-picker.md

@@ -0,0 +1,97 @@
+# Date Picker
+
+Date Picker is the calendar and range-selection suite for Banhaten forms. It covers single calendars, month/year views, double calendars, preset lists, date-picker triggers, date-range pickers, open/closed states, time rows, and RTL use cases.
+
+## Install
+
+```bash
+npx banhaten add date-picker
+```
+
+## Anatomy
+
+- `Calendar`: single calendar surface with day and month/year views.
+- `RangeCalendar`: single or double range calendar with optional preset list.
+- `DatePicker`: trigger plus single-date calendar surface.
+- `DateRangePicker`: trigger plus range calendar surface.
+- `DatePickerTrigger`: standalone tokenized trigger.
+
+## Example
+
+```tsx
+import { DatePicker, DateRangePicker } from "@/components/ui/date-picker"
+
+export function Example() {
+  return (
+    <div className="grid gap-4">
+      <DatePicker defaultOpen />
+      <DateRangePicker type="double" />
+    </div>
+  )
+}
+```
+
+## Variants
+
+| API | Values |
+| --- | --- |
+| `Calendar view` | `days`, `month-year` |
+| `RangeCalendar type` | `single`, `double`, `double-with-presets` |
+| `DatePicker state` | `open`, `closed` |
+| `dir` | inherited, `ltr`, `rtl` |
+
+## RTL
+
+The trigger, calendar header, preset list, day cells, range fill, and time rows use logical spacing and borders. Range endpoints keep their visual start/end rounding in both LTR and RTL.
+
+## API
+
+Supported runtime exports: `Calendar`, `DatePicker`, `DatePickerTrigger`, `DateRangePicker`, `RangeCalendar`, `calendarSurface`, `pickerTrigger`, `addDays`, `addMonths`, `formatCalendarDate`, `formatCalendarRange`, `formatMonthTitle`, `getCalendarCells`, `getCalendarDayState`, `getCalendarKeyboardTarget`, `getNextRange`, `isAfterOrSameDay`, `isBeforeDay`, `isBeforeOrSameDay`, `isSameDay`, `isSameMonth`, `normalizeRange`, `startOfDay`, `startOfMonth`, `toCalendarDateId`.
+
+| Contract | Values |
+| --- | --- |
+| `modes` | `single-calendar`, `single-month-year`, `double-calendar`, `double-calendar-with-presets`, `single-range-calendar`, `date-picker`, `date-range-picker` |
+| `states` | `open`, `closed` |
+
+## Examples
+
+Primary registry example: `examples/date-picker-demo.tsx`.
+
+Open the live component page or run `npx banhaten docs date-picker` 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/date-picker.tsx`, `components/date-picker-state.ts`.
+
+## RTL Rules
+
+- `inheritsDirection`: true
+- `triggerLayout`: The trigger uses inherited direction so the calendar icon and value mirror naturally.
+- `calendarLayout`: Calendar headers, range presets, date cells, and time rows use logical borders, spacing, and text alignment for LTR and RTL surfaces.
+- `rangeSelection`: Range fill uses logical start/end rounding for week edges and keeps selected endpoints tokenized with brand colors.
+
+## 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/date-picker.tsx: Calendar, DatePicker, DatePickerTrigger, DateRangePicker, RangeCalendar, calendarSurface, pickerTrigger`, `components/date-picker-state.ts: addDays, addMonths, formatCalendarDate, formatCalendarRange, formatMonthTitle, getCalendarCells, getCalendarDayState, getCalendarKeyboardTarget, getNextRange, isAfterOrSameDay, isBeforeDay, isBeforeOrSameDay, isSameDay, isSameMonth, normalizeRange, startOfDay, startOfMonth, toCalendarDateId` |
+| `parts` | `Calendar`, `RangeCalendar`, `DatePicker`, `DateRangePicker`, `DatePickerTrigger` |
+| `registryDependencies` | `popover` |
+| `props.density` | `"compact" \| "default" \| "comfortable"; default "comfortable"; Aligns DatePicker and DateRangePicker triggers to the shared 32px, 36px, or 40px control contract.` |
+| `props.icon` | `React.ReactNode; default "calendar"; Uses the calendar icon by default or accepts an explicit replacement node.` |
+| `props.triggerProps` | `React.ComponentProps<"button">; default null; Forwards accessible trigger attributes such as id and aria-label without replacing DatePicker geometry.` |
+| `densities` | `compact`, `default`, `comfortable` |
+| `modes` | `single-calendar`, `single-month-year`, `double-calendar`, `double-calendar-with-presets`, `single-range-calendar`, `date-picker`, `date-range-picker` |
+| `states` | `open`, `closed` |
+| `tokens` | `--bh-bg-brand-default`, `--bh-bg-brand-subtle`, `--bh-bg-default`, `--bh-bg-default-hover`, `--bh-bg-raised`, `--bh-border-disabled`, `--bh-border-input`, `--bh-border-subtle`, `--bh-border-width-default`, `--bh-button-sm-height`, `--bh-button-xs-height`, `--bh-content-brand-default`, `--bh-content-brand-strong`, `--bh-content-default`, `--bh-content-disabled`, `--bh-content-muted`, `--bh-content-on-color`, `--bh-content-subtle`, `--bh-control-default`, `--bh-date-day-cell-height`, `--bh-date-event-dot-offset-bottom`, `--bh-date-event-dot-size`, `--bh-date-list-item-height`, `--bh-date-month-year-item-height`, `--bh-date-month-year-list-top`, `--bh-date-month-year-list-width`, `--bh-date-month-year-spacer-height`, `--bh-date-nav-button-size`, `--bh-date-nav-icon-size`, `--bh-date-picker-width`, `--bh-date-presets-width`, `--bh-date-range-month-width`, `--bh-date-range-surface-max-width`, `--bh-date-surface-border`, `--bh-date-surface-width-calendar`, `--bh-date-surface-width-picker`, `--bh-date-time-input-min-height`, `--bh-date-title-chevron-size`, `--bh-date-title-height`, `--bh-date-trigger-border`, `--bh-date-trigger-height`, `--bh-date-trigger-icon-size`, `--bh-date-trigger-shadow`, `--bh-date-trigger-width`, `--bh-icon-stroke-180`, `--bh-interactive-ghost-hover`, `--bh-interactive-input-default`, `--bh-interactive-input-disabled`, `--bh-interactive-soft-default`, `--bh-interactive-soft-hover`, `--bh-opacity-0`, `--bh-radius-2xl-12`, `--bh-radius-full`, `--bh-radius-lg-8`, `--bh-radius-md-6`, `--bh-radius-sm-4`, `--bh-space-3xl-16`, `--bh-space-5xl-24`, `--bh-space-lg-10`, `--bh-space-md-8`, `--bh-space-sm-6`, `--bh-space-xl-12`, `--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-2xs-regular-font-size`, `--bh-text-body-2xs-regular-font-weight`, `--bh-text-body-2xs-regular-letter-spacing`, `--bh-text-body-2xs-regular-line-height`, `--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-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-z-raised`, `--shadow-button-focus`, `--shadow-component-default`, `--shadow-date-month-year-list`, `--shadow-date-surface`, `--shadow-date-time-input`, `--shadow-input-focus-ring` |
+<!-- registry-contract:end -->

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

@@ -0,0 +1,117 @@
+# Divider
+
+Dividers, also called separators, separate related content without creating a new surface. `Divider` is the canonical separator primitive for plain horizontal and vertical rules.
+
+Figma reference: `Divider`, node `165:3111`.
+
+## Variants
+
+The component defines these variants:
+
+| Direction | Type |
+| --- | --- |
+| `horizontal` | `solid`, `dotted` |
+| `vertical` | `solid`, `dotted` |
+
+## API
+
+Use semantic names in code even if the Figma variant labels are title-cased.
+
+```ts
+type DividerDirection = "horizontal" | "vertical";
+type DividerType = "solid" | "dotted";
+
+type DividerProps = {
+  direction?: DividerDirection;
+  type?: DividerType;
+  decorative?: boolean;
+};
+```
+
+## Layout
+
+- Horizontal dividers render as a `1px` high rule with the Figma component length.
+- Vertical dividers render as a `1px` wide rule with the same tokenized length.
+- Dotted dividers use a 2px dash/gap rhythm from the number scale.
+- Direction does not require a separate RTL prop; plain separators are direction-neutral.
+
+## Tokens
+
+Dividers should consume existing semantic tokens:
+
+```ts
+export const dividerTokens = {
+  ruleColor: "border.subtle",
+  strokeWidth: "space.xxxs-1",
+  dash: "space.xxs-2",
+  length: "space.15xl-224",
+};
+```
+
+Do not hard-code the Figma fallback values in component code. The current Figma fallback for the rule is `rgba(55, 83, 122, 0.13)`, but the implementation should resolve through `border.subtle`.
+
+## Accessibility
+
+- Decorative divider lines should be hidden from assistive technology.
+- A standalone semantic separator may render as `<hr />` or `role="separator"` when it conveys structure.
+- Do not use the divider as the only indicator of a required grouping if the grouping needs a visible heading.
+
+## Usage
+
+```tsx
+<Divider />
+<Divider type="dotted" />
+<Divider direction="vertical" />
+<Divider decorative />
+```
+
+## Preset Impact
+
+- `default`: quiet 1px rule using `border.subtle`.
+- `rounded`: same rule weight; surrounding compositions may use softer radius tokens.
+- `sharp`: same rule weight; surrounding compositions may use square or near-square containers.
+
+## Implementation Notes
+
+- Prefer `border-top` or a 1px block rule instead of a filled rectangle.
+- Use `border-style: dashed` for the Figma dotted variant unless the platform has a distinct dotted token or renderer.
+- Compose labeled section breaks outside `Divider`; the core primitive should stay a small separator.
+
+## Install
+
+```bash
+npx banhaten add divider
+```
+
+## Examples
+
+Primary registry example: `examples/divider-demo.tsx`.
+
+Open the live component page or run `npx banhaten docs divider` 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/divider.tsx`.
+
+## RTL Rules
+
+- `inheritsDirection`: false
+- `geometry`: Direction maps to component orientation, not document text direction.
+
+<!-- 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/divider.tsx: Divider, dividerVariants` |
+| `parts` | `Divider` |
+| `registryDependencies` | None |
+| `directions` | `horizontal`, `vertical` |
+| `tokens` | `--bh-border-subtle`, `--bh-space-15xl-224`, `--bh-space-xxs-2`, `--bh-space-xxxs-1` |
+| `types` | `solid`, `dotted` |
+<!-- registry-contract:end -->