@tokens-studio/tokenscript-schemas 0.0.11 → 0.0.13

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

@@ -0,0 +1,49 @@
+{
+  "name": "relative_luminance",
+  "type": "function",
+  "description": "Returns the WCAG 2.1 relative luminance of a color. This is the Y value from the XYZ-D65 color space, ranging from 0 (black) to 1 (white). Used in contrast ratio calculations. Different from perceptual lightness - relative luminance is weighted toward green (which human eyes are most sensitive to). Essential for WCAG accessibility calculations.",
+  "keyword": "relative_luminance",
+  "requirements": ["/api/v1/core/srgb-color/0/", "/api/v1/core/xyz-d65-color/0/"],
+  "schema": {
+    "type": "object",
+    "properties": {
+      "input": {
+        "type": "array",
+        "items": [
+          {
+            "description": "Color to measure",
+            "type": "color"
+          }
+        ],
+        "minItems": 1,
+        "maxItems": 1
+      }
+    },
+    "required": ["input"]
+  },
+  "returns": {
+    "type": "number",
+    "description": "Relative luminance (0-1)"
+  },
+  "script": {
+    "type": "https://schema.tokenscript.dev.gcp.tokens.studio/api/v1/core/tokenscript/0/",
+    "script": "./relative-luminance.tokenscript"
+  },
+  "examples": [
+    {
+      "description": "White has luminance 1",
+      "input": ["#ffffff"],
+      "output": 1
+    },
+    {
+      "description": "Black has luminance 0",
+      "input": ["#000000"],
+      "output": 0
+    },
+    {
+      "description": "Pure green is brighter than pure blue",
+      "input": ["#00ff00"],
+      "output": 0.7152
+    }
+  ]
+}

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

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

package/src/schemas/functions/rotate_hue/rotate-hue.tokenscript

@@ -0,0 +1,20 @@
+// Rotate a color's hue by specified degrees
+// Preserves lightness and chroma
+
+variable input: List = {input};
+variable color: Color.OKLCH = input.get(0).to.oklch();
+variable degrees: Number = input.get(1);
+
+variable new_h: Number = color.h + degrees;
+
+// Normalize to 0-360
+while (new_h >= 360) [ new_h = new_h - 360; ];
+while (new_h < 0) [ new_h = new_h + 360; ];
+
+variable result: Color.OKLCH;
+result.l = color.l;
+result.c = color.c;
+result.h = new_h;
+
+return result;
+

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

@@ -0,0 +1,24 @@
+{
+  "name": "Rotate Hue",
+  "type": "function",
+  "description": "Rotates a color's hue by a specified number of degrees in OKLCH space. Positive values rotate clockwise, negative counterclockwise.",
+  "keyword": "rotate_hue",
+  "input": {
+    "type": "object",
+    "properties": {
+      "color": {
+        "type": "color",
+        "description": "The color to rotate"
+      },
+      "degrees": {
+        "type": "number",
+        "description": "Degrees to rotate (-360 to 360)"
+      }
+    }
+  },
+  "script": {
+    "type": "/api/v1/core/tokenscript/0/",
+    "script": "./rotate-hue.tokenscript"
+  },
+  "requirements": ["/api/v1/core/oklch-color/0/", "/api/v1/core/srgb-color/0/"]
+}

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

@@ -0,0 +1,86 @@
+/**
+ * Unit tests for the Rotate Hue function
+ * Rotates a color's hue by specified degrees in OKLCH
+ */
+
+import { executeWithSchema, getBundledSchema } from "@tests/helpers/schema-test-utils";
+import { describe, expect, it } from "vitest";
+import type { FunctionSpecification } from "@/bundler/types";
+
+describe("Rotate Hue Function", () => {
+  describe("Schema Definition", () => {
+    it("should have correct schema structure", async () => {
+      const schema = (await getBundledSchema("rotate_hue", "function")) as FunctionSpecification;
+
+      expect(schema.name).toBe("Rotate Hue");
+      expect(schema.type).toBe("function");
+      expect(schema.keyword).toBe("rotate_hue");
+    });
+  });
+
+  describe("Function Execution", () => {
+    it("should rotate hue by specified degrees", async () => {
+      const result = await executeWithSchema(
+        "rotate_hue",
+        "function",
+        `
+        variable red: Color.SRGB;
+        red.r = 0.9; red.g = 0.2; red.b = 0.2;
+        rotate_hue(red, 120).to.srgb()
+        `,
+      );
+
+      expect(result?.constructor.name).toBe("ColorSymbol");
+      // Red rotated 120° should be more green-ish
+      const r = (result as any).value.r.value;
+      const g = (result as any).value.g.value;
+      expect(g).toBeGreaterThan(r);
+    });
+
+    it("should handle 360° rotation (return to original)", async () => {
+      const result = await executeWithSchema(
+        "rotate_hue",
+        "function",
+        `
+        variable blue: Color.SRGB;
+        blue.r = 0.2; blue.g = 0.3; blue.b = 0.9;
+        rotate_hue(blue, 360).to.srgb()
+        `,
+      );
+
+      expect(result?.constructor.name).toBe("ColorSymbol");
+      const r = (result as any).value.r.value;
+      const b = (result as any).value.b.value;
+      // Should still be blue-ish after full rotation
+      expect(b).toBeGreaterThan(r);
+    });
+
+    it("should handle negative rotation", async () => {
+      const result = await executeWithSchema(
+        "rotate_hue",
+        "function",
+        `
+        variable green: Color.SRGB;
+        green.r = 0.2; green.g = 0.8; green.b = 0.3;
+        rotate_hue(green, -60).to.srgb()
+        `,
+      );
+
+      expect(result?.constructor.name).toBe("ColorSymbol");
+    });
+
+    it("should preserve lightness and chroma", async () => {
+      const result = await executeWithSchema(
+        "rotate_hue",
+        "function",
+        `
+        variable color: Color.SRGB;
+        color.r = 0.6; color.g = 0.4; color.b = 0.8;
+        rotate_hue(color, 45).to.srgb()
+        `,
+      );
+
+      expect(result?.constructor.name).toBe("ColorSymbol");
+    });
+  });
+});

package/src/schemas/functions/saturate/saturate.tokenscript

@@ -0,0 +1,33 @@
+// Saturate a color by increasing its OKLCH chroma
+// Amount: 0-1 where 0.25 means 25% increase
+//
+// Algorithm: C' = C * (1 + amount)
+// Chroma has no strict upper bound but ~0.4 is practical max for sRGB
+
+variable input: List = {input};
+variable color: Color.OKLCH = input.get(0).to.oklch();
+
+// Default amount is 0.25 (25%)
+variable amount: Number = 0.25;
+if (input.length() > 1) [
+    amount = input.get(1);
+];
+
+// Calculate new chroma
+variable current_c: Number = color.c;
+variable new_c: Number = current_c * (1 + amount);
+
+// Soft clamp at 0.4 (approximate sRGB gamut max)
+if (new_c > 0.4) [ new_c = 0.4; ];
+
+// Create output in OKLCH, return as sRGB
+variable result: Color.OKLCH;
+result.l = color.l;
+result.c = new_c;
+result.h = color.h;
+
+return result;
+
+
+
+

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

@@ -0,0 +1,24 @@
+{
+  "name": "Saturate",
+  "type": "function",
+  "description": "Increases color saturation by boosting chroma in OKLCH space. Amount is 0-1 where 0.25 = 25% more saturated.",
+  "keyword": "saturate",
+  "input": {
+    "type": "object",
+    "properties": {
+      "color": {
+        "type": "color",
+        "description": "The color to saturate"
+      },
+      "amount": {
+        "type": "number",
+        "description": "Amount to saturate (0-1). Default is 0.25"
+      }
+    }
+  },
+  "script": {
+    "type": "/api/v1/core/tokenscript/0/",
+    "script": "./saturate.tokenscript"
+  },
+  "requirements": ["/api/v1/core/oklch-color/0/", "/api/v1/core/srgb-color/0/"]
+}

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

@@ -0,0 +1,59 @@
+/**
+ * Unit tests for the Saturate function
+ * Increases color saturation by boosting OKLCH chroma
+ */
+
+import { executeWithSchema, getBundledSchema } from "@tests/helpers/schema-test-utils";
+import { describe, expect, it } from "vitest";
+import type { FunctionSpecification } from "@/bundler/types";
+
+describe("Saturate Function", () => {
+  describe("Schema Definition", () => {
+    it("should have correct schema structure", async () => {
+      const schema = (await getBundledSchema("saturate", "function")) as FunctionSpecification;
+
+      expect(schema.name).toBe("Saturate");
+      expect(schema.type).toBe("function");
+      expect(schema.keyword).toBe("saturate");
+    });
+  });
+
+  describe("Function Execution", () => {
+    it("should increase saturation of a muted color", async () => {
+      const result = await executeWithSchema(
+        "saturate",
+        "function",
+        `
+        variable muted: Color.SRGB;
+        muted.r = 0.5; muted.g = 0.4; muted.b = 0.45;
+        saturate(muted, 0.05).to.srgb()
+        `,
+      );
+
+      expect(result?.constructor.name).toBe("ColorSymbol");
+      // Result should have more color separation (more saturated)
+      const r = (result as any).value.r.value;
+      const g = (result as any).value.g.value;
+      // b is extracted but not directly tested - saturation affects all channels
+      const _b = (result as any).value.b.value;
+      void _b; // Acknowledge extraction
+      const originalSpread = Math.abs(0.5 - 0.4);
+      const newSpread = Math.abs(r - g);
+      expect(newSpread).toBeGreaterThanOrEqual(originalSpread - 0.01);
+    });
+
+    it("should use default amount of 0.1", async () => {
+      const result = await executeWithSchema(
+        "saturate",
+        "function",
+        `
+        variable color: Color.SRGB;
+        color.r = 0.6; color.g = 0.5; color.b = 0.5;
+        saturate(color).to.srgb()
+        `,
+      );
+
+      expect(result?.constructor.name).toBe("ColorSymbol");
+    });
+  });
+});

package/src/schemas/functions/scale_chroma/scale-chroma.tokenscript

@@ -0,0 +1,22 @@
+// scale_chroma: Multiply chroma by a factor
+// Uses OKLCH for perceptually uniform scaling
+// Chroma cannot be negative; clamps to 0
+
+variable input: List = {input};
+variable color: Color.OKLCH = input.get(0).to.oklch();
+variable factor: Number = input.get(1);
+
+// Scale chroma
+variable new_c: Number = color.c * factor;
+
+// Clamp to valid range (no negative chroma)
+if (new_c < 0) [ new_c = 0; ];
+
+// Create result
+variable result: Color.OKLCH;
+result.l = color.l;
+result.c = new_c;
+result.h = color.h;
+
+return result;
+

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

@@ -0,0 +1,48 @@
+{
+  "name": "scale_chroma",
+  "type": "function",
+  "description": "Scales a color's chroma (saturation) by a factor. Unlike set_chroma which sets an absolute value, scale_chroma multiplies the current chroma. A factor of 1.5 increases colorfulness by 50%, while 0.5 decreases it by 50%. Uses OKLCH for perceptually uniform scaling. Useful for creating more or less vivid versions of a color.",
+  "keyword": "scale_chroma",
+  "requirements": ["/api/v1/core/srgb-color/0/", "/api/v1/core/oklch-color/0/"],
+  "schema": {
+    "type": "object",
+    "properties": {
+      "input": {
+        "type": "array",
+        "items": [
+          {
+            "description": "Color to scale",
+            "type": "color"
+          },
+          {
+            "description": "Scale factor (e.g., 1.5 for +50%, 0.5 for -50%)",
+            "type": "number"
+          }
+        ],
+        "minItems": 2,
+        "maxItems": 2
+      }
+    },
+    "required": ["input"]
+  },
+  "returns": {
+    "type": "color",
+    "description": "Color with scaled chroma"
+  },
+  "script": {
+    "type": "https://schema.tokenscript.dev.gcp.tokens.studio/api/v1/core/tokenscript/0/",
+    "script": "./scale-chroma.tokenscript"
+  },
+  "examples": [
+    {
+      "description": "Make color more vivid",
+      "input": ["#cc8080", 1.5],
+      "output": "More saturated red"
+    },
+    {
+      "description": "Desaturate color",
+      "input": ["#ff0000", 0.5],
+      "output": "Muted red"
+    }
+  ]
+}

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

@@ -0,0 +1,79 @@
+/**
+ * Unit tests for the scale_chroma function
+ * Scales a color's chroma by a factor
+ */
+
+import { executeWithSchema, getBundledSchema } from "@tests/helpers/schema-test-utils";
+import { describe, expect, it } from "vitest";
+import type { FunctionSpecification } from "@/bundler/types";
+
+describe("scale_chroma function", () => {
+  describe("Schema Definition", () => {
+    it("should have correct schema structure", async () => {
+      const schema = (await getBundledSchema("scale_chroma", "function")) as FunctionSpecification;
+
+      expect(schema.name).toBe("scale_chroma");
+      expect(schema.type).toBe("function");
+    });
+  });
+
+  describe("Function Execution", () => {
+    it("should decrease saturation with factor < 1", async () => {
+      const result = await executeWithSchema(
+        "scale_chroma",
+        "function",
+        `
+        variable red: Color.SRGB;
+        red.r = 1; red.g = 0; red.b = 0;
+        scale_chroma(red, 0.5).to.srgb()
+        `,
+      );
+
+      expect(result).toBeDefined();
+      const r = (result as any).value?.r?.value ?? (result as any).value?.r;
+      const g = (result as any).value?.g?.value ?? (result as any).value?.g;
+      // Desaturated red should have less extreme difference
+      expect(Math.abs(r - g)).toBeLessThan(0.8);
+    });
+
+    it("should produce gray with factor 0", async () => {
+      const result = await executeWithSchema(
+        "scale_chroma",
+        "function",
+        `
+        variable red: Color.SRGB;
+        red.r = 1; red.g = 0; red.b = 0;
+        scale_chroma(red, 0).to.srgb()
+        `,
+      );
+
+      expect(result).toBeDefined();
+      const r = (result as any).value?.r?.value ?? (result as any).value?.r;
+      const g = (result as any).value?.g?.value ?? (result as any).value?.g;
+      const b = (result as any).value?.b?.value ?? (result as any).value?.b;
+      // Should be gray
+      expect(Math.abs(r - g)).toBeLessThan(0.05);
+      expect(Math.abs(g - b)).toBeLessThan(0.05);
+    });
+
+    it("should handle already gray colors", async () => {
+      const result = await executeWithSchema(
+        "scale_chroma",
+        "function",
+        `
+        variable gray: Color.SRGB;
+        gray.r = 0.5; gray.g = 0.5; gray.b = 0.5;
+        scale_chroma(gray, 2).to.srgb()
+        `,
+      );
+
+      expect(result).toBeDefined();
+      const r = (result as any).value?.r?.value ?? (result as any).value?.r;
+      const g = (result as any).value?.g?.value ?? (result as any).value?.g;
+      const b = (result as any).value?.b?.value ?? (result as any).value?.b;
+      // Gray scaled stays gray (0 * 2 = 0)
+      expect(Math.abs(r - g)).toBeLessThan(0.05);
+      expect(Math.abs(g - b)).toBeLessThan(0.05);
+    });
+  });
+});

package/src/schemas/functions/scale_lightness/scale-lightness.tokenscript

@@ -0,0 +1,23 @@
+// scale_lightness: Multiply lightness by a factor
+// Uses OKLCH for perceptually uniform scaling
+// Clamps result to valid range [0, 1]
+
+variable input: List = {input};
+variable color: Color.OKLCH = input.get(0).to.oklch();
+variable factor: Number = input.get(1);
+
+// Scale lightness
+variable new_l: Number = color.l * factor;
+
+// Clamp to valid range
+if (new_l < 0) [ new_l = 0; ];
+if (new_l > 1) [ new_l = 1; ];
+
+// Create result
+variable result: Color.OKLCH;
+result.l = new_l;
+result.c = color.c;
+result.h = color.h;
+
+return result;
+

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

@@ -0,0 +1,48 @@
+{
+  "name": "scale_lightness",
+  "type": "function",
+  "description": "Scales a color's lightness by a factor. Unlike set_lightness which sets an absolute value, scale_lightness multiplies the current lightness. A factor of 1.2 increases lightness by 20%, while 0.8 decreases it by 20%. Uses OKLCH for perceptually uniform scaling. Result is clamped to valid lightness range [0, 1].",
+  "keyword": "scale_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 scale",
+            "type": "color"
+          },
+          {
+            "description": "Scale factor (e.g., 1.2 for +20%, 0.8 for -20%)",
+            "type": "number"
+          }
+        ],
+        "minItems": 2,
+        "maxItems": 2
+      }
+    },
+    "required": ["input"]
+  },
+  "returns": {
+    "type": "color",
+    "description": "Color with scaled lightness"
+  },
+  "script": {
+    "type": "https://schema.tokenscript.dev.gcp.tokens.studio/api/v1/core/tokenscript/0/",
+    "script": "./scale-lightness.tokenscript"
+  },
+  "examples": [
+    {
+      "description": "Brighten color by 20%",
+      "input": ["#808080", 1.2],
+      "output": "Lighter gray"
+    },
+    {
+      "description": "Dim color by 50%",
+      "input": ["#ffffff", 0.5],
+      "output": "Mid-gray"
+    }
+  ]
+}