What Is the 4px Grid Rule in Diagram Design?

The 4px grid rule in Diagram Design is a hard constraint requiring all geometric properties—coordinates, sizes, margins, and gutters—to be multiples of 4 pixels, while explicitly exempting data-driven values like bar heights or bubble positions to preserve both visual rhythm and numerical accuracy.

The Diagram Design system, maintained in the cathrynlavery/diagram-design repository, enforces this rigid grid to eliminate pixel-level inconsistencies across diverse visualization types. By snapping static layout elements to a 4px baseline, the system ensures diagrams remain visually cohesive regardless of scale or complexity.

Core Principles of the 4px Grid System

The 4px grid rule functions as a house rhythm that governs every non-data property of a diagram. According to skills/diagram-design/references/style-guide.md, the rule declares that "every coord, size, and gap is divisible by 4 (hard rule)".

Coordinates and Positioning

All x and y positions must resolve to multiples of 4px. This constraint applies to the origin points of cells, nodes, axes, and tick marks. In skills/diagram-design/references/type-scatter.md, the specification notes that axis rules and tick baselines use the 4px grid to maintain alignment across chart instances.

Dimensions and Spacing

Widths, heights, margins, paddings, and gutters must also conform to 4px increments. The system enforces fixed 4px gutters between adjacent elements—for example, treemap cells specifically require a 4px gutter to ensure clear separation without breaking the grid cadence as documented in skills/diagram-design/references/type-treemap.md.

The Data Exemption

Any property that directly encodes a data value remains exempt from snapping. This includes:

• The height of a bar in a bar chart
• The radius of a bubble in a scatter plot
• The y-position of a line-chart point

This exemption prevents the grid from distorting the visual representation of numerical values, ensuring geometric accuracy for data while maintaining structural alignment for decorative elements.

Application Across Diagram Types

The 4px grid manifests differently across visualization primitives, with each diagram type implementing the rule according to its specific geometry requirements.

Treemaps

As specified in skills/diagram-design/references/type-treemap.md, treemap cells snap to the nearest 4px grid line with a mandatory 4px gutter between adjacent cells. The verification script scripts/verify-treemap.py enforces these constraints, ensuring that rounding errors remain within a few percent of the true share while maintaining grid compliance.

Scatter Charts

The skills/diagram-design/references/type-scatter.md file specifies that axis rules and tick baselines align to the 4px grid. Static decorative elements like gridlines render at 4px intervals (e.g., y-coordinates at 416, 420, 424), while data points plot at exact calculated positions.

Sankey Diagrams

In flow-based visualizations documented in skills/diagram-design/references/type-sankey.md, node heights round to the nearest 4px. This ensures that flow bands align cleanly with node edges while preserving the visual integrity of the data flow.

Line Charts

The skills/diagram-design/references/type-line.md specification mandates that baseline rules and inter-element gutters follow the 4px grid. The x-axis baseline typically sits at a y-coordinate divisible by 4 (such as 420px), establishing a consistent foundation for data plotting.

Implementation Examples

The following JSON snippet demonstrates a treemap configuration respecting the 4px grid for all layout properties:

{
  "type": "treemap",
  "layout": {
    "x": 0,
    "y": 0,
    "width": 800,
    "height": 600
  },
  "cells": [
    {
      "label": "A",
      "share": 0.40,
      "x": 0,
      "y": 0,
      "w": 384,
      "h": 600
    },
    {
      "label": "B",
      "share": 0.60,
      "x": 388,
      "y": 0,
      "w": 408,
      "h": 600
    }
  ]
}

Note that x: 388 represents the previous cell width (384) plus the mandatory 4px gutter. Both cell widths are multiples of 4 (384 = 4×96, 408 = 4×102).

This SVG example illustrates grid alignment for static chart elements while preserving data accuracy:

<svg viewBox="0 0 1000 500">
  <!-- X-axis rule at y = 420 (divisible by 4) -->
  <line x1="80" y1="420" x2="960" y2="420"
        stroke="rgba(45,49,66,0.25)" stroke-width="1"/>
  <!-- Gridlines at 4px intervals -->
  <line x1="80" y1="416" x2="960" y2="416"
        stroke="rgba(45,49,66,0.08)" stroke-width="0.8"/>
  <!-- Data point at exact data-driven position (not snapped) -->
  <circle cx="500" cy="350" r="6" fill="#f08a59"/>
</svg>

The axis rule sits at y="420" (4×105) and gridlines step in 4px increments, while the data point's cy="350" reflects its actual value without grid snapping.

Verification and Quality Assurance

The repository includes automated verification scripts that enforce grid compliance. The scripts/verify-treemap.py script validates that every cell respects the 4px grid boundaries and that the sum of cell areas remains within tolerance of the specified shares. This automated checking prevents manual layout errors from reaching production diagrams.

Summary

• The 4px grid rule mandates that all coordinates, sizes, margins, and gutters in Diagram Design be multiples of 4 pixels.
• Data-driven values (bar heights, bubble positions, line points) remain exempt to prevent visual distortion of numerical information.
• Fixed 4px gutters separate adjacent elements like treemap cells to maintain consistent spacing.
• Source files including SKILL.md, style-guide.md, and type-specific references (type-treemap.md, type-scatter.md, type-sankey.md) collectively define and enforce this standard.
• Verification scripts automate grid compliance checking during the build process.

Frequently Asked Questions

What specific properties must follow the 4px grid rule?

The rule applies to all static geometric properties including x/y coordinates, element widths and heights, margins, paddings, and gutters. According to skills/diagram-design/SKILL.md section "### 4 px grid", these properties must be divisible by 4 to maintain the system's visual rhythm.

Are data values ever snapped to the 4px grid?

No. Any property encoding actual data—such as the height of a bar representing a numerical value, the radius of a data bubble, or the position of a line-chart point—remains unsnapped. This exemption, documented across multiple type reference files, ensures the visualization remains faithful to the underlying dataset.

How is the 4px grid rule enforced in the codebase?

Enforcement occurs through documentation and automation. The style guide declares the hard rule in style-guide.md, while scripts like scripts/verify-treemap.py programmatically check that generated diagrams adhere to the grid constraints, flagging any coordinate or dimension that violates the 4px multiple requirement.

Why was 4px chosen as the base unit rather than 8px or another value?

While the documentation does not explicitly state the rationale for selecting 4px over larger units, the choice provides sufficient granularity for detailed layouts while remaining large enough to create visible alignment patterns. The 4px unit strikes a balance between flexibility and the rigid structure needed for professional data visualization consistency.

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