@usefragments/ui 1.6.0 → 2.0.0

package/src/components/Tooltip/index.tsx

@@ -1,17 +1,20 @@
-'use client';
+"use client";
 
-import * as React from 'react';
-import { Tooltip as BaseTooltip } from '@base-ui/react/tooltip';
-import styles from './Tooltip.module.scss';
+import * as React from "react";
+import { Tooltip as BaseTooltip } from "@base-ui/react/tooltip";
+import styles from "./Tooltip.module.scss";
 
 // ============================================
 // Types
 // ============================================
 
-export type TooltipSide = 'top' | 'bottom' | 'left' | 'right';
-export type TooltipAlign = 'start' | 'center' | 'end';
+export type TooltipSide = "top" | "bottom" | "left" | "right";
+export type TooltipAlign = "start" | "center" | "end";
 
-export interface TooltipProps extends Omit<React.HTMLAttributes<HTMLDivElement>, 'content' | 'defaultChecked'> {
+export interface TooltipProps extends Omit<
+  React.HTMLAttributes<HTMLDivElement>,
+  "content" | "defaultChecked"
+> {
   /** The element that triggers the tooltip */
   children: React.ReactElement;
   /** Content to display in the tooltip */
@@ -76,8 +79,8 @@ const TooltipProviderContext = React.createContext(false);
 function TooltipRoot({
   children,
   content,
-  side = 'top',
-  align = 'center',
+  side = "top",
+  align = "center",
   sideOffset = 6,
   delay,
   closeDelay,
@@ -101,9 +104,9 @@ function TooltipRoot({
       for (const [key, triggerHandler] of Object.entries(triggerProps)) {
         const childHandler = childProps[key];
         if (
-          key.startsWith('on') &&
-          typeof triggerHandler === 'function' &&
-          typeof childHandler === 'function'
+          key.startsWith("on") &&
+          typeof triggerHandler === "function" &&
+          typeof childHandler === "function"
         ) {
           mergedProps[key] = (...args: unknown[]) => {
             (childHandler as (...event: unknown[]) => void)(...args);
@@ -114,7 +117,7 @@ function TooltipRoot({
 
       return React.cloneElement(children, mergedProps);
     },
-    [children],
+    [children]
   );
 
   if (disabled || !children) {
@@ -128,11 +131,7 @@ function TooltipRoot({
   } = contentProps ?? {};
 
   const tooltipNode = (
-    <BaseTooltip.Root
-      open={open}
-      defaultOpen={defaultOpen}
-      onOpenChange={onOpenChange}
-    >
+    <BaseTooltip.Root open={open} defaultOpen={defaultOpen} onOpenChange={onOpenChange}>
       <BaseTooltip.Trigger closeOnClick={closeOnClick} render={renderTrigger} />
       <BaseTooltip.Portal>
         <BaseTooltip.Positioner
@@ -144,7 +143,7 @@ function TooltipRoot({
           <BaseTooltip.Popup
             {...htmlProps}
             {...contentHtmlProps}
-            className={[styles.popup, className, contentClassName].filter(Boolean).join(' ')}
+            className={[styles.popup, className, contentClassName].filter(Boolean).join(" ")}
             style={{ ...(style ?? {}), ...(contentStyle ?? {}) }}
           >
             {content}
@@ -192,11 +191,7 @@ export function TooltipProvider({
 
   return (
     <TooltipProviderContext.Provider value={true}>
-      <BaseTooltip.Provider
-        delay={resolvedDelay}
-        closeDelay={closeDelay}
-        timeout={resolvedTimeout}
-      >
+      <BaseTooltip.Provider delay={resolvedDelay} closeDelay={closeDelay} timeout={resolvedTimeout}>
         {children}
       </BaseTooltip.Provider>
     </TooltipProviderContext.Provider>

package/src/components/VisuallyHidden/VisuallyHidden.contract.json

@@ -1,22 +1,13 @@
 {
   "$schema": "https://usefragments.com/schemas/contract.v1.json",
   "name": "VisuallyHidden",
-  "description": "Hides content visually while keeping it accessible to screen readers. Essential for accessible icon-only buttons and supplementary text.",
-  "category": "navigation",
-  "tags": [
-    "accessibility",
-    "a11y",
-    "screen-reader",
-    "hidden",
-    "sr-only"
-  ],
+  "description": "Keeps text in the accessibility tree while taking it off the screen.",
+  "category": "utilities",
+  "tags": ["accessibility", "a11y", "screen-reader", "hidden", "sr-only"],
   "status": "stable",
   "sourcePath": "src/components/VisuallyHidden/index.tsx",
   "exportName": "VisuallyHidden",
-  "propsSummary": [
-    "children: node (required)",
-    "as: span|div (default: span)"
-  ],
+  "propsSummary": ["children: node (required)", "as: span|div (default: span)"],
   "props": {
     "children": {
       "type": "node",
@@ -28,53 +19,45 @@
       "description": "HTML element to render",
       "default": "span",
       "required": false,
-      "values": [
-        "span",
-        "div"
-      ]
+      "values": ["span", "div"]
     }
   },
   "usage": {
     "when": [
-      "Providing accessible labels for icon-only buttons",
-      "Adding context that screen readers need but sighted users don't",
-      "Hiding decorative content while providing text alternatives",
-      "Skip links for keyboard navigation"
+      "An icon-only control needs a name",
+      "A link's text is vague out of context",
+      "A skip link needs to hide until focused"
     ],
     "whenNot": [
-      "Hiding content from everyone (use display: none or conditional render)",
-      "Content that should be visible on focus (use focus-visible styles)",
-      "Temporarily hidden content (use proper ARIA attributes)",
-      "Lazy-loaded content (use suspense or loading states)"
+      "Nobody should see or hear it (render nothing)",
+      "The content is just collapsed (use aria-expanded)"
     ],
     "guidelines": [
-      "Always use with icon-only interactive elements",
-      "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"
+      "Every icon-only button gets one",
+      "Say the action, not the icon: \"Search\", not \"magnifier\"",
+      "Keep it short — it is read aloud",
+      "Visible text beats hidden text whenever there is room"
     ],
     "accessibility": [
-      "Content is announced by screen readers",
-      "Content is focusable if interactive elements are inside",
-      "Essential for WCAG 2.1 compliance with icon-only controls",
-      "Must convey equivalent information to visual content"
+      "Screen readers announce it; the layout never moves",
+      "Focusable children inside still receive focus",
+      "Required for WCAG 2.1 on icon-only controls"
     ]
   },
   "examples": [
     {
       "name": "Icon Button Label",
-      "description": "Accessible label for icon-only button",
+      "description": "The only thing telling a screen reader what this button does.",
       "code": "<button style={{\n  display: 'inline-flex',\n  alignItems: 'center',\n  justifyContent: 'center',\n  width: '40px',\n  height: '40px',\n  border: '1px solid var(--fui-border-default)',\n  borderRadius: '8px',\n  background: 'var(--fui-color-surface-primary)',\n  cursor: 'pointer'\n}}>\n  <svg width=\"20\" height=\"20\" viewBox=\"0 0 24 24\" fill=\"none\" stroke=\"currentColor\" strokeWidth=\"2\">\n    <path d=\"M21 21l-6-6m2-5a7 7 0 11-14 0 7 7 0 0114 0z\" />\n  </svg>\n  <VisuallyHidden>Search</VisuallyHidden>\n</button>"
     },
     {
       "name": "Supplementary Text",
-      "description": "Additional context for screen readers",
+      "description": "Gives a vague link the context sighted readers get from layout.",
       "code": "<a href=\"#\" style={{ color: 'var(--fui-color-accent)' }}>\n  Read more\n  <VisuallyHidden> about our accessibility features</VisuallyHidden>\n</a>"
     },
     {
       "name": "Skip Link",
-      "description": "Navigation aid that becomes visible on focus",
+      "description": "Hidden until focused, then it jumps keyboard users past the nav.",
       "code": "<div>\n  <VisuallyHidden as=\"div\">\n    <a\n      href=\"#main-content\"\n      style={{\n        position: 'absolute',\n        padding: '8px 16px',\n        background: 'var(--fui-color-accent)',\n        color: 'white'\n      }}\n    >\n      Skip to main content\n    </a>\n  </VisuallyHidden>\n  <p style={{ color: 'var(--fui-color-text-tertiary)', fontSize: '14px' }}>\n    (Screen reader only: \"Skip to main content\" link)\n  </p>\n</div>"
     }
   ],
@@ -96,16 +79,11 @@
       "as: span|div - HTML element",
       "Forwards standard DOM props (id, aria-*, data-*, className, handlers)"
     ],
-    "a11yRules": [
-      "A11Y_SR_ONLY",
-      "A11Y_ICON_LABEL"
-    ]
+    "a11yRules": ["A11Y_SR_ONLY", "A11Y_ICON_LABEL"]
   },
   "ai": {
     "compositionPattern": "compound",
-    "subComponents": [
-      "Root"
-    ]
+    "subComponents": ["Root"]
   },
   "provenance": {
     "source": "migrated",

package/src/components/VisuallyHidden/VisuallyHidden.module.scss

@@ -1,16 +1,6 @@
-// Screen reader only - hides content visually but keeps it accessible
-// Based on the widely-used sr-only pattern
+@use "../../tokens/mixins" as *;
+
+// Screen reader only - hides content visually but keeps it accessible.
 .visuallyHidden {
-  position: absolute;
-  /* fragments-allow FUI2004 reason="Accessibility clipping box must remain exactly one CSS pixel" expires="2027-08-01" */
-  width: 1px;
-  /* fragments-allow FUI2004 reason="Accessibility clipping box must remain exactly one CSS pixel" expires="2027-08-01" */
-  height: 1px;
-  padding: 0;
-  /* fragments-allow FUI2004 reason="Negative offset keeps the clipping box outside visual layout" expires="2027-08-01" */
-  margin: -1px;
-  overflow: hidden;
-  clip: rect(0, 0, 0, 0);
-  white-space: nowrap;
-  border-width: 0;
+  @include visually-hidden;
 }

package/src/components/VisuallyHidden/index.tsx

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

package/src/index.ts

@@ -41,7 +41,7 @@ export {
   AlertAction,
   AlertClose,
   type AlertProps,
-  type AlertSeverity,
+  type AlertTone,
   type AlertIconProps,
   type AlertBodyProps,
   type AlertTitleProps,
@@ -50,7 +50,7 @@ export {
   type AlertActionProps,
   type AlertCloseProps,
 } from "./components/Alert";
-export { Badge, type BadgeProps } from "./components/Badge";
+export { Badge, type BadgeProps, type BadgeTone, type BadgeVariant } from "./components/Badge";
 export { IconButton, type IconButtonProps } from "./components/IconButton";
 export {
   ComponentDefaultsProvider,
@@ -216,7 +216,7 @@ export {
   Skeleton,
   type SkeletonProps,
   type SkeletonTextProps,
-  type SkeletonVariant,
+  type SkeletonShape,
   type SkeletonSize,
 } from "./components/Skeleton";
 
@@ -228,7 +228,7 @@ export {
   LoadingScreen,
   type LoadingProps,
   type LoadingSize,
-  type LoadingVariant,
+  type LoadingKind,
   type LoadingInlineProps,
   type LoadingScreenProps,
 } from "./components/Loading";
@@ -289,7 +289,7 @@ export {
   type ToastProps,
   type ToastProviderProps,
   type ToastData,
-  type ToastVariant,
+  type ToastTone,
   type ToastPosition,
 } from "./components/Toast";
 
@@ -344,15 +344,16 @@ export {
   Theme,
   ThemeProvider,
   ThemeToggle,
+  ThemeButton,
   useTheme,
   configureTheme,
   type ThemeProviderProps,
   type ThemeToggleProps,
+  type ThemeButtonProps,
   type ThemeMode,
   type UseThemeReturn,
   type ConfigureThemeOptions,
   type NeutralPalette,
-  type DensityPreset,
   type RadiusStyle,
 } from "./components/Theme";
 
@@ -559,7 +560,7 @@ export {
   ThinkingStep,
   useThinkingIndicatorContext,
   type ThinkingIndicatorProps,
-  type ThinkingVariant,
+  type ThinkingKind,
   type ThinkingStep as ThinkingStepType,
   type StepStatus,
   type ThinkingStepsProps,
@@ -584,6 +585,12 @@ export {
 // Assets
 export { FragmentsLogo, fragmentsLogoSvg, type FragmentsLogoProps } from "./assets/fragments-logo";
 export { FragmentsWordmark, type FragmentsWordmarkProps } from "./assets/fragments-wordmark";
+export {
+  NavGlyph,
+  NAV_GLYPH_NAMES,
+  type NavGlyphName,
+  type NavGlyphProps,
+} from "./assets/nav-glyph";
 
 // NavigationMenu
 export {
@@ -678,8 +685,8 @@ export {
   usePrefersContrast,
   useFocusTrap,
   handleArrowNavigation,
-  VisuallyHidden as A11yVisuallyHidden,
-  type VisuallyHiddenProps as A11yVisuallyHiddenProps,
+  A11yVisuallyHidden,
+  type A11yVisuallyHiddenProps,
 } from "./utils/a11y";
 
 // Keyboard Shortcuts
@@ -728,6 +735,3 @@ export {
   type ThemeConfig,
   type PresetDefinition,
 } from "./utils/theme-presets";
-
-// Legacy aliases (deprecated)
-export { Switch as Toggle, type SwitchProps as ToggleProps } from "./components/Switch";

package/src/measurements/MeasurementTargets.module.scss

@@ -30,21 +30,20 @@
 }
 
 .eyebrow {
-  margin: 0;
+  margin: var(--fui-raw-space-0, #{measurements.raw-space(0)});
   color: var(--fui-text-tertiary, #{tokens.$fui-text-tertiary});
-  text-transform: uppercase;
 }
 
 .title {
   @include typography.role("title-lg");
 
-  margin: 0;
+  margin: var(--fui-raw-space-0, #{measurements.raw-space(0)});
 }
 
 .description {
   @include typography.role("body-compact");
 
-  margin: 0;
+  margin: var(--fui-raw-space-0, #{measurements.raw-space(0)});
   color: var(--fui-text-secondary, #{tokens.$fui-text-secondary});
 }
 
@@ -78,7 +77,7 @@
 .sectionTitle {
   @include typography.role("title-sm");
 
-  margin: 0;
+  margin: var(--fui-raw-space-0, #{measurements.raw-space(0)});
 }
 
 .specimenList {
@@ -99,7 +98,7 @@
 
 .specimenName,
 .specimenValue {
-  margin: 0;
+  margin: var(--fui-raw-space-0, #{measurements.raw-space(0)});
 }
 
 .specimenName {
@@ -188,7 +187,7 @@
 }
 
 .typographySample {
-  margin: 0;
+  margin: var(--fui-raw-space-0, #{measurements.raw-space(0)});
   overflow-wrap: anywhere;
 }
 

package/src/measurements/generated.ts

@@ -1,98 +1,30 @@
 // This file is generated by scripts/generate-measurements.mjs. Do not edit.
-// Source SHA-256: 1e8a256c12eaf2f8f4a2a5c4ed25477bf303b56dc2184ac3e29dec71207853bd
+// Source SHA-256: 2783cbbef495c746894385914699542d96008deb952c3f3ab6adf84bf3fac80d
 
 export const MEASUREMENT_PROFILES = {
-  density: {
-    compact: {
-      baseUnit: "6px",
-      baseFontSize: "14px",
-      spacingMultipliers: {
-        "1": 1,
-        "2": 2,
-        "3": 3,
-        "4": 4,
-        "5": 5,
-        "6": 6,
-        "8": 8,
-        "10": 10,
-        "12": 12,
-        px: "1px",
-        "0-5": 0.3,
-        "0-75": 0.43,
-      },
-      controlHeight: {
-        xs: "32px",
-        sm: "32px",
-        md: "32px",
-        lg: "36px",
-      },
-      touch: {
-        sm: "32px",
-        md: "32px",
-        lg: "40px",
-      },
-      sidebarItemHeight: "32px",
+  spacing: {
+    baseUnit: "7px",
+    baseFontSize: "14px",
+    multipliers: {
+      "1": 1,
+      "2": 2,
+      "3": 3,
+      "4": 4,
+      "5": 5,
+      "6": 6,
+      "8": 8,
+      "10": 10,
+      "12": 12,
+      px: "1px",
+      "0-5": 0.3,
+      "0-75": 0.43,
     },
-    default: {
-      baseUnit: "7px",
-      baseFontSize: "14px",
-      spacingMultipliers: {
-        "1": 1,
-        "2": 2,
-        "3": 3,
-        "4": 4,
-        "5": 5,
-        "6": 6,
-        "8": 8,
-        "10": 10,
-        "12": 12,
-        px: "1px",
-        "0-5": 0.3,
-        "0-75": 0.43,
-      },
-      controlHeight: {
-        xs: "32px",
-        sm: "32px",
-        md: "40px",
-        lg: "44px",
-      },
-      touch: {
-        sm: "32px",
-        md: "32px",
-        lg: "44px",
-      },
-      sidebarItemHeight: "32px",
-    },
-    relaxed: {
-      baseUnit: "8px",
-      baseFontSize: "14px",
-      spacingMultipliers: {
-        "1": 1,
-        "2": 2,
-        "3": 3,
-        "4": 4,
-        "5": 5,
-        "6": 6,
-        "8": 8,
-        "10": 10,
-        "12": 12,
-        px: "1px",
-        "0-5": 0.3,
-        "0-75": 0.43,
-      },
-      controlHeight: {
-        xs: "32px",
-        sm: "32px",
-        md: "44px",
-        lg: "48px",
-      },
-      touch: {
-        sm: "32px",
-        md: "40px",
-        lg: "48px",
-      },
-      sidebarItemHeight: "36px",
+    touch: {
+      sm: "32px",
+      md: "32px",
+      lg: "44px",
     },
+    sidebarItemHeight: "32px",
   },
   radius: {
     sharp: {
@@ -182,10 +114,26 @@ export const MEASUREMENT_PROFILES = {
       "field-minimum": "140px",
       "inline-floor": "56px",
       "compact-content": "168px",
+      "menu-min": "192px",
       "grid-cell": "224px",
       "composer-item": "210px",
       "page-narrow": "800px",
     },
+    overlay: {
+      "popover-min": "192px",
+      "popover-sm": "256px",
+      "popover-md": "384px",
+      "popover-lg": "512px",
+      "tooltip-max": "320px",
+      "dialog-sm": "384px",
+      "dialog-md": "448px",
+      "dialog-lg": "576px",
+      "dialog-xl": "768px",
+      "drawer-sm": "320px",
+      "drawer-md": "384px",
+      "drawer-lg": "512px",
+      "drawer-xl": "768px",
+    },
   },
   typography: {
     caption: {
@@ -218,6 +166,12 @@ export const MEASUREMENT_PROFILES = {
       weight: 400,
       tracking: "0",
     },
+    display: {
+      size: "32px",
+      line: "40px",
+      weight: 600,
+      tracking: "-0.02em",
+    },
     "title-sm": {
       size: "16px",
       line: "24px",
@@ -254,11 +208,9 @@ export const MEASUREMENT_PROFILES = {
   },
 } as const;
 
-export type MeasurementDensity = keyof typeof MEASUREMENT_PROFILES.density;
 export type MeasurementRadiusStyle = keyof typeof MEASUREMENT_PROFILES.radius;
 
 export type MeasurementSelection = Readonly<{
-  density?: MeasurementDensity;
   radiusStyle?: MeasurementRadiusStyle;
 }>;
 
@@ -273,7 +225,7 @@ export function measurementPx(value: string, path = "measurement"): number {
   return pixels;
 }
 
-type MeasurementAttribute = "data-fui-density" | "data-fui-radius-style";
+type MeasurementAttribute = "data-fui-radius-style";
 
 function setRestorableAttribute(
   element: HTMLElement,
@@ -299,9 +251,6 @@ export function applyMeasurementSelection(
 ): () => void {
   const restore: Array<() => void> = [];
 
-  if (selection.density !== undefined) {
-    restore.push(setRestorableAttribute(element, "data-fui-density", selection.density));
-  }
   if (selection.radiusStyle !== undefined) {
     restore.push(setRestorableAttribute(element, "data-fui-radius-style", selection.radiusStyle));
   }
@@ -311,7 +260,7 @@ export function applyMeasurementSelection(
     if (cleaned) return;
     cleaned = true;
     for (let index = restore.length - 1; index >= 0; index -= 1) {
-      restore[index]();
+      restore[index]?.();
     }
   };
 }

package/src/measurements/index.ts

@@ -2,7 +2,6 @@ export {
   MEASUREMENT_PROFILES,
   applyMeasurementSelection,
   measurementPx,
-  type MeasurementDensity,
   type MeasurementRadiusStyle,
   type MeasurementSelection,
 } from "./generated";