What Is the Target Information Density for Diagram Design Diagrams?

Diagram Design defines a target information density of 4/10, serving as the baseline standard for creating diagrams that remain technically complete without requiring separate explanatory documentation.

The cathrynlavery/diagram-design repository establishes strict visual communication constraints to ensure technical illustrations remain accessible and maintainable. Understanding the target information density for Diagram Design diagrams helps contributors strike the precise balance between comprehensive detail and visual clarity, preventing cognitive overload while preserving technical accuracy.

Understanding the 4/10 Density Standard

The 4/10 density ratio represents a deliberate equilibrium in the Diagram Design methodology. Diagrams at this density level contain enough information to be technically complete and self-explanatory, yet remain sparse enough that readers do not need a separate guide to interpret them.

When diagrams exceed this target density threshold, the repository mandates architectural decomposition. Specifically, diagrams containing more than 9 nodes should be split into multiple smaller diagrams to maintain readability. This constraint prevents the common anti-pattern of "wall-of-text" technical diagrams that require hours of study to comprehend.

Where the Target Density Is Defined

The target information density constraint is codified in two primary locations within the repository, ensuring consistency across documentation and tooling.

Skill Manifest Configuration (SKILL.md)

The authoritative definition resides in skills/diagram-design/SKILL.md at line 46. According to the skill manifest, the explicit declaration "Target density: 4/10" establishes the constraint that all diagram generation must respect. This file serves as the source of truth for automated tooling and human contributors alike.

Repository Documentation (README.md)

The same target density specification appears in the repository's README.md at line 29, providing quick reference visibility for users browsing the project. This duplication ensures that the 4/10 standard is visible in both detailed technical specifications and high-level project documentation.

Enforcing Density Constraints Programmatically

Tools integrating with the Diagram Design specification can extract and enforce the target density value programmatically. The following Python snippet reads the SKILL.md file and parses the density constraint using regular expression matching:

import re, pathlib

skill_path = pathlib.Path(
    "/cache/repos/github.com/cathrynlavery/diagram-design/main/skills/diagram-design/SKILL.md"
)

text = skill_path.read_text()
match = re.search(r"Target density:\s*([0-9]+)/([0-9]+)", text)
if match:
    density = f"{match.group(1)}/{match.group(2)}"
    print("Diagram Design target density =", density)

This extraction pattern allows CI/CD pipelines, linting tools, and diagram editors to validate that generated diagrams comply with the 4/10 density budget before acceptance into the repository.

Summary

• Target density is 4/10 – The baseline standard defined in the Diagram Design specification.
• Defined in SKILL.md – Located at line 46 in skills/diagram-design/SKILL.md as the authoritative source.
• Documented in README.md – Repeated at line 29 in README.md for visibility.
• Split threshold exceeds 9 nodes – Diagrams denser than this must be decomposed into multiple illustrations.
• Programmatically accessible – The density value can be extracted via regex parsing for automated validation.

Frequently Asked Questions

What does the 4/10 density rating mean in Diagram Design?

The 4/10 rating indicates that diagrams should utilize approximately 40% of their potential information capacity. This specific ratio ensures diagrams remain technically substantive while avoiding the complexity that necessitates external documentation or walkthrough guides.

How many nodes before a diagram should be split?

Diagrams exceeding 9 nodes should be split into multiple diagrams according to the Diagram Design specification. This threshold serves as a practical implementation of the 4/10 density target, ensuring individual diagrams remain cognitively manageable.

Where is the target density defined in the repository?

The target density is defined in skills/diagram-design/SKILL.md at line 46 within the skill manifest, and reiterated in README.md at line 29. Both instances explicitly state "Target density: 4/10" to maintain consistency across documentation.

Can I enforce the density constraint programmatically?

Yes, the density value can be extracted programmatically by parsing SKILL.md using regular expressions to match the "Target density: X/10" pattern. This allows automated tools and CI pipelines to validate diagram compliance before merging contributions.

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