/* MARK: COLOR-SCHEME — light/dark + system-adaptation GOVERNOR (modular color system, Part 1 of 2)
Dependency-free, copy/paste-able, drop-in-anywhere. Link this ONE file in
and — with NO other CSS/JS — the page renders correctly in light,
dark, high-contrast, forced-colors, and reduced-transparency, driven by the
user's system/browser preferences. No id/class/data-* hooks; the only HTML
touchpoints are the and the .
It exposes a semantic fg/bg variable contract whose defaults are CSS SYSTEM
COLORS, so a theme-less drop-in still looks right. Part 2 (color-theme-*.css)
REASSIGNS the SAME variable names with a palette via light-dark(); Part 1 is
palette-independent.
@layer order (Rule 29): `color-scheme` (this file) is declared BEFORE
`color-theme`, so a later color-theme-*.css layer (Part 2) overrides these
system-color defaults, and any UNLAYERED author rule overrides both. Future
developers can therefore override what this system does by default with no
specificity fight and no hooks.
NOTE (autocss migration, a LATER step — not this file's concern): while the
existing themes.css is still present and UNLAYERED, its palette/`color-scheme`
win over this layer, so adding this file does not change the app's look yet.
The themes.css split + the index.html control + the JS persistence are
separate steps.
*/
@layer color-scheme, color-theme;
@layer color-scheme {
/* MARK: GOVERNOR
Rule 19: the SYSTEM drives the scheme by default. Both light-dark() and CSS
system colors key off `color-scheme`, so this single declaration makes the
whole page follow the OS light/dark setting. Do NOT hard-default to dark.
*/
:root {
color-scheme: light dark;
}
/* MARK: COLOR-SCHEME CONTROL — absolute Light / Dark / System via pure :has()
A three-state radio group (name="color-scheme") forces an ABSOLUTE scheme.
The System radio matches NO override rule, so it falls through to `light
dark` (OS-follow). No media-query flip, no matchMedia, no compare logic.
`value` is a standard attribute (same as the nav radios), not data-*.
DOM-AGNOSTIC: keyed off the GROUP (`input[name="color-scheme"]`) anchored at
`:root`, NOT a wrapper like `header`, so the control can live anywhere in
the page (the unique `name` is the scope). */
:root:has(input[name="color-scheme"][value="light"]:checked) { color-scheme: light; }
:root:has(input[name="color-scheme"][value="dark"]:checked) { color-scheme: dark; }
/* System checked -> no rule matches -> stays `light dark` (OS-follow). */
/* MARK: VARIABLE CONTRACT — semantic fg/bg, each defaulting to a CSS SYSTEM
COLOR (CSS Color 4 system keywords). They auto-adapt to the active
color-scheme AND to forced-colors, so a theme-less drop-in + high-contrast +
forced-colors all work for free. Part 2 reassigns these SAME names via
light-dark() in the `color-theme` layer.
System-color keywords used (most devs don't know these exist — documented):
Canvas = default page background
CanvasText = default text on Canvas
LinkText = unvisited link text
ActiveText = link text while being activated (hover/active)
AccentColor = the user/OS accent color (pairs with AccentColorText)
GrayText = disabled / dimmed text
ButtonFace = default push-button / control surface
Field = text input / textarea surface
Highlight = selection / highlighted surface (pairs with HighlightText)
*/
:root {
/* Foreground */
--fg: CanvasText; /* body text on Canvas */
--fg-link: var(--fg-accent); /* links share the accent hue */
--fg-link-hover: ActiveText; /* link hover/active */
--fg-accent: AccentColor; /* accent / emphasis hue */
--fg-emphasis: var(--fg-accent); /* emphasis === accent hue */
--fg-disabled: GrayText; /* disabled text */
--fg-muted: GrayText; /* secondary / muted text */
/* Background (mirrors foreground) */
--bg: Canvas; /* page background */
--bg-link: Canvas; /* surface behind links = the canvas */
--bg-link-hover: Canvas; /* (Part 2 may add a hover tint) */
--bg-accent: AccentColor; /* accent surface (alt: Highlight) */
--bg-emphasis: var(--bg-accent); /* emphasis surface === accent surface */
--bg-selected: rgb(from AccentColor r g b / 5%); /* selected/checked surface = 5% accent */
--bg-hover: rgb(from AccentColor r g b / 5%); /* hover surface = 5% accent */
--bg-disabled: ButtonFace; /* disabled control surface (alt: Field) */
--bg-muted: ButtonFace; /* muted panel surface */
--bg-panel: rgb(from currentColor r g b / 5%); /* region surface (header/main/aside/footer) = 5% of text; Part 2 overrides with % accent */
--bg-grd: linear-gradient(180deg, rgb(from currentColor r g b / 8%) 0%, rgb(from currentColor r g b / 2%) 100%); /* app-container backdrop = currentColor transparency stops; Part 2 overrides with accent-based stops */
/* Focus ring — same accent hue as --fg-accent so the keyboard-focus
indicator always tracks the theme accent. Forced-colors swaps it to
Highlight (see the forced-colors block). Part 2 derives it from the SAME
single theme hex as the accent.
NOTE: only the COLOR token is built in Part 1. The label-level
:focus-visible PAINT, the A/B primitive choice, and making the
state-machine inputs keyboard-focusable are DEFERRED — see the foot of
this file. */
--outline: AccentColor;
}
/* MARK: FOUNDATION — make a bare drop-in visible, sourced from the contract.
(In autocss these live in the low-priority `color-scheme` layer, so the
still-unlayered themes.css palette wins = visual parity; standalone, with no
theme, these paint the system-color defaults.)
*/
:root,
body {
background-color: var(--bg);
color: var(--fg);
}
body {
accent-color: var(--fg-accent); /* native checkbox/radio/range/progress tint */
}
:any-link {
color: var(--fg-link);
}
:any-link:hover {
color: var(--fg-link-hover);
}
::selection {
background-color: var(--bg-accent);
color: var(--bg); /* Part 2 supplies an explicit on-accent text color */
}
/* Region surfaces — a subtle tint so a theme-less drop-in still reads as
distinct panels. Default = 5% of the text color (currentColor); Part 2
overrides --bg-panel with a % of the accent hue (from the theme file's own
base color). nav is intentionally excluded (it stays transparent). */
header,
main,
aside,
footer {
background-color: var(--bg-panel);
}
/* app-container backdrop gradient — visible through the grid gaps + the
transparent nav. Default = currentColor transparency stops so a theme-less
drop-in still has depth; Part 2 overrides --bg-grd with accent-based stops. */
app-container {
background: var(--bg-grd);
}
/* COLOR-SCHEME CONTROL paint — this governor owns ITS OWN control's selected/
hover surfaces (scoped to input[name="color-scheme"], DOM-agnostic so the
control can live anywhere). It does NOT paint other app controls (nav, data
rows, buttons) — those are consumer rules in layout.css/forms.css reading the
same --bg-hover/--bg-selected tokens. Glyphs + text live in the markup. */
label:has(> input[name="color-scheme"]):hover {
background-color: var(--bg-hover);
color: var(--fg-emphasis);
}
label:has(> input[name="color-scheme"]:checked) {
background-color: var(--bg-selected);
color: var(--fg-emphasis);
}
/* MARK: SYSTEM PREFERENCE DETECTION (all four) */
/* forced-colors (e.g. Windows High Contrast): the OS forces its own palette.
We already use system-color keywords (which the forced palette maps), so we
only re-pin the accent/outline to forced-palette colors. NEVER override with
hard colors; keep non-color cues intact. */
@media (forced-colors: active) {
:root {
--fg-accent: Highlight;
--bg-accent: Highlight;
--outline: Highlight;
}
}
/* prefers-contrast: more -> snap to pure system colors, stop dimming. */
@media (prefers-contrast: more) {
:root {
--fg: CanvasText;
--bg: Canvas;
--fg-muted: CanvasText; /* muted text no longer dimmed */
--fg-accent: Highlight;
--outline: Highlight;
}
}
/* prefers-contrast: less -> soften. */
@media (prefers-contrast: less) {
:root {
--fg-muted: GrayText;
}
}
/* prefers-reduced-transparency: collapse any alpha/translucency to solid.
Part-1 defaults are already solid system colors; this block is where Part-2
palettes that carry alpha must collapse to their solid equivalents. */
@media (prefers-reduced-transparency: reduce) {
:root {
--bg: Canvas;
--fg: CanvasText;
--bg-selected: Highlight; /* collapse the 5% accent tint -> solid selection */
--bg-hover: ButtonFace; /* collapse the 5% accent tint -> solid control */
--bg-panel: ButtonFace; /* collapse the 5% panel tint -> solid panel */
}
}
}
/* ============================================================================
DEFERRED — user-postponed 2026-06-15; documented here so it can be resumed
with full context. NOT built in this file yet:
FOCUS / KEYBOARD-NAVIGATION INDICATOR (WCAG 2.4.7 & 2.4.11). The accent-hued
color token `--outline` (above) is the only Part-1 piece in place. Still to do:
(1) LABEL-level paint: `label:has(> input:focus-visible) { ...var(--outline) }`
— keyboard-only (nothing on mouse :focus). A