@usefragments/ui 1.6.0 → 1.7.0

package/src/components/Skeleton/Skeleton.contract.json

@@ -1,14 +1,9 @@
 {
   "$schema": "https://usefragments.com/schemas/contract.v1.json",
   "name": "Skeleton",
-  "description": "Placeholder loading state for content",
+  "description": "Holds the shape of content that has not arrived yet.",
   "category": "feedback",
-  "tags": [
-    "loading",
-    "placeholder",
-    "skeleton",
-    "shimmer"
-  ],
+  "tags": ["loading", "placeholder", "skeleton", "shimmer"],
   "status": "stable",
   "sourcePath": "src/components/Skeleton/index.tsx",
   "exportName": "Skeleton",
@@ -27,25 +22,14 @@
       "description": "Semantic variant that auto-sizes",
       "default": "rect",
       "required": false,
-      "values": [
-        "text",
-        "heading",
-        "avatar",
-        "button",
-        "input",
-        "rect"
-      ]
+      "values": ["text", "heading", "avatar", "button", "input", "rect"]
     },
     "size": {
       "type": "enum",
       "description": "Size for avatar/button variants",
       "default": "md",
       "required": false,
-      "values": [
-        "sm",
-        "md",
-        "lg"
-      ]
+      "values": ["sm", "md", "lg"]
     },
     "width": {
       "type": "union",
@@ -67,13 +51,7 @@
       "type": "enum",
       "description": "Border radius override",
       "required": false,
-      "values": [
-        "sm",
-        "md",
-        "lg",
-        "none",
-        "full"
-      ]
+      "values": ["sm", "md", "lg", "none", "full"]
     },
     "static": {
       "type": "boolean",
@@ -84,54 +62,53 @@
   },
   "usage": {
     "when": [
-      "Content is loading asynchronously",
-      "Preventing layout shift during data fetching",
-      "Providing visual feedback that content is coming",
-      "Improving perceived performance"
+      "Content is still being fetched",
+      "You want to stop the layout jumping when it lands",
+      "Making a wait feel shorter than it is"
     ],
     "whenNot": [
-      "Short loading times (< 300ms)",
-      "When spinner is more appropriate",
-      "Background operations without visible impact"
+      "Waits under about 300ms",
+      "A spinner says it better",
+      "Work the user cannot see anyway"
     ],
     "guidelines": [
-      "Match skeleton shape to expected content",
-      "Use semantic variants (text, heading, avatar) for consistency",
-      "Maintain similar dimensions to loaded content",
-      "Avoid too many skeleton elements - simplify complex layouts",
-      "Skeleton and Skeleton.Text forward DOM props (id, aria-*, data-*, handlers)"
+      "Match the shape and size of the real content",
+      "Prefer the text, heading, and avatar variants over hand-rolled boxes",
+      "Give Skeleton.Text an ancestor with a real width — percentage lines collapse without one",
+      "A few big shapes beat many small ones",
+      "Skeleton and Skeleton.Text forward id, aria-*, data-* and handlers"
     ],
     "accessibility": [
-      "Skeletons are decorative - use aria-hidden",
-      "Announce loading state separately if needed",
-      "Ensure sufficient contrast for the animation"
+      "Skeletons are decoration — hide them with aria-hidden",
+      "Announce the loading state separately if it matters",
+      "Keep the pulse subtle but visible against the surface"
     ]
   },
   "examples": [
     {
       "name": "Default",
-      "description": "Basic rectangle skeleton",
+      "description": "One rectangle at an explicit size.",
       "code": "<Skeleton width={200} height={20} />"
     },
     {
       "name": "Text Lines",
-      "description": "Multi-line text placeholder",
-      "code": "<Skeleton.Text lines={3} />"
+      "description": "Stacked lines that fill the width they are given.",
+      "code": "<div style={{ width: 260 }}>\n  <Skeleton.Text lines={3} />\n</div>"
     },
     {
       "name": "Semantic Variants",
-      "description": "Pre-configured shapes for common elements",
-      "code": "<div style={{ display: 'flex', flexDirection: 'column', gap: 'var(--fui-space-2)' }}>\n  <Skeleton variant=\"heading\" width={200} />\n  <Skeleton variant=\"text\" width=\"100%\" />\n  <Skeleton variant=\"text\" width=\"80%\" />\n</div>"
+      "description": "Heading sits taller than the body lines under it.",
+      "code": "<div\n  style={{\n    width: 260,\n    display: 'flex',\n    flexDirection: 'column',\n    gap: 'var(--fui-space-2)',\n  }}\n>\n  <Skeleton variant=\"heading\" width={200} />\n  <Skeleton variant=\"text\" width=\"100%\" />\n  <Skeleton variant=\"text\" width=\"80%\" />\n</div>"
     },
     {
       "name": "Avatar Skeleton",
-      "description": "Circular placeholder for avatars",
+      "description": "Circles matching the three avatar sizes.",
       "code": "<div style={{ display: 'flex', gap: 'var(--fui-space-1)', alignItems: 'center' }}>\n  <Skeleton.Circle size=\"sm\" />\n  <Skeleton.Circle size=\"md\" />\n  <Skeleton.Circle size=\"lg\" />\n</div>"
     },
     {
       "name": "Card Skeleton",
-      "description": "Composed skeleton for a card layout",
-      "code": "<div style={{ width: 300, padding: 'var(--fui-space-2)', border: '1px solid var(--fui-border)', borderRadius: 'var(--fui-radius-lg)' }}>\n  <Skeleton variant=\"rect\" height={120} radius=\"md\" />\n  <div style={{ marginTop: 'var(--fui-space-2)' }}>\n    <Skeleton variant=\"heading\" width=\"60%\" />\n  </div>\n  <div style={{ marginTop: 'var(--fui-space-1)' }}>\n    <Skeleton.Text lines={2} />\n  </div>\n</div>"
+      "description": "Media, title, then body — the card before it loads.",
+      "code": "<div\n  style={{\n    width: 300,\n    padding: 'var(--fui-space-2)',\n    border: '1px solid var(--fui-border)',\n    borderRadius: 'var(--fui-radius-lg)',\n  }}\n>\n  <Skeleton variant=\"rect\" height={120} radius=\"md\" />\n  <div style={{ marginTop: 'var(--fui-space-2)' }}>\n    <Skeleton variant=\"heading\" width=\"60%\" />\n  </div>\n  <div style={{ marginTop: 'var(--fui-space-1)' }}>\n    <Skeleton.Text lines={2} />\n  </div>\n</div>"
     }
   ],
   "relations": [
@@ -152,10 +129,7 @@
   },
   "ai": {
     "compositionPattern": "compound",
-    "subComponents": [
-      "Text",
-      "Circle"
-    ]
+    "subComponents": ["Text", "Circle"]
   },
   "provenance": {
     "source": "migrated",

package/src/components/Skeleton/Skeleton.module.scss

@@ -5,28 +5,44 @@
 // Skeleton Component Styles
 // ============================================
 
-// Animation
-@keyframes skeleton-pulse {
-  0%,
-  100% {
-    opacity: 1;
+// Animation — a highlight travelling across the placeholder, not the whole
+// block fading out. A pulsing opacity spends half its cycle invisible on a
+// light surface; the shimmer keeps the missing fact legible the entire time.
+@keyframes skeleton-shimmer {
+  from {
+    background-position: 120% 0;
   }
-  50% {
-    opacity: 0.5;
+  to {
+    background-position: -120% 0;
   }
 }
 
 // Base skeleton
 .skeleton {
   display: block;
-  background-color: var(--fui-bg-tertiary, #{$fui-bg-tertiary});
-  animation: skeleton-pulse 2s cubic-bezier(0.4, 0, 0.6, 1) infinite;
+  background-color: var(--fui-skeleton, #{$fui-bg-tertiary});
+  background-image: linear-gradient(
+    90deg,
+    var(--fui-skeleton, #{$fui-bg-tertiary}) 0%,
+    var(--fui-skeleton-hi, #{$fui-bg-secondary}) 45%,
+    var(--fui-skeleton, #{$fui-bg-tertiary}) 90%
+  );
+  background-size: 240% 100%;
+  animation: skeleton-shimmer var(--fui-duration-shimmer, $fui-duration-shimmer) linear infinite;
   border-radius: var(--fui-radius-md, #{$fui-radius-md});
 }
 
 // Static (no animation)
 .static {
   animation: none;
+  background-image: none;
+}
+
+@media (prefers-reduced-motion: reduce) {
+  .skeleton {
+    animation: none;
+    background-image: none;
+  }
 }
 
 // Fill parent
@@ -150,7 +166,8 @@
   height: 1em;
   width: 100%;
   background-color: var(--fui-bg-tertiary, #{$fui-bg-tertiary});
-  animation: skeleton-pulse 2s cubic-bezier(0.4, 0, 0.6, 1) infinite;
+  animation: skeleton-pulse var(--fui-duration-shimmer, $fui-duration-shimmer)
+    cubic-bezier(0.4, 0, 0.6, 1) infinite;
   border-radius: var(--fui-radius-sm, #{$fui-radius-sm});
 }
 

package/src/components/Slider/Slider.contract.json

@@ -1,15 +1,9 @@
 {
   "$schema": "https://usefragments.com/schemas/contract.v1.json",
   "name": "Slider",
-  "description": "Range input control for selecting a numeric value within a defined range. Supports labels, value display, and custom step intervals.",
-  "category": "forms",
-  "tags": [
-    "slider",
-    "range",
-    "input",
-    "number",
-    "control"
-  ],
+  "description": "Selects a numeric value within a defined range.",
+  "category": "inputs",
+  "tags": ["slider", "range", "input", "number", "control"],
   "status": "stable",
   "sourcePath": "src/components/Slider/index.tsx",
   "exportName": "Slider",
@@ -141,63 +135,63 @@
   },
   "usage": {
     "when": [
-      "Selecting a value from a continuous range",
-      "Volume or brightness controls",
-      "Price range filters",
-      "Settings that benefit from visual feedback"
+      "Any value along a range, where roughly right is good enough",
+      "Volume, brightness, opacity",
+      "Price and range filters",
+      "The effect is visible as the user drags"
     ],
     "whenNot": [
-      "Precise numeric input (use Input type=\"number\")",
-      "Discrete options (use RadioGroup or Select)",
-      "Yes/no choices (use Switch)"
+      "An exact number matters (use Input type=\"number\")",
+      "A handful of fixed choices (use RadioGroup or Select)",
+      "On or off (use Switch)"
     ],
     "guidelines": [
-      "Always provide a label describing what the slider controls",
-      "Show the current value when precision matters",
-      "Use appropriate min/max values for the context",
-      "Consider step size for usability"
+      "Label what the track controls",
+      "Turn on showValue whenever the number matters",
+      "Set min and max to the real limits, not 0-100 by habit",
+      "Pick a step the user can actually land on"
     ],
     "accessibility": [
-      "Label is associated with the slider",
-      "Keyboard accessible with arrow keys",
-      "Current value is announced to screen readers",
-      "Uses native slider semantics"
+      "Label is tied to the track",
+      "Arrow keys move the thumb",
+      "The current value is announced",
+      "Native slider semantics throughout"
     ]
   },
   "examples": [
     {
       "name": "Default",
-      "description": "Basic slider with label",
+      "description": "0-100 with no number shown.",
       "code": "<div style={{ width: '300px' }}>\n  <Slider label=\"Volume\" defaultValue={50} />\n</div>"
     },
     {
       "name": "With Value Display",
-      "description": "Shows current value alongside the slider",
+      "description": "showValue prints the number opposite the label.",
       "code": "<div style={{ width: '300px' }}>\n  <Slider\n    label=\"Brightness\"\n    defaultValue={75}\n    showValue\n    valueSuffix=\"%\"\n  />\n</div>"
     },
     {
       "name": "Custom Range",
-      "description": "Custom min, max, and step values",
+      "description": "min, max and step bound the track to real-world units.",
       "code": "<div style={{ width: '300px', display: 'flex', flexDirection: 'column', gap: '16px' }}>\n  <Slider\n    label=\"Temperature\"\n    min={60}\n    max={80}\n    step={1}\n    defaultValue={72}\n    showValue\n    valueSuffix=\"°F\"\n  />\n  <Slider\n    label=\"Font Size\"\n    min={12}\n    max={32}\n    step={2}\n    defaultValue={16}\n    showValue\n    valueSuffix=\"px\"\n  />\n</div>"
     },
     {
       "name": "Controlled",
-      "description": "Controlled slider with external state",
+      "description": "The parent owns the value and can react to every move.",
       "code": "<ControlledSliderDemo />"
     },
     {
       "name": "Drag Value Bubble",
-      "description": "Shows a floating value bubble while the thumb is being dragged",
+      "description": "The number floats above the thumb only while dragging.",
       "code": "<div style={{ width: '300px' }}>\n  <Slider\n    label=\"Mix\"\n    defaultValue={40}\n    showValueOnDrag\n    valueSuffix=\"%\"\n  />\n</div>"
     },
     {
       "name": "With Helper Text",
-      "description": "Slider with helper text guidance",
+      "description": "A line below the track explains the trade-off.",
       "code": "<div style={{ width: '300px' }}>\n  <Slider\n    label=\"Quality\"\n    defaultValue={80}\n    showValue\n    valueSuffix=\"%\"\n    helperText=\"Higher quality increases file size\"\n  />\n</div>"
     },
     {
       "name": "Disabled",
-      "description": "Disabled slider",
+      "description": "Dimmed; the thumb will not move.",
       "code": "<div style={{ width: '300px' }}>\n  <Slider\n    label=\"Locked Setting\"\n    defaultValue={30}\n    showValue\n    disabled\n  />\n</div>"
     }
   ],
@@ -227,17 +221,11 @@
       "showValueOnDrag: boolean - show value bubble during drag",
       "valueSuffix: string - unit suffix"
     ],
-    "a11yRules": [
-      "A11Y_LABEL_REQUIRED",
-      "A11Y_KEYBOARD_ACCESSIBLE",
-      "A11Y_TARGET_SIZE_MIN"
-    ]
+    "a11yRules": ["A11Y_LABEL_REQUIRED", "A11Y_KEYBOARD_ACCESSIBLE", "A11Y_TARGET_SIZE_MIN"]
   },
   "ai": {
     "compositionPattern": "compound",
-    "subComponents": [
-      "Root"
-    ]
+    "subComponents": ["Root"]
   },
   "provenance": {
     "source": "migrated",

package/src/components/Slider/Slider.module.scss

@@ -45,7 +45,7 @@
   position: relative;
   width: 100%;
   background-color: var(--fui-form-group-bg, $fui-bg-secondary);
-  box-shadow: inset 0 0 0 1px var(--fui-form-group-border, $fui-border);
+  box-shadow: inset 0 0 0 var(--fui-stroke-hairline, 1px) var(--fui-form-group-border, $fui-border);
   border-radius: var(--fui-radius-full, $fui-radius-full);
   cursor: pointer;
 
@@ -58,7 +58,7 @@
 .indicator {
   position: absolute;
   height: 100%;
-  background-color: var(--fui-field-selection-border, $fui-color-accent);
+  background-color: var(--fui-color-accent, $fui-color-accent);
   border-radius: var(--fui-radius-full, $fui-radius-full);
 }
 
@@ -67,7 +67,7 @@
   @include target.hit-area("compact");
 
   background-color: var(--fui-bg-primary, $fui-bg-primary);
-  border: var(--fui-stroke-hairline, 1px) solid var(--fui-field-selection-border, $fui-color-accent);
+  border: var(--fui-stroke-hairline, 1px) solid var(--fui-color-accent, $fui-color-accent);
   border-radius: var(--fui-radius-full, $fui-radius-full);
   box-shadow: var(--fui-shadow-sm, $fui-shadow-sm);
   cursor: grab;

package/src/components/Stack/Stack.contract.json

@@ -1,15 +1,9 @@
 {
   "$schema": "https://usefragments.com/schemas/contract.v1.json",
   "name": "Stack",
-  "description": "Flexible layout component for arranging children in rows or columns with consistent spacing. Supports responsive direction and gap.",
+  "description": "Stacks children in a row or column with one consistent gap.",
   "category": "layout",
-  "tags": [
-    "stack",
-    "layout",
-    "flex",
-    "spacing",
-    "responsive"
-  ],
+  "tags": ["stack", "layout", "flex", "spacing", "responsive"],
   "status": "stable",
   "sourcePath": "src/components/Stack/index.tsx",
   "exportName": "Stack",
@@ -47,24 +41,13 @@
       "type": "enum",
       "description": "Cross-axis alignment",
       "required": false,
-      "values": [
-        "start",
-        "center",
-        "end",
-        "stretch",
-        "baseline"
-      ]
+      "values": ["start", "center", "end", "stretch", "baseline"]
     },
     "justify": {
       "type": "enum",
       "description": "Main-axis alignment",
       "required": false,
-      "values": [
-        "start",
-        "center",
-        "end",
-        "between"
-      ]
+      "values": ["start", "center", "end", "between"]
     },
     "wrap": {
       "type": "boolean",
@@ -108,22 +91,21 @@
   },
   "usage": {
     "when": [
-      "Arranging elements in a row or column",
-      "Creating consistent spacing between items",
-      "Building responsive layouts",
-      "Simple flexbox-based arrangements"
+      "Spacing a short row or column of elements",
+      "Any one-directional flexbox arrangement",
+      "Layouts that flip direction at a breakpoint"
     ],
     "whenNot": [
-      "Complex grid layouts (use Grid)",
-      "Button-specific grouping (use ButtonGroup)",
-      "Page-level layout (use AppShell)"
+      "Two-dimensional layouts (use Grid)",
+      "Grouping buttons into one control (use ButtonGroup)",
+      "Page shell regions (use AppShell)"
     ],
     "guidelines": [
-      "Use semantic elements via the \"as\" prop when appropriate",
-      "Leverage responsive props for mobile-first layouts",
-      "Keep spacing consistent within related sections",
-      "Consider alignment for visual balance",
-      "Pass DOM attributes (id, role, aria-*, data-*, event handlers) directly to Stack root when needed"
+      "Set gap once on the parent instead of margins on children",
+      "Numeric gaps (1-8) map to the same spacing scale as the tokens",
+      "direction, gap, and align all accept per-breakpoint objects",
+      "Use as=\"nav\" or as=\"ul\" so the markup stays semantic",
+      "separator draws dividers without extra elements"
     ],
     "accessibility": [
       "Use semantic elements (nav, section, etc.) via \"as\" prop",
@@ -134,42 +116,37 @@
   "examples": [
     {
       "name": "Vertical Stack",
-      "description": "Default column layout",
-      "code": "<Stack gap=\"sm\">\n  <Badge>Item 1</Badge>\n  <Badge>Item 2</Badge>\n  <Badge>Item 3</Badge>\n</Stack>"
+      "description": "Children flow top to bottom — the default.",
+      "code": "import { Box } from '@/components/Box';\nimport { Stack } from '@/components/Stack';\n\n<Stack gap=\"sm\">\n  <Box background=\"secondary\" rounded=\"sm\" paddingX=\"md\" paddingY=\"sm\">One</Box>\n  <Box background=\"secondary\" rounded=\"sm\" paddingX=\"md\" paddingY=\"sm\">Two</Box>\n  <Box background=\"secondary\" rounded=\"sm\" paddingX=\"md\" paddingY=\"sm\">Three</Box>\n</Stack>"
     },
     {
       "name": "Horizontal Stack",
-      "description": "Row layout",
-      "code": "<Stack direction=\"row\" gap=\"sm\">\n  <Badge>Item 1</Badge>\n  <Badge>Item 2</Badge>\n  <Badge>Item 3</Badge>\n</Stack>"
+      "description": "Children flow left to right.",
+      "code": "import { Box } from '@/components/Box';\nimport { Stack } from '@/components/Stack';\n\n<Stack direction=\"row\" gap=\"sm\">\n  <Box background=\"secondary\" rounded=\"sm\" paddingX=\"md\" paddingY=\"sm\">One</Box>\n  <Box background=\"secondary\" rounded=\"sm\" paddingX=\"md\" paddingY=\"sm\">Two</Box>\n  <Box background=\"secondary\" rounded=\"sm\" paddingX=\"md\" paddingY=\"sm\">Three</Box>\n</Stack>"
     },
     {
       "name": "Gap Sizes",
-      "description": "Different spacing options",
-      "code": "<Stack gap=\"lg\">\n  <Stack direction=\"row\" gap=\"xs\">\n    <Badge variant=\"info\">XS</Badge>\n    <Badge variant=\"info\">Gap</Badge>\n  </Stack>\n  <Stack direction=\"row\" gap=\"sm\">\n    <Badge variant=\"info\">SM</Badge>\n    <Badge variant=\"info\">Gap</Badge>\n  </Stack>\n  <Stack direction=\"row\" gap=\"md\">\n    <Badge variant=\"info\">MD</Badge>\n    <Badge variant=\"info\">Gap</Badge>\n  </Stack>\n  <Stack direction=\"row\" gap=\"lg\">\n    <Badge variant=\"info\">LG</Badge>\n    <Badge variant=\"info\">Gap</Badge>\n  </Stack>\n</Stack>"
-    },
-    {
-      "name": "Numeric Gap",
-      "description": "Using number values (1-8) mapped to the spacing scale",
-      "code": "<Stack gap=\"lg\">\n  <Stack direction=\"row\" gap={2}>\n    <Badge variant=\"info\">Gap 2</Badge>\n    <Badge variant=\"info\">Gap 2</Badge>\n  </Stack>\n  <Stack direction=\"row\" gap={4}>\n    <Badge variant=\"info\">Gap 4</Badge>\n    <Badge variant=\"info\">Gap 4</Badge>\n  </Stack>\n  <Stack direction=\"row\" gap={6}>\n    <Badge variant=\"info\">Gap 6</Badge>\n    <Badge variant=\"info\">Gap 6</Badge>\n  </Stack>\n</Stack>"
+      "description": "One spacing token sets every gap in the stack.",
+      "code": "import { Box } from '@/components/Box';\nimport { Stack } from '@/components/Stack';\n\n<Stack gap=\"lg\">\n  <Stack direction=\"row\" gap=\"xs\">\n    <Box background=\"secondary\" rounded=\"sm\" paddingX=\"md\" paddingY=\"sm\">xs</Box>\n    <Box background=\"secondary\" rounded=\"sm\" paddingX=\"md\" paddingY=\"sm\">xs</Box>\n  </Stack>\n  <Stack direction=\"row\" gap=\"sm\">\n    <Box background=\"secondary\" rounded=\"sm\" paddingX=\"md\" paddingY=\"sm\">sm</Box>\n    <Box background=\"secondary\" rounded=\"sm\" paddingX=\"md\" paddingY=\"sm\">sm</Box>\n  </Stack>\n  <Stack direction=\"row\" gap=\"md\">\n    <Box background=\"secondary\" rounded=\"sm\" paddingX=\"md\" paddingY=\"sm\">md</Box>\n    <Box background=\"secondary\" rounded=\"sm\" paddingX=\"md\" paddingY=\"sm\">md</Box>\n  </Stack>\n  <Stack direction=\"row\" gap=\"lg\">\n    <Box background=\"secondary\" rounded=\"sm\" paddingX=\"md\" paddingY=\"sm\">lg</Box>\n    <Box background=\"secondary\" rounded=\"sm\" paddingX=\"md\" paddingY=\"sm\">lg</Box>\n  </Stack>\n</Stack>"
     },
     {
       "name": "Alignment",
-      "description": "Cross-axis and main-axis alignment",
-      "code": "<Stack gap=\"md\">\n  <Stack direction=\"row\" gap=\"sm\" justify=\"between\" style={{ width: '200px', padding: '8px', background: 'var(--fui-bg-secondary)', borderRadius: '4px' }}>\n    <Badge>Start</Badge>\n    <Badge>End</Badge>\n  </Stack>\n  <Stack direction=\"row\" gap=\"sm\" justify=\"center\" style={{ width: '200px', padding: '8px', background: 'var(--fui-bg-secondary)', borderRadius: '4px' }}>\n    <Badge>Centered</Badge>\n  </Stack>\n</Stack>"
+      "description": "justify positions children along the main axis.",
+      "code": "import { Box } from '@/components/Box';\nimport { Stack } from '@/components/Stack';\n\n<Stack gap=\"md\">\n  <Box width=\"240px\" border rounded=\"sm\" padding=\"sm\">\n    <Stack direction=\"row\" gap=\"sm\" justify=\"between\">\n      <Box background=\"secondary\" rounded=\"sm\" paddingX=\"sm\" paddingY=\"xs\">Start</Box>\n      <Box background=\"secondary\" rounded=\"sm\" paddingX=\"sm\" paddingY=\"xs\">End</Box>\n    </Stack>\n  </Box>\n  <Box width=\"240px\" border rounded=\"sm\" padding=\"sm\">\n    <Stack direction=\"row\" gap=\"sm\" justify=\"center\">\n      <Box background=\"secondary\" rounded=\"sm\" paddingX=\"sm\" paddingY=\"xs\">Centered</Box>\n    </Stack>\n  </Box>\n</Stack>"
     },
     {
       "name": "Responsive",
-      "description": "Direction changes at breakpoints",
+      "description": "Swap direction and gap per breakpoint with an object value.",
       "code": "<Stack\n  direction={{ base: 'column', md: 'row' }}\n  gap={{ base: 'sm', md: 'lg' }}\n>\n  <Button variant=\"secondary\">First</Button>\n  <Button variant=\"secondary\">Second</Button>\n  <Button variant=\"secondary\">Third</Button>\n</Stack>"
     },
     {
       "name": "With Separator",
-      "description": "Default line separator between items",
-      "code": "<Stack gap=\"md\" separator>\n  <div>Section One</div>\n  <div>Section Two</div>\n  <div>Section Three</div>\n</Stack>"
+      "description": "Draws a divider between each child.",
+      "code": "import { Stack } from '@/components/Stack';\nimport { Text } from '@/components/Text';\n\n<Stack gap=\"md\" separator>\n  <Text>Section one</Text>\n  <Text>Section two</Text>\n  <Text>Section three</Text>\n</Stack>"
     },
     {
       "name": "Semantic Element",
-      "description": "Using nav element for navigation",
+      "description": "The as prop renders a real nav, section, or list element.",
       "code": "<Stack as=\"nav\" direction=\"row\" gap=\"md\">\n  <Button variant=\"ghost\" size=\"sm\">Home</Button>\n  <Button variant=\"ghost\" size=\"sm\">About</Button>\n  <Button variant=\"ghost\" size=\"sm\">Contact</Button>\n</Stack>"
     }
   ],
@@ -201,15 +178,11 @@
       "as: string - HTML element",
       "Pass-through DOM props supported on the root (id, role, aria-*, data-*, handlers)"
     ],
-    "a11yRules": [
-      "A11Y_SEMANTIC_ELEMENTS"
-    ]
+    "a11yRules": ["A11Y_SEMANTIC_ELEMENTS"]
   },
   "ai": {
     "compositionPattern": "compound",
-    "subComponents": [
-      "Root"
-    ]
+    "subComponents": ["Root"]
   },
   "provenance": {
     "source": "migrated",

package/src/components/Stack/Stack.module.scss

@@ -1,4 +1,5 @@
 @use "../../recipes/layout";
+@use "../../tokens/mixins" as *;
 @use "../../tokens/variables" as *;
 
 .stack {
@@ -19,18 +20,18 @@
 .directionResponsive {
   flex-direction: var(--fui-stack-direction, column);
 
-  @media (min-width: 640px) {
+  @include breakpoint-sm {
     flex-direction: var(--fui-stack-direction-sm, var(--fui-stack-direction, column));
   }
 
-  @media (min-width: 768px) {
+  @include breakpoint-md {
     flex-direction: var(
       --fui-stack-direction-md,
       var(--fui-stack-direction-sm, var(--fui-stack-direction, column))
     );
   }
 
-  @media (min-width: 1024px) {
+  @include breakpoint-lg {
     flex-direction: var(
       --fui-stack-direction-lg,
       var(
@@ -40,7 +41,7 @@
     );
   }
 
-  @media (min-width: 1280px) {
+  @include breakpoint-xl {
     flex-direction: var(
       --fui-stack-direction-xl,
       var(
@@ -58,22 +59,22 @@
 .gapResponsive {
   gap: var(--fui-stack-gap, #{layout.gap("none")});
 
-  @media (min-width: 640px) {
+  @include breakpoint-sm {
     gap: var(--fui-stack-gap-sm, var(--fui-stack-gap, 0));
   }
 
-  @media (min-width: 768px) {
+  @include breakpoint-md {
     gap: var(--fui-stack-gap-md, var(--fui-stack-gap-sm, var(--fui-stack-gap, 0)));
   }
 
-  @media (min-width: 1024px) {
+  @include breakpoint-lg {
     gap: var(
       --fui-stack-gap-lg,
       var(--fui-stack-gap-md, var(--fui-stack-gap-sm, var(--fui-stack-gap, 0)))
     );
   }
 
-  @media (min-width: 1280px) {
+  @include breakpoint-xl {
     gap: var(
       --fui-stack-gap-xl,
       var(
@@ -154,7 +155,7 @@
   height: var(--fui-stroke-hairline, 1px);
 }
 
-@media (min-width: 640px) {
+@include breakpoint-sm {
   .directionResponsive[data-direction-sm="row"] > .separator {
     width: var(--fui-stroke-hairline, 1px);
     height: auto;
@@ -167,7 +168,7 @@
   }
 }
 
-@media (min-width: 768px) {
+@include breakpoint-md {
   .directionResponsive[data-direction-md="row"] > .separator {
     width: var(--fui-stroke-hairline, 1px);
     height: auto;
@@ -180,7 +181,7 @@
   }
 }
 
-@media (min-width: 1024px) {
+@include breakpoint-lg {
   .directionResponsive[data-direction-lg="row"] > .separator {
     width: var(--fui-stroke-hairline, 1px);
     height: auto;
@@ -193,7 +194,7 @@
   }
 }
 
-@media (min-width: 1280px) {
+@include breakpoint-xl {
   .directionResponsive[data-direction-xl="row"] > .separator {
     width: var(--fui-stroke-hairline, 1px);
     height: auto;