Feature w 20796448 figma mcps migration

[sf-cboscenco]

Summary

Figma MCP tools migration from Odyssey

Testing

Tests have been included for each MCP tool
test/tools/storefrontnext/figma/README.md | Manual test plan: unit tests, MCP Inspector, CLI testing, E2E workflow, troubleshooting

Dependencies

• No net-new third-party dependencies were added
• If net-new third-party dependencies were added, rationale/discussion is included and 3pl-approved is set by a maintainer

New PostCSS is needed for:
-Parsing @theme at-rules and inline blocks
-Distinguishing light/dark/shared tokens via selectors
-Handling nested rules and var() references
-and that regex-based parsing would be unreliable for real theme files.

---

• Tests pass (pnpm test)
• Code is formatted (pnpm run format)

[sf-cboscenco]

Figma MCP Tools Migration - Staged Changes Summary

Branch: feature-figma-mcps-migration
Generated: 2025-02-24

Overview

This document summarizes the staged changes for the Figma MCP tools migration into the b2c-dx-mcp package. The migration adds three implemented tools that replace previous placeholders: workflow orchestrator, component generation recommendation, and design token mapping.

Stats: 22 files changed, 4,327 insertions, 18 deletions

---

Modified Files

packages/b2c-dx-mcp/README.md

• Updated tool descriptions in the STOREFRONTNEXT toolset table for the three Figma tools:
  • storefront_next_figma_to_component_workflow — Workflow orchestrator for Figma-to-component conversion
  • storefront_next_generate_component — Analyze Figma design and discovered components for REUSE/EXTEND/CREATE recommendation
  • storefront_next_map_tokens_to_theme — Map Figma design tokens to existing theme tokens in app.css

packages/b2c-dx-mcp/package.json

• Added dependency: postcss (8.5.6)

packages/b2c-dx-mcp/src/tools/storefrontnext/index.ts

• Replaced three createPlaceholderTool calls with real implementations:
  • createFigmaToComponentTool(loadServices)
  • createGenerateComponentTool(loadServices)
  • createMapTokensToThemeTool(loadServices)
• Added imports for the new Figma tool factories

pnpm-lock.yaml

• Updated to include postcss dependency

---

New Source Files

figma-to-component

File	Purpose
figma-url-parser.ts	Parses Figma URLs to extract fileKey and nodeId; supports design/file URL formats
index.ts	Workflow orchestrator tool; inlines default workflow content, parses custom workflow files, returns step-by-step instructions

generate-component

File	Purpose
decision.ts	Analyzes component differences (styling, structural, behavioral, props); determines REUSE/EXTEND/CREATE action and extend strategy
formatter.ts	Formats recommendation output for AI/developer
index.ts	Main tool; wraps logic with createToolAdapter, uses services.getWorkingDirectory() for workspace path

map-tokens

File	Purpose
css-parser.ts	Parses theme CSS (app.css) with PostCSS; extracts light/dark/shared tokens, resolves var() references
token-matcher.ts	Matches Figma tokens to theme tokens (exact color, fuzzy name/semantic/value)
index.ts	Main tool; formats mapping results, uses services.getWorkingDirectory() for theme file discovery

---

New Test Files

File	Coverage
figma-url-parser.test.ts	Valid/invalid URLs, design/file formats, node-id conversion
figma-to-component/index.test.ts	Workflow output, custom workflow files, error handling, metadata parsing
generate-component/formatter.test.ts	All action types (CREATE/EXTEND/REUSE), all extend strategies
generate-component/index.test.ts	Decision logic, difference detection, strategy selection
map-tokens/css-parser.test.ts	Theme parsing, token types, var() resolution, findThemeFilePath
map-tokens/token-matcher.test.ts	Exact/fuzzy/no-match, color/spacing/radius tokens
map-tokens/index.test.ts	Integration tests for full workflow

---

New Test Fixtures

File	Purpose
workflow-custom.md	Custom workflow with YAML metadata (including colon in value)
workflow-no-metadata.md	Workflow without YAML frontmatter

---

New Documentation

File	Purpose
test/tools/storefrontnext/figma/README.md	Manual test plan: unit tests, MCP Inspector, CLI testing, E2E workflow, troubleshooting

---

Tool Names (Unchanged from Placeholders)

• storefront_next_figma_to_component_workflow
• storefront_next_generate_component
• storefront_next_map_tokens_to_theme

---

Quality Gates

• Tests: 462 passing
• Coverage: ~99% for Figma tools
• Linter: No errors
• Typecheck: No errors

[patricksullivansf]

Looks great except for a few lint errors. Please generate new documentation for each tool under docs/mcp/tools and update the docs/mcp/toolsets.md tables with links.

[yhsieh1]

Do we need to provide detailed discovery strategy? Will it better if we only provide the expected result and let Agentic IDE uses its build in approaches to find what we need? It should already indexed files and content and might be faster.

Can we compact and simplify the flow? Too much information might confuse agent and consume more token.

[sf-cboscenco]

These tools were demoed by Emmy Zhang under multiple audiences, I will provide some links to the demos. I also think that we can implement improvements in subsequent updates to these tools and just focus on the migration right now as agreed so we can meet the migration timeline of 2/27.

[yhsieh1]

@sf-cboscenco It looks great. Some the instruction content seems very long and complex. Is that possible to simplify them? Also it would be great to add jsdoc.

[yhsieh1]

Could you record a demo how these tools are used and the interaction with user?

[yhsieh1]

3pl review: PostCSS is widely used (Tailwind, Vite, VitePress, etc.), actively maintained, and already in your lockfile via VitePress. Version 8.5.6 is pinned, which is good for reproducibility.

[sf-cboscenco]

@sf-cboscenco It looks great. Some the instruction content seems very long and complex. Is that possible to simplify them? Also it would be great to add jsdoc.

Added jsdoc comments.

[sf-cboscenco]

One of the demos link, courtesy of Emmy Zhang, thank you!
https://drive.google.com/file/d/1_4wqPH5n1KeN-80msMLeL1k7ci3Qhc45/view?usp=sharing

[yhsieh1]

@sf-cboscenco There are some JSDoc warnings. Could you fix them so that we do not need to come back later?