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

> Discover why our design system mandates coordinates divisible by 4 for pixel-perfect rendering, error-free geometry, and consistent SVG output. Learn more.

- Repository: [Cathryn Lavery/diagram-design](https://github.com/cathrynlavery/diagram-design)
- Tags: internals
- Published: 2026-08-14

---

**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`](https://github.com/cathrynlavery/diagram-design/blob/main/skills/diagram-design/SKILL.md) and automatically validated by [`scripts/verify-geometry.py`](https://github.com/cathrynlavery/diagram-design/blob/main/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`](https://github.com/cathrynlavery/diagram-design/blob/main/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`](https://github.com/cathrynlavery/diagram-design/blob/main/scripts/verify-geometry.py) module implements the core validation logic:

```python
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`](https://github.com/cathrynlavery/diagram-design/blob/main/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:

```python
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:

```python

# 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`](https://github.com/cathrynlavery/diagram-design/blob/main/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`](https://github.com/cathrynlavery/diagram-design/blob/main/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`](https://github.com/cathrynlavery/diagram-design/blob/main/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`](https://github.com/cathrynlavery/diagram-design/blob/main/SKILL.md), [`verify-geometry.py`](https://github.com/cathrynlavery/diagram-design/blob/main/verify-geometry.py), and every coordinate in the diagram library.