How the 39 Diagram Types Are Referenced and Organized in diagram-design

The cathrynlavery/diagram-design repository defines 39 distinct editorial diagram types that are referenced through five integrated layers: human-readable documentation, CLI type flags, canonical HTML examples, PNG screenshot assets, type-specific markdown references, and a programmatic SUPPORTED_KINDS constant.

The repository maintains a curated taxonomy of diagram types—from standard flowchart and sequenceDiagram to specialized variants like stateDiagram-v2—used across import, export, and rendering pipelines. These 39 diagram types are not merely listed but embedded into the codebase through a cohesive organization system that connects documentation, visual assets, and validation logic.

Human-Readable Documentation in README and CONTRIBUTING

The primary enumeration of the 39 diagram types appears in the project documentation. The README explicitly lists all supported types as plain text identifiers (e.g., flowchart, sequenceDiagram, stateDiagram-v2, erDiagram), providing the human-readable catalogue that users reference when selecting a format.

The CONTRIBUTING guide reiterates this list and establishes the requirement that every diagram type must ship three distinct HTML variants. This documentation layer serves as the discoverability entry point, ensuring contributors and users understand the full scope of supported visual formats before interacting with the CLI or source code.

CLI Integration and Type Forcing

The diagram types surface directly in the command-line interface through the --type flag defined in the import command documentation. When importing Mermaid or Draw.io files, users can override automatic detection by specifying a type explicitly.

In commands/import-mermaid.md and commands/import-drawio.md, the --type parameter accepts any of the 39 identifiers listed in the README. This allows the parser to bypass inference and force a specific rendering pipeline:

# Force a specific diagram type during Mermaid import

diagram-design import-mermaid diagram.mmd --type flowchart

# Explicitly set type when importing Draw.io XML

diagram-design import-drawio architecture.drawio --type sequenceDiagram

If the --type flag is omitted, the system falls back to automatic detection driven by the source code constants described below.

Canonical Example Files and Visual Assets

Each of the 39 diagram types maintains a canonical set of example files at the repository root. These files follow the naming convention example-<type>.html, example-<type>-dark.html, and example-<type>-full.html, providing light, dark, and full-variant renderings respectively.

These HTML examples serve as the visual regression reference for the test suite. When the export pipeline generates output, it compares results against these canonical files to guarantee visual fidelity across diagram types.

Additionally, the repository stores PNG screenshots under docs/screenshots/ with filenames matching the diagram type identifiers (e.g., flowchart.png, sequence.png, state.png). These 39 images populate the README and Architecture Decision Records (ADRs), offering users a quick visual catalogue without requiring them to render examples locally.

Semantic Rules and Reference Documentation

Beneath the visual layer, each diagram type has a dedicated reference file under skills/diagram-design/references/ (e.g., type-loop.md, type-dp-security-matrix.md). These markdown files encode the layout rules, connector primitives, and semantic constraints specific to that diagram type.

The parser script consults these reference files during the validation and transformation phases. When mermaid_extract.py processes a diagram, it cross-references the type against its corresponding markdown file to ensure the rendered HTML respects semantic constraints such as valid node shapes, permissible edge types, and directional flow requirements.

Programmatic Enumeration in Source Code

The definitive machine-readable list of supported types lives in skills/diagram-design/scripts/mermaid_extract.py within the SUPPORTED_KINDS constant. This constant enumerates the valid diagram kinds as a delimited string or list:

# From mermaid_extract.py

SUPPORTED_KINDS = "flowchart, sequenceDiagram, stateDiagram-v2, erDiagram, ..."

This constant drives the automatic type inference performed by the import commands. When a user does not provide the --type flag, the code matches the input file’s syntax patterns against this list to determine the appropriate rendering pipeline. Adding a new diagram type requires extending this constant to ensure the parser recognizes the new format.

Adding a New Diagram Type

When contributors introduce a new diagram type to the repository, they must update all five organizational layers to maintain consistency:

1. Code constant: Add the type identifier to SUPPORTED_KINDS in skills/diagram-design/scripts/mermaid_extract.py
2. Reference rules: Create a new type-<name>.md file under skills/diagram-design/references/ documenting layout and semantic constraints
3. Example files: Generate example-<type>.html, example-<type>-dark.html, and example-<type>-full.html at the repository root
4. Visual asset: Add <type>.png to docs/screenshots/ for documentation previews
5. Documentation: Update README.md and CONTRIBUTING.md to list the new type among the supported 39

This multi-file workflow ensures that new types are discoverable, visually validated, and semantically enforceable across the entire toolchain.

Summary

• The 39 diagram types are enumerated in README.md and CONTRIBUTING.md for human discoverability.
• The CLI exposes types through the --type flag in commands/import-mermaid.md and commands/import-drawio.md.
• Canonical examples (example-<type>.html variants) and PNG screenshots (docs/screenshots/) provide visual regression testing and documentation assets.
• Semantic constraints for each type are defined in skills/diagram-design/references/type-*.md files.
• The SUPPORTED_KINDS constant in skills/diagram-design/scripts/mermaid_extract.py drives automatic type inference and validation.

Frequently Asked Questions

How do I force a specific diagram type when importing a file?

Use the --type flag followed by the diagram identifier. For example, diagram-design import-mermaid diagram.mmd --type flowchart forces the parser to treat the input as a flowchart rather than attempting automatic detection based on syntax patterns.

Where are the layout rules for each diagram type defined?

Layout rules, connector primitives, and semantic constraints reside in the reference markdown files located at skills/diagram-design/references/type-<name>.md. The mermaid_extract.py script consults these files during parsing to validate diagram structure.

What files must I create when adding a new diagram type to the repository?

You must update the SUPPORTED_KINDS constant in skills/diagram-design/scripts/mermaid_extract.py, create a reference file in skills/diagram-design/references/, add three HTML example files (example-<type>.html, example-<type>-dark.html, example-<type>-full.html) to the root, place a PNG screenshot in docs/screenshots/, and update the documentation in README.md and CONTRIBUTING.md.

How does the repository validate that a diagram renders correctly for its type?

The test suite compares generated output against the canonical HTML example files stored at the repository root. Each of the 39 diagram types has three variant files (light, dark, full) that serve as the ground truth for visual fidelity and structural correctness.

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