@salesforce/b2c-dx-mcp 0.4.4 → 0.4.6

package/dist/tools/storefrontnext/figma/map-tokens/index.d.ts

@@ -0,0 +1,61 @@
+/**
+ * Map tokens tool for Figma-to-component workflow.
+ *
+ * Maps Figma design tokens to Storefront Next theme tokens in app.css with exact/fuzzy matching.
+ *
+ * @module tools/storefrontnext/figma/map-tokens
+ */
+import { z } from 'zod';
+import type { McpTool } from '../../../../utils/index.js';
+import type { Services } from '../../../../services.js';
+export declare const mapTokensToThemeSchema: z.ZodObject<{
+    figmaTokens: z.ZodArray<z.ZodObject<{
+        name: z.ZodString;
+        value: z.ZodString;
+        type: z.ZodEnum<["color", "spacing", "radius", "opacity", "fontSize", "fontFamily", "other"]>;
+        description: z.ZodOptional<z.ZodString>;
+    }, "strip", z.ZodTypeAny, {
+        type: "color" | "fontFamily" | "fontSize" | "opacity" | "other" | "radius" | "spacing";
+        name: string;
+        value: string;
+        description?: string | undefined;
+    }, {
+        type: "color" | "fontFamily" | "fontSize" | "opacity" | "other" | "radius" | "spacing";
+        name: string;
+        value: string;
+        description?: string | undefined;
+    }>, "many">;
+    themeFilePath: z.ZodOptional<z.ZodString>;
+}, "strict", z.ZodTypeAny, {
+    figmaTokens: {
+        type: "color" | "fontFamily" | "fontSize" | "opacity" | "other" | "radius" | "spacing";
+        name: string;
+        value: string;
+        description?: string | undefined;
+    }[];
+    themeFilePath?: string | undefined;
+}, {
+    figmaTokens: {
+        type: "color" | "fontFamily" | "fontSize" | "opacity" | "other" | "radius" | "spacing";
+        name: string;
+        value: string;
+        description?: string | undefined;
+    }[];
+    themeFilePath?: string | undefined;
+}>;
+export type MapTokensToThemeInput = z.infer<typeof mapTokensToThemeSchema>;
+/**
+ * Maps Figma design tokens to existing theme tokens in app.css.
+ *
+ * @param args - Figma tokens array and optional theme file path
+ * @param workspaceRoot - Optional workspace root for theme file discovery; used when themeFilePath is not provided
+ * @returns Formatted mapping report with exact/fuzzy matches, confidence scores, and usage instructions, or error message on failure
+ */
+export declare function mapFigmaTokensToTheme(args: MapTokensToThemeInput, workspaceRoot?: string): string;
+/**
+ * Creates the storefront_next_map_tokens_to_theme MCP tool.
+ *
+ * @param loadServices - Function that loads configuration and returns Services instance
+ * @returns MCP tool for token mapping
+ */
+export declare function createMapTokensToThemeTool(loadServices: () => Services): McpTool;

package/dist/tools/storefrontnext/figma/map-tokens/index.js

@@ -0,0 +1,234 @@
+/*
+ * Copyright (c) 2025, Salesforce, Inc.
+ * SPDX-License-Identifier: Apache-2
+ * For full license text, see the license.txt file in the repo root or http://www.apache.org/licenses/LICENSE-2.0
+ */
+/**
+ * Map tokens tool for Figma-to-component workflow.
+ *
+ * Maps Figma design tokens to Storefront Next theme tokens in app.css with exact/fuzzy matching.
+ *
+ * @module tools/storefrontnext/figma/map-tokens
+ */
+import { z } from 'zod';
+import { createToolAdapter, textResult } from '../../../adapter.js';
+import { parseThemeFile } from './css-parser.js';
+import { matchTokens } from './token-matcher.js';
+export const mapTokensToThemeSchema = z
+    .object({
+    figmaTokens: z
+        .array(z.object({
+        name: z.string().describe('Token name from Figma (e.g., "Primary/Blue", "Spacing/Large")'),
+        value: z.string().describe('Token value (e.g., "#2563eb", "16px", "0.5rem")'),
+        type: z
+            .enum(['color', 'spacing', 'radius', 'opacity', 'fontSize', 'fontFamily', 'other'])
+            .describe('Type of the token'),
+        description: z.string().optional().describe('Optional description from Figma'),
+    }))
+        .describe('Array of design tokens extracted from Figma'),
+    themeFilePath: z
+        .string()
+        .optional()
+        .describe('Optional absolute path to theme CSS file. If not provided, will search for app.css in common locations.'),
+})
+    .strict();
+function formatTokenMatch(match) {
+    let output = `### ${match.figmaToken.name}\n\n`;
+    output += `- **Figma Value**: \`${match.figmaToken.value}\`\n`;
+    output += `- **Type**: ${match.figmaToken.type}\n`;
+    if (match.figmaToken.description) {
+        output += `- **Description**: ${match.figmaToken.description}\n`;
+    }
+    output += `\n#### Match Result\n\n`;
+    output += `- **Match Type**: ${match.matchType}\n`;
+    output += `- **Confidence**: ${match.confidence}%\n`;
+    if (match.matchedToken) {
+        output += `- **Matched Token**: \`${match.matchedToken.name}\`\n`;
+        output += `- **Token Value**: \`${match.matchedToken.value}\`\n`;
+        output += `- **Resolved Value**: \`${match.matchedToken.resolvedValue || match.matchedToken.value}\`\n`;
+        output += `- **Theme**: ${match.matchedToken.theme}\n`;
+    }
+    output += `- **Reason**: ${match.reason}\n\n`;
+    if (match.suggestions && match.suggestions.length > 0) {
+        output += `#### Suggestions\n\n`;
+        for (const [index, suggestion] of match.suggestions.entries()) {
+            output += `${index + 1}. **${suggestion.tokenName}**\n`;
+            output += `   - Value: \`${suggestion.value}\`\n`;
+            output += `   - Theme: ${suggestion.theme}\n`;
+            output += `   - Reason: ${suggestion.reason}\n`;
+            if (suggestion.insertAfter) {
+                output += `   - Insert after: \`${suggestion.insertAfter}\`\n`;
+            }
+            output += `\n`;
+        }
+    }
+    return output;
+}
+function generateSummary(matches) {
+    const exactMatches = matches.filter((m) => m.matchType === 'exact');
+    const fuzzyMatches = matches.filter((m) => m.matchType === 'fuzzy');
+    const noMatches = matches.filter((m) => m.matchType === 'none');
+    const highConfidence = matches.filter((m) => m.confidence >= 70 && m.matchedToken);
+    const lowConfidence = matches.filter((m) => m.confidence < 70 && m.confidence > 0);
+    let summary = `## Summary\n\n`;
+    summary += `- **Total Tokens**: ${matches.length}\n`;
+    summary += `- **Exact Matches**: ${exactMatches.length}\n`;
+    summary += `- **Fuzzy Matches**: ${fuzzyMatches.length}\n`;
+    summary += `- **No Matches**: ${noMatches.length}\n`;
+    summary += `- **High Confidence (≥70%)**: ${highConfidence.length}\n`;
+    summary += `- **Low Confidence (<70%)**: ${lowConfidence.length}\n\n`;
+    if (exactMatches.length > 0) {
+        summary += `### ✅ Exact Matches (Use these tokens directly)\n\n`;
+        for (const match of exactMatches) {
+            if (match.matchedToken) {
+                summary += `- \`${match.figmaToken.name}\` → \`${match.matchedToken.name}\`\n`;
+            }
+        }
+        summary += `\n`;
+    }
+    if (highConfidence.length > 0) {
+        summary += `### ⚠️ High Confidence Fuzzy Matches (Review and confirm)\n\n`;
+        for (const match of highConfidence) {
+            if (match.matchedToken) {
+                summary += `- \`${match.figmaToken.name}\` → \`${match.matchedToken.name}\` (${match.confidence}%)\n`;
+            }
+        }
+        summary += `\n`;
+    }
+    if (lowConfidence.length > 0) {
+        summary += `### ⚠️ Low Confidence Matches (Verify before using)\n\n`;
+        for (const match of lowConfidence) {
+            if (match.matchedToken) {
+                summary += `- \`${match.figmaToken.name}\` → \`${match.matchedToken.name}\` (${match.confidence}%)\n`;
+            }
+        }
+        summary += `\n`;
+    }
+    if (noMatches.length > 0) {
+        summary += `### ❌ No Matches (New tokens needed)\n\n`;
+        for (const match of noMatches) {
+            summary += `- \`${match.figmaToken.name}\`: ${match.figmaToken.value}\n`;
+            if (match.suggestions && match.suggestions.length > 0) {
+                summary += `  - Suggested: \`${match.suggestions[0].tokenName}\`\n`;
+            }
+        }
+        summary += `\n`;
+    }
+    return summary;
+}
+function generateRecommendations(matches) {
+    const needsNewTokens = matches.filter((m) => m.matchType === 'none');
+    const needsReview = matches.filter((m) => m.matchType === 'fuzzy' && m.confidence < 70);
+    if (needsNewTokens.length === 0 && needsReview.length === 0) {
+        return `## ✅ Recommendations\n\nAll tokens have been matched with high confidence. You can proceed with using the matched tokens in your component.\n\n`;
+    }
+    let recommendations = `## 📝 Recommendations\n\n`;
+    if (needsNewTokens.length > 0) {
+        recommendations += `### Create New Tokens\n\n`;
+        recommendations += `The following tokens from Figma don't have matches in your theme. Consider adding them to your \`app.css\` file:\n\n`;
+        for (const match of needsNewTokens) {
+            if (match.suggestions && match.suggestions.length > 0) {
+                const suggestion = match.suggestions[0];
+                recommendations += `\`\`\`css\n`;
+                recommendations += `/* Add to ${suggestion.theme === 'both' ? ':root and .dark' : suggestion.theme === 'light' ? ':root' : '.dark'} section */\n`;
+                recommendations += `${suggestion.tokenName}: ${suggestion.value};\n`;
+                recommendations += `\`\`\`\n\n`;
+            }
+        }
+    }
+    if (needsReview.length > 0) {
+        recommendations += `### Review Low Confidence Matches\n\n`;
+        recommendations += `The following matches have confidence below 70%. Please review and confirm they are correct before using:\n\n`;
+        for (const match of needsReview) {
+            if (match.matchedToken) {
+                recommendations += `- **${match.figmaToken.name}** (${match.figmaToken.value})\n`;
+                recommendations += `  - Matched: \`${match.matchedToken.name}\` (${match.matchedToken.resolvedValue})\n`;
+                recommendations += `  - Confidence: ${match.confidence}%\n`;
+                recommendations += `  - Reason: ${match.reason}\n\n`;
+            }
+        }
+    }
+    return recommendations;
+}
+/**
+ * Maps Figma design tokens to existing theme tokens in app.css.
+ *
+ * @param args - Figma tokens array and optional theme file path
+ * @param workspaceRoot - Optional workspace root for theme file discovery; used when themeFilePath is not provided
+ * @returns Formatted mapping report with exact/fuzzy matches, confidence scores, and usage instructions, or error message on failure
+ */
+export function mapFigmaTokensToTheme(args, workspaceRoot) {
+    try {
+        const parsedTheme = parseThemeFile(args.themeFilePath, workspaceRoot);
+        const figmaTokens = args.figmaTokens.map((token) => ({
+            name: token.name,
+            value: token.value,
+            type: token.type,
+            description: token.description,
+        }));
+        const matches = matchTokens(figmaTokens, parsedTheme);
+        let response = `# Figma Design Tokens → StorefrontNext Theme Mapping\n\n`;
+        if (parsedTheme.warnings.length > 0) {
+            response += `## ⚠️ Warnings\n\n`;
+            for (const warning of parsedTheme.warnings) {
+                response += `- ${warning}\n`;
+            }
+            response += `\n`;
+        }
+        response += generateSummary(matches);
+        response += `## Detailed Mapping Results\n\n`;
+        for (const match of matches) {
+            response += formatTokenMatch(match);
+        }
+        response += generateRecommendations(matches);
+        response += `## 💡 Usage Instructions\n\n`;
+        response += `### Using Matched Tokens in Components\n\n`;
+        response += `For exact and high-confidence matches, use the token directly in your Tailwind classes:\n\n`;
+        response += `\`\`\`tsx\n`;
+        response += `// Instead of hardcoded colors\n`;
+        response += `<div className="bg-[#2563eb]">\n\n`;
+        response += `// Use theme tokens\n`;
+        response += `<div className="bg-primary">\n`;
+        response += `\`\`\`\n\n`;
+        response += `### Creating New Tokens\n\n`;
+        response += `If you need to add new tokens, add them to your \`app.css\` file in both light and dark theme sections:\n\n`;
+        response += `\`\`\`css\n`;
+        response += `:root {\n`;
+        response += `  --your-new-token: #value;\n`;
+        response += `}\n\n`;
+        response += `.dark {\n`;
+        response += `  --your-new-token: #dark-value;\n`;
+        response += `}\n`;
+        response += `\`\`\`\n\n`;
+        return response;
+    }
+    catch (error) {
+        const errorMessage = error instanceof Error ? error.message : String(error);
+        return `# Error: Token Mapping Failed\n\n${errorMessage}\n\nPlease ensure the theme file path is correct and accessible.`;
+    }
+}
+/**
+ * Creates the storefront_next_map_tokens_to_theme MCP tool.
+ *
+ * @param loadServices - Function that loads configuration and returns Services instance
+ * @returns MCP tool for token mapping
+ */
+export function createMapTokensToThemeTool(loadServices) {
+    return createToolAdapter({
+        name: 'storefront_next_map_tokens_to_theme',
+        description: 'Maps Figma design tokens to existing StorefrontNext theme tokens in app.css. ' +
+            'Analyzes Figma design tokens (colors, spacing, radius, etc.) and finds exact matches, ' +
+            'provides fuzzy matches with confidence scores, suggests new token names for unmatched values, ' +
+            'and recommends where to add new tokens in the CSS file. ' +
+            'Use this tool after retrieving design variables from Figma MCP to ensure components use theme tokens instead of hardcoded values.',
+        toolsets: ['STOREFRONTNEXT'],
+        isGA: false,
+        requiresInstance: false,
+        inputSchema: mapTokensToThemeSchema.shape,
+        async execute(args, context) {
+            return mapFigmaTokensToTheme(args, context.services.resolveWithProjectDirectory());
+        },
+        formatOutput: (output) => textResult(output),
+    }, loadServices);
+}
+//# sourceMappingURL=index.js.map

package/dist/tools/storefrontnext/figma/map-tokens/token-matcher.d.ts

@@ -0,0 +1,65 @@
+import type { ThemeToken, ParsedTheme } from './css-parser.js';
+/**
+ * Design token extracted from Figma.
+ *
+ * @property {string} name - Token name from Figma (e.g., "Primary/Blue", "Spacing/Large")
+ * @property {string} value - Token value (e.g., "#2563eb", "16px", "0.5rem")
+ * @property {'color'|'fontFamily'|'fontSize'|'opacity'|'other'|'radius'|'spacing'} type - Token type for matching logic
+ * @property {string} [description] - Optional description from Figma
+ */
+export interface FigmaToken {
+    name: string;
+    value: string;
+    type: 'color' | 'fontFamily' | 'fontSize' | 'opacity' | 'other' | 'radius' | 'spacing';
+    description?: string;
+}
+/**
+ * Result of matching a Figma token to theme tokens.
+ *
+ * @property {FigmaToken} figmaToken - The Figma token that was matched
+ * @property {ThemeToken} [matchedToken] - Best-matching theme token (if found)
+ * @property {number} confidence - Match confidence (0-100)
+ * @property {'exact'|'fuzzy'|'none'} matchType - 'exact', 'fuzzy', or 'none'
+ * @property {string} reason - Human-readable explanation of the match
+ * @property {TokenSuggestion[]} [suggestions] - Suggested new tokens or alternatives (when no match or fuzzy match)
+ */
+export interface TokenMatch {
+    figmaToken: FigmaToken;
+    matchedToken?: ThemeToken;
+    confidence: number;
+    matchType: 'exact' | 'fuzzy' | 'none';
+    reason: string;
+    suggestions?: TokenSuggestion[];
+}
+/**
+ * Suggestion for a new or alternative theme token.
+ *
+ * @property {string} tokenName - Suggested CSS custom property name
+ * @property {string} value - Token value
+ * @property {'both'|'dark'|'light'} theme - Which theme(s) to add to: 'both', 'dark', or 'light'
+ * @property {string} reason - Explanation for the suggestion
+ * @property {string} [insertAfter] - Optional token name to insert after in the theme file
+ */
+export interface TokenSuggestion {
+    tokenName: string;
+    value: string;
+    theme: 'both' | 'dark' | 'light';
+    reason: string;
+    insertAfter?: string;
+}
+/**
+ * Matches a single Figma token to existing theme tokens.
+ *
+ * @param figmaToken - Figma design token to match
+ * @param parsedTheme - Parsed theme from app.css
+ * @returns TokenMatch with exact, fuzzy, or no match and optional suggestions
+ */
+export declare function matchToken(figmaToken: FigmaToken, parsedTheme: ParsedTheme): TokenMatch;
+/**
+ * Matches multiple Figma tokens to existing theme tokens.
+ *
+ * @param figmaTokens - Array of Figma design tokens to match
+ * @param parsedTheme - Parsed theme from app.css
+ * @returns Array of TokenMatch results, one per input token
+ */
+export declare function matchTokens(figmaTokens: FigmaToken[], parsedTheme: ParsedTheme): TokenMatch[];

package/dist/tools/storefrontnext/figma/map-tokens/token-matcher.js

@@ -0,0 +1,268 @@
+/*
+ * Copyright (c) 2025, Salesforce, Inc.
+ * SPDX-License-Identifier: Apache-2
+ * For full license text, see the license.txt file in the repo root or http://www.apache.org/licenses/LICENSE-2.0
+ */
+/**
+ * Normalizes hex colors to lowercase 6-digit format
+ */
+function normalizeHexColor(hex) {
+    let normalized = hex.toLowerCase().trim();
+    // Remove # if present
+    if (normalized.startsWith('#')) {
+        normalized = normalized.slice(1);
+    }
+    // Expand 3-digit hex to 6-digit
+    if (normalized.length === 3) {
+        normalized = [...normalized].map((c) => c + c).join('');
+    }
+    return normalized;
+}
+/**
+ * Calculates color distance between two hex colors (0-100, lower is closer)
+ */
+function calculateColorDistance(hex1, hex2) {
+    const r1 = Number.parseInt(hex1.slice(0, 2), 16);
+    const g1 = Number.parseInt(hex1.slice(2, 4), 16);
+    const b1 = Number.parseInt(hex1.slice(4, 6), 16);
+    const r2 = Number.parseInt(hex2.slice(0, 2), 16);
+    const g2 = Number.parseInt(hex2.slice(2, 4), 16);
+    const b2 = Number.parseInt(hex2.slice(4, 6), 16);
+    // Euclidean distance normalized to 0-100 scale
+    const distance = Math.hypot(r1 - r2, g1 - g2, b1 - b2);
+    // Max distance is sqrt(255^2 * 3) ≈ 441
+    return (distance / 441) * 100;
+}
+/**
+ * Calculates string similarity between two strings (0-100, higher is more similar)
+ * Uses Levenshtein distance algorithm
+ */
+function calculateStringSimilarity(str1, str2) {
+    const s1 = str1.toLowerCase();
+    const s2 = str2.toLowerCase();
+    // Exact match
+    if (s1 === s2)
+        return 100;
+    // Contains match bonus
+    if (s1.includes(s2) || s2.includes(s1)) {
+        return 80 + (Math.min(s1.length, s2.length) / Math.max(s1.length, s2.length)) * 20;
+    }
+    // Levenshtein distance
+    const matrix = [];
+    const len1 = s1.length;
+    const len2 = s2.length;
+    for (let i = 0; i <= len1; i++) {
+        matrix[i] = [i];
+    }
+    for (let j = 0; j <= len2; j++) {
+        matrix[0][j] = j;
+    }
+    for (let i = 1; i <= len1; i++) {
+        for (let j = 1; j <= len2; j++) {
+            const cost = s1[i - 1] === s2[j - 1] ? 0 : 1;
+            matrix[i][j] = Math.min(matrix[i - 1][j] + 1, matrix[i][j - 1] + 1, matrix[i - 1][j - 1] + cost);
+        }
+    }
+    const distance = matrix[len1][len2];
+    const maxLen = Math.max(len1, len2);
+    return ((maxLen - distance) / maxLen) * 100;
+}
+/**
+ * Extracts semantic meaning from token name
+ */
+function extractSemantics(name) {
+    const parts = name.toLowerCase().replace(/^--/, '').split(/[-_]/);
+    const semantics = [];
+    // Color semantics
+    const colorKeywords = new Set([
+        'accent',
+        'background',
+        'border',
+        'destructive',
+        'error',
+        'foreground',
+        'info',
+        'muted',
+        'primary',
+        'secondary',
+        'success',
+        'text',
+        'warning',
+    ]);
+    const lightDark = new Set(['dark', 'light']);
+    const colorNames = new Set(['black', 'blue', 'gray', 'green', 'orange', 'purple', 'red', 'white', 'yellow']);
+    for (const part of parts) {
+        if (colorKeywords.has(part)) {
+            semantics.push(`semantic:${part}`);
+        }
+        if (lightDark.has(part)) {
+            semantics.push(`theme:${part}`);
+        }
+        if (colorNames.has(part)) {
+            semantics.push(`color:${part}`);
+        }
+    }
+    return semantics;
+}
+/**
+ * Finds exact color match
+ */
+function findExactColorMatch(figmaValue, parsedTheme) {
+    const normalizedFigma = normalizeHexColor(figmaValue);
+    for (const token of parsedTheme.tokens) {
+        if (token.type === 'color' && token.resolvedValue) {
+            const normalizedToken = normalizeHexColor(token.resolvedValue);
+            if (normalizedFigma === normalizedToken) {
+                return token;
+            }
+        }
+    }
+    return null;
+}
+/**
+ * Finds fuzzy matches based on color similarity and name similarity
+ */
+function findFuzzyMatches(figmaToken, parsedTheme) {
+    const matches = [];
+    // Filter tokens by type
+    const relevantTokens = parsedTheme.tokens.filter((token) => token.type === figmaToken.type);
+    const figmaSemantics = extractSemantics(figmaToken.name);
+    const normalizedFigmaValue = figmaToken.type === 'color' && figmaToken.value.startsWith('#')
+        ? normalizeHexColor(figmaToken.value)
+        : figmaToken.value;
+    for (const token of relevantTokens) {
+        let score = 0;
+        // Name similarity (40% weight)
+        const nameSimilarity = calculateStringSimilarity(figmaToken.name, token.name);
+        score += nameSimilarity * 0.4;
+        // Semantic similarity (30% weight)
+        const tokenSemantics = extractSemantics(token.name);
+        const semanticMatches = figmaSemantics.filter((s) => tokenSemantics.includes(s)).length;
+        const semanticScore = figmaSemantics.length > 0 ? (semanticMatches / figmaSemantics.length) * 100 : 0;
+        score += semanticScore * 0.3;
+        // Value similarity (30% weight)
+        if (figmaToken.type === 'color' && token.resolvedValue) {
+            const normalizedTokenValue = normalizeHexColor(token.resolvedValue);
+            const colorDistance = calculateColorDistance(normalizedFigmaValue, normalizedTokenValue);
+            const colorSimilarity = Math.max(0, 100 - colorDistance);
+            score += colorSimilarity * 0.3;
+        }
+        if (score > 20) {
+            // Only include matches with score > 20
+            matches.push({ token, score });
+        }
+    }
+    // Sort by score descending
+    return matches.sort((a, b) => b.score - a.score);
+}
+/**
+ * Generates suggestions for new tokens if no good match found
+ */
+function generateTokenSuggestions(figmaToken, parsedTheme) {
+    const suggestions = [];
+    // Analyze existing token naming patterns
+    const existingNames = parsedTheme.tokens.filter((t) => t.type === figmaToken.type).map((t) => t.name);
+    // Extract common prefixes
+    const hasColorPrefix = existingNames.some((n) => n.startsWith('--color-'));
+    const hasRadiusPrefix = existingNames.some((n) => n.startsWith('--radius-'));
+    // Generate token name based on Figma token name
+    let suggestedName = figmaToken.name.toLowerCase().replaceAll(/[^a-z0-9-]/g, '-');
+    // Add appropriate prefix if not present
+    if (figmaToken.type === 'color' && !suggestedName.startsWith('--color-') && hasColorPrefix) {
+        suggestedName = `--color-${suggestedName.replace(/^--/, '')}`;
+    }
+    else if (figmaToken.type === 'radius' && !suggestedName.startsWith('--radius-') && hasRadiusPrefix) {
+        suggestedName = `--radius-${suggestedName.replace(/^--/, '')}`;
+    }
+    else if (!suggestedName.startsWith('--')) {
+        suggestedName = `--${suggestedName}`;
+    }
+    // Find a good place to insert
+    const similarTokens = existingNames.filter((name) => {
+        const similarity = calculateStringSimilarity(name, suggestedName);
+        return similarity > 30;
+    });
+    const insertAfter = similarTokens.length > 0 ? similarTokens[0] : undefined;
+    // For colors, suggest both light and dark values
+    if (figmaToken.type === 'color') {
+        suggestions.push({
+            tokenName: suggestedName,
+            value: figmaToken.value,
+            theme: 'both',
+            reason: `New token suggestion based on Figma token "${figmaToken.name}"`,
+            insertAfter,
+        });
+    }
+    else {
+        suggestions.push({
+            tokenName: suggestedName,
+            value: figmaToken.value,
+            theme: 'light',
+            reason: `New token suggestion based on Figma token "${figmaToken.name}"`,
+            insertAfter,
+        });
+    }
+    return suggestions;
+}
+/**
+ * Matches a single Figma token to existing theme tokens.
+ *
+ * @param figmaToken - Figma design token to match
+ * @param parsedTheme - Parsed theme from app.css
+ * @returns TokenMatch with exact, fuzzy, or no match and optional suggestions
+ */
+export function matchToken(figmaToken, parsedTheme) {
+    // Try exact match first (only for colors with hex values)
+    if (figmaToken.type === 'color' && figmaToken.value.startsWith('#')) {
+        const exactMatch = findExactColorMatch(figmaToken.value, parsedTheme);
+        if (exactMatch) {
+            return {
+                figmaToken,
+                matchedToken: exactMatch,
+                confidence: 100,
+                matchType: 'exact',
+                reason: `Exact color match: ${figmaToken.value} matches ${exactMatch.name}`,
+            };
+        }
+    }
+    // Try fuzzy matching
+    const fuzzyMatches = findFuzzyMatches(figmaToken, parsedTheme);
+    if (fuzzyMatches.length > 0 && fuzzyMatches[0].score >= 50) {
+        const bestMatch = fuzzyMatches[0];
+        return {
+            figmaToken,
+            matchedToken: bestMatch.token,
+            confidence: Math.round(bestMatch.score),
+            matchType: 'fuzzy',
+            reason: `Fuzzy match based on name similarity and semantic meaning`,
+            suggestions: fuzzyMatches.length > 1
+                ? fuzzyMatches.slice(1, 4).map((m) => ({
+                    tokenName: m.token.name,
+                    value: m.token.value,
+                    theme: m.token.theme === 'shared' ? 'both' : m.token.theme,
+                    reason: `Alternative match (confidence: ${Math.round(m.score)}%)`,
+                }))
+                : undefined,
+        };
+    }
+    // No good match found, generate suggestions
+    const suggestions = generateTokenSuggestions(figmaToken, parsedTheme);
+    return {
+        figmaToken,
+        confidence: 0,
+        matchType: 'none',
+        reason: 'No matching token found. Consider creating a new token.',
+        suggestions,
+    };
+}
+/**
+ * Matches multiple Figma tokens to existing theme tokens.
+ *
+ * @param figmaTokens - Array of Figma design tokens to match
+ * @param parsedTheme - Parsed theme from app.css
+ * @returns Array of TokenMatch results, one per input token
+ */
+export function matchTokens(figmaTokens, parsedTheme) {
+    return figmaTokens.map((token) => matchToken(token, parsedTheme));
+}
+//# sourceMappingURL=token-matcher.js.map

package/dist/tools/storefrontnext/index.d.ts

@@ -1,3 +1,20 @@
+/**
+ * Storefront Next toolset for B2C Commerce.
+ *
+ * This toolset provides MCP tools for Storefront Next development.
+ *
+ * **Implemented Tools:**
+ * - `storefront_next_development_guidelines` - Get development guidelines and best practices
+ * - `storefront_next_page_designer_decorator` - Add Page Designer decorators to React components
+ * - `storefront_next_site_theming` - Get theming guidelines, questions, and validation
+ * - `storefront_next_figma_to_component_workflow` - Convert Figma to components
+ * - `storefront_next_generate_component` - Generate new components
+ * - `storefront_next_map_tokens_to_theme` - Map design tokens
+ *
+ * Note: mrt_bundle_push is defined in the MRT toolset and appears in STOREFRONTNEXT.
+ *
+ * @module tools/storefrontnext
+ */
 import type { McpTool } from '../../utils/index.js';
 import type { Services } from '../../services.js';
 /**