Why Does the Design System Require All Coordinates to Be Divisible by 4?

The diagram-design system requires all coordinates to be divisible by 4 to ensure pixel-perfect rendering, eliminate floating-point rounding errors in connector geometry, and guarantee deterministic, reproducible SVG output across all display densities.

The cathrynlavery/diagram-design repository enforces this grid alignment as a foundational constraint. According to the source code, every x and y coordinate must land on a 4-pixel lattice—a rule documented in skills/diagram-design/SKILL.md and automatically validated by scripts/verify-geometry.py. This article explains the technical rationale behind this requirement and how it shapes the system's architecture.

Pixel-Perfect Rendering on All Displays

SVGs rasterize differently across device-pixel ratios. A coordinate like x=5 becomes a sub-pixel position on a 2× Retina display, triggering antialiasing artifacts that blur edges.

By forcing coordinates to multiples of 4, the system aligns with common display densities:

• 1× displays – 4 px maps to exactly 4 physical pixels
• 2× displays – 4 px maps to 8 physical pixels
• 4× displays – 4 px maps to 16 physical pixels

This alignment eliminates sub-pixel positioning entirely. Lines, shapes, and rounded connectors render sharply without blur, regardless of the output device.

Consistent Connector Geometry

Rounded right-angle connectors in this system use fixed radii—typically r=8 or r=6 for tight layouts. When endpoints sit on a 4-pixel grid, elbow-path calculations produce clean integer coordinates.

The quarter-arc geometry used for these connectors relies on precise tangent points. Floating-point coordinates would introduce rounding errors that distort the connector shape. The rule table in skills/diagram-design/SKILL.md explicitly documents this relationship: "x / y coordinates | multiples of 4" appears alongside the connector radius requirements【/skills/diagram-design/SKILL.md†L347-L354】.

Automated Validation with verify-geometry.py

The repository includes a dedicated geometry verifier that runs during the build process. The scripts/verify-geometry.py module implements the core validation logic:

def is_grid_aligned(value: int) -> bool:
    return value % 4 == 0

This utility checks that every coordinate ends in 0, 4, 8, or 12. The verification step runs automatically, catching alignment violations before they reach production.

Deterministic, Reproducible Output

The diagram-design system is parametric—identical input data must always generate identical SVG output. Floating-point coordinates introduce nondeterministic rounding variations across:

• Different Python versions
• Alternative SVG rendering engines
• Build platforms (CI vs. local development)

By restricting coordinates to a 4-pixel lattice, the system removes these variations entirely. The rendering becomes reproducible across builds and platforms, a property essential for version-controlled diagrams.

Architecture Decision Record: ADR 0005

The constraint is formally justified in docs/adr/0005-label-geometry-is-verified.md. This Architecture Decision Record explains that grid alignment is enforced automatically during verification and documents the rationale for choosing 4 px as the base unit【/docs/adr/0005-label-geometry-is-verified.md†L16-L23】.

The ADR process indicates this was an intentional design choice—not an arbitrary restriction but a trade-off that prioritizes visual consistency and build reliability over maximum layout flexibility.

Practical Implementation

Diagram generators in the codebase assert alignment before placing elements:

def place_node(cx: int, cy: int, label: str) -> dict:
    assert is_grid_aligned(cx) and is_grid_aligned(cy), "Coordinates must be multiples of 4"
    return {
        "type": "node",
        "cx": cx,
        "cy": cy,
        "label": label,
    }

Verification tests confirm the constraint behavior:

# Quick sanity test

for coord in [0, 4, 8, 12, 16]:
    assert is_grid_aligned(coord)   # passes

assert not is_grid_aligned(5)       # fails – would be caught by the verifier

Summary

• Pixel alignment – 4 px grid prevents sub-pixel artifacts on all display densities
• Connector precision – Fixed radii require integer coordinates for clean quarter-arc geometry
• Automated enforcement – verify-geometry.py validates every coordinate at build time
• Determinism – Lattice-based coordinates guarantee reproducible SVG output
• Documentation – Constraint formally recorded in SKILL.md and ADR 0005

Frequently Asked Questions

What happens if a coordinate isn't divisible by 4?

The build fails. scripts/verify-geometry.py raises an assertion error when it encounters coordinates ending in values other than 0, 4, 8, or 12. This prevents misaligned diagrams from reaching production.

Why 4 pixels instead of 2 or 8?

As documented in SKILL.md, 4 px balances connector radius flexibility (supporting both r=8 and r=6) with sufficient granularity for detailed layouts. Larger grids would restrict positioning; smaller grids wouldn't guarantee clean integer math for the specified radii.

Does this constraint affect performance?

Indirectly, yes. By eliminating floating-point calculations from the rendering path, the system reduces computational overhead. More significantly, it prevents the performance cost of regenerating diagrams due to nondeterministic output differences.

Can the grid size be changed in a fork?

Technically possible, but architecturally inadvisable. The connector geometry formulas, verification logic, and all existing diagrams are calibrated for 4 px. Changing the base unit would require updating SKILL.md, verify-geometry.py, and every coordinate in the diagram library.

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