analyze_color_collection
Analyze color collections for diversity, harmony, contrast, temperature distribution, and accessibility metrics to evaluate design quality and compliance.
Instructions
Analyze a collection of colors for diversity, harmony, contrast range, temperature distribution, and accessibility metrics.
Input Schema
TableJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| colors | Yes | Array of colors to analyze (2-50 colors) | |
| metrics | No | Metrics to calculate for the color collection |
Implementation Reference
- Core execution logic of the 'analyze_color_collection' tool. Validates input parameters using Joi schema, parses color strings into UnifiedColor objects, computes various metrics (diversity, harmony, contrast range, temperature distribution, accessibility), generates summary and recommendations, and returns structured response.
async function analyzeCollectionHandler( params: unknown ): Promise<ToolResponse | ErrorResponse> { const startTime = Date.now(); try { // Validate parameters const { error, value } = analyzeCollectionSchema.validate(params); if (error) { return createErrorResponse( 'analyze_color_collection', 'INVALID_PARAMETERS', `Invalid parameters: ${error.details.map(d => d.message).join(', ')}`, Date.now() - startTime, { details: error.details, } ); } const { colors: colorStrings, metrics } = value as AnalyzeCollectionParams; // Parse colors and create analyses const analyses: ColorAnalysis[] = []; for (let i = 0; i < colorStrings.length; i++) { const colorString = colorStrings[i]; if (!colorString) continue; try { const color = new UnifiedColor(colorString); const hsl = color.hsl; const rgb = color.rgb; const metadata = color.metadata; // Calculate brightness using perceived brightness formula const brightness = 0.299 * rgb.r + 0.587 * rgb.g + 0.114 * rgb.b; analyses.push({ color, hue: hsl.h, saturation: hsl.s, lightness: hsl.l, brightness, temperature: metadata?.temperature || 'neutral', contrastWithWhite: color.getContrastRatio('#ffffff'), contrastWithBlack: color.getContrastRatio('#000000'), }); } catch (error) { return createErrorResponse( 'analyze_color_collection', 'INVALID_COLOR', `Invalid color at index ${i}: ${colorString}`, Date.now() - startTime, { details: { colorIndex: i, providedColor: colorString, error: error instanceof Error ? error.message : 'Unknown error', }, suggestions: [ 'Ensure all colors are in valid format (hex, rgb, hsl, etc.)', 'Check color syntax and values', ], } ); } } // Calculate requested metrics const results: AnalysisResults = { total_colors: colorStrings.length, color_summary: analyses.map(a => ({ hex: a.color.hex, hue: Math.round(a.hue * 10) / 10, saturation: Math.round(a.saturation * 10) / 10, lightness: Math.round(a.lightness * 10) / 10, temperature: a.temperature, })), overall_assessment: { score: 0, interpretation: '', }, }; if (metrics.includes('diversity')) { results.diversity = calculateColorDiversity(analyses); } if (metrics.includes('harmony')) { results.harmony = calculateHarmonyScore(analyses); } if (metrics.includes('contrast_range')) { results.contrast_range = calculateContrastRange(analyses); } if (metrics.includes('temperature_distribution')) { results.temperature_distribution = calculateTemperatureDistribution(analyses); } if (metrics.includes('accessibility_score')) { results.accessibility_score = calculateAccessibilityScore(analyses); } const executionTime = Date.now() - startTime; // Generate overall assessment const overallScore = Math.round( [ results.diversity?.score || 0, results.harmony?.score || 0, results.accessibility_score?.score || 0, ].reduce((sum, score) => sum + score, 0) / 3 ); results.overall_assessment = { score: overallScore, interpretation: getOverallInterpretation(overallScore), }; // Generate accessibility notes const accessibilityNotes: string[] = []; if (results.accessibility_score) { accessibilityNotes.push( `Accessibility score: ${results.accessibility_score.score}/100` ); if ( 'recommendations' in results.accessibility_score && results.accessibility_score.recommendations ) { accessibilityNotes.push(...results.accessibility_score.recommendations); } } // Generate recommendations const recommendations: string[] = []; if (results.diversity && results.diversity.score < 50) { recommendations.push( 'Consider adding more diverse colors to improve visual interest' ); } if (results.harmony && results.harmony.score < 50) { recommendations.push('Adjust color relationships to improve harmony'); } if ( results.contrast_range && 'accessibility_percentage' in results.contrast_range && results.contrast_range.accessibility_percentage < 70 ) { recommendations.push('Improve contrast ratios for better accessibility'); } return createSuccessResponse( 'analyze_color_collection', results, executionTime, { colorSpaceUsed: 'hsl', accessibilityNotes: accessibilityNotes, recommendations, } ); } catch (error) { const executionTime = Date.now() - startTime; logger.error('Error in analyze_color_collection tool', { error: error as Error, }); return createErrorResponse( 'analyze_color_collection', 'PROCESSING_ERROR', 'An error occurred while analyzing the color collection', executionTime, { details: { error: error instanceof Error ? error.message : 'Unknown error', }, suggestions: [ 'Check that all input colors are valid', 'Verify metrics parameter contains valid values', 'Try with fewer colors if processing large collections', ], } ); } } - Joi validation schema for tool input parameters: requires 2-50 colors array, optional metrics array with specific valid values.
const analyzeCollectionSchema = Joi.object({ colors: Joi.array() .items(Joi.string().required()) .min(2) .max(50) .required() .messages({ 'array.min': 'At least 2 colors are required for analysis', 'array.max': 'Maximum 50 colors can be analyzed at once', }), metrics: Joi.array() .items( Joi.string().valid( 'diversity', 'harmony', 'contrast_range', 'temperature_distribution', 'accessibility_score' ) ) .default([ 'diversity', 'harmony', 'contrast_range', 'temperature_distribution', 'accessibility_score', ]) .messages({ 'any.only': 'Metrics must be one of: diversity, harmony, contrast_range, temperature_distribution, accessibility_score', }), }); - ToolHandler object definition exporting the tool with name, description, JSON schema for parameters, and reference to the handler function.
export const analyzeColorCollectionTool: ToolHandler = { name: 'analyze_color_collection', description: 'Analyze a collection of colors for diversity, harmony, contrast range, temperature distribution, and accessibility metrics.', parameters: { type: 'object', properties: { colors: { type: 'array', items: { type: 'string' }, minItems: 2, maxItems: 50, description: 'Array of colors to analyze (2-50 colors)', }, metrics: { type: 'array', items: { type: 'string', enum: [ 'diversity', 'harmony', 'contrast_range', 'temperature_distribution', 'accessibility_score', ], }, default: [ 'diversity', 'harmony', 'contrast_range', 'temperature_distribution', 'accessibility_score', ], description: 'Metrics to calculate for the color collection', }, }, required: ['colors'], }, handler: analyzeCollectionHandler, }; - src/tools/index.ts:137-137 (registration)Registers the analyzeColorCollectionTool instance to the central toolRegistry singleton.
toolRegistry.registerTool(analyzeColorCollectionTool); - src/tools/index.ts:92-92 (registration)Imports the analyzeColorCollectionTool from its implementation file prior to registration.
import { analyzeColorCollectionTool } from './analyze-color-collection';