@usefragments/ui 1.5.4 → 1.7.0

package/src/components/Select/Select.module.scss

@@ -1,23 +1,40 @@
 @use "../../tokens/variables" as *;
 @use "../../tokens/mixins" as *;
+@use "../../recipes/action";
+@use "../../recipes/field";
+@use "../../recipes/layout";
+@use "../../recipes/popup";
 
-// Form field wrapper (label + helper + error)
-@include form-field-wrapper;
+.wrapper {
+  @include field.wrapper;
+}
+
+.label {
+  @include field.label;
+}
+
+.helper {
+  @include field.helper;
+}
+
+.helperError,
+.errorMessage {
+  @include field.error;
+}
 
 // Trigger button
 .trigger {
   @include button-reset;
   @include interactive-base;
-  @include text-base;
-  @include field-shell;
-  @include control-size("md", "input");
+  @include field.size("md");
+  @include field.shell;
 
   display: inline-flex;
   align-items: center;
   justify-content: space-between;
-  gap: var(--fui-space-2, $fui-space-2);
+  gap: action.gap("md");
   width: 100%;
-  min-width: 10rem;
+  min-width: layout.measure("field-minimum");
   text-align: left;
 
   &[data-popup-open] {
@@ -27,11 +44,15 @@
 
 // Trigger size variants
 .triggerSm {
-  @include control-size("sm", "input");
+  @include field.size("sm");
+
+  gap: action.gap("sm");
 }
 
 .triggerLg {
-  @include control-size("lg", "input");
+  @include field.size("lg");
+
+  gap: action.gap("lg");
 }
 
 // Ghost trigger — the same control with the field shell taken off, for
@@ -45,20 +66,11 @@
 .triggerGhost {
   width: auto;
   min-width: 0;
-  // No block padding: the control is exactly the target size tall and centres
-  // its own contents, the way a button does. Padding here instead would add to
-  // the line box and leave a ghost taller than every other control in the row
-  // — and taller again wherever the surface has scaled the target down.
-  height: auto;
-  gap: var(--fui-space-1, $fui-space-1);
-  padding: 0 var(--fui-space-2, $fui-space-2);
   border: none;
   border-radius: var(--fui-radius-md, $fui-radius-md);
   background-color: transparent;
   box-shadow: none;
   color: var(--fui-text-secondary, $fui-text-secondary);
-  font-size: var(--fui-font-size-xs, $fui-font-size-xs);
-  font-weight: var(--fui-font-weight-medium, $fui-font-weight-medium);
 
   &:hover:not(:disabled):not([data-disabled]) {
     background-color: var(--fui-bg-hover, $fui-bg-hover);
@@ -73,7 +85,7 @@
   // it owns is on screen.
   &[data-popup-open] {
     border-color: transparent;
-    background-color: var(--fui-bg-tertiary, $fui-bg-tertiary);
+    background-color: var(--fui-control-selected-bg, $fui-bg-active);
     color: var(--fui-text-primary, $fui-text-primary);
   }
 
@@ -143,11 +155,18 @@
   }
 
   svg {
-    width: var(--fui-icon-sm, $fui-icon-sm);
-    height: var(--fui-icon-sm, $fui-icon-sm);
+    @include action.glyph("md");
   }
 }
 
+.triggerSm :is(.triggerIcon, .icon) svg {
+  @include action.glyph("sm");
+}
+
+.triggerLg :is(.triggerIcon, .icon) svg {
+  @include action.glyph("lg");
+}
+
 // Positioner — z-index must exceed Dialog positioner (51)
 .positioner {
   z-index: 52;
@@ -156,17 +175,10 @@
 
 // Popup container
 .popup {
-  @include surface-elevated;
-  @include popup-container;
-
-  @include popup-scroll-viewport;
+  @include popup.container;
+  @include popup.viewport;
 
-  border-color: var(--fui-form-group-border, $fui-border);
   min-width: var(--anchor-width);
-  // Show N items + half-peek scroll hint (default 4.5 items).
-  // !important needed to override Base UI's inline max-height: 100%
-  max-height: var(--_popup-scroll-max-h) !important;
-  overflow-y: auto !important;
 
   // Animation
   opacity: 0;
@@ -190,15 +202,15 @@
 
 // Individual option
 .item {
-  @include popup-item;
+  @include popup.row;
 
   // Base UI sets [data-highlighted] on pointer-hover AND keyboard nav → one indicator.
   &[data-highlighted] {
-    @include popup-item-highlight;
+    @include popup.highlight-state;
   }
 
   &[data-selected] {
-    @include popup-item-selected;
+    @include popup.selected-state;
 
     // Selected + active: stronger accent-tinted wash so it still reads as selected.
     &[data-highlighted] {
@@ -207,7 +219,7 @@
   }
 
   &[data-disabled] {
-    @include popup-item-disabled;
+    @include popup.disabled-state;
   }
 }
 
@@ -229,16 +241,16 @@
 
 // Group container
 .group {
-  &:not(:first-child) {
-    margin-top: var(--fui-space-1, $fui-space-1);
-    padding-top: var(--fui-space-1, $fui-space-1);
-    border-top: 1px solid var(--fui-border, $fui-border);
+  &:not(:first-child)::before {
+    content: "";
+    display: block;
+    @include popup.group-separator;
   }
 }
 
 // Group label
 .groupLabel {
-  @include popup-group-label;
+  @include popup.group-label;
 }
 
 // ============================================
@@ -247,7 +259,7 @@
 
 @media (prefers-contrast: more) {
   .trigger {
-    border-width: 2px;
+    border-width: var(--fui-stroke-default, 2px);
     border-color: var(--fui-text-primary, $fui-text-primary);
 
     &[data-popup-open] {
@@ -276,11 +288,11 @@
 
 // Arrow
 .arrow {
-  width: 10px;
-  height: 10px;
+  width: var(--fui-raw-space-10, 10px);
+  height: var(--fui-raw-space-10, 10px);
   transform: rotate(45deg);
   background-color: var(--fui-bg-elevated, $fui-bg-elevated);
-  border: 1px solid var(--fui-border, $fui-border);
+  border: var(--fui-stroke-hairline, 1px) solid var(--fui-border, $fui-border);
 
   &[data-side="top"] {
     border-top: none;

package/src/components/Select/index.tsx

@@ -4,6 +4,10 @@ import * as React from "react";
 import { Select as BaseSelect } from "@base-ui/react/select";
 import { useResolvedControlSize } from "../ComponentDefaults";
 import { mergeAriaIds, useFormFieldIds, type FormFieldProps } from "../../utils/aria";
+import {
+  POPUP_OFFSET_PX,
+  resolvePopupViewportRows,
+} from "../../recipes/popup";
 import styles from "./Select.module.scss";
 
 // ============================================
@@ -440,7 +444,7 @@ function SelectTrigger({
 function SelectContent({
   children,
   className,
-  sideOffset = 4,
+  sideOffset = POPUP_OFFSET_PX,
   align = "start",
   maxVisibleItems,
   ...htmlProps
@@ -451,7 +455,7 @@ function SelectContent({
   const popupStyle =
     maxVisibleItems != null
       ? ({
-          "--fui-select-max-items": maxVisibleItems + 0.5,
+          "--fui-popup-viewport-rows": resolvePopupViewportRows(maxVisibleItems),
           ...htmlProps.style,
         } as React.CSSProperties)
       : htmlProps.style;

package/src/components/Separator/Separator.contract.json

@@ -1,15 +1,9 @@
 {
   "$schema": "https://usefragments.com/schemas/contract.v1.json",
   "name": "Separator",
-  "description": "Visual divider between content sections. Use to create clear visual boundaries and improve content organization.",
+  "description": "Draws a rule between sections of related content.",
   "category": "layout",
-  "tags": [
-    "separator",
-    "divider",
-    "hr",
-    "line",
-    "layout"
-  ],
+  "tags": ["separator", "divider", "hr", "line", "layout"],
   "status": "stable",
   "sourcePath": "src/components/Separator/index.tsx",
   "exportName": "Separator",
@@ -26,22 +20,14 @@
       "description": "Direction of the separator",
       "default": "horizontal",
       "required": false,
-      "values": [
-        "horizontal",
-        "vertical"
-      ]
+      "values": ["horizontal", "vertical"]
     },
     "spacing": {
       "type": "enum",
       "description": "Margin around the separator",
       "default": "none",
       "required": false,
-      "values": [
-        "none",
-        "sm",
-        "md",
-        "lg"
-      ]
+      "values": ["none", "sm", "md", "lg"]
     },
     "soft": {
       "type": "boolean",
@@ -62,21 +48,20 @@
   },
   "usage": {
     "when": [
-      "Dividing content sections",
-      "Separating groups of related items",
-      "Creating visual breathing room",
-      "Labeled section breaks"
+      "Dividing sections that spacing alone cannot separate",
+      "Labelled breaks such as an Or divider",
+      "Splitting items inside a toolbar or row"
     ],
     "whenNot": [
-      "Creating grid layouts (use CSS Grid)",
-      "Decorative borders (use CSS)",
-      "Spacing alone is sufficient"
+      "Whenever spacing already reads as a break",
+      "Decorative rules (use a border)",
+      "Building layout structure (use Grid)"
     ],
     "guidelines": [
-      "Use sparingly - too many separators create visual noise",
-      "Consider if spacing alone would work",
-      "Use soft variant for subtle separation",
-      "Labeled separators work well for major section breaks"
+      "Use sparingly — stacked rules read as noise",
+      "soft halves the rule's weight for quieter breaks",
+      "orientation=\"vertical\" needs a parent with a set height",
+      "Add aria-hidden when the rule is purely decorative"
     ],
     "accessibility": [
       "Uses role=\"separator\" for semantic meaning",
@@ -86,28 +71,23 @@
   "examples": [
     {
       "name": "Default",
-      "description": "Basic horizontal separator",
-      "code": "<div style={{ width: '300px' }}>\n  <p>Content above</p>\n  <Separator spacing=\"md\" />\n  <p>Content below</p>\n</div>"
+      "description": "Standard and soft weights, one above the other.",
+      "code": "import { Box } from '@/components/Box';\nimport { Separator } from '@/components/Separator';\nimport { Text } from '@/components/Text';\n\n<Box width=\"100%\">\n  <Text>Standard weight</Text>\n  <Separator spacing=\"md\" />\n  <Text>Soft weight</Text>\n  <Separator soft spacing=\"md\" />\n  <Text>Below</Text>\n</Box>"
     },
     {
       "name": "With Label",
-      "description": "Labeled section divider",
-      "code": "<div style={{ width: '300px' }}>\n  <p>First section</p>\n  <Separator label=\"Or\" spacing=\"md\" />\n  <p>Second section</p>\n</div>"
-    },
-    {
-      "name": "Soft",
-      "description": "Subtle separator",
-      "code": "<div style={{ width: '300px' }}>\n  <p>Content above</p>\n  <Separator soft spacing=\"md\" />\n  <p>Content below</p>\n</div>"
+      "description": "A label sits inside the rule for a major break.",
+      "code": "import { Box } from '@/components/Box';\nimport { Separator } from '@/components/Separator';\nimport { Text } from '@/components/Text';\n\n<Box width=\"100%\">\n  <Text>First section</Text>\n  <Separator label=\"Or\" spacing=\"md\" />\n  <Text>Second section</Text>\n</Box>"
     },
     {
       "name": "Vertical",
-      "description": "Vertical separator between elements",
-      "code": "<div style={{ display: 'flex', alignItems: 'center', gap: '16px', height: '40px' }}>\n  <span>Item 1</span>\n  <Separator orientation=\"vertical\" />\n  <span>Item 2</span>\n  <Separator orientation=\"vertical\" />\n  <span>Item 3</span>\n</div>"
+      "description": "Divides items sitting in a row.",
+      "code": "import { Box } from '@/components/Box';\nimport { Separator } from '@/components/Separator';\nimport { Stack } from '@/components/Stack';\nimport { Text } from '@/components/Text';\n\n<Stack direction=\"row\" align=\"center\" gap=\"md\" style={{ height: '40px' }}>\n  <Text>Item 1</Text>\n  <Separator orientation=\"vertical\" />\n  <Text>Item 2</Text>\n  <Separator orientation=\"vertical\" />\n  <Text>Item 3</Text>\n</Stack>"
     },
     {
       "name": "Spacing Options",
-      "description": "Different spacing sizes",
-      "code": "<div style={{ width: '300px' }}>\n  <p>No spacing</p>\n  <Separator spacing=\"none\" />\n  <p>Small spacing</p>\n  <Separator spacing=\"sm\" />\n  <p>Medium spacing</p>\n  <Separator spacing=\"md\" />\n  <p>Large spacing</p>\n  <Separator spacing=\"lg\" />\n  <p>End</p>\n</div>"
+      "description": "spacing sets the breathing room around the rule.",
+      "code": "import { Box } from '@/components/Box';\nimport { Separator } from '@/components/Separator';\nimport { Text } from '@/components/Text';\n\n<Box width=\"100%\">\n  <Text>none</Text>\n  <Separator spacing=\"none\" />\n  <Text>sm</Text>\n  <Separator spacing=\"sm\" />\n  <Text>md</Text>\n  <Separator spacing=\"md\" />\n  <Text>lg</Text>\n  <Separator spacing=\"lg\" />\n  <Text>End</Text>\n</Box>"
     }
   ],
   "relations": [
@@ -124,15 +104,11 @@
       "soft: boolean - lighter appearance",
       "label: string - centered label text"
     ],
-    "a11yRules": [
-      "A11Y_SEPARATOR_ROLE"
-    ]
+    "a11yRules": ["A11Y_SEPARATOR_ROLE"]
   },
   "ai": {
     "compositionPattern": "compound",
-    "subComponents": [
-      "Root"
-    ]
+    "subComponents": ["Root"]
   },
   "provenance": {
     "source": "migrated",

package/src/components/Separator/Separator.module.scss

@@ -1,22 +1,35 @@
-@use '../../tokens/variables' as *;
-@use '../../tokens/mixins' as *;
+@use "../../recipes/layout";
+@use "../../recipes/typography";
+@use "../../tokens/variables" as *;
 
 .separator {
   flex-shrink: 0;
-  background-color: var(--fui-border, $fui-border);
+  background-color: transparent;
 }
 
 // Horizontal (default)
 .horizontal {
   width: 100%;
-  height: 1px;
+
+  .line {
+    display: block;
+    width: 100%;
+    height: var(--fui-stroke-hairline, 1px);
+    background-color: var(--fui-border, $fui-border);
+  }
 }
 
 // Vertical
 .vertical {
-  width: 1px;
   height: auto;
   align-self: stretch;
+
+  .line {
+    display: block;
+    width: var(--fui-stroke-hairline, 1px);
+    height: 100%;
+    background-color: var(--fui-border, $fui-border);
+  }
 }
 
 // With label
@@ -28,61 +41,58 @@
 
   &::before,
   &::after {
-    content: '';
+    content: "";
     flex: 1;
-    height: 1px;
+    height: var(--fui-stroke-hairline, 1px);
     background-color: var(--fui-border, $fui-border);
   }
 }
 
 .label {
-  font-family: var(--fui-font-sans, $fui-font-sans);
-  font-size: var(--fui-font-size-xs, $fui-font-size-xs);
-  font-weight: var(--fui-font-weight-medium, $fui-font-weight-medium);
+  @include typography.role("ui-compact");
+
   color: var(--fui-text-tertiary, $fui-text-tertiary);
   text-transform: uppercase;
-  letter-spacing: var(--fui-letter-spacing-wide, $fui-letter-spacing-wide);
   white-space: nowrap;
 }
 
 // Spacing variants
 .spacingNone {
-  margin: 0;
+  padding: 0;
 }
 
 .spacingSm {
   &.horizontal {
-    margin: var(--fui-space-2, $fui-space-2) 0;
+    padding-block: layout.gap("sm");
   }
 
   &.vertical {
-    margin: 0 var(--fui-space-2, $fui-space-2);
+    padding-inline: layout.gap("sm");
   }
 }
 
 .spacingMd {
   &.horizontal {
-    margin: var(--fui-space-4, $fui-space-4) 0;
+    padding-block: layout.gap("md");
   }
 
   &.vertical {
-    margin: 0 var(--fui-space-4, $fui-space-4);
+    padding-inline: layout.gap("md");
   }
 }
 
 .spacingLg {
   &.horizontal {
-    margin: var(--fui-space-6, $fui-space-6) 0;
+    padding-block: layout.gap("lg");
   }
 
   &.vertical {
-    margin: 0 var(--fui-space-6, $fui-space-6);
+    padding-inline: layout.gap("lg");
   }
 }
 
 // Soft variant (lighter color)
 .soft {
-  background-color: var(--fui-border, $fui-border);
   opacity: 0.5;
 
   &.withLabel::before,

package/src/components/Separator/index.tsx

@@ -1,18 +1,18 @@
-'use client';
+"use client";
 
-import * as React from 'react';
-import { Separator as BaseSeparator } from '@base-ui/react/separator';
-import styles from './Separator.module.scss';
+import * as React from "react";
+import { Separator as BaseSeparator } from "@base-ui/react/separator";
+import styles from "./Separator.module.scss";
 
 // ============================================
 // Types
 // ============================================
 
-export interface SeparatorProps extends Omit<React.HTMLAttributes<HTMLDivElement>, 'children'> {
+export interface SeparatorProps extends Omit<React.HTMLAttributes<HTMLDivElement>, "children"> {
   /** Orientation of the separator */
-  orientation?: 'horizontal' | 'vertical';
+  orientation?: "horizontal" | "vertical";
   /** Spacing around the separator */
-  spacing?: 'none' | 'sm' | 'md' | 'lg';
+  spacing?: "none" | "sm" | "md" | "lg";
   /** Softer visual appearance */
   soft?: boolean;
   /** Optional label text (creates a labeled divider) */
@@ -34,63 +34,67 @@ const spacingClasses = {
 // Component
 // ============================================
 
-const SeparatorRoot = React.forwardRef<HTMLDivElement, SeparatorProps>(
-  function Separator(
-    {
-      orientation = 'horizontal',
-      spacing = 'none',
-      soft = false,
-      label,
-      className,
-      style,
-      ...htmlProps
-    },
-    ref
-  ) {
-    // Labeled separator (horizontal only)
-    if (label && orientation === 'horizontal') {
-      const classes = [
-        styles.separator,
-        styles.withLabel,
-        spacingClasses[spacing],
-        soft && styles.soft,
-        className,
-      ].filter(Boolean).join(' ');
-
-      return (
-        <div
-          ref={ref}
-          role="separator"
-          aria-orientation="horizontal"
-          className={classes}
-          style={style}
-          {...htmlProps}
-        >
-          <span className={styles.label}>{label}</span>
-        </div>
-      );
-    }
-
-    // Standard separator
+const SeparatorRoot = React.forwardRef<HTMLDivElement, SeparatorProps>(function Separator(
+  {
+    orientation = "horizontal",
+    spacing = "none",
+    soft = false,
+    label,
+    className,
+    style,
+    ...htmlProps
+  },
+  ref
+) {
+  // Labeled separator (horizontal only)
+  if (label && orientation === "horizontal") {
     const classes = [
       styles.separator,
-      orientation === 'horizontal' ? styles.horizontal : styles.vertical,
+      styles.withLabel,
       spacingClasses[spacing],
       soft && styles.soft,
       className,
-    ].filter(Boolean).join(' ');
+    ]
+      .filter(Boolean)
+      .join(" ");
 
     return (
-      <BaseSeparator
+      <div
         ref={ref}
-        orientation={orientation}
+        role="separator"
+        aria-orientation="horizontal"
         className={classes}
         style={style}
         {...htmlProps}
-      />
+      >
+        <span className={styles.label}>{label}</span>
+      </div>
     );
   }
-);
+
+  // Standard separator
+  const classes = [
+    styles.separator,
+    orientation === "horizontal" ? styles.horizontal : styles.vertical,
+    spacingClasses[spacing],
+    soft && styles.soft,
+    className,
+  ]
+    .filter(Boolean)
+    .join(" ");
+
+  return (
+    <BaseSeparator
+      ref={ref}
+      orientation={orientation}
+      className={classes}
+      style={style}
+      {...htmlProps}
+    >
+      <span className={styles.line} aria-hidden="true" />
+    </BaseSeparator>
+  );
+});
 
 export const Separator = Object.assign(SeparatorRoot, {
   Root: SeparatorRoot,