@lotics/ui 44.14.0 → 45.2.0

package/src/popover.tsx

@@ -23,6 +23,7 @@ import {
 } from "./popover_layers";
 import { PopoverNavContext, type PopoverNavContextValue } from "./popover_nav";
 import { useLoticsLocale } from "./locale";
+import { HeadingAltitudeContext } from "./heading_altitude";
 
 export type PopoverSide = "top" | "right" | "bottom" | "left";
 export type PopoverAlign = "start" | "center" | "end";
@@ -607,155 +608,163 @@ export function PopoverContent(props: PopoverContentProps) {
   const contentZIndex = baseZIndex + nestingLevel * 2 + 1;
 
   return (
-    <Portal>
-      {/* Modal scrim — ONLY for the bottom-sheet (`small`) mode, which IS modal.
-          The anchored popover is NON-MODAL: no overlay, so the rest of the page
-          stays interactive; outside-dismiss is the click listener above. */}
-      {small && (
+    // A popover is dialog-scale — a few hundred px with its own chrome — so a
+    // heading inside it takes the ramp's `####` rung, exactly as one inside a
+    // dialog does. The provider covers ALL THREE BANDS, not just the scroller:
+    // `PopoverHeader` is a slot the CALLER composes (unlike a Drawer's title,
+    // which is chrome the container renders), and the identity line of a peek
+    // lives there. See `heading_altitude.ts`.
+    <HeadingAltitudeContext.Provider value="panel">
+      <Portal>
+        {/* Modal scrim — ONLY for the bottom-sheet (`small`) mode, which IS modal.
+            The anchored popover is NON-MODAL: no overlay, so the rest of the page
+            stays interactive; outside-dismiss is the click listener above. */}
+        {small && (
+          <div
+            style={{
+              position: "fixed",
+              top: 0,
+              left: 0,
+              right: 0,
+              bottom: 0,
+              backgroundColor: "rgba(0, 0, 0, 0.5)",
+              opacity: isBottomSheetShown ? 1 : 0,
+              transition: "opacity 0.3s ease",
+              zIndex: overlayZIndex,
+              pointerEvents: "auto",
+            }}
+            onClick={handleOverlayClick}
+            onMouseDown={(e) => e.stopPropagation()}
+          />
+        )}
+        {/* Popover */}
         <div
+          ref={popoverRef}
+          data-popover="true"
+          data-popover-level={nestingLevel}
+          data-testid={testID}
+          role="dialog"
+          aria-modal={small ? true : undefined}
+          tabIndex={small ? undefined : -1}
           style={{
             position: "fixed",
-            top: 0,
-            left: 0,
-            right: 0,
-            bottom: 0,
-            backgroundColor: "rgba(0, 0, 0, 0.5)",
-            opacity: isBottomSheetShown ? 1 : 0,
-            transition: "opacity 0.3s ease",
-            zIndex: overlayZIndex,
-            pointerEvents: "auto",
-          }}
-          onClick={handleOverlayClick}
-          onMouseDown={(e) => e.stopPropagation()}
-        />
-      )}
-      {/* Popover */}
-      <div
-        ref={popoverRef}
-        data-popover="true"
-        data-popover-level={nestingLevel}
-        data-testid={testID}
-        role="dialog"
-        aria-modal={small ? true : undefined}
-        tabIndex={small ? undefined : -1}
-        style={{
-          position: "fixed",
-          padding: PANEL_INSET,
-          borderTopLeftRadius: 16,
-          borderTopRightRadius: 16,
-          borderBottomLeftRadius: small ? 0 : 16,
-          borderBottomRightRadius: small ? 0 : 16,
-          backgroundColor: colors.background,
-          boxShadow: colors.shadow,
-          boxSizing: "border-box",
-          zIndex: contentZIndex,
-          transition: small ? "transform 0.3s ease" : undefined,
-          ...(small
-            ? {
-                bottom: 0,
-                left: 0,
-                right: 0,
-                maxHeight: "90vh",
-                display: "flex",
-                flexDirection: "column",
-                paddingBottom: 32,
-                transform: isBottomSheetShown ? "translateY(0)" : "translateY(100%)",
-              }
-            : position
+            padding: PANEL_INSET,
+            borderTopLeftRadius: 16,
+            borderTopRightRadius: 16,
+            borderBottomLeftRadius: small ? 0 : 16,
+            borderBottomRightRadius: small ? 0 : 16,
+            backgroundColor: colors.background,
+            boxShadow: colors.shadow,
+            boxSizing: "border-box",
+            zIndex: contentZIndex,
+            transition: small ? "transform 0.3s ease" : undefined,
+            ...(small
               ? {
-                  top: position.top,
-                  left: position.left,
-                  width: "max-content",
-                  maxWidth: 800,
-                  maxHeight: "80vh",
+                  bottom: 0,
+                  left: 0,
+                  right: 0,
+                  maxHeight: "90vh",
                   display: "flex",
                   flexDirection: "column",
+                  paddingBottom: 32,
+                  transform: isBottomSheetShown ? "translateY(0)" : "translateY(100%)",
                 }
-              : {
-                  top: -9999,
-                  left: -9999,
-                  width: "max-content",
-                  maxWidth: 800,
-                  maxHeight: "80vh",
-                  display: "flex",
-                  flexDirection: "column",
-                }),
-          // INHERIT means inherit — the width, not just a floor under it. The
-          // flag is set only by a popover anchored to a FIELD (Select,
-          // InlineSelect, Combobox), and a field's own width is the right width
-          // for the list of values that field can hold: option text longer than
-          // the field belongs on a second line, not on a wider panel.
-          //
-          // As a floor alone this LOOKED right, because with short options
-          // max-content lands on the trigger width anyway. It broke the moment
-          // an option was a sentence: the panel grew to the `maxWidth: 800` cap
-          // and then slid sideways to stay on screen, so a 371px field opened an
-          // 800px list starting 421px to its left, outside the drawer that owns
-          // the field.
-          //
-          // Floored at MIN_CONTROL_WIDTH so a genuinely narrow trigger — a
-          // a select in a dense grid column — still opens a list
-          // wide enough to read, rather than inheriting a width nothing fits in.
-          ...(inheritTriggerWidth &&
-            !small &&
-            triggerWidth > 0 && {
-              width: Math.max(triggerWidth, MIN_CONTROL_WIDTH),
-              maxWidth: Math.max(triggerWidth, MIN_CONTROL_WIDTH),
-            }),
-          // Last, so it beats the `max-content` every branch above sets.
-          ...(width != null && !small ? { width, maxWidth: width } : null),
-        }}
-        onClick={(e) => e.stopPropagation()}
-        // React synthetic events bubble through portals via the REACT tree, so a
-        // keydown inside this popover — or inside a Modal/Alert opened from it,
-        // which is a React child even though it portals to document.body — would
-        // reach the TRIGGER's ancestors (e.g. a grid cell's Escape-cancels-edit
-        // onKeyDown) and let a lower layer act on a higher layer's keys, on
-        // keydown, before any keyup layering logic runs. Keyboard sibling of the
-        // click curtain above. Keyup deliberately keeps flowing: RN-web Modal
-        // closes on a document-level keyup listener, and this popover's own
-        // Escape handling is a document capture keyup — neither must be starved.
-        onKeyDown={(e) => e.stopPropagation()}
-      >
-        {small && (
-          <View
-            style={{
-              padding: 8,
-              flexDirection: "row",
-              justifyContent: "flex-end",
-            }}
-          >
-            <IconButton icon="x" tooltip={closeLabel} onPress={handleClose} />
-          </View>
-        )}
-        {header}
-        {disableBodyScroll ? (
-          <SizeBoundary style={style}>{bodyChildren}</SizeBoundary>
-        ) : (
-          // FULL-BLEED HORIZONTALLY, then re-inset by the same 12. The panel
-          // pads all four sides, so a scroller sitting inside that padding
-          // clips its content 12px short of the edge and parks the scrollbar
-          // there too — content slides under an invisible margin instead of
-          // under the panel's own edge. Pulling out and padding back keeps the
-          // text on the exact column the header and footer use while giving the
-          // scroll its real edges. `PopoverFooter` already does this dance for
-          // its divider; the body needed it for the same reason.
-          //
-          // Horizontal only: the vertical padding is the gap to the header and
-          // footer, which is a gap the reader wants.
-          <ScrollView
-            style={[SCROLL_BODY, style]}
-            contentContainerStyle={[SCROLL_BODY_CONTENT, contentContainerStyle]}
-          >
-            {/* A popover is a box of its own — a few hundred px — so its contents
-                size to the panel rather than to whatever region it was opened
-                from. Both body paths get it; one of them is not a boundary. */}
-            <SizeBoundary>{bodyChildren}</SizeBoundary>
-          </ScrollView>
-        )}
-        {footer}
-      </div>
-    </Portal>
+              : position
+                ? {
+                    top: position.top,
+                    left: position.left,
+                    width: "max-content",
+                    maxWidth: 800,
+                    maxHeight: "80vh",
+                    display: "flex",
+                    flexDirection: "column",
+                  }
+                : {
+                    top: -9999,
+                    left: -9999,
+                    width: "max-content",
+                    maxWidth: 800,
+                    maxHeight: "80vh",
+                    display: "flex",
+                    flexDirection: "column",
+                  }),
+            // INHERIT means inherit — the width, not just a floor under it. The
+            // flag is set only by a popover anchored to a FIELD (Select,
+            // InlineSelect, Combobox), and a field's own width is the right width
+            // for the list of values that field can hold: option text longer than
+            // the field belongs on a second line, not on a wider panel.
+            //
+            // As a floor alone this LOOKED right, because with short options
+            // max-content lands on the trigger width anyway. It broke the moment
+            // an option was a sentence: the panel grew to the `maxWidth: 800` cap
+            // and then slid sideways to stay on screen, so a 371px field opened an
+            // 800px list starting 421px to its left, outside the drawer that owns
+            // the field.
+            //
+            // Floored at MIN_CONTROL_WIDTH so a genuinely narrow trigger — a
+            // a select in a dense grid column — still opens a list
+            // wide enough to read, rather than inheriting a width nothing fits in.
+            ...(inheritTriggerWidth &&
+              !small &&
+              triggerWidth > 0 && {
+                width: Math.max(triggerWidth, MIN_CONTROL_WIDTH),
+                maxWidth: Math.max(triggerWidth, MIN_CONTROL_WIDTH),
+              }),
+            // Last, so it beats the `max-content` every branch above sets.
+            ...(width != null && !small ? { width, maxWidth: width } : null),
+          }}
+          onClick={(e) => e.stopPropagation()}
+          // React synthetic events bubble through portals via the REACT tree, so a
+          // keydown inside this popover — or inside a Modal/Alert opened from it,
+          // which is a React child even though it portals to document.body — would
+          // reach the TRIGGER's ancestors (e.g. a grid cell's Escape-cancels-edit
+          // onKeyDown) and let a lower layer act on a higher layer's keys, on
+          // keydown, before any keyup layering logic runs. Keyboard sibling of the
+          // click curtain above. Keyup deliberately keeps flowing: RN-web Modal
+          // closes on a document-level keyup listener, and this popover's own
+          // Escape handling is a document capture keyup — neither must be starved.
+          onKeyDown={(e) => e.stopPropagation()}
+        >
+          {small && (
+            <View
+              style={{
+                padding: 8,
+                flexDirection: "row",
+                justifyContent: "flex-end",
+              }}
+            >
+              <IconButton icon="x" tooltip={closeLabel} onPress={handleClose} />
+            </View>
+          )}
+          {header}
+          {disableBodyScroll ? (
+            <SizeBoundary style={style}>{bodyChildren}</SizeBoundary>
+          ) : (
+            // FULL-BLEED HORIZONTALLY, then re-inset by the same 12. The panel
+            // pads all four sides, so a scroller sitting inside that padding
+            // clips its content 12px short of the edge and parks the scrollbar
+            // there too — content slides under an invisible margin instead of
+            // under the panel's own edge. Pulling out and padding back keeps the
+            // text on the exact column the header and footer use while giving the
+            // scroll its real edges. `PopoverFooter` already does this dance for
+            // its divider; the body needed it for the same reason.
+            //
+            // Horizontal only: the vertical padding is the gap to the header and
+            // footer, which is a gap the reader wants.
+            <ScrollView
+              style={[SCROLL_BODY, style]}
+              contentContainerStyle={[SCROLL_BODY_CONTENT, contentContainerStyle]}
+            >
+              {/* A popover is a box of its own — a few hundred px — so its contents
+                  size to the panel rather than to whatever region it was opened
+                  from. Both body paths get it; one of them is not a boundary. */}
+              <SizeBoundary>{bodyChildren}</SizeBoundary>
+            </ScrollView>
+          )}
+          {footer}
+        </div>
+      </Portal>
+    </HeadingAltitudeContext.Provider>
   );
 }
 

package/src/pressable_row.tsx

@@ -8,9 +8,9 @@ export interface PressableRowProps {
   onPress: () => void;
   /** The open/selected record — paints the persistent highlight. */
   selected?: boolean;
-  /** Part of a multi-select set — paints a persistent blue tint, distinct from
-   *  `selected` (the open record). The hover / open / press wash overrides it, so
-   *  it's the resting state of a ticked row in a bulk-select register. */
+  /** Part of a multi-select set — paints the same resting ground `selected` does.
+   *  What tells a ticked row from an open one is the ticked checkbox, which is
+   *  unmissable; the press wash still overrides both. */
   marked?: boolean;
   /**
    * - "register" (THE record-list default): a rounded row whose hover/open/`marked`
@@ -89,18 +89,27 @@ export function PressableRow(props: PressableRowProps) {
           // FOUR states, and they must not collide. Selection and hover painted
           // the SAME wash, which made "the row whose record is open" and "the row
           // the pointer happens to be over" indistinguishable — the register's
-          // one piece of persistent state, erased by a transient one. Hover is
-          // now neutral and lighter, because it answers "you can press this",
-          // while selection carries the brand's WASH because it answers "you are
-          // here" — the state the accent exists for. `pressed` stays neutral and
-          // darkest: a momentary depth cue, not an identity.
-          // `marked` shares the wash rather than keeping its own literal blue-50:
-          // that hex was the same colour the wash now resolves to, minus the
-          // theming, so a branded app painted its ticked rows in a hue it had
-          // replaced everywhere else. What separates a ticked row from an open
-          // one is the ticked checkbox, which is unmissable; two washes for two
-          // orthogonal states could never render anyway on a row that is both.
-          backgroundColor: pressed ? colors.zinc[200] : selected || marked ? colors.accent_wash : hovered ? colors.zinc[50] : undefined,
+          // one piece of persistent state, erased by a transient one.
+          //
+          // ONE NEUTRAL STEP is what separates them: zinc-50 hovered, zinc-100
+          // selected, zinc-200 pressed. The fix was briefly to give selection a
+          // blue ground instead, which read as a brand nobody had chosen on the
+          // busiest surface in the product — and contradicted `accent`'s own rule
+          // that it does not paint interaction chrome, which is exactly what
+          // these four states are.
+          //
+          // THE LITERAL, not `accent_wash`. Reading a selection through the brand
+          // token is how the blue got here in the first place: a themed app would
+          // tint the row, so "selection is neutral" would be true of the kit and
+          // false of every app that set an accent. The token still exists and
+          // still means the brand's tint — it is spent on ATTENTION now (a drop
+          // target lighting up), never on which record is open.
+          //
+          // `marked` shares the ground rather than keeping its own blue-50: what
+          // separates a ticked row from an open one is the ticked checkbox, which
+          // is unmissable, and two grounds for two orthogonal states could never
+          // render anyway on a row that is both.
+          backgroundColor: pressed ? colors.zinc[200] : selected || marked ? colors.zinc[100] : hovered ? colors.zinc[50] : undefined,
         },
         style,
       ]}

package/src/reference_field.tsx

@@ -7,7 +7,7 @@ import { formatDate } from "./format_date";
 import { InlineEditView } from "./inline_edit";
 import { InlineStatic } from "./inline_static";
 import { Popover, PopoverContent, PopoverFooter, PopoverHeader } from "./popover";
-import { DialogSectionHeadingTitle } from "./section_heading";
+import { SectionHeadingTitle } from "./section_heading";
 import { Text } from "./text";
 import { TextInputField } from "./text_input_field";
 import { TextLink } from "./text_link";
@@ -256,19 +256,21 @@ export function ReferenceField(props: ReferenceFieldProps) {
           </View>
         }
       />
-      {/* THE PEEK'S FORMAT — the kit's own grammar, not a bespoke one. A popover
-          is dialog-scale, so the identity takes the ramp's dialog rung
-          (`DialogSectionHeadingTitle`, ####) with the code as its description
-          rather than a hand-picked font weight; the facts are `DetailRow`s, which
+      {/* THE PEEK'S FORMAT — the kit's own grammar, not a bespoke one. The
+          identity is a plain `SectionHeadingTitle` with the code as its
+          description rather than a hand-picked font weight — a popover is
+          dialog-scale, so the ramp puts it on the `####` rung by itself, and
+          this call site no longer names the surface it is standing
+          on; the facts are `DetailRow`s, which
           is what label-beside-value IS everywhere else on this page; and the
           verbs sit in the popover's own pinned footer rather than floating after
           the last fact.
 
           WIDTH COMES FROM THE FIELD (`inheritTriggerWidth`), not a constant. A
           fixed 320 was "every peek in an app is the same object", and the object
-          it was actually the same as was nothing on screen: measured on a record
-          page, a 558px field opened a 320px panel left-aligned under it, stopping
-          238px short of the edge the reader's eye had just travelled to. A
+          it was actually the same as was nothing on screen: a wide field opened a
+          narrow panel left-aligned under it, stopping short of the edge the
+          reader's eye had just travelled to. A
           popover narrower than the control that opened it reads as belonging to
           something else. `InlineSelect` — the same shape, an inline field opening
           a `triggerRef` popover — already inherits its field's width, so the two
@@ -294,7 +296,7 @@ export function ReferenceField(props: ReferenceFieldProps) {
           is never what scrolls out of view. */}
       <PopoverContent style={{ maxHeight: 420 }}>
         <PopoverHeader>
-          <DialogSectionHeadingTitle description={code}>{name}</DialogSectionHeadingTitle>
+          <SectionHeadingTitle description={code}>{name}</SectionHeadingTitle>
         </PopoverHeader>
         <View style={{ gap: 12 }}>
           {/* ONE geometry for both modes — the table's own 40px band, which is

package/src/section_heading.tsx

@@ -1,8 +1,9 @@
 import { View, type StyleProp, type ViewStyle } from "react-native";
-import { Text, type HeadingLevel } from "./text";
+import { Text, type HeadingLevel, type TextSize } from "./text";
 import { Icon, type IconName } from "./icon";
 import { InfoPopover } from "./info_popover";
 import { useLoticsLocale } from "./locale";
+import { useHeadingAltitude, type HeadingAltitude } from "./heading_altitude";
 
 // The card-less section header — the bare-canvas sibling of `CardHeader`, built
 // the same compound way. A title (+ optional leading icon / description) on one
@@ -117,9 +118,15 @@ export interface SubsectionHeadingTitleProps {
   info?: string;
 }
 
-/** The subsection title — ALWAYS `###` (lg semibold), the fixed step under the
- * xl section title and above the md/sm body. Grows to push siblings (a
- * `SectionHeadingMeta`, a `Badge`, an action) to the right edge. */
+/** The subsection title — ALWAYS `###` (lg semibold), the fixed step under a
+ * PAGE's xl section title and above the md/sm body. Grows to push siblings (a
+ * `SectionHeadingMeta`, a `Badge`, an action) to the right edge.
+ *
+ * It has one altitude, not two: inside a PANEL the section rung is already
+ * the ramp's floor (`####` md), so a subsection there would out-rank its own
+ * section. A named group inside a panel's section is `Text size="sm"
+ * weight="semibold"` — a panel is one surface, and a second heading level in it
+ * is a document the reader is not reading. */
 export function SubsectionHeadingTitle(props: SubsectionHeadingTitleProps) {
   const { children, description, level = 3, info } = props;
   const words = useLoticsLocale();
@@ -144,64 +151,6 @@ export function SubsectionHeadingTitle(props: SubsectionHeadingTitleProps) {
   );
 }
 
-export interface DialogSectionHeadingTitleProps {
-  children: React.ReactNode;
-  /** Optional muted line under the title, as on `SectionHeadingTitle`. */
-  description?: string;
-  /** Leading glyph, as on `SectionHeadingTitle`. */
-  icon?: IconName;
-  /** Heading rank. Defaults to 4 — one level under `SubsectionHeadingTitle`'s 3. */
-  level?: HeadingLevel;
-  /** An ⓘ popover after the title, as on the two rungs above. */
-  info?: string;
-}
-
-/**
- * The section title for a surface hosted in a DIALOG — ALWAYS `####` (md semibold), the fourth
- * rung of the same fixed ladder.
- *
- * It exists because `DialogHeaderTitle` is `lg`, which is the rung `SubsectionHeadingTitle`
- * occupies: a dialog holding a multi-section surface has its own title tying with, or being
- * outranked by, its content. The ladder stays ABSOLUTE — this is one more fixed size, never a
- * knob on an existing rung. Do not reach for a `size`/`compact` prop on the titles above; the same
- * rank rendering at two sizes is exactly what the fixed ramp prevents.
- *
- * Compose it with the SUBSECTION layout — `Subsection` › `SubsectionHeading` › this, inside a
- * `SubsectionStack`. Only the type size steps down; the 12px body gap and the 32px between-group
- * beat are already right for a dialog, so duplicating them under a `Dialog*` name would add three
- * exports that differ from their siblings in nothing.
- *
- *   <SubsectionStack divided>
- *     <Subsection>
- *       <SubsectionHeading>
- *         <DialogSectionHeadingTitle info="…">Usage</DialogSectionHeadingTitle>
- *         <SectionHeadingMeta>Aug 2 – Sep 2</SectionHeadingMeta>
- *       </SubsectionHeading>
- *       {body}
- *     </Subsection>
- *   </SubsectionStack>
- */
-export function DialogSectionHeadingTitle(props: DialogSectionHeadingTitleProps) {
-  const { children, description, icon, level = 4, info } = props;
-  const words = useLoticsLocale();
-  return (
-    <View style={{ flex: 1, minWidth: HEADING_TITLE_MIN_WIDTH, gap: 2 }}>
-      <View style={{ flexDirection: "row", alignItems: "center", gap: 6 }}>
-        {icon ? <Icon name={icon} size={16} /> : null}
-        <Text level={level} size="md" weight="semibold">
-          {children}
-        </Text>
-        {info ? <InfoPopover text={info} accessibilityLabel={words.sectionHeading.info} /> : null}
-      </View>
-      {description ? (
-        <Text color="zinc-500" size="sm">
-          {description}
-        </Text>
-      ) : null}
-    </View>
-  );
-}
-
 export interface SectionHeadingProps {
   children: React.ReactNode;
   style?: StyleProp<ViewStyle>;
@@ -219,7 +168,15 @@ export interface SectionHeadingTitleProps {
   children: React.ReactNode;
   description?: string;
   icon?: IconName;
-  /** Heading rank. Defaults to 2 — typical for page-level section titles. */
+  /**
+   * Heading rank, when the surface's own outline needs one the altitude does not
+   * give it. Leave it unset: the default is the rank of whichever rung the
+   * altitude selected (`2` on a page, `4` in a panel), so an outline is
+   * correct without anyone thinking about it.
+   *
+   * It does NOT move the type size — the ramp is absolute, and a rank rendering
+   * at two sizes is exactly what a fixed ladder exists to prevent.
+   */
   level?: HeadingLevel;
   /** Title weight. Defaults to `semibold` — a section title must separate from
    * the body rows at a glance (medium blends in; it remains as an opt-down for
@@ -230,21 +187,50 @@ export interface SectionHeadingTitleProps {
   info?: string;
 }
 
-/** The title block — ALWAYS `##` (xl semibold): the heading ramp is the fixed
- * markdown ladder `#` xxl (`RecordSummary`/`PageHeader`) → `##` xl (section) →
- * `###` lg (`SubsectionHeadingTitle`) over the sm body — no per-surface size
- * knobs, one outline everywhere. Optional muted `description` line; grows to
- * push any sibling actions to the right edge. */
+/**
+ * THE SECTION RUNG, per altitude — the two fixed points of one ladder, written
+ * down once.
+ *
+ * On a PAGE the section title is `##` (xl), under the `#` xxl identity band.
+ * Inside a PANEL it is `####` (md), under the container's `lg` chrome title —
+ * the ladder does not gain a knob, it gains a second fixed point, chosen by
+ * where the heading IS rather than by what the caller remembered to pass.
+ *
+ * The glyph steps with the type: a 20px icon beside 16px text is a mark that
+ * outweighs the words it introduces.
+ */
+const SECTION_RUNG = {
+  page: { size: "xl", level: 2, icon: 20 },
+  panel: { size: "md", level: 4, icon: 16 },
+} as const satisfies Record<HeadingAltitude, { size: TextSize; level: HeadingLevel; icon: number }>;
+
+/** The title block — the heading ramp's SECTION rung, on the fixed markdown
+ * ladder `#` xxl (`RecordSummary`/`PageHeader`) → `##` xl (section) → `###` lg
+ * (`SubsectionHeadingTitle`) over the sm body. No size knob: which rung it
+ * renders is decided by the SURFACE, not the call site — `##` xl on a page,
+ * `####` md inside a panel's content region, where the container's own title
+ * is already `lg`. A caller never says which; the container publishes it (see
+ * `heading_altitude.ts`), so the same heading is correct on a page and in a
+ * drawer without being written twice.
+ *
+ * Inside a panel this rung is the ramp's FLOOR — a pane is one surface,
+ * not a document. A named group inside a section there is `Text size="sm"
+ * weight="semibold"`, not a `SubsectionHeadingTitle`, which is `lg` at every
+ * altitude and would out-rank the section holding it.
+ *
+ * Optional muted `description` line; grows to push any sibling actions to the
+ * right edge. */
 export function SectionHeadingTitle(props: SectionHeadingTitleProps) {
-  const { children, description, icon, level = 2, weight = "semibold", info } = props;
+  const { children, description, icon, level, weight = "semibold", info } = props;
   // Hoisted — a hook inside the `info ?` ternary breaks hook ordering the
   // render `info` appears or disappears.
   const words = useLoticsLocale();
+  const rung = SECTION_RUNG[useHeadingAltitude()];
   return (
     <View style={{ flex: 1, minWidth: HEADING_TITLE_MIN_WIDTH, gap: 2 }}>
       <View style={{ flexDirection: "row", alignItems: "center", gap: 6 }}>
-        {icon ? <Icon name={icon} size={20} /> : null}
-        <Text level={level} weight={weight} size="xl">
+        {icon ? <Icon name={icon} size={rung.icon} /> : null}
+        <Text level={level ?? rung.level} weight={weight} size={rung.size}>
           {children}
         </Text>
         {info ? <InfoPopover text={info} accessibilityLabel={words.sectionHeading.info} /> : null}

package/src/stepper.tsx

@@ -288,9 +288,8 @@ export function Step(props: StepProps) {
                 on the first content row, so there is a `markerTopOffset` band of
                 empty column above it. A single below-the-marker segment cannot
                 reach into the NEXT step's band, so the line broke at every joint
-                — ~4px under each marker (this segment's old top margin) plus the
-                next one's offset above it. Measured on the record template: 4px
-                and 3px, at every stage, which reads as dashes rather than a spine.
+                — a gap under each marker (this segment's old top margin) plus the
+                next one's offset above it, which reads as dashes rather than a spine.
                 The upper segment fills that band, so the line is continuous from
                 the first marker to the last. It also replaces the column's old
                 `paddingTop`, which is why the marker lands in the same place. */}

package/src/summary.tsx

@@ -231,9 +231,9 @@ const styles = StyleSheet.create({
   // 12, and it is half of what a page must put BETWEEN this band and its
   // neighbours. The band's parts are one group — a figure, the shape of what it
   // counts, and that shape's key — so they have to sit closer to each other than
-  // the band sits to the register below it. Measured at 14 against a 16px page
-  // gap, the ratio was 1.14: every block on the screen an equal peer, nothing
-  // grouped, which is what "no rhythm" is when you measure it.
+  // the band sits to the register below it. At near-parity with the page gap
+  // every block on the screen is an equal peer, nothing
+  // grouped, which is what "no rhythm" means.
   root: { gap: 12 },
   header: {
     flexDirection: "row",

package/src/table.tsx

@@ -612,7 +612,10 @@ const styles = StyleSheet.create({
   // A hairline under the column header anchors the columns; the rows below it are
   // Divider-separated.
   headerBandFilled: {
-    backgroundColor: colors.accent_wash,
+    // The literal neutral, not `accent_wash`: this band is a lid on the columns,
+    // never a "you are here", and reading it through the brand token made a
+    // themed app tint a piece of pure furniture.
+    backgroundColor: colors.zinc[100],
     // The band bleeds to the row wash's width so its edges line up with a hovered
     // row beneath it; without this the lid is narrower than the rows it caps.
     marginHorizontal: -ROW_WASH_BLEED,