banhaten 0.5.0 → 0.6.0

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

@@ -1,83 +1,83 @@
-# Button
-
-Button is the primary action primitive for forms, workflows, navigation actions, and destructive confirmations. It supports semantic variants, text and icon sizes, loading composition, link composition through `asChild`, and RTL-safe icon behavior.
-
-## API
-
-```tsx
-<Button variant="default" size="default">
-  Save changes
-</Button>
-```
-
-| Prop | Values | Default |
-| --- | --- | --- |
-| `variant` | `default`, `secondary`, `soft`, `outline`, `ghost`, `ghost-primary`, `danger`, `soft-danger`, `white`, `success`, `warning`, `link` | `default` |
-| `size` | `xs`, `sm`, `default`, `lg`, `xl`, `icon-xs`, `icon-sm`, `icon`, `icon-lg`, `icon-xl` | `default` |
-| `asChild` | `boolean` | `false` |
-| `disabled` | `boolean` | `false` |
-| `aria-busy` | `boolean` | none |
-
-`destructive` and `soft-destructive` remain accepted as deprecated compatibility aliases. Replace them with `danger` and `soft-danger`, respectively; the aliases are not separate visual treatments and will remain available for the repository's documented deprecation window.
-
-## Examples
-
-```tsx
-<Button>
-  <PlusIcon data-icon="inline-start" />
-  New item
-</Button>
-
-<Button variant="outline">
-  Continue
-  <ArrowRightIcon data-icon="inline-end" data-rtl-flip="true" />
-</Button>
-
-<Button disabled aria-busy="true">
-  <Spinner data-icon="inline-start" />
-  Loading
-</Button>
-```
-
-```tsx
-<div dir="rtl">
-  <Button>إرسال</Button>
-  <Button variant="outline">
-    متابعة
-    <ArrowRightIcon data-icon="inline-end" data-rtl-flip="true" />
-  </Button>
-</div>
-```
-
-## Token Contract
-
-Button consumes semantic interaction, content, border, radius, typography, spacing, opacity, and elevation tokens. Component source should not hard-code Figma color, spacing, radius, or elevation recipes.
-
-- Typography: `--bh-text-button-font-size`, `--bh-text-button-line-height`, `--bh-text-button-font-weight`, `--bh-text-button-letter-spacing`
-- Shape: `--bh-control-default`
-- Heights and padding: `--bh-button-*-height`, `--bh-button-*-padding-x`, `--bh-button-*-padding-y`
-- Icon rhythm: `--bh-button-icon-size` is an 18px glyph inside `--bh-button-icon-slot-size` at 20px; `--bh-button-icon-offset` and `--bh-button-label-padding-x` preserve optical alignment.
-- Effects: `--elevation-button-raised`, `--elevation-button-secondary`, `--elevation-button-soft`, `--elevation-button-focus`, `--elevation-button-danger-focus`
-
-## RTL Rules
-
-- Button inherits `dir` from the nearest parent.
-- Text labels render with `dir="auto"` so Arabic and English labels resolve naturally.
-- Use `data-icon="inline-start"` and `data-icon="inline-end"` for optical icon offsets.
-- Use `data-rtl-flip="true"` only for directional icons that should mirror, such as arrows and chevrons.
-
-## Accessibility
-
-- Use native `type`, `disabled`, and `aria-busy` attributes for behavior.
-- Icon-only buttons must have an accessible name through `aria-label`.
-- Use `asChild` for anchors or router links instead of nesting interactive elements.
-
-## Install
-
-```bash
-npx banhaten add button
-```
-
+# Button
+
+Button is the primary action primitive for forms, workflows, navigation actions, and destructive confirmations. It supports semantic variants, text and icon sizes, loading composition, link composition through `asChild`, and RTL-safe icon behavior.
+
+## API
+
+```tsx
+<Button variant="default" size="default">
+  Save changes
+</Button>
+```
+
+| Prop | Values | Default |
+| --- | --- | --- |
+| `variant` | `default`, `secondary`, `soft`, `outline`, `ghost`, `ghost-primary`, `danger`, `soft-danger`, `white`, `success`, `warning`, `link` | `default` |
+| `size` | `xs`, `sm`, `default`, `lg`, `xl`, `icon-xs`, `icon-sm`, `icon`, `icon-lg`, `icon-xl` | `default` |
+| `asChild` | `boolean` | `false` |
+| `disabled` | `boolean` | `false` |
+| `aria-busy` | `boolean` | none |
+
+`destructive` and `soft-destructive` remain accepted as deprecated compatibility aliases. Replace them with `danger` and `soft-danger`, respectively; the aliases are not separate visual treatments and will remain available for the repository's documented deprecation window.
+
+## Examples
+
+```tsx
+<Button>
+  <PlusIcon data-icon="inline-start" />
+  New item
+</Button>
+
+<Button variant="outline">
+  Continue
+  <ArrowRightIcon data-icon="inline-end" data-rtl-flip="true" />
+</Button>
+
+<Button disabled aria-busy="true">
+  <Spinner data-icon="inline-start" />
+  Loading
+</Button>
+```
+
+```tsx
+<div dir="rtl">
+  <Button>إرسال</Button>
+  <Button variant="outline">
+    متابعة
+    <ArrowRightIcon data-icon="inline-end" data-rtl-flip="true" />
+  </Button>
+</div>
+```
+
+## Token Contract
+
+Button consumes semantic interaction, content, border, radius, typography, spacing, opacity, and elevation tokens. Component source should not hard-code Figma color, spacing, radius, or elevation recipes.
+
+- Typography: `--bh-text-button-font-size`, `--bh-text-button-line-height`, `--bh-text-button-font-weight`, `--bh-text-button-letter-spacing`
+- Shape: `--bh-control-default`
+- Heights and padding: `--bh-button-*-height`, `--bh-button-*-padding-x`, `--bh-button-*-padding-y`
+- Icon rhythm: `--bh-button-icon-size` is an 18px glyph inside `--bh-button-icon-slot-size` at 20px; `--bh-button-icon-offset` and `--bh-button-label-padding-x` preserve optical alignment.
+- Effects: `--elevation-button-raised`, `--elevation-button-secondary`, `--elevation-button-soft`, `--elevation-button-focus`, `--elevation-button-danger-focus`
+
+## RTL Rules
+
+- Button inherits `dir` from the nearest parent.
+- Text labels render with `dir="auto"` so Arabic and English labels resolve naturally.
+- Use `data-icon="inline-start"` and `data-icon="inline-end"` for optical icon offsets.
+- Use `data-rtl-flip="true"` only for directional icons that should mirror, such as arrows and chevrons.
+
+## Accessibility
+
+- Use native `type`, `disabled`, and `aria-busy` attributes for behavior.
+- Icon-only buttons must have an accessible name through `aria-label`.
+- Use `asChild` for anchors or router links instead of nesting interactive elements.
+
+## Install
+
+```bash
+npx banhaten add button
+```
+
 <!-- registry-contract:start -->
 ## Registry Contract
 

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

@@ -1,90 +1,101 @@
-# Card
-
-Card is a token-built surface primitive for product summaries, media tiles, and action panels. It supports vertical and horizontal layouts, leading and trailing image treatments, full-image cards, desktop/mobile spacing, footer actions, and RTL-safe text.
-
-Use `CardSurface` when a product-specific composition needs the owned Banhaten card surface while supplying its own internal layout.
-
-```tsx
-<CardSurface>
-  <h3>Custom metric content</h3>
-</CardSurface>
-```
-
-## Install
-
-```bash
-npx banhaten add card
-```
-
-## Anatomy
-
-- `Card`: root surface with title, subtitle, description, media, and optional footer composition.
-- `CardMedia`: image/media slot with leading, trailing, or full-image treatment.
-- `CardFooter`: supporting metadata or action area.
-- `CardActions`: Button-composed primary and secondary actions.
-
-## Example
-
-```tsx
-import { Card } from "@/components/ui/card"
-
-export function Example() {
-  return (
-    <Card
-      title="Project activity"
-      subtitle="Updated 2 minutes ago"
-      description="A compact summary of the latest workspace changes."
-      orientation="horizontal"
-      type="leading-image"
-    />
-  )
-}
-```
-
-## Variants
-
-| Prop | Values |
-| --- | --- |
-| `orientation` | `vertical`, `horizontal` |
-| `type` | `leading-image`, `trailing-image`, `full-image` |
-| `breakpoint` | `desktop`, `mobile` |
-| `dir` | inherited, `ltr`, `rtl` |
-
-## RTL
-
-Card uses logical spacing, inherited direction, and `dir="auto"` copy wrappers so title, subtitle, description, footer actions, and menu affordances mirror naturally.
-
-## API
-
-Supported runtime exports: `Card`, `CardActions`, `CardFooter`, `CardMedia`, `CardSurface`, `cardVariants`.
-
-| Contract | Values |
-| --- | --- |
-| `types` | `leading-image`, `trailing-image`, `full-image` |
-| `orientations` | `vertical`, `horizontal` |
-
-## Examples
-
-Primary registry example: `examples/card-demo.tsx`.
-
-Open the live component page or run `npx banhaten docs card` 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/card.tsx`, `assets/images/art-01.jpg`.
-
-## RTL Rules
-
-- `inheritsDirection`: true
-- `spacing`: Uses logical direction, text-start behavior, and dir="auto" copy so title, subtitle, description, footer actions, and menu affordance mirror naturally.
-- `actions`: The default footer composes the existing Button primitive and keeps action order logical in LTR and RTL.
-
-## Accessibility
-
-Keep native semantics, accessible names, keyboard reachability, focus-visible treatment, and status/error announcements intact when composing this component.
-
+# Card
+
+Card is a token-built surface primitive for product summaries, media tiles, and action panels. It supports vertical and horizontal layouts, leading and trailing image treatments, full-image cards, desktop/mobile spacing, footer actions, and RTL-safe text.
+
+Use `CardSurface` when a product-specific composition needs the owned Banhaten card surface while supplying its own internal layout.
+
+```tsx
+<CardSurface>
+  <h3>Custom metric content</h3>
+</CardSurface>
+```
+
+## Install
+
+```bash
+npx banhaten add card
+```
+
+## Anatomy
+
+- `Card`: root surface with title, subtitle, description, media, and optional footer composition.
+- `CardMedia`: image/media slot with leading, trailing, or full-image treatment.
+- `CardFooter`: supporting metadata or action area.
+- `CardActions`: Button-composed primary and secondary actions.
+
+## Example
+
+```tsx
+import { Card } from "@/components/ui/card"
+
+export function Example() {
+  return (
+    <Card
+      title="Project activity"
+      subtitle="Updated 2 minutes ago"
+      description="A compact summary of the latest workspace changes."
+      orientation="horizontal"
+      type="leading-image"
+    />
+  )
+}
+```
+
+## Variants
+
+| Prop | Values |
+| --- | --- |
+| `orientation` | `vertical`, `horizontal` |
+| `type` | `leading-image`, `trailing-image`, `full-image` |
+| `breakpoint` | `desktop`, `mobile` |
+| `size` | `default`, `comfortable` |
+| `dir` | inherited, `ltr`, `rtl` |
+
+## Comfortable size
+
+`size="comfortable"` is the panel inside an app shell. It keeps the card surface, background and 1px inset edge, and uses a `12px` radius (`--bh-card-comfortable-radius`) where the library cards use `16px`. `Card` and `CardSurface` both take it, and both render `data-size`.
+
+```tsx
+<CardSurface size="comfortable" className="p-[var(--bh-space-5xl-24)]">
+  <h2>Position details</h2>
+</CardSurface>
+```
+
+## RTL
+
+Card uses logical spacing, inherited direction, and `dir="auto"` copy wrappers so title, subtitle, description, footer actions, and menu affordances mirror naturally.
+
+## API
+
+Supported runtime exports: `Card`, `CardActions`, `CardFooter`, `CardMedia`, `CardSurface`, `cardVariants`.
+
+| Contract | Values |
+| --- | --- |
+| `types` | `leading-image`, `trailing-image`, `full-image` |
+| `orientations` | `vertical`, `horizontal` |
+
+## Examples
+
+Primary registry example: `examples/card-demo.tsx`.
+
+Open the live component page or run `npx banhaten docs card` 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/card.tsx`, `assets/images/art-01.jpg`.
+
+## RTL Rules
+
+- `inheritsDirection`: true
+- `spacing`: Uses logical direction, text-start behavior, and dir="auto" copy so title, subtitle, description, footer actions, and menu affordance mirror naturally.
+- `actions`: The default footer composes the existing Button primitive and keeps action order logical in LTR and RTL.
+
+## 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
 
@@ -96,8 +107,11 @@ This table is generated from `registry/index.json`; edit the component-owned sou
 | `supportedExports` | `components/card.tsx: Card, CardActions, CardFooter, CardMedia, CardSurface, cardVariants` |
 | `parts` | `Card`, `CardSurface`, `CardMedia`, `CardFooter`, `CardActions` |
 | `registryDependencies` | `button` |
+| `props.Card.size` | `"default" \| "comfortable"; default "default"; comfortable is the panel inside an app shell: the same surface and 1px inset edge with a 12px radius instead of the library card's 16px.` |
+| `props.CardSurface.size` | `"default" \| "comfortable"; default "default"; The same sizes as Card, for compositions that bring their own layout.` |
 | `breakpoints` | `desktop`, `mobile` |
 | `orientations` | `vertical`, `horizontal` |
-| `tokens` | `--bh-bg-accent-green-subtle`, `--bh-bg-accent-sky-subtle`, `--bh-bg-neutral-subtle`, `--bh-bg-raised`, `--bh-border-subtle`, `--bh-border-width-default`, `--bh-card-actions-max-width`, `--bh-card-bg`, `--bh-card-border`, `--bh-card-content-padding`, `--bh-card-desktop-content-padding`, `--bh-card-desktop-full-height`, `--bh-card-desktop-horizontal-padding`, `--bh-card-desktop-media-height`, `--bh-card-full-height`, `--bh-card-horizontal-media-width`, `--bh-card-horizontal-min-height`, `--bh-card-horizontal-padding`, `--bh-card-horizontal-width`, `--bh-card-media-height`, `--bh-card-media-overlay`, `--bh-card-mobile-content-padding`, `--bh-card-mobile-full-height`, `--bh-card-mobile-horizontal-padding`, `--bh-card-mobile-media-height`, `--bh-card-more-icon-size`, `--bh-card-more-size`, `--bh-card-radius`, `--bh-card-vertical-width`, `--bh-content-default`, `--bh-content-on-color`, `--bh-content-subtle`, `--bh-control-default`, `--bh-interactive-ghost-hover`, `--bh-radius-3xl-16`, `--bh-space-3xl-16`, `--bh-space-5xl-24`, `--bh-space-6xl-32`, `--bh-space-md-8`, `--bh-space-xl-12`, `--bh-space-xxs-2`, `--bh-text-body-lg-regular-font-size`, `--bh-text-body-lg-regular-font-weight`, `--bh-text-body-lg-regular-letter-spacing`, `--bh-text-body-lg-regular-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-heading-sm-semibold-font-size`, `--bh-text-heading-sm-semibold-font-weight`, `--bh-text-heading-sm-semibold-letter-spacing`, `--bh-text-heading-sm-semibold-line-height`, `--elevation-button-focus` |
+| `sizes` | `default`, `comfortable` |
+| `tokens` | `--bh-bg-accent-green-subtle`, `--bh-bg-accent-sky-subtle`, `--bh-bg-neutral-subtle`, `--bh-bg-raised`, `--bh-border-subtle`, `--bh-border-width-default`, `--bh-card-actions-max-width`, `--bh-card-bg`, `--bh-card-border`, `--bh-card-comfortable-radius`, `--bh-card-content-padding`, `--bh-card-desktop-content-padding`, `--bh-card-desktop-full-height`, `--bh-card-desktop-horizontal-padding`, `--bh-card-desktop-media-height`, `--bh-card-full-height`, `--bh-card-horizontal-media-width`, `--bh-card-horizontal-min-height`, `--bh-card-horizontal-padding`, `--bh-card-horizontal-width`, `--bh-card-media-height`, `--bh-card-media-overlay`, `--bh-card-mobile-content-padding`, `--bh-card-mobile-full-height`, `--bh-card-mobile-horizontal-padding`, `--bh-card-mobile-media-height`, `--bh-card-more-icon-size`, `--bh-card-more-size`, `--bh-card-radius`, `--bh-card-vertical-width`, `--bh-content-default`, `--bh-content-on-color`, `--bh-content-subtle`, `--bh-control-default`, `--bh-interactive-ghost-hover`, `--bh-radius-3xl-16`, `--bh-space-3xl-16`, `--bh-space-5xl-24`, `--bh-space-6xl-32`, `--bh-space-md-8`, `--bh-space-xl-12`, `--bh-space-xxs-2`, `--bh-text-body-lg-regular-font-size`, `--bh-text-body-lg-regular-font-weight`, `--bh-text-body-lg-regular-letter-spacing`, `--bh-text-body-lg-regular-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-heading-sm-semibold-font-size`, `--bh-text-heading-sm-semibold-font-weight`, `--bh-text-heading-sm-semibold-letter-spacing`, `--bh-text-heading-sm-semibold-line-height`, `--elevation-button-focus` |
 | `types` | `leading-image`, `trailing-image`, `full-image` |
 <!-- registry-contract:end -->

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

@@ -1,49 +1,49 @@
-# Carousel
-
-Carousel is an Embla-backed carousel with content, item, previous, and next controls.
-
-## API
-
-```tsx
-<Carousel messages={{ previousSlide: "Previous item", nextSlide: "Next item" }}>
-  <CarouselContent>
-    <CarouselItem>Slide</CarouselItem>
-  </CarouselContent>
-  <CarouselPrevious />
-  <CarouselNext />
-</Carousel>
-```
-
-## Token Contract
-
-Carousel controls use Banhaten Button tokens, spacing, radius, and directional icon behavior.
-
-## RTL
-
-Directional icons flip in RTL. Direction does not select a language; pass `messages` on `Carousel` or `aria-label` on an individual control. Set Embla options through `opts` when you need a custom direction strategy.
-
-## Accessibility
-
-Carousel exposes a region and English button-label defaults for previous and next controls. `messages` accepts partial localized overrides, while a control's direct `aria-label` has highest precedence.
-
-## Install
-
-```bash
-npx banhaten add carousel
-```
-
-## Examples
-
-Primary registry example: `examples/carousel-demo.tsx`.
-
-Open the live component page or run `npx banhaten docs carousel` to inspect source files, install command, and examples.
-
-## RTL Rules
-
-- `inheritsDirection`: true
-- `directionalIconFlip`: Previous and next arrow icons flip in RTL.
-- `messages`: Direction does not select language. Pass messages or direct aria-label overrides for localized control names.
-
+# Carousel
+
+Carousel is an Embla-backed carousel with content, item, previous, and next controls.
+
+## API
+
+```tsx
+<Carousel messages={{ previousSlide: "Previous item", nextSlide: "Next item" }}>
+  <CarouselContent>
+    <CarouselItem>Slide</CarouselItem>
+  </CarouselContent>
+  <CarouselPrevious />
+  <CarouselNext />
+</Carousel>
+```
+
+## Token Contract
+
+Carousel controls use Banhaten Button tokens, spacing, radius, and directional icon behavior.
+
+## RTL
+
+Directional icons flip in RTL. Direction does not select a language; pass `messages` on `Carousel` or `aria-label` on an individual control. Set Embla options through `opts` when you need a custom direction strategy.
+
+## Accessibility
+
+Carousel exposes a region and English button-label defaults for previous and next controls. `messages` accepts partial localized overrides, while a control's direct `aria-label` has highest precedence.
+
+## Install
+
+```bash
+npx banhaten add carousel
+```
+
+## Examples
+
+Primary registry example: `examples/carousel-demo.tsx`.
+
+Open the live component page or run `npx banhaten docs carousel` to inspect source files, install command, and examples.
+
+## RTL Rules
+
+- `inheritsDirection`: true
+- `directionalIconFlip`: Previous and next arrow icons flip in RTL.
+- `messages`: Direction does not select language. Pass messages or direct aria-label overrides for localized control names.
+
 <!-- registry-contract:start -->
 ## Registry Contract
 

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

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