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

> Explore the diagram-design architecture for progressive disclosure and lazy-loading references. Load optional data on demand for faster rendering and a better user experience.

- Repository: [Cathryn Lavery/diagram-design](https://github.com/cathrynlavery/diagram-design)
- Tags: architecture
- Published: 2026-09-05

---

**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`](https://github.com/cathrynlavery/diagram-design/blob/main/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`](https://github.com/cathrynlavery/diagram-design/blob/main/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

```html
<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

```javascript
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

```python
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`](https://github.com/cathrynlavery/diagram-design/blob/main/scripts/verify-motion.py) | Documents and validates the `motion-ready` progressive enhancement class |
| [`skills/diagram-design/scripts/mermaid_extract.py`](https://github.com/cathrynlavery/diagram-design/blob/main/skills/diagram-design/scripts/mermaid_extract.py) | Implements lazy-id insertion for Mermaid diagram parsing |
| [`skills/diagram-design/references/primitive-sketchy.md`](https://github.com/cathrynlavery/diagram-design/blob/main/skills/diagram-design/references/primitive-sketchy.md) | Example lazy-loadable reference content |
| [`README.md`](https://github.com/cathrynlavery/diagram-design/blob/main/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`](https://github.com/cathrynlavery/diagram-design/blob/main/scripts/verify-motion.py)
- **Lazy-loading references** use placeholder IDs generated during Mermaid extraction in [`mermaid_extract.py`](https://github.com/cathrynlavery/diagram-design/blob/main/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`](https://github.com/cathrynlavery/diagram-design/blob/main/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`](https://github.com/cathrynlavery/diagram-design/blob/main/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.