docs(moai-design-tools): correct Figma MCP reference to match plugin v2.1.7#690
Open
gbrinan wants to merge 1 commit intomodu-ai:mainfrom
Open
docs(moai-design-tools): correct Figma MCP reference to match plugin v2.1.7#690gbrinan wants to merge 1 commit intomodu-ai:mainfrom
gbrinan wants to merge 1 commit intomodu-ai:mainfrom
Conversation
…v2.1.7
Verified all 18 tool signatures against live `mcp__plugin_figma_figma__*`
schemas loaded via ToolSearch in Claude Code. Prior docs only listed 16
tools and contained incorrect signatures in 13 tool entries.
Key corrections in reference/figma.md:
- get_design_context: nodeId is REQUIRED (was optional); add excludeScreenshot /
forceCode / disableCodeConnect flags; return is {code, assets, screenshot?}
- get_variable_defs: nodeId is REQUIRED (per-node subtree, not per-file);
return is a flat {variableName: value} map
- get_metadata: nodeId is REQUIRED; returns XML (not JSON); warn about
Figma Make files
- get_code_connect_map / add_code_connect_map / get_code_connect_suggestions /
send_code_connect_mappings: nodeId is REQUIRED; add_code_connect_map maps
a SINGLE node (not an array); enumerate 16 framework label values; add
optional template / templateDataJson parameters
- get_figjam: nodeId is REQUIRED (use "0:1" for root); add
includeImagesOfNodes; corrected purpose (generate UI code, FigJam-only)
- generate_diagram: required params are (name, mermaidSyntax), not
(description, fileKey); creates its own FigJam file; enumerate 6
supported Mermaid types; surface URL as markdown link
- generate_figma_design: multi-step workflow with no required params on
initial call; outputMode enum (newFile|existingFile|clipboard); captureId
polling; Playwright MCP integration for external URLs
- use_figma: required params are (fileKey, code, description); code is
JavaScript (max 50,000 chars); figma-use skill is MANDATORY prerequisite;
Inter "Semi Bold" and figma.setCurrentPageAsync gotchas
- search_design_system: fileKey is REQUIRED; add includeLibraryKeys,
includeComponents/Styles/Variables, disableCodeConnect
- create_new_file: required (fileName, planKey, editorType); editorType
enum; planKey obtained from whoami()
- create_design_system_rules: returns a PROMPT for repo rules, NOT Figma-
internal rules; no `rules` parameter
New sections added:
- get_libraries (was missing): returns {subscribed, available} lists with
{name, key, description, sourceType}; feeds search_design_system's
includeLibraryKeys
- get_context_for_code_connect (was missing): returns {properties, variants,
descendantTree} for authoring .figma.ts / .figma.js Code Connect templates
Supporting corrections:
- SKILL.md: allowed-tools now registers all 18 mcp__plugin_figma_figma__*
tools; tool count "16"→"18" in key strengths and footer
- reference/comparison.md: Tools Count 16→18
- reference/figma.md: fix signatures in implement-design Workflow Step 3,
Design Token Extraction code blocks, and Examples 1/2/3 so that
tutorials match the corrected tool signatures
- Footer: Last Updated 2026-04-21; Tool Version notes plugin v2.1.7
verification
Verification: live tool schemas fetched via Claude Code ToolSearch against
plugin v2.1.7; grep confirms zero stale signatures and 17 correct-signature
matches across both copies (template source and self-hosted).
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
WalkthroughExpanded Figma MCP skill tool surface from 16 to 18 tools across moai-design-tools skill definitions and reference documentation. Updated tool signatures, workflows, and metadata to reflect node-scoped operations, Code Connect enhancements, library discovery capabilities, and design generation flows. Changes applied consistently to both primary and template skill manifests. Changes
Estimated code review effort🎯 4 (Complex) | ⏱️ ~45 minutes Possibly related PRs
Suggested labels
🚥 Pre-merge checks | ✅ 5✅ Passed checks (5 passed)
✏️ Tip: You can configure your own custom pre-merge checks in the settings. ✨ Finishing Touches🧪 Generate unit tests (beta)
Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out. Comment |
![github-actions[bot]](https://avatars.githubusercontent.com/in/15368?s=60&v=4){kind=small}
Contributor
There was a problem hiding this comment.
Welcome to moai-adk-go! Thank you for your first pull request.
Our team will review your changes shortly. Before we do, please ensure:
- All tests pass locally (
go test -race ./...) - Code follows our coding standards (run
golangci-lint run) - Commit messages follow Conventional Commits format
- Templates are regenerated if modified (
make build)
This project supports multiple languages for discussion. Feel free to write in your preferred language, though English is recommended for code reviews and commit messages.
Thank you for contributing!
![coderabbitai[bot]](https://avatars.githubusercontent.com/in/347564?s=60&v=4){kind=small}
There was a problem hiding this comment.
Actionable comments posted: 1
🤖 Prompt for all review comments with AI agents
Verify each finding against the current code and only fix it if needed.
Inline comments:
In @.claude/skills/moai-design-tools/reference/figma.md:
- Line 67: Update the fenced code blocks in
.claude/skills/moai-design-tools/reference/figma.md to include the language
identifier "text" (e.g., change ``` to ```text) for all signature/example fences
such as the blocks containing get_design_context(...) and generate_diagram(...),
and any other unnamed fences listed (lines referenced in the review). Also
change the lowercase "markdown" instance to the proper noun "Markdown" in the
nearby IMPORTANT note (the line that currently reads "- IMPORTANT: after
calling, you MUST surface the returned URL to the user as a markdown link") so
it reads "Markdown". Ensure all occurrences in the file are updated
consistently.
🪄 Autofix (Beta)
Fix all unresolved CodeRabbit comments on this PR:
- Push a commit to this branch (recommended)
- Create a new PR with the fixes
ℹ️ Review info
⚙️ Run configuration
Configuration used: Path: .coderabbit.yaml
Review profile: ASSERTIVE
Plan: Pro
Run ID: 8c0c01b5-a8ec-4dfd-b9d7-10a82af17721
📒 Files selected for processing (6)
.claude/skills/moai-design-tools/SKILL.md.claude/skills/moai-design-tools/reference/comparison.md.claude/skills/moai-design-tools/reference/figma.mdinternal/template/templates/.claude/skills/moai-design-tools/SKILL.mdinternal/template/templates/.claude/skills/moai-design-tools/reference/comparison.mdinternal/template/templates/.claude/skills/moai-design-tools/reference/figma.md
| - Optional: `excludeScreenshot` (screenshots strongly recommended), `forceCode` (always return code even if large), `disableCodeConnect`, `clientFrameworks`, `clientLanguages` | ||
| - Returns a code string plus a JSON of asset download URLs and (by default) a screenshot | ||
|
|
||
| ``` |
There was a problem hiding this comment.
Address markdownlint MD040 (and “Markdown” capitalization) to keep docs lint-clean.
Multiple fenced blocks are missing language identifiers, and Line 208 should use “Markdown” as a proper noun.
Suggested patch pattern
-```
+```text
get_design_context(fileKey, nodeId, { excludeScreenshot?, forceCode?, disableCodeConnect? }?) → { code, assets: { [assetUrl]: string }, screenshot? }- +text
generate_diagram(name, mermaidSyntax, userIntent?) → { url, ... }
-- IMPORTANT: after calling, you MUST surface the returned URL to the user as a markdown link
+- IMPORTANT: after calling, you MUST surface the returned URL to the user as a Markdown link
Apply the same ```text convention to the other signature/example fences in this file for consistency.
Also applies to: 78-78, 90-90, 102-102, 114-114, 125-125, 138-138, 150-150, 161-161, 172-172, 184-184, 197-197, 210-210, 227-227, 250-250, 261-261, 272-272, 285-285, 429-429, 439-439, 208-208
🧰 Tools
🪛 markdownlint-cli2 (0.22.0)
[warning] 67-67: Fenced code blocks should have a language specified
(MD040, fenced-code-language)
🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed.
In @.claude/skills/moai-design-tools/reference/figma.md at line 67, Update the
fenced code blocks in .claude/skills/moai-design-tools/reference/figma.md to
include the language identifier "text" (e.g., change ``` to ```text) for all
signature/example fences such as the blocks containing get_design_context(...)
and generate_diagram(...), and any other unnamed fences listed (lines referenced
in the review). Also change the lowercase "markdown" instance to the proper noun
"Markdown" in the nearby IMPORTANT note (the line that currently reads "-
IMPORTANT: after calling, you MUST surface the returned URL to the user as a
markdown link") so it reads "Markdown". Ensure all occurrences in the file are
updated consistently.
|
Codecov Report✅ All modified and coverable lines are covered by tests. 📢 Thoughts on this report? Let us know! |
3 tasks
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
2 participants
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
The
moai-design-toolsskill's Figma MCP reference documentation was drifting from the actual plugin v2.1.7 schemas. Every tool's schema was loaded live in Claude Code viaToolSearch(mcp__plugin_figma_figma__*), compared line-by-line againstreference/figma.md, and corrected.Findings:
get_libraries,get_context_for_code_connect)add_code_connect_mapwas documented as accepting amappingsarray — it actually maps a single nodegenerate_figma_designwas documented as(url, targetFileKey?)— it's actually a multi-step capture workflow with no required initial paramsuse_figmawas documented as(fileKey, operations)— it's(fileKey, code, description)wherecodeis executable JavaScriptget_variable_defs,get_metadata,get_code_connect_map,get_figjam, and others were missing requirednodeIdparametercreate_design_system_ruleswas described as creating rules inside Figma — it actually returns a prompt for scaffolding repo-level rulesSKILL.mdallowed-toolsregistered zero Figma MCP tools despite the skill claiming Figma MCP as one of three core capabilitiesChanges
Files touched (both template source and self-hosted):
internal/template/templates/.claude/skills/moai-design-tools/SKILL.md+.claude/skills/moai-design-tools/SKILL.mdinternal/template/templates/.claude/skills/moai-design-tools/reference/figma.md+.claude/skills/moai-design-tools/reference/figma.mdinternal/template/templates/.claude/skills/moai-design-tools/reference/comparison.md+.claude/skills/moai-design-tools/reference/comparison.mdPer-tool corrections are detailed in the commit message. The rewrite preserves the document structure and all non-Figma sections.
Verification
get_variable_defs(fileKey),get_metadata(fileKey),generate_figma_design(url,use_figma(fileKey, operations)) remain; 17 matches for the new correct-signature patternsTest plan
moai updateon a test project and confirmreference/figma.mddeploys with the 18-tool referenceget_context_for_code_connect(fileKey, nodeId)) in the deployed templateallowed-toolsinSKILL.mdnow includes the 18mcp__plugin_figma_figma__*entries🤖 Generated with Claude Code
Summary by CodeRabbit
Release Notes