@sableui/react 0.17.0 → 0.19.0

package/dist/components/sidebar/sidebar.js

@@ -5,9 +5,12 @@ import { useRender } from "@base-ui/react/use-render";
 import {
   createContext,
   useContext,
+  useId,
   useState
 } from "react";
+import { Icon } from "../../icon/index.js";
 import { cn } from "../../lib/cn.js";
+import { useDensity } from "../../lib/density.js";
 import { HighlightGlide } from "../../lib/highlight-glide.js";
 import { motionAttribute } from "../../motion/MotionProvider.js";
 import { useAppShellFrame } from "../app-shell/app-shell-frame.js";
@@ -16,7 +19,8 @@ import { SimpleTooltip } from "../tooltip/index.js";
 import { Fragment, jsx, jsxs } from "react/jsx-runtime";
 var SidebarContext = createContext({
   collapsed: false,
-  icons: true
+  icons: true,
+  rung: "rail"
 });
 var LABEL_FADE = "starting:opacity-0 transition-opacity duration-(--motion-duration-base) ease-decelerate";
 function useSidebar() {
@@ -58,7 +62,8 @@ function Sidebar({
   const [hasCollapsed, setHasCollapsed] = useState(collapsed);
   if (collapsed && !hasCollapsed) setHasCollapsed(true);
   const inset = useAppShellFrame() === "inset";
-  return /* @__PURE__ */ jsx(SidebarContext.Provider, { value: { collapsed, icons, reopened: hasCollapsed && !collapsed }, children: /* @__PURE__ */ jsx(
+  const rung = useDensity() === "compact" ? "rail-compact" : "rail";
+  return /* @__PURE__ */ jsx(SidebarContext.Provider, { value: { collapsed, icons, reopened: hasCollapsed && !collapsed, rung }, children: /* @__PURE__ */ jsx(
     "aside",
     {
       "data-motion": motionAttribute(motion),
@@ -103,12 +108,15 @@ function SidebarHeader({
   className,
   ...props
 }) {
-  const { collapsed } = useSidebar();
+  const { collapsed, rung } = useSidebar();
   return /* @__PURE__ */ jsx(
     "div",
     {
       className: cn(
-        "flex min-h-16 flex-wrap content-center items-center gap-y-2 px-3 has-[>:nth-child(2)]:py-3",
+        "flex flex-wrap content-center items-center gap-y-2 px-3",
+        // Compact, the brand row is the height of the tool's own chrome bar,
+        // so it lines up with the WorkspaceBar beside it.
+        rung === "rail-compact" ? "min-h-(--chrome-bar-height) has-[>:nth-child(2)]:py-2" : "min-h-16 has-[>:nth-child(2)]:py-3",
         // Collapsed, the brand mark centres on the same axis as the item icons.
         collapsed && "justify-center px-0",
         className
@@ -119,7 +127,7 @@ function SidebarHeader({
 }
 SidebarHeader.displayName = "SidebarHeader";
 function SidebarBrand({ mark, label, render, className, "aria-label": ariaLabel, ...props }) {
-  const { collapsed, reopened } = useSidebar();
+  const { collapsed, reopened, rung } = useSidebar();
   return useRender({
     render: render ?? /* @__PURE__ */ jsx("div", {}),
     props: {
@@ -135,7 +143,7 @@ function SidebarBrand({ mark, label, render, className, "aria-label": ariaLabel,
         className
       ),
       children: /* @__PURE__ */ jsxs(Fragment, { children: [
-        /* @__PURE__ */ jsx("span", { className: sideNavItemIconVariants({ size: "rail" }), children: mark }),
+        /* @__PURE__ */ jsx("span", { className: sideNavItemIconVariants({ size: rung }), children: mark }),
         collapsed ? null : /* @__PURE__ */ jsx("span", { className: cn("min-w-0 truncate text-title-sm", reopened && LABEL_FADE), children: label })
       ] })
     },
@@ -148,6 +156,7 @@ function SidebarNav({
   children,
   ...props
 }) {
+  const { rung } = useSidebar();
   return /* @__PURE__ */ jsxs(
     "nav",
     {
@@ -155,7 +164,8 @@ function SidebarNav({
         // Thin scrollbar so a long nav does not hand a fat platform bar to a
         // narrow rail, and contained overscroll so a wheel gesture that runs
         // out of nav stops there instead of scrolling the page behind it.
-        "flex flex-1 flex-col gap-1 overflow-y-auto overscroll-contain px-3 py-4 scrollbar-quiet",
+        "flex flex-1 flex-col overflow-y-auto overscroll-contain px-3 scrollbar-quiet",
+        rung === "rail-compact" ? "gap-0.5 py-2" : "gap-1 py-4",
         "[&[data-glide]_[data-active]]:bg-transparent",
         className
       ),
@@ -173,11 +183,13 @@ function SidebarFooter({
   ...props
 }) {
   const inset = useAppShellFrame() === "inset";
+  const { rung } = useSidebar();
   return /* @__PURE__ */ jsx(
     "div",
     {
       className: cn(
-        "flex flex-col gap-1 border-t border-sidebar-border px-3 py-4",
+        "flex flex-col gap-1 border-t border-sidebar-border px-3",
+        rung === "rail-compact" ? "py-2" : "py-4",
         // In an inset shell the rail has no edge of its own (the gap is the
         // divider), so a full-width rule ran out into that gap and stopped on
         // nothing. Inset to the content column it spans what the rows span:
@@ -201,7 +213,7 @@ function SidebarItem({
   "aria-label": ariaLabel,
   ...props
 }) {
-  const { collapsed, icons, reopened } = useSidebar();
+  const { collapsed, icons, reopened, rung } = useSidebar();
   const showIcon = icon != null && (icons || collapsed);
   const element = useRender({
     render: render ?? /* @__PURE__ */ jsx("button", { type: "button" }),
@@ -214,12 +226,12 @@ function SidebarItem({
       "aria-label": ariaLabel ?? (collapsed && typeof label === "string" ? label : void 0),
       className: cn(
         // SideNav's row recipe on the rail rung — one row, not a copy.
-        sideNavItemVariants({ size: "rail", activeVariant: "sidebar" }),
+        sideNavItemVariants({ size: rung, activeVariant: "sidebar" }),
         collapsed && "justify-center px-0",
         className
       ),
       children: /* @__PURE__ */ jsxs(Fragment, { children: [
-        showIcon ? /* @__PURE__ */ jsx("span", { className: sideNavItemIconVariants({ size: "rail" }), children: icon }) : null,
+        showIcon ? /* @__PURE__ */ jsx("span", { className: sideNavItemIconVariants({ size: rung }), children: icon }) : null,
         collapsed ? null : /* @__PURE__ */ jsxs(Fragment, { children: [
           /* @__PURE__ */ jsx("span", { className: cn("min-w-0 flex-1 truncate", reopened && LABEL_FADE), children: label }),
           badge ? /* @__PURE__ */ jsx("span", { className: "ms-auto shrink-0", children: badge }) : null
@@ -234,10 +246,77 @@ function SidebarItem({
   return element;
 }
 SidebarItem.displayName = "SidebarItem";
+function SidebarGroup({ label, className, children, ...props }) {
+  const { collapsed, rung } = useSidebar();
+  const labelId = useId();
+  return /* @__PURE__ */ jsxs(
+    "div",
+    {
+      role: "group",
+      "aria-labelledby": label ? labelId : void 0,
+      className: cn("flex flex-col", rung === "rail-compact" ? "gap-0.5" : "gap-1", className),
+      ...props,
+      children: [
+        label ? collapsed ? /* @__PURE__ */ jsxs(Fragment, { children: [
+          /* @__PURE__ */ jsx("span", { id: labelId, className: "sr-only", children: label }),
+          /* @__PURE__ */ jsx("div", { "aria-hidden": true, className: "mx-3 my-2 h-px bg-sidebar-border" })
+        ] }) : /* @__PURE__ */ jsx("div", { id: labelId, className: "truncate px-3 pt-4 pb-1 text-caption text-muted-foreground", children: label }) : null,
+        children
+      ]
+    }
+  );
+}
+SidebarGroup.displayName = "SidebarGroup";
+function SidebarAccount({
+  avatar,
+  label,
+  detail,
+  indicator,
+  render,
+  className,
+  "aria-label": ariaLabel,
+  ...props
+}) {
+  const { collapsed, reopened, rung } = useSidebar();
+  const element = useRender({
+    // design-lint-disable-next-line raw-button -- a rail row with its own anatomy (avatar slot, two-line label, chevron) on SidebarItem's row recipe, and usually a MenuTrigger's render target; not a button-shaped action
+    render: render ?? /* @__PURE__ */ jsx("button", { type: "button" }),
+    props: {
+      ...props,
+      "aria-label": ariaLabel ?? (collapsed && typeof label === "string" ? label : void 0),
+      className: cn(
+        sideNavItemVariants({ size: rung, activeVariant: "sidebar" }),
+        // Holds the hover fill while its menu is open, so the row reads as
+        // the thing the menu came from.
+        "data-[popup-open]:bg-sidebar-accent data-[popup-open]:text-sidebar-accent-foreground",
+        collapsed && "justify-center px-0",
+        className
+      ),
+      children: /* @__PURE__ */ jsxs(Fragment, { children: [
+        /* @__PURE__ */ jsx("span", { className: sideNavItemIconVariants({ size: rung }), children: avatar }),
+        collapsed ? null : /* @__PURE__ */ jsxs(Fragment, { children: [
+          /* @__PURE__ */ jsxs("span", { className: cn("flex min-w-0 flex-1 flex-col", reopened && LABEL_FADE), children: [
+            /* @__PURE__ */ jsx("span", { className: "truncate", children: label }),
+            detail ? /* @__PURE__ */ jsx("span", { className: "truncate text-caption text-muted-foreground", children: detail }) : null
+          ] }),
+          indicator === false ? null : /* @__PURE__ */ jsx("span", { className: "ms-auto flex shrink-0 text-muted-foreground", "aria-hidden": true, children: indicator ?? /* @__PURE__ */ jsx(Icon, { name: "chevron-up-down", className: "text-base" }) })
+        ] })
+      ] })
+    },
+    defaultTagName: "button"
+  });
+  if (collapsed) {
+    return /* @__PURE__ */ jsx(SimpleTooltip, { content: label, side: "right", children: element });
+  }
+  return element;
+}
+SidebarAccount.displayName = "SidebarAccount";
 export {
   Sidebar,
+  SidebarAccount,
   SidebarBrand,
   SidebarFooter,
+  SidebarGroup,
   SidebarHeader,
   SidebarItem,
   SidebarNav,

package/dist/components/sidebar/sidebar.meta.js

@@ -1,13 +1,21 @@
 // src/components/sidebar/sidebar.meta.ts
 var sidebarMeta = {
   name: "Sidebar",
-  summary: "Desktop side-navigation rail (in-flow sticky, hidden below lg) with SidebarHeader / SidebarBrand / SidebarNav / SidebarItem / SidebarFooter parts. Items are router-agnostic via the `render` prop; an optional collapsed icon-rail mode reveals labels in tooltips.",
+  summary: "Desktop side-navigation rail (in-flow sticky, hidden below lg) with SidebarHeader / SidebarBrand / SidebarNav / SidebarGroup / SidebarItem / SidebarFooter / SidebarAccount parts, all on one set of columns. Items are router-agnostic via the `render` prop; an optional collapsed icon-rail mode reveals labels in tooltips.",
   status: "stable",
   keywords: [
     "sidebar",
     "navigation",
     "app chrome",
-    "rail"
+    "rail",
+    "nav group",
+    "section label",
+    "account",
+    "user menu",
+    "profile",
+    "account switcher",
+    "workspace switcher",
+    "sidebar footer"
   ],
   usage: {
     description: "Use Sidebar for persistent desktop navigation or application chrome outside the main content region.",
@@ -28,6 +36,18 @@ var sidebarMeta = {
         guidance: "do",
         description: `Keep surface="rail" inside AppShell frame="inset": the rail's tint becomes the ground the main panel floats on. Do not add a border-r class back \u2014 the gap is the divider.`
       },
+      {
+        guidance: "do",
+        description: "Group items with SidebarGroup and end the rail with one SidebarAccount that opens the account menu (settings, appearance, sign out). Every part sits on the same icon and label columns, at either density."
+      },
+      {
+        guidance: "dont",
+        description: "Do not put SideNav, an Entity or a stack of ghost Buttons in the rail. Each brings its own insets, so the icons and labels land on four different columns. SideNav is the in-page section list; the rail has its own parts."
+      },
+      {
+        guidance: "dont",
+        description: "Do not put a Badge or pill in the account row. Its one quiet detail line carries the plan, role or 'Demo'."
+      },
       {
         guidance: "dont",
         description: "Do not use Sidebar for page-local settings, filters, or temporary action groups."
@@ -93,7 +113,7 @@ var sidebarMeta = {
     {
       name: "SidebarHeader",
       type: "div props",
-      description: "The top of the rail, at least 64px tall. It holds SidebarBrand and may take a second row under it, such as a search field or a notifications button: give that row basis-full and the header grows to hold it instead of clipping."
+      description: "The top of the rail, at least 64px tall (the chrome bar's height inside a compact Workspace, so it lines up with the WorkspaceBar beside it). It holds SidebarBrand and may take a second row under it, such as a search field or a notifications button: give that row basis-full and the header grows to hold it instead of clipping."
     },
     {
       name: "SidebarBrand",
@@ -103,7 +123,17 @@ var sidebarMeta = {
     {
       name: "SidebarItem",
       type: "{ label: ReactNode; icon?: ReactNode; active?: boolean; badge?: ReactNode; render?: useRender.RenderProp } + button props",
-      description: 'A single nav row. label is the row text (inline when expanded, in a hover tooltip when collapsed); icon is the leading icon node (the consumer swaps fill weight for the active state); active marks the current route (accent fill + aria-current="page"); badge is a trailing node (e.g. a count) pushed to the row end and hidden when collapsed; render composes another element, e.g. render={<Link to="/x" />}.'
+      description: 'A single nav row, 44px on a page and 32px inside a compact scope such as a Workspace (the rail reads the density; nothing to set). label is the row text (inline when expanded, in a hover tooltip when collapsed); icon is the leading icon node (the consumer swaps fill weight for the active state); active marks the current route (accent fill + aria-current="page"); badge is a trailing node (e.g. a count) pushed to the row end and hidden when collapsed; render composes another element, e.g. render={<Link to="/x" />}.'
+    },
+    {
+      name: "SidebarGroup",
+      type: "{ label?: ReactNode } + div props",
+      description: `A labelled run of SidebarItems inside SidebarNav ("Workspace", "Favorites"). The label starts on the items' icon column; collapsed, a hairline stands in for it and the label stays as the group's accessible name.`
+    },
+    {
+      name: "SidebarAccount",
+      type: "{ avatar: ReactNode; label: ReactNode; detail?: ReactNode; indicator?: ReactNode | false; render?: useRender.RenderProp } + button props",
+      description: "The account row at the foot of the rail, inside SidebarFooter: the avatar in the icon slot (Avatar xs on a page rail, 2xs in a compact one), the label on the label column, one muted detail line, and an up-down chevron. Make it the trigger of the account Menu (render it through MenuTrigger render) and put Settings, appearance and sign-out there; it holds its fill while the menu is open. Collapsed, the avatar alone, with the label in a tooltip."
     }
   ],
   motion: [
@@ -165,6 +195,10 @@ var sidebarMeta = {
       label: "Collapsible (icon rail)",
       code: 'const [collapsed, setCollapsed] = useState(false)\n<Sidebar collapsed={collapsed}><SidebarNav><SidebarItem icon={<Icon name="home" />} label="Home" active render={<Link to="/" />} /></SidebarNav><SidebarFooter><Button variant="ghost" size="icon" onClick={() => setCollapsed((c) => !c)} aria-label="Toggle sidebar"><Icon name="chevron-left" /></Button></SidebarFooter></Sidebar>'
     },
+    {
+      label: "Grouped nav with an account menu",
+      code: '<Sidebar><SidebarHeader><SidebarBrand mark={<Avatar shape="square" size="xs" fallback="F" alt="" />} label="Forma Studio" /></SidebarHeader><SidebarNav><SidebarItem icon={<Icon name="inbox" />} label="Inbox" badge={<span className="text-ui-num">4</span>} /><SidebarGroup label="Workspace"><SidebarItem icon={<Icon name="folder" />} label="Projects" active /><SidebarItem icon={<Icon name="users" />} label="Clients" /></SidebarGroup></SidebarNav><SidebarFooter><Menu><MenuTrigger render={<SidebarAccount avatar={<Avatar size="xs" fallback="EL" alt="" />} label="Emma Lee" detail="Forma Studio" />} /><MenuContent side="top" align="start"><MenuItem>Settings</MenuItem><MenuSeparator /><MenuItem>Sign out</MenuItem></MenuContent></Menu></SidebarFooter></Sidebar>'
+    },
     {
       label: "Inline (inside a bounded frame)",
       code: '<div className="flex h-80 overflow-hidden rounded-lg border border-border"><Sidebar variant="inline"><SidebarNav><SidebarItem icon={<Icon name="home" />} label="Home" active /></SidebarNav></Sidebar><div className="flex-1 p-6">Content</div></div>'

package/dist/components/table/table.js

@@ -1,7 +1,11 @@
+"use client";
+
 // src/components/table/table.tsx
 import { cn } from "../../lib/cn.js";
+import { useDensity } from "../../lib/density.js";
 import { jsx } from "react/jsx-runtime";
 function Table({ className, ...props }) {
+  const tier = useDensity() === "compact" ? "text-ui-body" : "text-body-sm";
   return (
     // Thin scrollbar so a wide table's horizontal bar reads as part of the
     // table rather than as chrome, and contained overscroll so swiping past
@@ -9,7 +13,7 @@ function Table({ className, ...props }) {
     /* @__PURE__ */ jsx("div", { className: "w-full overflow-x-auto overscroll-x-contain scrollbar-quiet", children: /* @__PURE__ */ jsx(
       "table",
       {
-        className: cn("w-full caption-bottom text-body-sm", className),
+        className: cn("w-full caption-bottom", tier, className),
         ...props
       }
     ) })
@@ -66,7 +70,7 @@ function TableHead({ className, numeric = false, ...props }) {
     "th",
     {
       className: cn(
-        "h-10 px-3 text-start align-middle text-label-md text-muted-foreground first:ps-[var(--table-edge-px,--spacing(3))] last:pe-[var(--table-edge-px,--spacing(3))]",
+        "h-[var(--table-head-h,--spacing(10))] px-3 text-start align-middle text-label-md text-muted-foreground first:ps-[var(--table-edge-px,--spacing(3))] last:pe-[var(--table-edge-px,--spacing(3))]",
         numeric && NUMERIC,
         className
       ),
@@ -80,7 +84,7 @@ function TableCell({ className, numeric = false, ...props }) {
     "td",
     {
       className: cn(
-        "px-3 py-2.5 align-middle first:ps-[var(--table-edge-px,--spacing(3))] last:pe-[var(--table-edge-px,--spacing(3))]",
+        "px-3 py-[var(--table-cell-py,--spacing(2.5))] align-middle first:ps-[var(--table-edge-px,--spacing(3))] last:pe-[var(--table-edge-px,--spacing(3))]",
         numeric && NUMERIC,
         className
       ),

package/dist/components/tabs/tabs.js

@@ -21,7 +21,15 @@ function TabsList({ className, variant = "underline", children, ...props }) {
     {
       "data-variant": variant,
       className: cn(
-        variant === "underline" ? cn("relative inline-flex items-center gap-1 border-b border-border", UNDERLINE_HANDOFF) : cn("relative inline-flex items-center gap-1", PILL_HANDOFF),
+        variant === "underline" ? cn(
+          "relative inline-flex items-center gap-1 border-b border-border",
+          // In a WorkspaceBar the bar's hairline IS the divider: the list
+          // fills the bar's height, drops its own rule (which stopped
+          // after the last tab, a second line above the bar's), and the
+          // mark lands on the bar's edge.
+          "[[data-workspace-bar]_&]:self-stretch [[data-workspace-bar]_&]:border-b-0",
+          UNDERLINE_HANDOFF
+        ) : cn("relative inline-flex items-center gap-1", PILL_HANDOFF),
         className
       ),
       ...props,
@@ -48,7 +56,7 @@ function TabsTrigger({ className, children, ...props }) {
         variant === "underline" ? (
           // On the control ladder like the pill variant (it was py-2 plus
           // the label's line, ~36px — no rung).
-          "-mb-px inline-flex h-(--control-md) items-center gap-(--control-gap) border-b-2 border-transparent px-3 data-[active]:border-foreground"
+          "-mb-px inline-flex h-(--control-md) items-center gap-(--control-gap) border-b-2 border-transparent px-3 data-[active]:border-foreground [[data-workspace-bar]_&]:h-full"
         ) : "inline-flex h-(--control-sm) items-center gap-(--control-gap) rounded-[var(--button-radius,9999px)] px-3 data-[active]:bg-muted",
         className
       ),

package/dist/components/tabs/tabs.meta.js

@@ -16,6 +16,10 @@ var tabsMeta = {
         guidance: "do",
         description: "Use tabs when each panel is peer content and users may compare or switch often."
       },
+      {
+        guidance: "do",
+        description: `In tool chrome (a WorkspaceBar, a compact panel header) use variant="pill" for a view switch such as Overview / Issues / Updates: it reads as a control beside the bar's other controls. Underline is the page-section idiom; inside a WorkspaceBar it sits on the bar's hairline rather than drawing its own.`
+      },
       {
         guidance: "do",
         description: "Keep tab labels short and make the active tab unmistakable."

package/dist/components/workspace/workspace.js

@@ -7,6 +7,7 @@ import { jsx, jsxs } from "react/jsx-runtime";
 function Workspace({
   toolbar,
   statusBar,
+  bottomNav,
   density = "compact",
   skipLinkLabel = "Skip to canvas",
   className,
@@ -24,7 +25,7 @@ function Workspace({
       {
         "data-density": density,
         className: cn(
-          "grid h-dvh grid-rows-[auto_minmax(0,1fr)_auto] overflow-hidden bg-canvas text-canvas-foreground",
+          "flex h-dvh flex-col overflow-hidden bg-canvas text-canvas-foreground",
           className
         ),
         ...props,
@@ -38,8 +39,16 @@ function Workspace({
             }
           ),
           toolbar,
-          /* @__PURE__ */ jsx("div", { className: "grid min-h-0 grid-cols-1", children }),
-          statusBar
+          /* @__PURE__ */ jsx("div", { "data-workspace-body": "", className: "grid min-h-0 flex-1 grid-cols-1 grid-rows-[minmax(0,1fr)]", children }),
+          statusBar,
+          bottomNav ? /* @__PURE__ */ jsx(
+            "div",
+            {
+              "data-workspace-bottom-nav": "",
+              className: "h-[calc(var(--nav-height,56px)+env(safe-area-inset-bottom,0px))] shrink-0 lg:hidden",
+              children: bottomNav
+            }
+          ) : null
         ]
       }
     ) })
@@ -62,6 +71,7 @@ function WorkspaceBar({ className, children, ...props }) {
   return /* @__PURE__ */ jsx(
     "header",
     {
+      "data-workspace-bar": "",
       className: cn(
         "flex h-(--chrome-bar-height) shrink-0 items-center gap-1 border-b border-hairline bg-panel px-2",
         className

package/dist/components/workspace/workspace.meta.js

@@ -12,7 +12,18 @@ var workspaceMeta = {
     "chrome",
     "panels",
     "density",
-    "viewport"
+    "viewport",
+    "issue tracker",
+    "tracker",
+    "inspector",
+    "reading view",
+    "mobile",
+    "responsive",
+    "bottom nav",
+    "media query",
+    "breakpoint",
+    "top bar",
+    "topbar"
   ],
   usage: {
     description: 'Use Workspace as the outer frame for a tool \u2014 an editor, a console, a canvas app. It owns the viewport, scopes the compact control density, and guarantees a skip link plus a main landmark on the canvas. Reach for AppShell instead for page-register products: it is built around a scrolling document, where a workspace is built around a fixed one. Workspace fills the viewport (h-dvh) by design; to embed one in a page (a docs preview, a modal-sized demo), wrap it in a bounded container and pass className="h-full".',
@@ -29,6 +40,18 @@ var workspaceMeta = {
         guidance: "do",
         description: "Keep the density scope at compact unless you have a specific reason; the workspace register's measured control ladder is what makes tool chrome read as tool chrome."
       },
+      {
+        guidance: "do",
+        description: "Put a WorkspaceBar inside a column when the bar belongs to that column only. An issue tracker's bar (breadcrumb, view tabs, filters) sits above the list, while the sidebar and the inspector beside it run the full height: put the WorkspaceBar first inside the WorkspaceCanvas, not in the `toolbar` slot, which spans every panel. Don't hand-build a fixed-height header for it."
+      },
+      {
+        guidance: "do",
+        description: 'Wrap a reading view inside the workspace (a project overview, an update, a doc, release notes) in <Density value="comfortable">. The compact scope maps body text to the 11\u201312px UI tiers, which is right for chrome and too small for paragraphs; the comfortable scope gives prose its page size again while the chrome around it stays compact.'
+      },
+      {
+        guidance: "do",
+        description: 'Plan the phone layout with the shell rather than around it: pass a BottomNav to `bottomNav`, and give docked Panels `narrow="sheet"` (an inspector, a navigation rail) or `narrow="hidden"`. Don\'t measure the viewport with a resize listener, render the inspector twice, or subtract the nav\'s height from 100dvh.'
+      },
       {
         guidance: "dont",
         description: "Nest a Region or Page inside it to set a width. Region caps are a page-register idea; a workspace is edge-to-edge and its panels are fixed-width chrome outside the content grid."
@@ -66,6 +89,11 @@ var workspaceMeta = {
         name: "StatusBar",
         required: false,
         description: "Bottom chrome for ambient document facts."
+      },
+      {
+        name: "BottomNav",
+        required: false,
+        description: "Phone navigation in the `bottomNav` slot. Its row is reserved below lg and gone above it, so the body ends where the nav begins."
       }
     ]
   },
@@ -80,6 +108,11 @@ var workspaceMeta = {
       description: "Top chrome, normally a WorkspaceBar."
     },
     { name: "statusBar", type: "ReactNode", description: "Bottom chrome, normally a StatusBar." },
+    {
+      name: "bottomNav",
+      type: "ReactNode",
+      description: "Phone navigation, normally a BottomNav. Below lg (BottomNav's own breakpoint) the shell reserves the nav's height as its last row, so the body and the status bar end above the nav instead of under it; above lg the row is gone. Every slot is optional: the body is the shell's one growing row whichever of toolbar, statusBar and bottomNav are present."
+    },
     {
       name: "density",
       type: '"compact" | "comfortable"',
@@ -103,6 +136,16 @@ var workspaceMeta = {
       name: "WorkspaceCanvas",
       type: "ComponentProps<'main'>",
       description: "The work surface: renders main#main-content, fills the body, clips its overflow."
+    },
+    {
+      name: "useMediaQuery",
+      type: "(query: string, options?: { serverValue?: boolean }) => boolean",
+      description: "True while a media query matches, read through useSyncExternalStore: no resize listener, no setState in an effect, no hydration mismatch (the server reports serverValue, default false). Use it to branch structure a class cannot express; style-only changes stay as lg: classes."
+    },
+    {
+      name: "useBelowBreakpoint",
+      type: '(breakpoint?: "sm" | "md" | "lg" | "xl" | "2xl", options?: { serverValue?: boolean }) => boolean',
+      description: "True below a named breakpoint (default lg), flipping at the width where that breakpoint's classes start to apply (Tailwind's sm 40 / md 48 / lg 64 / xl 80 / 2xl 96rem). Panel's `narrow` uses it; reach for it instead of a hand-rolled window.innerWidth check."
     }
   ],
   a11y: [
@@ -164,6 +207,71 @@ var workspaceMeta = {
       <div className="p-3 text-ui-num text-muted-foreground">log output\u2026</div>
     </WorkspaceCanvas>
   </PanelGroup>
+</Workspace>`
+    },
+    {
+      label: "Issue tracker: column bar, docked inspector, phone sheet",
+      code: `function Tracker() {
+  const [selected, setSelected] = useState<string | null>("AES-104")
+  return (
+    <Workspace
+      bottomNav={
+        <BottomNav>
+          <BottomNavItem showLabel label="Issues" icon={<Icon name="list" />} active />
+          <BottomNavItem showLabel label="Inbox" icon={<Icon name="inbox" />} />
+        </BottomNav>
+      }
+      statusBar={<StatusBar><span>12 issues</span></StatusBar>}
+    >
+      <PanelGroup>
+        <Panel label="Navigation" width={220} narrow="hidden">
+          <PanelSection title="Workspace">
+            <PropertyRow label="Team"><Input defaultValue="Studio" /></PropertyRow>
+          </PanelSection>
+        </Panel>
+        <WorkspaceCanvas className="flex flex-col">
+          <WorkspaceBar>
+            <Breadcrumbs>
+              <BreadcrumbItem><BreadcrumbLink href="#">Studio</BreadcrumbLink></BreadcrumbItem>
+              <BreadcrumbSeparator />
+              <BreadcrumbItem><BreadcrumbPage>Digital flagship</BreadcrumbPage></BreadcrumbItem>
+            </Breadcrumbs>
+          </WorkspaceBar>
+          <div className="min-h-0 flex-1 overflow-y-auto scrollbar-quiet">
+            <Button size="xs" variant="ghost" onClick={() => setSelected("AES-104")}>AES-104 Refine product page</Button>
+          </div>
+        </WorkspaceCanvas>
+        <Panel
+          label="Issue details"
+          width={320}
+          narrow="sheet"
+          open={selected !== null}
+          onOpenChange={(open) => !open && setSelected(null)}
+        >
+          <PanelSection title={selected ?? ""}>
+            <PropertyRow label="Status"><Input defaultValue="In progress" /></PropertyRow>
+          </PanelSection>
+        </Panel>
+      </PanelGroup>
+    </Workspace>
+  )
+}`
+    },
+    {
+      label: "Reading view inside a workspace",
+      code: `<Workspace>
+  <PanelGroup>
+    <WorkspaceCanvas className="overflow-y-auto scrollbar-quiet">
+      <Density value="comfortable">
+        <article className="max-w-prose p-6">
+          <h2 className="text-heading-3">Project overview</h2>
+          <p className="mt-3 text-body-md text-muted-foreground">
+            Paragraphs keep their page size here, while the chrome around the canvas stays compact.
+          </p>
+        </article>
+      </Density>
+    </WorkspaceCanvas>
+  </PanelGroup>
 </Workspace>`
     },
     {