@fragments-sdk/ui 0.12.0 → 0.14.0

package/src/components/Toggle/Toggle.module.scss

@@ -4,13 +4,14 @@
 .root {
   display: flex;
   align-items: center;
-  gap: var(--fui-space-3, $fui-space-3);
+  gap: var(--fui-space-2, $fui-space-2);
   cursor: pointer;
   font-family: var(--fui-font-sans, $fui-font-sans);
+  -webkit-tap-highlight-color: transparent;
 
   &[data-disabled] {
     cursor: not-allowed;
-    opacity: 0.5;
+    opacity: 0.38;
   }
 }
 
@@ -22,64 +23,103 @@
   }
 }
 
+// iOS-style track: solid fill, clean pill shape
 .track {
-  @include button-reset;
-  @include interactive-base;
-  @include min-target-size;
-
   position: relative;
+  display: inline-flex;
+  align-items: center;
   flex-shrink: 0;
+  box-sizing: content-box;
   border-radius: var(--fui-radius-full, $fui-radius-full);
-  background-color: var(--fui-border-strong, $fui-border-strong);
-  transition: background-color var(--fui-transition-normal, $fui-transition-normal);
+  border: none;
+  // iOS unchecked: semi-transparent gray — visible in both light and dark
+  background-color: var(--fui-bg-active, $fui-bg-active);
+  overflow: hidden;
+  transition: background-color 250ms cubic-bezier(0.4, 0.0, 0.2, 1);
 
+  // Checked: accent fill
   .root[data-checked] & {
     background-color: var(--fui-color-accent, $fui-color-accent);
   }
 
-  .root:not([data-disabled]) &:hover {
-    opacity: 0.9;
+  // Hover (unchecked): slightly more opaque
+  .root:not([data-disabled]):not([data-checked]) &:hover {
+    background-color: var(--fui-border, $fui-border);
+  }
+
+  // Hover (checked): accent hover
+  .root:not([data-disabled])[data-checked] &:hover {
+    background-color: var(--fui-color-accent-hover, $fui-color-accent-hover);
+  }
+
+  // Focus ring
+  .root:focus-visible & {
+    outline: var(--fui-focus-ring-width, $fui-focus-ring-width) solid
+      var(--fui-focus-ring-color, $fui-focus-ring-color);
+    outline-offset: var(--fui-focus-ring-offset, $fui-focus-ring-offset);
   }
 }
 
+// Sm: 40×24
 .trackSm {
   width: var(--fui-toggle-width-sm, $fui-toggle-width-sm);
   height: var(--fui-toggle-height-sm, $fui-toggle-height-sm);
-  --_toggle-thumb-size: calc(var(--fui-toggle-height-sm, #{$fui-toggle-height-sm}) - 0.5rem);
-  --_toggle-inset: calc((var(--fui-toggle-height-sm, #{$fui-toggle-height-sm}) - var(--_toggle-thumb-size)) / 2);
+  --_toggle-thumb-size: calc(var(--fui-toggle-height-sm, #{$fui-toggle-height-sm}) - 4px);
+  --_toggle-inset: 2px;
   --_toggle-translate: calc(
     var(--fui-toggle-width-sm, #{$fui-toggle-width-sm}) -
     var(--_toggle-thumb-size) -
-    (var(--_toggle-inset) * 2)
+    4px
   );
 }
 
+// Md: 51×31 (iOS standard)
 .trackMd {
   width: var(--fui-toggle-width-md, $fui-toggle-width-md);
   height: var(--fui-toggle-height-md, $fui-toggle-height-md);
-  --_toggle-thumb-size: calc(var(--fui-toggle-height-md, #{$fui-toggle-height-md}) - 0.5rem);
-  --_toggle-inset: calc((var(--fui-toggle-height-md, #{$fui-toggle-height-md}) - var(--_toggle-thumb-size)) / 2);
+  --_toggle-thumb-size: calc(var(--fui-toggle-height-md, #{$fui-toggle-height-md}) - 4px);
+  --_toggle-inset: 2px;
   --_toggle-translate: calc(
     var(--fui-toggle-width-md, #{$fui-toggle-width-md}) -
     var(--_toggle-thumb-size) -
-    (var(--_toggle-inset) * 2)
+    4px
   );
 }
 
+// iOS-style thumb: always white, multi-layer shadow
 .thumb {
   position: absolute;
   top: var(--_toggle-inset, $fui-toggle-thumb-offset);
   left: var(--_toggle-inset, $fui-toggle-thumb-offset);
+  box-sizing: border-box;
   width: var(--_toggle-thumb-size, $fui-toggle-thumb-md);
   height: var(--_toggle-thumb-size, $fui-toggle-thumb-md);
   border-radius: 50%;
-  background-color: var(--fui-bg-primary, $fui-bg-primary);
-  box-shadow: var(--fui-shadow-sm, $fui-shadow-sm);
-  transition: transform var(--fui-transition-normal, $fui-transition-normal);
-
+  pointer-events: none;
+  background-color: #fff;
+  box-shadow:
+    0 3px 8px rgba(0, 0, 0, 0.15),
+    0 1px 1px rgba(0, 0, 0, 0.06),
+    0 3px 1px rgba(0, 0, 0, 0.06);
+  transition:
+    transform 250ms cubic-bezier(0.4, 0.0, 0.2, 1),
+    background-color 250ms cubic-bezier(0.4, 0.0, 0.2, 1),
+    width 120ms cubic-bezier(0.4, 0.0, 0.2, 1);
+
+  // Slide right when checked — inverse color for contrast against accent
   .root[data-checked] & {
-    // Move thumb to the right when checked
     transform: translateX(var(--_toggle-translate, 0));
+    background-color: var(--fui-text-inverse, $fui-text-inverse);
+  }
+
+  // Press: stretch thumb wider (iOS 17+)
+  .root:active:not([data-disabled]) & {
+    width: calc(var(--_toggle-thumb-size, #{$fui-toggle-thumb-md}) + 4px);
+  }
+
+  // Press + checked: compensate translate for wider thumb
+  .root:active:not([data-disabled])[data-checked] & {
+    transform: translateX(calc(var(--_toggle-translate, 0) - 4px));
   }
 }
 

package/src/components/Toggle/index.tsx

@@ -91,9 +91,9 @@ const SwitchRoot = React.forwardRef<HTMLButtonElement, SwitchProps>(
         aria-labelledby={ariaLabelledBy}
         aria-describedby={ariaDescribedBy}
       >
-        <BaseSwitch.Thumb className={trackClasses}>
-          <span className={thumbClasses} aria-hidden="true" />
-        </BaseSwitch.Thumb>
+        <span className={trackClasses} aria-hidden="true">
+          <BaseSwitch.Thumb className={thumbClasses} />
+        </span>
 
         {(label || description) && (
           <div className={styles.content}>

package/src/components/ToggleGroup/ToggleGroup.fragment.tsx

@@ -1,5 +1,5 @@
 import React from "react";
-import { defineFragment } from "@fragments-sdk/cli/core";
+import { defineFragment } from "@fragments-sdk/core";
 import { ToggleGroup } from ".";
 
 function DefaultExample() {
@@ -30,7 +30,7 @@ function OutlineExample() {
   const [value, setValue] = React.useState("day");
 
   return (
-    <ToggleGroup value={value} onChange={setValue} variant="outline">
+    <ToggleGroup value={value} onChange={setValue} variant="outlined">
       <ToggleGroup.Item value="day">Day</ToggleGroup.Item>
       <ToggleGroup.Item value="week">Week</ToggleGroup.Item>
       <ToggleGroup.Item value="month">Month</ToggleGroup.Item>
@@ -141,7 +141,7 @@ export default defineFragment({
       "Ensure adequate touch targets on mobile",
     ],
     accessibility: [
-      'Uses role="group" for semantic grouping',
+      'Uses role="radiogroup" for single-selection semantics',
       'Each item has role="radio" with aria-checked',
       "Keyboard navigable with Tab and arrow keys",
       "Focus visible on active item",
@@ -152,7 +152,10 @@ export default defineFragment({
     value: {
       type: "string",
       description: "Currently selected value",
-      required: true,
+    },
+    defaultValue: {
+      type: "string",
+      description: "Initial selected value (uncontrolled)",
     },
     onChange: {
       type: "function",
@@ -170,7 +173,7 @@ export default defineFragment({
     variant: {
       type: "enum",
       description: "Visual style",
-      values: ["default", "pills", "outline"],
+      values: ["default", "pills", "outline", "outlined"],
       default: "default",
     },
     size: {
@@ -185,6 +188,12 @@ export default defineFragment({
       values: ["none", "xs", "sm"],
       default: "xs",
     },
+    selectionMode: {
+      type: "enum",
+      description: "Selection behavior",
+      values: ["single"],
+      default: "single",
+    },
   },
 
   relations: [
@@ -199,12 +208,14 @@ export default defineFragment({
 
   contract: {
     propsSummary: [
-      "value: string - selected value (required)",
+      "value?: string - controlled selected value",
+      "defaultValue?: string - initial selected value (uncontrolled)",
       "onChange: (value: string) => void - change handler (or onValueChange)",
       "children: ToggleGroup.Item[] - toggle items",
-      "variant: default|pills|outline - visual style",
+      "variant: default|pills|outline|outlined - visual style (outlined aliases outline)",
       "size: sm|md - size variant",
       "gap: none|xs|sm - spacing",
+      "selectionMode: single (default: single)",
     ],
     scenarioTags: ["forms.selection", "input.toggle", "control.fragmented"],
     a11yRules: ["A11Y_GROUP_ROLE", "A11Y_KEYBOARD_ACCESSIBLE"],
@@ -234,13 +245,27 @@ export default defineFragment({
     {
       name: "Outline Variant",
       description: "Outlined toggle buttons",
-      code: `<ToggleGroup value={value} onChange={setValue} variant="outline">
+      code: `<ToggleGroup value={value} onChange={setValue} variant="outlined">
   <ToggleGroup.Item value="day">Day</ToggleGroup.Item>
   <ToggleGroup.Item value="week">Week</ToggleGroup.Item>
   <ToggleGroup.Item value="month">Month</ToggleGroup.Item>
 </ToggleGroup>`,
       render: () => <OutlineExample />,
     },
+    {
+      name: "Uncontrolled",
+      description: "Use defaultValue for simple single-select state",
+      code: `<ToggleGroup defaultValue="list">
+  <ToggleGroup.Item value="grid">Grid</ToggleGroup.Item>
+  <ToggleGroup.Item value="list">List</ToggleGroup.Item>
+</ToggleGroup>`,
+      render: () => (
+        <ToggleGroup defaultValue="list">
+          <ToggleGroup.Item value="grid">Grid</ToggleGroup.Item>
+          <ToggleGroup.Item value="list">List</ToggleGroup.Item>
+        </ToggleGroup>
+      ),
+    },
     {
       name: "Sizes",
       description: "Different size variants",

package/src/components/ToggleGroup/ToggleGroup.module.scss

@@ -12,7 +12,7 @@
 
 // Gap variants
 .gap-xs {
-  gap: 2px;
+  gap: calc(var(--fui-space-px, $fui-space-px) * 2);
 }
 
 .gap-sm {
@@ -26,8 +26,8 @@
 .default {
   background-color: var(--fui-bg-secondary, $fui-bg-secondary);
   border-radius: var(--fui-radius-md, $fui-radius-md);
-  padding: 2px;
-  gap: 2px;
+  padding: calc(var(--fui-space-px, $fui-space-px) * 2);
+  gap: calc(var(--fui-space-px, $fui-space-px) * 2);
 
   .item {
     background-color: transparent;

package/src/components/ToggleGroup/index.tsx

@@ -13,7 +13,9 @@ import styles from './ToggleGroup.module.scss';
  */
 export interface ToggleGroupProps extends Omit<React.HTMLAttributes<HTMLDivElement>, 'onChange'> {
   /** Current selected value */
-  value: string;
+  value?: string;
+  /** Default selected value (uncontrolled) */
+  defaultValue?: string;
   /** Callback when selection changes */
   onChange?: (value: string) => void;
   /** Alias for onChange (Radix convention) */
@@ -23,12 +25,15 @@ export interface ToggleGroupProps extends Omit<React.HTMLAttributes<HTMLDivEleme
   /** Visual variant.
    * @default "default"
    * @see https://usefragments.com/components/togglegroup#variants */
-  variant?: 'default' | 'pills' | 'outline';
+  variant?: 'default' | 'pills' | 'outline' | 'outlined';
   /** Size.
    * @default "md" */
   size?: 'sm' | 'md' | 'lg';
   /** Gap between items (for pills/outline variants) */
   gap?: 'none' | 'xs' | 'sm';
+  /** Selection mode for this control. Currently only single-select is supported.
+   * @default "single" */
+  selectionMode?: 'single';
 }
 
 export interface ToggleGroupItemProps extends Omit<React.HTMLAttributes<HTMLButtonElement>, 'onClick'> {
@@ -71,19 +76,30 @@ function useToggleGroupContext() {
 
 function ToggleGroupRoot({
   value,
+  defaultValue,
   onChange,
   onValueChange,
   children,
   variant = 'default',
   size = 'md',
   gap = 'xs',
+  selectionMode = 'single',
   className,
   ...htmlProps
 }: ToggleGroupProps) {
-  const resolvedOnChange = onChange ?? onValueChange ?? (() => {});
+  const normalizedVariant = variant === 'outlined' ? 'outline' : variant;
+  const [internalValue, setInternalValue] = React.useState(defaultValue ?? '');
+  const isControlled = value !== undefined;
+  const currentValue = isControlled ? value ?? '' : internalValue;
+  const emitChange = React.useCallback((nextValue: string) => {
+    if (!isControlled) {
+      setInternalValue(nextValue);
+    }
+    (onChange ?? onValueChange)?.(nextValue);
+  }, [isControlled, onChange, onValueChange]);
   const classes = [
     styles.group,
-    styles[variant],
+    styles[normalizedVariant],
     styles[`size-${size}`],
     gap !== 'none' && styles[`gap-${gap}`],
     className,
@@ -97,13 +113,13 @@ function ToggleGroupRoot({
   );
   const firstEnabledValue = childItems.find((item) => !item.props.disabled)?.props.value ?? null;
   const hasFocusableSelection = childItems.some(
-    (item) => !item.props.disabled && item.props.value === value
+    (item) => !item.props.disabled && item.props.value === currentValue
   );
 
   const contextValue: ToggleGroupContextValue = {
-    value,
-    onChange: resolvedOnChange,
-    variant,
+    value: currentValue,
+    onChange: emitChange,
+    variant: normalizedVariant,
     size,
     hasFocusableSelection,
     firstEnabledValue,
@@ -111,7 +127,11 @@ function ToggleGroupRoot({
 
   return (
     <ToggleGroupContext.Provider value={contextValue}>
-      <div {...htmlProps} role="radiogroup" className={classes}>
+      <div
+        {...htmlProps}
+        role={selectionMode === 'single' ? 'radiogroup' : 'radiogroup'}
+        className={classes}
+      >
         {children}
       </div>
     </ToggleGroupContext.Provider>

package/src/components/Tooltip/Tooltip.fragment.tsx

@@ -1,5 +1,5 @@
 import React from 'react';
-import { defineFragment } from '@fragments-sdk/cli/core';
+import { defineFragment } from '@fragments-sdk/core';
 import { Tooltip } from '.';
 import { Button } from '../Button';
 
@@ -33,6 +33,7 @@ export default defineFragment({
       'Use sentence case, no period for single sentences',
       'Avoid duplicating visible label text',
       'Consider mobile users who cannot hover',
+      'Use contentProps for tooltip popup attributes/styling; top-level HTML attrs are applied to the popup for backward compatibility',
     ],
     accessibility: [
       'Accessible via focus as well as hover',
@@ -102,6 +103,10 @@ export default defineFragment({
       type: 'function',
       description: 'Callback when open state changes',
     },
+    contentProps: {
+      type: 'object',
+      description: 'Props forwarded to the tooltip popup element (preferred way to pass popup attrs/className/style)',
+    },
   },
 
   relations: [
@@ -115,6 +120,7 @@ export default defineFragment({
       'side: top|bottom|left|right - position',
       'delay: number - show delay in ms (default: 400)',
       'arrow: boolean - show arrow (default: true)',
+      'contentProps: HTMLAttributes<HTMLDivElement> - popup element props',
     ],
     scenarioTags: [
       'help.tooltip',
@@ -172,5 +178,14 @@ export default defineFragment({
         </Tooltip>
       ),
     },
+    {
+      name: 'With Content Props',
+      description: 'Pass popup attributes/styling using contentProps',
+      render: () => (
+        <Tooltip content="Custom popup attrs" contentProps={{ id: 'custom-tooltip-popup' }}>
+          <Button variant="secondary">Hover me</Button>
+        </Tooltip>
+      ),
+    },
   ],
 });

package/src/components/Tooltip/Tooltip.module.scss

@@ -11,7 +11,7 @@
 .popup {
   @include text-base;
 
-  padding: var(--fui-padding-item-xs) var(--fui-padding-item-sm);
+  padding: var(--fui-space-1) var(--fui-space-2);
   font-size: var(--fui-font-size-xs, $fui-font-size-xs);
   line-height: var(--fui-line-height-tight, $fui-line-height-tight);
   // Tooltips use inverted colors - always dark bg with light text

package/src/components/Tooltip/Tooltip.test.tsx

@@ -91,6 +91,23 @@ describe('Tooltip', () => {
     });
   });
 
+  it('respects shared Tooltip.Provider delay settings', async () => {
+    const user = userEvent.setup({ advanceTimers: vi.advanceTimersByTime });
+    render(
+      <Tooltip.Provider delay={0}>
+        <Tooltip content="Provider tooltip">
+          <button>Provider Trigger</button>
+        </Tooltip>
+      </Tooltip.Provider>
+    );
+
+    await user.hover(screen.getByRole('button', { name: /provider trigger/i }));
+
+    await waitFor(() => {
+      expect(screen.getByText('Provider tooltip')).toBeInTheDocument();
+    });
+  });
+
   it('has no accessibility violations when open', async () => {
     const { container } = render(
       <Tooltip content="Accessible tooltip" open={true} delay={0}>

package/src/components/Tooltip/index.tsx

@@ -36,6 +36,8 @@ export interface TooltipProps extends Omit<React.HTMLAttributes<HTMLDivElement>,
   defaultOpen?: boolean;
   /** Callback when open state changes */
   onOpenChange?: (open: boolean) => void;
+  /** Explicit props for the tooltip popup element (preferred over top-level HTMLAttributes for clarity) */
+  contentProps?: React.HTMLAttributes<HTMLDivElement>;
 }
 
 export interface TooltipProviderProps {
@@ -56,6 +58,8 @@ export interface TooltipProviderProps {
 // Components
 // ============================================
 
+const TooltipProviderContext = React.createContext(false);
+
 /**
  * Tooltip - Shows contextual information on hover/focus
  *
@@ -72,16 +76,19 @@ function TooltipRoot({
   side = 'top',
   align = 'center',
   sideOffset = 6,
-  delay = 400,
-  closeDelay = 0,
+  delay,
+  closeDelay,
   disabled = false,
   arrow = true,
   open,
   defaultOpen,
   onOpenChange,
+  contentProps,
   className,
+  style,
   ...htmlProps
 }: TooltipProps) {
+  const hasExternalProvider = React.useContext(TooltipProviderContext);
   const renderTrigger = React.useCallback(
     (triggerProps: React.HTMLAttributes<HTMLElement> & { ref?: React.Ref<HTMLElement> }) => {
       const childProps = children.props as Record<string, unknown>;
@@ -110,30 +117,50 @@ function TooltipRoot({
     return children;
   }
 
-  return (
-    <BaseTooltip.Provider delay={delay} closeDelay={closeDelay}>
-      <BaseTooltip.Root
-        open={open}
-        defaultOpen={defaultOpen}
-        onOpenChange={onOpenChange}
-      >
-        <BaseTooltip.Trigger render={renderTrigger} />
-        <BaseTooltip.Portal>
-          <BaseTooltip.Positioner
-            side={side}
-            align={align}
-            sideOffset={sideOffset}
-            className={styles.positioner}
+  const {
+    className: contentClassName,
+    style: contentStyle,
+    ...contentHtmlProps
+  } = contentProps ?? {};
+
+  const tooltipNode = (
+    <BaseTooltip.Root
+      open={open}
+      defaultOpen={defaultOpen}
+      onOpenChange={onOpenChange}
+    >
+      <BaseTooltip.Trigger render={renderTrigger} />
+      <BaseTooltip.Portal>
+        <BaseTooltip.Positioner
+          side={side}
+          align={align}
+          sideOffset={sideOffset}
+          className={styles.positioner}
+        >
+          <BaseTooltip.Popup
+            {...htmlProps}
+            {...contentHtmlProps}
+            className={[styles.popup, className, contentClassName].filter(Boolean).join(' ')}
+            style={{ ...(style ?? {}), ...(contentStyle ?? {}) }}
           >
-            <BaseTooltip.Popup {...htmlProps} className={[styles.popup, className].filter(Boolean).join(' ')}>
-              {content}
-              {arrow && <BaseTooltip.Arrow className={styles.arrow} />}
-            </BaseTooltip.Popup>
-          </BaseTooltip.Positioner>
-        </BaseTooltip.Portal>
-      </BaseTooltip.Root>
-    </BaseTooltip.Provider>
+            {content}
+            {arrow && <BaseTooltip.Arrow className={styles.arrow} />}
+          </BaseTooltip.Popup>
+        </BaseTooltip.Positioner>
+      </BaseTooltip.Portal>
+    </BaseTooltip.Root>
   );
+
+  // Only create a local provider when no shared provider exists, or when a local delay override is requested.
+  if (!hasExternalProvider || delay !== undefined || closeDelay !== undefined) {
+    return (
+      <BaseTooltip.Provider delay={delay ?? 400} closeDelay={closeDelay ?? 0}>
+        {tooltipNode}
+      </BaseTooltip.Provider>
+    );
+  }
+
+  return tooltipNode;
 }
 
 /**
@@ -160,13 +187,15 @@ export function TooltipProvider({
   const resolvedTimeout = timeout ?? skipDelayDuration ?? 400;
 
   return (
-    <BaseTooltip.Provider
-      delay={resolvedDelay}
-      closeDelay={closeDelay}
-      timeout={resolvedTimeout}
-    >
-      {children}
-    </BaseTooltip.Provider>
+    <TooltipProviderContext.Provider value={true}>
+      <BaseTooltip.Provider
+        delay={resolvedDelay}
+        closeDelay={closeDelay}
+        timeout={resolvedTimeout}
+      >
+        {children}
+      </BaseTooltip.Provider>
+    </TooltipProviderContext.Provider>
   );
 }
 

package/src/components/VisuallyHidden/VisuallyHidden.fragment.tsx

@@ -1,5 +1,5 @@
 import React from 'react';
-import { defineFragment } from '@fragments-sdk/cli/core';
+import { defineFragment } from '@fragments-sdk/core';
 import { VisuallyHidden } from '.';
 
 export default defineFragment({
@@ -32,6 +32,7 @@ export default defineFragment({
       'Keep hidden text concise but descriptive',
       'Test with screen readers to verify announcements',
       'Don\'t overuse; visible text is often better',
+      'VisuallyHidden forwards DOM props and className to the rendered element',
     ],
     accessibility: [
       'Content is announced by screen readers',
@@ -64,6 +65,7 @@ export default defineFragment({
     propsSummary: [
       'children: ReactNode - hidden text (required)',
       'as: span|div - HTML element',
+      'Forwards standard DOM props (id, aria-*, data-*, className, handlers)',
     ],
     scenarioTags: [
       'accessibility.label',

package/src/components/VisuallyHidden/VisuallyHidden.test.tsx

@@ -28,4 +28,16 @@ describe('VisuallyHidden', () => {
     const { container } = render(<VisuallyHidden>Accessible hidden text</VisuallyHidden>);
     await expectNoA11yViolations(container);
   });
+
+  it('forwards DOM props and composes className', () => {
+    render(
+      <VisuallyHidden data-testid="vh" id="vh-id" className="extra">
+        Hidden
+      </VisuallyHidden>
+    );
+    const el = screen.getByTestId('vh');
+    expect(el).toHaveAttribute('id', 'vh-id');
+    expect(el).toHaveClass('visuallyHidden');
+    expect(el).toHaveClass('extra');
+  });
 });

package/src/components/VisuallyHidden/index.tsx

@@ -1,7 +1,7 @@
 import * as React from 'react';
 import styles from './VisuallyHidden.module.scss';
 
-export interface VisuallyHiddenProps {
+export interface VisuallyHiddenProps extends React.HTMLAttributes<HTMLElement> {
   children: React.ReactNode;
   /** HTML element to render */
   as?: 'span' | 'div';
@@ -19,9 +19,13 @@ export interface VisuallyHiddenProps {
  * </Button>
  */
 const VisuallyHiddenRoot = React.forwardRef<HTMLElement, VisuallyHiddenProps>(
-  function VisuallyHidden({ children, as: Component = 'span' }, ref) {
+  function VisuallyHidden({ children, as: Component = 'span', className, ...htmlProps }, ref) {
     return (
-      <Component ref={ref as React.Ref<never>} className={styles.visuallyHidden}>
+      <Component
+        ref={ref as React.Ref<never>}
+        {...htmlProps}
+        className={[styles.visuallyHidden, className].filter(Boolean).join(' ')}
+      >
         {children}
       </Component>
     );

package/src/index.ts

@@ -30,8 +30,6 @@ export {
 export {
   Switch,
   type SwitchProps,
-  Switch as Toggle,
-  type SwitchProps as ToggleProps,
 } from './components/Switch';
 export {
   Alert,
@@ -665,3 +663,6 @@ export {
   type ShortcutName,
   type UseKeyboardShortcutOptions,
 } from './utils/keyboard-shortcuts';
+
+// Legacy aliases (deprecated)
+export { Switch as Toggle, type SwitchProps as ToggleProps } from './components/Switch';