banhaten 0.3.0 → 0.5.0

package/docs/design-system/component-token-consistency-audit.md

@@ -1,173 +1,173 @@
-# Component Token Consistency Audit
-
-Date: 2026-06-13
-
-## Scope
-
-Reviewed the distributable component surface in `registry/components`, expanded component files in `registry/components/expanded`, generated/global token CSS in `registry/styles/globals.css`, token generation and contract scripts, and the playground mirrors.
-
-This audit is focused on whether component color, spacing, sizing, radius, typography, opacity, focus, z-index, shadow, and motion values are driven by Banhaten tokens or documented component aliases.
-
-## Checks Run
-
-- `npm run tokens:check` passed.
-- `npm run registry:check` passed.
-- `npm --prefix playground run test:components` passed with 97 component tests.
-
-Current automated coverage:
-
-- The token catalog compiler merges the owned `tokens/source/` fragments into
-  `tokens/banhaten.tokens.json`; `scripts/generate-token-css.mjs` combines that
-  compiled contract with `tokens/banhaten.utilities.css` and emits
-  `registry/styles/globals.css` without reading either generated output as an
-  authored input.
-- `scripts/check-token-css-reproducibility.mjs` runs the generator in a clean temporary tree with no previous `globals.css` and verifies equivalent generated content after line-ending normalization.
-- `scripts/check-token-contract.mjs` verifies those component aliases exist in the generated CSS.
-- `scripts/check-component-token-usage.mjs` scans `registry/components` for raw component-source values.
-- `scripts/check-registry-mirrors.mjs` verifies playground mirrors stay in sync with registry files.
-
-## Current Status
-
-The component library is mostly token-consistent now. The major items from the previous audit have been completed:
-
-- Component aliases have explicit owners under `tokens/source/` and compile into
-  one publication artifact; JavaScript no longer carries a second token source.
-- Tailwind mappings, keyframes, global rules, accessibility rules, and typography utilities are authored in `tokens/banhaten.utilities.css`; generated CSS is output-only.
-- Generated CSS is current.
-- Component aliases are contract-checked.
-- Registry component source passes the token-usage check.
-- Registry and playground mirrors match.
-- Core focus, z-index, duration, spacing, radius, typography, icon sizing, and common opacity patterns are now tokenized.
-
-The remaining changes are smaller consistency and governance items.
-
-## Required Changes
-
-### P1: Replace Remaining Raw `opacity-0` Utilities
-
-`--bh-opacity-0` already exists, and most components use tokenized opacity. Replace the remaining Tailwind raw zero-opacity utilities with token-backed forms:
-
-- `registry/components/date-picker.tsx`: replace `disabled:opacity-0` with `disabled:opacity-[var(--bh-opacity-0)]`.
-- `registry/components/radio-group.tsx`: replace the hidden input `opacity-0` with `opacity-[var(--bh-opacity-0)]`.
-- `registry/components/textarea.tsx`: replace `after:opacity-0` with `after:opacity-[var(--bh-opacity-0)]`.
-- Sync mirrors through `npm run registry:sync` or the existing mirror workflow.
-
-This is not a visual bug, but it is a token-discipline cleanup.
-
-### P1: Tighten The Token-Usage Check For Zero And Full Opacity
-
-`scripts/check-component-token-usage.mjs` currently flags raw Tailwind opacity only for `50`, `55`, `60`, and `70`. Extend that rule so component source also flags raw `opacity-0` and `opacity-100`, unless an explicit exception is added.
-
-Recommended pattern target:
-
-- Flag: `opacity-0`, `opacity-100`, `disabled:opacity-0`, `after:opacity-0`, grouped/state-prefixed variants.
-- Allow: `opacity-[var(--bh-opacity-0)]`, `opacity-[var(--bh-opacity-100)]`.
-
-### P2: Create A Formal Exception Ledger For Non-Token Literals In Alias Source
-
-Raw contract values in the authored token fragments are no longer leaking into
-component source. Intentional external or Figma-specific values carry a type and
-stay reviewable under their canonical owner so future cleanup does not
-accidentally erase brand/media fidelity.
-
-Document as approved exceptions or promote into a clearer token group:
-
-- Social provider colors: Facebook, Google, LinkedIn, WhatsApp.
-- Radio-card illustrative/payment colors and dimensions.
-- Fractional icon/media geometry such as `28.333px`, `13.333px`, and `6.364px`.
-- Effect/shadow color stops, since the supplied token zips do not include effect tokens.
-- Expanded layout widths and breakpoints for showcase/product-sized components.
-- `--bh-activity-feed-completed-brightness: 0.99`, or replace it with a semantic completed-state color if the visual can be expressed without a brightness filter.
-
-### P2: Keep JS Numeric Offsets Paired With CSS Tokens
-
-Radix APIs require numeric `sideOffset` values, so these cannot directly consume CSS variables:
-
-- `registry/components/select.tsx` uses `SELECT_MENU_SIDE_OFFSET_PX = 4`, mirroring `--bh-select-menu-offset`.
-- `registry/components/tooltip.tsx` uses pointer and pointerless numeric offsets, mirroring tooltip spacing aliases.
-
-The comments are already present. The remaining change is to add these cases to the exception ledger or add a small assertion/test that keeps the JS numbers aligned with their matching aliases.
-
-### P3: Clarify Expanded Component Contract
-
-Expanded components are registered with `status: "expanded"` and have many layout aliases, especially Icon Explorer, Table, Timeline, Steps, Catalog Components, and File Upload. Decide whether these are production component contracts or documentation/showcase layouts.
-
-If production:
-
-- Keep the `--bh-*` layout aliases as public component tokens.
-- Add docs for which layout aliases are safe to override.
-- Add them to any token documentation tables.
-
-If documentation/showcase only:
-
-- Mark them as documentation-level layout tokens.
-- Keep them under the static token check, but document that their large fixed widths are layout constraints rather than primitive spacing tokens.
-
-## Component Matrix
-
-### Core Components
-
-Needs token cleanup:
-
-- Date Picker: raw `disabled:opacity-0`.
-- Radio Group: raw hidden-input `opacity-0`.
-- Textarea: raw focus-ring pseudo-element `after:opacity-0`.
-
-Token-clean under current checks:
-
-- Accordion
-- Alert
-- Attribute
-- Avatar
-- Badge
-- Button
-- Button Group
-- Card
-- Checkbox
-- Divider
-- Input
-- Menu
-- Modal
-- Pagination
-- Progress
-- Progress Slider
-- Radio Card
-- Select
-- Select Content
-- Slider
-- Social Button
-- Spinner
-- Tag
-- Toggle
-- Toolbar
-- Tooltip
-
-### Expanded Components
-
-No direct component-source token violations remain under the current static check. Their remaining work is contract clarity and exception documentation:
-
-- Activity Feed
-- Banner
-- Breadcrumbs
-- Catalog Components Showcase
-- Command Bar
-- Expanded Divider
-- File Upload
-- Icon Explorer
-- Onboarding Step List Item
-- Page Header
-- Slideout
-- Steps
-- Table
-- Tabs
-- Timeline
-
-Approved literal media-query breakpoints remain in CSS `@media` conditions because CSS custom properties are not reliable media-query operands. Geometry inside those media query blocks should continue using Banhaten tokens or component aliases.
-
-## Suggested Implementation Order
-
-1. Replace the three raw `opacity-0` utilities in registry components and sync mirrors.
-2. Extend `scripts/check-component-token-usage.mjs` to catch raw `opacity-0` and `opacity-100`.
-3. Add an exception ledger for alias-source literals and Radix numeric offsets.
-4. Decide and document the expanded-component token contract.
-5. Re-run `npm run tokens:check`, `npm run registry:check`, and `npm --prefix playground run test:components`.
+# Component Token Consistency Audit
+
+Date: 2026-06-13
+
+## Scope
+
+Reviewed the distributable component surface in `registry/components`, expanded component files in `registry/components/expanded`, generated/global token CSS in `registry/styles/globals.css`, token generation and contract scripts, and the playground mirrors.
+
+This audit is focused on whether component color, spacing, sizing, radius, typography, opacity, focus, z-index, shadow, and motion values are driven by Banhaten tokens or documented component aliases.
+
+## Checks Run
+
+- `npm run tokens:check` passed.
+- `npm run registry:check` passed.
+- `npm --prefix playground run test:components` passed with 97 component tests.
+
+Current automated coverage:
+
+- The token catalog compiler merges the owned `tokens/source/` fragments into
+  `tokens/banhaten.tokens.json`; `scripts/generate-token-css.mjs` combines that
+  compiled contract with `tokens/banhaten.utilities.css` and emits
+  `registry/styles/globals.css` without reading either generated output as an
+  authored input.
+- `scripts/check-token-css-reproducibility.mjs` runs the generator in a clean temporary tree with no previous `globals.css` and verifies equivalent generated content after line-ending normalization.
+- `scripts/check-token-contract.mjs` verifies those component aliases exist in the generated CSS.
+- `scripts/check-component-token-usage.mjs` scans `registry/components` for raw component-source values.
+- `scripts/check-registry-mirrors.mjs` verifies playground mirrors stay in sync with registry files.
+
+## Current Status
+
+The component library is mostly token-consistent now. The major items from the previous audit have been completed:
+
+- Component aliases have explicit owners under `tokens/source/` and compile into
+  one publication artifact; JavaScript no longer carries a second token source.
+- Tailwind mappings, keyframes, global rules, accessibility rules, and typography utilities are authored in `tokens/banhaten.utilities.css`; generated CSS is output-only.
+- Generated CSS is current.
+- Component aliases are contract-checked.
+- Registry component source passes the token-usage check.
+- Registry and playground mirrors match.
+- Core focus, z-index, duration, spacing, radius, typography, icon sizing, and common opacity patterns are now tokenized.
+
+The remaining changes are smaller consistency and governance items.
+
+## Required Changes
+
+### P1: Replace Remaining Raw `opacity-0` Utilities
+
+`--bh-opacity-0` already exists, and most components use tokenized opacity. Replace the remaining Tailwind raw zero-opacity utilities with token-backed forms:
+
+- `registry/components/date-picker.tsx`: replace `disabled:opacity-0` with `disabled:opacity-[var(--bh-opacity-0)]`.
+- `registry/components/radio-group.tsx`: replace the hidden input `opacity-0` with `opacity-[var(--bh-opacity-0)]`.
+- `registry/components/textarea.tsx`: replace `after:opacity-0` with `after:opacity-[var(--bh-opacity-0)]`.
+- Sync mirrors through `npm run registry:sync` or the existing mirror workflow.
+
+This is not a visual bug, but it is a token-discipline cleanup.
+
+### P1: Tighten The Token-Usage Check For Zero And Full Opacity
+
+`scripts/check-component-token-usage.mjs` currently flags raw Tailwind opacity only for `50`, `55`, `60`, and `70`. Extend that rule so component source also flags raw `opacity-0` and `opacity-100`, unless an explicit exception is added.
+
+Recommended pattern target:
+
+- Flag: `opacity-0`, `opacity-100`, `disabled:opacity-0`, `after:opacity-0`, grouped/state-prefixed variants.
+- Allow: `opacity-[var(--bh-opacity-0)]`, `opacity-[var(--bh-opacity-100)]`.
+
+### P2: Create A Formal Exception Ledger For Non-Token Literals In Alias Source
+
+Raw contract values in the authored token fragments are no longer leaking into
+component source. Intentional external or Figma-specific values carry a type and
+stay reviewable under their canonical owner so future cleanup does not
+accidentally erase brand/media fidelity.
+
+Document as approved exceptions or promote into a clearer token group:
+
+- Social provider colors: Facebook, Google, LinkedIn, WhatsApp.
+- Radio-card illustrative/payment colors and dimensions.
+- Fractional icon/media geometry such as `28.333px`, `13.333px`, and `6.364px`.
+- Effect/shadow color stops, since the supplied token zips do not include effect tokens.
+- Expanded layout widths and breakpoints for showcase/product-sized components.
+- `--bh-activity-feed-completed-brightness: 0.99`, or replace it with a semantic completed-state color if the visual can be expressed without a brightness filter.
+
+### P2: Keep JS Numeric Offsets Paired With CSS Tokens
+
+Radix APIs require numeric `sideOffset` values, so these cannot directly consume CSS variables:
+
+- `registry/components/select.tsx` uses `SELECT_MENU_SIDE_OFFSET_PX = 4`, mirroring `--bh-select-menu-offset`.
+- `registry/components/tooltip.tsx` uses pointer and pointerless numeric offsets, mirroring tooltip spacing aliases.
+
+The comments are already present. The remaining change is to add these cases to the exception ledger or add a small assertion/test that keeps the JS numbers aligned with their matching aliases.
+
+### P3: Clarify Expanded Component Contract
+
+Expanded components are registered with `status: "expanded"` and have many layout aliases, especially Icon Explorer, Table, Timeline, Steps, Catalog Components, and File Upload. Decide whether these are production component contracts or documentation/showcase layouts.
+
+If production:
+
+- Keep the `--bh-*` layout aliases as public component tokens.
+- Add docs for which layout aliases are safe to override.
+- Add them to any token documentation tables.
+
+If documentation/showcase only:
+
+- Mark them as documentation-level layout tokens.
+- Keep them under the static token check, but document that their large fixed widths are layout constraints rather than primitive spacing tokens.
+
+## Component Matrix
+
+### Core Components
+
+Needs token cleanup:
+
+- Date Picker: raw `disabled:opacity-0`.
+- Radio Group: raw hidden-input `opacity-0`.
+- Textarea: raw focus-ring pseudo-element `after:opacity-0`.
+
+Token-clean under current checks:
+
+- Accordion
+- Alert
+- Attribute
+- Avatar
+- Badge
+- Button
+- Button Group
+- Card
+- Checkbox
+- Divider
+- Input
+- Menu
+- Modal
+- Pagination
+- Progress
+- Progress Slider
+- Radio Card
+- Select
+- Select Content
+- Slider
+- Social Button
+- Spinner
+- Tag
+- Toggle
+- Toolbar
+- Tooltip
+
+### Expanded Components
+
+No direct component-source token violations remain under the current static check. Their remaining work is contract clarity and exception documentation:
+
+- Activity Feed
+- Banner
+- Breadcrumbs
+- Catalog Components Showcase
+- Command Bar
+- Expanded Divider
+- File Upload
+- Icon Explorer
+- Onboarding Step List Item
+- Page Header
+- Slideout
+- Steps
+- Table
+- Tabs
+- Timeline
+
+Approved literal media-query breakpoints remain in CSS `@media` conditions because CSS custom properties are not reliable media-query operands. Geometry inside those media query blocks should continue using Banhaten tokens or component aliases.
+
+## Suggested Implementation Order
+
+1. Replace the three raw `opacity-0` utilities in registry components and sync mirrors.
+2. Extend `scripts/check-component-token-usage.mjs` to catch raw `opacity-0` and `opacity-100`.
+3. Add an exception ledger for alias-source literals and Radix numeric offsets.
+4. Decide and document the expanded-component token contract.
+5. Re-run `npm run tokens:check`, `npm run registry:check`, and `npm --prefix playground run test:components`.

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

@@ -1,76 +1,90 @@
-# Components
-
-Design-system components use semantic props and tokens. Appearance presets may change their visual treatment, but they should not change component APIs.
-
-## Component Catalog
-
-- [Accordion](./accordion.md): Radix-backed disclosure primitive with variants, size scale, animation, and RTL-safe text alignment.
-- [Activity Feed](./activity-feed.md): vertical activity timeline with avatars, status dots, captions or slot content, actions, and RTL support.
-- [Activity Heatmap](./activity-heatmap.md): token-only seven-day activity grid with five intensity levels, responsive overflow, and RTL support.
-- [Alert](./alert.md): compact and expandable contextual feedback with semantic status colors, action links, close control, and RTL support.
-- [Alert Dialog](./alert-dialog.md): Radix AlertDialog-backed confirmation surface for destructive or consequential actions with semantic intent styling.
-- [Aspect Ratio](./aspect-ratio.md): Radix AspectRatio wrapper for fixed-format media, previews, and product surfaces.
-- [Attribute](./attribute.md): semantic key-value description lists with alignment variants, density, bordered rows, rich value slots, and RTL support.
-- [Autocomplete](./autocomplete.md): searchable combobox field composed from Input, Select menu rows, and Tag chips for single or multiple selection.
-- [Avatar](./avatar.md): user avatar primitive with image, fallback, status, action overlays, groups, and RTL-safe overlap.
-- [Badge](./badge.md): compact status and metadata primitive with semantic colors, icons, dots, flags, counts, and RTL support.
-- [Banner](./banner.md): announcement and notice strip with slim, action, inline-action, input, color, size, content, and RTL variants.
-- [Button](./button.md): semantic action primitive with variants, text and icon sizes, loading composition, link composition, and Arabic/RTL-safe icon behavior.
-- [Button Group](./button-group.md): connected action groups with text and icon-only modes, md/sm/xs sizes, RTL widths, dividers, native interaction styling, and active/disabled states.
-- [Breadcrumbs](./breadcrumbs.md): hierarchical page navigation with slash or chevron separators, raised or inline styles, and RTL support.
-- [Card](./card.md): token-built content surface with image placements, footer actions, desktop/mobile spacing, and RTL-safe copy.
-- [Carousel](./carousel.md): Embla-backed carousel with content, item, previous, and next controls.
-- [Catalog Components](./catalog-components.md): expanded catalog showcase bundle for breadcrumbs, dividers, tags, file upload states, and table previews.
-- [Chart](./chart.md): Recharts wrapper with Banhaten chart tokens, responsive container, tooltip content, and legend content.
-- [Checkbox](./checkbox.md): Radix checkbox primitive plus checkbox-card composition with selected, disabled, hover, and RTL states.
-- [Collapsible](./collapsible.md): Radix Collapsible wrapper for disclosure sections with tokenized trigger and content slots.
-- [Command](./command.md): cmdk-backed command menu with search, groups, shortcuts, separators, and empty state.
-- [Context Menu](./context-menu.md): Radix ContextMenu-backed right-click menu with labels, separators, submenus, checks, radios, and shortcuts.
-- [Date Picker](./date-picker.md): calendar and range-picker suite with presets, open states, triggers, time rows, and RTL support.
-- [Divider](./divider.md): horizontal and vertical separator with solid or dotted rules.
-- [Empty State](./empty-state.md): no-results and first-run state with a neutral icon halo, title, supporting copy, actions, and RTL support.
-- [File Upload](./file-upload.md): drag-and-drop upload target with queued file rows, status feedback, and LTR/RTL size variants.
-- [Field](./field.md): accessible form-row composition for labels, controls, descriptions, errors, grouped fields, and validation state.
-- [Hover Card](./hover-card.md): Radix HoverCard-backed preview surface for rich hover and focus context.
-- [Icons](./icons.md): expanded icon explorer for pack review, semantic mapping, shortlist comparison, and Iconify inspection.
-- [Input](./input.md): text-entry field with labels, helper and error text, add-ons, tags, shortcuts, adornments, and RTL states.
-- [Input Group](./input-group.md): grouped input shell for protocol add-ons, inline actions, prefixes, suffixes, and compact rows.
-- [Input OTP](./input-otp.md): one-time-code field with grouped slots, paste distribution, masked values, hidden form value, and RTL keyboard behavior.
-- [Item](./item.md): composable list and action row with media, content, title, description, actions, separators, variants, sizes, and token-only styling.
-- [Kbd](./kbd.md): keyboard hint primitive for shortcuts, command rows, and form help text.
-- [Label](./label.md): Radix-backed accessible label primitive with required, optional, tone, disabled, and RTL-safe text behavior.
-- [Menu](./menu.md): Radix DropdownMenu-backed command surface with rich item slots, submenus, progress rows, labels, captions, and RTL layout.
-- [Menubar](./menubar.md): Radix Menubar-backed application menu with keyboard navigation and menu item slots.
-- [Modal](./modal.md): Radix Dialog-backed modal surface with size variants, header/body/footer slots, ConfirmModal guardrails, Button actions, Checkbox opt-out, and RTL support.
-- [Native Select](./native-select.md): tokenized native select field for platform forms, mobile fallback, and lightweight option sets.
-- [Navigation Menu](./navigation-menu.md): Radix NavigationMenu-backed top navigation with trigger, content, link, viewport, and indicator parts.
-- [Onboarding Step List Item](./onboarding-step-list-item.md): vertical progress-list row with finished, active, and inactive states plus RTL support.
-- [Page Header](./page-header.md): page hierarchy, title metadata, actions, description, and local tabs.
-- [Pagination](./pagination.md): numeric, simple, and summary pagination layouts with soft or ghost styling, captions, RTL layout, and explicit localized messages.
-- [Popover](./popover.md): contextual overlay primitive with click, focus, hover, positioning, arrows, close affordance, and RTL-safe composition.
-- [Progress](./progress.md): read-only progress meter with value fill, labels, helper text, indicator, spinner, and RTL support.
-- [Progress Slider](./progress-slider.md): Radix Slider-based progress control with start-anchored fill, semantic tones, ticks, and RTL keyboard behavior.
-- [Radio Card](./radio-card.md): rich single-choice option card with Figma content types, active/disabled states, and explicit RTL variants.
-- [Radio Group](./radio-group.md): native-input radio group with labels, descriptions, errors, controlled/uncontrolled values, and RTL-safe field rows.
-- [Select](./select.md): Radix Select-backed field and menu item system with item media, selection styles, validation states, and RTL layout.
-- [Segmented Control](./segmented-control.md): content-width single or multiple selection control with semantic density, an optional label segment, keyboard navigation, and RTL support.
-- [Resizable](./resizable.md): react-resizable-panels-backed split pane primitive with tokenized resize handle.
-- [Sheet](./sheet.md): Radix Dialog-based edge panel with logical start/end placement, top/bottom placement, size variants, and RTL support.
-- [Sidebar](./sidebar.md): composable app sidebar with collapse state, grouped menu items, logical placement, and sidebar tokens.
-- [Slideout](./slideout.md): desktop and mobile side panel with header/footer actions, scrollable slots, example content, and RTL support.
-- [Scroll Area](./scroll-area.md): Radix ScrollArea wrapper with tokenized viewport, scrollbar, thumb, and corner styling.
-- [Slider](./slider.md): accessible value and range control with single, range, multi-thumb, vertical, ticked, pill, tone, size, disabled, and RTL variants.
-- [Skeleton](./skeleton.md): token-built loading placeholders for text, avatars, actions, forms, cards, lists, tables, shimmer motion, and RTL surfaces.
-- [Social Button](./social-button.md): sign-in action primitive for supported providers with solid, outline, icon-only, focus, and RTL states.
-- [Spinner](./spinner.md): compact steady and dynamic loading spinners with inherited color and tokenized sizing.
-- [Steps](./steps.md): horizontal and vertical progress indicators with icon or number markers, item-level slots/actions, and RTL support.
-- [Table](./table.md): composable table and data-table workflow with selectable rows, sortable headers, search, filters, pagination, row states, RTL support, and reusable cell item variants.
-- [Tabs](./tabs.md): Radix Tabs-backed local navigation with underline, segmented, and rounded treatments across LTR and RTL.
-- [Textarea](./textarea.md): multiline field with labels, helper and error text, default and tags modes, placeholder, filled, disabled, and RTL states.
-- [Timeline](./timeline.md): vertical and horizontal progress/event sequences with default or icon markers, states, dates, captions, and RTL support.
-- [Toast](./toast.md): Sonner-style feedback primitive with semantic intents, action support, Banhaten token styling, and logical RTL placement.
-- [Tag](./tag.md): compact metadata, filter, and removable-selection chip with type, state, size, close-button, and RTL variants.
-- [Toggle](./toggle.md): switch-style boolean control with sm/md sizes, optional handle icons, labeled leading/trailing rows, supporting text, and RTL support.
-- [Toolbar](./toolbar.md): filter and action toolbar with search, select triggers, icon buttons, chips, summaries, desktop/mobile styles, and RTL support.
-- [Tooltip](./tooltip.md): Radix Tooltip-backed help surface with dark/default variants, pointer positions, shortcut/close slots, and RTL support.
-- [Typography](./typography.md): documentation for existing `.bh-text-*` token utility classes.
+# Components
+
+Design-system components use semantic props and tokens. Appearance presets may change their visual treatment, but they should not change component APIs.
+
+## Component Catalog
+
+- [Accordion](./accordion.md): Radix-backed disclosure primitive with variants, size scale, animation, and RTL-safe text alignment.
+- [Activity Feed](./activity-feed.md): vertical activity timeline with avatars, status dots, captions or slot content, actions, and RTL support.
+- [Activity Heatmap](./activity-heatmap.md): token-only seven-day activity grid with five intensity levels, responsive overflow, and RTL support.
+- [Alert](./alert.md): compact and expandable contextual feedback with semantic status colors, action links, close control, and RTL support.
+- [Alert Dialog](./alert-dialog.md): Radix AlertDialog-backed confirmation surface for destructive or consequential actions with semantic intent styling.
+- [Aspect Ratio](./aspect-ratio.md): Radix AspectRatio wrapper for fixed-format media, previews, and product surfaces.
+- [Attribute](./attribute.md): semantic key-value description lists with alignment variants, density, bordered rows, rich value slots, and RTL support.
+- [Autocomplete](./autocomplete.md): searchable combobox field composed from Input, Select menu rows, and Tag chips for single or multiple selection.
+- [Avatar](./avatar.md): user avatar primitive with image, fallback, status, action overlays, groups, and RTL-safe overlap.
+- [Badge](./badge.md): compact status and metadata primitive with semantic colors, icons, dots, flags, counts, and RTL support.
+- [Banner](./banner.md): announcement and notice strip with slim, action, inline-action, input, color, size, content, and RTL variants.
+- [Button](./button.md): semantic action primitive with variants, text and icon sizes, loading composition, link composition, and Arabic/RTL-safe icon behavior.
+- [Button Group](./button-group.md): connected action groups with text and icon-only modes, md/sm/xs sizes, RTL widths, dividers, native interaction styling, and active/disabled states.
+- [Breadcrumbs](./breadcrumbs.md): hierarchical page navigation with slash or chevron separators, raised or inline styles, and RTL support.
+- [Card](./card.md): token-built content surface with image placements, footer actions, desktop/mobile spacing, and RTL-safe copy.
+- [Carousel](./carousel.md): Embla-backed carousel with content, item, previous, and next controls.
+- [Catalog Components](./catalog-components.md): expanded catalog showcase bundle for breadcrumbs, dividers, tags, file upload states, and table previews.
+- [Chart](./chart.md): Recharts wrapper with Banhaten chart tokens, responsive container, tooltip content, and legend content.
+- [Checkbox](./checkbox.md): Radix checkbox primitive plus checkbox-card composition with selected, disabled, hover, and RTL states.
+- [Collapsible](./collapsible.md): Radix Collapsible wrapper for disclosure sections with tokenized trigger and content slots.
+- [Command](./command.md): cmdk-backed command menu with search, groups, shortcuts, separators, and empty state.
+- [Context Menu](./context-menu.md): Radix ContextMenu-backed right-click menu with labels, separators, submenus, checks, radios, and shortcuts.
+- [Date Picker](./date-picker.md): calendar and range-picker suite with presets, open states, triggers, time rows, and RTL support.
+- [Divider](./divider.md): horizontal and vertical separator with solid or dotted rules.
+- [Empty State](./empty-state.md): no-results and first-run state with a neutral icon halo, title, supporting copy, actions, and RTL support.
+- [File Upload](./file-upload.md): drag-and-drop upload target with queued file rows, status feedback, and LTR/RTL size variants.
+- [Field](./field.md): accessible form-row composition for labels, controls, descriptions, errors, grouped fields, and validation state.
+- [Hover Card](./hover-card.md): Radix HoverCard-backed preview surface for rich hover and focus context.
+- [Icons](./icons.md): expanded icon explorer for pack review, semantic mapping, shortlist comparison, and Iconify inspection.
+- [Input](./input.md): text-entry field with labels, helper and error text, add-ons, tags, shortcuts, adornments, and RTL states.
+- [Input Group](./input-group.md): grouped input shell for protocol add-ons, inline actions, prefixes, suffixes, and compact rows.
+- [Input OTP](./input-otp.md): one-time-code field with grouped slots, paste distribution, masked values, hidden form value, and RTL keyboard behavior.
+- [Item](./item.md): composable list and action row with media, content, title, description, actions, separators, variants, sizes, and token-only styling.
+- [Kbd](./kbd.md): keyboard hint primitive for shortcuts, command rows, and form help text.
+- [Label](./label.md): Radix-backed accessible label primitive with required, optional, tone, disabled, and RTL-safe text behavior.
+- [Menu](./menu.md): Radix DropdownMenu-backed command surface with rich item slots, submenus, progress rows, labels, captions, and RTL layout.
+- [Menubar](./menubar.md): Radix Menubar-backed application menu with keyboard navigation and menu item slots.
+- [Modal](./modal.md): Radix Dialog-backed modal surface with size variants, header/body/footer slots, ConfirmModal guardrails, Button actions, Checkbox opt-out, and RTL support.
+- [Native Select](./native-select.md): tokenized native select field for platform forms, mobile fallback, and lightweight option sets.
+- [Navigation Menu](./navigation-menu.md): Radix NavigationMenu-backed top navigation with trigger, content, link, viewport, and indicator parts.
+- [Onboarding Step List Item](./onboarding-step-list-item.md): vertical progress-list row with finished, active, and inactive states plus RTL support.
+- [Page Header](./page-header.md): page hierarchy, title metadata, actions, description, and local tabs.
+- [Pagination](./pagination.md): numeric, simple, and summary pagination layouts with soft or ghost styling, captions, RTL layout, and explicit localized messages.
+- [Popover](./popover.md): contextual overlay primitive with click, focus, hover, positioning, arrows, close affordance, and RTL-safe composition.
+- [Progress](./progress.md): read-only progress meter with value fill, labels, helper text, indicator, spinner, and RTL support.
+- [Progress Slider](./progress-slider.md): Radix Slider-based progress control with start-anchored fill, semantic tones, ticks, and RTL keyboard behavior.
+- [Radio Card](./radio-card.md): rich single-choice option card with Figma content types, active/disabled states, and explicit RTL variants.
+- [Radio Group](./radio-group.md): native-input radio group with labels, descriptions, errors, controlled/uncontrolled values, and RTL-safe field rows.
+- [Select](./select.md): Radix Select-backed field and menu item system with item media, selection styles, validation states, and RTL layout.
+- [Segmented Control](./segmented-control.md): content-width single or multiple selection control with semantic density, an optional label segment, keyboard navigation, and RTL support.
+- [Resizable](./resizable.md): react-resizable-panels-backed split pane primitive with tokenized resize handle.
+- [Rolling Count](./rolling-count.md): tabular figures that roll each changed digit into place like an odometer while assistive technology reads the plain value.
+- [Sheet](./sheet.md): Radix Dialog-based edge panel with logical start/end placement, top/bottom placement, size variants, and RTL support.
+- [Shimmer Text](./shimmer-text.md): text with a brightness sweep in reading direction for labels of work in progress.
+- [Sidebar](./sidebar.md): composable app sidebar with collapse state, grouped menu items, logical placement, and sidebar tokens.
+- [Slideout](./slideout.md): desktop and mobile side panel with header/footer actions, scrollable slots, example content, and RTL support.
+- [Scroll Area](./scroll-area.md): Radix ScrollArea wrapper with tokenized viewport, scrollbar, thumb, and corner styling.
+- [Slider](./slider.md): accessible value and range control with single, range, multi-thumb, vertical, ticked, pill, tone, size, disabled, and RTL variants.
+- [Skeleton](./skeleton.md): token-built loading placeholders for text, avatars, actions, forms, cards, lists, tables, shimmer motion, and RTL surfaces.
+- [Social Button](./social-button.md): sign-in action primitive for supported providers with solid, outline, icon-only, focus, and RTL states.
+- [Spinner](./spinner.md): compact steady and dynamic loading spinners with inherited color and tokenized sizing.
+- [Steps](./steps.md): horizontal and vertical progress indicators with icon or number markers, item-level slots/actions, and RTL support.
+- [Table](./table.md): composable table and data-table workflow with selectable rows, sortable headers, search, filters, pagination, row states, RTL support, and reusable cell item variants.
+- [Tabs](./tabs.md): Radix Tabs-backed local navigation with underline, segmented, and rounded treatments across LTR and RTL.
+- [Textarea](./textarea.md): multiline field with labels, helper and error text, default and tags modes, placeholder, filled, disabled, and RTL states.
+- [Timeline](./timeline.md): vertical and horizontal progress/event sequences with default or icon markers, states, dates, captions, and RTL support.
+- [Toast](./toast.md): Sonner-style feedback primitive with semantic intents, action support, Banhaten token styling, and logical RTL placement.
+- [Tag](./tag.md): compact metadata, filter, and removable-selection chip with type, state, size, close-button, and RTL variants.
+- [Toggle](./toggle.md): switch-style boolean control with sm/md sizes, optional handle icons, labeled leading/trailing rows, supporting text, and RTL support.
+- [Toolbar](./toolbar.md): filter and action toolbar with search, select triggers, icon buttons, chips, summaries, desktop/mobile styles, and RTL support.
+- [Tooltip](./tooltip.md): Radix Tooltip-backed help surface with dark/default variants, pointer positions, shortcut/close slots, and RTL support.
+- [Typography](./typography.md): documentation for existing `.bh-text-*` token utility classes.
+
+## AI Conversation
+
+Components for agent conversations: thinking states, streaming responses, citations, task progress, the prompt composer, and human-in-the-loop approvals. They compose the core components above, including Rolling Count and Shimmer Text, and move on the shared `--bh-duration-*` and `--bh-easing-*` foundation tokens.
+
+- [Agent Input](./agent-input.md): AI prompt composer with an auto-growing editor, slash-command skill palette, skill and attachment chips, add menu, prompt enhancement, and send action.
+- [Approval Card](./approval-card.md): human-in-the-loop decision cards for questions, shell command approval, and plan sign-off with an opt-in auto-approve countdown.
+- [Inline Citations](./inline-citations.md): prose with linked superscript citation chips, hover reference names, and a compact source list.
+- [Streaming Text](./streaming-text.md): token-by-token text reveal with a slim caret that stays solid while streaming and blinks when complete.
+- [Task List](./task-list.md): collapsible agent progress tracker with pending, active, and done rows, a list-to-pie-to-check header icon, and rolling counters.
+- [Thinking Reasoning](./thinking-reasoning.md): animated, collapsible reasoning block that reveals sentences as they arrive and folds into a Thought for Ns summary.
+- [Thinking State](./thinking-state.md): shimmering status label for the pre-response beat.