@usefragments/ui 1.6.0 → 2.0.0

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

@@ -1,21 +1,15 @@
 {
   "$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",
   "propsSummary": [
     "orientation: horizontal|vertical (default: horizontal)",
-    "spacing: none|sm|md|lg (default: none)",
+    "gap: none|xs|sm|md|lg|xl (default: none)",
     "soft: boolean (default: false)",
     "label: string",
     "style: object"
@@ -26,22 +20,14 @@
       "description": "Direction of the separator",
       "default": "horizontal",
       "required": false,
-      "values": [
-        "horizontal",
-        "vertical"
-      ]
+      "values": ["horizontal", "vertical"]
     },
-    "spacing": {
+    "gap": {
       "type": "enum",
-      "description": "Margin around the separator",
+      "description": "Breathing room around the rule",
       "default": "none",
       "required": false,
-      "values": [
-        "none",
-        "sm",
-        "md",
-        "lg"
-      ]
+      "values": ["none", "xs", "sm", "md", "lg", "xl"]
     },
     "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 gap=\"md\" />\n  <Text>Soft weight</Text>\n  <Separator soft gap=\"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\" gap=\"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>"
+      "name": "Gap Options",
+      "description": "gap 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 gap=\"none\" />\n  <Text>sm</Text>\n  <Separator gap=\"sm\" />\n  <Text>md</Text>\n  <Separator gap=\"md\" />\n  <Text>lg</Text>\n  <Separator gap=\"lg\" />\n  <Text>End</Text>\n</Box>"
     }
   ],
   "relations": [
@@ -120,19 +100,15 @@
   "contract": {
     "propsSummary": [
       "orientation: horizontal|vertical - direction",
-      "spacing: none|sm|md|lg - margin",
+      "gap: none|xs|sm|md|lg|xl - breathing room",
       "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",

package/src/components/Separator/Separator.module.scss

@@ -1,6 +1,7 @@
 @use "../../recipes/layout";
 @use "../../recipes/typography";
 @use "../../tokens/variables" as *;
+@use "../../tokens/measurements.generated" as measurements;
 
 .separator {
   flex-shrink: 0;
@@ -9,25 +10,25 @@
 
 // Horizontal (default)
 .horizontal {
-  width: 100%;
+  inline-size: 100%;
 
   .line {
     display: block;
-    width: 100%;
-    height: var(--fui-stroke-hairline, 1px);
+    inline-size: 100%;
+    block-size: var(--fui-stroke-hairline, #{$fui-stroke-hairline});
     background-color: var(--fui-border, $fui-border);
   }
 }
 
 // Vertical
 .vertical {
-  height: auto;
+  block-size: auto;
   align-self: stretch;
 
   .line {
     display: block;
-    width: var(--fui-stroke-hairline, 1px);
-    height: 100%;
+    inline-size: var(--fui-stroke-hairline, #{$fui-stroke-hairline});
+    block-size: 100%;
     background-color: var(--fui-border, $fui-border);
   }
 }
@@ -43,7 +44,7 @@
   &::after {
     content: "";
     flex: 1;
-    height: var(--fui-stroke-hairline, 1px);
+    block-size: var(--fui-stroke-hairline, #{$fui-stroke-hairline});
     background-color: var(--fui-border, $fui-border);
   }
 }
@@ -52,51 +53,34 @@
   @include typography.role("ui-compact");
 
   color: var(--fui-text-tertiary, $fui-text-tertiary);
-  text-transform: uppercase;
   white-space: nowrap;
 }
 
-// Spacing variants
-.spacingNone {
-  padding: 0;
+// Gap: breathing room on the cross axis of the rule.
+.gapNone {
+  padding: var(--fui-raw-space-0, #{measurements.raw-space(0)});
 }
 
-.spacingSm {
-  &.horizontal {
-    padding-block: layout.gap("sm");
-  }
-
-  &.vertical {
-    padding-inline: layout.gap("sm");
-  }
-}
-
-.spacingMd {
-  &.horizontal {
-    padding-block: layout.gap("md");
-  }
-
-  &.vertical {
-    padding-inline: layout.gap("md");
-  }
-}
-
-.spacingLg {
-  &.horizontal {
-    padding-block: layout.gap("lg");
-  }
+@each $gap, $class in ("xs": "gapXs", "sm": "gapSm", "md": "gapMd", "lg": "gapLg", "xl": "gapXl") {
+  .#{$class} {
+    &.horizontal,
+    &.withLabel {
+      padding-block: layout.gap($gap);
+    }
 
-  &.vertical {
-    padding-inline: layout.gap("lg");
+    &.vertical {
+      padding-inline: layout.gap($gap);
+    }
   }
 }
 
-// Soft variant (lighter color)
+// Soft: half-weight rule for quieter breaks. Shares the disabled opacity step
+// (0.5) — there is no dedicated soft-rule token yet.
 .soft {
-  opacity: 0.5;
+  opacity: var(--fui-opacity-disabled, #{$fui-opacity-disabled});
 
   &.withLabel::before,
   &.withLabel::after {
-    opacity: 0.5;
+    opacity: var(--fui-opacity-disabled, #{$fui-opacity-disabled});
   }
 }

package/src/components/Separator/index.tsx

@@ -8,11 +8,14 @@ import styles from "./Separator.module.scss";
 // Types
 // ============================================
 
+export type SeparatorGap = "none" | "xs" | "sm" | "md" | "lg" | "xl";
+
 export interface SeparatorProps extends Omit<React.HTMLAttributes<HTMLDivElement>, "children"> {
   /** Orientation of the separator */
   orientation?: "horizontal" | "vertical";
-  /** Spacing around the separator */
-  spacing?: "none" | "sm" | "md" | "lg";
+  /** Breathing room around the rule
+   * @default "none" */
+  gap?: SeparatorGap;
   /** Softer visual appearance */
   soft?: boolean;
   /** Optional label text (creates a labeled divider) */
@@ -20,14 +23,16 @@ export interface SeparatorProps extends Omit<React.HTMLAttributes<HTMLDivElement
 }
 
 // ============================================
-// Spacing class map
+// Gap class map
 // ============================================
 
-const spacingClasses = {
-  none: styles.spacingNone,
-  sm: styles.spacingSm,
-  md: styles.spacingMd,
-  lg: styles.spacingLg,
+const GAP_CLASS: Record<SeparatorGap, string> = {
+  none: styles.gapNone,
+  xs: styles.gapXs,
+  sm: styles.gapSm,
+  md: styles.gapMd,
+  lg: styles.gapLg,
+  xl: styles.gapXl,
 };
 
 // ============================================
@@ -37,7 +42,7 @@ const spacingClasses = {
 const SeparatorRoot = React.forwardRef<HTMLDivElement, SeparatorProps>(function Separator(
   {
     orientation = "horizontal",
-    spacing = "none",
+    gap = "none",
     soft = false,
     label,
     className,
@@ -51,7 +56,7 @@ const SeparatorRoot = React.forwardRef<HTMLDivElement, SeparatorProps>(function
     const classes = [
       styles.separator,
       styles.withLabel,
-      spacingClasses[spacing],
+      GAP_CLASS[gap],
       soft && styles.soft,
       className,
     ]
@@ -76,7 +81,7 @@ const SeparatorRoot = React.forwardRef<HTMLDivElement, SeparatorProps>(function
   const classes = [
     styles.separator,
     orientation === "horizontal" ? styles.horizontal : styles.vertical,
-    spacingClasses[spacing],
+    GAP_CLASS[gap],
     soft && styles.soft,
     className,
   ]

package/src/components/Sidebar/Sidebar.contract.json

@@ -1,15 +1,9 @@
 {
   "$schema": "https://usefragments.com/schemas/contract.v1.json",
   "name": "Sidebar",
-  "description": "Responsive navigation sidebar with collapsible desktop mode and mobile drawer behavior.",
-  "category": "navigation",
-  "tags": [
-    "sidebar",
-    "navigation",
-    "drawer",
-    "menu",
-    "layout"
-  ],
+  "description": "Collapsible navigation panel that turns into a drawer on mobile.",
+  "category": "layout",
+  "tags": ["sidebar", "navigation", "drawer", "menu", "layout"],
   "status": "stable",
   "sourcePath": "src/components/Sidebar/index.tsx",
   "exportName": "Sidebar",
@@ -83,31 +77,21 @@
       "description": "Sidebar position",
       "default": "left",
       "required": false,
-      "values": [
-        "left",
-        "right"
-      ]
+      "values": ["left", "right"]
     },
     "collapsible": {
       "type": "enum",
       "description": "Collapse behavior mode",
       "default": "icon",
       "required": false,
-      "values": [
-        "icon",
-        "offcanvas",
-        "none"
-      ]
+      "values": ["icon", "offcanvas", "none"]
     },
     "activeIndicator": {
       "type": "enum",
       "description": "Placement of the active-item affordance",
       "default": "start",
       "required": false,
-      "values": [
-        "start",
-        "end"
-      ]
+      "values": ["start", "end"]
     },
     "style": {
       "type": "object",
@@ -117,32 +101,22 @@
   },
   "usage": {
     "when": [
-      "Primary app navigation with multiple sections",
-      "Dashboard layouts requiring persistent navigation",
-      "Admin interfaces with hierarchical menu structure",
-      "Apps that need both mobile drawer and desktop sidebar"
+      "Primary navigation for an app shell",
+      "Navigation that must collapse to icons or hide entirely",
+      "Grouped destinations with active state"
     ],
     "whenNot": [
-      "Simple websites with few pages (use header nav)",
-      "Content-focused sites where navigation is secondary",
-      "Single-page applications with no navigation needs",
-      "Mobile-only apps where bottom navigation is preferred"
+      "Top-level horizontal navigation (use Header)",
+      "Temporary side panels for one task (use Drawer)",
+      "In-page section links (use a list of links)"
     ],
     "guidelines": [
-      "Group related items into sections with clear labels",
-      "Use icons for all items to support collapsed mode",
-      "Limit nesting to 2 levels maximum",
-      "Place most frequently used items at the top",
-      "Use badges sparingly for notifications or counts",
-      "The `active` prop on items should be controlled by your app based on current route",
-      "Use activeIndicator=\"end\" when the product language calls for a trailing status dot instead of the default start rail",
-      "Use `collapsedContent` on Header to show just a logo icon when collapsed",
-      "Submenus are hidden when collapsed - use tooltips for navigation hints instead",
-      "Use SidebarProvider to enable external triggers and keyboard shortcuts",
-      "Use asChild with routing libraries (Next.js Link, React Router NavLink)",
-      "Sidebar.Item and Sidebar.SubItem onClick handlers receive the click event object",
-      "Use `multiline` on Sidebar.Item when the row is a list entry rather than a nav link — a title over a status or preview line. Without it the label is one truncating line",
-      "Use Sidebar.MenuSkeleton while loading navigation data"
+      "Give every item an icon so the collapsed rail stays readable",
+      "collapsible=\"icon\" shrinks to a rail; \"offcanvas\" hides it completely",
+      "Wrap in SidebarProvider only when something outside must toggle it",
+      "An explicit collapsed prop overrides any surrounding provider",
+      "Sidebar.Rail and Sidebar.CollapseToggle are alternative toggles — pick one",
+      "Use Sidebar.MenuSkeleton while navigation data loads"
     ],
     "accessibility": [
       "Uses semantic <nav> element with aria-label",
@@ -157,57 +131,57 @@
   "examples": [
     {
       "name": "Default",
-      "description": "Standard sidebar with navigation sections. The `active` prop highlights the current page.",
+      "description": "Sections group items; active marks the current page.",
       "code": "<Sidebar>\n  <Sidebar.Header>\n    <Logo />\n    <span>Acme App</span>\n  </Sidebar.Header>\n  <Sidebar.Nav>\n    <Sidebar.Section>\n      <Sidebar.Item icon={<HomeIcon />} active>Dashboard</Sidebar.Item>\n      <Sidebar.Item icon={<ChartIcon />}>Analytics</Sidebar.Item>\n      <Sidebar.Item icon={<UsersIcon />}>Team</Sidebar.Item>\n      <Sidebar.Item icon={<FolderIcon />}>Projects</Sidebar.Item>\n    </Sidebar.Section>\n    <Sidebar.Section label=\"Settings\">\n      <Sidebar.Item icon={<GearIcon />}>Preferences</Sidebar.Item>\n      <Sidebar.Item icon={<HelpIcon />}>Help</Sidebar.Item>\n    </Sidebar.Section>\n  </Sidebar.Nav>\n  <Sidebar.Footer>\n    <Sidebar.CollapseToggle />\n  </Sidebar.Footer>\n</Sidebar>"
     },
     {
       "name": "Collapsed",
-      "description": "Icon-only collapsed state. Header shows only logo, tooltips appear on hover.",
+      "description": "Icon-only rail; labels move into hover tooltips.",
       "code": "function App() {\n  const [collapsed, setCollapsed] = useState(true);\n\n  return (\n    <Sidebar collapsed={collapsed} onCollapsedChange={setCollapsed}>\n      <Sidebar.Header collapsedContent={<Logo />}>\n        <Logo />\n        <span>Acme App</span>\n      </Sidebar.Header>\n      <Sidebar.Nav>\n        <Sidebar.Section>\n          <Sidebar.Item icon={<HomeIcon />} active>Dashboard</Sidebar.Item>\n          <Sidebar.Item icon={<ChartIcon />}>Analytics</Sidebar.Item>\n        </Sidebar.Section>\n      </Sidebar.Nav>\n      <Sidebar.Footer>\n        <Sidebar.CollapseToggle />\n      </Sidebar.Footer>\n    </Sidebar>\n  );\n}"
     },
     {
       "name": "With Badges",
-      "description": "Navigation items with notification badges for counts or alerts.",
+      "description": "Trailing counts for unread or pending work.",
       "code": "<Sidebar>\n  <Sidebar.Nav>\n    <Sidebar.Section>\n      <Sidebar.Item icon={<HomeIcon />} active>Dashboard</Sidebar.Item>\n      <Sidebar.Item icon={<ChartIcon />} badge=\"3\">Analytics</Sidebar.Item>\n      <Sidebar.Item icon={<UsersIcon />} badge=\"12\">Team</Sidebar.Item>\n      <Sidebar.Item icon={<FolderIcon />}>Projects</Sidebar.Item>\n    </Sidebar.Section>\n  </Sidebar.Nav>\n</Sidebar>"
     },
     {
       "name": "With Submenu",
-      "description": "Nested navigation with expandable sections. Use defaultExpanded for initial state without manual state tracking.",
+      "description": "Nested items; defaultExpanded sets the opening state.",
       "code": "<Sidebar>\n  <Sidebar.Nav>\n    <Sidebar.Section>\n      <Sidebar.Item icon={<HomeIcon />}>Dashboard</Sidebar.Item>\n      {/* Use defaultExpanded for uncontrolled mode - no state needed! */}\n      <Sidebar.Item icon={<FolderIcon />} hasSubmenu defaultExpanded>\n        Projects\n      </Sidebar.Item>\n      <Sidebar.Submenu>\n        <Sidebar.SubItem active>Website Redesign</Sidebar.SubItem>\n        <Sidebar.SubItem>Mobile App</Sidebar.SubItem>\n        <Sidebar.SubItem>API Integration</Sidebar.SubItem>\n      </Sidebar.Submenu>\n      {/* Multiple submenus work without tracking separate state */}\n      <Sidebar.Item icon={<UsersIcon />} hasSubmenu>\n        Team\n      </Sidebar.Item>\n      <Sidebar.Submenu>\n        <Sidebar.SubItem>Engineering</Sidebar.SubItem>\n        <Sidebar.SubItem>Design</Sidebar.SubItem>\n      </Sidebar.Submenu>\n    </Sidebar.Section>\n  </Sidebar.Nav>\n</Sidebar>"
     },
     {
       "name": "With Disabled Items",
-      "description": "Some navigation items are disabled for permissions or feature flags.",
+      "description": "Items switched off by permissions or feature flags.",
       "code": "<Sidebar>\n  <Sidebar.Nav>\n    <Sidebar.Section>\n      <Sidebar.Item icon={<HomeIcon />} active>Dashboard</Sidebar.Item>\n      <Sidebar.Item icon={<ChartIcon />}>Analytics</Sidebar.Item>\n      <Sidebar.Item icon={<UsersIcon />} disabled>\n        Team (Coming Soon)\n      </Sidebar.Item>\n      <Sidebar.Item icon={<FolderIcon />} disabled>\n        Projects (Upgrade)\n      </Sidebar.Item>\n    </Sidebar.Section>\n  </Sidebar.Nav>\n</Sidebar>"
     },
     {
       "name": "With Provider & External Trigger",
-      "description": "SidebarProvider enables external triggers and keyboard shortcuts (Cmd/Ctrl+B).",
-      "code": "function App() {\n  return (\n    <SidebarProvider>\n      <Sidebar>\n        <Sidebar.Header>\n          <Logo />\n          <span>Acme App</span>\n          <Sidebar.CollapseToggle />\n        </Sidebar.Header>\n        {/* sidebar nav */}\n      </Sidebar>\n      <MainContent />\n    </SidebarProvider>\n  );\n}\n\nfunction MainContent() {\n  const { toggleSidebar, state } = useSidebar();\n  return (\n    <main>\n      <p>State: {state}</p>\n      <button onClick={toggleSidebar}>Toggle</button>\n    </main>\n  );\n}"
+      "description": "useSidebar drives the sidebar from anywhere, plus Cmd/Ctrl+B.",
+      "code": "function App() {\n  return (\n    <SidebarProvider>\n      <Stack direction=\"row\" gap=\"lg\" align=\"start\">\n        <Sidebar>\n          <Sidebar.Header>\n            <Logo />\n            <span>Acme App</span>\n          </Sidebar.Header>\n          <Sidebar.Nav>\n            <Sidebar.Section>\n              <Sidebar.Item icon={<HomeIcon />} active>Dashboard</Sidebar.Item>\n              <Sidebar.Item icon={<ChartIcon />}>Analytics</Sidebar.Item>\n            </Sidebar.Section>\n          </Sidebar.Nav>\n        </Sidebar>\n        <MainContent />\n      </Stack>\n    </SidebarProvider>\n  );\n}\n\nfunction MainContent() {\n  const { toggleSidebar, state } = useSidebar();\n\n  return (\n    <Stack gap=\"sm\" align=\"start\">\n      <Text scale=\"sm\" color=\"secondary\">State: {state}</Text>\n      <Button size=\"sm\" variant=\"soft\" onClick={toggleSidebar}>\n        Toggle sidebar\n      </Button>\n    </Stack>\n  );\n}"
     },
     {
       "name": "With asChild (Polymorphic)",
-      "description": "Use asChild to render items as custom elements like Next.js Link or React Router NavLink.",
-      "code": "import { Link } from 'next/link';\n\n<Sidebar>\n  <Sidebar.Nav>\n    <Sidebar.Section>\n      <Sidebar.Item icon={<HomeIcon />} active asChild>\n        <Link href=\"/dashboard\">Dashboard</Link>\n      </Sidebar.Item>\n      <Sidebar.Item icon={<ChartIcon />} asChild>\n        <Link href=\"/analytics\">Analytics</Link>\n      </Sidebar.Item>\n    </Sidebar.Section>\n  </Sidebar.Nav>\n</Sidebar>"
+      "description": "Render items as your router's link component.",
+      "code": "import Link from 'next/link';\n\n<Sidebar>\n  <Sidebar.Nav>\n    <Sidebar.Section>\n      <Sidebar.Item icon={<HomeIcon />} active asChild>\n        <Link href=\"/dashboard\">Dashboard</Link>\n      </Sidebar.Item>\n      <Sidebar.Item icon={<ChartIcon />} asChild>\n        <Link href=\"/analytics\">Analytics</Link>\n      </Sidebar.Item>\n    </Sidebar.Section>\n  </Sidebar.Nav>\n</Sidebar>"
     },
     {
       "name": "With Section Action",
-      "description": "Section headers can include action buttons for quick actions like \"Add Project\".",
+      "description": "A section header can carry one quick action.",
       "code": "<Sidebar>\n  <Sidebar.Nav>\n    <Sidebar.Section\n      label=\"Projects\"\n      action={\n        <Sidebar.SectionAction aria-label=\"Add project\" onClick={handleAdd}>\n          <PlusIcon />\n        </Sidebar.SectionAction>\n      }\n    >\n      <Sidebar.Item icon={<FolderIcon />}>Website Redesign</Sidebar.Item>\n      <Sidebar.Item icon={<FolderIcon />}>Mobile App</Sidebar.Item>\n    </Sidebar.Section>\n  </Sidebar.Nav>\n</Sidebar>"
     },
     {
       "name": "With Loading Skeleton",
-      "description": "Show skeleton placeholders while navigation data is loading.",
-      "code": "<Sidebar>\n  <Sidebar.Nav>\n    {loading ? (\n      <Sidebar.MenuSkeleton count={6} />\n    ) : (\n      <Sidebar.Section>\n        <Sidebar.Item icon={<HomeIcon />}>Dashboard</Sidebar.Item>\n        {/* ... */}\n      </Sidebar.Section>\n    )}\n  </Sidebar.Nav>\n</Sidebar>"
+      "description": "Placeholder rows to show while navigation data loads.",
+      "code": "<Sidebar>\n  <Sidebar.Header>\n    <Logo />\n    <span>Acme App</span>\n  </Sidebar.Header>\n  <Sidebar.Nav>\n    <Sidebar.MenuSkeleton count={6} />\n  </Sidebar.Nav>\n</Sidebar>"
     },
     {
       "name": "With Rail Toggle",
-      "description": "Add a Rail component for a subtle drag-handle style toggle at the sidebar edge. Hover to reveal, click to toggle.",
-      "code": "<Sidebar collapsed={collapsed} onCollapsedChange={setCollapsed}>\n  <Sidebar.Header>{/* ... */}</Sidebar.Header>\n  <Sidebar.Nav>{/* ... */}</Sidebar.Nav>\n  <Sidebar.Footer>\n    <Sidebar.CollapseToggle />\n  </Sidebar.Footer>\n  <Sidebar.Rail />\n</Sidebar>"
+      "description": "Drag-handle toggle on the sidebar edge — hover to reveal, click to collapse.",
+      "code": "function App() {\n  const [collapsed, setCollapsed] = useState(false);\n\n  return (\n    <Sidebar collapsed={collapsed} onCollapsedChange={setCollapsed}>\n      <Sidebar.Header collapsedContent={<Logo />}>\n        <Logo />\n        <span>Acme App</span>\n      </Sidebar.Header>\n      <Sidebar.Nav>\n        <Sidebar.Section>\n          <Sidebar.Item icon={<HomeIcon />} active>Dashboard</Sidebar.Item>\n          <Sidebar.Item icon={<ChartIcon />}>Analytics</Sidebar.Item>\n          <Sidebar.Item icon={<FolderIcon />}>Projects</Sidebar.Item>\n        </Sidebar.Section>\n      </Sidebar.Nav>\n      <Sidebar.Rail />\n    </Sidebar>\n  );\n}"
     },
     {
       "name": "Offcanvas Collapsed",
-      "description": "Offcanvas mode hides the sidebar completely when collapsed, but the toggle button remains visible as a floating button so the user can always re-expand.",
+      "description": "Hides the panel entirely, leaving a floating re-open button.",
       "code": "function App() {\n  const [collapsed, setCollapsed] = useState(true);\n\n  return (\n    <Sidebar collapsed={collapsed} onCollapsedChange={setCollapsed} collapsible=\"offcanvas\">\n      <Sidebar.Header collapsedContent={<Logo />}>\n        <Logo />\n        <span>Acme App</span>\n      </Sidebar.Header>\n      <Sidebar.Nav>\n        <Sidebar.Section>\n          <Sidebar.Item icon={<HomeIcon />} active>Dashboard</Sidebar.Item>\n          <Sidebar.Item icon={<ChartIcon />}>Analytics</Sidebar.Item>\n        </Sidebar.Section>\n      </Sidebar.Nav>\n      <Sidebar.Footer>\n        <Sidebar.CollapseToggle />\n      </Sidebar.Footer>\n    </Sidebar>\n  );\n}"
     }
   ],
@@ -232,11 +206,7 @@
       "active: boolean - set on Sidebar.Item to mark current page (app-controlled)",
       "Sidebar.Item/SubItem onClick: (event) => void - click handler receives mouse event"
     ],
-    "a11yRules": [
-      "A11Y_NAV_LANDMARK",
-      "A11Y_FOCUS_TRAP",
-      "A11Y_ESCAPE_CLOSE"
-    ]
+    "a11yRules": ["A11Y_NAV_LANDMARK", "A11Y_FOCUS_TRAP", "A11Y_ESCAPE_CLOSE"]
   },
   "ai": {
     "compositionPattern": "compound",
@@ -255,9 +225,7 @@
       "Rail",
       "MenuSkeleton"
     ],
-    "requiredChildren": [
-      "Nav"
-    ],
+    "requiredChildren": ["Nav"],
     "commonPatterns": [
       "<Sidebar><Sidebar.Header>{logo}</Sidebar.Header><Sidebar.Nav><Sidebar.Section><Sidebar.Item icon={icon} active>{label}</Sidebar.Item></Sidebar.Section></Sidebar.Nav><Sidebar.Footer><Sidebar.CollapseToggle /></Sidebar.Footer></Sidebar>"
     ]