banhaten 0.5.0 → 0.6.0

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

@@ -1,60 +1,60 @@
-# Toast
-
-Toast provides transient feedback for saves, errors, warnings, background work, and undoable actions. It uses a Sonner-style API with Banhaten token styling, semantic intents, action support, and logical LTR/RTL placement.
-
-## API
-
-```tsx
-<Toaster />
-
-toast.success("Project saved")
-toast.danger("Unable to publish", {
-  action: { label: "Retry", onClick: retry },
-})
-```
-
-| Export | Purpose |
-| --- | --- |
-| `Toaster` | app-level toast viewport |
-| `toast` | imperative toast API |
-| `toast.success`, `toast.info`, `toast.warning`, `toast.danger` | semantic shortcuts |
-
-| Prop | Values |
-| --- | --- |
-| `dir` | `ltr`, `rtl` |
-| `side` | `start`, `end` |
-| `position` | Sonner position override |
-
-## Token Contract
-
-Toast uses Banhaten raised surface, border, shadow, radius, body typography, action, danger, warning, success, info, and content tokens.
-
-## RTL
-
-`side="end"` resolves to top-right in LTR and top-left in RTL. Use `side="start"` for the opposite logical edge.
-
-## Accessibility
-
-Keep toast copy short and pair destructive failures with a visible retry or recovery path when possible. Do not use toasts as the only place for critical validation errors.
-
-## Install
-
-```bash
-npx banhaten add toast
-```
-
-## Examples
-
-Primary registry example: `examples/toast-demo.tsx`.
-
-Open the live component page or run `npx banhaten docs toast` to inspect source files, install command, and examples.
-
-## RTL Rules
-
-- `inheritsDirection`: true
-- `placement`: side="end" resolves to top-right in LTR and top-left in RTL; side="start" resolves to the opposite edge.
-- `textDirection`: Toast content inherits the Toaster direction and uses tokenized typography classes.
-
+# Toast
+
+Toast provides transient feedback for saves, errors, warnings, background work, and undoable actions. It uses a Sonner-style API with Banhaten token styling, semantic intents, action support, and logical LTR/RTL placement.
+
+## API
+
+```tsx
+<Toaster />
+
+toast.success("Project saved")
+toast.danger("Unable to publish", {
+  action: { label: "Retry", onClick: retry },
+})
+```
+
+| Export | Purpose |
+| --- | --- |
+| `Toaster` | app-level toast viewport |
+| `toast` | imperative toast API |
+| `toast.success`, `toast.info`, `toast.warning`, `toast.danger` | semantic shortcuts |
+
+| Prop | Values |
+| --- | --- |
+| `dir` | `ltr`, `rtl` |
+| `side` | `start`, `end` |
+| `position` | Sonner position override |
+
+## Token Contract
+
+Toast uses Banhaten raised surface, border, shadow, radius, body typography, action, danger, warning, success, info, and content tokens.
+
+## RTL
+
+`side="end"` resolves to top-right in LTR and top-left in RTL. Use `side="start"` for the opposite logical edge.
+
+## Accessibility
+
+Keep toast copy short and pair destructive failures with a visible retry or recovery path when possible. Do not use toasts as the only place for critical validation errors.
+
+## Install
+
+```bash
+npx banhaten add toast
+```
+
+## Examples
+
+Primary registry example: `examples/toast-demo.tsx`.
+
+Open the live component page or run `npx banhaten docs toast` to inspect source files, install command, and examples.
+
+## RTL Rules
+
+- `inheritsDirection`: true
+- `placement`: side="end" resolves to top-right in LTR and top-left in RTL; side="start" resolves to the opposite edge.
+- `textDirection`: Toast content inherits the Toaster direction and uses tokenized typography classes.
+
 <!-- registry-contract:start -->
 ## Registry Contract
 

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

@@ -1,83 +1,83 @@
-# Toggle
-
-Toggle is a Radix Switch-backed boolean control. It supports sm and md switch geometry, active and disabled states, optional handle icons, labeled leading or trailing compositions, supporting text, and inherited RTL direction.
-
-The implementation follows the Figma components at `Design system 3.0 Copy / Toogle` (`175:23379`) and `Toggle label` (`175:23443`).
-
-## API
-
-Use `Toggle` for standalone controls with an accessible label.
-
-```tsx
-<Toggle aria-label="Enable notifications" defaultChecked />
-```
-
-Use `ToggleField` when the visible label and supporting text should name the switch.
-
-```tsx
-<ToggleField
-  defaultChecked
-  controlPosition="end"
-  label="Email notifications"
-  description="Send product updates and billing activity."
-/>
-```
-
-## Variants
-
-| Prop | Values |
-| --- | --- |
-| `size` | `sm`, `md` |
-| `showIcon` | `boolean` |
-| `ToggleField controlPosition` | `start`, `end` |
-| `disabled` | `boolean` |
-
-## Tokens
-
-Toggle uses the existing Banhaten switch aliases:
-
-| Purpose | Token |
-| --- | --- |
-| Default track | `--bh-interactive-switch-default` |
-| Hover track | `--bh-interactive-switch-hover` |
-| Active track | `--bh-interactive-switch-active` |
-| Active hover track | `--bh-interactive-switch-active-hover` |
-| Disabled track | `--bh-interactive-switch-disabled` |
-| Handle | `--bh-interactive-switch-handle` |
-| Disabled handle | `--bh-interactive-switch-handle-disabled` |
-| Focus ring | `--elevation-social-button-focus-ring` |
-
-Text uses body-md for labels and body-xs for supporting text. ToggleField uses logical start/end placement so label order and thumb motion mirror in RTL.
-
-## Install
-
-```bash
-npx banhaten add toggle
-```
-
-## Examples
-
-Primary registry example: `examples/toggle-demo.tsx`.
-
-Open the live component page or run `npx banhaten docs toggle` 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/toggle.tsx`.
-
-## RTL Rules
-
-- `inheritsDirection`: true
-- `controlPlacement`: ToggleField uses start/end control placement so the switch and text order mirror in RTL.
-- `handleMotion`: The thumb translates with logical direction, so checked state moves to the visual end edge in LTR and RTL.
-- `textDirection`: Labels and descriptions use dir="auto" with tokenized body-md/body-xs typography.
-
-## Accessibility
-
-This component relies on `@radix-ui/react-switch` for its base accessibility behavior. Keep required labels, titles, descriptions, and focusable trigger/content relationships intact when composing it.
-
+# Toggle
+
+Toggle is a Radix Switch-backed boolean control. It supports sm and md switch geometry, active and disabled states, optional handle icons, labeled leading or trailing compositions, supporting text, and inherited RTL direction.
+
+The implementation follows the Figma components at `Design system 3.0 Copy / Toogle` (`175:23379`) and `Toggle label` (`175:23443`).
+
+## API
+
+Use `Toggle` for standalone controls with an accessible label.
+
+```tsx
+<Toggle aria-label="Enable notifications" defaultChecked />
+```
+
+Use `ToggleField` when the visible label and supporting text should name the switch.
+
+```tsx
+<ToggleField
+  defaultChecked
+  controlPosition="end"
+  label="Email notifications"
+  description="Send product updates and billing activity."
+/>
+```
+
+## Variants
+
+| Prop | Values |
+| --- | --- |
+| `size` | `sm`, `md` |
+| `showIcon` | `boolean` |
+| `ToggleField controlPosition` | `start`, `end` |
+| `disabled` | `boolean` |
+
+## Tokens
+
+Toggle uses the existing Banhaten switch aliases:
+
+| Purpose | Token |
+| --- | --- |
+| Default track | `--bh-interactive-switch-default` |
+| Hover track | `--bh-interactive-switch-hover` |
+| Active track | `--bh-interactive-switch-active` |
+| Active hover track | `--bh-interactive-switch-active-hover` |
+| Disabled track | `--bh-interactive-switch-disabled` |
+| Handle | `--bh-interactive-switch-handle` |
+| Disabled handle | `--bh-interactive-switch-handle-disabled` |
+| Focus ring | `--elevation-social-button-focus-ring` |
+
+Text uses body-md for labels and body-xs for supporting text. ToggleField uses logical start/end placement so label order and thumb motion mirror in RTL.
+
+## Install
+
+```bash
+npx banhaten add toggle
+```
+
+## Examples
+
+Primary registry example: `examples/toggle-demo.tsx`.
+
+Open the live component page or run `npx banhaten docs toggle` 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/toggle.tsx`.
+
+## RTL Rules
+
+- `inheritsDirection`: true
+- `controlPlacement`: ToggleField uses start/end control placement so the switch and text order mirror in RTL.
+- `handleMotion`: The thumb translates with logical direction, so checked state moves to the visual end edge in LTR and RTL.
+- `textDirection`: Labels and descriptions use dir="auto" with tokenized body-md/body-xs typography.
+
+## Accessibility
+
+This component relies on `@radix-ui/react-switch` for its base accessibility behavior. Keep required labels, titles, descriptions, and focusable trigger/content relationships intact when composing it.
+
 <!-- registry-contract:start -->
 ## Registry Contract
 

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

@@ -1,92 +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, 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.
-
+# 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
 

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

@@ -1,95 +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 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.
-
+# 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