banhaten 0.4.0 → 0.5.0

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

@@ -1,89 +1,92 @@
-# Toolbar
-
-Toolbar is the token-built implementation of the Figma `Filter Toolbar` component set. It supports eight filter/action layouts, desktop and mobile wrapping, and inherited LTR/RTL direction.
-
-## Install
-
-```bash
-npx banhaten add toolbar
-```
-
-## Anatomy
-
-- `Toolbar`: root layout surface with `inline`, `split`, `stack`, and `wrap` modes.
-- `ToolbarSection`: grouped start, end, wrapped, or stacked control regions.
-- `ToolbarSearch`: tokenized search input using Banhaten input height, radius, typography, and focus ring.
-- `ToolbarSelect`: button-backed filter trigger using select/input tokens.
-- `ToolbarButton`: toolbar action button built with the same Slot and text-label construction as Button.
-- `ToolbarIconButton`, `ToolbarFilterButton`, `ToolbarMoreButton`: icon action helpers.
-- `ToolbarBadge`: selected-count or applied-filter metadata.
-- `ToolbarText` and `ToolbarSpacer`: supporting label and layout slots.
-
-## Example
-
-```tsx
-import {
-  Toolbar,
-  ToolbarButton,
-  ToolbarFilterButton,
-  ToolbarMoreButton,
-  ToolbarSearch,
-  ToolbarSection,
-  ToolbarSelect,
-} from "@/components/ui/toolbar"
-
-export function Example() {
-  return (
-    <Toolbar layout="split" wrap>
-      <ToolbarSection grow wrap>
-        <ToolbarSearch aria-label="Search objects" />
-        <ToolbarSelect value="Status" />
-        <ToolbarSelect value="Owner" />
-        <ToolbarFilterButton />
-      </ToolbarSection>
-      <ToolbarSection align="end" wrap>
-        <ToolbarMoreButton />
-        <ToolbarButton variant="soft">Export</ToolbarButton>
-        <ToolbarButton>Create Object</ToolbarButton>
-      </ToolbarSection>
-    </Toolbar>
-  )
-}
-```
-
-## Token Contract
-
-Toolbar styling is derived from the existing control tokens: `--bh-input-lg-height`, `--bh-input-radius`, `--bh-input-width`, `--bh-select-width`, `--bh-space-xl-12`, `--bh-space-3xl-16`, `--bh-control-default`, input/select/button shadows, and semantic content/interactive tokens.
-
-## RTL
-
-Set `dir="rtl"` on `Toolbar` or inherit it from the document. Sections, fields, button labels, badges, and search text use logical spacing and `dir="auto"` for mixed-language labels.
-
-## API
-
-Supported runtime exports: `Toolbar`, `ToolbarBadge`, `ToolbarButton`, `ToolbarFilterButton`, `ToolbarIconButton`, `ToolbarMoreButton`, `ToolbarSearch`, `ToolbarSection`, `ToolbarSelect`, `ToolbarSpacer`, `ToolbarText`, `toolbarBadgeVariants`, `toolbarButtonVariants`, `toolbarSearchVariants`, `toolbarSectionVariants`, `toolbarSelectVariants`, `toolbarVariants`.
-
-| Contract | Values |
-| --- | --- |
-| `styles` | `filter-fields`, `filter-actions`, `selection-actions`, `grouped-fields`, `field-grid`, `inline-search`, `filter-chips`, `saved-segment` |
-| `layouts` | `inline`, `split`, `stack`, `wrap` |
-
-## Examples
-
-Primary registry example: `examples/toolbar-demo.tsx`.
-
-Open the live component page or run `npx banhaten docs toolbar` to inspect source files, install command, and examples.
-
-## RTL Rules
-
-- `inheritsDirection`: true
-- `textAlignment`: Uses logical section layout and dir="auto" labels so mixed English and Arabic filter text aligns naturally.
-- `spacing`: Uses tokenized flex gaps and logical icon attributes so search, fields, chips, summaries, and actions mirror without alternate APIs.
-
-## 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.
-
+# Toolbar
+
+Toolbar is the token-built implementation of the Figma `Filter Toolbar` component set. It supports eight filter/action layouts, desktop and mobile wrapping, inherited LTR/RTL direction, and layout-group semantics that preserve each control's native Tab and arrow-key behavior.
+
+## Install
+
+```bash
+npx banhaten add toolbar
+```
+
+## Anatomy
+
+- `Toolbar`: root layout surface with `inline`, `split`, `stack`, and `wrap` modes. It defaults to `role="group"`, not the composite-widget `toolbar` role.
+- `ToolbarSection`: grouped start, end, wrapped, or stacked control regions.
+- `ToolbarSearch`: tokenized search input using Banhaten input height, radius, typography, and focus ring.
+- `ToolbarSelect`: button-backed filter trigger using select/input tokens.
+- `ToolbarButton`: toolbar action button built with the same Slot and text-label construction as Button.
+- `ToolbarIconButton`, `ToolbarFilterButton`, `ToolbarMoreButton`: icon action helpers.
+- `ToolbarBadge`: selected-count or applied-filter metadata.
+- `ToolbarText` and `ToolbarSpacer`: supporting label and layout slots.
+
+## Example
+
+```tsx
+import {
+  Toolbar,
+  ToolbarButton,
+  ToolbarFilterButton,
+  ToolbarMoreButton,
+  ToolbarSearch,
+  ToolbarSection,
+  ToolbarSelect,
+} from "@/components/ui/toolbar"
+
+export function Example() {
+  return (
+    <Toolbar aria-label="Object filters and actions" layout="split" wrap>
+      <ToolbarSection grow wrap>
+        <ToolbarSearch aria-label="Search objects" />
+        <ToolbarSelect value="Status" />
+        <ToolbarSelect value="Owner" />
+        <ToolbarFilterButton />
+      </ToolbarSection>
+      <ToolbarSection align="end" wrap>
+        <ToolbarMoreButton />
+        <ToolbarButton variant="soft">Export</ToolbarButton>
+        <ToolbarButton>Create Object</ToolbarButton>
+      </ToolbarSection>
+    </Toolbar>
+  )
+}
+```
+
+## Token Contract
+
+Toolbar styling is derived from the existing control tokens: `--bh-input-lg-height`, `--bh-input-radius`, `--bh-input-width`, `--bh-select-width`, `--bh-space-xl-12`, `--bh-space-3xl-16`, `--bh-control-default`, input/select/button elevation, and semantic content/interactive tokens.
+
+## RTL
+
+Set `dir="rtl"` on `Toolbar` or inherit it from the document. Sections, fields, button labels, badges, and search text use logical spacing and `dir="auto"` for mixed-language labels.
+
+## API
+
+Supported runtime exports: `Toolbar`, `ToolbarBadge`, `ToolbarButton`, `ToolbarFilterButton`, `ToolbarIconButton`, `ToolbarMoreButton`, `ToolbarSearch`, `ToolbarSection`, `ToolbarSelect`, `ToolbarSpacer`, `ToolbarText`, `toolbarBadgeVariants`, `toolbarButtonVariants`, `toolbarSearchVariants`, `toolbarSectionVariants`, `toolbarSelectVariants`, `toolbarVariants`.
+
+| Contract | Values |
+| --- | --- |
+| `styles` | `filter-fields`, `filter-actions`, `selection-actions`, `grouped-fields`, `field-grid`, `inline-search`, `filter-chips`, `saved-segment` |
+| `layouts` | `inline`, `split`, `stack`, `wrap` |
+| `role` | Defaults to `group`; explicit overrides are forwarded. |
+
+## Examples
+
+Primary registry example: `examples/toolbar-demo.tsx`.
+
+Open the live component page or run `npx banhaten docs toolbar` to inspect source files, install command, and examples.
+
+## RTL Rules
+
+- `inheritsDirection`: true
+- `textAlignment`: Uses logical section layout and dir="auto" labels so mixed English and Arabic filter text aligns naturally.
+- `spacing`: Uses tokenized flex gaps and logical icon attributes so search, fields, chips, summaries, and actions mirror without alternate APIs.
+
+## Accessibility
+
+`Toolbar` defaults to `role="group"` because it is a flexible layout surface, not a composite widget. The root is not a tab stop, every enabled control remains in the native Tab sequence, and the component does not intercept arrow keys used by search fields, selects, or nested widgets. Give the group an accessible name when its purpose is not already clear from surrounding content.
+
+Only override the root with `role="toolbar"` when the application also implements the complete [W3C Toolbar Pattern](https://www.w3.org/WAI/ARIA/apg/patterns/toolbar/): one Tab stop into the widget, managed arrow-key focus between controls, an accessible name, and orientation behavior. The role override alone does not add that keyboard model.
+
 <!-- registry-contract:start -->
 ## Registry Contract
 
@@ -97,9 +100,11 @@ This table is generated from `registry/index.json`; edit the component-owned sou
 | `registryDependencies` | `kbd` |
 | `props.density` | `"compact" \| "default" \| "comfortable"; default "default"; Aligns Toolbar Search, Select, Text, and Button controls to the shared 32px, 36px, or 40px control contract.` |
 | `props.shortcutKeys` | `readonly string[]; default null; Adds shared, platform-aware Kbd keycaps to ToolbarSearch without rebuilding a shortcut badge locally.` |
+| `props.role` | `React.AriaRole; default "group"; Uses layout-group semantics and native Tab order by default. Applications that override this to toolbar own the complete roving-focus and arrow-key contract.` |
 | `breakpoints` | `desktop`, `mobile` |
 | `densities` | `compact`, `default`, `comfortable` |
+| `features` | `native Tab-order layout grouping` |
 | `layouts` | `inline`, `split`, `stack`, `wrap` |
 | `styles` | `filter-fields`, `filter-actions`, `selection-actions`, `grouped-fields`, `field-grid`, `inline-search`, `filter-chips`, `saved-segment` |
-| `tokens` | `--bh-bg-brand-subtle`, `--bh-bg-default-hover`, `--bh-bg-neutral-subtle`, `--bh-border-brand-strong`, `--bh-border-danger-strong`, `--bh-border-default`, `--bh-border-disabled`, `--bh-border-width-default`, `--bh-button-gap`, `--bh-button-gap-xs`, `--bh-button-icon-offset`, `--bh-button-icon-size`, `--bh-button-icon-slot-size`, `--bh-button-label-padding-x`, `--bh-button-md-height`, `--bh-button-md-padding-x`, `--bh-button-sm-height`, `--bh-button-sm-padding-x`, `--bh-button-sm-padding-y`, `--bh-button-xs-height`, `--bh-button-xs-padding-x`, `--bh-content-brand-default`, `--bh-content-default`, `--bh-content-disabled`, `--bh-content-muted`, `--bh-content-on-brand`, `--bh-content-subtle`, `--bh-control-default`, `--bh-input-comfortable-height`, `--bh-input-comfortable-padding-x`, `--bh-input-content-gap`, `--bh-input-lg-height`, `--bh-input-lg-padding-x`, `--bh-input-md-height`, `--bh-input-md-padding-x`, `--bh-input-radius`, `--bh-input-width`, `--bh-interactive-brand-default`, `--bh-interactive-brand-disabled`, `--bh-interactive-brand-hover`, `--bh-interactive-brand-pressed`, `--bh-interactive-ghost-default`, `--bh-interactive-ghost-disabled`, `--bh-interactive-ghost-hover`, `--bh-interactive-ghost-pressed`, `--bh-interactive-input-default`, `--bh-interactive-input-disabled`, `--bh-interactive-outlined-default`, `--bh-interactive-outlined-disabled`, `--bh-interactive-outlined-hover`, `--bh-interactive-outlined-pressed`, `--bh-interactive-soft-default`, `--bh-interactive-soft-disabled`, `--bh-interactive-soft-hover`, `--bh-interactive-soft-pressed`, `--bh-radius-full`, `--bh-select-icon-size`, `--bh-select-icon-slot-size`, `--bh-select-trigger-padding-x`, `--bh-select-width`, `--bh-space-19xl-384`, `--bh-space-3xl-16`, `--bh-space-5xl-24`, `--bh-space-md-8`, `--bh-space-none`, `--bh-space-xl-12`, `--bh-space-xs-4`, `--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-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-button-font-size`, `--bh-text-button-font-weight`, `--bh-text-button-letter-spacing`, `--bh-text-button-line-height`, `--shadow-button-danger-focus`, `--shadow-button-focus`, `--shadow-button-raised`, `--shadow-button-soft`, `--shadow-input`, `--shadow-input-focus-ring`, `--shadow-select-trigger` |
+| `tokens` | `--bh-bg-brand-subtle`, `--bh-bg-default-hover`, `--bh-bg-neutral-subtle`, `--bh-border-brand-strong`, `--bh-border-danger-strong`, `--bh-border-default`, `--bh-border-disabled`, `--bh-border-width-default`, `--bh-button-gap`, `--bh-button-gap-xs`, `--bh-button-icon-offset`, `--bh-button-icon-size`, `--bh-button-icon-slot-size`, `--bh-button-label-padding-x`, `--bh-button-md-height`, `--bh-button-md-padding-x`, `--bh-button-sm-height`, `--bh-button-sm-padding-x`, `--bh-button-sm-padding-y`, `--bh-button-xs-height`, `--bh-button-xs-padding-x`, `--bh-content-brand-default`, `--bh-content-default`, `--bh-content-disabled`, `--bh-content-muted`, `--bh-content-on-brand`, `--bh-content-subtle`, `--bh-control-default`, `--bh-input-comfortable-height`, `--bh-input-comfortable-padding-x`, `--bh-input-content-gap`, `--bh-input-lg-height`, `--bh-input-lg-padding-x`, `--bh-input-md-height`, `--bh-input-md-padding-x`, `--bh-input-radius`, `--bh-input-width`, `--bh-interactive-brand-default`, `--bh-interactive-brand-disabled`, `--bh-interactive-brand-hover`, `--bh-interactive-brand-pressed`, `--bh-interactive-ghost-default`, `--bh-interactive-ghost-disabled`, `--bh-interactive-ghost-hover`, `--bh-interactive-ghost-pressed`, `--bh-interactive-input-default`, `--bh-interactive-input-disabled`, `--bh-interactive-outlined-default`, `--bh-interactive-outlined-disabled`, `--bh-interactive-outlined-hover`, `--bh-interactive-outlined-pressed`, `--bh-interactive-soft-default`, `--bh-interactive-soft-disabled`, `--bh-interactive-soft-hover`, `--bh-interactive-soft-pressed`, `--bh-radius-full`, `--bh-select-icon-size`, `--bh-select-icon-slot-size`, `--bh-select-trigger-padding-x`, `--bh-select-width`, `--bh-space-19xl-384`, `--bh-space-3xl-16`, `--bh-space-5xl-24`, `--bh-space-md-8`, `--bh-space-none`, `--bh-space-xl-12`, `--bh-space-xs-4`, `--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-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-button-font-size`, `--bh-text-button-font-weight`, `--bh-text-button-letter-spacing`, `--bh-text-button-line-height`, `--elevation-button-danger-focus`, `--elevation-button-focus`, `--elevation-button-raised`, `--elevation-button-soft`, `--elevation-input`, `--elevation-input-focus-ring`, `--elevation-select-trigger` |
 <!-- registry-contract:end -->

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

@@ -1,94 +1,95 @@
-# Tooltip
-
-Tooltip is a Radix Tooltip-backed help surface matched to the Figma tooltip matrix. It supports dark and default surfaces, small and large sizes, shortcut and close slots, logical pointer positions, tokenized shadows, and RTL-safe layout.
-
-## Install
-
-```bash
-npx banhaten add tooltip
-```
-
-## Anatomy
-
-- `TooltipProvider`: shared Radix provider for delay timing.
-- `Tooltip`: root tooltip wrapper.
-- `TooltipTrigger`: trigger element.
-- `TooltipContent`: positioned surface with pointer, title, support text, shortcut, and close affordance.
-- `TooltipShortcut`: shortcut slot.
-- `TooltipCloseButton`: optional close affordance.
-
-## Example
-
-```tsx
-import {
-  Tooltip,
-  TooltipContent,
-  TooltipProvider,
-  TooltipTrigger,
-} from "@/components/ui/tooltip"
-import { Button } from "@/components/ui/button"
-
-export function Example() {
-  return (
-    <TooltipProvider>
-      <Tooltip>
-        <TooltipTrigger asChild>
-          <Button variant="secondary">Details</Button>
-        </TooltipTrigger>
-        <TooltipContent pointerPosition="top-center" size="lg">
-          More information
-        </TooltipContent>
-      </Tooltip>
-    </TooltipProvider>
-  )
-}
-```
-
-## Variants
-
-| Prop | Values |
-| --- | --- |
-| `variant` | `dark`, `default` |
-| `size` | `sm`, `lg` |
-| `pointerPosition` | `top-left`, `top-center`, `top-right`, `bottom-left`, `bottom-center`, `bottom-right`, `center-left`, `center-right`, `none` |
-| `showPointer` | `boolean` |
-
-## RTL
-
-Tooltip content uses inherited direction and `dir="auto"` text. Top and bottom left/right positions map to logical start/end in RTL, while center-left and center-right remain physical sides to match the Figma matrix.
-
-## API
-
-Supported runtime exports: `Tooltip`, `TooltipCloseButton`, `TooltipContent`, `TooltipPortal`, `TooltipProvider`, `TooltipRoot`, `TooltipShortcut`, `TooltipTrigger`, `tooltipContentVariants`.
-
-| Contract | Values |
-| --- | --- |
-| `variants` | `dark`, `default` |
-| `sizes` | `sm`, `lg` |
-
-## Examples
-
-Primary registry example: `examples/tooltip-demo.tsx`.
-
-Open the live component page or run `npx banhaten docs tooltip` 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/tooltip.tsx`.
-
-## RTL Rules
-
-- `inheritsDirection`: true
-- `spacing`: Uses inherited direction with flex layout so label/shortcut and text/close order mirror naturally.
-- `pointerPlacement`: Top and bottom left/right positions map to logical start/end in RTL. Center-left and center-right remain physical sides to match the Figma matrix.
-- `textDirection`: Labels and support text use dir="auto" for Arabic and English copy.
-
-## Accessibility
-
-This component relies on `@radix-ui/react-tooltip` for its base accessibility behavior. Keep required labels, titles, descriptions, and focusable trigger/content relationships intact when composing it.
-
+# Tooltip
+
+Tooltip is a Radix Tooltip-backed help surface matched to the Figma tooltip matrix. It supports dark and default surfaces, small and large sizes, shortcut and close slots, logical pointer positions, tokenized elevation, and RTL-safe layout.
+
+## Install
+
+```bash
+npx banhaten add tooltip
+```
+
+## Anatomy
+
+- `TooltipProvider`: shared Radix provider for delay timing.
+- `Tooltip`: root tooltip wrapper.
+- `TooltipTrigger`: trigger element.
+- `TooltipContent`: positioned surface with pointer, title, support text, shortcut, and close affordance.
+- `TooltipShortcut`: direction-isolated physical shortcut slot.
+- `TooltipCloseButton`: optional close affordance.
+
+## Example
+
+```tsx
+import {
+  Tooltip,
+  TooltipContent,
+  TooltipProvider,
+  TooltipTrigger,
+} from "@/components/ui/tooltip"
+import { Button } from "@/components/ui/button"
+
+export function Example() {
+  return (
+    <TooltipProvider>
+      <Tooltip>
+        <TooltipTrigger asChild>
+          <Button variant="secondary">Details</Button>
+        </TooltipTrigger>
+        <TooltipContent pointerPosition="top-center" size="lg">
+          More information
+        </TooltipContent>
+      </Tooltip>
+    </TooltipProvider>
+  )
+}
+```
+
+## Variants
+
+| Prop | Values |
+| --- | --- |
+| `variant` | `dark`, `default` |
+| `size` | `sm`, `lg` |
+| `pointerPosition` | `top-left`, `top-center`, `top-right`, `bottom-left`, `bottom-center`, `bottom-right`, `center-left`, `center-right`, `none` |
+| `showPointer` | `boolean` |
+
+## RTL
+
+Tooltip content uses inherited direction and `dir="auto"` text. `TooltipShortcut` defaults to `dir="ltr"` so physical modifiers and keys do not reorder inside RTL tooltips. Top and bottom left/right positions map to logical start/end in RTL, while center-left and center-right remain physical sides to match the Figma matrix.
+
+## API
+
+Supported runtime exports: `Tooltip`, `TooltipCloseButton`, `TooltipContent`, `TooltipPortal`, `TooltipProvider`, `TooltipRoot`, `TooltipShortcut`, `TooltipTrigger`, `tooltipContentVariants`.
+
+| Contract | Values |
+| --- | --- |
+| `variants` | `dark`, `default` |
+| `sizes` | `sm`, `lg` |
+
+## Examples
+
+Primary registry example: `examples/tooltip-demo.tsx`.
+
+Open the live component page or run `npx banhaten docs tooltip` 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/tooltip.tsx`.
+
+## RTL Rules
+
+- `inheritsDirection`: true
+- `spacing`: Uses inherited direction with flex layout so label/shortcut and text/close order mirror naturally.
+- `pointerPlacement`: Top and bottom left/right positions map to logical start/end in RTL. Center-left and center-right remain physical sides to match the Figma matrix.
+- `textDirection`: Labels and support text use dir="auto" for Arabic and English copy.
+- `shortcutDirection`: TooltipShortcut defaults to dir="ltr" so physical key order remains stable inside RTL content.
+
+## Accessibility
+
+This component relies on `@radix-ui/react-tooltip` for its base accessibility behavior. Keep required labels, titles, descriptions, and focusable trigger/content relationships intact when composing it.
+
 <!-- registry-contract:start -->
 ## Registry Contract
 
@@ -100,8 +101,9 @@ This table is generated from `registry/index.json`; edit the component-owned sou
 | `supportedExports` | `components/tooltip.tsx: Tooltip, TooltipCloseButton, TooltipContent, TooltipPortal, TooltipProvider, TooltipRoot, TooltipShortcut, TooltipTrigger, tooltipContentVariants` |
 | `parts` | `Tooltip`, `TooltipRoot`, `TooltipTrigger`, `TooltipContent`, `TooltipProvider`, `TooltipPortal`, `TooltipShortcut`, `TooltipCloseButton` |
 | `registryDependencies` | None |
+| `props.dir` | `"ltr" \| "rtl" \| "auto"; default "ltr"; TooltipShortcut only: keeps key glyphs in physical order inside RTL tooltips. Override only for localized non-shortcut text.` |
 | `pointerPositions` | `top-left`, `top-center`, `top-right`, `bottom-left`, `bottom-center`, `bottom-right`, `center-right`, `center-left`, `none` |
 | `sizes` | `sm`, `lg` |
-| `tokens` | `--bh-bg-always-dark`, `--bh-bg-neutral-soft`, `--bh-bg-neutral-subtle`, `--bh-bg-raised`, `--bh-border-inverse-subtle`, `--bh-border-subtle`, `--bh-border-width-default`, `--bh-content-default`, `--bh-content-on-color`, `--bh-content-subtle`, `--bh-font-family`, `--bh-icon-stroke-200`, `--bh-interactive-ghost-hover`, `--bh-radius-full`, `--bh-radius-sm-4`, `--bh-space-md-8`, `--bh-space-none`, `--bh-space-xs-4`, `--bh-space-xxxs-1`, `--bh-text-base-letter-spacing`, `--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-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-tooltip-bg`, `--bh-tooltip-border`, `--bh-tooltip-close-fg`, `--bh-tooltip-close-icon-size`, `--bh-tooltip-close-size`, `--bh-tooltip-fg`, `--bh-tooltip-lg-padding`, `--bh-tooltip-lg-radius`, `--bh-tooltip-lg-width`, `--bh-tooltip-max-width`, `--bh-tooltip-pointer-border-depth`, `--bh-tooltip-pointer-border-half-width`, `--bh-tooltip-pointer-border-offset`, `--bh-tooltip-pointer-depth`, `--bh-tooltip-pointer-half-width`, `--bh-tooltip-pointer-inline-offset`, `--bh-tooltip-pointer-offset`, `--bh-tooltip-pointer-width`, `--bh-tooltip-shadow`, `--bh-tooltip-shortcut-bg`, `--bh-tooltip-shortcut-border`, `--bh-tooltip-shortcut-height`, `--bh-tooltip-shortcut-min-width`, `--bh-tooltip-sm-padding-x`, `--bh-tooltip-sm-padding-y`, `--bh-tooltip-sm-radius`, `--bh-z-overlay`, `--bh-z-raised`, `--shadow-button-focus`, `--shadow-lg` |
+| `tokens` | `--bh-bg-always-dark`, `--bh-bg-neutral-soft`, `--bh-bg-neutral-subtle`, `--bh-bg-raised`, `--bh-border-inverse-subtle`, `--bh-border-subtle`, `--bh-border-width-default`, `--bh-content-default`, `--bh-content-on-color`, `--bh-content-subtle`, `--bh-font-family`, `--bh-icon-stroke-200`, `--bh-interactive-ghost-hover`, `--bh-radius-full`, `--bh-radius-sm-4`, `--bh-space-md-8`, `--bh-space-none`, `--bh-space-xs-4`, `--bh-space-xxxs-1`, `--bh-text-base-letter-spacing`, `--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-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-tooltip-bg`, `--bh-tooltip-border`, `--bh-tooltip-close-fg`, `--bh-tooltip-close-icon-size`, `--bh-tooltip-close-size`, `--bh-tooltip-elevation`, `--bh-tooltip-fg`, `--bh-tooltip-lg-padding`, `--bh-tooltip-lg-radius`, `--bh-tooltip-lg-width`, `--bh-tooltip-max-width`, `--bh-tooltip-pointer-border-depth`, `--bh-tooltip-pointer-border-half-width`, `--bh-tooltip-pointer-border-offset`, `--bh-tooltip-pointer-depth`, `--bh-tooltip-pointer-half-width`, `--bh-tooltip-pointer-inline-offset`, `--bh-tooltip-pointer-offset`, `--bh-tooltip-pointer-width`, `--bh-tooltip-shortcut-bg`, `--bh-tooltip-shortcut-border`, `--bh-tooltip-shortcut-height`, `--bh-tooltip-shortcut-min-width`, `--bh-tooltip-sm-padding-x`, `--bh-tooltip-sm-padding-y`, `--bh-tooltip-sm-radius`, `--bh-z-overlay`, `--bh-z-raised`, `--elevation-04`, `--elevation-button-focus` |
 | `variants` | `dark`, `default` |
 <!-- registry-contract:end -->

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

@@ -1,18 +1,18 @@
-# Typography
-
-Banhaten exposes text utility classes generated from the design token contract. Use `.bh-text-*` classes when you need token-exact typography without pulling in a React component.
-
-## Usage
-
-```html
-<h1 class="bh-text-heading-lg-semibold">Workspace overview</h1>
-<p class="bh-text-body-md-regular">Review project status and owners.</p>
-```
-
-## Families
-
-The classes mirror token names across Display, Heading, and Body styles. Each class applies font size, line height, font weight, and letter spacing from `registry/styles/globals.css`.
-
-## RTL
-
-Typography classes do not set direction. Use `dir`, `lang`, and logical text alignment on the surrounding element.
+# Typography
+
+Banhaten exposes text utility classes generated from the design token contract. Use `.bh-text-*` classes when you need token-exact typography without pulling in a React component.
+
+## Usage
+
+```html
+<h1 class="bh-text-heading-lg-semibold">Workspace overview</h1>
+<p class="bh-text-body-md-regular">Review project status and owners.</p>
+```
+
+## Families
+
+The classes mirror token names across Display, Heading, and Body styles. Each class applies font size, line height, font weight, and letter spacing from `registry/styles/globals.css`.
+
+## RTL
+
+Typography classes do not set direction. Use `dir`, `lang`, and logical text alignment on the surrounding element.

package/docs/design-system/density-and-elevation.md

@@ -1,65 +1,65 @@
-# Density and Elevation
-
-## Density
-
-Banhaten exposes one semantic density contract for controls that must align in a
-product surface:
-
-| Density | Height | Typical use |
-| --- | ---: | --- |
-| `compact` | 32px | Dense desktop tables and constrained toolbars |
-| `default` | 36px | Standard forms, search, filters, and actions |
-| `comfortable` | 40px | Prominent forms and less dense product areas |
-
-Use `density` when Input, Select, Date Picker, Button, Button Group, Segmented
-Control, or Toolbar controls sit in the same row. The semantic prop overrides
-the component's legacy `size` prop. Existing `size` values remain supported for
-compatibility and for component-specific variants outside the shared 32/36/40
-control family.
-
-```tsx
-<Input density="default" />
-<Select density="default" />
-<DatePicker density="default" />
-<Button density="default">Apply</Button>
-<ToggleGroup density="default" />
-```
-
-Do not align controls by adding raw `h-*`, padding, radius, or font-size
-utilities. Choose one semantic density at the containing form or toolbar and
-pass it to every control. Compact controls are intended for pointer-led desktop
-interfaces; products with touch requirements should prefer `comfortable` or
-provide a larger interaction target around the control.
-
-This is a component composition contract, not a global scale transform. It does
-not silently resize navigation, cards, typography, or unrelated layout spacing.
-
-## Elevation
-
-Elevation uses two layers:
-
-- General steps: `--shadow-xs` through `--shadow-3xl`.
-- Semantic component aliases: `--shadow-component-*`, focus/danger rings, menus, controls, and component-specific aliases.
-
-The seven general steps mirror the current Figma `elevation/01` through
-`elevation/07` effect styles in [Shadow tests → With Variables](https://www.figma.com/design/LVAWtr5A5oEcAvsBmk6vdt/Banhaten-Design-system-3.0?node-id=6436-13190).
-The geometry is shared across modes. Figma's bound shadow color variables make
-the dark-mode drops, rings, and highlights stronger, so Banhaten publishes a
-separate exact recipe for each mode.
-
-| CSS step | Figma style | Current component roles |
-| --- | --- | --- |
-| `xs` | `elevation/01` | Flat surfaces with an ambient ring only |
-| `sm` | `elevation/02` | Subtle lift for inner cards, inset panels, and compact raised details |
-| `md` | `elevation/03` | Cards, surfaces, slider thumbs, and toggle handles |
-| `lg` | `elevation/04` | Menus, select menus, popovers, tooltips, and date surfaces |
-| `xl` | `elevation/05` | Sticky and floating surfaces, including floating banners |
-| `2xl` | `elevation/06` | Modals and dialogs |
-| `3xl` | `elevation/07` | Full-overlay surfaces that require maximum depth |
-
-Components consume the semantic alias that describes purpose rather than
-selecting a visual step directly. Focus rings, inset borders, and the Figma
-`Shadow/component/*` control effects remain separate from surface elevation.
-The Shadows documentation groups aliases under their canonical effect and
-distinguishes surface elevation, control strokes, focus rings, overlay
-elevation, and intentional `none` values.
+# Density and Elevation
+
+## Density
+
+Banhaten exposes one semantic density contract for controls that must align in a
+product surface:
+
+| Density | Height | Typical use |
+| --- | ---: | --- |
+| `compact` | 32px | Dense desktop tables and constrained toolbars |
+| `default` | 36px | Standard forms, search, filters, and actions |
+| `comfortable` | 40px | Prominent forms and less dense product areas |
+
+Use `density` when Input, Select, Date Picker, Button, Button Group, Segmented
+Control, or Toolbar controls sit in the same row. The semantic prop overrides
+the component's legacy `size` prop. Existing `size` values remain supported for
+compatibility and for component-specific variants outside the shared 32/36/40
+control family.
+
+```tsx
+<Input density="default" />
+<Select density="default" />
+<DatePicker density="default" />
+<Button density="default">Apply</Button>
+<ToggleGroup density="default" />
+```
+
+Do not align controls by adding raw `h-*`, padding, radius, or font-size
+utilities. Choose one semantic density at the containing form or toolbar and
+pass it to every control. Compact controls are intended for pointer-led desktop
+interfaces; products with touch requirements should prefer `comfortable` or
+provide a larger interaction target around the control.
+
+This is a component composition contract, not a global scale transform. It does
+not silently resize navigation, cards, typography, or unrelated layout spacing.
+
+## Elevation
+
+Elevation uses two layers in one public namespace:
+
+- General steps: `--elevation-01` through `--elevation-07`.
+- Semantic aliases: `--elevation-component-*`, focus/danger rings, menus, controls, and component-specific treatments.
+
+The seven general steps mirror the current Figma `elevation/01` through
+`elevation/07` effect styles in [Shadow tests → With Variables](https://www.figma.com/design/LVAWtr5A5oEcAvsBmk6vdt/Banhaten-Design-system-3.0?node-id=6436-13190).
+The geometry is shared across modes. Figma's bound shadow color variables make
+the dark-mode drops, rings, and highlights stronger, so Banhaten publishes a
+separate exact recipe for each mode.
+
+| CSS token | Figma style | Current component roles |
+| --- | --- | --- |
+| `--elevation-01` | `elevation/01` | Flat surfaces with an ambient ring only |
+| `--elevation-02` | `elevation/02` | Subtle lift for inner cards, inset panels, and compact raised details |
+| `--elevation-03` | `elevation/03` | Cards, surfaces, slider thumbs, and toggle handles |
+| `--elevation-04` | `elevation/04` | Menus, select menus, popovers, tooltips, and date surfaces |
+| `--elevation-05` | `elevation/05` | Sticky and floating surfaces, including floating banners |
+| `--elevation-06` | `elevation/06` | Modals and dialogs |
+| `--elevation-07` | `elevation/07` | Full-overlay surfaces that require maximum depth |
+
+Components consume the semantic alias that describes purpose rather than
+selecting a visual step directly. Focus rings and inset borders remain distinct
+effect recipes, but they share the `--elevation-*` public namespace so there is
+no parallel shadow-token API. CSS `box-shadow` is only the browser rendering
+mechanism. The Elevation documentation distinguishes surface depth, control
+strokes, focus rings, overlay elevation, and intentional `none` values.