Color modes One attribute switches between light and dark mode. Each token declares its light and dark values together. You do not need a second stylesheet, a .dark class, or a second copy of any value. How color modes work :root { color-scheme: light dark; --helix-color-background: light-dark(#fff, #0b0b0d); } Each token is written once, with its light and dark values in light-dark(). The color-scheme property alone decides which value applies. color-scheme inherits, so one property sets the mode for an element and everything inside it. A component that sets a color of its own for each mode uses light-dark() the same way. Set the mode <html data-color-mode="dark"> [data-color-mode="light"] and [data-color-mode="dark"] set color-scheme. Because color-scheme inherits, the attribute works on any element: <div data-color-mode="light"> <!-- A light preview inside a dark page. One attribute. --> </div> The theme builder uses the same attribute to show a component in light and dark mode side by side in one document. Follow the operating system When you do not set a mode, :root declares color-scheme: light dark, and the operating system decides the mode. This is the default, and it is usually the right choice. The token layer uses a prefers-color-scheme media query in one case. light-dark() chooses between two values. A value that has to be computed from the mode cannot use light-dark(), so a media query checks which mode is current. Toast uses the opposite mode Toast renders in the opposite mode to the page it is on. The base layer sets this with one rule: helix-toast:not([data-color-mode]) { color-scheme: var(--_helix-mode-inverted); } A toast sits over the page. The opposite mode sets it apart from the page without a border. To choose a toast's mode yourself, set data-color-mode on it. The rule applies only to a toast without that attribute. Colors in your own CSS Write your own colors with light-dark(). You do not need anything else: .callout { background: light-dark(#eef, #223); } The color then follows: The page's mode The mode of a subtree that sets its own The operating system, when nothing sets a mode Do not write a prefers-color-scheme query for it, and do not select on the data-color-mode attribute. Both stop working when a subtree sets its own mode, and this design exists to make that easy.