Diagram Design Grid System Dimensions: Complete Guide to Coordinates, Widths, and Gaps

Diagram Design enforces a strict 4 px grid system where all coordinates, widths, heights, and gaps must be multiples of 4 px, with specific allowed values defined in the Layout & Spacing specification.

The cathrynlavery/diagram-design repository implements a rigid geometric framework to ensure visual consistency across all diagram outputs. Understanding the specific dimensions of coordinates, widths, and gaps in the Diagram Design grid system is essential for creating compliant SVG layouts that pass automated verification. Every measurable property—from node positioning to internal padding—aligns to an invisible 4 px lattice defined in skills/diagram-design/SKILL.md.

The 4 Px Grid Foundation

At the core of the specification lies a 4 px base unit that governs every spatial calculation. The system requires that all numeric values for positioning and sizing end in 0, 2, 4, 6, or 8, ensuring they are divisible by 4. Any value violating this constraint triggers a grid violation during the pre-output checklist, forcing correction before the diagram can be finalized. This strict enforcement guarantees that elements align predictably without sub-pixel misalignment or visual inconsistencies.

Allowed Dimensions and Values

The Layout & Spacing section of SKILL.md (lines 52-60) enumerates the permitted ranges for each geometric property. Rather than allowing arbitrary multiples of 4, many categories restrict designers to specific curated values optimized for visual hierarchy.

Node Widths and Heights

Diagram nodes must conform to discrete dimensions chosen to maintain rhythm and scalability across layouts:

• Allowed values (px): 80, 96, 112, 120, 128, 140, 144, 160, 180, 200, 240, 320

These dimensions accommodate various content densities while ensuring that adjacent nodes align perfectly on the 4 px grid.

Coordinate Positioning

X and Y coordinates enjoy more flexibility than fixed dimensions, accepting any multiple of 4 within the canvas bounds. This allows precise positioning while maintaining grid alignment. For example, coordinates like x="120" and y="80" are valid, but x="125" would fail validation.

Gap Spacing Between Nodes

Inter-node spacing follows a specific vocabulary of distances that optimize readability without wasting space:

• Allowed gap values (px): 20, 24, 32, 40, 48

When calculating the position of a second node horizontally, the formula follows: first_node_x + first_node_width + gap_value. For instance, a node at x="0" with width 160 followed by a 24 px gap places the next node at x="184".

Typography and Internal Spacing

Text and padding dimensions adhere to the same modular scale:

• Font sizes: 8 → 40 px (increments of 4)
• Padding inside boxes: 8, 12, 16 px

These constraints ensure that text containers maintain consistent internal rhythm relative to their borders.

Border Radius Specifications

Corner rounding uses restricted values to prevent aesthetic fragmentation:

• Allowed radius (px): 4, 6, 8

Grid Compliance in Practice

The following examples demonstrate valid markup that satisfies the 4 px grid constraints defined in the repository specification.

Defining a compliant rectangular node:

<!-- Width = 160 px (allowed), x = 120 px, y = 80 px (both multiples of 4) -->
<rect x="120" y="80" width="160" height="80" rx="6" fill="#fff" stroke="#2d3142"/>

Positioning multiple nodes with standardized gaps:

<!-- First node at x = 0, second node starts at x = 0 + 160 (width) + 24 (gap) = 184 -->
<rect x="0"   y="40" width="160" height="80" fill="#fff"/>
<rect x="184" y="40" width="160" height="80" fill="#fff"/>

Both snippets respect the enumerated allowed values: the 160 px width appears in the node dimension list, the 24 px gap is permitted, and all coordinates are multiples of 4.

Verification and Validation

The repository provides automated tooling to enforce these dimensional constraints. The verify-geometry.py script located at scripts/verify-geometry.py parses generated SVGs to detect any values that violate the 4 px grid or use dimensions outside the allowed sets. Additionally, skills/diagram-design/scripts/self_check.py executes the complete pre-output checklist, including grid validation, ensuring that no non-compliant values reach final output. These scripts reference the canonical definitions in skills/diagram-design/SKILL.md to validate against the Layout & Spacing specification.

Summary

• Base unit: All measurements must align to a 4 px grid (divisible by 4).
• Fixed dimensions: Node widths and heights must be selected from the specific allowed list (80, 96, 112, 120, 128, 140, 144, 160, 180, 200, 240, 320 px).
• Flexible coordinates: X and Y positions accept any multiple of 4.
• Constrained gaps: Inter-node spacing must use 20, 24, 32, 40, or 48 px.
• Automated enforcement: Use verify-geometry.py and self_check.py to validate compliance before finalizing diagrams.

Frequently Asked Questions

What happens if I use a value that is not a multiple of 4?

Any value not divisible by 4 is considered a grid violation. The verify-geometry.py script will flag this error during validation, and the diagram will fail the pre-output checklist until corrected.

Can I use node dimensions outside the allowed list if they are multiples of 4?

No. While coordinates accept any multiple of 4, node widths and heights must conform to the specific enumerated values (80, 96, 112, 120, 128, 140, 144, 160, 180, 200, 240, 320). This restriction maintains visual consistency across different diagrams.

How do I calculate the correct position for a node after applying a gap?

Add the previous node's x-coordinate, its width, and the chosen gap value. For example, if Node A sits at x="0" with width="160", and you select a 32 px gap, Node B must be positioned at x="192" (0 + 160 + 32).

Why does the system enforce specific gap values rather than any multiple of 4?

The restricted gap set (20, 24, 32, 40, 48 px) establishes consistent spatial relationships that have been tested for optimal visual flow. This limitation prevents arbitrary spacing that could disrupt the rhythmic consistency of complex diagrams.

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