# What Information Is Included in Type‑Specific Convention Files for Diagram Design?

> Explore type-specific convention files for Diagram Design. Learn about headers, best use cases, layout rules, anti-patterns, and examples to improve your diagramming.

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

---

**Each type‑specific convention file in Diagram Design is a self‑contained style guide containing five standardized sections: a header identifying the diagram type, "Best for" use‑case guidance, detailed layout conventions, anti‑patterns to avoid, and links to working examples.**

The Diagram Design skill maintains a **reference file** for every supported diagram type in the `cathrynlavery/diagram-design` repository. These files live under `skills/diagram-design/references/` and follow a strict template that tells authors exactly **what to draw, how to draw it, and what to avoid**. Whether you're creating a Venn diagram, flowchart, or architecture diagram, the type‑specific convention file provides the authoritative rules for consistent, professional output.

---

## Standard Sections in Every Convention File

Every `type‑*.md` file follows the same six‑part structure. The sections are:

### Header: Diagram Type Identification

The file opens with an H1 heading that names the diagram type. This serves as the file's primary identifier and matches the naming convention used throughout the codebase.

```markdown

# Venn / Set Overlap

```

Source: [[`skills/diagram-design/references/type-venn.md`](https://github.com/cathrynlavery/diagram-design/blob/main/skills/diagram-design/references/type-venn.md)](https://github.com/cathrynlavery/diagram-design/blob/main/skills/diagram-design/references/type-venn.md)

---

### Best For: Ideal Use‑Cases

A concise paragraph describing when this diagram type excels. This helps authors select the right visualization for their data.

- **Venn diagrams**: "Intersection of concepts, domains, or feature sets"
- **Tree diagrams**: "Org charts, dependency trees, taxonomies, and hierarchical classifications"

Source: [[`skills/diagram-design/references/type-tree.md`](https://github.com/cathrynlavery/diagram-design/blob/main/skills/diagram-design/references/type-tree.md)](https://github.com/cathrynlavery/diagram-design/blob/main/skills/diagram-design/references/type-tree.md)

---

### Layout Conventions: Visual Rules and Structure

This is the most detailed section, covering:

- **Concrete visual guidelines**: stroke width, colors, opacity, fonts, sizes, positioning
- **Shape‑to‑type mappings**: e.g., "Oval = start/end", "Diamond = decision"
- **Ordering and hierarchy rules**: root placement, depth limits, vertical ordering
- **Special markers**: usage of the coral accent and other signature elements

These rules ensure diagrams render consistently across different environments and maintain the Diagram Design visual identity.

Source: [[`skills/diagram-design/references/type-flowchart.md`](https://github.com/cathrynlavery/diagram-design/blob/main/skills/diagram-design/references/type-flowchart.md)](https://github.com/cathrynlavery/diagram-design/blob/main/skills/diagram-design/references/type-flowchart.md)

---

### Anti‑Patterns: Common Mistakes to Avoid

A bullet‑list of errors specific to that diagram type. Examples include:

- "4+ circles in a Venn diagram"
- "Diagonal connector lines"
- "Using fill colour to signal node type"

Source: [[`skills/diagram-design/references/type-venn.md`](https://github.com/cathrynlavery/diagram-design/blob/main/skills/diagram-design/references/type-venn.md)](https://github.com/cathrynlavery/diagram-design/blob/main/skills/diagram-design/references/type-venn.md)

---

### Examples: Reference Implementations

Links to three asset types demonstrating correct implementation:

1. **Minimal**: Bare‑bones version showing core structure
2. **Dark‑mode**: Color‑adjusted variant for dark backgrounds
3. **Full‑editorial**: Production‑ready example with complete styling

Source: [[`skills/diagram-design/references/type-tree.md`](https://github.com/cathrynlavery/diagram-design/blob/main/skills/diagram-design/references/type-tree.md)](https://github.com/cathrynlavery/diagram-design/blob/main/skills/diagram-design/references/type-tree.md)

---

### Additional Notes: Type‑Specific Nuances

Some diagram types include extended guidance that doesn't fit the standard sections:

- **Bar ordering conventions** for high‑level diagrams
- **Colour‑override rules** for accessibility or branding
- **Explicit row/column definitions** for data‑flow diagrams

Source: [[`skills/diagram-design/references/type-high-level.md`](https://github.com/cathrynlavery/diagram-design/blob/main/skills/diagram-design/references/type-high-level.md)](https://github.com/cathrynlavery/diagram-design/blob/main/skills/diagram-design/references/type-high-level.md)

---

## How Skills Import and Apply Conventions

The `skills/diagram-design/scripts/` utilities load the appropriate convention file based on diagram type selection. Below is a minimal pattern showing how this works:

```python

# Import the appropriate convention file (e.g. for a Venn diagram)

from skills.diagram_design.references.type_venn import LAYOUT_CONVENTIONS


def render_venn(data):
    # Apply the layout conventions defined in the reference file

    diagram = Diagram()
    diagram.apply_layout(LAYOUT_CONVENTIONS)
    diagram.add_sets(data)
    return diagram.render()

```

The actual implementation resides in the scripts utilities; this snippet illustrates the pattern of loading type‑specific markdown content and using its defined constants for rendering.

---

## Complete File Inventory

| File | Diagram Type | Unique Features |
|:---|:---|:---|
| [`skills/diagram-design/references/type-venn.md`](https://github.com/cathrynlavery/diagram-design/blob/main/skills/diagram-design/references/type-venn.md) | Venn / set overlap | Circle limits, intersection labeling |
| [`skills/diagram-design/references/type-tree.md`](https://github.com/cathrynlavery/diagram-design/blob/main/skills/diagram-design/references/type-tree.md) | Hierarchical trees | Root placement, depth limits, branching rules |
| [`skills/diagram-design/references/type-flowchart.md`](https://github.com/cathrynlavery/diagram-design/blob/main/skills/diagram-design/references/type-flowchart.md) | Process flowcharts | Standard shapes, directional flow, decision logic |
| [`skills/diagram-design/references/type-high-level.md`](https://github.com/cathrynlavery/diagram-design/blob/main/skills/diagram-design/references/type-high-level.md) | High‑level bar charts | Colour override, bar ordering conventions |
| [`skills/diagram-design/references/type-data-flow.md`](https://github.com/cathrynlavery/diagram-design/blob/main/skills/diagram-design/references/type-data-flow.md) | Data‑flow diagrams | Row/column definitions, legend guidance |
| [`skills/diagram-design/references/type-architecture.md`](https://github.com/cathrynlavery/diagram-design/blob/main/skills/diagram-design/references/type-architecture.md) | Architecture diagrams | Layering rules, component grouping |
| [`skills/diagram-design/references/type-gantt.md`](https://github.com/cathrynlavery/diagram-design/blob/main/skills/diagram-design/references/type-gantt.md) | Gantt charts | Timeline handling, milestone markers |
| [`skills/diagram-design/references/type-scatter.md`](https://github.com/cathrynlavery/diagram-design/blob/main/skills/diagram-design/references/type-scatter.md) | Scatter plots | Axis labeling, colour‑mapping for data series |

Every `type‑*.md` file in `skills/diagram-design/references/` follows the same template described above, forming the **canonical design language** for the Diagram Design skill.

---

## Summary

- **Five core sections**: Header, Best for, Layout conventions, Anti‑patterns, Examples
- **Self‑contained authority**: Each file provides complete guidance without cross‑referencing
- **Consistent structure**: All 8+ diagram types follow identical organization
- **Implementation‑ready**: Conventions importable as code constants for automated rendering
- **Version‑controlled**: All files tracked in `cathrynlavery/diagram-design` repository

---

## Frequently Asked Questions

### What is the purpose of type‑specific convention files in Diagram Design?

They provide **authoritative, self‑contained style guides** for each supported diagram type. Rather than browsing scattered documentation, authors can open a single file to learn when to use a diagram type, how to structure it visually, what mistakes to avoid, and where to find reference implementations.

### How do I know which convention file to reference for my diagram?

Match your diagram's purpose to the file name: [`type-venn.md`](https://github.com/cathrynlavery/diagram-design/blob/main/type-venn.md) for set overlaps, [`type-tree.md`](https://github.com/cathrynlavery/diagram-design/blob/main/type-tree.md) for hierarchies, [`type-flowchart.md`](https://github.com/cathrynlavery/diagram-design/blob/main/type-flowchart.md) for processes, and so on. The "Best for" section in each file confirms whether it's appropriate for your use case.

### Can I override layout conventions from these files?

The [`type-high-level.md`](https://github.com/cathrynlavery/diagram-design/blob/main/type-high-level.md) file explicitly includes **colour‑override rules**, suggesting limited customization is supported. However, core structural conventions (shapes, ordering, anti‑patterns) should remain intact to preserve diagram readability and brand consistency.

### Where are these convention files located in the repository?

All files reside in `skills/diagram-design/references/` with the naming pattern `type-{diagram-type}.md`. The `skills/diagram-design/scripts/` directory contains utilities that import and apply these conventions during diagram generation.