Dev/ashwinm/figma skill update

plugins/figma/plugin.lock.json

@@ -7,7 +7,7 @@
   "skills": [
     {
       "id": "figma-code-connect",
-      "vendoredPath": "skills/figma-code-connect-components",
+      "vendoredPath": "skills/figma-code-connect",
       "source": {
         "type": "github",
         "repo": "figma/mcp-server-guide",

plugins/figma/skills/figma-code-connect-components/references/api.md → plugins/figma/skills/figma-code-connect/references/api.md

@@ -281,6 +281,18 @@ if (icon) {
 }
 ```
 
+#### `getSlot(propName: string): ResultSection[] | undefined`
+
+Reads a Figma component property whose type is **`SLOT`** (not **INSTANCE_SWAP**). Returns a `ResultSection[]` containing a slot section (`type: 'SLOT'`). Returns `undefined` if the property is missing or invalid. Do not call `executeTemplate()` on this value — unlike `getInstanceSwap()`, it is not an `InstanceHandle`.
+
+```javascript
+const content = instance.getSlot('Content')
+
+export default {
+  example: figma.code`<Card>${content}</Card>`
+}
+```
+
 #### `getPropertyValue(propName: string): string | boolean`
 
 Gets the raw property value without mapping.

plugins/figma/skills/figma-create-new-file/SKILL.md

@@ -1,6 +1,7 @@
 ---
 name: figma-create-new-file
 description: Create a new blank Figma file. Use when the user wants to create a new Figma design or FigJam file, or when you need a new file before calling use_figma. Handles plan resolution via whoami if needed. Usage — /figma-create-new-file [editorType] [fileName] (e.g. /figma-create-new-file figjam My Whiteboard)
+disable-model-invocation: true
 ---
 
 # create_new_file — Create a New Figma File

plugins/figma/skills/figma-generate-diagram/LICENSE.txt

@@ -0,0 +1,2 @@
+Use of these Figma skills and related files ("Materials") is governed by the Figma Developer Terms (available at https://www.figma.com/legal/developer-terms/). By accessing, downloading, or using these Materials — including through automated systems or AI agents — you agree to the Figma Developer Terms.
+These Materials are currently offered as a Beta feature. Figma may modify, suspend, or discontinue them at any time without notice.

plugins/figma/skills/figma-generate-diagram/SKILL.md

@@ -0,0 +1,112 @@
+---
+name: figma-generate-diagram
+description: "MANDATORY prerequisite — load this skill BEFORE every `generate_diagram` tool call. Routes to type-specific guidance (generic flowchart, architecture flowchart) and tells you when to proceed directly, when to use a different diagram type, or when the tool isn't the right fit at all."
+disable-model-invocation: false
+---
+
+# generate-diagram
+
+**You MUST load this skill before every `generate_diagram` tool call.** Skipping it causes preventable rendering failures and low-quality output.
+
+`generate_diagram` takes Mermaid.js syntax and produces an editable FigJam diagram. This skill routes you to the right per-type guidance and sets universal constraints.
+
+## Step 1: Is `generate_diagram` the right tool?
+
+### Supported diagram types
+
+`flowchart`, `sequenceDiagram`, `stateDiagram` / `stateDiagram-v2`, `gantt`, `erDiagram`.
+
+### Unsupported — don't call the tool
+
+If the user wants any of these, tell them directly that `generate_diagram` doesn't support it instead of calling the tool and failing:
+- **Pie chart, mindmap, venn diagram, class diagram, journey, timeline, quadrant, C4, git graph, requirement diagram**
+
+### When to push the user to edit in Figma
+
+The tool cannot:
+- Change fonts on an existing diagram
+- Move individual shapes
+- Edit a diagram node-by-node after generation
+
+If the user asks for any of those on an existing diagram, recommend they open the diagram in Figma and edit there. For content-level changes, it's usually faster to regenerate.
+
+## Step 2: Pick the diagram type
+
+Lightweight routing — use the first match.
+
+| User wants… | Type | Next step |
+|---|---|---|
+| Services + datastores + queues + integrations | **Architecture flowchart** | Read [references/architecture.md](./references/architecture.md) |
+| Decision tree, process flow, pipeline, dependency graph, user journey | **Flowchart** | Read [references/flowchart.md](./references/flowchart.md) |
+| Interactions between parties over time (API calls, auth, messaging) | **Sequence diagram** | Read [references/sequence.md](./references/sequence.md) |
+| Data model, tables, keys, cardinality | **ER diagram** | Read [references/erd.md](./references/erd.md) |
+| Named states with transitions between them | **State diagram** | Read [references/state.md](./references/state.md) |
+| Project schedule with dates, milestones | **Gantt chart** | Read [references/gantt.md](./references/gantt.md) |
+
+If a flowchart is requested and it describes software infrastructure (services, datastores, queues, external integrations), route to `architecture.md` — not `flowchart.md`. When in doubt, ask the user.
+
+## Step 3: Universal constraints (apply to every diagram type)
+
+1. **No emojis** in any part of the Mermaid source. The tool rejects them.
+2. **No `\n`** in labels. Use newlines only when absolutely required and only via actual line breaks (not the escape sequence).
+3. **No HTML tags** in labels.
+4. **Reserved words** — don't use `end`, `subgraph`, `graph` as node IDs.
+5. **Node IDs**: camelCase (`userService`), no spaces. Underscores can break edge routing in some processors.
+6. **Special characters in labels** must be wrapped in quotes: `A["Process (main)"]`, `-->|"O(1) lookup"|`.
+7. **Sequence diagrams** — do not use notes.
+8. **Gantt charts** — do not use color styling.
+
+## Step 4: Garbage in, garbage out
+
+The quality of the generated diagram is bounded by the quality of the Mermaid you produce, which is bounded by the context you have. Before writing Mermaid, make sure you have enough real information to describe the subject accurately — and use whatever the current environment gives you to gather it.
+
+Depending on what's available, useful sources of context include:
+
+- **Source code** — grep/read the relevant files so the diagram reflects real service names, real edge labels, real data stores, real entry points. Walking actual routes/handlers/consumers beats recreating from memory.
+- **User-provided documents** — a PRD, spec, meeting notes, transcript, research synthesis, onboarding doc, process write-up. Ask the user to paste or attach it if the subject isn't code.
+- **Existing Figma or FigJam files** — if the new diagram should align with one the user already has, read it with `get_figjam` or `get_design_context` (see the `figma-use` and `figma-use-figjam` skills).
+- **Other MCP servers or tools you have available** — issue trackers, docs sites, CRMs, analytics, internal wikis, design systems, database schemas, etc. If a connected tool holds the ground truth for what you're diagramming, pull from it rather than guessing.
+- **The user themselves** — when the description is thin or ambiguous (unclear direction of flow, unclear scope, unclear which entities matter), ask one or two focused questions before generating. Examples: "What are the 3–5 main steps?", "Who owns each step?", "What triggers the next step?". One good question beats one wasted diagram.
+
+Don't invent edges, labels, or entities to "round out" a diagram. Missing information is better than hallucinated information — leave a gap and flag it to the user.
+
+## Step 5: Will the diagram need more than Mermaid can express?
+
+Mermaid can't do everything. Sticky-note annotations tied to specific nodes, per-node domain coloring on ERDs, callouts with attached data — these all require composing `generate_diagram` with `use_figma` (via the [figma-use-figjam](../figma-use-figjam/SKILL.md) skill). This is the **hybrid workflow**.
+
+It's a judgment call, not a default. Deploy it when the user's ask clearly benefits — skip it when the base diagram is obviously enough. Signals that say yes: user explicitly asked for notes, colors, callouts, or "X attached to each node"; they shared data that maps to specific nodes; the diagram is a shareable artifact, not a thinking sketch. Signals that say no: short/self-explanatory request, small diagram, user exploring or testing.
+
+**If hybrid is warranted, read [references/workflow.md](./references/workflow.md) before calling `generate_diagram`** — it covers the pattern, two core recipes (annotations + color-coding), communication style, and failure handling. If not, proceed directly to Step 6.
+
+## Step 6: Calling the tool
+
+Required:
+- `name`: a descriptive title (shown to the user)
+- `mermaidSyntax`: the Mermaid source
+
+Optional:
+- `userIntent`: a short sentence describing what the user is trying to accomplish — helps telemetry and downstream tuning
+- `useArchitectureLayoutCode`: **only for architecture diagrams**; value is specified in `references/architecture.md`
+- `fileKey`: if the user wants the diagram added to an existing FigJam file instead of a new one
+
+Do **not** call `create_new_file` before `generate_diagram` — the tool creates its own file.
+
+## Step 7: After generation
+
+- The tool returns a link (or widget) the user can click to open the diagram in FigJam. Show it as a markdown link unless the client renders an inline widget.
+- If extensions are warranted (see Step 5), compose with `use_figma` now — the pattern and recipes are in [references/workflow.md](./references/workflow.md).
+- If the user is dissatisfied after 2 attempts at the same diagram, stop regenerating. Ask what specifically is wrong, or suggest they open it in Figma and edit manually rather than burning more tool calls.
+
+### Reuse the same file when iterating or adding related diagrams
+
+Every call to `generate_diagram` without a `fileKey` creates a new FigJam file in the user's drafts. Regenerating 4 times = 4 draft files to clean up. Prefer reusing the existing file when:
+
+- The user is iterating on the same diagram ("try again with…", "change the labels…").
+- The user wants a follow-up diagram that lives alongside the first (e.g. a sequence diagram next to a flowchart of the same system).
+
+How to reuse:
+
+1. **Pass `fileKey`** on subsequent `generate_diagram` calls. Extract from a `figma.com/board/{fileKey}/...` URL. The diagram is added to the existing file rather than creating a new one.
+2. If you want to replace the previous diagram rather than adding next to it, use the `use_figma` tool (see the `figma-use-figjam` skill) to delete the old diagram's nodes first, then call `generate_diagram` with the same `fileKey`. Or leave the old diagram and place the new one beside it — readers often benefit from seeing the history of attempts.
+
+Ask the user which they prefer the first time you iterate — "regenerate over the old one, or keep both side-by-side?" — and remember their answer for subsequent iterations in the session.

plugins/figma/skills/figma-generate-diagram/agents/openai.yaml

@@ -0,0 +1,4 @@
+interface:
+  display_name: "Generate Diagram"
+  short_description: "Create editable FigJam diagrams from Mermaid"
+  default_prompt: "Generate an editable FigJam diagram from this request, choosing the right Mermaid diagram type and syntax."

plugins/figma/skills/figma-generate-diagram/references/architecture.md

@@ -0,0 +1,149 @@
+# Architecture Diagrams
+
+Use this reference when the user asks for a **software architecture diagram** — a view showing services, datastores, message queues, external integrations, and how they connect. These are flowcharts rendered by a bespoke grid-based layout (not ELK), controlled by the `useArchitectureLayoutCode` parameter on `generate_diagram`.
+
+For generic flowcharts (decision trees, process flows, dependency graphs), use [flowchart.md](./flowchart.md) instead.
+
+---
+
+## Rules (read all before writing any Mermaid)
+
+1. Always `flowchart LR` (left-to-right).
+2. Every node = one independently deployable unit. Never decompose a service into internal modules.
+3. **Every node MUST be inside a subgraph.** No `classDef`, `class`, or `style` statements needed.
+4. **Subgraph IDs must be EXACTLY one of:** `client`, `gateway`, `service`, `datastore`, `external`, `async`. Use display labels for titles: `subgraph service ["Core Services"]`. **WRONG:** `subgraph Services`. **RIGHT:** `subgraph service`.
+5. Core flow edges use `-->` or `<-->` and must form a DAG across client -> gateway -> service -> datastore (no cycles) or the tool will error.
+6. Bidirectional edges must be written in forward direction: `client <-->|"WS"| gateway` not `gateway <-->|"WS"| client`. Bidirectional async (`<-.->`) is not supported and will fall back to a forward edge.
+7. **Backward edges** use `<---`: write left node first, arrow points left. `orderService <---|"Refund"| paymentService`.
+8. **ALL edges touching an async or external node MUST use dotted syntax (`-.->`)** for both directions. Never use `==>`.
+9. Never connect edges to subgraph IDs — only individual node IDs.
+10. Never create two edges between the same pair of nodes. Combine into one edge with a merged label.
+11. **Never connect datastore or async nodes to each other directly.** A service always mediates. WRONG: `kafka -.-> sqs`. RIGHT: `worker -.->|"Consumes"| kafka` then `worker -.->|"Produces"| sqs`.
+
+## Subgraph Categories
+
+Layout order: client -> gateway -> service -> datastore. External and async are placed above/below the service+datastore lanes. Colors and shapes are auto-assigned — use plain `[text]` syntax for all nodes.
+
+| Subgraph ID | What Belongs Here |
+|---|---|
+| `client` | Web/mobile/desktop apps, CLI, end users |
+| `gateway` | CDN, load balancer, API gateway, reverse proxy |
+| `service` | Microservices, monoliths, serverless, ETL, async workers, cron jobs |
+| `datastore` | Databases, caches, object storage (PostgreSQL, Redis, S3, Elasticsearch) |
+| `external` | Feature flags, monitoring, payment, OAuth, third-party SaaS |
+| `async` | Message infrastructure: Kafka, RabbitMQ, SQS, Pub/Sub, EventBridge, Redis Streams |
+
+## Async Subgraph
+
+**Async nodes = independently deployable message infrastructure.**
+
+Does NOT belong in `async`:
+- Consumer workers -> `service`
+- DB replication features (WAL, CDC) -> omit or use a dotted edge label from `datastore`
+- Logical splits of a single broker -> use one node
+
+Canonical pattern: `service -.->|"Produce"| queue` and `queue -.->|"Consume"| service`
+
+## Node Granularity
+
+"Can I deploy, restart, or scale this independently?" Yes = node. No = omit.
+
+## Edge Types
+
+| Category | Syntax | Use For |
+|----------|--------|---------|
+| **Forward** | `-->` | Normal left-to-right data flow |
+| **Bidirectional** | `<-->` | WebSocket, gRPC streaming (write in forward direction) |
+| **Backward** | `<---` | Return flows, invalidation (left node first) |
+| **Async/External** | `-.->` | Any edge touching async or external nodes |
+
+### Edge Decision
+
+1. Either endpoint is async or external? -> `-.->`
+2. Real-time bidirectional channel? -> `<-->`
+3. Backward-flowing between core nodes? -> `<---` (left node first)
+4. Otherwise -> `-->`
+
+### Key Patterns
+
+| Pattern | Syntax | Label Examples |
+|---------|--------|---------------|
+| client -> gateway | `-->` | "HTTPS" |
+| service -> datastore | `-->` | "Read/Write", "Query" |
+| service -> async | `-.->` | "Produce Events" |
+| async -> service | `-.->` | "Consume", "Fan Out" |
+| service -> external | `-.->` | "ServiceName: Purpose" |
+| service <- service | `<---` | "Invalidate", "Refund" |
+
+> **External edges** render to the section boundary. Include the service name in the label: `"ServiceName: Purpose"`.
+
+### Best Practices
+
+1. **One flow per diagram.** Focus on the architecture the user asked about.
+2. **Max 15-20 edges.** Omit edges unrelated to the requested flow.
+3. **Label every cross-subgraph edge.** Use a verb from the source node's perspective, with specifics when relevant (e.g., "Reads Users", "Writes Orders", "Produces"). 1-4 words max.
+4. **Bidirectional = one `<-->` edge.** Never split into separate `-->` and `-.->`.
+
+## Validation Checklist
+
+Before finalizing the diagram, verify:
+1. **Forward and bidirectional edges must form a DAG.** Any edges that would form a cycle must be represented as a backward edge.
+2. **Every service has both input and output.** For each service node, ask: "Where does it get data from?" and "Where does it return data to?" If either answer is missing, add the edge.
+3. **Walk each service node one by one.** List every service node, then for each one confirm it has at least one incoming edge and one outgoing edge. If not, fix it before calling generate_diagram.
+4. **Do not hallucinate labels or edges.** Ask the user questions when there is ambiguity.
+
+## Mermaid Syntax Rules
+
+1. Node IDs: camelCase, no spaces or underscores (`userService` not `user service` or `user_service`). The layout code splits on `_` internally, so underscores in IDs will break edge routing.
+2. Labels with special chars: wrap in double quotes (`A["Process (main)"]`).
+3. Edge labels with special chars: wrap in quotes (`-->|"O(1) lookup"|`).
+4. Avoid reserved words as node IDs: `end`, `subgraph`, `graph`.
+5. No HTML tags or emojis in labels.
+
+## Complete Example
+
+```mermaid
+flowchart LR
+    subgraph client ["Client Apps"]
+        web[Web App]
+        mobile[Mobile App]
+    end
+    subgraph gateway ["API Layer"]
+        alb[Load Balancer]
+    end
+    subgraph service ["Core Services"]
+        auth[Auth Service]
+        orders[Order Service]
+        notify[Notification Service]
+    end
+    subgraph datastore ["Data Stores"]
+        pg[PostgreSQL]
+        redis[Redis]
+    end
+    subgraph external ["External"]
+        stripe[Stripe]
+    end
+    subgraph async ["Event Streaming"]
+        orderQ[Order Queue]
+    end
+
+    web -->|"HTTPS"| alb
+    mobile -->|"HTTPS"| alb
+    web <-->|"WebSocket"| alb
+    alb -->|"Routes /auth"| auth
+    alb -->|"Routes /orders"| orders
+    auth -->|"Reads Sessions"| redis
+    orders -->|"Writes Orders"| pg
+    orders -.->|"Produces"| orderQ
+    notify -.->|"Consumes"| orderQ
+    orders -.->|"Stripe: Charges"| stripe
+```
+
+## Calling generate_diagram
+
+When calling `generate_diagram` for an architecture diagram, pass:
+
+- `name`: A descriptive diagram name
+- `mermaidSyntax`: Your Mermaid syntax following all rules above
+- `useArchitectureLayoutCode`: `"FIGMA_DIAGRAM_2026"`
+- `userIntent` (optional): What the user is trying to accomplish