Beyond Static Diagrams: Building Correctness-First Generative UI for Learning

How we combine verified components, declarative visual specifications, and sandboxed model-generated UI—without giving the model authority over mathematical truth.

A child struggling with a math problem often does not need another paragraph. They need to see the relationship: objects being counted, fractions becoming equal-sized pieces, quantities moving along a number line, or one part of a whole being shared again.

The best visual is specific to the exact problem. But delivering that specificity creates a fundamental product tension. Explore Math Magic to see this in action.

Static diagrams are reliable, but they cannot cover every combination of numbers, operations, and stories. Model-generated diagrams can adapt to almost anything, but they can also present incorrect mathematics with complete visual confidence.

For a children’s learning product, that is not an acceptable trade.

We chose a different approach: use deterministic, verified visuals for the problem patterns we understand, and introduce model-generated UI only where its flexibility is necessary.

The result is a correctness-first visual system that moves from authored components to declarative teaching specifications to sandboxed generation—while keeping grading and mathematical truth outside the model.

Start with authority, not generation

Much of today’s generative-UI work starts with the model:

What interface can the model create?

We started with a different question:

How much authority does the model need to help this child—and what authority should it never receive?

That led us to treat visual UI as a spectrum.

Moving right increases flexibility. Moving left increases predictability, speed, and control.

The spectrum has four levels:

• Static: fixed artwork or layouts.

• Parameterized: engineer-authored components whose values and state change with the problem.

• Declarative: typed specifications select and configure components from a verified visual vocabulary.

• Generative: a model creates new HTML or SVG when our existing vocabulary cannot represent the problem.

Each step adds expressive power. It also gives the system more freedom—and therefore introduces more uncertainty.

Our governing principle is:

Use the least powerful UI tier capable of correctly teaching the current concept.

This is where our approach differs from the typical generative-UI demo. We are not using generation to replace the product interface. We are building an adaptive model of UI authority: the system escalates from verified structure to model-authored structure only when the learning situation requires it.

A correctness-first cascade

When a child asks for visual help, the on-demand experience follows a cascade.

The system first looks for a known learning representation. If one exists, structured problem data configures a verified component and renders it immediately.

If no suitable component exists, a deterministic router can produce a typed visual descriptor. That descriptor selects from a known vocabulary of number lines, fraction models, grouping visuals, place-value tools, and other manipulatives.

Only when the router cannot find an appropriate representation does the system escalate to model-generated UI.

Deterministic UI handles the common path. Model-drawn UI expands coverage for the long tail inside defined containment boundaries.

This ordering gives us three advantages:

• Correctness: common problems use teaching structures we can inspect and test.

• Experience quality: deterministic visuals render immediately and behave consistently.

• Coverage: generation gives us a path for novel questions our component library does not yet support.

The model expands the system’s reach. It does not become the default rendering engine.

The visual system in practice

The architecture becomes clearer through real examples.

At the common end of the spectrum, a parameterized manipulative lets a child act directly on visible objects. Declarative fraction models assemble verified teaching structures from problem data. For a contextual word problem, the system can create a tailored visual sequence that connects the story to the underlying mathematics.

The rendering method changes, but the governing principle remains constant: the visual guides the reasoning while deterministic systems retain authority over the answer.

1. Turn a static counting question into an action

Parameterized manipulative: the component owns the interaction, problem data supplies the objects, and the coach grounds each hint in what the child can tap on screen.

A basic counting question could be rendered as four cookies and an input box. Instead, the visual turns counting into an observable action.

The child taps each cookie once. The component tracks the count, while the answer remains for the child to provide.

The coach’s three hints progress deliberately:

1. Establish the meaning of counting: give each object one number in order.

2. Offer another strategy: organize the objects into smaller groups.

3. Connect directly to the visual: tap each visible cookie once and say the count aloud.

The component, interaction state, and coach language all refer to the same four visible objects.

This is more than parameter substitution. The authored component defines a testable teaching interaction, while the current problem supplies the objects and values.

2. Make different denominators visible

Declarative teaching UI: structured fraction data selects a verified bar model, preserves the unknowns, and gives the coach a shared visual language for guiding the next step.

Adding 1/4 + 2/5 is difficult because children often focus on the written numbers without understanding why the pieces must first become the same size.

The visual renders two bars:

• One divided into fourths.

• One divided into fifths.

• Both waiting to be repartitioned into a common unit.

The unknown multipliers remain marked with ?. The visual exposes the relationship without completing it.

The coach can now guide the child through what is actually on screen:

• Notice that the bars contain different-sized pieces.

• Imagine cutting both bars into the same number of smaller pieces.

• Use the visible ?/? prompts to determine which partition fits both bars.

The visual does not merely decorate the equation. It becomes the shared reasoning surface between the child and the coach.

3. Show equivalent fractions as a transformation

Equivalent fractions become a visual transformation: the child maps fourths into smaller equal pieces while the coach grounds each hint in the two visible representations.

Equivalent fractions are often introduced as a rule: multiply the numerator and denominator by the same number.

That rule is correct, but it can hide the underlying meaning.

Here, the child starts with five fourths and constructs the same quantity using sixteenths. The missing numerator remains unknown. The child selects slices in the second representation to make the two quantities match.

The coach’s hints move from comparison to transformation:

• Compare the shaded quantity in the two representations.

• Consider how each fourth divides into smaller pieces.

• Count how many sixteenth-sized pieces correspond to one shaded fourth.

The child does not simply apply a memorized procedure. The interface makes equivalence visible as a change in partition size while the total quantity remains constant.

This is what we mean by a declarative teaching vocabulary. The specification does not merely say “render two circles.” It expresses a mathematical relationship the component and coach can share.

See guided visual learning in action

Explore how Math Magic turns abstract problems into interactive, guided experiences for kids—from number lines and fraction models to contextual visual aids.

Explore Math Magic

4. Adapt the representation to the story

Contextual visual generation: a multi-step word problem becomes a problem-specific bar model while deterministic grading retains authority over the answer.

Now consider a less standard problem:

Lila has 3/5 of a chocolate bar and shares 2/3 of her portion. How much of the whole bar does her friend receive?

This requires the child to reason about a fraction of another fraction. A generic fraction circle does not capture the sequence particularly well.

The contextual visual creates three stages:

1. The whole chocolate bar divided into five equal parts.

2. Lila’s three-fifths identified within the whole.

3. Two-thirds of Lila’s portion selected for her friend.

The representation preserves the story instead of immediately translating it into abstract arithmetic. The child can see that the second fraction operates on Lila’s portion—not on the entire bar.

This is where flexible visual composition becomes valuable. The system can adapt the representation to a multi-step context without allowing that representation to define or grade the correct answer.

Interactive components become manipulatives

These examples are not simply pictures with different numbers. They are manipulatives the child can operate: tapping, grouping, partitioning, selecting, and comparing.

Because engineers own the structure and interaction of verified components, we can test more than whether they render. We can test whether they:

• Use only values visible in the problem.

• Preserve the intended mathematical relationship.

• Hide the answer at the appropriate moment.

• Support the teaching strategy for that concept.

• Respond correctly to the child’s actions.

• Give the coach a valid surface to reference.

There is an important nuance: deterministic does not automatically mean pedagogically safe.

A deterministic comparison component could still reveal <, >, or = before the child has reasoned through the relationship. Answer safety must therefore be verified at the component and interaction level. It is not automatically inherited from the rendering technology.

Declarative UI becomes a teaching vocabulary

Above the components sits a typed declarative layer.

Instead of requesting arbitrary markup, the system can describe a known teaching structure:

• Show a fraction area model.

• Divide the whole into equal parts.

• Shade only the values visible in the problem.

• Keep the result unknown.

• Ask the child to compare or transform the regions.

A rendering engine maps that description onto a verified component.

This creates something more valuable than a UI library. It creates a visual teaching vocabulary.

The system can express concepts such as:

• Show equal groups.

• Make repeated jumps on a number line.

• Compare quantities without revealing the answer.

• Repartition two fractions into equal-sized units.

• Expose one step while keeping the next step unknown.

• Represent the same relationship in a different way.

Today, deterministic code produces these descriptors. That is deliberate. We receive the composability of declarative UI without introducing model variability into the common rendering path.

The router’s most valuable behavior is also its simplest: it can decline.

A multiplication-oriented fraction visual should not be shown for fraction addition merely because both questions are tagged as fractions.

Refusing to draw is better than presenting a confident visual with the wrong mathematical meaning.

Generative UI handles the long tail

No practical component library will anticipate every word problem, context, misconception, or useful representation.

For those cases, the system can ask a model to create a self-contained visual using HTML, CSS, and SVG.

This tier gives the product valuable flexibility:

• A novel story problem can receive a context-specific diagram.

• An uncommon misconception can receive a different representation.

• Visual coverage can expand without waiting for every component to be designed and shipped.

But model-generated UI remains probabilistic.

A schema can constrain the output shape. Instructions can tell the model to guide rather than solve and mark unknown values with ?. Neither proves that every generated diagram contains correct mathematics.

We therefore use generation to improve coverage—not to establish truth.

Containment is not the same as correctness

Allowing a model to create a visual introduces three separate questions:

1. Is the underlying mathematical answer still authoritative?

2. Does the picture accurately represent the problem?

3. Can the generated output affect the rest of the product?

These are different trust boundaries. Preventing generated content from changing the application does not prove that the picture teaches the right math.

Mathematical truth stays deterministic

The model does not define the correct answer or grade the child. Those decisions remain grounded in structured problem data and deterministic grading.

A generated visual may help explain the relationship, but it cannot change what the product considers correct.

This is an enforced boundary today.

The visual must match the math

This is the most important boundary for a learning product.

A diagram can be visually polished and still be wrong: a fraction bar can use the wrong number of parts, a number line can place values at incorrect distances, or a label can introduce a number that does not appear in the problem.

Our deterministic visuals provide the strongest protection because their geometry is derived from structured problem values. The same operands that create the question determine the partitions, labels, quantities, and interactions in the visual.

Raw generated visuals work differently today. The model receives the question and is instructed to:

• Use the values from the problem.

• Preserve their mathematical proportions.

• Keep the unknown hidden.

• Guide the child without revealing the answer.

• Check labels and relationships before returning the visual.

We also inspect generated visuals through repeated QA. These controls reduce risk, but they do not prove factual correctness. The current system does not deterministically verify that every generated shape, proportion, or label matches the canonical problem before the child sees it.

That is the most important gap in the generative path.

From prompt compliance to verifiable visuals

The next architectural step is to require the model to propose a typed visual specification before anything is rendered.

Instead of returning only a finished picture, the model would describe its mathematical intent in structured form:

• Which visual representation it selected.

• Which operands it used.

• Which relationship it is showing.

• How the whole is partitioned.

• Which quantities are visible.

• Which value must remain unknown.

The system can then validate that specification against the canonical problem:

• The operands match the structured question data.

• The operation and relationship are correct.

• Partitions and proportions represent the actual values.

• Every visible number is permitted by the problem.

• The unknown remains marked with ?.

• The correct answer is not exposed prematurely.

Only a specification that passes those checks should be rendered for the child. If validation fails, the system should fall back to a verified component or a grounded text hint.

This changes the role of the model in an important way:

The model proposes how to explain the math. Deterministic systems verify that the explanation matches the math.

Generated visuals cannot alter the product

The third boundary is product isolation.

Model-generated output is treated as display content, not application logic. It cannot change the question, correct answer, grading result, student progress, or surrounding experience.

The implementation uses sanitization and browser isolation to enforce this boundary, but the product principle is simpler:

The model can propose what the child sees; it cannot change how the product behaves.

This protects the application from generated output. It does not establish the pedagogical accuracy of the visual—that requires the separate validation boundary described above.

The trust model

The resulting division of responsibility is:

• Deterministic systems own mathematical truth and grading.

• Verified components own common teaching interactions.

• Models propose representations for unfamiliar situations.

• Structured validation confirms that proposed visuals match the problem.

• Product isolation prevents generated content from affecting application behavior.

• QA measures whether the complete experience remains understandable and answer-safe.

The goal is not unrestricted generative UI. It is verifiable generative UI: enough flexibility to personalize the explanation, with deterministic checks protecting the mathematical relationship a child is asked to learn.

For a learning product, preventing generated UI from running code is necessary. Proving that it represents the right math is the more important design challenge.