@usefragments/ui 1.6.0 → 1.7.0

package/src/components/Alert/index.tsx

@@ -1,14 +1,14 @@
-'use client';
+"use client";
 
-import * as React from 'react';
-import { Button as BaseButton } from '@base-ui/react/button';
-import styles from './Alert.module.scss';
+import * as React from "react";
+import { Button as BaseButton } from "@base-ui/react/button";
+import styles from "./Alert.module.scss";
 
 // ============================================
 // Types
 // ============================================
 
-export type AlertSeverity = 'info' | 'success' | 'warning' | 'error';
+export type AlertSeverity = "info" | "success" | "warning" | "error";
 
 /**
  * Alert for contextual feedback messages (info, success, warning, error).
@@ -20,6 +20,12 @@ export interface AlertProps extends React.HTMLAttributes<HTMLDivElement> {
    * @default "info"
    * @see https://usefragments.com/components/alert#variants */
   severity?: AlertSeverity;
+  /** How much surface the severity claims. `tint` washes the whole card in the
+   * severity colour. `surface` keeps the card on the page's own background and
+   * spends the colour only on the hairline and the title — for a standing
+   * failure that owns the view, where a full wash would read as a red page.
+   * @default "tint" */
+  emphasis?: "tint" | "surface";
 }
 
 export interface AlertIconProps extends React.HTMLAttributes<HTMLSpanElement> {
@@ -38,12 +44,18 @@ export interface AlertActionsProps extends React.HTMLAttributes<HTMLDivElement>
   children: React.ReactNode;
 }
 
-export interface AlertActionProps extends Omit<React.ButtonHTMLAttributes<HTMLButtonElement>, 'onClick'> {
+export interface AlertActionProps extends Omit<
+  React.ButtonHTMLAttributes<HTMLButtonElement>,
+  "onClick"
+> {
   children: React.ReactNode;
   onClick?: React.MouseEventHandler<HTMLButtonElement>;
 }
 
-export interface AlertCloseProps extends Omit<React.ButtonHTMLAttributes<HTMLButtonElement>, 'children'> {
+export interface AlertCloseProps extends Omit<
+  React.ButtonHTMLAttributes<HTMLButtonElement>,
+  "children"
+> {
   children?: React.ReactNode;
 }
 
@@ -67,7 +79,7 @@ const AlertContext = React.createContext<AlertContextValue | null>(null);
 function useAlertContext() {
   const context = React.useContext(AlertContext);
   if (!context) {
-    throw new Error('Alert compound components must be used within an Alert');
+    throw new Error("Alert compound components must be used within an Alert");
   }
   return context;
 }
@@ -88,10 +100,10 @@ function composeEventHandlers<E extends { defaultPrevented: boolean }>(
 // ============================================
 
 const severityIcons: Record<AlertSeverity, string> = {
-  info: 'i',
-  success: '\u2713',
-  warning: '!',
-  error: '\u2717',
+  info: "i",
+  success: "\u2713",
+  warning: "!",
+  error: "\u2717",
 };
 
 // ============================================
@@ -100,7 +112,8 @@ const severityIcons: Record<AlertSeverity, string> = {
 
 function AlertRoot({
   children,
-  severity = 'info',
+  severity = "info",
+  emphasis = "tint",
   className,
   ...htmlProps
 }: AlertProps) {
@@ -114,10 +127,15 @@ function AlertRoot({
 
   if (dismissed) return null;
 
-  const classes = [styles.alert, styles[severity], className]
+  const classes = [
+    styles.alert,
+    styles[severity],
+    emphasis === "surface" ? styles.surface : null,
+    className,
+  ]
     .filter(Boolean)
-    .join(' ');
-  const role = severity === 'warning' || severity === 'error' ? 'alert' : 'status';
+    .join(" ");
+  const role = severity === "warning" || severity === "error" ? "alert" : "status";
 
   const contextValue: AlertContextValue = {
     severity,
@@ -143,7 +161,7 @@ function AlertRoot({
 
 function AlertIcon({ children, className, ...htmlProps }: AlertIconProps) {
   const { severity } = useAlertContext();
-  const classes = [styles.icon, className].filter(Boolean).join(' ');
+  const classes = [styles.icon, className].filter(Boolean).join(" ");
 
   return (
     <span {...htmlProps} className={classes} aria-hidden="true">
@@ -153,13 +171,17 @@ function AlertIcon({ children, className, ...htmlProps }: AlertIconProps) {
 }
 
 function AlertBody({ children, className, ...htmlProps }: AlertBodyProps) {
-  const classes = [styles.body, className].filter(Boolean).join(' ');
-  return <div {...htmlProps} className={classes}>{children}</div>;
+  const classes = [styles.body, className].filter(Boolean).join(" ");
+  return (
+    <div {...htmlProps} className={classes}>
+      {children}
+    </div>
+  );
 }
 
 function AlertTitle({ children, className, ...htmlProps }: AlertTitleProps) {
   const { titleId } = useAlertContext();
-  const classes = [styles.title, className].filter(Boolean).join(' ');
+  const classes = [styles.title, className].filter(Boolean).join(" ");
   return (
     <div {...htmlProps} id={htmlProps.id ?? titleId} className={classes}>
       {children}
@@ -169,7 +191,7 @@ function AlertTitle({ children, className, ...htmlProps }: AlertTitleProps) {
 
 function AlertContent({ children, className, ...htmlProps }: AlertContentProps) {
   const { descId } = useAlertContext();
-  const classes = [styles.content, className].filter(Boolean).join(' ');
+  const classes = [styles.content, className].filter(Boolean).join(" ");
   return (
     <div {...htmlProps} id={htmlProps.id ?? descId} className={classes}>
       {children}
@@ -178,18 +200,22 @@ function AlertContent({ children, className, ...htmlProps }: AlertContentProps)
 }
 
 function AlertActions({ children, className, ...htmlProps }: AlertActionsProps) {
-  const classes = [styles.actions, className].filter(Boolean).join(' ');
-  return <div {...htmlProps} className={classes}>{children}</div>;
+  const classes = [styles.actions, className].filter(Boolean).join(" ");
+  return (
+    <div {...htmlProps} className={classes}>
+      {children}
+    </div>
+  );
 }
 
 function AlertAction({
   children,
   onClick,
-  type = 'button',
+  type = "button",
   className,
   ...htmlProps
 }: AlertActionProps) {
-  const classes = [styles.action, className].filter(Boolean).join(' ');
+  const classes = [styles.action, className].filter(Boolean).join(" ");
   return (
     <BaseButton {...htmlProps} onClick={onClick} type={type} className={classes}>
       {children}
@@ -201,12 +227,12 @@ function AlertClose({
   children,
   className,
   onClick,
-  type = 'button',
-  'aria-label': ariaLabel = 'Dismiss alert',
+  type = "button",
+  "aria-label": ariaLabel = "Dismiss alert",
   ...htmlProps
 }: AlertCloseProps) {
   const { dismiss } = useAlertContext();
-  const classes = [styles.close, className].filter(Boolean).join(' ');
+  const classes = [styles.close, className].filter(Boolean).join(" ");
 
   return (
     <BaseButton
@@ -216,7 +242,7 @@ function AlertClose({
       aria-label={ariaLabel}
       className={classes}
     >
-      {children ?? '\u00D7'}
+      {children ?? "\u00D7"}
     </BaseButton>
   );
 }

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\" 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>"
+      "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\" 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>"
+      "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\" 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>"
+      "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\" 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>"
+      "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\" 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>"
+      "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\" 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>"
+      "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\" 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": [
@@ -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

@@ -32,8 +32,13 @@
     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;
+  }
 
   // Mobile: single column layout
   @include below-md {
@@ -80,10 +85,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 +99,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)
-      )
-  );
+  align-self: stretch;
+  position: relative;
+  height: auto;
+  min-height: 100%;
   z-index: 30;
-  overflow: hidden;
+  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, 1px) 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
@@ -128,33 +147,27 @@
     height: 100vh;
     height: 100dvh;
     z-index: 51;
+    border-inline-end: 0;
 
-    // Allow the sidebar to appear as overlay on mobile
-    & > :global(.root) {
+    > aside {
+      position: relative;
+      top: 0;
       width: var(--appshell-sidebar-expanded-width, 240px);
-    }
-  }
-
-  // Override Sidebar component's height
-  :global(.root) {
-    height: 100%;
-
-    @include below-md {
       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;
   }
 }
 
@@ -190,7 +203,7 @@
   border: var(--fui-stroke-hairline, 1px) 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, 1px) 0
     color-mix(in srgb, var(--fui-text-primary, #{$fui-text-primary}) 5%, transparent);
   overflow: hidden auto;
 
@@ -285,7 +298,7 @@
   border: var(--fui-stroke-hairline, 1px) 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, 1px) 0
     color-mix(in srgb, var(--fui-text-primary, #{$fui-text-primary}) 5%, transparent);
   overflow: hidden;