figma/generate-project-plan

generate-project-plan

Turn a PRD (plus optional codebase grounding) into a FigJam project plan board. Section set is not fixed — the skill proposes candidates from the research and the user picks which to include. For each picked section, the skill proposes content + rendering shape (block) and the user confirms.

Mandatory prerequisites

Foundation skills (load by name; available in figma/mcp-server-guide):

• figma-use — Load once per session. Stays in context for all use_figma calls.
• figma-use-figjam — Re-load before every use_figma call.
• figma-generate-diagram — Re-load before every generate_diagram call.

Foundation references (in this plugin):

• foundation/palette.md — section + sticky + text palette constants (hex/255).
• foundation/layout.md — canvas geometry, sizing rules, placeholder lifecycle.
• foundation/plugin-api-traps.md — documented traps for FigJam use_figma.
• foundation/codebase-grounding.md — Step 1 expansion rules.

Section catalog:

• section-catalog.md — the ~10 candidate sections with default blocks and palette.

Block subskills (one per content type — re-load the one(s) you need before each use_figma fill call):

| Block | File | When to load | |---|---|---| | Top-level section | blocks/section.md | Skeleton pass (Step 6) and every fill call (Step 7) | | Nested section | blocks/nested-section.md | Fills that group sub-content (e.g. "Design Decisions 1/2/3") | | Intro callout | blocks/intro-callout.md | Fills that open with a highlighted intro (e.g. Motivation) | | Text primitives | blocks/text-primitives.md | Any fill that uses body paragraphs, H3 subheaders, or bulleted lists | | Table | blocks/table.md | Fills with structured data (Resources, Goals, Dependencies, Rollout, Milestones) | | Multi-column text | blocks/multi-column-text.md | Fills with 2–4 option columns (Design Decisions alternatives) | | Sticky column | blocks/sticky-column.md | Fills with lists of stickies (Success Metrics, Risks, Open Questions) | | Diagram section | blocks/diagram-section.md | Right-column diagram sections (Step 8) | | Metadata strip | blocks/metadata-strip.md | Skeleton pass — one metadata strip at top of board |

Also pass skillNames: "figma-use,figma-use-figjam,generate-project-plan" on use_figma calls (logging only).

Visual UI conventions — STRICT, do not deviate

These are derived from a canonical reference board. Read the source-of-truth files for the full constants; this section is a single-place summary so an agent can answer "what color / size / font / padding?" without hunting.

Colors (two-tone per section)

Every left-column section uses two coordinated colors of the same hue: a very-pale ARCH_PALE background, and a slightly-more-saturated FigJam-SECTION palette color for any table header inside that section. Right-column diagram sections are pure white.

| Section bg (ARCH_PALE.X) | Table header (TABLE_HEADER.lightX) | Hue | |---|---|---| | #F8F5FF | #DCCCFF | violet | | #EBFFEE | #CDF4D3 | green | | #DBF0FF | #C2E5FF | blue | | #F5FBFF (alt) | #C2E5FF | pale blue | | #FFF7F0 | #FFE0C2 | orange | | #F1FEFD | #C6FAF6 | teal | | #FFFBF0 | #FFEC BD | yellow | | #FFEEF8 | #FFC2EC | pink | | #FFEEE8 | #FFCDC2 | red |

Source: references/foundation/palette.md. Never use the dark-saturated palette (#874FFF, #3DADFF, etc.) for table headers — that's for FigJam's standalone tables, not project-plan boards.

Architecture-diagram subgraph colors are auto-applied by generate_diagram and must not be overridden. Their canonical values: client #AFF4C6 rounded-rect, gateway #FFFFFF square (diamond if labeled "Load Balancer"/"ALB"/"LB"), service #E4CCFF square, datastore #BDE3FF cylinder, external #FFFFFF PREDEFINED_PROCESS, async #BDE3FF ENG_QUEUE.

Typography (font sizes)

| Element | Size | Font | Color | |---|---|---|---| | H1 (board title) | 40 | Inter Medium | #1E1E1E | | H2 (section title — first child of every section) | 40 | Inter Medium | #1E1E1E | | H3 — full-width subhead (e.g. "Resources" inside Motivation) | 40 | Inter Medium | #1E1E1E | | H3 — nested-section header (e.g. "Design Decision 1: …") | 32 | Inter Medium | #1E1E1E | | H3 — column title in 2/3/4-col layouts (Risks col, Goals col) | 24 | Inter Medium | #1E1E1E | | Body text | 16 | Inter Medium | #1E1E1E | | Table cells (header AND body) | 16 | Inter Bold | #1E1E1E |

The three different H3 sizes are deliberate. 40 = matches H2 weight when subhead is alone in the section. 32 = sub-section header inside a child section (672px inner width). 24 = column title in narrow contexts (≤ 224px col width). Pick by container width, not by semantic depth.

Always load both Inter Medium AND Inter Bold at the top of any use_figma script that creates tables (Bold) plus any other text (Medium).

Section properties

| Property | Value | |---|---| | section.fills | [{ type: 'SOLID', color: ARCH_PALE.X }] (left column) or ARCH_PALE.white (right column / diagrams) | | section.name | "" — empty string. NO FigJam title-bar label. The H2 inside is the only title. | | Inner padding (all 4 sides) | 32 (current default; reference uses 40-50, kept at 32 for now) | | First child position | (32, 32) | | Width (left column) | 800 | | Width (right column / diagram) | max(1200, diag.width + 64) after diagram is reparented | | Vertical gap between sections (inside the wrapper) | 64 | | Hug behavior | Manual: call section.resizeWithoutConstraints(w, maxChildBottom + 32) after appending children. Sections do NOT auto-grow. | | Placeholder during build | placeholder = true in skeleton pass; placeholder = false at the end of the section's fill. |

Outer wrapper + column alignment (STRICT defaults)

The board has one outer wrapper (unlabeled, white) plus the diagram column:

1. Column wrapper — an unlabeled white SECTION at (_, 0). Contains, in order from top:
   • H1 project title (40px Inter Medium, charcoal) at (64, 64) (= section padding)
   • Body row of metadata: Owner / Status / Last updated / Source (16px Inter Medium, charcoal), at (64, h1.y + h1.height + 16) — 16px gap below H1; 32px gap between each body cell
   • 64px gap below the body row, then the 6 left-column sections stacked with 64px gutter
2. Diagram column at (columnWrapperRight + 64, 0). Each diagram is its own un-wrapped white SECTION; the top diagram's y aligns with the column wrapper's y (= 0). Diagrams stack with 64px gutter.

The metadata is embedded in the column wrapper (NOT a separate section). One column wrapper holds everything text-related.

Constants:

• Wrapper inner padding (all 4 sides): 64
• Vertical gap between sections inside the wrapper: 64
• Horizontal gap between wrapper right edge and diagram-column left edge: 64
• Top of the diagram column aligns with wrapper.y (same horizontal axis as the wrapper top edge)
• Vertical gap between stacked diagram sections: 64 (matches the inner gutter)

const PAD = 64;
const leftIds = [/* all left-column section ids in order */];
const sections = [];
for (const id of leftIds) sections.push(await figma.getNodeByIdAsync(id));

// Compute bbox of the column in page coords
let minX = Infinity, minY = Infinity, maxX = -Infinity, maxY = -Infinity;
for (const s of sections) {
  minX = Math.min(minX, s.x); minY = Math.min(minY, s.y);
  maxX = Math.max(maxX, s.x + s.width); maxY = Math.max(maxY, s.y + s.height);
}

const wrapper = figma.createSection();
wrapper.name = "";                                                              // STRICT
wrapper.fills = [{ type: 'SOLID', color: WHITE }];                              // ARCH_PALE.white
wrapper.resizeWithoutConstraints((maxX - minX) + 2*PAD, (maxY - minY) + 2*PAD);
wrapper.x = minX - PAD;
wrapper.y = minY - PAD;

// Reparent + translate to keep visual positions
for (const s of sections) {
  const newX = (s.x - minX) + PAD;
  const newY = (s.y - minY) + PAD;
  wrapper.appendChild(s);
  s.x = newX;
  s.y = newY;
}

The wrapper has no header (no H2 inside) and no name — it's a pure container. Don't repeat the project title here; that lives in the metadata strip.

Position the diagram column after the wrapper exists:

const wrapperRight = wrapper.x + wrapper.width;
const diagramX = wrapperRight + 64;       // 64px horizontal gap matches inter-section gutter
let y = wrapper.y;                          // align top with wrapper's top edge
for (const id of diagramSectionIdsInOrder) {
  const d = await figma.getNodeByIdAsync(id);
  d.x = diagramX;
  d.y = y;
  y += d.height + 64;                     // 64px vertical gutter between stacked diagrams
}

Vertical spacing (STRICT)

| Between | Gap | |---|---| | Section top edge → H2 (first child) | 32 (= padding) | | H2 → next child (body / intro callout / H3 / table / first column) | 24 | | Body paragraph → H3 | 24 | | H3 (any size: 40 / 32 / 24) → next child (body / table / list / column content) | 24 | | Body → body | 24 | | List → next block | 24 | | Last child bottom → section bottom edge | 32 (= padding) |

Always position children using prevChild.y + prevChild.height + 24 — never use a fixed offset like prevChild.y + 60. The H3 has three different sizes (40 / 32 / 24), so a fixed offset is wrong by definition; always read prevChild.height after the font size is set.

When you change a header's font size after the fact, you MUST re-stack downstream children. Setting h3.fontSize = 40 grows the node's height; if the next child's y was computed before the resize, it will overlap.

Tables

• Both header AND body cells use Inter Bold 16px (NOT Medium).
• Header text is #1E1E1E charcoal on a light fill (matching the section's hue).
• Body cells leave fill at default white; text is charcoal.
• Headers do NOT use white-on-dark — that's wrong for this board style.

Diagrams (right column)

generate_diagram with useArchitectureLayoutCode: "FIGMA_DIAGRAM_2026" produces multiple page-level nodes (1–2 subgraph SECTIONs + bare SHAPE_WITH_TEXTs + CONNECTORs), NOT a single container. To wrap them in a section:

1. Collect all new page-level nodes (exclude known plan-section IDs).
2. Compute the bbox.
3. Create a new SECTION sized to bboxW + 64 × bboxH + 64 + 64 (HEADER_BLOCK = 40 H2 + 24 gap), fill ARCH_PALE.white.
4. Reparent each diagram node, translating local coords to maintain visual layout.
5. CRITICAL — delete and recreate every connector after reparent. The assign-to-self trick (c.connectorStart = c.connectorStart) is NOT reliable: short connectors re-route fine, but long-bend connectors retain stale elbow waypoints and extend hundreds of pixels outside the section. Delete + figma.createConnector() from captured spec produces a clean route every time. See blocks/diagram-section.md for the spec-capture + recreate pattern.
6. Connector labels — explicit fontName + fontSize + fills ALL required. A fresh connector's text sublayer has no usable defaults. Set ALL FOUR: c.text.fontName = { family: 'Inter', style: 'Medium' }, c.text.fontSize = 14, c.text.characters = label, c.text.fills = [{ type: 'SOLID', color: CHARCOAL }]. Default text.fills is [] (empty array) so the label renders transparent and is invisible — read-back of c.text.characters lies; verify with a screenshot.

Diagram-section convention: section.name = "", H2 text node inside as the title (matches the rest of the board).

What NOT to use (common wrong defaults)

| Don't use | Use instead | Why | |---|---|---| | #CDF4D3 (FigJam lightGreen) for section bg | #EBFFEE (ARCH_PALE.green) | Too saturated next to diagrams | | #C2E5FF (FigJam lightBlue) for section bg | #DBF0FF or #F5FBFF (ARCH_PALE.blue / blueLite) | Same | | #874FFF (FigJam dark violet) for table header | #DCCCFF (FigJam lightViolet) | Reference uses light-on-pale, not dark-on-pale | | White text on dark table header | #1E1E1E charcoal text on light header | Same — pale-on-pale convention | | Inter Medium for table cells | Inter Bold | Reference uses Bold for all cells | | section.name = "Goals" (or any non-empty string) | section.name = "" | Reference uses empty names; H2 inside is the title | | Reparenting only one subgraph from a generated diagram | Reparent ALL page-level nodes (SECTIONs + SHAPEs + CONNECTORs) | Architecture diagrams are not single nodes | | Trusting c.connectorStart = c.connectorStart to re-route every connector | After reparent, delete and recreate every connector from a captured spec | Long-bend connectors retain stale elbow waypoints; only figma.createConnector() produces a fresh route | | Setting only c.text.characters = label on a fresh connector | Set c.text.fontName, c.text.fontSize, c.text.characters, AND c.text.fills | Defaults: fontSize=missing, fills=[] (empty array → transparent) → label invisible despite correct read-back |

Step template

Every step below uses this shape. Read the step, then execute.

## Step N — <Name>  [Type: Research | Confirm | Write]
Inputs required: …
Ask if missing: …
Tools / refs loaded: …
Do: (3–6 action bullets)
Checkpoint: (Research → self-check; Confirm → AskUserQuestion; Write → screenshot + AskUserQuestion)

Three step types:

• Research — read-only; checkpoint = self-check list.
• Confirm — no board writes, user decision gate; checkpoint = AskUserQuestion.
• Write — creates/mutates FigJam; checkpoint = screenshot + AskUserQuestion.

---

Step 1 — Gather context [Research]

Inputs required

• PRD file path or pasted text.
• Optional: codebase entry points (file paths, service names, doc paths).

Ask if missing

• "Where's the PRD? (path or paste)."
• "Any codebase entry points I should ground in? (paths / services / docs / 'none')."

Tools / refs loaded

• Read, Glob, Grep.
• foundation/codebase-grounding.md.

Do

1. Read the PRD. Extract: title, problem, goals, non-goals, owner, audience, success metrics, rollout hints, risks.
2. If entry points provided: follow codebase-grounding.md — bounded 20-file cap, depth-1 imports, walk up to CLAUDE.md/ARCHITECTURE.md/OWNERS.
3. Produce the tech-context object: files_read, services, external_deps, key_modules, architecture_notes, ownership, expansion_truncated.

Self-check

• Have: project title, problem statement, at least 1 concrete goal, owner (or "TBD"), services touched (or empty list with a reason).
• Enough signal to draft candidate section cards in Step 2. If not, loop back and ask.

---

Step 2 — Propose candidate sections [Confirm]

Inputs required

• Tech-context object from Step 1.

Tools / refs loaded

• section-catalog.md.
• AskUserQuestion.

Do

1. For each section in the catalog, decide if there is real content for it from Step 1. Skip catalog entries that would be empty or padding.
2. For each qualifying candidate, produce a card:
   • Title (catalog name)
   • 1-line description (what this section will contain, specific to the PRD)
   • Why suggested (which PRD facts or tech-context items justify it)
   • Default block shape (from the catalog)
3. Print all cards to chat.
4. Fire AskUserQuestion with a multiSelect question per batch of ≤4 candidates (max 4 questions per call, 4 options each → up to 16 candidates per call). Each option's label is the section title; description is the 1-line summary.

Checkpoint (AskUserQuestion)

• The multiSelect questions above. User ticks the sections they want. Store the selected set as approved_sections.
• If zero sections selected → stop with a clean exit message. No file is created.

---

Step 3 — Per-section deep research [Research]

Inputs required

• approved_sections from Step 2; tech-context from Step 1.

Tools / refs loaded

• Read, Grep, Glob (optional).

Do

1. For each section in approved_sections, look up its catalog entry. The catalog declares what the section needs (e.g. Dependencies needs cross-team services + external deps + blockers).
2. Compare what the section needs vs. what the tech-context has.
3. Produce a gap list per section: specific facts the user must supply, framed as answerable questions (no "figure it out yourself" gaps).

Self-check

• Every approved_sections entry has either ready (no gaps) or a specific non-empty gap list.
• Gaps are answerable — not vague prompts like "tell me more about X."

---

Step 4 — Per-section content + block proposal [Confirm]

Inputs required

• Gap lists from Step 3.

Tools / refs loaded

• AskUserQuestion.
• section-catalog.md.
• Block reference(s) for the section's default shape (e.g. blocks/table.md for Dependencies).

Do, per section (one at a time, or small batch if trivial):

1. Fill the gap list — free-text prompt for prose; AskUserQuestion for bounded choices.
2. Propose:
   • Content: the concrete bullets / rows / stickies that will appear.
   • Block shape: the rendering block (body paragraph / table / multi-column / sticky column / …). Default from section-catalog.md; offer alternative shapes where sensible (e.g. "As a table, or as a multi-column layout?").
3. Show a short preview — section title + first line of body + block type summary.
4. Fire AskUserQuestion: "Use this content + shape? [Yes / Edit / Skip this section]."
5. Edit → accept free-text amendments, re-show, re-ask. Skip → mark the section as skipped; do not write it to the board.

Checkpoint

• Every section is approved, edited+approved, or skipped. No board writes yet.

---

Step 5 — Create FigJam file [Write]

Inputs required

• approved_sections (non-skipped); project title; planKey (Figma team plan).

Tools / refs loaded

• create_new_file MCP tool.
• whoami MCP tool (for planKey if not known).
• use_figma (once).
• figma-use (already in context from Step 5 onward).
• figma-use-figjam (re-loaded for the probe).
• AskUserQuestion.

Do

1. Resolve planKey: call whoami. If one plan → use it. If multiple → AskUserQuestion which team.
2. Call create_new_file with { planKey, fileName: "<project title>", editorType: "figjam" }. Capture file_key + file_url.
3. Run the first-run probe (use_figma):

const page = figma.currentPage;
return {
  rootName: figma.root.name,
  editorType: figma.editorType,
  pageCount: figma.root.children.length,
  firstPageName: figma.root.children[0].name,
  currentPageChildrenCount: page.children.length,
};

Expect editorType === "figjam" and empty page. If not, halt and report.

Checkpoint (probe output + AskUserQuestion)

• Print probe return + file_url.
• AskUserQuestion: "File created at <file_url> — proceed to skeleton? [Yes / Cancel]." Cancel = stop, leave empty file.

---

Step 6 — Skeleton pass [Write]

Inputs required

• approved_sections in taxonomy order; palette from foundation/palette.md; layout constants from foundation/layout.md.

Tools / refs loaded

• use_figma (one call).
• Re-load figma-use-figjam/SKILL.md.
• Re-load blocks/section.md and blocks/metadata-strip.md.
• foundation/palette.md, foundation/layout.md.

Do

1. Create metadata strip per blocks/metadata-strip.md (H1 + 4 body texts at board (0, 0)–(0, ~100)).
2. For each approved section, create a top-level SECTION per blocks/section.md — colored bg from ARCH_PALE, section.name = "" (no title-bar label — STRICT), placeholder = true, resizeWithoutConstraints(LEFT_COL_W, DEFAULT_H) for left-column sections or resizeWithoutConstraints(RIGHT_COL_W_MIN, DEFAULT_H) for right-column diagram sections.
3. Position each left-column section at (0, SECTION_TOP_Y + cumulative_y). Right-column sections at (832, SECTION_TOP_Y + cumulative_y_right).
4. Return all created node IDs: { createdNodeIds: { metadataStrip: {...}, sections: { <slug>: "<id>", ... } }, status: "skeleton-complete" }. (The slug is internal, used to look up palette + drive Step 7 fills. It is never written to section.name.)
5. Take an inline screenshot at await figma.currentPage.screenshot({ scale: 0.3 }).

Checkpoint (screenshot + AskUserQuestion)

• AskUserQuestion: "Skeleton looks right? [Yes / Fix / Cancel]." Fix = targeted fix script; Cancel = stop.

---

Step 7 — Fill pass (one call per section) [Write]

Inputs required

• Approved content + block shape for each section; section ID from Step 6.

Tools / refs loaded

• use_figma (one call per section).
• Re-load figma-use-figjam/SKILL.md.
• Re-load whichever block refs this section uses:
  • blocks/section.md always.
  • blocks/text-primitives.md if body/H3/list.
  • blocks/table.md if table.
  • blocks/multi-column-text.md if multi-column.
  • blocks/nested-section.md if nested subsections.
  • blocks/intro-callout.md if highlighted intro.
  • blocks/sticky-column.md if stickies.

Do, per section:

1. await figma.getNodeByIdAsync(sectionId) — confirm type is SECTION.
2. Build content: H2 header first, then children per approved block shape. Append to section FIRST, then set x/y.
3. Two-pass measure for stickies per blocks/sticky-column.md.
4. section.resizeWithoutConstraints(LEFT_COL_W, computed_height).
5. section.placeholder = false.
6. await section.screenshot() inline.
7. return { mutatedNodeIds: [...], sectionHeight, screenshotIncluded: true }.

Checkpoint (screenshot + AskUserQuestion)

• Per section: AskUserQuestion: "Section <name> done? [Yes / Edit this section / Skip rest]." Edit = targeted fix; Skip rest = exit fill loop (user will finalize manually).

After all left-column fills: run the re-stack pass (single use_figma) to fix cumulative Y based on actual resized heights:

let y = SECTION_TOP_Y;
for (const id of leftColumnSectionIdsInOrder) {
  const sec = await figma.getNodeByIdAsync(id);
  sec.y = y;
  sec.x = 0;
  y += sec.height + 32;
}
return { mutatedNodeIds: leftColumnSectionIdsInOrder };

Then run the outer-wrapper pass (single use_figma) — wrap all left-column sections in an unlabeled white outer SECTION (see "Outer column wrapper" in the visual conventions block above). This is STRICT; do not skip.

---

Step 8 — Diagrams [Write]

Inputs required

• Diagram intents from Step 2/4 (Current State, Target State, 0–N Key Flows); tech-context for Mermaid composition.

Tools / refs loaded

• Re-load generate-diagram/SKILL.md before each generate_diagram call.
• Re-load figma-use-figjam/SKILL.md + blocks/diagram-section.md before each reparent use_figma call.
• generate_diagram MCP tool, use_figma.

Do, per diagram:

1. use_figma: create the right-column section (white fill, H2 header, placeholder = true) per blocks/diagram-section.md.
2. generate_diagram: compose Mermaid from tech-context; architecture diagrams use useArchitectureLayoutCode: "FIGMA_DIAGRAM_2026".
3. use_figma: locate the generated diagram node, reparent into the section (section.appendChild(diag)), position below H2, resize section to fit. placeholder = false.
4. await section.screenshot().

Failure handling: if generate_diagram fails, leave a text placeholder in the section reading "Diagram generation failed: <message>. Regenerate manually." Continue to the next diagram.

Checkpoint (screenshot + AskUserQuestion)

• Per diagram: AskUserQuestion: "Diagram <name> looks right? [Yes / Regenerate / Skip]."

---

Step 9 — Final review + report [Write, then Read]

Inputs required

• file_url from Step 5.

Tools / refs loaded

• use_figma (one call for full-page screenshot).

Do

1. await figma.currentPage.screenshot({ scale: 0.25 }) — full board.
2. Inspect: two-column structure, no overlaps, no sections left with placeholder = true, metadata strip visible.
3. Fix any issues with a targeted use_figma script. Do not regenerate from scratch.
4. Post to chat:

✅ Project plan written to FigJam.
File: <file_url>
Sections: <N text + N diagram>
Files referenced during grounding: <count>

Checkpoint (screenshot + AskUserQuestion)

• AskUserQuestion: "Done, or tweak? [Done / Tweak]." Tweak = targeted fix script on user's request, not regeneration.

---

Operational rules

• ≤10 logical operations per use_figma call.
• Always return createdNodeIds / mutatedNodeIds from every write script.
• Use hex/255 notation for all palette colors (see foundation/palette.md).
• STRICT: section backgrounds use the ARCH_PALE palette, NOT the FigJam standard SECTION palette. ARCH_PALE colors (#EBFFEE, #F8F5FF, #F5FBFF, #FFF7F0, etc.) visually pair with the architecture-diagram subgraph wrappers that generate_diagram produces. The FigJam SECTION palette (#CDF4D3, #C2E5FF, #DCCCFF, #FFE0C2) is too saturated and causes visible color clash next to diagrams. See foundation/palette.md.
• STRICT: section.name = "" on every project-plan section (left-column, right-column, and nested children). The user-facing title is rendered as the H2 text node inside the section, NOT via FigJam's section title-bar label. The reference board uses empty section names; setting a non-empty name produces a duplicate label that visually clutters the board.
• Read, edit, or cancel at every Confirm/Write checkpoint — never write past an unanswered AskUserQuestion.
• If a use_figma script errors: atomic — no changes made. Read the error, fix, retry.

Trigger phrases

"/generate-project-plan", "interactive project plan", "project plan", "make a FigJam project plan", "PRD to FigJam".