banhaten 0.5.0 → 0.6.0

package/docs/design-system/components/page-header.md

@@ -1,94 +1,122 @@
-# Page Header
-
-Page headers introduce a page or section with optional hierarchy, title metadata, actions, description, and local tabs.
-
-Figma reference: `Page Header`, node `1154:2816` in `Design system 3.0 Copy`.
-
-## API
-
-```tsx
-<PageHeader
-  title="Section Tile"
-  metaInfo="Meta info"
-  description="Section description"
-  breadcrumbs={[{ label: "Home" }, { label: "Home" }]}
-  actions={[{ label: "Button" }, { label: "Button" }]}
-  tabs={{ items: ["Tab item", "Tab item", "Tab item"] }}
-/>
-```
-
-| Prop | Type | Default |
-| --- | --- | --- |
-| `title` | `string` | `Section Tile` |
-| `metaInfo` | `string` | `Meta info` |
-| `description` | `string` | `Section description` |
-| `icon` | `ReactNode` or `false` | home icon |
-| `breadcrumbs` | `PageHeaderBreadcrumb[]` or `false` | four `Home` items |
-| `actions` | `PageHeaderAction[]` or `false` | four `Button` actions |
-| `tabs` | `PageHeaderTabs` or `false` | underline `Tabs` |
-| `tabs.fullWidth` | `boolean` | `true`; set `false` for content-width triggers |
-| `dir` | `ltr` or `rtl` | `ltr` |
-
-## Structure
-
-The implementation follows the Figma hierarchy:
-
-- Breadcrumb navigation above the section body.
-- Title row with optional icon, title, and meta text.
-- Action group aligned to the end of the title row.
-- Optional body description below the title row.
-- Underline `Tabs` spanning the full header width. Triggers take equal shares by default and can opt into content width with `tabs.fullWidth: false`.
-
-The title and description each resolve their own content direction. This keeps punctuation attached to the content when its script opposes the surrounding page direction, without changing the mirrored header layout.
-
-`PageHeader` reuses the existing `Button` and `Tabs` components instead of duplicating their behavior or visual contracts. Action descriptors render as `secondary`, default-density Buttons; PageHeader owns only their grouping and placement.
-
-Breadcrumb items retain Breadcrumbs' icon-slot contract: populated slots use the canonical icon geometry, while empty slots collapse instead of reserving space inside the header.
-
-## Token Contract
-
-The component consumes Banhaten semantic tokens and component aliases. Do not hard-code Figma fallback literals in component source; promote any Figma value into its owned `tokens/source/` fragment as a `--bh-*` token or alias first.
-
-- Content: `--bh-content-brand-default`, `--bh-content-default`, `--bh-content-heading`, `--bh-content-muted`, `--bh-content-subtle`
-- Actions inherit Button's secondary surface, border, typography, focus, and disabled tokens instead of redeclaring them in PageHeader.
-- Breadcrumb icon visibility and geometry remain owned by Breadcrumbs.
-
-## Pixel Rules
-
-- Header root is vertically padded by `20px`.
-- Breadcrumb and body text use `15px / 24px`.
-- Title uses `24px / 28px` at weight `600`.
-- Meta text uses `12px / 16px`.
-- Title row and action group are separated by `40px`.
-- Populated breadcrumb icon slots remain `20px`; empty slots collapse to `0px`.
-- Actions use Button's `secondary`, `density="default"` contract (`36px` high, resolving to `sm`); PageHeader owns only action-group placement and gap.
-- Tabs use the existing `underline`, `md`, `fullWidth` treatment by default. Full-width triggers keep equal shares while labels fit; both full and content-width modes preserve intrinsic label width and scroll horizontally when the row is narrower than its labels.
-
-## Accessibility
-
-- Breadcrumbs render as `<nav aria-label="Breadcrumb">` with an ordered list.
-- Mark the current breadcrumb with `current: true` so it receives `aria-current="page"`.
-- Separators are decorative and hidden from assistive technology.
-- Action items render as real buttons or anchors.
-- Action focus and disabled states come from Button; breadcrumb focus remains visible for keyboard users.
-- Tab labels remain complete and non-overlapping; constrained rows scroll locally instead of truncating or painting one label over another.
-
-## Install
-
-```bash
-npx banhaten add page-header
-```
-
-## Examples
-
-Primary registry example: `examples/expanded/page-header-demo.tsx`.
-
-Open the live component page or run `npx banhaten docs page-header` to inspect source files, install command, and examples.
-
-## RTL Rules
-
-The header layout inherits document direction and uses logical spacing. The title and description independently use `dir="auto"`, so Latin copy in an RTL header (and Arabic copy in an LTR header) keeps neutral punctuation at its content end while breadcrumbs, actions, metadata, and tabs retain the header direction. Horizontal tab overflow follows that inherited direction without changing or truncating label copy.
-
+# Page Header
+
+Page headers introduce a page or section with optional hierarchy, title metadata, actions, description, and local tabs.
+
+Figma reference: `Page Header`, node `1154:2816` in `Design system 3.0 Copy`.
+
+## API
+
+```tsx
+<PageHeader
+  title="Section Tile"
+  metaInfo="Meta info"
+  description="Section description"
+  breadcrumbs={[{ label: "Home" }, { label: "Home" }]}
+  actions={[{ label: "Button" }, { label: "Button" }]}
+  tabs={{ items: ["Tab item", "Tab item", "Tab item"] }}
+/>
+```
+
+| Prop | Type | Default |
+| --- | --- | --- |
+| `title` | `ReactNode` (inline content) | `Section Tile` |
+| `metaInfo` | `string` | `Meta info` |
+| `description` | `ReactNode` (inline content) | `Section description` |
+| `icon` | `ReactNode` or `false` | home icon; none in `comfortable` unless passed |
+| `breadcrumbs` | `PageHeaderBreadcrumb[]` or `false` | four `Home` items |
+| `actions` | `PageHeaderAction[]`, your own nodes, or `false` | four `Button` actions |
+| `children` | `ReactNode` | none; supporting content under the description, such as a status badge |
+| `size` | `default` or `comfortable` | `default` |
+| `tabs` | `PageHeaderTabs` or `false` | underline `Tabs`; none in `comfortable` unless passed |
+| `tabs.fullWidth` | `boolean` | `true`; set `false` for content-width triggers |
+| `dir` | `ltr` or `rtl` | `ltr` |
+
+### Comfortable size
+
+`size="comfortable"` is the page heading inside an app shell whose header already carries the breadcrumbs. This is the `Page heading` frame in the ATS360 product files.
+
+- **Spacing:** no block padding; the title and description sit `8px` apart, and actions sit `24px` from the copy and `12px` from each other.
+- **Action data** render as `40px` (`density="comfortable"`) secondary Buttons.
+- **Action widths:** Buttons in the actions keep a minimum width of `160px`, or `176px` for primary Buttons. Longer labels grow past it, and icon-only Buttons keep their own size.
+- **Icon and tabs** appear only when you pass them.
+
+When a page needs a primary action, pass your own nodes instead of action data. The page's Buttons keep their own variants:
+
+```tsx
+<PageHeader
+  size="comfortable"
+  title="Requisitions"
+  description="Track headcount requests, budget checks, and approval ownership."
+  actions={<>
+    <Button variant="outline">Budgets</Button>
+    <Button>Create request</Button>
+  </>}
+/>
+```
+
+`description` takes inline content, for example a record ID followed by its status text. `children` render under it in a wrapping row, for badges or other supporting content.
+
+## Structure
+
+The implementation follows the Figma hierarchy:
+
+- Breadcrumb navigation above the section body.
+- Title row with optional icon, title, and meta text.
+- Action group aligned to the end of the title row.
+- Optional body description below the title row.
+- Underline `Tabs` spanning the full header width. Triggers take equal shares by default and can opt into content width with `tabs.fullWidth: false`.
+
+The title and description each resolve their own content direction. This keeps punctuation attached to the content when its script opposes the surrounding page direction, without changing the mirrored header layout.
+
+`PageHeader` reuses the existing `Button` and `Tabs` components instead of duplicating their behavior or visual contracts. Action descriptors render as `secondary`, default-density Buttons; PageHeader owns only their grouping and placement.
+
+Breadcrumb items retain Breadcrumbs' icon-slot contract: populated slots use the canonical icon geometry, while empty slots collapse instead of reserving space inside the header.
+
+## Token Contract
+
+The component consumes Banhaten semantic tokens and component aliases. Do not hard-code Figma fallback literals in component source; promote any Figma value into its owned `tokens/source/` fragment as a `--bh-*` token or alias first.
+
+- Content: `--bh-content-brand-default`, `--bh-content-default`, `--bh-content-heading`, `--bh-content-muted`, `--bh-content-subtle`
+- Actions inherit Button's secondary surface, border, typography, focus, and disabled tokens instead of redeclaring them in PageHeader.
+- Breadcrumb icon visibility and geometry remain owned by Breadcrumbs.
+
+## Pixel Rules
+
+- Header root is vertically padded by `20px`; `comfortable` has no padding.
+- Breadcrumb and body text use `15px / 24px`.
+- Title uses `24px / 28px` at weight `600`.
+- Meta text uses `12px / 16px`.
+- Title row and action group are separated by `40px`; `24px` in `comfortable`.
+- Title and description are `4px` apart; `8px` in `comfortable`. Actions are `8px` apart; `12px` in `comfortable`.
+- Populated breadcrumb icon slots remain `20px`; empty slots collapse to `0px`.
+- Actions use Button's `secondary`, `density="default"` contract (`36px` high, resolving to `sm`); PageHeader owns only action-group placement and gap.
+- Tabs use the existing `underline`, `md`, `fullWidth` treatment by default. Full-width triggers keep equal shares while labels fit; both full and content-width modes preserve intrinsic label width and scroll horizontally when the row is narrower than its labels.
+
+## Accessibility
+
+- Breadcrumbs render as `<nav aria-label="Breadcrumb">` with an ordered list.
+- Mark the current breadcrumb with `current: true` so it receives `aria-current="page"`.
+- Separators are decorative and hidden from assistive technology.
+- Action items render as real buttons or anchors.
+- Action focus and disabled states come from Button; breadcrumb focus remains visible for keyboard users.
+- Tab labels remain complete and non-overlapping; constrained rows scroll locally instead of truncating or painting one label over another.
+
+## Install
+
+```bash
+npx banhaten add page-header
+```
+
+## Examples
+
+Primary registry example: `examples/expanded/page-header-demo.tsx`.
+
+Open the live component page or run `npx banhaten docs page-header` to inspect source files, install command, and examples.
+
+## RTL Rules
+
+The header layout inherits document direction and uses logical spacing. The title and description independently use `dir="auto"`, so Latin copy in an RTL header (and Arabic copy in an LTR header) keeps neutral punctuation at its content end while breadcrumbs, actions, metadata, and tabs retain the header direction. Horizontal tab overflow follows that inherited direction without changing or truncating label copy.
+
 <!-- registry-contract:start -->
 ## Registry Contract
 
@@ -100,8 +128,14 @@ This table is generated from `registry/index.json`; edit the component-owned sou
 | `supportedExports` | `components/expanded/PageHeader.tsx: PageHeader` |
 | `parts` | `PageHeader` |
 | `registryDependencies` | `breadcrumbs`, `button`, `tabs` |
-| `features` | `Breadcrumb-owned icon-slot visibility`, `Button-owned default-density secondary action styling`, `content-safe horizontal tab overflow`, `full-width tab opt-out` |
+| `props.PageHeader.size` | `"default" \| "comfortable"; default "default"; comfortable is the page heading inside an app shell whose header carries the breadcrumbs: no block padding, 8px between title and description, 24px between copy and actions, 12px between actions, 40px action Buttons with a 160px minimum width (176px for primary), and no icon or tabs unless passed.` |
+| `props.PageHeader.actions` | `PageHeaderAction[] \| ReactNode \| false; default "[]"; Action data renders secondary Buttons at the header density; pass your own nodes for primary actions or other controls.` |
+| `props.PageHeader.description` | `ReactNode; default null; Inline description content under the title, in body-md and content/subtle.` |
+| `props.PageHeader.children` | `ReactNode; default null; Supporting content under the description, such as status badges, in a wrapping row with 8px gaps.` |
+| `props.PageHeader.title` | `ReactNode; default null; Heading content in heading-md semibold (24/28); inline content such as a record name and its type is allowed.` |
+| `features` | `Breadcrumb-owned icon-slot visibility`, `Button-owned default-density secondary action styling`, `content-safe horizontal tab overflow`, `full-width tab opt-out`, `comfortable size for app-shell page headings`, `custom action nodes and rich descriptions` |
 | `modes` | `breadcrumbs`, `metadata`, `description`, `actions`, `tabs` |
+| `sizes` | `default`, `comfortable` |
 | `states` | `default`, `without-icon`, `without-actions`, `without-tabs` |
-| `tokens` | `--bh-button-label-padding-x`, `--bh-content-brand-default`, `--bh-content-default`, `--bh-content-muted`, `--bh-content-subtle`, `--bh-focus-ring-width`, `--bh-font-family`, `--bh-icon-stroke-190`, `--bh-space-2xl-14`, `--bh-space-3xl-16`, `--bh-space-4xl-20`, `--bh-space-5xl-24`, `--bh-space-7xl-40`, `--bh-space-lg-10`, `--bh-space-md-8`, `--bh-space-xs-4`, `--bh-space-xxs-2`, `--bh-text-body-2xs-regular-font-size`, `--bh-text-body-2xs-regular-font-weight`, `--bh-text-body-2xs-regular-line-height`, `--bh-text-body-md-medium-font-size`, `--bh-text-body-md-medium-font-weight`, `--bh-text-body-md-medium-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-md-semibold-font-size`, `--bh-text-heading-md-semibold-font-weight`, `--bh-text-heading-md-semibold-line-height` |
+| `tokens` | `--bh-button-label-padding-x`, `--bh-content-brand-default`, `--bh-content-default`, `--bh-content-muted`, `--bh-content-subtle`, `--bh-focus-ring-width`, `--bh-font-family`, `--bh-icon-stroke-190`, `--bh-page-header-comfortable-action-min-width`, `--bh-page-header-comfortable-primary-action-min-width`, `--bh-space-2xl-14`, `--bh-space-3xl-16`, `--bh-space-4xl-20`, `--bh-space-5xl-24`, `--bh-space-7xl-40`, `--bh-space-lg-10`, `--bh-space-md-8`, `--bh-space-xl-12`, `--bh-space-xs-4`, `--bh-space-xxs-2`, `--bh-text-body-2xs-regular-font-size`, `--bh-text-body-2xs-regular-font-weight`, `--bh-text-body-2xs-regular-line-height`, `--bh-text-body-md-medium-font-size`, `--bh-text-body-md-medium-font-weight`, `--bh-text-body-md-medium-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-md-semibold-font-size`, `--bh-text-heading-md-semibold-font-weight`, `--bh-text-heading-md-semibold-line-height` |
 <!-- registry-contract:end -->

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

@@ -1,59 +1,59 @@
-# Pagination
-
-Pagination navigates paged result sets, tables, and long lists. It supports numeric, simple, and summary layouts, soft and ghost styles, exact control geometry, captions, RTL layout, and explicit localized messages.
-
-## API
-
-```tsx
-<Pagination page={3} pages={[1, 2, 3, "ellipsis", 12]} type="numeric" />
-<Pagination
-  dir="rtl"
-  messages={{ previous: "הקודם", next: "הבא" }}
-  page={2}
-  type="summary"
-/>
-```
-
-| Prop | Values | Default |
-| --- | --- | --- |
-| `type` | `numeric`, `simple`, `summary` | `numeric` |
-| `variant` | `soft`, `ghost` | `soft` |
-| `page` | number | `2` |
-| `pages` | page numbers, page descriptors, `ellipsis` | built-in demo sequence |
-| `messages` | partial localized message catalog | English defaults |
-| `caption`, `summary`, previous/next label and ARIA props | direct overrides | matching message value |
-
-## Token Contract
-
-Pagination uses Banhaten control height, radius, border, background, content, focus, icon, caption, and elevation tokens. Previous/next glyphs are 18px inside 20px slots.
-
-## RTL
-
-Passing `dir="rtl"` mirrors previous/next directional icons with `data-rtl-flip="true"` and leaves the selected message catalog unchanged. Use `arabicPaginationMessages` or product-owned messages when the locale is Arabic.
-
-## Accessibility
-
-Wrap pagination in a navigation landmark with a descriptive label. Current page controls should expose current state, and previous/next buttons should have readable labels.
-
-## Install
-
-```bash
-npx banhaten add pagination
-```
-
-## Examples
-
-Primary registry example: `examples/pagination-demo.tsx`.
-
-Open the live component page or run `npx banhaten docs pagination` to inspect source files, install command, and examples.
-
-## RTL Rules
-
-- `inheritsDirection`: true
-- `messages`: Direction does not select language. English defaults are stable; pass messages for Arabic, Hebrew, Persian, Urdu, or another locale.
-- `directionalIconFlip`: Inline Figma arrow vectors use data-rtl-flip="true" so previous and next controls mirror in RTL.
-- `spacing`: Uses logical flex direction, gap, and text direction so English and Arabic captions align naturally.
-
+# Pagination
+
+Pagination navigates paged result sets, tables, and long lists. It supports numeric, simple, and summary layouts, soft and ghost styles, exact control geometry, captions, RTL layout, and explicit localized messages.
+
+## API
+
+```tsx
+<Pagination page={3} pages={[1, 2, 3, "ellipsis", 12]} type="numeric" />
+<Pagination
+  dir="rtl"
+  messages={{ previous: "הקודם", next: "הבא" }}
+  page={2}
+  type="summary"
+/>
+```
+
+| Prop | Values | Default |
+| --- | --- | --- |
+| `type` | `numeric`, `simple`, `summary` | `numeric` |
+| `variant` | `soft`, `ghost` | `soft` |
+| `page` | number | `2` |
+| `pages` | page numbers, page descriptors, `ellipsis` | built-in demo sequence |
+| `messages` | partial localized message catalog | English defaults |
+| `caption`, `summary`, previous/next label and ARIA props | direct overrides | matching message value |
+
+## Token Contract
+
+Pagination uses Banhaten control height, radius, border, background, content, focus, icon, caption, and elevation tokens. Previous/next glyphs are 18px inside 20px slots.
+
+## RTL
+
+Passing `dir="rtl"` mirrors previous/next directional icons with `data-rtl-flip="true"` and leaves the selected message catalog unchanged. Use `arabicPaginationMessages` or product-owned messages when the locale is Arabic.
+
+## Accessibility
+
+Wrap pagination in a navigation landmark with a descriptive label. Current page controls should expose current state, and previous/next buttons should have readable labels.
+
+## Install
+
+```bash
+npx banhaten add pagination
+```
+
+## Examples
+
+Primary registry example: `examples/pagination-demo.tsx`.
+
+Open the live component page or run `npx banhaten docs pagination` to inspect source files, install command, and examples.
+
+## RTL Rules
+
+- `inheritsDirection`: true
+- `messages`: Direction does not select language. English defaults are stable; pass messages for Arabic, Hebrew, Persian, Urdu, or another locale.
+- `directionalIconFlip`: Inline Figma arrow vectors use data-rtl-flip="true" so previous and next controls mirror in RTL.
+- `spacing`: Uses logical flex direction, gap, and text direction so English and Arabic captions align naturally.
+
 <!-- registry-contract:start -->
 ## Registry Contract
 

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

@@ -1,62 +1,62 @@
-# Popover
-
-Popover presents contextual controls, filters, actions, settings, and short help content near a trigger. It supports controlled and uncontrolled state, click, focus, and hover-capable triggers, positioned content, optional arrow, alignment, offsets, sizes, close affordance, and RTL-safe composition.
-
-## API
-
-```tsx
-<Popover>
-  <PopoverTrigger>Filters</PopoverTrigger>
-  <PopoverContent side="bottom" align="start">
-    <PopoverHeader>
-      <PopoverTitle>Filters</PopoverTitle>
-      <PopoverClose />
-    </PopoverHeader>
-    <PopoverBody>Filter controls go here.</PopoverBody>
-  </PopoverContent>
-</Popover>
-```
-
-| Prop | Values |
-| --- | --- |
-| `open`, `defaultOpen`, `onOpenChange` | controlled or uncontrolled state |
-| `side` | `top`, `right`, `bottom`, `left` |
-| `align` | `start`, `center`, `end` |
-| `size` | `sm`, `md`, `lg`, `auto` |
-| `offset` | `tight`, `default`, `loose` |
-| `showArrow` | `boolean` |
-
-## Token Contract
-
-Popover uses Banhaten popover width, padding, arrow, offset, surface, border, radius, shadow, trigger, typography, and z-index tokens.
-
-## RTL
-
-Top and bottom alignment use logical start/end behavior. Title and description slots use `dir="auto"` and product content can inherit the nearest direction.
-
-## Accessibility
-
-Use popovers for non-modal contextual content. Use Dialog or Sheet for workflows that require focus trapping or stronger dismissal semantics.
-
-## Install
-
-```bash
-npx banhaten add popover
-```
-
-## Examples
-
-Primary registry example: `examples/popover-demo.tsx`.
-
-Open the live component page or run `npx banhaten docs popover` to inspect source files, install command, and examples.
-
-## RTL Rules
-
-- `inheritsDirection`: true
-- `alignment`: Top and bottom alignments use logical start/end so the panel edge and arrow align correctly in LTR and RTL.
-- `spacing`: Uses logical layout and Banhaten spacing tokens for headers, bodies, footers, arrows, and trigger gaps.
-- `textDirection`: Title and description slots use dir="auto" while product content can inherit the nearest direction.
-
+# Popover
+
+Popover presents contextual controls, filters, actions, settings, and short help content near a trigger. It supports controlled and uncontrolled state, click, focus, and hover-capable triggers, positioned content, optional arrow, alignment, offsets, sizes, close affordance, and RTL-safe composition.
+
+## API
+
+```tsx
+<Popover>
+  <PopoverTrigger>Filters</PopoverTrigger>
+  <PopoverContent side="bottom" align="start">
+    <PopoverHeader>
+      <PopoverTitle>Filters</PopoverTitle>
+      <PopoverClose />
+    </PopoverHeader>
+    <PopoverBody>Filter controls go here.</PopoverBody>
+  </PopoverContent>
+</Popover>
+```
+
+| Prop | Values |
+| --- | --- |
+| `open`, `defaultOpen`, `onOpenChange` | controlled or uncontrolled state |
+| `side` | `top`, `right`, `bottom`, `left` |
+| `align` | `start`, `center`, `end` |
+| `size` | `sm`, `md`, `lg`, `auto` |
+| `offset` | `tight`, `default`, `loose` |
+| `showArrow` | `boolean` |
+
+## Token Contract
+
+Popover uses Banhaten popover width, padding, arrow, offset, surface, border, radius, shadow, trigger, typography, and z-index tokens.
+
+## RTL
+
+Top and bottom alignment use logical start/end behavior. Title and description slots use `dir="auto"` and product content can inherit the nearest direction.
+
+## Accessibility
+
+Use popovers for non-modal contextual content. Use Dialog or Sheet for workflows that require focus trapping or stronger dismissal semantics.
+
+## Install
+
+```bash
+npx banhaten add popover
+```
+
+## Examples
+
+Primary registry example: `examples/popover-demo.tsx`.
+
+Open the live component page or run `npx banhaten docs popover` to inspect source files, install command, and examples.
+
+## RTL Rules
+
+- `inheritsDirection`: true
+- `alignment`: Top and bottom alignments use logical start/end so the panel edge and arrow align correctly in LTR and RTL.
+- `spacing`: Uses logical layout and Banhaten spacing tokens for headers, bodies, footers, arrows, and trigger gaps.
+- `textDirection`: Title and description slots use dir="auto" while product content can inherit the nearest direction.
+
 <!-- registry-contract:start -->
 ## Registry Contract
 

package/docs/design-system/components/progress-slider.md

@@ -1,52 +1,52 @@
-# Progress Slider
-
-Progress Slider is an adjustable, start-anchored progress control. It is built on Radix Slider and keeps the filled surface growing from the logical start edge while the grip handle remains at the active value edge.
-
-## API
-
-```tsx
-<ProgressSlider value={[45]} aria-label="Upload progress" />
-<ProgressSlider defaultValue={[70]} tone="success" showTicks />
-```
-
-| Prop | Values |
-| --- | --- |
-| `value`, `defaultValue` | Radix slider value array |
-| `size` | `default`, `lg` |
-| `tone` | `brand`, `neutral`, `success`, `warning`, `danger` |
-| `disabled` | `boolean` |
-| `showTicks` | `boolean` |
-
-## Token Contract
-
-Progress Slider uses Banhaten slider, progress, semantic tone, track, handle, pill radius, focus, and disabled tokens. Keep tone styling semantic so alert and status palettes can theme consistently.
-
-## RTL
-
-Radix receives the inherited `dir` attribute for keyboard and value direction. The fill stays anchored to the logical start edge in both LTR and RTL.
-
-## Accessibility
-
-Provide an accessible name through `aria-label` or `aria-labelledby`. Use `aria-valuetext` when the numeric value needs domain-specific phrasing.
-
-## Install
-
-```bash
-npx banhaten add progress-slider
-```
-
-## Examples
-
-Primary registry example: `examples/progress-slider-demo.tsx`.
-
-Open the live component page or run `npx banhaten docs progress-slider` to inspect source files, install command, and examples.
-
-## RTL Rules
-
-- `inheritsDirection`: true
-- `valueDirection`: Radix Slider handles direction and keyboard behavior through the inherited dir attribute; the fill stays anchored to the logical start edge.
-- `spacing`: Uses tokenized pill geometry and logical direction through Radix.
-
+# Progress Slider
+
+Progress Slider is an adjustable, start-anchored progress control. It is built on Radix Slider and keeps the filled surface growing from the logical start edge while the grip handle remains at the active value edge.
+
+## API
+
+```tsx
+<ProgressSlider value={[45]} aria-label="Upload progress" />
+<ProgressSlider defaultValue={[70]} tone="success" showTicks />
+```
+
+| Prop | Values |
+| --- | --- |
+| `value`, `defaultValue` | Radix slider value array |
+| `size` | `default`, `lg` |
+| `tone` | `brand`, `neutral`, `success`, `warning`, `danger` |
+| `disabled` | `boolean` |
+| `showTicks` | `boolean` |
+
+## Token Contract
+
+Progress Slider uses Banhaten slider, progress, semantic tone, track, handle, pill radius, focus, and disabled tokens. Keep tone styling semantic so alert and status palettes can theme consistently.
+
+## RTL
+
+Radix receives the inherited `dir` attribute for keyboard and value direction. The fill stays anchored to the logical start edge in both LTR and RTL.
+
+## Accessibility
+
+Provide an accessible name through `aria-label` or `aria-labelledby`. Use `aria-valuetext` when the numeric value needs domain-specific phrasing.
+
+## Install
+
+```bash
+npx banhaten add progress-slider
+```
+
+## Examples
+
+Primary registry example: `examples/progress-slider-demo.tsx`.
+
+Open the live component page or run `npx banhaten docs progress-slider` to inspect source files, install command, and examples.
+
+## RTL Rules
+
+- `inheritsDirection`: true
+- `valueDirection`: Radix Slider handles direction and keyboard behavior through the inherited dir attribute; the fill stays anchored to the logical start edge.
+- `spacing`: Uses tokenized pill geometry and logical direction through Radix.
+
 <!-- registry-contract:start -->
 ## Registry Contract