@mrmeg/expo-ui 0.18.0 → 0.20.0

package/CHANGELOG.md

@@ -3,6 +3,139 @@
 All notable changes to `@mrmeg/expo-ui` are documented here. This project
 adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [0.20.0]
+
+### Added
+
+- **`surfaceSunken` semantic token.** The app-chrome tier below `background`,
+  so sidebars, rails, and side panels read as a layer *beneath* the content
+  pane instead of the same surface. Dark `#050506` (below zinc-950), light
+  `#FAFAFA` (zinc-50). Elevation is now a surface-tier ladder rather than a
+  shadow scale: `surfaceSunken` < `background` < `card`/`popover` < `muted`.
+
+- **`borderStrong` semantic token.** A hairline for elements sitting on a
+  filled surface — chips on `muted`, raised panels — one visible step above
+  the fill, where `border` shares `muted`'s hex and disappears. Dark
+  `#3F3F46` (zinc-700), light `#D4D4D8` (zinc-300). `border` stays the
+  hairline for elements on `background`/`card`.
+
+- **SSR theme seeding (`SsrThemeSeedContext`).** On a server-rendered web app,
+  `useTheme`/`useStyles` had no way to know the visitor's theme during the
+  server render, so every SSR page shipped a fully light-themed tree that
+  recolored after hydration. The store can't carry a per-request value — it's a
+  module singleton shared by concurrent SSR requests — so the new
+  `SsrThemeSeedContext` (with `SsrThemeSeed`, `SSR_THEME_SEED_DEFAULT`, and
+  `useSsrThemeSeed`) is the per-request channel. Provide it from a signal the
+  server and browser read identically (a cookie), and `useTheme` resolves from
+  it on web until persistence has loaded.
+
+  `SSR_THEME_SEED_DEFAULT` is `system`/light, i.e. what the store boots with —
+  so a host that receives no signal renders exactly as it did before the seed
+  existed. Note that this default is a *fallback*, not a reading: a host that
+  also writes the resolved scheme into its served HTML (`<html data-theme>`, a
+  blocking script's early-return, a `prefers-color-scheme` CSS fallback) must
+  distinguish "seed came from the visitor" from "seed is the default" and skip
+  the write in the latter case, or it will pin a dark-OS first-time visitor to
+  light with its own failsafes disabled.
+
+- **`user-theme-preference` cookie mirror.** On web, `setTheme` now dual-writes
+  `localStorage` **and** a `user-theme-preference` cookie (`path=/;
+  max-age≈1y; SameSite=Lax`, exported as `THEME_COOKIE_NAME`), and `loadTheme`
+  backfills/repairs it from `localStorage`, so a server-rendered host can read
+  the visitor's theme off the request. `localStorage` remains the source of
+  truth; the cookie is a render hint only. Native persistence is unchanged.
+
+- **`hasLoadedTheme` on the theme store.** False until `loadTheme()` has read
+  persistence (or `setTheme` was called). While it's false on web, `useTheme`
+  resolves from the SSR seed instead of store state; after that, store state
+  wins for good. Mirrors the `hasLoadedOnboarding` pattern.
+
+### Changed
+
+- **Dim text is more readable in both schemes (visual change).**
+  `textDim`/`mutedForeground` moved from `#A1A1AA` → `#B0B0B8` in dark
+  (~9.2:1 on `background`, ~6.9:1 on `muted`, up from ~7.8:1/~5.9:1) and from
+  zinc-500 `#71717A` → zinc-600 `#52525B` in light (~7.7:1 on white, up from
+  ~4.8:1). Captions, timestamps, meta rows, and neutral `StatCard` changes all
+  render a step brighter (dark) or darker (light) than before; both stay
+  clearly dimmer than `text`, so hierarchy is preserved. A new package test
+  enforces the floors (≥7:1 on `background`/`card`/`popover`, ≥6:1 on
+  `muted`/`secondary`), so these tokens cannot be dimmed back down silently.
+  Apps that hardcoded the old hexes, or asserted them in tests, need to update
+  those literals; apps using the tokens get the change for free.
+
+- **`Drawer` chrome paints `surfaceSunken`.** Both the overlay drawer panel and
+  the in-flow rail switched from `background` to `surfaceSunken`, so navigation
+  chrome is visibly darker than the content it sits beside (dark) or a faint
+  step off white (light). Override via the existing `style` props, or re-skin
+  `surfaceSunken` through `setColors`/`ThemeColorScope`, to restore the old
+  flat look.
+
+- **`syncThemeFromEnvironment()` starts the OS listener before reading
+  persistence.** `loadTheme()` is what flips `hasLoadedTheme` (the moment web
+  renders stop trusting the SSR seed), so the real OS scheme is now read first
+  and a `system` user never sees a frame of the boot-default light.
+
+## [0.19.0]
+
+### Added
+
+- **`Avatar` and `AvatarGroup`.** The package had `SkeletonAvatar` (a loading
+  placeholder) but no real avatar, so consumers hand-rolled circles. `Avatar`
+  renders an image with a graceful fallback chain — image → initials → icon —
+  and downgrades to initials at runtime when the image fails to load, so a
+  dead URL never leaves an empty hole. Accepts `source`, `name` (supplies 1–2
+  initials and the default accessibility label), `icon` (Feather, defaults to
+  `user`), `size` (`"sm" | "md" | "lg"` = 32/40/48, or an explicit pixel
+  diameter), and `shape` (`"circle" | "square"`). Initials derivation is
+  grapheme-aware: a decomposed accented character keeps its mark and an emoji
+  is not sliced into a lone surrogate.
+
+  `AvatarGroup` stacks children with a ring in the theme `background` color so
+  the stack reads on any surface, collapses anything past `max` into a `+N`
+  tile, propagates its `size` and `shape` to children that don't set their own,
+  and announces the total count (including the collapsed overflow) to screen
+  readers.
+
+  Uses React Native's own `Image`, so there is no new peer dependency.
+
+- **`Carousel` — horizontally snapping slide row with dot indicators.**
+  Children-based: each child becomes one slide at the resolved item width.
+
+  ```tsx
+  <Carousel itemWidth={0.8} onIndexChange={setPage}>
+    {testimonials.map((t) => (
+      <Card key={t.name}>
+        <BodyText>{t.quote}</BodyText>
+      </Card>
+    ))}
+  </Carousel>
+  ```
+
+  `itemWidth` (default `0.85`) is a fraction of the carousel's own width when
+  `<= 1` — leaving the next slide peeking — and absolute pixels when `> 1`.
+  `gap`, `contentPadding`, `showDots`, `initialIndex`, `onIndexChange`, and
+  `snap` cover the rest; dots are plain themed views (active uses `accent`)
+  and auto-hide for a single slide. `onIndexChange` fires once per settle.
+
+  Built on `ScrollView`, not a virtualized list, so every slide is in the
+  server-rendered tree — web SSR ships the real slide content instead of an
+  empty scroller that fills in after measurement. No animation library is
+  involved: native snapping uses `snapToInterval`, and because
+  react-native-web drops that prop, web gets equivalent CSS scroll-snap
+  (`scroll-snap-type`/`scroll-snap-align` plus a `scroll-padding-left` that
+  keeps page `i` at `i * (itemWidth + gap)` on both platforms). Wheel and
+  trackpad scrolling keep the dots live via throttled scroll ticks, since RNW
+  emits no momentum events.
+
+  Accessibility: the dot row is a `tablist` of `tab`s carrying
+  `selected` state and per-slide labels, plus a visually clipped
+  `aria-live="polite"` "N of M" page announcement.
+
+  `getCarouselIndex(offsetX, interval, count)` and
+  `resolveCarouselItemWidth(itemWidth, containerWidth)` are exported for hosts
+  building custom controls on the same math.
+
 ## [0.18.0]
 
 ### Added

package/LLM_USAGE.md

@@ -107,11 +107,13 @@ configureExpoUiI18n((key, options) => i18n.t(key, options));
 Useful theme tokens include:
 
 ```tsx
+theme.colors.surfaceSunken;
 theme.colors.background;
 theme.colors.foreground;
 theme.colors.card;
 theme.colors.popover;
 theme.colors.border;
+theme.colors.borderStrong;
 theme.colors.input;
 theme.colors.ring;
 theme.colors.primary;
@@ -131,6 +133,13 @@ Token intent:
 - `input`: form-control border color
 - `ring`: focus outline color
 - `popover`: elevated overlay surface
+- `surfaceSunken`: app-chrome surface one tier below `background`
+- `borderStrong`: hairline for elements on filled surfaces, where `border` would blend in
+
+Elevation is a surface-tier ladder, not shadow depth:
+`surfaceSunken` (chrome) < `background` (content) < `card`/`popover` (raised)
+< `muted` (chips, insets). Border a raised or filled element with
+`borderStrong`; `border` is for hairlines on `background`/`card`.
 
 Use `getShadowStyle()` for package surfaces that need elevation. It supports
 `base`, `soft`, `sharp`, `subtle`, `elevated`, `glow`, `glass`, `card`,
@@ -187,10 +196,12 @@ Use this table before creating a new app-local primitive.
 | `Accordion`, `AccordionItem`, `AccordionTrigger`, `AccordionContent` | Multi-section disclosure | Custom FAQ/settings expanders | FAQ lists, grouped settings, help sections |
 | `Alert` | Cross-platform imperative alerts | Direct `window.alert` or duplicated RN/web branching | Confirm destructive actions, native alert dialogs |
 | `AnimatedView` | Entrance and visibility animation | Hand-rolled one-off Animated wrappers | Staggered list rows, revealed panels, animated empty states |
+| `Avatar`, `AvatarGroup` | Profile images with initials/icon fallback | Hand-rolled circles with a nested `Image` and initials `Text` | Account menu, comment authors, assignee pickers, overlapping team stacks |
 | `Badge` | Short status labels | Custom pill `View` + `Text` | Draft/active states, counts, plan labels, role tags |
 | `BottomSheet` | Mobile-first modal sheets | Custom absolute-position sheets | Action pickers, mobile filters, keyboard-aware quick edit forms |
 | `Button` | Commands and CTAs | Pressable plus custom text styling | Submit, save, cancel, delete, navigation CTAs |
 | `Card`, `CardHeader`, `CardTitle`, `CardDescription`, `CardContent`, `CardFooter` | Framed content groups | Ad hoc bordered panels | List items, pricing plans, settings sections, summaries |
+| `Carousel` | Horizontally snapping slide rows with dot indicators | Hand-rolled snap `ScrollView` plus manual offset math | Testimonial strips, onboarding pages, feature highlights, image galleries |
 | `Checkbox` | Boolean selection | Custom checkmark controls | Terms consent, checklist items, multi-select filters |
 | `Collapsible`, `CollapsibleTrigger`, `CollapsibleContent` | One-off disclosure | Local animated height wrappers | Advanced settings, hidden helper text |
 | `Dialog`, `AlertDialog` | Modal decisions and custom modal content | Custom modal overlays | Confirm delete, edit profile, invite user |
@@ -227,8 +238,10 @@ Use this table before creating a new app-local primitive.
 - Use `RadioGroup` for small mutually exclusive choices and `Select` for longer option sets.
 - Use `Dialog` for blocking decisions, `Popover` for contextual controls, `Tooltip` for short explanations, and `DropdownMenu` for action lists.
 - Use `Card` for individual repeated or framed items, not as a wrapper around full page sections.
+- Use `Carousel` for a horizontal snap row of a known, small set of slides. It renders every child (no virtualization), so slides survive server rendering; reach for `FlatList` when the data set is large or unbounded.
 - Use `EmptyState` for no-data or recoverable error regions.
 - Use `Skeleton` for loading content with stable layout.
+- Use `Avatar` with both `source` and `name` whenever both exist: `name` supplies the initials shown when the image is absent or fails, plus the default accessibility label. Never hand-roll a circle with a nested `Image` and initials `Text`. Inside `AvatarGroup`, set `size`/`shape` on the group — children inherit them and gain the ring.
 - Use `Progress` for real progress or indeterminate long-running work.
 - Use `Drawer.Header` with `icon`, `title`, and `action` for a compact app-brand row; place `Drawer.ToggleCollapse` in `action` for a trailing rail control.
 

package/README.md

@@ -101,7 +101,9 @@ const styles = StyleSheet.create({
 });
 ```
 
-`useTheme()` returns the active `theme`, resolved `scheme`, persisted `currentTheme`, `setTheme`, `toggleTheme`, cross-platform shadow helpers, a web focus-ring helper, contrast helpers, and `withAlpha`. `getShadowStyle(type)` supports `base`, `soft`, `sharp`, `subtle`, `elevated`, `glow`, `glass`, `card`, `cardHover`, and `cardSubtle`. Use semantic tokens such as `theme.colors.background`, `foreground`, `card`, `popover`, `border`, `input`, `ring`, `primary`, `secondary`, `accent`, `mutedForeground`, `destructive`, `success`, and `warning`. `primary` is the neutral action color, `secondary` is a neutral secondary surface, `accent` is the teal highlight color, `input` is the default form-control border, and `ring` is the focus outline color.
+`useTheme()` returns the active `theme`, resolved `scheme`, persisted `currentTheme`, `setTheme`, `toggleTheme`, cross-platform shadow helpers, a web focus-ring helper, contrast helpers, and `withAlpha`. `getShadowStyle(type)` supports `base`, `soft`, `sharp`, `subtle`, `elevated`, `glow`, `glass`, `card`, `cardHover`, and `cardSubtle`. Use semantic tokens such as `theme.colors.surfaceSunken`, `background`, `foreground`, `card`, `popover`, `border`, `borderStrong`, `input`, `ring`, `primary`, `secondary`, `accent`, `mutedForeground`, `destructive`, `success`, and `warning`. `primary` is the neutral action color, `secondary` is a neutral secondary surface, `accent` is the teal highlight color, `input` is the default form-control border, and `ring` is the focus outline color.
+
+Surfaces are layered tiers rather than shadow depths: `surfaceSunken` (app chrome, e.g. the Drawer rail) sits below `background` (content), which sits below `card`/`popover` (raised panels), which sit below `muted` (chips and insets). `border` is the hairline for elements on `background`/`card`; use `borderStrong` when the element sits on a filled surface, where `border` would blend into the fill. `textDim`/`mutedForeground` are tuned for readability — at least 7:1 against `background`/`card` and 6:1 against `muted` in both schemes — and a package test enforces those floors.
 
 When `currentTheme` is `"system"`, the package tracks the OS color scheme and
 updates all `useTheme()` and `useStyles()` consumers through the package theme
@@ -295,10 +297,12 @@ All components are exported from `@mrmeg/expo-ui/components`; direct imports suc
 | `Accordion`, `AccordionItem`, `AccordionTrigger`, `AccordionContent` | Multi-section disclosure | Custom FAQ/settings expanders | FAQ lists, grouped settings, help sections, dense detail pages |
 | `Alert` | Cross-platform imperative alerts | Direct `window.alert` or duplicated RN/web branching | Confirm destructive actions, native alert dialogs, simple blocking messages |
 | `AnimatedView` | Entrance and visibility animation | Hand-rolled one-off Animated wrappers | Staggered list rows, revealed panels, animated empty states |
+| `Avatar`, `AvatarGroup` | Profile images with initials/icon fallback | Hand-rolled circles with a nested `Image` and initials `Text` | Account menu, comment authors, assignee pickers, testimonial cards, overlapping team/collaborator stacks |
 | `Badge` | Short status labels | Custom pill `View` + `Text` | Draft/active states, counts, plan labels, role tags |
 | `BottomSheet` | Mobile-first modal sheets | Custom absolute-position sheets | Action pickers, mobile filters, keyboard-aware quick edit forms, contextual details |
 | `Button` | Commands and CTAs | Pressable plus custom text styling | Submit, save, cancel, delete, navigation CTAs, icon-accessory buttons; loading state preserves resting width |
 | `Card`, `CardHeader`, `CardTitle`, `CardDescription`, `CardContent`, `CardFooter` | Framed content groups | Ad hoc bordered panels | List items, pricing plans, settings sections, summaries, dashboards |
+| `Carousel` | Horizontally snapping slide rows with dot indicators | Hand-rolled snap `ScrollView` plus manual offset math | Testimonial strips, onboarding pages, feature highlights, image galleries; `itemWidth` below 1 is a fraction of the carousel width so the next slide peeks |
 | `Checkbox` | Boolean selection | Custom checkmark controls | Terms consent, checklist items, multi-select filters, notification opt-ins |
 | `Collapsible`, `CollapsibleTrigger`, `CollapsibleContent` | One-off disclosure | Local animated height wrappers | Advanced settings, hidden helper text, optional details |
 | `Dialog`, `AlertDialog` | Modal decisions and custom modal content | Custom modal overlays | Confirm delete, edit profile, invite user, blocking warnings |
@@ -380,6 +384,8 @@ Use `Skeleton` components for loading content with stable dimensions, `EmptyStat
 
 Use `Toggle` for one pressed state, `ToggleGroup` for a related set of pressed states, `Switch` for binary settings, `RadioGroup` for small mutually exclusive choices, and `Select` for longer option sets.
 
+Pass `Avatar` both a `source` and a `name` whenever you have them: `name` supplies the initials shown while the image is missing or after it fails, and the default accessibility label. `SkeletonAvatar` is the loading placeholder, not a substitute. Inside `AvatarGroup`, child avatars inherit the group's `size` and `shape` and gain the ring, so set those on the group rather than per child.
+
 ### Quick Examples
 
 Card, badge, and CTA:

package/dist/components/Avatar.d.ts

@@ -0,0 +1,80 @@
+import React from "react";
+import { type ImageSourcePropType, type StyleProp, type ViewStyle } from "react-native";
+import { type IconName } from "./Icon";
+/** Named size tokens, or an explicit pixel diameter. */
+export type AvatarSize = "sm" | "md" | "lg" | number;
+export type AvatarShape = "circle" | "square";
+/**
+ * Derive 1–2 initials from a display name.
+ *
+ * First + last word (middle names are skipped, as in most avatar stacks), one
+ * initial for a single-word name, and `""` when there is nothing to derive —
+ * callers treat that as "fall through to the icon".
+ *
+ * Grapheme-aware by way of `Array.from`, so an accented character written as
+ * base + combining mark keeps its accent and an astral code point (emoji) is
+ * not sliced into a lone surrogate. `toLocaleUpperCase` is deliberate: a
+ * locale-sensitive uppercase is right for names.
+ */
+export declare function getAvatarInitials(name?: string): string;
+export interface AvatarProps {
+    /** Image to display. Falls back to initials (then the icon) if it fails to load. */
+    source?: ImageSourcePropType;
+    /** Display name; supplies the fallback initials and the default accessibility label. */
+    name?: string;
+    /** Feather icon rendered when there is no image and no derivable initials. @default "user" */
+    icon?: IconName;
+    /** Size token or explicit pixel diameter. Inherited from `AvatarGroup` when unset. @default "md" */
+    size?: AvatarSize;
+    /** Inherited from `AvatarGroup` when unset. @default "circle" */
+    shape?: AvatarShape;
+    /**
+     * Accessibility label. Defaults to `name`; when neither is set the avatar is
+     * decorative and stays out of the accessibility tree.
+     */
+    accessibilityLabel?: string;
+    style?: StyleProp<ViewStyle>;
+}
+/**
+ * Avatar Component
+ *
+ * A circular (or rounded-square) profile image with a graceful fallback chain:
+ * image → initials → icon. A broken or slow-failing image downgrades to
+ * initials at runtime, so a dead URL never leaves an empty hole.
+ *
+ * Usage:
+ * ```tsx
+ * <Avatar source={{ uri: user.avatarUrl }} name={user.fullName} />
+ * <Avatar name="Ada Lovelace" size="lg" />
+ * <Avatar icon="camera" shape="square" />
+ * ```
+ */
+declare function Avatar({ source, name, icon, size, shape, accessibilityLabel, style: styleOverride, }: AvatarProps): React.JSX.Element;
+export interface AvatarGroupProps {
+    children?: React.ReactNode;
+    /** Maximum number of avatars to render; the rest collapse into a `+N` tile. */
+    max?: number;
+    /** Size applied to child avatars that don't set their own. @default "md" */
+    size?: AvatarSize;
+    /** Shape applied to child avatars that don't set their own. @default "circle" */
+    shape?: AvatarShape;
+    /** Defaults to `"<n> avatars"`, counting the collapsed overflow. */
+    accessibilityLabel?: string;
+    style?: StyleProp<ViewStyle>;
+}
+/**
+ * AvatarGroup Component
+ *
+ * Overlapping stack of avatars, each ringed in the theme `background` color so
+ * the stack reads on any surface. Earlier avatars sit on top; anything past
+ * `max` collapses into a `+N` tile.
+ *
+ * Usage:
+ * ```tsx
+ * <AvatarGroup max={3}>
+ *   {members.map((m) => <Avatar key={m.id} source={{ uri: m.avatarUrl }} name={m.name} />)}
+ * </AvatarGroup>
+ * ```
+ */
+declare function AvatarGroup({ children, max, size, shape, accessibilityLabel, style: styleOverride, }: AvatarGroupProps): React.JSX.Element;
+export { Avatar, AvatarGroup };

package/dist/components/Avatar.js

@@ -0,0 +1,234 @@
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import React, { use, useState } from "react";
+import { Image, StyleSheet, View, } from "react-native";
+import { useTheme } from "../hooks/useTheme.js";
+import { spacing } from "../constants/spacing.js";
+import { Icon } from "./Icon.js";
+import { StyledText } from "./StyledText.js";
+import { createThemedStyles } from "../lib/themedStyles.js";
+const SIZE_TOKENS = {
+    sm: spacing.iconLg, // 32
+    md: spacing.iconLg + spacing.sm, // 40
+    lg: spacing.iconXl, // 48
+};
+function isSizeToken(size) {
+    return typeof size === "string";
+}
+function resolveSize(size) {
+    return isSizeToken(size) ? SIZE_TOKENS[size] : size;
+}
+/** Rounded-square radius scales with the avatar so 32px and 88px read the same. */
+function squareRadius(px) {
+    return Math.round(px / 4);
+}
+/** Initials/icon scale with the avatar rather than jumping between text tokens. */
+function contentSize(px) {
+    return { fontSize: Math.round(px * 0.4), iconSize: Math.round(px * 0.5) };
+}
+/** Overlap for stacked avatars — 30% keeps ~70% of each face visible. */
+function overlap(px) {
+    return -Math.round(px * 0.3);
+}
+/**
+ * Derive 1–2 initials from a display name.
+ *
+ * First + last word (middle names are skipped, as in most avatar stacks), one
+ * initial for a single-word name, and `""` when there is nothing to derive —
+ * callers treat that as "fall through to the icon".
+ *
+ * Grapheme-aware by way of `Array.from`, so an accented character written as
+ * base + combining mark keeps its accent and an astral code point (emoji) is
+ * not sliced into a lone surrogate. `toLocaleUpperCase` is deliberate: a
+ * locale-sensitive uppercase is right for names.
+ */
+export function getAvatarInitials(name) {
+    if (!name)
+        return "";
+    const words = name.trim().split(/\s+/).filter(Boolean);
+    if (words.length === 0)
+        return "";
+    const picked = words.length === 1 ? [words[0]] : [words[0], words[words.length - 1]];
+    return picked
+        .map((word) => {
+        const [first] = Array.from(word.normalize("NFC"));
+        return first ?? "";
+    })
+        .join("")
+        .toLocaleUpperCase();
+}
+/**
+ * Identity of an image source by content, not object identity.
+ *
+ * `source={{ uri }}` allocates a new object on every render, so a failure
+ * flag keyed on object identity would reset immediately and loop
+ * image → error → image. Returns `null` when there is no usable image.
+ */
+function getSourceKey(source) {
+    if (source == null)
+        return null;
+    if (typeof source === "number")
+        return `asset:${source}`;
+    if (Array.isArray(source)) {
+        const key = source.map((entry) => entry?.uri ?? "").filter(Boolean).join("|");
+        return key || null;
+    }
+    return source.uri || null;
+}
+const AvatarGroupContext = React.createContext(null);
+/**
+ * Avatar Component
+ *
+ * A circular (or rounded-square) profile image with a graceful fallback chain:
+ * image → initials → icon. A broken or slow-failing image downgrades to
+ * initials at runtime, so a dead URL never leaves an empty hole.
+ *
+ * Usage:
+ * ```tsx
+ * <Avatar source={{ uri: user.avatarUrl }} name={user.fullName} />
+ * <Avatar name="Ada Lovelace" size="lg" />
+ * <Avatar icon="camera" shape="square" />
+ * ```
+ */
+function Avatar({ source, name, icon, size, shape, accessibilityLabel, style: styleOverride, }) {
+    const { theme } = useTheme();
+    const styles = themedStyles(theme);
+    const group = use(AvatarGroupContext);
+    const px = resolveSize(size ?? group?.size ?? "md");
+    const resolvedShape = shape ?? group?.shape ?? "circle";
+    const sourceKey = getSourceKey(source);
+    // Keyed on the source's content, so a retry with a new URL clears the
+    // failure while a re-rendered identical URL keeps it.
+    const [failedKey, setFailedKey] = useState(null);
+    const showImage = sourceKey !== null && failedKey !== sourceKey;
+    const initials = getAvatarInitials(name);
+    const label = accessibilityLabel ?? name;
+    return (_jsx(AvatarSurface, { px: px, shape: resolvedShape, ring: group?.ring ?? false, accessibilityLabel: label, style: [styles.fallback, styleOverride], children: showImage ? (_jsx(Image, { source: source, resizeMode: "cover", style: geometry.image, onError: () => setFailedKey(sourceKey) })) : initials ? (_jsx(AvatarLabel, { px: px, style: styles.fallbackText, children: initials })) : (_jsx(Icon, { name: icon ?? "user", size: contentSize(px).iconSize, color: "mutedForeground", decorative: true })) }));
+}
+/**
+ * Shared chrome for an avatar-shaped tile — used by `Avatar` and by
+ * `AvatarGroup`'s `+N` overflow tile so both stay the same size, shape, and
+ * ring without duplicating the geometry rules.
+ */
+function AvatarSurface({ px, shape, ring, accessibilityLabel, style, children, }) {
+    const { theme } = useTheme();
+    const styles = themedStyles(theme);
+    const token = SIZE_TOKEN_FOR_PX[px];
+    return (_jsx(View
+    // Only join the accessibility tree when there is something to announce;
+    // an unlabeled avatar is decorative next to the name it sits beside.
+    , { 
+        // Only join the accessibility tree when there is something to announce;
+        // an unlabeled avatar is decorative next to the name it sits beside.
+        accessible: accessibilityLabel ? true : undefined, 
+        // RN's role name is "image"; RNW maps it to aria-role "img" on the web.
+        accessibilityRole: accessibilityLabel ? "image" : undefined, accessibilityLabel: accessibilityLabel, style: [
+            geometry.base,
+            // Token sizes hit a pre-registered rule; a custom pixel size falls back
+            // to an inline style (which always ships in the SSR HTML).
+            token
+                ? geometry[shape === "circle" ? `${token}Circle` : `${token}Square`]
+                : { width: px, height: px, borderRadius: shape === "circle" ? spacing.radiusFull : squareRadius(px) },
+            ring && geometry.ring,
+            ring && styles.ring,
+            style,
+        ], children: children }));
+}
+function AvatarLabel({ px, style, children, }) {
+    return (_jsx(StyledText, { accessible: false, selectable: false, fontWeight: "semibold", style: [geometry.labelText, { fontSize: contentSize(px).fontSize }, style], children: children }));
+}
+/**
+ * AvatarGroup Component
+ *
+ * Overlapping stack of avatars, each ringed in the theme `background` color so
+ * the stack reads on any surface. Earlier avatars sit on top; anything past
+ * `max` collapses into a `+N` tile.
+ *
+ * Usage:
+ * ```tsx
+ * <AvatarGroup max={3}>
+ *   {members.map((m) => <Avatar key={m.id} source={{ uri: m.avatarUrl }} name={m.name} />)}
+ * </AvatarGroup>
+ * ```
+ */
+function AvatarGroup({ children, max, size = "md", shape = "circle", accessibilityLabel, style: styleOverride, }) {
+    const { theme } = useTheme();
+    const styles = themedStyles(theme);
+    // toArray drops null/undefined/false children so a conditionally rendered
+    // avatar doesn't inflate the count or the overflow tally.
+    const items = React.Children.toArray(children);
+    const visible = max != null && max >= 0 ? items.slice(0, max) : items;
+    const overflowCount = items.length - visible.length;
+    const px = resolveSize(size);
+    const token = SIZE_TOKEN_FOR_PX[px];
+    const stackStyle = token ? geometry[`${token}Stack`] : { marginLeft: overlap(px) };
+    const totalTiles = visible.length + (overflowCount > 0 ? 1 : 0);
+    const contextValue = React.useMemo(() => ({ size, shape, ring: true }), [size, shape]);
+    return (_jsx(View, { accessible: true, accessibilityRole: "image", accessibilityLabel: accessibilityLabel ?? `${items.length} avatars`, style: [geometry.group, styleOverride], children: _jsxs(AvatarGroupContext.Provider, { value: contextValue, children: [visible.map((child, index) => (_jsx(View
+                // toArray assigns every child a stable key, so reordering the list
+                // moves the wrapper with its avatar instead of remounting both.
+                , { 
+                    // Earlier avatars paint over later ones, so the stack reads
+                    // left-to-right instead of the DOM's later-wins order.
+                    style: [index > 0 && stackStyle, { zIndex: totalTiles - index }], children: child }, React.isValidElement(child) ? child.key : index))), overflowCount > 0 ? (_jsx(View, { style: [visible.length > 0 && stackStyle, { zIndex: 0 }], children: _jsx(AvatarSurface, { px: px, shape: shape, ring: true, style: styles.overflow, children: _jsx(AvatarLabel, { px: px, style: styles.overflowText, children: `+${overflowCount}` }) }) })) : null] }) }));
+}
+/** px → token, so a size passed as a raw number still hits the registered rules. */
+const SIZE_TOKEN_FOR_PX = {
+    [SIZE_TOKENS.sm]: "sm",
+    [SIZE_TOKENS.md]: "md",
+    [SIZE_TOKENS.lg]: "lg",
+};
+// Geometry carries no theme values, so a plain module-scope sheet is enough to
+// get these rules into the server-rendered <head>. Only colors go through
+// createThemedStyles below. See docs/ssr-hydration.md.
+const geometry = StyleSheet.create({
+    base: {
+        alignItems: "center",
+        justifyContent: "center",
+        overflow: "hidden",
+    },
+    image: {
+        width: "100%",
+        height: "100%",
+    },
+    labelText: {
+        // The tile is the touch/visual target; text must not add its own metrics.
+        includeFontPadding: false,
+        textAlign: "center",
+        userSelect: "none",
+    },
+    ring: {
+        borderWidth: spacing.xxs,
+    },
+    group: {
+        flexDirection: "row",
+        alignItems: "center",
+    },
+    smCircle: { width: SIZE_TOKENS.sm, height: SIZE_TOKENS.sm, borderRadius: spacing.radiusFull },
+    mdCircle: { width: SIZE_TOKENS.md, height: SIZE_TOKENS.md, borderRadius: spacing.radiusFull },
+    lgCircle: { width: SIZE_TOKENS.lg, height: SIZE_TOKENS.lg, borderRadius: spacing.radiusFull },
+    smSquare: { width: SIZE_TOKENS.sm, height: SIZE_TOKENS.sm, borderRadius: squareRadius(SIZE_TOKENS.sm) },
+    mdSquare: { width: SIZE_TOKENS.md, height: SIZE_TOKENS.md, borderRadius: squareRadius(SIZE_TOKENS.md) },
+    lgSquare: { width: SIZE_TOKENS.lg, height: SIZE_TOKENS.lg, borderRadius: squareRadius(SIZE_TOKENS.lg) },
+    smStack: { marginLeft: overlap(SIZE_TOKENS.sm) },
+    mdStack: { marginLeft: overlap(SIZE_TOKENS.md) },
+    lgStack: { marginLeft: overlap(SIZE_TOKENS.lg) },
+});
+const createStyles = (theme) => StyleSheet.create({
+    fallback: {
+        backgroundColor: theme.colors.muted,
+    },
+    fallbackText: {
+        color: theme.colors.mutedForeground,
+    },
+    ring: {
+        borderColor: theme.colors.background,
+    },
+    overflow: {
+        backgroundColor: theme.colors.accent,
+    },
+    overflowText: {
+        color: theme.colors.accentForeground,
+    },
+});
+const themedStyles = createThemedStyles(createStyles);
+export { Avatar, AvatarGroup };

package/dist/components/Carousel.d.ts

@@ -0,0 +1,73 @@
+import React from "react";
+import { type StyleProp, type ViewStyle } from "react-native";
+export interface CarouselProps {
+    /** Slides to page through. Each child is wrapped in a fixed-width slide. */
+    children?: React.ReactNode;
+    /**
+     * Slide width. Values `<= 1` are a fraction of the carousel's own width —
+     * the default `0.85` leaves the next slide peeking. Values `> 1` are
+     * absolute pixels.
+     * @default 0.85
+     */
+    itemWidth?: number;
+    /** Space between slides. @default spacing.md */
+    gap?: number;
+    /** Horizontal inset before the first and after the last slide. @default spacing.lg */
+    contentPadding?: number;
+    /** Render the dot indicators. Auto-hidden for a single slide. @default true */
+    showDots?: boolean;
+    /** Slide shown on mount. @default 0 */
+    initialIndex?: number;
+    /** Called with the new active index whenever it changes. */
+    onIndexChange?: (index: number) => void;
+    /** Snap to slide boundaries. @default true */
+    snap?: boolean;
+    /** Custom style override for the outer container. */
+    style?: StyleProp<ViewStyle>;
+    /** Custom style override for the scroll content row. */
+    contentContainerStyle?: StyleProp<ViewStyle>;
+    /**
+     * testID prefix. Emits `<testID>`, `-scroll`, `-item-<i>`, `-dots`,
+     * `-dot-<i>`, and `-status`.
+     * @default "carousel"
+     */
+    testID?: string;
+}
+/**
+ * Active slide index for a horizontal scroll offset.
+ *
+ * `interval` is the slide pitch (item width + gap), so page `i` sits at
+ * `i * interval` for both the native snap offsets and web's CSS scroll-snap
+ * (see `scrollPaddingLeft` below). Clamped to `[0, count - 1]` so rubber-band
+ * overscroll at either end can't report an out-of-range page. Returns `0` for
+ * a degenerate interval — which is also the pre-measurement state on the
+ * server.
+ */
+export declare function getCarouselIndex(offsetX: number, interval: number, count: number): number;
+/** Resolves the `itemWidth` prop against a container width (fraction vs px). */
+export declare function resolveCarouselItemWidth(itemWidth: number, containerWidth: number): number;
+/**
+ * Carousel Component
+ *
+ * Horizontally snapping row of slides with dot indicators and an optional
+ * peek of the next slide. Children-based: every child becomes one slide at the
+ * resolved item width.
+ *
+ * Built on `ScrollView` — not a virtualized list — on purpose: every slide is
+ * in the server-rendered tree, so web SSR ships the real content instead of an
+ * empty scroller that only fills in after measurement. Snapping uses the
+ * platform scroller (`snapToInterval` on native, CSS scroll-snap on web); no
+ * animation library is involved.
+ *
+ * @example
+ * ```tsx
+ * <Carousel itemWidth={0.8} onIndexChange={setPage}>
+ *   {testimonials.map((t) => (
+ *     <Card key={t.name}>
+ *       <BodyText>{t.quote}</BodyText>
+ *     </Card>
+ *   ))}
+ * </Carousel>
+ * ```
+ */
+export declare function Carousel({ children, itemWidth, gap, contentPadding, showDots, initialIndex, onIndexChange, snap, style: styleOverride, contentContainerStyle, testID, }: CarouselProps): React.JSX.Element;

package/dist/components/Carousel.js

@@ -0,0 +1,184 @@
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import React, { useCallback, useEffect, useRef, useState } from "react";
+import { Platform, ScrollView, StyleSheet, Text, View, } from "react-native";
+import { useTheme } from "../hooks/useTheme.js";
+import { useDimensions } from "../hooks/useDimensions.js";
+import { spacing } from "../constants/spacing.js";
+import { createThemedStyles } from "../lib/themedStyles.js";
+// ============================================================================
+// Index math
+// ============================================================================
+/**
+ * Active slide index for a horizontal scroll offset.
+ *
+ * `interval` is the slide pitch (item width + gap), so page `i` sits at
+ * `i * interval` for both the native snap offsets and web's CSS scroll-snap
+ * (see `scrollPaddingLeft` below). Clamped to `[0, count - 1]` so rubber-band
+ * overscroll at either end can't report an out-of-range page. Returns `0` for
+ * a degenerate interval — which is also the pre-measurement state on the
+ * server.
+ */
+export function getCarouselIndex(offsetX, interval, count) {
+    if (!Number.isFinite(offsetX) || !Number.isFinite(interval))
+        return 0;
+    if (interval <= 0 || count <= 0)
+        return 0;
+    const raw = Math.round(offsetX / interval);
+    if (raw < 0)
+        return 0;
+    if (raw > count - 1)
+        return count - 1;
+    return raw;
+}
+/** Resolves the `itemWidth` prop against a container width (fraction vs px). */
+export function resolveCarouselItemWidth(itemWidth, containerWidth) {
+    if (!Number.isFinite(itemWidth) || itemWidth <= 0)
+        return 0;
+    if (itemWidth > 1)
+        return Math.round(itemWidth);
+    if (!Number.isFinite(containerWidth) || containerWidth <= 0)
+        return 0;
+    return Math.round(containerWidth * itemWidth);
+}
+function clampIndex(index, count) {
+    if (count <= 0)
+        return 0;
+    return Math.min(count - 1, Math.max(0, Math.trunc(index)));
+}
+// ============================================================================
+// Carousel
+// ============================================================================
+/**
+ * Carousel Component
+ *
+ * Horizontally snapping row of slides with dot indicators and an optional
+ * peek of the next slide. Children-based: every child becomes one slide at the
+ * resolved item width.
+ *
+ * Built on `ScrollView` — not a virtualized list — on purpose: every slide is
+ * in the server-rendered tree, so web SSR ships the real content instead of an
+ * empty scroller that only fills in after measurement. Snapping uses the
+ * platform scroller (`snapToInterval` on native, CSS scroll-snap on web); no
+ * animation library is involved.
+ *
+ * @example
+ * ```tsx
+ * <Carousel itemWidth={0.8} onIndexChange={setPage}>
+ *   {testimonials.map((t) => (
+ *     <Card key={t.name}>
+ *       <BodyText>{t.quote}</BodyText>
+ *     </Card>
+ *   ))}
+ * </Carousel>
+ * ```
+ */
+export function Carousel({ children, itemWidth = 0.85, gap = spacing.md, contentPadding = spacing.lg, showDots = true, initialIndex = 0, onIndexChange, snap = true, style: styleOverride, contentContainerStyle, testID = "carousel", }) {
+    const { theme } = useTheme();
+    const styles = themedStyles(theme);
+    const items = React.Children.toArray(children);
+    const count = items.length;
+    // Width source of truth: the measured container after mount, seeded from the
+    // viewport so the server and the client's first render agree. `useDimensions`
+    // reads the SSR viewport context rather than `window`, which is what keeps
+    // that seed hydration-safe (docs/ssr-hydration.md §4).
+    const { width: viewportWidth } = useDimensions();
+    const [measuredWidth, setMeasuredWidth] = useState(null);
+    const containerWidth = measuredWidth ?? viewportWidth;
+    const slideWidth = resolveCarouselItemWidth(itemWidth, containerWidth);
+    const interval = slideWidth + gap;
+    const [activeIndex, setActiveIndex] = useState(() => clampIndex(initialIndex, count));
+    // Mirrors activeIndex so the scroll handler can dedupe without re-reading
+    // state: one settle emits many scroll events, onIndexChange must fire once.
+    const activeIndexRef = useRef(activeIndex);
+    const scrollRef = useRef(null);
+    const hasScrolledToInitial = useRef(false);
+    const commitIndex = useCallback((next) => {
+        if (next === activeIndexRef.current)
+            return;
+        activeIndexRef.current = next;
+        setActiveIndex(next);
+        onIndexChange?.(next);
+    }, [onIndexChange]);
+    const handleScroll = useCallback((event) => {
+        commitIndex(getCarouselIndex(event.nativeEvent.contentOffset.x, interval, count));
+    }, [commitIndex, count, interval]);
+    const handleLayout = useCallback((event) => {
+        const next = event.nativeEvent.layout.width;
+        if (!(next > 0))
+            return;
+        setMeasuredWidth((current) => current !== null && Math.abs(current - next) < 1 ? current : next);
+    }, []);
+    // Jump to initialIndex once, after the first real layout — the seeded
+    // viewport width would put the offset in the wrong place. `contentOffset` is
+    // iOS-only, so drive it imperatively for Android/web parity.
+    const targetIndex = clampIndex(initialIndex, count);
+    useEffect(() => {
+        if (hasScrolledToInitial.current || measuredWidth === null || interval <= 0)
+            return;
+        hasScrolledToInitial.current = true;
+        if (targetIndex === 0)
+            return;
+        scrollRef.current?.scrollTo({ x: targetIndex * interval, animated: false });
+    }, [interval, measuredWidth, targetIndex]);
+    const isWeb = Platform.OS === "web";
+    const useCssSnap = isWeb && snap;
+    const dotsVisible = showDots && count > 1;
+    return (_jsxs(View, { style: [styles.container, styleOverride], onLayout: handleLayout, testID: testID, children: [_jsx(ScrollView, { ref: scrollRef, testID: `${testID}-scroll`, horizontal: true, showsHorizontalScrollIndicator: false, 
+                // Native snapping. react-native-web drops these (they aren't in its
+                // forwarded-prop list), so web uses the CSS scroll-snap styles instead.
+                snapToInterval: snap && interval > 0 ? interval : undefined, snapToAlignment: "start", decelerationRate: snap ? "fast" : "normal", 
+                // react-native-web only emits scroll ticks when the throttle is > 0 and
+                // never emits momentum events — this is what keeps the dots live for
+                // wheel/trackpad scrolling.
+                scrollEventThrottle: 16, onScroll: handleScroll, onMomentumScrollEnd: handleScroll, style: useCssSnap
+                    ? [webStyles.scroller, { scrollPaddingLeft: contentPadding }]
+                    : undefined, contentContainerStyle: [{ paddingHorizontal: contentPadding, gap }, contentContainerStyle], children: items.map((child, index) => (_jsx(View, { testID: `${testID}-item-${index}`, style: [slideWidth > 0 && { width: slideWidth }, useCssSnap && webStyles.item], children: child }, React.isValidElement(child) && child.key != null ? child.key : index))) }), count > 1 && (_jsx(View, { testID: `${testID}-status`, style: styles.status, "aria-live": "polite", children: _jsx(Text, { style: styles.statusText, children: `${activeIndex + 1} of ${count}` }) })), dotsVisible && (_jsx(View, { testID: `${testID}-dots`, style: styles.dots, accessibilityRole: "tablist", children: items.map((_, index) => (_jsx(View, { testID: `${testID}-dot-${index}`, accessibilityRole: "tab", accessibilityState: { selected: index === activeIndex }, accessibilityLabel: `Slide ${index + 1} of ${count}`, style: [styles.dot, index === activeIndex ? styles.dotActive : styles.dotInactive] }, index))) }))] }));
+}
+// ============================================================================
+// Styles
+// ============================================================================
+const DOT_SIZE = 8;
+// Web-only CSS scroll-snap. `scrollPaddingLeft` is applied inline at the call
+// site (it tracks the contentPadding prop) so the leading inset survives the
+// browser snapping slide 0 to the scrollport start — which also makes page `i`
+// land on `i * interval`, matching the native snap offsets.
+const webStyles = StyleSheet.create({
+    scroller: { scrollSnapType: "x mandatory" },
+    item: { scrollSnapAlign: "start" },
+});
+const createStyles = (theme) => StyleSheet.create({
+    container: {
+        width: "100%",
+    },
+    // Clipped to 1x1 rather than removed: screen readers skip
+    // display:none/opacity:0 nodes, and there is no visual affordance to show.
+    status: {
+        position: "absolute",
+        width: 1,
+        height: 1,
+        overflow: "hidden",
+    },
+    statusText: {
+        fontSize: 1,
+        color: "transparent",
+    },
+    dots: {
+        flexDirection: "row",
+        alignItems: "center",
+        justifyContent: "center",
+        gap: spacing.xs,
+        marginTop: spacing.md,
+    },
+    dot: {
+        width: DOT_SIZE,
+        height: DOT_SIZE,
+        borderRadius: spacing.radiusFull,
+    },
+    dotActive: {
+        backgroundColor: theme.colors.accent,
+    },
+    dotInactive: {
+        backgroundColor: theme.colors.border,
+    },
+});
+const themedStyles = createThemedStyles(createStyles);

package/dist/components/Drawer.js

@@ -395,7 +395,9 @@ function DrawerOverlayContent({ swipeEnabled = true, swipeThreshold = 0.3, veloc
         bottom: 0,
         width,
         [side]: 0,
-        backgroundColor: theme.colors.background,
+        // App chrome sits on the sunken tier so it reads as a layer beneath the
+        // content pane rather than the same surface.
+        backgroundColor: theme.colors.surfaceSunken,
         borderColor: theme.colors.border,
         ...(side === "left"
             ? { borderRightWidth: 1 }
@@ -502,7 +504,8 @@ swipeEnabled: _swipeEnabled, swipeThreshold: _swipeThreshold, velocityThreshold:
     const panelStyle = {
         width: Platform.OS === "web" ? targetWidth : widthAnim,
         overflow: "hidden",
-        backgroundColor: theme.colors.background,
+        // Rail chrome sits on the sunken tier, one step below the content pane.
+        backgroundColor: theme.colors.surfaceSunken,
         borderColor: theme.colors.border,
         ...(side === "left" ? { borderRightWidth: 1 } : { borderLeftWidth: 1 }),
         paddingTop: insets.top,

package/dist/components/index.d.ts

@@ -1,10 +1,12 @@
 export * from "./Accordion";
 export * from "./Alert";
 export * from "./AnimatedView";
+export * from "./Avatar";
 export * from "./Badge";
 export * from "./BottomSheet";
 export * from "./Button";
 export * from "./Card";
+export * from "./Carousel";
 export * from "./Checkbox";
 export * from "./Collapsible";
 export * from "./Dialog";

package/dist/components/index.js

@@ -1,10 +1,12 @@
 export * from "./Accordion.js";
 export * from "./Alert.js";
 export * from "./AnimatedView.js";
+export * from "./Avatar.js";
 export * from "./Badge.js";
 export * from "./BottomSheet.js";
 export * from "./Button.js";
 export * from "./Card.js";
+export * from "./Carousel.js";
 export * from "./Checkbox.js";
 export * from "./Collapsible.js";
 export * from "./Dialog.js";

package/dist/constants/colors.d.ts

@@ -22,11 +22,13 @@ declare const palette: {
     readonly gray900: "#18181B";
     readonly gray950: "#09090B";
     readonly black: "#000000";
+    readonly dark950: "#050506";
     readonly dark900: "#09090B";
     readonly dark800: "#18181B";
     readonly dark700: "#27272A";
     readonly dark600: "#3F3F46";
     readonly dark400: "#A1A1AA";
+    readonly dark350: "#B0B0B8";
     readonly dark300: "#D4D4D8";
     readonly dark100: "#F4F4F5";
     readonly green500: "#22C55E";
@@ -40,6 +42,7 @@ declare const palette: {
  * Semantic color interface - what colors mean in the UI
  */
 export interface ThemeColors {
+    surfaceSunken: string;
     background: string;
     foreground: string;
     card: string;
@@ -61,6 +64,7 @@ export interface ThemeColors {
     success: string;
     warning: string;
     border: string;
+    borderStrong: string;
     input: string;
     ring: string;
     overlay: string;

package/dist/constants/colors.js

@@ -25,11 +25,15 @@ const palette = {
     gray950: "#09090B",
     black: "#000000",
     // Dark mode surfaces — zinc-based
+    // `dark950` sits below zinc-950 as the app-chrome tier; `dark350` is a
+    // zinc-350 midpoint used for dim text that stays comfortably readable.
+    dark950: "#050506",
     dark900: "#09090B",
     dark800: "#18181B",
     dark700: "#27272A",
     dark600: "#3F3F46",
     dark400: "#A1A1AA",
+    dark350: "#B0B0B8",
     dark300: "#D4D4D8",
     dark100: "#F4F4F5",
     // Status
@@ -44,6 +48,7 @@ const lightTheme = {
     dark: false,
     fonts: navigationFonts,
     colors: {
+        surfaceSunken: palette.gray50,
         background: palette.white,
         foreground: palette.gray950,
         card: palette.white,
@@ -51,13 +56,13 @@ const lightTheme = {
         popover: palette.white,
         popoverForeground: palette.gray950,
         text: palette.gray950,
-        textDim: palette.gray500,
+        textDim: palette.gray600,
         primary: palette.gray900,
         primaryForeground: palette.gray50,
         secondary: palette.gray100,
         secondaryForeground: palette.gray900,
         muted: palette.gray100,
-        mutedForeground: palette.gray500,
+        mutedForeground: palette.gray600,
         accent: palette.teal500,
         accentForeground: palette.white,
         destructive: palette.red500,
@@ -65,6 +70,7 @@ const lightTheme = {
         success: palette.green500,
         warning: palette.amber500,
         border: palette.gray200,
+        borderStrong: palette.gray300,
         input: palette.gray200,
         ring: palette.gray400,
         overlay: "rgba(0, 0, 0, 0.5)",
@@ -82,6 +88,7 @@ const darkTheme = {
     dark: true,
     fonts: navigationFonts,
     colors: {
+        surfaceSunken: palette.dark950,
         background: palette.dark900,
         foreground: palette.dark100,
         card: palette.dark800,
@@ -89,13 +96,13 @@ const darkTheme = {
         popover: palette.dark800,
         popoverForeground: palette.dark100,
         text: palette.dark100,
-        textDim: palette.dark400,
+        textDim: palette.dark350,
         primary: palette.gray50,
         primaryForeground: palette.gray900,
         secondary: palette.gray800,
         secondaryForeground: palette.gray50,
         muted: palette.dark700,
-        mutedForeground: palette.dark400,
+        mutedForeground: palette.dark350,
         accent: palette.teal400,
         accentForeground: palette.gray900,
         destructive: palette.red400,
@@ -103,6 +110,7 @@ const darkTheme = {
         success: palette.green400,
         warning: palette.amber400,
         border: palette.dark700,
+        borderStrong: palette.dark600,
         input: palette.dark700,
         ring: palette.dark400,
         overlay: "rgba(0, 0, 0, 0.7)",

package/dist/hooks/useTheme.js

@@ -3,6 +3,7 @@ import { colors } from "../constants/colors.js";
 import { Platform, StyleSheet } from "react-native";
 import { resolveThemePreference, useThemeStore } from "../state/themeStore.js";
 import { useThemeColorScope } from "../state/themeColorScope.js";
+import { useSsrThemeSeed } from "../state/ssrTheme.js";
 import { spacing as spacingConstants } from "../constants/spacing.js";
 // Module-level cache for contrast calculations to avoid memory leak
 // and share across components
@@ -45,11 +46,24 @@ function getCachedOrCompute(key, compute) {
  * - getShadowStyle('base') → { boxShadow: "0px 2px 6px rgba(0, 0, 0, 0.05), 0px 4px 12px rgba(0, 0, 0, 0.03)" }
  */
 export function useTheme() {
-    const userTheme = useThemeStore((s) => s.userTheme);
-    const systemTheme = useThemeStore((s) => s.systemTheme);
+    const storeUserTheme = useThemeStore((s) => s.userTheme);
+    const storeSystemTheme = useThemeStore((s) => s.systemTheme);
+    const hasLoadedTheme = useThemeStore((s) => s.hasLoadedTheme);
     const setTheme = useThemeStore((s) => s.setTheme);
     const colorOverrides = useThemeStore((s) => s.colorOverrides);
     const scoped = useThemeColorScope();
+    const seed = useSsrThemeSeed();
+    // Before persistence has been read, a web render must resolve from the
+    // per-request SSR seed instead of store state. The store is a module
+    // singleton shared across concurrent SSR requests, so it can only ever hold
+    // the SSR-safe boot defaults ("system"/light); the seed is cookie-derived,
+    // which is the one signal the server and the browser read identically —
+    // that's what keeps the hydrated tree matching the server HTML. After mount
+    // `syncThemeFromEnvironment()` flips `hasLoadedTheme` and store state (real
+    // localStorage/AsyncStorage + live OS listener) takes over for good.
+    const useSeed = Platform.OS === "web" && !hasLoadedTheme;
+    const userTheme = useSeed ? seed.userTheme : storeUserTheme;
+    const systemTheme = useSeed ? seed.systemTheme : storeSystemTheme;
     // Determine which theme to use (user preference or system)
     const effectiveScheme = resolveThemePreference(userTheme, systemTheme);
     const base = colors[effectiveScheme];

package/dist/state/index.d.ts

@@ -2,4 +2,5 @@ export * from "./globalUIStore";
 export * from "./notify";
 export * from "./themeStore";
 export * from "./themeColorScope";
+export * from "./ssrTheme";
 export * from "./SsrViewportContext";

package/dist/state/index.js

@@ -2,4 +2,5 @@ export * from "./globalUIStore.js";
 export * from "./notify.js";
 export * from "./themeStore.js";
 export * from "./themeColorScope.js";
+export * from "./ssrTheme.js";
 export * from "./SsrViewportContext.js";

package/dist/state/ssrTheme.d.ts

@@ -0,0 +1,41 @@
+import type { ResolvedTheme, ThemePreference } from "./themeStore";
+/**
+ * The theme values the FIRST render must use on web — server and client alike.
+ *
+ * `useThemeStore` is a module singleton shared by every concurrent SSR request,
+ * so a per-request theme can never be written into it. This context is the
+ * per-request channel instead: the host app resolves it from the request (a
+ * cookie the client mirrors) and provides it above the tree, and `useTheme`
+ * reads it until the store has loaded real persistence after mount.
+ */
+export type SsrThemeSeed = {
+    userTheme: ThemePreference;
+    systemTheme: ResolvedTheme;
+};
+/**
+ * What a first-time visitor gets: no persisted preference, light scheme. Same
+ * values the store boots with, so a host app that never provides the context
+ * behaves exactly as it did before the seed existed.
+ */
+export declare const SSR_THEME_SEED_DEFAULT: SsrThemeSeed;
+/**
+ * Per-request theme seed consumed by `useTheme`/`useStyles` while
+ * `hasLoadedTheme` is false (i.e. on the server render and the client's first
+ * render, before `syncThemeFromEnvironment()` reads real persistence).
+ *
+ * Provide it near the top of the tree from a value BOTH the server and the
+ * browser can derive from the same bytes — a cookie. Reading `localStorage`
+ * for this would reintroduce the hydration mismatch it exists to remove,
+ * because the server cannot see `localStorage`.
+ *
+ * ```tsx
+ * import { SsrThemeSeedContext } from "@mrmeg/expo-ui/state";
+ *
+ * <SsrThemeSeedContext.Provider value={seedFromCookie}>
+ *   <App />
+ * </SsrThemeSeedContext.Provider>
+ * ```
+ */
+export declare const SsrThemeSeedContext: import("react").Context<SsrThemeSeed>;
+/** Read the active SSR theme seed (the default when no provider is mounted). */
+export declare function useSsrThemeSeed(): SsrThemeSeed;

package/dist/state/ssrTheme.js

@@ -0,0 +1,33 @@
+import { createContext, use } from "react";
+/**
+ * What a first-time visitor gets: no persisted preference, light scheme. Same
+ * values the store boots with, so a host app that never provides the context
+ * behaves exactly as it did before the seed existed.
+ */
+export const SSR_THEME_SEED_DEFAULT = {
+    userTheme: "system",
+    systemTheme: "light",
+};
+/**
+ * Per-request theme seed consumed by `useTheme`/`useStyles` while
+ * `hasLoadedTheme` is false (i.e. on the server render and the client's first
+ * render, before `syncThemeFromEnvironment()` reads real persistence).
+ *
+ * Provide it near the top of the tree from a value BOTH the server and the
+ * browser can derive from the same bytes — a cookie. Reading `localStorage`
+ * for this would reintroduce the hydration mismatch it exists to remove,
+ * because the server cannot see `localStorage`.
+ *
+ * ```tsx
+ * import { SsrThemeSeedContext } from "@mrmeg/expo-ui/state";
+ *
+ * <SsrThemeSeedContext.Provider value={seedFromCookie}>
+ *   <App />
+ * </SsrThemeSeedContext.Provider>
+ * ```
+ */
+export const SsrThemeSeedContext = createContext(SSR_THEME_SEED_DEFAULT);
+/** Read the active SSR theme seed (the default when no provider is mounted). */
+export function useSsrThemeSeed() {
+    return use(SsrThemeSeedContext);
+}

package/dist/state/themeStore.d.ts

@@ -2,6 +2,16 @@ import type { ThemeColors } from "../constants/colors";
 import type { FontOverrides } from "../constants/fonts";
 export type ThemePreference = "system" | "light" | "dark";
 export type ResolvedTheme = "light" | "dark";
+/**
+ * Cookie name the web build mirrors the persisted preference into, so a
+ * server-rendered host can seed its first render with the visitor's real
+ * theme instead of shipping a light tree that recolors after hydration.
+ *
+ * Same name as the `localStorage` key on purpose: one string to grep, and the
+ * blocking color-scheme script in a host's `+html.tsx` already reads it.
+ * `localStorage` stays the source of truth; the cookie is a render hint only.
+ */
+export declare const THEME_COOKIE_NAME = "user-theme-preference";
 /**
  * Per-scheme color overrides a host app can inject to brand the package.
  *
@@ -44,6 +54,15 @@ export type ShapeOverrides = {
 export type ThemeStore = {
     userTheme: ThemePreference;
     systemTheme: ResolvedTheme;
+    /**
+     * True once the persisted preference has actually been read (or explicitly
+     * set by the user). Until then, a web render must not trust `userTheme` /
+     * `systemTheme` — they still hold the SSR-safe boot defaults, and `useTheme`
+     * uses `SsrThemeSeedContext` (cookie-derived, identical on server and
+     * client) instead. Mirrors `hasLoadedOnboarding` in the host app's
+     * onboarding store.
+     */
+    hasLoadedTheme: boolean;
     /**
      * App-injected palette overrides, applied by `useTheme` on top of the
      * package defaults. Empty by default — zero override means the package

package/dist/state/themeStore.js

@@ -2,6 +2,26 @@ import { Appearance, Platform } from "react-native";
 import { create } from "zustand";
 import AsyncStorage from "@react-native-async-storage/async-storage";
 const THEME_KEY = "user-theme-preference";
+/**
+ * Cookie name the web build mirrors the persisted preference into, so a
+ * server-rendered host can seed its first render with the visitor's real
+ * theme instead of shipping a light tree that recolors after hydration.
+ *
+ * Same name as the `localStorage` key on purpose: one string to grep, and the
+ * blocking color-scheme script in a host's `+html.tsx` already reads it.
+ * `localStorage` stays the source of truth; the cookie is a render hint only.
+ */
+export const THEME_COOKIE_NAME = THEME_KEY;
+const THEME_COOKIE_MAX_AGE = 60 * 60 * 24 * 365; // 1 year
+function isThemePreference(value) {
+    return value === "system" || value === "light" || value === "dark";
+}
+function writeThemeCookie(theme) {
+    if (Platform.OS !== "web" || typeof document === "undefined")
+        return;
+    document.cookie =
+        `${THEME_COOKIE_NAME}=${theme}; path=/; max-age=${THEME_COOKIE_MAX_AGE}; SameSite=Lax`;
+}
 export function resolveThemePreference(userTheme, systemTheme) {
     return userTheme === "system" ? systemTheme : userTheme;
 }
@@ -14,8 +34,13 @@ function getSystemTheme() {
 export const useThemeStore = create((set) => ({
     userTheme: "system",
     // Always start with "light" so SSR and the first client render agree.
-    // Real values are populated by `syncThemeFromEnvironment()` after mount.
+    // Real values are populated by `syncThemeFromEnvironment()` after mount;
+    // until then a web render reads `SsrThemeSeedContext` (cookie-derived) so
+    // the server and the browser paint the visitor's actual theme.
     systemTheme: "light",
+    // False until persistence has been read. `useTheme` uses this to decide
+    // whether to trust store state or the per-request SSR seed.
+    hasLoadedTheme: false,
     // No overrides by default: the package renders with its built-in palette
     // until a host app calls `setColors`.
     colorOverrides: {},
@@ -36,6 +61,7 @@ export const useThemeStore = create((set) => ({
     setTheme: (theme) => {
         set({
             userTheme: theme,
+            hasLoadedTheme: true,
             ...(theme === "system" ? { systemTheme: getSystemTheme() } : {}),
         });
         // Save directly when setting theme
@@ -43,10 +69,14 @@ export const useThemeStore = create((set) => ({
             AsyncStorage.setItem(THEME_KEY, theme).catch(() => {
                 // Silently fail if storage is not available
             });
+            return;
         }
-        else if (typeof window !== "undefined" && window.localStorage) {
+        if (typeof window !== "undefined" && window.localStorage) {
             localStorage.setItem(THEME_KEY, theme);
         }
+        // Dual-write: localStorage for the client, cookie for the next SSR render
+        // (so the server paints the right theme on the visitor's next request).
+        writeThemeCookie(theme);
     },
     setSystemTheme: (theme) => {
         set({ systemTheme: theme });
@@ -54,19 +84,32 @@ export const useThemeStore = create((set) => ({
     loadTheme: () => {
         if (Platform.OS !== "web") {
             AsyncStorage.getItem(THEME_KEY).then((saved) => {
-                if (saved && (saved === "system" || saved === "light" || saved === "dark")) {
+                if (saved && isThemePreference(saved)) {
                     set({ userTheme: saved });
                 }
             }).catch(() => {
                 // Use default if loading fails
+            }).finally(() => {
+                set({ hasLoadedTheme: true });
             });
+            return;
         }
-        else if (typeof window !== "undefined" && window.localStorage) {
+        if (typeof window !== "undefined" && window.localStorage) {
             const saved = localStorage.getItem(THEME_KEY);
-            if (saved && (saved === "system" || saved === "light" || saved === "dark")) {
+            if (saved && isThemePreference(saved)) {
                 set({ userTheme: saved });
+                // Backfill / repair the cookie so a visitor who set their preference
+                // before this mechanism existed (or who cleared cookies) gets a
+                // correctly themed server render on their very next request.
+                writeThemeCookie(saved);
+            }
+            else {
+                // Nothing persisted: mirror the implicit "system" default so the
+                // server stops guessing from a stale cookie.
+                writeThemeCookie("system");
             }
         }
+        set({ hasLoadedTheme: true });
     }
 }));
 let stopSystemThemeListener = null;
@@ -112,9 +155,15 @@ export function startSystemThemeListener() {
 // environment (persisted preference + OS color scheme listener). Safe to
 // call multiple times — `startSystemThemeListener` is idempotent — and
 // returns the unsubscribe so it can be used directly inside `useEffect`.
+//
+// The listener starts BEFORE `loadTheme()` on purpose: `loadTheme` is what
+// flips `hasLoadedTheme`, which is the moment web renders stop trusting the
+// SSR seed and start trusting store state. Reading the real OS scheme first
+// means a `system` user never sees a frame of the boot-default "light".
 export function syncThemeFromEnvironment() {
+    const stop = startSystemThemeListener();
     useThemeStore.getState().loadTheme();
-    return startSystemThemeListener();
+    return stop;
 }
 // Native has no SSR mismatch concern, so keep the historical auto-init
 // behavior there. On web the host app must call `syncThemeFromEnvironment()`

package/llms-full.md

@@ -51,9 +51,14 @@ package `tx` props translated by its app-owned i18n instance.
 ## Theme Rules
 
 Use `useTheme()` and `useStyles()` from `@mrmeg/expo-ui/hooks`. Use semantic
-tokens such as `background`, `foreground`, `card`, `popover`, `border`,
-`input`, `ring`, `primary`, `secondary`, `accent`, `mutedForeground`,
-`destructive`, `success`, and `warning`.
+tokens such as `surfaceSunken`, `background`, `foreground`, `card`, `popover`,
+`border`, `borderStrong`, `input`, `ring`, `primary`, `secondary`, `accent`,
+`mutedForeground`, `destructive`, `success`, and `warning`.
+
+Surfaces form a tier ladder rather than a shadow scale: `surfaceSunken` (app
+chrome such as the Drawer rail) < `background` (content) < `card`/`popover`
+(raised) < `muted` (chips, insets). Use `borderStrong` for hairlines on filled
+or raised elements, where `border` would blend into the fill.
 
 Use `StyledText` and semantic text aliases instead of raw `Text` for app UI.
 Use package controls instead of hardcoded Pressable/View/Text combinations.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mrmeg/expo-ui",
-  "version": "0.18.0",
+  "version": "0.20.0",
   "private": false,
   "description": "Reusable Expo and React Native UI primitives for MrMeg projects.",
   "keywords": [