@tokens-studio/tokenscript-schemas 0.0.11 → 0.0.13

package/src/schemas/functions/shade_scale/shade-scale.tokenscript

@@ -0,0 +1,61 @@
+// Generate a design system shade scale (like Tailwind 50-900)
+// Input color becomes the middle (500) shade
+//
+// Lightness distribution:
+//   50: ~0.97  (very light)
+//  100: ~0.93
+//  200: ~0.87
+//  300: ~0.78
+//  400: ~0.67
+//  500: input lightness (base)
+//  600: ~0.52
+//  700: ~0.42
+//  800: ~0.32
+//  900: ~0.22 (very dark)
+//
+// Chroma is scaled to avoid washed-out lights and muddy darks
+
+variable input: List = {input};
+variable base: Color.OKLCH = input.get(0).to.oklch();
+
+variable count: Number = 10;
+if (input.length() > 1) [
+    count = input.get(1);
+];
+
+// Target lightness values for standard 10-step scale
+// These are perceptually optimized for OKLCH
+variable lightness_targets: List = 0.97, 0.93, 0.87, 0.78, 0.67, 0.55, 0.45, 0.35, 0.27, 0.20;
+
+variable base_h: Number = base.h;
+variable base_c: Number = base.c;
+
+variable result: List;
+variable i: Number = 0;
+variable target_l: Number = 0;
+variable l_factor: Number = 0;
+variable scaled_c: Number = 0;
+variable shade: Color.OKLCH;
+
+while (i < count) [
+    target_l = lightness_targets.get(i);
+    
+    // Scale chroma based on lightness
+    // Chroma peaks in midtones, reduces at extremes
+    l_factor = 1 - abs(target_l - 0.55) * 1.2;
+    if (l_factor < 0.3) [ l_factor = 0.3; ];
+    if (l_factor > 1.2) [ l_factor = 1.2; ];
+    
+    scaled_c = base_c * l_factor;
+    if (scaled_c > 0.4) [ scaled_c = 0.4; ];
+    
+    shade.l = target_l;
+    shade.c = scaled_c;
+    shade.h = base_h;
+    
+    result = result, shade.to.srgb();
+    i = i + 1;
+];
+
+return result;
+

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

@@ -0,0 +1,64 @@
+/**
+ * Unit tests for the Shade Scale function
+ * Generates a design system shade scale (like Tailwind 50-900)
+ */
+
+import { executeWithSchema, getBundledSchema } from "@tests/helpers/schema-test-utils";
+import { describe, expect, it } from "vitest";
+import type { FunctionSpecification } from "@/bundler/types";
+
+describe("Shade Scale Function", () => {
+  describe("Schema Definition", () => {
+    it("should have correct schema structure", async () => {
+      const schema = (await getBundledSchema("shade_scale", "function")) as FunctionSpecification;
+
+      expect(schema.name).toBe("Shade Scale");
+      expect(schema.type).toBe("function");
+      expect(schema.keyword).toBe("shade_scale");
+    });
+  });
+
+  describe("Function Execution", () => {
+    it("should generate 10 shades by default", async () => {
+      const result = await executeWithSchema(
+        "shade_scale",
+        "function",
+        `
+        variable base: Color.SRGB;
+        base.r = 0.2; base.g = 0.5; base.b = 0.9;
+        shade_scale(base)
+        `,
+      );
+
+      expect(result).toBeDefined();
+    });
+
+    it("should generate specified number of shades", async () => {
+      const result = await executeWithSchema(
+        "shade_scale",
+        "function",
+        `
+        variable base: Color.SRGB;
+        base.r = 0.9; base.g = 0.3; base.b = 0.4;
+        shade_scale(base, 5)
+        `,
+      );
+
+      expect(result).toBeDefined();
+    });
+
+    it("should preserve hue across shades", async () => {
+      const result = await executeWithSchema(
+        "shade_scale",
+        "function",
+        `
+        variable green: Color.SRGB;
+        green.r = 0.2; green.g = 0.7; green.b = 0.3;
+        shade_scale(green, 10)
+        `,
+      );
+
+      expect(result).toBeDefined();
+    });
+  });
+});

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

@@ -0,0 +1,24 @@
+{
+  "name": "Split Complement",
+  "type": "function",
+  "description": "Generates split-complementary colors - base color plus two colors adjacent to its complement. More nuanced than direct complement, less tension than triadic.",
+  "keyword": "split_complement",
+  "input": {
+    "type": "object",
+    "properties": {
+      "color": {
+        "type": "color",
+        "description": "Base color"
+      },
+      "angle": {
+        "type": "number",
+        "description": "Degrees from complement for split colors. Default is 30"
+      }
+    }
+  },
+  "script": {
+    "type": "/api/v1/core/tokenscript/0/",
+    "script": "./split-complement.tokenscript"
+  },
+  "requirements": ["/api/v1/core/oklch-color/0/", "/api/v1/core/srgb-color/0/"]
+}

package/src/schemas/functions/split_complement/split-complement.tokenscript

@@ -0,0 +1,38 @@
+// Generate split-complementary colors
+// Returns [base, complement-angle, complement+angle]
+//
+// Use case: Balanced contrast with more variety than complement
+// Example: Blue → Orange-Red, Orange-Yellow (instead of just Orange)
+
+variable input: List = {input};
+variable base: Color.OKLCH = input.get(0).to.oklch();
+
+variable angle: Number = 30;
+if (input.length() > 1) [
+    angle = input.get(1);
+];
+
+variable complement_h: Number = base.h + 180;
+if (complement_h >= 360) [ complement_h = complement_h - 360; ];
+
+variable result: List;
+
+// Base color
+result = result, base.to.srgb();
+
+// Complement - angle
+variable h2: Number = complement_h - angle;
+if (h2 < 0) [ h2 = h2 + 360; ];
+variable c2: Color.OKLCH;
+c2.l = base.l; c2.c = base.c; c2.h = h2;
+result = result, c2.to.srgb();
+
+// Complement + angle
+variable h3: Number = complement_h + angle;
+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/split_complement/unit.test.ts

@@ -0,0 +1,53 @@
+/**
+ * Unit tests for the Split Complement function
+ * Generates split complementary colors (150° and 210° from base)
+ */
+
+import { executeWithSchema, getBundledSchema } from "@tests/helpers/schema-test-utils";
+import { describe, expect, it } from "vitest";
+import type { FunctionSpecification } from "@/bundler/types";
+
+describe("Split Complement Function", () => {
+  describe("Schema Definition", () => {
+    it("should have correct schema structure", async () => {
+      const schema = (await getBundledSchema(
+        "split_complement",
+        "function",
+      )) as FunctionSpecification;
+
+      expect(schema.name).toBe("Split Complement");
+      expect(schema.type).toBe("function");
+      expect(schema.keyword).toBe("split_complement");
+    });
+  });
+
+  describe("Function Execution", () => {
+    it("should generate 3 colors", async () => {
+      const result = await executeWithSchema(
+        "split_complement",
+        "function",
+        `
+        variable base: Color.SRGB;
+        base.r = 0.9; base.g = 0.5; base.b = 0.2;
+        split_complement(base)
+        `,
+      );
+
+      expect(result).toBeDefined();
+    });
+
+    it("should include the base color", async () => {
+      const result = await executeWithSchema(
+        "split_complement",
+        "function",
+        `
+        variable purple: Color.SRGB;
+        purple.r = 0.6; purple.g = 0.2; purple.b = 0.8;
+        split_complement(purple)
+        `,
+      );
+
+      expect(result).toBeDefined();
+    });
+  });
+});

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

@@ -0,0 +1,28 @@
+{
+  "name": "Steps",
+  "type": "function",
+  "description": "Generates a list of colors interpolated between two colors in OKLCH space. Perfect for gradient stops.",
+  "keyword": "steps",
+  "input": {
+    "type": "object",
+    "properties": {
+      "color1": {
+        "type": "color",
+        "description": "Start color"
+      },
+      "color2": {
+        "type": "color",
+        "description": "End color"
+      },
+      "count": {
+        "type": "number",
+        "description": "Number of steps (including start and end). Default is 5"
+      }
+    }
+  },
+  "script": {
+    "type": "/api/v1/core/tokenscript/0/",
+    "script": "./steps.tokenscript"
+  },
+  "requirements": ["/api/v1/core/oklch-color/0/", "/api/v1/core/srgb-color/0/"]
+}

package/src/schemas/functions/steps/steps.tokenscript

@@ -0,0 +1,54 @@
+// Generate gradient steps between two colors in OKLCH space
+// Returns a List of colors from start to end (inclusive)
+//
+// Uses perceptually uniform interpolation with shortest hue path
+
+variable input: List = {input};
+variable color1: Color.OKLCH = input.get(0).to.oklch();
+variable color2: Color.OKLCH = input.get(1).to.oklch();
+
+// Default count is 5
+variable count: Number = 5;
+if (input.length() > 2) [
+    count = input.get(2);
+];
+
+// Calculate hue difference (shortest path)
+variable h1: Number = color1.h;
+variable h2: Number = color2.h;
+variable h_diff: Number = h2 - h1;
+if (h_diff > 180) [ h_diff = h_diff - 360; ];
+if (h_diff < -180) [ h_diff = h_diff + 360; ];
+
+// Generate steps
+variable result: List;
+variable i: Number = 0;
+variable t: Number = 0;
+variable step_l: Number = 0;
+variable step_c: Number = 0;
+variable step_h: Number = 0;
+variable step_color: Color.OKLCH;
+
+while (i < count) [
+    t = i / (count - 1);
+    
+    // Interpolate each component
+    step_l = color1.l + (color2.l - color1.l) * t;
+    step_c = color1.c + (color2.c - color1.c) * t;
+    step_h = h1 + h_diff * t;
+    
+    // Normalize hue
+    if (step_h < 0) [ step_h = step_h + 360; ];
+    if (step_h >= 360) [ step_h = step_h - 360; ];
+    
+    // Create color and add to list
+    step_color.l = step_l;
+    step_color.c = step_c;
+    step_color.h = step_h;
+    
+    result = result, step_color.to.srgb();
+    i = i + 1;
+];
+
+return result;
+

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

@@ -0,0 +1,71 @@
+/**
+ * Unit tests for the Steps function
+ * Generates gradient stops 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("Steps Function", () => {
+  describe("Schema Definition", () => {
+    it("should have correct schema structure", async () => {
+      const schema = (await getBundledSchema("steps", "function")) as FunctionSpecification;
+
+      expect(schema.name).toBe("Steps");
+      expect(schema.type).toBe("function");
+      expect(schema.keyword).toBe("steps");
+    });
+  });
+
+  describe("Function Execution", () => {
+    it("should generate 5 steps by default", async () => {
+      const result = await executeWithSchema(
+        "steps",
+        "function",
+        `
+        variable start: Color.SRGB;
+        start.r = 1; start.g = 0; start.b = 0;
+        variable end: Color.SRGB;
+        end.r = 0; end.g = 0; end.b = 1;
+        steps(start, end)
+        `,
+      );
+
+      // Result should be a list
+      expect(result).toBeDefined();
+    });
+
+    it("should generate specified number of steps", async () => {
+      const result = await executeWithSchema(
+        "steps",
+        "function",
+        `
+        variable start: Color.SRGB;
+        start.r = 0; start.g = 0; start.b = 0;
+        variable end: Color.SRGB;
+        end.r = 1; end.g = 1; end.b = 1;
+        steps(start, end, 3)
+        `,
+      );
+
+      expect(result).toBeDefined();
+    });
+
+    it("should include start and end colors", async () => {
+      const result = await executeWithSchema(
+        "steps",
+        "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;
+        steps(white, black, 5)
+        `,
+      );
+
+      expect(result).toBeDefined();
+    });
+  });
+});

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

@@ -0,0 +1,20 @@
+{
+  "name": "Tetradic",
+  "type": "function",
+  "description": "Generates tetradic (square) colors - four hues equally spaced 90° apart. Creates rich, complex palettes with two complementary pairs.",
+  "keyword": "tetradic",
+  "input": {
+    "type": "object",
+    "properties": {
+      "color": {
+        "type": "color",
+        "description": "Base color"
+      }
+    }
+  },
+  "script": {
+    "type": "/api/v1/core/tokenscript/0/",
+    "script": "./tetradic.tokenscript"
+  },
+  "requirements": ["/api/v1/core/oklch-color/0/", "/api/v1/core/srgb-color/0/"]
+}

package/src/schemas/functions/tetradic/tetradic.tokenscript

@@ -0,0 +1,40 @@
+// Generate tetradic (square) colors (90° apart)
+// Returns [base, base+90°, base+180°, base+270°]
+//
+// Use case: Rich, complex palettes
+// Contains two complementary pairs
+
+variable input: List = {input};
+variable base: Color.OKLCH = input.get(0).to.oklch();
+
+variable result: List;
+
+// Base color (0°)
+result = result, base.to.srgb();
+
+// +90°
+variable h2: Number = base.h + 90;
+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();
+
+// +180° (complement)
+variable h3: Number = base.h + 180;
+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();
+
+// +270°
+variable h4: Number = base.h + 270;
+if (h4 >= 360) [ h4 = h4 - 360; ];
+variable c4: Color.OKLCH;
+c4.l = base.l; c4.c = base.c; c4.h = h4;
+result = result, c4.to.srgb();
+
+return result;
+
+
+
+

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

@@ -0,0 +1,50 @@
+/**
+ * Unit tests for the Tetradic function
+ * Generates tetradic colors (90° 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("Tetradic Function", () => {
+  describe("Schema Definition", () => {
+    it("should have correct schema structure", async () => {
+      const schema = (await getBundledSchema("tetradic", "function")) as FunctionSpecification;
+
+      expect(schema.name).toBe("Tetradic");
+      expect(schema.type).toBe("function");
+      expect(schema.keyword).toBe("tetradic");
+    });
+  });
+
+  describe("Function Execution", () => {
+    it("should generate 4 colors", async () => {
+      const result = await executeWithSchema(
+        "tetradic",
+        "function",
+        `
+        variable base: Color.SRGB;
+        base.r = 0.8; base.g = 0.2; base.b = 0.4;
+        tetradic(base)
+        `,
+      );
+
+      expect(result).toBeDefined();
+    });
+
+    it("should include the base color", async () => {
+      const result = await executeWithSchema(
+        "tetradic",
+        "function",
+        `
+        variable green: Color.SRGB;
+        green.r = 0.2; green.g = 0.8; green.b = 0.3;
+        tetradic(green)
+        `,
+      );
+
+      expect(result).toBeDefined();
+    });
+  });
+});

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

@@ -0,0 +1,32 @@
+{
+  "name": "Tint Scale",
+  "type": "function",
+  "description": "Creates a sequential scale of tints from a base color. Varies lightness while preserving hue and adjusting chroma proportionally. Perfect for sequential/quantitative data visualization.",
+  "keyword": "tint_scale",
+  "input": {
+    "type": "object",
+    "properties": {
+      "color": {
+        "type": "color",
+        "description": "Base color for the scale"
+      },
+      "count": {
+        "type": "number",
+        "description": "Number of tints to generate. Default is 9"
+      },
+      "light_start": {
+        "type": "number",
+        "description": "Lightness of lightest tint (0-1). Default is 0.95"
+      },
+      "light_end": {
+        "type": "number",
+        "description": "Lightness of darkest tint (0-1). Default is 0.25"
+      }
+    }
+  },
+  "script": {
+    "type": "/api/v1/core/tokenscript/0/",
+    "script": "./tint-scale.tokenscript"
+  },
+  "requirements": ["/api/v1/core/oklch-color/0/", "/api/v1/core/srgb-color/0/"]
+}

package/src/schemas/functions/tint_scale/tint-scale.tokenscript

@@ -0,0 +1,71 @@
+// Create a sequential tint scale from a base color
+// Varies lightness while preserving hue and scaling chroma
+//
+// Ideal for: choropleth maps, intensity scales, single-hue heatmaps
+// Chroma is scaled proportionally to maintain color harmony
+
+variable input: List = {input};
+variable base: Color.OKLCH = input.get(0).to.oklch();
+
+// Default count is 9
+variable count: Number = 9;
+if (input.length() > 1) [
+    count = input.get(1);
+];
+
+// Default light_start is 0.95 (nearly white)
+variable light_start: Number = 0.95;
+if (input.length() > 2) [
+    light_start = input.get(2);
+];
+
+// Default light_end is 0.25 (dark)
+variable light_end: Number = 0.25;
+if (input.length() > 3) [
+    light_end = input.get(3);
+];
+
+// Base color properties
+variable base_h: Number = base.h;
+variable base_c: Number = base.c;
+variable base_l: Number = base.l;
+
+// Calculate chroma scaling factor (chroma decreases at extreme lightness)
+variable max_c: Number = base_c * 1.2;
+
+variable result: List;
+variable i: Number = 0;
+variable t: Number = 0;
+variable step_l: Number = 0;
+variable l_dist: Number = 0;
+variable chroma_scale: Number = 0;
+variable step_c: Number = 0;
+variable color: Color.OKLCH;
+
+while (i < count) [
+    t = i / (count - 1);
+    
+    // Interpolate lightness
+    step_l = light_start + (light_end - light_start) * t;
+    
+    // Scale chroma based on lightness distance from optimal (~0.6)
+    // Chroma is highest in midtones, lower at extremes
+    l_dist = step_l - 0.6;
+    if (l_dist < 0) [ l_dist = 0 - l_dist; ];
+    chroma_scale = 1 - l_dist * 1.5;
+    if (chroma_scale < 0.1) [ chroma_scale = 0.1; ];
+    step_c = max_c * chroma_scale;
+    
+    // Clamp chroma
+    if (step_c > 0.4) [ step_c = 0.4; ];
+    
+    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/tint_scale/unit.test.ts

@@ -0,0 +1,64 @@
+/**
+ * Unit tests for the Tint Scale function
+ * Creates a sequential tint scale from a base color
+ */
+
+import { executeWithSchema, getBundledSchema } from "@tests/helpers/schema-test-utils";
+import { describe, expect, it } from "vitest";
+import type { FunctionSpecification } from "@/bundler/types";
+
+describe("Tint Scale Function", () => {
+  describe("Schema Definition", () => {
+    it("should have correct schema structure", async () => {
+      const schema = (await getBundledSchema("tint_scale", "function")) as FunctionSpecification;
+
+      expect(schema.name).toBe("Tint Scale");
+      expect(schema.type).toBe("function");
+      expect(schema.keyword).toBe("tint_scale");
+    });
+  });
+
+  describe("Function Execution", () => {
+    it("should generate 9 tints by default", async () => {
+      const result = await executeWithSchema(
+        "tint_scale",
+        "function",
+        `
+        variable base: Color.SRGB;
+        base.r = 0.2; base.g = 0.5; base.b = 0.8;
+        tint_scale(base)
+        `,
+      );
+
+      expect(result).toBeDefined();
+    });
+
+    it("should generate specified number of tints", async () => {
+      const result = await executeWithSchema(
+        "tint_scale",
+        "function",
+        `
+        variable base: Color.SRGB;
+        base.r = 0.6; base.g = 0.3; base.b = 0.7;
+        tint_scale(base, 5)
+        `,
+      );
+
+      expect(result).toBeDefined();
+    });
+
+    it("should preserve hue across scale", async () => {
+      const result = await executeWithSchema(
+        "tint_scale",
+        "function",
+        `
+        variable blue: Color.SRGB;
+        blue.r = 0.1; blue.g = 0.2; blue.b = 0.9;
+        tint_scale(blue, 3)
+        `,
+      );
+
+      expect(result).toBeDefined();
+    });
+  });
+});