Skip to content

feat(settings): move explanatory help behind an info tip - #15823

Merged
chenmingwei23 merged 1 commit into
mainfrom
feat/settings-text-simplify
Oct 2, 2026
Merged

chenmingwei23 merged 1 commit into
mainfrom
feat/settings-text-simplify

Conversation

@bolichen97

@bolichen97 bolichen97 commented Oct 1, 2026 •

Copy link
Copy Markdown
Contributor

Problem / Motivation

Goal: Settings rows show only the text a reader needs; everything else sits behind an info tip the reader opens on purpose.

Today almost every row in Settings carries a sentence or a paragraph under its label, so a tab reads as a wall of text and the controls are hard to scan. Help you would read once is shown forever.

Why it matters

A person opens Settings to flip one switch. Dense prose under every row slows that down and buries the few sentences that really matter — a cost, a consequence, where data goes.

Not a goal

  • Rewording every Settings string. Five English strings are shortened; the rest keep their wording and only move.
  • The messaging-channel setup panels (Slack, Teams, Webex, WhatsApp and so on). Their prose is setup instruction and stays; a follow-up can apply the same triage.
  • The glass-theme overlap and the expanded-message-over-composer bug. Sibling work owns those.
  • A new tooltip library or a redesign of the Settings layout.

What changed (motivation → approach → change)

Settings rows had too many words on screen. The row primitives already had two slots — description, always visible, and hint, an info tip — but nearly every panel used description. This PR triages each row: a sentence a reader needs to MAKE the choice (a cost, a consequence, where data goes, a status) stays as description; a sentence that only explains what the control is becomes a hint. Rows that keep a description: "Reuse the current terminal" ("it is never run for you"), Split View ("Experimental"), Enable Shortcuts (names the hotkey), Default Model (tells it apart from the Background and Subagent rows), four rows whose sentence states a cost (huge paste, diff memory, provider polling, screenshot size), and six whose label alone does not say what they are (Folder suggestions, Max tree nodes, Composable layout, Tail-only Fork, Soft-stop budget, MCP Apps). About seventy rows move under website/src/pages/settings/ (ChatPanel.tsx, DisplayPanel.tsx, VoicePanel.tsx, NotificationsPanel.tsx, ShortcutsPanel.tsx, SkillsPanel.tsx, ComputerUsePanel.tsx, DeveloperPanel.tsx, FeaturePreviewsSection.tsx, BrowserPanel.tsx, RemoteCrewPanel.tsx, CrewmatesSection.tsx).

Part Before After
Settings row help 🟨 under the label, always 🟩 info tip beside the label
Choice-making sentence (cost, consequence, data egress, status) 🟦 under the label 🟦 under the label
InfoTip reveal 🟨 click only 🟩 hover (a 150 ms rest on the glyph opens, a crossing never does; glyph or bubble holds it, 150 ms leave grace), focus, click/tap pin; Escape closes from anywhere; a pinned tip also closes on an outside click or focus leaving
InfoTip bubble 🟨 fixed 120 px clamp, clips long text; beside the glyph, over the row's control 🟩 settings rows open it above the glyph (below only when there is no readable room above), maxHeight capped to the room, scrolls
InfoTip glyph 🟨 text "?" in a ring 🟩 lucide Info
hint prop 🟨 missing on SettingsCombobox 🟩 also on SettingsCombobox
Palette search 🟨 indexes description only 🟩 falls back to the hint string when a row keeps no description

🟩 added · 🟨 changed · 🟦 unchanged

InfoTip is the one shared pattern, so it had to work everywhere a finger, a mouse or a keyboard reaches it. A mouse resting on the glyph for 150 ms shows it (a pointer that merely crosses the glyph opens nothing, so a bubble never pops up in the path of a click aimed at the row above) and holds it while the pointer is on the glyph or the bubble, leaving both hides it after an equal 150 ms grace; a click or tap on the glyph pins it; a pointer down inside the bubble pins it and a click there goes no further, so selecting and copying its text keeps the tip open however it was opened (a drag that runs past the bubble's edge closes nothing until the button is released) and never flips the row beneath; Escape closes it from wherever focus is (and the key is claimed, so a dialog around it stays open); a pinned tip also closes on an outside click or when focus moves elsewhere; keyboard focus shows it, and while it is open the arrow and Page keys on the glyph scroll a long tip without moving focus; a click or a tap pins it and a tap elsewhere unpins it. On settings rows the bubble opens above the glyph, over the previous row, so it never sits on the control beneath the label (it falls below only for a row with no readable room above). Its accessible name stays the short "More information", and its text is its description — the open tooltip, or title while closed, dropped the moment the tip shows so the browser never draws a second tooltip over ours. Nothing of the tip is body copy until it opens. InfoTip does not reuse InstantTip's useInstantTip gesture on purpose: that hook is a transient hint for chips and badges (show on rest, hide on leave, blur or any anchor-moving scroll) with no pinned state, no bubble that is itself a hover and click target, no scrolling body and no outside-click close, and settings help needs all four so a reader can pin a long paragraph, select and copy from it, and scroll it; sharing the hook would mean growing it with states its two callers never use.

Three English descriptions are shortened in all twelve catalogs under website/src/i18n/locales/ (and en-XA.json is regenerated); no label changes, so every generated registry id and ?highlight= route is unchanged, each by removing a sentence the label already says; each dropped clause (what the row is) moves into that row's tip. "What Enter does while the agent is working" keeps one visible line telling Steer and Queue apart (new busy_alt_action_summary key: a new ten-word line in English, "Steer interrupts the current turn; Queue waits for it.", and the first sentence of the existing help in the other eleven catalogs); its tip carries the rest. Touched fr/ru/bn/hi sentences are worded impersonally (no clash with formal neighbours; the informal-register gate passes). The settings registry (settingsRegistry.gen.ts, settings-registry.generated.json) is regenerated and indexes a row's tip text and its description (tip first, then description, when a row keeps both, so the palette subtitle reads definition-then-consequence), so search still finds every moved sentence; the one row whose tip is a conditional (Default reasoning effort, a ternary the extractor cannot read as one string) gets its hidden clause as settingsKeywords.ts phrases instead, so "how long models think" still finds it. The Default reasoning effort row's "needs a reasoning model" tip gets its own key (effort_default_needs_reasoning_model) so the Knowledge Library's Extraction effort row, which shares the old key, keeps its unchanged sentence. Docs: website/docs/frontend-conventions.md gains the description-or-tip rule; the InfoTip section of docs/system-specs/modules/learn-cron-dashboard.md describes the new behaviour.

Backwards compatibility

Compatible: no config key, API or catalog key changes; only where a string renders moves, and five values are shorter.

Tests

  • website/src/test/InfoTip.test.tsx — rewritten for the contract: name and description, title present only while closed, hover shows and leave hides after the grace, the bubble keeps the tip open while the pointer is on it, a click inside the bubble neither closes it nor reaches anything beneath, a hover-opened tip closes on a document Escape without the glyph ever being focused (the event is defaultPrevented), a pinned tip closes when focus moves to another control or on Escape after blur, a touch pointer does not count as hover, a second tap keeps a focused tip closed through its pointer-leave (no dismissal latch: every close clears the hover and focus reveals, and the next real hover or focus reopens), a glyph low in the viewport gets a bubble anchored to its bottom edge with maxHeight capped to the room above (and overflow-y-auto), a glyph high up keeps top alignment with the full cap, focus shows and Escape hides then re-shows on the next focus, click pins past pointer-leave, a second click closes a pinned tip even while the trigger stays focused (a tap focuses as it clicks), outside click unpins, type="button", node-shaped text renders as paragraphs, and the two existing placement clamps.
  • website/src/test/InfoTip.settingsRow.test.tsx — a click inside an open tip never flips the owning SettingsToggle (the portal bubble swallows its click); clicking the row itself still toggles once.
  • website/src/test/previewSurfaces.test.tsx — its exhaustive button census is a named partition: exactly four More information help toggles (Composable layout keeps its sentence on the row), and an ingress set that stays empty (then Open Webhooks after that toggle), so every button on the tab stays observed; OverviewMemoryTabCov80.test.tsx pins the card heading's name without the old "?" glyph text. Tests that read a row's sentence (NotificationsPanel, DisplayPanel, BrowserPanel) read it from the tip's title.
  • settingsRegistry.test.ts and test/test_settings_deeplink_registry.py pin the regenerated registries (run, pass).

Manual verification

Captured on an isolated pod running this branch (kirocrew pod up settings-text, never the live gateway): Chat → Transcript / Sessions / Composer / Model, Display → View / Zoom / Terminal / Sidebar, Voice, Notifications. Hovered, focused, pinned and dismissed tips on the Transcript page in the recording below. The before shots come from a second pod on origin/main.

Screenshots / video

Every changed panel, before (origin/main pod, left) and after (this branch's pod, right) in one image per panel, all 1280×900 dark. Two inline, the rest folded; 22 panel pairs plus seven gated-state captures, so a reader with a 40-image budget sees them all.

Chat → Transcript: before (left) and after (right)

Chat → Sessions: before (left) and after (right)

The info tip open, pinned by a click, captured from this head (left: Default Model, the first row, so its tip falls below for want of room above; right: Message Font Size, whose tip opens above the glyph and leaves the stepper beneath the label clear):

Chat Model settings with the Default Model info tip pinned open
Chat Transcript settings with the Message Font Size info tip pinned open

The info tip in motion: hover reveals, keyboard focus reveals and Escape dismisses, click pins and an outside click unpins.

settings-infotip.webm

recorded from this head's build (bubble above the glyph) · feat/settings-text-simplify · mode: default · real pod gateway, no fixtures

Every other changed panel, before (left) and after (right)

Chat → Composer: before (left) and after (right)

Chat → Model: before (left) and after (right)

Chat → About You: before (left) and after (right)

Chat → Side panel: before (left) and after (right)

Chat → Discovery: before (left) and after (right)

Chat → Advanced: before (left) and after (right)

Display → View: before (left) and after (right)

Display → Zoom & Font: before (left) and after (right)

Display → Terminal: before (left) and after (right)

Display → Theme: before (left) and after (right)

Display → Sidebar Colors: before (left) and after (right)

Voice: before (left) and after (right)

Notifications → Desktop alerts: before (left) and after (right)

Notifications → Per-category sounds: before (left) and after (right)

Shortcuts: before (left) and after (right)

Skills: before (left) and after (right)

Browser: before (left) and after (right)

Remote Crew: before (left) and after (right)

Computer Use: before (left) and after (right)

Developer (top): before (left) and after (right)

Gated states, captured on this branch's pod with the gate flipped (no origin/main pair: the gate hides the row entirely there too):

Developer → Decisions on: the Decisions card expanded with its point list; the judge-model select sits inside the "Quiet check-ins" point and renders only once that point is set to the small judge
Developer → Crewmates: the Reply threads row with its info tip
Remote Crew enabled: the Auto-connect crews row with its info tip
Display → Zoom & Font with Font Family = Custom: the Custom font combobox and Enable ligatures rows with their info tips
Chat → About you with Role = Other: the Describe your role input with its info tip
Voice with Provider = Amazon Polly: the Voice, Engine, Speed and AWS profile rows with their info tips
Voice with Provider = Piper: the Piper rows with their info tips

Not capturable from this host, and said so rather than faked: Computer Use renders no rows on a Linux pod (macOS-only in this release — the pair above shows the notice, and "Show cursor motion" sits behind the same gate), the Shortcuts "Use Ctrl, not Option" row is macOS-only (IS_MAC &&), the Browser row's tip is the Electron branch of a platform ternary (isElectron ? … : undefined). The Decisions panel (DecisionsPointPanel.tsx) is not changed by this PR: its rows kept their text after triage, so its capture above is context, not a before/after pair. Each is a platform or config gate around the same InfoTip/description props every row shown here uses, so the diff is the evidence for those branches.

Related Issues

Closes #15837

Checklist

  • At most two commits (one is the norm), with a Conventional Commits title (feat|fix|docs|style|refactor|perf|test|chore|ci|build|revert: ...)
  • Existing tests pass and new tests added for new functionality
  • Self-review completed; code follows project style guidelines
  • Documentation updated (if applicable)
  • No secrets, credentials, or internal references in the diff

@bolichen97
bolichen97 requested a review from a team October 1, 2026 10:50
@bolichen97
bolichen97 requested a review from a team as a code owner October 1, 2026 10:50
@bolichen97
bolichen97 requested a review from buluoray October 1, 2026 10:50
@github-actions github-actions Bot added the readiness: checking Automated validation is still running label Oct 1, 2026
@github-actions

github-actions Bot commented Oct 1, 2026 •

Copy link
Copy Markdown
Contributor

GPT 5.6 Review — ✅ no blocking findings

GPT 5.6 completed its review of 652a270c5fd35aeb28de460efdd6bc6937e9f8bc and found no blocking issues.

This comment is updated in place on each push.

Review details

No findings.
[GPT-REVIEWED] 652a270

False positive or not applicable? A repository writer can comment:
/ai-review override gpt 652a270c5fd35aeb28de460efdd6bc6937e9f8bc: <one-sentence reason>

@github-actions

github-actions Bot commented Oct 1, 2026 •

Copy link
Copy Markdown
Contributor

Design Review (Fable 5) — ✅ PASS

Design-level review of 652a270c5fd35aeb28de460efdd6bc6937e9f8bc — updated in place on each push. A BLOCK verdict blocks PR readiness; PASS/CONCERNS are advisory.

Design-Verdict: PASS

Verify the row-by-row triage calls — which sentences stay visible — against the attached screenshots; that judgment is the only part code can't prove.

[DESIGN-REVIEWED] 652a270

Description read

[DESCRIPTION-READ] b29149bd781c1c9de49a709d6f98842ae93773897ab448d5a7ed6a9d5a84d658

That sha256 names everything this verdict read: the PR description, plus the 1 evidence file(s) the workflow collected from it and handed this review. It covers that evidence because the media strip replaces every attachment URL with the same placeholder, so an edit swapping one attachment for another would leave the description's captured text identical while what this review judged changed. Recompute it with .github/scripts/pr-description-capture.sh over the same inputs; if it differs, the description or that evidence changed after this verdict was formed and any finding drawn from either is unproven.

@github-actions

github-actions Bot commented Oct 1, 2026 •

Copy link
Copy Markdown
Contributor

First Principles Review (Fable 5) — 🟡 CONCERNS

Premise-level review of 652a270c5fd35aeb28de460efdd6bc6937e9f8bc — why this exists and whether the shipped surface is the smallest honest version. Updated in place on each push. A BLOCK verdict blocks PR readiness; PASS/CONCERNS are advisory.

First-Principles-Verdict: CONCERNS

The seventy-row move names nobody who was failing: its only support is the author's scan-cost argument and the hint prop's own doc comment.

Not justified as shipped

  • Item 1 — unjustified move: "a tab reads as a wall of text and the controls are hard to scan" cites no report, misclick or complaint; the convention document justifying the sweep (frontend-conventions.md § Help text) ships inside this same PR, and every existing user pays the relearning cost of help that is now invisible until hovered. The pre-existing hint contract in settings.tsx recorded the rule for new rows; it did not decide a bulk migration.
    Clears when: a linked report, usability observation or complaint of the always-visible-prose harm, or a maintainer's explicit acceptance of the premise for this sweep.

What this change ships

Inventory (10 items) — 9 justified

Intent: make Settings rows scannable by moving what-the-control-is prose behind an info tip, keeping only choice-making sentences visible. ADDITION (a mass move plus the tip rework it forces).

  1. ~70 settings rows' help sentence moves from under the label into an info tip — unjustified move (no named failing user)
  2. Info tips on every page now open on hover (150 ms rest) and focus, pin on click/tap — justified
  3. Settings-row tips open above the glyph; long tips cap to the room and scroll (old 120 px clamp clipped) — justified
  4. Tip glyph changes from text "?" to the lucide Info icon — justified
  5. Arrow/Page/Home/End scroll an open tip from the glyph; Escape closes it and is claimed before dialogs — justified
  6. Palette search indexes tip text (tip first, then description), keeping moved sentences findable — justified
  7. Catalog keys split in all 12 locales; Default reasoning effort gets its own key so Knowledge Library's sentence is untouched — justified
  8. "how long models think" and two sibling phrases added as palette keywords (ternary hint is unextractable) — justified
  9. hint prop added to SettingsCombobox and LinkPatternsEditor — justified (grepped hint= in this diff: 2 and 1 consumers)
  10. Soft-stop budget's cost sentence moves the other way, tip → always-visible — justified

[FIRST-PRINCIPLES-REVIEWED] 652a270

Description read

[DESCRIPTION-READ] d65ac1261ac0c08ec3d402ad714c4347621486383a47c9ae03115a62347ec758

That sha256 names the PR description this verdict read. Recompute it with .github/scripts/pr-description-capture.sh; if it differs, the description changed after this verdict was formed and any finding drawn from the description is unproven.

@github-actions

github-actions Bot commented Oct 1, 2026 •

Copy link
Copy Markdown
Contributor

UX Review (Fable 5) — 🔴 could not evaluate

The blind read could not run for 652a270c5fd35aeb28de460efdd6bc6937e9f8bc: one or more attachment downloads from the PR description failed for a transport reason (a throttle, a 5xx, no answer), so the reviewer could not see everything the author supplied. The evidence step failed the run, so PR readiness holds rather than reading this as advisory. Re-run this workflow; if the same downloads fail again, the attachment URLs themselves are the problem — re-attach the images to the description.

[UX-REVIEWED] 652a270

@bolichen97
bolichen97 force-pushed the feat/settings-text-simplify branch from 87ad401 to c5d1610 Compare October 1, 2026 11:15
@bolichen97

Copy link
Copy Markdown
Contributor Author
  • Evidence gap: no screenshot of an open info tip span=2b7f5a1499b7 — fixed

Two stills added to the body: Default Model's tip pinned open (both paragraphs visible) and a one-sentence tip on the Transcript page, captured on an isolated pod running c5d1610.
The WebM remains for the hover/focus/pin motion; the stills are what a blind read can see.

@bolichen97

Copy link
Copy Markdown
Contributor Author
  • Watch: "Reuse the current terminal" lost its safety promise span=2b7f5a1499b7 — fixed in c5d1610

"It is never run for you" is a consequence, which this PR's own triage rule keeps on the row. terminal_reuse_current_desc is a description again in DisplayPanel.tsx; the body names it as a kept row.

@bolichen97

Copy link
Copy Markdown
Contributor Author
  • Suggestion: Voice panel labels left bare span=da0cde7c1b92 — rebutted

Each of "Voice", "Speed", "Engine" sits directly under its section heading (Text-to-Speech / Speech-to-Text) and shows its current value in the control, so the row still self-explains; the moved sentences restated the heading ("Voice from the host's built-in speech engine", "Speech rate for spoken replies").
The Provider row keeps its description because it states where data goes (Polly uses AWS credentials and the network). Class-level: a label under a heading that names the subsystem needs no second sentence saying which subsystem it is.

@bolichen97

Copy link
Copy Markdown
Contributor Author
  • Item 3 — glyph swap not justified span=51f23979a218 — rebutted

The user's brief asked for "an Info button" as the one shared pattern, and website/AGENTS.md's icon rule is lucide-react, never a hand-rolled glyph; a text "?" inside a bordered circle is a hand-rolled icon. The swap is the brief's shape, not decoration.
The old component's own comment records the "?" being announced as "question mark", which is why its aria-label existed; an icon with aria-hidden removes that class of misread at the source.

@bolichen97

Copy link
Copy Markdown
Contributor Author
  • Item 9 — data-info-tip has zero consumers span=ec8becffd423 — fixed in c5d1610

It now has a counted consumer: previewSurfaces.test.tsx's ingress-button census excludes button[data-info-tip], the help toggle that opens a tooltip and never a page (the CI failure on 87ad401 was that census counting the new tips as ingress).

@bolichen97

Copy link
Copy Markdown
Contributor Author
  • Renamed labels change two registry ids span=0285d80048cf — rebutted

A registry id is derived from the label by design; neither row declares a settingId or configKey, so every prior label edit in this repo moved its id the same way. A stale ?highlight= for an id with no entry is stripped by useSettingHighlight ("unknown enough to strip") and the Chat tab still opens — a lost ring, not a broken link.
Shortening these labels is the PR's goal; restoring them to keep two deep-link ids would undo it for an advisory degradation that affects only a bookmarked highlight.

@github-actions

github-actions Bot commented Oct 1, 2026 •

Copy link
Copy Markdown
Contributor

Opus 5 Review — ✅ no blocking findings

Reviewed 652a270c5fd35aeb28de460efdd6bc6937e9f8bc — this comment is updated in place on each push.

Review details

The tip's scroll-key handler claims Arrow/Page/Home/End on the focused glyph even when the bubble has nothing to scroll, so keyboard scrolling of the settings page is silently swallowed.

FINDING — website/src/components/InfoTip.tsx:268 — open is true whenever the glyph merely has focus, and for a non-overflowing tip max = tip.scrollHeight - view is 0, yet the switch still assigns a non-null next and e.preventDefault() runs unconditionally, so ArrowUp/ArrowDown/PageUp/PageDown/Home/End do nothing at all while a Tab-focused info glyph holds focus (tip.scrollTop = Math.max(0, Math.min(next, 0))) → Fix: compute max first and return before e.preventDefault() when max <= 0, so the keys fall through to the page's scroll container.

[OPUS-REVIEWED] 652a270

Verdict parsed from the review's SHA-scoped output markers for commit 652a270c5fd35aeb28de460efdd6bc6937e9f8bc.

False positive or not applicable? A repository writer can comment:
/ai-review override fable 652a270c5fd35aeb28de460efdd6bc6937e9f8bc: <one-sentence reason>

@github-actions github-actions Bot added readiness: action required A blocking check or review needs attention and removed readiness: checking Automated validation is still running labels Oct 1, 2026
@bolichen97
bolichen97 force-pushed the feat/settings-text-simplify branch from c5d1610 to e00d32b Compare October 1, 2026 11:37
@bolichen97

Copy link
Copy Markdown
Contributor Author

self-added: yes

  • The exact button ratchet now excludes this PR's controls span=8a8a48371dc8 — fixed in e00d32b

The :not([data-info-tip]) exclusion is gone; previewSurfaces.test.tsx pins the five More information help toggles in every exact set (and Open Webhooks after the webhooks toggle), so the census observes every button on the tab again — at least as tight as before this PR.
The data-info-tip attribute itself is deleted from InfoTip.tsx; it had no other consumer.

@github-actions github-actions Bot added readiness: checking Automated validation is still running and removed readiness: action required A blocking check or review needs attention labels Oct 1, 2026
@bolichen97

Copy link
Copy Markdown
Contributor Author
  • Watch: hover reveal closes before the pointer can reach the bubble span=1b6a9a13e6b2 — fixed in e00d32b

The glyph's and the bubble's pointer-leave now schedule a close after HOVER_LEAVE_GRACE_MS (150 ms) and entering either cancels it, so the pointer can cross the 6 px gap to read or copy a long tip. InfoTip.test.tsx pins both the grace and the bubble keeping the tip open.

@bolichen97

Copy link
Copy Markdown
Contributor Author
  • Item 7 — registry id change undeclared span=48432443a7d8 — fixed in e00d32b

The body's What changed now names the two labels, the two ids they move (chat.double-click-to-edit, chat.pr-and-issue-chips), and how a stale ?highlight= degrades (stripped; the Chat tab still opens).

@bolichen97

Copy link
Copy Markdown
Contributor Author
  • Item 10 — data-info-tip is a test-support marker span=cdd860be6c6c — fixed in e00d32b

Deleted from InfoTip.tsx. The census that used it now counts the help toggles by name instead of skipping them, which is what the GPT lane's ratchet rule asked for, so no selector needs the marker.

@bolichen97
bolichen97 force-pushed the feat/settings-text-simplify branch from e00d32b to dcc0e6f Compare October 1, 2026 11:48
@bolichen97

Copy link
Copy Markdown
Contributor Author

self-added: yes

  • A second tap's pointer-leave reopens the focused tip after 150 ms span=5031af599c78 — fixed in dcc0e6f

The deferred leave now clears only hovered; dismissal lifts on a new mouse enter or on blur, never on the timer. InfoTip.test.tsx adds the touch sequence (focus, tap, leave, tap, leave, settle: still closed; blur+focus: shown) and extends the Escape test to mouse leave and re-enter.

@bolichen97

Copy link
Copy Markdown
Contributor Author
  • Item 1 — provenance rests on an unverifiable thread span=fc899d874a62 — fixed

The complaint is now a tracked issue, #15837, and the body's Related Issues line reads Closes #15837.

@bolichen97

Copy link
Copy Markdown
Contributor Author
  • Item 4 — two label renames cost deep links span=0d906d465b81 — rebutted

The report that names who the longer labels failed is the maintainer's own ask in #15837 ("labels and descriptions are shortened where they repeat the label or the section heading"): "Double-click to edit your messages" repeats its tip, and "PR and Issue Chips on Session Cards" repeats the Sessions page it sits on. The cost is a bookmarked ?highlight= losing its ring on two browser-local rows while the tab still opens; neither row ever declared a stable settingId, so this is the same cost every prior label edit paid.
Class-level: a label rename in this repo moves its derived id by design; the stable-id mechanism exists (settingId) for rows that need one, and these do not.

@bolichen97
bolichen97 force-pushed the feat/settings-text-simplify branch from dcc0e6f to 50864fb Compare October 1, 2026 12:00
@bolichen97

Copy link
Copy Markdown
Contributor Author

Rebased 8819413a -> cd054c75 onto origin/main 02c60483 (docs-only moves on main). Docs lint and the InfoTip, palette and settings suites (968 tests) pass locally.

@bolichen97

Copy link
Copy Markdown
Contributor Author

self-added: yes

  • A long tip capped to the room scrolls, but a keyboard user has no way to scroll it span=365e5719e2ec — fixed in 592ac86

While the tip is open, the arrow keys, Page keys and Home / End on the focused glyph scroll the bubble (a line, a view, or to either end) and claim the key, so the whole paragraph is readable without moving focus off the glyph; closed, the keys fall through to the page. No tab stop is added to the bubble, so the focus and blur contract is unchanged. Two tests cover the scroll steps and the closed fall-through.

@bolichen97

Copy link
Copy Markdown
Contributor Author

self-added: yes

  • The InfoTip timers re-spell InstantTip's gesture; use useInstantTip or say why not span=4b0321c45bbb — rebutted

Stated in the body now: useInstantTip is a transient hint for chips and badges (show on rest, hide on leave, blur or an anchor-moving scroll) with no pinned state, no bubble that is itself a hover and click target, no scrolling body and no outside-click close, and settings help needs all four so a reader can pin a long paragraph, select and copy from it, and scroll it. Sharing the hook would grow it with states its two callers never use, which is the duplication the hook's own header warns against in the other direction.

@bolichen97

Copy link
Copy Markdown
Contributor Author

self-added: yes

  • Composer markdown-list-continuation code and its 221-line test ride along undeclared span=6195b8751b65 — rebutted

The PR's diff against main contains no composer code: the only ChatInput-related change is a two-line regex update in ChatInput.liquidGlass.test.tsx (it reads the translucent-panels row's sentence from hint instead of description). #15911 landed on main after this branch's base, which is why its files appeared beside this diff in the lane's read; the head is now rebased onto that main, so the comparison no longer shows them.

@bolichen97

Copy link
Copy Markdown
Contributor Author

self-added: yes

  • The registry's single description field loses the visible-vs-tip distinction; the Default Model entry restates itself span=51c688667b92 — rebutted

The registry field feeds palette search and its one-line subtitle, both of which want one string; splitting it changes a generated schema with a Python consumer for three rows, wider than this PR's purpose of moving text. The Default Model row is the one pre-existing row whose visible sentence and tip both state what the row is, so its subtitle is longer than the others; shortening it would mean rewording that row's catalog strings, which this PR deliberately does not do.

@bolichen97

Copy link
Copy Markdown
Contributor Author

self-added: yes

  • Per-category notification sound rows lose their sentence, leaving bare labels (Cron, Webhook, Heartbeat, Subagent) span=7f0b01c62c9a — rebutted

This is the per-category watch rebutted on an earlier head, under the maintainer's ruling for this PR: a sentence stays on the row only when it states a cost, a data-loss risk or a security consequence. Each sentence here says which event the category covers, a what-it-is sentence; the row's label names the category and its control is a sound picker, so a wrong pick costs nothing and is undone in place. The sentence stays in the tip, one hover, tap or Tab away.

@bolichen97

Copy link
Copy Markdown
Contributor Author

self-added: yes

  • Default Model's concatenated palette subtitle is four sentences that restate themselves; dedupe span=509aabd0b17c — rebutted

Same shape as the Design suggestion on the registry: the Default Model row is a pre-existing row whose visible line and tip both state what the row is, and this PR changes neither of its strings. Deduplicating the subtitle would mean rewording that row's catalog text or adding a per-row exception to the extractor, both wider than this PR's purpose; both sentences are complete and the row is still found by every word in either.

@bolichen97

Copy link
Copy Markdown
Contributor Author

Rebased cd054c75 -> 592ac86d onto origin/main 337470d5 (+23 on main; same-directory moves only, no shared files). Docs lint and the InfoTip, palette, settings and ChatInput-test suites (949 tests) pass locally.

@bolichen97

Copy link
Copy Markdown
Contributor Author

self-added: yes

  • The document Escape listener runs after Radix's capture-phase dismissal, so a tip inside a dialog cannot stop the dialog closing span=5031af599c78 — fixed in 029c118

The listener is registered and removed on window with capture: true; capture traverses window before document, so it runs ahead of @radix-ui/react-dismissable-layer's document-capture Escape listener and claims the key. The handler body is unchanged. A new test proves the ordering (a document-capture spy never runs while the tip is open, a later window-capture spy sees the key already prevented) and that a closed tip lets Escape through unprevented.

@bolichen97

Copy link
Copy Markdown
Contributor Author

self-added: yes

  • The ? to lucide Info glyph swap is unjustified and reaches every InfoTip surface span=13b3023d2bff — rebutted

This is the glyph item rebutted on three earlier heads under new span ids. The brief this PR implements (#15837) asks for an Info control and the repo's icon rule is lucide glyphs, so the hand-drawn "?" ring is the exception being removed; reaching every InfoTip surface is the point of a shared component, since two glyphs for one control would be the inconsistency. The accessible name is unchanged, so no assistive-technology user relearns anything.

@bolichen97

Copy link
Copy Markdown
Contributor Author

self-added: yes

  • The blind reader identified the info glyph only as "a guess"; every settings row now depends on it span=452b72e499af — rebutted

The glyph is the standard lucide Info mark with the accessible name "More information" and a title fallback while closed; the recording shows an incidental mouse-over opening it, and the lane itself notes click-to-pin rescues a reader who never hovers. The user's stated goal rules out adding a visible teaching line; the item is marked no-fix-mandatory and a human confirms from the recording, which is attached.

@bolichen97

Copy link
Copy Markdown
Contributor Author

self-added: yes

  • Quick Send's Shift+click gesture hint moved into the tip; keep it visible like Enable Shortcuts span=1c8119f6a84b — rebutted

Under the maintainer's ruling for this PR a sentence stays on the row only when it states a cost, a data-loss risk or a security consequence; the Quick Send gesture sentence is none of those, and a missed gesture costs one extra click. Enable Shortcuts is the one kept exception because its row is inert until the reader knows the key, whereas Quick Send's toggle works without the gesture. The sentence stays in the tip, one hover, tap or Tab away.

@bolichen97

Copy link
Copy Markdown
Contributor Author

Rebased 592ac86d -> 029c1189 onto origin/main cfb42848 (+15 on main, same-directory moves only). Docs lint and the InfoTip, palette and settings suites (957 tests) pass locally.

@bolichen97

Copy link
Copy Markdown
Contributor Author

/ai-review override ux 029c118: the three gated rows (macOS-only cursor motion and Ctrl-not-Option, Electron-only built-in browser) cannot be captured on the Linux pod; their only change is the sentence moving to the same InfoTip every attached capture shows.

@github-actions

github-actions Bot commented Oct 2, 2026

Copy link
Copy Markdown
Contributor

Human judgment recorded

@bolichen97 marked the ux AI finding as false positive, not applicable, or explicitly accepted for 029c1189c4896b368e908bf8315ede95f9ba44b0.

the three gated rows (macOS-only cursor motion and Ctrl-not-Option, Electron-only built-in browser) cannot be captured on the Linux pod; their only change is the sentence moving to the same InfoTip every attached capture shows.

This decision applies only to this commit. A new push requires a new judgment.

@bolichen97

Copy link
Copy Markdown
Contributor Author

Inherited red, not from this diff (no Python changed): on head 029c1189 Backend Tests (3.12, 5) and (Windows) (5) fail test/test_context_composition_contract.py::TestSurface::test_builder_members_keep_their_kind_and_signature, and (Windows) (1) fails test/test_app_script_cron_sibling_import.py::TestACommandCronRunningBundleCode::test_the_call_site_leaves_the_bundle_readable; Coverage Gate fails closed behind them. Main's own CI run on this PR's exact base cfb42848 (run 36972843145) fails the same four jobs. Failed jobs rerun once (head unchanged, the UX override stays pinned).

Settings rows showed a paragraph under almost every control, so a tab
read as a wall of text. Each row now keeps only the sentence a reader
needs to make the choice (a consequence, a cost, where data goes, a
status); everything that merely explains what the control is moves to
the row's info tip.

InfoTip becomes the one shared help pattern: a lucide Info glyph that
reveals on hover and keyboard focus, pins on click or tap for touch,
dismisses on Escape, and is described by its text at all times (the
open tooltip, or `title` while closed). `hint` accepts a node so a tip
can carry two paragraphs, and SettingsCombobox gains the prop.

Five English strings are shortened in every catalog, and the settings
registry indexes the tip text for palette search when a row keeps no
description.
@bolichen97

Copy link
Copy Markdown
Contributor Author

Rebased 029c1189 -> 652a270c onto origin/main 5a70ce7d, which carries #16083 (the fix for the two inherited backend reds). No code change on this branch. Docs lint, the InfoTip/palette/settings suites (957 tests) and the previously red test_context_composition_contract.py pass locally. The UX override pinned to 029c1189 no longer applies to this head.

@bolichen97

Copy link
Copy Markdown
Contributor Author

self-added: yes

Correct: for a bubble with nothing to scroll the handler still calls preventDefault, so the arrow and Page keys do nothing while that tip is open and focused; Escape, Tab or blur releases them. The one-line fix (return before preventDefault when there is nothing to scroll, plus a test) is tracked in #16120 with an owner and a due date, rather than restarting every review lane on a head that has reached readiness after twenty rounds.

@bolichen97

Copy link
Copy Markdown
Contributor Author

self-added: yes

  • The sweep's premise ("a wall of text") cites no report; the convention justifying it ships in the same PR span=929eeb4a0938 — rebutted

The premise is the maintainer's own: #15837 records the request that Settings show less text with explanation behind an Info tip or hover, which is the "maintainer's explicit acceptance of the premise for this sweep" the item names as clearing it. The convention document is written down in this PR because the request made it the rule; the before/after pairs for every panel are the observation of the harm it names.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

Settings pages show too much text under every row

2 participants