banhaten 0.1.2 → 0.2.0

package/docs/design-system/component-showcase-consistency-report.md

@@ -0,0 +1,217 @@
+# Component Showcase Consistency Report
+
+Date: 2026-06-16
+
+## Purpose
+
+This report audits how registry-backed Banhaten components are presented across the playground and docs. The immediate question was whether `Button` is the most complete example and whether the rest of the components should be made consistent with it.
+
+## Short Answer
+
+`Button` is the strongest content baseline, but it is not ready to be copied as the implementation template.
+
+Use `Button` as the reference for what a complete component page should explain: install, usage, examples, composition, API, RTL, states, variants, sizes, and token/effect readouts. Use the shared `RegistryComponentDocs` renderer as the scalable page skeleton, then attach optional deep reference sections when the component needs visual matrices, state grids, size scales, or token readouts.
+
+## Checks Run
+
+- `npm exec -- tsc -p tsconfig.json --noEmit` from `playground` passed.
+- `npm --prefix playground run test:docs` passed.
+  - Component docs coverage audit passed for 41 registry-backed pages.
+  - `catalog-components` is intentionally covered as a registry bundle alias.
+- `npm run registry:check` passed.
+  - Registry mirrors and expanded ownership match across 149 files.
+
+## Current Inventory
+
+- Registry items: 42 total.
+- Core items: 28.
+- Expanded items: 14.
+- Playground pages: 41 registry-backed pages plus 1 bundle-only registry item.
+- Pages using shared `RegistryComponentDocs`: 32.
+- Interactive inspector sections rendered on component pages: 0. The previous custom inspector panels and shared inspector helper were removed from the playground.
+- Bespoke pages with hand-authored docs navigation: 9.
+- Components with markdown docs in `docs/design-system/components` or known top-level docs: 27 of 42.
+- Components with registry RTL metadata: 27 of 42.
+
+## Recommended Standard
+
+Every public component page should use this consistent pattern:
+
+1. Page header with short component purpose.
+2. Above-the-fold live preview:
+   - Small title and concise subtitle.
+   - The real component visible immediately without scrolling past long prose.
+   - A vertical stack of example cards so wide components, such as tables, do not get squeezed into a two-column preview.
+   - English/LTR example first, then Arabic/RTL directly below it for every component where direction, copy, icon placement, or layout can change.
+3. Shared registry docs:
+   - Preview
+   - Installation
+   - Usage
+   - Examples
+   - Composition
+   - API Reference
+   - RTL Behavior
+   - Live Variants
+4. Visual reference, state matrix, size scale, placement matrix, or token reference rendered from live components when deeper inspection is useful.
+5. No interactive inspector section in the component page body.
+6. Registry metadata that matches the real source, example, and playground spec.
+7. Markdown docs linked from the component docs index when the component is public.
+8. Tests that catch missing docs routes, registry mirror drift, and obvious source/metadata drift.
+
+## Button Baseline Audit
+
+### What Button Does Well
+
+`Button` is currently the most complete component page by depth. It has:
+
+- Installation, usage, example, composition, API, RTL, visual reference, size scale, state matrix, and shadow reference sections.
+- Rich examples for variants, sizes, icons, loading, `asChild`, and RTL.
+- Token readouts for fill, text, stroke, effects, geometry, and typography.
+- Registry demo coverage for variants, text sizes, icon sizes, icon placement, loading, and RTL.
+
+### What Button Is Missing Or Inconsistent
+
+- Registry size metadata now matches the implementation and examples, including `xl` and `icon-xl`.
+- Source supports compatibility variants that are not part of the visible registry contract: `destructive`, `soft-destructive`, `success`, `warning`, and `link`. Decide whether these are public aliases, deprecated aliases, or should be removed.
+- Button now has a component markdown page and is listed in the component docs index.
+- The interactive inspector has been removed from the Button page, matching the new page direction.
+- The page is a high-quality bespoke file rather than a scalable shared template. Copying it component by component would increase drift.
+- Test coverage only smoke-renders a basic Button. It does not assert the variant/size contract, `asChild`, loading composition, icon sizing, or source/metadata parity.
+
+### Verdict
+
+Button should be the content-quality model, not the code-shape model. Its opening preview, registry size metadata, and component markdown docs now match the proposed standard. The remaining work is the source-supported alias policy and a metadata parity check.
+
+## Presentation Families
+
+| Family | Components | Current read |
+| --- | --- | --- |
+| Bespoke rich docs plus deep reference | Button, Attribute, Card, Toggle, Modal, Toolbar, Slider, Progress, Alert | Most complete editorially, but highest drift risk because docs are hand-authored per page. Inspector sections should stay removed. |
+| Shared registry docs plus live reference examples | Accordion, Avatar, Badge, Button Group, Checkbox, Date Picker, Divider, Input, Menu, Pagination, Progress Slider, Radio Card, Radio Group, Select, Social Button, Tag, Textarea | Best scalable direction. These already get consistent docs structure from the shared renderer and should add early examples where missing. |
+| Shared registry docs plus expanded custom page | Activity Feed, Banner, Breadcrumbs, Command Bar, File Upload, Onboarding Step, Page Header, Slideout, Steps, Table, Tabs, Timeline | Consistent shell, but registry metadata is under-specified for capabilities and RTL. Expanded/core contract needs a decision. |
+| Shared docs only or custom examples | Tooltip, Spinner, Icons | Acceptable for Spinner and maybe Icons. Tooltip should keep a placement/pointer matrix rather than an inspector. |
+| Bundle-only registry item | Catalog Components | No direct playground page. This is fine if it remains an internal bundle alias; otherwise it needs a public docs page or should be marked as non-public. |
+
+## Component-by-Component Status
+
+| Component | Status | Current presentation | Recommendation |
+| --- | --- | --- | --- |
+| Accordion | Core | Shared docs plus live reference | Keep template. Add markdown docs if public. |
+| Activity Feed | Expanded | Shared docs plus expanded custom page | Add registry capability and RTL metadata. Decide whether it is production or showcase. |
+| Alert | Core | Bespoke rich docs plus deep reference | Strong page. Migrate structure into shared standard or extract page data. |
+| Attribute | Core | Bespoke rich docs plus deep reference | Strong page. Migrate to shared standard; keep detailed slot/composition examples. |
+| Avatar | Core | Shared docs plus live reference | Keep template. Add markdown docs if public. |
+| Badge | Core | Shared docs plus live reference | Keep template. Add markdown docs if public. |
+| Banner | Expanded | Shared docs plus expanded custom page | Add capability and RTL metadata. Promotion candidate for feedback components. |
+| Breadcrumbs | Expanded | Shared docs plus expanded custom page | Add capability and RTL metadata. Promotion candidate with Page Header. |
+| Button | Core | Bespoke baseline | Treat as content baseline. Keep the new above-the-fold examples; resolve variant alias policy and parity tests. |
+| Button Group | Core | Shared docs plus live reference | Good scalable page. Already has markdown docs. |
+| Card | Core | Bespoke rich docs plus deep reference | Strong page. Migrate to shared standard; preserve image/layout coverage. |
+| Checkbox | Core | Shared docs plus live reference | Keep template. Add markdown docs if public. |
+| Command Bar | Expanded | Shared docs plus expanded custom page | Add capability and RTL metadata. Clarify keyboard/search contract before promotion. |
+| Date Picker | Core | Shared docs plus live reference | Good scalable page. Keep as shared-docs example for complex form components. |
+| Divider | Core | Shared docs plus live reference | Good. Simple component can keep a lighter visual reference. |
+| File Upload | Expanded | Shared docs plus expanded custom page | Add accessibility/error/queue contract before core promotion. |
+| Icons | Expanded/foundation | Shared docs/explorer only | Treat as foundation tooling, not a normal component. Keep top-level docs or move into components index intentionally. |
+| Input | Core | Shared docs plus live reference | Keep template. Add markdown docs if public. |
+| Menu | Core | Shared docs plus live reference | Keep template. Add markdown docs if public. Confirm trigger/anchoring expectations. |
+| Modal | Core | Bespoke rich docs plus deep reference | Strong page. Migrate to shared standard; preserve ConfirmModal guardrail docs. |
+| Onboarding Step | Expanded | Shared docs plus expanded custom page | Add capability and RTL metadata. Rename docs/page consistently around `onboarding-step` vs `onboarding-step-list-item`. |
+| Page Header | Expanded | Shared docs plus expanded custom page | Add capability and RTL metadata. Likely app composition pattern, not primitive. |
+| Pagination | Core | Shared docs plus live reference | Keep template. Add markdown docs if public. |
+| Progress | Core | Bespoke rich docs plus deep reference | Strong page. Migrate to shared standard; preserve label/RTL fill coverage. |
+| Progress Slider | Core | Shared docs plus live reference | Keep template. Add markdown docs if public. |
+| Radio Card | Core | Shared docs plus live reference | Keep template. Add markdown docs if public. Clarify explicit RTL behavior in docs. |
+| Radio Group | Core | Shared docs plus live reference | Keep template. Add markdown docs if public. |
+| Select | Core | Shared docs plus live reference | Keep template. Add markdown docs if public. Good candidate for metadata parity tests because it has many item types. |
+| Slideout | Expanded | Shared docs plus expanded custom page | Add focus/portal/mobile contract before core promotion. |
+| Slider | Core | Bespoke rich docs plus deep reference | Strong page. Migrate to shared standard; preserve value mode and indicator examples. |
+| Social Button | Core | Shared docs plus live reference | Keep template. Add markdown docs if public and document provider-color exceptions. |
+| Spinner | Core | Shared docs only | Probably acceptable as a simple primitive. Add markdown docs or explicitly mark as helper primitive. |
+| Steps | Expanded | Shared docs plus expanded custom page | Add capability and RTL metadata. Promotion candidate. |
+| Table | Expanded | Shared docs plus expanded custom page | Add capability and RTL metadata. Clarify Table vs DataTable public contract. |
+| Tabs | Expanded | Shared docs plus expanded custom page | Move or link top-level `docs/design-system/tabs.md` from the component index. Promotion candidate. |
+| Tag | Core | Shared docs plus live reference | Good scalable page. Already has markdown docs. |
+| Textarea | Core | Shared docs plus live reference | Keep template. Add markdown docs if public. |
+| Timeline | Expanded | Shared docs plus expanded custom page | Add capability and RTL metadata. Clarify event/progress variants before promotion. |
+| Toggle | Core | Bespoke rich docs plus deep reference | Strong page. Migrate to shared standard; preserve labeled field composition. |
+| Toolbar | Core | Bespoke rich docs plus deep reference | Strong page. Migrate to shared standard; preserve responsive/filter examples. |
+| Tooltip | Core | Shared docs plus custom pointer examples | Keep the placement matrix as the equivalent deep reference. Already has markdown docs. |
+| Catalog Components | Expanded bundle | No playground page | Mark private/bundle-only, keep alias coverage, or create a real public docs page. |
+
+## Cross-Cutting Gaps
+
+### P0: Fix Contract Drift
+
+- Decide the public/deprecated status of Button compatibility variants: `destructive`, `soft-destructive`, `success`, `warning`, and `link`.
+- Add a parity check that compares registry metadata values against obvious exported spec/example usage for variants and sizes.
+
+### P0: Pick One Page Standard
+
+Adopt this as the canonical implementation pattern:
+
+- Above-the-fold hero preview that shows the component immediately after the title/subtitle.
+- Early stacked examples: English/LTR first, Arabic/RTL directly below when the component can reasonably render Arabic copy or direction-aware layout.
+- Shared `RegistryComponentDocs` for the common docs surface.
+- Optional "Deep Reference" section for state matrices, size scales, pointer matrices, token readouts, and layout grids.
+
+This keeps the consistency of the shared renderer while preserving the richness of Button/Slider/Modal-style pages.
+
+### P1: Normalize Markdown Docs
+
+The component docs index currently covers only part of the registry surface. Public components missing component markdown docs are:
+
+- Accordion
+- Avatar
+- Badge
+- Checkbox
+- Input
+- Menu
+- Pagination
+- Progress Slider
+- Radio Card
+- Radio Group
+- Select
+- Social Button
+- Spinner
+- Textarea
+- Catalog Components, if public
+
+Tabs and Icons have top-level docs, but not under `docs/design-system/components`. Either link them explicitly from the component index or move them under the components directory.
+
+### P1: Fill Expanded Metadata
+
+Expanded components often show RTL and multiple states in demos, but their registry metadata does not expose RTL or capability keys. Add metadata for:
+
+- Activity Feed
+- Banner
+- Breadcrumbs
+- Command Bar
+- File Upload
+- Onboarding Step
+- Page Header
+- Slideout
+- Steps
+- Table
+- Tabs
+- Timeline
+
+This makes the shared API/RTL sections truthful instead of generic.
+
+### P1: Define Simple-Component Exceptions
+
+Spinner probably does not need a deep reference section. Icons is closer to foundation tooling than a reusable component primitive. These exceptions should be explicit so they do not look accidentally incomplete.
+
+### P2: Migrate Bespoke Pages Gradually
+
+Do not rewrite the best pages all at once. Start with one or two:
+
+1. Button: fix metadata and use it to define the standard.
+2. Alert or Progress: migrate a smaller bespoke rich page to validate the shared-plus-reference pattern.
+3. Modal or Slider: migrate a complex page once the pattern feels stable.
+
+## Suggested Decision
+
+Make Button the quality bar, but make `above-the-fold examples + RegistryComponentDocs + optional Deep Reference` the page architecture. Then measure every component against that architecture.
+
+That gives us a consistent system without losing the parts that make the Button page valuable.

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

@@ -0,0 +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`.

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

@@ -0,0 +1,75 @@
+# 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.
+- [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.

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

@@ -0,0 +1,67 @@
+# Accordion
+
+Accordion is the disclosure primitive for grouped details, settings, FAQs, and compact content sections. It is backed by Radix Accordion and supports single or multiple expansion, size variants, visual treatments, animation, and RTL-safe copy.
+
+## API
+
+```tsx
+<Accordion type="single" collapsible>
+  <AccordionItem value="billing">
+    <AccordionTrigger>Billing</AccordionTrigger>
+    <AccordionContent>Invoice and payment details.</AccordionContent>
+  </AccordionItem>
+</Accordion>
+```
+
+| Prop | Values | Default |
+| --- | --- | --- |
+| `variant` | `default`, `bordered`, `cards`, `soft` | `default` |
+| `size` | `sm`, `default`, `lg` | `default` |
+| `type` | Radix `single`, `multiple` | required |
+| `collapsible` | `boolean` | Radix default |
+
+## Token Contract
+
+Accordion uses Banhaten spacing, border, radius, content, interactive, typography, and animation tokens. Avoid raw colors or pixel values in local variants.
+
+## RTL
+
+Accordion inherits direction from its parent. Triggers and content use logical spacing and `text-start`; text labels use `dir="auto"` where the component renders string copy.
+
+## Accessibility
+
+Radix provides button semantics, `aria-expanded`, roving state, and keyboard behavior. Keep trigger content concise and do not put nested interactive controls inside `AccordionTrigger`.
+
+## Install
+
+```bash
+npx banhaten add accordion
+```
+
+## Examples
+
+Primary registry example: `examples/accordion-demo.tsx`.
+
+Open the live component page or run `npx banhaten docs accordion` to inspect source files, install command, and examples.
+
+## RTL Rules
+
+- `inheritsDirection`: true
+- `textAlignment`: Uses text-start and dir="auto" so Arabic and English copy align and punctuate naturally.
+- `spacing`: Uses gap and logical inherited direction rather than physical left/right spacing.
+
+<!-- registry-contract:start -->
+## Registry Contract
+
+This table is generated from `registry/index.json`; edit the component-owned source under `registry/catalog/components/`, not this table or the compiled index.
+`supportedExports` is the exhaustive runtime import contract grouped by source module. `parts` is an ordered, non-exhaustive anatomy list.
+
+| Field | Values |
+| --- | --- |
+| `supportedExports` | `components/accordion.tsx: Accordion, AccordionContent, AccordionItem, AccordionTrigger, accordionVariants` |
+| `parts` | `Accordion`, `AccordionItem`, `AccordionTrigger`, `AccordionContent` |
+| `registryDependencies` | None |
+| `sizes` | `sm`, `default`, `lg` |
+| `tokens` | `--bh-bg-neutral-subtle`, `--bh-bg-raised`, `--bh-border-subtle`, `--bh-content-default`, `--bh-content-muted`, `--bh-content-subtle`, `--bh-duration-accordion`, `--bh-duration-default`, `--bh-easing-out`, `--bh-opacity-50`, `--bh-radius-md-6`, `--bh-radius-xs-2`, `--bh-space-3xl-16`, `--bh-space-4xl-20`, `--bh-space-md-8`, `--bh-space-xl-12`, `--bh-space-xs-4`, `--bh-space-xxs-2`, `--bh-space-xxxs-1`, `--bh-text-body-md-medium-font-size`, `--bh-text-body-md-medium-line-height`, `--bh-text-body-md-regular-font-size`, `--bh-text-body-md-regular-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`, `--bh-text-body-sm-regular-font-size`, `--bh-text-body-sm-regular-font-weight`, `--bh-text-body-sm-regular-letter-spacing`, `--bh-text-body-sm-regular-line-height`, `--bh-text-body-xs-medium-font-size`, `--bh-text-body-xs-medium-line-height`, `--bh-text-body-xs-regular-font-size`, `--bh-text-body-xs-regular-line-height`, `--shadow-accordion-item`, `--shadow-button-focus` |
+| `variants` | `default`, `bordered`, `cards`, `soft` |
+<!-- registry-contract:end -->

package/docs/design-system/components/activity-feed.md

@@ -0,0 +1,106 @@
+# Activity Feed
+
+`ActivityFeed` renders a vertical timeline of activity items with avatars, status dots, captions or slot content, timestamps, and action buttons.
+
+Figma reference: `Design system 3.0 Copy / ActivityFeed`, component set node `587:19445`.
+
+## Variants
+
+The Figma component defines these top-level variants:
+
+| Direction | Node |
+| --- | --- |
+| LTR | `587:19381` |
+| RTL | `587:19711` |
+
+`ActivityFeedItem` also supports `caption` and `slot` item types through the `type` prop.
+
+## API
+
+```tsx
+<ActivityFeed
+  dir="ltr"
+  items={[
+    {
+      label: "Label",
+      supportText: "Support Text",
+      link: "#Link",
+      caption: "Caption text",
+      timestamp: "Mar 15. 2050",
+      type: "caption",
+    },
+  ]}
+/>
+```
+
+| Prop | Values | Default |
+| --- | --- | --- |
+| `dir` | `ltr`, `rtl` | `ltr` |
+| `items` | `ActivityFeedItemProps[]` | ten caption items |
+| `avatarSrc` | `string` | local Figma avatar asset |
+| `type` | `caption`, `slot` | `caption` |
+| `hasStatus` | `boolean` | `true` |
+| `hasActionButtons` | `boolean` | `true` |
+| `hasTwoActionButtons` | `boolean` | `true` |
+| `showLine` | `boolean` | `true` |
+| `showPaddingBottom` | `boolean` | `true` |
+
+## 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.
+
+- Backgrounds: `--bh-bg-raised`, `--bh-bg-success-default`
+- Borders: `--bh-border-default`, `--bh-border-subtle`
+- Content: `--bh-content-default`, `--bh-content-link`, `--bh-content-on-brand`, `--bh-content-subtle`
+- Interactive: `--bh-interactive-brand-default`, `--bh-interactive-secondary-default`
+- Shape: `--bh-radius-full`, `--bh-radius-sm-4`, `--bh-control-default`
+- Space: `--bh-space-xxs-2`, `--bh-space-xs-4`, `--bh-space-md-8`, `--bh-space-lg-10`, `--bh-space-xl-12`
+
+## Pixel Rules
+
+- Feed width is `600px`.
+- Items use a `12px` gap between the indicator rail and content.
+- Avatar is `32px` square with a full radius and subtle border.
+- The status dot renders in a `16px` box with a `6px` success fill.
+- Body text is Inter `15px / 24px`; timestamps are `14px / 20px`.
+- Captions use `12px` padding, subtle border, white raised fill, and `4px` radius.
+- Slot content is `76px` high with purple dashed border and subtle purple fill.
+- Actions use `8px` top padding, `8px` button gap, and `36px` tall buttons.
+- The repeated-item default uses a `22px` decorative bottom spacer so ten items fit the `2000px` Figma feed frame.
+- RTL mirrors the avatar rail to the right and right-aligns text content.
+
+## Accessibility
+
+- The feed uses a labelled `section`; provide `ariaLabel` when the surrounding context is not explicit.
+- Status dots and connector lines are decorative. Use item copy or parent-level announcements for meaningful state.
+- Action buttons are real `button` or `a` elements and support `ariaLabel`, `disabled`, `href`, and `onClick`.
+
+## Install
+
+```bash
+npx banhaten add activity-feed
+```
+
+## Examples
+
+Primary registry example: `examples/expanded/activity-feed-demo.tsx`.
+
+Open the live component page or run `npx banhaten docs activity-feed` 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
+
+This table is generated from `registry/index.json`; edit the component-owned source under `registry/catalog/components/`, not this table or the compiled index.
+`supportedExports` is the exhaustive runtime import contract grouped by source module. `parts` is an ordered, non-exhaustive anatomy list.
+
+| Field | Values |
+| --- | --- |
+| `supportedExports` | `components/expanded/ActivityFeed.tsx: ActivityFeed, ActivityFeedItem` |
+| `parts` | `ActivityFeed`, `ActivityFeedItem` |
+| `registryDependencies` | `button` |
+| `tokens` | `--bh-activity-feed-compact-width`, `--bh-bg-accent-purple-subtle`, `--bh-bg-raised`, `--bh-bg-success-default`, `--bh-border-accent-purple-strong`, `--bh-border-default`, `--bh-border-subtle`, `--bh-content-default`, `--bh-content-link`, `--bh-content-on-brand`, `--bh-content-subtle`, `--bh-control-default`, `--bh-font-family`, `--bh-font-weight-medium`, `--bh-font-weight-regular`, `--bh-font-weight-semibold`, `--bh-interactive-brand-default`, `--bh-interactive-secondary-default`, `--bh-radius-full`, `--bh-radius-sm-4`, `--bh-space-3xl-16`, `--bh-space-4xl-20`, `--bh-space-6xl-32`, `--bh-space-8xl-48`, `--bh-space-9xl-64`, `--bh-space-lg-10`, `--bh-space-md-8`, `--bh-space-sm-6`, `--bh-space-xl-12`, `--bh-space-xs-4`, `--bh-space-xxs-2`, `--bh-space-xxxs-1`, `--bh-text-base-letter-spacing`, `--bh-text-body-md-font-size`, `--bh-text-body-md-line-height`, `--bh-text-body-sm-regular-font-size`, `--bh-text-body-sm-regular-line-height`, `--bh-text-body-xs-regular-font-size`, `--shadow-button-raised`, `--shadow-component-default` |
+<!-- registry-contract:end -->