Progressive Disclosure and Lazy-Loading References Architecture in Diagram-Design

Diagram-Design implements a progressive-enhancement architecture that separates core diagram rendering from optional reference data, loading extra content only when users explicitly request it.

The cathrynlavery/diagram-design repository uses a modular frontend strategy to keep initial page loads fast while supporting rich reference documentation. This architecture ensures diagrams render even without JavaScript, then progressively enhances the experience as users interact with reference controls.

Core Design Principles

The architecture rests on two pillars: progressive disclosure for UI behavior and lazy-loading references for data management. Each solves a distinct performance problem while maintaining accessibility and resilience.

Progressive Disclosure with motion-ready

Hidden reference blocks stay dormant until user interaction triggers reveal. The CSS class motion-ready marks elements prepared for progressive enhancement—the class is injected by a small script after initial render, ensuring markup remains functional if JavaScript fails.

In scripts/verify-motion.py, a comment documents this "progressive enhancement class" pattern. The script verifies that motion-capable browsers receive enhanced behavior while baseline users still access core content.

Lazy-Loading References with lazy-id

Reference data lives in standalone Markdown files under skills/diagram-design/references/. The frontend fetches these on demand using the lazy-id technique embedded in Mermaid extraction logic.

During diagram generation in skills/diagram-design/scripts/mermaid_extract.py, the extractor inserts placeholder IDs into markup. These IDs enable the rendering engine to request corresponding reference files only when needed—typically when a user clicks a "show reference" control.

Implementation Workflow

The complete data flow follows four stages:

1. Initial render — The main diagram page generates without any reference content, sending minimal HTML/CSS.

2. User activation — Clicking a "show reference" control swaps the motion-ready class on the target element, triggering the lazy loader.

3. Data fetch — The loader requests the appropriate Markdown file from the references/ folder, parses it, and injects rendered HTML.

4. Caching benefit — Because reference files are separate, they cache individually and update without rebuilding the entire diagram.

Code Implementation

HTML: Minimal Diagram Structure

<div class="diagram">
  <!-- Diagram SVG goes here -->
</div>

<button class="show-ref" data-ref="primitive-sketchy">
  Show reference
</button>

<div class="reference motion-ready" id="ref-primitive-sketchy" hidden></div>

The hidden attribute ensures the reference block is invisible and removed from accessibility trees until revealed. The data-ref attribute links the trigger button to its target container.

JavaScript: Progressive Disclosure Controller

document.querySelectorAll('.show-ref').forEach(btn => {
  btn.addEventListener('click', async e => {
    const refId = e.target.dataset.ref;
    const container = document.getElementById(`ref-${refId}`);
    
    // Reveal container (progressive disclosure)
    container.hidden = false;
    container.classList.add('motion-ready');
    
    // Lazy-load markdown reference
    if (!container.dataset.loaded) {
      const resp = await fetch(`/skills/diagram-design/references/${refId}.md`);
      const markdown = await resp.text();
      container.innerHTML = marked.parse(markdown);
      container.dataset.loaded = 'true';
    }
  });
});

The dataset.loaded flag prevents redundant network requests if users toggle the same reference multiple times.

Python: Lazy-ID Generation in Mermaid Extraction

def extract_mermaid(text):
    # When encountering participant declarations, preserve lazy id

    # e.g., `participant "Alice Smith"` → lazy id "A"

    if line.startswith('participant'):
        name = ...  # extract name

        lazy_id = name[0].upper()
        diagram.add_node(lazy_id, label=name)

This extraction logic preserves the lazy-id mapping that connects diagram elements to their reference files.

Key Files and Responsibilities

File	Purpose
scripts/verify-motion.py	Documents and validates the motion-ready progressive enhancement class
skills/diagram-design/scripts/mermaid_extract.py	Implements lazy-id insertion for Mermaid diagram parsing
skills/diagram-design/references/primitive-sketchy.md	Example lazy-loadable reference content
README.md	Describes overall plugin architecture

Performance and Scalability Benefits

• Reduced initial payload — Only essential diagram markup travels on first load; reference assets load on demand
• Independent caching — Reference files cache with their own TTLs, eliminating full rebuilds for documentation updates
• Graceful degradation — Core diagram functionality persists without JavaScript; references simply remain accessible via alternative navigation
• Modular scaling — New reference documents integrate by dropping files into references/ without pipeline modifications

Summary

• Progressive disclosure relies on the motion-ready CSS class added post-render, documented in scripts/verify-motion.py
• Lazy-loading references use placeholder IDs generated during Mermaid extraction in mermaid_extract.py
• Reference data lives as standalone Markdown in skills/diagram-design/references/ for on-demand fetching
• Resilience is built-in: diagrams render without JavaScript, enhancing only when capabilities allow

Frequently Asked Questions

How does the motion-ready class support accessibility?

The motion-ready class signals that dynamic transitions can safely apply to an element. By adding it via JavaScript after initial render, the base markup remains stable for screen readers and non-JS environments. Users with prefers-reduced-motion can be detected before class application, respecting accessibility preferences.

Can reference files be updated without redeploying the application?

Yes. Because references are standalone Markdown files fetched at runtime, updating skills/diagram-design/references/primitive-sketchy.md or adding new files requires no build step. CDN cache invalidation or filename versioning controls propagation.

What happens if a lazy-loaded reference request fails?

The implementation should include error handling in the fetch promise—omitted in the example for clarity. Production code typically catches network failures and displays a fallback message or retry control, keeping the dataset.loaded flag unset so subsequent clicks reattempt the load.

Is this architecture specific to Mermaid diagrams?

No. While the mermaid_extract.py implementation targets Mermaid syntax, the progressive disclosure and lazy-loading patterns apply broadly. The motion-ready class pattern and on-demand fetch logic work with any markup structure where hidden supplementary content enhances a core visualization.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}