refactor(desktop): unify page/section header hierarchy across Agents and Settings (#1912)

Co-authored-by: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

desktop/src/features/agents/ui/AgentSessionToolItem/ToolDetailBlocks.tsx

@@ -97,7 +97,7 @@ function ToolCodeBlock({
 }) {
   return (
     <div className="space-y-2 overflow-hidden">
-      <h4 className="text-xs font-medium uppercase tracking-wide text-muted-foreground">
+      <h4 className="text-2xs font-semibold uppercase tracking-wide text-muted-foreground">
         {label}
       </h4>
       <pre

desktop/src/features/agents/ui/AgentsView.tsx

@@ -24,6 +24,7 @@ import { useManagedAgentActions } from "./useManagedAgentActions";
 import { usePersonaActions } from "./usePersonaActions";
 import { useTeamActions } from "./useTeamActions";
 import { useProfilePanel } from "@/shared/context/ProfilePanelContext";
+import { PageHeader } from "@/shared/ui/PageHeader";
 import { GlobalAgentConfigSettingsCard } from "@/features/settings/ui/GlobalAgentConfigSettingsCard";
 
 export function AgentsView() {
@@ -89,6 +90,10 @@ export function AgentsView() {
     <>
       <div className="flex-1 overflow-y-auto overflow-x-hidden overscroll-contain px-4 py-7 sm:px-6 sm:py-8">
         <div className="mx-auto flex w-full max-w-6xl flex-col gap-8">
+          <PageHeader
+            description="Set up and manage your agents."
+            title="Agents"
+          />
           <div className="flex flex-col gap-8">
             <GlobalAgentConfigSettingsCard />
 

desktop/src/features/agents/ui/ManagedAgentLogPanel.tsx

@@ -161,7 +161,7 @@ function HarnessLogHeader({
   return (
     <div className="flex min-h-12 items-center justify-between gap-3 border-b border-white/10 px-3 py-2">
       <div className="flex min-w-0 flex-col gap-0.5">
-        <span className="min-w-0 truncate text-2xs font-semibold uppercase tracking-[0.18em] text-zinc-300">
+        <span className="min-w-0 truncate text-2xs font-semibold uppercase tracking-wide text-zinc-300">
           Harness Log
         </span>
         <span

desktop/src/features/agents/ui/ManagedAgentRow.tsx

@@ -26,6 +26,7 @@ import { AgentConfigPanel } from "./AgentConfigPanel";
 import { friendlyAgentLastError } from "@/features/agents/lib/friendlyAgentLastError";
 import { ManagedAgentLogPanel } from "./ManagedAgentLogPanel";
 import { PubKey } from "@/shared/ui/PubKey";
+import { SubsectionLabel } from "@/shared/ui/PageHeader";
 
 export function ManagedAgentRow({
   agent,
@@ -358,9 +359,7 @@ function StatusBlock({
 }) {
   return (
     <div className="space-y-1 lg:pt-0.5">
-      <p className="text-2xs font-semibold uppercase tracking-[0.16em] text-muted-foreground lg:hidden">
-        Status
-      </p>
+      <SubsectionLabel className="lg:hidden">Status</SubsectionLabel>
       <AgentStatusBadge
         isWorking={isWorking}
         presenceLoaded={presenceLoaded}
@@ -394,9 +393,7 @@ function RuntimeBlock({
 }) {
   return (
     <div className="space-y-1 lg:pt-0.5">
-      <p className="text-2xs font-semibold uppercase tracking-[0.16em] text-muted-foreground lg:hidden">
-        Runtime
-      </p>
+      <SubsectionLabel className="lg:hidden">Runtime</SubsectionLabel>
       <p className="truncate font-mono text-xs text-foreground">
         {agent.agentCommand}
       </p>

desktop/src/features/agents/ui/PersonaCatalogDetailsSheet.tsx

@@ -123,13 +123,13 @@ export function PersonaCatalogDetailsSheet({
 
               <div className="grid gap-3 sm:grid-cols-2">
                 <div className="rounded-xl border border-border/70 bg-card/70 p-4">
-                  <p className="text-xs font-semibold uppercase tracking-[0.14em] text-muted-foreground">
+                  <p className="text-2xs font-semibold uppercase tracking-wide text-muted-foreground">
                     Type
                   </p>
                   <p className="mt-2 text-sm font-medium">Built-in agent</p>
                 </div>
                 <div className="rounded-xl border border-border/70 bg-card/70 p-4">
-                  <p className="text-xs font-semibold uppercase tracking-[0.14em] text-muted-foreground">
+                  <p className="text-2xs font-semibold uppercase tracking-wide text-muted-foreground">
                     Preferred model
                   </p>
                   <p className="mt-2 text-sm font-medium">
@@ -137,7 +137,7 @@ export function PersonaCatalogDetailsSheet({
                   </p>
                 </div>
                 <div className="rounded-xl border border-border/70 bg-card/70 p-4 sm:col-span-2">
-                  <p className="text-xs font-semibold uppercase tracking-[0.14em] text-muted-foreground">
+                  <p className="text-2xs font-semibold uppercase tracking-wide text-muted-foreground">
                     Preferred runtime
                   </p>
                   <p className="mt-2 text-sm font-medium">
@@ -147,7 +147,7 @@ export function PersonaCatalogDetailsSheet({
               </div>
 
               <div className="rounded-xl border border-border/70 bg-card/70 p-4">
-                <p className="text-xs font-semibold uppercase tracking-[0.14em] text-muted-foreground">
+                <p className="text-2xs font-semibold uppercase tracking-wide text-muted-foreground">
                   System prompt
                 </p>
                 <pre className="mt-3 whitespace-pre-wrap break-words font-sans text-sm leading-6 text-foreground">

desktop/src/features/agents/ui/RelayDirectorySection.tsx

@@ -61,9 +61,9 @@ export function RelayDirectorySection({
         ) : (
           <ChevronRight className="h-4 w-4 shrink-0 text-muted-foreground" />
         )}
-        <h3 className="text-sm font-semibold tracking-tight">
+        <h2 className="text-lg font-semibold tracking-tight">
           Relay directory
-        </h3>
+        </h2>
         <span className="text-sm text-muted-foreground">
           ({otherAgents.length} other agent{otherAgents.length !== 1 ? "s" : ""}
           )
@@ -95,7 +95,7 @@ export function RelayDirectorySection({
                   className="w-full border-collapse text-left text-sm"
                   data-testid="relay-directory-table"
                 >
-                  <thead className="bg-muted/35 text-2xs font-semibold uppercase tracking-[0.16em] text-muted-foreground">
+                  <thead className="bg-muted/35 text-2xs font-semibold uppercase tracking-wide text-muted-foreground">
                     <tr>
                       <th className="px-4 py-3">Agent</th>
                       <th className="px-4 py-3">Status</th>

desktop/src/features/agents/ui/TeamsSection.tsx

@@ -18,6 +18,7 @@ import {
   DropdownMenuTrigger,
 } from "@/shared/ui/dropdown-menu";
 import { IdentityCardSkeleton } from "@/shared/ui/identity-card-skeleton";
+import { SectionHeader } from "@/shared/ui/PageHeader";
 import { CreateIdentityCard } from "./CreateIdentityCard";
 import { TeamIdentityCard } from "./TeamIdentityCard";
 
@@ -55,15 +56,11 @@ export function TeamsSection({
 }: TeamsSectionProps) {
   return (
     <section className="relative space-y-4" data-testid="agents-library-teams">
-      <div
-        className={`${TEAM_CARD_COLUMN_CLASS} flex items-center justify-between gap-3`}
-      >
-        <div>
-          <h3 className="text-sm font-semibold tracking-tight">Teams</h3>
-          <p className="text-sm text-secondary-foreground/75">
-            Saved groups from My Agents that you can add to a channel together.
-          </p>
-        </div>
+      <div className={TEAM_CARD_COLUMN_CLASS}>
+        <SectionHeader
+          title="Teams"
+          description="Groups of your agents you can add to a channel together."
+        />
       </div>
 
       {isLoading ? (

desktop/src/features/agents/ui/UnifiedAgentsSection.tsx

@@ -24,6 +24,7 @@ import {
   DropdownMenuTrigger,
 } from "@/shared/ui/dropdown-menu";
 import { IdentityCardSkeleton } from "@/shared/ui/identity-card-skeleton";
+import { SectionHeader } from "@/shared/ui/PageHeader";
 import { AgentIdentityCard } from "./AgentIdentityCard";
 import { AgentRuntimeAvatarControl } from "./AgentRuntimeAvatarControl";
 import { CreateIdentityCard } from "./CreateIdentityCard";
@@ -157,7 +158,7 @@ export function UnifiedAgentsSection(props: UnifiedAgentsSectionProps) {
         </div>
       ) : null}
 
-      <SectionHeader
+      <AgentsListHeader
         agentCount={agents.length}
         fileInputRef={fileInputRef}
         handleFileChange={handleFileChange}
@@ -434,7 +435,7 @@ function firstAvatarUrl(
   return null;
 }
 
-function SectionHeader({
+function AgentsListHeader({
   agentCount,
   fileInputRef,
   handleFileChange,
@@ -450,15 +451,7 @@ function SectionHeader({
   onBulkStopRunning: () => void;
 }) {
   return (
-    <div
-      className={`${AGENT_CARD_COLUMN_CLASS} flex items-center justify-between gap-3`}
-    >
-      <div>
-        <h3 className="text-sm font-semibold tracking-tight">Agents</h3>
-        <p className="text-sm text-secondary-foreground/75">
-          Agents in this community.
-        </p>
-      </div>
+    <div className={AGENT_CARD_COLUMN_CLASS}>
       <input
         accept=".agent.json,.agent.png"
         className="hidden"
@@ -466,32 +459,38 @@ function SectionHeader({
         ref={fileInputRef}
         type="file"
       />
-      {agentCount > 0 ? (
-        <DropdownMenu modal={false}>
-          <DropdownMenuTrigger asChild>
-            <Button
-              aria-label="Bulk actions"
-              className="h-7 w-7"
-              size="icon"
-              variant="ghost"
-            >
-              <Ellipsis className="h-4 w-4" />
-            </Button>
-          </DropdownMenuTrigger>
-          <DropdownMenuContent
-            align="end"
-            onCloseAutoFocus={(event) => event.preventDefault()}
-          >
-            <DropdownMenuItem
-              disabled={isActionPending || runningCount === 0}
-              onClick={onBulkStopRunning}
-            >
-              <OctagonX className="h-4 w-4" />
-              Stop all running ({runningCount})
-            </DropdownMenuItem>
-          </DropdownMenuContent>
-        </DropdownMenu>
-      ) : null}
+      <SectionHeader
+        title="Agents"
+        description="Agents in this community."
+        action={
+          agentCount > 0 ? (
+            <DropdownMenu modal={false}>
+              <DropdownMenuTrigger asChild>
+                <Button
+                  aria-label="Bulk actions"
+                  className="h-7 w-7"
+                  size="icon"
+                  variant="ghost"
+                >
+                  <Ellipsis className="h-4 w-4" />
+                </Button>
+              </DropdownMenuTrigger>
+              <DropdownMenuContent
+                align="end"
+                onCloseAutoFocus={(event) => event.preventDefault()}
+              >
+                <DropdownMenuItem
+                  disabled={isActionPending || runningCount === 0}
+                  onClick={onBulkStopRunning}
+                >
+                  <OctagonX className="h-4 w-4" />
+                  Stop all running ({runningCount})
+                </DropdownMenuItem>
+              </DropdownMenuContent>
+            </DropdownMenu>
+          ) : undefined
+        }
+      />
     </div>
   );
 }

desktop/src/features/agents/ui/buzzAgentModelTuningFields.tsx

@@ -165,7 +165,7 @@ export function BuzzAgentModelTuningFields({
 
   return (
     <div className="space-y-4">
-      <p className="text-xs font-medium text-muted-foreground uppercase tracking-wide">
+      <p className="text-2xs font-semibold uppercase tracking-wide text-muted-foreground">
         buzz-agent model tuning
       </p>
 

desktop/src/features/community-members/ui/CommunityMembersSettingsCard.tsx

@@ -354,7 +354,7 @@ export function CommunityMembersSettingsCard({
   return (
     <section className="min-w-0" data-testid="settings-community-members">
       <SettingsSectionHeader
-        title="Community Access"
+        title="Community access"
         description={
           <>
             Manage who can connect to this relay. Owners can invite admins or

desktop/src/features/custom-emoji/ui/CustomEmojiSettingsCard.tsx

@@ -126,7 +126,7 @@ export function CustomEmojiSettingsCard() {
   return (
     <section className="min-w-0" data-testid="settings-custom-emoji">
       <SettingsSectionHeader
-        title="Custom Emoji"
+        title="Custom emoji"
         description={
           <>
             Add your own custom emoji for everyone on this relay to use. Type{" "}
@@ -257,9 +257,9 @@ export function CustomEmojiSettingsCard() {
         </form>
 
         <div className="space-y-3" data-testid="custom-emoji-mine">
-          <h3 className="text-sm font-medium">
+          <h2 className="text-lg font-semibold tracking-tight">
             My emoji{own.length > 0 ? ` (${own.length})` : ""}
-          </h3>
+          </h2>
           {ownLoading ? (
             <SettingsOptionGroup>
               <div className="px-4 py-3 text-sm font-normal text-muted-foreground">
@@ -305,9 +305,9 @@ export function CustomEmojiSettingsCard() {
 
         {!communityLoading && othersEmoji.length > 0 ? (
           <div className="space-y-3" data-testid="custom-emoji-community">
-            <h3 className="text-sm font-medium">
+            <h2 className="text-lg font-semibold tracking-tight">
               Community emoji ({othersEmoji.length})
-            </h3>
+            </h2>
             <p className="text-sm font-normal text-muted-foreground">
               Added by other members. You can use these, but only their owner
               can remove them.

desktop/src/features/local-archive/ui/LocalArchiveSettingsCard.tsx

@@ -77,7 +77,9 @@ function ObserverArchiveSection({
 }: ObserverSectionProps) {
   return (
     <div className="space-y-3" data-testid="local-archive-observer-section">
-      <h3 className="text-sm font-medium">Agent observer feed</h3>
+      <h2 className="text-lg font-semibold tracking-tight">
+        Agent observer feed
+      </h2>
       <SettingsOptionGroup>
         <SettingsOptionRow>
           <div className="min-w-0 flex-1">
@@ -121,7 +123,9 @@ function AgentMetricArchiveSection({
 }: AgentMetricSectionProps) {
   return (
     <div className="space-y-3" data-testid="local-archive-agent-metric-section">
-      <h3 className="text-sm font-medium">Agent turn metrics</h3>
+      <h2 className="text-lg font-semibold tracking-tight">
+        Agent turn metrics
+      </h2>
       <SettingsOptionGroup>
         <SettingsOptionRow>
           <div className="min-w-0 flex-1">
@@ -512,7 +516,7 @@ export function LocalArchiveSettingsCard() {
   return (
     <section className="min-w-0" data-testid="settings-local-archive">
       <SettingsSectionHeader
-        title="Local Archive"
+        title="Local archive"
         description="Save copies of relay messages to a local SQLite database in your Buzz nest. Events are re-verified against the relay at archive time."
       />
 
@@ -533,10 +537,10 @@ export function LocalArchiveSettingsCard() {
 
         {/* Channel subscriptions */}
         <div className="space-y-3" data-testid="local-archive-subscriptions">
-          <h3 className="text-sm font-medium">
+          <h2 className="text-lg font-semibold tracking-tight">
             Channel subscriptions
             {channelSubs.length > 0 ? ` (${channelSubs.length})` : ""}
-          </h3>
+          </h2>
           {isLoading ? (
             <SettingsOptionGroup>
               <div className="px-4 py-3 text-sm font-normal text-muted-foreground">
@@ -588,7 +592,9 @@ export function LocalArchiveSettingsCard() {
 
         {/* Add channel subscription */}
         <div className="space-y-3" data-testid="local-archive-add">
-          <h3 className="text-sm font-medium">Add channel subscription</h3>
+          <h2 className="text-lg font-semibold tracking-tight">
+            Add channel subscription
+          </h2>
           {isAddingOpen ? (
             <AddSubscriptionForm
               channels={joinedChannels}

desktop/src/features/settings/ui/ChannelTemplatesSettingsCard.tsx

@@ -101,7 +101,7 @@ export function ChannelTemplatesSettingsCard() {
   return (
     <section className="min-w-0" data-testid="settings-channel-templates">
       <SettingsSectionHeader
-        title="Channel Templates"
+        title="Channel templates"
         description={
           <>
             Save reusable channel configurations and apply them when creating

desktop/src/features/settings/ui/DoctorSettingsPanel.tsx

@@ -497,7 +497,9 @@ export function DoctorSettingsPanel() {
           {gitBashQuery.data ? (
             <>
               <div className="px-4 py-3 text-sm">
-                <h3 className="text-sm font-medium">System prerequisites</h3>
+                <h2 className="text-lg font-semibold tracking-tight">
+                  System prerequisites
+                </h2>
                 <p className="mt-1 text-sm font-normal text-muted-foreground">
                   Windows tools required by supported agents.
                 </p>
@@ -506,7 +508,9 @@ export function DoctorSettingsPanel() {
             </>
           ) : null}
           <div className="px-4 py-3 text-sm">
-            <h3 className="text-sm font-medium">Agent CLIs and ACP runtimes</h3>
+            <h2 className="text-lg font-semibold tracking-tight">
+              Agent CLIs and ACP runtimes
+            </h2>
             <p className="mt-1 text-sm font-normal text-muted-foreground">
               Installation status of supported agent CLIs and their ACP
               runtimes.

desktop/src/features/settings/ui/GlobalAgentConfigSettingsCard.tsx

@@ -25,7 +25,7 @@ import {
   EMPTY_GLOBAL_CONFIG,
 } from "@/features/agents/ui/GlobalAgentConfigFields";
 import { Button } from "@/shared/ui/button";
-import { SettingsSectionHeader } from "./SettingsSectionHeader";
+import { SectionHeader } from "@/shared/ui/PageHeader";
 
 type SaveState = "idle" | "saving" | "saved" | "error";
 
@@ -133,10 +133,13 @@ export function GlobalAgentConfigSettingsCard() {
   }
 
   return (
-    <section className="min-w-0" data-testid="settings-global-agent-config">
-      <SettingsSectionHeader
+    <section
+      className="min-w-0 space-y-4"
+      data-testid="settings-global-agent-config"
+    >
+      <SectionHeader
         title="Agent defaults"
-        description="Global configuration inherited by all local agents. Per-agent and persona settings always take priority."
+        description="Default settings for every agent running on this computer. You can override them for any individual agent or persona."
       />
 
       {isLoading ? (

desktop/src/features/settings/ui/KeyboardShortcutsCard.tsx

@@ -34,16 +34,16 @@ export function KeyboardShortcutsCard() {
   return (
     <section className="min-w-0" data-testid="settings-shortcuts">
       <SettingsSectionHeader
-        title="Keyboard Shortcuts"
+        title="Keyboard shortcuts"
         description="All available keyboard shortcuts. Shortcuts are read-only."
       />
 
       <div className="space-y-4">
         {[...categories.entries()].map(([category, shortcuts]) => (
           <div key={category}>
-            <h3 className="mb-2 text-xs font-semibold uppercase tracking-widest text-muted-foreground">
+            <h2 className="mb-2 text-lg font-semibold tracking-tight">
               {category}
-            </h3>
+            </h2>
             <SettingsOptionGroup>
               {shortcuts.map((shortcut) => (
                 <SettingsOptionRow

desktop/src/features/settings/ui/ProfileSettingsCard.tsx

@@ -772,9 +772,9 @@ export function ProfileSettingsCard({
                           data-testid="profile-metadata-card"
                         >
                           <div className="flex min-h-14 items-center justify-between gap-4 px-4 py-3">
-                            <h3 className="text-sm font-medium">
+                            <h2 className="text-lg font-semibold tracking-tight">
                               Profile info
-                            </h3>
+                            </h2>
                             <EditProfileMetadataButton
                               disabled={updateProfileMutation.isPending}
                               isEditing={isEditingProfileMetadata}
@@ -866,9 +866,9 @@ export function ProfileSettingsCard({
                               data-testid="profile-identity-toggle"
                             >
                               <div className="min-w-0">
-                                <h3 className="text-sm font-medium">
+                                <h2 className="text-lg font-semibold tracking-tight">
                                   Identity
-                                </h3>
+                                </h2>
                                 <p className="mt-1 text-sm font-normal text-muted-foreground">
                                   Your keypair and NIP-05 handle are fixed for
                                   this device.
@@ -961,7 +961,7 @@ export function ProfileSettingsCard({
       >
         <div className="flex items-center justify-between gap-4 px-1">
           <div className="min-w-0 space-y-1">
-            <h2 className="text-sm font-medium">Sign out</h2>
+            <h2 className="text-lg font-semibold tracking-tight">Sign out</h2>
             <p className="text-sm text-muted-foreground">
               Removes your identity key and all local app data from this device.
               Back up your private key (nsec) first — this cannot be undone.

desktop/src/features/settings/ui/SettingsPanels.tsx

@@ -179,7 +179,7 @@ export const settingsSections: SettingsSectionDescriptor[] = [
   },
   {
     value: "community-members",
-    label: "Community Access",
+    label: "Community access",
     icon: LockKeyhole,
   },
   {
@@ -189,13 +189,13 @@ export const settingsSections: SettingsSectionDescriptor[] = [
   },
   {
     value: "custom-emoji",
-    label: "Custom Emoji",
+    label: "Custom emoji",
     icon: Smile,
     featureGate: "custom-emoji",
   },
   {
     value: "local-archive",
-    label: "Local Archive",
+    label: "Local archive",
     icon: Archive,
   },
   {

desktop/src/features/settings/ui/SettingsSectionHeader.tsx

@@ -1,5 +1,11 @@
 import type { ReactNode } from "react";
 
+import { PageHeader } from "@/shared/ui/PageHeader";
+
+/**
+ * Page title for a Settings card. Thin wrapper over the shared {@link PageHeader}
+ * that preserves the `mb-12` spacing every Settings card relies on.
+ */
 export function SettingsSectionHeader({
   action,
   description,
@@ -9,23 +15,12 @@ export function SettingsSectionHeader({
   description: ReactNode;
   title: ReactNode;
 }) {
-  const copy = (
-    <>
-      <h2 className="text-2xl font-semibold tracking-tight">{title}</h2>
-      <p className="text-base font-normal text-muted-foreground">
-        {description}
-      </p>
-    </>
+  return (
+    <PageHeader
+      action={action}
+      className="mb-12"
+      description={description}
+      title={title}
+    />
   );
-
-  if (action) {
-    return (
-      <div className="mb-12 flex min-w-0 items-start justify-between gap-4">
-        <div className="min-w-0 space-y-1">{copy}</div>
-        <div className="shrink-0">{action}</div>
-      </div>
-    );
-  }
-
-  return <div className="mb-12 min-w-0 space-y-1">{copy}</div>;
 }

desktop/src/features/settings/ui/SoundPicker.tsx

@@ -113,7 +113,7 @@ export function SoundPicker({
                   <span>{name}</span>
                   <span className="flex items-center gap-2">
                     {name === recommended ? (
-                      <span className="text-2xs uppercase tracking-wide text-muted-foreground">
+                      <span className="text-2xs font-semibold uppercase tracking-wide text-muted-foreground">
                         rec.
                       </span>
                     ) : null}

desktop/src/shared/ui/PageHeader.tsx

@@ -0,0 +1,115 @@
+import type { ReactNode } from "react";
+
+import { cn } from "@/shared/lib/cn";
+
+type HeaderProps = {
+  /** Optional trailing content (buttons, menus) aligned to the header's end. */
+  action?: ReactNode;
+  className?: string;
+  /** Muted supporting line rendered beneath the title. */
+  description?: ReactNode;
+  title: ReactNode;
+};
+
+/**
+ * Level 1 of the shared header ramp: one per page (a Settings card, the Agents
+ * page). Renders the page's single `h1`. Pair with {@link SectionHeader} for
+ * peer sections within the page and {@link SubsectionLabel} for the smallest
+ * grouping labels.
+ */
+export function PageHeader({
+  action,
+  className,
+  description,
+  title,
+}: HeaderProps) {
+  const copy = (
+    <>
+      <h1 className="text-2xl font-semibold tracking-tight">{title}</h1>
+      {description ? (
+        <p className="text-base font-normal text-muted-foreground">
+          {description}
+        </p>
+      ) : null}
+    </>
+  );
+
+  if (action) {
+    return (
+      <div
+        className={cn(
+          "flex min-w-0 items-start justify-between gap-4",
+          className,
+        )}
+      >
+        <div className="min-w-0 space-y-1">{copy}</div>
+        <div className="shrink-0">{action}</div>
+      </div>
+    );
+  }
+
+  return <div className={cn("min-w-0 space-y-1", className)}>{copy}</div>;
+}
+
+/**
+ * Level 2 of the shared header ramp: a peer section within a page (Agent
+ * defaults, Teams, Profile info). Renders an `h2` one step down from
+ * {@link PageHeader}.
+ */
+export function SectionHeader({
+  action,
+  className,
+  description,
+  title,
+}: HeaderProps) {
+  const copy = (
+    <>
+      <h2 className="text-lg font-semibold tracking-tight">{title}</h2>
+      {description ? (
+        <p className="text-sm font-normal text-muted-foreground">
+          {description}
+        </p>
+      ) : null}
+    </>
+  );
+
+  if (action) {
+    return (
+      <div
+        className={cn(
+          "flex min-w-0 items-start justify-between gap-3",
+          className,
+        )}
+      >
+        <div className="min-w-0 space-y-0.5">{copy}</div>
+        <div className="shrink-0">{action}</div>
+      </div>
+    );
+  }
+
+  return <div className={cn("min-w-0 space-y-0.5", className)}>{copy}</div>;
+}
+
+/**
+ * Level 3 of the shared header ramp: the smallest grouping label (field-group
+ * eyebrows, table headers). Replaces the assorted uppercase/tracking variants
+ * with one canonical style.
+ */
+export function SubsectionLabel({
+  children,
+  className,
+}: {
+  children: ReactNode;
+  className?: string;
+}) {
+  return (
+    <p
+      className={cn(
+        "text-2xs font-semibold uppercase tracking-wide text-muted-foreground",
+        className,
+      )}
+    >
+      {children}
+    </p>
+  );
+}