/* 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 in `index.html`.
It exposes a semantic fg/bg variable contract whose defaults are CSS SYSTEM
COLORS, so a theme-less drop-in still looks right in both light and dark mode.
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 easily 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 */
/* Notification status colours (notifications.css). Names declared here so a
theme-less drop-in still shows coloured notices; Part 2 tunes them to the
theme hue. light-dark() adapts each to the active color-scheme. */
--notice-information: light-dark(oklch(45% 0.13 250), oklch(80% 0.12 233)); /* blue */
--notice-warning: light-dark(oklch(62% 0.15 65), oklch(78% 0.14 70)); /* orange */
--notice-error: light-dark(oklch(55% 0.20 27), oklch(70% 0.18 27)); /* red */
--notice-success: light-dark(oklch(52% 0.15 150), oklch(75% 0.18 150)); /* green */
/* 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