banhaten 0.1.2 → 0.1.3

package/docs/design-system/appearance-presets.md

@@ -0,0 +1,184 @@
+# Appearance Presets
+
+Appearance presets change the feel of the design system without changing component APIs.
+
+Components keep semantic variants such as `primary`, `secondary`, `subtle`, `danger`, and `ghost`. Presets decide how those meanings look through design tokens: color, radius, density, border, and elevation.
+
+## Presets
+
+- `default`: The baseline product UI. Gray application background, white cards, modest radius, conservative spacing.
+- `rounded`: A softer UI. White application background, stronger radius, relaxed spacing, gentler separation.
+- `sharp`: A precise UI. Square edges, tighter spacing, clearer borders, minimal elevation.
+
+Each preset has its own markdown file:
+
+- [Default](./appearances/default.md)
+- [Rounded](./appearances/rounded.md)
+- [Sharp](./appearances/sharp.md)
+
+Component specs:
+
+- [Icons](./icons.md)
+- [Tabs](./tabs.md)
+- [Tag](./components/tag.md)
+- [Timeline](./components/timeline.md)
+
+Component guidance lives in:
+
+- [Components](./components/README.md)
+- [Banner](./components/banner.md)
+- [Breadcrumbs](./components/breadcrumbs.md)
+- [Divider](./components/divider.md)
+- [File Upload](./components/file-upload.md)
+- [Tag](./components/tag.md)
+- [Timeline](./components/timeline.md)
+
+## Token Contract
+
+The design system should use semantic tokens instead of importing naming patterns from a framework. Tokens describe where they are used, not how they happen to look in one theme.
+
+### Content
+
+`content` tokens apply to text and icons.
+
+- `content.default`
+- `content.primary`
+- `content.subtle`
+- `content.muted`
+- `content.disabled`
+- `content.inverse`
+- `content.link`
+- `content.linkHover`
+- `content.onColor`
+- `content.onLight`
+- `content.onBrand`
+- `content.success`
+- `content.warning`
+- `content.danger`
+
+### Background
+
+`background` tokens apply to page, layout, component, and interactive fills.
+
+- `background.app`
+- `background.default`
+- `background.card`
+- `background.subtle`
+- `background.muted`
+- `background.disabled`
+- `background.inverse`
+- `background.overlay`
+- `background.brand`
+- `background.brandHover`
+- `background.brandPressed`
+- `background.selected`
+- `background.hover`
+- `background.pressed`
+- `background.success`
+- `background.warning`
+- `background.danger`
+
+### Border
+
+`border` tokens apply to component outlines, dividers, focus states, and validation states.
+
+- `border.default`
+- `border.subtle`
+- `border.strong`
+- `border.disabled`
+- `border.focus`
+- `border.brand`
+- `border.success`
+- `border.warning`
+- `border.danger`
+
+### Shape
+
+`shape` tokens control radius by usage, not component name.
+
+- `shape.action`
+- `shape.control`
+- `shape.card`
+- `shape.panel`
+- `shape.modal`
+- `shape.popover`
+- `shape.badge`
+- `shape.avatar`
+
+### Density
+
+`density` tokens control repeated spacing and sizing decisions.
+
+- `density.controlHeight`
+- `density.controlPaddingX`
+- `density.cardPadding`
+- `density.panelPadding`
+- `density.sectionGap`
+- `density.listRowHeight`
+- `density.tableRowHeight`
+
+### Elevation
+
+`elevation` tokens control shadows and stacking treatment.
+
+- `elevation.card`
+- `elevation.panel`
+- `elevation.popover`
+- `elevation.modal`
+- `elevation.none`
+
+## Component Rule
+
+Components consume semantic tokens and component-scoped aliases. They must not hard-code preset-specific values or Figma fallback literals in component source.
+
+If a Figma reference exposes a literal color, size, radius, shadow, or opacity, promote it into the generated token contract or a component-level `--bh-*` alias in `registry/styles/globals.css`, then consume that token from the component. Component docs may record Figma references for audit and QA, but those literals are not implementation fallbacks.
+
+Good:
+
+```tsx
+<Button variant="primary" />
+<Card />
+```
+
+Avoid:
+
+```tsx
+<Button rounded />
+<Card sharp />
+<Card className="rounded-[16px]" />
+```
+
+The preset is selected at the design-system root:
+
+```tsx
+<DesignSystemProvider appearance="default">
+  <App />
+</DesignSystemProvider>
+```
+
+or through a root attribute:
+
+```html
+<body data-appearance="default">
+```
+
+## Preset Responsibilities
+
+An appearance preset may change:
+
+- Page and layout background treatment
+- Card and panel background treatment
+- Radius for actions, controls, cards, modals, popovers, badges, and tabs
+- Component density and padding
+- Border prominence
+- Elevation and shadow strength
+- Hover, pressed, selected, and disabled treatment
+
+An appearance preset should not change:
+
+- Component behavior
+- Component variant names
+- Accessibility requirements
+- Interaction contracts
+- Information hierarchy
+- Meaning of semantic color roles

package/docs/design-system/appearances/default.md

@@ -0,0 +1,94 @@
+# Default Appearance
+
+`default` is the baseline product appearance.
+
+It should feel practical, calm, and balanced: a gray application background, white cards, modest radius, restrained elevation, and conservative spacing.
+
+## Visual Character
+
+- Application background is gray or off-white.
+- Cards and primary content areas are white.
+- Actions and controls have a modest radius.
+- Spacing is comfortable but compact enough for daily product use.
+- Shadows are subtle and used only to separate floating or raised elements.
+
+## Token Direction
+
+```ts
+export const defaultAppearance = {
+  content: {
+    default: "#171717",
+    primary: "#000000",
+    subtle: "#404040",
+    muted: "#737373",
+    disabled: "#a3a3a3",
+    inverse: "#ffffff",
+    link: "#1d4ed8",
+    linkHover: "#1e40af",
+    onColor: "#ffffff",
+    onLight: "#171717",
+    onBrand: "#ffffff",
+  },
+  background: {
+    app: "#f4f4f5",
+    default: "#ffffff",
+    card: "#ffffff",
+    subtle: "#fafafa",
+    muted: "#f5f5f5",
+    disabled: "#e5e5e5",
+    inverse: "#171717",
+    overlay: "rgba(23, 23, 23, 0.48)",
+    brand: "#171717",
+    brandHover: "#262626",
+    brandPressed: "#0a0a0a",
+    selected: "#e5e7eb",
+    hover: "#f5f5f5",
+    pressed: "#e5e5e5",
+  },
+  border: {
+    default: "#d4d4d4",
+    subtle: "#e5e5e5",
+    strong: "#a3a3a3",
+    disabled: "#e5e5e5",
+    focus: "#2563eb",
+    brand: "#171717",
+  },
+  shape: {
+    action: "10px",
+    control: "10px",
+    card: "12px",
+    panel: "12px",
+    modal: "16px",
+    popover: "12px",
+    badge: "999px",
+    avatar: "999px",
+  },
+  density: {
+    controlHeight: "40px",
+    controlPaddingX: "14px",
+    cardPadding: "20px",
+    panelPadding: "20px",
+    sectionGap: "24px",
+    listRowHeight: "44px",
+    tableRowHeight: "44px",
+  },
+  elevation: {
+    card: "0 1px 2px rgba(0, 0, 0, 0.04)",
+    panel: "0 1px 3px rgba(0, 0, 0, 0.06)",
+    popover: "0 12px 28px rgba(0, 0, 0, 0.14)",
+    modal: "0 24px 64px rgba(0, 0, 0, 0.20)",
+    none: "none",
+  },
+};
+```
+
+## Component Impact
+
+- Buttons: modest radius, dark primary action, balanced padding.
+- Breadcrumbs: inline trails stay quiet; raised trails use `background.card`, `border.subtle`, and the modest control radius.
+- Inputs: modest radius, visible but quiet border.
+- Cards: white on gray app background, subtle border or shadow.
+- Dividers: quiet 1px separators using `border.subtle`, with compact spacing around labels or inline actions.
+- File uploads: subtle dashed drop zones with white queued rows, modest radius, and quiet row elevation.
+- Modals and popovers: slightly more radius than inline components.
+- Tables and lists: normal row height for readable operational screens.

package/docs/design-system/appearances/rounded.md

@@ -0,0 +1,95 @@
+# Rounded Appearance
+
+`rounded` is the softer appearance.
+
+It should feel open, approachable, and more polished: a white application background, larger radii, softer borders, relaxed spacing, and less visual heaviness.
+
+## Visual Character
+
+- Application background is white.
+- Cards use white or near-white backgrounds with light borders.
+- Primary actions can be pill-shaped.
+- Panels and cards have visibly larger radius.
+- Spacing is a little more relaxed than `default`.
+- Shadows are soft and optional.
+
+## Token Direction
+
+```ts
+export const roundedAppearance = {
+  content: {
+    default: "#18181b",
+    primary: "#09090b",
+    subtle: "#52525b",
+    muted: "#71717a",
+    disabled: "#a1a1aa",
+    inverse: "#ffffff",
+    link: "#0f766e",
+    linkHover: "#115e59",
+    onColor: "#ffffff",
+    onLight: "#18181b",
+    onBrand: "#ffffff",
+  },
+  background: {
+    app: "#ffffff",
+    default: "#ffffff",
+    card: "#ffffff",
+    subtle: "#fafafa",
+    muted: "#f6f7f7",
+    disabled: "#e4e4e7",
+    inverse: "#18181b",
+    overlay: "rgba(24, 24, 27, 0.42)",
+    brand: "#0f766e",
+    brandHover: "#115e59",
+    brandPressed: "#134e4a",
+    selected: "#ccfbf1",
+    hover: "#f4f7f6",
+    pressed: "#e7f3f0",
+  },
+  border: {
+    default: "#dedede",
+    subtle: "#eeeeee",
+    strong: "#b8b8b8",
+    disabled: "#e4e4e7",
+    focus: "#0f766e",
+    brand: "#0f766e",
+  },
+  shape: {
+    action: "999px",
+    control: "16px",
+    card: "22px",
+    panel: "24px",
+    modal: "28px",
+    popover: "20px",
+    badge: "999px",
+    avatar: "999px",
+  },
+  density: {
+    controlHeight: "44px",
+    controlPaddingX: "18px",
+    cardPadding: "24px",
+    panelPadding: "24px",
+    sectionGap: "32px",
+    listRowHeight: "48px",
+    tableRowHeight: "48px",
+  },
+  elevation: {
+    card: "0 8px 24px rgba(15, 23, 42, 0.06)",
+    panel: "0 10px 32px rgba(15, 23, 42, 0.08)",
+    popover: "0 18px 40px rgba(15, 23, 42, 0.16)",
+    modal: "0 28px 72px rgba(15, 23, 42, 0.22)",
+    none: "none",
+  },
+};
+```
+
+## Component Impact
+
+- Buttons: pill-like primary and action buttons.
+- Breadcrumbs: raised trails inherit the softer control radius and can use slightly more relaxed spacing.
+- Inputs: rounded controls with slightly taller height.
+- Cards: larger radius with light borders and soft separation.
+- Dividers: quiet 1px separators using `border.subtle`, with softer action backgrounds and the preset control radius.
+- File uploads: softer drop zones and queued rows, relaxed padding, and gentle borders.
+- Modals and popovers: rounded, friendly containers.
+- Tables and lists: slightly more vertical breathing room.

package/docs/design-system/appearances/sharp.md

@@ -0,0 +1,95 @@
+# Sharp Appearance
+
+`sharp` is the precise appearance.
+
+It should feel structured, architectural, and efficient: square edges, tighter spacing, stronger borders, flatter surfaces, and minimal elevation.
+
+## Visual Character
+
+- Application background can be white or a very light gray.
+- Cards are flat panels with clear borders.
+- Radius is zero or nearly zero across most UI.
+- Spacing is tighter than `default`.
+- Borders carry most of the separation work.
+- Shadows are reserved for overlays only.
+
+## Token Direction
+
+```ts
+export const sharpAppearance = {
+  content: {
+    default: "#111111",
+    primary: "#000000",
+    subtle: "#3f3f46",
+    muted: "#6b7280",
+    disabled: "#9ca3af",
+    inverse: "#ffffff",
+    link: "#7c2d12",
+    linkHover: "#431407",
+    onColor: "#ffffff",
+    onLight: "#111111",
+    onBrand: "#ffffff",
+  },
+  background: {
+    app: "#f7f7f7",
+    default: "#ffffff",
+    card: "#ffffff",
+    subtle: "#f9fafb",
+    muted: "#f3f4f6",
+    disabled: "#e5e7eb",
+    inverse: "#111111",
+    overlay: "rgba(17, 17, 17, 0.52)",
+    brand: "#111111",
+    brandHover: "#262626",
+    brandPressed: "#000000",
+    selected: "#e5e7eb",
+    hover: "#f3f4f6",
+    pressed: "#e5e7eb",
+  },
+  border: {
+    default: "#c7c7c7",
+    subtle: "#dedede",
+    strong: "#737373",
+    disabled: "#dedede",
+    focus: "#111111",
+    brand: "#111111",
+  },
+  shape: {
+    action: "0px",
+    control: "0px",
+    card: "0px",
+    panel: "0px",
+    modal: "0px",
+    popover: "0px",
+    badge: "2px",
+    avatar: "0px",
+  },
+  density: {
+    controlHeight: "38px",
+    controlPaddingX: "12px",
+    cardPadding: "16px",
+    panelPadding: "16px",
+    sectionGap: "20px",
+    listRowHeight: "40px",
+    tableRowHeight: "38px",
+  },
+  elevation: {
+    card: "none",
+    panel: "none",
+    popover: "0 12px 24px rgba(0, 0, 0, 0.18)",
+    modal: "0 20px 56px rgba(0, 0, 0, 0.24)",
+    none: "none",
+  },
+};
+```
+
+## Component Impact
+
+- Buttons: square edges, compact padding, strong hover and pressed states.
+- Breadcrumbs: raised trails use square or near-square corners with tight separator rhythm.
+- Inputs: square controls with clear border states.
+- Cards: flat panels with borders instead of visible rounding.
+- Dividers: clear 1px separators using `border.subtle`, with square action treatment and tight spacing.
+- File uploads: precise dashed drop zones, square queued rows, tighter spacing, and border-led error states.
+- Modals and popovers: square containers with overlay separation.
+- Tables and lists: denser rows for scanning and comparison.

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

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