generate_semantic_colors

Instructions

Implementation Reference

• src/tools/generate-semantic-colors.ts:57-215 (handler)

  Core handler function executing the tool logic: validates base palette, generates semantic color mappings for roles like primary/success/error, ensures accessibility compliance, produces reports and recommendations.

  export async function generateSemanticColors(
    params: GenerateSemanticColorsParams
  ): Promise<ToolResponse | ErrorResponse> {
    const startTime = Date.now();
  
    try {
      // Validate required parameters
      if (!params.base_palette || params.base_palette.length === 0) {
        return createErrorResponse(
          'generate_semantic_colors',
          'MISSING_PARAMETER',
          'Base palette parameter is required and must contain at least one color',
          Date.now() - startTime,
          {
            details: { parameter: 'base_palette' },
            suggestions: ['Provide an array of colors in any supported format'],
          }
        );
      }
  
      // Validate all colors in base palette
      const basePalette: UnifiedColor[] = [];
      for (let i = 0; i < params.base_palette.length; i++) {
        const colorStr = params.base_palette[i];
        if (!colorStr) {
          return createErrorResponse(
            'generate_semantic_colors',
            'INVALID_COLOR',
            `Color at index ${i} is undefined`,
            Date.now() - startTime,
            {
              details: { index: i },
              suggestions: ['Ensure all colors in the palette are defined'],
            }
          );
        }
  
        const validation = validateColorInput(colorStr);
        if (!validation.isValid) {
          return createErrorResponse(
            'generate_semantic_colors',
            'INVALID_COLOR',
            `Invalid color at index ${i}: ${colorStr}`,
            Date.now() - startTime,
            {
              details: { index: i, provided: colorStr, error: validation.error },
              suggestions: [
                'Ensure all colors are in valid formats like #FF0000 or rgb(255, 0, 0)',
              ],
            }
          );
        }
        basePalette.push(new UnifiedColor(colorStr));
      }
  
      // Set defaults
      const semanticRoles = params.semantic_roles || [
        'primary',
        'secondary',
        'success',
        'warning',
        'error',
        'info',
        'neutral',
      ];
      const context = params.context || 'web';
      const ensureContrast = params.ensure_contrast !== false; // Default to true
      const accessibilityLevel = params.accessibility_level || 'AA';
  
      // Generate semantic mapping
      const semanticMapping = await generateSemanticMapping(
        basePalette,
        semanticRoles,
        context,
        ensureContrast,
        accessibilityLevel
      );
  
      // Generate accessibility report
      const accessibilityReport = await generateSemanticAccessibilityReport(
        semanticMapping,
        accessibilityLevel
      );
  
      // Generate usage recommendations
      const usageRecommendations = generateUsageRecommendations(
        semanticMapping,
        context,
        accessibilityReport
      );
  
      // Prepare response
      const responseData: GenerateSemanticColorsResponse = {
        base_palette: params.base_palette,
        context,
        semantic_mapping: semanticMapping,
        accessibility_report: accessibilityReport,
        usage_recommendations: usageRecommendations,
      };
  
      const executionTime = Date.now() - startTime;
  
      // Generate accessibility notes
      const accessibilityNotes: string[] = [];
      if (accessibilityReport.overall_compliance === 'FAIL') {
        accessibilityNotes.push(
          'Some semantic colors do not meet accessibility standards'
        );
      } else if (accessibilityReport.overall_compliance === 'AA') {
        accessibilityNotes.push('Semantic colors meet WCAG AA standards');
      } else {
        accessibilityNotes.push('Semantic colors meet WCAG AAA standards');
      }
  
      if (accessibilityReport.adjustments_made > 0) {
        accessibilityNotes.push(
          `${accessibilityReport.adjustments_made} colors were adjusted for accessibility`
        );
      }
  
      const recommendations: string[] = [];
      if (accessibilityReport.contrast_issues.length > 0) {
        recommendations.push(
          `${accessibilityReport.contrast_issues.length} contrast issues found`
        );
      }
      recommendations.push(...usageRecommendations.slice(0, 3));
  
      return createSuccessResponse(
        'generate_semantic_colors',
        responseData,
        executionTime,
        {
          colorSpaceUsed: 'sRGB',
          accessibilityNotes,
          recommendations: recommendations.slice(0, 5),
        }
      );
    } catch (error) {
      const executionTime = Date.now() - startTime;
      return createErrorResponse(
        'generate_semantic_colors',
        'SEMANTIC_MAPPING_ERROR',
        `Failed to generate semantic colors: ${error instanceof Error ? error.message : 'Unknown error'}`,
        executionTime,
        {
          details: {
            base_palette: params.base_palette,
            context: params.context,
          },
          suggestions: [
            'Check that all colors in the base palette are valid',
            'Ensure the context is supported',
            'Try with different parameters',
          ],
        }
      );
    }
  }

• src/tools/generate-semantic-colors.ts:11-25 (schema)

  TypeScript interface for input parameters including base color palette and optional semantic roles/context.

  export interface GenerateSemanticColorsParams {
    base_palette: string[];
    semantic_roles?: Array<
      | 'primary'
      | 'secondary'
      | 'success'
      | 'warning'
      | 'error'
      | 'info'
      | 'neutral'
    >;
    context?: 'web' | 'mobile' | 'desktop' | 'print';
    ensure_contrast?: boolean;
    accessibility_level?: 'AA' | 'AAA';
  }

• src/tools/generate-semantic-colors.ts:37-52 (schema)

  TypeScript interface for the tool's response structure including semantic mappings and accessibility report.

  export interface GenerateSemanticColorsResponse {
    base_palette: string[];
    context: string;
    semantic_mapping: SemanticColorRole[];
    accessibility_report: {
      overall_compliance: 'AA' | 'AAA' | 'FAIL';
      contrast_issues: Array<{
        role: string;
        color: string;
        issue: string;
        recommendation: string;
      }>;
      adjustments_made: number;
    };
    usage_recommendations: string[];
  }

• src/tools/index.ts:86-86 (registration)

  Import statement for the generateSemanticColorsTool.

  import { generateSemanticColorsTool } from './generate-semantic-colors';

• src/tools/index.ts:131-131 (registration)

  Registration of the generate_semantic_colors tool in the central tool registry.

  toolRegistry.registerTool(generateSemanticColorsTool);