admin-ui-starter-kit 0.1.0

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

@@ -0,0 +1,94 @@
+[
+  {"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","examples":["Default","VariantCard","VariantBordered","VariantFlat","IconStyleMedallion","IconStyleInline","IconStyleNone","MultipleOpen","WithBadgeAndDisabled","CompoundApi","RealisticFAQ"],"doc":"./base__accordion.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","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","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","examples":["Default","WithIconTooltipFooter","WithActions","AlertVariants","PaddingSizes","SurfaceVariants","HeaderSlots","HeaderAndFooterDividers","ExpandableUncontrolled","ExpandableCustomLabels","Skeleton","MetricKPICard","NotificationCard","PrimitiveComposition","StatRowClickable"],"doc":"./base__cards.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","examples":["Default","SingleSelect","SingleHighlightMatch","SingleCreatable","MultipleSelect","MultipleApplyButton","MultipleCloseOnSelect","MultipleGrouped","GroupedTeamByRole","AsyncCustomers","AsyncDebouncedSearch","AsyncWithLoadMore","CustomItemRendering","CustomGroupLabels","SizeSm","SizeMd","SizeLg","Disabled","Invalid","MinSearchLength","RealisticCustomerPicker"],"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","examples":["Default","Mono","MonoTruncate","CustomDisplayValue","CustomToastMessage","RealisticOrderRow","CustomerListWithCopyableEmails"],"doc":"./base__copyable.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","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","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","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","examples":["Default","NoProductsWithActions","NoTeamMembers","NoSearchResults","InboxZero","PaddingCompact","PaddingBase","PaddingLoose","DashedBorderDropZone","StringsPropLocalisation","RenderPropCustomMedia"],"doc":"./base__empty-state.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","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","examples":["BasicField","WithError","WithHelperText","InputBasic","InputWithIcons","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/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","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","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":"Data display","tags":["base","data","display","metadata","list","flexible","label","value"],"sourcePath":"src/components/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","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":"Feedback","tags":["base","feedback","spinner","loading","indicator","visual","variants"],"sourcePath":"src/components/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","examples":["BasicDefaultSizeXsCompact","SizeSm","SizeBase","SurfaceGlassHeaderTransparentCleanOutlineNoMutedHeader","SurfaceFlatInsideSmartCardTableRendersNoChrome","SizeSmGlassExplicitCellTextScaling","WithSortingRowActions","PaginationExample","RealisticOrdersTable","CellRenderers","WithRowSelection","WithColumnVisibility","WithCustomToolbar","StickyHeaderAndFirstColumn","EmptyState"],"doc":"./base__table.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","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","examples":["Default","EmptyDropzoneOnly","MixedItemStates","LiveSimulatedUpload","LocalisedFrench"],"doc":"./base__upload-tray.md"},
+  {"id":"common/brand","title":"Common · Brand","description":"Logo + AppLogo (sized variants). Source images expected at /assets/media/gct-logo[-light].png.","layer":"common","family":"Branding","tags":["common","branding","_brand","brand","logo","applogo","sized"],"sourcePath":"src/preview/_brand","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","examples":["TeamMembers","RolePermissions","RecentConversations","SettingsToggles","InventoryLevel"],"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","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","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","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","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","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","examples":["CartSummaryCardExample","CouponInputCardEmptyApplied","OrderStatusCardExample","PaymentMethodCardExample","TaxBreakdownCardExample","SubscriptionSummaryCardExample","RefundStatusCardExample","AddressCardExample","VoucherEntryCardExample"],"doc":"./composed__commerce-extras.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","examples":["WithAllFields","WithInitialsOnly","Minimal","DifferentBadgeVariants"],"doc":"./composed__contact-card.md"},
+  {"id":"composed/course-card","title":"Composed · Course card","description":"Group experience with participants & progress.","layer":"composed","family":"Cards","tags":["composed","cards","course-card","course","card","group","experience"],"sourcePath":"src/components/composed/cards/course-card","examples":["DefaultWithEverything","GradientVioletFuchsiaPinkDefault","GradientCustomCyanEmerald","GradientCustomAmberRose","Minimal"],"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","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","examples":["Dashboard","ScoreCard","Classification","Financial","ProjectCards"],"doc":"./composed__dense-info.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","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","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","examples":["HeroCardWithAction","CompactAllGradients","HeroVariants"],"doc":"./composed__gradient-card.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","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","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","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","examples":["Default","WithTaxRate"],"doc":"./composed__invoice-table.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","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","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","examples":["BorderedDefaultPointOfSaleOnboarding","CardVariantWorkspaceSetupControlled","FlatVariantMinimal"],"doc":"./composed__onboarding-checklist.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","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","examples":["WithEverything","Minimal"],"doc":"./composed__vendor-profile.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","examples":["DefaultDensityHeadlineSegmentsGrouping","CompactDensitySingleLineDotFeed","RichDensityChangesMetadataActions","MassEventConfigurationCustomStringsTones","CustomRowRenderingSlotsRenderRow","ResourceRegistrySaveRestoreTaggingBadgingLinking"],"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","examples":["Counter","Default","Streaming","Empty","WithSlots","Headless"],"doc":"./features__ai-chat.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","examples":["APISurface","CommentsExample","ReadOnly","EmptyStateCustomStrings","CustomReferenceRendering"],"doc":"./features__comments.md"},
+  {"id":"features/enhanced-activities","title":"Features · Enhanced activities","description":"","layer":"","family":"Collaboration","tags":["collaboration","features","enhanced","activities"],"sourcePath":"src/components/features","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","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","examples":["Default"],"doc":"./features__filters.md"},
+  {"id":"features/global-search","title":"GlobalSearch","description":"Async search palette with slots, render-props, and a headless useGlobalSearch hook.","layer":"features","family":"Search & filter","tags":["features","search","filter","global-search","globalsearch","async","palette","slots"],"sourcePath":"src/components/features/global-search","examples":["Default"],"doc":"./features__global-search.md"},
+  {"id":"features/kanban","title":"Features · Kanban","description":"Drag-and-drop board, generic in T. Pass `itemActions` (static array or per-item factory) for the ⋮ menu, `onItemClick` for whole-card click. Headless via `useKanban`; slots: KanbanBoard / KanbanColumn / KanbanColumnContent / KanbanItem / KanbanItemHandle / KanbanItemActions / KanbanOverlay.","layer":"features","family":"Boards","tags":["features","boards","kanban","drag","drop","board","generic"],"sourcePath":"src/components/features/kanban","examples":["RoadmapBoardWithActionsOnItemClick"],"doc":"./features__kanban.md"},
+  {"id":"features/metrics-analytics-bar","title":"Features · Metrics · Analytics bar","description":"`MetricBar` — horizontal KPI strip with hairline-divided cells. Pair with `MetricGrid` for card-style layouts.","layer":"features","family":"Metrics","tags":["features","metrics","analytics","bar","metricbar","horizontal","kpi"],"sourcePath":"src/components/composed/analytics","examples":["MetricBarDefault","MetricBarGradientFrame","MetricGridCompactCardsAlternative"],"doc":"./features__metrics-analytics-bar.md"},
+  {"id":"features/metrics-analytics-cards","title":"Features · Metrics · Analytics cards","description":"`MetricGradient` — vivid gradient hero card with embedded area chart. Pick a `theme` to drive the colour palette.","layer":"features","family":"Metrics","tags":["features","metrics","analytics","cards","metricgradient","vivid","gradient"],"sourcePath":"src/components/composed/analytics","examples":["FourThemes"],"doc":"./features__metrics-analytics-cards.md"},
+  {"id":"features/metrics-comparison","title":"Features · Metrics · Comparison","description":"`MetricComparison` — side-by-side current vs previous with a tone-tinted delta box. Reuses the unified `MetricData` shape so currency/percent formatting carries through.","layer":"features","family":"Metrics","tags":["features","metrics","analytics","comparison","metriccomparison","side","current"],"sourcePath":"src/components/composed/analytics","examples":["Default","WithCurrencyOverrideEUR","PercentageValues","FlatNoChange"],"doc":"./features__metrics-comparison.md"},
+  {"id":"features/metrics-heatmap","title":"Features · Metrics · Activity heatmap","description":"`ActivityHeatmap` — GitHub-style daily-activity calendar with success-tinted intensity cells.","layer":"features","family":"Metrics","tags":["features","metrics","analytics","activity","heatmap","activityheatmap","github"],"sourcePath":"src/components/composed/analytics","examples":["OrderActivity"],"doc":"./features__metrics-heatmap.md"},
+  {"id":"features/metrics-inline-badge","title":"Features · Metrics · Inline badge","description":"`InlineMetricBadge` — compact `label · value · change%` pill rows. Use as in-flow copy where a full Metric tile is too heavy.","layer":"features","family":"Metrics","tags":["features","metrics","inline-metric","inline","badge","inlinemetricbadge","compact"],"sourcePath":"src/components/composed/data-display/inline-metric","examples":["MixedSizesDirections"],"doc":"./features__metrics-inline-badge.md"},
+  {"id":"features/metrics-kpi-row","title":"Features · Metrics · KPI row","description":"`MiniKpiRow` — compact horizontal divider-separated KPI strip for header / footer accents.","layer":"features","family":"Metrics","tags":["features","metrics","mini-kpi","kpi","row","minikpirow","compact"],"sourcePath":"src/components/composed/data-display/mini-kpi","examples":["Example4KPIs","Example3KPIs"],"doc":"./features__metrics-kpi-row.md"},
+  {"id":"features/metrics-micro-grid","title":"Features · Metrics · Micro chart grid","description":"`MetricMicroGrid` — six-cell dense overview pairing each KPI with a different lightweight visualization (bars / line / dots / progress / area / pie).","layer":"features","family":"Metrics","tags":["features","metrics","analytics","micro","chart","grid","metricmicrogrid"],"sourcePath":"src/components/composed/analytics","examples":["DefaultAutoAssignedCharts","PinnedChartKinds"],"doc":"./features__metrics-micro-grid.md"},
+  {"id":"features/metrics-overview","title":"Features · Metrics · Overview","description":"The unified metrics module: a single Metric component with seven layout variants, plus MetricBar, MetricGrid, and supporting atoms (TrendChip, Sparkline, Skeleton). One MetricData shape powers every surface — see the dedicated pages for each layout.","layer":"features","family":"Metrics","tags":["features","metrics","analytics","overview","unified","module","single"],"sourcePath":"src/components/composed/analytics","examples":["MetricBarDefault","MetricBarGradientFrame","MetricGridCardVariant","MetricGridCompactList","MetricSizesSmMdLg","MetricMinimalInlineCopy","MetricTrendChipExample","MetricSparklineExample","LoadingSkeletons","LiveLoadingState","ErrorState"],"doc":"./features__metrics-overview.md"},
+  {"id":"features/metrics-stat-cards","title":"Features · Metrics · Stat cards","description":"Two stat tile flavors built from the unified `Metric` component — `accent` (dark surface + sparkline) and `colored` (segmented progress bar).","layer":"features","family":"Metrics","tags":["features","metrics","analytics","stat","cards","tile","flavors"],"sourcePath":"src/components/composed/analytics","examples":["MetricAccent","MetricColored"],"doc":"./features__metrics-stat-cards.md"},
+  {"id":"features/overlays","title":"Features · Overlays","description":"","layer":"","family":"Overlays","tags":["overlays","features"],"sourcePath":"src/components/features/overlays","examples":["APISurface","DialogDefault","DialogEmphasisTones","DialogRichContent","DialogFormPattern","Drawer4Directions","AlertDialogConfirmationPatterns","BestPractices"],"doc":"./features__overlays.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","examples":["ProductionWiring","Default","CompactSmallerInlineNote","EmptyPlaceholder","Disabled","StringsOverride"],"doc":"./features__rich-text-editor.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","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","examples":["AppHeaderComposition","HeaderPartials","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","actions"],"sourcePath":"src/components/layout/page","examples":["ProductionPageShell","ComposablePartials"],"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","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","examples":["AvatarStates","HeaderUserMenuExample","SidebarUserMenu","CustomTriggerCustomContent"],"doc":"./layout__layout-users.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","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","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","examples":["Default","CustomSeparator"],"doc":"./ui__breadcrumb.md"},
+  {"id":"ui/button","title":"UI · Button","description":"shadcn primitive button — variants, sizes, button group.","layer":"ui","family":"Forms","tags":["ui","forms","button","shadcn","primitive","variants","sizes"],"sourcePath":"src/components/ui/button","examples":["Variants","Sizes","ButtonGroupExample"],"doc":"./ui__button.md"},
+  {"id":"ui/calendar","title":"UI · Calendar","description":"react-day-picker styled with shadcn primitives.","layer":"ui","family":"Forms","tags":["ui","forms","calendar","react","day","picker","styled"],"sourcePath":"src/components/ui/calendar","examples":["Single"],"doc":"./ui__calendar.md"},
+  {"id":"ui/collapsible","title":"UI · Collapsible","description":"Headless show/hide region.","layer":"ui","family":"Layout","tags":["ui","layout","collapsible","headless","show","hide","region"],"sourcePath":"src/components/ui/collapsible","examples":["Default"],"doc":"./ui__collapsible.md"},
+  {"id":"ui/empty-item","title":"UI · Empty + Item","description":"Empty state and Item list-row primitives.","layer":"ui","family":"Data display","tags":["ui","data","display","empty","item","state","list"],"sourcePath":"src/components/ui","examples":["EmptyState","ItemsList"],"doc":"./ui__empty-item.md"},
+  {"id":"ui/input-group","title":"UI · Input group","description":"Input with leading / trailing add-ons.","layer":"ui","family":"Forms","tags":["ui","forms","input-group","input","group","leading","trailing"],"sourcePath":"src/components/ui/input-group","examples":["LeadingIcon","TrailingAddon","StackedEmailPassword"],"doc":"./ui__input-group.md"},
+  {"id":"ui/inputs","title":"UI · Inputs","description":"Input, Textarea, Select primitives.","layer":"ui","family":"Forms","tags":["ui","forms","inputs","input","textarea","select"],"sourcePath":"src/components/ui","examples":["InputExample","TextareaExample","SelectExample"],"doc":"./ui__inputs.md"},
+  {"id":"ui/menus","title":"UI · Menus","description":"DropdownMenu, ContextMenu, Command palette.","layer":"ui","family":"Overlays","tags":["ui","overlays","menus","dropdownmenu","contextmenu","command"],"sourcePath":"src/components/ui","examples":["DropdownMenuExample","ContextMenuRightClick","CommandPalette"],"doc":"./ui__menus.md"},
+  {"id":"ui/overlays","title":"UI · Overlays","description":"Dialog, Sheet, Popover, Tooltip, HoverCard.","layer":"ui","family":"Overlays","tags":["ui","overlays","dialog","sheet","popover","tooltip"],"sourcePath":"src/components/ui","examples":["DialogExample","SheetExample","PopoverExample","TooltipExample","HoverCardExample"],"doc":"./ui__overlays.md"},
+  {"id":"ui/pagination","title":"UI · Pagination","description":"Manual composition of pagination controls.","layer":"ui","family":"Navigation","tags":["ui","navigation","pagination","manual","composition","controls"],"sourcePath":"src/components/ui/pagination","examples":["Default"],"doc":"./ui__pagination.md"},
+  {"id":"ui/progress","title":"UI · Progress","description":"Linear progress bar at varying values.","layer":"ui","family":"Data display","tags":["ui","data","display","progress","linear","bar","varying","values"],"sourcePath":"src/components/ui/progress","examples":["Values"],"doc":"./ui__progress.md"},
+  {"id":"ui/scroll-area","title":"UI · Scroll area","description":"Custom-styled scroll viewport.","layer":"ui","family":"Layout","tags":["ui","layout","scroll-area","scroll","area","custom","styled"],"sourcePath":"src/components/ui/scroll-area","examples":["Vertical","Horizontal"],"doc":"./ui__scroll-area.md"},
+  {"id":"ui/separator","title":"UI · Separator","description":"Horizontal & vertical dividers.","layer":"ui","family":"Layout","tags":["ui","layout","separator","horizontal","vertical","dividers"],"sourcePath":"src/components/ui/separator","examples":["Horizontal","Vertical"],"doc":"./ui__separator.md"},
+  {"id":"ui/skeleton","title":"UI · Skeleton","description":"Animated loading placeholders.","layer":"ui","family":"Data display","tags":["ui","data","display","skeleton","animated","loading","placeholders"],"sourcePath":"src/components/ui/skeleton","examples":["Lines","CardPlaceholder"],"doc":"./ui__skeleton.md"},
+  {"id":"ui/sonner","title":"UI · Sonner toaster","description":"Toast notifications.","layer":"ui","family":"Feedback","tags":["ui","feedback","button","sonner","toaster","toast","notifications"],"sourcePath":"src/components/ui/button","examples":["TriggerToasts"],"doc":"./ui__sonner.md"},
+  {"id":"ui/spinner","title":"UI · Spinner","description":"Loading spinner — sized via className.","layer":"ui","family":"Data display","tags":["ui","data","display","spinner","loading","sized","classname"],"sourcePath":"src/components/ui/spinner","examples":["Sizes","ColorViaClassName"],"doc":"./ui__spinner.md"},
+  {"id":"ui/tabs","title":"UI · Tabs","description":"Tab list with content panels.","layer":"ui","family":"Navigation","tags":["ui","navigation","tabs","tab","list","content","panels"],"sourcePath":"src/components/ui/tabs","examples":["Default"],"doc":"./ui__tabs.md"},
+  {"id":"ui/toggles","title":"UI · Toggles","description":"Checkbox, Switch, RadioGroup, Slider primitives.","layer":"ui","family":"Forms","tags":["ui","forms","toggles","checkbox","switch","radiogroup"],"sourcePath":"src/components/ui","examples":["CheckboxExample","SwitchExample","RadioGroupExample","SliderExample"],"doc":"./ui__toggles.md"},
+  {"id":"ui/toggles-group","title":"UI · Toggle + ToggleGroup","description":"Single toggle + radio/multiple group.","layer":"ui","family":"Forms","tags":["ui","forms","toggle","togglegroup","single","radio"],"sourcePath":"src/components/ui","examples":["SingleToggle","MultipleSelectGroup"],"doc":"./ui__toggles-group.md"},
+  {"id":"ui/ui-badge","title":"UI · Badge","description":"shadcn badge primitive (no theming wrapper).","layer":"ui","family":"Data display","tags":["ui","data","display","badge","shadcn","primitive","theming","wrapper"],"sourcePath":"src/components/ui/badge","examples":["Variants","InContext"],"doc":"./ui__ui-badge.md"},
+  {"id":"ui/ui-card","title":"UI · Card","description":"shadcn primitive card with header / title / description / content / footer.","layer":"ui","family":"Layout","tags":["ui","layout","card","shadcn","primitive","header","title"],"sourcePath":"src/components/ui/card","examples":["Default","CompactSizeSm"],"doc":"./ui__ui-card.md"},
+  {"id":"ui/ui-table","title":"UI · Table","description":"shadcn table primitive (no data layer).","layer":"ui","family":"Data display","tags":["ui","data","display","table","shadcn","primitive","layer"],"sourcePath":"src/components/ui/table","examples":["Default"],"doc":"./ui__ui-table.md"}
+]

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

@@ -0,0 +1,116 @@
+# Component reference index
+
+Auto-generated. Do not edit by hand — run `npm run docs:sync-skill`.
+
+Agents: prefer `INDEX.json` (structured) for discovery; this file is for humans.
+
+## base
+
+- [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.
+- [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.
+- [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.
+- [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.
+- [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.
+- [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.
+- [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.
+
+## common
+
+- [Common · Brand](./common__brand.md) — Logo + AppLogo (sized variants). Source images expected at /assets/media/gct-logo[-light].png.
+
+## composed
+
+- [Composed · Admin](./composed__admin.md) — Team list, permissions, conversations, settings, inventory.
+- [Composed · AI](./composed__ai.md) — Summary block + classification panel.
+- [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 · Contact card](./composed__contact-card.md) — ContactCard — name, role, email, phone, location, badge.
+- [Composed · Course card](./composed__course-card.md) — Group experience with participants & progress.
+- [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.
+- [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.
+- [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.
+- [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 · 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.
+
+## 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 · 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 · Enhanced activities](./features__enhanced-activities.md) — 
+- [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.
+- [GlobalSearch](./features__global-search.md) — Async search palette with slots, render-props, and a headless useGlobalSearch hook.
+- [Features · Kanban](./features__kanban.md) — Drag-and-drop board, generic in T. Pass `itemActions` (static array or per-item factory) for the ⋮ menu, `onItemClick` for whole-card click. Headless via `useKanban`; slots: KanbanBoard / KanbanColumn / KanbanColumnContent / KanbanItem / KanbanItemHandle / KanbanItemActions / KanbanOverlay.
+- [Features · Metrics · Analytics bar](./features__metrics-analytics-bar.md) — `MetricBar` — horizontal KPI strip with hairline-divided cells. Pair with `MetricGrid` for card-style layouts.
+- [Features · Metrics · Analytics cards](./features__metrics-analytics-cards.md) — `MetricGradient` — vivid gradient hero card with embedded area chart. Pick a `theme` to drive the colour palette.
+- [Features · Metrics · Comparison](./features__metrics-comparison.md) — `MetricComparison` — side-by-side current vs previous with a tone-tinted delta box. Reuses the unified `MetricData` shape so currency/percent formatting carries through.
+- [Features · Metrics · Activity heatmap](./features__metrics-heatmap.md) — `ActivityHeatmap` — GitHub-style daily-activity calendar with success-tinted intensity cells.
+- [Features · Metrics · Inline badge](./features__metrics-inline-badge.md) — `InlineMetricBadge` — compact `label · value · change%` pill rows. Use as in-flow copy where a full Metric tile is too heavy.
+- [Features · Metrics · KPI row](./features__metrics-kpi-row.md) — `MiniKpiRow` — compact horizontal divider-separated KPI strip for header / footer accents.
+- [Features · Metrics · Micro chart grid](./features__metrics-micro-grid.md) — `MetricMicroGrid` — six-cell dense overview pairing each KPI with a different lightweight visualization (bars / line / dots / progress / area / pie).
+- [Features · Metrics · Overview](./features__metrics-overview.md) — The unified metrics module: a single Metric component with seven layout variants, plus MetricBar, MetricGrid, and supporting atoms (TrendChip, Sparkline, Skeleton). One MetricData shape powers every surface — see the dedicated pages for each layout.
+- [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) — 
+- [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.
+
+## layout
+
+- [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 · 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.
+
+## ui
+
+- [UI · Alert](./ui__alert.md) — shadcn alert primitive: variants, with title/description/action.
+- [UI · Avatar](./ui__avatar.md) — Avatar with fallback, image, sizes, group, badge.
+- [UI · Breadcrumb](./ui__breadcrumb.md) — shadcn breadcrumb — list, items, separator (default & custom).
+- [UI · Button](./ui__button.md) — shadcn primitive button — variants, sizes, button group.
+- [UI · Calendar](./ui__calendar.md) — react-day-picker styled with shadcn primitives.
+- [UI · Collapsible](./ui__collapsible.md) — Headless show/hide region.
+- [UI · Empty + Item](./ui__empty-item.md) — Empty state and Item list-row primitives.
+- [UI · Input group](./ui__input-group.md) — Input with leading / trailing add-ons.
+- [UI · Inputs](./ui__inputs.md) — Input, Textarea, Select primitives.
+- [UI · Menus](./ui__menus.md) — DropdownMenu, ContextMenu, Command palette.
+- [UI · Overlays](./ui__overlays.md) — Dialog, Sheet, Popover, Tooltip, HoverCard.
+- [UI · Pagination](./ui__pagination.md) — Manual composition of pagination controls.
+- [UI · Progress](./ui__progress.md) — Linear progress bar at varying values.
+- [UI · Scroll area](./ui__scroll-area.md) — Custom-styled scroll viewport.
+- [UI · Separator](./ui__separator.md) — Horizontal & vertical dividers.
+- [UI · Skeleton](./ui__skeleton.md) — Animated loading placeholders.
+- [UI · Sonner toaster](./ui__sonner.md) — Toast notifications.
+- [UI · Spinner](./ui__spinner.md) — Loading spinner — sized via className.
+- [UI · Tabs](./ui__tabs.md) — Tab list with content panels.
+- [UI · Toggles](./ui__toggles.md) — Checkbox, Switch, RadioGroup, Slider primitives.
+- [UI · Toggle + ToggleGroup](./ui__toggles-group.md) — Single toggle + radio/multiple group.
+- [UI · Badge](./ui__ui-badge.md) — shadcn badge primitive (no theming wrapper).
+- [UI · Card](./ui__ui-card.md) — shadcn primitive card with header / title / description / content / footer.
+- [UI · Table](./ui__ui-table.md) — shadcn table primitive (no data layer).
+

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

@@ -0,0 +1,9 @@
+# Component reference
+
+This directory is generated from the MDX showcase pages under
+`src/preview/pages/`. AI agents using the `component-library-rules`
+skill should read `INDEX.md` to find the canonical usage example for
+each component.
+
+To regenerate: `npm run docs:sync-skill`
+To verify freshness in CI: `npm run docs:sync-skill -- --check`

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

@@ -0,0 +1,229 @@
+---
+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"
+sourcePath: src/components/base/accordion
+examples:
+  - Default
+  - VariantCard
+  - VariantBordered
+  - VariantFlat
+  - IconStyleMedallion
+  - IconStyleInline
+  - IconStyleNone
+  - MultipleOpen
+  - WithBadgeAndDisabled
+  - CompoundApi
+  - RealisticFAQ
+imports:
+  - @/components/base/accordion
+  - @/components/base/badge
+  - @/components/base/cards
+  - @/components/typography/text
+tags:
+  - base
+  - display
+  - accordion
+  - tiers
+  - pass
+  - through
+  - compound
+---
+
+# Accordion
+
+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`  
+**Source:** `src/components/base/accordion`
+
+## Examples
+
+```tsx
+import { Bell, CreditCard, HelpCircle, Lock, Settings, Sparkles } from 'lucide-react';
+import { Accordion, AccordionContent, AccordionItem, AccordionTrigger, SmartAccordion } from '@/components/base/accordion';
+import { Badge } from '@/components/base/badge';
+import { SmartCard } from '@/components/base/cards';
+import { Text } from '@/components/typography/text';
+
+const settingsItems = [
+	{
+		value: 'account',
+		icon: <Settings className="size-4" />,
+		title: 'Account settings',
+		badge: <Badge variant="primary">New</Badge>,
+		content:
+			'Manage your account preferences, security settings, and personal information. You can also configure two-factor authentication here.',
+	},
+	{
+		value: 'privacy',
+		icon: <Lock className="size-4" />,
+		title: 'Privacy & security',
+		content:
+			'Control who can see your profile and what data we collect. View our latest security audits and transparency reports.',
+	},
+	{
+		value: 'notifications',
+		icon: <Bell className="size-4" />,
+		title: 'Notifications',
+		badge: <Badge variant="secondary">3</Badge>,
+		content:
+			'Choose which events trigger an email or push notification. Granular per-channel control.',
+	},
+	{
+		value: 'billing',
+		icon: <CreditCard className="size-4" />,
+		title: 'Billing',
+		content: 'Update your payment method, download invoices, and manage seats.',
+		disabled: true,
+	},
+	{
+		value: 'support',
+		icon: <HelpCircle className="size-4" />,
+		title: 'Help & support',
+		content: 'Access our help center, community forums, and contact support 24/7.',
+	},
+];
+
+const faqItems = [
+	{ value: 'a', title: 'What is included in the plan?', content: 'Everything in the free tier plus team seats, audit log, and custom roles.' },
+	{ value: 'b', title: 'Can I switch plans later?', content: 'Yes — upgrades take effect immediately, downgrades at the next billing cycle.' },
+	{ value: 'c', title: 'Do you offer discounts for non-profits?', content: 'We do — drop a note to billing with proof of status.' },
+];
+
+export function Default() {
+	return (
+		<div className="w-full max-w-xl">
+			<SmartAccordion items={settingsItems.slice(0, 3)} defaultValue={['account']} />
+		</div>
+	);
+}
+
+export function VariantCard() {
+	return (
+		<div className="w-full max-w-xl">
+			<SmartAccordion items={settingsItems.slice(0, 3)} variant="card" defaultValue={['account']} />
+		</div>
+	);
+}
+
+export function VariantBordered() {
+	return (
+		<div className="w-full max-w-xl">
+			<SmartAccordion items={settingsItems.slice(0, 3)} variant="bordered" defaultValue={['privacy']} />
+		</div>
+	);
+}
+
+export function VariantFlat() {
+	return (
+		<SmartCard padding="sm" className="w-full max-w-xl">
+			<SmartAccordion items={faqItems} variant="flat" iconStyle="none" defaultValue={['a']} />
+		</SmartCard>
+	);
+}
+
+export function IconStyleMedallion() {
+	return (
+		<div className="w-full max-w-xl">
+			<SmartAccordion items={settingsItems.slice(0, 3)} iconStyle="medallion" defaultValue={['account']} />
+		</div>
+	);
+}
+
+export function IconStyleInline() {
+	return (
+		<div className="w-full max-w-xl">
+			<SmartAccordion items={settingsItems.slice(0, 3)} iconStyle="inline" defaultValue={['account']} />
+		</div>
+	);
+}
+
+export function IconStyleNone() {
+	return (
+		<div className="w-full max-w-xl">
+			<SmartAccordion items={faqItems} iconStyle="none" defaultValue={['a']} />
+		</div>
+	);
+}
+
+export function MultipleOpen() {
+	return (
+		<div className="w-full max-w-xl">
+			<SmartAccordion items={settingsItems.slice(0, 3)} multiple defaultValue={['account', 'privacy']} />
+		</div>
+	);
+}
+
+export function WithBadgeAndDisabled() {
+	return (
+		<div className="w-full max-w-xl">
+			<SmartAccordion items={settingsItems} defaultValue={['account']} />
+		</div>
+	);
+}
+
+export function CompoundApi() {
+	return (
+		<div className="w-full max-w-xl">
+			<Accordion defaultValue={['custom']}>
+				<AccordionItem value="custom" className="rounded-md border bg-card mb-2">
+					<AccordionTrigger className="px-4 py-3">
+						<div className="flex items-center gap-2">
+							<Sparkles className="size-4 text-primary" />
+							<span className="font-semibold">Custom row layout</span>
+							<Badge variant="warning">Beta</Badge>
+						</div>
+					</AccordionTrigger>
+					<AccordionContent className="px-4 pb-4">
+						<Text type="secondary">
+							Drop down to the compound API when you need more than icon + title +
+							body — e.g. multi-line meta, action rows, or custom indicators.
+						</Text>
+					</AccordionContent>
+				</AccordionItem>
+				<AccordionItem value="another" className="rounded-md border bg-card">
+					<AccordionTrigger className="px-4 py-3">
+						<div className="flex w-full items-center justify-between">
+							<span className="font-semibold">Two-line trigger</span>
+							<Text size="xs" type="secondary">Updated 2h ago</Text>
+						</div>
+					</AccordionTrigger>
+					<AccordionContent className="px-4 pb-4">
+						<Text type="secondary">Body content for the second item.</Text>
+					</AccordionContent>
+				</AccordionItem>
+			</Accordion>
+		</div>
+	);
+}
+
+export function RealisticFAQ() {
+	return (
+		<div className="w-full max-w-xl space-y-4">
+			<div>
+				<h3 className="text-base font-semibold">Frequently asked questions</h3>
+				<p className="text-sm text-muted-foreground">Everything you need to know before signing up.</p>
+			</div>
+			<SmartAccordion items={faqItems} variant="bordered" iconStyle="none" />
+		</div>
+	);
+}
+```
+
+## Example exports
+
+- `Default`
+- `VariantCard`
+- `VariantBordered`
+- `VariantFlat`
+- `IconStyleMedallion`
+- `IconStyleInline`
+- `IconStyleNone`
+- `MultipleOpen`
+- `WithBadgeAndDisabled`
+- `CompoundApi`
+- `RealisticFAQ`
+