# How Diagram Design Loads Semantic, Type, and Animation References

> Learn how Diagram Design loads semantic, type, and animation references using a convention-based loader. Explore markdown file parsing and runtime API access for efficient lookup.

- Repository: [Cathryn Lavery/diagram-design](https://github.com/cathrynlavery/diagram-design)
- Tags: internals
- Published: 2026-08-21

---

**Diagram Design uses a convention-based reference loader that scans the `skills/diagram-design/references/` directory for markdown files matching `type-*.md` (semantic types) and [`animation.md`](https://github.com/cathrynlavery/diagram-design/blob/main/animation.md) (animation catalog), parses them into in-memory maps, and exposes them via the skill's public API for runtime lookup.**

The `cathrynlavery/diagram-design` repository implements a data-driven architecture that separates diagram semantics from core engine logic. Understanding how to load semantic type and animation references is essential for extending the system or debugging type-related issues, as the engine relies entirely on these markdown-based assets to define capabilities.

## Reference Loader Architecture

The loading mechanism treats semantic definitions as plain markdown assets rather than hard-coded configurations. This design keeps the core engine lightweight while making the reference set fully extensible.

### Directory Structure and File Conventions

The loader expects reference files in `skills/diagram-design/references/` following strict naming patterns:

- **`type-*.md`** files define specific diagram kinds (e.g., [`type-flowchart.md`](https://github.com/cathrynlavery/diagram-design/blob/main/type-flowchart.md), [`type-sankey.md`](https://github.com/cathrynlavery/diagram-design/blob/main/type-sankey.md))
- **[`animation.md`](https://github.com/cathrynlavery/diagram-design/blob/main/animation.md)** contains the central catalog of animation primitives used across all diagram types

According to the source code, examples include [`type-flowchart.md`](https://github.com/cathrynlavery/diagram-design/blob/main/type-flowchart.md) for Flowchart diagrams and [`type-sankey.md`](https://github.com/cathrynlavery/diagram-design/blob/main/type-sankey.md) for Sankey diagrams.

### In-Memory Data Structures

After scanning, the loader populates two primary data structures:

1. **Semantic-type map** (`semanticTypes`): Keys are diagram type identifiers derived from filenames (stripping the `type-` prefix and `.md` extension), values are parsed markdown content describing the type’s semantics, allowed primitives, and default visual parameters.

2. **Animation map** (`animationReference`): A single entry keyed by `"animation"` containing the parsed animation reference data from [`animation.md`](https://github.com/cathrynlavery/diagram-design/blob/main/animation.md).

## The Three-Step Loading Process

The initialization sequence follows three distinct phases:

1. **Directory Scan**: The loader walks `skills/diagram-design/references/` and collects every `.md` file.

2. **Pattern Classification**: Files matching `type-*.md` are classified as semantic-type references, while [`animation.md`](https://github.com/cathrynlavery/diagram-design/blob/main/animation.md) is treated as the animation catalog.

3. **Parsing and Storage**: Each markdown file is parsed (typically via a lightweight parser like `markdown-it`) and stored in the corresponding map for fast lookup at runtime.

## Implementation: The Reference Loader Code

The loading logic is implemented in the skill's initialization code. Below is a simplified representation of [`reference-loader.js`](https://github.com/cathrynlavery/diagram-design/blob/main/reference-loader.js):

```js
// ==== reference-loader.js (simplified) ====
// Scan the references folder and populate maps
import { readdirSync, readFileSync } from 'fs';
import path from 'path';
import markdownIt from 'markdown-it';

const REFS_DIR = path.resolve(__dirname, 'skills/diagram-design/references');
const md = markdownIt();

export const semanticTypes = {};
export let animationReference = null;

for (const file of readdirSync(REFS_DIR)) {
  const fullPath = path.join(REFS_DIR, file);
  const content = readFileSync(fullPath, 'utf8');
  const parsed = md.render(content);

  if (file.startsWith('type-') && file.endsWith('.md')) {
    const typeName = file.slice(5, -3); // strip "type-" and ".md"
    semanticTypes[typeName] = parsed;
  } else if (file === 'animation.md') {
    animationReference = parsed;
  }
}

```

## Consuming References in Commands

Once loaded, these maps are exposed through the skill's public API. Commands such as `import-mermaid`, `export-diagram`, and `doctor` access type capabilities without hard-coding definitions.

### Retrieving Type Specifications

```js
// ==== consumer code ====
// Retrieve a type definition
import { semanticTypes, animationReference } from './reference-loader.js';

function getDiagramSpec(type) {
  const spec = semanticTypes[type];
  if (!spec) throw new Error(`Unknown diagram type: ${type}`);
  return spec;
}

// Retrieve an animation definition
function getAnimationSpec(name) {
  // animationReference contains a markdown list of all animations;
  // you can further parse it to locate a specific entry.
  // For brevity, assume a simple lookup helper exists.
  return findAnimationInMarkdown(animationReference, name);
}

```

### Usage in the Import-Mermaid Command

The `import-mermaid` command demonstrates runtime lookup:

```js
// ==== Example usage in a command ====
// `import‑mermaid` command uses the loader to validate the requested type
import { getDiagramSpec } from './reference-loader.js';

export async function importMermaid(args) {
  const { type, source } = args;
  const typeSpec = getDiagramSpec(type);   // ← loads the semantic type
  // …process the mermaid source using `typeSpec`…
}

```

## Extending the Reference System

Because reference data lives in plain markdown, adding support for new diagram types requires no code changes. Simply drop a new `type-{name}.md` file into `skills/diagram-design/references/`. The loader automatically picks it up on the next initialization, populating the `semanticTypes` map with the new key.

Similarly, animation definitions can be extended by modifying [`animation.md`](https://github.com/cathrynlavery/diagram-design/blob/main/animation.md). This convention-based approach is documented in [`skills/diagram-design/references/semantic-patterns.md`](https://github.com/cathrynlavery/diagram-design/blob/main/skills/diagram-design/references/semantic-patterns.md) and the main [`skills/diagram-design/SKILL.md`](https://github.com/cathrynlavery/diagram-design/blob/main/skills/diagram-design/SKILL.md).

## Summary

- **Convention-based loading**: The system scans `skills/diagram-design/references/` for `type-*.md` and [`animation.md`](https://github.com/cathrynlavery/diagram-design/blob/main/animation.md) files.
- **Dynamic parsing**: Files are parsed at runtime into `semanticTypes` and `animationReference` maps.
- **Zero-code extensibility**: New diagram types are added by creating markdown files without modifying the engine.
- **API exposure**: Commands like `import-mermaid` access type specifications through the public API rather than hard-coded logic.
- **Documentation sources**: Reference semantics are documented in [`semantic-patterns.md`](https://github.com/cathrynlavery/diagram-design/blob/main/semantic-patterns.md) and [`SKILL.md`](https://github.com/cathrynlavery/diagram-design/blob/main/SKILL.md).

## Frequently Asked Questions

### What file naming convention identifies semantic types?

Files must match the pattern `type-*.md` and reside in `skills/diagram-design/references/`. The asterisk represents the type identifier (e.g., `flowchart` in [`type-flowchart.md`](https://github.com/cathrynlavery/diagram-design/blob/main/type-flowchart.md)), which becomes the key in the `semanticTypes` map after stripping the `type-` prefix and `.md` extension.

### How does the loader handle animation references differently from type references?

While semantic types are distributed across multiple `type-*.md` files and stored in the `semanticTypes` object map, animation references are consolidated in a single [`animation.md`](https://github.com/cathrynlavery/diagram-design/blob/main/animation.md) file. The loader treats this as a special case, storing it in the `animationReference` variable rather than a map, though it is conceptually keyed by `"animation"`.

### Can I add custom diagram types without modifying the core engine?

Yes. The architecture supports zero-code extension. Create a new markdown file following the `type-{custom-name}.md` convention in the references directory, and the loader will automatically include it in the `semanticTypes` map on the next run. No changes to [`reference-loader.js`](https://github.com/cathrynlavery/diagram-design/blob/main/reference-loader.js) or other source files are required.

### Where are the reference files located in the repository?

All reference assets are stored in `skills/diagram-design/references/`. Key files include [`type-flowchart.md`](https://github.com/cathrynlavery/diagram-design/blob/main/type-flowchart.md) for flowchart semantics, [`type-sankey.md`](https://github.com/cathrynlavery/diagram-design/blob/main/type-sankey.md) for Sankey diagrams, [`animation.md`](https://github.com/cathrynlavery/diagram-design/blob/main/animation.md) for animation primitives, and [`semantic-patterns.md`](https://github.com/cathrynlavery/diagram-design/blob/main/semantic-patterns.md) which documents the overall semantic-pattern system driving the loader.