@usefragments/ui 1.6.0 → 1.7.0

package/src/components/RadioGroup/RadioGroup.module.scss

@@ -74,27 +74,26 @@
   &[data-checked] {
     background-color: color-mix(
       in srgb,
-      var(--fui-button-primary-base, #{$fui-color-accent}) 8%,
+      var(--fui-control-checked-bg, #{$fui-color-accent}) 8%,
       var(--fui-field-bg, #{$fui-bg-elevated})
     );
-    border-color: var(--fui-button-primary-base, $fui-color-accent);
-    box-shadow: inset 0 0 0 1px
-      color-mix(in srgb, var(--fui-button-primary-base, #{$fui-color-accent}) 55%, transparent);
+    border-color: var(--fui-control-checked-border, $fui-color-accent);
+    box-shadow: inset 0 0 0 var(--fui-stroke-hairline, 1px)
+      color-mix(in srgb, var(--fui-control-checked-border, #{$fui-color-accent}) 55%, transparent);
   }
 
   &[data-checked]:hover:not([data-disabled]) {
     background-color: color-mix(
       in srgb,
-      var(--fui-button-primary-hover, #{$fui-color-accent}) 12%,
+      var(--fui-control-checked-bg-hover, #{$fui-color-accent-hover}) 12%,
       var(--fui-field-bg, #{$fui-bg-elevated})
     );
-    border-color: var(--fui-button-primary-hover, $fui-color-accent);
+    border-color: var(--fui-control-checked-border-hover, $fui-color-accent-hover);
   }
 
   &[data-invalid] {
     border-color: var(--fui-color-danger-text, $fui-color-danger-text);
   }
-
 }
 
 // Size variants
@@ -114,7 +113,7 @@
   left: 50%;
   width: var(--fui-raw-space-8, 8px);
   height: var(--fui-raw-space-8, 8px);
-  background-color: var(--fui-button-primary-base, $fui-color-accent);
+  background-color: var(--fui-control-checked-bg, $fui-color-accent);
   border-radius: var(--fui-radius-full, $fui-radius-full);
 
   // Animation - use translate for centering combined with scale
@@ -186,23 +185,23 @@
   }
 
   &:focus-within:not([data-disabled]) {
-    border-color: var(--fui-button-primary-base, $fui-color-accent);
+    border-color: var(--fui-control-checked-border, $fui-color-accent);
     @include focus-ring;
   }
 
   &:has([data-checked]) {
     background: color-mix(
       in srgb,
-      var(--fui-button-primary-base, #{$fui-color-accent}) 13%,
+      var(--fui-control-checked-bg, #{$fui-color-accent}) 13%,
       transparent
     );
     border-color: color-mix(
       in srgb,
-      var(--fui-button-primary-base, #{$fui-color-accent}) 62%,
+      var(--fui-control-checked-border, #{$fui-color-accent}) 62%,
       transparent
     );
-    box-shadow: 0 0 0 1px
-      color-mix(in srgb, var(--fui-button-primary-base, #{$fui-color-accent}) 28%, transparent);
+    box-shadow: 0 0 0 var(--fui-stroke-hairline, 1px)
+      color-mix(in srgb, var(--fui-control-checked-border, #{$fui-color-accent}) 28%, transparent);
   }
 
   &[data-size="sm"] {
@@ -233,7 +232,7 @@
     outline-offset: calc(-1 * var(--fui-stroke-default, 2px));
 
     &[data-checked] {
-      border-color: var(--fui-button-primary-base, $fui-color-accent);
+      border-color: var(--fui-control-checked-border, $fui-color-accent);
     }
 
     &[data-invalid] {

package/src/components/ScrollArea/ScrollArea.contract.json

@@ -1,7 +1,7 @@
 {
   "$schema": "https://usefragments.com/schemas/contract.v1.json",
   "name": "ScrollArea",
-  "description": "A styled scrollable container with thin scrollbars and optional fade indicators.",
+  "description": "Scrolls overflowing content with a slim scrollbar and optional edge fades.",
   "category": "layout",
   "tags": ["scroll", "overflow", "scrollbar", "container", "layout"],
   "status": "stable",
@@ -48,20 +48,19 @@
   },
   "usage": {
     "when": [
-      "Content overflows its container and needs scrolling",
-      "Horizontal tab bars or chip lists that may overflow",
-      "Scrollable panels, sidebars, or dropdown content",
-      "Any area where native scrollbars look too heavy"
+      "Content that overflows a fixed-size container",
+      "Tab bars or chip rows that may run past the edge",
+      "Scrollable panels, sidebars, and menu content"
     ],
     "whenNot": [
-      "Page-level scrolling (use native body scroll)",
-      "Very short content that never overflows"
+      "Whole-page scrolling (use the native body scroll)",
+      "Content that can never overflow"
     ],
     "guidelines": [
-      "Use `orientation` to constrain scroll direction",
-      "Use `showFades` to hint at hidden content beyond the viewport",
-      "The `auto` and `hover` modes keep the thumb quiet until hover or keyboard focus without changing track geometry",
-      "Combine with `orientation=\"horizontal\"` for tab bars and chip rows"
+      "orientation constrains which axis can scroll",
+      "showFades hints at hidden content when nothing else does",
+      "scrollbarVisibility=\"hover\" hides the thumb without shifting layout",
+      "The container needs a fixed height or the area cannot scroll"
     ],
     "accessibility": [
       "Preserves native scroll behavior and keyboard support across both axes",
@@ -72,23 +71,23 @@
   "examples": [
     {
       "name": "Vertical",
-      "description": "Vertical scrollable area with thin scrollbar.",
-      "code": "<ScrollArea style={{ height: '200px' }}>\n  {/* Long content */}\n</ScrollArea>"
+      "description": "Scrolls down with a thin, always-visible thumb.",
+      "code": "import { Box } from '@/components/Box';\nimport { ScrollArea } from '@/components/ScrollArea';\nimport { Stack } from '@/components/Stack';\nimport { Text } from '@/components/Text';\n\n<Box width=\"100%\">\n  <ScrollArea style={{ height: '200px' }}>\n    <Box padding=\"sm\">\n      <Stack gap=\"sm\">\n        <Text>Row 1</Text>\n        <Text>Row 2</Text>\n        <Text>Row 3</Text>\n        <Text>Row 4</Text>\n        <Text>Row 5</Text>\n        <Text>Row 6</Text>\n        <Text>Row 7</Text>\n        <Text>Row 8</Text>\n        <Text>Row 9</Text>\n        <Text>Row 10</Text>\n        <Text>Row 11</Text>\n        <Text>Row 12</Text>\n      </Stack>\n    </Box>\n  </ScrollArea>\n</Box>"
     },
     {
       "name": "Horizontal",
-      "description": "Horizontal scrollable area for overflowing inline content like tabs or chips.",
-      "code": "<ScrollArea orientation=\"horizontal\">\n  <div style={{ display: 'flex', gap: '8px' }}>\n    {tags.map(tag => <Chip key={tag}>{tag}</Chip>)}\n  </div>\n</ScrollArea>"
+      "description": "Keeps an overflowing row of chips on one line.",
+      "code": "import { Box } from '@/components/Box';\nimport { Chip } from '@/components/Chip';\nimport { ScrollArea } from '@/components/ScrollArea';\nimport { Stack } from '@/components/Stack';\n\n<Box width=\"100%\">\n  <ScrollArea orientation=\"horizontal\">\n    <Stack direction=\"row\" gap=\"sm\">\n      <Chip>React</Chip>\n      <Chip>TypeScript</Chip>\n      <Chip>Accessibility</Chip>\n      <Chip>Docs</Chip>\n      <Chip>Playground</Chip>\n      <Chip>CLI</Chip>\n      <Chip>Tokens</Chip>\n      <Chip>Governance</Chip>\n      <Chip>Contracts</Chip>\n      <Chip>Registry</Chip>\n    </Stack>\n  </ScrollArea>\n</Box>"
     },
     {
       "name": "With Fades",
-      "description": "Fade indicators independently show the available logical direction on each scrollable axis.",
-      "code": "<ScrollArea orientation=\"horizontal\" showFades>\n  {/* Overflowing content */}\n</ScrollArea>"
+      "description": "Edge fades signal there is more content each way.",
+      "code": "import { Box } from '@/components/Box';\nimport { Chip } from '@/components/Chip';\nimport { ScrollArea } from '@/components/ScrollArea';\nimport { Stack } from '@/components/Stack';\n\n<Box width=\"100%\">\n  <ScrollArea orientation=\"horizontal\" showFades>\n    <Stack direction=\"row\" gap=\"sm\">\n      <Chip>React</Chip>\n      <Chip>TypeScript</Chip>\n      <Chip>Accessibility</Chip>\n      <Chip>Docs</Chip>\n      <Chip>Playground</Chip>\n      <Chip>CLI</Chip>\n      <Chip>Tokens</Chip>\n      <Chip>Governance</Chip>\n      <Chip>Contracts</Chip>\n      <Chip>Registry</Chip>\n    </Stack>\n  </ScrollArea>\n</Box>"
     },
     {
       "name": "Hover Scrollbar",
-      "description": "Scrollbar thumb paint appears on hover or keyboard focus without changing track dimensions.",
-      "code": "<ScrollArea scrollbarVisibility=\"hover\" style={{ height: '200px' }}>\n  {/* Content */}\n</ScrollArea>"
+      "description": "Thumb stays invisible until hover or keyboard focus.",
+      "code": "import { Box } from '@/components/Box';\nimport { ScrollArea } from '@/components/ScrollArea';\nimport { Stack } from '@/components/Stack';\nimport { Text } from '@/components/Text';\n\n<Box width=\"100%\">\n  <ScrollArea scrollbarVisibility=\"hover\" style={{ height: '200px' }}>\n    <Box padding=\"sm\">\n      <Stack gap=\"sm\">\n        <Text>Row 1</Text>\n        <Text>Row 2</Text>\n        <Text>Row 3</Text>\n        <Text>Row 4</Text>\n        <Text>Row 5</Text>\n        <Text>Row 6</Text>\n        <Text>Row 7</Text>\n        <Text>Row 8</Text>\n        <Text>Row 9</Text>\n        <Text>Row 10</Text>\n        <Text>Row 11</Text>\n        <Text>Row 12</Text>\n      </Stack>\n    </Box>\n  </ScrollArea>\n</Box>"
     }
   ],
   "contract": {

package/src/components/ScrollArea/ScrollArea.module.scss

@@ -1,5 +1,5 @@
-@use '../../tokens/measurements.generated' as measurements;
-@use '../../tokens/variables' as *;
+@use "../../tokens/measurements.generated" as measurements;
+@use "../../tokens/variables" as *;
 
 .root {
   --fui-scrollarea-track-size: var(--fui-raw-space-6, #{measurements.raw-space(6)});
@@ -55,7 +55,7 @@
 
   &:hover,
   &:focus-within,
-  &[data-scrollbar-visibility='always'] {
+  &[data-scrollbar-visibility="always"] {
     scrollbar-color: var(--fui-border-strong, #{$fui-border-strong}) transparent;
 
     &::-webkit-scrollbar-thumb {
@@ -82,17 +82,17 @@
   overflow: auto;
 }
 
-.horizontal:not([data-scroll-x='none']),
-.both:not([data-scroll-x='none']) {
+.horizontal:not([data-scroll-x="none"]),
+.both:not([data-scroll-x="none"]) {
   scroll-padding-inline: var(--_fui-scrollarea-inline-fade);
 }
 
-.vertical:not([data-scroll-y='none']),
-.both:not([data-scroll-y='none']) {
+.vertical:not([data-scroll-y="none"]),
+.both:not([data-scroll-y="none"]) {
   scroll-padding-block: var(--_fui-scrollarea-block-fade);
 }
 
-.viewport[data-scroll-x='end'] {
+.viewport[data-scroll-x="end"] {
   --_fui-scrollarea-inline-mask: linear-gradient(
     to right,
     black calc(100% - var(--_fui-scrollarea-inline-fade)),
@@ -100,7 +100,7 @@
   );
 }
 
-.viewport[data-scroll-x='start'] {
+.viewport[data-scroll-x="start"] {
   --_fui-scrollarea-inline-mask: linear-gradient(
     to right,
     transparent,
@@ -108,7 +108,7 @@
   );
 }
 
-.viewport[data-scroll-x='both'] {
+.viewport[data-scroll-x="both"] {
   --_fui-scrollarea-inline-mask: linear-gradient(
     to right,
     transparent,
@@ -118,7 +118,7 @@
   );
 }
 
-.viewport[data-scroll-x='end']:dir(rtl) {
+.viewport[data-scroll-x="end"]:dir(rtl) {
   --_fui-scrollarea-inline-mask: linear-gradient(
     to right,
     transparent,
@@ -126,7 +126,7 @@
   );
 }
 
-.viewport[data-scroll-x='start']:dir(rtl) {
+.viewport[data-scroll-x="start"]:dir(rtl) {
   --_fui-scrollarea-inline-mask: linear-gradient(
     to right,
     black calc(100% - var(--_fui-scrollarea-inline-fade)),
@@ -134,7 +134,7 @@
   );
 }
 
-.viewport[data-scroll-y='end'] {
+.viewport[data-scroll-y="end"] {
   --_fui-scrollarea-block-mask: linear-gradient(
     to bottom,
     black calc(100% - var(--_fui-scrollarea-block-fade)),
@@ -142,7 +142,7 @@
   );
 }
 
-.viewport[data-scroll-y='start'] {
+.viewport[data-scroll-y="start"] {
   --_fui-scrollarea-block-mask: linear-gradient(
     to bottom,
     transparent,
@@ -150,7 +150,7 @@
   );
 }
 
-.viewport[data-scroll-y='both'] {
+.viewport[data-scroll-y="both"] {
   --_fui-scrollarea-block-mask: linear-gradient(
     to bottom,
     transparent,

package/src/components/ScrollArea/index.tsx

@@ -1,13 +1,13 @@
-'use client';
+"use client";
 
-import * as React from 'react';
-import styles from './ScrollArea.module.scss';
+import * as React from "react";
+import styles from "./ScrollArea.module.scss";
 import {
   detectRtlScrollModel,
   readScrollAxes,
   type ScrollAxesState,
   type ScrollOrientation,
-} from './scroll-state';
+} from "./scroll-state";
 
 // ============================================
 // Types
@@ -18,8 +18,8 @@ export interface ScrollAreaProps extends React.HTMLAttributes<HTMLDivElement> {
   /** Scroll direction */
   orientation?: ScrollOrientation;
   /** Scrollbar visibility behavior */
-  scrollbarVisibility?: 'auto' | 'always' | 'hover';
-  /** Whether to show fade indicators at scroll edges */
+  scrollbarVisibility?: "auto" | "always" | "hover";
+  /** Whether to show fade indicators at scroll edges. Defaults to false. */
   showFades?: boolean;
   /** Additional class name */
   className?: string;
@@ -37,15 +37,15 @@ export interface ScrollAreaProps extends React.HTMLAttributes<HTMLDivElement> {
  */
 function ScrollAreaRoot({
   children,
-  orientation = 'vertical',
-  scrollbarVisibility = 'auto',
+  orientation = "vertical",
+  scrollbarVisibility = "auto",
   showFades = false,
   className,
   dir,
   ...htmlProps
 }: ScrollAreaProps) {
   const viewportRef = React.useRef<HTMLDivElement>(null);
-  const [axes, setAxes] = React.useState<ScrollAxesState>({ x: 'none', y: 'none' });
+  const [axes, setAxes] = React.useState<ScrollAxesState>({ x: "none", y: "none" });
 
   React.useEffect(() => {
     const viewport = viewportRef.current;
@@ -58,11 +58,11 @@ function ScrollAreaRoot({
       frame = null;
       const view = viewport.ownerDocument.defaultView;
       const computedDirection = view?.getComputedStyle(viewport).direction;
-      const direction = (computedDirection || dir) === 'rtl' ? 'rtl' : 'ltr';
+      const direction = (computedDirection || dir) === "rtl" ? "rtl" : "ltr";
       const nextAxes = readScrollAxes(viewport, {
         orientation,
         direction,
-        rtlModel: direction === 'rtl' ? detectRtlScrollModel(viewport.ownerDocument) : undefined,
+        rtlModel: direction === "rtl" ? detectRtlScrollModel(viewport.ownerDocument) : undefined,
       });
 
       setAxes((currentAxes) =>
@@ -99,22 +99,22 @@ function ScrollAreaRoot({
     resizeObserver.observe(viewport);
     syncObservedChildren();
     mutationObserver.observe(viewport, { childList: true, subtree: true });
-    viewport.addEventListener('scroll', schedule, { passive: true });
+    viewport.addEventListener("scroll", schedule, { passive: true });
     schedule();
 
     return () => {
       if (frame !== null) cancelAnimationFrame(frame);
-      viewport.removeEventListener('scroll', schedule);
+      viewport.removeEventListener("scroll", schedule);
       resizeObserver.disconnect();
       mutationObserver.disconnect();
       observedChildren.clear();
     };
   }, [dir, orientation, showFades]);
 
-  const rootClasses = [styles.root, className].filter(Boolean).join(' ');
-  const visibleAxes = showFades ? axes : { x: 'none' as const, y: 'none' as const };
+  const rootClasses = [styles.root, className].filter(Boolean).join(" ");
+  const visibleAxes = showFades ? axes : { x: "none" as const, y: "none" as const };
 
-  const viewportClasses = [styles.viewport, styles[orientation]].filter(Boolean).join(' ');
+  const viewportClasses = [styles.viewport, styles[orientation]].filter(Boolean).join(" ");
 
   return (
     <div {...htmlProps} className={rootClasses} data-orientation={orientation} dir={dir}>

package/src/components/ScrollArea/scroll-state.ts

@@ -1,6 +1,6 @@
-export type ScrollOrientation = 'horizontal' | 'vertical' | 'both';
-export type ScrollEdgeState = 'none' | 'start' | 'end' | 'both';
-export type RtlScrollModel = 'negative' | 'positive-descending' | 'positive-ascending';
+export type ScrollOrientation = "horizontal" | "vertical" | "both";
+export type ScrollEdgeState = "none" | "start" | "end" | "both";
+export type RtlScrollModel = "negative" | "positive-descending" | "positive-ascending";
 
 export interface ScrollAxesState {
   x: ScrollEdgeState;
@@ -16,21 +16,21 @@ export function detectRtlScrollModel(document: Document): RtlScrollModel {
   const cachedModel = rtlScrollModels.get(document);
   if (cachedModel) return cachedModel;
 
-  const viewport = document.createElement('div');
-  const content = document.createElement('div');
-  viewport.dir = 'rtl';
+  const viewport = document.createElement("div");
+  const content = document.createElement("div");
+  viewport.dir = "rtl";
   viewport.style.cssText =
-    'position:absolute;inset-block-start:-9999px;inline-size:4px;block-size:1px;overflow:scroll;visibility:hidden';
-  content.style.cssText = 'inline-size:8px;block-size:1px';
+    "position:absolute;inset-block-start:-9999px;inline-size:4px;block-size:1px;overflow:scroll;visibility:hidden";
+  content.style.cssText = "inline-size:8px;block-size:1px";
   viewport.append(content);
   (document.body ?? document.documentElement).append(viewport);
 
   let model: RtlScrollModel;
   if (viewport.scrollLeft > 0) {
-    model = 'positive-descending';
+    model = "positive-descending";
   } else {
     viewport.scrollLeft = 1;
-    model = viewport.scrollLeft === 0 ? 'negative' : 'positive-ascending';
+    model = viewport.scrollLeft === 0 ? "negative" : "positive-ascending";
   }
 
   viewport.remove();
@@ -43,37 +43,37 @@ function clamp(value: number, min: number, max: number): number {
 }
 
 function resolveEdgeState(distanceFromStart: number, maxScroll: number): ScrollEdgeState {
-  if (maxScroll <= SCROLL_EDGE_EPSILON_PX) return 'none';
-  if (distanceFromStart <= SCROLL_EDGE_EPSILON_PX) return 'end';
-  if (maxScroll - distanceFromStart <= SCROLL_EDGE_EPSILON_PX) return 'start';
-  return 'both';
+  if (maxScroll <= SCROLL_EDGE_EPSILON_PX) return "none";
+  if (distanceFromStart <= SCROLL_EDGE_EPSILON_PX) return "end";
+  if (maxScroll - distanceFromStart <= SCROLL_EDGE_EPSILON_PX) return "start";
+  return "both";
 }
 
 export function readScrollAxes(
   element: Pick<
     HTMLElement,
-    'clientWidth' | 'clientHeight' | 'scrollWidth' | 'scrollHeight' | 'scrollLeft' | 'scrollTop'
+    "clientWidth" | "clientHeight" | "scrollWidth" | "scrollHeight" | "scrollLeft" | "scrollTop"
   >,
   options: {
     orientation: ScrollOrientation;
-    direction: 'ltr' | 'rtl';
+    direction: "ltr" | "rtl";
     rtlModel?: RtlScrollModel;
   }
 ): ScrollAxesState {
-  const allowX = options.orientation === 'horizontal' || options.orientation === 'both';
-  const allowY = options.orientation === 'vertical' || options.orientation === 'both';
+  const allowX = options.orientation === "horizontal" || options.orientation === "both";
+  const allowY = options.orientation === "vertical" || options.orientation === "both";
 
   const maxX = Math.max(0, element.scrollWidth - element.clientWidth);
   const maxY = Math.max(0, element.scrollHeight - element.clientHeight);
 
-  let x: ScrollEdgeState = 'none';
+  let x: ScrollEdgeState = "none";
   if (allowX) {
     let logicalScrollLeft = element.scrollLeft;
-    if (options.direction === 'rtl') {
-      const rtlModel = options.rtlModel ?? 'negative';
-      if (rtlModel === 'negative') {
+    if (options.direction === "rtl") {
+      const rtlModel = options.rtlModel ?? "negative";
+      if (rtlModel === "negative") {
         logicalScrollLeft = -element.scrollLeft;
-      } else if (rtlModel === 'positive-descending') {
+      } else if (rtlModel === "positive-descending") {
         logicalScrollLeft = maxX - element.scrollLeft;
       }
     }
@@ -81,7 +81,7 @@ export function readScrollAxes(
     x = resolveEdgeState(clamp(logicalScrollLeft, 0, maxX), maxX);
   }
 
-  const y = allowY ? resolveEdgeState(clamp(element.scrollTop, 0, maxY), maxY) : 'none';
+  const y = allowY ? resolveEdgeState(clamp(element.scrollTop, 0, maxY), maxY) : "none";
 
   return { x, y };
 }

package/src/components/Select/Select.module.scss

@@ -85,7 +85,7 @@
   // it owns is on screen.
   &[data-popup-open] {
     border-color: transparent;
-    background-color: var(--fui-bg-tertiary, $fui-bg-tertiary);
+    background-color: var(--fui-control-selected-bg, $fui-bg-active);
     color: var(--fui-text-primary, $fui-text-primary);
   }
 
@@ -259,7 +259,7 @@
 
 @media (prefers-contrast: more) {
   .trigger {
-    border-width: 2px;
+    border-width: var(--fui-stroke-default, 2px);
     border-color: var(--fui-text-primary, $fui-text-primary);
 
     &[data-popup-open] {

package/src/components/Separator/Separator.contract.json

@@ -1,15 +1,9 @@
 {
   "$schema": "https://usefragments.com/schemas/contract.v1.json",
   "name": "Separator",
-  "description": "Visual divider between content sections. Use to create clear visual boundaries and improve content organization.",
+  "description": "Draws a rule between sections of related content.",
   "category": "layout",
-  "tags": [
-    "separator",
-    "divider",
-    "hr",
-    "line",
-    "layout"
-  ],
+  "tags": ["separator", "divider", "hr", "line", "layout"],
   "status": "stable",
   "sourcePath": "src/components/Separator/index.tsx",
   "exportName": "Separator",
@@ -26,22 +20,14 @@
       "description": "Direction of the separator",
       "default": "horizontal",
       "required": false,
-      "values": [
-        "horizontal",
-        "vertical"
-      ]
+      "values": ["horizontal", "vertical"]
     },
     "spacing": {
       "type": "enum",
       "description": "Margin around the separator",
       "default": "none",
       "required": false,
-      "values": [
-        "none",
-        "sm",
-        "md",
-        "lg"
-      ]
+      "values": ["none", "sm", "md", "lg"]
     },
     "soft": {
       "type": "boolean",
@@ -62,21 +48,20 @@
   },
   "usage": {
     "when": [
-      "Dividing content sections",
-      "Separating groups of related items",
-      "Creating visual breathing room",
-      "Labeled section breaks"
+      "Dividing sections that spacing alone cannot separate",
+      "Labelled breaks such as an Or divider",
+      "Splitting items inside a toolbar or row"
     ],
     "whenNot": [
-      "Creating grid layouts (use CSS Grid)",
-      "Decorative borders (use CSS)",
-      "Spacing alone is sufficient"
+      "Whenever spacing already reads as a break",
+      "Decorative rules (use a border)",
+      "Building layout structure (use Grid)"
     ],
     "guidelines": [
-      "Use sparingly - too many separators create visual noise",
-      "Consider if spacing alone would work",
-      "Use soft variant for subtle separation",
-      "Labeled separators work well for major section breaks"
+      "Use sparingly — stacked rules read as noise",
+      "soft halves the rule's weight for quieter breaks",
+      "orientation=\"vertical\" needs a parent with a set height",
+      "Add aria-hidden when the rule is purely decorative"
     ],
     "accessibility": [
       "Uses role=\"separator\" for semantic meaning",
@@ -86,28 +71,23 @@
   "examples": [
     {
       "name": "Default",
-      "description": "Basic horizontal separator",
-      "code": "<div style={{ width: '300px' }}>\n  <p>Content above</p>\n  <Separator spacing=\"md\" />\n  <p>Content below</p>\n</div>"
+      "description": "Standard and soft weights, one above the other.",
+      "code": "import { Box } from '@/components/Box';\nimport { Separator } from '@/components/Separator';\nimport { Text } from '@/components/Text';\n\n<Box width=\"100%\">\n  <Text>Standard weight</Text>\n  <Separator spacing=\"md\" />\n  <Text>Soft weight</Text>\n  <Separator soft spacing=\"md\" />\n  <Text>Below</Text>\n</Box>"
     },
     {
       "name": "With Label",
-      "description": "Labeled section divider",
-      "code": "<div style={{ width: '300px' }}>\n  <p>First section</p>\n  <Separator label=\"Or\" spacing=\"md\" />\n  <p>Second section</p>\n</div>"
-    },
-    {
-      "name": "Soft",
-      "description": "Subtle separator",
-      "code": "<div style={{ width: '300px' }}>\n  <p>Content above</p>\n  <Separator soft spacing=\"md\" />\n  <p>Content below</p>\n</div>"
+      "description": "A label sits inside the rule for a major break.",
+      "code": "import { Box } from '@/components/Box';\nimport { Separator } from '@/components/Separator';\nimport { Text } from '@/components/Text';\n\n<Box width=\"100%\">\n  <Text>First section</Text>\n  <Separator label=\"Or\" spacing=\"md\" />\n  <Text>Second section</Text>\n</Box>"
     },
     {
       "name": "Vertical",
-      "description": "Vertical separator between elements",
-      "code": "<div style={{ display: 'flex', alignItems: 'center', gap: '16px', height: '40px' }}>\n  <span>Item 1</span>\n  <Separator orientation=\"vertical\" />\n  <span>Item 2</span>\n  <Separator orientation=\"vertical\" />\n  <span>Item 3</span>\n</div>"
+      "description": "Divides items sitting in a row.",
+      "code": "import { Box } from '@/components/Box';\nimport { Separator } from '@/components/Separator';\nimport { Stack } from '@/components/Stack';\nimport { Text } from '@/components/Text';\n\n<Stack direction=\"row\" align=\"center\" gap=\"md\" style={{ height: '40px' }}>\n  <Text>Item 1</Text>\n  <Separator orientation=\"vertical\" />\n  <Text>Item 2</Text>\n  <Separator orientation=\"vertical\" />\n  <Text>Item 3</Text>\n</Stack>"
     },
     {
       "name": "Spacing Options",
-      "description": "Different spacing sizes",
-      "code": "<div style={{ width: '300px' }}>\n  <p>No spacing</p>\n  <Separator spacing=\"none\" />\n  <p>Small spacing</p>\n  <Separator spacing=\"sm\" />\n  <p>Medium spacing</p>\n  <Separator spacing=\"md\" />\n  <p>Large spacing</p>\n  <Separator spacing=\"lg\" />\n  <p>End</p>\n</div>"
+      "description": "spacing sets the breathing room around the rule.",
+      "code": "import { Box } from '@/components/Box';\nimport { Separator } from '@/components/Separator';\nimport { Text } from '@/components/Text';\n\n<Box width=\"100%\">\n  <Text>none</Text>\n  <Separator spacing=\"none\" />\n  <Text>sm</Text>\n  <Separator spacing=\"sm\" />\n  <Text>md</Text>\n  <Separator spacing=\"md\" />\n  <Text>lg</Text>\n  <Separator spacing=\"lg\" />\n  <Text>End</Text>\n</Box>"
     }
   ],
   "relations": [
@@ -124,15 +104,11 @@
       "soft: boolean - lighter appearance",
       "label: string - centered label text"
     ],
-    "a11yRules": [
-      "A11Y_SEPARATOR_ROLE"
-    ]
+    "a11yRules": ["A11Y_SEPARATOR_ROLE"]
   },
   "ai": {
     "compositionPattern": "compound",
-    "subComponents": [
-      "Root"
-    ]
+    "subComponents": ["Root"]
   },
   "provenance": {
     "source": "migrated",