@sit-onyx/figma-utils 1.0.0-beta.0 → 1.0.0-beta.2

package/dist/cli.js

@@ -2,10 +2,11 @@
 import { Command } from "commander";
 import fs from "node:fs";
 import { fileURLToPath, URL } from "node:url";
-import { importCommand } from "./commands/import-variables.js";
+import { importIconsCommand } from "./commands/import-icons.js";
+import { importVariablesCommand } from "./commands/import-variables.js";
 const packageJson = JSON.parse(fs.readFileSync(fileURLToPath(new URL("../package.json", import.meta.url)), "utf8"));
 const cli = new Command();
 cli.version(packageJson.version, "-v, --version").description(packageJson.description);
-const availableCommands = [importCommand];
+const availableCommands = [importVariablesCommand, importIconsCommand];
 availableCommands.forEach((command) => cli.addCommand(command));
 cli.parse();

package/dist/commands/import-icons.d.ts

@@ -0,0 +1,14 @@
+import { Command } from "commander";
+export type ImportIconsCommandOptions = {
+    fileKey: string;
+    token: string;
+    pageId: string;
+    aliasSeparator: string;
+    dir?: string;
+    metaFile?: string;
+};
+export declare const importIconsCommand: Command;
+/**
+ * Action to run when executing the import action. Only intended to be called manually for testing.
+ */
+export declare function importIconsCommandAction(options: ImportIconsCommandOptions): Promise<void>;

package/dist/commands/import-icons.js

@@ -0,0 +1,47 @@
+import { Command } from "commander";
+import { mkdir, writeFile } from "node:fs/promises";
+import path from "node:path";
+import { writeIconMetadata } from "../icons/generate.js";
+import { optimizeSvg } from "../icons/optimize.js";
+import { parseComponentsToIcons } from "../icons/parse.js";
+import { fetchFigmaComponents, fetchFigmaSVGs } from "../index.js";
+import { isDirectory } from "../utils/fs.js";
+export const importIconsCommand = new Command("import-icons")
+    .description("CLI tool to import SVG icons from Figma.")
+    .requiredOption("-k, --file-key <string>", "Figma file key (required)")
+    .requiredOption("-t, --token <string>", "Figma access token with scope `file_read` or `files:read` (required)")
+    .requiredOption("-p, --page-id <string>", "Figma page ID that contains the icons (required)")
+    .option("-d, --dir <string>", "Directory to save the icons to. Defaults to current working directory of the script.")
+    .option("-m, --meta-file <string>", 'JSON filename/path to write icon metadata to (categories, alias names etc.). Must end with ".json". If unset, no metadata will be generated.')
+    .option("-s, --alias-separator <string>", "Separator for icon alias names (which can be set to the component description in Figma).", "|")
+    .action(importIconsCommandAction);
+/**
+ * Action to run when executing the import action. Only intended to be called manually for testing.
+ */
+export async function importIconsCommandAction(options) {
+    console.log("Fetching components from Figma API...");
+    const data = await fetchFigmaComponents(options.fileKey, options.token);
+    console.log("Parsing Figma icons...");
+    const parsedIcons = parseComponentsToIcons({
+        components: data.meta.components,
+        pageId: options.pageId,
+        aliasSeparator: options.aliasSeparator,
+    });
+    const outputDirectory = options.dir ?? process.cwd();
+    console.log(`Fetching SVG content for ${parsedIcons.length} icons...`);
+    const svgContents = await fetchFigmaSVGs(options.fileKey, parsedIcons.map(({ id }) => id), options.token);
+    console.log("Optimizing and writing icon files...");
+    if (!(await isDirectory(outputDirectory))) {
+        await mkdir(outputDirectory, { recursive: true });
+    }
+    await Promise.all(parsedIcons.map((icon) => {
+        const content = optimizeSvg(svgContents[icon.id]);
+        const fullPath = path.join(outputDirectory, `${icon.name}.svg`);
+        return writeFile(fullPath, content, "utf-8");
+    }));
+    if (options.metaFile) {
+        console.log("Writing icon metadata...");
+        await writeIconMetadata(options.metaFile, parsedIcons);
+    }
+    console.log("Done.");
+}

package/dist/commands/import-variables.d.ts

@@ -1,5 +1,5 @@
 import { Command } from "commander";
-export type ImportCommandOptions = {
+export type ImportVariablesCommandOptions = {
     fileKey: string;
     token: string;
     format: string[];
@@ -8,8 +8,8 @@ export type ImportCommandOptions = {
     modes?: string[];
     selector: string;
 };
-export declare const importCommand: Command;
+export declare const importVariablesCommand: Command;
 /**
  * Action to run when executing the import action. Only intended to be called manually for testing.
  */
-export declare function importCommandAction(options: ImportCommandOptions): Promise<void>;
+export declare function importVariablesCommandAction(options: ImportVariablesCommandOptions): Promise<void>;

package/dist/commands/import-variables.js

@@ -2,7 +2,7 @@ import { Command } from "commander";
 import fs from "node:fs";
 import path from "node:path";
 import { DEFAULT_MODE_NAME, fetchFigmaVariables, generateAsCSS, generateAsJSON, generateAsSCSS, parseFigmaVariables, } from "../index.js";
-export const importCommand = new Command("import-variables")
+export const importVariablesCommand = new Command("import-variables")
     .description("CLI tool to import Figma variables into CSS, SCSS etc. variables.")
     .requiredOption("-k, --file-key <string>", "Figma file key (required)")
     .requiredOption("-t, --token <string>", "Figma access token with scope `file_variables:read` (required)")
@@ -11,11 +11,11 @@ export const importCommand = new Command("import-variables")
     .option("-d, --dir <string>", "Working directory to use. Defaults to current working directory of the script.")
     .option("-m, --modes <strings...>", "Can be used to only export specific Figma modes. If unset, all modes will be exported as a separate file.")
     .option("-s, --selector <string>", 'CSS selector to use for the CSS format. You can use {mode} as placeholder for the mode name, so e.g. for the mode named "dark", passing the selector "html.{mode}" will result in "html.dark"', ":root")
-    .action(importCommandAction);
+    .action(importVariablesCommandAction);
 /**
  * Action to run when executing the import action. Only intended to be called manually for testing.
  */
-export async function importCommandAction(options) {
+export async function importVariablesCommandAction(options) {
     const generators = {
         CSS: (data) => generateAsCSS(data, { selector: options.selector }),
         SCSS: generateAsSCSS,

package/dist/icons/generate.d.ts

@@ -0,0 +1,8 @@
+import { ParsedIcon } from "../types/figma.js";
+/**
+ * Writes a JSON file with metadata of the given icons (category, aliases etc.).
+ *
+ * @param path File path of the .json file, e.g. "./metadata.json"
+ * @param icons Icons to write metadata for
+ */
+export declare const writeIconMetadata: (path: string, icons: ParsedIcon[]) => Promise<void>;

package/dist/icons/generate.js

@@ -0,0 +1,23 @@
+import { mkdir, writeFile } from "node:fs/promises";
+import { dirname } from "node:path";
+import { isDirectory } from "../utils/fs.js";
+/**
+ * Writes a JSON file with metadata of the given icons (category, aliases etc.).
+ *
+ * @param path File path of the .json file, e.g. "./metadata.json"
+ * @param icons Icons to write metadata for
+ */
+export const writeIconMetadata = async (path, icons) => {
+    const metaDirname = dirname(path);
+    if (!(await isDirectory(metaDirname))) {
+        await mkdir(metaDirname, { recursive: true });
+    }
+    const iconMetadata = icons.reduce((meta, icon) => {
+        meta[icon.name] = {
+            category: icon.category,
+            aliases: icon.aliases,
+        };
+        return meta;
+    }, {});
+    await writeFile(path, JSON.stringify(iconMetadata, null, 2), "utf-8");
+};

package/dist/icons/optimize.d.ts

@@ -0,0 +1,8 @@
+/**
+ * Optimizes the given SVG content for usage inside an icon library using [svgo](https://svgo.dev).
+ * Will apply the following optimizations:
+ * - remove all fills so the color can be set via CSS
+ * - remove dimensions (height/width) so it can be set via CSS
+ * - "preset-default" to reduce file size and redundant information
+ */
+export declare const optimizeSvg: (svgContent: string) => string;

package/dist/icons/optimize.js

@@ -0,0 +1,25 @@
+import { optimize } from "svgo";
+/**
+ * Optimizes the given SVG content for usage inside an icon library using [svgo](https://svgo.dev).
+ * Will apply the following optimizations:
+ * - remove all fills so the color can be set via CSS
+ * - remove dimensions (height/width) so it can be set via CSS
+ * - "preset-default" to reduce file size and redundant information
+ */
+export const optimizeSvg = (svgContent) => {
+    const { data } = optimize(svgContent, {
+        multipass: true,
+        plugins: [
+            { name: "preset-default" },
+            { name: "removeDimensions" },
+            {
+                name: "removeAttrs",
+                params: {
+                    // remove all fills so we can set the color via CSS
+                    attrs: ["fill"],
+                },
+            },
+        ],
+    });
+    return data;
+};

package/dist/icons/parse.d.ts

@@ -0,0 +1,18 @@
+import { Component, ParsedIcon } from "../types/figma.js";
+export type ParseIconComponentsOptions = {
+    /**
+     * Available Figma components.
+     */
+    components: Component[];
+    /**
+     * Page ID that contains all icons. Components will be filtered accordingly.
+     */
+    pageId: string;
+    /**
+     * Separator for icon alias names (which can be set to the component description in Figma).
+     *
+     * @default "|"
+     */
+    aliasSeparator?: string;
+};
+export declare const parseComponentsToIcons: (options: ParseIconComponentsOptions) => ParsedIcon[];

package/dist/icons/parse.js

@@ -0,0 +1,15 @@
+export const parseComponentsToIcons = (options) => {
+    const pageComponents = options.components.filter(({ containing_frame }) => containing_frame.pageId === options.pageId);
+    return pageComponents
+        .map((component) => {
+        return {
+            id: component.node_id,
+            name: component.name,
+            aliases: component.description
+                .split(options.aliasSeparator ?? "|")
+                .map((alias) => alias.trim()),
+            category: component.containing_frame.name.trim(),
+        };
+    })
+        .sort((a, b) => a.name.localeCompare(b.name));
+};

package/dist/index.d.ts

@@ -1,4 +1,7 @@
+export * from "./icons/generate.js";
+export * from "./icons/optimize.js";
+export * from "./icons/parse.js";
 export * from "./types/figma.js";
 export * from "./utils/fetch.js";
-export * from "./utils/generate.js";
-export * from "./utils/parse.js";
+export * from "./variables/generate.js";
+export * from "./variables/parse.js";

package/dist/index.js

@@ -1,4 +1,7 @@
+export * from "./icons/generate.js";
+export * from "./icons/optimize.js";
+export * from "./icons/parse.js";
 export * from "./types/figma.js";
 export * from "./utils/fetch.js";
-export * from "./utils/generate.js";
-export * from "./utils/parse.js";
+export * from "./variables/generate.js";
+export * from "./variables/parse.js";

package/dist/types/figma.d.ts

@@ -48,3 +48,59 @@ export type ParsedVariable = {
      */
     variables: Record<string, string>;
 };
+/**
+ * Figma API response when fetching from https://api.figma.com/v1/files/${fileKey}/components
+ */
+export type FigmaComponentsApiResponse = {
+    meta: {
+        components: Component[];
+    };
+};
+/**
+ * An arrangement of published UI elements that can be instantiated across Figma files
+ */
+export type Component = {
+    /**
+     * ID of the component node within the Figma file
+     */
+    node_id: string;
+    /**
+     * Name of the component
+     */
+    name: string;
+    /**
+     * Data on component's containing frame, if component resides within a frame
+     */
+    containing_frame: FrameInfo;
+    /**
+     * The description of the component as entered by the publisher
+     */
+    description: string;
+};
+/**
+ * Data on the frame a component resides in
+ */
+export type FrameInfo = {
+    /**
+     * ID of the frame node within the file
+     */
+    nodeId: string;
+    /**
+     * Name of the frame
+     */
+    name: string;
+    /**
+     * ID of the frame's residing page
+     */
+    pageId: string;
+    /**
+     * Name of the frame's residing page
+     */
+    pageName: string;
+};
+export type ParsedIcon = {
+    id: string;
+    name: string;
+    aliases: string[];
+    category: string;
+};

package/dist/utils/fetch.d.ts

@@ -1,8 +1,26 @@
-import { FigmaVariablesApiResponse } from "../types/figma.js";
+import { FigmaComponentsApiResponse, FigmaVariablesApiResponse } from "../types/figma.js";
 /**
  * Fetches the Figma Variables for the given file from the Figma API v1.
  *
  * @param fileKey File key. Example: https://www.figma.com/file/your-file-key-here
  * @param accessToken Personal access token with scope/permission `file_variables:read`
+ * @see https://www.figma.com/developers/api#get-local-variables-endpoint
  */
 export declare const fetchFigmaVariables: (fileKey: string, accessToken: string) => Promise<FigmaVariablesApiResponse>;
+/**
+ * Fetches the Figma components for the given file from the Figma API v1.
+ *
+ * @param fileKey File key. Example: https://www.figma.com/file/your-file-key-here
+ * @param accessToken Personal access token with scope/permission `file_read` or `files:read`
+ * @see https://www.figma.com/developers/api#get-file-components-endpoint
+ */
+export declare const fetchFigmaComponents: (fileKey: string, accessToken: string) => Promise<FigmaComponentsApiResponse>;
+export declare const fetchFigmaSVGs: (fileKey: string, componentIds: string[], accessToken: string) => Promise<Record<string, string>>;
+/**
+ * Generic utility to fetch Figma API routes.
+ *
+ * @param url API route, e.g. "https://api.figma.com/v1/files/${filekey}"
+ * @param accessToken Access token for authentication
+ * @throws Error if request was not successful
+ */
+export declare const fetchFigma: <T = unknown>(url: string, accessToken: string) => Promise<T>;

package/dist/utils/fetch.js

@@ -3,9 +3,41 @@
  *
  * @param fileKey File key. Example: https://www.figma.com/file/your-file-key-here
  * @param accessToken Personal access token with scope/permission `file_variables:read`
+ * @see https://www.figma.com/developers/api#get-local-variables-endpoint
  */
 export const fetchFigmaVariables = async (fileKey, accessToken) => {
-    const response = await fetch(`https://api.figma.com/v1/files/${fileKey}/variables/local`, {
+    return fetchFigma(`https://api.figma.com/v1/files/${fileKey}/variables/local`, accessToken);
+};
+/**
+ * Fetches the Figma components for the given file from the Figma API v1.
+ *
+ * @param fileKey File key. Example: https://www.figma.com/file/your-file-key-here
+ * @param accessToken Personal access token with scope/permission `file_read` or `files:read`
+ * @see https://www.figma.com/developers/api#get-file-components-endpoint
+ */
+export const fetchFigmaComponents = async (fileKey, accessToken) => {
+    return fetchFigma(`https://api.figma.com/v1/files/${fileKey}/components`, accessToken);
+};
+export const fetchFigmaSVGs = async (fileKey, componentIds, accessToken) => {
+    const result = await fetchFigma(`https://api.figma.com/v1/images/${fileKey}?ids=${componentIds.join()}&format=svg`, accessToken);
+    await Promise.all(Object.entries(result.images).map(async ([id, imageUrl]) => {
+        const response = await fetch(imageUrl);
+        if (!response.ok) {
+            throw new Error(`Failed to fetch SVG content for component ${id}: ${response.statusText}`);
+        }
+        result.images[id] = await response.text();
+    }));
+    return result.images;
+};
+/**
+ * Generic utility to fetch Figma API routes.
+ *
+ * @param url API route, e.g. "https://api.figma.com/v1/files/${filekey}"
+ * @param accessToken Access token for authentication
+ * @throws Error if request was not successful
+ */
+export const fetchFigma = async (url, accessToken) => {
+    const response = await fetch(url, {
         headers: {
             "X-FIGMA-TOKEN": accessToken,
         },

package/dist/utils/fs.d.ts

@@ -0,0 +1,7 @@
+import { PathLike } from "node:fs";
+/**
+ * Checks whether the given path is a directory.
+ *
+ * @returns `true` if path exists and is a directory, `false` otherwise.
+ */
+export declare const isDirectory: (path: PathLike) => Promise<boolean>;

package/dist/utils/fs.js

@@ -0,0 +1,15 @@
+import { stat } from "node:fs/promises";
+/**
+ * Checks whether the given path is a directory.
+ *
+ * @returns `true` if path exists and is a directory, `false` otherwise.
+ */
+export const isDirectory = async (path) => {
+    try {
+        const stats = await stat(path);
+        return stats.isDirectory();
+    }
+    catch (e) {
+        return false;
+    }
+};

package/dist/{utils → variables}/parse.js

@@ -74,8 +74,8 @@ export const parseFigmaVariables = (apiResponse, options) => {
 export const resolveFigmaVariableValue = (value, allVariables, remBase = 16) => {
     if (typeof value === "number") {
         // numeric value, parse as rem or pixel value
-        if (value === 0)
-            return "0";
+        // note: value 0 should also be parsed as "0rem" instead of just "0" because otherwise
+        // the CSS variable could not be used together with "calc()"
         if (remBase === false || remBase <= 0)
             return `${value}px`;
         return `${value / remBase}rem`;

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@sit-onyx/figma-utils",
   "description": "Utility functions and CLI for importing data from the Figma API into different formats (e.g. CSS, SCSS etc.)",
-  "version": "1.0.0-beta.0",
+  "version": "1.0.0-beta.2",
   "type": "module",
   "bin": {
     "@sit-onyx/figma-utils": "./dist/cli.js"
@@ -31,6 +31,9 @@
   "dependencies": {
     "commander": "^12.1.0"
   },
+  "optionalDependencies": {
+    "svgo": "^3.3.2"
+  },
   "scripts": {
     "build": "pnpm run '/type-check|build-only/'",
     "build-only": "rimraf dist && tsc -p tsconfig.node.json --composite false",