@usefragments/ui 1.5.4 → 1.6.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@usefragments/ui",
-  "version": "1.5.4",
+  "version": "1.6.0",
   "license": "MIT",
   "description": "Customizable UI components built on Base UI headless primitives",
   "author": "Conan McNicholl",
@@ -29,6 +29,16 @@
         "default": "./dist/index.cjs"
       }
     },
+    "./measurements": {
+      "import": {
+        "types": "./dist/measurements/index.d.ts",
+        "default": "./dist/measurements.js"
+      },
+      "require": {
+        "types": "./dist/measurements/index.d.ts",
+        "default": "./dist/measurements.cjs"
+      }
+    },
     "./datepicker": {
       "import": {
         "types": "./dist/components/DatePicker/index.d.ts",
@@ -210,6 +220,9 @@
     "@phosphor-icons/react": "^2.1.10"
   },
   "devDependencies": {
+    "@fontsource-variable/inter": "5.2.8",
+    "@fontsource-variable/jetbrains-mono": "5.2.8",
+    "@playwright/test": "1.58.2",
     "@storybook/addon-a11y": "^8",
     "@storybook/addon-essentials": "^8",
     "@storybook/react": "^8",
@@ -226,6 +239,7 @@
     "@types/react": "^19.0.0",
     "@types/react-dom": "^19.0.0",
     "@vitejs/plugin-react": "^4.3.0",
+    "ajv": "8.17.1",
     "chromatic": "^17.1.0",
     "date-fns": "^4.0.0",
     "jsdom": "^25.0.0",
@@ -241,7 +255,7 @@
     "vite": "^6.0.0",
     "vitest": "^2.1.8",
     "vitest-axe": "^0.1.0",
-    "@usefragments/core": "1.10.1"
+    "@usefragments/core": "1.10.2"
   },
   "files": [
     "src",
@@ -262,9 +276,14 @@
   ],
   "scripts": {
     "dev": "storybook dev -p 6006",
-    "build": "vite build && node ./scripts/emit-complete-styles.mjs && tsc -p tsconfig.build.json",
-    "lint": "eslint src",
+    "generate:measurements": "node scripts/generate-measurements.mjs",
+    "check:measurements": "node scripts/generate-measurements.mjs --check && node scripts/check-measurement-parity.mjs",
+    "build": "pnpm run check:measurements && vite build && node ./scripts/emit-complete-styles.mjs && tsc -p tsconfig.build.json",
+    "lint": "eslint src geometry",
     "test": "vitest run",
+    "test:geometry": "node geometry/run.mjs",
+    "test:geometry:self": "node --test geometry/__tests__/*.test.mjs",
+    "test:geometry:types": "tsc -p geometry/tsconfig.json --noEmit",
     "build-storybook": "storybook build",
     "chromatic": "chromatic",
     "chromatic:ci": "chromatic --build-script-name build-storybook"

package/src/components/Accordion/Accordion.module.scss

@@ -1,14 +1,12 @@
 @use "../../tokens/variables" as *;
 @use "../../tokens/mixins" as *;
+@use "../../recipes/feedback" as feedback;
 
 .accordion {
-  font-family: var(--fui-font-sans, $fui-font-sans);
   width: 100%;
 
-  // Borders target direct children (BaseCollapsible.Root wrappers)
-  // so :first-child/:last-child selectors work correctly
   > * {
-    border-bottom: 1px solid var(--fui-border, $fui-border);
+    border-bottom: var(--fui-stroke-hairline, 1px) solid var(--fui-border, $fui-border);
 
     &:last-child {
       border-bottom: none;
@@ -16,48 +14,45 @@
   }
 }
 
-.item {
-  &[data-disabled] {
-    opacity: 0.5;
-    pointer-events: none;
-  }
+.item[data-disabled] {
+  opacity: 0.5;
+  pointer-events: none;
 }
 
-// Reset heading styles (semantic wrapper for trigger)
 .heading {
   margin: 0;
-  font-size: inherit;
-  font-weight: inherit;
+  font: inherit;
 }
 
 .trigger {
   @include button-reset;
   @include interactive-base;
+  @include feedback.disclosure-row;
 
-  display: flex;
-  align-items: center;
   justify-content: space-between;
-  width: 100%;
-  padding: var(--fui-space-2, $fui-space-2) 0;
-  font-size: var(--fui-font-size-sm, $fui-font-size-sm);
-  font-weight: var(--fui-font-weight-medium, $fui-font-weight-medium);
+  inline-size: 100%;
   color: var(--fui-text-primary, $fui-text-primary);
-  text-align: left;
+  text-align: start;
+
+  &:hover:not(:disabled) {
+    background-color: var(--fui-bg-hover, $fui-bg-hover);
+  }
 
   &:focus-visible {
     @include focus-ring;
+
     border-radius: var(--fui-radius-sm, $fui-radius-sm);
   }
 }
 
 .triggerContent {
   flex: 1;
+  min-inline-size: 0;
 }
 
 .chevron {
-  flex-shrink: 0;
-  width: var(--fui-icon-md, $fui-icon-md);
-  height: var(--fui-icon-md, $fui-icon-md);
+  @include feedback.disclosure-glyph;
+
   color: var(--fui-text-secondary, $fui-text-secondary);
   transition: transform var(--fui-transition-normal, $fui-transition-normal);
 
@@ -67,47 +62,31 @@
 }
 
 .content {
+  display: grid;
+  grid-template-rows: 0fr;
   overflow: hidden;
-
-  // Base UI Collapsible handles height animation via CSS
-  // We need to handle the collapsed state
-  &[data-state="closed"] {
-    height: 0;
-  }
+  opacity: 0;
+  transition:
+    grid-template-rows var(--fui-transition-normal, $fui-transition-normal),
+    opacity var(--fui-transition-normal, $fui-transition-normal);
 
   &[data-state="open"] {
-    height: auto;
-  }
-
-  // Smooth animation using Base UI's built-in transition
-  &[data-starting-style],
-  &[data-ending-style] {
-    transition:
-      height var(--fui-transition-normal, $fui-transition-normal),
-      padding var(--fui-transition-normal, $fui-transition-normal);
+    grid-template-rows: 1fr;
+    opacity: 1;
   }
 }
 
 .contentInner {
-  padding-bottom: var(--fui-space-1, $fui-space-1);
-  font-size: var(--fui-font-size-sm, $fui-font-size-sm);
+  @include feedback.disclosure-panel;
+
+  min-block-size: 0;
+  overflow: hidden;
   color: var(--fui-text-secondary, $fui-text-secondary);
-  line-height: var(--fui-line-height-normal, $fui-line-height-normal);
 }
 
-// ============================================
-// Accessibility: Reduced Motion
-// ============================================
-
 @media (prefers-reduced-motion: reduce) {
-  .chevron {
-    transition: none;
-  }
-
+  .chevron,
   .content {
-    &[data-starting-style],
-    &[data-ending-style] {
-      transition: none;
-    }
+    transition: none;
   }
 }

package/src/components/Alert/Alert.module.scss

@@ -1,67 +1,57 @@
 @use "../../tokens/variables" as *;
 @use "../../tokens/mixins" as *;
+@use "../../recipes/feedback" as feedback;
 
 .alert {
-  display: flex;
-  // Single-line alerts (icon + one line, no title) read best vertically
-  // centered. Multi-line alerts top-align instead — see `:has(.title)` below.
-  align-items: center;
-  gap: var(--fui-space-3, $fui-space-3);
-  padding: var(--fui-space-2, $fui-space-2) var(--fui-space-3, $fui-space-3);
-  border-radius: var(--fui-radius-lg, $fui-radius-lg);
-  font-family: var(--fui-font-sans, $fui-font-sans);
-  font-size: var(--fui-font-size-sm, $fui-font-size-sm);
-  line-height: var(--fui-line-height-normal, $fui-line-height-normal);
+  @include feedback.contextual;
+
+  border-radius: var(--fui-card-radius, var(--fui-radius-lg, $fui-radius-lg));
 }
 
-// With a title (title + description), the block is multi-line: top-align so
-// the icon and close sit with the first line rather than the block's centre.
 .alert:has(.title) {
   align-items: flex-start;
 }
 
-// Severity variants
 .info {
   background: var(--fui-color-info-bg, $fui-color-info-bg);
-  border: 1px solid var(--fui-color-info-border, $fui-color-info-border);
+  border: var(--fui-stroke-hairline, 1px) solid var(--fui-color-info-border, $fui-color-info-border);
   color: var(--fui-color-info-text, $fui-color-info-text);
 }
 
 .success {
   background: var(--fui-color-success-bg, $fui-color-success-bg);
-  border: 1px solid var(--fui-color-success-border, $fui-color-success-border);
+  border: var(--fui-stroke-hairline, 1px) solid
+    var(--fui-color-success-border, $fui-color-success-border);
   color: var(--fui-color-success-text, $fui-color-success-text);
 }
 
 .warning {
   background: var(--fui-color-warning-bg, $fui-color-warning-bg);
-  border: 1px solid var(--fui-color-warning-border, $fui-color-warning-border);
+  border: var(--fui-stroke-hairline, 1px) solid
+    var(--fui-color-warning-border, $fui-color-warning-border);
   color: var(--fui-color-warning-text, $fui-color-warning-text);
 }
 
 .error {
   background: var(--fui-color-danger-bg, $fui-color-danger-bg);
-  border: 1px solid var(--fui-color-danger-border, $fui-color-danger-border);
+  border: var(--fui-stroke-hairline, 1px) solid
+    var(--fui-color-danger-border, $fui-color-danger-border);
   color: var(--fui-color-danger-text, $fui-color-danger-text);
 }
 
 .icon {
+  @include feedback.icon;
+
   display: flex;
   align-items: center;
   justify-content: center;
-  width: $fui-icon-lg;
-  height: $fui-icon-lg;
   border-radius: 50%;
-  font-size: var(--fui-font-size-xs, $fui-font-size-xs);
-  font-weight: var(--fui-font-weight-semibold, $fui-font-weight-semibold);
-  flex-shrink: 0;
   color: var(--fui-text-inverse, $fui-text-inverse);
+  font: inherit;
 }
 
-// Only nudge the icon down to meet the first text line when the alert is
-// multi-line; centered single-line alerts need no offset.
 .alert:has(.title) .icon {
-  margin-top: var(--fui-space-px, $fui-space-px);
+  margin-block-start: var(--fui-stroke-hairline, 1px);
 }
 
 .info .icon {
@@ -81,41 +71,38 @@
 }
 
 .body {
+  display: grid;
   flex: 1;
-  min-width: 0;
+  gap: var(--fui-feedback-text-gap, var(--fui-raw-space-4, 4px));
+  min-inline-size: 0;
 }
 
 .title {
-  font-weight: var(--fui-font-weight-semibold, $fui-font-weight-semibold);
-  margin-bottom: var(--fui-space-0-5, $fui-space-0-5);
+  @include feedback.title;
 }
 
 .content {
+  @include feedback.body;
+
   opacity: 0.9;
 }
 
 .actions {
   display: flex;
   align-items: center;
-  gap: var(--fui-space-3, $fui-space-3);
+  gap: var(--fui-feedback-transient-gap, var(--fui-raw-space-8, 8px));
 }
 
 .close {
   @include button-reset;
   @include interactive-base;
-  @include min-target-size;
+  @include feedback.close;
 
-  display: inline-flex;
-  align-items: center;
-  justify-content: center;
-  padding: 0 var(--fui-space-1, $fui-space-1);
-  font-size: var(--fui-font-size-lg, $fui-font-size-lg);
+  margin-inline-start: auto;
+  border-radius: var(--fui-radius-sm, $fui-radius-sm);
   color: inherit;
-  opacity: 0.6;
   line-height: 1;
-  border-radius: var(--fui-radius-sm, $fui-radius-sm);
-  margin-left: auto;
-  flex-shrink: 0;
+  opacity: 0.6;
 
   &:hover {
     opacity: 1;
@@ -124,12 +111,9 @@
 
 .action {
   @include button-reset;
-  @include min-target-size;
+  @include feedback.compact-action;
 
-  display: inline-flex;
-  align-items: center;
-  font-weight: var(--fui-font-weight-semibold, $fui-font-weight-semibold);
-  font-size: var(--fui-font-size-xs, $fui-font-size-xs);
+  border-radius: var(--fui-radius-sm, $fui-radius-sm);
   color: inherit;
   text-decoration: underline;
 

package/src/components/AppShell/AppShell.module.scss

@@ -1,5 +1,6 @@
 @use "../../tokens/variables" as *;
 @use "../../tokens/mixins" as *;
+@use "../../recipes/navigation" as navigation;
 
 // ============================================
 // AppShell Root - CSS Grid Layout
@@ -10,6 +11,8 @@
 // Visual treatment (floating) is controlled per-slot via `variant` props.
 
 .root {
+  @include navigation.properties;
+
   display: grid;
   min-height: 100vh;
   min-height: 100dvh;
@@ -184,7 +187,7 @@
   margin: var(--fui-space-1, $fui-space-1) var(--fui-space-1, $fui-space-1)
     var(--fui-space-1, $fui-space-1) 0;
   padding: var(--fui-space-4, $fui-space-4);
-  border: 1px solid var(--fui-border, $fui-border);
+  border: var(--fui-stroke-hairline, 1px) solid var(--fui-border, $fui-border);
   border-radius: var(--fui-radius-xl, $fui-radius-xl);
   background-color: var(--fui-app-main-bg, var(--fui-main-bg, #{$fui-main-bg}));
   box-shadow: inset 0 1px 0
@@ -253,7 +256,7 @@
     position: static;
     width: 100%;
     height: auto;
-    border-top: 1px solid var(--fui-border, $fui-border);
+    border-top: var(--fui-stroke-hairline, 1px) solid var(--fui-border, $fui-border);
   }
 }
 
@@ -279,7 +282,7 @@
   );
   margin: var(--fui-space-1, $fui-space-1) var(--fui-space-1, $fui-space-1)
     var(--fui-space-1, $fui-space-1) 0;
-  border: 1px solid var(--fui-border, $fui-border);
+  border: var(--fui-stroke-hairline, 1px) solid var(--fui-border, $fui-border);
   border-radius: var(--fui-radius-xl, $fui-radius-xl);
   background-color: var(--fui-panel-bg, inherit);
   box-shadow: inset 0 1px 0

package/src/components/AppShell/index.tsx

@@ -71,7 +71,7 @@ export interface AppShellSidebarProps extends React.HTMLAttributes<HTMLDivElemen
   children: React.ReactNode;
   /** Width of expanded sidebar (default: '240px') */
   width?: string;
-  /** Width when collapsed (default: '64px') */
+  /** Width when collapsed (default: '56px') */
   collapsedWidth?: string;
   /** Collapse behavior */
   collapsible?: SidebarCollapsible;
@@ -79,6 +79,8 @@ export interface AppShellSidebarProps extends React.HTMLAttributes<HTMLDivElemen
   position?: "left" | "right";
   /** Default collapsed state */
   defaultCollapsed?: boolean;
+  /** Forwarded to Sidebar — where the active-item affordance paints */
+  activeIndicator?: "start" | "end";
   /** Visual treatment: `'floating'` blends sidebar with the shell background */
   variant?: AppShellSlotVariant;
   /** Background color override (accepts any CSS color value or token) */
@@ -156,7 +158,7 @@ const AppShellContext = React.createContext<AppShellContextValue>({
   structure: "default",
   headerHeight: "56px",
   sidebarWidth: "240px",
-  sidebarCollapsedWidth: "64px",
+  sidebarCollapsedWidth: "var(--fui-navigation-sidebar-collapsed-width, 56px)",
   asideWidth: "280px",
   asideVisible: false,
 });
@@ -204,7 +206,7 @@ function extractConfigFromChildren(children: React.ReactNode): ExtractedConfig {
   const config: ExtractedConfig = {
     headerHeight: "56px",
     sidebarWidth: "240px",
-    sidebarCollapsedWidth: "64px",
+    sidebarCollapsedWidth: "var(--fui-navigation-sidebar-collapsed-width, 56px)",
     sidebarCollapsible: "icon",
     sidebarDefaultCollapsed: false,
     asideWidth: "280px",
@@ -384,10 +386,11 @@ function AppShellHeader({
 function AppShellSidebar({
   children,
   width = "240px",
-  collapsedWidth = "64px",
+  collapsedWidth = "var(--fui-navigation-sidebar-collapsed-width, 56px)",
   collapsible = "icon",
   position = "left",
   defaultCollapsed = false,
+  activeIndicator = "start",
   variant,
   bg,
   "aria-label": ariaLabel,
@@ -420,6 +423,7 @@ function AppShellSidebar({
         position={position}
         collapsible={collapsible}
         defaultCollapsed={defaultCollapsed}
+        activeIndicator={activeIndicator}
         aria-label={ariaLabel}
         style={bg ? { backgroundColor: bg } : undefined}
       >

package/src/components/Avatar/Avatar.module.scss

@@ -1,4 +1,5 @@
-@use '../../tokens/variables' as *;
+@use "../../tokens/variables" as *;
+@use "../../recipes/representation" as representation;
 
 // ============================================
 // Avatar Component Styles
@@ -14,47 +15,22 @@
   border-radius: var(--fui-radius-full, $fui-radius-full);
   background-color: var(--fui-bg-tertiary, $fui-bg-tertiary);
   color: var(--fui-text-secondary, $fui-text-secondary);
-  font-family: var(--fui-font-sans, $fui-font-sans);
   user-select: none;
 }
 
-// Shape variant
-.square {
-  border-radius: var(--fui-radius-md, $fui-radius-md);
-}
-
 // ============================================
 // Size Variants
 // ============================================
 
-.xs {
-  width: 1.5rem;   // 24px
-  height: 1.5rem;
-  font-size: var(--fui-font-size-2xs, $fui-font-size-2xs);
-}
-
-.sm {
-  width: 2rem;     // 32px
-  height: 2rem;
-  font-size: var(--fui-font-size-xs, $fui-font-size-xs);
-}
-
-.md {
-  width: 2.5rem;   // 40px
-  height: 2.5rem;
-  font-size: var(--fui-font-size-sm, $fui-font-size-sm);
-}
-
-.lg {
-  width: 3rem;     // 48px
-  height: 3rem;
-  font-size: var(--fui-font-size-base, $fui-font-size-base);
+@each $size in ("xs", "sm", "md", "lg", "xl") {
+  .#{$size} {
+    @include representation.avatar($size);
+  }
 }
 
-.xl {
-  width: 4rem;     // 64px
-  height: 4rem;
-  font-size: var(--fui-font-size-lg, $fui-font-size-lg);
+// Shape is paint applied after the size recipe's circular default.
+.square {
+  border-radius: var(--fui-radius-md, $fui-radius-md);
 }
 
 // ============================================
@@ -78,6 +54,14 @@
   line-height: 1;
 }
 
+.fallback {
+  display: inline-flex;
+  align-items: center;
+  justify-content: center;
+  inline-size: 100%;
+  block-size: 100%;
+}
+
 .fallbackIcon {
   width: 60%;
   height: 60%;
@@ -94,41 +78,19 @@
   justify-content: flex-end;
 }
 
-.groupItem {
-  margin-left: -0.5rem;
-  border: 2px solid var(--fui-bg-primary, $fui-bg-primary);
-
-  &:last-child {
-    margin-left: 0;
+@each $size in ("xs", "sm", "md", "lg", "xl") {
+  .group .#{$size}.groupItem {
+    @include representation.avatar-group-item($size);
   }
 }
 
-// Adjust overlap for different sizes
-.group .xs.groupItem {
-  margin-left: -0.375rem;
-}
-
-.group .sm.groupItem {
-  margin-left: -0.5rem;
-}
-
-.group .md.groupItem {
-  margin-left: -0.625rem;
-}
-
-.group .lg.groupItem {
-  margin-left: -0.75rem;
-}
-
-.group .xl.groupItem {
-  margin-left: -1rem;
+.groupItem:last-child {
+  margin-inline-start: 0;
 }
 
 // Overflow count indicator
 .overflow {
-  margin-left: -0.625rem;
   background-color: var(--fui-bg-tertiary, $fui-bg-tertiary);
-  border: 2px solid var(--fui-bg-primary, $fui-bg-primary);
 
   .initials {
     color: var(--fui-text-secondary, $fui-text-secondary);