@timmo001/groundwork-tokens 0.0.0-stage → 0.0.0

package/package.json

@@ -1,6 +1,57 @@
 {
   "name": "@timmo001/groundwork-tokens",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.0.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",
+    "./themes.css": "./generated/themes.css",
+    "./themes.json": "./generated/themes.json"
+  },
+  "files": [
+    "src",
+    "!src/cli.ts",
+    "themes",
+    "generated",
+    "README.md",
+    "LICENSE"
+  ],
+  "sideEffects": [
+    "*.css"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/timmo001/groundwork.git",
+    "directory": "packages/tokens"
+  },
+  "scripts": {
+    "check": "bun run --parallel --no-exit-on-error lint typecheck format:check",
+    "gen": "bun run src/cli.ts gen",
+    "gen:check": "bun run src/cli.ts gen --check",
+    "contrast": "bun run src/cli.ts contrast",
+    "lint": "oxlint .",
+    "typecheck": "tsc",
+    "format": "prettier --write .",
+    "format:check": "prettier --check ."
+  },
+  "dependencies": {
+    "culori": "4.0.2",
+    "effect": "4.1.1"
+  },
+  "devDependencies": {
+    "@effect/platform-node": "4.1.1",
+    "@oxlint/plugins": "1.90.0",
+    "@timmo001/oxlint-rules": "0.6.3",
+    "@types/bun": "1.4.4",
+    "@types/culori": "4.0.1",
+    "oxlint": "1.90.0",
+    "oxlint-tsgolint": "7.0.2005",
+    "prettier": "3.9.10",
+    "typescript": "7.0.2"
+  }
+}

package/src/color.ts

@@ -0,0 +1,122 @@
+/**
+ * Color math in OKLCH: parsing, gamut mapping, contrast and solving for a
+ * lightness that meets a contrast target.
+ *
+ * @module
+ */
+import {
+  converter,
+  differenceEuclidean,
+  formatHex,
+  formatHex8,
+  parse,
+  toGamut,
+  wcagContrast,
+} from "culori";
+
+/** A color in OKLCH: lightness 0 to 1, chroma, hue in degrees, and alpha. */
+export interface Oklch {
+  readonly l: number;
+  readonly c: number;
+  readonly h: number;
+  readonly alpha?: number;
+}
+
+const toOklch = converter("oklch");
+const toSrgbGamut = toGamut("rgb", "oklch");
+
+export const fromHex = (hex: string): Oklch => {
+  const color = toOklch(parse(hex));
+
+  if (color === undefined) return { l: 0, c: 0, h: 0 };
+
+  return { l: color.l, c: color.c, h: color.h ?? 0 };
+};
+
+/** Bring a color into sRGB by reducing chroma, keeping lightness and hue. */
+export const inGamut = (color: Oklch): Oklch => {
+  const mapped = toOklch(
+    toSrgbGamut({ mode: "oklch", l: color.l, c: color.c, h: color.h }),
+  );
+
+  return { ...color, c: mapped.c };
+};
+
+/** Six-digit sRGB hex, or eight digits when the color has alpha. */
+export const toHex = (color: Oklch) => {
+  const mapped = toSrgbGamut({
+    mode: "oklch",
+    l: color.l,
+    c: color.c,
+    h: color.h,
+  });
+
+  return color.alpha === undefined || color.alpha === 1
+    ? formatHex(mapped)
+    : formatHex8({ ...mapped, alpha: color.alpha });
+};
+
+const round = (value: number, places: number) => Number(value.toFixed(places));
+
+export const toCss = (color: Oklch) => {
+  const { l, c, h } = inGamut(color);
+
+  const alpha =
+    color.alpha === undefined || color.alpha === 1
+      ? ""
+      : ` / ${round(color.alpha, 2)}`;
+
+  return `oklch(${round(l * 100, 2)}% ${round(c, 4)} ${round(h, 2)}${alpha})`;
+};
+
+const oklabDistance = differenceEuclidean("oklab");
+
+/** How far apart two hex colors look, as the Euclidean distance in OKLab. */
+export const distance = (a: string, b: string) => oklabDistance(a, b);
+
+/** The WCAG 2 contrast ratio between two colors, ignoring alpha. */
+export const contrast = (a: Oklch, b: Oklch) =>
+  wcagContrast(toHex({ ...a, alpha: 1 }), toHex({ ...b, alpha: 1 }));
+
+export const withLightness = (color: Oklch, l: number): Oklch => ({
+  ...color,
+  l: Math.min(1, Math.max(0, l)),
+});
+
+export const shift = (color: Oklch, by: number): Oklch =>
+  withLightness(color, color.l + by);
+
+export const withAlpha = (color: Oklch, alpha: number): Oklch => ({
+  ...color,
+  alpha,
+});
+
+/**
+ * The lightness, moving away from `against` toward white or black, at which
+ * the color first reaches `target` contrast. Falls back to the extreme when
+ * the target can't be reached.
+ */
+export const solveLightness = (
+  color: Oklch,
+  against: Oklch,
+  target: number,
+  direction: "lighter" | "darker",
+): Oklch => {
+  let low = direction === "lighter" ? against.l : 0;
+  let high = direction === "lighter" ? 1 : against.l;
+
+  for (let step = 0; step < 32; step++) {
+    const middle = (low + high) / 2;
+
+    const passes =
+      contrast(inGamut(withLightness(color, middle)), against) >= target;
+
+    if (direction === "lighter") {
+      if (passes) high = middle;
+      else low = middle;
+    } else if (passes) low = middle;
+    else high = middle;
+  }
+
+  return inGamut(withLightness(color, direction === "lighter" ? high : low));
+};