@usefragments/ui 1.5.4 → 1.7.0

package/src/components/Breadcrumbs/Breadcrumbs.contract.json

@@ -1,14 +1,9 @@
 {
   "$schema": "https://usefragments.com/schemas/contract.v1.json",
   "name": "Breadcrumbs",
-  "description": "Breadcrumb navigation showing the current page location within a hierarchy. Helps users navigate back through parent pages.",
+  "description": "Shows where the user is and links back up the hierarchy.",
   "category": "navigation",
-  "tags": [
-    "breadcrumbs",
-    "navigation",
-    "hierarchy",
-    "wayfinding"
-  ],
+  "tags": ["breadcrumbs", "navigation", "hierarchy", "wayfinding"],
   "status": "stable",
   "sourcePath": "src/components/Breadcrumbs/index.tsx",
   "exportName": "Breadcrumbs",
@@ -44,21 +39,22 @@
   },
   "usage": {
     "when": [
-      "Showing hierarchical page location (e.g., Home > Category > Product)",
-      "Allowing quick navigation to parent pages",
-      "Multi-level content structures like documentation or e-commerce"
+      "Nested content more than two levels deep",
+      "Jumping back to a parent in one click",
+      "Documentation and catalogue hierarchies"
     ],
     "whenNot": [
-      "Flat navigation with no hierarchy (use Tabs or Header nav)",
-      "Step-by-step wizards (use Stepper)",
+      "Flat structures with no parents (use Tabs or header navigation)",
+      "Steps in an order (use Stepper)",
       "Primary navigation (use Sidebar or Header)"
     ],
     "guidelines": [
-      "Always include the current page as the last, non-linked item",
-      "Keep labels short and descriptive",
-      "Use maxItems to collapse long paths, keeping first and last visible",
-      "The separator defaults to \"/\" but can be customized",
-      "Use the label prop to customize the nav landmark name (defaults to \"Breadcrumb\")"
+      "End on the current page, unlinked",
+      "Short labels — the trail is a path, not a summary",
+      "Set maxItems to fold long paths, keeping first and last",
+      "The separator defaults to a slash and takes any node",
+      "Set label to rename the landmark (defaults to \"Breadcrumb\")",
+      "Crumbs truncate at 200px so one long title cannot push the rest out"
     ],
     "accessibility": [
       "Uses <nav aria-label=\"Breadcrumb\"> for landmark navigation",
@@ -70,27 +66,27 @@
   "examples": [
     {
       "name": "Default",
-      "description": "Basic breadcrumb navigation",
+      "description": "Each ancestor links; the last one does not.",
       "code": "<Breadcrumbs>\n  <Breadcrumbs.Item href=\"#\">Home</Breadcrumbs.Item>\n  <Breadcrumbs.Item href=\"#\">Products</Breadcrumbs.Item>\n  <Breadcrumbs.Item href=\"#\">Category</Breadcrumbs.Item>\n  <Breadcrumbs.Item current>Current Page</Breadcrumbs.Item>\n</Breadcrumbs>"
     },
     {
       "name": "With Icons",
-      "description": "Breadcrumbs with icons on items",
+      "description": "Glyphs mark what kind of thing each level is.",
       "code": "<Breadcrumbs>\n  <Breadcrumbs.Item\n    href=\"#\"\n    icon={\n      <svg viewBox=\"0 0 16 16\" fill=\"currentColor\">\n        <path d=\"M8 1.25l-7 6v7.5c0 .138.112.25.25.25H5.5V10h5v5h4.25a.25.25 0 0 0 .25-.25v-7.5l-7-6z\" />\n      </svg>\n    }\n  >\n    Home\n  </Breadcrumbs.Item>\n  <Breadcrumbs.Item\n    href=\"#\"\n    icon={\n      <svg viewBox=\"0 0 16 16\" fill=\"currentColor\">\n        <path d=\"M1.75 1A1.75 1.75 0 0 0 0 2.75v10.5C0 14.216.784 15 1.75 15h12.5A1.75 1.75 0 0 0 16 13.25v-8.5A1.75 1.75 0 0 0 14.25 3H7.5a.25.25 0 0 1-.2-.1l-.9-1.2C6.07 1.26 5.55 1 5 1H1.75z\" />\n      </svg>\n    }\n  >\n    Documents\n  </Breadcrumbs.Item>\n  <Breadcrumbs.Item current>Report.pdf</Breadcrumbs.Item>\n</Breadcrumbs>"
     },
     {
       "name": "Collapsed",
-      "description": "Long breadcrumb trail collapsed with ellipsis",
+      "description": "Middle levels fold behind an ellipsis.",
       "code": "<Breadcrumbs maxItems={3}>\n  <Breadcrumbs.Item href=\"#\">Home</Breadcrumbs.Item>\n  <Breadcrumbs.Item href=\"#\">Category</Breadcrumbs.Item>\n  <Breadcrumbs.Item href=\"#\">Subcategory</Breadcrumbs.Item>\n  <Breadcrumbs.Item href=\"#\">Section</Breadcrumbs.Item>\n  <Breadcrumbs.Item current>Current Page</Breadcrumbs.Item>\n</Breadcrumbs>"
     },
     {
       "name": "Custom Separator",
-      "description": "Breadcrumbs with a custom chevron separator",
+      "description": "Any node can replace the slash.",
       "code": "<Breadcrumbs\n  separator={\n    <svg width=\"12\" height=\"12\" viewBox=\"0 0 16 16\" fill=\"currentColor\">\n      <path fillRule=\"evenodd\" d=\"M6.22 3.22a.75.75 0 0 1 1.06 0l4.25 4.25a.75.75 0 0 1 0 1.06l-4.25 4.25a.75.75 0 0 1-1.06-1.06L9.94 8 6.22 4.28a.75.75 0 0 1 0-1.06z\" />\n    </svg>\n  }\n>\n  <Breadcrumbs.Item href=\"#\">Home</Breadcrumbs.Item>\n  <Breadcrumbs.Item href=\"#\">Settings</Breadcrumbs.Item>\n  <Breadcrumbs.Item current>Profile</Breadcrumbs.Item>\n</Breadcrumbs>"
     },
     {
       "name": "Custom Landmark Label",
-      "description": "Override the nav landmark label for screen readers",
+      "description": "Renames the landmark screen readers announce.",
       "code": "<Breadcrumbs label=\"Documentation breadcrumbs\">\n  <Breadcrumbs.Item href=\"#\">Docs</Breadcrumbs.Item>\n  <Breadcrumbs.Item href=\"#\">Components</Breadcrumbs.Item>\n  <Breadcrumbs.Item current>Breadcrumbs</Breadcrumbs.Item>\n</Breadcrumbs>"
     }
   ],
@@ -115,21 +111,12 @@
       "Breadcrumbs.Item current: boolean - marks current page",
       "Breadcrumbs.Item icon: ReactNode - icon before label"
     ],
-    "a11yRules": [
-      "A11Y_NAV_LANDMARK",
-      "A11Y_ARIA_CURRENT",
-      "A11Y_TARGET_SIZE_MIN"
-    ]
+    "a11yRules": ["A11Y_NAV_LANDMARK", "A11Y_ARIA_CURRENT", "A11Y_TARGET_SIZE_MIN"]
   },
   "ai": {
     "compositionPattern": "compound",
-    "subComponents": [
-      "Item",
-      "Separator"
-    ],
-    "requiredChildren": [
-      "Item"
-    ],
+    "subComponents": ["Item", "Separator"],
+    "requiredChildren": ["Item"],
     "commonPatterns": [
       "<Breadcrumbs><Breadcrumbs.Item href=\"/\">Home</Breadcrumbs.Item><Breadcrumbs.Item href=\"/products\">Products</Breadcrumbs.Item><Breadcrumbs.Item current>Widget</Breadcrumbs.Item></Breadcrumbs>"
     ]

package/src/components/Breadcrumbs/Breadcrumbs.module.scss

@@ -1,11 +1,12 @@
-@use '../../tokens/variables' as *;
-@use '../../tokens/mixins' as *;
+@use "../../tokens/variables" as *;
+@use "../../tokens/mixins" as *;
+@use "../../recipes/action" as action;
+@use "../../recipes/target" as target;
+@use "../../recipes/typography" as typography;
 
 // Root nav wrapper
 .root {
-  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 typography.role("body-compact");
 }
 
 // Ordered list container
@@ -29,6 +30,8 @@
 
 // Link styling
 .link {
+  @include target.hit-area("micro");
+
   display: inline-flex;
   align-items: center;
   gap: var(--fui-space-1, $fui-space-1);
@@ -37,11 +40,12 @@
   white-space: nowrap;
   overflow: hidden;
   text-overflow: ellipsis;
+  // Intentional truncation width: one long crumb must not push the rest of the
+  // trail off screen. Keep in sync with .current below.
   max-width: 200px;
   border-radius: var(--fui-radius-sm, $fui-radius-sm);
-  padding: var(--fui-space-0-5, $fui-space-0-5) var(--fui-space-1, $fui-space-1);
-  margin: calc(-1 * var(--fui-space-0-5, $fui-space-0-5)) calc(-1 * var(--fui-space-1, $fui-space-1));
-  transition: color var(--fui-transition-fast, $fui-transition-fast),
+  transition:
+    color var(--fui-transition-fast, $fui-transition-fast),
     background-color var(--fui-transition-fast, $fui-transition-fast);
 
   &:hover {
@@ -64,6 +68,7 @@
   white-space: nowrap;
   overflow: hidden;
   text-overflow: ellipsis;
+  // Intentional truncation width — matches .link above.
   max-width: 200px;
 }
 
@@ -79,21 +84,20 @@
 
 // Ellipsis button for collapsed items
 .ellipsis {
-  @include touch-target;
+  @include action.base;
+  @include action.icon-only("micro");
+  @include target.hit-area("compact");
 
   display: inline-flex;
   align-items: center;
   justify-content: center;
   background: none;
-  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-sm, $fui-radius-sm);
   color: var(--fui-text-secondary, $fui-text-secondary);
   cursor: pointer;
-  padding: var(--fui-space-0-5, $fui-space-0-5) var(--fui-space-2, $fui-space-2);
-  font-family: inherit;
-  font-size: var(--fui-font-size-sm, $fui-font-size-sm);
-  line-height: 1;
-  transition: color var(--fui-transition-fast, $fui-transition-fast),
+  transition:
+    color var(--fui-transition-fast, $fui-transition-fast),
     background-color var(--fui-transition-fast, $fui-transition-fast);
 
   &:hover {

package/src/components/Button/Button.module.scss

@@ -1,10 +1,11 @@
 @use "../../tokens/variables" as *;
 @use "../../tokens/mixins" as *;
+@use "../../recipes/action";
 
 .button {
   @include button-reset;
   @include interactive-base;
-  @include text-base;
+  @include action.base;
 
   --_button-bg: transparent;
   --_button-bg-hover: var(--fui-bg-hover, #{$fui-bg-hover});
@@ -16,18 +17,13 @@
   --_button-shadow-hover: var(--_button-shadow);
   --_button-shadow-active: var(--_button-shadow);
 
-  display: inline-flex;
-  align-items: center;
-  justify-content: center;
-  gap: var(--fui-space-1, $fui-space-1);
-  border: 1px solid var(--_button-border);
+  border: var(--fui-stroke-hairline, 1px) solid var(--_button-border);
   border-radius: var(--fui-button-radius, var(--fui-radius-lg, #{$fui-radius-lg}));
   background: var(--_button-bg);
   box-shadow: var(--_button-shadow);
   color: var(--_button-color);
   font-weight: var(--fui-font-weight-medium, $fui-font-weight-medium);
   white-space: nowrap;
-  user-select: none;
 
   // A composed link — `Button asChild` cloning an <a>, or an anchor rendered
   // as a child — must wear the button's own foreground, never the global
@@ -65,33 +61,36 @@
   }
 }
 
-// Sizes
-// Note: Button padding intentionally diverges from the control-size mixin
-// (md: space-3 vs mixin's space-4, lg: space-4 vs mixin's space-5).
-// Buttons need tighter horizontal padding than inputs for visual balance,
-// since button text is typically shorter than input content.
 .xs {
-  min-height: var(--fui-button-height-xs, $fui-button-height-xs);
-  padding: 0 var(--fui-space-1, $fui-space-1);
-  font-size: var(--fui-font-size-xs, $fui-font-size-xs);
+  @include action.size("micro");
+
+  > svg {
+    @include action.glyph("micro");
+  }
 }
 
 .sm {
-  min-height: var(--fui-button-height-sm, $fui-button-height-sm);
-  padding: 0 var(--fui-space-2, $fui-space-2);
-  font-size: var(--fui-font-size-xs, $fui-font-size-xs);
+  @include action.size("sm");
+
+  > svg {
+    @include action.glyph("sm");
+  }
 }
 
 .md {
-  min-height: var(--fui-button-height-md, $fui-button-height-md);
-  padding: 0 var(--fui-space-3, $fui-space-3);
-  font-size: var(--fui-font-size-sm, $fui-font-size-sm);
+  @include action.size("md");
+
+  > svg {
+    @include action.glyph("md");
+  }
 }
 
 .lg {
-  min-height: var(--fui-button-height-lg, $fui-button-height-lg);
-  padding: 0 var(--fui-space-4, $fui-space-4);
-  font-size: var(--fui-font-size-base, $fui-font-size-base);
+  @include action.size("lg");
+
+  > svg {
+    @include action.glyph("lg");
+  }
 }
 
 // ============================================
@@ -101,20 +100,29 @@
 // uneven. When an icon leads or trails text, reduce padding on the icon
 // side so the content appears optically centered.
 //
-// Uses :has() + :first-child/:last-child to detect icon position without
-// JS. The negative margin pulls the icon into the padding zone, compensating
-// for the icon's inherent visual whitespace.
-
-.button:not(.icon) {
-  > svg:first-child:not(:last-child) {
-    // Leading icon: pull left to optically balance
-    margin-left: calc(var(--fui-space-1, $fui-space-1) * -0.5);
-  }
-
-  > svg:last-child:not(:first-child) {
-    // Trailing icon: pull right to optically balance
-    margin-right: calc(var(--fui-space-1, $fui-space-1) * -0.5);
-  }
+.xs:not(.icon):has(> svg:first-child:not(:last-child)) {
+  padding-inline-start: action.icon-side-inset("micro");
+}
+.xs:not(.icon):has(> svg:last-child:not(:first-child)) {
+  padding-inline-end: action.icon-side-inset("micro");
+}
+.sm:not(.icon):has(> svg:first-child:not(:last-child)) {
+  padding-inline-start: action.icon-side-inset("sm");
+}
+.sm:not(.icon):has(> svg:last-child:not(:first-child)) {
+  padding-inline-end: action.icon-side-inset("sm");
+}
+.md:not(.icon):has(> svg:first-child:not(:last-child)) {
+  padding-inline-start: action.icon-side-inset("md");
+}
+.md:not(.icon):has(> svg:last-child:not(:first-child)) {
+  padding-inline-end: action.icon-side-inset("md");
+}
+.lg:not(.icon):has(> svg:first-child:not(:last-child)) {
+  padding-inline-start: action.icon-side-inset("lg");
+}
+.lg:not(.icon):has(> svg:last-child:not(:first-child)) {
+  padding-inline-end: action.icon-side-inset("lg");
 }
 
 // Variants
@@ -137,8 +145,10 @@
   --_button-bg: var(--fui-button-neutral-bg);
   --_button-bg-hover: var(--fui-button-neutral-bg-hover);
   --_button-bg-active: var(--fui-button-neutral-bg-active);
-  --_button-border: var(--fui-button-neutral-border);
-  --_button-border-hover: var(--fui-button-neutral-border-hover);
+  // Secondary hierarchy comes from its fill. The transparent border preserves
+  // control geometry while leaving visible neutral borders to `.outlined`.
+  --_button-border: transparent;
+  --_button-border-hover: transparent;
   --_button-color: var(--fui-button-neutral-color, var(--fui-text-primary, #{$fui-text-primary}));
   --_button-shadow: var(--fui-button-neutral-shadow);
   --_button-shadow-hover: var(--fui-button-neutral-shadow);
@@ -188,6 +198,8 @@
 // takes its hit target from the text and the row's own padding. That makes it
 // the wrong choice for a standalone action — reach for `ghost` there.
 .quiet {
+  @include action.inline;
+
   --_button-bg: transparent;
   --_button-bg-hover: transparent;
   --_button-bg-active: transparent;
@@ -198,8 +210,6 @@
   --_button-shadow-hover: none;
   --_button-shadow-active: none;
 
-  min-height: 0;
-  padding: 0;
   font-weight: var(--fui-font-weight-normal, $fui-font-weight-normal);
 
   // Only the custom property is restated: `color` reads it on .button, so the
@@ -257,24 +267,10 @@
 
 // Icon-only button (square aspect ratio)
 .icon {
-  aspect-ratio: 1;
-  padding: 0;
-
-  &.xs {
-    width: var(--fui-button-height-xs, $fui-button-height-xs);
-  }
-
-  &.sm {
-    width: var(--fui-button-height-sm, $fui-button-height-sm);
-  }
-
-  &.md {
-    width: var(--fui-button-height-md, $fui-button-height-md);
-  }
-
-  &.lg {
-    width: var(--fui-button-height-lg, $fui-button-height-lg);
-  }
+  inline-size: var(--_fui-action-track);
+  block-size: var(--_fui-action-track);
+  min-block-size: var(--_fui-action-track);
+  padding-inline: 0;
 }
 
 // Full width
@@ -302,17 +298,17 @@
 
 @media (prefers-contrast: more) {
   .secondary {
-    border-width: 2px;
+    border-width: var(--fui-stroke-default, 2px);
     border-color: var(--fui-text-primary, $fui-text-primary);
   }
 
   .outlined {
-    border-width: 2px;
+    border-width: var(--fui-stroke-default, 2px);
     border-color: var(--fui-text-primary, $fui-text-primary);
   }
 
   .ghost {
-    border-width: 2px;
+    border-width: var(--fui-stroke-default, 2px);
 
     &:hover:not(:disabled) {
       border-color: var(--fui-text-primary, $fui-text-primary);
@@ -320,7 +316,7 @@
   }
 
   .link {
-    border-width: 2px;
+    border-width: var(--fui-stroke-default, 2px);
 
     &:hover:not(:disabled) {
       border-color: var(--fui-color-accent, $fui-color-accent);

package/src/components/ButtonGroup/ButtonGroup.contract.json

@@ -1,15 +1,9 @@
 {
   "$schema": "https://usefragments.com/schemas/contract.v1.json",
   "name": "ButtonGroup",
-  "description": "Groups related buttons together with consistent spacing and alignment. Useful for action bars, toolbars, and related button sets.",
-  "category": "forms",
-  "tags": [
-    "button",
-    "group",
-    "toolbar",
-    "actions",
-    "layout"
-  ],
+  "description": "Lays out related buttons in a row with one shared gap and alignment.",
+  "category": "actions",
+  "tags": ["button", "group", "toolbar", "actions", "layout"],
   "status": "stable",
   "sourcePath": "src/components/ButtonGroup/index.tsx",
   "exportName": "ButtonGroup",
@@ -30,12 +24,7 @@
       "description": "Spacing between buttons",
       "default": "sm",
       "required": false,
-      "values": [
-        "none",
-        "xs",
-        "sm",
-        "md"
-      ]
+      "values": ["none", "xs", "sm", "md"]
     },
     "wrap": {
       "type": "boolean",
@@ -47,57 +36,57 @@
       "type": "enum",
       "description": "Alignment of buttons",
       "required": false,
-      "values": [
-        "start",
-        "center",
-        "end"
-      ]
+      "values": ["start", "center", "end"]
     }
   },
   "usage": {
     "when": [
-      "Grouping related actions together",
-      "Creating toolbars or action bars",
-      "Form submit/cancel button pairs",
+      "Confirm/cancel pairs at the end of a form",
+      "Toolbars and action bars",
       "Pagination controls"
     ],
     "whenNot": [
-      "Unrelated buttons (use Stack instead)",
-      "Navigation links (use nav element)",
-      "Single button (no grouping needed)"
+      "Unrelated buttons — use Stack",
+      "Navigation links — use a nav element",
+      "A single button"
     ],
     "guidelines": [
-      "Keep button groups focused on related actions",
-      "Use consistent button variants within a group",
-      "Consider visual hierarchy - primary action should stand out",
-      "Limit to 2-4 buttons per group for clarity",
-      "Pass role/aria-label/id/data-* directly to ButtonGroup when you need semantic grouping hooks"
+      "Two to four buttons; more belongs in a Menu",
+      "Confirming action goes last",
+      "One primary button per group",
+      "align=\"end\" for form footers",
+      "Pass role, aria-label, id and data-* straight through to ButtonGroup"
     ],
     "accessibility": [
-      "Group provides semantic relationship between buttons",
-      "Each button remains individually focusable",
-      "Consider using role=\"group\" with aria-label for screen readers"
+      "Each button stays individually focusable",
+      "Add role=\"group\" plus aria-label when the set needs a name",
+      "Order buttons the way they read, not the way they look"
     ]
   },
   "examples": [
     {
       "name": "Default",
-      "description": "Basic button group with default spacing",
+      "description": "Confirming action sits last in the row.",
       "code": "<ButtonGroup>\n  <Button variant=\"secondary\">Cancel</Button>\n  <Button variant=\"primary\">Save</Button>\n</ButtonGroup>"
     },
     {
-      "name": "Gap Variants",
-      "description": "Different spacing options",
-      "code": "<div style={{ display: 'flex', flexDirection: 'column', gap: '16px' }}>\n  <ButtonGroup gap=\"none\">\n    <Button variant=\"secondary\" size=\"sm\">None</Button>\n    <Button variant=\"secondary\" size=\"sm\">Gap</Button>\n  </ButtonGroup>\n  <ButtonGroup gap=\"xs\">\n    <Button variant=\"secondary\" size=\"sm\">XS</Button>\n    <Button variant=\"secondary\" size=\"sm\">Gap</Button>\n  </ButtonGroup>\n  <ButtonGroup gap=\"sm\">\n    <Button variant=\"secondary\" size=\"sm\">SM</Button>\n    <Button variant=\"secondary\" size=\"sm\">Gap</Button>\n  </ButtonGroup>\n  <ButtonGroup gap=\"md\">\n    <Button variant=\"secondary\" size=\"sm\">MD</Button>\n    <Button variant=\"secondary\" size=\"sm\">Gap</Button>\n  </ButtonGroup>\n</div>"
+      "name": "Spacing",
+      "description": "Four gap steps, from touching to airy.",
+      "code": "import { Stack } from '@/components/Stack';\n\n<Stack direction=\"column\" gap=\"md\">\n  <ButtonGroup gap=\"none\">\n    <Button variant=\"secondary\" size=\"sm\">None</Button>\n    <Button variant=\"secondary\" size=\"sm\">Gap</Button>\n  </ButtonGroup>\n  <ButtonGroup gap=\"xs\">\n    <Button variant=\"secondary\" size=\"sm\">XS</Button>\n    <Button variant=\"secondary\" size=\"sm\">Gap</Button>\n  </ButtonGroup>\n  <ButtonGroup gap=\"sm\">\n    <Button variant=\"secondary\" size=\"sm\">SM</Button>\n    <Button variant=\"secondary\" size=\"sm\">Gap</Button>\n  </ButtonGroup>\n  <ButtonGroup gap=\"md\">\n    <Button variant=\"secondary\" size=\"sm\">MD</Button>\n    <Button variant=\"secondary\" size=\"sm\">Gap</Button>\n  </ButtonGroup>\n</Stack>"
     },
     {
       "name": "Alignment",
-      "description": "Different alignment options",
-      "code": "<div style={{ display: 'flex', flexDirection: 'column', gap: '16px', width: '300px' }}>\n  <ButtonGroup align=\"start\">\n    <Button variant=\"secondary\" size=\"sm\">Start</Button>\n    <Button variant=\"secondary\" size=\"sm\">Aligned</Button>\n  </ButtonGroup>\n  <ButtonGroup align=\"center\">\n    <Button variant=\"secondary\" size=\"sm\">Center</Button>\n    <Button variant=\"secondary\" size=\"sm\">Aligned</Button>\n  </ButtonGroup>\n  <ButtonGroup align=\"end\">\n    <Button variant=\"secondary\" size=\"sm\">End</Button>\n    <Button variant=\"secondary\" size=\"sm\">Aligned</Button>\n  </ButtonGroup>\n</div>"
+      "description": "Pins the row to the left, centre, or right of its container.",
+      "code": "import { Stack } from '@/components/Stack';\n\n<Stack direction=\"column\" gap=\"md\">\n  <ButtonGroup align=\"start\">\n    <Button variant=\"secondary\" size=\"sm\">Start</Button>\n    <Button variant=\"secondary\" size=\"sm\">Aligned</Button>\n  </ButtonGroup>\n  <ButtonGroup align=\"center\">\n    <Button variant=\"secondary\" size=\"sm\">Center</Button>\n    <Button variant=\"secondary\" size=\"sm\">Aligned</Button>\n  </ButtonGroup>\n  <ButtonGroup align=\"end\">\n    <Button variant=\"secondary\" size=\"sm\">End</Button>\n    <Button variant=\"secondary\" size=\"sm\">Aligned</Button>\n  </ButtonGroup>\n</Stack>"
+    },
+    {
+      "name": "Wrapping",
+      "description": "Buttons drop to a second line instead of overflowing.",
+      "code": "<ButtonGroup wrap>\n  <Button variant=\"secondary\" size=\"sm\">Approve</Button>\n  <Button variant=\"secondary\" size=\"sm\">Request changes</Button>\n  <Button variant=\"secondary\" size=\"sm\">Reassign reviewer</Button>\n  <Button variant=\"secondary\" size=\"sm\">Move to backlog</Button>\n  <Button variant=\"secondary\" size=\"sm\">Archive</Button>\n</ButtonGroup>"
     },
     {
       "name": "Form Actions",
-      "description": "Common pattern for form submit/cancel",
+      "description": "Right-aligned pair, named for screen readers.",
       "code": "<ButtonGroup align=\"end\" role=\"group\" aria-label=\"Form actions\">\n  <Button variant=\"ghost\">Cancel</Button>\n  <Button variant=\"primary\">Submit</Button>\n</ButtonGroup>"
     }
   ],
@@ -121,15 +110,11 @@
       "align: start|center|end - alignment",
       "Pass-through DOM props supported on root (id, role, aria-*, data-*, handlers)"
     ],
-    "a11yRules": [
-      "A11Y_GROUP_LABEL"
-    ]
+    "a11yRules": ["A11Y_GROUP_LABEL"]
   },
   "ai": {
     "compositionPattern": "compound",
-    "subComponents": [
-      "Root"
-    ]
+    "subComponents": ["Root"]
   },
   "provenance": {
     "source": "migrated",

package/src/components/ButtonGroup/ButtonGroup.module.scss

@@ -1,4 +1,4 @@
-@use "../../tokens/variables" as *;
+@use "../../recipes/layout";
 
 .group {
   display: flex;
@@ -14,7 +14,7 @@
   }
 
   > *:not(:first-child) {
-    margin-left: -1px;
+    margin-inline-start: calc(-1 * var(--fui-stroke-hairline, 1px));
     border-top-left-radius: 0;
     border-bottom-left-radius: 0;
   }
@@ -31,15 +31,15 @@
 }
 
 .gap-xs {
-  gap: var(--fui-space-1, $fui-space-1);
+  gap: layout.gap("xs");
 }
 
 .gap-sm {
-  gap: var(--fui-space-2, $fui-space-2);
+  gap: layout.gap("sm");
 }
 
 .gap-md {
-  gap: var(--fui-space-3, $fui-space-3);
+  gap: layout.gap("md");
 }
 
 // Wrap

package/src/components/Card/Card.consumer-fixture.module.scss

@@ -0,0 +1,8 @@
+// Deliberately unlayered: this proves ordinary consumer CSS can customize a
+// layered Card without specificity escalation or priority hacks.
+.consumerOverride {
+  --fui-card-consumer-fixture: 1;
+
+  padding: 29px;
+  background-color: rgb(9 87 73);
+}