admin-ui-starter-kit 0.6.8 → 0.7.0

package/.agents/skills/admin-ui-consumer-migration/SKILL.md

@@ -23,8 +23,14 @@ When available in the installed package or repo, read these before editing:
    contract.
 5. `.agents/skills/component-library-rules/references/components/INDEX.json` —
    searchable component index.
-6. `.agents/skills/admin-ui-consumer-migration/references/actions-service.md` —
+6. `.agents/skills/admin-ui-consumer-migration/references/theme-overrides.md` —
+   consumer CSS variable overrides, additional themes, dark scopes,
+   `publish-theme`, and `<UIProvider>` precedence.
+7. `.agents/skills/admin-ui-consumer-migration/references/actions-service.md` —
    shared action registry, overlay, form, and lifecycle wiring guide.
+8. `.agents/skills/admin-ui-consumer-migration/references/package-gap-surfaces.md` —
+   package-owned index, show, settings, resource picker, product editor, and
+   tokenized glue surfaces that should not be rebuilt locally.
 
 Do not bulk-load every component doc. Use the index, then read only the matching
 component file.
@@ -64,6 +70,8 @@ import { EnhancedCombobox } from 'admin-ui-starter-kit/base/combobox';
 import { SchemaForm, type SchemaFormSchema, type SchemaFormValues } from 'admin-ui-starter-kit/features/schema-form';
 import { Comments } from 'admin-ui-starter-kit/features/comments';
 import { MediaLibraryDialog, MediaResourceGallery } from 'admin-ui-starter-kit/features/media-library';
+import { ProductVariantsManager } from 'admin-ui-starter-kit/features/products';
+import { SeoListingCard } from 'admin-ui-starter-kit/composed/commerce';
 ```
 
 Do not use:
@@ -120,6 +128,12 @@ Use this split:
   `--icon`, `--avatar`, and `--shell-sidebar-width` when a scoped override is
   truly needed.
 
+When a consumer app needs checked-in theme files, additional brand themes,
+dark-mode scope wiring, or root `<UIProvider>` value defaults, read
+`references/theme-overrides.md`. Keep the split clear: CSS variables own visual
+values; `<UIProvider>` owns JS-side display defaults; component props still win
+for one-off instances.
+
 Delete or migrate local component-family aliases for action controls, display
 blocks, cards, tables, headers, app shells, and component-specific text roles.
 Normal consumer code should use package components and Tailwind utilities
@@ -181,6 +195,8 @@ Review the diff before deleting local folders.
 | Dialogs/drawers | `admin-ui-starter-kit/features/overlays` |
 | Shared action lifecycle across page/table/card/command/overlay surfaces | `admin-ui-starter-kit/services/actions` |
 | Metrics/charts | `admin-ui-starter-kit/composed/analytics` |
+| Search-engine listing preview / SEO score | `SeoListingCard`, `calculateSeoListingScore` from `admin-ui-starter-kit/composed/commerce` |
+| Product editor options and variants | `ProductVariantsManager`, `ProductOptionsMatrix`, `ProductVariantsBulkTable` from `admin-ui-starter-kit/features/products` |
 | Selected-resource cards | `ResourceSelectorCard` from `admin-ui-starter-kit/composed/data-display` |
 | Settings/action/token surfaces | `ActionList`, `ActionRow`, `SensitiveActionCard`, `CopyableSecretAlert`, `ApiTokenManager` from `admin-ui-starter-kit/composed/admin` |
 | Page/header/sidebar/resource/settings chrome | `admin-ui-starter-kit/layout/page`, `/header`, `/sidebar`, `/resource`, `/settings` |
@@ -206,6 +222,18 @@ Use `AsyncResourceCombobox` plus `ResourceSelectorCard` for "pick a resource"
 flows. The package owns selector/card UI state; the app owns the dialog,
 fetcher, route generation, permissions, and mutation side effects.
 
+Use `ProductVariantsManager` when a product editor needs option groups,
+generated variants, editable price/SKU/inventory cells, selection, grouping,
+and shared action menus. Use `ProductOptionsMatrix` or
+`ProductVariantsBulkTable` directly only when the app owns the surrounding card
+or needs a custom composition. Keep persistence, variant generation, validation,
+permissions, and route changes in the app through callbacks.
+
+Use `SeoListingCard` for product or commerce search-engine previews and SEO
+scoring. The package owns the title, description, permalink, and keyword checks
+through `calculateSeoListingScore`; the app owns field editing, persistence,
+route generation, and translated strings.
+
 Use `services/actions` only when one action definition must appear in multiple
 surfaces and share state: page actions, table-row menus, card menus, command
 palette entries, and overlay confirmation/form flows. Keep one-off dialog state

package/.agents/skills/admin-ui-consumer-migration/references/package-gap-surfaces.md

@@ -30,6 +30,20 @@ or resource selectors.
 - Keep picker dialogs, fetch wrappers, permissions, routing, and mutations in
   the app.
 
+## Product Editor Pages
+
+- Use `ProductVariantsManager` from
+  `admin-ui-starter-kit/features/products` for option groups plus generated
+  variants with grouping, selection, editable cells, and shared action menus.
+- Use `ProductOptionsMatrix` or `ProductVariantsBulkTable` directly only when
+  the consumer owns the surrounding product editor card or needs a custom
+  composition.
+- Use `SeoListingCard` and `calculateSeoListingScore` from
+  `admin-ui-starter-kit/composed/commerce` for search-engine listing previews,
+  permalink checks, title/description length scoring, and keyword checks.
+- Keep product persistence, validation, variant generation, permissions,
+  routing, and translated strings in the consuming app.
+
 ## Show And Settings Pages
 
 - Use `ResourceShowShell` or `TabbedResourceShell` for resource detail pages.

package/.agents/skills/admin-ui-consumer-migration/references/theme-overrides.md

@@ -0,0 +1,172 @@
+# Consumer Theme And Value Overrides
+
+Use this when a consuming app wants to change the package look, density,
+runtime defaults, or tenant/theme values without copying package components.
+
+## Override Layers
+
+Keep these concerns separate:
+
+- CSS variables own visual values: theme colors, fonts, radius, shadows,
+  density, spacing, action/control heights, row padding, surfaces, icons,
+  avatars, and shell dimensions.
+- `<UIProvider>` owns JS-side display defaults: money/date locale, default
+  component sizes, card defaults, toast defaults, media accessors, and similar
+  app-wide display choices.
+- Component props still win for one-off instances.
+
+Precedence:
+
+```txt
+component prop > UIProvider config > package default
+nearest/later CSS variable override > package style.css default
+```
+
+## Default Consumer Mode
+
+Prefer importing the compiled package stylesheet, then an app-owned override
+file after it:
+
+```tsx
+import 'admin-ui-starter-kit/style.css';
+import './styles/admin-ui-overrides.css';
+```
+
+```css
+:root {
+	--font-sans: Inter, -apple-system, BlinkMacSystemFont, 'Segoe UI', sans-serif;
+	--text-scale: 1;
+	--space-scale: 1;
+	--density-scale: 1;
+	--height-control: calc(2.05rem * var(--density-scale));
+	--row-y: calc(0.5rem * var(--density-scale));
+	--surface-x: calc(1rem * var(--space-scale));
+	--shell-sidebar-width: 17rem;
+}
+```
+
+Start with `--text-scale`, `--space-scale`, and `--density-scale`. Use precise
+variables such as `--height-control`, `--height-action`, `--control-x`,
+`--row-y`, `--surface-x`, `--icon`, `--avatar`, and
+`--shell-sidebar-width` only when the product needs a specific adjustment.
+
+## Defining Additional Themes
+
+Theme palette, radius, shadows, chart colors, and sidebar colors map to the
+shadcn-compatible variables from the package theme adapter. Structural sizing
+stays in the package token variables.
+
+```css
+[data-theme='acme'] {
+	--background: oklch(1 0 0);
+	--foreground: oklch(0.24 0 0);
+	--card: oklch(1 0 0);
+	--card-foreground: oklch(0.24 0 0);
+	--popover: oklch(1 0 0);
+	--popover-foreground: oklch(0.24 0 0);
+	--primary: oklch(0.48 0.14 165);
+	--primary-foreground: oklch(0.99 0 0);
+	--secondary: oklch(0.97 0 0);
+	--secondary-foreground: oklch(0.22 0 0);
+	--muted: oklch(0.97 0 0);
+	--muted-foreground: oklch(0.50 0 0);
+	--accent: oklch(0.97 0 0);
+	--accent-foreground: oklch(0.22 0 0);
+	--destructive: oklch(0.50 0.245 27.325);
+	--destructive-foreground: oklch(0.99 0 0);
+	--border: oklch(0.92 0 0);
+	--input: oklch(0.92 0 0);
+	--ring: oklch(0.70 0 0);
+	--radius: 0.5rem;
+	--sidebar: oklch(0.96 0 0);
+	--sidebar-foreground: oklch(0.28 0 0);
+	--sidebar-accent: oklch(0.98 0 0);
+	--sidebar-accent-foreground: oklch(0.20 0 0);
+}
+
+[data-theme='acme'].dark,
+.dark [data-theme='acme'] {
+	--background: oklch(0.22 0 0);
+	--foreground: oklch(0.98 0 0);
+	--card: oklch(0.18 0 0);
+	--card-foreground: oklch(0.98 0 0);
+	--popover: oklch(0.18 0 0);
+	--popover-foreground: oklch(0.98 0 0);
+	--border: oklch(1 0 0 / 12%);
+	--input: oklch(1 0 0 / 16%);
+	--sidebar: oklch(0.18 0 0);
+	--sidebar-accent: oklch(0.26 0 0);
+}
+```
+
+If the app relies on package `dark:` utilities, place `.dark` on or above the
+theme scope. A `data-theme='dark'` attribute changes variables, but it does
+not activate Tailwind's `.dark *` selectors by itself.
+
+Scoped themes and density are valid:
+
+```tsx
+<div data-theme="acme" data-density="compact">
+	<AdminArea />
+</div>
+```
+
+## UIProvider Defaults
+
+Mount `<UIProvider>` once near the React root. Its config is app-wide and
+mount-once; do not use it for runtime toggles or per-page callbacks.
+
+```tsx
+import { UIProvider } from 'admin-ui-starter-kit/ui-provider';
+
+<UIProvider
+	config={{
+		money: { defaultCurrency: 'EUR', locale: 'bg-BG' },
+		dates: { weekStartsOn: 1, locale: 'bg-BG' },
+		table: { defaultSize: 'small' },
+		card: {
+			defaultSurface: 'flat',
+			defaultPadding: 'default',
+			defaultHeaderDivider: true,
+		},
+		toast: {
+			position: 'top-right',
+			theme: 'dark',
+			richColors: false,
+		},
+	}}
+>
+	<App />
+</UIProvider>
+```
+
+## Published Theme Mode
+
+When the consumer needs checked-in editable theme files, run:
+
+```bash
+npx admin-ui-starter-kit-publish-theme
+```
+
+It writes:
+
+```txt
+src/styles/admin-ui/theme.css
+src/styles/admin-ui/defaults.css
+src/styles/admin-ui/overrides.css
+src/styles/admin-ui/admin-ui.css
+src/styles/admin-ui/source.css
+```
+
+Use `admin-ui.css` for the normal mode: package CSS plus local runtime
+overrides. Use `source.css` only when the app intentionally rebuilds Tailwind
+from source and includes `admin-ui-starter-kit/dist/**/*.{js,cjs}` in Tailwind
+content or `@source`.
+
+## Do Not
+
+- Do not edit files under `node_modules`.
+- Do not move package structural values into the shadcn theme layer.
+- Do not keep copied action/card/table/header/app-shell token families.
+- Do not solve product-level density by scattering `text-[...]`, `px-[...]`,
+  `gap-[...]`, or `size-[...]` through JSX.

package/.agents/skills/component-library-rules/SKILL.md

@@ -157,7 +157,7 @@ Rules:
 
 When uncertain whether to add to `base` or `composed`: if it's a single visual element (Button, Badge, Input variant), it's `base`. If it's a row, card, or layout containing multiple primitives, it's `composed`. Pure text primitives (Text, Heading, Label, TextLink) live in `typography/`, not `base/`.
 
-## 3. Typography — sm and xs are the workhorses
+## 3. Typography — sm and pxs are the workhorses
 
 The `Text` component (`@/components/typography/text`) and `Heading` component (`@/components/typography/heading`) are **mandatory** for any user-facing text. Typography lives at the top-level peer layer alongside `ui/` — never under `base/`. Import via `import { Text, Heading, Label, TextLink } from '@/components/typography'`.
 
@@ -167,6 +167,7 @@ The `Text` component (`@/components/typography/text`) and `Heading` component (`
 | Section headings | `text-base` weight=semibold (rare) |
 | **Card titles, primary labels** | **`weight="semibold"`** (`sm` inherited) |
 | **Body text, item labels** | **omit `size`** (`sm` inherited) |
+| **Buttons, badges, compact controls** | **`text-pxs`** |
 | **Secondary / subtitles / metadata** | **`size="xs" type="secondary"`** |
 | **Eyebrows / micro-labels / counts** | **`size="xxs" type="secondary"`** |
 
@@ -179,7 +180,7 @@ preview. Same rule for component scale props such as
 provider-driven, so omit those props at normal call sites.
 
 Forbidden:
-- `text-[10px]`, `text-[11px]`, `text-[13px]` — pick `xxs` / `xs` / `sm`.
+- `text-[10px]`, `text-[11px]`, `text-[13px]`, `text-[14px]` — 10px/11px are below the admin scale; pick `xs` / `pxs` / `sm`.
 - `<span className="text-sm font-semibold">` — use `<Text weight="semibold">`.
 - `text-foreground/85` — use `Text type="secondary"` or `type="discrete"`.
 
@@ -195,7 +196,7 @@ Admin density ≠ smashing things together. Use these defaults:
 | Card body | `p-4` (sm), `p-5` (base), `p-6` (lg) — see SmartCard PADDING |
 | Page section | `gap-3` to `gap-6` between cards |
 
-**Rows shorter than 28px (`h-7`) feel cramped.** Default menu items: `py-2` (≈32-36px tall with text-sm).
+**Rows shorter than 28px (`h-7`) feel cramped.** Default menu items: `py-2` (≈32-36px tall with `text-pxs`).
 
 ## 5. Use base components, not raw HTML+classes
 
@@ -1001,7 +1002,7 @@ See [`src/components/CONVENTIONS.md` §8](../../../src/components/CONVENTIONS.md
 ## Anti-patterns I keep falling into (correct yourself when tempted)
 
 - ❌ "Let me just edit the shadcn primitive to make it smaller." → Wrap or compose instead.
-- ❌ "I'll use `<span className='text-[10px]'>` for this eyebrow." → `<Text size="xxs">`.
+- ❌ "I'll use `<span className='text-[10px]'>` for this eyebrow." → `<Text size="xs" type="secondary">`.
 - ❌ "I'll inline a custom popover header here." → Use `Text` + `Heading` + a `border-b` div, with proper paddings.
 - ❌ "The screenshot is too zoomed in to compare." → It's still your problem; fix it for the actual rendered DPI.
 - ❌ "I'll wrap the icon in a `bg-muted` square." → Plain icon usually reads better; only add a container when it's load-bearing.

package/.agents/skills/component-library-rules/references/components/INDEX.json

@@ -13,7 +13,7 @@
   {"id":"base/conditional-rendering","title":"Conditional rendering","description":"Small display helper for conditional content with an explicit fallback.","layer":"base","family":"Display","tags":["base","display","show-if","conditional","rendering","small","helper"],"sourcePath":"src/components/base/display/show-if","publicImport":"admin-ui-starter-kit/base/display","examples":[],"doc":"./base__conditional-rendering.md"},
   {"id":"base/copyable","title":"Copyable","description":"Click-to-copy inline span with hover affordance and toast feedback.","layer":"base","family":"Display","tags":["base","display","copyable","click","copy","inline","span"],"sourcePath":"src/components/base/copyable","publicImport":"admin-ui-starter-kit/base/copyable","examples":["Default","Mono","MonoTruncate","CustomDisplayValue","CustomToastMessage","RealisticOrderRow","CustomerListWithCopyableEmails"],"doc":"./base__copyable.md"},
   {"id":"base/css-variables","title":"CSS Variables","description":"Token reference for the compact structural contract that controls typography, spacing, density, controls, rows, surfaces, media, and shell dimensions.","layer":"base","family":"Foundations","tags":["base","foundations","*","css","variables","token","reference"],"sourcePath":"src/css/themes/shadcn.default.css + src/css/tokens/*","publicImport":"","examples":["ScalePreview","RuntimeOverrideDemo","VariableExplorer"],"doc":"./base__css-variables.md"},
-  {"id":"base/currency","title":"Currency","description":"MoneyDisplay and CurrencyPairPreview — locale-aware, dual-pricing-aware money rendering driven by useCurrency() / UIProvider config.","layer":"base","family":"Display","tags":["base","display","currency","moneydisplay","currencypairpreview","locale","aware"],"sourcePath":"src/components/base/currency","publicImport":"admin-ui-starter-kit/base/currency","examples":["Default","Sizes","MultipleCurrencies","EmptyState","PairStackedEmphasisVariants","PairInlineEmphasisVariants","PairMinimalVariant","CurrencyPairPreviewExample","ProviderConfigDualPricing","RealisticOrdersList"],"doc":"./base__currency.md"},
+  {"id":"base/currency","title":"Currency","description":"Currency formatting helpers, pair previews, and dual-pricing examples driven by useCurrency() / UIProvider config.","layer":"base","family":"Display","tags":["base","display","currency","formatting","helpers","pair","previews"],"sourcePath":"src/components/base/currency","publicImport":"admin-ui-starter-kit/base/currency","examples":["Default","Sizes","MultipleCurrencies","EmptyState","PairStackedEmphasisVariants","PairInlineEmphasisVariants","PairMinimalVariant","CurrencyPairPreviewExample","ProviderConfigDualPricing","RealisticOrdersList"],"doc":"./base__currency.md"},
   {"id":"base/date-block","title":"Date block","description":"Compact date display block for event, schedule, and timeline summaries.","layer":"base","family":"Display","tags":["base","display","date-block","date","block","compact","event"],"sourcePath":"src/components/base/display/date-block","publicImport":"admin-ui-starter-kit/base/display","examples":[],"doc":"./base__date-block.md"},
   {"id":"base/date-pickers","title":"Date pickers","description":"DatePicker (single / range / multiple) and MonthYearPicker — popover-based, locale-aware, with optional year dropdown and time input.","layer":"base","family":"Forms & inputs","tags":["base","forms","inputs","date-pickers","date","pickers","datepicker","single"],"sourcePath":"src/components/base/date-pickers","publicImport":"admin-ui-starter-kit/base/date-pickers","examples":["Default","ModeSingle","ModeRange","ModeMultiple","WithYearDropdown","ButtonStyles","MonthYearPickerExample","DateRangePickerLegacy","WithTimeInput","RealisticDateFilter"],"doc":"./base__date-pickers.md"},
   {"id":"base/dialog","title":"Dialog","description":"Base dialog wrapper for simple modal content and confirmations.","layer":"base","family":"Display","tags":["base","display","dialog","wrapper","simple","modal","content"],"sourcePath":"src/components/base/display/dialog","publicImport":"admin-ui-starter-kit/base/display","examples":[],"doc":"./base__dialog.md"},
@@ -43,7 +43,22 @@
   {"id":"composed/ai","title":"Composed · AI","description":"Summary block, classification panel, confidence card, prompt suggestions, usage card, message bubble, tool call, citation, and feedback.","layer":"composed","family":"AI","tags":["composed","ai","summary","block","classification","panel"],"sourcePath":"src/components/composed/ai","publicImport":"admin-ui-starter-kit/composed/ai","examples":["AISummary","AIClassification"],"doc":"./composed__ai.md"},
   {"id":"composed/ai-elements","title":"Composed · AI (elements)","description":"Standalone surfaces ported from elements.ai-sdk.dev: shimmer, code-block, agent, package-info, reasoning, chain-of-thought, sources, inline-citation, task, artifact, file-tree, confirmation, attachment.","layer":"composed","family":"AI","tags":["composed","ai","elements","standalone","surfaces","ported"],"sourcePath":"src/components/composed/ai","publicImport":"admin-ui-starter-kit/composed/ai","examples":["Counter","AiShimmerExample","AiAgentExample","AiCodeBlockExample","AiAttachmentExample","AiInlineCitationExample","AiSourcesExample","AiReasoningExample","AiChainOfThoughtExample","AiTaskExample","AiArtifactExample","AiFileTreeExample","AiPackageInfoExample","AiConfirmationExample"],"doc":"./composed__ai-elements.md"},
   {"id":"composed/api-key-list","title":"Composed · Admin · API key list","description":"Collapsible section with per-row dropdown menu (Copy / Delete) and an optional Add action in the header. Generic enough for any 'named secret list' — service tokens, webhook URLs, deployment hooks. Composes base/cards + base/display/collapsible + base/navigation/ActionMenu + base/copyable.","layer":"composed","family":"Admin","tags":["composed","admin","api","key","list","collapsible"],"sourcePath":"src/components/composed/admin","publicImport":"admin-ui-starter-kit/composed/admin","examples":["DefaultVisibleSecretsCallbacksForAddDelete","MaskedSecretsStripeStyle","EmptyState","LocalizedStrings"],"doc":"./composed__api-key-list.md"},
-  {"id":"composed/commerce","title":"Composed · Commerce","description":"Bookings, loyalty, discount stacks, shipment tracking, cart, coupons, payment, tax, subscription, refund, address, and voucher surfaces.","layer":"composed","family":"Commerce","tags":["composed","commerce","bookings","loyalty","discount","stacks"],"sourcePath":"src/components/composed/commerce","publicImport":"admin-ui-starter-kit/composed/commerce","examples":["UpcomingBookings","LoyaltyPoints","DiscountStack","ShipmentTracking"],"doc":"./composed__commerce.md"},
+  {"id":"composed/commerce","title":"Composed · Commerce","description":"Commerce component family for product, order, payment, fulfillment, promotion, and customer-detail surfaces. Each component has its own page and examples.","layer":"composed","family":"Commerce","tags":["composed","commerce","component","family","product","order"],"sourcePath":"src/components/composed/commerce","publicImport":"admin-ui-starter-kit/composed/commerce","examples":[],"doc":"./composed__commerce.md"},
+  {"id":"composed/commerce-address-card","title":"Composed · Commerce · Address card","description":"Shipping and billing address cards with edit, remove, default, and make-default callbacks.","layer":"composed","family":"","tags":["composed","address-card","commerce","address","card","shipping"],"sourcePath":"src/components/composed/commerce/address-card","publicImport":"admin-ui-starter-kit/composed/commerce","examples":["ShippingAndBilling"],"doc":"./composed__commerce-address-card.md"},
+  {"id":"composed/commerce-cart-summary","title":"Composed · Commerce · Cart summary","description":"Checkout summary card with line items, thumbnails, totals, discounts, tax, and checkout callback.","layer":"composed","family":"","tags":["composed","cart-summary","commerce","cart","summary","checkout"],"sourcePath":"src/components/composed/commerce/cart-summary","publicImport":"admin-ui-starter-kit/composed/commerce","examples":["CartSummary"],"doc":"./composed__commerce-cart-summary.md"},
+  {"id":"composed/commerce-coupon-input","title":"Composed · Commerce · Coupon input","description":"Coupon input card with empty and applied states plus apply/remove callbacks.","layer":"composed","family":"","tags":["composed","coupon-input","commerce","coupon","input","card"],"sourcePath":"src/components/composed/commerce/coupon-input","publicImport":"admin-ui-starter-kit/composed/commerce","examples":["EmptyAndApplied"],"doc":"./composed__commerce-coupon-input.md"},
+  {"id":"composed/commerce-discount-stack","title":"Composed · Commerce · Discount stack","description":"Discount stack preview for coupons, loyalty savings, promotions, and total savings.","layer":"composed","family":"","tags":["composed","discount-stack","commerce","discount","stack","preview"],"sourcePath":"src/components/composed/commerce/discount-stack","publicImport":"admin-ui-starter-kit/composed/commerce","examples":["DiscountStack"],"doc":"./composed__commerce-discount-stack.md"},
+  {"id":"composed/commerce-inventory-section","title":"Composed · Commerce · Inventory section","description":"Controlled inventory form card for product and variant stock, identifiers, sell-through policy, fulfillment location, shipping weight, customs data, and operational tags.","layer":"composed","family":"","tags":["composed","inventory-section","commerce","inventory","section","controlled"],"sourcePath":"src/components/composed/commerce/inventory-section","publicImport":"admin-ui-starter-kit/composed/commerce","examples":["FullProductInventory","DigitalProductInventory","LowStockValidation"],"doc":"./composed__commerce-inventory-section.md"},
+  {"id":"composed/commerce-loyalty-points","title":"Composed · Commerce · Loyalty points","description":"Loyalty balance card with tier, history rows, and redeem callback.","layer":"composed","family":"","tags":["composed","loyalty-points","commerce","loyalty","points","balance"],"sourcePath":"src/components/composed/commerce/loyalty-points","publicImport":"admin-ui-starter-kit/composed/commerce","examples":["LoyaltyPoints"],"doc":"./composed__commerce-loyalty-points.md"},
+  {"id":"composed/commerce-order-status","title":"Composed · Commerce · Order status","description":"Order status card with current stage, ETA, and timeline events.","layer":"composed","family":"","tags":["composed","order-status","commerce","order","status","card"],"sourcePath":"src/components/composed/commerce/order-status","publicImport":"admin-ui-starter-kit/composed/commerce","examples":["OrderStatus"],"doc":"./composed__commerce-order-status.md"},
+  {"id":"composed/commerce-payment-method","title":"Composed · Commerce · Payment method","description":"Payment method card with card brand, masked number, expiry, default state, and change callback.","layer":"composed","family":"","tags":["composed","payment-method","commerce","payment","method","card"],"sourcePath":"src/components/composed/commerce/payment-method","publicImport":"admin-ui-starter-kit/composed/commerce","examples":["PaymentMethod"],"doc":"./composed__commerce-payment-method.md"},
+  {"id":"composed/commerce-refund-status","title":"Composed · Commerce · Refund status","description":"Refund status card with amount, reason, payment method, ETA, and requested timestamp.","layer":"composed","family":"","tags":["composed","refund-status","commerce","refund","status","card"],"sourcePath":"src/components/composed/commerce/refund-status","publicImport":"admin-ui-starter-kit/composed/commerce","examples":["RefundStatus"],"doc":"./composed__commerce-refund-status.md"},
+  {"id":"composed/commerce-seo-listing","title":"Composed · Commerce · SEO listing","description":"Search result preview with product SEO scoring for title length, meta description, permalink, URL quality, slug format, and focus keyword coverage.","layer":"composed","family":"","tags":["composed","seo-listing","commerce","seo","listing","search"],"sourcePath":"src/components/composed/commerce/seo-listing","publicImport":"admin-ui-starter-kit/composed/commerce","examples":["CompleteListing","ListingNeedsWork","CompactScoreOnly"],"doc":"./composed__commerce-seo-listing.md"},
+  {"id":"composed/commerce-shipment-tracking","title":"Composed · Commerce · Shipment tracking","description":"Shipment card with tracking number, carrier, status steps, and delivery details.","layer":"composed","family":"","tags":["composed","shipment-tracking","commerce","shipment","tracking","card"],"sourcePath":"src/components/composed/commerce/shipment-tracking","publicImport":"admin-ui-starter-kit/composed/commerce","examples":["ShipmentTracking"],"doc":"./composed__commerce-shipment-tracking.md"},
+  {"id":"composed/commerce-subscription-summary","title":"Composed · Commerce · Subscription summary","description":"Subscription plan summary with price, billing date, perks, and manage/upgrade callbacks.","layer":"composed","family":"","tags":["composed","subscription-summary","commerce","subscription","summary","plan"],"sourcePath":"src/components/composed/commerce/subscription-summary","publicImport":"admin-ui-starter-kit/composed/commerce","examples":["SubscriptionSummary"],"doc":"./composed__commerce-subscription-summary.md"},
+  {"id":"composed/commerce-tax-breakdown","title":"Composed · Commerce · Tax breakdown","description":"Tax breakdown card for item subtotals, rate lines, total tax, and final totals.","layer":"composed","family":"","tags":["composed","tax-breakdown","commerce","tax","breakdown","card"],"sourcePath":"src/components/composed/commerce/tax-breakdown","publicImport":"admin-ui-starter-kit/composed/commerce","examples":["TaxBreakdown"],"doc":"./composed__commerce-tax-breakdown.md"},
+  {"id":"composed/commerce-upcoming-booking","title":"Composed · Commerce · Upcoming booking","description":"Upcoming booking rows for compact commerce dashboards and operational schedules.","layer":"composed","family":"","tags":["composed","upcoming-booking","commerce","upcoming","booking","rows"],"sourcePath":"src/components/composed/commerce/upcoming-booking","publicImport":"admin-ui-starter-kit/composed/commerce","examples":["UpcomingBookingList"],"doc":"./composed__commerce-upcoming-booking.md"},
+  {"id":"composed/commerce-voucher-entry","title":"Composed · Commerce · Voucher entry","description":"Voucher lookup card with controlled applied state and remove callback.","layer":"composed","family":"","tags":["composed","voucher-entry","commerce","voucher","entry","lookup"],"sourcePath":"src/components/composed/commerce/voucher-entry","publicImport":"admin-ui-starter-kit/composed/commerce","examples":["VoucherEntry"],"doc":"./composed__commerce-voucher-entry.md"},
   {"id":"composed/contact-card","title":"Composed · Contact card","description":"ContactCard — name, role, email, phone, location, badge.","layer":"composed","family":"Cards","tags":["composed","cards","contact-card","contact","card","contactcard","name"],"sourcePath":"src/components/composed/cards/contact-card","publicImport":"admin-ui-starter-kit/composed/cards","examples":["WithAllFields","WithInitialsOnly","Minimal","DifferentBadgeVariants"],"doc":"./composed__contact-card.md"},
   {"id":"composed/course-card","title":"Composed · Course card","description":"Operational session cards for bookings, courses, and guided experiences.","layer":"composed","family":"Cards","tags":["composed","cards","course-card","course","card","operational","session"],"sourcePath":"src/components/composed/cards/course-card","publicImport":"admin-ui-starter-kit/composed/cards","examples":["DefaultSession","FeaturedSession","CompactList"],"doc":"./composed__course-card.md"},
   {"id":"composed/dark-surfaces","title":"Composed · Dark surfaces","description":"Dark-wrapped components — payment, receipt, info panel, order items, outstanding balance.","layer":"composed","family":"Surfaces","tags":["composed","surfaces","dark-surfaces","dark","wrapped","components","payment"],"sourcePath":"src/components/composed/dark-surfaces","publicImport":"admin-ui-starter-kit/composed/dark-surfaces","examples":["PaymentConfirmation","BookingReceipt","InfoPanel","OrderItems","OutstandingBalance"],"doc":"./composed__dark-surfaces.md"},
@@ -91,7 +106,11 @@
   {"id":"features/metrics-overview","title":"Features · Metrics · Overview","description":"The unified metrics module: a single Metric component with seven layout variants, plus MetricBar, MetricGrid, and supporting atoms (TrendChip, Sparkline, Skeleton). One MetricData shape powers every surface — see the dedicated pages for each layout.","layer":"features","family":"Metrics","tags":["features","metrics","analytics","overview","unified","module","single"],"sourcePath":"src/components/composed/analytics","publicImport":"admin-ui-starter-kit/composed/analytics","examples":["MetricBarDefault","MetricBarGradientFrame","MetricGridCardVariant","MetricGridCompactList","MetricSizesSmMdLg","MetricMinimalInlineCopy","MetricTrendChipExample","MetricSparklineExample","LoadingSkeletons","LiveLoadingState","ErrorState"],"doc":"./features__metrics-overview.md"},
   {"id":"features/metrics-stat-cards","title":"Features · Metrics · Stat cards","description":"Two stat tile flavors built from the unified `Metric` component — `accent` (dark surface + sparkline) and `colored` (segmented progress bar).","layer":"features","family":"Metrics","tags":["features","metrics","analytics","stat","cards","tile","flavors"],"sourcePath":"src/components/composed/analytics","publicImport":"admin-ui-starter-kit/composed/analytics","examples":["MetricAccent","MetricColored"],"doc":"./features__metrics-stat-cards.md"},
   {"id":"features/overlays","title":"Features · Overlays","description":"Native dialog-backed Dialog, Drawer in four directions, and AlertDialog. Same emphasis/tone system, focus management, async-confirm flow, and confirm/cancel ergonomics across all three. Callback-driven so they slot into any framework.","layer":"features","family":"Overlays","tags":["features","overlays","native","dialog","backed","drawer"],"sourcePath":"src/components/features/overlays","publicImport":"admin-ui-starter-kit/features/overlays","examples":["APISurface","DialogDefault","DialogEmphasisTones","DialogRichContent","DialogFormPattern","Drawer4Directions","AlertDialogConfirmationPatterns","BestPractices"],"doc":"./features__overlays.md"},
-  {"id":"features/products","title":"Features · Products","description":"Shopify-style product editor surfaces built from standalone product feature components. Routing, forms, and persistence stay consumer-owned.","layer":"features","family":"Commerce","tags":["features","commerce","products","shopify","style","product","editor"],"sourcePath":"src/components/features/products","publicImport":"admin-ui-starter-kit/features/products","examples":["ProductEditor","OptionsAndVariants","VariantDetailsAndEditor","StandaloneActionMenus","ProductSupportRail"],"doc":"./features__products.md"},
+  {"id":"features/products","title":"Features · Products","description":"Shopify-style product editor surfaces built from standalone product feature components. Routing, forms, and persistence stay consumer-owned.","layer":"features","family":"Commerce","tags":["features","commerce","products","shopify","style","product","editor"],"sourcePath":"src/components/features/products","publicImport":"admin-ui-starter-kit/features/products","examples":[],"doc":"./features__products.md"},
+  {"id":"features/products/actions","title":"Features · Products · Actions","description":"Product option and variant action menus that can be mounted inside tables, cards, rows, or fully custom consumer layouts.","layer":"features","family":"","tags":["features","products","actions","product","option","variant"],"sourcePath":"src/components/features/products","publicImport":"admin-ui-starter-kit/features/products","examples":[],"doc":"./features__products__actions.md"},
+  {"id":"features/products/support-rail","title":"Features · Products · Support Rail","description":"Secondary product cards for readiness, structure, operations, quote preview, and policies.","layer":"features","family":"","tags":["features","products","support","rail","secondary","product"],"sourcePath":"src/components/features/products","publicImport":"admin-ui-starter-kit/features/products","examples":["ProductSupportRail"],"doc":"./features__products__support-rail.md"},
+  {"id":"features/products/variant-details","title":"Features · Products · Variant Details","description":"Variant detail and editor surfaces for product-specific edit flows. Persistence, validation, and routing stay callback-owned by the consumer.","layer":"features","family":"","tags":["features","products","variant","details","detail","editor"],"sourcePath":"src/components/features/products","publicImport":"admin-ui-starter-kit/features/products","examples":["VariantDetailsAndEditor"],"doc":"./features__products__variant-details.md"},
+  {"id":"features/products/variant-management","title":"Features · Products · Variant Management","description":"Option matrix and generated variants table with controlled collapse, selection, editable cells, render-props, and bulk callbacks.","layer":"features","family":"","tags":["features","products","variant","management","option","matrix"],"sourcePath":"src/components/features/products","publicImport":"admin-ui-starter-kit/features/products","examples":["VariantManagement","VariantTableControls"],"doc":"./features__products__variant-management.md"},
   {"id":"features/resource","title":"Features · Resource shells","description":"Resource index and show shells for app-owned data, actions, tabs, loading, empty, and related-record regions.","layer":"features","family":"Operations","tags":["features","operations","resource","shells","index","show","app"],"sourcePath":"src/components/features/resource","publicImport":"admin-ui-starter-kit/features/resource","examples":["ResourceIndexShellExample","ResourceShowShellExample","TabbedResourceDetails"],"doc":"./features__resource.md"},
   {"id":"features/rich-text-editor","title":"Features · Rich text editor","description":"Tiptap-backed editor with bold / italic / strike / lists / quote / undo-redo. Falls back to a non-editable preview when @tiptap/react is not bundled. Strings overridable via the `strings` prop.","layer":"features","family":"Inputs","tags":["features","inputs","rich-text-editor","rich","text","editor","tiptap"],"sourcePath":"src/components/features/rich-text-editor","publicImport":"admin-ui-starter-kit/features/rich-text-editor","examples":["ProductionWiring","Default","CompactSmallerInlineNote","EmptyPlaceholder","Disabled","StringsOverride"],"doc":"./features__rich-text-editor.md"},
   {"id":"features/schema-form","title":"Features · Schema form","description":"Schema-driven form renderer built from the package form fields. Supports one cohesive form, section cards, controlled values, validation callbacks, and render-prop overrides.","layer":"features","family":"Inputs","tags":["features","inputs","schema-form","schema","form","driven","renderer"],"sourcePath":"src/components/features/schema-form","publicImport":"admin-ui-starter-kit/features/schema-form","examples":["CohesiveForm","SectionCards","RenderPropField"],"doc":"./features__schema-form.md"},

package/.agents/skills/component-library-rules/references/components/INDEX.md

@@ -20,7 +20,7 @@ Agents: prefer `INDEX.json` (structured) for discovery; this file is for humans.
 - [Conditional rendering](./base__conditional-rendering.md) — Small display helper for conditional content with an explicit fallback.
 - [Copyable](./base__copyable.md) — Click-to-copy inline span with hover affordance and toast feedback.
 - [CSS Variables](./base__css-variables.md) — Token reference for the compact structural contract that controls typography, spacing, density, controls, rows, surfaces, media, and shell dimensions.
-- [Currency](./base__currency.md) — MoneyDisplay and CurrencyPairPreview — locale-aware, dual-pricing-aware money rendering driven by useCurrency() / UIProvider config.
+- [Currency](./base__currency.md) — Currency formatting helpers, pair previews, and dual-pricing examples driven by useCurrency() / UIProvider config.
 - [Date block](./base__date-block.md) — Compact date display block for event, schedule, and timeline summaries.
 - [Date pickers](./base__date-pickers.md) — DatePicker (single / range / multiple) and MonthYearPicker — popover-based, locale-aware, with optional year dropdown and time input.
 - [Dialog](./base__dialog.md) — Base dialog wrapper for simple modal content and confirmations.
@@ -56,7 +56,22 @@ Agents: prefer `INDEX.json` (structured) for discovery; this file is for humans.
 - [Composed · AI](./composed__ai.md) — Summary block, classification panel, confidence card, prompt suggestions, usage card, message bubble, tool call, citation, and feedback.
 - [Composed · AI (elements)](./composed__ai-elements.md) — Standalone surfaces ported from elements.ai-sdk.dev: shimmer, code-block, agent, package-info, reasoning, chain-of-thought, sources, inline-citation, task, artifact, file-tree, confirmation, attachment.
 - [Composed · Admin · API key list](./composed__api-key-list.md) — Collapsible section with per-row dropdown menu (Copy / Delete) and an optional Add action in the header. Generic enough for any 'named secret list' — service tokens, webhook URLs, deployment hooks. Composes base/cards + base/display/collapsible + base/navigation/ActionMenu + base/copyable.
-- [Composed · Commerce](./composed__commerce.md) — Bookings, loyalty, discount stacks, shipment tracking, cart, coupons, payment, tax, subscription, refund, address, and voucher surfaces.
+- [Composed · Commerce](./composed__commerce.md) — Commerce component family for product, order, payment, fulfillment, promotion, and customer-detail surfaces. Each component has its own page and examples.
+- [Composed · Commerce · Address card](./composed__commerce-address-card.md) — Shipping and billing address cards with edit, remove, default, and make-default callbacks.
+- [Composed · Commerce · Cart summary](./composed__commerce-cart-summary.md) — Checkout summary card with line items, thumbnails, totals, discounts, tax, and checkout callback.
+- [Composed · Commerce · Coupon input](./composed__commerce-coupon-input.md) — Coupon input card with empty and applied states plus apply/remove callbacks.
+- [Composed · Commerce · Discount stack](./composed__commerce-discount-stack.md) — Discount stack preview for coupons, loyalty savings, promotions, and total savings.
+- [Composed · Commerce · Inventory section](./composed__commerce-inventory-section.md) — Controlled inventory form card for product and variant stock, identifiers, sell-through policy, fulfillment location, shipping weight, customs data, and operational tags.
+- [Composed · Commerce · Loyalty points](./composed__commerce-loyalty-points.md) — Loyalty balance card with tier, history rows, and redeem callback.
+- [Composed · Commerce · Order status](./composed__commerce-order-status.md) — Order status card with current stage, ETA, and timeline events.
+- [Composed · Commerce · Payment method](./composed__commerce-payment-method.md) — Payment method card with card brand, masked number, expiry, default state, and change callback.
+- [Composed · Commerce · Refund status](./composed__commerce-refund-status.md) — Refund status card with amount, reason, payment method, ETA, and requested timestamp.
+- [Composed · Commerce · SEO listing](./composed__commerce-seo-listing.md) — Search result preview with product SEO scoring for title length, meta description, permalink, URL quality, slug format, and focus keyword coverage.
+- [Composed · Commerce · Shipment tracking](./composed__commerce-shipment-tracking.md) — Shipment card with tracking number, carrier, status steps, and delivery details.
+- [Composed · Commerce · Subscription summary](./composed__commerce-subscription-summary.md) — Subscription plan summary with price, billing date, perks, and manage/upgrade callbacks.
+- [Composed · Commerce · Tax breakdown](./composed__commerce-tax-breakdown.md) — Tax breakdown card for item subtotals, rate lines, total tax, and final totals.
+- [Composed · Commerce · Upcoming booking](./composed__commerce-upcoming-booking.md) — Upcoming booking rows for compact commerce dashboards and operational schedules.
+- [Composed · Commerce · Voucher entry](./composed__commerce-voucher-entry.md) — Voucher lookup card with controlled applied state and remove callback.
 - [Composed · Contact card](./composed__contact-card.md) — ContactCard — name, role, email, phone, location, badge.
 - [Composed · Course card](./composed__course-card.md) — Operational session cards for bookings, courses, and guided experiences.
 - [Composed · Dark surfaces](./composed__dark-surfaces.md) — Dark-wrapped components — payment, receipt, info panel, order items, outstanding balance.
@@ -111,6 +126,10 @@ Agents: prefer `INDEX.json` (structured) for discovery; this file is for humans.
 - [Features · Metrics · Stat cards](./features__metrics-stat-cards.md) — Two stat tile flavors built from the unified `Metric` component — `accent` (dark surface + sparkline) and `colored` (segmented progress bar).
 - [Features · Overlays](./features__overlays.md) — Native dialog-backed Dialog, Drawer in four directions, and AlertDialog. Same emphasis/tone system, focus management, async-confirm flow, and confirm/cancel ergonomics across all three. Callback-driven so they slot into any framework.
 - [Features · Products](./features__products.md) — Shopify-style product editor surfaces built from standalone product feature components. Routing, forms, and persistence stay consumer-owned.
+- [Features · Products · Actions](./features__products__actions.md) — Product option and variant action menus that can be mounted inside tables, cards, rows, or fully custom consumer layouts.
+- [Features · Products · Support Rail](./features__products__support-rail.md) — Secondary product cards for readiness, structure, operations, quote preview, and policies.
+- [Features · Products · Variant Details](./features__products__variant-details.md) — Variant detail and editor surfaces for product-specific edit flows. Persistence, validation, and routing stay callback-owned by the consumer.
+- [Features · Products · Variant Management](./features__products__variant-management.md) — Option matrix and generated variants table with controlled collapse, selection, editable cells, render-props, and bulk callbacks.
 - [Features · Resource shells](./features__resource.md) — Resource index and show shells for app-owned data, actions, tabs, loading, empty, and related-record regions.
 - [Features · Rich text editor](./features__rich-text-editor.md) — Tiptap-backed editor with bold / italic / strike / lists / quote / undo-redo. Falls back to a non-editable preview when @tiptap/react is not bundled. Strings overridable via the `strings` prop.
 - [Features · Schema form](./features__schema-form.md) — Schema-driven form renderer built from the package form fields. Supports one cohesive form, section cards, controlled values, validation callbacks, and render-prop overrides.

package/.agents/skills/component-library-rules/references/components/base__avatar.md

@@ -60,7 +60,7 @@ export function AvatarSizes() {
 			<Avatar>
 				<AvatarFallback>ML</AvatarFallback>
 			</Avatar>
-			<Avatar className="size-avatar">
+			<Avatar>
 				<AvatarImage src="https://api.dicebear.com/7.x/avataaars/svg?seed=aiko" />
 				<AvatarFallback>AT</AvatarFallback>
 			</Avatar>
@@ -88,9 +88,9 @@ export function RealisticUserCard() {
 	const customer = MOCK_CUSTOMERS[0];
 
 	return (
-		<Item variant="outline" className="w-full max-w-md">
+		<Item variant="outline" padding="default" className="w-full max-w-md">
 			<ItemMedia variant="avatar">
-				<Avatar className="size-avatar-lg">
+				<Avatar>
 					<AvatarImage src={`https://api.dicebear.com/7.x/avataaars/svg?seed=${customer.avatarSeed}`} />
 					<AvatarFallback>{customer.name.split(' ').map((part) => part[0]).join('')}</AvatarFallback>
 				</Avatar>

package/.agents/skills/component-library-rules/references/components/base__carousel.md

@@ -228,7 +228,7 @@ export function ProductCarousel() {
 			<CarouselContent>
 				{products.map((product) => (
 					<CarouselItem key={product.id}>
-						<SmartCard padding="default" className="overflow-hidden">
+						<SmartCard padding="default" className="overflow-visible">
 							<div className="grid gap-3 sm:grid-cols-[1.2fr_1fr] sm:items-center">
 								<ProductVisual product={product} />
 								<div className="space-y-2">
@@ -265,7 +265,7 @@ export function InsideControlsCarousel() {
 							description={product.category}
 							icon={<Package className="size-4" />}
 							padding="default"
-							className="overflow-hidden"
+							className="overflow-visible"
 						>
 							<ProductVisual product={product} className="aspect-[16/10] w-full" />
 							<Text size="xs" type="secondary" className="mt-3">
@@ -319,7 +319,7 @@ export function GalleryCarousel() {
 				<CarouselContent className="-ml-3">
 					{products.slice(0, 4).map((product) => (
 						<CarouselItem key={product.id} className="pl-3">
-							<SmartCard padding="default" className="overflow-hidden">
+							<SmartCard padding="default" className="overflow-visible">
 								<div className="grid gap-4 md:grid-cols-[1.4fr_1fr] md:items-center">
 									<ProductVisual product={product} className="aspect-[16/10] w-full" />
 									<div className="space-y-3">
@@ -381,6 +381,7 @@ export function ProductGridGallery() {
 									icon={<ShoppingBag className="size-4" />}
 									headerEnd={<Badge variant={stockVariant(product.stock)}>{product.stock}</Badge>}
 									padding="default"
+									className="overflow-visible"
 								>
 									<ProductVisual product={product} className="aspect-[4/3] w-full" />
 									<div className="mt-3 grid grid-cols-2 gap-2">
@@ -428,6 +429,7 @@ export function TopNavigationCarousel() {
 							description={product.category}
 							icon={<ShoppingBag className="size-4" />}
 							headerEnd={<Badge variant={stockVariant(product.stock)}>{product.stock}</Badge>}
+							className="overflow-visible"
 						>
 							<Text size="xs" type="secondary">
 								{product.units} units sold this month.
@@ -450,6 +452,7 @@ export function ResponsiveCarousel() {
 							title={product.name}
 							description={product.category}
 							icon={<Package className="size-4" />}
+							className="overflow-visible"
 						>
 							<ProductVisual product={product} className="aspect-[4/3] w-full" />
 							<Text size="xs" type="secondary" className="mt-3">
@@ -471,7 +474,7 @@ export function VerticalCarousel() {
 			<CarouselContent className="h-64">
 				{products.map((product) => (
 					<CarouselItem key={product.id} className="basis-1/2">
-						<SmartCard title={product.name} description={product.category}>
+						<SmartCard title={product.name} description={product.category} className="overflow-visible">
 							<Text size="xs" type="secondary">Monthly revenue</Text>
 							<Text weight="semibold">{product.revenue}</Text>
 						</SmartCard>
@@ -497,7 +500,7 @@ export function LocalizedControls() {
 			<CarouselContent>
 				{products.slice(0, 2).map((product) => (
 					<CarouselItem key={product.id}>
-						<SmartCard title={product.name} description={product.category}>
+						<SmartCard title={product.name} description={product.category} className="overflow-visible">
 							<Text size="xs" type="secondary">Accessible labels are supplied through `strings`.</Text>
 						</SmartCard>
 					</CarouselItem>

package/.agents/skills/component-library-rules/references/components/base__css-variables.md

@@ -708,6 +708,7 @@ const PUBLIC_THEME_VARIABLES = new Set([
 	'--font-mono',
 	'--text-xxs',
 	'--text-xs',
+	'--text-pxs',
 	'--text-sm',
 	'--text-base',
 	'--text-lg',

package/.agents/skills/component-library-rules/references/components/base__currency.md

@@ -1,7 +1,7 @@
 ---
 id: base/currency
 title: "Currency"
-description: "MoneyDisplay and CurrencyPairPreview — locale-aware, dual-pricing-aware money rendering driven by useCurrency() / UIProvider config."
+description: "Currency formatting helpers, pair previews, and dual-pricing examples driven by useCurrency() / UIProvider config."
 layer: base
 family: "Display"
 sourcePath: src/components/base/currency
@@ -25,15 +25,15 @@ tags:
   - base
   - display
   - currency
-  - moneydisplay
-  - currencypairpreview
-  - locale
-  - aware
+  - formatting
+  - helpers
+  - pair
+  - previews
 ---
 
 # Currency
 
-MoneyDisplay and CurrencyPairPreview — locale-aware, dual-pricing-aware money rendering driven by useCurrency() / UIProvider config.
+Currency formatting helpers, pair previews, and dual-pricing examples driven by useCurrency() / UIProvider config.
 
 **Layer:** `base`
 **Source:** `src/components/base/currency`
@@ -46,11 +46,10 @@ The examples below use repository source aliases because they run inside the pre
 
 ## Overview
 
-`MoneyDisplay` renders a primary (and optional secondary) currency amount,
-using the active `useCurrency()` config for formatting, dual-pricing, and
-display mode. `CurrencyPairPreview` renders an inline `source → target`
-conversion. Both honour `UIProvider` config so consumers can flip the entire
-app to dual pricing or a different default currency in one place.
+Use this page for cross-currency behavior: dual pricing, conversion previews,
+provider configuration, and realistic mixed-currency rows. The focused
+`MoneyDisplay` component page lives at [Money display](#/base/money-display)
+so its component API is documented once.
 
 ## Default