@fragments-sdk/ui 0.17.1 → 0.18.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@fragments-sdk/ui",
-  "version": "0.17.1",
+  "version": "0.18.0",
   "license": "MIT",
   "description": "Customizable UI components built on Base UI headless primitives",
   "author": "Conan McNicholl",
@@ -230,7 +230,7 @@
     "vite": "^6.0.0",
     "vitest": "^2.1.8",
     "vitest-axe": "^0.1.0",
-    "@fragments-sdk/core": "1.0.1"
+    "@fragments-sdk/core": "2.0.0"
   },
   "files": [
     "src",
@@ -246,7 +246,7 @@
   ],
   "scripts": {
     "cli:ensure": "test -f ../../packages/cli/dist/bin.js || pnpm --filter @fragments-sdk/cli build",
-    "dev": "pnpm run cli:ensure && node ../../packages/cli/dist/bin.js dev",
+    "dev": "pnpm run cli:ensure && node ../../packages/cli/dist/bin.js build",
     "build": "pnpm run cli:ensure && node ../../packages/cli/dist/bin.js build && vite build && tsc -p tsconfig.build.json",
     "lint": "eslint src",
     "validate": "pnpm run cli:ensure && node ../../packages/cli/dist/bin.js validate",

package/src/components/Accordion/Accordion.contract.json

@@ -0,0 +1,169 @@
+{
+  "$schema": "https://usefragments.com/schemas/contract.v1.json",
+  "name": "Accordion",
+  "description": "Vertically stacked, collapsible content sections. Use for organizing related content that can be progressively disclosed.",
+  "category": "layout",
+  "tags": [
+    "accordion",
+    "collapse",
+    "expand",
+    "disclosure",
+    "faq"
+  ],
+  "status": "stable",
+  "sourcePath": "src/components/Accordion/index.tsx",
+  "exportName": "Accordion",
+  "propsSummary": [
+    "type: single|multiple (default: single)",
+    "value: union",
+    "defaultValue: union",
+    "onValueChange: union",
+    "children: node (required)",
+    "collapsible: boolean (default: false)",
+    "headingLevel: union (default: 3)"
+  ],
+  "props": {
+    "type": {
+      "type": "enum",
+      "description": "Whether one or multiple items can be open",
+      "default": "single",
+      "required": false,
+      "values": [
+        "single",
+        "multiple"
+      ]
+    },
+    "value": {
+      "type": "union",
+      "description": "Controlled open item(s): string in single mode, string[] in multiple mode",
+      "required": false
+    },
+    "defaultValue": {
+      "type": "union",
+      "description": "Initially open item(s): string in single mode, string[] in multiple mode",
+      "required": false
+    },
+    "onValueChange": {
+      "type": "union",
+      "description": "Called when open items change (single: string | undefined, multiple: string[])",
+      "required": false
+    },
+    "children": {
+      "type": "node",
+      "description": "Accordion items (use Accordion.Item with Accordion.Trigger and Accordion.Content)",
+      "required": true
+    },
+    "collapsible": {
+      "type": "boolean",
+      "description": "Whether all items can be closed (single mode only)",
+      "default": "false",
+      "required": false
+    },
+    "headingLevel": {
+      "type": "union",
+      "description": "Semantic heading level for accordion triggers",
+      "default": "3",
+      "required": false,
+      "values": [
+        "2",
+        "3",
+        "4",
+        "5",
+        "6"
+      ]
+    }
+  },
+  "usage": {
+    "when": [
+      "FAQ pages with multiple questions and answers",
+      "Settings panels with grouped options",
+      "Long forms that benefit from progressive disclosure",
+      "Navigation menus with nested items"
+    ],
+    "whenNot": [
+      "Primary content that all users need to see",
+      "Very short content (just display inline)",
+      "Sequential steps (use Stepper or wizard)",
+      "Tab-like navigation (use Tabs instead)"
+    ],
+    "guidelines": [
+      "Keep section headers concise and descriptive",
+      "Use single mode when only one section should be open at a time",
+      "Use multiple mode when users may need to compare sections",
+      "Consider defaulting important sections to open",
+      "Avoid nesting accordions more than one level deep"
+    ],
+    "accessibility": [
+      "Keyboard navigation with Enter/Space to toggle",
+      "Uses proper ARIA expanded/controls attributes",
+      "Focus is visible on accordion triggers"
+    ]
+  },
+  "examples": [
+    {
+      "name": "Basic",
+      "description": "Single accordion with collapsible sections",
+      "code": "import { Accordion } from '@/components/Accordion';\n\n<Accordion type=\"single\" collapsible defaultValue=\"item-1\">\n  <Accordion.Item value=\"item-1\">\n    <Accordion.Trigger>What is Fragments UI?</Accordion.Trigger>\n    <Accordion.Content>\n      Fragments UI is a modern React component library built on Base UI primitives, providing accessible and customizable components.\n    </Accordion.Content>\n  </Accordion.Item>\n  <Accordion.Item value=\"item-2\">\n    <Accordion.Trigger>How do I install it?</Accordion.Trigger>\n    <Accordion.Content>\n      Install via npm or pnpm: pnpm add @fragments-sdk/ui\n    </Accordion.Content>\n  </Accordion.Item>\n  <Accordion.Item value=\"item-3\">\n    <Accordion.Trigger>Is it accessible?</Accordion.Trigger>\n    <Accordion.Content>\n      Yes! All components follow WAI-ARIA guidelines and support keyboard navigation.\n    </Accordion.Content>\n  </Accordion.Item>\n</Accordion>"
+    },
+    {
+      "name": "Multiple Open",
+      "description": "Allows multiple sections to be open simultaneously",
+      "code": "import { Accordion } from '@/components/Accordion';\n\n<Accordion type=\"multiple\" defaultValue={['features', 'pricing']}>\n  <Accordion.Item value=\"features\">\n    <Accordion.Trigger>Features</Accordion.Trigger>\n    <Accordion.Content>\n      Comprehensive component library with theming support, accessibility built-in, and TypeScript-first development.\n    </Accordion.Content>\n  </Accordion.Item>\n  <Accordion.Item value=\"pricing\">\n    <Accordion.Trigger>Pricing</Accordion.Trigger>\n    <Accordion.Content>\n      Free and open source. MIT licensed for both personal and commercial use.\n    </Accordion.Content>\n  </Accordion.Item>\n  <Accordion.Item value=\"support\">\n    <Accordion.Trigger>Support</Accordion.Trigger>\n    <Accordion.Content>\n      Community support via GitHub issues and discussions.\n    </Accordion.Content>\n  </Accordion.Item>\n</Accordion>"
+    },
+    {
+      "name": "With Disabled",
+      "description": "Accordion with a disabled item",
+      "code": "import { Accordion } from '@/components/Accordion';\n\n<Accordion type=\"single\" collapsible>\n  <Accordion.Item value=\"available\">\n    <Accordion.Trigger>Available Section</Accordion.Trigger>\n    <Accordion.Content>\n      This section can be expanded and collapsed.\n    </Accordion.Content>\n  </Accordion.Item>\n  <Accordion.Item value=\"disabled\" disabled>\n    <Accordion.Trigger>Disabled Section</Accordion.Trigger>\n    <Accordion.Content>\n      This content is not accessible because the item is disabled.\n    </Accordion.Content>\n  </Accordion.Item>\n  <Accordion.Item value=\"another\">\n    <Accordion.Trigger>Another Section</Accordion.Trigger>\n    <Accordion.Content>\n      This section is also available for interaction.\n    </Accordion.Content>\n  </Accordion.Item>\n</Accordion>"
+    }
+  ],
+  "relations": [
+    {
+      "component": "Tabs",
+      "relationship": "alternative",
+      "note": "Use Tabs for horizontal switching between related views"
+    },
+    {
+      "component": "Dialog",
+      "relationship": "alternative",
+      "note": "Use Dialog for focused content that interrupts the flow"
+    },
+    {
+      "component": "Card",
+      "relationship": "complementary",
+      "note": "Accordion items can contain Card-like content"
+    }
+  ],
+  "contract": {
+    "propsSummary": [
+      "type: single|multiple - controls how many items can be open",
+      "value/defaultValue are type-discriminated (single -> string, multiple -> string[])",
+      "onValueChange is type-discriminated by mode (single -> string|undefined, multiple -> string[])",
+      "collapsible: boolean - allow all closed in single mode",
+      "Accordion.Trigger forwards button props and defaults type=\"button\""
+    ],
+    "a11yRules": [
+      "A11Y_DISCLOSURE_KEYBOARD",
+      "A11Y_FOCUS_VISIBLE"
+    ]
+  },
+  "ai": {
+    "compositionPattern": "compound",
+    "subComponents": [
+      "Item",
+      "Trigger",
+      "Content"
+    ],
+    "requiredChildren": [
+      "Item"
+    ],
+    "commonPatterns": [
+      "<Accordion type=\"single\" collapsible><Accordion.Item value=\"item-1\"><Accordion.Trigger>{title}</Accordion.Trigger><Accordion.Content>{content}</Accordion.Content></Accordion.Item></Accordion>"
+    ]
+  },
+  "provenance": {
+    "source": "migrated",
+    "verified": false,
+    "frameworkSupport": "native",
+    "extractedAt": "2026-03-13T23:18:49.840Z"
+  }
+}

package/src/components/Alert/Alert.contract.json

@@ -0,0 +1,157 @@
+{
+  "$schema": "https://usefragments.com/schemas/contract.v1.json",
+  "name": "Alert",
+  "description": "Contextual feedback messages for user actions or system status. Supports multiple severity levels with optional actions and dismissibility.",
+  "category": "feedback",
+  "tags": [
+    "notification",
+    "message",
+    "feedback",
+    "banner",
+    "toast"
+  ],
+  "status": "stable",
+  "sourcePath": "src/components/Alert/index.tsx",
+  "exportName": "Alert",
+  "propsSummary": [
+    "children: node (required)",
+    "severity: info|success|warning|error (default: info)"
+  ],
+  "props": {
+    "children": {
+      "type": "node",
+      "description": "Alert content - use Alert.Icon, Alert.Body, Alert.Title, Alert.Content, Alert.Actions, Alert.Close sub-components",
+      "required": true
+    },
+    "severity": {
+      "type": "enum",
+      "description": "Visual severity level",
+      "default": "info",
+      "required": false,
+      "values": [
+        "info",
+        "success",
+        "warning",
+        "error"
+      ]
+    }
+  },
+  "usage": {
+    "when": [
+      "Communicating the result of a user action (success, error)",
+      "Warning about potential issues before they occur",
+      "Providing important contextual information inline",
+      "System status notifications that require attention"
+    ],
+    "whenNot": [
+      "Brief status labels (use Badge instead)",
+      "Transient notifications (use Toast/Snackbar)",
+      "Form-field-level errors (use Input error prop)",
+      "Confirmation before destructive actions (use Dialog)"
+    ],
+    "guidelines": [
+      "Match severity to the actual importance: info for context, warning for potential issues, error for failures",
+      "Always provide actionable guidance in error alerts",
+      "Use Alert.Title for complex messages; skip titles for brief one-liners",
+      "Limit to one action per alert to avoid decision paralysis",
+      "Use Alert.Close only for non-critical information",
+      "Alert.Action and Alert.Close render buttons with type=\"button\" by default (safe inside forms)",
+      "Alert.Close composes your onClick handler with built-in dismiss behavior and respects preventDefault()",
+      "Alert sub-components forward DOM props (aria-*, data-*, id, handlers) to their rendered elements"
+    ],
+    "accessibility": [
+      "Uses role=\"alert\" for screen reader announcement",
+      "Error and warning alerts are announced immediately by assistive technology",
+      "Alert.Close must have an accessible label",
+      "Color alone must not convey meaning - icons and text reinforce severity"
+    ]
+  },
+  "examples": [
+    {
+      "name": "Info",
+      "description": "Informational context for the user",
+      "code": "import { Alert } from '@/components/Alert';\n\n<Alert severity=\"info\">\n  <Alert.Icon />\n  <Alert.Body>\n    <Alert.Content>\n      Your session will expire in 15 minutes. Save your work to avoid losing changes.\n    </Alert.Content>\n  </Alert.Body>\n</Alert>"
+    },
+    {
+      "name": "Success",
+      "description": "Positive confirmation of completed action",
+      "code": "import { Alert } from '@/components/Alert';\n\n<Alert severity=\"success\">\n  <Alert.Icon />\n  <Alert.Body>\n    <Alert.Title>Payment processed</Alert.Title>\n    <Alert.Content>\n      Your order #12345 has been confirmed. You will receive a confirmation email shortly.\n    </Alert.Content>\n  </Alert.Body>\n</Alert>"
+    },
+    {
+      "name": "Warning",
+      "description": "Caution about potential issues",
+      "code": "import { Alert } from '@/components/Alert';\n\n<Alert severity=\"warning\">\n  <Alert.Icon />\n  <Alert.Body>\n    <Alert.Title>Storage almost full</Alert.Title>\n    <Alert.Content>\n      You have used 90% of your storage quota. Consider deleting unused files.\n    </Alert.Content>\n  </Alert.Body>\n</Alert>"
+    },
+    {
+      "name": "Error",
+      "description": "Error state requiring user attention",
+      "code": "import { Alert } from '@/components/Alert';\n\n<Alert severity=\"error\">\n  <Alert.Icon />\n  <Alert.Body>\n    <Alert.Title>Upload failed</Alert.Title>\n    <Alert.Content>\n      The file could not be uploaded. Check your connection and try again.\n    </Alert.Content>\n  </Alert.Body>\n</Alert>"
+    },
+    {
+      "name": "With Action",
+      "description": "Alert with an actionable button",
+      "code": "import { Alert } from '@/components/Alert';\n\n<Alert severity=\"warning\">\n  <Alert.Icon />\n  <Alert.Body>\n    <Alert.Title>Update available</Alert.Title>\n    <Alert.Content>\n      A new version is available with important security fixes.\n    </Alert.Content>\n    <Alert.Actions>\n      <Alert.Action onClick={() => {}}>Update now</Alert.Action>\n    </Alert.Actions>\n  </Alert.Body>\n</Alert>"
+    },
+    {
+      "name": "Dismissible",
+      "description": "Alert that can be closed by the user",
+      "code": "import { Alert } from '@/components/Alert';\n\n<Alert severity=\"info\">\n  <Alert.Icon />\n  <Alert.Body>\n    <Alert.Content>\n      You can customize your notification preferences in Settings.\n    </Alert.Content>\n  </Alert.Body>\n  <Alert.Close />\n</Alert>"
+    }
+  ],
+  "relations": [
+    {
+      "component": "Badge",
+      "relationship": "alternative",
+      "note": "Use Badge for compact, inline status labels"
+    },
+    {
+      "component": "Toast",
+      "relationship": "alternative",
+      "note": "Use Toast for transient notifications that auto-dismiss"
+    },
+    {
+      "component": "Dialog",
+      "relationship": "sibling",
+      "note": "Use Dialog for blocking confirmations"
+    }
+  ],
+  "contract": {
+    "propsSummary": [
+      "severity: info|success|warning|error - visual severity",
+      "Sub-components: Alert.Icon, Alert.Body, Alert.Title, Alert.Content, Alert.Actions, Alert.Action, Alert.Close",
+      "Alert.Action / Alert.Close accept button props and default type=\"button\""
+    ],
+    "a11yRules": [
+      "A11Y_ALERT_ROLE",
+      "A11Y_ALERT_DISMISS",
+      "A11Y_ALERT_CONTRAST",
+      "A11Y_TARGET_SIZE_MIN"
+    ]
+  },
+  "ai": {
+    "compositionPattern": "compound",
+    "subComponents": [
+      "Icon",
+      "Body",
+      "Title",
+      "Content",
+      "Actions",
+      "Action",
+      "Close"
+    ],
+    "requiredChildren": [
+      "Body"
+    ],
+    "commonPatterns": [
+      "<Alert severity=\"info\"><Alert.Icon /><Alert.Body><Alert.Content>{message}</Alert.Content></Alert.Body></Alert>",
+      "<Alert severity=\"warning\"><Alert.Icon /><Alert.Body><Alert.Title>{title}</Alert.Title><Alert.Content>{message}</Alert.Content></Alert.Body></Alert>",
+      "<Alert severity=\"error\"><Alert.Icon /><Alert.Body><Alert.Title>{title}</Alert.Title><Alert.Content>{message}</Alert.Content></Alert.Body><Alert.Close /></Alert>"
+    ]
+  },
+  "provenance": {
+    "source": "migrated",
+    "verified": false,
+    "frameworkSupport": "native",
+    "extractedAt": "2026-03-13T23:18:50.066Z"
+  }
+}

package/src/components/AppShell/AppShell.contract.json

@@ -0,0 +1,155 @@
+{
+  "$schema": "https://usefragments.com/schemas/contract.v1.json",
+  "name": "AppShell",
+  "description": "Full layout wrapper integrating sidebar, header, main content, and optional aside panel. Two structural layouts (default, sidebar) combine with per-slot variant=\"floating\" for full flexibility.",
+  "category": "layout",
+  "tags": [
+    "layout",
+    "shell",
+    "scaffold",
+    "dashboard",
+    "app-layout"
+  ],
+  "status": "stable",
+  "sourcePath": "src/components/AppShell/index.tsx",
+  "exportName": "AppShell",
+  "propsSummary": [
+    "children: node (required)",
+    "layout: default|sidebar|sidebar-floating|floating (default: default)",
+    "bg: string",
+    "style: object"
+  ],
+  "props": {
+    "children": {
+      "type": "node",
+      "description": "Layout content (use AppShell.Header, AppShell.Sidebar, AppShell.Main, AppShell.Aside)",
+      "required": true
+    },
+    "layout": {
+      "type": "enum",
+      "description": "Structural layout for CSS grid areas",
+      "default": "default",
+      "required": false,
+      "values": [
+        "default",
+        "sidebar",
+        "sidebar-floating",
+        "floating"
+      ]
+    },
+    "bg": {
+      "type": "string",
+      "description": "Background color override for the shell container (accepts any CSS color or token reference like \"var(--fui-bg-secondary)\")",
+      "required": false
+    },
+    "style": {
+      "type": "object",
+      "description": "",
+      "required": false
+    }
+  },
+  "usage": {
+    "when": [
+      "Building dashboard-style applications",
+      "Apps with persistent sidebar navigation",
+      "Layouts requiring header, sidebar, and main content areas",
+      "Responsive layouts that need mobile drawer behavior"
+    ],
+    "whenNot": [
+      "Simple marketing pages (use standard layout)",
+      "Content-first sites without navigation (use simpler layout)",
+      "Single-page apps with minimal UI (use minimal layout)"
+    ],
+    "guidelines": [
+      "Use layout=\"default\" when header should span full width (logo in header)",
+      "Use layout=\"sidebar\" when sidebar should be full height (logo in sidebar)",
+      "Add variant=\"floating\" to individual slots for rounded, elevated appearance",
+      "Use bg prop on any slot to override its background color",
+      "Combine layout with per-slot variants freely — no enum explosion",
+      "AppShell automatically wraps with SidebarProvider",
+      "Use AppShell.Sidebar to configure sidebar width and collapse behavior",
+      "Main content responds to sidebar collapsed state",
+      "Aside panel is hidden on mobile automatically"
+    ],
+    "accessibility": [
+      "Main content area has id=\"main-content\" for skip links",
+      "Use Header.SkipLink for keyboard navigation",
+      "Sidebar drawer has proper focus trap on mobile",
+      "Keyboard navigation supported throughout"
+    ]
+  },
+  "examples": [
+    {
+      "name": "Default Layout",
+      "description": "Header spans full width above sidebar (default). Best when brand/logo should be prominent in header.",
+      "code": "import { ChartBar, Gear, House } from '@phosphor-icons/react';\nimport { AppShell } from '@/components/AppShell';\nimport { Box } from '@/components/Box';\nimport { Header } from '@/components/Header';\nimport { Icon } from '@/components/Icon';\nimport { Sidebar } from '@/components/Sidebar';\nimport { Stack } from '@/components/Stack';\nimport { Text } from '@/components/Text';\nimport { ThemeToggle } from '@/components/Theme';\n\n<Box minHeight=\"100vh\" overflow=\"hidden\" border rounded=\"md\">\n  <AppShell layout=\"default\">\n    <AppShell.Header>\n      <Header>\n        <Header.Trigger />\n        <Header.Brand>MyApp</Header.Brand>\n        <Header.Nav>\n          <Header.NavItem active>Dashboard</Header.NavItem>\n          <Header.NavItem>Settings</Header.NavItem>\n        </Header.Nav>\n        <Header.Spacer />\n        <Header.Actions>\n          <ThemeToggle size=\"sm\" />\n        </Header.Actions>\n      </Header>\n    </AppShell.Header>\n\n    <AppShell.Sidebar width=\"200px\" collapsible=\"offcanvas\">\n      <Sidebar.Nav>\n        <Sidebar.Section label=\"Menu\">\n          <Sidebar.Item icon={<Icon icon={House} size=\"md\" />} active>Home</Sidebar.Item>\n          <Sidebar.Item icon={<Icon icon={ChartBar} size=\"md\" />}>Analytics</Sidebar.Item>\n          <Sidebar.Item icon={<Icon icon={Gear} size=\"md\" />}>Settings</Sidebar.Item>\n        </Sidebar.Section>\n      </Sidebar.Nav>\n    </AppShell.Sidebar>\n\n    <AppShell.Main padding=\"md\">\n      <Stack gap=\"xs\">\n        <Text as=\"h2\" size=\"xl\" weight=\"semibold\">Default Layout</Text>\n        <Text as=\"p\" color=\"secondary\">\n          Header spans full width. Logo is in the header.\n        </Text>\n      </Stack>\n    </AppShell.Main>\n  </AppShell>\n</Box>"
+    },
+    {
+      "name": "Sidebar Layout",
+      "description": "Sidebar is full height, header sits next to it. Best for documentation sites or when sidebar branding is preferred.",
+      "code": "import { ChartBar, Gear, House, MagnifyingGlass } from '@phosphor-icons/react';\nimport { AppShell } from '@/components/AppShell';\nimport { Box } from '@/components/Box';\nimport { Header } from '@/components/Header';\nimport { Icon } from '@/components/Icon';\nimport { Sidebar } from '@/components/Sidebar';\nimport { Stack } from '@/components/Stack';\nimport { Text } from '@/components/Text';\nimport { ThemeToggle } from '@/components/Theme';\n\n<Box minHeight=\"100vh\" overflow=\"hidden\" border rounded=\"md\">\n  <AppShell layout=\"sidebar\">\n    <AppShell.Header>\n      <Header>\n        <Header.Trigger />\n        <Header.Search>\n          <Box background=\"secondary\" rounded=\"sm\" paddingX=\"sm\" paddingY=\"xs\">\n            <Stack direction=\"row\" align=\"center\" gap=\"sm\">\n              <Icon icon={MagnifyingGlass} size=\"sm\" variant=\"tertiary\" />\n              <Text size=\"sm\" color=\"tertiary\">Search...</Text>\n            </Stack>\n          </Box>\n        </Header.Search>\n        <Header.Spacer />\n        <Header.Actions>\n          <ThemeToggle size=\"sm\" />\n        </Header.Actions>\n      </Header>\n    </AppShell.Header>\n\n    <AppShell.Sidebar width=\"200px\" collapsible=\"offcanvas\">\n      <Sidebar.Header>\n        <Text weight=\"semibold\">MyApp</Text>\n      </Sidebar.Header>\n      <Sidebar.Nav>\n        <Sidebar.Section label=\"Menu\">\n          <Sidebar.Item icon={<Icon icon={House} size=\"md\" />} active>Home</Sidebar.Item>\n          <Sidebar.Item icon={<Icon icon={ChartBar} size=\"md\" />}>Analytics</Sidebar.Item>\n          <Sidebar.Item icon={<Icon icon={Gear} size=\"md\" />}>Settings</Sidebar.Item>\n        </Sidebar.Section>\n      </Sidebar.Nav>\n      <Sidebar.Footer>v1.0.0</Sidebar.Footer>\n    </AppShell.Sidebar>\n\n    <AppShell.Main padding=\"md\">\n      <Stack gap=\"xs\">\n        <Text as=\"h2\" size=\"xl\" weight=\"semibold\">Sidebar Layout</Text>\n        <Text as=\"p\" color=\"secondary\">\n          Sidebar is full height. Logo is in the sidebar header.\n        </Text>\n      </Stack>\n    </AppShell.Main>\n  </AppShell>\n</Box>"
+    },
+    {
+      "name": "With Aside Panel",
+      "description": "App shell with optional right panel for additional context or actions.",
+      "code": "import { ChartBar, House } from '@phosphor-icons/react';\nimport { AppShell } from '@/components/AppShell';\nimport { Box } from '@/components/Box';\nimport { Header } from '@/components/Header';\nimport { Icon } from '@/components/Icon';\nimport { Sidebar } from '@/components/Sidebar';\nimport { Stack } from '@/components/Stack';\nimport { Text } from '@/components/Text';\nimport { ThemeToggle } from '@/components/Theme';\n\n<Box minHeight=\"100vh\" overflow=\"hidden\" border rounded=\"md\">\n  <AppShell layout=\"default\">\n    <AppShell.Header>\n      <Header>\n        <Header.Brand>App</Header.Brand>\n        <Header.Spacer />\n        <Header.Actions>\n          <ThemeToggle size=\"sm\" />\n        </Header.Actions>\n      </Header>\n    </AppShell.Header>\n\n    <AppShell.Sidebar width=\"180px\" collapsible=\"offcanvas\">\n      <Sidebar.Nav>\n        <Sidebar.Section>\n          <Sidebar.Item icon={<Icon icon={House} size=\"md\" />} active>Home</Sidebar.Item>\n          <Sidebar.Item icon={<Icon icon={ChartBar} size=\"md\" />}>Stats</Sidebar.Item>\n        </Sidebar.Section>\n      </Sidebar.Nav>\n    </AppShell.Sidebar>\n\n    <AppShell.Main padding=\"md\">\n      <Stack gap=\"xs\">\n        <Text as=\"h2\" size=\"xl\" weight=\"semibold\">Main Content</Text>\n        <Text as=\"p\">Content with aside panel on the right.</Text>\n      </Stack>\n    </AppShell.Main>\n\n    <AppShell.Aside width=\"180px\">\n      <Box padding=\"md\">\n        <Stack gap=\"xs\">\n          <Text as=\"h3\" size=\"sm\" weight=\"semibold\">Aside Panel</Text>\n          <Text as=\"p\" size=\"sm\" color=\"secondary\">\n            Additional context, filters, or quick actions.\n          </Text>\n        </Stack>\n      </Box>\n    </AppShell.Aside>\n  </AppShell>\n</Box>"
+    },
+    {
+      "name": "Collapsible Icon Sidebar",
+      "description": "Sidebar that collapses to icons only on desktop.",
+      "code": "import { ChartBar, Gear, House } from '@phosphor-icons/react';\nimport { AppShell } from '@/components/AppShell';\nimport { Box } from '@/components/Box';\nimport { Header } from '@/components/Header';\nimport { Icon } from '@/components/Icon';\nimport { Sidebar } from '@/components/Sidebar';\nimport { Text } from '@/components/Text';\nimport { ThemeToggle } from '@/components/Theme';\n\n<Box minHeight=\"100vh\" overflow=\"hidden\" border rounded=\"md\">\n  <AppShell layout=\"sidebar\">\n    <AppShell.Header>\n      <Header>\n        <Header.Trigger />\n        <Header.Spacer />\n        <Header.Actions>\n          <ThemeToggle size=\"sm\" />\n        </Header.Actions>\n      </Header>\n    </AppShell.Header>\n\n    <AppShell.Sidebar collapsible=\"icon\" width=\"200px\" collapsedWidth=\"56px\">\n      <Sidebar.Header>\n        <Text weight=\"semibold\">App</Text>\n      </Sidebar.Header>\n      <Sidebar.Nav>\n        <Sidebar.Section>\n          <Sidebar.Item icon={<Icon icon={House} size=\"md\" />} active>Home</Sidebar.Item>\n          <Sidebar.Item icon={<Icon icon={ChartBar} size=\"md\" />}>Analytics</Sidebar.Item>\n          <Sidebar.Item icon={<Icon icon={Gear} size=\"md\" />}>Settings</Sidebar.Item>\n        </Sidebar.Section>\n      </Sidebar.Nav>\n      <Sidebar.Footer>\n        <Sidebar.CollapseToggle />\n      </Sidebar.Footer>\n    </AppShell.Sidebar>\n\n    <AppShell.Main padding=\"md\">\n      <Text as=\"p\">\n        Click the collapse button in the sidebar footer to toggle between expanded and icon-only modes.\n      </Text>\n    </AppShell.Main>\n  </AppShell>\n</Box>"
+    },
+    {
+      "name": "Floating Main",
+      "description": "Sidebar layout with floating main content. Per-slot variant=\"floating\" gives the main area rounded corners and a distinct background, while the sidebar blends with the shell.",
+      "code": "import { ChartBar, Gear, House, MagnifyingGlass } from '@phosphor-icons/react';\nimport { AppShell } from '@/components/AppShell';\nimport { Box } from '@/components/Box';\nimport { Header } from '@/components/Header';\nimport { Icon } from '@/components/Icon';\nimport { Sidebar } from '@/components/Sidebar';\nimport { Stack } from '@/components/Stack';\nimport { Text } from '@/components/Text';\nimport { ThemeToggle } from '@/components/Theme';\n\n<Box minHeight=\"100vh\" overflow=\"hidden\" border rounded=\"md\">\n  <AppShell layout=\"sidebar\">\n    <AppShell.Header>\n      <Header>\n        <Header.Trigger />\n        <Header.Search>\n          <Box background=\"primary\" border rounded=\"sm\" paddingX=\"sm\" paddingY=\"xs\">\n            <Stack direction=\"row\" align=\"center\" gap=\"sm\">\n              <Icon icon={MagnifyingGlass} size=\"sm\" variant=\"tertiary\" />\n              <Text size=\"sm\" color=\"tertiary\">Search...</Text>\n            </Stack>\n          </Box>\n        </Header.Search>\n        <Header.Spacer />\n        <Header.Actions>\n          <ThemeToggle size=\"sm\" />\n        </Header.Actions>\n      </Header>\n    </AppShell.Header>\n\n    <AppShell.Sidebar width=\"200px\" collapsible=\"offcanvas\" variant=\"floating\">\n      <Sidebar.Header>\n        <Text weight=\"semibold\">MyApp</Text>\n      </Sidebar.Header>\n      <Sidebar.Nav>\n        <Sidebar.Section label=\"Menu\">\n          <Sidebar.Item icon={<Icon icon={House} size=\"md\" />} active>Home</Sidebar.Item>\n          <Sidebar.Item icon={<Icon icon={ChartBar} size=\"md\" />}>Analytics</Sidebar.Item>\n          <Sidebar.Item icon={<Icon icon={Gear} size=\"md\" />}>Settings</Sidebar.Item>\n        </Sidebar.Section>\n      </Sidebar.Nav>\n      <Sidebar.Footer>v1.0.0</Sidebar.Footer>\n    </AppShell.Sidebar>\n\n    <AppShell.Main padding=\"md\" variant=\"floating\">\n      <Stack gap=\"xs\">\n        <Text as=\"h2\" size=\"xl\" weight=\"semibold\">Floating Main</Text>\n        <Text as=\"p\" color=\"secondary\">\n          Main content has rounded corners and visual separation from the sidebar.\n        </Text>\n      </Stack>\n    </AppShell.Main>\n  </AppShell>\n</Box>"
+    },
+    {
+      "name": "Floating Main & Aside",
+      "description": "Both main content and aside panel float with rounded corners. Each slot independently opts into the floating visual treatment via variant=\"floating\".",
+      "code": "import { ChartBar, Gear, House, MagnifyingGlass } from '@phosphor-icons/react';\nimport { AppShell } from '@/components/AppShell';\nimport { Box } from '@/components/Box';\nimport { Header } from '@/components/Header';\nimport { Icon } from '@/components/Icon';\nimport { Sidebar } from '@/components/Sidebar';\nimport { Stack } from '@/components/Stack';\nimport { Text } from '@/components/Text';\nimport { ThemeToggle } from '@/components/Theme';\n\n<Box minHeight=\"100vh\" overflow=\"hidden\" border rounded=\"md\">\n  <AppShell layout=\"sidebar\">\n    <AppShell.Header>\n      <Header>\n        <Header.Trigger />\n        <Header.Search>\n          <Box background=\"primary\" border rounded=\"sm\" paddingX=\"sm\" paddingY=\"xs\">\n            <Stack direction=\"row\" align=\"center\" gap=\"sm\">\n              <Icon icon={MagnifyingGlass} size=\"sm\" variant=\"tertiary\" />\n              <Text size=\"sm\" color=\"tertiary\">Search...</Text>\n            </Stack>\n          </Box>\n        </Header.Search>\n        <Header.Spacer />\n        <Header.Actions>\n          <ThemeToggle size=\"sm\" />\n        </Header.Actions>\n      </Header>\n    </AppShell.Header>\n\n    <AppShell.Sidebar width=\"200px\" collapsible=\"offcanvas\" variant=\"floating\">\n      <Sidebar.Header>\n        <Text weight=\"semibold\">MyApp</Text>\n      </Sidebar.Header>\n      <Sidebar.Nav>\n        <Sidebar.Section label=\"Menu\">\n          <Sidebar.Item icon={<Icon icon={House} size=\"md\" />} active>Home</Sidebar.Item>\n          <Sidebar.Item icon={<Icon icon={ChartBar} size=\"md\" />}>Analytics</Sidebar.Item>\n          <Sidebar.Item icon={<Icon icon={Gear} size=\"md\" />}>Settings</Sidebar.Item>\n        </Sidebar.Section>\n      </Sidebar.Nav>\n      <Sidebar.Footer>v1.0.0</Sidebar.Footer>\n    </AppShell.Sidebar>\n\n    <AppShell.Main padding=\"md\" variant=\"floating\">\n      <Stack gap=\"xs\">\n        <Text as=\"h2\" size=\"xl\" weight=\"semibold\">Floating Main & Aside</Text>\n        <Text as=\"p\" color=\"secondary\">\n          Both main content and aside panel float with rounded corners.\n        </Text>\n      </Stack>\n    </AppShell.Main>\n\n    <AppShell.Aside width=\"200px\" variant=\"floating\">\n      <Box padding=\"md\">\n        <Stack gap=\"xs\">\n          <Text as=\"h3\" size=\"sm\" weight=\"semibold\">Aside Panel</Text>\n          <Text as=\"p\" size=\"sm\" color=\"secondary\">\n            This aside also floats, matching the main content area.\n          </Text>\n        </Stack>\n      </Box>\n    </AppShell.Aside>\n  </AppShell>\n</Box>"
+    },
+    {
+      "name": "Floating Default Layout",
+      "description": "Default header-on-top structure with a floating main content area. Demonstrates that floating is independent of structure — any slot can float in any layout.",
+      "code": "import { ChartBar, House } from '@phosphor-icons/react';\nimport { AppShell } from '@/components/AppShell';\nimport { Box } from '@/components/Box';\nimport { Header } from '@/components/Header';\nimport { Icon } from '@/components/Icon';\nimport { Sidebar } from '@/components/Sidebar';\nimport { Stack } from '@/components/Stack';\nimport { Text } from '@/components/Text';\nimport { ThemeToggle } from '@/components/Theme';\n\n<Box minHeight=\"100vh\" overflow=\"hidden\" border rounded=\"md\">\n  <AppShell layout=\"default\">\n    <AppShell.Header>\n      <Header>\n        <Header.Brand>MyApp</Header.Brand>\n        <Header.Spacer />\n        <Header.Actions>\n          <ThemeToggle size=\"sm\" />\n        </Header.Actions>\n      </Header>\n    </AppShell.Header>\n\n    <AppShell.Sidebar width=\"180px\" collapsible=\"offcanvas\" variant=\"floating\">\n      <Sidebar.Nav>\n        <Sidebar.Section>\n          <Sidebar.Item icon={<Icon icon={House} size=\"md\" />} active>Home</Sidebar.Item>\n          <Sidebar.Item icon={<Icon icon={ChartBar} size=\"md\" />}>Stats</Sidebar.Item>\n        </Sidebar.Section>\n      </Sidebar.Nav>\n    </AppShell.Sidebar>\n\n    <AppShell.Main padding=\"md\" variant=\"floating\">\n      <Stack gap=\"xs\">\n        <Text as=\"h2\" size=\"xl\" weight=\"semibold\">Floating Default Layout</Text>\n        <Text as=\"p\" color=\"secondary\">\n          Default structure (header on top) with floating main content. Any slot can float in any layout.\n        </Text>\n      </Stack>\n    </AppShell.Main>\n  </AppShell>\n</Box>"
+    },
+    {
+      "name": "Custom Backgrounds",
+      "description": "Each slot accepts a bg prop to override its background color independently. Here the sidebar and aside use bg-elevated (lighter) while main uses bg-primary (darker).",
+      "code": "import { ChartBar, House } from '@phosphor-icons/react';\nimport { AppShell } from '@/components/AppShell';\nimport { Box } from '@/components/Box';\nimport { Header } from '@/components/Header';\nimport { Icon } from '@/components/Icon';\nimport { Sidebar } from '@/components/Sidebar';\nimport { Stack } from '@/components/Stack';\nimport { Text } from '@/components/Text';\nimport { ThemeToggle } from '@/components/Theme';\n\n<Box minHeight=\"100vh\" overflow=\"hidden\" border rounded=\"md\">\n  <AppShell layout=\"sidebar\">\n    <AppShell.Header>\n      <Header>\n        <Header.Trigger />\n        <Header.Spacer />\n        <Header.Actions>\n          <ThemeToggle size=\"sm\" />\n        </Header.Actions>\n      </Header>\n    </AppShell.Header>\n\n    <AppShell.Sidebar width=\"200px\" collapsible=\"offcanvas\" bg=\"var(--fui-bg-elevated)\">\n      <Sidebar.Header>\n        <Text weight=\"semibold\">MyApp</Text>\n      </Sidebar.Header>\n      <Sidebar.Nav>\n        <Sidebar.Section label=\"Menu\">\n          <Sidebar.Item icon={<Icon icon={House} size=\"md\" />} active>Home</Sidebar.Item>\n          <Sidebar.Item icon={<Icon icon={ChartBar} size=\"md\" />}>Analytics</Sidebar.Item>\n        </Sidebar.Section>\n      </Sidebar.Nav>\n    </AppShell.Sidebar>\n\n    <AppShell.Main padding=\"md\" bg=\"var(--fui-bg-primary)\">\n      <Stack gap=\"xs\">\n        <Text as=\"h2\" size=\"xl\" weight=\"semibold\">Custom Backgrounds</Text>\n        <Text as=\"p\" color=\"secondary\">\n          Sidebar uses bg-elevated (lighter), main uses bg-primary (darker). Any CSS color or token works.\n        </Text>\n      </Stack>\n    </AppShell.Main>\n\n    <AppShell.Aside width=\"200px\" bg=\"var(--fui-bg-elevated)\">\n      <Box padding=\"md\">\n        <Stack gap=\"xs\">\n          <Text as=\"h3\" size=\"sm\" weight=\"semibold\">Aside Panel</Text>\n          <Text as=\"p\" size=\"sm\" color=\"secondary\">\n            Aside with bg-elevated background matching the sidebar.\n          </Text>\n        </Stack>\n      </Box>\n    </AppShell.Aside>\n  </AppShell>\n</Box>"
+    }
+  ],
+  "relations": [
+    {
+      "component": "Theme",
+      "relationship": "parent",
+      "note": "AppShell should be wrapped in ThemeProvider"
+    },
+    {
+      "component": "Header",
+      "relationship": "child",
+      "note": "Header is placed inside AppShell.Header"
+    },
+    {
+      "component": "Sidebar",
+      "relationship": "child",
+      "note": "Sidebar content goes inside AppShell.Sidebar"
+    }
+  ],
+  "ai": {
+    "compositionPattern": "compound",
+    "subComponents": [
+      "Header",
+      "Sidebar",
+      "Main",
+      "Aside"
+    ]
+  },
+  "provenance": {
+    "source": "migrated",
+    "verified": false,
+    "frameworkSupport": "native",
+    "extractedAt": "2026-03-13T23:18:50.550Z"
+  }
+}