From 62cbc3401273b947d1ecad2e5e5c65e313eb5c8e Mon Sep 17 00:00:00 2001
From: flamboh <oliver.boorstein@gmail.com>
Date: Fri, 6 Nov 2026 05:12:50 +0000
Subject: [PATCH] fix(web): settings descriptions fill the row and stay two
 lines

Settings descriptions used text-balance and a 10rem minimum control
column, so long copy wrapped into narrow half-width lines.

Descriptions now use text-pretty, the control column sizes to its
content (dropdowns keep their 160px minimum), and a new
t3code/max-settings-description-length lint rule caps SettingsRow
descriptions at 200 characters of static text. The five descriptions
over the cap are shortened, with mobile copies kept in sync.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
---
 .../settings/ThreadSettingsSections.tsx       |  7 +--
 .../components/DatabaseStorageNotice.tsx      |  2 +-
 .../settings/DatabaseStorageNotice.tsx        |  2 +-
 .../components/settings/LabsSettingsPanel.tsx | 10 +--
 .../settings/VoiceSettingsPanel.tsx           |  2 +-
 .../components/settings/settingsLayout.tsx    |  6 +-
 oxlint-plugin-t3code/index.ts                 |  2 +
 .../max-settings-description-length.test.ts   | 43 +++++++++++++
 .../rules/max-settings-description-length.ts  | 63 +++++++++++++++++++
 vite.config.ts                                |  4 ++
 10 files changed, 126 insertions(+), 15 deletions(-)
 create mode 100644 oxlint-plugin-t3code/rules/max-settings-description-length.test.ts
 create mode 100644 oxlint-plugin-t3code/rules/max-settings-description-length.ts

diff --git a/apps/mobile/src/features/settings/ThreadSettingsSections.tsx b/apps/mobile/src/features/settings/ThreadSettingsSections.tsx
index 8aaae71673a0e..df463bd1f664c 100644
--- a/apps/mobile/src/features/settings/ThreadSettingsSections.tsx
+++ b/apps/mobile/src/features/settings/ThreadSettingsSections.tsx
@@ -268,7 +268,7 @@ function BetaSettingsSection() {
       </SettingsSection>
       <Text className="px-2 text-sm text-foreground-muted">
         Let agents on a machine work on your other machines, and theirs on it. Turn it on for each
-        machine. While it is off, nothing new starts over a link; tasks already running finish.
+        machine. While off, nothing new starts over a link; running tasks finish.
       </Text>
     </View>
   );
@@ -306,9 +306,8 @@ function ToolCallVisibilitySection() {
         ))}
       </SettingsSection>
       <Text className="px-2 text-sm text-foreground-muted">
-        Hide the commands, edits, and searches agents run, so a thread reads like a conversation.
-        Hide successful keeps calls that fail. Zen also hides the agent&apos;s in-between messages
-        and shows only final answers. Approvals, questions, and errors always show.
+        Hide the commands, edits, and searches agents run. Hide successful keeps failures. Zen shows
+        only final answers. Approvals, questions, and errors always show.
       </Text>
     </View>
   );
diff --git a/apps/mobile/src/features/settings/components/DatabaseStorageNotice.tsx b/apps/mobile/src/features/settings/components/DatabaseStorageNotice.tsx
index f492574db4339..963a94f607ae0 100644
--- a/apps/mobile/src/features/settings/components/DatabaseStorageNotice.tsx
+++ b/apps/mobile/src/features/settings/components/DatabaseStorageNotice.tsx
@@ -31,7 +31,7 @@ export function DatabaseStorageNotice({
   return (
     <SettingsSection
       title="Reclaim database space"
-      footer="Old history is cleaned up automatically, but these databases still hold the freed space. Run the command on each machine to return it to disk; it pauses and restarts the background service. Quit the desktop app first if it hosts the environment."
+      footer="These databases still hold space freed by history cleanup. Run the command on each machine to reclaim it. It restarts the background service. Quit the desktop app first if it hosts the environment."
     >
       {visible.map(({ environmentId, status }) => (
         <SettingsActionRow
diff --git a/apps/web/src/components/settings/DatabaseStorageNotice.tsx b/apps/web/src/components/settings/DatabaseStorageNotice.tsx
index 08ccf816a9e1a..732b26ebc3c5c 100644
--- a/apps/web/src/components/settings/DatabaseStorageNotice.tsx
+++ b/apps/web/src/components/settings/DatabaseStorageNotice.tsx
@@ -35,7 +35,7 @@ export function DatabaseStorageNotice({
     <SettingsSection id="storage-database" title="Database">
       <SettingsRow
         title="Reclaim freed database space"
-        description="Old history is cleaned up automatically, but these databases still hold the freed space. Run the command on each machine to return it to disk; it pauses and restarts the background service. Quit the desktop app first if it hosts the environment."
+        description="These databases still hold space freed by history cleanup. Run the command on each machine to reclaim it. It restarts the background service. Quit the desktop app first if it hosts the environment."
       />
       {visible.map(({ environmentId, status }) => (
         <SettingsRow
diff --git a/apps/web/src/components/settings/LabsSettingsPanel.tsx b/apps/web/src/components/settings/LabsSettingsPanel.tsx
index c9c63987cb69c..3ab93229b2c5a 100644
--- a/apps/web/src/components/settings/LabsSettingsPanel.tsx
+++ b/apps/web/src/components/settings/LabsSettingsPanel.tsx
@@ -91,7 +91,7 @@ function ToolCallVisibilityRow() {
   return (
     <SettingsRow
       {...searchableSetting("tool-call-visibility")}
-      description="Hide the commands, edits, and searches agents run, so a thread reads like a conversation. Hide successful keeps calls that fail. Zen also hides the agent's in-between messages and shows only final answers. Approvals, questions, and errors always show."
+      description="Hide the commands, edits, and searches agents run. Hide successful keeps failures. Zen shows only final answers. Approvals, questions, and errors always show."
       control={
         <div className="w-full sm:w-40">
           <Select
@@ -125,7 +125,7 @@ function GuestLinksRowWithSignIn() {
   return (
     <SettingsRow
       {...searchableSetting("guest-links")}
-      description="Share a thread with a guest who watches it live in their browser and sends messages you approve. Sign in to T3 Connect to use guest links."
+      description="Share a thread with a guest who watches it live in a browser and sends messages you approve. Sign in to T3 Connect to use guest links."
       control={
         <Button size="sm" variant="outline" onClick={openAuthPrompt}>
           Sign in
@@ -156,12 +156,12 @@ function GuestLinksRow() {
       managed={settings.guestSharingEnabled ? undefined : connectDenial}
       description={
         <>
-          Share a thread with a guest who watches it live in their browser and sends messages you
+          Share a thread with a guest who watches it live in a browser and sends messages you
           approve. Needs T3 Connect: sign in and link this machine in{" "}
           <Link to="/settings/access" className="underline underline-offset-2">
             Sharing & access
           </Link>
-          . While it is off, every guest link stops working.
+          . Turning it off stops every guest link.
         </>
       }
       control={
@@ -191,7 +191,7 @@ function LinkedEnvironmentsRow() {
           <Link to="/settings/connections" className="underline underline-offset-2">
             Connections
           </Link>
-          . While it is off, nothing new starts over a link; tasks already running finish.
+          . While off, nothing new starts over a link; running tasks finish.
         </>
       }
       control={
diff --git a/apps/web/src/components/settings/VoiceSettingsPanel.tsx b/apps/web/src/components/settings/VoiceSettingsPanel.tsx
index 596e3ea295ad7..c08844bafe09b 100644
--- a/apps/web/src/components/settings/VoiceSettingsPanel.tsx
+++ b/apps/web/src/components/settings/VoiceSettingsPanel.tsx
@@ -1283,7 +1283,7 @@ export function VoiceSettingsPanel() {
       <SettingsSection id={searchableSetting("speech-post-processing").id} title="Cleanup">
         <SettingsRow
           title="Clean up transcripts with a provider"
-          description="Sends each transcript, plus the draft text around your cursor, to the text generation provider on the draft’s environment to fix punctuation, numbers, and spoken corrections. Your audio is never sent. Off by default."
+          description="Sends each transcript and the draft text around your cursor to the draft environment’s text generation provider to fix punctuation, numbers, and spoken corrections. Your audio is never sent."
           control={
             <Switch
               aria-label="Clean up transcripts with a provider"
diff --git a/apps/web/src/components/settings/settingsLayout.tsx b/apps/web/src/components/settings/settingsLayout.tsx
index 605dd37739784..e5d555bf8f7c0 100644
--- a/apps/web/src/components/settings/settingsLayout.tsx
+++ b/apps/web/src/components/settings/settingsLayout.tsx
@@ -500,7 +500,7 @@ export function SettingsRow({
         className,
       )}
     >
-      <div className="flex flex-col gap-3 @min-[32rem]/settings-row:grid @min-[32rem]/settings-row:grid-cols-[minmax(0,1fr)_minmax(10rem,auto)] @min-[32rem]/settings-row:items-center @min-[32rem]/settings-row:gap-8">
+      <div className="flex flex-col gap-3 @min-[32rem]/settings-row:grid @min-[32rem]/settings-row:grid-cols-[minmax(0,1fr)_auto] @min-[32rem]/settings-row:items-center @min-[32rem]/settings-row:gap-8">
         <div className="min-w-0 flex-1 space-y-1">
           <div className="flex min-h-5 items-center gap-1.5">
             <h3 className="text-sm font-medium text-foreground">{title}</h3>
@@ -522,7 +522,7 @@ export function SettingsRow({
             </span>
           </div>
           {description ? (
-            <p className="max-w-2xl text-balance text-xs leading-normal text-muted-foreground">
+            <p className="max-w-2xl text-pretty text-xs leading-normal text-muted-foreground">
               {description}
             </p>
           ) : null}
@@ -531,7 +531,7 @@ export function SettingsRow({
           ) : null}
         </div>
         {renderedControl ? (
-          <div className="flex w-full min-w-0 shrink-0 items-center gap-2 @min-[32rem]/settings-row:w-auto @min-[32rem]/settings-row:justify-end">
+          <div className="flex w-full min-w-0 shrink-0 items-center gap-2 @min-[32rem]/settings-row:w-auto @min-[32rem]/settings-row:justify-end @min-[32rem]/settings-row:[&_[data-slot=select-trigger]]:min-w-40">
             {renderedControl}
           </div>
         ) : null}
diff --git a/oxlint-plugin-t3code/index.ts b/oxlint-plugin-t3code/index.ts
index ed9532ff6c5ce..1efb0fb2a3907 100644
--- a/oxlint-plugin-t3code/index.ts
+++ b/oxlint-plugin-t3code/index.ts
@@ -1,5 +1,6 @@
 import { definePlugin } from "@oxlint/plugins";
 
+import maxSettingsDescriptionLength from "./rules/max-settings-description-length.ts";
 import namespaceNodeImports from "./rules/namespace-node-imports.ts";
 import noDomTestEnvironment from "./rules/no-dom-test-environment.ts";
 import noEmDashCopy from "./rules/no-em-dash-copy.ts";
@@ -38,6 +39,7 @@ export default definePlugin({
     name: "t3code",
   },
   rules: {
+    "max-settings-description-length": maxSettingsDescriptionLength,
     "namespace-node-imports": namespaceNodeImports,
     "no-dom-test-environment": noDomTestEnvironment,
     "no-em-dash-copy": noEmDashCopy,
diff --git a/oxlint-plugin-t3code/rules/max-settings-description-length.test.ts b/oxlint-plugin-t3code/rules/max-settings-description-length.test.ts
new file mode 100644
index 0000000000000..32c2d3ab3a0da
--- /dev/null
+++ b/oxlint-plugin-t3code/rules/max-settings-description-length.test.ts
@@ -0,0 +1,43 @@
+import { describe } from "@effect/vitest";
+
+import { createOxlintRuleHarness } from "../test/utils.ts";
+
+const rule = createOxlintRuleHarness("t3code/max-settings-description-length", {
+  filename: "apps/web/src/components/settings/Example.tsx",
+});
+
+const long = "Agents ".repeat(30);
+
+describe("t3code/max-settings-description-length", () => {
+  rule.valid(
+    "allows a short description",
+    `const row = <SettingsRow title="Theme" description="Choose how T3 Code looks." />;`,
+  );
+
+  rule.valid(
+    "does not count dynamic text",
+    `const row = <SettingsRow title="Task" description={\`${long.slice(0, 150)}\${prompt}\`} />;`,
+  );
+
+  rule.invalid(
+    "reports a long string description",
+    `const row = <SettingsRow title="Theme" description="${long}" />;`,
+  );
+
+  rule.invalid(
+    "counts link text inside a JSX description",
+    `
+      const row = (
+        <SettingsRow
+          title="Guests"
+          description={
+            <>
+              ${long.slice(0, 150)}{" "}
+              <Link to="/docs">${long.slice(0, 60)}</Link>
+            </>
+          }
+        />
+      );
+    `,
+  );
+});
diff --git a/oxlint-plugin-t3code/rules/max-settings-description-length.ts b/oxlint-plugin-t3code/rules/max-settings-description-length.ts
new file mode 100644
index 0000000000000..aa9f3e162a315
--- /dev/null
+++ b/oxlint-plugin-t3code/rules/max-settings-description-length.ts
@@ -0,0 +1,63 @@
+import { defineRule, type ESTree } from "@oxlint/plugins";
+
+const MAX_LENGTH = 200;
+
+const MESSAGE = (length: number) =>
+  `SettingsRow description is ${length} characters; keep it at ${MAX_LENGTH} or fewer so it stays two lines next to a control. Shorten the copy: keep each fact a user needs and drop restatements.`;
+
+type Node = ESTree.Node | ESTree.JSXElement["children"][number] | null | undefined;
+
+const staticText = (node: Node): string => {
+  if (!node) return "";
+  switch (node.type) {
+    case "Literal":
+      return typeof node.value === "string" ? node.value : "";
+    case "TemplateLiteral":
+      return node.quasis.map((quasi) => quasi.value.cooked ?? "").join("");
+    case "JSXText":
+      return node.value
+        .split(/\r\n|\n|\r/u)
+        .map((line, index, lines) => {
+          const start = index > 0 ? line.trimStart() : line;
+          return index < lines.length - 1 ? start.trimEnd() : start;
+        })
+        .filter(Boolean)
+        .join(" ");
+    case "JSXExpressionContainer":
+      return node.expression.type === "JSXEmptyExpression" ? "" : staticText(node.expression);
+    case "JSXElement":
+    case "JSXFragment":
+      return node.children.map(staticText).join("");
+    case "ConditionalExpression": {
+      const consequent = staticText(node.consequent);
+      const alternate = staticText(node.alternate);
+      return consequent.length >= alternate.length ? consequent : alternate;
+    }
+    default:
+      return "";
+  }
+};
+
+export default defineRule({
+  meta: {
+    type: "suggestion",
+    docs: {
+      description: `Limit SettingsRow descriptions to ${MAX_LENGTH} characters of static text. The column is at most 672px, about 110 characters per line next to a dropdown, so ${MAX_LENGTH} stays two lines.`,
+    },
+  },
+  create(context) {
+    return {
+      JSXOpeningElement(node) {
+        if (node.name.type !== "JSXIdentifier" || node.name.name !== "SettingsRow") return;
+        for (const attribute of node.attributes) {
+          if (attribute.type !== "JSXAttribute") continue;
+          if (attribute.name.type !== "JSXIdentifier" || attribute.name.name !== "description") {
+            continue;
+          }
+          const length = staticText(attribute.value).replace(/\s+/gu, " ").trim().length;
+          if (length > MAX_LENGTH) context.report({ node: attribute, message: MESSAGE(length) });
+        }
+      },
+    };
+  },
+});
diff --git a/vite.config.ts b/vite.config.ts
index 9a5a80414a959..fb6255cf96363 100644
--- a/vite.config.ts
+++ b/vite.config.ts
@@ -519,6 +519,10 @@ export default defineConfig({
         files: ["apps/web/src/**"],
         rules: { "t3code/no-outset-state-indicators": "error" },
       },
+      {
+        files: ["apps/web/src/**"],
+        rules: { "t3code/max-settings-description-length": "error" },
+      },
       {
         files: ["apps/*/src/**", "packages/*/src/**"],
         excludeFiles: [