Class without classDef
Auditing 107 posts for diagram candidates, setting token-driven styling rules for Mermaid figures, and defining an accessible, click-to-trigger motion standard.
The development blog had reached 107 published posts covering four months of history, and while the writing had settled into a steady cadence since the first style guide, the visual language remained almost entirely unstandardized. Most posts relied on dense prose to describe state machines, architecture boundaries, and timing sequences that would be clearer at a glance with a diagram. A coordinated pass set out to audit the full archive for illustration opportunities and pin down reusable standards for technical figures and interactive motion.
Twelve research passes categorized all 107 posts by subject matter and structure, evaluating whether each topic described a flow, a layout transition, or an architectural boundary. The survey sorted the backlog into 43 high-value candidates, 37 secondary candidates, and 22 posts better left as pure prose. Unusually dense refactors and multi-stage game flows rose to the top, giving the project a clear map of where visual receipts would pay off most without turning diagram creation into an unmanageable chore.
flowchart LR accTitle: Mermaid highlight class styling flow accDescr: A node tagged with class accent receives theme tokens from global CSS without needing inline classDef overrides. Input[Raw Diagram] --> Node[class nodeId accent] Node --> Output[Theme-Aware SVG] class Node accent
Turning those suggestions into reality required a strict set of rules for technical diagrams. A soft complexity ceiling was established so flowcharts split before branching became unreadable, while sequence and state diagrams were allowed more density before breaking apart. But adding semantic highlight classes (accent, warn, muted) exposed an unexpected rendering bug. Pairing a diagram’s class assignment with a classDef placeholder injected an inline !important style directly onto the SVG element. In dark mode, that inline override beat the site’s stylesheet, rendering solid white node backgrounds behind light text and triggering a severe contrast failure. The fix was removing classDef entirely: tagging nodes with class alone lets the site’s design tokens style every element cleanly across theme changes.
Static diagrams still could not capture mechanics defined by timing and movement, such as win confetti, collision bursts, or combo feedback pacing. For those cases, the project established guidelines for animated illustrations built as standalone Svelte islands. To avoid pulling in the full game runtime, each island uses hardcoded spawn points and deterministic physics while rendering inside a standard figure wrapper. Crucially, motion never autoplays: every animation requires an explicit click to trigger, provides a distinct replay affordance, and freezes on a single representative frame whenever a reader requests reduced motion.
With standards pinned for both static diagrams and interactive motion, the blog machine has a predictable foundation for illustrating technical stories. The next step is working through the high-priority backlog to equip the archive’s most complex posts with the visual context they deserve.