@lotics/ui 43.4.0 → 43.5.0

package/src/avatar_props.ts

@@ -0,0 +1,66 @@
+import type { ImageContentFit, ImageSource } from "expo-image";
+import type { StyleProp, ViewStyle, ImageStyle } from "react-native";
+import { CONTROL_RADIUS } from "./control_surface";
+import type { AvatarSize } from "./avatar_size";
+
+/**
+ * THE prop surface both `Avatar` variants implement — the native `avatar.tsx`
+ * and the web `avatar.web.tsx`.
+ *
+ * It lives in a third module for the same reason `color_tokens` does: neither
+ * variant may own the contract, because only one of them is ever compiled. TypeScript
+ * resolves `./avatar` to the NATIVE file, so a prop added there typechecks
+ * everywhere while the web build — the one every custom-code app actually runs —
+ * silently ignores it. Nothing fails: no error, no warning, and the call site
+ * reads as correct. That is exactly how `shape` was added, verified against the
+ * types, and rendered as a circle.
+ *
+ * A shared interface cannot fix which FILE renders, but it does make the two
+ * implementations answer to one declaration, so a prop that exists in the type
+ * has a compiler-visible home in both. The behavioural half is `avatarShapeStyle`
+ * below: derived once here rather than written twice.
+ */
+export interface AvatarProps {
+  /** A rung on the shared avatar scale — never a pixel count. See
+   *  [`avatar_size`](./avatar_size.ts) for why the number was removed. */
+  size?: AvatarSize;
+  /**
+   * WHAT KIND OF THING this identifies — a person (`circle`, the default) or an
+   * organization (`square`, a rounded rect at `CONTROL_RADIUS`).
+   *
+   * It is a real axis, not decoration. A register of companies drawn with the
+   * same disc as a register of people asserts they are the same kind of entity,
+   * and the reader has nothing but the column header to correct it — so the mark
+   * that exists to make a row identifiable at a glance is the one element
+   * actively misleading them. The circle/square split is the convention every
+   * product carrying both uses, and it costs no colour and no space.
+   *
+   * Same component rather than a second one, per the kit's mode-is-a-variant
+   * rule: the scale, the initials rule, the accent ground, the image path and the
+   * a11y contract are all identical, and forking would give an organization its
+   * own drifting copy of every one of them.
+   */
+  shape?: "circle" | "square";
+  source?: ImageSource;
+  name?: string;
+  style?: StyleProp<ViewStyle | ImageStyle>;
+  contentFit?: ImageContentFit;
+  /**
+   * When true, the avatar announces its `name` to assistive tech. Default
+   * false because avatars almost always appear adjacent to the name text —
+   * announcing the image as well would double-read. Pass `announce` when the
+   * avatar is standalone (with no visible name nearby).
+   */
+  announce?: boolean;
+}
+
+/**
+ * The radius override a `shape` implies, or `null` for the default disc.
+ *
+ * A square mark takes the SAME radius as every other control-sized box on the
+ * page rather than a number picked for this component, so an org mark sitting
+ * beside a button, a chip or an input corners identically instead of nearly so.
+ */
+export function avatarShapeStyle(shape: AvatarProps["shape"]): { borderRadius: number } | null {
+  return shape === "square" ? { borderRadius: CONTROL_RADIUS } : null;
+}

package/src/avatar_tone.ts

@@ -0,0 +1,79 @@
+import { colors } from "./colors";
+
+/**
+ * THE IDENTITY PALETTE — the ground an initials avatar is drawn on, derived from
+ * the name it shows.
+ *
+ * Every disc used to be `colors.accent`, on the argument that an avatar is "the
+ * one place a member LOOKS like the product". That argument holds for ONE avatar
+ * in a header. It fails in the place avatars actually live: a register of twenty
+ * people renders twenty identical circles, so the only thing distinguishing one
+ * person from another is two letters at 14px — and the largest, most colourful
+ * element in the row carries no information at all. A mark whose whole job is
+ * making a row identifiable at a glance should not be the one part of it that is
+ * the same on every row.
+ *
+ * Handing the hue to the NAME makes the colour carry identity too: the same
+ * person is the same colour on every screen, and a reader learns "Nguyễn Vi is
+ * the violet one" without being told. The brand did not lose anything — it moved
+ * to the chrome it belongs in (the active tab, the selection wash, the primary
+ * action), which is shared across apps and learned once.
+ *
+ * Contrast is why the set is CURATED rather than "every family":
+ * - every entry is AA against white text at the shade named here, which the warm
+ *   and green families are NOT at 600 (amber-600 measures ~2.9:1) — so those take
+ *   700 or stay out;
+ * - `red` and `amber` are excluded entirely. They mean danger and waiting
+ *   everywhere else in this system, and a person is not a warning. A palette that
+ *   can paint someone red makes every red on the screen ambiguous.
+ *
+ * The ORDER is interleaved, not spectral, and that is load-bearing. Listed by
+ * hue — blue, indigo, violet, purple, fuchsia, pink — six consecutive entries are
+ * six shades of the same purple, so any two names hashing to adjacent buckets get
+ * near-identical discs. On a real register that is what happened: ten contacts
+ * produced six marks in the violet-to-magenta range and the column read as one
+ * colour again. Adjacent indices are now far apart in hue, so near-collisions
+ * still look distinct.
+ */
+const IDENTITY_TONES: readonly string[] = [
+  colors.blue["600"],
+  colors.orange["700"],
+  colors.violet["600"],
+  colors.emerald["700"],
+  colors.fuchsia["700"],
+  colors.teal["700"],
+  colors.indigo["600"],
+  colors.pink["600"],
+  colors.cyan["700"],
+  colors.purple["600"],
+];
+
+/**
+ * The ground for `name`'s initials — stable for a given string, so one person
+ * keeps one colour across every screen and every session.
+ *
+ * The hash MIXES rather than sums, which fixes ANAGRAMS specifically: a plain
+ * character sum gives `Hai Dang` and `Dang Hai` the same disc, and reorderings
+ * are common in names (family name first or last, with or without a middle
+ * name). Multiplying by 31 per character makes position count; `|0` keeps it in
+ * int32 so the result is identical on every engine.
+ *
+ * It is NOT what fixed the clustering seen on a real register — the sum was
+ * already producing a healthy spread of buckets there, and the interleaved order
+ * above is what made that spread visible. Do not credit the hash for it.
+ *
+ * Whatever the arithmetic, this value is not STORED anywhere: it is recomputed on
+ * every render on every client, and the only thing making one person one colour
+ * is that the function is pure and never changes. Editing the hash or reordering
+ * `IDENTITY_TONES` repaints every person in the product.
+ *
+ * An empty or missing name falls to the first entry rather than throwing —
+ * `Avatar` already substitutes a locale placeholder, and a nameless avatar is a
+ * real state (a member still loading) that must render.
+ */
+export function avatarTone(name: string | undefined): string {
+  const s = name ?? "";
+  let h = 0;
+  for (let i = 0; i < s.length; i += 1) h = (h * 31 + s.charCodeAt(i)) | 0;
+  return IDENTITY_TONES[Math.abs(h) % IDENTITY_TONES.length];
+}

package/src/button.tsx

@@ -165,9 +165,22 @@ export function Button(props: ButtonProps) {
           // 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
           // app-icon technique) catch the light — premium, not skeuomorphic. The
-          // lift stays on hover/press; only the gradient drops so the wash shows.
+          // lift stays on hover/press; the rest gradient is replaced by a flat
+          // overlay so the state reads without losing the themed ground.
           isPrimary && { boxShadow: "inset 0 1px 0 rgba(255,255,255,0.08), 0 1px 2px rgba(0,0,0,0.18)" },
-          restPrimary && { backgroundImage: `linear-gradient(180deg, ${colors.zinc["700"]} 0%, ${colors.zinc["900"]} 100%)` },
+          // A LIGHT overlay, not a zinc one. This painted
+          // `linear-gradient(zinc-700 → zinc-900)` — opaque, hard-coded, and drawn
+          // ON TOP of the background — so a themed `colors.primary` was resolved
+          // correctly underneath and then completely covered up. The button read
+          // near-black in every app, and "primary cannot be themed" looked true
+          // while the token had been right all along. A translucent white wash
+          // reproduces the same lit-from-above sheen over ANY hue, which also
+          // means it cannot go stale against a palette change.
+          restPrimary && { backgroundImage: "linear-gradient(180deg, rgba(255,255,255,0.14) 0%, rgba(255,255,255,0) 100%)" },
+          // Hover/press ride the SAME ground, lifted by a flat overlay, so the
+          // brand stays on screen through every state instead of only at rest.
+          isPrimary && pressed && { backgroundImage: `linear-gradient(0deg, ${PRIMARY_OVERLAY.press}, ${PRIMARY_OVERLAY.press})` },
+          isPrimary && !pressed && hovered && { backgroundImage: `linear-gradient(0deg, ${PRIMARY_OVERLAY.hover}, ${PRIMARY_OVERLAY.hover})` },
           styles.button,
           style,
           alignSelf && { alignSelf },
@@ -227,6 +240,21 @@ function shade(hex: string, factor: number): string {
   return `rgb(${ch[0]}, ${ch[1]}, ${ch[2]})`;
 }
 
+/**
+ * The primary button's hover / press lift, as a translucent WHITE overlay.
+ *
+ * Every state of a themeable control has to derive from its token, and on web a
+ * token is a `var()` — a string no colour maths can read, so "the same colour a
+ * bit lighter" cannot be computed at the call site. An overlay sidesteps that
+ * entirely: it lightens whatever is underneath, so one pair of values works for
+ * near-black, cobalt, teal or anything an app sets, and it can never go stale
+ * against a palette it does not know about.
+ *
+ * The direction matches what the hard-coded zinc steps did (zinc-900 → 700 →
+ * 600): both states LIFT, and press lifts further than hover.
+ */
+const PRIMARY_OVERLAY = { hover: "rgba(255,255,255,0.16)", press: "rgba(255,255,255,0.26)" };
+
 function getButtonBackgroundColor(color?: ButtonColor) {
   switch (color) {
     case "primary":
@@ -259,7 +287,10 @@ function getButtonDisabledBackgroundColor(color?: ButtonColor) {
 function getButtonHoverColor(color?: ButtonColor) {
   switch (color) {
     case "primary":
-      return colors.zinc["700"];
+      // The TOKEN, unchanged — the lift is an overlay, not a lighter zinc. See
+      // `PRIMARY_OVERLAY`. Returning zinc-700 here meant a themed button was the
+      // brand at rest and grey the instant a pointer touched it.
+      return colors.primary;
     case "secondary":
       return colors.zinc["200"];
     case "danger":
@@ -274,7 +305,8 @@ function getButtonHoverColor(color?: ButtonColor) {
 function getButtonPressedColor(color?: ButtonColor) {
   switch (color) {
     case "primary":
-      return colors.zinc["600"];
+      // The TOKEN, unchanged — see `getButtonHoverColor`.
+      return colors.primary;
     case "secondary":
       return colors.zinc["300"];
     case "danger":

package/src/checkbox.tsx

@@ -25,7 +25,10 @@ export function Checkbox(props: CheckboxProps) {
         alignItems: "center",
         borderWidth: 1,
         borderColor: colors.border,
-        backgroundColor: filled ? colors.zinc["800"] : colors.background,
+        // The ticked fill is the app's PRIMARY colour, not a fixed near-black.
+        // "on" is the same claim the one filled button makes, so it reads from
+        // the same token and a themed app gets a branded tick for free.
+        backgroundColor: filled ? colors.primary : colors.background,
         borderRadius: 6,
       }}
     >

package/src/choice_list.tsx

@@ -8,7 +8,7 @@ import { composeHandler, useFocusRing } from "./use_focus_ring";
 import { useHover } from "./use_hover";
 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 { fontFamilyMedium, getInputTextStyle, INPUT_LETTER_SPACING } from "./text_utils";
 import { useLoticsLocale } from "./locale";
 
 // A typed custom answer must read exactly like a picked option's LABEL (`Text
@@ -16,7 +16,7 @@ import { useLoticsLocale } from "./locale";
 // 14 on desktop = the sm label, 16 on mobile to defeat iOS-Safari focus-zoom — and the
 // size useAutoGrowHeight is tuned to); this override only aligns the family, tracking,
 // and colour to the label, which is where an unstyled input actually diverges from it.
-const ANSWER_LABEL_FONT = { fontFamily: fontFamilyMedium, letterSpacing: -0.4, color: colors.zinc[900] } as const;
+const ANSWER_LABEL_FONT = { fontFamily: fontFamilyMedium, letterSpacing: INPUT_LETTER_SPACING, color: colors.zinc[900] } as const;
 
 export interface ChoiceOption {
   label: string;
@@ -73,7 +73,9 @@ function ChoiceRow({ option, selected, onSelect }: { option: ChoiceOption; selec
         ) : null}
       </View>
       <View style={{ width: 17, alignItems: "center" }}>
-        {selected ? <Icon name="check" size={17} color={colors.zinc[900]} /> : null}
+        {/* The tick is a "this is on" mark like a checkbox's fill or a switch's
+            track, so it reads the primary token rather than a fixed near-black. */}
+        {selected ? <Icon name="check" size={17} color={colors.primary} /> : null}
       </View>
     </Pressable>
   );

package/src/color_tokens.ts

@@ -315,9 +315,8 @@ export const colors = {
   /** A RAISED surface — Card, Drawer, Modal, the things that sit on the page. */
   background: palette.white,
   /**
-   * The one brand hue, and its reach is narrower than the word suggests: it
-   * paints IDENTITY marks — today the avatar's initials disc, the one place a
-   * person is rendered as a coloured shape, on every register in every app.
+   * The one brand hue. It paints "WHERE YOU ARE" — the active tab's underline,
+   * the selected row's ground, an active filter — and IDENTITY chrome.
    *
    * It deliberately does NOT paint interaction chrome. The focus ring is
    * `zinc[900]` and the primary action is near-black because those are the KIT's
@@ -328,14 +327,13 @@ export const colors = {
    */
   accent: palette.blue["600"],
   /**
-   * The PRIMARY action's fill — the one filled button on a surface.
+   * The PRIMARY action's fill — the one filled button on a surface, and every
+   * other "this is on": a ticked checkbox, a switch's track, a selected day.
    *
-   * 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.
+   * Separate from `accent` because their jobs differ: an app can own the hue that
+   * says WHERE YOU ARE without owning the shape of a COMMIT, and a near-black
+   * commit reads under any brand. Folding them would force an app that themes its
+   * accent to also repaint every CTA.
    */
   primary: palette.zinc["900"],
   /**
@@ -344,13 +342,16 @@ export const colors = {
    * 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
+   * type would catch. `applyLoticsTheme` 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.
+   * The default is DERIVED FROM `accent`'s default, not picked separately: the
+   * accent is blue-600, so the wash is blue-50. It was zinc-100, which meant the
+   * two halves of one token pair disagreed and every unthemed app got a
+   * colourless "you are here"; a wash that contradicts its own accent is not a
+   * neutral default, it is a second brand nobody chose.
    */
-  accent_wash: palette.zinc["100"],
+  accent_wash: palette.blue["50"],
   shadow: `0px 0px 6px 1px ${palette.zinc["300"]}`,
 };
 

package/src/composer.tsx

@@ -3,7 +3,7 @@ import { View, TextInput as RNTextInput, ScrollView, StyleSheet, type TextInputP
 import { IconButton } from "./icon_button";
 import { colors } from "./colors";
 import { Text } from "./text";
-import { fontFamilyRegular, getInputTextStyle } from "./text_utils";
+import { fontFamilyRegular, getInputTextStyle, INPUT_LETTER_SPACING } from "./text_utils";
 import { useAutoGrowHeight } from "./use_auto_grow_height";
 import { useLoticsLocale } from "./locale";
 
@@ -220,7 +220,7 @@ export function Composer(props: ComposerProps) {
           wrap into clipped lines inside the pill — one line, ellipsized. */}
       {emptyText && placeholder ? (
         <View pointerEvents="none" style={[styles.placeholderOverlay, expanded ? styles.placeholderOverlayExpanded : { paddingHorizontal: 10 }]}>
-          <Text size="sm" numberOfLines={1} style={{ color: colors.zinc[500], letterSpacing: -0.4 }}>
+          <Text size="sm" numberOfLines={1} style={{ color: colors.zinc[500], letterSpacing: INPUT_LETTER_SPACING }}>
             {placeholder}
           </Text>
         </View>
@@ -346,6 +346,6 @@ const styles = StyleSheet.create({
   textInput: {
     flex: 1,
     fontFamily: fontFamilyRegular,
-    letterSpacing: -0.4,
+    letterSpacing: INPUT_LETTER_SPACING,
   },
 });

package/src/control_surface.ts

@@ -106,12 +106,27 @@ export const FOCUS_RING = `0 0 0 ${FOCUS_RING_WIDTH}px ${colors.zinc[900]}`;
  */
 export const CONTROL_TEXT_INSET = 9;
 
-/** A bordered control's pointer-hover edge: the resting `border` darkens to this on
- *  hover — the premium "this is interactive" affordance that complements the focus
- *  ring (focus = the ring; hover = a darker border). Drive it with `useHover` on a
- *  TextInput/select, or a Pressable's built-in `hovered` state. Pair with
- *  `CONTROL_TRANSITION` so the change eases in. */
-export const HOVER_BORDER = colors.zinc[400];
+/**
+ * THE hover edge for every bordered control — the resting `border` darkens to
+ * this. Focus is the ring; hover is a darker border; those are the only two, and
+ * a control that adds a third signal of its own breaks the pattern for all of
+ * them. Drive it with `useHover` on a TextInput/select or a Pressable's built-in
+ * `hovered`, and pair it with `CONTROL_TRANSITION` so the change eases in.
+ *
+ * zinc-500, not zinc-400. At 400 the shift was zinc-200 → zinc-400 on a 1px
+ * line — measurably a change and visually almost nothing, which is exactly why
+ * `InlineEdit` had grown a background TINT on top to compensate. That left the
+ * kit with two hover languages: most inputs moved their border, one also washed
+ * its surface, and a reader crossing a form met both. The answer is one signal
+ * carried properly rather than a second signal bolted on, so the border does the
+ * work everywhere and nothing tints.
+ *
+ * It stays NEUTRAL rather than taking the accent: hover means "your pointer is
+ * here", which is transient and true of whatever you happen to be over, while
+ * the accent means "you are here" — a state the screen holds. Painting both in
+ * the brand would make the brand the least informative colour on the page.
+ */
+export const HOVER_BORDER = colors.zinc[500];
 
 /**
  * The wash a control paints when it rides a HOVERABLE surface — a register row,
@@ -154,9 +169,22 @@ export function chipSurfaceStyle(
     justifyContent: "center",
     borderRadius: CONTROL_RADIUS,
     borderWidth: 1,
-    borderColor: selected ? colors.zinc[900] : colors.border,
-    backgroundColor: state.pressed ? colors.zinc[200] : state.hovered ? colors.zinc[100] : colors.white,
-    boxShadow: selected ? `0 0 0 1px ${colors.zinc[900]}` : undefined,
+    // A SELECTED chip needs a GROUND, not a heavier outline. This drew
+    // zinc-900 at 2px on a white fill — and in a toolbar where every sibling is
+    // also a white pill with a 1px border, "which filter is on" came down to a
+    // one-pixel colour change that reads as noise at a glance. The accent wash
+    // is the same "you are here" ground the active tab and the selected row
+    // carry, so one signal means one thing across the product; it also stays
+    // clear of the primary button's near-black fill, which a dark chip would
+    // have collided with two controls away.
+    borderColor: selected ? colors.accent : colors.border,
+    backgroundColor: selected
+      ? colors.accent_wash
+      : state.pressed
+        ? colors.zinc[200]
+        : state.hovered
+          ? colors.zinc[100]
+          : colors.white,
   };
 }
 

package/src/copy_button.tsx

@@ -13,7 +13,14 @@ export interface CopyButtonProps {
    *  the pack's bare verb. */
   label?: string;
   /** `sm` (the default, 24px) sits beside body/sm text — a value in a register
-   *  cell or a detail row. `md` (28px) for a toolbar. */
+   *  cell or a detail row — because 24 IS the `sm` line box, so the control adds
+   *  nothing to the line's height. `md` (28px) for a toolbar.
+   *
+   *  On a SMALLER line (an `xs` supporting line, 18px) there is no matching rung,
+   *  and dropping `sm` on it makes the row 24 — the text then sits 3px lower than
+   *  the same supporting line one column over. Pin that row's `height` to the
+   *  text's leading and let this overflow it; see `docs/composition.md`
+   *  §"The register's own craft" for the rule and `tpl_item_list` for the worked line. */
   size?: "sm" | "md";
   disabled?: boolean;
   testID?: string;

package/src/counter.tsx

@@ -56,6 +56,6 @@ export function Counter(props: CounterProps) {
 
 const styles = StyleSheet.create({
   row: { flexDirection: "row", alignItems: "center", gap: 16, alignSelf: "flex-start" },
-  btn: { width: 32, height: 32, borderWidth: 1, borderColor: colors.zinc[300] },
+  btn: { width: 32, height: 32, borderWidth: 1, borderColor: colors.border },
   value: { minWidth: 56 },
 });

package/src/data_grid.tsx

@@ -150,7 +150,10 @@ function SortLabel(props: { label: string; sortKey: string; sortable: boolean; s
   if (!sortable) {
     return (
       <View style={[styles.sortLabel, style]}>
-        <Text size="xs" weight="semibold" color="muted" numberOfLines={1} style={styles.headLabel}>{label}</Text>
+        {/* The SAME header treatment as `Table`, which owns the reason —
+            `DataGrid` and `Table` are one surface to a reader, so they cannot
+            label their columns differently. */}
+        <Text size="sm" weight="medium" color="muted" numberOfLines={1}>{label}</Text>
       </View>
     );
   }
@@ -158,7 +161,8 @@ function SortLabel(props: { label: string; sortKey: string; sortable: boolean; s
   const dirText = active ? (sort?.dir === "asc" ? (labels?.ascending ?? ", ascending") : (labels?.descending ?? ", descending")) : "";
   return (
     <FocusRingPressable onPress={() => onSort?.(sortKey)} accessibilityRole="button" accessibilityLabel={`${sortByLabel}${dirText}`} style={({ hovered }: { hovered?: boolean }) => [styles.sortLabel, styles.sortLabelPressable, hovered ? styles.sortLabelHover : null, style]}>
-      <Text size="xs" weight="semibold" color={active ? "default" : "muted"} numberOfLines={1} style={styles.headLabel}>{label}</Text>
+      {/* Active steps up in INK, not weight — see `SortHeader`. */}
+      <Text size="sm" weight="medium" color={active ? "default" : "muted"} numberOfLines={1}>{label}</Text>
       {arrow ? <Icon name={arrow} size={12} color={colors.zinc[500]} /> : null}
     </FocusRingPressable>
   );
@@ -181,7 +185,6 @@ const styles = StyleSheet.create({
     borderBottomColor: colors.zinc[100],
     marginBottom: 4,
   },
-  headLabel: { letterSpacing: 0.3, textTransform: "uppercase" },
   // Padded for the hover pill but zero-width in flow (negative margin), so the label
   // sits on its cell's edge instead of 8px inside it.
   sortLabel: { flexDirection: "row", alignItems: "center", gap: 4, paddingHorizontal: 6, marginHorizontal: -6, paddingVertical: 2, borderRadius: 6 },

package/src/date_calendar.tsx

@@ -832,7 +832,9 @@ const styles = StyleSheet.create({
     borderRadius: 999,
   },
   dayCircleSelected: {
-    backgroundColor: colors.zinc["800"],
+    // The picked day is the calendar's one filled mark — the same claim as a
+    // ticked checkbox or the primary button, so it reads the same token.
+    backgroundColor: colors.primary,
   },
   dayCircleHovered: {
     backgroundColor: colors.zinc["50"],
@@ -843,7 +845,7 @@ const styles = StyleSheet.create({
     width: 4,
     height: 4,
     borderRadius: 2,
-    backgroundColor: colors.zinc["800"],
+    backgroundColor: colors.primary,
   },
   todayDotInverted: {
     backgroundColor: colors.white,

package/src/date_range_filter_field.tsx

@@ -132,7 +132,11 @@ export function DateRangeFilterField(props: DateRangeFilterFieldProps) {
             paddingVertical: 9,
             paddingHorizontal: 12,
             borderWidth: 1,
-            borderColor: state.hovered ? HOVER_BORDER : colors.zinc[300],
+            // `colors.border` like every other control — this rested a step
+            // heavier for no stated reason, which is the same outlier
+            // `SearchInput` was: one control in a band with a darker edge reads
+            // as an accident rather than as emphasis.
+            borderColor: state.hovered ? HOVER_BORDER : colors.border,
             borderRadius: CONTROL_RADIUS,
             backgroundColor: colors.white,
             ...CONTROL_TRANSITION,

package/src/date_segments_field.tsx

@@ -11,7 +11,7 @@ import {
 } from "react-native";
 import { colors } from "./colors";
 import { Text } from "./text";
-import { fontFamilyRegular, getInputTextStyle } from "./text_utils";
+import { fontFamilyRegular, getInputTextStyle, INPUT_LETTER_SPACING } from "./text_utils";
 import {
   SegmentBuffer,
   SegmentLabels,
@@ -449,7 +449,7 @@ const styles = StyleSheet.create({
   segment: {
     ...getInputTextStyle(),
     fontFamily: fontFamilyRegular,
-    letterSpacing: -0.4,
+    letterSpacing: INPUT_LETTER_SPACING,
     color: colors.zinc["900"],
     textAlign: "center",
     paddingVertical: 0,

package/src/file_drop_target.web.tsx

@@ -112,7 +112,7 @@ const styles = StyleSheet.create({
   // box-shadow/background — zero layout impact, so nothing shifts mid-drag.
   dragging: {
     borderRadius: 12,
-    backgroundColor: colors.blue[50],
-    boxShadow: `0 0 0 1.5px ${colors.blue[500]}, 0 0 0 6px ${colors.blue[50]}`,
+    backgroundColor: colors.accent_wash,
+    boxShadow: `0 0 0 1.5px ${colors.accent}, 0 0 0 6px ${colors.accent_wash}`,
   },
 });

package/src/file_dropzone.tsx

@@ -99,9 +99,9 @@ export function FileDropzone(props: FileDropzoneProps) {
           ]}
         >
           <View style={[styles.iconWell, dragging ? styles.iconWellDragging : null]}>
-            <Icon name="upload" size={20} color={dragging ? colors.blue[600] : colors.zinc[500]} />
+            <Icon name="upload" size={20} color={dragging ? colors.accent : colors.zinc[500]} />
           </View>
-          <Text size="sm" weight="medium" style={dragging ? { color: colors.blue[700] } : undefined}>
+          <Text size="sm" weight="medium" style={dragging ? { color: colors.accent } : undefined}>
             {dragging ? dropLabel : label}
           </Text>
           {!dragging && hint ? (
@@ -133,10 +133,13 @@ const styles = StyleSheet.create({
     backgroundColor: colors.zinc[100],
   },
   // The drop invitation: accent border + tinted well — unmistakably "this is
-  // where your files land".
+  // where your files land". THE TOKEN, not a literal blue: the comment already
+  // said "accent" while the value was a fixed hue, so a themed app's most
+  // conspicuous state — a whole region lighting up under a dragged file — was
+  // the one that stayed brand blue.
   zoneDragging: {
-    borderColor: colors.blue[500],
-    backgroundColor: colors.blue[50],
+    borderColor: colors.accent,
+    backgroundColor: colors.accent_wash,
   },
   zoneDisabled: {
     opacity: 0.5,
@@ -149,7 +152,10 @@ const styles = StyleSheet.create({
     justifyContent: "center",
     backgroundColor: colors.zinc[100],
   },
+  // WHITE on the wash rather than a deeper tint of it. The deeper tint has no
+  // token — `withAlpha` cannot derive one from a themed `var()` — and a lifted
+  // white disc reads as raised at every hue, which the two-tone did only at one.
   iconWellDragging: {
-    backgroundColor: colors.blue[100],
+    backgroundColor: colors.white,
   },
 });

package/src/file_rows.tsx

@@ -43,6 +43,21 @@ export interface FileRowsProps {
   onError?: (error: unknown, meta: { fileId: string; mimeType: string }) => void;
   /** Translated chrome — Download / Remove / Open-external / gallery + confirm. */
   labels?: Partial<GalleryLabels>;
+  /**
+   * WHAT PRESSING A ROW DOES. Default `"preview"`.
+   *
+   * Not a switch for turning the gallery off — a statement about what the files
+   * ARE. A scan, a photo, a screenshot is something you LOOK at and move on
+   * from, and a full-screen preview is the whole interaction. A contract, a
+   * recording, a spreadsheet is something you WORK on, and a lightbox inside a
+   * drawer is a dead end: you cannot sign it, edit it, or send it from there, so
+   * every press costs a dismiss before the real act.
+   *
+   * `"open"` requires `onOpenExternal` — without a way out, the row would be a
+   * door onto nothing — and it stops mounting the gallery at all, so a surface
+   * that never previews pays nothing for the engines it does not use.
+   */
+  press?: "preview" | "open";
   /** Gap between rows. Default 8. */
   gap?: number;
   /** Credentials mode for the gallery's preview fetches — `"include"` for the
@@ -56,8 +71,11 @@ export interface FileRowsProps {
  * record's documents, a message's files. For an ADD/upload surface use `FileGrid`;
  * for bare square tiles use `FileThumbnailGrid`.
  */
-export function FileRows({ files, meta, onRemove, onOpenExternal, onDownload, onError, labels, gap = 8, credentials }: FileRowsProps) {
+export function FileRows({ files, meta, onRemove, onOpenExternal, onDownload, onError, labels, gap = 8, credentials, press = "preview" }: FileRowsProps) {
   const [activeIndex, setActiveIndex] = useState<number | null>(null);
+  // `open` without a way out would make every row a door onto nothing, so the
+  // preview stays the fallback rather than the press silently doing nothing.
+  const opens = press === "open" && onOpenExternal !== undefined;
   const l = { ...useLoticsLocale().gallery, ...labels };
 
   if (files.length === 0) return null;
@@ -96,11 +114,12 @@ export function FileRows({ files, meta, onRemove, onOpenExternal, onDownload, on
             name={file.filename}
             meta={meta ? meta(file) : undefined}
             mimeType={file.mimeType}
-            onPress={() => setActiveIndex(index)}
+            onPress={opens ? () => onOpenExternal(file) : () => setActiveIndex(index)}
             trailing={<ActionMenu accessibilityLabel={`${l.actions}: ${file.filename}`} items={items} />}
           />
         );
       })}
+      {opens ? null : (
       <FileGalleryModal
         files={files}
         activeIndex={activeIndex}
@@ -115,6 +134,7 @@ export function FileRows({ files, meta, onRemove, onOpenExternal, onDownload, on
         onError={onError}
         labels={labels}
       />
+      )}
     </View>
   );
 }