@grampro/kit 2.5.0 → 2.6.1

package/CHANGELOG.md

@@ -1,5 +1,143 @@
 # Changelog
 
+## 2.6.1
+
+### Changed
+
+**A screen costs about half what it did to read.** Measured on a real
+purchase-orders design: 42.9 KB to 23.9 KB, roughly 13,300 tokens to
+7,400.
+
+Eight table rows exported as eight sibling subtrees of identical shape
+whose text differed — 48% of that screen was the same row said seven
+more times. The first is now given in full, because the agent builds from
+its shape, and the rest become `repeatedText`: one array of strings per
+row, which is closer to what a DataGrid's `data` prop wants than the
+subtrees were.
+
+Runs are matched on structure rather than appearance. Keyed on style, the
+rows never matched at all: a striped table alternates its background, so
+every consecutive pair looked like a different shape and nothing
+collapsed. Where the fills do vary across a run they come back as
+`repeatedFills`, which is how the striping and the per-status badge
+colours stay legible.
+
+Only runs of three or more collapse, and only where there is depth to
+save: two of a thing is a pair, not a list, and a row of labels has
+nothing inside it worth folding.
+
+### Fixed
+
+**`depth` is honoured on the plugin and file routes.** The tool has always
+offered it — "Lower it if the payload is large" — and only ever applied
+it to a design fetched from a URL. A caller who read the schema and
+lowered it to cut a large payload got the large payload back. The same
+screen at `depth: 3` is now 3.5 KB, and what was dropped says so rather
+than going quiet.
+
+**Selecting several frames exports several screens.** It used to produce
+one pseudo-frame called "3 selected nodes" holding all of them, which
+`design` then wrote as a single file under that name — a folder whose
+whole point is one file per screen, with one file for three. The screens
+were in there, but nothing said where one ended and the next began.
+
+A selection of several frames now produces the same shape the whole-file
+export does, so the split, the index and `figma_frame` treat them
+identically. One frame selected is still one screen.
+
+This is also the scoping the all-screens command lacks: a file with forty
+frames in it need not be exported entire to build two of them. Select the
+screens you want and export those.
+
+
+## 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.1",
   "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.1",
     "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.1",
     "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.1",
     "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.1",
     "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.1",
     "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.1",
     "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.1",
     "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.1",
     "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.1",
     "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.1",
     "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.1",
     "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.1",
     "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.1",
     "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.1",
     "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.1",
     "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.1",
     "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.1",
     "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.1",
     "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.1",
     "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.1",
     "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.1",
     "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.1",
     "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.1",
     "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.1",
     "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.1",
     "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.1",
     "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.1",
     "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

@@ -265,6 +265,123 @@ function repeatedNames(node, counts) {
 
 // ------------------------------------------------------------------- tool
 
+/*
+ * Repetition is the point, and sending it in full is the waste.
+ *
+ * A table of eight rows exports as eight siblings of identical shape whose
+ * text differs. The agent needs the shape once and the values eight times;
+ * on a real screen the other seven copies were 48% of the payload.
+ */
+
+/**
+ * A node's structure: names, types, nesting and layout.
+ *
+ * Style is deliberately not part of it. Table rows are zebra-striped, so
+ * consecutive rows differ by a background colour and nothing else — keying
+ * on style meant every pair looked distinct and no run was ever found. The
+ * variation is reported instead of being treated as a different shape.
+ */
+function shapeKey(node) {
+  return JSON.stringify([
+    node.name,
+    node.type,
+    node.layout,
+    (node.children || []).map(shapeKey),
+  ]);
+}
+
+/** The fills down a subtree, so a collapsed run can say how they alternate. */
+function fillsOf(node, into = []) {
+  if (node.style && node.style.fill) into.push(node.style.fill);
+  for (const child of node.children || []) fillsOf(child, into);
+  return into;
+}
+
+/** Every string in a subtree, in order: what one row of a table actually says. */
+function textsOf(node, into = []) {
+  if (node.text) into.push(node.text);
+  for (const child of node.children || []) textsOf(child, into);
+  return into;
+}
+
+/** How many levels deep a subtree goes. */
+const depthOf = (node) =>
+  1 + Math.max(0, ...(node.children || []).map(depthOf));
+
+/**
+ * Collapse runs of same-shaped siblings, and trim to `limit` levels.
+ *
+ * Only runs of three or more are collapsed: two of a thing is a pair, not a
+ * list, and the saving would not pay for the indirection. A run that is only
+ * one level deep is left alone too — there is nothing to save in a row of
+ * labels, and collapsing it would cost the agent the order they appear in.
+ */
+function condenseTree(nodes, limit, level = 1) {
+  const out = [];
+  let i = 0;
+
+  while (i < nodes.length) {
+    const node = nodes[i];
+    const key = shapeKey(node);
+    let run = 1;
+    while (i + run < nodes.length && shapeKey(nodes[i + run]) === key) run += 1;
+
+    const worthIt = run >= 3 && depthOf(node) > 1;
+    const trimmed = trim(node, limit, level);
+
+    if (!worthIt) {
+      for (let n = 0; n < run; n += 1) out.push(trim(nodes[i + n], limit, level));
+      i += run;
+      continue;
+    }
+
+    /*
+     * The first in full, then the rest as what they say. `repeats` is the
+     * count including this one, so an agent reading only this node knows how
+     * many rows to render.
+     */
+    const rest = [];
+    for (let n = 1; n < run; n += 1) rest.push(textsOf(nodes[i + n]));
+
+    /*
+     * Fills are reported only where they actually differ across the run.
+     * Where they do it is nearly always zebra striping, and two colours
+     * said once is the whole of it.
+     */
+    const fills = [];
+    for (let n = 0; n < run; n += 1) fills.push(fillsOf(nodes[i + n]).join(","));
+    const varies = new Set(fills).size > 1;
+
+    out.push({
+      ...trimmed,
+      repeats: run,
+      repeatsNote:
+        `${run} siblings share this structure. The first is given in full; ` +
+        "`repeatedText` holds what each of the others says, in the same order " +
+        "as the text in this one." +
+        (varies ? " `repeatedFills` gives each one's colours, which alternate." : ""),
+      repeatedText: rest,
+      ...(varies ? { repeatedFills: fills.map((f) => f.split(",")) } : {}),
+    });
+    i += run;
+  }
+
+  return out;
+}
+
+/** Drop everything below `limit` levels, saying what was dropped. */
+function trim(node, limit, level) {
+  if (!node.children || node.children.length === 0) return node;
+  if (level >= limit) {
+    const inside = node.children.reduce(
+      (n, child) => n + 1 + (child.children ? child.children.length : 0),
+      0,
+    );
+    const { children, ...rest } = node;
+    return { ...rest, truncated: `${inside}+ nodes below this, not shown` };
+  }
+  return { ...node, children: condenseTree(node.children, limit, level + 1) };
+}
 /*
  * A selection exported by the plugin, which has already done the condensing
  * inside Figma. The work left is the part that needs no file access: giving
@@ -273,7 +390,7 @@ function repeatedNames(node, counts) {
  * This is the path for anyone who would rather not hold an API token, and
  * for files the token cannot reach.
  */
-function fromPluginExport(design) {
+function fromPluginExport(design, depth) {
   let parsed;
   try {
     parsed = typeof design === "string" ? JSON.parse(design) : design;
@@ -311,6 +428,14 @@ function fromPluginExport(design) {
   };
   for (const node of parsed.nodes) findInstances(node);
 
+  /*
+   * `depth` was offered on this tool and only ever honoured for a URL. A
+   * caller who read the schema and lowered it to cut a large payload got
+   * the large payload back.
+   */
+  const limit = Math.min(Number(depth) || MAX_DEPTH, MAX_DEPTH);
+  const tree = condenseTree(parsed.nodes, limit);
+
   return {
     source: "figma plugin export",
     frame: parsed.frame,
@@ -322,13 +447,63 @@ function fromPluginExport(design) {
       .map(([name, n]) => ({ name, times: n })),
     builtFromLibrary: instances.length > 0,
     componentsNamed: [...new Set(instances)],
-    tree: parsed.nodes,
+    tree,
+    /*
+     * 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.
-  if (design) return fromPluginExport(design);
+/**
+ * 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, depth) {
+  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/, ""), depth);
+}
+
+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, depth);
+  if (design) return fromPluginExport(design, depth);
 
   const token = figmaToken();
   if (!token) {

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." },