From 8c80fd6113faf96e879085994aa176b9e7ae96b7 Mon Sep 17 00:00:00 2001
From: morgmart <98432065+morgmart@users.noreply.github.com>
Date: Sat, 10 Oct 2026 15:20:13 -0700
Subject: [PATCH 1/2] Default icon actions to the compact size

Signed-off-by: morgmart <98432065+morgmart@users.noreply.github.com>
---
 docs/design-system-adoption.md                |  2 +-
 src/features/communities/CommunityRail.tsx    |  2 ++
 .../communities/CommunityRailItem.tsx         |  1 +
 src/features/profiles/AvatarEditor.tsx        |  1 +
 src/shared/design-system/DESIGN.md            |  8 +++--
 src/shared/design-system/ui/IconButton.tsx    |  2 +-
 src/shared/design-system/ui/controls.test.tsx | 35 +++++++++++++++++++
 src/shared/design-system/ui/registry.ts       |  4 +--
 tests/browser/avatar-edit.spec.mjs            | 11 +++++-
 tests/browser/plugin-import.spec.mjs          |  2 +-
 tests/browser/sidenav-polish.spec.mjs         | 21 +++++++++++
 .../design-system/ui/ButtonSpecimens.tsx      |  4 +++
 tests/fixtures/design-system/viewer.spec.ts   | 14 ++++++++
 13 files changed, 99 insertions(+), 8 deletions(-)

diff --git a/docs/design-system-adoption.md b/docs/design-system-adoption.md
index 144b77892..b97c52e37 100644
--- a/docs/design-system-adoption.md
+++ b/docs/design-system-adoption.md
@@ -11,7 +11,7 @@ Use this map to find the shared owner before changing a product surface.
 | Area | Shared owner | App uses |
 | --- | --- | --- |
 | Colors and type | Surface, text, border, affordance, and complete type roles | Host aliases forward to shared roles. Feature CSS uses role names; inline links pair text and hover roles. |
-| Actions | Button and IconButton | Retry, refresh, delete, recovery, composer send, and picker triggers. Standard sizes are 32/40/52px minimums. Labels stay on one line; surrounding layouts reflow whole controls or scroll. |
+| Actions | Button and IconButton | Retry, refresh, delete, recovery, composer send, and picker triggers. Standard sizes are 32/40/52px; IconButton defaults to small and labelled Button defaults to medium. Text-button heights are minimums. Labels stay on one line; surrounding layouts reflow whole controls or scroll. |
 | Forms and choices | Field, Input, Textarea, RadioGroup, Checkbox | Profile, community setup, appearance, plugin import, and workflow editing. |
 | Search | SearchField | Channels, pages, members, and GIFs retain their query, refs, and keyboard handlers. |
 | Navigation | NavigationItem | Settings, channel rows, shell destinations, Home, and community choices. Route destinations use button semantics; the wide shell topbar is the documented chrome-tab exception. |
diff --git a/src/features/communities/CommunityRail.tsx b/src/features/communities/CommunityRail.tsx
index c8b4c1331..ed8073b11 100644
--- a/src/features/communities/CommunityRail.tsx
+++ b/src/features/communities/CommunityRail.tsx
@@ -193,6 +193,7 @@ export function CommunityRail({
         <Tooltip content="Personal space" side="right">
           <IconButton
             ref={personalRef}
+            size="md"
             aria-label="Personal space"
             aria-current={client.selected === null ? "true" : undefined}
             data-selected={client.selected === null || undefined}
@@ -232,6 +233,7 @@ export function CommunityRail({
         <Tooltip content="Add a community" side="right">
           <IconButton
             ref={addRef}
+            size="md"
             aria-label="Add a community"
             icon={<PlusIcon size={22} aria-hidden="true" />}
             onClick={() => setJoining(true)}
diff --git a/src/features/communities/CommunityRailItem.tsx b/src/features/communities/CommunityRailItem.tsx
index 20cad3d47..f6e3bd4b3 100644
--- a/src/features/communities/CommunityRailItem.tsx
+++ b/src/features/communities/CommunityRailItem.tsx
@@ -156,6 +156,7 @@ export function CommunityRailItem({
               button.current = node;
               buttonRef?.(node);
             }}
+            size="md"
             aria-label={`Switch to ${name}`}
             aria-current={selected ? "true" : undefined}
             data-selected={selected || undefined}
diff --git a/src/features/profiles/AvatarEditor.tsx b/src/features/profiles/AvatarEditor.tsx
index 9e911dbd9..9c1948751 100644
--- a/src/features/profiles/AvatarEditor.tsx
+++ b/src/features/profiles/AvatarEditor.tsx
@@ -125,6 +125,7 @@ export function AvatarEditor(props: Props) {
             render={
               <IconButton
                 variant="solid"
+                size="md"
                 shape="round"
                 style={{
                   width: "100%",
diff --git a/src/shared/design-system/DESIGN.md b/src/shared/design-system/DESIGN.md
index 18f64f836..79ac58fb3 100644
--- a/src/shared/design-system/DESIGN.md
+++ b/src/shared/design-system/DESIGN.md
@@ -632,8 +632,12 @@ the composer's model name, `size="inline"` keeps a 24px minimum target with 4px
 horizontal padding and icon gap, and 12px icons. Pair it with `variant="ghost"`
 for an unframed label; shared hover, disabled, and keyboard focus still apply.
 
-IconButton defaults to a 10px rounded rectangle (`--radius-icon-button`) and uses the same
-sm/md/lg sizes. Existing names
+Button defaults to `md` (40px minimum height); IconButton defaults to `sm`
+(32px square with 16px artwork) and a 10px rounded rectangle
+(`--radius-icon-button`). Choose `md` or `lg` explicitly when an icon action needs
+a larger control; community rail identities and the avatar edit badge retain their
+existing larger treatment. These defaults do not depend on pointer type or viewport
+width. Both controls use the same sm/md/lg scale. Existing names
 remain compatibility aliases: primary/solid → prominent, quiet → subtle,
 compact/toolbar → sm, default → md, large → lg. Do not add new alias call sites.
 Buzz's tint and chrome icon variants remain for composer and backdrop actions.
diff --git a/src/shared/design-system/ui/IconButton.tsx b/src/shared/design-system/ui/IconButton.tsx
index d0ab9bb56..1476db0c6 100644
--- a/src/shared/design-system/ui/IconButton.tsx
+++ b/src/shared/design-system/ui/IconButton.tsx
@@ -30,7 +30,7 @@ export type IconButtonProps = Omit<
 export function IconButton({
   icon,
   variant = "ghost",
-  size = "md",
+  size = "sm",
   shape = variant === "avatar" ? "round" : "control",
   ...props
 }: IconButtonProps) {
diff --git a/src/shared/design-system/ui/controls.test.tsx b/src/shared/design-system/ui/controls.test.tsx
index d29bd6941..27b97a13b 100644
--- a/src/shared/design-system/ui/controls.test.tsx
+++ b/src/shared/design-system/ui/controls.test.tsx
@@ -5,6 +5,8 @@ import { act, cleanup, render, screen, waitFor } from "@testing-library/react";
 import userEvent from "@testing-library/user-event";
 import { createRef, useState } from "react";
 import { Button } from "./Button";
+import { IconButton } from "./IconButton";
+import { PlusIcon } from "../icons";
 import { Field } from "./Field";
 import { Input } from "./Input";
 import { Textarea } from "./Textarea";
@@ -15,6 +17,39 @@ import { Composer } from "./Composer";
 
 afterEach(cleanup);
 
+test("icon actions default to small while labelled actions remain medium", () => {
+  render(
+    <>
+      <IconButton aria-label="Add item" icon={<PlusIcon />} />
+      <Button>Continue</Button>
+    </>,
+  );
+  expect(screen.getByRole("button", { name: "Add item" })).toHaveAttribute(
+    "data-size",
+    "sm",
+  );
+  expect(screen.getByRole("button", { name: "Continue" })).toHaveAttribute(
+    "data-size",
+    "md",
+  );
+});
+
+test.each([
+  ["sm", "sm"],
+  ["md", "md"],
+  ["lg", "lg"],
+  ["compact", "sm"],
+  ["toolbar", "sm"],
+  ["default", "md"],
+  ["large", "lg"],
+  ["xs", "sm"],
+] as const)("explicit icon size %s retains its contract", (size, resolved) => {
+  render(<IconButton size={size} aria-label="Add item" icon={<PlusIcon />} />);
+  const control = screen.getByRole("button", { name: "Add item" });
+  expect(control).toHaveAttribute("data-size", resolved);
+  expect(control).toHaveAttribute("data-icon-size", size);
+});
+
 test("composer enables submission only for an available non-empty draft", async () => {
   const user = userEvent.setup();
   const submit = vi.fn((event) => event.preventDefault());
diff --git a/src/shared/design-system/ui/registry.ts b/src/shared/design-system/ui/registry.ts
index 39d757155..45635e831 100644
--- a/src/shared/design-system/ui/registry.ts
+++ b/src/shared/design-system/ui/registry.ts
@@ -414,7 +414,7 @@ export const COMPONENTS: readonly ComponentDefinition[] = [
       "outline",
       "inverted",
       "link",
-      "size: inline | xs | sm | md | lg",
+      "size: inline | xs | sm | md (default) | lg",
       "shape: capsule (default) | control (12px)",
       "loading",
     ],
@@ -445,7 +445,7 @@ export const COMPONENTS: readonly ComponentDefinition[] = [
       "media",
       "bare (glyph-state toggle, no background in any state; 20px artwork at sm)",
       "shape: control (default, 10px) | round (avatar default) | row-end",
-      "size: xs (20px, 12px icon) | sm (32px) | md (40px) | lg (52px)",
+      "size: xs (20px, 12px icon) | sm (default, 32px, 16px icon) | md (40px) | lg (52px)",
       "legacy aliases: quiet, solid, compact, toolbar, default, large",
     ],
     status: "proposed",
diff --git a/tests/browser/avatar-edit.spec.mjs b/tests/browser/avatar-edit.spec.mjs
index f0fc199b4..b5ee37d7d 100644
--- a/tests/browser/avatar-edit.spec.mjs
+++ b/tests/browser/avatar-edit.spec.mjs
@@ -10,7 +10,16 @@ test("avatar image controls retain their hover fill and accessible URL label", a
   await page
     .getByRole("button", { name: "Edit human profile", exact: true })
     .click();
-  await page.getByRole("button", { name: "Edit avatar", exact: true }).click();
+  const editAvatar = page.getByRole("button", {
+    name: "Edit avatar",
+    exact: true,
+  });
+  // The badge owns its outer box; opting into medium preserves the artwork
+  // without replacing that human/agent geometry with the new compact default.
+  await expect(editAvatar).toHaveCSS("width", "32px");
+  await expect(editAvatar).toHaveCSS("height", "32px");
+  await expect(editAvatar.locator("svg")).toHaveCSS("width", "24px");
+  await editAvatar.click();
   const dropzone = page.getByRole("button", {
     name: "Drop or browse",
     exact: true,
diff --git a/tests/browser/plugin-import.spec.mjs b/tests/browser/plugin-import.spec.mjs
index af3538510..e56de448f 100644
--- a/tests/browser/plugin-import.spec.mjs
+++ b/tests/browser/plugin-import.spec.mjs
@@ -265,7 +265,7 @@ test("Settings controls scale together and keep enlarged labels reachable", asyn
       // Icon buttons grow with the interface while keeping their square shape.
       await expect(
         page.getByRole("button", { name: "Search Buzz", exact: true }),
-      ).toHaveAttribute("data-icon-size", "md");
+      ).toHaveAttribute("data-icon-size", "sm");
       await expect
         .poll(() =>
           page
diff --git a/tests/browser/sidenav-polish.spec.mjs b/tests/browser/sidenav-polish.spec.mjs
index 2ba13062a..421d64cbd 100644
--- a/tests/browser/sidenav-polish.spec.mjs
+++ b/tests/browser/sidenav-polish.spec.mjs
@@ -308,6 +308,27 @@ test("top bar uses consistent square controls and translucent ghost fills", asyn
       await expect(overflow).toBeHidden();
       await expect(topbarPages).toBeVisible();
     }
+    // The icon default is compact, but community identities keep their larger
+    // targets. Host CSS must not accidentally erase those explicit exceptions.
+    const rail = page.getByRole("navigation", {
+      name: "Communities",
+      exact: true,
+    });
+    for (const control of await rail.getByRole("button").all()) {
+      const box = await control.boundingBox();
+      expect([box.width, box.height]).toEqual([40, 40]);
+    }
+    await header
+      .getByRole("button", { name: "Your profile", exact: true })
+      .click();
+    const profileAvatar = page.getByRole("menuitem", {
+      name: "View your profile",
+    });
+    await expect(profileAvatar).toBeVisible();
+    const avatarBox = await profileAvatar.boundingBox();
+    expect([avatarBox.width, avatarBox.height]).toEqual([40, 40]);
+    await page.keyboard.press("Escape");
+    await expect(profileAvatar).toHaveCount(0);
     expect(await controls.count()).toBeGreaterThanOrEqual(5);
     for (const control of await controls.all()) {
       const box = await control.boundingBox();
diff --git a/tests/fixtures/design-system/ui/ButtonSpecimens.tsx b/tests/fixtures/design-system/ui/ButtonSpecimens.tsx
index dc903a34f..5086f443a 100644
--- a/tests/fixtures/design-system/ui/ButtonSpecimens.tsx
+++ b/tests/fixtures/design-system/ui/ButtonSpecimens.tsx
@@ -288,6 +288,10 @@ export function IconButtonSpecimen() {
   const [unread, setUnread] = useState(false);
   return (
     <div className="component-specimen-stack">
+      <p className="text-body-sm text-subtle">
+        Icon actions default to small: a 32px control with 16px artwork.
+        Labelled buttons stay medium; choose a larger icon size explicitly.
+      </p>
       <ExamplePreview
         className="justify-center"
         code={`<IconButton
diff --git a/tests/fixtures/design-system/viewer.spec.ts b/tests/fixtures/design-system/viewer.spec.ts
index febb224b1..778f61db1 100644
--- a/tests/fixtures/design-system/viewer.spec.ts
+++ b/tests/fixtures/design-system/viewer.spec.ts
@@ -1200,9 +1200,23 @@ test("buttons and icon buttons share size geometry and preserve loading and disa
     });
     await expect(samples).toBeVisible();
     await page.evaluate(() => document.fonts.ready);
+    const defaultControl = page
+      .getByRole("button", {
+        name: kind === "button" ? "Continue" : "Add item",
+        exact: true,
+      })
+      .first();
     for (const mode of ["light", "dark"]) {
       const toggle = page.getByRole("button", { name: `Use ${mode} mode` });
       if (await toggle.count()) await toggle.click();
+      await expect(defaultControl).toHaveCSS(
+        "height",
+        kind === "button" ? "40px" : "32px",
+      );
+      if (kind === "icon-button") {
+        await expect(defaultControl).toHaveCSS("width", "32px");
+        await expect(defaultControl.locator("svg")).toHaveCSS("width", "16px");
+      }
       for (const [size, height, artwork] of [
         ["sm", 32, 16],
         ["md", 40, 24],

From 652d2ff9e854e54bc935617460b4f523bc14dae8 Mon Sep 17 00:00:00 2001
From: morgmart <98432065+morgmart@users.noreply.github.com>
Date: Sat, 10 Oct 2026 16:53:48 -0700
Subject: [PATCH 2/2] Reduce invitation paging test overhead without weakening
 coverage

Signed-off-by: morgmart <98432065+morgmart@users.noreply.github.com>
---
 src/bundled/channels/ChannelMembersDialog.test.tsx | 13 +++++++++----
 1 file changed, 9 insertions(+), 4 deletions(-)

diff --git a/src/bundled/channels/ChannelMembersDialog.test.tsx b/src/bundled/channels/ChannelMembersDialog.test.tsx
index e3c072e0b..ce3623460 100644
--- a/src/bundled/channels/ChannelMembersDialog.test.tsx
+++ b/src/bundled/channels/ChannelMembersDialog.test.tsx
@@ -1195,9 +1195,10 @@ it("pages combined local and relay invitations without losing matches", async ({
 }) => {
   return ownedTask(signal, async (step) => {
     const { t, idle, more, rows, pages } = await pagedInvitations(step, 65);
-    expect(rows()).toHaveLength(30);
+    const firstPage = rows();
+    expect(firstPage).toHaveLength(30);
     expect(
-      rows().every((row) =>
+      firstPage.every((row) =>
         row.getAttribute("aria-label")?.startsWith("Add Helper remote"),
       ),
     ).toBe(true);
@@ -1209,7 +1210,9 @@ it("pages combined local and relay invitations without losing matches", async ({
     }
     await more();
     await idle();
-    screen.getByRole("button", { name: /^Add Helper final/ });
+    expect(
+      screen.getByRole("button", { name: /^Add Helper final/ }),
+    ).toBeVisible();
     expect(rows()).toHaveLength(96);
     expect(pages()).toEqual([1, 2]);
     expect(
@@ -1228,7 +1231,9 @@ it("resets combined invitation paging on refresh or query change", async ({
       await pagedInvitations(step, 31);
     for (let i = 0; i < 3; i++) await more();
     await idle();
-    screen.getByRole("button", { name: /^Add Helper final/ });
+    expect(
+      screen.getByRole("button", { name: /^Add Helper final/ }),
+    ).toBeVisible();
     expect(rows()).toHaveLength(62);
     expect(pages()).toEqual([1, 2]);
     await click(refresh);