From 12234c7b459cfe2542e1160d26e179c19bd606c4 Mon Sep 17 00:00:00 2001
From: idevlab <idevlab@outlook.com>
Date: Wed, 16 Sep 2026 15:53:32 +0800
Subject: [PATCH 1/2] refactor(desktop): unify settings page rhythm and layout

- converge every settings tab on one 48rem measure
- route appearance and memory headings through shared section primitives
- align SettingsSection title weight to 600 and render Usage via PageHeader
- make `sm` button an alias of the 28px `compact` size
- add settingsRhythmContract test and SDLC records
---
 .../components/business/settings-section.tsx  |   2 +-
 apps/desktop/src/components/ui/button.tsx     |   2 +-
 .../src/settings/AppearanceSettings.tsx       | 107 ++++++----------
 apps/desktop/src/settings/MemorySettings.tsx  |  13 +-
 apps/desktop/src/settings/SettingsPage.tsx    |   9 +-
 .../src/settings/SettingsPrimitives.tsx       |  15 ++-
 .../src/settings/appearance-settings.css      |  51 +-------
 apps/desktop/src/settings/memory-settings.css |  16 +--
 apps/desktop/src/settings/settings-page.css   |  23 +---
 apps/desktop/src/usage/Usage.tsx              |  15 +--
 .../desktop/tests/appearanceSettings.test.tsx |   6 +-
 .../tests/settingsLayoutContract.test.ts      |   7 +-
 .../tests/settingsRhythmContract.test.ts      | 118 ++++++++++++++++++
 .../intent.md                                 |  50 ++++++++
 .../plan.md                                   |  60 +++++++++
 .../spec.md                                   |  58 +++++++++
 .../verification.md                           |  59 +++++++++
 17 files changed, 433 insertions(+), 178 deletions(-)
 create mode 100644 apps/desktop/tests/settingsRhythmContract.test.ts
 create mode 100644 docs/sdlc/changes/2026-09-16-unify-settings-page-rhythm/intent.md
 create mode 100644 docs/sdlc/changes/2026-09-16-unify-settings-page-rhythm/plan.md
 create mode 100644 docs/sdlc/changes/2026-09-16-unify-settings-page-rhythm/spec.md
 create mode 100644 docs/sdlc/changes/2026-09-16-unify-settings-page-rhythm/verification.md

diff --git a/apps/desktop/src/components/business/settings-section.tsx b/apps/desktop/src/components/business/settings-section.tsx
index d0a4bbfd..379ea923 100644
--- a/apps/desktop/src/components/business/settings-section.tsx
+++ b/apps/desktop/src/components/business/settings-section.tsx
@@ -33,7 +33,7 @@ function SettingsSection({
           <h2
             id={accessibleHeadingId}
             data-slot="settings-section-title"
-            className="text-body text-content font-medium"
+            className="text-body text-content font-semibold"
           >
             {title}
           </h2>
diff --git a/apps/desktop/src/components/ui/button.tsx b/apps/desktop/src/components/ui/button.tsx
index 5b31ab5b..c036e170 100644
--- a/apps/desktop/src/components/ui/button.tsx
+++ b/apps/desktop/src/components/ui/button.tsx
@@ -31,7 +31,7 @@ const buttonVariants = cva(
         field:
           "h-control-field gap-inline px-surface-inset has-[>svg]:px-module-inset",
         xs: "h-control-mini rounded-control text-metadata gap-1 px-2 has-[>svg]:px-1.5 [&_svg:not([class*='size-'])]:size-3",
-        sm: "h-control-mini rounded-control has-[>svg]:px-module-inset gap-1.5 px-3",
+        sm: "h-control-mini gap-inline px-surface-inset has-[>svg]:px-module-inset",
         lg: "h-control-field rounded-control px-6 has-[>svg]:px-4",
         icon: "size-control",
         "icon-xs":
diff --git a/apps/desktop/src/settings/AppearanceSettings.tsx b/apps/desktop/src/settings/AppearanceSettings.tsx
index 2e20504d..21f052b8 100644
--- a/apps/desktop/src/settings/AppearanceSettings.tsx
+++ b/apps/desktop/src/settings/AppearanceSettings.tsx
@@ -2,6 +2,7 @@ import { useEffect, useRef, useState } from "react";
 
 import { SettingRow } from "@/components/business/setting-row";
 import { SettingToggle } from "@/components/business/setting-toggle";
+import { SettingsSection } from "@/components/business/settings-section";
 import { ViewSwitcher } from "@/components/business/view-switcher";
 import { Button } from "@/components/ui/button";
 import { Copy, Download, Plus, Trash2, Upload } from "@/components/ui/icons";
@@ -664,16 +665,10 @@ export function AppearanceSettings({
 
   return (
     <div className="appearance-settings">
-      <section
-        className="appearance-section"
-        aria-labelledby="appearance-color-scheme"
+      <SettingsSection
+        title={t("settings.colorScheme")}
+        headingId="appearance-color-scheme"
       >
-        <h2
-          id="appearance-color-scheme"
-          className="appearance-settings-heading"
-        >
-          {t("settings.colorScheme")}
-        </h2>
         <div
           className="appearance-scheme-grid"
           role="radiogroup"
@@ -694,15 +689,12 @@ export function AppearanceSettings({
             </label>
           ))}
         </div>
-      </section>
+      </SettingsSection>
 
-      <section
-        className="appearance-section"
-        aria-labelledby="appearance-typography"
+      <SettingsSection
+        title={t("settings.typography")}
+        headingId="appearance-typography"
       >
-        <h2 id="appearance-typography" className="appearance-settings-heading">
-          {t("settings.typography")}
-        </h2>
         <div className="appearance-profile-grid">
           {PROFILE_SCHEMES.map((scheme) => (
             <TypographyProfileEditor
@@ -734,17 +726,13 @@ export function AppearanceSettings({
             onChange={(codeFontSize) => setAppearanceSettings({ codeFontSize })}
           />
         </div>
-      </section>
+      </SettingsSection>
 
-      <section
-        className="appearance-section"
-        aria-labelledby="appearance-themes"
-      >
-        <div className="appearance-section-header">
-          <h2 id="appearance-themes" className="appearance-settings-heading">
-            {t("settings.themes")}
-          </h2>
-          <div className="appearance-section-actions">
+      <SettingsSection
+        title={t("settings.themes")}
+        headingId="appearance-themes"
+        actions={
+          <>
             <Button
               variant="secondary"
               size="sm"
@@ -774,8 +762,9 @@ export function AppearanceSettings({
               }
               tabIndex={-1}
             />
-          </div>
-        </div>
+          </>
+        }
+      >
         <div className="appearance-theme-grid">
           {catalog.map((theme) => (
             <ThemeCard
@@ -789,27 +778,18 @@ export function AppearanceSettings({
             />
           ))}
         </div>
-      </section>
-
-      <section
-        className="appearance-section appearance-editor-section"
-        aria-labelledby="appearance-theme-editor"
-      >
-        <div className="appearance-section-header">
-          <div>
-            <h2
-              id="appearance-theme-editor"
-              className="appearance-settings-heading"
-            >
-              {t("settings.themeEditor")}
-            </h2>
-            <p className="appearance-section-hint">
-              {activeTheme.builtin
-                ? t("settings.builtinThemeHint")
-                : t("settings.customThemeHint")}
-            </p>
-          </div>
-          <div className="appearance-section-actions">
+      </SettingsSection>
+
+      <SettingsSection
+        title={t("settings.themeEditor")}
+        headingId="appearance-theme-editor"
+        description={
+          activeTheme.builtin
+            ? t("settings.builtinThemeHint")
+            : t("settings.customThemeHint")
+        }
+        actions={
+          <>
             <Button
               variant="ghost"
               size="sm"
@@ -829,8 +809,9 @@ export function AppearanceSettings({
                 <Trash2 />
               </TooltipButton>
             )}
-          </div>
-        </div>
+          </>
+        }
+      >
         <div className="appearance-editor-surface">
           {!activeTheme.builtin && (
             <SettingRow
@@ -865,15 +846,12 @@ export function AppearanceSettings({
             />
           </div>
         </div>
-      </section>
+      </SettingsSection>
 
-      <section
-        className="appearance-section"
-        aria-labelledby="appearance-surfaces"
+      <SettingsSection
+        title={t("settings.surfaces")}
+        headingId="appearance-surfaces"
       >
-        <h2 id="appearance-surfaces" className="appearance-settings-heading">
-          {t("settings.surfaces")}
-        </h2>
         <div className="appearance-profile-grid">
           {PROFILE_SCHEMES.map((scheme) => (
             <SurfaceProfileEditor
@@ -885,15 +863,12 @@ export function AppearanceSettings({
             />
           ))}
         </div>
-      </section>
+      </SettingsSection>
 
-      <section
-        className="appearance-section"
-        aria-labelledby="appearance-preferences"
+      <SettingsSection
+        title={t("settings.appearancePreferences")}
+        headingId="appearance-preferences"
       >
-        <h2 id="appearance-preferences" className="appearance-settings-heading">
-          {t("settings.appearancePreferences")}
-        </h2>
         <div className="appearance-setting-group">
           <SettingToggle
             label={t("settings.pointerCursors")}
@@ -954,7 +929,7 @@ export function AppearanceSettings({
             />
           </SettingRow>
         </div>
-      </section>
+      </SettingsSection>
 
       {status && (
         <p className="appearance-status" role="status">
diff --git a/apps/desktop/src/settings/MemorySettings.tsx b/apps/desktop/src/settings/MemorySettings.tsx
index 44471676..c5817c45 100644
--- a/apps/desktop/src/settings/MemorySettings.tsx
+++ b/apps/desktop/src/settings/MemorySettings.tsx
@@ -85,6 +85,7 @@ import {
   originLabelKey,
 } from "./memory-model";
 import type { MemoryFilter, MemoryView } from "./memory-model";
+import { GroupHeading } from "./SettingsPrimitives";
 
 import "./memory-settings.css";
 
@@ -616,7 +617,7 @@ function DetailPanel({
       </div>
       <section className="memory-detail-section">
         <div className="memory-detail-section-title">
-          <h3>{t("memory.evidence")}</h3>
+          <GroupHeading className="pt-0">{t("memory.evidence")}</GroupHeading>
           <Button
             variant="ghost"
             size="xs"
@@ -662,7 +663,7 @@ function DetailPanel({
         )}
       </section>
       <section className="memory-detail-section">
-        <h3>{t("memory.usageHistory")}</h3>
+        <GroupHeading className="pt-0">{t("memory.usageHistory")}</GroupHeading>
         {usages.length === 0 ? (
           <p className="memory-detail-muted">{t("memory.noUsage")}</p>
         ) : (
@@ -1061,7 +1062,9 @@ export function MemorySettingsPage({
         </summary>
         <div className="memory-disclosure-body">
           <div className="memory-policy-column">
-            <h2>{t("memory.globalDefaults")}</h2>
+            <GroupHeading className="pt-0">
+              {t("memory.globalDefaults")}
+            </GroupHeading>
             <SettingToggle
               checked={settings.enabled}
               label={t("memory.enabled")}
@@ -1093,7 +1096,9 @@ export function MemorySettingsPage({
             />
           </div>
           <div className="memory-policy-column">
-            <h2>{t("memory.projectOverrides")}</h2>
+            <GroupHeading className="pt-0">
+              {t("memory.projectOverrides")}
+            </GroupHeading>
             <p className="text-metadata text-muted-foreground">
               {t("memory.projectOverridesHint")}
             </p>
diff --git a/apps/desktop/src/settings/SettingsPage.tsx b/apps/desktop/src/settings/SettingsPage.tsx
index d07969b6..5c9a9022 100644
--- a/apps/desktop/src/settings/SettingsPage.tsx
+++ b/apps/desktop/src/settings/SettingsPage.tsx
@@ -31,7 +31,6 @@ import {
   SelectValue,
 } from "@/components/ui/select";
 import { cssVars } from "@/lib/cssVars";
-import { cn } from "@/lib/utils";
 
 import { resetVisualAppearanceSettings } from "../appearance";
 import {
@@ -463,13 +462,7 @@ export function SettingsPage({
         </header>
 
         <ScrollArea key={tab} className="min-h-0 flex-1">
-          <div
-            className={cn(
-              "settings-page mx-auto w-full",
-              tab === "profile" && "settings-profile-page",
-              tab === "worktrees" && "settings-worktrees-page"
-            )}
-          >
+          <div className="settings-page mx-auto w-full">
             {tab === "project" && onSelectProject && (
               <Select
                 value={projectPath}
diff --git a/apps/desktop/src/settings/SettingsPrimitives.tsx b/apps/desktop/src/settings/SettingsPrimitives.tsx
index bd72fa14..e40bbfee 100644
--- a/apps/desktop/src/settings/SettingsPrimitives.tsx
+++ b/apps/desktop/src/settings/SettingsPrimitives.tsx
@@ -55,9 +55,20 @@ export function ProjectRow(props: RowProps) {
   );
 }
 
-export function GroupHeading({ children }: { children: ReactNode }) {
+export function GroupHeading({
+  children,
+  className,
+}: {
+  children: ReactNode;
+  className?: string;
+}) {
   return (
-    <h3 className="pt-section text-body text-foreground font-semibold">
+    <h3
+      className={cn(
+        "pt-section text-body text-content font-semibold",
+        className
+      )}
+    >
       {children}
     </h3>
   );
diff --git a/apps/desktop/src/settings/appearance-settings.css b/apps/desktop/src/settings/appearance-settings.css
index affd9dc5..fb741737 100644
--- a/apps/desktop/src/settings/appearance-settings.css
+++ b/apps/desktop/src/settings/appearance-settings.css
@@ -6,44 +6,9 @@
   gap: var(--ds-space-page-section);
 }
 
-.appearance-section {
-  display: flex;
-  min-width: 0;
-  flex-direction: column;
-  gap: var(--ds-space-surface-inset);
-}
-
-.appearance-section-header {
-  display: flex;
-  min-width: 0;
-  align-items: flex-end;
-  justify-content: space-between;
-  gap: var(--ds-space-section);
-}
-
-.appearance-section-actions {
-  display: flex;
-  min-width: 0;
-  flex-wrap: wrap;
-  align-items: center;
-  justify-content: flex-end;
-  gap: var(--ds-space-control-group);
-}
-
-.appearance-settings-heading {
-  margin: 0;
-  color: var(--ds-color-text);
-  font-size: var(--ds-type-section-size);
-  font-weight: var(--ds-font-weight-medium);
-  line-height: var(--ds-type-section-leading);
-}
-
-.appearance-section-hint {
-  max-width: 36rem;
-  margin: var(--ds-space-optical) 0 0;
-  color: var(--ds-color-text-muted);
-  font-size: var(--ds-type-body-size);
-  line-height: var(--ds-type-body-leading);
+/* The typography section stacks two blocks inside one shared SettingsSection content. */
+.appearance-profile-grid + .appearance-setting-group {
+  margin-top: var(--ds-space-surface-inset);
 }
 
 .appearance-scheme-grid {
@@ -564,16 +529,6 @@
   .appearance-profile-grid {
     grid-template-columns: minmax(0, 1fr);
   }
-
-  .appearance-section-header {
-    align-items: flex-start;
-    flex-direction: column;
-    gap: var(--ds-space-module-inset);
-  }
-
-  .appearance-section-actions {
-    justify-content: flex-start;
-  }
 }
 
 @container (max-width: 30rem) {
diff --git a/apps/desktop/src/settings/memory-settings.css b/apps/desktop/src/settings/memory-settings.css
index 7cd6f862..1cac6082 100644
--- a/apps/desktop/src/settings/memory-settings.css
+++ b/apps/desktop/src/settings/memory-settings.css
@@ -24,7 +24,7 @@
 .memory-disclosure {
   overflow: clip;
   border-radius: var(--ds-radius-module);
-  background: var(--ds-color-fill-quiet);
+  background: var(--ds-color-surface);
   box-shadow: inset 0 0 0 var(--hairline-width) var(--ds-color-fill-rest);
 }
 .memory-disclosure summary {
@@ -81,19 +81,13 @@
 .memory-disclosure-body {
   display: grid;
   grid-template-columns: repeat(2, minmax(0, 1fr));
-  background: var(--background);
 }
 .memory-policy-column {
   min-width: 0;
   padding: 0.75rem;
 }
 .memory-policy-column + .memory-policy-column {
-  background: var(--ds-color-fill-quiet);
-}
-.memory-policy-column h2 {
-  margin-bottom: 0.25rem;
-  font-size: var(--ds-type-metadata-size);
-  font-weight: 600;
+  box-shadow: inset var(--hairline-width) 0 0 var(--ds-color-fill-rest);
 }
 .memory-safety-note,
 .memory-conflict-note {
@@ -376,10 +370,6 @@
   margin-top: 1rem;
   padding-top: 0.75rem;
 }
-.memory-detail-section h3 {
-  font-size: var(--ds-type-metadata-size);
-  font-weight: 600;
-}
 .memory-detail-muted,
 .memory-empty-state {
   padding-block: 1.5rem;
@@ -465,7 +455,7 @@
     flex: 1;
   }
   .memory-policy-column + .memory-policy-column {
-    background: var(--ds-color-fill-quiet);
+    box-shadow: inset 0 var(--hairline-width) 0 var(--ds-color-fill-rest);
   }
   .memory-toolbar {
     grid-template-columns: minmax(0, 1fr) minmax(7rem, 0.7fr);
diff --git a/apps/desktop/src/settings/settings-page.css b/apps/desktop/src/settings/settings-page.css
index 3987d678..8adbfa0e 100644
--- a/apps/desktop/src/settings/settings-page.css
+++ b/apps/desktop/src/settings/settings-page.css
@@ -43,20 +43,11 @@
   margin-left: auto;
 }
 
-.settings-profile-page {
-  max-width: 64rem;
-  padding: var(--ds-space-page) var(--ds-space-page) var(--ds-space-page-end);
-}
-
-.settings-worktrees-page {
-  max-width: 64rem;
-}
-
 .worktree-policy-card {
   overflow: hidden;
   margin-top: var(--ds-space-module-inset);
   border-radius: var(--ds-radius-module);
-  background: var(--ds-color-fill-quiet);
+  background: var(--ds-color-surface);
   box-shadow: var(--ds-elevation-surface);
 }
 
@@ -93,7 +84,7 @@
 .worktree-project-card {
   overflow: hidden;
   border-radius: var(--ds-radius-module);
-  background: var(--ds-color-fill-quiet);
+  background: var(--ds-color-surface);
   box-shadow: var(--ds-elevation-surface);
 }
 
@@ -189,7 +180,7 @@
 .profile-editor,
 .profile-activity-surface {
   border-radius: var(--ds-radius-module);
-  background: var(--ds-color-fill-quiet);
+  background: var(--ds-color-surface);
 }
 
 .profile-editor {
@@ -342,19 +333,11 @@
     margin-left: 0;
   }
 
-  .settings-profile-page {
-    padding: 1rem 1rem var(--ds-space-page-end);
-  }
-
   .session-import-result {
     align-items: stretch;
     flex-direction: column;
   }
 
-  .settings-worktrees-page {
-    padding: 1rem 1rem var(--ds-space-page-end);
-  }
-
   .worktree-settings-row {
     align-items: stretch;
     flex-direction: column;
diff --git a/apps/desktop/src/usage/Usage.tsx b/apps/desktop/src/usage/Usage.tsx
index d65afd42..14939ac3 100644
--- a/apps/desktop/src/usage/Usage.tsx
+++ b/apps/desktop/src/usage/Usage.tsx
@@ -1,5 +1,6 @@
 import { useEffect, useRef, useState, useCallback } from "react";
 
+import { PageHeader } from "@/components/business/page-header";
 import { QuotaProgress } from "@/components/business/quota-progress";
 import { Button } from "@/components/ui/button";
 import {
@@ -697,15 +698,11 @@ function UsageView({
         </DialogHeader>
       ) : (
         <div className="pb-3">
-          <div className="flex items-center gap-2">
-            <h1 className="text-page font-semibold tracking-tight">
-              {t("usage.title")}
-            </h1>
-            {controls}
-          </div>
-          <p className="text-metadata text-muted-foreground pt-1.5">
-            {t("usage.description")}
-          </p>
+          <PageHeader
+            title={t("usage.title")}
+            description={t("usage.description")}
+            actions={controls}
+          />
         </div>
       )}
 
diff --git a/apps/desktop/tests/appearanceSettings.test.tsx b/apps/desktop/tests/appearanceSettings.test.tsx
index 56e0adc5..9ff66ab5 100644
--- a/apps/desktop/tests/appearanceSettings.test.tsx
+++ b/apps/desktop/tests/appearanceSettings.test.tsx
@@ -120,9 +120,9 @@ describe("Appearance settings", () => {
         .querySelector('[aria-label="Interface font size"]')
         ?.closest('[data-slot="setting-row"]')
     ).not.toBeNull();
-    expect(view.container.querySelectorAll(".appearance-section")).toHaveLength(
-      6
-    );
+    expect(
+      view.container.querySelectorAll('[data-slot="settings-section"]')
+    ).toHaveLength(6);
     expect(
       view.container.querySelectorAll(".appearance-setting-group")
     ).toHaveLength(2);
diff --git a/apps/desktop/tests/settingsLayoutContract.test.ts b/apps/desktop/tests/settingsLayoutContract.test.ts
index 4b27333a..9b2a8c5c 100644
--- a/apps/desktop/tests/settingsLayoutContract.test.ts
+++ b/apps/desktop/tests/settingsLayoutContract.test.ts
@@ -161,7 +161,7 @@ describe("Settings page layout contract", () => {
     expect(source).toContain(
       "<ProfileSettings providerNames={providerNames} />"
     );
-    expect(styles).toContain(".settings-profile-page");
+    expect(styles).not.toContain(".settings-profile-page");
     expect(styles).toContain(".profile-activity-grid");
     expect(styles).toContain("@container settings-page (max-width: 40rem)");
     expect(styles).toMatch(
@@ -187,8 +187,9 @@ describe("Settings page layout contract", () => {
     expect(appearanceStyles).toMatch(
       /\.appearance-settings\s*{[^}]*display:\s*flex;[^}]*flex-direction:\s*column;[^}]*gap:\s*var\(--ds-space-page-section\);/s
     );
-    expect(appearanceStyles).toMatch(
-      /\.appearance-section\s*{[^}]*gap:\s*var\(--ds-space-surface-inset\);/s
+    expect(appearanceStyles).not.toContain(".appearance-section");
+    expect(appearanceStyles).toContain(
+      ".appearance-profile-grid + .appearance-setting-group"
     );
     expect(appearanceStyles).toContain(".appearance-setting-group");
     expect(appearanceStyles).toContain(".appearance-editor-surface");
diff --git a/apps/desktop/tests/settingsRhythmContract.test.ts b/apps/desktop/tests/settingsRhythmContract.test.ts
new file mode 100644
index 00000000..a9452f07
--- /dev/null
+++ b/apps/desktop/tests/settingsRhythmContract.test.ts
@@ -0,0 +1,118 @@
+import { describe, expect, test } from "bun:test";
+import { readFileSync } from "node:fs";
+
+const normalizeSource = (source: string) => source.replaceAll(/\r\n?/gu, "\n");
+const readSource = (relativePath: string) =>
+  normalizeSource(
+    readFileSync(new URL(relativePath, import.meta.url), "utf-8")
+  );
+
+const button = readSource("../src/components/ui/button.tsx");
+
+const settingsPage = readSource("../src/settings/SettingsPage.tsx");
+const settingsPageCss = readSource("../src/settings/settings-page.css");
+const settingsSection = readSource(
+  "../src/components/business/settings-section.tsx"
+);
+const settingsPrimitives = readSource("../src/settings/SettingsPrimitives.tsx");
+const appearance = readSource("../src/settings/AppearanceSettings.tsx");
+const appearanceCss = readSource("../src/settings/appearance-settings.css");
+const memory = readSource("../src/settings/MemorySettings.tsx");
+const memoryCss = readSource("../src/settings/memory-settings.css");
+const usage = readSource("../src/usage/Usage.tsx");
+
+describe("settings rhythm contract", () => {
+  test("normalizes source contracts across platform line endings", () => {
+    expect(normalizeSource("first\r\nsecond\rthird")).toBe(
+      "first\nsecond\nthird"
+    );
+  });
+
+  test("keeps one 48rem measure for every settings tab", () => {
+    expect(settingsPage).toContain('className="settings-page mx-auto w-full"');
+    expect(settingsPage).not.toContain("settings-profile-page");
+    expect(settingsPage).not.toContain("settings-worktrees-page");
+    expect(settingsPageCss).not.toContain(".settings-profile-page");
+    expect(settingsPageCss).not.toContain(".settings-worktrees-page");
+  });
+
+  test("renders appearance sections through the shared section anatomy", () => {
+    expect(appearance).toContain(
+      'import { SettingsSection } from "@/components/business/settings-section";'
+    );
+    expect(appearance.match(/<SettingsSection/gu)).toHaveLength(6);
+    for (const headingId of [
+      "appearance-color-scheme",
+      "appearance-typography",
+      "appearance-themes",
+      "appearance-theme-editor",
+      "appearance-surfaces",
+      "appearance-preferences",
+    ]) {
+      expect(appearance).toContain(`headingId="${headingId}"`);
+    }
+    expect(appearance).not.toContain("appearance-settings-heading");
+    expect(appearance).not.toContain("appearance-section");
+    expect(appearanceCss).not.toContain(".appearance-settings-heading");
+    expect(appearanceCss).not.toContain(".appearance-section");
+  });
+
+  test("renders memory section headings through the shared group heading", () => {
+    expect(memory).toContain(
+      'import { GroupHeading } from "./SettingsPrimitives";'
+    );
+    expect(memory.match(/<GroupHeading className="pt-0">/gu)).toHaveLength(4);
+    expect(memory).not.toMatch(/<h[23]>\{t\("memory\./u);
+    expect(memoryCss).not.toContain(".memory-policy-column h2");
+    expect(memoryCss).not.toContain(".memory-detail-section h3");
+  });
+
+  test("renders the usage tab title through the shared page header", () => {
+    expect(usage).toContain(
+      'import { PageHeader } from "@/components/business/page-header";'
+    );
+    expect(usage).toContain("<PageHeader");
+    expect(usage).not.toContain("text-page font-semibold tracking-tight");
+  });
+
+  test("keeps settings module cards on the surface plane", () => {
+    const ruleBlock = (css: string, selector: string) => {
+      const start = css.indexOf(`${selector} {`);
+      return start < 0 ? "" : css.slice(start, css.indexOf("}", start));
+    };
+    for (const [css, selector] of [
+      [settingsPageCss, ".worktree-policy-card"],
+      [settingsPageCss, ".worktree-project-card"],
+      [settingsPageCss, ".profile-editor,\n.profile-activity-surface"],
+      [memoryCss, ".memory-disclosure"],
+    ] as const) {
+      const block = ruleBlock(css, selector);
+      expect(block).toContain("background: var(--ds-color-surface);");
+      expect(block).not.toContain("fill-quiet");
+    }
+    expect(memoryCss).toContain(
+      ".memory-policy-column + .memory-policy-column {\n  box-shadow: inset var(--hairline-width) 0 0 var(--ds-color-fill-rest);\n}"
+    );
+    expect(ruleBlock(memoryCss, ".memory-disclosure-body")).not.toContain(
+      "background:"
+    );
+  });
+
+  test("keeps one weight for the shared settings heading role", () => {
+    expect(settingsSection).toContain(
+      'className="text-body text-content font-semibold"'
+    );
+    expect(settingsPrimitives).toContain(
+      '"pt-section text-body text-content font-semibold",'
+    );
+    expect(settingsSection).not.toContain("font-medium");
+    expect(settingsPrimitives).not.toContain("font-medium");
+  });
+
+  test("keeps the 28px button sizes to one treatment", () => {
+    const collapsed = button.replaceAll(/\s+/gu, " ");
+    const sizeEntry = (name: string) =>
+      new RegExp(`${name}: "([^"]+)"`, "u").exec(collapsed)?.[1];
+    expect(sizeEntry("sm")).toBe(sizeEntry("compact"));
+  });
+});
diff --git a/docs/sdlc/changes/2026-09-16-unify-settings-page-rhythm/intent.md b/docs/sdlc/changes/2026-09-16-unify-settings-page-rhythm/intent.md
new file mode 100644
index 00000000..4b857ecb
--- /dev/null
+++ b/docs/sdlc/changes/2026-09-16-unify-settings-page-rhythm/intent.md
@@ -0,0 +1,50 @@
+---
+id: 2026-09-16-unify-settings-page-rhythm
+schema: 5
+stage: intent
+status: accepted
+owner: chenli
+created: 2026-09-16
+source: user
+risk: medium
+approved_by: chenli
+approved_at: 2026-09-16
+approval_source: "Direct request: 开始按照顺序打勾修复, following 还有页面风格和排版不统一（特别设置里面的页面） and the agreed repair order whose first item is the settings-page cohort."
+next_trigger: chenli reviews the verified work.
+---
+
+# Intent: Unify the settings page rhythm
+
+## Intent
+
+The user reports that page style and typography are inconsistent, especially inside Settings. A code
+survey confirms measurable divergence inside one shell:
+
+- two content measures: `.settings-page` 48rem versus `.settings-profile-page` and
+  `.settings-worktrees-page` at 64rem;
+- three page-title blocks: shared `Page`/`PageHeader` in most tabs, a hand-rolled
+  `text-page font-semibold tracking-tight` `h1` in `usage/Usage.tsx`, and the Profile identity `h1`;
+- four section-heading treatments: shared `SettingsSection` 14/600, an 18px
+  `.appearance-settings-heading`, a 14px local worktree `h2`, and raw Memory `h2`/`h3` whose only
+  style is file-local CSS at 12/600;
+- three grouped-row planes: `--ds-color-surface` for pets and appearance, `--ds-color-fill-quiet`
+  for the worktree policy card and the memory policy column;
+- one 28px button height spelled three ways (`sm`, `xs`, `compact`) with different padding and type.
+
+Outcome: one settings anatomy — one measure, one page-title block, one section-heading role, one
+grouped-row plane, one 28px button treatment — so any settings tab reads as the same product without
+per-page inspection.
+
+Constraints: visual and structural only. No behavior, data, copy, navigation, token value, radius,
+color, elevation, or motion change. Keep every `aria-labelledby` relationship and heading id. Keep
+the Profile identity hero (avatar, name, handle, bio, share) as that tab's header: it is a designed
+identity block, not a form header, and it already uses the shared page-title typography.
+
+Non-goals: the remaining design-consistency program (governance registry, status-language
+convergence, action budget, motion and focus follow-ups) stays in its own records. The dense `xs`
+button variant and the broader spacing-vocabulary cleanup are not decided here.
+
+## Non-goals
+
+No settings behavior or copy change, no new shared component, no token or appearance-palette change,
+and no removal of the `xs` button size in this change.
diff --git a/docs/sdlc/changes/2026-09-16-unify-settings-page-rhythm/plan.md b/docs/sdlc/changes/2026-09-16-unify-settings-page-rhythm/plan.md
new file mode 100644
index 00000000..d7384a40
--- /dev/null
+++ b/docs/sdlc/changes/2026-09-16-unify-settings-page-rhythm/plan.md
@@ -0,0 +1,60 @@
+---
+id: 2026-09-16-unify-settings-page-rhythm
+schema: 5
+stage: plan
+status: accepted
+owner: chenli
+created: 2026-09-16
+based_on: spec.md
+scope: apps/desktop/src/settings/SettingsPage.tsx, apps/desktop/src/settings/settings-page.css, apps/desktop/src/settings/SettingsPrimitives.tsx, apps/desktop/src/settings/AppearanceSettings.tsx, apps/desktop/src/settings/appearance-settings.css, apps/desktop/src/settings/MemorySettings.tsx, apps/desktop/src/settings/memory-settings.css, apps/desktop/src/usage/Usage.tsx, apps/desktop/src/components/ui/button.tsx, apps/desktop/src/components/business/settings-section.tsx, apps/desktop/tests/settingsRhythmContract.test.ts, apps/desktop/tests/settingsLayoutContract.test.ts, apps/desktop/tests/appearanceSettings.test.tsx, docs/sdlc/changes/2026-09-16-unify-settings-page-rhythm
+---
+
+# Plan: Unify the settings page rhythm
+
+## Plan
+
+1. `apps/desktop/src/settings/SettingsPage.tsx` and `settings-page.css` — drop the per-tab width
+   conditionals and the two 64rem rules so every tab uses `.settings-page` (48rem). (AC-1)
+2. `apps/desktop/src/settings/AppearanceSettings.tsx` and `appearance-settings.css` — convert the six
+   `.appearance-section` blocks to `SettingsSection`, moving section actions into its `actions` prop
+   and the hint into `description`; delete the superseded heading/section/hint rules and their
+   container-query overrides. (AC-2)
+3. `apps/desktop/src/settings/SettingsPrimitives.tsx` — let `GroupHeading` accept an optional
+   `className` for containers that already own their top spacing.
+4. `apps/desktop/src/settings/MemorySettings.tsx` and `memory-settings.css` — render the four Memory
+   section headings through `GroupHeading`; delete the local 12/600 `h2`/`h3` rules. (AC-3)
+5. `apps/desktop/src/usage/Usage.tsx` — replace the local page-title block with `PageHeader`, keeping
+   the existing bottom spacing holder. (AC-4)
+6. `settings-page.css` and `memory-settings.css` — `worktree-policy-card` and the memory policy
+   column move from `fill-quiet` to the `surface` card plane. (AC-5)
+7. `apps/desktop/src/components/ui/button.tsx` — make `size: "sm"` byte-identical to `size:
+   "compact"`. (AC-6)
+8. `apps/desktop/src/components/business/settings-section.tsx` — the shared section title moves from
+   Tailwind's 500 `font-medium` to the 600 weight that `GroupHeading` and `PageHeader` already use,
+   so the settings heading role has one treatment. (AC-2, found during rendered verification)
+9. `apps/desktop/tests/settingsRhythmContract.test.ts` — source-contract test in the
+   `composerGeometryContract.test.ts` style: asserts the removed classes/rules stay gone, the shared
+   anatomy and heading weight are used, and `sm`/`compact` stay identical.
+   `tests/settingsLayoutContract.test.ts` and `tests/appearanceSettings.test.tsx` encode the
+   superseded divergences and move to the unified contract in the same change.
+
+Checks by risk and affected behavior:
+
+- Desktop: `bun run lint`, `bunx tsc --noEmit`, `bun test`, `bun run build:renderer` from
+  `apps/desktop`. The existing `tests/appearanceSettings.test.tsx` mounts the real Appearance
+  component, so the conversion is exercised by the suite.
+- Rendered UI (AC-1, AC-2, AC-3, AC-4, AC-7): the desktop renderer was served with
+  `bun run dev:renderer --port 1420` (task-owned, no Core, the user's instance untouched) and driven
+  through the agent's collaborative browser: the UI Lab settings scenario for the shared section
+  anatomy, and the real empty-shell app for every settings tab's measure and heading role. If a
+  surface cannot render in this environment, the gap is recorded as residual risk instead of being
+  claimed.
+- Repository: `bun script/verify/sdlc.ts --worktree` before handoff.
+
+Temporary resources: the task-owned renderer log root
+`.codex/run/2026-09-16-unify-settings-page-rhythm/` and the Vite dev server on port 1420, plus the
+repository's ignored `apps/desktop/dist/` renderer output and bun cache. The dev server is stopped
+and the log removed before handoff; screenshots retained as Verification evidence.
+
+Rollback: `git revert` of the single commit; every edit is visual or structural markup with no data,
+protocol, or persistence surface.
diff --git a/docs/sdlc/changes/2026-09-16-unify-settings-page-rhythm/spec.md b/docs/sdlc/changes/2026-09-16-unify-settings-page-rhythm/spec.md
new file mode 100644
index 00000000..364365b2
--- /dev/null
+++ b/docs/sdlc/changes/2026-09-16-unify-settings-page-rhythm/spec.md
@@ -0,0 +1,58 @@
+---
+id: 2026-09-16-unify-settings-page-rhythm
+schema: 5
+stage: spec
+status: accepted
+owner: chenli
+created: 2026-09-16
+based_on: intent.md
+---
+
+# Spec: Unify the settings page rhythm
+
+## Design
+
+1. **One measure.** Every tab renders inside `.settings-page` (48rem), matching
+   `apps/desktop/layout-spec.json` `content.settings.maxWidth`. Delete `.settings-profile-page` and
+   `.settings-worktrees-page` and their `SettingsPage.tsx` conditionals. The Profile stat grid and
+   activity grid already have container-query fallbacks, so the narrower measure reflows instead of
+   overflowing.
+2. **One page-title block.** Tabs use `Page`/`PageHeader`. `usage/Usage.tsx` renders `PageHeader`
+   with its controls as `actions`, replacing the local `h1` + description block. Profile keeps its
+   identity hero, whose `h1` already consumes the shared page-title role, and is recorded here as the
+   one intentional variation rather than silently rebuilt.
+3. **One section-heading role.** Settings sections use the shared `SettingsSection` (title 14/600,
+   optional description, optional actions, 12px content inset) or the shared `GroupHeading` where the
+   container already owns the spacing, and both shared headings carry the same 14px/600 treatment —
+   `SettingsSection`'s 500-weight title was the outlier against `GroupHeading` and `PageHeader`.
+   Appearance's six sections and Memory's policy columns and
+   detail sections convert; `.appearance-settings-heading`, `.appearance-section`,
+   `.appearance-section-header`, `.appearance-section-actions`, `.appearance-section-hint`,
+   `.memory-policy-column h2`, and `.memory-detail-section h3` are removed. `GroupHeading` gains an
+   optional `className` so an already-spaced container can suppress its default top spacing.
+   The obsolete `.appearance-section-header`/`.appearance-section-actions` container-query overrides
+   go with them; `SettingsSection` already wraps its own header and actions.
+4. **One grouped-row plane.** Grouped setting rows use the documented card plane
+   `--ds-color-surface`: `.worktree-policy-card` and `.memory-policy-column + .memory-policy-column`
+   stop using `--ds-color-fill-quiet`, matching `.pet-setting-group` and `.appearance-setting-group`.
+   Result and status banners keep their own treatment and are out of scope.
+5. **One 28px button treatment.** `sm` becomes an alias of `compact` in `buttonVariants` (same
+   height, padding, gap, and typography), so the 60+ existing `size="sm"` call sites stop rendering a
+   second 28px look. `xs` remains the dense 12px variant and is untouched.
+
+## Acceptance criteria
+
+- [x] AC-1: Every settings tab renders inside one 48rem measure; no `.settings-profile-page`,
+  `.settings-worktrees-page`, or per-tab width override remains.
+- [x] AC-2: Appearance renders through the shared section anatomy; the removed `appearance-*`
+  section/heading rules are gone, every `appearance-*` heading id still labels its region, and
+  `SettingsSection` and `GroupHeading` render one 14px/600 heading treatment.
+- [x] AC-3: Memory section headings render the shared 14/600 role; the local 12/600 `h2`/`h3` rules
+  are gone.
+- [x] AC-4: Usage renders title and description through `PageHeader`; no hand-rolled page-title `h1`
+  remains in `usage/Usage.tsx`.
+- [x] AC-5: Worktree and Memory grouped rows sit on the surface plane; no `fill-quiet` grouped-row
+  card remains in settings.
+- [x] AC-6: `size="sm"` and `size="compact"` resolve to the same 28px button classes.
+- [x] AC-7: Desktop lint, type, tests, and renderer build pass, and a rendered settings capture in
+  light and dark shows one measure and one heading rhythm.
diff --git a/docs/sdlc/changes/2026-09-16-unify-settings-page-rhythm/verification.md b/docs/sdlc/changes/2026-09-16-unify-settings-page-rhythm/verification.md
new file mode 100644
index 00000000..e3182dc4
--- /dev/null
+++ b/docs/sdlc/changes/2026-09-16-unify-settings-page-rhythm/verification.md
@@ -0,0 +1,59 @@
+---
+id: 2026-09-16-unify-settings-page-rhythm
+schema: 5
+stage: verification
+status: passed
+owner: chenli
+created: 2026-09-16
+based_on: plan.md
+revision: "8d1f32d7 worktree baseline with the uncommitted change applied"
+verification_mode: owner
+verified_by: chenli
+verified_at: 2026-09-16
+release_target: none
+cleanup_status: complete
+---
+
+# Verification: Unify the settings page rhythm
+
+## Verification
+
+- AC-1: PASS — In the real renderer (`bun run dev:renderer --port 1420`, no Core) Appearance, Profile, Worktrees, Memory, Usage and Pets each measured `.settings-page` at `768px` (`getComputedStyle().maxWidth` and `getBoundingClientRect().width`); `settingsRhythmContract` and `settingsLayoutContract` assert the two width overrides are gone.
+- AC-2: PASS — The UI Lab settings scenario rendered 6 `[data-slot="settings-section"]` nodes with every title at `14px/600`, a 32px section gap and a 12px heading-to-content inset, matching `GroupHeading` and the 20px/600 `PageHeader`; `settingsRhythmContract` asserts the six `headingId`s survive, the removed `appearance-section*` rules stay gone and both shared headings carry the same weight class, and `appearanceSettings.test.tsx` mounts the real component.
+- AC-3: PASS — The Memory tab rendered "Global defaults" and "Project overrides" at `14px/600`; `settingsRhythmContract` asserts the four `GroupHeading` call sites and the absence of the local 12/600 `h2`/`h3` rules.
+- AC-4: PASS — The Usage tab rendered a `20px` page-header title with description and actions; `settingsRhythmContract` asserts no hand-rolled page-title `h1` remains in `usage/Usage.tsx`.
+- AC-5: PASS — `settingsRhythmContract` extracts each module rule block and asserts the `--ds-color-surface` background with no `fill-quiet`, plus the memory column hairline.
+- AC-6: PASS — `settingsRhythmContract` compares the `sm` and `compact` size entries in `button.tsx`; the diff makes them byte-identical.
+- AC-7: PASS — From `apps/desktop`: `bun run lint`, `bunx tsc --noEmit`, `bun test` (940 pass, 3 skip, 0 fail) and `bun run build:renderer`; rendered captures `browser-artifacts/browser-screenshot-localhost-mu3sfuce-db2d19b2.png` (light) and `browser-artifacts/browser-screenshot-localhost-mu3sg191-b8d2a6be.png` (dark), plus the per-tab measurements above.
+
+Verification finding: the first rendered pass showed `SettingsSection` titles at weight 500 against `GroupHeading`/`PageHeader` at 600 — one heading role with two weights. The shared section title moved to the 600 weight and both AC-2 and AC-7 were re-rendered and re-run on the corrected revision.
+
+Verdict: verified.
+Residual risk: the full-window captures ran against the Core-less empty shell, so populated row
+content was not exercised; Profile keeps its identity hero (no `PageHeader` title, recorded design
+variation) and its card labels stay at 14/400 and 12/500; the `--ds-font-weight-*` tokens are still
+not bridged to Tailwind utilities, so shared headings name Tailwind's `font-semibold` rather than the
+token; the dense `xs` button variant, the remaining legacy type aliases, and the legacy colour
+variables in `memory-settings.css` are later records in the agreed order.
+
+## Cleanup
+
+Removed: `apps/desktop/dist/` (48 MB renderer build output created by the AC-7 build), the
+task-owned `.codex/run/2026-09-16-unify-settings-page-rhythm/renderer.log` root, and the four
+superseded screenshots from the first rendered pass.
+Retained: two browser screenshots in `/Users/chenli/.t3/userdata/browser-artifacts/` referenced as
+AC-7 evidence.
+Retention owner: chenli.
+Cleanup trigger: remove with the next browser-artifact cleanup after review.
+Processes: the task-owned Vite dev server (pid 66134 on port 1420, then pid 18215 on port 1431, the
+latter chosen because another worktree's server already owned 1420 and was left untouched) was
+stopped; `lsof -nP -iTCP:1431 -sTCP:LISTEN` and `pgrep -fl "vite --port 1431"` match nothing.
+Evidence: `git status --porcelain` shows only the intended 12 modified files, the new contract test
+and this record bundle; `du -sh apps/desktop/dist` reported 48M before removal.
+
+## Review and release
+
+Approval: awaiting chenli's review of the verified work.
+Rollback: See plan.md.
+Release: No release requested; merge and external actions require their own authorization.
+Feedback: Link an Incident and regression Eval when a real failure occurs.

From 80ede079f1090cf014d4ae716e60a1d5badb162c Mon Sep 17 00:00:00 2001
From: idevlab <idevlab@outlook.com>
Date: Wed, 16 Sep 2026 15:58:12 +0800
Subject: [PATCH 2/2] docs: link PR #236 and the hosted CI result from the
 verified record

---
 .../2026-09-16-unify-settings-page-rhythm/verification.md   | 6 +++++-
 1 file changed, 5 insertions(+), 1 deletion(-)

diff --git a/docs/sdlc/changes/2026-09-16-unify-settings-page-rhythm/verification.md b/docs/sdlc/changes/2026-09-16-unify-settings-page-rhythm/verification.md
index e3182dc4..05e3af78 100644
--- a/docs/sdlc/changes/2026-09-16-unify-settings-page-rhythm/verification.md
+++ b/docs/sdlc/changes/2026-09-16-unify-settings-page-rhythm/verification.md
@@ -53,7 +53,11 @@ and this record bundle; `du -sh apps/desktop/dist` reported 48M before removal.
 
 ## Review and release
 
-Approval: awaiting chenli's review of the verified work.
+Approval: implementation and PR delivery were requested directly by the user (开始按照顺序打勾修复,
+then pr); merge and release are not authorized.
 Rollback: See plan.md.
 Release: No release requested; merge and external actions require their own authorization.
+Review: [PR #236](https://github.com/IchenDEV/codeTwo/pull/236) carries this change on branch
+t3code/cube-computer-ui-cleanup-study; the hosted CI Validate job passed (run 35070958654, job
+104712090561, 2m38s).
 Feedback: Link an Incident and regression Eval when a real failure occurs.