@sableui/react 0.1.1 → 0.3.0

package/llms/blocks/product-card-block.md

@@ -0,0 +1,69 @@
+# ProductCardBlock
+
+A product card: edge-to-edge artwork, title and maker, an edition Badge, and the price beside a single buy action.
+
+**Intent:** Reach for this for a product, edition or listing in a grid or a featured slot. For a row in a dense list, use an Entity with the image as `leading` instead.
+
+**Block:** Commerce · card · designed for 16rem–20rem wide (fills its container up to the max)
+
+## Notes
+
+- The artwork runs to the card's edges; the card clips it to its own corners (overflow-hidden).
+- Prices are `text-mono-lg` — the metric mono tier with tabular figures — never a heading tier.
+- The placeholder art is painted from the palette's decorative tones so it follows the theme; swap it for the product image with real alt text.
+
+## Accessibility
+
+- The placeholder art is aria-hidden. A real product image needs alt text naming the product.
+- The card is not a link: it holds its own button. To make the whole card navigate, move the action to the detail page and render the Card as an <a>.
+
+## Source
+
+```tsx
+import { Badge, Button, Card, CardAction, CardDescription, CardFooter, CardHeader, CardTitle, cn } from "@sableui/react"
+
+const product = { title: "Untitled (gold rush)", maker: "Mara Okafor", edition: "12 of 50", price: "0.42 SOL" }
+
+/**
+ * Placeholder artwork painted from the palette — a soft mesh of the theme's
+ * decorative tones over the brand, so it follows every look. Replace the art
+ * <div> with your product's image.
+ */
+const ART_TONES = ["info", "collectible", "edition", "standard"]
+const ART_SPOTS = [[18, 22, 58], [82, 18, 55], [70, 88, 60], [12, 92, 55]]
+const artwork = [
+	...ART_SPOTS.map(
+		([x, y, reach], i) =>
+			// design-lint-disable-next-line inline-color -- relative colour derived from the theme's own --tone token, so it follows every look
+			`radial-gradient(in oklab at ${x}% ${y}%, oklch(from var(--tone-${ART_TONES[i % ART_TONES.length]}) clamp(0.5, calc(l + 0.16), 0.9) max(calc(c * 1.25), 0.1) h), transparent ${reach}%)`,
+	),
+	"var(--primary)",
+].join(", ")
+
+export interface ProductCardBlockProps {
+	className?: string
+	/** false drops the card's surface and border — for a muted section that already frames it. */
+	framed?: boolean
+	/** The buy action. */
+	onCollect?: () => void
+}
+
+export function ProductCardBlock({ className, framed = true, onCollect }: ProductCardBlockProps) {
+	return (
+		<Card variant={framed ? "default" : "flat"} className={cn("w-full max-w-xs overflow-hidden", className)}>
+			<div aria-hidden className="aspect-[4/3]" style={{ background: artwork }} />
+			<CardHeader>
+				<CardTitle>{product.title}</CardTitle>
+				<CardDescription>{product.maker}</CardDescription>
+				<CardAction>
+					<Badge tone="edition">{product.edition}</Badge>
+				</CardAction>
+			</CardHeader>
+			<CardFooter className="justify-between pt-4">
+				<span className="text-mono-lg">{product.price}</span>
+				<Button onClick={onCollect}>Collect</Button>
+			</CardFooter>
+		</Card>
+	)
+}
+```

package/llms/blocks/profile-card-block.md

@@ -0,0 +1,103 @@
+# ProfileCardBlock
+
+A profile card: a cover banner, an avatar rising into it, Share and Follow, the name and handle, a one-line bio and two counts.
+
+**Intent:** Reach for this for a person or creator summary — a suggested-follow card, a hover target's full view, the top of a profile sidebar. For a small inline preview on hover, use ContextCard; for a row in a list of people, use Entity.
+
+**Block:** Social & messaging · card · designed for 18rem–20rem wide (fills its container up to the max)
+
+## Notes
+
+- The avatar overlaps the banner by half its height with a ring in the card colour, so it reads as sitting on the card, not pasted over the art.
+- Follow is the one primary action and flips to a secondary Following once pressed; Share is an icon-only ghost Button beside it.
+- Counts pair a label-tier number with muted body text, so the numbers scan as a row.
+
+## Accessibility
+
+- The Share button carries aria-label; Follow's visible text changes with its state.
+- The banner is decorative (aria-hidden); the Avatar's alt is the person's name.
+
+## Source
+
+```tsx
+import { useState } from "react"
+import { Avatar, Button, Card, CardContent, CardDescription, CardTitle, cn, Icon } from "@sableui/react"
+
+const profile = {
+	name: "Juno Avery",
+	initials: "JA",
+	handle: "@juno · Sound and light",
+	bio: "Field recordings, slowed down. New edition every full moon.",
+	stats: [
+		{ value: "128", label: "posts" },
+		{ value: "4.2k", label: "followers" },
+	],
+}
+
+/**
+ * Placeholder banner painted from the palette — the theme's decorative tones
+ * over the brand, so it follows every look. Replace with the person's cover image.
+ */
+const ART_TONES = ["info", "collectible", "edition", "standard"]
+const ART_SPOTS = [[10, 50, 60], [50, 0, 55], [90, 60, 60], [40, 100, 50]]
+const banner = [
+	...ART_SPOTS.map(
+		([x, y, reach], i) =>
+			// design-lint-disable-next-line inline-color -- relative colour derived from the theme's own --tone token, so it follows every look
+			`radial-gradient(in oklab at ${x}% ${y}%, oklch(from var(--tone-${ART_TONES[i % ART_TONES.length]}) clamp(0.5, calc(l + 0.16), 0.9) max(calc(c * 1.25), 0.1) h), transparent ${reach}%)`,
+	),
+	"var(--primary)",
+].join(", ")
+
+export interface ProfileCardBlockProps {
+	className?: string
+	/** false drops the card's surface and border — for a muted section that already frames it. */
+	framed?: boolean
+	/** Called with the new follow state. */
+	onFollowChange?: (following: boolean) => void
+	onShare?: () => void
+}
+
+export function ProfileCardBlock({ className, framed = true, onFollowChange, onShare }: ProfileCardBlockProps) {
+	const [following, setFollowing] = useState(false)
+	return (
+		<Card variant={framed ? "default" : "flat"} className={cn("w-full max-w-xs overflow-hidden", className)}>
+			<div aria-hidden className="h-20" style={{ background: banner }} />
+			{/* pt-0: the avatar rises into the banner above, so the content
+			    starts at the banner's edge rather than a full pad below it. */}
+			<CardContent className="flex flex-col gap-3 pt-0">
+				<div className="flex items-start justify-between">
+					<Avatar size="lg" fallback={profile.initials} alt={profile.name} className="-mt-6 ring-4 ring-card" />
+					<div className="flex gap-1.5 pt-3">
+						<Button variant="ghost" size="icon-sm" aria-label="Share profile" onClick={onShare}>
+							<Icon name="share" />
+						</Button>
+						<Button
+							size="sm"
+							variant={following ? "secondary" : "primary"}
+							onClick={() => {
+								setFollowing(!following)
+								onFollowChange?.(!following)
+							}}
+						>
+							{following ? "Following" : "Follow"}
+						</Button>
+					</div>
+				</div>
+				<div className="flex flex-col gap-0.5">
+					<CardTitle>{profile.name}</CardTitle>
+					<CardDescription>{profile.handle}</CardDescription>
+				</div>
+				<p className="text-body-sm">{profile.bio}</p>
+				<div className="flex gap-4 text-body-sm">
+					{profile.stats.map((s) => (
+						<span key={s.label}>
+							<span className="text-label-lg">{s.value}</span> <span className="text-muted-foreground">{s.label}</span>
+						</span>
+					))}
+				</div>
+			</CardContent>
+		</Card>
+	)
+}
+```

package/llms/blocks/profile-form-block.md

@@ -0,0 +1,114 @@
+# ProfileFormBlock
+
+A profile settings card: avatar with upload/remove, name and handle side by side, a bio, a timezone Select, and one Save profile in the footer.
+
+**Intent:** Reach for this for the profile or account section of settings, or any form of drafted text that is committed together. Toggles that apply instantly belong in NotificationSettingsBlock, never behind this Save.
+
+**Block:** Settings & team · card · designed for 20rem–42rem wide (fills its container up to the max)
+
+## Notes
+
+- Copied from the SettingsPage page shell's Profile section; the shell keeps its own copy so it stays one self-contained file.
+- One explicit save for the whole card. Short pairs (name + handle) sit side by side from sm up with Grid cols={{ base: 1, sm: 2 }}.
+- The CardTitle renders an h2, so the section joins the page outline under its h1.
+
+## Accessibility
+
+- Field wires label, description and error to each control; the handle's URL preview is its description.
+- The photo actions are type="button", so neither one submits the form.
+
+## Source
+
+```tsx
+import { Avatar, Button, Card, CardContent, CardDescription, CardFooter, CardHeader, CardTitle, cn, Field, Form, Grid, Input, Row, Select, SelectContent, SelectItem, SelectTrigger, Stack, Textarea } from "@sableui/react"
+
+const profile = {
+	name: "Ada Lovelace",
+	initials: "AL",
+	handle: "ada",
+	bio: "Generative artist working in plotted ink and code. New editions of 25 to 100 every month.",
+	timezone: "europe-london",
+}
+
+const timezones = [
+	{ value: "europe-london", label: "London (GMT+1)" },
+	{ value: "europe-paris", label: "Paris (GMT+2)" },
+	{ value: "america-new-york", label: "New York (GMT−4)" },
+	{ value: "america-los-angeles", label: "Los Angeles (GMT−7)" },
+	{ value: "asia-tokyo", label: "Tokyo (GMT+9)" },
+]
+
+export interface ProfileFormBlockProps {
+	className?: string
+	/** false drops the card's surface and border — for a muted section that already frames it. */
+	framed?: boolean
+	/** Called with the form's fields on Save profile. */
+	onSave?: (fields: FormData) => void
+}
+
+export function ProfileFormBlock({ className, framed = true, onSave }: ProfileFormBlockProps) {
+	return (
+		<Card variant={framed ? "default" : "flat"} className={cn("w-full max-w-2xl", className)}>
+			<CardHeader>
+				<CardTitle render={<h2 />}>Profile</CardTitle>
+				<CardDescription>How collectors see you.</CardDescription>
+			</CardHeader>
+			{/* The one explicit save: profile text is drafted, then committed. */}
+			<Form
+				className="gap-0"
+				onSubmit={(event) => {
+					event.preventDefault()
+					onSave?.(new FormData(event.currentTarget))
+				}}
+			>
+				<CardContent>
+					<Stack gap={3}>
+						<Row gap={2}>
+							<Avatar size="lg" fallback={profile.initials} alt={profile.name} />
+							<Stack gap={0.5} align="start">
+								<Row gap={1}>
+									<Button type="button" variant="outline" size="sm">
+										Upload photo
+									</Button>
+									<Button type="button" variant="ghost" size="sm">
+										Remove
+									</Button>
+								</Row>
+								<p className="text-caption text-muted-foreground">Square PNG or JPG, at least 400 px.</p>
+							</Stack>
+						</Row>
+						<Grid cols={{ base: 1, sm: 2 }} gap={3}>
+							<Field label="Display name" name="displayName" required>
+								<Input defaultValue={profile.name} autoComplete="name" />
+							</Field>
+							<Field label="Handle" name="handle" description={`atelier.com/@${profile.handle}`} required>
+								<Input defaultValue={profile.handle} autoComplete="username" spellCheck={false} />
+							</Field>
+						</Grid>
+						<Field label="Bio" name="bio" description="Shown on your profile and edition pages.">
+							<Textarea rows={3} defaultValue={profile.bio} />
+						</Field>
+						<Grid cols={{ base: 1, sm: 2 }} gap={3}>
+							<Field label="Timezone" name="timezone" description="Release times use this zone.">
+								<Select defaultValue={profile.timezone} items={timezones}>
+									<SelectTrigger />
+									<SelectContent>
+										{timezones.map((zone) => (
+											<SelectItem key={zone.value} value={zone.value}>
+												{zone.label}
+											</SelectItem>
+										))}
+									</SelectContent>
+								</Select>
+							</Field>
+						</Grid>
+					</Stack>
+				</CardContent>
+				<CardFooter className="justify-end">
+					<Button type="submit">Save profile</Button>
+				</CardFooter>
+			</Form>
+		</Card>
+	)
+}
+```

package/llms/blocks/revenue-breakdown-block.md

@@ -0,0 +1,70 @@
+# RevenueBreakdownBlock
+
+A stat card with a breakdown: the KPI in the metric mono tier, its trend Badge, a SegmentedBar of how the total divides, and a StatusDot legend.
+
+**Intent:** Reach for this when a headline number is worth splitting into a few categories — revenue by product, storage by type, tickets by priority. A plain KPI with no split is a smaller stat card (see DashboardPage's stat row).
+
+**Block:** Dashboard · card · designed for 18rem–20rem wide (fills its container up to the max)
+
+## Notes
+
+- The value is `text-mono-xl` — tabular figures, never a heading tier — and the label above it is CardDescription.
+- The legend reflows from two columns to one by measuring in em, so larger type or a narrower card never truncates a label.
+- Each category keeps the same tone in the bar and its legend dot; reuse those tones wherever the category appears.
+
+## Accessibility
+
+- The SegmentedBar is one image whose name reads every share; the legend repeats it visually and is aria-hidden so it is not announced twice.
+- The trend Badge states the change as text (+8.2%), not by colour.
+
+## Source
+
+```tsx
+import { Badge, Card, CardAction, CardContent, CardDescription, CardHeader, cn, Grid, SegmentedBar, StatusDot } from "@sableui/react"
+
+const revenue = { label: "Revenue this month", total: "$12,480", change: "+8.2%" }
+
+const segments = [
+	{ label: "Editions", value: 42, tone: "edition" },
+	{ label: "Collectibles", value: 27, tone: "collectible" },
+	{ label: "Standard", value: 19, tone: "standard" },
+	{ label: "Commissions", value: 12, tone: "info" },
+] as const
+
+export interface RevenueBreakdownBlockProps {
+	className?: string
+	/** false drops the card's surface and border — for a muted section that already frames it. */
+	framed?: boolean
+}
+
+export function RevenueBreakdownBlock({ className, framed = true }: RevenueBreakdownBlockProps) {
+	return (
+		<Card variant={framed ? "default" : "flat"} className={cn("w-full max-w-xs", className)}>
+			<CardHeader>
+				<CardDescription>{revenue.label}</CardDescription>
+				<CardAction>
+					<Badge tone="success" size="sm">
+						{revenue.change}
+					</Badge>
+				</CardAction>
+			</CardHeader>
+			<CardContent className="flex flex-col gap-4 pt-2">
+				<span className="text-mono-xl">{revenue.total}</span>
+				<SegmentedBar label="Revenue by type" segments={[...segments]} size="lg" />
+				{/* Two columns while each entry fits whole, one when they would not:
+				    sized in em, so a larger type or a narrower card drops to one.
+				    aria-hidden: the bar already reads every share aloud. */}
+				<Grid aria-hidden minItemWidth="9.5em" gap="calc(var(--spacing) * 1.5) calc(var(--spacing) * 4)">
+					{segments.map((s) => (
+						<div key={s.label} className="flex items-center gap-2 text-body-sm">
+							<StatusDot tone={s.tone} />
+							<span className="flex-1 text-muted-foreground">{s.label}</span>
+							<span className="text-mono-caption">{s.value}%</span>
+						</div>
+					))}
+				</Grid>
+			</CardContent>
+		</Card>
+	)
+}
+```

package/llms/blocks/sign-in-block.md

@@ -0,0 +1,64 @@
+# SignInBlock
+
+A sign-in card: email and password, a primary Sign in, and a passkey alternative under an "or" separator.
+
+**Intent:** Reach for this wherever someone signs in inside a surface you already have — a Sheet, a Dialog, a gated panel. For a whole sign-in route with brand art beside the form, start from the AuthPage page shell instead.
+
+**Block:** Auth · card · designed for 18rem–20rem wide (fills its container up to the max)
+
+## Notes
+
+- One primary action. The passkey is an outline Button under a labelled Separator, so it reads as an alternative, not a second submit.
+- The fields are a real <form>: Enter submits, and the browser's password manager recognises the autocomplete hints.
+- framed={false} keeps the padding and drops the surface, for a Sheet or Dialog that is already the frame.
+
+## Accessibility
+
+- Inputs carry aria-label because the design shows placeholders, not visible labels; add Field labels if your brief wants them visible.
+- `onSignIn` receives "password" or "passkey", so focus and error handling stay with the caller's auth flow.
+
+## Source
+
+```tsx
+import { Button, Card, CardContent, CardDescription, CardHeader, CardTitle, cn, Icon, Input, Separator } from "@sableui/react"
+
+export interface SignInBlockProps {
+	className?: string
+	/** false drops the card's surface and border — for a Sheet, Dialog or muted section that already frames it. */
+	framed?: boolean
+	/** Called with the method the person chose. Wire your auth here. */
+	onSignIn?: (method: "password" | "passkey") => void
+}
+
+export function SignInBlock({ className, framed = true, onSignIn }: SignInBlockProps) {
+	return (
+		<Card variant={framed ? "default" : "flat"} className={cn("w-full max-w-xs", className)}>
+			<CardHeader>
+				<CardTitle>Welcome back</CardTitle>
+				<CardDescription>Sign in to pick up where you left off.</CardDescription>
+			</CardHeader>
+			<CardContent>
+				<form
+					className="flex flex-col gap-4"
+					onSubmit={(event) => {
+						event.preventDefault()
+						onSignIn?.("password")
+					}}
+				>
+					<div className="flex flex-col gap-2">
+						<Input name="email" type="email" autoComplete="email" placeholder="you@studio.com" aria-label="Email" />
+						<Input name="password" type="password" autoComplete="current-password" placeholder="Password" aria-label="Password" />
+					</div>
+					<Button type="submit" className="w-full">
+						Sign in
+					</Button>
+					<Separator label="or" />
+					<Button variant="outline" className="w-full" iconStart={<Icon name="lock" />} onClick={() => onSignIn?.("passkey")}>
+						Use a passkey
+					</Button>
+				</form>
+			</CardContent>
+		</Card>
+	)
+}
+```

package/llms/blocks/sign-up-block.md

@@ -0,0 +1,78 @@
+# SignUpBlock
+
+A sign-up card: name, work email and password as labelled Fields, one full-width Create account, and a link to sign in instead.
+
+**Intent:** Reach for this to create an account inside a surface you already have, or as the form of a sign-up route. For the whole route with brand art beside it, start from the AuthPage page shell and drop this card in.
+
+**Block:** Auth · card · designed for 18rem–24rem wide (fills its container up to the max)
+
+## Notes
+
+- Visible labels, not placeholders: someone filling a new form needs to see what each field is after typing in it.
+- The password rule is stated up front in the Field description, before anyone fails it.
+- `onSignUp` receives the fields only after the browser's own validation (required, type=email, minLength) passes.
+
+## Accessibility
+
+- Field wires each label, description and error to its input; never hand-roll <label> + <input> pairs.
+- autoComplete hints (name, email, new-password) let password managers offer to generate and save the password.
+
+## Source
+
+```tsx
+import { Button, Card, CardContent, CardDescription, CardFooter, CardHeader, CardTitle, cn, Field, Form, Input } from "@sableui/react"
+
+export interface SignUpBlockProps {
+	className?: string
+	/** false drops the card's surface and border — for a Sheet, Dialog or muted section that already frames it. */
+	framed?: boolean
+	/** Called with the submitted fields once the browser's validation passes. */
+	onSignUp?: (account: { name: string; email: string; password: string }) => void
+}
+
+export function SignUpBlock({ className, framed = true, onSignUp }: SignUpBlockProps) {
+	return (
+		<Card variant={framed ? "default" : "flat"} className={cn("w-full max-w-sm", className)}>
+			<CardHeader>
+				<CardTitle>Create your account</CardTitle>
+				<CardDescription>Free for 14 days. No card needed.</CardDescription>
+			</CardHeader>
+			<Form
+				className="gap-0"
+				onSubmit={(event) => {
+					event.preventDefault()
+					const data = new FormData(event.currentTarget)
+					onSignUp?.({
+						name: String(data.get("name") ?? ""),
+						email: String(data.get("email") ?? ""),
+						password: String(data.get("password") ?? ""),
+					})
+				}}
+			>
+				<CardContent className="flex flex-col gap-3">
+					<Field label="Name" name="name" required>
+						<Input autoComplete="name" />
+					</Field>
+					<Field label="Work email" name="email" required>
+						<Input type="email" autoComplete="email" placeholder="you@studio.com" />
+					</Field>
+					<Field label="Password" name="password" description="At least 12 characters." required>
+						<Input type="password" autoComplete="new-password" minLength={12} />
+					</Field>
+				</CardContent>
+				<CardFooter className="flex-col items-stretch gap-3">
+					<Button type="submit" className="w-full">
+						Create account
+					</Button>
+					<p className="text-center text-caption text-muted-foreground">
+						Already have an account?{" "}
+						<a href="/sign-in" className="text-foreground underline underline-offset-4 motion-interactive hover:text-muted-foreground">
+							Sign in
+						</a>
+					</p>
+				</CardFooter>
+			</Form>
+		</Card>
+	)
+}
+```

package/llms/blocks/site-footer-block.md

@@ -0,0 +1,96 @@
+# SiteFooterBlock
+
+A site footer: the brand and a one-line tagline beside link groups in a labelled Footer nav, over a copyright line.
+
+**Intent:** Reach for this at the foot of a marketing or docs site. App screens inside an AppShell take no footer; their navigation lives in the sidebar.
+
+**Block:** Marketing · section
+
+## Notes
+
+- Copied from the LandingPage page shell's footer.
+- Every link is at least 36px tall (min-h-9), so the dense list is still an easy touch target.
+- Groups go two up on a phone and three up from sm; add a group only if it has three links or more.
+
+## Accessibility
+
+- Renders <footer> with a <nav aria-label="Footer">, distinct from the page's main navigation.
+- Group titles are h2s, so the footer's structure is navigable by heading.
+
+## Source
+
+```tsx
+import { cn, Region, Stack } from "@sableui/react"
+
+const brand = { name: "Sable", tagline: "React components, patterns, and tokens for products built with AI agents." }
+
+const groups = [
+	{
+		title: "Product",
+		links: [
+			{ label: "Components", href: "/components" },
+			{ label: "Patterns", href: "/patterns" },
+			{ label: "Themes", href: "/themes" },
+			{ label: "Canvas", href: "/canvas" },
+		],
+	},
+	{
+		title: "Resources",
+		links: [
+			{ label: "Documentation", href: "/docs" },
+			{ label: "Changelog", href: "/changelog" },
+			{ label: "llms.txt", href: "/llms.txt" },
+		],
+	},
+	{
+		title: "Community",
+		links: [
+			{ label: "GitHub", href: "/github" },
+			{ label: "npm", href: "/npm" },
+			{ label: "Discussions", href: "/discussions" },
+		],
+	},
+]
+
+export interface SiteFooterBlockProps {
+	className?: string
+}
+
+export function SiteFooterBlock({ className }: SiteFooterBlockProps) {
+	return (
+		<footer className={cn("w-full border-t border-border", className)}>
+			<Region max="wide" className="py-12">
+				<div className="grid gap-10 md:grid-cols-[minmax(0,2fr)_minmax(0,3fr)]">
+					<Stack gap={3} className="max-w-xs">
+						<a href="/" className="w-fit text-title-lg motion-interactive hover:text-muted-foreground">
+							{brand.name}
+						</a>
+						<p className="text-body-sm text-muted-foreground">{brand.tagline}</p>
+					</Stack>
+					<nav aria-label="Footer" className="grid grid-cols-2 gap-8 sm:grid-cols-3">
+						{groups.map((group) => (
+							<div key={group.title}>
+								<h2 className="text-label-md text-muted-foreground">{group.title}</h2>
+								<ul className="mt-3 flex flex-col gap-1">
+									{group.links.map((link) => (
+										<li key={link.label}>
+											<a href={link.href} className="flex min-h-9 items-center text-body-sm motion-interactive hover:text-muted-foreground">
+												{link.label}
+											</a>
+										</li>
+									))}
+								</ul>
+							</div>
+						))}
+					</nav>
+				</div>
+				<div className="mt-12 border-t border-border pt-6">
+					<p className="text-caption text-muted-foreground">
+						© 2026 {brand.name}. Released under the MIT license.
+					</p>
+				</div>
+			</Region>
+		</footer>
+	)
+}
+```

package/llms/blocks/stat-row-block.md

@@ -0,0 +1,59 @@
+# StatRowBlock
+
+A KPI row: four stat cards, each a label, the value in the metric mono tier, and a trend Badge with its comparison note — 2 × 2 on a phone, one row from xl.
+
+**Intent:** Reach for this at the top of a dashboard or report, above the tables and charts it summarises. One headline number worth splitting into categories is RevenueBreakdownBlock.
+
+**Block:** Dashboard · section
+
+## Notes
+
+- Copied from the DashboardPage page shell's stat row.
+- Values are `text-mono-xl` — tabular figures, never a heading tier — so the four numbers align digit for digit.
+- The trend Badge sits with its note in CardContent, so the value keeps the full card width when the row folds to 2 × 2.
+- Keep it to four. A fifth stat is a sign one of them belongs in a table.
+
+## Accessibility
+
+- The trend is stated in text (+8.2%) with an arrow icon; the tone is reinforcement, not the signal.
+- Each card's label is read before its value, in source order.
+
+## Source
+
+```tsx
+import { Badge, Card, CardContent, CardDescription, CardHeader, CardTitle, cn, Grid, Icon, Row } from "@sableui/react"
+
+const stats = [
+	{ label: "Revenue", value: "$18,240", delta: "+8.2%", up: true, note: "vs. $16,857" },
+	{ label: "Collects", value: "1,284", delta: "+3.1%", up: true, note: "182 first-time" },
+	{ label: "Collectors", value: "312", delta: "+12.4%", up: true, note: "Best month yet" },
+	{ label: "Sell-through", value: "64%", delta: "−1.8%", up: false, note: "6 open editions" },
+]
+
+export interface StatRowBlockProps {
+	className?: string
+}
+
+export function StatRowBlock({ className }: StatRowBlockProps) {
+	return (
+		<Grid cols={{ base: 2, xl: 4 }} gap={3} className={cn("w-full", className)}>
+			{stats.map((stat) => (
+				<Card key={stat.label}>
+					<CardHeader>
+						<CardDescription>{stat.label}</CardDescription>
+						<CardTitle className="text-mono-xl">{stat.value}</CardTitle>
+					</CardHeader>
+					<CardContent>
+						<Row gap={1} wrap>
+							<Badge tone={stat.up ? "success" : "warning"} size="sm" icon={<Icon name={stat.up ? "arrow-up" : "arrow-down"} />}>
+								{stat.delta}
+							</Badge>
+							<span className="text-caption text-muted-foreground">{stat.note}</span>
+						</Row>
+					</CardContent>
+				</Card>
+			))}
+		</Grid>
+	)
+}
+```