ixt-scripts

A collection of useful development tools by Interactive Things for managing design tokens, Figma assets, and deployment workflows.

Installation

yarn add @interactivethings/scripts
# or
npm install @interactivethings/scripts

Quick Start

1. Create a TypeScript configuration file in your project root:

// ixt.config.ts
import { defineConfig } from "@interactivethings/scripts";

export default defineConfig({
  figma: {
    assets: [
      {
        name: "icons",
        url: "https://www.figma.com/design/YOUR_FILE_ID/Design-System?node-id=123-456",
        output: "src/assets/icons",
      },
      {
        name: "illustrations", 
        url: "https://www.figma.com/design/YOUR_FILE_ID/Design-System?node-id=789-012",
        output: "src/assets/illustrations",
      },
    ],
  },
  tokensStudio: {
    input: "./tokens",
    output: "src/theme/tokens.json", 
    handler: "./transforms/mui-transform.ts",
  },
});

2. Create a .env.local file with your API tokens:

FIGMA_TOKEN=fig_***

ℹ️ Environment variables are loaded using @next/env the same way as Next.js.

3. Use the CLI commands:

# Download Figma assets
ixt figma download

# Transform design tokens
ixt tokens-studio transform

Configuration

ixt-scripts uses a unified configuration system with a single ixt.config.ts file that provides full TypeScript support and type safety.

Supported Config Files

• ixt.config.ts (TypeScript configuration with full type safety)

For detailed configuration options and schema reference, see CONFIG.md.

Available Commands

Figma Commands

Download assets from Figma:

# Download all configured assets
ixt figma download

# Download specific asset collection  
ixt figma download icons

# Get node information
ixt figma get "https://www.figma.com/design/..."

Features:

• Download SVG icons and optimize them
• Download assets exported from Figma
• Automatic asset optimization

⚠️ Assets must be exported in Figma to be visible to the tool.

Tokens Studio Commands

Transform design tokens exported from Tokens Studio:

# Transform using config file settings
ixt tokens-studio transform

# Override config settings
ixt tokens-studio transform --handler ./custom-transform.ts --output theme.json

Concept: UI frameworks like MUI and Tailwind require variables in specific formats, while designers work with Figma Tokens. The tokens-studio tool bridges this gap by transforming design tokens into framework-compatible variables.

Workflow:

1. Designers create tokens in Figma
2. Designers export tokens using Tokens Studio plugin
3. Developers store token files in the code repository
4. Developers run ixt tokens-studio transform to convert tokens for their framework

Creating Custom Transformers

You can create custom transformers for the tokens-studio command:

// transforms/my-transform.ts
export function transform(input: { metadata: any; tokenData: any }) {
  // Transform the tokens to your desired format
  return {
    colors: transformColors(input.tokenData.colors),
    typography: transformTypography(input.tokenData.typography),
    // ... other transformations
  };
}

Then reference it in your config:

export default defineConfig({
  tokensStudio: {
    handler: "./transforms/my-transform.ts",
  },
});

Vercel Commands

Utilities for Vercel deployments:

# Wait for deployment to complete
ixt vercel wait-deployment COMMIT_SHA --team TEAM_ID --project PROJECT_ID

Framework Integration Examples

After transforming your design tokens, you can use them directly in your framework configuration:

Tailwind CSS v3

// tailwind.config.ts
import theme from 'src/theme/tokens.json'

export default {
  darkMode: ["class"],
  content: [
    "./src/**/*.{js,ts,jsx,tsx,mdx}",
    process.env.TAILWIND_STORIES === "false"
      ? "!./src/**/*.stories.{js,ts,jsx,tsx,mdx}"
      : undefined,
  ].filter(Boolean),
  theme: {
    extend: {
      colors: {
        ...theme.colors
      }
    }
  }
}

Material-UI (MUI)

// theme.tsx
import { createTheme } from '@mui/material/styles';
import tokens from 'src/theme/tokens.json';

export const theme = createTheme({
  typography: {
    fontFamily: `${tokens.typography.body1.desktop.fontFamily}, -apple-system, BlinkMacSystemFont, 'Segoe UI', Roboto, sans-serif`,
    h1: omit(tokens.typography.h1.desktop, ["fontFamily"]),
    h2: omit(tokens.typography.h2.desktop, ["fontFamily"]),
    h3: omit(tokens.typography.h3.desktop, ["fontFamily"]),
    body1: omit(tokens.typography.body1.desktop, ["fontFamily"]),
    body2: omit(tokens.typography.body2.desktop, ["fontFamily"]),
  },
  palette: {
    primary: {
      main: tokens.palette.primary.main,
      light: tokens.palette.primary.light,
      dark: tokens.palette.primary.dark,
    },
    secondary: {
      main: tokens.palette.secondary.main,
    },
    error: {
      main: tokens.palette.functional.error,
    },
    warning: {
      main: tokens.palette.functional.warning,
    },
    success: {
      main: tokens.palette.functional.success,
    },
  },
});

Publishing

Publishing is done automatically through semantic-release via a GitHub action job, from the branch main. Commit prefixes will trigger different types of versions and we use the default commit analyser.

• 'fix:' commits will trigger a patch version
• 'feat:' commits will trigger a minor version
• 'BREAKING CHANGE:' in the body of a commit will trigger a major version