@usefragments/ui 1.0.0

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

@@ -0,0 +1,244 @@
+@use "../../tokens/variables" as *;
+@use "../../tokens/mixins" as *;
+
+// Local component tokens (web-proportioned: ~1.8:1 width:height ratio)
+$fui-toggle-width-sm: 1.857rem !default; // 26px
+$fui-toggle-width-md: 2.571rem !default; // 36px
+$fui-toggle-width-lg: 3.286rem !default; // 46px
+$fui-toggle-height-sm: 1.143rem !default; // 16px
+$fui-toggle-height-md: 1.429rem !default; // 20px
+$fui-toggle-height-lg: 1.857rem !default; // 26px
+$fui-toggle-thumb-sm: 0.857rem !default; // 12px
+$fui-toggle-thumb-md: 1.143rem !default; // 16px
+$fui-toggle-thumb-offset: 2px !default;
+
+.root {
+  --_switch-off-bg: light-dark(
+    color-mix(in srgb, var(--fui-bg-elevated) 92%, var(--fui-text-primary) 8%),
+    color-mix(in srgb, var(--fui-bg-elevated) 82%, var(--fui-text-primary) 18%)
+  );
+  --_switch-off-bg-hover: light-dark(
+    color-mix(in srgb, var(--fui-bg-elevated) 88%, var(--fui-text-primary) 12%),
+    color-mix(in srgb, var(--fui-bg-elevated) 76%, var(--fui-text-primary) 24%)
+  );
+  --_switch-off-border: light-dark(
+    color-mix(in srgb, var(--fui-border-strong) 72%, var(--fui-text-primary) 28%),
+    color-mix(in srgb, var(--fui-border-strong) 58%, var(--fui-text-primary) 42%)
+  );
+  --_switch-off-border-hover: light-dark(
+    color-mix(in srgb, var(--fui-border-strong) 58%, var(--fui-text-primary) 42%),
+    color-mix(in srgb, var(--fui-border-strong) 44%, var(--fui-text-primary) 56%)
+  );
+  --_switch-thumb-bg: light-dark(
+    color-mix(in srgb, var(--fui-bg-primary) 98%, white 2%),
+    color-mix(in srgb, var(--fui-bg-primary) 56%, var(--fui-text-primary) 44%)
+  );
+  --_switch-thumb-border: light-dark(
+    color-mix(in srgb, var(--fui-border-strong) 68%, var(--fui-text-primary) 32%),
+    color-mix(in srgb, var(--fui-border-strong) 45%, var(--fui-text-primary) 55%)
+  );
+
+  position: relative;
+  display: flex;
+  align-items: center;
+  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;
+  }
+
+  &::before {
+    content: "";
+    position: absolute;
+    top: 50%;
+    left: 0;
+    width: max(100%, var(--fui-target-size-min, #{$fui-target-size-min}));
+    height: var(--fui-target-size-min, $fui-target-size-min);
+    transform: translateY(-50%);
+  }
+}
+
+.rootWithHelper {
+  align-items: flex-start;
+
+  .track {
+    margin-top: var(--fui-space-0-5, $fui-space-0-5);
+  }
+}
+
+// iOS-style track: solid fill, clean pill shape
+.track {
+  position: relative;
+  display: inline-flex;
+  align-items: center;
+  flex-shrink: 0;
+  box-sizing: border-box;
+  border-radius: var(--fui-radius-full, $fui-radius-full);
+  border: 1px solid var(--_switch-off-border);
+  background-color: var(--_switch-off-bg);
+  box-shadow:
+    inset 0 1px 0 color-mix(in srgb, white 26%, transparent),
+    inset 0 -1px 0 color-mix(in srgb, var(--fui-text-primary, $fui-text-primary) 5%, transparent);
+  transition:
+    background-color var(--fui-transition-normal, $fui-transition-normal),
+    border-color var(--fui-transition-normal, $fui-transition-normal),
+    box-shadow var(--fui-transition-normal, $fui-transition-normal);
+
+  .root[data-checked] & {
+    background-color: var(--fui-button-primary-base, $fui-color-accent);
+    border-color: var(
+      --fui-button-primary-border,
+      var(--fui-button-primary-base, #{$fui-color-accent})
+    );
+    box-shadow: inset 0 1px 0 color-mix(in srgb, white 24%, transparent);
+  }
+
+  .root:not([data-disabled]):not([data-checked]) &:hover {
+    background-color: var(--_switch-off-bg-hover);
+    border-color: var(--_switch-off-border-hover);
+  }
+
+  .root:not([data-disabled])[data-checked] &:hover {
+    background-color: var(--fui-button-primary-hover, $fui-color-accent);
+    border-color: var(
+      --fui-button-primary-border-hover,
+      var(--fui-button-primary-hover, #{$fui-color-accent})
+    );
+  }
+
+  .root:focus-visible & {
+    @include field-shell-focus;
+  }
+}
+
+// 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}) - 4px);
+  --_toggle-inset: 1px;
+  --_toggle-translate: calc(
+    var(--fui-toggle-width-sm, #{$fui-toggle-width-sm}) - var(--_toggle-thumb-size) - 4px
+  );
+}
+
+// Lg: 60×36
+.trackLg {
+  width: var(--fui-toggle-width-lg, $fui-toggle-width-lg);
+  height: var(--fui-toggle-height-lg, $fui-toggle-height-lg);
+  --_toggle-thumb-size: calc(var(--fui-toggle-height-lg, #{$fui-toggle-height-lg}) - 4px);
+  --_toggle-inset: 1px;
+  --_toggle-translate: calc(
+    var(--fui-toggle-width-lg, #{$fui-toggle-width-lg}) - var(--_toggle-thumb-size) - 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}) - 4px);
+  --_toggle-inset: 1px;
+  --_toggle-translate: calc(
+    var(--fui-toggle-width-md, #{$fui-toggle-width-md}) - var(--_toggle-thumb-size) - 4px
+  );
+}
+
+.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%;
+  pointer-events: none;
+  background-color: var(--_switch-thumb-bg);
+  border: 1px solid var(--_switch-thumb-border);
+  box-shadow:
+    0 1px 1px color-mix(in srgb, black 18%, transparent),
+    inset 0 1px 0 color-mix(in srgb, white 42%, transparent);
+  transition:
+    transform var(--fui-transition-normal, $fui-transition-normal),
+    background-color var(--fui-transition-normal, $fui-transition-normal),
+    border-color var(--fui-transition-normal, $fui-transition-normal),
+    box-shadow var(--fui-transition-fast, $fui-transition-fast);
+
+  .root[data-checked] & {
+    transform: translateX(var(--_toggle-translate, 0));
+    background-color: var(--fui-button-primary-color, #fff);
+    border-color: color-mix(
+      in srgb,
+      var(--fui-button-primary-active, #{$fui-color-accent}) 28%,
+      transparent
+    );
+  }
+
+  .root:active:not([data-disabled]) & {
+    box-shadow: var(--fui-shadow-md, $fui-shadow-md);
+  }
+}
+
+.content {
+  flex: 1;
+}
+
+.label {
+  font-size: var(--fui-font-size-sm, $fui-font-size-sm);
+  font-weight: var(--fui-font-weight-medium, $fui-font-weight-medium);
+  color: var(--fui-text-primary, $fui-text-primary);
+  line-height: var(--fui-line-height-tight, $fui-line-height-tight);
+  user-select: none;
+}
+
+.labelSm {
+  font-size: var(--fui-font-size-xs, $fui-font-size-xs);
+}
+
+.labelLg {
+  font-size: var(--fui-font-size-base, $fui-font-size-base);
+}
+
+.helper {
+  display: block;
+  font-size: var(--fui-font-size-xs, $fui-font-size-xs);
+  color: var(--fui-text-secondary, $fui-text-secondary);
+  margin-top: var(--fui-space-1, $fui-space-1);
+  line-height: var(--fui-line-height-normal, $fui-line-height-normal);
+}
+
+.helperSm {
+  font-size: var(--fui-font-size-2xs, $fui-font-size-2xs);
+}
+
+// ============================================
+// Accessibility: High Contrast Mode
+// ============================================
+
+@media (prefers-contrast: more) {
+  .track {
+    border: 2px solid var(--fui-text-primary, $fui-text-primary);
+  }
+
+  .root[data-checked] .track {
+    border-color: var(--fui-button-primary-base, $fui-color-accent);
+  }
+}
+
+// ============================================
+// Accessibility: Reduced Motion
+// ============================================
+
+@media (prefers-reduced-motion: reduce) {
+  .thumb {
+    transition: none;
+  }
+
+  .track {
+    transition: none;
+  }
+}

package/src/components/Toggle/index.tsx

@@ -0,0 +1,140 @@
+"use client";
+
+import * as React from "react";
+import { Switch as BaseSwitch } from "@base-ui/react/switch";
+import { useResolvedControlSize } from "../ComponentDefaults";
+import { mergeAriaIds } from "../../utils/aria";
+import styles from "./Toggle.module.scss";
+
+/**
+ * Binary on/off switch for settings and preferences.
+ * @see https://usefragments.com/components/switch
+ */
+export interface SwitchProps {
+  /** Whether the switch is on */
+  checked?: boolean;
+  /** Default checked state (uncontrolled) */
+  defaultChecked?: boolean;
+  /** Called when the switch is toggled */
+  onCheckedChange?: (checked: boolean) => void;
+  /** Alias for onCheckedChange */
+  onChange?: (checked: boolean) => void;
+  label?: string;
+  /** Helper text shown below the label */
+  helperText?: string;
+  /** @deprecated Use helperText instead. */
+  description?: string;
+  disabled?: boolean;
+  readOnly?: boolean;
+  required?: boolean;
+  size?: "sm" | "md" | "lg";
+  className?: string;
+  name?: string;
+  form?: string;
+  value?: string;
+  uncheckedValue?: string;
+  inputRef?: React.Ref<HTMLInputElement>;
+  id?: string;
+  "aria-label"?: string;
+  "aria-labelledby"?: string;
+  "aria-describedby"?: string;
+}
+
+export type ToggleProps = SwitchProps;
+
+const SwitchRoot = React.forwardRef<HTMLButtonElement, SwitchProps>(function Switch(
+  {
+    checked,
+    defaultChecked,
+    onChange,
+    onCheckedChange,
+    label,
+    helperText,
+    description,
+    disabled = false,
+    readOnly = false,
+    required = false,
+    size: sizeProp,
+    className,
+    name,
+    form,
+    value,
+    uncheckedValue,
+    inputRef,
+    id,
+    "aria-label": ariaLabel,
+    "aria-labelledby": ariaLabelledBy,
+    "aria-describedby": ariaDescribedBy,
+  },
+  ref
+) {
+  const size = useResolvedControlSize(sizeProp);
+  const resolvedHelperText = helperText ?? description;
+  const generatedId = React.useId();
+  const resolvedId = id ?? `switch-${generatedId}`;
+  const helperId = resolvedHelperText ? `${resolvedId}-helper` : undefined;
+  const trackClasses = [
+    styles.track,
+    size === "sm" ? styles.trackSm : size === "lg" ? styles.trackLg : styles.trackMd,
+  ].join(" ");
+
+  const thumbClasses = styles.thumb;
+
+  const labelClasses = [
+    styles.label,
+    size === "sm" && styles.labelSm,
+    size === "lg" && styles.labelLg,
+  ]
+    .filter(Boolean)
+    .join(" ");
+
+  const helperClasses = [styles.helper, size === "sm" && styles.helperSm].filter(Boolean).join(" ");
+
+  const rootClasses = [styles.root, resolvedHelperText && styles.rootWithHelper, className]
+    .filter(Boolean)
+    .join(" ");
+
+  return (
+    <BaseSwitch.Root
+      ref={ref}
+      id={resolvedId}
+      checked={checked}
+      defaultChecked={defaultChecked}
+      onCheckedChange={onCheckedChange ?? onChange}
+      disabled={disabled}
+      readOnly={readOnly}
+      required={required}
+      name={name}
+      form={form}
+      value={value}
+      uncheckedValue={uncheckedValue}
+      inputRef={inputRef}
+      className={rootClasses}
+      aria-label={ariaLabel}
+      aria-labelledby={ariaLabelledBy}
+      aria-describedby={mergeAriaIds(ariaDescribedBy, helperId)}
+    >
+      <span className={trackClasses} aria-hidden="true">
+        <BaseSwitch.Thumb className={thumbClasses} />
+      </span>
+
+      {(label || resolvedHelperText) && (
+        <div className={styles.content}>
+          {label && <span className={labelClasses}>{label}</span>}
+          {resolvedHelperText && (
+            <span id={helperId} className={helperClasses}>
+              {resolvedHelperText}
+            </span>
+          )}
+        </div>
+      )}
+    </BaseSwitch.Root>
+  );
+});
+
+export const Switch = Object.assign(SwitchRoot, {
+  Root: SwitchRoot,
+});
+
+/** @deprecated Use `Switch` instead. */
+export const Toggle = Switch;

package/src/components/ToggleGroup/ToggleGroup.contract.json

@@ -0,0 +1,206 @@
+{
+  "$schema": "https://usefragments.com/schemas/contract.v1.json",
+  "name": "ToggleGroup",
+  "description": "A group of toggle buttons where only one can be selected at a time. Useful for switching between views, modes, or options.",
+  "category": "forms",
+  "tags": [
+    "toggle",
+    "group",
+    "fragmented",
+    "control",
+    "tabs",
+    "switch"
+  ],
+  "status": "stable",
+  "sourcePath": "src/components/ToggleGroup/index.tsx",
+  "exportName": "ToggleGroup",
+  "propsSummary": [
+    "value: string",
+    "defaultValue: string",
+    "onChange: function",
+    "onValueChange: function",
+    "children: node (required)",
+    "variant: default|pills|outline|outlined (default: default)",
+    "size: sm|md|lg (default: md)",
+    "gap: sm|none|xs (default: xs)",
+    "selectionMode: single (default: single)"
+  ],
+  "props": {
+    "value": {
+      "type": "string",
+      "description": "Currently selected value",
+      "required": false
+    },
+    "defaultValue": {
+      "type": "string",
+      "description": "Initial selected value (uncontrolled)",
+      "required": false
+    },
+    "onChange": {
+      "type": "function",
+      "description": "Called with new value when selection changes",
+      "required": false
+    },
+    "onValueChange": {
+      "type": "function",
+      "description": "Alias for onChange (Radix convention): (value: string) => void",
+      "required": false
+    },
+    "children": {
+      "type": "node",
+      "description": "ToggleGroup.Item components",
+      "required": true
+    },
+    "variant": {
+      "type": "enum",
+      "description": "Visual style",
+      "default": "default",
+      "required": false,
+      "values": [
+        "default",
+        "pills",
+        "outline",
+        "outlined"
+      ]
+    },
+    "size": {
+      "type": "enum",
+      "description": "Size variant",
+      "default": "md",
+      "required": false,
+      "values": [
+        "sm",
+        "md",
+        "lg"
+      ]
+    },
+    "gap": {
+      "type": "enum",
+      "description": "Gap between items (pills/outline variants)",
+      "default": "xs",
+      "required": false,
+      "values": [
+        "sm",
+        "none",
+        "xs"
+      ]
+    },
+    "selectionMode": {
+      "type": "enum",
+      "description": "Selection behavior",
+      "default": "single",
+      "required": false,
+      "values": [
+        "single"
+      ]
+    }
+  },
+  "usage": {
+    "when": [
+      "Switching between mutually exclusive views or modes",
+      "Selecting one option from a small set (2-5 options)",
+      "Fragmented controls like view switchers",
+      "Filter or sort options"
+    ],
+    "whenNot": [
+      "Multiple selections allowed (use Checkbox group)",
+      "Many options (use Select or RadioGroup)",
+      "Navigation between pages (use Tabs)",
+      "On/off toggle (use Switch component)"
+    ],
+    "guidelines": [
+      "Keep options to 2-5 items for clarity",
+      "Use clear, concise labels",
+      "Consider icons for common actions (grid/list view)",
+      "Ensure adequate touch targets on mobile"
+    ],
+    "accessibility": [
+      "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"
+    ]
+  },
+  "examples": [
+    {
+      "name": "Default",
+      "description": "Basic toggle group",
+      "code": "<ToggleGroup value={value} onChange={setValue}>\n  <ToggleGroup.Item value=\"left\">Left</ToggleGroup.Item>\n  <ToggleGroup.Item value=\"center\">Center</ToggleGroup.Item>\n  <ToggleGroup.Item value=\"right\">Right</ToggleGroup.Item>\n</ToggleGroup>"
+    },
+    {
+      "name": "Pills Variant",
+      "description": "Pill-shaped toggle buttons",
+      "code": "<ToggleGroup value={value} onChange={setValue} variant=\"pills\">\n  <ToggleGroup.Item value=\"all\">All</ToggleGroup.Item>\n  <ToggleGroup.Item value=\"active\">Active</ToggleGroup.Item>\n  <ToggleGroup.Item value=\"completed\">Completed</ToggleGroup.Item>\n</ToggleGroup>"
+    },
+    {
+      "name": "Outline Variant",
+      "description": "Outlined toggle buttons",
+      "code": "<ToggleGroup value={value} onChange={setValue} variant=\"outlined\">\n  <ToggleGroup.Item value=\"day\">Day</ToggleGroup.Item>\n  <ToggleGroup.Item value=\"week\">Week</ToggleGroup.Item>\n  <ToggleGroup.Item value=\"month\">Month</ToggleGroup.Item>\n</ToggleGroup>"
+    },
+    {
+      "name": "Uncontrolled",
+      "description": "Use defaultValue for simple single-select state",
+      "code": "<ToggleGroup defaultValue=\"list\">\n  <ToggleGroup.Item value=\"grid\">Grid</ToggleGroup.Item>\n  <ToggleGroup.Item value=\"list\">List</ToggleGroup.Item>\n</ToggleGroup>"
+    },
+    {
+      "name": "Sizes",
+      "description": "Different size variants",
+      "code": "<ToggleGroup value={value} onChange={setValue} size=\"sm\">\n  <ToggleGroup.Item value=\"a\">Small</ToggleGroup.Item>\n  <ToggleGroup.Item value=\"b\">Size</ToggleGroup.Item>\n</ToggleGroup>\n<ToggleGroup value={value} onChange={setValue} size=\"md\">\n  <ToggleGroup.Item value=\"a\">Medium</ToggleGroup.Item>\n  <ToggleGroup.Item value=\"b\">Size</ToggleGroup.Item>\n</ToggleGroup>"
+    },
+    {
+      "name": "View Switcher",
+      "description": "Common pattern for switching between views",
+      "code": "<ToggleGroup value={view} onChange={setView} size=\"sm\">\n  <ToggleGroup.Item value=\"grid\"><GridIcon /></ToggleGroup.Item>\n  <ToggleGroup.Item value=\"list\"><ListIcon /></ToggleGroup.Item>\n</ToggleGroup>"
+    },
+    {
+      "name": "With Disabled Item",
+      "description": "Toggle group with a disabled option",
+      "code": "<ToggleGroup value={value} onChange={setValue}>\n  <ToggleGroup.Item value=\"basic\">Basic</ToggleGroup.Item>\n  <ToggleGroup.Item value=\"pro\">Pro</ToggleGroup.Item>\n  <ToggleGroup.Item value=\"enterprise\" disabled>Enterprise</ToggleGroup.Item>\n</ToggleGroup>"
+    }
+  ],
+  "relations": [
+    {
+      "component": "RadioGroup",
+      "relationship": "alternative",
+      "note": "RadioGroup for form-style single selection"
+    },
+    {
+      "component": "Tabs",
+      "relationship": "alternative",
+      "note": "Tabs for content panel switching"
+    },
+    {
+      "component": "Switch",
+      "relationship": "sibling",
+      "note": "Switch for single on/off control"
+    }
+  ],
+  "contract": {
+    "propsSummary": [
+      "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|outlined - visual style (outlined aliases outline)",
+      "size: sm|md - size variant",
+      "gap: none|xs|sm - spacing",
+      "selectionMode: single (default: single)"
+    ],
+    "a11yRules": [
+      "A11Y_GROUP_ROLE",
+      "A11Y_KEYBOARD_ACCESSIBLE"
+    ]
+  },
+  "ai": {
+    "compositionPattern": "compound",
+    "subComponents": [
+      "Item"
+    ]
+  },
+  "provenance": {
+    "source": "migrated",
+    "verified": false,
+    "frameworkSupport": "native",
+    "extractedAt": "2026-03-13T23:19:07.233Z"
+  }
+}