@grampro/kit 2.5.0 → 2.6.0

package/CHANGELOG.md

@@ -1,5 +1,93 @@
 # Changelog
 
+## 2.6.0
+
+### Added
+
+**A whole Figma design, exported once and built screen by screen.**
+
+In Figma, **Grampro Kit → Export all screens for an agent** walks every page
+and takes each top-level frame. Then:
+
+```bash
+npx @grampro/kit design ./design.json
+```
+
+```text
+Wrote 3 screen(s) to design/
+  purchase-orders.json         Purchase orders (Product) — 22 nodes
+  suppliers.json               Suppliers (Product) — 16 nodes
+  settings.json                Settings (Admin) — 12 nodes
+  index.json                   the plan: every screen, shared theme
+```
+
+The accuracy is in the theme rather than the convenience. Derived one
+frame at a time it disagrees with itself — a screen that is mostly white
+names a different background from one that is mostly grey — and the agent
+then themes each page differently. Read across every screen, once, it is
+well founded.
+
+`index.json` is the plan: every screen with its size, node count and the
+regions whose names repeat, plus that shared theme. It is the cheap place
+to be wrong. A design drawn without the component library names nothing
+directly, so every component is inferred, and a guess that `Action` is a
+Card rather than a Button costs one sentence there and five screens of
+rework later.
+
+**`figma_frame` reads a file.** Pass `designFile` with a path instead of
+`design` with the JSON. A chat input caps at around fifty thousand
+characters and a whole screen passes that; and a pasted export sits in the
+conversation twice, once as the argument and again inside the tool call,
+where a file appears only in the answer.
+
+**Every prop the library declares now carries a description.** 117 did
+not, and the passports are what an agent reads instead of the source, so
+an undescribed prop is one it guesses at. `DataGrid`'s `columns` and
+`data` had none at all. See 2.5.0's notes — this is that work, reaching
+npm for the first time.
+
+### Changed
+
+**The Figma export costs a third of what it did.** The copy button takes
+minified JSON: `JSON.parse` cannot tell the difference, and indentation
+was most of the payload. Three fields that said nothing went with it —
+`radius: 0` on every square frame, `padding: [0,0,0,0]` on every frame
+without padding, and `align`/`justify` restating Figma's own defaults —
+along with the child frame Figma wraps around every icon, whose entire
+content was the word "Vector" when the frame's name (`search`, `plus`)
+was the whole signal.
+
+**It also says more about what it exports.** Node size and stroke colour
+are now included, because most designs are not built from the kit's Figma
+library and an agent has to infer every component from what it can see. A
+36px pill with a label is a button; the same shape at 200px is a card. A
+white box with a border is a secondary button; without one it is a
+surface. Neither was visible before.
+
+### Fixed
+
+**The design system generator laid out over itself.** Variant grids were
+placed by column count without measuring whether the row fitted, so 14 of
+38 component sets overflowed the card holding them — Alert reached 2444px
+inside a 1320px section.
+
+**Text that was told a width kept its own.** Figma creates a text node
+auto-width, and setting it to fill is quietly ignored, so 23 layers across
+the file measured themselves from their own characters. NumberInput's
+value layer, created empty and filled in later by a component property,
+wrapped one glyph per line.
+
+**Alert's coloured edge did not match its card**, being sized before the
+card had any content and never clipped to its rounded corners. Toast drew
+the same edge with the same fault.
+
+**The uploader thumbnails and the dialog's intent badge rendered at full
+saturation**, which also hid the icon drawn on them in the same colour.
+
+**The plugin's name displayed as mojibake** in Figma's menu, and its
+build was never committed despite its README saying so, so a clone could
+not run it.
+
 ## 2.5.0
 
 ### Added

package/README.md

@@ -6,6 +6,10 @@ React components you own — styled, dependency-free, and machine-readable. Each
 component arrives in your project as source, with its stylesheet, and with a
 contract describing what it is and what can safely be done to it.
 
+It ships an **MCP server**, so Claude Code, Codex and Cursor can read that
+contract instead of guessing at it — and build a screen straight from a
+Figma design.
+
 ```bash
 npx @grampro/kit add DataGrid
 ```
@@ -92,15 +96,31 @@ In this repository:
 
 ## MCP server (beta)
 
-For agents that speak MCP, the catalogue is also served on demand:
+The catalogue, served to a coding agent on demand over the Model Context
+Protocol:
 
 ```bash
-claude mcp add grampro -- npx -y @grampro/kit mcp
+npx @grampro/kit mcp install
 ```
 
-It reads a Figma design, installs what it needs, answers what exists, each component's full contract, working examples, and
-whether the JSX an agent just wrote actually matches the component it used.
-No dependencies, no configuration. See `tools/mcp/README.md`.
+That configures **Claude Code** (`.mcp.json`), **Codex**
+(`.codex/config.toml`) and **Cursor** (`.cursor/mcp.json`) in one command,
+merging into whatever is already there.
+
+Its seven tools answer what components exist (`list_components`), what a
+component's props actually are (`get_component`), how it is used
+(`get_example`, `get_guidance`), what a Figma frame contains
+(`figma_frame`), and — the one that earns its place — whether the JSX an
+agent just wrote matches the real API (`validate_usage`).
+
+`install_component` copies what the design needs into your project, so an
+agent can go from a Figma link to a working screen without you installing
+anything first.
+
+No dependencies, and it starts in about the time an empty Node process
+takes. Full walkthrough, including a prompt to paste:
+[kit.gramproindia.com/mcp-server](https://kit.gramproindia.com/mcp-server).
+Details in [`tools/mcp/README.md`](tools/mcp/README.md).
 
 ## Agent skill
 

package/index.cjs

@@ -1190,7 +1190,7 @@ const validateComponents = (components, beta = false) => {
  * projects a week install this; breaking their scripts to tidy an argument
  * parser is not a trade worth making.
  */
-const COMMANDS = new Set(["add", "list", "skill", "passport", "mcp", "secret"]);
+const COMMANDS = new Set(["add", "list", "skill", "passport", "mcp", "secret", "design"]);
 
 /**
  * Flags that take a separate value, so the token after one is that value and
@@ -1297,6 +1297,7 @@ const main = async () => {
     .example("$0 mcp install", "Register the MCP server with every agent found")
     .example("$0 mcp install --for codex", "Only write the Codex config")
     .example("$0 secret set figma", "Store a Figma token in the OS credential store")
+    .example("$0 design ./design.json", "Split a whole-file Figma export into design/")
     .example("$0 -i", "Interactive selection")
     .help().argv;
 
@@ -1333,6 +1334,36 @@ const main = async () => {
     return;
   }
 
+  if (parsed && parsed.command === "design") {
+    const [file, dest] = parsed.operands;
+    if (!file) {
+      console.log(`Which export? Try: ${CLI_NAME} design ./design.json`);
+      console.log("");
+      console.log("Save one from Figma first: Grampro Kit -> Export all screens for an agent.");
+      return;
+    }
+    const { splitDesign } = require("./tools/mcp/design.cjs");
+    const result = splitDesign(file, dest || "design");
+    if (result.error) {
+      console.log(result.error);
+      process.exitCode = 1;
+      return;
+    }
+    const rel = path.relative(process.cwd(), result.dest) || result.dest;
+    console.log(`Wrote ${result.written.length} screen(s) to ${rel}/`);
+    for (const screen of result.written) {
+      const where = screen.page ? ` (${screen.page})` : "";
+      console.log(`  ${screen.file.padEnd(28)} ${screen.name}${where} — ${screen.nodes} nodes`);
+    }
+    console.log(`  index.json${" ".repeat(18)} the plan: every screen, shared theme`);
+    console.log("");
+    console.log(
+      `Point an agent at it: "read ${rel}/index.json and build these screens`
+        + ` with the grampro MCP server".`,
+    );
+    return;
+  }
+
   if (parsed) {
     if (parsed.command === "list") argv.list = true;
     if (parsed.command === "skill") argv.skill = true;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@grampro/kit",
-  "version": "2.5.0",
+  "version": "2.6.0",
   "description": "GramproKit \u2014 an agent-native UI runtime for React. Copy-in components you own, each publishing a contract that software can read.",
   "type": "module",
   "files": [

package/source/components/accordion/passport.json

@@ -10,7 +10,7 @@
     ]
   },
   "source": {
-    "libraryVersion": "2.5.0",
+    "libraryVersion": "2.6.0",
     "files": [
       "core/index.ts",
       "core/open.ts",

package/source/components/alert/passport.json

@@ -8,7 +8,7 @@
     ]
   },
   "source": {
-    "libraryVersion": "2.5.0",
+    "libraryVersion": "2.6.0",
     "files": [
       "core/index.ts",
       "core/live.ts",

package/source/components/avatar/passport.json

@@ -9,7 +9,7 @@
     ]
   },
   "source": {
-    "libraryVersion": "2.5.0",
+    "libraryVersion": "2.6.0",
     "files": [
       "core/identity.ts",
       "core/index.ts",

package/source/components/badge/passport.json

@@ -9,7 +9,7 @@
     ]
   },
   "source": {
-    "libraryVersion": "2.5.0",
+    "libraryVersion": "2.6.0",
     "files": [
       "core/count.ts",
       "core/index.ts",

package/source/components/breadcrumb/passport.json

@@ -8,7 +8,7 @@
     ]
   },
   "source": {
-    "libraryVersion": "2.5.0",
+    "libraryVersion": "2.6.0",
     "files": [
       "core/index.ts",
       "core/trail.ts",

package/source/components/button/passport.json

@@ -8,7 +8,7 @@
     ]
   },
   "source": {
-    "libraryVersion": "2.5.0",
+    "libraryVersion": "2.6.0",
     "files": [
       "core/index.ts",
       "core/state.ts",

package/source/components/card/passport.json

@@ -12,7 +12,7 @@
     ]
   },
   "source": {
-    "libraryVersion": "2.5.0",
+    "libraryVersion": "2.6.0",
     "files": [
       "core/index.ts",
       "core/trend.ts",

package/source/components/checkbox/passport.json

@@ -10,7 +10,7 @@
     ]
   },
   "source": {
-    "libraryVersion": "2.5.0",
+    "libraryVersion": "2.6.0",
     "files": [
       "core/group.ts",
       "core/index.ts",

package/source/components/combobox/passport.json

@@ -9,7 +9,7 @@
     ]
   },
   "source": {
-    "libraryVersion": "2.5.0",
+    "libraryVersion": "2.6.0",
     "files": [
       "core/filter.ts",
       "core/index.ts",

package/source/components/data-grid/passport.json

@@ -14,7 +14,7 @@
     ]
   },
   "source": {
-    "libraryVersion": "2.5.0",
+    "libraryVersion": "2.6.0",
     "files": [
       "agent/coerce.ts",
       "agent/contract.ts",

package/source/components/date-picker/passport.json

@@ -10,7 +10,7 @@
     ]
   },
   "source": {
-    "libraryVersion": "2.5.0",
+    "libraryVersion": "2.6.0",
     "files": [
       "core/calendar.ts",
       "core/format.ts",

package/source/components/dialog/passport.json

@@ -9,7 +9,7 @@
     ]
   },
   "source": {
-    "libraryVersion": "2.5.0",
+    "libraryVersion": "2.6.0",
     "files": [
       "core/api.ts",
       "core/dialog.ts",

package/source/components/file-uploader/passport.json

@@ -13,7 +13,7 @@
     ]
   },
   "source": {
-    "libraryVersion": "2.5.0",
+    "libraryVersion": "2.6.0",
     "files": [
       "core/format.ts",
       "core/index.ts",

package/source/components/input/passport.json

@@ -9,7 +9,7 @@
     ]
   },
   "source": {
-    "libraryVersion": "2.5.0",
+    "libraryVersion": "2.6.0",
     "files": [
       "core/count.ts",
       "core/index.ts",

package/source/components/menu/passport.json

@@ -16,7 +16,7 @@
     ]
   },
   "source": {
-    "libraryVersion": "2.5.0",
+    "libraryVersion": "2.6.0",
     "files": [
       "core/index.ts",
       "core/navigation.ts",

package/source/components/modal/passport.json

@@ -8,7 +8,7 @@
     ]
   },
   "source": {
-    "libraryVersion": "2.5.0",
+    "libraryVersion": "2.6.0",
     "files": [
       "core/dismiss.ts",
       "core/index.ts",

package/source/components/number-input/passport.json

@@ -8,7 +8,7 @@
     ]
   },
   "source": {
-    "libraryVersion": "2.5.0",
+    "libraryVersion": "2.6.0",
     "files": [
       "core/format.ts",
       "core/index.ts",

package/source/components/popover/passport.json

@@ -8,7 +8,7 @@
     ]
   },
   "source": {
-    "libraryVersion": "2.5.0",
+    "libraryVersion": "2.6.0",
     "files": [
       "core/index.ts",
       "core/types.ts",

package/source/components/progress/passport.json

@@ -9,7 +9,7 @@
     ]
   },
   "source": {
-    "libraryVersion": "2.5.0",
+    "libraryVersion": "2.6.0",
     "files": [
       "core/index.ts",
       "core/progress.ts",

package/source/components/radio-group/passport.json

@@ -10,7 +10,7 @@
     ]
   },
   "source": {
-    "libraryVersion": "2.5.0",
+    "libraryVersion": "2.6.0",
     "files": [
       "core/group.ts",
       "core/index.ts",

package/source/components/skeleton/passport.json

@@ -9,7 +9,7 @@
     ]
   },
   "source": {
-    "libraryVersion": "2.5.0",
+    "libraryVersion": "2.6.0",
     "files": [
       "core/index.ts",
       "core/lines.ts",

package/source/components/spinner/passport.json

@@ -8,7 +8,7 @@
     ]
   },
   "source": {
-    "libraryVersion": "2.5.0",
+    "libraryVersion": "2.6.0",
     "files": [
       "core/index.ts",
       "core/types.ts",

package/source/components/switch/passport.json

@@ -8,7 +8,7 @@
     ]
   },
   "source": {
-    "libraryVersion": "2.5.0",
+    "libraryVersion": "2.6.0",
     "files": [
       "core/index.ts",
       "core/toggle.ts",

package/source/components/tabs/passport.json

@@ -12,7 +12,7 @@
     ]
   },
   "source": {
-    "libraryVersion": "2.5.0",
+    "libraryVersion": "2.6.0",
     "files": [
       "core/index.ts",
       "core/navigation.ts",

package/source/components/textarea/passport.json

@@ -8,7 +8,7 @@
     ]
   },
   "source": {
-    "libraryVersion": "2.5.0",
+    "libraryVersion": "2.6.0",
     "files": [
       "core/count.ts",
       "core/index.ts",

package/source/components/toaster/passport.json

@@ -11,7 +11,7 @@
     ]
   },
   "source": {
-    "libraryVersion": "2.5.0",
+    "libraryVersion": "2.6.0",
     "files": [
       "core/api.ts",
       "core/index.ts",

package/source/components/tooltip/passport.json

@@ -8,7 +8,7 @@
     ]
   },
   "source": {
-    "libraryVersion": "2.5.0",
+    "libraryVersion": "2.6.0",
     "files": [
       "core/index.ts",
       "core/types.ts",

package/tools/mcp/README.md

@@ -108,7 +108,7 @@ document pasted into the prompt.
 | `get_component` | Props with types and allowed values, which are required, handler signatures, slots, states, composition rules |
 | `get_example` | Working usage from the component's README |
 | `get_guidance` | Authored notes on forms, overlays, the grid, pickers, styling, accessibility |
-| `figma_frame` | A design's structure, text, repeated regions and theme variables |
+| `figma_frame` | A design's structure, text, repeated regions and theme variables, from a `designFile` path, a pasted `design`, or a Figma `url` |
 | `install_component` | Copies components into the project being worked in |
 | `validate_usage` | Whether the JSX an agent wrote matches the passports |
 
@@ -125,9 +125,38 @@ invention, and this catches it:
   dismissible — not a prop of this component. Did you mean: onDismiss
 ```
 
+## A whole design at once
+
+In Figma, **Grampro Kit → Export all screens for an agent** walks every
+page and exports each top-level frame, with one set of theme values read
+across the whole design rather than guessed per frame. Save it, then:
+
+```bash
+npx @grampro/kit design ./design.json
+```
+
+```text
+Wrote 3 screen(s) to design/
+  purchase-orders.json         Purchase orders (Product) — 22 nodes
+  suppliers.json               Suppliers (Product) — 16 nodes
+  settings.json                Settings (Admin) — 12 nodes
+  index.json                   the plan: every screen, shared theme
+```
+
+A browser cannot write a directory and a plugin is an iframe, so the
+plugin hands over one file and the CLI does the filesystem work. Each
+screen is written in the shape a single-frame export has, so `figma_frame`
+reads one with `designFile` and no special case.
+
+`index.json` is the plan: every screen with its size, node count and
+repeated regions, plus the shared theme. Have an agent map regions to
+components from that and correct it before any code exists — a guess that
+`Action` is a Card rather than a Button costs one sentence there and five
+screens of rework later. Then build one screen at a time, validating each.
+
 ## From a Figma design
 
-Two routes, and the second needs no credentials.
+Three routes, and only the first needs credentials.
 
 **By URL.** Pass a `figma.com/design/...` link. Called with just the URL it
 lists the frames in the file; called again with `frame` it returns that
@@ -140,6 +169,12 @@ agent**, then pass the JSON as `design`. The plugin reads the scene graph
 directly, so this works on any file you can open, asks for no token, and
 never touches the REST API — which also means it cannot be rate limited.
 
+**By file.** Press **Save .json** in that panel and pass the path as
+`designFile`. Prefer this for anything but a small frame: a chat input
+caps at around fifty thousand characters, and a pasted export sits in the
+conversation twice — once as the argument, again inside the tool call —
+where a file appears only in the answer.
+
 Either way the answer is the same shape: the structure, the text, the
 regions whose names repeat — eight `Status cell` nodes are a column — and
 the `--gbs-*` variables the design's own colours and radii map onto.

package/tools/mcp/design.cjs

@@ -0,0 +1,154 @@
+/*
+ * `grampro-kit design <file>` — a whole-file Figma export, split into a folder.
+ *
+ * The plugin downloads one file because a browser cannot write a directory.
+ * Splitting it is filesystem work, which belongs in the CLI rather than in a
+ * plugin iframe, and it is what makes the result usable: an agent reads the
+ * index to plan, then opens one screen at a time, instead of loading every
+ * screen to build any of them.
+ *
+ * Each screen is written in the same shape a single-frame export has, so
+ * `figma_frame` reads one with no special case.
+ */
+"use strict";
+
+const fs = require("fs");
+const path = require("path");
+const { themeFrom } = require("./figma.cjs");
+
+/** A file name from a screen name: lowercase, dashes, nothing exotic. */
+const slug = (name) =>
+  String(name)
+    .toLowerCase()
+    .replace(/[^a-z0-9]+/g, "-")
+    .replace(/^-|-$/g, "") || "screen";
+
+/** Names a designer repeated are the ones that mean something. */
+function countNames(node, counts) {
+  counts.set(node.name, (counts.get(node.name) || 0) + 1);
+  for (const child of node.children || []) countNames(child, counts);
+}
+
+const repeatedIn = (nodes) => {
+  const counts = new Map();
+  for (const node of nodes) countNames(node, counts);
+  return [...counts.entries()]
+    .filter(([, n]) => n > 2)
+    .sort((a, b) => b[1] - a[1])
+    .slice(0, 12)
+    .map(([name, times]) => ({ name, times }));
+};
+
+/** Component instances found anywhere in a screen. */
+function componentsIn(nodes) {
+  const found = new Set();
+  const visit = (node) => {
+    if (node.component) found.add(node.component);
+    for (const child of node.children || []) visit(child);
+  };
+  for (const node of nodes) visit(node);
+  return [...found];
+}
+
+const countNodes = (nodes) =>
+  nodes.reduce((n, node) => n + 1 + countNodes(node.children || []), 0);
+
+/**
+ * Split an export into `dest`.
+ *
+ * Returns what it wrote rather than printing, so the CLI owns the words and
+ * this stays testable.
+ */
+function splitDesign(file, dest) {
+  const source = path.resolve(file);
+  if (!fs.existsSync(source)) return { error: `No file at ${source}.` };
+
+  let design;
+  try {
+    design = JSON.parse(fs.readFileSync(source, "utf8").replace(/^/, ""));
+  } catch (error) {
+    return { error: `${source} is not JSON: ${error.message}` };
+  }
+
+  /*
+   * A single-frame export is accepted too, as one screen. Someone who ran the
+   * wrong menu item should get a folder, not a lecture.
+   */
+  const screens = Array.isArray(design.screens)
+    ? design.screens
+    : Array.isArray(design.nodes)
+      ? [{ name: design.frame || "screen", page: "", nodes: design.nodes }]
+      : null;
+
+  if (!screens) {
+    return {
+      error:
+        "Expected the output of the Figma plugin's 'Export all screens for an agent' " +
+        "(or 'Export selection'). This file has neither `screens` nor `nodes`.",
+    };
+  }
+  if (screens.length === 0) return { error: "That export contains no screens." };
+
+  const out = path.resolve(dest);
+  fs.mkdirSync(out, { recursive: true });
+
+  const tokens = design.tokens || {};
+  const colours = new Map((tokens.colours || []).map((c) => [c.value, c.uses]));
+  const radii = new Map((tokens.radii || []).map((r) => [r.value, r.uses]));
+  const fontSizes = new Map((tokens.fontSizes || []).map((f) => [f.value, f.uses]));
+
+  const taken = new Set();
+  const written = [];
+
+  for (const screen of screens) {
+    // Two screens may share a name across pages; the second gets a suffix
+    // rather than quietly overwriting the first.
+    let name = slug(screen.name);
+    if (taken.has(name)) {
+      let n = 2;
+      while (taken.has(`${name}-${n}`)) n += 1;
+      name = `${name}-${n}`;
+    }
+    taken.add(name);
+
+    const fileName = `${name}.json`;
+    fs.writeFileSync(
+      path.join(out, fileName),
+      `${JSON.stringify({ frame: screen.name, nodes: screen.nodes, tokens }, null, 2)}\n`,
+      "utf8",
+    );
+
+    written.push({
+      name: screen.name,
+      page: screen.page || undefined,
+      file: fileName,
+      size: screen.size,
+      nodes: countNodes(screen.nodes),
+      repeatedRegions: repeatedIn(screen.nodes),
+      componentsNamed: componentsIn(screen.nodes),
+    });
+  }
+
+  /*
+   * The index is what an agent reads first: every screen, how big it is, the
+   * regions whose names repeat, and one theme for all of them. Enough to
+   * propose a component for each region before any code is written, which is
+   * where a wrong guess is cheap to correct.
+   */
+  const index = {
+    screens: written,
+    theme: themeFrom(colours, radii, fontSizes),
+    builtFromLibrary: written.some((s) => s.componentsNamed.length > 0),
+    howToUse:
+      "Read this index first and say which kit component each repeated region maps to, " +
+      "so the mapping can be corrected before any screen is built. Then take one screen " +
+      "at a time: figma_frame with designFile set to its file, get_component for each " +
+      "component before writing it, install_component for what is missing, and " +
+      "validate_usage on the JSX before moving to the next screen.",
+  };
+  fs.writeFileSync(path.join(out, "index.json"), `${JSON.stringify(index, null, 2)}\n`, "utf8");
+
+  return { dest: out, index, written };
+}
+
+module.exports = { splitDesign, slug };

package/tools/mcp/figma.cjs

@@ -323,11 +323,61 @@ function fromPluginExport(design) {
     builtFromLibrary: instances.length > 0,
     componentsNamed: [...new Set(instances)],
     tree: parsed.nodes,
+    /*
+     * The same closing instruction the URL route gives. Without it an agent
+     * arriving by the plugin — now the route the documentation leads with —
+     * got the tree and no word on what to do when nothing names a component,
+     * which is exactly when it starts approximating.
+     */
+    howToUse: instances.length
+      ? "This design uses component instances; `component` names the master for each."
+      : "This design was drawn without the component library, so nothing names a component directly. Use the region names and structure to decide which catalogue component each part is, then call get_component before writing it.",
   };
 }
 
-async function figmaFrame({ url, design, frame, depth }) {
-  // The export needs no token, so it is offered before one is demanded.
+/**
+ * The plugin's export, read from a file.
+ *
+ * Worth preferring over `design` for anything but a small frame, because a
+ * chat input caps at around fifty thousand characters and a whole screen
+ * passes that.
+ *
+ * It halves the context too, though not more: pasted, the export is in the
+ * conversation twice — once as the argument and again inside the tool call
+ * — where from a file it appears only in the answer. The tree still comes
+ * back in full, because the tree is what the agent builds from. The plugin
+ * has already condensed it; there is nothing further to drop that the
+ * screen does not need.
+ */
+function fromFile(file) {
+  let resolved;
+  try {
+    resolved = path.resolve(file);
+  } catch (error) {
+    return { error: `Not a usable path: ${file}` };
+  }
+  if (!fs.existsSync(resolved)) {
+    return {
+      error:
+        `No file at ${resolved}. Save the plugin's export first — in Figma, ` +
+        "Grampro Kit -> Export selection for an agent, then Save .json.",
+    };
+  }
+  let body;
+  try {
+    body = fs.readFileSync(resolved, "utf8");
+  } catch (error) {
+    return { error: `Could not read ${resolved}: ${error.message}` };
+  }
+  // A byte-order mark survives a round trip through some editors and is not
+  // valid JSON, so it goes before parsing rather than after a confusing throw.
+  return fromPluginExport(body.replace(/^\uFEFF/, ""));
+}
+
+async function figmaFrame({ url, design, designFile, frame, depth }) {
+  // Both export routes need no token, so they are offered before one is
+  // demanded. The file comes first: it is the one that scales.
+  if (designFile) return fromFile(designFile);
   if (design) return fromPluginExport(design);
 
   const token = figmaToken();

package/tools/mcp/server.cjs

@@ -371,7 +371,7 @@ const TOOLS = [
   {
     name: "figma_frame",
     description:
-      "BETA. Read a Figma design, from a URL (needs FIGMA_TOKEN) or from the plugin export (no token). Called with just a URL it lists the frames in the file; called with `frame` it returns that screen's structure, text, the repeated regions that indicate lists and tables, and the theme variables its colours and radii map onto. Needs FIGMA_TOKEN.",
+      "BETA. Read a Figma design: from a URL (needs FIGMA_TOKEN), from a file the kit's Figma plugin saved (`designFile`, no token, and the one to use for a whole screen), or from that export pasted in (`design`). Called with just a URL it lists the frames in the file; called with `frame` it returns that screen's structure, text, the repeated regions that indicate lists and tables, and the theme variables its colours and radii map onto.",
     inputSchema: {
       type: "object",
       properties: {
@@ -379,7 +379,12 @@ const TOOLS = [
         design: {
           type: "string",
           description:
-            "Alternative to url, needing no token: JSON from the kit's Figma plugin, 'Export selection for an agent'.",
+            "Alternative to url, needing no token: JSON from the kit's Figma plugin, 'Export selection for an agent'. For anything but a small frame, prefer designFile.",
+        },
+        designFile: {
+          type: "string",
+          description:
+            "Path to a .json saved by the plugin's 'Save .json' button. Preferred over `design`: the file is read here, so the raw export never passes through the conversation.",
         },
         frame: { type: "string", description: "Which frame to read, from the listing." },
         depth: { type: "number", description: "How deep to descend. Lower it if the payload is large." },