@lotics/ui 43.4.0 → 43.5.0

package/examples/tpl_item_list.tsx

@@ -5,6 +5,7 @@ import { Text } from "@lotics/ui/text";
 import { colors, solid, type ColorName } from "@lotics/ui/colors";
 import { ActionMenu, type ActionMenuItem } from "@lotics/ui/action_menu";
 import { Alert } from "@lotics/ui/alert";
+import { Avatar } from "@lotics/ui/avatar";
 import { Badge } from "@lotics/ui/badge";
 import { Button } from "@lotics/ui/button";
 import { CheckboxInput } from "@lotics/ui/checkbox_input";
@@ -60,7 +61,8 @@ import { useChangeSet } from "@lotics/ui/use_change_set";
 // Template, Register — THE canonical register, and the ONE work-execution list
 // shape. A flat, paginated, SELECTABLE list of records: one toolbar row (search +
 // consolidated filters LEFT, New CTA RIGHT), a light SummaryLine of the filtered
-// view, a sortable, Divider-separated register where every row has a leading
+// view, a sortable register whose rows are separated by their own height and the
+// hover wash rather than by a rule, where every row has a leading
 // checkbox (a row that can't take the bulk action — here an "Awaiting docs" case —
 // gets a DISABLED one), a per-row PRINT action button, and a ⋯ overflow (press the
 // row = the sequenced workspace Drawer), a select-all band, footer totals +
@@ -215,59 +217,98 @@ function HoSoRow({ hs, ordinal, daThu, selected, marked, selectable, onToggle, o
       ordinal={ordinal}
       selected={selected}
       marked={marked}
-      minHeight={56}
       accessibilityLabel={`Open record ${hs.ma} — ${hs.khach}`}
       leading={<CheckboxInput accessibilityLabel={selectable ? `Select ${hs.ma}` : `${hs.ma} — awaiting docs, not ready to export`} checked={marked} disabled={!selectable} onChange={onToggle} />}
       action={<Button title="Print" icon={docFor(hs, daThu).icon} color="secondary" onPress={() => {}} />}
       trailing={<ActionMenu items={menuFor(hs, daThu)} accessibilityLabel={`Actions for ${hs.ma}`} />}
     >
       <TableCell>
-        <View style={{ gap: 2, alignSelf: "stretch" }}>
-          {/* The name takes the row, the thread pins right. A comment count is
-              the one thing on this row that is about PEOPLE talking rather than
-              the record's own state, so it sits apart from the values below it
-              instead of joining them on the supporting line. */}
-          <View style={{ flexDirection: "row", alignItems: "center", gap: 8 }}>
-            <Text size="sm" weight="medium" numberOfLines={1} style={{ flexShrink: 1 }}>{hs.khach}</Text>
-            {/* Rendered only where a thread EXISTS — a zero on every quiet row is a
-                column of noise that trains the eye to skip where the signal appears. */}
-            {hs.binhLuan > 0 ? <CommentsButton count={hs.binhLuan} subject={hs.khach} onPress={onOpenComments} /> : null}
-          </View>
-          {/* Every value on this row is selectable — that is what a register owes
-              its reader, and it costs no chrome. The phone gets a CONTROL on top
-              because it is the one value copied often enough to earn one (a desk
-              pastes it into a message, a rep dials it). The verb rides the value
-              inside its own cell: the trailing gutter belongs to the ⋯, and with
-              two values in this cell it would have nothing to name.
-
-              UNCONDITIONAL, and that is the load-bearing part of this shape. A
-              row centres its cells, so a supporting line that appears only when
-              its field is set makes this cell two heights, and the NAME above it
-              then sits at two different offsets down the column while every row
-              still measures the same. That is why the values here are ones every
-              record carries — a key, a contact — rather than whichever field is
-              most interesting: the line has to be honest on every row to be
-              reservable at all. */}
-          <View style={{ flexDirection: "row", alignItems: "center", gap: 2 }}>
-            {/* The KEY, muted, on the supporting line — at most this, never a
-                column and never the row's name.
-
-                It does NOT shrink. A key is quoted whole or it is not a key: a
-                phone number clipped to "(555) 384-7…" is still recognisably a
-                number the reader can widen the column to finish, while
-                "RC-2026-0…" is unusable — it is the exact string a desk reads
-                out. So the fixed-length identifier holds its width and the phone
-                gives way, which is also the right order of loss: the phone has a
-                Copy control beside it that hands over the full value regardless. */}
-            <Text size="xs" color="muted" tabular numberOfLines={1} style={{ flexShrink: 0 }}>{hs.ma}</Text>
-            {/* A GAP, not a middot. Two facts of different kinds sat either side
-                of a ` · ` here, which is the separator this kit bans outright —
-                punctuation claiming a relation it refuses to name, and dropped
-                entirely by a screen reader. Spacing separates them without
-                asserting anything, and the two are already told apart by shape:
-                one is a key, one is a number with a Copy control on it. */}
-            <Text size="xs" color="muted" tabular numberOfLines={1} style={{ flexShrink: 1, marginLeft: 8 }}>{hs.dienThoai}</Text>
-            <CopyButton value={hs.dienThoai} label="Copy phone number" />
+        {/* THE IDENTITY MARK leads the cell that names the row. A register of
+            entities without one is N rows of grey text a reader scans linearly;
+            with one, the eye lands on the row it wants by colour and letter
+            before it reads a word. `Avatar` derives its hue from the name, so
+            the marks differ across rows without anyone configuring anything —
+            the failure mode to avoid is N identical marks, which is the largest
+            and brightest thing on the row carrying no information at all.
+
+            It sits in the SUBJECT'S CELL, not the `leading` slot: `leading`
+            already holds the selection checkbox, and those two are different
+            jobs — one is what the row IS, the other is something you are doing
+            to it. Stacking them in one slot reads as a single compound control.
+
+            `lg` because the customer is what this row is ABOUT. A person who is
+            one FIELD among columns (the owner, below) takes `md`; see
+            `avatar_size.ts`, which owns that rule.
+
+            ONE SHAPE for the whole register. `Avatar` takes `square` for an
+            organization, but that distinction earns its place only where a
+            surface mixes entity TYPES and the reader acts on which is which.
+            Here every row is a record, and whether the customer is a company is
+            not something the reader does anything with — so a column of mixed
+            circles and squares reads as an inconsistency rather than as
+            information, which is exactly how it gets reported. */}
+        <View style={{ flexDirection: "row", alignItems: "center", gap: 10, alignSelf: "stretch" }}>
+          <Avatar name={hs.khach} size="lg" />
+          <View style={{ gap: 2, flex: 1, minWidth: 0 }}>
+            {/* The name takes the row, the thread pins right. A comment count is
+                the one thing on this row that is about PEOPLE talking rather than
+                the record's own state, so it sits apart from the values below it
+                instead of joining them on the supporting line. */}
+            <View style={{ flexDirection: "row", alignItems: "center", gap: 8 }}>
+              <Text size="sm" weight="medium" numberOfLines={1} style={{ flexShrink: 1 }}>{hs.khach}</Text>
+              {/* Rendered only where a thread EXISTS — a zero on every quiet row is a
+                  column of noise that trains the eye to skip where the signal appears. */}
+              {hs.binhLuan > 0 ? <CommentsButton count={hs.binhLuan} subject={hs.khach} onPress={onOpenComments} /> : null}
+            </View>
+            {/* Every value on this row is selectable — that is what a register owes
+                its reader, and it costs no chrome. The phone gets a CONTROL on top
+                because it is the one value copied often enough to earn one (a desk
+                pastes it into a message, a rep dials it). The verb rides the value
+                inside its own cell: the trailing gutter belongs to the ⋯, and with
+                two values in this cell it would have nothing to name.
+
+                UNCONDITIONAL, and that is the load-bearing part of this shape. A
+                row centres its cells, so a supporting line that appears only when
+                its field is set makes this cell two heights, and the NAME above it
+                then sits at two different offsets down the column while every row
+                still measures the same. That is why the values here are ones every
+                record carries — a key, a contact — rather than whichever field is
+                most interesting: the line has to be honest on every row to be
+                reservable at all. */}
+            {/* HEIGHT PINNED TO THE xs LINE BOX (18), because this line carries a
+                CONTROL. `CopyButton` at `sm` is 24 — sized to sit beside `sm`
+                text, per its own doc — so on an `xs` line it made the row 24 and
+                `alignItems: "center"` spent 3 of those px above the text. The
+                supporting line then started 5px under the name while the Fee
+                column's identical primary-over-supporting pair, which carries no
+                control, started 2px under its own. Same shape, two treatments,
+                and the reason (one of them has a button) is invisible to a
+                reader — which is the whole test.
+
+                Pinning the row to the text's line box lets the 24px hit area
+                overflow it without moving the text. Any verb riding a supporting
+                line needs this; a control must not resize the line it sits on. */}
+            <View style={{ flexDirection: "row", alignItems: "center", gap: 2, height: 18 }}>
+              {/* The KEY, muted, on the supporting line — at most this, never a
+                  column and never the row's name.
+
+                  It does NOT shrink. A key is quoted whole or it is not a key: a
+                  phone number clipped to "(555) 384-7…" is still recognisably a
+                  number the reader can widen the column to finish, while
+                  "RC-2026-0…" is unusable — it is the exact string a desk reads
+                  out. So the fixed-length identifier holds its width and the phone
+                  gives way, which is also the right order of loss: the phone has a
+                  Copy control beside it that hands over the full value regardless. */}
+              <Text size="xs" color="muted" tabular numberOfLines={1} style={{ flexShrink: 0 }}>{hs.ma}</Text>
+              {/* A GAP, not a middot. Two facts of different kinds sat either side
+                  of a ` · ` here, which is the separator this kit bans outright —
+                  punctuation claiming a relation it refuses to name, and dropped
+                  entirely by a screen reader. Spacing separates them without
+                  asserting anything, and the two are already told apart by shape:
+                  one is a key, one is a number with a Copy control on it. */}
+              <Text size="xs" color="muted" tabular numberOfLines={1} style={{ flexShrink: 1, marginLeft: 8 }}>{hs.dienThoai}</Text>
+              <CopyButton value={hs.dienThoai} label="Copy phone number" />
+            </View>
           </View>
         </View>
       </TableCell>
@@ -1199,11 +1240,15 @@ export function TplItemList() {
     <FileDropTarget onFiles={openIntakeSeeded} paste style={{ flex: 1 }}>
     <ScrollView style={{ flex: 1, backgroundColor: colors.white }} contentContainerStyle={{ padding: 28 }}>
       <View style={{ width: "100%", maxWidth: 1040, alignSelf: "center", gap: 16 }}>
-        {/* header — title only; the New case action lives on the toolbar row */}
-        <View style={{ gap: 2 }}>
-          <Text size="xxl" weight="semibold">Records</Text>
-          <Text size="sm" color="muted">Track each record's status and print the right document for its stage</Text>
-        </View>
+        {/* The page band — the screen's TYPE ANCHOR before it is a label. Without
+            it this page's largest text is 16px against a 12px floor, and a 1.33x
+            range reads flat however much colour is on it. The title repeating the
+            nav is a real cost and the right trade: one line buys the whole range.
+            What is NOT here is a gloss on the widget ("track each record's status
+            and print the right document for its stage"), which described the
+            control rather than the domain — and what is not here EITHER is the
+            summary, which belongs under the filters that change it. */}
+        <Text size="xxl" weight="semibold">Records</Text>
 
         {/* toolbar — search + consolidated filters LEFT, New case RIGHT, one row.
             A search is present, so status is a dropdown (Select), not pills. */}
@@ -1273,7 +1318,17 @@ export function TplItemList() {
           <Button title="Enter data" color="primary" onPress={openIntake} />
         </View>
 
-        {/* light summary of the filtered register (search/assignee/fee applied; status counts stay visible across tabs) */}
+        {/* THE SUMMARY READS THE FILTERED SET, so it sits BELOW the controls that
+            produce it. These figures move every time the reader touches a chip:
+            put them above, and the screen answers before it has been asked — the
+            reader changes a filter, the numbers change behind their eye, and the
+            causal order the layout states is backwards. Under the toolbar it
+            reads as the result of what was just set, and it is the last thing
+            before the rows it counts.
+
+            It is not a page-band subtitle for the same reason. A subtitle
+            describes the screen; these describe the QUERY, and the query is what
+            the toolbar above just wrote. */}
         <SummaryLine
           items={[
             { label: "processing", value: dem("dangxuly") },

package/examples/tpl_record.tsx

@@ -52,7 +52,7 @@ import { MemberSelect, type MemberSelectMember } from "@lotics/ui/member_select"
 import { EmptyState } from "@lotics/ui/empty_state";
 import { FormField } from "@lotics/ui/form_field";
 import { TextInputField } from "@lotics/ui/text_input_field";
-import { FileThumbnail, THUMBNAIL_SIZE, type DisplayFile } from "@lotics/ui/file_thumbnail";
+import { FileThumbnail, THUMBNAIL_SIZE, COMPACT_THUMBNAIL_SIZE, type DisplayFile } from "@lotics/ui/file_thumbnail";
 import { FileThumbnailGrid } from "@lotics/ui/file_thumbnail_grid";
 import { Inset } from "@lotics/ui/inset";
 import { FileGalleryModal } from "@lotics/ui/file_gallery_modal";
@@ -122,6 +122,87 @@ type Part = UIMessagePart<UIDataTypes, UITools>;
 //                     table ONCE (creates + links the sibling; Recall undoes).
 // - Danger zone     — destructive lifecycle. Always last.
 //
+//
+// ─── THE RULES THIS TEMPLATE ENCODES ─────────────────────────────────────────
+// Read these before adapting it. Each one shipped WRONG on a real app first,
+// was reported by the person using it, and cost a rebuild. They are not style
+// preferences; they are the difference between a screen that works and a screen
+// that gets called bland, cluttered or inconsistent.
+//
+// 1. A BADGE MEANS STATUS. Nothing else.
+//    A lifecycle, a stage, a risk level — something that reads at a glance and
+//    changes what you DO. A type, a category, an attribute or a count is NOT a
+//    status: an industry, a source, a department, a headcount band, a CITY.
+//    Those are plain `Text`. A coloured pill only means "state" for as long as
+//    it stays scarce, so one spent on where a company happens to be devalues
+//    the one column that IS a state. A field carrying a configured `color` is
+//    not consent to paint it — someone set that colour for the one surface that
+//    badges, and every other surface still has to decide.
+//    Feed pickers with `optionPicker(options)` — text — and add
+//    `{ badge: "dot" }` only on a status. Helper defaults must be the SAFE
+//    answer, because a badging default reaches every call site in one sweep.
+//
+// 2. ONE VARIANT PER CONCEPT, product-wide. `dot` or `tonal`, chosen once. The
+//    same field rendering as a filled pill on one screen and a dot on another is
+//    the inconsistency people actually notice. Where a register already carries
+//    identity marks, prefer `dot`: two colour systems in one row compete and
+//    neither reads as the subject.
+//
+// 3. THE PAGE BAND IS THE TYPE ANCHOR before it is a label. Without it a record
+//    or register tops out near 16px over a 12px floor — a 1.33x range that reads
+//    flat at ANY amount of colour, because scale is the one hierarchy device
+//    colour cannot replace. Accept that the title repeats the nav. Its second
+//    line carries LIVE STATE (counts that move as you filter), never a gloss on
+//    the widget.
+//
+// 4. A SUPPORTING LINE IS ONE RUNG BELOW ITS PRIMARY, never a fixed size. `md`
+//    over `xs` drops 1.33x while the same shape elsewhere drops 1.17x, and the
+//    wider pair reads as though its second line SHRANK rather than stepped.
+//    Compare the RATIOS across the surface, not the sizes.
+//
+// 5. ACTIONABLE FIRST. Identity and the one editable status go above the fold.
+//    An UNBOUNDED section (an activity feed, a comment thread) stacked above a
+//    bounded field set does not order them — it BURIES the second, and the
+//    burial deepens every time the record is used. Measured on a real record,
+//    the fields the reader came to edit began 2,500px down. That is the case
+//    where tabs beat one page, against the record-extent rule.
+//    Promoting a field means MOVING it: a copy left behind gives one field two
+//    editors on one surface, and either could be the one the reader changed.
+//
+// 6. PICK THE CONTROL BY SPECIES, from what already exists. Read
+//    `data_entry.md`'s ladder and the `tpl_*` that covers the shape BEFORE
+//    building. A binary filter is a `ChipGroup` (every option visible, one
+//    press), never a popover holding one checkbox. Grouping picks a DIMENSION
+//    via the same control species as the filters beside it, never an icon
+//    toggling on/off. A SELECTED control needs a GROUND, not a heavier outline —
+//    among white pills a 1px border change is invisible.
+//
+// 7. CLUSTER A TOOLBAR BY QUESTION, and check the gap RATIO. Filters answer
+//    *which rows*; view controls answer *how are they arranged*; the CTA answers
+//    neither. Uniform gaps make eight controls read as one undifferentiated
+//    band; 8px within a cluster and 24px between reads as groups with no lines
+//    or boxes added. Long labels are a toolbar defect — the band is a set of
+//    handles, not sentences.
+//
+// 8. PICK THE FILE SURFACE BY WHAT IDENTIFIES THE FILE, after counting the real
+//    data. Images are identified by CONTENT (grid); documents by NAME (list) —
+//    a grid of PDFs is a wall of one grey tile. Press should OPEN a document
+//    (`press="open"`); a preview lightbox is a dead end for anything you sign,
+//    edit or send. A files field is `InlineFiles` in a `DetailRow`, the same
+//    grammar as every other field beside it — never a bespoke block below the
+//    table. A surface that can SHOW a file and cannot RECEIVE one is unfinished.
+//
+// 9. AN IDENTITY MARK MUST NOT LOOK THE SAME ON EVERY ROW — that is its entire
+//    job. `Avatar` derives its hue from the name; circle for a person, square
+//    for an organization. A screen whose subject is an entity and whose marks
+//    are all one colour has the largest, brightest element in each row carrying
+//    no information.
+//
+// 10. NEVER FORK THE KIT. Hitting a limit means fixing the kit — a component
+//     built app-local beside one that nearly fits is a fork that drifts, and the
+//     next author inherits both. If a prop is missing, add the prop.
+// ─────────────────────────────────────────────────────────────────────────────
+//
 // The lifecycle is the HANDOFF CHAIN, and it reads in TWO places by design:
 // `Progress` carries the position and the act that changes it; `Handoff` near
 // the end carries the RESULT — what each handoff created, and when. There is no
@@ -3609,9 +3690,13 @@ export function TplRecord({ chrome = "page", code = "RC-2026-0418", openSection
               >
                 <TableCell>
                   <View style={{ flexDirection: "row", alignItems: "center", gap: 10 }}>
-                    {/* ONE square 32px slot for every type: an image fills it as a
-                        real thumbnail, a document centers its badge in it */}
-                    <FileThumbnail file={toDisplay(f)} size={32} onPress={() => openPreview(visibleFiles, fi)} />
+                    {/* ONE square slot for every type: an image fills it as a real
+                        thumbnail, a document centers its badge in it. The rung is
+                        the kit's, not a number picked here — it tracks the row
+                        height, and a file row's mark is the same size as a
+                        person's in a register, because both answer "which row is
+                        this". */}
+                    <FileThumbnail file={toDisplay(f)} size={COMPACT_THUMBNAIL_SIZE} onPress={() => openPreview(visibleFiles, fi)} />
                     <Text size="sm" weight="medium" numberOfLines={1} style={{ flexShrink: 1 }}>{f.name}</Text>
                   </View>
                 </TableCell>

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@lotics/ui",
-  "version": "43.4.0",
+  "version": "43.5.0",
   "type": "module",
   "exports": {
     "./vite": {
@@ -13,6 +13,7 @@
       "default": "./src/colors.web.ts"
     },
     "./deadline": "./src/deadline.ts",
+    "./option_picker": "./src/option_picker.tsx",
     "./option_badge": "./src/option_badge.tsx",
     "./member_chip": "./src/member_chip.tsx",
     "./member_select": "./src/member_select.tsx",
@@ -90,8 +91,8 @@
     "./locale": "./src/locale.tsx",
     "./spacing": "./src/spacing.ts",
     "./theme": {
-      "react-native": "./src/theme.tsx",
-      "default": "./src/theme.web.tsx"
+      "react-native": "./src/theme.ts",
+      "default": "./src/theme.web.ts"
     },
     "./progress_bar": "./src/progress_bar.tsx",
     "./form_date_picker": "./src/form_date_picker.tsx",
@@ -272,9 +273,12 @@
     "./landmark": "./src/landmark.tsx",
     "./skip_link": "./src/skip_link.tsx",
     "./text_utils": "./src/text_utils.ts",
+    "./type_ramp": "./src/type_ramp.ts",
     "./column_filter": "./src/column_filter.tsx",
     "./chip_group": "./src/chip_group.tsx",
     "./avatar_size": "./src/avatar_size.ts",
+    "./avatar_tone": "./src/avatar_tone.ts",
+    "./avatar_props": "./src/avatar_props.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

@@ -1,33 +1,22 @@
-import { Image, ImageContentFit, ImageSource } from "expo-image";
+import { Image } from "expo-image";
 import React from "react";
-import { View, StyleSheet, StyleProp, ViewStyle, ImageStyle } from "react-native";
+import { View, StyleSheet, 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 {
-  /** 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>;
-  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;
-}
+import { avatarTone } from "./avatar_tone";
+import { AVATAR_PX, AVATAR_TEXT, avatarInitials } from "./avatar_size";
+import { avatarShapeStyle, type AvatarProps } from "./avatar_props";
 
+/**
+ * A person or an organization, as an identity MARK — an image when there is
+ * one, otherwise initials on the brand accent. Prop contract: `avatar_props`.
+ */
 export function Avatar(props: AvatarProps) {
   const locale = useLoticsLocale();
-  const { source, size = "md", name = locale.avatar.unknown, style, contentFit, announce } = props;
+  const { source, size = "md", shape = "circle", name = locale.avatar.unknown, style, contentFit, announce } = props;
   const decorative = !announce;
   const px = AVATAR_PX[size];
+  const shapeStyle = avatarShapeStyle(shape);
 
   if (!source || !source.uri) {
     return (
@@ -39,12 +28,14 @@ export function Avatar(props: AvatarProps) {
         aria-hidden={decorative || undefined}
         style={[
           styles.base,
-          // The initials disc is the one place a member LOOKS like the product,
-          // so it carries the brand accent rather than a fixed blue. NOT a
-          // restyle: `colors.accent` DEFAULTS to this exact blue-600, so an app
-          // that themes nothing renders identical pixels, while one that sets an
-          // accent gets its own hue without this file knowing.
-          { backgroundColor: colors.accent, width: px, height: px },
+          // The disc's ground is DERIVED FROM THE NAME — see `avatar_tone`. It
+          // used to be `colors.accent`, which made every person in a register the
+          // same colour and left the row's biggest, brightest element carrying no
+          // information. The brand did not lose a home; it moved to the chrome
+          // (active tab, selection wash, primary action), where it is shared
+          // across apps and learned once.
+          { backgroundColor: avatarTone(name), width: px, height: px },
+          shapeStyle,
           style,
         ]}
       >
@@ -70,7 +61,7 @@ export function Avatar(props: AvatarProps) {
       alt={decorative ? "" : name}
       accessibilityElementsHidden={decorative}
       importantForAccessibility={decorative ? "no-hide-descendants" : undefined}
-      style={[styles.base, { width: px, height: px }, style as ImageStyle]}
+      style={[styles.base, { width: px, height: px }, shapeStyle, style as ImageStyle]}
       source={source}
       contentFit={contentFit}
       cachePolicy="memory-disk"
@@ -85,5 +76,14 @@ const styles = StyleSheet.create({
     justifyContent: "center",
     alignItems: "center",
     userSelect: "none",
+    // An INSET hairline, not a border and not a shadow. A flat disc of saturated
+    // colour on white is a sticker: nothing relates it to the surface, and at
+    // register scale a column of them reads as printed-on rather than sitting
+    // there. `inset` keeps the ring INSIDE the box, so the avatar's measured size
+    // is unchanged and every layout that budgeted `AVATAR_PX` still fits — an
+    // outset border would have grown every disc by 2px and pushed the name beside
+    // it. Black at 8% darkens whatever hue is underneath rather than tinting it,
+    // so it works across the whole identity palette without a per-hue value.
+    ...({ boxShadow: "inset 0 0 0 1px rgba(0,0,0,0.08)" } as object),
   },
 });

package/src/avatar.web.tsx

@@ -1,40 +1,30 @@
-import type { ImageContentFit, ImageSource } from "expo-image";
-import { Image, View, StyleSheet, StyleProp, ViewStyle, ImageStyle } from "react-native";
+import { Image, View, StyleSheet, 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 {
-  /** A rung on the shared avatar scale — never a pixel count. */
-  size?: AvatarSize;
-  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;
-}
+import { avatarTone } from "./avatar_tone";
+import { AVATAR_PX, AVATAR_TEXT, avatarInitials } from "./avatar_size";
+import { avatarShapeStyle, type AvatarProps } from "./avatar_props";
 
 /**
  * Web Avatar. The native `avatar.tsx` renders through `expo-image`, a native
  * module that pulls expo's runtime into the graph and fails to load under
  * pure-web bundlers (Vite dev throws on its CJS interop; vitest can't resolve
  * expo's winter runtime). On web, `react-native`'s `Image` (→ react-native-web
- * → `<img>`) renders the same circular avatar with none of that cost. The prop
- * surface is identical — `ImageSource`/`ImageContentFit` are kept as erased
- * type-only imports so no expo-image module is ever loaded.
+ * → `<img>`) renders the same avatar with none of that cost.
+ *
+ * Its prop surface is NOT declared here — see `avatar_props`, which both
+ * variants implement and where expo-image's `ImageSource`/`ImageContentFit`
+ * survive as erased type-only imports, so no expo-image module is ever loaded on
+ * this path. The interface used to be declared twice, and `tsc` resolves
+ * `./avatar` to the NATIVE sibling: a prop added there compiled clean
+ * everywhere, and did nothing in the browser.
  */
 export function Avatar(props: AvatarProps) {
   const locale = useLoticsLocale();
-  const { source, size = "md", name = locale.avatar.unknown, style, contentFit, announce } = props;
+  const { source, size = "md", shape = "circle", name = locale.avatar.unknown, style, contentFit, announce } = props;
   const decorative = !announce;
   const px = AVATAR_PX[size];
+  const shapeStyle = avatarShapeStyle(shape);
 
   if (!source || !source.uri) {
     return (
@@ -46,12 +36,14 @@ export function Avatar(props: AvatarProps) {
         aria-hidden={decorative || undefined}
         style={[
           styles.base,
-          // The initials disc is the one place a member LOOKS like the product,
-          // so it carries the brand accent rather than a fixed blue. NOT a
-          // restyle: `colors.accent` DEFAULTS to this exact blue-600, so an app
-          // that themes nothing renders identical pixels, while one that sets an
-          // accent gets its own hue without this file knowing.
-          { backgroundColor: colors.accent, width: px, height: px },
+          // The disc's ground is DERIVED FROM THE NAME — see `avatar_tone`. It
+          // used to be `colors.accent`, which made every person in a register the
+          // same colour and left the row's biggest, brightest element carrying no
+          // information. The brand did not lose a home; it moved to the chrome
+          // (active tab, selection wash, primary action), where it is shared
+          // across apps and learned once.
+          { backgroundColor: avatarTone(name), width: px, height: px },
+          shapeStyle,
           style,
         ]}
       >
@@ -77,7 +69,7 @@ export function Avatar(props: AvatarProps) {
       accessibilityLabel={decorative ? undefined : name}
       accessibilityElementsHidden={decorative}
       importantForAccessibility={decorative ? "no-hide-descendants" : undefined}
-      style={[styles.base, { width: px, height: px }, style as ImageStyle]}
+      style={[styles.base, { width: px, height: px }, shapeStyle, style as ImageStyle]}
       source={{ uri: source.uri }}
       resizeMode={contentFit === "contain" ? "contain" : "cover"}
     />
@@ -91,5 +83,14 @@ const styles = StyleSheet.create({
     justifyContent: "center",
     alignItems: "center",
     userSelect: "none",
+    // An INSET hairline, not a border and not a shadow. A flat disc of saturated
+    // colour on white is a sticker: nothing relates it to the surface, and at
+    // register scale a column of them reads as printed-on rather than sitting
+    // there. `inset` keeps the ring INSIDE the box, so the avatar's measured size
+    // is unchanged and every layout that budgeted `AVATAR_PX` still fits — an
+    // outset border would have grown every disc by 2px and pushed the name beside
+    // it. Black at 8% darkens whatever hue is underneath rather than tinting it,
+    // so it works across the whole identity palette without a per-hue value.
+    ...({ boxShadow: "inset 0 0 0 1px rgba(0,0,0,0.08)" } as object),
   },
 });