admin-ui-starter-kit 0.4.5 → 0.6.1

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

@@ -8,26 +8,27 @@ Agents: prefer `INDEX.json` (structured) for discovery; this file is for humans.
 
 - [Accordion](./base__accordion.md) — Two tiers — pass-through compound parts (Accordion / AccordionItem / AccordionTrigger / AccordionContent) for full control, or SmartAccordion for the canonical icon + title + optional badge + body admin pattern.
 - [Alert](./base__alert.md) — Semantic notice primitive with icon, title, description, and responsive action regions.
+- [Avatar](./base__avatar.md) — Avatar, fallback initials, and stacked avatars for compact identity surfaces.
 - [Badge](./base__badge.md) — Status pills and chips for tags, counts, and inline state.
-- [Buttons](./base__buttons.md) — The base button family — BaseButton (variant × style × size), the higher-level Button (loader / tooltip / link wrapper), and specialty buttons (Google, Shopify, Text, PageAction).
-- [Cards (SmartCard)](./base__cards.md) — The composed card primitive — header (icon, title, suffix, slots), optional alert, expandable body, footer text or slot, and three surface chromes.
+- [Buttons](./base__buttons.md) — The base button family — BaseButton (semantic variants, style, package scale), the higher-level Button (loader / tooltip / link wrapper), and specialty buttons (Google, Shopify, Text, PageAction).
+- [Cards (SmartCard)](./base__cards.md) — The composed card primitive — header (icon, title, suffix, slots), optional alert, expandable body, footer text or slot, and calibrated card spacing.
 - [Carousel](./base__carousel.md) — Embla-backed carousel with keyboard navigation, orientation support, plugins, and base Button controls.
 - [Chart](./base__chart.md) — Token-aware Recharts helpers plus a composed ChartCard for admin analytics surfaces.
 - [Combobox](./base__combobox.md) — EnhancedCombobox and EnhancedComboboxMultiple — searchable, optionally grouped, with apply / close-on-select behaviours, async fetchers, custom rendering, and form integration.
 - [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.
 - [Date pickers](./base__date-pickers.md) — DatePicker (single / range / multiple) and MonthYearPicker — popover-based, locale-aware, with optional year dropdown and time input.
-- [Display](./base__display.md) — The display layer — Avatar, IconBadge, InlineStat, Tooltip, Separator, NotificationBanner, BooleanIndicator, ShowIf, ThrottleAlert, VisuallyHidden, PlaceholderPattern.
-- [Empty state](./base__empty-state.md) — Adaptive zero-data surface. Wrap with the right illustration per resource — products, users, search results, inbox. Slots for media / actions / footer; consumer overrides every string.
+- [Display utilities](./base__display-utilities.md) — Narrow display helpers only: separator, banners, boolean indicators, conditionals, progress, skeleton, and utility wrappers.
 - [Event calendar](./base__event-calendar.md) — Month view with categories, filtering, navigation rules, custom event rendering, and three day-heading variants.
 - [Forms](./base__forms.md) — The full form scope — FormField wrapper plus every field component exported from base/forms/fields: text inputs, numeric, selects, toggles, choice groups, date/time, repeaters, localized fields, and uploads.
-- [Frame](./base__frame.md) — Grouped panel primitive for related admin content, stacked records, and dense framed surfaces.
+- [Icon badge](./base__icon-badge.md) — Tokenized icon container for status, resource, and row media affordances.
 - [Item](./base__item.md) — Canonical row primitive — icon/avatar/image media, title + description content, optional actions. Use ItemGroup to compose lists.
 - [Map](./base__map.md) — Leaflet-backed map primitives — Map shell, MapTileLayer, MapMarker, MapPopup. Always wrap in a fixed-height container.
-- [Metadata list](./base__metadata-list.md) — Flexible label/value list for entity metadata. Three layouts (vertical grid, horizontal pills, two-column rows), per-item icons, tooltips, descriptions, and custom renderers — with first-class empty-state handling.
 - [Navigation](./base__navigation.md) — The navigation primitives — PageHeader, Breadcrumbs, ActionMenu, LanguageSwitcher, SectionNav, SideNav, AsideNavigationMenu, TabNavigationMenu, NavigationTabs, OverflowTabBar.
 - [Spinner](./base__spinner.md) — Loading indicator with three visual variants. Pairs with content placeholders, route transitions, and Suspense fallbacks.
-- [Table](./base__table.md) — DataTable + Pagination — TanStack-React-Table-backed, with sorting, row actions, sticky header, three sizes, and three surface chromes.
+- [Table](./base__table.md) — DataTable + Pagination — TanStack-React-Table-backed, with sorting, row actions, sticky header, calibrated table rhythm, and three surface chromes.
+- [Tooltip](./base__tooltip.md) — Tooltip provider, trigger, and content wrappers for short contextual help.
 - [Typography](./base__typography.md) — Heading, Text, Label, and TextLink — the four typography primitives every higher layer composes from.
 - [Upload tray](./base__upload-tray.md) — Drag-drop area + per-file progress rows + summary toolbar. Composes Dropzone and UploadProgressList. Framework-agnostic — the consumer drives the actual transfer.
 
@@ -38,35 +39,46 @@ Agents: prefer `INDEX.json` (structured) for discovery; this file is for humans.
 ## composed
 
 - [Composed · Admin](./composed__admin.md) — Team list, permissions, conversations, settings, inventory.
-- [Composed · AI](./composed__ai.md) — Summary block + classification panel.
+- [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 · AI (extras)](./composed__ai-new.md) — Confidence dial, prompt suggestions, token usage card, message bubble, tool call, citation, feedback.
 - [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.
-- [Composed · Commerce (extras)](./composed__commerce-extras.md) — Cart, coupon, order status, payment, tax breakdown, subscription, refund, address, voucher.
+- [Composed · Commerce](./composed__commerce.md) — Bookings, loyalty, discount stacks, shipment tracking, cart, coupons, payment, tax, subscription, refund, address, and voucher surfaces.
 - [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.
 - [Composed · Dense info cards](./composed__dense-info.md) — Five layout variants — dashboard, classification, financial, project, score.
+- [Empty state](./composed__empty-state.md) — Adaptive zero-data surface. Wrap with the right illustration per resource — products, users, search results, inbox. Slots for media / actions / footer; consumer overrides every string.
 - [Composed · Feature announcement](./composed__feature-announcement.md) — Highlight a new feature with tags and an action.
 - [Composed · Giftcard cards](./composed__giftcard-cards.md) — Five visual variants — gradient, compact, minimal, dark, illustrated.
 - [Composed · Gradient card](./composed__gradient-card.md) — Vivid gradient card with optional pattern, badge, alert, action.
+- [Inline stat](./composed__inline-stat.md) — Inline label/value pairs for counters, totals, and compact card rows. Use MetadataList for entity detail fields.
 - [Composed · Invoice header](./composed__invoice-header.md) — Top of an invoice — number, status, parties, amount.
 - [Composed · Invoice items](./composed__invoice-items.md) — Table, compact, detailed layouts with subtotal/tax/discount/total.
 - [Composed · Invoice mini](./composed__invoice-mini.md) — Compact invoice tile — paid / pending / overdue.
 - [Composed · Invoice table](./composed__invoice-table.md) — Line items with qty / price / total.
+- [Metadata list](./composed__metadata-list.md) — Flexible label/value list for entity metadata. Three layouts (vertical grid, horizontal pills, two-column rows), per-item icons, tooltips, descriptions, and custom renderers — with first-class empty-state handling.
 - [Composed · Navigation & boards](./composed__navigation.md) — Kanban, tab switcher, time ruler, vendor performance, experience activity.
 - [Composed · Navigation (extras)](./composed__navigation-extras.md) — BreadcrumbProgress wizard + CategoryNavCard sidebar.
 - [Composed · Onboarding · Checklist](./composed__onboarding-checklist.md) — Step-list accordion with completed / in-progress / pending status indicators. Auto-opens the next non-completed step. Strings + status ARIA fully overridable. Composes base/accordion.
+- [Composed · Resource selector card](./composed__resource-selector-card.md) — Selected-resource card for dialogs, forms, and show pages. The app owns picking, fetching, and routing.
 - [Composed · Timelines](./composed__timelines.md) — Read-only tracking timelines — steps, order, payment, activity stream, release changelog, project milestones. For interactive activity (segments, mass-config, resource registry, callbacks) see Features → Activity feed.
 - [Composed · Vendor profile](./composed__vendor-profile.md) — VendorProfileCard with metrics, stats and actions.
 
+## docs
+
+- [Design system consistency guide](./docs__design-system-consistency.md) — The operating manual for keeping the package cohesive: goals, ownership, token rules, drift detection, and browser-quality review.
+- [Installation](./docs__installation.md) — Install the package, import the stylesheet, and consume exact public subpaths.
+- [Overview](./docs__overview.md) — How the starter kit is organized, how to browse it, and which contracts consumers can rely on.
+- [Refinement guide](./docs__refinement-guide.md) — What changed in the showcase, why it matters, and how to keep polishing the package without losing the system contract.
+- [Showcase](./docs__showcase.md) — How to use this preview app as the package map, design review surface, and release verification aid.
+
 ## features
 
 - [Features · Activity feed](./features__activities.md) — Interactive activity feed — generic, framework-agnostic, with headline segments, callbacks (actor / resource / action), strings, slots, mass event configuration, and a save/restore resource registry. For read-only tracking timelines (order, payment, changelog, milestones) see Composed → Timelines.
 - [AI Chat](./features__ai-chat.md) — Framework-agnostic AI chat surface. Ties together prompt input, conversation, message renderer, queue, and the full composed/ai/* palette (reasoning, tool calls, attachments, artifacts, confirmations).
 - [Features · Card](./features__card.md) — Stateful feature cards for booking/event details and shared resource assignment. Selector state, confirmation, dialog chrome, slots, render-props, and strings stay callback-driven so consumers own persistence.
 - [Features · Comments](./features__comments.md) — Generic, framework-agnostic comments with rich-text composer (TipTap-backed), inline resource references (mentions, links, badges), attachment uploads with progress, and reactions. Every callback / registry flows as a direct prop — no provider.
+- [Features · Data view](./features__data-view.md) — Controlled data-view chrome for tables, filters, saved views, and pagination. Consumers own fetching, query state, table data, and persistence.
 - [Features · Enhanced activities](./features__enhanced-activities.md) — Shopify-style unified surface: domain events and comments under one chronological timeline. Comments render as note activities with MentionContent-powered user, booking, and order chips. Composer at the top uses the same TipTap-backed editor with the live mention trigger flow.
 - [Features · Event log](./features__event-log.md) — Unified, mentions-aware mixed-source log: comments + audit events + system messages + custom kinds under one chronological surface. Inline `@user` / `#booking` / `$order` triggers work in the composer; resource chips render with tone-driven Badge variants in every entry kind.
 - [Filters](./features__filters.md) — Composable filter system. Search + multi-select stay always visible; the rest collapse behind a Filters button. Provider-driven so it works with any data source.
@@ -85,6 +97,7 @@ 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 · 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.
 - [Features · Suggestions](./features__suggestions.md) — Framework-agnostic typeahead suggestions with a drop-in combobox and a headless hook. Consumers own fetching, selected-value persistence, telemetry, and result rendering.
@@ -96,11 +109,16 @@ Agents: prefer `INDEX.json` (structured) for discovery; this file is for humans.
 - [Layout · Auth shell](./layout__layout-auth.md) — Framework-neutral auth card and split shells for login, register, invite, reset, magic-link, and verification pages.
 - [Layout · Containers](./layout__layout-containers.md) — Container and Section primitives for page structure, width clamps, padding density, and semantic wrappers.
 - [Layout · Header](./layout__layout-header.md) — Topbar, breadcrumbs, command search, notifications, and action slots in a realistic app-shell canvas.
-- [Layout · Page](./layout__layout-page.md) — Page shell, header partials, actions, and content regions with framework-neutral links.
+- [Layout · Page](./layout__layout-page.md) — Page shell, index scaffolds, resource show shells, header partials, actions, and content regions with framework-neutral links.
 - [Layout · Sidebar](./layout__layout-sidebar.md) — Full app sidebar assembly plus reusable navigation, workspace, and footer item partials.
 - [Layout · Users & avatars](./layout__layout-users.md) — User identity surfaces used by layout headers, sidebars, menus, avatar groups, and status badges.
 - [Layout · Workspace](./layout__layout-workspace.md) — Nested record workspace shell with header, workflow navigation, scroll-owned body, and optional right rail.
 
+## services
+
+- [Actions service](./services__actions.md) — Framework-neutral action registry, lifecycle, overlay, request, guard, and feedback glue for shared admin actions.
+- [Hooks reference](./services__hooks.md) — Public hook import boundaries for provider defaults, layout helpers, action lifecycle, and feature headless state.
+
 ## ui
 
 - [UI · Alert](./ui__alert.md) — shadcn alert primitive: variants, with title/description/action.

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

@@ -189,7 +189,7 @@ export function VariantBordered() {
 
 export function VariantFlat() {
 	return (
-		<SmartCard padding="sm" className="w-full max-w-xl">
+		<SmartCard padding="default" className="w-full max-w-xl">
 			<SmartAccordion items={faqItems} variant="flat" iconStyle="none" defaultValue={['a']} />
 		</SmartCard>
 	);

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

@@ -116,8 +116,8 @@ export function AlertWithActions() {
 				12 team members have not enrolled. Enforcement begins at the end of the week.
 			</AlertDescription>
 			<AlertAction>
-				<Button variant="warning" buttonStyle="outline" size="xs">Review users</Button>
-				<Button variant="secondary" buttonStyle="ghost" size="xs">Dismiss</Button>
+				<Button variant="warning" buttonStyle="outline" size="small">Review users</Button>
+				<Button variant="secondary" buttonStyle="ghost" size="small">Dismiss</Button>
 			</AlertAction>
 		</Alert>
 	);
@@ -130,7 +130,7 @@ export function InverseAlert() {
 			<AlertTitle>New analytics view is available</AlertTitle>
 			<AlertDescription>Switch to the updated report builder from the workspace menu.</AlertDescription>
 			<AlertAction>
-				<Button variant="light" buttonStyle="outline" size="xs">Open builder</Button>
+				<Button variant="light" buttonStyle="outline" size="small">Open builder</Button>
 			</AlertAction>
 		</Alert>
 	);

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

@@ -0,0 +1,118 @@
+---
+id: base/avatar
+title: "Avatar"
+description: "Avatar, fallback initials, and stacked avatars for compact identity surfaces."
+layer: base
+family: "Display"
+sourcePath: src/components/base/display/avatar
+examples:
+  - AvatarSizes
+  - StackedAvatarsExample
+  - RealisticUserCard
+imports:
+  - @/components/base/badge
+  - @/components/base/display/avatar
+  - @/components/base/display/stacked-avatars
+  - @/components/base/item
+  - @/preview/_mocks
+publicImport: admin-ui-starter-kit/base/display
+tags:
+  - base
+  - display
+  - avatar
+  - fallback
+  - initials
+  - stacked
+  - avatars
+---
+
+# Avatar
+
+Avatar, fallback initials, and stacked avatars for compact identity surfaces.
+
+**Layer:** `base`
+**Source:** `src/components/base/display/avatar`
+**Consumer import:** `admin-ui-starter-kit/base/display`
+
+## Consumer import
+
+Consumers import this surface from `admin-ui-starter-kit/base/display`.
+The examples below use repository source aliases because they run inside the preview app; do not copy those aliases into consuming applications.
+
+## Examples
+
+```tsx
+import { CheckCircle2 } from 'lucide-react';
+
+import { Badge } from '@/components/base/badge';
+import { Avatar, AvatarFallback, AvatarImage } from '@/components/base/display/avatar';
+import { StackedAvatars } from '@/components/base/display/stacked-avatars';
+import { Item, ItemActions, ItemContent, ItemDescription, ItemMedia, ItemTitle } from '@/components/base/item';
+import { MOCK_CUSTOMERS } from '@/preview/_mocks';
+
+export function AvatarSizes() {
+	return (
+		<div className="flex items-end gap-space-md">
+			<Avatar size="small">
+				<AvatarImage src="https://api.dicebear.com/7.x/avataaars/svg?seed=sarah" />
+				<AvatarFallback>SS</AvatarFallback>
+			</Avatar>
+			<Avatar>
+				<AvatarFallback>ML</AvatarFallback>
+			</Avatar>
+			<Avatar className="size-avatar">
+				<AvatarImage src="https://api.dicebear.com/7.x/avataaars/svg?seed=aiko" />
+				<AvatarFallback>AT</AvatarFallback>
+			</Avatar>
+			<Avatar className="size-avatar-lg">
+				<AvatarFallback>DR</AvatarFallback>
+			</Avatar>
+		</div>
+	);
+}
+
+export function StackedAvatarsExample() {
+	return (
+		<StackedAvatars
+			users={MOCK_CUSTOMERS.slice(0, 5).map((customer) => ({
+				id: customer.id,
+				name: customer.name,
+				imageUrl: `https://api.dicebear.com/7.x/avataaars/svg?seed=${customer.avatarSeed}`,
+			}))}
+			max={3}
+		/>
+	);
+}
+
+export function RealisticUserCard() {
+	const customer = MOCK_CUSTOMERS[0];
+
+	return (
+		<Item variant="outline" className="w-full max-w-md">
+			<ItemMedia variant="avatar">
+				<Avatar className="size-avatar-lg">
+					<AvatarImage src={`https://api.dicebear.com/7.x/avataaars/svg?seed=${customer.avatarSeed}`} />
+					<AvatarFallback>{customer.name.split(' ').map((part) => part[0]).join('')}</AvatarFallback>
+				</Avatar>
+			</ItemMedia>
+			<ItemContent>
+				<ItemTitle>{customer.name}</ItemTitle>
+				<ItemDescription clamp={1}>{customer.email}</ItemDescription>
+			</ItemContent>
+			<ItemActions>
+				<Badge variant="success" className="whitespace-nowrap">
+					<CheckCircle2 className="size-icon-sm" />
+					Verified
+				</Badge>
+			</ItemActions>
+		</Item>
+	);
+}
+```
+
+## Example exports
+
+- `AvatarSizes`
+- `StackedAvatarsExample`
+- `RealisticUserCard`
+

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

@@ -1,7 +1,7 @@
 ---
 id: base/buttons
 title: "Buttons"
-description: "The base button family — BaseButton (variant × style × size), the higher-level Button (loader / tooltip / link wrapper), and specialty buttons (Google, Shopify, Text, PageAction)."
+description: "The base button family — BaseButton (semantic variants, style, package scale), the higher-level Button (loader / tooltip / link wrapper), and specialty buttons (Google, Shopify, Text, PageAction)."
 layer: base
 family: "Foundations"
 sourcePath: src/components/base/buttons
@@ -38,12 +38,12 @@ tags:
   - button
   - family
   - basebutton
-  - variant
+  - semantic
 ---
 
 # Buttons
 
-The base button family — BaseButton (variant × style × size), the higher-level Button (loader / tooltip / link wrapper), and specialty buttons (Google, Shopify, Text, PageAction).
+The base button family — BaseButton (semantic variants, style, package scale), the higher-level Button (loader / tooltip / link wrapper), and specialty buttons (Google, Shopify, Text, PageAction).
 
 **Layer:** `base`
 **Source:** `src/components/base/buttons`
@@ -58,10 +58,16 @@ The examples below use repository source aliases because they run inside the pre
 
 `BaseButton` is the foundational primitive — eight semantic `variant`s (dark,
 primary, secondary, error, warning, success, light, action) crossed with three
-`buttonStyle`s (solid, outline, ghost) and four sizes (xs, sm, default, lg)
-plus four icon-only sizes. `Button` layers on optional `loading`, `withTooltip`,
-and `href` so a single component covers most call sites. The specialty buttons
-are pre-styled wrappers for common patterns.
+`buttonStyle`s (solid, outline, ghost). `Button` layers on optional `loading`,
+`withTooltip`, and `href` so a single component covers most call sites. The
+specialty buttons are pre-styled wrappers for common patterns.
+
+Routine usage omits `size`; the default comes from
+`UIProvider.forms.defaultControlSize` and resolves through the shared
+control height, padding, gap, icon, and text tokens. Public sizing is intentionally limited to `default` / `small` plus
+the matching icon-only controls (`icon` / `icon-small`). Tune the actual
+heights, gaps, icon sizes, and text scale in CSS instead of repeating
+one-off size props.
 
 ## Default
 
@@ -87,7 +93,7 @@ are pre-styled wrappers for common patterns.
 	<Examples.VariantStyleMatrix />
 </Example>
 
-## Sizes
+## Scale
 
 <Example name="Sizes" source={examplesSource}>
 	<Examples.Sizes />
@@ -189,8 +195,8 @@ import { Text } from '@/components/typography';
 
 const VARIANTS: ButtonVariant[] = ['dark', 'primary', 'secondary', 'error', 'warning', 'success', 'light', 'action'];
 const STYLES: ButtonStyle[] = ['solid', 'outline', 'ghost'];
-const SIZES: ButtonSize[] = ['xs', 'sm', 'default', 'lg'];
-const ICON_SIZES: ButtonSize[] = ['icon-xs', 'icon-sm', 'icon', 'icon-lg'];
+const SIZES: ButtonSize[] = ['default', 'small'];
+const ICON_SIZES: ButtonSize[] = ['icon', 'icon-small'];
 
 export function Default() {
 	return <Button>Save changes</Button>;
@@ -364,7 +370,7 @@ export function TooltipButtonExample() {
 				withTooltip="Permanently delete"
 				variant="error"
 				icon={Trash2}
-				size="icon-sm"
+				size="icon-small"
 				aria-label="Permanently delete"
 			>
 				{''}
@@ -392,9 +398,8 @@ export function ShopifyButtonExample() {
 export function TextButtonSizes() {
 	return (
 		<div className="flex flex-wrap items-baseline gap-4">
-			<TextButton size="xs">Extra small link</TextButton>
-			<TextButton size="sm">Small link</TextButton>
-			<TextButton size="base">Base link</TextButton>
+			<TextButton size="default">Default link</TextButton>
+			<TextButton size="small">Small link</TextButton>
 		</div>
 	);
 }
@@ -412,9 +417,8 @@ export function PageActionButtonVariants() {
 export function PageActionButtonSizes() {
 	return (
 		<div className="flex flex-wrap items-center gap-2">
-			<PageActionButton variant="primary" size="xs">xs</PageActionButton>
-			<PageActionButton variant="primary" size="sm">sm</PageActionButton>
-			<PageActionButton variant="primary" size="base">base</PageActionButton>
+			<PageActionButton variant="primary" size="default">Default</PageActionButton>
+			<PageActionButton variant="primary" size="small">Small</PageActionButton>
 		</div>
 	);
 }

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

@@ -1,7 +1,7 @@
 ---
 id: base/cards
 title: "Cards (SmartCard)"
-description: "The composed card primitive — header (icon, title, suffix, slots), optional alert, expandable body, footer text or slot, and three surface chromes."
+description: "The composed card primitive — header (icon, title, suffix, slots), optional alert, expandable body, footer text or slot, and calibrated card spacing."
 layer: base
 family: "Foundations"
 sourcePath: src/components/base/cards
@@ -12,6 +12,7 @@ examples:
   - AlertVariants
   - PaddingSizes
   - SurfaceVariants
+  - FrameMode
   - HeaderSlots
   - HeaderAndFooterDividers
   - ExpandableUncontrolled
@@ -40,7 +41,7 @@ tags:
 
 # Cards (SmartCard)
 
-The composed card primitive — header (icon, title, suffix, slots), optional alert, expandable body, footer text or slot, and three surface chromes.
+The composed card primitive — header (icon, title, suffix, slots), optional alert, expandable body, footer text or slot, and calibrated card spacing.
 
 **Layer:** `base`
 **Source:** `src/components/base/cards`
@@ -55,10 +56,19 @@ The examples below use repository source aliases because they run inside the pre
 
 `SmartCard` is the canonical card surface — every dashboard tile, settings
 panel, or KPI block runs through it. Three `surface` chromes (`card`, `flat`,
-`framed`), three padding scales, optional `headerStart` / `headerEnd` /
+`framed`), package-scale padding, optional `headerStart` / `headerEnd` /
 `headerAction` slots, action menus, alert bands, footer text or `footerSlot`,
 and an `expandable` body for long content.
 
+Use `surface="framed"` when a surface needs a grouped-card feel without a
+separate wrapper route or nested borders. It is still a SmartCard, so padding,
+headers, alerts, actions, and footer slots behave identically.
+
+Card padding props are intentionally limited to `default` and `small`; the
+measurements resolve through `--surface-*` and the shared `--space-*` scale. Use
+`UIProvider.card.defaultPadding` or CSS variables when changing the default
+card rhythm across an app.
+
 ## Default
 
 <Example name="Default" source={examplesSource}>
@@ -67,11 +77,15 @@ and an `expandable` body for long content.
 
 ## Surface variants
 
+<Example name="FrameMode" source={examplesSource}>
+	<Examples.FrameMode />
+</Example>
+
 <Example name="SurfaceVariants" source={examplesSource}>
 	<Examples.SurfaceVariants />
 </Example>
 
-## Padding sizes
+## Padding Scale
 
 <Example name="PaddingSizes" source={examplesSource}>
 	<Examples.PaddingSizes />
@@ -156,7 +170,7 @@ import {
 	CardContent,
 	CardFooter,
 } from '@/components/base/cards';
-import { Avatar, AvatarFallback } from '@/components/base/display/avatar';
+import { Avatar, AvatarFallback, AvatarGroup, AvatarGroupCount } from '@/components/base/display/avatar';
 import { Text } from '@/components/typography/text';
 import { Badge } from '@/components/base/badge';
 
@@ -194,7 +208,7 @@ export function WithActions() {
 				{ id: 'edit', label: 'Edit', icon: <Pencil className="size-3.5" />, onClick: () => {} },
 				{ id: 'delete', label: 'Delete', icon: <Trash2 className="size-3.5" />, onClick: () => {} },
 			]}
-			headerEnd={<Badge variant="info" size="sm">Pending</Badge>}
+			headerEnd={<Badge variant="info" size="default">Pending</Badge>}
 		>
 			<Text type="secondary">3 vouchers — wellness, food, adventure.</Text>
 		</SmartCard>
@@ -226,7 +240,7 @@ export function AlertVariants() {
 export function PaddingSizes() {
 	return (
 		<div className="grid w-full max-w-md gap-3">
-			{(['sm', 'base', 'lg'] as const).map((p) => (
+			{(['default', 'small'] as const).map((p) => (
 				<SmartCard key={p} title={`padding="${p}"`} padding={p}>
 					<Text>Card body with {p} padding.</Text>
 				</SmartCard>
@@ -244,13 +258,36 @@ export function SurfaceVariants() {
 			<SmartCard surface="flat" title="Flat" description="No border, no shadow.">
 				<Text type="secondary">Use when nesting inside another surface.</Text>
 			</SmartCard>
-			<SmartCard surface="framed" title="Framed" description="Matted polaroid look.">
-				<Text type="secondary">5px outer border + 1px hairline inner.</Text>
+			<SmartCard surface="framed" title="Framed" description="Soft grouped surface.">
+				<Text type="secondary">One clean card border with a tokenized outer ring.</Text>
 			</SmartCard>
 		</div>
 	);
 }
 
+export function FrameMode() {
+	return (
+		<SmartCard
+			surface="framed"
+			title="Frame mode"
+			description="A SmartCard surface for grouped panels without nesting a second frame."
+			className="w-full max-w-md"
+			headerEnd={<Badge variant="secondary">surface=&quot;framed&quot;</Badge>}
+		>
+			<div className="grid gap-space-md">
+				<div className="flex items-center justify-between rounded-radius bg-muted/45 px-row-x py-row-y">
+					<Text weight="medium">Panel content</Text>
+					<Badge variant="success">Ready</Badge>
+				</div>
+				<Text size="xs" type="secondary">
+					Use this when a section needs a stronger boundary than a card, but should
+					still inherit SmartCard spacing, header slots, alerts, and footer behavior.
+				</Text>
+			</div>
+		</SmartCard>
+	);
+}
+
 export function HeaderSlots() {
 	return (
 		<SmartCard
@@ -290,16 +327,14 @@ export function HeaderAndFooterDividers() {
 				</Button>
 			}
 		>
-			<div className="flex items-center -space-x-2 pt-2">
+			<AvatarGroup className="pt-2">
 				{['SC', 'MR', 'EW'].map((init) => (
 					<Avatar key={init} className="ring-2 ring-background">
 						<AvatarFallback>{init}</AvatarFallback>
 					</Avatar>
 				))}
-				<span className="ml-2 inline-flex size-6 items-center justify-center rounded-full border border-background bg-muted text-xs text-muted-foreground">
-					+3
-				</span>
-			</div>
+				<AvatarGroupCount className="ml-2">+3</AvatarGroupCount>
+			</AvatarGroup>
 		</SmartCard>
 	);
 }
@@ -475,6 +510,7 @@ export function StatRowClickable() {
 - `AlertVariants`
 - `PaddingSizes`
 - `SurfaceVariants`
+- `FrameMode`
 - `HeaderSlots`
 - `HeaderAndFooterDividers`
 - `ExpandableUncontrolled`

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="sm" className="overflow-hidden">
+						<SmartCard padding="default" className="overflow-hidden">
 							<div className="grid gap-3 sm:grid-cols-[1.2fr_1fr] sm:items-center">
 								<ProductVisual product={product} />
 								<div className="space-y-2">
@@ -264,7 +264,7 @@ export function InsideControlsCarousel() {
 							title={product.name}
 							description={product.category}
 							icon={<Package className="size-4" />}
-							padding="sm"
+							padding="default"
 							className="overflow-hidden"
 						>
 							<ProductVisual product={product} className="aspect-[16/10] w-full" />
@@ -293,7 +293,7 @@ function GalleryThumbnails() {
 					type="button"
 					variant="secondary"
 					buttonStyle="ghost"
-					size="sm"
+					size="default"
 					aria-label={`Show ${product.name}`}
 					aria-current={selectedIndex === index ? 'true' : undefined}
 					className="h-auto min-w-0 justify-start rounded-lg p-1 data-[active=true]:ring-2 data-[active=true]:ring-ring/40"
@@ -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="sm" className="overflow-hidden">
+							<SmartCard padding="default" className="overflow-hidden">
 								<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">
@@ -380,7 +380,7 @@ export function ProductGridGallery() {
 									description={product.category}
 									icon={<ShoppingBag className="size-4" />}
 									headerEnd={<Badge variant={stockVariant(product.stock)}>{product.stock}</Badge>}
-									padding="sm"
+									padding="default"
 								>
 									<ProductVisual product={product} className="aspect-[4/3] w-full" />
 									<div className="mt-3 grid grid-cols-2 gap-2">