Een Docusaurus plugin voor toegankelijke diagrammen
Leestijd: 7 minuten
Ik heb gisteren mijn lange duurloop niet gedaan 😅. Ik zat weer veel te lang achter mijn beeldscherm 🥲. Een ideetje vanuit mijn werk liet me niet los. En programmeerwerk duurt vaak stuk langer dan je denkt. Nog even, nog even.. en zo zit je nog uren, de 80% moeite te steken in die laatste 20% werk. Want je moet toch op 100% komen. The reverse Pareto regel. Maar ik heb nu wel op NPM staan (npmjs.org): mijn 1e NodeJS in jaren open source module gepublished: remark-kroki-a11y Totaal zit ik nu op vier.
Komende week start een nieuw onderwijsblok en we... read more
Een Docusaurus plugin voor toegankelijke diagrammen
Leestijd: 7 minuten
▶Versiegeschiedenis
Datum
Status
Toelichting
01 feb 2026
Gestart
Eerste idee
01 feb 2026
Gepubliceerd
Eerste publicatie
03 feb 2026
Gewijzigd
Roodkapje UML plaatje toegevoegd; Tot slot sectie over ASSET/SVG accessibility uitgebreid; PlantUML code blocks aangepast
Ik heb gisteren mijn lange duurloop niet gedaan 😅. Ik zat weer veel te lang achter mijn beeldscherm 🥲. Een ideetje vanuit mijn werk liet me niet los. En programmeerwerk duurt vaak stuk langer dan je denkt. Nog even, nog even.. en zo zit je nog uren, de 80% moeite te steken in die laatste 20% werk. Want je moet toch op 100% komen. The reverse Pareto regel. Maar ik heb nu wel op NPM staan (npmjs.org): mijn 1e NodeJS in jaren open source module gepublished: remark-kroki-a11y Totaal zit ik nu op vier.
Komende week start een nieuw onderwijsblok en we zijn in lesmateriaal en (digitale) toetsen aan het kijken naar de toegankelijkheid ervan voor slechtziende en blinde studenten. Daarvan zijn er eigenlijk nog veel te weinig in ons onderwijs — en dat ligt misschien ook wel aan ons.
Programma code leent zich prima voor visueel beperkten, die hun screenreaders het laten voorlezen. En ‘blindtypen’ gaat sneller dan ziend typen (ook voor ‘zienden’). Alleen plaatjes zijn wel een obstakel. In Software Engineering gebruiken we veel diagrammen. Met bolletjes en pijltjes. Of vierkanten en pijltjes worden het meestal.
Een collega bedacht zich dat de ‘diagrams-as-code’ aanpak die we hanteren ook een betere instap biedt om het toegankelijk te maken, dan de plaatjes die hier uit komen. We gebruiken diagram-as-code formaten zoals PlantUML en Mermaid vooral omdat de voorbeelddiagrammen bij onze opdrachten dan makkelijk onderhoudbaar zijn. We hoeven niet de plaatjes zelf aan te passen, maar gewoon de code erachter. Dit kunnen we in versiebeheer houden, samen met de setup van codeprojecten. In git diff zie je welke aanpassingen op welk moment gemaakt zijn. En alles komt zo online als eigen website (we gebruiken Docusaurus).
In dit artikel beschrijf ik de plugin die we hiervoor gemaakt hebben. Sectie 1 legt het probleem uit. Sectie 2 beschrijft hoe diagrams-as-code een kans biedt. Sectie 3 introduceert de plugin, met het concept van situationele beperking en de roadmap voor verdere ontwikkeling. Sectie 4 illustreert UML voor lezers die nog geen goed beeld hebben, met een onverwacht maar wel vertrouwd voorbeeld: Roodkapje als UML. Sectie 5 reflecteert op het meta-aspect van dit project.
1. Het probleem: visuele diagrammen in een tekstuele wereld
UML diagrammen, C4 architectuurvisualisaties, flowcharts — het zijn krachtige communicatiemiddelen. Een goed diagram kan complexe relaties in één oogopslag duidelijk maken. Maar die “oogopslag” is precies het probleem.
Voor mensen die blind of slechtziend zijn, zijn deze diagrammen onzichtbaar. Een screenreader leest de alt-tekst van een afbeelding voor, maar wat schrijf je als alt-tekst voor een klassendiagram met tien klassen en vijftien relaties? “Klassendiagram” is te weinig informatie. Een volledige beschrijving wordt al snel een muur van tekst.
De European Accessibility Act (EAA) stelt vanaf 2025 eisen aan digitale toegankelijkheid. WCAG 2.1 niveau AA is de standaard. Maar los van wetgeving: als we als opleiding zeggen dat we inclusief willen zijn, dan moeten onze materialen dat ook zijn.
2. Diagrams-as-code: de oplossing zit in de bron
Hier komt een interessant inzicht: moderne diagramtools zoals PlantUML en Mermaid genereren diagrammen uit tekstuele broncode. Die broncode is per definitie toegankelijk — het is gewoon tekst.
Het Mermaid-project verwoordt dit mooi:
“The entire concept of Mermaid is that we can represent this visual content as plain structured text. Mermaid diagrams aren’t just static images generated in Photoshop; they are rendered dynamically from structured data.”
De broncode bevat alle informatie die in het diagram zit. We moeten het alleen op de juiste manier presenteren.
Hier een voorbeeld van een eenvoudig klassendiagram:
<p>Een eenvoudig klassendiagram met de klassen Student en Vak en de relatie ‘volgt’.</figcaption> </figure></p>
<details>
<summary>PlantUML broncode</summary>
<pre><code class="language-plantuml"><img class="plantuml" src="https://www.plantuml.com/plantuml/svg/~h407374617274756d6c0a217468656d6520706c61696e0a636c6173732053747564656e74207b0a20202d6e61616d3a20537472696e670a20202d73747564656e746e756d6d65723a20696e740a20202b766f6c677456616b2876616b3a2056616b290a7d0a0a636c6173732056616b207b0a20202d6e61616d3a20537472696e670a20202d73747564696570756e74656e3a20696e740a7d0a0a53747564656e742022302e2e2a22202d2d2022312e2e2a222056616b203a20766f6c67740a40656e64756d6c"> </code></pre>
</details>
<p>Dit beschrijft een <code class="language-plaintext highlighter-rouge">Student</code> met attributen <code class="language-plaintext highlighter-rouge">naam</code> en <code class="language-plaintext highlighter-rouge">studentnummer</code>, en een relatie met <code class="language-plaintext highlighter-rouge">Vak</code>. Een screenreader kan deze tekst voorlezen — het visuele diagram niet. Dat is precies het punt: de broncode <em>is</em> de toegankelijke beschrijving.</p>
<h2 id="remark-kroki-a11y-de-plugin">3. remark-kroki-a11y: de plugin</h2>
<p>Een collega kwam met een setup voor kleine customisatie van een Docusaurus plugin, <code class="language-plaintext highlighter-rouge">remark-kroki</code>, die we gebruiken om tijdens het opleveren van een nieuwe versie van de website alle diagrammen opnieuw te genereren. De plugin genereert naast het plaatje ook de originele code.</p>
<p>Ik maakte er een uitklapbalkje van, zodat reguliere studenten niet al deze afleidende tekst krijgen — maar de code wel kunnen gebruiken om zelf te visualiseren met een online tool, en eventueel aanpassingen te maken. Toen bedacht ik me dat je het diagram ook als natuurlijke taal zou kunnen beschrijven. En toen was het weekend voorbij.</p>
<p>De huidige 0.3 versie zet twee diagramtypes om naar natuurlijke taal: klassendiagrammen en sequentiediagrammen (de twee meest gebruikte). Deze beschrijvingen zijn bedoeld voor screenreaders, maar zijn ook nuttig voor zienden die <em>situationeel beperkt</em> zijn — in de zin dat ze deze diagrammen nog niet goed kennen en dus zelf nog niet kunnen “oplezen”. Beginnende studenten dus.</p>
<h3 id="situationele-beperking">3.1 Situationele beperking</h3>
<p>Dit concept van situationele beperking is belangrijk. Toegankelijkheid wordt vaak gezien als iets voor “mensen met een beperking”, maar iedereen is wel eens situationeel beperkt. Je bent slechtziend als je zonder bril wakker wordt. Je bent slechthorend in een lawaaierige trein. En je bent “diagram-analfabeet” als je nog nooit UML hebt gezien.</p>
<p><img src="/assets/img/posts/situational-limitations-uml.png" alt="Permanente, tijdelijke en situationele beperkingen - inclusief een student die UML nog niet kent" /> <em>Figuur 1</em>: Permanente, tijdelijke en situationele beperkingen. Bron: Chugaievska (2025).</p>
<p>Figuur 1 is gebaseerd op het werk van Chugaievska over inclusief ontwerp, uitgebreid met een vierde voorbeeld: een student die UML nog niet kent. Door de natuurlijke-taalbeschrijving toe te voegen helpen we niet alleen blinde studenten, maar ook beginners die de diagramsyntax nog moeten leren. De beschrijving is een brug naar begrip.</p>
<h3 id="wat-de-plugin-doet">3.2 Wat de plugin doet</h3>
<ol>
<li><strong>Toont de broncode</strong> — In een inklapbaar <code class="language-plaintext highlighter-rouge"><details></code> element onder elk diagram</li>
<li><strong>Genereert natuurlijke-taalbeschrijvingen</strong> — Voor ondersteunde diagramtypes</li>
<li><strong>Biedt tabs</strong> — Gebruikers kiezen tussen broncode en beschrijving</li>
<li><strong>Ondersteunt lokalisatie</strong> — Nederlands en Engels</li>
</ol>
<h3 id="wat-er-nog-kan-komen">3.3 Wat er nog kan komen</h3>
<p>Het lectoraat Accessible Digital Tools and Engineering heeft interesse getoond om studenten te begeleiden bij verdere uitbreiding. Denk aan:</p>
<ul>
<li>Echte ARIA-labels met betere navigatiestructuur</li>
<li>Meer diagramtypes: pie charts, bar charts, activity diagrams (Mermaid ondersteunt er 14)</li>
<li>Meer talen — meer talen is ook meer toegankelijk</li>
<li>Op termijn: de a11y-code integreren in de oorspronkelijke diagram-as-code tools, in plaats van als aparte plugin</li>
<li>Port naar Brightspace — nu we in het onderwijs naar Brightspace overstappen, moeten we onze open source Docusaurus website verlaten. Een Brightspace-integratie zou de toegankelijke diagrammen ook daar beschikbaar maken</li>
</ul>
<p>Een andere richting is SVG-embedded accessibility: de beschrijvingen niet <em>naast</em> het diagram, maar <em>in</em> de SVG zelf. SVG ondersteunt <code class="language-plaintext highlighter-rouge"><title></code>, <code class="language-plaintext highlighter-rouge"><desc></code>, en ARIA-attributen per element. Een klasse krijgt dan <code class="language-plaintext highlighter-rouge">aria-label="Klasse Student"</code>, een relatie <code class="language-plaintext highlighter-rouge">aria-label="Student volgt Vak (0..* naar 1..*)"</code>. Met <code class="language-plaintext highlighter-rouge">aria-flowto</code> kun je zelfs navigatie tussen elementen mogelijk maken. Het idee: de diagram-renderer verrijkt de SVG met semantische informatie. Wellicht kunnen we dit project ASSET noemen: Accessible SVG Source Enhancement Tool.</p>
<p>More Accessible Software Engineering for the world — mede dankzij de HAN.</p>
<p>De plugin staat op npm en GitHub: <a href="https://github.com/bartvanderwal/remark-kroki-a11y">github.com/bartvanderwal/remark-kroki-a11y</a>.</p>
<h3 id="architectuur-alternatieven-voor-jekyll">3.4 Architectuur-alternatieven voor Jekyll</h3>
<p>De remark-kroki-a11y plugin is gebouwd voor Docusaurus (remark/unified ecosystem). Voor Jekyll zijn er drie mogelijke aanpakken:</p>
<p><strong>Optie 1: Pre-build Script</strong> - Node.js script roept remark-kroki-a11y aan vóór Jekyll build, met A11y cache in JSON.</p>
<p><strong>Optie 2: Shared Core</strong> - Gedeelde npm package (a11y-diagram-core) met parsing logic, gebruikt door zowel remark plugin als Ruby gem via node.</p>
<p><strong>Optie 3: Client-side JS</strong> - Jekyll Spaceship rendert diagram als img, client-side JavaScript decodeert URL en genereert beschrijving.</p>
<p><strong>Optie 1</strong> hergebruikt de bestaande plugin maximaal. <strong>Optie 2</strong> vereist refactoring naar een gedeelde core. <strong>Optie 3</strong> dupliceert de logic in JavaScript maar werkt direct.</p>
<h2 id="roodkapje-als-uml-een-introductie-in-diagrammen">4. Roodkapje als UML: een introductie in diagrammen</h2>
<p>Om de plugin te demonstreren — en tegelijk UML te introduceren — gebruiken we een onverwacht domein: het sprookje van Roodkapje.</p>
<p><img src="/assets/img/posts/roodkapje-uml.png" alt="Roodkapje als UML klassendiagram - het sprookje gemodelleerd met klassen en relaties" /> <em>Figuur 2</em>: Roodkapje als UML klassendiagram. Een bekend verhaal vertaald naar formele diagrammen als introductie voor niet-technici.</p>
<p>Dit voorbeeld toont hoe je een verhaal in natuurlijke taal kunt vertalen naar formele diagrammen. Het is een prima introductie voor niet-technici of beginnende technici.</p>
<p>Roodkapje is wellicht een gimmick, maar ook een manier om analyse en ontwerp toe te passen op een bekend domein. Ervaren IT-ers classificeren op een gegeven moment technische complexiteit als ‘accidental complexity’ — die je minimaliseert — en domeincomplexiteit als ‘inherent complexity’ — die je maximaliseert door een complex domein te zoeken waar nog veel te verbeteren valt.</p>
<p>Denk aan innovatie in de <strong>energietransitie</strong>: zelfrijdende auto’s, robotisering van arbeid, de stikstof-transitie. Of de <strong>zorg</strong>: persoonsgebonden medicijnen, lifestyle-interventies tegen welvaartsziekten. Dit zijn thema’s waar HAN ICT zich op richt — complexe domeinen waar software verschil maakt.</p>
<h3 id="vermijd-the-one-diagram-to-rule-them-all">4.1 Vermijd “The One Diagram to rule them all”</h3>
<p>We splitsen het Roodkapje-verhaal op in drie delen om een “God Diagram” te voorkomen. Een God diagram is een anti-pattern, net als een ‘God object’ in code. Het opsplitsen beperkt cognitive load. Om toch overzicht te bieden maak je een apart diagram voor de onderlinge verbanden — vergelijkbaar met C4 zoomniveaus.</p>
<p>Een volledig voorbeeld heb ik in de plugin documentatie gezet als ‘gentle introduction to UML’ (met wel een stoer Roodkapje plaatje erbij voor de clickbait factor ;): <a href="https://bartvanderwal.github.io/remark-kroki-a11y/examples/roodkapje-als-uml-diagrammen">Roodkapje als UML diagrammen</a>.</p>
<h2 id="meta-eating-our-own-dogfood">5. Meta: eating our own dogfood</h2>
<p><img src="/assets/img/posts/roodkapje-uml-cute.png" alt="" width="400" style="float: right; margin-left: 1em;" /></p>
<p>Dit project heeft een meta-aspect: we bouwen een toegankelijkheids-plugin voor diagrammen, en gebruiken diezelfde diagrammen om de plugin te documenteren. De documentatiesite is tegelijk testsite.</p>
<p>Als de diagrammen niet toegankelijk zijn, faalt de plugin. Als ze wel toegankelijk zijn, bewijst de documentatie zichzelf.</p>
<h2 id="bronnen">Bronnen</h2>
<ul>
<li>Chugaievska, N. (27 januari 2025). <em>Designing for Everyone: Addressing Permanent, Temporary, and Situational Limitations</em>. Medium. Geraadpleegd van https://medium.com/@natalia.chugaievska/designing-for-everyone-addressing-permanent-temporary-and-situational-limitations-c3992b0e622e</li>
<li>Mermaid. (2024). <em>Accessibility discussion</em>. Geraadpleegd van https://github.com/mermaid-js/mermaid/issues/5632</li>
<li>Van der Wal, B. (2026). <em>remark-kroki-a11y</em>. Geraadpleegd van https://github.com/bartvanderwal/remark-kroki-a11y</li>
<li>W3C. (2018). <em>Web Content Accessibility Guidelines (WCAG) 2.1</em>. Geraadpleegd van https://w3.org/TR/WCAG21/</li>
</ul>
Bart van der Wal
Docent aan de HAN University of Applied Sciences en MAMIL met een passie voor SwimRun en andere avontuurlijke duursportavonturen. Schrijft over technologie, softwareontwikkeling en duursport.
