figmatk 0.3.0 → 0.3.7

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

@@ -6,10 +6,10 @@ description: >
   clone or remove slides, or produce a .deck file for Figma Slides.
   Powered by FigmaTK under the hood.
 metadata:
-  version: "0.3.0"
+  version: "0.3.7"
 ---
 
-# Figma Slides Creator
+# FigmaTK Skill
 
 ## ⚠️ Never open .deck files directly
 
@@ -23,132 +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` |
-| 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` |
+| 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`) |
 
 ---
 
-## File locations — always use /tmp
+## Path A — Create from Scratch (High-Level API)
 
-**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.
+Use this when the user wants a new presentation. Write a Node.js script and execute it.
 
----
-
-## 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.
-
-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.
-
----
-
-## 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
@@ -158,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)
 
@@ -186,17 +91,13 @@ function hex(h) {
 | `Body 3` | 24pt | Regular | Captions, labels |
 | `Note` | 20pt | Regular | Footnotes, sources |
 
-### Colors for `setBackground()`
-
-Accepts named colors, hex strings, or designer aliases — **when using figmatk 0.0.12+ from the workspace install**.
+### Named colors for `setBackground()`
 
-**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
 
@@ -214,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)
 ```
 
@@ -240,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) |
@@ -249,37 +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 |
+| `figmatk_render_slide` | Render a slide to image (inline WebP or saved PNG) |
 
 ---
 
-## Design Philosophy
-
-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.
+## Path C — Visual QA (Render + Inspect)
 
-### Deck structure — use this template every time
+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.
 
-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
 
@@ -298,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
 
@@ -328,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

@@ -0,0 +1,158 @@
+---
+name: figma-template-builder
+description: >
+  Author reusable Figma Slides templates as .deck files. Use when the user
+  wants to build a template from reference images or examples, derive a new
+  template from an existing deck, define reusable layouts, mark editable
+  text/image slots, or prepare a draft template for later instantiation.
+metadata:
+  version: "0.3.7"
+---
+
+# 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.
+
+Stay here when the user wants to:
+
+- translate reference images or screenshots into template layouts
+- create a new layout family
+- define placeholder semantics for later sessions
+- turn an ordinary deck into a reusable template
+
+Hand off to `skills/figma-slides-creator/SKILL.md` once the template exists and the task becomes simple content population.
+
+## Core Model
+
+Template work happens in two states:
+
+- Draft template: `SLIDE_ROW -> SLIDE -> ...`
+- Published or publish-like template: `SLIDE_ROW -> MODULE -> SLIDE -> ...`
+
+Draft templates are easier to author. Publish-like wrapping is the final step before later instantiation.
+
+## Design-First Workflow
+
+When the user provides reference images, screenshots, or example decks:
+
+1. Read the references first and infer the layout family before touching the `.deck`.
+2. Decide which parts are reusable structure versus one-off sample content.
+3. Create only the smallest set of layouts that captures the system.
+4. Use semantic slot names so later sessions can populate them without re-reading the design intent.
+
+Do not mirror every visual variation as its own layout unless the content structure changes materially.
+
+## Naming Conventions
+
+Always use explicit metadata when authoring reusable layouts:
+
+- Layouts: `layout:<name>`
+- Text slots: `slot:text:<name>`
+- Image slots: `slot:image:<name>`
+- Decorative fixed imagery: `fixed:image:<name>`
+
+These conventions are how later sessions discover what is editable.
+
+Prefer semantic names over visual or auto-generated names.
+
+Good:
+
+- `title`
+- `subtitle`
+- `hero_image`
+- `device_screen_primary`
+- `quote_author`
+
+Bad:
+
+- `text1`
+- `frame183`
+- `image-left`
+- `rectangle2`
+
+## Recommended Flow
+
+### 1. Create or inspect a draft template
+
+- New draft from scratch: `figmatk_create_template_draft`
+- Existing deck/template: `figmatk_list_template_layouts`
+- Structural inspection: `figmatk_inspect`
+
+### 2. Annotate reusable layouts
+
+Use `figmatk_annotate_template_layout` to:
+
+- rename a slide as a layout
+- mark text nodes as editable text slots
+- mark image-bearing nodes as editable image slots
+- mark decorative imagery as fixed
+
+The tool accepts node ID maps, so inspect first if you need the raw node IDs.
+
+While annotating:
+
+- rename the slide itself to the stable layout name
+- mark only true placeholders as `slot:*`
+- mark decorative or sample imagery as `fixed:image:*`
+- prefer stable semantic names over spatial names like `left_box`
+
+### 3. Publish-wrap when the template is ready
+
+Use `figmatk_publish_template_draft` to add publish-like `MODULE` wrappers while preserving the slide subtree and internal assets.
+
+### 4. Verify the result
+
+- `figmatk_list_template_layouts`
+- `figmatk_list_text`
+- `figmatk_roundtrip` if you want a conservative encode/decode check
+- open the wrapped template in Figma Desktop when validating real upload behavior
+
+## Practical Rules
+
+- Prefer explicit slot names over heuristic placeholders.
+- Do not assume every image fill is editable content.
+- Preserve `Internal Only Canvas` assets.
+- Preserve special nodes such as device mockups and interactive slide elements; do not try to recreate them from scratch unless necessary.
+
+## Template Authoring Heuristics
+
+- Start with 4-8 reusable layouts, not an exhaustive library.
+- Reuse one layout when only copy length changes; create a new layout when hierarchy or media structure changes.
+- Separate content slots from chrome. For device mockups, the screen is usually the slot and the hardware frame is usually fixed.
+- If a layout has explicit slot metadata, do not rely on heuristic image placeholders for that layout.
+- After publish-wrapping, re-run `figmatk_list_template_layouts` and confirm the layout names and slot names survived unchanged.
+
+## Example
+
+```json
+{
+  "path": "/tmp/draft-template.deck",
+  "output": "/tmp/draft-template-annotated.deck",
+  "slideId": "1:42",
+  "layoutName": "cover",
+  "textSlots": {
+    "1:120": "title",
+    "1:121": "subtitle"
+  },
+  "imageSlots": {
+    "1:144": "hero_image"
+  },
+  "fixedImages": {
+    "1:199": "background_texture"
+  }
+}
+```