Settings UI Patterns

Required Companion Skills

• Load theme-system for colors, buttons, icons, and visual states.
• Load openchamber-ui-guidance for depth, surfaces, layout stability, sizing and composition.
• Load locale-ui-patterns for every visible string, tooltip, placeholder, and accessible label.
• Load ui-api-decoupling when a setting reads/writes runtime data or adds a capability, and write the surface list from its Name The Surfaces Before Editing step before adding or moving a settings page: a page that exists on desktop and is unreachable on a phone is the common way this goes wrong.

When examples conflict, shared component/theme and localization contracts win. Stop on unresolved material conflicts.

Canonical Direction

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 boxed backgrounds or row chrome. Card grids are the one exception, for browse pages (see references/layout.md).
• Secondary helper text is hidden behind an info icon (info prop) by default; 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.

Keep A Page From Turning Into A List

Pages grow one control at a time, and each addition looks fine alone; the mess shows up as a whole. When adding to a page, read the page, not only the spot you add to:

• A section holds one topic a user would name ("Terminal", "Sending"). A new setting goes into the section it belongs to, or starts its own; never append it to whatever section is last or nearest.
• One row kind per run: field rows together, checkboxes together. A field row (label + select, stepper, chips) between checkboxes is the clearest sign of a page that needs regrouping.
• Same shape for the same kind of choice: a short enum is chips in a field row everywhere, never radios on one page and chips on the next.
• A text line belongs to one option and sits under its label (description, footer), never loose between two rows.
• When a page passes about four sections or a scroll of mixed topics, split it into tabs (references/layout.md, Pages With Tabs) rather than adding more.

Load References By Task

Load each reference whose task branch applies; reference loading is complete when layout, control, and search implications are each classified.

Quick Primitive Selection

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 goes behind the info icon via the info prop by default.
• An info hint is one or two short sentences that add what the label or summary does not say. It names no list of every action and carries no caveat that stopped being true (for example "applies after OpenCode restarts" for tools that now apply live).
• When labels alone cannot explain the differences, consequences, or conditions needed to choose a setting, use a title, a visible description, then checkbox or radio controls. Option lists whose labels already read as complete choices (large-text paste modes, send shortcut) keep the explanation behind info even when it carries an exception. Having multiple options or a group title alone does not require a description; see references/controls.md for composition.
• 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 (primitives accept settingsItem);
• localized title/description keys;
• availability matching actual render conditions;
• 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.

Completion Criteria

• Built from shared primitives; no ad-hoc page/section/row markup.
• Description placement follows the policy above; warnings/syntax/status remain 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.