@lotics/ui 43.0.0 → 43.1.0

package/docs/composition.md

@@ -1033,8 +1033,30 @@ When it IS a status, match weight to prominence — lightest → heaviest:
    a surface (a drawer/detail header). Opt IN explicitly and sparingly; one per view, never
    sprinkled through rows.
 
-A register's dense rows read lighter — the row's primary status is `dot`, its drawer twin may go
-tonal. A `Badge` is never a metric value.
+**`tonal` IS allowed on a register's ONE primary status column, and that is the rule this
+paragraph used to get wrong.** It read "a register's dense rows read lighter, the row's primary
+status is `dot`" while `badge.tsx` named "a register's primary Status column" as a legitimate
+tonal use — two docs, opposite answers, so the choice fell to whoever read which. What "one per
+view" governs is the number of badge KINDS on a surface, not the number of rows: badging the
+stage AND the type AND the city is the clutter the rule exists to stop; one status column that
+happens to render 133 times is one badge.
+
+Prefer `dot` when the column is secondary or the row already carries a coloured mark. Reach for
+`tonal` when the status column is what the register is SCANNED by — the tints are the palette's
+50-step against its 900-step ink (measured 8.7:1 and 9.5:1, so roughly double the AA floor), and
+a column of them is the difference between a register that reads as organised and one that reads
+as a grey spreadsheet. That difference is the commonest "it looks bland" report, and it has a
+real answer that costs no meaning: make the colour the screen ALREADY earns more present, rather
+than adding colour somewhere that has to invent a meaning to justify it.
+
+**A `Badge` in a table cell needs `alignSelf`.** A cell stretches its child on the cross axis, and
+a `dot` has no ground so nothing shows — swap the variant to `tonal` and the pill becomes a filled
+block the full width of the column, which reads as a cell state rather than a chip. The kit cannot
+fix this on the badge: `alignSelf: "flex-start"` means LEFT inside a column-direction cell and TOP
+inside a row-direction one, so setting it globally would break every badge sitting inline beside
+text. Pass it at the call site.
+
+A `Badge` is never a metric value.
 
 ## Typography
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@lotics/ui",
-  "version": "43.0.0",
+  "version": "43.1.0",
   "type": "module",
   "exports": {
     "./vite": {
@@ -277,7 +277,15 @@
     "./avatar_size": "./src/avatar_size.ts",
     "./diff_value": "./src/diff_value.tsx",
     "./diff_mark": "./src/diff_mark.tsx",
-    "./use_change_set": "./src/use_change_set.ts"
+    "./use_change_set": "./src/use_change_set.ts",
+    "./display_font": {
+      "react-native": "./src/display_font.ts",
+      "default": "./src/display_font.web.ts"
+    },
+    "./font_family": {
+      "react-native": "./src/font_family.ts",
+      "default": "./src/font_family.web.ts"
+    }
   },
   "files": [
     "src",

package/src/badge.tsx

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

package/src/button.tsx

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

package/src/color_tokens.ts

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

package/src/colors.web.ts

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

package/src/display_font.ts

@@ -0,0 +1,27 @@
+/**
+ * THE DISPLAY FACE — the family `<Text family="display">` renders in.
+ *
+ * A themeable typeface exists for the DISPLAY role and deliberately not for the
+ * body, and the asymmetry is the whole design. Swapping the face a headline
+ * wears is one value with no dependencies: it appears a handful of times, large,
+ * in one weight. Swapping the BODY face is four coupled things —
+ *
+ *   1. weight is a FAMILY here, not a `font-weight` (`Inter_400Regular` /
+ *      `Inter_500Medium` / `Inter_600SemiBold`), so one variable cannot say it;
+ *   2. `text.css` hand-tunes letter-spacing per size FOR Inter's glyphs and for
+ *      Vietnamese diacritics at 12px;
+ *   3. `font-feature-settings: "cv11","ss01","ss03"` are INTER's stylistic
+ *      alternates and mean nothing — or something else — on another face;
+ *   4. the files are self-hosted, so a family name nobody `@font-face`d falls
+ *      silently through the stack to system sans.
+ *
+ * — which is why there is no `bodyFont` role. A variable for it would not fail,
+ * it would render every screen in the product subtly miscalibrated, globally and
+ * invisibly to typecheck. Changing the body face is a KIT change: add the
+ * @font-face trio, re-tune the curve, re-check the features. Rare, deliberate,
+ * and done once for everybody.
+ */
+import { fontFamilySemiBold } from "./font_family";
+
+/** Native: a literal, because `var()` means nothing off the web. */
+export const fontFamilyDisplay = fontFamilySemiBold;

package/src/display_font.web.ts

@@ -0,0 +1,31 @@
+/**
+ * THE DISPLAY FACE — the family `<Text family="display">` renders in.
+ *
+ * A themeable typeface exists for the DISPLAY role and deliberately not for the
+ * body, and the asymmetry is the whole design. Swapping the face a headline
+ * wears is one value with no dependencies: it appears a handful of times, large,
+ * in one weight. Swapping the BODY face is four coupled things —
+ *
+ *   1. weight is a FAMILY here, not a `font-weight` (`Inter_400Regular` /
+ *      `Inter_500Medium` / `Inter_600SemiBold`), so one variable cannot say it;
+ *   2. `text.css` hand-tunes letter-spacing per size FOR Inter's glyphs and for
+ *      Vietnamese diacritics at 12px;
+ *   3. `font-feature-settings: "cv11","ss01","ss03"` are INTER's stylistic
+ *      alternates and mean nothing — or something else — on another face;
+ *   4. the files are self-hosted, so a family name nobody `@font-face`d falls
+ *      silently through the stack to system sans.
+ *
+ * — which is why there is no `bodyFont` role. A variable for it would not fail,
+ * it would render every screen in the product subtly miscalibrated, globally and
+ * invisibly to typecheck. Changing the body face is a KIT change: add the
+ * @font-face trio, re-tune the curve, re-check the features. Rare, deliberate,
+ * and done once for everybody.
+ */
+import { fontFamilySemiBold } from "./font_family";
+
+/**
+ * The default IS the kit's own semibold sans, so `family="display"` changes
+ * nothing until an app sets `displayFont` — the same opt-in contract the colour
+ * roles keep.
+ */
+export const fontFamilyDisplay = `var(--lotics-display-font, ${fontFamilySemiBold})`;

package/src/filter_chip.tsx

@@ -113,7 +113,10 @@ export function FilterChip(props: FilterChipProps) {
         <Chip onDismiss={showClear ? onClear : undefined} dismissTooltip={clearLabel}>
           {active && typeof summary !== "string" ? (
             <View style={styles.summaryRow}>
-              <Text userSelect="none" size="sm" weight="medium" color="zinc-700">{`${label}:`}</Text>
+              {/* This branch only renders when ACTIVE, so it takes the accent
+                  unconditionally — the two branches are one state seen twice, and
+                  they were drifting the moment only one of them was themed. */}
+              <Text userSelect="none" size="sm" weight="medium" style={{ color: colors.accent }}>{`${label}:`}</Text>
               {summary}
             </View>
           ) : (
@@ -121,7 +124,14 @@ export function FilterChip(props: FilterChipProps) {
               userSelect="none"
               size="sm"
               weight="medium"
-              color={active ? "zinc-900" : "zinc-700"}
+              // An APPLIED filter wears the accent; an empty one stays neutral.
+              // The pill already changed its words and grew a ×, but both are
+              // read only after you look AT it — the whole job of a filter bar is
+              // to answer "is anything on?" from across the screen, and ink is the
+              // only channel that carries at that distance. It is a state, not
+              // decoration, which is what makes it a legitimate place for brand.
+              color={active ? undefined : "zinc-700"}
+              style={active ? { color: colors.accent } : undefined}
               numberOfLines={1}
             >
               {active ? `${label}: ${summary}` : label}

package/src/font_family.ts

@@ -0,0 +1,26 @@
+/**
+ * THE BODY FACE, as three weight rungs.
+ *
+ * Weight is a FAMILY in this kit, not a `font-weight`: Inter ships as three
+ * separate `@font-face` families (`Inter_400Regular` / `Inter_500Medium` /
+ * `Inter_600SemiBold`), which is the React Native convention and the reason a
+ * single family token cannot express the ladder on its own.
+ *
+ * So the tokens are per-rung, and `LoticsThemeProvider` FANS ONE VALUE OUT
+ * across all three when an app sets `bodyFont`. That is what keeps the app-facing
+ * surface at one parameter while the kit keeps a rung it can default correctly:
+ * unthemed, each rung resolves to its own Inter face; themed, all three resolve
+ * to the app's family and the numeric `font-weight` already on every style makes
+ * the weights. The fan-out lives in the provider, where it is explained once,
+ * rather than at 11 call sites that would each have to remember it.
+ */
+/** Native: literals. `var()` means nothing off the web. */
+export const fontFamilyRegular = `Inter_400Regular, "apple-system", "BlinkMacSystemFont",
+    "Segoe UI", "Roboto", "Oxygen", "Ubuntu", "Cantarell", "Fira Sans",
+    "Droid Sans", "Helvetica Neue", sans-serif`;
+export const fontFamilyMedium = `Inter_500Medium, "apple-system", "BlinkMacSystemFont",
+    "Segoe UI", "Roboto", "Oxygen", "Ubuntu", "Cantarell", "Fira Sans",
+    "Droid Sans", "Helvetica Neue", sans-serif`;
+export const fontFamilySemiBold = `Inter_600SemiBold, "apple-system", "BlinkMacSystemFont",
+    "Segoe UI", "Roboto", "Oxygen", "Ubuntu", "Cantarell", "Fira Sans",
+    "Droid Sans", "Helvetica Neue", sans-serif`;

package/src/font_family.web.ts

@@ -0,0 +1,29 @@
+/**
+ * THE BODY FACE, as three weight rungs.
+ *
+ * Weight is a FAMILY in this kit, not a `font-weight`: Inter ships as three
+ * separate `@font-face` families (`Inter_400Regular` / `Inter_500Medium` /
+ * `Inter_600SemiBold`), which is the React Native convention and the reason a
+ * single family token cannot express the ladder on its own.
+ *
+ * So the tokens are per-rung, and `LoticsThemeProvider` FANS ONE VALUE OUT
+ * across all three when an app sets `bodyFont`. That is what keeps the app-facing
+ * surface at one parameter while the kit keeps a rung it can default correctly:
+ * unthemed, each rung resolves to its own Inter face; themed, all three resolve
+ * to the app's family and the numeric `font-weight` already on every style makes
+ * the weights. The fan-out lives in the provider, where it is explained once,
+ * rather than at 11 call sites that would each have to remember it.
+ */
+/**
+ * Each rung carries its own Inter face as the inline fallback, so an app that
+ * themes nothing renders byte-identically to before these variables existed.
+ */
+export const fontFamilyRegular = `var(--lotics-font-regular, Inter_400Regular, "apple-system", "BlinkMacSystemFont",
+    "Segoe UI", "Roboto", "Oxygen", "Ubuntu", "Cantarell", "Fira Sans",
+    "Droid Sans", "Helvetica Neue", sans-serif)`;
+export const fontFamilyMedium = `var(--lotics-font-medium, Inter_500Medium, "apple-system", "BlinkMacSystemFont",
+    "Segoe UI", "Roboto", "Oxygen", "Ubuntu", "Cantarell", "Fira Sans",
+    "Droid Sans", "Helvetica Neue", sans-serif)`;
+export const fontFamilySemiBold = `var(--lotics-font-semibold, Inter_600SemiBold, "apple-system", "BlinkMacSystemFont",
+    "Segoe UI", "Roboto", "Oxygen", "Ubuntu", "Cantarell", "Fira Sans",
+    "Droid Sans", "Helvetica Neue", sans-serif)`;

package/src/index.css

@@ -1,6 +1,4 @@
 :root {
-  --font-family: "Inter", sans-serif;
-
   --font-size-xs: 12px;
   --font-size-xs-line-height: 16px;
   --font-size-sm: 14px;

package/src/pressable_row.tsx

@@ -86,7 +86,11 @@ export function PressableRow(props: PressableRowProps) {
         styles.row,
         variant === "inset" ? styles.inset : variant === "bleed" ? styles.bleed : styles.register,
         {
-          backgroundColor: pressed ? colors.zinc[200] : selected ? colors.zinc[100] : hovered ? colors.zinc[100] : marked ? colors.blue[50] : undefined,
+          // Hover and selection wear the brand's WASH, whose default IS the zinc-100
+          // these states already used — so an unthemed app is unchanged and a themed
+          // one warms every row it touches. `pressed` stays neutral and one step
+          // darker: it is a momentary depth cue, not an identity.
+          backgroundColor: pressed ? colors.zinc[200] : selected ? colors.accent_wash : hovered ? colors.accent_wash : marked ? colors.blue[50] : undefined,
         },
         style,
       ]}

package/src/summary.tsx

@@ -28,6 +28,16 @@ export interface SummaryBucket {
   color: string;
   /** What this bucket means — the ⓘ beside its count. */
   info?: string;
+  /**
+   * Valence on the bucket's COUNT, for a bucket that represents work someone has
+   * to do. Reserve it: a screen where every bucket is toned has said nothing, and
+   * the bucket holding the largest number is usually the one that needs it least
+   * (work that has left the building is not a queue).
+   *
+   * It colours the figure only. The segment keeps the bucket's own `color`, so
+   * the bar goes on reading as a distribution rather than as a heat map.
+   */
+  tone?: MetricTone;
 }
 
 interface SummaryContext {
@@ -99,13 +109,26 @@ function Header(props: { children: ReactNode }) {
 /**
  * The set's SIZE, at display scale — the band's headline.
  *
- * The number is the sum of the buckets and is never passed in. A page that
- * restates its own total eventually restates it wrongly: a bucket gets added,
+ * By DEFAULT it is the sum of the buckets, and that default is the point: a page
+ * that restates its own total eventually restates it wrongly — a bucket is added,
  * the constant does not move, and the headline quietly disagrees with the bar
  * directly beneath it.
+ *
+ * `value` overrides it, for the one case that is not a restatement: a total with
+ * its OWN authority, counted by the same source that counted the buckets. A
+ * server-paginated register is the example — the buckets are per-stage `COUNT`s
+ * over the filtered view and the size is a fourth count over that same view, so
+ * summing the three client-side would replace an authoritative number with a
+ * derived one that can differ (a bucket query filtered a shade differently, or
+ * landed a moment later) and would be believed because it is the biggest figure
+ * on the screen.
+ *
+ * The line, then: pass `value` when something ELSE counted it, never to write a
+ * literal. A number typed into this prop is the defect the default prevents.
  */
-function Total(props: { label: string; formatValue?: (n: number) => string }) {
-  const { total } = useSummary("Total");
+function Total(props: { label: string; value?: number; formatValue?: (n: number) => string }) {
+  const { total: summed } = useSummary("Total");
+  const total = props.value ?? summed;
   const tag = useLocaleTag();
   // Grouped by the reader's locale by default — a set of 12,345 was rendering
   // "12345" in the one place on the screen sized to be read first, because the
@@ -187,6 +210,7 @@ function Facts(props: { extra?: readonly SummaryLineItem[] }) {
     value: b.value,
     color: b.color,
     info: b.info,
+    tone: b.tone,
   }));
   return <SummaryLine items={[...items, ...(props.extra ?? [])]} />;
 }

package/src/table.tsx

@@ -17,6 +17,7 @@ import { Divider } from "./divider";
 import { DetailRow } from "./detail_row";
 import { SortHeader, type SortState, type SortHeaderLabels } from "./sort_header";
 import { COLUMN_GAP, ROW_GUTTER, computeTableFit, type TableFit, type TableFitColumn } from "./table_fit";
+import { ROW_WASH_BLEED } from "./control_surface";
 
 /**
  * One column of a register — its width/flex/align/label/sortability defined ONCE,
@@ -120,8 +121,36 @@ export interface TableProps {
    * Positions are yours for the same reason — see `TableRowProps.ordinal`. This
    * prop only says "this register is counted", which is what reserves the gutter
    * on the header and on every row at once, so they cannot disagree.
+   *
+   * Pass {@link TableProps.counted} INSTEAD when the page already states the
+   * total somewhere the reader will see first.
    */
   count?: number;
+  /**
+   * Number the rows WITHOUT heading the gutter with a total.
+   *
+   * The total earns its place in the header by answering "how many" without
+   * scrolling to the last row — so it stops earning it the moment the page
+   * answers that louder. A register whose band opens with the count in display
+   * type was printing the same figure twice within a hundred pixels, at the same
+   * left edge, one huge and one muted, which reads as a mistake rather than as
+   * two deliberate statements.
+   *
+   * Ignored when `count` is given; the gutter is reserved either way, so header
+   * and rows can never disagree about its width.
+   */
+  counted?: boolean;
+  /**
+   * Paint the column-header band with the brand's wash.
+   *
+   * OPT-IN, and deliberately not the default: a filled header is a real restyle
+   * of every table in every app, and the kit's language is a white canvas where
+   * a hairline does the separating. It earns its place on a register that is the
+   * page's whole content, where the band gives the columns a lid and the table
+   * stops floating; it is noise on a small table inside a card that already has
+   * edges of its own.
+   */
+  headerFill?: boolean;
   /** Reserve a trailing gutter (px) for rows that render a `trailing` slot (a ⋯ / button). */
   trailing?: number;
   /** The `TableRow`s. */
@@ -143,8 +172,11 @@ 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 ordinal = count != null ? ORDINAL_W : 0;
+  const { columns, sort, onSort, sortLabels, selectAll, leading = 0, count, counted, headerFill, trailing = 0, children } = props;
+  // Either prop reserves the gutter; only `count` puts a number in its header.
+  // `LeadGutter` already renders an empty box when it has no number — the same
+  // path a group band takes — so nothing new is needed to draw it.
+  const ordinal = count != null || counted ? ORDINAL_W : 0;
   const rows = Children.toArray(children).filter(isValidElement);
 
   // Measure-then-REVEAL (the `DetailTable` contract): the unmeasured first
@@ -174,12 +206,12 @@ export function Table(props: TableProps) {
           // select-all checkbox keeps its band: it's the bulk-select entry point,
           // aligned over the rows' leading checkboxes.
           (selectAll != null && leading > 0) || ordinal > 0 ? (
-            <View style={styles.headerBand}>
+            <View style={[styles.headerBand, headerFill ? styles.headerBandFilled : null]}>
               <LeadGutter ordinal={count}>{selectAll}</LeadGutter>
             </View>
           ) : null
         ) : (
-          <View style={styles.headerBand}>
+          <View style={[styles.headerBand, headerFill ? styles.headerBandFilled : null]}>
             {/* The TOTAL heads the column of positions — the one number that
                 answers "how many" without the reader scrolling to the last row. */}
             <LeadGutter ordinal={count}>{selectAll}</LeadGutter>
@@ -458,6 +490,16 @@ const styles = StyleSheet.create({
   },
   // A hairline under the column header anchors the columns; the rows below it are
   // Divider-separated.
+  headerBandFilled: {
+    backgroundColor: colors.accent_wash,
+    // The band bleeds to the row wash's width so its edges line up with a hovered
+    // row beneath it; without this the lid is narrower than the rows it caps.
+    marginHorizontal: -ROW_WASH_BLEED,
+    paddingHorizontal: ROW_GUTTER + ROW_WASH_BLEED,
+    paddingTop: 8,
+    borderTopLeftRadius: 8,
+    borderTopRightRadius: 8,
+  },
   headerBand: {
     paddingHorizontal: ROW_GUTTER,
     // NO top padding (GAP-85): a Table is borderless, so its container ALWAYS owns

package/src/text.tsx

@@ -1,6 +1,7 @@
 import "./text.css";
 import React from "react";
 import { Platform, Text as RNText, TextProps as RNTextProps, StyleSheet } from "react-native";
+import { fontFamilyDisplay } from "./display_font";
 import {
   fontFamilyMedium,
   fontFamilyRegular,
@@ -14,6 +15,16 @@ export interface TextProps {
   testID?: string;
   size?: TextSize;
   color?: TextColor;
+  /**
+   * `display` renders in the app's display face — a headline, a wordmark, a
+   * figure the page exists to show. Everything else stays the body face, which
+   * is not themeable (see `display_font.ts`).
+   *
+   * A ROLE, not a font name: the call site says what the text IS, and the theme
+   * decides what that looks like. Threading family strings through call sites is
+   * how one screen ends up in a different face from the next.
+   */
+  family?: "display";
   align?: TextAlign;
   weight?: TextWeight;
   numberOfLines?: number;
@@ -69,6 +80,7 @@ export function Text(props: TextProps) {
     color = "default",
     size = "sm",
     weight = "regular",
+    family,
     numberOfLines,
     decoration,
     tabular,
@@ -107,6 +119,10 @@ export function Text(props: TextProps) {
         styles.text,
         Platform.OS !== "web" && styles[size],
         styles[weight],
+        // AFTER the weight, because the weight ladder sets a family too — each
+        // rung is a distinct Inter family, not a `font-weight` — so the display
+        // face has to win the family while leaving the numeric weight alone.
+        family === "display" && { fontFamily: fontFamilyDisplay },
         // Only when ASKED for. Left to inherit, a label inside a button is
         // unselectable and a paragraph is selectable, each from its container —
         // which is what a container setting `userSelect` is trying to say.

package/src/text_utils.ts

@@ -47,17 +47,9 @@ export function getTextColor(color?: TextColor): string {
   }
 }
 
-export const fontFamilyRegular = `Inter_400Regular, "apple-system", "BlinkMacSystemFont",
-    "Segoe UI", "Roboto", "Oxygen", "Ubuntu", "Cantarell", "Fira Sans",
-    "Droid Sans", "Helvetica Neue", sans-serif`;
-
-export const fontFamilyMedium = `Inter_500Medium, "apple-system", "BlinkMacSystemFont",
-    "Segoe UI", "Roboto", "Oxygen", "Ubuntu", "Cantarell", "Fira Sans",
-    "Droid Sans", "Helvetica Neue", sans-serif`;
-
-export const fontFamilySemiBold = `Inter_600SemiBold, "apple-system", "BlinkMacSystemFont",
-    "Segoe UI", "Roboto", "Oxygen", "Ubuntu", "Cantarell", "Fira Sans",
-    "Droid Sans", "Helvetica Neue", sans-serif`;
+// The three rungs live in their own platform-split module — see `font_family.ts`.
+// Re-exported here so every existing consumer keeps one import.
+export { fontFamilyRegular, fontFamilyMedium, fontFamilySemiBold } from "./font_family";
 
 /** Line height for mobile web (prevents Safari iOS auto-zoom) */
 export const INPUT_LINE_HEIGHT_MOBILE = 24;

package/src/theme.web.tsx

@@ -1,5 +1,5 @@
 import { useMemo, type CSSProperties, type ReactNode } from "react";
-import { LoticsThemeContext, THEME_VARS, type LoticsTheme } from "./theme_context";
+import { ACCENT_WASH_VAR, deriveAccentWash, FONT_MEDIUM_VAR, FONT_SEMIBOLD_VAR, LoticsThemeContext, THEME_VARS, type LoticsTheme } from "./theme_context";
 
 export { DEFAULT_ACCENT, useLoticsTheme, THEME_VARS, type LoticsTheme } from "./theme_context";
 
@@ -46,6 +46,21 @@ export function LoticsThemeProvider(props: LoticsThemeProviderProps) {
       const value = theme[role as keyof LoticsTheme];
       if (value !== undefined) vars[name] = value;
     }
+    // The wash is DERIVED here, where the accent is still a literal — see
+    // `deriveAccentWash`. An accent the parser cannot read leaves it undefined,
+    // so those surfaces keep the neutral default instead of breaking.
+    if (theme.accent !== undefined) {
+      const wash = deriveAccentWash(theme.accent);
+      if (wash !== undefined) vars[ACCENT_WASH_VAR] = wash;
+    }
+    // ONE font value, THREE rungs. `THEME_VARS` already mapped `bodyFont` to the
+    // regular rung; medium and semibold follow it here, because a family set on
+    // only one rung would leave every medium and semibold run in Inter — the
+    // screen would come out in two typefaces and look like a loading bug.
+    if (theme.bodyFont !== undefined) {
+      vars[FONT_MEDIUM_VAR] = theme.bodyFont;
+      vars[FONT_SEMIBOLD_VAR] = theme.bodyFont;
+    }
     // `display: contents` — the provider generates NO box. Custom properties
     // inherit down the DOM tree rather than the box tree, so the variables still
     // reach every descendant while the element itself adds no layout at all.

package/src/theme_context.ts

@@ -19,8 +19,40 @@ export interface LoticsTheme {
    *  on almost every app; set it only for a deliberately toned surface. */
   background?: string;
   /** Hairlines — 48 sites in the kit, and a register is mostly these lines, so a
-   *  small change here is felt across a whole screen. */
+   *  small change here is felt against a whole screen. */
   border?: string;
+  /**
+   * THE TYPEFACE, for everything. One value — a CSS font stack — and the whole
+   * app follows it.
+   *
+   * It fans out to the three weight rungs (`font_family.ts`), because weight is
+   * a FAMILY in this kit rather than a `font-weight`. Themed, all three resolve
+   * to this family and the numeric weight already on every style makes the
+   * ladder; unthemed, each keeps its own Inter face.
+   *
+   * Pass a stack you know RESOLVES — a face nobody `@font-face`d falls silently
+   * through to system sans, which is the one failure here that looks like
+   * nothing happening. And check Vietnamese: a face without the diacritics turns
+   * "Thẩm định" into tofu.
+   *
+   * The kit's letter-spacing curve is tuned for Inter's glyphs, so another face
+   * inherits tracking chosen for a different drawing. It is a refinement, not a
+   * defect — worth an eye, not a blocker.
+   */
+  bodyFont?: string;
+  /**
+   * The typeface for DISPLAY text only — what `<Text family="display">` renders
+   * in. A headline, a wordmark, a figure the page exists to show.
+   *
+   * Defaults to `bodyFont` when that is set, so ONE parameter changes the whole
+   * app and a SECOND one is only needed to make display type differ from body —
+   * a serif masthead over a sans register, say.
+   */
+  displayFont?: string;
+  /** The PRIMARY action's fill. Defaults to the kit's near-black, so an app that
+   *  themes nothing is unchanged; set it to put the brand on the one filled
+   *  button a surface gets. Distinct from `accent`, which marks identity. */
+  primary?: string;
 }
 
 /**
@@ -31,8 +63,38 @@ export const THEME_VARS: Record<keyof LoticsTheme, string> = {
   accent: "--lotics-accent",
   background: "--lotics-background",
   border: "--lotics-border",
+  primary: "--lotics-primary",
+  bodyFont: "--lotics-font-regular",
+  displayFont: "--lotics-display-font",
 };
 
+/** The extra variable the provider DERIVES — not a role an app sets, because it
+ *  is the accent seen through alpha and two sources for one colour drift. */
+export const ACCENT_WASH_VAR = "--lotics-accent-wash";
+
+/** The two rungs `bodyFont` fans out to beyond its own `THEME_VARS` entry. */
+export const FONT_MEDIUM_VAR = "--lotics-font-medium";
+export const FONT_SEMIBOLD_VAR = "--lotics-font-semibold";
+
+/**
+ * The accent at wash strength.
+ *
+ * Computed from the literal hex the app passed, because it CANNOT be computed
+ * downstream: on web the token is a `var()`, and the kit's alpha helpers parse
+ * `rgba()` strings. Returns undefined for a value it cannot parse (a named
+ * colour, an `oklch()`), so an unparseable accent falls back to the neutral wash
+ * rather than painting rows in garbage.
+ */
+export function deriveAccentWash(accent: string): string | undefined {
+  const hex = accent.trim();
+  const m = /^#([0-9a-f]{6})$/i.exec(hex);
+  if (!m) return undefined;
+  const n = parseInt(m[1], 16);
+  // 0.07 — heavy enough to read as a tint on white, light enough that body text
+  // on top keeps its contrast; the neutral it replaces (zinc-100) sits about here.
+  return `rgba(${(n >> 16) & 255}, ${(n >> 8) & 255}, ${n & 255}, 0.07)`;
+}
+
 export const LoticsThemeContext = createContext<LoticsTheme>({});
 
 /**