Merge branch 'main' into changeset-release/main

Author: yhsieh1

.github/workflows/3pl-guard.yml

@@ -123,9 +123,14 @@ jobs:
               per_page: 100,
             });
 
+            // Exclude package.json under test/fixtures/ (e.g. e2e workspace-detection fixtures)
+            const isUnderTestFixtures = (filename) =>
+              filename.includes('/test/') && filename.includes('/fixtures/');
             const changedPackageJsonFiles = files
               .map((file) => file.filename)
-              .filter((filename) => filename.endsWith('package.json'));
+              .filter((filename) =>
+                filename.endsWith('package.json') && !isUnderTestFixtures(filename),
+              );
 
             const findings = [];
 
@@ -200,4 +205,4 @@ jobs:
             await addLabel(reviewLabel);
             core.setFailed(
               `Net-new third-party dependencies found: ${allNetNewDeps.join(', ')}. Add \`${approvalLabel}\` after review.`,
-            );
+            );

.github/workflows/e2e-tests.yml

@@ -166,3 +166,39 @@ jobs:
             if (context.eventName === 'schedule') {
               github.rest.issues.create(issue);
             }
+
+  mcp-e2e-tests:
+    name: MCP E2E
+    runs-on: ubuntu-latest
+    timeout-minutes: 15
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-node@v4
+        with:
+          node-version: '22.x'
+      - name: Setup pnpm
+        uses: pnpm/action-setup@v4
+        with:
+          version: 10.17.1
+      - name: Get pnpm store directory
+        id: pnpm-store
+        shell: bash
+        run: |
+          echo "store_path=$(pnpm store path --silent)" >> $GITHUB_OUTPUT
+      - name: Setup pnpm cache
+        uses: actions/cache@v4
+        with:
+          path: ${{ steps.pnpm-store.outputs.store_path }}
+          key: ${{ runner.os }}-pnpm-store-${{ hashFiles('**/pnpm-lock.yaml') }}
+          restore-keys: |
+            ${{ runner.os }}-pnpm-store-
+      - name: Install dependencies
+        run: pnpm install --frozen-lockfile
+      - name: Build packages
+        run: pnpm -r run build
+      - name: Run MCP E2E tests
+        working-directory: packages/b2c-dx-mcp
+        env:
+          SFCC_DISABLE_TELEMETRY: 'true'
+          NODE_ENV: test
+        run: pnpm run test:e2e:ci

docs/.vitepress/config.mts

@@ -58,6 +58,7 @@ const guideSidebar = [
       {text: 'Installation', link: '/mcp/installation'},
       {text: 'Configuration', link: '/mcp/configuration'},
       {text: 'Toolsets & Tools', link: '/mcp/toolsets'},
+      {text: 'Figma Tools Setup', link: '/mcp/figma-tools-setup'},
     ],
   },
   {
@@ -99,9 +100,14 @@ const guideSidebar = [
       {text: 'mrt_bundle_push', link: '/mcp/tools/mrt-bundle-push'},
       {text: 'pwakit_development_guidelines', link: '/mcp/tools/pwakit-development-guidelines'},
       {text: 'scapi_schemas_list', link: '/mcp/tools/scapi-schemas-list'},
+      {text: 'scapi_custom_api_scaffold', link: '/mcp/tools/scapi-custom-api-scaffold'},
       {text: 'scapi_custom_apis_status', link: '/mcp/tools/scapi-custom-apis-status'},
       {text: 'storefront_next_development_guidelines', link: '/mcp/tools/storefront-next-development-guidelines'},
+      {text: 'storefront_next_figma_to_component_workflow', link: '/mcp/tools/storefront-next-figma-to-component-workflow'},
+      {text: 'storefront_next_generate_component', link: '/mcp/tools/storefront-next-generate-component'},
+      {text: 'storefront_next_map_tokens_to_theme', link: '/mcp/tools/storefront-next-map-tokens-to-theme'},
       {text: 'storefront_next_page_designer_decorator', link: '/mcp/tools/storefront-next-page-designer-decorator'},
+      {text: 'storefront_next_site_theming', link: '/mcp/tools/storefront-next-site-theming'},
     ],
   },
 ];

docs/mcp/figma-tools-setup.md

@@ -0,0 +1,136 @@
+---
+description: Prerequisites and setup for Figma-to-component tools (workflow orchestrator, generate component, map tokens).
+---
+
+# Figma-to-Component Tools Setup
+
+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`.
+
+## Overview
+
+The Figma-to-component workflow uses **two MCP servers** that must both be enabled in your MCP client:
+
+1. **b2c-dx-mcp** - Workflow orchestration, component analysis (REUSE/EXTEND/CREATE), and token mapping
+2. **Figma MCP** (external) - Fetches design context, screenshots, and metadata from Figma files
+
+For full end-to-end conversion from Figma design to Storefront Next component, both servers must be configured and enabled.
+
+## B2C DX MCP Configuration
+
+Ensure the b2c-dx-mcp server is configured with:
+
+- **`--project-directory`** - Must point to your Storefront Next project root. Required for:
+  - `storefront_next_map_tokens_to_theme` - Theme file discovery (`app.css`)
+  - `storefront_next_generate_component` - Workspace context
+- **`--allow-non-ga-tools`** - Figma tools are preview; this flag is required to enable them
+- **Storefront Next project** - Must have `app.css` or `src/app.css` for token mapping (or pass `themeFilePath` explicitly)
+
+See [Installation](./installation) for MCP client setup (Cursor, Claude Desktop, etc.).
+
+## Figma MCP Setup
+
+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.
+
+**Figma MCP tools used by the workflow:**
+
+| Tool | Purpose |
+|------|---------|
+| `get_design_context` | Generates UI code from the design and returns asset URLs |
+| `get_screenshot` | Provides a visual reference image of the design |
+| `get_metadata` | Retrieves node hierarchy, layer types, names, positions, and sizes |
+
+See the [Figma MCP Server Documentation](https://developers.figma.com/docs/figma-mcp-server) for official setup and tool details.
+
+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:
+
+### Desktop MCP (Local)
+
+Runs through the Figma desktop app on your machine. No API token required; uses your Figma app session.
+
+- Requires the Figma desktop application to be installed and running
+- See [Figma MCP - Local Server Installation](https://developers.figma.com/docs/figma-mcp-server/local-server-installation/)
+
+### Remote MCP (Hosted)
+
+Connects directly to Figma's hosted endpoint. Does not require the desktop app but **requires a Figma Personal Access Token**.
+
+- See [Figma MCP - Remote Server Installation](https://developers.figma.com/docs/figma-mcp-server/remote-server-installation/)
+
+#### Creating a Figma Personal Access Token
+
+1. Log in to [Figma](https://www.figma.com)
+2. Click your profile icon (top-left) → **Settings**
+3. Go to **Settings → Security → Personal Access Tokens**
+4. Click **Generate New Token** and give it a name (e.g., "MCP")
+5. Select **read-only** access for all scopes
+6. Click **Generate token** and **copy the token immediately** — Figma shows it only once
+
+#### Storing the Token
+
+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.
+
+**Cursor** (`.cursor/mcp.json`):
+
+```json
+{
+  "mcpServers": {
+    "figma": {
+      "command": "...",
+      "env": {
+        "FIGMA_API_KEY": "your-token-here"
+      }
+    }
+  }
+}
+```
+
+Refer to your Figma MCP provider's documentation for the exact environment variable name and configuration.
+
+## Figma Design File
+
+### File Access
+
+You must have **view access** (or higher) to the Figma file. The file cannot be restricted in a way that blocks API access.
+
+### URL with node-id
+
+The workflow requires a Figma URL that includes the `node-id` query parameter. This identifies the specific frame or component to convert.
+
+**How to get a URL with node-id:**
+
+1. Open the Figma file
+2. Select the frame or component you want to convert
+3. Right-click → **Copy link to selection** (or use the share menu)
+4. The copied URL will include `?node-id=1-2` (or similar)
+
+**Supported URL formats:**
+
+- `https://figma.com/design/:fileKey/:fileName?node-id=1-2`
+- `https://www.figma.com/design/:fileKey/:fileName?node-id=1-2`
+- `https://figma.com/file/:fileKey/:fileName?node-id=1-2`
+
+### No Special Figma Configuration
+
+The basic workflow does not require:
+
+- Figma Dev Mode
+- Code Connect
+- Plugins
+- Special file structure
+
+## Verification
+
+To confirm both servers are working:
+
+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`
+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)
+
+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.
+
+## Related Documentation
+
+- [storefront_next_figma_to_component_workflow](./tools/storefront-next-figma-to-component-workflow) - Workflow orchestrator (call first)
+- [storefront_next_generate_component](./tools/storefront-next-generate-component) - REUSE/EXTEND/CREATE recommendation
+- [storefront_next_map_tokens_to_theme](./tools/storefront-next-map-tokens-to-theme) - Token mapping
+- [STOREFRONTNEXT Toolset](./toolsets#storefrontnext) - Overview of Storefront Next tools
+- [Figma MCP Server Documentation](https://developers.figma.com/docs/figma-mcp-server) - Official Figma MCP setup

docs/mcp/index.md

@@ -120,6 +120,7 @@ AI assistants automatically decide which MCP tools to use based on your prompts.
 **Storefront Next Development:**
 - ✅ "I'm new to Storefront Next. Use the MCP tool to show me the critical rules I need to know."
 - ✅ "I need to build a product detail page. Use the MCP tool to show me best practices for data fetching and component patterns."
+- ✅ "I want to apply my brand colors to my Storefront Next site. Use the MCP tool to help me."
 
 **SCAPI Discovery:**
 - ✅ "Use the MCP tool to list all available SCAPI schemas."
@@ -131,6 +132,11 @@ AI assistants automatically decide which MCP tools to use based on your prompts.
 **MRT Bundle Operations:**
 - ✅ "Use the MCP tool to build and push my Storefront Next bundle to staging."
 
+**Figma-to-Component:**
+- ✅ "Use the MCP tool to convert this Figma design to a Storefront Next component: [Figma URL with node-id]"
+- ✅ "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."
+- ✅ "Use the MCP tool to map Figma design tokens to my theme."
+
 See the [Toolsets & Tools Reference](./toolsets) for more prompting examples for each toolset.
 
 ## Telemetry

docs/mcp/installation.md

@@ -12,6 +12,8 @@ This guide covers installing and configuring the B2C DX MCP Server for various M
 - A B2C Commerce project (for project-specific toolsets)
 - MCP client (Cursor, Claude Desktop, or compatible client)
 
+**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.
+
 ## Install via npm (Recommended)
 
 ```json

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

@@ -0,0 +1,141 @@
+---
+description: Workflow orchestrator for Figma-to-component conversion. Parses your Figma URL and guides your AI assistant through design-to-component conversion.
+---
+
+# storefront_next_figma_to_component_workflow
+
+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.
+
+## Overview
+
+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:
+
+- Fetch design context and screenshots from Figma
+- **Ask for your approval before exporting images** — when the design contains image assets (photos, logos, icons), the assistant presents the list and waits for you to confirm before exporting
+- Discover similar components in your project
+- Recommend whether to REUSE, EXTEND, or CREATE a component
+- Map Figma design tokens to your theme variables
+
+You receive a component recommendation with confidence score and a token mapping summary when the workflow completes.
+
+This tool is part of the STOREFRONTNEXT toolset.
+
+## Prerequisites
+
+- **B2C DX MCP** configured with `--project-directory` pointing to your Storefront Next project and `--allow-non-ga-tools`
+- **Figma MCP server** (external) enabled in your MCP client for full workflow execution
+- **Valid Figma URL** with `node-id` query parameter (obtain by right-clicking a frame in Figma → Copy link to selection)
+
+See [Figma-to-Component Tools Setup](../figma-tools-setup) for complete prerequisites and configuration.
+
+## Authentication
+
+No authentication required. This tool operates on local workflow files and URL parsing only.
+
+## Parameters
+
+| Parameter | Type | Required | Description |
+|-----------|------|----------|-------------|
+| `figmaUrl` | string | Yes | The Figma design URL to convert. Must be a valid URL and include the `node-id` query parameter. |
+| `workflowFilePath` | string | No | Optional absolute path to a custom workflow `.md` file. If not provided, uses the default built-in workflow. |
+
+## Supported Figma URL Formats
+
+The parser supports these URL formats:
+
+- `https://figma.com/design/:fileKey/:fileName?node-id=1-2`
+- `https://www.figma.com/design/:fileKey/:fileName?node-id=1-2`
+- `https://figma.com/file/:fileKey/:fileName?node-id=1-2`
+
+The `node-id` parameter accepts hyphen format (`1-2`) or colon format (`1:2`). The parser converts hyphens to colons for Figma MCP compatibility.
+
+## Output
+
+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.
+
+**Example prompts:**
+- ✅ "Use the MCP tool to convert this Figma design to a Storefront Next component: [Figma URL with node-id]"
+- ✅ "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."
+- ✅ "Use the MCP tool to start the Figma-to-component workflow with a custom workflow file at /path/to/custom-workflow.md"
+
+## Usage Examples
+
+### Basic Workflow Start
+
+```
+Use the MCP tool to convert this Figma design to a Storefront Next component: [Figma URL with node-id]
+```
+
+### Custom Workflow File
+
+```
+Use the MCP tool to start the Figma-to-component workflow with a custom workflow file at /path/to/custom-workflow.md
+```
+
+### Full Homepage Implementation
+
+Create a homepage from a Figma design, creating or updating components as needed:
+
+```
+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.
+```
+
+## Requirements
+
+- Valid Figma URL from figma.com
+- URL must include `node-id` query parameter
+- For custom workflow: file must exist at the provided path
+
+## Error Handling
+
+The tool returns formatted error messages if:
+
+- **Invalid URL**: URL is not from figma.com, or `fileKey`/`node-id` cannot be extracted
+- **Workflow file not found**: Custom `workflowFilePath` is provided but the file does not exist
+
+**Example error format:**
+
+```
+# Error: Invalid Figma URL
+
+Could not extract node-id from URL. Expected query parameter: ?node-id=1-2
+
+Please provide a valid Figma URL in the format:
+https://figma.com/design/:fileKey/:fileName?node-id=1-2
+```
+
+## Related Tools
+
+- [`storefront_next_generate_component`](./storefront-next-generate-component) - Analyzes design and discovered components; recommends REUSE/EXTEND/CREATE
+- [`storefront_next_map_tokens_to_theme`](./storefront-next-map-tokens-to-theme) - Maps Figma design tokens to theme variables
+- Part of the [STOREFRONTNEXT](../toolsets#storefrontnext) toolset
+- Auto-enabled for Storefront Next projects
+
+## Figma MCP Tools (External)
+
+The workflow relies on your AI assistant having access to Figma MCP tools to fetch design data:
+
+- **get_design_context** - Generates UI code from the design and returns asset URLs
+- **get_screenshot** - Provides a visual reference image of the design
+- **get_metadata** - Retrieves node hierarchy, layer types, names, positions, and sizes
+
+### Image Export and User Approval
+
+The workflow requires the assistant to **ask for your approval before exporting any image assets**. The assistant will:
+
+1. Call `get_design_context` **without** `dirForAssetWrites` on the initial call (never export on first call)
+2. Identify image-containing nodes (photos, banners, **logos**, **brand assets**, icons)
+3. Present the list of nodes to you
+4. Ask once: "Should I export these N image assets now? (yes/no)"
+5. Wait for your explicit "yes" before calling `get_design_context` with `dirForAssetWrites` to export
+
+You are prompted **once per batch**—not per image. This ensures you control when assets are written to disk. Logo and brand assets are explicitly included in the identification criteria so they are not missed.
+
+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.
+
+## See Also
+
+- [Figma-to-Component Tools Setup](../figma-tools-setup) - Prerequisites and Figma MCP configuration
+- [STOREFRONTNEXT Toolset](../toolsets#storefrontnext) - Overview of Storefront Next development tools
+- [Configuration](../configuration) - Configure project directory
+- [Storefront Next Guide](../../guide/storefront-next) - Storefront Next development guide