diff --git a/apps/docs/package.json b/apps/docs/package.json
index 12f7bd8a..309d2e04 100644
--- a/apps/docs/package.json
+++ b/apps/docs/package.json
@@ -7,6 +7,9 @@
 	},
 	"type": "module",
 	"sideEffects": false,
+	"imports": {
+		"#docs/comparison": "./src/examples/comparison.tsx"
+	},
 	"scripts": {
 		"build": "vp build",
 		"check:docs": "tsx scripts/check-docs.ts",
diff --git a/apps/docs/scripts/generate-playground-types.ts b/apps/docs/scripts/generate-playground-types.ts
index 1df4b74f..900f4d60 100644
--- a/apps/docs/scripts/generate-playground-types.ts
+++ b/apps/docs/scripts/generate-playground-types.ts
@@ -20,9 +20,11 @@ import * as z from 'zod';
 
 const scriptDir = dirname(fileURLToPath(import.meta.url));
 const docsPackageJsonPath = resolve(scriptDir, '../package.json');
+const docsExamplesDir = resolve(scriptDir, '../src/examples');
 const reactPackageDir = resolve(scriptDir, '../../../packages/@luke-ui/react');
 const rainbowSprinklesDir = resolve(scriptDir, '../../../packages/@luke-ui/rainbow-sprinkles');
 const outputPath = resolve(scriptDir, '../src/generated/playground-types.generated.json');
+const docsComparisonVirtualPath = 'file:///docs/comparison.tsx';
 
 const files: Record<string, string> = {};
 
@@ -34,6 +36,10 @@ function addFile(packageName: string, packageDir: string, filePath: string): voi
 	files[virtualPath(packageName, relative(packageDir, filePath))] = readFileSync(filePath, 'utf8');
 }
 
+function addDocsFile(virtualPath: string, filePath: string): void {
+	files[virtualPath] = readFileSync(filePath, 'utf8');
+}
+
 function walk(dir: string, visit: (filePath: string) => void): void {
 	for (const entry of readdirSync(dir, { withFileTypes: true })) {
 		if (entry.name === 'node_modules') continue;
@@ -151,6 +157,8 @@ for (const [packageName, packageDir] of externalTypePackages) {
 	addTypesPackage(packageName, packageDir);
 }
 
+addDocsFile(docsComparisonVirtualPath, join(docsExamplesDir, 'comparison.tsx'));
+
 const output = JSON.stringify(files);
 mkdirSync(dirname(outputPath), { recursive: true });
 writeFileSync(outputPath, output);
diff --git a/apps/docs/src/components/playground/preview-runner.browser.test.tsx b/apps/docs/src/components/playground/preview-runner.browser.test.tsx
index 6bbedf54..295b3e36 100644
--- a/apps/docs/src/components/playground/preview-runner.browser.test.tsx
+++ b/apps/docs/src/components/playground/preview-runner.browser.test.tsx
@@ -7,6 +7,7 @@ import { act } from 'react';
 import type { Root } from 'react-dom/client';
 import { createRoot } from 'react-dom/client';
 import { afterEach, expect, test } from 'vite-plus/test';
+import toneSource from '../../examples/button/tones.tsx?raw';
 import type { PlaygroundPreviewMessage } from '../../lib/playground-protocol.js';
 import { isPlaygroundPreviewMessage } from '../../lib/playground-protocol.js';
 import { DocsThemeRoot } from '../theme-controls.js';
@@ -94,6 +95,20 @@ test('compiles parent playground code and posts success', async () => {
 		.toEqual({ type: 'playground:success' });
 });
 
+test('runs the Button tone example with the docs comparison helper', async () => {
+	const messages = collectParentPreviewMessages();
+	await mountPreview();
+
+	await act(async () => {
+		postFromParent({ code: toneSource, type: 'playground:code' });
+	});
+
+	await expect
+		.poll(() => messages.find((message) => message.type === 'playground:success'))
+		.toEqual({ type: 'playground:success' });
+	expect(container).toHaveTextContent('Neutral');
+});
+
 test('posts the compileComponent error when parent playground code is invalid', async () => {
 	const messages = collectParentPreviewMessages();
 	await mountPreview();
diff --git a/apps/docs/src/examples/button/appearance.tsx b/apps/docs/src/examples/button/appearance.tsx
index 58a4899d..ca201742 100644
--- a/apps/docs/src/examples/button/appearance.tsx
+++ b/apps/docs/src/examples/button/appearance.tsx
@@ -1,12 +1,18 @@
-import { Box } from '@luke-ui/react/box';
 import { Button } from '@luke-ui/react/button';
+import { Comparison, ComparisonItem } from '#docs/comparison';
 
 export default () => {
 	return (
-		<Box alignItems="center" display="flex" flexWrap="wrap" gap="sp16">
-			<Button appearance="solid">Save changes</Button>
-			<Button appearance="subtle">Save changes</Button>
-			<Button appearance="ghost">Save changes</Button>
-		</Box>
+		<Comparison>
+			<ComparisonItem label="Solid">
+				<Button appearance="solid">Example button</Button>
+			</ComparisonItem>
+			<ComparisonItem label="Subtle">
+				<Button appearance="subtle">Example button</Button>
+			</ComparisonItem>
+			<ComparisonItem label="Ghost">
+				<Button appearance="ghost">Example button</Button>
+			</ComparisonItem>
+		</Comparison>
 	);
 };
diff --git a/apps/docs/src/examples/button/sizes.tsx b/apps/docs/src/examples/button/sizes.tsx
index 35cbdc01..89ec560e 100644
--- a/apps/docs/src/examples/button/sizes.tsx
+++ b/apps/docs/src/examples/button/sizes.tsx
@@ -1,16 +1,15 @@
-import { Box } from '@luke-ui/react/box';
 import { Button } from '@luke-ui/react/button';
-import { Icon } from '@luke-ui/react/icon';
+import { Comparison, ComparisonItem } from '#docs/comparison';
 
 export default () => {
 	return (
-		<Box alignItems="center" display="flex" gap="sp16">
-			<Button size="small" startIcon={<Icon name="edit" />}>
-				Edit profile
-			</Button>
-			<Button size="medium" startIcon={<Icon name="edit" />}>
-				Edit profile
-			</Button>
-		</Box>
+		<Comparison>
+			<ComparisonItem label="Small">
+				<Button size="small">Example button</Button>
+			</ComparisonItem>
+			<ComparisonItem label="Medium">
+				<Button size="medium">Example button</Button>
+			</ComparisonItem>
+		</Comparison>
 	);
 };
diff --git a/apps/docs/src/examples/button/tones.tsx b/apps/docs/src/examples/button/tones.tsx
index 15d94b96..bc9ebfb3 100644
--- a/apps/docs/src/examples/button/tones.tsx
+++ b/apps/docs/src/examples/button/tones.tsx
@@ -1,12 +1,18 @@
-import { Box } from '@luke-ui/react/box';
 import { Button } from '@luke-ui/react/button';
+import { Comparison, ComparisonItem } from '#docs/comparison';
 
 export default () => {
 	return (
-		<Box alignItems="center" display="flex" flexWrap="wrap" gap="sp16">
-			<Button>Cancel</Button>
-			<Button tone="accent">Save changes</Button>
-			<Button tone="danger">Delete account</Button>
-		</Box>
+		<Comparison>
+			<ComparisonItem label="Neutral">
+				<Button tone="neutral">Example button</Button>
+			</ComparisonItem>
+			<ComparisonItem label="Accent">
+				<Button tone="accent">Example button</Button>
+			</ComparisonItem>
+			<ComparisonItem label="Danger">
+				<Button tone="danger">Example button</Button>
+			</ComparisonItem>
+		</Comparison>
 	);
 };
diff --git a/apps/docs/src/examples/checkbox/sizes.tsx b/apps/docs/src/examples/checkbox/sizes.tsx
index d3fd987e..b62457d1 100644
--- a/apps/docs/src/examples/checkbox/sizes.tsx
+++ b/apps/docs/src/examples/checkbox/sizes.tsx
@@ -1,18 +1,24 @@
-import { Box } from '@luke-ui/react/box';
 import { Checkbox } from '@luke-ui/react/checkbox';
+import { Comparison, ComparisonItem } from '#docs/comparison';
 
 export default () => {
 	return (
-		<Box display="grid" gap="sp12">
-			<Checkbox defaultSelected size="small">
-				Small
-			</Checkbox>
-			<Checkbox defaultSelected size="medium">
-				Medium
-			</Checkbox>
-			<Checkbox defaultSelected size="large">
-				Large
-			</Checkbox>
-		</Box>
+		<Comparison direction="vertical">
+			<ComparisonItem label="Small">
+				<Checkbox defaultSelected size="small">
+					Example checkbox
+				</Checkbox>
+			</ComparisonItem>
+			<ComparisonItem label="Medium">
+				<Checkbox defaultSelected size="medium">
+					Example checkbox
+				</Checkbox>
+			</ComparisonItem>
+			<ComparisonItem label="Large">
+				<Checkbox defaultSelected size="large">
+					Example checkbox
+				</Checkbox>
+			</ComparisonItem>
+		</Comparison>
 	);
 };
diff --git a/apps/docs/src/examples/combobox-field/sizes.tsx b/apps/docs/src/examples/combobox-field/sizes.tsx
index 57e02c54..50e281f7 100644
--- a/apps/docs/src/examples/combobox-field/sizes.tsx
+++ b/apps/docs/src/examples/combobox-field/sizes.tsx
@@ -1,37 +1,42 @@
 import { Box } from '@luke-ui/react/box';
 import { ComboboxField } from '@luke-ui/react/combobox-field';
 import { ComboboxItem } from '@luke-ui/react/primitives/combobox';
+import { Comparison, ComparisonItem } from '#docs/comparison';
 
-type Fruit = { id: string; label: string };
+type Option = { id: string; label: string };
 
-const fruits: Array<Fruit> = [
-	{ id: 'apple', label: 'Apple' },
-	{ id: 'orange', label: 'Orange' },
-	{ id: 'banana', label: 'Banana' },
-	{ id: 'grape', label: 'Grape' },
+const options: Array<Option> = [
+	{ id: 'one', label: 'Example option' },
+	{ id: 'two', label: 'Another option' },
 ];
 
 export default () => {
 	return (
-		<Box display="flex" flexDirection="column" gap="sp16" maxInlineSize="20rem">
-			<ComboboxField
-				defaultItems={fruits}
-				label="Favourite fruit"
-				name="smallFruit"
-				placeholder="Choose a fruit"
-				size="small"
-			>
-				{(item) => <ComboboxItem>{item.label}</ComboboxItem>}
-			</ComboboxField>
-			<ComboboxField
-				defaultItems={fruits}
-				label="Favourite fruit"
-				name="mediumFruit"
-				placeholder="Choose a fruit"
-				size="medium"
-			>
-				{(item) => <ComboboxItem>{item.label}</ComboboxItem>}
-			</ComboboxField>
+		<Box maxInlineSize="20rem">
+			<Comparison direction="vertical">
+				<ComparisonItem label="Small">
+					<ComboboxField
+						defaultItems={options}
+						label="Example field"
+						name="example"
+						placeholder="Choose an option"
+						size="small"
+					>
+						{(item) => <ComboboxItem>{item.label}</ComboboxItem>}
+					</ComboboxField>
+				</ComparisonItem>
+				<ComparisonItem label="Medium">
+					<ComboboxField
+						defaultItems={options}
+						label="Example field"
+						name="example"
+						placeholder="Choose an option"
+						size="medium"
+					>
+						{(item) => <ComboboxItem>{item.label}</ComboboxItem>}
+					</ComboboxField>
+				</ComparisonItem>
+			</Comparison>
 		</Box>
 	);
 };
diff --git a/apps/docs/src/examples/comparison.tsx b/apps/docs/src/examples/comparison.tsx
new file mode 100644
index 00000000..ab6c3c02
--- /dev/null
+++ b/apps/docs/src/examples/comparison.tsx
@@ -0,0 +1,38 @@
+import { Box } from '@luke-ui/react/box';
+import { Text } from '@luke-ui/react/text';
+import type { PropsWithChildren } from 'react';
+
+type ComparisonProps = PropsWithChildren<{
+	direction?: 'horizontal' | 'vertical';
+}>;
+
+type ComparisonItemProps = PropsWithChildren<{
+	label: string;
+}>;
+
+export function Comparison({ children, direction = 'horizontal' }: ComparisonProps) {
+	if (direction === 'vertical') {
+		return (
+			<Box display="grid" gap="sp16">
+				{children}
+			</Box>
+		);
+	}
+
+	return (
+		<Box alignItems="center" display="flex" flexWrap="wrap" gap="sp16">
+			{children}
+		</Box>
+	);
+}
+
+export function ComparisonItem({ children, label }: ComparisonItemProps) {
+	return (
+		<Box display="grid" gap="sp4">
+			<Text color="secondary" typography="caption">
+				{label}
+			</Text>
+			{children}
+		</Box>
+	);
+}
diff --git a/apps/docs/src/examples/heading/typography.tsx b/apps/docs/src/examples/heading/typography.tsx
index b2d9bbd9..023d6eb1 100644
--- a/apps/docs/src/examples/heading/typography.tsx
+++ b/apps/docs/src/examples/heading/typography.tsx
@@ -1,9 +1,44 @@
 import { Heading } from '@luke-ui/react/heading';
+import { Comparison, ComparisonItem } from '#docs/comparison';
 
 export default () => {
 	return (
-		<Heading level={2} typography="display">
-			Account overview
-		</Heading>
+		<Comparison direction="vertical">
+			<ComparisonItem label="body">
+				<Heading level={2} typography="body">
+					Example heading
+				</Heading>
+			</ComparisonItem>
+			<ComparisonItem label="lead">
+				<Heading level={2} typography="lead">
+					Example heading
+				</Heading>
+			</ComparisonItem>
+			<ComparisonItem label="heading4">
+				<Heading level={2} typography="heading4">
+					Example heading
+				</Heading>
+			</ComparisonItem>
+			<ComparisonItem label="heading3">
+				<Heading level={2} typography="heading3">
+					Example heading
+				</Heading>
+			</ComparisonItem>
+			<ComparisonItem label="heading2">
+				<Heading level={2} typography="heading2">
+					Example heading
+				</Heading>
+			</ComparisonItem>
+			<ComparisonItem label="heading1">
+				<Heading level={2} typography="heading1">
+					Example heading
+				</Heading>
+			</ComparisonItem>
+			<ComparisonItem label="display">
+				<Heading level={2} typography="display">
+					Example heading
+				</Heading>
+			</ComparisonItem>
+		</Comparison>
 	);
 };
diff --git a/apps/docs/src/examples/icon-button/appearance.tsx b/apps/docs/src/examples/icon-button/appearance.tsx
index 5f954d9b..fa71c563 100644
--- a/apps/docs/src/examples/icon-button/appearance.tsx
+++ b/apps/docs/src/examples/icon-button/appearance.tsx
@@ -1,12 +1,18 @@
-import { Box } from '@luke-ui/react/box';
 import { IconButton } from '@luke-ui/react/icon-button';
+import { Comparison, ComparisonItem } from '#docs/comparison';
 
 export default () => {
 	return (
-		<Box alignItems="center" display="flex" flexWrap="wrap" gap="sp16">
-			<IconButton appearance="solid" aria-label="Open documentation" icon="bookOpen" />
-			<IconButton appearance="subtle" aria-label="Open documentation" icon="bookOpen" />
-			<IconButton appearance="ghost" aria-label="Open documentation" icon="bookOpen" />
-		</Box>
+		<Comparison>
+			<ComparisonItem label="Solid">
+				<IconButton appearance="solid" aria-label="Example action" icon="bookOpen" />
+			</ComparisonItem>
+			<ComparisonItem label="Subtle">
+				<IconButton appearance="subtle" aria-label="Example action" icon="bookOpen" />
+			</ComparisonItem>
+			<ComparisonItem label="Ghost">
+				<IconButton appearance="ghost" aria-label="Example action" icon="bookOpen" />
+			</ComparisonItem>
+		</Comparison>
 	);
 };
diff --git a/apps/docs/src/examples/icon-button/size.tsx b/apps/docs/src/examples/icon-button/size.tsx
index f934a66a..99bfb01a 100644
--- a/apps/docs/src/examples/icon-button/size.tsx
+++ b/apps/docs/src/examples/icon-button/size.tsx
@@ -1,11 +1,15 @@
-import { Box } from '@luke-ui/react/box';
 import { IconButton } from '@luke-ui/react/icon-button';
+import { Comparison, ComparisonItem } from '#docs/comparison';
 
 export default () => {
 	return (
-		<Box alignItems="center" display="flex" gap="sp16">
-			<IconButton aria-label="Search" icon="search" size="small" />
-			<IconButton aria-label="Search" icon="search" />
-		</Box>
+		<Comparison>
+			<ComparisonItem label="Small">
+				<IconButton aria-label="Example action" icon="search" size="small" />
+			</ComparisonItem>
+			<ComparisonItem label="Medium">
+				<IconButton aria-label="Example action" icon="search" size="medium" />
+			</ComparisonItem>
+		</Comparison>
 	);
 };
diff --git a/apps/docs/src/examples/icon-button/tones.tsx b/apps/docs/src/examples/icon-button/tones.tsx
index 5544cb03..dde13aca 100644
--- a/apps/docs/src/examples/icon-button/tones.tsx
+++ b/apps/docs/src/examples/icon-button/tones.tsx
@@ -1,12 +1,18 @@
-import { Box } from '@luke-ui/react/box';
 import { IconButton } from '@luke-ui/react/icon-button';
+import { Comparison, ComparisonItem } from '#docs/comparison';
 
 export default () => {
 	return (
-		<Box alignItems="center" display="flex" flexWrap="wrap" gap="sp16">
-			<IconButton aria-label="Search" icon="search" />
-			<IconButton aria-label="Add item" icon="add" tone="accent" />
-			<IconButton aria-label="Delete item" icon="delete" tone="danger" />
-		</Box>
+		<Comparison>
+			<ComparisonItem label="Neutral">
+				<IconButton aria-label="Example action" icon="search" tone="neutral" />
+			</ComparisonItem>
+			<ComparisonItem label="Accent">
+				<IconButton aria-label="Example action" icon="search" tone="accent" />
+			</ComparisonItem>
+			<ComparisonItem label="Danger">
+				<IconButton aria-label="Example action" icon="search" tone="danger" />
+			</ComparisonItem>
+		</Comparison>
 	);
 };
diff --git a/apps/docs/src/examples/icon/colours.tsx b/apps/docs/src/examples/icon/colours.tsx
index 69b0ce7d..768532bd 100644
--- a/apps/docs/src/examples/icon/colours.tsx
+++ b/apps/docs/src/examples/icon/colours.tsx
@@ -5,30 +5,48 @@ import type { PropsWithChildren } from 'react';
 
 export default () => {
 	return (
-		<Box alignItems="center" display="flex" gap="sp16">
+		<Box alignItems="center" display="flex" flexWrap="wrap" gap="sp16">
+			<FlexCol>
+				<Text color="primary">
+					<Icon name="checkCircle" />
+				</Text>
+				<Text color="secondary">Primary</Text>
+			</FlexCol>
+			<FlexCol>
+				<Text color="secondary">
+					<Icon name="checkCircle" />
+				</Text>
+				<Text color="secondary">Secondary</Text>
+			</FlexCol>
 			<FlexCol>
 				<Text color="accent">
-					<Icon name="checkCircle" title="Accent" />
+					<Icon name="checkCircle" />
+				</Text>
+				<Text color="secondary">Accent</Text>
+			</FlexCol>
+			<FlexCol>
+				<Text color="info">
+					<Icon name="checkCircle" />
 				</Text>
-				<Text color="secondary">accent</Text>
+				<Text color="secondary">Info</Text>
 			</FlexCol>
 			<FlexCol>
 				<Text color="success">
-					<Icon name="checkCircle" title="Success" />
+					<Icon name="checkCircle" />
 				</Text>
-				<Text color="secondary">success</Text>
+				<Text color="secondary">Success</Text>
 			</FlexCol>
 			<FlexCol>
 				<Text color="warning">
-					<Icon name="exclamationTriangle" title="Warning" />
+					<Icon name="checkCircle" />
 				</Text>
-				<Text color="secondary">warning</Text>
+				<Text color="secondary">Warning</Text>
 			</FlexCol>
 			<FlexCol>
 				<Text color="danger">
-					<Icon name="closeCircle" title="Danger" />
+					<Icon name="checkCircle" />
 				</Text>
-				<Text color="secondary">danger</Text>
+				<Text color="secondary">Danger</Text>
 			</FlexCol>
 		</Box>
 	);
diff --git a/apps/docs/src/examples/icon/sizes.tsx b/apps/docs/src/examples/icon/sizes.tsx
index 01ff8ec4..b2a05cc1 100644
--- a/apps/docs/src/examples/icon/sizes.tsx
+++ b/apps/docs/src/examples/icon/sizes.tsx
@@ -5,22 +5,30 @@ import type { PropsWithChildren } from 'react';
 
 export default () => {
 	return (
-		<Box alignItems="flex-end" display="flex" gap="sp16">
+		<Box alignItems="flex-end" display="flex" flexWrap="wrap" gap="sp16">
 			<FlexCol>
 				<Icon name="search" size="xsmall" />
-				<Text color="secondary">xsmall</Text>
+				<Text color="secondary" typography="caption">
+					X-small
+				</Text>
 			</FlexCol>
 			<FlexCol>
 				<Icon name="search" size="small" />
-				<Text color="secondary">small</Text>
+				<Text color="secondary" typography="caption">
+					Small
+				</Text>
 			</FlexCol>
 			<FlexCol>
 				<Icon name="search" size="medium" />
-				<Text color="secondary">medium</Text>
+				<Text color="secondary" typography="caption">
+					Medium
+				</Text>
 			</FlexCol>
 			<FlexCol>
 				<Icon name="search" size="large" />
-				<Text color="secondary">large</Text>
+				<Text color="secondary" typography="caption">
+					Large
+				</Text>
 			</FlexCol>
 		</Box>
 	);
diff --git a/apps/docs/src/examples/link/tones.tsx b/apps/docs/src/examples/link/tones.tsx
index 6bf50675..ca7d4744 100644
--- a/apps/docs/src/examples/link/tones.tsx
+++ b/apps/docs/src/examples/link/tones.tsx
@@ -1,24 +1,19 @@
-import { Box } from '@luke-ui/react/box';
 import { Link } from '@luke-ui/react/link';
-import { Text } from '@luke-ui/react/text';
+import { Comparison, ComparisonItem } from '#docs/comparison';
 
 export default () => {
 	return (
-		<Box display="flex" flexWrap="wrap" gap="sp16">
-			<Box display="grid" gap="sp4">
-				<Text color="secondary" typography="caption">
-					Accent
-				</Text>
-				<Link href="#example-destination">Example destination</Link>
-			</Box>
-			<Box display="grid" gap="sp4">
-				<Text color="secondary" typography="caption">
-					Neutral
-				</Text>
+		<Comparison>
+			<ComparisonItem label="Accent">
+				<Link href="#example-destination" tone="accent">
+					Example destination
+				</Link>
+			</ComparisonItem>
+			<ComparisonItem label="Neutral">
 				<Link href="#example-destination" tone="neutral">
 					Example destination
 				</Link>
-			</Box>
-		</Box>
+			</ComparisonItem>
+		</Comparison>
 	);
 };
diff --git a/apps/docs/src/examples/loading-spinner/colors.tsx b/apps/docs/src/examples/loading-spinner/colors.tsx
index a3f34962..25805de6 100644
--- a/apps/docs/src/examples/loading-spinner/colors.tsx
+++ b/apps/docs/src/examples/loading-spinner/colors.tsx
@@ -1,11 +1,33 @@
-import { Box } from '@luke-ui/react/box';
 import { LoadingSpinner } from '@luke-ui/react/loading-spinner';
+import { Comparison, ComparisonItem } from '#docs/comparison';
 
 export default () => {
 	return (
-		<Box alignItems="center" display="flex" flexWrap="wrap" gap="sp16">
-			<LoadingSpinner aria-label="Loading content" />
-			<LoadingSpinner aria-label="Loading highlighted content" color="accent" />
-		</Box>
+		<Comparison>
+			<ComparisonItem label="Inherited">
+				<LoadingSpinner aria-label="Loading" />
+			</ComparisonItem>
+			<ComparisonItem label="Primary">
+				<LoadingSpinner aria-label="Loading" color="primary" />
+			</ComparisonItem>
+			<ComparisonItem label="Secondary">
+				<LoadingSpinner aria-label="Loading" color="secondary" />
+			</ComparisonItem>
+			<ComparisonItem label="Accent">
+				<LoadingSpinner aria-label="Loading" color="accent" />
+			</ComparisonItem>
+			<ComparisonItem label="Info">
+				<LoadingSpinner aria-label="Loading" color="info" />
+			</ComparisonItem>
+			<ComparisonItem label="Success">
+				<LoadingSpinner aria-label="Loading" color="success" />
+			</ComparisonItem>
+			<ComparisonItem label="Warning">
+				<LoadingSpinner aria-label="Loading" color="warning" />
+			</ComparisonItem>
+			<ComparisonItem label="Danger">
+				<LoadingSpinner aria-label="Loading" color="danger" />
+			</ComparisonItem>
+		</Comparison>
 	);
 };
diff --git a/apps/docs/src/examples/loading-spinner/sizes.tsx b/apps/docs/src/examples/loading-spinner/sizes.tsx
index e9402430..9a6f622a 100644
--- a/apps/docs/src/examples/loading-spinner/sizes.tsx
+++ b/apps/docs/src/examples/loading-spinner/sizes.tsx
@@ -1,13 +1,21 @@
-import { Box } from '@luke-ui/react/box';
 import { LoadingSpinner } from '@luke-ui/react/loading-spinner';
+import { Comparison, ComparisonItem } from '#docs/comparison';
 
 export default () => {
 	return (
-		<Box alignItems="center" display="flex" gap="sp16">
-			<LoadingSpinner aria-label="Loading inline content" size="xsmall" />
-			<LoadingSpinner aria-label="Loading compact control" size="small" />
-			<LoadingSpinner aria-label="Loading content" size="medium" />
-			<LoadingSpinner aria-label="Loading prominent content" size="large" />
-		</Box>
+		<Comparison>
+			<ComparisonItem label="X-small">
+				<LoadingSpinner aria-label="Loading" size="xsmall" />
+			</ComparisonItem>
+			<ComparisonItem label="Small">
+				<LoadingSpinner aria-label="Loading" size="small" />
+			</ComparisonItem>
+			<ComparisonItem label="Medium">
+				<LoadingSpinner aria-label="Loading" size="medium" />
+			</ComparisonItem>
+			<ComparisonItem label="Large">
+				<LoadingSpinner aria-label="Loading" size="large" />
+			</ComparisonItem>
+		</Comparison>
 	);
 };
diff --git a/apps/docs/src/examples/text-field/sizes.tsx b/apps/docs/src/examples/text-field/sizes.tsx
index e6d8a518..0e8f54a7 100644
--- a/apps/docs/src/examples/text-field/sizes.tsx
+++ b/apps/docs/src/examples/text-field/sizes.tsx
@@ -1,11 +1,28 @@
 import { Box } from '@luke-ui/react/box';
 import { TextField } from '@luke-ui/react/text-field';
+import { Comparison, ComparisonItem } from '#docs/comparison';
 
 export default () => {
 	return (
-		<Box display="flex" flexDirection="column" gap="sp16" maxInlineSize="20rem">
-			<TextField label="Search" name="smallSearch" placeholder="Search" size="small" />
-			<TextField label="Search" name="mediumSearch" placeholder="Search" size="medium" />
+		<Box maxInlineSize="20rem">
+			<Comparison direction="vertical">
+				<ComparisonItem label="Small">
+					<TextField
+						label="Example field"
+						name="example"
+						placeholder="Example input"
+						size="small"
+					/>
+				</ComparisonItem>
+				<ComparisonItem label="Medium">
+					<TextField
+						label="Example field"
+						name="example"
+						placeholder="Example input"
+						size="medium"
+					/>
+				</ComparisonItem>
+			</Comparison>
 		</Box>
 	);
 };
diff --git a/apps/docs/src/lib/example-reachability.test.ts b/apps/docs/src/lib/example-reachability.test.ts
index 2fdf7b03..df7f32e5 100644
--- a/apps/docs/src/lib/example-reachability.test.ts
+++ b/apps/docs/src/lib/example-reachability.test.ts
@@ -29,6 +29,7 @@ test('finds examples that are neither documented nor imported by another example
 	writeFileSync(
 		join(examplesDir, 'profile/basic.tsx'),
 		[
+			"import { Comparison } from '#docs/comparison';",
 			"import { Preferences } from './preferences';",
 			"import { ProfileDetails } from './profile-details.js';",
 			'',
@@ -45,6 +46,10 @@ test('finds examples that are neither documented nor imported by another example
 		join(examplesDir, 'profile/preferences.tsx'),
 		'export function Preferences() { return null; }\n',
 	);
+	writeFileSync(
+		join(examplesDir, 'comparison.tsx'),
+		'export function Comparison() { return null; }\n',
+	);
 	writeFileSync(
 		join(examplesDir, 'profile/obsolete.tsx'),
 		'export default function Obsolete() { return null; }\n',
diff --git a/apps/docs/src/lib/monaco-setup.ts b/apps/docs/src/lib/monaco-setup.ts
index aa865eb9..218b38ff 100644
--- a/apps/docs/src/lib/monaco-setup.ts
+++ b/apps/docs/src/lib/monaco-setup.ts
@@ -104,6 +104,7 @@ typescriptDefaults.setCompilerOptions({
 	module: monaco.typescript.ModuleKind.ESNext,
 	moduleResolution: bundlerModuleResolution,
 	paths: {
+		'#docs/comparison': ['file:///docs/comparison.tsx'],
 		'@luke-ui/react/*': ['file:///node_modules/@luke-ui/react/dist/*/index.d.ts'],
 	},
 	strict: true,
diff --git a/apps/docs/src/lib/playground-runtime-specifiers.test.ts b/apps/docs/src/lib/playground-runtime-specifiers.test.ts
index 3d579189..dfabf81b 100644
--- a/apps/docs/src/lib/playground-runtime-specifiers.test.ts
+++ b/apps/docs/src/lib/playground-runtime-specifiers.test.ts
@@ -21,12 +21,16 @@ test('treats a relative import as unresolvable in the playground', () => {
 });
 
 test('treats an example that only imports playground specifiers as runnable', () => {
-	const source = "import { Button } from '@luke-ui/react/button';\n";
+	const source = [
+		"import { Button } from '@luke-ui/react/button';",
+		"import { Comparison } from '#docs/comparison';",
+		'',
+	].join('\n');
 
 	expect(canRunInPlayground(source, specifiers)).toBe(true);
 });
 
-test('documented examples that the playground cannot resolve are the known relative-import pair', () => {
+test('documented examples that the playground cannot resolve use unsupported relative imports', () => {
 	const docsDir = resolve(import.meta.dirname, '../../content/docs');
 	const examplesDir = resolve(import.meta.dirname, '../examples');
 	const unrunnable = documentedExampleSources(docsDir)
diff --git a/apps/docs/src/lib/playground-runtime-specifiers.ts b/apps/docs/src/lib/playground-runtime-specifiers.ts
index 3cc1e4a4..7b5e30d1 100644
--- a/apps/docs/src/lib/playground-runtime-specifiers.ts
+++ b/apps/docs/src/lib/playground-runtime-specifiers.ts
@@ -23,6 +23,9 @@ const PLAYGROUND_THIRD_PARTY_SPECIFIERS = [
 	'zod',
 ] as const;
 
+/** Docs-only helpers that documented examples can import in the playground. */
+const PLAYGROUND_DOCS_SPECIFIERS = ['#docs/comparison'] as const;
+
 const packageJsonSchema = z.object({
 	exports: z.record(z.string(), z.string()),
 });
@@ -60,6 +63,7 @@ export function playgroundRuntimeSpecifierList(
 		...lukeUiPlaygroundSpecifiers(reactExports),
 		...PLAYGROUND_BASE_SPECIFIERS,
 		...PLAYGROUND_THIRD_PARTY_SPECIFIERS,
+		...PLAYGROUND_DOCS_SPECIFIERS,
 	];
 }
 
diff --git a/apps/docs/src/lib/remark-validate-examples.ts b/apps/docs/src/lib/remark-validate-examples.ts
index 673be04b..477bba5d 100644
--- a/apps/docs/src/lib/remark-validate-examples.ts
+++ b/apps/docs/src/lib/remark-validate-examples.ts
@@ -104,14 +104,16 @@ function findDocumentedExamples(docsDir: string, examplesDir: string): Set<strin
 
 function findImportedExamples(examplePath: string, examplesDir: string): Array<string> {
 	const importedExamples: Array<string> = [];
-	const importPattern = /\bfrom\s+["'](\.[^"']+)["']/g;
+	const importPattern = /\bfrom\s+["']((?:\.|#docs\/)[^"']+)["']/g;
 	const contents = readFileSync(examplePath, 'utf8');
 
 	for (const match of contents.matchAll(importPattern)) {
 		const importPath = match[1];
 		if (!importPath) continue;
 
-		const resolvedImportPath = resolve(examplePath, '..', importPath);
+		const resolvedImportPath = importPath.startsWith('#docs/')
+			? resolve(examplesDir, importPath.slice('#docs/'.length))
+			: resolve(examplePath, '..', importPath);
 		const importedPath = extname(resolvedImportPath)
 			? resolvedImportPath.replace(/\.js$/, '.tsx')
 			: `${resolvedImportPath}.tsx`;
diff --git a/docs/DOCUMENTATION.md b/docs/DOCUMENTATION.md
index f27a913f..a8e9b076 100644
--- a/docs/DOCUMENTATION.md
+++ b/docs/DOCUMENTATION.md
@@ -210,6 +210,8 @@ the code first.
 - In comparison examples, content may name the value being demonstrated when the content is only a
   specimen label, such as "Small", "Medium", and "Large". Keep those names in a caption beside the
   control, not in the control's own label.
+- Use a docs-only comparison helper when repeated caption and layout markup would hide the component
+  JSX. Keep each demonstrated component and its prop values visible in the example.
 - Do not use API terms as labels for interactive controls. When the control's purpose is incidental,
   use a neutral or self-referential label instead.
 - When an example needs extended text, choose a subject that helps explain why the component
@@ -219,14 +221,14 @@ the code first.
 - Keep the example as small as it can be without becoming artificial.
 - Choose one approach and show it. Do not present several interchangeable ways to reach the same
   result.
-- Do not demonstrate every value a prop accepts. Show the values a reader chooses between, and leave
-  the full list to the `## API` section.
-
-Exhaustive variant and state coverage belongs in the visual test kitchen sink, not in a docs
-example. See [TESTING.md](TESTING.md).
-
-A reference page is the exception. A token, typography, or icon page enumerates on purpose, because
-the enumeration is the content.
+- Show all values of one prop when readers need to compare the values or select one. Give all other
+  props the same value.
+- Combine values from two props only when the combination changes the result. Show only the
+  combinations that explain the change.
+- Do not show all prop combinations only to provide coverage. The Props page lists all available
+  props and values. Visual tests cover all valid combinations.
+
+A reference page can show a full scale or catalogue when the page is about that scale or catalogue.
 
 ### Prose around an example