@timmo001/groundwork-tokens 0.3.0 → 0.4.0

package/generated/themes.ts

@@ -880,7 +880,7 @@ export const themes = [
   {
     "id": "bridge",
     "name": "Bridge",
-    "description": "A clear, bright blue on neutral charcoal. Medium radii, soft borders and pill chips.",
+    "description": "System Bridge's violet on neutral charcoal. Medium radii, soft borders and pill chips.",
     "optional": false,
     "family": null,
     "examples": [
@@ -977,15 +977,15 @@ export const themes = [
         "fill-primary-hovered": "#2e2e2f",
         "fill-primary-pressed": "#383839",
         "on-primary": "#fdfdff",
-        "accent": "#1465b9",
-        "fill-accent-resting": "#1465b9",
-        "fill-accent-hovered": "#0057a8",
-        "fill-accent-pressed": "#1f6dc1",
-        "fill-accent-quiet": "#1465b929",
-        "border-accent": "#1465b980",
+        "accent": "#7152bb",
+        "fill-accent-resting": "#7152bb",
+        "fill-accent-hovered": "#6343ab",
+        "fill-accent-pressed": "#785ac4",
+        "fill-accent-quiet": "#7152bb29",
+        "border-accent": "#7152bb80",
         "on-accent": "#ffffff",
-        "focus": "#1465b9",
-        "link": "#1465b9",
+        "focus": "#7152bb",
+        "link": "#7152bb",
         "info": "#276baa",
         "fill-info-quiet": "#276baa24",
         "border-info": "#276baa73",
@@ -1024,15 +1024,15 @@ export const themes = [
         "fill-primary-hovered": "#d4d4d6",
         "fill-primary-pressed": "#c7c7c9",
         "on-primary": "#17171b",
-        "accent": "#549ff7",
-        "fill-accent-resting": "#549ff7",
-        "fill-accent-hovered": "#6bafff",
-        "fill-accent-pressed": "#4c97ee",
-        "fill-accent-quiet": "#549ff729",
-        "border-accent": "#549ff780",
+        "accent": "#a78bfa",
+        "fill-accent-resting": "#a78bfa",
+        "fill-accent-hovered": "#b69eff",
+        "fill-accent-pressed": "#9f83f1",
+        "fill-accent-quiet": "#a78bfa29",
+        "border-accent": "#a78bfa80",
         "on-accent": "#0b0b0b",
-        "focus": "#549ff7",
-        "link": "#549ff7",
+        "focus": "#a78bfa",
+        "link": "#a78bfa",
         "info": "#5b9ee0",
         "fill-info-quiet": "#5b9ee024",
         "border-info": "#5b9ee073",
@@ -1071,15 +1071,15 @@ export const themes = [
         "fill-primary-hovered": "#d4d4d6",
         "fill-primary-pressed": "#c7c7c9",
         "on-primary": "#141418",
-        "accent": "#549ff7",
-        "fill-accent-resting": "#549ff7",
-        "fill-accent-hovered": "#6bafff",
-        "fill-accent-pressed": "#4c97ee",
-        "fill-accent-quiet": "#549ff729",
-        "border-accent": "#549ff780",
+        "accent": "#a78bfa",
+        "fill-accent-resting": "#a78bfa",
+        "fill-accent-hovered": "#b69eff",
+        "fill-accent-pressed": "#9f83f1",
+        "fill-accent-quiet": "#a78bfa29",
+        "border-accent": "#a78bfa80",
         "on-accent": "#0b0b0b",
-        "focus": "#549ff7",
-        "link": "#549ff7",
+        "focus": "#a78bfa",
+        "link": "#a78bfa",
         "info": "#5b9ee0",
         "fill-info-quiet": "#5b9ee024",
         "border-info": "#5b9ee073",

package/package.json

@@ -1,12 +1,15 @@
 {
   "name": "@timmo001/groundwork-tokens",
-  "version": "0.3.0",
+  "version": "0.4.0",
   "description": "Groundwork's design tokens: the theme schema, the OKLCH solver and every theme as CSS and JSON",
   "license": "Apache-2.0",
   "type": "module",
   "exports": {
     ".": "./src/index.ts",
     "./runtime": "./src/runtime.ts",
+    "./page": "./src/page.ts",
+    "./webmcp": "./src/webmcp.ts",
+    "./opentui": "./generated/opentui.ts",
     "./themes.css": "./generated/themes.css",
     "./themes.json": "./generated/themes.json"
   },

package/src/generate.ts

@@ -233,6 +233,26 @@ const preUpgrade = {
   "gw-page-header": { display: "flex", "min-block-size": "3rem" },
   "gw-page-header[description]": { "min-block-size": "3.6875rem" },
   "gw-section-title": { display: "flex", "align-items": "center" },
+  "gw-app-bar": {
+    position: "sticky",
+    "inset-block-start": "0",
+    "z-index": "50",
+    display: "flex",
+    gap: "var(--gw-space-3)",
+    "align-items": "center",
+    "min-block-size": "calc(3.5rem + 1px)",
+    "padding-inline":
+      "max(var(--gw-space-3), (100% - var(--gw-content-width)) / 2)",
+  },
+  "gw-app-bar[overlay]": { position: "fixed", "inset-inline": "0" },
+  'gw-app-bar[reveal-after]:not(:defined) > [slot="brand"]': {
+    visibility: "hidden",
+  },
+  "gw-theme-picker": {
+    display: "inline-block",
+    "min-block-size": "2.5rem",
+    "vertical-align": "middle",
+  },
   "gw-button[icon]": {
     "padding-inline-start":
       "calc(var(--gw-space-4) + var(--gw-space-2) + 1.125rem + 1px)",

package/src/omarchy.test.ts

@@ -0,0 +1,63 @@
+/**
+ * Tests the Omarchy import against a real `colors.toml` shape, in both modes,
+ * and that a file missing a color fails rather than half-applies.
+ *
+ * @module
+ */
+import { expect, test } from "bun:test";
+import { Result } from "effect";
+import { omarchyTheme } from "./omarchy.ts";
+
+const dark = `mode = "dark"
+
+accent = "#7aa2f7"
+selection = "#292e42"
+muted = "#414868"
+
+background = "#1a1b26"
+dark_background = "#13141c"
+lighter_background = "#24283b"
+
+foreground = "#a9b1d6"
+light_foreground = "#b4bee6"
+bright_foreground = "#c0caf5"
+
+red = "#f7768e"
+yellow = "#e0af68"
+green = "#9ece6a"
+blue = "#7aa2f7"
+magenta = "#ad8ee6"
+`;
+
+test("maps a dark colors.toml onto the roles", () => {
+  const theme = Result.getOrThrow(omarchyTheme(dark, "Tokyo Night", "tokyo"));
+
+  expect(theme.mode).toBe("dark");
+  expect(theme.palette).toMatchObject({
+    lower: "#13141c",
+    background: "#1a1b26",
+    raised: "#24283b",
+    border: "#414868",
+    text: "#c0caf5",
+    muted: "#a9b1d6",
+    danger: "#f7768e",
+  });
+});
+
+test("uses the light foreground as muted when foreground is the text", () => {
+  const light = dark
+    .replace('mode = "dark"', 'mode = "light"')
+    .replace("#a9b1d6", "#C0CAF5")
+    .replace("#b4bee6", "#403e3c");
+
+  const theme = Result.getOrThrow(omarchyTheme(light));
+
+  expect(theme.mode).toBe("light");
+  expect(theme.palette.muted).toBe("#403e3c");
+});
+
+test("fails when a color is missing", () => {
+  expect(Result.isFailure(omarchyTheme(dark.replace(/^red = .*$/m, "")))).toBe(
+    true,
+  );
+});

package/src/omarchy.ts

@@ -0,0 +1,66 @@
+/**
+ * Omarchy theme import: reads an Omarchy theme's `colors.toml` and maps it
+ * onto a Groundwork mapped theme, so an app can follow the desktop's theme.
+ * It parses the flat `key = "value"` lines itself, so it runs in a browser.
+ *
+ * @module
+ */
+import { Schema } from "effect";
+import { MappedTheme } from "./schema.ts";
+
+/** The `key = "value"` pairs of a flat TOML file, ignoring comments. */
+const readPairs = (text: string): ReadonlyMap<string, string> => {
+  const pairs = new Map<string, string>();
+
+  for (const line of text.split(/\r?\n/)) {
+    const match = /^\s*([A-Za-z_][\w-]*)\s*=\s*"([^"]*)"/.exec(line);
+
+    if (match?.[1] !== undefined && match[2] !== undefined) {
+      pairs.set(match[1], match[2]);
+    }
+  }
+
+  return pairs;
+};
+
+/**
+ * Maps an Omarchy `colors.toml` onto a mapped theme's palette, then checks it
+ * against the Schema. Missing keys or bad colors come back as a `Failure`.
+ */
+export const omarchyTheme = (
+  text: string,
+  name = "Omarchy",
+  id = "omarchy",
+) => {
+  const pairs = readPairs(text);
+  const color = (key: string) => pairs.get(key)?.toLowerCase();
+  const text_ = color("bright_foreground") ?? color("foreground");
+  const foreground = color("foreground");
+
+  return Schema.decodeUnknownResult(MappedTheme)({
+    kind: "mapped",
+    id,
+    name,
+    family: "Omarchy",
+    mode: pairs.get("mode") === "light" ? "light" : "dark",
+    palette: {
+      lower: color("dark_background"),
+      background: color("background"),
+      raised: color("lighter_background"),
+      border: color("muted") ?? color("selection"),
+      text: text_,
+      // Omarchy's foreground is the body text; when it's the same as the
+      // brightest text, its light foreground is the quieter one
+      muted:
+        foreground !== undefined && foreground !== text_
+          ? foreground
+          : color("light_foreground"),
+      accent: color("accent"),
+      info: color("blue"),
+      success: color("green"),
+      important: color("magenta"),
+      warning: color("yellow"),
+      danger: color("red"),
+    },
+  });
+};

package/src/page.ts

@@ -0,0 +1,307 @@
+/**
+ * A page's theme and mode: keeps the visitor's pick across visits, applies
+ * it to `<html>`, and lets them bring their own theme. The solver and the
+ * WebMCP tools load only when a custom theme or `document.modelContext`
+ * needs them, so a page that only switches built-in themes stays small.
+ *
+ * Put `themeBootScript()` in an inline `<script>` in `<head>` so the stored
+ * pick applies before the first paint.
+ *
+ * @module
+ */
+import base from "../themes/base.json" with { type: "json" };
+import bridge from "../themes/bridge.json" with { type: "json" };
+import glazing from "../themes/glazing.json" with { type: "json" };
+import slate from "../themes/slate.json" with { type: "json" };
+import snag from "../themes/snag.json" with { type: "json" };
+import survey from "../themes/survey.json" with { type: "json" };
+import type { Theme } from "./schema.ts";
+// Only for `document.modelContext`'s type; the tools themselves load lazily
+import type {} from "./webmcp.ts";
+
+/** How light the page is: `auto` follows the system. */
+export type ThemeMode = "auto" | "light" | "dark" | "darker";
+
+/** The theme id a visitor's own theme is solved under. */
+export const customThemeId = "custom";
+
+/** The id of the `<style>` holding a custom theme's CSS. */
+export const customThemeStyleId = "gw-custom-theme";
+
+const modes: readonly ThemeMode[] = ["auto", "light", "dark", "darker"];
+
+export interface PageThemeState {
+  readonly mode: ThemeMode;
+  /** The theme id in use: a built-in one, or `custom`. */
+  readonly theme: string;
+  /** The visitor's own theme's name, when they've imported one. */
+  readonly custom: string | null;
+}
+
+/** What `importTheme` reports: the theme's name and any contrast misses, or why it failed. */
+export type ImportResult =
+  | {
+      readonly ok: true;
+      readonly name: string;
+      readonly misses: readonly string[];
+    }
+  | { readonly ok: false; readonly error: string };
+
+/** A theme to offer, by id and name. A `Theme` document is one. */
+export interface ThemeChoice {
+  readonly id: string;
+  readonly name: string;
+}
+
+/** The core themes by id and name, in the order the docs list them. */
+export const coreThemeChoices: readonly ThemeChoice[] = [
+  base,
+  glazing,
+  survey,
+  slate,
+  bridge,
+  snag,
+].map(({ id, name }) => ({ id, name }));
+
+export interface PageThemeOptions {
+  /** The local storage key prefix, such as `my-site:theme`. */
+  readonly key: string;
+  /** The built-in themes to offer, their CSS already on the page. */
+  readonly themes: readonly ThemeChoice[];
+  /**
+   * The full documents of `themes`, loaded only when the WebMCP tools
+   * register. Defaults to the core themes.
+   */
+  readonly documents?: () => Promise<readonly Theme[]>;
+  /** The theme id to start with. */
+  readonly defaultTheme: string;
+  /** The mode to start with. Defaults to `auto`. */
+  readonly defaultMode?: ThemeMode;
+  /** The element the attributes go on. Defaults to `<html>`. */
+  readonly root?: HTMLElement;
+}
+
+export interface PageTheme {
+  readonly state: () => PageThemeState;
+  readonly setMode: (mode: ThemeMode) => void;
+  readonly setTheme: (id: string) => void;
+  /** Solves a theme document's JSON or an Omarchy `colors.toml` and applies it. */
+  readonly importTheme: (text: string) => Promise<ImportResult>;
+  /** Drops the visitor's own theme and goes back to the defaults. */
+  readonly reset: () => void;
+  /** Calls `listener` on every change; returns a function that stops it. */
+  readonly subscribe: (listener: (state: PageThemeState) => void) => () => void;
+}
+
+const keys = (key: string) => ({
+  mode: `${key}:mode`,
+  theme: `${key}:id`,
+  document: `${key}:custom`,
+  css: `${key}:custom-css`,
+  name: `${key}:custom-name`,
+});
+
+const read = (key: string) => {
+  try {
+    return localStorage.getItem(key);
+  } catch {
+    return null;
+  }
+};
+
+const write = (key: string, value: string | null) => {
+  try {
+    if (value === null) localStorage.removeItem(key);
+    else localStorage.setItem(key, value);
+  } catch {
+    // Blocked or full: the pick still applies until the page closes
+  }
+};
+
+/**
+ * An inline script that applies the stored mode, theme and any custom theme's
+ * cached CSS before the first paint. Takes the same key and defaults as
+ * `pageTheme`.
+ */
+export const themeBootScript = (
+  options: Pick<PageThemeOptions, "key" | "defaultTheme" | "defaultMode">,
+) => {
+  const stored = keys(options.key);
+
+  const config = JSON.stringify({
+    keys: stored,
+    theme: options.defaultTheme,
+    mode: options.defaultMode ?? "auto",
+    custom: customThemeId,
+    style: customThemeStyleId,
+  });
+
+  return `(()=>{const c=${config};let s;try{s=localStorage}catch{}const g=(k)=>{try{return s?.getItem(k)??null}catch{return null}};const r=document.documentElement;let t=g(c.keys.theme)??c.theme;const m=g(c.keys.mode)??c.mode;if(t===c.custom){const css=g(c.keys.css);if(css){const e=document.createElement("style");e.id=c.style;e.textContent=css;document.head.append(e)}else t=c.theme}r.setAttribute("data-gw-theme",t);if(m==="auto")r.removeAttribute("data-gw-mode");else r.setAttribute("data-gw-mode",m)})();`;
+};
+
+/** Reads a theme from JSON text or an Omarchy `colors.toml`. */
+const readTheme = async (text: string) => {
+  const { Result } = await import("effect");
+  const { omarchyTheme, parseTheme } = await import("./runtime.ts");
+  const parsed = parseTheme(text);
+
+  if (Result.isSuccess(parsed) || text.trimStart().startsWith("{")) {
+    return parsed;
+  }
+
+  return omarchyTheme(text);
+};
+
+/**
+ * Sets up the page's theme from what's stored, falling back to the defaults,
+ * and registers the WebMCP theme tools where the browser offers them.
+ */
+export const pageTheme = (options: PageThemeOptions): PageTheme => {
+  const stored = keys(options.key);
+  const root = options.root ?? document.documentElement;
+  const defaultMode = options.defaultMode ?? "auto";
+  const listeners = new Set<(state: PageThemeState) => void>();
+
+  const known = (id: string) => options.themes.some((theme) => theme.id === id);
+
+  const storedMode = read(stored.mode);
+  const storedTheme = read(stored.theme);
+  const customName = read(stored.name);
+  const customCss = read(stored.css);
+
+  let state: PageThemeState = {
+    mode: modes.find((mode) => mode === storedMode) ?? defaultMode,
+    theme:
+      storedTheme !== null &&
+      (known(storedTheme) ||
+        (storedTheme === customThemeId && customCss !== null))
+        ? storedTheme
+        : options.defaultTheme,
+    custom: customCss === null ? null : customName,
+  };
+
+  const setStyle = (css: string | null) => {
+    let style = document.getElementById(customThemeStyleId);
+
+    if (css === null) {
+      style?.remove();
+
+      return;
+    }
+
+    if (style === null) {
+      style = document.createElement("style");
+      style.id = customThemeStyleId;
+      document.head.append(style);
+    }
+
+    style.textContent = css;
+  };
+
+  const commit = (next: PageThemeState) => {
+    state = next;
+    root.setAttribute("data-gw-theme", state.theme);
+
+    if (state.mode === "auto") root.removeAttribute("data-gw-mode");
+    else root.setAttribute("data-gw-mode", state.mode);
+
+    for (const listener of listeners) listener(state);
+  };
+
+  /** Solves a document under the custom id, applies it and keeps it. */
+  const applyCustom = async (document: Theme, text: string) => {
+    const { runtimeTheme } = await import("./runtime.ts");
+    const runtime = runtimeTheme(document, customThemeId);
+
+    setStyle(runtime.css);
+    write(stored.document, text);
+    write(stored.css, runtime.css);
+    write(stored.name, document.name);
+    write(stored.theme, customThemeId);
+    commit({ ...state, theme: customThemeId, custom: document.name });
+
+    return runtime.checks
+      .filter((result) => !result.passes)
+      .map(
+        (result) =>
+          `${result.role} in ${result.mode} (${result.ratio.toFixed(2)})`,
+      );
+  };
+
+  const setTheme = (id: string) => {
+    if (!known(id) && !(id === customThemeId && state.custom !== null)) return;
+
+    write(stored.theme, id);
+    commit({ ...state, theme: id });
+  };
+
+  const page: PageTheme = {
+    state: () => state,
+    setMode: (mode) => {
+      write(stored.mode, mode);
+      commit({ ...state, mode });
+    },
+    setTheme,
+    importTheme: async (text) => {
+      const { Result } = await import("effect");
+      const parsed = await readTheme(text);
+
+      if (Result.isFailure(parsed)) {
+        return {
+          ok: false,
+          error: `That isn't a theme document or an Omarchy colors.toml: ${String(parsed.failure).slice(0, 400)}`,
+        };
+      }
+
+      const misses = await applyCustom(parsed.success, text);
+
+      return { ok: true, name: parsed.success.name, misses };
+    },
+    reset: () => {
+      setStyle(null);
+
+      for (const key of Object.values(stored)) write(key, null);
+
+      commit({ mode: defaultMode, theme: options.defaultTheme, custom: null });
+    },
+    subscribe: (listener) => {
+      listeners.add(listener);
+
+      return () => {
+        listeners.delete(listener);
+      };
+    },
+  };
+
+  commit(state);
+
+  if (document.modelContext !== undefined) {
+    void import("./webmcp.ts").then(
+      async ({ coreThemes, registerThemeTools }) => {
+        const documents = ((await options.documents?.()) ?? coreThemes).filter(
+          (theme) => known(theme.id),
+        );
+
+        registerThemeTools({
+          themes: documents,
+          // The custom document is kept by `applyCustom`, so a built-in pick
+          // doesn't overwrite it
+          store: {
+            load: async () =>
+              state.custom === null ? null : read(stored.document),
+            save: async () => {},
+            clear: async () => {
+              page.reset();
+            },
+          },
+          apply: ({ document: theme, text }) => {
+            if (documents.includes(theme)) setTheme(theme.id);
+            else void applyCustom(theme, text);
+          },
+        });
+      },
+    );
+  }
+
+  return page;
+};

package/src/runtime.ts

@@ -11,6 +11,8 @@ import { themeCss } from "./generate.ts";
 import { SolvedTheme, Theme } from "./schema.ts";
 import { check, resolve, type Check, type ResolvedTheme } from "./solve.ts";
 
+export { omarchyTheme } from "./omarchy.ts";
+
 const base = Schema.decodeUnknownSync(SolvedTheme)(baseDocument);
 
 /** A theme solved at runtime, with its CSS and every contrast check. */
@@ -34,3 +36,44 @@ export const runtimeTheme = (theme: Theme, id = theme.id): RuntimeTheme => {
 
   return { theme: resolved, css: themeCss(resolved), checks: check(resolved) };
 };
+
+/**
+ * Where an app keeps a user's theme document. The document is stored, not
+ * its CSS, so it's solved again when the solver changes. Local storage is
+ * the first tier; an app with a profile or a host, such as System Bridge,
+ * passes its own store with the same shape.
+ */
+export interface ThemeStore {
+  /** The stored document's JSON text, or `null` when there's none. */
+  readonly load: () => Promise<string | null>;
+  readonly save: (text: string) => Promise<void>;
+  readonly clear: () => Promise<void>;
+}
+
+/**
+ * A store in the browser's local storage under `key`. It reads as empty and
+ * skips writes when storage is blocked, so a theme still applies for the visit.
+ */
+export const localThemeStore = (key: string): ThemeStore => ({
+  load: async () => {
+    try {
+      return localStorage.getItem(key);
+    } catch {
+      return null;
+    }
+  },
+  save: async (text) => {
+    try {
+      localStorage.setItem(key, text);
+    } catch {
+      // Blocked or full: the theme still applies until the page closes
+    }
+  },
+  clear: async () => {
+    try {
+      localStorage.removeItem(key);
+    } catch {
+      // Nothing to clear when storage is blocked
+    }
+  },
+});