@lotics/ui 10.0.0 → 11.0.0

package/AGENTS.md

@@ -1,5 +1,13 @@
 # @lotics/ui — the UI reference
 
+> **Upgrading to v11 from ≤10.x — the type scale was re-slotted.** The display sizes gained the
+> missing `##` step: `xl` is now 22/24 (section title), `xxl` is 28/32 (page/record title — the
+> OLD `xl` look), and the new `xxxl` is 32/48 (hero numbers — the OLD `xxl` look). Migrate an
+> app with two renames IN THIS ORDER: first `size="xxl"` → `size="xxxl"`, then `size="xl"` →
+> `size="xxl"` — every existing usage keeps its exact look. Also: `SectionHeadingTitle` is now
+> ALWAYS `##` (22/24), and disabled `Button`s fade their label to the zinc-400 disabled ink on
+> every variant.
+
 A React-Native-Web component kit (renders on web **and** native). This file is the design
 law + the "reach for what" guide. The **exact API** of any component is its source, which
 ships with the package: read `node_modules/@lotics/ui/src/<name>.tsx`. **Never guess a prop —
@@ -121,7 +129,12 @@ Pick by capability, not by name. (→ the source file for the API.)
   row/column/grand totals; press a cell to drill).
 - **Surfaces & layout** — `Card` (+ `CardHeader`/`CardHeaderTitle`/`CardHeaderMeta`/`CardBody`/
   `CardFooter`), `Section` (the card-less twin of `Card`: bare gap-spaced region + `SectionHeading`/
-  `SectionHeadingTitle`/`SectionHeadingMeta`; no body component — children are the body), `SectionCard`,
+  `SectionHeadingTitle`/`SectionHeadingMeta`; no body component — children are the body;
+  ), `Subsection` (+ `SubsectionHeading`/
+  `SubsectionHeadingTitle` — the named group INSIDE a section, `###` lg-semibold title),
+  `SectionStack` (the flat page's content column — owns the fixed 56px beat + hairline between
+  top-level blocks), `SubsectionStack` (the same law one step tighter — fixed 24px beat +
+  hairline between a section's `Subsection` groups), `SectionCard`,
   `PageHeader` /
   `PageContent`, `Stack`, `Spacer`, `Divider`, `Accordion`, `Tabs`, `SegmentedControl`, `Stepper`,
   `DangerZone` (the destructive section — delete/archive — set apart at the bottom of a record/settings surface).
@@ -655,19 +668,32 @@ was only ever about the review surfaces' sparkles/severity glyphs, not functiona
 - **Canvas**: full-bleed `colors.zinc[50]` ScrollView; content column `maxWidth` 880–1040,
   centered, `padding: 28`. Cards float on the canvas — never white-on-white.
 - **Heading vocabulary — ONE construct per altitude, no drift.**
-  · **Page band**: one per screen — `Text size="xl" weight="semibold"` title + one `sm muted`
+  · **Page band**: one per screen — `Text size="xxl" weight="semibold"` title (`#`) + one `sm muted`
     subtitle that says what the screen decides. Right side: the screen's ONE primary action and/or
     a period filter — never a summary Badge (those belong to the KPI strip).
   · **Card header** (a card's own title band, or separate banded cards): `CardHeader` +
     `CardHeaderTitle` (`sm semibold`; `info` when the title alone doesn't define the numbers).
   · **Section title** — ONE construct: `Section` > `SectionHeading` > `SectionHeadingTitle`
     (lg semibold + optional muted `description`/`info`), everything left-aligned at the column
-    edge. The `Divider` goes BETWEEN sections (page column `gap: 32`, a bare hairline separating
-    one section from the next) — NEVER directly under the heading, which orphans the title from
-    its own content. Inside a DRAWER, a full multi-section WORKSPACE uses the real
+    edge. The page column is a `SectionStack` — it owns the between-section law (`gap: 32` +
+    a bare hairline separating one section from the next); the `Divider` NEVER goes directly
+    under the heading, which orphans the title from its own content. Inside a DRAWER, a full
+    multi-section WORKSPACE uses the real
     `SectionHeading` (lg) — its meta + CTA slots carry each section's count and action; a
     `Text size="sm" weight="semibold"` stand-in is only for small sub-groups. Do NOT wrap each section in its own `CardHeader`, do NOT
     hand-roll sm-semibold lead lines on a flat page. NEVER a bare eyebrow as a section title.
+  · **The heading ramp is FIXED — the markdown ladder, no size knobs.** `#` = xxl
+    (`RecordSummary` / `PageHeader` title) → `##` = xl (`SectionHeadingTitle`, always) →
+    `###` = lg (`SubsectionHeadingTitle`, always) → body sm. One outline on every surface;
+    never restyle a heading level per-page.
+  · **Subsection title** — the level BELOW a section on a long record surface: `Subsection` >
+    `SubsectionHeading` > `SubsectionHeadingTitle` (`###` lg semibold; siblings — a `Badge`, a
+    `SectionHeadingMeta`, an action — ride the heading row's right edge). Sibling subsections
+    stack in a `SubsectionStack` (24 + hairline between groups — no margins, no hand-rolled
+    dividers); a headingless `Subsection` is the section's lead group. Group leads INSIDE a
+    subsection's rows are `md medium` at most. Do NOT hand-roll `Text weight="semibold"` group
+    leads inside a section, and never promote a subsection to its own section-level heading
+    just to separate it.
   · **Eyebrow / label** (`<Text size="xs" color="muted" weight="medium">` — **sentence case, NEVER
     `transform="uppercase"`**): a small quiet label above or beside content — an artifact tag
     ("Proposed", "Question", "Suggested edit"), a field name, a metric caption, a minor one-line
@@ -1017,7 +1043,8 @@ recipe for a screen JOB; copy and adapt). Pick by the job:
 text ·
 markdown (Markdown — the single canonical markdown renderer for chat, apps, and `AgentRun`; rich on web via react-markdown/remark-gfm with copyable tables, plain-text on native; takes a markdown `children` string; import `@lotics/ui/markdown.css` once for styling) ·
 card (Card · CardHeader · CardHeaderTitle · CardHeaderMeta · CardBody · CardFooter) ·
-section_heading (Section · SectionHeading · SectionHeadingTitle · SectionHeadingMeta — the card-less twin of the Card family, compound, owns no margin; spacing via the Section gap, no body component. `SectionHeadingTitle` takes `weight` medium|semibold — default medium, `semibold` for dense surfaces (a side panel, a stacked group list) where medium blends into the body, matching `CardHeaderTitle`; + `info` for an ⓘ provenance popover after the title, same as `CardHeaderTitle.info`) · badge ·
+section_heading (Section · SectionHeading · SectionHeadingTitle · SectionHeadingMeta · Subsection · SubsectionHeading · SubsectionHeadingTitle — the card-less twin of the Card family, compound, owns no margin; spacing via the Section gap (12, fixed), no body component. `SectionHeadingTitle` is ALWAYS `##` (xl semibold; `weight="medium"` opt-down only) + `info` for an ⓘ provenance popover after the title, same as `CardHeaderTitle.info`. `SubsectionHeadingTitle` is the `###` lg-semibold level-3 title of a named group inside a section — heading-row siblings ride its right edge; the heading ramp is FIXED: # xxl / ## xl / ### lg, no size props) ·
+section_stack (SectionStack · SubsectionStack — divided stacks that own the between-block law: a fixed beat + hairline Divider BETWEEN blocks, skipping null children (56 for the flat page's Sections, 24 for a section's Subsections); stop hand-rolling gap + `<Divider />` pairs) · badge ·
 option_badge (OptionBadge — a select value as its configured colored badge) ·
 member_chip (MemberChip — avatar + name; the universal person render) ·
 member_select (MemberSelect — a Picker of MemberChip options; the member picker) ·

package/examples/tpl_allocate.tsx

@@ -67,7 +67,7 @@ export function TplAllocate() {
       <View style={{ width: "100%", maxWidth: 1000, alignSelf: "center", gap: 16 }}>
         {/* header */}
         <View style={{ gap: 2 }}>
-          <Text size="xl" weight="semibold">Apply payment</Text>
+          <Text size="xxl" weight="semibold">Apply payment</Text>
           <Text size="sm" color="muted">Split one received payment across the customer's open invoices — oldest first, or line by line</Text>
         </View>
 
@@ -76,7 +76,7 @@ export function TplAllocate() {
           <View style={{ padding: 20, flexDirection: "row", alignItems: "flex-start", gap: 24, flexWrap: "wrap" }}>
             <View style={{ gap: 2, flexGrow: 1, flexBasis: 220 }}>
               <Text size="xs" color="muted" weight="medium">Payment received</Text>
-              <Text size="xxl" weight="semibold" tabular>{formatMoney(PAYMENT.amount)}</Text>
+              <Text size="xxxl" weight="semibold" tabular>{formatMoney(PAYMENT.amount)}</Text>
               <Text size="sm" color="muted">{`${PAYMENT.from} · ref ${PAYMENT.ref} · ${PAYMENT.date}`}</Text>
             </View>
             <View style={{ gap: 10, flexGrow: 1, flexBasis: 300 }}>

package/examples/tpl_attendance.tsx

@@ -274,7 +274,7 @@ export function TplAttendance() {
         {/* header band */}
         <View style={{ flexDirection: "row", alignItems: "flex-end", gap: 12 }}>
           <View style={{ gap: 2, flex: 1 }}>
-            <Text size="xl" weight="semibold">Attendance</Text>
+            <Text size="xxl" weight="semibold">Attendance</Text>
             <Text size="sm" color="muted">Today, Friday 12/06 — in/out times for 9 employees</Text>
           </View>
           <Picker

package/examples/tpl_calendar.tsx

@@ -209,7 +209,7 @@ export function TplCalendar() {
         {/* header band */}
         <View style={{ flexDirection: "row", alignItems: "flex-end", gap: 12 }}>
           <View style={{ gap: 2, flex: 1 }}>
-            <Text size="xl" weight="semibold">Calendar & planning</Text>
+            <Text size="xxl" weight="semibold">Calendar & planning</Text>
             <Text size="sm" color="muted">This week — deliveries, reconciliations and customer visits</Text>
           </View>
           <Text size="sm" color="muted" tabular>

package/examples/tpl_dashboard.tsx

@@ -313,7 +313,7 @@ export function TplDashboard() {
             screen needs it) */}
         <View style={{ flexDirection: "row", alignItems: "flex-end", gap: 12 }}>
           <View style={{ gap: 2, flex: 1 }}>
-            <Text size="xl" weight="semibold">Executive dashboard</Text>
+            <Text size="xxl" weight="semibold">Executive dashboard</Text>
             <Text size="sm" color="muted">Revenue, the sales pipeline and what needs handling — refreshed every morning</Text>
           </View>
           <DateRangeFilterField value={period} onValueChange={setPeriod} locale="en-GB" labels={NHAN_BO_LOC} />

package/examples/tpl_documents.tsx

@@ -351,7 +351,7 @@ export function TplDocuments() {
     <ScrollView style={{ flex: 1, backgroundColor: colors.white }} contentContainerStyle={{ padding: 28, paddingBottom: 120 }}>
       <View style={{ maxWidth: 720, width: "100%", alignSelf: "center", gap: 24 }}>
         <View style={{ gap: 2 }}>
-          <Text size="xl" weight="semibold">PO-2481 — Nordic Furniture AB</Text>
+          <Text size="xxl" weight="semibold">PO-2481 — Nordic Furniture AB</Text>
           <Text size="sm" color="muted">Sea freight · Gothenburg → Ho Chi Minh City · FOB · ETD 18 Jul 2026</Text>
         </View>
 

package/examples/tpl_item_list.tsx

@@ -1212,7 +1212,7 @@ export function TplItemList() {
       <View style={{ width: "100%", maxWidth: 1040, alignSelf: "center", gap: 16 }}>
         {/* header — title only; the New case action lives on the toolbar row */}
         <View style={{ gap: 2 }}>
-          <Text size="xl" weight="semibold">Records</Text>
+          <Text size="xxl" weight="semibold">Records</Text>
           <Text size="sm" color="muted">Track each record's status and print the right document for its stage</Text>
         </View>
 

package/examples/tpl_lookup.tsx

@@ -255,7 +255,7 @@ export function TplLookup() {
                 <Text size="xs" color="muted" weight="medium" style={{ flex: 1 }}>Suggested HS code</Text>
                 <Confidence level={active.confidence} />
               </View>
-              <Text size="xxl" weight="semibold" tabular>{active.code}</Text>
+              <Text size="xxxl" weight="semibold" tabular>{active.code}</Text>
               <Text size="sm" color="muted">{active.heading}</Text>
             </View>
 

package/examples/tpl_pick.tsx

@@ -101,7 +101,7 @@ function CurrentTask({ line, index, total, onConfirm, onShort }: {
         {/* the bin is the biggest thing on screen — it's where you walk */}
         <View style={{ gap: 2 }}>
           <Text size="xs" color="muted" weight="medium">Go to bin</Text>
-          <Text size="xxl" weight="semibold" tabular>{line.bin}</Text>
+          <Text size="xxxl" weight="semibold" tabular>{line.bin}</Text>
         </View>
         <View style={{ flexDirection: "row", alignItems: "flex-end", gap: 16, flexWrap: "wrap" }}>
           <View style={{ gap: 2, flexGrow: 1, flexBasis: 200 }}>
@@ -110,7 +110,7 @@ function CurrentTask({ line, index, total, onConfirm, onShort }: {
           </View>
           <View style={{ flexDirection: "row", alignItems: "baseline", gap: 8 }}>
             <Text size="sm" color="muted">Pick</Text>
-            <Text size="xl" weight="semibold" tabular>{line.qty}</Text>
+            <Text size="xxl" weight="semibold" tabular>{line.qty}</Text>
             <Text size="sm" color="muted">units</Text>
           </View>
         </View>
@@ -199,7 +199,7 @@ export function TplPick() {
         {/* header — the wave + the cart it's filling */}
         <View style={{ flexDirection: "row", alignItems: "flex-end", gap: 12, flexWrap: "wrap" }}>
           <View style={{ gap: 2, flex: 1 }}>
-            <Text size="xl" weight="semibold">Queue W-0142</Text>
+            <Text size="xxl" weight="semibold">Queue W-0142</Text>
             <Text size="sm" color="muted">7 lines for 3 outbound orders · Cart C-07</Text>
           </View>
           <Button title="Pause wave" color="muted" onPress={() => {}} />

package/examples/tpl_pivot.tsx

@@ -128,7 +128,7 @@ export function TplPivot() {
     <ScrollView style={{ flex: 1, backgroundColor: colors.white }} contentContainerStyle={{ padding: 28 }}>
       <View style={{ width: "100%", maxWidth: 960, alignSelf: "center", gap: 16 }}>
         <View style={{ gap: 2 }}>
-          <Text size="xl" weight="semibold">Stock distribution</Text>
+          <Text size="xxl" weight="semibold">Stock distribution</Text>
           <Text size="sm" color="muted">Where each category sits across the network — press a cell to list what's behind it</Text>
         </View>
 

package/examples/tpl_record.tsx

@@ -12,7 +12,8 @@ import type { PickerOption } from "@lotics/ui/picker";
 import { Combobox, ComboboxInput, ComboboxContent } from "@lotics/ui/combobox";
 import { DetailRow, DetailTable } from "@lotics/ui/detail_row";
 import { Callout, CalloutText } from "@lotics/ui/callout";
-import { Section, SectionHeading, SectionHeadingMeta, SectionHeadingTitle } from "@lotics/ui/section_heading";
+import { Section, SectionHeading, SectionHeadingMeta, SectionHeadingTitle, Subsection, SubsectionHeading, SubsectionHeadingTitle } from "@lotics/ui/section_heading";
+import { SectionStack, SubsectionStack } from "@lotics/ui/section_stack";
 import { MenuButton } from "@lotics/ui/menu_button";
 import { Modal, ModalBody, ModalHeader } from "@lotics/ui/modal";
 import { useSectionNav } from "@lotics/ui/use_section_nav";
@@ -653,7 +654,12 @@ export function TplRecord() {
         </View>
       )}
     <ScrollView ref={nav.scrollRef} onScroll={nav.onScroll} scrollEventThrottle={16} style={{ flex: 1 }} contentContainerStyle={{ padding: 28, paddingBottom: 96 }}>
-      <View style={{ width: "100%", maxWidth: 720, alignSelf: "center", gap: 32 }}>
+      {/* the page column is a SectionStack — it owns the 56px beat + the
+          hairline BETWEEN top-level blocks (a conditional block that renders
+          null never leaves a stray divider) */}
+      <SectionStack style={{ width: "100%", maxWidth: 720, alignSelf: "center" }}>
+        {/* header band — app bar + summary + key facts read as ONE block */}
+        <View style={{ gap: 32 }}>
         {/* app bar — CREATE is one click; the surface is where everything is refined */}
         <View style={{ flexDirection: "row", alignItems: "center", flexWrap: "wrap", columnGap: 10, rowGap: 8 }}>
           <Text size="sm" color="muted">Records <Text size="sm" color="muted">/</Text> <Text size="sm" weight="medium" color="default" tabular>{code}</Text></Text>
@@ -691,8 +697,7 @@ export function TplRecord() {
             <InlineSelect value={terms} options={TERMS} onSave={persist(setTerms)} accessibilityLabel="Payment terms" />
           </DetailRow>
         </DetailTable>
-
-        <Divider />
+        </View>
 
         {/* ONE DetailTable = the record's field grid: label · editor · trailing
             columns set once on the parent, every row aligned like a table —
@@ -743,8 +748,6 @@ export function TplRecord() {
         </Section>
         </View>
 
-        <Divider />
-
         {/* CUSTOMER — TWO states, no swap mode. Attached: the read-only-first
             card (identity + editable fields — Tax ID with the registry Fetch
             that fills Contact + City, which are inline-editable too); Remove
@@ -857,8 +860,6 @@ export function TplRecord() {
         </Section>
         </View>
 
-        <Divider />
-
         {/* BILLING — invoice documents on the record, in the inline vocabulary.
             The issue action lives in each band's header; ONE section-level
             callout explains what blocks issuing (no per-band totals, no
@@ -884,6 +885,9 @@ export function TplRecord() {
             </Callout>
           ) : null}
 
+          {/* the section's GROUPS — bands · collect · deposit — divide via the
+              SubsectionStack law (24 + hairline), no hand-rolled dividers */}
+          <SubsectionStack>
           <View style={{ gap: 10 }}>
             {invoices.map((inv) => (
               <InvoiceBand
@@ -905,9 +909,8 @@ export function TplRecord() {
             ))}
           </View>
 
-          {/* collect band */}
-          <Divider />
-          <View style={{ gap: 10 }}>
+          {/* collect band — a headingless Subsection: the total owns the number */}
+          <Subsection>
             <View style={{ flexDirection: "row", alignItems: "center", gap: 8 }}>
               <Text weight="semibold" style={{ flex: 1 }}>Total to collect</Text>
               <Text weight="semibold" size="lg" tabular>{formatMoney(grandTotal)}</Text>
@@ -923,15 +926,15 @@ export function TplRecord() {
               <Text size="xs" color="muted" style={{ flex: 1 }}>{issuedCount} of {invoices.length} issued</Text>
               <Button title="Print receipt" color="primary" disabled={grandTotal <= 0} onPress={printReceipt} />
             </View>
-          </View>
+          </Subsection>
 
-          {/* deposit band — labelled separate, never part of the total */}
-          <Divider />
-          <View style={{ gap: 8 }}>
-            <View style={{ flexDirection: "row", alignItems: "center", gap: 8 }}>
-              <Text weight="semibold">Deposit</Text>
+          {/* deposit band — a named Subsection: labelled separate, never part
+              of the total (the badge rides the heading row's right edge) */}
+          <Subsection>
+            <SubsectionHeading>
+              <SubsectionHeadingTitle>Deposit</SubsectionHeadingTitle>
               <Badge label="Collected separately" color="zinc" />
-            </View>
+            </SubsectionHeading>
             <View style={{ flexDirection: "row", alignItems: "center", gap: 12, flexWrap: "wrap", minHeight: 40 }}>
               <Text size="sm" color="muted" style={{ width: 150 }}>Refundable</Text>
               <View style={{ flexGrow: 1, flexBasis: 160 }}>
@@ -951,12 +954,11 @@ export function TplRecord() {
                 onPress={() => Alert.alert("Deposit receipt", `Printing deposit receipt for ${formatMoney(deposit)}.`, [{ text: "OK" }])}
               />
             </View>
-          </View>
+          </Subsection>
+          </SubsectionStack>
         </Section>
         </View>
 
-        <Divider />
-
         {/* FILES — the record's document CRUD: drop to add, click a thumbnail
             to preview in the gallery, ✕ to delete. */}
         <View onLayout={nav.register("files")}>
@@ -996,8 +998,6 @@ export function TplRecord() {
         </Section>
         </View>
 
-        <Divider />
-
         {/* TASKS — the handoff checklist, grouped by the desk that owns
             them; every row edits (the stage gates the handoff and Billing,
             never task editing). The CURRENT desk's open tasks warn beside
@@ -1159,8 +1159,6 @@ export function TplRecord() {
         </Section>
         </View>
 
-        <Divider />
-
         {/* THE HANDOFF GATE — the atomic boundary between departments, not a
             form and not a message: the record itself changes desks. Each stage
             names what it owes (the why-hint) before its CTA un-gates; the
@@ -1191,8 +1189,6 @@ export function TplRecord() {
           </View>
         )}
 
-        <Divider />
-
         {/* the settings shape: title + description left, a live control right,
             applied on change */}
         <View onLayout={nav.register("preferences")}>
@@ -1217,15 +1213,13 @@ export function TplRecord() {
         </Section>
         </View>
 
-        <Divider />
-
         <DangerZone
           title="Delete record"
           description="Permanently remove this record and its invoices, charges, and history. This can't be undone."
         >
           <Button title="Delete record" color="danger" onPress={() => {}} />
         </DangerZone>
-      </View>
+      </SectionStack>
 
       {/* the narrow-mode section picker — a full-page takeover: pick a section
           to jump there; Escape or the close control dismisses */}

package/examples/tpl_report.tsx

@@ -222,7 +222,7 @@ export function TplReport() {
         {/* header band — title + the persistent period + the one primary action */}
         <View style={{ flexDirection: "row", gap: 16, alignItems: "flex-start", flexWrap: "wrap", zIndex: 20 }}>
           <View style={{ gap: 2, flex: 1, minWidth: 260 }}>
-            <Text size="xl" weight="semibold">Payments</Text>
+            <Text size="xxl" weight="semibold">Payments</Text>
             <Text size="sm" color="muted">Look up payments by customer, reference, or operator across a period — totals, facets, and the matching lines</Text>
           </View>
           <View style={{ flexDirection: "row", gap: 12, alignItems: "center", flexWrap: "wrap" }}>

package/examples/tpl_rollup.tsx

@@ -147,7 +147,7 @@ export function TplRollup() {
       <View style={{ width: "100%", maxWidth: 980, alignSelf: "center", gap: 16 }}>
         {/* header band */}
         <View style={{ gap: 2 }}>
-          <Text size="xl" weight="semibold">Network rollup</Text>
+          <Text size="xxl" weight="semibold">Network rollup</Text>
           <Text size="sm" color="muted">This month by region, site and lane — expand the branch that drags the total</Text>
         </View>
 

package/examples/tpl_shifts.tsx

@@ -185,7 +185,7 @@ export function TplShifts() {
       <View style={{ width: "100%", maxWidth: 1100, alignSelf: "center", gap: 16 }}>
         {/* header band */}
         <View style={{ gap: 2 }}>
-          <Text size="xl" weight="semibold">Shift staffing · week 15–21/06</Text>
+          <Text size="xxl" weight="semibold">Shift staffing · week 15–21/06</Text>
           <Text size="sm" color="muted">Members sign up, you allocate — fill every slot without burning anyone out</Text>
         </View>
 

package/examples/tpl_statements.tsx

@@ -119,7 +119,7 @@ function StatementPage({ title, meta, children }: { title: string; meta: string;
       <View style={{ width: "100%", maxWidth: 680, alignSelf: "center", gap: 20 }}>
         <View style={{ flexDirection: "row", alignItems: "flex-start", flexWrap: "wrap", columnGap: 12, rowGap: 8 }}>
           <View style={{ flexGrow: 1, flexBasis: 240, gap: 2 }}>
-            <Text size="xl" weight="semibold">{title}</Text>
+            <Text size="xxl" weight="semibold">{title}</Text>
             <Text size="sm" color="muted">{meta}</Text>
           </View>
           <Button title="Export" color="secondary" icon="file-down" onPress={() => {}} />

package/examples/tpl_stock.tsx

@@ -193,7 +193,7 @@ export function TplStock() {
         {/* header band */}
         <View style={{ flexDirection: "row", alignItems: "flex-end", gap: 12 }}>
           <View style={{ gap: 2, flex: 1 }}>
-            <Text size="xl" weight="semibold">Stock overview</Text>
+            <Text size="xxl" weight="semibold">Stock overview</Text>
             <Text size="sm" color="muted">The whole fleet at a glance — drill into any slice, then walk the units one by one</Text>
           </View>
           <Button title="Register units" color="primary" onPress={() => {}} />

package/examples/tpl_task_board.tsx

@@ -328,7 +328,7 @@ export function TplTaskBoard() {
     <>
     <ScrollView style={{ flex: 1, backgroundColor: colors.white }} contentContainerStyle={{ paddingVertical: 28, paddingHorizontal: 24, paddingBottom: 96 }}>
       <View style={{ maxWidth: 1240, width: "100%", alignSelf: "center", gap: 16 }}>
-        <Text size="xl" weight="semibold">Task board</Text>
+        <Text size="xxl" weight="semibold">Task board</Text>
 
         <View style={{ flexDirection: "row", alignItems: "center", gap: 8 }}>
           <View style={{ flexDirection: "row", flexWrap: "wrap", alignItems: "center", gap: 8, flex: 1 }}>

package/examples/tpl_tasks.tsx

@@ -235,7 +235,7 @@ export function TplTasks() {
     <>
     <ScrollView style={{ flex: 1, backgroundColor: colors.white }} contentContainerStyle={{ paddingVertical: 28, paddingHorizontal: 20, paddingBottom: 96 }}>
       <View style={{ maxWidth: 680, width: "100%", alignSelf: "center", gap: 14 }}>
-        <Text size="xl" weight="semibold">Tasks</Text>
+        <Text size="xxl" weight="semibold">Tasks</Text>
 
         <View style={{ flexDirection: "row", alignItems: "center", gap: 8 }}>
           <View style={{ flexDirection: "row", flexWrap: "wrap", alignItems: "center", gap: 8, flex: 1 }}>

package/examples/tpl_tower.tsx

@@ -166,7 +166,7 @@ export function TplTower() {
       <View style={{ width: "100%", maxWidth: 1100, alignSelf: "center", gap: 16 }}>
         {/* header band */}
         <View style={{ gap: 2 }}>
-          <Text size="xl" weight="semibold">Control tower</Text>
+          <Text size="xxl" weight="semibold">Control tower</Text>
           <Text size="sm" color="muted">Every unit's live state — scan for red, work the exceptions, read the pattern</Text>
         </View>
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@lotics/ui",
-  "version": "10.0.0",
+  "version": "11.0.0",
   "type": "module",
   "exports": {
     "./tokens": "./src/tokens.ts",
@@ -173,6 +173,7 @@
     "./list_item": "./src/list_item.tsx",
     "./section": "./src/section.tsx",
     "./section_heading": "./src/section_heading.tsx",
+    "./section_stack": "./src/section_stack.tsx",
     "./separator": "./src/separator.tsx",
     "./stack": "./src/stack.tsx",
     "./status_badge": "./src/status_badge.tsx",

package/src/button.tsx

@@ -151,6 +151,10 @@ export function Button(props: ButtonProps) {
 
 
 export function getButtonTextColor(color?: ButtonColor, disabled?: boolean): TextColor {
+  // Disabled fades the label to the zinc-400 disabled ink on EVERY variant —
+  // the washed background alone is a one-step tint nobody reads as disabled.
+  // (The primary keeps inverted ink; its zinc-300 surface carries the wash.)
+  if (disabled) return color === "primary" ? "inverted" : "zinc-400";
   switch (color) {
     case "primary":
       return "inverted";
@@ -162,7 +166,7 @@ export function getButtonTextColor(color?: ButtonColor, disabled?: boolean): Tex
     case "muted":
       return "muted";
     default:
-      return disabled ? "muted" : "default";
+      return "default";
   }
 }
 

package/src/button_colors.ts

@@ -6,6 +6,9 @@ import { colors } from "./colors";
  *  same colour. Lives in its own module (not `button.tsx`) so a test that mocks
  *  `@lotics/ui/button` can't leave `IconButton` without it. */
 export function getButtonIconColor(color?: ButtonColor, disabled?: boolean): string {
+  // Disabled mutes the glyph on EVERY variant (mirrors `getButtonTextColor`) —
+  // the primary keeps white ink on its washed zinc-300 disabled surface.
+  if (disabled) return color === "primary" ? colors.white : colors.zinc["400"];
   switch (color) {
     case "primary":
       return colors.white;
@@ -18,6 +21,6 @@ export function getButtonIconColor(color?: ButtonColor, disabled?: boolean): str
     case "muted":
       return colors.zinc["600"];
     default:
-      return disabled ? colors.zinc["300"] : colors.zinc["950"];
+      return colors.zinc["950"];
   }
 }

package/src/page_content.tsx

@@ -84,7 +84,7 @@ export function PageContent(props: PageContentProps) {
             }}
           >
             {!!title && (
-              <Text size="xl" weight="semibold">
+              <Text size="xxl" weight="semibold">
                 {title}
               </Text>
             )}

package/src/page_header.tsx

@@ -22,12 +22,12 @@ export function PageHeader(props: PageHeaderProps) {
             {left}
             {right}
           </View>
-          <Text size="xl" weight="semibold">
+          <Text size="xxl" weight="semibold">
             {title}
           </Text>
         </>
       ) : (
-        <Text size="xl" weight="semibold">
+        <Text size="xxl" weight="semibold">
           {title}
         </Text>
       )}

package/src/record_summary.tsx

@@ -47,7 +47,9 @@ export function RecordSummary(props: RecordSummaryProps) {
     <View style={styles.identityRow}>
         <View style={styles.identity}>
           <View style={styles.titleRow}>
-            <Text size="xl" weight="semibold" tabular level={level}>
+            {/* xxl — the `#` of the heading ramp (# xxl → ## xl section →
+                ### lg subsection); the identity always tops the outline */}
+            <Text size="xxl" weight="semibold" tabular level={level}>
               {title}
             </Text>
             {status ?? null}

package/src/ring_gauge.tsx

@@ -53,7 +53,7 @@ export function RingGauge(props: RingGaugeProps) {
             transform={`rotate(-90 ${center} ${center})`}
           />
         </svg>
-        <Text size="xxl" weight="semibold">
+        <Text size="xxxl" weight="semibold">
           {Math.round(clamped)}%
         </Text>
       </View>

package/src/section_heading.tsx

@@ -38,13 +38,72 @@ export interface SectionProps {
  */
 export function Section(props: SectionProps) {
   // gap 12 spaces the heading from its body. Space BETWEEN sections belongs to
-  // the page column: flat record/form pages use `gap: 32` on the content column
-  // with a bare `Divider` BETWEEN sections (never under the heading — the
-  // heading belongs to its content; the hairline separates it from the LAST
-  // section).
+  // the page column (`SectionStack`, 56 + hairline); a body of `Subsection`
+  // groups divides via a nested `SubsectionStack` (24 + hairline) —
+  // never a hairline directly under the heading (it belongs to its content).
   return <View style={[{ gap: 12 }, props.style]}>{props.children}</View>;
 }
 
+export interface SubsectionProps {
+  children: React.ReactNode;
+  style?: StyleProp<ViewStyle>;
+}
+
+/**
+ * One named group INSIDE a `Section` — the level below `Section` on a long
+ * record surface (`###` in the heading ramp). Compose a `SubsectionHeading`
+ * then the group's rows; sibling subsections stack in a `SubsectionStack`
+ * (24 + hairline between groups — no margins, no hand-rolled dividers). A
+ * headingless `Subsection` is fine for the section's lead group.
+ *
+ *   <Section>
+ *     <SectionHeading><SectionHeadingTitle>Delivery</SectionHeadingTitle></SectionHeading>
+ *     <SubsectionStack>
+ *       <Subsection>{lead rows}</Subsection>
+ *       <Subsection>
+ *         <SubsectionHeading><SubsectionHeadingTitle>Carrier</SubsectionHeadingTitle></SubsectionHeading>
+ *         {rows}
+ *       </Subsection>
+ *     </SubsectionStack>
+ *   </Section>
+ */
+export function Subsection(props: SubsectionProps) {
+  return <View style={[{ gap: 12 }, props.style]}>{props.children}</View>;
+}
+
+export interface SubsectionHeadingProps {
+  children: React.ReactNode;
+  style?: StyleProp<ViewStyle>;
+}
+
+export function SubsectionHeading(props: SubsectionHeadingProps) {
+  return (
+    <View style={[{ flexDirection: "row", alignItems: "center", gap: 10 }, props.style]}>
+      {props.children}
+    </View>
+  );
+}
+
+export interface SubsectionHeadingTitleProps {
+  children: React.ReactNode;
+  /** Heading rank. Defaults to 3 — one level under `SectionHeadingTitle`'s 2. */
+  level?: HeadingLevel;
+}
+
+/** 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. */
+export function SubsectionHeadingTitle(props: SubsectionHeadingTitleProps) {
+  const { children, level = 3 } = props;
+  return (
+    <View style={{ flex: 1 }}>
+      <Text level={level} size="lg" weight="semibold">
+        {children}
+      </Text>
+    </View>
+  );
+}
+
 export interface SectionHeadingProps {
   children: React.ReactNode;
   style?: StyleProp<ViewStyle>;
@@ -73,16 +132,18 @@ export interface SectionHeadingTitleProps {
   info?: string;
 }
 
-/** The title block — lg semibold (a section must announce itself; md blends
- * into control labels) + an optional muted `description` line. Grows to push
- * any sibling actions to the right edge. */
+/** 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. */
 export function SectionHeadingTitle(props: SectionHeadingTitleProps) {
   const { children, description, icon, level = 2, weight = "semibold", info } = props;
   return (
     <View style={{ flex: 1, gap: 2 }}>
       <View style={{ flexDirection: "row", alignItems: "center", gap: 6 }}>
-        {icon ? <Icon name={icon} size={18} /> : null}
-        <Text level={level} weight={weight} size="lg">
+        {icon ? <Icon name={icon} size={20} /> : null}
+        <Text level={level} weight={weight} size="xl">
           {children}
         </Text>
         {info ? <InfoPopover text={info} accessibilityLabel={useLoticsLocale().sectionHeading.info} /> : null}

package/src/section_stack.tsx

@@ -0,0 +1,67 @@
+import { Children, Fragment } from "react";
+import { View, type StyleProp, type ViewStyle } from "react-native";
+import { Divider } from "./divider";
+
+interface StackProps {
+  children: React.ReactNode;
+  /** Hairline between blocks (default true). Turn off for a short surface
+   *  where the beat alone is enough. */
+  divided?: boolean;
+  style?: StyleProp<ViewStyle>;
+}
+
+/** Interleave a hairline between the non-null blocks of a gap column. */
+function DividedStack({ children, divided = true, gap, style }: StackProps & { gap: number }) {
+  const blocks = Children.toArray(children); // drops null/undefined/false
+  return (
+    <View style={[{ gap }, style]}>
+      {blocks.map((block, i) => (
+        // Children.toArray keys are stable for conditional lists; the fragment
+        // pairs each block with the hairline that separates it from the last.
+        <Fragment key={`sec_${i}`}>
+          {divided && i > 0 ? <Divider /> : null}
+          {block}
+        </Fragment>
+      ))}
+    </View>
+  );
+}
+
+export type SectionStackProps = StackProps;
+
+/**
+ * The content column of a flat record/form page — it OWNS the between-section
+ * law: a fixed 56px beat with a hairline `Divider` between top-level blocks
+ * (never under a heading; the hairline separates a block from the PREVIOUS
+ * one). Null/false children are skipped, so a conditional section never
+ * leaves a stray hairline. No knobs — every flat page shares one rhythm.
+ *
+ *   <SectionStack>
+ *     {headerBand}
+ *     <Section>…</Section>
+ *     {canTransfer ? <Section>…</Section> : null}
+ *   </SectionStack>
+ */
+export function SectionStack(props: SectionStackProps) {
+  return <DividedStack {...props} gap={56} />;
+}
+
+export type SubsectionStackProps = StackProps;
+
+/**
+ * The divided stack of `Subsection` groups INSIDE a `Section` — the same
+ * hairline law one step tighter: a fixed 24px beat. Compose it as the
+ * section's body (after the `SectionHeading`); a section's groups divide
+ * without hand-rolled gaps or dividers.
+ *
+ *   <Section>
+ *     <SectionHeading><SectionHeadingTitle>Delivery</SectionHeadingTitle></SectionHeading>
+ *     <SubsectionStack>
+ *       <Subsection>{lead rows}</Subsection>
+ *       {carrier ? <Subsection>…</Subsection> : null}
+ *     </SubsectionStack>
+ *   </Section>
+ */
+export function SubsectionStack(props: SubsectionStackProps) {
+  return <DividedStack {...props} gap={24} />;
+}

package/src/text.css

@@ -31,12 +31,19 @@
   line-height: 24px;
   letter-spacing: -0.005em;
 }
+/* Display ramp — the heading ladder: xl = `##` (section), xxl = `#`
+   (page/record title), xxxl = hero numbers. */
 [data-text-size="xl"] {
+  font-size: 22px;
+  line-height: 28px;
+  letter-spacing: -0.01em;
+}
+[data-text-size="xxl"] {
   font-size: 28px;
   line-height: 34px;
   letter-spacing: -0.015em;
 }
-[data-text-size="xxl"] {
+[data-text-size="xxxl"] {
   font-size: 32px;
   line-height: 38px;
   letter-spacing: -0.02em;
@@ -61,10 +68,14 @@
     line-height: 28px;
   }
   [data-text-size="xl"] {
+    font-size: 24px;
+    line-height: 32px;
+  }
+  [data-text-size="xxl"] {
     font-size: 32px;
     line-height: 44px;
   }
-  [data-text-size="xxl"] {
+  [data-text-size="xxxl"] {
     font-size: 48px;
     line-height: 52px;
   }

package/src/text.tsx

@@ -50,7 +50,7 @@ export interface TextProps {
 
 export type HeadingLevel = 1 | 2 | 3 | 4 | 5 | 6;
 
-export type TextSize = "xs" | "sm" | "md" | "lg" | "xl" | "xxl";
+export type TextSize = "xs" | "sm" | "md" | "lg" | "xl" | "xxl" | "xxxl";
 type TextAlign = "left" | "right" | "center";
 type TextDecorationLine = "underline" | "lineThrough" | "underline lineThrough";
 type TextWeight = "regular" | "medium" | "semibold";
@@ -146,11 +146,17 @@ const styles = StyleSheet.create({
     fontSize: 18,
     lineHeight: 30,
   },
+  // Display ramp — the heading ladder: xl = `##` (section), xxl = `#`
+  // (page/record title), xxxl = hero numbers.
   xl: {
+    fontSize: 22,
+    lineHeight: 28,
+  },
+  xxl: {
     fontSize: 28,
     lineHeight: 34,
   },
-  xxl: {
+  xxxl: {
     fontSize: 32,
     lineHeight: 38,
   },

package/src/text_utils.ts

@@ -10,7 +10,8 @@ export type TextColor =
   | "success"
   | "zinc-900"
   | "zinc-700"
-  | "zinc-500";
+  | "zinc-500"
+  | "zinc-400";
 
 export function getTextColor(color?: TextColor): string {
   switch (color) {
@@ -24,6 +25,10 @@ export function getTextColor(color?: TextColor): string {
       return colors.zinc["700"];
     case "zinc-500":
       return colors.zinc["500"];
+    // The disabled ink — light enough that a control reads inert at a glance
+    // (muted/600 still reads as body ink on a zinc-50 chip).
+    case "zinc-400":
+      return colors.zinc["400"];
     case "inverted":
       return colors.white;
     // Valence set — the lightest status weight: a state WORD whose meaning is in