@salesforce/b2c-dx-mcp 0.4.3 → 0.4.5

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';
 /**

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;