@mstrathman/figma 0.1.0 → 0.2.1

package/dist/main.js

@@ -60,9 +60,9 @@ var init_client = __esm({
         this.timeout = options.timeout ?? DEFAULT_TIMEOUT_MS;
         this.maxRetries = options.maxRetries ?? MAX_RETRIES;
       }
-      async request(method, path5, options = {}, retryCount = 0) {
+      async request(method, path8, options = {}, retryCount = 0) {
         const baseWithSlash = this.baseUrl.endsWith("/") ? this.baseUrl : `${this.baseUrl}/`;
-        const pathWithoutLeadingSlash = path5.startsWith("/") ? path5.slice(1) : path5;
+        const pathWithoutLeadingSlash = path8.startsWith("/") ? path8.slice(1) : path8;
         const url = new URL(pathWithoutLeadingSlash, baseWithSlash);
         if (options.params) {
           for (const [key, value] of Object.entries(options.params)) {
@@ -110,12 +110,12 @@ var init_client = __esm({
           const retryAfter = response.headers.get("Retry-After");
           const delayMs = retryAfter ? parseInt(retryAfter, 10) * 1e3 : INITIAL_RETRY_DELAY_MS * Math.pow(2, retryCount);
           await this.sleep(delayMs);
-          return this.request(method, path5, options, retryCount + 1);
+          return this.request(method, path8, options, retryCount + 1);
         }
         if (response.status >= 500 && retryCount < this.maxRetries) {
           const delayMs = INITIAL_RETRY_DELAY_MS * Math.pow(2, retryCount);
           await this.sleep(delayMs);
-          return this.request(method, path5, options, retryCount + 1);
+          return this.request(method, path8, options, retryCount + 1);
         }
         if (!response.ok) {
           let body;
@@ -133,7 +133,7 @@ var init_client = __esm({
         return response.json();
       }
       sleep(ms) {
-        return new Promise((resolve) => setTimeout(resolve, ms));
+        return new Promise((resolve3) => setTimeout(resolve3, ms));
       }
       // User endpoints
       async getMe() {
@@ -281,8 +281,8 @@ var init_client = __esm({
         );
       }
       // Generic API method for raw access
-      async api(method, path5, options) {
-        const normalizedPath = path5.startsWith("/") ? path5 : `/${path5}`;
+      async api(method, path8, options) {
+        const normalizedPath = path8.startsWith("/") ? path8 : `/${path8}`;
         return this.request(method.toUpperCase(), normalizedPath, options);
       }
     };
@@ -578,19 +578,19 @@ async function findAvailablePort(startPort, maxPort = MAX_PORT) {
   if (startPort > maxPort) {
     throw new Error(`No available ports found between 8585 and ${maxPort}`);
   }
-  return new Promise((resolve, reject) => {
+  return new Promise((resolve3, reject) => {
     const server = http.createServer();
     server.listen(startPort, "127.0.0.1", () => {
       const address = server.address();
       if (address && typeof address === "object") {
         const port = address.port;
-        server.close(() => resolve(port));
+        server.close(() => resolve3(port));
       } else {
         reject(new Error("Could not get server address"));
       }
     });
     server.on("error", () => {
-      findAvailablePort(startPort + 1, maxPort).then(resolve).catch(reject);
+      findAvailablePort(startPort + 1, maxPort).then(resolve3).catch(reject);
     });
   });
 }
@@ -599,7 +599,7 @@ async function startOAuthFlow(config, onOpenUrl) {
   const redirectUri = config.redirectUri || `http://127.0.0.1:${port}/callback`;
   const state = generateState();
   const scopes = config.scopes || ["files:read"];
-  return new Promise((resolve, reject) => {
+  return new Promise((resolve3, reject) => {
     let serverClosed = false;
     const closeServer = () => {
       if (!serverClosed) {
@@ -656,7 +656,7 @@ async function startOAuthFlow(config, onOpenUrl) {
           res.writeHead(200, { "Content-Type": "text/html" });
           res.end(getSuccessHtml());
           closeServer();
-          resolve({
+          resolve3({
             accessToken: tokenData.access_token,
             refreshToken: tokenData.refresh_token,
             expiresIn: tokenData.expires_in,
@@ -876,7 +876,7 @@ function createFactory() {
 }
 
 // src/cmd/root.ts
-import { Command as Command26 } from "commander";
+import { Command as Command30 } from "commander";
 
 // src/cmd/auth/index.ts
 import { Command as Command4 } from "commander";
@@ -1163,7 +1163,7 @@ function createAuthCommand(factory) {
 }
 
 // src/cmd/file/index.ts
-import { Command as Command8 } from "commander";
+import { Command as Command9 } from "commander";
 
 // src/cmd/file/get.ts
 import { Command as Command5 } from "commander";
@@ -1228,25 +1228,78 @@ function formatValue(value) {
   return String(value);
 }
 
+// src/internal/url/parser.ts
+import {
+  parseFileAndNodeId,
+  parseFileId,
+  formatNodeId
+} from "@design-sdk/figma-url";
+function parseFigmaInput(input) {
+  const trimmed = input.trim();
+  if (trimmed.includes("figma.com/")) {
+    const result = parseFileAndNodeId(trimmed);
+    if (result) {
+      return {
+        fileKey: result.file,
+        nodeId: result.node || void 0
+      };
+    }
+    try {
+      const fileKey = parseFileId(trimmed);
+      return { fileKey };
+    } catch (error) {
+      const message = error instanceof Error ? error.message : String(error);
+      throw new Error(`Could not parse Figma URL: ${trimmed}. ${message}`);
+    }
+  }
+  return { fileKey: trimmed };
+}
+function parseNodeIds(input) {
+  const rawIds = input.split(",").map((id) => id.trim()).filter(Boolean);
+  const validIds = [];
+  const invalidIds = [];
+  for (const id of rawIds) {
+    const formatted = formatNodeId(id);
+    if (formatted) {
+      validIds.push(formatted);
+    } else {
+      invalidIds.push(id);
+    }
+  }
+  if (invalidIds.length > 0) {
+    throw new Error(
+      `Invalid node ID(s): ${invalidIds.join(", ")}. Node IDs should be in format "1:2" or "1-2".`
+    );
+  }
+  return validIds;
+}
+
 // src/cmd/file/get.ts
 function createFileGetCommand(factory) {
-  const cmd = new Command5("get").description("Get file JSON structure").argument("<key>", "File key (from Figma URL)").option("-v, --version <version>", "File version to get").option(
+  const cmd = new Command5("get").description("Get file JSON structure").argument("<url>", "Figma URL or file key").option("-v, --version <version>", "File version to get").option(
     "-d, --depth <depth>",
     "Depth of node tree to return (default: full tree)",
     parseInt
-  ).option("-i, --ids <ids>", "Comma-separated list of node IDs to include").option("--geometry <paths>", "Include geometry data (paths)").option("-f, --format <format>", "Output format (json, table)", "json").option("-t, --token <token>", "Override authentication token").action(
-    async (fileKey, options) => {
+  ).option("--id <ids>", "Comma-separated node IDs (overrides URL node-id)").option("--geometry <paths>", "Include geometry data (paths)").option("-f, --format <format>", "Output format (json, table)", "json").option("-t, --token <token>", "Override authentication token").action(
+    async (url, options) => {
       const { io } = factory;
       try {
-        const token = await factory.getToken(options.token);
+        const parsed = parseFigmaInput(url);
+        const fileKey = parsed.fileKey;
+        let nodeIds;
+        if (options.id) {
+          nodeIds = parseNodeIds(options.id);
+        } else if (parsed.nodeId) {
+          nodeIds = [parsed.nodeId];
+        }
         const client = await factory.getClient();
         if (options.token) {
           const { FigmaClient: FigmaClient2 } = await Promise.resolve().then(() => (init_client(), client_exports));
-          const overrideClient = new FigmaClient2({ token });
+          const overrideClient = new FigmaClient2({ token: options.token });
           const file2 = await overrideClient.getFile(fileKey, {
             version: options.version,
             depth: options.depth,
-            ids: options.ids?.split(","),
+            ids: nodeIds,
             geometry: options.geometry
           });
           io.out.write(
@@ -1258,7 +1311,7 @@ function createFileGetCommand(factory) {
         const file = await client.getFile(fileKey, {
           version: options.version,
           depth: options.depth,
-          ids: options.ids?.split(","),
+          ids: nodeIds,
           geometry: options.geometry
         });
         io.out.write(
@@ -1282,13 +1335,27 @@ function createFileGetCommand(factory) {
 import { Command as Command6 } from "commander";
 import chalk6 from "chalk";
 function createFileNodesCommand(factory) {
-  const cmd = new Command6("nodes").description("Get specific nodes from a file").argument("<key>", "File key (from Figma URL)").requiredOption("-i, --ids <ids>", "Comma-separated list of node IDs").option("-v, --version <version>", "File version to get").option("-d, --depth <depth>", "Depth of node tree to return", parseInt).option("--geometry <paths>", "Include geometry data (paths)").option("-f, --format <format>", "Output format (json, table)", "json").option("-t, --token <token>", "Override authentication token").action(
-    async (fileKey, options) => {
+  const cmd = new Command6("nodes").description("Get specific nodes from a file").argument("<url>", "Figma URL (with node-id) or file key").option("--id <ids>", "Comma-separated node IDs (overrides URL node-id)").option("-v, --version <version>", "File version to get").option("-d, --depth <depth>", "Depth of node tree to return", parseInt).option("--geometry <paths>", "Include geometry data (paths)").option("-f, --format <format>", "Output format (json, table)", "json").option("-t, --token <token>", "Override authentication token").action(
+    async (url, options) => {
       const { io } = factory;
       try {
+        const parsed = parseFigmaInput(url);
+        const fileKey = parsed.fileKey;
+        let nodeIds;
+        if (options.id) {
+          nodeIds = parseNodeIds(options.id);
+        } else if (parsed.nodeId) {
+          nodeIds = [parsed.nodeId];
+        } else {
+          io.err.write(
+            chalk6.red(
+              "Error: node ID required. Use a URL with node-id or --id flag.\n"
+            )
+          );
+          process.exit(1);
+        }
         const token = await factory.getToken(options.token);
         const client = await factory.getClient();
-        const nodeIds = options.ids.split(",").map((id) => id.trim());
         if (options.token) {
           const { FigmaClient: FigmaClient2 } = await Promise.resolve().then(() => (init_client(), client_exports));
           const overrideClient = new FigmaClient2({ token });
@@ -1402,208 +1469,894 @@ function sanitizeFilename(name) {
   return name.replace(/[:/\\?*"<>|]/g, "-");
 }
 
-// src/cmd/file/images.ts
-function createFileImagesCommand(factory) {
-  const cmd = new Command7("images").description("Export images from a file").argument("<key>", "File key (from Figma URL)").requiredOption(
-    "-i, --ids <ids>",
-    "Comma-separated list of node IDs to export"
-  ).option("-s, --scale <scale>", "Scale factor (0.01-4)", parseFloat, 1).option("--format <format>", "Image format (jpg, png, svg, pdf)", "png").option("--svg-include-id", "Include node ID as an attribute in SVGs").option("--svg-simplify-stroke", "Simplify strokes in SVG export").option("-o, --output <dir>", "Output directory for downloaded images").option(
-    "-O, --output-format <format>",
-    "Output format (json, table)",
-    "json"
-  ).option("-t, --token <token>", "Override authentication token").action(
-    async (fileKey, options) => {
-      const { io } = factory;
-      const validFormats = ["jpg", "png", "svg", "pdf"];
-      if (!validFormats.includes(options.format)) {
-        io.err.write(
-          chalk7.red(
-            `Invalid format "${options.format}". Valid formats: ${validFormats.join(", ")}
-`
-          )
-        );
-        process.exit(1);
-      }
-      const imageFormat = options.format;
-      try {
-        const token = await factory.getToken(options.token);
-        const client = await factory.getClient();
-        const nodeIds = options.ids.split(",").map((id) => id.trim());
-        let activeClient = client;
-        if (options.token) {
-          const { FigmaClient: FigmaClient2 } = await Promise.resolve().then(() => (init_client(), client_exports));
-          activeClient = new FigmaClient2({ token });
-        }
-        const images = await activeClient.getImages(fileKey, nodeIds, {
-          scale: options.scale,
-          format: imageFormat,
-          svg_include_id: options.svgIncludeId,
-          svg_simplify_stroke: options.svgSimplifyStroke
-        });
-        if (options.output) {
-          const imageUrls = images.images || {};
-          const downloadItems = Object.entries(imageUrls).map(
-            ([nodeId, url]) => ({
-              id: nodeId,
-              url: url ?? null,
-              filename: `${sanitizeFilename(nodeId)}.${imageFormat}`
-            })
-          );
-          const results = await downloadFiles(downloadItems, options.output);
-          const downloadResults = results.map((r) => ({
-            nodeId: r.id,
-            file: r.file,
-            status: r.status === "success" ? "downloaded" : r.error ?? "error"
-          }));
-          io.out.write(
-            formatOutput(downloadResults, {
-              format: options.outputFormat
-            })
-          );
-          io.out.write("\n");
-        } else {
-          io.out.write(
-            formatOutput(images, {
-              format: options.outputFormat
-            })
-          );
-          io.out.write("\n");
-        }
-      } catch (error) {
-        io.err.write(chalk7.red("Error exporting images.\n"));
-        if (error instanceof Error) {
-          io.err.write(chalk7.dim(`${error.message}
-`));
-        }
-        process.exit(1);
-      }
-    }
-  );
-  return cmd;
+// src/internal/transform/tokens.ts
+function figmaColorToCss(color) {
+  const r = Math.round(color.r * 255);
+  const g = Math.round(color.g * 255);
+  const b = Math.round(color.b * 255);
+  const a = color.a ?? 1;
+  if (a === 1) {
+    return `#${r.toString(16).padStart(2, "0")}${g.toString(16).padStart(2, "0")}${b.toString(16).padStart(2, "0")}`;
+  }
+  return `rgba(${r}, ${g}, ${b}, ${a.toFixed(2)})`;
 }
-
-// src/cmd/file/index.ts
-function createFileCommand(factory) {
-  const cmd = new Command8("file").description("Work with Figma files");
-  cmd.addCommand(createFileGetCommand(factory));
-  cmd.addCommand(createFileNodesCommand(factory));
-  cmd.addCommand(createFileImagesCommand(factory));
-  return cmd;
+function toKebabCase(str) {
+  return str.replace(/\s+/g, "-").replace(/([a-z])([A-Z])/g, "$1-$2").replace(/[^a-zA-Z0-9-]/g, "-").replace(/-+/g, "-").toLowerCase();
 }
-
-// src/cmd/project/index.ts
-import { Command as Command11 } from "commander";
-
-// src/cmd/project/list.ts
-import { Command as Command9 } from "commander";
-import chalk8 from "chalk";
-function createProjectListCommand(factory) {
-  const cmd = new Command9("list").description("List team projects").requiredOption("--team <id>", "Team ID").option("-f, --format <format>", "Output format (json, table)", "json").option("-t, --token <token>", "Override authentication token").action(
-    async (options) => {
-      const { io } = factory;
-      try {
-        const token = await factory.getToken(options.token);
-        let client = await factory.getClient();
-        if (options.token) {
-          const { FigmaClient: FigmaClient2 } = await Promise.resolve().then(() => (init_client(), client_exports));
-          client = new FigmaClient2({ token });
-        }
-        const projects = await client.getTeamProjects(options.team);
-        if (options.format === "table") {
-          const tableData = projects.projects.map((p) => ({
-            id: p.id,
-            name: p.name
-          }));
-          io.out.write(
-            formatOutput(tableData, {
-              format: "table",
-              columns: ["id", "name"]
-            })
-          );
-        } else {
-          io.out.write(formatOutput(projects, { format: "json" }));
+function shadowToCss(shadow) {
+  const inset = shadow.inset ? "inset " : "";
+  return `${inset}${shadow.x}px ${shadow.y}px ${shadow.blur}px ${shadow.spread}px ${shadow.color}`;
+}
+function extractStylesFromFile(file, styleMetadata) {
+  const tokens = {
+    colors: {},
+    typography: {},
+    shadows: {},
+    radii: {},
+    spacing: {},
+    effects: {}
+  };
+  const seenRadii = /* @__PURE__ */ new Set();
+  const seenSpacing = /* @__PURE__ */ new Set();
+  const styleNodeMap = /* @__PURE__ */ new Map();
+  for (const style of styleMetadata) {
+    const nodeId = style.node_id;
+    if (nodeId) {
+      styleNodeMap.set(nodeId, style);
+    }
+  }
+  function traverseNode(node) {
+    const nodeWithStyles = node;
+    if ("styles" in nodeWithStyles && nodeWithStyles.styles) {
+      const styles = nodeWithStyles.styles;
+      if (styles.fill && "fills" in nodeWithStyles) {
+        const fills = nodeWithStyles.fills;
+        if (fills && fills.length > 0 && fills[0].type === "SOLID") {
+          const fill = fills[0];
+          if (fill.color) {
+            const styleInfo = styleNodeMap.get(node.id);
+            const styleName = styleInfo?.name || node.name;
+            const tokenName = toKebabCase(styleName);
+            tokens.colors[tokenName] = {
+              name: styleName,
+              type: "color",
+              value: figmaColorToCss(fill.color),
+              description: styleInfo?.description
+            };
+          }
         }
-        io.out.write("\n");
-      } catch (error) {
-        io.err.write(chalk8.red("Error fetching projects.\n"));
-        if (error instanceof Error) {
-          io.err.write(chalk8.dim(`${error.message}
-`));
+      }
+      if (styles.text && "style" in nodeWithStyles && nodeWithStyles.style) {
+        const textStyle = nodeWithStyles.style;
+        const styleInfo = styleNodeMap.get(node.id);
+        const styleName = styleInfo?.name || node.name;
+        const tokenName = toKebabCase(styleName);
+        tokens.typography[tokenName] = {
+          name: styleName,
+          type: "typography",
+          value: {
+            fontFamily: textStyle.fontFamily || "sans-serif",
+            fontSize: `${textStyle.fontSize || 16}px`,
+            fontWeight: textStyle.fontWeight || 400,
+            lineHeight: textStyle.lineHeightPx !== void 0 ? `${textStyle.lineHeightPx}px` : "normal",
+            letterSpacing: textStyle.letterSpacing !== void 0 ? `${textStyle.letterSpacing}px` : "normal"
+          },
+          description: styleInfo?.description
+        };
+      }
+      if (styles.effect && "effects" in nodeWithStyles && nodeWithStyles.effects) {
+        const effects = nodeWithStyles.effects;
+        const styleInfo = styleNodeMap.get(node.id);
+        const styleName = styleInfo?.name || node.name;
+        const baseTokenName = toKebabCase(styleName);
+        let shadowIndex = 0;
+        for (const effect of effects) {
+          if ((effect.type === "DROP_SHADOW" || effect.type === "INNER_SHADOW") && effect.visible !== false) {
+            const shadowEffect = effect;
+            const colorValue = shadowEffect.color ? figmaColorToCss(shadowEffect.color) : "rgba(0, 0, 0, 0.25)";
+            const tokenName = shadowIndex === 0 ? baseTokenName : `${baseTokenName}-${shadowIndex}`;
+            tokens.shadows[tokenName] = {
+              name: shadowIndex === 0 ? styleName : `${styleName} ${shadowIndex + 1}`,
+              type: "shadow",
+              value: {
+                x: shadowEffect.offset?.x ?? 0,
+                y: shadowEffect.offset?.y ?? 0,
+                blur: shadowEffect.radius ?? 0,
+                spread: shadowEffect.spread ?? 0,
+                color: colorValue,
+                inset: effect.type === "INNER_SHADOW"
+              },
+              description: styleInfo?.description
+            };
+            shadowIndex++;
+          }
         }
-        process.exit(1);
       }
     }
-  );
-  return cmd;
-}
-
-// src/cmd/project/files.ts
-import { Command as Command10 } from "commander";
-import chalk9 from "chalk";
-function createProjectFilesCommand(factory) {
-  const cmd = new Command10("files").description("List files in a project").argument("<project-id>", "Project ID").option("--branch-data", "Include branch metadata").option("-f, --format <format>", "Output format (json, table)", "json").option("-t, --token <token>", "Override authentication token").action(
-    async (projectId, options) => {
-      const { io } = factory;
-      try {
-        const token = await factory.getToken(options.token);
-        let client = await factory.getClient();
-        if (options.token) {
-          const { FigmaClient: FigmaClient2 } = await Promise.resolve().then(() => (init_client(), client_exports));
-          client = new FigmaClient2({ token });
-        }
-        const files = await client.getProjectFiles(projectId, {
-          branch_data: options.branchData
-        });
-        if (options.format === "table") {
-          const tableData = files.files.map((f) => ({
-            key: f.key,
-            name: f.name,
-            last_modified: f.last_modified
-          }));
-          io.out.write(
-            formatOutput(tableData, {
-              format: "table",
-              columns: ["key", "name", "last_modified"]
-            })
-          );
-        } else {
-          io.out.write(formatOutput(files, { format: "json" }));
+    if ("cornerRadius" in nodeWithStyles && nodeWithStyles.cornerRadius !== void 0) {
+      const radius = nodeWithStyles.cornerRadius;
+      if (radius > 0) {
+        const radiusValue = `${radius}px`;
+        if (!seenRadii.has(radiusValue)) {
+          seenRadii.add(radiusValue);
+          const tokenName = `radius-${radius}`;
+          tokens.radii[tokenName] = {
+            name: `Radius ${radius}`,
+            type: "radius",
+            value: radiusValue
+          };
+        }
+      }
+    }
+    if ("rectangleCornerRadii" in nodeWithStyles && nodeWithStyles.rectangleCornerRadii) {
+      const [topLeft, topRight, bottomRight, bottomLeft] = nodeWithStyles.rectangleCornerRadii;
+      for (const radius of [topLeft, topRight, bottomRight, bottomLeft]) {
+        if (radius > 0) {
+          const radiusValue = `${radius}px`;
+          if (!seenRadii.has(radiusValue)) {
+            seenRadii.add(radiusValue);
+            const tokenName = `radius-${radius}`;
+            tokens.radii[tokenName] = {
+              name: `Radius ${radius}`,
+              type: "radius",
+              value: radiusValue
+            };
+          }
         }
-        io.out.write("\n");
-      } catch (error) {
-        io.err.write(chalk9.red("Error fetching project files.\n"));
-        if (error instanceof Error) {
-          io.err.write(chalk9.dim(`${error.message}
-`));
+      }
+    }
+    if ("layoutMode" in nodeWithStyles && nodeWithStyles.layoutMode !== "NONE") {
+      if (nodeWithStyles.itemSpacing !== void 0 && nodeWithStyles.itemSpacing > 0) {
+        const spacingValue = `${nodeWithStyles.itemSpacing}px`;
+        if (!seenSpacing.has(spacingValue)) {
+          seenSpacing.add(spacingValue);
+          const tokenName = `spacing-${nodeWithStyles.itemSpacing}`;
+          tokens.spacing[tokenName] = {
+            name: `Spacing ${nodeWithStyles.itemSpacing}`,
+            type: "spacing",
+            value: spacingValue
+          };
+        }
+      }
+      const paddings = [
+        nodeWithStyles.paddingTop,
+        nodeWithStyles.paddingRight,
+        nodeWithStyles.paddingBottom,
+        nodeWithStyles.paddingLeft
+      ];
+      for (const padding of paddings) {
+        if (padding !== void 0 && padding > 0) {
+          const spacingValue = `${padding}px`;
+          if (!seenSpacing.has(spacingValue)) {
+            seenSpacing.add(spacingValue);
+            const tokenName = `spacing-${padding}`;
+            tokens.spacing[tokenName] = {
+              name: `Spacing ${padding}`,
+              type: "spacing",
+              value: spacingValue
+            };
+          }
         }
-        process.exit(1);
       }
     }
-  );
-  return cmd;
-}
-
+    if ("children" in node) {
+      const parent = node;
+      for (const child of parent.children || []) {
+        traverseNode(child);
+      }
+    }
+  }
+  if (file.document) {
+    traverseNode(file.document);
+  }
+  return tokens;
+}
+function tokensToCss(tokens) {
+  const lines = [":root {"];
+  if (tokens.colors && Object.keys(tokens.colors).length > 0) {
+    lines.push("  /* Colors */");
+    for (const [name, token] of Object.entries(tokens.colors)) {
+      lines.push(`  --color-${name}: ${token.value};`);
+    }
+    lines.push("");
+  }
+  if (tokens.typography && Object.keys(tokens.typography).length > 0) {
+    lines.push("  /* Typography */");
+    for (const [name, token] of Object.entries(tokens.typography)) {
+      const value = token.value;
+      lines.push(`  --font-${name}-family: ${value.fontFamily};`);
+      lines.push(`  --font-${name}-size: ${value.fontSize};`);
+      lines.push(`  --font-${name}-weight: ${value.fontWeight};`);
+      lines.push(`  --font-${name}-line-height: ${value.lineHeight};`);
+      lines.push(`  --font-${name}-letter-spacing: ${value.letterSpacing};`);
+    }
+    lines.push("");
+  }
+  if (tokens.shadows && Object.keys(tokens.shadows).length > 0) {
+    lines.push("  /* Shadows */");
+    for (const [name, token] of Object.entries(tokens.shadows)) {
+      const value = token.value;
+      const shadowCss = shadowToCss(value);
+      lines.push(`  --shadow-${name}: ${shadowCss};`);
+    }
+    lines.push("");
+  }
+  if (tokens.radii && Object.keys(tokens.radii).length > 0) {
+    lines.push("  /* Border Radii */");
+    for (const [name, token] of Object.entries(tokens.radii)) {
+      lines.push(`  --${name}: ${token.value};`);
+    }
+    lines.push("");
+  }
+  if (tokens.spacing && Object.keys(tokens.spacing).length > 0) {
+    lines.push("  /* Spacing */");
+    for (const [name, token] of Object.entries(tokens.spacing)) {
+      lines.push(`  --${name}: ${token.value};`);
+    }
+  }
+  lines.push("}");
+  return lines.join("\n");
+}
+function tokensToScss(tokens) {
+  const lines = [];
+  if (tokens.colors && Object.keys(tokens.colors).length > 0) {
+    lines.push("// Colors");
+    for (const [name, token] of Object.entries(tokens.colors)) {
+      lines.push(`$color-${name}: ${token.value};`);
+    }
+    lines.push("");
+  }
+  if (tokens.typography && Object.keys(tokens.typography).length > 0) {
+    lines.push("// Typography");
+    for (const [name, token] of Object.entries(tokens.typography)) {
+      const value = token.value;
+      lines.push(`$font-${name}-family: ${value.fontFamily};`);
+      lines.push(`$font-${name}-size: ${value.fontSize};`);
+      lines.push(`$font-${name}-weight: ${value.fontWeight};`);
+      lines.push(`$font-${name}-line-height: ${value.lineHeight};`);
+      lines.push(`$font-${name}-letter-spacing: ${value.letterSpacing};`);
+    }
+    lines.push("");
+  }
+  if (tokens.shadows && Object.keys(tokens.shadows).length > 0) {
+    lines.push("// Shadows");
+    for (const [name, token] of Object.entries(tokens.shadows)) {
+      const value = token.value;
+      const shadowCss = shadowToCss(value);
+      lines.push(`$shadow-${name}: ${shadowCss};`);
+    }
+    lines.push("");
+  }
+  if (tokens.radii && Object.keys(tokens.radii).length > 0) {
+    lines.push("// Border Radii");
+    for (const [name, token] of Object.entries(tokens.radii)) {
+      lines.push(`$${name}: ${token.value};`);
+    }
+    lines.push("");
+  }
+  if (tokens.spacing && Object.keys(tokens.spacing).length > 0) {
+    lines.push("// Spacing");
+    for (const [name, token] of Object.entries(tokens.spacing)) {
+      lines.push(`$${name}: ${token.value};`);
+    }
+  }
+  return lines.join("\n");
+}
+function tokensToStyleDictionary(tokens) {
+  const output = {};
+  if (tokens.colors && Object.keys(tokens.colors).length > 0) {
+    output.color = {};
+    for (const [name, token] of Object.entries(tokens.colors)) {
+      output.color[name] = {
+        value: token.value,
+        type: "color",
+        description: token.description
+      };
+    }
+  }
+  if (tokens.typography && Object.keys(tokens.typography).length > 0) {
+    output.typography = {};
+    for (const [name, token] of Object.entries(tokens.typography)) {
+      output.typography[name] = {
+        value: token.value,
+        type: "typography",
+        description: token.description
+      };
+    }
+  }
+  if (tokens.shadows && Object.keys(tokens.shadows).length > 0) {
+    output.shadow = {};
+    for (const [name, token] of Object.entries(tokens.shadows)) {
+      output.shadow[name] = {
+        value: token.value,
+        type: "shadow",
+        description: token.description
+      };
+    }
+  }
+  if (tokens.radii && Object.keys(tokens.radii).length > 0) {
+    output.borderRadius = {};
+    for (const [name, token] of Object.entries(tokens.radii)) {
+      output.borderRadius[name] = {
+        value: token.value,
+        type: "dimension",
+        description: token.description
+      };
+    }
+  }
+  if (tokens.spacing && Object.keys(tokens.spacing).length > 0) {
+    output.spacing = {};
+    for (const [name, token] of Object.entries(tokens.spacing)) {
+      output.spacing[name] = {
+        value: token.value,
+        type: "dimension",
+        description: token.description
+      };
+    }
+  }
+  return JSON.stringify(output, null, 2);
+}
+function tokensToTailwind(tokens) {
+  const config = {
+    theme: {
+      extend: {}
+    }
+  };
+  if (tokens.colors && Object.keys(tokens.colors).length > 0) {
+    config.theme.extend.colors = {};
+    for (const [name, token] of Object.entries(tokens.colors)) {
+      config.theme.extend.colors[name] = token.value;
+    }
+  }
+  if (tokens.typography && Object.keys(tokens.typography).length > 0) {
+    config.theme.extend.fontFamily = {};
+    config.theme.extend.fontSize = {};
+    for (const [name, token] of Object.entries(tokens.typography)) {
+      const value = token.value;
+      config.theme.extend.fontFamily[name] = [value.fontFamily];
+      config.theme.extend.fontSize[name] = value.fontSize;
+    }
+  }
+  if (tokens.shadows && Object.keys(tokens.shadows).length > 0) {
+    config.theme.extend.boxShadow = {};
+    for (const [name, token] of Object.entries(tokens.shadows)) {
+      config.theme.extend.boxShadow[name] = shadowToCss(token.value);
+    }
+  }
+  if (tokens.radii && Object.keys(tokens.radii).length > 0) {
+    config.theme.extend.borderRadius = {};
+    for (const [name, token] of Object.entries(tokens.radii)) {
+      config.theme.extend.borderRadius[name] = token.value;
+    }
+  }
+  if (tokens.spacing && Object.keys(tokens.spacing).length > 0) {
+    config.theme.extend.spacing = {};
+    for (const [name, token] of Object.entries(tokens.spacing)) {
+      config.theme.extend.spacing[name] = token.value;
+    }
+  }
+  return `/** @type {import('tailwindcss').Config} */
+module.exports = ${JSON.stringify(config, null, 2)};`;
+}
+
+// src/cmd/file/images.ts
+function getNodeInfoMap(nodes, nodeIds) {
+  const nodeInfoMap = /* @__PURE__ */ new Map();
+  for (const nodeId of nodeIds) {
+    const nodeData = nodes[nodeId];
+    if (nodeData && nodeData.document) {
+      const node = nodeData.document;
+      const nameParts = node.name.split("/");
+      const name = nameParts[nameParts.length - 1];
+      const parentNames = nameParts.slice(0, -1);
+      nodeInfoMap.set(nodeId, {
+        name,
+        parentNames
+      });
+    }
+  }
+  return nodeInfoMap;
+}
+function generateFilename(nodeId, nodeInfo, namingStrategy, format, isVariant, variantSuffix) {
+  let baseName;
+  switch (namingStrategy) {
+    case "name":
+      if (nodeInfo) {
+        baseName = toKebabCase(nodeInfo.name);
+      } else {
+        baseName = sanitizeFilename(nodeId);
+      }
+      break;
+    case "path":
+      if (nodeInfo && nodeInfo.parentNames.length > 0) {
+        const pathParts = [...nodeInfo.parentNames, nodeInfo.name];
+        baseName = pathParts.map((p) => toKebabCase(p)).join("--");
+      } else if (nodeInfo) {
+        baseName = toKebabCase(nodeInfo.name);
+      } else {
+        baseName = sanitizeFilename(nodeId);
+      }
+      break;
+    case "id":
+    default:
+      baseName = sanitizeFilename(nodeId);
+      break;
+  }
+  if (isVariant && variantSuffix) {
+    baseName = `${baseName}--${toKebabCase(variantSuffix)}`;
+  }
+  return `${baseName}.${format}`;
+}
+function createFileImagesCommand(factory) {
+  const cmd = new Command7("images").description("Export images from a file").argument("<url>", "Figma URL (with node-id) or file key").option("--id <ids>", "Comma-separated node IDs (overrides URL node-id)").option("-s, --scale <scale>", "Scale factor (0.01-4)", parseFloat, 1).option("--format <format>", "Image format (jpg, png, svg, pdf)", "png").option("--svg-include-id", "Include node ID as an attribute in SVGs").option("--svg-simplify-stroke", "Simplify strokes in SVG export").option("-o, --output <dir>", "Output directory for downloaded images").option(
+    "-O, --output-format <format>",
+    "Output format (json, table)",
+    "json"
+  ).option(
+    "--naming <strategy>",
+    "Naming strategy: id, name, or path (default: id)",
+    "id"
+  ).option("-t, --token <token>", "Override authentication token").action(
+    async (url, options) => {
+      const { io } = factory;
+      const validFormats = ["jpg", "png", "svg", "pdf"];
+      if (!validFormats.includes(options.format)) {
+        io.err.write(
+          chalk7.red(
+            `Invalid format "${options.format}". Valid formats: ${validFormats.join(", ")}
+`
+          )
+        );
+        process.exit(1);
+      }
+      const imageFormat = options.format;
+      if (isNaN(options.scale) || options.scale < 0.01 || options.scale > 4) {
+        io.err.write(
+          chalk7.red(
+            `Invalid scale "${options.scale}". Scale must be between 0.01 and 4.
+`
+          )
+        );
+        process.exit(1);
+      }
+      const validNamingStrategies = ["id", "name", "path"];
+      if (!validNamingStrategies.includes(options.naming)) {
+        io.err.write(
+          chalk7.red(
+            `Invalid naming strategy "${options.naming}". Valid strategies: ${validNamingStrategies.join(", ")}
+`
+          )
+        );
+        process.exit(1);
+      }
+      const namingStrategy = options.naming;
+      try {
+        const parsed = parseFigmaInput(url);
+        const fileKey = parsed.fileKey;
+        let nodeIds;
+        if (options.id) {
+          nodeIds = parseNodeIds(options.id);
+        } else if (parsed.nodeId) {
+          nodeIds = [parsed.nodeId];
+        } else {
+          io.err.write(
+            chalk7.red(
+              "Error: node ID required. Use a URL with node-id or --id flag.\n"
+            )
+          );
+          process.exit(1);
+        }
+        const client = await factory.getClient();
+        let activeClient = client;
+        if (options.token) {
+          const { FigmaClient: FigmaClient2 } = await Promise.resolve().then(() => (init_client(), client_exports));
+          activeClient = new FigmaClient2({ token: options.token });
+        }
+        const images = await activeClient.getImages(fileKey, nodeIds, {
+          scale: options.scale,
+          format: imageFormat,
+          svg_include_id: options.svgIncludeId,
+          svg_simplify_stroke: options.svgSimplifyStroke
+        });
+        if (options.output) {
+          const imageUrls = images.images || {};
+          if (Object.keys(imageUrls).length === 0) {
+            io.err.write(
+              chalk7.yellow(
+                "Warning: No image URLs returned from Figma API.\n"
+              )
+            );
+          }
+          let nodeInfoMap = /* @__PURE__ */ new Map();
+          if (namingStrategy === "name" || namingStrategy === "path") {
+            try {
+              const nodesResponse = await activeClient.getFileNodes(
+                fileKey,
+                nodeIds
+              );
+              nodeInfoMap = getNodeInfoMap(nodesResponse.nodes, nodeIds);
+            } catch (fetchError) {
+              const errorMsg = fetchError instanceof Error ? fetchError.message : String(fetchError);
+              io.err.write(
+                chalk7.yellow(
+                  `Warning: Could not fetch node names (${errorMsg}), falling back to ID naming.
+`
+                )
+              );
+            }
+          }
+          const downloadItems = Object.entries(imageUrls).map(
+            ([nodeId, url2]) => {
+              const nodeInfo = nodeInfoMap.get(nodeId);
+              const filename = generateFilename(
+                nodeId,
+                nodeInfo,
+                namingStrategy,
+                imageFormat,
+                false
+              );
+              return {
+                id: nodeId,
+                url: url2 ?? null,
+                filename
+              };
+            }
+          );
+          const results = await downloadFiles(downloadItems, options.output);
+          const failures = results.filter((r) => r.status === "error");
+          const downloadResults = results.map((r) => ({
+            nodeId: r.id,
+            file: r.file,
+            status: r.status === "success" ? "downloaded" : r.error ?? "error"
+          }));
+          io.out.write(
+            formatOutput(downloadResults, {
+              format: options.outputFormat
+            })
+          );
+          io.out.write("\n");
+          if (failures.length > 0) {
+            io.err.write(
+              chalk7.yellow(
+                `${failures.length} image(s) failed to download.
+`
+              )
+            );
+            process.exit(1);
+          }
+        } else {
+          io.out.write(
+            formatOutput(images, {
+              format: options.outputFormat
+            })
+          );
+          io.out.write("\n");
+        }
+      } catch (error) {
+        io.err.write(chalk7.red("Error exporting images.\n"));
+        if (error instanceof Error) {
+          io.err.write(chalk7.dim(`${error.message}
+`));
+        }
+        process.exit(1);
+      }
+    }
+  );
+  return cmd;
+}
+
+// src/cmd/file/structure.ts
+import { Command as Command8 } from "commander";
+import chalk8 from "chalk";
+import * as fs4 from "fs";
+import * as path4 from "path";
+function extractFrameInfo(node, currentDepth, maxDepth, includeHidden) {
+  const nodeWithBounds = node;
+  if (!includeHidden && nodeWithBounds.visible === false) {
+    return null;
+  }
+  const relevantTypes = [
+    "FRAME",
+    "COMPONENT",
+    "COMPONENT_SET",
+    "SECTION",
+    "GROUP",
+    "INSTANCE"
+  ];
+  if (!relevantTypes.includes(node.type)) {
+    return null;
+  }
+  const frame = {
+    id: node.id,
+    name: node.name,
+    type: node.type
+  };
+  if (nodeWithBounds.absoluteBoundingBox) {
+    frame.width = Math.round(nodeWithBounds.absoluteBoundingBox.width);
+    frame.height = Math.round(nodeWithBounds.absoluteBoundingBox.height);
+  }
+  if (currentDepth < maxDepth && "children" in node) {
+    const parent = node;
+    const children = (parent.children || []).map(
+      (child) => extractFrameInfo(child, currentDepth + 1, maxDepth, includeHidden)
+    ).filter((child) => child !== null);
+    if (children.length > 0) {
+      frame.children = children;
+    }
+  }
+  return frame;
+}
+function extractStructure(file, maxDepth, includeHidden) {
+  const pages = [];
+  if (file.document && "children" in file.document) {
+    const doc = file.document;
+    for (const pageNode of doc.children || []) {
+      if (pageNode.type !== "CANVAS") continue;
+      const page = {
+        id: pageNode.id,
+        name: pageNode.name,
+        frames: []
+      };
+      if ("children" in pageNode) {
+        const pageWithChildren = pageNode;
+        for (const child of pageWithChildren.children || []) {
+          const frame = extractFrameInfo(child, 1, maxDepth, includeHidden);
+          if (frame) {
+            page.frames.push(frame);
+          }
+        }
+      }
+      pages.push(page);
+    }
+  }
+  return {
+    name: file.name,
+    lastModified: file.lastModified,
+    version: file.version,
+    pages
+  };
+}
+function formatTree(structure) {
+  const lines = [];
+  lines.push(`\u{1F4C1} ${structure.name}`);
+  lines.push(`   Last Modified: ${structure.lastModified}`);
+  lines.push("");
+  for (let i = 0; i < structure.pages.length; i++) {
+    const page = structure.pages[i];
+    const isLastPage = i === structure.pages.length - 1;
+    const pagePrefix = isLastPage ? "\u2514\u2500\u2500" : "\u251C\u2500\u2500";
+    lines.push(`${pagePrefix} \u{1F4C4} ${page.name} (${page.id})`);
+    const indent = isLastPage ? "    " : "\u2502   ";
+    formatFramesTree(page.frames, indent, lines);
+  }
+  return lines.join("\n");
+}
+function formatFramesTree(frames, indent, lines) {
+  for (let i = 0; i < frames.length; i++) {
+    const frame = frames[i];
+    const isLast = i === frames.length - 1;
+    const prefix = isLast ? "\u2514\u2500\u2500" : "\u251C\u2500\u2500";
+    const icon = getTypeIcon(frame.type);
+    const sizeInfo = frame.width && frame.height ? ` (${frame.width}\xD7${frame.height})` : "";
+    lines.push(`${indent}${prefix} ${icon} ${frame.name}${sizeInfo}`);
+    if (frame.children && frame.children.length > 0) {
+      const childIndent = indent + (isLast ? "    " : "\u2502   ");
+      formatFramesTree(frame.children, childIndent, lines);
+    }
+  }
+}
+function getTypeIcon(type) {
+  switch (type) {
+    case "COMPONENT":
+      return "\u{1F537}";
+    case "COMPONENT_SET":
+      return "\u{1F536}";
+    case "FRAME":
+      return "\u2B1C";
+    case "SECTION":
+      return "\u{1F4C2}";
+    case "GROUP":
+      return "\u{1F4E6}";
+    case "INSTANCE":
+      return "\u25C7";
+    default:
+      return "\u25AB";
+  }
+}
+function createFileStructureCommand(factory) {
+  const cmd = new Command8("structure").description("Get simplified file structure").argument("<url>", "Figma URL or file key").option("-d, --depth <depth>", "Max depth of hierarchy (default: 2)", "2").option("--include-hidden", "Include hidden nodes", false).option("-f, --format <format>", "Output format (json, tree)", "json").option("-o, --output <file>", "Write output to file").option("-t, --token <token>", "Override authentication token").action(
+    async (url, options) => {
+      const { io } = factory;
+      try {
+        const parsed = parseFigmaInput(url);
+        const fileKey = parsed.fileKey;
+        const maxDepth = parseInt(options.depth, 10);
+        if (isNaN(maxDepth) || maxDepth < 1) {
+          io.err.write(
+            chalk8.red(
+              `Invalid depth "${options.depth}". Depth must be a positive integer.
+`
+            )
+          );
+          process.exit(1);
+        }
+        const validFormats = ["json", "tree"];
+        if (!validFormats.includes(
+          options.format
+        )) {
+          io.err.write(
+            chalk8.red(
+              `Invalid format "${options.format}". Valid formats: ${validFormats.join(", ")}
+`
+            )
+          );
+          process.exit(1);
+        }
+        const client = await factory.getClient();
+        let activeClient = client;
+        if (options.token) {
+          const { FigmaClient: FigmaClient2 } = await Promise.resolve().then(() => (init_client(), client_exports));
+          activeClient = new FigmaClient2({ token: options.token });
+        }
+        const file = await activeClient.getFile(fileKey, {
+          depth: maxDepth + 1
+          // +1 to include top-level frames
+        });
+        const structure = extractStructure(
+          file,
+          maxDepth,
+          options.includeHidden
+        );
+        let output;
+        if (options.format === "tree") {
+          output = formatTree(structure);
+        } else {
+          output = JSON.stringify(structure, null, 2);
+        }
+        if (options.output) {
+          const outputPath = path4.resolve(options.output);
+          fs4.writeFileSync(outputPath, output + "\n");
+          io.out.write(chalk8.green(`Structure written to ${outputPath}
+`));
+        } else {
+          io.out.write(output + "\n");
+        }
+      } catch (error) {
+        io.err.write(chalk8.red("Error fetching file structure.\n"));
+        if (error instanceof Error) {
+          io.err.write(chalk8.dim(`${error.message}
+`));
+        }
+        process.exit(1);
+      }
+    }
+  );
+  return cmd;
+}
+
+// src/cmd/file/index.ts
+function createFileCommand(factory) {
+  const cmd = new Command9("file").description("Work with Figma files");
+  cmd.addCommand(createFileGetCommand(factory));
+  cmd.addCommand(createFileNodesCommand(factory));
+  cmd.addCommand(createFileImagesCommand(factory));
+  cmd.addCommand(createFileStructureCommand(factory));
+  return cmd;
+}
+
+// src/cmd/project/index.ts
+import { Command as Command12 } from "commander";
+
+// src/cmd/project/list.ts
+import { Command as Command10 } from "commander";
+import chalk9 from "chalk";
+function createProjectListCommand(factory) {
+  const cmd = new Command10("list").description("List team projects").requiredOption("--team <id>", "Team ID").option("-f, --format <format>", "Output format (json, table)", "json").option("-t, --token <token>", "Override authentication token").action(
+    async (options) => {
+      const { io } = factory;
+      try {
+        const token = await factory.getToken(options.token);
+        let client = await factory.getClient();
+        if (options.token) {
+          const { FigmaClient: FigmaClient2 } = await Promise.resolve().then(() => (init_client(), client_exports));
+          client = new FigmaClient2({ token });
+        }
+        const projects = await client.getTeamProjects(options.team);
+        if (options.format === "table") {
+          const tableData = projects.projects.map((p) => ({
+            id: p.id,
+            name: p.name
+          }));
+          io.out.write(
+            formatOutput(tableData, {
+              format: "table",
+              columns: ["id", "name"]
+            })
+          );
+        } else {
+          io.out.write(formatOutput(projects, { format: "json" }));
+        }
+        io.out.write("\n");
+      } catch (error) {
+        io.err.write(chalk9.red("Error fetching projects.\n"));
+        if (error instanceof Error) {
+          io.err.write(chalk9.dim(`${error.message}
+`));
+        }
+        process.exit(1);
+      }
+    }
+  );
+  return cmd;
+}
+
+// src/cmd/project/files.ts
+import { Command as Command11 } from "commander";
+import chalk10 from "chalk";
+function createProjectFilesCommand(factory) {
+  const cmd = new Command11("files").description("List files in a project").argument("<project-id>", "Project ID").option("--branch-data", "Include branch metadata").option("-f, --format <format>", "Output format (json, table)", "json").option("-t, --token <token>", "Override authentication token").action(
+    async (projectId, options) => {
+      const { io } = factory;
+      try {
+        const token = await factory.getToken(options.token);
+        let client = await factory.getClient();
+        if (options.token) {
+          const { FigmaClient: FigmaClient2 } = await Promise.resolve().then(() => (init_client(), client_exports));
+          client = new FigmaClient2({ token });
+        }
+        const files = await client.getProjectFiles(projectId, {
+          branch_data: options.branchData
+        });
+        if (options.format === "table") {
+          const tableData = files.files.map((f) => ({
+            key: f.key,
+            name: f.name,
+            last_modified: f.last_modified
+          }));
+          io.out.write(
+            formatOutput(tableData, {
+              format: "table",
+              columns: ["key", "name", "last_modified"]
+            })
+          );
+        } else {
+          io.out.write(formatOutput(files, { format: "json" }));
+        }
+        io.out.write("\n");
+      } catch (error) {
+        io.err.write(chalk10.red("Error fetching project files.\n"));
+        if (error instanceof Error) {
+          io.err.write(chalk10.dim(`${error.message}
+`));
+        }
+        process.exit(1);
+      }
+    }
+  );
+  return cmd;
+}
+
 // src/cmd/project/index.ts
 function createProjectCommand(factory) {
-  const cmd = new Command11("project").description("Work with Figma projects");
+  const cmd = new Command12("project").description("Work with Figma projects");
   cmd.addCommand(createProjectListCommand(factory));
   cmd.addCommand(createProjectFilesCommand(factory));
   return cmd;
 }
 
 // src/cmd/component/index.ts
-import { Command as Command14 } from "commander";
+import { Command as Command15 } from "commander";
 
 // src/cmd/component/list.ts
-import { Command as Command12 } from "commander";
-import chalk10 from "chalk";
+import { Command as Command13 } from "commander";
+import chalk11 from "chalk";
 function createComponentListCommand(factory) {
-  const cmd = new Command12("list").description("List components (from team or file)").option("--team <id>", "Team ID to list components from").option("--file <key>", "File key to list components from").option("--page-size <size>", "Number of results per page", parseInt).option("-f, --format <format>", "Output format (json, table)", "json").option("-t, --token <token>", "Override authentication token").action(
+  const cmd = new Command13("list").description("List components (from team or file)").option("--team <id>", "Team ID to list components from").option("--file <url>", "Figma URL or file key").option("--page-size <size>", "Number of results per page", parseInt).option("-f, --format <format>", "Output format (json, table)", "json").option("-t, --token <token>", "Override authentication token").action(
     async (options) => {
       const { io } = factory;
       if (!options.team && !options.file) {
         io.err.write(
-          chalk10.red("Error: Either --team or --file must be specified.\n")
+          chalk11.red("Error: Either --team or --file must be specified.\n")
         );
         process.exit(1);
       }
@@ -1634,7 +2387,8 @@ function createComponentListCommand(factory) {
             io.out.write(formatOutput(components, { format: "json" }));
           }
         } else if (options.file) {
-          const components = await client.getFileComponents(options.file);
+          const parsed = parseFigmaInput(options.file);
+          const components = await client.getFileComponents(parsed.fileKey);
           if (options.format === "table") {
             const tableData = components.meta?.components?.map((c) => ({
               key: c.key,
@@ -1653,9 +2407,9 @@ function createComponentListCommand(factory) {
         }
         io.out.write("\n");
       } catch (error) {
-        io.err.write(chalk10.red("Error fetching components.\n"));
+        io.err.write(chalk11.red("Error fetching components.\n"));
         if (error instanceof Error) {
-          io.err.write(chalk10.dim(`${error.message}
+          io.err.write(chalk11.dim(`${error.message}
 `));
         }
         process.exit(1);
@@ -1666,10 +2420,10 @@ function createComponentListCommand(factory) {
 }
 
 // src/cmd/component/get.ts
-import { Command as Command13 } from "commander";
-import chalk11 from "chalk";
+import { Command as Command14 } from "commander";
+import chalk12 from "chalk";
 function createComponentGetCommand(factory) {
-  const cmd = new Command13("get").description("Get component details").argument("<key>", "Component key").option("-f, --format <format>", "Output format (json, table)", "json").option("-t, --token <token>", "Override authentication token").action(
+  const cmd = new Command14("get").description("Get component details").argument("<key>", "Component key").option("-f, --format <format>", "Output format (json, table)", "json").option("-t, --token <token>", "Override authentication token").action(
     async (componentKey, options) => {
       const { io } = factory;
       try {
@@ -1687,9 +2441,9 @@ function createComponentGetCommand(factory) {
         );
         io.out.write("\n");
       } catch (error) {
-        io.err.write(chalk11.red("Error fetching component.\n"));
+        io.err.write(chalk12.red("Error fetching component.\n"));
         if (error instanceof Error) {
-          io.err.write(chalk11.dim(`${error.message}
+          io.err.write(chalk12.dim(`${error.message}
 `));
         }
         process.exit(1);
@@ -1701,7 +2455,7 @@ function createComponentGetCommand(factory) {
 
 // src/cmd/component/index.ts
 function createComponentCommand(factory) {
-  const cmd = new Command14("component").description(
+  const cmd = new Command15("component").description(
     "Work with Figma components"
   );
   cmd.addCommand(createComponentListCommand(factory));
@@ -1710,18 +2464,18 @@ function createComponentCommand(factory) {
 }
 
 // src/cmd/style/index.ts
-import { Command as Command17 } from "commander";
+import { Command as Command18 } from "commander";
 
 // src/cmd/style/list.ts
-import { Command as Command15 } from "commander";
-import chalk12 from "chalk";
+import { Command as Command16 } from "commander";
+import chalk13 from "chalk";
 function createStyleListCommand(factory) {
-  const cmd = new Command15("list").description("List styles (from team or file)").option("--team <id>", "Team ID to list styles from").option("--file <key>", "File key to list styles from").option("--page-size <size>", "Number of results per page", parseInt).option("-f, --format <format>", "Output format (json, table)", "json").option("-t, --token <token>", "Override authentication token").action(
+  const cmd = new Command16("list").description("List styles (from team or file)").option("--team <id>", "Team ID to list styles from").option("--file <url>", "Figma URL or file key").option("--page-size <size>", "Number of results per page", parseInt).option("-f, --format <format>", "Output format (json, table)", "json").option("-t, --token <token>", "Override authentication token").action(
     async (options) => {
       const { io } = factory;
       if (!options.team && !options.file) {
         io.err.write(
-          chalk12.red("Error: Either --team or --file must be specified.\n")
+          chalk13.red("Error: Either --team or --file must be specified.\n")
         );
         process.exit(1);
       }
@@ -1753,7 +2507,8 @@ function createStyleListCommand(factory) {
             io.out.write(formatOutput(styles, { format: "json" }));
           }
         } else if (options.file) {
-          const styles = await client.getFileStyles(options.file);
+          const parsed = parseFigmaInput(options.file);
+          const styles = await client.getFileStyles(parsed.fileKey);
           if (options.format === "table") {
             const tableData = styles.meta?.styles?.map((s) => ({
               key: s.key,
@@ -1773,9 +2528,9 @@ function createStyleListCommand(factory) {
         }
         io.out.write("\n");
       } catch (error) {
-        io.err.write(chalk12.red("Error fetching styles.\n"));
+        io.err.write(chalk13.red("Error fetching styles.\n"));
         if (error instanceof Error) {
-          io.err.write(chalk12.dim(`${error.message}
+          io.err.write(chalk13.dim(`${error.message}
 `));
         }
         process.exit(1);
@@ -1786,10 +2541,10 @@ function createStyleListCommand(factory) {
 }
 
 // src/cmd/style/get.ts
-import { Command as Command16 } from "commander";
-import chalk13 from "chalk";
+import { Command as Command17 } from "commander";
+import chalk14 from "chalk";
 function createStyleGetCommand(factory) {
-  const cmd = new Command16("get").description("Get style details").argument("<key>", "Style key").option("-f, --format <format>", "Output format (json, table)", "json").option("-t, --token <token>", "Override authentication token").action(
+  const cmd = new Command17("get").description("Get style details").argument("<key>", "Style key").option("-f, --format <format>", "Output format (json, table)", "json").option("-t, --token <token>", "Override authentication token").action(
     async (styleKey, options) => {
       const { io } = factory;
       try {
@@ -1807,9 +2562,9 @@ function createStyleGetCommand(factory) {
         );
         io.out.write("\n");
       } catch (error) {
-        io.err.write(chalk13.red("Error fetching style.\n"));
+        io.err.write(chalk14.red("Error fetching style.\n"));
         if (error instanceof Error) {
-          io.err.write(chalk13.dim(`${error.message}
+          io.err.write(chalk14.dim(`${error.message}
 `));
         }
         process.exit(1);
@@ -1821,23 +2576,25 @@ function createStyleGetCommand(factory) {
 
 // src/cmd/style/index.ts
 function createStyleCommand(factory) {
-  const cmd = new Command17("style").description("Work with Figma styles");
+  const cmd = new Command18("style").description("Work with Figma styles");
   cmd.addCommand(createStyleListCommand(factory));
   cmd.addCommand(createStyleGetCommand(factory));
   return cmd;
 }
 
 // src/cmd/variable/index.ts
-import { Command as Command20 } from "commander";
+import { Command as Command21 } from "commander";
 
 // src/cmd/variable/list.ts
-import { Command as Command18 } from "commander";
-import chalk14 from "chalk";
+import { Command as Command19 } from "commander";
+import chalk15 from "chalk";
 function createVariableListCommand(factory) {
-  const cmd = new Command18("list").description("List variables from a file (Enterprise)").argument("<file-key>", "File key").option("--published", "List published variables only").option("-f, --format <format>", "Output format (json, table)", "json").option("-t, --token <token>", "Override authentication token").action(
-    async (fileKey, options) => {
+  const cmd = new Command19("list").description("List variables from a file (Enterprise)").argument("<url>", "Figma URL or file key").option("--published", "List published variables only").option("-f, --format <format>", "Output format (json, table)", "json").option("-t, --token <token>", "Override authentication token").action(
+    async (url, options) => {
       const { io } = factory;
       try {
+        const parsed = parseFigmaInput(url);
+        const fileKey = parsed.fileKey;
         const token = await factory.getToken(options.token);
         let client = await factory.getClient();
         if (options.token) {
@@ -1865,13 +2622,13 @@ function createVariableListCommand(factory) {
         }
         io.out.write("\n");
       } catch (error) {
-        io.err.write(chalk14.red("Error fetching variables.\n"));
+        io.err.write(chalk15.red("Error fetching variables.\n"));
         if (error instanceof Error) {
-          io.err.write(chalk14.dim(`${error.message}
+          io.err.write(chalk15.dim(`${error.message}
 `));
         }
         io.err.write(
-          chalk14.dim("\nNote: Variables API requires Figma Enterprise plan.\n")
+          chalk15.dim("\nNote: Variables API requires Figma Enterprise plan.\n")
         );
         process.exit(1);
       }
@@ -1881,28 +2638,115 @@ function createVariableListCommand(factory) {
 }
 
 // src/cmd/variable/export.ts
-import { Command as Command19 } from "commander";
-import chalk15 from "chalk";
-import * as fs4 from "fs";
+import { Command as Command20 } from "commander";
+import chalk16 from "chalk";
+import * as fs5 from "fs";
+var SCOPE_CATEGORIES = {
+  colors: [
+    "ALL_FILLS",
+    "FRAME_FILL",
+    "SHAPE_FILL",
+    "TEXT_FILL",
+    "STROKE_COLOR"
+  ],
+  spacing: ["GAP", "WIDTH_HEIGHT"],
+  radius: ["CORNER_RADIUS"],
+  effects: ["EFFECT_COLOR"],
+  typography: [
+    "FONT_FAMILY",
+    "FONT_SIZE",
+    "FONT_WEIGHT",
+    "LINE_HEIGHT",
+    "LETTER_SPACING"
+  ],
+  other: []
+};
+function categorizeVariables(variables) {
+  const categorized = {
+    colors: [],
+    spacing: [],
+    radius: [],
+    effects: [],
+    typography: [],
+    other: []
+  };
+  for (const variable of Object.values(variables)) {
+    const scopes = variable.scopes || [];
+    let placed = false;
+    for (const [category, categoryScopes] of Object.entries(SCOPE_CATEGORIES)) {
+      if (category === "other") continue;
+      if (scopes.some((scope) => categoryScopes.includes(scope))) {
+        categorized[category].push(variable);
+        placed = true;
+        break;
+      }
+    }
+    if (!placed) {
+      switch (variable.resolvedType) {
+        case "COLOR":
+          categorized.colors.push(variable);
+          break;
+        case "FLOAT": {
+          const nameLower = variable.name.toLowerCase();
+          if (nameLower.includes("radius") || nameLower.includes("corner")) {
+            categorized.radius.push(variable);
+          } else if (nameLower.includes("spacing") || nameLower.includes("gap") || nameLower.includes("padding") || nameLower.includes("margin")) {
+            categorized.spacing.push(variable);
+          } else {
+            categorized.other.push(variable);
+          }
+          break;
+        }
+        default:
+          categorized.other.push(variable);
+      }
+    }
+  }
+  return Object.fromEntries(
+    Object.entries(categorized).filter(([, vars]) => vars.length > 0)
+  );
+}
 function createVariableExportCommand(factory) {
-  const cmd = new Command19("export").description("Export variables as design tokens (Enterprise)").argument("<file-key>", "File key").option(
+  const cmd = new Command20("export").description("Export variables as design tokens (Enterprise)").argument("<url>", "Figma URL or file key").option(
     "--format <format>",
     "Output format (json, css, scss, style-dictionary)",
     "json"
-  ).option("--mode <mode>", "Specific mode to export").option("-o, --output <file>", "Output file path").option("-t, --token <token>", "Override authentication token").action(
-    async (fileKey, options) => {
+  ).option("--mode <mode>", "Specific mode to export").option(
+    "--categorize",
+    "Group variables by scope (CORNER_RADIUS, GAP, etc.)",
+    false
+  ).option("-o, --output <file>", "Output file path").option("-t, --token <token>", "Override authentication token").action(
+    async (url, options) => {
       const { io } = factory;
+      const validFormats = [
+        "json",
+        "css",
+        "scss",
+        "style-dictionary"
+      ];
+      if (!validFormats.includes(
+        options.format
+      )) {
+        io.err.write(
+          chalk16.red(
+            `Invalid format "${options.format}". Valid formats: ${validFormats.join(", ")}
+`
+          )
+        );
+        process.exit(1);
+      }
       try {
-        const token = await factory.getToken(options.token);
+        const parsed = parseFigmaInput(url);
+        const fileKey = parsed.fileKey;
         let client = await factory.getClient();
         if (options.token) {
           const { FigmaClient: FigmaClient2 } = await Promise.resolve().then(() => (init_client(), client_exports));
-          client = new FigmaClient2({ token });
+          client = new FigmaClient2({ token: options.token });
         }
         const response = await client.getLocalVariables(fileKey);
         const meta = response.meta;
         if (!meta) {
-          io.err.write(chalk15.red("No variables found in file.\n"));
+          io.err.write(chalk16.red("No variables found in file.\n"));
           process.exit(1);
         }
         const variables = meta.variables;
@@ -1919,13 +2763,13 @@ function createVariableExportCommand(factory) {
             }
           }
           if (!targetModeId) {
-            io.err.write(chalk15.red(`Mode "${options.mode}" not found.
+            io.err.write(chalk16.red(`Mode "${options.mode}" not found.
 `));
             const allModes = Object.values(collections).flatMap(
               (c) => c.modes.map((m) => m.name)
             );
             io.err.write(
-              chalk15.dim(`Available modes: ${allModes.join(", ")}
+              chalk16.dim(`Available modes: ${allModes.join(", ")}
 `)
             );
             process.exit(1);
@@ -1934,37 +2778,53 @@ function createVariableExportCommand(factory) {
         let output;
         switch (options.format) {
           case "css":
-            output = exportToCss(variables, collections, targetModeId);
+            output = exportToCss(
+              variables,
+              collections,
+              targetModeId,
+              options.categorize
+            );
             break;
           case "scss":
-            output = exportToScss(variables, collections, targetModeId);
+            output = exportToScss(
+              variables,
+              collections,
+              targetModeId,
+              options.categorize
+            );
             break;
           case "style-dictionary":
             output = exportToStyleDictionary(
               variables,
               collections,
-              targetModeId
+              targetModeId,
+              options.categorize
             );
             break;
           default:
-            output = JSON.stringify({ variables, collections }, null, 2);
+            if (options.categorize) {
+              const categorized = categorizeVariables(variables);
+              output = JSON.stringify({ categorized, collections }, null, 2);
+            } else {
+              output = JSON.stringify({ variables, collections }, null, 2);
+            }
         }
         if (options.output) {
-          fs4.writeFileSync(options.output, output);
-          io.out.write(chalk15.green(`\u2713 Exported to ${options.output}
+          fs5.writeFileSync(options.output, output);
+          io.out.write(chalk16.green(`\u2713 Exported to ${options.output}
 `));
         } else {
           io.out.write(output);
           io.out.write("\n");
         }
       } catch (error) {
-        io.err.write(chalk15.red("Error exporting variables.\n"));
+        io.err.write(chalk16.red("Error exporting variables.\n"));
         if (error instanceof Error) {
-          io.err.write(chalk15.dim(`${error.message}
+          io.err.write(chalk16.dim(`${error.message}
 `));
         }
         io.err.write(
-          chalk15.dim("\nNote: Variables API requires Figma Enterprise plan.\n")
+          chalk16.dim("\nNote: Variables API requires Figma Enterprise plan.\n")
         );
         process.exit(1);
       }
@@ -1972,9 +2832,6 @@ function createVariableExportCommand(factory) {
   );
   return cmd;
 }
-function toKebabCase(str) {
-  return str.replace(/\s+/g, "-").replace(/([a-z])([A-Z])/g, "$1-$2").replace(/[^a-zA-Z0-9-]/g, "-").replace(/-+/g, "-").toLowerCase();
-}
 function resolveValue(value, variables, _modeId) {
   if (typeof value === "object" && value !== null) {
     if ("r" in value && "g" in value && "b" in value) {
@@ -2001,47 +2858,90 @@ function resolveValue(value, variables, _modeId) {
   }
   return String(value);
 }
-function exportToCss(variables, collections, modeId) {
+function exportToCss(variables, collections, modeId, categorize) {
   const lines = [":root {"];
-  for (const variable of Object.values(variables)) {
-    const collection = collections[variable.variableCollectionId];
-    const targetMode = modeId || collection?.defaultModeId;
-    const value = variable.valuesByMode[targetMode];
-    if (value !== void 0) {
-      const cssName = toKebabCase(variable.name);
-      const cssValue = resolveValue(value, variables, targetMode);
-      lines.push(`  --${cssName}: ${cssValue};`);
+  if (categorize) {
+    const categorized = categorizeVariables(variables);
+    for (const [category, categoryVars] of Object.entries(categorized)) {
+      if (categoryVars.length === 0) continue;
+      lines.push(
+        `  /* ${category.charAt(0).toUpperCase() + category.slice(1)} */`
+      );
+      for (const variable of categoryVars) {
+        const collection = collections[variable.variableCollectionId];
+        const targetMode = modeId || collection?.defaultModeId;
+        const value = variable.valuesByMode[targetMode];
+        if (value !== void 0) {
+          const cssName = toKebabCase(variable.name);
+          const cssValue = resolveValue(value, variables, targetMode);
+          lines.push(`  --${cssName}: ${cssValue};`);
+        }
+      }
+      lines.push("");
+    }
+  } else {
+    for (const variable of Object.values(variables)) {
+      const collection = collections[variable.variableCollectionId];
+      const targetMode = modeId || collection?.defaultModeId;
+      const value = variable.valuesByMode[targetMode];
+      if (value !== void 0) {
+        const cssName = toKebabCase(variable.name);
+        const cssValue = resolveValue(value, variables, targetMode);
+        lines.push(`  --${cssName}: ${cssValue};`);
+      }
     }
   }
   lines.push("}");
   return lines.join("\n");
 }
-function exportToScss(variables, collections, modeId) {
+function exportToScss(variables, collections, modeId, categorize) {
   const lines = [];
-  for (const variable of Object.values(variables)) {
-    const collection = collections[variable.variableCollectionId];
-    const targetMode = modeId || collection?.defaultModeId;
-    const value = variable.valuesByMode[targetMode];
-    if (value !== void 0) {
-      const scssName = toKebabCase(variable.name);
-      const scssValue = resolveValue(value, variables, targetMode).replace(
-        /var\(--([^)]+)\)/g,
-        "$$$1"
-      );
-      lines.push(`$${scssName}: ${scssValue};`);
+  if (categorize) {
+    const categorized = categorizeVariables(variables);
+    for (const [category, categoryVars] of Object.entries(categorized)) {
+      if (categoryVars.length === 0) continue;
+      lines.push(`// ${category.charAt(0).toUpperCase() + category.slice(1)}`);
+      for (const variable of categoryVars) {
+        const collection = collections[variable.variableCollectionId];
+        const targetMode = modeId || collection?.defaultModeId;
+        const value = variable.valuesByMode[targetMode];
+        if (value !== void 0) {
+          const scssName = toKebabCase(variable.name);
+          const scssValue = resolveValue(value, variables, targetMode).replace(
+            /var\(--([^)]+)\)/g,
+            "$$$1"
+          );
+          lines.push(`$${scssName}: ${scssValue};`);
+        }
+      }
+      lines.push("");
+    }
+  } else {
+    for (const variable of Object.values(variables)) {
+      const collection = collections[variable.variableCollectionId];
+      const targetMode = modeId || collection?.defaultModeId;
+      const value = variable.valuesByMode[targetMode];
+      if (value !== void 0) {
+        const scssName = toKebabCase(variable.name);
+        const scssValue = resolveValue(value, variables, targetMode).replace(
+          /var\(--([^)]+)\)/g,
+          "$$$1"
+        );
+        lines.push(`$${scssName}: ${scssValue};`);
+      }
     }
   }
   return lines.join("\n");
 }
-function exportToStyleDictionary(variables, collections, modeId) {
+function exportToStyleDictionary(variables, collections, modeId, categorize) {
   const tokens = {};
-  for (const variable of Object.values(variables)) {
+  const processVariable = (variable, targetTokens) => {
     const collection = collections[variable.variableCollectionId];
     const targetMode = modeId || collection?.defaultModeId;
     const value = variable.valuesByMode[targetMode];
-    if (value === void 0) continue;
+    if (value === void 0) return;
     const pathParts = variable.name.split("/").map((p) => p.trim());
-    let current = tokens;
+    let current = targetTokens;
     for (let i = 0; i < pathParts.length - 1; i++) {
       const part = pathParts[i];
       if (!current[part]) {
@@ -2055,6 +2955,20 @@ function exportToStyleDictionary(variables, collections, modeId) {
       type: mapTypeToStyleDictionary(variable.resolvedType),
       description: variable.description || void 0
     };
+  };
+  if (categorize) {
+    const categorized = categorizeVariables(variables);
+    for (const [category, categoryVars] of Object.entries(categorized)) {
+      if (categoryVars.length === 0) continue;
+      tokens[category] = {};
+      for (const variable of categoryVars) {
+        processVariable(variable, tokens[category]);
+      }
+    }
+  } else {
+    for (const variable of Object.values(variables)) {
+      processVariable(variable, tokens);
+    }
   }
   return JSON.stringify(tokens, null, 2);
 }
@@ -2096,266 +3010,89 @@ function mapTypeToStyleDictionary(figmaType) {
       return figmaType.toLowerCase();
   }
 }
-
-// src/cmd/variable/index.ts
-function createVariableCommand(factory) {
-  const cmd = new Command20("variable").description(
-    "Work with Figma variables (Enterprise)"
-  );
-  cmd.addCommand(createVariableListCommand(factory));
-  cmd.addCommand(createVariableExportCommand(factory));
-  return cmd;
-}
-
-// src/cmd/export/index.ts
-import { Command as Command24 } from "commander";
-
-// src/cmd/export/tokens.ts
-import { Command as Command21 } from "commander";
-import chalk16 from "chalk";
-import * as fs5 from "fs";
-
-// src/internal/transform/tokens.ts
-function figmaColorToCss(color) {
-  const r = Math.round(color.r * 255);
-  const g = Math.round(color.g * 255);
-  const b = Math.round(color.b * 255);
-  const a = color.a ?? 1;
-  if (a === 1) {
-    return `#${r.toString(16).padStart(2, "0")}${g.toString(16).padStart(2, "0")}${b.toString(16).padStart(2, "0")}`;
-  }
-  return `rgba(${r}, ${g}, ${b}, ${a.toFixed(2)})`;
-}
-function toKebabCase2(str) {
-  return str.replace(/\s+/g, "-").replace(/([a-z])([A-Z])/g, "$1-$2").replace(/[^a-zA-Z0-9-]/g, "-").replace(/-+/g, "-").toLowerCase();
-}
-function extractStylesFromFile(file, styleMetadata) {
-  const tokens = {
-    colors: {},
-    typography: {},
-    spacing: {},
-    effects: {}
-  };
-  const styleNodeMap = /* @__PURE__ */ new Map();
-  for (const style of styleMetadata) {
-    const nodeId = style.node_id;
-    if (nodeId) {
-      styleNodeMap.set(nodeId, style);
-    }
-  }
-  function traverseNode(node) {
-    const nodeWithStyles = node;
-    if ("styles" in nodeWithStyles && nodeWithStyles.styles) {
-      const styles = nodeWithStyles.styles;
-      if (styles.fill && "fills" in nodeWithStyles) {
-        const fills = nodeWithStyles.fills;
-        if (fills && fills.length > 0 && fills[0].type === "SOLID") {
-          const fill = fills[0];
-          if (fill.color) {
-            const styleInfo = styleNodeMap.get(node.id);
-            const styleName = styleInfo?.name || node.name;
-            const tokenName = toKebabCase2(styleName);
-            tokens.colors[tokenName] = {
-              name: styleName,
-              type: "color",
-              value: figmaColorToCss(fill.color),
-              description: styleInfo?.description
-            };
-          }
-        }
-      }
-      if (styles.text && "style" in nodeWithStyles && nodeWithStyles.style) {
-        const textStyle = nodeWithStyles.style;
-        const styleInfo = styleNodeMap.get(node.id);
-        const styleName = styleInfo?.name || node.name;
-        const tokenName = toKebabCase2(styleName);
-        tokens.typography[tokenName] = {
-          name: styleName,
-          type: "typography",
-          value: {
-            fontFamily: textStyle.fontFamily || "sans-serif",
-            fontSize: `${textStyle.fontSize || 16}px`,
-            fontWeight: textStyle.fontWeight || 400,
-            lineHeight: textStyle.lineHeightPx !== void 0 ? `${textStyle.lineHeightPx}px` : "normal",
-            letterSpacing: textStyle.letterSpacing !== void 0 ? `${textStyle.letterSpacing}px` : "normal"
-          },
-          description: styleInfo?.description
-        };
-      }
-    }
-    if ("children" in node) {
-      const parent = node;
-      for (const child of parent.children || []) {
-        traverseNode(child);
-      }
-    }
-  }
-  if (file.document) {
-    traverseNode(file.document);
-  }
-  return tokens;
-}
-function tokensToCss(tokens) {
-  const lines = [":root {"];
-  if (tokens.colors) {
-    lines.push("  /* Colors */");
-    for (const [name, token] of Object.entries(tokens.colors)) {
-      lines.push(`  --color-${name}: ${token.value};`);
-    }
-    lines.push("");
-  }
-  if (tokens.typography) {
-    lines.push("  /* Typography */");
-    for (const [name, token] of Object.entries(tokens.typography)) {
-      const value = token.value;
-      lines.push(`  --font-${name}-family: ${value.fontFamily};`);
-      lines.push(`  --font-${name}-size: ${value.fontSize};`);
-      lines.push(`  --font-${name}-weight: ${value.fontWeight};`);
-      lines.push(`  --font-${name}-line-height: ${value.lineHeight};`);
-      lines.push(`  --font-${name}-letter-spacing: ${value.letterSpacing};`);
-    }
-    lines.push("");
-  }
-  if (tokens.spacing) {
-    lines.push("  /* Spacing */");
-    for (const [name, token] of Object.entries(tokens.spacing)) {
-      lines.push(`  --spacing-${name}: ${token.value};`);
-    }
-  }
-  lines.push("}");
-  return lines.join("\n");
-}
-function tokensToScss(tokens) {
-  const lines = [];
-  if (tokens.colors) {
-    lines.push("// Colors");
-    for (const [name, token] of Object.entries(tokens.colors)) {
-      lines.push(`$color-${name}: ${token.value};`);
-    }
-    lines.push("");
-  }
-  if (tokens.typography) {
-    lines.push("// Typography");
-    for (const [name, token] of Object.entries(tokens.typography)) {
-      const value = token.value;
-      lines.push(`$font-${name}-family: ${value.fontFamily};`);
-      lines.push(`$font-${name}-size: ${value.fontSize};`);
-      lines.push(`$font-${name}-weight: ${value.fontWeight};`);
-      lines.push(`$font-${name}-line-height: ${value.lineHeight};`);
-      lines.push(`$font-${name}-letter-spacing: ${value.letterSpacing};`);
-    }
-    lines.push("");
-  }
-  if (tokens.spacing) {
-    lines.push("// Spacing");
-    for (const [name, token] of Object.entries(tokens.spacing)) {
-      lines.push(`$spacing-${name}: ${token.value};`);
-    }
-  }
-  return lines.join("\n");
-}
-function tokensToStyleDictionary(tokens) {
-  const output = {};
-  if (tokens.colors && Object.keys(tokens.colors).length > 0) {
-    output.color = {};
-    for (const [name, token] of Object.entries(tokens.colors)) {
-      output.color[name] = {
-        value: token.value,
-        type: "color",
-        description: token.description
-      };
-    }
-  }
-  if (tokens.typography && Object.keys(tokens.typography).length > 0) {
-    output.typography = {};
-    for (const [name, token] of Object.entries(tokens.typography)) {
-      output.typography[name] = {
-        value: token.value,
-        type: "typography",
-        description: token.description
-      };
-    }
-  }
-  if (tokens.spacing && Object.keys(tokens.spacing).length > 0) {
-    output.spacing = {};
-    for (const [name, token] of Object.entries(tokens.spacing)) {
-      output.spacing[name] = {
-        value: token.value,
-        type: "dimension",
-        description: token.description
-      };
-    }
-  }
-  return JSON.stringify(output, null, 2);
-}
-function tokensToTailwind(tokens) {
-  const config = {
-    theme: {
-      extend: {}
-    }
-  };
-  if (tokens.colors && Object.keys(tokens.colors).length > 0) {
-    config.theme.extend.colors = {};
-    for (const [name, token] of Object.entries(tokens.colors)) {
-      config.theme.extend.colors[name] = token.value;
-    }
-  }
-  if (tokens.typography && Object.keys(tokens.typography).length > 0) {
-    config.theme.extend.fontFamily = {};
-    config.theme.extend.fontSize = {};
-    for (const [name, token] of Object.entries(tokens.typography)) {
-      const value = token.value;
-      config.theme.extend.fontFamily[name] = [value.fontFamily];
-      config.theme.extend.fontSize[name] = value.fontSize;
-    }
-  }
-  if (tokens.spacing && Object.keys(tokens.spacing).length > 0) {
-    config.theme.extend.spacing = {};
-    for (const [name, token] of Object.entries(tokens.spacing)) {
-      config.theme.extend.spacing[name] = token.value;
-    }
-  }
-  return `/** @type {import('tailwindcss').Config} */
-module.exports = ${JSON.stringify(config, null, 2)};`;
+
+// src/cmd/variable/index.ts
+function createVariableCommand(factory) {
+  const cmd = new Command21("variable").description(
+    "Work with Figma variables (Enterprise)"
+  );
+  cmd.addCommand(createVariableListCommand(factory));
+  cmd.addCommand(createVariableExportCommand(factory));
+  return cmd;
 }
 
+// src/cmd/export/index.ts
+import { Command as Command25 } from "commander";
+
 // src/cmd/export/tokens.ts
+import { Command as Command22 } from "commander";
+import chalk17 from "chalk";
+import * as fs6 from "fs";
 function createExportTokensCommand(factory) {
-  const cmd = new Command21("tokens").description("Export design tokens from a Figma file").argument("<file-key>", "File key").option(
+  const cmd = new Command22("tokens").description("Export design tokens from a Figma file").argument("<url>", "Figma URL or file key").option(
     "--format <format>",
     "Output format (json, css, scss, style-dictionary, tailwind)",
     "json"
   ).option("-o, --output <file>", "Output file path").option("-t, --token <token>", "Override authentication token").action(
-    async (fileKey, options) => {
+    async (url, options) => {
       const { io } = factory;
+      const validFormats = [
+        "json",
+        "css",
+        "scss",
+        "style-dictionary",
+        "tailwind"
+      ];
+      if (!validFormats.includes(
+        options.format
+      )) {
+        io.err.write(
+          chalk17.red(
+            `Invalid format "${options.format}". Valid formats: ${validFormats.join(", ")}
+`
+          )
+        );
+        process.exit(1);
+      }
       try {
-        const token = await factory.getToken(options.token);
+        const parsed = parseFigmaInput(url);
+        const fileKey = parsed.fileKey;
         let client = await factory.getClient();
         if (options.token) {
           const { FigmaClient: FigmaClient2 } = await Promise.resolve().then(() => (init_client(), client_exports));
-          client = new FigmaClient2({ token });
+          client = new FigmaClient2({ token: options.token });
         }
-        io.err.write(chalk16.dim("Fetching file styles...\n"));
+        io.err.write(chalk17.dim("Fetching file styles...\n"));
         const stylesResponse = await client.getFileStyles(fileKey);
         const styles = stylesResponse.meta?.styles || [];
         if (styles.length === 0) {
           io.err.write(
-            chalk16.yellow("No styles found in file. Trying variables...\n")
+            chalk17.yellow("No styles found in file. Trying variables...\n")
           );
           try {
             const variablesResponse = await client.getLocalVariables(fileKey);
             if (variablesResponse.meta?.variables) {
               io.err.write(
-                chalk16.dim(
+                chalk17.dim(
                   "Found variables. Use 'figma variable export' for variable-based tokens.\n"
                 )
               );
             }
-          } catch {
+          } catch (error) {
+            const message = error instanceof Error ? error.message.toLowerCase() : "";
+            const isPermissionError = message.includes("403") || message.includes("enterprise") || message.includes("permission") || message.includes("forbidden");
+            if (!isPermissionError) {
+              io.err.write(
+                chalk17.dim(
+                  `Note: Could not check for variables: ${error instanceof Error ? error.message : String(error)}
+`
+                )
+              );
+            }
           }
           process.exit(0);
         }
-        io.err.write(chalk16.dim("Extracting token values...\n"));
+        io.err.write(chalk17.dim("Extracting token values...\n"));
         const file = await client.getFile(fileKey);
         const tokens = extractStylesFromFile(file, styles);
         let output;
@@ -2376,17 +3113,17 @@ function createExportTokensCommand(factory) {
             output = JSON.stringify(tokens, null, 2);
         }
         if (options.output) {
-          fs5.writeFileSync(options.output, output);
-          io.out.write(chalk16.green(`\u2713 Exported to ${options.output}
+          fs6.writeFileSync(options.output, output);
+          io.out.write(chalk17.green(`\u2713 Exported to ${options.output}
 `));
         } else {
           io.out.write(output);
           io.out.write("\n");
         }
       } catch (error) {
-        io.err.write(chalk16.red("Error exporting tokens.\n"));
+        io.err.write(chalk17.red("Error exporting tokens.\n"));
         if (error instanceof Error) {
-          io.err.write(chalk16.dim(`${error.message}
+          io.err.write(chalk17.dim(`${error.message}
 `));
         }
         process.exit(1);
@@ -2397,19 +3134,67 @@ function createExportTokensCommand(factory) {
 }
 
 // src/cmd/export/icons.ts
-import { Command as Command22 } from "commander";
-import chalk17 from "chalk";
+import { Command as Command23 } from "commander";
+import chalk18 from "chalk";
+import * as path5 from "path";
+import * as fs7 from "fs";
+function parseVariantName(name) {
+  const parts = name.split("/");
+  const variants = [];
+  let baseName = "";
+  for (const part of parts) {
+    if (part.includes("=")) {
+      const [, value] = part.split("=");
+      if (value) {
+        variants.push(value.trim());
+      }
+    } else {
+      baseName = baseName ? `${baseName}-${part}` : part;
+    }
+  }
+  return { baseName: baseName || name, variants };
+}
+function generateVariantFilename(name, variantFormat, prefix, imageFormat) {
+  const { baseName, variants } = parseVariantName(name);
+  const kebabBase = toKebabCase(baseName);
+  switch (variantFormat) {
+    case "suffix":
+      if (variants.length > 0) {
+        const variantSuffix = variants.map((v) => toKebabCase(v)).join("-");
+        return {
+          filename: `${prefix}${kebabBase}--${variantSuffix}.${imageFormat}`
+        };
+      }
+      return { filename: `${prefix}${kebabBase}.${imageFormat}` };
+    case "folder":
+      if (variants.length > 0) {
+        const variantSuffix = variants.map((v) => toKebabCase(v)).join("-");
+        return {
+          filename: `${variantSuffix}.${imageFormat}`,
+          subdir: `${prefix}${kebabBase}`
+        };
+      }
+      return { filename: `${prefix}${kebabBase}.${imageFormat}` };
+    case "flat":
+    default:
+      return { filename: `${prefix}${toKebabCase(name)}.${imageFormat}` };
+  }
+}
 function createExportIconsCommand(factory) {
-  const cmd = new Command22("icons").description("Export icons from a Figma file").argument("<file-key>", "File key").option(
+  const cmd = new Command23("icons").description("Export icons from a Figma file").argument("<url>", "Figma URL or file key").option(
     "--frame <name>",
     "Name of frame/page containing icons (searches all pages if not specified)"
-  ).option("--format <format>", "Export format (svg, png)", "svg").option("-s, --scale <scale>", "Scale factor for PNG export", parseFloat, 1).option("-o, --output <dir>", "Output directory", "./icons").option("--prefix <prefix>", "Prefix for icon filenames", "icon-").option("-t, --token <token>", "Override authentication token").action(
-    async (fileKey, options) => {
+  ).option("--format <format>", "Export format (svg, png)", "svg").option("-s, --scale <scale>", "Scale factor for PNG export", parseFloat, 1).option("-o, --output <dir>", "Output directory", "./icons").option("--prefix <prefix>", "Prefix for icon filenames", "icon-").option(
+    "--variant-format <format>",
+    "How to handle variants: flat, suffix, or folder (default: flat)",
+    "flat"
+  ).option("-t, --token <token>", "Override authentication token").action(
+    async (url, options) => {
       const { io } = factory;
       const validFormats = ["svg", "png"];
       if (!validFormats.includes(options.format)) {
         io.err.write(
-          chalk17.red(
+          chalk18.red(
             `Invalid format "${options.format}". Valid formats: ${validFormats.join(", ")}
 `
           )
@@ -2445,30 +3230,32 @@ function createExportIconsCommand(factory) {
           );
         };
         var findIcons = findIcons2, hasDeepChildren = hasDeepChildren2;
+        const parsed = parseFigmaInput(url);
+        const fileKey = parsed.fileKey;
         const token = await factory.getToken(options.token);
         let client = await factory.getClient();
         if (options.token) {
           const { FigmaClient: FigmaClient2 } = await Promise.resolve().then(() => (init_client(), client_exports));
           client = new FigmaClient2({ token });
         }
-        io.err.write(chalk17.dim("Fetching file structure...\n"));
+        io.err.write(chalk18.dim("Fetching file structure...\n"));
         const file = await client.getFile(fileKey, { depth: 2 });
         const iconNodes = [];
         if (file.document) {
           findIcons2(file.document, false);
         }
         if (iconNodes.length === 0) {
-          io.err.write(chalk17.yellow("No icons found in file.\n"));
+          io.err.write(chalk18.yellow("No icons found in file.\n"));
           if (options.frame) {
             io.err.write(
-              chalk17.dim(`Looking for frame: "${options.frame}"
+              chalk18.dim(`Looking for frame: "${options.frame}"
 `)
             );
           }
           process.exit(0);
         }
         io.err.write(
-          chalk17.dim(`Found ${iconNodes.length} icons. Exporting...
+          chalk18.dim(`Found ${iconNodes.length} icons. Exporting...
 `)
         );
         const nodeIds = iconNodes.map((n) => n.id);
@@ -2479,12 +3266,51 @@ function createExportIconsCommand(factory) {
           svg_simplify_stroke: true
         });
         const imageUrls = imagesResponse.images || {};
-        const downloadItems = iconNodes.map((node) => ({
-          id: node.id,
-          name: node.name,
-          url: imageUrls[node.id] ?? null,
-          filename: `${options.prefix}${toKebabCase2(node.name)}.${imageFormat}`
-        }));
+        const validVariantFormats = ["flat", "suffix", "folder"];
+        if (!validVariantFormats.includes(
+          options.variantFormat
+        )) {
+          io.err.write(
+            chalk18.red(
+              `Invalid variant format "${options.variantFormat}". Valid formats: ${validVariantFormats.join(", ")}
+`
+            )
+          );
+          process.exit(1);
+        }
+        const variantFormat = options.variantFormat;
+        const subdirs = /* @__PURE__ */ new Set();
+        for (const node of iconNodes) {
+          const { subdir } = generateVariantFilename(
+            node.name,
+            variantFormat,
+            options.prefix,
+            imageFormat
+          );
+          if (subdir) {
+            subdirs.add(subdir);
+          }
+        }
+        fs7.mkdirSync(options.output, { recursive: true });
+        for (const subdir of subdirs) {
+          fs7.mkdirSync(path5.join(options.output, subdir), {
+            recursive: true
+          });
+        }
+        const downloadItems = iconNodes.map((node) => {
+          const { filename, subdir } = generateVariantFilename(
+            node.name,
+            variantFormat,
+            options.prefix,
+            imageFormat
+          );
+          return {
+            id: node.id,
+            name: node.name,
+            url: imageUrls[node.id] ?? null,
+            filename: subdir ? path5.join(subdir, filename) : filename
+          };
+        });
         const results = await downloadFiles(downloadItems, options.output);
         const successCount = results.filter(
           (r) => r.status === "success"
@@ -2492,25 +3318,25 @@ function createExportIconsCommand(factory) {
         const failures = results.filter((r) => r.status === "error");
         for (const failure of failures) {
           io.err.write(
-            chalk17.yellow(
+            chalk18.yellow(
               `Warning: Failed to download "${failure.name ?? failure.id}": ${failure.error}
 `
             )
           );
         }
         io.err.write(
-          chalk17.green(`Exported ${successCount} icons to ${options.output}
+          chalk18.green(`Exported ${successCount} icons to ${options.output}
 `)
         );
         if (failures.length > 0) {
-          io.err.write(chalk17.yellow(`${failures.length} icons failed
+          io.err.write(chalk18.yellow(`${failures.length} icons failed
 `));
           process.exit(1);
         }
       } catch (error) {
-        io.err.write(chalk17.red("Error exporting icons.\n"));
+        io.err.write(chalk18.red("Error exporting icons.\n"));
         if (error instanceof Error) {
-          io.err.write(chalk17.dim(`${error.message}
+          io.err.write(chalk18.dim(`${error.message}
 `));
         }
         process.exit(1);
@@ -2521,33 +3347,35 @@ function createExportIconsCommand(factory) {
 }
 
 // src/cmd/export/theme.ts
-import { Command as Command23 } from "commander";
-import chalk18 from "chalk";
-import * as fs6 from "fs";
-import * as path4 from "path";
+import { Command as Command24 } from "commander";
+import chalk19 from "chalk";
+import * as fs8 from "fs";
+import * as path6 from "path";
 function createExportThemeCommand(factory) {
-  const cmd = new Command23("theme").description("Export complete theme package from a Figma file").argument("<file-key>", "File key").option("-o, --output <dir>", "Output directory", "./theme").option(
+  const cmd = new Command24("theme").description("Export complete theme package from a Figma file").argument("<url>", "Figma URL or file key").option("-o, --output <dir>", "Output directory", "./theme").option(
     "--formats <formats>",
     "Comma-separated list of formats (json, css, scss, style-dictionary, tailwind)",
     "json,css"
   ).option("-t, --token <token>", "Override authentication token").action(
-    async (fileKey, options) => {
+    async (url, options) => {
       const { io } = factory;
       try {
+        const parsed = parseFigmaInput(url);
+        const fileKey = parsed.fileKey;
         const token = await factory.getToken(options.token);
         let client = await factory.getClient();
         if (options.token) {
           const { FigmaClient: FigmaClient2 } = await Promise.resolve().then(() => (init_client(), client_exports));
           client = new FigmaClient2({ token });
         }
-        io.err.write(chalk18.dim("Fetching file styles...\n"));
+        io.err.write(chalk19.dim("Fetching file styles...\n"));
         const stylesResponse = await client.getFileStyles(fileKey);
         const styles = stylesResponse.meta?.styles || [];
-        io.err.write(chalk18.dim("Extracting token values...\n"));
+        io.err.write(chalk19.dim("Extracting token values...\n"));
         const file = await client.getFile(fileKey);
         const tokens = extractStylesFromFile(file, styles);
-        if (!fs6.existsSync(options.output)) {
-          fs6.mkdirSync(options.output, { recursive: true });
+        if (!fs8.existsSync(options.output)) {
+          fs8.mkdirSync(options.output, { recursive: true });
         }
         const formats = options.formats.split(",").map((f) => f.trim());
         const outputs = [];
@@ -2576,8 +3404,8 @@ function createExportThemeCommand(factory) {
               output = JSON.stringify(tokens, null, 2);
               filename = "tokens.json";
           }
-          const filepath = path4.join(options.output, filename);
-          fs6.writeFileSync(filepath, output);
+          const filepath = path6.join(options.output, filename);
+          fs8.writeFileSync(filepath, output);
           outputs.push(filename);
         }
         const metadata = {
@@ -2587,22 +3415,22 @@ function createExportThemeCommand(factory) {
           exportedAt: (/* @__PURE__ */ new Date()).toISOString(),
           formats
         };
-        fs6.writeFileSync(
-          path4.join(options.output, "metadata.json"),
+        fs8.writeFileSync(
+          path6.join(options.output, "metadata.json"),
           JSON.stringify(metadata, null, 2)
         );
-        io.out.write(chalk18.green(`\u2713 Theme exported to ${options.output}
+        io.out.write(chalk19.green(`\u2713 Theme exported to ${options.output}
 `));
-        io.out.write(chalk18.dim("  Files:\n"));
+        io.out.write(chalk19.dim("  Files:\n"));
         for (const filename of outputs) {
-          io.out.write(chalk18.dim(`    - ${filename}
+          io.out.write(chalk19.dim(`    - ${filename}
 `));
         }
-        io.out.write(chalk18.dim("    - metadata.json\n"));
+        io.out.write(chalk19.dim("    - metadata.json\n"));
       } catch (error) {
-        io.err.write(chalk18.red("Error exporting theme.\n"));
+        io.err.write(chalk19.red("Error exporting theme.\n"));
         if (error instanceof Error) {
-          io.err.write(chalk18.dim(`${error.message}
+          io.err.write(chalk19.dim(`${error.message}
 `));
         }
         process.exit(1);
@@ -2614,7 +3442,7 @@ function createExportThemeCommand(factory) {
 
 // src/cmd/export/index.ts
 function createExportCommand(factory) {
-  const cmd = new Command24("export").description(
+  const cmd = new Command25("export").description(
     "Design-to-code export commands"
   );
   cmd.addCommand(createExportTokensCommand(factory));
@@ -2625,10 +3453,10 @@ function createExportCommand(factory) {
 
 // src/cmd/api/index.ts
 init_client();
-import { Command as Command25 } from "commander";
-import chalk19 from "chalk";
+import { Command as Command26 } from "commander";
+import chalk20 from "chalk";
 function createApiCommand(factory) {
-  const cmd = new Command25("api").description("Make direct API requests to Figma").argument("<path>", "API path (e.g., /v1/files/:key)").option("-X, --method <method>", "HTTP method", "GET").option("-d, --data <json>", "Request body as JSON").option("-q, --query <params>", "Query parameters (key=value,key2=value2)").option("-t, --token <token>", "Override authentication token").option("--raw", "Output raw response without formatting").action(
+  const cmd = new Command26("api").description("Make direct API requests to Figma").argument("<path>", "API path (e.g., /v1/files/:key)").option("-X, --method <method>", "HTTP method", "GET").option("-d, --data <json>", "Request body as JSON").option("-q, --query <params>", "Query parameters (key=value,key2=value2)").option("-t, --token <token>", "Override authentication token").option("--raw", "Output raw response without formatting").action(
     async (apiPath, options) => {
       const { io } = factory;
       try {
@@ -2653,7 +3481,7 @@ function createApiCommand(factory) {
           try {
             body = JSON.parse(options.data);
           } catch {
-            io.err.write(chalk19.red("Error: Invalid JSON in --data\n"));
+            io.err.write(chalk20.red("Error: Invalid JSON in --data\n"));
             process.exit(1);
           }
         }
@@ -2670,15 +3498,15 @@ function createApiCommand(factory) {
       } catch (error) {
         if (error instanceof FigmaApiError) {
           io.err.write(
-            chalk19.red(`API Error: ${error.status} ${error.statusText}
+            chalk20.red(`API Error: ${error.status} ${error.statusText}
 `)
           );
           if (error.body) {
-            io.err.write(chalk19.dim(JSON.stringify(error.body, null, 2)));
+            io.err.write(chalk20.dim(JSON.stringify(error.body, null, 2)));
             io.err.write("\n");
           }
         } else if (error instanceof Error) {
-          io.err.write(chalk19.red(`Error: ${error.message}
+          io.err.write(chalk20.red(`Error: ${error.message}
 `));
         }
         process.exit(1);
@@ -2699,15 +3527,515 @@ Examples:
   return cmd;
 }
 
+// src/cmd/frame/index.ts
+import { Command as Command28 } from "commander";
+
+// src/cmd/frame/list.ts
+import { Command as Command27 } from "commander";
+import chalk21 from "chalk";
+var FRAME_TYPES = [
+  "FRAME",
+  "COMPONENT",
+  "COMPONENT_SET",
+  "SECTION",
+  "GROUP",
+  "INSTANCE"
+];
+function extractFrames(file, options) {
+  const frames = [];
+  const allowedTypes = options.types || FRAME_TYPES;
+  if (!file.document || !("children" in file.document)) {
+    return frames;
+  }
+  const doc = file.document;
+  for (const pageNode of doc.children || []) {
+    let traverseNode2 = function(node, isTopLevel) {
+      const nodeWithBounds = node;
+      if (allowedTypes.includes(node.type)) {
+        if (!options.topLevel || isTopLevel) {
+          const frame = {
+            id: node.id,
+            name: node.name,
+            type: node.type,
+            page: pageNode.name,
+            pageId: pageNode.id
+          };
+          if (nodeWithBounds.absoluteBoundingBox) {
+            frame.width = Math.round(nodeWithBounds.absoluteBoundingBox.width);
+            frame.height = Math.round(
+              nodeWithBounds.absoluteBoundingBox.height
+            );
+          }
+          frames.push(frame);
+        }
+      }
+      if (!options.topLevel && "children" in node) {
+        const parent = node;
+        for (const child of parent.children || []) {
+          traverseNode2(child, false);
+        }
+      }
+    };
+    var traverseNode = traverseNode2;
+    if (pageNode.type !== "CANVAS") continue;
+    if (options.page && pageNode.name !== options.page) continue;
+    if (!("children" in pageNode)) continue;
+    const page = pageNode;
+    for (const child of page.children || []) {
+      traverseNode2(child, true);
+    }
+  }
+  return frames;
+}
+function formatTable2(frames) {
+  if (frames.length === 0) {
+    return "No frames found.";
+  }
+  const headers = ["ID", "Name", "Type", "Page", "Size"];
+  const rows = frames.map((f) => [
+    f.id,
+    f.name,
+    f.type,
+    f.page,
+    f.width && f.height ? `${f.width}\xD7${f.height}` : "-"
+  ]);
+  const widths = headers.map(
+    (h, i) => Math.max(h.length, ...rows.map((r) => r[i].length))
+  );
+  const separator = widths.map((w) => "-".repeat(w)).join("-+-");
+  const headerLine = headers.map((h, i) => h.padEnd(widths[i])).join(" | ");
+  const rowLines = rows.map(
+    (r) => r.map((cell, i) => cell.padEnd(widths[i])).join(" | ")
+  );
+  return [headerLine, separator, ...rowLines].join("\n");
+}
+function createFrameListCommand(factory) {
+  const cmd = new Command27("list").description("List frames in a file").requiredOption("--file <url>", "Figma URL or file key").option("--page <name>", "Filter to specific page").option(
+    "--type <types>",
+    "Comma-separated types: frame,component,component_set,section,group,instance"
+  ).option("--top-level", "Only top-level frames", false).option("-f, --format <format>", "Output format (json, table)", "json").option("-t, --token <token>", "Override authentication token").action(
+    async (options) => {
+      const { io } = factory;
+      const validFormats = ["json", "table"];
+      if (!validFormats.includes(
+        options.format
+      )) {
+        io.err.write(
+          chalk21.red(
+            `Invalid format "${options.format}". Valid formats: ${validFormats.join(", ")}
+`
+          )
+        );
+        process.exit(1);
+      }
+      try {
+        const parsed = parseFigmaInput(options.file);
+        const fileKey = parsed.fileKey;
+        let types;
+        if (options.type) {
+          const typeMap = {
+            frame: "FRAME",
+            component: "COMPONENT",
+            component_set: "COMPONENT_SET",
+            section: "SECTION",
+            group: "GROUP",
+            instance: "INSTANCE"
+          };
+          types = options.type.split(",").map((t) => {
+            const mapped = typeMap[t.trim().toLowerCase()];
+            if (!mapped) {
+              throw new Error(
+                `Invalid type "${t}". Valid types: ${Object.keys(typeMap).join(", ")}`
+              );
+            }
+            return mapped;
+          });
+        }
+        const client = await factory.getClient();
+        let activeClient = client;
+        if (options.token) {
+          const { FigmaClient: FigmaClient2 } = await Promise.resolve().then(() => (init_client(), client_exports));
+          activeClient = new FigmaClient2({ token: options.token });
+        }
+        const file = await activeClient.getFile(fileKey, {
+          depth: options.topLevel ? 2 : void 0
+        });
+        const frames = extractFrames(file, {
+          page: options.page,
+          types,
+          topLevel: options.topLevel
+        });
+        if (options.format === "table") {
+          io.out.write(formatTable2(frames) + "\n");
+        } else {
+          io.out.write(
+            formatOutput(frames, { format: options.format })
+          );
+          io.out.write("\n");
+        }
+      } catch (error) {
+        io.err.write(chalk21.red("Error listing frames.\n"));
+        if (error instanceof Error) {
+          io.err.write(chalk21.dim(`${error.message}
+`));
+        }
+        process.exit(1);
+      }
+    }
+  );
+  return cmd;
+}
+
+// src/cmd/frame/index.ts
+function createFrameCommand(factory) {
+  const cmd = new Command28("frame").description("Work with Figma frames");
+  cmd.addCommand(createFrameListCommand(factory));
+  return cmd;
+}
+
+// src/cmd/handoff/index.ts
+import { Command as Command29 } from "commander";
+import chalk22 from "chalk";
+import * as fs9 from "fs";
+import * as path7 from "path";
+function countTokens(tokens) {
+  return {
+    colors: Object.keys(tokens.colors || {}).length,
+    typography: Object.keys(tokens.typography || {}).length,
+    shadows: Object.keys(tokens.shadows || {}).length,
+    radii: Object.keys(tokens.radii || {}).length,
+    spacing: Object.keys(tokens.spacing || {}).length
+  };
+}
+function extractComponents(file) {
+  const components = [];
+  function traverseNode(node) {
+    if (node.type === "COMPONENT" || node.type === "COMPONENT_SET") {
+      components.push({
+        id: node.id,
+        name: node.name,
+        type: node.type
+      });
+    }
+    if ("children" in node) {
+      const parent = node;
+      for (const child of parent.children || []) {
+        traverseNode(child);
+      }
+    }
+  }
+  if (file.document) {
+    traverseNode(file.document);
+  }
+  return components;
+}
+function countPagesAndFrames(file) {
+  let pages = 0;
+  let frames = 0;
+  if (file.document && "children" in file.document) {
+    const doc = file.document;
+    for (const pageNode of doc.children || []) {
+      if (pageNode.type === "CANVAS") {
+        pages++;
+        if ("children" in pageNode) {
+          const page = pageNode;
+          frames += (page.children || []).length;
+        }
+      }
+    }
+  }
+  return { pages, frames };
+}
+function generateHandoffReadme(summary, tokenFormats) {
+  const lines = [];
+  lines.push(`# Design Handoff: ${summary.name}`);
+  lines.push("");
+  lines.push(`Source: ${summary.url}`);
+  lines.push(`Generated: ${summary.generatedAt}`);
+  lines.push("");
+  lines.push("## Tokens Summary");
+  lines.push(`- Colors: ${summary.tokens.colors} tokens`);
+  lines.push(`- Typography: ${summary.tokens.typography} tokens`);
+  lines.push(`- Shadows: ${summary.tokens.shadows} tokens`);
+  lines.push(`- Radii: ${summary.tokens.radii} tokens`);
+  lines.push(`- Spacing: ${summary.tokens.spacing} tokens`);
+  lines.push("");
+  if (summary.components.length > 0) {
+    lines.push("## Component Inventory");
+    lines.push("| ID | Name | Type | Asset |");
+    lines.push("|----|------|------|-------|");
+    for (const comp of summary.components) {
+      lines.push(
+        `| ${comp.id} | ${comp.name} | ${comp.type} | ${comp.asset || "-"} |`
+      );
+    }
+    lines.push("");
+  }
+  lines.push("## File Structure");
+  lines.push(
+    `${summary.pages} pages, ${summary.frames} frames, ${summary.components.length} components`
+  );
+  lines.push("");
+  lines.push("## Implementation Notes");
+  if (tokenFormats.includes("css")) {
+    lines.push("- Import tokens: `@import './tokens/tokens.css'`");
+  }
+  if (tokenFormats.includes("scss")) {
+    lines.push("- SCSS import: `@import './tokens/tokens.scss'`");
+  }
+  if (summary.components.some((c) => c.asset)) {
+    lines.push("- Asset path: `./assets/{name}.svg`");
+  }
+  lines.push("");
+  return lines.join("\n");
+}
+function extractSimplifiedStructure(file) {
+  const structure = {
+    name: file.name,
+    lastModified: file.lastModified,
+    pages: []
+  };
+  if (file.document && "children" in file.document) {
+    const doc = file.document;
+    for (const pageNode of doc.children || []) {
+      if (pageNode.type !== "CANVAS") continue;
+      const page = {
+        id: pageNode.id,
+        name: pageNode.name,
+        frames: []
+      };
+      if ("children" in pageNode) {
+        const pageWithChildren = pageNode;
+        for (const child of pageWithChildren.children || []) {
+          const childWithBounds = child;
+          const frame = {
+            id: child.id,
+            name: child.name,
+            type: child.type
+          };
+          if (childWithBounds.absoluteBoundingBox) {
+            frame.width = Math.round(childWithBounds.absoluteBoundingBox.width);
+            frame.height = Math.round(
+              childWithBounds.absoluteBoundingBox.height
+            );
+          }
+          page.frames.push(frame);
+        }
+      }
+      structure.pages.push(page);
+    }
+  }
+  return structure;
+}
+function createHandoffCommand(factory) {
+  const cmd = new Command29("handoff").description("Export complete design handoff package").argument("<url>", "Figma URL or file key").option("-o, --output <dir>", "Output directory", "./figma-handoff").option(
+    "--tokens <formats>",
+    "Token formats to export (comma-separated: css,json,scss)",
+    "css,json"
+  ).option("--assets", "Export component assets", false).option("--asset-format <format>", "Asset format (svg, png)", "svg").option("--structure", "Include structure.json", false).option("--readme", "Generate HANDOFF.md", false).option("--all", "Export all (tokens, assets, structure, readme)", false).option("-t, --token <token>", "Override authentication token").action(
+    async (url, options) => {
+      const { io } = factory;
+      try {
+        const parsed = parseFigmaInput(url);
+        const fileKey = parsed.fileKey;
+        const exportAssets = options.all || options.assets;
+        const exportStructure = options.all || options.structure;
+        const exportReadme = options.all || options.readme;
+        const tokenFormats = options.tokens.split(",").map((f) => f.trim());
+        const validTokenFormats = ["css", "scss", "json"];
+        for (const format of tokenFormats) {
+          if (!validTokenFormats.includes(
+            format
+          )) {
+            io.err.write(
+              chalk22.red(
+                `Invalid token format "${format}". Valid formats: ${validTokenFormats.join(", ")}
+`
+              )
+            );
+            process.exit(1);
+          }
+        }
+        const validAssetFormats = ["svg", "png"];
+        if (!validAssetFormats.includes(
+          options.assetFormat
+        )) {
+          io.err.write(
+            chalk22.red(
+              `Invalid asset format "${options.assetFormat}". Valid formats: ${validAssetFormats.join(", ")}
+`
+            )
+          );
+          process.exit(1);
+        }
+        const assetFormat = options.assetFormat;
+        const outputDir = path7.resolve(options.output);
+        const cwd = process.cwd();
+        const homeDir = process.env.HOME || "";
+        if (!outputDir.startsWith(cwd) && !outputDir.startsWith(homeDir)) {
+          io.err.write(
+            chalk22.red(
+              `Error: Output directory "${outputDir}" is outside your project and home directory. Use a relative path or a path within your home directory.
+`
+            )
+          );
+          process.exit(1);
+        }
+        const tokensDir = path7.join(outputDir, "tokens");
+        const assetsDir = path7.join(outputDir, "assets");
+        fs9.mkdirSync(tokensDir, { recursive: true });
+        if (exportAssets) {
+          fs9.mkdirSync(assetsDir, { recursive: true });
+        }
+        io.err.write(chalk22.dim("Fetching Figma file...\n"));
+        const client = await factory.getClient();
+        let activeClient = client;
+        if (options.token) {
+          const { FigmaClient: FigmaClient2 } = await Promise.resolve().then(() => (init_client(), client_exports));
+          activeClient = new FigmaClient2({ token: options.token });
+        }
+        const [file, stylesResponse] = await Promise.all([
+          activeClient.getFile(fileKey),
+          activeClient.getFileStyles(fileKey)
+        ]);
+        const styles = stylesResponse.meta?.styles || [];
+        io.err.write(chalk22.dim("Extracting design tokens...\n"));
+        const tokens = extractStylesFromFile(file, styles);
+        for (const format of tokenFormats) {
+          let content;
+          let filename;
+          switch (format) {
+            case "css":
+              content = tokensToCss(tokens);
+              filename = "tokens.css";
+              break;
+            case "scss":
+              content = tokensToScss(tokens);
+              filename = "tokens.scss";
+              break;
+            case "json":
+            default:
+              content = JSON.stringify(tokens, null, 2);
+              filename = "tokens.json";
+              break;
+          }
+          fs9.writeFileSync(path7.join(tokensDir, filename), content + "\n");
+          io.err.write(chalk22.green(`  \u2713 ${filename}
+`));
+        }
+        const components = extractComponents(file);
+        const { pages, frames } = countPagesAndFrames(file);
+        if (exportAssets && components.length > 0) {
+          io.err.write(chalk22.dim("Exporting component assets...\n"));
+          const componentIds = components.map((c) => c.id);
+          const images = await activeClient.getImages(fileKey, componentIds, {
+            format: assetFormat
+          });
+          const imageUrls = images.images || {};
+          if (Object.keys(imageUrls).length === 0) {
+            io.err.write(
+              chalk22.yellow(
+                "  Warning: No image URLs returned from Figma API.\n"
+              )
+            );
+          }
+          const downloadItems = Object.entries(imageUrls).map(
+            ([nodeId, imageUrl]) => {
+              const component = components.find((c) => c.id === nodeId);
+              const filename = component ? `${toKebabCase(component.name)}.${assetFormat}` : `${sanitizeFilename(nodeId)}.${assetFormat}`;
+              if (component) {
+                component.asset = filename;
+              }
+              return {
+                id: nodeId,
+                url: imageUrl ?? null,
+                filename
+              };
+            }
+          );
+          const downloadResults = await downloadFiles(
+            downloadItems,
+            assetsDir
+          );
+          const successCount = downloadResults.filter(
+            (r) => r.status === "success"
+          ).length;
+          const failures = downloadResults.filter(
+            (r) => r.status === "error"
+          );
+          io.err.write(chalk22.green(`  \u2713 ${successCount} assets exported
+`));
+          if (failures.length > 0) {
+            io.err.write(
+              chalk22.yellow(
+                `  Warning: ${failures.length} asset(s) failed to download:
+`
+              )
+            );
+            for (const failure of failures) {
+              io.err.write(
+                chalk22.dim(
+                  `    - ${failure.name ?? failure.id}: ${failure.error}
+`
+                )
+              );
+            }
+            process.exit(1);
+          }
+        }
+        if (exportStructure) {
+          io.err.write(chalk22.dim("Generating structure.json...\n"));
+          const structure = extractSimplifiedStructure(file);
+          fs9.writeFileSync(
+            path7.join(outputDir, "structure.json"),
+            JSON.stringify(structure, null, 2) + "\n"
+          );
+          io.err.write(chalk22.green("  \u2713 structure.json\n"));
+        }
+        if (exportReadme) {
+          io.err.write(chalk22.dim("Generating HANDOFF.md...\n"));
+          const summary = {
+            name: file.name,
+            url: `https://www.figma.com/file/${fileKey}`,
+            generatedAt: (/* @__PURE__ */ new Date()).toISOString(),
+            tokens: countTokens(tokens),
+            components,
+            pages,
+            frames
+          };
+          const readme = generateHandoffReadme(summary, tokenFormats);
+          fs9.writeFileSync(path7.join(outputDir, "HANDOFF.md"), readme);
+          io.err.write(chalk22.green("  \u2713 HANDOFF.md\n"));
+        }
+        io.out.write(
+          chalk22.bold.green(`
+\u2713 Handoff package created at ${outputDir}
+`)
+        );
+      } catch (error) {
+        io.err.write(chalk22.red("Error creating handoff package.\n"));
+        if (error instanceof Error) {
+          io.err.write(chalk22.dim(`${error.message}
+`));
+        }
+        process.exit(1);
+      }
+    }
+  );
+  return cmd;
+}
+
 // src/cmd/root.ts
 function createRootCommand(factory) {
-  const program = new Command26();
+  const program = new Command30();
   program.name("figma").description("CLI for the Figma API").version("1.0.0").configureHelp({
     sortSubcommands: true,
     sortOptions: true
   });
   program.addCommand(createAuthCommand(factory));
   program.addCommand(createFileCommand(factory));
+  program.addCommand(createFrameCommand(factory));
+  program.addCommand(createHandoffCommand(factory));
   program.addCommand(createProjectCommand(factory));
   program.addCommand(createComponentCommand(factory));
   program.addCommand(createStyleCommand(factory));