figma-sprite-tool 0.1.0 → 0.1.1

package/README.md

@@ -18,16 +18,76 @@ CLI tool to generate PNG/SVG sprite sheets, SCSS mixins, and JSON metadata from
 
 ## Installation
 
+### For End Users
+
+#### Global Installation (Recommended)
+```bash
+npm install -g figma-sprite-tool
+```
+
+Verify installation:
+```bash
+figma-sprite --version
+```
+
+#### Use with npx (No Installation)
+```bash
+npx figma-sprite-tool init
+npx figma-sprite-tool generate
+```
+
+#### Project-Local Installation
+```bash
+npm install --save-dev figma-sprite-tool
+```
+
+Add to package.json:
+```json
+{
+  "scripts": {
+    "sprite": "figma-sprite generate"
+  }
+}
+```
+
+## Environment Setup
+
+### Figma Token
+
+Get your token from: https://www.figma.com/developers/api#access-tokens
+
+#### Windows (Git Bash)
+```bash
+export FIGMA_TOKEN="your-token-here"
+```
+
+Make persistent:
 ```bash
-npm i -g figma-sprite-tool
+echo 'export FIGMA_TOKEN="your-token-here"' >> ~/.bashrc
+```
+
+#### Windows (CMD)
+```cmd
+set FIGMA_TOKEN=your-token-here
+```
+
+Make persistent:
+```cmd
+setx FIGMA_TOKEN "your-token-here"
 ```
 
-Without global install:
+#### macOS/Linux
+```bash
+export FIGMA_TOKEN="your-token-here"
+```
 
+Make persistent:
 ```bash
-npx figma-sprite --help
+echo 'export FIGMA_TOKEN="your-token-here"' >> ~/.bashrc
 ```
 
+⚠️ **Never commit tokens to git!**
+
 ## Development
 
 ```bash
@@ -172,6 +232,43 @@ For detailed usage instructions on how to use generated sprite files:
 - 🇰🇷 [스프라이트 사용 가이드 (한국어)](./docs/SPRITE_USAGE_GUIDE.md)
 - 🇬🇧 [Sprite Usage Guide (English)](./docs/SPRITE_USAGE_GUIDE_EN.md)
 
+## Troubleshooting
+
+### Command not found: figma-sprite
+
+**Problem**: Package not installed or not in PATH.
+
+**Solutions**:
+- Install globally: `npm install -g figma-sprite-tool`
+- Use npx: `npx figma-sprite-tool [command]`
+- Check PATH: `which figma-sprite` (should show path)
+
+### Figma token not found
+
+**Problem**: FIGMA_TOKEN environment variable not set.
+
+**Solutions**:
+1. Get token from: https://www.figma.com/developers/api#access-tokens
+2. Set environment variable (see [Environment Setup](#environment-setup))
+3. Or add to config: `{ "figma": { "personalAccessToken": "..." } }`
+
+### Configuration file not found
+
+**Problem**: `figma.sprite.config.json` missing.
+
+**Solutions**:
+- Run: `figma-sprite init`
+- Or create config manually (see [Manual Configuration (Advanced)](#manual-configuration-advanced))
+
+### Permission denied (Windows)
+
+**Problem**: Execution policy blocks scripts.
+
+**Solution** (PowerShell as Administrator):
+```powershell
+Set-ExecutionPolicy -ExecutionPolicy RemoteSigned -Scope CurrentUser
+```
+
 ## Architecture
 
 - **CLI Layer**: Commander.js for command-line interface

package/dist/index.js

@@ -394,14 +394,28 @@ function normalizeLegacyConfig(rawConfig) {
 async function loadConfig(options = {}) {
   const configPath = await resolveConfigPath(options);
   if (!configPath) {
-    throw createConfigError(
-      "E101" /* CONFIG_NOT_FOUND */,
-      "Configuration file not found",
-      {
-        searchedPaths: DEFAULT_CONFIG_NAMES,
-        cwd: options.cwd ?? process.cwd()
-      }
-    );
+    const cwd = options.cwd ?? process.cwd();
+    const errorMessage = [
+      "\u274C Configuration file not found",
+      "",
+      "\u{1F680} Quick Start:",
+      "  Run: figma-sprite init",
+      "  Then follow the interactive prompts",
+      "",
+      "\u{1F4DD} Manual Setup:",
+      `  Create ${DEFAULT_CONFIG_NAMES[0]} with:`,
+      "  {",
+      '    "figma": { "fileKey": "...", "page": "..." },',
+      '    "output": { "dir": "./sprites", "name": "sprite" }',
+      "  }",
+      "",
+      `\u{1F4C2} Searched in: ${cwd}`,
+      `\u{1F4C4} Tried: ${DEFAULT_CONFIG_NAMES.join(", ")}`
+    ].join("\n");
+    throw createConfigError("E101" /* CONFIG_NOT_FOUND */, errorMessage, {
+      searchedPaths: DEFAULT_CONFIG_NAMES,
+      cwd
+    });
   }
   return await loadConfigFromPath(configPath);
 }
@@ -2335,9 +2349,27 @@ function getFigmaToken(config) {
   }
   const token = process.env.FIGMA_TOKEN;
   if (!token) {
-    throw new Error(
-      "Figma token not found. Set FIGMA_TOKEN environment variable or add personalAccessToken to config."
-    );
+    const errorMessage = [
+      "\u274C Figma token not found",
+      "",
+      "\u{1F4DD} Setup Instructions:",
+      "  1. Get your token: https://www.figma.com/developers/api#access-tokens",
+      "  2. Set environment variable:",
+      "",
+      "  Windows (Git Bash):",
+      '    export FIGMA_TOKEN="your-token-here"',
+      "",
+      "  Windows (CMD):",
+      "    set FIGMA_TOKEN=your-token-here",
+      "",
+      "  macOS/Linux:",
+      '    export FIGMA_TOKEN="your-token-here"',
+      "",
+      '  3. Or add to config: { "figma": { "personalAccessToken": "your-token" } }',
+      "",
+      "\u26A0\uFE0F  Never commit tokens to git!"
+    ].join("\n");
+    throw new Error(errorMessage);
   }
   return token;
 }