Docs Components
ThemeToggleexperimental
Sun or moon: paper or sumi. Two themes, nothing else — the app remembers your choice, and the very first visit follows your system preference.
Mechanism
A pre-paint inline script in the root layout resolves the effective theme before first paint (stored 'atom-theme' value, else OS preference) so there is never a theme flash. The toggle itself renders as an icon SegmentedControl (aria-pressed buttons in a role=group labeled 'Color theme') and applies the choice by setting or deleting data-theme='dark' on the document element — sumi overrides in tokens.css key off that attribute.
Guidelines
- must-notNever apply a default mode before the stored preference has been read: the component initializes to null and applies nothing until localStorage resolves. Applying a placeholder briefly stamps the wrong theme and overwrites the stored key — which races the pre-paint script of any same-origin iframe (this shipped as a real bug in the storybook breakpoint frames).
- mustTwo modes only — light (paper) and dark (sumi). No third 'system' segment: OS preference seeds the first visit, then the explicit choice wins everywhere.
- mustTheme state lives in one place: data-theme on the root element plus the 'atom-theme' localStorage key. Components never read or branch on the theme — every themed value arrives through token variables.