diff --git a/web/src/lib/avatar.ts b/web/src/lib/avatar.ts
index 0350e8e6..8259d7ce 100644
--- a/web/src/lib/avatar.ts
+++ b/web/src/lib/avatar.ts
@@ -1,4 +1,4 @@
 // the service wants signed urls and the secret is server side, so this points
 // at the route that signs
-export const avatarUrl = (did: string, tiny = false): string =>
-	`/avatar/${encodeURIComponent(did)}${tiny ? "?size=tiny" : ""}`;
+export const avatarUrl = (did: string, width?: number): string =>
+	`/avatar/${encodeURIComponent(did)}${width ? `?size=${width}` : ""}`;
diff --git a/web/src/lib/components/comment/Comment.svelte b/web/src/lib/components/comment/Comment.svelte
index 8fd23d87..2550dd39 100644
--- a/web/src/lib/components/comment/Comment.svelte
+++ b/web/src/lib/components/comment/Comment.svelte
@@ -45,7 +45,7 @@
 		class={`flex gap-2 ${variant === "top" ? "border-b border-border-default bg-background-default px-6 py-4" : "py-4 pr-4"}`}
 	>
 		<div class="shrink-0">
-			<Avatar did={authorDid} handle={authorHandle} size="size-8" tiny />
+			<Avatar did={authorDid} handle={authorHandle} size="large" />
 		</div>
 		<div class="min-w-0 flex-1">
 			<div class="flex flex-wrap items-center gap-1 typography-paragraph-small text-foreground-subtle">
diff --git a/web/src/lib/components/comment/CommentBox.svelte b/web/src/lib/components/comment/CommentBox.svelte
index 01e10f42..48a2e62e 100644
--- a/web/src/lib/components/comment/CommentBox.svelte
+++ b/web/src/lib/components/comment/CommentBox.svelte
@@ -64,7 +64,7 @@
 	<!-- two-column, mirroring Comment: avatar left, handle + editor right -->
 	<div class="flex gap-2 bg-background-default/50 px-6 py-3">
 		<div class="shrink-0">
-			<Avatar did={authorDid} handle={authorHandle} size="size-8" tiny />
+			<Avatar did={authorDid} handle={authorHandle} size="large" />
 		</div>
 		<div class="flex min-w-0 flex-1 flex-col gap-2">
 			<div class="flex flex-wrap items-center gap-1 typography-paragraph-small text-foreground-subtle">
diff --git a/web/src/lib/components/profile/FollowCardContent.svelte b/web/src/lib/components/profile/FollowCardContent.svelte
index 2a4959b6..4e39ed3d 100644
--- a/web/src/lib/components/profile/FollowCardContent.svelte
+++ b/web/src/lib/components/profile/FollowCardContent.svelte
@@ -19,7 +19,7 @@
 <div class="flex flex-col gap-4 md:flex-row md:items-center md:justify-between">
 	<div class="flex min-w-0 flex-1 items-center gap-4">
 		<div class="flex size-24 shrink-0 items-center justify-center">
-			<Avatar did={person.did} handle={person.handle} size="size-24" class="p-2" />
+			<Avatar did={person.did} handle={person.handle} size="full" class="p-2" />
 		</div>
 
 		<div class="flex min-w-0 flex-1 flex-col justify-around">
diff --git a/web/src/lib/components/profile/ProfileCard.svelte b/web/src/lib/components/profile/ProfileCard.svelte
index 2ae561f6..ff4cd27a 100644
--- a/web/src/lib/components/profile/ProfileCard.svelte
+++ b/web/src/lib/components/profile/ProfileCard.svelte
@@ -40,12 +40,7 @@
 <div class="grid grid-cols-3 items-center gap-1 md:grid-cols-1">
 	<div class="col-span-1 flex items-center justify-center">
 		<div class="relative aspect-square w-3/4">
-			<Avatar
-				did={identity.did}
-				handle={identity.handle}
-				size="h-full w-full"
-				class="absolute inset-0"
-			/>
+			<Avatar did={identity.did} handle={identity.handle} size="full" class="absolute inset-0" />
 		</div>
 	</div>
 
diff --git a/web/src/lib/components/repo/CommitHeader.svelte b/web/src/lib/components/repo/CommitHeader.svelte
index b4d6c391..742ecab3 100644
--- a/web/src/lib/components/repo/CommitHeader.svelte
+++ b/web/src/lib/components/repo/CommitHeader.svelte
@@ -42,7 +42,7 @@
 			<span class="w-24 text-foreground-subtle select-none">{label}</span>
 			<!-- no email -> did mapping here, always the fallback form -->
 			<span class="flex items-center gap-1">
-				<Avatar size="size-6" />
+				<Avatar size="large" />
 				{#if email}
 					<a href="mailto:{email}" class="no-underline hover:underline">{name}</a>
 				{:else}
diff --git a/web/src/lib/components/repo/CommitLogView.svelte b/web/src/lib/components/repo/CommitLogView.svelte
index d07df54f..a38d1f63 100644
--- a/web/src/lib/components/repo/CommitLogView.svelte
+++ b/web/src/lib/components/repo/CommitLogView.svelte
@@ -42,7 +42,7 @@
 {#snippet authorCell(commit: CommitSummary)}
 	<span class="flex items-center gap-1">
 		<!-- no did/handle on a commit summary, always the placeholder -->
-		<Avatar size="size-6" />
+		<Avatar size="large" />
 		{#if commit.authorEmail}
 			<a href="mailto:{commit.authorEmail}" class="no-underline hover:underline">
 				{commit.authorName}
diff --git a/web/src/lib/components/repo/LastCommitPanel.svelte b/web/src/lib/components/repo/LastCommitPanel.svelte
index 7eb6c664..7864729a 100644
--- a/web/src/lib/components/repo/LastCommitPanel.svelte
+++ b/web/src/lib/components/repo/LastCommitPanel.svelte
@@ -21,7 +21,7 @@
 	<div class="flex min-w-0 flex-wrap items-center gap-2">
 		{#if commit.authorName}
 		    <!-- no email→did mapping yet, always the placeholder -->
-			<Avatar size="size-5" />
+			<Avatar size="regular" />
 			<span class="truncate text-foreground-default">{commit.authorName}</span>
 			<span class="text-foreground-subtle" aria-hidden="true">&middot;</span>
 		{/if}
diff --git a/web/src/lib/components/repo/RepoHeader.svelte b/web/src/lib/components/repo/RepoHeader.svelte
index 4b56f499..0288d885 100644
--- a/web/src/lib/components/repo/RepoHeader.svelte
+++ b/web/src/lib/components/repo/RepoHeader.svelte
@@ -74,7 +74,7 @@
 					href={resolve(`/${repo.ownerHandle}` as "/")}
 					class="flex items-center gap-2 text-foreground-default no-underline hover:underline"
 				>
-					<Avatar did={repo.ownerDid} handle={repo.ownerHandle} size="size-6" tiny />
+					<Avatar did={repo.ownerDid} handle={repo.ownerHandle} size="large" />
 					{repo.ownerHandle}
 				</a>
 				<span class="text-foreground-subtle select-none">/</span>
diff --git a/web/src/lib/components/settings/tabs/ProfileTab.svelte b/web/src/lib/components/settings/tabs/ProfileTab.svelte
index 91c2c50d..eb061d95 100644
--- a/web/src/lib/components/settings/tabs/ProfileTab.svelte
+++ b/web/src/lib/components/settings/tabs/ProfileTab.svelte
@@ -60,7 +60,7 @@
 <div class="flex w-full flex-col gap-10">
 	<SettingsSection>
 		<div class="flex w-full flex-col items-center gap-2 pb-4">
-			<Avatar did={user?.did} handle={user?.handle} size="size-[158px]" />
+			<Avatar did={user?.did} handle={user?.handle} size="full" class="size-39.5" />
 			<Button icon={Pencil} href="/settings/profile/avatar">Edit</Button>
 		</div>
 		<SettingsRow title="Bio" stack>
diff --git a/web/src/lib/components/ui/Avatar.stories.svelte b/web/src/lib/components/ui/Avatar.stories.svelte
index ce91be3b..6e91e897 100644
--- a/web/src/lib/components/ui/Avatar.stories.svelte
+++ b/web/src/lib/components/ui/Avatar.stories.svelte
@@ -1,6 +1,9 @@
 <script module lang="ts">
 	import { defineMeta } from "@storybook/addon-svelte-csf";
-	import Avatar from "./Avatar.svelte";
+	import Avatar, { avatarSizeNames } from "./Avatar.svelte";
+
+	// `full` takes its size from the layout, so it has nothing to show in a ramp
+	const scale = avatarSizeNames.filter((size) => size !== "full");
 
 	const { Story } = defineMeta({
 		title: "UI/Avatar",
@@ -10,8 +13,7 @@
 			did: { control: "text" },
 			src: { control: "text" },
 			handle: { control: "text" },
-			tiny: { control: "boolean" },
-			size: { control: "text" }
+			size: { control: "select", options: avatarSizeNames }
 		},
 		args: {
 			handle: "user.tld"
@@ -25,9 +27,12 @@
 <Story name="Broken image" args={{ src: "https://example.invalid/broken.png" }} />
 
 <Story name="Sizes" asChild>
-	<div class="flex items-center gap-3">
-		<Avatar handle="user.tld" size="size-6" />
-		<Avatar handle="user.tld" size="size-10" />
-		<Avatar handle="user.tld" size="size-16" />
+	<div class="flex items-end gap-3">
+		{#each scale as size (size)}
+			<div class="flex flex-col items-center gap-1">
+				<Avatar handle="user.tld" {size} />
+				<span class="typography-paragraph-mini text-foreground-muted">{size}</span>
+			</div>
+		{/each}
 	</div>
 </Story>
diff --git a/web/src/lib/components/ui/Avatar.svelte b/web/src/lib/components/ui/Avatar.svelte
index 028e01da..43077c79 100644
--- a/web/src/lib/components/ui/Avatar.svelte
+++ b/web/src/lib/components/ui/Avatar.svelte
@@ -1,3 +1,45 @@
+<script module lang="ts">
+	import { tv, type VariantProps } from "tailwind-variants";
+
+	// the sizes the design system names, from Figma's User component (node 723:254).
+	// Size=Header is not a rung here: it draws the same 26px circle as Size=Large
+	// and differs only in the text style beside it.
+	export const avatar = tv({
+		base: "shrink-0 rounded-full border border-border-default",
+		variants: {
+			size: {
+				mini: "size-3.25",
+				small: "size-4.25",
+				regular: "size-5.25",
+				large: "size-6.5",
+				// for a size off the scale: `full` fills the parent, and a size class
+				// passed by the caller replaces it, since tv() merges the two rather
+				// than leaving both to fight in the class string
+				full: "size-full"
+			}
+		},
+		defaultVariants: {
+			size: "regular"
+		}
+	});
+
+	export type AvatarSize = NonNullable<VariantProps<typeof avatar>["size"]>;
+
+	// what each rung above renders at, in css pixels — the spacing unit is 4px, so
+	// these are the class numbers times four. the avatar is fetched at twice this so
+	// that it stays sharp at 2x. `full` has no size of its own, the layout decides
+	// it, so there is nothing to fetch at.
+	const sizePx = {
+		mini: 13,
+		small: 17,
+		regular: 21,
+		large: 26,
+		full: undefined
+	} satisfies Record<AvatarSize, number | undefined>;
+
+	export const avatarSizeNames = Object.keys(sizePx) as AvatarSize[];
+</script>
+
 <script lang="ts">
 	import UserRound from "$icon/user-round";
 	import { avatarUrl } from "$lib/avatar";
@@ -6,14 +48,16 @@
 		did?: string;
 		src?: string;
 		handle?: string;
-		tiny?: boolean;
-		size?: string;
+		size?: AvatarSize;
 		class?: string;
 	}
 
-	let { did, src, handle, tiny = false, size = "size-10", class: className = "" }: Props = $props();
+	let { did, src, handle, size = "regular", class: className = "" }: Props = $props();
 
-	const source = $derived(src ?? (did ? avatarUrl(did, tiny) : undefined));
+	const px = $derived(sizePx[size]);
+	const source = $derived(
+		src ?? (did ? avatarUrl(did, px === undefined ? undefined : px * 2) : undefined)
+	);
 
 	// an unconfigured avatar service 404s, same as a broken image
 	let failed = $state(false);
@@ -27,12 +71,15 @@
 	<img
 		src={source}
 		alt={handle ? `${handle}'s avatar` : "avatar"}
-		class={`${size} shrink-0 rounded-full border border-border-default object-cover ${className}`}
+		class={avatar({ size, class: `object-cover ${className}` })}
 		onerror={() => (failed = true)}
 	/>
 {:else}
 	<span
-		class={`${size} flex shrink-0 items-center justify-center rounded-full border border-border-default bg-background-inset text-foreground-default ${className}`}
+		class={avatar({
+			size,
+			class: `flex items-center justify-center bg-background-inset text-foreground-default ${className}`
+		})}
 		role={handle ? "img" : undefined}
 		aria-label={handle ? `${handle}'s avatar` : undefined}
 		aria-hidden={handle ? undefined : "true"}
diff --git a/web/src/lib/components/ui/User.svelte b/web/src/lib/components/ui/User.svelte
index 0c064230..aff642f6 100644
--- a/web/src/lib/components/ui/User.svelte
+++ b/web/src/lib/components/ui/User.svelte
@@ -1,37 +1,32 @@
 <script module lang="ts">
 	import { tv, type VariantProps } from "tailwind-variants";
+	import type { AvatarSize } from "./Avatar.svelte";
 
 	export const user = tv({
 		slots: {
 			root: "inline-flex items-center",
-			avatar: "",
 			handle: "truncate"
 		},
 		variants: {
 			size: {
 				header: {
 					root: "gap-2",
-					avatar: "size-6.5",
 					handle: "typography-heading-4"
 				},
 				large: {
 					root: "gap-1.5",
-					avatar: "size-6.5",
 					handle: "typography-paragraph-large"
 				},
 				regular: {
 					root: "gap-1",
-					avatar: "size-5.25",
 					handle: "typography-paragraph-regular"
 				},
 				small: {
 					root: "gap-1",
-					avatar: "size-4.25",
 					handle: "typography-paragraph-small"
 				},
 				mini: {
 					root: "gap-1",
-					avatar: "size-3.25",
 					handle: "typography-paragraph-mini"
 				}
 			}
@@ -42,6 +37,17 @@
 	});
 
 	export type UserVariants = VariantProps<typeof user>;
+
+	// the avatar names its own size rather than taking a class through a slot, so
+	// that it can pick the image width it needs. header and large share a rung
+	// because in Figma they differ only in the text style beside the circle.
+	const avatarSize = {
+		header: "large",
+		large: "large",
+		regular: "regular",
+		small: "small",
+		mini: "mini"
+	} satisfies Record<NonNullable<UserVariants["size"]>, AvatarSize>;
 </script>
 
 <script lang="ts">
@@ -74,8 +80,7 @@
 
 <span class={slots.root({ class: className })}>
 	{#if showImage}
-		<!-- every variant here is size-8 or under, so the small image always fits -->
-		<Avatar {did} {handle} size={slots.avatar({ class: avatarClass })} tiny />
+		<Avatar {did} {handle} size={avatarSize[size]} class={avatarClass} />
 	{/if}
 	{#if showText && handle}
 		<span class={slots.handle({ class: handleClass })}>{handle}</span>
diff --git a/web/src/routes/[handle]/[repo]/settings/access/+page.svelte b/web/src/routes/[handle]/[repo]/settings/access/+page.svelte
index ecf8612e..a962be40 100644
--- a/web/src/routes/[handle]/[repo]/settings/access/+page.svelte
+++ b/web/src/routes/[handle]/[repo]/settings/access/+page.svelte
@@ -51,7 +51,7 @@
 			<SettingsRow stack>
 				{#snippet label()}
 					<span class="flex min-w-0 items-center gap-2">
-						<Avatar did={person.did} handle={person.handle} size="size-5" />
+						<Avatar did={person.did} handle={person.handle} size="regular" />
 						<span class="typography-paragraph-regular text-foreground-default">
 							{person.handle}
 						</span>
diff --git a/web/src/routes/[handle]/[repo]/settings/hooks/+page.svelte b/web/src/routes/[handle]/[repo]/settings/hooks/+page.svelte
index 53f0bc77..963691b4 100644
--- a/web/src/routes/[handle]/[repo]/settings/hooks/+page.svelte
+++ b/web/src/routes/[handle]/[repo]/settings/hooks/+page.svelte
@@ -79,7 +79,7 @@
 							class="flex items-center gap-1.5 typography-paragraph-regular text-foreground-muted"
 						>
 							{hook.added}
-							<Avatar handle={hook.by} size="size-4" />
+							<Avatar handle={hook.by} size="small" />
 							{hook.by}
 						</span>
 					</div>
diff --git a/web/src/routes/[handle]/[repo]/settings/pipelines/+page.svelte b/web/src/routes/[handle]/[repo]/settings/pipelines/+page.svelte
index ccff6de0..daf19d3b 100644
--- a/web/src/routes/[handle]/[repo]/settings/pipelines/+page.svelte
+++ b/web/src/routes/[handle]/[repo]/settings/pipelines/+page.svelte
@@ -85,7 +85,7 @@
 							class="flex items-center gap-1.5 typography-paragraph-regular text-foreground-muted"
 						>
 							{secret.added}
-							<Avatar handle={secret.by} size="size-4" />
+							<Avatar handle={secret.by} size="small" />
 							{secret.by}
 						</span>
 					</span>
diff --git a/web/src/routes/repo/new/+page.svelte b/web/src/routes/repo/new/+page.svelte
index ff9d309a..1188bd8a 100644
--- a/web/src/routes/repo/new/+page.svelte
+++ b/web/src/routes/repo/new/+page.svelte
@@ -54,7 +54,7 @@
 								<div
 									class="hidden shrink-0 items-center gap-1 p-2 typography-paragraph-small text-foreground-muted md:flex md:rounded-l md:border md:border-r-0 md:border-border-default md:bg-background-inset"
 								>
-									<Avatar did={user?.did} handle={user?.handle} size="size-5" tiny />
+									<Avatar did={user?.did} handle={user?.handle} size="regular" />
 									<span>{user?.handle ?? "…"}</span>
 								</div>
 								<input