extrafigma 0.1.0__tar.gz

extrafigma-0.1.0/LICENSE

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

extrafigma-0.1.0/PKG-INFO

@@ -0,0 +1,128 @@
+Metadata-Version: 2.4
+Name: extrafigma
+Version: 0.1.0
+Summary: Pull Figma files into agent-readable local folders
+Project-URL: Homepage, https://github.com/think41/extrafigma
+Project-URL: Repository, https://github.com/think41/extrafigma
+Project-URL: Issues, https://github.com/think41/extrafigma/issues
+License-Expression: MIT
+License-File: LICENSE
+Keywords: ai,cli,codegen,design,figma
+Classifier: Environment :: Console
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Multimedia :: Graphics
+Classifier: Topic :: Software Development :: Code Generators
+Requires-Python: >=3.11
+Requires-Dist: httpx>=0.27.0
+Requires-Dist: rich>=13.0.0
+Requires-Dist: typer>=0.12.0
+Description-Content-Type: text/markdown
+
+# ExtraFigma
+
+A pull-only CLI that converts Figma files into agent-readable local folders. Drop the output into your project and let Claude Code (or any AI coding agent) implement pixel-perfect frontend code from the design.
+
+## Install
+
+```bash
+pip install extrafigma
+# or
+uvx extrafigma --help
+```
+
+## Quick start
+
+```bash
+extrafigma pull "https://www.figma.com/design/abc123/My-App" ./my-design
+```
+
+On first run you'll be prompted for a Figma Personal Access Token. Get one at **Figma → Settings → Security → Personal Access Tokens** (scopes needed: `file_content:read`, `file_metadata:read`).
+
+The token is stored at `~/.config/extrafigma/credentials.json` and reused for all future pulls.
+
+## What gets extracted
+
+```
+my-design/
+  CLAUDE.md               ← instructions for AI agents
+  index.md                ← overview of all pages and frames
+  tokens/
+    colors.json           ← named color styles → hex values
+    typography.json       ← named text styles → font properties
+  assets/
+    icon-name.svg         ← exported SVG icons (VECTOR nodes)
+  pages/
+    Page-1/
+      page.md
+      Hero.frame.json     ← distilled layout tree (CSS-friendly)
+      Hero.png            ← 2× frame render (visual ground truth)
+```
+
+### `frame.json` structure
+
+Every frame is distilled to a CSS-friendly layout tree:
+
+```json
+{
+  "type": "FRAME",
+  "name": "Hero",
+  "width": 1440,
+  "height": 900,
+  "layout": { "mode": "flex", "direction": "column", "gap": 24 },
+  "background": "colors/brand-primary",
+  "borderRadius": 0,
+  "children": [
+    {
+      "type": "TEXT",
+      "content": "Welcome",
+      "style": "typography/heading-xl",
+      "color": "colors/gray-800"
+    }
+  ]
+}
+```
+
+Named Figma Styles become tokens (`colors/brand-primary`, `typography/heading-xl`). Raw hex values that weren't saved as styles are flagged with `# not in tokens`.
+
+## Auth commands
+
+```bash
+extrafigma auth login               # interactive prompt
+extrafigma auth login --pat <token> # non-interactive (CI-friendly)
+extrafigma auth status              # check stored PAT
+extrafigma auth logout              # remove stored PAT
+```
+
+## Rate limits
+
+Figma's REST API limits `GET /v1/files` calls based on your seat type:
+
+| Seat | Limit |
+|------|-------|
+| View / Collab | 6 per month |
+| Dev / Full (Starter) | 10 per minute |
+| Dev / Full (Professional) | 15 per minute |
+
+Use an account with an **editor seat** on the file for meaningful usage.
+
+## Known limitations
+
+- **Design tokens require named Figma Styles.** If the designer applied colors directly without saving them as named styles, tokens will be empty. Variables (Figma Professional+) are not supported — use Styles instead.
+- **SVG export skips remote library components.** Icons that are instances of components from external shared libraries cannot be exported via the REST API. They'll appear as `INSTANCE` nodes in the frame JSON.
+- **x/y positions** are canvas-space coordinates. For absolute-layout frames, subtract the parent's x/y to get relative positions.
+
+## How it works
+
+1. `GET /v1/files/:key` — fetches the full document tree
+2. Batch-fetches style node data to resolve exact color/font values
+3. Distills each top-level frame to a CSS-friendly JSON tree
+4. Exports frame PNGs at 2× resolution
+5. Exports VECTOR nodes as SVGs in a second pass
+
+## License
+
+MIT

extrafigma-0.1.0/README.md

@@ -0,0 +1,104 @@
+# ExtraFigma
+
+A pull-only CLI that converts Figma files into agent-readable local folders. Drop the output into your project and let Claude Code (or any AI coding agent) implement pixel-perfect frontend code from the design.
+
+## Install
+
+```bash
+pip install extrafigma
+# or
+uvx extrafigma --help
+```
+
+## Quick start
+
+```bash
+extrafigma pull "https://www.figma.com/design/abc123/My-App" ./my-design
+```
+
+On first run you'll be prompted for a Figma Personal Access Token. Get one at **Figma → Settings → Security → Personal Access Tokens** (scopes needed: `file_content:read`, `file_metadata:read`).
+
+The token is stored at `~/.config/extrafigma/credentials.json` and reused for all future pulls.
+
+## What gets extracted
+
+```
+my-design/
+  CLAUDE.md               ← instructions for AI agents
+  index.md                ← overview of all pages and frames
+  tokens/
+    colors.json           ← named color styles → hex values
+    typography.json       ← named text styles → font properties
+  assets/
+    icon-name.svg         ← exported SVG icons (VECTOR nodes)
+  pages/
+    Page-1/
+      page.md
+      Hero.frame.json     ← distilled layout tree (CSS-friendly)
+      Hero.png            ← 2× frame render (visual ground truth)
+```
+
+### `frame.json` structure
+
+Every frame is distilled to a CSS-friendly layout tree:
+
+```json
+{
+  "type": "FRAME",
+  "name": "Hero",
+  "width": 1440,
+  "height": 900,
+  "layout": { "mode": "flex", "direction": "column", "gap": 24 },
+  "background": "colors/brand-primary",
+  "borderRadius": 0,
+  "children": [
+    {
+      "type": "TEXT",
+      "content": "Welcome",
+      "style": "typography/heading-xl",
+      "color": "colors/gray-800"
+    }
+  ]
+}
+```
+
+Named Figma Styles become tokens (`colors/brand-primary`, `typography/heading-xl`). Raw hex values that weren't saved as styles are flagged with `# not in tokens`.
+
+## Auth commands
+
+```bash
+extrafigma auth login               # interactive prompt
+extrafigma auth login --pat <token> # non-interactive (CI-friendly)
+extrafigma auth status              # check stored PAT
+extrafigma auth logout              # remove stored PAT
+```
+
+## Rate limits
+
+Figma's REST API limits `GET /v1/files` calls based on your seat type:
+
+| Seat | Limit |
+|------|-------|
+| View / Collab | 6 per month |
+| Dev / Full (Starter) | 10 per minute |
+| Dev / Full (Professional) | 15 per minute |
+
+Use an account with an **editor seat** on the file for meaningful usage.
+
+## Known limitations
+
+- **Design tokens require named Figma Styles.** If the designer applied colors directly without saving them as named styles, tokens will be empty. Variables (Figma Professional+) are not supported — use Styles instead.
+- **SVG export skips remote library components.** Icons that are instances of components from external shared libraries cannot be exported via the REST API. They'll appear as `INSTANCE` nodes in the frame JSON.
+- **x/y positions** are canvas-space coordinates. For absolute-layout frames, subtract the parent's x/y to get relative positions.
+
+## How it works
+
+1. `GET /v1/files/:key` — fetches the full document tree
+2. Batch-fetches style node data to resolve exact color/font values
+3. Distills each top-level frame to a CSS-friendly JSON tree
+4. Exports frame PNGs at 2× resolution
+5. Exports VECTOR nodes as SVGs in a second pass
+
+## License
+
+MIT

extrafigma-0.1.0/extrafigma/__init__.py

@@ -0,0 +1 @@
+__version__ = "0.1.0"

extrafigma-0.1.0/extrafigma/api.py

@@ -0,0 +1,117 @@
+import time
+from typing import Optional
+
+import httpx
+
+BASE_URL = "https://api.figma.com/v1"
+# Figma returns very large Retry-After values for monthly quota exhaustion.
+# We cap the sleep and surface a clear error instead.
+_MAX_RETRY_SLEEP = 60.0
+
+
+class FigmaAPIError(Exception):
+    def __init__(self, status_code: int, message: str):
+        self.status_code = status_code
+        super().__init__(f"Figma API {status_code}: {message}")
+
+
+class FigmaAuthError(FigmaAPIError):
+    pass
+
+
+class FigmaNotFoundError(FigmaAPIError):
+    pass
+
+
+class FigmaPermissionError(FigmaAPIError):
+    pass
+
+
+class FigmaRateLimitError(FigmaAPIError):
+    def __init__(self, retry_after: Optional[float] = None, quota_exhausted: bool = False):
+        self.retry_after = retry_after
+        self.quota_exhausted = quota_exhausted
+        msg = (
+            "Monthly API quota exhausted. Resets on the 1st of next month.\n"
+            "  Upgrade your Figma seat to Dev/Full for 10 req/min instead of 6/month."
+            if quota_exhausted
+            else "Rate limited after retries"
+        )
+        super().__init__(429, msg)
+
+
+class FigmaClient:
+    def __init__(self, pat: str):
+        self._client = httpx.Client(
+            headers={"X-Figma-Token": pat},
+            timeout=90.0,
+        )
+
+    def _get(self, path: str, params: Optional[dict] = None) -> dict:
+        url = f"{BASE_URL}{path}"
+        for attempt in range(3):
+            resp = self._client.get(url, params=params or {})
+            if resp.status_code == 200:
+                return resp.json()
+            if resp.status_code == 429:
+                retry_after = float(resp.headers.get("Retry-After", 10))
+                # Large values (>5 min) indicate monthly quota exhaustion, not a burst limit.
+                if retry_after > _MAX_RETRY_SLEEP:
+                    raise FigmaRateLimitError(retry_after=retry_after, quota_exhausted=True)
+                print(f"  Rate limited. Waiting {retry_after:.0f}s...")
+                time.sleep(retry_after)
+                continue
+            if resp.status_code == 401:
+                raise FigmaAuthError(401, "Invalid PAT. Run: extrafigma auth login")
+            if resp.status_code == 404:
+                raise FigmaNotFoundError(404, f"Not found: {path}")
+            if resp.status_code == 403:
+                raise FigmaPermissionError(403, resp.text[:200])
+            resp.raise_for_status()
+        raise FigmaRateLimitError()
+
+    def get_file(self, file_key: str) -> dict:
+        return self._get(f"/files/{file_key}", params={"geometry": "paths"})
+
+    def get_nodes(self, file_key: str, node_ids: list[str]) -> dict:
+        """Return {node_id: document_node} for the given node IDs."""
+        if not node_ids:
+            return {}
+        data = self._get(
+            f"/files/{file_key}/nodes",
+            params={"ids": ",".join(node_ids)},
+        )
+        return {
+            nid: info.get("document", {})
+            for nid, info in data.get("nodes", {}).items()
+            if info
+        }
+
+    def get_images(
+        self,
+        file_key: str,
+        ids: list[str],
+        scale: int = 2,
+        format: str = "png",
+    ) -> dict:
+        """Return {node_id: signed_url}. Batches handled by caller."""
+        if not ids:
+            return {}
+        params: dict = {"ids": ",".join(ids), "format": format}
+        if format == "png":
+            params["scale"] = scale
+        elif format == "svg":
+            params["svg_outline_text"] = "false"   # keep <text> elements, not paths
+            params["svg_include_id"] = "false"
+            params["svg_simplify_stroke"] = "true"
+        data = self._get(f"/images/{file_key}", params=params)
+        return data.get("images", {})
+
+    def close(self) -> None:
+        self._client.close()
+
+    def __enter__(self) -> "FigmaClient":
+        return self
+
+    def __exit__(self, *_) -> None:
+        self.close()

extrafigma-0.1.0/extrafigma/auth.py

@@ -0,0 +1,33 @@
+import json
+import stat
+from pathlib import Path
+
+
+def get_credentials_path() -> Path:
+    config_dir = Path.home() / ".config" / "extrafigma"
+    config_dir.mkdir(parents=True, exist_ok=True)
+    return config_dir / "credentials.json"
+
+
+def save_pat(pat: str) -> None:
+    path = get_credentials_path()
+    path.write_text(json.dumps({"pat": pat}, indent=2))
+    path.chmod(stat.S_IRUSR | stat.S_IWUSR)
+
+
+def load_pat() -> str:
+    path = get_credentials_path()
+    if not path.exists():
+        return ""
+    try:
+        return json.loads(path.read_text()).get("pat", "")
+    except (json.JSONDecodeError, OSError):
+        return ""
+
+
+def delete_credentials() -> bool:
+    path = get_credentials_path()
+    if path.exists():
+        path.unlink()
+        return True
+    return False

extrafigma-0.1.0/extrafigma/cli.py

@@ -0,0 +1,95 @@
+from typing import Optional
+
+import typer
+from rich.console import Console
+from rich.text import Text
+
+from extrafigma.auth import load_pat, save_pat, delete_credentials, get_credentials_path
+from extrafigma.utils.file_key import parse_file_key
+
+console = Console()
+app = typer.Typer(
+    name="extrafigma",
+    help="Pull Figma files into agent-readable local folders.",
+    no_args_is_help=True,
+)
+auth_app = typer.Typer(help="Manage your Figma Personal Access Token.")
+app.add_typer(auth_app, name="auth")
+
+
+def _require_pat() -> str:
+    """Return stored PAT, prompting the user to set one if not found."""
+    pat = load_pat()
+    if pat:
+        return pat
+    console.print("[yellow]No Figma PAT found.[/yellow] You only need to do this once.\n")
+    console.print("[dim]Get yours at: Figma → Settings → Security → Personal Access Tokens[/dim]")
+    console.print("[dim]Required scopes: file_content:read, file_metadata:read[/dim]\n")
+    pat = typer.prompt("Paste your Figma PAT", hide_input=True).strip()
+    if not pat:
+        console.print("[red]✗ No PAT provided.[/red]")
+        raise typer.Exit(1)
+    save_pat(pat)
+    console.print("[green]✓ PAT saved — won't ask again.[/green]\n")
+    return pat
+
+
+@auth_app.command("login")
+def auth_login(
+    pat: Optional[str] = typer.Option(None, "--pat", help="PAT to store (skips interactive prompt)"),
+):
+    """Store your Figma Personal Access Token."""
+    if pat:
+        pat = pat.strip()
+    else:
+        console.print("[dim]Generate a PAT at: Figma → Settings → Security → Personal Access Tokens[/dim]")
+        console.print("[dim]Required scopes: file_content:read, file_metadata:read[/dim]\n")
+        pat = typer.prompt("Paste your Figma PAT", hide_input=True).strip()
+    if not pat:
+        console.print("[red]✗ No PAT provided.[/red]")
+        raise typer.Exit(1)
+    save_pat(pat)
+    console.print("[green]✓ PAT saved.[/green]")
+
+
+@auth_app.command("status")
+def auth_status():
+    """Show PAT status."""
+    creds = get_credentials_path()
+    if not creds.exists():
+        console.print("[red]✗ No PAT stored.[/red] Run: extrafigma auth login")
+        raise typer.Exit(1)
+    pat = load_pat()
+    if not pat:
+        console.print("[red]✗ credentials.json exists but PAT is empty.[/red]")
+        raise typer.Exit(1)
+    masked = pat[:8] + "..." + pat[-4:] if len(pat) > 12 else "***"
+    console.print(f"[green]✓ PAT set[/green] ({masked})")
+    console.print(f"  Stored at: {creds}")
+
+
+@auth_app.command("logout")
+def auth_logout():
+    """Remove stored credentials."""
+    if delete_credentials():
+        console.print("[green]✓ Credentials removed.[/green]")
+    else:
+        console.print("No credentials to remove.")
+
+
+@app.command()
+def pull(
+    url: str = typer.Argument(..., help="Figma file URL or file key"),
+    folder: str = typer.Argument(..., help="Output folder path"),
+):
+    """Pull a Figma file to a local agent-readable folder."""
+    from extrafigma.puller.pull import pull as do_pull
+
+    pat = _require_pat()
+
+    file_key = parse_file_key(url)
+    if not file_key:
+        console.print(f"[red]✗ Could not parse a file key from:[/red] {url}")
+        raise typer.Exit(1)
+
+    do_pull(file_key=file_key, figma_url=url, output_dir=folder, pat=pat)