From 2d4f0437a2030a74de99dcff333f946cb50ac08d Mon Sep 17 00:00:00 2001
From: Luke Bennett <hello@lukebennett.com.au>
Date: Wed, 15 Jul 2026 11:56:54 +1000
Subject: [PATCH] Migrate Icon, LoadingSpinner, and LoadingSkeleton (#118)

* Migrate loading feedback primitives (#102)

* Address PR review feedback

* Fix AllIcons story

* Make Storybook canvas fill previews

* Tune loading animations

* Set Storybook canvas foreground colour

* Improve LoadingSkeleton dark contrast
---
 .../loading-skeleton/border-radius.tsx        |   2 +-
 .../src/examples/loading-spinner/colors.tsx   |   4 +-
 .../@luke-ui/react/.storybook/preview.tsx     |  13 +-
 .../@luke-ui/react/src/icon/icon.stories.tsx  |  44 ++---
 .../react/src/icon/icon.visual.test.tsx       |  22 ++-
 .../react/src/loading-skeleton/index.tsx      |  11 +-
 .../loading-skeleton.stories.tsx              |  63 +++++++-
 .../loading-skeleton.visual.test.tsx          |  43 ++++-
 .../react/src/loading-spinner/index.tsx       |   2 +-
 .../loading-spinner.stories.tsx               |  42 ++++-
 .../loading-spinner.visual.test.tsx           |   8 +-
 .../@luke-ui/react/src/recipes/icon.css.ts    |   2 +-
 packages/@luke-ui/react/src/recipes/index.ts  |  12 +-
 .../recipes/loading-skeleton.browser.test.ts  | 152 ++++++++++++++++++
 .../react/src/recipes/loading-skeleton.css.ts |  45 ++++--
 .../recipes/loading-spinner.browser.test.ts   |  53 ++++++
 .../react/src/recipes/loading-spinner.css.ts  |  48 ++++--
 .../react/src/theme/build-theme.test.ts       |  14 ++
 .../@luke-ui/react/src/theme/build-theme.ts   |  16 +-
 packages/@luke-ui/react/src/theme/contract.ts |   1 +
 .../use-synchronize-animations.ts             |   4 +-
 21 files changed, 505 insertions(+), 96 deletions(-)
 create mode 100644 packages/@luke-ui/react/src/recipes/loading-skeleton.browser.test.ts
 create mode 100644 packages/@luke-ui/react/src/recipes/loading-spinner.browser.test.ts

diff --git a/apps/docs/src/examples/loading-skeleton/border-radius.tsx b/apps/docs/src/examples/loading-skeleton/border-radius.tsx
index 5d911a3b..7269a2ae 100644
--- a/apps/docs/src/examples/loading-skeleton/border-radius.tsx
+++ b/apps/docs/src/examples/loading-skeleton/border-radius.tsx
@@ -7,7 +7,7 @@ export default function BorderRadius() {
 
 	return (
 		<div style={{ display: 'flex', flexDirection: 'column', gap: '1rem', maxInlineSize: '20rem' }}>
-			<LoadingSkeleton borderRadius="0.25rem" isLoading={isLoading}>
+			<LoadingSkeleton isLoading={isLoading} radius="control">
 				<TextField label="Email" name="email" />
 			</LoadingSkeleton>
 			<label style={{ alignItems: 'center', display: 'flex', gap: '0.5rem' }}>
diff --git a/apps/docs/src/examples/loading-spinner/colors.tsx b/apps/docs/src/examples/loading-spinner/colors.tsx
index 2f717f9c..a04416a8 100644
--- a/apps/docs/src/examples/loading-spinner/colors.tsx
+++ b/apps/docs/src/examples/loading-spinner/colors.tsx
@@ -3,8 +3,8 @@ import { LoadingSpinner } from '@luke-ui/react/loading-spinner';
 export default function Colors() {
 	return (
 		<div style={{ alignItems: 'center', display: 'flex', gap: '1rem' }}>
-			<LoadingSpinner aria-label="Syncing" color="informative" />
-			<LoadingSpinner aria-label="Syncing" color="critical" />
+			<LoadingSpinner aria-label="Syncing" color="info" />
+			<LoadingSpinner aria-label="Syncing" color="danger" />
 		</div>
 	);
 }
diff --git a/packages/@luke-ui/react/.storybook/preview.tsx b/packages/@luke-ui/react/.storybook/preview.tsx
index b0f541c2..d6dc0f27 100644
--- a/packages/@luke-ui/react/.storybook/preview.tsx
+++ b/packages/@luke-ui/react/.storybook/preview.tsx
@@ -29,7 +29,14 @@ export default definePreview({
 					<div
 						className={`${themeRootClassName} ${themeClassName}`}
 						data-color-mode={colorMode}
-						style={{ backgroundColor: vars.color.surface.canvas }}
+						style={{
+							backgroundColor: vars.color.surface.canvas,
+							boxSizing: 'border-box',
+							color: vars.color.text.primary,
+							inlineSize: '100%',
+							minBlockSize: isStoryView ? '100vh' : undefined,
+							padding: vars.space[800],
+						}}
 					>
 						<Story />
 					</div>
@@ -78,6 +85,7 @@ export default definePreview({
 				date: /Date$/i,
 			},
 		},
+		layout: 'fullscreen',
 	},
 });
 
@@ -95,10 +103,12 @@ function StoryCanvasTheme({
 		const hadThemeClass = body.classList.contains(themeClassName);
 		const previousColorMode = body.getAttribute('data-color-mode');
 		const previousBackgroundColor = body.style.backgroundColor;
+		const previousColor = body.style.color;
 
 		body.classList.add(themeClassName);
 		body.dataset.colorMode = colorMode;
 		body.style.backgroundColor = vars.color.surface.canvas;
+		body.style.color = vars.color.text.primary;
 
 		return () => {
 			if (!hadThemeClass) body.classList.remove(themeClassName);
@@ -108,6 +118,7 @@ function StoryCanvasTheme({
 				body.dataset.colorMode = previousColorMode;
 			}
 			body.style.backgroundColor = previousBackgroundColor;
+			body.style.color = previousColor;
 		};
 	}, [colorMode, themeClassName]);
 
diff --git a/packages/@luke-ui/react/src/icon/icon.stories.tsx b/packages/@luke-ui/react/src/icon/icon.stories.tsx
index f3c1c3c8..e2d154e6 100644
--- a/packages/@luke-ui/react/src/icon/icon.stories.tsx
+++ b/packages/@luke-ui/react/src/icon/icon.stories.tsx
@@ -1,11 +1,11 @@
 import { Button } from '@luke-ui/react/button';
 import type { IconProps } from '@luke-ui/react/icon';
 import { createIcon, Icon, iconNames } from '@luke-ui/react/icon';
-import { tokenKeys, tokens } from '@luke-ui/react/tokens';
+import type { TextProps } from '@luke-ui/react/text';
+import { vars } from '@luke-ui/react/theme';
 import type { CSSProperties } from 'react';
 import { expect } from 'storybook/test';
 import preview from '../../.storybook/preview.js';
-import { vars } from '../theme.css.js';
 
 const meta = preview.meta({
 	component: Icon,
@@ -19,7 +19,12 @@ const baseArgs = {
 } as const satisfies Partial<IconProps>;
 
 const iconSizes: Array<NonNullable<IconProps['size']>> = ['xsmall', 'small', 'medium', 'large'];
-const colors = tokenKeys(tokens.foregroundColor);
+const colors = {
+	accent: vars.color.intent.accent.text,
+	danger: vars.color.intent.danger.text,
+	primary: vars.color.text.primary,
+	secondary: vars.color.text.secondary,
+} as const satisfies Partial<Record<NonNullable<TextProps['color']>, string>>;
 
 const wrapStyle = {
 	display: 'grid',
@@ -33,16 +38,6 @@ const iconItemStyle = {
 	gap: '0.5rem',
 } as const satisfies CSSProperties;
 
-const iconButtonStyle = {
-	blockSize: 'auto',
-	display: 'flex',
-	flexDirection: 'column',
-	gap: '1rem',
-	inlineSize: '100%',
-	paddingBlock: '2rem',
-	paddingInline: '1rem',
-} as const satisfies CSSProperties;
-
 const HeartIcon = createIcon({
 	path: (
 		<path d="M12 21a1 1 0 0 1-.7-.3L5 14.5a5 5 0 1 1 7-6 5 5 0 1 1 7 6l-6.3 6.2a1 1 0 0 1-.7.3Z" />
@@ -55,7 +50,13 @@ const HeartIcon = createIcon({
 export const Default = meta.story({
 	args: baseArgs,
 	play: async ({ canvas }) => {
-		await expect(canvas.getByRole('img', { name: 'add' })).toBeInTheDocument();
+		const icon = canvas.getByRole('img', { name: 'add' });
+		const iconStyles = getComputedStyle(icon);
+		const bodyStyles = getComputedStyle(document.body);
+		const primaryColor = bodyStyles.getPropertyValue('--luke-color-text-primary');
+
+		await expect(iconStyles.color).toBe(primaryColor);
+		await expect(bodyStyles.color).toBe(primaryColor);
 	},
 });
 
@@ -74,16 +75,16 @@ export const Sizes = meta.story({
 });
 
 /**
- * Icon color follows `currentColor`, so any foreground token can be applied.
+ * Icon color follows the semantic content color inherited from its parent.
  */
 export const Color = meta.story({
 	args: baseArgs,
 	render: (props) => (
 		<div style={wrapStyle}>
-			{colors.map((color) => (
-				<div key={color} style={iconItemStyle}>
-					<Icon {...props} style={{ color: vars.color[color] }} />
-					<span>{color}</span>
+			{Object.entries(colors).map(([name, color]) => (
+				<div key={name} style={{ ...iconItemStyle, color }}>
+					<Icon {...props} />
+					<span>{name}</span>
 				</div>
 			))}
 		</div>
@@ -127,13 +128,14 @@ export const AllIcons = meta.story({
 			{iconNames.map((name) => (
 				<li key={name} style={iconItemStyle}>
 					<Button
+						appearance="subtle"
+						isBlock
 						onPress={async () => {
 							await navigator.clipboard.writeText(name);
 						}}
-						style={iconButtonStyle}
+						startIcon={<Icon {...props} name={name} title={name} />}
 						tone="neutral"
 					>
-						<Icon {...props} name={name} title={name} />
 						{name}
 					</Button>
 				</li>
diff --git a/packages/@luke-ui/react/src/icon/icon.visual.test.tsx b/packages/@luke-ui/react/src/icon/icon.visual.test.tsx
index fc5e34ac..b4254142 100644
--- a/packages/@luke-ui/react/src/icon/icon.visual.test.tsx
+++ b/packages/@luke-ui/react/src/icon/icon.visual.test.tsx
@@ -1,11 +1,14 @@
 import type { CSSProperties } from 'react';
-import { test } from 'vite-plus/test';
+import { expect, test } from 'vite-plus/test';
 import {
 	captureVisual,
+	captureVisualAppearance,
 	renderVisual,
 	Stack,
 	variantValuesFor,
+	visualAppearances,
 } from '../test-utils/render-visual.js';
+import { vars } from '../theme/index.js';
 import { Icon } from './index.js';
 
 const rowStyle = {
@@ -41,3 +44,20 @@ test('sizes and glyphs', async () => {
 
 	await captureVisual(locator, 'icon/sizes-glyphs');
 });
+
+for (const appearance of visualAppearances) {
+	test(`semantic content inheritance: ${appearance.theme} ${appearance.mode}`, async () => {
+		const scene = renderVisual(
+			<div style={{ color: vars.color.intent.accent.text }}>
+				<Icon name="checkCircle" title="Inherited accent" />
+			</div>,
+			appearance,
+		);
+		const icon = scene.getByRole('img', { name: 'Inherited accent' });
+		const parent = icon.element().parentElement;
+		if (!parent) throw new Error('Expected icon parent.');
+
+		expect(getComputedStyle(icon.element()).color).toBe(getComputedStyle(parent).color);
+		await captureVisualAppearance(scene, 'icon/content-inheritance', appearance);
+	});
+}
diff --git a/packages/@luke-ui/react/src/loading-skeleton/index.tsx b/packages/@luke-ui/react/src/loading-skeleton/index.tsx
index 2da5d83a..eb3f8bcd 100644
--- a/packages/@luke-ui/react/src/loading-skeleton/index.tsx
+++ b/packages/@luke-ui/react/src/loading-skeleton/index.tsx
@@ -1,6 +1,7 @@
 import type { ComponentProps, ElementType, JSX, ReactNode } from 'react';
 import { createContext, isValidElement, useContext } from 'react';
 import * as styles from '../recipes/loading-skeleton.css.js';
+import { vars } from '../theme/contract.css.js';
 import { useSynchronizeAnimations } from '../use-synchronize-animations/use-synchronize-animations.js';
 import { cx } from '../utils/index.js';
 
@@ -33,10 +34,10 @@ export interface LoadingSkeletonProps extends ComponentProps<'span'> {
 	 */
 	as?: ElementType;
 	/**
-	 * Overrides the corner radius of the skeleton overlay. Use when the wrapped child has no radius of its own but
-	 * a visual descendant does (e.g. wrapping a `TextField`).
+	 * Sets the semantic corner radius of the skeleton overlay. Use when the wrapped child has no
+	 * radius of its own but a visual descendant does (e.g. wrapping a `TextField`).
 	 */
-	borderRadius?: string;
+	radius?: keyof typeof vars.radius;
 	/**
 	 * Whether the skeleton is shown in place of `children`. Overridden by a `LoadingSkeletonProvider` ancestor.
 	 * @default true
@@ -51,10 +52,10 @@ export interface LoadingSkeletonProps extends ComponentProps<'span'> {
 export function LoadingSkeleton(props: LoadingSkeletonProps): ReactNode {
 	const {
 		as: Component = 'span',
-		borderRadius,
 		children,
 		className,
 		isLoading: isLoadingProp,
+		radius,
 		style,
 		...spanProps
 	} = props;
@@ -76,7 +77,7 @@ export function LoadingSkeleton(props: LoadingSkeletonProps): ReactNode {
 			className={cx(styles.loadingSkeleton, className)}
 			data-skeleton-inline={isInline ? '' : undefined}
 			inert
-			style={borderRadius ? { ...style, [styles.skeletonBorderRadiusVar]: borderRadius } : style}
+			style={radius ? { ...style, [styles.skeletonRadiusVar]: vars.radius[radius] } : style}
 			tabIndex={-1}
 		>
 			{children}
diff --git a/packages/@luke-ui/react/src/loading-skeleton/loading-skeleton.stories.tsx b/packages/@luke-ui/react/src/loading-skeleton/loading-skeleton.stories.tsx
index 861a9162..93bbe1dd 100644
--- a/packages/@luke-ui/react/src/loading-skeleton/loading-skeleton.stories.tsx
+++ b/packages/@luke-ui/react/src/loading-skeleton/loading-skeleton.stories.tsx
@@ -1,6 +1,5 @@
 import { Button } from '@luke-ui/react/button';
 import { LoadingSkeleton, LoadingSkeletonProvider } from '@luke-ui/react/loading-skeleton';
-import { skeletonAnimationName } from '@luke-ui/react/recipes';
 import { Text } from '@luke-ui/react/text';
 import { TextField } from '@luke-ui/react/text-field';
 import type { CSSProperties } from 'react';
@@ -36,6 +35,33 @@ export const Default = meta.story({
 
 		await expect(skeleton).toHaveAttribute('aria-hidden', 'true');
 		await expect(skeleton).toHaveAttribute('tabIndex', '-1');
+		await expect(getComputedStyle(skeleton).color).toBe('rgba(0, 0, 0, 0)');
+
+		const [animation] = requireSkeletonAnimations(skeleton);
+		if (!animation?.effect) throw new Error('Expected skeleton animation effect.');
+
+		await expect(animation.effect.getTiming()).toMatchObject({
+			direction: 'normal',
+			duration: 2000,
+		});
+
+		try {
+			await expect(await samplePulseBrightness(skeleton, animation, 50)).toBe(1);
+			await expect(await samplePulseBrightness(skeleton, animation, 150)).toBe(1);
+
+			const outwardBrightness = await samplePulseBrightness(skeleton, animation, 600);
+			await expect(outwardBrightness).toBeGreaterThan(0.88);
+			await expect(outwardBrightness).toBeLessThan(1);
+
+			await expect(await samplePulseBrightness(skeleton, animation, 1050)).toBe(0.88);
+			await expect(await samplePulseBrightness(skeleton, animation, 1150)).toBe(0.88);
+
+			const returnBrightness = await samplePulseBrightness(skeleton, animation, 1600);
+			await expect(returnBrightness).toBeGreaterThan(0.88);
+			await expect(returnBrightness).toBeLessThan(1);
+		} finally {
+			animation.play();
+		}
 	},
 });
 
@@ -74,20 +100,23 @@ export const ElementType = meta.story({
 	),
 });
 
-/** Use `borderRadius` when the visible control is rounded below the direct child. */
-export const BorderRadius = meta.story({
+/** Use `radius` when the visible control is rounded below the direct child. */
+export const Radius = meta.story({
 	play: async ({ canvasElement }) => {
 		const skeletonSurface = requireElement(canvasElement, '[aria-hidden] > *');
 
 		await advanceSkeletonPulseToFadePoint(skeletonSurface);
 
 		const skeletonOverlayStyles = getComputedStyle(skeletonSurface, '::after');
+		const expectedRadius =
+			getComputedStyle(canvasElement).getPropertyValue('--luke-radius-control');
 
 		await expect(skeletonOverlayStyles.opacity).toBe('1');
+		await expect(skeletonOverlayStyles.borderRadius).toBe(expectedRadius);
 		await expect(getBrightnessFilterValue(skeletonOverlayStyles.filter)).toBeLessThanOrEqual(0.9);
 	},
 	render: () => (
-		<LoadingSkeleton borderRadius="0.25rem">
+		<LoadingSkeleton radius="control">
 			<TextField label="Email" name="email" />
 		</LoadingSkeleton>
 	),
@@ -146,12 +175,24 @@ async function advanceSkeletonPulseToFadePoint(element: Element) {
 		const timing = animation.effect?.getTiming();
 
 		animation.pause();
-		animation.currentTime = Number(timing?.delay ?? 0) + Number(timing?.duration ?? 0);
+		animation.currentTime = Number(timing?.delay ?? 0) + Number(timing?.duration ?? 0) * 0.5;
 	}
 
 	await new Promise(requestAnimationFrame);
 }
 
+async function samplePulseBrightness(
+	element: Element,
+	animation: CSSAnimation,
+	activeTime: number,
+) {
+	const timing = animation.effect?.getTiming();
+	animation.pause();
+	animation.currentTime = Number(timing?.delay ?? 0) + activeTime;
+	await new Promise(requestAnimationFrame);
+	return getBrightnessFilterValue(getComputedStyle(element).filter);
+}
+
 function getBrightnessFilterValue(filter: string) {
 	const match = /^brightness\((?<value>[\d.]+)\)$/.exec(filter);
 
@@ -173,9 +214,15 @@ function requireElement(parent: ParentNode, selector: string) {
 }
 
 function requireSkeletonAnimations(element: Element) {
-	const animations = element.getAnimations({ subtree: true }).filter((candidate) => {
-		return candidate instanceof CSSAnimation && candidate.animationName === skeletonAnimationName;
-	});
+	const animations = element
+		.getAnimations({ subtree: true })
+		.filter((candidate): candidate is CSSAnimation => {
+			return (
+				candidate instanceof CSSAnimation &&
+				candidate.effect instanceof KeyframeEffect &&
+				candidate.effect.target === element
+			);
+		});
 
 	if (animations.length === 0) {
 		throw new Error('Expected skeleton CSS animation.');
diff --git a/packages/@luke-ui/react/src/loading-skeleton/loading-skeleton.visual.test.tsx b/packages/@luke-ui/react/src/loading-skeleton/loading-skeleton.visual.test.tsx
index 45b0aba1..09946b2e 100644
--- a/packages/@luke-ui/react/src/loading-skeleton/loading-skeleton.visual.test.tsx
+++ b/packages/@luke-ui/react/src/loading-skeleton/loading-skeleton.visual.test.tsx
@@ -1,7 +1,13 @@
 import type { CSSProperties } from 'react';
-import { test } from 'vite-plus/test';
+import { expect, test } from 'vite-plus/test';
 import { Button } from '../button/index.js';
-import { captureVisual, renderVisual, Stack } from '../test-utils/render-visual.js';
+import {
+	captureVisual,
+	captureVisualAppearance,
+	renderVisual,
+	Stack,
+	visualAppearances,
+} from '../test-utils/render-visual.js';
 import { TextField } from '../text-field/index.js';
 import { LoadingSkeleton } from './index.js';
 
@@ -17,7 +23,7 @@ test('text and component placeholders', async () => {
 			<LoadingSkeleton>
 				<Button>Submit</Button>
 			</LoadingSkeleton>
-			<LoadingSkeleton borderRadius="4px">
+			<LoadingSkeleton radius="control">
 				<TextField label="Email" name="email" placeholder="Email address" />
 			</LoadingSkeleton>
 		</Stack>,
@@ -37,3 +43,34 @@ test('loaded content', async () => {
 
 	await captureVisual(locator, 'loading-skeleton/loaded');
 });
+
+test.each(visualAppearances)('flattens tactile descendants: $theme $mode', async (appearance) => {
+	const scene = renderVisual(
+		<LoadingSkeleton radius="surface">
+			<div>
+				<Button>Nested action</Button>
+				<TextField label="Email" name="email" />
+			</div>
+		</LoadingSkeleton>,
+		appearance,
+	);
+	const button = requireElement(scene.element(), 'button');
+	const field = requireElement(scene.element(), 'input');
+
+	for (const descendant of [button, field]) {
+		const style = getComputedStyle(descendant);
+		expect(style.backgroundColor).not.toBe('rgba(0, 0, 0, 0)');
+		expect(style.backgroundImage).toBe('none');
+		expect(style.borderStyle).toBe('none');
+		expect(style.boxShadow).toBe('none');
+		expect(style.color).toBe('rgba(0, 0, 0, 0)');
+	}
+
+	await captureVisualAppearance(scene, 'loading-skeleton/descendant-suppression', appearance);
+});
+
+function requireElement(parent: ParentNode, selector: string) {
+	const element = parent.querySelector(selector);
+	if (!element) throw new Error(`Expected element matching "${selector}".`);
+	return element;
+}
diff --git a/packages/@luke-ui/react/src/loading-spinner/index.tsx b/packages/@luke-ui/react/src/loading-spinner/index.tsx
index 304a6227..df07edd7 100644
--- a/packages/@luke-ui/react/src/loading-spinner/index.tsx
+++ b/packages/@luke-ui/react/src/loading-spinner/index.tsx
@@ -15,7 +15,7 @@ import { cx } from '../utils/index.js';
 interface LoadingSpinnerVariantProps extends NonNullable<styles.LoadingSpinnerVariants> {}
 
 interface LoadingSpinnerStyleProps {
-	/** Sets the spinner color. */
+	/** Sets a semantic content color. Omit to inherit the surrounding content color. */
 	color?: LoadingSpinnerVariantProps['color'];
 	/** Sets the spinner size. */
 	size?: LoadingSpinnerVariantProps['size'];
diff --git a/packages/@luke-ui/react/src/loading-spinner/loading-spinner.stories.tsx b/packages/@luke-ui/react/src/loading-spinner/loading-spinner.stories.tsx
index 38cfa16a..99d5a2d1 100644
--- a/packages/@luke-ui/react/src/loading-spinner/loading-spinner.stories.tsx
+++ b/packages/@luke-ui/react/src/loading-spinner/loading-spinner.stories.tsx
@@ -1,7 +1,6 @@
 import type { LoadingSpinnerProps } from '@luke-ui/react/loading-spinner';
 import { LoadingSpinner } from '@luke-ui/react/loading-spinner';
-import { spinAnimationName } from '@luke-ui/react/recipes';
-import { tokenKeys, tokens } from '@luke-ui/react/tokens';
+import { vars } from '@luke-ui/react/theme';
 import type { CSSProperties } from 'react';
 import { useState } from 'react';
 import { expect, userEvent } from 'storybook/test';
@@ -39,6 +38,22 @@ export const Default = meta.story({
 	},
 });
 
+/** Use a value when progress can be measured against a known range. */
+export const Determinate = meta.story({
+	args: {
+		'aria-label': 'Uploading',
+		maxValue: 200,
+		minValue: 100,
+		value: 175,
+	},
+	play: async ({ canvas }) => {
+		await expect(canvas.getByRole('progressbar', { name: 'Uploading' })).toHaveAttribute(
+			'aria-valuenow',
+			'175',
+		);
+	},
+});
+
 const sizes: Array<NonNullable<LoadingSpinnerProps['size']>> = ['small', 'medium'];
 
 /**
@@ -55,17 +70,27 @@ export const Size = meta.story({
 	),
 });
 
-const colors = tokenKeys(tokens.foregroundColor);
+const colors = ['primary', 'secondary', 'accent', 'info', 'success', 'warning', 'danger'] as const;
 
 /**
- * Spinner color can use any design-system foreground color token.
+ * Spinner color can use semantic content roles, or inherit its parent's color when omitted.
  */
 export const Color = meta.story({
 	args: baseArgs,
+	play: async ({ canvas }) => {
+		const inherited = canvas.getByRole('progressbar', { name: 'Inherited accent' });
+		const parent = inherited.parentElement;
+		if (!parent) throw new Error('Expected spinner parent.');
+
+		await expect(getComputedStyle(inherited).color).toBe(getComputedStyle(parent).color);
+	},
 	render: (props) => (
 		<div style={flexRowStyle}>
+			<div style={{ color: vars.color.intent.accent.text }}>
+				<LoadingSpinner {...props} aria-label="Inherited accent" />
+			</div>
 			{colors.map((color) => (
-				<LoadingSpinner color={color} key={color} {...props} />
+				<LoadingSpinner {...props} aria-label={color} color={color} key={color} />
 			))}
 		</div>
 	),
@@ -117,6 +142,11 @@ function StaggeredSpinners(props: LoadingSpinnerProps) {
 
 function findSpinAnimations(root: Element): Array<CSSAnimation> {
 	return root.getAnimations({ subtree: true }).filter((animation): animation is CSSAnimation => {
-		return animation instanceof CSSAnimation && animation.animationName === spinAnimationName;
+		return (
+			animation instanceof CSSAnimation &&
+			animation.effect instanceof KeyframeEffect &&
+			animation.effect.target instanceof HTMLElement &&
+			animation.effect.target.getAttribute('role') === 'progressbar'
+		);
 	});
 }
diff --git a/packages/@luke-ui/react/src/loading-spinner/loading-spinner.visual.test.tsx b/packages/@luke-ui/react/src/loading-spinner/loading-spinner.visual.test.tsx
index 26720b2e..12d97513 100644
--- a/packages/@luke-ui/react/src/loading-spinner/loading-spinner.visual.test.tsx
+++ b/packages/@luke-ui/react/src/loading-spinner/loading-spinner.visual.test.tsx
@@ -18,11 +18,7 @@ const rowStyle = {
 } satisfies CSSProperties;
 
 const sizes = variantValuesFor<typeof LoadingSpinner, 'size'>()(['small', 'medium', 'large']);
-const colors = variantValuesFor<typeof LoadingSpinner, 'color'>()([
-	'neutralBold',
-	'informative',
-	'critical',
-]);
+const colors = variantValuesFor<typeof LoadingSpinner, 'color'>()(['primary', 'info', 'danger']);
 
 test('sizes colors and modes', async () => {
 	const locator = renderVisual(
@@ -52,7 +48,7 @@ test.each(visualAppearances)('theme matrix: $theme $mode', async (appearance) =>
 	const scene = renderVisual(
 		<div style={themeMatrixStyle}>
 			<ThemeMatrixScope label="Root scope">
-				<LoadingSpinner aria-label="Root theme" style={spinnerStyle} value={65} />
+				<LoadingSpinner aria-label="Root theme pending" style={spinnerStyle} />
 			</ThemeMatrixScope>
 			<ThemeMatrixScope label="Opposite mode" mode={oppositeMode}>
 				<LoadingSpinner aria-label="Opposite mode theme" style={spinnerStyle} value={65} />
diff --git a/packages/@luke-ui/react/src/recipes/icon.css.ts b/packages/@luke-ui/react/src/recipes/icon.css.ts
index c8711807..42e7a43d 100644
--- a/packages/@luke-ui/react/src/recipes/icon.css.ts
+++ b/packages/@luke-ui/react/src/recipes/icon.css.ts
@@ -1,6 +1,6 @@
 import type { RecipeVariants } from '@vanilla-extract/recipes';
 import { recipeInLayer } from '../styles/layered-style.css.js';
-import { vars } from '../styles/vars.css.js';
+import { vars } from '../theme/contract.css.js';
 
 /** Shared size dimensions for Icon and LoadingSpinner (icon-aligned sizing). */
 export const iconSizeVariants = {
diff --git a/packages/@luke-ui/react/src/recipes/index.ts b/packages/@luke-ui/react/src/recipes/index.ts
index 49f46e7a..00806596 100644
--- a/packages/@luke-ui/react/src/recipes/index.ts
+++ b/packages/@luke-ui/react/src/recipes/index.ts
@@ -7,17 +7,9 @@ export type { IconButtonVariants } from '../recipes/icon-button.css.js';
 export { iconButton } from '../recipes/icon-button.css.js';
 export type { LinkVariants } from '../recipes/link.css.js';
 export { link } from '../recipes/link.css.js';
-export {
-	loadingSkeleton,
-	skeletonAnimationName,
-	skeletonBorderRadiusVar,
-} from '../recipes/loading-skeleton.css.js';
+export { loadingSkeleton } from '../recipes/loading-skeleton.css.js';
 export type { LoadingSpinnerVariants } from '../recipes/loading-spinner.css.js';
-export {
-	rubberBandAnimationName,
-	spinAnimationName,
-	spinner as loadingSpinner,
-} from '../recipes/loading-spinner.css.js';
+export { spinner as loadingSpinner } from '../recipes/loading-spinner.css.js';
 export type {
 	TextAlign,
 	TextColor,
diff --git a/packages/@luke-ui/react/src/recipes/loading-skeleton.browser.test.ts b/packages/@luke-ui/react/src/recipes/loading-skeleton.browser.test.ts
new file mode 100644
index 00000000..11e21486
--- /dev/null
+++ b/packages/@luke-ui/react/src/recipes/loading-skeleton.browser.test.ts
@@ -0,0 +1,152 @@
+import '@luke-ui/react/themes/elmo.css';
+import '@luke-ui/react/themes/machined-edge.css';
+import { afterEach, expect, test } from 'vite-plus/test';
+import { cdp } from 'vite-plus/test/context';
+import { contrastRatio, parseColor } from '../theme/color.js';
+import { themeRootClassName } from '../theme/index.js';
+import { elmoThemeClassName, machinedEdgeThemeClassName } from '../themes/index.js';
+import { loadingSkeleton } from './loading-skeleton.css.js';
+
+let root: HTMLElement | undefined;
+
+const themeCases = [
+	{ className: machinedEdgeThemeClassName, name: 'Machined edge' },
+	{ className: elmoThemeClassName, name: 'ELMO' },
+] as const;
+
+afterEach(async () => {
+	root?.remove();
+	root = undefined;
+	await setEmulatedMedia();
+});
+
+test('forced colors keeps the static skeleton surface visible', async () => {
+	await setEmulatedMedia('forced-colors', 'active');
+	const skeleton = mountInlineSkeleton();
+	const style = getComputedStyle(skeleton);
+
+	expect(style.animationName).toBe('none');
+	expect(style.backgroundColor).toBe(resolveSystemColor('CanvasText'));
+	expect(style.forcedColorAdjust).toBe('none');
+});
+
+test('reduced motion keeps the skeleton surface without a running animation', async () => {
+	await setEmulatedMedia('prefers-reduced-motion', 'reduce');
+	const skeleton = mountInlineSkeleton();
+	const style = getComputedStyle(skeleton);
+
+	expect(style.animationName).toBe('none');
+	expect(style.backgroundColor).not.toBe('rgba(0, 0, 0, 0)');
+});
+
+for (const theme of themeCases) {
+	for (const mode of ['light', 'dark'] as const) {
+		test(`${theme.name} ${mode} keeps both pulse extremes distinct from the canvas`, async () => {
+			const skeleton = mountInlineSkeleton(theme.className, mode);
+			const canvasColor = getComputedStyle(requireRoot()).backgroundColor;
+			const animation = requireAnimation(skeleton);
+
+			const brightRatio = await samplePulseContrast(skeleton, animation, canvasColor, 50);
+			const dimRatio = await samplePulseContrast(skeleton, animation, canvasColor, 1050);
+
+			expect(Math.min(brightRatio, dimRatio)).toBeGreaterThanOrEqual(1.4);
+		});
+	}
+}
+
+function mountInlineSkeleton(
+	themeClassName = machinedEdgeThemeClassName,
+	mode: 'light' | 'dark' = 'light',
+) {
+	root = document.body.appendChild(document.createElement('div'));
+	root.className = `${themeRootClassName} ${themeClassName}`;
+	root.dataset.colorMode = mode;
+	root.style.backgroundColor = 'var(--luke-color-surface-canvas)';
+	const skeleton = root.appendChild(document.createElement('span'));
+	skeleton.className = loadingSkeleton;
+	skeleton.dataset.skeletonInline = '';
+	return skeleton;
+}
+
+function requireRoot() {
+	if (!root) throw new Error('Expected theme root.');
+	return root;
+}
+
+function requireAnimation(element: Element) {
+	const animation = element.getAnimations()[0];
+	if (!animation) throw new Error('Expected skeleton animation.');
+	return animation;
+}
+
+async function samplePulseContrast(
+	element: Element,
+	animation: Animation,
+	canvasColor: string,
+	activeTime: number,
+) {
+	animation.pause();
+	animation.currentTime = 500 + activeTime;
+	await new Promise(requestAnimationFrame);
+	const style = getComputedStyle(element);
+	return contrastRatio(
+		parseColor(rgbToHex(applyBrightness(style.backgroundColor, brightnessValue(style.filter)))),
+		parseColor(rgbToHex(cssColorToRgb(canvasColor))),
+	);
+}
+
+function brightnessValue(filter: string) {
+	const match = /^brightness\((?<value>[\d.]+)\)$/.exec(filter);
+	if (!match?.groups?.value) throw new Error(`Expected brightness filter, received "${filter}".`);
+	return Number(match.groups.value);
+}
+
+interface Rgb {
+	b: number;
+	g: number;
+	r: number;
+}
+
+function cssColorToRgb(color: string): Rgb {
+	const canvas = document.createElement('canvas');
+	canvas.width = 1;
+	canvas.height = 1;
+	const context = canvas.getContext('2d');
+	if (!context) throw new Error('Expected canvas context.');
+	context.fillStyle = color;
+	context.fillRect(0, 0, 1, 1);
+	const [r, g, b] = context.getImageData(0, 0, 1, 1).data;
+	if (r === undefined || g === undefined || b === undefined) {
+		throw new Error(`Expected RGB channels for "${color}".`);
+	}
+	return { b, g, r };
+}
+
+function applyBrightness(color: string, brightness: number): Rgb {
+	const rgb = cssColorToRgb(color);
+	return {
+		b: Math.min(rgb.b * brightness, 255),
+		g: Math.min(rgb.g * brightness, 255),
+		r: Math.min(rgb.r * brightness, 255),
+	};
+}
+
+function rgbToHex(color: Rgb) {
+	const channel = (value: number) => Math.round(value).toString(16).padStart(2, '0');
+	return `#${channel(color.r)}${channel(color.g)}${channel(color.b)}`;
+}
+
+function resolveSystemColor(color: string) {
+	if (!root) throw new Error('Expected theme root.');
+	const probe = root.appendChild(document.createElement('div'));
+	probe.style.color = color;
+	const value = getComputedStyle(probe).color;
+	probe.remove();
+	return value;
+}
+
+async function setEmulatedMedia(name?: string, value?: string) {
+	await cdp().send('Emulation.setEmulatedMedia', {
+		features: name === undefined || value === undefined ? [] : [{ name, value }],
+	});
+}
diff --git a/packages/@luke-ui/react/src/recipes/loading-skeleton.css.ts b/packages/@luke-ui/react/src/recipes/loading-skeleton.css.ts
index 5d7be593..f3eebe83 100644
--- a/packages/@luke-ui/react/src/recipes/loading-skeleton.css.ts
+++ b/packages/@luke-ui/react/src/recipes/loading-skeleton.css.ts
@@ -1,19 +1,21 @@
 import type { StyleRule } from '@vanilla-extract/css';
-import { keyframes } from '@vanilla-extract/css';
+import { fallbackVar, keyframes } from '@vanilla-extract/css';
 import { globalStyleInLayer, styleInLayer } from '../styles/layered-style.css.js';
-import { vars } from '../styles/vars.css.js';
+import { vars } from '../theme/contract.css.js';
 
 /**
- * Generated name of the skeleton pulse animation. Pass to `useSynchronizeAnimations` so every mounted skeleton
- * pulses in lockstep.
+ * @internal
  */
 export const skeletonAnimationName = keyframes({
-	from: { filter: 'brightness(1)' },
-	to: { filter: 'brightness(0.88)' },
+	'0%': { filter: 'brightness(1)' },
+	'10%': { filter: 'brightness(1)' },
+	'50%': { filter: 'brightness(0.88)' },
+	'60%': { filter: 'brightness(0.88)' },
+	'100%': { filter: 'brightness(1)' },
 });
 
-/** Custom property that sets the corner radius of the skeleton overlay painted on wrapped children. */
-export const skeletonBorderRadiusVar = '--luke-ui-loading-skeleton-border-radius';
+/** @internal */
+export const skeletonRadiusVar = '--luke-loading-skeleton-radius';
 
 // Forced onto every skeleton surface so an arbitrary wrapped component reads as a flat placeholder shape.
 // `!important` is deliberate: cascade layers alone can't beat consumers' un-layered or inline styles, and the
@@ -21,7 +23,7 @@ export const skeletonBorderRadiusVar = '--luke-ui-loading-skeleton-border-radius
 // admit the `!important` suffix in their type.
 const surface = {
 	backgroundClip: 'border-box !important',
-	backgroundColor: `${vars.backgroundColor.neutralBold} !important`,
+	backgroundColor: `${vars.color.loadingSkeleton} !important`,
 	backgroundImage: 'none !important',
 	border: 'none !important',
 	// Text spanning multiple lines keeps its radius on every line fragment.
@@ -34,15 +36,23 @@ const surface = {
 	userSelect: 'none !important' as 'none',
 } as const satisfies StyleRule;
 
+const forcedColorsSurface = {
+	backgroundColor: 'CanvasText !important',
+	forcedColorAdjust: 'none !important' as 'none',
+} as const satisfies StyleRule;
+
 // Not `!important`: reduced-motion overrides (below) and animation syncing must stay able to adjust it.
 const pulse = {
 	animationDelay: '0.5s',
-	animationDirection: 'alternate',
-	animationDuration: vars.motion.duration.slow,
+	animationDuration: '2s',
 	animationIterationCount: 'infinite',
 	animationName: skeletonAnimationName,
-	animationTimingFunction: vars.motion.easing.emphasized,
+	animationTimingFunction: vars.motion.easing.standard,
 	'@media': {
+		'(forced-colors: active)': {
+			...forcedColorsSurface,
+			animationName: 'none',
+		},
 		// The global reduced-motion reset lives in the lowest layer, so it can't win against this rule.
 		'(prefers-reduced-motion: reduce)': {
 			animationName: 'none',
@@ -57,7 +67,7 @@ export const loadingSkeleton = styleInLayer('utilities', {
 		'&[data-skeleton-inline]': {
 			...surface,
 			...pulse,
-			borderRadius: vars.borderRadius.small,
+			borderRadius: fallbackVar(`var(${skeletonRadiusVar})`, vars.radius.detail),
 		},
 		// Block mode: the wrapper is invisible; skeleton styles apply to its direct children.
 		'&:not([data-skeleton-inline])': {
@@ -73,12 +83,19 @@ globalStyleInLayer('utilities', `${loadingSkeleton}:not([data-skeleton-inline])
 	position: 'relative !important' as 'relative',
 });
 
+globalStyleInLayer('utilities', `${loadingSkeleton}:not([data-skeleton-inline]) > * *`, {
+	'@media': {
+		'(forced-colors: active)': forcedColorsSurface,
+	},
+	...surface,
+});
+
 // A pseudo-element painted over the child covers visuals the forced styles can't reach (nested backgrounds,
 // rounded corners); `inset: -1px` also covers the child's border box edges.
 globalStyleInLayer('utilities', `${loadingSkeleton}:not([data-skeleton-inline]) > *::after`, {
 	...surface,
 	...pulse,
-	borderRadius: `var(${skeletonBorderRadiusVar}, 0px)`,
+	borderRadius: `var(${skeletonRadiusVar}, 0px)`,
 	content: '""',
 	inset: '-1px',
 	position: 'absolute',
diff --git a/packages/@luke-ui/react/src/recipes/loading-spinner.browser.test.ts b/packages/@luke-ui/react/src/recipes/loading-spinner.browser.test.ts
new file mode 100644
index 00000000..8bb135e1
--- /dev/null
+++ b/packages/@luke-ui/react/src/recipes/loading-spinner.browser.test.ts
@@ -0,0 +1,53 @@
+import { afterEach, expect, test } from 'vite-plus/test';
+import { cdp } from 'vite-plus/test/context';
+import { indicator, spinnerState } from './loading-spinner.css.js';
+
+const mounted: Array<Element> = [];
+
+afterEach(async () => {
+	for (const element of mounted) element.remove();
+	mounted.length = 0;
+	await setEmulatedMedia();
+});
+
+test('indeterminate spinner uses the original rotation and rubber-band timing', () => {
+	const { ring, spinner } = mountSpinner();
+	const spinnerStyle = getComputedStyle(spinner);
+	const ringStyle = getComputedStyle(ring);
+
+	expect(spinnerStyle.animationDuration).toBe('1.2s');
+	expect(spinnerStyle.animationTimingFunction).toBe('linear');
+	expect(ringStyle.animationDuration).toBe('2s');
+	expect(ringStyle.animationTimingFunction).toBe('cubic-bezier(0.42, 0, 0.58, 1)');
+});
+
+for (const [name, value] of [
+	['forced-colors', 'active'],
+	['prefers-reduced-motion', 'reduce'],
+] as const) {
+	test(`${name} renders an indeterminate spinner as a static partial ring`, async () => {
+		await setEmulatedMedia(name, value);
+		const { ring, spinner } = mountSpinner();
+
+		expect(getComputedStyle(spinner).animationName).toBe('none');
+		expect(getComputedStyle(ring).animationName).toBe('none');
+		expect(getComputedStyle(ring).strokeDasharray).toBe('25px, 100px');
+		expect(getComputedStyle(ring).strokeDashoffset).toBe('0px');
+	});
+}
+
+function mountSpinner() {
+	const spinner = document.body.appendChild(document.createElement('div'));
+	spinner.className = spinnerState({ mode: 'indeterminate' });
+	const svg = spinner.appendChild(document.createElementNS('http://www.w3.org/2000/svg', 'svg'));
+	const ring = svg.appendChild(document.createElementNS('http://www.w3.org/2000/svg', 'circle'));
+	ring.setAttribute('class', indicator({ mode: 'indeterminate' }));
+	mounted.push(spinner);
+	return { ring, spinner };
+}
+
+async function setEmulatedMedia(name?: string, value?: string) {
+	await cdp().send('Emulation.setEmulatedMedia', {
+		features: name === undefined || value === undefined ? [] : [{ name, value }],
+	});
+}
diff --git a/packages/@luke-ui/react/src/recipes/loading-spinner.css.ts b/packages/@luke-ui/react/src/recipes/loading-spinner.css.ts
index 3dd76ef3..83d7c251 100644
--- a/packages/@luke-ui/react/src/recipes/loading-spinner.css.ts
+++ b/packages/@luke-ui/react/src/recipes/loading-spinner.css.ts
@@ -1,14 +1,22 @@
 import { keyframes } from '@vanilla-extract/css';
 import type { RecipeVariants } from '@vanilla-extract/recipes';
 import { recipeInLayer, styleInLayer } from '../styles/layered-style.css.js';
-import { vars } from '../styles/vars.css.js';
-import { tokenKeys } from '../tokens/groups.js';
-import { tokens } from '../tokens/index.js';
+import { vars } from '../theme/contract.css.js';
 import { iconSizeVariants } from './icon.css.js';
 
-const colorKeys = tokenKeys(tokens.foregroundColor);
+const rotationDuration = '1.2s';
+const rubberBandDuration = '2s';
+const rubberBandEasing = 'cubic-bezier(0.42, 0, 0.58, 1)';
 
-const colorVariants = Object.fromEntries(colorKeys.map((key) => [key, { color: vars.color[key] }]));
+const colorVariants = {
+	accent: { color: vars.color.intent.accent.text },
+	danger: { color: vars.color.intent.danger.text },
+	info: { color: vars.color.intent.info.text },
+	primary: { color: vars.color.text.primary },
+	secondary: { color: vars.color.text.secondary },
+	success: { color: vars.color.intent.success.text },
+	warning: { color: vars.color.intent.warning.text },
+} as const;
 
 const base = styleInLayer('recipes', {
 	color: 'currentColor',
@@ -31,7 +39,7 @@ export const spinner = recipeInLayer('recipes', {
 /** Variant type for the `LoadingSpinner` recipe. */
 export type LoadingSpinnerVariants = RecipeVariants<typeof spinner>;
 
-/** Generated name of the spinner's rotation animation. Pass to `useSynchronizeAnimations` so every mounted spinner rotates in lockstep. */
+/** @internal */
 export const spinAnimationName = keyframes({
 	to: { transform: 'rotate(360deg)' },
 });
@@ -44,10 +52,14 @@ export const spinnerState = recipeInLayer('recipes', {
 		mode: {
 			determinate: {},
 			indeterminate: {
-				animationDuration: vars.motion.duration.slow,
+				'@media': {
+					'(forced-colors: active)': { animationName: 'none' },
+					'(prefers-reduced-motion: reduce)': { animationName: 'none' },
+				},
+				animationDuration: rotationDuration,
 				animationIterationCount: 'infinite',
 				animationName: spinAnimationName,
-				animationTimingFunction: vars.motion.easing.linear,
+				animationTimingFunction: 'linear',
 			},
 		},
 	},
@@ -62,7 +74,7 @@ export const svg = recipeInLayer('recipes', {
 	},
 });
 
-/** Generated name of the spinner indicator's rubber-band animation. Pass to `useSynchronizeAnimations` so every mounted spinner pulses in lockstep. */
+/** @internal */
 export const rubberBandAnimationName = keyframes({
 	'0%': { strokeDasharray: '2 100' },
 	'50%': { strokeDasharray: '65 100', strokeDashoffset: -20 },
@@ -79,15 +91,27 @@ export const indicator = recipeInLayer('recipes', {
 	variants: {
 		mode: {
 			determinate: {
-				transitionDuration: vars.motion.duration.quick,
+				transitionDuration: vars.motion.duration.fast,
 				transitionProperty: 'stroke-dashoffset',
 				transitionTimingFunction: vars.motion.easing.exit,
 			},
 			indeterminate: {
-				animationDuration: vars.motion.duration.slower,
+				'@media': {
+					'(forced-colors: active)': {
+						animationName: 'none',
+						strokeDasharray: '25 100',
+						strokeDashoffset: 0,
+					},
+					'(prefers-reduced-motion: reduce)': {
+						animationName: 'none',
+						strokeDasharray: '25 100',
+						strokeDashoffset: 0,
+					},
+				},
+				animationDuration: rubberBandDuration,
 				animationIterationCount: 'infinite',
 				animationName: rubberBandAnimationName,
-				animationTimingFunction: vars.motion.easing.emphasized,
+				animationTimingFunction: rubberBandEasing,
 			},
 		},
 	},
diff --git a/packages/@luke-ui/react/src/theme/build-theme.test.ts b/packages/@luke-ui/react/src/theme/build-theme.test.ts
index 23fa0a3b..d737c6b2 100644
--- a/packages/@luke-ui/react/src/theme/build-theme.test.ts
+++ b/packages/@luke-ui/react/src/theme/build-theme.test.ts
@@ -116,6 +116,7 @@ describe('buildTheme output', () => {
 
 	it('uses the stable kebab-case variable names', () => {
 		expect(css).toContain('--luke-color-intent-danger-surface-solid-hover');
+		expect(css).toContain('--luke-color-loading-skeleton');
 		expect(css).toContain('--luke-color-surface-disabled');
 		expect(css).toContain('--luke-color-intent-accent-text-hover');
 		expect(css).toContain('--luke-depth-raised');
@@ -475,6 +476,19 @@ describe('bundled themes meet WCAG 2.2 AA', () => {
 	}
 });
 
+describe('bundled loading skeleton surfaces', () => {
+	for (const foundation of [machinedEdgeFoundation, elmoFoundation]) {
+		it(`${foundation.name} keeps loading skeletons distinct from the canvas in both modes`, () => {
+			const blocks = splitBlocks(buildTheme(foundation));
+			for (const block of [blocks.baseLight, blocks.mediaDark]) {
+				const canvas = parseColor(extractValue(block, '--luke-color-surface-canvas'));
+				const skeleton = parseColor(extractValue(block, '--luke-color-loading-skeleton'));
+				expect(contrastRatio(skeleton, canvas)).toBeGreaterThanOrEqual(1.4);
+			}
+		});
+	}
+});
+
 describe('bundled theme identity', () => {
 	it('exports class-name constants that match the emitted identity classes', () => {
 		expect(machinedEdgeThemeClassName).toBe('luke-ui-theme-machined-edge');
diff --git a/packages/@luke-ui/react/src/theme/build-theme.ts b/packages/@luke-ui/react/src/theme/build-theme.ts
index 231fdbe2..7f39974a 100644
--- a/packages/@luke-ui/react/src/theme/build-theme.ts
+++ b/packages/@luke-ui/react/src/theme/build-theme.ts
@@ -89,8 +89,11 @@ type ColorMode = 'light' | 'dark';
 const THEME_NAME_PATTERN = /^[a-z][a-z0-9]*(-[a-z0-9]+)*$/;
 const TEXT_RATIO = 4.5;
 const UI_RATIO = 3;
-// Solve slightly past the required ratio so 4-decimal OKLCH emission cannot round a passing pair
-// below the WCAG threshold.
+// Skeletons are decorative, so this is a perceptual distinction target rather than a WCAG
+// requirement. Dark mode needs more headroom because the brightness pulse moves toward the canvas.
+const LOADING_SKELETON_RATIOS = { dark: 1.75, light: 1.4 } as const;
+// Solve slightly past the requested ratio so 4-decimal OKLCH emission cannot round a passing pair
+// below its target.
 const RATIO_HEADROOM = 0.05;
 
 const INTENT_NAMES = ['neutral', 'accent', 'info', 'success', 'warning', 'danger'] as const;
@@ -264,6 +267,15 @@ function buildModeColors(
 		'color.surface.floating': surfaces.floating,
 		'color.surface.overlay': surfaces.overlay,
 	};
+	colors['color.loadingSkeleton'] = solveLightness({
+		backgrounds: [canvas],
+		chroma: Math.min(neutral.c, 0.01),
+		hue: neutral.h,
+		mode,
+		ratio: LOADING_SKELETON_RATIOS[mode],
+		startLightness: canvas.l,
+		window: isLight ? [0, canvas.l] : [canvas.l, 1],
+	});
 
 	colors['color.text.primary'] = solveLightness({
 		backgrounds: allSurfaces,
diff --git a/packages/@luke-ui/react/src/theme/contract.ts b/packages/@luke-ui/react/src/theme/contract.ts
index 51731171..a6d4c38d 100644
--- a/packages/@luke-ui/react/src/theme/contract.ts
+++ b/packages/@luke-ui/react/src/theme/contract.ts
@@ -15,6 +15,7 @@ export const themeContractTree = {
 	color: {
 		surface: { canvas: null, resting: null, recessed: null, floating: null, overlay: null },
 		surfaceDisabled: null,
+		loadingSkeleton: null,
 		text: { primary: null, secondary: null },
 		textDisabled: null,
 		border: { decorative: null, control: null, focus: null },
diff --git a/packages/@luke-ui/react/src/use-synchronize-animations/use-synchronize-animations.ts b/packages/@luke-ui/react/src/use-synchronize-animations/use-synchronize-animations.ts
index f3ce2b8c..5d3f4235 100644
--- a/packages/@luke-ui/react/src/use-synchronize-animations/use-synchronize-animations.ts
+++ b/packages/@luke-ui/react/src/use-synchronize-animations/use-synchronize-animations.ts
@@ -7,8 +7,8 @@ const useIsomorphicLayoutEffect = typeof window !== 'undefined' ? useLayoutEffec
  * Synchronises the CSS animation identified by `animationName` across every element currently playing it, so they
  * all pulse in lockstep rather than each starting from their own offset.
  *
- * Pass the animation name string (e.g. `skeletonAnimationName`), or a falsy value to skip syncing (e.g. when the
- * animated element isn't rendered).
+ * Pass an animation name string, or a falsy value to skip syncing when the animated element isn't
+ * rendered.
  */
 export function useSynchronizeAnimations(animationName: string | null | undefined): void {
 	useIsomorphicLayoutEffect(() => {
-- 
2.51.2