@lotics/ui 35.0.0 → 37.0.0

package/MIGRATION.md

@@ -4,6 +4,87 @@ Breaking changes, newest first — normally per major, plus the rare minor that
 anyway (recorded under its exact version). The current contract lives in `AGENTS.md` + `docs/`;
 this file exists only to move an app from one release to the next.
 
+## 37.0.0 — `PageContent`'s side gutter is a token, and responsive
+
+`PageContent` padded `16` at every width. It now uses `pagePad` from
+`@lotics/ui/spacing` — **16 on a phone, 32 wider**. Nothing to pass; the only visible
+change is that a wide page breathes where it used to sit 16px off the chrome.
+
+```ts
+import { pagePad } from "@lotics/ui/spacing";
+pagePad(small); // SPACE.md | SPACE.xl
+```
+
+**Why a token rather than a prop.** A screen that cannot use this shell — one with a
+rail, a side panel, or a scroller it must hold a ref to — still has to land on the
+same left edge, and a list and the record it opens are one reading column seen twice:
+a gutter that differs between them slides the content sideways as the reader crosses.
+Left to each app this lands on hand-picked numbers; the case that prompted this had
+14 and 28, one of them not even a multiple of 4, against a scale whose own doc says
+that reads as broken.
+
+It is also COUPLED to `ROW_WASH_BLEED`: a register row bleeds its wash outward to
+`pagePad − ROW_WASH_BLEED`. Two numbers that must be read together should not live in
+two repositories.
+
+**If you hand-roll a page shell, import `pagePad` instead of choosing.** And check
+whether `PageContent` would do — it carries the centred `maxWidth` column and the
+title band most screens re-type by hand.
+
+## 36.0.0 — seven components stopped announcing English; their strings moved to the pack
+
+**Nothing to change if you pass a shipped pack** (`en` / `vi`) — both carry every
+new entry, and no component API changed. A HAND-BUILT pack must add them:
+
+```ts
+commentsButton: { comment: "bình luận", comments: "bình luận",
+                  withSubject: (counted, subject) => `${counted} về ${subject}` },
+infoPopover:    { more: "Thông tin thêm", about: (label) => `Thông tin về ${label}` },
+fileRow:        { open: (name) => `Mở ${name}` },
+sources:        { open: (label) => `Mở ${label}`, heading: "Nguồn" },
+counter:        { decrease: (label) => `Giảm ${label}`, increase: (label) => `Tăng ${label}` },
+allocationRow:  { allocateTo: (label) => `Phân bổ vào ${label}`,
+                  due: (amount) => `còn ${amount}`, clear: "Xoá", full: "Toàn bộ" },
+columnFilter:   { min: (label) => `${label} tối thiểu`, max: (label) => `${label} tối đa` },
+```
+
+**Why.** These components built user-facing strings by concatenating an English
+word onto caller data — `Open ${name}`, `About ${label}`, `${label} min`,
+`${amount} due` — with no locale lookup at all. Most were accessible names, so a
+Vietnamese app announced "Open hop_dong.pdf" to the one user who cannot see the
+screen and has only the announcement; `Sources`' eyebrow and `AllocationRow`'s
+caption and buttons were visibly English too.
+
+`CommentsButton` is the same defect one step further along: it composed
+`3 comments · Northwind`, and a middot is the one part of a string a screen reader
+drops, so the mark carrying the relation never survived being read aloud.
+
+**Every interpolated entry is a FUNCTION, not a word plus concatenation**, because
+the added word sits in a different PLACE in different languages — `5,000,000 due`
+against `còn 5.000.000`. A pack supplying only vocabulary would still be stuck with
+English order. This is how every other interpolated string in a pack already works
+(`sortHeader.sortBy`, `ledger.rowDetails`, `pagination.rangeWithTotal`).
+
+Required rather than optional on purpose: both shipped packs are compile-forced
+complete, and that is the mechanism that catches an untranslated string before it
+ships.
+
+`Checklist`'s phase toggle also lost a middot and needs nothing from you — its name
+is now `Show Picking` rather than `Show · Picking`, verb then object.
+
+### `PressableHighlight` now sets `accessibilityRole="button"` itself
+
+Nothing to pass; an explicit `accessibilityRole` still wins. Surfaces built on it
+that never declared a role now announce as buttons and take a tab stop, which is
+what the component always claimed to be — the docblock says "it IS a button", and
+that is the whole reason its children must be non-interactive while `PressableRow`
+stays role-less. In this package 18 of 35 call sites passed the role by hand and
+every one passed `"button"`; the other 17 rendered a surface a screen reader could
+name but not identify as pressable.
+
+If a surface of yours is genuinely not a button, say so (`accessibilityRole="link"`,
+…) — or reach for `PressableRow`, which carries no role by design.
+
 ## 35.0.0 — `FilterChip` has no Clear footer; the × is the clear
 
 `FilterChip` no longer renders a Clear button in its popover footer. **Nothing to

package/docs/catalog.md

@@ -418,7 +418,13 @@ source (`src/<module>.tsx`/`.ts`) is the API reference.
   scales and `getCssVariables()` — an OPT-IN serializer to `--lotics-*` CSS variables for
   hand-rolled plain DOM/CSS (nothing injects them automatically; `@lotics/ui` components
   don't need them).
-- **`spacing`** — the `SPACE` scale + `SpaceToken`.
+- **`spacing`** — the `SPACE` scale + `SpaceToken`, and **`pagePad(small)`** — the page's
+  side gutter (`SPACE.md` on a phone, `SPACE.xl` wider). `PageContent` applies it; a screen
+  that cannot use that shell — one with a rail, a side panel or its own scroller — imports it
+  rather than picking a number, because a list and the record it opens are one reading column
+  seen twice and must not shift sideways between them. It is also COUPLED to `ROW_WASH_BLEED`:
+  a register row bleeds its wash outward to `pagePad − ROW_WASH_BLEED`, so the two are read
+  together and neither belongs to the app.
 - **`control_surface`** — `CONTROL_HEIGHT` (40), `CONTROL_CONTENT_HEIGHT` (28 — the tallest
   FIXED-height node a 40px band seats, 6 per side of air; what `InlineButton` and a `md`
   `IconButton` already used, now named so an avatar or any other child lands on it too. Text
@@ -513,7 +519,13 @@ source (`src/<module>.tsx`/`.ts`) is the API reference.
   `CONTAINER_SIZES`).
 - **`page_header`** — `PageHeader`: the page's title band; `actions` puts page-level CTAs on the title row (right-aligned), while `left`/`right` form a separate nav row above.
 - **`page_content`** — `PageContent` + `PAGE_SIZES`: the page's padded, width-capped content
-  region.
+  region — a centred column with optional `title`/`titleRight`/`description`, `header`/`footer`
+  slots and `fullscreen`. **Reach for it before hand-rolling a screen shell**: a scroller, a
+  centred `maxWidth` column and a title band re-typed per screen is how two pages of one app end
+  up on different gutters. Its side padding is `pagePad` (`@lotics/ui/spacing`), so a screen that
+  genuinely cannot use it — one with a rail, a side panel, or a scroller it must hold a ref to —
+  still lands on the same edge by importing that token. It OWNS its `ScrollView` and exposes no
+  scroll props, which is the real limit on adoption.
 - **`accordion`** — `Accordion` + `AccordionHeader`/`AccordionTitle`/`AccordionMeta`:
   expandable section rows.
 - **`tabs`** — `Tabs`: switch between content sections; WAI-ARIA tablist + roving tabindex;
@@ -555,8 +567,11 @@ source (`src/<module>.tsx`/`.ts`) is the API reference.
   aims at, and splitting them leaves half the affordance dead under the pointer. FULL INK, unlike
   the muted values around it — everything else on a row is a fact ABOUT the record, this is people
   talking about it and the one thing there that can be UNREAD. `subject` reaches the accessible
-  NAME only ("3 comments · Northwind Packaging" is a destination; "3 comments" on the fortieth row
-  is not) — never the visible label, which would spend row width restating whose record it is.
+  NAME only ("3 comments on Northwind Packaging" is a destination; "3 comments" on the fortieth row
+  is not) — never the visible label, which would spend row width restating whose record it is. The
+  pack's `commentsButton.withSubject` builds that phrase, so the word ORDER is the pack's to choose
+  and the join is a WORD: this string exists to be read aloud, and a screen reader drops
+  punctuation along with the relation it was carrying.
   **Render it only when `count > 0`** — a zero on every quiet row is a column of noise that trains
   the eye to skip exactly where the signal will appear. Pair it with a jump that LANDS on the
   thread (`tpl_item_list` opens the record's drawer on its comments section), because a count the
@@ -634,7 +649,12 @@ source (`src/<module>.tsx`/`.ts`) is the API reference.
   designing a pressable surface it doesn't cover.
 - **`pressable_highlight`** — `PressableHighlight`: the hover-wash + keyboard-focus-ring
   `Pressable` under `MenuButton`/`Switcher`/custom pressable surfaces; its style-fn/children
-  receive `hovered` + `focusVisible`.
+  receive `hovered` + `focusVisible`. It announces as `role="button"` by DEFAULT (pass
+  `accessibilityRole` to override), and that role is the line between it and
+  **`PressableRow`**, which stays role-less and out of the tab order: a button may not
+  contain interactive descendants, so a row carrying its own CTA / ⋯ / checkbox is a
+  `PressableRow` with the body as its door, never this. Give it an `accessibilityLabel` —
+  a button whose whole content is an icon or a chip announces as nothing otherwise.
 - **`focus_ring_pressable`** — `FocusRingPressable`: a Pressable that rings on keyboard
   focus; the raw-control default.
 - **`card_select_item`** — `CardSelectItem`: a bordered, card-shaped button; `selected` =

package/examples/tpl_record.tsx

@@ -2131,10 +2131,15 @@ export function TplRecord({ chrome = "page", code = "RC-2026-0418", openSection
                 "the Harbor Freight order", never "RC-2026-0418" — the code is how
                 the SYSTEM refers to the record, which makes it a supporting value.
                 The register's identity cell makes the same trade, so the two
-                surfaces name a record the same way. */}
+                surfaces name a record the same way.
+
+                A COMMA joins them, never a middot — two identifying facts read as
+                a list, and the kit bans the glyph outright (composition.md
+                §Microcopy): it claims a relation while refusing to name it, and a
+                screen reader drops it, taking the only thing that joined them. */}
             <RecordSummary
               title={customer ? customer.name : "No customer"}
-              subtitle={[code, customer?.city].filter(Boolean).join(" · ")}
+              subtitle={[code, customer?.city].filter(Boolean).join(", ")}
             />
           </View>
         </View>

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@lotics/ui",
-  "version": "35.0.0",
+  "version": "37.0.0",
   "type": "module",
   "exports": {
     "./vite": {

package/src/accordion.tsx

@@ -101,7 +101,8 @@ export function AccordionHeader(props: AccordionHeaderProps) {
 
   return (
     <PressableHighlight
-      focusRing      onPress={toggle}
+      focusRing
+      onPress={toggle}
       accessibilityRole="button"
       // The W3C prop, NOT `accessibilityState` — this react-native-web build drops the
       // latter silently, so a disclosure shipped a `role="button"` that never announced

package/src/agent_progress.tsx

@@ -68,7 +68,8 @@ export function AgentProgress(props: AgentProgressProps) {
       ) : null}
 
       <PressableHighlight
-        focusRing        onPress={() => setExpanded((e) => !e)}
+        focusRing
+        onPress={() => setExpanded((e) => !e)}
         style={styles.pill}
         accessibilityLabel={expanded ? "Hide the agent's steps" : "Show the agent's steps"}
       >

package/src/allocation_row.tsx

@@ -3,6 +3,7 @@ import { View } from "react-native";
 import { Text } from "./text";
 import { Button } from "./button";
 import { NumberInput } from "./number_input";
+import { useLoticsLocale } from "./locale";
 
 export interface AllocationRowProps {
   /** The target's primary line — an invoice no., an order, a cost centre. */
@@ -28,6 +29,7 @@ export interface AllocationRowProps {
  */
 export function AllocationRow(props: AllocationRowProps) {
   const { label, sublabel, cap, value, onValueChange, format = (n) => n.toLocaleString(), trailing } = props;
+  const locale = useLoticsLocale();
   const full = value >= cap;
   return (
     <View style={{ flexDirection: "row", alignItems: "center", gap: 12, paddingHorizontal: 20, minHeight: 60 }}>
@@ -38,17 +40,17 @@ export function AllocationRow(props: AllocationRowProps) {
         </View>
         {sublabel ? <Text size="xs" color="muted">{sublabel}</Text> : null}
       </View>
-      <Text size="sm" color="muted" tabular style={{ width: 128, textAlign: "right" }}>{`${format(cap)} due`}</Text>
+      <Text size="sm" color="muted" tabular style={{ width: 128, textAlign: "right" }}>{locale.allocationRow.due(format(cap))}</Text>
       <View style={{ width: 150 }}>
         <NumberInput
           value={value || null}
           onValueChange={(n) => onValueChange(Math.max(0, Math.min(cap, n ?? 0)))}
           min={0}
           max={cap}
-          accessibilityLabel={`Allocate to ${label}`}
+          accessibilityLabel={locale.allocationRow.allocateTo(label)}
         />
       </View>
-      <Button title={full ? "Clear" : "Full"} color="muted" onPress={() => onValueChange(full ? 0 : cap)} />
+      <Button title={full ? locale.allocationRow.clear : locale.allocationRow.full} color="muted" onPress={() => onValueChange(full ? 0 : cap)} />
     </View>
   );
 }

package/src/breakdown.tsx

@@ -95,7 +95,8 @@ export function Breakdown(props: BreakdownProps) {
           );
           return onSelect ? (
             <PressableHighlight
-              focusRing              key={item.key}
+              focusRing
+              key={item.key}
               accessibilityRole="button"
               // The W3C prop — `accessibilityState` is dropped by this react-native-web
               // build, and `selected` has no meaning on a `button` role regardless.
@@ -114,7 +115,8 @@ export function Breakdown(props: BreakdownProps) {
         })}
         {collapsible ? (
           <PressableHighlight
-              focusRing            accessibilityRole="button"
+            focusRing
+            accessibilityRole="button"
             // The W3C prop — `accessibilityState` is dropped by this react-native-web build.
             aria-expanded={expanded}
             accessibilityLabel={expanded ? labels.less : labels.more(hidden)}

package/src/checklist.tsx

@@ -165,9 +165,13 @@ export function ChecklistGroup({ title, open, onToggleOpen, labels, ...positiona
         {/* A TEXT link, not a chevron: the phase is a heading rather than a row, so
             a disclosure triangle would give it the affordance of something that
             opens INTO a place. This only shows and hides rows already in the run,
-            and it says which in words. */}
+            and it says which in words.
+
+            The NAME is verb then object with nothing between them — "Show Picking"
+            is already a phrase, and the middot that stood here bought no clarity
+            while being dropped by every screen reader that read it aloud. */}
         {onToggleOpen != null ? (
-          <Pressable onPress={onToggleOpen} accessibilityRole="button" accessibilityLabel={`${word} · ${title}`}>
+          <Pressable onPress={onToggleOpen} accessibilityRole="button" accessibilityLabel={`${word} ${title}`}>
             <TextLink size="xs">{word}</TextLink>
           </Pressable>
         ) : null}

package/src/chip_group.tsx

@@ -46,7 +46,8 @@ export function ChipGroup<T extends string = string>(props: ChipGroupProps<T>) {
         const active = option.value === value;
         return (
           <PressableHighlight
-            focusRing            key={option.value}
+            focusRing
+            key={option.value}
             testID={option.testID}
             onPress={() => onValueChange(option.value)}
             accessibilityRole="button"

package/src/column_filter.tsx

@@ -5,6 +5,7 @@ import { NumberInput } from "./number_input";
 import { OptionList } from "./option_list";
 import { FilterChip } from "./filter_chip";
 import type { PickerOption } from "./picker";
+import { useLoticsLocale } from "./locale";
 
 /** A column the picker can filter on. `type` selects the control + operators. */
 export interface FilterableColumn {
@@ -107,6 +108,7 @@ export interface ColumnFilterProps {
  */
 export function ColumnFilter(props: ColumnFilterProps) {
   const { column, value, onChange, clearLabel } = props;
+  const locale = useLoticsLocale();
   const active = isColumnFilterActive(value);
 
   return (
@@ -129,7 +131,7 @@ export function ColumnFilter(props: ColumnFilterProps) {
         ) : column.type === "number" ? (
           <View style={styles.range}>
             <NumberInput
-              accessibilityLabel={`${column.label} min`}
+              accessibilityLabel={locale.columnFilter.min(column.label)}
               value={value?.kind === "number" ? value.min : null}
               onValueChange={(min) =>
                 onChange({ kind: "number", min, max: value?.kind === "number" ? value.max : null })
@@ -139,7 +141,7 @@ export function ColumnFilter(props: ColumnFilterProps) {
               –
             </Text>
             <NumberInput
-              accessibilityLabel={`${column.label} max`}
+              accessibilityLabel={locale.columnFilter.max(column.label)}
               value={value?.kind === "number" ? value.max : null}
               onValueChange={(max) =>
                 onChange({ kind: "number", min: value?.kind === "number" ? value.min : null, max })

package/src/comments_button.tsx

@@ -20,8 +20,14 @@ export interface CommentsButtonProps {
   /** `sm` (the register row's) or `md`. Matches `CopyButton`'s scale so the two
    *  affordances a row carries sit at one size. */
   size?: "sm" | "md";
-  /** Override the wording; otherwise the locale's. */
-  labels?: { comments?: string; comment?: string };
+  /** Override the wording; otherwise the locale's. `withSubject` builds the whole
+   *  phrase from the counted noun and the subject, so an override changes the word
+   *  ORDER too, not just the words. */
+  labels?: {
+    comments?: string;
+    comment?: string;
+    withSubject?: (counted: string, subject: string) => string;
+  };
   disabled?: boolean;
   testID?: string;
 }
@@ -57,7 +63,15 @@ export function CommentsButton(props: CommentsButtonProps) {
   // The subject rides the NAME, never the visible label: a row already says whose
   // record it is, and repeating it beside the count spends the row's width on
   // something the eye has just read.
-  const name = subject ? `${count} ${noun} · ${subject}` : `${count} ${noun}`;
+  //
+  // The PACK composes it, exactly as `sortBy` and `rowDetails` do. Two reasons,
+  // and the second is the one that outlives this component: a middot is dropped by
+  // every screen reader, so the one mark carrying "these comments are about that
+  // record" is the one part that never survives being read aloud — and the word
+  // that replaces it sits in a different PLACE in different languages, which a
+  // component concatenating in English order cannot express at all.
+  const counted = `${count} ${noun}`;
+  const name = subject ? (labels?.withSubject ?? locale.commentsButton.withSubject)(counted, subject) : counted;
 
   return (
     <PressableHighlight

package/src/counter.tsx

@@ -2,6 +2,7 @@ import { StyleSheet, View } from "react-native";
 import { Text } from "./text";
 import { colors } from "./colors";
 import { IconButton } from "./icon_button";
+import { useLoticsLocale } from "./locale";
 
 export interface CounterProps {
   value: number;
@@ -9,7 +10,8 @@ export interface CounterProps {
   min?: number;
   max?: number;
   step?: number;
-  /** Announced name — the buttons become "Decrease/Increase {label}". */
+  /** Announced name — the pack wraps it into each button's own phrase
+   *  ("Decrease {label}" in English, "Giảm {label}" in Vietnamese). */
   accessibilityLabel: string;
   /** Render the value with units ("3 nights", "2 guests"). Default: the number. */
   format?: (value: number) => string;
@@ -24,6 +26,7 @@ export interface CounterProps {
  */
 export function Counter(props: CounterProps) {
   const { value, onValueChange, min = 0, max = Infinity, step = 1, accessibilityLabel, format } = props;
+  const locale = useLoticsLocale();
   const clamp = (n: number) => Math.min(max, Math.max(min, n));
 
   return (
@@ -32,7 +35,7 @@ export function Counter(props: CounterProps) {
         icon="minus"
         size="md"
         style={styles.btn}
-        accessibilityLabel={`Decrease ${accessibilityLabel}`}
+        accessibilityLabel={locale.counter.decrease(accessibilityLabel)}
         disabled={value <= min}
         onPress={() => onValueChange(clamp(value - step))}
       />
@@ -43,7 +46,7 @@ export function Counter(props: CounterProps) {
         icon="plus"
         size="md"
         style={styles.btn}
-        accessibilityLabel={`Increase ${accessibilityLabel}`}
+        accessibilityLabel={locale.counter.increase(accessibilityLabel)}
         disabled={value >= max}
         onPress={() => onValueChange(clamp(value + step))}
       />

package/src/file_row.tsx

@@ -5,6 +5,7 @@ import { colors } from "./colors";
 import { FileBadge } from "./file_badge";
 import { FOCUS_RING } from "./control_surface";
 import { useFocusRing } from "./use_focus_ring";
+import { useLoticsLocale } from "./locale";
 
 export interface FileRowProps {
   /** The file / document name — the primary line. */
@@ -76,6 +77,7 @@ export function FileRow({
   leading,
   size = "sm",
 }: FileRowProps) {
+  const locale = useLoticsLocale();
   const md = size === "md";
   const [hovered, setHovered] = useState(false);
   const [pressed, setPressed] = useState(false);
@@ -134,7 +136,7 @@ export function FileRow({
         onPressIn={() => setPressed(true)}
         onPressOut={() => setPressed(false)}
         accessibilityRole="button"
-        accessibilityLabel={`Open ${name}`}
+        accessibilityLabel={locale.fileRow.open(name)}
         style={[styles.door, focusVisible && { boxShadow: FOCUS_RING }]}
       >
         {content}

package/src/kpi_card.tsx

@@ -3,6 +3,7 @@ import { Text } from "./text";
 import { Metric, type MetricFormat, type MetricSize, type MetricTone } from "./metric";
 import { TrendChip } from "./trend_chip";
 import { InfoPopover } from "./info_popover";
+import { useLoticsLocale } from "./locale";
 import { SPACE } from "./spacing";
 
 interface KPICardProps {
@@ -50,13 +51,16 @@ interface KPICardProps {
  */
 export function KPICard(props: KPICardProps) {
   const { label, value, format, currency, locale, emptyLabel, compact, size = "lg", tone, trend, caption, info, style } = props;
+  // `pack`, not `locale` — that name is taken by the BCP-47 tag this card passes
+  // to `Metric` for number formatting, which is a different axis entirely.
+  const pack = useLoticsLocale();
   return (
     <View style={[styles.container, style]}>
       <View style={styles.labelRow}>
         <Text size="xs" color="muted" transform="uppercase">
           {label}
         </Text>
-        {info ? <InfoPopover text={info} accessibilityLabel={`About ${label}`} /> : null}
+        {info ? <InfoPopover text={info} accessibilityLabel={pack.infoPopover.about(label)} /> : null}
       </View>
       <View style={styles.valueRow}>
         <Metric

package/src/locale.tsx

@@ -164,8 +164,27 @@ export interface LoticsLocale {
   /** `ImageGallery`: the empty state, the inline rotate controls, and the
    *  press-to-zoom a11y name. */
   imageGallery: { empty: string; rotateLeft: string; rotateRight: string; zoom: string };
-  /** `InfoPopover`: the ⓘ trigger's a11y name. */
-  infoPopover: { more: string };
+  /** `InfoPopover`: the ⓘ trigger's a11y name. `more` is the bare default;
+   *  `about` names the SUBJECT, which is what a screen a11y reader needs when a
+   *  page carries several ⓘ buttons and "More information" is said four times. */
+  infoPopover: { more: string; about: (label: string) => string };
+  /** `FileRow` / `Sources`: the door onto one file or one cited source. Two
+   *  slices rather than one shared verb, because a pack may open a FILE and open
+   *  a SOURCE with different words. */
+  fileRow: { open: (name: string) => string };
+  sources: { open: (label: string) => string; heading: string };
+  /** `Counter`: the two steppers, named for the value they move. */
+  counter: { decrease: (label: string) => string; increase: (label: string) => string };
+  /** `AllocationRow`: the a11y name of the amount input (naming its destination),
+   *  the outstanding-amount caption, and the two fill/empty verbs. */
+  allocationRow: {
+    allocateTo: (label: string) => string;
+    due: (amount: string) => string;
+    clear: string;
+    full: string;
+  };
+  /** `ColumnFilter`: the two bounds of a numeric range, named for their column. */
+  columnFilter: { min: (label: string) => string; max: (label: string) => string };
   /** `Matrix`: the total column/row header and the legend's less→more ends. */
   matrix: { total: string; less: string; more: string };
   /** `ScrollToBottom`: the jump-to-latest tooltip. */
@@ -209,8 +228,17 @@ export interface LoticsLocale {
    *  value only the call site knows, the same split `referenceField.open` draws. */
   copyButton: { copy: string; copied: string };
   /** `CommentsButton`'s accessible name — the kit owns the noun so one surface
-   *  does not say "comments" while the next says "notes" for the same thread. */
-  commentsButton: { comment: string; comments: string };
+   *  does not say "comments" while the next says "notes" for the same thread.
+   *  `withSubject` builds the WHOLE phrase, so a pack chooses the word ORDER and
+   *  not merely the vocabulary: the subject leads in some languages, and a
+   *  component that concatenates in English order cannot be translated into one.
+   *  It joins with a WORD because this string exists to be read aloud, and a
+   *  screen reader drops punctuation, taking the relation with it. */
+  commentsButton: {
+    comment: string;
+    comments: string;
+    withSubject: (counted: string, subject: string) => string;
+  };
 }
 
 /** The platform default — English. Every component's hardcoded default lives
@@ -329,7 +357,17 @@ export const en: LoticsLocale = {
     retryAll: "Retry all",
   },
   imageGallery: { empty: "No images.", rotateLeft: "Rotate left", rotateRight: "Rotate right", zoom: "Zoom image" },
-  infoPopover: { more: "More information" },
+  infoPopover: { more: "More information", about: (label) => `About ${label}` },
+  fileRow: { open: (name) => `Open ${name}` },
+  sources: { open: (label) => `Open ${label}`, heading: "Sources" },
+  counter: { decrease: (label) => `Decrease ${label}`, increase: (label) => `Increase ${label}` },
+  allocationRow: {
+    allocateTo: (label) => `Allocate to ${label}`,
+    due: (amount) => `${amount} due`,
+    clear: "Clear",
+    full: "Full",
+  },
+  columnFilter: { min: (label) => `${label} min`, max: (label) => `${label} max` },
   matrix: { total: "Total", less: "Less", more: "More" },
   scrollToBottom: { tooltip: "Scroll to bottom" },
   textInputField: { clear: "Clear" },
@@ -366,7 +404,11 @@ export const en: LoticsLocale = {
   approvalPrompt: { message: "The assistant wants to perform an action that needs your approval.", approve: "Approve", deny: "Deny" },
   messageActions: { copy: "Copy", copied: "Copied", regenerate: "Regenerate", edit: "Edit", previousVersion: "Previous version", nextVersion: "Next version" },
   copyButton: { copy: "Copy", copied: "Copied" },
-  commentsButton: { comment: "comment", comments: "comments" },
+  commentsButton: {
+    comment: "comment",
+    comments: "comments",
+    withSubject: (counted, subject) => `${counted} on ${subject}`,
+  },
 };
 
 /** Vietnamese. Maintained once here so every app (and the frontend) shares one
@@ -482,7 +524,22 @@ export const vi: LoticsLocale = {
     retryAll: "Thử lại tất cả",
   },
   imageGallery: { empty: "Chưa có ảnh.", rotateLeft: "Xoay trái", rotateRight: "Xoay phải", zoom: "Phóng to ảnh" },
-  infoPopover: { more: "Thông tin thêm" },
+  infoPopover: { more: "Thông tin thêm", about: (label) => `Thông tin về ${label}` },
+  fileRow: { open: (name) => `Mở ${name}` },
+  sources: { open: (label) => `Mở ${label}`, heading: "Nguồn" },
+  counter: { decrease: (label) => `Giảm ${label}`, increase: (label) => `Tăng ${label}` },
+  allocationRow: {
+    allocateTo: (label) => `Phân bổ vào ${label}`,
+    // The word LEADS in Vietnamese and trails in English — "còn 5.000.000 ₫"
+    // against "5,000,000 ₫ due". A pack-owned function is the only shape that
+    // expresses both.
+    due: (amount) => `còn ${amount}`,
+    clear: "Xoá",
+    full: "Toàn bộ",
+  },
+  // The qualifier FOLLOWS the noun in Vietnamese — "Doanh thu tối thiểu", never
+  // "tối thiểu Doanh thu". Exactly what a pack-owned function is for.
+  columnFilter: { min: (label) => `${label} tối thiểu`, max: (label) => `${label} tối đa` },
   matrix: { total: "Tổng", less: "Ít", more: "Nhiều" },
   scrollToBottom: { tooltip: "Cuộn xuống cuối" },
   textInputField: { clear: "Xóa" },
@@ -519,7 +576,11 @@ export const vi: LoticsLocale = {
   approvalPrompt: { message: "Trợ lý muốn thực hiện thao tác cần bạn duyệt.", approve: "Cho phép", deny: "Từ chối" },
   messageActions: { copy: "Sao chép", copied: "Đã sao chép", regenerate: "Tạo lại", edit: "Chỉnh sửa", previousVersion: "Phiên bản trước", nextVersion: "Phiên bản sau" },
   copyButton: { copy: "Sao chép", copied: "Đã sao chép" },
-  commentsButton: { comment: "bình luận", comments: "bình luận" },
+  commentsButton: {
+    comment: "bình luận",
+    comments: "bình luận",
+    withSubject: (counted, subject) => `${counted} về ${subject}`,
+  },
 };
 
 const LoticsLocaleContext = createContext<LoticsLocale>(en);

package/src/page_content.tsx

@@ -4,6 +4,7 @@ import { colors } from "@lotics/ui/colors";
 import { Spacer } from "@lotics/ui/spacer";
 import { ReactNode } from "react";
 import { useContainerSize } from "@lotics/ui/size_boundary";
+import { pagePad } from "@lotics/ui/spacing";
 
 interface PageContentProps {
   children: ReactNode;
@@ -26,6 +27,10 @@ export function PageContent(props: PageContentProps) {
   const screenSize = useContainerSize();
 
   const maxWidth = !screenSize.small && size ? PAGE_SIZES[size] : undefined;
+  // The gutter is a TOKEN, not this component's own number — a screen that cannot
+  // use this shell (one with a rail, a side panel, its own scroller) still has to
+  // land on the same edge, and it can only do that if the number has one home.
+  const pad = pagePad(screenSize.small);
 
   if (fullscreen) {
     return (
@@ -33,7 +38,7 @@ export function PageContent(props: PageContentProps) {
         {!!header && (
           <View
             style={{
-              paddingHorizontal: 16,
+              paddingHorizontal: pad,
               paddingTop: 16,
               width: "100%",
             }}
@@ -51,7 +56,7 @@ export function PageContent(props: PageContentProps) {
       {!!header && (
         <View
           style={{
-            paddingHorizontal: 16,
+            paddingHorizontal: pad,
             paddingTop: 16,
             maxWidth,
             width: "100%",
@@ -73,7 +78,7 @@ export function PageContent(props: PageContentProps) {
             maxWidth,
             width: "100%",
             marginHorizontal: "auto",
-            paddingHorizontal: 16,
+            paddingHorizontal: pad,
           }}
         >
           <View
@@ -101,19 +106,25 @@ export function PageContent(props: PageContentProps) {
         </View>
       </ScrollView>
       {!!footer && (
-        <View
-          style={{
-            borderTopWidth: 1,
-            borderTopColor: colors.border,
-            padding: 16,
-            paddingBottom: 24,
-          }}
-        >
+        // The RULE spans the page; the CONTENT sits on the body's column. Those
+        // are two different widths, which is why they are two elements.
+        <View style={{ borderTopWidth: 1, borderTopColor: colors.border }}>
+          {/* ONE box carries the cap AND the gutter, exactly as the body's does.
+              Split across two — the padding outside, the cap inside — they
+              compute different edges the moment a cap is in play and the viewport
+              is wider than it: the body's content starts `pad` inside a centred
+              1280 box, while the footer's starts wherever 1280 centres inside a
+              padded full-width box. That put a footer's totals 32px off the column
+              they total, and it is invisible at phone width, where nothing is
+              capped. */}
           <View
             style={{
               maxWidth,
               width: "100%",
               marginHorizontal: "auto",
+              paddingHorizontal: pad,
+              paddingTop: 16,
+              paddingBottom: 24,
             }}
           >
             {footer}

package/src/peek.tsx

@@ -33,7 +33,8 @@ export function Peek(props: PeekProps) {
     <Popover side={side} align={align}>
       <PopoverTrigger>
         <PressableHighlight
-          focusRing          accessibilityRole="button"
+          focusRing
+          accessibilityRole="button"
           accessibilityLabel={accessibilityLabel}
           style={styles.trigger}
           // 32px visual, 40px touch target (32 + 2×4) — same as IconButton.

package/src/pressable_highlight.tsx

@@ -71,12 +71,14 @@ export interface PressableHighlightProps extends PressableProps {
  * A pressable component that highlights when hovered and pressed.
  * It will darken the `backgroundColor` prop when hovered and pressed.
  *
- * It IS a button and it WRAPS its children — so its content must be non-interactive by
- * construction. A row whose content carries its own controls (a CTA, a ⋯ menu, a
- * checkbox, a `Link`) must not be built on it: a button cannot contain interactive
- * descendants. Compose the role-less `PressableRow` + a `PressDoor` sibling instead —
- * the surface takes the mouse, the door takes the keyboard, the controls stay their own
- * tab stops (`TableRow` is the reference).
+ * It IS a button — it says so itself, with `accessibilityRole="button"` by default —
+ * and it WRAPS its children, so its content must be non-interactive by construction.
+ * A row whose content carries its own controls (a CTA, a ⋯ menu, a checkbox, a
+ * `Link`) must not be built on it: a button cannot contain interactive descendants.
+ * Compose the role-less `PressableRow` + a `PressDoor` sibling instead — the surface
+ * takes the mouse, the door takes the keyboard, the controls stay their own tab stops
+ * (`TableRow` is the reference). That role split IS the difference between the two
+ * components, which is why neither leaves it to the call site.
  */
 export function PressableHighlight(props: PressableHighlightProps) {
   const {
@@ -122,6 +124,15 @@ export function PressableHighlight(props: PressableHighlightProps) {
         ] as StyleProp<ViewStyle>;
       }}
       onPress={handlePress}
+      // THE ROLE IS THE CONTRACT, so it is set here rather than asked for at every
+      // call site. This component IS a button — that is what separates it from the
+      // role-less `PressableRow`, and it is why its children must be
+      // non-interactive. Left to the call sites the split existed only in prose:
+      // 18 of 35 passed the role, all 18 passed "button", and the other 17
+      // rendered a surface a screen reader could name but not identify as
+      // pressable. Before the spread, so a caller that genuinely means something
+      // else still wins.
+      accessibilityRole="button"
       {...restPressableProps}
       // `onFocus` / `onBlur` are part of `PressableProps`, so a trailing
       // `{...tooltipProps}` spread would silently overwrite caller-provided

package/src/scroll_to_bottom.tsx

@@ -17,7 +17,8 @@ export function ScrollToBottom(props: ScrollToBottomProps) {
 
   return (
     <PressableHighlight
-      focusRing      testID="scroll-to-bottom-button"
+      focusRing
+      testID="scroll-to-bottom-button"
       tooltip={tooltip}
       onPress={onPress}
       style={styles.button}

package/src/sources.tsx

@@ -3,6 +3,7 @@ import { colors, solid, tint, type ColorName } from "./colors";
 import { Text } from "./text";
 import { Icon, type IconName } from "./icon";
 import { PressableHighlight } from "./pressable_highlight";
+import { useLoticsLocale } from "./locale";
 
 export type SourceKind = "record" | "document" | "table" | "web" | "knowledge";
 
@@ -43,18 +44,19 @@ const KIND: Record<SourceKind, { icon: IconName; color: ColorName }> = {
  * Renders nothing for an empty list.
  */
 export function Sources(props: SourcesProps) {
+  const locale = useLoticsLocale();
   if (props.sources.length === 0) return null;
   return (
     <View style={{ gap: 8 }}>
       {props.label === null ? null : (
         <Text size="xs" color="muted" weight="medium">
-          {props.label ?? "Sources"}
+          {props.label ?? locale.sources.heading}
         </Text>
       )}
       <View style={styles.row}>
         {props.sources.map((s) =>
           props.onOpen ? (
-            <PressableHighlight focusRing key={s.id} onPress={() => props.onOpen?.(s)} accessibilityLabel={`Open ${s.label}`} style={styles.chip}>
+            <PressableHighlight focusRing key={s.id} onPress={() => props.onOpen?.(s)} accessibilityLabel={locale.sources.open(s.label)} style={styles.chip}>
               <SourceChip source={s} openable />
             </PressableHighlight>
           ) : (

package/src/spacing.ts

@@ -21,3 +21,23 @@ export const SPACE = {
 } as const;
 
 export type SpaceToken = keyof typeof SPACE;
+
+/**
+ * The page's side gutter, by width — what a full-page surface pads by.
+ *
+ * ONE number, because a list and the record it opens are the same reading column
+ * seen twice: a gutter that differs between them slides the content sideways at
+ * the moment the reader changes screens. `PageContent` applies it; a screen that
+ * hand-rolls its own shell imports it rather than picking again.
+ *
+ * ON THE LADDER above, deliberately. Left to each app this lands on numbers like
+ * 14 and 28 — one of them not even a multiple of 4 — which is the "reads as
+ * broken" case this scale exists to prevent. `md` on a phone, where 28 a side
+ * spends 15% of a 375px screen on margin and 16 is the platform norm besides;
+ * `xl` wider, where 16 leaves a capped column nearly touching the chrome.
+ *
+ * COUPLED to `ROW_WASH_BLEED` (`control_surface`): a register row bleeds its wash
+ * OUTWARD past this, landing at `pagePad − ROW_WASH_BLEED`. Two numbers that must
+ * be read together is exactly why this one does not belong to the app.
+ */
+export const pagePad = (small: boolean): number => (small ? SPACE.md : SPACE.xl);

package/src/status_grid.tsx

@@ -131,7 +131,8 @@ export function StatusLegend(props: StatusLegendProps) {
         );
         return onSelect ? (
           <PressableHighlight
-            focusRing            key={state.key}
+            focusRing
+            key={state.key}
             accessibilityRole="button"
             // The W3C prop — `accessibilityState` is dropped by this react-native-web
             // build, and `selected` has no meaning on a `button` role regardless.

package/src/summary_line.tsx

@@ -3,6 +3,7 @@ import { Text } from "./text";
 import { Metric, type MetricFormat, type MetricTone } from "./metric";
 import { TrendChip } from "./trend_chip";
 import { InfoPopover } from "./info_popover";
+import { useLoticsLocale } from "./locale";
 
 export interface SummaryLineItem {
   /** Label that reads AFTER the value ("below minimum", "stock value"). */
@@ -49,6 +50,7 @@ export interface SummaryLineProps {
  */
 export function SummaryLine(props: SummaryLineProps) {
   const { items } = props;
+  const locale = useLoticsLocale();
   return (
     <View style={styles.row}>
       {items.map((item) => (
@@ -67,7 +69,7 @@ export function SummaryLine(props: SummaryLineProps) {
             {item.label}
           </Text>
           {item.trend != null ? <TrendChip value={item.trend} /> : null}
-          {item.info ? <InfoPopover text={item.info} accessibilityLabel={`About ${item.label}`} /> : null}
+          {item.info ? <InfoPopover text={item.info} accessibilityLabel={locale.infoPopover.about(item.label)} /> : null}
         </View>
       ))}
     </View>

package/src/switch_button.tsx

@@ -16,7 +16,8 @@ export function SwitchButton(props: SwitchButtonProps) {
 
   return (
     <PressableHighlight
-      focusRing      style={{
+      focusRing
+      style={{
         flexDirection: "row",
         gap: 16,
         alignItems: "center",