Repository navigation
feat(settings): move explanatory help behind an info tip - #15823
Conversation
GPT 5.6 Review — ✅ no blocking findingsGPT 5.6 completed its review of This comment is updated in place on each push. Review detailsNo findings. False positive or not applicable? A repository writer can comment: |
Design Review (Fable 5) — ✅ PASSDesign-level review of 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 |
First Principles Review (Fable 5) — 🟡 CONCERNSPremise-level review of 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 Not justified as shipped
What this change shipsInventory (10 items) — 9 justifiedIntent: 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).
[FIRST-PRINCIPLES-REVIEWED] 652a270 Description read[DESCRIPTION-READ] d65ac1261ac0c08ec3d402ad714c4347621486383a47c9ae03115a62347ec758 That sha256 names the PR description this verdict read. Recompute it with |
UX Review (Fable 5) — 🔴 could not evaluateThe blind read could not run for [UX-REVIEWED] 652a270 |
87ad401 to
c5d1610
Compare
|
|
|
|
|
|
Opus 5 Review — ✅ no blocking findingsReviewed Review detailsThe 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 — [OPUS-REVIEWED] 652a270 Verdict parsed from the review's SHA-scoped output markers for commit False positive or not applicable? A repository writer can comment: |
c5d1610 to
e00d32b
Compare
|
self-added: yes
|
|
|
|
e00d32b to
dcc0e6f
Compare
|
self-added: yes
|
|
|
dcc0e6f to
50864fb
Compare
|
Rebased |
|
self-added: yes
|
|
self-added: yes
|
|
self-added: yes
|
|
self-added: yes
|
|
self-added: yes
|
|
self-added: yes
|
|
Rebased |
|
self-added: yes
|
|
self-added: yes
|
|
self-added: yes
|
|
self-added: yes
|
|
Rebased |
|
/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. |
Human judgment recorded@bolichen97 marked the ux AI finding as false positive, not applicable, or explicitly accepted for
This decision applies only to this commit. A new push requires a new judgment. |
|
Inherited red, not from this diff (no Python changed): on head |
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.
|
Rebased |
|
self-added: yes
|
|
self-added: yes
|
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
What changed (motivation → approach → change)
Settings rows had too many words on screen. The row primitives already had two slots —
description, always visible, andhint, an info tip — but nearly every panel useddescription. This PR triages each row: a sentence a reader needs to MAKE the choice (a cost, a consequence, where data goes, a status) stays asdescription; a sentence that only explains what the control is becomes ahint. 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 underwebsite/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).InfoTiprevealInfoTipbubblemaxHeightcapped to the room, scrollsInfoTipglyphInfohintpropSettingsComboboxSettingsComboboxdescriptiononlyhintstring when a row keeps no description🟩 added · 🟨 changed · 🟦 unchanged
InfoTipis 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, ortitlewhile 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.InfoTipdoes not reuseInstantTip'suseInstantTipgesture 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/(anden-XA.jsonis 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 (newbusy_alt_action_summarykey: 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 assettingsKeywords.tsphrases 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.mdgains the description-or-tip rule; theInfoTipsection ofdocs/system-specs/modules/learn-cron-dashboard.mddescribes 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,titlepresent 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 isdefaultPrevented), 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 withmaxHeightcapped to the room above (andoverflow-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 owningSettingsToggle(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 fourMore informationhelp toggles (Composable layout keeps its sentence on the row), and an ingress set that stays empty (thenOpen Webhooksafter that toggle), so every button on the tab stays observed;OverviewMemoryTabCov80.test.tsxpins 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'stitle.settingsRegistry.test.tsandtest/test_settings_deeplink_registry.pypin 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 onorigin/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.
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):
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)
Gated states, captured on this branch's pod with the gate flipped (no origin/main pair: the gate hides the row entirely there too):
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 sameInfoTip/descriptionprops every row shown here uses, so the diff is the evidence for those branches.Related Issues
Closes #15837
Checklist
feat|fix|docs|style|refactor|perf|test|chore|ci|build|revert: ...)