@tokens-studio/tokenscript-schemas 0.0.11 → 0.0.13

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

@@ -0,0 +1,86 @@
+/**
+ * Unit tests for the Is Light function
+ * Checks if a color is perceptually light
+ */
+
+import { executeWithSchema, getBundledSchema } from "@tests/helpers/schema-test-utils";
+import { describe, expect, it } from "vitest";
+import type { FunctionSpecification } from "@/bundler/types";
+
+describe("Is Light Function", () => {
+  describe("Schema Definition", () => {
+    it("should have correct schema structure", async () => {
+      const schema = (await getBundledSchema("is_light", "function")) as FunctionSpecification;
+
+      expect(schema.name).toBe("Is Light");
+      expect(schema.type).toBe("function");
+      expect(schema.keyword).toBe("is_light");
+    });
+  });
+
+  describe("Function Execution", () => {
+    it("should return true for white", async () => {
+      const result = await executeWithSchema(
+        "is_light",
+        "function",
+        `
+        variable white: Color.SRGB;
+        white.r = 1; white.g = 1; white.b = 1;
+        is_light(white)
+        `,
+      );
+
+      expect(result).toBeDefined();
+      const isLight = (result as any).value ?? result;
+      expect(isLight).toBe(true);
+    });
+
+    it("should return false for black", async () => {
+      const result = await executeWithSchema(
+        "is_light",
+        "function",
+        `
+        variable black: Color.SRGB;
+        black.r = 0; black.g = 0; black.b = 0;
+        is_light(black)
+        `,
+      );
+
+      expect(result).toBeDefined();
+      const isLight = (result as any).value ?? result;
+      expect(isLight).toBe(false);
+    });
+
+    it("should return true for light yellow", async () => {
+      const result = await executeWithSchema(
+        "is_light",
+        "function",
+        `
+        variable yellow: Color.SRGB;
+        yellow.r = 1; yellow.g = 0.95; yellow.b = 0.6;
+        is_light(yellow)
+        `,
+      );
+
+      expect(result).toBeDefined();
+      const isLight = (result as any).value ?? result;
+      expect(isLight).toBe(true);
+    });
+
+    it("should return false for dark blue", async () => {
+      const result = await executeWithSchema(
+        "is_light",
+        "function",
+        `
+        variable darkBlue: Color.SRGB;
+        darkBlue.r = 0.1; darkBlue.g = 0.1; darkBlue.b = 0.3;
+        is_light(darkBlue)
+        `,
+      );
+
+      expect(result).toBeDefined();
+      const isLight = (result as any).value ?? result;
+      expect(isLight).toBe(false);
+    });
+  });
+});

package/src/schemas/functions/is_neutral/is-neutral.tokenscript

@@ -0,0 +1,16 @@
+// is_neutral: Check if a color is achromatic (gray)
+// Uses OKLCH chroma - low chroma means neutral
+// Threshold of 0.02 allows for near-neutral colors
+
+variable input: List = {input};
+variable color: Color.OKLCH = input.get(0).to.oklch();
+
+// Default chroma threshold
+variable threshold: Number = 0.02;
+if (input.length() > 1) [
+    threshold = input.get(1);
+];
+
+// Color is neutral if chroma is below threshold
+return color.c < threshold;
+

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

@@ -0,0 +1,53 @@
+{
+  "name": "is_neutral",
+  "type": "function",
+  "description": "Determines if a color is achromatic (neutral/gray). Uses OKLCH chroma value - colors with very low chroma are considered neutral regardless of their hue. Default threshold of 0.02 allows for near-neutral colors that appear gray to human observers.",
+  "keyword": "is_neutral",
+  "requirements": ["/api/v1/core/srgb-color/0/", "/api/v1/core/oklch-color/0/"],
+  "schema": {
+    "type": "object",
+    "properties": {
+      "input": {
+        "type": "array",
+        "items": [
+          {
+            "description": "Color to test",
+            "type": "color"
+          },
+          {
+            "description": "Chroma threshold (default 0.02). Lower = stricter.",
+            "type": "number"
+          }
+        ],
+        "minItems": 1,
+        "maxItems": 2
+      }
+    },
+    "required": ["input"]
+  },
+  "returns": {
+    "type": "boolean",
+    "description": "True if color is achromatic/neutral"
+  },
+  "script": {
+    "type": "https://schema.tokenscript.dev.gcp.tokens.studio/api/v1/core/tokenscript/0/",
+    "script": "./is-neutral.tokenscript"
+  },
+  "examples": [
+    {
+      "description": "Pure gray is neutral",
+      "input": ["#808080"],
+      "output": true
+    },
+    {
+      "description": "Pure red is not neutral",
+      "input": ["#ff0000"],
+      "output": false
+    },
+    {
+      "description": "Desaturated color may be neutral",
+      "input": ["#7a7a7c"],
+      "output": true
+    }
+  ]
+}

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

@@ -0,0 +1,85 @@
+/**
+ * Unit tests for the is_neutral function
+ * Checks if a color is achromatic (gray)
+ */
+
+import { executeWithSchema, getBundledSchema } from "@tests/helpers/schema-test-utils";
+import { describe, expect, it } from "vitest";
+import type { FunctionSpecification } from "@/bundler/types";
+
+describe("is_neutral function", () => {
+  describe("Schema Definition", () => {
+    it("should have correct schema structure", async () => {
+      const schema = (await getBundledSchema("is_neutral", "function")) as FunctionSpecification;
+
+      expect(schema.name).toBe("is_neutral");
+      expect(schema.type).toBe("function");
+    });
+  });
+
+  describe("Function Execution", () => {
+    it("should return true for pure gray", async () => {
+      const result = await executeWithSchema(
+        "is_neutral",
+        "function",
+        `
+        variable gray: Color.SRGB;
+        gray.r = 0.5; gray.g = 0.5; gray.b = 0.5;
+        is_neutral(gray)
+        `,
+      );
+
+      expect(result).toBeDefined();
+      const neutral = (result as any).value ?? result;
+      expect(neutral).toBe(true);
+    });
+
+    it("should return true for white", async () => {
+      const result = await executeWithSchema(
+        "is_neutral",
+        "function",
+        `
+        variable white: Color.SRGB;
+        white.r = 1; white.g = 1; white.b = 1;
+        is_neutral(white)
+        `,
+      );
+
+      expect(result).toBeDefined();
+      const neutral = (result as any).value ?? result;
+      expect(neutral).toBe(true);
+    });
+
+    it("should return true for black", async () => {
+      const result = await executeWithSchema(
+        "is_neutral",
+        "function",
+        `
+        variable black: Color.SRGB;
+        black.r = 0; black.g = 0; black.b = 0;
+        is_neutral(black)
+        `,
+      );
+
+      expect(result).toBeDefined();
+      const neutral = (result as any).value ?? result;
+      expect(neutral).toBe(true);
+    });
+
+    it("should return false for saturated red", async () => {
+      const result = await executeWithSchema(
+        "is_neutral",
+        "function",
+        `
+        variable red: Color.SRGB;
+        red.r = 1; red.g = 0; red.b = 0;
+        is_neutral(red)
+        `,
+      );
+
+      expect(result).toBeDefined();
+      const neutral = (result as any).value ?? result;
+      expect(neutral).toBe(false);
+    });
+  });
+});

package/src/schemas/functions/is_warm/is-warm.tokenscript

@@ -0,0 +1,62 @@
+// Is Warm Color
+// Determines if a color is perceptually warm or cool
+//
+// Color Temperature Psychology:
+// - Warm colors: Red, orange, yellow (associated with fire, sun)
+// - Cool colors: Blue, green, purple (associated with water, ice)
+//
+// Hue ranges (in OKLCH/HSL degrees):
+// - Warm: roughly 0-90° (red through yellow) and 330-360° (red-magenta)
+// - Cool: roughly 90-330° (yellow-green through purple)
+//
+// Achromatic colors (low chroma) are considered neutral
+// and return false (lean towards cool for safety in accessibility)
+
+variable input: List = {input};
+variable color: Color.OKLCH = input.get(0).to.oklch();
+
+// Get hue and chroma
+variable h: Number = color.h;
+variable c: Number = color.c;
+
+// Achromatic colors (very low chroma) are neutral
+// Return false (cool) for these
+if (c < 0.02) [
+    return false;
+];
+
+// Normalize hue to 0-360
+if (h < 0) [ h = h + 360; ];
+if (h >= 360) [ h = h - 360; ];
+
+// OKLCH Warm hue ranges:
+// In OKLCH, hue angles differ from HSL:
+// - Red: ~29°
+// - Orange: ~53°
+// - Yellow: ~110°
+// - Yellow-green: ~130°
+// - Green: ~145°
+// - Cyan: ~195°
+// - Blue: ~265°
+// - Purple: ~300°
+// - Magenta: ~330°
+//
+// Warm colors: 0-130° (red through yellow-green) and 320-360° (magenta-red)
+variable is_warm: Boolean = false;
+
+// Check 0-130 range (red through yellow to yellow-green)
+if (h >= 0) [
+    if (h <= 130) [
+        is_warm = true;
+    ];
+];
+
+// Check 320-360 range (magenta-red)
+if (h >= 320) [
+    if (h <= 360) [
+        is_warm = true;
+    ];
+];
+
+return is_warm;
+

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

@@ -0,0 +1,20 @@
+{
+  "name": "Is Warm",
+  "type": "function",
+  "description": "Checks if a color is perceptually warm. Uses OKLCH color space where warm colors have hues in the red-yellow range (roughly 0-130° and 320-360°). Returns true for warm colors (red, orange, yellow), false for cool colors (green, cyan, blue, purple). Achromatic colors are considered neutral/cool.",
+  "keyword": "is_warm",
+  "input": {
+    "type": "object",
+    "properties": {
+      "color": {
+        "type": "color",
+        "description": "Color to check"
+      }
+    }
+  },
+  "script": {
+    "type": "/api/v1/core/tokenscript/0/",
+    "script": "./is-warm.tokenscript"
+  },
+  "requirements": ["/api/v1/core/oklch-color/0/"]
+}

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

@@ -0,0 +1,161 @@
+import { executeWithSchema } from "@tests/helpers/schema-test-utils";
+import { describe, expect, it } from "vitest";
+
+describe("Is Warm Function", () => {
+  describe("Schema Definition", () => {
+    it("should have correct schema structure", async () => {
+      const { getBundledSchema } = await import("@tests/helpers/schema-test-utils");
+      const schema = await getBundledSchema("is_warm", "function");
+
+      expect(schema.name).toBe("Is Warm");
+      expect(schema.type).toBe("function");
+      expect((schema as any).keyword).toBe("is_warm");
+    });
+  });
+
+  describe("Warm Colors", () => {
+    it("should return true for red", async () => {
+      const result = await executeWithSchema(
+        "is_warm",
+        "function",
+        `
+        variable c: Color.SRGB;
+        c.r = 1; c.g = 0; c.b = 0;
+        is_warm(c)
+        `,
+      );
+
+      expect(result.value).toBe(true);
+    });
+
+    it("should return true for orange", async () => {
+      const result = await executeWithSchema(
+        "is_warm",
+        "function",
+        `
+        variable c: Color.SRGB;
+        c.r = 1; c.g = 0.5; c.b = 0;
+        is_warm(c)
+        `,
+      );
+
+      expect(result.value).toBe(true);
+    });
+
+    it("should return true for yellow", async () => {
+      const result = await executeWithSchema(
+        "is_warm",
+        "function",
+        `
+        variable c: Color.SRGB;
+        c.r = 1; c.g = 1; c.b = 0;
+        is_warm(c)
+        `,
+      );
+
+      expect(result.value).toBe(true);
+    });
+  });
+
+  describe("Cool Colors", () => {
+    it("should return false for blue", async () => {
+      const result = await executeWithSchema(
+        "is_warm",
+        "function",
+        `
+        variable c: Color.SRGB;
+        c.r = 0; c.g = 0; c.b = 1;
+        is_warm(c)
+        `,
+      );
+
+      expect(result.value).toBe(false);
+    });
+
+    it("should return false for green", async () => {
+      const result = await executeWithSchema(
+        "is_warm",
+        "function",
+        `
+        variable c: Color.SRGB;
+        c.r = 0; c.g = 1; c.b = 0;
+        is_warm(c)
+        `,
+      );
+
+      expect(result.value).toBe(false);
+    });
+
+    it("should return false for cyan", async () => {
+      const result = await executeWithSchema(
+        "is_warm",
+        "function",
+        `
+        variable c: Color.SRGB;
+        c.r = 0; c.g = 1; c.b = 1;
+        is_warm(c)
+        `,
+      );
+
+      expect(result.value).toBe(false);
+    });
+
+    it("should return false for purple", async () => {
+      const result = await executeWithSchema(
+        "is_warm",
+        "function",
+        `
+        variable c: Color.SRGB;
+        c.r = 0.5; c.g = 0; c.b = 1;
+        is_warm(c)
+        `,
+      );
+
+      expect(result.value).toBe(false);
+    });
+  });
+
+  describe("Achromatic Colors", () => {
+    it("should return false for white (neutral)", async () => {
+      const result = await executeWithSchema(
+        "is_warm",
+        "function",
+        `
+        variable c: Color.SRGB;
+        c.r = 1; c.g = 1; c.b = 1;
+        is_warm(c)
+        `,
+      );
+
+      expect(result.value).toBe(false);
+    });
+
+    it("should return false for black (neutral)", async () => {
+      const result = await executeWithSchema(
+        "is_warm",
+        "function",
+        `
+        variable c: Color.SRGB;
+        c.r = 0; c.g = 0; c.b = 0;
+        is_warm(c)
+        `,
+      );
+
+      expect(result.value).toBe(false);
+    });
+
+    it("should return false for gray (neutral)", async () => {
+      const result = await executeWithSchema(
+        "is_warm",
+        "function",
+        `
+        variable c: Color.SRGB;
+        c.r = 0.5; c.g = 0.5; c.b = 0.5;
+        is_warm(c)
+        `,
+      );
+
+      expect(result.value).toBe(false);
+    });
+  });
+});

package/src/schemas/functions/lighten/lighten.tokenscript

@@ -0,0 +1,37 @@
+// lighten: Increase lightness proportionally towards white
+// Amount: 0-1 where 0.25 means 25% closer to white
+//
+// Algorithm: L' = L + (1 - L) * amount
+// This ensures we approach white (L=1) proportionally.
+//
+// Input:  Any color space (converted to OKLab internally)
+// Output: OKLCH (working space)
+// To get sRGB: lighten(color, 0.25).to.srgb()
+
+variable input: List = {input};
+variable color: Color.OKLab = input.get(0).to.oklab();
+
+// Default amount is 0.25 (25%)
+variable amount: Number = 0.25;
+if (input.length() > 1) [
+    amount = input.get(1);
+];
+
+// Calculate new lightness (move toward 1)
+variable current_l: Number = color.l;
+variable new_l: Number = current_l + (1 - current_l) * amount;
+
+// Clamp to valid range
+if (new_l > 1) [ new_l = 1; ];
+
+// Create output in OKLab, return as OKLCH (working space)
+variable result: Color.OKLab;
+result.l = new_l;
+result.a = color.a;
+result.b = color.b;
+
+return result.to.oklch();
+
+
+
+

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

@@ -0,0 +1,24 @@
+{
+  "name": "Lighten",
+  "type": "function",
+  "description": "Makes a color lighter by increasing its lightness in OKLab space. Amount is 0-1 where 0.25 = 25% lighter.",
+  "keyword": "lighten",
+  "input": {
+    "type": "object",
+    "properties": {
+      "color": {
+        "type": "color",
+        "description": "The color to lighten"
+      },
+      "amount": {
+        "type": "number",
+        "description": "Amount to lighten (0-1). Default is 0.25"
+      }
+    }
+  },
+  "script": {
+    "type": "/api/v1/core/tokenscript/0/",
+    "script": "./lighten.tokenscript"
+  },
+  "requirements": ["/api/v1/core/oklab-color/0/", "/api/v1/core/srgb-color/0/"]
+}

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

@@ -0,0 +1,109 @@
+/**
+ * Unit tests for the Lighten function
+ * Increases color lightness in OKLab perceptual space
+ */
+
+import { executeWithSchema, getBundledSchema } from "@tests/helpers/schema-test-utils";
+import { describe, expect, it } from "vitest";
+import type { FunctionSpecification } from "@/bundler/types";
+
+describe("Lighten Function", () => {
+  describe("Schema Definition", () => {
+    it("should have correct schema structure", async () => {
+      const schema = (await getBundledSchema("lighten", "function")) as FunctionSpecification;
+
+      expect(schema.name).toBe("Lighten");
+      expect(schema.type).toBe("function");
+      expect(schema.keyword).toBe("lighten");
+    });
+
+    it("should have script defined", async () => {
+      const schema = (await getBundledSchema("lighten", "function")) as FunctionSpecification;
+
+      expect(schema.script).toBeDefined();
+      expect(schema.script.script).toBeTruthy();
+      expect(schema.script.script).not.toContain("./");
+    });
+  });
+
+  describe("Function Execution", () => {
+    it("should lighten a dark color", async () => {
+      // Note: lighten() returns OKLCH, we chain .to.srgb() to get RGB values
+      const result = await executeWithSchema(
+        "lighten",
+        "function",
+        `
+        variable dark: Color.SRGB;
+        dark.r = 0.2; dark.g = 0.2; dark.b = 0.4;
+        lighten(dark, 0.2).to.srgb()
+        `,
+      );
+
+      expect(result?.constructor.name).toBe("ColorSymbol");
+      // Lightened color should have higher luminance
+      const r = (result as any).value.r.value;
+      const g = (result as any).value.g.value;
+      const b = (result as any).value.b.value;
+      expect(r).toBeGreaterThan(0.2);
+      expect(g).toBeGreaterThan(0.2);
+      expect(b).toBeGreaterThan(0.4);
+    });
+
+    it("should use default amount of 0.25", async () => {
+      const result = await executeWithSchema(
+        "lighten",
+        "function",
+        `
+        variable color: Color.SRGB;
+        color.r = 0.3; color.g = 0.3; color.b = 0.3;
+        lighten(color).to.srgb()
+        `,
+      );
+
+      expect(result?.constructor.name).toBe("ColorSymbol");
+      const r = (result as any).value.r.value;
+      expect(r).toBeGreaterThan(0.3);
+    });
+
+    it("should not exceed maximum lightness", async () => {
+      const result = await executeWithSchema(
+        "lighten",
+        "function",
+        `
+        variable bright: Color.SRGB;
+        bright.r = 0.9; bright.g = 0.9; bright.b = 0.9;
+        lighten(bright, 0.5).to.srgb()
+        `,
+      );
+
+      expect(result?.constructor.name).toBe("ColorSymbol");
+      const r = (result as any).value.r.value;
+      const g = (result as any).value.g.value;
+      const b = (result as any).value.b.value;
+      // Should be clamped to valid range
+      expect(r).toBeLessThanOrEqual(1);
+      expect(g).toBeLessThanOrEqual(1);
+      expect(b).toBeLessThanOrEqual(1);
+    });
+
+    it("should preserve hue when lightening", async () => {
+      const result = await executeWithSchema(
+        "lighten",
+        "function",
+        `
+        variable red: Color.SRGB;
+        red.r = 0.6; red.g = 0.1; red.b = 0.1;
+        lighten(red, 0.15).to.srgb()
+        `,
+      );
+
+      expect(result?.constructor.name).toBe("ColorSymbol");
+      const r = (result as any).value.r.value;
+      const g = (result as any).value.g.value;
+      const b = (result as any).value.b.value;
+      // Red should still dominate
+      expect(r).toBeGreaterThan(g);
+      expect(r).toBeGreaterThan(b);
+    });
+  });
+});

package/src/schemas/functions/lightness/lightness.tokenscript

@@ -0,0 +1,12 @@
+// lightness: Extract perceptual lightness from a color
+// Reference: OKLCH Color Space (Björn Ottosson)
+// Reference: https://bottosson.github.io/posts/oklab/
+//
+// Returns the L component from OKLCH, which represents
+// perceptually uniform lightness. Range: 0 (black) to 1 (white).
+
+variable input: List = {input};
+variable color: Color.OKLCH = input.get(0).to.oklch();
+
+return color.l;
+