Understanding the 4px Grid System in Diagram-Design: Coordinate Alignment Explained

The diagram-design repository enforces a strict 4px grid where every geometric coordinate, dimension, and spacing value must be a multiple of four to ensure pixel-perfect alignment across all diagram variants.

All visual elements in the cathrynlavery/diagram-design codebase are constrained by a unified 4px grid system that governs typography, node positioning, and layout geometry. This constraint guarantees that treemaps, scatter plots, sankey diagrams, and other visualizations share a consistent visual rhythm while rendering crisply on both standard and high-DPI displays.

What Is the 4px Grid System?

The 4px grid is the foundational layout rule mandating that all numeric values influencing diagram geometry—font sizes, paddings, node dimensions, gaps, and explicit x/y coordinates—must be divisible by 4. This creates a shared raster where every element lands on predictable intervals, making outputs comparable across diagram types and resolutions.

Core Principles of the 4px Grid

According to the style guide in skills/diagram-design/SKILL.md, the grid operates on three fundamental constraints:

• Base unit multiplication: Every coordinate is expressed as 4 × n (e.g., 0, 4, 8, 12, 16)
• Mandatory snapping: Layout algorithms round computed positions to the nearest multiple of 4 before rendering
• Build-time validation: Verification scripts reject any SVG containing off-grid geometry

The SKILL.md file explicitly states that any coordinate not divisible by 4 must be corrected, providing an exhaustive table of allowed values in the "### 4px grid" section.

Why 4px? The Design Rationale

The 4px increment was selected to balance flexibility with precision:

• Pixel-perfect rendering: Multiples of 4 align cleanly on both 1x and 2x (Retina) displays without sub-pixel anti-aliasing artifacts
• Mathematical simplicity: Rounding data-driven dimensions (such as treemap cell heights) preserves fidelity to source values while maintaining grid adherence
• Systemic consistency: A single spacing language allows designers and automation scripts to predict spatial relationships across all diagram variants

How Coordinate Alignment Works in Diagram-Design

Coordinate alignment in the repository follows a structured pipeline from calculation to validation, ensuring no off-grid elements reach production builds.

Base Unit and Snapping Logic

The system treats 4px as the atomic unit. When a layout algorithm calculates a node position or cell boundary, it applies a snapping function to coerce the value to the grid:

# Python helper: snap any coordinate to the nearest 4px grid

def snap_to_grid(value: float) -> int:
    """Round to the nearest multiple of 4."""
    return round(value / 4) * 4

# Example usage

x = snap_to_grid(83.7)   # → 84

y = snap_to_grid(127.2)  # → 128

For SVG output, this means attributes like x, y, width, height, and rx (corner radius) must resolve to multiples of 4:

<!-- Example: a node positioned on the 4px grid -->
<svg viewBox="0 0 400 300" role="img" aria-labelledby="title desc">
  <title id="title">Sample Node</title>
  <desc id="desc">A node placed on a 4-pixel grid</desc>

  <!-- x=80, y=120 are both multiples of 4 -->
  <rect x="80" y="120" width="96" height="96"
        fill="var(--paper)" stroke="var(--ink)" stroke-width="0.8"
        rx="4"/>   <!-- radius = 4px (grid-aligned) -->

  <!-- Text positioned with 4-pixel padding -->
  <text x="128" y="176" font-size="12"
        font-family="Geist, sans-serif" text-anchor="middle"
        fill="var(--ink)">Node</text>
</svg>

Grid Enforcement in Verification Scripts

The repository enforces grid compliance through automated verification. Two critical scripts validate geometry at build time:

• scripts/verify-treemap.py: Performs grid-residue checks on treemap cell edges, failing the build if any cell boundary is not divisible by 4
• scripts/verify-geometry.py: General geometry validator that ensures all coordinates in generated SVGs obey the 4px constraint

These scripts reference the treemap type specification in skills/diagram-design/references/type-treemap.md, which documents that "cell edges snap to the grid … with a 4px gutter" to maintain consistent spacing between data regions.

Exclusions and Edge Cases

While geometric coordinates strictly adhere to the grid, certain aesthetic properties are deliberately exempt because they do not affect pixel alignment:

• Stroke widths: Values like stroke-width="0.8" are allowed for hairline borders
• Opacity values: Alpha channels (e.g., opacity="0.5") fall outside the grid system
• Pattern definitions: The 22×22 dot-pattern used for specific textures is exempt from the 4px rule

These exemptions are documented in the repository's design guidelines to prevent unnecessary constraints on visual styling that does not impact layout geometry.

Summary

• The 4px grid system in cathrynlavery/diagram-design mandates that all coordinates, dimensions, and spacing values must be multiples of 4

• Coordinate alignment relies on base-unit snapping (4 × n) implemented in layout algorithms and validated by snap_to_grid logic

• Build-time enforcement occurs through verify-treemap.py and verify-geometry.py, which reject off-grid SVG elements

• Key documentation resides in SKILL.md under the "### 4px grid" section and in type-specific references like type-treemap.md

• Exemptions include stroke widths, opacity values, and specific pattern dimensions that do not affect geometric alignment

Frequently Asked Questions

Why does diagram-design use a 4px grid instead of 8px?

The 4px grid provides finer granularity than 8px while maintaining the same mathematical benefits for high-DPI screens. According to the repository's design rationale, 4px offers sufficient flexibility for data-driven layouts (like treemap cell sizing) without sacrificing the crisp alignment that larger increments provide. The smaller unit allows more precise representation of data values while keeping the visual system consistent.

How do I verify my SVG coordinates comply with the 4px grid?

Run the repository's verification scripts against your generated files. Execute python scripts/verify-geometry.py to check general coordinate compliance, or python scripts/verify-treemap.py for treemap-specific validation. These scripts parse SVG attributes and fail if they detect values not divisible by 4, indicating which elements require adjustment.

What happens if coordinates are not divisible by 4?

The build system will reject the output. Both verify-treemap.py and verify-geometry.py are configured to fail when encountering off-grid coordinates, preventing non-compliant diagrams from entering the codebase. You must round the offending values to the nearest multiple of 4 using the snap_to_grid logic or manual correction before the build will pass.

Are there any exceptions to the 4px grid rule?

Yes, but only for properties that do not influence geometric alignment. Stroke widths (e.g., stroke-width="0.8"), opacity values, and the 22×22 dot-pattern are exempt from the grid requirement. However, all positional attributes (x, y), dimensions (width, height), and spacing values (padding, gutter, margin) must strictly adhere to multiples of 4 as defined in skills/diagram-design/SKILL.md.

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