@interactivethings/scripts 2.2.0 → 2.2.1

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.2.0",
+  "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",