@usefragments/ui 1.6.0 → 2.0.0

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

@@ -1,15 +1,9 @@
 {
   "$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.",
+  "description": "Lays out header, sidebar, main, and optional aside as one responsive app frame.",
   "category": "layout",
-  "tags": [
-    "layout",
-    "shell",
-    "scaffold",
-    "dashboard",
-    "app-layout"
-  ],
+  "tags": ["layout", "shell", "scaffold", "dashboard", "app-layout"],
   "status": "stable",
   "sourcePath": "src/components/AppShell/index.tsx",
   "exportName": "AppShell",
@@ -30,12 +24,7 @@
       "description": "Structural layout for CSS grid areas",
       "default": "default",
       "required": false,
-      "values": [
-        "default",
-        "sidebar",
-        "sidebar-floating",
-        "floating"
-      ]
+      "values": ["default", "sidebar", "sidebar-floating", "floating"]
     },
     "bg": {
       "type": "string",
@@ -50,26 +39,25 @@
   },
   "usage": {
     "when": [
-      "Building dashboard-style applications",
+      "Dashboards and internal tools",
       "Apps with persistent sidebar navigation",
-      "Layouts requiring header, sidebar, and main content areas",
-      "Responsive layouts that need mobile drawer behavior"
+      "Layouts needing header, sidebar, and main together",
+      "Navigation that must collapse to a drawer on mobile"
     ],
     "whenNot": [
-      "Simple marketing pages (use standard layout)",
-      "Content-first sites without navigation (use simpler layout)",
-      "Single-page apps with minimal UI (use minimal layout)"
+      "Marketing and landing pages",
+      "Content-first sites with no app navigation",
+      "Single-screen tools with no chrome"
     ],
     "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"
+      "layout=\"default\" puts the logo in a full-width header",
+      "layout=\"sidebar\" puts the logo in a full-height sidebar",
+      "variant=\"floating\" is per slot — mix it with any layout",
+      "bg overrides one slot's background without touching the rest",
+      "AppShell supplies SidebarProvider; do not add your own",
+      "Set width and collapse behaviour on AppShell.Sidebar",
+      "Main reflows automatically when the sidebar collapses",
+      "Aside hides itself on mobile"
     ],
     "accessibility": [
       "Main content area has id=\"main-content\" for skip links",
@@ -81,43 +69,43 @@
   "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>"
+      "description": "Header spans the full width above the sidebar.",
+      "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 height=\"360px\" 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\" scale=\"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>"
+      "description": "Sidebar runs full height with the header beside it.",
+      "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 height=\"360px\" 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\" color=\"tertiary\" />\n              <Text scale=\"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\" scale=\"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>"
+      "description": "Adds a right rail for context, filters, 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 height=\"360px\" 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\" scale=\"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\" scale=\"sm\" weight=\"semibold\">Aside Panel</Text>\n          <Text as=\"p\" scale=\"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>"
+      "description": "Sidebar shrinks to icons on desktop via the footer toggle.",
+      "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 height=\"360px\" 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>"
+      "description": "Only the main slot floats — rounded, raised, on its own background.",
+      "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 height=\"360px\" 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\" color=\"tertiary\" />\n              <Text scale=\"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\" scale=\"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>"
+      "description": "Two slots float independently; the sidebar stays flush.",
+      "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 height=\"360px\" 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\" color=\"tertiary\" />\n              <Text scale=\"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\" scale=\"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\" scale=\"sm\" weight=\"semibold\">Aside Panel</Text>\n          <Text as=\"p\" scale=\"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>"
+      "description": "Floating works under any layout, including header-on-top.",
+      "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 height=\"360px\" 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\" scale=\"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>"
+      "description": "Each slot takes its own bg, so regions read apart.",
+      "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 height=\"360px\" 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\" scale=\"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\" scale=\"sm\" weight=\"semibold\">Aside Panel</Text>\n          <Text as=\"p\" scale=\"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": [
@@ -139,12 +127,7 @@
   ],
   "ai": {
     "compositionPattern": "compound",
-    "subComponents": [
-      "Header",
-      "Sidebar",
-      "Main",
-      "Aside"
-    ]
+    "subComponents": ["Header", "Sidebar", "Main", "Aside"]
   },
   "provenance": {
     "source": "migrated",

package/src/components/AppShell/AppShell.module.scss

@@ -1,7 +1,17 @@
 @use "../../tokens/variables" as *;
+@use "../../tokens/measurements.generated" as measurements;
 @use "../../tokens/mixins" as *;
 @use "../../recipes/navigation" as navigation;
 
+// Tablet band (md ≤ width < lg): the sidebar stays docked but a third column
+// would starve main, so the aside stacks under it. Below md the sidebar
+// becomes an overlay and everything is one column.
+@mixin tablet {
+  @media (min-width: $fui-breakpoint-md) and (max-width: #{$fui-breakpoint-lg - 1px}) {
+    @content;
+  }
+}
+
 // ============================================
 // AppShell Root - CSS Grid Layout
 // ============================================
@@ -25,15 +35,33 @@
     "header header header"
     "sidebar main aside";
   grid-template-columns:
-    var(--appshell-sidebar-width, 240px)
+    var(--appshell-sidebar-width)
     1fr
-    var(--appshell-aside-width, 0px);
+    var(--appshell-aside-width);
   grid-template-rows:
     var(--appshell-header-height, var(--fui-appshell-header-height, $fui-appshell-header-height))
     1fr;
 
-  // Smooth transition for sidebar collapse/expand
-  transition: grid-template-columns var(--fui-transition-normal, $fui-transition-normal) ease;
+  // Smooth transition for sidebar collapse/expand.
+  // The token already carries its own easing curve — do not append another.
+  transition: grid-template-columns var(--fui-transition-normal, $fui-transition-normal);
+
+  @media (prefers-reduced-motion: reduce) {
+    transition: none;
+  }
+
+  // Tablet: sidebar + main, aside stacked under main
+  @include tablet {
+    grid-template-areas:
+      "header header"
+      "sidebar main"
+      "sidebar aside";
+    grid-template-columns: var(--appshell-sidebar-width) 1fr;
+    grid-template-rows:
+      var(--appshell-header-height, var(--fui-appshell-header-height, $fui-appshell-header-height))
+      1fr
+      auto;
+  }
 
   // Mobile: single column layout
   @include below-md {
@@ -58,6 +86,14 @@
     "sidebar header header"
     "sidebar main aside";
 
+  @include tablet {
+    grid-template-areas:
+      "sidebar header"
+      "sidebar main"
+      "sidebar aside";
+    grid-template-columns: var(--appshell-sidebar-width) 1fr;
+  }
+
   @include below-md {
     grid-template-areas:
       "header"
@@ -80,10 +116,11 @@
     var(--fui-appshell-header-height, $fui-appshell-header-height)
   );
   z-index: var(--fui-header-z-index, $fui-header-z-index);
-  background-color: inherit;
+  // Match the reading pane (`--fui-app-main-bg`), not the rail.
+  background-color: var(--fui-app-main-bg, var(--fui-main-bg, #{$fui-main-bg}));
 
   > header {
-    background-color: inherit;
+    background-color: var(--fui-app-main-bg, var(--fui-main-bg, #{$fui-main-bg}));
   }
 }
 
@@ -93,29 +130,42 @@
 
 .sidebar {
   grid-area: sidebar;
-  position: sticky;
-  top: var(
-    --appshell-header-height,
-    var(--fui-appshell-header-height, $fui-appshell-header-height)
-  );
-  height: calc(
-    100vh - var(
-        --appshell-header-height,
-        var(--fui-appshell-header-height, $fui-appshell-header-height)
-      )
-  );
-  height: calc(
-    100dvh - var(
-        --appshell-header-height,
-        var(--fui-appshell-header-height, $fui-appshell-header-height)
-      )
-  );
-  z-index: 30;
-  overflow: hidden;
+  align-self: stretch;
+  position: relative;
+  height: auto;
+  min-height: 100%;
+  z-index: 1;
+  overflow: visible;
   background-color: inherit;
+  // Border lives on the grid column so the rail runs the full content
+  // height; the sticky inner sidebar is viewport-tall for nav scrolling.
+  border-inline-end: var(--fui-stroke-hairline, #{$fui-stroke-hairline}) solid
+    var(
+      --fui-sidebar-border,
+      var(--fui-border-subtle, var(--fui-border-default, #{$fui-border-default}))
+    );
 
   > aside {
+    position: sticky;
+    top: var(
+      --appshell-header-height,
+      var(--fui-appshell-header-height, $fui-appshell-header-height)
+    );
+    height: calc(
+      100vh - var(
+          --appshell-header-height,
+          var(--fui-appshell-header-height, $fui-appshell-header-height)
+        )
+    );
+    height: calc(
+      100dvh - var(
+          --appshell-header-height,
+          var(--fui-appshell-header-height, $fui-appshell-header-height)
+        )
+    );
+    overflow: hidden;
     background-color: inherit;
+    border-inline-end: 0;
   }
 
   // On mobile, sidebar becomes a fixed overlay
@@ -127,34 +177,28 @@
     width: 0;
     height: 100vh;
     height: 100dvh;
-    z-index: 51;
+    z-index: var(--fui-overlay-layer-modal, #{$fui-overlay-layer-modal});
+    border-inline-end: 0;
 
-    // Allow the sidebar to appear as overlay on mobile
-    & > :global(.root) {
-      width: var(--appshell-sidebar-expanded-width, 240px);
-    }
-  }
-
-  // Override Sidebar component's height
-  :global(.root) {
-    height: 100%;
-
-    @include below-md {
+    > aside {
+      position: relative;
+      top: 0;
+      width: var(--appshell-sidebar-expanded-width);
       height: 100vh;
       height: 100dvh;
     }
   }
 }
 
-// Sidebar in sidebar structure: full height
+// Sidebar in sidebar structure: column stretches both rows; inner sticks
+// from the top of the viewport.
 .sidebarFullHeight {
-  top: 0;
-  height: 100vh;
-  height: 100dvh;
   z-index: var(--fui-header-z-index, $fui-header-z-index);
 
-  :global(.root) {
-    height: 100%;
+  > aside {
+    top: 0;
+    height: 100vh;
+    height: 100dvh;
   }
 }
 
@@ -187,10 +231,10 @@
   margin: var(--fui-space-1, $fui-space-1) var(--fui-space-1, $fui-space-1)
     var(--fui-space-1, $fui-space-1) 0;
   padding: var(--fui-space-4, $fui-space-4);
-  border: var(--fui-stroke-hairline, 1px) solid var(--fui-border, $fui-border);
+  border: var(--fui-stroke-hairline, #{$fui-stroke-hairline}) solid var(--fui-border, $fui-border);
   border-radius: var(--fui-radius-xl, $fui-radius-xl);
   background-color: var(--fui-app-main-bg, var(--fui-main-bg, #{$fui-main-bg}));
-  box-shadow: inset 0 1px 0
+  box-shadow: inset 0 var(--fui-stroke-hairline, #{$fui-stroke-hairline}) 0
     color-mix(in srgb, var(--fui-text-primary, #{$fui-text-primary}) 5%, transparent);
   overflow: hidden auto;
 
@@ -207,7 +251,7 @@
 // Keep these compound rules after `.mainFloating`: the explicit padding prop
 // owns the content inset even when the floating surface supplies its default.
 .main.paddingNone {
-  padding: 0;
+  padding: var(--fui-raw-space-0, #{measurements.raw-space(0)});
 }
 
 .main.paddingSm {
@@ -245,18 +289,19 @@
         var(--fui-appshell-header-height, $fui-appshell-header-height)
       )
   );
-  width: var(--aside-width, 280px);
+  width: var(--aside-width);
   min-height: 0; // Allow shrinking in grid
-  z-index: 30;
+  z-index: 1;
   background-color: var(--fui-app-sidebar-bg, inherit);
   overflow: hidden;
 
-  // Stack below main on mobile
-  @include below-md {
+  // Stack below main on tablet and mobile
+  @include below-lg {
     position: static;
     width: 100%;
     height: auto;
-    border-top: var(--fui-stroke-hairline, 1px) solid var(--fui-border, $fui-border);
+    border-top: var(--fui-stroke-hairline, #{$fui-stroke-hairline}) solid
+      var(--fui-border, $fui-border);
   }
 }
 
@@ -282,14 +327,14 @@
   );
   margin: var(--fui-space-1, $fui-space-1) var(--fui-space-1, $fui-space-1)
     var(--fui-space-1, $fui-space-1) 0;
-  border: var(--fui-stroke-hairline, 1px) solid var(--fui-border, $fui-border);
+  border: var(--fui-stroke-hairline, #{$fui-stroke-hairline}) solid var(--fui-border, $fui-border);
   border-radius: var(--fui-radius-xl, $fui-radius-xl);
   background-color: var(--fui-panel-bg, inherit);
-  box-shadow: inset 0 1px 0
+  box-shadow: inset 0 var(--fui-stroke-hairline, #{$fui-stroke-hairline}) 0
     color-mix(in srgb, var(--fui-text-primary, #{$fui-text-primary}) 5%, transparent);
   overflow: hidden;
 
-  @include below-md {
+  @include below-lg {
     margin: var(--fui-space-1, $fui-space-1) 0;
     border-left: none;
     border-right: none;

package/src/components/AppShell/index.tsx

@@ -156,7 +156,7 @@ interface AppShellContextValue {
 const AppShellContext = React.createContext<AppShellContextValue>({
   layout: "default",
   structure: "default",
-  headerHeight: "56px",
+  headerHeight: "var(--fui-appshell-header-height, 56px)",
   sidebarWidth: "240px",
   sidebarCollapsedWidth: "var(--fui-navigation-sidebar-collapsed-width, 56px)",
   asideWidth: "280px",
@@ -204,7 +204,7 @@ interface ExtractedConfig {
 
 function extractConfigFromChildren(children: React.ReactNode): ExtractedConfig {
   const config: ExtractedConfig = {
-    headerHeight: "56px",
+    headerHeight: "var(--fui-appshell-header-height, 56px)",
     sidebarWidth: "240px",
     sidebarCollapsedWidth: "var(--fui-navigation-sidebar-collapsed-width, 56px)",
     sidebarCollapsible: "icon",