Settings: another design pass, with one row style, less text and tabs considered (research first) #475

Closed
opened 2026-11-10 11:21:39 -05:00 by cmoriarty · 4 comments
Owner

What happens

The last pass (#463, item 7) fit every setting on one page, and it reads as messy and unprofessional:

  • Rows don't match. Labels are beside some controls and above others; input widths and heights vary; cards end at different heights.
  • Too much text. "default: 2", "Kept with vLLM · qwen3.8-27b" on four cards, "Limited to … by the ceiling", a how-to line under the backend selector. #187 moved explanations into ⓘ hovers; stray text has crept back.
  • Redundant labels. "Use CI" then "Check each round with the project's CI"; "Auto-approve" then "Approve gates automatically in new runs".

What we want

A style that is compact by design, not by shrinking. One screen is no longer the goal; a clean, consistent, professional page is.

  1. Research how well-made apps lay out dense settings (tabs, a side rail, grouped rows) and what one row holds (label, control, help, default, error). Post it here. Start with Apple, Microsoft, IBM Carbon and GitHub Primer guidance, NN/g on tabs and labels, and tools like JetBrains and macOS System Settings.
  2. Mock 2 or 3 options, tabs among them, with the real settings, as screenshots of the real console. The owner picks before anything is built.
  3. One row for every setting. A checkbox row is the name and the box, its sentence in the ⓘ. A default is a placeholder, not a line. The backend a setting is kept with is said once, not four times. A limit marks the control and its ⓘ.
  4. If tabs, Save and Discard still cover the whole page, and a tab with an unsaved change or an error shows it.

Done when

  • The research is on this issue and the owner has picked from the screenshots.
  • Every setting uses the same row; no text sits under a control except an error.
  • "Every setting is on one page" in the settings spec and its browser test are rewritten for the chosen layout; a phone still stacks.
  • Checked in a real browser with before and after screenshots; no setting changes meaning or how it saves.

Where to look: ui/src/components/Settings.tsx, openspec/specs/settings/spec.md, ui/e2e/console.spec.ts.

From the owner's review of the one-page settings, 2026-11-10.

**What happens** The last pass (#463, item 7) fit every setting on one page, and it reads as messy and unprofessional: - **Rows don't match.** Labels are beside some controls and above others; input widths and heights vary; cards end at different heights. - **Too much text.** "default: 2", "Kept with vLLM · qwen3.8-27b" on four cards, "Limited to … by the ceiling", a how-to line under the backend selector. #187 moved explanations into ⓘ hovers; stray text has crept back. - **Redundant labels.** "Use CI" then "Check each round with the project's CI"; "Auto-approve" then "Approve gates automatically in new runs". **What we want** A style that is compact by design, not by shrinking. One screen is no longer the goal; a clean, consistent, professional page is. 1. **Research** how well-made apps lay out dense settings (tabs, a side rail, grouped rows) and what one row holds (label, control, help, default, error). Post it here. Start with Apple, Microsoft, IBM Carbon and GitHub Primer guidance, NN/g on tabs and labels, and tools like JetBrains and macOS System Settings. 2. **Mock 2 or 3 options**, tabs among them, with the real settings, as screenshots of the real console. The owner picks before anything is built. 3. **One row for every setting.** A checkbox row is the name and the box, its sentence in the ⓘ. A default is a placeholder, not a line. The backend a setting is kept with is said once, not four times. A limit marks the control and its ⓘ. 4. **If tabs,** Save and Discard still cover the whole page, and a tab with an unsaved change or an error shows it. **Done when** - The research is on this issue and the owner has picked from the screenshots. - Every setting uses the same row; no text sits under a control except an error. - "Every setting is on one page" in the settings spec and its browser test are rewritten for the chosen layout; a phone still stacks. - Checked in a real browser with before and after screenshots; no setting changes meaning or how it saves. **Where to look:** `ui/src/components/Settings.tsx`, `openspec/specs/settings/spec.md`, `ui/e2e/console.spec.ts`. *From the owner's review of the one-page settings, 2026-11-10.*
Author
Owner

Research: how well-made apps lay out dense settings

Read first-hand: Apple, Microsoft, JetBrains, IBM Carbon, GitHub Primer and NN/g (links below). They agree on more than they differ.

What the sources say For Braid
Chunking JetBrains: group headers while a group has up to 10 controls and all groups fit in two dialog heights, tabs past that (up to 8), a side list beyond. Apple: a fixed toolbar of panes. NN/g: tabs for a few clear groups you need not compare side by side. About 35 controls in 7 sections: tabs or a side list. Settings that move each other share a pane.
Columns Primer: no columns just to save height. Microsoft: one column, about 1000 px wide. JetBrains: two only for short, related fields. The three columns go.
Labels 1–3 words, sentence case, no colon (Primer, Carbon, JetBrains). Left-aligned with the boxes aligned (JetBrains), or above (Carbon). One label column, one control column, three control widths.
Text Primer: a caption must add something and gives way to an error. Carbon: helper text only if truly needed, else a tooltip. JetBrains: never repeat the setting's name. The ⓘ holds every explanation. Under a control: an error, or why it is disabled.
Checkboxes A short label beside the box, no negation (JetBrains). NN/g and Carbon: switches act at once, so with a Save button use checkboxes. "Use CI", the box, the ⓘ.

Also: JetBrains tab rules (1–3 word labels, no "General" or "Advanced", most used first, never hide a tab, say why in its body); Apple: fewer settings, reopen on the last pane; Microsoft: keep rarely used settings behind an expander, and say in the row why a control is disabled.

What this means here. Panes of about ten rows that each fit a laptop window; the backend named once, not on four cards; the per-step thinking levels behind a disclosure; and Save stays, since Braid validates a save as a whole. Settings that move each other stay together: the model window, output reservation and context per agent (the ceiling), and parallel sessions with the run and subagent limits.

Next: three options with the real settings, as screenshots of the real console.

Sources: Apple · Microsoft · JetBrains groups, tabs, layout, help text, checkbox · Carbon forms, form · Primer forms · NN/g tabs, toggles

**Research: how well-made apps lay out dense settings** Read first-hand: Apple, Microsoft, JetBrains, IBM Carbon, GitHub Primer and NN/g (links below). They agree on more than they differ. | | What the sources say | For Braid | |---|---|---| | **Chunking** | JetBrains: group headers while a group has up to 10 controls and all groups fit in two dialog heights, tabs past that (up to 8), a side list beyond. Apple: a fixed toolbar of panes. NN/g: tabs for a few clear groups you need not compare side by side. | About 35 controls in 7 sections: tabs or a side list. Settings that move each other share a pane. | | **Columns** | Primer: no columns just to save height. Microsoft: one column, about 1000 px wide. JetBrains: two only for short, related fields. | The three columns go. | | **Labels** | 1–3 words, sentence case, no colon (Primer, Carbon, JetBrains). Left-aligned with the boxes aligned (JetBrains), or above (Carbon). | One label column, one control column, three control widths. | | **Text** | Primer: a caption must add something and gives way to an error. Carbon: helper text only if truly needed, else a tooltip. JetBrains: never repeat the setting's name. | The ⓘ holds every explanation. Under a control: an error, or why it is disabled. | | **Checkboxes** | A short label beside the box, no negation (JetBrains). NN/g and Carbon: switches act at once, so with a Save button use checkboxes. | "Use CI", the box, the ⓘ. | Also: JetBrains tab rules (1–3 word labels, no "General" or "Advanced", most used first, never hide a tab, say why in its body); Apple: fewer settings, reopen on the last pane; Microsoft: keep rarely used settings behind an expander, and say in the row why a control is disabled. **What this means here.** Panes of about ten rows that each fit a laptop window; the backend named once, not on four cards; the per-step thinking levels behind a disclosure; and Save stays, since Braid validates a save as a whole. Settings that move each other stay together: the model window, output reservation and context per agent (the ceiling), and parallel sessions with the run and subagent limits. Next: three options with the real settings, as screenshots of the real console. Sources: [Apple](https://developer.apple.com/design/human-interface-guidelines/settings) · [Microsoft](https://learn.microsoft.com/en-us/windows/apps/design/app-settings/guidelines-for-app-settings) · JetBrains [groups](https://plugins.jetbrains.com/docs/intellij/groups-of-controls.html), [tabs](https://plugins.jetbrains.com/docs/intellij/tabs.html), [layout](https://plugins.jetbrains.com/docs/intellij/layout.html), [help text](https://plugins.jetbrains.com/docs/intellij/inline-help-text.html), [checkbox](https://plugins.jetbrains.com/docs/intellij/checkbox.html) · Carbon [forms](https://carbondesignsystem.com/patterns/forms-pattern/), [form](https://carbondesignsystem.com/components/form/usage/) · [Primer forms](https://primer.style/product/ui-patterns/forms/) · NN/g [tabs](https://www.nngroup.com/articles/tabs-used-right/), [toggles](https://www.nngroup.com/articles/toggle-switch-guidelines/)
Author
Owner

Three layouts to pick from

Screenshots of the real console on fixture data, at 1280×800. All three use the same new row, so only the way the panes are held differs. Click an image for full size.

Now

The settings page now

A. Tabs (my pick). Backend · Model · Runs · Display, one row of tabs, each pane fits the window with room to spare. Model and Runs belong to the backend chosen in the selector at their top, which replaces "Kept with …" on four cards. Display is the console's, so it has none. A tab with an unsaved change or an error will get a dot (not drawn yet), and each pane has its own address, #/settings/runs.

Backend Model
Runs Display

B. Side list. The same four panes as a list on the left (Runs shown). It costs 9 rem of width for four items, and earns its place past about eight sections.

Side list, Runs pane

C. One column. Everything in a single scrolling column under a bar of jump links. It is more than two screens long, which is the opposite of compact.

One column

What changed in every option

  • One row: label, control, ⓘ, at one height and three widths (a number, a choice, a URL).
  • The ⓘ now ends with the default ("Default: 2"), and holds the limit warning: the ⓘ goes amber instead of a line under the box.
  • "Use CI" and "Auto-approve" are the name and a box. Their sentences are in the ⓘ.
  • "Apply the change" is one segmented row. The prices and the subagents are one row each. The per-step thinking levels sit behind "Thinking per step".
  • Left under a control: an error, why Delete is not offered, and the Connect result.

Which one? Reply here, or tell me in the session.

**Three layouts to pick from** Screenshots of the real console on fixture data, at 1280×800. All three use the same new row, so only the way the panes are held differs. Click an image for full size. **Now** [![The settings page now](https://forgejo.underthere.xyz/attachments/63f0fa89-cfab-4a31-aa7d-568ce20410b8)](https://forgejo.underthere.xyz/attachments/63f0fa89-cfab-4a31-aa7d-568ce20410b8) **A. Tabs** (my pick). Backend · Model · Runs · Display, one row of tabs, each pane fits the window with room to spare. Model and Runs belong to the backend chosen in the selector at their top, which replaces "Kept with …" on four cards. Display is the console's, so it has none. A tab with an unsaved change or an error will get a dot (not drawn yet), and each pane has its own address, `#/settings/runs`. | | | |---|---| | [![Backend](https://forgejo.underthere.xyz/attachments/958408e6-9705-41a4-8900-62f0e44f64be)](https://forgejo.underthere.xyz/attachments/958408e6-9705-41a4-8900-62f0e44f64be) | [![Model](https://forgejo.underthere.xyz/attachments/9248b62d-0f23-4d80-aaa6-2b65fc385a72)](https://forgejo.underthere.xyz/attachments/9248b62d-0f23-4d80-aaa6-2b65fc385a72) | | [![Runs](https://forgejo.underthere.xyz/attachments/4fa0db7e-a1b5-423e-93b4-6b41ddb09f03)](https://forgejo.underthere.xyz/attachments/4fa0db7e-a1b5-423e-93b4-6b41ddb09f03) | [![Display](https://forgejo.underthere.xyz/attachments/589b2ca0-d04f-4602-95d8-aa7cacc26e75)](https://forgejo.underthere.xyz/attachments/589b2ca0-d04f-4602-95d8-aa7cacc26e75) | **B. Side list.** The same four panes as a list on the left (Runs shown). It costs 9 rem of width for four items, and earns its place past about eight sections. [![Side list, Runs pane](https://forgejo.underthere.xyz/attachments/25f423bd-971d-4dec-aead-c83ff4dbb128)](https://forgejo.underthere.xyz/attachments/25f423bd-971d-4dec-aead-c83ff4dbb128) **C. One column.** Everything in a single scrolling column under a bar of jump links. It is more than two screens long, which is the opposite of compact. [![One column](https://forgejo.underthere.xyz/attachments/c691ae41-4903-4263-a77e-19ea759bab4d)](https://forgejo.underthere.xyz/attachments/c691ae41-4903-4263-a77e-19ea759bab4d) **What changed in every option** - One row: label, control, ⓘ, at one height and three widths (a number, a choice, a URL). - The ⓘ now ends with the default ("Default: 2"), and holds the limit warning: the ⓘ goes amber instead of a line under the box. - "Use CI" and "Auto-approve" are the name and a box. Their sentences are in the ⓘ. - "Apply the change" is one segmented row. The prices and the subagents are one row each. The per-step thinking levels sit behind "Thinking per step". - Left under a control: an error, why Delete is not offered, and the Connect result. Which one? Reply here, or tell me in the session.
Author
Owner

Decision (owner): the one column, with a search.

Option C is the layout: one scrolling column, which also reads well on a phone. The bar of jump links goes, and a search box takes its place: it shows the settings that match what is typed, as it is typed, and the sections that have none drop out.

Building it now, in a worktree, with the proposal first:

  • sections in one order: Backend, Model, Runs, Agents (all the backend chosen at the top), then Planning and repair and Display
  • one heading style for every section
  • the search matches names, a few synonyms and the ⓘ text; Escape clears it, and / jumps to it
  • a refused save clears the search and scrolls to the first field to fix, since the page is no longer one screen
  • checked at laptop and phone widths with before and after screenshots
**Decision (owner): the one column, with a search.** Option C is the layout: one scrolling column, which also reads well on a phone. The bar of jump links goes, and a search box takes its place: it shows the settings that match what is typed, as it is typed, and the sections that have none drop out. Building it now, in a worktree, with the proposal first: - sections in one order: Backend, Model, Runs, Agents (all the backend chosen at the top), then Planning and repair and Display - one heading style for every section - the search matches names, a few synonyms and the ⓘ text; Escape clears it, and `/` jumps to it - a refused save clears the search and scrolls to the first field to fix, since the page is no longer one screen - checked at laptop and phone widths with before and after screenshots
Author
Owner

Shipped in #478, archived in #479.

The settings page is one column of one-shape rows, the owner's choice of the three layouts mocked above.

  • Every setting is a label, a control and an ⓘ, at one height and three widths. "Use CI" and "Auto-approve" are the name and a box; their sentences, the defaults, the model's default and the context-per-agent limit warning are in the ⓘ (amber when it warns). Kept with … is gone.
  • The sections run Backend, Model, Runs, Agents (the backend chosen at the top), then Planning and repair and Display. Apply the change is one row of segments, prices and subagents are one row each, and the per-step thinking levels sit behind "Thinking per step".
  • A search box in the heading row shows only the settings that match what is typed, as it is typed: by name, a few synonyms or the ⓘ text. Escape clears it, and a refused save clears it and scrolls to the field to fix.
  • It stacks on a phone: nothing scrolls sideways and Save stays in view.

Evidence, from the laptop

  • ./tools/test.sh passed in 47 s, 52 browser journeys among them. The new search journey cannot pass on the old page, which has no search box, and it also asks for every setting by its own name. A phone journey replaces the one that held every setting in a laptop window, whose rule ("Every setting is on one page") the settings spec no longer has.
  • Four unit tests for the matcher, the real console on fixture data at 1280×800 and 390×844 (screenshots on #478).
  • Nothing a model sees changed, so there is no replay.

The research is the first comment above, and the owner's pick of the layout the third.

**Shipped** in #478, archived in #479. The settings page is one column of one-shape rows, the owner's choice of the three layouts mocked above. - Every setting is a label, a control and an ⓘ, at one height and three widths. "Use CI" and "Auto-approve" are the name and a box; their sentences, the defaults, the model's default and the context-per-agent limit warning are in the ⓘ (amber when it warns). `Kept with …` is gone. - The sections run Backend, Model, Runs, Agents (the backend chosen at the top), then Planning and repair and Display. Apply the change is one row of segments, prices and subagents are one row each, and the per-step thinking levels sit behind "Thinking per step". - A search box in the heading row shows only the settings that match what is typed, as it is typed: by name, a few synonyms or the ⓘ text. Escape clears it, and a refused save clears it and scrolls to the field to fix. - It stacks on a phone: nothing scrolls sideways and Save stays in view. **Evidence, from the laptop** - `./tools/test.sh` passed in 47 s, 52 browser journeys among them. The new search journey cannot pass on the old page, which has no search box, and it also asks for every setting by its own name. A phone journey replaces the one that held every setting in a laptop window, whose rule ("Every setting is on one page") the settings spec no longer has. - Four unit tests for the matcher, the real console on fixture data at 1280×800 and 390×844 (screenshots on #478). - Nothing a model sees changed, so there is no replay. The research is the first comment above, and the owner's pick of the layout the third.
Sign in to join this conversation.
No labels
No milestone
No project
No assignees
1 participant
Notifications
Due date
The due date is invalid or out of range. Please use the format "yyyy-mm-dd".

No due date set.

Dependencies

No dependencies set

Reference
cmoriarty/braid#475
No description provided.