How Diagram Design Loads Semantic, Type, and Animation References

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 (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, type-sankey.md)
• animation.md contains the central catalog of animation primitives used across all diagram types

According to the source code, examples include type-flowchart.md for Flowchart diagrams and 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.

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 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:

// ==== 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

// ==== 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:

// ==== 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. This convention-based approach is documented in skills/diagram-design/references/semantic-patterns.md and the main skills/diagram-design/SKILL.md.

Summary

• Convention-based loading: The system scans skills/diagram-design/references/ for type-*.md and 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 and 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), 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 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 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 for flowchart semantics, type-sankey.md for Sankey diagrams, animation.md for animation primitives, and semantic-patterns.md which documents the overall semantic-pattern system driving the loader.

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