@unpunnyfuns/swatchbook-blocks 0.60.9 → 0.62.1

package/dist/index.mjs

@@ -1,5 +1,6 @@
 import './style.css';
-import Color from "colorjs.io";
+import { COLOR_FORMATS } from "@unpunnyfuns/swatchbook-core/color-formats";
+import { formatColor, parseColor } from "@unpunnyfuns/swatchbook-core/format-color";
 import { createContext, memo, useCallback, useContext, useDeferredValue, useEffect, useMemo, useRef, useState, useSyncExternalStore } from "react";
 import { Fragment, jsx, jsxs } from "react/jsx-runtime";
 import { getVariance, listPaths, resolveAllAt } from "@unpunnyfuns/swatchbook-core/graph";
@@ -7,188 +8,18 @@ import { makeCssVar } from "@unpunnyfuns/swatchbook-core/css-var";
 import { SWATCHBOOK_STYLE_ELEMENT_ID, ensureStyleElement } from "@unpunnyfuns/swatchbook-core/style-element";
 import { tupleToName } from "@unpunnyfuns/swatchbook-core/themes";
 import { addons } from "storybook/preview-api";
-import { axes, css, cssVarPrefix, defaultTuple, diagnostics, listing, presets, tokenGraph } from "virtual:swatchbook/tokens";
 import { dataAttr } from "@unpunnyfuns/swatchbook-core/data-attr";
 import { matchPath } from "@unpunnyfuns/swatchbook-core/match-path";
 import { fuzzyFilter } from "@unpunnyfuns/swatchbook-core/fuzzy";
 import cx from "clsx";
-//#region src/format-color.ts
-const COLOR_FORMATS = [
-	"hex",
-	"rgb",
-	"hsl",
-	"oklch",
-	"raw"
-];
-const DEFAULT_FALLBACK = "—";
-/**
-* Convert Terrazzo's normalized color payload into a display string in the
-* requested format. Pure function — never throws; returns `{ value: '—' }`
-* for unrecognized input so calling blocks don't need try/catch.
-*/
-function formatColor(value, format, fallback = DEFAULT_FALLBACK) {
-	const normalized = coerce(value);
-	if (!normalized) return {
-		value: stringifyFallback(value, fallback),
-		outOfGamut: false
-	};
-	if (format === "raw") return {
-		value: compactJson(normalized),
-		outOfGamut: false
-	};
-	const color = toColor(normalized);
-	if (!color) return {
-		value: stringifyFallback(value, fallback),
-		outOfGamut: false
-	};
-	const alpha = typeof normalized.alpha === "number" ? normalized.alpha : 1;
-	if (format === "hex") return formatHex(color, alpha);
-	if (format === "rgb") return formatRgb(color, alpha);
-	if (format === "hsl") return formatHsl(color, alpha);
-	return formatOklch(color, alpha);
-}
-function coerce(value) {
-	if (!value || typeof value !== "object") return null;
-	const v = value;
-	const colorSpace = typeof v.colorSpace === "string" ? v.colorSpace : void 0;
-	const components = Array.isArray(v.components) ? v.components : Array.isArray(v.channels) ? v.channels : void 0;
-	if (!colorSpace || !components) {
-		if (typeof v.hex === "string") return {
-			colorSpace: "srgb",
-			components: hexToComponents(v.hex)
-		};
-		return null;
-	}
-	const alpha = typeof v.alpha === "number" ? v.alpha : void 0;
-	const hexVal = v["hex"];
-	const hex = typeof hexVal === "string" ? hexVal : void 0;
-	return {
-		colorSpace,
-		components,
-		...alpha !== void 0 && { alpha },
-		...hex !== void 0 && { hex }
-	};
-}
-function hexToComponents(hex) {
-	const h = hex.replace("#", "");
-	const expanded = h.length === 3 || h.length === 4 ? h.split("").map((c) => c + c).join("") : h;
-	return [
-		parseInt(expanded.slice(0, 2), 16) / 255,
-		parseInt(expanded.slice(2, 4), 16) / 255,
-		parseInt(expanded.slice(4, 6), 16) / 255
-	];
-}
+//#region src/internal/styles.tsx
 /**
-* Map Terrazzo's canonical CSS Color 4 space identifiers to the shorter
-* identifiers colorjs.io registers. Only the ones that differ need an entry.
+* Chrome-style primitives shared across every block. Kept as JS exports
+* for the inline-style sites that still compose them into per-block style
+* objects (e.g. TokenNavigator's `typePill` that builds on the shared
+* pill base). The pure direct-reference chrome — surface wrapper, caption,
+* empty-state — lives in `styles.css` and is applied via class names.
 */
-const COLORJS_SPACE_ALIASES = {
-	"display-p3": "p3",
-	"a98-rgb": "a98rgb",
-	"prophoto-rgb": "prophoto"
-};
-function toColor(normalized) {
-	const source = normalized.components ?? normalized.channels ?? [];
-	const coords = [
-		numberOrZero(source[0]),
-		numberOrZero(source[1]),
-		numberOrZero(source[2])
-	];
-	const space = COLORJS_SPACE_ALIASES[normalized.colorSpace] ?? normalized.colorSpace;
-	try {
-		return new Color(space, coords, normalized.alpha ?? 1);
-	} catch {
-		return null;
-	}
-}
-function numberOrZero(n) {
-	return typeof n === "number" && !Number.isNaN(n) ? n : 0;
-}
-function coord(color, i) {
-	const c = color.coords[i];
-	return typeof c === "number" && !Number.isNaN(c) ? c : 0;
-}
-function formatHex(color, alpha) {
-	const srgb = color.to("srgb");
-	if (!srgb.inGamut("srgb")) return {
-		value: formatRgb(color, alpha).value,
-		outOfGamut: true
-	};
-	const r = clamp255(coord(srgb, 0));
-	const g = clamp255(coord(srgb, 1));
-	const b = clamp255(coord(srgb, 2));
-	const base = `#${toHexByte(r)}${toHexByte(g)}${toHexByte(b)}`;
-	if (alpha >= 1) return {
-		value: base,
-		outOfGamut: false
-	};
-	return {
-		value: `${base}${toHexByte(clamp255(alpha))}`,
-		outOfGamut: false
-	};
-}
-function formatRgb(color, alpha) {
-	const srgb = color.to("srgb");
-	const inGamut = srgb.inGamut("srgb");
-	const body = `${Math.round(clampUnit(coord(srgb, 0)) * 255)} ${Math.round(clampUnit(coord(srgb, 1)) * 255)} ${Math.round(clampUnit(coord(srgb, 2)) * 255)}`;
-	return {
-		value: alpha >= 1 ? `rgb(${body})` : `rgb(${body} / ${roundAlpha(alpha)})`,
-		outOfGamut: !inGamut
-	};
-}
-function formatHsl(color, alpha) {
-	const hsl = color.to("hsl");
-	const inGamut = color.to("srgb").inGamut("srgb");
-	const body = `${roundHue(coord(hsl, 0))} ${roundPercent(coord(hsl, 1))}% ${roundPercent(coord(hsl, 2))}%`;
-	return {
-		value: alpha >= 1 ? `hsl(${body})` : `hsl(${body} / ${roundAlpha(alpha)})`,
-		outOfGamut: !inGamut
-	};
-}
-function formatOklch(color, alpha) {
-	const oklch = color.to("oklch");
-	const body = `${roundTo(coord(oklch, 0), 3)} ${roundTo(coord(oklch, 1), 3)} ${roundTo(coord(oklch, 2), 2)}`;
-	return {
-		value: alpha >= 1 ? `oklch(${body})` : `oklch(${body} / ${roundAlpha(alpha)})`,
-		outOfGamut: false
-	};
-}
-function clamp255(n) {
-	return Math.max(0, Math.min(255, Math.round(n * 255)));
-}
-function clampUnit(n) {
-	return Math.max(0, Math.min(1, n));
-}
-function toHexByte(n) {
-	return n.toString(16).padStart(2, "0");
-}
-function roundTo(n, digits) {
-	const f = 10 ** digits;
-	return Math.round(n * f) / f;
-}
-function roundHue(h) {
-	return roundTo((h % 360 + 360) % 360, 1);
-}
-function roundPercent(n) {
-	return Math.round(n * 10) / 10;
-}
-function roundAlpha(a) {
-	return roundTo(a, 3);
-}
-function compactJson(value) {
-	const parts = [`"colorSpace":${JSON.stringify(value.colorSpace)}`];
-	const components = value.components ?? value.channels;
-	if (components) parts.push(`"components":[${components.map((c) => c === null ? "null" : c).join(", ")}]`);
-	if (typeof value.alpha === "number" && value.alpha !== 1) parts.push(`"alpha":${value.alpha}`);
-	return `{ ${parts.join(", ")} }`;
-}
-function stringifyFallback(value, fallback) {
-	if (value == null) return fallback;
-	if (typeof value === "string" || typeof value === "number") return String(value);
-	return fallback;
-}
-//#endregion
-//#region src/internal/styles.tsx
 const TEXT_MUTED = "var(--swatchbook-text-muted, CanvasText)";
 const SURFACE_RAISED = "var(--swatchbook-surface-raised, Canvas)";
 const SURFACE_MUTED = "var(--swatchbook-surface-muted, rgba(128,128,128,0.15))";
@@ -196,7 +27,7 @@ const BORDER_FAINT = `1px solid var(--swatchbook-border-default, rgba(128,128,12
 const BORDER_STRONG = `1px solid var(--swatchbook-border-default, rgba(128,128,128,0.3))`;
 /**
 * Inner content for a block's "nothing to render" state. Call sites wrap
-* it in their own block wrapper (which already carries `themeAttrs`), so
+* it in their own block wrapper (which already carries `blockWrapperAttrs`), so
 * the message itself just needs the muted type.
 */
 function EmptyState({ children }) {
@@ -243,11 +74,6 @@ function ensureSubscribed$1() {
 	channel.on("updateGlobals", onGlobals);
 	channel.on("setGlobals", onGlobals);
 }
-/**
-* Subscribe at module load so the `SET_GLOBALS` emission from preview init
-* lands in our snapshot before any block renders. Running `useSyncExternalStore`'s
-* `subscribe` lazily on first hook call would miss the event in most cases.
-*/
 ensureSubscribed$1();
 function subscribe$1(cb) {
 	ensureSubscribed$1();
@@ -293,7 +119,7 @@ function useActiveTheme() {
 * Active axis tuple for the current story/docs render — `Record<axisName,
 * contextName>`. Derived from the same input as {@link ThemeContext}; split
 * out so consumers needing per-axis info (toolbar, panel, tuple-aware
-* blocks) don't have to reparse the composed permutation ID.
+* blocks) don't have to reparse the composed theme name.
 */
 const AxesContext = createContext({});
 function useActiveAxes() {
@@ -321,49 +147,66 @@ function useColorFormat() {
 /**
 * Live token snapshot backed by the addon's preview dev-time HMR event.
 *
-* Blocks read the virtual module at module load; without a way to notice
-* changes, edits to the source token files would flow into the addon's
-* in-memory project but nowhere else — the React tree would keep
-* rendering the old values until a full preview reload. This module
-* subscribes to `TOKENS_UPDATED_EVENT` on Storybook's channel (which the
-* addon preview re-broadcasts from its own HMR listener) and exposes
-* the latest snapshot via `useSyncExternalStore`, so hooks that read
-* through this module re-render in place on each token save.
+* The initial snapshot is *injected* by the addon preview via
+* {@link registerTokenSource} rather than imported from the addon's
+* `virtual:swatchbook/tokens` build artifact — so blocks carries no
+* dependency on that module and imports cleanly standalone (outside
+* Storybook, in unit tests, in the docs site). Until something registers
+* a source, blocks render from empty defaults.
 *
-* Outside the preview iframe (the docs-site path, unit tests) the
-* channel never receives anything, and consumers keep seeing the
-* initial values baked into the virtual module at build time.
+* For dev-time updates this module subscribes to `TOKENS_UPDATED_EVENT`
+* on Storybook's channel (which the addon preview re-broadcasts from its
+* own HMR listener) and exposes the latest snapshot via
+* `useSyncExternalStore`, so hooks re-render in place on each token save.
 */
 const TOKENS_UPDATED_EVENT = "swatchbook/tokens-updated";
 let snapshot = {
-	axes,
-	presets,
-	diagnostics,
-	css,
-	cssVarPrefix,
-	listing: listing ?? {},
-	tokenGraph,
-	defaultTuple: defaultTuple ?? {},
+	axes: [],
+	presets: [],
+	diagnostics: [],
+	css: "",
+	cssVarPrefix: "",
+	listing: {},
+	tokenGraph: {
+		nodes: {},
+		axes: [],
+		axisDefaults: {},
+		axisContexts: {}
+	},
+	defaultTuple: {},
 	version: 0
 };
 const listeners = /* @__PURE__ */ new Set();
 let subscribed = false;
+function applyPatch(patch) {
+	snapshot = {
+		axes: patch.axes ?? snapshot.axes,
+		presets: patch.presets ?? snapshot.presets,
+		diagnostics: patch.diagnostics ?? snapshot.diagnostics,
+		css: patch.css ?? snapshot.css,
+		cssVarPrefix: patch.cssVarPrefix ?? snapshot.cssVarPrefix,
+		listing: patch.listing ?? snapshot.listing,
+		tokenGraph: patch.tokenGraph ?? snapshot.tokenGraph,
+		defaultTuple: patch.defaultTuple ?? snapshot.defaultTuple,
+		version: snapshot.version + 1
+	};
+	for (const cb of listeners) cb();
+}
+/**
+* Seed the initial token snapshot. The addon preview calls this once at
+* init with the build-time `virtual:swatchbook/tokens` data. Keeping the
+* virtual-module read on the addon side (the package that owns it) lets
+* blocks import cleanly without it. No-op fields fall back to the current
+* snapshot, so a partial source is safe.
+*/
+function registerTokenSource(source) {
+	applyPatch(source);
+}
 function ensureSubscribed() {
 	if (subscribed || typeof window === "undefined") return;
 	subscribed = true;
 	addons.getChannel().on(TOKENS_UPDATED_EVENT, (payload) => {
-		snapshot = {
-			axes: payload.axes ?? snapshot.axes,
-			presets: payload.presets ?? snapshot.presets,
-			diagnostics: payload.diagnostics ?? snapshot.diagnostics,
-			css: payload.css ?? snapshot.css,
-			cssVarPrefix: payload.cssVarPrefix ?? snapshot.cssVarPrefix,
-			listing: payload.listing ?? snapshot.listing,
-			tokenGraph: payload.tokenGraph ?? snapshot.tokenGraph,
-			defaultTuple: payload.defaultTuple ?? snapshot.defaultTuple,
-			version: snapshot.version + 1
-		};
-		for (const cb of listeners) cb();
+		applyPatch(payload);
 	});
 }
 ensureSubscribed();
@@ -385,33 +228,24 @@ function useTokenSnapshot() {
 }
 //#endregion
 //#region src/internal/use-project.ts
+function computeVarianceByPath(graph) {
+	if (!graph) return {};
+	const out = {};
+	for (const path of listPaths(graph)) out[path] = getVariance(graph, path);
+	return out;
+}
 function ensureStylesheet(css) {
 	ensureStyleElement(SWATCHBOOK_STYLE_ELEMENT_ID, css);
 }
-function defaultTuple$1(axes) {
+function defaultTuple(axes) {
 	const out = {};
 	for (const axis of axes) out[axis.name] = axis.default;
 	return out;
 }
-/**
-* Build a `resolveAt` accessor backed by the token graph. Returns an
-* empty resolver when no graph is present (test stubs, partial
-* snapshots). Stable identity when memoized on `tokenGraph` — the
-* graph is a module-level virtual-module export so its reference stays
-* constant for the lifetime of the iframe.
-*/
 function makeResolveAt(graph) {
 	if (!graph) return () => ({});
 	return (tuple) => resolveAllAt(graph, tuple);
 }
-/**
-* Build the `resolveAt` accessor for a snapshot. Prefers the
-* snapshot's own `resolveAt` (the addon's preview decorator
-* pre-builds one at module load — see `previewResolveAt` in
-* `packages/addon/src/preview.tsx`), otherwise builds one from
-* `tokenGraph`. Hand-built snapshots can omit `resolveAt`;
-* the graph-backed fallback covers them.
-*/
 function snapshotResolveAt(snapshot) {
 	if (snapshot.resolveAt) return snapshot.resolveAt;
 	return makeResolveAt(snapshot.tokenGraph);
@@ -441,12 +275,7 @@ function useProject() {
 		if (!snapshot) return null;
 		return snapshotResolveAt(snapshot);
 	}, [tokenGraph, activeTheme]);
-	const derivedVarianceByPath = useMemo(() => {
-		if (!tokenGraph) return {};
-		const out = {};
-		for (const path of listPaths(tokenGraph)) out[path] = getVariance(tokenGraph, path);
-		return out;
-	}, [tokenGraph]);
+	const derivedVarianceByPath = useMemo(() => computeVarianceByPath(tokenGraph), [tokenGraph]);
 	const providerData = useMemo(() => {
 		if (!snapshot || !resolveAt || !axes || !activeAxes) return null;
 		return {
@@ -458,12 +287,6 @@ function useProject() {
 			cssVarPrefix: cssVarPrefix ?? "",
 			listing: listing ?? {},
 			varianceByPath: derivedVarianceByPath,
-			tokenGraph: tokenGraph ?? {
-				nodes: {},
-				axes: [],
-				axisDefaults: {},
-				axisContexts: {}
-			},
 			resolveAt
 		};
 	}, [
@@ -482,37 +305,24 @@ function useProject() {
 	return providerData ?? fallback;
 }
 function useVirtualModuleFallback(enabled) {
-	const contextPermutation = useActiveTheme();
+	const contextThemeName = useActiveTheme();
 	const contextAxes = useActiveAxes();
 	const channelGlobals = useChannelGlobals();
-	/**
-	* Subscribe to the live token snapshot rather than reading the virtual
-	* module's module-level exports directly. Initial values come from
-	* `virtual:swatchbook/tokens` at load time; subsequent dev-time edits
-	* flow through the addon's HMR channel and update this snapshot in
-	* place so blocks re-render without a full preview reload.
-	*/
 	const tokens = useTokenSnapshot();
 	useEffect(() => {
 		if (!enabled) return;
 		ensureStylesheet(tokens.css);
 	}, [enabled, tokens.css]);
 	const activeAxes = useMemo(() => {
-		return Object.keys(contextAxes).length > 0 ? { ...contextAxes } : channelGlobals.axes ?? defaultTuple$1(tokens.axes);
+		return Object.keys(contextAxes).length > 0 ? { ...contextAxes } : channelGlobals.axes ?? defaultTuple(tokens.axes);
 	}, [
 		contextAxes,
 		channelGlobals.axes,
 		tokens.axes
 	]);
-	const activeTheme = contextPermutation || tupleToName(tokens.axes, activeAxes);
+	const activeTheme = contextThemeName || tupleToName(tokens.axes, activeAxes);
 	const resolveAt = useMemo(() => makeResolveAt(tokens.tokenGraph), [tokens.tokenGraph]);
-	const fallbackVarianceByPath = useMemo(() => {
-		const graph = tokens.tokenGraph;
-		if (!graph) return {};
-		const out = {};
-		for (const path of listPaths(graph)) out[path] = getVariance(graph, path);
-		return out;
-	}, [tokens.tokenGraph]);
+	const fallbackVarianceByPath = useMemo(() => computeVarianceByPath(tokens.tokenGraph), [tokens.tokenGraph]);
 	return useMemo(() => ({
 		activeTheme,
 		activeAxes,
@@ -522,7 +332,6 @@ function useVirtualModuleFallback(enabled) {
 		cssVarPrefix: tokens.cssVarPrefix,
 		listing: tokens.listing,
 		varianceByPath: fallbackVarianceByPath,
-		tokenGraph: tokens.tokenGraph,
 		resolveAt
 	}), [
 		activeTheme,
@@ -532,7 +341,6 @@ function useVirtualModuleFallback(enabled) {
 		tokens.cssVarPrefix,
 		tokens.listing,
 		fallbackVarianceByPath,
-		tokens.tokenGraph,
 		resolveAt
 	]);
 }
@@ -590,6 +398,32 @@ function BorderSample({ path }) {
 	});
 }
 //#endregion
+//#region src/internal/composite-sample-format.ts
+/**
+* Display a composite sub-field dimension (shadow offset / blur / spread,
+* border width, …) in the preview tables. Renders `—` for a missing
+* sub-field and falls back to JSON for shapes it doesn't recognize.
+*
+* Distinct from `format-token-value`'s internal `formatDimension`, which
+* formats a token's top-level value and has no `—` placeholder — these are
+* the per-layer sample formatters shared by `ShadowPreview` + `BorderPreview`.
+*/
+function formatDimension$1(raw) {
+	if (raw == null) return "—";
+	if (typeof raw === "number") return String(raw);
+	if (typeof raw === "string") return raw;
+	if (typeof raw === "object") {
+		const v = raw;
+		if (typeof v.value === "number" && typeof v.unit === "string") return `${v.value}${v.unit}`;
+	}
+	return JSON.stringify(raw);
+}
+/** Display a composite sub-field color via the active format; `—` when absent. */
+function formatSubColor(raw, format) {
+	if (raw == null) return "—";
+	return formatColor(raw, format).value;
+}
+//#endregion
 //#region src/internal/data-attr.ts
 /**
 * Marker attribute set on every block wrapper. Retained as a stable hook
@@ -597,14 +431,6 @@ function BorderSample({ path }) {
 * override block chrome without relying on hashed class names).
 */
 const BLOCK_ATTR = "data-swatchbook-block";
-/**
-* Opt-out class that Storybook's `.sbdocs` stylesheet uses to self-exclude
-* on MDX docs pages — every `.sbdocs` house rule is wrapped in
-* `:not(.sb-unstyled, .sb-unstyled *)`, so any descendant of a `.sb-unstyled`
-* container is left alone. Stamped onto every block wrapper so blocks
-* render identically in MDX docs and regular stories without fighting
-* cascade specificity.
-*/
 const WRAPPER_CLASSES = "sb-unstyled sb-block";
 /**
 * Spread helper for the common block wrapper. Returns:
@@ -622,7 +448,7 @@ const WRAPPER_CLASSES = "sb-unstyled sb-block";
 *   MDX docs house styles self-exclude the subtree, plus `sb-block`
 *   which carries the shared chrome from `internal/styles.css`.
 */
-function themeAttrs(prefix, tuple) {
+function blockWrapperAttrs(prefix, tuple) {
 	return {
 		...perAxisAttrs(prefix, tuple),
 		[BLOCK_ATTR]: "",
@@ -728,29 +554,14 @@ function toMagnitude(v) {
 	}
 	return NaN;
 }
-/**
-* Coerce a possibly-null/undefined number to 0 — `coords` returns
-* `(number | null)[]` and `noUncheckedIndexedAccess` adds `undefined`
-* on top. `typeof` narrows the union for the comparator below.
-*/
 function safeNumber(v) {
 	return typeof v === "number" && Number.isFinite(v) ? v : 0;
 }
 function colorKey(v) {
-	if (!v || typeof v !== "object") return null;
+	const color = parseColor(v);
+	if (!color) return null;
 	try {
-		const c = v;
-		let source;
-		if (typeof c.hex === "string") source = c.hex;
-		else if (typeof c.colorSpace === "string") {
-			const channels = Array.isArray(c.components) ? c.components : Array.isArray(c.channels) ? c.channels : void 0;
-			if (!channels) return null;
-			source = {
-				space: c.colorSpace,
-				coords: channels
-			};
-		} else return null;
-		const [l, chroma, h] = new Color(source).to("oklch").coords;
+		const [l, chroma, h] = color.to("oklch").coords;
 		return {
 			l: safeNumber(l),
 			c: safeNumber(chroma),
@@ -768,20 +579,6 @@ function toDisplayable(v) {
 }
 //#endregion
 //#region src/BorderPreview.tsx
-function formatDimension$2(raw) {
-	if (raw == null) return "—";
-	if (typeof raw === "number") return String(raw);
-	if (typeof raw === "string") return raw;
-	if (typeof raw === "object") {
-		const v = raw;
-		if (typeof v.value === "number" && typeof v.unit === "string") return `${v.value}${v.unit}`;
-	}
-	return JSON.stringify(raw);
-}
-function formatSubColor$1(raw, format) {
-	if (raw == null) return "—";
-	return formatColor(raw, format).value;
-}
 function BorderPreview({ filter, caption, sortBy = "path", sortDir = "asc" }) {
 	const project = useProject();
 	const { resolved, activeTheme, activeAxes, cssVarPrefix } = project;
@@ -807,14 +604,14 @@ function BorderPreview({ filter, caption, sortBy = "path", sortDir = "asc" }) {
 	]);
 	const captionText = caption ?? `${rows.length} border${rows.length === 1 ? "" : "s"}${filter ? ` matching \`${filter}\`` : ""} · ${activeTheme}`;
 	if (rows.length === 0) return /* @__PURE__ */ jsx("div", {
-		...themeAttrs(cssVarPrefix, activeAxes),
+		...blockWrapperAttrs(cssVarPrefix, activeAxes),
 		children: /* @__PURE__ */ jsx("div", {
 			className: "sb-block__empty",
 			children: "No border tokens match this filter."
 		})
 	});
 	return /* @__PURE__ */ jsxs("div", {
-		...themeAttrs(cssVarPrefix, activeAxes),
+		...blockWrapperAttrs(cssVarPrefix, activeAxes),
 		children: [/* @__PURE__ */ jsx("div", {
 			className: "sb-block__caption",
 			children: captionText
@@ -842,7 +639,7 @@ function BorderPreview({ filter, caption, sortBy = "path", sortDir = "asc" }) {
 							className: "sb-border-preview__breakdown-key",
 							children: "width"
 						}),
-						/* @__PURE__ */ jsx("span", { children: formatDimension$2(row.value.width) }),
+						/* @__PURE__ */ jsx("span", { children: formatDimension$1(row.value.width) }),
 						/* @__PURE__ */ jsx("span", {
 							className: "sb-border-preview__breakdown-key",
 							children: "style"
@@ -852,7 +649,7 @@ function BorderPreview({ filter, caption, sortBy = "path", sortDir = "asc" }) {
 							className: "sb-border-preview__breakdown-key",
 							children: "color"
 						}),
-						/* @__PURE__ */ jsx("span", { children: formatSubColor$1(row.value.color, colorFormat) })
+						/* @__PURE__ */ jsx("span", { children: formatSubColor(row.value.color, colorFormat) })
 					]
 				})
 			]
@@ -861,10 +658,6 @@ function BorderPreview({ filter, caption, sortBy = "path", sortDir = "asc" }) {
 }
 //#endregion
 //#region src/ColorPalette.tsx
-/**
-* Count segments in the filter before the first glob (`*` / `**`).
-* `color.*` → 2; `color.surface.*` → 3; `color` → 1; undefined → 0.
-*/
 function fixedPrefixLength(filter) {
 	if (!filter) return 0;
 	const segments = filter.split(".");
@@ -922,14 +715,14 @@ function ColorPalette({ filter, groupBy, caption, sortBy = "path", sortDir = "as
 	const totalCount = groups.reduce((acc, [, swatches]) => acc + swatches.length, 0);
 	const captionText = caption ?? `${totalCount} color${totalCount === 1 ? "" : "s"}${filter ? ` matching \`${filter}\`` : ""} · ${activeTheme}`;
 	if (totalCount === 0) return /* @__PURE__ */ jsx("div", {
-		...themeAttrs(cssVarPrefix, activeAxes),
+		...blockWrapperAttrs(cssVarPrefix, activeAxes),
 		children: /* @__PURE__ */ jsx("div", {
 			className: "sb-block__empty",
 			children: "No color tokens match this filter."
 		})
 	});
 	return /* @__PURE__ */ jsxs("div", {
-		...themeAttrs(cssVarPrefix, activeAxes),
+		...blockWrapperAttrs(cssVarPrefix, activeAxes),
 		children: [/* @__PURE__ */ jsx("div", {
 			className: "sb-block__caption",
 			children: captionText
@@ -1115,14 +908,14 @@ function ColorTable({ filter, caption, sortBy = "path", sortDir = "asc", searcha
 	const matchSuffix = searchable && query.trim() !== "" ? ` · ${visibleGroups.length} matching "${query.trim()}"` : "";
 	const captionText = caption ?? `${totalTokens} color${totalTokens === 1 ? "" : "s"} across ${groups.length} group${groups.length === 1 ? "" : "s"}${filter ? ` matching \`${filter}\`` : ""}${matchSuffix} · ${activeTheme}`;
 	if (groups.length === 0) return /* @__PURE__ */ jsx("div", {
-		...themeAttrs(cssVarPrefix, activeAxes),
+		...blockWrapperAttrs(cssVarPrefix, activeAxes),
 		children: /* @__PURE__ */ jsx("div", {
 			className: "sb-block__empty",
 			children: "No color tokens match this filter."
 		})
 	});
 	return /* @__PURE__ */ jsxs("div", {
-		...themeAttrs(cssVarPrefix, activeAxes),
+		...blockWrapperAttrs(cssVarPrefix, activeAxes),
 		children: [searchable && /* @__PURE__ */ jsx("div", {
 			className: "sb-color-table__search",
 			children: /* @__PURE__ */ jsx("input", {
@@ -1404,13 +1197,6 @@ function ValueCell({ value, label, children }) {
 		]
 	});
 }
-/**
-* Pick the value + gamut flag to display in the single Value column based
-* on the active color-format context. We pre-compute hex/hsl/oklch for the
-* expanded sub-table regardless; the extras (`rgb`, `raw`) take a fresh
-* `formatColor` pass. Keeps the hot path fast while staying honest about
-* out-of-gamut warnings per-format.
-*/
 function pickActiveFormat(raw, colorFormat, hex, hsl, oklch) {
 	switch (colorFormat) {
 		case "hex": return {
@@ -1454,30 +1240,11 @@ function buildVariantDefs(variants) {
 		displayOrder
 	};
 }
-/**
-* Position of a label within a group — the `base` entry always sorts first,
-* then declared labels in the order the caller wrote them in the `variants`
-* prop. Unknown labels (shouldn't happen in practice) fall to the end.
-*/
 function orderIndex(label, defs) {
 	if (label === BASE_LABEL) return -1;
 	const idx = defs.displayOrder.indexOf(label);
 	return idx >= 0 ? idx : Number.POSITIVE_INFINITY;
 }
-/**
-* Resolve the variant label + base path for a token, if any. The leaf
-* (last dot-segment) must either equal the suffix outright (dot-segment
-* form: `hi.disabled` matches suffix `disabled`) or end in `-<suffix>`
-* (hyphen-tail form: `hi-d` matches `d`). The leading hyphen is required
-* for the tail form so suffix `0` can't hit `neutral-900` by character.
-*
-* Returned `basePath` is what gets used as the grouping key:
-* - Dot-segment match → parent path (drop the last dot-segment)
-* - Hyphen-tail match → same dot-depth, leaf with `-<suffix>` stripped
-*
-* Entries in `matchOrder` are pre-sorted longest-first, so `h-dark` wins
-* over `dark` for a path ending in `-h-dark`.
-*/
 function matchVariant(path, matchOrder) {
 	if (matchOrder.length === 0) return void 0;
 	const segments = path.split(".");
@@ -1552,7 +1319,7 @@ function Diagnostics({ caption } = {}) {
 	const summary = useMemo(() => summarize(diagnostics), [diagnostics]);
 	const headingText = caption ?? `Diagnostics · ${summary.text}`;
 	return /* @__PURE__ */ jsx("div", {
-		...themeAttrs(cssVarPrefix, activeAxes),
+		...blockWrapperAttrs(cssVarPrefix, activeAxes),
 		"data-testid": "diagnostics",
 		children: /* @__PURE__ */ jsxs("details", {
 			open: summary.hasErrorsOrWarnings,
@@ -1583,8 +1350,26 @@ function Diagnostics({ caption } = {}) {
 	});
 }
 //#endregion
+//#region src/dimension-scale/dimension-px.ts
+/**
+* Convert a DTCG dimension `$value` (`{ value, unit }`) to pixels for the
+* purpose of deciding whether to cap the rendered size. Returns `NaN` for
+* units we can't reasonably approximate (ex / ch / %), which the caller
+* treats as "render at cssVar but don't cap".
+*/
+function toPixels(raw) {
+	if (raw == null || typeof raw !== "object") return NaN;
+	const v = raw;
+	if (typeof v.value !== "number" || typeof v.unit !== "string") return NaN;
+	switch (v.unit) {
+		case "px": return v.value;
+		case "rem":
+		case "em": return v.value * 16;
+		default: return NaN;
+	}
+}
+//#endregion
 //#region src/dimension-scale/DimensionBar.tsx
-const MAX_RENDER_PX$1 = 480;
 const styles$1 = {
 	bar: {
 		height: 14,
@@ -1605,31 +1390,14 @@ const styles$1 = {
 		minHeight: 1
 	}
 };
-/**
-* Convert a DTCG dimension `$value` (`{ value, unit }`) to pixels for the
-* purpose of deciding whether to cap the rendered bar. Returns `NaN` for
-* units we can't reasonably approximate (ex / ch / %), which the caller
-* treats as "render at cssVar but don't cap".
-*/
-function toPixels$1(raw) {
-	if (raw == null || typeof raw !== "object") return NaN;
-	const v = raw;
-	if (typeof v.value !== "number" || typeof v.unit !== "string") return NaN;
-	switch (v.unit) {
-		case "px": return v.value;
-		case "rem":
-		case "em": return v.value * 16;
-		default: return NaN;
-	}
-}
-function DimensionBar({ path, kind = "length" }) {
+function DimensionBar({ path, visual = "length" }) {
 	const project = useProject();
 	const { resolved } = project;
 	const cssVar = resolveCssVar(path, project);
 	const token = resolved[path];
-	const pxValue = toPixels$1(token?.$value);
-	const cappedValue = Number.isFinite(pxValue) && pxValue > MAX_RENDER_PX$1 ? `${MAX_RENDER_PX$1}px` : cssVar;
-	switch (kind) {
+	const pxValue = toPixels(token?.$value);
+	const cappedValue = Number.isFinite(pxValue) && pxValue > 480 ? `480px` : cssVar;
+	switch (visual) {
 		case "radius": return /* @__PURE__ */ jsx("div", {
 			style: {
 				...styles$1.radiusSample,
@@ -1674,7 +1442,7 @@ function formatTokenValue(value, $type, colorFormat, listingEntry) {
 	switch ($type) {
 		case "color": return formatColor(value, colorFormat).value;
 		case "dimension":
-		case "duration": return formatDimension$1(value);
+		case "duration": return formatDimension(value);
 		case "fontFamily": return formatFontFamily$1(value);
 		case "fontWeight":
 		case "lineHeight":
@@ -1688,7 +1456,7 @@ function formatTokenValue(value, $type, colorFormat, listingEntry) {
 		default: return formatUnknown(value);
 	}
 }
-function formatDimension$1(v) {
+function formatDimension(v) {
 	if (typeof v === "string" || typeof v === "number") return String(v);
 	if (v && typeof v === "object") {
 		const d = v;
@@ -1717,7 +1485,7 @@ function formatStrokeStyle(v) {
 	if (v && typeof v === "object") {
 		const s = v;
 		const parts = ["dashed"];
-		if (Array.isArray(s.dashArray)) parts.push(s.dashArray.map((n) => formatDimension$1(n)).join(" "));
+		if (Array.isArray(s.dashArray)) parts.push(s.dashArray.map((n) => formatDimension(n)).join(" "));
 		if (typeof s.lineCap === "string") parts.push(s.lineCap);
 		return parts.join(" · ");
 	}
@@ -1728,10 +1496,10 @@ function formatShadow(v, colorFormat) {
 		if (!layer || typeof layer !== "object") return formatUnknown(layer);
 		const s = layer;
 		const pieces = [
-			formatDimension$1(s.offsetX),
-			formatDimension$1(s.offsetY),
-			formatDimension$1(s.blur),
-			formatDimension$1(s.spread),
+			formatDimension(s.offsetX),
+			formatDimension(s.offsetY),
+			formatDimension(s.blur),
+			formatDimension(s.spread),
 			formatColor(s.color, colorFormat).value
 		].filter((p) => p !== "");
 		if (s.inset) pieces.push("inset");
@@ -1742,7 +1510,7 @@ function formatBorder(v, colorFormat) {
 	if (!v || typeof v !== "object") return formatUnknown(v);
 	const b = v;
 	return [
-		formatDimension$1(b.width),
+		formatDimension(b.width),
 		formatPrimitive$1(b.style),
 		formatColor(b.color, colorFormat).value
 	].filter((p) => p !== "").join(" ");
@@ -1758,19 +1526,7 @@ function formatUnknown(v) {
 }
 //#endregion
 //#region src/DimensionScale.tsx
-const MAX_RENDER_PX = 480;
-function toPixels(raw) {
-	if (raw == null || typeof raw !== "object") return NaN;
-	const v = raw;
-	if (typeof v.value !== "number" || typeof v.unit !== "string") return NaN;
-	switch (v.unit) {
-		case "px": return v.value;
-		case "rem":
-		case "em": return v.value * 16;
-		default: return NaN;
-	}
-}
-function DimensionScale({ filter, kind = "length", caption, sortBy = "value", sortDir = "asc" }) {
+function DimensionScale({ filter, visual = "length", caption, sortBy = "value", sortDir = "asc" }) {
 	const project = useProject();
 	const { resolved, activeTheme, activeAxes, cssVarPrefix } = project;
 	const rows = useMemo(() => {
@@ -1787,7 +1543,7 @@ function DimensionScale({ filter, kind = "length", caption, sortBy = "value", so
 				cssVar: resolveCssVar(path, project),
 				displayValue: formatTokenValue(token.$value, token.$type, "raw", project.listing[path]),
 				pxValue,
-				capped: Number.isFinite(pxValue) && pxValue > MAX_RENDER_PX
+				capped: Number.isFinite(pxValue) && pxValue > 480
 			};
 		});
 	}, [
@@ -1799,14 +1555,14 @@ function DimensionScale({ filter, kind = "length", caption, sortBy = "value", so
 	]);
 	const captionText = caption ?? `${rows.length} dimension${rows.length === 1 ? "" : "s"}${filter ? ` matching \`${filter}\`` : ""} · ${activeTheme}`;
 	if (rows.length === 0) return /* @__PURE__ */ jsx("div", {
-		...themeAttrs(cssVarPrefix, activeAxes),
+		...blockWrapperAttrs(cssVarPrefix, activeAxes),
 		children: /* @__PURE__ */ jsx("div", {
 			className: "sb-block__empty",
 			children: "No dimension tokens match this filter."
 		})
 	});
 	return /* @__PURE__ */ jsxs("div", {
-		...themeAttrs(cssVarPrefix, activeAxes),
+		...blockWrapperAttrs(cssVarPrefix, activeAxes),
 		children: [/* @__PURE__ */ jsx("div", {
 			className: "sb-block__caption",
 			children: captionText
@@ -1827,12 +1583,12 @@ function DimensionScale({ filter, kind = "length", caption, sortBy = "value", so
 					className: "sb-dimension-scale__visual-cell",
 					children: [/* @__PURE__ */ jsx(DimensionBar, {
 						path: row.path,
-						kind
+						visual
 					}), row.capped && /* @__PURE__ */ jsxs("span", {
 						className: "sb-dimension-scale__cap",
 						children: [
 							"capped at ",
-							MAX_RENDER_PX,
+							480,
 							"px"
 						]
 					})]
@@ -1846,13 +1602,13 @@ function DimensionScale({ filter, kind = "length", caption, sortBy = "value", so
 	});
 }
 //#endregion
-//#region src/FontFamilySample.tsx
+//#region src/FontFamilyPreview.tsx
 function stackString(raw) {
 	if (typeof raw === "string") return raw;
 	if (Array.isArray(raw)) return raw.map(String).join(", ");
 	return "";
 }
-function FontFamilySample({ filter, sample = "The quick brown fox jumps over the lazy dog.", caption, sortBy = "path", sortDir = "asc" }) {
+function FontFamilyPreview({ filter, sample = "The quick brown fox jumps over the lazy dog.", caption, sortBy = "path", sortDir = "asc" }) {
 	const project = useProject();
 	const { resolved, activeTheme, activeAxes, cssVarPrefix } = project;
 	const rows = useMemo(() => {
@@ -1876,14 +1632,14 @@ function FontFamilySample({ filter, sample = "The quick brown fox jumps over the
 	]);
 	const captionText = caption ?? `${rows.length} fontFamily token${rows.length === 1 ? "" : "s"}${filter && filter !== "fontFamily" ? ` matching \`${filter}\`` : ""} · ${activeTheme}`;
 	if (rows.length === 0) return /* @__PURE__ */ jsx("div", {
-		...themeAttrs(cssVarPrefix, activeAxes),
+		...blockWrapperAttrs(cssVarPrefix, activeAxes),
 		children: /* @__PURE__ */ jsx("div", {
 			className: "sb-block__empty",
 			children: "No fontFamily tokens match this filter."
 		})
 	});
 	return /* @__PURE__ */ jsxs("div", {
-		...themeAttrs(cssVarPrefix, activeAxes),
+		...blockWrapperAttrs(cssVarPrefix, activeAxes),
 		children: [/* @__PURE__ */ jsx("div", {
 			className: "sb-block__caption",
 			children: captionText
@@ -1963,14 +1719,14 @@ function FontWeightScale({ filter, sample = "Aa", caption, sortBy = "value", sor
 	]);
 	const captionText = caption ?? `${rows.length} fontWeight token${rows.length === 1 ? "" : "s"}${filter && filter !== "fontWeight" ? ` matching \`${filter}\`` : ""} · ${activeTheme}`;
 	if (rows.length === 0) return /* @__PURE__ */ jsx("div", {
-		...themeAttrs(cssVarPrefix, activeAxes),
+		...blockWrapperAttrs(cssVarPrefix, activeAxes),
 		children: /* @__PURE__ */ jsx("div", {
 			className: "sb-block__empty",
 			children: "No fontWeight tokens match this filter."
 		})
 	});
 	return /* @__PURE__ */ jsxs("div", {
-		...themeAttrs(cssVarPrefix, activeAxes),
+		...blockWrapperAttrs(cssVarPrefix, activeAxes),
 		children: [/* @__PURE__ */ jsx("div", {
 			className: "sb-block__caption",
 			children: captionText
@@ -2006,14 +1762,10 @@ function asStops(raw) {
 	if (!Array.isArray(raw)) return [];
 	return raw;
 }
-const pct = (n) => `${(n * 100).toFixed(3)}%`;
 function stopCssColor(stop) {
-	const color = stop.color;
-	if (!color || !Array.isArray(color.components) || color.components.length < 3) return "transparent";
-	const [r, g, b] = color.components;
-	if (r === void 0 || g === void 0 || b === void 0) return "transparent";
-	const alpha = color.alpha ?? 1;
-	return alpha === 1 ? `rgb(${pct(r)} ${pct(g)} ${pct(b)})` : `rgb(${pct(r)} ${pct(g)} ${pct(b)} / ${alpha})`;
+	const color = parseColor(stop.color);
+	if (!color) return "transparent";
+	return color.toString();
 }
 function stopKey(path, stop, fallback) {
 	return `${path}|${stop.position ?? fallback}|${stopCssColor(stop)}`;
@@ -2047,14 +1799,14 @@ function GradientPalette({ filter, caption, sortBy = "path", sortDir = "asc" })
 	]);
 	const captionText = caption ?? `${rows.length} gradient${rows.length === 1 ? "" : "s"}${filter ? ` matching \`${filter}\`` : ""} · ${activeTheme}`;
 	if (rows.length === 0) return /* @__PURE__ */ jsx("div", {
-		...themeAttrs(cssVarPrefix, activeAxes),
+		...blockWrapperAttrs(cssVarPrefix, activeAxes),
 		children: /* @__PURE__ */ jsx("div", {
 			className: "sb-block__empty",
 			children: "No gradient tokens match this filter."
 		})
 	});
 	return /* @__PURE__ */ jsxs("div", {
-		...themeAttrs(cssVarPrefix, activeAxes),
+		...blockWrapperAttrs(cssVarPrefix, activeAxes),
 		children: [/* @__PURE__ */ jsx("div", {
 			className: "sb-block__caption",
 			children: captionText
@@ -2104,14 +1856,6 @@ function GradientPalette({ filter, caption, sortBy = "path", sortDir = "asc" })
 }
 //#endregion
 //#region src/internal/prefers-reduced-motion.ts
-/**
-* True when rendering inside Chromatic's snapshot runner. Chromatic's
-* browser ships a recognisable user-agent string; checked here so
-* motion-looping components can fall back to their static state for
-* deterministic snapshots. Per-component detection rather than the
-* global `chromatic.prefersReducedMotion: true` parameter — that
-* parameter is incompatible with Chromatic's verification parser.
-*/
 function isChromatic() {
 	if (typeof navigator === "undefined") return false;
 	return navigator.userAgent.includes("Chromatic");
@@ -2332,14 +2076,14 @@ function MotionPreview({ filter, caption }) {
 	]);
 	const captionText = caption ?? `${rows.length} motion token${rows.length === 1 ? "" : "s"}${filter ? ` matching \`${filter}\`` : ""} · ${activeTheme}`;
 	if (rows.length === 0) return /* @__PURE__ */ jsx("div", {
-		...themeAttrs(cssVarPrefix, activeAxes),
+		...blockWrapperAttrs(cssVarPrefix, activeAxes),
 		children: /* @__PURE__ */ jsx("div", {
 			className: "sb-block__empty",
 			children: "No motion tokens match this filter."
 		})
 	});
 	return /* @__PURE__ */ jsxs("div", {
-		...themeAttrs(cssVarPrefix, activeAxes),
+		...blockWrapperAttrs(cssVarPrefix, activeAxes),
 		children: [
 			/* @__PURE__ */ jsx("div", {
 				className: "sb-block__caption",
@@ -2442,7 +2186,7 @@ function OpacityScale({ filter, type = "number", sampleColor = "color.accent.bg"
 	]);
 	const captionText = caption ?? `${rows.length} opacity token${rows.length === 1 ? "" : "s"}${filter ? ` matching \`${filter}\`` : ""} · ${activeTheme}`;
 	if (rows.length === 0) return /* @__PURE__ */ jsx("div", {
-		...themeAttrs(cssVarPrefix, activeAxes),
+		...blockWrapperAttrs(cssVarPrefix, activeAxes),
 		children: /* @__PURE__ */ jsx("div", {
 			className: "sb-block__empty",
 			children: "No opacity tokens match this filter."
@@ -2450,7 +2194,7 @@ function OpacityScale({ filter, type = "number", sampleColor = "color.accent.bg"
 	});
 	const sampleColorVar = resolveCssVar(sampleColor, project);
 	return /* @__PURE__ */ jsxs("div", {
-		...themeAttrs(cssVarPrefix, activeAxes),
+		...blockWrapperAttrs(cssVarPrefix, activeAxes),
 		children: [/* @__PURE__ */ jsx("div", {
 			className: "sb-block__caption",
 			children: captionText
@@ -2534,27 +2278,13 @@ function ShadowSample({ path }) {
 }
 //#endregion
 //#region src/ShadowPreview.tsx
-function formatDimension(raw) {
-	if (raw == null) return "—";
-	if (typeof raw === "number") return String(raw);
-	if (typeof raw === "string") return raw;
-	if (typeof raw === "object") {
-		const v = raw;
-		if (typeof v.value === "number" && typeof v.unit === "string") return `${v.value}${v.unit}`;
-	}
-	return JSON.stringify(raw);
-}
-function formatSubColor(raw, format) {
-	if (raw == null) return "—";
-	return formatColor(raw, format).value;
-}
 function asLayers(raw) {
 	if (Array.isArray(raw)) return raw;
 	if (raw && typeof raw === "object") return [raw];
 	return [];
 }
 function layerKey(path, layer, fallback) {
-	return `${path}|${`${formatDimension(layer.offsetX)},${formatDimension(layer.offsetY)}`}|${formatDimension(layer.blur)}|${formatDimension(layer.spread)}|${fallback}`;
+	return `${path}|${`${formatDimension$1(layer.offsetX)},${formatDimension$1(layer.offsetY)}`}|${formatDimension$1(layer.blur)}|${formatDimension$1(layer.spread)}|${fallback}`;
 }
 function ShadowPreview({ filter, caption, sortBy = "path", sortDir = "asc" }) {
 	const project = useProject();
@@ -2581,14 +2311,14 @@ function ShadowPreview({ filter, caption, sortBy = "path", sortDir = "asc" }) {
 	]);
 	const captionText = caption ?? `${rows.length} shadow${rows.length === 1 ? "" : "s"}${filter ? ` matching \`${filter}\`` : ""} · ${activeTheme}`;
 	if (rows.length === 0) return /* @__PURE__ */ jsx("div", {
-		...themeAttrs(cssVarPrefix, activeAxes),
+		...blockWrapperAttrs(cssVarPrefix, activeAxes),
 		children: /* @__PURE__ */ jsx("div", {
 			className: "sb-block__empty",
 			children: "No shadow tokens match this filter."
 		})
 	});
 	return /* @__PURE__ */ jsxs("div", {
-		...themeAttrs(cssVarPrefix, activeAxes),
+		...blockWrapperAttrs(cssVarPrefix, activeAxes),
 		children: [/* @__PURE__ */ jsx("div", {
 			className: "sb-block__caption",
 			children: captionText
@@ -2625,9 +2355,9 @@ function ShadowPreview({ filter, caption, sortBy = "path", sortDir = "asc" }) {
 function renderLayer(layer, format) {
 	if (!layer) return [];
 	const entries = [
-		["offset", `${formatDimension(layer.offsetX)} ${formatDimension(layer.offsetY)}`],
-		["blur", formatDimension(layer.blur)],
-		["spread", formatDimension(layer.spread)],
+		["offset", `${formatDimension$1(layer.offsetX)} ${formatDimension$1(layer.offsetY)}`],
+		["blur", formatDimension$1(layer.blur)],
+		["spread", formatDimension$1(layer.spread)],
 		["color", formatSubColor(layer.color, format)]
 	];
 	if (layer.inset) entries.push(["inset", String(layer.inset)]);
@@ -2654,7 +2384,7 @@ function Layer({ layer, index, total, colorFormat }) {
 	});
 }
 //#endregion
-//#region src/StrokeStyleSample.tsx
+//#region src/StrokeStylePreview.tsx
 const STRING_STYLES = new Set([
 	"solid",
 	"dashed",
@@ -2669,7 +2399,7 @@ function extractCssStyle(value) {
 	if (typeof value === "string" && STRING_STYLES.has(value)) return value;
 	return null;
 }
-function StrokeStyleSample({ filter, caption, sortBy = "path", sortDir = "asc" }) {
+function StrokeStylePreview({ filter, caption, sortBy = "path", sortDir = "asc" }) {
 	const project = useProject();
 	const { resolved, activeTheme, activeAxes, cssVarPrefix } = project;
 	const rows = useMemo(() => {
@@ -2694,14 +2424,14 @@ function StrokeStyleSample({ filter, caption, sortBy = "path", sortDir = "asc" }
 	]);
 	const captionText = caption ?? `${rows.length} strokeStyle token${rows.length === 1 ? "" : "s"}${filter && filter !== "strokeStyle" ? ` matching \`${filter}\`` : ""} · ${activeTheme}`;
 	if (rows.length === 0) return /* @__PURE__ */ jsx("div", {
-		...themeAttrs(cssVarPrefix, activeAxes),
+		...blockWrapperAttrs(cssVarPrefix, activeAxes),
 		children: /* @__PURE__ */ jsx("div", {
 			className: "sb-block__empty",
 			children: "No strokeStyle tokens match this filter."
 		})
 	});
 	return /* @__PURE__ */ jsxs("div", {
-		...themeAttrs(cssVarPrefix, activeAxes),
+		...blockWrapperAttrs(cssVarPrefix, activeAxes),
 		children: [/* @__PURE__ */ jsx("div", {
 			className: "sb-block__caption",
 			children: captionText
@@ -2833,15 +2563,13 @@ function AliasedByRow({ node, depth }) {
 function buildAliasedByTree(rootPath, resolved) {
 	const direct = resolved[rootPath]?.aliasedBy;
 	if (!direct || direct.length === 0) return [];
-	const visited = new Set([rootPath]);
-	return sortPaths(direct).map((p) => walk(p, resolved, visited, 1));
+	return sortPaths(direct).map((p) => walk(p, resolved, new Set([rootPath]), 1));
 }
-function walk(path, resolved, visited, depth) {
-	if (visited.has(path)) return {
+function walk(path, resolved, ancestors, depth) {
+	if (ancestors.has(path)) return {
 		path,
 		children: []
 	};
-	visited.add(path);
 	const parents = resolved[path]?.aliasedBy;
 	if (!parents || parents.length === 0) return {
 		path,
@@ -2852,9 +2580,10 @@ function walk(path, resolved, visited, depth) {
 		children: [],
 		truncated: true
 	};
+	const childAncestors = new Set(ancestors).add(path);
 	return {
 		path,
-		children: sortPaths(parents).map((p) => walk(p, resolved, visited, depth + 1))
+		children: sortPaths(parents).map((p) => walk(p, resolved, childAncestors, depth + 1))
 	};
 }
 function sortPaths(paths) {
@@ -3252,12 +2981,6 @@ function formatDimensionValue(v) {
 	}
 	return JSON.stringify(v);
 }
-/**
-* Route sub-value colors through `formatColor` so they honor the active
-* color-format dropdown, just like the standalone `<ColorPalette />` and
-* `<TokenDetail />` top-line do. Returns `null` for a missing field so
-* the key/value row drops out entirely.
-*/
 function formatColorSubValue(v, format) {
 	if (v == null) return null;
 	return formatColor(v, format).value;
@@ -3270,11 +2993,6 @@ function pickArrayAliases(v) {
 	if (!Array.isArray(v)) return void 0;
 	return v;
 }
-/**
-* Walk the alias chain starting from an immediate sub-value alias target.
-* `aliasTarget` is the path the sub-value directly references; the target
-* token's own `aliasChain` continues the walk to the primitive.
-*/
 function subValueChain(aliasTarget, resolved) {
 	if (!aliasTarget) return void 0;
 	const tail = (resolved?.[aliasTarget])?.aliasChain;
@@ -3294,6 +3012,35 @@ function gradientStopKey(stop, fallback) {
 	return `stop|${stop.position ?? fallback}|${JSON.stringify(stop.color)}`;
 }
 //#endregion
+//#region src/token-detail/transition-duration.ts
+/**
+* Numeric duration (ms) the motion preview should animate over for a given
+* token type, read from its resolved `$value`. Lets the sample's toggle loop
+* match the token's real duration instead of a fixed cadence — a long token
+* (say 2s) otherwise reverses mid-move under the old hardcoded interval.
+* Returns `undefined` for types that carry no duration, so the caller can
+* fall back to its default.
+*/
+function transitionDurationMs(type, rawValue) {
+	if (type === "cubicBezier") return 800;
+	if (type === "duration") return parseDurationMs(rawValue);
+	if (type === "transition" && rawValue !== null && typeof rawValue === "object") return parseDurationMs(rawValue.duration);
+}
+function parseDurationMs(v) {
+	if (typeof v === "number") return v;
+	if (typeof v === "string") {
+		const m = /^([\d.]+)(ms|s)?$/.exec(v.trim());
+		if (!m?.[1]) return void 0;
+		const n = Number(m[1]);
+		if (Number.isNaN(n)) return void 0;
+		return m[2] === "s" ? n * 1e3 : n;
+	}
+	if (v !== null && typeof v === "object") {
+		const d = v;
+		if (typeof d.value === "number") return d.unit === "s" ? d.value * 1e3 : d.value;
+	}
+}
+//#endregion
 //#region src/token-detail/CompositePreview.tsx
 const PANGRAM = "Sphinx of black quartz, judge my vow.";
 const STROKE_STYLE_STRINGS = new Set([
@@ -3340,7 +3087,10 @@ function CompositePreviewContent({ type, cssVar, rawValue }) {
 		style: { border: cssVar },
 		"aria-hidden": true
 	});
-	if (type === "transition") return /* @__PURE__ */ jsx(TransitionSample, { transition: cssVar });
+	if (type === "transition") return /* @__PURE__ */ jsx(TransitionSample, {
+		transition: cssVar,
+		durationMs: transitionDurationMs(type, rawValue)
+	});
 	if (type === "dimension") return /* @__PURE__ */ jsx("div", {
 		className: "sb-token-detail__dimension-track",
 		children: /* @__PURE__ */ jsx("div", {
@@ -3349,7 +3099,10 @@ function CompositePreviewContent({ type, cssVar, rawValue }) {
 			"aria-hidden": true
 		})
 	});
-	if (type === "duration") return /* @__PURE__ */ jsx(TransitionSample, { transition: `left ${cssVar} ease` });
+	if (type === "duration") return /* @__PURE__ */ jsx(TransitionSample, {
+		transition: `left ${cssVar} ease`,
+		durationMs: transitionDurationMs(type, rawValue)
+	});
 	if (type === "fontFamily") return /* @__PURE__ */ jsx("div", {
 		className: "sb-token-detail__font-family-sample",
 		style: { fontFamily: cssVar },
@@ -3360,13 +3113,16 @@ function CompositePreviewContent({ type, cssVar, rawValue }) {
 		style: { fontWeight: cssVarAsNumber(cssVar) },
 		children: "Aa"
 	});
-	if (type === "cubicBezier") return /* @__PURE__ */ jsx(TransitionSample, { transition: `left 800ms ${cssVar}` });
+	if (type === "cubicBezier") return /* @__PURE__ */ jsx(TransitionSample, {
+		transition: `left 800ms ${cssVar}`,
+		durationMs: transitionDurationMs(type, rawValue)
+	});
 	if (type === "gradient") return /* @__PURE__ */ jsx("div", {
 		className: "sb-token-detail__gradient-sample",
 		style: { background: `linear-gradient(to right, ${cssVar})` },
 		"aria-hidden": true
 	});
-	if (type === "strokeStyle") return /* @__PURE__ */ jsx(StrokeStylePreview, { value: rawValue });
+	if (type === "strokeStyle") return /* @__PURE__ */ jsx(StrokeStylePreview$1, { value: rawValue });
 	if (type === "color") return /* @__PURE__ */ jsxs("div", {
 		className: "sb-token-detail__color-swatch-row",
 		"aria-hidden": true,
@@ -3380,7 +3136,7 @@ function CompositePreviewContent({ type, cssVar, rawValue }) {
 	});
 	return null;
 }
-function StrokeStylePreview({ value }) {
+function StrokeStylePreview$1({ value }) {
 	if (typeof value === "string" && STROKE_STYLE_STRINGS.has(value)) return /* @__PURE__ */ jsx("div", {
 		className: "sb-token-detail__stroke-style-line",
 		style: { borderTopStyle: value },
@@ -3431,20 +3187,23 @@ function asDashLengths(raw) {
 	}
 	return out;
 }
-function TransitionSample({ transition }) {
+const DEFAULT_LOOP_MS = 1200;
+const MOTION_HOLD_MS = 400;
+function TransitionSample({ transition, durationMs }) {
 	const reduced = usePrefersReducedMotion();
 	const [phase, setPhase] = useState(0);
 	useEffect(() => {
 		if (reduced) return;
+		const loopMs = durationMs === void 0 ? DEFAULT_LOOP_MS : durationMs + MOTION_HOLD_MS;
 		const id = requestAnimationFrame(() => setPhase(1));
 		const loop = window.setInterval(() => {
 			setPhase((p) => p === 0 ? 1 : 0);
-		}, 1200);
+		}, loopMs);
 		return () => {
 			cancelAnimationFrame(id);
 			window.clearInterval(loop);
 		};
-	}, [reduced]);
+	}, [reduced, durationMs]);
 	if (reduced) return /* @__PURE__ */ jsx("div", {
 		className: "sb-token-detail__reduced-motion",
 		children: "Animation suppressed by `prefers-reduced-motion: reduce`."
@@ -3579,11 +3338,6 @@ function TokenHeader({ path, heading }) {
 }
 //#endregion
 //#region src/token-detail/TokenUsageSnippet.tsx
-/**
-* DTCG `$type`s with a single canonical CSS property. Types whose value is
-* applied across many properties (`dimension`, `number`, `strokeStyle`,
-* `typography`) are intentionally absent — they fall back to a commented hint.
-*/
 const CSS_PROPERTY_BY_TYPE = {
 	color: "color",
 	shadow: "box-shadow",
@@ -3624,10 +3378,11 @@ function TokenUsageSnippet({ path }) {
 function TokenDetail({ path, heading }) {
 	const { token, cssVar, activeTheme, activeAxes, cssVarPrefix } = useTokenDetailData(path);
 	const colorFormat = useColorFormat();
-	const theme = themeAttrs(cssVarPrefix, activeAxes);
+	const { listing } = useProject();
+	const wrapperAttrs = blockWrapperAttrs(cssVarPrefix, activeAxes);
 	if (!token) return /* @__PURE__ */ jsx("div", {
-		...theme,
-		className: cx(theme["className"], "sb-token-detail"),
+		...wrapperAttrs,
+		className: cx(wrapperAttrs["className"], "sb-token-detail"),
 		children: /* @__PURE__ */ jsxs("div", {
 			className: "sb-token-detail__missing",
 			children: [
@@ -3639,14 +3394,13 @@ function TokenDetail({ path, heading }) {
 			]
 		})
 	});
-	const { listing } = useProject();
 	const isColor = token.$type === "color";
 	const gamut = isColor ? formatColor(token.$value, colorFormat) : null;
 	const value = formatTokenValue(token.$value, token.$type, colorFormat, listing[path]);
 	const outOfGamut = gamut?.outOfGamut ?? false;
 	return /* @__PURE__ */ jsxs("div", {
-		...theme,
-		className: cx(theme["className"], "sb-token-detail"),
+		...wrapperAttrs,
+		className: cx(wrapperAttrs["className"], "sb-token-detail"),
 		children: [
 			/* @__PURE__ */ jsx(TokenHeader, {
 				path,
@@ -3689,12 +3443,6 @@ function TokenDetail({ path, heading }) {
 }
 //#endregion
 //#region src/internal/DetailOverlay.tsx
-/**
-* Selector for elements the trap considers focus stops. Mirrors the
-* "tabbable" set most focus-trap libraries use; the `:not(...)` clauses
-* skip the panel wrapper itself (we focus it manually on mount via its
-* own ref) and any explicitly-detabbed descendants.
-*/
 const FOCUSABLE_SELECTOR = [
 	"a[href]",
 	"button:not([disabled])",
@@ -3734,11 +3482,6 @@ function DetailOverlay({ path, onClose, testId = "swatchbook-overlay" }) {
 		window.addEventListener("keydown", onKey);
 		return () => window.removeEventListener("keydown", onKey);
 	}, [onClose]);
-	/**
-	* Wrap Tab inside the panel: from the last focusable, jump to the first;
-	* from the first (or from the panel itself), Shift+Tab jumps to the last.
-	* Defers to the browser otherwise.
-	*/
 	const onPanelKeyDown = (e) => {
 		if (e.key !== "Tab") return;
 		const panel = panelRef.current;
@@ -3787,12 +3530,6 @@ function DetailOverlay({ path, onClose, testId = "swatchbook-overlay" }) {
 		})
 	});
 }
-/**
-* Walk up from `node` to the direct child of `<body>` that contains it.
-* Returns `null` when the node isn't attached to the document (mid-mount,
-* post-unmount). Used to identify which top-level branch to *not* mark
-* inert when the overlay opens.
-*/
 function findBodyChildContaining(node) {
 	let cursor = node;
 	while (cursor && cursor.parentElement !== document.body) cursor = cursor.parentElement;
@@ -3886,11 +3623,6 @@ function flattenVisible(nodes, expanded, parentPath, out) {
 		if (node.kind === "group" && expanded.has(node.path)) flattenVisible(node.children, expanded, node.path, out);
 	}
 }
-/**
-* Return a pruned copy of the tree keeping only leaves whose path is in
-* `matches`, plus the groups on the way to them. Every surviving group's
-* path is added to `expandOut` so callers can force those groups open.
-*/
 function pruneTreeForMatches(nodes, matches, expandOut) {
 	const out = [];
 	for (const node of nodes) if (node.kind === "leaf") {
@@ -4092,11 +3824,11 @@ function TokenNavigator({ root, type, initiallyExpanded = 1, searchable = true,
 		return n;
 	}, [visibleTree, searchExpanded]);
 	if (tree.length === 0) return /* @__PURE__ */ jsx("div", {
-		...themeAttrs(cssVarPrefix, activeAxes),
+		...blockWrapperAttrs(cssVarPrefix, activeAxes),
 		children: /* @__PURE__ */ jsx(EmptyState, { children: root ? `No tokens under "${root}"${typeFilter ? ` matching ${typeLabel.slice(3)}` : ""}.` : typeFilter ? `No tokens matching ${typeLabel.slice(3)} in the active theme.` : "No tokens in the active theme." })
 	});
 	return /* @__PURE__ */ jsxs("div", {
-		...themeAttrs(cssVarPrefix, activeAxes),
+		...blockWrapperAttrs(cssVarPrefix, activeAxes),
 		children: [
 			searchable && /* @__PURE__ */ jsx("div", {
 				className: "sb-token-navigator__search",
@@ -4288,7 +4020,7 @@ const LeafPreview = memo(function LeafPreview({ path, token }) {
 			className: "sb-token-navigator__preview-dimension",
 			children: /* @__PURE__ */ jsx(DimensionBar, {
 				path,
-				kind: "length"
+				visual: "length"
 			})
 		})]
 	});
@@ -4378,14 +4110,14 @@ function TokenTable({ filter, type, caption, sortBy = "path", sortDir = "asc", s
 	const matchSuffix = searchable && query.trim() !== "" ? ` · ${visibleRows.length} matching "${query.trim()}"` : "";
 	const captionText = caption ?? `${rows.length} token${rows.length === 1 ? "" : "s"}${filter ? ` matching \`${filter}\`` : ""}${type ? ` · $type=${type}` : ""}${matchSuffix} · ${activeTheme}`;
 	if (rows.length === 0) return /* @__PURE__ */ jsx("div", {
-		...themeAttrs(cssVarPrefix, activeAxes),
+		...blockWrapperAttrs(cssVarPrefix, activeAxes),
 		children: /* @__PURE__ */ jsx("div", {
 			className: "sb-block__empty",
 			children: "No tokens match this filter."
 		})
 	});
 	return /* @__PURE__ */ jsxs("div", {
-		...themeAttrs(cssVarPrefix, activeAxes),
+		...blockWrapperAttrs(cssVarPrefix, activeAxes),
 		children: [
 			searchable && /* @__PURE__ */ jsx("div", {
 				className: "sb-token-table__search",
@@ -4557,14 +4289,14 @@ function TypographyScale({ filter, sample = "The quick brown fox jumps over the
 	]);
 	const captionText = caption ?? `${rows.length} typography token${rows.length === 1 ? "" : "s"}${filter && filter !== "typography" ? ` matching \`${filter}\`` : ""} · ${activeTheme}`;
 	if (rows.length === 0) return /* @__PURE__ */ jsx("div", {
-		...themeAttrs(cssVarPrefix, activeAxes),
+		...blockWrapperAttrs(cssVarPrefix, activeAxes),
 		children: /* @__PURE__ */ jsx("div", {
 			className: "sb-block__empty",
 			children: "No typography tokens match this filter."
 		})
 	});
 	return /* @__PURE__ */ jsxs("div", {
-		...themeAttrs(cssVarPrefix, activeAxes),
+		...blockWrapperAttrs(cssVarPrefix, activeAxes),
 		children: [/* @__PURE__ */ jsx("div", {
 			className: "sb-block__caption",
 			children: captionText
@@ -4587,6 +4319,6 @@ function TypographyScale({ filter, sample = "The quick brown fox jumps over the
 	});
 }
 //#endregion
-export { AliasChain, AliasedBy, AxesContext, AxisVariance, BorderPreview, BorderSample, COLOR_FORMATS, ColorFormatContext, ColorPalette, ColorTable, CompositeBreakdown, CompositePreview, ConsumerOutput, Diagnostics, DimensionBar, DimensionScale, FontFamilySample, FontWeightScale, GradientPalette, MotionPreview, MotionSample, OpacityScale, ShadowPreview, ShadowSample, StrokeStyleSample, SwatchbookContext, SwatchbookProvider, ThemeContext, TokenDetail, TokenHeader, TokenNavigator, TokenTable, TokenUsageSnippet, TypographyScale, formatColor, useActiveAxes, useActiveTheme, useColorFormat, useOptionalSwatchbookData, useSwatchbookData };
+export { AliasChain, AliasedBy, AxesContext, AxisVariance, BorderPreview, BorderSample, COLOR_FORMATS, ColorFormatContext, ColorPalette, ColorTable, CompositeBreakdown, CompositePreview, ConsumerOutput, Diagnostics, DimensionBar, DimensionScale, FontFamilyPreview, FontWeightScale, GradientPalette, MotionPreview, MotionSample, OpacityScale, ShadowPreview, ShadowSample, StrokeStylePreview, SwatchbookContext, SwatchbookProvider, TOKENS_UPDATED_EVENT, ThemeContext, TokenDetail, TokenHeader, TokenNavigator, TokenTable, TokenUsageSnippet, TypographyScale, formatColor, registerTokenSource, useActiveAxes, useActiveTheme, useChannelGlobals, useColorFormat, useOptionalSwatchbookData, useSwatchbookData, useTokenSnapshot };
 
 //# sourceMappingURL=index.mjs.map