@tokens-studio/tokenscript-schemas 0.0.11 → 0.0.13

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

@@ -0,0 +1,48 @@
+{
+  "name": "to_gamut",
+  "type": "function",
+  "description": "Maps a color into a target gamut using the CSS Color Level 4 gamut mapping algorithm. This preserves the perceptual lightness and hue while reducing chroma until the color fits within the target color space. Uses OKLCH for perceptually uniform mapping and binary search with Delta E OK for convergence. Essential for wide-gamut to sRGB conversion in design systems.",
+  "keyword": "to_gamut",
+  "requirements": ["/api/v1/core/srgb-color/0/", "/api/v1/core/oklch-color/0/"],
+  "schema": {
+    "type": "object",
+    "properties": {
+      "input": {
+        "type": "array",
+        "items": [
+          {
+            "description": "Color to map into gamut",
+            "type": "color"
+          },
+          {
+            "description": "Target gamut/space (default 'srgb')",
+            "type": "string"
+          }
+        ],
+        "minItems": 1,
+        "maxItems": 2
+      }
+    },
+    "required": ["input"]
+  },
+  "returns": {
+    "type": "color",
+    "description": "Color mapped into the target gamut"
+  },
+  "script": {
+    "type": "https://schema.tokenscript.dev.gcp.tokens.studio/api/v1/core/tokenscript/0/",
+    "script": "./to-gamut.tokenscript"
+  },
+  "examples": [
+    {
+      "description": "Map out-of-gamut P3 color to sRGB",
+      "input": ["oklch(0.8 0.3 150)", "srgb"],
+      "output": "Color with reduced chroma that fits sRGB"
+    },
+    {
+      "description": "In-gamut color returns unchanged",
+      "input": ["#ff0000"],
+      "output": "#ff0000"
+    }
+  ]
+}

package/src/schemas/functions/to_gamut/to-gamut.tokenscript

@@ -0,0 +1,96 @@
+// to_gamut: Perceptual gamut mapping (CSS Color Level 4 algorithm)
+// Reference: CSS Color Level 4, Section 13.2 Gamut Mapping
+// Reference: https://www.w3.org/TR/css-color-4/#gamut-mapping
+//
+// Maps out-of-gamut colors into sRGB while preserving perceptual
+// intent. Uses OKLCH space with binary search on chroma:
+//   - Lightness and hue are preserved
+//   - Chroma is reduced until the color fits in gamut
+//
+// This is the CSS Gamut Mapping Algorithm (GMA) used by browsers.
+
+variable input: List = {input};
+variable color: Color.OKLCH = input.get(0).to.oklch();
+
+// Target space (default sRGB) - currently only supports sRGB
+variable target_space: String = "srgb";
+if (input.length() > 1) [
+    target_space = input.get(1);
+];
+
+// Constants
+variable epsilon: Number = 0.0001;
+variable neg_epsilon: Number = 0 - epsilon;
+variable one_plus_eps: Number = 1 + epsilon;
+
+// Check if already in gamut by converting and checking bounds
+variable test_color: Color.SRGB = color.to.srgb();
+variable in_gamut: Boolean = true;
+
+// Check if sRGB values are in range [0, 1]
+if (test_color.r < neg_epsilon) [ in_gamut = false; ];
+if (test_color.r > one_plus_eps) [ in_gamut = false; ];
+if (test_color.g < neg_epsilon) [ in_gamut = false; ];
+if (test_color.g > one_plus_eps) [ in_gamut = false; ];
+if (test_color.b < neg_epsilon) [ in_gamut = false; ];
+if (test_color.b > one_plus_eps) [ in_gamut = false; ];
+
+// If already in gamut, return clamped version
+if (in_gamut) [
+    variable clamped: Color.SRGB;
+    clamped.r = min(1, max(0, test_color.r));
+    clamped.g = min(1, max(0, test_color.g));
+    clamped.b = min(1, max(0, test_color.b));
+    return clamped;
+];
+
+// Binary search: reduce chroma until in gamut
+variable min_c: Number = 0;
+variable max_c: Number = color.c;
+variable current: Color.OKLCH;
+current.l = color.l;
+current.h = color.h;
+
+variable iterations: Number = 0;
+variable max_iterations: Number = 25;
+
+while (max_c - min_c > epsilon) [
+    if (iterations >= max_iterations) [
+        max_c = min_c;  // Force exit
+    ];
+    
+    variable mid_c: Number = (min_c + max_c) / 2;
+    current.c = mid_c;
+    
+    variable test: Color.SRGB = current.to.srgb();
+    variable test_in_gamut: Boolean = true;
+    
+    if (test.r < neg_epsilon) [ test_in_gamut = false; ];
+    if (test.r > one_plus_eps) [ test_in_gamut = false; ];
+    if (test.g < neg_epsilon) [ test_in_gamut = false; ];
+    if (test.g > one_plus_eps) [ test_in_gamut = false; ];
+    if (test.b < neg_epsilon) [ test_in_gamut = false; ];
+    if (test.b > one_plus_eps) [ test_in_gamut = false; ];
+    
+    if (test_in_gamut) [
+        // We can try higher chroma
+        min_c = mid_c;
+    ] else [
+        // Need to reduce chroma
+        max_c = mid_c;
+    ];
+    
+    iterations = iterations + 1;
+];
+
+// Use the last valid chroma
+current.c = min_c;
+variable result: Color.SRGB = current.to.srgb();
+
+// Final clamp for any floating point errors
+variable final_result: Color.SRGB;
+final_result.r = min(1, max(0, result.r));
+final_result.g = min(1, max(0, result.g));
+final_result.b = min(1, max(0, result.b));
+
+return final_result;

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

@@ -0,0 +1,97 @@
+/**
+ * Unit tests for the to_gamut function
+ * Maps colors into sRGB gamut
+ */
+
+import { executeWithSchema, getBundledSchema } from "@tests/helpers/schema-test-utils";
+import { describe, expect, it } from "vitest";
+import type { FunctionSpecification } from "@/bundler/types";
+
+describe("to_gamut function", () => {
+  describe("Schema Definition", () => {
+    it("should have correct schema structure", async () => {
+      const schema = (await getBundledSchema("to_gamut", "function")) as FunctionSpecification;
+
+      expect(schema.name).toBe("to_gamut");
+      expect(schema.type).toBe("function");
+    });
+  });
+
+  describe("Function Execution", () => {
+    it("should return in-gamut color unchanged", async () => {
+      const result = await executeWithSchema(
+        "to_gamut",
+        "function",
+        `
+        variable red: Color.SRGB;
+        red.r = 1; red.g = 0; red.b = 0;
+        to_gamut(red)
+        `,
+      );
+
+      expect(result).toBeDefined();
+      const r = (result as any).value?.r?.value ?? (result as any).value?.r;
+      expect(r).toBeCloseTo(1, 1);
+    });
+
+    it("should handle white", async () => {
+      const result = await executeWithSchema(
+        "to_gamut",
+        "function",
+        `
+        variable white: Color.SRGB;
+        white.r = 1; white.g = 1; white.b = 1;
+        to_gamut(white)
+        `,
+      );
+
+      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", async () => {
+      const result = await executeWithSchema(
+        "to_gamut",
+        "function",
+        `
+        variable black: Color.SRGB;
+        black.r = 0; black.g = 0; black.b = 0;
+        to_gamut(black)
+        `,
+      );
+
+      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);
+    });
+
+    it("should handle grayscale colors", async () => {
+      const result = await executeWithSchema(
+        "to_gamut",
+        "function",
+        `
+        variable gray: Color.SRGB;
+        gray.r = 0.5; gray.g = 0.5; gray.b = 0.5;
+        to_gamut(gray)
+        `,
+      );
+
+      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 remain gray
+      expect(Math.abs(r - g)).toBeLessThan(0.05);
+      expect(Math.abs(g - b)).toBeLessThan(0.05);
+    });
+  });
+});

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

@@ -0,0 +1,20 @@
+{
+  "name": "Triadic",
+  "type": "function",
+  "description": "Generates triadic colors - three hues equally spaced 120° apart on the color wheel. Creates vibrant, balanced palettes with high contrast.",
+  "keyword": "triadic",
+  "input": {
+    "type": "object",
+    "properties": {
+      "color": {
+        "type": "color",
+        "description": "Base color"
+      }
+    }
+  },
+  "script": {
+    "type": "/api/v1/core/tokenscript/0/",
+    "script": "./triadic.tokenscript"
+  },
+  "requirements": ["/api/v1/core/oklch-color/0/", "/api/v1/core/srgb-color/0/"]
+}

package/src/schemas/functions/triadic/triadic.tokenscript

@@ -0,0 +1,33 @@
+// Generate triadic colors (120° apart)
+// Returns [base, base+120°, base+240°]
+//
+// Use case: Vibrant, balanced palettes
+// Example: Red → Green → Blue
+
+variable input: List = {input};
+variable base: Color.OKLCH = input.get(0).to.oklch();
+
+variable result: List;
+
+// Base color
+result = result, base.to.srgb();
+
+// +120°
+variable h2: Number = base.h + 120;
+if (h2 >= 360) [ h2 = h2 - 360; ];
+variable c2: Color.OKLCH;
+c2.l = base.l; c2.c = base.c; c2.h = h2;
+result = result, c2.to.srgb();
+
+// +240°
+variable h3: Number = base.h + 240;
+if (h3 >= 360) [ h3 = h3 - 360; ];
+variable c3: Color.OKLCH;
+c3.l = base.l; c3.c = base.c; c3.h = h3;
+result = result, c3.to.srgb();
+
+return result;
+
+
+
+

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

@@ -0,0 +1,64 @@
+/**
+ * Unit tests for the Triadic function
+ * Generates triadic colors (120° apart on color wheel)
+ */
+
+import { executeWithSchema, getBundledSchema } from "@tests/helpers/schema-test-utils";
+import { describe, expect, it } from "vitest";
+import type { FunctionSpecification } from "@/bundler/types";
+
+describe("Triadic Function", () => {
+  describe("Schema Definition", () => {
+    it("should have correct schema structure", async () => {
+      const schema = (await getBundledSchema("triadic", "function")) as FunctionSpecification;
+
+      expect(schema.name).toBe("Triadic");
+      expect(schema.type).toBe("function");
+      expect(schema.keyword).toBe("triadic");
+    });
+  });
+
+  describe("Function Execution", () => {
+    it("should generate 3 colors", async () => {
+      const result = await executeWithSchema(
+        "triadic",
+        "function",
+        `
+        variable base: Color.SRGB;
+        base.r = 0.9; base.g = 0.2; base.b = 0.2;
+        triadic(base)
+        `,
+      );
+
+      expect(result).toBeDefined();
+    });
+
+    it("should include the base color", async () => {
+      const result = await executeWithSchema(
+        "triadic",
+        "function",
+        `
+        variable blue: Color.SRGB;
+        blue.r = 0.2; blue.g = 0.3; blue.b = 0.9;
+        triadic(blue)
+        `,
+      );
+
+      expect(result).toBeDefined();
+    });
+
+    it("should preserve lightness across colors", async () => {
+      const result = await executeWithSchema(
+        "triadic",
+        "function",
+        `
+        variable mid: Color.SRGB;
+        mid.r = 0.6; mid.g = 0.5; mid.b = 0.4;
+        triadic(mid)
+        `,
+      );
+
+      expect(result).toBeDefined();
+    });
+  });
+});

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

@@ -0,0 +1,48 @@
+{
+  "name": "vibrant",
+  "type": "function",
+  "description": "Increases a color's chroma toward a vibrant level. Preserves lightness and hue while boosting colorfulness. The optional amount parameter controls the intensity (0-1, default 0.5). Uses OKLCH for perceptually uniform chroma adjustment. Useful for creating attention-grabbing accents or active states from muted base colors.",
+  "keyword": "vibrant",
+  "requirements": ["/api/v1/core/srgb-color/0/", "/api/v1/core/oklch-color/0/"],
+  "schema": {
+    "type": "object",
+    "properties": {
+      "input": {
+        "type": "array",
+        "items": [
+          {
+            "description": "Color to make vibrant",
+            "type": "color"
+          },
+          {
+            "description": "Amount (0-1, default 0.5). Higher = more vibrant.",
+            "type": "number"
+          }
+        ],
+        "minItems": 1,
+        "maxItems": 2
+      }
+    },
+    "required": ["input"]
+  },
+  "returns": {
+    "type": "color",
+    "description": "More vibrant version of the color"
+  },
+  "script": {
+    "type": "https://schema.tokenscript.dev.gcp.tokens.studio/api/v1/core/tokenscript/0/",
+    "script": "./vibrant.tokenscript"
+  },
+  "examples": [
+    {
+      "description": "Make muted blue more vibrant",
+      "input": ["#6688aa"],
+      "output": "More saturated blue"
+    },
+    {
+      "description": "Full vibrancy",
+      "input": ["#808080", 1],
+      "output": "Still gray (no hue to enhance)"
+    }
+  ]
+}

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

@@ -0,0 +1,55 @@
+/**
+ * Unit tests for the vibrant function
+ * Increases chroma toward maximum
+ */
+
+import { executeWithSchema, getBundledSchema } from "@tests/helpers/schema-test-utils";
+import { describe, expect, it } from "vitest";
+import type { FunctionSpecification } from "@/bundler/types";
+
+describe("vibrant function", () => {
+  describe("Schema Definition", () => {
+    it("should have correct schema structure", async () => {
+      const schema = (await getBundledSchema("vibrant", "function")) as FunctionSpecification;
+
+      expect(schema.name).toBe("vibrant");
+      expect(schema.type).toBe("function");
+    });
+  });
+
+  describe("Function Execution", () => {
+    it("should increase saturation of muted colors", async () => {
+      const result = await executeWithSchema(
+        "vibrant",
+        "function",
+        `
+        variable muted_blue: Color.SRGB;
+        muted_blue.r = 0.4; muted_blue.g = 0.5; muted_blue.b = 0.6;
+        vibrant(muted_blue).to.srgb()
+        `,
+      );
+
+      expect(result).toBeDefined();
+      expect((result as any).constructor.name).toBe("ColorSymbol");
+    });
+
+    it("should have minimal effect on already vibrant colors", async () => {
+      const result = await executeWithSchema(
+        "vibrant",
+        "function",
+        `
+        variable red: Color.SRGB;
+        red.r = 1; red.g = 0; red.b = 0;
+        vibrant(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 be predominantly red
+      expect(r).toBeGreaterThan(0.7);
+      expect(g).toBeLessThan(0.5);
+    });
+  });
+});

package/src/schemas/functions/vibrant/vibrant.tokenscript

@@ -0,0 +1,29 @@
+// vibrant: Increase chroma toward maximum colorfulness
+// Preserves lightness and hue
+// Amount controls how much to boost (0-1)
+
+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);
+];
+
+// Target maximum chroma for sRGB at this lightness (approximate)
+// Real max varies by hue and lightness, but 0.3 is a reasonable target
+variable max_chroma: Number = 0.3;
+
+// Increase chroma toward max
+variable current_c: Number = color.c;
+variable new_c: Number = current_c + (max_chroma - current_c) * 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/warmer/schema.json

@@ -0,0 +1,43 @@
+{
+  "name": "warmer",
+  "type": "function",
+  "description": "Shifts a color's hue towards warm colors (orange, ~60° in OKLCH). The amount parameter controls how much to shift, from 0 (no change) to 1 (fully warm). Preserves lightness and chroma.",
+  "keyword": "warmer",
+  "requirements": ["/api/v1/core/srgb-color/0/", "/api/v1/core/oklch-color/0/"],
+  "schema": {
+    "type": "object",
+    "properties": {
+      "input": {
+        "type": "array",
+        "items": [
+          {
+            "description": "Color to warm",
+            "type": "color"
+          },
+          {
+            "description": "Amount to shift (0-1), default 0.25",
+            "type": "number"
+          }
+        ],
+        "minItems": 1,
+        "maxItems": 2
+      }
+    },
+    "required": ["input"]
+  },
+  "returns": {
+    "type": "color",
+    "description": "Color shifted towards warm hues"
+  },
+  "script": {
+    "type": "https://schema.tokenscript.dev.gcp.tokens.studio/api/v1/core/tokenscript/0/",
+    "script": "./warmer.tokenscript"
+  },
+  "examples": [
+    {
+      "description": "Make blue warmer",
+      "input": ["#0000ff", 0.5],
+      "output": "Blue shifted towards purple/magenta"
+    }
+  ]
+}

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

@@ -0,0 +1,69 @@
+/**
+ * Unit tests for the warmer function
+ * Shifts hue towards warm colors
+ */
+
+import { executeWithSchema, getBundledSchema } from "@tests/helpers/schema-test-utils";
+import { describe, expect, it } from "vitest";
+import type { FunctionSpecification } from "@/bundler/types";
+
+describe("warmer function", () => {
+  describe("Schema Definition", () => {
+    it("should have correct schema structure", async () => {
+      const schema = (await getBundledSchema("warmer", "function")) as FunctionSpecification;
+
+      expect(schema.name).toBe("warmer");
+      expect(schema.type).toBe("function");
+    });
+  });
+
+  describe("Function Execution", () => {
+    it("should shift blue towards warm (purple)", async () => {
+      const result = await executeWithSchema(
+        "warmer",
+        "function",
+        `
+        variable blue: Color.SRGB;
+        blue.r = 0; blue.g = 0; blue.b = 1;
+        warmer(blue, 0.5).to.srgb()
+        `,
+      );
+
+      expect(result).toBeDefined();
+      // Blue shifted warm should have more red
+      const r = (result as any).value?.r?.value ?? (result as any).value?.r;
+      expect(r).toBeGreaterThan(0.1);
+    });
+
+    it("should shift green towards warm (yellow)", async () => {
+      const result = await executeWithSchema(
+        "warmer",
+        "function",
+        `
+        variable green: Color.SRGB;
+        green.r = 0; green.g = 1; green.b = 0;
+        warmer(green, 0.5).to.srgb()
+        `,
+      );
+
+      expect(result).toBeDefined();
+      // Green shifted warm should have more red
+      const r = (result as any).value?.r?.value ?? (result as any).value?.r;
+      expect(r).toBeGreaterThan(0.1);
+    });
+
+    it("should use default amount if not provided", async () => {
+      const result = await executeWithSchema(
+        "warmer",
+        "function",
+        `
+        variable blue: Color.SRGB;
+        blue.r = 0; blue.g = 0; blue.b = 1;
+        warmer(blue).to.srgb()
+        `,
+      );
+
+      expect(result).toBeDefined();
+    });
+  });
+});

package/src/schemas/functions/warmer/warmer.tokenscript

@@ -0,0 +1,45 @@
+// warmer: Shift hue towards warm colors
+//
+// Warm colors are centered around orange (~60° in OKLCH).
+// The function interpolates the hue towards this target via
+// the shortest angular path on the hue wheel.
+//
+// Parameters:
+//   color  - Input color
+//   amount - Shift amount (0 = no change, 1 = fully warm), default 0.25
+//
+// Preserves lightness and chroma.
+
+variable input: List = {input};
+variable color: Color.OKLCH = input.get(0).to.oklch();
+variable amount: Number = 0.25;
+
+if (input.length() > 1) [
+    amount = input.get(1);
+];
+
+// Warm hue target (orange in OKLCH is around 60°)
+variable warm_hue: Number = 60;
+
+// Calculate shortest path hue difference
+variable hue_diff: Number = warm_hue - color.h;
+
+// Wrap to shortest path
+if (hue_diff > 180) [ hue_diff = hue_diff - 360; ];
+if (hue_diff < -180) [ hue_diff = hue_diff + 360; ];
+
+// Apply interpolation
+variable new_hue: Number = color.h + (hue_diff * amount);
+
+// Normalize to 0-360
+if (new_hue < 0) [ new_hue = new_hue + 360; ];
+if (new_hue >= 360) [ new_hue = new_hue - 360; ];
+
+// Create result
+variable result: Color.OKLCH;
+result.l = color.l;
+result.c = color.c;
+result.h = new_hue;
+
+return result;
+