@lotics/ui 42.4.0 → 43.1.0

package/MIGRATION.md

@@ -4,6 +4,80 @@ 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.
 
+## 43.0.0 — a time is PICKED, and there is nothing to type
+
+`TimePicker` is no longer a segmented text field. It is the value on a pressable
+control — the bordered surface a `Select` uses — that opens an **hour / minute /
+day-period** picker. `InlineTimePicker` is the same thing on the inline shell.
+
+**Why the segments went.** A time was typed, with a picker bolted on as a small
+glyph inside the field, and each half of that was wrong:
+
+- **The glyph was undiscoverable, and worse than undiscoverable.** It sat exactly
+  where `DateField` puts a display-only calendar icon — same slot, same size,
+  same colour — so the one affordance for picking was indistinguishable from
+  decoration. A control nobody can identify is not a control.
+- **A day period is not something to spell.** AM/PM is a choice between two named
+  things; asking someone to type "PM" is asking them to type an answer to a
+  yes/no question. It is now a column.
+- **Composed times cannot cover the clock.** The old list offered whole times at
+  a fixed step, so anything between the rungs — a 13:07 cut-off — was reachable
+  only by typing, and the list had to splice odd values back in to stay honest.
+  Split by UNIT, every minute is offered and that whole class of special case is
+  gone.
+
+The value is unchanged: canonical 24-hour `"HH:mm"`. The locale still decides 12-
+vs 24-hour, and now also decides the SHAPE — a 24-hour locale gets two columns
+and hours 00–23, a 12-hour locale gets a clock face starting at 12 plus the
+period column. Tab reaches each column once and arrows move within it (roving
+tabindex), so sixty minutes are not sixty tab stops.
+
+**To migrate:**
+
+- **`TimePicker` drops `onBlur`, `onEscape`, `onIncompleteChange`, `autoFocus`
+  and `segmentLabels`.** They all served typed entry. A pick is always a complete
+  time, so there is no half-entered state to report and nothing to cancel back
+  to; `placeholder` replaces them as the empty-state control. Delete the props —
+  the compiler will point at each one.
+- **`InlineTimePicker` gains `locale` and drops `controls`.** It commits when the
+  popover closes, not on blur, so a `"buttons"` mode has nothing to confirm.
+- **Add `chooseTime` to any complete `DatePickerLabels` you build** — it names the
+  control and doubles as the empty placeholder. A `labels` prop passed to
+  `DatePicker` is `Partial`, so only a hand-built full set breaks.
+
+**Two kit-wide `OptionList` fixes ride along**, both pre-existing and both
+invisible until a long list met them:
+
+- **A chosen option carries `aria-selected`.** It had only the check GLYPH, so
+  which option was selected was information available to whoever could see the
+  row and to nobody else. It comes with `MenuButton`'s resting `zinc.100`
+  highlight — one weight above the `zinc.50` the keyboard/hover row takes — so
+  **every** `Select`, `Combobox` and option list now tints its selected row.
+  Nothing to change; expect the pixels to move.
+- **An opening list scrolls to its seat.** The initial highlight was seated
+  without scrolling to it, so any list longer than its own box opened at the top
+  with the current value below the fold.
+
+`MenuButton` gains `tabIndex` + `onKeyDown` so a listbox row can hold a roving
+tab stop. Additive.
+
+**A pressable `ListItem` presses BESIDE its `right` slot.** The slot is documented as holding
+a control, and a button may not contain one: `<button>` inside `<button>` is invalid HTML and
+buries a second tab stop and a second accessible name inside one control. The anatomy carries
+this rather than a prop opting into safety, so every call site already passing a control there
+is fixed without being touched, and it applies whether or not a slot is passed — `right` is
+routinely conditional, and an anatomy that flipped on that would make two rows in one list
+press differently. The one visible consequence: a DECORATIVE `right` (a badge, a chevron) is no
+longer part of the press target — the row still presses everywhere else.
+
+**The pointer cursor is now reserved for controls that ACT** — buttons, links, disclosures.
+Rows, menu options, cards, tabs, field triggers, checkboxes, switches, chips and calendar
+days all show the arrow. No API changes; every affected component is one you already use, so
+the only thing to expect is that the cursor stops changing over most of a screen. The rule and
+its reasoning are in `docs/composition.md` § The pointer cursor. If a component of your own
+needs the pointer, set `CURSOR_ACTION` in its style — and if it is built on the bare
+react-native `Pressable`, note that the pointer is what you get by DEFAULT, from
+react-native-web, unless you set `CURSOR_DEFAULT`.
 ## 42.4.0 — `Picker` is named by its `FormField`, and its way back to empty has a name
 
 Two fixes to the same control, both about a thing on screen that the control did

package/docs/catalog.md

@@ -788,7 +788,12 @@ source (`src/<module>.tsx`/`.ts`) is the API reference.
   shell-owned `actions`).
 - **`option_list`** — `OptionList`: the ONE shared searchable listbox body every selector
   opens — single/multi, optional internal search, create row, keyboard + native-`<select>`
-  typeahead; host it directly in a `Popover`/`Dialog` for a command palette.
+  typeahead; host it directly in a `Popover`/`Dialog` for a command palette. A chosen row is
+  `selected`: the kit's `zinc.100` resting highlight AND `aria-selected`, one weight above the
+  `zinc.50` the keyboard/hover row takes — a check glyph alone said nothing to a screen reader.
+  It opens SCROLLED to its seat (the selected row in `search.mode:"none"`, else the first real
+  option), which only shows on a list longer than its own box and is the difference between a
+  96-row list opening on your value and opening at the top.
 - **`combobox`** — COMPOUND single-select editable search: `Combobox` root +
   `ComboboxInput` + `ComboboxContent`, optional `ComboboxEmpty`/`ComboboxFooter`,
   `useCombobox()`; over the shared option-list engine; browses on focus; no `multi` —
@@ -865,6 +870,11 @@ source (`src/<module>.tsx`/`.ts`) is the API reference.
   localized weekday/month names via BCP-47 `locale`, `firstDayOfWeek` (default Monday),
   `ref.navigateToMonth`. The engine `DatePicker`/`DateFilter` wrap in field chrome — reach
   for it bare only when the calendar lives permanently on the surface, not behind a field.
+  While a range is OPEN (a start, no end), hovering a day fills the span it would close on,
+  across both months — including the day under the pointer, which a committed range draws
+  dark and a previewed one has nothing else to mark. It shares its open-ness test with the
+  click (`previewEndFor` beside `nextRangeSelection`), so the span shown is always the span
+  the next click produces; hovering backwards from the start previews just as well.
 - **`date_filter`** — `DateFilter`: the date+time period filter panel — presets
   (`PresetId`), calendar, optional time segments; the body `DateRangeFilterField` opens.
   **Every preset SETS a range** — the list holds no mode and no null case, so a hand-picked
@@ -880,10 +890,25 @@ source (`src/<module>.tsx`/`.ts`) is the API reference.
   end that is still open.
 - **`date_range_filter_field`** — `DateRangeFilterField`: the register's period filter field
   (presets + footer + time-segment a11y; localized via the `dateRange` locale slice).
-- **`time_picker`** — `TimePicker`: the time-of-day field. Segments (hour / minute / AM-PM),
-  **12- vs 24-hour derived from `locale`** — never from the browser, which is why this is not
-  an `<input type="time">`. The value is always canonical 24-hour `"HH:mm"`; `locale` changes
-  only what is displayed and typed.
+- **`time_picker`** — `TimePicker`: the time-of-day FIELD. The value on a pressable
+  control (the bordered surface a `Select` uses, so it reads as pickable by the same
+  shape as every other field that opens something), and `TimeColumns` behind it.
+  **No text entry** — a glyph inside a field is indistinguishable from `DateField`'s
+  display-only calendar icon, and a day period is a choice between two named things
+  rather than a word to spell. `placeholder` covers the empty state (defaults to the
+  `chooseTime` label). The value is always canonical 24-hour `"HH:mm"`; `locale`
+  decides what is displayed AND the picker's shape.
+- **`time_columns`** — `TimeColumns`: the picking face — hour, minute, and a day
+  period **only where the locale uses one** (a 24-hour locale gets two columns and
+  hours 00–23). Every minute is offered, so no time is unreachable and no step has
+  to be chosen; each column commits on its own, so the value is always a real time
+  and there is no draft to confirm. Roving tabindex per column — Tab reaches a
+  column once, arrows move within it, and selection follows focus.
+- **`time_options`** — the columns' vocabulary, RN-free and pure: `decomposeTime` /
+  `composeTime` (the split into `displayHour` / `minute` / `pm` and back — a
+  12-hour locale's displayed hour means two different times and only the period
+  says which, which is why composing takes both), `hourOptions`, `minuteOptions`,
+  `dayPeriodOptions`, `dayPeriodLabels`, `formatTimeOfDay`, `timeToMinuteOfDay`.
 - **`deadline`** — the COUNTDOWN vocabulary, RN-free and pure: `daysUntil`, `countdownLabel`,
   `deadlineTone` / `deadlineColor`, `deadlineAnnotation`, `nearestDeadline` (+ `DeadlineLabels`,
   `DeadlineThresholds`, `Deadline`). Three contracts a screen must not invent for itself — how
@@ -1172,7 +1197,14 @@ source (`src/<module>.tsx`/`.ts`) is the API reference.
 ### Lists, tables & registers
 
 - **`list`** — `List`: children separated by hairline `Divider`s.
-- **`list_item`** — `ListItem`: the plain list row.
+- **`list_item`** — `ListItem`: the plain list row. A pressable row with a `right` slot
+  presses BESIDE it, never around it: the slot holds a control, and a button may not contain
+  one — `<button>` inside `<button>` is invalid HTML and buries a second tab stop and name
+  inside one control. So the surface is a wrapper, the press target is `left` + the text, and
+  the slot sits outside it (the anatomy `InlineEditView`'s `actions` uses). ALWAYS, not only
+  when a slot is passed: `right` is routinely conditional, and an anatomy that flipped on that
+  would make two rows in one list press differently. Nothing to opt into — a decorative
+  `right` simply stops being part of the press target.
 - **`table`** — `Table` + `TableRow` + `TableCell`: the paginated high-volume register
   (columns defined once, `sortLabels` localizable; rows are `PressableRow`-based).
   CONTAINER-RESPONSIVE with no prop (measures itself, like `Breakdown`/`DetailTable`): when

package/docs/composition.md

@@ -396,7 +396,7 @@ shows a zinc-100 highlight; `marked` (a bulk-ticked row) a resting blue-50 tint.
 band + every row's cell widths derive from it and can't drift. ONE hairline under the header; the
 rows below it Divider-separated. A sortable column shows its `SortHeader` glyph ALWAYS (a neutral
 up/down glyph when unsorted) so it reads as sortable; pressing cycles none → asc → desc → none.
-A `TableRow` with no `onPress` renders a STATIC read-only row (no hover wash, no pointer cursor) —
+A `TableRow` with no `onPress` renders a STATIC read-only row (no hover wash) —
 so `Table` also serves read-only tabular data (a fee breakdown, a spec sheet), not just interactive
 registers. A pressable `TableRow` REQUIRES `accessibilityLabel` ("Open …") — its keyboard door is
 an empty overlay with no content to derive a name from.
@@ -966,6 +966,26 @@ gate's SCOPE, once** — never prose beside the button, never revealed only on p
   a mix of "Đổi"/"Gỡ"): with a clearable link, changing = remove → the empty-state picker
   re-prompts, so the destructive verb covers both required anchors and optional adds.
 
+## The pointer cursor
+
+**Only a control that ACTS ON ITS OWN shows a pointer** — a button, a link, a disclosure.
+Everything else shows the arrow: a row, a menu option, a card, a tab, a field trigger, a
+checkbox, a switch, a chip. The line is not "is it pressable" (nearly everything is) but
+"does pressing it DO something, or does it set a value / open the thing you are already
+looking at".
+
+Drawn tightly because a signal on half the screen is not a signal. A pointer everywhere says
+only "this is a web page"; reserved, it marks the few things that act. What carries "you can
+press this" elsewhere is the hover treatment the surface already owns — a row's wash, a
+field's border, a chip's fill — which is what a native list or menu uses too, where the
+cursor stays an arrow throughout.
+
+The arrow is never the default and always has to be asked for: react-native-web ships
+`cursor: pointer` inside `Pressable`'s own base style, so a component that says nothing gets
+a pointer. `PressableHighlight` and `FocusRingPressable` set the arrow for everything built
+on them (`CURSOR_DEFAULT`); a component on the bare `Pressable` sets it itself, and the few
+that act set `CURSOR_ACTION` back over the top.
+
 ## Color discipline — solid / tint / ramp + ONE accent
 
 Every status / data-viz / accent color comes from a NAMED helper (`@lotics/ui/colors`), never a
@@ -1013,8 +1033,30 @@ When it IS a status, match weight to prominence — lightest → heaviest:
    a surface (a drawer/detail header). Opt IN explicitly and sparingly; one per view, never
    sprinkled through rows.
 
-A register's dense rows read lighter — the row's primary status is `dot`, its drawer twin may go
-tonal. A `Badge` is never a metric value.
+**`tonal` IS allowed on a register's ONE primary status column, and that is the rule this
+paragraph used to get wrong.** It read "a register's dense rows read lighter, the row's primary
+status is `dot`" while `badge.tsx` named "a register's primary Status column" as a legitimate
+tonal use — two docs, opposite answers, so the choice fell to whoever read which. What "one per
+view" governs is the number of badge KINDS on a surface, not the number of rows: badging the
+stage AND the type AND the city is the clutter the rule exists to stop; one status column that
+happens to render 133 times is one badge.
+
+Prefer `dot` when the column is secondary or the row already carries a coloured mark. Reach for
+`tonal` when the status column is what the register is SCANNED by — the tints are the palette's
+50-step against its 900-step ink (measured 8.7:1 and 9.5:1, so roughly double the AA floor), and
+a column of them is the difference between a register that reads as organised and one that reads
+as a grey spreadsheet. That difference is the commonest "it looks bland" report, and it has a
+real answer that costs no meaning: make the colour the screen ALREADY earns more present, rather
+than adding colour somewhere that has to invent a meaning to justify it.
+
+**A `Badge` in a table cell needs `alignSelf`.** A cell stretches its child on the cross axis, and
+a `dot` has no ground so nothing shows — swap the variant to `tonal` and the pill becomes a filled
+block the full width of the column, which reads as a cell state rather than a chip. The kit cannot
+fix this on the badge: `alignSelf: "flex-start"` means LEFT inside a column-direction cell and TOP
+inside a row-direction one, so setting it globally would break every badge sitting inline beside
+text. Pass it at the call site.
+
+A `Badge` is never a metric value.
 
 ## Typography
 

package/docs/data_entry.md

@@ -123,7 +123,7 @@ dialog save, a debounced autosave).
 ### Keyboard entry — type → Tab → type
 
 Bulk entry never needs the mouse. KEYBOARD focus (Tab / Shift+Tab) landing on a closed
-SWAP editor — `InlineNumberInput`, `InlineTimePicker`, `InlineDatePicker` — opens edit mode
+SWAP editor — `InlineNumberInput`, `InlineDatePicker` — opens edit mode
 immediately with the input focused; commit-on-blur then makes Tab itself the commit, so the chain
 is type → Tab → type with the next editor already open. Pointer focus never auto-opens (mousedown
 records "pointer" modality before focus fires — `interaction_modality.ts`), so the click path is
@@ -172,21 +172,26 @@ One per type:
 - **`InlineDatePicker`** — `format="datetime"` for always-on time; `optionalTime` to let the user
   ADD/REMOVE a time — the value's own shape, date vs datetime, is the source of truth
   (`optionalTime` is ignored when `format="datetime"`).
-- **`InlineTimePicker`** — a time-only value.
+- **`InlineTimePicker`** — a time-only value, PICKED: the value at rest, the hour /
+  minute / period columns in a popover anchored to the field, committing when the
+  popover closes. On the POPOVER shell beside `InlineDatePicker`, not the typed one
+  — `useInlineEdit` commits when the field blurs, and a picker cannot live there,
+  because opening one moves focus into it, which reads as a blur and unmounts the
+  editor before the picker can paint.
 - **`InlineSelect multi`** — the MULTI mode of `InlineSelect` (there's no separate tag component):
   a tag SET (`value: T[]`), selected tags render as badges inside the standard chip, clicking floats
   a multi `OptionList` (checkbox rows), CLOSING commits the new set in one `onSave` — never a borderless `Select` posing as an inline
   field.
 
 They split across two shared shells. The same-height **typed** editors (`InlineTextInput`,
-`InlineNumberInput`, `InlineTimePicker`) render **`InlineEditFrame`** driven by the
+`InlineNumberInput`) render **`InlineEditFrame`** driven by the
 **`useInlineEdit`** hook (the draft buffer, async save, and — for the two that swap — the view⇄edit
 toggle) — pass a custom input to that pair to join the family. On the frame, **`editing` means an
 input is MOUNTED** (which element renders, and whether the surface drops its resting padding to
 host one); an always-mounted editor passes it constant and passes the real state as **`editOpen`**,
 which the ✓/✕ verbs read — they assert "there is an edit to accept or reject", so on a resting
 field they would be both a false claim and dead buttons. The **popover** editors (`InlineSelect`,
-`InlineMemberSelect`, `InlineDatePicker`) instead compose **`InlineEditView`**
+`InlineMemberSelect`, `InlineDatePicker`, `InlineTimePicker`) instead compose **`InlineEditView`**
 (the resting box, wired as the popover trigger) with their OWN `useState` for open/draft/saving/
 error — a pick, not a keystroke, is the edit, so `useInlineEdit` doesn't fit. `onSave` is async
 either way: the saving spinner sits INSIDE the control at its right edge (never a sibling — that

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@lotics/ui",
-  "version": "42.4.0",
+  "version": "43.1.0",
   "type": "module",
   "exports": {
     "./vite": {
@@ -244,6 +244,8 @@
     "./date_filter": "./src/date_filter.tsx",
     "./date_range_filter_field": "./src/date_range_filter_field.tsx",
     "./time_picker": "./src/time_picker.tsx",
+    "./time_options": "./src/time_options.ts",
+    "./time_columns": "./src/time_columns.tsx",
     "./date_calendar": "./src/date_calendar.tsx",
     "./dialog": "./src/dialog.tsx",
     "./drawer": "./src/drawer.tsx",
@@ -275,7 +277,15 @@
     "./avatar_size": "./src/avatar_size.ts",
     "./diff_value": "./src/diff_value.tsx",
     "./diff_mark": "./src/diff_mark.tsx",
-    "./use_change_set": "./src/use_change_set.ts"
+    "./use_change_set": "./src/use_change_set.ts",
+    "./display_font": {
+      "react-native": "./src/display_font.ts",
+      "default": "./src/display_font.web.ts"
+    },
+    "./font_family": {
+      "react-native": "./src/font_family.ts",
+      "default": "./src/font_family.web.ts"
+    }
   },
   "files": [
     "src",

package/src/back_button.tsx

@@ -3,6 +3,7 @@ import { View } from "react-native";
 import { Icon } from "./icon";
 import { Text } from "./text";
 import { colors } from "./colors";
+import { CURSOR_ACTION } from "./control_surface";
 import { PressableHighlight } from "./pressable_highlight";
 import { useLoticsLocale } from "./locale";
 
@@ -44,7 +45,9 @@ export function BackButton(props: BackButtonProps) {
       accessibilityLabel={accessibilityLabel}
       userSelect="none"
       onPress={onPress}
-      style={{ flexDirection: "row", alignItems: "center", gap: 8, alignSelf: "flex-start", borderRadius: 999, paddingRight: 14 }}
+      // Going back ACTS, exactly as the bare variant's `IconButton` does —
+      // without this, one component shows two cursors decided by a label.
+      style={{ cursor: CURSOR_ACTION, flexDirection: "row", alignItems: "center", gap: 8, alignSelf: "flex-start", borderRadius: 999, paddingRight: 14 }}
     >
       <View style={{ width: 40, height: 40, borderRadius: 999, backgroundColor: colors.zinc[100], alignItems: "center", justifyContent: "center" }}>
         <Icon name="chevron-left" size={20} color={colors.zinc[900]} />

package/src/badge.tsx

@@ -15,8 +15,16 @@ interface BadgeProps {
    *   Light enough to sit anywhere without shouting. Reach for this by default.
    * - "tonal": a filled pill — HEAVY, and easy to overuse into clutter. Reserve
    *   it for the ONE prominent status of a surface (a drawer header, a register's
-   *   primary Status column). One per view, a deliberate choice — not sprinkled
-   *   through rows or option lists. If in doubt, use `dot`.
+   *   primary Status column). "One per view" counts badge KINDS, not rows: one
+   *   status column rendering on every row is ONE badge, while the stage plus the
+   *   type plus the city is the clutter this warns about. Not for option lists.
+   *   If in doubt, use `dot`.
+   *
+   *   In a TABLE CELL, pass `style={{ alignSelf: "flex-start" }}`: a cell
+   *   stretches its child, so a tonal pill fills the whole column otherwise. It
+   *   cannot be defaulted here — `flex-start` means left in a column-direction
+   *   parent and TOP in a row-direction one, which would misalign every badge
+   *   sitting inline beside text.
    * (StatusGrid/StatusLegend keep their own dot — raw hex coupled to the grid
    * cells' tint, a separate data-viz concern.)
    */

package/src/button.tsx

@@ -27,6 +27,35 @@ interface ButtonPropsBase {
   icon?: IconName;
   alignSelf?: "flex-start" | "flex-end" | "center" | "stretch" | "auto";
   color?: ButtonColor;
+  /**
+   * An action whose DESTINATION carries a brand of its own — an export that
+   * produces a spreadsheet, a sign-in with a named provider, a share into a
+   * service. Pass that brand's colour and the button wears it: a wash of it as
+   * the ground, the colour itself on the label and the mark.
+   *
+   * **Why this exists rather than a `style` escape hatch.** `ButtonColor` is a
+   * closed set on purpose — primary / secondary / danger are the kit's OWN
+   * vocabulary, and keeping it small is what lets a reader learn the ladder once.
+   * An outside brand genuinely is not on that ladder: it is not a status, not a
+   * valence, and not a palette family, so no named variant could ever cover it.
+   * The answer is a named CATEGORY with a colour slot, never a hole through
+   * which any call site can restyle any button — that is how a design system
+   * stops being one.
+   *
+   * It renders SOLID, with white ink — which is what a brand action looks like
+   * everywhere it appears, and what makes the colour recognisable at a glance
+   * rather than merely present. A tonal wash was tried first, on the reasoning
+   * that a second filled control competes with the surface's one primary; it
+   * reads as washed-out rather than restrained, and the hierarchy survives
+   * anyway because the primary keeps the last position and the affirmative verb.
+   *
+   * The cost is real and worth naming: a screen with several of these is a screen
+   * with no primary. Reach for it where a destination genuinely has a brand, not
+   * to make a button louder.
+   *
+   * Ignored on `primary` and `danger`, whose own colours are load-bearing.
+   */
+  brandColor?: string;
   loading?: boolean;
   disabled?: boolean;
   tooltip?: string | UseTooltipOptions;
@@ -59,11 +88,15 @@ export function Button(props: ButtonProps) {
     onPress,
     testID,
     accessibilityLabel,
+    brandColor,
   } = props;
 
   // The press waits out an inline commit the same gesture started (pending_commits.ts)
   // and reports busy while it does — so `busy`, not the `loading` prop alone, drives the
   // spinner, aria-busy, and the double-press block.
+  // Ignored on the variants whose colour MEANS something: a primary that is not
+  // the surface's primary colour, or a danger that is not red, would be lying.
+  const brand = color === "primary" || color === "danger" || color === "danger-secondary" ? undefined : brandColor;
   const { handlePress, waiting } = useGatedPress<NativeSyntheticEvent<any>>(onPress);
   const busy = loading || waiting;
   const disabledOrLoading = disabled || busy;
@@ -77,14 +110,16 @@ export function Button(props: ButtonProps) {
       ) : (
         <>
           {!!icon && (
-            <Icon size={20} name={icon} color={getButtonIconColor(color, disabledOrLoading)} />
+            <Icon size={20} name={icon} color={brand && !disabledOrLoading ? colors.white : getButtonIconColor(color, disabledOrLoading)} />
           )}
           {!!title && (
             <Text
               numberOfLines={1}
               size="sm"
               weight="medium"
-              color={getButtonTextColor(color, disabledOrLoading)}
+              // `inverted` — the kit's own white-on-dark ink, the same token the primary
+              // uses, so a brand button and the primary read as one family.
+              color={brand && !disabledOrLoading ? "inverted" : getButtonTextColor(color, disabledOrLoading)}
               userSelect="none"
             >
               {title}
@@ -116,11 +151,16 @@ export function Button(props: ButtonProps) {
             borderRadius: CONTROL_RADIUS,
             backgroundColor: disabled
               ? getButtonDisabledBackgroundColor(color)
-              : pressed
-                ? getButtonPressedColor(color)
-                : hovered
-                  ? getButtonHoverColor(color)
-                  : getButtonBackgroundColor(color),
+              : brand
+                ? // Solid, darkening under the pointer — the same depth ladder the
+                  // primary walks, so a brand button behaves like a button rather
+                  // than like a coloured label.
+                  shade(brand, pressed ? 0.78 : hovered ? 0.88 : 1)
+                : pressed
+                  ? getButtonPressedColor(color)
+                  : hovered
+                    ? getButtonHoverColor(color)
+                    : getButtonBackgroundColor(color),
           },
           // Subtle depth on the primary: a soft drop shadow lifts it off the
           // surface and a whisper of top highlight + a gentle vertical shade (the
@@ -169,10 +209,31 @@ export function getButtonTextColor(color?: ButtonColor, disabled?: boolean): Tex
   }
 }
 
+/**
+ * A brand colour at `factor` of its own lightness — the hover/press steps for a
+ * solid brand button.
+ *
+ * Multiplying the channels rather than blending toward black keeps the hue: a
+ * dark green stays green as it darkens, where mixing with black walks it toward
+ * grey and the recognition goes with it. Returns the input unchanged for a value
+ * it cannot parse, so an unusual colour loses its pointer feedback rather than
+ * rendering as something else entirely.
+ */
+function shade(hex: string, factor: number): string {
+  const m = /^#([0-9a-f]{6})$/i.exec(hex.trim());
+  if (!m || factor === 1) return hex;
+  const n = parseInt(m[1], 16);
+  const ch = [(n >> 16) & 255, (n >> 8) & 255, n & 255].map((v) => Math.round(v * factor));
+  return `rgb(${ch[0]}, ${ch[1]}, ${ch[2]})`;
+}
+
 function getButtonBackgroundColor(color?: ButtonColor) {
   switch (color) {
     case "primary":
-      return colors.zinc["900"];
+      // The themeable role, whose DEFAULT is this exact near-black — so an app
+      // that sets no theme renders identical pixels, and one that sets `primary`
+      // puts its brand on the surface's single filled button.
+      return colors.primary;
     case "secondary":
       return colors.zinc["100"];
     case "danger":

package/src/check_circle.tsx

@@ -118,8 +118,7 @@ const styles = StyleSheet.create({
   tap: {
     alignItems: "center",
     justifyContent: "center",
-    // @ts-ignore rn-web
-    cursor: "pointer",
+    cursor: "auto",
   },
   disabled: { opacity: 0.4 },
   ring: {

package/src/checkbox_input.tsx

@@ -1,7 +1,7 @@
 import { useCallback } from "react";
 import { Pressable } from "react-native";
 import { Checkbox } from "./checkbox";
-import { FOCUS_RING } from "./control_surface";
+import { CURSOR_DEFAULT, FOCUS_RING } from "./control_surface";
 import { useFocusRing } from "./use_focus_ring";
 interface CheckboxInputProps {
   /**
@@ -32,7 +32,7 @@ export function CheckboxInput(props: CheckboxInputProps) {
       onPress={handlePress}
       disabled={disabled}
       {...focusProps}
-      style={[{ opacity: disabled ? 0.5 : 1, borderRadius: 6 }, focusVisible && { boxShadow: FOCUS_RING }]}
+      style={[{ opacity: disabled ? 0.5 : 1, borderRadius: 6, cursor: CURSOR_DEFAULT }, focusVisible && { boxShadow: FOCUS_RING }]}
       // Use the W3C ARIA props directly: RN-web 0.21 no longer maps
       // `accessibilityState={{ checked }}` to `aria-checked`, which dropped the
       // checked state from the accessibility tree (a role="checkbox" with no

package/src/choice_list.tsx

@@ -6,7 +6,7 @@ import { Icon } from "./icon";
 import { Divider } from "./divider";
 import { composeHandler, useFocusRing } from "./use_focus_ring";
 import { useHover } from "./use_hover";
-import { CONTROL_RADIUS, FOCUS_RING, ROW_WASH_BLEED } from "./control_surface";
+import { CONTROL_RADIUS, CURSOR_DEFAULT, FOCUS_RING, ROW_WASH_BLEED } from "./control_surface";
 import { useAutoGrowHeight } from "./use_auto_grow_height";
 import { fontFamilyMedium, getInputTextStyle } from "./text_utils";
 import { useLoticsLocale } from "./locale";
@@ -55,7 +55,7 @@ function ChoiceRow({ option, selected, onSelect }: { option: ChoiceOption; selec
         // Bleeds like every other washed row, so the option TEXT sits on the
         // container's edge — level with the question above it, which no longer
         // has to hand-pad itself to match.
-        { flexDirection: "row", alignItems: "center", gap: 12, paddingVertical: 14, paddingHorizontal: ROW_WASH_BLEED, marginHorizontal: -ROW_WASH_BLEED, borderRadius: CONTROL_RADIUS },
+        { cursor: CURSOR_DEFAULT, flexDirection: "row", alignItems: "center", gap: 12, paddingVertical: 14, paddingHorizontal: ROW_WASH_BLEED, marginHorizontal: -ROW_WASH_BLEED, borderRadius: CONTROL_RADIUS },
         // Selected reads as a persistent tint (zinc-100); an unselected row only
         // washes on hover (zinc-50). The check below reserves its slot always.
         selected ? { backgroundColor: colors.zinc[100] } : hovered || pressed ? { backgroundColor: colors.zinc[50] } : null,

package/src/color_tokens.ts

@@ -292,8 +292,8 @@ const palette = {
 };
 
 /**
- * THE THREE THEMEABLE ROLES are `background`, `border` and `accent` — and
- * deliberately nothing else. See `colors.web.ts`, which redefines exactly
+ * THE FOUR THEMEABLE ROLES are `background`, `border`, `accent` and `primary` —
+ * and deliberately nothing else. See `colors.web.ts`, which redefines exactly
  * these as CSS variables so an app can carry its own identity.
  *
  * The line is drawn at MEANING, not at convenience. A palette family
@@ -327,6 +327,30 @@ export const colors = {
    * a palette family, so an accent can never overwrite a meaning.
    */
   accent: palette.blue["600"],
+  /**
+   * The PRIMARY action's fill — the one filled button on a surface.
+   *
+   * Separate from `accent` because their defaults differ and so do their jobs: a
+   * brand can own the disc a person is drawn as without owning the shape of a
+   * commit, and near-black is a deliberate neutral that works under any brand.
+   * Folding them would force an app that themes its avatars to also repaint every
+   * CTA, and would turn this near-black into blue for every app that themes
+   * nothing.
+   */
+  primary: palette.zinc["900"],
+  /**
+   * The brand's TINT — a row's hover, an active filter's ground, a header band.
+   *
+   * It exists as its own token because it cannot be derived where it is used:
+   * `withAlpha`/`tint` do string surgery on an `rgba()`, and on web `accent` is a
+   * `var()`, so asking for "accent at 7%" at the call site produces garbage no
+   * type would catch. `LoticsThemeProvider` computes it instead, from the literal
+   * hex the app handed it — derivation happens where the literal still exists.
+   *
+   * The default is the neutral wash these surfaces already wore, so an app that
+   * themes nothing is pixel-identical.
+   */
+  accent_wash: palette.zinc["100"],
   shadow: `0px 0px 6px 1px ${palette.zinc["300"]}`,
 };
 
@@ -357,7 +381,7 @@ export function withAlpha(color: string, alpha: number): string {
  */
 export type ColorName = Exclude<
   keyof typeof colors,
-  "border" | "border_shadow" | "background" | "accent" | "shadow" | "black" | "white"
+  "border" | "border_shadow" | "background" | "accent" | "accent_wash" | "primary" | "shadow" | "black" | "white"
 >;
 
 /**

package/src/colors.web.ts

@@ -4,7 +4,7 @@ export { withAlpha, solid, tint, ramp, isColorName, asColorName } from "./color_
 export type { ColorName } from "./color_tokens";
 
 /**
- * The token contract, with its FOUR themeable roles indirected through CSS
+ * The token contract, with its four themeable roles indirected through CSS
  * variables so an app can carry its own visual identity.
  *
  * Why this file exists at all, rather than a React context: 136 of the kit's 320
@@ -28,7 +28,7 @@ export type { ColorName } from "./color_tokens";
  * the strictest sense — an app that sets nothing has no `--lotics-*` defined,
  * every `var()` falls back, and the pixels are identical to before this file.
  *
- * ONLY these three. The palette families stay literal, and must: `withAlpha`,
+ * ONLY these five. The palette families stay literal, and must: `withAlpha`,
  * `tint` and `ramp` do string surgery on an `rgba()` to derive a wash, and a
  * `var()` handed to them would produce garbage no type would catch. Keeping the
  * themeable set to chrome keeps those functions total — the maintainability
@@ -40,4 +40,6 @@ export const colors = {
   background: `var(--lotics-background, ${contract.background})`,
   border: `var(--lotics-border, ${contract.border})`,
   accent: `var(--lotics-accent, ${contract.accent})`,
+  primary: `var(--lotics-primary, ${contract.primary})`,
+  accent_wash: `var(--lotics-accent-wash, ${contract.accent_wash})`,
 };

package/src/comments_button.tsx

@@ -2,7 +2,7 @@ import { StyleSheet, type GestureResponderEvent } from "react-native";
 import { colors } from "./colors";
 import { Icon } from "./icon";
 import { PressableHighlight } from "./pressable_highlight";
-import { ROW_CONTROL_HOVER, ROW_CONTROL_PRESS } from "./control_surface";
+import { CURSOR_ACTION, ROW_CONTROL_HOVER, ROW_CONTROL_PRESS } from "./control_surface";
 import { Text } from "./text";
 import { useLoticsLocale } from "./locale";
 
@@ -105,6 +105,8 @@ export function CommentsButton(props: CommentsButtonProps) {
 
 const styles = StyleSheet.create({
   button: {
+    // Opening the thread ACTS — see `CURSOR_ACTION`.
+    cursor: CURSOR_ACTION,
     flexDirection: "row",
     alignItems: "center",
     // Tight: the glyph and its number are ONE word, not two things in a row.

package/src/control_surface.ts

@@ -159,3 +159,30 @@ export function chipSurfaceStyle(
     boxShadow: selected ? `0 0 0 1px ${colors.zinc[900]}` : undefined,
   };
 }
+
+/**
+ * Which controls show a POINTER, and which show the arrow.
+ *
+ * **Only a control that ACTS ON ITS OWN gets the pointer** — a button, a link, a
+ * disclosure. Everything else takes the arrow: a row, a menu option, a card, a
+ * tab, a field trigger, a checkbox, a switch, a chip. The line is not "is it
+ * pressable" (nearly everything here is) but "does pressing it DO something, or
+ * does it set a value / open the thing you are already looking at".
+ *
+ * The reason to draw it tightly is that a signal on half the screen is not a
+ * signal. A pointer everywhere says only "this is a web page"; reserved, it
+ * marks the handful of things that act. What carries "you can press this"
+ * elsewhere is the hover treatment each surface already owns — a row's wash, a
+ * field's border, a chip's fill — which is the affordance a native list or menu
+ * uses too, where the cursor stays an arrow throughout.
+ *
+ * **The arrow is never the default and always has to be asked for.**
+ * react-native-web ships `cursor: pointer` inside `Pressable`'s own base style,
+ * so a component that says nothing gets a pointer. `PressableHighlight` and
+ * `FocusRingPressable` set the arrow for everything built on them, and a
+ * component on the bare `Pressable` sets it itself; the few that act set
+ * {@link CURSOR_ACTION} back over the top.
+ */
+export const CURSOR_DEFAULT = "auto";
+/** For a button, a link, a disclosure — see {@link CURSOR_DEFAULT}. */
+export const CURSOR_ACTION = "pointer";