npm package: @interactivethings/scripts
Description: A collection of useful development tools by Interactive Things for managing design tokens, Figma assets, and deployment workflows.
Author: Interactive Things
Latest version: 2.2.2

# ixt-scripts

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

## Installation

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

## Quick Start

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

```typescript
// 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:

```bash
FIGMA_TOKEN=fig_***
```

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

3. Use the CLI commands:

```bash
# 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](./CONFIG.md).

## Available Commands

### Figma Commands

Download assets from Figma:

```bash
# 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:

```bash
# 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:

```typescript
// 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:

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

### Vercel Commands

Utilities for Vercel deployments:

```bash
# 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

```typescript
// 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)

```tsx
// 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