banhaten 0.1.1 → 0.1.3

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.

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

@@ -0,0 +1,163 @@
+# Component Token Consistency Audit
+
+Date: 2026-06-13
+
+## Scope
+
+Reviewed the distributable component surface in `registry/components`, expanded component files in `registry/components/expanded`, generated/global token CSS in `registry/styles/globals.css`, token generation and contract scripts, and the playground mirrors.
+
+This audit is focused on whether component color, spacing, sizing, radius, typography, opacity, focus, z-index, shadow, and motion values are driven by Banhaten tokens or documented component aliases.
+
+## Checks Run
+
+- `npm run tokens:check` passed.
+- `npm run registry:check` passed.
+- `npm --prefix playground run test:components` passed with 97 component tests.
+
+Current automated coverage:
+
+- `scripts/generate-token-css.mjs` imports `componentAliasDeclarations()` and emits component aliases into `registry/styles/globals.css`.
+- `scripts/check-token-contract.mjs` verifies those component aliases exist in the generated CSS.
+- `scripts/check-component-token-usage.mjs` scans `registry/components` for raw component-source values.
+- `scripts/check-registry-mirrors.mjs` verifies playground mirrors stay in sync with registry files.
+
+## Current Status
+
+The component library is mostly token-consistent now. The major items from the previous audit have been completed:
+
+- Component aliases are centralized in `scripts/component-token-aliases.mjs`.
+- Generated CSS is current.
+- Component aliases are contract-checked.
+- Registry component source passes the token-usage check.
+- Registry and playground mirrors match.
+- Core focus, z-index, duration, spacing, radius, typography, icon sizing, and common opacity patterns are now tokenized.
+
+The remaining changes are smaller consistency and governance items.
+
+## Required Changes
+
+### P1: Replace Remaining Raw `opacity-0` Utilities
+
+`--bh-opacity-0` already exists, and most components use tokenized opacity. Replace the remaining Tailwind raw zero-opacity utilities with token-backed forms:
+
+- `registry/components/date-picker.tsx`: replace `disabled:opacity-0` with `disabled:opacity-[var(--bh-opacity-0)]`.
+- `registry/components/radio-group.tsx`: replace the hidden input `opacity-0` with `opacity-[var(--bh-opacity-0)]`.
+- `registry/components/textarea.tsx`: replace `after:opacity-0` with `after:opacity-[var(--bh-opacity-0)]`.
+- Sync mirrors through `npm run registry:sync` or the existing mirror workflow.
+
+This is not a visual bug, but it is a token-discipline cleanup.
+
+### P1: Tighten The Token-Usage Check For Zero And Full Opacity
+
+`scripts/check-component-token-usage.mjs` currently flags raw Tailwind opacity only for `50`, `55`, `60`, and `70`. Extend that rule so component source also flags raw `opacity-0` and `opacity-100`, unless an explicit exception is added.
+
+Recommended pattern target:
+
+- Flag: `opacity-0`, `opacity-100`, `disabled:opacity-0`, `after:opacity-0`, grouped/state-prefixed variants.
+- Allow: `opacity-[var(--bh-opacity-0)]`, `opacity-[var(--bh-opacity-100)]`.
+
+### P2: Create A Formal Exception Ledger For Non-Token Literals In Alias Source
+
+Raw values inside `scripts/component-token-aliases.mjs` are no longer leaking into component source, but several are intentional external or Figma-specific values. Document them so future cleanup does not accidentally erase brand/media fidelity.
+
+Document as approved exceptions or promote into a clearer token group:
+
+- Social provider colors: Facebook, Google, LinkedIn, WhatsApp.
+- Radio-card illustrative/payment colors and dimensions.
+- Fractional icon/media geometry such as `28.333px`, `13.333px`, and `6.364px`.
+- Effect/shadow color stops, since the supplied token zips do not include effect tokens.
+- Expanded layout widths and breakpoints for showcase/product-sized components.
+- `--bh-activity-feed-completed-brightness: 0.99`, or replace it with a semantic completed-state color if the visual can be expressed without a brightness filter.
+
+### P2: Keep JS Numeric Offsets Paired With CSS Tokens
+
+Radix APIs require numeric `sideOffset` values, so these cannot directly consume CSS variables:
+
+- `registry/components/select.tsx` uses `SELECT_MENU_SIDE_OFFSET_PX = 4`, mirroring `--bh-select-menu-offset`.
+- `registry/components/tooltip.tsx` uses pointer and pointerless numeric offsets, mirroring tooltip spacing aliases.
+
+The comments are already present. The remaining change is to add these cases to the exception ledger or add a small assertion/test that keeps the JS numbers aligned with their matching aliases.
+
+### P3: Clarify Expanded Component Contract
+
+Expanded components are registered with `status: "expanded"` and have many layout aliases, especially Icon Explorer, Table, Timeline, Steps, Catalog Components, and File Upload. Decide whether these are production component contracts or documentation/showcase layouts.
+
+If production:
+
+- Keep the `--bh-*` layout aliases as public component tokens.
+- Add docs for which layout aliases are safe to override.
+- Add them to any token documentation tables.
+
+If documentation/showcase only:
+
+- Mark them as documentation-level layout tokens.
+- Keep them under the static token check, but document that their large fixed widths are layout constraints rather than primitive spacing tokens.
+
+## Component Matrix
+
+### Core Components
+
+Needs token cleanup:
+
+- Date Picker: raw `disabled:opacity-0`.
+- Radio Group: raw hidden-input `opacity-0`.
+- Textarea: raw focus-ring pseudo-element `after:opacity-0`.
+
+Token-clean under current checks:
+
+- Accordion
+- Alert
+- Attribute
+- Avatar
+- Badge
+- Button
+- Button Group
+- Card
+- Checkbox
+- Divider
+- Input
+- Menu
+- Modal
+- Pagination
+- Progress
+- Progress Slider
+- Radio Card
+- Select
+- Select Content
+- Slider
+- Social Button
+- Spinner
+- Tag
+- Toggle
+- Toolbar
+- Tooltip
+
+### Expanded Components
+
+No direct component-source token violations remain under the current static check. Their remaining work is contract clarity and exception documentation:
+
+- Activity Feed
+- Banner
+- Breadcrumbs
+- Catalog Components Showcase
+- Command Bar
+- Expanded Divider
+- File Upload
+- Icon Explorer
+- Onboarding Step List Item
+- Page Header
+- Slideout
+- Steps
+- Table
+- Tabs
+- Timeline
+
+Approved literal media-query breakpoints remain in CSS `@media` conditions because CSS custom properties are not reliable media-query operands. Geometry inside those media query blocks should continue using Banhaten tokens or component aliases.
+
+## Suggested Implementation Order
+
+1. Replace the three raw `opacity-0` utilities in registry components and sync mirrors.
+2. Extend `scripts/check-component-token-usage.mjs` to catch raw `opacity-0` and `opacity-100`.
+3. Add an exception ledger for alias-source literals and Radix numeric offsets.
+4. Decide and document the expanded-component token contract.
+5. Re-run `npm run tokens:check`, `npm run registry:check`, and `npm --prefix playground run test:components`.