# 4px Grid System Values and Constraints in Diagram-Design

> Explore the 4px grid system in Diagram-Design. Understand typical values for fonts, nodes, gaps, and padding, along with key constraints to ensure visual consistency.

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

---

**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`](https://github.com/cathrynlavery/diagram-design/blob/main/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`](https://github.com/cathrynlavery/diagram-design/blob/main/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`](https://github.com/cathrynlavery/diagram-design/blob/main/type-architecture.md) and [`type-sequence.md`](https://github.com/cathrynlavery/diagram-design/blob/main/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`](https://github.com/cathrynlavery/diagram-design/blob/main/scripts/verify-geometry.py) that scans generated SVGs for grid compliance:

```bash
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

```html
<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

```html
<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`](https://github.com/cathrynlavery/diagram-design/blob/main/skills/diagram-design/SKILL.md) | Core grid documentation and value tables |
| [`scripts/verify-geometry.py`](https://github.com/cathrynlavery/diagram-design/blob/main/scripts/verify-geometry.py) | Automated compliance validation |
| `skills/diagram-design/references/type-*.md` | Type-specific layout guides |
| [`assets/template.html`](https://github.com/cathrynlavery/diagram-design/blob/main/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`](https://github.com/cathrynlavery/diagram-design/blob/main/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`](https://github.com/cathrynlavery/diagram-design/blob/main/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`](https://github.com/cathrynlavery/diagram-design/blob/main/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.