@multiplatform.one/components 6.7.0 → 7.1.0

package/src/AnimateHeight/AnimateHeight.spec.tsx

@@ -0,0 +1,152 @@
+import { renderWithProviders } from "@multiplatform.one/test-utils";
+import { act, fireEvent } from "@testing-library/react";
+import { useState } from "react";
+import { Text } from "tamagui";
+import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
+import { AnimateHeight } from "./index";
+
+/**
+ * The shared test setup ships a ResizeObserver mock that never fires, so by
+ * default AnimateHeight has no measurement and takes its instant paths (the
+ * semantics the Accordion specs rely on). Tests that need the animated paths
+ * install this controllable observer plus a fixed getBoundingClientRect.
+ */
+class FiringResizeObserver {
+  static instances: FiringResizeObserver[] = [];
+  callback: ResizeObserverCallback;
+  constructor(callback: ResizeObserverCallback) {
+    this.callback = callback;
+    FiringResizeObserver.instances.push(this);
+  }
+  observe() {
+    // real observers fire an initial measurement on observe
+    this.callback([], this as unknown as ResizeObserver);
+  }
+  unobserve() {}
+  disconnect() {}
+}
+
+function Harness({ initialOpen }: { initialOpen: boolean }) {
+  const [open, setOpen] = useState(initialOpen);
+  return (
+    <>
+      <button data-testid="toggle" type="button" onClick={() => setOpen((v) => !v)}>
+        toggle
+      </button>
+      <AnimateHeight open={open} testID="animate-height-outer">
+        <Text>Collapsible body</Text>
+      </AnimateHeight>
+    </>
+  );
+}
+
+const originalResizeObserver = window.ResizeObserver;
+
+function installFiringObserver(height: number) {
+  FiringResizeObserver.instances = [];
+  window.ResizeObserver = FiringResizeObserver as unknown as typeof ResizeObserver;
+  vi.spyOn(Element.prototype, "getBoundingClientRect").mockReturnValue({
+    height,
+    width: 260,
+    x: 0,
+    y: 0,
+    top: 0,
+    left: 0,
+    right: 260,
+    bottom: height,
+    toJSON: () => ({}),
+  } as DOMRect);
+}
+
+describe("AnimateHeight", () => {
+  beforeEach(() => {
+    vi.useFakeTimers();
+  });
+
+  afterEach(() => {
+    vi.useRealTimers();
+    vi.restoreAllMocks();
+    window.ResizeObserver = originalResizeObserver;
+  });
+
+  it("follower mode always renders children", () => {
+    const result = renderWithProviders(
+      <AnimateHeight>
+        <Text>Follower body</Text>
+      </AnimateHeight>,
+    );
+    expect(result.container.textContent).toContain("Follower body");
+  });
+
+  it("collapsible closed at rest renders no children", () => {
+    const result = renderWithProviders(<Harness initialOpen={false} />);
+    expect(result.container.textContent).not.toContain("Collapsible body");
+  });
+
+  it("mounts children in the same commit open flips true", () => {
+    const result = renderWithProviders(<Harness initialOpen={false} />);
+    fireEvent.click(result.getByTestId("toggle"));
+    expect(result.container.textContent).toContain("Collapsible body");
+  });
+
+  it("closing without a measurement unmounts synchronously", () => {
+    // default never-firing observer mock: nothing can tween
+    const result = renderWithProviders(<Harness initialOpen={true} />);
+    expect(result.container.textContent).toContain("Collapsible body");
+    fireEvent.click(result.getByTestId("toggle"));
+    expect(result.container.textContent).not.toContain("Collapsible body");
+  });
+
+  it("closing with a real measurement keeps children through the exit tween, then unmounts", () => {
+    installFiringObserver(120);
+    const result = renderWithProviders(<Harness initialOpen={true} />);
+    expect(result.container.textContent).toContain("Collapsible body");
+
+    fireEvent.click(result.getByTestId("toggle"));
+    // exit tween in flight — children must stay mounted
+    expect(result.container.textContent).toContain("Collapsible body");
+
+    // knob default transition is "quick" — settle table 450ms + buffer
+    act(() => {
+      vi.advanceTimersByTime(600);
+    });
+    expect(result.container.textContent).not.toContain("Collapsible body");
+  });
+
+  it("expanding from closed tweens 0 → measured height", () => {
+    installFiringObserver(120);
+    const result = renderWithProviders(<Harness initialOpen={false} />);
+    fireEvent.click(result.getByTestId("toggle"));
+    // double rAF lands the measured target (fake timers tick rAF at 16ms)
+    act(() => {
+      vi.advanceTimersByTime(50);
+    });
+    act(() => {
+      vi.advanceTimersByTime(50);
+    });
+    const region = result.container.querySelector('[data-testid="animate-height-outer"]');
+    // outer carries the measured numeric height once the target lands —
+    // tamagui emits it as an atomic height class in this environment
+    expect((region as HTMLElement | null)?.className).toContain("_h-120px");
+  });
+
+  it("reduced motion unmounts immediately on close even with a measurement", () => {
+    installFiringObserver(120);
+    vi.spyOn(window, "matchMedia").mockImplementation(
+      (query: string) =>
+        ({
+          matches: query.includes("prefers-reduced-motion"),
+          media: query,
+          onchange: null,
+          addEventListener: () => {},
+          removeEventListener: () => {},
+          addListener: () => {},
+          removeListener: () => {},
+          dispatchEvent: () => false,
+        }) as unknown as MediaQueryList,
+    );
+    const result = renderWithProviders(<Harness initialOpen={true} />);
+    fireEvent.click(result.getByTestId("toggle"));
+    expect(result.container.textContent).not.toContain("Collapsible body");
+  });
+});

package/src/AnimateHeight/index.tsx

@@ -0,0 +1,237 @@
+import { isWeb } from "@multiplatform.one/platform";
+import { useResolvedKnobs } from "@multiplatform.one/theme";
+import type { ReactNode } from "react";
+import { forwardRef, useCallback, useEffect, useLayoutEffect, useRef, useState } from "react";
+import type { LayoutChangeEvent } from "react-native";
+// tamagui 2.0.0-rc dropped the StackProps alias; YStackProps is the same shape.
+import type { TamaguiElement, TransitionProp, YStackProps as StackProps } from "tamagui";
+import { View } from "tamagui";
+
+/**
+ * AnimateHeight — the house auto-height primitive.
+ *
+ * CSS cannot transition to `height: auto` — intrinsic (content-driven) height
+ * changes snap no matter what `transition` is set, because height never
+ * appears as an interpolable value. This container measures its content
+ * (ResizeObserver on web, onLayout on native) and drives a NUMERIC `height`
+ * through the house `transition` token. The web css driver tweens it; the RN
+ * driver applies layout props directly (Axiom 4 native constraint), so native
+ * lands correct heights without a decorative tween — no worse than before,
+ * while mount/unmount sequencing still works on both platforms.
+ *
+ * Two modes:
+ *  - follower (no `open` prop): always mounted; height tracks the content's
+ *    intrinsic height, so content that grows or shrinks while visible tweens
+ *    instead of snapping.
+ *  - collapsible (`open: boolean`): `false` tweens to 0 and unmounts children
+ *    once the collapse settles (immediately when nothing can tween, e.g.
+ *    reduced motion or no measurement yet); `true` remounts children and
+ *    tweens 0 → measured height, then keeps following content changes.
+ *
+ * Reduced motion is respected CONDITIONALLY: the transition resolves through
+ * the knob system (`useResolvedKnobs`), which is `undefined` under OS
+ * `prefers-reduced-motion` or `animation="none"` — heights then apply
+ * instantly, with no decorative tween, but state changes still land.
+ *
+ * Padding belongs INSIDE children (or on a wrapper around this component):
+ * the measured box is the children's wrapper, so padding on AnimateHeight
+ * itself would be excluded from the animated height.
+ */
+export interface AnimateHeightProps extends Omit<StackProps, "height" | "children"> {
+  /**
+   * Collapsible mode. Omit entirely for follower mode (height always tracks
+   * content). `false` collapses to 0 and unmounts children at rest.
+   */
+  open?: boolean;
+  children?: ReactNode;
+}
+
+/**
+ * Conservative settle time (ms) per house transition token, for unmounting
+ * after the collapse tween. Keep in sync with the token vocabulary in
+ * public/theme/src/theme/animations (css timings AND spring physics): values
+ * cover the native spring tails, which outlast the fixed css durations — on
+ * web the box is already clipped to 0 by then, so the later unmount is
+ * invisible.
+ */
+const settleTable: Record<string, number> = {
+  snappy: 300,
+  quick: 450,
+  bouncy: 800,
+  medium: 600,
+  tooltip: 700,
+  gentle: 900,
+  slow: 1100,
+  lazy: 1300,
+};
+
+/**
+ * Settle time before finalizing (unmounting / releasing a clamp) — token
+ * settle + buffer. Exported for siblings that sequence work after a height
+ * tween (e.g. CodeBlock's reveal releases its maxHeight clamp on settle).
+ */
+export function settleMs(transition: TransitionProp | undefined): number {
+  if (!transition) return 0;
+  const ms = typeof transition === "string" ? settleTable[transition] : undefined;
+  // Non-string TransitionProp shapes (arrays/objects) fall back like an
+  // unknown token name.
+  return (ms ?? 600) + 80;
+}
+
+export const AnimateHeight = forwardRef<TamaguiElement, AnimateHeightProps>(
+  function AnimateHeight({ open, children, transition: transitionProp, ...props }, ref) {
+    const { knobProps } = useResolvedKnobs();
+    // knob transition is undefined under reduced motion / animation="none"
+    const transition = transitionProp ?? knobProps.transition;
+    const collapsible = open !== undefined;
+
+    // null = natural (auto) height: initial open/follower render before the
+    // first measurement, so there is never a flash of collapsed content.
+    const [displayHeight, setDisplayHeight] = useState<number | null>(
+      collapsible && !open ? 0 : null,
+    );
+    // Children stay mounted through the exit tween, then unmount at rest.
+    const [exiting, setExiting] = useState(false);
+    const [prevOpen, setPrevOpen] = useState(open);
+
+    const measuredRef = useRef<number | null>(null);
+    // Set on closed → open: hold height 0 until the first measurement so the
+    // expand tweens 0 → px instead of snapping to auto.
+    const openingRef = useRef(false);
+    const unmountTimerRef = useRef<ReturnType<typeof setTimeout> | null>(null);
+    const rafRef = useRef<number | null>(null);
+    const innerRef = useRef<TamaguiElement | null>(null);
+
+    // Adjust state during render (React's usePrevious pattern) so children
+    // mount in the SAME commit `open` flips true, and stay mounted for the
+    // exit tween when it flips false.
+    if (collapsible && open !== prevOpen) {
+      setPrevOpen(open);
+      if (open) {
+        // Hold at 0 until measurement only when children were unmounted (at
+        // rest). Re-opening mid-exit keeps the existing measurement — the
+        // observer will not re-fire for unchanged content — so the effect
+        // below retargets it directly and the tween reverses in place.
+        openingRef.current = !exiting;
+        if (exiting) setExiting(false);
+      } else {
+        openingRef.current = false;
+        setExiting(true);
+      }
+    }
+
+    const shouldRenderChildren = !collapsible || open || exiting;
+    const atRestClosed = collapsible && !open && !exiting;
+
+    const clearPending = useCallback(() => {
+      if (unmountTimerRef.current != null) {
+        clearTimeout(unmountTimerRef.current);
+        unmountTimerRef.current = null;
+      }
+      if (rafRef.current != null && typeof cancelAnimationFrame === "function") {
+        cancelAnimationFrame(rafRef.current);
+        rafRef.current = null;
+      }
+    }, []);
+
+    const handleMeasured = useCallback(
+      (height: number) => {
+        measuredRef.current = height;
+        // Closing (or closed): the target stays 0 — ignore content measures.
+        if (collapsible && !open) return;
+        if (openingRef.current) {
+          openingRef.current = false;
+          // Double rAF: guarantee the browser paints the height-0 frame
+          // before the target lands, or the 0 → px tween never runs.
+          rafRef.current = requestAnimationFrame(() => {
+            rafRef.current = requestAnimationFrame(() => {
+              rafRef.current = null;
+              setDisplayHeight(height);
+            });
+          });
+          return;
+        }
+        setDisplayHeight(height);
+      },
+      [collapsible, open],
+    );
+    const handleMeasuredRef = useRef(handleMeasured);
+    handleMeasuredRef.current = handleMeasured;
+    const transitionRef = useRef(transition);
+    transitionRef.current = transition;
+
+    // Web: ResizeObserver on the content wrapper — fires on observe (initial
+    // measure) and on any intrinsic size change while mounted.
+    useLayoutEffect(() => {
+      if (!isWeb || !shouldRenderChildren) return;
+      const node = innerRef.current as unknown as HTMLElement | null;
+      if (!node || typeof ResizeObserver === "undefined") return;
+      const observer = new ResizeObserver(() => {
+        // getBoundingClientRect keeps fractional text heights exact.
+        handleMeasuredRef.current(node.getBoundingClientRect().height);
+      });
+      observer.observe(node);
+      return () => observer.disconnect();
+    }, [shouldRenderChildren]);
+
+    // Native: onLayout on the content wrapper is the measurement source.
+    const onInnerLayout = useCallback((event: LayoutChangeEvent) => {
+      handleMeasuredRef.current(event.nativeEvent.layout.height);
+    }, []);
+
+    // Drive the open/close targets after commit.
+    useEffect(() => {
+      if (!collapsible) return;
+      clearPending();
+      if (open) {
+        // Opening from closed holds 0 until measurement (openingRef); if a
+        // measurement already exists (close interrupted mid-tween), retarget
+        // it immediately so the tween reverses from wherever it is.
+        if (!openingRef.current && measuredRef.current != null) {
+          setDisplayHeight(measuredRef.current);
+        }
+        return;
+      }
+      // Closing: tween px → 0, then unmount at rest. When nothing can tween
+      // (no transition token — reduced motion — or no real measurement, as in
+      // non-layout test environments), finalize immediately. The transition is
+      // read through a ref at close time only — mid-tween knob changes should
+      // not restart the exit timer.
+      setDisplayHeight(0);
+      const closeTransition = transitionRef.current;
+      const canTween = Boolean(closeTransition) && (measuredRef.current ?? 0) > 0;
+      if (canTween) {
+        unmountTimerRef.current = setTimeout(() => {
+          unmountTimerRef.current = null;
+          setExiting(false);
+        }, settleMs(closeTransition));
+      } else {
+        setExiting(false);
+      }
+    }, [collapsible, open, clearPending]);
+
+    useEffect(() => clearPending, [clearPending]);
+
+    return (
+      <View
+        ref={ref}
+        overflow="hidden"
+        {...(displayHeight != null ? { height: displayHeight } : {})}
+        {...(atRestClosed ? { display: "none" as const } : {})}
+        {...(transition ? { transition } : {})}
+        {...props}
+      >
+        {shouldRenderChildren ? (
+          <View
+            ref={innerRef}
+            // keep natural height inside the clipped, height-driven outer
+            flexShrink={0}
+            {...(!isWeb ? { onLayout: onInnerLayout } : {})}
+          >
+            {children}
+          </View>
+        ) : null}
+      </View>
+    );
+  },
+);

package/src/Avatar/Avatar.spec.tsx

@@ -1,6 +1,7 @@
 import { renderWithProviders } from "@multiplatform.one/test-utils";
-import { describe, expect, it } from "vitest";
-import { Avatar, getInitials } from "./index";
+import { fireEvent } from "@testing-library/react";
+import { describe, expect, it, vi } from "vitest";
+import { Avatar, fallbackTone, fallbackToneIndex, getInitials } from "./index";
 
 describe("getInitials", () => {
   it("takes first letters of two words", () => {
@@ -20,7 +21,21 @@ describe("getInitials", () => {
   });
 });
 
+describe("fallbackTone", () => {
+  it("is stable for the same seed", () => {
+    expect(fallbackToneIndex("Ada Lovelace")).toBe(fallbackToneIndex("Ada Lovelace"));
+    expect(fallbackTone("Ada Lovelace")).toEqual(fallbackTone("Ada Lovelace"));
+  });
+
+  it("diverges for different names", () => {
+    expect(fallbackTone("Ada Lovelace")?.bg).not.toBe(fallbackTone("Grace Hopper")?.bg);
+  });
+});
+
 describe("Avatar", () => {
+  const pxOf = (container: HTMLElement) =>
+    Number(container.querySelector("[data-avatar-px]")?.getAttribute("data-avatar-px"));
+
   it("renders initials from name", () => {
     const { container } = renderWithProviders(<Avatar name="Ada Lovelace" />);
     expect(container.textContent).toContain("AL");
@@ -42,6 +57,62 @@ describe("Avatar", () => {
     );
     expect(container.textContent).toContain("OK");
   });
+
+  it("keeps size, density, and nested on separate channels", () => {
+    const page = renderWithProviders(<Avatar name="Ada Lovelace" />);
+    const nested = renderWithProviders(<Avatar name="Ada Lovelace" nested />);
+    const compact = renderWithProviders(<Avatar name="Ada Lovelace" compact />);
+    expect(pxOf(page.container)).toBe(36);
+    expect(pxOf(nested.container)).toBe(32);
+    expect(pxOf(compact.container)).toBe(28);
+    expect(
+      nested.container.querySelector("[data-avatar-nested]")?.getAttribute("data-avatar-nested"),
+    ).toBe("true");
+  });
+
+  it("lets an explicit size token eject the recipe", () => {
+    const { container } = renderWithProviders(<Avatar name="Ada Lovelace" size="$5" />);
+    expect(pxOf(container)).toBe(52);
+  });
+
+  it("restores the 44px floor with hitSlop when painted below it", () => {
+    const onPress = vi.fn();
+    const { container } = renderWithProviders(
+      <Avatar name="Ada Lovelace" nested onPress={onPress} />,
+    );
+    const el = container.querySelector("[data-avatar-interactive]");
+    expect(el?.getAttribute("data-avatar-px")).toBe("32");
+    expect(el?.getAttribute("data-avatar-hitslop")).toBe("6");
+    fireEvent.click(el as Element);
+    expect(onPress).toHaveBeenCalledTimes(1);
+  });
+});
+
+describe("Avatar.Group", () => {
+  it("overflows extras as +N (Primer stack cap)", () => {
+    const { container } = renderWithProviders(
+      <Avatar.Group max={2}>
+        <Avatar name="Ada Lovelace" />
+        <Avatar name="Grace Hopper" />
+        <Avatar name="Alan Turing" />
+      </Avatar.Group>,
+    );
+    expect(container.textContent).toContain("+1");
+    expect(container.querySelector("[data-avatar-group]")).toBeTruthy();
+    expect(
+      container.querySelector("[data-avatar-overlap]")?.getAttribute("data-avatar-overlap"),
+    ).toBe("true");
+  });
+
+  it("flush square stacks declare no identity circle", () => {
+    const { container } = renderWithProviders(
+      <Avatar.Group circular={false} overlap={false}>
+        <Avatar name="Core Team" />
+        <Avatar name="Ops Bot" />
+      </Avatar.Group>,
+    );
+    expect(container.querySelector("[data-radius-class='R-IDENTITY']")).toBeNull();
+  });
 });
 
 // D-09 / LC-60: Avatar is the spec's declared R-IDENTITY part. Knob immunity

package/src/Avatar/Avatar.stories.tsx

@@ -10,7 +10,7 @@ const meta: Meta<typeof Avatar> = {
     docs: {
       description: {
         component:
-          "Themed Avatar for assigned users, comments, and activity feeds. Image with initials fallback; size variants; compound Avatar.Image / Avatar.Fallback still available.",
+          "Themed Avatar for assigned users, comments, and activity feeds. Image with initials fallback; size recipe (density ≠ size, nested scales down); compound Avatar.Image / Avatar.Fallback / Avatar.Group.",
       },
     },
   },
@@ -19,17 +19,74 @@ const meta: Meta<typeof Avatar> = {
     src: { control: "text" },
     size: { control: "text" },
     circular: { control: "boolean" },
+    nested: { control: "boolean" },
+    compact: { control: "boolean" },
+    status: { control: "select", options: ["online", "busy", "away", "offline"] },
   },
 };
 export default meta;
 
 type Story = StoryObj<typeof Avatar>;
 
+const Caption = ({ children }: { children: string }) => (
+  <SizableText size="$1" color="$color11">
+    {children}
+  </SizableText>
+);
+
 export const Default: Story = {
   name: "Main",
-  args: {
-    name: "Ada Lovelace",
-  },
+  render: () => (
+    <YStack gap="$4" padding="$4">
+      <XStack gap="$3" alignItems="center">
+        <Avatar name="Ada Lovelace" />
+        <Avatar name="Grace Hopper" />
+        <Avatar name="Alan Turing" />
+        <Avatar name="Katherine Johnson" />
+        <Avatar name="Linus Torvalds" />
+        <Avatar />
+      </XStack>
+      <XStack gap="$3" alignItems="flex-end">
+        {(["$1.5", "$2", "$3", "$4", "$6"] as const).map((size) => (
+          <YStack key={size} alignItems="center" gap="$1">
+            <Avatar name="Ada Lovelace" size={size} />
+            <Caption>{size}</Caption>
+          </YStack>
+        ))}
+      </XStack>
+      <XStack gap="$4" alignItems="flex-end">
+        <YStack alignItems="center" gap="$1">
+          <Avatar name="Ada Lovelace" />
+          <Caption>page</Caption>
+        </YStack>
+        <YStack alignItems="center" gap="$1">
+          <Avatar name="Ada Lovelace" nested />
+          <Caption>nested</Caption>
+        </YStack>
+        <YStack alignItems="center" gap="$1">
+          <Avatar name="Ada Lovelace" compact />
+          <Caption>compact</Caption>
+        </YStack>
+        <Avatar name="Ada Lovelace" status="online" />
+        <Avatar name="Grace Hopper" status="busy" />
+        <Avatar circular={false} name="Bitspur Labs" />
+      </XStack>
+      <XStack gap="$4" alignItems="center">
+        <Avatar.Group>
+          <Avatar name="Ada Lovelace" />
+          <Avatar name="Grace Hopper" />
+          <Avatar name="Alan Turing" />
+          <Avatar name="Katherine Johnson" />
+          <Avatar name="Linus Torvalds" />
+        </Avatar.Group>
+        <Avatar.Group circular={false} overlap={false}>
+          <Avatar name="Core Team" />
+          <Avatar name="Ops Bot" />
+          <Avatar name="Docs Org" />
+        </Avatar.Group>
+      </XStack>
+    </YStack>
+  ),
 };
 
 export const WithImage: Story = {
@@ -37,6 +94,7 @@ export const WithImage: Story = {
     name: "Grace Hopper",
     src: "https://images.unsplash.com/photo-1494790108377-be9c29b29330?w=150&h=150&dpr=2&q=80",
     size: "$5",
+    status: "online",
   },
 };
 
@@ -66,6 +124,50 @@ export const InitialsFallback: Story = {
   ),
 };
 
+export const Nested: Story = {
+  render: () => (
+    <XStack gap="$4" alignItems="flex-end">
+      <YStack alignItems="center" gap="$1">
+        <Avatar name="Ada Lovelace" />
+        <SizableText size="$1" color="$color11">
+          page
+        </SizableText>
+      </YStack>
+      <YStack alignItems="center" gap="$1">
+        <Avatar name="Ada Lovelace" nested />
+        <SizableText size="$1" color="$color11">
+          nested
+        </SizableText>
+      </YStack>
+      <YStack alignItems="center" gap="$1">
+        <Avatar name="Ada Lovelace" compact />
+        <SizableText size="$1" color="$color11">
+          compact
+        </SizableText>
+      </YStack>
+    </XStack>
+  ),
+};
+
+export const Group: Story = {
+  render: () => (
+    <YStack gap="$4">
+      <Avatar.Group>
+        <Avatar name="Ada Lovelace" />
+        <Avatar name="Grace Hopper" />
+        <Avatar name="Alan Turing" />
+        <Avatar name="Katherine Johnson" />
+        <Avatar name="Linus Torvalds" />
+      </Avatar.Group>
+      <Avatar.Group circular={false} overlap={false}>
+        <Avatar name="Core Team" />
+        <Avatar name="Ops Bot" />
+        <Avatar name="Docs Org" />
+      </Avatar.Group>
+    </YStack>
+  ),
+};
+
 export const Compound: Story = {
   render: () => (
     <Avatar circular size="$5" backgroundColor="$blue4">

package/src/Avatar/getInitials.ts

@@ -13,3 +13,32 @@ export function getInitials(name: string): string {
   }
   return trimmed.substring(0, 2).toUpperCase();
 }
+
+/**
+ * Polaris-style deterministic initials fill. Tokens only — the same seed
+ * always lands on the same ramp pair so two "AB" avatars match.
+ */
+export const FALLBACK_TONES = [
+  { bg: "$blue4", fg: "$blue12" },
+  { bg: "$green4", fg: "$green12" },
+  { bg: "$orange4", fg: "$orange12" },
+  { bg: "$purple4", fg: "$purple12" },
+  { bg: "$yellow4", fg: "$yellow12" },
+  { bg: "$red4", fg: "$red12" },
+] as const;
+
+export type FallbackTone = (typeof FALLBACK_TONES)[number];
+
+export function fallbackToneIndex(seed: string): number {
+  let hash = 0;
+  for (let i = 0; i < seed.length; i++) {
+    hash = (Math.imul(hash, 31) + seed.charCodeAt(i)) | 0;
+  }
+  return Math.abs(hash) % FALLBACK_TONES.length;
+}
+
+export function fallbackTone(seed: string | undefined): FallbackTone | undefined {
+  const trimmed = (seed ?? "").trim();
+  if (!trimmed) return undefined;
+  return FALLBACK_TONES[fallbackToneIndex(trimmed)];
+}