@tokens-studio/tokenscript-schemas 0.0.11 → 0.0.13

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

@@ -0,0 +1,95 @@
+/**
+ * Unit tests for the Mix function
+ * Interpolates between two colors in OKLCH space
+ */
+
+import { executeWithSchema, getBundledSchema } from "@tests/helpers/schema-test-utils";
+import { describe, expect, it } from "vitest";
+import type { FunctionSpecification } from "@/bundler/types";
+
+describe("Mix Function", () => {
+  describe("Schema Definition", () => {
+    it("should have correct schema structure", async () => {
+      const schema = (await getBundledSchema("mix", "function")) as FunctionSpecification;
+
+      expect(schema.name).toBe("Mix");
+      expect(schema.type).toBe("function");
+      expect(schema.keyword).toBe("mix");
+    });
+  });
+
+  describe("Function Execution", () => {
+    it("should mix red and blue at 50%", async () => {
+      const result = await executeWithSchema(
+        "mix",
+        "function",
+        `
+        variable red: Color.SRGB;
+        red.r = 1; red.g = 0; red.b = 0;
+        variable blue: Color.SRGB;
+        blue.r = 0; blue.g = 0; blue.b = 1;
+        mix(red, blue, 0.5).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 have both red and blue components
+      expect(r).toBeGreaterThan(0.2);
+      expect(b).toBeGreaterThan(0.2);
+    });
+
+    it("should return first color at 0%", async () => {
+      const result = await executeWithSchema(
+        "mix",
+        "function",
+        `
+        variable white: Color.SRGB;
+        white.r = 1; white.g = 1; white.b = 1;
+        variable black: Color.SRGB;
+        black.r = 0; black.g = 0; black.b = 0;
+        mix(white, black, 0).to.srgb()
+        `,
+      );
+
+      expect(result?.constructor.name).toBe("ColorSymbol");
+      const r = (result as any).value.r.value;
+      expect(r).toBeCloseTo(1, 1);
+    });
+
+    it("should return second color at 100%", async () => {
+      const result = await executeWithSchema(
+        "mix",
+        "function",
+        `
+        variable white: Color.SRGB;
+        white.r = 1; white.g = 1; white.b = 1;
+        variable black: Color.SRGB;
+        black.r = 0; black.g = 0; black.b = 0;
+        mix(white, black, 1).to.srgb()
+        `,
+      );
+
+      expect(result?.constructor.name).toBe("ColorSymbol");
+      const r = (result as any).value.r.value;
+      expect(r).toBeCloseTo(0, 1);
+    });
+
+    it("should default to 50% mix", async () => {
+      const result = await executeWithSchema(
+        "mix",
+        "function",
+        `
+        variable c1: Color.SRGB;
+        c1.r = 0.8; c1.g = 0.2; c1.b = 0.2;
+        variable c2: Color.SRGB;
+        c2.r = 0.2; c2.g = 0.8; c2.b = 0.2;
+        mix(c1, c2).to.srgb()
+        `,
+      );
+
+      expect(result?.constructor.name).toBe("ColorSymbol");
+    });
+  });
+});

package/src/schemas/functions/monochromatic/monochromatic.tokenscript

@@ -0,0 +1,72 @@
+// Monochromatic Color Palette
+// Generates variations of a single hue with different lightness
+//
+// A monochromatic scheme uses:
+// - Same hue throughout
+// - Varying lightness (from light tints to dark shades)
+// - Varying chroma (reduced at extremes for natural appearance)
+//
+// This creates harmonious, cohesive palettes ideal for:
+// - UI background/foreground variations
+// - Data visualization with single-variable emphasis
+// - Brand color systems
+
+variable input: List = {input};
+variable base: Color.OKLCH = input.get(0).to.oklch();
+
+// Default count is 5
+variable count: Number = 5;
+if (input.length() > 1) [
+    count = input.get(1);
+];
+
+// Preserve the hue
+variable base_h: Number = base.h;
+variable base_c: Number = base.c;
+
+// Define lightness range (from light to dark)
+variable light_start: Number = 0.9;
+variable light_end: Number = 0.3;
+
+variable result: List;
+variable i: Number = 0;
+variable t: Number = 0;
+variable step_l: Number = 0;
+variable l_factor: Number = 0;
+variable step_c: Number = 0;
+variable color: Color.OKLCH;
+
+while (i < count) [
+    // Calculate interpolation factor
+    if (count > 1) [
+        t = i / (count - 1);
+    ] else [
+        t = 0.5;
+    ];
+    
+    // Interpolate lightness
+    step_l = light_start + (light_end - light_start) * t;
+    
+    // Scale chroma - reduce at extremes for natural appearance
+    // Peak chroma around middle lightness (0.6)
+    l_factor = step_l - 0.6;
+    if (l_factor < 0) [ l_factor = 0 - l_factor; ];
+    l_factor = 1 - l_factor * 1.5;
+    if (l_factor < 0.3) [ l_factor = 0.3; ];
+    if (l_factor > 1) [ l_factor = 1; ];
+    
+    step_c = base_c * l_factor;
+    
+    // Clamp chroma to avoid out-of-gamut
+    if (step_c > 0.35) [ step_c = 0.35; ];
+    
+    color.l = step_l;
+    color.c = step_c;
+    color.h = base_h;
+    
+    result = result, color.to.srgb();
+    i = i + 1;
+];
+
+return result;
+

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

@@ -0,0 +1,24 @@
+{
+  "name": "Monochromatic",
+  "type": "function",
+  "description": "Generates a monochromatic color palette - variations of a single hue with different lightness and chroma. Useful for creating cohesive single-color schemes. Preserves hue, varies lightness from light to dark.",
+  "keyword": "monochromatic",
+  "input": {
+    "type": "object",
+    "properties": {
+      "color": {
+        "type": "color",
+        "description": "Base color"
+      },
+      "count": {
+        "type": "number",
+        "description": "Number of colors to generate (default: 5)"
+      }
+    }
+  },
+  "script": {
+    "type": "/api/v1/core/tokenscript/0/",
+    "script": "./monochromatic.tokenscript"
+  },
+  "requirements": ["/api/v1/core/oklch-color/0/", "/api/v1/core/srgb-color/0/"]
+}

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

@@ -0,0 +1,91 @@
+import { executeWithSchema } from "@tests/helpers/schema-test-utils";
+import { describe, expect, it } from "vitest";
+
+describe("Monochromatic Function", () => {
+  describe("Schema Definition", () => {
+    it("should have correct schema structure", async () => {
+      const { getBundledSchema } = await import("@tests/helpers/schema-test-utils");
+      const schema = await getBundledSchema("monochromatic", "function");
+
+      expect(schema.name).toBe("Monochromatic");
+      expect(schema.type).toBe("function");
+      expect((schema as any).keyword).toBe("monochromatic");
+    });
+  });
+
+  describe("Basic Generation", () => {
+    it("should generate colors with default count", async () => {
+      const result = await executeWithSchema(
+        "monochromatic",
+        "function",
+        `
+        variable c: Color.SRGB;
+        c.r = 0.2; c.g = 0.4; c.b = 0.8;
+        monochromatic(c)
+        `,
+      );
+
+      expect(result).toBeDefined();
+      expect(result.value).toBeDefined();
+    });
+
+    it("should generate colors with specified count", async () => {
+      const result = await executeWithSchema(
+        "monochromatic",
+        "function",
+        `
+        variable c: Color.SRGB;
+        c.r = 0.8; c.g = 0.2; c.b = 0.4;
+        monochromatic(c, 7)
+        `,
+      );
+
+      expect(result).toBeDefined();
+      expect(result.value).toBeDefined();
+    });
+  });
+
+  describe("Different Base Colors", () => {
+    it("should work with red base", async () => {
+      const result = await executeWithSchema(
+        "monochromatic",
+        "function",
+        `
+        variable c: Color.SRGB;
+        c.r = 1; c.g = 0; c.b = 0;
+        monochromatic(c, 5)
+        `,
+      );
+
+      expect(result).toBeDefined();
+    });
+
+    it("should work with blue base", async () => {
+      const result = await executeWithSchema(
+        "monochromatic",
+        "function",
+        `
+        variable c: Color.SRGB;
+        c.r = 0; c.g = 0; c.b = 1;
+        monochromatic(c, 5)
+        `,
+      );
+
+      expect(result).toBeDefined();
+    });
+
+    it("should work with green base", async () => {
+      const result = await executeWithSchema(
+        "monochromatic",
+        "function",
+        `
+        variable c: Color.SRGB;
+        c.r = 0; c.g = 0.8; c.b = 0.2;
+        monochromatic(c, 5)
+        `,
+      );
+
+      expect(result).toBeDefined();
+    });
+  });
+});

package/src/schemas/functions/muted/muted.tokenscript

@@ -0,0 +1,25 @@
+// muted: Decrease chroma toward neutral (gray)
+// Preserves lightness and hue
+// Amount controls how much to reduce (0-1, 1 = fully gray)
+
+variable input: List = {input};
+variable color: Color.OKLCH = input.get(0).to.oklch();
+
+// Default amount
+variable amount: Number = 0.5;
+if (input.length() > 1) [
+    amount = input.get(1);
+];
+
+// Move chroma toward 0 by the specified amount
+variable current_c: Number = color.c;
+variable new_c: Number = current_c * (1 - amount);
+
+// Create result
+variable result: Color.OKLCH;
+result.l = color.l;
+result.c = new_c;
+result.h = color.h;
+
+return result;
+

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

@@ -0,0 +1,48 @@
+{
+  "name": "muted",
+  "type": "function",
+  "description": "Decreases a color's chroma toward neutral (gray). Preserves lightness and hue while reducing colorfulness. The optional amount parameter controls the intensity (0-1, default 0.5). Uses OKLCH for perceptually uniform chroma adjustment. Useful for creating subtle backgrounds, disabled states, or calming variations of vibrant colors.",
+  "keyword": "muted",
+  "requirements": ["/api/v1/core/srgb-color/0/", "/api/v1/core/oklch-color/0/"],
+  "schema": {
+    "type": "object",
+    "properties": {
+      "input": {
+        "type": "array",
+        "items": [
+          {
+            "description": "Color to mute",
+            "type": "color"
+          },
+          {
+            "description": "Amount (0-1, default 0.5). Higher = more muted.",
+            "type": "number"
+          }
+        ],
+        "minItems": 1,
+        "maxItems": 2
+      }
+    },
+    "required": ["input"]
+  },
+  "returns": {
+    "type": "color",
+    "description": "More muted version of the color"
+  },
+  "script": {
+    "type": "https://schema.tokenscript.dev.gcp.tokens.studio/api/v1/core/tokenscript/0/",
+    "script": "./muted.tokenscript"
+  },
+  "examples": [
+    {
+      "description": "Mute vibrant red",
+      "input": ["#ff0000"],
+      "output": "Desaturated red"
+    },
+    {
+      "description": "Fully muted becomes gray",
+      "input": ["#ff0000", 1],
+      "output": "Gray with same lightness as red"
+    }
+  ]
+}

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

@@ -0,0 +1,100 @@
+/**
+ * Unit tests for the muted function
+ * Decreases chroma toward neutral
+ */
+
+import { executeWithSchema, getBundledSchema } from "@tests/helpers/schema-test-utils";
+import { describe, expect, it } from "vitest";
+import type { FunctionSpecification } from "@/bundler/types";
+
+describe("muted function", () => {
+  describe("Schema Definition", () => {
+    it("should have correct schema structure", async () => {
+      const schema = (await getBundledSchema("muted", "function")) as FunctionSpecification;
+
+      expect(schema.name).toBe("muted");
+      expect(schema.type).toBe("function");
+    });
+  });
+
+  describe("Function Execution", () => {
+    it("should decrease saturation of vibrant colors", async () => {
+      const result = await executeWithSchema(
+        "muted",
+        "function",
+        `
+        variable red: Color.SRGB;
+        red.r = 1; red.g = 0; red.b = 0;
+        muted(red).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;
+      // Muted red should have less extreme channel differences
+      expect(r - g).toBeLessThan(0.9);
+    });
+
+    it("should produce gray with amount 1", async () => {
+      const result = await executeWithSchema(
+        "muted",
+        "function",
+        `
+        variable red: Color.SRGB;
+        red.r = 1; red.g = 0; red.b = 0;
+        muted(red, 1).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 have no effect with amount 0", async () => {
+      const result = await executeWithSchema(
+        "muted",
+        "function",
+        `
+        variable red: Color.SRGB;
+        red.r = 1; red.g = 0; red.b = 0;
+        muted(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 remain red
+      expect(r).toBeCloseTo(1, 1);
+      expect(g).toBeCloseTo(0, 1);
+      expect(b).toBeCloseTo(0, 1);
+    });
+
+    it("should preserve gray (already muted)", async () => {
+      const result = await executeWithSchema(
+        "muted",
+        "function",
+        `
+        variable gray: Color.SRGB;
+        gray.r = 0.5; gray.g = 0.5; gray.b = 0.5;
+        muted(gray).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 should stay gray
+      expect(Math.abs(r - g)).toBeLessThan(0.05);
+      expect(Math.abs(g - b)).toBeLessThan(0.05);
+    });
+  });
+});

package/src/schemas/functions/neutral_variant/neutral-variant.tokenscript

@@ -0,0 +1,23 @@
+// neutral_variant: Create gray version of color preserving lightness
+// Optionally retain some chroma for subtle tinting
+
+variable input: List = {input};
+variable color: Color.OKLCH = input.get(0).to.oklch();
+
+// Default to pure gray (0 chroma retention)
+variable retention: Number = 0;
+if (input.length() > 1) [
+    retention = input.get(1);
+];
+
+// Calculate retained chroma
+variable new_c: Number = color.c * retention;
+
+// Create result
+variable result: Color.OKLCH;
+result.l = color.l;
+result.c = new_c;
+result.h = color.h;  // Hue preserved for subtle tinting
+
+return result;
+

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

@@ -0,0 +1,48 @@
+{
+  "name": "neutral_variant",
+  "type": "function",
+  "description": "Creates a neutral (gray) variant of a color while preserving its lightness. Optionally retains a hint of the original hue. Useful for creating subtle backgrounds, disabled states, or neutral UI elements that relate to a brand color. Uses OKLCH for accurate lightness preservation.",
+  "keyword": "neutral_variant",
+  "requirements": ["/api/v1/core/srgb-color/0/", "/api/v1/core/oklch-color/0/"],
+  "schema": {
+    "type": "object",
+    "properties": {
+      "input": {
+        "type": "array",
+        "items": [
+          {
+            "description": "Source color",
+            "type": "color"
+          },
+          {
+            "description": "Optional chroma retention (0-1, default 0 for pure gray)",
+            "type": "number"
+          }
+        ],
+        "minItems": 1,
+        "maxItems": 2
+      }
+    },
+    "required": ["input"]
+  },
+  "returns": {
+    "type": "color",
+    "description": "Neutral variant with same lightness"
+  },
+  "script": {
+    "type": "https://schema.tokenscript.dev.gcp.tokens.studio/api/v1/core/tokenscript/0/",
+    "script": "./neutral-variant.tokenscript"
+  },
+  "examples": [
+    {
+      "description": "Pure gray from blue",
+      "input": ["#0066cc"],
+      "output": "Gray with same lightness as blue"
+    },
+    {
+      "description": "Slightly tinted gray",
+      "input": ["#ff0000", 0.02],
+      "output": "Very subtle warm gray"
+    }
+  ]
+}

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

@@ -0,0 +1,102 @@
+/**
+ * Unit tests for the neutral_variant function
+ * Creates a gray version of a color preserving lightness
+ */
+
+import { executeWithSchema, getBundledSchema } from "@tests/helpers/schema-test-utils";
+import { describe, expect, it } from "vitest";
+import type { FunctionSpecification } from "@/bundler/types";
+
+describe("neutral_variant function", () => {
+  describe("Schema Definition", () => {
+    it("should have correct schema structure", async () => {
+      const schema = (await getBundledSchema(
+        "neutral_variant",
+        "function",
+      )) as FunctionSpecification;
+
+      expect(schema.name).toBe("neutral_variant");
+      expect(schema.type).toBe("function");
+    });
+  });
+
+  describe("Function Execution", () => {
+    it("should produce pure gray with default retention", async () => {
+      const result = await executeWithSchema(
+        "neutral_variant",
+        "function",
+        `
+        variable blue: Color.SRGB;
+        blue.r = 0; blue.g = 0.4; blue.b = 0.8;
+        neutral_variant(blue).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 retain some color with retention > 0", async () => {
+      const result = await executeWithSchema(
+        "neutral_variant",
+        "function",
+        `
+        variable red: Color.SRGB;
+        red.r = 1; red.g = 0; red.b = 0;
+        neutral_variant(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;
+      // Should still have some red tint
+      expect(r).toBeGreaterThan(g);
+    });
+
+    it("should handle white (already neutral)", async () => {
+      const result = await executeWithSchema(
+        "neutral_variant",
+        "function",
+        `
+        variable white: Color.SRGB;
+        white.r = 1; white.g = 1; white.b = 1;
+        neutral_variant(white).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;
+      expect(r).toBeCloseTo(1, 1);
+      expect(g).toBeCloseTo(1, 1);
+      expect(b).toBeCloseTo(1, 1);
+    });
+
+    it("should handle black (already neutral)", async () => {
+      const result = await executeWithSchema(
+        "neutral_variant",
+        "function",
+        `
+        variable black: Color.SRGB;
+        black.r = 0; black.g = 0; black.b = 0;
+        neutral_variant(black).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;
+      expect(r).toBeCloseTo(0, 1);
+      expect(g).toBeCloseTo(0, 1);
+      expect(b).toBeCloseTo(0, 1);
+    });
+  });
+});

package/src/schemas/functions/relative_luminance/relative-luminance.tokenscript

@@ -0,0 +1,15 @@
+// relative_luminance: Get WCAG 2.1 relative luminance
+// Reference: WCAG 2.1 Definition of Relative Luminance
+// Reference: https://www.w3.org/TR/WCAG21/#dfn-relative-luminance
+//
+// Returns the Y component from CIE XYZ D65, which is the
+// relative luminance as defined by WCAG. Range is [0, 1]
+// where 0 = black and 1 = reference white.
+//
+// This value is used in WCAG contrast ratio calculations.
+
+variable input: List = {input};
+variable color: Color.XYZD65 = input.get(0).to.xyzd65();
+
+return color.y;
+