banhaten 0.3.0 → 0.5.0

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

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