@aurostack/stacks 0.1.0

package/templates/react-app/files/src/shared/layouts/app-shell/app-shell.tsx

@@ -0,0 +1,225 @@
+import { type ReactNode, useState } from 'react';
+import { NavLink, Outlet } from 'react-router';
+import { Menu, X } from 'lucide-react';
+import { Logo, cn } from '@/shared/ui';
+import { UserMenu, type ShellUser } from './user-menu';
+
+export type NavItem = {
+	label: string;
+	to: string;
+	icon: ReactNode;
+	/** Match the route exactly (use for the index/dashboard route). */
+	end?: boolean;
+};
+
+/**
+ * Warm a route's chunk before the click, given its `to`. Wired to hover, keyboard
+ * focus and touch-start, so it covers pointer, keyboard and mobile — a phone has
+ * no hover, but `touchstart` still lands a few hundred ms before the click.
+ * Optional: apps without code-split routes just leave it off.
+ */
+export type PreloadRoute = (to: string) => void;
+
+export type ComingSoonItem = {
+	label: string;
+	icon: ReactNode;
+};
+
+type AppShellProps = {
+	nav: NavItem[];
+	user: ShellUser;
+	onSignOut: () => void;
+	/** Brand lockup at the top of the sidebar. Defaults to the Acme Corp mark. */
+	brand?: ReactNode;
+	/** Locked "Coming soon" nav entries shown below the main nav. */
+	comingSoon?: ComingSoonItem[];
+	/** Slot pinned to the bottom of the sidebar (e.g. the market ticker). */
+	sidebarFooter?: ReactNode;
+	/** Topbar search slot. */
+	search?: ReactNode;
+	/** Topbar action slot to the left of the user menu (e.g. the notification bell). */
+	topbarActions?: ReactNode;
+	/** Page content. Defaults to the router <Outlet /> when omitted. */
+	children?: ReactNode;
+	/** Warms a route's code-split chunk on nav hover/focus/touch. */
+	preloadRoute?: PreloadRoute;
+};
+
+function DefaultBrand() {
+	return (
+		<div className="px-2">
+			<Logo />
+		</div>
+	);
+}
+
+function Sidebar({
+	nav,
+	comingSoon,
+	sidebarFooter,
+	brand,
+	onNavigate,
+	preloadRoute
+}: Pick<AppShellProps, 'nav' | 'comingSoon' | 'sidebarFooter' | 'brand' | 'preloadRoute'> & {
+	onNavigate?: () => void;
+}) {
+	return (
+		<div className="flex h-full flex-col p-4">
+			<div className="py-2">{brand ?? <DefaultBrand />}</div>
+			{/*
+			 * `min-h-0` is load-bearing: a flex child defaults to `min-height: auto`,
+			 * which lets it grow past its flex-basis to fit its content instead of
+			 * scrolling — on a short viewport that pushed `sidebarFooter` off the
+			 * bottom of the fixed-height sidebar with no way to reach it. Scrollbar
+			 * is hidden (still scrollable via wheel/touch/keyboard) to match the
+			 * flat, chrome-free sidebar surface — nav is short enough that a visible
+			 * track would only appear briefly during scroll anyway.
+			 */}
+			<div className="flex min-h-0 flex-1 flex-col gap-1 overflow-y-auto [scrollbar-width:none] [&::-webkit-scrollbar]:hidden">
+				<nav className="flex flex-col gap-0.5">
+					{nav.map((item) => (
+						<NavLink
+							key={item.to}
+							to={item.to}
+							end={item.end}
+							onClick={onNavigate}
+							onPointerEnter={() => preloadRoute?.(item.to)}
+							onFocus={() => preloadRoute?.(item.to)}
+							onTouchStart={() => preloadRoute?.(item.to)}
+							className={({ isActive }) =>
+								cn(
+									'flex items-center gap-3 rounded-xl px-3 py-2.5 text-sm font-semibold transition-colors [&_svg]:size-[18px]',
+									isActive ? 'bg-accent text-accent-foreground' : 'text-body hover:bg-secondary'
+								)
+							}
+						>
+							{item.icon}
+							{item.label}
+						</NavLink>
+					))}
+				</nav>
+				{comingSoon && comingSoon.length > 0 ? (
+					<>
+						<div className="mx-2 my-3 h-px bg-border" />
+						<p className="px-3 pb-1 text-[10px] font-bold uppercase tracking-[0.09em] text-mute">Coming soon</p>
+						<div className="flex flex-col gap-0.5">
+							{comingSoon.map((item) => (
+								<div
+									key={item.label}
+									className="flex cursor-default items-center justify-between gap-2 rounded-xl px-3 py-2 text-sm font-semibold text-mute [&_svg]:size-4"
+								>
+									<span className="flex items-center gap-3">
+										{item.icon}
+										{item.label}
+									</span>
+									<span className="rounded-full bg-accent px-1.5 py-0.5 text-[8.5px] font-bold uppercase tracking-[0.08em] text-accent-foreground">
+										Soon
+									</span>
+								</div>
+							))}
+						</div>
+					</>
+				) : null}
+			</div>
+			{sidebarFooter ? <div className="pt-3">{sidebarFooter}</div> : null}
+		</div>
+	);
+}
+
+/**
+ * Authenticated app shell (shared by Client + Admin): fixed sidebar at desktop,
+ * a slide-in drawer on mobile, and a sticky topbar with search / actions / user
+ * menu. Presentational only — nav and slots are passed in, and sign-out is
+ * delegated via `onSignOut`, so it stays decoupled from the auth package.
+ */
+export function AppShell({
+	nav,
+	user,
+	onSignOut,
+	brand,
+	comingSoon,
+	sidebarFooter,
+	search,
+	topbarActions,
+	children,
+	preloadRoute
+}: AppShellProps) {
+	const [mobileOpen, setMobileOpen] = useState(false);
+
+	return (
+		<div className="min-h-screen bg-background">
+			{/* Desktop sidebar */}
+			<aside className="fixed inset-y-0 left-0 hidden w-64 border-r border-border bg-card lg:block">
+				<Sidebar
+					nav={nav}
+					comingSoon={comingSoon}
+					sidebarFooter={sidebarFooter}
+					brand={brand}
+					preloadRoute={preloadRoute}
+				/>
+			</aside>
+
+			{/* Mobile drawer — always mounted so it animates on both enter and exit. */}
+			<div
+				className={cn('fixed inset-0 z-50 lg:hidden', !mobileOpen && 'pointer-events-none')}
+				aria-hidden={!mobileOpen}
+				inert={!mobileOpen}
+			>
+				<div
+					onClick={() => setMobileOpen(false)}
+					aria-hidden="true"
+					className={cn(
+						'absolute inset-0 bg-scrim transition-opacity duration-300 ease-out motion-reduce:transition-none',
+						mobileOpen ? 'opacity-100' : 'opacity-0'
+					)}
+				/>
+				<aside
+					className={cn(
+						'absolute inset-y-0 left-0 w-64 border-r border-border bg-card',
+						'transition-transform duration-300 ease-out motion-reduce:transition-none',
+						mobileOpen ? 'translate-x-0' : '-translate-x-full'
+					)}
+				>
+					<button
+						type="button"
+						onClick={() => setMobileOpen(false)}
+						aria-label="Close menu"
+						className="absolute right-3 top-4 flex size-8 items-center justify-center rounded-full text-mute hover:bg-secondary"
+					>
+						<X className="size-5" />
+					</button>
+					<Sidebar
+						nav={nav}
+						comingSoon={comingSoon}
+						sidebarFooter={sidebarFooter}
+						brand={brand}
+						preloadRoute={preloadRoute}
+						onNavigate={() => setMobileOpen(false)}
+					/>
+				</aside>
+			</div>
+
+			{/* Main column */}
+			<div className="flex min-h-screen flex-col lg:pl-64">
+				<header className="sticky top-0 z-40 flex items-center gap-2.5 border-b border-border bg-card px-4 py-2.5">
+					<button
+						type="button"
+						onClick={() => setMobileOpen(true)}
+						aria-label="Open menu"
+						className="flex size-9 items-center justify-center rounded-full text-foreground hover:bg-secondary lg:hidden"
+					>
+						<Menu className="size-5" />
+					</button>
+					{search ?? <div className="flex-1" />}
+					<div className="ml-auto flex items-center gap-2">
+						{topbarActions}
+						<UserMenu user={user} onSignOut={onSignOut} />
+					</div>
+				</header>
+				<main className="flex-1">
+					<div className="mx-auto w-full max-w-6xl p-4 sm:p-6 lg:p-8">{children ?? <Outlet />}</div>
+				</main>
+			</div>
+		</div>
+	);
+}

package/templates/react-app/files/src/shared/layouts/app-shell/user-menu.tsx

@@ -0,0 +1,74 @@
+import { useEffect, useRef, useState } from 'react';
+import { LogOut } from 'lucide-react';
+
+export type ShellUser = {
+	name?: string | null;
+	email?: string | null;
+	image?: string | null;
+};
+
+function initials(user: ShellUser): string {
+	const name = (user.name ?? '').trim();
+	if (name) {
+		const parts = name.split(/\s+/);
+		const first = parts[0]?.[0] ?? '';
+		const second = parts[1]?.[0] ?? '';
+		return (first + second || first).toUpperCase();
+	}
+	const email = (user.email ?? '').trim();
+	return email ? email[0].toUpperCase() : '?';
+}
+
+/** Avatar button + dropdown (name/email + sign out). Sign-out is delegated via `onSignOut`. */
+export function UserMenu({ user, onSignOut }: { user: ShellUser; onSignOut: () => void }) {
+	const [open, setOpen] = useState(false);
+	const ref = useRef<HTMLDivElement>(null);
+
+	useEffect(() => {
+		if (!open) return;
+		const onDocClick = (event: MouseEvent) => {
+			if (ref.current && !ref.current.contains(event.target as Node)) setOpen(false);
+		};
+		document.addEventListener('mousedown', onDocClick);
+		return () => document.removeEventListener('mousedown', onDocClick);
+	}, [open]);
+
+	return (
+		<div className="relative" ref={ref}>
+			<button
+				type="button"
+				onClick={() => setOpen((value) => !value)}
+				aria-haspopup="menu"
+				aria-expanded={open}
+				aria-label="Account menu"
+				className="flex size-9 items-center justify-center overflow-hidden rounded-full bg-primary text-sm font-bold text-primary-foreground outline-none focus-visible:ring-2 focus-visible:ring-ring focus-visible:ring-offset-2 focus-visible:ring-offset-background"
+			>
+				{user.image ? <img src={user.image} alt="" className="size-9 rounded-full object-cover" /> : initials(user)}
+			</button>
+			{open ? (
+				<div
+					role="menu"
+					className="absolute right-0 top-11 z-50 w-56 rounded-2xl border border-border bg-card p-2 shadow-[0_12px_32px_rgba(14,15,12,0.18)]"
+				>
+					<div className="px-3 py-2">
+						<p className="truncate text-sm font-semibold text-foreground">{user.name ?? 'Your account'}</p>
+						{user.email ? <p className="truncate text-xs text-mute">{user.email}</p> : null}
+					</div>
+					<div className="my-1 h-px bg-border" />
+					<button
+						type="button"
+						role="menuitem"
+						onClick={() => {
+							setOpen(false);
+							onSignOut();
+						}}
+						className="flex w-full items-center gap-2.5 rounded-xl px-3 py-2 text-left text-sm font-semibold text-foreground transition-colors hover:bg-secondary"
+					>
+						<LogOut className="size-4" />
+						Sign out
+					</button>
+				</div>
+			) : null}
+		</div>
+	);
+}

package/templates/react-app/files/src/shared/layouts/auth-layout.tsx

@@ -0,0 +1,137 @@
+import type { ReactNode } from 'react';
+import { Logo, LogoMark, ThemeToggle } from '@/shared/ui';
+
+/**
+ * Brand-panel watermark, per the design system's Watermark guideline: one large
+ * mark, offset, clear of all text, never tiled — "felt, not read".
+ *
+ * Inline SVG (`LogoMark` fills with `currentColor`), so it costs no request and
+ * inverts with the theme for free: ink on the sage panel, near-white on the ink
+ * one. The DS quotes 6–8% ink, but that assumes a light surface — the dark panel
+ * is far darker, so the same alpha reads ~45% stronger against it. Measured in
+ * CIELAB against each panel colour and matched: 0.07 light gives ΔE 5.4, 0.05
+ * dark gives ΔE 5.6. Don't "simplify" these to one value.
+ *
+ * `-z-10` under the panel's `isolate` puts it behind the copy while staying above
+ * the panel's own background; without `isolate` the negative z-index would sink
+ * below it and disappear.
+ */
+function BrandWatermark() {
+	return (
+		<div className="pointer-events-none absolute inset-0 -z-10 overflow-hidden" aria-hidden="true">
+			{/*
+			 * Size and offset are load-bearing, and every value here came from looking
+			 * at it rather than reasoning about it:
+			 * - 460px left only a corner fragment on-panel, so it read as stray grey
+			 *   rectangles rather than the monogram.
+			 * - 300px read correctly at 1280 but the dot poked out past the teaser
+			 *   card's right edge; the guideline is explicit that it stays clear.
+			 * - 240px clears the card at 1280 — but not at 1024, where the panel is
+			 *   only 512px wide. The card is 340px inside 48px padding, so it owns the
+			 *   left 388px and *any* legible mark overlaps it horizontally there. The
+			 *   only way to clear is vertically, hence the smaller `lg` size that fits
+			 *   in the ~155px below the card, going full size from `xl`.
+			 *
+			 * Sized in CSS, not the `width` prop, so it can be responsive — the classes
+			 * override the SVG's width/height attributes and the viewBox keeps the ratio.
+			 * Re-check both breakpoints if the card's width or the panel padding changes.
+			 */}
+			<LogoMark
+				width={240}
+				className="absolute -bottom-4 -right-4 h-auto w-40 text-foreground opacity-[0.07] dark:opacity-[0.05] xl:w-60"
+			/>
+		</div>
+	);
+}
+
+/**
+ * Product teaser — the brand panel's signature element. Shows a prospective user
+ * what the product does instead of decorating around them, and costs nothing:
+ * the sparkline is inline SVG, no image request.
+ *
+ * Replace the copy and the figure with your own; keep the shape. **The numbers
+ * are illustrative, not anyone's data**, which is why the visually-hidden
+ * "Example" prefix is here — without it a screen reader announces a fabricated
+ * figure as fact.
+ *
+ * Brand green on the line doesn't conflict with "green is for CTAs": `--primary`
+ * is the same hex in both themes, so the card needs no per-theme handling, and
+ * the surrounding surfaces do.
+ */
+const SPARK = 'M0,44 C24,40 40,46 62,38 C86,29 102,34 124,27 C148,19 166,24 190,17 C214,11 236,14 256,9 L280,6';
+
+function ProductTeaser() {
+	return (
+		<div className="mt-7 max-w-[340px] rounded-[20px] bg-card px-5 py-[18px]">
+			<div className="flex items-baseline justify-between gap-2.5">
+				<span className="text-[11px] font-semibold uppercase leading-[15px] tracking-[0.07em] text-mute">
+					<span className="sr-only">Example: </span>This month
+				</span>
+				<span className="text-[11.5px] font-semibold leading-4 text-positive">▲ +18.4%</span>
+			</div>
+			<div className="mt-1.5 text-[26px] font-extrabold leading-8 tracking-[-0.02em] tabular-nums text-foreground">
+				42,830.16
+			</div>
+			<svg viewBox="0 0 280 56" className="mt-2.5 h-14 w-full" aria-hidden="true">
+				{/* Area first so the stroke sits on top of it. */}
+				<path d={`${SPARK} L280,56 L0,56 Z`} className="fill-primary opacity-12" />
+				<path d={SPARK} fill="none" strokeWidth="2.5" className="stroke-primary" />
+			</svg>
+			<p className="mt-1.5 text-[10.5px] leading-[15px] text-mute">Illustrative figures · replace with your own</p>
+		</div>
+	);
+}
+
+type AuthLayoutProps = {
+	children: ReactNode;
+	/** Optional brand-panel content (headline / illustration). */
+	aside?: ReactNode;
+};
+
+/**
+ * Split auth shell (Wise pattern): sage brand panel on the left at desktop,
+ * form panel on the right; stacked to a single centered column on mobile.
+ * No shadows — the form sits on the page/card surface via contrast.
+ */
+export function AuthLayout({ children, aside }: AuthLayoutProps) {
+	return (
+		<div className="min-h-screen w-full bg-background lg:grid lg:grid-cols-2">
+			{/*
+			 * `isolate` so the watermark's -z-10 stays above the panel background.
+			 *
+			 * `my-auto` on the content block rather than `justify-between` on the panel:
+			 * the footer line used to anchor the bottom, so with it gone space-between
+			 * would drop the headline to the floor.
+			 */}
+			<aside className="relative isolate hidden flex-col gap-10 bg-brand-panel p-12 lg:flex">
+				<BrandWatermark />
+				<Logo />
+				<div className="my-auto max-w-md">
+					{aside ?? (
+						<>
+							<h1 className="font-display text-4xl font-black leading-[1.06] tracking-tight text-foreground">
+								One line on why you exist.
+							</h1>
+							<p className="mt-4 max-w-sm text-body">
+								A sentence of supporting copy, written for someone who has never heard of this product.
+							</p>
+							<ProductTeaser />
+						</>
+					)}
+				</div>
+			</aside>
+			{/*
+			 * The auth app has no topbar, so the toggle rides the form panel. Placed
+			 * here rather than per-route because every auth screen goes through this
+			 * layout. `relative` on the panel keeps it inside the right-hand column at
+			 * desktop instead of over the brand panel.
+			 */}
+			<main className="relative flex min-h-screen items-center justify-center p-6">
+				<div className="absolute right-4 top-4">
+					<ThemeToggle />
+				</div>
+				<div className="w-full max-w-md">{children}</div>
+			</main>
+		</div>
+	);
+}

package/templates/react-app/files/src/shared/layouts/error-boundary.tsx

@@ -0,0 +1,38 @@
+import { Component, type ErrorInfo, type ReactNode } from 'react';
+import { Button } from '@/shared/ui';
+import { StateScreen } from './states/state-screen';
+
+type ErrorBoundaryProps = {
+	children: ReactNode;
+	fallback?: ReactNode;
+};
+
+type ErrorBoundaryState = {
+	hasError: boolean;
+};
+
+/** Catches render errors in its subtree and shows a recoverable fallback. */
+export class ErrorBoundary extends Component<ErrorBoundaryProps, ErrorBoundaryState> {
+	state: ErrorBoundaryState = { hasError: false };
+
+	static getDerivedStateFromError(): ErrorBoundaryState {
+		return { hasError: true };
+	}
+
+	componentDidCatch(error: Error, info: ErrorInfo): void {
+		console.error('ErrorBoundary caught an error', error, info);
+	}
+
+	render(): ReactNode {
+		if (this.state.hasError) {
+			return (
+				this.props.fallback ?? (
+					<StateScreen title="Something went wrong" description="An unexpected error occurred. Try reloading the page.">
+						<Button onClick={() => window.location.reload()}>Reload</Button>
+					</StateScreen>
+				)
+			);
+		}
+		return this.props.children;
+	}
+}

package/templates/react-app/files/src/shared/layouts/index.ts

@@ -0,0 +1,23 @@
+// @/shared/layouts — shared layouts and state components.
+export { AuthLayout } from './auth-layout';
+export { Loading } from './states/loading';
+export { AppShellSkeleton } from './states/app-shell-skeleton';
+export { RouteFallback } from './states/route-fallback';
+export { PageSkeleton } from './states/page-skeleton';
+export { Forbidden } from './states/forbidden';
+export { NotFound } from './states/not-found';
+export { Empty } from './states/empty';
+export { StateScreen } from './states/state-screen';
+export { ErrorBoundary } from './error-boundary';
+
+// App shell (Client + Admin)
+export { AppShell } from './app-shell/app-shell';
+export type { NavItem, ComingSoonItem, PreloadRoute } from './app-shell/app-shell';
+export { UserMenu } from './app-shell/user-menu';
+export type { ShellUser } from './app-shell/user-menu';
+
+// Marketing (landing)
+export { MarketingLayout } from './marketing/marketing-layout';
+export { Section } from './marketing/section';
+export type { SectionTone } from './marketing/section';
+export { SectionHeading } from './marketing/section-heading';

package/templates/react-app/files/src/shared/layouts/marketing/marketing-layout.tsx

@@ -0,0 +1,29 @@
+import type { ReactNode } from 'react';
+import { Outlet } from 'react-router';
+
+type MarketingLayoutProps = {
+	/** Sticky header slot (brand, nav, auth CTAs). */
+	header?: ReactNode;
+	/** Footer slot (link columns, legal, newsletter). */
+	footer?: ReactNode;
+	/** Page content. Defaults to the router <Outlet /> when omitted. */
+	children?: ReactNode;
+};
+
+/**
+ * Shared shell for the public marketing site (landing) and its legal pages: a
+ * header slot, the routed page content, and a footer slot — defined once so
+ * nav and footer aren't rebuilt per route. Presentational only, like
+ * `AppShell`: no data fetching, no router coupling beyond the `Outlet`
+ * fallback, and no Suspense of its own — that's the consumer's job, same as
+ * `AppShell` leaves it to `ClientShell`.
+ */
+export function MarketingLayout({ header, footer, children }: MarketingLayoutProps) {
+	return (
+		<div className="flex min-h-screen flex-col bg-background">
+			{header}
+			<main className="flex-1">{children ?? <Outlet />}</main>
+			{footer}
+		</div>
+	);
+}

package/templates/react-app/files/src/shared/layouts/marketing/section-heading.tsx

@@ -0,0 +1,38 @@
+import { cn } from '@/shared/ui';
+
+type SectionHeadingProps = {
+	eyebrow?: string;
+	title: string;
+	lede?: string;
+	/** `left` drops the centering, for a heading inside a two-column row rather than standing alone. */
+	align?: 'center' | 'left';
+	className?: string;
+};
+
+/**
+ * Eyebrow pill / h2 / lede — the heading stack the design repeats at the top
+ * of most sections. `bg-accent text-accent-foreground` rather than the fixed
+ * `primary-pale` + `ink-deep`: the accent pair flips together per theme, where a
+ * fixed pale badge goes muddy on dark.
+ */
+export function SectionHeading({ eyebrow, title, lede, align = 'center', className }: SectionHeadingProps) {
+	return (
+		<div
+			className={cn(
+				'flex flex-col gap-4',
+				align === 'center' ? 'items-center text-center' : 'items-start text-left',
+				className
+			)}
+		>
+			{eyebrow ? (
+				<span className="inline-flex rounded-full bg-accent px-3.5 py-1.5 text-xs font-bold uppercase tracking-wider text-accent-foreground">
+					{eyebrow}
+				</span>
+			) : null}
+			<h2 className="max-w-3xl font-display text-3xl font-black tracking-tight text-foreground sm:text-4xl lg:text-5xl">
+				{title}
+			</h2>
+			{lede ? <p className="max-w-2xl text-lg text-body">{lede}</p> : null}
+		</div>
+	);
+}

package/templates/react-app/files/src/shared/layouts/marketing/section.tsx

@@ -0,0 +1,30 @@
+import type { ReactNode } from 'react';
+import { cn } from '@/shared/ui';
+
+export type SectionTone = 'page' | 'band';
+
+type SectionProps = {
+	/** `page` (default) is the plain page background; `band` is the tinted alternate. */
+	tone?: SectionTone;
+	id?: string;
+	className?: string;
+	children?: ReactNode;
+};
+
+/**
+ * The design alternates the plain page background and a tinted band between
+ * sections. This owns that tone plus the shared 1200px container and vertical
+ * rhythm, so pages reach for a prop instead of one-off classes per section.
+ */
+export function Section({ tone = 'page', id, className, children }: SectionProps) {
+	return (
+		<section
+			id={id}
+			// `scroll-mt` only matters for a section that's also an anchor
+			// target — otherwise the sticky header covers the heading on arrival.
+			className={cn(tone === 'band' ? 'bg-secondary' : 'bg-background', id && 'scroll-mt-20')}
+		>
+			<div className={cn('mx-auto max-w-[1200px] px-5 py-14 sm:py-16 lg:py-24', className)}>{children}</div>
+		</section>
+	);
+}

package/templates/react-app/files/src/shared/layouts/states/app-shell-skeleton.tsx

@@ -0,0 +1,47 @@
+import { Logo, Skeleton } from '@/shared/ui';
+import { PageSkeleton } from './page-skeleton';
+
+/**
+ * Full-page skeleton for the authenticated bootstrap (session resolving on reload).
+ * Renders the real app-shell chrome — sidebar frame + brand + topbar — so the frame
+ * appears instantly and only nav/content pulse, then hands off to the route's own
+ * skeletons once the shell mounts. Route-agnostic content (used by Client + Admin).
+ */
+export function AppShellSkeleton() {
+	return (
+		<div className="min-h-screen bg-background">
+			{/* Desktop sidebar */}
+			<aside className="fixed inset-y-0 left-0 hidden w-64 border-r border-border bg-card lg:block">
+				<div className="flex h-full flex-col gap-1 p-4">
+					<div className="px-2 py-2">
+						<Logo />
+					</div>
+					<div className="mt-1 flex flex-col gap-1">
+						{Array.from({ length: 6 }).map((_, i) => (
+							<div key={i} className="flex items-center gap-3 px-3 py-2.5">
+								<Skeleton className="size-[18px] rounded-md" />
+								<Skeleton className="h-3.5 w-24" />
+							</div>
+						))}
+					</div>
+				</div>
+			</aside>
+
+			{/* Main column */}
+			<div className="flex min-h-screen flex-col lg:pl-64">
+				<header className="sticky top-0 z-40 flex items-center gap-2.5 border-b border-border bg-card px-4 py-2.5">
+					<Skeleton className="size-9 rounded-full lg:hidden" />
+					<div className="flex-1" />
+					<Skeleton className="size-9 rounded-full" />
+				</header>
+				<main className="flex-1">
+					{/* Same content skeleton a route transition shows, so a reload and a
+					    navigation look identical. */}
+					<div className="mx-auto w-full max-w-6xl p-4 sm:p-6 lg:p-8">
+						<PageSkeleton />
+					</div>
+				</main>
+			</div>
+		</div>
+	);
+}

package/templates/react-app/files/src/shared/layouts/states/empty.tsx

@@ -0,0 +1,22 @@
+import type { ReactNode } from 'react';
+
+type EmptyProps = {
+	title: string;
+	description?: string;
+	icon?: ReactNode;
+	action?: ReactNode;
+};
+
+/** Inline empty state for lists/panels (a card, not a full page). */
+export function Empty({ title, description, icon, action }: EmptyProps) {
+	return (
+		<div className="flex flex-col items-center justify-center gap-3 rounded-3xl border border-border bg-card p-10 text-center">
+			{icon ? <div className="text-mute">{icon}</div> : null}
+			<div className="flex flex-col gap-1">
+				<p className="font-semibold text-foreground">{title}</p>
+				{description ? <p className="text-sm text-mute">{description}</p> : null}
+			</div>
+			{action}
+		</div>
+	);
+}