figmatk 0.1.1 → 0.2.1

package/.claude-plugin/marketplace.json

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

package/.claude-plugin/plugin.json

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

package/lib/api.mjs

@@ -561,7 +561,7 @@ export class Slide {
   addRectangle(x, y, width, height, opts = {}) {
     const fd = this._fd;
     const localID = fd.maxLocalID() + 1;
-    const fill = opts.fill ?? { r: 1, g: 1, b: 1, a: 1 };
+    const fill = parseColor(fd, opts.fill ?? 'White');
 
     const node = {
       guid: { sessionID: 1, localID },
@@ -904,7 +904,7 @@ export class Slide {
   _addShapeWithText(shapeType, x, y, width, height, opts = {}) {
     const fd = this._fd;
     const localID = fd.maxLocalID() + 1;
-    const fill = opts.fill ?? { r: 1, g: 1, b: 1, a: 1 };
+    const fill = parseColor(fd, opts.fill ?? 'White');
     const fillPaint = {
       type: 'SOLID',
       color: { r: fill.r, g: fill.g, b: fill.b, a: fill.a ?? 1 },
@@ -1185,7 +1185,7 @@ export class Slide {
     fd.message.blobs.push({ bytes: _buildVectorNetworkBlob(allCmds) });
     const vnbIdx = fd.message.blobs.length - 1;
 
-    const fill = opts.fill ?? { r: 0, g: 0, b: 0 };
+    const fill = parseColor(fd, opts.fill ?? 'Black');
     const opacity = opts.opacity ?? 1;
 
     const frameId = nextId++;

package/mcp-server.mjs

@@ -6,6 +6,7 @@ import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
 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 { 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';
@@ -246,6 +247,95 @@ server.tool(
   }
 );
 
+// ── create-deck ─────────────────────────────────────────────────────────
+const THEMES = {
+  midnight:   { dark: 'Black',     light: 'White',          accent: { r: 0.792, g: 0.863, b: 0.988 }, textDark: 'White', textLight: 'Black' },
+  ocean:      { dark: 'Blue',      light: 'Pale Blue',      accent: { r: 0.129, g: 0.161, b: 0.361 }, textDark: 'White', textLight: 'Black' },
+  forest:     { dark: 'Green',     light: 'Pale Green',     accent: { r: 0.592, g: 0.737, b: 0.384 }, textDark: 'White', textLight: 'Black' },
+  coral:      { dark: 'Persimmon', light: 'Pale Persimmon', accent: { r: 0.184, g: 0.235, b: 0.494 }, textDark: 'White', textLight: 'Black' },
+  terracotta: { dark: 'Persimmon', light: 'Pale Persimmon', accent: { r: 0.906, g: 0.910, b: 0.820 }, textDark: 'White', textLight: 'Black' },
+  minimal:    { dark: 'Black',     light: 'White',          accent: { r: 0.212, g: 0.271, b: 0.310 }, textDark: 'White', textLight: 'Black' },
+};
+
+const SlideSchema = z.object({
+  type: z.enum(['title', 'bullets', 'two-column', 'stat', 'image-full', 'closing']),
+  title:      z.string().optional(),
+  subtitle:   z.string().optional(),
+  body:       z.string().optional(),
+  bullets:    z.array(z.string()).optional(),
+  stat:       z.string().optional(),
+  caption:    z.string().optional(),
+  image:      z.string().optional().describe('Absolute path to image file'),
+  leftText:   z.string().optional(),
+  rightText:  z.string().optional(),
+  background: z.string().optional().describe('Override background (named color)'),
+});
+
+server.tool(
+  'figmatk_create_deck',
+  'Create a new Figma Slides .deck file from a structured description. No npm install needed — runs directly in the MCP server.',
+  {
+    output: z.string().describe('Output path for the .deck file, e.g. /tmp/my-deck.deck'),
+    title:  z.string().describe('Deck title'),
+    theme:  z.string().optional().describe('Theme: midnight | ocean | forest | coral | terracotta | minimal (default: midnight)'),
+    slides: z.array(SlideSchema).describe('Slides to create'),
+  },
+  async ({ output, title, theme, slides }) => {
+    const t = THEMES[theme ?? 'midnight'] ?? THEMES.midnight;
+    const deck = await Deck.create(title);
+
+    for (const s of slides) {
+      const slide = deck.addBlankSlide();
+      const isDark = ['title', 'closing', 'stat', 'image-full'].includes(s.type);
+      const bg = s.background ?? (isDark ? t.dark : t.light);
+      const fg = isDark ? t.textDark : t.textLight;
+      slide.setBackground(bg);
+
+      if (s.type === 'title' || s.type === 'closing') {
+        slide.addRectangle(0, 0, 1920, 8, { fill: t.accent });
+        if (s.title)    slide.addText(s.title,    { style: 'Title',  color: fg, x: 80, y: 360, width: 1760, align: 'CENTER' });
+        if (s.subtitle) slide.addText(s.subtitle, { style: 'Body 1', color: fg, x: 80, y: 540, width: 1760, align: 'CENTER' });
+
+      } else if (s.type === 'bullets') {
+        slide.addRectangle(0, 0, 1920, 8, { fill: t.accent });
+        if (s.title) slide.addText(s.title, { style: 'Header 2', color: fg, x: 80, y: 80, width: 1760, align: 'LEFT' });
+        const items = s.bullets ?? (s.body ? s.body.split('\n') : []);
+        let y = 240;
+        for (const item of items) {
+          slide.addRectangle(80, y + 10, 12, 12, { fill: t.accent });
+          slide.addText(item, { style: 'Body 1', color: fg, x: 116, y, width: 1724, align: 'LEFT' });
+          y += 80;
+        }
+
+      } else if (s.type === 'two-column') {
+        slide.addRectangle(0, 0, 1920, 8, { fill: t.accent });
+        if (s.title) slide.addText(s.title, { style: 'Header 2', color: fg, x: 80, y: 80, width: 1760, align: 'LEFT' });
+        slide.addRectangle(960, 200, 4, 800, { fill: t.accent });
+        if (s.leftText)  slide.addText(s.leftText,  { style: 'Body 1', color: fg, x: 80,   y: 240, width: 840, align: 'LEFT' });
+        if (s.rightText) slide.addText(s.rightText, { style: 'Body 1', color: fg, x: 1004, y: 240, width: 836, align: 'LEFT' });
+        if (s.image) await slide.addImage(s.image, { x: 1004, y: 200, width: 836, height: 800 });
+
+      } else if (s.type === 'stat') {
+        slide.addRectangle(0, 0, 1920, 8, { fill: t.accent });
+        if (s.title)   slide.addText(s.title,   { style: 'Header 2', color: fg, x: 80, y: 80,  width: 1760, align: 'LEFT' });
+        if (s.stat)    slide.addText(s.stat,    { style: 'Title',    color: fg, x: 80, y: 300, width: 1760, align: 'CENTER' });
+        if (s.caption) slide.addText(s.caption, { style: 'Body 1',   color: fg, x: 80, y: 720, width: 1760, align: 'CENTER' });
+
+      } else if (s.type === 'image-full') {
+        if (s.image) await slide.addImage(s.image, { x: 0, y: 0, width: 1920, height: 1080 });
+        if (s.title || s.body) {
+          slide.addRectangle(0, 680, 1920, 400, { fill: { r: 0, g: 0, b: 0 }, opacity: 0.7 });
+          if (s.title) slide.addText(s.title, { style: 'Header 1', color: 'White', x: 80, y: 720, width: 1760, align: 'LEFT' });
+          if (s.body)  slide.addText(s.body,  { style: 'Body 1',   color: 'White', x: 80, y: 880, width: 1760, align: 'LEFT' });
+        }
+      }
+    }
+
+    await deck.save(output);
+    return { content: [{ type: 'text', text: `Created ${output} — ${slides.length} slides. 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.1.1",
+  "version": "0.2.1",
   "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.1.1"
+  version: "0.2.1"
 ---
 
 # Figma Slides Creator
@@ -23,10 +23,10 @@ To let the user view the result: tell them to **open the file in Figma Desktop**
 
 | Task | Approach |
 |------|----------|
-| 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`) |
+| Create a new deck from scratch | **`figmatk_create_deck` MCP tool** — no npm install needed |
+| 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,25 +36,60 @@ To let the user view the result: tell them to **open the file in Figma Desktop**
 
 ---
 
-## Path A — Create from Scratch (High-Level API)
+## Path A — Create from Scratch (MCP tool — preferred)
+
+**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
+
+`midnight` · `ocean` · `forest` · `coral` · `terracotta` · `minimal`
+
+Each theme handles backgrounds, accent colors, and text colors automatically.
 
-Use this when the user wants a new presentation. Follow these steps **in order, every time, no exceptions**.
+---
+
+## Path A2 — Create from Scratch (Node.js script fallback)
 
-### Step 1 — Set up workspace (MANDATORY FIRST STEP — never skip)
+Only use this if `figmatk_create_deck` is unavailable or you need layout control beyond what the MCP tool offers.
 
-The environment has no `node_modules`. **Before writing any script**, run this exact command:
+### 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)
 ```
 
-Do not proceed to Step 2 until this command succeeds.
-
-### Step 2 — Write the script to `/tmp/figmatk-ws/deck.mjs`
-
-**Always write the script to `/tmp/figmatk-ws/deck.mjs`** — not to the current directory, not to any other path.
+### Step 2 — Write script to `/tmp/figmatk-ws/deck.mjs`
 
-**Always use the bare specifier** `import { Deck } from 'figmatk'` — never a file path import.
+**Always use bare specifier** `import { Deck } from 'figmatk'` — never a file path.
 
 ```javascript
 import { Deck } from 'figmatk';
@@ -64,32 +99,19 @@ function hex(h) {
 }
 
 const deck = await Deck.create('My Presentation');
-
-// Each call to addBlankSlide() returns a new blank slide.
-// The template blank slide is auto-removed on the first call.
 const slide = deck.addBlankSlide();
-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'
-});
-
+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 — open /tmp/my-presentation.deck in Figma Desktop');
+console.log('Done');
 ```
 
-### Step 3 — Run the script
+### Step 3 — Run
 
 ```bash
 node /tmp/figmatk-ws/deck.mjs
 ```
 
-If this fails, check the error and fix the script — **do not change the workspace setup or the import path**.
-
 ### ⚠️ Critical gotchas
 
 | Issue | Wrong | Right |
@@ -97,7 +119,7 @@ If this fails, check the error and fix the script — **do not change the worksp
 | `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: '#F4900C' }` | `{ fill: hex('#F4900C') }` — use the hex() helper |
+| Shape fill color | `{ fill: { r:1, g:0, b:0 } }` | `{ fill: '#F4900C' }` or `{ fill: 'Red' }` — hex strings and named colors work directly |
 | `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 |
@@ -179,6 +201,7 @@ 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) |