@usefragments/ui 1.5.4 → 1.7.0

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;
@@ -29,8 +32,13 @@
     var(--appshell-header-height, var(--fui-appshell-header-height, $fui-appshell-header-height))
     1fr;
 
-  // Smooth transition for sidebar collapse/expand
-  transition: grid-template-columns var(--fui-transition-normal, $fui-transition-normal) ease;
+  // Smooth transition for sidebar collapse/expand.
+  // The token already carries its own easing curve — do not append another.
+  transition: grid-template-columns var(--fui-transition-normal, $fui-transition-normal);
+
+  @media (prefers-reduced-motion: reduce) {
+    transition: none;
+  }
 
   // Mobile: single column layout
   @include below-md {
@@ -77,10 +85,11 @@
     var(--fui-appshell-header-height, $fui-appshell-header-height)
   );
   z-index: var(--fui-header-z-index, $fui-header-z-index);
-  background-color: inherit;
+  // Match the reading pane (`--fui-app-main-bg`), not the rail.
+  background-color: var(--fui-app-main-bg, var(--fui-main-bg, #{$fui-main-bg}));
 
   > header {
-    background-color: inherit;
+    background-color: var(--fui-app-main-bg, var(--fui-main-bg, #{$fui-main-bg}));
   }
 }
 
@@ -90,29 +99,42 @@
 
 .sidebar {
   grid-area: sidebar;
-  position: sticky;
-  top: var(
-    --appshell-header-height,
-    var(--fui-appshell-header-height, $fui-appshell-header-height)
-  );
-  height: calc(
-    100vh - var(
-        --appshell-header-height,
-        var(--fui-appshell-header-height, $fui-appshell-header-height)
-      )
-  );
-  height: calc(
-    100dvh - var(
-        --appshell-header-height,
-        var(--fui-appshell-header-height, $fui-appshell-header-height)
-      )
-  );
+  align-self: stretch;
+  position: relative;
+  height: auto;
+  min-height: 100%;
   z-index: 30;
-  overflow: hidden;
+  overflow: visible;
   background-color: inherit;
+  // Border lives on the grid column so the rail runs the full content
+  // height; the sticky inner sidebar is viewport-tall for nav scrolling.
+  border-inline-end: var(--fui-stroke-hairline, 1px) solid
+    var(
+      --fui-sidebar-border,
+      var(--fui-border-subtle, var(--fui-border-default, #{$fui-border-default}))
+    );
 
   > aside {
+    position: sticky;
+    top: var(
+      --appshell-header-height,
+      var(--fui-appshell-header-height, $fui-appshell-header-height)
+    );
+    height: calc(
+      100vh - var(
+          --appshell-header-height,
+          var(--fui-appshell-header-height, $fui-appshell-header-height)
+        )
+    );
+    height: calc(
+      100dvh - var(
+          --appshell-header-height,
+          var(--fui-appshell-header-height, $fui-appshell-header-height)
+        )
+    );
+    overflow: hidden;
     background-color: inherit;
+    border-inline-end: 0;
   }
 
   // On mobile, sidebar becomes a fixed overlay
@@ -125,33 +147,27 @@
     height: 100vh;
     height: 100dvh;
     z-index: 51;
+    border-inline-end: 0;
 
-    // Allow the sidebar to appear as overlay on mobile
-    & > :global(.root) {
+    > aside {
+      position: relative;
+      top: 0;
       width: var(--appshell-sidebar-expanded-width, 240px);
-    }
-  }
-
-  // Override Sidebar component's height
-  :global(.root) {
-    height: 100%;
-
-    @include below-md {
       height: 100vh;
       height: 100dvh;
     }
   }
 }
 
-// Sidebar in sidebar structure: full height
+// Sidebar in sidebar structure: column stretches both rows; inner sticks
+// from the top of the viewport.
 .sidebarFullHeight {
-  top: 0;
-  height: 100vh;
-  height: 100dvh;
   z-index: var(--fui-header-z-index, $fui-header-z-index);
 
-  :global(.root) {
-    height: 100%;
+  > aside {
+    top: 0;
+    height: 100vh;
+    height: 100dvh;
   }
 }
 
@@ -184,10 +200,10 @@
   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
+  box-shadow: inset 0 var(--fui-stroke-hairline, 1px) 0
     color-mix(in srgb, var(--fui-text-primary, #{$fui-text-primary}) 5%, transparent);
   overflow: hidden auto;
 
@@ -253,7 +269,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,10 +295,10 @@
   );
   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
+  box-shadow: inset 0 var(--fui-stroke-hairline, 1px) 0
     color-mix(in srgb, var(--fui-text-primary, #{$fui-text-primary}) 5%, transparent);
   overflow: hidden;
 

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.contract.json

@@ -1,14 +1,9 @@
 {
   "$schema": "https://usefragments.com/schemas/contract.v1.json",
   "name": "Avatar",
-  "description": "Visual representation of a user or entity",
+  "description": "Shows who someone is — their photo, or their initials when there is none.",
   "category": "display",
-  "tags": [
-    "user",
-    "profile",
-    "image",
-    "identity"
-  ],
+  "tags": ["user", "profile", "image", "identity"],
   "status": "stable",
   "sourcePath": "src/components/Avatar/index.tsx",
   "exportName": "Avatar",
@@ -52,13 +47,7 @@
       "description": "Size variant",
       "default": "md",
       "required": false,
-      "values": [
-        "xs",
-        "sm",
-        "md",
-        "lg",
-        "xl"
-      ]
+      "values": ["xs", "sm", "md", "lg", "xl"]
     },
     "customSize": {
       "type": "union",
@@ -70,10 +59,7 @@
       "description": "Shape variant",
       "default": "circle",
       "required": false,
-      "values": [
-        "circle",
-        "square"
-      ]
+      "values": ["circle", "square"]
     },
     "color": {
       "type": "string",
@@ -98,66 +84,67 @@
   },
   "usage": {
     "when": [
-      "Displaying user profile pictures",
-      "Showing team member lists",
-      "Representing entities in lists or cards",
-      "User identification in comments or messages"
+      "A row, comment, or card needs to say who",
+      "Several people belong to one thing — use Avatar.Group"
     ],
     "whenNot": [
-      "Decorative images (use Image)",
-      "Logo display (use Logo component)",
-      "Large profile headers (use custom layout)"
+      "The picture is content, not identity (use Image)",
+      "A profile hero at display size (build the layout yourself)"
     ],
     "guidelines": [
-      "Always provide alt text or name for accessibility",
-      "Use consistent sizes within the same context",
-      "Provide fallback initials when image may not load",
-      "Use Avatar.Group for multiple avatars in a row",
-      "Use imageProps for advanced img attributes (loading, decoding, referrerPolicy, etc.)"
+      "Pass name even when you pass src — it is the fallback and the label",
+      "Hold one size per context; mixed sizes read as a mistake",
+      "Avatar.Group max caps the stack and counts the rest",
+      "imageProps carries loading, decoding, referrerPolicy"
     ],
     "accessibility": [
-      "Include meaningful alt text describing the user",
-      "Initials should be derived from name for screen readers",
-      "Decorative avatars should have empty alt"
+      "alt describes the person, not the word \"avatar\"",
+      "Initials come from name, so screen readers get the whole name",
+      "Purely decorative? Pass alt=\"\""
     ]
   },
   "examples": [
     {
       "name": "Default",
-      "description": "Avatar with image",
+      "description": "A photo, cropped to the circle and centred.",
       "code": "import { Avatar } from '@/components/Avatar';\n\n<Avatar\n  src=\"https://i.pravatar.cc/150?u=jane\"\n  alt=\"Jane Doe\"\n  name=\"Jane Doe\"\n/>"
     },
     {
       "name": "With Initials",
-      "description": "Fallback when no image is provided",
+      "description": "No src, so the name collapses to initials.",
       "code": "import { Avatar } from '@/components/Avatar';\n\n<Avatar name=\"John Smith\" />"
     },
     {
       "name": "Sizes",
-      "description": "Available size options",
+      "description": "Five steps, xs through xl — pick one per context and stick to it.",
       "code": "import { Avatar } from '@/components/Avatar';\nimport { Stack } from '@/components/Stack';\n\n<Stack direction=\"row\" gap=\"sm\" align=\"center\" wrap>\n  <Avatar name=\"XS\" size=\"xs\" />\n  <Avatar name=\"SM\" size=\"sm\" />\n  <Avatar name=\"MD\" size=\"md\" />\n  <Avatar name=\"LG\" size=\"lg\" />\n  <Avatar name=\"XL\" size=\"xl\" />\n</Stack>"
     },
     {
       "name": "Custom Size",
-      "description": "Set an exact avatar size",
+      "description": "customSize takes any number when the scale does not fit.",
       "code": "import { Avatar } from '@/components/Avatar';\n\n<Avatar name=\"Conan McNicholl\" customSize={36} />"
     },
     {
       "name": "Square Shape",
-      "description": "Square variant for app icons or brands",
+      "description": "Squares read as products or orgs, circles as people.",
       "code": "import { Avatar } from '@/components/Avatar';\n\n<Avatar name=\"App\" shape=\"square\" />"
     },
     {
       "name": "Group",
-      "description": "Multiple avatars stacked together",
+      "description": "Overlapping stack with a count for whoever did not fit.",
       "code": "import { Avatar } from '@/components/Avatar';\n\n<Avatar.Group max={3} size=\"md\">\n  <Avatar name=\"Alice Johnson\" />\n  <Avatar name=\"Bob Smith\" />\n  <Avatar name=\"Carol Williams\" />\n  <Avatar name=\"David Brown\" />\n  <Avatar name=\"Eve Davis\" />\n</Avatar.Group>"
     }
   ],
   "relations": [
     {
-      "component": "Avatar",
-      "relationship": "parent",
-      "note": "Use Avatar.Group for stacked avatar displays"
+      "component": "Image",
+      "relationship": "alternative",
+      "note": "Use Image for content pictures that are not a person or entity"
+    },
+    {
+      "component": "Badge",
+      "relationship": "sibling",
+      "note": "Pair with Badge to show presence or role beside a name"
     }
   ],
   "contract": {
@@ -170,15 +157,11 @@
       "imageProps: ImgHTMLAttributes - advanced img attributes",
       "shape: circle|square (default: circle)"
     ],
-    "a11yRules": [
-      "A11Y_IMG_ALT"
-    ]
+    "a11yRules": ["A11Y_IMG_ALT"]
   },
   "ai": {
     "compositionPattern": "compound",
-    "subComponents": [
-      "Group"
-    ]
+    "subComponents": ["Group"]
   },
   "provenance": {
     "source": "migrated",

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,22 @@
   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;
+// Must match the specificity of `.group .<size>.groupItem` above (and follow it
+// in source order), otherwise the leading avatar keeps its negative margin and
+// the whole stack sits offset from the content around it.
+.group .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);