@usefragments/ui 1.5.4 → 1.7.0

package/src/components/Alert/Alert.module.scss

@@ -1,67 +1,81 @@
 @use "../../tokens/variables" as *;
 @use "../../tokens/mixins" as *;
+@use "../../recipes/feedback" as feedback;
 
 .alert {
-  display: flex;
-  // Single-line alerts (icon + one line, no title) read best vertically
-  // centered. Multi-line alerts top-align instead — see `:has(.title)` below.
-  align-items: center;
-  gap: var(--fui-space-3, $fui-space-3);
-  padding: var(--fui-space-2, $fui-space-2) var(--fui-space-3, $fui-space-3);
-  border-radius: var(--fui-radius-lg, $fui-radius-lg);
-  font-family: var(--fui-font-sans, $fui-font-sans);
-  font-size: var(--fui-font-size-sm, $fui-font-size-sm);
-  line-height: var(--fui-line-height-normal, $fui-line-height-normal);
+  @include feedback.contextual;
+
+  border-radius: var(--fui-card-radius, var(--fui-radius-lg, $fui-radius-lg));
 }
 
-// With a title (title + description), the block is multi-line: top-align so
-// the icon and close sit with the first line rather than the block's centre.
 .alert:has(.title) {
   align-items: flex-start;
 }
 
-// Severity variants
 .info {
   background: var(--fui-color-info-bg, $fui-color-info-bg);
-  border: 1px solid var(--fui-color-info-border, $fui-color-info-border);
+  border: var(--fui-stroke-hairline, 1px) solid var(--fui-color-info-border, $fui-color-info-border);
   color: var(--fui-color-info-text, $fui-color-info-text);
 }
 
 .success {
   background: var(--fui-color-success-bg, $fui-color-success-bg);
-  border: 1px solid var(--fui-color-success-border, $fui-color-success-border);
+  border: var(--fui-stroke-hairline, 1px) solid
+    var(--fui-color-success-border, $fui-color-success-border);
   color: var(--fui-color-success-text, $fui-color-success-text);
 }
 
 .warning {
   background: var(--fui-color-warning-bg, $fui-color-warning-bg);
-  border: 1px solid var(--fui-color-warning-border, $fui-color-warning-border);
+  border: var(--fui-stroke-hairline, 1px) solid
+    var(--fui-color-warning-border, $fui-color-warning-border);
   color: var(--fui-color-warning-text, $fui-color-warning-text);
 }
 
 .error {
   background: var(--fui-color-danger-bg, $fui-color-danger-bg);
-  border: 1px solid var(--fui-color-danger-border, $fui-color-danger-border);
+  border: var(--fui-stroke-hairline, 1px) solid
+    var(--fui-color-danger-border, $fui-color-danger-border);
+  color: var(--fui-color-danger-text, $fui-color-danger-text);
+}
+
+// `emphasis="surface"`: the card keeps the page's own surface and spends the
+// severity only on the hairline and the title. Declared after the severities
+// so it overrides their wash while their border survives.
+.surface {
+  background: var(--fui-bg-secondary, $fui-bg-secondary);
+  color: var(--fui-text-secondary, $fui-text-secondary);
+}
+
+.surface.info .title {
+  color: var(--fui-color-info-text, $fui-color-info-text);
+}
+
+.surface.success .title {
+  color: var(--fui-color-success-text, $fui-color-success-text);
+}
+
+.surface.warning .title {
+  color: var(--fui-color-warning-text, $fui-color-warning-text);
+}
+
+.surface.error .title {
   color: var(--fui-color-danger-text, $fui-color-danger-text);
 }
 
 .icon {
+  @include feedback.icon;
+
   display: flex;
   align-items: center;
   justify-content: center;
-  width: $fui-icon-lg;
-  height: $fui-icon-lg;
   border-radius: 50%;
-  font-size: var(--fui-font-size-xs, $fui-font-size-xs);
-  font-weight: var(--fui-font-weight-semibold, $fui-font-weight-semibold);
-  flex-shrink: 0;
   color: var(--fui-text-inverse, $fui-text-inverse);
+  font: inherit;
 }
 
-// Only nudge the icon down to meet the first text line when the alert is
-// multi-line; centered single-line alerts need no offset.
 .alert:has(.title) .icon {
-  margin-top: var(--fui-space-px, $fui-space-px);
+  margin-block-start: var(--fui-stroke-hairline, 1px);
 }
 
 .info .icon {
@@ -81,41 +95,38 @@
 }
 
 .body {
+  display: grid;
   flex: 1;
-  min-width: 0;
+  gap: var(--fui-feedback-text-gap, var(--fui-raw-space-4, 4px));
+  min-inline-size: 0;
 }
 
 .title {
-  font-weight: var(--fui-font-weight-semibold, $fui-font-weight-semibold);
-  margin-bottom: var(--fui-space-0-5, $fui-space-0-5);
+  @include feedback.title;
 }
 
 .content {
+  @include feedback.body;
+
   opacity: 0.9;
 }
 
 .actions {
   display: flex;
   align-items: center;
-  gap: var(--fui-space-3, $fui-space-3);
+  gap: var(--fui-feedback-transient-gap, var(--fui-raw-space-8, 8px));
 }
 
 .close {
   @include button-reset;
   @include interactive-base;
-  @include min-target-size;
+  @include feedback.close;
 
-  display: inline-flex;
-  align-items: center;
-  justify-content: center;
-  padding: 0 var(--fui-space-1, $fui-space-1);
-  font-size: var(--fui-font-size-lg, $fui-font-size-lg);
+  margin-inline-start: auto;
+  border-radius: var(--fui-radius-sm, $fui-radius-sm);
   color: inherit;
-  opacity: 0.6;
   line-height: 1;
-  border-radius: var(--fui-radius-sm, $fui-radius-sm);
-  margin-left: auto;
-  flex-shrink: 0;
+  opacity: 0.6;
 
   &:hover {
     opacity: 1;
@@ -124,12 +135,9 @@
 
 .action {
   @include button-reset;
-  @include min-target-size;
+  @include feedback.compact-action;
 
-  display: inline-flex;
-  align-items: center;
-  font-weight: var(--fui-font-weight-semibold, $fui-font-weight-semibold);
-  font-size: var(--fui-font-size-xs, $fui-font-size-xs);
+  border-radius: var(--fui-radius-sm, $fui-radius-sm);
   color: inherit;
   text-decoration: underline;
 

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",