What should a figure represent?
A number line includes points, intervals and marks, potentially indicating zero or an undefined location. An image alone requires fresh interpretation to address these parts. Structured description defines the relevant elements and relationships instead of leaving them to unrestricted inference.
We do not attempt to represent every possible drawing in an open format. The starting families have defined educational meanings, such as number lines and annotated equations. Type boundaries contribute to correctness: an unsupported figure should not be guessed into a trustworthy-looking drawing.
Structure does not replace Arabic explanation
The system needs element structure; the learner and tutor need an account of the idea. Arabic description therefore remains independently necessary. Coordinates do not explain why the book focuses on an interval and cannot replace a description for someone who cannot see the figure.
Figures refer to lesson formulas rather than rewriting them. A duplicated equation can change independently, leaving the figure and text inconsistent without an obvious error. A shared reference makes this relationship inspectable and reduces drift.
Validate before drawing
A valid JSON shape is not necessarily a valid diagram. Two points may share an identity, or an annotation may refer to a nonexistent element. The contract needs relationship and semantic checks in addition to data-shape validation.
We can check that a formula reference belongs to the same lesson and that a selected element is unambiguous. This does not guarantee every educational interpretation; it prevents structural mistakes from appearing valid merely because a browser rendered them.
Pointing is different from rewriting
Warda separates the original description from explanatory emphasis. A design can identify and highlight an element without modifying its stored specification. Changing a mark or adding an element has another responsibility and should not be hidden inside a highlighting operation.
Visual provenance remains a review reference. Successful generation of a structured figure does not establish correspondence with the book. Review compares the rendering with the original and attends to differences carrying mathematical meaning.
Element identity is part of explanation quality
When the same symbol appears several times, pointing to “this exponent” needs an unambiguous occurrence. Text matching can select part of a longer number or multiple positions. Element identity and reference therefore belong in the contract instead of relying on letter similarity in an image.
Arabic text direction also does not automatically mirror every diagram. A number line retains its printed point order; equation panels follow their educational arrangement. Direction rules belong to the figure type, rather than a blanket reversal. This prevents an apparently helpful RTL adjustment from reversing a mathematical relationship the learner needs to read as printed.
What makes this educational content?
Zoom and colour help visibility, but the contract offers more: elements have names and relationships, references have origins, and explanation has a precise target. The figure becomes more than decoration beside prose.
This account describes a bounded structured-figure design, not a promise to generate any diagram or edit any exercise live. Understanding a figure’s structure and offering an interaction that changes its meaning require different contracts, each appropriate to its effect on the learner.
Sources and context
- Warda engineering decision — structured figures
Decision on bounded types, references, validation, emphasis and visual provenance.
Internal records document Warda’s decisions and engineering contracts. External references, where included, explain a pattern or specification; design quality and effects on student learning are different questions.