pixelize-native-library 1.0.7 → 1.2.1

package/lib/module/modules/avatar/Avatar.variants.js

@@ -18,7 +18,11 @@
  * only `react-native`'s `StyleSheet`, as `core/style` and `Button.variants.ts` do).
  */
 
+import { resolveFilledAccent } from "../../theme/tokens/builders/accentText.js";
 import { createThemedVariants } from "../../core/style/index.js";
+
+/** `circle` for a person, `rounded` for an organisation/product, `square` for tiles/thumbnails. */
+
 /**
  * Avatar-specific dimensions. Kept a plain constant — no theme dependency — same as `BUTTON_SIZES` /
  * `CHECKBOX_SIZES`, so the render layer and tests share one source of truth for the diameter.
@@ -59,6 +63,32 @@ export function resolveAvatarColors(colors) {
     initialsText: colors.fg.default
   };
 }
+
+/** The ramp names an identity seed hashes onto — never the brand ramp, which would make every
+ *  identity look alike. Slot order mirrors web's `AVATAR_COLORS` so a given name lands on the same
+ *  hue on both platforms; `cyan` stands in for web's violet (this palette ships one purple ramp). */
+export const AVATAR_IDENTITY_RAMPS = ["purple", "blue", "green", "orange", "red", "pink", "cyan", "teal"];
+/** Web's `avatarColor` hash, character for character, so both platforms agree on the slot. */
+export function avatarIdentityRamp(seed) {
+  let hash = 0;
+  for (let i = 0; i < seed.length; i += 1) {
+    hash = seed.charCodeAt(i) + ((hash << 5) - hash);
+  }
+  return AVATAR_IDENTITY_RAMPS[Math.abs(hash) % AVATAR_IDENTITY_RAMPS.length];
+}
+/**
+ * A stable per-identity fill drawn from the palette's own hue ramps, with its label DERIVED by the
+ * same `resolveFilledAccent` walk every filled surface in this library uses. Web hashes onto eight
+ * fixed hex swatches and inks them with `onFilled`, which is why two of its eight measure ~2:1
+ * against white; walking a real ramp instead clears AA on every brand × mode (`Avatar.test.ts`).
+ */
+export function resolveAvatarIdentityColors(palette, seed) {
+  const filled = resolveFilledAccent(palette[avatarIdentityRamp(seed)]);
+  return {
+    containerBg: filled.fill,
+    initialsText: filled.label
+  };
+}
 /**
  * Derives the accessibility surface once, purely, so the "decorative unless labelled" contract is
  * testable without a renderer. Unlike `Button`'s icon-only shape or `Checkbox`'s unlabelled shape,
@@ -93,8 +123,7 @@ export const avatarStructure = createThemedVariants(theme => ({
   base: {
     alignItems: "center",
     justifyContent: "center",
-    overflow: "hidden",
-    borderRadius: theme.radii.full
+    overflow: "hidden"
   },
   variants: {
     size: {
@@ -118,10 +147,22 @@ export const avatarStructure = createThemedVariants(theme => ({
         width: AVATAR_SIZES.xl.box,
         height: AVATAR_SIZES.xl.box
       }
+    },
+    shape: {
+      circle: {
+        borderRadius: theme.radii.full
+      },
+      rounded: {
+        borderRadius: theme.radii.lg
+      },
+      square: {
+        borderRadius: theme.radii.none
+      }
     }
   },
   defaultVariants: {
-    size: "md"
+    size: "md",
+    shape: "circle"
   }
 }));
 //# sourceMappingURL=Avatar.variants.js.map

package/lib/module/modules/avatar/MODULE.md

@@ -1,8 +1,8 @@
 # avatar/ — a circular identity glyph (image, initials, or a plain placeholder)
 
-`Avatar` is the simplest module in the library — no press handling, no loading state, no
-animation — which is exactly why its accessibility default is the one place it deliberately
-diverges from `Button`/`Checkbox`: an avatar is almost always rendered beside a visible name, so
+`Avatar` is one of the simplest modules in the library — no press handling, no loading state —
+which is exactly why its accessibility default is the one place it deliberately diverges from
+`Button`/`Checkbox`: an avatar is almost always rendered beside a visible name, so
 `accessibilityLabel` is optional rather than a required trap.
 
 ## Files
@@ -10,29 +10,45 @@ diverges from `Button`/`Checkbox`: an avatar is almost always rendered beside a
 | File | Role |
 |------|------|
 | `Avatar.tsx` | The component. Fallback precedence (image → initials → placeholder), a11y wiring. |
-| `Avatar.variants.ts` | Pure resolvers (`AVATAR_SIZES`, `resolveAvatarColors`, `resolveAvatarAccessibility`) + the themed structural variant resolver `avatarStructure`. No React. |
-| `index.ts` | Public surface: `Avatar`, `AvatarProps`, `AvatarSize`. |
-| `__tests__/Avatar.test.ts` | Pure: WCAG contrast (all brands × modes) + the size scale + the a11y contract. |
-| `__tests__/Avatar.render.test.tsx` | Render: fallback precedence, size scale, decorative-vs-labelled a11y. |
+| `Avatar.variants.ts` | Pure resolvers (`AVATAR_SIZES`, `resolveAvatarColors`, `resolveAvatarIdentityColors`, `avatarIdentityRamp`, `resolveAvatarAccessibility`) + the themed structural variant resolver `avatarStructure`. No React. |
+| `index.ts` | Public surface: `Avatar`, `AvatarProps`, `AvatarSize`, `AvatarShape`. |
+| `__tests__/Avatar.test.ts` | Pure: WCAG contrast for the neutral **and** every identity fill (all brands × modes) + the identity hash + the size scale + the a11y contract. |
+| `__tests__/Avatar.render.test.tsx` | Render: fallback precedence, size scale, shape, identity fill, recycling key, decorative-vs-labelled a11y. |
 
 ## Props
 
 | Prop | Type | Default | Notes |
 |------|------|---------|-------|
 | `size` | `xs \| sm \| md \| lg \| xl` | `md` | Diameters 24 / 32 / 40 / 56 / 72 dp. |
+| `shape` | `circle \| rounded` | `circle` | `rounded` uses `radii.full` for an org/product; a person stays circular. |
 | `source` | `{ uri: string }` | — | A remote image. Wins over `initials` when present. |
 | `initials` | `string` | — | Shown when there is no `source`. Clipped to the first two characters. |
+| `identity` | `string` | — | Seeds a stable hashed fill for the initials/placeholder state. Absent → the neutral fill. |
+| `recyclingKey` | `string` | `source.uri` | Blanks the image the instant it changes — see Recycled lists below. |
 | `accessibilityLabel` | `string` | — | **Optional** — see Accessibility contract below. |
 | `style` | `LayoutStyle` | — | Layout-only, outermost, applied exactly once, last. |
 | `testID` | `string` | — | The image (when `source` is set) also gets `${testID}-image`. |
 
-No `tone`/`color` prop: an avatar has exactly one neutral identity (`resolveAvatarColors`), the
-same reasoning as `Checkbox`'s colour resolver — there is nothing for an app to widen.
+No `tone`/`color` prop. `identity` is a *seed*, not a colour: it hashes onto one of eight of the
+palette's own hue ramps and derives its label with the same `resolveFilledAccent` walk every filled
+surface here uses, so an app still cannot introduce an off-palette or unreadable value. Web hashes
+onto eight fixed hex swatches and inks them with `onFilled`, which is why two of its eight measure
+~2:1 against white; the slot order matches web's so a given org lands on the same hue on both.
+
+## Recycled lists — why `expo-image`, not RN's `Image`
+
+Avatar is the one image on every recycled FlashList row. RN's `Image` keeps painting the old bitmap
+until the new URI resolves, so a scrolled row shows the **previous** subject's face for a beat.
+`expo-image`'s `recyclingKey` blanks it on the spot; a 120 ms `transition` comes along with it.
+`expo-image` is an **optional peer** — the same shape `FileUpload` uses for the native pickers.
+The image itself now renders through `core/media`'s shared `MediaImage` (expo-image when installed,
+RN `Image` fallback otherwise) instead of calling `getExpoImage()` directly — same behavior, one
+fewer place to special-case the optional-peer fallback.
 
 ## Accessibility contract (WCAG)
 
-- **1.4.3** — initials text is `fg.default` on `bg.sunken`; measured ≥ 4.5:1 for every brand × mode
-  (`resolveAvatarColors`, tested in `Avatar.test.ts`).
+- **1.4.3** — initials text is `fg.default` on `bg.sunken`, or a derived label on the identity fill;
+  both measured ≥ 4.5:1 for every brand × mode (`Avatar.test.ts`).
 - **Decorative by default, unlike `Button`'s icon-only shape.** `Button`/`Checkbox` make an
   unlabelled interactive element a type error, because their label is the *only* carrier of
   meaning for a screen-reader user. An avatar is not interactive and is almost always adjacent to
@@ -49,14 +65,14 @@ same reasoning as `Checkbox`'s colour resolver — there is nothing for an app t
 
 ## Patterns copied from `Button`/`Checkbox`
 
-1. **Structure vs colour split.** Diameter + the circular radius → `createThemedVariants`
-   (`avatarStructure`, registered once per theme). Colour → resolved from role tokens
-   (`resolveAvatarColors`), applied inline.
+1. **Structure vs colour split.** Diameter + radius → `createThemedVariants` (`avatarStructure`,
+   registered once per theme). Colour → resolved from role tokens (`resolveAvatarColors`) or the
+   palette's hue ramps (`resolveAvatarIdentityColors`), applied inline.
 2. **Pure, testable resolvers** in `Avatar.variants.ts` (no React) so the WCAG + accessibility
    contract is unit-tested by measuring real palettes — never eyeballed.
 3. **`radii.full` clips a circle for any diameter.** One token (a finite `9999`, not `Infinity` —
    RN rejects non-finite style values) covers every size instead of each variant computing its own
-   `box / 2`.
+   `box / 2`; `shape="rounded"` swaps it for `radii.full`.
 4. **`style: LayoutStyle` last and once, no `{...rest}`** — internals never receive consumer style.
 
 ## Testing note — hidden elements and React Native Testing Library
@@ -74,3 +90,9 @@ the tree but intentionally unreachable by assistive tech — see `Avatar.render.
 ## Performance
 
 Wrapped in `React.memo` (repo-wide re-render audit, 2026-07-17 — see root `CLAUDE.md`). No child library component receives a derived array/object/callback, so no `useCallback`/`useMemo` was needed.
+
+## Modernization (v1.0.7)
+
+- Theme imports decoupled to `theme/hooks`; optional peers (reanimated, gesture-handler, flash-list) load at runtime.
+- List-heavy surfaces use `VirtualList` with device-tier window sizing where applicable.
+- `React.memo` + stable callbacks retained; render-item/key-extractor hoisted per ESLint perf rules.

package/lib/module/modules/avatar-group/AvatarGroup.js

@@ -0,0 +1,81 @@
+"use strict";
+
+/**
+ * AvatarGroup — a horizontal stack of `Avatar`s with negative overlap and a `+N` overflow pill when
+ * `avatars.length` exceeds `max`. Each face is this library's own `Avatar` module — never a hand-rolled
+ * image/initials pair — so list recycling, identity hashing, and shape defaults stay consistent.
+ *
+ * No `accessibilityRole` of its own. Each composed `Avatar` gets a label — the consumer's, or (since
+ * a grouped face has no adjacent visible name to lean on, unlike a standalone `Avatar`) a generic
+ * `resolveAvatarGroupFaceFallbackLabel` fallback. The overflow pill carries its own `"text"`-role
+ * label so a screen reader hears how many faces are hidden, not just the ones on screen.
+ */
+
+import { memo, useMemo } from "react";
+import { Text, View } from "react-native";
+import { useTheme } from "../../theme/hooks.js";
+import { Avatar } from "../avatar/index.js";
+import { AVATAR_GROUP_DEFAULT_MAX, avatarGroupItemStructure, avatarGroupOverflowLabelStructure, avatarGroupOverflowStructure, avatarGroupStructure, resolveAvatarGroupColors, resolveAvatarGroupFaceFallbackLabel, resolveAvatarGroupOverflowAccessibility, resolveAvatarGroupOverflowCount, resolveAvatarGroupOverlap, resolveAvatarGroupVisibleCount } from "./AvatarGroup.variants.js";
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+export const AvatarGroup = /*#__PURE__*/memo(function AvatarGroup({
+  avatars,
+  max = AVATAR_GROUP_DEFAULT_MAX,
+  size = "md",
+  style,
+  testID
+}) {
+  const theme = useTheme();
+  const colors = useMemo(() => resolveAvatarGroupColors(theme.colors), [theme.colors]);
+  const overlap = resolveAvatarGroupOverlap(size);
+  const visibleCount = resolveAvatarGroupVisibleCount(avatars.length, max);
+  const overflowCount = resolveAvatarGroupOverflowCount(avatars.length, visibleCount);
+  const overflowAccessibility = resolveAvatarGroupOverflowAccessibility(overflowCount);
+  const visibleAvatars = useMemo(() => avatars.slice(0, visibleCount), [avatars, visibleCount]);
+  const rootStyle = useMemo(() => [avatarGroupStructure(theme), style], [theme, style]);
+  const faces = useMemo(() => visibleAvatars.map((item, index) => /*#__PURE__*/_jsx(View, {
+    style: [avatarGroupItemStructure(theme), {
+      borderColor: colors.ring,
+      marginLeft: index === 0 ? 0 : overlap,
+      zIndex: visibleAvatars.length - index
+    }],
+    children: /*#__PURE__*/_jsx(Avatar, {
+      size: size,
+      source: item.source,
+      initials: item.initials,
+      identity: item.identity,
+      accessibilityLabel: item.accessibilityLabel ?? resolveAvatarGroupFaceFallbackLabel(index),
+      testID: testID === undefined ? undefined : `${testID}-avatar-${index}`
+    })
+  }, `${item.source?.uri ?? item.initials ?? item.identity ?? "avatar"}-${index}`)), [visibleAvatars, theme, colors, overlap, size, testID]);
+  const overflowStyle = useMemo(() => [avatarGroupItemStructure(theme), avatarGroupOverflowStructure(theme, {
+    size
+  }), {
+    borderColor: colors.ring,
+    marginLeft: overlap,
+    backgroundColor: colors.overflowBackground,
+    alignItems: "center",
+    justifyContent: "center",
+    zIndex: 0
+  }], [theme, size, colors, overlap]);
+  const overflowLabelStyle = useMemo(() => [theme.fontStyleForWeight(theme.fontWeights.semibold), avatarGroupOverflowLabelStructure(theme, {
+    size
+  }), {
+    color: colors.overflowText
+  }], [theme, size, colors]);
+  return /*#__PURE__*/_jsxs(View, {
+    testID: testID,
+    style: rootStyle,
+    children: [faces, overflowCount > 0 ? /*#__PURE__*/_jsx(View, {
+      testID: testID === undefined ? undefined : `${testID}-overflow`,
+      accessible: overflowAccessibility.accessible,
+      accessibilityRole: overflowAccessibility.accessibilityRole,
+      accessibilityLabel: overflowAccessibility.accessibilityLabel,
+      style: overflowStyle,
+      children: /*#__PURE__*/_jsx(Text, {
+        style: overflowLabelStyle,
+        children: `+${overflowCount}`
+      })
+    }) : null]
+  });
+});
+//# sourceMappingURL=AvatarGroup.js.map

package/lib/module/modules/avatar-group/AvatarGroup.variants.js

@@ -0,0 +1,132 @@
+"use strict";
+
+/**
+ * AvatarGroup's style resolution — same split as `Avatar.variants`:
+ *  - STRUCTURE (row overlap, overflow pill sizing) lives in the themed resolvers and plain constants.
+ *  - COLOUR is resolved from the theme's ROLE colours, never a raw ramp and never a hardcoded hex.
+ *
+ * Free of React and lucide, so the behaviour tests import this directly (mocking only
+ * `react-native`'s `StyleSheet`, as `core/style` and every sibling module's tests do).
+ */
+
+import { createThemedTextVariants, createThemedVariants } from "../../core/style/index.js";
+import { AVATAR_SIZES } from "../avatar/Avatar.variants.js";
+
+/** Default visible faces before collapsing the remainder into a `+N` overflow pill. */
+export const AVATAR_GROUP_DEFAULT_MAX = 4;
+
+/** Ring width separating stacked faces — drawn in the canvas colour so each face reads distinctly. */
+export const AVATAR_GROUP_RING_WIDTH = 2;
+export function resolveAvatarGroupColors(colors) {
+  return {
+    ring: colors.bg.canvas,
+    overflowBackground: colors.bg.sunken,
+    overflowText: colors.fg.muted
+  };
+}
+
+/** Negative overlap as a fraction of the avatar diameter — same visual density as common stacked rows. */
+export function resolveAvatarGroupOverlap(size) {
+  return Math.round(AVATAR_SIZES[size].box * -0.25);
+}
+export function resolveAvatarGroupVisibleCount(total, max) {
+  if (total <= max) return total;
+  // Reserve one slot for the overflow pill when there are hidden faces.
+  return Math.max(1, max - 1);
+}
+export function resolveAvatarGroupOverflowCount(total, visible) {
+  return Math.max(0, total - visible);
+}
+/**
+ * WCAG 2.5.3: the accessible name must CONTAIN the visible "+N" text (same contract as
+ * `MoreItems`'s trigger), so a voice-control user saying what they read still lands on this pill.
+ * `"text"`, not `"button"` — the pill is informational chrome, not interactive (same as `Badge`).
+ */
+export function resolveAvatarGroupOverflowAccessibility(count) {
+  return {
+    accessible: true,
+    accessibilityRole: "text",
+    accessibilityLabel: `+${count} more`
+  };
+}
+
+/**
+ * A face's honest-but-generic name when its consumer never set `accessibilityLabel`. Unlike a
+ * standalone `Avatar` (usually sits beside a visible name, so undecorated is a fair default —
+ * see `resolveAvatarAccessibility`), a grouped face has no adjacent name: falling through to
+ * `Avatar`'s decorative default would leave a screen reader user unable to tell how many distinct
+ * people the stack represents.
+ */
+export function resolveAvatarGroupFaceFallbackLabel(index) {
+  return `Avatar ${index + 1}`;
+}
+export const avatarGroupStructure = createThemedVariants(_theme => ({
+  base: {
+    flexDirection: "row",
+    alignItems: "center"
+  }
+}));
+export const avatarGroupItemStructure = createThemedVariants(_theme => ({
+  base: {
+    borderWidth: AVATAR_GROUP_RING_WIDTH
+  }
+}));
+export const avatarGroupOverflowStructure = createThemedVariants(theme => ({
+  variants: {
+    size: {
+      xs: {
+        width: AVATAR_SIZES.xs.box,
+        height: AVATAR_SIZES.xs.box,
+        borderRadius: theme.radii.full
+      },
+      sm: {
+        width: AVATAR_SIZES.sm.box,
+        height: AVATAR_SIZES.sm.box,
+        borderRadius: theme.radii.full
+      },
+      md: {
+        width: AVATAR_SIZES.md.box,
+        height: AVATAR_SIZES.md.box,
+        borderRadius: theme.radii.full
+      },
+      lg: {
+        width: AVATAR_SIZES.lg.box,
+        height: AVATAR_SIZES.lg.box,
+        borderRadius: theme.radii.full
+      },
+      xl: {
+        width: AVATAR_SIZES.xl.box,
+        height: AVATAR_SIZES.xl.box,
+        borderRadius: theme.radii.full
+      }
+    }
+  },
+  defaultVariants: {
+    size: "md"
+  }
+}));
+export const avatarGroupOverflowLabelStructure = createThemedTextVariants(_theme => ({
+  variants: {
+    size: {
+      xs: {
+        fontSize: AVATAR_SIZES.xs.fontSize
+      },
+      sm: {
+        fontSize: AVATAR_SIZES.sm.fontSize
+      },
+      md: {
+        fontSize: AVATAR_SIZES.md.fontSize
+      },
+      lg: {
+        fontSize: AVATAR_SIZES.lg.fontSize
+      },
+      xl: {
+        fontSize: AVATAR_SIZES.xl.fontSize
+      }
+    }
+  },
+  defaultVariants: {
+    size: "md"
+  }
+}));
+//# sourceMappingURL=AvatarGroup.variants.js.map

package/lib/module/modules/avatar-group/MODULE.md

@@ -0,0 +1,44 @@
+# avatar-group/ — stacked avatars with overflow count
+
+`AvatarGroup` renders a horizontal stack of library `Avatar`s with negative overlap and a `+N`
+overflow pill when `avatars.length` exceeds `max`.
+
+## Files
+
+| File | Role |
+|------|------|
+| `AvatarGroup.tsx` | The component. Composes `Avatar` + overflow pill; `style` last. |
+| `AvatarGroup.variants.ts` | Pure resolvers (colours, overlap math, overflow counts) + themed structural resolvers. |
+| `index.ts` | Public surface: `AvatarGroup`, `AvatarGroupProps`, `AvatarGroupItem`, `AvatarSize`. |
+| `__tests__/AvatarGroup.test.ts` | Pure: overflow math, WCAG on overflow pill label. |
+| `__tests__/AvatarGroup.render.test.tsx` | Render: visible faces + `+N` pill, consumer `style` last. |
+
+## Props
+
+| Prop | Type | Default | Notes |
+|------|------|---------|-------|
+| `avatars` | `AvatarGroupItem[]` | — | Required. Each item forwards to `Avatar`. |
+| `max` | `number` | `4` | Visible faces before collapsing remainder into `+N`. |
+| `size` | `AvatarSize` | `"md"` | Shared size for every face and the overflow pill. |
+| `style` | `LayoutStyle` | — | Layout-only, outermost, last. |
+| `testID` | `string` | — | Forwarded to the outermost `View`; faces get `${testID}-avatar-{i}`. |
+
+## Accessibility
+
+- **Overflow pill** carries `accessible` + `accessibilityRole="text"` + an accessibility label
+  (`"+N more"`, containing the visible `"+N"` per WCAG 2.5.3, same contract as `MoreItems`) instead
+  of being hidden from assistive tech — a screen reader user now hears how many faces are hidden.
+- **Per-face labels** fall back to `resolveAvatarGroupFaceFallbackLabel` (`"Avatar {n}"`) when a
+  consumer doesn't set `AvatarGroupItem.accessibilityLabel` — a grouped face has no adjacent visible
+  name to lean on, unlike a standalone `Avatar`, so leaving it unlabeled would leave it silent.
+
+## Borders (Wave 5 tonal restyle)
+
+The `AVATAR_GROUP_RING_WIDTH` ring (`avatarGroupItemStructure`) is deliberately KEPT, unlike other
+modules' container hairlines: it is drawn in `colors.ring` (`bg.canvas`, not a visible stroke
+colour) purely to cut a gap between overlapping circular faces — a divider BETWEEN adjacent avatars,
+not decorative container chrome. Removing it would let overlapping faces visually merge.
+
+## Performance
+
+Wrapped in `React.memo`. Visible slice is `useMemo`'d on `avatars` and `max`.

package/lib/module/modules/avatar-group/index.js

@@ -0,0 +1,10 @@
+"use strict";
+
+/**
+ * Public surface of `pixelize-native-library/avatar-group`. Value exports and type exports are split
+ * for `verbatimModuleSyntax`. The resolvers stay internal — a consumer configures an AvatarGroup
+ * through its props, never by importing its internals.
+ */
+
+export { AvatarGroup } from "./AvatarGroup.js";
+//# sourceMappingURL=index.js.map

package/lib/module/modules/badge/Badge.js

@@ -9,12 +9,14 @@
 import { memo } from "react";
 import { Text, View } from "react-native";
 import { Icon } from "../../core/icon/index.js";
-import { useTheme } from "../../theme/index.js";
+import { AccentGradientFill } from "../../core/gradient/index.js";
+import { useTheme } from "../../theme/hooks.js";
 import { BADGE_SIZES, badgeStructure, resolveBadgeAccessibility, resolveBadgeTone } from "./Badge.variants.js";
 import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
 const ICON_STROKE = 2;
 export const Badge = /*#__PURE__*/memo(function Badge({
   tone = "accent",
+  customColors,
   size = "md",
   label,
   icon,
@@ -23,10 +25,11 @@ export const Badge = /*#__PURE__*/memo(function Badge({
 }) {
   const theme = useTheme();
   const spec = BADGE_SIZES[size];
-  const toneColors = resolveBadgeTone(theme.colors, tone);
+  const toneColors = resolveBadgeTone(theme.colors, tone, customColors);
   const a11y = resolveBadgeAccessibility({
     label
   });
+  const useGradient = tone === "accent";
   return /*#__PURE__*/_jsxs(View, {
     testID: testID,
     accessible: a11y.accessible,
@@ -35,19 +38,23 @@ export const Badge = /*#__PURE__*/memo(function Badge({
     style: [badgeStructure(theme, {
       size
     }), {
-      backgroundColor: toneColors.fill,
-      borderColor: toneColors.border
+      borderColor: toneColors.border,
+      overflow: "hidden"
+    }, !useGradient && {
+      backgroundColor: toneColors.fill
     }, style],
-    children: [icon && /*#__PURE__*/_jsx(Icon, {
+    children: [useGradient && /*#__PURE__*/_jsx(AccentGradientFill, {
+      color: theme.colors.accent.solid
+    }), icon && /*#__PURE__*/_jsx(Icon, {
       name: icon,
       size: spec.iconSize,
-      color: toneColors.text,
+      color: useGradient ? theme.colors.accent.onSolid : toneColors.text,
       strokeWidth: ICON_STROKE
     }), /*#__PURE__*/_jsx(Text, {
       numberOfLines: 1,
       style: [theme.fontStyleForWeight(theme.fontWeights.semibold), {
         fontSize: spec.fontSize,
-        color: toneColors.text
+        color: useGradient ? theme.colors.accent.onSolid : toneColors.text
       }],
       children: label
     })]

package/lib/module/modules/badge/Badge.variants.js

@@ -13,7 +13,7 @@
 
 import { createThemedVariants } from "../../core/style/index.js";
 
-/** `accent`/`neutral` are brand-driven emphasis; the rest mirror the theme's status roles. */
+/** `custom` requires `customColors` — server-driven hex escape hatch. */
 
 /**
  * Badge-specific dimensions — a chip is never a touch target (Badge is a `View`, not a
@@ -53,7 +53,17 @@ export const BADGE_SIZES = {
  * and measures ≥ 5.05:1 against the canvas incidentally) — so the border reuses it, giving a
  * coloured outline that always matches the label, never an unreadable hairline.
  */
-export function resolveBadgeTone(colors, tone) {
+export function resolveBadgeTone(colors, tone, customColors) {
+  if (tone === "custom") {
+    if (!customColors) {
+      throw new Error('Badge tone="custom" requires customColors={{ bg, fg }}.');
+    }
+    return {
+      fill: customColors.bg,
+      text: customColors.fg,
+      border: customColors.fg
+    };
+  }
   switch (tone) {
     case "accent":
       return {
@@ -102,7 +112,8 @@ export const badgeStructure = createThemedVariants(theme => ({
     alignItems: "center",
     justifyContent: "center",
     columnGap: theme.space[1],
-    borderRadius: theme.radii.base,
+    borderRadius: theme.radii.md,
+    borderCurve: "continuous",
     borderWidth: theme.borderWidths.thin
   },
   variants: {

package/lib/module/modules/badge/MODULE.md

@@ -18,7 +18,8 @@ or disabled state.
 
 | Prop | Type | Default | Notes |
 |------|------|---------|-------|
-| `tone` | `accent \| neutral \| success \| warning \| danger \| info` | `accent` | Closed union — see below. |
+| `tone` | `accent \| neutral \| success \| warning \| danger \| info \| custom` | `accent` | Closed union — see below. |
+| `customColors` | `{ bg, fg }` | — | Required when `tone="custom"`. Server-driven hex escape hatch. |
 | `size` | `sm \| md` | `md` | 20 / 24 dp. No touch-target floor — not interactive. |
 | `label` | `string` | — | Always required; a Badge is never icon-only. |
 | `icon` | `IconName` | — | A NAME, never a `ReactNode`. Optional, leading only. |
@@ -40,10 +41,9 @@ or disabled state.
 ## Why `tone` is a union, not a `color`
 
 Same reasoning as Button/Input: every colour a Badge can show is a role lookup
-(`resolveBadgeTone`), guaranteed legible in both modes, never an app-invented hex. `accent`/
-`neutral` mirror Button's tone shapes at "subtle" emphasis only (a badge never uses a solid fill —
-it's a passive label, not a call-to-action). The four status tones map onto
-`colors.status.<role>`.
+(`resolveBadgeTone`), guaranteed legible in both modes, never an app-invented hex — except
+`tone="custom"`, which requires `customColors={{ bg, fg }}` and maps fill/text/border from those
+values (the same escape hatch `Chip` and `SelectOption` share for workflow-driven colours).
 
 ## A real gap this module found: `StatusColors.border` is not a badge border
 
@@ -80,3 +80,9 @@ brand × mode.
 ## Performance
 
 Wrapped in `React.memo` (repo-wide re-render audit, 2026-07-17 — see root `CLAUDE.md`). Its one child, `Icon`, only ever receives primitives — nothing to memoize.
+
+## Modernization (v1.0.7)
+
+- Theme imports decoupled to `theme/hooks`; optional peers (reanimated, gesture-handler, flash-list) load at runtime.
+- List-heavy surfaces use `VirtualList` with device-tier window sizing where applicable.
+- `React.memo` + stable callbacks retained; render-item/key-extractor hoisted per ESLint perf rules.