A Capability-Trigger Progression Model for Diagram-as-Code Pedagogy: Mermaid to D2 to TikZ for Document Engineering Volume 5

Document Engineering Volume 5 in the elixresearches program teaches Vietnamese 14+ learners to author diagrams as text using Mermaid, D2, and TikZ. The pedagogical question that determines its architecture is not which tool to teach first but when a learner should switch tools and when they should deepen the current one. This paper synthesises the official documentation of the three tools, the visualization-theory canon (Larkin and Simon, Tufte, Bertin, Cheng, Munzner, Healy), the cognitive-load and multimedia-learning literature (Sweller, PaasRenkl-Sweller, Mayer), the desirable-difficulty literature (Bjork and Bjork), and the cognitive-dimensions-of-notations literature (Green-Petre, Petre, Stenning-Oberlander) into a capabilitytrigger progression model. The model is operational: for any (learner, target diagram) pair it specifies which tool to use, which expressive limit will eventually trigger escalation, and which next tool resolves that limit. Mermaid covers procedural and behavioural diagrams at low syntactic cost; D2 covers structural and architectural diagrams with declarative layout; TikZ covers everything PGF can express. The substantive contribution is the transition-criteria table linking trigger to next tool to rationale, three worked transitions, and four learner-route maps (schoolproject, science-fair, capstone, math-olympiad). The progression is capability-trigger-based, not chronological; the operational question for the teacher is whether the learner has hit a recurring expressive limit, not whether a curriculum unit has been completed.