figmatk 0.3.1 → 0.3.8

package/lib/template-deck.mjs

@@ -298,13 +298,41 @@ function describeLayout(deck, layout, row) {
   };
 }
 
+/**
+ * Walk the node tree like deck.walkTree, but follow INSTANCE → SYMBOL links.
+ * When an INSTANCE node is encountered, its referenced SYMBOL's children are
+ * also walked so that slots inside published template components are discovered.
+ */
+function walkTreeThroughInstances(deck, rootId, visitor, depth = 0, visited = new Set()) {
+  if (!rootId || visited.has(rootId)) return;
+  visited.add(rootId);
+
+  const node = deck.getNode(rootId);
+  if (!node || node.phase === 'REMOVED') return;
+  visitor(node, depth);
+
+  // Follow INSTANCE → SYMBOL: walk the SYMBOL's children
+  if (node.type === 'INSTANCE' && node.symbolData?.symbolID) {
+    const sid = node.symbolData.symbolID;
+    const symNid = `${sid.sessionID}:${sid.localID}`;
+    for (const child of deck.getChildren(symNid)) {
+      walkTreeThroughInstances(deck, nid(child), visitor, depth + 1, visited);
+    }
+  }
+
+  // Walk direct children
+  for (const child of deck.getChildren(rootId)) {
+    walkTreeThroughInstances(deck, nid(child), visitor, depth + 1, visited);
+  }
+}
+
 function discoverSlots(deck, rootId) {
   const explicitTextSlots = [];
   const explicitImageSlots = [];
   const fallbackTextSlots = [];
   const fallbackImageSlots = [];
 
-  deck.walkTree(rootId, node => {
+  walkTreeThroughInstances(deck, rootId, node => {
     const textSlotName = parsePrefixedName(node.name, TEXT_SLOT_PREFIX);
     if (textSlotName) {
       const slot = describeTextSlot(node, textSlotName, 'explicit');

package/manifest.json

@@ -0,0 +1,21 @@
+{
+  "manifest_version": "0.2",
+  "name": "figmatk",
+  "version": "0.3.3",
+  "description": "Create and edit Figma Slides .deck files programmatically - no Figma API required",
+  "author": {
+    "name": "FigmaTK Contributors"
+  },
+  "server": {
+    "type": "node",
+    "entry_point": "mcp-server.mjs",
+    "mcp_config": {
+      "command": "node",
+      "args": [
+        "${__dirname}/mcp-server.mjs"
+      ],
+      "env": {}
+    }
+  },
+  "license": "MIT"
+}

package/mcp-server.mjs

@@ -5,8 +5,12 @@
 import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
 import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
 import { z } from 'zod';
+import packageJson from './package.json' with { type: 'json' };
 import { FigDeck } from './lib/fig-deck.mjs';
 import { Deck } from './lib/api.mjs';
+import { slideToSvg } from './lib/rasterizer/svg-builder.mjs';
+import { svgToPng } from './lib/rasterizer/deck-rasterizer.mjs';
+import { resolveFonts } from './lib/rasterizer/font-resolver.mjs';
 import {
   annotateTemplateLayout,
   createDraftTemplate,
@@ -20,7 +24,7 @@ import { deepClone } from './lib/deep-clone.mjs';
 
 const server = new McpServer({
   name: 'figmatk',
-  version: '0.0.3',
+  version: packageJson.version,
 });
 
 // ── inspect ─────────────────────────────────────────────────────────────
@@ -435,7 +439,7 @@ server.tool(
 
 server.tool(
   'figmatk_list_template_layouts',
-  'Inspect a template or draft template .deck file and return available layouts with explicit text/image slot metadata. Call this before figmatk_create_from_template or figmatk_annotate_template_layout.',
+  'Inspect a template or draft template .deck file and return a layout library catalog with explicit text/image slot metadata. Use this to inventory candidate layouts, classify what each layout is for, and choose a subset before calling figmatk_create_from_template. Do not edit, remove, or reorder the source template as a way to build the output deck.',
   {
     template: z.string().describe('Path to the .deck template file'),
   },
@@ -459,7 +463,7 @@ server.tool(
 // ── figmatk_create_from_template ─────────────────────────────────────────
 server.tool(
   'figmatk_create_from_template',
-  'Create a new Figma Slides deck by cherry-picking layouts from a draft, published, or publish-like template .deck file and populating explicit text/image slots. Preserves colors, fonts, internal assets, and special nodes.',
+  'Create a new Figma Slides deck by selecting any ordered subset of layouts from a draft, published, or publish-like template .deck file and populating explicit text/image slots. The slides array defines the output order. This clones the chosen layouts into a new deck; do not remove, reorder, or mutate the source template to build the result. Works with flat-frame template slides as well as module-backed layouts, and preserves colors, fonts, internal assets, and special nodes.',
   {
     template: z.string().describe('Path to the source .deck template file'),
     output:   z.string().describe('Output path for the new .deck file (use /tmp/)'),
@@ -467,7 +471,7 @@ server.tool(
       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 slot/name/nodeId -> value (e.g. { "title": "My Company" })'),
       images:  z.record(z.string()).optional().describe('Map of image slot/name/nodeId -> absolute image path (e.g. { "hero_image": "/tmp/photo.jpg" })'),
-    })).describe('Ordered list of slides to include, each referencing a template layout'),
+    })).describe('Ordered subset of template layouts to include in the output deck. The array order becomes the output deck order, regardless of the template\'s original order.'),
   },
   async ({ template, output, slides }) => {
     const bytes = await createFromTemplate(template, output, slides);
@@ -475,6 +479,63 @@ server.tool(
   }
 );
 
+// ── render-slide ───────────────────────────────────────────────────────
+server.tool(
+  'figmatk_render_slide',
+  'Render a slide from a .deck file to an image. Without output path, returns inline WebP for visual QA. With output path, saves full PNG. Default is 1920×1080; use width (pixels) or scale (e.g. "50%") to resize.',
+  {
+    path: z.string().describe('Path to .deck file'),
+    slide: z.number().int().min(1).describe('Slide number (1-based)'),
+    output: z.string().optional().describe('Optional output path to save the PNG file (full resolution)'),
+    width: z.number().int().optional().describe('Output width in pixels (height scales proportionally)'),
+    scale: z.string().optional().describe('Scale as percentage, e.g. "50%" or "25%"'),
+  },
+  async ({ path, slide, output, width, scale }) => {
+    const deck = await FigDeck.fromDeckFile(path);
+    await resolveFonts(deck, { quiet: true });
+    const slides = deck.getActiveSlides();
+
+    if (slide > slides.length) {
+      return { content: [{ type: 'text', text: `Slide ${slide} does not exist — deck has ${slides.length} slides` }] };
+    }
+
+    const svg = slideToSvg(deck, slides[slide - 1]);
+
+    // Build render options
+    const renderOpts = {};
+    if (width) {
+      renderOpts.width = width;
+    } else if (scale) {
+      const pct = parseFloat(scale.replace('%', ''));
+      if (!isNaN(pct) && pct > 0) renderOpts.scale = pct / 100;
+    }
+
+    const png = await svgToPng(svg, renderOpts);
+    const buf = Buffer.from(png);
+
+    if (output) {
+      const { writeFileSync } = await import('fs');
+      writeFileSync(output, buf);
+      return { content: [{ type: 'text', text: `Rendered slide ${slide} → ${output} (${buf.length} bytes)` }] };
+    }
+
+    // For inline display: convert to WebP (much smaller) via sharp
+    // Default to width=800 if no size specified to stay under MCP 1MB limit
+    const sharp = (await import('sharp')).default;
+    let img = sharp(buf);
+    if (!width && !scale) img = img.resize(800);
+    const webp = await img.webp({ quality: 80 }).toBuffer();
+
+    return {
+      content: [{
+        type: 'image',
+        data: webp.toString('base64'),
+        mimeType: 'image/webp',
+      }],
+    };
+  }
+);
+
 // ── Start server ────────────────────────────────────────────────────────
 const transport = new StdioServerTransport();
 await server.connect(transport);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "figmatk",
-  "version": "0.3.1",
+  "version": "0.3.8",
   "description": "Figma Toolkit — Swiss-army knife CLI for Figma .deck and .fig files",
   "type": "module",
   "bin": {
@@ -17,6 +17,7 @@
   "files": [
     "cli.mjs",
     "mcp-server.mjs",
+    "manifest.json",
     "lib/",
     "commands/",
     "skills/",
@@ -26,7 +27,12 @@
     "README.md"
   ],
   "scripts": {
-    "start": "node cli.mjs"
+    "start": "node cli.mjs",
+    "pack": "node scripts/pack.mjs",
+    "release": "node scripts/release.mjs",
+    "validate:extension": "mcpb validate manifest.json",
+    "test": "vitest run",
+    "test:watch": "vitest"
   },
   "engines": {
     "node": ">=18"
@@ -42,13 +48,22 @@
   "author": "rcoenen",
   "dependencies": {
     "@modelcontextprotocol/sdk": "^1.27.1",
+    "@resvg/resvg-wasm": "^2.6.2",
     "archiver": "^7.0.1",
     "fzstd": "^0.1.1",
     "kiwi-schema": "^0.5.0",
     "pako": "^2.1.0",
     "sharp": "^0.34.5",
+    "ssim.js": "^3.5.0",
     "zstd-codec": "^0.1.5"
   },
+  "devDependencies": {
+    "@anthropic-ai/mcpb": "^2.1.2",
+    "@fontsource/darker-grotesque": "^5.2.8",
+    "@fontsource/inter": "^5.2.8",
+    "@fontsource/irish-grover": "^5.2.7",
+    "vitest": "^4.1.0"
+  },
   "keywords": [
     "figma",
     "deck",

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

@@ -1,29 +1,15 @@
 ---
 name: figma-slides-creator
 description: >
-  Create, populate, edit, and inspect Figma Slides .deck files. Use when the
-  user wants a finished presentation deck, wants to fill an existing template
-  with content, or wants to edit a non-template deck's text, images, or slide
-  order. Do not use this skill to author reusable templates themselves.
+  Create, edit, and inspect Figma Slides .deck files. Use when the user asks to
+  create a presentation, build a slide deck, edit slides, update text or images,
+  clone or remove slides, or produce a .deck file for Figma Slides.
   Powered by FigmaTK under the hood.
 metadata:
-  version: "0.3.1"
+  version: "0.3.8"
 ---
 
-# Figma Slides Creator
-
-Use this skill for the default workflow: take an existing template and build a new presentation from it. For authoring reusable templates themselves, use `skills/figma-template-builder/SKILL.md`.
-
-## Skill Boundary
-
-Use this skill when the outcome is a finished deck for immediate use.
-
-Switch to `skills/figma-template-builder/SKILL.md` when the user wants to:
-
-- build a reusable template
-- define layouts or placeholders
-- rename slots for future sessions
-- derive a new template system from references or examples
+# FigmaTK Skill
 
 ## ⚠️ Never open .deck files directly
 
@@ -37,144 +23,39 @@ To let the user view the result: tell them to **open the file in Figma Desktop**
 
 | Task | Approach |
 |------|----------|
-| 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` |
-| Author a reusable template | Use `skills/figma-template-builder/SKILL.md` |
-| 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` |
-
----
-
-## File locations — always use /tmp
-
-**All files go in `/tmp/`** — scripts, output decks, images, everything. Never write to the Desktop, Documents, Downloads, or any user directory. Never create intermediate notes or reference markdown files. Just build and save the deck.
-
-## Default Workflow
-
-1. Inspect the template or deck.
-2. Pick the minimum set of layouts or edits needed.
-3. Populate text slots first, then image slots.
-4. Save to a new `/tmp/` output path.
-5. Sanity-check the result with `figmatk_list_text` or by opening it in Figma Desktop.
+| Create a new deck from scratch | Use the high-level JS API (`lib/api.mjs`) |
+| Edit text or images in an existing deck | Use MCP tools (`figmatk_update_text`, `figmatk_insert_image`) |
+| Clone, remove, or restructure slides | Use MCP tools (`figmatk_clone_slide`, `figmatk_remove_slide`) |
+| Inspect structure or read content | Use MCP tools (`figmatk_inspect`, `figmatk_list_text`) |
 
 ---
 
-## 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
-- Layout state — `draft` or `published`
-- Text slots — explicit `slot:text:*` fields when present, otherwise fallback text candidates
-- Image slots — explicit `slot:image:*` fields when present, otherwise fallback image candidates
-- Node IDs — usable for direct targeting when the template has not been fully annotated yet
-
-**Read the catalog carefully before picking layouts:**
-- Prefer layouts with explicit slot metadata when available
-- Match each slide's purpose to your content; the existing copy is often the best hint
-- Use slot names first, then node IDs, then raw node names when populating content
-- If a layout exposes no explicit image slots, treat heuristic image candidates as weaker signals and avoid overwriting decorative sample imagery unless the user clearly wants that
-
-### 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": "The problem.", "body": "Description here." }, images: { "hero_image": "/tmp/problem-photo.jpg" } },
-    { slideId: "1:643", text: { "title": "Thank you!" } }
-  ]
-})
-```
-
-Only pass slots or node IDs that exist in the layout's catalog. Extra keys are silently ignored.
-
----
-
-## Path A — Create from Scratch (MCP tool — no template)
-
-**Always use this path.** No npm install, no scripts, no workspace setup.
-
-Call `figmatk_create_deck` with a structured slide description:
-
-```json
-{
-  "output": "/tmp/my-deck.deck",
-  "title": "My Presentation",
-  "theme": "midnight",
-  "slides": [
-    { "type": "title",   "title": "My Presentation", "subtitle": "A subtitle" },
-    { "type": "bullets", "title": "Key Points", "bullets": ["Point one", "Point two", "Point three"] },
-    { "type": "two-column", "title": "Comparison", "leftText": "Left side content", "rightText": "Right side content" },
-    { "type": "stat",    "title": "By the numbers", "stat": "42%", "caption": "of users prefer this" },
-    { "type": "image-full", "image": "/tmp/photo.jpg", "title": "Caption text" },
-    { "type": "closing", "title": "Thank you", "subtitle": "Questions?" }
-  ]
-}
-```
-
-### Slide types
-
-| Type | Fields |
-|------|--------|
-| `title` | `title`, `subtitle` |
-| `bullets` | `title`, `bullets` (array) |
-| `two-column` | `title`, `leftText`, `rightText`, `image` (right side) |
-| `stat` | `title`, `stat` (big number), `caption` |
-| `image-full` | `image` (path), `title`, `body` (overlay text) |
-| `closing` | `title`, `subtitle` |
-
-### Themes
+## Path A — Create from Scratch (High-Level API)
 
-`midnight` · `ocean` · `forest` · `coral` · `terracotta` · `minimal`
+Use this when the user wants a new presentation. Write a Node.js script and execute it.
 
-Each theme handles backgrounds, accent colors, and text colors automatically.
-
----
-
-## Path A2 — Create from Scratch (Node.js script fallback)
-
-Only use this if `figmatk_create_deck` is unavailable or you need layout control beyond what the MCP tool offers.
-
-### Step 1 — Set up workspace (MANDATORY — never skip)
-
-```bash
-[ -d /tmp/figmatk-ws/node_modules ] || (mkdir -p /tmp/figmatk-ws && cd /tmp/figmatk-ws && npm init -y && npm install figmatk)
-```
-
-### Step 2 — Write script to `/tmp/figmatk-ws/deck.mjs`
-
-**Always use bare specifier** `import { Deck } from 'figmatk'` — never a file path.
+> **Import path:** `figmatk` is an npm package. Import from the installed package:
+> ```javascript
+> import { Deck } from 'figmatk';
+> ```
 
 ```javascript
 import { Deck } from 'figmatk';
 
-function hex(h) {
-  return { r: parseInt(h.slice(1,3),16)/255, g: parseInt(h.slice(3,5),16)/255, b: parseInt(h.slice(5,7),16)/255 };
-}
-
 const deck = await Deck.create('My Presentation');
-const slide = deck.addBlankSlide();
-slide.setBackground('Black');
-slide.addText('Slide Title', { style: 'Title', color: 'White', x: 64, y: 80, width: 1792, align: 'LEFT' });
-await deck.save('/tmp/my-presentation.deck');
-console.log('Done');
-```
 
-### Step 3 — Run
-
-```bash
-node /tmp/figmatk-ws/deck.mjs
+const slide = deck.addBlankSlide();          // template blank slide auto-removed
+slide.setBackground('Black');                // named color — see list below
+slide.addText('Slide Title', {
+  style: 'Title', color: 'White',
+  x: 64, y: 80, width: 1792, align: 'LEFT'
+});
+slide.addText('Subtitle', {
+  style: 'Body 1', color: 'Grey',
+  x: 64, y: 240, width: 1200, align: 'LEFT'
+});
+
+await deck.save('/path/to/output.deck');
 ```
 
 ### ⚠️ Critical gotchas
@@ -184,11 +65,9 @@ node /tmp/figmatk-ws/deck.mjs
 | `setBackground` with hex | `s.setBackground('#1A1A1A')` | `s.setBackground('Black')` |
 | `setBackground` with raw RGB | `s.setBackground({ r:0.1, g:0.1, b:0.1 })` | `s.setBackground('Black')` — raw RGB silently renders white |
 | Shape method signature | `s.addRectangle({ x:0, y:0, width:100 })` | `s.addRectangle(0, 0, 100, 100, opts)` |
-| Shape fill color | `{ fill: { r:1, g:0, b:0 } }` | `{ fill: '#F4900C' }` or `{ fill: 'Red' }` — hex strings and named colors work directly |
+| Shape fill color | `{ fill: '#F4900C' }` | `{ fill: hex('#F4900C') }` — use the hex() helper |
 | `addLine` options | `{ strokeColor: ..., strokeWeight: 2 }` | `{ color: 'Black', weight: 2 }` |
 | `align` value | `align: 'left'` | `align: 'LEFT'` (uppercase) |
-| `addImage` without await | `slide.addImage('/tmp/photo.jpg')` | `await slide.addImage('/tmp/photo.jpg')` — async, images silently missing without await |
-| `addImage` old signature | `await slide.addImage(x, y, w, h, path)` | `await slide.addImage(path, { x, y, width, height })` — path is first arg now |
 
 ### Hex color helper (for shape fills)
 
@@ -212,17 +91,13 @@ function hex(h) {
 | `Body 3` | 24pt | Regular | Captions, labels |
 | `Note` | 20pt | Regular | Footnotes, sources |
 
-### Colors for `setBackground()`
+### Named colors for `setBackground()`
 
-Accepts named colors, hex strings, or designer aliases — **when using figmatk 0.0.12+ from the workspace install**.
-
-**Named colors** (case-sensitive, from the Light Slides theme):
+> **Case-sensitive.** `'Black'` works, `'black'` does not.
 
 `'Black'`, `'White'`, `'Grey'`, `'Blue'`, `'Red'`, `'Yellow'`, `'Green'`, `'Orange'`, `'Pink'`, `'Purple'`, `'Teal'`, `'Violet'`, `'Persimmon'`, `'Pale Pink'`, `'Pale Blue'`, `'Pale Green'`, `'Pale Teal'`, `'Pale Purple'`, `'Pale Persimmon'`, `'Pale Violet'`, `'Pale Red'`, `'Pale Yellow'`
 
-**Hex strings** (0.0.12+): `slide.setBackground('#C8102E')`
-
-**Designer aliases** (0.0.12+): `slide.setBackground('navy')`, `slide.setBackground('coral')`, `slide.setBackground('terracotta')` etc.
+Use `'Black'` for dark backgrounds, `'White'` for light. For custom slide backgrounds, use the closest named color — **not hex**.
 
 ### Slide dimensions
 
@@ -240,8 +115,8 @@ slide.addDiamond(x, y, width, height, opts)
 slide.addTriangle(x, y, width, height, opts)
 slide.addStar(x, y, width, height, opts)
 slide.addLine(x1, y1, x2, y2, opts)             // opts: color, weight
-await slide.addImage(pathOrBuf, opts)    // ⚠️ ASYNC — must use await; opts: x, y, width, height (default: full slide 1920×1080), cornerRadius, opacity
-slide.addTable(x, y, data, opts)                  // 2D string array; opts: width, colWidths, rowHeight
+slide.addImage(path, opts)                        // opts: x, y, width, height
+slide.addTable(data, opts)                        // 2D string array; opts: x, y, width, colWidths, rowHeight
 slide.addSVG(x, y, width, svgPathOrBuf, opts)
 ```
 
@@ -266,7 +141,6 @@ Use this when the user provides a `.deck` file to modify.
 
 | Tool | Purpose |
 |------|---------|
-| `figmatk_create_deck` | **Create a new deck from scratch** — no npm install needed |
 | `figmatk_inspect` | Node hierarchy tree — structure, node IDs, slide count |
 | `figmatk_list_text` | All text strings and image hashes per slide |
 | `figmatk_list_overrides` | Editable override keys per symbol (component) |
@@ -275,45 +149,55 @@ Use this when the user provides a `.deck` file to modify.
 | `figmatk_clone_slide` | Deep-clone a slide with new text and images |
 | `figmatk_remove_slide` | Mark slides as REMOVED (never deleted) |
 | `figmatk_roundtrip` | Decode + re-encode for pipeline validation |
-
-## Final Checks
-
-Before finishing, prefer at least one of these:
-
-- `figmatk_list_text` on the output deck
-- `figmatk_roundtrip` if the deck went through multiple edits
-- a manual open check in Figma Desktop when the user is validating upload/render behavior
+| `figmatk_render_slide` | Render a slide to image (inline WebP or saved PNG) |
 
 ---
 
-## Design Philosophy
+## Path C — Visual QA (Render + Inspect)
 
-Think like a **professional PowerPoint designer**, not an AI generating slides. Every deck must feel like it was made by a human who spent a day on it.
+After creating or modifying a deck, **always render and visually inspect** the output. This catches issues that text inspection misses: overflowing text, broken layouts, wrong colors, misaligned elements.
 
-### Deck structure — use this template every time
-
-A proper deck has a clear spine. Follow this slide order:
+### Workflow
 
-| # | Slide type | Purpose |
-|---|-----------|---------|
-| 1 | **Title** | Dark bg, big title, subtitle, presenter name |
-| 2 | **Agenda / Overview** | 3–5 bullet topics, light bg |
-| 3–N | **Content slides** | Vary layout each slide — see below |
-| N+1 | **Section divider** (optional) | Bold colour block to signal a new chapter |
-| Last | **Closing / CTA** | Dark bg mirrors title slide — "Thank you", next steps, contact |
+1. Render each slide at preview size (returns inline WebP image):
+   ```
+   figmatk_render_slide(path: "/tmp/my-deck.deck", slide: 1)
+   ```
+2. Inspect the returned image for:
+   - Text overflowing its bounding box or clipped
+   - Layout misalignment or overlapping elements
+   - Wrong colors or missing backgrounds
+   - Missing images or broken fills
+3. If issues are found, fix them and re-render
+4. For full-resolution export:
+   ```
+   figmatk_render_slide(path: "/tmp/my-deck.deck", slide: 1, output: "/tmp/slide-1.png")
+   ```
+
+### Render options
+
+| Option | Example | Effect |
+|--------|---------|--------|
+| (none) | `slide: 1` | Inline WebP at 800px wide (for QA) |
+| `width` | `width: 400` | Resize to 400px wide (proportional) |
+| `scale` | `scale: "50%"` | Half size (960×540) |
+| `output` | `output: "/tmp/s.png"` | Save full PNG to disk |
+
+### CLI alternative
 
-The title and closing slides must use the **same dark background** — this creates the "sandwich" effect that makes decks feel complete.
+```bash
+figmatk render my-deck.deck -o /tmp/renders/                   # all slides
+figmatk render my-deck.deck -o /tmp/renders/ --slide 3         # single slide
+figmatk render my-deck.deck -o /tmp/renders/ --width 400       # thumbnail size
+```
 
-### Consistent visual motif — pick one and use it on every slide
+**Important:** Always run visual QA on every deck you create or modify. Do not skip this step.
 
-Choose one repeating element and place it consistently across all content slides:
+---
 
-- **Top accent bar**: `addRectangle(0, 0, 1920, 8, { fill: hex('#...') })` — full-width coloured strip at top
-- **Left colour panel**: tall rectangle on the left third, text floats right
-- **Corner badge**: small filled circle or square in bottom-right with slide number or logo
-- **Bottom rule**: thin full-width line at y=1040
+## Design Philosophy
 
-Without a motif, slides look unrelated. With one, the deck feels designed.
+Every deck must look **intentionally designed**, not AI-generated.
 
 ### Colour
 
@@ -332,29 +216,18 @@ Without a motif, slides look unrelated. With one, the deck feels designed.
 | Ocean | `'Blue'` | `hex('#21295C')` | `'White'` |
 | Minimal | `'White'` | `hex('#36454F')` | `'Black'` |
 
-### Layout — vary every slide
-
-Each content slide should use a **different layout type**. Never repeat the same structure back-to-back.
+### Layout
 
-| Layout | When to use |
-|--------|------------|
-| Two-column | Comparison, pros/cons, text + image |
-| 2×2 or 2×3 grid | Features, icons, categories |
-| Large stat callout | One big number + explanation |
-| Half-background image | Photo-rich slides |
-| Timeline / steps | Process, history, roadmap |
-| Icon + text rows | Lists that need visual weight |
-| Full-bleed image | Impact moment, section break |
+- Every slide needs at least **one visual element** — shape, image, SVG, or table.
+- **Vary layouts** — never repeat the same structure slide after slide.
+- Carry one visual motif through every slide (coloured accent bar, icon circles, etc.).
 
-Every slide needs at least **one visual element** — shape, image, SVG, or table. No text-only slides.
+**Layout options:** two-column, icon+text rows, 2×2/2×3 grid, large stat callout, half-background image, timeline/steps.
 
 ### Typography
 
-- Left-align body text. Centre only titles on title/closing slides.
+- Left-align body text. Centre only titles.
 - Minimum 64px margin from slide edges. 24–48px between content blocks.
-- Use `Header 2` or `Header 3` for slide titles on content slides (not `Title` — that's for the title slide only).
-- **Body text: max 2 sentences per text block.** Text boxes have fixed heights — overflow gets clipped. If you have more to say, use a bullet list or split across slides.
-- **Bullets: max 6 items, max 8 words per bullet.** Longer bullets wrap and push content off-slide.
 
 ### Never do
 
@@ -362,17 +235,17 @@ 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 — **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
+- Low-contrast text against background
 
 ---
 
 ## QA
 
 1. Self-check: no placeholder text (`lorem ipsum`, `[title here]`) remains
-2. Tell the user to open the `.deck` in Figma Desktop to catch rendering issues
-3. Offer to fix anything they report
+2. **Render every slide** using `figmatk_render_slide` and visually inspect for overflows, clipping, alignment, and color issues
+3. Fix any issues found and re-render to confirm
+4. Tell the user to open the `.deck` in Figma Desktop for final review
+5. Offer to fix anything they report
 
 ---
 

package/skills/figma-template-builder/SKILL.md

@@ -6,13 +6,23 @@ description: >
   template from an existing deck, define reusable layouts, mark editable
   text/image slots, or prepare a draft template for later instantiation.
 metadata:
-  version: "0.1.0"
+  version: "0.3.8"
 ---
 
 # Figma Template Builder
 
 Use this skill when the goal is to build or refine the template itself. For the common workflow of taking an existing template and producing a new presentation, use `skills/figma-slides-creator/SKILL.md`.
 
+## MCP First
+
+In Claude Cowork, keep template authoring inside the MCP plugin.
+
+- Do not inspect the installed `figmatk` package to discover template features.
+- Do not write direct Node.js scripts for draft creation, annotation, wrapping, or instantiation when MCP tools exist for those steps.
+- Prefer `figmatk_create_template_draft`, `figmatk_annotate_template_layout`, `figmatk_publish_template_draft`, and `figmatk_list_template_layouts`.
+
+Only fall back to direct library code if the MCP server is unavailable or the required capability is missing from the MCP surface.
+
 ## Skill Boundary
 
 Use this skill when the deliverable is a reusable template, not a one-off deck.