Visualising Concepts

A diagram is not decoration. It earns its place only when seeing the concept spatially changes how the student understands it. When in doubt, leave it out — a cluttered detail panel is worse than none at all.

When a Diagram Helps

A diagram works well when:

• The concept has inherent geometric structure (functions, transformations, vectors, distributions)
• A visual reveals a relationship that prose would take many sentences to describe
• The student needs to build spatial intuition before working with formulas
• You want to show a step-by-step process that unfolds over time

• The concept is already clear from the text
• The diagram contains too many elements and no clear focal point
• The same information is shown in both the body and the detail panel

Body and Detail Together

Think of the scene body and the detail panel as two complementary channels. The body narrates; the diagram illustrates. They should not repeat each other.

scene{
    ## Definite Integrals as Area

    The definite integral $\int_a^b f(x)\,dx$ gives the signed area between
    the curve $y = f(x)$ and the x-axis, from $x = a$ to $x = b$.

    Area below the x-axis counts as negative.
}[
    diagram{
        curve(expression: sin(x); colour: blue)
        polygon(
            data: (0,0),(0.01,0.01),(3.14,0.01),(3.14,0)
            colour: teal
            opacity: 0.3
        )
    }(
        x domain: [-1, 5]
        y domain: [-1.5, 1.5]
        x-axis-label: x
        y-axis-label: y
    )
]

Design for Clarity

Keep diagrams simple. Each element should serve a purpose. Before you add a shape, point, or label, ask: does this help the student see what I want them to see?

Practical guidelines:

• One focal point per diagram — the student's eye should land on the most important element first
• Use colour to distinguish, not decorate — use a different colour for the element you want students to notice
• Label sparingly — a diagram with 10 labels teaches the student to ignore labels
• Restrict domains — use the domain attribute on curves to show only the relevant portion

Revealing Ideas with Animation

Animation is most useful when the concept is inherently dynamic — a limit being approached, a transformation being applied, a step in a construction being added.

Use cue to fade elements in at the moment you introduce them in the narrative. Use cue.draw to show a curve being traced. Use cue.morph to show one shape transforming into another.

scene{
    The tangent line at a point has the same slope as the curve at that point.

    Watch as the secant line through $(1, 1)$ and a moving point approaches the tangent.
}[
    diagram{
        curve(expression: x^2; colour: blue)
        point(x: 1; y: 1; colour: orange)

        cue.draw{
            segment(x1: -1; y1: 1; x2: 3; y2: 9; colour: grey; dashed: true)
        }(in: 0; in-duration: 800)

        cue.morph{
            segment(x1: -1; y1: 1; x2: 3; y2: 9; colour: grey; dashed: true)
        }[
            segment(x1: -1; y1: -1; x2: 3; y2: 3; colour: pink)
        ](at: 1000; duration: 1200)
    }(x domain: [-2, 4]; y domain: [-1, 9])
](autoplay: true)

Using Parameters for Exploration

A parameter slider lets students become active explorers rather than passive readers. They see how a variable changes a graph, not just that it changes it.

Design parametrised diagrams around a specific question: "What happens to the shape of the curve as a increases?" Give the student the question in the body text, then let them answer it by moving the slider.

scene{
    How does the period of $y = \sin(bx)$ change as $b$ increases?

    Drag the slider and watch the wave compress or stretch.
}[
    parameter{
        Frequency $b$
    }(var: b; range: [0.5, 4]; step: 0.5; default: 1)

    diagram{
        curve(expression: sin(b * x); colour: teal)
    }(x domain: [-7, 7]; y domain: [-1.5, 1.5])
]

A Diagram is Not a Textbook Figure

Textbook figures have captions, labels, legends, and comprehensive axis annotations. Your diagram in an internote works alongside prose — the body text does the explaining. The diagram can be sparser than you might expect.