@salesforce/b2c-dx-mcp 0.4.4 → 0.4.6

package/dist/tools/storefrontnext/index.js

@@ -3,62 +3,12 @@
  * 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
  */
-/**
- * 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 (GA)
- *
- * **Placeholder Tools (Use `--allow-non-ga-tools` flag to enable):**
- * - `storefront_next_site_theming` - Configure site theming
- * - `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
- * - `storefront_next_generate_page_designer_metadata` - Generate Page Designer metadata
- *
- * @module tools/storefrontnext
- */
-import { z } from 'zod';
-import { createToolAdapter, jsonResult } from '../adapter.js';
-import { createDeveloperGuidelinesTool } from './developer-guidelines.js';
+import { createDeveloperGuidelinesTool } from './sfnext-development-guidelines.js';
 import { createPageDesignerDecoratorTool } from './page-designer-decorator/index.js';
-/**
- * Creates a placeholder tool for Storefront Next development.
- *
- * Placeholder tools log invocations and return mock responses until
- * the actual implementation is available.
- *
- * @param name - Tool name
- * @param description - Tool description
- * @param loadServices - Function that loads configuration and returns Services instance
- * @returns The configured MCP tool
- */
-function createPlaceholderTool(name, description, loadServices) {
-    return createToolAdapter({
-        name,
-        description: `[PLACEHOLDER] ${description}`,
-        toolsets: ['STOREFRONTNEXT'],
-        isGA: false,
-        requiresInstance: false,
-        inputSchema: {
-            message: z.string().optional().describe('Optional message to echo'),
-        },
-        async execute(args) {
-            // Placeholder implementation
-            const timestamp = new Date().toISOString();
-            return {
-                tool: name,
-                status: 'placeholder',
-                message: `This is a placeholder implementation for '${name}'. The actual implementation is coming soon.`,
-                input: args,
-                timestamp,
-            };
-        },
-        formatOutput: (output) => jsonResult(output),
-    }, loadServices);
-}
+import { createSiteThemingTool } from './site-theming/index.js';
+import { createFigmaToComponentTool } from './figma/figma-to-component/index.js';
+import { createGenerateComponentTool } from './figma/generate-component/index.js';
+import { createMapTokensToThemeTool } from './figma/map-tokens/index.js';
 /**
  * Creates all tools for the STOREFRONTNEXT toolset.
  *
@@ -73,11 +23,11 @@ export function createStorefrontNextTools(loadServices) {
     return [
         createDeveloperGuidelinesTool(loadServices),
         createPageDesignerDecoratorTool(loadServices),
-        createPlaceholderTool('storefront_next_site_theming', 'Configure and manage site theming for Storefront Next', loadServices),
-        createPlaceholderTool('storefront_next_figma_to_component_workflow', 'Convert Figma designs to Storefront Next components', loadServices),
-        createPlaceholderTool('storefront_next_generate_component', 'Generate a new Storefront Next component', loadServices),
-        createPlaceholderTool('storefront_next_map_tokens_to_theme', 'Map design tokens to Storefront Next theme configuration', loadServices),
-        createPlaceholderTool('storefront_next_generate_page_designer_metadata', 'Generate Page Designer metadata for Storefront Next components', loadServices),
+        createSiteThemingTool(loadServices),
+        createPageDesignerDecoratorTool(loadServices),
+        createFigmaToComponentTool(loadServices),
+        createGenerateComponentTool(loadServices),
+        createMapTokensToThemeTool(loadServices),
     ];
 }
 //# sourceMappingURL=index.js.map

package/dist/tools/storefrontnext/page-designer-decorator/analyzer.js

@@ -226,12 +226,27 @@ export function generateTypeSuggestions(propName, tsType) {
 // ============================================================================
 /**
  * Extract component name from file content
+ *
+ * Priority order:
+ * 1. export default function X (inline default function)
+ * 2. export default X (default export of named identifier, e.g. export default ProductItem)
+ * 3. export function X (first named function export)
+ * 4. export const X =
+ * 5. fallback: 'Component'
+ *
+ * Note: (2) must be checked before (3) because files may have both "export function Foo"
+ * and "export default Bar" — the default export is the primary component.
  */
 function extractComponentName(content) {
     const defaultFunctionMatch = content.match(/export\s+default\s+function\s+(\w+)/);
     if (defaultFunctionMatch) {
         return defaultFunctionMatch[1];
     }
+    // export default X where X is a named identifier (not "function")
+    const defaultNamedMatch = content.match(/export\s+default\s+(?!function\s)(\w+)/);
+    if (defaultNamedMatch) {
+        return defaultNamedMatch[1];
+    }
     const namedFunctionMatch = content.match(/export\s+function\s+(\w+)/);
     if (namedFunctionMatch) {
         return namedFunctionMatch[1];

package/dist/tools/storefrontnext/page-designer-decorator/index.js

@@ -14,7 +14,7 @@ export const pageDesignerDecoratorSchema = z
     .object({
     component: z
         .string()
-        .describe('Component name (e.g., "ProductCard", "Hero") or file path (e.g., "src/components/ProductCard.tsx"). ' +
+        .describe('Component name (e.g., "ProductItem", "ProductTile") or file path (e.g., "src/components/ProductItem.tsx"). ' +
         'When a name is provided, the tool automatically searches common component directories. ' +
         'For backward compatibility, file paths are also supported.'),
     searchPaths: z
@@ -530,7 +530,7 @@ export function createPageDesignerDecoratorTool(loadServices) {
         name: 'storefront_next_page_designer_decorator',
         description: 'Adds Page Designer decorators (@Component, @AttributeDefinition, @RegionDefinition) to React components. ' +
             'Two modes: autoMode=true for quick setup with defaults, or interactive mode via conversationContext.step. ' +
-            'Component discovery uses projectDirectory from flags/env. ' +
+            'Component discovery uses --project-directory flag or SFCC_PROJECT_DIRECTORY env var. ' +
             'Auto mode: selects suitable props, infers types, generates code immediately. ' +
             'Interactive mode: multi-step workflow (analyze → select_props → configure_attrs → configure_regions → confirm_generation).',
         inputSchema: pageDesignerDecoratorSchema.shape,
@@ -543,7 +543,7 @@ export function createPageDesignerDecoratorTool(loadServices) {
                 // Use projectDirectory from services to ensure we search in the correct project directory
                 // This prevents searches in the home folder when MCP clients spawn servers from ~
                 const services = loadServices();
-                const workspaceRoot = services.getWorkingDirectory();
+                const workspaceRoot = services.resolveWithProjectDirectory();
                 if (validatedArgs.autoMode === undefined && !validatedArgs.conversationContext) {
                     const fullPath = resolveComponent(validatedArgs.component, workspaceRoot, validatedArgs.searchPaths);
                     const componentInfo = componentAnalyzer.analyzeComponent(fullPath);

package/dist/tools/storefrontnext/{developer-guidelines.js → sfnext-development-guidelines.js}

@@ -9,7 +9,7 @@
  * Provides critical development guidelines and best practices for building
  * Storefront Next applications with React Server Components.
  *
- * @module tools/storefrontnext/developer-guidelines
+ * @module tools/storefrontnext/sfnext-development-guidelines
  */
 import { readFileSync } from 'node:fs';
 import { createRequire } from 'node:module';
@@ -21,7 +21,7 @@ import { createToolAdapter, textResult } from '../adapter.js';
 // regardless of where this module is located in the build output
 const require = createRequire(import.meta.url);
 const packageRoot = path.dirname(require.resolve('@salesforce/b2c-dx-mcp/package.json'));
-const CONTENT_DIR = path.join(packageRoot, 'content');
+const CONTENT_DIR = path.join(packageRoot, 'content', 'sfnext');
 /**
  * Section metadata with key and optional description.
  * Single source of truth for all available sections.
@@ -137,4 +137,4 @@ export function createDeveloperGuidelinesTool(loadServices) {
         formatOutput: (output) => textResult(output),
     }, loadServices);
 }
-//# sourceMappingURL=developer-guidelines.js.map
+//# sourceMappingURL=sfnext-development-guidelines.js.map

package/dist/tools/storefrontnext/site-theming/color-contrast.d.ts

@@ -0,0 +1,92 @@
+/**
+ * Validates that a string is a valid 6-digit hex color.
+ * @param hex - Hex color string to validate
+ * @returns true if valid
+ */
+export declare function isValidHex(hex: string): boolean;
+/**
+ * Calculates the relative luminance of a color according to WCAG 2.1
+ * @param hex - Hex color string (e.g., "#635BFF")
+ * @returns Relative luminance value between 0 and 1
+ * @throws Error if hex format is invalid
+ */
+export declare function getLuminance(hex: string): number;
+/**
+ * Calculates the contrast ratio between two colors according to WCAG 2.1
+ * @param color1 - First hex color string
+ * @param color2 - Second hex color string
+ * @returns Contrast ratio (1:1 to 21:1)
+ */
+export declare function getContrastRatio(color1: string, color2: string): number;
+/**
+ * WCAG compliance levels
+ */
+export declare enum WCAGLevel {
+    AA = "AA",// 4.5:1 for normal text
+    AA_LARGE = "AA_LARGE",// 3:1 for large text
+    AAA = "AAA",// 7:1 for normal text
+    AAA_LARGE = "AAA_LARGE",// 4.5:1 for large text
+    FAIL = "FAIL"
+}
+/**
+ * Determines WCAG compliance level for a contrast ratio
+ * @param ratio - Contrast ratio
+ * @param isLargeText - Whether this is for large text (18pt+ or 14pt+ bold)
+ * @returns WCAG compliance level
+ */
+export declare function getWCAGLevel(ratio: number, isLargeText?: boolean): WCAGLevel;
+/**
+ * Result of color contrast validation for a single foreground/background pair.
+ *
+ * @property {string} color1 - First hex color (typically foreground)
+ * @property {string} color2 - Second hex color (typically background)
+ * @property {number} ratio - Contrast ratio (1:1 to 21:1)
+ * @property {WCAGLevel} wcagLevel - WCAG compliance level
+ * @property {boolean} passesAA - Whether the combination meets WCAG AA
+ * @property {boolean} passesAAA - Whether the combination meets WCAG AAA
+ * @property {boolean} isLargeText - Whether validation used large-text thresholds
+ * @property {string} visualAssessment - Readability assessment (excellent, good, acceptable, poor)
+ * @property {string} [recommendation] - Optional suggestion when contrast is suboptimal
+ */
+export interface ContrastValidationResult {
+    color1: string;
+    color2: string;
+    ratio: number;
+    wcagLevel: WCAGLevel;
+    passesAA: boolean;
+    passesAAA: boolean;
+    isLargeText: boolean;
+    visualAssessment: 'acceptable' | 'excellent' | 'good' | 'poor';
+    recommendation?: string;
+}
+/**
+ * Validates contrast between two colors
+ * @param color1 - First hex color string
+ * @param color2 - Second hex color string
+ * @param isLargeText - Whether this is for large text
+ * @returns Validation result with contrast ratio and compliance info
+ */
+export declare function validateContrast(color1: string, color2: string, isLargeText?: boolean): ContrastValidationResult;
+/**
+ * Validates multiple color combinations for WCAG compliance.
+ *
+ * @param combinations - Array of foreground/background pairs with optional label and large-text flag
+ * @returns Array of validation results, each including the input label if provided
+ */
+export declare function validateColorCombinations(combinations: Array<{
+    foreground: string;
+    background: string;
+    isLargeText?: boolean;
+    label?: string;
+}>): Array<ContrastValidationResult & {
+    label?: string;
+}>;
+/**
+ * Formats a validation result as a human-readable string for display to users.
+ *
+ * @param result - Validation result, optionally with a label for the color combination
+ * @returns Multi-line string with contrast ratio, WCAG status, and recommendation (if any)
+ */
+export declare function formatValidationResult(result: ContrastValidationResult & {
+    label?: string;
+}): string;

package/dist/tools/storefrontnext/site-theming/color-contrast.js

@@ -0,0 +1,186 @@
+/*
+ * 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
+ */
+/**
+ * WCAG 2.1 color contrast utilities for accessibility validation.
+ *
+ * Provides luminance calculation, contrast ratio computation, and WCAG compliance
+ * checking for theming and color validation in Storefront Next.
+ *
+ * @module tools/storefrontnext/site-theming/color-contrast
+ */
+/**
+ * WCAG 2.1 constants for contrast ratio calculation
+ * These values are specified in the WCAG 2.1 standard
+ */
+const WCAG_CONTRAST_OFFSET = 0.05; // Offset added to luminance values in contrast ratio formula
+// Linear RGB conversion constants (sRGB to linear RGB)
+const LINEAR_RGB_THRESHOLD = 0.039_28; // Threshold for linear RGB conversion
+const LINEAR_RGB_DIVISOR = 12.92; // Divisor for values below threshold
+const GAMMA_CORRECTION_OFFSET = 0.055; // Offset for gamma correction
+const GAMMA_CORRECTION_DIVISOR = 1.055; // Divisor for gamma correction
+const GAMMA_EXPONENT = 2.4; // Gamma exponent for sRGB
+// Relative luminance weights (WCAG 2.1 standard)
+const LUMINANCE_RED_WEIGHT = 0.2126;
+const LUMINANCE_GREEN_WEIGHT = 0.7152;
+const LUMINANCE_BLUE_WEIGHT = 0.0722;
+/** Valid 6-digit hex color pattern (with optional # prefix) */
+const HEX_PATTERN = /^#?[0-9A-Fa-f]{6}$/;
+/**
+ * Validates that a string is a valid 6-digit hex color.
+ * @param hex - Hex color string to validate
+ * @returns true if valid
+ */
+export function isValidHex(hex) {
+    return typeof hex === 'string' && HEX_PATTERN.test(hex.trim());
+}
+/**
+ * Calculates the relative luminance of a color according to WCAG 2.1
+ * @param hex - Hex color string (e.g., "#635BFF")
+ * @returns Relative luminance value between 0 and 1
+ * @throws Error if hex format is invalid
+ */
+export function getLuminance(hex) {
+    const trimmed = hex.trim();
+    if (!HEX_PATTERN.test(trimmed)) {
+        throw new Error(`Invalid hex color: "${hex}". Expected 6-digit hex (e.g., #635BFF).`);
+    }
+    const cleanHex = trimmed.replace('#', '');
+    // Parse RGB values
+    const r = Number.parseInt(cleanHex.slice(0, 2), 16) / 255;
+    const g = Number.parseInt(cleanHex.slice(2, 4), 16) / 255;
+    const b = Number.parseInt(cleanHex.slice(4, 6), 16) / 255;
+    // Convert to linear RGB
+    const [rs, gs, bs] = [r, g, b].map((c) => {
+        return c <= LINEAR_RGB_THRESHOLD
+            ? c / LINEAR_RGB_DIVISOR
+            : ((c + GAMMA_CORRECTION_OFFSET) / GAMMA_CORRECTION_DIVISOR) ** GAMMA_EXPONENT;
+    });
+    // Calculate relative luminance
+    return LUMINANCE_RED_WEIGHT * rs + LUMINANCE_GREEN_WEIGHT * gs + LUMINANCE_BLUE_WEIGHT * bs;
+}
+/**
+ * Calculates the contrast ratio between two colors according to WCAG 2.1
+ * @param color1 - First hex color string
+ * @param color2 - Second hex color string
+ * @returns Contrast ratio (1:1 to 21:1)
+ */
+export function getContrastRatio(color1, color2) {
+    const l1 = getLuminance(color1);
+    const l2 = getLuminance(color2);
+    const lighter = Math.max(l1, l2);
+    const darker = Math.min(l1, l2);
+    return (lighter + WCAG_CONTRAST_OFFSET) / (darker + WCAG_CONTRAST_OFFSET);
+}
+/**
+ * WCAG compliance levels
+ */
+export var WCAGLevel;
+(function (WCAGLevel) {
+    WCAGLevel["AA"] = "AA";
+    WCAGLevel["AA_LARGE"] = "AA_LARGE";
+    WCAGLevel["AAA"] = "AAA";
+    WCAGLevel["AAA_LARGE"] = "AAA_LARGE";
+    WCAGLevel["FAIL"] = "FAIL";
+})(WCAGLevel || (WCAGLevel = {}));
+/**
+ * Determines WCAG compliance level for a contrast ratio
+ * @param ratio - Contrast ratio
+ * @param isLargeText - Whether this is for large text (18pt+ or 14pt+ bold)
+ * @returns WCAG compliance level
+ */
+export function getWCAGLevel(ratio, isLargeText = false) {
+    if (isLargeText) {
+        if (ratio >= 4.5) {
+            return WCAGLevel.AAA_LARGE;
+        }
+        if (ratio >= 3) {
+            return WCAGLevel.AA_LARGE;
+        }
+        return WCAGLevel.FAIL;
+    }
+    if (ratio >= 7) {
+        return WCAGLevel.AAA;
+    }
+    if (ratio >= 4.5) {
+        return WCAGLevel.AA;
+    }
+    return WCAGLevel.FAIL;
+}
+/**
+ * Validates contrast between two colors
+ * @param color1 - First hex color string
+ * @param color2 - Second hex color string
+ * @param isLargeText - Whether this is for large text
+ * @returns Validation result with contrast ratio and compliance info
+ */
+export function validateContrast(color1, color2, isLargeText = false) {
+    const ratio = getContrastRatio(color1, color2);
+    const wcagLevel = getWCAGLevel(ratio, isLargeText);
+    const passesAA = ratio >= (isLargeText ? 3 : 4.5);
+    const passesAAA = ratio >= (isLargeText ? 4.5 : 7);
+    // Visual assessment based on ratio
+    let visualAssessment;
+    let recommendation;
+    if (ratio >= 7) {
+        visualAssessment = 'excellent';
+    }
+    else if (ratio >= 5) {
+        visualAssessment = 'good';
+    }
+    else if (ratio >= 4.5) {
+        visualAssessment = 'acceptable';
+        recommendation =
+            'Meets minimum WCAG AA but may be difficult to read, especially for body text. Consider using a darker/lighter color for better readability.';
+    }
+    else {
+        visualAssessment = 'poor';
+        recommendation =
+            'Does not meet WCAG AA standards. Text will be difficult to read. Strongly recommend using a color with better contrast.';
+    }
+    return {
+        color1,
+        color2,
+        ratio,
+        wcagLevel,
+        passesAA,
+        passesAAA,
+        isLargeText,
+        visualAssessment,
+        recommendation,
+    };
+}
+/**
+ * Validates multiple color combinations for WCAG compliance.
+ *
+ * @param combinations - Array of foreground/background pairs with optional label and large-text flag
+ * @returns Array of validation results, each including the input label if provided
+ */
+export function validateColorCombinations(combinations) {
+    return combinations.map((combo) => ({
+        ...validateContrast(combo.foreground, combo.background, combo.isLargeText ?? false),
+        label: combo.label,
+    }));
+}
+/**
+ * Formats a validation result as a human-readable string for display to users.
+ *
+ * @param result - Validation result, optionally with a label for the color combination
+ * @returns Multi-line string with contrast ratio, WCAG status, and recommendation (if any)
+ */
+export function formatValidationResult(result) {
+    const label = result.label ? `${result.label}: ` : '';
+    const textType = result.isLargeText ? 'large text' : 'normal text';
+    const wcagStatus = result.passesAAA ? '✅ AAA' : result.passesAA ? '✅ AA' : '❌ FAIL';
+    let output = `${label}${result.color1} on ${result.color2}\n`;
+    output += `  Contrast Ratio: ${result.ratio.toFixed(2)}:1\n`;
+    output += `  WCAG ${textType}: ${wcagStatus}\n`;
+    output += `  Visual Assessment: ${result.visualAssessment.toUpperCase()}\n`;
+    if (result.recommendation) {
+        output += `  ⚠️  ${result.recommendation}\n`;
+    }
+    return output;
+}
+//# sourceMappingURL=color-contrast.js.map

package/dist/tools/storefrontnext/site-theming/color-mapping.d.ts

@@ -0,0 +1,16 @@
+/** A foreground/background color pair for contrast validation */
+export type ColorCombination = {
+    foreground: string;
+    background: string;
+    label: string;
+    isLargeText?: boolean;
+};
+/**
+ * Builds foreground/background color combinations from a semantic color mapping.
+ * Derives pairs for text-on-background, button text, links, etc.
+ */
+export declare function buildColorCombinations(colorMapping: Record<string, string>): ColorCombination[];
+/**
+ * Appends WCAG color contrast validation results to the given instructions string.
+ */
+export declare function appendValidationSection(internalInstructions: string, combinations: ColorCombination[]): string;

package/dist/tools/storefrontnext/site-theming/color-mapping.js

@@ -0,0 +1,131 @@
+/*
+ * 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
+ */
+/**
+ * Derives foreground/background color combinations from a color mapping and
+ * appends WCAG validation results to response text.
+ *
+ * @module tools/storefrontnext/site-theming/color-mapping
+ */
+import { validateColorCombinations, formatValidationResult, isValidHex } from './color-contrast.js';
+function tryTextCombo(key, color, keyLower, ctx) {
+    if (keyLower.includes('text') && keyLower.includes('light') && isValidHex(ctx.lightBg)) {
+        return { foreground: color, background: ctx.lightBg, label: `${key}: ${color} on light background (${ctx.lightBg})` };
+    }
+    if (keyLower.includes('text') && keyLower.includes('dark') && isValidHex(ctx.darkBg)) {
+        return { foreground: color, background: ctx.darkBg, label: `${key}: ${color} on dark background (${ctx.darkBg})` };
+    }
+    const isButtonText = keyLower === 'buttontext' || (keyLower.includes('button') && keyLower.includes('text'));
+    if (isButtonText && isValidHex(ctx.buttonBg)) {
+        return {
+            foreground: color,
+            background: ctx.buttonBg,
+            label: `${key}: ${color} on button background (${ctx.buttonBg})`,
+        };
+    }
+    if (keyLower.includes('link') && isValidHex(ctx.lightBg)) {
+        return { foreground: color, background: ctx.lightBg, label: `${key}: ${color} on light background (${ctx.lightBg})` };
+    }
+    return null;
+}
+function tryBackgroundCombo(key, color, ctx) {
+    const foregroundKey = key.replace(/Background|Bg/i, 'Text') || key.replace(/Background|Bg/i, 'Foreground');
+    const foreground = ctx.colorMapping[foregroundKey] || ctx.colorMapping[`${key.replace(/Background|Bg/i, '')}Text`];
+    if (foreground?.startsWith('#') && isValidHex(foreground)) {
+        return { foreground, background: color, label: `${foregroundKey || 'text'} (${foreground}) on ${key} (${color})` };
+    }
+    return null;
+}
+function tryTextForegroundCombo(key, color, keyLower, ctx) {
+    const backgroundKey = key.replace(/Text|Foreground/i, 'Background') || key.replace(/Text|Foreground/i, 'Bg');
+    let background = ctx.colorMapping[backgroundKey];
+    let backgroundLabel = backgroundKey;
+    if (!background) {
+        background = keyLower.includes('button') ? ctx.buttonBg : keyLower.includes('dark') ? ctx.darkBg : ctx.lightBg;
+        backgroundLabel = keyLower.includes('button')
+            ? 'button background'
+            : keyLower.includes('dark')
+                ? 'dark background'
+                : 'light background';
+    }
+    if (background?.startsWith('#') && isValidHex(background)) {
+        return { foreground: color, background, label: `${key} (${color}) on ${backgroundLabel} (${background})` };
+    }
+    return null;
+}
+function tryComboForEntry(key, color, ctx) {
+    const keyLower = key.toLowerCase();
+    const textCombo = tryTextCombo(key, color, keyLower, ctx);
+    if (textCombo)
+        return textCombo;
+    if (keyLower.includes('background') || keyLower.includes('bg'))
+        return tryBackgroundCombo(key, color, ctx);
+    if (keyLower.includes('text') || keyLower.includes('foreground'))
+        return tryTextForegroundCombo(key, color, keyLower, ctx);
+    return null;
+}
+/**
+ * Builds foreground/background color combinations from a semantic color mapping.
+ * Derives pairs for text-on-background, button text, links, etc.
+ */
+export function buildColorCombinations(colorMapping) {
+    const ctx = {
+        colorMapping,
+        lightBg: colorMapping.lightBackground || colorMapping.background || '#FFFFFF',
+        darkBg: colorMapping.darkBackground || '#18181B',
+        buttonBg: colorMapping.buttonBackground || colorMapping.primary || '#0A2540',
+    };
+    const combinations = [];
+    for (const [key, color] of Object.entries(colorMapping)) {
+        if (!color || !color.startsWith('#') || !isValidHex(color))
+            continue;
+        const combo = tryComboForEntry(key, color, ctx);
+        if (combo)
+            combinations.push(combo);
+    }
+    if (combinations.length === 0) {
+        const whiteBg = '#FFFFFF';
+        const darkBgFallback = '#18181B';
+        for (const [key, color] of Object.entries(colorMapping)) {
+            if (!color || !color.startsWith('#') || !isValidHex(color))
+                continue;
+            if (key.toLowerCase().includes('background') || key.toLowerCase().includes('bg'))
+                continue;
+            combinations.push({ foreground: color, background: whiteBg, label: `${key} (${color}) on white background` }, { foreground: color, background: darkBgFallback, label: `${key} (${color}) on dark background` });
+        }
+    }
+    return combinations;
+}
+/**
+ * Appends WCAG color contrast validation results to the given instructions string.
+ */
+export function appendValidationSection(internalInstructions, combinations) {
+    if (combinations.length === 0) {
+        return internalInstructions;
+    }
+    const results = validateColorCombinations(combinations);
+    let output = internalInstructions;
+    for (const result of results) {
+        output += formatValidationResult(result);
+        output += '\n';
+    }
+    const hasIssues = results.some((r) => !r.passesAA || r.visualAssessment === 'poor' || r.visualAssessment === 'acceptable');
+    if (hasIssues) {
+        output += '### ⚠️ VALIDATION SUMMARY\n\n';
+        output += '**Issues found that should be addressed:**\n\n';
+        for (const result of results.filter((r) => !r.passesAA || r.visualAssessment === 'poor' || r.visualAssessment === 'acceptable')) {
+            output += `- ${result.label || 'Color combination'}: ${result.recommendation || 'Needs improvement'}\n`;
+        }
+        output += '\n';
+        output +=
+            '**You MUST present these findings to the user BEFORE implementing and wait for their confirmation.**\n\n';
+    }
+    else {
+        output += '### ✅ VALIDATION SUMMARY\n\n';
+        output += 'All color combinations meet WCAG AA standards and have good visual assessment.\n\n';
+    }
+    return output;
+}
+//# sourceMappingURL=color-mapping.js.map

package/dist/tools/storefrontnext/site-theming/guidance-merger.d.ts

@@ -0,0 +1,11 @@
+/**
+ * Merges multiple ThemingGuidance objects from different theming files.
+ *
+ * @module tools/storefrontnext/site-theming/guidance-merger
+ */
+import type { ThemingGuidance } from './theming-store.js';
+/**
+ * Merges multiple ThemingGuidance objects into one.
+ * Questions are deduplicated by ID; guidelines, rules, workflows, and validations are combined.
+ */
+export declare function mergeGuidance(guidanceArray: ThemingGuidance[]): ThemingGuidance;