From 22fbfda73efcad3b7d4797487c11d267ec48b967 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 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
-- 
2.51.2