MCP UI/UX Prompt Refiner

Instructions

Implementation Reference

• src/tools/animations.ts:279-465 (handler)

  The primary handler function for the 'compose_animations' tool. It takes AnimationCompositionInput and returns a detailed Markdown string specifying animations, philosophy, recommendations for entry/hover/scroll effects, section choreography, CSS variables, keyframes, performance tips, and accessibility guidelines. Uses helper functions to select and generate content based on intensity.

  export function composeAnimations(input: AnimationCompositionInput): string {
    const { interfaceType, intensity, sections, customRequirements } = input;
    const multiplier = getIntensityMultiplier(intensity);
    
    const entryAnims = selectEntryAnimations(intensity);
    const hoverAnims = selectHoverAnimations(intensity);
    const scrollAnims = selectScrollAnimations(intensity);
    const sectionSpecs = generateSectionAnimations(interfaceType, intensity);
  
    return `# Animation Specification
  
  ## Overview
  **Interface Type**: ${interfaceType.replace(/-/g, ' ').replace(/\b\w/g, c => c.toUpperCase())}
  **Animation Intensity**: ${intensity.toUpperCase()}
  **Complexity Level**: ${multiplier.complexity}/4
  
  ${customRequirements ? `**Custom Requirements**: ${customRequirements}` : ''}
  
  ---
  
  ## Animation Philosophy
  
  For ${intensity} intensity, animations should feel:
  ${intensity === 'subtle' ? '- Barely noticeable but present\n- Quick and efficient\n- Professional and understated' : ''}
  ${intensity === 'moderate' ? '- Noticeable but not distracting\n- Purposeful and meaningful\n- Enhancing without overwhelming' : ''}
  ${intensity === 'dramatic' ? '- Eye-catching and impressive\n- Bold and expressive\n- Statement-making' : ''}
  ${intensity === 'cinematic' ? '- Theatrical and immersive\n- Story-telling through motion\n- Memorable and unique' : ''}
  
  ---
  
  ## Entry Animations
  
  ### Recommended Types
  ${entryAnims.map(name => {
    const anim = ENTRY_ANIMATIONS[name as keyof typeof ENTRY_ANIMATIONS];
    return `
  #### ${anim.name}
  - **Initial State**: \`${anim.initial}\`
  - **Final State**: \`${anim.final}\`
  - **Duration**: ${anim.duration}
  - **Easing**: ${anim.easing}
  - **Stagger**: ${anim.stagger}
  - **Description**: ${anim.description}
  `;
  }).join('')}
  
  ---
  
  ## Scroll Animations
  
  ### Active Effects
  ${scrollAnims.map(name => {
    const anim = SCROLL_ANIMATIONS[name as keyof typeof SCROLL_ANIMATIONS];
    return `
  #### ${anim.name}
  - **Description**: ${anim.description}
  - **Use Case**: ${anim.useCase}
  `;
  }).join('')}
  
  ### Implementation Notes
  - Use Intersection Observer for scroll-triggered animations
  - Trigger animations when element is 20-30% in viewport
  - Consider scroll velocity for parallax effects
  - Debounce scroll handlers for performance
  
  ---
  
  ## Hover & Interaction Effects
  
  ### Active Effects
  ${hoverAnims.map(name => {
    const anim = HOVER_ANIMATIONS[name as keyof typeof HOVER_ANIMATIONS];
    return `
  #### ${anim.name}
  - **Effect**: \`${anim.effect}\`
  - **Duration**: ${anim.duration}
  - **Description**: ${anim.description}
  - **Use Case**: ${anim.useCase}
  `;
  }).join('')}
  
  ---
  
  ## Loading States
  
  ### Recommended Loaders
  ${Object.entries(LOADING_ANIMATIONS).slice(0, 4).map(([key, anim]) => `
  #### ${anim.name}
  - **Effect**: ${anim.effect}
  - **Implementation**: ${anim.implementation}
  - **Use Case**: ${anim.useCase}
  `).join('')}
  
  ---
  
  ## Section-by-Section Choreography
  
  ${sectionSpecs.map(spec => `
  ### ${spec.element}
  - **Trigger**: ${spec.trigger}
  - **Animation**: ${spec.type}
  - **Duration**: ${spec.duration}
  - **Delay**: ${spec.delay}
  - **Purpose**: ${spec.description}
  `).join('')}
  
  ---
  
  ## Transition Choreography
  
  ### Staggered Reveals
  ${TRANSITION_CHOREOGRAPHY.staggeredFade.description}
  - Timing: ${TRANSITION_CHOREOGRAPHY.staggeredFade.timing}
  - Direction: ${TRANSITION_CHOREOGRAPHY.staggeredFade.direction}
  
  ### Page/View Transitions
  ${TRANSITION_CHOREOGRAPHY.exitThenEnter.description}
  - Timing: ${TRANSITION_CHOREOGRAPHY.exitThenEnter.timing}
  - Direction: ${TRANSITION_CHOREOGRAPHY.exitThenEnter.direction}
  
  ---
  
  ## Easing Reference
  
  ${Object.entries(EASING_FUNCTIONS).map(([key, easing]) => `
  ### ${easing.name}
  - **CSS**: \`${easing.css}\`
  - **Feel**: ${easing.description}
  - **Use For**: ${easing.useCase}
  `).join('')}
  
  ---
  
  ${generateCSSVariables(intensity)}
  
  ${generateKeyframeExamples(intensity)}
  
  ---
  
  ## Performance Guidelines
  
  ### GPU-Accelerated Properties
  Only animate these for 60fps performance:
  - \`transform\` (translate, scale, rotate)
  - \`opacity\`
  - \`filter\` (blur, brightness)
  
  ### Avoid Animating
  - \`width\`, \`height\` (use transform: scale instead)
  - \`top\`, \`left\`, \`right\`, \`bottom\` (use transform: translate)
  - \`margin\`, \`padding\` (causes layout recalculation)
  - \`border-width\` (use box-shadow or pseudo-elements)
  
  ### Optimization Tips
  1. Use \`will-change\` sparingly for complex animations
  2. Use \`transform: translateZ(0)\` to force GPU layer
  3. Debounce scroll-based animations
  4. Use Intersection Observer, not scroll events
  5. Prefer CSS animations over JavaScript when possible
  
  ---
  
  ## Accessibility: Reduced Motion
  
  Always provide reduced motion alternatives:
  
  \`\`\`css
  @media (prefers-reduced-motion: reduce) {
    /* Replace motion with instant/fade transitions */
    .animated-element {
      animation: none;
      transition: opacity 0.2s ease;
    }
    
    /* Disable parallax and scroll-jacking */
    .parallax {
      transform: none !important;
    }
  }
  \`\`\`
  
  ---
  
  *These animation specifications are designed to create a cohesive, polished feel that elevates the interface beyond typical AI-generated designs.*
  `;
  }

• src/server.ts:71-81 (schema)

  Zod validation schema (ComposeAnimationsSchema) used for parsing tool arguments in the server dispatch handler.

  const ComposeAnimationsSchema = z.object({
    interfaceType: z.enum([
      'website-landing', 'website-saas', 'website-portfolio', 'website-ecommerce',
      'dashboard', 'mobile-app', 'desktop-app', 'cli-terminal', 'presentation',
      'admin-panel', 'social-platform', 'custom'
    ]).describe('Type of interface'),
    intensity: z.enum(['subtle', 'moderate', 'dramatic', 'cinematic'])
      .describe('Animation intensity level'),
    sections: z.array(z.string()).optional().describe('Specific sections to animate'),
    customRequirements: z.string().optional().describe('Additional animation requirements'),
  });

• src/tools/animations.ts:4-9 (schema)

  TypeScript interface definition for AnimationCompositionInput, defining the expected input structure for the handler function.

  interface AnimationCompositionInput {
    interfaceType: InterfaceType;
    intensity: AnimationIntensity;
    sections?: string[];
    customRequirements?: string;
  }

• src/server.ts:168-193 (registration)

  Tool registration in the ListToolsRequestSchema handler, defining the name 'compose_animations', description, and inputSchema for MCP tool listing.

  {
    name: 'compose_animations',
    description: 'Generate detailed animation specifications including entry animations, scroll effects, hover states, loading animations, and transition choreography with CSS code examples.',
    inputSchema: {
      type: 'object',
      properties: {
        interfaceType: {
          type: 'string',
          enum: ['website-landing', 'website-saas', 'website-portfolio', 'website-ecommerce', 'dashboard', 'mobile-app', 'desktop-app', 'cli-terminal', 'presentation', 'admin-panel', 'social-platform', 'custom'],
          description: 'Type of interface'
        },
        intensity: {
          type: 'string',
          enum: ['subtle', 'moderate', 'dramatic', 'cinematic'],
          description: 'Animation intensity level'
        },
        sections: {
          type: 'array',
          items: { type: 'string' },
          description: 'Specific sections to animate'
        },
        customRequirements: { type: 'string', description: 'Additional animation requirements' }
      },
      required: ['interfaceType', 'intensity']
    }
  },

• src/server.ts:286-295 (registration)

  Dispatch logic in the CallToolRequestSchema handler's switch statement, where tool calls to 'compose_animations' are parsed with the schema and delegated to the composeAnimations function.

  case 'compose_animations': {
    const parsed = ComposeAnimationsSchema.parse(args);
    const result = composeAnimations({
      interfaceType: parsed.interfaceType as InterfaceType,
      intensity: parsed.intensity as AnimationIntensity,
      sections: parsed.sections,
      customRequirements: parsed.customRequirements,
    });
    return { content: [{ type: 'text', text: result }] };
  }