# Where to Find Reference Files for Each Diagram Type in Diagram Design

> Locate diagram reference files in the skills diagram-design references directory. Find grammar, layout rules, and styling tokens for each diagram type.

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

---

**Diagram Design stores dedicated reference files for every supported diagram type in the `skills/diagram-design/references/` directory**, with each `type-<name>.md` file containing the complete grammar, layout rules, and styling tokens required for rendering.

Diagram Design is an open-source diagramming specification system that defines visual layouts through structured markdown files. According to the cathrynlavery/diagram-design source code, these reference files serve as the single source of truth for how each diagram type renders, and the CLI automatically reads them when processing diagram commands.

## Locating the Reference File Directory

All diagram type specifications live in a dedicated references folder within the skill directory. Navigate to:

```bash
skills/diagram-design/references/

```

This directory contains one markdown file per supported diagram type following the naming convention `type-<name>.md`. The core documentation in [`skills/diagram-design/SKILL.md`](https://github.com/cathrynlavery/diagram-design/blob/main/skills/diagram-design/SKILL.md) maintains a comprehensive table mapping every visual type to its corresponding reference file between lines 86 and 108, making it easy to locate the exact specification you need.

## Understanding Reference File Contents

Each reference file is a self-contained specification document that defines:

- **Grammar rules** – Syntax requirements for the diagram type
- **Layout algorithms** – Spacing, positioning, and structural rules
- **Styling tokens** – Colors, fonts, line weights, and visual attributes
- **Validation schemas** – Accepted data structures and parameter ranges

For example, [`type-bar.md`](https://github.com/cathrynlavery/diagram-design/blob/main/type-bar.md) contains the complete specification for rendering bar charts, while [`type-sankey.md`](https://github.com/cathrynlavery/diagram-design/blob/main/type-sankey.md) defines the flow visualization logic for Sankey diagrams.

## Mapping Diagram Types to Reference Files

The master mapping lives in [`SKILL.md`](https://github.com/cathrynlavery/diagram-design/blob/main/SKILL.md) and lists every supported visualization. Common reference files include:

| Diagram Type | Reference File |
|--------------|----------------|
| Bar chart | [`type-bar.md`](https://github.com/cathrynlavery/diagram-design/blob/main/type-bar.md) |
| Polar chart | [`type-polar.md`](https://github.com/cathrynlavery/diagram-design/blob/main/type-polar.md) |
| Sankey diagram | [`type-sankey.md`](https://github.com/cathrynlavery/diagram-design/blob/main/type-sankey.md) |
| Tree diagram | [`type-tree.md`](https://github.com/cathrynlavery/diagram-design/blob/main/type-tree.md) |
| ER / Data model | [`type-er.md`](https://github.com/cathrynlavery/diagram-design/blob/main/type-er.md) |

The CLI commands `import-mermaid`, `export-diagram`, and `render` automatically pull the correct reference file when you specify a diagram type via the `--type` parameter.

## Working with Reference Files via CLI

You can interact with reference files directly using standard shell commands or the Diagram Design CLI.

List all available reference files:

```bash
cd diagram-design
ls skills/diagram-design/references/type-*.md

```

Inspect a specific reference specification:

```bash
less skills/diagram-design/references/type-bar.md

```

Render a diagram using its reference file automatically:

```bash

# Create input data

cat <<EOF > data.yaml
type: bar
series:
  - label: "2021"
    values: [10, 20, 30]
  - label: "2022"
    values: [15, 25, 35]
EOF

# Generate SVG using the bar chart reference

diagram-design render data.yaml --type bar --output chart.svg

```

## Key Files in the Repository

| Purpose | Path |
|---------|------|
| Master type mapping and documentation | [`skills/diagram-design/SKILL.md`](https://github.com/cathrynlavery/diagram-design/blob/main/skills/diagram-design/SKILL.md) |
| Reference file directory | `skills/diagram-design/references/` |
| Global style tokens and semantic guide | [`skills/diagram-design/references/style-guide.md`](https://github.com/cathrynlavery/diagram-design/blob/main/skills/diagram-design/references/style-guide.md) |
| Bar chart specification | [`skills/diagram-design/references/type-bar.md`](https://github.com/cathrynlavery/diagram-design/blob/main/skills/diagram-design/references/type-bar.md) |
| Polar chart specification | [`skills/diagram-design/references/type-polar.md`](https://github.com/cathrynlavery/diagram-design/blob/main/skills/diagram-design/references/type-polar.md) |

## Summary

- **Diagram Design reference files** are located in `skills/diagram-design/references/` and follow the naming pattern `type-<name>.md`
- **SKILL.md lines 86-108** contain the authoritative mapping between diagram types and their reference files
- **Each reference file** contains grammar, layout rules, and styling tokens specific to one diagram type
- **The CLI automatically reads** the appropriate reference file when you specify a diagram type in commands like `render` or `export-diagram`
- **The style guide** at [`references/style-guide.md`](https://github.com/cathrynlavery/diagram-design/blob/main/references/style-guide.md) provides shared semantic tokens used across all diagram types

## Frequently Asked Questions

### What is the naming convention for diagram reference files in Diagram Design?

Reference files use the pattern `type-<name>.md` where `<name>` corresponds to the diagram type identifier. For example, bar charts use [`type-bar.md`](https://github.com/cathrynlavery/diagram-design/blob/main/type-bar.md), tree diagrams use [`type-tree.md`](https://github.com/cathrynlavery/diagram-design/blob/main/type-tree.md), and entity-relationship diagrams use [`type-er.md`](https://github.com/cathrynlavery/diagram-design/blob/main/type-er.md). All files reside in the `skills/diagram-design/references/` directory.

### How do I determine which reference file corresponds to a specific diagram type?

Check the mapping table in [`skills/diagram-design/SKILL.md`](https://github.com/cathrynlavery/diagram-design/blob/main/skills/diagram-design/SKILL.md) between lines 86 and 108. This table lists every supported diagram type alongside its corresponding reference file name. Alternatively, list the contents of the `references/` directory and match the type name in the filename.

### Can I modify reference files to customize diagram rendering?

Yes, reference files are markdown specifications that define rendering behavior. Editing `type-<name>.md` files allows you to customize grammar rules, layout parameters, and styling tokens. However, modifications affect how the CLI renders diagrams of that type, so changes should follow the semantic tokens defined in [`style-guide.md`](https://github.com/cathrynlavery/diagram-design/blob/main/style-guide.md) for consistency.

### Where does Diagram Design store global styling rules?

Global styling tokens and semantic specifications live in [`skills/diagram-design/references/style-guide.md`](https://github.com/cathrynlavery/diagram-design/blob/main/skills/diagram-design/references/style-guide.md). This file contains shared definitions for colors, typography, spacing scales, and other visual attributes that individual diagram reference files reference to maintain visual consistency across different diagram types.