banhaten 0.2.0 → 0.4.0

package/CHANGELOG.md

@@ -2,6 +2,61 @@
 
 All notable Banhaten changes are recorded here. Releases follow the policy in `docs/design-system/release-policy.md`.
 
+## 0.4.0 - 2026-08-22
+
+### Added
+
+- A Figma-aligned Sidebar composition with brand and workspace headers, header and group actions, menu badges, nested and tree navigation, user footers, rail tooltips, controlled state, and documented expanded, collapsed, LTR, and RTL variants.
+- `Shortcut`, a compact combined keyboard-chord primitive for inputs and constrained action rows, alongside the existing separated-keycap `KbdShortcut` API.
+- A Test Lab V2 playground with scenario navigation, a focused inspector, state-comparison boards, responsive previews, and browser coverage for the new QA workflow.
+- Noto Sans Arabic as the default Arabic playground font, with the previous Arabic font options retained.
+
+### Changed
+
+- The default brand theme is now monochrome `gray`; `blue` remains available as an explicit alternate theme.
+- Elevation now publishes the complete seven-level Figma scale as `--shadow-xs` through `--shadow-3xl`, with dedicated reviewed light and dark values and updated token documentation.
+- Shared icon and icon-slot geometry is tokenized across controls, navigation, feedback, and data-display components for more consistent alignment.
+- Sidebar defaults now use a 280px expanded shell and a 48px collapsed rail, with logical placement and spacing throughout.
+
+### Fixed
+
+- Sidebar focus, tooltip, collapse, nesting, active-state, narrow-layout, and RTL behavior across both controlled and uncontrolled compositions.
+- Component icon sizing, spacing, and state styling across Alert, Avatar, Button Group, Date Picker, Input, Item, Menu, Pagination, Select, Tag, Toolbar, and expanded compositions.
+- Playground token enforcement now uses explicit Banhaten shadow variables in every Test Lab surface.
+
+### Migration
+
+- To retain the previous blue default, set `data-theme="blue"` on the themed root; roots without `data-theme` now resolve to gray.
+- Review custom Sidebar shells before updating because the canonical expanded and collapsed widths and the recommended header, menu, and footer composition have changed. Run `npx banhaten diff sidebar` before `npx banhaten update sidebar`, and use `--force` only after reviewing local generated-file changes.
+
+## 0.3.0 - 2026-08-21
+
+### Added
+
+- `ActivityHeatmap`, a token-only expanded component with five intensity levels, accessible summary semantics, responsive overflow, inherited RTL behavior, registry metadata, documentation, and an installable example.
+- Public `CardSurface`, semantic table-element exports, and `ProgressSteps` APIs for owned product composition without bypassing Banhaten primitives.
+- An AST-backed component-ownership gate plus route-wide accessibility, inherited-RTL containment, and deterministic visual-regression coverage for every component page.
+
+### Changed
+
+- Expanded components and all 38 audited playground backgrounds now compose Banhaten-owned controls; Alert, Page Header, and Slideout declare their new Button and Breadcrumbs registry dependencies.
+- Direction inheritance, narrow-layout containment, focus behavior, and machine-readable RTL contracts were completed across the 68-component catalog.
+- Elevation and color-mode sources were consolidated around shared semantic effects, and the canonical contrast audit was expanded to 910 passing scenarios.
+- Page Header accepts `headingLevel`; Timeline labels and captions accept React nodes; horizontal timelines are keyboard-scrollable and standalone `TimelineItem` semantics are now caller-controlled.
+
+### Fixed
+
+- ARIA ownership, naming, focus, landmark, and relationship defects across Date Picker, Select, Command, Tabs, Field, Table, Menu, Carousel, Sidebar, Slideout, Timeline, and composed documentation examples.
+- Contrast failures across component states and themes, including focus indicators, selected states, badges, tags, alerts, banners, toggles, social buttons, and tables.
+- Inherited-RTL and 324px containment defects in activity, navigation, form, data-display, and expanded layout components.
+
+### Migration
+
+- `SidebarInset` now renders a neutral `div` instead of an implicit `main`. When the inset is the page landmark, render your own `<main>` through `<SidebarInset asChild><main>...</main></SidebarInset>`.
+- `Slideout` is an explicitly named presentational region. Use `Sheet` or `Modal` when the experience requires a portal, overlay, focus trap, Escape dismissal, and focus return.
+- A standalone `TimelineItem` no longer assumes `role="listitem"`; use it inside `Timeline` or pass an explicit role when composing your own list.
+- Run `npx banhaten diff` before `npx banhaten update`, then review locally customized generated files before using `--force`.
+
 ## 0.2.0 - 2026-08-08
 
 ### Added

package/README.md

@@ -109,10 +109,10 @@ Token modes:
 - Radius mode: `default`, `rounded`, `sharp`.
 - Direction: inherited LTR or RTL, with component-level `dir` support where needed.
 
-The default appearance is the `blue` brand theme composed with the achromatic
-`gray` neutral scale. This keeps page, card, border, and muted surfaces neutral
-while links, focus states, and primary actions remain blue. The `gray` theme is
-still a separate monochrome brand option; it changes the brand roles as well.
+The default appearance is the monochrome `gray` brand theme. It keeps page,
+card, border, and muted surfaces neutral while applying gray to links, focus
+states, and primary actions as well. `blue` remains available as an alternate
+brand theme.
 
 Example:
 
@@ -162,7 +162,7 @@ Markdown docs live in `docs/design-system/components`. They are checked for inst
 
 Launch guides cover [installation](docs/design-system/installation.md), [direction and localization](docs/design-system/direction-and-localization.md), [form recipes](docs/design-system/form-recipes.md), [density and elevation](docs/design-system/density-and-elevation.md), the [support matrix](docs/design-system/support-matrix.md), and the [release policy](docs/design-system/release-policy.md).
 
-The durable [launch comparison with shadcn/ui](docs/design-system/launch-comparison-shadcn.md) records every audited area, remediation, verification gate, contrast exception, and deliberate non-copying decision.
+The durable [launch comparison with shadcn/ui](docs/design-system/launch-comparison-shadcn.md) records every audited area, remediation, verification gate, the closed 910/910 contrast contract, and deliberate non-copying decisions.
 
 Useful commands:
 

package/docs/design-system/component-implementation-ownership-audit.md

@@ -0,0 +1,245 @@
+# Component Implementation and Ownership Audit
+
+Audit date: 2026-08-20
+
+Remediation status: complete for the requested 96 component-ownership gaps
+
+## Executive status
+
+The requested component-gap remediation is complete.
+
+- **96 of 96 requested issues are closed.**
+- All **94 background component-kind gaps** were replaced with Banhaten-owned components or compositions and removed from scenario metadata.
+- The two untracked ownership violations were fixed:
+  - Activity Heatmap period controls now use Segmented Control in the live page, copyable example, and customer-activity background.
+  - Scroll Area alternatives now use the Banhaten Scroll Area API and no longer import Radix directly.
+- All **38 of 38 audited backgrounds** now pass the enforced component-only consumer rule.
+- Those backgrounds contain **zero native button, input, select, textarea, or table roots**.
+- Playground consumer source contains **zero direct imports from the restricted UI-vendor set**.
+- A new AST-based ownership gate prevents those regressions from returning.
+
+This is a pass for the requested component-ownership scope. The subsequent full component-quality audit also closed the five expanded-component primitive-reuse notes, so there are no known visible-control ownership exceptions in the component catalog. It is not a claim that every reference background is visually complete: **100 non-component fidelity gaps remain** and are tracked separately.
+
+## Before and after
+
+| Measure | Before | Current | Status |
+| --- | ---: | ---: | --- |
+| Requested ownership issues | 96 | 0 open | Pass |
+| Background component-kind gaps | 94 | 0 | Pass |
+| Missing-component gaps | 47 | 0 | Pass |
+| Component approximations | 47 | 0 | Pass |
+| Strict component-only backgrounds | 2 of 38 | 38 of 38 | Pass |
+| Native control/table roots in audited backgrounds | 27 | 0 | Pass |
+| Activity Heatmap raw period-control usages | 3 surfaces | 0 | Pass |
+| Scroll Area direct Radix consumer imports | 1 page | 0 | Pass |
+| Automated ownership boundary | Absent | Enforced in playground test and root check | Pass |
+| Non-component visual gaps | 100 | 100 | Outside this remediation |
+
+The remaining visual-gap inventory is:
+
+| Gap kind | Count |
+| --- | ---: |
+| Layout/composition fidelity | 47 |
+| Icon assets | 20 |
+| Image assets | 20 |
+| Tokens | 13 |
+| **Total** | **100** |
+
+## What changed
+
+### Ownership violations
+
+- [ActivityHeatmapPage.tsx](../../playground/src/pages/new-components/ActivityHeatmapPage.tsx) now composes SegmentedControl and SegmentedControlItem in both published code and the live example.
+- [customer-activity-dashboard/index.tsx](../../playground/src/app/backgrounds/customer-activity-dashboard/index.tsx) uses the same owned segmented-control contract.
+- [ScrollAreaPage.tsx](../../playground/src/pages/ScrollAreaPage.tsx) no longer imports or assembles Radix primitives.
+- [scroll-area.tsx](../../registry/components/scroll-area.tsx) now exposes vertical, horizontal, and combined orientation behavior through the Banhaten API.
+
+### Reusable APIs promoted to close repeated gaps
+
+- [table-elements.tsx](../../registry/components/table-elements.tsx) adds Banhaten-owned semantic table and data-surface elements.
+- [card.tsx](../../registry/components/card.tsx) adds CardSurface for product-specific card composition without redrawing a card shell.
+- [sidebar.tsx](../../registry/components/sidebar.tsx) supports standalone owned sidebar surfaces while preserving provider-aware behavior for interactive sidebar parts.
+- [Steps.tsx](../../registry/components/expanded/Steps.tsx) adds ProgressSteps with bar and marker variants.
+- [Timeline.tsx](../../registry/components/expanded/Timeline.tsx) accepts richer label/caption content and local styling hooks needed by migrated flows.
+
+### Background migrations
+
+The 38 reference backgrounds were audited and migrated as a complete set. The repeated replacements include:
+
+- Native buttons to Button, Button Group, Segmented Control, or the relevant owned action component.
+- Handcrafted switches to Toggle.
+- Native inputs/selects/textareas to the matching Banhaten form owner.
+- Native data tables and ARIA table shells to TableRoot or DataTableSurface compositions.
+- Handcrafted cards to CardSurface.
+- Root application sidebars to Sidebar.
+- Custom progress bars, numbered setup flows, and status tracks to ProgressSteps, Steps, or Timeline.
+- Product chips and variables to Tag, Badge, and Avatar composition.
+
+Component-gap metadata and component-gap DOM markers were removed only after the corresponding implementations migrated and passed type, unit, build, and browser checks.
+
+## Enforced ownership boundary
+
+The ownership rule is layer-aware:
+
+1. **Registry foundation layer:** Native HTML and declared behavior libraries may be used inside the Banhaten component that owns and publishes that behavior.
+2. **Expanded registry layer:** Higher-level components should compose Banhaten primitives whenever an equivalent owner exists.
+3. **Consumer layer:** Backgrounds, examples, and copyable documentation must use Banhaten components for interactive controls. Passive semantic/layout HTML remains allowed.
+4. **Public integration exceptions:** Recharts remains an intentional extension surface of Chart. No such exception exists for direct Radix, cmdk, Embla, react-resizable-panels, or Sonner imports in playground consumers.
+5. **Test fixtures:** Native elements may be used when a test specifically needs a fixture and does not publish that fixture as product guidance.
+
+[component-ownership.test.mjs](../../playground/src/test/component-ownership.test.mjs) now enforces:
+
+- No direct playground consumer imports from Radix, cmdk, Embla, react-resizable-panels, or Sonner.
+- No native button, input, select, textarea, or table roots in any background implementation.
+- No component-kind background gap metadata.
+- No raw controls or direct restricted-vendor imports in the copyable Activity Heatmap and Scroll Area pages.
+
+The gate runs first in the playground test pipeline and is also available from the repository root as components:ownership:check.
+
+## Component-by-component status
+
+All 68 catalog components remain owned, buildable, installable, documented, token-validated, and runtime-export validated. The status below focuses on implementation ownership after remediation.
+
+| Component | Status | Ownership note |
+| --- | --- | --- |
+| Accordion | Pass | Owned declared Radix wrapper. |
+| Aspect Ratio | Pass | Owned declared Radix wrapper. |
+| Avatar | Pass | Owned declared Radix wrapper. |
+| Badge | Pass | Owned Slot/CVA primitive. |
+| Tag | Pass | Canonical owned tag/chip owner. |
+| Attribute | Pass | Owned structural key/value composition. |
+| Button | Pass | Canonical action owner. |
+| Card | Pass | Owned card family; CardSurface now covers custom card shells. |
+| Chart | Pass — integration | Banhaten owns container, tooltip, legend, and tokens; Recharts children are the documented public extension. |
+| Carousel | Pass — integration | Owned declared Embla behavior with Banhaten controls. |
+| Button Group | Pass | Canonical connected action/toggle owner. |
+| Segmented Control | Pass | Owned mutually exclusive control composed from Button Group. |
+| Toggle | Pass | Owned declared switch behavior. |
+| Menu | Pass | Owned declared Radix menu implementation. |
+| Menubar | Pass | Owned declared Radix menubar implementation. |
+| Command | Pass — integration | Owned cmdk-backed command surface. |
+| Context Menu | Pass | Owned declared Radix context-menu implementation. |
+| Tooltip | Pass | Owned declared Radix tooltip implementation. |
+| Popover | Pass | Owned declared Radix popover implementation. |
+| Hover Card | Pass | Owned declared Radix hover-card implementation. |
+| Modal | Pass | Owned declared dialog behavior and action composition. |
+| Alert Dialog | Pass | Owned declared alert-dialog behavior with Banhaten actions. |
+| Checkbox | Pass | Owned checkbox and checkbox-card behavior. |
+| Collapsible | Pass | Owned declared collapsible implementation. |
+| Radio Group | Pass | Canonical owned radio-group owner. |
+| Radio Card | Pass | Canonical owned radio-card owner. |
+| Divider | Pass | Owned structural separator. |
+| Pagination | Pass | Canonical pagination owner. |
+| Toolbar | Pass | Owned search, action, filter, and select-trigger family. |
+| Social Button | Pass | Owned provider-action primitive. |
+| Input | Pass | Canonical input owner. |
+| Input Group | Pass | Owned grouped input and inline-action surface. |
+| Label | Pass | Owned declared label implementation. |
+| Kbd | Pass | Owned keyboard-hint primitive. |
+| Item | Pass | Owned Slot-based row composition. |
+| Field | Pass | Owned field composition using Label. |
+| Input OTP | Pass | Owned OTP slot and form behavior. |
+| Select | Pass | Owned declared select and rich menu-item surfaces. |
+| Native Select | Pass | Canonical native-select owner. |
+| Sheet | Pass | Owned edge-panel dialog behavior. |
+| Sidebar | Pass | Canonical provider-aware and standalone sidebar owner. |
+| Navigation Menu | Pass | Owned declared navigation-menu implementation. |
+| Scroll Area | Pass | Owned orientation API; direct consumer Radix usage removed. |
+| Resizable | Pass — integration | Owned react-resizable-panels wrapper. |
+| Autocomplete | Pass | Composes Input, Popover, Select, and Tag. |
+| Date Picker | Pass | Owned calendar behavior composed with Banhaten primitives. |
+| Slider | Pass | Owned declared slider implementation. |
+| Progress | Pass | Owned read-only progress primitive. |
+| Progress Slider | Pass | Owned declared interactive progress control. |
+| Textarea | Pass | Canonical textarea owner. |
+| Skeleton | Pass | Owned loading-placeholder family. |
+| Spinner | Pass | Owned loading indicator. |
+| Toast | Pass — integration | Owned Sonner-backed feedback API and token layer. |
+| Activity Feed | Pass | Owned activity composition using Banhaten actions. |
+| Activity Heatmap | Pass | Owned heatmap; period controls now use Segmented Control everywhere published. |
+| Alert | Pass | Canonical alert owner. |
+| Banner | Pass | Composes Banhaten Button and Input. |
+| Catalog Components | Pass | Publishable owned composition; catalog divider actions use Button and the bundle has a dedicated docs page. |
+| Breadcrumbs | Pass | Canonical breadcrumb navigation owner. |
+| File Upload | Pass | Hidden native file input is the valid owned platform hook; all visible browse/retry actions use Button. |
+| Table | Pass | Semantic table surface closes consumer gaps; visible actions use Button and selection/meter semantics are owned. |
+| Empty State | Pass | Uses Banhaten actions, including link composition. |
+| Onboarding Step | Pass | Owned presentational step row. |
+| Page Header | Pass | Composes Breadcrumbs, Tabs, and Button with explicit heading-level and landmark contracts. |
+| Slideout | Pass | Explicitly documented as a named presentational region and composes Button actions; it no longer claims incomplete dialog behavior. |
+| Steps | Pass | Owns standard, horizontal, vertical, and ProgressSteps compositions. |
+| Tabs | Pass | Owned declared tabs implementation. |
+| Timeline | Pass | Owned timeline composition with richer content hooks. |
+
+Component summary:
+
+- **68 of 68** catalog entries pass build, publication, docs, tokens, and isolated-install validation.
+- **68 of 68** have no open primitive-reuse or visible-control ownership note in this audit.
+- The only native interactive element in the expanded layer is File Upload's hidden `input[type=file]`, which is the owning platform behavior rather than a visible consumer bypass.
+
+## Remaining work outside the 96 gaps
+
+### Visual fidelity backlog
+
+The remaining 100 gaps are non-component concerns. The current promotion report identifies four recurring candidate families:
+
+- Workspace shell/layout composition.
+- Icon assets.
+- Elevation treatment.
+- Avatar/image assets.
+
+See [gap-promotion-report.md](./gap-promotion-report.md) for the generated detail.
+
+### Component-quality closure
+
+The former internal primitive-reuse notes are closed: Catalog Divider, File Upload, Table, Page Header, Slideout, and Alert use owned visible actions, while Page Header also composes Breadcrumbs. Slideout is deliberately a named presentational region rather than an incomplete dialog; modal interaction remains owned by Sheet and Modal.
+
+The full route audit now covers all component pages with strict Axe, inherited RTL, 324px document containment, and deterministic Chromium base-card screenshots. Contrast is also clean at 910 of 910 scenarios.
+
+### Structural hotspots
+
+The largest implementation units remain Date Picker, expanded Table, Input, Menu, Select, and Modal. They pass current checks, but splitting helpers/state from public component modules would reduce future change risk.
+
+### Test depth
+
+Every component route has uniform Axe, inherited-RTL, 324px containment, documentation, and visual-baseline coverage. Deep interaction-specific keyboard and focus assertions remain intentionally component-specific because their behavior contracts differ.
+
+## Verification results
+
+| Gate | Result | Evidence |
+| --- | --- | --- |
+| Component ownership | Pass | 38 backgrounds; zero component gaps; zero native controls; zero restricted direct consumer UI-vendor imports. |
+| Background metadata | Pass | 38 scenarios and 100 remaining non-component gaps are internally consistent. |
+| Gap promotion report | Pass | Current with 4 candidates across 38 backgrounds. |
+| TypeScript | Pass | Playground typecheck completed with no errors. |
+| Unit/component tests | Pass | 8 Vitest files and 205 tests. |
+| Documentation coverage | Pass | 68 registry-backed pages; zero pending rollout pages and zero aliases. |
+| Production build | Pass | Vite transformed 3,350 modules and bundle budget passed. |
+| Browser suite | Pass | 389 Playwright tests passed across Chromium, Firefox, and WebKit; 4 engine-deduplicated checks skipped by design. |
+| Registry validation | Pass | 68 catalogs and 113 mirrors; all 68 packed component installs compiled and exported correctly. |
+| Token ownership | Pass | 91 owned token sources; 161 component/example files; metadata current for all 68 components. |
+| Package artifact | Pass | 300 packed files; 96-file registry closure; 72 examples; CLI smoke for all 68 installs. |
+| Documentation contracts | Pass | Markdown checks passed for all 68 components. |
+| Accessibility/RTL/containment | Pass | 69 of 69 component UI routes pass strict Axe and inherited-RTL containment at 324px. |
+| Contrast | Pass | 910 of 910 canonical scenarios pass. |
+| Visual regression | Pass | 69 of 69 canonical Chromium base-card baselines reproduce cleanly. |
+| Patch hygiene | Pass | Git diff whitespace/error check is clean. |
+
+Registry and package checks used an isolated npm cache under /tmp because the user-level npm cache contains root-owned entries. The user cache was not changed.
+
+## Final verdict
+
+**Pass for the requested 96 component-ownership gaps.**
+
+The audited backgrounds and the two named copyable-documentation violations now use Banhaten-owned components, and the invariant is protected by an automated gate. The remaining 100 tracked gaps are visual/layout/token/asset work, not missing or approximated components.
+
+The component catalog is also clean under the broader implementation-quality audit. The remaining 100 tracked gaps are background visual/layout/token/asset fidelity work, not missing, approximated, or bypassed components. This distinction keeps the ownership result reliable without treating the separate background-fidelity backlog as component debt.
+
+## Audit scope
+
+- Repository: /Users/ahmadgalal/Downloads/Work/Banhaten-design-system
+- Canonical surface: 68 registry catalog entries.
+- Consumer remediation surface: all 38 background implementations and scenario descriptors, plus the Activity Heatmap and Scroll Area copyable pages.
+- Generated artifacts validated: registry indexes, runtime mirrors, token metadata, component docs contracts, background catalog, and gap-promotion report.
+- Verification environments: TypeScript, Vitest, Vite production build, isolated packed installs, and Playwright on Chromium, Firefox, and WebKit.
+- Existing unrelated dirty-tree changes were preserved.

package/docs/design-system/component-quality-audit-2026-08-20.md

@@ -0,0 +1,225 @@
+# Component Implementation Quality Audit — Final Status
+
+Audit date: 2026-08-20
+
+Repository: `Banhaten-design-system`
+
+Remediation status: complete for the component-library scope
+
+## Executive verdict
+
+**Pass.** All 68 registry components now pass the repository's implementation, ownership, accessibility, contrast, RTL, responsive-containment, documentation, token, publication, install, unit, build, and browser contracts.
+
+The previous 96 component-ownership gaps remain closed. The wider quality review also closed the concrete ARIA, focus, landmark, contrast, inherited-RTL, narrow-layout, primitive-reuse, metadata, and proof-coverage defects found during the audit.
+
+Current measured status:
+
+- **68 of 68 registry components** are owned, documented on dedicated pages, token-current, packageable, and isolated-install validated.
+- **69 of 69 component UI routes** — the 68 registry pages plus the non-installable Icons explorer — pass the strict route-wide Axe scan and inherited-RTL 324px containment sweep.
+- **69 of 69 routes** have deterministic Chromium base-card visual baselines, and all 69 reproduce without diffs.
+- **910 of 910 contrast scenarios pass**; there are zero known failures in the canonical audit.
+- **38 of 38 audited backgrounds** have zero component-kind gaps, zero native interactive/table roots, and zero restricted direct UI-vendor imports.
+- The final authoritative `npm run check` is green: **389 Playwright tests passed, 4 intentionally browser-deduplicated tests skipped, 205 unit tests passed, and npm reported 0 vulnerabilities.**
+
+This is a 100% audit of the repository's declared component catalog and executable contracts. It is not a claim of pixel equivalence to an external Figma source that was not part of this task. The 100 tracked background fidelity gaps for layout, icon assets, image assets, and tokens remain a separate non-component backlog.
+
+## Scope and assurance model
+
+The audit covered:
+
+- all 68 authored catalog entries and their 113 mirrored registry files;
+- all published component source, CSS, exports, examples, token references, generated metadata, and Markdown contracts;
+- all 68 dedicated registry-backed documentation pages and the Icons explorer;
+- Base and Alternatives content, live Anatomy where a single measurable root exists, and documented exemptions for portals, caller-sized canvases, and the Catalog composition bundle;
+- every live route under LTR and inherited RTL, including 324px viewport containment;
+- all live examples on each page through an unsuppressed Axe scan;
+- state/theme/mode contrast through 910 generated scenarios;
+- consumer ownership across all 38 background implementations;
+- package closure, isolated installs, runtime exports, production build, cross-browser behavior, and visual regression output.
+
+The assurance layers are intentionally different:
+
+1. **Consumer layer:** product backgrounds, copyable examples, and documentation consumers must use Banhaten owners for interactive UI.
+2. **Expanded component layer:** compositions use Banhaten primitives for visible controls. The only native interactive element left in this layer is File Upload's hidden `input[type=file]`, which is the behavior-owning platform input rather than a visible bypass.
+3. **Foundation layer:** Banhaten wrappers may directly use their declared behavior libraries — Radix, cmdk, Embla, react-resizable-panels, Recharts, Sonner — because those wrappers are the owned component boundary.
+4. **Semantic HTML:** elements such as `table`, `nav`, `hr`, headings, and list containers remain correct native structure; ownership does not mean replacing semantics with generic components.
+
+Static scans confirm no raw visible `button`, `select`, or `textarea` controls in expanded components and no restricted UI-vendor imports in playground consumers or expanded components.
+
+## Before and after
+
+| Measure | Audit starting point | Final status |
+| --- | ---: | ---: |
+| Requested component-ownership gaps | 96 open | 0 open |
+| Audited backgrounds using only owned controls | 2 of 38 | 38 of 38 |
+| Missing catalog RTL contracts | 12 | 0 |
+| Dedicated registry-backed component pages | 67 plus 1 alias | 68, no aliases |
+| Canonical contrast audit | 468 pass / 274 fail / 742 total | 910 pass / 0 fail / 910 total |
+| Route-wide automated accessibility | 48 clean / 19 flagged in the initial sweep | 69 clean / 0 flagged |
+| 324px inherited-RTL route containment | Multiple component failures | 69 pass / 0 fail |
+| Per-route component visual baselines | Incomplete | 69 of 69 |
+| Unit/component tests | 187 | 205 passing |
+| Cross-browser Playwright result | 315 passing | 389 passing, 4 intentional skips |
+| Token/example source enforcement | 160 files | 161 files passing |
+
+## Remediation completed
+
+### Semantics and accessibility
+
+- Rebuilt Date Picker's calendar as a valid named ARIA grid with rowgroups, rows, column headers, gridcells, localized labels, and selected-state contrast.
+- Restored Select's Radix-owned combobox state, named standalone listboxes, made internal wrappers presentational, and kept checkbox-styled options valid inside listboxes.
+- Guaranteed a real panel for every Tabs trigger, including Page Header's composed tabs.
+- Corrected Command listbox ownership: separators and internal wrappers are presentational, and empty results are disabled options.
+- Registered only mounted Field descriptions and errors in `aria-describedby`.
+- Made Scroll Area, Button Group, Activity Heatmap, Resizable panel content, horizontal Timeline, and wide Table surfaces keyboard reachable where local scrolling can occur.
+- Added valid Avatar image semantics, named Table progress/rating output, complete header names, and a named Table scroll region.
+- Reframed Slideout as an explicit named presentational region instead of publishing incomplete dialog semantics.
+- Added localized named Carousel landmarks and role descriptions.
+- Corrected Menu switch ownership with `menuitemcheckbox`, hid the visual switch from the accessibility tree, and named Menu progress meters from their visible labels.
+- Removed duplicate page/demo landmarks and IDs; documentation examples now preserve real landmark semantics while scoping repeated valid names to their owning example.
+- Added configurable Page Header heading levels and removed SidebarInset's implicit nested `main`; consumers opt into `main` with `asChild`.
+- Kept standalone TimelineItem neutral while Timeline owns `list`/`listitem` semantics.
+
+### Owned-component composition
+
+- Replaced visible raw actions in Catalog Divider, File Upload, Table, Page Header, Slideout, and Alert with the owned Button API.
+- Page Header now composes the owned Breadcrumbs component.
+- Expanded components contain no direct imports from restricted behavior vendors.
+- All 38 audited backgrounds contain no native `button`, `input`, `select`, `textarea`, or `table` roots and no restricted direct vendor imports.
+
+### RTL and localization
+
+- Reworked Activity Feed, Steps, Timeline, Slideout, Activity Heatmap, Banner, Onboarding Step, Breadcrumbs, File Upload, Table, Page Header, and Social Button to inherit the nearest direction boundary instead of requiring a direct prop.
+- Converted physical spacing/position branches to logical CSS where direction changes placement.
+- Fixed Social Button's inline width precedence so provider-specific RTL widths and Arabic labels remain contained.
+- Added or completed machine-readable RTL contracts for all 68 catalog entries.
+- Localized Carousel landmark/control messages without coupling language choice to direction.
+
+### Responsive layout and containment
+
+- Added narrow rules or local-scroll contracts for Card, Toolbar, Progress Slider, Button Group, Pagination, Table, Banner, Timeline, and the Catalog showcase.
+- Pagination uses a component container query and collapses long numeric runs without losing navigation controls.
+- Table now has keyboard-reachable local scrolling plus paint containment, preventing a 960px data grid from expanding a 324px RTL document.
+- Catalog cards, upload layouts, actions, and table compositions collapse safely at 324px.
+- The complete inherited-RTL route sweep reports zero document overflows at 324px.
+
+### Contrast and states
+
+- Repaired semantic foreground/background roles across Avatar, Badge, Tag, Button, Date Picker, Alert, Banner, Toggle, Social Button, Table, and shared focus indicators.
+- Expanded the canonical audit from 742 to 910 scenarios so repaired live-only cases are now represented in the durable gate.
+- Final status is **910 pass, 0 fail**, including default, hover, pressed, selected, disabled, warning, success, danger, accent, dark/light, theme, typography, and focus-indicator scenarios covered by the audit data.
+
+### Documentation and visual proof
+
+- Every registry entry now has a dedicated normalized Markdown contract and a dedicated registry-backed playground page; pending rollout and bundle aliases are both zero.
+- Every page exposes Base and Alternatives. Fifty single-root components also expose a live measured Anatomy inspector; eighteen portal/caller-sized/composition surfaces are explicitly exempt.
+- Fixed percentage-width Anatomy fixtures for Pagination and Progress Slider so their off-screen measurement rack produces real geometry.
+- Added one deterministic canonical screenshot per component UI route under `playground/e2e/__screenshots__`.
+- Added a reviewed aggregate contact sheet at `output/audits/component-visual-baselines-contact-sheet.png` for clipping, collapse, spacing, and base-layout inspection.
+
+## Component-by-component final status
+
+| Component | Status | Final implementation note |
+| --- | --- | --- |
+| Accordion | Pass | Valid disclosure semantics; unique example region names; variants, sizes, states, and RTL documented. |
+| Aspect Ratio | Pass | Owned Radix wrapper; caller-sized surface with explicit Anatomy exemption. |
+| Avatar | Pass | Valid optional image naming and repaired fallback/disabled contrast. |
+| Badge | Pass | State/theme foregrounds remapped to passing contrast roles. |
+| Tag | Pass | Avatar and active/disabled states pass contrast and owned close actions. |
+| Attribute | Pass | Owned semantic key/value composition with complete docs route. |
+| Button | Pass | Owned action primitive; all audited state/theme contrast combinations pass. |
+| Card | Pass | Horizontal layouts now collapse safely in narrow containers. |
+| Chart | Pass — integration | Banhaten owns the chart shell, semantics, legend, tooltip, and tokens around Recharts. |
+| Carousel | Pass — integration | Named/localized region, owned Button controls, Embla behavior, RTL, and containment pass. |
+| Button Group | Pass | Keyboard-reachable local scroll, focus treatment, narrow containment, and RTL pass. |
+| Segmented Control | Pass | Owned Button Group composition with pressed state and direction-aware keyboard behavior. |
+| Toggle | Pass | Repaired supporting-copy contrast and complete state semantics. |
+| Menu | Pass | Switch items, progress meters, separators, static previews, and Radix menus expose valid ownership. |
+| Menubar | Pass | Owned Radix wrapper with cross-browser docs and accessibility coverage. |
+| Command | Pass — integration | cmdk listbox tree, empty state, groups, and separators are now valid. |
+| Context Menu | Pass | Owned portalled Radix behavior with documented exemption and clean route audit. |
+| Tooltip | Pass | Placement, pointer, focus, RTL, and portal behavior pass. |
+| Popover | Pass | Escape dismissal, focus return, portalled RTL, Axe, and visual baseline pass in all engines. |
+| Hover Card | Pass | Owned Radix behavior with clean route and docs contracts. |
+| Modal | Pass | Dialog naming, focus entry/trap/return, actions, and documentation pass. |
+| Alert Dialog | Pass | Alert-dialog semantics, safe default focus, and owned actions pass. |
+| Checkbox | Pass | Control/card states, focus, contrast, and RTL pass. |
+| Collapsible | Pass | Owned Radix trigger/content relationship and docs pass. |
+| Radio Group | Pass | Orientation, state, labeling, and RTL keyboard behavior pass. |
+| Radio Card | Pass | Direction inheritance and card/radio semantics have focused regressions. |
+| Divider | Pass | Structural separator semantics and variants pass. |
+| Pagination | Pass | Named navigation, unique docs landmarks, container-query collapse, local scroll, and RTL pass. |
+| Toolbar | Pass | Sections and children wrap/contain correctly at narrow widths. |
+| Social Button | Pass | RTL width precedence, Arabic containment, provider states, and contrast pass. |
+| Input | Pass | State, variant, size, density, labeling, and token contracts pass. |
+| Input Group | Pass | Owned grouped input/action surface passes. |
+| Label | Pass | Owned Radix label wrapper and association contract pass. |
+| Kbd | Pass | Intentional chord direction and surrounding RTL inheritance pass. |
+| Item | Pass | Slot-based row composition and state coverage pass. |
+| Field | Pass | Only mounted description/error nodes are referenced. |
+| Input OTP | Pass | Slot semantics, sizes, states, and RTL pass. |
+| Select | Pass | Combobox ARIA, named listboxes, option selection semantics, density, and RTL pass. |
+| Native Select | Pass | Native semantics wrapped by Banhaten state/size/variant tokens. |
+| Sheet | Pass | Edge dialog focus, dismissal, overlay, and RTL pass. |
+| Sidebar | Pass | Provider behavior passes; SidebarInset no longer creates accidental nested-main landmarks. |
+| Navigation Menu | Pass | Named/unique landmarks, Radix behavior, portal layout, and RTL pass. |
+| Scroll Area | Pass | Viewport is keyboard reachable and exposes safe viewport props. |
+| Resizable | Pass — integration | Panels expose focusable overflow content and owned handle focus around react-resizable-panels. |
+| Autocomplete | Pass | Owned Input/Popover/Select/Tag composition passes. |
+| Date Picker | Pass | Valid ARIA calendar grid, names, localization, focus, range/single modes, and contrast pass. |
+| Slider | Pass | Intentional thumb geometry, states, labels, and RTL pass. |
+| Progress | Pass | Named meter semantics and tokenized tones pass. |
+| Progress Slider | Pass | Keyboard/ARIA behavior, sizes, tones, ticks, narrow containment, RTL, and live Anatomy pass. |
+| Textarea | Pass | Modes, labels, states, and token ownership pass. |
+| Skeleton | Pass | Loading family and reduced-motion behavior pass. |
+| Spinner | Pass | Named/hidden modes, token ownership, RTL contract, and reduced motion pass. |
+| Toast | Pass — integration | Owned Sonner API, live region behavior, direction, and tokens pass. |
+| Activity Feed | Pass | Inherits direction and composes owned actions; named feed semantics pass. |
+| Activity Heatmap | Pass | Named image semantics, keyboard-reachable overflow, RTL, tokens, and dedicated docs pass. |
+| Alert | Pass | Owned actions, wrapping/padding invariants, state semantics, and contrast pass. |
+| Banner | Pass | Owned controls, inherited RTL, narrow wrapping, state metadata, and contrast pass. |
+| Catalog Components | Pass — composition | Dedicated page and baseline; Breadcrumbs, Divider, Tag, File Upload, Table, and owned actions compose cleanly. |
+| Breadcrumbs | Pass | Unique named navigation, logical spacing, RTL, truncation, and owned Page Header composition pass. |
+| File Upload | Pass | Visible actions use Button; status text is valid; hidden native file input remains the correct owned platform hook. |
+| Table | Pass | Named meters/ratings/headers, owned actions, focusable local scroll, narrow paint containment, states, and RTL pass. |
+| Empty State | Pass | Sizes, semantics, RTL, and owned actions pass. |
+| Onboarding Step | Pass | Inherited RTL, state metadata, marker geometry, and docs pass. |
+| Page Header | Pass | Composes Breadcrumbs/Tabs/Button, exposes heading level, avoids landmark collisions, and contains narrowly. |
+| Slideout | Pass | Explicit named presentational region, owned actions, unique IDs, logical RTL, and narrow layout pass. |
+| Steps | Pass | Standard/horizontal/vertical/progress modes inherit RTL and preserve marker/connector geometry. |
+| Tabs | Pass | Every trigger owns an existing panel; keyboard, selected state, and docs contracts pass. |
+| Timeline | Pass | Owned list semantics, standalone item neutrality, inherited RTL, connector alignment, and narrow scrolling pass. |
+
+## Final verification evidence
+
+| Gate | Final result |
+| --- | --- |
+| Authoritative repository gate | `npm run check` exited 0 |
+| Contract schemas | 3 canonical contracts passed |
+| CLI | Argument, dependency, install-plan, integration, and doctor tests passed |
+| Token graph | 91 deterministic owned sources; catalog/CSS generation and clean-room reproduction passed |
+| Component token ownership | 161 component/example files passed; metadata current for all 68 entries |
+| Consumer ownership | 38 backgrounds; zero component gaps, native controls, or restricted direct vendor imports |
+| Registry | 68 catalogs, 113 mirrors, current shadcn export, all 68 isolated packed installs passed |
+| Documentation | 68 normalized Markdown contracts and 68 dedicated registry-backed pages; zero pending/aliases |
+| Unit/component suite | 8 Vitest files, 205 tests passed |
+| Production build | TypeScript passed; Vite transformed 3,350 modules; bundle budget passed |
+| Package artifact | 300 files; 96-file registry closure; 72 examples; 68 CLI install smokes passed |
+| Contrast | 910 pass, 0 fail |
+| Catalog accessibility | 69 of 69 routes pass Axe with all violation impacts enabled |
+| RTL/containment | 69 of 69 routes inherit RTL and keep the 324px document contained |
+| Visual regression | 69 of 69 Chromium base-card baselines reproduce cleanly |
+| Cross-browser suite | 389 passed; 4 intentional Chromium-only deduplication skips |
+| Dependency audit | 0 vulnerabilities |
+
+## Residual risk and separate backlog
+
+No open component-specific defect was reproduced by the final source, unit, build, package, accessibility, contrast, direction, containment, documentation, or browser gates.
+
+Three limitations remain important:
+
+1. The visual baselines make future drift detectable; they do not independently prove parity with a design file that was not supplied as a comparison oracle.
+2. Automated Axe and browser tests do not replace periodic manual assistive-technology and usability review on representative real devices.
+3. The background audit still tracks 100 non-component fidelity gaps: 47 layout/composition, 20 icon assets, 20 image assets, and 13 token applications. Those are explicitly outside the 96 component-ownership gaps and outside this component-library remediation.
+
+Within the declared component scope, the completion verdict is **Pass: 68 of 68 components, zero known open component gaps.**

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

@@ -2,6 +2,8 @@
 
 Date: 2026-06-16
 
+> **Status refresh — 2026-08-20:** This file preserves the June baseline and its recommendations. The rollout described below is now complete: all 68 registry entries have dedicated pages using the shared component-doc shell, Base and Alternatives coverage, normalized Markdown contracts, and either live Anatomy or an explicit no-single-root exemption. `catalog-components` now has a dedicated public page; there are zero pending pages and zero bundle aliases. See [Component Implementation Quality Audit — Final Status](./component-quality-audit-2026-08-20.md) for the current component-by-component verdict and verification results.
+
 ## 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.

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

@@ -6,6 +6,7 @@ Design-system components use semantic props and tokens. Appearance presets may c
 
 - [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.

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

@@ -102,5 +102,7 @@ This table is generated from `registry/index.json`; edit the component-owned sou
 | `supportedExports` | `components/expanded/ActivityFeed.tsx: ActivityFeed, ActivityFeedItem` |
 | `parts` | `ActivityFeed`, `ActivityFeedItem` |
 | `registryDependencies` | `button` |
+| `states` | `default`, `with-status`, `with-link`, `with-actions` |
 | `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` |
+| `variants` | `caption`, `slot` |
 <!-- registry-contract:end -->