# How the 39 Diagram Types Are Referenced and Organized in diagram-design > Discover how the cathrynlavery/diagram-design repository organizes 39 diagram types across documentation CLI flags HTML examples PNG assets markdown references and a constant - Repository: [Cathryn Lavery/diagram-design](https://github.com/cathrynlavery/diagram-design) - Tags: architecture - Published: 2026-08-21 --- **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`](https://github.com/cathrynlavery/diagram-design/blob/main/commands/import-mermaid.md) and [`commands/import-drawio.md`](https://github.com/cathrynlavery/diagram-design/blob/main/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: ```bash # 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-.html`, `example--dark.html`, and `example--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`](https://github.com/cathrynlavery/diagram-design/blob/main/type-loop.md), [`type-dp-security-matrix.md`](https://github.com/cathrynlavery/diagram-design/blob/main/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`](https://github.com/cathrynlavery/diagram-design/blob/main/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`](https://github.com/cathrynlavery/diagram-design/blob/main/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: ```python # 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`](https://github.com/cathrynlavery/diagram-design/blob/main/skills/diagram-design/scripts/mermaid_extract.py) 2. **Reference rules**: Create a new `type-.md` file under `skills/diagram-design/references/` documenting layout and semantic constraints 3. **Example files**: Generate `example-.html`, `example--dark.html`, and `example--full.html` at the repository root 4. **Visual asset**: Add `.png` to `docs/screenshots/` for documentation previews 5. **Documentation**: Update [`README.md`](https://github.com/cathrynlavery/diagram-design/blob/main/README.md) and [`CONTRIBUTING.md`](https://github.com/cathrynlavery/diagram-design/blob/main/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`](https://github.com/cathrynlavery/diagram-design/blob/main/README.md) and [`CONTRIBUTING.md`](https://github.com/cathrynlavery/diagram-design/blob/main/CONTRIBUTING.md) for human discoverability. - The **CLI** exposes types through the `--type` flag in [`commands/import-mermaid.md`](https://github.com/cathrynlavery/diagram-design/blob/main/commands/import-mermaid.md) and [`commands/import-drawio.md`](https://github.com/cathrynlavery/diagram-design/blob/main/commands/import-drawio.md). - **Canonical examples** (`example-.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`](https://github.com/cathrynlavery/diagram-design/blob/main/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-.md`. The [`mermaid_extract.py`](https://github.com/cathrynlavery/diagram-design/blob/main/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`](https://github.com/cathrynlavery/diagram-design/blob/main/skills/diagram-design/scripts/mermaid_extract.py), create a reference file in `skills/diagram-design/references/`, add three HTML example files (`example-.html`, `example--dark.html`, `example--full.html`) to the root, place a PNG screenshot in `docs/screenshots/`, and update the documentation in [`README.md`](https://github.com/cathrynlavery/diagram-design/blob/main/README.md) and [`CONTRIBUTING.md`](https://github.com/cathrynlavery/diagram-design/blob/main/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.