Skip to content

Commit fb0f895

Browse files
sf-cboscencosf-cboscenco
authored
Feature w 20796448 figma mcps migration (#212)
* Figma MCP tools migration * Fixed warnings * Fix linter error * Create docs as suggested in the code review * Added tools usage prerequisites * Added example prompts * Fixed directory determination * Improved jsdoc comments * Updated documsntation as requested * Fix jsodc warnings
1 parent d5eddeb commit fb0f895

29 files changed

+5140
-0
lines changed

‎docs/mcp/figma-tools-setup.md‎

Lines changed: 136 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,136 @@
1+
---
2+
description: Prerequisites and setup for Figma-to-component tools (workflow orchestrator, generate component, map tokens).
3+
---
4+
5+
# Figma-to-Component Tools Setup
6+
7+
Prerequisites and setup for using the Figma workflow tools: `storefront_next_figma_to_component_workflow`, `storefront_next_generate_component`, and `storefront_next_map_tokens_to_theme`.
8+
9+
## Overview
10+
11+
The Figma-to-component workflow uses **two MCP servers** that must both be enabled in your MCP client:
12+
13+
1. **b2c-dx-mcp** - Workflow orchestration, component analysis (REUSE/EXTEND/CREATE), and token mapping
14+
2. **Figma MCP** (external) - Fetches design context, screenshots, and metadata from Figma files
15+
16+
For full end-to-end conversion from Figma design to Storefront Next component, both servers must be configured and enabled.
17+
18+
## B2C DX MCP Configuration
19+
20+
Ensure the b2c-dx-mcp server is configured with:
21+
22+
- **`--project-directory`** - Must point to your Storefront Next project root. Required for:
23+
- `storefront_next_map_tokens_to_theme` - Theme file discovery (`app.css`)
24+
- `storefront_next_generate_component` - Workspace context
25+
- **`--allow-non-ga-tools`** - Figma tools are preview; this flag is required to enable them
26+
- **Storefront Next project** - Must have `app.css` or `src/app.css` for token mapping (or pass `themeFilePath` explicitly)
27+
28+
See [Installation](./installation) for MCP client setup (Cursor, Claude Desktop, etc.).
29+
30+
## Figma MCP Setup
31+
32+
The workflow calls Figma MCP tools to fetch design data. These come from a **separate Figma MCP server** that you must enable in your MCP client.
33+
34+
**Figma MCP tools used by the workflow:**
35+
36+
| Tool | Purpose |
37+
|------|---------|
38+
| `get_design_context` | Generates UI code from the design and returns asset URLs |
39+
| `get_screenshot` | Provides a visual reference image of the design |
40+
| `get_metadata` | Retrieves node hierarchy, layer types, names, positions, and sizes |
41+
42+
See the [Figma MCP Server Documentation](https://developers.figma.com/docs/figma-mcp-server) for official setup and tool details.
43+
44+
Figma provides two connection options. Check the [Figma MCP catalog](https://www.figma.com/mcp-catalog/) to see which your client supports, then follow the matching installation:
45+
46+
### Desktop MCP (Local)
47+
48+
Runs through the Figma desktop app on your machine. No API token required; uses your Figma app session.
49+
50+
- Requires the Figma desktop application to be installed and running
51+
- See [Figma MCP - Local Server Installation](https://developers.figma.com/docs/figma-mcp-server/local-server-installation/)
52+
53+
### Remote MCP (Hosted)
54+
55+
Connects directly to Figma's hosted endpoint. Does not require the desktop app but **requires a Figma Personal Access Token**.
56+
57+
- See [Figma MCP - Remote Server Installation](https://developers.figma.com/docs/figma-mcp-server/remote-server-installation/)
58+
59+
#### Creating a Figma Personal Access Token
60+
61+
1. Log in to [Figma](https://www.figma.com)
62+
2. Click your profile icon (top-left) → **Settings**
63+
3. Go to **Settings → Security → Personal Access Tokens**
64+
4. Click **Generate New Token** and give it a name (e.g., "MCP")
65+
5. Select **read-only** access for all scopes
66+
6. Click **Generate token** and **copy the token immediately** — Figma shows it only once
67+
68+
#### Storing the Token
69+
70+
Store the token in an environment variable (e.g., `FIGMA_API_KEY` or `FIGMA_ACCESS_TOKEN`). Do not hardcode it in configuration files or commit it to version control.
71+
72+
**Cursor** (`.cursor/mcp.json`):
73+
74+
```json
75+
{
76+
"mcpServers": {
77+
"figma": {
78+
"command": "...",
79+
"env": {
80+
"FIGMA_API_KEY": "your-token-here"
81+
}
82+
}
83+
}
84+
}
85+
```
86+
87+
Refer to your Figma MCP provider's documentation for the exact environment variable name and configuration.
88+
89+
## Figma Design File
90+
91+
### File Access
92+
93+
You must have **view access** (or higher) to the Figma file. The file cannot be restricted in a way that blocks API access.
94+
95+
### URL with node-id
96+
97+
The workflow requires a Figma URL that includes the `node-id` query parameter. This identifies the specific frame or component to convert.
98+
99+
**How to get a URL with node-id:**
100+
101+
1. Open the Figma file
102+
2. Select the frame or component you want to convert
103+
3. Right-click → **Copy link to selection** (or use the share menu)
104+
4. The copied URL will include `?node-id=1-2` (or similar)
105+
106+
**Supported URL formats:**
107+
108+
- `https://figma.com/design/:fileKey/:fileName?node-id=1-2`
109+
- `https://www.figma.com/design/:fileKey/:fileName?node-id=1-2`
110+
- `https://figma.com/file/:fileKey/:fileName?node-id=1-2`
111+
112+
### No Special Figma Configuration
113+
114+
The basic workflow does not require:
115+
116+
- Figma Dev Mode
117+
- Code Connect
118+
- Plugins
119+
- Special file structure
120+
121+
## Verification
122+
123+
To confirm both servers are working:
124+
125+
1. **b2c-dx-mcp** - List tools in your MCP client; you should see `storefront_next_figma_to_component_workflow`, `storefront_next_generate_component`, and `storefront_next_map_tokens_to_theme`
126+
2. **Figma MCP** - List tools; you should see `mcp__figma__get_design_context`, `mcp__figma__get_screenshot`, and `mcp__figma__get_metadata` (or similar names per your Figma MCP provider)
127+
128+
If the Figma MCP server is not enabled, the workflow tool will still return instructions and parsed parameters, but the AI assistant will not be able to fetch design data. Inform the user that the Figma MCP server must be enabled for full conversion.
129+
130+
## Related Documentation
131+
132+
- [storefront_next_figma_to_component_workflow](./tools/storefront-next-figma-to-component-workflow) - Workflow orchestrator (call first)
133+
- [storefront_next_generate_component](./tools/storefront-next-generate-component) - REUSE/EXTEND/CREATE recommendation
134+
- [storefront_next_map_tokens_to_theme](./tools/storefront-next-map-tokens-to-theme) - Token mapping
135+
- [STOREFRONTNEXT Toolset](./toolsets#storefrontnext) - Overview of Storefront Next tools
136+
- [Figma MCP Server Documentation](https://developers.figma.com/docs/figma-mcp-server) - Official Figma MCP setup

‎docs/mcp/index.md‎

Lines changed: 5 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -132,6 +132,11 @@ AI assistants automatically decide which MCP tools to use based on your prompts.
132132
**MRT Bundle Operations:**
133133
- ✅ "Use the MCP tool to build and push my Storefront Next bundle to staging."
134134

135+
**Figma-to-Component:**
136+
- ✅ "Use the MCP tool to convert this Figma design to a Storefront Next component: [Figma URL with node-id]"
137+
- ✅ "Use the MCP tool to create this homepage from the Figma design: [Figma URL with node-id]. Create new components or update existing components using the MCP tool if necessary, then update the home page. The expected result should be that the homepage matches as closely as possible to the provided Figma design."
138+
- ✅ "Use the MCP tool to map Figma design tokens to my theme."
139+
135140
See the [Toolsets & Tools Reference](./toolsets) for more prompting examples for each toolset.
136141

137142
## Telemetry

‎docs/mcp/installation.md‎

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -12,6 +12,8 @@ This guide covers installing and configuring the B2C DX MCP Server for various M
1212
- A B2C Commerce project (for project-specific toolsets)
1313
- MCP client (Cursor, Claude Desktop, or compatible client)
1414

15+
**Figma-to-component tools:** If you use the Figma workflow tools (`storefront_next_figma_to_component_workflow`, `storefront_next_generate_component`, `storefront_next_map_tokens_to_theme`), you also need an external Figma MCP server enabled. See [Figma-to-Component Tools Setup](./figma-tools-setup) for prerequisites and configuration.
16+
1517
## Install via npm (Recommended)
1618

1719
```json

‎docs/mcp/tools/storefront-next-figma-to-component-workflow.md‎

Lines changed: 128 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,128 @@
1+
---
2+
description: Workflow orchestrator for Figma-to-component conversion. Parses your Figma URL and guides your AI assistant through design-to-component conversion.
3+
---
4+
5+
# storefront_next_figma_to_component_workflow
6+
7+
Workflow orchestrator for converting Figma designs to Storefront Next components. When you ask your AI assistant to convert a Figma design, it starts with this workflow tool, which parses your URL and guides the assistant through the conversion.
8+
9+
## Overview
10+
11+
When you provide a Figma design URL, your AI assistant uses this tool to extract the file and node identifiers, then follows the workflow to fetch design data, analyze your codebase, and produce recommendations. The assistant will:
12+
13+
- Fetch design context and screenshots from Figma
14+
- Discover similar components in your project
15+
- Recommend whether to REUSE, EXTEND, or CREATE a component
16+
- Map Figma design tokens to your theme variables
17+
18+
You receive a component recommendation with confidence score and a token mapping summary when the workflow completes.
19+
20+
This tool is part of the STOREFRONTNEXT toolset.
21+
22+
## Prerequisites
23+
24+
- **B2C DX MCP** configured with `--project-directory` pointing to your Storefront Next project and `--allow-non-ga-tools`
25+
- **Figma MCP server** (external) enabled in your MCP client for full workflow execution
26+
- **Valid Figma URL** with `node-id` query parameter (obtain by right-clicking a frame in Figma → Copy link to selection)
27+
28+
See [Figma-to-Component Tools Setup](../figma-tools-setup) for complete prerequisites and configuration.
29+
30+
## Authentication
31+
32+
No authentication required. This tool operates on local workflow files and URL parsing only.
33+
34+
## Parameters
35+
36+
| Parameter | Type | Required | Description |
37+
|-----------|------|----------|-------------|
38+
| `figmaUrl` | string | Yes | The Figma design URL to convert. Must be a valid URL and include the `node-id` query parameter. |
39+
| `workflowFilePath` | string | No | Optional absolute path to a custom workflow `.md` file. If not provided, uses the default built-in workflow. |
40+
41+
## Supported Figma URL Formats
42+
43+
The parser supports these URL formats:
44+
45+
- `https://figma.com/design/:fileKey/:fileName?node-id=1-2`
46+
- `https://www.figma.com/design/:fileKey/:fileName?node-id=1-2`
47+
- `https://figma.com/file/:fileKey/:fileName?node-id=1-2`
48+
49+
The `node-id` parameter accepts hyphen format (`1-2`) or colon format (`1:2`). The parser converts hyphens to colons for Figma MCP compatibility.
50+
51+
## Output
52+
53+
The workflow returns a guide with extracted Figma parameters (`fileKey`, `nodeId`, and original URL). After the full workflow completes, you receive a component recommendation (REUSE/EXTEND/CREATE) with confidence score and a token mapping summary.
54+
55+
**Example prompts:**
56+
- ✅ "Use the MCP tool to convert this Figma design to a Storefront Next component: [Figma URL with node-id]"
57+
- ✅ "Use the MCP tool to create this homepage from the Figma design: [Figma URL with node-id]. Create new components or update existing components using the MCP tool if necessary, then update the home page. The expected result should be that the homepage matches as closely as possible to the provided Figma design."
58+
- ✅ "Use the MCP tool to start the Figma-to-component workflow with a custom workflow file at /path/to/custom-workflow.md"
59+
60+
## Usage Examples
61+
62+
### Basic Workflow Start
63+
64+
```
65+
Use the MCP tool to convert this Figma design to a Storefront Next component: [Figma URL with node-id]
66+
```
67+
68+
### Custom Workflow File
69+
70+
```
71+
Use the MCP tool to start the Figma-to-component workflow with a custom workflow file at /path/to/custom-workflow.md
72+
```
73+
74+
### Full Homepage Implementation
75+
76+
Create a homepage from a Figma design, creating or updating components as needed:
77+
78+
```
79+
Use the MCP tool to create this homepage from the Figma design: [Figma URL with node-id]. Create new components or update existing components using the MCP tool if necessary, then update the home page. The expected result should be that the homepage matches as closely as possible to the provided Figma design.
80+
```
81+
82+
## Requirements
83+
84+
- Valid Figma URL from figma.com
85+
- URL must include `node-id` query parameter
86+
- For custom workflow: file must exist at the provided path
87+
88+
## Error Handling
89+
90+
The tool returns formatted error messages if:
91+
92+
- **Invalid URL**: URL is not from figma.com, or `fileKey`/`node-id` cannot be extracted
93+
- **Workflow file not found**: Custom `workflowFilePath` is provided but the file does not exist
94+
95+
**Example error format:**
96+
97+
```
98+
# Error: Invalid Figma URL
99+
100+
Could not extract node-id from URL. Expected query parameter: ?node-id=1-2
101+
102+
Please provide a valid Figma URL in the format:
103+
https://figma.com/design/:fileKey/:fileName?node-id=1-2
104+
```
105+
106+
## Related Tools
107+
108+
- [`storefront_next_generate_component`](./storefront-next-generate-component) - Analyzes design and discovered components; recommends REUSE/EXTEND/CREATE
109+
- [`storefront_next_map_tokens_to_theme`](./storefront-next-map-tokens-to-theme) - Maps Figma design tokens to theme variables
110+
- Part of the [STOREFRONTNEXT](../toolsets#storefrontnext) toolset
111+
- Auto-enabled for Storefront Next projects
112+
113+
## Figma MCP Tools (External)
114+
115+
The workflow relies on your AI assistant having access to Figma MCP tools to fetch design data:
116+
117+
- **get_design_context** - Generates UI code from the design and returns asset URLs
118+
- **get_screenshot** - Provides a visual reference image of the design
119+
- **get_metadata** - Retrieves node hierarchy, layer types, names, positions, and sizes
120+
121+
Ensure the Figma MCP server is enabled in your MCP client. See [Figma-to-Component Tools Setup](../figma-tools-setup) for configuration and the [Figma MCP Server Documentation](https://developers.figma.com/docs/figma-mcp-server) for official setup and tool details.
122+
123+
## See Also
124+
125+
- [Figma-to-Component Tools Setup](../figma-tools-setup) - Prerequisites and Figma MCP configuration
126+
- [STOREFRONTNEXT Toolset](../toolsets#storefrontnext) - Overview of Storefront Next development tools
127+
- [Configuration](../configuration) - Configure project directory
128+
- [Storefront Next Guide](../../guide/storefront-next) - Storefront Next development guide

0 commit comments

Comments
 (0)