Improve animation quality in generated diagrams

Start with the four skill files named in the issue, especially apps/agent/skills/svg-diagram-skill.txt, and compare their current guidance with the reference animation patterns. Update the animation, annotation, shape-library, and composition guidance, then apply the changes to the MCP mirrors in apps/mcp/skills/. Verify the listed prompts, reduced-motion behavior, and sendPrompt() annotations against the reference.

Summary

When users ask questions like "how does a plane work?", the agent should generate animated, illustrative SVG diagrams with smooth CSS animations, physics-accurate visual cues, and interactive annotations. Current output is static or minimally animated. This issue targets closing the gap between what we generate today and production-quality animated explainers.

Reference output

The attached HTML shows the target quality bar for a "how does a plane work?" prompt:

What it does well:

• CSS keyframe animations — airflow lines animate with stroke-dashoffset at different speeds above vs below the wing (faster above = lower pressure, Bernoulli's principle visualized)
• Exhaust animation — engine thrust shown with animated dashed lines in warm colors, distinct from airflow
• Geometric construction — the airplane is built from composable primitives (ellipses for fuselage/nacelle, paths for wing airfoil shape, circles for windows) rather than a single freehand path
• Four forces arrows — lift, weight, thrust, drag shown with color-coded arrows and proper marker heads
• Annotation hierarchy — primary labels (force names) at 14px, secondary annotations (Bernoulli explanation, angle of attack) at smaller size with leader lines
• Interactive click targets — annotations are wrapped in <g class="node" onclick="sendPrompt(...)"> so clicking a label sends a follow-up question to the agent
• Accessibility — prefers-reduced-motion media query disables animations for users who need it
• Layered composition — sky background → fuselage → wing → engine → airflow → force arrows → annotations, each layer visually distinct

<style>
  @keyframes airflow { to { stroke-dashoffset: -40; } }
  @keyframes thrust { to { stroke-dashoffset: -16; } }
  .airflow { stroke-dasharray: 12 8; animation: airflow 1.2s linear infinite; }
  .airflow-fast { stroke-dasharray: 8 6; animation: airflow 0.7s linear infinite; }
  .exhaust { stroke-dasharray: 4 12; animation: thrust 0.6s linear infinite; }
  @media (prefers-reduced-motion: reduce) {
    .airflow, .airflow-fast, .exhaust { animation: none; }
  }
</style>

<svg width="100%" viewBox="0 0 680 520">
  <!-- Full reference SVG omitted for brevity — see attached file -->
  <!-- Key patterns: animated airflow lines, geometric airplane construction,
       four forces arrows, clickable annotation groups, Bernoulli callouts -->
</svg>

Current gaps

Proposed changes

1. Add animation skill/rules to svg-diagram-skill.txt

Expand the illustrative diagram section with animation guidance:

• When to animate: moving fluids (air, water, fuel), force transmission, energy flow, rotational motion
• Animation patterns: stroke-dashoffset for flow lines, transform: rotate() for spinning parts, opacity pulses for energy transfer
• Speed as information: faster animation = higher velocity/lower pressure (encode physics in timing)
• Color coding: warm colors (orange/red) for heat/thrust/resistance, cool colors (blue) for airflow/cooling, green for lift/positive forces
• Always include @media (prefers-reduced-motion: reduce) to disable animations

2. Add clickable annotation pattern

Teach the agent to wrap annotations in interactive groups:

<g class="node" onclick="sendPrompt('Explain X in more detail')">
  <line class="leader" x1="..." y1="..." x2="..." y2="..."/>
  <text class="ts" x="..." y="...">Annotation text</text>
</g>

This turns static diagrams into conversational entry points — users click to drill deeper.

3. Add animation examples to shape library

Add reusable animation patterns to svg-shape-library.txt:

• Fluid flow: dashed path with stroke-dashoffset animation (configurable speed/direction)
• Exhaust/emission: multi-line fan pattern with warm colors and fast animation
• Rotation: transform-origin + rotate keyframes for gears, turbines, wheels
• Pulse: opacity keyframe for highlighting active components

4. Update mechanical illustration skill

Add an "Animation layer" step to the composition planning in mechanical-illustration-skill.txt:

• After spatial layout, identify which elements should animate and why
• Map animation speed to physical quantity (airflow speed, RPM, pressure)
• Define animation classes upfront in a <style> block before the SVG

Verification

Test with these prompts and compare animated output to the reference:

• "how does a plane work?"
• "how do cars work?"
• "explain how a jet engine works"
• "how does a wind turbine generate electricity?"
• Verify prefers-reduced-motion disables all animations
• Verify clickable annotations call sendPrompt() correctly

Key files

• apps/agent/skills/svg-diagram-skill.txt — animation rules go here
• apps/agent/skills/mechanical-illustration-skill.txt — composition planning update
• apps/agent/skills/svg-shape-library.txt — reusable animation patterns
• apps/mcp/skills/ — MCP mirrors of all skill files