Math-Driven Interactive Artifacts
Build interactive figures that show meaning, not control panels. The reader should leave understanding a physical or mathematical idea. Numbers are outputs of the model, not toys to twiddle.
Non-negotiables
- Compute, then draw. Every reactive visual must come from a real formula, transform, or simulation step.
- Purpose on every element. If removing a control, label, card, or decoration does not hurt understanding, remove it.
- Scenes over knobs. Prefer named situations such as "near field" and "at focus" over raw parameters unless the audience asked for a lab bench.
- No chat leakage. Write as the final paper or product surface.
- Match the surface. Research notes should be precise. Tutorials can be plain, but never condescending.
Workflow
1. State the teaching goal
Write one sentence: This artifact exists so the reader understands ____.
If you cannot finish that sentence, do not build controls yet.
2. Choose the minimal model
| Idea | Minimal model |
|---|---|
| Propagation depth matters | 1D Fresnel or ASM step |
| Conservation | Continuity residual on a toy grid |
| Consensus coupling | Two fields plus a penalty term |
| Optimization tradeoff | Two or three loss terms |
Implement the model as pure functions: params → field / metrics → draw.
3. Design interaction as scenes
Define three to six named scenes. Each scene needs a short title, one sentence of meaning, a complete parameter vector, and any discrete mode switches.
When a scene changes:
- Cancel the current animation.
- Apply discrete modes immediately.
- Smoothly interpolate continuous parameters.
- Recompute the model every frame.
- Snap to the exact target at the end.
Do not expose the raw parameter vector unless the user asks for expert controls.
4. Bind visuals to robust quantities
- Prefer RMS width, encircled-energy diameter, or support-above-threshold over fragile center-based FWHM.
- Find peaks with
argmax, not assumed indices. - Clamp display scales for readability without making scenes look identical.
- Light smoothing is acceptable when it removes frame flicker.
5. Compose one visual story
- Embed derived plots on the main geometry instead of adding a detached chart.
- Put secondary numeric readouts below the figure.
- Drive overlays from the same computed field as the plot.
6. Decorate with intent
Decoration is allowed when it carries information: active state, residual, axis meaning, or equation identity. Remove unrelated glow, decorative gradients, emoji, stat walls, and controls that do not change the substance.
7. Write the surrounding prose like the final artifact
- Define jargon when it first appears.
- Separate the problem class from the method contribution.
- Number important equations and keep notation consistent.
- Captions explain what the figure shows and why it exists.
Cursor Canvas constraints
When the deliverable is a .canvas.tsx:
- Import only from
cursor/canvas, plus React types or hooks when required. - Keep it in one file and embed the model inline.
- Persist scene id and parameters with
useCanvasState. - Use flat token colors and avoid gradient chrome.
- Save under
~/.cursor/projects/<workspace>/canvases/<name>.canvas.tsx.
Quality checklist
- The teaching goal is one clear sentence
- Every animation frame recomputes from the model
- Scene controls are enough to run the demo
- Raw expert knobs appear only when requested
- Drawn sizes use robust metrics
- The primary plot belongs to the main figure
- No meta or chat language appears in the UI
- Captions explain purpose