banhaten 0.5.0 → 0.6.0

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

@@ -1,179 +1,182 @@
-# Breadcrumbs
-
-Breadcrumbs show a user's location in a hierarchy and provide a quick path back to parent pages. Use `Breadcrumbs` for page-level navigation, not for step progress, tabs, or filters.
-
-Figma reference: `Breadcrumbs`, node `238:7987`.
-
-## Variants
-
-The Figma component defines these variants:
-
-| Type | Style | Separator type | Direction |
-| --- | --- | --- | --- |
-| `Default` | `Default` | `Slash` | LTR and RTL |
-| `Default` | `Default` | `Chevron` | LTR and RTL |
-| `Default` | `Raised` | `Slash` | LTR and RTL |
-| `Default` | `Raised` | `Chevron` | LTR and RTL |
-| `Only Icon` | `Default` | `Slash` | LTR and RTL |
-| `Only Icon` | `Default` | `Chevron` | LTR and RTL |
-| `Only Icon` | `Raised` | `Slash` | LTR and RTL |
-| `Only Icon` | `Raised` | `Chevron` | LTR and RTL |
-
-The Figma source supports up to six visible breadcrumb items. Code should model this as an `items` collection instead of positional booleans such as `showBreadcrumb01`.
-
-## API
-
-Use semantic names in code even if the Figma variant labels are title-cased.
-
-```ts
-type BreadcrumbSeparator = "slash" | "chevron";
-type BreadcrumbStyle = "default" | "raised";
-
-type BreadcrumbItem = {
-  label: string;
-  href?: string;
-  icon?: React.ReactNode;
-  current?: boolean;
-};
-
-type BreadcrumbsProps = {
-  items: BreadcrumbItem[];
-  separator?: BreadcrumbSeparator;
-  style?: BreadcrumbStyle;
-  iconOnly?: boolean;
-  dir?: "ltr" | "rtl" | "auto";
-  maxItems?: number;
-  "aria-label"?: string;
-};
-```
-
-`items` should be ordered from root to current page in logical reading order. RTL rendering should mirror the visual order through layout direction, not by reversing the source data.
-
-## Layout
-
-- The root is a horizontal flex row with centered alignment.
-- The default style has no container background and uses a compact inline gap.
-- The raised style adds a surface fill, a 1px border, 12px padding, and an 8px radius in the Figma source.
-- Text items use `Body/body-md (base)/medium` with a 15px size and 24px line height.
-- Item glyphs are 18px square inside 20px slots.
-- Slash and chevron separators are 16px square and should be decorative.
-- LTR chevrons point right; RTL chevrons point left.
-- Each label resolves its own content direction, so an opposing script truncates at its actual end while the trail keeps the inherited layout direction.
-- The icon-only type keeps the same item and separator rhythm but hides visible labels.
-- Do not allow wrapping inside individual breadcrumb labels unless the component has a deliberate collapsed or overflow mode.
-
-## Tokens
-
-Breadcrumbs should consume existing semantic tokens:
-
-```ts
-export const breadcrumbsTokens = {
-  itemColor: "content.subtle",
-  currentItemColor: "content.default",
-  iconColor: "content.subtle",
-  separatorColor: "content.subtle",
-  raisedBackground: "background.card",
-  raisedBorder: "border.subtle",
-  raisedRadius: "shape.control",
-  inlineGap: "space.xs-4",
-  raisedGap: "space.md-8",
-  raisedPadding: "space.xl-12",
-};
-```
-
-Do not hard-code Figma fallback values in component code. The current Figma fallbacks include `content/subtle` as `#4e596e`, `bg/raised` as white, `border/subtle` as `rgba(55, 83, 122, 0.13)`, and `radius/lg-8` as 8px. Implementations should resolve those through semantic tokens.
-
-If the design system later adds a dedicated `background.raised` token, the raised style can map to it. Until then, use the closest raised surface token such as `background.card`.
-
-## Accessibility
-
-- Render the component as navigation, usually `<nav aria-label="Breadcrumb">`.
-- Use an ordered list so the hierarchy is exposed to assistive technology.
-- Render linked ancestors as anchors.
-- Mark the current page with `aria-current="page"` and do not require it to be a link.
-- Hide separators from assistive technology with `aria-hidden="true"`.
-- Icon-only breadcrumbs must provide an accessible label for every item, even when visible text is hidden.
-- Preserve logical item order for screen readers in RTL contexts.
-- Provide keyboard focus treatment through the link or action primitive, not on decorative separators.
-
-## Usage
-
-```tsx
-<Breadcrumbs
-  items={[
-    { label: "Home", href: "/", icon: <HomeIcon /> },
-    { label: "Products", href: "/products" },
-    { label: "Analytics", current: true },
-  ]}
-/>
-
-<Breadcrumbs
-  separator="chevron"
-  style="raised"
-  items={[
-    { label: "Home", href: "/", icon: <HomeIcon /> },
-    { label: "Reports", href: "/reports" },
-    { label: "Monthly", current: true },
-  ]}
-/>
-
-<Breadcrumbs
-  iconOnly
-  aria-label="Breadcrumb"
-  items={[
-    { label: "Home", href: "/", icon: <HomeIcon /> },
-    { label: "Settings", href: "/settings", icon: <SettingsIcon /> },
-    { label: "Profile", current: true, icon: <UserIcon /> },
-  ]}
-/>
-
-<Breadcrumbs
-  dir="rtl"
-  separator="chevron"
-  items={[
-    { label: "Home", href: "/", icon: <HomeIcon /> },
-    { label: "Account", href: "/account" },
-    { label: "Security", current: true },
-  ]}
-/>
-```
-
-## Preset Impact
-
-- `default`: inline breadcrumbs remain quiet, and raised breadcrumbs use a modest surface radius with subtle border separation.
-- `rounded`: raised breadcrumbs can use the softer control radius and slightly more relaxed spacing.
-- `sharp`: raised breadcrumbs should use square or near-square corners and tighter horizontal rhythm.
-
-## Implementation Notes
-
-- Use the design system's icon primitive for home and chevron icons. The Figma source uses Remix Icon `home-5-line`, `arrow-right-s-line`, and `arrow-left-s-line`.
-- Generate separators between items instead of requiring callers to include separator items.
-- Keep overflow behavior explicit. If the trail is too long, collapse middle items behind an overflow control instead of silently hiding the current page.
-- Prefer `dir` or logical CSS properties for RTL behavior rather than maintaining separate RTL item arrays.
-- The raised style is a navigation surface, not a card. Keep elevation at `elevation.none` unless a consuming product places it inside an overlay.
-
-## Install
-
-```bash
-npx banhaten add breadcrumbs
-```
-
-## Examples
-
-Primary registry example: `examples/expanded/breadcrumbs-demo.tsx`.
-
-Open the live component page or run `npx banhaten docs breadcrumbs` to inspect source files, install command, and examples.
-
-## Token Contract
-
-Component styles must resolve through Banhaten semantic tokens, component aliases, or documented exception-ledger values.
-Do not add raw colors, pixel values, opacity utilities, z-index values, durations, or shadow literals directly to component source.
-Covered source files: `components/expanded/breadcrumbs.css`, `components/expanded/Breadcrumbs.tsx`.
-
-## RTL Rules
-
-The ordered trail inherits document direction and uses logical spacing. Each independently truncated label uses `dir="auto"`, preserving the identifying start of Latin content in an RTL trail (and Arabic content in an LTR trail) without changing item order, icon placement, or separator mirroring.
-
+# Breadcrumbs
+
+Breadcrumbs show a user's location in a hierarchy and provide a quick path back to parent pages. Use `Breadcrumbs` for page-level navigation, not for step progress, tabs, or filters.
+
+Figma reference: `Breadcrumbs`, node `238:7987`.
+
+## Variants
+
+The Figma component defines these variants:
+
+| Type | Style | Separator type | Direction |
+| --- | --- | --- | --- |
+| `Default` | `Default` | `Slash` | LTR and RTL |
+| `Default` | `Default` | `Chevron` | LTR and RTL |
+| `Default` | `Raised` | `Slash` | LTR and RTL |
+| `Default` | `Raised` | `Chevron` | LTR and RTL |
+| `Only Icon` | `Default` | `Slash` | LTR and RTL |
+| `Only Icon` | `Default` | `Chevron` | LTR and RTL |
+| `Only Icon` | `Raised` | `Slash` | LTR and RTL |
+| `Only Icon` | `Raised` | `Chevron` | LTR and RTL |
+
+The Figma source supports up to six visible breadcrumb items. Code should model this as an `items` collection instead of positional booleans such as `showBreadcrumb01`.
+
+## API
+
+Use semantic names in code even if the Figma variant labels are title-cased.
+
+```ts
+type BreadcrumbSeparator = "slash" | "chevron";
+type BreadcrumbStyle = "default" | "raised";
+type BreadcrumbSize = "md" | "sm";
+
+type BreadcrumbItem = {
+  label: string;
+  href?: string;
+  icon?: React.ReactNode;
+  current?: boolean;
+};
+
+type BreadcrumbsProps = {
+  items: BreadcrumbItem[];
+  separator?: BreadcrumbSeparator;
+  style?: BreadcrumbStyle;
+  size?: BreadcrumbSize;
+  iconOnly?: boolean;
+  dir?: "ltr" | "rtl" | "auto";
+  maxItems?: number;
+  "aria-label"?: string;
+};
+```
+
+`items` should be ordered from root to current page in logical reading order. RTL rendering should mirror the visual order through layout direction, not by reversing the source data.
+
+## Layout
+
+- The root is a horizontal flex row with centered alignment.
+- The default style has no container background and uses a compact inline gap.
+- The raised style adds a surface fill, a 1px border, 12px padding, and an 8px radius in the Figma source.
+- Text items use `Body/body-md (base)/medium` with a 15px size and 24px line height.
+- `size="sm"` uses `Body/body-sm/medium` with a 14px size, a 20px line height, and a 12px separator, so labels sit 20px apart, as in a 14px trail written with two spaces on each side of the slash.
+- Item glyphs are 18px square inside 20px slots.
+- Slash and chevron separators are 16px square and should be decorative.
+- LTR chevrons point right; RTL chevrons point left.
+- Each label resolves its own content direction, so an opposing script truncates at its actual end while the trail keeps the inherited layout direction.
+- The icon-only type keeps the same item and separator rhythm but hides visible labels.
+- Do not allow wrapping inside individual breadcrumb labels unless the component has a deliberate collapsed or overflow mode.
+
+## Tokens
+
+Breadcrumbs should consume existing semantic tokens:
+
+```ts
+export const breadcrumbsTokens = {
+  itemColor: "content.subtle",
+  currentItemColor: "content.default", // --bh-breadcrumbs-current-content
+  iconColor: "content.subtle",
+  separatorColor: "content.subtle",
+  raisedBackground: "background.card",
+  raisedBorder: "border.subtle",
+  raisedRadius: "shape.control",
+  inlineGap: "space.xs-4",
+  raisedGap: "space.md-8",
+  raisedPadding: "space.xl-12",
+};
+```
+
+Do not hard-code Figma fallback values in component code. The current Figma fallbacks include `content/subtle` as `#4e596e`, `bg/raised` as white, `border/subtle` as `rgba(55, 83, 122, 0.13)`, and `radius/lg-8` as 8px. Implementations should resolve those through semantic tokens.
+
+If the design system later adds a dedicated `background.raised` token, the raised style can map to it. Until then, use the closest raised surface token such as `background.card`.
+
+## Accessibility
+
+- Render the component as navigation, usually `<nav aria-label="Breadcrumb">`.
+- Use an ordered list so the hierarchy is exposed to assistive technology.
+- Render linked ancestors as anchors.
+- Mark the current page with `aria-current="page"` and do not require it to be a link.
+- Hide separators from assistive technology with `aria-hidden="true"`.
+- Icon-only breadcrumbs must provide an accessible label for every item, even when visible text is hidden.
+- Preserve logical item order for screen readers in RTL contexts.
+- Provide keyboard focus treatment through the link or action primitive, not on decorative separators.
+
+## Usage
+
+```tsx
+<Breadcrumbs
+  items={[
+    { label: "Home", href: "/", icon: <HomeIcon /> },
+    { label: "Products", href: "/products" },
+    { label: "Analytics", current: true },
+  ]}
+/>
+
+<Breadcrumbs
+  separator="chevron"
+  style="raised"
+  items={[
+    { label: "Home", href: "/", icon: <HomeIcon /> },
+    { label: "Reports", href: "/reports" },
+    { label: "Monthly", current: true },
+  ]}
+/>
+
+<Breadcrumbs
+  iconOnly
+  aria-label="Breadcrumb"
+  items={[
+    { label: "Home", href: "/", icon: <HomeIcon /> },
+    { label: "Settings", href: "/settings", icon: <SettingsIcon /> },
+    { label: "Profile", current: true, icon: <UserIcon /> },
+  ]}
+/>
+
+<Breadcrumbs
+  dir="rtl"
+  separator="chevron"
+  items={[
+    { label: "Home", href: "/", icon: <HomeIcon /> },
+    { label: "Account", href: "/account" },
+    { label: "Security", current: true },
+  ]}
+/>
+```
+
+## Preset Impact
+
+- `default`: inline breadcrumbs remain quiet, and raised breadcrumbs use a modest surface radius with subtle border separation.
+- `rounded`: raised breadcrumbs can use the softer control radius and slightly more relaxed spacing.
+- `sharp`: raised breadcrumbs should use square or near-square corners and tighter horizontal rhythm.
+
+## Implementation Notes
+
+- Use the design system's icon primitive for home and chevron icons. The Figma source uses Remix Icon `home-5-line`, `arrow-right-s-line`, and `arrow-left-s-line`.
+- Generate separators between items instead of requiring callers to include separator items.
+- Keep overflow behavior explicit. If the trail is too long, collapse middle items behind an overflow control instead of silently hiding the current page.
+- Prefer `dir` or logical CSS properties for RTL behavior rather than maintaining separate RTL item arrays.
+- The raised style is a navigation surface, not a card. Keep elevation at `elevation.none` unless a consuming product places it inside an overlay.
+
+## Install
+
+```bash
+npx banhaten add breadcrumbs
+```
+
+## Examples
+
+Primary registry example: `examples/expanded/breadcrumbs-demo.tsx`.
+
+Open the live component page or run `npx banhaten docs breadcrumbs` to inspect source files, install command, and examples.
+
+## Token Contract
+
+Component styles must resolve through Banhaten semantic tokens, component aliases, or documented exception-ledger values.
+Do not add raw colors, pixel values, opacity utilities, z-index values, durations, or shadow literals directly to component source.
+Covered source files: `components/expanded/breadcrumbs.css`, `components/expanded/Breadcrumbs.tsx`.
+
+## RTL Rules
+
+The ordered trail inherits document direction and uses logical spacing. Each independently truncated label uses `dir="auto"`, preserving the identifying start of Latin content in an RTL trail (and Arabic content in an LTR trail) without changing item order, icon placement, or separator mirroring.
+
 <!-- registry-contract:start -->
 ## Registry Contract
 
@@ -186,7 +189,8 @@ This table is generated from `registry/index.json`; edit the component-owned sou
 | `parts` | `Breadcrumbs` |
 | `registryDependencies` | None |
 | `modes` | `text`, `icon-only`, `slash`, `chevron` |
+| `sizes` | `md`, `sm` |
 | `states` | `link`, `current`, `overflow` |
-| `tokens` | `--bh-bg-raised`, `--bh-border-focus`, `--bh-border-subtle`, `--bh-content-default`, `--bh-content-subtle`, `--bh-focus-ring-width`, `--bh-font-family`, `--bh-font-weight-medium`, `--bh-icon-size-default`, `--bh-icon-slot-size-default`, `--bh-icon-stroke-190`, `--bh-icon-stroke-200`, `--bh-icon-stroke-225`, `--bh-interactive-ghost-hover`, `--bh-radius-lg-8`, `--bh-radius-sm-4`, `--bh-space-3xl-16`, `--bh-space-6xl-32`, `--bh-space-md-8`, `--bh-space-xl-12`, `--bh-space-xs-4`, `--bh-space-xxs-2`, `--bh-space-xxxs-1`, `--bh-text-base-letter-spacing`, `--bh-text-body-2xs-regular-line-height`, `--bh-text-body-md-font-size`, `--bh-text-body-md-line-height` |
+| `tokens` | `--bh-bg-raised`, `--bh-border-focus`, `--bh-border-subtle`, `--bh-breadcrumbs-current-content`, `--bh-content-default`, `--bh-content-subtle`, `--bh-focus-ring-width`, `--bh-font-family`, `--bh-font-weight-medium`, `--bh-icon-size-default`, `--bh-icon-slot-size-default`, `--bh-icon-stroke-190`, `--bh-icon-stroke-200`, `--bh-icon-stroke-225`, `--bh-interactive-ghost-hover`, `--bh-radius-lg-8`, `--bh-radius-sm-4`, `--bh-space-3xl-16`, `--bh-space-6xl-32`, `--bh-space-md-8`, `--bh-space-xl-12`, `--bh-space-xs-4`, `--bh-space-xxs-2`, `--bh-space-xxxs-1`, `--bh-text-base-letter-spacing`, `--bh-text-body-2xs-regular-line-height`, `--bh-text-body-md-font-size`, `--bh-text-body-md-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` |
 | `variants` | `default`, `raised` |
 <!-- registry-contract:end -->

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

@@ -1,100 +1,100 @@
-# Button Group
-
-Button Group is a connected set of related button actions. It supports text buttons and icon-only buttons, three sizes, inherited LTR/RTL direction, logical dividers, and tokenized interaction states.
-
-The implementation follows the Figma component at `Design system 3.0 Copy / Button Group Item 1.2` (`390:12399`).
-
-## API
-
-Use `ButtonGroup` as the connected container and `ButtonGroupItem` for each action.
-
-```tsx
-<ButtonGroup aria-label="View options" size="md">
-  <ButtonGroupItem>
-    <PlusIcon data-icon="inline-start" />
-    Button
-    <PlusIcon data-icon="inline-end" />
-  </ButtonGroupItem>
-  <ButtonGroupItem aria-pressed>
-    <PlusIcon data-icon="inline-start" />
-    Active
-    <PlusIcon data-icon="inline-end" />
-  </ButtonGroupItem>
-</ButtonGroup>
-```
-
-Use `ToggleGroup` when the connected controls own a single or multiple pressed-value model. It includes controlled and uncontrolled state plus Home, End, and direction-aware arrow-key focus movement.
-
-```tsx
-<ToggleGroup aria-label="Text alignment" defaultValue="start">
-  <ToggleGroupItem value="start">Start</ToggleGroupItem>
-  <ToggleGroupItem value="center">Center</ToggleGroupItem>
-  <ToggleGroupItem value="end">End</ToggleGroupItem>
-</ToggleGroup>
-```
-
-## Variants
-
-| Prop | Values |
-| --- | --- |
-| `size` | `md`, `sm`, `xs` |
-| `mode` | `default`, `iconOnly` |
-| `ButtonGroupItem aria-pressed` | `true`, `false` |
-| `ButtonGroupItem disabled` | `boolean` |
-| `ToggleGroup type` | `single`, `multiple` |
-| `ToggleGroup value`, `defaultValue` | `string`, `string[]` |
-| `ToggleGroupItem value` | `string` |
-
-Interaction styling is applied through native CSS pseudo states: `:hover`, `:active`, `:focus-visible`, `:disabled`, and `aria-pressed="true"`.
-
-## States
-
-| State | Background | Content |
-| --- | --- | --- |
-| Default | `--bh-button-group-item-bg` | `--bh-button-group-content-default` |
-| Hover | `--bh-button-group-item-hover-bg` | `--bh-button-group-content-default` |
-| Pressed | `--bh-button-group-item-pressed-bg` | `--bh-button-group-content-default` |
-| Active | `--bh-button-group-item-active-bg` | `--bh-button-group-content-active` |
-| Disabled | `--bh-button-group-item-disabled-bg` | `--bh-button-group-content-disabled` |
-
-## Dimensions
-
-| Size | Height | LTR text item | RTL text item | Icon-only item |
-| --- | ---: | ---: | ---: | ---: |
-| `md` | 40px | 128px | 124px | 40px |
-| `sm` | 36px | 120px | 116px | 36px |
-| `xs` | 32px | 112px | 108px | 32px |
-
-Text buttons use the design-system button typography tokens. Default glyphs are 18px inside preserved 20px slots. Icon-only buttons require an accessible label.
-
-## Install
-
-```bash
-npx banhaten add button-group
-```
-
-## Examples
-
-Primary registry example: `examples/button-group-demo.tsx`.
-
-Open the live component page or run `npx banhaten docs button-group` 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/button-group.tsx`.
-
-## RTL Rules
-
-- `inheritsDirection`: true
-- `itemSizing`: LTR and RTL default items keep their fixed Figma matrix widths. Icon-only groups keep the same square dimensions.
-- `spacing`: Uses logical dividers and inherited flex direction so item order, icon order, padding, and separators follow LTR or RTL.
-
-## 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.
-
+# Button Group
+
+Button Group is a connected set of related button actions. It supports text buttons and icon-only buttons, three sizes, inherited LTR/RTL direction, logical dividers, and tokenized interaction states.
+
+The implementation follows the Figma component at `Design system 3.0 Copy / Button Group Item 1.2` (`390:12399`).
+
+## API
+
+Use `ButtonGroup` as the connected container and `ButtonGroupItem` for each action.
+
+```tsx
+<ButtonGroup aria-label="View options" size="md">
+  <ButtonGroupItem>
+    <PlusIcon data-icon="inline-start" />
+    Button
+    <PlusIcon data-icon="inline-end" />
+  </ButtonGroupItem>
+  <ButtonGroupItem aria-pressed>
+    <PlusIcon data-icon="inline-start" />
+    Active
+    <PlusIcon data-icon="inline-end" />
+  </ButtonGroupItem>
+</ButtonGroup>
+```
+
+Use `ToggleGroup` when the connected controls own a single or multiple pressed-value model. It includes controlled and uncontrolled state plus Home, End, and direction-aware arrow-key focus movement.
+
+```tsx
+<ToggleGroup aria-label="Text alignment" defaultValue="start">
+  <ToggleGroupItem value="start">Start</ToggleGroupItem>
+  <ToggleGroupItem value="center">Center</ToggleGroupItem>
+  <ToggleGroupItem value="end">End</ToggleGroupItem>
+</ToggleGroup>
+```
+
+## Variants
+
+| Prop | Values |
+| --- | --- |
+| `size` | `md`, `sm`, `xs` |
+| `mode` | `default`, `iconOnly` |
+| `ButtonGroupItem aria-pressed` | `true`, `false` |
+| `ButtonGroupItem disabled` | `boolean` |
+| `ToggleGroup type` | `single`, `multiple` |
+| `ToggleGroup value`, `defaultValue` | `string`, `string[]` |
+| `ToggleGroupItem value` | `string` |
+
+Interaction styling is applied through native CSS pseudo states: `:hover`, `:active`, `:focus-visible`, `:disabled`, and `aria-pressed="true"`.
+
+## States
+
+| State | Background | Content |
+| --- | --- | --- |
+| Default | `--bh-button-group-item-bg` | `--bh-button-group-content-default` |
+| Hover | `--bh-button-group-item-hover-bg` | `--bh-button-group-content-default` |
+| Pressed | `--bh-button-group-item-pressed-bg` | `--bh-button-group-content-default` |
+| Active | `--bh-button-group-item-active-bg` | `--bh-button-group-content-active` |
+| Disabled | `--bh-button-group-item-disabled-bg` | `--bh-button-group-content-disabled` |
+
+## Dimensions
+
+| Size | Height | LTR text item | RTL text item | Icon-only item |
+| --- | ---: | ---: | ---: | ---: |
+| `md` | 40px | 128px | 124px | 40px |
+| `sm` | 36px | 120px | 116px | 36px |
+| `xs` | 32px | 112px | 108px | 32px |
+
+Text buttons use the design-system button typography tokens. Default glyphs are 18px inside preserved 20px slots. Icon-only buttons require an accessible label.
+
+## Install
+
+```bash
+npx banhaten add button-group
+```
+
+## Examples
+
+Primary registry example: `examples/button-group-demo.tsx`.
+
+Open the live component page or run `npx banhaten docs button-group` 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/button-group.tsx`.
+
+## RTL Rules
+
+- `inheritsDirection`: true
+- `itemSizing`: LTR and RTL default items keep their fixed Figma matrix widths. Icon-only groups keep the same square dimensions.
+- `spacing`: Uses logical dividers and inherited flex direction so item order, icon order, padding, and separators follow LTR or RTL.
+
+## Accessibility
+
+This component relies on `@radix-ui/react-slot` for its base accessibility behavior. Keep required labels, titles, descriptions, and focusable trigger/content relationships intact when composing it.
+
 <!-- registry-contract:start -->
 ## Registry Contract