@tokens-studio/tokenscript-schemas 0.0.11 → 0.0.13

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

@@ -0,0 +1,49 @@
+{
+  "name": "lightness",
+  "type": "function",
+  "description": "Extracts the perceptual lightness value from any color using OKLCH. Returns a value from 0 (black) to 1 (white). This is the 'L' in OKLCH, which is perceptually uniform - equal steps in L appear as equal steps in lightness to human vision. Essential for creating perceptually even color scales.",
+  "keyword": "lightness",
+  "requirements": ["/api/v1/core/srgb-color/0/", "/api/v1/core/oklch-color/0/"],
+  "schema": {
+    "type": "object",
+    "properties": {
+      "input": {
+        "type": "array",
+        "items": [
+          {
+            "description": "Color to extract lightness from",
+            "type": "color"
+          }
+        ],
+        "minItems": 1,
+        "maxItems": 1
+      }
+    },
+    "required": ["input"]
+  },
+  "returns": {
+    "type": "number",
+    "description": "Perceptual lightness value (0-1)"
+  },
+  "script": {
+    "type": "https://schema.tokenscript.dev.gcp.tokens.studio/api/v1/core/tokenscript/0/",
+    "script": "./lightness.tokenscript"
+  },
+  "examples": [
+    {
+      "description": "White has lightness 1",
+      "input": ["#ffffff"],
+      "output": 1
+    },
+    {
+      "description": "Black has lightness 0",
+      "input": ["#000000"],
+      "output": 0
+    },
+    {
+      "description": "Mid-gray has lightness ~0.6",
+      "input": ["#808080"],
+      "output": 0.6
+    }
+  ]
+}

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

@@ -0,0 +1,99 @@
+/**
+ * Unit tests for the lightness function
+ * Extracts perceptual lightness from a color
+ */
+
+import { executeWithSchema, getBundledSchema } from "@tests/helpers/schema-test-utils";
+import { describe, expect, it } from "vitest";
+import type { FunctionSpecification } from "@/bundler/types";
+
+describe("lightness function", () => {
+  describe("Schema Definition", () => {
+    it("should have correct schema structure", async () => {
+      const schema = (await getBundledSchema("lightness", "function")) as FunctionSpecification;
+
+      expect(schema.name).toBe("lightness");
+      expect(schema.type).toBe("function");
+    });
+  });
+
+  describe("Function Execution", () => {
+    it("should return 1 for white", async () => {
+      const result = await executeWithSchema(
+        "lightness",
+        "function",
+        `
+        variable white: Color.SRGB;
+        white.r = 1; white.g = 1; white.b = 1;
+        lightness(white)
+        `,
+      );
+
+      expect(result).toBeDefined();
+      const l = (result as any).value ?? result;
+      expect(l).toBeCloseTo(1, 1);
+    });
+
+    it("should return 0 for black", async () => {
+      const result = await executeWithSchema(
+        "lightness",
+        "function",
+        `
+        variable black: Color.SRGB;
+        black.r = 0; black.g = 0; black.b = 0;
+        lightness(black)
+        `,
+      );
+
+      expect(result).toBeDefined();
+      const l = (result as any).value ?? result;
+      expect(l).toBeCloseTo(0, 1);
+    });
+
+    it("should return ~0.6 for mid-gray", async () => {
+      const result = await executeWithSchema(
+        "lightness",
+        "function",
+        `
+        variable gray: Color.SRGB;
+        gray.r = 0.5; gray.g = 0.5; gray.b = 0.5;
+        lightness(gray)
+        `,
+      );
+
+      expect(result).toBeDefined();
+      const l = (result as any).value ?? result;
+      // OKLCH lightness for mid-gray is around 0.6
+      expect(l).toBeGreaterThan(0.5);
+      expect(l).toBeLessThan(0.8);
+    });
+
+    it("should show yellow is lighter than blue", async () => {
+      const yellowResult = await executeWithSchema(
+        "lightness",
+        "function",
+        `
+        variable yellow: Color.SRGB;
+        yellow.r = 1; yellow.g = 1; yellow.b = 0;
+        lightness(yellow)
+        `,
+      );
+
+      const blueResult = await executeWithSchema(
+        "lightness",
+        "function",
+        `
+        variable blue: Color.SRGB;
+        blue.r = 0; blue.g = 0; blue.b = 1;
+        lightness(blue)
+        `,
+      );
+
+      const yellowL = (yellowResult as any).value ?? yellowResult;
+      const blueL = (blueResult as any).value ?? blueResult;
+
+      // Yellow is perceptually much lighter than blue
+      expect(yellowL).toBeGreaterThan(blueL);
+    });
+  });
+});

package/src/schemas/functions/luminance/luminance.tokenscript

@@ -0,0 +1,16 @@
+// Get relative luminance of a color
+// Per WCAG 2.1: L = 0.2126*R + 0.7152*G + 0.0722*B (linear RGB)
+//
+// Returns: 0 (black) to 1 (white)
+// Used for contrast calculations
+
+variable input: List = {input};
+variable color: Color.LinearSRGB = input.get(0).to.linearsrgb();
+
+variable lum: Number = 0.2126 * color.r + 0.7152 * color.g + 0.0722 * color.b;
+
+return lum;
+
+
+
+

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

@@ -0,0 +1,20 @@
+{
+  "name": "Luminance",
+  "type": "function",
+  "description": "Returns the relative luminance of a color (0-1). Uses the WCAG formula based on linear sRGB. Useful for contrast calculations and accessibility.",
+  "keyword": "luminance",
+  "input": {
+    "type": "object",
+    "properties": {
+      "color": {
+        "type": "color",
+        "description": "The color to measure"
+      }
+    }
+  },
+  "script": {
+    "type": "/api/v1/core/tokenscript/0/",
+    "script": "./luminance.tokenscript"
+  },
+  "requirements": ["/api/v1/core/srgb-linear-color/0/"]
+}

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

@@ -0,0 +1,105 @@
+/**
+ * Unit tests for the Luminance function
+ * Returns relative luminance (0-1) of a color
+ */
+
+import { executeWithSchema, getBundledSchema } from "@tests/helpers/schema-test-utils";
+import { describe, expect, it } from "vitest";
+import type { FunctionSpecification } from "@/bundler/types";
+
+describe("Luminance Function", () => {
+  describe("Schema Definition", () => {
+    it("should have correct schema structure", async () => {
+      const schema = (await getBundledSchema("luminance", "function")) as FunctionSpecification;
+
+      expect(schema.name).toBe("Luminance");
+      expect(schema.type).toBe("function");
+      expect(schema.keyword).toBe("luminance");
+    });
+  });
+
+  describe("Function Execution", () => {
+    it("should return 1 for white", async () => {
+      const result = await executeWithSchema(
+        "luminance",
+        "function",
+        `
+        variable white: Color.SRGB;
+        white.r = 1; white.g = 1; white.b = 1;
+        luminance(white)
+        `,
+      );
+
+      expect(result).toBeDefined();
+      const lum = (result as any).value ?? result;
+      expect(lum).toBeCloseTo(1, 1);
+    });
+
+    it("should return 0 for black", async () => {
+      const result = await executeWithSchema(
+        "luminance",
+        "function",
+        `
+        variable black: Color.SRGB;
+        black.r = 0; black.g = 0; black.b = 0;
+        luminance(black)
+        `,
+      );
+
+      expect(result).toBeDefined();
+      const lum = (result as any).value ?? result;
+      expect(lum).toBeCloseTo(0, 1);
+    });
+
+    it("should return ~0.21 for pure red", async () => {
+      const result = await executeWithSchema(
+        "luminance",
+        "function",
+        `
+        variable red: Color.SRGB;
+        red.r = 1; red.g = 0; red.b = 0;
+        luminance(red)
+        `,
+      );
+
+      expect(result).toBeDefined();
+      const lum = (result as any).value ?? result;
+      // Red luminance coefficient is ~0.2126
+      expect(lum).toBeCloseTo(0.21, 1);
+    });
+
+    it("should return ~0.72 for pure green", async () => {
+      const result = await executeWithSchema(
+        "luminance",
+        "function",
+        `
+        variable green: Color.SRGB;
+        green.r = 0; green.g = 1; green.b = 0;
+        luminance(green)
+        `,
+      );
+
+      expect(result).toBeDefined();
+      const lum = (result as any).value ?? result;
+      // Green luminance coefficient is ~0.7152
+      expect(lum).toBeCloseTo(0.72, 1);
+    });
+
+    it("should return ~0.07 for pure blue", async () => {
+      const result = await executeWithSchema(
+        "luminance",
+        "function",
+        `
+        variable blue: Color.SRGB;
+        blue.r = 0; blue.g = 0; blue.b = 1;
+        luminance(blue)
+        `,
+      );
+
+      expect(result).toBeDefined();
+      const lum = (result as any).value ?? result;
+      // Blue luminance coefficient is ~0.0722
+      expect(lum).toBeCloseTo(0.07, 1);
+    });
+  });
+});

package/src/schemas/functions/meets_contrast/meets-contrast.tokenscript

@@ -0,0 +1,49 @@
+// Meets Contrast (WCAG 2.1 Compliance Check)
+// Reference: WCAG 2.1 Success Criteria 1.4.3 and 1.4.6
+// Reference: https://www.w3.org/TR/WCAG21/#contrast-minimum
+//
+// WCAG 2.1 Contrast Levels:
+//   - Level AA (normal text):  4.5:1
+//   - Level AA (large text):   3:1
+//   - Level AAA (normal text): 7:1
+//   - Level AAA (large text):  4.5:1
+//
+// Large text is defined as:
+//   - 14pt (18.66px) bold
+//   - 18pt (24px) regular
+//
+// Returns true if the contrast ratio meets or exceeds the threshold.
+
+variable input: List = {input};
+variable color1: Color.LinearSRGB = input.get(0).to.linearsrgb();
+variable color2: Color.LinearSRGB = input.get(1).to.linearsrgb();
+
+// Default threshold is 4.5 (WCAG AA for normal text)
+variable threshold: Number = 4.5;
+if (input.length() > 2) [
+    threshold = input.get(2);
+];
+
+// Calculate relative luminance for each color
+// Formula: L = 0.2126 * R + 0.7152 * G + 0.0722 * B
+variable lum1: Number = 0.2126 * color1.r + 0.7152 * color1.g + 0.0722 * color1.b;
+variable lum2: Number = 0.2126 * color2.r + 0.7152 * color2.g + 0.0722 * color2.b;
+
+// Ensure non-negative luminance
+if (lum1 < 0) [ lum1 = 0; ];
+if (lum2 < 0) [ lum2 = 0; ];
+
+// Determine lighter and darker luminance
+variable lighter: Number = lum1;
+variable darker: Number = lum2;
+if (lum2 > lum1) [
+    lighter = lum2;
+    darker = lum1;
+];
+
+// Calculate contrast ratio: (L1 + 0.05) / (L2 + 0.05)
+variable ratio: Number = (lighter + 0.05) / (darker + 0.05);
+
+// Return whether it meets the threshold
+return ratio >= threshold;
+

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

@@ -0,0 +1,28 @@
+{
+  "name": "Meets Contrast",
+  "type": "function",
+  "description": "Checks if two colors meet WCAG 2.1 contrast requirements. Returns true if contrast ratio meets the specified level: 'AA' (4.5:1 for normal text, 3:1 for large text), 'AAA' (7:1 for normal text, 4.5:1 for large text), or a custom ratio.",
+  "keyword": "meets_contrast",
+  "input": {
+    "type": "object",
+    "properties": {
+      "color1": {
+        "type": "color",
+        "description": "First color"
+      },
+      "color2": {
+        "type": "color",
+        "description": "Second color"
+      },
+      "threshold": {
+        "type": "number",
+        "description": "Minimum contrast ratio required (default: 4.5 for AA)"
+      }
+    }
+  },
+  "script": {
+    "type": "/api/v1/core/tokenscript/0/",
+    "script": "./meets-contrast.tokenscript"
+  },
+  "requirements": ["/api/v1/core/srgb-linear-color/0/"]
+}

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

@@ -0,0 +1,170 @@
+import { executeWithSchema } from "@tests/helpers/schema-test-utils";
+import { describe, expect, it } from "vitest";
+
+describe("Meets 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("meets_contrast", "function");
+
+      expect(schema.name).toBe("Meets Contrast");
+      expect(schema.type).toBe("function");
+      expect((schema as any).keyword).toBe("meets_contrast");
+    });
+  });
+
+  describe("Black and White (Maximum Contrast)", () => {
+    it("should return true for black/white at AA threshold", async () => {
+      const result = await executeWithSchema(
+        "meets_contrast",
+        "function",
+        `
+        variable c1: Color.SRGB;
+        c1.r = 0; c1.g = 0; c1.b = 0;
+        variable c2: Color.SRGB;
+        c2.r = 1; c2.g = 1; c2.b = 1;
+        meets_contrast(c1, c2, 4.5)
+        `,
+      );
+
+      expect(result.value).toBe(true);
+    });
+
+    it("should return true for black/white at AAA threshold", async () => {
+      const result = await executeWithSchema(
+        "meets_contrast",
+        "function",
+        `
+        variable c1: Color.SRGB;
+        c1.r = 0; c1.g = 0; c1.b = 0;
+        variable c2: Color.SRGB;
+        c2.r = 1; c2.g = 1; c2.b = 1;
+        meets_contrast(c1, c2, 7)
+        `,
+      );
+
+      expect(result.value).toBe(true);
+    });
+  });
+
+  describe("Identical Colors (No Contrast)", () => {
+    it("should return false for identical colors", async () => {
+      const result = await executeWithSchema(
+        "meets_contrast",
+        "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;
+        meets_contrast(c1, c2, 4.5)
+        `,
+      );
+
+      expect(result.value).toBe(false);
+    });
+  });
+
+  describe("AA Threshold (4.5:1)", () => {
+    it("should return true for good contrast (dark gray on white)", async () => {
+      // Dark gray (#595959) on white should meet AA
+      const result = await executeWithSchema(
+        "meets_contrast",
+        "function",
+        `
+        variable c1: Color.SRGB;
+        c1.r = 0.35; c1.g = 0.35; c1.b = 0.35;
+        variable c2: Color.SRGB;
+        c2.r = 1; c2.g = 1; c2.b = 1;
+        meets_contrast(c1, c2, 4.5)
+        `,
+      );
+
+      expect(result.value).toBe(true);
+    });
+
+    it("should return false for poor contrast (light gray on white)", async () => {
+      // Light gray on white fails AA
+      const result = await executeWithSchema(
+        "meets_contrast",
+        "function",
+        `
+        variable c1: Color.SRGB;
+        c1.r = 0.75; c1.g = 0.75; c1.b = 0.75;
+        variable c2: Color.SRGB;
+        c2.r = 1; c2.g = 1; c2.b = 1;
+        meets_contrast(c1, c2, 4.5)
+        `,
+      );
+
+      expect(result.value).toBe(false);
+    });
+  });
+
+  describe("Large Text AA Threshold (3:1)", () => {
+    it("should return true for moderate contrast at 3:1 threshold", async () => {
+      const result = await executeWithSchema(
+        "meets_contrast",
+        "function",
+        `
+        variable c1: Color.SRGB;
+        c1.r = 0.45; c1.g = 0.45; c1.b = 0.45;
+        variable c2: Color.SRGB;
+        c2.r = 1; c2.g = 1; c2.b = 1;
+        meets_contrast(c1, c2, 3)
+        `,
+      );
+
+      expect(result.value).toBe(true);
+    });
+  });
+
+  describe("Default Threshold", () => {
+    it("should use 4.5 as default threshold", async () => {
+      // Dark gray on white should meet default AA (4.5:1)
+      const result = await executeWithSchema(
+        "meets_contrast",
+        "function",
+        `
+        variable c1: Color.SRGB;
+        c1.r = 0.3; c1.g = 0.3; c1.b = 0.3;
+        variable c2: Color.SRGB;
+        c2.r = 1; c2.g = 1; c2.b = 1;
+        meets_contrast(c1, c2)
+        `,
+      );
+
+      expect(result.value).toBe(true);
+    });
+  });
+
+  describe("Order Independence", () => {
+    it("should give same result regardless of color order", async () => {
+      const result1 = await executeWithSchema(
+        "meets_contrast",
+        "function",
+        `
+        variable c1: Color.SRGB;
+        c1.r = 0.2; c1.g = 0.2; c1.b = 0.2;
+        variable c2: Color.SRGB;
+        c2.r = 0.9; c2.g = 0.9; c2.b = 0.9;
+        meets_contrast(c1, c2, 4.5)
+        `,
+      );
+
+      const result2 = await executeWithSchema(
+        "meets_contrast",
+        "function",
+        `
+        variable c1: Color.SRGB;
+        c1.r = 0.9; c1.g = 0.9; c1.b = 0.9;
+        variable c2: Color.SRGB;
+        c2.r = 0.2; c2.g = 0.2; c2.b = 0.2;
+        meets_contrast(c1, c2, 4.5)
+        `,
+      );
+
+      expect(result1.value).toBe(result2.value);
+    });
+  });
+});

package/src/schemas/functions/mix/mix.tokenscript

@@ -0,0 +1,47 @@
+// mix: Blend two colors in perceptual space
+// Uses shortest hue path for natural color blending.
+//
+// Algorithm: Linear interpolation on L, C, and shortest-path H
+//
+// Input:  Any color space (converted to OKLCH internally)
+// Output: OKLCH (working space)
+// To get sRGB: mix(color1, color2, 0.5).to.srgb()
+
+variable input: List = {input};
+variable color1: Color.OKLCH = input.get(0).to.oklch();
+variable color2: Color.OKLCH = input.get(1).to.oklch();
+
+// Default amount is 0.5 (50/50 blend)
+variable amount: Number = 0.5;
+if (input.length() > 2) [
+    amount = input.get(2);
+];
+
+// Interpolate lightness and chroma linearly
+variable new_l: Number = color1.l + (color2.l - color1.l) * amount;
+variable new_c: Number = color1.c + (color2.c - color1.c) * amount;
+
+// Interpolate hue using shortest path
+variable h1: Number = color1.h;
+variable h2: Number = color2.h;
+variable h_diff: Number = h2 - h1;
+
+// Normalize to shortest path (-180 to 180)
+if (h_diff > 180) [ h_diff = h_diff - 360; ];
+if (h_diff < -180) [ h_diff = h_diff + 360; ];
+
+variable new_h: Number = h1 + h_diff * amount;
+if (new_h < 0) [ new_h = new_h + 360; ];
+if (new_h >= 360) [ new_h = new_h - 360; ];
+
+// Create mixed color
+variable result: Color.OKLCH;
+result.l = new_l;
+result.c = new_c;
+result.h = new_h;
+
+return result;
+
+
+
+

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

@@ -0,0 +1,28 @@
+{
+  "name": "Mix",
+  "type": "function",
+  "description": "Blends two colors together in OKLCH space. Amount 0 = first color, 1 = second color, 0.5 = equal blend.",
+  "keyword": "mix",
+  "input": {
+    "type": "object",
+    "properties": {
+      "color1": {
+        "type": "color",
+        "description": "First color"
+      },
+      "color2": {
+        "type": "color",
+        "description": "Second color"
+      },
+      "amount": {
+        "type": "number",
+        "description": "Blend amount (0-1). Default is 0.5"
+      }
+    }
+  },
+  "script": {
+    "type": "/api/v1/core/tokenscript/0/",
+    "script": "./mix.tokenscript"
+  },
+  "requirements": ["/api/v1/core/oklch-color/0/", "/api/v1/core/srgb-color/0/"]
+}