From d3e04a1dcd3a72e64ee337258fe34f4c937313fd Mon Sep 17 00:00:00 2001
From: Luke Bennett <hello@lukebennett.com.au>
Date: Wed, 12 Aug 2026 16:19:51 +1000
Subject: [PATCH] Update Playground toolbars and alignment

---
 .../docs/src/components/playground/editor.tsx |  7 +-
 .../playground/icon-toggle-button-group.tsx   | 96 +++++++++----------
 .../playground/pane-toolbar.browser.test.ts   | 81 ++++++++++++++++
 .../components/playground/pane-toolbar.tsx    | 20 ++++
 .../components/playground/preview-toolbar.tsx |  5 +-
 5 files changed, 154 insertions(+), 55 deletions(-)
 create mode 100644 apps/docs/src/components/playground/pane-toolbar.browser.test.ts
 create mode 100644 apps/docs/src/components/playground/pane-toolbar.tsx

diff --git a/apps/docs/src/components/playground/editor.tsx b/apps/docs/src/components/playground/editor.tsx
index 58adae09..6f571459 100644
--- a/apps/docs/src/components/playground/editor.tsx
+++ b/apps/docs/src/components/playground/editor.tsx
@@ -10,6 +10,7 @@ import {
 	runFormatDocument,
 } from '../../lib/playground-format';
 import { EditorSkeleton } from './editor-skeleton';
+import { PlaygroundPaneToolbar } from './pane-toolbar.js';
 
 type PlaygroundEditorProps = {
 	defaultValue: string;
@@ -48,16 +49,16 @@ export default function PlaygroundEditor({
 
 	return (
 		<div className="flex h-full min-h-0 flex-col">
-			<div className="flex shrink-0 items-center border-fd-border border-b bg-fd-background px-2 py-1.5 sm:px-3">
+			<PlaygroundPaneToolbar>
 				<Button
-					appearance="ghost"
+					appearance="subtle"
 					isPending={isFormatting}
 					onPress={() => void handleFormat()}
 					size="small"
 				>
 					Format
 				</Button>
-			</div>
+			</PlaygroundPaneToolbar>
 			<div className="min-h-0 flex-1">
 				<Editor
 					height="100%"
diff --git a/apps/docs/src/components/playground/icon-toggle-button-group.tsx b/apps/docs/src/components/playground/icon-toggle-button-group.tsx
index 252e0f37..3082af5d 100644
--- a/apps/docs/src/components/playground/icon-toggle-button-group.tsx
+++ b/apps/docs/src/components/playground/icon-toggle-button-group.tsx
@@ -1,33 +1,11 @@
 import type { IconName } from '@luke-ui/react/icon';
 import { Icon } from '@luke-ui/react/icon';
-import { cx } from '@luke-ui/react/utils';
+import { button } from '@luke-ui/react/recipes';
+import type { ComponentProps } from 'react';
 import type { Selection } from 'react-aria-components/GridList';
 import { ToggleButton } from 'react-aria-components/ToggleButton';
 import { ToggleButtonGroup } from 'react-aria-components/ToggleButtonGroup';
 
-/** Rounded pill group shared by every toggle group in this file, matched on shape and focus. */
-const GROUP_CLASS_NAME = 'flex items-center rounded-full bg-fd-secondary p-0.5';
-
-/** Selected/unselected pill treatment shared by icon and text toggle buttons. */
-const PILL_CLASS_NAME =
-	'cursor-pointer rounded-full text-fd-muted-foreground transition-colors data-hovered:bg-fd-accent data-hovered:text-fd-accent-foreground data-pressed:bg-fd-accent';
-const PILL_SELECTED_CLASS_NAME = 'bg-fd-background text-fd-foreground shadow-sm';
-
-function toSelectionChangeHandler<Value extends string>(
-	options: ReadonlyArray<{ value: Value }>,
-	onChange: (value: Value) => void,
-) {
-	return (selection: Selection) => {
-		if (selection === 'all') return;
-
-		const selectedKey = selection.values().next().value;
-		const selectedOption = options.find((option) => option.value === selectedKey);
-		if (!selectedOption) return;
-
-		onChange(selectedOption.value);
-	};
-}
-
 type IconToggleItem<Value extends string> = {
 	icon: IconName;
 	label: string;
@@ -41,6 +19,20 @@ type IconToggleButtonGroupProps<Value extends string> = {
 	value: Value | null;
 };
 
+type TextToggleItem<Value extends string> = {
+	label: string;
+	value: Value;
+};
+
+type TextToggleButtonGroupProps<Value extends string> = {
+	label: string;
+	onChange: (value: Value) => void;
+	options: ReadonlyArray<TextToggleItem<Value>>;
+	value: Value;
+};
+
+const GROUP_CLASS_NAME = 'flex items-center gap-2 bg-fd-secondary p-0.5';
+
 /** A round icon-only pill group, for choices with well-known glyphs such as light/dark/system. */
 export function IconToggleButtonGroup<Value extends string>({
 	label,
@@ -61,15 +53,10 @@ export function IconToggleButtonGroup<Value extends string>({
 			{options.map(({ icon, label: optionLabel, value: optionValue }) => (
 				<ToggleButton
 					aria-label={optionLabel}
-					className={({ isSelected }) => {
-						return cx(
-							'flex size-8 items-center justify-center',
-							PILL_CLASS_NAME,
-							isSelected && PILL_SELECTED_CLASS_NAME,
-						);
-					}}
+					className={button({ appearance: 'subtle', size: 'small', tone: 'neutral' })}
 					id={optionValue}
 					key={optionValue}
+					render={renderToggleButton}
 				>
 					<Icon aria-hidden className="size-4" name={icon} />
 				</ToggleButton>
@@ -78,18 +65,6 @@ export function IconToggleButtonGroup<Value extends string>({
 	);
 }
 
-type TextToggleItem<Value extends string> = {
-	label: string;
-	value: Value;
-};
-
-type TextToggleButtonGroupProps<Value extends string> = {
-	label: string;
-	onChange: (value: Value) => void;
-	options: ReadonlyArray<TextToggleItem<Value>>;
-	value: Value;
-};
-
 /**
  * A round pill group with visible text labels, for choices without an established glyph, such as
  * a named theme identity. Matches `IconToggleButtonGroup` in height, radius, and focus treatment.
@@ -112,15 +87,10 @@ export function TextToggleButtonGroup<Value extends string>({
 		>
 			{options.map(({ label: optionLabel, value: optionValue }) => (
 				<ToggleButton
-					className={({ isSelected }) => {
-						return cx(
-							'flex h-8 items-center justify-center whitespace-nowrap px-3 font-medium text-xs',
-							PILL_CLASS_NAME,
-							isSelected && PILL_SELECTED_CLASS_NAME,
-						);
-					}}
+					className={button({ appearance: 'subtle', size: 'small', tone: 'neutral' })}
 					id={optionValue}
 					key={optionValue}
+					render={renderToggleButton}
 				>
 					{optionLabel}
 				</ToggleButton>
@@ -128,3 +98,29 @@ export function TextToggleButtonGroup<Value extends string>({
 		</ToggleButtonGroup>
 	);
 }
+
+type RenderToggleButton = ComponentProps<typeof ToggleButton>['render'];
+
+/**
+ * Renders the toggle's `<button>` with `data-pressed` kept true while selected, so the selected
+ * toggle stays in the recipe's pressed treatment. `data-pressed` is a styling hook; the
+ * `aria-pressed` state comes from RAC's selection props.
+ */
+const renderToggleButton: RenderToggleButton = (domProps, state) => {
+	return <button {...domProps} data-pressed={state.isPressed || state.isSelected || undefined} />;
+};
+
+function toSelectionChangeHandler<Value extends string>(
+	options: ReadonlyArray<{ value: Value }>,
+	onChange: (value: Value) => void,
+) {
+	return (selection: Selection) => {
+		if (selection === 'all') return;
+
+		const selectedKey = selection.values().next().value;
+		const selectedOption = options.find((option) => option.value === selectedKey);
+		if (!selectedOption) return;
+
+		onChange(selectedOption.value);
+	};
+}
diff --git a/apps/docs/src/components/playground/pane-toolbar.browser.test.ts b/apps/docs/src/components/playground/pane-toolbar.browser.test.ts
new file mode 100644
index 00000000..3fde8d1a
--- /dev/null
+++ b/apps/docs/src/components/playground/pane-toolbar.browser.test.ts
@@ -0,0 +1,81 @@
+import '../../styles/app.css';
+import '@luke-ui/react/themes/paper/stylesheet.css';
+import '@luke-ui/react/themes/tactile/stylesheet.css';
+import { Button } from '@luke-ui/react/button';
+import { act, createElement, useState } from 'react';
+import type { Root } from 'react-dom/client';
+import { createRoot } from 'react-dom/client';
+import { afterEach, expect, test } from 'vite-plus/test';
+import { StoryWrapper } from '../../lib/story-wrapper';
+import { DocsThemeRoot } from '../theme-controls';
+import { PlaygroundPaneToolbar } from './pane-toolbar.js';
+import { PreviewToolbar } from './preview-toolbar.js';
+import type { ViewportWidth } from './viewport-toggle.js';
+
+let container: HTMLElement | undefined;
+let root: Root | undefined;
+
+afterEach(() => {
+	if (root) act(() => root?.unmount());
+	container?.remove();
+	container = undefined;
+	root = undefined;
+});
+
+test('editor and preview toolbars share the same block size', () => {
+	renderToolbars();
+
+	const [editorToolbar, previewToolbar] = getToolbars();
+	expect(editorToolbar.offsetHeight).toBe(previewToolbar.offsetHeight);
+});
+
+function renderToolbars() {
+	container = document.body.appendChild(document.createElement('div'));
+	root = createRoot(container);
+
+	act(() => {
+		root?.render(
+			createElement(
+				DocsThemeRoot,
+				null,
+				createElement(StoryWrapper, null, createElement(ToolbarHarness)),
+			),
+		);
+	});
+}
+
+function ToolbarHarness() {
+	const [viewportWidth, setViewportWidth] = useState<ViewportWidth>('100%');
+	const [isFullscreen, setIsFullscreen] = useState(false);
+
+	return createElement(
+		'div',
+		{ 'data-testid': 'toolbar-harness' },
+		createElement(
+			PlaygroundPaneToolbar,
+			null,
+			createElement(Button, { appearance: 'ghost', size: 'small' }, 'Format'),
+		),
+		createElement(PreviewToolbar, {
+			isFullscreen,
+			onFullscreenChange: setIsFullscreen,
+			onViewportChange: setViewportWidth,
+			viewportWidth,
+		}),
+	);
+}
+
+function getToolbars(): [HTMLElement, HTMLElement] {
+	const harness = container?.querySelector('[data-testid="toolbar-harness"]');
+	if (!harness || harness.children.length !== 2) {
+		throw new Error('expected editor and preview toolbars');
+	}
+
+	const editorToolbar = harness.children[0];
+	const previewToolbar = harness.children[1];
+	if (!(editorToolbar instanceof HTMLElement) || !(previewToolbar instanceof HTMLElement)) {
+		throw new Error('expected editor and preview toolbars');
+	}
+
+	return [editorToolbar, previewToolbar];
+}
diff --git a/apps/docs/src/components/playground/pane-toolbar.tsx b/apps/docs/src/components/playground/pane-toolbar.tsx
new file mode 100644
index 00000000..dc79c43e
--- /dev/null
+++ b/apps/docs/src/components/playground/pane-toolbar.tsx
@@ -0,0 +1,20 @@
+import { cx } from '@luke-ui/react/utils';
+import type { ReactNode } from 'react';
+
+type PlaygroundPaneToolbarProps = {
+	children: ReactNode;
+	className?: string;
+};
+
+const TOOLBAR_CLASS_NAME =
+	'flex shrink-0 items-center border-fd-border border-b bg-fd-background px-2 py-1.5 sm:px-3';
+
+/** IconToggleButtonGroup: size-8 buttons plus p-0.5 wrapper padding. */
+const MIN_BLOCK_SIZE_CLASS_NAME = 'min-block-[calc(2rem+--spacing(0.5)*2+--spacing(1.5)*2+1px)]';
+
+/** Shared toolbar chrome for editor and preview panes so bottom borders align. */
+export function PlaygroundPaneToolbar({ children, className }: PlaygroundPaneToolbarProps) {
+	return (
+		<div className={cx(TOOLBAR_CLASS_NAME, MIN_BLOCK_SIZE_CLASS_NAME, className)}>{children}</div>
+	);
+}
diff --git a/apps/docs/src/components/playground/preview-toolbar.tsx b/apps/docs/src/components/playground/preview-toolbar.tsx
index 9ae9f4d4..a1e5968e 100644
--- a/apps/docs/src/components/playground/preview-toolbar.tsx
+++ b/apps/docs/src/components/playground/preview-toolbar.tsx
@@ -1,5 +1,6 @@
 import { IconButton } from '@luke-ui/react/icon-button';
 import type { Dispatch, SetStateAction } from 'react';
+import { PlaygroundPaneToolbar } from './pane-toolbar.js';
 import type { ViewportWidth } from './viewport-toggle.js';
 import { ViewportToggle } from './viewport-toggle.js';
 
@@ -26,7 +27,7 @@ export function PreviewToolbar({
 	viewportWidth,
 }: PreviewToolbarProps) {
 	return (
-		<div className="flex shrink-0 items-center justify-between gap-2 border-fd-border border-b bg-fd-background px-2 py-1.5 sm:px-3">
+		<PlaygroundPaneToolbar className="justify-between gap-2">
 			<ViewportToggle onChange={onViewportChange} value={viewportWidth} />
 			<IconButton
 				appearance="ghost"
@@ -35,6 +36,6 @@ export function PreviewToolbar({
 				onPress={() => onFullscreenChange((prev) => !prev)}
 				size="small"
 			/>
-		</div>
+		</PlaygroundPaneToolbar>
 	);
 }
-- 
2.51.2