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 |
1---2name: desktop-ui-settings-layout3description: 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."4---56# Settings Layout (Desktop)78## Pick a structure that matches how many settings there are910| Setting count | Structure |11|---|---|12| Under ~15 total | Single scrollable page, grouped into labeled sections |13| ~15–40 | A settings-specific sidebar (categories: General, Appearance, Shortcuts, Advanced...) with one category shown at a time |14| 40+ | Sidebar categories plus a search bar at the top that can jump directly to any individual setting, highlighting it in place |1516Don'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.1718## Grouping and layout within a section1920- 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`).21- 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.22- 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.23- 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.2425## Search2627If 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.2829## Dangerous / advanced settings3031- 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.32- 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.3334## Accessibility & internationalization3536- 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`.37- 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.3839## Review format4041| Before | After | Why |42|---|---|---|43| 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 |44| "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 |45| 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 |
simply-ehis