@usefragments/ui 1.6.0 → 1.7.0

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

@@ -84,7 +84,10 @@
   }
 }
 
-.groupItem:last-child {
+// 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;
 }
 

package/src/components/Badge/Badge.contract.json

@@ -1,7 +1,7 @@
 {
   "$schema": "https://usefragments.com/schemas/contract.v1.json",
   "name": "Badge",
-  "description": "Compact label for status, counts, or categorization. Draws attention to metadata without dominating the layout.",
+  "description": "Labels a status, count, or category without pulling focus.",
   "category": "display",
   "tags": ["status", "label", "tag", "count", "chip"],
   "status": "stable",
@@ -87,71 +87,66 @@
   },
   "usage": {
     "when": [
-      "Showing item status (active, pending, archived)",
-      "Displaying counts or quantities inline",
-      "Categorizing or tagging content",
-      "Highlighting new or updated items"
+      "Marking item status: active, pending, archived",
+      "Showing a count inline",
+      "Tagging or categorising content",
+      "Flagging what is new or changed"
     ],
     "whenNot": [
-      "Conveying critical errors (use Alert instead)",
-      "Long-form status messages (use Alert)",
-      "Interactive filtering (use Chip/ToggleGroup)",
-      "Navigation labels (use Tabs or links)"
+      "Real errors that need attention — use Alert",
+      "Anything longer than a few words — use Alert",
+      "Clickable filters — use Chip or ToggleGroup",
+      "View switching — use Tabs or links"
     ],
     "guidelines": [
-      "Keep badge text under 20 characters",
-      "Use dot variant for live status indicators",
-      "Pair success/error variants with meaningful labels, not just colors",
-      "Semantic status badges are borderless pills using shared semantic bg/text tokens",
-      "Use onRemove for user-created tags only, not system-generated badges",
-      "Badges are not announced as live status updates by default; use announce for screen-reader status announcements when appropriate"
+      "Under 20 characters",
+      "dot for live status; add dotPulse only while it is still changing",
+      "Semantic variants are borderless pills on shared status tokens",
+      "label pairs with dotColor; dim pairs with active for filter chrome",
+      "onRemove for user-created tags only, never system labels"
     ],
     "accessibility": [
-      "Badge text must be meaningful without relying on color alone",
-      "Removable badges must have accessible dismiss button labels",
-      "Avoid using badges as the sole indicator of important state changes"
+      "The text must carry the meaning — colour alone never does",
+      "Removable badges need a named dismiss button",
+      "Badges are silent to screen readers unless you pass announce",
+      "Do not make a badge the only signal that something changed"
     ]
   },
   "examples": [
-    {
-      "name": "Default",
-      "description": "Neutral badge for general labels",
-      "code": "import { Badge } from '@/components/Badge';\n\n<Badge>Default</Badge>"
-    },
     {
       "name": "Status Variants",
-      "description": "All severity variants for different contexts",
-      "code": "import { Badge } from '@/components/Badge';\nimport { Stack } from '@/components/Stack';\n\n<Stack direction=\"row\" gap=\"sm\" wrap>\n  <Badge variant=\"default\">Default</Badge>\n  <Badge variant=\"success\">Active</Badge>\n  <Badge variant=\"warning\">Pending</Badge>\n  <Badge variant=\"error\">Failed</Badge>\n  <Badge variant=\"info\">New</Badge>\n</Stack>"
-    },
-    {
-      "name": "Delivery Status",
-      "description": "Reference status pills with deep semantic fill and bright text",
-      "code": "import { Badge } from '@/components/Badge';\nimport { Stack } from '@/components/Stack';\n\n<Stack direction=\"row\" gap=\"sm\" wrap>\n  <Badge variant=\"success\" size=\"lg\">Delivered</Badge>\n  <Badge variant=\"error\" size=\"lg\">Bounced</Badge>\n</Stack>"
+      "description": "Neutral through info, on shared status tokens.",
+      "code": "import { Stack } from '@/components/Stack';\n\n<Stack direction=\"row\" gap=\"sm\" wrap>\n  <Badge variant=\"default\">Default</Badge>\n  <Badge variant=\"success\">Active</Badge>\n  <Badge variant=\"warning\">Pending</Badge>\n  <Badge variant=\"error\">Failed</Badge>\n  <Badge variant=\"info\">New</Badge>\n</Stack>"
     },
     {
       "name": "With Dot",
-      "description": "Live status indicators using dot prefix",
-      "code": "import { Badge } from '@/components/Badge';\nimport { Stack } from '@/components/Stack';\n\n<Stack direction=\"row\" gap=\"sm\" wrap>\n  <Badge variant=\"success\" dot>Online</Badge>\n  <Badge variant=\"warning\" dot>Away</Badge>\n  <Badge variant=\"error\" dot>Offline</Badge>\n</Stack>"
+      "description": "Leading dot for live state; it breathes while still moving.",
+      "code": "import { Stack } from '@/components/Stack';\n\n<Stack direction=\"row\" gap=\"sm\" wrap>\n  <Badge variant=\"success\" dot>Online</Badge>\n  <Badge variant=\"warning\" dot>Away</Badge>\n  <Badge variant=\"error\" dot>Offline</Badge>\n  <Badge variant=\"info\" dot dotPulse>Syncing</Badge>\n</Stack>"
     },
     {
-      "name": "Announced Status",
-      "description": "Opt into screen-reader status announcement behavior",
-      "code": "import { Badge } from '@/components/Badge';\n\n<Badge variant=\"success\" announce>Saved</Badge>"
+      "name": "Label and Filter",
+      "description": "Hairline metadata pill, and filter chrome that marks the active one.",
+      "code": "import { Stack } from '@/components/Stack';\n\n<Stack direction=\"row\" gap=\"sm\" wrap>\n  <Badge variant=\"label\" dotColor=\"var(--fui-color-accent)\">Design</Badge>\n  <Badge variant=\"label\" dotColor=\"var(--fui-color-success)\">Shipped</Badge>\n  <Badge variant=\"dim\" active>All</Badge>\n  <Badge variant=\"dim\">Archived</Badge>\n</Stack>"
     },
     {
       "name": "Outline",
-      "description": "Minimal bordered badge for neutral emphasis",
-      "code": "import { Badge } from '@/components/Badge';\n\n<Badge variant=\"outline\">Outline</Badge>"
+      "description": "Bordered and transparent, when a fill would shout.",
+      "code": "<Badge variant=\"outline\">Outline</Badge>"
     },
     {
-      "name": "Small Size",
-      "description": "Compact badges for dense UIs",
-      "code": "import { Badge } from '@/components/Badge';\nimport { Stack } from '@/components/Stack';\n\n<Stack direction=\"row\" gap=\"sm\" align=\"center\" wrap>\n  <Badge size=\"sm\" variant=\"info\">v2.1</Badge>\n  <Badge size=\"sm\" variant=\"success\">Stable</Badge>\n  <Badge size=\"md\" variant=\"info\">Standard</Badge>\n</Stack>"
+      "name": "Sizes",
+      "description": "sm for dense tables, lg for reference status pills.",
+      "code": "import { Stack } from '@/components/Stack';\n\n<Stack direction=\"row\" gap=\"sm\" align=\"center\" wrap>\n  <Badge variant=\"success\" size=\"sm\">Small</Badge>\n  <Badge variant=\"success\" size=\"md\">Medium</Badge>\n  <Badge variant=\"success\" size=\"lg\">Large</Badge>\n</Stack>"
     },
     {
       "name": "Removable",
-      "description": "User-created tags that can be dismissed",
-      "code": "import { Badge } from '@/components/Badge';\nimport { Stack } from '@/components/Stack';\n\n<Stack direction=\"row\" gap=\"sm\" wrap>\n  <Badge variant=\"info\" onRemove={() => {}}>React</Badge>\n  <Badge variant=\"info\" onRemove={() => {}}>TypeScript</Badge>\n  <Badge variant=\"info\" onRemove={() => {}}>CSS</Badge>\n</Stack>"
+      "description": "Dismissible tags the user added themselves.",
+      "code": "import { Stack } from '@/components/Stack';\n\n<Stack direction=\"row\" gap=\"sm\" wrap>\n  <Badge variant=\"info\" onRemove={() => {}}>React</Badge>\n  <Badge variant=\"info\" onRemove={() => {}}>TypeScript</Badge>\n  <Badge variant=\"info\" onRemove={() => {}}>CSS</Badge>\n</Stack>"
+    },
+    {
+      "name": "Announced Status",
+      "description": "Looks the same, but screen readers now hear the change.",
+      "code": "<Badge variant=\"success\" announce>Saved</Badge>"
     }
   ],
   "relations": [

package/src/components/Badge/Badge.module.scss

@@ -1,4 +1,5 @@
 @use "../../tokens/variables" as *;
+@use "../../tokens/mixins" as *;
 @use "../../recipes/action" as action;
 @use "../../recipes/representation" as representation;
 @use "../../recipes/target" as target;
@@ -85,7 +86,7 @@
 
   &.active {
     border-color: var(--fui-border, $fui-border);
-    background-color: var(--fui-bg-hover, $fui-bg-hover);
+    background-color: var(--fui-control-selected-bg, $fui-bg-active);
     color: var(--fui-text-primary, $fui-text-primary);
   }
 }
@@ -109,7 +110,7 @@
 // motion the component has. Opacity only: nothing reflows, and a reader who has
 // asked for less motion loses the breathing and keeps the badge.
 .dotPulse {
-  animation: fui-badge-dot-pulse 1.6s ease-in-out infinite;
+  animation: fui-badge-dot-pulse var(--fui-duration-pulse, $fui-duration-pulse) ease-in-out infinite;
 }
 
 @keyframes fui-badge-dot-pulse {
@@ -169,4 +170,10 @@
   &:hover {
     opacity: 1;
   }
+
+  &:focus-visible {
+    @include focus-ring;
+
+    opacity: 1;
+  }
 }

package/src/components/BentoGrid/BentoGrid.contract.json

@@ -1,16 +1,9 @@
 {
   "$schema": "https://usefragments.com/schemas/contract.v1.json",
   "name": "BentoGrid",
-  "description": "Asymmetric grid layout with responsive spans and built-in surface styling for bento-style feature sections",
+  "description": "Asymmetric feature grid where tiles span different widths and heights.",
   "category": "layout",
-  "tags": [
-    "bento",
-    "grid",
-    "layout",
-    "responsive",
-    "feature-grid",
-    "asymmetric"
-  ],
+  "tags": ["bento", "grid", "layout", "responsive", "feature-grid", "asymmetric"],
   "status": "stable",
   "sourcePath": "src/components/BentoGrid/index.tsx",
   "exportName": "BentoGrid",
@@ -31,25 +24,14 @@
       "description": "Number of columns — auto-collapses responsively (3→2→1)",
       "default": "3",
       "required": false,
-      "values": [
-        "2",
-        "3",
-        "4"
-      ]
+      "values": ["2", "3", "4"]
     },
     "gap": {
       "type": "enum",
       "description": "Gap between grid items, mapped to spacing tokens",
       "default": "md",
       "required": false,
-      "values": [
-        "none",
-        "xs",
-        "sm",
-        "md",
-        "lg",
-        "xl"
-      ]
+      "values": ["none", "xs", "sm", "md", "lg", "xl"]
     },
     "style": {
       "type": "object",
@@ -59,22 +41,21 @@
   },
   "usage": {
     "when": [
-      "Asymmetric feature grids with hero + supporting items",
-      "Dashboard overviews where cards have different visual weight",
-      "Marketing pages with mixed-size content blocks",
-      "Any layout where items need per-breakpoint column/row spans"
+      "Feature grids with one hero tile and supporting tiles",
+      "Dashboards where cards carry different weight",
+      "Marketing sections with mixed-size blocks"
     ],
     "whenNot": [
-      "Uniform grids where all items are the same size (use Grid)",
-      "Form layouts with labeled fields (use Grid)",
-      "Simple stacked content (use Stack)"
+      "Uniform tiles of one size (use Grid)",
+      "Labelled form fields (use Grid)",
+      "A single column of content (use Stack)"
     ],
     "guidelines": [
-      "Use colSpan/rowSpan with responsive objects for layouts that adapt across breakpoints",
-      "The hero item typically uses colSpan={2} rowSpan={2} at lg and above",
-      "Items include built-in surface styling — no need to wrap children in Card",
-      "Grid auto-collapses: 3→2 columns below lg, all→1 column below sm",
-      "Root and Item forward DOM props (aria-*, data-*, handlers), and Item style merges with span CSS vars"
+      "colSpan and rowSpan take per-breakpoint objects",
+      "A hero tile is usually colSpan 2 and rowSpan 2 from lg up",
+      "Tiles carry their own surface — do not wrap them in Card",
+      "Columns collapse 3 to 2 below lg, and to 1 below sm",
+      "Keep source order equal to visual order for screen readers"
     ],
     "accessibility": [
       "Grid is purely visual — it does not affect reading order or semantics",
@@ -86,23 +67,18 @@
   "examples": [
     {
       "name": "Default",
-      "description": "Basic 3-column uniform bento grid",
-      "code": "<BentoGrid columns={3} gap=\"md\">\n  <BentoGrid.Item>Item 1</BentoGrid.Item>\n  <BentoGrid.Item>Item 2</BentoGrid.Item>\n  <BentoGrid.Item>Item 3</BentoGrid.Item>\n  <BentoGrid.Item>Item 4</BentoGrid.Item>\n  <BentoGrid.Item>Item 5</BentoGrid.Item>\n  <BentoGrid.Item>Item 6</BentoGrid.Item>\n</BentoGrid>"
+      "description": "Equal tiles, each on its own surface.",
+      "code": "import { BentoGrid } from '@/components/BentoGrid';\nimport { Box } from '@/components/Box';\n\n<Box width=\"100%\">\n  <BentoGrid columns={3} gap=\"md\">\n    <BentoGrid.Item>Item 1</BentoGrid.Item>\n    <BentoGrid.Item>Item 2</BentoGrid.Item>\n    <BentoGrid.Item>Item 3</BentoGrid.Item>\n    <BentoGrid.Item>Item 4</BentoGrid.Item>\n    <BentoGrid.Item>Item 5</BentoGrid.Item>\n    <BentoGrid.Item>Item 6</BentoGrid.Item>\n  </BentoGrid>\n</Box>"
     },
     {
       "name": "Hero Layout",
-      "description": "2×2 hero item with 4 supporting items in a 3-column grid",
-      "code": "<BentoGrid columns={3} gap=\"md\">\n  <BentoGrid.Item colSpan={{ base: 1, lg: 2 }} rowSpan={{ base: 1, lg: 2 }}>\n    Hero content\n  </BentoGrid.Item>\n  <BentoGrid.Item>Item 2</BentoGrid.Item>\n  <BentoGrid.Item>Item 3</BentoGrid.Item>\n  <BentoGrid.Item>Item 4</BentoGrid.Item>\n  <BentoGrid.Item>Item 5</BentoGrid.Item>\n</BentoGrid>"
+      "description": "One tile takes two columns and two rows; the rest fill around it.",
+      "code": "import { BentoGrid } from '@/components/BentoGrid';\nimport { Box } from '@/components/Box';\n\n<Box width=\"100%\">\n  <BentoGrid columns={3} gap=\"md\">\n    <BentoGrid.Item colSpan={{ base: 1, lg: 2 }} rowSpan={{ base: 1, lg: 2 }}>\n      Hero content\n    </BentoGrid.Item>\n    <BentoGrid.Item>Item 2</BentoGrid.Item>\n    <BentoGrid.Item>Item 3</BentoGrid.Item>\n    <BentoGrid.Item>Item 4</BentoGrid.Item>\n    <BentoGrid.Item>Item 5</BentoGrid.Item>\n  </BentoGrid>\n</Box>"
     },
     {
       "name": "Two Column",
-      "description": "2-column bento with a wide item",
-      "code": "<BentoGrid columns={2} gap=\"md\">\n  <BentoGrid.Item>Item 1</BentoGrid.Item>\n  <BentoGrid.Item>Item 2</BentoGrid.Item>\n  <BentoGrid.Item colSpan={2}>Wide item</BentoGrid.Item>\n  <BentoGrid.Item>Item 4</BentoGrid.Item>\n  <BentoGrid.Item>Item 5</BentoGrid.Item>\n</BentoGrid>"
-    },
-    {
-      "name": "Full-Width Banner",
-      "description": "3-column grid with a full-width item spanning all columns",
-      "code": "<BentoGrid columns={3} gap=\"md\">\n  <BentoGrid.Item>Item 1</BentoGrid.Item>\n  <BentoGrid.Item>Item 2</BentoGrid.Item>\n  <BentoGrid.Item>Item 3</BentoGrid.Item>\n  <BentoGrid.Item colSpan={3}>Full-width banner</BentoGrid.Item>\n</BentoGrid>"
+      "description": "colSpan stretches a tile across the whole row.",
+      "code": "import { BentoGrid } from '@/components/BentoGrid';\nimport { Box } from '@/components/Box';\n\n<Box width=\"100%\">\n  <BentoGrid columns={2} gap=\"md\">\n    <BentoGrid.Item>Item 1</BentoGrid.Item>\n    <BentoGrid.Item>Item 2</BentoGrid.Item>\n    <BentoGrid.Item colSpan={2}>Wide item</BentoGrid.Item>\n    <BentoGrid.Item>Item 4</BentoGrid.Item>\n    <BentoGrid.Item>Item 5</BentoGrid.Item>\n  </BentoGrid>\n</Box>"
     }
   ],
   "relations": [