M1.10: light theme, live theme switching, editor tokens

- theme::LIGHT next to DARK with the 10 new tokens (editor selection,
  active line, cursor, gutter, match, font size, tab active/modified,
  notice); light fg-muted, accent and error darkened for WCAG AA
- theme.list, theme.systemPreference, themeChanged event when the
  resolved theme changes (settings.set/reset appearance.theme, or the
  OS preference in system mode)
- desktop init script and window background from the stored setting;
  system mode uses a prefers-color-scheme media query for the first frame
- ui/src/theme.ts applies tokens to :root and color-scheme live; editor,
  tabs and notice drop their var() fallbacks
- Vitest WCAG AA contrast check against a Rust-maintained snapshot,
  DOM tests, headless control-channel test
- docs: architecture Themes, parity rows, ui-parity, gaps, roadmaps

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
This commit is contained in:
danny 2026-10-16 15:49:23 +02:00
parent 1ab448de4d
commit cde6e119c6
29 changed files with 1192 additions and 72 deletions

View file

@ -0,0 +1,94 @@
/**
* WCAG 2.1 contrast check of the built-in themes
* (https://www.w3.org/TR/WCAG21/#contrast-minimum). Every token pair the
* UI draws text with reaches AA: 4.5:1 for body text, 3:1 for non-text
* marks (cursor, modified dot; WCAG 1.4.11). The themes come from
* `themes.json`, a snapshot that the Rust test `ui_snapshot_is_current`
* keeps equal to `lutra_engine::theme`.
*/
import { describe, expect, it } from "vitest";
import themes from "./themes.json";
/** Minimum ratio for normal-size text (AA). */
const TEXT = 4.5;
/** Minimum ratio for large text and non-text marks (AA). */
const LARGE = 3;
/**
* Foreground token, background token and minimum ratio, for every
* combination the components use (see `ui/src/**` `color`/`background`).
*/
const PAIRS: [string, string, number][] = [
["fg", "bg", TEXT],
["fg", "editor-bg", TEXT],
["fg", "tab-active-bg", TEXT],
["fg", "notice-bg", TEXT],
["fg", "editor-active-line-bg", TEXT],
["fg", "editor-selection-bg", TEXT],
["fg", "editor-match-bg", TEXT],
["fg-muted", "bg", TEXT],
["fg-muted", "editor-bg", TEXT],
["accent", "bg", TEXT],
["error", "bg", TEXT],
["error", "statusbar-bg", TEXT],
["statusbar-fg", "statusbar-bg", TEXT],
["editor-gutter-fg", "editor-gutter-bg", TEXT],
["editor-gutter-fg", "editor-active-line-bg", TEXT],
["editor-cursor", "editor-bg", LARGE],
["editor-cursor", "editor-active-line-bg", LARGE],
["tab-modified", "bg", LARGE],
["tab-modified", "tab-active-bg", LARGE],
];
/**
* Relative luminance of a `#rrggbb` colour (WCAG 2.1 definition).
*
* @param hex - the colour.
* @returns the luminance, 0 (black) to 1 (white).
*/
export function luminance(hex: string): number {
const match = /^#([0-9a-f]{2})([0-9a-f]{2})([0-9a-f]{2})$/i.exec(hex);
if (!match) {
throw new Error(`not a #rrggbb colour: ${hex}`);
}
const [r, g, b] = match.slice(1).map((part) => {
const c = parseInt(part, 16) / 255;
return c <= 0.03928 ? c / 12.92 : ((c + 0.055) / 1.055) ** 2.4;
}) as [number, number, number];
return 0.2126 * r + 0.7152 * g + 0.0722 * b;
}
/**
* Contrast ratio of two colours.
*
* @param a - one `#rrggbb` colour.
* @param b - the other.
* @returns the ratio, 1 to 21.
*/
export function contrast(a: string, b: string): number {
const [hi, lo] = [luminance(a), luminance(b)].sort((x, y) => y - x) as [number, number];
return (hi + 0.05) / (lo + 0.05);
}
describe("contrast helper", () => {
it("matches the WCAG extremes", () => {
expect(contrast("#000000", "#ffffff")).toBeCloseTo(21, 5);
expect(contrast("#777777", "#777777")).toBe(1);
expect(contrast("#767676", "#ffffff")).toBeGreaterThanOrEqual(4.5);
});
});
describe.each(themes)("theme $id", (theme) => {
const tokens: Record<string, string> = theme.tokens;
const token = (name: string): string => {
const value = tokens[`--lt-${name}`];
if (value === undefined) {
throw new Error(`${theme.id} has no --lt-${name}`);
}
return value;
};
it.each(PAIRS)("%s on %s reaches %d:1", (fg, bg, min) => {
expect(contrast(token(fg), token(bg))).toBeGreaterThanOrEqual(min);
});
});

View file

@ -0,0 +1,194 @@
/**
* Tests of live theme switching (`ui/src/theme.ts`): tokens and
* `color-scheme` land on `:root`, `themeChanged` events and the OS
* preference drive it, and the components read only tokens both themes
* define (no `var(--lt-x, fallback)` left for theme tokens).
*/
import { readdirSync, readFileSync } from "node:fs";
import { join } from "node:path";
import { flushPromises } from "@vue/test-utils";
import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
import themes from "./themes.json";
const invoke = vi.hoisted(() => vi.fn());
const listeners = vi.hoisted(() => new Map<string, (event: { payload: unknown }) => void>());
vi.mock("@tauri-apps/api/core", () => ({ invoke }));
vi.mock("@tauri-apps/api/event", () => ({
listen: (name: string, handler: (event: { payload: unknown }) => void) => {
listeners.set(name, handler);
return Promise.resolve(() => listeners.delete(name));
},
}));
import { ENGINE_EVENT } from "../../src/ipc";
import { applyTheme, startTheme, toResolvedTheme, type ResolvedTheme } from "../../src/theme";
/** The snapshot themes by id. */
const byId = (id: string): ResolvedTheme => {
const theme = themes.find((t) => t.id === id);
if (!theme) {
throw new Error(`no theme ${id}`);
}
return theme;
};
/** A controllable `matchMedia` stand-in. */
function fakeMedia(dark: boolean) {
const handlers = new Set<(event: MediaQueryListEvent) => void>();
const query = {
matches: dark,
addEventListener: (_: string, h: (event: MediaQueryListEvent) => void) => handlers.add(h),
removeEventListener: (_: string, h: (event: MediaQueryListEvent) => void) =>
handlers.delete(h),
};
return {
query,
handlers,
change(next: boolean) {
query.matches = next;
for (const h of handlers) {
h({ matches: next } as MediaQueryListEvent);
}
},
};
}
const root = document.documentElement;
beforeEach(() => {
invoke.mockReset();
listeners.clear();
root.removeAttribute("style");
delete root.dataset.theme;
});
afterEach(() => {
vi.unstubAllGlobals();
});
describe("applyTheme", () => {
it("writes every token and the colour scheme onto :root", () => {
const light = byId("lutra-light");
applyTheme(light);
for (const [name, value] of Object.entries(light.tokens)) {
expect(root.style.getPropertyValue(name)).toBe(value);
}
expect(root.style.colorScheme).toBe("light");
expect(root.dataset.theme).toBe("lutra-light");
applyTheme(byId("lutra-dark"));
expect(root.style.getPropertyValue("--lt-bg")).toBe("#1f1d1b");
expect(root.style.getPropertyValue("--lt-editor-selection-bg")).toBe("#513f2c");
expect(root.style.colorScheme).toBe("dark");
});
});
describe("toResolvedTheme", () => {
it("rejects malformed data and drops foreign tokens", () => {
expect(toResolvedTheme(null)).toBeNull();
expect(toResolvedTheme({ id: "x" })).toBeNull();
expect(
toResolvedTheme({
kind: "themeChanged",
id: "x",
dark: true,
tokens: { "--lt-bg": "#000000", color: "red", "--lt-fg": 3 },
}),
).toEqual({ id: "x", dark: true, tokens: { "--lt-bg": "#000000" } });
});
});
describe("startTheme", () => {
it("reports the OS preference, applies the result and follows changes", async () => {
const media = fakeMedia(false);
vi.stubGlobal("matchMedia", () => media.query);
invoke.mockImplementation((_: string, args: { command: string; params: { dark: boolean } }) =>
Promise.resolve(
args.command === "theme.systemPreference"
? byId(args.params.dark ? "lutra-dark" : "lutra-light")
: null,
),
);
const stop = startTheme();
await flushPromises();
expect(invoke).toHaveBeenCalledWith("engine_execute", {
command: "theme.systemPreference",
params: { dark: false },
});
expect(root.dataset.theme).toBe("lutra-light");
expect(root.style.colorScheme).toBe("light");
media.change(true);
await flushPromises();
expect(root.dataset.theme).toBe("lutra-dark");
expect(root.style.getPropertyValue("--lt-bg")).toBe("#1f1d1b");
stop();
expect(media.handlers.size).toBe(0);
});
it("applies themeChanged events without a reload", async () => {
invoke.mockResolvedValue(null);
const stop = startTheme();
await flushPromises();
const emit = listeners.get(ENGINE_EVENT);
expect(emit).toBeDefined();
emit?.({ payload: { kind: "themeChanged", ...byId("lutra-light") } });
expect(root.dataset.theme).toBe("lutra-light");
expect(root.style.getPropertyValue("--lt-notice-bg")).toBe("#e9dfd4");
emit?.({ payload: { kind: "treeChanged", dir: "" } });
expect(root.dataset.theme).toBe("lutra-light");
stop();
});
it("keeps the current theme when the engine call fails", async () => {
invoke.mockRejectedValue({ code: "internal", message: "down" });
const stop = startTheme();
await flushPromises();
expect(root.dataset.theme).toBeUndefined();
stop();
});
});
describe("components", () => {
const SRC = join(import.meta.dirname, "..", "..", "src");
const files = (dir: string): string[] =>
readdirSync(dir, { withFileTypes: true }).flatMap((entry) => {
const path = join(dir, entry.name);
if (entry.isDirectory()) {
return files(path);
}
return /\.(ts|vue|css)$/.test(entry.name) ? [path] : [];
});
const source = files(SRC).map((file) => readFileSync(file, "utf8"));
const defined = (name: string) => themes.every((t) => name in t.tokens);
it("use only theme tokens that both themes define, without fallbacks", () => {
const used = source.flatMap((text) =>
[...text.matchAll(/var\((--lt-[a-z0-9-]+)\s*(,)?/g)].map((m) => ({
name: m[1] ?? "",
fallback: m[2] !== undefined,
})),
);
expect(used.length).toBeGreaterThan(0);
const missing = used.filter((u) => !u.fallback && !defined(u.name)).map((u) => u.name);
expect([...new Set(missing)]).toEqual([]);
const needless = used.filter((u) => u.fallback && defined(u.name)).map((u) => u.name);
expect([...new Set(needless)]).toEqual([]);
});
it("give the editor every editor token", () => {
const editor = readFileSync(join(SRC, "components", "editor", "extensions.ts"), "utf8");
for (const name of [
"--lt-editor-selection-bg",
"--lt-editor-active-line-bg",
"--lt-editor-cursor",
"--lt-editor-gutter-bg",
"--lt-editor-gutter-fg",
"--lt-editor-match-bg",
"--lt-font-size-editor",
]) {
expect(editor).toContain(`var(${name})`);
}
});
});

View file

@ -0,0 +1,62 @@
[
{
"dark": true,
"id": "lutra-dark",
"labelKey": "theme.lutraDark",
"tokens": {
"--lt-accent": "#d39a5c",
"--lt-bg": "#1f1d1b",
"--lt-border": "#34302c",
"--lt-editor-active-line-bg": "#232221",
"--lt-editor-bg": "#191817",
"--lt-editor-cursor": "#d39a5c",
"--lt-editor-gutter-bg": "#191817",
"--lt-editor-gutter-fg": "#9a928a",
"--lt-editor-match-bg": "#3a2f23",
"--lt-editor-selection-bg": "#513f2c",
"--lt-error": "#ef7b6c",
"--lt-fg": "#e6e1da",
"--lt-fg-muted": "#9a928a",
"--lt-font-mono": "ui-monospace, \"Cascadia Code\", Menlo, Consolas, monospace",
"--lt-font-size-editor": "14px",
"--lt-font-size-small": "12px",
"--lt-font-size-ui": "13px",
"--lt-font-ui": "system-ui, -apple-system, \"Segoe UI\", Roboto, Ubuntu, sans-serif",
"--lt-notice-bg": "#3a3025",
"--lt-statusbar-bg": "#24211f",
"--lt-statusbar-fg": "#b8afa6",
"--lt-tab-active-bg": "#191817",
"--lt-tab-modified": "#d39a5c"
}
},
{
"dark": false,
"id": "lutra-light",
"labelKey": "theme.lutraLight",
"tokens": {
"--lt-accent": "#965a22",
"--lt-bg": "#f4f1ec",
"--lt-border": "#ddd6cd",
"--lt-editor-active-line-bg": "#f1efed",
"--lt-editor-bg": "#fbfaf8",
"--lt-editor-cursor": "#965a22",
"--lt-editor-gutter-bg": "#fbfaf8",
"--lt-editor-gutter-fg": "#6b625a",
"--lt-editor-match-bg": "#ece2d8",
"--lt-editor-selection-bg": "#e5d7c9",
"--lt-error": "#b23a29",
"--lt-fg": "#2a2622",
"--lt-fg-muted": "#6b625a",
"--lt-font-mono": "ui-monospace, \"Cascadia Code\", Menlo, Consolas, monospace",
"--lt-font-size-editor": "14px",
"--lt-font-size-small": "12px",
"--lt-font-size-ui": "13px",
"--lt-font-ui": "system-ui, -apple-system, \"Segoe UI\", Roboto, Ubuntu, sans-serif",
"--lt-notice-bg": "#e9dfd4",
"--lt-statusbar-bg": "#ece7e0",
"--lt-statusbar-fg": "#5a5149",
"--lt-tab-active-bg": "#fbfaf8",
"--lt-tab-modified": "#965a22"
}
}
]