@lotics/ui 30.1.0 → 31.0.0

package/MIGRATION.md

@@ -4,6 +4,47 @@ 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.
 
+## 31.0.0 — avatar `size` is a rung, not a pixel count
+
+`Avatar`, `MemberChip` and `GroupAvatar` no longer take `size?: number`. They take
+`size?: AvatarSize` — `"sm" | "md" | "lg" | "xl"` = **24 / 36 / 48 / 72** — defaulting to `md`.
+
+Map an EXPLICIT size by the density it was reaching for, not by nearest pixel:
+
+| was | now |
+| --- | --- |
+| ≤ 24 (18, 20, 22, 24) | `"sm"` |
+| 28, 32, 36 | `"md"` |
+| 40, 48 | `"lg"` |
+| 64, 80 | `"xl"` |
+
+**The DEFAULT is now `md` (36) on all three components**, which is a separate move from that
+table and goes in different directions: `Avatar` grows (32 → 36), `MemberChip` grows (28 → 36),
+and **`GroupAvatar` shrinks (40 → 36)**. If a `GroupAvatar` was relying on its default to sit at
+40 beside something else, pass `"lg"`. One default is the point — a member and a group in one
+list had no business being different sizes.
+
+Need an avatar's pixels for a sibling box — a stack's overlap, a dashed placeholder? Import
+`AVATAR_PX` from `@lotics/ui/avatar_size` and index it by the rung, so the two cannot drift.
+
+**Three rendering changes come with it, and none is opt-in.**
+
+Initials are now the first and **last** word of the name rather than the first two: "Vũ Thị
+Lan" renders VL where it rendered VT. A Vietnamese name is họ + đệm + tên, so the first two
+words are the parts a whole office shares — on a real 29-person roster the old rule left 11
+people indistinguishable and this one leaves 5. Two-word names are unaffected ("John Smith" is
+JS either way), and it matches the conventional English rendering ("Mary Jane Watson" → MW).
+`GroupAvatar` follows the same rule now: it showed one letter at every size and its neighbours
+in the same list showed two.
+
+The one-initial cutoff moved from "≤ 32px" to "`sm` only". Anything you map to `md` or above
+now shows two letters where it showed one — which is the point: every call site in the
+register apps sat under the old threshold, so the product only ever rendered a single letter.
+If a surface genuinely wants one letter, that surface is `sm`.
+
+The initials' TYPE SIZE now follows the rung instead of being a fixed `xs`. Most visible on the
+large rungs: an avatar that was 80px wore 12px letters and looked empty; at `xl` it wears 28px.
+
 ## 30.0.0 — a washed row bleeds; content sits on the container's edge
 
 No API changed. Every register, table and choice list **moves its content 20px

package/docs/catalog.md

@@ -76,6 +76,20 @@ inline: a picker option, an assignee, a `select_member` value. Pure: resolve the
 your directory and pass `name` / `image`; never hand-roll `Avatar` + `Text`. (`MemberSelect`
 renders these per option.)
 
+**Size is a RUNG, never a pixel count** — `sm | md | lg | xl` = 24 / 36 / 48 / 72
+(`@lotics/ui/avatar_size`, shared by `Avatar`, `MemberChip` and `GroupAvatar`). Default `md`.
+The number was removed because the same concept had drifted to eleven different values across
+the product and its apps, so one person looked different on every screen. Pick by density:
+`sm` for a dense row or inline cell, `md` for a register or list (the default), `lg` for a
+prominent row or the account menu, `xl` for a profile's own header.
+
+**`sm` shows ONE initial; every larger rung shows two** — two letters are not legible at 24px.
+That is the practical reason not to reach for `sm` by reflex: on a real roster a single letter
+is rarely unique (nine people can share "N"), so a register that must identify someone wants
+`md`. Initials are the first and **last** word of the name — "Vũ Thị Lan" → VL, "Mary Jane
+Watson" → MW — because a Vietnamese name's first two words are the family and middle names
+that a whole office shares.
+
 ### A select-field value
 
 `OptionBadge` (a stored `select` value as its CONFIGURED colored badge) — never hand-map
@@ -425,12 +439,15 @@ source (`src/<module>.tsx`/`.ts`) is the API reference.
   `themeColor` palette token (unknown → neutral zinc) holding any Lucide icon by runtime
   name via `DynamicIcon`; `size` sm|md. One render wherever an app shows — launcher, list,
   picker, settings.
-- **`avatar`** — `Avatar`: image-or-initial person avatar (`source`/`name`/`size`;
-  `announce` when standalone — decorative by default because the name text usually sits
-  beside it).
-- **`group_avatar`** — `GroupAvatar`: the first letter of `name` in a zinc rounded square
-  (`size`, default 40); the avatar for image-less entities — groups, organizations. A person
-  → `Avatar`/`MemberChip`.
+- **`avatar`** — `Avatar`: image-or-initial person avatar (`source`/`name`/`size` — a rung,
+  see above; `announce` when standalone — decorative by default because the name text usually
+  sits beside it).
+- **`avatar_size`** — the shared avatar scale: `AvatarSize` (`sm|md|lg|xl`), `AVATAR_PX`,
+  `AVATAR_TEXT`, `avatarInitials`. Import `AVATAR_PX` when a sibling box must match an
+  avatar's pixels (a stack's overlap, a dashed placeholder) so the two cannot drift.
+- **`group_avatar`** — `GroupAvatar`: a name's initials in a zinc rounded square (`size` — the
+  same rung scale AND the same initials rule as `Avatar`, default `md`); the avatar for
+  image-less entities — groups, organizations. A person → `Avatar`/`MemberChip`.
 - **`wave_avatar`** — `WaveAvatar`: decorative animated waveform avatar (voice/audit
   history); animates on web, renders a static fallback on native.
 - **`member_chip`** — `MemberChip`: avatar + name; the universal person render.

package/docs/composition.md

@@ -402,6 +402,17 @@ running total. `tpl_item_list` is the reference. Paginate OUTSIDE (slice + `Pagi
 Right-hand columns align only if every trailing element is FIXED-width — give each trailing action
 a fixed `width`, so amount/status columns don't jitter.
 
+**Cells whose LINE COUNTS differ need `align="top"`.** Cells are centred by default, which is
+right while every cell is one line. The moment they are not — an identity cell carrying a
+supporting line (2), a status cell with a bar over a label (3), a member chip (1) — centring four
+different heights puts their four FIRST lines at four different heights, and the eye steps down
+and back up reading across one row. Measured on a live register: a 12px spread, closed to 2px by
+`align="top"`, which makes cells share a top edge so first lines land on one baseline. It governs
+the CELLS only; the ordinal, the leading checkbox and the trailing ⋯ stay centred, being one line
+by construction. Note a cell whose first element is a BAR or an image still starts its text below
+that element — top-aligning the cell does not top-align the text inside it, so put the line you
+want on the baseline first.
+
 ## Row actions are always-visible siblings — never hover-revealed, never nested
 
 A pressable row = a role-less surface (the hover/press wash covers the whole row) + an accessible

package/examples/tpl_attendance.tsx

@@ -141,7 +141,7 @@ function HomNayRow({ nv, selected, onPress }: { nv: NhanVien; selected: boolean;
     >
       <TableCell>
         <View style={{ flexDirection: "row", alignItems: "center", gap: 10 }}>
-          <Avatar name={nv.ten} size={36} />
+          <Avatar name={nv.ten} size="md" />
           <View style={{ flex: 1, gap: 2, minWidth: 0 }}>
             <Text weight="medium" numberOfLines={1}>{nv.ten}</Text>
             <Text size="sm" color="zinc-500" numberOfLines={1}>{nv.chucVu}</Text>
@@ -207,7 +207,7 @@ function NhanVienWorkspace({ nv }: { nv: NhanVien }) {
     <>
       <ScrollView style={{ flex: 1 }} contentContainerStyle={{ padding: 24, gap: 20 }}>
         <View style={{ flexDirection: "row", alignItems: "center", gap: 12 }}>
-          <Avatar name={nv.ten} size={40} />
+          <Avatar name={nv.ten} size="lg" />
           <View style={{ flex: 1, gap: 2 }}>
             <Text size="sm" color="muted">{nv.chucVu}</Text>
           </View>

package/examples/tpl_dashboard.tsx

@@ -257,7 +257,7 @@ function KhachPeek({ kh }: { kh: (typeof KHACH_DAN_DAU)[number] }) {
   return (
     <View style={{ gap: 10 }}>
       <View style={{ flexDirection: "row", alignItems: "center", gap: 10 }}>
-        <Avatar name={kh.ten} size={32} />
+        <Avatar name={kh.ten} size="md" />
         <View style={{ gap: 1, flex: 1 }}>
           <Text size="sm" weight="semibold">{kh.ten}</Text>
           <Text size="xs" color="muted">{kh.nganh}</Text>
@@ -500,7 +500,7 @@ export function TplDashboard() {
             <View key={kh.ten}>
               {i > 0 ? <Divider /> : null}
               <View style={{ paddingHorizontal: 20, paddingVertical: 12, flexDirection: "row", alignItems: "center", gap: 12 }}>
-                <Avatar name={kh.ten} size={32} />
+                <Avatar name={kh.ten} size="md" />
                 <View style={{ flex: 1, gap: 0, alignItems: "flex-start" }}>
                   <Peek accessibilityLabel={`Customer profile for ${kh.ten}`} content={<KhachPeek kh={kh} />}>
                     <Text size="sm" weight="medium" numberOfLines={1}>{kh.ten}</Text>

package/examples/tpl_shifts.tsx

@@ -283,7 +283,7 @@ export function TplShifts() {
                       onPress={() => setOpenSlot(slotId(su.day, su.shift))}
                       style={{ flex: 1, flexDirection: "row", alignItems: "center", gap: 12, minHeight: 52 }}
                     >
-                      <Avatar name={su.member} size={28} />
+                      <Avatar name={su.member} size="md" />
                       <View style={{ flex: 1, gap: 0 }}>
                         <Text size="sm" numberOfLines={1}>{su.member}</Text>
                         <Text size="xs" color="muted">{slotLabel(su.day, su.shift)}</Text>
@@ -344,7 +344,7 @@ export function TplShifts() {
               ) : (
                 openAssigned.map((m) => (
                   <View key={m} style={{ flexDirection: "row", alignItems: "center", gap: 10, minHeight: 36 }}>
-                    <Avatar name={m} size={28} />
+                    <Avatar name={m} size="md" />
                     <Text size="sm" style={{ flex: 1 }}>{m}</Text>
                     <Text size="xs" color="muted" tabular>{`${hoursOf(m)}h this week`}</Text>
                     <ActionMenu
@@ -362,7 +362,7 @@ export function TplShifts() {
                   const hoursAfter = hoursOf(su.member) + SHIFT_HOURS;
                   return (
                     <View key={su.id} style={{ flexDirection: "row", alignItems: "center", gap: 10, minHeight: 36 }}>
-                      <Avatar name={su.member} size={28} />
+                      <Avatar name={su.member} size="md" />
                       <Text size="sm" style={{ flex: 1 }}>{su.member}</Text>
                       <Text size="xs" color={hoursAfter > WEEK_LIMIT ? "danger" : "muted"} tabular>{`→ ${hoursAfter}h`}</Text>
                       {hoursAfter > WEEK_LIMIT ? (
@@ -398,7 +398,7 @@ export function TplShifts() {
                     return (
                       <MenuListItem
                         key={m}
-                        icon={<Avatar name={m} size={28} />}
+                        icon={<Avatar name={m} size="md" />}
                         title={m}
                         description={
                           after > WEEK_LIMIT

package/examples/tpl_task_board.tsx

@@ -322,7 +322,7 @@ export function TplTaskBoard() {
       out = STATUS_ORDER.map((s) => ({ key: s, header: <OptionBadge value={STATUS[s]} variant="dot" />, items: pool.filter((t) => t.status === s) }));
     } else if (groupBy === "assignee") {
       out = [
-        ...MEMBERS.map((m) => ({ key: m.id, header: <MemberChip name={m.name} size={22} />, items: pool.filter((t) => t.ownerId === m.id) })),
+        ...MEMBERS.map((m) => ({ key: m.id, header: <MemberChip name={m.name} size="sm" />, items: pool.filter((t) => t.ownerId === m.id) })),
         { key: "none", header: <Text size="sm" color="muted">Unassigned</Text>, items: pool.filter((t) => !t.ownerId) },
       ];
     } else {
@@ -348,11 +348,11 @@ export function TplTaskBoard() {
           </FilterChip>
           <FilterChip
             label="Assignee"
-            summary={assigneeFilter.length > 0 ? <View style={styles.summary}>{assigneeFilter.slice(0, 4).map((id) => <Avatar key={id} name={memberName(id)} size={20} />)}</View> : undefined}
+            summary={assigneeFilter.length > 0 ? <View style={styles.summary}>{assigneeFilter.slice(0, 4).map((id) => <Avatar key={id} name={memberName(id)} size="sm" />)}</View> : undefined}
             onClear={() => setAssigneeFilter([])}
             clearLabel="Clear assignee filter"
           >
-            <OptionList search={{ mode: "none" }} multi options={MEMBER_OPTS} value={assigneeFilter} onValueChange={setAssigneeFilter} renderOptionContent={(o) => <MemberChip name={o.label ?? memberName(o.value)} size={22} />} />
+            <OptionList search={{ mode: "none" }} multi options={MEMBER_OPTS} value={assigneeFilter} onValueChange={setAssigneeFilter} renderOptionContent={(o) => <MemberChip name={o.label ?? memberName(o.value)} size="sm" />} />
           </FilterChip>
           <FilterChip
             label="Tag"

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@lotics/ui",
-  "version": "30.1.0",
+  "version": "31.0.0",
   "type": "module",
   "exports": {
     "./vite": {
@@ -257,6 +257,7 @@
     "./text_utils": "./src/text_utils.ts",
     "./column_filter": "./src/column_filter.tsx",
     "./chip_group": "./src/chip_group.tsx",
+    "./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"

package/src/avatar.tsx

@@ -4,9 +4,12 @@ import { View, StyleSheet, StyleProp, ViewStyle, ImageStyle } from "react-native
 import { Text } from "./text";
 import { colors } from "./colors";
 import { useLoticsLocale } from "./locale";
+import { AVATAR_PX, AVATAR_TEXT, avatarInitials, type AvatarSize } from "./avatar_size";
 
 interface AvatarProps {
-  size?: number;
+  /** 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;
   source?: ImageSource;
   name?: string;
   style?: StyleProp<ViewStyle | ImageStyle>;
@@ -22,8 +25,9 @@ interface AvatarProps {
 
 export function Avatar(props: AvatarProps) {
   const locale = useLoticsLocale();
-  const { source, size = 32, name = locale.avatar.unknown, style, contentFit, announce } = props;
+  const { source, size = "md", name = locale.avatar.unknown, style, contentFit, announce } = props;
   const decorative = !announce;
+  const px = AVATAR_PX[size];
 
   if (!source || !source.uri) {
     return (
@@ -35,7 +39,7 @@ export function Avatar(props: AvatarProps) {
         aria-hidden={decorative || undefined}
         style={[
           styles.base,
-          { backgroundColor: colors.blue["600"], width: size, height: size },
+          { backgroundColor: colors.blue["600"], width: px, height: px },
           style,
         ]}
       >
@@ -43,14 +47,14 @@ export function Avatar(props: AvatarProps) {
             on the container so the SR does not read "HM" in addition. */}
         <Text
           userSelect="none"
-          size="xs"
+          size={AVATAR_TEXT[size]}
           weight="medium"
           color="inverted"
           accessibilityElementsHidden
           importantForAccessibility="no-hide-descendants"
           aria-hidden
         >
-          {getInitials(name, size)}
+          {avatarInitials(name, size)}
         </Text>
       </View>
     );
@@ -61,7 +65,7 @@ export function Avatar(props: AvatarProps) {
       alt={decorative ? "" : name}
       accessibilityElementsHidden={decorative}
       importantForAccessibility={decorative ? "no-hide-descendants" : undefined}
-      style={[styles.base, { width: size, height: size }, style as ImageStyle]}
+      style={[styles.base, { width: px, height: px }, style as ImageStyle]}
       source={source}
       contentFit={contentFit}
       cachePolicy="memory-disk"
@@ -69,23 +73,6 @@ export function Avatar(props: AvatarProps) {
   );
 }
 
-function getInitials(name: string, size?: number): string {
-  let initials = 2;
-
-  if (size && size <= 32) {
-    initials = 1;
-
-    if (name.length <= 2) {
-      return name;
-    }
-  }
-
-  return name
-    .split(" ")
-    .map((c) => c.charAt(0).toUpperCase())
-    .slice(0, initials)
-    .join("");
-}
 
 const styles = StyleSheet.create({
   base: {

package/src/avatar.web.tsx

@@ -3,9 +3,11 @@ import { Image, View, StyleSheet, StyleProp, ViewStyle, ImageStyle } from "react
 import { Text } from "./text";
 import { colors } from "./colors";
 import { useLoticsLocale } from "./locale";
+import { AVATAR_PX, AVATAR_TEXT, avatarInitials, type AvatarSize } from "./avatar_size";
 
 interface AvatarProps {
-  size?: number;
+  /** A rung on the shared avatar scale — never a pixel count. */
+  size?: AvatarSize;
   source?: ImageSource;
   name?: string;
   style?: StyleProp<ViewStyle | ImageStyle>;
@@ -30,8 +32,9 @@ interface AvatarProps {
  */
 export function Avatar(props: AvatarProps) {
   const locale = useLoticsLocale();
-  const { source, size = 32, name = locale.avatar.unknown, style, contentFit, announce } = props;
+  const { source, size = "md", name = locale.avatar.unknown, style, contentFit, announce } = props;
   const decorative = !announce;
+  const px = AVATAR_PX[size];
 
   if (!source || !source.uri) {
     return (
@@ -43,7 +46,7 @@ export function Avatar(props: AvatarProps) {
         aria-hidden={decorative || undefined}
         style={[
           styles.base,
-          { backgroundColor: colors.blue["600"], width: size, height: size },
+          { backgroundColor: colors.blue["600"], width: px, height: px },
           style,
         ]}
       >
@@ -51,14 +54,14 @@ export function Avatar(props: AvatarProps) {
             on the container so the SR does not read "HM" in addition. */}
         <Text
           userSelect="none"
-          size="xs"
+          size={AVATAR_TEXT[size]}
           weight="medium"
           color="inverted"
           accessibilityElementsHidden
           importantForAccessibility="no-hide-descendants"
           aria-hidden
         >
-          {getInitials(name, size)}
+          {avatarInitials(name, size)}
         </Text>
       </View>
     );
@@ -69,30 +72,13 @@ export function Avatar(props: AvatarProps) {
       accessibilityLabel={decorative ? undefined : name}
       accessibilityElementsHidden={decorative}
       importantForAccessibility={decorative ? "no-hide-descendants" : undefined}
-      style={[styles.base, { width: size, height: size }, style as ImageStyle]}
+      style={[styles.base, { width: px, height: px }, style as ImageStyle]}
       source={{ uri: source.uri }}
       resizeMode={contentFit === "contain" ? "contain" : "cover"}
     />
   );
 }
 
-function getInitials(name: string, size?: number): string {
-  let initials = 2;
-
-  if (size && size <= 32) {
-    initials = 1;
-
-    if (name.length <= 2) {
-      return name;
-    }
-  }
-
-  return name
-    .split(" ")
-    .map((c) => c.charAt(0).toUpperCase())
-    .slice(0, initials)
-    .join("");
-}
 
 const styles = StyleSheet.create({
   base: {

package/src/avatar_size.ts

@@ -0,0 +1,77 @@
+import type { TextSize } from "./text";
+
+/**
+ * ONE scale for every avatar in the product — `Avatar`, `MemberChip`,
+ * `GroupAvatar`.
+ *
+ * It replaces a free `size?: number`, and the reason is not tidiness. Across the
+ * product and the apps that number had been given ELEVEN different values for the
+ * same concept (18, 20, 22, 24, 28, 32, 36, 40, 48, 64, 80), which is what made a
+ * person look different depending on which screen you met them on. A closed scale
+ * cannot drift that way, and it lets the initials rule below key off a rung the
+ * component actually knows rather than an arbitrary pixel count.
+ */
+export type AvatarSize = "sm" | "md" | "lg" | "xl";
+
+export const AVATAR_PX: Record<AvatarSize, number> = {
+  /** Dense rows and inline chips — one initial, because two do not fit. */
+  sm: 24,
+  /** The default: registers, lists, anywhere a person is a row. */
+  md: 36,
+  /** Prominent rows, the account menu. */
+  lg: 48,
+  /** A profile's own header. */
+  xl: 72,
+};
+
+/**
+ * The initials' type size, so a large avatar does not wear tiny letters — the
+ * old fixed `xs` made an 80px circle look empty.
+ *
+ * Measured in the gallery on web (a `TextSize` resolves to different pixels on
+ * native, and `text.css` moves again at 768px, so these are the desktop numbers
+ * and only a render can give them):
+ *
+ *   sm  12 on 24 = 50%   ·  md  14 on 36 = 39%
+ *   lg  20 on 48 = 42%   ·  xl  32 on 72 = 44%
+ *
+ * The two-letter rungs sit within 6 points of each other, so an avatar reads the
+ * same at every size rather than growing emptier as it grows — `lg` was on `md`
+ * type (16 on 48 = 33%) and was visibly the thin one. `sm` runs richer by design:
+ * one letter in a small circle needs the weight.
+ */
+export const AVATAR_TEXT: Record<AvatarSize, TextSize> = {
+  sm: "xs", // 12 on 24 — one letter, so it carries a larger share of the circle
+  md: "sm", // 14 on 36
+  lg: "lg", // 18 on 48
+  xl: "xxl", // 28 on 72
+};
+
+const words = (name: string): string[] => name.trim().split(/\s+/).filter((w) => w !== "");
+
+/**
+ * The initials shown when a member has no photo.
+ *
+ * TWO LETTERS, AND THEY ARE THE FIRST AND **LAST** WORDS — not the first two.
+ * A Vietnamese name is họ + đệm + tên, so the first two words are the family name
+ * and a middle name shared by half the office: "Vũ Thị Lan" and "Vũ Thị Ngọc" both
+ * reduce to "VT". Taking the first and last gives VL and VN. Measured on a real
+ * 29-person workspace, first-two-words leaves 11 people indistinguishable and
+ * first-and-last leaves 5. It is also what English display initials have always
+ * been — "Mary Jane Watson" is MW — so this is a correction, not a localization.
+ *
+ * `sm` gets ONE letter: two do not fit legibly at 24px, which is the whole reason
+ * the rung exists. Every larger rung gets two — where the old rule keyed off a
+ * `<= 32px` threshold that every call site in both apps happened to sit under, so
+ * in practice the product only ever showed a single letter.
+ */
+export function avatarInitials(name: string, size: AvatarSize): string {
+  const parts = words(name);
+  if (parts.length === 0) return "";
+  const first = parts[0];
+  if (size === "sm") return first.charAt(0).toUpperCase();
+  // A single-word name gives up its second letter rather than a lone initial
+  // floating in a 36px circle — "Nga" reads better as "NG" than as "N".
+  if (parts.length === 1) return first.slice(0, 2).toUpperCase();
+  return (first.charAt(0) + parts[parts.length - 1].charAt(0)).toUpperCase();
+}

package/src/group_avatar.tsx

@@ -1,32 +1,41 @@
 import { StyleSheet, View } from "react-native";
 import { Text } from "@lotics/ui/text";
 import { colors } from "@lotics/ui/colors";
+import { AVATAR_PX, AVATAR_TEXT, avatarInitials, type AvatarSize } from "@lotics/ui/avatar_size";
 
 export interface GroupAvatarProps {
   name: string;
-  size?: number;
+  /** A rung on the shared avatar scale. Default `md`. */
+  size?: AvatarSize;
 }
 
 /**
- * Renders the first letter of a name in a styled rounded square. Use
- * for entities without an image (groups, organizations, tags).
+ * Renders a name's initials in a styled rounded square. Use for entities
+ * without an image (groups, organizations, tags).
+ *
+ * Shares `Avatar`'s scale AND its initials rule, so a member and a group
+ * standing next to each other in one list — a permission list, an approver
+ * picker, a search result — read as the same kind of thing. A group left on a
+ * single letter beside a person showing two was the tell that the two had
+ * drifted apart.
  */
 export function GroupAvatar(props: GroupAvatarProps) {
-  const { name, size = 40 } = props;
+  const { name, size = "md" } = props;
+  const px = AVATAR_PX[size];
 
   return (
     <View
       style={[
         styles.container,
         {
-          width: size,
-          height: size,
-          borderRadius: size * 0.2,
+          width: px,
+          height: px,
+          borderRadius: px * 0.2,
         },
       ]}
     >
-      <Text size="sm" weight="medium">
-        {name.charAt(0).toUpperCase()}
+      <Text size={AVATAR_TEXT[size]} weight="medium">
+        {avatarInitials(name, size)}
       </Text>
     </View>
   );

package/src/inline_member_select.tsx

@@ -4,6 +4,7 @@ import type { InlineEditVariant } from "./inline_edit";
 import { InlineSelect } from "./inline_select";
 import { MemberChip } from "./member_chip";
 import { Avatar } from "./avatar";
+import { AVATAR_PX, type AvatarSize } from "./avatar_size";
 import { Icon } from "./icon";
 import { colors } from "./colors";
 import type { MemberSelectMember } from "./member_select";
@@ -42,7 +43,11 @@ interface InlineMemberSelectProps {
   avatarOnly?: boolean;
 }
 
-const AVATAR_ONLY_SIZE = 24;
+// The avatar-only variant sits in a dense inline cell — `sm`. The placeholder
+// box below takes its pixels from the SAME rung, so the empty slot can never
+// stop matching the avatar that fills it.
+const AVATAR_ONLY: AvatarSize = "sm";
+const AVATAR_ONLY_SIZE = AVATAR_PX[AVATAR_ONLY];
 
 /**
  * Edit a `select_member` field in place: the assigned member shows as a
@@ -79,7 +84,7 @@ export function InlineMemberSelect(props: InlineMemberSelectProps) {
     (option: PickerOption<string>) => {
       const member = byId.get(option.value);
       if (!member) return null;
-      return <Avatar size={AVATAR_ONLY_SIZE} name={member.name || member.email || member.id} source={member.image ? { uri: member.image } : undefined} announce />;
+      return <Avatar size={AVATAR_ONLY} name={member.name || member.email || member.id} source={member.image ? { uri: member.image } : undefined} announce />;
     },
     [byId],
   );

package/src/member_chip.tsx

@@ -2,6 +2,7 @@ import React from "react";
 import { View, StyleSheet, StyleProp, ViewStyle } from "react-native";
 import { Avatar } from "./avatar";
 import { Text } from "./text";
+import type { AvatarSize } from "./avatar_size";
 
 interface MemberChipProps {
   /** Display name. Empty/blank falls back to a neutral label — pass
@@ -11,8 +12,8 @@ interface MemberChipProps {
   image?: string | null;
   /** Optional secondary line under the name — e.g. email, role, department. */
   secondary?: string | null;
-  /** Avatar diameter in px. Default 28. */
-  size?: number;
+  /** A rung on the shared avatar scale. Default `md`. */
+  size?: AvatarSize;
   style?: StyleProp<ViewStyle>;
 }
 
@@ -26,7 +27,7 @@ interface MemberChipProps {
  * `select_member` cell joined against that roster); this component fetches
  * nothing and carries no domain types.
  */
-export function MemberChip({ name, image, secondary, size = 28, style }: MemberChipProps) {
+export function MemberChip({ name, image, secondary, size = "md", style }: MemberChipProps) {
   const displayName = name?.trim() || "Unknown";
   return (
     <View style={[styles.row, style]}>

package/src/table.tsx

@@ -35,6 +35,30 @@ export interface TableColumn extends TableFitColumn {
   sortable?: boolean;
 }
 
+/**
+ * How cells sit on the row's CROSS axis.
+ *
+ * `center` (the default) — every cell centred in the row. Right for a register
+ * whose cells are one line each, which is most of them, and the reason this is
+ * not being changed underneath anyone.
+ *
+ * `top` — cells share a top edge, so the FIRST LINE of every cell lands on one
+ * baseline. Reach for it the moment cells carry different numbers of lines: an
+ * identity cell with a supporting line (2), a status cell with a bar over a
+ * label (3), a member chip (1) and a wrapped cell (2) centred together put four
+ * first lines at four different heights, and the eye steps down and back up
+ * across a single row. Measured on a live register: a 12px spread.
+ *
+ * It governs the CELLS only. The ordinal, the leading checkbox and the trailing
+ * ⋯ stay centred in the row — they are chrome, they are one line by
+ * construction, and pinning them to the top of a tall row would strand them.
+ *
+ * It applies to EVERY column row — pressable and read-only alike — because a
+ * table that mixed the two would otherwise align its own rows differently from
+ * each other. A STACKED row (tier 3) is unaffected: it has no columns to line up.
+ */
+export type TableAlign = "center" | "top";
+
 interface TableCtx {
   columns: TableColumn[];
   leading: number;
@@ -43,6 +67,7 @@ interface TableCtx {
   trailing: number;
   visibleKeys: ReadonlySet<string>;
   stacked: boolean;
+  align: TableAlign;
 }
 const TableContext = createContext<TableCtx | null>(null);
 
@@ -123,6 +148,9 @@ export interface TableProps {
   count?: number;
   /** Reserve a trailing gutter (px) for rows that render a `trailing` slot (a ⋯ / button). */
   trailing?: number;
+  /** How cells sit on the row's cross axis — see {@link TableAlign}. Default
+   *  `center`; pass `top` when cells carry different numbers of lines. */
+  align?: TableAlign;
   /** The `TableRow`s. */
   children: ReactNode;
 }
@@ -142,7 +170,7 @@ export interface TableProps {
  * keeps its current order). See `computeTableFit`.
  */
 export function Table(props: TableProps) {
-  const { columns, sort, onSort, sortLabels, selectAll, leading = 0, count, trailing = 0, children } = props;
+  const { columns, sort, onSort, sortLabels, selectAll, leading = 0, count, trailing = 0, align = "center", children } = props;
   const ordinal = count != null ? ORDINAL_W : 0;
   const rows = Children.toArray(children).filter(isValidElement);
 
@@ -160,7 +188,7 @@ export function Table(props: TableProps) {
   const visibleColumns = columns.filter((c) => fit.visibleKeys.has(c.key));
 
   return (
-    <TableContext.Provider value={{ columns, leading, ordinal, trailing, visibleKeys: fit.visibleKeys, stacked: fit.stacked }}>
+    <TableContext.Provider value={{ columns, leading, ordinal, trailing, visibleKeys: fit.visibleKeys, stacked: fit.stacked, align }}>
       {/* ONE layout node: without this wrapper the header band + body land as two
           direct flex children of the app's container, and a parent column `gap`
           (the standard section spacing) opens a hole between the header and rows. */}
@@ -312,6 +340,12 @@ export function TableRow(props: TableRowProps) {
     // no cell, and column 0 never drops in register mode either.)
     .map(({ cell, column }, i) => cloneElement(cell, { _column: column, _stacked: ctx.stacked, _primary: i === 0 }));
 
+  // ONE style for the column row, shared by the pressable and read-only paths
+  // below. They rendered near-identical Views and `align` was added to only one,
+  // so a table mixing the two aligned its own rows differently — computing it
+  // once is what makes that divergence impossible rather than merely fixed.
+  const cellsStyle = [styles.cells, { minHeight }, ctx.align === "top" ? styles.cellsTop : null];
+
   const body = ctx.stacked ? (
     <View style={styles.stackedBody}>
       <View style={styles.stackedTopLine}>
@@ -346,7 +380,7 @@ export function TableRow(props: TableRowProps) {
     return (
       <View style={styles.staticRow}>
         <LeadGutter ordinal={ordinal}>{leading}</LeadGutter>
-        <View style={[styles.cells, { minHeight }]}>{cells}</View>
+        <View style={cellsStyle}>{cells}</View>
         {ctx.trailing > 0 ? (
           <View style={[styles.trailingSlot, { width: ctx.trailing }]}>
             {action}
@@ -368,7 +402,7 @@ export function TableRow(props: TableRowProps) {
         body
       ) : (
         <>
-          <View style={[styles.cells, { minHeight }]}>{cells}</View>
+          <View style={cellsStyle}>{cells}</View>
           {ctx.trailing > 0 ? (
             <View style={[styles.slot, styles.trailingSlot, { width: ctx.trailing }]}>
               {action}
@@ -495,6 +529,11 @@ const styles = StyleSheet.create({
     gap: COLUMN_GAP,
     zIndex: 1,
   },
+  // `align="top"` — see `TableAlign`. Overrides the centring above so unequal
+  // cells share a first-line baseline; the row's own chrome stays centred.
+  cellsTop: {
+    alignItems: "flex-start",
+  },
   // Leading/trailing gutters carry their own controls — lifted above the door
   // like the cells.
   slot: {