Settings

Settings is a system window opened by Cmd-, (macOS convention), by typing “settings” into Spotlight, or programmatically via openWindow({ kind: "system", systemId: "settings" }). It reads theme.customizable and renders the appropriate editor per field kind.

Press Cmd-, to open Settings and tweak the theme live Open in new tab ↗

Import

import { Settings } from "@react-ui-os/desktop";

In normal use you never instantiate <Settings> directly. The library registers it as a system window automatically; opening it goes through the window manager.

How it works

The active theme declares a customizable map: keys are dotted paths into the theme (e.g. "palette.accent"), values describe the field kind.
Opening Settings groups entries by section into a left sidebar; selecting a section renders its fields as grouped rows in the content pane.
Edits write to the storage adapter under settings:<themeId>.
The effective-theme overlay applies the change immediately; the rest of the desktop reads tokens via useTheme() and re-renders.
Reload restores the user’s overrides via the same storage adapter.

Layout

The window follows the pattern modern settings apps converged on (macOS Ventura System Settings, Windows 11 Settings, GNOME Settings): a category sidebar on the left and a content pane of grouped rows on the right. Each row puts the field label and description on the left and its control on the right; sliders show their value inline, and wide controls (the wallpaper picker) stack beneath the label. The active category, the card surface, the row separators, and the hover highlights all read from palette tokens, so the window looks right on light and dark themes.

Supported field kinds

Kind	Editor
`color-from-palette`	A row of color swatches. Selected swatch wears an outline.
`image-pick`	A thumbnail grid (stacks beneath the label). Each option has an `src` and a `label`.
`range`	A slider with `min` / `max` / `step` and a tabular-numeric readout (optional `unit`).
`select`	A segmented control where each `option` has a `value` and a `label`.
`toggle`	An iOS-style switch with a 36 × 20 rounded pill and a sliding thumb.

Reset buttons

The panel surfaces two reset buttons contextually:

Per-field Reset appears next to the control of any field whose value is currently overridden.
Reset all appears at the bottom of the sidebar when at least one override exists.

Both write through useSettings() so any subscriber (the desktop itself, the dock, a custom inspector) re-renders.

Programmatic access

import { useSettings } from "@react-ui-os/desktop";

function MyCustomToolbar() {
  const { schema, prefs, setPref, resetAll } = useSettings();
  // …
}

See the useSettings reference for the full hook surface.

Accessibility

The window inherits the standard role="region" aria-label="Settings window".
Toggle controls use role="switch" aria-checked.
Color swatches expose the hex string via aria-label.