admin-ui-starter-kit 0.1.4 → 0.4.3

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

@@ -0,0 +1,826 @@
+---
+id: layout/layout-auth
+title: "Layout · Auth shell"
+description: "Framework-neutral auth card and split shells for login, register, invite, reset, magic-link, and verification pages."
+layer: layout
+family: "Shells"
+sourcePath: src/components/layout/auth
+examples:
+  - CenteredCardAuth
+  - LocalizedPatternCardAuth
+  - ProviderMatrixAuth
+  - ResetPasswordAuth
+  - SplitAuthShell
+  - RightSplitAuthShell
+  - FrameworkLinkContract
+imports:
+  - @/components/base/badge
+  - @/components/base/buttons
+  - @/components/base/display/alert
+  - @/components/base/forms
+  - @/components/layout
+  - @/components/layout/auth
+  - @/components/typography
+publicImport: admin-ui-starter-kit/layout/auth
+tags:
+  - layout
+  - shells
+  - auth
+  - shell
+  - framework
+  - neutral
+  - card
+---
+
+# Layout · Auth shell
+
+Framework-neutral auth card and split shells for login, register, invite, reset, magic-link, and verification pages.
+
+**Layer:** `layout`
+**Source:** `src/components/layout/auth`
+**Consumer import:** `admin-ui-starter-kit/layout/auth`
+
+## Consumer import
+
+Consumers import this surface from `admin-ui-starter-kit/layout/auth`.
+The examples below use repository source aliases because they run inside the preview app; do not copy those aliases into consuming applications.
+
+## Overview
+
+`AuthShell` owns the reusable auth chrome: centered card layout, split panel
+layout, brand area, full-bleed card media strip, social-provider buttons,
+language rows with a globe marker, policy/footer link rows, card header,
+after-card support copy, and footer slots. `AuthMethodSwitch` renders alternate
+login strategies as explicit buttons behind a divider, with controlled or
+uncontrolled state for magic-link, SSO, recovery, or any other consumer-owned
+auth state. The consuming app still owns the auth form, request action, route
+names, translations, language state, and framework link component.
+
+Use `renderLink` for every router-specific link. This is the same layout link
+contract used by header, sidebar, breadcrumbs, and page actions, so Inertia,
+Next, React Router, TanStack Router, or plain anchors stay app-owned.
+
+## Consumer usage
+
+```tsx
+import { AuthShell } from 'admin-ui-starter-kit/layout/auth';
+import { AuthMethodSwitch } from 'admin-ui-starter-kit/layout/auth';
+import { Button } from 'admin-ui-starter-kit/base/buttons';
+import { FormField, Input, PasswordInput } from 'admin-ui-starter-kit/base/forms';
+
+<AuthShell
+	brand={{ logo: <Logo />, label: 'Acme Admin', href: '/' }}
+	cardMedia={<PatternStrip />}
+	cardMediaClassName="h-16 min-h-16 overflow-hidden border-b-0 bg-transparent"
+	title="Sign in"
+	description="Use your company account to continue."
+	socialProviders={[
+		{ provider: 'google', label: 'Google', href: '/auth/google' },
+		{ provider: 'github', label: 'GitHub', href: '/auth/github' },
+	]}
+	footerLinks={[
+		{ label: 'Support', href: '/support' },
+	]}
+	policyLinks={[
+		{ label: 'Privacy', href: '/privacy' },
+		{ label: 'Terms', href: '/terms' },
+	]}
+	languageLinks={[
+		{ label: 'EN', href: '/locale/en' },
+		{ label: 'BG', href: '/locale/bg' },
+	]}
+	renderLink={({ href, children, className }) => (
+		<AppLink href={href ?? '#'} className={className}>{children}</AppLink>
+	)}
+>
+	<form onSubmit={submit}>
+		<FormField label="Email" required>
+			<Input type="email" autoComplete="email" />
+		</FormField>
+		<FormField label="Password" required>
+			<PasswordInput autoComplete="current-password" />
+		</FormField>
+		<Button type="submit" fullWidth>Continue</Button>
+		<AuthMethodSwitch
+			value={method === 'password' ? null : method}
+			onValueChange={setMethod}
+			options={[
+				{ id: 'magic-link', label: 'Email me a magic link' },
+				{ id: 'sso', label: 'Continue with company SSO' },
+			]}
+		/>
+	</form>
+</AuthShell>
+```
+
+## Examples
+
+```tsx
+import {
+	BarChart3,
+	Building2,
+	CheckCircle2,
+	Clock3,
+	Globe2,
+	KeyRound,
+	LockKeyhole,
+	MailCheck,
+	ShieldCheck,
+	Sparkles,
+	UsersRound,
+} from 'lucide-react';
+import { useState } from 'react';
+
+import { Badge } from '@/components/base/badge';
+import { Button } from '@/components/base/buttons';
+import { Alert, AlertAction, AlertDescription, AlertTitle } from '@/components/base/display/alert';
+import { Checkbox, FormField, Input, PasswordInput } from '@/components/base/forms';
+import type { LayoutLinkRenderProps } from '@/components/layout';
+import {
+	AuthFooterLinks,
+	AuthMethodSwitch,
+	AuthShell,
+	AuthSplitPanel,
+	type AuthLink,
+	type AuthMethodOption,
+	type AuthSocialProvider,
+} from '@/components/layout/auth';
+import { Text, TextLink } from '@/components/typography';
+
+const footerLinks: AuthLink[] = [
+	{ id: 'support', label: 'Support', href: '#/support' },
+	{ id: 'status', label: 'Status', href: 'https://status.example.com', external: true },
+];
+
+const policyLinks: AuthLink[] = [
+	{ id: 'privacy', label: 'Privacy', href: '#/privacy' },
+	{ id: 'terms', label: 'Terms', href: '#/terms' },
+];
+
+const languageLinks: AuthLink[] = [
+	{ id: 'en', label: 'EN', href: '#/locale/en' },
+	{ id: 'bg', label: 'BG', href: '#/locale/bg' },
+	{ id: 'el', label: 'EL', href: '#/locale/el' },
+];
+
+const socialProviders: AuthSocialProvider[] = [
+	{ id: 'google', provider: 'google', label: 'Google', href: '#/auth/google' },
+	{ id: 'github', provider: 'github', label: 'GitHub', href: '#/auth/github' },
+];
+
+const providerMatrix: AuthSocialProvider[] = [
+	{ id: 'google', provider: 'google', label: 'Google', href: '#/auth/google' },
+	{ id: 'github', provider: 'github', label: 'GitHub', href: '#/auth/github' },
+	{ id: 'microsoft', provider: 'microsoft', label: 'Microsoft', href: '#/auth/microsoft' },
+	{ id: 'apple', provider: 'apple', label: 'Apple', href: '#/auth/apple' },
+	{ id: 'sso', provider: 'sso', label: 'Company SSO', href: '#/auth/sso' },
+	{
+		id: 'custom',
+		provider: 'custom',
+		label: 'Magic link',
+		href: '#/auth/magic-link',
+		icon: <MailCheck className="size-4" aria-hidden="true" />,
+	},
+];
+
+type AuthDemoMethod = 'password' | 'magic-link' | 'sso' | 'forgot-password';
+
+const alternateAuthMethodOptions: AuthMethodOption[] = [
+	{
+		id: 'magic-link',
+		label: 'Email me a magic link',
+		description: 'Send a single-use sign-in link to the address above.',
+		icon: <MailCheck className="size-3.5" aria-hidden="true" />,
+	},
+	{
+		id: 'sso',
+		label: 'Continue with company SSO',
+		description: 'Use the identity provider configured by the host app.',
+		icon: <KeyRound className="size-3.5" aria-hidden="true" />,
+	},
+];
+
+function LogoMark() {
+	return (
+		<span className="flex size-9 items-center justify-center rounded-lg bg-foreground text-background">
+			<Building2 className="size-4" aria-hidden="true" />
+		</span>
+	);
+}
+
+function Wordmark() {
+	return (
+		<div className="flex flex-col items-center gap-1 text-center">
+			<Text tag="div" className="font-serif text-2xl leading-none tracking-normal text-foreground">
+				Gift come true
+			</Text>
+			<div className="h-px w-16 bg-foreground/40" />
+		</div>
+	);
+}
+
+function renderPreviewLink({
+	href,
+	children,
+	className,
+	target,
+	rel,
+	onClick,
+}: LayoutLinkRenderProps) {
+	return (
+		<a href={href ?? '#'} className={className} target={target} rel={rel} onClick={onClick}>
+			{children}
+		</a>
+	);
+}
+
+function PatternStrip() {
+	return (
+		<div className="relative h-full min-h-16 overflow-hidden">
+			<div className="absolute inset-0 bg-info/15" />
+			<div className="absolute -left-8 top-0 h-24 w-24 rotate-45 border-[10px] border-info/70" />
+			<div className="absolute left-20 -top-6 h-28 w-16 rotate-12 bg-warning/75" />
+			<div className="absolute left-44 top-3 h-20 w-28 rotate-[-18deg] border-[10px] border-success/70" />
+			<div className="absolute right-20 -top-4 h-24 w-12 rotate-45 bg-info/70" />
+			<div className="absolute right-0 top-0 h-20 w-24 rotate-12 border-[10px] border-warning/80" />
+			<div className="absolute inset-x-0 bottom-0 h-3 bg-foreground/80" />
+		</div>
+	);
+}
+
+function DensePatternStrip() {
+	return (
+		<div className="relative h-full min-h-16 overflow-hidden bg-foreground">
+			<div className="absolute left-0 top-0 h-full w-20 border-e-8 border-warning bg-info/80" />
+			<div className="absolute left-14 top-0 h-24 w-24 rotate-45 border-[10px] border-success" />
+			<div className="absolute left-36 -top-4 h-28 w-16 rotate-12 bg-warning" />
+			<div className="absolute left-52 top-4 h-20 w-32 rotate-[-18deg] border-[10px] border-info" />
+			<div className="absolute right-24 -top-2 h-24 w-20 rotate-45 bg-success" />
+			<div className="absolute right-0 top-0 h-20 w-28 rotate-12 border-[10px] border-warning" />
+		</div>
+	);
+}
+
+function LoginForm() {
+	const [method, setMethod] = useState<AuthDemoMethod>('password');
+	const alternateOptions = alternateAuthMethodOptions.filter((option) => option.id !== method);
+
+	return (
+		<div className="grid gap-4">
+			{method === 'password' && (
+				<form className="grid gap-4" aria-label="Password sign in">
+					<FormField label="Email" required>
+						<Input type="email" placeholder="you@company.com" autoComplete="email" />
+					</FormField>
+
+					<FormField label="Password" required>
+						<PasswordInput
+							placeholder="Enter your password"
+							autoComplete="current-password"
+							startIcon={LockKeyhole}
+						/>
+					</FormField>
+
+					<div className="flex items-center justify-between gap-3">
+						<label className="flex min-w-0 items-center gap-2">
+							<Checkbox aria-label="Remember this device" />
+							<Text tag="span" size="xs">
+								Remember this device
+							</Text>
+						</label>
+						<Button
+							type="button"
+							size="xs"
+							variant="action"
+							buttonStyle="ghost"
+							className="h-auto px-1 py-0"
+							onClick={() => setMethod('forgot-password')}
+						>
+							Forgot password?
+						</Button>
+					</div>
+
+					<Button type="submit" fullWidth>
+						Sign in
+					</Button>
+
+					<AuthMethodSwitch
+						options={alternateOptions}
+						value={null}
+						onValueChange={(nextValue) => setMethod(nextValue as AuthDemoMethod)}
+					/>
+				</form>
+			)}
+
+			{method === 'magic-link' && (
+				<form className="grid gap-4" aria-label="Magic link sign in">
+					<FormField label="Work email" hint="We will send a single-use link that expires in 15 minutes." required>
+						<Input type="email" placeholder="you@company.com" autoComplete="email" startIcon={MailCheck} />
+					</FormField>
+
+					<Button type="submit" fullWidth>
+						Send magic link
+					</Button>
+					<Button
+						type="button"
+						variant="secondary"
+						buttonStyle="outline"
+						fullWidth
+						onClick={() => setMethod('password')}
+					>
+						Use password instead
+					</Button>
+
+					<AuthMethodSwitch
+						options={alternateOptions}
+						value={null}
+						onValueChange={(nextValue) => setMethod(nextValue as AuthDemoMethod)}
+					/>
+				</form>
+			)}
+
+			{method === 'sso' && (
+				<form className="grid gap-4" aria-label="SSO sign in">
+					<FormField label="Company domain" hint="Route the user to the provider owned by the host app." required>
+						<Input type="text" placeholder="northwind.com" autoComplete="organization" startIcon={Globe2} />
+					</FormField>
+
+					<Button type="submit" fullWidth>
+						Continue with SSO
+					</Button>
+					<Button
+						type="button"
+						variant="secondary"
+						buttonStyle="outline"
+						fullWidth
+						onClick={() => setMethod('password')}
+					>
+						Use password instead
+					</Button>
+
+					<AuthMethodSwitch
+						options={alternateOptions}
+						value={null}
+						onValueChange={(nextValue) => setMethod(nextValue as AuthDemoMethod)}
+					/>
+				</form>
+			)}
+
+			{method === 'forgot-password' && (
+				<div className="grid gap-4" aria-label="Forgot password">
+					<Alert variant="info">
+						<AlertTitle>Password reset</AlertTitle>
+						<AlertDescription>
+							Send a recovery link without leaving the auth shell or changing routes first.
+						</AlertDescription>
+					</Alert>
+					<form className="grid gap-4">
+						<FormField label="Account email" hint="Use the email connected to your workspace." required>
+							<Input type="email" placeholder="you@company.com" autoComplete="email" />
+						</FormField>
+
+						<Button type="submit" fullWidth>
+							Send reset link
+						</Button>
+					</form>
+					<Button
+						type="button"
+						variant="secondary"
+						buttonStyle="outline"
+						fullWidth
+						onClick={() => setMethod('password')}
+					>
+						Back to password sign in
+					</Button>
+				</div>
+			)}
+		</div>
+	);
+}
+
+function LocalizedLoginForm() {
+	return (
+		<form className="grid gap-4">
+			<FormField label="Имейл" required>
+				<Input type="email" placeholder="you@company.com" autoComplete="email" />
+			</FormField>
+
+			<FormField label="Парола" required>
+				<PasswordInput
+					placeholder="Въведете парола"
+					autoComplete="current-password"
+					startIcon={LockKeyhole}
+					strings={{
+						showPassword: 'Покажи паролата',
+						hidePassword: 'Скрий паролата',
+					}}
+				/>
+			</FormField>
+
+			<Button type="submit" fullWidth>
+				Вход
+			</Button>
+		</form>
+	);
+}
+
+function InviteForm() {
+	return (
+		<form className="grid gap-4">
+			<FormField label="Work email" hint="Use the email address that received the invite." required>
+				<Input type="email" placeholder="you@company.com" autoComplete="email" startIcon={Globe2} />
+			</FormField>
+
+			<FormField label="Password" hint="Minimum 12 characters." required>
+				<PasswordInput placeholder="Create a password" autoComplete="new-password" startIcon={KeyRound} />
+			</FormField>
+
+			<Button type="submit" fullWidth>
+				Accept invite
+			</Button>
+		</form>
+	);
+}
+
+function OneTimeCodeForm() {
+	return (
+		<form className="grid gap-4">
+			<FormField label="Work email" hint="We will send a secure one-time code.">
+				<Input type="email" placeholder="admin@company.com" autoComplete="email" />
+			</FormField>
+			<Button type="submit" fullWidth>
+				Send code
+			</Button>
+		</form>
+	);
+}
+
+function ResetPasswordForm() {
+	return (
+		<form className="grid gap-4">
+			<FormField label="New password" hint="Use at least 12 characters." required>
+				<PasswordInput autoComplete="new-password" placeholder="Create a new password" />
+			</FormField>
+			<FormField label="Confirm password" required>
+				<PasswordInput autoComplete="new-password" placeholder="Repeat password" />
+			</FormField>
+			<Button type="submit" fullWidth>
+				Update password
+			</Button>
+		</form>
+	);
+}
+
+function MetricsPreview() {
+	const rows = [
+		{ label: 'Orders protected', value: '18.4k', icon: ShieldCheck },
+		{ label: 'Team seats', value: '42', icon: UsersRound },
+		{ label: 'Risk checks', value: '99.9%', icon: BarChart3 },
+	];
+
+	return (
+		<div className="grid gap-3 p-4">
+			<div className="rounded-md border border-border/60 bg-card p-4">
+				<div className="flex items-center justify-between gap-3">
+					<div>
+						<Text size="xs" type="secondary">
+							Last 30 days
+						</Text>
+						<Text tag="div" weight="semibold">
+							Operational overview
+						</Text>
+					</div>
+					<Badge variant="success">Live</Badge>
+				</div>
+				<div className="mt-4 flex h-24 items-end gap-1.5">
+					{[34, 42, 31, 52, 48, 66, 58, 72, 63, 76, 68, 84].map((height, index) => (
+						<span
+							key={index}
+							className="flex-1 rounded-t bg-info/70"
+							style={{ height: `${height}%` }}
+						/>
+					))}
+				</div>
+			</div>
+
+			<div className="grid gap-2 sm:grid-cols-3">
+				{rows.map((row) => {
+					const Icon = row.icon;
+					return (
+						<div key={row.label} className="rounded-md border border-border/60 bg-background/80 p-3">
+							<Icon className="mb-2 size-4 text-muted-foreground" aria-hidden="true" />
+							<Text tag="div" weight="semibold">
+								{row.value}
+							</Text>
+							<Text size="xs" type="secondary">
+								{row.label}
+							</Text>
+						</div>
+					);
+				})}
+			</div>
+		</div>
+	);
+}
+
+function InvitePanel() {
+	return (
+		<AuthSplitPanel
+			surface="card"
+			eyebrow="Workspace access"
+			title="Secure onboarding for every admin account."
+			description="Use the shell for visual context and trust signals while the app owns the actual auth action, translations, and routing."
+			media={<MetricsPreview />}
+			className="rounded-lg shadow-sm"
+			contentClassName="gap-6 p-5 md:p-7 lg:p-8"
+			features={[
+				{
+					id: 'approval',
+					icon: <CheckCircle2 className="size-4" aria-hidden="true" />,
+					title: 'Approval-aware sessions',
+					description: 'Invite, verification, and review states stay visible without crowding the form.',
+				},
+				{
+					id: 'audit',
+					icon: <Clock3 className="size-4" aria-hidden="true" />,
+					title: 'Audit-friendly copy',
+					description: 'Use concise admin language and keep framework routes at the call site.',
+				},
+			]}
+			footer={
+				<div className="flex flex-wrap items-center justify-between gap-3">
+					<Text size="xs" type="secondary">
+						Trusted by finance, operations, and support teams.
+					</Text>
+					<Badge variant="success">SOC2 ready</Badge>
+				</div>
+			}
+		/>
+	);
+}
+
+export function CenteredCardAuth() {
+	return (
+		<AuthShell
+			brand={{
+				logo: <LogoMark />,
+				label: 'Northwind Admin',
+				description: 'Operations console',
+				href: '#/',
+				ariaLabel: 'Northwind Admin home',
+			}}
+			title="Sign in to your workspace"
+			description="Use your company account to continue."
+			banner={
+				<Alert variant="info">
+					<AlertTitle>Single sign-on is available</AlertTitle>
+					<AlertDescription>Company domains can sign in with Google or email.</AlertDescription>
+					<AlertAction>
+						<Button size="xs" variant="action" buttonStyle="ghost">
+							Learn more
+						</Button>
+					</AlertAction>
+				</Alert>
+			}
+			socialProviders={socialProviders}
+			socialProvidersLayout="grid"
+			socialDivider="or use email"
+			cardFooter={
+				<Text size="xs" type="secondary">
+					New to Northwind? <TextLink href="#/register" size="xs">Request access</TextLink>
+				</Text>
+			}
+			postCard={
+				<Text size="xs" type="secondary">
+					Protected by device verification and audit logging.
+				</Text>
+			}
+			footerLinks={footerLinks}
+			policyLinks={policyLinks}
+			languageLinks={languageLinks}
+			renderLink={renderPreviewLink}
+		>
+			<LoginForm />
+		</AuthShell>
+	);
+}
+
+export function LocalizedPatternCardAuth() {
+	return (
+		<AuthShell
+			size="md"
+			brand={<Wordmark />}
+			cardMedia={<DensePatternStrip />}
+			cardMediaClassName="h-16 min-h-16 overflow-hidden border-b-0 bg-transparent"
+			title="Влезте в акаунта си"
+			description="Въведете вашите данни, за да получите достъп до таблото."
+			cardFooter={
+				<Text size="xs" type="secondary">
+					Нямате достъп? <TextLink href="#/request-access" size="xs">Заявете покана</TextLink>
+				</Text>
+			}
+			languageLinks={[
+				{ id: 'bg', label: 'Български', href: '#/locale/bg' },
+				{ id: 'en', label: 'English', href: '#/locale/en' },
+			]}
+			policyLinks={policyLinks}
+			renderLink={renderPreviewLink}
+			strings={{
+				languageLinksLabel: 'Език',
+				policyLinksLabel: 'Правила',
+			}}
+		>
+			<LocalizedLoginForm />
+		</AuthShell>
+	);
+}
+
+export function ProviderMatrixAuth() {
+	return (
+		<AuthShell
+			brand={{
+				logo: <LogoMark />,
+				label: 'Northwind Admin',
+				description: 'Identity gateway',
+				href: '#/',
+			}}
+			title="Choose a sign-in method"
+			description="Route every provider through the host app while keeping the button layout consistent."
+			socialProviders={providerMatrix}
+			socialProvidersLayout="grid"
+			socialDivider="or send a one-time code"
+			footerLinks={footerLinks}
+			policyLinks={policyLinks}
+			renderLink={renderPreviewLink}
+		>
+			<OneTimeCodeForm />
+		</AuthShell>
+	);
+}
+
+export function ResetPasswordAuth() {
+	return (
+		<AuthShell
+			size="sm"
+			brand={{ logo: <LogoMark />, label: 'Northwind Admin', href: '#/' }}
+			title="Reset your password"
+			description="Choose a new password for marina@northwind.test."
+			banner={
+				<Alert variant="warning">
+					<AlertTitle>Reset link expires soon</AlertTitle>
+					<AlertDescription>For security, this link is valid for another 12 minutes.</AlertDescription>
+				</Alert>
+			}
+			cardFooter={
+				<Text size="xs" type="secondary">
+					Remembered it? <TextLink href="#/login" size="xs">Back to sign in</TextLink>
+				</Text>
+			}
+			policyLinks={policyLinks}
+			renderLink={renderPreviewLink}
+		>
+			<ResetPasswordForm />
+		</AuthShell>
+	);
+}
+
+export function SplitAuthShell() {
+	return (
+		<AuthShell
+			variant="split"
+			size="md"
+			splitSide="left"
+			splitMobile="stacked"
+			className="bg-muted/20"
+			splitPanelClassName="p-3 lg:p-6"
+			brand={{
+				logo: <LogoMark />,
+				label: 'Northwind Admin',
+				href: '#/',
+			}}
+			cardMedia={<PatternStrip />}
+			cardMediaClassName="h-16 min-h-16 overflow-hidden border-b-0 bg-transparent"
+			eyebrow="Team invite"
+			title="Create your admin account"
+			description="Accept the invite and configure your first secure session."
+			headerEnd={<Badge variant="warning">Invite</Badge>}
+			splitPanel={<InvitePanel />}
+			cardFooter={
+				<Text size="xs" type="secondary">
+					Already joined? <TextLink href="#/login" size="xs">Sign in</TextLink>
+				</Text>
+			}
+			footerLinks={footerLinks}
+			policyLinks={policyLinks}
+			renderLink={renderPreviewLink}
+		>
+			<InviteForm />
+		</AuthShell>
+	);
+}
+
+export function RightSplitAuthShell() {
+	return (
+		<AuthShell
+			variant="split"
+			size="sm"
+			splitSide="right"
+			className="bg-muted/20"
+			splitPanelClassName="p-3 lg:p-6"
+			splitPanel={{
+				surface: 'card',
+				className: 'rounded-lg shadow-sm',
+				contentClassName: 'gap-6 p-5 md:p-7 lg:p-8',
+				eyebrow: 'Access policy',
+				title: 'Passwordless flows use the same shell.',
+				description: 'Magic-link, verification, reset-password, and two-factor pages can reuse the same card and after-card areas.',
+				features: [
+					{
+						id: 'configurable',
+						icon: <Sparkles className="size-4" aria-hidden="true" />,
+						title: 'Configurable chrome',
+						description: 'Brand, media, footer links, panel, and post-card copy are all slots.',
+					},
+					{
+						id: 'framework',
+						icon: <ShieldCheck className="size-4" aria-hidden="true" />,
+						title: 'Framework-neutral links',
+						description: 'Pass renderLink once and the shell uses the host router component.',
+					},
+				],
+			}}
+			brand={{ logo: <LogoMark />, label: 'Northwind Admin', href: '#/' }}
+			title="Check your email"
+			description="We sent a one-time sign-in link to marina@northwind.test."
+			footerLinks={footerLinks}
+			policyLinks={policyLinks}
+			languageSwitcher={
+				<Button size="xs" variant="secondary" buttonStyle="outline">
+					English
+				</Button>
+			}
+			renderLink={renderPreviewLink}
+		>
+			<div className="grid gap-4">
+				<Alert variant="success">
+					<AlertTitle>Magic link sent</AlertTitle>
+					<AlertDescription>The link expires in 15 minutes.</AlertDescription>
+				</Alert>
+				<Button fullWidth>Open mail app</Button>
+				<Button variant="secondary" buttonStyle="outline" fullWidth>
+					Resend link
+				</Button>
+			</div>
+		</AuthShell>
+	);
+}
+
+export function FrameworkLinkContract() {
+	const adapter = ({
+		href,
+		children,
+		className,
+		target,
+		rel,
+		onClick,
+	}: LayoutLinkRenderProps) => (
+		<a
+			href={href ?? '#'}
+			className={className}
+			target={target}
+			rel={rel}
+			onClick={onClick}
+			data-router-link="example"
+		>
+			{children}
+		</a>
+	);
+
+	return (
+		<div className="max-w-md rounded-lg border border-dashed border-border p-6">
+			<Text tag="div" weight="semibold">
+				Footer links use the host router
+			</Text>
+			<Text size="xs" type="secondary" className="mt-1">
+				The package never imports Inertia, Next, React Router, or TanStack Router.
+			</Text>
+			<AuthFooterLinks
+				className="mt-4 justify-start"
+				links={footerLinks}
+				renderLink={adapter}
+			/>
+		</div>
+	);
+}
+```
+
+## Example exports
+
+- `CenteredCardAuth`
+- `LocalizedPatternCardAuth`
+- `ProviderMatrixAuth`
+- `ResetPasswordAuth`
+- `SplitAuthShell`
+- `RightSplitAuthShell`
+- `FrameworkLinkContract`
+