create_theme_preview_html
Generate HTML mockups to visualize color themes in realistic UI contexts like websites, mobile apps, and dashboards for design validation.
Instructions
Generate HTML theme preview mockups showing colors in realistic UI contexts
Input Schema
TableJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
No arguments | |||
Implementation Reference
- Core handler function executing the tool logic: validates inputs, processes theme colors with accessibility checks, generates interactive HTML preview mockups, handles exports, and file saving.
async function createThemePreviewHtml( params: CreateThemePreviewHtmlParams ): Promise<ToolResponse | ErrorResponse> { const startTime = Date.now(); try { // Validate parameters const { error, value } = createThemePreviewHtmlSchema.validate(params); if (error) { return { success: false, error: { code: 'INVALID_PARAMETERS', message: 'Invalid parameters provided', details: error.details, suggestions: [ 'Ensure theme_colors is an object with color name keys and color value strings', 'Check that preview_type is one of: website, mobile_app, dashboard, components', 'Verify components array contains valid component names', ], }, metadata: { execution_time: Date.now() - startTime, tool: 'create_theme_preview_html', timestamp: new Date().toISOString(), }, }; } const validatedParams = value as CreateThemePreviewHtmlParams; // Validate and process theme colors const processedThemeColors: Record< string, { hex: string; rgb: string; hsl: string; name: string; accessibility?: { contrastRatio: number; wcagAA: boolean; wcagAAA: boolean; }; } > = {}; const accessibilityNotes: string[] = []; const recommendations: string[] = []; // Required semantic colors for different preview types const requiredColors = getRequiredColorsForPreviewType( validatedParams.preview_type || 'website' ); const missingColors: string[] = []; for (const [colorName, colorValue] of Object.entries( validatedParams.theme_colors )) { if (!colorValue || typeof colorValue !== 'string') { return { success: false, error: { code: 'INVALID_COLOR_VALUE', message: `Invalid color value for "${colorName}": ${colorValue}`, details: { colorName, colorValue }, suggestions: [ 'Ensure all color values are valid color strings', 'Use hex format like #FF0000', 'Use RGB format like rgb(255, 0, 0)', 'Use HSL format like hsl(0, 100%, 50%)', ], }, metadata: { execution_time: Date.now() - startTime, tool: 'create_theme_preview_html', timestamp: new Date().toISOString(), }, }; } try { // Validate color format const colorValidation = validateColorInput(colorValue); if (!colorValidation.isValid) { return { success: false, error: { code: 'INVALID_COLOR_FORMAT', message: `Invalid color format for "${colorName}": ${colorValue}`, details: { colorName, colorValue, reason: colorValidation.error, }, suggestions: [ 'Use hex format like #FF0000', 'Use RGB format like rgb(255, 0, 0)', 'Use HSL format like hsl(0, 100%, 50%)', 'Check the color format documentation', ], }, metadata: { execution_time: Date.now() - startTime, tool: 'create_theme_preview_html', timestamp: new Date().toISOString(), }, }; } const unifiedColor = new UnifiedColor(colorValue); // Calculate accessibility information let accessibility; if (colorName === 'text' || colorName === 'primary') { // Calculate contrast against background colors const backgroundColors = ['background', 'surface']; let bestContrast = 0; for (const bgColorName of backgroundColors) { if (validatedParams.theme_colors[bgColorName]) { try { const bgColor = new UnifiedColor( validatedParams.theme_colors[bgColorName] ); const contrast = unifiedColor.getContrastRatio(bgColor.hex); bestContrast = Math.max(bestContrast, contrast); } catch { // Ignore errors for background color processing } } } if (bestContrast > 0) { accessibility = { contrastRatio: bestContrast, wcagAA: bestContrast >= 4.5, wcagAAA: bestContrast >= 7.0, }; if (!accessibility.wcagAA) { accessibilityNotes.push( `Color "${colorName}" may not meet WCAG AA contrast requirements (${bestContrast.toFixed(2)}:1)` ); } } } processedThemeColors[colorName] = { hex: unifiedColor.hex, rgb: unifiedColor.toFormat('rgb'), hsl: unifiedColor.toFormat('hsl'), name: colorName, ...(accessibility && { accessibility }), }; } catch (colorError) { return { success: false, error: { code: 'COLOR_PROCESSING_ERROR', message: `Failed to process color "${colorName}": ${colorValue}`, details: { colorName, colorValue, error: colorError }, suggestions: [ 'Verify the color format is supported', 'Check for typos in color values', 'Try a different color format', ], }, metadata: { execution_time: Date.now() - startTime, tool: 'create_theme_preview_html', timestamp: new Date().toISOString(), }, }; } } // Check for missing required colors for (const requiredColor of requiredColors) { if (!processedThemeColors[requiredColor]) { missingColors.push(requiredColor); } } if (missingColors.length > 0) { recommendations.push( `Consider adding these semantic colors for better ${validatedParams.preview_type} preview: ${missingColors.join(', ')}` ); } // Generate additional recommendations const colorCount = Object.keys(processedThemeColors).length; if (colorCount < 3) { recommendations.push( 'Consider adding more semantic colors (background, text, primary, secondary) for a complete theme' ); } if ( validatedParams.preview_type === 'dashboard' && !processedThemeColors['sidebar'] ) { recommendations.push( 'Dashboard previews work best with a sidebar color defined' ); } // Prepare visualization data const visualizationData: ThemePreviewVisualizationData = { themeColors: processedThemeColors, previewType: validatedParams.preview_type || 'website', components: validatedParams.components || [ 'header', 'content', 'buttons', ], interactive: validatedParams.interactive !== false, responsive: validatedParams.responsive !== false, theme: validatedParams.theme || 'light', metadata: { title: 'Theme Preview', description: `${validatedParams.preview_type || 'Website'} preview with ${colorCount} theme colors`, timestamp: new Date().toLocaleString(), colorCount, previewType: validatedParams.preview_type || 'website', }, }; // Generate enhanced HTML with background controls let result: EnhancedVisualizationResult; try { const enhancedOptions: EnhancedHTMLOptions = { interactive: true, // Enable interactive features including JavaScript backgroundControls: { enableToggle: validatedParams.enable_background_controls ?? true, enableColorPicker: validatedParams.enable_background_controls ?? true, defaultBackground: validatedParams.theme === 'dark' ? 'dark' : 'light', }, enableAccessibilityTesting: validatedParams.enable_accessibility_testing ?? true, includeKeyboardHelp: validatedParams.include_keyboard_help ?? true, }; result = await enhancedHTMLGenerator.generateEnhancedThemePreviewHTML( visualizationData, enhancedOptions ); } catch (htmlError) { throw new Error( `Failed to generate enhanced HTML: ${htmlError instanceof Error ? htmlError.message : String(htmlError)}` ); } // Prepare export formats const exportFormats: Record<string, string | object> = {}; exportFormats['css'] = generateThemeCSSExport(processedThemeColors); exportFormats['scss'] = generateThemeSCSSExport(processedThemeColors); exportFormats['json'] = { theme_colors: Object.fromEntries( Object.entries(processedThemeColors).map(([name, color]) => [ name, { hex: color.hex, rgb: color.rgb, hsl: color.hsl, accessibility: color.accessibility, }, ]) ), preview_type: validatedParams.preview_type, components: validatedParams.components, metadata: visualizationData.metadata, }; const executionTime = Date.now() - startTime; // Try to save file using enhanced file output manager let visualizationResult; try { await enhancedFileOutputManager.initialize(); // If we have HTML content, save it using the enhanced file output manager if (result.htmlContent) { visualizationResult = await enhancedFileOutputManager.saveHTMLVisualization( result.htmlContent, { toolName: 'create_theme_preview_html', description: `Enhanced theme preview with ${colorCount} colors`, } ); } } catch (fileError) { // If file saving fails, we'll fall back to returning HTML content directly logger.warn('Failed to save HTML file, falling back to content', { error: fileError as Error, }); } return { success: true, data: { theme_colors: Object.fromEntries( Object.entries(processedThemeColors).map(([name, color]) => [ name, color.hex, ]) ), preview_type: validatedParams.preview_type || 'website', components: validatedParams.components || [ 'header', 'content', 'buttons', ], color_count: colorCount, accessibility_compliant: Object.values(processedThemeColors).every( color => !color.accessibility || color.accessibility.wcagAA ), file_path: result.filePath, file_name: result.fileName, file_size: result.fileSize, background_controls_enabled: result.backgroundControlsEnabled, accessibility_features: result.accessibilityFeatures, }, metadata: { execution_time: executionTime, tool: 'create_theme_preview_html', timestamp: new Date().toISOString(), color_space_used: 'sRGB', accessibility_notes: accessibilityNotes, recommendations: [ ...recommendations, 'HTML file saved with interactive background controls', 'Use Alt+T to toggle background theme', 'Use Alt+C to open color picker', ], }, visualizations: { html: result.htmlContent || `File saved: ${result.filePath}`, ...(visualizationResult?.html_file && { html_file: visualizationResult.html_file, }), }, export_formats: exportFormats, }; } catch (error) { const errorMessage = error instanceof Error ? error.message : String(error); const errorStack = error instanceof Error ? error.stack : undefined; return { success: false, error: { code: 'INTERNAL_ERROR', message: `Theme preview HTML generation error: ${errorMessage}`, details: { errorMessage, errorStack, errorType: error?.constructor?.name || 'Unknown', }, suggestions: [ 'Verify all theme colors are in valid formats', 'Check that the preview type and components are supported', 'Try with a simpler theme color set', ], }, metadata: { execution_time: Date.now() - startTime, tool: 'create_theme_preview_html', timestamp: new Date().toISOString(), }, }; } } - Joi schema defining input parameters including theme_colors, preview_type, components, and various options.
const createThemePreviewHtmlSchema = Joi.object({ theme_colors: Joi.object() .pattern(Joi.string(), Joi.string()) .required() .description('Semantic color mapping object'), preview_type: Joi.string() .valid('website', 'mobile_app', 'dashboard', 'components') .default('website') .description('Preview type'), components: Joi.array() .items( Joi.string().valid( 'header', 'sidebar', 'content', 'footer', 'buttons', 'forms', 'cards' ) ) .default(['header', 'content', 'buttons']) .description('Components to show'), interactive: Joi.boolean().default(true).description('Enable interactivity'), responsive: Joi.boolean().default(true).description('Responsive design'), theme: Joi.string() .valid('light', 'dark', 'auto') .default('light') .description('Color theme for the visualization'), enable_background_controls: Joi.boolean() .default(true) .description('Enable interactive background controls'), enable_accessibility_testing: Joi.boolean() .default(true) .description('Enable accessibility testing and warnings'), include_keyboard_help: Joi.boolean() .default(true) .description('Include keyboard shortcuts help'), }); - src/tools/create-theme-preview-html.ts:551-558 (registration)ToolHandler export that defines the tool name, description, parameters schema, and handler wrapper.
export const createThemePreviewHtmlTool: ToolHandler = { name: 'create_theme_preview_html', description: 'Generate HTML theme preview mockups showing colors in realistic UI contexts', parameters: createThemePreviewHtmlSchema.describe(), handler: async (params: unknown) => createThemePreviewHtml(params as CreateThemePreviewHtmlParams), }; - src/tools/index.ts:77-122 (registration)Central import and registration of the tool into the ToolRegistry singleton.
import { createThemePreviewHtmlTool } from './create-theme-preview-html'; // Import and register PNG generation tools import { createPalettePngTool } from './create-palette-png'; import { createGradientPngTool } from './create-gradient-png'; import { createColorComparisonPngTool } from './create-color-comparison-png'; // Import and register theme generation tools import { generateThemeTool } from './generate-theme'; import { generateSemanticColorsTool } from './generate-semantic-colors'; // Import color utility tools import { mixColorsTool } from './mix-colors'; import { generateColorVariationsTool } from './generate-color-variations'; import { sortColorsTool } from './sort-colors'; import { analyzeColorCollectionTool } from './analyze-color-collection'; // Import export format tools import { exportCssTool } from './export-css'; import { exportScssTool } from './export-scss'; import { exportTailwindTool } from './export-tailwind'; import { exportJsonTool } from './export-json'; // Register conversion tools toolRegistry.registerTool(convertColorTool); // Register analysis tools toolRegistry.registerTool(analyzeColorTool); toolRegistry.registerTool(checkContrastTool); // Register accessibility tools toolRegistry.registerTool(simulateColorblindnessTool); toolRegistry.registerTool(optimizeForAccessibilityTool); // Register palette generation tools toolRegistry.registerTool(generateHarmonyPaletteTool); // Register gradient generation tools toolRegistry.registerTool(generateLinearGradientTool); toolRegistry.registerTool(generateRadialGradientTool); // Register visualization tools toolRegistry.registerTool(createPaletteHtmlTool); toolRegistry.registerTool(createColorWheelHtmlTool); toolRegistry.registerTool(createGradientHtmlTool); toolRegistry.registerTool(createThemePreviewHtmlTool); - Helper function determining required semantic colors for different preview types (website, mobile_app, etc.).
function getRequiredColorsForPreviewType(previewType: string): string[] { const baseColors = ['background', 'text', 'primary']; switch (previewType) { case 'website': return [...baseColors, 'surface', 'secondary']; case 'mobile_app': return [...baseColors, 'surface', 'accent']; case 'dashboard': return [ ...baseColors, 'surface', 'sidebar', 'accent', 'success', 'warning', 'error', ]; case 'components': return [ ...baseColors, 'secondary', 'success', 'warning', 'error', 'info', ]; default: return baseColors; } }