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

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.

# 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)

---

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)

---

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)

---

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)

---

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)

---

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)

---

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:

# 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	Venn / set overlap	Circle limits, intersection labeling
skills/diagram-design/references/type-tree.md	Hierarchical trees	Root placement, depth limits, branching rules
skills/diagram-design/references/type-flowchart.md	Process flowcharts	Standard shapes, directional flow, decision logic
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	Data‑flow diagrams	Row/column definitions, legend guidance
skills/diagram-design/references/type-architecture.md	Architecture diagrams	Layering rules, component grouping
skills/diagram-design/references/type-gantt.md	Gantt charts	Timeline handling, milestone markers
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 for set overlaps, type-tree.md for hierarchies, 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 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.

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