admin-ui-starter-kit 0.5.0 → 0.6.2

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

@@ -1,7 +1,7 @@
 ---
 id: layout/layout-page
 title: "Layout · Page"
-description: "Page shell, header partials, actions, and content regions with framework-neutral links."
+description: "Page shell, index scaffolds, resource show shells, header partials, actions, and content regions with framework-neutral links."
 layer: layout
 family: "Shells"
 sourcePath: src/components/layout
@@ -15,9 +15,10 @@ imports:
   - @/components/base/badge
   - @/components/base/buttons
   - @/components/base/cards
+  - @/components/base/item
+  - @/components/features/resource
   - @/components/layout
   - @/components/layout/page
-  - @/components/layout/resource
   - @/components/layout/settings
   - @/components/typography
 publicImport: admin-ui-starter-kit/layout
@@ -26,13 +27,13 @@ tags:
   - shells
   - page
   - shell
-  - header
-  - partials
+  - index
+  - scaffolds
 ---
 
 # Layout · Page
 
-Page shell, header partials, actions, and content regions with framework-neutral links.
+Page shell, index scaffolds, resource show shells, header partials, actions, and content regions with framework-neutral links.
 
 **Layer:** `layout`
 **Source:** `src/components/layout`
@@ -43,6 +44,16 @@ Page shell, header partials, actions, and content regions with framework-neutral
 Consumers import this surface from `admin-ui-starter-kit/layout`.
 The examples below use repository source aliases because they run inside the preview app; do not copy those aliases into consuming applications.
 
+## Overview
+
+Page and resource shells own layout rhythm while the consuming app owns
+routing, data, permissions, and mutation behavior. Use `ResourceIndexShell`
+for index pages and `ResourceShowShell` / `TabbedResourceShell` for detail
+pages. Show-page card padding, section gaps, action controls, metadata rows,
+and aside rhythm inherit from shared surface, spacing, control, row, text, and
+media variables; adjust those variables or provider defaults when changing the
+whole app's density.
+
 ## Examples
 
 ```tsx
@@ -51,6 +62,7 @@ import { Bell, Plus, RefreshCw, Shield, Trash2, User } from 'lucide-react';
 import { Badge } from '@/components/base/badge';
 import { Button } from '@/components/base/buttons';
 import { SmartCard } from '@/components/base/cards';
+import { Item, ItemActions, ItemContent, ItemGroup, ItemMedia, ItemTitle, ItemDescription } from '@/components/base/item';
 import { Text } from '@/components/typography';
 import { Page, PageActions, PageContent, PageHeader, type PageAction } from '@/components/layout/page';
 import {
@@ -63,7 +75,7 @@ import {
 	ResourceRelatedCard,
 	ResourceShowShell,
 	TabbedResourceShell,
-} from '@/components/layout/resource';
+} from '@/components/features/resource';
 import { SettingsShell } from '@/components/layout/settings';
 import type { LayoutLinkRenderProps } from '@/components/layout';
 
@@ -79,6 +91,12 @@ const queue = [
 	{ label: 'Draft contracts', value: '16', detail: '3 waiting on finance' },
 ];
 
+const recentCustomers = [
+	{ initials: 'SS', name: 'Sarah Smitha', detail: 'Gold segment · 4 active bookings', status: 'Live' },
+	{ initials: 'DS', name: 'Daniel Smith', detail: 'Operations owner · invoice review', status: 'Review' },
+	{ initials: 'EG', name: 'Emma Garcia', detail: 'New contact · onboarding started', status: 'New' },
+];
+
 function renderPreviewLink({ href, children, className, target, rel }: LayoutLinkRenderProps) {
 	return <a href={href ?? '#'} className={className} target={target} rel={rel}>{children}</a>;
 }
@@ -92,7 +110,7 @@ function renderPreviewLink({ href, children, className, target, rel }: LayoutLin
 function DemoViewport({ children, height = 560 }: { children: ReactNode; height?: number }) {
 	return (
 		<div
-			className="layout-demo-viewport relative w-full overflow-hidden rounded-md border border-dashed border-border bg-background"
+			className="layout-demo-viewport relative w-full overflow-hidden rounded-lg border border-border bg-muted/20 shadow-sm"
 			style={{ height }}
 		>
 			{children}
@@ -105,7 +123,7 @@ function CustomerOverview() {
 		<div className="space-y-4">
 			<div className="grid gap-3 md:grid-cols-3">
 				{queue.map((item) => (
-					<SmartCard key={item.label} padding="sm" className="border-border/80 shadow-sm">
+					<SmartCard key={item.label} padding="default" className="border-border/80 shadow-sm">
 						<div className="space-y-1">
 							<Text size="xs" type="secondary">{item.label}</Text>
 							<Text weight="semibold">{item.value}</Text>
@@ -115,7 +133,7 @@ function CustomerOverview() {
 				))}
 			</div>
 
-			<SmartCard padding="sm" className="border-border/80 shadow-sm">
+			<SmartCard padding="default" className="border-border/80 shadow-sm">
 				<div className="flex flex-col gap-4 md:flex-row md:items-center md:justify-between">
 					<div className="space-y-1">
 						<Text weight="semibold">Review queue</Text>
@@ -128,6 +146,25 @@ function CustomerOverview() {
 					</div>
 				</div>
 			</SmartCard>
+
+			<SmartCard title="Recent customers" description="Row rhythm, status, and actions use package primitives." padding="default" className="border-border/80 shadow-sm">
+				<ItemGroup>
+					{recentCustomers.map((customer) => (
+						<Item key={customer.name} variant="default">
+							<ItemMedia variant="avatar">{customer.initials}</ItemMedia>
+							<ItemContent>
+								<ItemTitle>{customer.name}</ItemTitle>
+								<ItemDescription>{customer.detail}</ItemDescription>
+							</ItemContent>
+							<ItemActions>
+								<Badge variant={customer.status === 'Live' ? 'success' : customer.status === 'Review' ? 'warning' : 'info'}>
+									{customer.status}
+								</Badge>
+							</ItemActions>
+						</Item>
+					))}
+				</ItemGroup>
+			</SmartCard>
 		</div>
 	);
 }
@@ -182,49 +219,88 @@ export function ComposablePartials() {
 
 export function ResourceShells() {
 	return (
-		<div className="grid gap-4">
-			<ResourceIndexShell
-				title="Bookings"
-				description="Index shells keep header, toolbar, list content, and empty state rhythm consistent."
-				actions={<Button variant="primary" icon={Plus}>New booking</Button>}
-				toolbar={
-					<ResourceActionBar
-						leading={
-							<>
-								<Badge variant="info">24 active</Badge>
-								<Badge variant="warning">8 review</Badge>
-							</>
-						}
-						trailing={<Button variant="secondary">Export</Button>}
-					/>
-				}
-			>
-				<div className="grid gap-2">
-					{queue.map((item) => (
-						<SmartCard key={item.label} padding="sm" className="shadow-sm">
-							<div className="flex items-center justify-between gap-3">
-								<div>
-									<Text weight="medium">{item.label}</Text>
-									<Text size="xs" type="secondary">{item.detail}</Text>
+		<div className="max-h-[38rem] overflow-auto pr-2 md:max-h-[42rem]">
+			<div className="grid gap-4">
+				<ResourceIndexShell
+					title="Bookings"
+					description="Index shells keep header, toolbar, list content, and empty state rhythm consistent."
+					actions={<Button variant="primary" icon={Plus}>New booking</Button>}
+					toolbar={
+						<ResourceActionBar
+							leading={
+								<>
+									<Badge variant="info">24 active</Badge>
+									<Badge variant="warning">8 review</Badge>
+								</>
+							}
+							trailing={<Button variant="secondary">Export</Button>}
+						/>
+					}
+				>
+					<div className="grid gap-2">
+						{queue.map((item) => (
+							<SmartCard key={item.label} padding="default" className="shadow-sm">
+								<div className="flex items-center justify-between gap-3">
+									<div>
+										<Text weight="medium">{item.label}</Text>
+										<Text size="xs" type="secondary">{item.detail}</Text>
+									</div>
+									<Text weight="semibold">{item.value}</Text>
 								</div>
-								<Text weight="semibold">{item.value}</Text>
-							</div>
-						</SmartCard>
-					))}
-				</div>
-			</ResourceIndexShell>
+							</SmartCard>
+						))}
+					</div>
+				</ResourceIndexShell>
 
-			<ResourceShowShell
+				<ResourceShowShell
+					slots={{
+						header: (
+							<ResourceHeader
+								title="Sarah Smitha"
+								eyebrow="Customer"
+								description="Gold-tier account with active bookings and billing history."
+								badges={<Badge variant="success">Active</Badge>}
+								actions={<Button variant="secondary">Edit profile</Button>}
+							/>
+						),
+						aside: (
+							<ResourceRelatedCard title="Related records">
+								<div className="grid gap-2">
+									<Text size="xs" type="secondary">4 bookings</Text>
+									<Text size="xs" type="secondary">2 invoices</Text>
+								</div>
+							</ResourceRelatedCard>
+						),
+					}}
+				>
+					<div className="grid gap-3 md:grid-cols-2">
+						<ResourceDetailsCard title="Account details">
+							<Text size="xs" type="secondary">Primary email, billing status, and customer metadata.</Text>
+						</ResourceDetailsCard>
+						<ResourceActivityCard title="Recent activity">
+							<Text size="xs" type="secondary">Last booking updated 12 minutes ago.</Text>
+						</ResourceActivityCard>
+					</div>
+				</ResourceShowShell>
+			</div>
+		</div>
+	);
+}
+
+export function TabbedResourceDetails() {
+	return (
+		<div className="max-h-[38rem] overflow-auto pr-2 md:max-h-[42rem]">
+			<TabbedResourceShell
+				title="Sarah Smitha"
+				description="Gold-tier account with active bookings and billing history."
+				activeTab="profile"
+				tabs={[
+					{ id: 'profile', label: 'Profile', icon: User },
+					{ id: 'security', label: 'Security', icon: Shield },
+					{ id: 'notifications', label: 'Notifications', icon: Bell, badge: '3' },
+				]}
+				actions={<Button variant="secondary">Edit profile</Button>}
 				slots={{
-					header: (
-						<ResourceHeader
-							title="Sarah Smitha"
-							eyebrow="Customer"
-							description="Gold-tier account with active bookings and billing history."
-							badges={<Badge variant="success">Active</Badge>}
-							actions={<Button variant="secondary">Edit profile</Button>}
-						/>
-					),
 					aside: (
 						<ResourceRelatedCard title="Related records">
 							<div className="grid gap-2">
@@ -236,60 +312,25 @@ export function ResourceShells() {
 				}}
 			>
 				<div className="grid gap-3 md:grid-cols-2">
-					<ResourceDetailsCard title="Account details">
-						<Text size="xs" type="secondary">Primary email, billing status, and customer metadata.</Text>
-					</ResourceDetailsCard>
+					<ResourceDetailsSection
+						title="Account details"
+						metadata={[
+							{ label: 'Email', value: 'sarah@example.com' },
+							{ label: 'Segment', value: 'Gold' },
+							{ label: 'Created', value: 'May 14, 2026' },
+							{ label: 'Owner', value: 'Emma Garcia' },
+						]}
+						help="Consumers own field visibility, permissions, and edit workflows."
+					/>
 					<ResourceActivityCard title="Recent activity">
 						<Text size="xs" type="secondary">Last booking updated 12 minutes ago.</Text>
 					</ResourceActivityCard>
 				</div>
-			</ResourceShowShell>
+			</TabbedResourceShell>
 		</div>
 	);
 }
 
-export function TabbedResourceDetails() {
-	return (
-		<TabbedResourceShell
-			title="Sarah Smitha"
-			description="Gold-tier account with active bookings and billing history."
-			activeTab="profile"
-			tabs={[
-				{ id: 'profile', label: 'Profile', icon: User },
-				{ id: 'security', label: 'Security', icon: Shield },
-				{ id: 'notifications', label: 'Notifications', icon: Bell, badge: '3' },
-			]}
-			actions={<Button variant="secondary">Edit profile</Button>}
-			slots={{
-				aside: (
-					<ResourceRelatedCard title="Related records">
-						<div className="grid gap-2">
-							<Text size="xs" type="secondary">4 bookings</Text>
-							<Text size="xs" type="secondary">2 invoices</Text>
-						</div>
-					</ResourceRelatedCard>
-				),
-			}}
-		>
-			<div className="grid gap-3 md:grid-cols-2">
-				<ResourceDetailsSection
-					title="Account details"
-					metadata={[
-						{ label: 'Email', value: 'sarah@example.com' },
-						{ label: 'Segment', value: 'Gold' },
-						{ label: 'Created', value: 'May 14, 2026' },
-						{ label: 'Owner', value: 'Emma Garcia' },
-					]}
-					help="Consumers own field visibility, permissions, and edit workflows."
-				/>
-				<ResourceActivityCard title="Recent activity">
-					<Text size="xs" type="secondary">Last booking updated 12 minutes ago.</Text>
-				</ResourceActivityCard>
-			</div>
-		</TabbedResourceShell>
-	);
-}
-
 export function SettingsShellExample() {
 	return (
 		<SettingsShell

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

@@ -127,7 +127,7 @@ export function AppSidebarShell() {
 	return (
 		<>
 			<SidebarProvider defaultOpen className="min-h-0">
-								<div className="flex h-[42rem] w-full min-w-[56rem] overflow-hidden rounded-lg border border-border bg-background p-3">
+								<div className="flex h-168 w-full min-w-224 overflow-hidden rounded-lg border border-border bg-background p-3">
 									<div className="flex min-w-0 flex-1 overflow-hidden rounded-lg border border-border bg-background shadow-sm">
 										<AppSidebar
 											className="h-full p-0"
@@ -183,7 +183,7 @@ export function AppSidebarShell() {
 												/>
 												<div className="grid gap-3 md:grid-cols-3">
 													{['Manual review', 'Awaiting stock', 'Ready to fulfill'].map((label, index) => (
-														<SmartCard key={label} padding="sm" className="shadow-sm">
+														<SmartCard key={label} padding="default" className="shadow-sm">
 															<Text size="xs" type="secondary">{label}</Text>
 															<Text weight="semibold">{[8, 12, 36][index]}</Text>
 														</SmartCard>
@@ -203,7 +203,7 @@ export function NavigationPartials() {
 		<>
 			<SidebarProvider defaultOpen className="min-h-0">
 								<div className="grid w-full gap-5 md:grid-cols-2">
-									<div className="h-[30rem] overflow-hidden rounded-xl border border-border bg-sidebar text-sidebar-foreground shadow-sm">
+									<div className="h-120 overflow-hidden rounded-xl border border-border bg-sidebar text-sidebar-foreground shadow-sm">
 										<Sidebar collapsible="none" className="w-full" surfaceClassName="bg-background">
 											<SidebarWorkspaceDropdown
 												logo={<Brand />}
@@ -217,7 +217,7 @@ export function NavigationPartials() {
 										</Sidebar>
 									</div>
 
-									<div className="h-[30rem] overflow-hidden rounded-xl border border-border bg-sidebar p-2 text-sidebar-foreground shadow-sm">
+									<div className="h-120 overflow-hidden rounded-xl border border-border bg-sidebar p-2 text-sidebar-foreground shadow-sm">
 										<SidebarNavigation
 											label="Flat navigation"
 											items={[

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

@@ -14,7 +14,7 @@ imports:
   - @/components/base/badge
   - @/components/base/buttons
   - @/components/base/display/avatar
-  - @/components/base/display/user-cell
+  - @/components/composed/data-display/user-cell
   - @/components/layout
   - @/components/layout/header
   - @/components/layout/sidebar
@@ -49,7 +49,7 @@ The examples below use repository source aliases because they run inside the pre
 import { LogOut, Settings, User, UserPlus } from 'lucide-react';
 import { Button } from '@/components/base/buttons';
 import { Avatar, AvatarBadge, AvatarFallback, AvatarGroup, AvatarGroupCount, AvatarImage } from '@/components/base/display/avatar';
-import { UserCell } from '@/components/base/display/user-cell';
+import { UserCell } from '@/components/composed/data-display/user-cell';
 import { Text } from '@/components/typography';
 import { Badge } from '@/components/base/badge';
 import { HeaderUserMenu } from '@/components/layout/header';
@@ -72,7 +72,7 @@ export function AvatarStates() {
 		<>
 			<Row>
 								{users.map((user, index) => (
-									<Avatar key={user.name} size={index === 0 ? 'lg' : 'default'}>
+									<Avatar key={user.name} className={index === 0 ? 'size-avatar-lg' : undefined}>
 										{!!user.avatar && <AvatarImage src={user.avatar} alt={user.name} />}
 										<AvatarFallback>{initials(user.name)}</AvatarFallback>
 										<AvatarBadge className={index === 1 ? 'bg-warning' : 'bg-success'} />
@@ -133,7 +133,7 @@ export function CustomTriggerCustomContent() {
 								className="h-auto w-full justify-start rounded-md px-2.5 py-2"
 							>
 								<UserCell
-									size="sm"
+									size="small"
 									name={user.name}
 									initials={initials(user.name)}
 									trailing={<Badge variant="info">Admin</Badge>}

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

@@ -12,7 +12,7 @@ imports:
   - @/components/base/badge
   - @/components/base/buttons
   - @/components/base/cards
-  - @/components/base/display
+  - @/components/composed/data-display
   - @/components/layout
   - @/components/layout/workspace
   - @/components/typography
@@ -43,13 +43,21 @@ The examples below use repository source aliases because they run inside the pre
 ## Examples
 
 ```tsx
-import type { ReactNode } from 'react';
-import { Box, ClipboardCheck, Globe2, Image, Languages, PackageCheck, ShieldCheck, SlidersHorizontal } from 'lucide-react';
+import type {
+	ReactNode } from 'react';
+import { Box,
+	ClipboardCheck,
+	Globe2,
+	Image,
+	Languages,
+	PackageCheck,
+	ShieldCheck,
+	SlidersHorizontal } from 'lucide-react';
 
 import { Badge } from '@/components/base/badge';
 import { Button } from '@/components/base/buttons';
 import { SmartCard } from '@/components/base/cards';
-import { InlineStat } from '@/components/base/display';
+import { InlineStat } from '@/components/composed/data-display';
 import {
 	WorkspaceLayout,
 	WorkspaceLocaleStrip,
@@ -102,13 +110,13 @@ function MainWorkspaceContent() {
 	return (
 		<div className="space-y-4">
 			<div className="grid gap-3 md:grid-cols-3">
-				<SmartCard padding="sm" className="border-border/80 shadow-sm">
+				<SmartCard padding="default" className="border-border/80 shadow-sm">
 					<InlineStat label="Readiness" value="82%" layout="stacked" mono valueClassName="font-semibold" />
 				</SmartCard>
-				<SmartCard padding="sm" className="border-border/80 shadow-sm">
+				<SmartCard padding="default" className="border-border/80 shadow-sm">
 					<InlineStat label="Variants" value="6" layout="stacked" mono valueClassName="font-semibold" />
 				</SmartCard>
-				<SmartCard padding="sm" className="border-border/80 shadow-sm">
+				<SmartCard padding="default" className="border-border/80 shadow-sm">
 					<InlineStat label="Locales" value="2 / 4" layout="stacked" mono valueClassName="font-semibold" />
 				</SmartCard>
 			</div>
@@ -116,7 +124,7 @@ function MainWorkspaceContent() {
 			<SmartCard
 				title="Workspace body"
 				description="Consumers mount composed product cards, feature surfaces, or their own forms here."
-				padding="sm"
+				padding="default"
 				headerDivider
 			>
 				<div className="grid gap-3 md:grid-cols-2">
@@ -141,7 +149,7 @@ function WorkspaceRail() {
 				icon={<ClipboardCheck className="size-4" />}
 				title="Review"
 				description="Right rail stays fixed to the workspace column on wide screens."
-				padding="sm"
+				padding="default"
 			>
 				<div className="space-y-2">
 					<InlineStat label="Blocked checks" value="2" mono />
@@ -149,7 +157,7 @@ function WorkspaceRail() {
 					<InlineStat label="Owner" value="Catalogue" />
 				</div>
 			</SmartCard>
-			<SmartCard title="Publishing" padding="sm">
+			<SmartCard title="Publishing" padding="default">
 				<Text size="xs" type="secondary">Rail cards are consumer-owned content. The layout only controls the column and scroll.</Text>
 			</SmartCard>
 		</div>
@@ -211,7 +219,7 @@ export function WorkspaceWithoutRail() {
 				)}
 				sidebar={<WorkspaceNav activeId="translations" groups={navGroups.slice(1)} renderLink={renderPreviewLink} />}
 			>
-				<SmartCard title="Focused editor" description="A narrower workspace for dense forms or translation review." padding="sm">
+				<SmartCard title="Focused editor" description="A narrower workspace for dense forms or translation review." padding="default">
 					<div className="space-y-3">
 						{['Headline', 'Summary', 'Customer instructions'].map((label) => (
 							<div key={label} className="rounded-md border border-border bg-background px-3 py-2.5">