@womp/kookie-ui 0.32.0 → 0.34.0

package/src/components/shell.css

@@ -26,8 +26,8 @@
 /* ── Frame ─────────────────────────────────────────────────────────────────── */
 
 .kui-ShellRoot {
-  /* Read by inset panes. Declared here, so the documented override on the Root works. */
-  --shell-inset-gap: var(--space-3);
+  /* The air around a pane pulled off the frame (`flush={false}`). Declared here, so the documented override on the Root works. */
+  --shell-gap: var(--space-3);
   /* Written inline by the Root while a Rail shows; stated here so a nested Shell never inherits its parent's. */
   --shell-rail-offset: 0px;
   /* How far the stuck header reaches down the screen while the page scrolls. Stated here so a nested Shell never inherits its parent's. */
@@ -938,68 +938,154 @@
   position: fixed;
 }
 
-/* ── Inset ─────────────────────────────────────────────────────────────────── */
+/* ── Flush and off the frame (from v2, 0.33.0) ─────────────────────────────── */
 
 /*
- * The backdrop behind the middle row while any pane is inset. A grid item of
- * its own, so the header and the bottom row keep the page. `:has()` paints it
- * from the server markup, before any script; `data-has-inset` is the Root's
- * own record, which also covers a pane wrapped in another element.
+ * Every pane says one thing about itself: whether it joins the app frame (`flush`, the default)
+ * or is pulled off it as a card (`flush={false}`). Whether a card floats or sits on the Shell's
+ * background is not stated anywhere; it falls out of the content's own answer, here, so it is
+ * right at first paint:
+ *
+ * - A flush pane is level with the page: square, no fill, no shadow, and one hairline in
+ *   `--color-border` on its inner edge. Each seam is drawn by exactly one pane, and the content
+ *   draws none, so two neighbours never double a line.
+ * - With the content flush, a card floats over it: the content's grid area grows underneath.
+ * - With the content off the frame, nothing floats. The Shell paints its background and every
+ *   pane, flush or not, sits on it; the content is a card, and a flush pane draws no hairline
+ *   toward it, because a line beside a card's own edge is a second boundary.
  */
-.kui-ShellRoot:has(> [data-inset])::before,
-.kui-ShellRoot[data-has-inset]::before {
-  content: '';
-  grid-row: 2;
-  grid-column: 1 / -1;
-  background: var(--neutral-2);
+
+.kui-ShellHeader[data-flush],
+.kui-ShellPane[data-flush],
+.kui-ShellContent[data-flush] {
+  border: 0 solid var(--color-border);
+  border-radius: 0;
+}
+
+.kui-ShellHeader[data-flush] {
+  border-block-end-width: 1px;
+}
+
+.kui-ShellRail[data-flush],
+.kui-ShellPanel[data-flush],
+.kui-ShellSidebar[data-flush] {
+  border-inline-end-width: 1px;
+}
+
+.kui-ShellInspector[data-flush] {
+  border-inline-start-width: 1px;
 }
 
-.kui-ShellPane[data-inset],
-.kui-ShellContent[data-inset] {
-  margin: var(--shell-inset-gap);
+.kui-ShellBottom[data-flush] {
+  border-block-start-width: 1px;
+}
+
+/* A seam needs something on the other side. Against a card content there is only the gap. The
+   Panel and the Rail face the content only when no flush pane stands between them. */
+.kui-ShellRoot:has(> .kui-ShellContent:not([data-flush])) > .kui-ShellHeader[data-flush] {
+  border-block-end-width: 0;
+}
+
+.kui-ShellRoot:has(> .kui-ShellContent:not([data-flush])) > .kui-ShellSidebar[data-flush],
+.kui-ShellRoot:has(> .kui-ShellContent:not([data-flush])):not(:has(> .kui-ShellSidebar[data-presentation='fixed'][data-mode]:not([data-mode='collapsed']))) > .kui-ShellPanel[data-flush],
+.kui-ShellRoot:has(> .kui-ShellContent:not([data-flush])):not(:has(> .kui-ShellPanel[data-presentation='fixed'][data-mode]:not([data-mode='collapsed']), > .kui-ShellSidebar[data-presentation='fixed'][data-mode]:not([data-mode='collapsed']))) > .kui-ShellRail[data-flush] {
+  border-inline-end-width: 0;
+}
+
+.kui-ShellRoot:has(> .kui-ShellContent:not([data-flush])) > .kui-ShellInspector[data-flush] {
+  border-inline-start-width: 0;
+}
+
+.kui-ShellRoot:has(> .kui-ShellContent:not([data-flush])) > .kui-ShellBottom[data-flush] {
+  border-block-start-width: 0;
+}
+
+/* Off the frame: a card, with its own air on every side. */
+.kui-ShellHeader:not([data-flush]),
+.kui-ShellPane:not([data-flush]),
+.kui-ShellContent:not([data-flush]) {
+  margin: var(--shell-gap);
   border-radius: var(--radius-surface-1);
-  background: var(--color-page);
+  background-color: var(--color-page);
   box-shadow: var(--surface-chrome);
 }
 
+/* A header card rests level with the panes below it, so its shadow falls behind them, not on them. */
+.kui-ShellHeader:not([data-flush]) {
+  z-index: 1;
+}
+
+/* With the content off the frame, the Shell paints the background the cards sit on. */
+.kui-ShellRoot:has(> .kui-ShellContent:not([data-flush])) {
+  background-color: var(--neutral-2);
+}
+
 /*
- * Two inset panes side by side share one gap rather than doubling it: the
- * later pane in the row drops the margin on the side that meets the earlier
- * one. Only the pane right beside it counts, and only while it is shown in
- * the frame (the JS mirror's data-presentation and data-mode), so a closed,
- * hidden or floating pane never takes the gap away. Before hydration the
- * gap is doubled.
+ * Two cards side by side share one gap rather than doubling it: the later card in the row drops
+ * its margin on the side that meets the earlier one, so card to card and card to edge come out
+ * equal. Only a pane shown in the frame counts.
  */
-.kui-ShellRoot:has(> .kui-ShellRail[data-inset][data-presentation='fixed'][data-mode]:not([data-mode='collapsed'])) > .kui-ShellPanel[data-inset][data-presentation='fixed'],
-.kui-ShellRoot:has(> .kui-ShellPanel[data-inset][data-presentation='fixed'][data-mode]:not([data-mode='collapsed'])) > .kui-ShellSidebar[data-inset][data-presentation='fixed'],
-.kui-ShellRoot:has(> .kui-ShellRail[data-inset][data-presentation='fixed'][data-mode]:not([data-mode='collapsed'])):not(
-    :has(> .kui-ShellPanel[data-presentation='fixed'][data-mode]:not([data-mode='collapsed']))
-  )
-  > .kui-ShellSidebar[data-inset][data-presentation='fixed'],
-.kui-ShellRoot:has(> .kui-ShellSidebar[data-inset][data-presentation='fixed'][data-mode]:not([data-mode='collapsed'])) > .kui-ShellContent[data-inset],
-.kui-ShellRoot:has(> .kui-ShellPanel[data-inset][data-presentation='fixed'][data-mode]:not([data-mode='collapsed'])):not(
-    :has(> .kui-ShellSidebar[data-presentation='fixed'][data-mode]:not([data-mode='collapsed']))
-  )
-  > .kui-ShellContent[data-inset],
-.kui-ShellRoot:has(> .kui-ShellRail[data-inset][data-presentation='fixed'][data-mode]:not([data-mode='collapsed'])):not(
-    :has(> .kui-ShellPanel[data-presentation='fixed'][data-mode]:not([data-mode='collapsed']), > .kui-ShellSidebar[data-presentation='fixed'][data-mode]:not([data-mode='collapsed']))
-  )
-  > .kui-ShellContent[data-inset],
-.kui-ShellRoot:has(> .kui-ShellContent[data-inset]) > .kui-ShellInspector[data-inset][data-presentation='fixed'] {
+.kui-ShellRoot:has(> .kui-ShellRail:not([data-flush])[data-presentation='fixed'][data-mode]:not([data-mode='collapsed'])) > .kui-ShellPanel:not([data-flush])[data-presentation='fixed'],
+.kui-ShellRoot:has(> .kui-ShellPanel:not([data-flush])[data-presentation='fixed'][data-mode]:not([data-mode='collapsed'])) > .kui-ShellSidebar:not([data-flush])[data-presentation='fixed'],
+.kui-ShellRoot:has(> .kui-ShellRail:not([data-flush])[data-presentation='fixed'][data-mode]:not([data-mode='collapsed'])):not(:has(> .kui-ShellPanel[data-presentation='fixed'][data-mode]:not([data-mode='collapsed']))) > .kui-ShellSidebar:not([data-flush])[data-presentation='fixed'],
+.kui-ShellRoot:has(> .kui-ShellSidebar:not([data-flush])[data-presentation='fixed'][data-mode]:not([data-mode='collapsed'])) > .kui-ShellContent:not([data-flush]),
+.kui-ShellRoot:has(> .kui-ShellPanel:not([data-flush])[data-presentation='fixed'][data-mode]:not([data-mode='collapsed'])):not(:has(> .kui-ShellSidebar[data-presentation='fixed'][data-mode]:not([data-mode='collapsed']))) > .kui-ShellContent:not([data-flush]),
+.kui-ShellRoot:has(> .kui-ShellRail:not([data-flush])[data-presentation='fixed'][data-mode]:not([data-mode='collapsed'])):not(:has(> .kui-ShellPanel[data-presentation='fixed'][data-mode]:not([data-mode='collapsed']), > .kui-ShellSidebar[data-presentation='fixed'][data-mode]:not([data-mode='collapsed']))) > .kui-ShellContent:not([data-flush]),
+.kui-ShellRoot:has(> .kui-ShellContent:not([data-flush])) > .kui-ShellInspector:not([data-flush])[data-presentation='fixed'] {
   margin-inline-start: 0;
 }
 
-.kui-ShellRoot:has(
-    > .kui-ShellRail[data-inset][data-presentation='fixed'][data-mode]:not([data-mode='collapsed']),
-    > .kui-ShellPanel[data-inset][data-presentation='fixed'][data-mode]:not([data-mode='collapsed']),
-    > .kui-ShellSidebar[data-inset][data-presentation='fixed'][data-mode]:not([data-mode='collapsed']),
-    > .kui-ShellContent[data-inset],
-    > .kui-ShellInspector[data-inset][data-presentation='fixed'][data-mode]:not([data-mode='collapsed'])
-  )
-  > .kui-ShellBottom[data-inset] {
+.kui-ShellRoot:has(> .kui-ShellHeader:not([data-flush])) > :is(.kui-ShellPane:not(.kui-ShellBottom), .kui-ShellContent):not([data-flush]),
+.kui-ShellRoot:has(> :is(.kui-ShellRail, .kui-ShellPanel, .kui-ShellSidebar, .kui-ShellInspector):not([data-flush])[data-presentation='fixed'][data-mode]:not([data-mode='collapsed']), > .kui-ShellContent:not([data-flush])) > .kui-ShellBottom:not([data-flush]) {
   margin-block-start: 0;
 }
 
+/* A card content pays no air toward a flush side pane in the frame: the pane's padding is the
+   air. Toward a flush header it keeps its gap, since a header's row has no padding below it. */
+.kui-ShellRoot:has(> .kui-ShellSidebar[data-flush][data-presentation='fixed'][data-mode]:not([data-mode='collapsed'])) > .kui-ShellContent:not([data-flush]),
+.kui-ShellRoot:has(> .kui-ShellPanel[data-flush][data-presentation='fixed'][data-mode]:not([data-mode='collapsed'])):not(:has(> .kui-ShellSidebar[data-presentation='fixed'][data-mode]:not([data-mode='collapsed']))) > .kui-ShellContent:not([data-flush]),
+.kui-ShellRoot:has(> .kui-ShellRail[data-flush][data-presentation='fixed'][data-mode]:not([data-mode='collapsed'])):not(:has(> .kui-ShellPanel[data-presentation='fixed'][data-mode]:not([data-mode='collapsed']), > .kui-ShellSidebar[data-presentation='fixed'][data-mode]:not([data-mode='collapsed']))) > .kui-ShellContent:not([data-flush]) {
+  margin-inline-start: 0;
+}
+
+.kui-ShellRoot:has(> .kui-ShellInspector[data-flush][data-presentation='fixed'][data-mode]:not([data-mode='collapsed'])) > .kui-ShellContent:not([data-flush]) {
+  margin-inline-end: 0;
+}
+
+.kui-ShellRoot:has(> .kui-ShellBottom[data-flush][data-presentation='fixed'][data-mode]:not([data-mode='collapsed'])) > .kui-ShellContent:not([data-flush]) {
+  margin-block-end: 0;
+}
+
+/*
+ * Floating: with the content flush, a card is over it, and the content's grid area grows to the
+ * card's own line so the content runs underneath. It grows only on the sides something floats
+ * on. The Rail and the Panel float over the content only when no flush pane stands between.
+ * The panes already sit above the content (`z-index` 1 against the content's isolated layer).
+ */
+.kui-ShellRoot:has(> .kui-ShellSidebar:not([data-flush])) > .kui-ShellContent[data-flush] {
+  grid-column-start: sidebar-start;
+}
+
+.kui-ShellRoot:has(> .kui-ShellPanel:not([data-flush])):not(:has(> .kui-ShellSidebar[data-flush])) > .kui-ShellContent[data-flush] {
+  grid-column-start: panel-start;
+}
+
+.kui-ShellRoot:has(> .kui-ShellRail:not([data-flush])):not(:has(> .kui-ShellPanel[data-flush], > .kui-ShellSidebar[data-flush])) > .kui-ShellContent[data-flush] {
+  grid-column-start: rail-start;
+}
+
+.kui-ShellRoot:has(> .kui-ShellInspector:not([data-flush])) > .kui-ShellContent[data-flush] {
+  grid-column-end: inspector-end;
+}
+
+.kui-ShellRoot:has(> .kui-ShellHeader:not([data-flush])) > .kui-ShellContent[data-flush] {
+  grid-row-start: header-start;
+}
+
+.kui-ShellRoot:has(> .kui-ShellBottom:not([data-flush])) > .kui-ShellContent[data-flush] {
+  grid-row-end: bottom-end;
+}
+
 /* ── On a phone, the page scrolls (0.27.0) ────────────────────────────────── */
 
 /*

package/src/components/shell.tsx

@@ -36,16 +36,16 @@ import { usePane, paneAttributes, usePresentationTable } from './_internal/shell
 import { splitHandles, useInitialPaneSize, useResizablePane } from './_internal/shell-resizable.js';
 import {
   FIXED_TABLE,
-  ShellInsetContext,
+  ShellFrameContext,
   ShellStoreContext,
   createShellStore,
   setShellPeek,
   subscribeShellStore,
-  useInsetRegistration,
+  useFrameRegistration,
   usePaneEntry,
   useShellStore,
   warnOnce,
-  type InsetPaneId,
+  type FramePaneId,
 } from './_internal/shell-store.js';
 import { navigationRest, detailRest, toPaneValue, startAnchoredGrowth, withoutRemovedPaneProps } from './_internal/shell-rest.js';
 import { useShell, useSidebarMode } from './shell.context.js';
@@ -145,20 +145,20 @@ const Root = React.forwardRef<HTMLDivElement, ShellRootProps>(({ className, chil
   const rootRef = React.useRef<HTMLDivElement | null>(null);
   const composedRef = useComposedRefs(ref, rootRef);
 
-  // Inset: the Root paints the backdrop while any pane is inset.
-  const [insetPanes, setInsetPanes] = React.useState<ReadonlySet<InsetPaneId>>(() => new Set());
-  const registerInset = React.useCallback((id: InsetPaneId) => {
-    setInsetPanes((prev) => (prev.has(id) ? prev : new Set(prev).add(id)));
+  // The panes pulled off the frame (`flush={false}`). Only the Rail's is read, for the offset below.
+  const [offFrame, setOffFrame] = React.useState<ReadonlySet<FramePaneId>>(() => new Set());
+  const registerOffFrame = React.useCallback((id: FramePaneId) => {
+    setOffFrame((prev) => (prev.has(id) ? prev : new Set(prev).add(id)));
   }, []);
-  const unregisterInset = React.useCallback((id: InsetPaneId) => {
-    setInsetPanes((prev) => {
+  const unregisterOffFrame = React.useCallback((id: FramePaneId) => {
+    setOffFrame((prev) => {
       if (!prev.has(id)) return prev;
       const next = new Set(prev);
       next.delete(id);
       return next;
     });
   }, []);
-  const insetContext = React.useMemo(() => ({ registerInset, unregisterInset }), [registerInset, unregisterInset]);
+  const frameContext = React.useMemo(() => ({ registerOffFrame, unregisterOffFrame }), [registerOffFrame, unregisterOffFrame]);
 
   const closeOverlays = React.useCallback(() => {
     for (const entry of store.entries.values()) {
@@ -444,10 +444,10 @@ const Root = React.forwardRef<HTMLDivElement, ShellRootProps>(({ className, chil
   };
 
   // A floating Panel sits beside the Rail when the Rail is showing, and
-  // beside its card when the Rail is inset.
+  // beside its card when the Rail is off the frame.
   const rail = store.entries.get('rail');
   const railShown = rail !== undefined && rail.value !== undefined && rail.value !== 'closed';
-  const railOffset = railShown ? (insetPanes.has('rail') ? `calc(${rail.size}px + 2 * var(--shell-inset-gap))` : `${rail.size}px`) : undefined;
+  const railOffset = railShown ? (offFrame.has('rail') ? `calc(${rail.size}px + 2 * var(--shell-gap))` : `${rail.size}px`) : undefined;
 
   // `full` writes no inline height: the stylesheet states it as 100vh with a
   // 100dvh override where supported, and an inline value would beat both.
@@ -459,7 +459,7 @@ const Root = React.forwardRef<HTMLDivElement, ShellRootProps>(({ className, chil
       <ShellContentContext.Provider value={false}>
       <ShellWindowContext.Provider value={windowShell}>
       <ShellHeaderHeightContext.Provider value={setHeaderHeight}>
-      <ShellInsetContext.Provider value={insetContext}>
+      <ShellFrameContext.Provider value={frameContext}>
       {/* A Shell inside a portalled surface's Theme starts with no band, like any other. */}
       <PaneBandSizeContext.Provider value={undefined}>
         {/* The Root is not a widget: it hears Escape bubbling up from the panes,
@@ -472,7 +472,6 @@ const Root = React.forwardRef<HTMLDivElement, ShellRootProps>(({ className, chil
           data-height={height === 'auto' && !contained ? 'auto' : undefined}
           data-contained={contained || undefined}
           data-window={windowShell || undefined}
-          data-has-inset={insetPanes.size > 0 || undefined}
           data-overlay-live={liveCount > 0 || undefined}
           onKeyDown={handleKeyDown}
           onFocus={handleFocus}
@@ -490,7 +489,7 @@ const Root = React.forwardRef<HTMLDivElement, ShellRootProps>(({ className, chil
           <div className="kui-ShellScrim" aria-hidden onClick={closeOverlays} />
         </div>
       </PaneBandSizeContext.Provider>
-      </ShellInsetContext.Provider>
+      </ShellFrameContext.Provider>
       </ShellHeaderHeightContext.Provider>
       </ShellWindowContext.Provider>
       </ShellContentContext.Provider>
@@ -504,9 +503,14 @@ Root.displayName = 'Shell.Root';
 
 interface ShellHeaderProps extends React.ComponentPropsWithoutRef<'header'> {
   height?: number;
+  /**
+   * Sets whether the header joins the app frame. The default is `true`: a hairline under it. Set
+   * `flush={false}` to make it a card off the frame.
+   */
+  flush?: boolean;
 }
 
-const Header = React.forwardRef<HTMLElement, ShellHeaderProps>(({ className, height = DEFAULT_HEADER_HEIGHT, style, ...props }, ref) => {
+const Header = React.forwardRef<HTMLElement, ShellHeaderProps>(({ className, height = DEFAULT_HEADER_HEIGHT, flush = true, style, ...props }, ref) => {
   // Rows that stick beneath the header while the page scrolls need its height. The stylesheet
   // assumes the default, so only another height is told to the Root.
   const setHeaderHeight = React.useContext(ShellHeaderHeightContext);
@@ -520,6 +524,7 @@ const Header = React.forwardRef<HTMLElement, ShellHeaderProps>(({ className, hei
       {...props}
       ref={ref}
       className={classNames('kui-ShellHeader', className)}
+      data-flush={flush || undefined}
       style={
         {
           ...style,
@@ -541,7 +546,6 @@ interface LeftProps extends React.ComponentPropsWithoutRef<'div'> {
   collapsible?: boolean;
   onExpand?: () => void;
   onCollapse?: () => void;
-  inset?: boolean;
 }
 
 /**
@@ -572,14 +576,19 @@ type RailProps = React.ComponentPropsWithoutRef<'div'> & {
   onExpand?: () => void;
   /** @deprecated Use `onOpenChange`. */
   onCollapse?: () => void;
-  /** When true, adds margin and triggers the gray backdrop on the Shell. */
-  inset?: boolean;
+  /**
+   * Sets whether this pane joins the app frame. The default is `true`: the pane sits against its
+   * neighbours with one hairline between them. Set `flush={false}` to pull it off the frame as a
+   * card. It then floats over the content if the content is flush, and otherwise sits on the
+   * Shell's background beside a card content.
+   */
+  flush?: boolean;
 } & (RailControlledProps | RailUncontrolledProps);
 
 const RAIL_PROP_NAMES = { controlled: 'open', default: 'defaultOpen' };
 
 const Rail = React.forwardRef<HTMLDivElement, RailProps>((props, ref) => {
-  const { className, presentation, expandedSize = 64, collapsible: _collapsible, onExpand, onCollapse, children, style, open, defaultOpen, onOpenChange, inset, id, ...domProps } = props;
+  const { className, presentation, expandedSize = 64, collapsible: _collapsible, onExpand, onCollapse, children, style, open, defaultOpen, onOpenChange, flush = true, id, ...domProps } = props;
   const { table, attributes } = usePresentationTable(presentation, 'fixed');
   const pane = usePane({
     name: 'rail',
@@ -595,7 +604,7 @@ const Rail = React.forwardRef<HTMLDivElement, RailProps>((props, ref) => {
     onCollapse,
     size: expandedSize,
   });
-  useInsetRegistration('rail', inset);
+  useFrameRegistration('rail', flush);
   const composedRef = useComposedRefs(ref, pane.setElement);
 
   return (
@@ -606,7 +615,7 @@ const Rail = React.forwardRef<HTMLDivElement, RailProps>((props, ref) => {
       ref={composedRef}
       className={classNames('kui-ShellPane', 'kui-ShellRail', className)}
       {...paneAttributes(pane, attributes)}
-      data-inset={inset || undefined}
+      data-flush={flush || undefined}
       tabIndex={pane.overlaying ? -1 : domProps.tabIndex}
       style={{ ...style, '--rail-size': `${expandedSize}px` } as CSSPropertiesWithVars}
     >
@@ -644,8 +653,13 @@ type PanelPublicProps = PaneBaseProps &
     onSizeChange?: (size: number, meta: PanelSizeChangeMeta) => void;
     sizeUpdate?: 'throttle' | 'debounce';
     sizeUpdateMs?: number;
-    /** When true, adds margin and triggers the gray backdrop on the Shell. */
-    inset?: boolean;
+    /**
+     * Sets whether this pane joins the app frame. The default is `true`: the pane sits against its
+     * neighbours with one hairline between them. Set `flush={false}` to pull it off the frame as a
+     * card. It then floats over the content if the content is flush, and otherwise sits on the
+     * Shell's background beside a card content.
+     */
+    flush?: boolean;
   };
 type PanelComponent = React.ForwardRefExoticComponent<PanelPublicProps & React.RefAttributes<HTMLDivElement>> & {
   Handle: HandleComponent;
@@ -688,7 +702,7 @@ const Panel = React.forwardRef<HTMLDivElement, PanelPublicProps>((props, ref) =>
     onSizeChange,
     sizeUpdate,
     sizeUpdateMs = 50,
-    inset,
+    flush = true,
     id,
     ...domProps
   } = props;
@@ -713,7 +727,7 @@ const Panel = React.forwardRef<HTMLDivElement, PanelPublicProps>((props, ref) =>
     onCollapse,
     size: expandedSize,
   });
-  useInsetRegistration('panel', inset);
+  useFrameRegistration('panel', flush);
 
   React.useEffect(() => {
     if (snapPoints !== undefined || collapseThreshold !== undefined || paneId !== undefined || persistence !== undefined) {
@@ -774,7 +788,7 @@ const Panel = React.forwardRef<HTMLDivElement, PanelPublicProps>((props, ref) =>
       ref={composedRef}
       className={classNames('kui-ShellPane', 'kui-ShellPanel', className)}
       {...paneAttributes(pane, presentationAttributes)}
-      data-inset={inset || undefined}
+      data-flush={flush || undefined}
       tabIndex={pane.overlaying ? -1 : domProps.tabIndex}
       style={
         {
@@ -799,18 +813,22 @@ Panel.Handle = PanelHandle;
 /* ── Content ───────────────────────────────────────────────────────────────── */
 
 interface ShellContentProps extends React.ComponentPropsWithoutRef<'main'> {
-  /** When true, adds margin and triggers the gray backdrop on the Shell. */
-  inset?: boolean;
+  /**
+   * Sets whether the work area joins the app frame. The default is `true`. Set `flush={false}`
+   * to make it a card on the Shell's background; the panes beside it then sit on that background
+   * too, and draw no hairline toward it.
+   */
+  flush?: boolean;
 }
 
 /**
  * The work area. It scrolls as it is; with a `Shell.Scroll` child it becomes a column and the
  * Scroll scrolls instead, so a `Shell.PaneHeader float` beside it stays pinned over the page.
  */
-const Content = React.forwardRef<HTMLElement, ShellContentProps>(({ className, inset, children, ...props }, ref) => {
-  useInsetRegistration('content', inset);
+const Content = React.forwardRef<HTMLElement, ShellContentProps>(({ className, flush = true, children, ...props }, ref) => {
+  useFrameRegistration('content', flush);
   return (
-    <main {...props} ref={ref} className={classNames('kui-ShellContent', className)} data-inset={inset || undefined}>
+    <main {...props} ref={ref} className={classNames('kui-ShellContent', className)} data-flush={flush || undefined}>
       {/* Each pane holds its own page store, so a band's title can mirror the page beside it. */}
       <ShellContentContext.Provider value={true}>
         <PageScope>{children}</PageScope>

package/src/styles/tokens/color.css

@@ -8,6 +8,8 @@
   --color-page: white;
   --color-overlay: var(--black-a6);
   --color-surface: white;
+  /* A rule between two regions, such as the hairline between two flush Shell panes. The same role and value as v2's. */
+  --color-border: var(--neutral-6, var(--gray-6));
   /* A background for an app page that holds raised surfaces. No component reads it. */
   --color-ground: var(--neutral-1, var(--gray-1));