@juwel-development/design-system 4.2.0 → 4.3.0

package/src/Arrangement/ColumnLayout/ColumnLayout.tsx

@@ -49,7 +49,19 @@ const columnLayoutFrame = cva(
 // Chrome's layout grain, into a full switch; `0px` and `100%` are the two states, not measurements.
 const columnLayoutColumn = cva(
   'min-w-0 grow-[calc(var(--column-layout-weight)/var(--column-layout-growth-unit))] basis-[clamp(0px,(var(--column-layout-threshold)-100%)*1000000,100%)] max-w-[var(--column-layout-maximum)]',
+  {
+    variants: {
+      // The head keeps its content height and the next row takes what is left of a filled
+      // column's height; in a content-height column both rows keep their content height.
+      hasHead: {
+        true: 'grid grid-cols-[minmax(0,1fr)] grid-rows-[auto_minmax(0,1fr)] gap-[var(--column-layout-gap)]',
+        false: '',
+      },
+    },
+    defaultVariants: { hasHead: false },
+  },
 );
+const columnLayoutColumnHead = cva('min-w-0');
 
 // The selecting holder is the box the alternatives are measured against; it takes no space of
 // its own. The probes sit out of flow and clipped, so a shortfall never becomes overflow.
@@ -173,7 +185,13 @@ export interface IColumnLayoutColumnProps {
    * The theme must supply a nonnegative CSS length at least as large as minWidth; resolved
    * lengths are not read or validated by the component. */
   maxWidth?: WidthToken;
-  /** The column's content. Rendered unmodified: the column imposes no anatomy. */
+  /** Optional consumer content at content height above the column's content, spanning this
+   *  column only. In a filled column the content below it takes the remaining height. Omitted,
+   *  `undefined`, `null` or `false`, the column renders exactly as without it. */
+  head?: ReactNode;
+  /** The column's content, rendered unmodified. With a `head`, supply one element: one that
+   *  accepts the remaining height (a Pane, `Alternatives fill`, `Root fill`, `Tabs.Root fill`)
+   *  or content-height content. */
   children?: ReactNode;
   testId?: string;
 }
@@ -224,21 +242,31 @@ const ColumnLayoutRoot: FunctionComponent<IColumnLayoutRootProps> = ({
           '--column-layout-threshold': thresholdOf(tracks),
           '--column-layout-growth-unit': growthUnitOf(tracks),
         };
+  // `data-height-passing` tells Screen's fit check to look through a box to its children: it
+  // stretches to its allocation, so only what it holds has a height of its own (#159).
   const row = (
     <div
       className={columnLayout({ gap, fill })}
       style={style}
+      data-height-passing={fill || undefined}
       data-testid={testId}
     >
       {markColumns(children)}
     </div>
   );
-  return fill ? <div className={columnLayoutFrame()}>{row}</div> : row;
+  return fill ? (
+    <div className={columnLayoutFrame()} data-height-passing>
+      {row}
+    </div>
+  ) : (
+    row
+  );
 };
 
 const ColumnLayoutColumn: FunctionComponent<IColumnLayoutColumnProps> = ({
   weight,
   maxWidth,
+  head,
   children,
   testId,
 }) => {
@@ -253,9 +281,18 @@ const ColumnLayoutColumn: FunctionComponent<IColumnLayoutColumnProps> = ({
         ? 'none'
         : `max(var(${maxWidth}), clamp(0px, (var(--column-layout-threshold) - 100%) * 1000000, 100%))`,
   };
+  const hasHead = head !== undefined && head !== null && head !== false;
+  // The head takes a slot of its own ahead of the content, so its arrival or departure never
+  // moves the content's position among the column's children and never remounts it.
   return (
-    <div className={columnLayoutColumn()} style={style} data-testid={testId}>
+    <div
+      className={columnLayoutColumn({ hasHead })}
+      style={style}
+      data-height-passing
+      data-testid={testId}
+    >
       <ColumnLayoutMembership.Provider value={false}>
+        {hasHead && <div className={columnLayoutColumnHead()}>{head}</div>}
         {children}
       </ColumnLayoutMembership.Provider>
     </div>
@@ -480,7 +517,11 @@ const ColumnLayoutAlternatives: FunctionComponent<
       ? `${reserve}px`
       : '0px';
   return (
-    <div className={columnLayoutAlternatives({ fill })} data-testid={testId}>
+    <div
+      className={columnLayoutAlternatives({ fill })}
+      data-height-passing={fill || undefined}
+      data-testid={testId}
+    >
       <div ref={probes} aria-hidden="true" className={columnLayoutFitProbes()}>
         {declarations.map(({ arrangement, threshold }, index) => (
           <div
@@ -516,6 +557,11 @@ const ColumnLayoutAlternatives: FunctionComponent<
  * - With `fill`, Root accepts its parent's allocated height and every horizontal column takes
  *   that height, bounding a filling Pane, Table or ScrollContainer. An internal inline-size
  *   frame supplies the width query; columns remain direct children of the row.
+ * - A Column's optional `head` renders first inside that column, at content height, separated
+ *   from the content by the Root's gap role and spanning that column only. In a filled
+ *   horizontal column the content takes the height left below it; otherwise both keep their
+ *   content height. The head adds no role, name, tab stop or scrolling, and its arrival,
+ *   change or removal never remounts the content.
  * - In an unsized parent, `fill` invents no bound: columns retain content height. When stacked,
  *   columns return to content height and the holder owns scrolling. No column scrolls itself.
  * - The row holds only while every proportional share is at least its own minimum. The moment one
@@ -586,7 +632,11 @@ const ColumnLayoutAlternatives: FunctionComponent<
  *   maximum below minimum has no guaranteed runtime exception. A valid maximum below the
  *   original share at the threshold applies immediately, with its surplus redistributed.
  * - With `fill`, the holder supplies a definite height to bound content and owns overflow for
- *   the stacked fallback. Filling children own their overflow; fixed content must fit the bound.
+ *   the stacked fallback. Filling children own their overflow; fixed content must fit the bound,
+ *   or - inside Screen - releases the whole content into the enclosing scroll owner.
+ * - Under a `head`, supply one child that accepts the remaining height (a Pane, `Root fill`,
+ *   `Alternatives fill`, `Tabs.Root fill`) or content-height content. The head is the
+ *   consumer's: its wording, controls and any heading level are not supplied by the column.
  * - The holder gives the Root a definite width, as any block does. Inside a shrink-to-fit frame
  *   there is no width to measure the shares against.
  * - Content that cannot wrap - an unbroken string, a fixed-width control - needs its own overflow

package/src/Display/Table/Table.tsx

@@ -89,9 +89,11 @@ const table = cva(
         highlight:
           '[&>table>*>tr[aria-selected=true]]:bg-selected-surface [&>table>*>tr[aria-selected=true]]:[--color-error:var(--color-selected-error)]',
       },
+      // A hidden caption is positioned against the table's own box, so it scrolls and clips with the
+      // table instead of extending the document below an enclosing scroll owner (#159).
       captionVisibility: {
         visible: '[&>table>caption]:pb-3',
-        hidden: '[&>table>caption]:sr-only',
+        hidden: 'relative [&>table>caption]:sr-only',
       },
       // Density publishes the two cell insets the cells read, so head and body move together and the
       // theme's comfortable or compact pair is the only source (docs/adr/0008, Amendments, #115).
@@ -341,7 +343,10 @@ const useOverflow = (
           Number.parseFloat(getComputedStyle(element).paddingTop) || 0;
         element.style.scrollPaddingTop = `${headerHeight + 2 * ringRoom}px`;
       }
+      // Only bounded tables participate in Dialog release. Reading an absent inherited custom
+      // property is depth-dependent in jsdom 29.1.1, even for ordinary content tables (#157).
       const isReleased =
+        bounded &&
         getComputedStyle(element)
           .getPropertyValue('--_scroll-released')
           .trim() === '1';
@@ -508,6 +513,7 @@ const TableRoot: FunctionComponent<ITableRootProps> = ({
       })}
       style={style}
       data-bounded={bounded || undefined}
+      data-height-bounded={bounded || undefined}
       data-notes={notes}
       data-columns={columnCount}
       data-icon-actions={
@@ -641,6 +647,7 @@ const TableCell: FunctionComponent<ITableCellProps> = ({
  * - `Root` renders its required `caption` as the table's first child, so every table is named.
  *   `captionVisibility` defaults to `visible`; `hidden` visually clips the caption out of flow,
  *   including its spacing, while preserving its native accessible name and the scroll wrapper's name.
+ *   The clipped caption stays inside the table's box, so it never extends an enclosing scrollport.
  *   Hide it only when visible text directly above the table already names what it lists; the
  *   enclosing arrangement owns the gap above the table. The consumer still supplies the caption.
  * - The block reads as a table from two rule weights alone: the heavier `rule` above the first row,

package/src/Interaction/Slider/Slider.tsx

@@ -47,12 +47,22 @@ export interface ISliderProps {
   onInput$: Subject<number>;
   /**
    * Always rendered as a visible label associated with the control, the way `Input`'s is (#112);
-   * it doubles as the accessible name.
+   * it is the accessible name, and stays exactly that while a `visibleValue` is shown.
    */
   label: string;
+  /**
+   * The current value shown beside the label, in the consumer's wording ("$3,542", "34 %"). The
+   * consumer formats it and passes new wording with each new `value`; Slider generates none. It
+   * shares the label's row when both fit and wraps below it when they do not. It never joins the
+   * accessible name and is not announced a second time: assistive technology hears it through
+   * `aria-valuetext`, which carries this wording whenever `valueText` is left out. Left out, only
+   * the label is shown.
+   */
+  visibleValue?: string;
   /**
    * How the value is announced, in the consumer's wording ("$60 a week"). Left out, assistive
-   * technology reads the bare number: the library ships no wording of its own.
+   * technology reads `visibleValue`, or the bare number without one: the library ships no
+   * wording of its own.
    */
   valueText?: string;
   /** The explicit non-operable state: native disabled conduct, no emissions, disabled paint. */
@@ -88,11 +98,11 @@ const assertOperatingRange = (
 /**
  * A control that sets one numeric value by moving one thumb along a fixed, visible operating
  * range. Controlled: the consumer holds the value and passes it back in, and a value it does not
- * pass back is never adopted. It renders the value nowhere - the consumer sets any figures beside
- * it with typography - and it fills its container's width the way `Input` does. Its label follows
- * `Input` too: visible, associated, and the only text the component renders (#112). It is still
- * a live control and not a form field, so none of Input's annotations - hint, error, optional
- * marker - come with it. `disabled` is the explicit non-operable state.
+ * pass back is never adopted. It fills its container's width the way `Input` does. Its label
+ * follows `Input` too: visible, associated, and the stable accessible name (#112). The only other
+ * text it renders is an optional `visibleValue` in the consumer's wording, beside the label (#160).
+ * It is still a live control and not a form field, so none of Input's annotations - hint, error,
+ * optional marker - come with it. `disabled` is the explicit non-operable state.
  *
  * An off-range value renders at the nearest bound through the native control. The consumer still
  * owns the value: the clamped position is not emitted on `onInput$` until the user moves the thumb.
@@ -104,22 +114,47 @@ export const Slider: FunctionComponent<ISliderProps> = ({
   value,
   onInput$,
   label,
+  visibleValue,
   valueText,
   disabled,
   testId,
 }) => {
   const controlId = `${useId()}-control`;
   assertOperatingRange({ min, max, step, value });
+  // The label declares its face and size on itself, never on the wrapper, which would hand them
+  // to the control too; `body` is the control's own role (docs/adr/0004, #90, #92).
+  const visibleLabel = (
+    <label
+      htmlFor={controlId}
+      className={'font-secondary font-medium text-body text-foreground'}
+    >
+      {label}
+    </label>
+  );
   return (
     <div className={'flex flex-col gap-[var(--space-stack)]'}>
-      {/* The label declares its face and size on itself, never on the wrapper, which would hand
-          them to the control too; `body` is the control's own role (docs/adr/0004, #90, #92). */}
-      <label
-        htmlFor={controlId}
-        className={'font-secondary font-medium text-body text-foreground'}
-      >
-        {label}
-      </label>
+      {visibleValue === undefined ? (
+        visibleLabel
+      ) : (
+        // The label's face, role and leading, so a shared line keeps the label-only height even
+        // under a consumer face. aria-hidden because the range already announces the value;
+        // wrap-anywhere lets overlong wording break instead of widening the holder.
+        <div
+          className={
+            'flex flex-wrap items-baseline justify-between gap-x-[var(--space-stack)]'
+          }
+        >
+          {visibleLabel}
+          <span
+            aria-hidden={true}
+            className={
+              'min-w-0 wrap-anywhere font-secondary text-body text-foreground'
+            }
+          >
+            {visibleValue}
+          </span>
+        </div>
+      )}
       <input
         id={controlId}
         type={'range'}
@@ -129,7 +164,7 @@ export const Slider: FunctionComponent<ISliderProps> = ({
         step={step}
         value={value}
         disabled={disabled}
-        aria-valuetext={valueText}
+        aria-valuetext={valueText ?? visibleValue}
         data-testid={testId}
         // React's onChange rides the native input event, so every movement emits through here.
         onChange={(event) => onInput$.next(event.currentTarget.valueAsNumber)}

package/src/Interaction/Stepper/Stepper.tsx

@@ -154,7 +154,7 @@ const StepperRoot: FunctionComponent<IStepperRootProps> = ({
   }, [active$]);
   return (
     <StepperContext.Provider value={{ active, onSelect$, label, baseId }}>
-      <div className={stepperRoot()} data-testid={testId}>
+      <div className={stepperRoot()} data-height-passing data-testid={testId}>
         {children}
       </div>
     </StepperContext.Provider>
@@ -272,6 +272,7 @@ const StepperPanel: FunctionComponent<IStepperPanelProps> = ({
       hidden={!isActive}
       tabIndex={isActive ? 0 : undefined}
       className={stepperPanel()}
+      data-height-passing
       data-testid={testId}
     >
       {isActive ? children : undefined}

package/src/Interaction/Tabs/Tabs.tsx

@@ -167,7 +167,11 @@ const TabsRoot: FunctionComponent<ITabsRootProps> = ({
     <TabsContext.Provider
       value={{ active, onSelect$, label, baseId, fill: fill === true }}
     >
-      <div className={tabsRoot({ fill })} data-testid={testId}>
+      <div
+        className={tabsRoot({ fill })}
+        data-height-passing={fill || undefined}
+        data-testid={testId}
+      >
         {children}
       </div>
     </TabsContext.Provider>
@@ -253,6 +257,7 @@ const TabsPanel: FunctionComponent<ITabsPanelProps> = ({
       hidden={!isActive}
       tabIndex={isActive ? 0 : undefined}
       className={tabsPanel({ fill })}
+      data-height-passing={fill || undefined}
       data-testid={testId}
     >
       {isActive ? children : undefined}

package/src/Layout/Pane/Pane.tsx

@@ -9,9 +9,12 @@ import {
   useState,
 } from 'react';
 
-const pane = cva(
+// A Pane inside a compact Screen follows it; a Dialog's Pane is not one of its work areas (#158).
+const pane = cva([
   'box-border flex h-full min-h-0 min-w-0 flex-col gap-[var(--space-stack)] border border-solid border-border bg-surface text-foreground p-[var(--space-box-inset)] [overflow-wrap:anywhere]',
-);
+  '[[data-screen-spacing=compact]_&:not(dialog_*)]:gap-[var(--space-pane-slot-compact)]',
+  '[[data-screen-spacing=compact]_&:not(dialog_*)]:p-[max(var(--space-pane-inset-compact),calc(var(--focus-ring-width)+var(--focus-ring-offset)))]',
+]);
 const paneSection = cva('min-w-0 shrink-0');
 const paneBody = cva('min-h-0 min-w-0 flex-[0_1_auto]', {
   variants: {
@@ -164,21 +167,36 @@ const useScreenFallback = (root: {
       typeof ResizeObserver === 'undefined'
         ? undefined
         : new ResizeObserver(measure);
+    const mutations = new MutationObserver(() => observe());
+    const content = { childList: true, subtree: true, characterData: true };
+    // Content above the pane - a column head, a tab row - moves it without resizing it, so each
+    // box ahead of it up to the remainder is watched, attributes included (#159).
     const observe = () => {
       observer?.disconnect();
+      mutations.disconnect();
       observer?.observe(frame);
       observer?.observe(element);
       for (const child of element.querySelectorAll('*'))
         observer?.observe(child);
+      mutations.observe(element, content);
+      for (
+        let node: Element = element;
+        node !== frame && node.parentElement;
+        node = node.parentElement
+      ) {
+        mutations.observe(node.parentElement, { childList: true });
+        for (
+          let before = node.previousElementSibling;
+          before;
+          before = before.previousElementSibling
+        ) {
+          observer?.observe(before);
+          mutations.observe(before, { ...content, attributes: true });
+        }
+      }
       measure();
     };
     observe();
-    const mutations = new MutationObserver(observe);
-    mutations.observe(element, {
-      childList: true,
-      subtree: true,
-      characterData: true,
-    });
     window.addEventListener('resize', measure);
     return () => {
       observer?.disconnect();
@@ -201,6 +219,7 @@ const Root: FunctionComponent<IPaneRootProps> = ({
     <div
       ref={root}
       data-screen-unusable={isUnusable || undefined}
+      data-height-bounded
       className={pane()}
       role={name ? 'group' : undefined}
       aria-label={name || undefined}
@@ -257,6 +276,8 @@ const Body: FunctionComponent<IPaneBodyProps> = ({
  *   stretch: Foot follows it, with any unused height left in Root rather than inside Body.
  * - Root paints surface, foreground, border and box inset, square and without elevation.
  *   The stack space role separates slots; a non-empty name exposes a group, never a landmark.
+ *   Inside a Screen with spacing="compact", outside a Dialog, the inset and slot gaps follow
+ *   that Screen's compact treatment instead; Pane offers no selector of its own.
  * - Default Body is the sole scroll region: a named group and keyboard stop only while
  *   overflowing, retained while focused. It reserves the shared focus ring's room and leaves
  *   native focus reveal, scrolling and child keyboard interactions intact.
@@ -274,9 +295,11 @@ const Body: FunctionComponent<IPaneBodyProps> = ({
  *   own overflow and focus ring. Intermediate wrappers must preserve that allocation.
  * - Inside Screen, fixed regions and the usable body minimum participate in whole-content
  *   fallback and restoration, measured against what Screen's remainder leaves below anything
- *   above the pane - a filling Tabs row. Dialog owns the corresponding whole-task fallback for
- *   a Pane with child-owned Body and bounded Table. Other parents own their fallback policy.
- * - Filled ColumnLayout columns and active Stepper panels can pass the bound to Root. Keep
- *   those holders and Pane directly composed so no intermediate wrapper loses the allocation.
+ *   above the pane - a filling Tabs row or a column head - and again whenever that changes.
+ *   Dialog owns the corresponding whole-task fallback for a Pane with child-owned Body and
+ *   bounded Table. Other parents own their fallback policy.
+ * - Filled ColumnLayout columns, with or without a head, and active Stepper panels can pass
+ *   the bound to Root. Keep those holders and Pane directly composed so no intermediate
+ *   wrapper loses the allocation. An unsized Pane inside a content-height Stack grows with it.
  */
 export const Pane = { Root, Head, Body, Foot } as const;

package/src/Layout/Screen/Screen.tsx

@@ -1,18 +1,108 @@
-import { cva } from 'class-variance-authority';
-import { type FunctionComponent, type ReactNode, useState } from 'react';
+import { cva, type VariantProps } from 'class-variance-authority';
+import {
+  type FunctionComponent,
+  type ReactNode,
+  useLayoutEffect,
+  useState,
+} from 'react';
 import { ScreenBodyAllocation } from './ScreenBodyAllocation';
 
+// Compact marks the main for its Panes, which read the marker through CSS (architecture
+// standard, Two rules). Its floor keeps a focus ring at the content's edge inside the scrollport.
 const screen = cva(
-  'box-border grid h-full min-h-0 min-w-0 grid-rows-[minmax(0,1fr)] px-[var(--gutter)] py-[var(--space-region)] [&:has(>header)]:grid-rows-[auto_minmax(0,1fr)] [&:has(>header)]:gap-[var(--space-region)]',
+  'box-border grid h-full min-h-0 min-w-0 grid-rows-[minmax(0,1fr)] px-[var(--gutter)] [&:has(>header)]:grid-rows-[auto_minmax(0,1fr)]',
+  {
+    variants: {
+      spacing: {
+        comfortable:
+          'py-[var(--space-region)] [&:has(>header)]:gap-[var(--space-region)]',
+        compact:
+          'py-[max(var(--space-screen-region-compact),calc(var(--focus-ring-width)+var(--focus-ring-offset)))] [&:has(>header)]:gap-[max(var(--space-screen-region-compact),calc(var(--focus-ring-width)+var(--focus-ring-offset)))]',
+      },
+    },
+    defaultVariants: { spacing: 'comfortable' },
+  },
 );
 const screenHeading = cva('min-w-0');
 const screenBody = cva(
   'h-full min-h-0 min-w-0 [&>div]:h-full [&:has([data-screen-unusable])>div]:h-auto',
 );
-export interface IScreenProps {
+type Extent = { bottom: number; observed: readonly Element[] };
+
+const isOutOfFlow = (computed: CSSStyleDeclaration): boolean =>
+  computed.display === 'none' ||
+  computed.position === 'absolute' ||
+  computed.position === 'fixed';
+
+// Height-passing boxes (filled columns, Tabs, Stepper) stretch to the allocation in one mode and
+// shrink to their content in the other, so they are looked through; self-bounded boxes (Pane, a
+// bounded Table or ScrollContainer) answer for their own room. What remains keeps its content
+// height in both modes, so its lowest edge decides fallback and restoration alike (#159).
+const extentOf = (holder: Element): Extent =>
+  Array.from(holder.children).reduce<Extent>(
+    (extent, child) => {
+      const computed = getComputedStyle(child);
+      const observed = [...extent.observed, child];
+      if (isOutOfFlow(computed) || child.hasAttribute('data-height-bounded')) {
+        return { bottom: extent.bottom, observed };
+      }
+      if (child.hasAttribute('data-height-passing')) {
+        const inner = extentOf(child);
+        return {
+          bottom: Math.max(extent.bottom, inner.bottom),
+          observed: [...observed, ...inner.observed],
+        };
+      }
+      const bottom =
+        child.getBoundingClientRect().bottom +
+        (Number.parseFloat(computed.marginBottom) || 0);
+      return { bottom: Math.max(extent.bottom, bottom), observed };
+    },
+    { bottom: Number.NEGATIVE_INFINITY, observed: [] },
+  );
+
+const useContentOverflow = (allocation: HTMLDivElement | null): boolean => {
+  const [isOverflowing, setIsOverflowing] = useState(false);
+  useLayoutEffect(() => {
+    const content = allocation?.firstElementChild;
+    if (!allocation || !content) return;
+    const measure = () =>
+      setIsOverflowing(
+        extentOf(content).bottom > allocation.getBoundingClientRect().bottom,
+      );
+    const observer =
+      typeof ResizeObserver === 'undefined'
+        ? undefined
+        : new ResizeObserver(measure);
+    // Observing a box reports it once, so the boxes are collected again only when content changes.
+    const observe = () => {
+      observer?.disconnect();
+      observer?.observe(allocation);
+      for (const box of extentOf(content).observed) observer?.observe(box);
+      measure();
+    };
+    observe();
+    const mutations = new MutationObserver(observe);
+    mutations.observe(content, {
+      childList: true,
+      subtree: true,
+      characterData: true,
+    });
+    window.addEventListener('resize', measure);
+    return () => {
+      observer?.disconnect();
+      mutations.disconnect();
+      window.removeEventListener('resize', measure);
+    };
+  }, [allocation]);
+  return isOverflowing;
+};
+
+export interface IScreenProps extends VariantProps<typeof screen> {
   /** Consumer-owned visible heading; omit when the heading belongs inside a Pane. */
   heading?: ReactNode;
-  /** Height-passing content, normally a filling ColumnLayout with direct Panes. */
+  /** A filling ColumnLayout, a Pane or `Tabs.Root fill`, or content-height content such as a
+   *  Stack or an unbounded Table. See the supported compositions below. */
   children: ReactNode;
   testId?: string;
 }
@@ -21,36 +111,56 @@ export interface IScreenProps {
  *
  * @Guarantees
  * - Uses the page gutter horizontally and region spacing vertically and beneath a present heading.
+ * - spacing="compact" selects the compact console treatment: its own vertical air and heading gap,
+ *   and the inset and slot gaps of every Pane inside it outside a Dialog, read from the
+ *   --space-screen-region-compact, --space-pane-inset-compact and --space-pane-slot-compact tokens.
+ *   Gutter, type, controls, focus rings and descendant spacing stay; Pane has no selector of its own.
+ *   Omitted or "comfortable" renders as before; switching never remounts content.
  * - Omitted, undefined, null and false headings reserve no wrapper, track or gap. Arbitrary
  *   components are not inspected for emptiness. Changing the slot never remounts content.
- * - Adds no scrollport or tab stop. Pane bodies scroll independently while fixed regions plus a
- *   complete text line or ordinary row/control and focus room fit. Otherwise all content grows
- *   into the enclosing scroll owner. Bounds restore without probing or remounting children.
+ * - Adds no scrollport or tab stop, and gives no content-height region one. Bounded bodies
+ *   scroll independently while all fixed content fits: Pane heads and feet, a column head,
+ *   content-height columns and sole content, plus each bounded body's complete text line or
+ *   ordinary row/control with focus room. Long bounded-body content is never fixed content.
+ * - Otherwise all content, the heading included, grows into the enclosing scroll owner and stays
+ *   reachable there. Bounds restore when room returns, without probing, clipping or remounting
+ *   children; mounted controls keep focus and selection in both directions.
  * - Unsized parents use natural height; ColumnLayout retains its container-fit stacking rule.
  *
  * @CallerMustEnsure
  * - Supply the visible heading here or inside a panel, and exactly one main for the page.
  * - Use Shell's console body, optionally Sidebar.Root fill / Sidebar.Content, to allocate height
  *   and own fallback scrolling. Every intermediate wrapper must pass that allocation through.
- * - Compose filling ColumnLayout with direct Pane children; retain Pane's Head/Body/Foot order.
- *   Body can delegate to one bounded Table. A filling Tabs row above a Pane counts against that
- *   Pane's room; other height-consuming wrappers need their own allocation contract.
+ * - Compose one of these as content; retain Pane's Head/Body/Foot order and never nest Panes.
+ *   1. Filling ColumnLayout whose columns hold a Pane, `Tabs.Root fill` or `Alternatives fill`
+ *      directly, optionally under a `Column head`; Body can delegate to one bounded Table.
+ *   2. A column holding a content-height Stack - a Box and an unsized summary Pane, say.
+ *   3. A content-height Stack or unbounded Table as the sole content, with or without heading.
+ *   4. Content-height Stacks in one or more filled columns, beside Panes or each other.
+ * - A filling Tabs row or a column head above a Pane counts against that Pane's room. Other
+ *   height-passing wrappers, such as a Stack meant to bound a Pane, are outside the contract.
  * - Keep the Shell bar short enough to leave a usable enclosing scrollport. This is representative
  *   panel fit, not a guarantee that arbitrary content fits any particular viewport.
  */
 export const Screen: FunctionComponent<IScreenProps> = ({
   heading,
+  spacing,
   children,
   testId,
 }) => {
   const [allocation, setAllocation] = useState<HTMLDivElement | null>(null);
+  const isOverflowing = useContentOverflow(allocation);
   return (
-    <main className={screen()} data-testid={testId}>
+    <main
+      className={screen({ spacing })}
+      data-screen-spacing={spacing === 'compact' ? spacing : undefined}
+      data-testid={testId}
+    >
       {heading !== undefined && heading !== null && heading !== false && (
         <header className={screenHeading()}>{heading}</header>
       )}
       <div ref={setAllocation} className={screenBody()}>
-        <div>
+        <div data-screen-unusable={isOverflowing || undefined}>
           <ScreenBodyAllocation.Provider value={allocation}>
             {children}
           </ScreenBodyAllocation.Provider>

package/src/Layout/ScrollContainer/ScrollContainer.tsx

@@ -136,6 +136,7 @@ export const ScrollContainer: FunctionComponent<IScrollContainerProps> = ({
     <div
       ref={container}
       className={scrollContainer({ axis })}
+      data-height-bounded
       data-testid={testId}
       role={isScrollable ? 'group' : undefined}
       aria-label={isScrollable ? ariaLabel : undefined}

package/src/Theme/renderTokens.ts

@@ -254,6 +254,16 @@ const BOX_INSET = `:root {
   --space-box-inset: 1em;
 }`;
 
+/* Screen's compact console treatment (#158, ADR 0008): one value per enclosure position, so a
+   theme tunes it without retuning the generic region, box-inset and stack roles descendants read.
+   In em like those roles. Constraint: nonnegative; Screen and Pane floor them at the focus ring's
+   room. */
+const CONSOLE_SPACING = `:root {
+  --space-screen-region-compact: 0.5em;
+  --space-pane-inset-compact: 0.5em;
+  --space-pane-slot-compact: 0.25em;
+}`;
+
 /* Table cell insets (#115): one inline/block pair per density, in :root so a brand tunes both
    treatments without Table gaining a measurement prop. comfortable is exactly what px-4 / py-2
    resolved to, so the default moves nothing; compact halves both. In rem: cell type is fixed at the
@@ -478,6 +488,9 @@ ${COLUMN_LAYOUT_FIT}
 /* Box's inner padding, measured against inherited type, beside Collection's. */
 ${BOX_INSET}
 
+/* Screen's compact console positions, beside the roles they stand in for. */
+${CONSOLE_SPACING}
+
 /* Callout marks an edge without enclosing or arranging its content. */
 ${CALLOUT_MARK}
 

package/src/tokens.css

@@ -293,6 +293,13 @@
   --space-box-inset: 1em;
 }
 
+/* Screen's compact console positions, beside the roles they stand in for. */
+:root {
+  --space-screen-region-compact: 0.5em;
+  --space-pane-inset-compact: 0.5em;
+  --space-pane-slot-compact: 0.25em;
+}
+
 /* Callout marks an edge without enclosing or arranging its content. */
 :root {
   --callout-mark-width: 0.25rem;

package/src/tokens.dark.css

@@ -257,6 +257,13 @@
   --space-box-inset: 1em;
 }
 
+/* Screen's compact console positions, beside the roles they stand in for. */
+:root {
+  --space-screen-region-compact: 0.5em;
+  --space-pane-inset-compact: 0.5em;
+  --space-pane-slot-compact: 0.25em;
+}
+
 /* Callout marks an edge without enclosing or arranging its content. */
 :root {
   --callout-mark-width: 0.25rem;