diff --git a/web/src/lib/components/repo/StarButton.stories.svelte b/web/src/lib/components/repo/StarButton.stories.svelte
new file mode 100644
index 000000000..75e244297
--- /dev/null
+++ b/web/src/lib/components/repo/StarButton.stories.svelte
@@ -0,0 +1,138 @@
+<script module lang="ts">
+	import { defineMeta, type StoryContext } from "@storybook/addon-svelte-csf";
+	import { expect, screen, userEvent, waitFor } from "storybook/test";
+	import StarButton from "./StarButton.svelte";
+
+	// the toggle (create/delete) goes through the mock agent's handler, so a story
+	// that needs a successful toggle passes `respond` on the auth parameter.
+	const respond = (pathname: string): Response => {
+		if (pathname.includes("createRecord")) {
+			return Response.json({
+				uri: "at://did:plc:alice/sh.tangled.feed.star/3lknew",
+				cid: "bafyreibfko5xzzdptcimcaql4tmsaffgr6jhreyjz3tv6nlh34si6k4u7e"
+			});
+		}
+		if (pathname.includes("deleteRecord")) {
+			return Response.json({});
+		}
+		return new Response(null, { status: 404 });
+	};
+
+	// a never-settling respond keeps the toggle in its loading state so the
+	// spinner swap can be asserted
+	const hang = () => new Promise<Response>(() => {});
+
+	type PlayContext = Pick<StoryContext<Record<string, unknown>>, "canvas">;
+
+	const args = {
+		repoDid: "did:plc:repo",
+		repoOwnerHandle: "dawn",
+		repoName: "tangled",
+		initialCount: 128
+	};
+
+	const notStarred = async ({ canvas }: PlayContext) => {
+		const button = await canvas.findByRole("button", { name: "Star" });
+		await waitFor(() => expect(button).toBeEnabled());
+	};
+
+	const starred = async ({ canvas }: PlayContext) => {
+		const button = await canvas.findByRole("button", { name: "Starred" });
+		await waitFor(() => expect(button).toBeEnabled());
+	};
+
+	// clicking star: the icon swaps to a spinner while the write is in flight,
+	// then settles on "Starred" with the filled star icon
+	const starring = async ({ canvas }: PlayContext) => {
+		const button = await canvas.findByRole("button", { name: "Star" });
+		await userEvent.click(button);
+		await waitFor(() => expect(canvas.getByRole("button", { name: "Starred" })).toBeVisible());
+	};
+
+	// a hung write: the button stays on "Star" with the icon replaced by a spinner
+	const starringLoading = async ({ canvas }: PlayContext) => {
+		const button = await canvas.findByRole("button", { name: "Star" });
+		await userEvent.click(button);
+		await waitFor(() => expect(button).toHaveAttribute("aria-busy", "true"));
+		await expect(button).toHaveTextContent("Star");
+		await expect(button).toBeDisabled();
+	};
+
+	const unstarring = async ({ canvas }: PlayContext) => {
+		const button = await canvas.findByRole("button", { name: "Starred" });
+		await userEvent.click(button);
+		await waitFor(() => expect(canvas.getByRole("button", { name: "Star" })).toBeVisible());
+	};
+
+	// the toggle failed: the button turns red with a triangle-alert icon, and
+	// hovering shows the error in a tooltip. the error clears itself after 2s.
+	const toggleError = async ({ canvas }: PlayContext) => {
+		const button = await canvas.findByRole("button", { name: "Star" });
+		await waitFor(() => expect(button).toBeEnabled());
+		await userEvent.click(button);
+		await waitFor(() =>
+			expect(canvas.getByRole("button", { name: "Star" })).toHaveAttribute(
+				"data-variant",
+				"danger"
+			)
+		);
+		await userEvent.hover(button);
+		await waitFor(() =>
+			expect(screen.getByRole("tooltip")).toHaveTextContent("Something went wrong")
+		);
+		await waitFor(
+			() =>
+				expect(canvas.getByRole("button", { name: "Star" })).not.toHaveAttribute(
+					"data-variant",
+					"danger"
+				),
+			{ timeout: 3000 }
+		);
+		await waitFor(() => expect(canvas.queryByRole("tooltip")).toBeNull());
+	};
+
+	const signedOutStars = async ({ canvas }: PlayContext) => {
+		const [star] = await canvas.findAllByRole("link", { name: "Star" });
+		expect(star.getAttribute("href")).toContain("/login");
+	};
+
+	const { Story } = defineMeta({
+		title: "Repo/StarButton",
+		component: StarButton,
+		tags: ["autodocs"],
+		args
+	});
+</script>
+
+<Story name="Not starred" asChild play={notStarred} parameters={{ auth: true }}>
+	<StarButton {...args} initialRkey={null} />
+</Story>
+
+<Story name="Starred" asChild play={starred} parameters={{ auth: true }}>
+	<StarButton {...args} initialRkey="3jzstar" />
+</Story>
+
+<Story name="Starring" asChild play={starring} parameters={{ auth: { respond } }}>
+	<StarButton {...args} initialRkey={null} />
+</Story>
+
+<Story
+	name="Starring (loading)"
+	asChild
+	play={starringLoading}
+	parameters={{ auth: { respond: hang } }}
+>
+	<StarButton {...args} initialRkey={null} />
+</Story>
+
+<Story name="Unstarring" asChild play={unstarring} parameters={{ auth: { respond } }}>
+	<StarButton {...args} initialRkey="3jzstar" />
+</Story>
+
+<Story name="Toggle error" asChild play={toggleError} parameters={{ auth: true }}>
+	<StarButton {...args} initialRkey={null} />
+</Story>
+
+<Story name="Signed out" asChild play={signedOutStars} parameters={{ auth: false }}>
+	<StarButton {...args} initialRkey={null} />
+</Story>
diff --git a/web/src/lib/components/repo/StarButton.svelte b/web/src/lib/components/repo/StarButton.svelte
index 4637000bf..215d6ca78 100644
--- a/web/src/lib/components/repo/StarButton.svelte
+++ b/web/src/lib/components/repo/StarButton.svelte
@@ -2,11 +2,14 @@
 	import { resolve } from "$app/paths";
 	import { page } from "$app/state";
 	import Star from "$icon/star";
+	import TriangleAlert from "$icon/triangle-alert";
 	import { getAuth } from "$lib/auth.svelte";
 	import { loginWithReturn } from "$lib/auth/guards";
 	import { createStar, deleteStar } from "$lib/api/graph";
 	import Button from "$lib/components/ui/Button.svelte";
 	import ButtonGroup from "$lib/components/ui/ButtonGroup.svelte";
+	import Spinner from "$lib/components/ui/Spinner.svelte";
+	import Tooltip from "$lib/components/ui/Tooltip.svelte";
 	import { getProfileCounts } from "$lib/components/profile/counts.svelte";
 	import { createOptimisticRelation, createOptimisticCount } from "$lib/optimistic.svelte";
 	import { formatCount } from "$lib/format";
@@ -83,6 +86,14 @@
 	});
 	const starred = $derived(relation.active);
 	const failed = $derived(relation.failed || starCount.failed);
+	$effect(() => {
+		if (!failed) return;
+		const timer = setTimeout(() => {
+			relation.resetFailure();
+			starCount.resetFailure();
+		}, 2000);
+		return () => clearTimeout(timer);
+	});
 	// if signed out, sends you to log in first, then back here
 	const loginHref = $derived(
 		resolve(loginWithReturn(page.url.pathname + page.url.search) as "/login")
@@ -122,34 +133,40 @@
 </script>
 
 <div class="flex flex-1 flex-col items-start">
-	<ButtonGroup class="w-full">
-		<Button
-			variant="default"
-			size="small"
-			{insetShadow}
-			href={signedIn ? undefined : loginHref}
-			loading={relation.loading}
-			disabled={signedIn && (!relation.known || !repoDid)}
-			onclick={signedIn ? toggle : undefined}
-			class="flex-1"
-		>
-			<Star
-				class={`size-4 shrink-0 ${starred ? "[&_path]:fill-[currentColor]" : ""}`}
-				aria-hidden="true"
-			/>
-			<span>{starred ? "Unstar" : "Star"}</span>
-		</Button>
-		<Button href={starsHref} variant="ghost" size="small" title="Starred by">
-			{#if loadedCount === undefined}
-				<Bones capture={uiLoadingprimitivesCount} class="inline-block w-8 align-middle" />
-			{:else}
-				{formatCount(starCount.value)}
-			{/if}
-		</Button>
-	</ButtonGroup>
-	{#if failed}
-		<p class="mt-1 typography-paragraph-small text-foreground-danger">
-			Something went wrong. Try again.
-		</p>
-	{/if}
+	<Tooltip content="Something went wrong. Try again." disabled={!failed} class="w-full">
+		<ButtonGroup class="w-full">
+			<Button
+				variant={failed ? "danger" : "default"}
+				size="small"
+				{insetShadow}
+				href={signedIn ? undefined : loginHref}
+				disabled={signedIn && (!relation.known || !repoDid || relation.loading)}
+				aria-busy={relation.loading}
+				onclick={signedIn ? toggle : undefined}
+				class="flex-1"
+			>
+				{#if relation.loading}
+					<Spinner class="size-4 shrink-0" />
+				{:else if failed}
+					<TriangleAlert class="size-4 shrink-0" aria-hidden="true" />
+				{:else}
+					<Star
+						class={`size-4 shrink-0 ${starred ? "[&_path]:fill-[currentColor]" : ""}`}
+						aria-hidden="true"
+					/>
+				{/if}
+				<span>{starred ? "Starred" : "Star"}</span>
+			</Button>
+			<Button href={starsHref} variant="ghost" size="small" title="Starred by">
+				{#if loadedCount === undefined}
+					<Bones
+						capture={uiLoadingprimitivesCount}
+						class="inline-block w-8 align-middle"
+					/>
+				{:else}
+					{formatCount(starCount.value)}
+				{/if}
+			</Button>
+		</ButtonGroup>
+	</Tooltip>
 </div>