banhaten 0.3.0 → 0.5.0

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

@@ -1,219 +1,219 @@
-# Component Showcase Consistency Report
-
-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.
-
-## 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.
+# Component Showcase Consistency Report
+
+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.
+
+## 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`.
+- The visible contract now publishes `success`, `warning`, and `link` as canonical variants. `destructive` and `soft-destructive` remain documented compatibility aliases for `danger` and `soft-danger`.
+- 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.
+- Focused parity coverage now locks Button's runtime variant union, canonical catalog/index/spec values, manual API and example lists, distinct recipes, and exact compatibility aliases. Broader behavior such as `asChild`, loading composition, and icon sizing remains covered by shared component and browser checks rather than this focused contract test.
+
+### Verdict
+
+Button should be the content-quality model, not the code-shape model. Its opening preview, registry metadata, canonical variant policy, component markdown docs, and source parity check now match the proposed standard.
+
+## 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
+
+- Button's variant policy is resolved: `success`, `warning`, and `link` are canonical; `destructive` and `soft-destructive` are deprecated aliases for `danger` and `soft-danger`.
+- Button now has a focused parity check across its runtime types, registry metadata, generated index, playground spec, Markdown API, and examples. Apply that pattern to other components when drift is found.
+
+### 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.