From 3b25059fb97bd5edbf9f1ace4194ec2ea4323fff Mon Sep 17 00:00:00 2001
From: eti <eti@eti.tf>
Date: Tue, 4 Aug 2026 16:53:20 +0200
Subject: [PATCH] web: add the welcome onboarding flow
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Four steps in one card — profile, follow & star, ssh keys, finish — with
the same content as the appview's /welcome templates. The step rail sits
at the top and the body slides left or right as you move between steps.

Data is mocked, nothing talks to an api yet.

Field and Textarea gained the variants the steps needed: sentence-case
labels, and a shorter box for the ssh key.

Signed-off-by: eti <eti@eti.tf>
---
 web/src/lib/components/icons/Bluesky.svelte   |  24 +++
 web/src/lib/components/ui/Field.svelte        |  39 +++-
 web/src/lib/components/ui/Textarea.svelte     |  25 ++-
 .../lib/components/welcome/FinishStep.svelte  | 167 ++++++++++++++++++
 .../lib/components/welcome/KeysStep.svelte    |  68 +++++++
 .../lib/components/welcome/ProfileStep.svelte |  73 ++++++++
 .../lib/components/welcome/SocialStep.svelte  |  32 ++++
 .../lib/components/welcome/StepHeader.svelte  |  32 ++++
 web/src/lib/components/welcome/Steps.svelte   |  79 +++++++++
 .../lib/components/welcome/WelcomeCard.svelte |  96 ++++++++++
 .../lib/components/welcome/draft.svelte.ts    |  33 ++++
 web/src/lib/components/welcome/mock.ts        |  95 ++++++++++
 web/src/lib/components/welcome/steps.ts       |  16 ++
 web/src/routes/+layout.svelte                 |   6 +-
 web/src/routes/welcome/+page.svelte           |  69 ++++++++
 15 files changed, 838 insertions(+), 16 deletions(-)
 create mode 100644 web/src/lib/components/icons/Bluesky.svelte
 create mode 100644 web/src/lib/components/welcome/FinishStep.svelte
 create mode 100644 web/src/lib/components/welcome/KeysStep.svelte
 create mode 100644 web/src/lib/components/welcome/ProfileStep.svelte
 create mode 100644 web/src/lib/components/welcome/SocialStep.svelte
 create mode 100644 web/src/lib/components/welcome/StepHeader.svelte
 create mode 100644 web/src/lib/components/welcome/Steps.svelte
 create mode 100644 web/src/lib/components/welcome/WelcomeCard.svelte
 create mode 100644 web/src/lib/components/welcome/draft.svelte.ts
 create mode 100644 web/src/lib/components/welcome/mock.ts
 create mode 100644 web/src/lib/components/welcome/steps.ts
 create mode 100644 web/src/routes/welcome/+page.svelte

diff --git a/web/src/lib/components/icons/Bluesky.svelte b/web/src/lib/components/icons/Bluesky.svelte
new file mode 100644
index 00000000..72be9924
--- /dev/null
+++ b/web/src/lib/components/icons/Bluesky.svelte
@@ -0,0 +1,24 @@
+<script lang="ts">
+	// lucide carries no Bluesky mark, so this is the vector the appview already
+	// ships at appview/pages/static/icons/bluesky.svg — kept identical so both
+	// front ends draw the same butterfly.
+	import type { SVGAttributes } from "svelte/elements";
+
+	let { class: className = "size-4", ...rest }: SVGAttributes<SVGSVGElement> = $props();
+</script>
+
+<svg
+	xmlns="http://www.w3.org/2000/svg"
+	role="img"
+	viewBox="-3 -3 30 30"
+	class={className}
+	{...rest}
+>
+	<title>Bluesky</title>
+	<path
+		fill="none"
+		stroke="currentColor"
+		stroke-width="2.25"
+		d="M12 10.8c-1.087-2.114-4.046-6.053-6.798-7.995C2.566.944 1.561 1.266.902 1.565.139 1.908 0 3.08 0 3.768c0 .69.378 5.65.624 6.479.815 2.736 3.713 3.66 6.383 3.364.136-.02.275-.039.415-.056-.138.022-.276.04-.415.056-3.912.58-7.387 2.005-2.83 7.078 5.013 5.19 6.87-1.113 7.823-4.308.953 3.195 2.05 9.271 7.733 4.308 4.267-4.308 1.172-6.498-2.74-7.078a8.741 8.741 0 0 1-.415-.056c.14.017.279.036.415.056 2.67.297 5.568-.628 6.383-3.364.246-.828.624-5.79.624-6.478 0-.69-.139-1.861-.902-2.206-.659-.298-1.664-.62-4.3 1.24C16.046 4.748 13.087 8.687 12 10.8Z"
+	/>
+</svg>
diff --git a/web/src/lib/components/ui/Field.svelte b/web/src/lib/components/ui/Field.svelte
index 0df26037..0eca6620 100644
--- a/web/src/lib/components/ui/Field.svelte
+++ b/web/src/lib/components/ui/Field.svelte
@@ -1,3 +1,28 @@
+<script module lang="ts">
+	import { tv, type VariantProps } from "tailwind-variants";
+
+	export const field = tv({
+		slots: {
+			root: "flex flex-col gap-1.5",
+			label: "typography-paragraph-small font-medium text-foreground-default",
+			subtitle: "typography-paragraph-small text-foreground-muted"
+		},
+		variants: {
+			// settings forms label their fields in small caps; the onboarding steps use
+			// sentence case, so the casing is a variant rather than baked into the slot
+			labelCase: {
+				upper: { label: "tracking-wide uppercase" },
+				normal: { label: "" }
+			}
+		},
+		defaultVariants: {
+			labelCase: "upper"
+		}
+	});
+
+	export type FieldVariants = VariantProps<typeof field>;
+</script>
+
 <script lang="ts">
 	import type { Snippet } from "svelte";
 	import type { HTMLAttributes } from "svelte/elements";
@@ -7,6 +32,7 @@
 		subtitle?: string;
 		for?: string;
 		required?: boolean;
+		labelCase?: FieldVariants["labelCase"];
 		class?: string;
 		children: Snippet<[{ id: string }]>;
 	}
@@ -16,21 +42,20 @@
 		subtitle,
 		for: forId,
 		required = false,
-		class: className = "",
+		labelCase = "upper",
+		class: className,
 		children,
 		...rest
 	}: Props = $props();
 
 	const generatedId = $props.id();
 	const id = $derived(forId ?? generatedId);
+	const slot = $derived(field({ labelCase }));
 </script>
 
-<div class={`flex flex-col gap-1.5 ${className}`} {...rest}>
+<div class={slot.root({ class: className })} {...rest}>
 	{#if label}
-		<label
-			for={id}
-			class="typography-paragraph-small font-medium tracking-wide text-foreground-default uppercase"
-		>
+		<label for={id} class={slot.label()}>
 			{label}
 			{#if required}
 				<span class="text-foreground-danger">*</span>
@@ -39,6 +64,6 @@
 	{/if}
 	{@render children({ id })}
 	{#if subtitle}
-		<p class="typography-paragraph-small text-foreground-muted">{subtitle}</p>
+		<p class={slot.subtitle()}>{subtitle}</p>
 	{/if}
 </div>
diff --git a/web/src/lib/components/ui/Textarea.svelte b/web/src/lib/components/ui/Textarea.svelte
index f320f907..ca85aa78 100644
--- a/web/src/lib/components/ui/Textarea.svelte
+++ b/web/src/lib/components/ui/Textarea.svelte
@@ -9,14 +9,20 @@
 	export const textareaField = tv({
 		slots: {
 			root: "relative flex items-start gap-1 rounded-sm border bg-background-default transition-colors",
-			// the floor has to live on the textarea, not the root: the resize handle only ever
-			// shrinks the textarea, so a min-height on the root would let the handle drag past the
-			// box's own minimum and leave dead space under the field. keep this in sync with
-			// textareaMinHeight above — it's 2px shorter because the root's border sits outside it.
 			textarea:
-				"min-h-63.5 flex-1 self-stretch bg-transparent py-2 typography-paragraph-small leading-6 outline-none placeholder:text-foreground-placeholder read-only:resize-none disabled:cursor-not-allowed disabled:resize-none"
+				"flex-1 self-stretch bg-transparent py-2 outline-none placeholder:text-foreground-placeholder read-only:resize-none disabled:cursor-not-allowed disabled:resize-none"
 		},
 		variants: {
+			// the floor has to live on the textarea, not the root: the resize handle only ever
+			// shrinks the textarea, so a min-height on the root would let the handle drag past the
+			// box's own minimum and leave dead space under the field. `default` keeps
+			// textareaMinHeight above in sync — it's 2px shorter because the root's border sits
+			// outside it. `compact` is for short fields (an ssh key, a one-line note) where the
+			// editor-sized floor would swallow the form.
+			size: {
+				default: { textarea: "min-h-63.5" },
+				compact: { textarea: "min-h-20" }
+			},
 			error: {
 				false: {
 					root: "border-border-default focus-within:border-border-strong focus-within:ring-1 focus-within:ring-border-strong"
@@ -46,7 +52,8 @@
 		defaultVariants: {
 			error: false,
 			disabled: false,
-			readonly: false
+			readonly: false,
+			size: "default"
 		}
 	});
 
@@ -65,6 +72,7 @@
 		loading?: boolean;
 		readonly?: boolean;
 		resizeable?: boolean;
+		size?: TextareaFieldVariants["size"];
 		iconLeft?: Component<SvelteHTMLElements["svg"]>;
 		iconRight?: Component<SvelteHTMLElements["svg"]>;
 		class?: string;
@@ -78,6 +86,7 @@
 		loading = false,
 		readonly = false,
 		resizeable = false,
+		size = "default",
 		iconLeft,
 		iconRight,
 		class: className,
@@ -85,7 +94,9 @@
 		...rest
 	}: Props = $props();
 
-	const { root, textarea } = $derived(textareaField({ error, disabled, readonly, resizeable }));
+	const { root, textarea } = $derived(
+		textareaField({ error, disabled, readonly, resizeable, size })
+	);
 
 	// The root no longer carries the text inset (so the scrollbar/resize handle can sit flush
 	// against the border) — the textarea itself owns its horizontal padding, collapsing to 0 on
diff --git a/web/src/lib/components/welcome/FinishStep.svelte b/web/src/lib/components/welcome/FinishStep.svelte
new file mode 100644
index 00000000..904a900c
--- /dev/null
+++ b/web/src/lib/components/welcome/FinishStep.svelte
@@ -0,0 +1,167 @@
+<script module lang="ts">
+	import { tv, type VariantProps } from "tailwind-variants";
+
+	// the finish bento: a two-column grid where one tile runs the full width and
+	// another spans both rows (appview onboarding/fragments/finish.html)
+	export const tile = tv({
+		slots: {
+			root: "flex flex-col gap-2 rounded-sm border border-border-default p-4",
+			heading: "flex items-center gap-2 typography-paragraph-regular text-foreground-default",
+			body: "flex-1 typography-paragraph-small text-foreground-muted",
+			action:
+				"ml-auto flex w-fit items-center gap-1 typography-paragraph-small text-foreground-default no-underline hover:underline"
+		},
+		variants: {
+			span: {
+				full: { root: "sm:col-span-2" },
+				tall: { root: "sm:row-span-2" },
+				single: { root: "" }
+			},
+			// the community row's tiles are themselves the link, so they need the hover
+			// surface and the tighter gap the four bento tiles don't want
+			link: {
+				true: {
+					root: "flex-1 gap-1 no-underline transition-colors hover:bg-background-subtle hover:no-underline"
+				},
+				false: { root: "" }
+			}
+		},
+		defaultVariants: {
+			span: "single",
+			link: false
+		}
+	});
+
+	export type TileVariants = VariantProps<typeof tile>;
+</script>
+
+<script lang="ts">
+	import type { Component } from "svelte";
+	import type { SvelteHTMLElements } from "svelte/elements";
+	import { resolve } from "$app/paths";
+	import ArrowRight from "$icon/arrow-right";
+	import BookMarked from "$icon/book-marked";
+	import GitPullRequest from "$icon/git-pull-request";
+	import Layers2 from "$icon/layers-2";
+	import MessageCircle from "$icon/message-circle";
+	import Server from "$icon/server";
+	import Twitter from "$icon/twitter";
+	import Bluesky from "$lib/components/icons/Bluesky.svelte";
+	import StepHeader from "./StepHeader.svelte";
+
+	const slot = tile();
+
+	// the appview links /core, a shortcut route it owns; the svelte app addresses
+	// repositories as /[handle]/[repo]
+	const coreHref = resolve("/tangled.org/core" as "/");
+	const newRepoHref = resolve("/repo/new");
+
+	const docs: {
+		icon: Component<SvelteHTMLElements["svg"]>;
+		title: string;
+		body: string;
+		href: string;
+	}[] = [
+		{
+			icon: Server,
+			title: "Host your own knot",
+			body: "Host repositories on your own infrastructure with knots.",
+			href: "https://docs.tangled.org/knot-self-hosting-guide.html"
+		},
+		{
+			icon: Layers2,
+			title: "Host your own spindle",
+			body: "Run CI jobs on your own infrastructure using spindles.",
+			href: "https://docs.tangled.org/spindles.html#self-hosting-guide"
+		}
+	];
+
+	const community: {
+		icon: Component<SvelteHTMLElements["svg"]>;
+		title: string;
+		body: string;
+		href: string;
+	}[] = [
+		{
+			icon: Bluesky,
+			title: "Bluesky",
+			body: "Follow us @tangled.org on Bluesky for updates.",
+			href: "https://bsky.app/profile/tangled.org"
+		},
+		{
+			icon: MessageCircle,
+			title: "Discord",
+			body: "Join the community on Discord.",
+			href: "https://chat.tangled.org"
+		},
+		{
+			icon: Twitter,
+			title: "X (Twitter)",
+			body: "Follow us @tangled_org on X for updates.",
+			href: "https://x.com/tangled_org"
+		}
+	];
+</script>
+
+<div class="flex flex-col gap-6">
+	<StepHeader title="You're all set!" subtitle="Here are a few things to explore next:" />
+
+	<div class="grid grid-cols-1 gap-3 sm:grid-cols-2">
+		<div class={tile({ span: "full" }).root()}>
+			{@render heading(BookMarked, "Create a repository")}
+			<p class={slot.body()}>Kick things off by creating your first repository.</p>
+			<a href={newRepoHref} class={slot.action()}>
+				Create
+				<ArrowRight class="size-4 shrink-0" aria-hidden="true" />
+			</a>
+		</div>
+
+		<div class={tile({ span: "tall" }).root()}>
+			{@render heading(GitPullRequest, "Contribute to the Tangled project")}
+			<p class={slot.body()}>
+				Tangled is fully open-source: Open a feature request, or submit a bug-fix!
+				<br /><br />
+				All contributions are welcome.
+			</p>
+			<a href={coreHref} class={slot.action()}>
+				Contribute
+				<ArrowRight class="size-4 shrink-0" aria-hidden="true" />
+			</a>
+		</div>
+
+		{#each docs as doc (doc.title)}
+			<div class={slot.root()}>
+				{@render heading(doc.icon, doc.title)}
+				<p class={slot.body()}>{doc.body}</p>
+				<a href={doc.href} target="_blank" rel="external noopener noreferrer" class={slot.action()}>
+					Read the docs
+					<ArrowRight class="size-4 shrink-0" aria-hidden="true" />
+				</a>
+			</div>
+		{/each}
+	</div>
+
+	<ul class="grid grid-cols-1 gap-3 sm:grid-cols-3">
+		{#each community as link (link.title)}
+			<li class="flex">
+				<a
+					href={link.href}
+					target="_blank"
+					rel="external noopener noreferrer"
+					class={tile({ link: true }).root()}
+				>
+					{@render heading(link.icon, link.title)}
+					<span class={slot.body()}>{link.body}</span>
+				</a>
+			</li>
+		{/each}
+	</ul>
+</div>
+
+{#snippet heading(icon: Component<SvelteHTMLElements["svg"]>, title: string)}
+	{@const Icon = icon}
+	<span class={slot.heading()}>
+		<Icon class="size-4 shrink-0" aria-hidden="true" />
+		{title}
+	</span>
+{/snippet}
diff --git a/web/src/lib/components/welcome/KeysStep.svelte b/web/src/lib/components/welcome/KeysStep.svelte
new file mode 100644
index 00000000..eff4fa66
--- /dev/null
+++ b/web/src/lib/components/welcome/KeysStep.svelte
@@ -0,0 +1,68 @@
+<script lang="ts">
+	import Plus from "$icon/plus";
+	import Button from "$lib/components/ui/Button.svelte";
+	import Field from "$lib/components/ui/Field.svelte";
+	import Input from "$lib/components/ui/Input.svelte";
+	import Textarea from "$lib/components/ui/Textarea.svelte";
+	import KeyCard from "$lib/components/settings/KeyCard.svelte";
+	import StepHeader from "./StepHeader.svelte";
+	import { addKey, draft, removeKey } from "./draft.svelte";
+
+	let name = $state("");
+	let key = $state("");
+
+	const canAdd = $derived(name.trim() !== "" && key.trim() !== "");
+
+	const add = (event: SubmitEvent) => {
+		event.preventDefault();
+		if (!canAdd) return;
+		addKey(name.trim(), key.trim());
+		name = "";
+		key = "";
+	};
+</script>
+
+<div class="flex flex-col gap-6">
+	<StepHeader
+		title="Add an SSH key"
+		subtitle="Add a public SSH key to push to your repositories over SSH."
+	/>
+
+	{#if draft.keys.length > 0}
+		<ul class="flex flex-col gap-3">
+			{#each draft.keys as pubkey (pubkey.id)}
+				<li>
+					<KeyCard
+						name={pubkey.name}
+						fingerprint={pubkey.fingerprint}
+						createdAt={pubkey.createdAt}
+						onDelete={() => removeKey(pubkey.id)}
+					/>
+				</li>
+			{/each}
+		</ul>
+	{/if}
+
+	<form class="flex flex-col gap-4" onsubmit={add}>
+		<Field label="Key name" labelCase="normal">
+			{#snippet children({ id })}
+				<Input {id} placeholder="my-laptop" required bind:value={name} />
+			{/snippet}
+		</Field>
+
+		<Field label="Public key" labelCase="normal">
+			{#snippet children({ id })}
+				<Textarea
+					{id}
+					size="compact"
+					rows={3}
+					required
+					placeholder="ssh-ed25519 AAAA..."
+					bind:value={key}
+				/>
+			{/snippet}
+		</Field>
+
+		<Button type="submit" icon={Plus} disabled={!canAdd} class="ml-auto">Add key</Button>
+	</form>
+</div>
diff --git a/web/src/lib/components/welcome/ProfileStep.svelte b/web/src/lib/components/welcome/ProfileStep.svelte
new file mode 100644
index 00000000..a8e0a224
--- /dev/null
+++ b/web/src/lib/components/welcome/ProfileStep.svelte
@@ -0,0 +1,73 @@
+<script module lang="ts">
+	import { tv, type VariantProps } from "tailwind-variants";
+
+	export const avatarPicker = tv({
+		slots: {
+			label:
+				"flex size-40 cursor-pointer flex-col items-center justify-center gap-1 overflow-hidden rounded-full border border-border-default text-foreground-subtle transition-colors hover:bg-background-subtle",
+			image: "size-full rounded-full object-cover",
+			placeholder: "flex flex-col items-center justify-center gap-1"
+		}
+	});
+
+	export type AvatarPickerVariants = VariantProps<typeof avatarPicker>;
+</script>
+
+<script lang="ts">
+	import Camera from "$icon/camera";
+	import Field from "$lib/components/ui/Field.svelte";
+	import Input from "$lib/components/ui/Input.svelte";
+	import StepHeader from "./StepHeader.svelte";
+	import { draft } from "./draft.svelte";
+
+	const slot = avatarPicker();
+
+	// no upload endpoint wired up: the preview is a local object url, which is all
+	// the appview shows before its hx-post to /profile/avatar comes back
+	const pick = (event: Event) => {
+		const file = (event.currentTarget as HTMLInputElement).files?.[0];
+		if (!file) return;
+		if (draft.picture) URL.revokeObjectURL(draft.picture);
+		draft.picture = URL.createObjectURL(file);
+	};
+</script>
+
+<div class="flex flex-col gap-6">
+	<StepHeader title="Welcome!" subtitle="Let's get your profile ready. All fields are optional." />
+
+	<div class="flex flex-col gap-6 md:flex-row">
+		<div class="flex shrink-0 justify-center md:block">
+			<label class={slot.label()}>
+				{#if draft.picture}
+					<img src={draft.picture} alt="Your new avatar" class={slot.image()} />
+				{:else}
+					<span class={slot.placeholder()}>
+						<Camera class="size-6" aria-hidden="true" />
+						<span class="typography-paragraph-small">Upload picture</span>
+					</span>
+				{/if}
+				<input type="file" accept="image/png,image/jpeg" class="hidden" onchange={pick} />
+			</label>
+		</div>
+
+		<div class="flex min-w-0 flex-1 flex-col gap-4">
+			<Field label="Bio" labelCase="normal">
+				{#snippet children({ id })}
+					<Input {id} placeholder="Tell us about yourself" bind:value={draft.description} />
+				{/snippet}
+			</Field>
+
+			<Field label="Pronouns" labelCase="normal">
+				{#snippet children({ id })}
+					<Input {id} placeholder="they/them" bind:value={draft.pronouns} />
+				{/snippet}
+			</Field>
+
+			<Field label="Website" labelCase="normal">
+				{#snippet children({ id })}
+					<Input {id} placeholder="example.com" bind:value={draft.website} />
+				{/snippet}
+			</Field>
+		</div>
+	</div>
+</div>
diff --git a/web/src/lib/components/welcome/SocialStep.svelte b/web/src/lib/components/welcome/SocialStep.svelte
new file mode 100644
index 00000000..0ee0360a
--- /dev/null
+++ b/web/src/lib/components/welcome/SocialStep.svelte
@@ -0,0 +1,32 @@
+<script lang="ts">
+	import EmptyState from "$lib/components/ui/EmptyState.svelte";
+	import FollowCard from "$lib/components/profile/FollowCard.svelte";
+	import RepoCard from "$lib/components/repo/RepoCard.svelte";
+	import { repoKey } from "$lib/components/profile/types";
+	import StepHeader from "./StepHeader.svelte";
+	import { people, trendingRepos } from "./mock";
+</script>
+
+<div class="flex flex-col gap-6">
+	<StepHeader title="Discover" subtitle="Find users to follow and repositories to star." />
+
+	{#if people.length > 0 || trendingRepos.length > 0}
+		{#if people.length > 0}
+			<div class="flex flex-col gap-3">
+				{#each people as person (person.did)}
+					<FollowCard {person} border />
+				{/each}
+			</div>
+		{/if}
+
+		{#if trendingRepos.length > 0}
+			<div class="flex flex-col gap-3">
+				{#each trendingRepos as repo (repoKey(repo))}
+					<RepoCard {repo} border />
+				{/each}
+			</div>
+		{/if}
+	{:else}
+		<EmptyState message="Nothing to suggest right now — you can explore once you're set up." />
+	{/if}
+</div>
diff --git a/web/src/lib/components/welcome/StepHeader.svelte b/web/src/lib/components/welcome/StepHeader.svelte
new file mode 100644
index 00000000..3a5dff2f
--- /dev/null
+++ b/web/src/lib/components/welcome/StepHeader.svelte
@@ -0,0 +1,32 @@
+<script module lang="ts">
+	import { tv, type VariantProps } from "tailwind-variants";
+
+	// every step opens with the same title/subtitle pair (appview onboarding/* fragments)
+	export const stepHeader = tv({
+		slots: {
+			root: "flex flex-col gap-2",
+			title: "typography-heading-3 font-semibold text-foreground-default",
+			subtitle: "typography-paragraph-regular text-foreground-muted"
+		}
+	});
+
+	export type StepHeaderVariants = VariantProps<typeof stepHeader>;
+</script>
+
+<script lang="ts">
+	interface Props {
+		title: string;
+		subtitle?: string;
+	}
+
+	let { title, subtitle }: Props = $props();
+
+	const slot = stepHeader();
+</script>
+
+<header class={slot.root()}>
+	<h1 class={slot.title()}>{title}</h1>
+	{#if subtitle}
+		<p class={slot.subtitle()}>{subtitle}</p>
+	{/if}
+</header>
diff --git a/web/src/lib/components/welcome/Steps.svelte b/web/src/lib/components/welcome/Steps.svelte
new file mode 100644
index 00000000..c0833305
--- /dev/null
+++ b/web/src/lib/components/welcome/Steps.svelte
@@ -0,0 +1,79 @@
+<script module lang="ts">
+	import { tv, type VariantProps } from "tailwind-variants";
+
+	// the numbered rail from Figma node 191:6514 — same shape as the appview's
+	// onboarding/fragments/steps, restyled onto the design-system tokens. the three
+	// states differ only in the marker fill and the label colour, so they are one
+	// variant across two slots rather than three hand-written class strings.
+	export const steps = tv({
+		slots: {
+			root: "flex w-full items-center gap-2",
+			item: "flex shrink-0 items-center gap-2",
+			marker:
+				"flex size-5 shrink-0 items-center justify-center rounded-full typography-paragraph-small",
+			// labels are desktop-only, but sr-only rather than hidden so the rail still
+			// reads as a named list of steps on a narrow screen
+			label: "sr-only typography-paragraph-small whitespace-nowrap sm:not-sr-only",
+			connector: "h-px min-w-4 flex-1 bg-border-default"
+		},
+		variants: {
+			state: {
+				done: {
+					marker: "bg-background-inset text-foreground-default",
+					label: "text-foreground-subtle"
+				},
+				current: {
+					marker: "bg-background-muted text-foreground-default",
+					label: "text-foreground-default"
+				},
+				upcoming: {
+					marker: "bg-background-inset text-foreground-subtle",
+					label: "text-foreground-subtle"
+				}
+			}
+		},
+		defaultVariants: {
+			state: "upcoming"
+		}
+	});
+
+	export type StepsVariants = VariantProps<typeof steps>;
+	export type StepState = NonNullable<StepsVariants["state"]>;
+</script>
+
+<script lang="ts">
+	import Check from "$icon/check";
+
+	interface Props {
+		items: readonly { key: string; label: string }[];
+		current: number;
+	}
+
+	let { items, current }: Props = $props();
+
+	// root and connector take no variant, so they resolve once
+	const shell = steps();
+
+	const stateOf = (index: number): StepState =>
+		index < current ? "done" : index === current ? "current" : "upcoming";
+</script>
+
+<ol class={shell.root()}>
+	{#each items as item, index (item.key)}
+		{#if index > 0}
+			<li aria-hidden="true" class={shell.connector()}></li>
+		{/if}
+		{@const state = stateOf(index)}
+		{@const slot = steps({ state })}
+		<li class={slot.item()} aria-current={state === "current" ? "step" : undefined}>
+			<span class={slot.marker()} aria-label={state === "done" ? "done" : undefined}>
+				{#if state === "done"}
+					<Check class="size-3.5" aria-hidden="true" />
+				{:else}
+					{index + 1}
+				{/if}
+			</span>
+			<span class={slot.label()}>{item.label}</span>
+		</li>
+	{/each}
+</ol>
diff --git a/web/src/lib/components/welcome/WelcomeCard.svelte b/web/src/lib/components/welcome/WelcomeCard.svelte
new file mode 100644
index 00000000..97136fff
--- /dev/null
+++ b/web/src/lib/components/welcome/WelcomeCard.svelte
@@ -0,0 +1,96 @@
+<script module lang="ts">
+	import { tv, type VariantProps } from "tailwind-variants";
+
+	export const welcomeCard = tv({
+		slots: {
+			root: "overflow-hidden rounded-sm border border-border-default bg-background-default shadow-xs",
+			header: "overflow-x-auto border-b border-border-default px-6 py-5",
+			// grid so the outgoing and incoming panes share one cell and cross-fade in
+			// place; overflow-hidden is what keeps the swipe inside the card
+			body: "grid overflow-hidden p-6",
+			pane: "col-start-1 row-start-1 min-w-0",
+			footer: "flex items-center justify-between gap-4 border-t border-border-default px-6 py-4"
+		}
+	});
+
+	export type WelcomeCardVariants = VariantProps<typeof welcomeCard>;
+</script>
+
+<script lang="ts">
+	import type { Snippet } from "svelte";
+	import { untrack } from "svelte";
+	import { cubicIn, cubicOut } from "svelte/easing";
+	import { prefersReducedMotion } from "svelte/motion";
+	import { fly } from "svelte/transition";
+	import ArrowLeft from "$icon/arrow-left";
+	import ArrowRight from "$icon/arrow-right";
+	import Check from "$icon/check";
+	import Button from "$lib/components/ui/Button.svelte";
+	import Steps from "./Steps.svelte";
+	import { WELCOME_STEPS, LAST_STEP } from "./steps";
+
+	interface Props {
+		step: number;
+		/** +1 when advancing, -1 when going back — decides which way the pane slides */
+		direction: number;
+		/** the appview greens Next once the step has something worth saving */
+		nextReady?: boolean;
+		onBack: () => void;
+		onNext: () => void;
+		/** rendered per step index, frozen at pane creation so the outgoing pane keeps its own content */
+		children: Snippet<[number]>;
+	}
+
+	let { step, direction, nextReady = false, onBack, onNext, children }: Props = $props();
+
+	const slot = welcomeCard();
+
+	const DISTANCE = 40;
+	const enter = $derived(
+		prefersReducedMotion.current
+			? { duration: 0 }
+			: { x: direction * DISTANCE, duration: 240, delay: 90, easing: cubicOut }
+	);
+	const leave = $derived(
+		prefersReducedMotion.current
+			? { duration: 0 }
+			: { x: direction * -DISTANCE, duration: 150, easing: cubicIn }
+	);
+
+	const isLast = $derived(step === LAST_STEP);
+</script>
+
+<div class={slot.root()}>
+	<div class={slot.header()}>
+		<Steps items={WELCOME_STEPS} current={step} />
+	</div>
+
+	<div class={slot.body()}>
+		{#key step}
+			<!-- untrack freezes the index at creation: `children` is a live snippet, so
+			     without this the leaving pane would re-render with the new step's content
+			     halfway through its own exit transition -->
+			{@const frozen = untrack(() => step)}
+			<div class={slot.pane()} in:fly={enter} out:fly={leave}>
+				{@render children(frozen)}
+			</div>
+		{/key}
+	</div>
+
+	<div class={slot.footer()}>
+		{#if step > 0}
+			<Button variant="ghost" icon={ArrowLeft} onclick={onBack}>Back</Button>
+		{:else}
+			<span></span>
+		{/if}
+
+		<Button
+			variant={nextReady ? "primary" : "default"}
+			icon={isLast ? Check : ArrowRight}
+			iconSide={isLast ? "left" : "right"}
+			onclick={onNext}
+		>
+			{isLast ? "Finish" : "Next"}
+		</Button>
+	</div>
+</div>
diff --git a/web/src/lib/components/welcome/draft.svelte.ts b/web/src/lib/components/welcome/draft.svelte.ts
new file mode 100644
index 00000000..2cbf848e
--- /dev/null
+++ b/web/src/lib/components/welcome/draft.svelte.ts
@@ -0,0 +1,33 @@
+// what the user has entered so far. the step panes are destroyed and recreated on
+// every transition, so this cannot live inside them — the appview has the same
+// split for a different reason, keeping progress in the `onboarding` table and the
+// profile/keys on the record, so wiring this up later means replacing the module
+// rather than moving state around the components.
+
+import { initialKeys, newKey, type MockKey } from "./mock";
+
+export const draft = $state({
+	description: "",
+	pronouns: "",
+	website: "",
+	/** a local object url until there is an upload endpoint to post to */
+	picture: undefined as string | undefined,
+	keys: [...initialKeys] as MockKey[]
+});
+
+/** the appview greens Next once any profile field has something in it */
+export const profileFilled = () =>
+	[draft.description, draft.pronouns, draft.website].some((value) => value.trim() !== "");
+
+// the counter lives here rather than in KeysStep: the pane is recreated on every
+// transition, so a component-local counter would restart and collide with the ids
+// already in the list
+let nextKeyId = 1;
+
+export const addKey = (name: string, key: string) => {
+	draft.keys = [...draft.keys, newKey(nextKeyId++, name, key)];
+};
+
+export const removeKey = (id: number) => {
+	draft.keys = draft.keys.filter((key) => key.id !== id);
+};
diff --git a/web/src/lib/components/welcome/mock.ts b/web/src/lib/components/welcome/mock.ts
new file mode 100644
index 00000000..4aff06c7
--- /dev/null
+++ b/web/src/lib/components/welcome/mock.ts
@@ -0,0 +1,95 @@
+// stand-in data for the welcome flow. the appview fills these from
+// OnboardingSocial / OnboardingKeys; nothing here is wired to an api yet, so the
+// step components read from this module and a real load later replaces it.
+
+import type { PersonData, RepoCardData } from "$lib/components/profile/types";
+
+export interface MockKey {
+	id: number;
+	name: string;
+	fingerprint: string;
+	createdAt: string;
+}
+
+const did = (name: string) => `did:plc:${name.replace(/[^a-z0-9]/g, "")}welcome`;
+
+/** OnboardingSocial's People — suggested accounts to follow */
+export const people: PersonData[] = [
+	{
+		did: did("alphaone"),
+		handle: "alpha.one",
+		description: "Innovative coder at tangled.org, passionate about sustainable tech.",
+		followers: 1100,
+		following: 99
+	},
+	{
+		did: did("betaspace"),
+		handle: "beta.space",
+		description: "Rust and Go enthusiast, creating pixel art and exploring plant-based living.",
+		followers: 987,
+		following: 78
+	},
+	{
+		did: did("gammanetwork"),
+		handle: "gamma.network",
+		description: "Co-founder of EcoTech Labs, blending software with environmental solutions.",
+		followers: 1700,
+		following: 25
+	}
+];
+
+/** OnboardingSocial's TrendingRepos */
+export const trendingRepos: RepoCardData[] = [
+	{
+		rkey: "welcome-1",
+		name: "core",
+		repoDid: did("tangledorg"),
+		ownerHandle: "tangled.org",
+		description: "A decentralized network for secure and scalable data storage.",
+		createdAt: "2026-05-02T10:00:00Z",
+		language: "Go",
+		stars: 2200,
+		issues: 31,
+		pulls: 1
+	},
+	{
+		rkey: "welcome-2",
+		name: "batman.vim",
+		repoDid: did("072004xyz"),
+		ownerHandle: "072004.xyz",
+		description: "A Vim colourscheme that only works at night.",
+		createdAt: "2026-04-18T10:00:00Z",
+		language: "Vim Script",
+		stars: 412,
+		issues: 3,
+		pulls: 2
+	},
+	{
+		rkey: "welcome-3",
+		name: "knotserver",
+		repoDid: did("coopppage"),
+		ownerHandle: "coop.page",
+		description: "Self-hostable git remote that speaks the Tangled protocol.",
+		createdAt: "2026-03-09T10:00:00Z",
+		language: "Rust",
+		stars: 856,
+		issues: 12,
+		pulls: 4
+	}
+];
+
+/** OnboardingKeys' PubKeys — starts empty, the step adds to it */
+export const initialKeys: MockKey[] = [];
+
+/**
+ * Builds the row the appview would get back from `PUT /settings/keys`. It lives
+ * here rather than in draft.svelte.ts because svelte/prefer-svelte-reactivity
+ * rejects a plain `Date` inside a rune module, and this one is a throwaway — the
+ * timestamp is read once, never held.
+ */
+export const newKey = (id: number, name: string, key: string): MockKey => ({
+	id,
+	name,
+	fingerprint: `SHA256:${key.slice(-32)}`,
+	createdAt: new Date().toISOString()
+});
diff --git a/web/src/lib/components/welcome/steps.ts b/web/src/lib/components/welcome/steps.ts
new file mode 100644
index 00000000..82d5ddc5
--- /dev/null
+++ b/web/src/lib/components/welcome/steps.ts
@@ -0,0 +1,16 @@
+// the onboarding steps, mirroring appview/models/onboarding.go. the appview
+// persists the index in the `onboarding` table, so these values are storage
+// keys, not just display order — keep them aligned with the Go constants.
+export const WELCOME_STEPS = [
+	{ key: "profile", label: "Set up your profile" },
+	{ key: "social", label: "Follow & star" },
+	{ key: "keys", label: "Add SSH keys" },
+	{ key: "finish", label: "Finish" }
+] as const;
+
+export type WelcomeStepKey = (typeof WELCOME_STEPS)[number]["key"];
+
+export const WELCOME_TOTAL = WELCOME_STEPS.length;
+
+/** the last step is the summary — there is nothing left to skip past it */
+export const LAST_STEP = WELCOME_TOTAL - 1;
diff --git a/web/src/routes/+layout.svelte b/web/src/routes/+layout.svelte
index 0d9bea87..7bb082e2 100644
--- a/web/src/routes/+layout.svelte
+++ b/web/src/routes/+layout.svelte
@@ -20,6 +20,8 @@
 
 	const signedIn = $derived(Boolean(auth.currentUser));
 	const isAuthShell = $derived(page.url.pathname === "/login");
+	// the welcome flow runs its own steps chrome, so the bar and footer step aside
+	const isWelcomeShell = $derived(page.url.pathname === "/welcome");
 	const isMarketingShell = $derived(
 		!signedIn && (page.url.pathname === "/about" || page.url.pathname === "/")
 	);
@@ -37,7 +39,7 @@
 			? "flex min-h-screen flex-col bg-linear-to-b from-background-default to-background-canvas text-foreground-default"
 			: "flex min-h-screen flex-col bg-background-canvas text-foreground-default"}
 >
-	{#if !isAuthShell}
+	{#if !isAuthShell && !isWelcomeShell}
 		<header
 			class={isMarketingShell
 				? "z-20 w-full bg-transparent pt-[env(safe-area-inset-top)]"
@@ -56,7 +58,7 @@
 		{@render children()}
 	</main>
 
-	{#if !isAuthShell}
+	{#if !isAuthShell && !isWelcomeShell}
 		<Footer variant={isMarketingShell ? "full" : "minimal"} />
 	{/if}
 </div>
diff --git a/web/src/routes/welcome/+page.svelte b/web/src/routes/welcome/+page.svelte
new file mode 100644
index 00000000..12b561f0
--- /dev/null
+++ b/web/src/routes/welcome/+page.svelte
@@ -0,0 +1,69 @@
+<script lang="ts">
+	import { goto } from "$app/navigation";
+	import { resolve } from "$app/paths";
+	import X from "$icon/x";
+	import Button from "$lib/components/ui/Button.svelte";
+	import Logo from "$lib/components/ui/Logo.svelte";
+	import FinishStep from "$lib/components/welcome/FinishStep.svelte";
+	import KeysStep from "$lib/components/welcome/KeysStep.svelte";
+	import ProfileStep from "$lib/components/welcome/ProfileStep.svelte";
+	import SocialStep from "$lib/components/welcome/SocialStep.svelte";
+	import WelcomeCard from "$lib/components/welcome/WelcomeCard.svelte";
+	import { profileFilled } from "$lib/components/welcome/draft.svelte";
+	import { LAST_STEP, WELCOME_TOTAL } from "$lib/components/welcome/steps";
+
+	// the appview keeps the index in the onboarding table and gives each step its
+	// own GET route; with nothing wired up yet this is local state, so wiring it
+	// later means splitting this into /welcome/[step] and reading the record.
+	let step = $state(0);
+	let direction = $state(1);
+
+	const go = (to: number) => {
+		if (to < 0 || to >= WELCOME_TOTAL) return;
+		direction = to > step ? 1 : -1;
+		step = to;
+	};
+
+	// the appview greens Next on every step past the profile, where it is earned
+	const nextReady = $derived(step === 0 ? profileFilled() : true);
+
+	const leave = () => goto(resolve("/"));
+</script>
+
+<svelte:head>
+	<title>Welcome &middot; Tangled</title>
+</svelte:head>
+
+<div class="flex min-h-screen w-full items-start justify-center px-4 pt-16 pb-8">
+	<main class="w-full max-w-3xl">
+		<h1 class="mb-4 flex place-content-center">
+			<Logo wordmark class="h-10" />
+		</h1>
+
+		<WelcomeCard
+			{step}
+			{direction}
+			{nextReady}
+			onBack={() => go(step - 1)}
+			onNext={() => (step === LAST_STEP ? leave() : go(step + 1))}
+		>
+			{#snippet children(current)}
+				{#if current === 0}
+					<ProfileStep />
+				{:else if current === 1}
+					<SocialStep />
+				{:else if current === 2}
+					<KeysStep />
+				{:else}
+					<FinishStep />
+				{/if}
+			{/snippet}
+		</WelcomeCard>
+
+		{#if step < LAST_STEP}
+			<div class="mt-4 flex justify-center">
+				<Button variant="ghost" icon={X} onclick={leave}>Skip onboarding</Button>
+			</div>
+		{/if}
+	</main>
+</div>
-- 
2.51.2