Improve animation quality in generated diagrams

[GeneralJerel]

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

Reference HTML source

<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

Area	Current state	Target (reference)
Animation	None or minimal	CSS keyframe animations for airflow, exhaust, moving parts
Airflow visualization	Static or absent	Animated dashed lines at different speeds above/below wing
Object construction	Single freehand <path>	Composed from geometric primitives (ellipses, circles, arcs)
Interactivity	Passive labels	Clickable annotations that send follow-up prompts via sendPrompt()
Accessibility	No motion consideration	prefers-reduced-motion media query
Visual layering	Flat, overlapping elements	Explicit depth order: background → structure → overlays → labels
Physics accuracy	Force arrows only	Bernoulli principle visualized through animation speed differences

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