@usefragments/ui 1.5.4 → 1.7.0

package/src/components/Theme/index.tsx

@@ -1,19 +1,17 @@
 "use client";
 
 import * as React from "react";
-import {
-  ComponentDefaultsProvider,
-  useResolvedControlSize,
-  type ComponentDefaults,
-} from "../ComponentDefaults";
-import styles from "./ThemeToggle.module.scss";
+import { ComponentDefaultsProvider, type ComponentDefaults } from "../ComponentDefaults";
+import { ThemeToggle } from "../ThemeToggle";
+import { ThemeContext, useTheme, type ThemeContextValue, type ThemeMode } from "./context";
+
+export type { ThemeToggleProps } from "../ThemeToggle";
+export type { ThemeMode, UseThemeReturn } from "./context";
 
 // ============================================
 // Types
 // ============================================
 
-export type ThemeMode = "light" | "dark" | "system";
-
 export interface ThemeProviderProps {
   children: React.ReactNode;
   /** Default primitive component behavior for the subtree. */
@@ -34,46 +32,6 @@ export interface ThemeProviderProps {
   attribute?: "data-theme" | "class";
 }
 
-export interface UseThemeReturn {
-  /** Current theme mode setting */
-  mode: ThemeMode;
-  /** Set the theme mode */
-  setMode: (mode: ThemeMode) => void;
-  /** Resolved mode (never 'system', always 'light' or 'dark') */
-  resolvedMode: "light" | "dark";
-  /** System preference detected from prefers-color-scheme */
-  systemPreference: "light" | "dark";
-  /** Toggle between light and dark (skips system) */
-  toggleMode: () => void;
-}
-
-export interface ThemeToggleProps extends React.HTMLAttributes<HTMLDivElement> {
-  /** Size of the toggle button */
-  size?: "sm" | "md" | "lg";
-  /** Whether to include system mode option (default: false) */
-  showSystem?: boolean;
-  /** Controlled value for custom usage (bypasses theme context) */
-  value?: "light" | "dark";
-  /** Callback when value changes (for controlled usage) */
-  onValueChange?: (value: "light" | "dark") => void;
-  /** Accessible label for the group */
-  "aria-label"?: string;
-}
-
-// ============================================
-// Context
-// ============================================
-
-interface ThemeContextValue {
-  mode: ThemeMode;
-  setMode: (mode: ThemeMode) => void;
-  resolvedMode: "light" | "dark";
-  systemPreference: "light" | "dark";
-  toggleMode: () => void;
-}
-
-const ThemeContext = React.createContext<ThemeContextValue | null>(null);
-
 // ============================================
 // Hooks
 // ============================================
@@ -102,75 +60,6 @@ function useSystemPreference(): "light" | "dark" {
   return preference;
 }
 
-/**
- * Hook to access theme context
- */
-function useTheme(): UseThemeReturn {
-  const context = React.useContext(ThemeContext);
-
-  if (!context) {
-    // Return safe defaults when used outside provider
-    return {
-      mode: "system",
-      setMode: () => {},
-      resolvedMode: "light",
-      systemPreference: "light",
-      toggleMode: () => {},
-    };
-  }
-
-  return context;
-}
-
-// ============================================
-// Icons
-// ============================================
-
-function SunIcon({ size = 20 }: { size?: number }) {
-  return (
-    <svg
-      xmlns="http://www.w3.org/2000/svg"
-      width={size}
-      height={size}
-      viewBox="0 0 256 256"
-      fill="currentColor"
-      aria-hidden="true"
-    >
-      <path d="M120,40V16a8,8,0,0,1,16,0V40a8,8,0,0,1-16,0Zm72,88a64,64,0,1,1-64-64A64.07,64.07,0,0,1,192,128Zm-16,0a48,48,0,1,0-48,48A48.05,48.05,0,0,0,176,128ZM58.34,69.66A8,8,0,0,0,69.66,58.34l-16-16A8,8,0,0,0,42.34,53.66Zm0,116.68-16,16a8,8,0,0,0,11.32,11.32l16-16a8,8,0,0,0-11.32-11.32ZM192,72a8,8,0,0,0,5.66-2.34l16-16a8,8,0,0,0-11.32-11.32l-16,16A8,8,0,0,0,192,72Zm5.66,114.34a8,8,0,0,0-11.32,11.32l16,16a8,8,0,0,0,11.32-11.32ZM48,128a8,8,0,0,0-8-8H16a8,8,0,0,0,0,16H40A8,8,0,0,0,48,128Zm80,80a8,8,0,0,0-8,8v24a8,8,0,0,0,16,0V216A8,8,0,0,0,128,208Zm112-88H216a8,8,0,0,0,0,16h24a8,8,0,0,0,0-16Z" />
-    </svg>
-  );
-}
-
-function MoonIcon({ size = 20 }: { size?: number }) {
-  return (
-    <svg
-      xmlns="http://www.w3.org/2000/svg"
-      width={size}
-      height={size}
-      viewBox="0 0 256 256"
-      fill="currentColor"
-      aria-hidden="true"
-    >
-      <path d="M233.54,142.23a8,8,0,0,0-8-2,88.08,88.08,0,0,1-109.8-109.8,8,8,0,0,0-10-10,104.84,104.84,0,0,0-52.91,37A104,104,0,0,0,136,224a103.09,103.09,0,0,0,62.52-20.88,104.84,104.84,0,0,0,37-52.91A8,8,0,0,0,233.54,142.23ZM188.9,190.34A88,88,0,0,1,65.66,67.11a89,89,0,0,1,31.4-26A106,106,0,0,0,96,56,104.11,104.11,0,0,0,200,160a106,106,0,0,0,14.92-1.06A89,89,0,0,1,188.9,190.34Z" />
-    </svg>
-  );
-}
-
-function MonitorIcon({ size = 20 }: { size?: number }) {
-  return (
-    <svg
-      xmlns="http://www.w3.org/2000/svg"
-      width={size}
-      height={size}
-      viewBox="0 0 256 256"
-      fill="currentColor"
-      aria-hidden="true"
-    >
-      <path d="M208,40H48A24,24,0,0,0,24,64V176a24,24,0,0,0,24,24H208a24,24,0,0,0,24-24V64A24,24,0,0,0,208,40Zm8,136a8,8,0,0,1-8,8H48a8,8,0,0,1-8-8V64a8,8,0,0,1,8-8H208a8,8,0,0,1,8,8Zm-48,48a8,8,0,0,1-8,8H96a8,8,0,0,1,0-16h64A8,8,0,0,1,168,224Z" />
-    </svg>
-  );
-}
-
 // ============================================
 // Components
 // ============================================
@@ -192,7 +81,7 @@ function ThemeProvider({
   const systemPreference = useSystemPreference();
 
   // Warn on deprecated prop usage (dev only)
-  if (process.env.NODE_ENV !== "production" && defaultTheme !== undefined) {
+  if (!isProductionBuild() && defaultTheme !== undefined) {
     console.warn(
       "[Fragments] ThemeProvider: `defaultTheme` is deprecated. Use `defaultMode` instead. " +
         "`defaultTheme` will be removed in v1.0."
@@ -285,88 +174,6 @@ function ThemeProvider({
   );
 }
 
-/**
- * ThemeToggle - Fragmented button group to toggle between light and dark themes
- *
- * Can be used in two modes:
- * 1. Uncontrolled (default): Uses ThemeProvider context to get/set theme
- * 2. Controlled: Pass `value` and `onValueChange` props for custom behavior
- */
-function ThemeToggle({
-  size: sizeProp,
-  showSystem = false,
-  value: controlledValue,
-  onValueChange,
-  "aria-label": ariaLabel,
-  className,
-  ...htmlProps
-}: ThemeToggleProps) {
-  const size = useResolvedControlSize(sizeProp);
-  const { mode: contextMode, setMode: setContextMode } = useTheme();
-
-  // Use controlled value if provided, otherwise use context
-  const isControlled = controlledValue !== undefined;
-  const currentMode = isControlled ? controlledValue : contextMode;
-
-  const handleModeChange = (newMode: "light" | "dark") => {
-    if (isControlled) {
-      onValueChange?.(newMode);
-    } else {
-      setContextMode(newMode);
-    }
-  };
-
-  const groupClasses = [
-    styles.toggleGroup,
-    styles[`size${size.charAt(0).toUpperCase() + size.slice(1)}`],
-    className,
-  ]
-    .filter(Boolean)
-    .join(" ");
-
-  const getButtonClasses = (buttonMode: ThemeMode) => {
-    return [styles.toggleButton, currentMode === buttonMode && styles.toggleButtonActive]
-      .filter(Boolean)
-      .join(" ");
-  };
-
-  const label = ariaLabel || "Theme toggle";
-
-  return (
-    <div {...htmlProps} className={groupClasses} role="group" aria-label={label}>
-      <button
-        type="button"
-        className={getButtonClasses("light")}
-        onClick={() => handleModeChange("light")}
-        aria-pressed={currentMode === "light"}
-        aria-label="Light mode"
-      >
-        <SunIcon />
-      </button>
-      <button
-        type="button"
-        className={getButtonClasses("dark")}
-        onClick={() => handleModeChange("dark")}
-        aria-pressed={currentMode === "dark"}
-        aria-label="Dark mode"
-      >
-        <MoonIcon />
-      </button>
-      {showSystem && !isControlled && (
-        <button
-          type="button"
-          className={getButtonClasses("system")}
-          onClick={() => setContextMode("system")}
-          aria-pressed={contextMode === "system"}
-          aria-label="System preference"
-        >
-          <MonitorIcon />
-        </button>
-      )}
-    </div>
-  );
-}
-
 // ============================================
 // Exports
 // ============================================
@@ -386,6 +193,8 @@ export { ThemeProvider, ThemeToggle, useTheme };
 
 // Import + re-export seed derivation types — canonical definitions in utils/seed-derivation.ts
 import type { NeutralPalette, DensityPreset, RadiusStyle } from "../../utils/seed-derivation";
+import { applyMeasurementSelection } from "../../measurements";
+import { isProductionBuild } from "../../utils/env";
 export type { NeutralPalette, DensityPreset, RadiusStyle };
 
 export interface ConfigureThemeOptions {
@@ -407,62 +216,6 @@ export interface ConfigureThemeOptions {
   info?: string;
 }
 
-// -- Radius presets (match _radius.scss) --
-
-const RADIUS_PRESETS: Record<RadiusStyle, Record<string, string>> = {
-  sharp: { sm: "0", md: "0", lg: "0", xl: "0" },
-  subtle: { sm: "0.125rem", md: "0.25rem", lg: "0.375rem", xl: "0.5rem" },
-  default: { sm: "0.25rem", md: "0.429rem", lg: "0.571rem", xl: "0.857rem" },
-  rounded: { sm: "0.375rem", md: "0.5rem", lg: "0.75rem", xl: "1rem" },
-  pill: { sm: "0.5rem", md: "0.75rem", lg: "1rem", xl: "1.5rem" },
-};
-
-// -- Density presets (match _density.scss) --
-
-interface DensityConfig {
-  baseUnit: number;
-  baseFontSize: number;
-  buttonHeightXs: number;
-  buttonHeights: [number, number, number]; // sm, md, lg
-  inputHeights: [number, number, number]; // sm, default, lg
-  touchTargets: [number, number, number]; // sm, md, lg — Fragments floor: ≥32px
-  sidebarItemHeight: number;
-}
-
-const DENSITY_CONFIGS: Record<DensityPreset, DensityConfig> = {
-  compact: {
-    baseUnit: 6,
-    baseFontSize: 14,
-    buttonHeightXs: 32,
-    buttonHeights: [32, 32, 36],
-    inputHeights: [32, 32, 36],
-    touchTargets: [32, 32, 40],
-    sidebarItemHeight: 32,
-  },
-  default: {
-    baseUnit: 7,
-    baseFontSize: 14,
-    buttonHeightXs: 32,
-    buttonHeights: [32, 40, 44],
-    inputHeights: [32, 40, 44],
-    touchTargets: [32, 32, 44],
-    sidebarItemHeight: 32,
-  },
-  relaxed: {
-    baseUnit: 8,
-    baseFontSize: 14,
-    buttonHeightXs: 32,
-    buttonHeights: [32, 44, 48],
-    inputHeights: [32, 44, 48],
-    touchTargets: [32, 40, 48],
-    sidebarItemHeight: 36,
-  },
-};
-
-function pxToRem(px: number, baseFontSize: number): string {
-  return `${px / baseFontSize}rem`;
-}
-
 function hexToRgb(hex: string): [number, number, number] | null {
   const result = /^#?([a-f\d]{2})([a-f\d]{2})([a-f\d]{2})$/i.exec(hex);
   if (!result) return null;
@@ -522,58 +275,11 @@ export function configureTheme(options: ConfigureThemeOptions): void {
   if (options.warning) setVar(root, "--fui-color-warning", options.warning);
   if (options.info) setVar(root, "--fui-color-info", options.info);
 
-  // -- Radius --
-  if (options.radiusStyle) {
-    const r = RADIUS_PRESETS[options.radiusStyle];
-    if (r) {
-      setVar(root, "--fui-radius-sm", r.sm);
-      setVar(root, "--fui-radius-md", r.md);
-      setVar(root, "--fui-radius-lg", r.lg);
-      setVar(root, "--fui-radius-xl", r.xl);
-    }
-  }
-
-  // -- Density --
-  if (options.density) {
-    const d = DENSITY_CONFIGS[options.density];
-    if (d) {
-      const unitRem = d.baseUnit / d.baseFontSize;
-
-      // Micro spacing
-      setVar(root, "--fui-space-0-5", `${unitRem * 0.3}rem`);
-      setVar(root, "--fui-space-0-75", `${unitRem * 0.43}rem`);
-
-      // Spacing scale
-      setVar(root, "--fui-space-1", `${unitRem}rem`);
-      setVar(root, "--fui-space-2", `${unitRem * 2}rem`);
-      setVar(root, "--fui-space-3", `${unitRem * 3}rem`);
-      setVar(root, "--fui-space-4", `${unitRem * 4}rem`);
-      setVar(root, "--fui-space-5", `${unitRem * 5}rem`);
-      setVar(root, "--fui-space-6", `${unitRem * 6}rem`);
-      setVar(root, "--fui-space-8", `${unitRem * 8}rem`);
-      setVar(root, "--fui-space-10", `${unitRem * 10}rem`);
-      setVar(root, "--fui-space-12", `${unitRem * 12}rem`);
-
-      // Component heights
-      setVar(root, "--fui-button-height-xs", pxToRem(d.buttonHeightXs, d.baseFontSize));
-      setVar(root, "--fui-button-height-sm", pxToRem(d.buttonHeights[0], d.baseFontSize));
-      setVar(root, "--fui-button-height-md", pxToRem(d.buttonHeights[1], d.baseFontSize));
-      setVar(root, "--fui-button-height-lg", pxToRem(d.buttonHeights[2], d.baseFontSize));
-      setVar(root, "--fui-input-height-sm", pxToRem(d.inputHeights[0], d.baseFontSize));
-      setVar(root, "--fui-input-height", pxToRem(d.inputHeights[1], d.baseFontSize));
-      setVar(root, "--fui-input-height-lg", pxToRem(d.inputHeights[2], d.baseFontSize));
-
-      // Touch targets (Fragments control floor: all values ≥32px)
-      setVar(root, "--fui-touch-sm", pxToRem(d.touchTargets[0], d.baseFontSize));
-      setVar(root, "--fui-touch-md", pxToRem(d.touchTargets[1], d.baseFontSize));
-      setVar(root, "--fui-touch-lg", pxToRem(d.touchTargets[2], d.baseFontSize));
-      setVar(root, "--fui-target-size-min", pxToRem(32, d.baseFontSize));
-
-      // Sidebar navigation
-      setVar(root, "--fui-sidebar-item-height", pxToRem(d.sidebarItemHeight, d.baseFontSize));
-
-      // Base unit
-      setVar(root, "--fui-base-unit", `${d.baseUnit}px`);
-    }
-  }
+  // Named geometry is selected through the generated Measurement Module.
+  // Partial calls leave the omitted selector untouched and never write numeric
+  // CSS maps inline.
+  applyMeasurementSelection(root, {
+    density: options.density,
+    radiusStyle: options.radiusStyle,
+  });
 }

package/src/components/ThemeToggle/ThemeToggle.module.scss

@@ -0,0 +1,89 @@
+@use "../../tokens/variables" as *;
+@use "../../tokens/mixins" as *;
+@use "../../recipes/action";
+
+// ============================================
+// Theme Toggle - Fragmented Button Group
+// ============================================
+
+.toggleGroup {
+  display: inline-flex;
+  align-items: stretch;
+  gap: 0;
+  padding: 0;
+  background-color: var(--fui-theme-toggle-bg, var(--fui-bg-tertiary, #{$fui-bg-tertiary}));
+  border-radius: var(--fui-radius-md, $fui-radius-md);
+}
+
+.toggleButton {
+  @include button-reset;
+  @include interactive-base;
+  @include action.base;
+
+  border-radius: var(--fui-radius-sm, $fui-radius-sm);
+  color: var(--fui-text-secondary, $fui-text-secondary);
+  background-color: transparent;
+
+  &:hover:not(.toggleButtonActive) {
+    color: var(--fui-text-primary, $fui-text-primary);
+  }
+
+  // Keyboard focus ring is supplied by @include interactive-base.
+
+  svg {
+    flex-shrink: 0;
+  }
+}
+
+.toggleButtonActive {
+  background-color: var(
+    --fui-theme-toggle-active-bg,
+    var(--fui-control-selected-bg, #{$fui-bg-active})
+  );
+  color: var(--fui-text-primary, $fui-text-primary);
+  box-shadow: var(--fui-theme-toggle-active-shadow, none);
+}
+
+.iconButton {
+  background-color: transparent;
+  color: var(--fui-text-secondary, $fui-text-secondary);
+
+  &:hover {
+    color: var(--fui-text-primary, $fui-text-primary);
+    background-color: var(--fui-bg-hover, $fui-bg-hover);
+  }
+}
+
+// Size variants — nested for the group, same-element for appearance="icon"
+.sizeSm {
+  .toggleButton,
+  &.toggleButton {
+    @include action.icon-only("sm");
+
+    svg {
+      @include action.glyph("sm");
+    }
+  }
+}
+
+.sizeMd {
+  .toggleButton,
+  &.toggleButton {
+    @include action.icon-only("md");
+
+    svg {
+      @include action.glyph("md");
+    }
+  }
+}
+
+.sizeLg {
+  .toggleButton,
+  &.toggleButton {
+    @include action.icon-only("lg");
+
+    svg {
+      @include action.glyph("lg");
+    }
+  }
+}

package/src/components/ThemeToggle/index.tsx

@@ -0,0 +1,180 @@
+"use client";
+
+import * as React from "react";
+import { useResolvedControlSize } from "../ComponentDefaults";
+import { useTheme, type ThemeMode } from "../Theme/context";
+import styles from "./ThemeToggle.module.scss";
+
+export interface ThemeToggleProps extends React.HTMLAttributes<HTMLElement> {
+  /** Size of the toggle button */
+  size?: "sm" | "md" | "lg";
+  /**
+   * `group` is the segmented light/dark control. `icon` is a single button
+   * that shows the current resolved theme and toggles light ↔ dark.
+   */
+  appearance?: "group" | "icon";
+  /** Whether to include system mode option (default: false) */
+  showSystem?: boolean;
+  /** Controlled value for custom usage (bypasses theme context) */
+  value?: "light" | "dark";
+  /** Callback when value changes (for controlled usage) */
+  onValueChange?: (value: "light" | "dark") => void;
+  /** Accessible label for the group */
+  "aria-label"?: string;
+}
+
+function SunIcon({ size = 20 }: { size?: number }) {
+  return (
+    <svg
+      xmlns="http://www.w3.org/2000/svg"
+      width={size}
+      height={size}
+      viewBox="0 0 256 256"
+      fill="currentColor"
+      aria-hidden="true"
+    >
+      <path d="M120,40V16a8,8,0,0,1,16,0V40a8,8,0,0,1-16,0Zm72,88a64,64,0,1,1-64-64A64.07,64.07,0,0,1,192,128Zm-16,0a48,48,0,1,0-48,48A48.05,48.05,0,0,0,176,128ZM58.34,69.66A8,8,0,0,0,69.66,58.34l-16-16A8,8,0,0,0,42.34,53.66Zm0,116.68-16,16a8,8,0,0,0,11.32,11.32l16-16a8,8,0,0,0-11.32-11.32ZM192,72a8,8,0,0,0,5.66-2.34l16-16a8,8,0,0,0-11.32-11.32l-16,16A8,8,0,0,0,192,72Zm5.66,114.34a8,8,0,0,0-11.32,11.32l16,16a8,8,0,0,0,11.32-11.32ZM48,128a8,8,0,0,0-8-8H16a8,8,0,0,0,0,16H40A8,8,0,0,0,48,128Zm80,80a8,8,0,0,0-8,8v24a8,8,0,0,0,16,0V216A8,8,0,0,0,128,208Zm112-88H216a8,8,0,0,0,0,16h24a8,8,0,0,0,0-16Z" />
+    </svg>
+  );
+}
+
+function MoonIcon({ size = 20 }: { size?: number }) {
+  return (
+    <svg
+      xmlns="http://www.w3.org/2000/svg"
+      width={size}
+      height={size}
+      viewBox="0 0 256 256"
+      fill="currentColor"
+      aria-hidden="true"
+    >
+      <path d="M233.54,142.23a8,8,0,0,0-8-2,88.08,88.08,0,0,1-109.8-109.8,8,8,0,0,0-10-10,104.84,104.84,0,0,0-52.91,37A104,104,0,0,0,136,224a103.09,103.09,0,0,0,62.52-20.88,104.84,104.84,0,0,0,37-52.91A8,8,0,0,0,233.54,142.23ZM188.9,190.34A88,88,0,0,1,65.66,67.11a89,89,0,0,1,31.4-26A106,106,0,0,0,96,56,104.11,104.11,0,0,0,200,160a106,106,0,0,0,14.92-1.06A89,89,0,0,1,188.9,190.34Z" />
+    </svg>
+  );
+}
+
+function MonitorIcon({ size = 20 }: { size?: number }) {
+  return (
+    <svg
+      xmlns="http://www.w3.org/2000/svg"
+      width={size}
+      height={size}
+      viewBox="0 0 256 256"
+      fill="currentColor"
+      aria-hidden="true"
+    >
+      <path d="M208,40H48A24,24,0,0,0,24,64V176a24,24,0,0,0,24,24H208a24,24,0,0,0,24-24V64A24,24,0,0,0,208,40Zm8,136a8,8,0,0,1-8,8H48a8,8,0,0,1-8-8V64a8,8,0,0,1,8-8H208a8,8,0,0,1,8,8Zm-48,48a8,8,0,0,1-8,8H96a8,8,0,0,1,0-16h64A8,8,0,0,1,168,224Z" />
+    </svg>
+  );
+}
+
+/**
+ * Fragmented button group for choosing light, dark, or system theme modes.
+ *
+ * It can read and update ThemeProvider context, or operate as a controlled
+ * light/dark selector through `value` and `onValueChange`.
+ */
+export function ThemeToggle({
+  size: sizeProp,
+  appearance = "group",
+  showSystem = false,
+  value: controlledValue,
+  onValueChange,
+  "aria-label": ariaLabel,
+  className,
+  ...htmlProps
+}: ThemeToggleProps) {
+  const size = useResolvedControlSize(sizeProp);
+  const {
+    mode: contextMode,
+    setMode: setContextMode,
+    resolvedMode,
+    toggleMode,
+  } = useTheme();
+
+  const isControlled = controlledValue !== undefined;
+  const currentMode = isControlled ? controlledValue : contextMode;
+  const sizeClass = styles[`size${size.charAt(0).toUpperCase() + size.slice(1)}`];
+
+  if (appearance === "icon") {
+    const resolved = isControlled ? controlledValue : resolvedMode;
+    const nextMode = resolved === "dark" ? "light" : "dark";
+    const iconClasses = [styles.toggleButton, styles.iconButton, sizeClass, className]
+      .filter(Boolean)
+      .join(" ");
+
+    return (
+      <button
+        {...(htmlProps as React.ButtonHTMLAttributes<HTMLButtonElement>)}
+        type="button"
+        className={iconClasses}
+        onClick={() => {
+          if (isControlled) {
+            onValueChange?.(nextMode);
+          } else {
+            toggleMode();
+          }
+        }}
+        aria-label={
+          ariaLabel ?? (resolved === "dark" ? "Switch to light mode" : "Switch to dark mode")
+        }
+      >
+        {resolved === "dark" ? <MoonIcon /> : <SunIcon />}
+      </button>
+    );
+  }
+
+  const handleModeChange = (newMode: "light" | "dark") => {
+    if (isControlled) {
+      onValueChange?.(newMode);
+    } else {
+      setContextMode(newMode);
+    }
+  };
+
+  const groupClasses = [styles.toggleGroup, sizeClass, className]
+    .filter(Boolean)
+    .join(" ");
+
+  const getButtonClasses = (buttonMode: ThemeMode) => {
+    return [styles.toggleButton, currentMode === buttonMode && styles.toggleButtonActive]
+      .filter(Boolean)
+      .join(" ");
+  };
+
+  const label = ariaLabel || "Theme toggle";
+
+  return (
+    <div {...htmlProps} className={groupClasses} role="group" aria-label={label}>
+      <button
+        type="button"
+        className={getButtonClasses("light")}
+        onClick={() => handleModeChange("light")}
+        aria-pressed={currentMode === "light"}
+        aria-label="Light mode"
+      >
+        <SunIcon />
+      </button>
+      <button
+        type="button"
+        className={getButtonClasses("dark")}
+        onClick={() => handleModeChange("dark")}
+        aria-pressed={currentMode === "dark"}
+        aria-label="Dark mode"
+      >
+        <MoonIcon />
+      </button>
+      {showSystem && !isControlled && (
+        <button
+          type="button"
+          className={getButtonClasses("system")}
+          onClick={() => setContextMode("system")}
+          aria-pressed={contextMode === "system"}
+          aria-label="System preference"
+        >
+          <MonitorIcon />
+        </button>
+      )}
+    </div>
+  );
+}