feat(theme): Light/Dark/System, reduced motion, and one radius scale

The theme foundation DESIGN.md requires (ADR 0060):

- A design token may carry a `dark` value and a `reduced` value. The
  token stylesheet selects them in CSS alone: dark under
  prefers-color-scheme unless the host chose light, or when it chose
  dark; motion durations zero under prefers-reduced-motion unless it
  allowed motion, or when it chose reduce. `color-scheme` travels with
  the tokens. System is live, an explicit choice wins, and every module
  root follows through custom-property inheritance, with no module
  contract change.
- @ekklesia/design-tokens adds a small appearance API: system/light/dark
  and system/reduce/allow, parsers for untrusted stored values,
  resolvers, and a controller that applies the attributes immediately.
  The shell applies it before React renders. That is the hook the
  account preferences work will feed; nothing is persisted. The
  Dashboard page declares `color-scheme: light dark` so a dark system
  never flashes white. Displays stay light.
- A designed dark theme: teal-tinted charcoal, never pure black or
  white, the same teal accent.
- WCAG AA contrast is tested for 41 element pairings in both schemes.
  Two light pairings failed and are fixed visibly: text.muted darkens,
  and form controls get a new border.control (3:1).
  background.placeholder keeps skeletons visible in dark.
- Motion tokens (duration-short, duration-ambient) replace literal
  durations and every per-element reduced-motion rule. radius.scale
  multiplies sm/md/lg, unchanged at its default of 1.
- The sign-in card and module loading/error text move from literal
  colours to tokens. Guards keep raw colours and literal radii out of
  Dashboard product source and @ekklesia/ui.
- Fixes ConfirmationDialog's phrase input, which used a class that
  does not exist (`ek-input`) and so was unstyled.

Co-Authored-By: Claude Opus 5.5 <[email protected]>

packages/design-tokens/src/appearance.ts

@@ -0,0 +1,162 @@
+import {
+  DESIGN_TOKEN_APPEARANCE_ATTRIBUTE,
+  DESIGN_TOKEN_MOTION_ATTRIBUTE,
+  type DesignTokenColorScheme,
+} from "./token.js";
+
+/**
+ * A person's appearance preference (DESIGN.md §3.2, ADR 0060). `system` follows the operating
+ * system's light or dark setting, live; it is the default.
+ */
+export const EKKLESIA_APPEARANCES = Object.freeze(["system", "light", "dark"] as const);
+export type EkklesiaAppearance = (typeof EKKLESIA_APPEARANCES)[number];
+
+/**
+ * A person's motion preference (DESIGN.md §3.3, ADR 0060). `system` follows
+ * `prefers-reduced-motion`; `reduce` always reduces; `allow` keeps the platform's subtle motion even
+ * when the system asks for less.
+ */
+export const EKKLESIA_MOTION_PREFERENCES = Object.freeze(["system", "reduce", "allow"] as const);
+export type EkklesiaMotionPreference = (typeof EKKLESIA_MOTION_PREFERENCES)[number];
+
+export const EKKLESIA_DARK_SCHEME_QUERY = "(prefers-color-scheme: dark)";
+export const EKKLESIA_REDUCED_MOTION_QUERY = "(prefers-reduced-motion: reduce)";
+
+/** Reads an untrusted stored or received value; anything unrecognised is the default, `system`. */
+export function parseEkklesiaAppearance(value: unknown): EkklesiaAppearance {
+  return EKKLESIA_APPEARANCES.includes(value as EkklesiaAppearance)
+    ? (value as EkklesiaAppearance)
+    : "system";
+}
+
+/** Reads an untrusted stored or received value; anything unrecognised is the default, `system`. */
+export function parseEkklesiaMotionPreference(value: unknown): EkklesiaMotionPreference {
+  return EKKLESIA_MOTION_PREFERENCES.includes(value as EkklesiaMotionPreference)
+    ? (value as EkklesiaMotionPreference)
+    : "system";
+}
+
+/** The scheme an appearance shows, given whether the system currently prefers dark. */
+export function resolveEkklesiaColorScheme(
+  appearance: EkklesiaAppearance,
+  systemPrefersDark: boolean,
+): DesignTokenColorScheme {
+  if (appearance === "system") {
+    return systemPrefersDark ? "dark" : "light";
+  }
+  return appearance;
+}
+
+/** Whether motion is reduced, given the preference and whether the system currently asks for less. */
+export function resolveEkklesiaReducedMotion(
+  preference: EkklesiaMotionPreference,
+  systemPrefersReduced: boolean,
+): boolean {
+  return preference === "system" ? systemPrefersReduced : preference === "reduce";
+}
+
+/** The element a host themes: its document's root element, or an isolated root's host element. */
+export interface EkklesiaThemeTarget {
+  setAttribute(name: string, value: string): void;
+}
+
+/** A media query list, structurally: what `window.matchMedia` returns. */
+export interface EkklesiaMediaQueryList {
+  readonly matches: boolean;
+  addEventListener(type: "change", listener: () => void): void;
+  removeEventListener(type: "change", listener: () => void): void;
+}
+
+export interface EkklesiaThemeControllerOptions {
+  readonly target: EkklesiaThemeTarget;
+  /** The browser's `matchMedia`, handed in by the host. Without one, the system is taken to prefer
+   * light and full motion. */
+  readonly matchMedia?: (query: string) => EkklesiaMediaQueryList;
+  readonly appearance?: EkklesiaAppearance;
+  readonly motion?: EkklesiaMotionPreference;
+}
+
+/**
+ * The host's handle on its theme (ADR 0060).
+ *
+ * The **stylesheet** does the work: installed tokens resolve light, dark, and reduced motion in CSS
+ * from the system's media features and two attributes on the theme root, so a change of OS setting
+ * restyles everything at once — every isolated module root included, since custom properties and
+ * `color-scheme` inherit — with no script and no reload. This controller only sets those attributes,
+ * and answers what is currently in effect for code that needs to know.
+ */
+export interface EkklesiaThemeController {
+  appearance(): EkklesiaAppearance;
+  motion(): EkklesiaMotionPreference;
+  /** The scheme on screen now: the explicit appearance, or the system's while it is `system`. */
+  colorScheme(): DesignTokenColorScheme;
+  /** Whether motion is reduced now. */
+  reducedMotion(): boolean;
+  setAppearance(appearance: EkklesiaAppearance): void;
+  setMotion(motion: EkklesiaMotionPreference): void;
+  /** Notifies after a preference changes, and after the system's setting changes. */
+  subscribe(listener: () => void): () => void;
+}
+
+/**
+ * Applies a theme to its target **immediately** — before anything renders, which is what keeps a
+ * persisted explicit choice from flashing the other scheme first — and returns its controller.
+ * Preferences are taken through {@link parseEkklesiaAppearance} and
+ * {@link parseEkklesiaMotionPreference}, so an untrusted stored value can be passed straight in.
+ */
+export function createEkklesiaThemeController(
+  options: EkklesiaThemeControllerOptions,
+): EkklesiaThemeController {
+  let appearance = parseEkklesiaAppearance(options.appearance);
+  let motion = parseEkklesiaMotionPreference(options.motion);
+  const darkQuery = options.matchMedia?.(EKKLESIA_DARK_SCHEME_QUERY);
+  const motionQuery = options.matchMedia?.(EKKLESIA_REDUCED_MOTION_QUERY);
+  const listeners = new Set<() => void>();
+  const notify = (): void => {
+    for (const listener of [...listeners]) {
+      listener();
+    }
+  };
+
+  options.target.setAttribute(DESIGN_TOKEN_APPEARANCE_ATTRIBUTE, appearance);
+  options.target.setAttribute(DESIGN_TOKEN_MOTION_ATTRIBUTE, motion);
+
+  return {
+    appearance: () => appearance,
+    colorScheme: () => resolveEkklesiaColorScheme(appearance, darkQuery?.matches ?? false),
+    motion: () => motion,
+    reducedMotion: () => resolveEkklesiaReducedMotion(motion, motionQuery?.matches ?? false),
+    setAppearance(next) {
+      const parsed = parseEkklesiaAppearance(next);
+      if (parsed === appearance) {
+        return;
+      }
+      appearance = parsed;
+      options.target.setAttribute(DESIGN_TOKEN_APPEARANCE_ATTRIBUTE, appearance);
+      notify();
+    },
+    setMotion(next) {
+      const parsed = parseEkklesiaMotionPreference(next);
+      if (parsed === motion) {
+        return;
+      }
+      motion = parsed;
+      options.target.setAttribute(DESIGN_TOKEN_MOTION_ATTRIBUTE, motion);
+      notify();
+    },
+    subscribe(listener) {
+      if (listeners.size === 0) {
+        darkQuery?.addEventListener("change", notify);
+        motionQuery?.addEventListener("change", notify);
+      }
+      listeners.add(listener);
+      return () => {
+        listeners.delete(listener);
+        if (listeners.size === 0) {
+          darkQuery?.removeEventListener("change", notify);
+          motionQuery?.removeEventListener("change", notify);
+        }
+      };
+    },
+  };
+}

packages/design-tokens/src/index.ts

@@ -1,3 +1,4 @@
+export * from "./appearance.js";
 export * from "./install.js";
 export * from "./registry.js";
 export * from "./token.js";

packages/design-tokens/src/registry.ts

@@ -12,9 +12,12 @@ import {
  * every consumer's meaning changing with it: `background.raised` stays "the surface that sits above
  * an ordinary surface" whatever a church's brand makes it.
  *
- * The default values are Ekklesia's calm, teal-accented light theme. They remain semantic defaults —
- * a deployment overrides them by installing different values at its host root, and this pass
- * deliberately ships no theme editor, brand builder, or dark-mode variant to do that with.
+ * The default values are Ekklesia's calm, teal-accented light theme, and each colour carries a
+ * `dark` value: a designed dark theme of the same product — teal-tinted charcoal rather than black,
+ * text that is never pure white, an accent that stays the same teal rather than glowing — selected by
+ * `prefers-color-scheme` or by the host's explicit appearance (ADR 0060). Every text and focus
+ * pairing a component uses meets WCAG 2.2 AA in both, and `tests/contrast.test.ts` holds that.
+ * There is still no theme editor or brand builder; a deployment overrides values at its host root.
  *
  * ## Status is never colour alone
  *
@@ -32,6 +35,7 @@ const declarations = [
     label: "Page background",
     name: "background.page",
     value: "#f3f7f6",
+    dark: "#0e1615",
   },
   {
     description:
@@ -39,30 +43,43 @@ const declarations = [
     label: "Canvas background",
     name: "background.canvas",
     value: "#f8faf9",
+    dark: "#121b1a",
   },
   {
     description: "An ordinary panel, card, table, or dialog body sitting on the page.",
     label: "Surface background",
     name: "background.surface",
     value: "#ffffff",
+    dark: "#162120",
   },
   {
     description: "A surface deliberately lifted above an ordinary surface, such as a popover.",
     label: "Raised surface background",
     name: "background.raised",
     value: "#ffffff",
+    dark: "#1c2826",
   },
   {
     description: "The scrim drawn behind a modal dialog to separate it from the page beneath.",
     label: "Overlay background",
     name: "background.overlay",
     value: "rgba(23, 23, 21, 0.55)",
+    dark: "rgba(3, 8, 7, 0.68)",
   },
   {
     description: "A recessed area such as a text input, a code block, or a well.",
     label: "Inset background",
     name: "background.inset",
     value: "#edf3f1",
+    dark: "#0b1211",
+  },
+  {
+    description:
+      "The shape of content that is still loading — a skeleton placeholder. Visibly distinct from the page and from a surface in both schemes.",
+    label: "Placeholder background",
+    name: "background.placeholder",
+    value: "#e3ebe9",
+    dark: "#243230",
   },
 
   // ---------------------------------------------------------------------------------------------
@@ -73,42 +90,49 @@ const declarations = [
     label: "Primary text",
     name: "text.primary",
     value: "#182321",
+    dark: "#e4edeb",
   },
   {
     description: "Supporting text that is still content: captions, secondary columns, help text.",
     label: "Secondary text",
     name: "text.secondary",
     value: "#4f5f5b",
+    dark: "#b4c3bf",
   },
   {
     description: "De-emphasised text such as placeholders, timestamps, and disabled labels.",
     label: "Muted text",
     name: "text.muted",
-    value: "#6c7b77",
+    value: "#5d6d69",
+    dark: "#93a5a0",
   },
   {
     description: "Text drawn on a strongly coloured background, such as a primary button.",
     label: "Inverse text",
     name: "text.inverse",
     value: "#ffffff",
+    dark: "#0e1615",
   },
   {
     description: "Text reporting a successful outcome, paired with the success symbol.",
     label: "Success text",
     name: "text.success",
     value: "#166534",
+    dark: "#86d9a7",
   },
   {
     description: "Text reporting a caution or a degraded state, paired with the warning symbol.",
     label: "Warning text",
     name: "text.warning",
     value: "#854d0e",
+    dark: "#e9c37a",
   },
   {
     description: "Text reporting a failure or a destructive consequence, paired with its symbol.",
     label: "Danger text",
     name: "text.danger",
     value: "#9f1239",
+    dark: "#f5a6b6",
   },
 
   // ---------------------------------------------------------------------------------------------
@@ -119,42 +143,49 @@ const declarations = [
     label: "Accent",
     name: "accent.base",
     value: "#4fb3a8",
+    dark: "#5bbcb1",
   },
   {
     description: "The accent background under a hovered primary action.",
     label: "Accent hover",
     name: "accent.hover",
     value: "#5ab9ae",
+    dark: "#6cc5bb",
   },
   {
     description: "The accent background while a primary action is pressed.",
     label: "Accent active",
     name: "accent.active",
     value: "#45a59b",
+    dark: "#4ea99f",
   },
   {
     description: "A deeper accent for pressed primary actions and high-emphasis emphasis.",
     label: "Strong accent",
     name: "accent.strong",
     value: "#246b64",
+    dark: "#82d3c8",
   },
   {
     description: "A faint accent wash for selected rows and subtle accent backgrounds.",
     label: "Subtle accent",
     name: "accent.subtle",
     value: "#def2ef",
+    dark: "#163330",
   },
   {
     description: "Foreground drawn on top of the accent background.",
     label: "Accent foreground",
     name: "accent.foreground",
     value: "#102a27",
+    dark: "#04201d",
   },
   {
     description: "The focus ring colour. Never the only signal that something has focus.",
     label: "Focus ring",
     name: "accent.focus",
     value: "#287a72",
+    dark: "#7fd4c9",
   },
 
   // ---------------------------------------------------------------------------------------------
@@ -165,18 +196,29 @@ const declarations = [
     label: "Border",
     name: "border.base",
     value: "#d3dedb",
+    dark: "#2b3836",
   },
   {
     description: "A heavier border for emphasis, active inputs, and selected outlines.",
     label: "Strong border",
     name: "border.strong",
-    value: "#91a6a1",
+    value: "#637571",
+    dark: "#8a9c98",
   },
   {
     description: "A hairline rule separating rows or sections inside one surface.",
     label: "Divider",
     name: "border.divider",
     value: "#e2eae8",
+    dark: "#222e2c",
+  },
+  {
+    description:
+      "The boundary of a form control — an input, a select — which must stand out at least 3:1 against what surrounds it (WCAG 2.2 §1.4.11).",
+    label: "Control border",
+    name: "border.control",
+    value: "#7a8d89",
+    dark: "#667a76",
   },
   {
     description: "The border width used by controls and panels.",
@@ -193,12 +235,14 @@ const declarations = [
     label: "Success background",
     name: "status.success-background",
     value: "#dcfce7",
+    dark: "#12301f",
   },
   {
     description: "Border of a success badge or banner.",
     label: "Success border",
     name: "status.success-border",
     value: "#86efac",
+    dark: "#2f6e49",
   },
   {
     description: "The non-colour signal for success, rendered beside the label.",
@@ -211,12 +255,14 @@ const declarations = [
     label: "Warning background",
     name: "status.warning-background",
     value: "#fef3c7",
+    dark: "#33280f",
   },
   {
     description: "Border of a warning badge or banner.",
     label: "Warning border",
     name: "status.warning-border",
     value: "#fcd34d",
+    dark: "#7c6121",
   },
   {
     description: "The non-colour signal for a warning, rendered beside the label.",
@@ -229,12 +275,14 @@ const declarations = [
     label: "Danger background",
     name: "status.danger-background",
     value: "#ffe4e6",
+    dark: "#3b1a22",
   },
   {
     description: "Border of a danger badge or banner.",
     label: "Danger border",
     name: "status.danger-border",
     value: "#fda4af",
+    dark: "#8c3648",
   },
   {
     description: "The non-colour signal for danger or failure, rendered beside the label.",
@@ -247,12 +295,14 @@ const declarations = [
     label: "Info background",
     name: "status.info-background",
     value: "#def2ef",
+    dark: "#14322e",
   },
   {
     description: "Border of a neutral informational badge or banner.",
     label: "Info border",
     name: "status.info-border",
     value: "#9bd5ce",
+    dark: "#2f6c63",
   },
   {
     description: "The non-colour signal for information, rendered beside the label.",
@@ -269,24 +319,28 @@ const declarations = [
     label: "Hover background",
     name: "state.hover-background",
     value: "#edf3f1",
+    dark: "#1f2c2a",
   },
   {
     description: "Background wash under a control being pressed.",
     label: "Pressed background",
     name: "state.pressed-background",
     value: "#e1ebe8",
+    dark: "#273634",
   },
   {
     description: "Background of a selected row, tab, or list item.",
     label: "Selected background",
     name: "state.selected-background",
     value: "#def2ef",
+    dark: "#183b37",
   },
   {
     description: "Foreground of a selected row, tab, or list item.",
     label: "Selected foreground",
     name: "state.selected-foreground",
     value: "#205f59",
+    dark: "#a3e6dc",
   },
   {
     description: "Opacity applied to a disabled control. Disabled state is never colour alone.",
@@ -462,23 +516,30 @@ const declarations = [
     name: "radius.none",
     value: "0",
   },
+  {
+    description:
+      "How rounded every corner is, as one multiplier: 1 is the default, 0 is square. Small, medium, and large radii scale with it; none and pill do not.",
+    label: "Corner roundness",
+    name: "radius.scale",
+    value: "1",
+  },
   {
     description: "Corner radius for badges and small inline elements.",
     label: "Small radius",
     name: "radius.sm",
-    value: "0.25rem",
+    value: "calc(0.25rem * var(--ekklesia-radius-scale))",
   },
   {
     description: "Corner radius for controls, inputs, and buttons.",
     label: "Medium radius",
     name: "radius.md",
-    value: "0.625rem",
+    value: "calc(0.625rem * var(--ekklesia-radius-scale))",
   },
   {
     description: "Corner radius for panels and dialogs.",
     label: "Large radius",
     name: "radius.lg",
-    value: "0.875rem",
+    value: "calc(0.875rem * var(--ekklesia-radius-scale))",
   },
   {
     description: "Fully rounded ends, for pills and status dots.",
@@ -497,18 +558,21 @@ const declarations = [
     label: "Small shadow",
     name: "shadow.sm",
     value: "0 1px 3px rgba(24, 35, 33, 0.08)",
+    dark: "0 1px 3px rgba(0, 0, 0, 0.45)",
   },
   {
     description: "Shadow for a popover or a raised surface.",
     label: "Medium shadow",
     name: "shadow.md",
     value: "0 8px 24px rgba(24, 35, 33, 0.12)",
+    dark: "0 8px 24px rgba(0, 0, 0, 0.5)",
   },
   {
     description: "Shadow for a modal dialog.",
     label: "Large shadow",
     name: "shadow.lg",
     value: "0 18px 48px rgba(24, 35, 33, 0.2)",
+    dark: "0 18px 48px rgba(0, 0, 0, 0.6)",
   },
 
   // ---------------------------------------------------------------------------------------------
@@ -538,6 +602,27 @@ const declarations = [
     name: "control.padding-inline",
     value: "0.75rem",
   },
+
+  // ---------------------------------------------------------------------------------------------
+  // Motion — every duration an element animates for. Each is zero when motion is reduced (ADR 0060),
+  // so an element that uses these tokens needs no reduced-motion rule of its own.
+  // ---------------------------------------------------------------------------------------------
+  {
+    description:
+      "A quick, purposeful transition: a sidebar collapsing, a notification arriving. Zero when motion is reduced.",
+    label: "Short duration",
+    name: "motion.duration-short",
+    value: "160ms",
+    reduced: "0ms",
+  },
+  {
+    description:
+      "One cycle of a gentle, continuous indication that something is happening, such as a loading placeholder. Zero when motion is reduced.",
+    label: "Ambient duration",
+    name: "motion.duration-ambient",
+    value: "1.6s",
+    reduced: "0s",
+  },
 ] as const satisfies readonly DesignTokenInput[];
 
 /** Every registered token name, as a union — the compile-time half of "modules consume registered

packages/design-tokens/src/token.ts

@@ -26,6 +26,7 @@ export const DESIGN_TOKEN_CATEGORIES = [
   "radius",
   "shadow",
   "control",
+  "motion",
 ] as const;
 
 export type DesignTokenCategory = (typeof DESIGN_TOKEN_CATEGORIES)[number];
@@ -82,8 +83,18 @@ export interface DesignTokenInput {
   readonly label: string;
   /** What the token means and when to reach for it. Enumerable, never rendered by the platform. */
   readonly description: string;
-  /** The default CSS value installed at a host root. */
+  /** The default CSS value installed at a host root: the light value, for a colour. */
   readonly value: string;
+  /**
+   * The value in the dark colour scheme, when it differs (ADR 0060). A token without one keeps its
+   * value in both schemes — a length, a weight, a font stack. Validated exactly like `value`.
+   */
+  readonly dark?: string;
+  /**
+   * The value when motion is reduced (ADR 0060), for a motion token: a duration of zero. A token
+   * without one is unaffected by the motion preference. Validated exactly like `value`.
+   */
+  readonly reduced?: string;
 }
 
 /** A validated token: its declaration plus the two derived facts callers actually consume. */
@@ -191,6 +202,12 @@ function validateToken(input: DesignTokenInput): DesignToken {
   if (!isTokenValue(input.value)) {
     throw new DesignTokenError("DESIGN_TOKEN_VALUE_INVALID");
   }
+  if (input.dark !== undefined && !isTokenValue(input.dark)) {
+    throw new DesignTokenError("DESIGN_TOKEN_VALUE_INVALID");
+  }
+  if (input.reduced !== undefined && !isTokenValue(input.reduced)) {
+    throw new DesignTokenError("DESIGN_TOKEN_VALUE_INVALID");
+  }
   return Object.freeze({
     category: category as DesignTokenCategory,
     cssVariable,
@@ -198,6 +215,8 @@ function validateToken(input: DesignTokenInput): DesignToken {
     label: input.label,
     name: input.name,
     value: input.value,
+    ...(input.dark === undefined ? {} : { dark: input.dark }),
+    ...(input.reduced === undefined ? {} : { reduced: input.reduced }),
   });
 }
 
@@ -206,6 +225,22 @@ function validateToken(input: DesignTokenInput): DesignToken {
  * an arbitrary selector string is exactly the unbounded value this package refuses everywhere else. */
 export type DesignTokenScope = "root" | "host";
 
+/** The colour schemes a token can carry a value for. */
+export type DesignTokenColorScheme = "light" | "dark";
+
+/**
+ * The attribute a host sets on its theme root to choose an appearance (ADR 0060): `light` or `dark`
+ * forces that scheme; anything else, including its absence, follows `prefers-color-scheme`.
+ */
+export const DESIGN_TOKEN_APPEARANCE_ATTRIBUTE = "data-ekklesia-appearance";
+
+/**
+ * The attribute a host sets on its theme root to choose motion (ADR 0060): `reduce` forces reduced
+ * motion; `allow` keeps full motion even when the system asks for less; anything else, including its
+ * absence, follows `prefers-reduced-motion`.
+ */
+export const DESIGN_TOKEN_MOTION_ATTRIBUTE = "data-ekklesia-motion";
+
 export interface DesignTokenRegistry<Name extends string = string> {
   /** Every token, in declaration order. Stable, frozen, and the enumeration a theme editor reads. */
   list(): readonly DesignToken[];
@@ -219,10 +254,52 @@ export interface DesignTokenRegistry<Name extends string = string> {
   variable(name: Name): string;
   /** `var(--ekklesia-…)` for a registered token — what component code actually writes. */
   reference(name: Name): string;
-  /** The complete default theme as one CSS rule, ready to install at a host root. */
+  /** The value of a registered token in one colour scheme. Throws `DesignTokenError` otherwise. */
+  valueFor(name: Name, scheme: DesignTokenColorScheme): string;
+  /**
+   * The complete theme, ready to install at a host root: every default value, and — when the
+   * registry has them — the dark values and the reduced-motion values, each selected by CSS alone
+   * (ADR 0060). A registry with neither emits exactly one rule.
+   */
   stylesheet(scope?: DesignTokenScope): string;
 }
 
+function declarationBlock(
+  tokens: readonly DesignToken[],
+  pick: (token: DesignToken) => string | undefined,
+  extra: readonly string[] = [],
+): string {
+  const lines = tokens.flatMap((token) => {
+    const value = pick(token);
+    return value === undefined ? [] : [`  ${token.cssVariable}: ${value};`];
+  });
+  return [...extra.map((line) => `  ${line};`), ...lines].join("\n");
+}
+
+/**
+ * The selectors one scope uses. `root` is a document; `host` is an isolated root with no inheriting
+ * ancestor, whose host element carries the attributes. Fixed strings — never a caller's selector.
+ */
+function selectorsFor(scope: DesignTokenScope) {
+  const appearance = DESIGN_TOKEN_APPEARANCE_ATTRIBUTE;
+  const motion = DESIGN_TOKEN_MOTION_ATTRIBUTE;
+  return scope === "root"
+    ? {
+        base: ":root",
+        darkExplicit: `:root[${appearance}="dark"]`,
+        darkSystem: `:root:not([${appearance}="light"])`,
+        reducedExplicit: `:root[${motion}="reduce"]`,
+        reducedSystem: `:root:not([${motion}="allow"])`,
+      }
+    : {
+        base: ":host",
+        darkExplicit: `:host([${appearance}="dark"])`,
+        darkSystem: `:host(:not([${appearance}="light"]))`,
+        reducedExplicit: `:host([${motion}="reduce"])`,
+        reducedSystem: `:host(:not([${motion}="allow"]))`,
+      };
+}
+
 /**
  * Validates a declaration list and returns the immutable registry built from it.
  *
@@ -272,10 +349,37 @@ export function createDesignTokenRegistry<const Tokens extends readonly DesignTo
       if (scope !== "root" && scope !== "host") {
         throw new DesignTokenError("DESIGN_TOKEN_SCOPE_INVALID");
       }
-      const declarationText = tokens
-        .map((token) => `  ${token.cssVariable}: ${token.value};`)
-        .join("\n");
-      return `${scope === "root" ? ":root" : ":host"} {\n${declarationText}\n}\n`;
+      const selectors = selectorsFor(scope);
+      const themed = tokens.some((token) => token.dark !== undefined);
+      const moving = tokens.some((token) => token.reduced !== undefined);
+      // `color-scheme` goes with the tokens, so native controls and scrollbars always match the
+      // scheme the tokens are in — including inside an isolated root, which inherits it.
+      const rules = [
+        `${selectors.base} {\n${declarationBlock(
+          tokens,
+          (token) => token.value,
+          themed ? ["color-scheme: light"] : [],
+        )}\n}`,
+      ];
+      if (themed) {
+        const dark = declarationBlock(tokens, (token) => token.dark, ["color-scheme: dark"]);
+        rules.push(
+          `@media (prefers-color-scheme: dark) {\n${selectors.darkSystem} {\n${dark}\n}\n}`,
+          `${selectors.darkExplicit} {\n${dark}\n}`,
+        );
+      }
+      if (moving) {
+        const reduced = declarationBlock(tokens, (token) => token.reduced);
+        rules.push(
+          `@media (prefers-reduced-motion: reduce) {\n${selectors.reducedSystem} {\n${reduced}\n}\n}`,
+          `${selectors.reducedExplicit} {\n${reduced}\n}`,
+        );
+      }
+      return `${rules.join("\n")}\n`;
+    },
+    valueFor: (name: string, scheme: DesignTokenColorScheme): string => {
+      const token = requireToken(name);
+      return scheme === "dark" ? (token.dark ?? token.value) : token.value;
     },
     variable: (name: string): string => requireToken(name).cssVariable,
   });