In a recruiting app with a dark-mode toggle, how should the in-app choice relate to the operating system's appearance preference?

## Two sources of truth A recruiter using an applicant-tracking app has two places to express an appearance preference: - the **operating system's appearance preference** — light, dark, or switching automatically by time of day — which every app on the device can read; - the **in-app dark-mode toggle**, which lets them choose differently for this one app, perhaps because they present candidate pipelines on a meeting-room screen where light mode reads better. The design question is how the two interact. The widely used answer is: **the system preference is the default, and an explicit in-app choice overrides it.** ## Why three states and not two | Control | States | What goes wrong | |---|---|---| | Two-state toggle | Light, dark | No way to return to following the device; the first flip freezes the choice forever | | Three-state choice | System, light, dark | Nothing — each intent is expressible | With a two-state toggle, the initial position is usually copied from the device. The moment the recruiter flips it, the app stops tracking the device. If their device switches to dark every evening, the app no longer follows, and there is no control that means *go back to following my device*. A **system** option is that control. The control can still look like a toggle in compact places — a quick switch in the header — as long as the full three-way choice is reachable in settings. ## How each state behaves 1. **System** — the app resolves to whatever the device currently prefers and **updates live** when the device changes, including automatic evening switching. 2. **Light** — the app stays light regardless of the device preference. 3. **Dark** — the app stays dark regardless of the device preference. The resolved mode then selects which value set the semantic tokens use. The components do not care where the decision came from. ## Contrast is a separate axis Operating systems also expose **contrast settings**, and they should not be folded into the light-dark choice: - **An increase-contrast setting** asks apps for stronger contrast. It combines with either mode, so a system that supports it needs a light high-contrast and a dark high-contrast value set, and the app should honour it whichever appearance is chosen. - **A color-replacement contrast mode**, offered by some platforms, replaces the app's colors with a small palette the user chose. That is an accessibility setting, not a preference to override: the in-app toggle has no business fighting it, and components must stay usable when their own colors are replaced. So the in-app choice overrides the *appearance* preference, but it does not override the user's *accessibility* settings. ## Scope and edge cases - **Per user, not per device, when accounts exist.** A recruiter who signs in on a laptop and a tablet usually expects the same explicit choice on both, while *system* follows each device. - **Shared screens.** A meeting-room display may want its own setting; that is a reason the in-app override exists at all. - **Embedded surfaces.** An interview-scheduling widget embedded in a client's careers page should follow the host's mode or the device, not the recruiter's personal choice. How the choice is stored, and how the app applies it on load without briefly showing the wrong mode, belong to the theme-application mechanics; the design-system decision is the three-state model and the precedence rules above.