Standardize Settings layout and save feedback (#2122)

* Group settings navigation menu

Co-authored-by: Serhii Dziupin <makeittech@users.noreply.github.com>

* Revert "Group settings navigation menu"

This reverts commit 5983a4e82074b8dab1084af1cadd803ba28ea65d.

* Standardize settings layout feedback

Co-authored-by: Serhii Dziupin <makeittech@users.noreply.github.com>

* Fix settings save status timer typing

Co-authored-by: Serhii Dziupin <makeittech@users.noreply.github.com>

* Retain settings save status

Co-authored-by: Serhii Dziupin <makeittech@users.noreply.github.com>

* Report color mode save state

Co-authored-by: Serhii Dziupin <makeittech@users.noreply.github.com>

* Match Appearance settings to two-column layout

Rebuild Appearance into Color mode & Theme, Localization, and Density & type sections with responsive two-column grids, consistent section headers, page description, and green save status.

Co-authored-by: Serhii Dziupin <makeittech@users.noreply.github.com>

* Migrate settings pages to SettingsPageLayout and SettingsSection

Replace ScrollableOverlay/max-w-3xl shells with the shared settings
layout primitives across entity and static settings pages, normalize
section headers, and add settings.page.behavior.description locales.

Co-authored-by: Serhii Dziupin <makeittech@users.noreply.github.com>

* Unify remaining settings pages on shared section chrome

Wire Appearance, Projects, and Remote Instances through SettingsSection/SettingsPageLayout so every settings surface shares the same header, divider, and page shell treatment.

Co-authored-by: Serhii Dziupin <makeittech@users.noreply.github.com>

* Align settings UI with OpenChamber design system kit

Apply kit geometry and control specs: 840px content width, 32/48 padding, fixed 260/280 sidebars, radius/spacing tokens, settings select height, stepper dimensions, and shared field/link typography.

Co-authored-by: Serhii Dziupin <makeittech@users.noreply.github.com>

* Migrate OpenChamberVisualSettings to shared settings primitives

Replace ad-hoc radio/checkbox/chip/field layouts with SettingsSection
shared chrome for Appearance, Density, Navigation, Chat/behavior, and
Privacy while preserving handlers and data-settings-item anchors.

Co-authored-by: Serhii Dziupin <makeittech@users.noreply.github.com>

* Migrate settings pages to shared field/checkbox/radio primitives

Unify Defaults, Notifications, Behavior, Git, Session Retention, Passkeys,
OpenCode CLI, Commands, About, Keyboard Shortcuts, and Desktop Network on
SettingsFieldRow / SettingsCheckboxRow / SettingsRadioGroup / SettingsChipGroup
for consistent grid, spacing, and DRY layout. Also remove the GitPage double
SettingsSection wrap around GitHubSettings.

Co-authored-by: Serhii Dziupin <makeittech@users.noreply.github.com>

* Unify remaining settings pages onto shared field primitives

Migrate Agents, Snippets, Skills, Usage, MCP identity rows and selects to
SettingsFieldRow/CheckboxRow/ChipGroup and SETTINGS_SELECT_*; align page
titles; light-touch Voice/Tunnel/Providers/Plugins without rewriting
complex OAuth, permissions, or tunnel flows.

Co-authored-by: Serhii Dziupin <makeittech@users.noreply.github.com>

* Polish settings section dividers and transport helper text

Slightly stronger section borders for clearer group separation, and keep
message-stream transport description under the chip control.

Co-authored-by: Serhii Dziupin <makeittech@users.noreply.github.com>

* Fix settings grid alignment, control heights, and Chat section titles

Co-authored-by: Serhii Dziupin <makeittech@users.noreply.github.com>

* Tighten settings grid: flat Chat 2x2 and full-width stacked selects

Message options use a flat two-column grid so row headers share a baseline.
Stacked selects fill their column; field-row selects keep a fixed sm:w-56 width.

Co-authored-by: Serhii Dziupin <makeittech@users.noreply.github.com>

* Align mixed settings controls to shared FieldRow/CheckboxRow grid

Separate FieldRows from CheckboxRows with SettingsInset, move enum
radios into ControlGroups, and convert misplaced StackedFields to
full-width FieldRows so left edges no longer clash.

Co-authored-by: Serhii Dziupin <makeittech@users.noreply.github.com>

* Translate Behavior response-style preset labels for es and pl

Co-authored-by: Serhii Dziupin <makeittech@users.noreply.github.com>

* Group settings nav into categories and improve icons/order

Co-authored-by: Serhii Dziupin <makeittech@users.noreply.github.com>

* Fix settings layout: fewer hrs, shared control widths, chat transport section

Remove SettingsInset top borders, align App install/Density controls to full cluster width, give Message Stream Transport its own Chat section, and fold Sessions Small Model into the first section to cut extra dividers.

Co-authored-by: Serhii Dziupin <makeittech@users.noreply.github.com>

* Align Voice and MCP settings labels with shared heading classes

Swap form field labels to SETTINGS_FIELD_LABEL_CLASS and use
SettingsGroupTitle for MCP control-group headings (manual auth fallback,
request headers).

Co-authored-by: Serhii Dziupin <makeittech@users.noreply.github.com>

* Differentiate settings heading levels by context

Page titles are larger and quieter than section titles; group and field
labels use dedicated shared classes so hierarchy is consistent across
settings surfaces without ad-hoc typography mixes.

Co-authored-by: Serhii Dziupin <makeittech@users.noreply.github.com>

* Use shared settings title classes in SettingsView home

Wire home and unavailable headings through the shared L1/L2 class
constants so they stay aligned with SettingsPageLayout.

Co-authored-by: Serhii Dziupin <makeittech@users.noreply.github.com>

* Keep settings number steppers from stretching +/- buttons

Density & type NumberInputs no longer flex-grow across the row, and
NumberInput locks minus/plus to fixed width so the plus side cannot
inflate when the control is placed in a full-width cluster.

Co-authored-by: Serhii Dziupin <makeittech@users.noreply.github.com>

* Place spacing and input-bar offset on their own row

Density & type now lays out as font families, then font sizes, then
Spacing Density / Input Bar Offset on the row below.

Co-authored-by: Serhii Dziupin <makeittech@users.noreply.github.com>

* Regroup settings nav and improve Voice layout

Drop Advanced/Usage/Git nav categories: Voice and About under
Interface, Usage under OpenCode, Git under Workspace. Voice provider
chips and STT model cards use shared settings primitives with roomier
spacing and a two-column model grid.

Co-authored-by: Serhii Dziupin <makeittech@users.noreply.github.com>

* Space out chat feature groups in visual settings

* Polish settings: save-state wiring, container-query layouts, unified dropdown triggers

- Wire shared save indicator into Behavior page saves and git identity CRUD
- Convert settings layout primitives and page rows from viewport to container
  queries so narrow panes stack instead of clipping
- Unify custom dropdown triggers (model/agent/provider pickers) and remaining
  page selects on the settings control size
- Bump global radius scale by 1px; align variant input with select size
- Migrate stray raw controls (MCP OAuth checkbox, worktree remove button,
  git identity dialog rows, skills dialog labels) onto shared primitives
- Make settings nav items span full sidebar width; trim nav to 240px

* Add General settings page, regroup nav, cap control widths, promote chat feature headers

* Mobile settings nav: plain background and touch-sized rows

* Hide secondary settings descriptions behind clickable info hints

* Move quota credentials to Usage, navigation settings to General, rename External Tunnel

* Quiet settings save indicator: silent success, delayed spinner, visible errors

* Rewrite settings-ui-patterns skill around shared primitives and refactored conventions

* Remove settings starter page; open last visited page, defaulting to General

* Settings polish: spacing, control sizes, trigger widths, readable model names, device dates

* Centralize dropdown trigger chrome, settings nav polish, mobile-only input bar offset

* Fix global line-height regression, auto-hide first-section divider, shortcut row spacing

* Global line-height 1.45, align scheduled tasks header button with select

* Hide editor toolbar and About in VS Code, animate chat render preview outside desktop dialog

* Rebuild agent tool permissions on source-of-truth model

Edit the agent's own permission map verbatim (inherit vs explicit actions, pattern rules only for pattern-capable keys), save permission-only, drop the server-side non-wildcard re-merge that resurrected deleted rules, and surface session-granted rules as read-only.

* Agents model parameters polish: row spacing, variant dropdown, unified widths, dash for unset numbers

---------

Co-authored-by: Serhii Dziupin <makeittech@users.noreply.github.com>
Co-authored-by: Bohdan Triapitsyn <artmore@protonmail.com>

.agents/skills/settings-ui-patterns/SKILL.md

@@ -15,54 +15,74 @@ When examples conflict, shared component/theme and localization contracts win. S
 
 ## Canonical Direction
 
-- Prefer flat hierarchy built with spacing and typography.
-- Avoid unnecessary cards, wrappers, row chrome, and redundant headings.
-- Keep controls compact and align related rows consistently.
-- Put checkbox/radio state before labels.
-- Use subtle, stable selected-state styling without layout shifts.
-- Preserve responsive wrapping/stacking and long-text behavior.
+Settings are built from the shared primitives in
+`packages/ui/src/components/sections/shared/SettingsSection.tsx`,
+`SettingsPageLayout.tsx`, and `SettingsInfoHint.tsx`. Never hand-roll page
+chrome, section headers, field rows, checkbox rows, or info tooltips with raw
+divs — use the primitives, and extend them (in the shared file) when a new
+shape is genuinely missing.
+
+- Flat hierarchy through spacing and typography; no cards, boxed backgrounds, or row chrome.
+- Secondary helper text is hidden behind an info icon (`info` prop); the default view stays quiet.
+- Controls have one standard size (`h-9` / select `size="settings"`) and capped widths — no full-bleed inputs.
+- Layouts respond to the settings pane width via container queries (`@xl:` / `@3xl:`), never viewport `sm:`/`lg:` breakpoints (the pane is much narrower than the viewport inside the dialog).
+- Checkbox/radio state comes before labels; selected states are subtle and never shift layout.
 
 ## Load References By Task
 
 | Task | Required reference |
 |---|---|
-| Page hierarchy, typography, spacing, columns, responsive grids | `references/layout.md` |
-| Chips, radios, checkboxes, numeric overrides, inputs, icon actions, pickers | `references/controls.md` |
+| Page skeleton, sections, hierarchy, nav placement, spacing, columns, responsiveness | `references/layout.md` |
+| Field rows, checkboxes, radios, chips, selects, inputs, numeric steppers, info hints | `references/controls.md` |
 | Adding/moving controls, pages, availability, anchors, or search entries | `references/search.md` |
 
 Load every matching reference before editing.
 
-## Quick Control Selection
+## Quick Primitive Selection
 
-| Need | Shared pattern |
+| Need | Shared primitive |
 |---|---|
-| Short selectable options | `Button variant="chip" size="xs"` + `aria-pressed` |
-| Mutually exclusive mode list | `Radio` rows |
-| Boolean | `Checkbox` |
-| Numeric value/override | `NumberInput` |
-| Text/path | `Input` with shared adjacent actions |
-| Icon-only action | `Button size="icon"` + sprite `Icon` + localized `aria-label` |
+| Page wrapper (title, description, save status, scrolling, `@container`) | `SettingsPageLayout` |
+| Titled block with divider | `SettingsSection` (`divider={false}` for the first one) |
+| Label left / control right | `SettingsFieldRow` |
+| Label above control (two-column cells, wide controls) | `SettingsStackedField` |
+| Boolean | `SettingsCheckboxRow` |
+| Mutually exclusive list | `SettingsRadioGroup` + `SettingsRadioOption` |
+| Short segmented options | `SettingsChipGroup` |
+| Sub-cluster with a quiet L3 title inside a section | `SettingsControlGroup` |
+| Two-column area on wide panes | `SettingsTwoColumn` |
+| Helper text on demand (hover + tap) | `info` prop or `SettingsInfoHint` |
 
-Do not introduce `ButtonSmall`, direct Remixicon components, hardcoded user-facing strings, or one-off color/button systems.
+Do not introduce raw `<Tooltip>`-based info icons, direct Remixicon components, hardcoded user-facing strings, or one-off color/button systems. New icons: reference a Remix icon name in code, then run `bun run icons:generate` to add it to the sprite.
+
+## Description Policy (info hints)
+
+- Explanatory prose (what a feature does, when it applies) goes behind the info icon via the `info` prop — never as always-visible `description`.
+- Stays visible: security/data-loss warnings, destructive consequences, required syntax/placeholder lists the user reads while typing, dynamic status, empty states, validation errors, active-flow wizard instructions.
+- Mixed text: keep the warning sentence visible, move the explanation to `info`.
+
+## Save Feedback
+
+`SettingsPageLayout showSaveStatus` renders the shared quiet indicator: success is silent, "Saving…" appears only past ~500 ms, failures show "Save failed". Anything persisted through `updateDesktopSettings` reports automatically; page-specific APIs must call `reportSettingsSaveState` from `@/lib/persistence`. Never add per-page save badges or success toasts for ordinary setting writes.
 
 ## Settings Search Contract
 
 Every stable Settings control addition or move must consider search in the same change:
 
 - explicit registry item in `packages/ui/src/lib/settings/search.ts` when searchable;
-- matching `data-settings-item` anchor;
+- matching `data-settings-item` anchor (primitives accept `settingsItem`);
 - localized title/description keys;
 - availability matching actual render conditions;
-- state preparation before highlighting conditional targets.
+- when a control moves to another page, update the item's `page` too.
 
 Dynamic entity rows normally are not indexed. Load `references/search.md` for exact rules.
 
 ## Review Checklist
 
-- Hierarchy reads through spacing and typography without unnecessary boxes.
-- Shared controls are used with localized visible/accessibility text.
-- Desktop alignment degrades cleanly on narrow/mobile layouts.
-- Disabled state affects the control, not unrelated labels, unless intentional.
-- Long labels and adjacent actions do not overflow.
-- Search registry, anchor, localization, and availability agree.
+- Built from shared primitives; no ad-hoc page/section/row markup.
+- Explanatory text hidden behind `info`; warnings/syntax/status still visible.
+- Container-query (`@xl:`/`@3xl:`) responsiveness — no viewport breakpoints in pane content.
+- Controls use the standard size and width caps; no stretched full-width inputs.
+- Localized visible and accessibility text everywhere.
+- Search registry, anchor, page, localization, and availability agree.
 - Nearby Settings precedent and relevant tests remain consistent.

.agents/skills/settings-ui-patterns/references/controls.md

@@ -1,83 +1,83 @@
 # Settings Controls
 
-Load `theme-system` for button/icon/color contracts and `locale-ui-patterns` for every visible or accessible string.
+Load `theme-system` for button/icon/color contracts and `locale-ui-patterns`
+for every visible or accessible string. All primitives/constants come from
+`packages/ui/src/components/sections/shared/SettingsSection.tsx` (+
+`SettingsInfoHint.tsx`).
 
-## Choosing A Control
+## Standard Sizes And Widths
 
-- Short chip-like option set: shared `Button variant="chip" size="xs"` with `aria-pressed`.
-- Explicit mutually exclusive list: shared `Radio`.
-- Boolean value: shared `Checkbox`, not paired show/hide buttons.
-- Numeric value: shared `NumberInput`.
-- Text/path value: shared `Input` plus shared actions.
+One control size across Settings — `h-8`:
 
-Do not couple unrelated toggles beneath a synthetic heading.
+- `SelectTrigger`: `size={SETTINGS_SELECT_SIZE}` ('settings' → h-8, rounded-md, px-3).
+- Custom dropdown triggers (ModelSelector / AgentSelector): `SETTINGS_CUSTOM_TRIGGER_CLASS`.
+- Text `Input` next to dropdowns: `h-8 rounded-md px-3` (match the trigger footprint).
+- Icon action next to a control: `SETTINGS_ICON_BUTTON_CLASS`.
 
-## Segmented Option
+Widths are capped — never let controls span the pane:
+
+- Field-row control cluster / stacked-field default cap: `max-w-[24rem]` (built into `SettingsStackedField`; use `SETTINGS_CONTROL_CLUSTER_CLASS` elsewhere).
+- Field-row selects: `SETTINGS_SELECT_ROW_TRIGGER_CLASS` (full width narrow, `@xl:w-56` wide).
+- Stacked-field selects: `SETTINGS_SELECT_TRIGGER_CLASS` (fills the capped container).
+- Genuinely full-width content (dialog textareas): opt out with `controlClassName="w-full max-w-none"`.
+
+## Field Rows
 
 ```tsx
-<Button variant="chip" size="xs" aria-pressed={isSelected}>
-  {t(labelKey)}
-</Button>
+<SettingsFieldRow
+  label={t('...label')}
+  info={t('...hint')}                 // helper text behind the info icon
+  settingsItem="page.some-setting"
+>
+  <Select …>
+    <SelectTrigger size={SETTINGS_SELECT_SIZE} className={SETTINGS_SELECT_ROW_TRIGGER_CLASS} aria-label={t('...aria')}>…
 ```
 
-## Radio Row
+Use `SettingsStackedField` (label above control) inside `SettingsTwoColumn`
+cells or when the control is wide; same `info` / `settingsItem` props.
+
+## Boolean
 
 ```tsx
-<div role="radiogroup" aria-label={t(groupLabelKey)}>
-  <div className="flex items-center gap-2 py-0.5">
-    <Radio checked={selected} onChange={onSelect} ariaLabel={t(labelKey)} />
-    <span className={cn('typography-ui-label', selected ? 'text-foreground' : 'text-foreground/50')}>
-      {t(labelKey)}
-    </span>
-  </div>
-</div>
-```
-
-## Checkbox Row
-
-```tsx
-<div className="flex cursor-pointer items-center gap-2 py-1.5">
-  <Checkbox checked={value} onChange={setValue} ariaLabel={t(labelKey)} />
-  <span className="typography-ui-label">{t(labelKey)}</span>
-</div>
-```
-
-Preserve row click and keyboard behavior when the container is interactive.
-
-## Optional Numeric Override
-
-Empty means “inherit/default.” Provide fallback stepping and explicit clear:
-
-```tsx
-<NumberInput
-  value={temperature}
-  fallbackValue={0.7}
-  onValueChange={setTemperature}
-  onClear={() => setTemperature(undefined)}
-  min={0}
-  max={2}
-  step={0.1}
-  inputMode="decimal"
-  emptyLabel="—"
+<SettingsCheckboxRow
+  checked={value}
+  onChange={setValue}
+  label={t('...label')}
+  ariaLabel={t('...aria')}
+  info={t('...explanation')}          // optional; see Description Policy
+  settingsItem="page.some-setting"
 />
 ```
 
-Keep reset adjacent. Prefer an info tooltip over persistent helper text when the explanation is secondary.
+Row click + keyboard toggling are built in. A visible `description` is only
+for text that must stay visible (warnings, dynamic status).
 
-## Inputs And Icon Actions
+## Mutually Exclusive Options
 
 ```tsx
-<div className="flex items-center gap-2">
-  <Input className="h-7" />
-  <Button variant="outline" size="icon" aria-label={t(browseLabelKey)}>
-    <Icon name="folder" className="size-4" />
-  </Button>
-</div>
+<SettingsRadioGroup aria-label={t('...group')}>
+  <SettingsRadioOption selected={…} onSelect={…} label={t('...')} ariaLabel={t('...')} />
+</SettingsRadioGroup>
 ```
 
-- Prefer compact inputs in dense rows.
-- Avoid large select triggers in Settings.
-- Use shared `Button` and sprite `Icon`, never wrapper buttons or direct Remixicon imports.
+Skip per-option descriptions when labels are self-explanatory. For short
+segmented choices use `SettingsChipGroup` (chips with `aria-pressed`).
+
+## Numeric Value / Override
+
+`NumberInput` inside `SETTINGS_NUMBER_STEPPER_ROW_CLASS`, with
+`SETTINGS_NUMBER_UNIT_CLASS` for the unit and an adjacent
+`SETTINGS_ICON_BUTTON_CLASS` reset button. Never flex-grow the stepper.
+Optional overrides: empty means "inherit"; provide `fallbackValue`,
+`onClear`, `emptyLabel="—"`.
+
+## Info Hints
+
+`SettingsInfoHint` is the only info-icon implementation: it opens on hover
+AND on click (touch devices have no hover), and closes on outside tap.
+Prefer the `info` prop of the enclosing primitive; use the component
+directly only next to raw labels/headings. Never build info icons from raw
+`<Tooltip>` + `<Icon name="information">` — those don't work on mobile.
 
 ## Mobile Constraints
 
@@ -89,3 +89,10 @@ Keep reset adjacent. Prefer an info tooltip over persistent helper text when the
 - Place icon/color palettes beneath their label.
 - Keep option dimensions and gaps consistent.
 - Use stable border/ring/background selection; avoid scale transforms that shift layout.
+
+## Dialogs
+
+Dialogs reuse the same primitives (`SettingsCheckboxRow`,
+`SETTINGS_FIELD_LABEL_CLASS`, `SettingsStackedField`) and the same sizes.
+Dividers between dialog form groups are acceptable; wizard step
+instructions guiding an active flow stay visible (not behind info).

.agents/skills/settings-ui-patterns/references/layout.md

@@ -1,53 +1,67 @@
 # Settings Layout
 
-## Visual Hierarchy
+All primitives and class constants below live in
+`packages/ui/src/components/sections/shared/SettingsSection.tsx` and
+`SettingsPageLayout.tsx`. Import them; never re-declare local equivalents.
 
-- Prefer spacing and typography over boxed backgrounds.
-- Avoid wrappers that mix unrelated controls.
-- Omit redundant headings when page context already names the controls.
-- Keep controls compact and row chrome minimal.
-- Place checkbox/radio state before its label.
-- Dim inactive option labels subtly; do not use transform jumps.
+## Page Skeleton
 
-## Typography
+```tsx
+<SettingsPageLayout
+  title={t('settings.page.x.title')}
+  description={t('settings.page.x.description')}
+  showSaveStatus
+>
+  <SettingsSection title={t('...sectionA')} divider={false}>…</SettingsSection>
+  <SettingsSection title={t('...sectionB')}>…</SettingsSection>
+</SettingsPageLayout>
+```
 
-Use classes from `packages/ui/src/lib/typography.ts`:
+- `SettingsPageLayout` owns scrolling, page padding, the `@container` context, and the quiet save indicator (`showSaveStatus`).
+- Sections separate with a top border (`divider`, default true); the first section under the page header passes `divider={false}`.
+- Section titles are real headers (L2). Do not nest an umbrella section around a list of `SettingsControlGroup`s when each group deserves its own header — promote groups to sections instead (see the Chat page precedent).
 
-- Page title: `typography-ui-header font-semibold text-foreground`
-- Section header: `typography-ui-header font-medium text-foreground`
-- Control group: `typography-ui-header font-medium` or `font-normal` when needed
-- Values/labels: `typography-ui-label text-foreground`
-- Helper/meta: `typography-meta text-muted-foreground` or `typography-small text-muted-foreground`
-- Numeric values: add `tabular-nums`
+## Hierarchy Levels
+
+| Level | Component / class | Use |
+|---|---|---|
+| L1 | `SETTINGS_PAGE_TITLE_CLASS` (via `SettingsPageLayout`) | Page title |
+| L2 | `SettingsSection` title (`SETTINGS_SECTION_TITLE_CLASS`) | Section |
+| L3 | `SettingsControlGroup` title (`SETTINGS_GROUP_TITLE_CLASS`) | Sub-cluster inside a section |
+| L4 | `SETTINGS_FIELD_LABEL_CLASS` | Field / control labels |
+| Helper | `SETTINGS_HELPER_CLASS`, `SETTINGS_DESCRIPTION_CLASS` | Rare visible helper text (most goes behind `info`) |
+
+## Navigation Placement
+
+Sidebar groups (`packages/ui/src/lib/settings/metadata.ts`, order in `SettingsView.tsx`):
+
+- **OpenChamber** (`general` group): General, Appearance, Chat, Notifications, Sessions, Shortcuts, Voice, Usage, About.
+- **Workspace** (`projects`): Projects, Remote Instances, External Tunnel, Git.
+- **OpenCode** (`opencode`): Providers, Agents, Behavior, Commands, MCP, Plugins.
+- **Library** (`content`): Magic Prompts, Snippets, Skills, Skills Catalog.
+
+Placement rules:
+
+- **General** hosts app-level settings that don't belong to a feature page: startup/tray/window, network access + UI password, passkeys, OpenCode CLI binary, terminal shell/navigation, message stream transport, privacy.
+- Feature pages (Appearance, Chat, Sessions…) keep only settings about that feature. If a setting reads awkwardly on its page, move it to General rather than inventing a new page.
+- New pages need metadata, `pageOrder`, nav icon, `settings.page.<slug>.title/description` in every locale, and mobile whitelist (`MOBILE_SETTINGS_PAGES` in `MobileApp.tsx`) when relevant.
+
+## Responsiveness: Container Queries
+
+The settings pane is far narrower than the viewport (3-pane dialog). All
+pane content responds to the pane via container queries — `@xl:` (36rem) and
+`@3xl:` (48rem) — never viewport `sm:`/`lg:`. `SettingsPageLayout` provides
+the `@container` scope; `SettingsFieldRow`, `SettingsTwoColumn`, and the
+trigger-width constants already carry the right variants.
+
+Exception: `SettingsView` navigation chrome (outside the pane) uses viewport
+`sm:` to give phones 44px touch rows and plain `bg-background`; keep that
+pattern when touching nav.
 
 ## Spacing
 
-- Keep section-to-section spacing larger than header-to-content spacing.
-- Typical flat section: header `mb-1 px-1`, content `pt-0 pb-2 px-2`, outer `mb-8`.
-- Group related controls with `space-y-3` and modest internal padding such as `p-2`.
-- Avoid elevated backgrounds, rounded rows, and hover fills without explicit UX value.
-
-## Alignment
-
-For consistent desktop columns:
-
-```tsx
-<div className="flex items-center gap-8 py-1.5">
-  <span className="w-56 shrink-0 typography-ui-label">{t(labelKey)}</span>
-  <div className="flex w-fit items-center gap-2">...</div>
-</div>
-```
-
-- Let narrow layouts stack or wrap.
-- Compare the complete control footprint, including adjacent actions, when matching widths.
-- Disable only the unavailable control; do not dim the entire label row by default.
-
-## Responsive Grids
-
-Use a one-column base and introduce columns at a deliberate breakpoint:
-
-```tsx
-<div className="grid grid-cols-1 gap-2 md:grid-cols-[14rem_auto] md:gap-x-8" />
-```
-
-Template fields commonly use `grid grid-cols-1 gap-2 md:grid-cols-2 md:gap-3` with flat `p-2` cells.
+- Sections own vertical rhythm: divider + `py-8` come from `SettingsSection`.
+- Fields inside a column: `SETTINGS_FIELDS_STACK_CLASS` (`space-y-4`).
+- Checkbox/radio lists: `SETTINGS_OPTION_STACK_CLASS` (`space-y-1.5`).
+- Two-column areas: `SettingsTwoColumn` (`@3xl:grid-cols-2`); use `SettingsStackedField` inside cells (a `SettingsFieldRow` overflows half-width columns).
+- No elevated backgrounds, rounded rows, or hover fills without explicit UX value.

.agents/skills/settings-ui-patterns/references/search.md

@@ -5,9 +5,10 @@ Settings search uses an explicit registry; it does not scrape JSX.
 ## Required Integration
 
 - Add/update items in `packages/ui/src/lib/settings/search.ts`.
-- Add a matching `data-settings-item="..."` anchor to the rendered setting.
+- Add a matching `data-settings-item="..."` anchor to the rendered setting — shared primitives take it via their `settingsItem` prop.
 - Use localized labels/descriptions from every `packages/ui/src/lib/i18n/messages/*.settings.ts` dictionary.
-- For a new top-level page, add metadata in `packages/ui/src/lib/settings/metadata.ts` and searchable content unless the page is purely navigational.
+- For a new top-level page, add metadata in `packages/ui/src/lib/settings/metadata.ts` and searchable content unless the page is purely navigational; also extend `pageOrder`/nav icon in `SettingsView.tsx` and `MOBILE_SETTINGS_PAGES` in `MobileApp.tsx` when the page applies to mobile.
+- When a control moves between pages (e.g. into General), update the registry item's `page` — item `id`s stay stable even if they carry the old page prefix.
 
 ## Registry Rules
 

.agents/skills/theme-system/SKILL.md

@@ -10,6 +10,7 @@ description: Use when creating or modifying OpenChamber UI components, styling,
 - Use semantic OpenChamber theme tokens; never hardcode hex colors or generic Tailwind palette colors.
 - Use shared UI primitives before introducing feature-local controls.
 - Use the shared `Button`; do not create button wrappers such as `ButtonSmall` or `ButtonLarge`.
+- Every dropdown-style value-picker trigger (shows current value, opens a picker) takes its chrome from `dropdownTriggerVariants` in `packages/ui/src/components/ui/dropdown-trigger.ts` (sizes: `sm` dense h-6, `default` forms h-8; native `SelectTrigger` consumes it). Call sites add layout classes only (width/truncation) — never re-declare border/radius/bg/hover. Deliberately chrome-less pickers (chat composer, headers) are the only exception.
 - Use the sprite-based `Icon`; never import icons directly from `@remixicon/react`.
 - Apply hover tokens only to interactive elements.
 - Use status colors only for actual status/feedback.