@usefragments/ui 1.6.0 → 1.7.0

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/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/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

@@ -678,8 +678,8 @@ export {
   usePrefersContrast,
   useFocusTrap,
   handleArrowNavigation,
-  VisuallyHidden as A11yVisuallyHidden,
-  type VisuallyHiddenProps as A11yVisuallyHiddenProps,
+  A11yVisuallyHidden,
+  type A11yVisuallyHiddenProps,
 } from "./utils/a11y";
 
 // Keyboard Shortcuts

package/src/measurements/generated.ts

@@ -1,5 +1,5 @@
 // This file is generated by scripts/generate-measurements.mjs. Do not edit.
-// Source SHA-256: 1e8a256c12eaf2f8f4a2a5c4ed25477bf303b56dc2184ac3e29dec71207853bd
+// Source SHA-256: deb4b375de296c627460bd2d99618182ae0fa21768c26b2037d549cd84a7a0c8
 
 export const MEASUREMENT_PROFILES = {
   density: {
@@ -182,6 +182,7 @@ 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",
@@ -218,6 +219,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",
@@ -311,7 +318,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/measurements.json

@@ -181,6 +181,7 @@
       "field-minimum": "140px",
       "inline-floor": "56px",
       "compact-content": "168px",
+      "menu-min": "192px",
       "grid-cell": "224px",
       "composer-item": "210px",
       "page-narrow": "800px"
@@ -217,6 +218,12 @@
       "weight": 400,
       "tracking": "0"
     },
+    "display": {
+      "size": "32px",
+      "line": "40px",
+      "weight": 600,
+      "tracking": "-0.02em"
+    },
     "title-sm": {
       "size": "16px",
       "line": "24px",

package/src/recipes/_boolean-range.scss

@@ -32,10 +32,7 @@
 
 @function switch-inline-size($size) {
   @if $size == "sm" or $size == "md" or $size == "lg" {
-    @return var(
-      --fui-control-track-#{$size},
-      #{measurements.target-value("controlTrack", $size)}
-    );
+    @return var(--fui-control-track-#{$size}, #{measurements.target-value("controlTrack", $size)});
   }
 
   @error "Unknown boolean size '#{$size}'. Expected sm, md, or lg.";
@@ -102,13 +99,8 @@
   --_fui-switch-inline-size: #{switch-inline-size($size)};
   --_fui-switch-block-size: #{switch-block-size($size)};
   --_fui-switch-thumb-size: #{switch-thumb-size($size)};
-  --_fui-switch-inset: var(
-    --fui-stroke-default,
-    #{measurements.target-value("stroke", "default")}
-  );
-  --_fui-switch-travel: calc(
-    var(--_fui-switch-inline-size) - var(--_fui-switch-block-size)
-  );
+  --_fui-switch-inset: var(--fui-stroke-default, #{measurements.target-value("stroke", "default")});
+  --_fui-switch-travel: calc(var(--_fui-switch-inline-size) - var(--_fui-switch-block-size));
 
   inline-size: var(--_fui-switch-inline-size);
   block-size: var(--_fui-switch-block-size);

package/src/recipes/_field.scss

@@ -80,7 +80,11 @@
 @mixin focus-state {
   border-color: var(--fui-color-accent, #{tokens.$fui-color-accent});
   outline: var(--fui-focus-ring-width, #{tokens.$fui-focus-ring-width}) solid
-    color-mix(in srgb, var(--fui-focus-ring-color, #{tokens.$fui-focus-ring-color}) 34%, transparent);
+    color-mix(
+      in srgb,
+      var(--fui-focus-ring-color, #{tokens.$fui-focus-ring-color}) 34%,
+      transparent
+    );
   outline-offset: var(--fui-focus-ring-offset, #{tokens.$fui-focus-ring-offset});
 }
 

package/src/recipes/_layout.scss

@@ -49,13 +49,20 @@
 }
 
 @function measure($role) {
-  @if
-    $role == "field-minimum" or
-    $role == "inline-floor" or
-    $role == "compact-content" or
-    $role == "grid-cell" or
-    $role == "composer-item" or
-    $role == "page-narrow"
+  @if $role ==
+    "field-minimum" or
+    $role ==
+    "inline-floor" or
+    $role ==
+    "compact-content" or
+    $role ==
+    "menu-min" or
+    $role ==
+    "grid-cell" or
+    $role ==
+    "composer-item" or
+    $role ==
+    "page-narrow"
   {
     @return var(
       --fui-layout-measure-#{$role},

package/src/recipes/_popup.scss

@@ -8,7 +8,10 @@
   --fui-popup-row-block-inset: var(--fui-raw-space-8, #{measurements.raw-space(8)});
   --fui-popup-row-inline-inset: var(--fui-raw-space-8, #{measurements.raw-space(8)});
   --fui-popup-row-content-gap: var(--fui-raw-space-8, #{measurements.raw-space(8)});
-  --fui-popup-row-gap: var(--fui-stroke-hairline, #{measurements.target-value("stroke", "hairline")});
+  --fui-popup-row-gap: var(
+    --fui-stroke-hairline,
+    #{measurements.target-value("stroke", "hairline")}
+  );
   --fui-popup-indicator-box: var(--fui-raw-space-16, #{measurements.raw-space(16)});
   --fui-popup-separator-size: var(
     --fui-stroke-hairline,
@@ -52,6 +55,10 @@
   @include typography.role("ui-compact");
 
   box-sizing: border-box;
+  // Rows are pick targets: rapid pointer travel must never start a text
+  // selection, and touch taps get no highlight flash.
+  user-select: none;
+  -webkit-tap-highlight-color: transparent;
   display: flex;
   align-items: center;
   min-block-size: var(--_fui-popup-effective-row-pitch);
@@ -65,7 +72,10 @@
 }
 
 @mixin selected-state {
-  background: var(--fui-bg-active, #{tokens.$fui-bg-active});
+  background: var(
+    --fui-field-selection-bg,
+    var(--fui-control-selected-bg, #{tokens.$fui-bg-active})
+  );
   color: var(--fui-text-primary, #{tokens.$fui-text-primary});
 }
 

package/src/recipes/_prose.scss

@@ -1,5 +1,9 @@
+@use "../tokens/mixins" as mixins;
 @use "typography" as typography;
 
+// Block rhythm is owned by the container (owl selectors below). The element
+// mixins reset inline margins only, so a `.x p { @include paragraph }` rule
+// (specificity 0,1,1) cannot out-rank the owl (0,1,0) and glue the flow.
 @mixin root {
   @include typography.role("body-relaxed");
 
@@ -19,7 +23,7 @@
 @mixin paragraph {
   @include typography.role("body-relaxed");
 
-  margin: 0;
+  margin-inline: 0;
 }
 
 @mixin heading($level) {
@@ -35,7 +39,7 @@
     @error "Unknown prose heading '#{$level}'. Expected 1 through 6.";
   }
 
-  margin: 0;
+  margin-inline: 0;
 }
 
 @mixin list($kind) {
@@ -152,12 +156,16 @@
 @mixin link {
   color: inherit;
   text-decoration: underline;
-  text-underline-offset: var(--fui-raw-space-2);
+  // Em offset scales with the inherited font size (prose links render at
+  // several sizes); matches the Link component's hover/dotted variants.
+  text-underline-offset: 0.2em;
   overflow-wrap: anywhere;
 
   &:focus-visible {
-    outline: var(--fui-stroke-default) solid var(--fui-focus-ring);
-    outline-offset: var(--fui-stroke-default);
+    // The previous hand-rolled outline referenced --fui-focus-ring, which is
+    // never defined — the whole declaration was invalid and prose links had
+    // no visible ring at all.
+    @include mixins.focus-ring;
   }
 }