@interactivethings/scripts 2.1.4 → 2.2.1

package/dist/cli.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+export declare function main(): Promise<void>;

package/dist/cloudflare/cli.d.ts

@@ -0,0 +1,13 @@
+#!/usr/bin/env node
+type Args = {
+    subcommand: "wait-deployment";
+    commit: string;
+    interval: number;
+    timeout: number;
+    project?: string;
+    email?: string;
+    account_id?: string;
+    config?: string;
+};
+declare const _default: import("../shared/cli").CLIModule<Args>;
+export default _default;

package/dist/cloudflare/cloudflare.d.ts

@@ -0,0 +1,69 @@
+import { IDeploymentService, Deployment } from "../shared/deployment-service";
+/** /!\ Inferred with ChatGPT */
+export type CloudflareDeployment = {
+    id: string;
+    short_id: string;
+    project_id: string;
+    project_name: string;
+    environment: string;
+    url: string;
+    created_on: string;
+    modified_on: string;
+    latest_stage: {
+        name: string;
+        started_on: string;
+        ended_on: string;
+        status: string;
+    };
+    deployment_trigger: {
+        type: string;
+        metadata: {
+            branch: string;
+            commit_hash: string;
+            commit_message: string;
+            commit_dirty: boolean;
+        };
+    };
+    stages: {
+        name: string;
+        started_on: string;
+        ended_on: string;
+        status: string;
+    }[];
+    build_config: {
+        build_command: string;
+        destination_dir: string;
+        build_caching: boolean;
+        root_dir: string;
+        web_analytics_tag: string | null;
+        web_analytics_token: string | null;
+    };
+    source: {
+        type: string;
+        config: {
+            owner: string;
+            repo_name: string;
+            production_branch: string;
+            pr_comments_enabled: boolean;
+        };
+    };
+    env_vars: Record<string, {
+        type: "secret_text" | "plain_text";
+        value: string;
+    }>;
+    compatibility_date: string;
+    compatibility_flags: string[];
+    build_image_major_version: number;
+    usage_model: string;
+    aliases: string[];
+    is_skipped: boolean;
+    production_branch: string;
+};
+export declare class CloudflareDeploymentService implements IDeploymentService {
+    private accountId;
+    private projectName;
+    private email;
+    private apiKey;
+    constructor(accountId: string, projectName: string, email: string, apiKey: string);
+    fetchForCommit(commitSha: string): Promise<Deployment[]>;
+}

package/dist/cloudflare/deployments.d.ts

@@ -0,0 +1,9 @@
+export declare function waitForDeploymentReady({ accountId, project, email, apiKey, commitSha, interval, timeout, }: {
+    accountId: string;
+    project: string;
+    email: string;
+    apiKey: string;
+    commitSha: string;
+    interval: number;
+    timeout: number;
+}): Promise<import("../shared/deployment-service").Deployment | undefined>;

package/dist/config.d.ts

@@ -0,0 +1,92 @@
+import { z } from "zod";
+/**
+ * Figma configuration schema
+ */
+export declare const FigmaAssetConfigSchema: z.ZodObject<{
+    url: z.ZodString;
+    output: z.ZodString;
+    name: z.ZodString;
+}, z.core.$strip>;
+export declare const FigmaConfigSchema: z.ZodObject<{
+    token: z.ZodOptional<z.ZodString>;
+    assets: z.ZodDefault<z.ZodArray<z.ZodObject<{
+        url: z.ZodString;
+        output: z.ZodString;
+        name: z.ZodString;
+    }, z.core.$strip>>>;
+}, z.core.$strip>;
+/**
+ * Tokens Studio configuration schema
+ */
+export declare const TokensStudioConfigSchema: z.ZodObject<{
+    input: z.ZodDefault<z.ZodString>;
+    output: z.ZodOptional<z.ZodString>;
+    handler: z.ZodString;
+}, z.core.$strip>;
+/**
+ * Vercel configuration schema
+ */
+export declare const VercelConfigSchema: z.ZodObject<{
+    team: z.ZodOptional<z.ZodString>;
+    project: z.ZodOptional<z.ZodString>;
+}, z.core.$strip>;
+/**
+ * Cloudflare configuration schema
+ */
+export declare const CloudflareConfigSchema: z.ZodObject<{
+    project: z.ZodOptional<z.ZodString>;
+    email: z.ZodOptional<z.ZodString>;
+    accountId: z.ZodOptional<z.ZodString>;
+}, z.core.$strip>;
+/**
+ * Main IXT Scripts configuration schema
+ */
+export declare const IxtConfigSchema: z.ZodObject<{
+    figma: z.ZodOptional<z.ZodObject<{
+        token: z.ZodOptional<z.ZodString>;
+        assets: z.ZodDefault<z.ZodArray<z.ZodObject<{
+            url: z.ZodString;
+            output: z.ZodString;
+            name: z.ZodString;
+        }, z.core.$strip>>>;
+    }, z.core.$strip>>;
+    tokensStudio: z.ZodOptional<z.ZodObject<{
+        input: z.ZodDefault<z.ZodString>;
+        output: z.ZodOptional<z.ZodString>;
+        handler: z.ZodString;
+    }, z.core.$strip>>;
+    vercel: z.ZodOptional<z.ZodObject<{
+        team: z.ZodOptional<z.ZodString>;
+        project: z.ZodOptional<z.ZodString>;
+    }, z.core.$strip>>;
+    cloudflare: z.ZodOptional<z.ZodObject<{
+        project: z.ZodOptional<z.ZodString>;
+        email: z.ZodOptional<z.ZodString>;
+        accountId: z.ZodOptional<z.ZodString>;
+    }, z.core.$strip>>;
+}, z.core.$strip>;
+export type IxtConfig = z.infer<typeof IxtConfigSchema>;
+export type FigmaConfig = z.infer<typeof FigmaConfigSchema>;
+export type FigmaAssetConfig = z.infer<typeof FigmaAssetConfigSchema>;
+export type TokensStudioConfig = z.infer<typeof TokensStudioConfigSchema>;
+export type VercelConfig = z.infer<typeof VercelConfigSchema>;
+export type CloudflareConfig = z.infer<typeof CloudflareConfigSchema>;
+/**
+ * Helper function for type-safe configuration definition
+ * Provides IntelliSense and validation for the configuration object
+ */
+export declare function defineConfig(config: IxtConfig): IxtConfig;
+/**
+ * Load configuration from a TypeScript file
+ * Only supports .ts configuration files for better type safety
+ */
+export declare function loadConfig(configPath?: string): Promise<IxtConfig>;
+/**
+ * Merge CLI arguments with configuration
+ * CLI arguments take precedence over config file values
+ */
+export declare function mergeConfigWithArgs<T extends Record<string, any>>(config: IxtConfig, args: T, section: keyof IxtConfig): T & Partial<IxtConfig[keyof IxtConfig]>;
+/**
+ * Validate that required values are present after merging config and args
+ */
+export declare function validateRequiredConfig<T extends Record<string, any>>(mergedConfig: T, requiredFields: (keyof T)[]): void;

package/dist/config.js

@@ -107,17 +107,6 @@ exports.IxtConfigSchema = zod_1.z.object({
 function defineConfig(config) {
     return exports.IxtConfigSchema.parse(config);
 }
-/**
- * Default configuration values
- */
-const DEFAULT_CONFIG = {
-    figma: {
-        assets: [],
-    },
-    tokensStudio: {
-        input: "./tokens",
-    },
-};
 /**
  * Load configuration from a TypeScript file
  * Only supports .ts configuration files for better type safety

package/dist/figma/api.d.ts

@@ -0,0 +1,69 @@
+type Color = {
+    r: number;
+    g: number;
+    b: number;
+    a: number;
+};
+type FileId = string;
+type NodeId = string;
+export type FigmaNode = ({
+    type: "RECTANGLE";
+    fills: {
+        type: "SOLID";
+        color: Color;
+    }[];
+    effects: {
+        type: "DROP_SHADOW";
+        offset: {
+            x: number;
+            y: number;
+        };
+        color: Color;
+        radius: number;
+    }[];
+} | {
+    type: "TEXT";
+    style: {
+        fontFamily: string;
+        fontWeight: number;
+        fontSize: number;
+        letterSpacing: number;
+        lineHeightPx: number;
+    };
+}) & {
+    name: string;
+    id: string;
+};
+export declare const createAPI: (figmaToken: string) => {
+    file: {
+        fetch: (fileId: FileId) => Promise<any>;
+    };
+    nodes: {
+        fetch: (fileId: FileId, ids: NodeId[]) => Promise<any>;
+    };
+    styles: {
+        fetch: (fileId: FileId) => Promise<{
+            nodes: {
+                document: FigmaNode;
+            }[];
+        }>;
+    };
+    /**
+     * Given a root node, fetches all exports of the nodes in the tree.
+     * This is especially useful to fetch all icons or assets from a design system.
+     */
+    images: {
+        fetch: (fileId: FileId, nodeIds: string[], { onFetchSources, onFetchImage, }?: {
+            onFetchSources?: (sources: {
+                name: string;
+                format: string;
+            }[]) => void;
+            onFetchImage?: (url: string) => void;
+        }) => Promise<{
+            data: string | Buffer<ArrayBufferLike>;
+            name: string;
+            format: string;
+        }[]>;
+    };
+};
+export {};

package/dist/figma/cli.d.ts

@@ -0,0 +1,30 @@
+/**
+ * This script downloads the assets from Figma and saves them into the repository.
+ * It is configured via the unified ixt configuration system.
+ *
+ * @example ixt.config.js
+ * import { defineConfig } from '@interactivethings/scripts';
+ *
+ * export default defineConfig({
+ *   figma: {
+ *     assets: [{
+ *       name: "illustrations",
+ *       url: "https://www.figma.com/design/ElWWZIcOGFhiT06rzfIwRO/Design-System?node-id=11861-10071",
+ *       output: "src/assets/illustrations"
+ *     }]
+ *   }
+ * });
+ */
+type FigmaArgs = {
+    config?: string;
+    token?: string;
+    name?: string;
+    subcommand: "download";
+} | {
+    config?: string;
+    token?: string;
+    subcommand: "get";
+    url: string;
+};
+declare const _default: import("../shared/cli").CLIModule<FigmaArgs>;
+export default _default;

package/dist/figma/cli.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/figma/images.d.ts

@@ -0,0 +1 @@
+export declare const optimizeImage: (filepath: string) => Promise<void>;

package/dist/figma/utils.d.ts

@@ -0,0 +1,10 @@
+/**
+ * Should parse a URL in the form https://www.figma.com/design/ElWWZIcOGFhiT06rzfIwRO/Design-System-%5BTPW-Mobile-App%5D?node-id=10404-19140&p=f&t=K5K37NzOSt1uwjsX-0
+ * and extracts the pageId and nodeId
+ * The page id is the part just after /design
+ */
+export declare const parseFigmaURL: (urlString: string) => {
+    figmaFileId: string;
+    figmaPageId: string;
+};
+export declare const formatFigmaURL: (figmaFileId: string, figmaPageId: string) => string;

package/dist/index.d.ts

@@ -0,0 +1,8 @@
+/**
+ * @interactivethings/scripts
+ *
+ * A collection of useful development tools by Interactive Things
+ */
+export * from "./types";
+export { defineConfig, type IxtConfig, type FigmaConfig, type TokensStudioConfig, } from "./config";
+export * as tokensStudio from "./tokens-studio";

package/dist/init/cli.d.ts

@@ -0,0 +1,5 @@
+type InitArgs = {
+    force?: boolean;
+};
+declare const _default: import("../shared/cli").CLIModule<InitArgs>;
+export default _default;

package/dist/shared/cli.d.ts

@@ -0,0 +1,32 @@
+import { ArgumentParser } from "argparse";
+/**
+ * Base interface that all CLI modules must implement
+ */
+export interface CLIModule<TArgs = any> {
+    /**
+     * Function to configure the argument parser for this module
+     */
+    configParser: (parser: ArgumentParser) => void;
+    /**
+     * Function to execute the module logic with parsed arguments
+     */
+    run: (args: TArgs) => Promise<void>;
+}
+/**
+ * Configuration object for defining a CLI module
+ */
+export interface CLIModuleConfig<TArgs = any> {
+    /**
+     * Function to configure the argument parser
+     */
+    configParser: (parser: ArgumentParser) => void;
+    /**
+     * Function to execute the module logic
+     */
+    run: (args: TArgs) => Promise<void>;
+}
+/**
+ * Type-safe factory function for creating CLI modules
+ * Provides consistent interface and utilities for all CLI modules
+ */
+export declare function defineCLIModule<TArgs = any>(config: CLIModuleConfig<TArgs>): CLIModule<TArgs>;

package/dist/shared/deployment-service.d.ts

@@ -0,0 +1,7 @@
+export type Deployment = {
+    state: string;
+    url: string;
+};
+export interface IDeploymentService {
+    fetchForCommit: (commitSha: string) => Promise<Deployment[]>;
+}

package/dist/shared/wait-deployment.d.ts

@@ -0,0 +1,7 @@
+import { IDeploymentService } from "./deployment-service";
+export declare function waitForDeploymentReady({ commitSha, interval, timeout, deploymentService, }: {
+    commitSha: string;
+    interval: number;
+    timeout: number;
+    deploymentService: IDeploymentService;
+}): Promise<import("./deployment-service").Deployment | undefined>;

package/dist/tokens-studio/__tests__/fixtures/invalid-transformer.d.ts

@@ -0,0 +1,9 @@
+/**
+ * Invalid transformer for testing error cases
+ * This transformer does not export a transform function
+ */
+declare function someOtherFunction(): string;
+declare const _default: {
+    someOtherFunction: typeof someOtherFunction;
+};
+export default _default;

package/dist/tokens-studio/__tests__/fixtures/test-transformer.d.ts

@@ -0,0 +1,18 @@
+/**
+ * Test transformer for tokens-studio CLI tests
+ * This transformer simply wraps the input tokens with metadata
+ */
+declare function transform(input: {
+    metadata: any;
+    tokenData: any;
+}): {
+    source: string;
+    metadata: any;
+    tokens: any;
+    processed: boolean;
+    transformedAt: string;
+};
+declare const _default: {
+    transform: typeof transform;
+};
+export default _default;

package/dist/tokens-studio/cli.d.ts

@@ -0,0 +1,14 @@
+#!/usr/bin/env node
+/**
+ * CLI entry point for tokens-studio transformations
+ * Supports different transformer handlers via --handler argument
+ */
+type TokenStudioArgs = {
+    config?: string;
+    subcommand: "transform";
+    handler?: string;
+    input?: string;
+    output?: string;
+};
+declare const _default: import("../shared/cli").CLIModule<TokenStudioArgs>;
+export default _default;

package/dist/tokens-studio/cli.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/tokens-studio/index.d.ts

@@ -0,0 +1,9 @@
+/**
+ * Tokens Studio module for @interactivethings/scripts
+ *
+ * This module provides utilities and transformers for working with
+ * tokens exported from Tokens Studio (Figma plugin).
+ */
+export { simplifyValues, kebabCase, mapEntries, maybeParseToNumber, maybeParseToPx, isToken, deepMerge, resolveReferences, formatValues, flattenTokens, makeResolver, mapKeysRecursively, defineTransform, } from "./utils";
+export type { Metadata, TransformInput, TransformerModule, TokenStudioShadowValue, TokenStudioShadowRecord, } from "./types";
+export * as cli from "./cli";

package/dist/tokens-studio/index.js

@@ -39,7 +39,7 @@ var __importStar = (this && this.__importStar) || (function () {
     };
 })();
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.cli = exports.flattenTokens = exports.formatValues = exports.resolveReferences = exports.deepMerge = exports.isToken = exports.maybeParseToPx = exports.maybeParseToNumber = exports.mapEntries = exports.kebabCase = exports.simplifyValues = void 0;
+exports.cli = exports.defineTransform = exports.mapKeysRecursively = exports.makeResolver = exports.flattenTokens = exports.formatValues = exports.resolveReferences = exports.deepMerge = exports.isToken = exports.maybeParseToPx = exports.maybeParseToNumber = exports.mapEntries = exports.kebabCase = exports.simplifyValues = void 0;
 // Export all utility functions
 var utils_1 = require("./utils");
 Object.defineProperty(exports, "simplifyValues", { enumerable: true, get: function () { return utils_1.simplifyValues; } });
@@ -52,5 +52,10 @@ Object.defineProperty(exports, "deepMerge", { enumerable: true, get: function ()
 Object.defineProperty(exports, "resolveReferences", { enumerable: true, get: function () { return utils_1.resolveReferences; } });
 Object.defineProperty(exports, "formatValues", { enumerable: true, get: function () { return utils_1.formatValues; } });
 Object.defineProperty(exports, "flattenTokens", { enumerable: true, get: function () { return utils_1.flattenTokens; } });
+Object.defineProperty(exports, "makeResolver", { enumerable: true, get: function () { return utils_1.makeResolver; } });
+Object.defineProperty(exports, "mapKeysRecursively", { enumerable: true, get: function () { return utils_1.mapKeysRecursively; } });
+Object.defineProperty(exports, "defineTransform", { enumerable: true, get: function () { return utils_1.defineTransform; } });
+// Note: Transformers are now provided as examples in the examples/ directory
+// Users should copy and customize these examples for their specific needs
 // Export the CLI module (for internal use)
 exports.cli = __importStar(require("./cli"));

package/dist/tokens-studio/require.d.ts

@@ -0,0 +1,3 @@
+import { TransformerModule } from "./types";
+declare const ourRequire: (modulePath: string) => Promise<TransformerModule>;
+export { ourRequire };

package/dist/tokens-studio/types.d.ts

@@ -0,0 +1,22 @@
+export interface Metadata {
+    tokenSetOrder: string[];
+}
+export interface TransformInput {
+    metadata: Metadata;
+    tokenData: any;
+}
+export interface TransformerModule {
+    transform: (input: TransformInput) => any;
+}
+export type TokenStudioShadowValue = {
+    color: string;
+    x: string;
+    y: string;
+    blur: string;
+    spread: string;
+};
+export type TokenStudioShadowRecord = Record<string, {
+    value: TokenStudioShadowValue;
+} | {
+    value: TokenStudioShadowValue[];
+}>;

package/dist/tokens-studio/utils.d.ts

@@ -0,0 +1,60 @@
+import { $IntentionalAny } from "../types";
+import { Metadata } from "./types";
+/**
+ * Shared utility functions for tokens-studio transformations
+ */
+/**
+ * Simplifies nested token values by extracting the 'value' property
+ */
+export declare const simplifyValues: (x: {
+    value: unknown;
+} | string | null) => $IntentionalAny;
+/**
+ * Converts space-separated strings to camelCase
+ */
+export declare const kebabCase: (x: string) => string;
+/**
+ * Maps over object entries with a custom mapper function
+ */
+export declare const mapEntries: <K extends string | number | symbol, V, K2 extends string | number | symbol, V2>(obj: Record<K, V>, mapper: (key: K, value: V) => [K2, V2]) => Record<K2, V2>;
+/**
+ * Attempts to parse a string or number to a number, returns original if not possible
+ */
+export declare const maybeParseToNumber: (x: string | number) => string | number;
+/**
+ * Converts a value to pixels (adds 'px' suffix if it's a number)
+ */
+export declare const maybeParseToPx: (x: string | number) => string;
+/**
+ * Type guard to check if an object is a token with value and type properties
+ */
+export declare const isToken: (obj: any) => obj is {
+    value: string;
+    type: string;
+};
+/**
+ * Deep merge utility for combining token objects
+ */
+export declare const deepMerge: (mergedTokens: any, tokenData: any) => void;
+/**
+ * Resolves token references (strings like "{path.to.token}") using a value map
+ */
+export declare const resolveReferences: (obj: any, map: Map<string, string>) => void;
+/**
+ * Formats token values by extracting the value property
+ */
+export declare const formatValues: (v: {
+    type: string;
+    value: string | number;
+}) => string | number;
+export declare const flattenTokens: (v: any, depth: number | undefined, transformKey: (key: string, depth: number) => string) => unknown;
+/** Creates a resolver function for token references */
+export declare const makeResolver: <T extends object>(data: T, keys: (keyof T)[]) => (str: string) => any;
+export declare const mapKeysRecursively: (obj: $IntentionalAny, keyMapper: (key: string) => string) => Record<string, any>;
+export declare const defineTransform: <TInput, TOutput = unknown>(transformFn: (input: {
+    tokenData: TInput;
+    metadata: Metadata;
+}) => TOutput) => (input: {
+    tokenData: TInput;
+    metadata: Metadata;
+}) => TOutput;

package/dist/tokens-studio/utils.js

@@ -1,6 +1,6 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.flattenTokens = exports.formatValues = exports.resolveReferences = exports.deepMerge = exports.isToken = exports.maybeParseToPx = exports.maybeParseToNumber = exports.mapEntries = exports.kebabCase = exports.simplifyValues = void 0;
+exports.defineTransform = exports.mapKeysRecursively = exports.makeResolver = exports.flattenTokens = exports.formatValues = exports.resolveReferences = exports.deepMerge = exports.isToken = exports.maybeParseToPx = exports.maybeParseToNumber = exports.mapEntries = exports.kebabCase = exports.simplifyValues = void 0;
 const remeda_1 = require("remeda");
 /**
  * Shared utility functions for tokens-studio transformations
@@ -154,3 +154,39 @@ const flattenTokens = (v, depth = 0, transformKey) => {
     return v;
 };
 exports.flattenTokens = flattenTokens;
+/** Creates a resolver function for token references */
+const makeResolver = (data, keys) => {
+    const index = {};
+    for (const k of keys) {
+        for (const [vName, value] of Object.entries(data[k])) {
+            if (typeof k !== "string")
+                continue;
+            index[`${k}.${vName}`] = value;
+        }
+    }
+    return (str) => {
+        var _a;
+        if (str[0] === "{" && str[str.length - 1] === "}") {
+            const path = str.substring(1, str.length - 1);
+            return (_a = index[path]) === null || _a === void 0 ? void 0 : _a.value;
+        }
+        else {
+            return str;
+        }
+    };
+};
+exports.makeResolver = makeResolver;
+const mapKeysRecursively = (obj, keyMapper) => {
+    const visitor = (k, v) => {
+        if (typeof v === "object") {
+            return [keyMapper(k), (0, exports.mapEntries)(v, visitor)];
+        }
+        else {
+            return [keyMapper(k), v];
+        }
+    };
+    return (0, exports.mapEntries)(obj, visitor);
+};
+exports.mapKeysRecursively = mapKeysRecursively;
+const defineTransform = (transformFn) => transformFn;
+exports.defineTransform = defineTransform;

package/dist/types.d.ts

@@ -0,0 +1,2 @@
+export type $IntentionalAny = any;
+export type { CLIModule, CLIModuleConfig } from "./shared/cli";

package/dist/vercel/cli.d.ts

@@ -0,0 +1,11 @@
+#!/usr/bin/env node
+type Args = {
+    subcommand: "wait-deployment";
+    commit: string;
+    interval: number;
+    timeout: number;
+    team: string;
+    project: string;
+};
+declare const _default: import("../shared/cli").CLIModule<Args>;
+export default _default;

package/dist/vercel/cli.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/vercel/deployments.d.ts

@@ -0,0 +1,8 @@
+export declare function waitForDeploymentReady({ team, project, commitSha, interval, timeout, accessToken, }: {
+    team: string;
+    project: string;
+    commitSha: string;
+    interval: number;
+    timeout: number;
+    accessToken: string;
+}): Promise<import("../shared/deployment-service").Deployment | undefined>;

package/dist/vercel/vercel.d.ts

@@ -0,0 +1,15 @@
+import { IDeploymentService, Deployment } from "../shared/deployment-service";
+export type VercelDeployment = {
+    state: string;
+    url: string;
+    meta: {
+        githubCommitSha: string;
+    };
+};
+export declare class VercelDeploymentService implements IDeploymentService {
+    private teamId;
+    private projectId;
+    private accessToken;
+    constructor(teamId: string, projectId: string, accessToken: string);
+    fetchForCommit(commitSha: string): Promise<Deployment[]>;
+}

package/examples/README.md

@@ -0,0 +1,62 @@
+# Tokens Studio Transform Examples
+
+This directory contains example transformer handlers that demonstrate how to use the `ixt tokens-studio transform` command with custom transformation logic.
+
+## Development Setup
+
+When working in this repository during development, the TypeScript path mappings are configured to resolve `@interactivethings/scripts/*` imports to the local source files.
+
+To compile and check the examples:
+
+```bash
+npx tsc --noEmit --project tsconfig.examples.json
+```
+
+## Usage
+
+### MUI Transform Example
+
+```bash
+ixt tokens-studio transform --handler ./examples/mui-transform.ts --input ./tokens --output mui-theme.json
+```
+
+### Tailwind Transform Example
+
+```bash
+ixt tokens-studio transform --handler ./examples/tailwind-transform.ts --input ./tokens --output tailwind-theme.json
+```
+
+### Custom Transform Example
+
+```bash
+ixt tokens-studio transform --handler ./examples/custom-transform.js --input ./tokens --output custom-theme.json
+```
+
+## Creating Your Own Transformer
+
+1. Copy one of the example files as a starting point
+2. Modify the `transform` function to suit your needs
+3. The `transform` function receives: `{ metadata, tokenData }`
+4. Return the transformed data object
+
+### Using in Production
+
+When using these examples in your own project after installing `@interactivethings/scripts`:
+
+```typescript
+import {
+  kebabCase,
+  mapEntries /* ... */,
+} from "@interactivethings/scripts/tokens-studio";
+import { $IntentionalAny } from "@interactivethings/scripts/types";
+```
+
+Or using the alias:
+
+```typescript
+import {
+  kebabCase,
+  mapEntries /* ... */,
+} from "@interactivethings/scripts/tokens-studio";
+import { $IntentionalAny } from "@interactivethings/scripts/types";
+```

package/examples/custom-transform.js

@@ -0,0 +1,41 @@
+/**
+ * Example custom transformer handler
+ * This file demonstrates how to create a completely custom transformer
+ *
+ * Usage:
+ * ixt tokens-studio transform --handler ./examples/custom-transform.js --input ./tokens --output theme.json
+ */
+
+module.exports = {
+  transform: (input) => {
+    const { metadata, tokenData } = input;
+
+    // Example: Extract only colors and convert to CSS custom properties
+    const colors = tokenData.core || {};
+
+    const cssVariables = {};
+
+    // Recursively convert tokens to CSS custom property format
+    const convertToCssVars = (obj, prefix = "") => {
+      for (const [key, value] of Object.entries(obj)) {
+        if (value && typeof value === "object" && "value" in value) {
+          // This is a token
+          cssVariables[`--${prefix}${key}`] = value.value;
+        } else if (value && typeof value === "object") {
+          // This is a nested object
+          convertToCssVars(value, `${prefix}${key}-`);
+        }
+      }
+    };
+
+    convertToCssVars(colors, "color-");
+
+    return {
+      cssVariables,
+      metadata: {
+        generatedAt: new Date().toISOString(),
+        tokenSetOrder: metadata.tokenSetOrder,
+      },
+    };
+  },
+};

package/examples/ixt.config.example.ts

@@ -0,0 +1,33 @@
+import { defineConfig } from '@interactivethings/scripts';
+
+export default defineConfig({
+  figma: {
+    // Figma API token (can also be set via FIGMA_TOKEN environment variable)
+    token: process.env.FIGMA_TOKEN,
+    
+    // Assets to download from Figma
+    assets: [
+      {
+        name: "icons",
+        url: "https://www.figma.com/design/ElWWZIcOGFhiT06rzfIwRO/Design-System?node-id=11861-10071",
+        output: "src/assets/icons"
+      },
+      {
+        name: "illustrations",
+        url: "https://www.figma.com/design/ElWWZIcOGFhiT06rzfIwRO/Design-System?node-id=12345-67890",
+        output: "src/assets/illustrations"
+      }
+    ]
+  },
+  
+  tokensStudio: {
+    // Input directory containing design tokens
+    input: "./design-tokens",
+    
+    // Default output file for transformations
+    output: "src/theme/tokens.json",
+    
+    // Default transformer handler
+    handler: "./transforms/mui-transform.ts"
+  }
+});

package/examples/mui-transform.ts

@@ -0,0 +1,158 @@
+/**
+ * MUI transformer for tokens-studio
+ * Transforms tokens exported with tokens-studio in Figma into
+ * a format that is easier to work with when using MUI.
+ */
+
+import { mapValues, pick } from "remeda";
+
+import { $IntentionalAny } from "@interactivethings/scripts/types";
+import {
+  simplifyValues,
+  kebabCase,
+  mapEntries,
+  maybeParseToNumber,
+  maybeParseToPx,
+  makeResolver,
+  defineTransform,
+  type TokenStudioShadowValue,
+  mapKeysRecursively,
+} from "@interactivethings/scripts/tokens-studio";
+
+// Ideally those types should be imported from your theme's type definitions
+// You should change those lines to match your actual theme structure
+// @example
+// ```
+// import tokensStudioTokens from '../path/to/your/tokens-studio/tokens.json';
+// type MUITokenData = typeof tokensStudioTokens
+// ```
+type MUITokenData = {
+  Base: $IntentionalAny;
+  Functional: $IntentionalAny;
+  Elevation: Record<
+    string,
+    { value: TokenStudioShadowValue | TokenStudioShadowValue[] }
+  >;
+  Desktop: $IntentionalAny;
+  Mobile: $IntentionalAny;
+  fontFamilies: $IntentionalAny;
+  lineHeights: $IntentionalAny;
+  fontWeights: $IntentionalAny;
+  fontSize: $IntentionalAny;
+  letterSpacing: $IntentionalAny;
+  textDecoration: $IntentionalAny;
+};
+
+const renameColorKeys = (k: string) => {
+  return kebabCase(
+    k
+      .replace(/-[a-zA-Z0-9]+/, "")
+      .replace(" - ", " ")
+      .replace(",", "")
+      .replace(/^\d+\s+/, "")
+  );
+};
+
+const getPalette = (tokensData: MUITokenData) => {
+  const data = tokensData;
+  const colorKeys = ["Base", "Functional"] as const;
+
+  let palette = pick(data, colorKeys);
+  type Palette = typeof palette;
+  palette = mapValues(palette, simplifyValues);
+  const tpalette = mapKeysRecursively(palette, renameColorKeys) as unknown as {
+    base: Palette["Base"];
+    functional: Palette["Functional"];
+  };
+  palette = {
+    ...tpalette.base,
+    ...pick(tpalette, ["functional"]),
+  };
+  return palette;
+};
+
+const getTypography = (tokensData: MUITokenData) => {
+  const sizes = ["Desktop", "Mobile"] as const;
+  const res = {} as Record<string, $IntentionalAny>;
+  const resolve = makeResolver(tokensData, [
+    "fontFamilies",
+    "lineHeights",
+    "fontWeights",
+    "fontSize",
+    "letterSpacing",
+    "textDecoration",
+  ] as const);
+
+  const cleanupTypographyFns = {
+    fontWeight: (x: string) => {
+      const lowered = x.toLowerCase();
+      if (lowered == "regular") {
+        return 400;
+      }
+      return lowered;
+    },
+    fontSize: maybeParseToNumber,
+    lineHeight: (x: string | number) => maybeParseToPx(maybeParseToNumber(x)),
+    paragraphSpacing: maybeParseToNumber,
+    letterSpacing: maybeParseToNumber,
+  };
+
+  const cleanupTypographyValue = (k: string, v: $IntentionalAny) => {
+    if (k in cleanupTypographyFns) {
+      return [
+        k,
+        cleanupTypographyFns[k as keyof typeof cleanupTypographyFns](v),
+      ] as [string, $IntentionalAny];
+    } else {
+      return [k, v] as [string, $IntentionalAny];
+    }
+  };
+
+  for (const size of sizes) {
+    const typographies = tokensData[size];
+    for (const [typo, typoDataRaw] of Object.entries(typographies)) {
+      const typoData = typoDataRaw as { value: $IntentionalAny };
+      const typoKey = kebabCase(typo.toLowerCase());
+      res[typoKey] = res[typoKey] || {};
+      res[typoKey][size.toLowerCase()] = mapEntries(
+        mapValues(typoData.value, resolve),
+        cleanupTypographyValue
+      );
+    }
+  }
+  return res;
+};
+
+const getShadows = (tokenData: MUITokenData) => {
+  const transformShadow = (shadowData: TokenStudioShadowValue) => {
+    const { color, x, y, blur, spread } = shadowData;
+    return `${x}px ${y}px ${blur}px ${spread}px ${color}`;
+  };
+
+  const shadows = mapEntries(tokenData.Elevation, (k, v) => {
+    const shadowEntry = v as
+      | { value: TokenStudioShadowValue }
+      | { value: TokenStudioShadowValue[] };
+    return [
+      `${Number((k as string).replace("dp", "").replace("pd", ""))}`,
+      Array.isArray(shadowEntry.value)
+        ? (shadowEntry.value as TokenStudioShadowValue[])
+            .map(transformShadow)
+            .join(", ")
+        : transformShadow(shadowEntry.value as TokenStudioShadowValue),
+    ];
+  });
+  return shadows;
+};
+
+export const transform = defineTransform<MUITokenData>((input) => {
+  const palette = getPalette(input.tokenData);
+  const typography = getTypography(input.tokenData);
+  const shadows = getShadows(input.tokenData);
+
+  return {
+    palette,
+    typography,
+    shadows,
+  };
+});

package/examples/tailwind-transform.ts

@@ -0,0 +1,167 @@
+/**
+ * Tailwind transformer for tokens-studio
+ * Transforms tokens exported with tokens-studio in Figma into
+ * a format that is compatible with Tailwind CSS.
+ */
+
+import { mapValues, pick } from "remeda";
+import {
+  resolveReferences,
+  mapEntries,
+  flattenTokens,
+  defineTransform,
+} from "@interactivethings/scripts/tokens-studio";
+import { $IntentionalAny } from "../dist/types";
+
+// Ideally those types should be imported from your theme's type definitions
+// You should change those lines to match your actual theme structure
+// @example
+// ```
+// import coreTokens from '../path/to/your/core/tokens.json';
+// import functionalTokens from '../path/to/your/functional/tokens.json';
+// type TailwindTokenData = {
+//   core: typeof coreTokens;
+//   functional: typeof functionalTokens;
+// };
+// ```
+type TailwindTokenData = {
+  core: $IntentionalAny;
+  functional: $IntentionalAny;
+};
+
+export const transform = defineTransform<TailwindTokenData>((input) => {
+  const mergedTokens = input.tokenData;
+
+  const valueMap = new Map<string, string>();
+  resolveReferences(mergedTokens, valueMap);
+
+  const theme = {
+    colors: {
+      ...pick(mergedTokens.core, [
+        "amber",
+        "blue",
+        "brand",
+        "cyan",
+        "emerald",
+        "fuchsia",
+        "green",
+        "indigo",
+        "light-blue",
+        "lime",
+        "midnight",
+        "monochrome",
+        "orange",
+        "pink",
+        "purple",
+        "red",
+        "rose",
+        "teal",
+        "violet",
+        "yellow",
+      ]),
+      ...pick(mergedTokens.functional, [
+        "primary",
+        "secondary",
+        "tertiary",
+        "error",
+        "success",
+        "warning",
+        "link",
+        "surface",
+        "on-surface",
+        "surface-inverted",
+        "on-surface-inverted",
+        "border",
+        "input",
+        "accent",
+        "qualitative",
+        "pathways",
+      ]),
+    },
+    borderWidth: {
+      ...mergedTokens.functional["border-width"],
+    },
+    borderRadius: {
+      ...mergedTokens.functional["border-radius"],
+    },
+    fontSize: mergedTokens.core["font-size"],
+    fontWeight: mergedTokens.core["font-weight"],
+    lineHeight: mergedTokens.core["line-height"],
+    spacing: mergedTokens.functional.spacing,
+  };
+
+  const transformKey = (key: string, depth: number) => {
+    if (key.startsWith("on-")) {
+      if (depth === 1) {
+        return key.replace("on-", "foreground-");
+      } else {
+        return "foreground";
+      }
+    }
+    if (key === "default") {
+      return "DEFAULT";
+    }
+    return key;
+  };
+
+  const flattenedTheme = mapValues(theme, (x) =>
+    flattenTokens(x, 0, transformKey)
+  ) as {
+    colors: Record<string, string>;
+    borderWidth: Record<string, string>;
+    borderRadius: Record<string, string>;
+    fontSize: Record<
+      "mobile-large" | "mobile-xxxlarge",
+      Record<string, number>
+    >;
+    fontWeight: Record<string, string>;
+    lineHeight: Record<
+      "mobile-large" | "mobile-xxxlarge",
+      Record<string, number>
+    >;
+    spacing: Record<string, string>;
+  };
+
+  const lineHeights = flattenedTheme.lineHeight;
+  const fontWeights = flattenedTheme.fontWeight;
+
+  const finalTheme = {
+    ...flattenedTheme,
+    borderWidth: mapValues(flattenedTheme.borderWidth, (x) => `${x}px`),
+    borderRadius: mapValues(flattenedTheme.borderRadius, (x) => `${x}px`),
+    fontSize: mapEntries(
+      flattenedTheme.fontSize["mobile-large"],
+      (k: string, value) => {
+        return [
+          k.replace(",", ""),
+          [
+            `${value}px`,
+            {
+              lineHeight: lineHeights["mobile-large"][k]
+                ? `${lineHeights["mobile-large"][k]}px`
+                : undefined,
+              fontWeight: fontWeights[k],
+            },
+          ],
+        ];
+      }
+    ),
+    fontWeight: flattenedTheme.fontWeight,
+    lineHeight: mapEntries(
+      flattenedTheme.lineHeight["mobile-large"],
+      (k: string, value) => {
+        return [k.replace(",", ""), `${value}px`];
+      }
+    ),
+    backgroundImage: {
+      "gradient-2":
+        "var(--Gradient-2, linear-gradient(135deg, var(--core-brand-electricblue500, #48A1C7) 20.83%, var(--core-brand-nocturne700, #336476) 87.96%))",
+    },
+    spacing: mapEntries(flattenedTheme.spacing, (k, v) => [
+      k.replace("spacing-", ""),
+      `${v}px`,
+    ]),
+  };
+
+  return finalTheme;
+});

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@interactivethings/scripts",
-  "version": "2.1.4",
+  "version": "2.2.1",
   "main": "dist/index.js",
   "exports": {
     ".": "./dist/index.js",
@@ -36,7 +36,8 @@
   "files": [
     "dist",
     "README.md",
-    "codemods"
+    "codemods",
+    "examples"
   ],
   "dependencies": {
     "@next/env": "^15.5.4",