figma-token 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 lee090626
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,40 @@
+# figma-token
+
+`figma-token` exports Figma Variables to design token files.
+
+## Install
+
+```bash
+npm install --global figma-token
+```
+
+## Help
+
+```bash
+figma-token --help
+figma-token sync --help
+```
+
+## Basic usage
+
+Export a local Figma Variables JSON file:
+
+```bash
+figma-token sync --input ./figma-variables.json --format theme-ts --output ./theme.ts
+```
+
+Preview token changes without writing output or snapshot files:
+
+```bash
+figma-token sync --input ./figma-variables.json --dry-run
+```
+
+`--input` accepts a Figma Variables JSON response or a normalized `tokens.json` array. Without `--input`, provide `--figma-token` and `--file-key`, or set `FIGMA_TOKEN` and `FIGMA_FILE_KEY`.
+
+## Options
+
+`sync` supports `--input`, `--output`, `--snapshot`, `--format`, `--export-name`, `--figma-token`, `--file-key`, and `--dry-run`.
+
+Supported formats are `tokens-json`, `theme-ts`, `variables-css`, `tokens-scss`, `tailwind-css`, and `tokens-dtcg-json`.
+
+For Plugin usage and project-wide documentation, see <https://github.com/lee090626/Project-F>.

package/dist/index.js

@@ -0,0 +1,109 @@
+#!/usr/bin/env node
+
+// src/index.ts
+import "dotenv/config";
+import { Command, InvalidArgumentError } from "commander";
+
+// src/sync.ts
+import { mkdir, readFile, writeFile } from "fs/promises";
+import { dirname } from "path";
+import {
+  diffTokens,
+  isDesignTokenArray,
+  normalizeFigmaVariables,
+  renderCssVariables,
+  renderDtcgJson,
+  renderScssVariables,
+  renderTailwindTheme,
+  renderTheme,
+  renderTokensJson
+} from "@lee090626/core";
+
+// src/figma/fetchFigmaVariables.ts
+var FIGMA_API = "https://api.figma.com/v1";
+async function fetchFigmaVariables(fileKey, token) {
+  const response = await fetch(`${FIGMA_API}/files/${encodeURIComponent(fileKey)}/variables/local`, {
+    headers: { "X-Figma-Token": token }
+  });
+  if (response.ok) {
+    try {
+      return await response.json();
+    } catch {
+      throw new Error("Figma API \uC751\uB2F5\uC744 JSON\uC73C\uB85C \uD30C\uC2F1\uD560 \uC218 \uC5C6\uC2B5\uB2C8\uB2E4.");
+    }
+  }
+  if (response.status === 403) throw new Error("Figma Variables API \uC811\uADFC\uC774 \uAC70\uBD80\uB418\uC5C8\uC2B5\uB2C8\uB2E4. Figma plan, \uD574\uB2F9 file \uC811\uADFC \uAD8C\uD55C, token scope(file_variables:read)\uB97C \uD655\uC778\uD574 \uC8FC\uC138\uC694.");
+  if (response.status === 429) throw new Error("Figma API rate limit\uC5D0 \uB3C4\uB2EC\uD588\uC2B5\uB2C8\uB2E4. \uC7A0\uC2DC \uD6C4 \uB2E4\uC2DC \uC2E4\uD589\uD574 \uC8FC\uC138\uC694.");
+  throw new Error(`Figma API \uC694\uCCAD\uC5D0 \uC2E4\uD328\uD588\uC2B5\uB2C8\uB2E4. (status ${response.status})`);
+}
+
+// src/sync.ts
+var readJson = async (path) => {
+  try {
+    return JSON.parse(await readFile(path, "utf8"));
+  } catch (error) {
+    if (error instanceof SyntaxError) throw new Error(`Invalid JSON: ${path}`);
+    throw error;
+  }
+};
+var readSnapshot = async (path) => {
+  try {
+    const value = await readJson(path);
+    if (!isDesignTokenArray(value)) throw new Error("snapshot\uC740 DesignToken \uBC30\uC5F4\uC774\uC5B4\uC57C \uD569\uB2C8\uB2E4.");
+    return value;
+  } catch (error) {
+    if (error.code === "ENOENT") return [];
+    throw error;
+  }
+};
+var save = async (path, contents) => {
+  await mkdir(dirname(path), { recursive: true });
+  await writeFile(path, contents);
+};
+var render = (tokens, options) => ({
+  "tokens-json": renderTokensJson,
+  "theme-ts": (value) => renderTheme(value, options.exportName),
+  "variables-css": renderCssVariables,
+  "tokens-scss": renderScssVariables,
+  "tailwind-css": renderTailwindTheme,
+  "tokens-dtcg-json": renderDtcgJson
+})[options.format](tokens);
+var skippedMessage = (name, reason, collection) => {
+  const suffix = collection ? ` (collection: ${collection})` : "";
+  return reason === "unclassified-float" ? `unclassified FLOAT variable skipped: ${name}${suffix}` : `unsupported type skipped: ${name}${suffix}`;
+};
+var aliasSkippedMessage = (name, reason, collection) => {
+  const suffix = collection ? ` (collection: ${collection})` : "";
+  return `alias ${reason.replace(/^alias-/, "").replace(/-/g, " ")} skipped: ${name}${suffix}`;
+};
+async function sync(options, log = console.log, warn = console.warn) {
+  if (!options.input && (!options.figmaToken || !options.fileKey)) throw new Error("--input \uB610\uB294 FIGMA_TOKEN\uACFC FIGMA_FILE_KEY\uAC00 \uD544\uC694\uD569\uB2C8\uB2E4.");
+  const raw = options.input ? await readJson(options.input) : await fetchFigmaVariables(options.fileKey, options.figmaToken);
+  const current = isDesignTokenArray(raw) ? raw : normalizeFigmaVariables(raw, {
+    onUnsupported: (name, reason, collection) => warn(skippedMessage(name, reason, collection)),
+    onAliasWarning: (name, reason, collection) => warn(aliasSkippedMessage(name, reason, collection))
+  });
+  const diffs = diffTokens(await readSnapshot(options.snapshot), current);
+  for (const type of ["added", "changed", "removed"]) log(`${type[0].toUpperCase()}${type.slice(1)}: ${diffs.filter((diff) => diff.type === type).length}`);
+  diffs.forEach((diff) => log(`${diff.type} ${diff.token.path.join("/")}`));
+  if (options.dryRun) return;
+  await save(options.output, render(current, options));
+  await save(options.snapshot, renderTokensJson(current));
+}
+
+// src/index.ts
+var format = (value) => {
+  const formats = ["tokens-json", "theme-ts", "variables-css", "tokens-scss", "tailwind-css", "tokens-dtcg-json"];
+  if (!formats.includes(value)) throw new InvalidArgumentError(`format\uC740 ${formats.join(", ")} \uC911 \uD558\uB098\uC5EC\uC57C \uD569\uB2C8\uB2E4.`);
+  return value;
+};
+var program = new Command().name("figma-token").description("Figma Variables\uB97C \uB85C\uCEEC \uB514\uC790\uC778 \uD1A0\uD070\uC73C\uB85C \uB3D9\uAE30\uD654\uD569\uB2C8\uB2E4.");
+program.command("sync").option("--input <path>", "\uB85C\uCEEC Figma Variables JSON").option("--output <path>", "\uCD9C\uB825 \uD30C\uC77C", "./tokens.json").option("--snapshot <path>", "snapshot \uD30C\uC77C", ".figma-token/snapshot.json").option("--format <format>", "\uCD9C\uB825 \uD3EC\uB9F7", format, "tokens-json").option("--export-name <name>", "theme.ts export \uC774\uB984", "theme").option("--figma-token <token>", "Figma token").option("--file-key <key>", "Figma file key").option("--dry-run", "\uD30C\uC77C\uC744 \uC4F0\uC9C0 \uC54A\uACE0 diff\uB9CC \uCD9C\uB825", false).action(async (options) => sync({
+  ...options,
+  figmaToken: options.figmaToken ?? process.env.FIGMA_TOKEN,
+  fileKey: options.fileKey ?? process.env.FIGMA_FILE_KEY
+}));
+program.parseAsync().catch((error) => {
+  console.error(`Error: ${error instanceof Error ? error.message : String(error)}`);
+  process.exitCode = 1;
+});

package/package.json

@@ -0,0 +1,31 @@
+{
+  "name": "figma-token",
+  "version": "0.1.0",
+  "description": "Export Figma Variables to design token files.",
+  "license": "MIT",
+  "type": "module",
+  "bin": {
+    "figma-token": "dist/index.js"
+  },
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/lee090626/Project-F.git",
+    "directory": "packages/cli"
+  },
+  "files": [
+    "dist",
+    "README.md"
+  ],
+  "dependencies": {
+    "commander": "^14.0.0",
+    "dotenv": "^17.0.0",
+    "@lee090626/core": "0.1.0"
+  },
+  "devDependencies": {
+    "tsup": "^8.5.0"
+  },
+  "scripts": {
+    "build": "tsup",
+    "test": "vitest run"
+  }
+}