figmatk 0.0.7 → 0.0.9

package/.claude-plugin/marketplace.json

@@ -13,7 +13,7 @@
     {
       "name": "figmatk",
       "description": "Inspect and modify Figma Slides .deck files natively",
-      "version": "0.0.6",
+      "version": "0.0.8",
       "author": {
         "name": "FigmaTK Contributors"
       },

package/.claude-plugin/plugin.json

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

package/lib/api.mjs

@@ -1667,12 +1667,15 @@ function parseColor(fd, color) {
   if (typeof color === 'string') {
     // Hex string
     if (/^#?[0-9a-fA-F]{6}$/.test(color)) return _hexToRgb(color);
-    // Designer alias (case-insensitive)
+    // Figma theme variable first (exact match, preserves colorVar binding for slides)
+    try {
+      const variable = resolveColorVariable(fd, color);
+      return { r: variable.r, g: variable.g, b: variable.b, _guid: variable.guid };
+    } catch (_) {}
+    // Designer alias fallback (case-insensitive)
     const alias = DESIGNER_COLORS[color.toLowerCase()];
     if (alias) return _hexToRgb(alias);
-    // Figma theme variable
-    const variable = resolveColorVariable(fd, color);
-    return { r: variable.r, g: variable.g, b: variable.b, _guid: variable.guid };
+    throw new Error(`Unknown color: "${color}". Use a Light Slides name ('Black', 'Teal'), a designer alias ('navy', 'coral'), or a hex string ('#E63946').`);
   }
   throw new Error(`Invalid color: ${JSON.stringify(color)}`);
 }

package/package.json

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

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

@@ -0,0 +1,213 @@
+---
+name: figma-slides-creator
+description: >
+  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.0.8"
+---
+
+# FigmaTK Skill
+
+## ⚠️ Never open .deck files directly
+
+`.deck` files are binary ZIP archives. **Never open, read, or display a `.deck` file** — it will show garbage bytes in the panel. To inspect or modify a `.deck` file, always use the CLI commands or Node.js API shown below.
+
+To let the user view the result: tell them to **open the file in Figma Desktop** (`File → Open` or double-click the `.deck` file).
+
+---
+
+## Quick Reference
+
+| 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`) |
+
+---
+
+## Path A — Create from Scratch (High-Level API)
+
+Use this when the user wants a new presentation. Write a Node.js script and execute it.
+
+> **Import path:** `figmatk` is an npm package. Import from the installed package:
+> ```javascript
+> import { Deck } from 'figmatk';
+> ```
+
+```javascript
+import { Deck } from 'figmatk';
+
+const deck = await Deck.create('My Presentation');
+
+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
+
+| Issue | Wrong | Right |
+|-------|-------|-------|
+| `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 |
+| `addLine` options | `{ strokeColor: ..., strokeWeight: 2 }` | `{ color: 'Black', weight: 2 }` |
+| `align` value | `align: 'left'` | `align: 'LEFT'` (uppercase) |
+
+### Hex color helper (for shape fills)
+
+```javascript
+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 };
+}
+// Usage: s.addRectangle(0, 0, 200, 50, { fill: hex('#F4900C') })
+```
+
+### Text styles
+
+| Style | Size | Weight | Use for |
+|-------|------|--------|---------|
+| `Title` | 96pt | Bold | Slide title |
+| `Header 1` | 60pt | Bold | Section headers |
+| `Header 2` | 48pt | Bold | Sub-headers |
+| `Header 3` | 36pt | Bold | In-slide headings |
+| `Body 1` | 36pt | Regular | Primary body text |
+| `Body 2` | 30pt | Regular | Secondary body text |
+| `Body 3` | 24pt | Regular | Captions, labels |
+| `Note` | 20pt | Regular | Footnotes, sources |
+
+### Named colors for `setBackground()`
+
+> **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'`
+
+Use `'Black'` for dark backgrounds, `'White'` for light. For custom slide backgrounds, use the closest named color — **not hex**.
+
+### Slide dimensions
+
+1920 × 1080px. All positions and sizes in pixels.
+
+### Slide methods (correct signatures)
+
+```javascript
+slide.setBackground(namedColor)                   // named color only — hex/raw RGB render white
+slide.addText(text, opts)                         // opts: style, color (named or hex('#...')), x, y, width, align, bold, italic, fontSize
+slide.addFrame(opts)                              // auto-layout: stackMode, spacing, x, y, width, height
+slide.addRectangle(x, y, width, height, opts)    // opts: fill (named or {r,g,b}), opacity, cornerRadius
+slide.addEllipse(x, y, width, height, opts)      // opts: fill, opacity
+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
+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)
+```
+
+---
+
+## Path B — Edit an Existing Deck (MCP Tools)
+
+Use this when the user provides a `.deck` file to modify.
+
+### Workflow
+
+1. `figmatk_inspect` — understand the deck structure (node IDs, slide count, symbols)
+2. `figmatk_list_text` — read current text and images per slide
+3. `figmatk_list_overrides` — find the override keys for each symbol (what's editable)
+4. `figmatk_update_text` — apply text changes
+5. `figmatk_insert_image` — apply image changes
+6. `figmatk_clone_slide` — duplicate a slide and populate it
+7. `figmatk_remove_slide` — mark unwanted slides as REMOVED
+8. Always write to a **new output path** — never overwrite the source
+
+### MCP tool reference
+
+| Tool | Purpose |
+|------|---------|
+| `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) |
+| `figmatk_update_text` | Set text overrides on a slide instance |
+| `figmatk_insert_image` | Set image fill override (handles SHA-1 hashing + thumbnail) |
+| `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 |
+
+---
+
+## Design Philosophy
+
+Every deck must look **intentionally designed**, not AI-generated.
+
+### Colour
+
+- Pick a bold palette for the **specific topic** — not a generic one.
+- One dominant colour (60–70%) + 1–2 supporting tones + one sharp accent.
+- Dark backgrounds on title/conclusion slides, light on content ("sandwich") — or fully dark for premium feel.
+
+**Starter palettes** (use nearest named color for `setBackground`, hex helper for shapes):
+
+| Theme | Background | Shape accent | Text |
+|-------|-----------|-------------|------|
+| Midnight | `'Black'` | `hex('#CADCFC')` | `'White'` |
+| Forest | `'Green'` | `hex('#97BC62')` | `'White'` |
+| Coral | `'Persimmon'` | `hex('#2F3C7E')` | `'White'` |
+| Terracotta | `'Persimmon'` | `hex('#E7E8D1')` | `'White'` |
+| Ocean | `'Blue'` | `hex('#21295C')` | `'White'` |
+| Minimal | `'White'` | `hex('#36454F')` | `'Black'` |
+
+### Layout
+
+- 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.).
+
+**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.
+- Minimum 64px margin from slide edges. 24–48px between content blocks.
+
+### Never do
+
+- Repeat the same layout slide after slide
+- Centre body text
+- Use accent lines under slide titles (hallmark of AI-generated slides)
+- Text-only slides
+- 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
+
+---
+
+## Critical Format Rules
+
+- Blank text must be `" "` (space), never `""` — empty string crashes Figma
+- Image overrides need both a full-image hash and thumbnail hash (40-char hex SHA-1)
+- Removed nodes: set `phase: 'REMOVED'`, never delete from `nodeChanges`
+- Chunk 1 of `canvas.fig` must be zstd-compressed
+- `thumbHash` must be `new Uint8Array(0)`, never `{}`

package/skills/figmatk/SKILL.md

@@ -1,188 +0,0 @@
----
-name: figmatk
-description: >
-  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.
-metadata:
-  version: "0.0.6"
----
-
-# FigmaTK Skill
-
-## Quick Reference
-
-| 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`) |
-
----
-
-## Path A — Create from Scratch (High-Level API)
-
-Use this when the user wants a new presentation. Write a Node.js script and execute it.
-
-```javascript
-import { Deck } from 'figmatk';
-
-const deck = await Deck.create('My Presentation');
-const slide = deck.addBlankSlide();
-
-slide.setBackground('slate');
-slide.addText('Slide Title', { style: 'Title', color: 'white', x: 64, y: 80, width: 1792 });
-slide.addText('Subtitle or tagline here', { style: 'Body 1', color: 'light-gray', x: 64, y: 240, width: 1200 });
-
-await deck.save('/path/to/output.deck');
-```
-
-### Text styles
-
-| Style | Size | Weight | Use for |
-|-------|------|--------|---------|
-| `Title` | 96pt | Bold | Slide title |
-| `Header 1` | 60pt | Bold | Section headers |
-| `Header 2` | 48pt | Bold | Sub-headers |
-| `Header 3` | 36pt | Bold | In-slide headings |
-| `Body 1` | 36pt | Regular | Primary body text |
-| `Body 2` | 30pt | Regular | Secondary body text |
-| `Body 3` | 24pt | Regular | Captions, labels |
-| `Note` | 20pt | Regular | Footnotes, sources |
-
-### Colors
-
-Use **names** — never RGB values. The API accepts:
-
-| Type | Example |
-|------|---------|
-| Designer name | `'teal'`, `'coral'`, `'navy'`, `'midnight'`, `'forest'`, `'charcoal'`, `'cream'`, `'gold'`, `'terracotta'`, `'sage'`, `'cobalt'`, `'rose'`, `'indigo'`, `'burgundy'`, `'sand'`... |
-| Hex string | `'#E63946'` |
-| Light Slides theme | `'Blue'`, `'Red'`, `'Green'`, `'Yellow'`, `'Orange'`, `'Pink'`, `'Purple'`, `'Slate'`, `'White'`, `'Black'` |
-
-Pick colors by feeling: "warm terracotta on cream", "midnight blue with coral accent". Let the design drive the choice, then pick the closest name.
-
-### Slide dimensions
-
-1920 × 1080px. Position and size all elements in pixels.
-
-### Available slide methods
-
-```javascript
-slide.setBackground(color)                        // named color or hex
-slide.addText(text, opts)                         // opts: style, color, x, y, width, align, bold, italic, fontSize
-slide.addFrame(opts)                              // auto-layout frame: stackMode, spacing, x, y, width, height
-slide.addRectangle(opts)                          // opts: x, y, width, height, fill, opacity, cornerRadius
-slide.addEllipse(opts)                            // circle/ellipse: x, y, width, height, fill
-slide.addDiamond(opts)                            // diamond shape
-slide.addTriangle(opts)                           // triangle
-slide.addStar(opts)                               // 5-pointed star
-slide.addLine(x1, y1, x2, y2, opts)             // line: strokeColor, strokeWeight
-slide.addImage(path, opts)                        // freestanding image: x, y, width, height
-slide.addTable(data, opts)                        // 2D array of strings: x, y, width, colWidths, rowHeight
-slide.addSVG(x, y, width, svgPathOrBuf, opts)   // import SVG vector graphic
-```
-
----
-
-## Path B — Edit an Existing Deck (MCP Tools)
-
-Use this when the user provides a `.deck` file to modify.
-
-### Workflow
-
-1. `figmatk_inspect` — understand the deck structure (node IDs, slide count, symbols)
-2. `figmatk_list_text` — read current text and images per slide
-3. `figmatk_list_overrides` — find the override keys for each symbol (what's editable)
-4. `figmatk_update_text` — apply text changes
-5. `figmatk_insert_image` — apply image changes
-6. `figmatk_clone_slide` — duplicate a slide and populate it
-7. `figmatk_remove_slide` — mark unwanted slides as REMOVED
-8. Always write to a **new output path** — never overwrite the source
-
-### MCP tool reference
-
-| Tool | Purpose |
-|------|---------|
-| `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) |
-| `figmatk_update_text` | Set text overrides on a slide instance |
-| `figmatk_insert_image` | Set image fill override (handles SHA-1 hashing + thumbnail) |
-| `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 |
-
----
-
-## Design Philosophy
-
-Every deck must look **intentionally designed**, not AI-generated. Follow these rules on every presentation task.
-
-### Colour
-
-- Pick a bold palette that reflects the **specific topic**. If the same palette would suit a completely different presentation, it's not specific enough.
-- Use **one dominant colour** (60–70% visual weight) + 1–2 supporting tones + one sharp accent.
-- Use dark backgrounds on title and conclusion slides, light on content slides ("sandwich" structure) — or commit fully to dark for a premium feel.
-
-**Starter palettes:**
-
-| Theme | Background | Accent | Text |
-|-------|-----------|--------|------|
-| Midnight | `navy` | `sky` | `white` |
-| Forest | `forest` | `sage` | `white` |
-| Coral | `coral` | `indigo` | `white` |
-| Terracotta | `terracotta` | `sand` | `white` |
-| Ocean | `cobalt` | `midnight` | `white` |
-| Minimal | `smoke` | `charcoal` | `black` |
-
-### Layout
-
-- Every slide needs at least **one visual element** — shape, image, SVG icon, or table. Text-only slides are forgettable.
-- **Vary layouts** — never use the same structure slide after slide.
-- Pick one visual motif (e.g. rounded image frames, coloured icon circles, thick side accent bars) and carry it through every slide.
-
-**Layout options per slide:**
-
-- Two-column (text left, visual right)
-- Icon + text rows (icon in coloured circle, bold header, description)
-- 2×2 or 2×3 grid of cards
-- Large stat callout (big number + small label)
-- Half-background image with text overlay
-- Timeline / numbered steps
-
-### Typography
-
-- Left-align body text. Centre only titles.
-- **Font sizes:** titles use `Title` style (96pt); section headers `Header 1` (60pt); body `Body 1` or `Body 2`; captions `Body 3` or `Note`.
-- Minimum 64px margin from slide edges. 24–48px gap between content blocks.
-
-### Things to never do
-
-- Repeat the same layout slide after slide
-- Centre body text
-- Use accent lines under slide titles (hallmark of AI-generated slides — use colour or whitespace instead)
-- Create text-only slides
-- Use low-contrast text — always check text against its background
-- Default to generic blue — pick colours that reflect the topic
-
----
-
-## QA
-
-After generating or editing a deck:
-
-1. **Self-check:** confirm all placeholder text has been replaced, no `lorem ipsum` or `[title here]` remains
-2. **Tell the user** to upload the `.deck` to Figma Slides and review visually — this is the only way to catch rendering issues
-3. **Offer to fix** any issues the user reports after upload
-
----
-
-## Critical Format Rules
-
-- Blank text fields must use `" "` (space), **never** empty string — empty string crashes Figma
-- Image overrides require both a full-image hash and a ~320px thumbnail hash (40-char hex SHA-1)
-- Removed nodes use `phase: 'REMOVED'` — never delete from `nodeChanges`
-- Chunk 1 of `canvas.fig` must be zstd-compressed — Figma silently rejects deflateRaw
-- `thumbHash` must be `new Uint8Array(0)`, never `{}`