Skip to main content

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 sets data-color-scheme on <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:

ConceptScopeHow it switches
Color schemeSystem-widedata-color-scheme="light|dark" on <html>. Semetrika ships this.
ThemeConsumer-wideA 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.