Color schemes
Semetrika ships exactly two color schemes: light (default) and dark. There is no high-contrast scheme, no per-section scheme, no brand-A / brand-B opposite-mode wiring. Two schemes, no more.
The mechanism
The active scheme is selected at page level via the data-color-scheme attribute on <html>. When the attribute is absent, the light defaults from :root apply.
<!-- Light (default) -->
<html>
<!-- ... -->
</html>
<!-- Forced light, explicit -->
<html data-color-scheme="light">
<!-- ... -->
</html>
<!-- Forced dark -->
<html data-color-scheme="dark">
<!-- ... -->
</html>
Under the hood, every scheme-aware semantic token has its light value on :root and a matching dark value in a single :root[data-color-scheme='dark'] override block:
:root {
--page-background-color: #ffffff;
}
:root[data-color-scheme='dark'] {
color-scheme: dark;
--page-background-color: #152235;
}
The color-scheme: dark declaration tells the browser to render its built-in widgets (form controls, scrollbars, default text color) appropriately for dark mode.
Only on <html>
The data-color-scheme attribute is recognized only on <html>. Setting it on <body>, on a <section>, or on an individual component has no effect - the CSS overrides are scoped to :root[data-color-scheme='dark'] and :root[data-color-scheme='light']. Per-component or per-section color schemes are not a feature of the design system.
If you need a section that renders dark-on-light when the rest of the page is light-on-dark, that is a scoped token override, not a color-scheme switch:
.invert-island {
--background-color-neutral: #1a1a1a;
--text-color-neutral: #f0f0f0;
}
This re-themes the section but leaves the page color scheme intact.
Consumer responsibility
Semetrika ships the CSS contract only. The following are the consumer's responsibility:
- The toggle UI. A button, a select, a system-preference auto-mode. Semetrika does not place a toggle for you.
- Persistence. Storing the user's choice (typically in
localStorage) and restoring it on subsequent visits. - No-FOUC head snippet. A small inline script in
<head>that reads the persisted value and setsdata-color-schemeon<html>before the page paints. This avoids the flash of incorrect theme that would otherwise happen between the initial paint and your toggle script running.
A minimal no-FOUC snippet looks like this:
<!doctype html>
<html lang="en">
<head>
<script>
(function () {
const stored = localStorage.getItem('color-scheme');
const initial = stored || (matchMedia('(prefers-color-scheme: dark)').matches ? 'dark' : 'light');
document.documentElement.setAttribute('data-color-scheme', initial);
})();
</script>
<link rel="stylesheet" href="semetrika.min.css" />
</head>
<body>
<button type="button" id="theme-toggle">Toggle theme</button>
<script>
document.querySelector('#theme-toggle').addEventListener('click', () => {
const next = document.documentElement.dataset.colorScheme === 'dark' ? 'light' : 'dark';
document.documentElement.dataset.colorScheme = next;
localStorage.setItem('color-scheme', next);
});
</script>
</body>
</html>
The script in <head> runs synchronously before the stylesheet loads, so the document's first paint is in the right scheme. The toggle script runs after page load.
Why two and only two
The dark scheme exists because user agents and operating systems expose a single binary preference (prefers-color-scheme: light / dark). Honoring that preference is an accessibility expectation.
Anything beyond those two - a high-contrast mode, a sepia mode, a brand-specific palette - is not a color-scheme switch. It is a theme, which is consumer-level CSS layered on top of Semetrika. The two concepts sit at different layers:
| Concept | Scope | How it switches |
|---|---|---|
| Color scheme | System-wide | data-color-scheme="light|dark" on <html>. Semetrika ships this. |
| Theme | Consumer-wide | A second stylesheet that overrides semantic tokens on :root. The consumer ships this. |
A consumer who wants three brand themes that each honor the OS dark mode writes three theme stylesheets, each with both :root and :root[data-color-scheme='dark'] blocks. Semetrika does not have a built-in slot for "third theme".
See Tokens for the override mechanism and Extending for how consumer themes attach. To produce a fresh palette from your brand hex codes, use the Palette generator - it emits the --color-*-N declarations both schemes feed off.