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

package/README.md

@@ -1,9 +1,5 @@
 <div align="center" style="text-align: center">
-  <picture>
-    <source media="(prefers-color-scheme: dark)" type="image/svg+xml" srcset="https://raw.githubusercontent.com/SchwarzIT/onyx/main/.github/onyx-logo-light.svg">
-    <source media="(prefers-color-scheme: light)" type="image/svg+xml" srcset="https://raw.githubusercontent.com/SchwarzIT/onyx/main/.github/onyx-logo-dark.svg">
-    <img alt="onyx logo" src="https://raw.githubusercontent.com/SchwarzIT/onyx/main/.github/onyx-logo-dark.svg" width="160px">
-  </picture>
+  <img alt="onyx logo" src="https://raw.githubusercontent.com/SchwarzIT/onyx/main/.github/onyx-logo.svg" height="96px">
 </div>
 
 <br>

package/dist/cli.js

@@ -2,10 +2,12 @@
 import { Command } from "commander";
 import fs from "node:fs";
 import { fileURLToPath, URL } from "node:url";
-import { importCommand } from "./commands/import-variables.js";
+import { importFlagsCommand } from "./commands/import-flags.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, importFlagsCommand];
 availableCommands.forEach((command) => cli.addCommand(command));
 cli.parse();

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

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

package/dist/commands/import-flags.js

@@ -0,0 +1,42 @@
+import { Command } from "commander";
+import { mkdir, writeFile } from "node:fs/promises";
+import path from "node:path";
+import { writeFlagMetadata } from "../flags/generate.js";
+import { parseComponentsToFlags } from "../flags/parse.js";
+import { fetchFigmaComponents, fetchFigmaSVGs } from "../index.js";
+import { optimizeSvg } from "../utils/optimize.js";
+export const importFlagsCommand = new Command("import-flags")
+    .description("CLI tool to import SVG flags 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 flags (required)")
+    .option("-d, --dir <string>", "Directory to save the flags to. Defaults to current working directory of the script.")
+    .option("-m, --meta-file <string>", 'JSON filename/path to write flag metadata to (country name etc.). Must end with ".json". If unset, no metadata will be generated.')
+    .action(importFlagsCommandAction);
+/**
+ * Action to run when executing the import action. Only intended to be called manually for testing.
+ */
+export async function importFlagsCommandAction(options) {
+    console.log("Fetching components from Figma API...");
+    const data = await fetchFigmaComponents(options.fileKey, options.token);
+    console.log("Parsing Figma flags...");
+    const parsedFlags = parseComponentsToFlags({
+        components: data.meta.components,
+        pageId: options.pageId,
+    });
+    const outputDirectory = options.dir ?? process.cwd();
+    console.log(`Fetching SVG content for ${parsedFlags.length} flags...`);
+    const svgContents = await fetchFigmaSVGs(options.fileKey, parsedFlags.map(({ id }) => id), options.token);
+    console.log("Optimizing and writing flag files...");
+    await mkdir(outputDirectory, { recursive: true });
+    await Promise.all(parsedFlags.map((flag) => {
+        const content = optimizeSvg(svgContents[flag.id], "image");
+        const fullPath = path.join(outputDirectory, `${flag.code}.svg`);
+        return writeFile(fullPath, content, "utf-8");
+    }));
+    if (options.metaFile) {
+        console.log("Writing flag metadata...");
+        await writeFlagMetadata(options.metaFile, parsedFlags);
+    }
+    console.log("Done.");
+}

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,44 @@
+import { Command } from "commander";
+import { mkdir, writeFile } from "node:fs/promises";
+import path from "node:path";
+import { writeIconMetadata } from "../icons/generate.js";
+import { parseComponentsToIcons } from "../icons/parse.js";
+import { fetchFigmaComponents, fetchFigmaSVGs } from "../index.js";
+import { optimizeSvg } from "../utils/optimize.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...");
+    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,15 +1,16 @@
 import { Command } from "commander";
-export type ImportCommandOptions = {
+export type ImportVariablesCommandOptions = {
     fileKey: string;
     token: string;
     format: string[];
     filename?: string;
     dir?: string;
     modes?: string[];
+    combinesDarkLight?: boolean;
     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)")
@@ -10,16 +10,17 @@ export const importCommand = new Command("import-variables")
     .option("-n, --filename <string>", "Base name / prefix of the generated variables file. Will append the mode name")
     .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("-c, --combines-dark-light", "Combines the dark theme data with the light theme data by using the light-dark() CSS function. The Figma file must include two modes with -light and -dark prefix, e.g. example-light and example-dark.")
     .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,
-        JSON: generateAsJSON,
+        CSS: (data, dataDark) => generateAsCSS(data, { selector: options.selector, dataDarkTheme: dataDark }),
+        SCSS: (data, dataDark) => generateAsSCSS(data, { dataDarkTheme: dataDark }),
+        JSON: (data) => generateAsJSON(data),
     };
     options.format.forEach((format) => {
         if (!(format in generators)) {
@@ -59,8 +60,17 @@ export async function importCommandAction(options) {
             if (!isModeIncluded)
                 return;
             const baseName = getBaseFileName(data.modeName);
-            const fullPath = path.join(outputDirectory, `${baseName}.${format.toLowerCase()}`);
-            fs.writeFileSync(fullPath, generators[format](data));
+            if (options.combinesDarkLight) {
+                const themeName = baseName.replace("-light", "").replace("-dark", "");
+                const fullPath = path.join(outputDirectory, `${themeName}.${format.toLowerCase()}`);
+                // find the matching theme
+                const dataDark = parsedVariables.find((themeData) => themeData.modeName === themeName + "-dark");
+                fs.writeFileSync(fullPath, generators[format]({ ...data, modeName: themeName }, dataDark));
+            }
+            else {
+                const fullPath = path.join(outputDirectory, `${baseName}.${format.toLowerCase()}`);
+                fs.writeFileSync(fullPath, generators[format](data));
+            }
         });
     });
     console.log("Done.");

package/dist/flags/generate.d.ts

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

package/dist/flags/generate.js

@@ -0,0 +1,18 @@
+import { mkdir, writeFile } from "node:fs/promises";
+import { dirname } from "node:path";
+/**
+ * Writes a JSON file with metadata of the given flags (code, name etc.).
+ *
+ * @param path File path of the .json file, e.g. "./metadata.json"
+ * @param flags Flags to write metadata for
+ */
+export const writeFlagMetadata = async (path, flags) => {
+    const metaDirname = dirname(path);
+    await mkdir(metaDirname, { recursive: true });
+    const flagMetadata = flags.reduce((meta, flag) => {
+        const { id: _id, code, ...rest } = flag;
+        meta[code] = rest;
+        return meta;
+    }, {});
+    await writeFile(path, JSON.stringify(flagMetadata, null, 2), "utf-8");
+};

package/dist/flags/parse.d.ts

@@ -0,0 +1,12 @@
+import { Component, ParsedFlag } from "../types/figma.js";
+export type ParseFlagComponentsOptions = {
+    /**
+     * Available Figma components.
+     */
+    components: Component[];
+    /**
+     * Page ID that contains all flags. Components will be filtered accordingly.
+     */
+    pageId: string;
+};
+export declare const parseComponentsToFlags: (options: ParseFlagComponentsOptions) => ParsedFlag[];

package/dist/flags/parse.js

@@ -0,0 +1,34 @@
+/**
+ * Map of country names for country codes that are not (yet) supported by `Intl.DisplayNames`.
+ */
+const UNKNOWN_COUNTRY_NAMES = {
+    "CA-BC": "British Columbia",
+    "GB-ENG": "England",
+    "GB-SCT": "Scotland",
+    "GB-WLS": "Wales",
+    "US-HI": "Hawaii",
+};
+export const parseComponentsToFlags = (options) => {
+    const pageComponents = options.components.filter(({ containing_frame }) => containing_frame.pageId === options.pageId);
+    const countryCodeFormatter = new Intl.DisplayNames("en", { type: "region" });
+    return (pageComponents
+        .map((component) => {
+        const code = component.description.trim();
+        let internationalName = UNKNOWN_COUNTRY_NAMES[code] ?? "";
+        try {
+            internationalName = countryCodeFormatter.of(code) || internationalName;
+        }
+        catch {
+            // noop
+        }
+        return {
+            id: component.node_id,
+            code,
+            continent: component.containing_frame.name.trim(),
+            internationalName,
+        };
+    })
+        // remove invalid flags without a country code
+        .filter(({ code }) => code)
+        .sort((a, b) => a.code.localeCompare(b.code)));
+};

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,18 @@
+import { mkdir, writeFile } from "node:fs/promises";
+import { dirname } from "node:path";
+/**
+ * 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);
+    await mkdir(metaDirname, { recursive: true });
+    const iconMetadata = icons.reduce((meta, icon) => {
+        const { id: _id, name, ...rest } = icon;
+        meta[name] = rest;
+        return meta;
+    }, {});
+    await writeFile(path, JSON.stringify(iconMetadata, null, 2), "utf-8");
+};

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,16 @@
+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,
+            category: component.containing_frame.name.trim(),
+            aliases: component.description
+                .split(options.aliasSeparator ?? ",")
+                .map((alias) => alias.trim())
+                .filter((i) => i !== ""),
+        };
+    })
+        .sort((a, b) => a.name.localeCompare(b.name));
+};

package/dist/index.d.ts

@@ -1,4 +1,9 @@
+export * from "./flags/generate.js";
+export * from "./flags/parse.js";
+export * from "./icons/generate.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 "./utils/optimize.js";
+export * from "./variables/generate.js";
+export * from "./variables/parse.js";

package/dist/index.js

@@ -1,4 +1,9 @@
+export * from "./flags/generate.js";
+export * from "./flags/parse.js";
+export * from "./icons/generate.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 "./utils/optimize.js";
+export * from "./variables/generate.js";
+export * from "./variables/parse.js";

package/dist/types/figma.d.ts

@@ -20,9 +20,10 @@ export type Variable = {
     name: string;
     variableCollectionId: string;
     hiddenFromPublishing: boolean;
+    deletedButReferenced?: boolean;
     valuesByMode: Record<string, VariableValue>;
 };
-export type VariableValue = RGBAValue | ColorsAlias | number;
+export type VariableValue = RGBAValue | ColorsAlias | number | string;
 export type RGBAValue = {
     r: number;
     g: number;
@@ -48,3 +49,65 @@ 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;
+};
+export type ParsedFlag = {
+    id: string;
+    code: string;
+    internationalName: string;
+    continent: 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 {
+        return false;
+    }
+};

package/dist/utils/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 dimensions (height/width) so it can be set via CSS
+ * - "preset-default" to reduce file size and redundant information
+ * - (only if type "icon"): remove all fills so the color can be set via CSS
+ */
+export declare const optimizeSvg: (svgContent: string, type?: "icon" | "image") => string;

package/dist/utils/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 dimensions (height/width) so it can be set via CSS
+ * - "preset-default" to reduce file size and redundant information
+ * - (only if type "icon"): remove all fills so the color can be set via CSS
+ */
+export const optimizeSvg = (svgContent, type = "icon") => {
+    const plugins = [{ name: "preset-default" }, { name: "removeDimensions" }];
+    if (type === "icon") {
+        plugins.push({
+            name: "removeAttrs",
+            params: {
+                // remove all fills so we can set the color via CSS
+                attrs: ["fill"],
+            },
+        });
+    }
+    const { data } = optimize(svgContent, {
+        multipass: true,
+        plugins,
+    });
+    return data;
+};

package/dist/{utils → variables}/generate.d.ts

@@ -7,6 +7,10 @@ export type BaseGenerateOptions = {
      * @default false
      */
     resolveAlias?: boolean;
+    /**
+     * Parsed Figma variables for an additionally dark theme.
+     */
+    dataDarkTheme?: ParsedVariable;
 };
 export type GenerateAsCSSOptions = BaseGenerateOptions & {
     /**
@@ -69,7 +73,10 @@ export declare const generateTimestampComment: (modeName?: string) => string;
  * @example "{your-variable-name}"
  * @returns `isAlias` whether the variable is an alias and `aliasName` the raw variable name without curly braces.
  */
-export declare const isAliasVariable: (variableValue: string) => {
+export declare const isAliasVariable: (variableValue?: string) => {
+    isAlias: boolean;
+    aliasName: string;
+} | {
     isAlias: RegExpExecArray | null;
     aliasName: string;
 };

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

@@ -76,6 +76,8 @@ export const generateTimestampComment = (modeName) => {
  * @returns `isAlias` whether the variable is an alias and `aliasName` the raw variable name without curly braces.
  */
 export const isAliasVariable = (variableValue) => {
+    if (!variableValue)
+        return { isAlias: false, aliasName: "" };
     const isAlias = /{.*}/.exec(variableValue);
     const aliasName = variableValue.replace("{", "").replace("}", "");
     return { isAlias, aliasName };
@@ -85,17 +87,37 @@ export const isAliasVariable = (variableValue) => {
  * represents a single line of the file.
  *
  * @param variables Variable data (name + value)
+ * @param variablesDarkTheme Variable data (name +value) for additionally dark theme
  * @param nameFormatter Function to format the variable name
  * @param aliasFormatter Function to format a reference to another variable (e.g. `var(--name)` for CSS)
  * @param options Generator options
  */
 const getCssOrScssVariableContent = (variables, nameFormatter, aliasFormatter, options) => {
+    const variablesDarkTheme = options?.dataDarkTheme?.variables;
     return Object.entries(variables).map(([name, value]) => {
-        const { isAlias, aliasName } = isAliasVariable(value);
-        let variableValue = isAlias ? aliasFormatter(aliasName) : value;
-        if (isAlias && options?.resolveAlias) {
-            variableValue = resolveValue(name, variables);
+        const lightRawValue = value;
+        const darkRawValue = variablesDarkTheme?.[name];
+        const { isAlias: isLightAlias, aliasName: lightAliasName } = isAliasVariable(lightRawValue);
+        const { isAlias: isDarkAlias, aliasName: darkAliasName } = isAliasVariable(darkRawValue ?? lightRawValue);
+        let lightValue = isLightAlias ? aliasFormatter(lightAliasName) : lightRawValue;
+        let darkValue = isDarkAlias ? aliasFormatter(darkAliasName) : (darkRawValue ?? lightRawValue);
+        if (options?.resolveAlias) {
+            if (isLightAlias) {
+                lightValue = resolveValue(name, variables);
+            }
+            if (isDarkAlias) {
+                darkValue = resolveValue(name, variablesDarkTheme ?? {});
+            }
         }
-        return `${nameFormatter(name)}: ${variableValue};`;
+        const formattedName = nameFormatter(name);
+        if (variablesDarkTheme && darkRawValue) {
+            if (lightValue === darkValue) {
+                return `${formattedName}: ${lightValue};`;
+            }
+            else {
+                return `${formattedName}: light-dark(${lightValue}, ${darkValue});`;
+            }
+        }
+        return `${formattedName}: ${lightValue};`;
     });
 };

package/dist/{utils → variables}/parse.d.ts

@@ -26,7 +26,7 @@ export declare const parseFigmaVariables: (apiResponse: FigmaVariablesApiRespons
  * @param value Figma variable value
  * @param allVariables Object of all variables. Needed for variables that use aliases.
  */
-export declare const resolveFigmaVariableValue: (value: VariableValue, allVariables: Record<string, Variable>, remBase?: ParseFigmaVariablesOptions["remBase"]) => string;
+export declare const resolveFigmaVariableValue: (value: VariableValue, allVariables: Record<string, Variable>, remBase?: ParseFigmaVariablesOptions["remBase"], name?: string) => string;
 /**
  * Converts a RGBA value to a hex color.
  * Transparency will only be added if its not 1, e.g. "#000000" instead of "#000000ff"

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

@@ -14,12 +14,14 @@ export const parseFigmaVariables = (apiResponse, options) => {
      */
     Object.values(apiResponse.meta.variables).forEach((variable) => {
         const collection = apiResponse.meta.variableCollections[variable.variableCollectionId];
-        if (variable.hiddenFromPublishing || collection.hiddenFromPublishing)
+        if (variable.hiddenFromPublishing ||
+            variable.deletedButReferenced ||
+            collection.hiddenFromPublishing)
             return;
         // parse variable value for every mode
         Object.values(collection.modes).forEach((mode) => {
             const variableName = normalizeVariableName(variable.name);
-            const variableValue = resolveFigmaVariableValue(variable.valuesByMode?.[mode.modeId], apiResponse.meta.variables, options?.remBase);
+            const variableValue = resolveFigmaVariableValue(variable.valuesByMode?.[mode.modeId], apiResponse.meta.variables, options?.remBase, variableName);
             // add/update parsed variable value
             const existingIndex = parsedData.findIndex((i) => i.modeName === mode.name);
             if (existingIndex !== -1) {
@@ -71,15 +73,20 @@ export const parseFigmaVariables = (apiResponse, options) => {
  * @param value Figma variable value
  * @param allVariables Object of all variables. Needed for variables that use aliases.
  */
-export const resolveFigmaVariableValue = (value, allVariables, remBase = 16) => {
+export const resolveFigmaVariableValue = (value, allVariables, remBase = 16, name) => {
     if (typeof value === "number") {
+        if (name?.includes("font-weight"))
+            return `${value}`;
         // 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`;
     }
+    if (typeof value === "string") {
+        return `"${value}"`;
+    }
     if ("type" in value) {
         // parse value as alias
         if (value.type !== "VARIABLE_ALIAS") {

package/package.json

@@ -1,17 +1,19 @@
 {
   "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.10",
   "type": "module",
+  "author": "Schwarz IT KG",
+  "license": "Apache-2.0",
+  "engines": {
+    "node": ">=20"
+  },
   "bin": {
     "@sit-onyx/figma-utils": "./dist/cli.js"
   },
   "files": [
     "dist"
   ],
-  "engines": {
-    "node": ">=18"
-  },
   "types": "./dist/index.d.ts",
   "exports": {
     ".": {
@@ -29,7 +31,10 @@
     "url": "https://github.com/SchwarzIT/onyx/issues"
   },
   "dependencies": {
-    "commander": "^12.1.0"
+    "commander": "^14.0.0"
+  },
+  "optionalDependencies": {
+    "svgo": "^4.0.0"
   },
   "scripts": {
     "build": "pnpm run '/type-check|build-only/'",