From 7bd332b6ca227c4152632769897589979253ef59 Mon Sep 17 00:00:00 2001
From: Luke Bennett <hello@lukebennett.com.au>
Date: Sat, 25 Jul 2026 16:06:32 +1000
Subject: [PATCH] Rebuild the theme identity control and fix the icon collision
 (#265)
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

* Replace the docs theme identity select with a matching pill control

The theme identity picker was a raw native <select>, the only native
form control on the docs surface, squeezed to ~200px in the sidebar
footer and truncating "Tactile". Add a text-label segmented toggle
group alongside the existing icon-only one, sharing the same pill
shape, height, and focus treatment as the colour-mode group beside it,
and use it for theme identity in both the sidebar footer and the
playground header.

Also give system colour mode a settings-gear glyph so it no longer
collides with the monitor icon used for the Desktop viewport option.

* Swap the system colour-mode glyph for a half-filled circle

A settings cog reads as "open theme options", not "follow the
operating system" — a misleading glyph, not just an ambiguous one.
Replace it with the conventional split-circle contrast mark (one
half filled, one half outline), which reads as "either of these two,
decided for you". Matches the existing icon set's outline
conventions (24x24 viewBox, currentColor stroke) apart from the
filled half the mark requires.
---
 .../playground/color-mode-toggle.tsx          |   2 +-
 .../playground/icon-toggle-button-group.tsx   | 102 ++++++++++++++----
 .../theme-controls.browser.test.tsx           |  36 ++++++-
 apps/docs/src/components/theme-controls.tsx   |  30 +++---
 packages/@luke-ui/react/icons/circleHalf.svg  |   4 +
 5 files changed, 133 insertions(+), 41 deletions(-)
 create mode 100644 packages/@luke-ui/react/icons/circleHalf.svg

diff --git a/apps/docs/src/components/playground/color-mode-toggle.tsx b/apps/docs/src/components/playground/color-mode-toggle.tsx
index ee200b46..18e0d60d 100644
--- a/apps/docs/src/components/playground/color-mode-toggle.tsx
+++ b/apps/docs/src/components/playground/color-mode-toggle.tsx
@@ -5,7 +5,7 @@ import { IconToggleButtonGroup } from './icon-toggle-button-group.js';
 const COLOR_MODES = [
 	{ icon: 'sun', label: 'Light theme', value: 'light' },
 	{ icon: 'moon', label: 'Dark theme', value: 'dark' },
-	{ icon: 'monitor', label: 'System theme', value: 'system' },
+	{ icon: 'circleHalf', label: 'System theme', value: 'system' },
 ] as const;
 
 type ColorMode = (typeof COLOR_MODES)[number]['value'];
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 c4f1137d..941763ef 100644
--- a/apps/docs/src/components/playground/icon-toggle-button-group.tsx
+++ b/apps/docs/src/components/playground/icon-toggle-button-group.tsx
@@ -5,6 +5,29 @@ 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;
@@ -18,28 +41,19 @@ type IconToggleButtonGroupProps<Value extends string> = {
 	value: Value | null;
 };
 
+/** A round icon-only pill group, for choices with well-known glyphs such as light/dark/system. */
 export function IconToggleButtonGroup<Value extends string>({
 	label,
 	onChange,
 	options,
 	value,
 }: IconToggleButtonGroupProps<Value>) {
-	const handleSelectionChange = (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);
-	};
-
 	return (
 		<ToggleButtonGroup
 			aria-label={label}
-			className="flex items-center rounded-full bg-fd-secondary p-0.5"
+			className={GROUP_CLASS_NAME}
 			disallowEmptySelection={value !== null}
-			onSelectionChange={handleSelectionChange}
+			onSelectionChange={toSelectionChangeHandler(options, onChange)}
 			orientation="horizontal"
 			selectedKeys={value === null ? [] : [value]}
 			selectionMode="single"
@@ -47,12 +61,13 @@ export function IconToggleButtonGroup<Value extends string>({
 			{options.map(({ icon, label: optionLabel, value: optionValue }) => (
 				<ToggleButton
 					aria-label={optionLabel}
-					className={({ isSelected }) => {
-						return cx(
-							'flex size-8 cursor-pointer items-center justify-center rounded-full text-fd-muted-foreground transition-colors data-hovered:bg-fd-accent data-hovered:text-fd-accent-foreground data-pressed:bg-fd-accent',
-							isSelected && 'bg-fd-background text-fd-foreground shadow-sm',
-						);
-					}}
+					className={({ isSelected }) =>
+						cx(
+							'flex size-8 items-center justify-center',
+							PILL_CLASS_NAME,
+							isSelected && PILL_SELECTED_CLASS_NAME,
+						)
+					}
 					id={optionValue}
 					key={optionValue}
 				>
@@ -62,3 +77,54 @@ export function IconToggleButtonGroup<Value extends string>({
 		</ToggleButtonGroup>
 	);
 }
+
+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.
+ */
+export function TextToggleButtonGroup<Value extends string>({
+	label,
+	onChange,
+	options,
+	value,
+}: TextToggleButtonGroupProps<Value>) {
+	return (
+		<ToggleButtonGroup
+			aria-label={label}
+			className={GROUP_CLASS_NAME}
+			disallowEmptySelection
+			onSelectionChange={toSelectionChangeHandler(options, onChange)}
+			orientation="horizontal"
+			selectedKeys={[value]}
+			selectionMode="single"
+		>
+			{options.map(({ label: optionLabel, value: optionValue }) => (
+				<ToggleButton
+					className={({ isSelected }) =>
+						cx(
+							'flex h-8 items-center justify-center whitespace-nowrap px-3 font-medium text-xs',
+							PILL_CLASS_NAME,
+							isSelected && PILL_SELECTED_CLASS_NAME,
+						)
+					}
+					id={optionValue}
+					key={optionValue}
+				>
+					{optionLabel}
+				</ToggleButton>
+			))}
+		</ToggleButtonGroup>
+	);
+}
diff --git a/apps/docs/src/components/theme-controls.browser.test.tsx b/apps/docs/src/components/theme-controls.browser.test.tsx
index ecc75ce7..520fc420 100644
--- a/apps/docs/src/components/theme-controls.browser.test.tsx
+++ b/apps/docs/src/components/theme-controls.browser.test.tsx
@@ -1,6 +1,8 @@
 import '../styles/app.css';
 import '@luke-ui/react/themes/paper.css';
 import '@luke-ui/react/themes/tactile.css';
+import { IconSpritesheetProvider } from '@luke-ui/react/icon';
+import spriteSheetHref from '@luke-ui/react/spritesheet.svg?url&no-inline';
 import { paperThemeClassName } from '@luke-ui/react/themes';
 import { ThemeProvider } from 'next-themes';
 import { act } from 'react';
@@ -36,13 +38,13 @@ test('persists theme identity and colour mode independently', async () => {
 		</>,
 	);
 
-	const profile = page.getByRole('combobox', { name: 'Theme profile' });
+	const paperProfile = page.getByRole('radio', { name: 'Paper' });
 	const darkMode = page.getByRole('radio', { name: 'Dark theme' });
 	const themeRoot = getThemeRoot();
 
-	await userEvent.selectOptions(profile, 'paper');
+	await userEvent.click(paperProfile, { force: true });
 
-	expect(profile).toHaveValue('paper');
+	expect(paperProfile).toBeChecked();
 	expect(themeRoot).toHaveClass(paperThemeClassName);
 	expect(themeRoot.dataset.colorMode).toBe('light');
 
@@ -54,12 +56,34 @@ test('persists theme identity and colour mode independently', async () => {
 	unmountTheme();
 	renderTheme(<ThemeControls />);
 
-	expect(page.getByRole('combobox', { name: 'Theme profile' })).toHaveValue('paper');
+	expect(page.getByRole('radio', { name: 'Paper' })).toBeChecked();
 	expect(page.getByRole('radio', { name: 'Dark theme' })).toBeChecked();
 	expect(getThemeRoot()).toHaveClass(paperThemeClassName);
 	await expect.poll(() => getThemeRoot().dataset.colorMode).toBe('dark');
 });
 
+test('theme profile is labelled and operable with arrow keys', async () => {
+	renderTheme(<ThemeControls />);
+
+	const group = page.getByRole('radiogroup', { name: 'Theme profile' });
+	const tactileProfile = page.getByRole('radio', { name: 'Tactile' });
+	const paperProfile = page.getByRole('radio', { name: 'Paper' });
+
+	expect(group.element()).toBeInTheDocument();
+	expect(tactileProfile).toBeChecked();
+
+	await userEvent.tab();
+	expect(tactileProfile.element()).toHaveFocus();
+
+	await userEvent.keyboard('{ArrowRight}');
+	expect(paperProfile.element()).toHaveFocus();
+
+	await userEvent.keyboard('{Enter}');
+
+	expect(paperProfile).toBeChecked();
+	expect(getThemeRoot()).toHaveClass(paperThemeClassName);
+});
+
 test('system colour mode follows the platform preference and drives the docs chrome', async () => {
 	await emulateColorScheme('dark');
 	renderTheme(<ThemeControls />, { defaultTheme: 'system', enableSystem: true });
@@ -165,7 +189,9 @@ function renderTheme(
 				defaultTheme={options.defaultTheme ?? 'light'}
 				enableSystem={options.enableSystem ?? false}
 			>
-				<DocsThemeRoot>{children}</DocsThemeRoot>
+				<IconSpritesheetProvider href={spriteSheetHref}>
+					<DocsThemeRoot>{children}</DocsThemeRoot>
+				</IconSpritesheetProvider>
 			</ThemeProvider>,
 		);
 	});
diff --git a/apps/docs/src/components/theme-controls.tsx b/apps/docs/src/components/theme-controls.tsx
index d232f2c8..c1136f35 100644
--- a/apps/docs/src/components/theme-controls.tsx
+++ b/apps/docs/src/components/theme-controls.tsx
@@ -1,15 +1,21 @@
 import { themeRootClassName } from '@luke-ui/react/theme';
 import { paperThemeClassName, tactileThemeClassName } from '@luke-ui/react/themes';
 import { cx } from '@luke-ui/react/utils';
-import type { ChangeEvent, ComponentProps, PropsWithChildren } from 'react';
+import type { ComponentProps, PropsWithChildren } from 'react';
 import { createContext, useContext, useMemo, useSyncExternalStore } from 'react';
 import { ColorModeToggle, useHydratedColorMode } from './playground/color-mode-toggle.js';
+import { TextToggleButtonGroup } from './playground/icon-toggle-button-group.js';
 
 export type ThemeIdentity = 'paper' | 'tactile';
 
 const THEME_IDENTITY_STORAGE_KEY = 'luke-ui-docs-theme';
 const THEME_IDENTITY_CHANGE_EVENT = 'luke-ui-docs-theme-change';
 
+const THEME_IDENTITIES = [
+	{ label: 'Tactile', value: 'tactile' },
+	{ label: 'Paper', value: 'paper' },
+] as const satisfies ReadonlyArray<{ label: string; value: ThemeIdentity }>;
+
 interface ThemeIdentitySettings {
 	setThemeIdentity: (themeIdentity: ThemeIdentity) => void;
 	themeIdentity: ThemeIdentity;
@@ -43,24 +49,14 @@ export function DocsThemeRoot({ children }: PropsWithChildren) {
 export function ThemeControls({ className, ...props }: ComponentProps<'div'>) {
 	const { setThemeIdentity, themeIdentity } = useDocsThemeIdentity();
 
-	function handleThemeChange(event: ChangeEvent<HTMLSelectElement>) {
-		setThemeIdentity(event.target.value === 'paper' ? 'paper' : 'tactile');
-	}
-
 	return (
 		<div {...props} className={cx('flex items-center gap-1', className)}>
-			<label>
-				<span className="sr-only">Theme profile</span>
-				<select
-					aria-label="Theme profile"
-					className="h-8 rounded-md border border-fd-border bg-fd-background px-2 text-fd-foreground text-xs"
-					onChange={handleThemeChange}
-					value={themeIdentity}
-				>
-					<option value="tactile">Tactile</option>
-					<option value="paper">Paper</option>
-				</select>
-			</label>
+			<TextToggleButtonGroup
+				label="Theme profile"
+				onChange={setThemeIdentity}
+				options={THEME_IDENTITIES}
+				value={themeIdentity}
+			/>
 			<ColorModeToggle />
 		</div>
 	);
diff --git a/packages/@luke-ui/react/icons/circleHalf.svg b/packages/@luke-ui/react/icons/circleHalf.svg
new file mode 100644
index 00000000..1f37069b
--- /dev/null
+++ b/packages/@luke-ui/react/icons/circleHalf.svg
@@ -0,0 +1,4 @@
+<svg xmlns="http://www.w3.org/2000/svg" fill="none" viewBox="0 0 24 24" stroke-width="1.5" stroke="currentColor" aria-hidden="true" data-slot="icon">
+  <path stroke-linecap="round" stroke-linejoin="round" d="M21 12a9 9 0 1 1-18 0 9 9 0 0 1 18 0Z"/>
+  <path d="M12 3a9 9 0 0 1 0 18Z" fill="currentColor" stroke="none"/>
+</svg>
-- 
2.51.2