From 2e4bb5a5686d09ec730568eba05047f29084fb7e Mon Sep 17 00:00:00 2001
From: eti <eti@eti.tf>
Date: Tue, 4 Aug 2026 14:13:31 +0200
Subject: [PATCH] web: give Avatar a named size scale
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Avatar used to take a tailwind class for its size, and a separate `tiny` flag
that picked which image size to download. Nothing kept those two in agreement,
and they drifted apart: comment avatars draw at 32px but downloaded a 32px
image, so they looked blurry on retina screens, while the small 16px avatars in
settings downloaded a full-size one.

Now there's one prop. Pick mini, small, regular or large — the names the design
system already uses — and Avatar works out the image size itself, always asking
for twice what it draws so it stays sharp. `full` is for the cases where the
surrounding layout sets the size instead; it fills whatever box you put it in
and uses the original image.

The sizes go through tv() so you can still pass your own size class and have it
win. Two size classes in one string is a coin flip otherwise, because tailwind
decides by where the rules land in the stylesheet, not the order you wrote them.

A few avatars shift slightly to land on the scale: comments 32 to 26, settings
lists 16 to 17, access and last commit 20 to 21, repo header and commit rows 24
to 26.

Signed-off-by: eti <eti@eti.tf>
---
 web/src/lib/avatar.ts                         |  4 +-
 web/src/lib/components/comment/Comment.svelte |  2 +-
 .../lib/components/comment/CommentBox.svelte  |  2 +-
 .../profile/FollowCardContent.svelte          |  2 +-
 .../lib/components/profile/ProfileCard.svelte |  7 +--
 .../lib/components/repo/CommitHeader.svelte   |  2 +-
 .../lib/components/repo/CommitLogView.svelte  |  2 +-
 .../components/repo/LastCommitPanel.svelte    |  2 +-
 web/src/lib/components/repo/RepoHeader.svelte |  2 +-
 .../settings/tabs/ProfileTab.svelte           |  2 +-
 .../lib/components/ui/Avatar.stories.svelte   | 19 +++---
 web/src/lib/components/ui/Avatar.svelte       | 59 +++++++++++++++++--
 web/src/lib/components/ui/User.svelte         | 21 ++++---
 .../[repo]/settings/access/+page.svelte       |  2 +-
 .../[repo]/settings/hooks/+page.svelte        |  2 +-
 .../[repo]/settings/pipelines/+page.svelte    |  2 +-
 web/src/routes/repo/new/+page.svelte          |  2 +-
 17 files changed, 93 insertions(+), 41 deletions(-)

diff --git a/web/src/lib/avatar.ts b/web/src/lib/avatar.ts
index 0350e8e6e..8259d7ce0 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 8fd23d878..2550dd39b 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 01e10f42c..48a2e62ea 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 2a4959b6d..4e39ed3d8 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 2ae561f6a..ff4cd27a9 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 b4d6c391a..742ecab3b 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 d07df54f2..a38d1f638 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 7eb6c6640..7864729ac 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 4b56f4998..0288d8853 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 91c2c50d5..eb061d959 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 ce91be3bf..6e91e8978 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 028e01da5..43077c79e 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 0c0642308..aff642f63 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 ecf8612e7..a962be402 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 53f0bc770..963691b45 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 ccff6de06..daf19d3b9 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 ff9d309ab..1188bd8aa 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
-- 
2.51.2