admin-ui-starter-kit 0.5.0 → 0.6.2

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

@@ -1,57 +1,65 @@
 [
   {"id":"base/accordion","title":"Accordion","description":"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.","layer":"base","family":"Display","tags":["base","display","accordion","tiers","pass","through","compound"],"sourcePath":"src/components/base/accordion","publicImport":"admin-ui-starter-kit/base/accordion","examples":["Default","VariantCard","VariantBordered","VariantFlat","IconStyleMedallion","IconStyleInline","IconStyleNone","MultipleOpen","WithBadgeAndDisabled","CompoundApi","RealisticFAQ"],"doc":"./base__accordion.md"},
   {"id":"base/alert","title":"Alert","description":"Semantic notice primitive with icon, title, description, and responsive action regions.","layer":"base","family":"Display","tags":["base","display","alert","semantic","notice","primitive","icon"],"sourcePath":"src/components/base/display/alert","publicImport":"admin-ui-starter-kit/base/display","examples":["AlertVariants","AlertWithActions","InverseAlert","StatusRoleAlert"],"doc":"./base__alert.md"},
+  {"id":"base/avatar","title":"Avatar","description":"Avatar, fallback initials, and stacked avatars for compact identity surfaces.","layer":"base","family":"Display","tags":["base","display","avatar","fallback","initials","stacked","avatars"],"sourcePath":"src/components/base/display/avatar","publicImport":"admin-ui-starter-kit/base/display","examples":["AvatarSizes","StackedAvatarsExample","RealisticUserCard"],"doc":"./base__avatar.md"},
   {"id":"base/badge","title":"Badge","description":"Status pills and chips for tags, counts, and inline state.","layer":"base","family":"Foundations","tags":["base","foundations","badge","status","pills","chips","tags"],"sourcePath":"src/components/base/badge","publicImport":"admin-ui-starter-kit/base/badge","examples":["Default","Variants","WithDot"],"doc":"./base__badge.md"},
-  {"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).","layer":"base","family":"Foundations","tags":["base","foundations","buttons","button","family","basebutton","variant"],"sourcePath":"src/components/base/buttons","publicImport":"admin-ui-starter-kit/base/buttons","examples":["Default","AllVariantsSolid","AllVariantsOutline","AllVariantsGhost","VariantStyleMatrix","Sizes","IconOnlySizes","WithIconLeft","WithIconRight","StateDisabled","StateFullWidth","ButtonComboFeatures","LoaderButtonStates","LoaderButtonInteractive","TooltipButtonExample","GoogleButtonExample","ShopifyButtonExample","TextButtonSizes","PageActionButtonVariants","PageActionButtonSizes","RealisticToolbar"],"doc":"./base__buttons.md"},
-  {"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.","layer":"base","family":"Foundations","tags":["base","foundations","cards","smartcard","composed","card","primitive"],"sourcePath":"src/components/base/cards","publicImport":"admin-ui-starter-kit/base/cards","examples":["Default","WithIconTooltipFooter","WithActions","AlertVariants","PaddingSizes","SurfaceVariants","HeaderSlots","HeaderAndFooterDividers","ExpandableUncontrolled","ExpandableCustomLabels","Skeleton","MetricKPICard","NotificationCard","PrimitiveComposition","StatRowClickable"],"doc":"./base__cards.md"},
+  {"id":"base/buttons","title":"Buttons","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","tags":["base","foundations","buttons","button","family","basebutton","semantic"],"sourcePath":"src/components/base/buttons","publicImport":"admin-ui-starter-kit/base/buttons","examples":["Default","AllVariantsSolid","AllVariantsOutline","AllVariantsGhost","VariantStyleMatrix","Sizes","IconOnlySizes","WithIconLeft","WithIconRight","StateDisabled","StateFullWidth","ButtonComboFeatures","LoaderButtonStates","LoaderButtonInteractive","TooltipButtonExample","GoogleButtonExample","ShopifyButtonExample","TextButtonSizes","PageActionButtonVariants","PageActionButtonSizes","RealisticToolbar"],"doc":"./base__buttons.md"},
+  {"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 calibrated card spacing.","layer":"base","family":"Foundations","tags":["base","foundations","cards","smartcard","composed","card","primitive"],"sourcePath":"src/components/base/cards","publicImport":"admin-ui-starter-kit/base/cards","examples":["Default","WithIconTooltipFooter","WithActions","AlertVariants","PaddingSizes","SurfaceVariants","FrameMode","HeaderSlots","HeaderAndFooterDividers","ExpandableUncontrolled","ExpandableCustomLabels","Skeleton","MetricKPICard","NotificationCard","PrimitiveComposition","StatRowClickable"],"doc":"./base__cards.md"},
   {"id":"base/carousel","title":"Carousel","description":"Embla-backed carousel with keyboard navigation, orientation support, plugins, and base Button controls.","layer":"base","family":"Navigation & data","tags":["base","navigation","data","carousel","embla","backed","keyboard","orientation"],"sourcePath":"src/components/base/carousel","publicImport":"admin-ui-starter-kit/base/carousel","examples":["ProductCarousel","InsideControlsCarousel","GalleryCarousel","ProductGridGallery","TopNavigationCarousel","ResponsiveCarousel","VerticalCarousel","LocalizedControls"],"doc":"./base__carousel.md"},
   {"id":"base/chart","title":"Chart","description":"Token-aware Recharts helpers plus a composed ChartCard for admin analytics surfaces.","layer":"base","family":"Display","tags":["base","display","chart","token","aware","recharts","helpers"],"sourcePath":"src/components/base/display/chart","publicImport":"admin-ui-starter-kit/base/display/chart","examples":["BarChartCard","AreaChartCard","LineChartCard","DonutChartCard","RadialChartCard","MixedSeriesChartCard"],"doc":"./base__chart.md"},
-  {"id":"base/combobox","title":"Combobox","description":"EnhancedCombobox and EnhancedComboboxMultiple — searchable, optionally grouped, with apply / close-on-select behaviours, async fetchers, custom rendering, and form integration.","layer":"base","family":"Forms & inputs","tags":["base","forms","inputs","combobox","enhancedcombobox","enhancedcomboboxmultiple","searchable","optionally"],"sourcePath":"src/components/base/combobox","publicImport":"admin-ui-starter-kit/base/combobox","examples":["Default","SingleSelect","SingleHighlightMatch","SingleCreatable","MultipleSelect","MultipleApplyButton","MultipleCloseOnSelect","MultipleGrouped","GroupedTeamByRole","AsyncCustomers","AsyncResourceCustomerPicker","AsyncDebouncedSearch","AsyncWithLoadMore","CustomItemRendering","CustomGroupLabels","SizeSm","SizeMd","SizeLg","Disabled","Invalid","MinSearchLength","RealisticCustomerPicker","FormFieldIntegration"],"doc":"./base__combobox.md"},
+  {"id":"base/combobox","title":"Combobox","description":"EnhancedCombobox and EnhancedComboboxMultiple — searchable, optionally grouped, with apply / close-on-select behaviours, async fetchers, custom rendering, and form integration.","layer":"base","family":"Forms & inputs","tags":["base","forms","inputs","combobox","enhancedcombobox","enhancedcomboboxmultiple","searchable","optionally"],"sourcePath":"src/components/base/combobox","publicImport":"admin-ui-starter-kit/base/combobox","examples":["Default","SingleSelect","SingleHighlightMatch","SingleCreatable","MultipleSelect","MultipleApplyButton","MultipleCloseOnSelect","MultipleGrouped","GroupedTeamByRole","AsyncCustomers","AsyncResourceCustomerPicker","AsyncDebouncedSearch","AsyncWithLoadMore","CustomItemRendering","CustomGroupLabels","CssVariableScale","Disabled","Invalid","MinSearchLength","RealisticCustomerPicker","FormFieldIntegration"],"doc":"./base__combobox.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/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/display","title":"Display","description":"The display layer — Avatar, IconBadge, InlineStat, Tooltip, Separator, NotificationBanner, BooleanIndicator, ShowIf, ThrottleAlert, VisuallyHidden, PlaceholderPattern.","layer":"base","family":"Display","tags":["base","display","layer","avatar","iconbadge","inlinestat"],"sourcePath":"src/components/base/display","publicImport":"admin-ui-starter-kit/base/display","examples":["NotificationBannerVariants","AvatarSizes","StackedAvatarsExample","IconBadgeTones","IconBadgeShapes","IconBadgeSizes","InlineStatLayouts","SeparatorExample","TooltipExample","BooleanIndicatorExample","ShowIfExample","ThrottleAlertExample","VisuallyHiddenExample","PlaceholderPatternExample","AlertExample","ProgressExample","SkeletonExample","CollapsibleExample","DialogExample","DateBlockExample","MoneyDisplayExample","QRCodeExample","RealisticUserCard"],"doc":"./base__display.md"},
-  {"id":"base/empty-state","title":"Empty state","description":"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.","layer":"base","family":"Display","tags":["base","display","empty-state","empty","state","adaptive","zero"],"sourcePath":"src/components/base/display/empty-state","publicImport":"admin-ui-starter-kit/base/display","examples":["Default","NoProductsWithActions","NoTeamMembers","NoSearchResults","InboxZero","PaddingCompact","PaddingBase","PaddingLoose","DashedBorderDropZone","StringsPropLocalisation","RenderPropCustomMedia"],"doc":"./base__empty-state.md"},
+  {"id":"base/display-utilities","title":"Display utilities","description":"Narrow display helpers only: separator, banners, boolean indicators, conditionals, progress, skeleton, and utility wrappers.","layer":"base","family":"Display","tags":["base","display","utilities","narrow","helpers","only"],"sourcePath":"src/components/base/display","publicImport":"admin-ui-starter-kit/base/display","examples":["NotificationBannerVariants","SeparatorExample","BooleanIndicatorExample","ShowIfExample","ThrottleAlertExample","VisuallyHiddenExample","PlaceholderPatternExample","AlertExample","ProgressExample","SkeletonExample","CollapsibleExample","DialogExample","DateBlockExample","MoneyDisplayExample","QRCodeExample"],"doc":"./base__display-utilities.md"},
   {"id":"base/event-calendar","title":"Event calendar","description":"Month view with categories, filtering, navigation rules, custom event rendering, and three day-heading variants.","layer":"base","family":"Navigation & data","tags":["base","navigation","data","event-calendar","event","calendar","month","view"],"sourcePath":"src/components/base/event-calendar","publicImport":"admin-ui-starter-kit/base/event-calendar","examples":["Default","RangeModeMonthYearCompactMonthYearJump","NavigationLimitsDisabledDates","FilterEventRenderEventCustomEventRendering","DayHeadingVariantTinted","DayHeadingVariantBordered","DayHeadingVariantAccent","WithCustomStringsBG"],"doc":"./base__event-calendar.md"},
   {"id":"base/forms","title":"Forms","description":"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.","layer":"base","family":"Forms & inputs","tags":["base","forms","inputs","full","form","scope","formfield"],"sourcePath":"src/components/base/forms","publicImport":"admin-ui-starter-kit/base/forms","examples":["BasicField","WithError","WithHelperText","WorkflowChrome","InputBasic","InputWithIcons","PasswordInputExample","SlugFieldExample","InputWithAddons","InputClearableLoading","InputCharacterCount","TextareaExample","DecimalInputExample","PercentageInputExample","CurrencyInputExample","MoneyInputExample","WeightInputExample","DimensionsInputExample","SelectExample","RichSelectExample","RoundingModeSelectExample","SwitchExample","CheckboxExample","ToggleFieldExample","SwitchCardExample","PillRadioGroupExample","ListRadioGroupExample","CardRadioGroupExample","CardCheckboxGroupExample","DateTimeInputExample","TimePickerExample","SliderExample","TagsInputExample","PhoneInputExample","CoordinatesInputExample","StringRepeaterExample","ObjectRepeaterExample","KeyValueEditorExample","ListExample","LocalizedStringFieldExample","LocalizedObjectFieldExample","LocalizedStringRepeaterExample","AvatarUploadExample","DropzoneExample","WholeForm"],"doc":"./base__forms.md"},
-  {"id":"base/frame","title":"Frame","description":"Grouped panel primitive for related admin content, stacked records, and dense framed surfaces.","layer":"base","family":"Foundations","tags":["base","foundations","frame","grouped","panel","primitive","related"],"sourcePath":"src/components/base/frame","publicImport":"admin-ui-starter-kit/base/frame","examples":["DefaultFrame","StackedPanels","InverseFrame","DenseFitPanel","FrameVariantMatrix"],"doc":"./base__frame.md"},
+  {"id":"base/icon-badge","title":"Icon badge","description":"Tokenized icon container for status, resource, and row media affordances.","layer":"base","family":"Display","tags":["base","display","icon-badge","icon","badge","tokenized","container"],"sourcePath":"src/components/base/display/icon-badge","publicImport":"admin-ui-starter-kit/base/display","examples":["IconBadgeTones","IconBadgeShapes","IconBadgeSmallDefault"],"doc":"./base__icon-badge.md"},
   {"id":"base/item","title":"Item","description":"Canonical row primitive — icon/avatar/image media, title + description content, optional actions. Use ItemGroup to compose lists.","layer":"base","family":"Foundations","tags":["base","foundations","item","canonical","row","primitive","icon"],"sourcePath":"src/components/base/item","publicImport":"admin-ui-starter-kit/base/item","examples":["Basic","Variants","PolymorphicLink"],"doc":"./base__item.md"},
   {"id":"base/map","title":"Map","description":"Leaflet-backed map primitives — Map shell, MapTileLayer, MapMarker, MapPopup. Always wrap in a fixed-height container.","layer":"base","family":"Navigation & data","tags":["base","navigation","data","map","leaflet","backed","primitives","shell"],"sourcePath":"src/components/base/map","publicImport":"admin-ui-starter-kit/base/map","examples":["Default","MultipleMarkers","TighterZoom","CompactSize"],"doc":"./base__map.md"},
-  {"id":"base/metadata-list","title":"Metadata list","description":"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.","layer":"base","family":"","tags":["base","metadata","list","flexible","label","value"],"sourcePath":"src/components/base/display/metadata","publicImport":"admin-ui-starter-kit/base/display/metadata","examples":["APISurface","Vertical2ColumnNoIcons","VerticalSingleColumnNoIcons","RowsTwoColumnWithHairlines","RowsReceiptStyle","RowsWithIconsTooltips","SectionedMultiCard","Dense4ColumnOverview","Example3ColumnWithIcons","HorizontalPillSummary","WithTitleSeparator","EmptyStateFallbacksCustomRenderers"],"doc":"./base__metadata-list.md"},
   {"id":"base/navigation","title":"Navigation","description":"The navigation primitives — PageHeader, Breadcrumbs, ActionMenu, LanguageSwitcher, SectionNav, SideNav, AsideNavigationMenu, TabNavigationMenu, NavigationTabs, OverflowTabBar.","layer":"base","family":"Navigation & data","tags":["base","navigation","data","primitives","pageheader","breadcrumbs","actionmenu"],"sourcePath":"src/components/base/navigation","publicImport":"admin-ui-starter-kit/base/navigation","examples":["PageHeaderExample","SectionNavSticky","BreadcrumbsSizes","ActionMenuExample","LanguageSwitcherButtons","LanguageSwitcherInline","AsideNavigationMenuExample","TabNavigationMenuExample","NavigationTabsRound","SideNavCollapsibleGroups","OverflowTabBarResponsiveWithMoreMenu"],"doc":"./base__navigation.md"},
-  {"id":"base/spinner","title":"Spinner","description":"Loading indicator with three visual variants. Pairs with content placeholders, route transitions, and Suspense fallbacks.","layer":"base","family":"","tags":["base","spinner","loading","indicator","visual","variants"],"sourcePath":"src/components/base/spinner","publicImport":"admin-ui-starter-kit/base/spinner","examples":["Default","Variants","WithLabel","CustomColour","SectionPlaceholder"],"doc":"./base__spinner.md"},
-  {"id":"base/table","title":"Table","description":"DataTable + Pagination — TanStack-React-Table-backed, with sorting, row actions, sticky header, three sizes, and three surface chromes.","layer":"base","family":"Navigation & data","tags":["base","navigation","data","table","datatable","pagination","tanstack","react"],"sourcePath":"src/components/base/table","publicImport":"admin-ui-starter-kit/base/table","examples":["BasicDefaultSizeXsCompact","SizeSm","SizeBase","SurfaceGlassHeaderTransparentCleanOutlineNoMutedHeader","SurfaceFlatInsideSmartCardTableRendersNoChrome","SizeSmGlassExplicitCellTextScaling","WithSortingRowActions","PaginationExample","RealisticOrdersTable","CellRenderers","IndexTableCells","WithRowSelection","WithColumnVisibility","WithCustomToolbar","DataViewChrome","StickyHeaderAndFirstColumn","EmptyState"],"doc":"./base__table.md"},
+  {"id":"base/spinner","title":"Spinner","description":"Loading indicator with three visual variants. Pairs with content placeholders, route transitions, and Suspense fallbacks.","layer":"base","family":"Feedback","tags":["base","feedback","spinner","loading","indicator","visual","variants"],"sourcePath":"src/components/base/spinner","publicImport":"admin-ui-starter-kit/base/spinner","examples":["Default","Variants","WithLabel","CustomColour","SectionPlaceholder"],"doc":"./base__spinner.md"},
+  {"id":"base/table","title":"Table","description":"DataTable + Pagination — TanStack-React-Table-backed, with sorting, row actions, sticky header, calibrated table rhythm, and three surface chromes.","layer":"base","family":"Navigation & data","tags":["base","navigation","data","table","datatable","pagination","tanstack","react"],"sourcePath":"src/components/base/table","publicImport":"admin-ui-starter-kit/base/table","examples":["BasicDefault","ComfortableTable","SurfaceGlassHeaderTransparentCleanOutlineNoMutedHeader","SurfaceFlatInsideSmartCardTableRendersNoChrome","WithSortingRowActions","PaginationExample","RealisticOrdersTable","FilteredTabbedOrdersTable","CellRenderers","IndexTableCells","WithRowSelection","WithColumnVisibility","WithCustomToolbar","DataViewChrome","StickyHeaderAndFirstColumn","EmptyState"],"doc":"./base__table.md"},
+  {"id":"base/tooltip","title":"Tooltip","description":"Tooltip provider, trigger, and content wrappers for short contextual help.","layer":"base","family":"Display","tags":["base","display","tooltip","provider","trigger","content","wrappers"],"sourcePath":"src/components/base/display/tooltip","publicImport":"admin-ui-starter-kit/base/display","examples":["TooltipExample"],"doc":"./base__tooltip.md"},
   {"id":"base/typography","title":"Typography","description":"Heading, Text, Label, and TextLink — the four typography primitives every higher layer composes from.","layer":"base","family":"Foundations","tags":["base","foundations","typography","heading","text","label","textlink"],"sourcePath":"src/components/typography","publicImport":"admin-ui-starter-kit/typography","examples":["HeadingTags","HeadingWithSubHeading","TextSizes","TextTypes","TextWeights","TextLineHeights","TextAlignment","TextContentAndHTML","TextTags","LabelExample","TextLinkVariants","TextLinkSizes","HighLightExample","UnderlineExample","DangerousHTMLExample","RealisticArticle"],"doc":"./base__typography.md"},
   {"id":"base/upload-tray","title":"Upload tray","description":"Drag-drop area + per-file progress rows + summary toolbar. Composes Dropzone and UploadProgressList. Framework-agnostic — the consumer drives the actual transfer.","layer":"base","family":"Forms & inputs","tags":["base","forms","inputs","fields","upload","tray","drag","drop"],"sourcePath":"src/components/base/forms/fields","publicImport":"admin-ui-starter-kit/base/forms","examples":["Default","EmptyDropzoneOnly","MixedItemStates","LiveSimulatedUpload","LocalisedFrench"],"doc":"./base__upload-tray.md"},
   {"id":"common/brand","title":"Common · Brand","description":"Inline Logo + AppLogo variants used by the preview shell.","layer":"common","family":"Branding","tags":["common","branding","_brand","brand","inline","logo","applogo"],"sourcePath":"src/preview/_brand","publicImport":"","examples":["LogoExample","AppLogoSizes","AppLogoVariants"],"doc":"./common__brand.md"},
   {"id":"composed/admin","title":"Composed · Admin","description":"Team list, permissions, conversations, settings, inventory.","layer":"composed","family":"Admin","tags":["composed","admin","team","list","permissions","conversations"],"sourcePath":"src/components/composed/admin","publicImport":"admin-ui-starter-kit/composed/admin","examples":["TeamMembers","RolePermissions","RecentConversations","SettingsToggles","InventoryLevel","ActionSurfaces","TokenManager"],"doc":"./composed__admin.md"},
-  {"id":"composed/ai","title":"Composed · AI","description":"Summary block + classification panel.","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","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/ai-new","title":"Composed · AI (extras)","description":"Confidence dial, prompt suggestions, token usage card, message bubble, tool call, citation, feedback.","layer":"composed","family":"AI","tags":["composed","ai","extras","confidence","dial","prompt"],"sourcePath":"src/components/composed/ai","publicImport":"admin-ui-starter-kit/composed/ai","examples":["AiConfidenceCardExample","AiPromptSuggestionsExample","AiTokenUsageCardExample","AiMessageBubbleExample","AiToolCallExample","AiCitationExample","AiFeedbackExample"],"doc":"./composed__ai-new.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.","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-extras","title":"Composed · Commerce (extras)","description":"Cart, coupon, order status, payment, tax breakdown, subscription, refund, address, voucher.","layer":"composed","family":"Commerce","tags":["composed","commerce","extras","cart","coupon","order"],"sourcePath":"src/components/composed/commerce","publicImport":"admin-ui-starter-kit/composed/commerce","examples":["CartSummaryCardExample","CouponInputCardEmptyApplied","OrderStatusCardExample","PaymentMethodCardExample","TaxBreakdownCardExample","SubscriptionSummaryCardExample","RefundStatusCardExample","AddressCardExample","VoucherEntryCardExample"],"doc":"./composed__commerce-extras.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/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"},
   {"id":"composed/dense-info","title":"Composed · Dense info cards","description":"Five layout variants — dashboard, classification, financial, project, score.","layer":"composed","family":"Data display","tags":["composed","data","display","dense-info-card","dense","info","cards","five"],"sourcePath":"src/components/composed/data-display/dense-info-card","publicImport":"admin-ui-starter-kit/composed/data-display","examples":["Dashboard","ScoreCard","Classification","Financial","ProjectCards"],"doc":"./composed__dense-info.md"},
+  {"id":"composed/empty-state","title":"Empty state","description":"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.","layer":"base","family":"Data display","tags":["base","data","display","empty-state","empty","state","adaptive","zero"],"sourcePath":"src/components/composed/data-display/empty-state","publicImport":"admin-ui-starter-kit/composed/data-display","examples":["Default","NoProductsWithActions","NoTeamMembers","NoSearchResults","InboxZero","PaddingCompact","PaddingBase","PaddingLoose","DashedBorderDropZone","StringsPropLocalisation","RenderPropCustomMedia"],"doc":"./composed__empty-state.md"},
   {"id":"composed/feature-announcement","title":"Composed · Feature announcement","description":"Highlight a new feature with tags and an action.","layer":"composed","family":"Cards","tags":["composed","cards","feature-announcement","feature","announcement","highlight","new"],"sourcePath":"src/components/composed/cards/feature-announcement","publicImport":"admin-ui-starter-kit/composed/cards","examples":["WithIconTagsAction"],"doc":"./composed__feature-announcement.md"},
   {"id":"composed/giftcard-cards","title":"Composed · Giftcard cards","description":"Five visual variants — gradient, compact, minimal, dark, illustrated.","layer":"composed","family":"Cards","tags":["composed","cards","giftcard-card","giftcard","five","visual","variants"],"sourcePath":"src/components/composed/cards/giftcard-card","publicImport":"admin-ui-starter-kit/composed/cards","examples":["GradientDefault","Minimal","Dark","Illustrated","CompactActiveExpired"],"doc":"./composed__giftcard-cards.md"},
   {"id":"composed/gradient-card","title":"Composed · Gradient card","description":"Vivid gradient card with optional pattern, badge, alert, action.","layer":"composed","family":"Cards","tags":["composed","cards","gradient-card","gradient","card","vivid","optional"],"sourcePath":"src/components/composed/cards/gradient-card","publicImport":"admin-ui-starter-kit/composed/cards","examples":["HeroCardWithAction","CompactAllGradients","HeroVariants"],"doc":"./composed__gradient-card.md"},
+  {"id":"composed/inline-stat","title":"Inline stat","description":"Inline label/value pairs for counters, totals, and compact card rows. Use MetadataList for entity detail fields.","layer":"base","family":"Data display","tags":["base","data","display","inline-stat","inline","stat","label","value"],"sourcePath":"src/components/composed/data-display/inline-stat","publicImport":"admin-ui-starter-kit/composed/data-display","examples":["InlineStatLayouts"],"doc":"./composed__inline-stat.md"},
   {"id":"composed/invoice-header","title":"Composed · Invoice header","description":"Top of an invoice — number, status, parties, amount.","layer":"composed","family":"Data display","tags":["composed","data","display","invoice-header","invoice","header","top","number"],"sourcePath":"src/components/composed/data-display/invoice-header","publicImport":"admin-ui-starter-kit/composed/data-display","examples":["Paid","Overdue"],"doc":"./composed__invoice-header.md"},
   {"id":"composed/invoice-items","title":"Composed · Invoice items","description":"Table, compact, detailed layouts with subtotal/tax/discount/total.","layer":"composed","family":"Data display","tags":["composed","data","display","invoice-items","invoice","items","table","compact"],"sourcePath":"src/components/composed/data-display/invoice-items","publicImport":"admin-ui-starter-kit/composed/data-display","examples":["Table","Compact","Detailed"],"doc":"./composed__invoice-items.md"},
   {"id":"composed/invoice-mini","title":"Composed · Invoice mini","description":"Compact invoice tile — paid / pending / overdue.","layer":"composed","family":"Data display","tags":["composed","data","display","invoice-mini","invoice","mini","compact","tile"],"sourcePath":"src/components/composed/data-display/invoice-mini","publicImport":"admin-ui-starter-kit/composed/data-display","examples":["Statuses"],"doc":"./composed__invoice-mini.md"},
   {"id":"composed/invoice-table","title":"Composed · Invoice table","description":"Line items with qty / price / total.","layer":"composed","family":"Data display","tags":["composed","data","display","invoice-table","invoice","table","line","items"],"sourcePath":"src/components/composed/data-display/invoice-table","publicImport":"admin-ui-starter-kit/composed/data-display","examples":["Default","WithTaxRate"],"doc":"./composed__invoice-table.md"},
+  {"id":"composed/metadata-list","title":"Metadata list","description":"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.","layer":"base","family":"Data display","tags":["base","data","display","metadata","list","flexible","label","value"],"sourcePath":"src/components/composed/data-display/metadata","publicImport":"admin-ui-starter-kit/composed/data-display","examples":["APISurface","Vertical2ColumnNoIcons","VerticalSingleColumnNoIcons","RowsTwoColumnWithHairlines","RowsReceiptStyle","RowsWithIconsTooltips","SectionedMultiCard","Dense4ColumnOverview","Vertical3ColumnWithIcons","HorizontalPillSummary","WithTitleSeparator","EmptyStateFallbacksCustomRenderers"],"doc":"./composed__metadata-list.md"},
   {"id":"composed/navigation","title":"Composed · Navigation & boards","description":"Kanban, tab switcher, time ruler, vendor performance, experience activity.","layer":"composed","family":"Navigation","tags":["composed","navigation","boards","kanban","tab","switcher"],"sourcePath":"src/components/composed/navigation","publicImport":"admin-ui-starter-kit/composed/navigation","examples":["KanbanMicroBoardExample","TabSwitcherCardExample","TimeDistributionRulerExample","VendorPerformance","ExperienceActivity"],"doc":"./composed__navigation.md"},
   {"id":"composed/navigation-extras","title":"Composed · Navigation (extras)","description":"BreadcrumbProgress wizard + CategoryNavCard sidebar.","layer":"composed","family":"Navigation","tags":["composed","navigation","extras","breadcrumbprogress","wizard","categorynavcard"],"sourcePath":"src/components/composed/navigation","publicImport":"admin-ui-starter-kit/composed/navigation","examples":["BreadcrumbProgressExample","CategoryNavCardExample"],"doc":"./composed__navigation-extras.md"},
   {"id":"composed/onboarding-checklist","title":"Composed · Onboarding · Checklist","description":"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.","layer":"composed","family":"Onboarding","tags":["composed","onboarding","checklist","step","list","accordion"],"sourcePath":"src/components/composed/onboarding","publicImport":"admin-ui-starter-kit/composed/onboarding","examples":["BorderedDefaultPointOfSaleOnboarding","CardVariantWorkspaceSetupControlled","FlatVariantMinimal"],"doc":"./composed__onboarding-checklist.md"},
   {"id":"composed/resource-selector-card","title":"Composed · Resource selector card","description":"Selected-resource card for dialogs, forms, and show pages. The app owns picking, fetching, and routing.","layer":"composed","family":"Data display","tags":["composed","data","display","resource-selector-card.tsx","resource","selector","card","selected"],"sourcePath":"src/components/composed/data-display/resource-selector-card.tsx","publicImport":"admin-ui-starter-kit/composed/data-display","examples":["SelectedResource","EmptyResource"],"doc":"./composed__resource-selector-card.md"},
   {"id":"composed/timelines","title":"Composed · Timelines","description":"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.","layer":"composed","family":"Timelines","tags":["composed","timelines","read","only","tracking","steps"],"sourcePath":"src/components/composed/timelines","publicImport":"admin-ui-starter-kit/composed/timelines","examples":["StepsVertical","StepsHorizontalExample","OrderTimeline","PaymentTimeline","ActivityStreamReadOnlyTracking","Changelog","Milestones"],"doc":"./composed__timelines.md"},
   {"id":"composed/vendor-profile","title":"Composed · Vendor profile","description":"VendorProfileCard with metrics, stats and actions.","layer":"composed","family":"Cards","tags":["composed","cards","vendor-profile","vendor","profile","vendorprofilecard","metrics"],"sourcePath":"src/components/composed/cards/vendor-profile","publicImport":"admin-ui-starter-kit/composed/cards","examples":["WithEverything","Minimal"],"doc":"./composed__vendor-profile.md"},
+  {"id":"docs/design-system-consistency","title":"Design system consistency guide","description":"The operating manual for keeping the package cohesive: goals, ownership, token rules, drift detection, and browser-quality review.","layer":"docs","family":"Start here","tags":["docs","start","here","preview","design","system","consistency","guide"],"sourcePath":"src/components + src/css + src/preview","publicImport":"","examples":[],"doc":"./docs__design-system-consistency.md"},
+  {"id":"docs/installation","title":"Installation","description":"Install the package, import the stylesheet, and consume exact public subpaths.","layer":"docs","family":"Start here","tags":["docs","start","here","readme.md","installation","install","package","import"],"sourcePath":"README.md","publicImport":"","examples":["InstallCommand","RequiredSteps","ImportRecipe","OptionalPeers","MaintainerChecks","NextLinks"],"doc":"./docs__installation.md"},
+  {"id":"docs/overview","title":"Overview","description":"How the starter kit is organized, how to browse it, and which contracts consumers can rely on.","layer":"docs","family":"Start here","tags":["docs","start","here","registry.tsx","overview","how","starter","kit"],"sourcePath":"src/preview/registry.tsx","publicImport":"","examples":["OverviewSnapshot","LayerMap","NavigationModel","PackageFlow","ArchitectureRule"],"doc":"./docs__overview.md"},
+  {"id":"docs/refinement-guide","title":"Refinement guide","description":"What changed in the showcase, why it matters, and how to keep polishing the package without losing the system contract.","layer":"docs","family":"Start here","tags":["docs","start","here","registry.tsx","refinement","guide","what","changed"],"sourcePath":"src/preview/PreviewApp.tsx + src/preview/registry.tsx","publicImport":"","examples":["RefinementOutcomes","RefinementGoals","ReviewLoop","AcceptanceChecklist","NextPassTargets"],"doc":"./docs__refinement-guide.md"},
+  {"id":"docs/showcase","title":"Showcase","description":"How to use this preview app as the package map, design review surface, and release verification aid.","layer":"docs","family":"Start here","tags":["docs","start","here","preview","showcase","how","app","package"],"sourcePath":"src/preview","publicImport":"","examples":["ShowcaseWorkflow","SearchTargets","RouteShortcuts","InteractionChecks"],"doc":"./docs__showcase.md"},
   {"id":"features/activities","title":"Features · Activity feed","description":"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.","layer":"features","family":"Collaboration","tags":["features","collaboration","activities","activity","feed","interactive","generic"],"sourcePath":"src/components/features/activities","publicImport":"admin-ui-starter-kit/features/activities","examples":["DefaultFeed","CompactFeed","RichFeed","EventConfiguration","CustomRows","ResourceRegistry"],"doc":"./features__activities.md"},
   {"id":"features/ai-chat","title":"AI Chat","description":"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).","layer":"features","family":"AI","tags":["features","ai","ai-chat","chat","framework","agnostic","surface"],"sourcePath":"src/components/features/ai-chat","publicImport":"admin-ui-starter-kit/features/ai-chat","examples":["Counter","Default","Streaming","Empty","WithSlots","Headless"],"doc":"./features__ai-chat.md"},
   {"id":"features/card","title":"Features · Card","description":"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.","layer":"features","family":"Commerce","tags":["features","commerce","card","stateful","feature","cards","booking"],"sourcePath":"src/components/features/card","publicImport":"admin-ui-starter-kit/features/card","examples":["BookingEventCard","SharedResourceSelector","EmptySharedResource"],"doc":"./features__card.md"},
   {"id":"features/comments","title":"Features · Comments","description":"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.","layer":"features","family":"Collaboration","tags":["features","collaboration","comments","generic","framework","agnostic","rich"],"sourcePath":"src/components/features/comments","publicImport":"admin-ui-starter-kit/features/comments","examples":["APISurface","CommentsExample","ReadOnly","EmptyStateCustomStrings","CustomReferenceRendering"],"doc":"./features__comments.md"},
+  {"id":"features/data-view","title":"Features · Data view","description":"Controlled data-view chrome for tables, filters, saved views, and pagination. Consumers own fetching, query state, table data, and persistence.","layer":"features","family":"Tables","tags":["features","tables","data-view","data","view","controlled","chrome"],"sourcePath":"src/components/features/data-view","publicImport":"admin-ui-starter-kit/features/data-view","examples":["CustomerDataView","EmptyCustomerDataView"],"doc":"./features__data-view.md"},
   {"id":"features/enhanced-activities","title":"Features · Enhanced activities","description":"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.","layer":"features","family":"Collaboration","tags":["features","collaboration","activities","enhanced","shopify","style","unified"],"sourcePath":"src/components/features/activities","publicImport":"admin-ui-starter-kit/features/activities","examples":["APISurface","ActivityTimelineComposer","CompactDensity"],"doc":"./features__enhanced-activities.md"},
   {"id":"features/event-log","title":"Features · Event log","description":"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.","layer":"features","family":"Collaboration","tags":["features","collaboration","event-log","event","log","unified","mentions"],"sourcePath":"src/components/features/event-log","publicImport":"admin-ui-starter-kit/features/event-log","examples":["APISurface","CommentsEventsUnderOneLog","ReadOnlyTimelineNoComposer"],"doc":"./features__event-log.md"},
   {"id":"features/filters","title":"Filters","description":"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.","layer":"features","family":"Search & filter","tags":["features","search","filter","filters","composable","system","multi","select"],"sourcePath":"src/components/features/filters","publicImport":"admin-ui-starter-kit/features/filters","examples":["Default","QueryStateHelpers"],"doc":"./features__filters.md"},
@@ -70,6 +78,7 @@
   {"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/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"},
   {"id":"features/suggestions","title":"Features · Suggestions","description":"Framework-agnostic typeahead suggestions with a drop-in combobox and a headless hook. Consumers own fetching, selected-value persistence, telemetry, and result rendering.","layer":"features","family":"Search & filter","tags":["features","search","filter","suggestions","framework","agnostic","typeahead","drop"],"sourcePath":"src/components/features/suggestions","publicImport":"admin-ui-starter-kit/features/suggestions","examples":["AccountSuggestionsCombobox","HeadlessSuggestionsState"],"doc":"./features__suggestions.md"},
@@ -78,10 +87,12 @@
   {"id":"layout/layout-auth","title":"Layout · Auth shell","description":"Framework-neutral auth card and split shells for login, register, invite, reset, magic-link, and verification pages.","layer":"layout","family":"Shells","tags":["layout","shells","auth","shell","framework","neutral","card"],"sourcePath":"src/components/layout/auth","publicImport":"admin-ui-starter-kit/layout/auth","examples":["CenteredCardAuth","LocalizedPatternCardAuth","ProviderMatrixAuth","ResetPasswordAuth","SplitAuthShell","RightSplitAuthShell","FrameworkLinkContract"],"doc":"./layout__layout-auth.md"},
   {"id":"layout/layout-containers","title":"Layout · Containers","description":"Container and Section primitives for page structure, width clamps, padding density, and semantic wrappers.","layer":"layout","family":"Building blocks","tags":["layout","building","blocks","containers","container","section","primitives","page"],"sourcePath":"src/components/layout/containers","publicImport":"admin-ui-starter-kit/layout/containers","examples":["NarrowContainer","WideContainer","BareContainer","SectionRhythm"],"doc":"./layout__layout-containers.md"},
   {"id":"layout/layout-header","title":"Layout · Header","description":"Topbar, breadcrumbs, command search, notifications, and action slots in a realistic app-shell canvas.","layer":"layout","family":"Shells","tags":["layout","shells","header","topbar","breadcrumbs","command"],"sourcePath":"src/components/layout","publicImport":"admin-ui-starter-kit/layout","examples":["AppHeaderComposition","HeaderPartials","HeaderToolPrimitives","CustomNotificationRenderer"],"doc":"./layout__layout-header.md"},
-  {"id":"layout/layout-page","title":"Layout · Page","description":"Page shell, header partials, actions, and content regions with framework-neutral links.","layer":"layout","family":"Shells","tags":["layout","shells","page","shell","header","partials"],"sourcePath":"src/components/layout","publicImport":"admin-ui-starter-kit/layout","examples":["ProductionPageShell","ComposablePartials","ResourceShells","TabbedResourceDetails","SettingsShellExample"],"doc":"./layout__layout-page.md"},
+  {"id":"layout/layout-page","title":"Layout · Page","description":"Page shell, index scaffolds, resource show shells, header partials, actions, and content regions with framework-neutral links.","layer":"layout","family":"Shells","tags":["layout","shells","page","shell","index","scaffolds"],"sourcePath":"src/components/layout","publicImport":"admin-ui-starter-kit/layout","examples":["ProductionPageShell","ComposablePartials","ResourceShells","TabbedResourceDetails","SettingsShellExample"],"doc":"./layout__layout-page.md"},
   {"id":"layout/layout-sidebar","title":"Layout · Sidebar","description":"Full app sidebar assembly plus reusable navigation, workspace, and footer item partials.","layer":"layout","family":"Shells","tags":["layout","shells","sidebar","full","app","assembly"],"sourcePath":"src/components/layout","publicImport":"admin-ui-starter-kit/layout","examples":["AppSidebarShell","NavigationPartials","CustomRowRenderer"],"doc":"./layout__layout-sidebar.md"},
   {"id":"layout/layout-users","title":"Layout · Users & avatars","description":"User identity surfaces used by layout headers, sidebars, menus, avatar groups, and status badges.","layer":"layout","family":"Building blocks","tags":["layout","building","blocks","users","avatars","user","identity"],"sourcePath":"src/components/layout","publicImport":"admin-ui-starter-kit/layout","examples":["AvatarStates","HeaderUserMenuExample","SidebarUserMenu","CustomTriggerCustomContent"],"doc":"./layout__layout-users.md"},
   {"id":"layout/layout-workspace","title":"Layout · Workspace","description":"Nested record workspace shell with header, workflow navigation, scroll-owned body, and optional right rail.","layer":"layout","family":"Shells","tags":["layout","shells","workspace","nested","record","shell","header"],"sourcePath":"src/components/layout/workspace","publicImport":"admin-ui-starter-kit/layout/workspace","examples":["ProductRecordWorkspaceShell","WorkspaceWithoutRail"],"doc":"./layout__layout-workspace.md"},
+  {"id":"services/actions","title":"Actions service","description":"Framework-neutral action registry, lifecycle, overlay, request, guard, and feedback glue for shared admin actions.","layer":"services","family":"Runtime","tags":["services","runtime","actions","service","framework","neutral","action"],"sourcePath":"src/services/actions","publicImport":"admin-ui-starter-kit/services/actions","examples":["RuntimeMap","LifecycleFlow","RuntimeGlue","SurfaceHelpers","FormsAndState","FitChecklist","NextRoutes"],"doc":"./services__actions.md"},
+  {"id":"services/hooks","title":"Hooks reference","description":"Public hook import boundaries for provider defaults, layout helpers, action lifecycle, and feature headless state.","layer":"services","family":"Hooks","tags":["services","hooks","reference","public","hook","import"],"sourcePath":"src/lib/ui-provider, src/components/layout/hooks, src/services/actions, src/components/features/*/hooks","publicImport":"","examples":["HookImportMatrix","HookRules","FeatureHookList","InternalHooksNotice","HookRouteShortcuts"],"doc":"./services__hooks.md"},
   {"id":"ui/alert","title":"UI · Alert","description":"shadcn alert primitive: variants, with title/description/action.","layer":"ui","family":"Feedback","tags":["ui","feedback","alert","shadcn","primitive","variants","title"],"sourcePath":"src/components/ui/alert","publicImport":"","examples":["Variants","WithAlertAction","TitleOnly"],"doc":"./ui__alert.md"},
   {"id":"ui/avatar","title":"UI · Avatar","description":"Avatar with fallback, image, sizes, group, badge.","layer":"ui","family":"Data display","tags":["ui","data","display","avatar","fallback","image","sizes","group"],"sourcePath":"src/components/ui/avatar","publicImport":"","examples":["Sizes","WithImageFallback","WithBadge","Group"],"doc":"./ui__avatar.md"},
   {"id":"ui/breadcrumb","title":"UI · Breadcrumb","description":"shadcn breadcrumb — list, items, separator (default & custom).","layer":"ui","family":"Navigation","tags":["ui","navigation","breadcrumb","shadcn","list","items","separator"],"sourcePath":"src/components/ui/breadcrumb","publicImport":"","examples":["Default","CustomSeparator"],"doc":"./ui__breadcrumb.md"},

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,23 +39,24 @@ 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.
@@ -62,12 +64,21 @@ Agents: prefer `INDEX.json` (structured) for discovery; this file is for humans.
 - [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.
@@ -86,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.
@@ -97,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`
+