Modes
Accessible themes respecting user preference
The system has one theme with two modes, light and dark. Each colour token has a value for each mode, so an application that uses the tokens can switch between them.
The Theme and ThemeSwitcher components use the word 'theme' for the mode.
User preference
Offering users the choice of light or dark mode honours their preference, which could be due to lighting conditions, accessibility needs or simply their preferred choice.
Light mode is the default in the CSS: the values on :root are the light values. Give users a way to switch, and to follow the mode set by their device.

Switch the mode
Add the Theme component to your application's top-level layout. It applies the user's saved choice, or the mode set by their device, when the page loads. ThemeSwitcher gives the user a menu of light, dark and system, and can go anywhere in the application, such as the footer.
<script>
import { Theme, ThemeSwitcher } from '@ldn-viz/ui';
</script>
<Theme />
…
<ThemeSwitcher />ThemeSwitcher needs Theme to be on the page.
Dark mode for part of a page
A .dark class applies dark mode to everything inside it, whatever the mode of the page. An element without a .dark ancestor follows the page.
.text-class {
color: var(--color-text);
}<div class="dark bg-color-canvas">
<p class="text-color-text">I'm in dark mode, because my parent has the dark class.</p>
</div>
<div class="bg-color-canvas">
<p class="text-color-text">I'm in light mode, unless an ancestor has the dark class.</p>
</div>I'm in dark mode, because my parent has the dark class.
I'm in light mode, unless an ancestor has the dark class.
There is no light class, so a part of a page can't be kept in light mode while the page is dark.
The header, sidebar and footer
Header, Sidebar and Footer are in dark mode by default. Set theme="light" on them to follow the page's mode instead, as the sidebar of this documentation does.
Inverse colours
Content on a background of the opposite lightness, such as a light panel in dark mode, uses the inverse colour tokens, such as --color-inverse-text on --color-inverse-surface. Design tokens describes the inverse variant.
Colours outside the browser
In a medium that doesn't use CSS, such as a slide deck, use the resolved colour values from @ldn-viz/themes/colors.js. Everywhere else, use the tokens, so the colours change with the mode.