figmatk 0.2.6 → 0.3.0

package/.claude-plugin/marketplace.json

@@ -13,7 +13,7 @@
     {
       "name": "figmatk",
       "description": "Swiss Army Knife for Figma Files (.deck)",
-      "version": "0.2.6",
+      "version": "0.3.0",
       "author": {
         "name": "FigmaTK Contributors"
       },

package/.claude-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "figmatk",
-  "version": "0.2.6",
+  "version": "0.3.0",
   "description": "Create and edit Figma Slides .deck files programmatically — no Figma API required",
   "author": {
     "name": "FigmaTK Contributors"

package/lib/template-deck.mjs

@@ -0,0 +1,218 @@
+/**
+ * template-deck — Clone slides from a Figma template and populate with content.
+ *
+ * Template decks use MODULE > SLIDE > (TEXT, FRAME, ...) structure.
+ * Unlike generated decks, text is set directly on child nodes — not via symbolOverrides.
+ */
+import { FigDeck } from './fig-deck.mjs';
+import { nid, removeNode } from './node-helpers.mjs';
+import { deepClone } from './deep-clone.mjs';
+
+/**
+ * Inspect a template deck and return available layout slots.
+ * Returns an array of { slideId, name, textFields: [{ nodeId, name }] }
+ */
+export async function listTemplateLayouts(templatePath) {
+  const deck = await FigDeck.fromDeckFile(templatePath);
+  const layouts = [];
+
+  for (const slide of deck.getActiveSlides()) {
+    const id = nid(slide);
+    const textFields = [];
+    const imagePlaceholders = [];
+
+    deck.walkTree(id, (node) => {
+      if (node.type === 'TEXT' && node.name && node.textData?.characters) {
+        textFields.push({ nodeId: nid(node), name: node.name, preview: node.textData.characters.slice(0, 80) });
+      }
+      // SHAPE_WITH_TEXT: text lives in nodeGenerationData.overrides[n].textData
+      if (node.type === 'SHAPE_WITH_TEXT' && node.nodeGenerationData?.overrides) {
+        for (const ov of node.nodeGenerationData.overrides) {
+          if (ov.textData?.characters) {
+            const preview = ov.textData.characters.trim();
+            // Use #nodeId as key so createFromTemplate can target this specific field
+            textFields.push({ nodeId: nid(node), name: `#${nid(node)}`, preview });
+          }
+        }
+      }
+      // Detect image placeholder areas: frames/shapes with IMAGE fill, or large empty frames
+      const hasImageFill = node.fillPaints?.some(f => f.type === 'IMAGE');
+      const isLargeFrame = (node.type === 'FRAME' || node.type === 'ROUNDED_RECTANGLE')
+        && node.size?.x > 100 && node.size?.y > 100
+        && deck.getChildren(nid(node)).filter(c => c.type !== 'FRAME').length === 0;
+      if (hasImageFill || isLargeFrame) {
+        imagePlaceholders.push({
+          nodeId: nid(node),
+          type: node.type,
+          width: Math.round(node.size?.x ?? 0),
+          height: Math.round(node.size?.y ?? 0),
+          hasCurrentImage: hasImageFill,
+        });
+      }
+    });
+
+    layouts.push({ slideId: id, name: slide.name, textFields, imagePlaceholders });
+  }
+
+  return layouts;
+}
+
+/**
+ * Create a new deck from a template by cherry-picking and populating slides.
+ *
+ * @param {string} templatePath  - Path to source .deck file
+ * @param {string} outputPath    - Path to write output .deck file
+ * @param {Array}  slideDefs     - [{ slideId: '1:74', text: { 'Title': 'Hello', 'Body 1': '...' } }]
+ * @returns {number} bytes written
+ */
+export async function createFromTemplate(templatePath, outputPath, slideDefs) {
+  const deck = await FigDeck.fromDeckFile(templatePath);
+
+  // Record original MODULE/SLIDE IDs to remove after cloning
+  const originalSlideIds = deck.getActiveSlides().map(s => nid(s));
+
+  // Find SLIDE_ROW id (parent of MODULEs)
+  const slideRowNode = deck.message.nodeChanges.find(n => n.type === 'SLIDE_ROW');
+  if (!slideRowNode) throw new Error('No SLIDE_ROW found in template');
+  const slideRowId = nid(slideRowNode);
+
+  let nextId = deck.maxLocalID() + 1;
+  const SESSION = 200; // fresh session ID for cloned nodes
+
+  for (let defIdx = 0; defIdx < slideDefs.length; defIdx++) {
+    const { slideId, text = {} } = slideDefs[defIdx];
+
+    // Find the source SLIDE node
+    const sourceSlide = deck.getNode(slideId);
+    if (!sourceSlide) throw new Error(`Slide not found: ${slideId}`);
+
+    // Find the parent MODULE (if present)
+    const parentModuleId = sourceSlide.parentIndex?.guid
+      ? `${sourceSlide.parentIndex.guid.sessionID}:${sourceSlide.parentIndex.guid.localID}`
+      : null;
+    const sourceModule = parentModuleId ? deck.getNode(parentModuleId) : null;
+
+    // Collect all nodes in the subtree to clone (MODULE + SLIDE + all descendants)
+    const rootId = sourceModule ? nid(sourceModule) : slideId;
+    const subtreeNodes = [];
+    deck.walkTree(rootId, (node) => subtreeNodes.push(node));
+
+    // Build ID remap table: old "s:l" → new { sessionID, localID }
+    const idMap = new Map();
+    for (const node of subtreeNodes) {
+      const oldId = nid(node);
+      if (oldId) idMap.set(oldId, { sessionID: SESSION, localID: nextId++ });
+    }
+
+    // Deep-clone each node with remapped IDs
+    const clonedNodes = subtreeNodes.map(node => {
+      const clone = deepClone(node);
+
+      // Remap own guid
+      const newGuid = idMap.get(nid(node));
+      if (newGuid) clone.guid = newGuid;
+
+      // Remap parentIndex.guid if it's within the subtree
+      if (clone.parentIndex?.guid) {
+        const pid = `${clone.parentIndex.guid.sessionID}:${clone.parentIndex.guid.localID}`;
+        const remapped = idMap.get(pid);
+        if (remapped) {
+          clone.parentIndex = { ...clone.parentIndex, guid: remapped };
+        } else if (pid === slideRowId || pid === parentModuleId) {
+          // Root node — attach to SLIDE_ROW
+          clone.parentIndex = {
+            guid: { sessionID: slideRowNode.guid.sessionID, localID: slideRowNode.guid.localID },
+            position: String.fromCharCode(0x21 + (originalSlideIds.length + defIdx)),
+          };
+        }
+      }
+
+      clone.phase = 'CREATED';
+      delete clone.slideThumbnailHash;
+      delete clone.editInfo;
+      delete clone.prototypeInteractions;
+
+      return clone;
+    });
+
+    // Apply text overrides: find TEXT nodes by name, set characters
+    const clonedSlideGuid = idMap.get(slideId);
+    const clonedSlideId = clonedSlideGuid
+      ? `${clonedSlideGuid.sessionID}:${clonedSlideGuid.localID}`
+      : null;
+
+    for (const clone of clonedNodes) {
+      // TEXT nodes — matched by node name
+      if (clone.type === 'TEXT' && clone.name && text[clone.name] !== undefined) {
+        const chars = text[clone.name] || ' ';
+        if (!clone.textData) clone.textData = {};
+        clone.textData.characters = chars;
+        clone.textData.lines = chars.split('\n').map(() => ({
+          lineType: 'PLAIN', styleId: 0, indentationLevel: 0,
+          sourceDirectionality: 'AUTO', listStartOffset: 0, isFirstLineOfList: false,
+        }));
+        delete clone.derivedTextData;
+      }
+
+      // SHAPE_WITH_TEXT nodes — matched by #nodeId key (original ID before remapping)
+      if (clone.type === 'SHAPE_WITH_TEXT' && clone.nodeGenerationData?.overrides) {
+        // Find original node ID (before remapping) by reverse-looking up from idMap
+        const origId = [...idMap.entries()].find(
+          ([, v]) => v.sessionID === clone.guid.sessionID && v.localID === clone.guid.localID
+        )?.[0];
+        const key = origId ? `#${origId}` : null;
+        if (key && text[key] !== undefined) {
+          const chars = text[key] || ' ';
+          for (const ov of clone.nodeGenerationData.overrides) {
+            if (ov.textData?.characters !== undefined) {
+              ov.textData.characters = chars;
+              ov.textData.lines = chars.split('\n').map(() => ({
+                lineType: 'PLAIN', styleId: 0, indentationLevel: 0,
+                sourceDirectionality: 'AUTO', listStartOffset: 0, isFirstLineOfList: false,
+              }));
+            }
+          }
+          delete clone.derivedImmutableFrameData;
+        }
+      }
+    }
+
+    deck.message.nodeChanges.push(...clonedNodes);
+  }
+
+  // Rebuild maps so we can walk the original slide subtrees
+  deck.rebuildMaps();
+
+  // Collect all node IDs in original slide subtrees to physically remove from nodeChanges.
+  // phase=REMOVED is NOT used here — Figma ignores it for TEXT/FRAME nodes.
+  const pruneIds = new Set();
+
+  function collectSubtree(id) {
+    if (pruneIds.has(id)) return;
+    pruneIds.add(id);
+    for (const child of deck.getChildren(id)) {
+      collectSubtree(nid(child));
+    }
+  }
+
+  for (const id of originalSlideIds) {
+    const slide = deck.getNode(id);
+    if (!slide) continue;
+
+    if (slide.parentIndex?.guid) {
+      const modId = `${slide.parentIndex.guid.sessionID}:${slide.parentIndex.guid.localID}`;
+      const mod = deck.getNode(modId);
+      if (mod?.type === 'MODULE') { collectSubtree(modId); continue; }
+    }
+    collectSubtree(id);
+  }
+
+  // Filter them out entirely — absent nodes render as non-existent in Figma
+  deck.message.nodeChanges = deck.message.nodeChanges.filter(n => {
+    const id = nid(n);
+    return !id || !pruneIds.has(id);
+  });
+
+  deck.rebuildMaps();
+  return deck.saveDeck(outputPath);
+}

package/mcp-server.mjs

@@ -7,6 +7,7 @@ import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js'
 import { z } from 'zod';
 import { FigDeck } from './lib/fig-deck.mjs';
 import { Deck } from './lib/api.mjs';
+import { listTemplateLayouts, createFromTemplate } from './lib/template-deck.mjs';
 import { nid, ov, nestedOv, removeNode, parseId, positionChar } from './lib/node-helpers.mjs';
 import { imageOv, hexToHash, hashToHex } from './lib/image-helpers.mjs';
 import { deepClone } from './lib/deep-clone.mjs';
@@ -336,6 +337,41 @@ server.tool(
   }
 );
 
+// ── figmatk_list_template_layouts ────────────────────────────────────────
+server.tool(
+  'figmatk_list_template_layouts',
+  'Inspect a Figma .deck template and return available slide layouts with their text field names. Call this first before figmatk_create_from_template.',
+  {
+    template: z.string().describe('Path to the .deck template file'),
+  },
+  async ({ template }) => {
+    const layouts = await listTemplateLayouts(template);
+    const lines = layouts.map(l => {
+      const fields = l.textFields.map(f => `    - "${f.name}" (${f.nodeId}): "${f.preview}"`).join('\n');
+      return `Slide "${l.name}" [${l.slideId}]\n${fields || '    (no text fields)'}`;
+    });
+    return { content: [{ type: 'text', text: lines.join('\n\n') }] };
+  }
+);
+
+// ── figmatk_create_from_template ─────────────────────────────────────────
+server.tool(
+  'figmatk_create_from_template',
+  'Create a new Figma Slides deck by cherry-picking layouts from a template .deck file and populating them with content. Preserves all template colors, fonts, and styling.',
+  {
+    template: z.string().describe('Path to the source .deck template file'),
+    output:   z.string().describe('Output path for the new .deck file (use /tmp/)'),
+    slides: z.array(z.object({
+      slideId: z.string().describe('Slide ID from figmatk_list_template_layouts (e.g. "1:74")'),
+      text:    z.record(z.string()).optional().describe('Map of text field name → value (e.g. { "Title": "My Company", "Body 1": "..." })'),
+    })).describe('Ordered list of slides to include, each referencing a template layout'),
+  },
+  async ({ template, output, slides }) => {
+    const bytes = await createFromTemplate(template, output, slides);
+    return { content: [{ type: 'text', text: `Created ${output} — ${slides.length} slides (${bytes} bytes). Open in Figma Desktop.` }] };
+  }
+);
+
 // ── Start server ────────────────────────────────────────────────────────
 const transport = new StdioServerTransport();
 await server.connect(transport);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "figmatk",
-  "version": "0.2.6",
+  "version": "0.3.0",
   "description": "Figma Toolkit — Swiss-army knife CLI for Figma .deck and .fig files",
   "type": "module",
   "bin": {

package/skills/figma-slides-creator/SKILL.md

@@ -6,7 +6,7 @@ description: >
   clone or remove slides, or produce a .deck file for Figma Slides.
   Powered by FigmaTK under the hood.
 metadata:
-  version: "0.2.6"
+  version: "0.3.0"
 ---
 
 # Figma Slides Creator
@@ -23,7 +23,8 @@ To let the user view the result: tell them to **open the file in Figma Desktop**
 
 | Task | Approach |
 |------|----------|
-| Create a new deck from scratch | **`figmatk_create_deck` MCP tool** — no npm install needed |
+| Create from scratch | **Path A** — `figmatk_create_deck` MCP tool |
+| Create from a `.deck` template | **Path B** — `figmatk_list_template_layouts` + `figmatk_create_from_template` |
 | Edit text or images in an existing deck | `figmatk_update_text`, `figmatk_insert_image` |
 | Clone, remove, or restructure slides | `figmatk_clone_slide`, `figmatk_remove_slide` |
 | Inspect structure or read content | `figmatk_inspect`, `figmatk_list_text` |
@@ -36,7 +37,45 @@ To let the user view the result: tell them to **open the file in Figma Desktop**
 
 ---
 
-## Path A — Create from Scratch (MCP tool — preferred)
+## Path B — Create from a Template (preferred when user provides a .deck file)
+
+Use this path when the user provides a `.deck` template file. The output deck inherits all fonts, colors, spacing, and visual design from the template verbatim.
+
+### Step 1 — Inspect the template
+
+```
+figmatk_list_template_layouts("/path/to/template.deck")
+```
+
+Returns a catalog of all available slide layouts. Each entry includes:
+- `slideId` — the ID to reference this layout
+- Text fields — editable TEXT nodes with their names and current content
+- Image placeholders — FRAME nodes with IMAGE fill (these need a real image)
+
+**Read the catalog carefully before picking layouts:**
+- Match each slide's purpose to your content (the existing text in the template is a strong hint — e.g. "Use this slide to introduce the big problem" → use for your problem statement)
+- Slides with image placeholders need an appropriate image — the surrounding text should describe what's shown in that image
+- Slides with `SHAPE_WITH_TEXT` pill labels (MONTH XX YEAR, TAGLINE, CONFIDENTIAL) cannot be changed programmatically — tell the user to update those in Figma
+
+### Step 2 — Create the deck
+
+```
+figmatk_create_from_template({
+  template: "/path/to/template.deck",
+  output: "/tmp/my-deck.deck",
+  slides: [
+    { slideId: "1:74",  text: { "Title": "My Company" } },
+    { slideId: "1:112", text: { "Header 1": "The problem.", "Body 1": "Description here." } },
+    { slideId: "1:643", text: { "Thank you": "Thank you!" } }
+  ]
+})
+```
+
+Only pass text fields that exist in the layout's catalog — extra fields are silently ignored.
+
+---
+
+## Path A — Create from Scratch (MCP tool — no template)
 
 **Always use this path.** No npm install, no scripts, no workspace setup.
 
@@ -289,7 +328,7 @@ Every slide needs at least **one visual element** — shape, image, SVG, or tabl
 - Centre body text
 - Use accent lines under slide titles (hallmark of AI-generated slides)
 - Text-only slides
-- Low-contrast text against background
+- Low-contrast text against background — **match image tone to slide palette**: dark/moody images on light-background slides make text unreadable; pick a bright image or switch to a dark-background layout
 - Skip the closing slide — it makes the deck feel unfinished
 - Put long paragraphs in body/caption fields — text overflows the container