From 7137c3cd52e483e9fda923de56bab442e92ae1c7 Mon Sep 17 00:00:00 2001
From: Jake Howell <jake@hwll.me>
Date: Fri, 31 Jul 2026 00:11:10 +0000
Subject: [PATCH 1/6] refactor(site): demui `<IconField />`

---
 .../IconField/IconField.stories.tsx           |  31 ++-
 site/src/components/IconField/IconField.tsx   | 198 ++++++++++++------
 .../components/IconPickerField.tsx            |  92 +-------
 3 files changed, 171 insertions(+), 150 deletions(-)

diff --git a/site/src/components/IconField/IconField.stories.tsx b/site/src/components/IconField/IconField.stories.tsx
index 698c1d6d356..f9412f25968 100644
--- a/site/src/components/IconField/IconField.stories.tsx
+++ b/site/src/components/IconField/IconField.stories.tsx
@@ -1,12 +1,13 @@
 import type { Meta, StoryObj } from "@storybook/react-vite";
-import { action } from "storybook/actions";
+import { expect, fn, screen, userEvent, within } from "storybook/test";
 import { IconField } from "./IconField";
 
 const meta: Meta<typeof IconField> = {
 	title: "components/IconField",
 	component: IconField,
 	args: {
-		onPickEmoji: action("onPickEmoji"),
+		onPickEmoji: fn(),
+		onChange: fn(),
 	},
 };
 
@@ -26,3 +27,29 @@ export const IconSelected: Story = {
 		value: "/icon/fedora.svg",
 	},
 };
+
+export const WithHelperText: Story = {
+	args: {
+		helperText: "Paste an image URL or pick an emoji.",
+	},
+};
+
+export const WithError: Story = {
+	args: {
+		error: true,
+		helperText: "Icon URL is too long.",
+		value: "https://example.com/very-long-icon-url.png",
+	},
+};
+
+export const OpenPicker: Story = {
+	play: async ({ canvasElement }) => {
+		const canvas = within(canvasElement);
+		const button = canvas.getByRole("button", {
+			name: "Pick an emoji or icon",
+		});
+		await userEvent.click(button);
+		await expect(button).toHaveAttribute("aria-expanded", "true");
+		await expect(await screen.findByText("Smileys & People")).toBeVisible();
+	},
+};
diff --git a/site/src/components/IconField/IconField.tsx b/site/src/components/IconField/IconField.tsx
index be48b8449ba..0e26022bc45 100644
--- a/site/src/components/IconField/IconField.tsx
+++ b/site/src/components/IconField/IconField.tsx
@@ -1,95 +1,159 @@
-import { css, Global, useTheme } from "@emotion/react";
-import InputAdornment from "@mui/material/InputAdornment";
-import TextField, { type TextFieldProps } from "@mui/material/TextField";
-import { type FC, lazy, Suspense, useState } from "react";
-import { ChevronDownIcon } from "#/components/AnimatedIcons/ChevronDown";
+import {
+	type ChangeEventHandler,
+	type FC,
+	type FocusEventHandler,
+	lazy,
+	type ReactNode,
+	Suspense,
+	useId,
+	useState,
+} from "react";
+import { ChevronDownIcon as AnimatedChevronDownIcon } from "#/components/AnimatedIcons/ChevronDown";
 import { Button } from "#/components/Button/Button";
 import { ExternalImage } from "#/components/ExternalImage/ExternalImage";
+import {
+	InputGroup,
+	InputGroupAddon,
+	InputGroupInput,
+} from "#/components/InputGroup/InputGroup";
+import { Label } from "#/components/Label/Label";
 import { Loader } from "#/components/Loader/Loader";
 import {
 	Popover,
 	PopoverContent,
 	PopoverTrigger,
 } from "#/components/Popover/Popover";
+import { cn } from "#/utils/cn";
+
+const EmojiPicker = lazy(() => import("./EmojiPicker"));
 
-type IconFieldProps = TextFieldProps & {
+type IconFieldProps = {
+	id?: string;
+	name?: string;
+	value?: string | number;
+	onChange?: ChangeEventHandler<HTMLInputElement>;
+	onBlur?: FocusEventHandler<HTMLInputElement>;
+	label?: ReactNode;
+	error?: boolean;
+	helperText?: ReactNode;
+	disabled?: boolean;
+	placeholder?: string;
 	onPickEmoji: (value: string) => void;
+	/** Accepted for call-site compatibility with former MUI TextField usage. */
+	fullWidth?: boolean;
 };
 
-const EmojiPicker = lazy(() => import("./EmojiPicker"));
-
 export const IconField: FC<IconFieldProps> = ({
+	id: idProp,
+	name,
+	value,
+	onChange,
+	onBlur,
+	label = "Icon",
+	error,
+	helperText,
+	disabled,
+	placeholder,
 	onPickEmoji,
-	...textFieldProps
+	fullWidth: _fullWidth,
 }) => {
-	if (
-		typeof textFieldProps.value !== "string" &&
-		typeof textFieldProps.value !== "undefined"
-	) {
-		throw new Error(`Invalid icon value "${typeof textFieldProps.value}"`);
+	if (typeof value !== "string" && typeof value !== "undefined") {
+		throw new Error(`Invalid icon value "${typeof value}"`);
 	}
 
-	const theme = useTheme();
-	const hasIcon = textFieldProps.value && textFieldProps.value !== "";
+	const generatedId = useId();
+	const id = idProp ?? generatedId;
+	const errorId = `${id}-error`;
+	const helperId = `${id}-helper`;
 	const [open, setOpen] = useState(false);
+	const stringValue = value ?? "";
+	const hasIcon = stringValue !== "";
 
 	return (
-		<div className="flex items-center gap-2">
-			<TextField
-				fullWidth
-				label="Icon"
-				{...textFieldProps}
-				InputProps={{
-					endAdornment: hasIcon ? (
-						<InputAdornment
-							position="end"
-							className="size-6 flex items-center justify-center [&_img]:max-w-full [&_img]:object-contain"
-						>
+		<div className="flex w-full flex-col gap-2">
+			{label ? (
+				<Label htmlFor={id} className="text-sm">
+					{label}
+				</Label>
+			) : null}
+			<InputGroup>
+				<InputGroupInput
+					id={id}
+					name={name}
+					value={stringValue}
+					onChange={onChange}
+					onBlur={onBlur}
+					placeholder={placeholder}
+					disabled={disabled}
+					aria-invalid={error}
+					aria-describedby={
+						helperText ? (error ? errorId : helperId) : undefined
+					}
+					className="min-w-0 placeholder:text-content-disabled"
+					spellCheck={false}
+				/>
+				<InputGroupAddon align="inline-end" className="gap-1.5">
+					{hasIcon && (
+						<span className="flex size-5 items-center justify-center [&_img]:max-w-full [&_img]:object-contain">
 							<ExternalImage
 								alt=""
-								src={textFieldProps.value}
-								// This prevent browser to display the ugly error icon if the
-								// image path is wrong or user didn't finish typing the url
-								onError={(e) => {
-									e.currentTarget.style.display = "none";
+								src={stringValue}
+								onError={(event) => {
+									event.currentTarget.style.display = "none";
 								}}
-								onLoad={(e) => {
-									e.currentTarget.style.display = "inline";
+								onLoad={(event) => {
+									event.currentTarget.style.display = "inline";
 								}}
 							/>
-						</InputAdornment>
-					) : undefined,
-				}}
-			/>
-
-			<Global
-				styles={css`
-					em-emoji-picker {
-						--rgb-background: ${theme.palette.background.paper};
-						--rgb-input: ${theme.palette.primary.main};
-						--rgb-color: ${theme.palette.text.primary};
-					}
-				`}
-			/>
-			<Popover open={open} onOpenChange={setOpen}>
-				<PopoverTrigger asChild>
-					<Button variant="outline" size="lg" className="group flex-shrink-0">
-						Emoji
-						<ChevronDownIcon />
-					</Button>
-				</PopoverTrigger>
-				<PopoverContent id="emoji" side="bottom" align="end" className="w-min">
-					<Suspense fallback={<Loader />}>
-						<EmojiPicker
-							onEmojiSelect={(emoji) => {
-								const value = emoji.src ?? `/emojis/${emoji.unified}.png`;
-								onPickEmoji(value);
-								setOpen(false);
-							}}
-						/>
-					</Suspense>
-				</PopoverContent>
-			</Popover>
+						</span>
+					)}
+					<Popover open={open} onOpenChange={setOpen}>
+						<PopoverTrigger asChild>
+							<Button
+								type="button"
+								variant="subtle"
+								size="sm"
+								className="group h-7 gap-1"
+								disabled={disabled}
+								aria-label="Pick an emoji or icon"
+							>
+								Emoji
+								<AnimatedChevronDownIcon />
+							</Button>
+						</PopoverTrigger>
+						<PopoverContent
+							side="bottom"
+							align="end"
+							className="w-min"
+							// The popover is portaled in the DOM but still a React child of
+							// InputGroupAddon, whose click handler focuses the text input.
+							// Stop clicks here so the emoji picker keeps focus.
+							onClick={(event) => event.stopPropagation()}
+						>
+							<Suspense fallback={<Loader />}>
+								<EmojiPicker
+									onEmojiSelect={(emoji) => {
+										const picked = emoji.src ?? `/emojis/${emoji.unified}.png`;
+										onPickEmoji(picked);
+										setOpen(false);
+									}}
+								/>
+							</Suspense>
+						</PopoverContent>
+					</Popover>
+				</InputGroupAddon>
+			</InputGroup>
+			{helperText ? (
+				<span
+					id={error ? errorId : helperId}
+					className={cn(
+						"text-xs",
+						error ? "text-content-destructive" : "text-content-secondary",
+					)}
+				>
+					{helperText}
+				</span>
+			) : null}
 
 			{/*
       - This component takes a long time to load (easily several seconds), so we
diff --git a/site/src/pages/AISettingsPage/MCPServersPage/components/IconPickerField.tsx b/site/src/pages/AISettingsPage/MCPServersPage/components/IconPickerField.tsx
index 8f50854f2c0..b961d3712c2 100644
--- a/site/src/pages/AISettingsPage/MCPServersPage/components/IconPickerField.tsx
+++ b/site/src/pages/AISettingsPage/MCPServersPage/components/IconPickerField.tsx
@@ -1,20 +1,5 @@
-import { type FC, lazy, Suspense, useState } from "react";
-import { ChevronDownIcon as AnimatedChevronDownIcon } from "#/components/AnimatedIcons/ChevronDown";
-import { Button } from "#/components/Button/Button";
-import { ExternalImage } from "#/components/ExternalImage/ExternalImage";
-import {
-	InputGroup,
-	InputGroupAddon,
-	InputGroupInput,
-} from "#/components/InputGroup/InputGroup";
-import { Loader } from "#/components/Loader/Loader";
-import {
-	Popover,
-	PopoverContent,
-	PopoverTrigger,
-} from "#/components/Popover/Popover";
-
-const EmojiPicker = lazy(() => import("#/components/IconField/EmojiPicker"));
+import type { FC } from "react";
+import { IconField } from "#/components/IconField/IconField";
 
 interface IconPickerFieldProps {
 	id?: string;
@@ -31,70 +16,15 @@ export const IconPickerField: FC<IconPickerFieldProps> = ({
 	disabled,
 	onChange,
 }) => {
-	const [open, setOpen] = useState(false);
-	const hasIcon = value !== "";
-
 	return (
-		<InputGroup>
-			<InputGroupInput
-				id={id}
-				value={value}
-				onChange={(event) => onChange(event.target.value)}
-				placeholder={placeholder}
-				disabled={disabled}
-				className="min-w-0 placeholder:text-content-disabled"
-				spellCheck={false}
-			/>
-			<InputGroupAddon align="inline-end" className="gap-1.5">
-				{hasIcon && (
-					<span className="flex size-5 items-center justify-center [&_img]:max-w-full [&_img]:object-contain">
-						<ExternalImage
-							alt=""
-							src={value}
-							onError={(event) => {
-								event.currentTarget.style.display = "none";
-							}}
-							onLoad={(event) => {
-								event.currentTarget.style.display = "inline";
-							}}
-						/>
-					</span>
-				)}
-				<Popover open={open} onOpenChange={setOpen}>
-					<PopoverTrigger asChild>
-						<Button
-							type="button"
-							variant="subtle"
-							size="sm"
-							className="group h-7 gap-1"
-							disabled={disabled}
-							aria-label="Pick an emoji or icon"
-						>
-							Emoji
-							<AnimatedChevronDownIcon />
-						</Button>
-					</PopoverTrigger>
-					<PopoverContent
-						side="bottom"
-						align="end"
-						className="w-min"
-						// The popover is portaled in the DOM but still a React child of
-						// InputGroupAddon, whose click handler focuses the text input.
-						// Stop clicks here so the emoji picker keeps focus.
-						onClick={(event) => event.stopPropagation()}
-					>
-						<Suspense fallback={<Loader />}>
-							<EmojiPicker
-								onEmojiSelect={(emoji) => {
-									const picked = emoji.src ?? `/emojis/${emoji.unified}.png`;
-									onChange(picked);
-									setOpen(false);
-								}}
-							/>
-						</Suspense>
-					</PopoverContent>
-				</Popover>
-			</InputGroupAddon>
-		</InputGroup>
+		<IconField
+			id={id}
+			value={value}
+			placeholder={placeholder}
+			disabled={disabled}
+			label={null}
+			onChange={(event) => onChange(event.target.value)}
+			onPickEmoji={onChange}
+		/>
 	);
 };

From 273607676bdfcc88d9ff06fc1649e76a5c7e0119 Mon Sep 17 00:00:00 2001
From: Jake Howell <jake@hwll.me>
Date: Fri, 31 Jul 2026 00:16:21 +0000
Subject: [PATCH 2/6] fix: component props

---
 site/src/components/IconField/IconField.tsx | 25 +++++----------------
 1 file changed, 6 insertions(+), 19 deletions(-)

diff --git a/site/src/components/IconField/IconField.tsx b/site/src/components/IconField/IconField.tsx
index 0e26022bc45..ffb43703915 100644
--- a/site/src/components/IconField/IconField.tsx
+++ b/site/src/components/IconField/IconField.tsx
@@ -1,7 +1,6 @@
 import {
-	type ChangeEventHandler,
+	type ComponentPropsWithRef,
 	type FC,
-	type FocusEventHandler,
 	lazy,
 	type ReactNode,
 	Suspense,
@@ -27,17 +26,10 @@ import { cn } from "#/utils/cn";
 
 const EmojiPicker = lazy(() => import("./EmojiPicker"));
 
-type IconFieldProps = {
-	id?: string;
-	name?: string;
-	value?: string | number;
-	onChange?: ChangeEventHandler<HTMLInputElement>;
-	onBlur?: FocusEventHandler<HTMLInputElement>;
+type IconFieldProps = Omit<ComponentPropsWithRef<"input">, "type"> & {
 	label?: ReactNode;
 	error?: boolean;
 	helperText?: ReactNode;
-	disabled?: boolean;
-	placeholder?: string;
 	onPickEmoji: (value: string) => void;
 	/** Accepted for call-site compatibility with former MUI TextField usage. */
 	fullWidth?: boolean;
@@ -45,17 +37,15 @@ type IconFieldProps = {
 
 export const IconField: FC<IconFieldProps> = ({
 	id: idProp,
-	name,
 	value,
-	onChange,
-	onBlur,
 	label = "Icon",
 	error,
 	helperText,
 	disabled,
-	placeholder,
+	className,
 	onPickEmoji,
 	fullWidth: _fullWidth,
+	...inputProps
 }) => {
 	if (typeof value !== "string" && typeof value !== "undefined") {
 		throw new Error(`Invalid icon value "${typeof value}"`);
@@ -78,18 +68,15 @@ export const IconField: FC<IconFieldProps> = ({
 			) : null}
 			<InputGroup>
 				<InputGroupInput
+					{...inputProps}
 					id={id}
-					name={name}
 					value={stringValue}
-					onChange={onChange}
-					onBlur={onBlur}
-					placeholder={placeholder}
 					disabled={disabled}
 					aria-invalid={error}
 					aria-describedby={
 						helperText ? (error ? errorId : helperId) : undefined
 					}
-					className="min-w-0 placeholder:text-content-disabled"
+					className={cn("min-w-0 placeholder:text-content-disabled", className)}
 					spellCheck={false}
 				/>
 				<InputGroupAddon align="inline-end" className="gap-1.5">

From 9cb5dfd9d20edeed9676c61e8e00c7b78bd62949 Mon Sep 17 00:00:00 2001
From: Jake Howell <jake@hwll.me>
Date: Fri, 31 Jul 2026 00:54:57 +0000
Subject: [PATCH 3/6] refactor(site): redesign `<AppearanceSettingsPage />`

---
 .../AnnouncementBannerDialog.tsx              | 235 ++++++++++--------
 .../AnnouncementBannerItem.tsx                |  16 +-
 .../AnnouncementBannerSettings.tsx            | 187 +++++++-------
 .../AppearanceSettingsPageView.tsx            | 186 +++++++-------
 4 files changed, 340 insertions(+), 284 deletions(-)

diff --git a/site/src/pages/DeploymentSettingsPage/AppearanceSettingsPage/AnnouncementBannerDialog.tsx b/site/src/pages/DeploymentSettingsPage/AppearanceSettingsPage/AnnouncementBannerDialog.tsx
index 0b86ab3a28b..f6fccfd7b0d 100644
--- a/site/src/pages/DeploymentSettingsPage/AppearanceSettingsPage/AnnouncementBannerDialog.tsx
+++ b/site/src/pages/DeploymentSettingsPage/AppearanceSettingsPage/AnnouncementBannerDialog.tsx
@@ -1,13 +1,16 @@
 import { type Interpolation, type Theme, useTheme } from "@emotion/react";
 import DialogActions from "@mui/material/DialogActions";
-import TextField from "@mui/material/TextField";
 import { useFormik } from "formik";
 import { type FC, useState } from "react";
 import { SliderPicker, TwitterPicker } from "react-color";
+import { createPortal } from "react-dom";
 import type { BannerConfig } from "#/api/typesGenerated";
 import { Button } from "#/components/Button/Button";
 import { Dialog, DialogActionButtons } from "#/components/Dialogs/Dialog";
+import { Label } from "#/components/Label/Label";
+import { Textarea } from "#/components/Textarea/Textarea";
 import { AnnouncementBannerView } from "#/modules/dashboard/AnnouncementBanners/AnnouncementBannerView";
+import { cn } from "#/utils/cn";
 import { getFormHelpers } from "#/utils/formUtils";
 
 interface AnnouncementBannerDialogProps {
@@ -22,6 +25,7 @@ export const AnnouncementBannerDialog: FC<AnnouncementBannerDialogProps> = ({
 	onUpdate,
 }) => {
 	const theme = useTheme();
+	const isCreating = !banner.message;
 
 	const bannerForm = useFormik<{
 		message: string;
@@ -33,115 +37,152 @@ export const AnnouncementBannerDialog: FC<AnnouncementBannerDialogProps> = ({
 		},
 		onSubmit: (banner) => onUpdate(banner),
 	});
-	const bannerFieldHelpers = getFormHelpers(bannerForm);
+	const getFieldHelpers = getFormHelpers(bannerForm);
+	const messageField = getFieldHelpers("message", {
+		helperText: "Markdown bold, italics, and links are supported.",
+	});
+	const messageHelperId = `${messageField.id}-helper`;
+	const messageErrorId = `${messageField.id}-error`;
 
 	const [showHuePicker, setShowHuePicker] = useState(false);
+	const previewMessage = bannerForm.values.message.trim();
 
 	return (
-		<Dialog css={styles.dialogWrapper} open onClose={onCancel}>
-			{/* Banner preview */}
-			<div className="fixed top-0 left-0 right-0">
-				<AnnouncementBannerView
-					message={bannerForm.values.message}
-					backgroundColor={bannerForm.values.background_color}
-				/>
-			</div>
+		<>
+			{/* Portal so fixed positioning escapes the dialog transform containing block. */}
+			{createPortal(
+				<div className="pointer-events-none fixed top-0 right-0 left-0 z-[1400]">
+					<AnnouncementBannerView
+						message={bannerForm.values.message}
+						backgroundColor={bannerForm.values.background_color}
+					/>
+				</div>,
+				document.body,
+			)}
 
-			<div css={styles.dialogContent}>
-				<h3 css={styles.dialogTitle}>Announcement banner</h3>
-				<div className="flex flex-col gap-4">
-					<div>
-						<h4 css={styles.settingName}>Message</h4>
-						<TextField
-							{...bannerFieldHelpers("message", {
-								helperText: "Markdown bold, italics, and links are supported.",
-							})}
-							fullWidth
-							multiline
-							inputProps={{
-								"aria-label": "Message",
-								placeholder: "Enter a message for the banner",
-							}}
-						/>
-					</div>
-					<div>
-						<h4 css={styles.settingName}>Background color</h4>
-						<div className="flex flex-col gap-4">
-							{showHuePicker ? (
-								<SliderPicker
-									color={bannerForm.values.background_color}
-									onChange={async (color) => {
-										await bannerForm.setFieldValue(
-											"background_color",
-											color.hex,
-										);
-									}}
-								/>
+			<Dialog css={styles.dialogWrapper} open onClose={onCancel}>
+				<div css={styles.dialogContent}>
+					<h3 css={styles.dialogTitle}>Announcement banner</h3>
+					<div className="flex flex-col gap-4">
+						<div className="flex flex-col gap-2">
+							<Label htmlFor={messageField.id}>Message</Label>
+							<Textarea
+								id={messageField.id}
+								name={messageField.name}
+								value={messageField.value}
+								onChange={messageField.onChange}
+								onBlur={messageField.onBlur}
+								rows={3}
+								placeholder="Enter a message for the banner"
+								aria-invalid={messageField.error}
+								aria-describedby={
+									messageField.error
+										? messageErrorId
+										: messageField.helperText
+											? messageHelperId
+											: undefined
+								}
+								className={cn(
+									messageField.error && "border-border-destructive",
+								)}
+							/>
+							{messageField.error ? (
+								<span
+									id={messageErrorId}
+									className="text-xs text-content-destructive"
+								>
+									{messageField.helperText}
+								</span>
 							) : (
-								<TwitterPicker
-									color={bannerForm.values.background_color}
-									onChange={async (color) => {
-										await bannerForm.setFieldValue(
-											"background_color",
-											color.hex,
-										);
-									}}
-									triangle="hide"
-									colors={[
-										"#8b5cf6",
-										"#d94a5d",
-										"#f78da7",
-										"#d65d0f",
-										"#ff6900",
-										"#fcb900",
-										"#0693e3",
+								messageField.helperText && (
+									<span
+										id={messageHelperId}
+										className="text-xs text-content-secondary"
+									>
+										{messageField.helperText}
+									</span>
+								)
+							)}
+						</div>
+						<div>
+							<h4 css={styles.settingName}>Background color</h4>
+							<div className="flex flex-col gap-4">
+								{showHuePicker ? (
+									<SliderPicker
+										color={bannerForm.values.background_color}
+										onChange={async (color) => {
+											await bannerForm.setFieldValue(
+												"background_color",
+												color.hex,
+											);
+										}}
+									/>
+								) : (
+									<TwitterPicker
+										color={bannerForm.values.background_color}
+										onChange={async (color) => {
+											await bannerForm.setFieldValue(
+												"background_color",
+												color.hex,
+											);
+										}}
+										triangle="hide"
+										colors={[
+											"#8b5cf6",
+											"#d94a5d",
+											"#f78da7",
+											"#d65d0f",
+											"#ff6900",
+											"#fcb900",
+											"#0693e3",
 
-										"#8ed1fc",
-										"#4cd473",
-										"#abb8c3",
-									]}
-									styles={{
-										default: {
-											input: {
-												color: "white",
-												backgroundColor: theme.palette.background.default,
+											"#8ed1fc",
+											"#4cd473",
+											"#abb8c3",
+										]}
+										styles={{
+											default: {
+												input: {
+													color: "white",
+													backgroundColor: theme.palette.background.default,
+												},
+												body: {
+													backgroundColor: "transparent",
+													color: "white",
+													padding: 0,
+												},
+												card: {
+													backgroundColor: "transparent",
+												},
 											},
-											body: {
-												backgroundColor: "transparent",
-												color: "white",
-												padding: 0,
-											},
-											card: {
-												backgroundColor: "transparent",
-											},
-										},
-									}}
-								/>
-							)}
-							<div>
-								<Button
-									variant="outline"
-									onClick={() => setShowHuePicker((it) => !it)}
-								>
-									Show {showHuePicker ? "palette" : "slider"}
-								</Button>
+										}}
+									/>
+								)}
+								<div>
+									<Button
+										variant="outline"
+										onClick={() => setShowHuePicker((it) => !it)}
+									>
+										Show {showHuePicker ? "palette" : "slider"}
+									</Button>
+								</div>
 							</div>
 						</div>
 					</div>
 				</div>
-			</div>
 
-			<DialogActions>
-				<DialogActionButtons
-					cancelText="Cancel"
-					confirmLoading={bannerForm.isSubmitting}
-					confirmText="Update"
-					disabled={bannerForm.isSubmitting}
-					onCancel={onCancel}
-					onConfirm={bannerForm.handleSubmit}
-				/>
-			</DialogActions>
-		</Dialog>
+				<DialogActions>
+					<DialogActionButtons
+						cancelText="Cancel"
+						confirmLoading={bannerForm.isSubmitting}
+						confirmText={isCreating ? "Create" : "Update"}
+						disabled={bannerForm.isSubmitting || previewMessage === ""}
+						onCancel={onCancel}
+						onConfirm={bannerForm.handleSubmit}
+					/>
+				</DialogActions>
+			</Dialog>
+		</>
 	);
 };
 
diff --git a/site/src/pages/DeploymentSettingsPage/AppearanceSettingsPage/AnnouncementBannerItem.tsx b/site/src/pages/DeploymentSettingsPage/AppearanceSettingsPage/AnnouncementBannerItem.tsx
index fd746b2c0bf..666af6c72d5 100644
--- a/site/src/pages/DeploymentSettingsPage/AppearanceSettingsPage/AnnouncementBannerItem.tsx
+++ b/site/src/pages/DeploymentSettingsPage/AppearanceSettingsPage/AnnouncementBannerItem.tsx
@@ -1,5 +1,4 @@
-import Checkbox from "@mui/material/Checkbox";
-import { EllipsisVerticalIcon } from "lucide-react";
+import { EllipsisVerticalIcon, PencilIcon, TrashIcon } from "lucide-react";
 import type { FC } from "react";
 import type { BannerConfig } from "#/api/typesGenerated";
 import { Button } from "#/components/Button/Button";
@@ -9,6 +8,7 @@ import {
 	DropdownMenuItem,
 	DropdownMenuTrigger,
 } from "#/components/DropdownMenu/DropdownMenu";
+import { Switch } from "#/components/Switch/Switch";
 import { TableCell, TableRow } from "#/components/Table/Table";
 
 interface AnnouncementBannerItemProps {
@@ -30,11 +30,13 @@ export const AnnouncementBannerItem: FC<AnnouncementBannerItemProps> = ({
 }) => {
 	return (
 		<TableRow>
-			<TableCell>
-				<Checkbox
-					size="small"
+			<TableCell className="align-middle pl-5">
+				<Switch
 					checked={enabled}
-					onClick={() => void onUpdate({ enabled: !enabled })}
+					aria-label="Enabled"
+					onCheckedChange={(checked) => {
+						void onUpdate({ enabled: checked });
+					}}
 				/>
 			</TableCell>
 
@@ -56,12 +58,14 @@ export const AnnouncementBannerItem: FC<AnnouncementBannerItemProps> = ({
 					</DropdownMenuTrigger>
 					<DropdownMenuContent align="end">
 						<DropdownMenuItem onClick={() => onEdit()}>
+							<PencilIcon className="size-icon-xs" />
 							Edit&hellip;
 						</DropdownMenuItem>
 						<DropdownMenuItem
 							className="text-content-destructive focus:text-content-destructive"
 							onClick={() => onDelete()}
 						>
+							<TrashIcon className="size-icon-xs" />
 							Delete&hellip;
 						</DropdownMenuItem>
 					</DropdownMenuContent>
diff --git a/site/src/pages/DeploymentSettingsPage/AppearanceSettingsPage/AnnouncementBannerSettings.tsx b/site/src/pages/DeploymentSettingsPage/AppearanceSettingsPage/AnnouncementBannerSettings.tsx
index f3126a44e0a..1bcda4d667e 100644
--- a/site/src/pages/DeploymentSettingsPage/AppearanceSettingsPage/AnnouncementBannerSettings.tsx
+++ b/site/src/pages/DeploymentSettingsPage/AppearanceSettingsPage/AnnouncementBannerSettings.tsx
@@ -3,39 +3,63 @@ import { type FC, useState } from "react";
 import type { BannerConfig } from "#/api/typesGenerated";
 import { Button } from "#/components/Button/Button";
 import { ConfirmDialog } from "#/components/Dialogs/ConfirmDialog/ConfirmDialog";
-import { EmptyState } from "#/components/EmptyState/EmptyState";
 import { Link } from "#/components/Link/Link";
+import {
+	SettingsHeader,
+	SettingsHeaderDescription,
+	SettingsHeaderTitle,
+} from "#/components/SettingsHeader/SettingsHeader";
 import {
 	Table,
 	TableBody,
-	TableCell,
 	TableHead,
 	TableHeader,
 	TableRow,
 } from "#/components/Table/Table";
+import { TableEmpty } from "#/components/TableEmpty/TableEmpty";
 import { AnnouncementBannerDialog } from "./AnnouncementBannerDialog";
 import { AnnouncementBannerItem } from "./AnnouncementBannerItem";
 
+const DEFAULT_BANNER: BannerConfig = {
+	enabled: true,
+	message: "",
+	background_color: "#ABB8C3",
+};
+
+type NewBannerButtonProps = {
+	onClick: () => void;
+};
+
+const NewBannerButton: FC<NewBannerButtonProps> = ({ onClick }) => (
+	<Button onClick={onClick} variant="outline">
+		<PlusIcon />
+		New announcement
+	</Button>
+);
+
 interface AnnouncementBannersettingsProps {
 	isEntitled: boolean;
 	announcementBanners: readonly BannerConfig[];
 	onSubmit: (banners: readonly BannerConfig[]) => Promise<void>;
 }
 
+type EditingBanner = {
+	/** `null` means creating a new banner. */
+	index: number | null;
+	banner: BannerConfig;
+};
+
 export const AnnouncementBannerSettings: FC<
 	AnnouncementBannersettingsProps
 > = ({ isEntitled, announcementBanners, onSubmit }) => {
 	const [banners, setBanners] = useState(announcementBanners);
-	const [editingBannerId, setEditingBannerId] = useState<number | null>(null);
+	const [editingBanner, setEditingBanner] = useState<EditingBanner | null>(
+		null,
+	);
 	const [deletingBannerId, setDeletingBannerId] = useState<number | null>(null);
 
-	const addBanner = () => {
-		setBanners([
-			...banners,
-			{ enabled: true, message: "", background_color: "#ABB8C3" },
-		]);
-		setEditingBannerId(banners.length);
-	};
+	const openCreateDialog = () =>
+		setEditingBanner({ index: null, banner: DEFAULT_BANNER });
 
 	const updateBanner = (i: number, banner: Partial<BannerConfig>) => {
 		const newBanners = [...banners];
@@ -51,95 +75,90 @@ export const AnnouncementBannerSettings: FC<
 		return newBanners;
 	};
 
-	const editingBanner = editingBannerId !== null && banners[editingBannerId];
 	const deletingBanner = deletingBannerId !== null && banners[deletingBannerId];
 
-	// If we're not editing a new banner, remove all empty banners. This makes canceling the
-	// "new" dialog more intuitive, by not persisting an empty banner.
-	if (editingBannerId === null && banners.some((banner) => !banner.message)) {
-		setBanners(banners.filter((banner) => banner.message));
-	}
-
 	return (
 		<>
-			<div className="mt-8 overflow-hidden rounded-lg border border-solid border-border">
-				<div className="p-6">
-					<div className="flex items-center justify-between gap-4">
-						<h3 className="m-0 text-xl font-semibold">Announcement Banners</h3>
-						<Button
-							disabled={!isEntitled}
-							onClick={() => addBanner()}
-							variant="outline"
-						>
-							<PlusIcon />
-							New
-						</Button>
-					</div>
-					<div className="mt-2 text-sm text-content-secondary">
+			<div>
+				<SettingsHeader
+					actions={
+						isEntitled ? (
+							<NewBannerButton onClick={openCreateDialog} />
+						) : undefined
+					}
+				>
+					<SettingsHeaderTitle hierarchy="secondary" level="h2">
+						Announcement Banners
+					</SettingsHeaderTitle>
+					<SettingsHeaderDescription>
 						Display message banners to all users.
-					</div>
-
-					<div className="pt-4 text-sm">
-						<Table>
-							<TableHeader>
-								<TableRow>
-									<TableHead className="w-[1%]">Enabled</TableHead>
-									<TableHead>Message</TableHead>
-									<TableHead className="w-[2%]">Color</TableHead>
-									<TableHead className="w-[1%]" />
-								</TableRow>
-							</TableHeader>
-							<TableBody>
-								{!isEntitled || banners.length < 1 ? (
-									<TableCell colSpan={999}>
-										<EmptyState
-											className="min-h-[160px]"
-											message="No announcement banners"
-										/>
-									</TableCell>
-								) : (
-									banners.map((banner, i) => (
-										<AnnouncementBannerItem
-											key={banner.message}
-											enabled={banner.enabled && Boolean(banner.message)}
-											backgroundColor={banner.background_color}
-											message={banner.message}
-											onEdit={() => setEditingBannerId(i)}
-											onUpdate={async (banner) => {
-												const newBanners = updateBanner(i, banner);
-												await onSubmit(newBanners);
-											}}
-											onDelete={() => setDeletingBannerId(i)}
-										/>
-									))
-								)}
-							</TableBody>
-						</Table>
-					</div>
-				</div>
-
-				{!isEntitled && (
-					<footer className="bg-surface-secondary px-6 py-4 text-sm">
-						<div className="text-content-secondary">
-							<p>
+						{!isEntitled && (
+							<>
+								{" "}
 								Your license does not include Service Banners.{" "}
 								<Link href="mailto:sales@coder.com" showExternalIcon={false}>
 									Contact sales
 								</Link>{" "}
 								to learn more.
-							</p>
-						</div>
-					</footer>
-				)}
+							</>
+						)}
+					</SettingsHeaderDescription>
+				</SettingsHeader>
+
+				<Table aria-label="Announcement banners">
+					<TableHeader>
+						<TableRow>
+							<TableHead className="w-[1%] pl-5">Enabled</TableHead>
+							<TableHead>Message</TableHead>
+							<TableHead className="w-[2%]">Color</TableHead>
+							<TableHead className="w-[1%]" />
+						</TableRow>
+					</TableHeader>
+					<TableBody>
+						{!isEntitled || banners.length < 1 ? (
+							<TableEmpty
+								message="No announcement banners"
+								description="Create a banner to display a message to all users."
+								cta={
+									isEntitled ? (
+										<NewBannerButton onClick={openCreateDialog} />
+									) : undefined
+								}
+							/>
+						) : (
+							banners.map((banner, i) => (
+								<AnnouncementBannerItem
+									key={banner.message}
+									enabled={banner.enabled && Boolean(banner.message)}
+									backgroundColor={banner.background_color}
+									message={banner.message}
+									onEdit={() => setEditingBanner({ index: i, banner })}
+									onUpdate={async (banner) => {
+										const newBanners = updateBanner(i, banner);
+										await onSubmit(newBanners);
+									}}
+									onDelete={() => setDeletingBannerId(i)}
+								/>
+							))
+						)}
+					</TableBody>
+				</Table>
 			</div>
 
 			{editingBanner && (
 				<AnnouncementBannerDialog
-					banner={editingBanner}
-					onCancel={() => setEditingBannerId(null)}
+					banner={editingBanner.banner}
+					onCancel={() => setEditingBanner(null)}
 					onUpdate={async (banner) => {
-						const newBanners = updateBanner(editingBannerId, banner);
-						setEditingBannerId(null);
+						const nextBanner = { ...editingBanner.banner, ...banner };
+						const newBanners =
+							editingBanner.index === null
+								? [...banners, nextBanner]
+								: banners.map((existing, i) =>
+										i === editingBanner.index ? nextBanner : existing,
+									);
+						setBanners(newBanners);
+						setEditingBanner(null);
 						await onSubmit(newBanners);
 					}}
 				/>
diff --git a/site/src/pages/DeploymentSettingsPage/AppearanceSettingsPage/AppearanceSettingsPageView.tsx b/site/src/pages/DeploymentSettingsPage/AppearanceSettingsPage/AppearanceSettingsPageView.tsx
index 74acf048df3..ee0084770d9 100644
--- a/site/src/pages/DeploymentSettingsPage/AppearanceSettingsPage/AppearanceSettingsPageView.tsx
+++ b/site/src/pages/DeploymentSettingsPage/AppearanceSettingsPage/AppearanceSettingsPageView.tsx
@@ -7,18 +7,21 @@ import {
 	PremiumBadge,
 } from "#/components/Badges/Badges";
 import { Button } from "#/components/Button/Button";
-import { Input } from "#/components/Input/Input";
 import {
-	InputGroup,
-	InputGroupAddon,
-	InputGroupInput,
-} from "#/components/InputGroup/InputGroup";
+	FormFields,
+	FormFooter,
+	FormSection,
+	HorizontalForm,
+} from "#/components/Form/Form";
+import { FormField } from "#/components/FormField/FormField";
+import { IconField } from "#/components/IconField/IconField";
 import { PopoverPaywall } from "#/components/Paywall/PopoverPaywall";
 import {
 	SettingsHeader,
 	SettingsHeaderDescription,
 	SettingsHeaderTitle,
 } from "#/components/SettingsHeader/SettingsHeader";
+import { Spinner } from "#/components/Spinner/Spinner";
 import {
 	Tooltip,
 	TooltipContent,
@@ -26,7 +29,6 @@ import {
 } from "#/components/Tooltip/Tooltip";
 import { docs } from "#/utils/docs";
 import { getFormHelpers } from "#/utils/formUtils";
-import { Fieldset } from "../Fieldset";
 import { AnnouncementBannerSettings } from "./AnnouncementBannerSettings";
 
 type AppearanceSettingsPageViewProps = {
@@ -41,111 +43,101 @@ type AppearanceSettingsPageViewProps = {
 export const AppearanceSettingsPageView: FC<
 	AppearanceSettingsPageViewProps
 > = ({ appearance, isEntitled, isPremium, onSaveAppearance }) => {
-	const applicationNameForm = useFormik<{
+	const form = useFormik<{
 		application_name: string;
-	}>({
-		initialValues: {
-			application_name: appearance.application_name,
-		},
-		onSubmit: (values) => onSaveAppearance(values),
-	});
-	const applicationNameFieldHelpers = getFormHelpers(applicationNameForm);
-
-	const logoForm = useFormik<{
 		logo_url: string;
 	}>({
 		initialValues: {
+			application_name: appearance.application_name,
 			logo_url: appearance.logo_url,
 		},
 		onSubmit: (values) => onSaveAppearance(values),
+		enableReinitialize: true,
 	});
-	const logoFieldHelpers = getFormHelpers(logoForm);
+	const getFieldHelpers = getFormHelpers(form);
+	const fieldsDisabled = !isEntitled || form.isSubmitting;
 
 	return (
-		<>
-			<SettingsHeader>
-				<SettingsHeaderTitle>Appearance</SettingsHeaderTitle>
-				<SettingsHeaderDescription>
-					Customize the look and feel of your Coder deployment.
-				</SettingsHeaderDescription>
-			</SettingsHeader>
+		<div className="flex flex-col gap-12">
+			<div>
+				<SettingsHeader>
+					<SettingsHeaderTitle>Appearance</SettingsHeaderTitle>
+					<SettingsHeaderDescription>
+						Customize the look and feel of your Coder deployment.
+					</SettingsHeaderDescription>
+				</SettingsHeader>
 
-			<Badges>
-				<Tooltip>
-					{isEntitled && !isPremium ? (
-						<EnterpriseBadge />
-					) : (
-						<TooltipTrigger asChild>
-							<span>
-								<PremiumBadge />
-							</span>
-						</TooltipTrigger>
-					)}
+				<Badges>
+					<Tooltip>
+						{isEntitled && !isPremium ? (
+							<EnterpriseBadge />
+						) : (
+							<TooltipTrigger asChild>
+								<span>
+									<PremiumBadge />
+								</span>
+							</TooltipTrigger>
+						)}
 
-					<TooltipContent
-						sideOffset={-28}
-						collisionPadding={16}
-						className="p-0"
+						<TooltipContent
+							sideOffset={-28}
+							collisionPadding={16}
+							className="p-0"
+						>
+							<PopoverPaywall
+								message="Appearance"
+								description="With a Premium license, you can customize the appearance and branding of your deployment."
+								documentationLink={docs("/admin/setup/appearance")}
+							/>
+						</TooltipContent>
+					</Tooltip>
+				</Badges>
+
+				<HorizontalForm
+					onSubmit={form.handleSubmit}
+					aria-label="Appearance settings"
+					className="mt-8"
+				>
+					<FormSection
+						title="Branding"
+						description="Customize the application name and logo shown on the login page and in the dashboard."
 					>
-						<PopoverPaywall
-							message="Appearance"
-							description="With a Premium license, you can customize the appearance and branding of your deployment."
-							documentationLink={docs("/admin/setup/appearance")}
-						/>
-					</TooltipContent>
-				</Tooltip>
-			</Badges>
+						<FormFields>
+							<FormField
+								field={getFieldHelpers("application_name", {
+									helperText: isEntitled
+										? 'Leave empty to use "Coder".'
+										: "This is an Enterprise only feature.",
+								})}
+								label="Application name"
+								placeholder="Coder"
+								disabled={fieldsDisabled}
+							/>
 
-			<Fieldset
-				title="Application name"
-				subtitle="Specify a custom application name to be displayed on the login page."
-				validation={!isEntitled ? "This is an Enterprise only feature." : ""}
-				onSubmit={applicationNameForm.handleSubmit}
-				button={!isEntitled && <Button disabled>Submit</Button>}
-			>
-				<Input
-					{...applicationNameFieldHelpers("application_name")}
-					placeholder='Leave empty to display "Coder".'
-					disabled={!isEntitled}
-					aria-label="Application name"
-				/>
-			</Fieldset>
+							<IconField
+								{...getFieldHelpers("logo_url", {
+									helperText: isEntitled
+										? "Leave empty to use the Coder logo. An image with transparency and an aspect ratio of 3:1 or less will look best."
+										: "This is an Enterprise only feature.",
+								})}
+								label="Logo URL"
+								placeholder="/icon/coder.svg"
+								disabled={fieldsDisabled}
+								onPickEmoji={(value) => {
+									void form.setFieldValue("logo_url", value);
+								}}
+							/>
+						</FormFields>
+					</FormSection>
 
-			<Fieldset
-				title="Logo URL"
-				subtitle="Specify a custom URL for your logo to be displayed on the sign in page and in the top left
-          corner of the dashboard."
-				validation={
-					isEntitled
-						? "An image with transparency and an aspect ratio of 3:1 or less will look best."
-						: "This is an Enterprise only feature."
-				}
-				onSubmit={logoForm.handleSubmit}
-				button={!isEntitled && <Button disabled>Submit</Button>}
-			>
-				<InputGroup>
-					<InputGroupInput
-						{...logoFieldHelpers("logo_url")}
-						placeholder="Leave empty to display the Coder logo."
-						disabled={!isEntitled}
-						aria-label="Logo URL"
-					/>
-					<InputGroupAddon align="inline-end">
-						<img
-							alt=""
-							src={logoForm.values.logo_url}
-							className="size-6 max-w-full object-contain"
-							// Hide broken image icon while users type incomplete URLs.
-							onError={(e) => {
-								e.currentTarget.style.display = "none";
-							}}
-							onLoad={(e) => {
-								e.currentTarget.style.display = "inline";
-							}}
-						/>
-					</InputGroupAddon>
-				</InputGroup>
-			</Fieldset>
+					<FormFooter>
+						<Button type="submit" disabled={fieldsDisabled}>
+							<Spinner loading={form.isSubmitting} />
+							Save
+						</Button>
+					</FormFooter>
+				</HorizontalForm>
+			</div>
 
 			<AnnouncementBannerSettings
 				isEntitled={isEntitled}
@@ -154,6 +146,6 @@ export const AppearanceSettingsPageView: FC<
 					onSaveAppearance({ announcement_banners: announcementBanners })
 				}
 			/>
-		</>
+		</div>
 	);
 };

From 84bf4e9dff6f3c168acbaf9473c146c2453c1154 Mon Sep 17 00:00:00 2001
From: Jake Howell <jake@hwll.me>
Date: Fri, 31 Jul 2026 00:57:23 +0000
Subject: [PATCH 4/6] chore: standaradise paywall splash

---
 .../AppearanceSettingsPage/AppearanceSettingsPageView.tsx       | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/site/src/pages/DeploymentSettingsPage/AppearanceSettingsPage/AppearanceSettingsPageView.tsx b/site/src/pages/DeploymentSettingsPage/AppearanceSettingsPage/AppearanceSettingsPageView.tsx
index ee0084770d9..691d0dc8cda 100644
--- a/site/src/pages/DeploymentSettingsPage/AppearanceSettingsPage/AppearanceSettingsPageView.tsx
+++ b/site/src/pages/DeploymentSettingsPage/AppearanceSettingsPage/AppearanceSettingsPageView.tsx
@@ -86,7 +86,7 @@ export const AppearanceSettingsPageView: FC<
 						>
 							<PopoverPaywall
 								message="Appearance"
-								description="With a Premium license, you can customize the appearance and branding of your deployment."
+								description="With a Premium license, you can customize branding and announcement banners for your deployment."
 								documentationLink={docs("/admin/setup/appearance")}
 							/>
 						</TooltipContent>

From 29ab792e06096406808119fa4d3e7ca9507e1eab Mon Sep 17 00:00:00 2001
From: Jake Howell <jake@hwll.me>
Date: Tue, 4 Aug 2026 16:28:16 +0000
Subject: [PATCH 5/6] chore: horizontal form

---
 .../AppearanceSettingsPage/AppearanceSettingsPageView.tsx   | 6 +++---
 1 file changed, 3 insertions(+), 3 deletions(-)

diff --git a/site/src/pages/DeploymentSettingsPage/AppearanceSettingsPage/AppearanceSettingsPageView.tsx b/site/src/pages/DeploymentSettingsPage/AppearanceSettingsPage/AppearanceSettingsPageView.tsx
index 691d0dc8cda..da561a31148 100644
--- a/site/src/pages/DeploymentSettingsPage/AppearanceSettingsPage/AppearanceSettingsPageView.tsx
+++ b/site/src/pages/DeploymentSettingsPage/AppearanceSettingsPage/AppearanceSettingsPageView.tsx
@@ -11,7 +11,7 @@ import {
 	FormFields,
 	FormFooter,
 	FormSection,
-	HorizontalForm,
+	VerticalForm,
 } from "#/components/Form/Form";
 import { FormField } from "#/components/FormField/FormField";
 import { IconField } from "#/components/IconField/IconField";
@@ -93,7 +93,7 @@ export const AppearanceSettingsPageView: FC<
 					</Tooltip>
 				</Badges>
 
-				<HorizontalForm
+				<VerticalForm
 					onSubmit={form.handleSubmit}
 					aria-label="Appearance settings"
 					className="mt-8"
@@ -136,7 +136,7 @@ export const AppearanceSettingsPageView: FC<
 							Save
 						</Button>
 					</FormFooter>
-				</HorizontalForm>
+				</VerticalForm>
 			</div>
 
 			<AnnouncementBannerSettings

From aa7bdac5c8fee661eb6a8e12f961db8e7fee1288 Mon Sep 17 00:00:00 2001
From: Jake Howell <jake@hwll.me>
Date: Tue, 4 Aug 2026 16:28:20 +0000
Subject: [PATCH 6/6] chore: bool usage

---
 .../AppearanceSettingsPage/AnnouncementBannerDialog.tsx         | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/site/src/pages/DeploymentSettingsPage/AppearanceSettingsPage/AnnouncementBannerDialog.tsx b/site/src/pages/DeploymentSettingsPage/AppearanceSettingsPage/AnnouncementBannerDialog.tsx
index f6fccfd7b0d..13fe63fcb07 100644
--- a/site/src/pages/DeploymentSettingsPage/AppearanceSettingsPage/AnnouncementBannerDialog.tsx
+++ b/site/src/pages/DeploymentSettingsPage/AppearanceSettingsPage/AnnouncementBannerDialog.tsx
@@ -25,7 +25,7 @@ export const AnnouncementBannerDialog: FC<AnnouncementBannerDialogProps> = ({
 	onUpdate,
 }) => {
 	const theme = useTheme();
-	const isCreating = !banner.message;
+	const isCreating = new Boolean(banner.message);
 
 	const bannerForm = useFormik<{
 		message: string;