admin-ui-starter-kit 0.1.4 → 0.4.2

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

@@ -7,9 +7,12 @@ 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.
+- [Alert](./base__alert.md) — Semantic notice primitive with icon, title, description, and responsive action regions.
 - [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.
+- [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.
 - [Currency](./base__currency.md) — MoneyDisplay and CurrencyPairPreview — locale-aware, dual-pricing-aware money rendering driven by useCurrency() / UIProvider config.
@@ -18,6 +21,7 @@ Agents: prefer `INDEX.json` (structured) for discovery; this file is for humans.
 - [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.
+- [Frame](./base__frame.md) — Grouped panel primitive for related admin content, stacked records, and dense framed surfaces.
 - [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.
@@ -29,7 +33,7 @@ Agents: prefer `INDEX.json` (structured) for discovery; this file is for humans.
 
 ## common
 
-- [Common · Brand](./common__brand.md) — Logo + AppLogo (sized variants). Source images expected at /assets/media/gct-logo[-light].png.
+- [Common · Brand](./common__brand.md) — Inline Logo + AppLogo variants used by the preview shell.
 
 ## composed
 
@@ -41,7 +45,7 @@ Agents: prefer `INDEX.json` (structured) for discovery; this file is for humans.
 - [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 · 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.
 - [Composed · Feature announcement](./composed__feature-announcement.md) — Highlight a new feature with tags and an action.
@@ -61,12 +65,15 @@ Agents: prefer `INDEX.json` (structured) for discovery; this file is for humans.
 
 - [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 · Enhanced activities](./features__enhanced-activities.md) — 
+- [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.
 - [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 · Media Library](./features__media-library.md) — Framework-agnostic media picker for admin product, CMS, and campaign flows. Provides an embeddable library surface, a Dialog-backed picker wrapper, upload staging, details editing, controlled selection, async fetching, slots, render hooks, and headless state through useMediaLibrary.
+- [Features · Mentions](./features__mentions.md) — Inline resource references for editors, comments, and event logs. Consumers provide resource registries and search callbacks; the package provides chips, picker UI, inline suggestions, parsing helpers, and headless hooks.
 - [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.
@@ -76,17 +83,23 @@ Agents: prefer `INDEX.json` (structured) for discovery; this file is for humans.
 - [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 · 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 · 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.
+- [Features · Sync](./features__sync.md) — Reusable sync-range form for integration repair flows. The feature owns form state and validation wiring; consumers own dialog placement, submission, errors, and telemetry.
 
 ## layout
 
 - [Layout · App shell](./layout__layout-app-shell.md) — Standalone header-first shell with a 70px+ topbar and a sidebar/content body grid.
+- [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 · 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.
 
 ## ui
 

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

@@ -21,7 +21,8 @@ imports:
   - @/components/base/accordion
   - @/components/base/badge
   - @/components/base/cards
-  - @/components/typography/text
+  - @/components/typography
+publicImport: admin-ui-starter-kit/base/accordion
 tags:
   - base
   - display
@@ -36,8 +37,77 @@ tags:
 
 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`  
+**Layer:** `base`
 **Source:** `src/components/base/accordion`
+**Consumer import:** `admin-ui-starter-kit/base/accordion`
+
+## Consumer import
+
+Consumers import this surface from `admin-ui-starter-kit/base/accordion`.
+The examples below use repository source aliases because they run inside the preview app; do not copy those aliases into consuming applications.
+
+## Overview
+
+`SmartAccordion` is the 90% case — pass an `items` array of `{ value, title,
+icon?, badge?, content, disabled? }` and pick a visual `variant` (`card` |
+`bordered` | `flat`) and an `iconStyle` (`medallion` | `inline` | `none`).
+Drop down to the compound `Accordion` parts for richer rows.
+
+## Default
+
+<Example name="Default" source={examplesSource}>
+	<Examples.Default />
+</Example>
+
+## Variants
+
+<Example name="VariantCard" source={examplesSource}>
+	<Examples.VariantCard />
+</Example>
+
+<Example name="VariantBordered" source={examplesSource}>
+	<Examples.VariantBordered />
+</Example>
+
+<Example name="VariantFlat" source={examplesSource}>
+	<Examples.VariantFlat />
+</Example>
+
+## Icon styles
+
+<Example name="IconStyleMedallion" source={examplesSource}>
+	<Examples.IconStyleMedallion />
+</Example>
+
+<Example name="IconStyleInline" source={examplesSource}>
+	<Examples.IconStyleInline />
+</Example>
+
+<Example name="IconStyleNone" source={examplesSource}>
+	<Examples.IconStyleNone />
+</Example>
+
+## States
+
+<Example name="MultipleOpen" source={examplesSource}>
+	<Examples.MultipleOpen />
+</Example>
+
+<Example name="WithBadgeAndDisabled" source={examplesSource}>
+	<Examples.WithBadgeAndDisabled />
+</Example>
+
+## Compound API
+
+<Example name="CompoundApi" source={examplesSource}>
+	<Examples.CompoundApi />
+</Example>
+
+## Realistic usage
+
+<Example name="RealisticFAQ" source={examplesSource}>
+	<Examples.RealisticFAQ />
+</Example>
 
 ## Examples
 
@@ -46,7 +116,7 @@ import { Bell, CreditCard, HelpCircle, Lock, Settings, Sparkles } from 'lucide-r
 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';
+import { Heading, Text } from '@/components/typography';
 
 const settingsItems = [
 	{
@@ -173,7 +243,7 @@ export function CompoundApi() {
 					<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>
+							<Text tag="span" weight="semibold">Custom row layout</Text>
 							<Badge variant="warning">Beta</Badge>
 						</div>
 					</AccordionTrigger>
@@ -187,7 +257,7 @@ export function CompoundApi() {
 				<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 tag="span" weight="semibold">Two-line trigger</Text>
 							<Text size="xs" type="secondary">Updated 2h ago</Text>
 						</div>
 					</AccordionTrigger>
@@ -203,10 +273,9 @@ export function CompoundApi() {
 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>
+			<Heading tag="h4" subHeading="Everything you need to know before signing up.">
+				Frequently asked questions
+			</Heading>
 			<SmartAccordion items={faqItems} variant="bordered" iconStyle="none" />
 		</div>
 	);

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

@@ -0,0 +1,156 @@
+---
+id: base/alert
+title: "Alert"
+description: "Semantic notice primitive with icon, title, description, and responsive action regions."
+layer: base
+family: "Display"
+sourcePath: src/components/base/display/alert
+examples:
+  - AlertVariants
+  - AlertWithActions
+  - InverseAlert
+  - StatusRoleAlert
+imports:
+  - @/components/base/buttons
+  - @/components/base/display/alert
+publicImport: admin-ui-starter-kit/base/display
+tags:
+  - base
+  - display
+  - alert
+  - semantic
+  - notice
+  - primitive
+  - icon
+---
+
+# Alert
+
+Semantic notice primitive with icon, title, description, and responsive action regions.
+
+**Layer:** `base`
+**Source:** `src/components/base/display/alert`
+**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.
+
+## Overview
+
+Use `Alert` for inline notices inside admin workflows. Variants map to semantic
+tokens, actions wrap responsively, and title/description text is routed through
+the typography layer.
+
+## Usage
+
+Import the package-owned alert from the display family:
+
+```tsx
+import {
+	Alert,
+	AlertTitle,
+	AlertDescription,
+	AlertAction,
+} from 'admin-ui-starter-kit/base/display';
+```
+
+Use `variant` for semantic tone: `default`, `info`, `success`, `warning`,
+`destructive`, or `inverse`. `Alert` defaults to `role="alert"` for urgent
+notices; pass `role="status"` for non-urgent confirmations. Place buttons,
+links, or other commands in `AlertAction` so actions stack on narrow screens and
+align to the right on wider admin layouts.
+
+## Examples
+
+```tsx
+import { AlertTriangle, CheckCircle2, Info, ShieldAlert, XCircle } from 'lucide-react';
+
+import {
+	Alert,
+	AlertAction,
+	AlertDescription,
+	AlertTitle,
+} from '@/components/base/display/alert';
+import { Button } from '@/components/base/buttons';
+
+export function AlertVariants() {
+	return (
+		<div className="grid w-full max-w-2xl gap-3">
+			<Alert>
+				<Info />
+				<AlertTitle>Default notice</AlertTitle>
+				<AlertDescription>Workspace settings were updated by an administrator.</AlertDescription>
+			</Alert>
+			<Alert variant="info">
+				<Info />
+				<AlertTitle>Import queued</AlertTitle>
+				<AlertDescription>Catalog import will start after the current sync finishes.</AlertDescription>
+			</Alert>
+			<Alert variant="success">
+				<CheckCircle2 />
+				<AlertTitle>Billing profile verified</AlertTitle>
+				<AlertDescription>Invoices can now be issued for this workspace.</AlertDescription>
+			</Alert>
+			<Alert variant="warning">
+				<AlertTriangle />
+				<AlertTitle>Usage is approaching the plan limit</AlertTitle>
+				<AlertDescription>Upgrade before the next billing cycle to avoid paused automations.</AlertDescription>
+			</Alert>
+			<Alert variant="destructive">
+				<XCircle />
+				<AlertTitle>Webhook delivery failed</AlertTitle>
+				<AlertDescription>Three endpoints rejected the latest payload.</AlertDescription>
+			</Alert>
+		</div>
+	);
+}
+
+export function AlertWithActions() {
+	return (
+		<Alert variant="warning" className="max-w-2xl">
+			<ShieldAlert />
+			<AlertTitle>Two-factor enforcement is pending</AlertTitle>
+			<AlertDescription>
+				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>
+			</AlertAction>
+		</Alert>
+	);
+}
+
+export function InverseAlert() {
+	return (
+		<Alert variant="inverse" className="max-w-2xl">
+			<Info />
+			<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>
+			</AlertAction>
+		</Alert>
+	);
+}
+
+export function StatusRoleAlert() {
+	return (
+		<Alert role="status" variant="success" className="max-w-2xl">
+			<CheckCircle2 />
+			<AlertTitle>Changes saved</AlertTitle>
+			<AlertDescription>This non-urgent confirmation uses `role="status"`.</AlertDescription>
+		</Alert>
+	);
+}
+```
+
+## Example exports
+
+- `AlertVariants`
+- `AlertWithActions`
+- `InverseAlert`
+- `StatusRoleAlert`
+

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

@@ -11,6 +11,7 @@ examples:
   - WithDot
 imports:
   - @/components/base/badge
+publicImport: admin-ui-starter-kit/base/badge
 tags:
   - base
   - foundations
@@ -25,8 +26,14 @@ tags:
 
 Status pills and chips for tags, counts, and inline state.
 
-**Layer:** `base`  
+**Layer:** `base`
 **Source:** `src/components/base/badge`
+**Consumer import:** `admin-ui-starter-kit/base/badge`
+
+## Consumer import
+
+Consumers import this surface from `admin-ui-starter-kit/base/badge`.
+The examples below use repository source aliases because they run inside the preview app; do not copy those aliases into consuming applications.
 
 ## Examples
 

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

@@ -30,6 +30,7 @@ examples:
 imports:
   - @/components/base/buttons
   - @/components/typography
+publicImport: admin-ui-starter-kit/base/buttons
 tags:
   - base
   - foundations
@@ -44,8 +45,127 @@ tags:
 
 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`  
+**Layer:** `base`
 **Source:** `src/components/base/buttons`
+**Consumer import:** `admin-ui-starter-kit/base/buttons`
+
+## Consumer import
+
+Consumers import this surface from `admin-ui-starter-kit/base/buttons`.
+The examples below use repository source aliases because they run inside the preview app; do not copy those aliases into consuming applications.
+
+## Overview
+
+`BaseButton` is the foundational primitive — eight semantic `variant`s (dark,
+primary, secondary, error, warning, success, light, action) crossed with three
+`buttonStyle`s (solid, outline, ghost) and four sizes (xs, sm, default, lg)
+plus four icon-only sizes. `Button` layers on optional `loading`, `withTooltip`,
+and `href` so a single component covers most call sites. The specialty buttons
+are pre-styled wrappers for common patterns.
+
+## Default
+
+<Example name="Default" source={examplesSource}>
+	<Examples.Default />
+</Example>
+
+## Variants
+
+<Example name="AllVariantsSolid" source={examplesSource}>
+	<Examples.AllVariantsSolid />
+</Example>
+
+<Example name="AllVariantsOutline" source={examplesSource}>
+	<Examples.AllVariantsOutline />
+</Example>
+
+<Example name="AllVariantsGhost" source={examplesSource}>
+	<Examples.AllVariantsGhost />
+</Example>
+
+<Example name="VariantStyleMatrix" source={examplesSource}>
+	<Examples.VariantStyleMatrix />
+</Example>
+
+## Sizes
+
+<Example name="Sizes" source={examplesSource}>
+	<Examples.Sizes />
+</Example>
+
+<Example name="IconOnlySizes" source={examplesSource}>
+	<Examples.IconOnlySizes />
+</Example>
+
+## Composition
+
+<Example name="WithIconLeft" source={examplesSource}>
+	<Examples.WithIconLeft />
+</Example>
+
+<Example name="WithIconRight" source={examplesSource}>
+	<Examples.WithIconRight />
+</Example>
+
+## States
+
+<Example name="StateDisabled" source={examplesSource}>
+	<Examples.StateDisabled />
+</Example>
+
+<Example name="StateFullWidth" source={examplesSource}>
+	<Examples.StateFullWidth />
+</Example>
+
+## Button (combo wrapper)
+
+<Example name="ButtonComboFeatures" source={examplesSource}>
+	<Examples.ButtonComboFeatures />
+</Example>
+
+## LoaderButton
+
+<Example name="LoaderButtonStates" source={examplesSource}>
+	<Examples.LoaderButtonStates />
+</Example>
+
+<Example name="LoaderButtonInteractive" source={examplesSource}>
+	<Examples.LoaderButtonInteractive />
+</Example>
+
+## TooltipButton
+
+<Example name="TooltipButtonExample" source={examplesSource}>
+	<Examples.TooltipButtonExample />
+</Example>
+
+## Specialty buttons
+
+<Example name="GoogleButtonExample" source={examplesSource}>
+	<Examples.GoogleButtonExample />
+</Example>
+
+<Example name="ShopifyButtonExample" source={examplesSource}>
+	<Examples.ShopifyButtonExample />
+</Example>
+
+<Example name="TextButtonSizes" source={examplesSource}>
+	<Examples.TextButtonSizes />
+</Example>
+
+<Example name="PageActionButtonVariants" source={examplesSource}>
+	<Examples.PageActionButtonVariants />
+</Example>
+
+<Example name="PageActionButtonSizes" source={examplesSource}>
+	<Examples.PageActionButtonSizes />
+</Example>
+
+## Realistic usage
+
+<Example name="RealisticToolbar" source={examplesSource}>
+	<Examples.RealisticToolbar />
+</Example>
 
 ## Examples
 

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

@@ -25,8 +25,9 @@ imports:
   - @/components/base/badge
   - @/components/base/buttons
   - @/components/base/cards
+  - @/components/base/display/avatar
   - @/components/typography/text
-  - @/components/ui/avatar
+publicImport: admin-ui-starter-kit/base/cards
 tags:
   - base
   - foundations
@@ -41,8 +42,104 @@ tags:
 
 The composed card primitive — header (icon, title, suffix, slots), optional alert, expandable body, footer text or slot, and three surface chromes.
 
-**Layer:** `base`  
+**Layer:** `base`
 **Source:** `src/components/base/cards`
+**Consumer import:** `admin-ui-starter-kit/base/cards`
+
+## Consumer import
+
+Consumers import this surface from `admin-ui-starter-kit/base/cards`.
+The examples below use repository source aliases because they run inside the preview app; do not copy those aliases into consuming applications.
+
+## Overview
+
+`SmartCard` is the canonical card surface — every dashboard tile, settings
+panel, or KPI block runs through it. Three `surface` chromes (`card`, `flat`,
+`framed`), three padding scales, optional `headerStart` / `headerEnd` /
+`headerAction` slots, action menus, alert bands, footer text or `footerSlot`,
+and an `expandable` body for long content.
+
+## Default
+
+<Example name="Default" source={examplesSource}>
+	<Examples.Default />
+</Example>
+
+## Surface variants
+
+<Example name="SurfaceVariants" source={examplesSource}>
+	<Examples.SurfaceVariants />
+</Example>
+
+## Padding sizes
+
+<Example name="PaddingSizes" source={examplesSource}>
+	<Examples.PaddingSizes />
+</Example>
+
+## Header composition
+
+<Example name="WithIconTooltipFooter" source={examplesSource}>
+	<Examples.WithIconTooltipFooter />
+</Example>
+
+<Example name="HeaderSlots" source={examplesSource}>
+	<Examples.HeaderSlots />
+</Example>
+
+<Example name="WithActions" source={examplesSource}>
+	<Examples.WithActions />
+</Example>
+
+<Example name="HeaderAndFooterDividers" source={examplesSource}>
+	<Examples.HeaderAndFooterDividers />
+</Example>
+
+## Alerts
+
+<Example name="AlertVariants" source={examplesSource}>
+	<Examples.AlertVariants />
+</Example>
+
+## Expandable
+
+<Example name="ExpandableUncontrolled" source={examplesSource}>
+	<Examples.ExpandableUncontrolled />
+</Example>
+
+<Example name="ExpandableCustomLabels" source={examplesSource}>
+	<Examples.ExpandableCustomLabels />
+</Example>
+
+## States
+
+<Example name="Skeleton" source={examplesSource}>
+	<Examples.Skeleton />
+</Example>
+
+## Primitive parts
+
+`CardShell`, `CardHeader`, `CardTitle`, `CardDescription`, `CardContent`,
+and `CardFooter` are exported from `base/cards` for the rare case when
+`SmartCard`'s composition is too opinionated.
+
+<Example name="PrimitiveComposition" source={examplesSource}>
+	<Examples.PrimitiveComposition />
+</Example>
+
+## Realistic usage
+
+<Example name="MetricKPICard" source={examplesSource}>
+	<Examples.MetricKPICard />
+</Example>
+
+<Example name="NotificationCard" source={examplesSource}>
+	<Examples.NotificationCard />
+</Example>
+
+<Example name="StatRowClickable" source={examplesSource}>
+	<Examples.StatRowClickable />
+</Example>
 
 ## Examples
 
@@ -59,7 +156,7 @@ import {
 	CardContent,
 	CardFooter,
 } from '@/components/base/cards';
-import { Avatar, AvatarFallback } from '@/components/ui/avatar';
+import { Avatar, AvatarFallback } from '@/components/base/display/avatar';
 import { Text } from '@/components/typography/text';
 import { Badge } from '@/components/base/badge';
 
@@ -140,7 +237,7 @@ export function PaddingSizes() {
 
 export function SurfaceVariants() {
 	return (
-		<div className="grid w-full grid-cols-1 gap-4 md:grid-cols-3">
+		<div className="grid w-full grid-cols-[repeat(auto-fit,minmax(min(12rem,100%),1fr))] gap-3">
 			<SmartCard surface="card" title="Card (default)" description="Bordered + soft shadow.">
 				<Text type="secondary">Canonical card chrome.</Text>
 			</SmartCard>