@tokens-studio/tokenscript-schemas 0.0.11 → 0.0.13

package/src/schemas/functions/apca_contrast/unit.test.ts

@@ -0,0 +1,259 @@
+import { executeWithSchema } from "@tests/helpers/schema-test-utils";
+import Color from "colorjs.io";
+import { describe, expect, it } from "vitest";
+
+describe("APCA Contrast Function", () => {
+  describe("Schema Definition", () => {
+    it("should have correct schema structure", async () => {
+      const { getBundledSchema } = await import("@tests/helpers/schema-test-utils");
+      const schema = await getBundledSchema("apca_contrast", "function");
+
+      expect(schema.name).toBe("APCA Contrast");
+      expect(schema.type).toBe("function");
+      expect((schema as any).keyword).toBe("apca_contrast");
+    });
+  });
+
+  describe("Basic Contrast Calculations", () => {
+    it("should return high positive contrast for black text on white background", async () => {
+      // Black text on white background = dark on light = POSITIVE Lc
+      const result = await executeWithSchema(
+        "apca_contrast",
+        "function",
+        `
+        variable text: Color.SRGB;
+        text.r = 0; text.g = 0; text.b = 0;
+        variable bg: Color.SRGB;
+        bg.r = 1; bg.g = 1; bg.b = 1;
+        apca_contrast(text, bg)
+        `,
+      );
+
+      expect(typeof result.value).toBe("number");
+      expect(result.value).toBeGreaterThan(100); // Should be around +106
+    });
+
+    it("should return high negative contrast for white text on black background", async () => {
+      // White text on black background = light on dark = NEGATIVE Lc
+      const result = await executeWithSchema(
+        "apca_contrast",
+        "function",
+        `
+        variable text: Color.SRGB;
+        text.r = 1; text.g = 1; text.b = 1;
+        variable bg: Color.SRGB;
+        bg.r = 0; bg.g = 0; bg.b = 0;
+        apca_contrast(text, bg)
+        `,
+      );
+
+      expect(typeof result.value).toBe("number");
+      expect(result.value).toBeLessThan(-100); // Should be around -108
+    });
+
+    it("should return zero contrast for identical colors", async () => {
+      const result = await executeWithSchema(
+        "apca_contrast",
+        "function",
+        `
+        variable text: Color.SRGB;
+        text.r = 0.5; text.g = 0.5; text.b = 0.5;
+        variable bg: Color.SRGB;
+        bg.r = 0.5; bg.g = 0.5; bg.b = 0.5;
+        apca_contrast(text, bg)
+        `,
+      );
+
+      expect(result.value).toBeCloseTo(0, 1);
+    });
+  });
+
+  describe("Polarity (BoW vs WoB)", () => {
+    it("should return positive for dark text on light background", async () => {
+      // Dark on light = POSITIVE (per APCA spec)
+      const result = await executeWithSchema(
+        "apca_contrast",
+        "function",
+        `
+        variable text: Color.SRGB;
+        text.r = 0.2; text.g = 0.2; text.b = 0.2;
+        variable bg: Color.SRGB;
+        bg.r = 0.9; bg.g = 0.9; bg.b = 0.9;
+        apca_contrast(text, bg)
+        `,
+      );
+
+      expect(result.value).toBeGreaterThan(0);
+    });
+
+    it("should return negative for light text on dark background", async () => {
+      // Light on dark = NEGATIVE (per APCA spec)
+      const result = await executeWithSchema(
+        "apca_contrast",
+        "function",
+        `
+        variable text: Color.SRGB;
+        text.r = 0.9; text.g = 0.9; text.b = 0.9;
+        variable bg: Color.SRGB;
+        bg.r = 0.2; bg.g = 0.2; bg.b = 0.2;
+        apca_contrast(text, bg)
+        `,
+      );
+
+      expect(result.value).toBeLessThan(0);
+    });
+  });
+
+  describe("Color.js Parity", () => {
+    // Note: In Color.js, colorObj.contrast(other, "APCA") treats:
+    //   - colorObj as BACKGROUND
+    //   - other as FOREGROUND (text)
+    // Our apca_contrast(text, bg) uses opposite order:
+    //   - text as FOREGROUND
+    //   - bg as BACKGROUND
+    // So apca_contrast(A, B) should match B.contrast(A, "APCA")
+
+    it("should match Color.js APCA for black text on white background", async () => {
+      const result = await executeWithSchema(
+        "apca_contrast",
+        "function",
+        `
+        variable text: Color.SRGB;
+        text.r = 0; text.g = 0; text.b = 0;
+        variable bg: Color.SRGB;
+        bg.r = 1; bg.g = 1; bg.b = 1;
+        apca_contrast(text, bg)
+        `,
+      );
+
+      // apca_contrast(black, white) = black text on white bg
+      // In Color.js: white.contrast(black, "APCA") = black fg on white bg
+      const white = new Color("srgb", [1, 1, 1]);
+      const black = new Color("srgb", [0, 0, 0]);
+      const colorJsApca = white.contrast(black, "APCA");
+
+      expect(result.value).toBeCloseTo(colorJsApca, 0);
+    });
+
+    it("should match Color.js APCA for white text on black background", async () => {
+      const result = await executeWithSchema(
+        "apca_contrast",
+        "function",
+        `
+        variable text: Color.SRGB;
+        text.r = 1; text.g = 1; text.b = 1;
+        variable bg: Color.SRGB;
+        bg.r = 0; bg.g = 0; bg.b = 0;
+        apca_contrast(text, bg)
+        `,
+      );
+
+      // apca_contrast(white, black) = white text on black bg
+      // In Color.js: black.contrast(white, "APCA") = white fg on black bg
+      const white = new Color("srgb", [1, 1, 1]);
+      const black = new Color("srgb", [0, 0, 0]);
+      const colorJsApca = black.contrast(white, "APCA");
+
+      expect(result.value).toBeCloseTo(colorJsApca, 0);
+    });
+
+    it("should match Color.js APCA for blue text on light gray", async () => {
+      const result = await executeWithSchema(
+        "apca_contrast",
+        "function",
+        `
+        variable text: Color.SRGB;
+        text.r = 0.2; text.g = 0.4; text.b = 0.8;
+        variable bg: Color.SRGB;
+        bg.r = 0.95; bg.g = 0.95; bg.b = 0.95;
+        apca_contrast(text, bg)
+        `,
+      );
+
+      // apca_contrast(blue, lightGray) = blue text on lightGray bg
+      // In Color.js: lightGray.contrast(blue, "APCA")
+      const blue = new Color("srgb", [0.2, 0.4, 0.8]);
+      const lightGray = new Color("srgb", [0.95, 0.95, 0.95]);
+      const colorJsApca = lightGray.contrast(blue, "APCA");
+
+      expect(result.value).toBeCloseTo(colorJsApca, 0);
+    });
+
+    it("should match Color.js APCA for mid-contrast scenario", async () => {
+      const result = await executeWithSchema(
+        "apca_contrast",
+        "function",
+        `
+        variable text: Color.SRGB;
+        text.r = 0.4; text.g = 0.4; text.b = 0.4;
+        variable bg: Color.SRGB;
+        bg.r = 0.8; bg.g = 0.8; bg.b = 0.8;
+        apca_contrast(text, bg)
+        `,
+      );
+
+      const darkGray = new Color("srgb", [0.4, 0.4, 0.4]);
+      const lightGray = new Color("srgb", [0.8, 0.8, 0.8]);
+      // darkGray text on lightGray bg → lightGray.contrast(darkGray)
+      const colorJsApca = lightGray.contrast(darkGray, "APCA");
+
+      expect(result.value).toBeCloseTo(colorJsApca, 0);
+    });
+  });
+
+  describe("WCAG 3.0 Threshold Guidelines", () => {
+    it("should meet body text threshold (|Lc| >= 60) for dark gray on white", async () => {
+      const result = await executeWithSchema(
+        "apca_contrast",
+        "function",
+        `
+        variable text: Color.SRGB;
+        text.r = 0.3; text.g = 0.3; text.b = 0.3;
+        variable bg: Color.SRGB;
+        bg.r = 1; bg.g = 1; bg.b = 1;
+        apca_contrast(text, bg)
+        `,
+      );
+
+      // Dark gray on white should be positive and meet body text requirements
+      expect(result.value).toBeGreaterThan(60);
+    });
+  });
+
+  describe("Edge Cases", () => {
+    it("should handle very dark colors (soft black clamp)", async () => {
+      const result = await executeWithSchema(
+        "apca_contrast",
+        "function",
+        `
+        variable text: Color.SRGB;
+        text.r = 0.01; text.g = 0.01; text.b = 0.01;
+        variable bg: Color.SRGB;
+        bg.r = 0.02; bg.g = 0.02; bg.b = 0.02;
+        apca_contrast(text, bg)
+        `,
+      );
+
+      // Very dark colors should still produce a valid result
+      expect(typeof result.value).toBe("number");
+      expect(Number.isFinite(result.value)).toBe(true);
+    });
+
+    it("should work with chromatic colors", async () => {
+      const result = await executeWithSchema(
+        "apca_contrast",
+        "function",
+        `
+        variable text: Color.SRGB;
+        text.r = 0.8; text.g = 0.2; text.b = 0.2;
+        variable bg: Color.SRGB;
+        bg.r = 0.2; bg.g = 0.6; bg.b = 0.2;
+        apca_contrast(text, bg)
+        `,
+      );
+
+      expect(typeof result.value).toBe("number");
+      expect(Number.isFinite(result.value)).toBe(true);
+    });
+  });
+});

package/src/schemas/functions/are_similar/are-similar.tokenscript

@@ -0,0 +1,24 @@
+// are_similar: Check if two colors are perceptually similar
+// Uses Delta E OK (OKLab Euclidean distance) for perceptual comparison
+// Default threshold 0.02 approximates "just noticeable difference"
+
+variable input: List = {input};
+variable color1: Color.OKLab = input.get(0).to.oklab();
+variable color2: Color.OKLab = input.get(1).to.oklab();
+
+// Default threshold for JND (just noticeable difference)
+variable threshold: Number = 0.02;
+if (input.length() > 2) [
+    threshold = input.get(2);
+];
+
+// Calculate Delta E OK (Euclidean distance in OKLab)
+variable delta_l: Number = color1.l - color2.l;
+variable delta_a: Number = color1.a - color2.a;
+variable delta_b: Number = color1.b - color2.b;
+
+variable delta_e: Number = sqrt(delta_l * delta_l + delta_a * delta_a + delta_b * delta_b);
+
+// Return true if within threshold
+return delta_e <= threshold;
+

package/src/schemas/functions/are_similar/schema.json

@@ -0,0 +1,57 @@
+{
+  "name": "are_similar",
+  "type": "function",
+  "description": "Determines if two colors are perceptually similar using Delta E OK (Euclidean distance in OKLab space). Returns true if the colors are within the specified threshold. Default threshold of 0.02 corresponds to a 'just noticeable difference' (JND). Based on Björn Ottosson's OKLab color space which provides excellent perceptual uniformity.",
+  "keyword": "are_similar",
+  "requirements": ["/api/v1/core/srgb-color/0/", "/api/v1/core/oklab-color/0/"],
+  "schema": {
+    "type": "object",
+    "properties": {
+      "input": {
+        "type": "array",
+        "items": [
+          {
+            "description": "First color",
+            "type": "color"
+          },
+          {
+            "description": "Second color",
+            "type": "color"
+          },
+          {
+            "description": "Delta E threshold (default 0.02 ≈ JND)",
+            "type": "number"
+          }
+        ],
+        "minItems": 2,
+        "maxItems": 3
+      }
+    },
+    "required": ["input"]
+  },
+  "returns": {
+    "type": "boolean",
+    "description": "True if colors are perceptually similar (within threshold)"
+  },
+  "script": {
+    "type": "https://schema.tokenscript.dev.gcp.tokens.studio/api/v1/core/tokenscript/0/",
+    "script": "./are-similar.tokenscript"
+  },
+  "examples": [
+    {
+      "description": "Nearly identical colors",
+      "input": ["#ff0000", "#ff0001"],
+      "output": true
+    },
+    {
+      "description": "Obviously different colors",
+      "input": ["#ff0000", "#00ff00"],
+      "output": false
+    },
+    {
+      "description": "Custom threshold for stricter comparison",
+      "input": ["#808080", "#818181", 0.01],
+      "output": true
+    }
+  ]
+}

package/src/schemas/functions/are_similar/unit.test.ts

@@ -0,0 +1,57 @@
+/**
+ * Unit tests for the are_similar function
+ * Checks if two colors are perceptually similar
+ */
+
+import { executeWithSchema, getBundledSchema } from "@tests/helpers/schema-test-utils";
+import { describe, expect, it } from "vitest";
+import type { FunctionSpecification } from "@/bundler/types";
+
+describe("are_similar function", () => {
+  describe("Schema Definition", () => {
+    it("should have correct schema structure", async () => {
+      const schema = (await getBundledSchema("are_similar", "function")) as FunctionSpecification;
+
+      expect(schema.name).toBe("are_similar");
+      expect(schema.type).toBe("function");
+    });
+  });
+
+  describe("Function Execution", () => {
+    it("should return true for identical colors", async () => {
+      const result = await executeWithSchema(
+        "are_similar",
+        "function",
+        `
+        variable c1: Color.SRGB;
+        c1.r = 0.5; c1.g = 0.5; c1.b = 0.5;
+        variable c2: Color.SRGB;
+        c2.r = 0.5; c2.g = 0.5; c2.b = 0.5;
+        are_similar(c1, c2)
+        `,
+      );
+
+      expect(result).toBeDefined();
+      const similar = (result as any).value ?? result;
+      expect(similar).toBe(true);
+    });
+
+    it("should return false for obviously different colors", async () => {
+      const result = await executeWithSchema(
+        "are_similar",
+        "function",
+        `
+        variable red: Color.SRGB;
+        red.r = 1; red.g = 0; red.b = 0;
+        variable green: Color.SRGB;
+        green.r = 0; green.g = 1; green.b = 0;
+        are_similar(red, green)
+        `,
+      );
+
+      expect(result).toBeDefined();
+      const similar = (result as any).value ?? result;
+      expect(similar).toBe(false);
+    });
+  });
+});

package/src/schemas/functions/auto_text_color/auto-text-color.tokenscript

@@ -0,0 +1,41 @@
+// auto_text_color: Select black or white text for optimal contrast
+// Reference: WCAG 2.1 Relative Luminance
+// Reference: https://www.w3.org/TR/WCAG21/#dfn-relative-luminance
+//
+// Returns black (#000) or white (#fff) depending on which provides
+// better contrast against the input background color.
+//
+// Default threshold: 0.179 (geometric mean of WCAG luminance range)
+// - sqrt(1.05 * 0.05) - 0.05 ≈ 0.179
+// - Above threshold: light background → black text
+// - Below threshold: dark background → white text
+
+variable input: List = {input};
+
+// Default threshold based on WCAG luminance midpoint
+variable threshold: Number = 0.179;
+if (input.length() > 1) [
+    threshold = input.get(1);
+];
+
+// Convert to XYZ-D65 to get relative luminance (Y component)
+variable xyz: Color.XYZD65 = input.get(0).to.xyzd65();
+variable luminance: Number = xyz.y;
+
+// If luminance is above threshold, background is "light" -> use black text
+// If luminance is below threshold, background is "dark" -> use white text
+variable result: Color.SRGB;
+
+if (luminance > threshold) [
+    // Light background: return black
+    result.r = 0;
+    result.g = 0;
+    result.b = 0;
+] else [
+    // Dark background: return white
+    result.r = 1;
+    result.g = 1;
+    result.b = 1;
+];
+
+return result;

package/src/schemas/functions/auto_text_color/schema.json

@@ -0,0 +1,53 @@
+{
+  "name": "auto_text_color",
+  "type": "function",
+  "description": "Returns black or white text color for optimal contrast against a background. Uses WCAG relative luminance to determine if the background is light or dark, then returns the opposite for maximum readability. Essential for generating accessible text colors in design systems.",
+  "keyword": "auto_text_color",
+  "requirements": ["/api/v1/core/srgb-color/0/", "/api/v1/core/xyz-d65-color/0/"],
+  "schema": {
+    "type": "object",
+    "properties": {
+      "input": {
+        "type": "array",
+        "items": [
+          {
+            "description": "Background color to test",
+            "type": "color"
+          },
+          {
+            "description": "Optional threshold (0-1, default 0.179 per WCAG). Higher values bias toward white text.",
+            "type": "number"
+          }
+        ],
+        "minItems": 1,
+        "maxItems": 2
+      }
+    },
+    "required": ["input"]
+  },
+  "returns": {
+    "type": "color",
+    "description": "Either black (#000000) or white (#ffffff) for optimal contrast"
+  },
+  "script": {
+    "type": "https://schema.tokenscript.dev.gcp.tokens.studio/api/v1/core/tokenscript/0/",
+    "script": "./auto-text-color.tokenscript"
+  },
+  "examples": [
+    {
+      "description": "Dark background returns white text",
+      "input": ["#1a1a1a"],
+      "output": "#ffffff"
+    },
+    {
+      "description": "Light background returns black text",
+      "input": ["#f0f0f0"],
+      "output": "#000000"
+    },
+    {
+      "description": "Mid-tone with custom threshold",
+      "input": ["#808080", 0.5],
+      "output": "#ffffff"
+    }
+  ]
+}

package/src/schemas/functions/auto_text_color/unit.test.ts

@@ -0,0 +1,122 @@
+/**
+ * Unit tests for the auto_text_color function
+ * Returns black or white for optimal contrast against a background
+ */
+
+import { executeWithSchema, getBundledSchema } from "@tests/helpers/schema-test-utils";
+import { describe, expect, it } from "vitest";
+import type { FunctionSpecification } from "@/bundler/types";
+
+describe("auto_text_color function", () => {
+  describe("Schema Definition", () => {
+    it("should have correct schema structure", async () => {
+      const schema = (await getBundledSchema(
+        "auto_text_color",
+        "function",
+      )) as FunctionSpecification;
+
+      expect(schema.name).toBe("auto_text_color");
+      expect(schema.type).toBe("function");
+    });
+  });
+
+  describe("Function Execution", () => {
+    it("should return white text for dark backgrounds", async () => {
+      const result = await executeWithSchema(
+        "auto_text_color",
+        "function",
+        `
+        variable bg: Color.SRGB;
+        bg.r = 0.1; bg.g = 0.1; bg.b = 0.1;
+        auto_text_color(bg)
+        `,
+      );
+
+      expect(result).toBeDefined();
+      const r = (result as any).value?.r?.value ?? (result as any).value?.r;
+      expect(r).toBeCloseTo(1, 1);
+    });
+
+    it("should return black text for light backgrounds", async () => {
+      const result = await executeWithSchema(
+        "auto_text_color",
+        "function",
+        `
+        variable bg: Color.SRGB;
+        bg.r = 0.94; bg.g = 0.94; bg.b = 0.94;
+        auto_text_color(bg)
+        `,
+      );
+
+      expect(result).toBeDefined();
+      const r = (result as any).value?.r?.value ?? (result as any).value?.r;
+      expect(r).toBeCloseTo(0, 1);
+    });
+
+    it("should return black text for pure white", async () => {
+      const result = await executeWithSchema(
+        "auto_text_color",
+        "function",
+        `
+        variable bg: Color.SRGB;
+        bg.r = 1; bg.g = 1; bg.b = 1;
+        auto_text_color(bg)
+        `,
+      );
+
+      expect(result).toBeDefined();
+      const r = (result as any).value?.r?.value ?? (result as any).value?.r;
+      expect(r).toBeCloseTo(0, 1);
+    });
+
+    it("should return white text for pure black", async () => {
+      const result = await executeWithSchema(
+        "auto_text_color",
+        "function",
+        `
+        variable bg: Color.SRGB;
+        bg.r = 0; bg.g = 0; bg.b = 0;
+        auto_text_color(bg)
+        `,
+      );
+
+      expect(result).toBeDefined();
+      const r = (result as any).value?.r?.value ?? (result as any).value?.r;
+      expect(r).toBeCloseTo(1, 1);
+    });
+
+    it("should return black text for bright yellow (high luminance)", async () => {
+      const result = await executeWithSchema(
+        "auto_text_color",
+        "function",
+        `
+        variable bg: Color.SRGB;
+        bg.r = 1; bg.g = 1; bg.b = 0;
+        auto_text_color(bg)
+        `,
+      );
+
+      expect(result).toBeDefined();
+      const r = (result as any).value?.r?.value ?? (result as any).value?.r;
+      // Yellow has high luminance -> black text
+      expect(r).toBeCloseTo(0, 1);
+    });
+
+    it("should return white text for dark blue", async () => {
+      const result = await executeWithSchema(
+        "auto_text_color",
+        "function",
+        `
+        variable bg: Color.SRGB;
+        bg.r = 0; bg.g = 0.4; bg.b = 0.8;
+        auto_text_color(bg)
+        `,
+      );
+
+      expect(result).toBeDefined();
+      const r = (result as any).value?.r?.value ?? (result as any).value?.r;
+      // Blue has low luminance -> white text
+      expect(r).toBeCloseTo(1, 1);
+    });
+  });
+});

package/src/schemas/functions/best_contrast/best-contrast.tokenscript

@@ -0,0 +1,66 @@
+// Select the most contrasting color from a list of candidates
+// Uses WCAG 2.1 contrast ratio based on relative luminance
+//
+// Algorithm:
+// 1. Calculate relative luminance: L = 0.2126*R + 0.7152*G + 0.0722*B (linear RGB)
+// 2. Contrast ratio: (L_lighter + 0.05) / (L_darker + 0.05)
+// 3. Return candidate with highest contrast ratio
+//
+// Default candidates: black (#000) and white (#fff)
+
+variable input: List = {input};
+variable bg: Color.LinearSRGB = input.get(0).to.linearsrgb();
+
+// Calculate background luminance
+variable bg_lum: Number = 0.2126 * bg.r + 0.7152 * bg.g + 0.0722 * bg.b;
+
+// Get candidates list, default to black and white
+variable candidates: List;
+if (input.length() > 1) [
+    candidates = input.get(1);
+] else [
+    // Default: black and white
+    variable black: Color.SRGB;
+    black.r = 0; black.g = 0; black.b = 0;
+    variable white: Color.SRGB;
+    white.r = 1; white.g = 1; white.b = 1;
+    candidates = black, white;
+];
+
+// Find candidate with highest contrast
+variable best_color: Color.SRGB = candidates.get(0).to.srgb();
+variable best_contrast: Number = 0;
+variable candidate: Color.LinearSRGB;
+variable cand_lum: Number = 0;
+variable lighter: Number = 0;
+variable darker: Number = 0;
+variable contrast: Number = 0;
+
+variable i: Number = 0;
+while (i < candidates.length()) [
+    candidate = candidates.get(i).to.linearsrgb();
+    
+    // Calculate candidate luminance
+    cand_lum = 0.2126 * candidate.r + 0.7152 * candidate.g + 0.0722 * candidate.b;
+    
+    // Calculate contrast ratio (lighter / darker)
+    lighter = bg_lum;
+    darker = cand_lum;
+    if (cand_lum > bg_lum) [
+        lighter = cand_lum;
+        darker = bg_lum;
+    ];
+    
+    contrast = (lighter + 0.05) / (darker + 0.05);
+    
+    // Track best
+    if (contrast > best_contrast) [
+        best_contrast = contrast;
+        best_color = candidates.get(i).to.srgb();
+    ];
+    
+    i = i + 1;
+];
+
+return best_color;
+