@usefragments/ui 1.5.4 → 1.7.0

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

@@ -1,163 +1,240 @@
 @use "../../tokens/variables" as *;
 @use "../../tokens/mixins" as *;
+@use "../../recipes/layout";
+@use "../../recipes/segmented";
 
 // ============================================
 // Group Container
 // ============================================
 
 .group {
-  --fui-toggle-group-height: var(--fui-button-height-sm, #{$fui-button-height-sm});
-
   display: inline-flex;
   align-items: stretch;
-  min-height: var(--fui-toggle-group-height);
+  isolation: isolate;
 }
 
 // Gap variants
 .gap-xs {
-  gap: var(--fui-space-0-5, $fui-space-0-5);
+  gap: layout.gap("xs");
 }
 
 .gap-sm {
-  gap: var(--fui-space-1, $fui-space-1);
+  gap: layout.gap("sm");
 }
 
 // ============================================
-// Default variant (connected buttons)
+// Item base styles
 // ============================================
 
-.default {
-  @include form-group-surface;
+.item {
+  @include button-reset;
+  @include interactive-base;
 
+  color: var(--fui-text-secondary, $fui-text-secondary);
+  position: relative;
   border: 0;
-  padding: 0;
-  gap: 0;
-  box-shadow: inset 0 0 0 1px var(--fui-form-group-border, var(--fui-border, #{$fui-border}));
+  white-space: nowrap;
+  transition:
+    background-color var(--fui-transition-fast, $fui-transition-fast),
+    border-color var(--fui-transition-fast, $fui-transition-fast),
+    box-shadow var(--fui-transition-fast, $fui-transition-fast),
+    color var(--fui-transition-fast, $fui-transition-fast);
 
-  .item {
-    background-color: transparent;
-    border: 1px solid transparent;
-    // Match the container's radius (form-group-surface = --fui-radius-lg),
-    // less its 1px inset border, so the selected fill nests inside the
-    // container corners instead of poking past them.
-    border-radius: calc(var(--fui-radius-lg, #{$fui-radius-lg}) - 1px);
+  &.selected {
+    color: var(--fui-text-primary, $fui-text-primary);
+  }
 
-    &.selected {
-      background-color: var(--fui-toggle-group-selected-bg, var(--fui-bg-hover, #{$fui-bg-hover}));
-      border-color: var(--fui-toggle-group-selected-border, transparent);
-      box-shadow: var(--fui-toggle-group-selected-shadow, none);
-    }
+  &:focus-visible {
+    z-index: 1;
+  }
+
+  &.disabled {
+    opacity: 0.5;
+    cursor: not-allowed;
   }
 }
 
 // ============================================
-// Pills variant (separate pill buttons)
+// Size variants
 // ============================================
 
-.pills {
+.size-sm {
+  @include segmented.rail("sm");
+
   .item {
-    background-color: var(--fui-field-bg, $fui-bg-elevated);
-    border: 1px solid var(--fui-form-group-border, $fui-border);
-    border-radius: var(--fui-radius-md, $fui-radius-md);
+    @include segmented.item("sm");
 
-    &:hover:not(:disabled):not(.selected) {
-      background-color: var(--fui-bg-hover, $fui-bg-hover);
-      border-color: var(--fui-field-border-hover, $fui-text-tertiary);
+    svg {
+      @include segmented.glyph("sm");
     }
+  }
+}
 
-    &.selected {
-      background-color: var(--fui-toggle-group-selected-bg, var(--fui-bg-hover, #{$fui-bg-hover}));
-      border-color: var(--fui-toggle-group-selected-border, transparent);
-      box-shadow: var(--fui-toggle-group-selected-shadow, none);
+.size-md {
+  @include segmented.rail("md");
+
+  .item {
+    @include segmented.item("md");
+
+    svg {
+      @include segmented.glyph("md");
+    }
+  }
+}
+
+.size-lg {
+  @include segmented.rail("lg");
+
+  .item {
+    @include segmented.item("lg");
+
+    svg {
+      @include segmented.glyph("lg");
     }
   }
 }
 
 // ============================================
-// Outline variant (bordered buttons)
+// Default variant: inset tonal selection
 // ============================================
 
-.outline {
+.default {
+  gap: 0;
+  padding: var(--fui-raw-space-2, 2px);
+  background-color: var(--fui-form-group-bg, var(--fui-bg-secondary, #{$fui-bg-secondary}));
+  border-radius: var(--fui-radius-lg, $fui-radius-lg);
+  box-shadow: inset 0 0 0 var(--fui-stroke-hairline, 1px)
+    var(--fui-form-group-border, var(--fui-border, #{$fui-border}));
+
   .item {
+    min-block-size: calc(
+      var(--_fui-segmented-track) - var(--fui-raw-space-2, 2px) - var(--fui-raw-space-2, 2px)
+    );
     background-color: transparent;
-    border: 1px solid var(--fui-field-border, $fui-border);
-    border-radius: var(--fui-radius-md, $fui-radius-md);
+    // Connected segments: only outer corners are rounded. Per-item full radius
+    // left a rail-colored notch between items that reads as a gap.
+    border-radius: 0;
+
+    &:first-child {
+      border-start-start-radius: var(--fui-radius-md, $fui-radius-md);
+      border-end-start-radius: var(--fui-radius-md, $fui-radius-md);
+    }
+
+    &:last-child {
+      border-start-end-radius: var(--fui-radius-md, $fui-radius-md);
+      border-end-end-radius: var(--fui-radius-md, $fui-radius-md);
+    }
+
+    &:only-child {
+      border-radius: var(--fui-radius-md, $fui-radius-md);
+    }
 
     &:hover:not(:disabled):not(.selected) {
       background-color: var(--fui-bg-hover, $fui-bg-hover);
-      border-color: var(--fui-field-border-hover, $fui-text-tertiary);
     }
 
     &.selected {
-      background-color: var(--fui-toggle-group-selected-bg, var(--fui-bg-hover, #{$fui-bg-hover}));
-      border-color: var(--fui-toggle-group-selected-border, transparent);
-      box-shadow: var(--fui-toggle-group-selected-shadow, none);
+      background-color: var(
+        --fui-toggle-group-selected-bg,
+        var(
+          --fui-control-selected-bg,
+          color-mix(in srgb, var(--fui-text-primary, #{$fui-text-primary}) 9%, transparent)
+        )
+      );
+      box-shadow:
+        inset 0 0 0 var(--fui-stroke-hairline, 1px)
+          var(--fui-toggle-group-selected-border, transparent),
+        var(--fui-toggle-group-selected-shadow, none);
     }
   }
 }
 
 // ============================================
-// Item base styles
+// Pills variant: open cluster with soft selected pills
 // ============================================
 
-.item {
-  @include button-reset;
-  @include interactive-base;
-
-  display: inline-flex;
-  align-items: center;
-  justify-content: center;
-  gap: var(--fui-space-2, $fui-space-2);
-  font-weight: var(--fui-font-weight-medium, $fui-font-weight-medium);
-  color: var(--fui-text-secondary, $fui-text-secondary);
-  white-space: nowrap;
-  user-select: none;
-  transition:
-    background-color var(--fui-transition-fast, $fui-transition-fast),
-    border-color var(--fui-transition-fast, $fui-transition-fast),
-    box-shadow var(--fui-transition-fast, $fui-transition-fast),
-    color var(--fui-transition-fast, $fui-transition-fast);
+.pills {
+  .item {
+    background-color: transparent;
+    border-radius: var(--fui-radius-full, $fui-radius-full);
+    box-shadow: inset 0 0 0 var(--fui-stroke-hairline, 1px) transparent;
 
-  &.selected {
-    color: var(--fui-text-primary, $fui-text-primary);
-  }
+    &:hover:not(:disabled):not(.selected) {
+      background-color: var(--fui-bg-hover, $fui-bg-hover);
+    }
 
-  &.disabled {
-    opacity: 0.5;
-    cursor: not-allowed;
+    &.selected {
+      background-color: var(
+        --fui-toggle-group-selected-bg,
+        var(
+          --fui-control-selected-bg,
+          color-mix(in srgb, var(--fui-text-primary, #{$fui-text-primary}) 9%, transparent)
+        )
+      );
+      box-shadow:
+        inset 0 0 0 var(--fui-stroke-hairline, 1px)
+          var(--fui-toggle-group-selected-border, transparent),
+        var(--fui-toggle-group-selected-shadow, none);
+    }
   }
 }
 
 // ============================================
-// Size variants
+// Outline variant: connected transparent segments
 // ============================================
 
-.size-sm {
-  --fui-toggle-group-height: var(--fui-button-height-sm, #{$fui-button-height-sm});
+.outline {
+  gap: 0;
+  background-color: transparent;
+  border-radius: var(--fui-radius-lg, $fui-radius-lg);
+  box-shadow: inset 0 0 0 var(--fui-stroke-hairline, 1px)
+    var(--fui-form-group-border, var(--fui-border, #{$fui-border}));
 
   .item {
-    min-height: var(--fui-toggle-group-height);
-    padding: 0 var(--fui-space-2, $fui-space-2);
-    font-size: var(--fui-font-size-xs, $fui-font-size-xs);
-  }
-}
+    background-color: transparent;
+    border-radius: 0;
 
-.size-md {
-  --fui-toggle-group-height: var(--fui-button-height-sm, #{$fui-button-height-sm});
+    &:first-child {
+      border-start-start-radius: var(--fui-radius-lg, $fui-radius-lg);
+      border-end-start-radius: var(--fui-radius-lg, $fui-radius-lg);
+    }
 
-  .item {
-    min-height: var(--fui-toggle-group-height);
-    padding: 0 var(--fui-space-3, $fui-space-3);
-    font-size: var(--fui-font-size-sm, $fui-font-size-sm);
-  }
-}
+    &:last-child {
+      border-start-end-radius: var(--fui-radius-lg, $fui-radius-lg);
+      border-end-end-radius: var(--fui-radius-lg, $fui-radius-lg);
+    }
 
-.size-lg {
-  --fui-toggle-group-height: var(--fui-button-height-lg, #{$fui-button-height-lg});
+    & + .item::before {
+      content: "";
+      position: absolute;
+      inset-block: var(--fui-raw-space-6, 6px);
+      inset-inline-start: 0;
+      inline-size: var(--fui-stroke-hairline, 1px);
+      background-color: var(--fui-form-group-border, var(--fui-border, #{$fui-border}));
+      transition: opacity var(--fui-transition-fast, $fui-transition-fast);
+    }
 
-  .item {
-    min-height: var(--fui-toggle-group-height);
-    padding: 0 var(--fui-space-4, $fui-space-4);
-    font-size: var(--fui-font-size-base, $fui-font-size-base);
+    &.selected::before,
+    &.selected + .item::before {
+      opacity: 0;
+    }
+
+    &:hover:not(:disabled):not(.selected) {
+      background-color: var(--fui-bg-hover, $fui-bg-hover);
+    }
+
+    &.selected {
+      background-color: var(
+        --fui-toggle-group-selected-bg,
+        var(
+          --fui-control-selected-bg,
+          color-mix(in srgb, var(--fui-text-primary, #{$fui-text-primary}) 9%, transparent)
+        )
+      );
+      box-shadow:
+        inset 0 0 0 var(--fui-stroke-hairline, 1px)
+          var(--fui-toggle-group-selected-border, transparent),
+        var(--fui-toggle-group-selected-shadow, none);
+    }
   }
 }

package/src/components/ToggleGroup/index.tsx

@@ -30,7 +30,8 @@ export interface ToggleGroupProps extends Omit<React.HTMLAttributes<HTMLDivEleme
   /** Size.
    * @default "md" */
   size?: "sm" | "md" | "lg";
-  /** Gap between items (for pills/outline variants) */
+  /** Gap between items in the pills variant. Defaults to `xs` for pills and
+   * is intentionally removed from connected variants. */
   gap?: "none" | "xs" | "sm";
   /** Selection mode for this control. Currently only single-select is supported.
    * @default "single" */
@@ -84,13 +85,14 @@ function ToggleGroupRoot({
   children,
   variant = "default",
   size: sizeProp,
-  gap = "xs",
+  gap,
   selectionMode = "single",
   className,
   ...htmlProps
 }: ToggleGroupProps) {
   const size = useResolvedControlSize(sizeProp);
   const normalizedVariant = variant === "outlined" ? "outline" : variant;
+  const resolvedGap = normalizedVariant === "pills" ? (gap ?? "xs") : "none";
   const [internalValue, setInternalValue] = React.useState(defaultValue ?? "");
   const isControlled = value !== undefined;
   const currentValue = isControlled ? (value ?? "") : internalValue;
@@ -107,7 +109,7 @@ function ToggleGroupRoot({
     styles.group,
     styles[normalizedVariant],
     styles[`size-${size}`],
-    gap !== "none" && styles[`gap-${gap}`],
+    resolvedGap !== "none" && styles[`gap-${resolvedGap}`],
     className,
   ]
     .filter(Boolean)

package/src/components/Tooltip/Tooltip.contract.json

@@ -1,15 +1,9 @@
 {
   "$schema": "https://usefragments.com/schemas/contract.v1.json",
   "name": "Tooltip",
-  "description": "Contextual help text that appears on hover or focus. Perfect for explaining icons, truncated text, or providing additional context.",
-  "category": "feedback",
-  "tags": [
-    "tooltip",
-    "hint",
-    "help",
-    "hover",
-    "contextual"
-  ],
+  "description": "Shows a one-line hint when a control is hovered or focused.",
+  "category": "overlays",
+  "tags": ["tooltip", "hint", "help", "hover", "contextual"],
   "status": "stable",
   "sourcePath": "src/components/Tooltip/index.tsx",
   "exportName": "Tooltip",
@@ -45,23 +39,14 @@
       "description": "Which side to show the tooltip",
       "default": "top",
       "required": false,
-      "values": [
-        "top",
-        "bottom",
-        "left",
-        "right"
-      ]
+      "values": ["top", "bottom", "left", "right"]
     },
     "align": {
       "type": "enum",
       "description": "Alignment along the side",
       "default": "center",
       "required": false,
-      "values": [
-        "start",
-        "center",
-        "end"
-      ]
+      "values": ["start", "center", "end"]
     },
     "sideOffset": {
       "type": "number",
@@ -122,55 +107,55 @@
   },
   "usage": {
     "when": [
-      "Explaining icon-only buttons",
-      "Showing full text for truncated content",
-      "Providing keyboard shortcuts",
-      "Brief contextual help that fits in one line"
+      "Naming icon-only buttons",
+      "Showing text that had to be truncated",
+      "Surfacing a keyboard shortcut",
+      "One line of help, no more"
     ],
     "whenNot": [
-      "Long-form help content (use Popover)",
-      "Critical information users must see (use Alert)",
-      "Interactive content (use Popover or Menu)",
-      "Mobile-primary interfaces (tooltips require hover)"
+      "Help longer than a line — use Popover",
+      "Anything the user must not miss — use Alert",
+      "Content they need to click — use Popover or Menu",
+      "Touch-first screens, where there is no hover"
     ],
     "guidelines": [
-      "Keep tooltip text concise (under 80 characters)",
-      "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"
+      "Under 80 characters",
+      "Sentence case, no trailing period",
+      "Never just repeat the visible label",
+      "Always leave a non-hover path to the same information",
+      "contentProps sets attributes and styling on the popup"
     ],
     "accessibility": [
-      "Accessible via focus as well as hover",
-      "Uses role=\"tooltip\" with proper aria association",
-      "Delay prevents tooltips from appearing during navigation"
+      "Opens on keyboard focus, not only hover",
+      "The open delay stops tooltips flashing while the pointer crosses the screen",
+      "Do not put anything critical here — treat it as a hint, not a label"
     ]
   },
   "examples": [
     {
       "name": "Default",
-      "description": "Basic tooltip on hover",
+      "description": "Appears after a short delay above the trigger.",
       "code": "<Tooltip content=\"Save your changes\">\n  <Button>Save</Button>\n</Tooltip>"
     },
     {
       "name": "Positions",
-      "description": "Tooltips on different sides",
-      "code": "<div style={{ display: 'flex', gap: '16px', padding: '40px' }}>\n  <Tooltip content=\"Top tooltip\" side=\"top\">\n    <Button variant=\"secondary\">Top</Button>\n  </Tooltip>\n  <Tooltip content=\"Bottom tooltip\" side=\"bottom\">\n    <Button variant=\"secondary\">Bottom</Button>\n  </Tooltip>\n  <Tooltip content=\"Left tooltip\" side=\"left\">\n    <Button variant=\"secondary\">Left</Button>\n  </Tooltip>\n  <Tooltip content=\"Right tooltip\" side=\"right\">\n    <Button variant=\"secondary\">Right</Button>\n  </Tooltip>\n</div>"
+      "description": "Four sides; it flips if the edge is too close.",
+      "code": "import { Stack } from '@/components/Stack';\n\n<Stack direction=\"row\" gap=\"md\" align=\"center\" wrap>\n  <Tooltip content=\"Top tooltip\" side=\"top\">\n    <Button variant=\"secondary\">Top</Button>\n  </Tooltip>\n  <Tooltip content=\"Bottom tooltip\" side=\"bottom\">\n    <Button variant=\"secondary\">Bottom</Button>\n  </Tooltip>\n  <Tooltip content=\"Left tooltip\" side=\"left\">\n    <Button variant=\"secondary\">Left</Button>\n  </Tooltip>\n  <Tooltip content=\"Right tooltip\" side=\"right\">\n    <Button variant=\"secondary\">Right</Button>\n  </Tooltip>\n</Stack>"
     },
     {
       "name": "With Shortcut",
-      "description": "Tooltip showing keyboard shortcut",
+      "description": "Spells out the key combination the icon implies.",
       "code": "<Tooltip content=\"Undo (Ctrl+Z)\">\n  <Button variant=\"ghost\">Undo</Button>\n</Tooltip>"
     },
     {
       "name": "No Arrow",
-      "description": "Tooltip without arrow",
-      "code": "<Tooltip content=\"Clean tooltip\" arrow={false}>\n  <Button variant=\"secondary\">Hover me</Button>\n</Tooltip>"
+      "description": "Drops the pointer for tooltips packed into dense chrome.",
+      "code": "<Tooltip content=\"No arrow on this one\" arrow={false}>\n  <Button variant=\"secondary\">Arrowless</Button>\n</Tooltip>"
     },
     {
       "name": "With Content Props",
-      "description": "Pass popup attributes/styling using contentProps",
-      "code": "<Tooltip content=\"Custom popup attrs\" contentProps={{ id: 'custom-tooltip-popup' }}>\n  <Button variant=\"secondary\">Hover me</Button>\n</Tooltip>"
+      "description": "contentProps lands on the popup element itself.",
+      "code": "<Tooltip\n  content=\"Styled through contentProps\"\n  contentProps={{ id: 'custom-tooltip-popup' }}\n>\n  <Button variant=\"secondary\">Custom popup</Button>\n</Tooltip>"
     }
   ],
   "relations": [
@@ -193,17 +178,11 @@
       "arrow: boolean - show arrow (default: true)",
       "contentProps: HTMLAttributes<HTMLDivElement> - popup element props"
     ],
-    "a11yRules": [
-      "A11Y_TOOLTIP_FOCUS",
-      "A11Y_TOOLTIP_ROLE"
-    ]
+    "a11yRules": ["A11Y_TOOLTIP_FOCUS", "A11Y_TOOLTIP_ROLE"]
   },
   "ai": {
     "compositionPattern": "compound",
-    "subComponents": [
-      "Root",
-      "Provider"
-    ]
+    "subComponents": ["Root", "Provider"]
   },
   "provenance": {
     "source": "migrated",

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

@@ -1,32 +1,19 @@
-@use '../../tokens/variables' as *;
-@use '../../tokens/mixins' as *;
+@use "../../tokens/variables" as *;
+@use "../../recipes/overlay" as overlay;
 
-// Local component tokens (tooltips always use inverted colors — no light variant)
-// Arrow size shared with Popover/Menu for a consistent overlay arrow.
-$fui-arrow-size: 10px !default;
-
-// Positioner (handles placement)
 .positioner {
-  z-index: 60;
+  z-index: var(--fui-overlay-layer-tooltip, 60);
   pointer-events: none;
 }
 
-// The tooltip popup
 .popup {
-  @include text-base;
+  @include overlay.tooltip;
 
-  padding: var(--fui-space-1, $fui-space-1) var(--fui-space-2, $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
   color: var(--fui-text-inverse, $fui-text-inverse);
   background-color: var(--fui-bg-inverse, $fui-bg-inverse);
   border-radius: var(--fui-radius-md, $fui-radius-md);
   box-shadow: var(--fui-shadow-md, $fui-shadow-md);
-  max-width: 20rem; // 320px
-  word-wrap: break-word;
-
-  // Animation
+  overflow-wrap: break-word;
   opacity: 0;
   transform: scale(0.95);
   transform-origin: var(--transform-origin);
@@ -39,49 +26,46 @@ $fui-arrow-size: 10px !default;
     transform: scale(1);
   }
 
-  &[data-starting-style] {
-    opacity: 0;
-    transform: scale(0.95);
-  }
-
+  &[data-starting-style],
   &[data-ending-style] {
     opacity: 0;
     transform: scale(0.95);
   }
 
-  // Instant transitions (when moving between tooltips)
   &[data-instant] {
     transition-duration: 0ms;
   }
 }
 
-// Arrow element — matches Popover/Menu (10px + border)
 .arrow {
-  width: $fui-arrow-size;
-  height: $fui-arrow-size;
-  transform: rotate(45deg);
+  @include overlay.arrow-box;
+
   background-color: var(--fui-bg-inverse, $fui-bg-inverse);
-  border: 1px solid var(--fui-bg-inverse, $fui-bg-inverse);
+  border: var(--fui-stroke-hairline, 1px) solid var(--fui-bg-inverse, $fui-bg-inverse);
 
-  // Position based on side (offset = half the arrow size)
-  &[data-side='top'] {
-    bottom: calc($fui-arrow-size / -2);
+  &[data-side="top"] {
+    bottom: calc(var(--fui-overlay-arrow-size, var(--fui-raw-space-10, 10px)) / -2);
   }
 
-  &[data-side='bottom'] {
-    top: calc($fui-arrow-size / -2);
+  &[data-side="bottom"] {
+    top: calc(var(--fui-overlay-arrow-size, var(--fui-raw-space-10, 10px)) / -2);
   }
 
-  &[data-side='left'] {
-    right: calc($fui-arrow-size / -2);
+  &[data-side="left"] {
+    right: calc(var(--fui-overlay-arrow-size, var(--fui-raw-space-10, 10px)) / -2);
   }
 
-  &[data-side='right'] {
-    left: calc($fui-arrow-size / -2);
+  &[data-side="right"] {
+    left: calc(var(--fui-overlay-arrow-size, var(--fui-raw-space-10, 10px)) / -2);
   }
 }
 
-// Trigger wrapper (when using asChild)
 .trigger {
   display: inline-flex;
 }
+
+@media (prefers-reduced-motion: reduce) {
+  .popup {
+    transition: none;
+  }
+}