System preference, manual toggle, tokens for both themes, no flash on load.
Spec — Dark mode
Status: draft · Created: 2026-11-10
1. Context and goal
Users read the interface in a light or dark theme that follows their system or their own choice, without a flash of the wrong theme.
2. Functional requirements (EARS)
- FR-1: WHEN the user has made no choice, THE SYSTEM SHALL follow the
prefers-color-schemesetting of the system and switch within 1 second when it changes. - FR-2: WHEN the user picks light, dark or system in the theme toggle, THE SYSTEM SHALL apply it at once and remember it across sessions on that device.
- FR-3: THE SYSTEM SHALL define every color as a design token with a value for each theme, with no hard-coded colors in components, checked by a lint rule.
- FR-4: THE SYSTEM SHALL keep text contrast at a ratio of at least 4.5:1 in both themes.
- FR-5: WHEN a page loads, THE SYSTEM SHALL apply the chosen theme before the first paint, so no frame shows the other theme.
3. Out of scope
- Themes other than light and dark.
- Per-page theme overrides.