suggest_css_solution

Generate CSS-only solutions for UI tasks using modern CSS features, logical properties, and light-dark theming without JavaScript.

Instructions

CSS-ONLY solution engine with strict enforcement of modern CSS features. Provides zero-JavaScript solutions using cutting-edge CSS (2021-2025) with logical properties, modern carousels, and light-dark() theming.

Input Schema

TableJSON Schema

Name	Required	Description
`task_description`	Yes	Description of the UI task or problem to solve
`preferred_approach`	No	Preferred CSS approach - modern (latest features), compatible (wide browser support), or progressive (with fallbacks)
`target_browsers`	No	Target browsers/versions (e.g., ["Chrome 90+", "Firefox 88+", "Safari 14+"])
`project_context`	No	Project context (framework, existing CSS patterns, constraints)
`include_analysis`	No	Include semantic analysis details in response

Implementation Reference

src/index.ts:79-162 (handler)

Primary execution logic for the suggest_css_solution tool. Processes input parameters, performs semantic analysis, searches MDN for CSS properties, adds consent prompts, and returns structured JSON response.

async (args: {
  task_description: string;
  preferred_approach?: "modern" | "compatible" | "progressive";
  target_browsers?: string[];
  project_context?: string;
  include_analysis?: boolean;
}) => {
  try {
    const {
      task_description,
      preferred_approach = "modern",
      project_context,
      include_analysis = false,
    } = args;

    // Enhanced semantic analysis and intelligent search
    const suggestions: CSSPropertySuggestion[] =
      await searchMDNForCSSProperties(
        task_description,
        preferred_approach,
        project_context
      );

    // Get analysis details if requested
    let analysisDetails = null;
    if (include_analysis) {
      const { analyzeTaskIntent } = await import("./services/mdnApi.js");
      analysisDetails = analyzeTaskIntent(task_description, project_context);
    }

    const result =
      suggestions.length === 0
        ? {
            success: false,
            message:
              "No CSS-ONLY solutions found. This tool provides ONLY CSS solutions - no JavaScript alternatives will be suggested. Please rephrase your request to focus on CSS-achievable UI patterns.",
            suggestions: [],
            ...(analysisDetails && { analysis: analysisDetails }),
          }
        : {
            success: true,
            message: `Found ${suggestions.length} CSS-ONLY solution(s) using modern CSS features. All solutions are JavaScript-free and use logical properties by default.`,
            suggestions: suggestions.map((suggestion) => ({
              ...suggestion,
              needs_consent: true,
              consent_message: `Do you want to use the CSS property "${suggestion.property}" which has ${suggestion.browser_support.overall_support}% browser support?`,
            })),
            ...(analysisDetails && {
              analysis: {
                ...analysisDetails,
                explanation: `Analyzed with ${Math.round(
                  analysisDetails.confidence * 100
                )}% confidence. Detected intent: ${analysisDetails.intent.join(
                  ", "
                )}.`,
              },
            }),
          };

    return {
      content: [
        {
          type: "text" as const,
          text: JSON.stringify(result, null, 2),
        },
      ],
    };
  } catch (error) {
    return {
      content: [
        {
          type: "text" as const,
          text: JSON.stringify(
            {
              error: error instanceof Error ? error.message : "Unknown error",
            },
            null,
            2
          ),
        },
      ],
    };
  }
}

src/index.ts:49-163 (registration)

Registration of the 'suggest_css_solution' tool on the MCP server, including name, description, input schema, and inline handler function.

server.tool(
  "suggest_css_solution",
  "CSS-ONLY solution engine with strict enforcement of modern CSS features. Provides zero-JavaScript solutions using cutting-edge CSS (2021-2025) with logical properties, modern carousels, and light-dark() theming.",
  {
    task_description: z
      .string()
      .describe("Description of the UI task or problem to solve"),
    preferred_approach: z
      .enum(["modern", "compatible", "progressive"])
      .optional()
      .describe(
        "Preferred CSS approach - modern (latest features), compatible (wide browser support), or progressive (with fallbacks)"
      ),
    target_browsers: z
      .array(z.string())
      .optional()
      .describe(
        'Target browsers/versions (e.g., ["Chrome 90+", "Firefox 88+", "Safari 14+"])'
      ),
    project_context: z
      .string()
      .optional()
      .describe(
        "Project context (framework, existing CSS patterns, constraints)"
      ),
    include_analysis: z
      .boolean()
      .optional()
      .describe("Include semantic analysis details in response"),
  },
  async (args: {
    task_description: string;
    preferred_approach?: "modern" | "compatible" | "progressive";
    target_browsers?: string[];
    project_context?: string;
    include_analysis?: boolean;
  }) => {
    try {
      const {
        task_description,
        preferred_approach = "modern",
        project_context,
        include_analysis = false,
      } = args;

      // Enhanced semantic analysis and intelligent search
      const suggestions: CSSPropertySuggestion[] =
        await searchMDNForCSSProperties(
          task_description,
          preferred_approach,
          project_context
        );

      // Get analysis details if requested
      let analysisDetails = null;
      if (include_analysis) {
        const { analyzeTaskIntent } = await import("./services/mdnApi.js");
        analysisDetails = analyzeTaskIntent(task_description, project_context);
      }

      const result =
        suggestions.length === 0
          ? {
              success: false,
              message:
                "No CSS-ONLY solutions found. This tool provides ONLY CSS solutions - no JavaScript alternatives will be suggested. Please rephrase your request to focus on CSS-achievable UI patterns.",
              suggestions: [],
              ...(analysisDetails && { analysis: analysisDetails }),
            }
          : {
              success: true,
              message: `Found ${suggestions.length} CSS-ONLY solution(s) using modern CSS features. All solutions are JavaScript-free and use logical properties by default.`,
              suggestions: suggestions.map((suggestion) => ({
                ...suggestion,
                needs_consent: true,
                consent_message: `Do you want to use the CSS property "${suggestion.property}" which has ${suggestion.browser_support.overall_support}% browser support?`,
              })),
              ...(analysisDetails && {
                analysis: {
                  ...analysisDetails,
                  explanation: `Analyzed with ${Math.round(
                    analysisDetails.confidence * 100
                  )}% confidence. Detected intent: ${analysisDetails.intent.join(
                    ", "
                  )}.`,
                },
              }),
            };

      return {
        content: [
          {
            type: "text" as const,
            text: JSON.stringify(result, null, 2),
          },
        ],
      };
    } catch (error) {
      return {
        content: [
          {
            type: "text" as const,
            text: JSON.stringify(
              {
                error: error instanceof Error ? error.message : "Unknown error",
              },
              null,
              2
            ),
          },
        ],
      };
    }
  }
);

src/index.ts:52-78 (schema)

Zod input schema defining parameters for the tool: task_description, preferred_approach, target_browsers, project_context, include_analysis.

{
  task_description: z
    .string()
    .describe("Description of the UI task or problem to solve"),
  preferred_approach: z
    .enum(["modern", "compatible", "progressive"])
    .optional()
    .describe(
      "Preferred CSS approach - modern (latest features), compatible (wide browser support), or progressive (with fallbacks)"
    ),
  target_browsers: z
    .array(z.string())
    .optional()
    .describe(
      'Target browsers/versions (e.g., ["Chrome 90+", "Firefox 88+", "Safari 14+"])'
    ),
  project_context: z
    .string()
    .optional()
    .describe(
      "Project context (framework, existing CSS patterns, constraints)"
    ),
  include_analysis: z
    .boolean()
    .optional()
    .describe("Include semantic analysis details in response"),
},

src/services/css/suggestions.ts:289-302 (helper)

Core helper function called by the handler to perform semantic analysis and search for relevant CSS properties based on task description.

export async function searchMDNForCSSProperties(
  description: string | string[],
  approach: 'modern' | 'compatible' | 'progressive' = 'modern',
  projectContext?: any
): Promise<CSSPropertySuggestion[]> {
  // Handle backward compatibility with keyword array
  if (Array.isArray(description)) {
    return searchLegacyKeywords(description, approach);
  }

  // New semantic analysis approach
  const analysis = analyzeTaskIntent(description, projectContext);
  return searchWithIntelligentRanking(analysis, approach, projectContext);
}

src/services/css/suggestions.ts:79-159 (helper)

Helper function for semantic analysis of task intent, keyword extraction, framework detection, and category suggestion. Used optionally in handler and by searchMDNForCSSProperties.

export function analyzeTaskIntent(description: string, projectContext?: any): {
  keywords: string[];
  intent: string[];
  confidence: number;
  suggestedCategories: CSSFeatureCategory[];
  frameworkHints: string[];
  contextAnalysis?: any;
  recommendations?: string[];
} {
  const keywords: string[] = [];
  const intent: string[] = [];
  const suggestedCategories: CSSFeatureCategory[] = [];
  const frameworkHints: string[] = [];
  let totalMatches = 0;
  let totalPatterns = 0;

  // Analyze project context
  const contextAnalysis = analyzeProjectContext(projectContext);

  // Analyze intent patterns
  for (const [intentType, config] of Object.entries(INTENT_PATTERNS)) {
    let intentMatches = 0;
    for (const pattern of config.patterns) {
      totalPatterns++;
      if (pattern.test(description)) {
        intentMatches++;
        totalMatches++;
      }
    }
    
    if (intentMatches > 0) {
      intent.push(intentType);
      suggestedCategories.push(...config.categories);
    }
  }

  // Extract framework hints from project context and description
  if (contextAnalysis.framework) {
    frameworkHints.push(contextAnalysis.framework);
  }
  if (contextAnalysis.cssFramework) {
    frameworkHints.push(contextAnalysis.cssFramework);
  }

  // Additional framework detection from description
  for (const [framework, indicators] of Object.entries(FRAMEWORK_INDICATORS)) {
    if (indicators.some(indicator => 
      description.toLowerCase().includes(indicator)
    )) {
      frameworkHints.push(framework);
    }
  }

  // Legacy keyword extraction for backward compatibility
  keywords.push(...extractLegacyKeywords(description));

  const confidence = totalPatterns > 0 ? totalMatches / totalPatterns : 0;

  // Generate context-aware recommendations
  const recommendations: string[] = [];
  if (contextAnalysis.framework) {
    recommendations.push(...getFrameworkSpecificRecommendations(contextAnalysis.framework));
  }
  if (contextAnalysis.cssFramework) {
    recommendations.push(...getCSSFrameworkRecommendations(contextAnalysis.cssFramework));
  }
  
  // Add logical units recommendations
  const writingModeRecommendations = getWritingModeRecommendations(projectContext);
  recommendations.push(...writingModeRecommendations);

  return {
    keywords: [...new Set(keywords)],
    intent: [...new Set(intent)],
    confidence,
    suggestedCategories: [...new Set(suggestedCategories)],
    frameworkHints: [...new Set(frameworkHints)],
    contextAnalysis,
    recommendations: recommendations.length > 0 ? recommendations : undefined
  };
}

@depthark/css-first