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);
+        }
+      };
+    },
+  };
+}