4px Grid System Values and Constraints in Diagram-Design

The Diagram-Design system enforces strict 4px grid alignment for all dimensions, with specific allowed values for font sizes (8–40px), node sizes (80–320px), gaps (20–48px), padding (8–16px), and border radii (4–8px), while exempting stroke widths, opacity, and the 22×22 dot pattern.

The 4px grid system is the foundational constraint that governs every visual element in the Diagram-Design repository. This editorial design system, located at cathrynlavery/diagram-design, uses the grid to ensure consistent typography, spacing, and node geometry across all diagram types. Understanding these constraints is essential for creating valid diagrams that pass automated verification.

Core Constraint: Divisibility by 4

Every numeric value in the system must be a multiple of 4. This rule applies universally to spatial attributes and is validated by the verify-geometry.py script.

What the Grid Governs

• x/y coordinates — all positioning values
• Node width and height — dimensional bounds
• Inter-node gaps — spacing between elements
• Internal padding — inset spacing within boxes
• Border radii — corner rounding values
• Font sizes — typographic scale

Quick Validation Rule

Coordinates ending in 1, 2, 3, 5, 6, 7, 9 are illegal and trigger verification failures. Valid coordinates always end in 0, 4, 8.

Allowed Discrete Values by Category

The reference table in SKILL.md (lines 44-50) defines the hard-coded value sets for each attribute:

Category	Allowed Values
Font sizes	8, 12, 16, 20, 24, 28, 32, 40 px
Node width / height	80, 96, 112, 120, 128, 140, 144, 160, 180, 200, 240, 320 px
x / y coordinates	Any multiple of 4 px
Gap between nodes	20, 24, 32, 40, 48 px
Padding inside boxes	8, 12, 16 px
Border radius	4, 6, 8 px

These values appear consistently across type reference files including type-architecture.md and type-sequence.md.

Exemptions to the 4px Rule

Three categories break the divisibility constraint intentionally:

• Stroke widths — values like 0.8, 1, 1.2 px for fine line control
• Opacity values — fractional percentages (e.g., 0.6, 0.8)
• 22 × 22 dot pattern — fixed decorative element size

These exemptions exist where sub-4px precision improves visual clarity without disrupting spatial rhythm.

Verification and Enforcement

The repository ships an automated validation tool at scripts/verify-geometry.py that scans generated SVGs for grid compliance:

python3 scripts/verify-geometry.py path/to/generated.html

This script performs deterministic checks on:

• Non-grid-aligned coordinates
• Illegal font sizes outside the allowed set
• Spacing errors in gaps and padding

Running verification before publication ensures every diagram maintains editorial consistency.

Practical Implementation Examples

Grid-Aligned Node Box

<svg width="400" height="200" role="img" aria-labelledby="example-title example-desc">
  <title id="example-title">Example Node</title>
  <desc id="example-desc">A single box demonstrating grid-aligned dimensions.</desc>

  <!-- 4px-aligned rectangle: width=120px, height=80px -->
  <rect x="40" y="40" width="120" height="80"
        rx="6" fill="#ffffff" stroke="#2d3142" stroke-width="1"/>
  
  <!-- 12px font from allowed set -->
  <text x="100" y="80" text-anchor="middle"
        font-family="Geist, sans-serif" font-size="12" font-weight="600"
        fill="#2d3142">Node</text>
</svg>

Key compliance points:

• x=40, y=40 — multiples of 4
• width=120, height=80 — from allowed node dimensions
• font-size="12" — valid typographic scale value
• rx="6" — permitted border radius

Inter-Node Gap Implementation

<svg width="800" height="200" role="img" aria-labelledby="gap-title gap-desc">
  <title id="gap-title">Two Nodes with 24px Gap</title>
  <desc id="gap-desc">Two adjacent boxes separated by a 24-px gap.</desc>

  <!-- First node: x=40, width=160, right edge at 200 -->
  <rect x="40" y="60" width="160" height="80"
        rx="6" fill="#ffffff" stroke="#2d3142"/>

  <!-- Second node: x=224 = 200 + 24px gap -->
  <rect x="224" y="60" width="160" height="80"
        rx="6" fill="#ffffff" stroke="#2d3142"/>
</svg>

The second node's x="224" position demonstrates proper gap calculation: first node's right edge (200) plus the allowed 24 px spacing value.

Design System Benefits

The 4px grid delivers three core advantages according to the Diagram-Design source:

• Visual rhythm — consistent spacing creates instantly recognizable diagrams with clean editorial aesthetics
• Predictable scaling — proportional relationships preserve integrity across output formats (slides, social cards, print) without fractional pixel artifacts
• Automation compatibility — deterministic validation enables tooling to detect and flag violations programmatically

Key Source Files

File	Purpose
skills/diagram-design/SKILL.md	Core grid documentation and value tables
scripts/verify-geometry.py	Automated compliance validation
skills/diagram-design/references/type-*.md	Type-specific layout guides
assets/template.html	Minimal compliant diagram template

Summary

• All dimensions must be multiples of 4 except stroke widths, opacity, and the 22×22 dot pattern
• Discrete allowed values are hard-coded for fonts (8–40px), nodes (80–320px), gaps (20–48px), padding (8–16px), and radii (4–8px)
• Illegal coordinate endings (1, 2, 3, 5, 6, 7, 9) trigger verification failures
• Automated enforcement via verify-geometry.py ensures compliance before publication
• Design benefits include visual consistency, clean scaling, and tooling integration

Frequently Asked Questions

What happens if I use a value that's not divisible by 4?

The verify-geometry.py script will flag the violation and output a specific error indicating the non-compliant coordinate or dimension. You must correct the value to the nearest valid multiple or allowed discrete value before the diagram passes validation.

Can I create custom node sizes outside the allowed list?

No. The node dimension values in SKILL.md are exhaustive. While x/y coordinates accept any multiple of 4, width and height must match one of the twelve specified values (80, 96, 112, 120, 128, 140, 144, 160, 180, 200, 240, 320 px).

Why is border radius 6px allowed when it's not divisible by 4?

The 6px radius is a deliberate exemption for visual refinement. The rx/ry attributes accept 4, 6, 8 px specifically—6px provides intermediate rounding that harmonizes with the grid without breaking perceived alignment.

How do I calculate valid positions for multiple nodes?

Sum the originating node's x-coordinate plus its width, then add an allowed gap value (20, 24, 32, 40, or 48 px). The result must end in 0, 4, or 8. For example: node at x=40 with width=160 has right edge at 200; adding 24 px gap yields valid x=224 for the next node.

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