# Desktop UI Settings Layout

> Use whenever designing or reviewing a desktop app's settings/preferences screen. Depends on desktop-ui-foundations, desktop-ui-layout-navigation, and desktop-ui-text-inputs. Trigger on "settings page," "preferences," or "settings layout."

- Skill: `simply-ehis/desktop-ui-settings-layout` (Agent Skill)
- Install (CLI): `npx skillmds@latest add simply-ehis/desktop-ui-settings-layout`
- Raw SKILL.md: https://api.skillmd.com/api/skills/simply-ehis/desktop-ui-settings-layout/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Coding & Dev Tools
- Author: simply-ehis (https://skillmd.com/u/simply-ehis)
- Updated: 2026-09-22
- Page: https://skillmd.com/skills/simply-ehis/desktop-ui-settings-layout

---


# Settings Layout (Desktop)

## Pick a structure that matches how many settings there are

| Setting count | Structure |
|---|---|
| Under ~15 total | Single scrollable page, grouped into labeled sections |
| ~15–40 | A settings-specific sidebar (categories: General, Appearance, Shortcuts, Advanced...) with one category shown at a time |
| 40+ | Sidebar categories plus a search bar at the top that can jump directly to any individual setting, highlighting it in place |

Don't build a multi-category sidebar for a dozen settings — that's more navigation than the content needs and just adds clicks. Don't cram forty settings into one endless scroll either — grouping into categories is what makes a large settings surface scannable.

## Grouping and layout within a section

- Group related settings under a clear section heading, with tighter internal spacing between settings in the same group and a larger gap between groups (see the proximity principle in `desktop-ui-spacing-sizing`).
- Each setting row: label + brief description (if the setting isn't self-explanatory from its name alone) on the left, the control (toggle, select, input) aligned to the right — this is a strong, well-understood convention and there's little reason to deviate from it.
- Keep description text genuinely brief (one line, two at most) — a settings page is not the place for paragraphs of documentation; link out to real docs for anything that needs more explanation.
- Settings that take effect immediately (most toggles) shouldn't need a separate "Save" action; settings that require an app restart or a heavier operation to apply should say so explicitly next to the control, not silently.

## Search

If the settings surface is large enough to need search, the search should filter/highlight matching settings in place (jumping the view to the right category and scrolling to the match) rather than opening a separate flat search-results view that looks like a different screen.

## Dangerous / advanced settings

- Settings with real consequences (data deletion, resetting the app, disabling safety features) should be visually set apart — often literally in an "Advanced" or "Danger Zone" section at the bottom, with a distinguishing treatment (a subtle danger-colored border/heading) — see the color-system skill's `danger` role.
- Anything irreversible triggered from settings still needs a confirmation step (see `desktop-ui-surfaces-overlays`), even though it lives in a "boring" settings page rather than a headline action — settings pages are exactly where users click quickly without reading closely, precisely because most settings there are low-stakes.

## Accessibility & internationalization

- Every toggle, field, and control needs a programmatically-associated label, not just adjacent text — otherwise a screen reader can't announce what the control actually does. See `desktop-ui-accessibility-i18n`.
- Give setting labels and descriptions headroom for translated text — a settings row sized exactly to fit its English label is the first thing to break once translated.

## Review format

| Before | After | Why |
|---|---|---|
| 60 settings on one long undifferentiated scroll | Sidebar categories, with search that jumps to and highlights a matching setting | A single long scroll becomes unscannable well before 60 settings |
| "Reset all data" button styled identically to "Change theme" | "Reset all data" set apart in a distinguished danger section, with a confirmation dialog on click | Irreversible actions need to stand out from routine preference toggles, and still require confirmation |
| Setting requiring a restart applies silently with no indication | Control shows a small "Restart required" note next to it when changed | Users should know when a change hasn't actually taken effect yet |