@lotics/ui 41.1.0 → 41.3.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@lotics/ui",
-  "version": "41.1.0",
+  "version": "41.3.0",
   "type": "module",
   "exports": {
     "./vite": {
@@ -109,6 +109,7 @@
       "react-native": "./src/markdown.tsx",
       "default": "./src/markdown.web.tsx"
     },
+    "./markdown_types": "./src/markdown_types.ts",
     "./markdown.css": "./src/markdown.css",
     "./confidence": "./src/confidence.tsx",
     "./finding": "./src/finding.tsx",
@@ -194,6 +195,7 @@
     "./counter": "./src/counter.tsx",
     "./link": "./src/link.tsx",
     "./reference_field": "./src/reference_field.tsx",
+    "./text_disclosure": "./src/text_disclosure.tsx",
     "./text_link": "./src/text_link.tsx",
     "./sort_header": "./src/sort_header.tsx",
     "./skeleton": "./src/skeleton.tsx",

package/src/inline_text_input.tsx

@@ -25,8 +25,37 @@ export interface InlineTextInputProps {
    * a payment term, an address, a clause. Default 1 (the single-line field).
    * Above 1 the field is that many lines tall and wraps, in both states. Enter
    * then inserts a newline; the field commits on blur (or the ✓ in "buttons").
+   *
+   * With `autoGrow` this becomes the MINIMUM rather than the whole budget.
    */
   numberOfLines?: number;
+  /**
+   * Grow to fit the value instead of clipping it at `numberOfLines`.
+   *
+   * A fixed budget is right for a value with a KNOWN shape — a two-line address,
+   * a payment term — where reserving the space keeps the page still. It is wrong
+   * for open prose, and it fails in the worst way: the field renders a box the
+   * value does not fit, with no ellipsis, no scrollbar and no scroll, so the
+   * reader is given no evidence that anything is missing. Measured on a record
+   * note, 285 characters drew 76px of a 116px value — two lines gone, silently.
+   *
+   * Growing costs nothing this control was protecting: the field is ONE input in
+   * both states, so a grown box is the same height resting and editing, and
+   * nothing moves on focus. It grows as you type, which is the same promise the
+   * value's own wrapping already makes.
+   *
+   * Reach for it wherever the length is the AUTHOR's choice rather than the
+   * field's. Keep the fixed budget in the two cases it is still right:
+   *
+   * - **A value that can be arbitrarily long.** Growth has no ceiling — measured,
+   *   406 characters is already 238px — so a field that may hold a document wants
+   *   the reserve, and a length that overflows it is the signal that the value
+   *   belongs somewhere else.
+   * - **A GRID cell** (`variant="bare"` in a `DataGrid`). A cell that varies with
+   *   its data breaks the row rhythm the grid promises — see the register laws in
+   *   composition.md. Grow on a record surface, reserve in a table.
+   */
+  autoGrow?: boolean;
   accessibilityLabel?: string;
   /** Verbs on the field's surface — an `InlineButton` Copy on a reference a reader
    *  quotes elsewhere. See `InlineEditView.actions`: rendered in BOTH modes so the
@@ -46,8 +75,9 @@ export interface InlineTextInputProps {
  * implementation detail.
  */
 export function InlineTextInput(props: InlineTextInputProps) {
-  const { value, onSave, placeholder, controls = "blur", disabled, struck, accessibilityLabel , variant, actions, numberOfLines } = props;
-  const multiline = (numberOfLines ?? 1) > 1;
+  const { value, onSave, placeholder, controls = "blur", disabled, struck, accessibilityLabel , variant, actions, numberOfLines, autoGrow } = props;
+  // Growing implies wrapping: a field that grows on one line has nowhere to go.
+  const multiline = (numberOfLines ?? 1) > 1 || autoGrow === true;
   const edit = useInlineEdit<string>({ value, onSave });
 
   const onKeyPress = useCallback(
@@ -128,6 +158,7 @@ export function InlineTextInput(props: InlineTextInputProps) {
         onKeyPress={onKeyPress}
         multiline={multiline}
         numberOfLines={numberOfLines}
+        autoGrow={autoGrow}
         placeholder={placeholder}
         accessibilityLabel={accessibilityLabel}
         // `disabled`, NOT `editable`: TextInputField derives editability as

package/src/markdown.css

@@ -60,6 +60,49 @@
   margin: 0;
 }
 
+/*
+ * EMBEDDED — markdown that is a VALUE on someone else's page, not the page.
+ *
+ * The scale above is a document's: `h1` is 24/600, which is exactly a
+ * `SectionHeadingTitle`. That is right when the markdown IS the surface (a
+ * knowledge doc, a terms page) and wrong the moment it is a field on a record,
+ * because the author of the text is then not the author of the page — and
+ * increasingly is not a person at all. A model asked for a call summary writes
+ * `##` headings and liberal `**bold**`, and the page hands them a rung one step
+ * under its own section headings: measured on a real interaction log, a machine
+ * summary inside a feed row drew 18px/600 headings over 44 medium-weight runs,
+ * so the least-trustworthy content on the screen was also the loudest.
+ *
+ * Embedded, every heading collapses to ONE treatment at the body's own size,
+ * one weight step above `strong`. A heading is still legible as a heading —
+ * it owns its line and carries the space around it, which is SHAPE rather than
+ * scale — and it can no longer outrank the surface it was dropped into.
+ */
+.ui-markdown-embedded h1,
+.ui-markdown-embedded h2,
+.ui-markdown-embedded h3,
+.ui-markdown-embedded h4,
+.ui-markdown-embedded h5,
+.ui-markdown-embedded h6 {
+  font-family: Inter_600SemiBold, "apple-system", "BlinkMacSystemFont", "Segoe UI",
+    "Roboto", "Oxygen", "Ubuntu", "Cantarell", "Fira Sans", "Droid Sans",
+    "Helvetica Neue", sans-serif;
+  font-size: 14px;
+  line-height: 20px;
+  font-weight: 600;
+  padding-top: 8px;
+  padding-bottom: 2px;
+}
+
+/* A value never opens with a gap its container did not ask for. */
+.ui-markdown-embedded > :first-child {
+  padding-top: 0;
+}
+
+.ui-markdown-embedded > :last-child {
+  padding-bottom: 0;
+}
+
 /* Block elements */
 
 .ui-markdown p {

package/src/markdown.tsx

@@ -1,5 +1,6 @@
 import { View } from "react-native";
 import { Text } from "./text";
+import type { MarkdownProps } from "./markdown_types";
 
 /**
  * Native fallback. The rich renderer (`markdown.web.tsx`) is react-markdown over
@@ -7,11 +8,16 @@ import { Text } from "./text";
  * native, so this renders the source as plain text. Rich markdown shows on web
  * (custom-code apps + the frontend on web), which is where it's used; the web
  * variant is picked via the conditional `exports` in package.json.
+ *
+ * `variant` is accepted and ignored: plain text has one scale, so there is no
+ * heading to demote. The props type is NOT re-exported — import it from
+ * `@lotics/ui/markdown_types`, the same way `MediaPlayerProps` is reached.
  */
-export function Markdown({ children }: { children: string }) {
+export function Markdown({ children }: MarkdownProps) {
   return (
     <View>
       <Text size="sm">{children}</Text>
     </View>
   );
 }
+

package/src/markdown.web.tsx

@@ -5,11 +5,12 @@ import ReactMarkdown from "react-markdown";
 import { remarkGfmSafe } from "./remark_gfm_safe";
 import { Icon } from "./icon";
 import { colors } from "./colors";
+import type { MarkdownProps } from "./markdown_types";
 
-export function Markdown({ children }: { children: string }) {
+export function Markdown({ children, variant = "document" }: MarkdownProps) {
   return (
     <View>
-      <div className="ui-markdown">
+      <div className={variant === "embedded" ? "ui-markdown ui-markdown-embedded" : "ui-markdown"}>
         <ReactMarkdown remarkPlugins={[remarkGfmSafe]} components={markdownComponents}>
           {children}
         </ReactMarkdown>
@@ -18,6 +19,7 @@ export function Markdown({ children }: { children: string }) {
   );
 }
 
+
 const markdownComponents = {
   table: CopyableTable,
 };

package/src/markdown_types.ts

@@ -0,0 +1,21 @@
+export interface MarkdownProps {
+  children: string;
+  /**
+   * Whose type ladder the headings belong to.
+   *
+   * **`"document"` (default)** — the markdown IS the surface: a knowledge doc, a
+   * terms page, a rendered artifact. Its `h1` is the page's `h1`.
+   *
+   * **`"embedded"`** — the markdown is a VALUE on a page someone else designed:
+   * a field on a record, a summary in a feed row, a note in a drawer. Every
+   * heading collapses to the body's own size so it cannot outrank the section
+   * that contains it.
+   *
+   * **Reach for `"embedded"` whenever the text was not written by whoever built
+   * the screen** — and that is now the common case, because the writer is
+   * routinely a model. A model asked for a summary emits `##` headings and heavy
+   * `**bold**` with no idea what surrounds them, so document scale puts the
+   * least-trustworthy content on the screen at the loudest rung on it.
+   */
+  variant?: "document" | "embedded";
+}

package/src/member_chip.tsx

@@ -36,15 +36,25 @@ interface MemberChipProps {
  */
 export function MemberChip({ name, image, secondary, size = "md", style }: MemberChipProps) {
   const displayName = name?.trim() || "Unknown";
+  // THE TEXT FOLLOWS THE RUNG. `size` used to scale the avatar alone, so a chip
+  // asked for the dense rung got a 24px avatar beside a 14px name — half-dense,
+  // and the mismatch surfaces wherever the chip sits INSIDE a sentence: a 12px
+  // "Logged by" running straight into a 14px name reads as two type systems
+  // meeting mid-phrase, and their line boxes (16 against 20) then refuse to
+  // share a baseline under any `alignItems: "center"`.
+  //
+  // Only `sm` steps down, because only `sm` claims to be dense; every larger
+  // rung keeps the body size, where a person's name belongs.
+  const textSize = size === "sm" ? "xs" : "sm";
   return (
     <View style={[styles.row, style]}>
       <Avatar size={size} name={displayName} source={image ? { uri: image } : undefined} />
       <View style={styles.text}>
-        <Text userSelect="none" numberOfLines={1}>
+        <Text userSelect="none" size={textSize} numberOfLines={1}>
           {displayName}
         </Text>
         {secondary ? (
-          <Text userSelect="none" size="sm" color="zinc-500" numberOfLines={1}>
+          <Text userSelect="none" size={textSize} color="zinc-500" numberOfLines={1}>
             {secondary}
           </Text>
         ) : null}

package/src/text_disclosure.tsx

@@ -0,0 +1,70 @@
+import { Pressable } from "react-native";
+import { TextLink } from "./text_link";
+import type { TextSize } from "./text";
+
+export interface TextDisclosureProps {
+  /** Open state — controlled, because the content it reveals is the caller's. */
+  expanded: boolean;
+  onToggle: (expanded: boolean) => void;
+  /** What is behind it, as a noun: "transcript", "3 earlier replies". The verb
+   *  is supplied — a caller writing its own "Show …" ends up with two vocabularies
+   *  for one control the first time somebody writes "View". */
+  label: string;
+  /** Matches the prose it sits in. Default "sm". */
+  size?: TextSize;
+  /** Announced name, when `label` alone is ambiguous on a page with several. */
+  accessibilityLabel?: string;
+  testID?: string;
+}
+
+/**
+ * An in-prose DISCLOSURE: muted underlined text that reveals adjacent content in
+ * place — a transcript under its player, a long value under its summary.
+ *
+ * The counterpart to {@link TextLink}, and the pair is the point: underlined text
+ * either GOES somewhere or REVEALS something, and the INK says which.
+ *
+ *   blue + `role="link"` (`Link`)   → leaves this surface
+ *   muted underline (this)          → reveals more of it, right here
+ *
+ * Both answer "show me more"; only one takes the reader away, which is the single
+ * question the affordance exists to answer. Anything that MUTATES — saves, sends,
+ * deletes, opens an overlay — carries a control surface instead (`Button` in
+ * chrome, `InlineButton` on a field). See composition.md §"Commit & feedback surfaces".
+ *
+ * **Why this is a component rather than three lines at each call site.** It
+ * carries a contract, and every part of it is a thing a hand-roll gets wrong:
+ *
+ * - **`role="button"`, never `role="link"`.** The obvious reach is `Link`, which
+ *   announces a destination — so a screen-reader user is told they are leaving a
+ *   page that is about to unfold under them.
+ * - **Muted, never blue.** Blue is the promise of a trip. One caller passing the
+ *   navigation ink is all it takes for underline to stop meaning anything.
+ * - **Reveal only.** The exception to "underline navigates" is this narrow, and a
+ *   named component is what keeps it narrow — the next author reaching for quiet
+ *   text to hang a DELETE on finds a name that does not fit.
+ *
+ * **What it is not.** Not `Accordion`: that is a list-row disclosure with a header
+ * and a chevron, right for a run of expandable rows and heavy furniture for a verb
+ * inside one. Not `Button color="muted"`: measured, that is transparent,
+ * borderless and undecorated at rest, so its affordance arrives only on hover —
+ * invisible to keyboard and touch, and against a text column it reads as a label.
+ */
+export function TextDisclosure(props: TextDisclosureProps) {
+  const { expanded, onToggle, label, size = "sm", accessibilityLabel, testID } = props;
+  return (
+    <Pressable
+      onPress={() => onToggle(!expanded)}
+      accessibilityRole="button"
+      // The STATE, announced. Without it a screen reader hears the same words
+      // whichever way the disclosure is sitting.
+      aria-expanded={expanded}
+      accessibilityLabel={accessibilityLabel}
+      testID={testID}
+    >
+      <TextLink size={size} color="muted">
+        {expanded ? `Hide ${label}` : `Show ${label}`}
+      </TextLink>
+    </Pressable>
+  );
+}

package/src/text_link.tsx

@@ -26,9 +26,19 @@ export interface TextLinkProps extends TextProps {
  * The act mode briefly became its own surface-less component and is now gone
  * entirely: it made underline mean two things separable only by ink, and it competed
  * with the `Button` colour ladder for the job `muted` already does. **Underlined text
- * is the NAVIGATION affordance; anything that acts carries a control surface** —
- * `Button` in chrome, `InlineButton` on a field. A quiet verb that cannot sit against
- * a text column belongs in chrome, not in a rung of its own.
+ * GOES somewhere or REVEALS something; anything that MUTATES carries a control
+ * surface** — `Button` in chrome, `InlineButton` on a field.
+ *
+ * The reveal half is the one narrow exception, and this component is how you build
+ * it: an in-prose DISCLOSURE (a transcript under its player, a long value under its
+ * summary) wrapped in your own `Pressable`, `color="muted"` so it never wears the
+ * navigation blue. It exists because the rule used to end "a quiet verb that cannot
+ * sit against a text column belongs in chrome" — and a disclosure cannot go to
+ * chrome, it belongs to the thing above it. The two controls that fit chrome both
+ * fail here: a `muted` Button is transparent and undecorated at rest (a hover-only
+ * affordance), and an `Accordion` is a list row nested inside a list row. The INK is
+ * what keeps underline unambiguous — blue leaves, muted stays. See composition.md
+ * §"Commit & feedback surfaces".
  */
 export function TextLink(props: TextLinkProps) {
   const { icon, href, children, color, style, ...textProps } = props;

package/src/timeline.tsx

@@ -14,11 +14,55 @@ export interface TimelineItem {
    *  renders a tinted disc of this color; the icon takes the full color. */
   iconColor: string;
   isLoading?: boolean;
+  /**
+   * The row's identity line — CLAMPED TO TWO LINES, because it is a scan target
+   * before it is a sentence. A feed is the one place user-authored prose lands in
+   * a row primitive, and unclamped it eats the section: measured on a real
+   * interaction log, one 700-character summary drew a 180px label — nine lines
+   * for one entry, and the disc, which centres on the label row, ended up 80px
+   * below the first line it was meant to sit beside.
+   *
+   * So a label that can run long belongs in `details` as well, in full. The
+   * clamp is the contract rather than a prop: a prop would let the next caller
+   * re-open the same hole, and the whole point is that the row keeps its beat
+   * whatever the caller hands it.
+   */
   label: string;
-  /** An always-visible sub-line under the label (a note, a detail). When set, the
-   *  row top-aligns so `right` sits next to the label, not centred on the block. */
+  /**
+   * The label is a STAND-IN the surface supplied, not a value the record holds —
+   * render it in the placeholder tone the kit uses for an unfilled field.
+   *
+   * A feed fills up from more than one direction: a person writes an entry, but
+   * an automation also drops one the moment a recording lands, and an extraction
+   * files one from a screenshot. Those arrive with no words in them, and a row
+   * whose identity line is `string` forces the caller to invent some — which
+   * then renders in body ink, indistinguishable from a note somebody actually
+   * wrote. "Nobody has written this up" and "this is what happened" must not
+   * look alike; without this flag the type makes them.
+   */
+  placeholder?: boolean;
+  /** An always-visible sub-line under the label (a note, a detail) — clamped to
+   *  two lines, same reason. When set, the row top-aligns so `right` sits next to
+   *  the label, not centred on the block. */
   description?: string;
   error?: string;
+  /**
+   * Trailing content — a duration, a badge, a status. It renders BESIDE the press
+   * target rather than inside it, so an interactive one stays clickable on its
+   * own: nesting a control in the row's own button is invalid HTML (`<button>`
+   * cannot contain `<button>`) and hands one click to two handlers. The chevron
+   * closes the pressable region; `right` sits after it.
+   *
+   * **On a row that EXPANDS, prefer putting verbs in the body instead.** A
+   * control sharing the label row with the press target produced three separate
+   * defects here, and they are not independent: it nested a button in a button,
+   * it needed a fixed-height box of its own to stay on the label's first line,
+   * and it sat close enough to the chevron to read as one cluster with it. All
+   * three exist only because something interactive shares the row. In the body
+   * there is no press target to share with, and the verbs sit next to the
+   * content they act on — where an expansion the reader chose is also the look
+   * before a destructive act. Keep `right` for what it is good at: a fact.
+   */
   right?: ReactNode;
   details?: ReactNode;
 }
@@ -50,20 +94,44 @@ export function Timeline(props: TimelineProps) {
         const isFirst = index === 0;
         const isLast = index === items.length - 1;
 
-        // The label row: label + right + chevron only. Secondary lines
-        // (description/error) render BELOW in the spine band, so the disc can
-        // center against this row whatever its height (a plain 20px label or a
-        // 40px inline control in `right` both align label-on-disc).
+        // The label row: label + chevron only. Secondary lines
+        // (description/error) render BELOW in the spine band.
+        //
+        // Everything in this band aligns to the label's FIRST LINE, never to the
+        // label BLOCK — see FIRST_LINE_CENTRE. That is why the row tops its
+        // children and the chevron carries an offset instead of being centred:
+        // centring matches first-line alignment exactly until a label wraps, and
+        // then quietly stops.
         const row = (
           <View style={styles.row}>
-            <Text size="sm" style={{ flex: 1 }}>{item.label}</Text>
-            {item.right}
+            <Text
+              size="sm"
+              numberOfLines={2}
+              // The same ink an unfilled field draws (`Not set`, `No date set`),
+              // so an unwritten row reads as unwritten everywhere it appears.
+              color={item.placeholder ? "zinc-400" : undefined}
+              style={{ flex: 1 }}
+            >
+              {item.label}
+            </Text>
             {hasDetails ? (
-              <Icon name={expanded ? "chevron-up" : "chevron-down"} size={14} color={colors.zinc[400]} />
+              <View style={styles.onFirstLine}>
+                <Icon name={expanded ? "chevron-up" : "chevron-down"} size={14} color={colors.zinc[400]} />
+              </View>
             ) : null}
           </View>
         );
 
+        // `right` centres inside a first-line-tall box, so a duration, a badge
+        // and a row-action menu all land on the label's first line whatever
+        // their own height, and stay there when the label wraps. Which box
+        // depends on whether it sits inside the row's padding or beside it.
+        const trailing = item.right ? (
+          <View style={hasDetails ? styles.onFirstLineOutdented : styles.onFirstLine}>
+            {item.right}
+          </View>
+        ) : null;
+
         return (
           <View key={item.id}>
             {/* Band 1 — disc beside the label row, vertically CENTERED on it.
@@ -71,7 +139,7 @@ export function Timeline(props: TimelineProps) {
                 through tall rows. */}
             <View style={styles.labelBand}>
               <View style={styles.discColumn}>
-                <View style={styles.halfSpineSlot}>{!isFirst ? <View style={styles.spineFill} /> : null}</View>
+                <View style={styles.spineAbove}>{!isFirst ? <View style={styles.spineFill} /> : null}</View>
                 <AnimationFadeIn key={`${item.id}-${item.icon}`}>
                   {/* Tinted disc: a low-alpha wash of the accent behind a full-color icon. */}
                   <View style={[styles.node, { backgroundColor: withAlpha(item.iconColor, 0.1) }]}>
@@ -82,15 +150,23 @@ export function Timeline(props: TimelineProps) {
                     )}
                   </View>
                 </AnimationFadeIn>
-                <View style={styles.halfSpineSlot}>{!isLast ? <View style={styles.spineFill} /> : null}</View>
+                <View style={styles.spineBelow}>{!isLast ? <View style={styles.spineFill} /> : null}</View>
               </View>
               <View style={styles.rowColumn}>
                 {hasDetails ? (
-                  <PressableHighlight focusRing onPress={() => toggleItem(item.id)} style={styles.pressableRow}>
-                    {row}
-                  </PressableHighlight>
+                  // `right` is a SIBLING of the press target, never a child of
+                  // it — see the prop's doc comment.
+                  <View style={styles.rowSplit}>
+                    <PressableHighlight focusRing onPress={() => toggleItem(item.id)} style={styles.pressableRow}>
+                      {row}
+                    </PressableHighlight>
+                    {trailing}
+                  </View>
                 ) : (
-                  <View style={styles.plainRow}>{row}</View>
+                  <View style={styles.plainRow}>
+                    {row}
+                    {trailing}
+                  </View>
                 )}
               </View>
             </View>
@@ -100,7 +176,7 @@ export function Timeline(props: TimelineProps) {
             <View style={styles.belowBand}>
               <View style={styles.spineColumn}>{!isLast ? <View style={styles.spineFill} /> : null}</View>
               <View style={[styles.belowColumn, isLast && !hasBelow ? styles.belowColumnLast : null]}>
-                {item.description ? <Text size="xs" color="muted">{item.description}</Text> : null}
+                {item.description ? <Text size="xs" color="muted" numberOfLines={2}>{item.description}</Text> : null}
                 {item.error ? (
                   <Text size="xs" color="danger" numberOfLines={1}>{item.error}</Text>
                 ) : null}
@@ -114,19 +190,55 @@ export function Timeline(props: TimelineProps) {
   );
 }
 
+/** Line box of the label (`Text size="sm"`). */
+const LINE_HEIGHT = 20;
+/** The row's vertical padding — also the press target's breathing room. */
+const ROW_PAD_Y = 10;
+/** The disc itself, and the air it keeps around it. */
+const NODE_SIZE = 32;
+const NODE_MARGIN_Y = 3;
+/** The disc's own box — DERIVED, because `spineAbove` is sized by the difference
+ *  between this and the first line. Hand-copied as `38` it drifted the moment
+ *  either number above changed, and the symptom would have been the disc sliding
+ *  off the very line FIRST_LINE_CENTRE exists to hold it on. */
+const NODE_BOX = NODE_SIZE + NODE_MARGIN_Y * 2;
+
+/**
+ * WHERE THE LABEL'S FIRST LINE SITS, measured from the top of the label band —
+ * and the single number every ornament in that band derives from.
+ *
+ * It exists because "centre it on the row" and "put it on the first line" are
+ * the same answer right up until a label wraps, and then they are 10px apart,
+ * silently: the disc slides to the middle of the pair while the one-line rows
+ * beside it stay put, and the column stops being a column. Only the wrapped rows
+ * are wrong, so nothing about the screen says which number is the mistake.
+ *
+ * Every ornament reads this instead of picking its own — the disc, the chevron,
+ * and whatever a caller puts in `right`.
+ */
+const FIRST_LINE_CENTRE = ROW_PAD_Y + LINE_HEIGHT / 2;
+
 const styles = StyleSheet.create({
   labelBand: {
     flexDirection: "row",
     gap: 12,
   },
-  // Stretches to the label row's height; the disc centers on it, half-spines
-  // fill the remainder so the line never breaks on a tall row.
+  // Stretches to the label row's height so the spine below the disc can fill it;
+  // the disc itself is PINNED to the first line rather than centred on the block
+  // (see FIRST_LINE_CENTRE).
   discColumn: {
     width: 32,
     alignSelf: "stretch",
     alignItems: "center",
   },
-  halfSpineSlot: {
+  // A fixed sliver above the disc puts its centre on the label's first line; the
+  // slot below flexes, so the spine still reaches the bottom of a tall row.
+  spineAbove: {
+    height: FIRST_LINE_CENTRE - NODE_BOX / 2,
+    alignItems: "center",
+    justifyContent: "center",
+  },
+  spineBelow: {
     flex: 1,
     alignItems: "center",
     justifyContent: "center",
@@ -138,12 +250,12 @@ const styles = StyleSheet.create({
     backgroundColor: colors.zinc[200],
   },
   node: {
-    width: 32,
-    height: 32,
-    borderRadius: 16,
+    width: NODE_SIZE,
+    height: NODE_SIZE,
+    borderRadius: NODE_SIZE / 2,
     justifyContent: "center",
     alignItems: "center",
-    marginVertical: 3,
+    marginVertical: NODE_MARGIN_Y,
   },
   rowColumn: {
     flex: 1,
@@ -167,31 +279,79 @@ const styles = StyleSheet.create({
   },
   row: {
     flexDirection: "row",
-    alignItems: "center",
+    // TOP, not centre — the whole band aligns to the first line.
+    alignItems: "flex-start",
     gap: 10,
     flex: 1,
   },
-  // The press target for expandable rows; pressable rows bleed the hover wash
-  // past the text column.
+  // Centres its content on the first line, for anything INSIDE the row's padding
+  // — the chevron, and `right` on a row that is not a press target.
+  //
+  // `height`, never `minHeight`. A floor lets the box GROW to whatever the
+  // caller passed, and a grown box centres its content on its own new middle
+  // rather than on the line: against these numbers a 28px `ActionMenu` in a
+  // plain row's `right` lands 4px low and a 40px control 10px low, while a 16px
+  // duration — the only `right` in the kit's own examples — sits perfectly,
+  // which is exactly how a defect like this survives review. A FIXED box
+  // overflows symmetrically instead (a View does not clip), so the content's
+  // centre stays pinned whatever its size.
+  onFirstLine: {
+    height: LINE_HEIGHT,
+    justifyContent: "center",
+  },
+  // The same job for `right` on an EXPANDABLE row, where it sits outside the
+  // press target and so does not inherit that padding. Two styles rather than
+  // one because the difference is real: same target line, different origin.
+  onFirstLineOutdented: {
+    height: FIRST_LINE_CENTRE * 2,
+    justifyContent: "center",
+  },
+  // Holds the press target and `right` side by side, so the wash marks exactly
+  // what a press acts on. The 8px BLEED lives here rather than on the pressable:
+  // owned by the child it would push `right` into the gap, and a wash sliding
+  // under a control is how a row action stops being visible at the moment the
+  // pointer reaches it.
+  rowSplit: {
+    flexDirection: "row",
+    alignItems: "flex-start",
+    // WIDER than the gap INSIDE the press target (10), because these are not
+    // peers: the chevron belongs to the row's own button, `right` does not. At 4
+    // the two sat 12px apart against the chevron's 10 — near enough to 1:1 that
+    // the eye read them as one cluster, with only a 4px break in the hover wash
+    // saying otherwise, which a reader who never hovers never sees. 20 against
+    // 10 is the ratio that makes them two things.
+    gap: 12,
+    marginHorizontal: -8,
+  },
+  // The press target for expandable rows; the horizontal padding puts the label
+  // back on the column's own left edge, which the bleed above moved off it.
+  //
+  // There is no `minHeight` any more, and none is missing: `ROW_PAD_Y` on both
+  // sides of one line IS the 40px touch target, so the two can no longer
+  // disagree. A floor above the content was also what made this row centre its
+  // children in slack it owned — the drift FIRST_LINE_CENTRE exists to remove.
   pressableRow: {
+    flex: 1,
     borderRadius: 8,
     paddingHorizontal: 8,
-    paddingVertical: 4,
-    marginHorizontal: -8,
-    minHeight: 40,
+    paddingVertical: ROW_PAD_Y,
     flexDirection: "row",
-    alignItems: "center",
+    alignItems: "flex-start",
   },
   plainRow: {
-    paddingVertical: 4,
-    minHeight: 40,
+    paddingVertical: ROW_PAD_Y,
     flexDirection: "row",
-    alignItems: "center",
+    alignItems: "flex-start",
+    gap: 10,
   },
+  // NO left padding. It was 2, which put a row's body 2px right of the
+  // description line directly above it — one column of text at two left edges,
+  // small enough to read as sloppiness rather than as a defect, and the reason a
+  // reader cannot say what is wrong with a screen that measures fine everywhere
+  // else. An indent is legitimate only when something VISIBLE occupies it.
   detailsContainer: {
     gap: 8,
     paddingTop: 8,
-    paddingLeft: 2,
   },
 });