@timmo001/groundwork-tokens 0.5.0 → 0.6.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@timmo001/groundwork-tokens",
-  "version": "0.5.0",
+  "version": "0.6.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",
@@ -11,7 +11,8 @@
     "./webmcp": "./src/webmcp.ts",
     "./opentui": "./generated/opentui.ts",
     "./themes.css": "./generated/themes.css",
-    "./themes.json": "./generated/themes.json"
+    "./themes.json": "./generated/themes.json",
+    "./themes/*.json": "./themes/*.json"
   },
   "files": [
     "src",

package/src/generate.ts

@@ -151,40 +151,53 @@ const modeBlock = (roles: Roles, dark: boolean, indent = "  ") =>
     declarations({ ...colorProperties(roles), ...shadows(dark) }, indent),
   ].join("\n");
 
-/** One theme's `--gw-*` rules under `[data-gw-theme]`, in each of its modes. */
-export const themeCss = (theme: ResolvedTheme) => {
+/**
+ * A rule under `theme`'s selector for each of its modes, matching how
+ * `data-gw-mode` and the system's scheme pick one. `block` writes a mode's
+ * declarations at the indent it's given.
+ */
+export const modeRules = (
+  theme: ResolvedTheme,
+  block: (roles: Roles, dark: boolean, indent: string) => string,
+) => {
   const selector = `[data-gw-theme="${theme.id}"]`;
-  const style = `${selector} {\n${declarations(styleProperties(theme.style))}\n}`;
   const { light, dark, darker } = theme.modes;
-  const blocks = [style];
+  const rules: string[] = [];
 
   if (light !== undefined) {
-    blocks.push(`${selector} {\n${modeBlock(light, false)}\n}`);
+    rules.push(`${selector} {\n${block(light, false, "  ")}\n}`);
   } else if (dark !== undefined) {
-    blocks.push(`${selector} {\n${modeBlock(dark, true)}\n}`);
+    rules.push(`${selector} {\n${block(dark, true, "  ")}\n}`);
   }
 
   if (dark !== undefined) {
-    blocks.push(
-      `${selector}[data-gw-mode="dark"] {\n${modeBlock(dark, true)}\n}`,
+    rules.push(
+      `${selector}[data-gw-mode="dark"] {\n${block(dark, true, "  ")}\n}`,
     );
 
     if (light !== undefined) {
-      blocks.push(
-        `@media (prefers-color-scheme: dark) {\n  ${selector}:not([data-gw-mode]) {\n${modeBlock(dark, true, "    ")}\n  }\n}`,
+      rules.push(
+        `@media (prefers-color-scheme: dark) {\n  ${selector}:not([data-gw-mode]) {\n${block(dark, true, "    ")}\n  }\n}`,
       );
     }
   }
 
   if (darker !== undefined) {
-    blocks.push(
-      `${selector}[data-gw-mode="darker"] {\n${modeBlock(darker, true)}\n}`,
+    rules.push(
+      `${selector}[data-gw-mode="darker"] {\n${block(darker, true, "  ")}\n}`,
     );
   }
 
-  return blocks.join("\n\n");
+  return rules;
 };
 
+/** One theme's `--gw-*` rules under `[data-gw-theme]`, in each of its modes. */
+export const themeCss = (theme: ResolvedTheme) =>
+  [
+    `[data-gw-theme="${theme.id}"] {\n${declarations(styleProperties(theme.style))}\n}`,
+    ...modeRules(theme, modeBlock),
+  ].join("\n\n");
+
 /**
  * What each `gw-` element looks like before its script defines it: the
  * display and block size it will have, so nothing moves when it upgrades.

package/src/index.ts

@@ -9,3 +9,5 @@ export * from "./color.ts";
 export * from "./schema.ts";
 
 export * from "./solve.ts";
+
+export * from "./tones.ts";

package/src/page.ts

@@ -79,6 +79,12 @@ export interface PageThemeOptions {
   readonly defaultMode?: ThemeMode;
   /** The element the attributes go on. Defaults to `<html>`. */
   readonly root?: HTMLElement;
+  /**
+   * The app's own tones, solved into an imported theme's CSS beside its
+   * roles. The built-in themes' tones come from `appTones` in the runtime
+   * entry, on the page with their CSS.
+   */
+  readonly tones?: Readonly<Record<string, string>>;
 }
 
 export interface PageTheme {
@@ -210,12 +216,17 @@ export const pageTheme = (options: PageThemeOptions): PageTheme => {
 
   /** 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 { appTonesCss, runtimeTheme } = await import("./runtime.ts");
     const runtime = runtimeTheme(document, customThemeId);
 
-    setStyle(runtime.css);
+    const css =
+      options.tones === undefined
+        ? runtime.css
+        : `${runtime.css}\n\n${appTonesCss(options.tones, runtime.theme)}`;
+
+    setStyle(css);
     write(stored.document, text);
-    write(stored.css, runtime.css);
+    write(stored.css, css);
     write(stored.name, document.name);
     write(stored.theme, customThemeId);
     commit({ ...state, theme: customThemeId, custom: document.name });

package/src/runtime.ts

@@ -10,9 +10,12 @@ import baseDocument from "../themes/base.json" with { type: "json" };
 import { themeCss } from "./generate.ts";
 import { SolvedTheme, Theme } from "./schema.ts";
 import { check, resolve, type Check, type ResolvedTheme } from "./solve.ts";
+import { appTonesCss, type AppTones } from "./tones.ts";
 
 export { omarchyTheme } from "./omarchy.ts";
 
+export { appTonesCss, type AppTones } from "./tones.ts";
+
 const base = Schema.decodeUnknownSync(SolvedTheme)(baseDocument);
 
 /** A theme solved at runtime, with its CSS and every contrast check. */
@@ -37,6 +40,21 @@ export const runtimeTheme = (theme: Theme, id = theme.id): RuntimeTheme => {
   return { theme: resolved, css: themeCss(resolved), checks: check(resolved) };
 };
 
+/**
+ * An app's own tones as CSS for each of `themes`: `--app-tone-<name>`,
+ * `-fill` and `-border`, solved against each theme's surfaces in every mode
+ * so they meet the status colors' contrast. Put it beside the themes' CSS,
+ * such as at build time, then point a component's tone at one:
+ *
+ * ```css
+ * .regressed { --gw-tone: var(--app-tone-regressed); }
+ * ```
+ */
+export const appTones = (tones: AppTones, themes: readonly Theme[]) =>
+  themes
+    .map((theme) => appTonesCss(tones, resolve(theme, base.style)))
+    .join("\n\n");
+
 /**
  * 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

package/src/tones.ts

@@ -0,0 +1,87 @@
+/**
+ * App tones: an app's own state colors, such as an issue's "regressed" or
+ * "muted", solved against each theme's surfaces the way the status colors
+ * are, so they read in every theme and mode.
+ *
+ * @module
+ */
+import {
+  contrast,
+  fromHex,
+  solveLightness,
+  toCss,
+  withAlpha,
+  type Oklch,
+} from "./color.ts";
+import { modeRules } from "./generate.ts";
+import { targets, type ResolvedTheme, type Roles } from "./solve.ts";
+
+/** An app's tones: each name and the hex color it starts from. */
+export type AppTones = Readonly<Record<string, string>>;
+
+const textSurfaces = [
+  "surface-lower",
+  "surface-low",
+  "surface-default",
+  "surface-raised",
+  "surface-overlay",
+] as const;
+
+/**
+ * Each tone in one mode: its text color, kept as given where it already meets
+ * the status contrast target on every surface and moved lighter or darker
+ * until it does where not, with a quiet fill and a border from it.
+ */
+export const appToneRoles = (
+  tones: AppTones,
+  roles: Roles,
+  dark: boolean,
+): Roles =>
+  Object.fromEntries(
+    Object.entries(tones).flatMap(([name, hex]) => {
+      const seed = fromHex(hex);
+
+      const surfaces = textSurfaces.flatMap((surface) => {
+        const color = roles[surface];
+
+        return color === undefined ? [] : [color];
+      });
+
+      // Where the tone reads worst
+      const ground = surfaces.reduce<Oklch | undefined>(
+        (worst, surface) =>
+          worst === undefined || contrast(seed, surface) < contrast(seed, worst)
+            ? surface
+            : worst,
+        undefined,
+      );
+
+      const text =
+        ground === undefined || contrast(seed, ground) >= targets.status
+          ? seed
+          : solveLightness(
+              seed,
+              ground,
+              targets.status,
+              dark ? "lighter" : "darker",
+            );
+
+      return [
+        [name, text],
+        [`${name}-fill`, withAlpha(text, 0.14)],
+        [`${name}-border`, withAlpha(text, 0.45)],
+      ];
+    }),
+  );
+
+/**
+ * `--app-tone-<name>`, `-fill` and `-border` for each tone, under the same
+ * selectors as `theme`'s own CSS. Set a component's `--gw-tone`,
+ * `--gw-tone-fill` and `--gw-tone-border` from them.
+ */
+export const appTonesCss = (tones: AppTones, theme: ResolvedTheme) =>
+  modeRules(theme, (roles, dark, indent) =>
+    Object.entries(appToneRoles(tones, roles, dark))
+      .map(([name, color]) => `${indent}--app-tone-${name}: ${toCss(color)};`)
+      .join("\n"),
+  ).join("\n\n");