Diagram Design: evidence-driven visual explanations
A learning lab for Diagram Design: explain checker findings beside the rendered artifact
Design a proposed local teaching interface that makes paint order and checker coverage visible without pretending it is already shipped.
What you will learn
- Make the checker’s model visible
- Keep static analysis distinct from browser observation
- Add interaction only where it explains a relationship
Before you start
- Basic HTML and SVG concepts
- Ability to distinguish a system relationship from its visual layout
Choose a useful representation, account for simplification and interpret checker findings within their real scope.
Key takeaways
- Expose what a checker recognizes, not only whether it passes.
- Use disagreement with rendering to explain model limits.
- A new preview interface needs its own execution and accessibility design.
Make the checker’s model visible
A useful extension would place synthetic SVG markup, the checker’s recognized rectangles and a browser preview side by side. Selecting a reported mask could highlight its source offset, dimensions and later node. The reader would see why paint order changes the result without having to infer everything from an error line.
Start with the paired fixtures from this review: later versus earlier node, one-unit versus two-unit overlap, and width 200 versus 201. Ask learners to predict the result before revealing it. This is a proposed educational interface, not an existing Diagram Design command or a measured improvement in learning outcomes.
Keep static analysis distinct from browser observation
The interface should show when a rectangle was not recognized because its attributes use a different order or quote style. It should also distinguish raw-coordinate findings from a browser preview affected by transforms or fill. Disagreement is useful teaching evidence rather than an error that the interface should hide to make the checker appear complete.
Use only synthetic fixtures initially. Rendering arbitrary imported HTML introduces a new execution boundary, so a future implementation needs isolation and a clear resource policy before accepting real files. A source inspector that silently loads user scripts or remote fonts would change the project’s risk profile substantially.
Add interaction only where it explains a relationship
A keyboard-operable two-dimensional interface can explain rectangle overlap and paint order directly. Three.js would add camera and rendering concerns without automatically improving this lesson. If a later idea involves genuinely spatial structure, define the learning task first and compare it with a simpler representation before choosing a 3D engine.
The next deliverable could be a versioned fixture explorer with an accessible textual explanation of every result, followed by reader prediction tasks. This series delivers original static illustrations and a reproducible checker probe only. No interactive application, browser sandbox, automatic repair system or learner experiment has been implemented.
Implementation steps
- 1
Select paired synthetic fixtures with different outcomes.
- 2
Display recognized geometry and source order explicitly.
- 3
Design isolated rendering before accepting arbitrary files.
- 4
Test whether learners can predict outcomes before adding richer graphics.
Copy-ready example
{
"proposal": "geometry-checker teaching lab",
"status": "not implemented",
"acceptArbitraryHtml": false,
"executeImportedScripts": false,
"automaticRepair": false,
"learningTask": "predict findings and explain coverage limits"
}Frequently asked questions
Is the teaching lab already available?
No. It is an editorial proposal. The delivered work consists of static chapter diagrams and a reproducible sixteen-case checker probe.
Why not start with Three.js?
Paint order and rectangle overlap are directly explainable in two dimensions. A 3D interface should follow a demonstrated learning requirement, not precede it.
Sources
- scripts/verify-geometry.pySource checked 2026-09-08
- docs/adr/0005-label-geometry-is-verified.mdSource checked 2026-09-08
- docs/adr/0001-static-by-default-single-pinned-controller.mdSource checked 2026-09-08