pi-mono-figma 0.1.1

package/CHANGELOG.md

@@ -0,0 +1,34 @@
+# pi-mono-figma
+
+## Unreleased
+
+### Minor Changes
+
+### Added: LLM-ready Figma workflow
+
+- Added `figma_get_node_summary`, `figma_extract_text`, `figma_explain_node`, and `figma_get_implementation_context` processed tools.
+- Added compact node summarization that ignores hidden nodes, vector internals, and component instance internals by default.
+- Changed `figma_get_design_context` to return compact top-level file context or target-node summaries instead of full recursive file structure.
+- Updated tool descriptions, README, and skill guidance to prefer processed tools and keep raw JSON tools as debugging escape hatches.
+- Added response caps, truncation metadata, and next-step suggestions for summarized node output.
+
+## 0.1.1
+
+### Patch Changes
+
+### Enhanced: auth setup
+
+- Added `/figma-auth` command and `figma_configure_auth` tool for masked local token capture.
+- Figma tools now prompt for a fresh token and retry once when auth is missing, invalid, or expired.
+- Token setup writes to `~/.pi/agent/auth.json` without returning the token to the model.
+
+## 0.1.0
+
+### Minor Changes
+
+### New Extension: figma
+
+- Added native Figma REST API tools for file, node, styles, variables, components, component sets, component search, design-context, URL parsing, metadata, and node rendering workflows.
+- Added bundled `figma` skill that explains when and how to use the native `figma_*` tools.
+- Added authentication support via `FIGMA_TOKEN` and `~/.pi/agent/auth.json` at `.figma.token`.
+- Added README documentation for token creation, required Figma file-content read scope, and setup/troubleshooting.

package/LICENCE.md

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

package/README.md

@@ -0,0 +1,171 @@
+# pi-mono-figma
+
+A pi extension and skill package that exposes native Figma tools for design exploration and design-to-code workflows. The default tools return compact, LLM-ready design context instead of raw Figma JSON.
+
+## Tools
+
+### Processed, LLM-ready tools (preferred)
+
+- `figma_parse_url` — parse a Figma URL into `fileKey` and `nodeId`.
+- `figma_render_nodes` — render node image URLs and optionally download assets locally. Downloads use an OS temp directory by default unless `outputDir` is provided.
+- `figma_get_node_summary` — fetch a compact structured summary of a node: name, type, size, layout, spacing, visual style, visible text, component properties, and shallow child hierarchy.
+- `figma_extract_text` — return visible text nodes only.
+- `figma_explain_node` — explain a node in Markdown using summary, visible text, hierarchy, and optional rendered asset.
+- `figma_get_implementation_context` — return coding-ready design context: purpose, sections, fields/buttons, measurements, typography, colors, spacing, assets, and component hierarchy.
+- `figma_get_design_context` — fetch compact file context. With `nodeId`, returns target node summary plus location/sibling context; without `nodeId`, returns canvases and top-level frames only.
+- `figma_get_node_metadata` — fetch compact spatial/layout metadata for one or more nodes.
+- `figma_get_styles` — fetch named styles.
+- `figma_get_variables` — fetch local variables/collections for design tokens.
+- `figma_get_components` — fetch component metadata.
+- `figma_get_component_sets` — fetch component set metadata.
+- `figma_search_components` — search components by name or description.
+- `figma_configure_auth` — securely prompt for and store a Figma token without exposing it to the model.
+
+### Raw escape hatches
+
+- `figma_get_file` — fetch raw Figma file JSON. Use only when raw Figma JSON is explicitly needed or when debugging the extension.
+- `figma_get_nodes` — fetch raw node JSON. Use only when raw Figma JSON is explicitly needed or when debugging the extension.
+
+The package also bundles the `figma` skill under `skills/figma/SKILL.md`.
+
+## Recommended workflows
+
+### Explaining a component
+
+```text
+figma_parse_url
+figma_render_nodes
+figma_explain_node
+```
+
+### Implementing a design
+
+```text
+figma_parse_url
+figma_render_nodes
+figma_get_implementation_context
+figma_get_node_summary for specific subnodes if needed
+```
+
+### Debugging raw Figma data
+
+```text
+figma_get_nodes
+```
+
+## Processed node options
+
+Processed tools fetch nodes with compact depth limits and summarize safely:
+
+```ts
+{
+  depth?: number; // default 2, capped at 4
+  includeHidden?: boolean; // default false
+  includeVectors?: boolean; // default false
+  includeComponentInternals?: boolean; // default false
+}
+```
+
+Defaults intentionally avoid hidden layers, vector internals, and huge component instance trees. Increase depth or include internals only for a focused child node.
+
+## Output limits and truncation
+
+Processed tools default to compact responses (~20k chars unless overridden by `maxResponseChars`) and cap common large arrays:
+
+- visible text: 200 entries
+- children: 100 entries
+- depth: 4 max
+
+When data is capped, responses include `metadata.truncated: true`, `truncatedReasons`, and `nextSteps` such as inspecting a child node or increasing depth.
+
+## Authentication
+
+The extension looks for a Figma token in this order:
+
+1. in-memory token override created by `/figma-auth --force` or `figma_configure_auth`
+2. `FIGMA_TOKEN` environment variable
+3. `~/.pi/agent/auth.json` at `.figma.token`
+
+If no token is found, or if Figma rejects the token as invalid/expired, the native tools can prompt you with a masked local dialog and store the replacement token without returning it to the model.
+
+Do **not** paste tokens into an LLM chat.
+
+### Recommended: native auth command
+
+Run this in pi:
+
+```text
+/figma-auth --force
+```
+
+The command shows the Figma token URL and required scopes, prompts for the token with masked input, and writes it to `~/.pi/agent/auth.json` at `.figma.token`.
+
+The same flow is available to the agent through the `figma_configure_auth` tool. That tool returns only metadata such as `stored: true`; it never returns the token.
+
+### Option A: environment variable
+
+For the current shell session:
+
+```bash
+export FIGMA_TOKEN="figd_xxx"
+```
+
+To persist it, add that export to your shell profile (`~/.zshrc`, `~/.bashrc`, etc.) or your preferred secrets manager.
+
+### Option B: pi auth file
+
+Create or update `~/.pi/agent/auth.json`:
+
+```json
+{
+  "figma": {
+    "token": "figd_xxx"
+  }
+}
+```
+
+Recommended file permissions:
+
+```bash
+mkdir -p ~/.pi/agent
+chmod 700 ~/.pi/agent
+chmod 600 ~/.pi/agent/auth.json
+```
+
+If the file already contains other credentials, merge the `figma.token` entry instead of overwriting the file.
+
+## Creating a Figma token
+
+1. Open Figma.
+2. Go to **Settings → Security → Personal access tokens**.
+3. Click **Generate new token**.
+4. Name it something recognizable, for example `pi-agent`.
+5. Enable the required scopes/permissions below.
+6. Copy the token once and store it via `FIGMA_TOKEN` or `~/.pi/agent/auth.json`.
+
+## Required scopes / permissions
+
+This extension is read-only. It needs permission to read file content and render nodes.
+
+Enable:
+
+- **File content** / read access to files
+
+Also make sure the token has access to the specific Figma file, project, or team you want to inspect. If your Figma organization supports resource scoping, grant access only to the minimum projects/files needed.
+
+No write/admin scopes are required.
+
+## Troubleshooting
+
+### `Token expired`
+
+Generate a new Figma personal access token and update `FIGMA_TOKEN` or `~/.pi/agent/auth.json`.
+
+### Missing or inaccessible file
+
+Confirm that:
+
+- the file key is correct,
+- the token has file-content read permission,
+- the token owner can access the file in Figma,
+- the node ID uses either URL format (`27399-4245`) or API format (`27399:4245`).

package/index.ts

@@ -0,0 +1,6 @@
+import type { ExtensionAPI } from "@mariozechner/pi-coding-agent";
+import { registerFigmaTools } from "./src/figma-tools.js";
+
+export default function figmaExtension(pi: ExtensionAPI): void {
+	registerFigmaTools(pi);
+}

package/package.json

@@ -0,0 +1,27 @@
+{
+  "name": "pi-mono-figma",
+  "version": "0.1.1",
+  "description": "Pi extension and skill for Figma design context tools",
+  "type": "module",
+  "keywords": [
+    "pi-package",
+    "pi-extension",
+    "pi-skill",
+    "figma"
+  ],
+  "dependencies": {
+    "pi-common": "0.1.1"
+  },
+  "peerDependencies": {
+    "@mariozechner/pi-coding-agent": "*",
+    "@sinclair/typebox": "*"
+  },
+  "pi": {
+    "extensions": [
+      "./index.ts"
+    ],
+    "skills": [
+      "./skills"
+    ]
+  }
+}

package/skills/figma/SKILL.md

@@ -0,0 +1,113 @@
+---
+name: figma
+description: Access Figma design files using native pi tools — read LLM-ready summaries, explanations, implementation context, screenshots, components, styles, variables, and design tokens. Requires a Figma personal access token.
+---
+
+# Figma Design Integration
+
+Use the native `figma_*` tools to read Figma files and translate designs into code. Prefer processed, LLM-ready tools over raw Figma JSON.
+
+## When to Use
+
+- User provides a Figma file URL and asks you to explain or implement a design.
+- User asks about Figma colors, typography, spacing, components, variables, or layout.
+- You need screenshots/assets for visual validation.
+
+## Authentication
+
+The tools read the token from an in-memory override, `FIGMA_TOKEN`, or `~/.pi/agent/auth.json` at `.figma.token`.
+
+If auth is missing, invalid, or expired, do **not** ask the user to paste the token in chat. Use the native `figma_configure_auth` tool or ask the user to run `/figma-auth --force`. The prompt is masked and the token is stored by the extension without returning it to the model.
+
+## URL Parsing
+
+Given:
+
+```text
+https://www.figma.com/design/ABC123def456/Project-Name?node-id=123-456
+```
+
+- File key: `ABC123def456`
+- Node ID: `123-456` from the URL (`figma_*` tools also accept API format `123:456`)
+
+Use `figma_parse_url` when you need to extract these values from a full URL.
+
+## Default Tool Workflow
+
+1. Use `figma_configure_auth` only when auth is missing, invalid, expired, or the user asks to update the token.
+2. Use `figma_parse_url` for full Figma URLs.
+3. Use `figma_render_nodes` for screenshots/assets when visual context helps.
+4. Use `figma_explain_node` or `figma_get_node_summary` for the target frame/component.
+5. Use `figma_get_implementation_context` when coding from a design.
+6. Use `figma_get_design_context` for compact file/page/top-level context.
+7. Use `figma_get_nodes` only for raw debugging.
+
+**Do not call `figma_get_nodes` by default. Prefer processed tools.**
+
+Prefer batch calls where supported: pass multiple node IDs to `figma_render_nodes`, `figma_get_node_metadata`, or raw `figma_get_nodes` instead of looping.
+
+## Recommended Workflows
+
+### Explaining a component
+
+```text
+figma_parse_url
+figma_render_nodes
+figma_explain_node
+```
+
+### Implementing a design
+
+```text
+figma_parse_url
+figma_render_nodes
+figma_get_implementation_context
+figma_get_node_summary for specific subnodes if needed
+```
+
+### Debugging the extension or raw Figma data
+
+```text
+figma_get_nodes
+```
+
+## Processed Tools
+
+- `figma_get_node_summary` returns compact structured summaries: name, type, size, layout, spacing/padding, fills/strokes/effects, visible text, component properties, and immediate child hierarchy.
+- `figma_extract_text` returns visible text nodes only.
+- `figma_explain_node` returns human-readable Markdown for questions like “Explain this component.”
+- `figma_get_implementation_context` returns coding-ready context: purpose, sections, fields/buttons, measurements, typography, colors, spacing, assets, and React-friendly hierarchy.
+
+Processed tools default to shallow, safe fetches:
+
+```ts
+{
+  depth: 2,
+  includeHidden: false,
+  includeVectors: false,
+  includeComponentInternals: false
+}
+```
+
+Only increase `depth` (max 4) or enable internals/vectors for a specific child node when needed.
+
+## Raw Escape Hatches
+
+- `figma_get_file`
+- `figma_get_nodes`
+
+Use these only when raw Figma JSON is explicitly needed or when debugging the extension. They may return very large responses and reduce answer quality.
+
+## Output Limits
+
+Processed tools enforce compact defaults and may include `metadata.truncated: true` plus `nextSteps`, for example:
+
+- Call `figma_get_node_summary` with a deeper `depth`.
+- Inspect a specific child node by ID.
+- Enable `includeComponentInternals=true` for a focused component instance.
+
+## Notes
+
+- Figma API is rate-limited; batch node IDs where supported.
+- Large responses may be truncated; narrow to a specific child node when needed.
+- This integration is read-only and cannot modify Figma files.

package/src/figma-cache.ts

@@ -0,0 +1,6 @@
+import { createTtlCache } from "pi-common/cache";
+
+export const figmaCache = createTtlCache<unknown>({
+	defaultTtlMs: 5 * 60 * 1000,
+	maxEntries: 100,
+});