admin-ui-starter-kit 0.5.0 → 0.6.2

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

@@ -0,0 +1,427 @@
+---
+id: base/display-utilities
+title: "Display utilities"
+description: "Narrow display helpers only: separator, banners, boolean indicators, conditionals, progress, skeleton, and utility wrappers."
+layer: base
+family: "Display"
+sourcePath: src/components/base/display
+examples:
+  - NotificationBannerVariants
+  - SeparatorExample
+  - BooleanIndicatorExample
+  - ShowIfExample
+  - ThrottleAlertExample
+  - VisuallyHiddenExample
+  - PlaceholderPatternExample
+  - AlertExample
+  - ProgressExample
+  - SkeletonExample
+  - CollapsibleExample
+  - DialogExample
+  - DateBlockExample
+  - MoneyDisplayExample
+  - QRCodeExample
+imports:
+  - @/components/base/buttons
+  - @/components/base/display/alert
+  - @/components/base/display/boolean-indicator
+  - @/components/base/display/collapsible
+  - @/components/base/display/date-block
+  - @/components/base/display/dialog
+  - @/components/base/display/money-display
+  - @/components/base/display/notification-banner
+  - @/components/base/display/placeholder-pattern
+  - @/components/base/display/progress
+  - @/components/base/display/qr-code
+  - @/components/base/display/separator
+  - @/components/base/display/show-if
+  - @/components/base/display/skeleton
+  - @/components/base/display/throttle-alert
+  - @/components/base/display/visually-hidden
+  - @/components/typography/text
+publicImport: admin-ui-starter-kit/base/display
+tags:
+  - base
+  - display
+  - utilities
+  - narrow
+  - helpers
+  - only
+---
+
+# Display utilities
+
+Narrow display helpers only: separator, banners, boolean indicators, conditionals, progress, skeleton, and utility wrappers.
+
+**Layer:** `base`
+**Source:** `src/components/base/display`
+**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
+
+This route is for narrow display helpers. Identity and contextual primitives now
+have standalone pages in the Base menu: Avatar, Icon badge, Inline stat,
+Metadata list, and Tooltip.
+
+## Separator
+
+<Example name="SeparatorExample" source={examplesSource}>
+	<Examples.SeparatorExample />
+</Example>
+
+## NotificationBanner
+
+<Example name="NotificationBannerVariants" source={examplesSource}>
+	<Examples.NotificationBannerVariants />
+</Example>
+
+## Boolean & conditionals
+
+<Example name="BooleanIndicatorExample" source={examplesSource}>
+	<Examples.BooleanIndicatorExample />
+</Example>
+
+<Example name="ShowIfExample" source={examplesSource}>
+	<Examples.ShowIfExample />
+</Example>
+
+## Misc
+
+<Example name="ThrottleAlertExample" source={examplesSource}>
+	<Examples.ThrottleAlertExample />
+</Example>
+
+<Example name="VisuallyHiddenExample" source={examplesSource}>
+	<Examples.VisuallyHiddenExample />
+</Example>
+
+<Example name="PlaceholderPatternExample" source={examplesSource}>
+	<Examples.PlaceholderPatternExample />
+</Example>
+
+## Alert
+
+<Example name="AlertExample" source={examplesSource}>
+	<Examples.AlertExample />
+</Example>
+
+## Progress & Skeleton
+
+<Example name="ProgressExample" source={examplesSource}>
+	<Examples.ProgressExample />
+</Example>
+
+<Example name="SkeletonExample" source={examplesSource}>
+	<Examples.SkeletonExample />
+</Example>
+
+## Collapsible & Dialog
+
+<Example name="CollapsibleExample" source={examplesSource}>
+	<Examples.CollapsibleExample />
+</Example>
+
+<Example name="DialogExample" source={examplesSource}>
+	<Examples.DialogExample />
+</Example>
+
+## DateBlock
+
+<Example name="DateBlockExample" source={examplesSource}>
+	<Examples.DateBlockExample />
+</Example>
+
+## MoneyDisplay
+
+<Example name="MoneyDisplayExample" source={examplesSource}>
+	<Examples.MoneyDisplayExample />
+</Example>
+
+## QRCode
+
+<Example name="QRCodeExample" source={examplesSource}>
+	<Examples.QRCodeExample />
+</Example>
+
+## Examples
+
+```tsx
+import { useState } from 'react';
+import { AlertTriangle, ChevronDown, Terminal } from 'lucide-react';
+import { BooleanIndicator } from '@/components/base/display/boolean-indicator';
+import { NotificationBanner } from '@/components/base/display/notification-banner';
+import { PlaceholderPattern } from '@/components/base/display/placeholder-pattern';
+import { Separator } from '@/components/base/display/separator';
+import { ShowIf } from '@/components/base/display/show-if';
+import { ThrottleAlert } from '@/components/base/display/throttle-alert';
+import { VisuallyHidden } from '@/components/base/display/visually-hidden';
+import { Alert, AlertTitle, AlertDescription } from '@/components/base/display/alert';
+import { Progress } from '@/components/base/display/progress';
+import { Skeleton } from '@/components/base/display/skeleton';
+import { Collapsible, CollapsibleContent, CollapsibleTrigger } from '@/components/base/display/collapsible';
+import { Dialog, DialogContent, DialogDescription, DialogFooter, DialogHeader, DialogTitle, DialogTrigger } from '@/components/base/display/dialog';
+import { DateBlock } from '@/components/base/display/date-block';
+import { MoneyDisplay } from '@/components/base/display/money-display';
+import { QRCode } from '@/components/base/display/qr-code';
+import { Button } from '@/components/base/buttons';
+import { Text } from '@/components/typography/text';
+
+export function NotificationBannerVariants() {
+	return (
+		<div className="flex flex-col gap-3 w-full max-w-md">
+			<NotificationBanner type="info" title="Heads up" message="An informational notice." />
+			<NotificationBanner type="success" title="Saved" message="All changes have been saved." />
+			<NotificationBanner type="warning" title="Be careful" message="This will affect 24 records." />
+			<NotificationBanner
+				type="error"
+				title="Failed"
+				message="Something went wrong."
+				dismissible
+				onDismiss={() => {}}
+			/>
+		</div>
+	);
+}
+
+export function SeparatorExample() {
+	return (
+		<div className="w-full max-w-md">
+			<Text>Section above</Text>
+			<Separator className="my-3" />
+			<Text>Section below</Text>
+			<div className="mt-4 flex h-6 items-center gap-2">
+				<Text tag="span">Inline</Text>
+				<Separator orientation="vertical" />
+				<Text tag="span">Items</Text>
+				<Separator orientation="vertical" />
+				<Text tag="span">Here</Text>
+			</div>
+		</div>
+	);
+}
+
+export function BooleanIndicatorExample() {
+	return (
+		<div className="flex flex-col gap-2 w-full max-w-sm">
+			<BooleanIndicator label="Verified" value trueVariant="success" />
+			<BooleanIndicator label="Active" value={false} />
+			<BooleanIndicator label="Subscribed" value trueLabel="Yes" falseLabel="No" trueVariant="primary" />
+		</div>
+	);
+}
+
+export function ShowIfExample() {
+	const [show, setShow] = useState(true);
+	return (
+		<div className="flex flex-col gap-2 w-full max-w-sm">
+			<Button
+				type="button"
+				variant="secondary"
+				buttonStyle="outline"
+				className="self-start"
+				onClick={() => setShow((v) => !v)}
+			>
+				{show ? 'Hide' : 'Show'} content
+			</Button>
+			<ShowIf when={show} fallback={<Text tag="span" type="secondary">Hidden — fallback shown.</Text>}>
+				<Text tag="span">Visible only when <code>when</code> is true.</Text>
+			</ShowIf>
+		</div>
+	);
+}
+
+export function ThrottleAlertExample() {
+	return (
+		<div className="w-full max-w-md">
+			<ThrottleAlert
+				message="Too many failed attempts. Please wait."
+				attempts={5}
+				remaining="2 minutes"
+			/>
+		</div>
+	);
+}
+
+export function VisuallyHiddenExample() {
+	return (
+		<div className="flex flex-col gap-2">
+			<Button type="button" variant="secondary" buttonStyle="outline" size="icon-small" className="self-start">
+				<span aria-hidden>×</span>
+				<VisuallyHidden>Close</VisuallyHidden>
+			</Button>
+			<Text size="xs" type="secondary">
+				The button has accessible name &quot;Close&quot; — only the × is visible.
+			</Text>
+		</div>
+	);
+}
+
+export function PlaceholderPatternExample() {
+	return (
+		<div className="relative h-32 w-full max-w-md overflow-hidden rounded-lg border border-border">
+			<PlaceholderPattern className="absolute inset-0 size-full text-muted" />
+		</div>
+	);
+}
+
+// ─────────────────────────────────────────────────────────────────────────────
+// Alert (shadcn re-export)
+// ─────────────────────────────────────────────────────────────────────────────
+
+export function AlertExample() {
+	return (
+		<div className="flex w-full max-w-md flex-col gap-3">
+			<Alert>
+				<Terminal className="size-4" />
+				<AlertTitle>Heads up!</AlertTitle>
+				<AlertDescription>You can preview every example below.</AlertDescription>
+			</Alert>
+			<Alert variant="destructive">
+				<AlertTriangle className="size-4" />
+				<AlertTitle>Something went wrong</AlertTitle>
+				<AlertDescription>Please retry or contact support.</AlertDescription>
+			</Alert>
+		</div>
+	);
+}
+
+// ─────────────────────────────────────────────────────────────────────────────
+// Progress
+// ─────────────────────────────────────────────────────────────────────────────
+
+export function ProgressExample() {
+	return (
+		<div className="flex w-full max-w-md flex-col gap-3">
+			<Progress value={20} />
+			<Progress value={60} />
+			<Progress value={92} />
+		</div>
+	);
+}
+
+// ─────────────────────────────────────────────────────────────────────────────
+// Skeleton
+// ─────────────────────────────────────────────────────────────────────────────
+
+export function SkeletonExample() {
+	return (
+		<div className="flex w-full max-w-md items-center gap-4">
+			<Skeleton className="size-12 rounded-full" />
+			<div className="flex flex-1 flex-col gap-2">
+				<Skeleton className="h-4 w-3/4" />
+				<Skeleton className="h-3 w-1/2" />
+			</div>
+		</div>
+	);
+}
+
+// ─────────────────────────────────────────────────────────────────────────────
+// Collapsible
+// ─────────────────────────────────────────────────────────────────────────────
+
+export function CollapsibleExample() {
+	return (
+		<div className="w-full max-w-md">
+			<Collapsible>
+				<CollapsibleTrigger asChild>
+					<Button type="button" variant="secondary" buttonStyle="outline" icon={ChevronDown}>
+						Toggle details
+					</Button>
+				</CollapsibleTrigger>
+				<CollapsibleContent className="mt-2 rounded-md border border-border bg-card p-3">
+					<Text>Hidden content revealed on click. Use Collapsible for inline disclosures.</Text>
+				</CollapsibleContent>
+			</Collapsible>
+		</div>
+	);
+}
+
+// ─────────────────────────────────────────────────────────────────────────────
+// Dialog
+// ─────────────────────────────────────────────────────────────────────────────
+
+export function DialogExample() {
+	return (
+		<Dialog>
+			<DialogTrigger asChild>
+				<Button>Open dialog</Button>
+			</DialogTrigger>
+			<DialogContent>
+				<DialogHeader>
+					<DialogTitle>Are you sure?</DialogTitle>
+					<DialogDescription>This action cannot be undone.</DialogDescription>
+				</DialogHeader>
+				<DialogFooter>
+					<Button variant="secondary" buttonStyle="ghost">Cancel</Button>
+					<Button variant="error">Delete</Button>
+				</DialogFooter>
+			</DialogContent>
+		</Dialog>
+	);
+}
+
+// ─────────────────────────────────────────────────────────────────────────────
+// DateBlock
+// ─────────────────────────────────────────────────────────────────────────────
+
+export function DateBlockExample() {
+	return (
+		<div className="flex flex-wrap items-start gap-4">
+			<DateBlock date="2026-04-12" />
+			<DateBlock date="2026-04-12" time="14:30" />
+			<DateBlock date="2026-04-12" layout="inline" />
+			<DateBlock date={new Date()} tone="primary" />
+		</div>
+	);
+}
+
+// ─────────────────────────────────────────────────────────────────────────────
+// MoneyDisplay
+// ─────────────────────────────────────────────────────────────────────────────
+
+export function MoneyDisplayExample() {
+	return (
+		<div className="flex flex-col gap-3">
+			<MoneyDisplay money={{ amount: 2450, currency: 'USD' }} size="lg" weight="semibold" />
+			<MoneyDisplay money={{ amount: 49.99, currency: 'EUR' }} />
+			<MoneyDisplay money={null} />
+		</div>
+	);
+}
+
+// ─────────────────────────────────────────────────────────────────────────────
+// QRCode
+// ─────────────────────────────────────────────────────────────────────────────
+
+export function QRCodeExample() {
+	return (
+		<div className="w-40">
+			<QRCode data="https://github.com/admin-ui-starter-kit" />
+		</div>
+	);
+}
+```
+
+## Example exports
+
+- `NotificationBannerVariants`
+- `SeparatorExample`
+- `BooleanIndicatorExample`
+- `ShowIfExample`
+- `ThrottleAlertExample`
+- `VisuallyHiddenExample`
+- `PlaceholderPatternExample`
+- `AlertExample`
+- `ProgressExample`
+- `SkeletonExample`
+- `CollapsibleExample`
+- `DialogExample`
+- `DateBlockExample`
+- `MoneyDisplayExample`
+- `QRCodeExample`
+

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

@@ -172,7 +172,7 @@ export function FilterEventRenderEventCustomEventRendering() {
 								categories={categories}
 								filterEvent={(e) => e.category !== 'wine'}
 								renderEvent={(event, category) => (
-									<div className="truncate rounded-sm bg-foreground/8 px-1.5 py-0.5 text-[length:var(--text-xxs)] text-foreground">
+									<div className="truncate rounded-sm bg-foreground/8 px-1.5 py-0.5 text-xxs text-foreground">
 										{category?.label?.split(' ')[0] ?? ''} · {event.title}
 									</div>
 								)}

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

@@ -93,6 +93,12 @@ Pair any field with `FormField` (or `ControlledFormField` for RHF) to inherit
 the standard label / required asterisk / error / hint rhythm. Pass `invalid`
 to the inner field to flip the destructive border + ring.
 
+Control height, padding, icon offsets, clear-button size, textarea minimums,
+and action-bar rhythm are tokenized through `--control-*`, `--row-*`,
+`--surface-*`, and the shared `--space-*` scale. Prefer CSS variables or
+`UIProvider.forms.defaultControlSize` for global density changes instead of
+pinning `size` props at every form field.
+
 ## FormField wrapper
 
 <Example name="BasicField" source={examplesSource}>
@@ -462,7 +468,7 @@ export function WorkflowChrome() {
 			<FormSection
 				title="Publishing"
 				description="Section chrome, validation summary, dirty state, and submit state stay reusable across form libraries."
-				actions={<Button variant="secondary" size="sm">Reset</Button>}
+				actions={<Button variant="secondary">Reset</Button>}
 			>
 				<div className="grid gap-3 sm:grid-cols-2">
 					<FormField label="Display title" required>
@@ -487,7 +493,7 @@ export function WorkflowChrome() {
 			<DirtyStateBanner
 				title="Unsaved changes"
 				description="Save or discard before leaving this workflow."
-				actions={<Button variant="secondary" size="sm">Discard</Button>}
+				actions={<Button variant="secondary">Discard</Button>}
 			/>
 			<FormActionsBar
 				leading={<span className="text-xs text-muted-foreground">Last saved 2 minutes ago</span>}

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

@@ -0,0 +1,84 @@
+---
+id: base/icon-badge
+title: "Icon badge"
+description: "Tokenized icon container for status, resource, and row media affordances."
+layer: base
+family: "Display"
+sourcePath: src/components/base/display/icon-badge
+examples:
+  - IconBadgeTones
+  - IconBadgeShapes
+  - IconBadgeSmallDefault
+imports:
+  - @/components/base/display/icon-badge
+publicImport: admin-ui-starter-kit/base/display
+tags:
+  - base
+  - display
+  - icon-badge
+  - icon
+  - badge
+  - tokenized
+  - container
+---
+
+# Icon badge
+
+Tokenized icon container for status, resource, and row media affordances.
+
+**Layer:** `base`
+**Source:** `src/components/base/display/icon-badge`
+**Consumer import:** `admin-ui-starter-kit/base/display`
+
+## Consumer import
+
+Consumers import this surface from `admin-ui-starter-kit/base/display`.
+The examples below use repository source aliases because they run inside the preview app; do not copy those aliases into consuming applications.
+
+## Examples
+
+```tsx
+import { Bell, Sparkles } from 'lucide-react';
+
+import { IconBadge } from '@/components/base/display/icon-badge';
+
+export function IconBadgeTones() {
+	const tones = ['primary', 'secondary', 'success', 'warning', 'destructive', 'info', 'muted'] as const;
+
+	return (
+		<div className="flex flex-wrap items-center gap-space-md">
+			{tones.map((tone) => (
+				<IconBadge key={tone} icon={Sparkles} tone={tone} />
+			))}
+		</div>
+	);
+}
+
+export function IconBadgeShapes() {
+	return (
+		<div className="flex items-center gap-space-md">
+			<IconBadge icon={Sparkles} shape="circle" />
+			<IconBadge icon={Sparkles} shape="square" />
+			<IconBadge icon={Sparkles} shape="circle" solid tone="primary" />
+			<IconBadge icon={Sparkles} shape="square" solid tone="success" />
+			<IconBadge icon={Sparkles} bordered />
+		</div>
+	);
+}
+
+export function IconBadgeSmallDefault() {
+	return (
+		<div className="flex items-center gap-space-md">
+			<IconBadge icon={Bell} size="small" />
+			<IconBadge icon={Bell} size="default" />
+		</div>
+	);
+}
+```
+
+## Example exports
+
+- `IconBadgeTones`
+- `IconBadgeShapes`
+- `IconBadgeSmallDefault`
+

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

@@ -49,6 +49,15 @@ dropdown menus. Compose `ItemMedia`, `ItemContent` (with `ItemTitle` and
 The `render` prop turns any `Item` into a custom element (anchor, button, link
 wrapper) without breaking focus/hover styling.
 
+Default row sizing comes from `UIProvider.item.defaultSize` and the shared
+`--row-*`, `--space-*`, `--icon*`, and `--avatar*` structural variables. Omit
+`size` for ordinary rows; use CSS variables or the provider default when
+tightening item density across a surface.
+
+Do not use local `px-0` or one-off vertical padding to align rows with a card
+edge. Keep the item padding balanced and adjust the surrounding section or card
+spacing instead.
+
 ## Consumer usage
 
 Consumers import the row primitive from the exact package entrypoint:
@@ -108,7 +117,7 @@ export function Basic() {
 					<ItemDescription>Primary contact email</ItemDescription>
 				</ItemContent>
 				<ItemActions>
-					<Button buttonStyle="ghost" variant="secondary">
+					<Button buttonStyle="ghost" variant="secondary" size="small">
 						Copy
 					</Button>
 				</ItemActions>

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

@@ -58,7 +58,8 @@ The examples below use repository source aliases because they run inside the pre
 The `navigation/` folder bundles every cross-cutting nav surface — page
 headers, breadcrumb trails, side rails, tab bars, action menus, and the
 language switcher. All components are framework-agnostic — pass `href`s and
-let the consumer wire routing.
+let the consumer wire routing. Breadcrumb scale is limited to `default` and
+`small`; spacing and typography come from the shared display/text variables.
 
 ## Page header
 
@@ -169,10 +170,10 @@ export function SectionNavSticky() {
 									/>
 								</aside>
 								<div className="space-y-6">
-									<section id="nav-overview" className="rounded-md border border-border p-4 min-h-[140px]"><strong>Overview</strong> — section anchor target.</section>
-									<section id="nav-orders" className="rounded-md border border-border p-4 min-h-[140px]"><strong>Orders</strong> — section anchor target.</section>
-									<section id="nav-team" className="rounded-md border border-border p-4 min-h-[140px]"><strong>Team</strong> — section anchor target.</section>
-									<section id="nav-preferences" className="rounded-md border border-border p-4 min-h-[140px]"><strong>Preferences</strong> — section anchor target.</section>
+									<section id="nav-overview" className="min-h-35 rounded-md border border-border p-4"><strong>Overview</strong> — section anchor target.</section>
+									<section id="nav-orders" className="min-h-35 rounded-md border border-border p-4"><strong>Orders</strong> — section anchor target.</section>
+									<section id="nav-team" className="min-h-35 rounded-md border border-border p-4"><strong>Team</strong> — section anchor target.</section>
+									<section id="nav-preferences" className="min-h-35 rounded-md border border-border p-4"><strong>Preferences</strong> — section anchor target.</section>
 								</div>
 							</div>
 		</>
@@ -183,7 +184,7 @@ export function BreadcrumbsSizes() {
 	return (
 		<>
 			<div className="space-y-2">
-								{(['xs', 'sm', 'md'] as const).map((s) => (
+								{(['default', 'small'] as const).map((s) => (
 									<Breadcrumbs
 										key={s}
 										size={s}

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

@@ -3,6 +3,7 @@ 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"
 sourcePath: src/components/base/spinner
 examples:
   - Default
@@ -15,6 +16,7 @@ imports:
 publicImport: admin-ui-starter-kit/base/spinner
 tags:
   - base
+  - feedback
   - spinner
   - loading
   - indicator