Spacing System Migration: 10px to 4px

Overview

Blueprint is transitioning from a 10px-based grid system ($pt-grid-size) to a 4px-based spacing system ($pt-spacing). This change provides more flexible spacing options and improves consistency across components.

Why This Change?

Current Pain Points

The 10px base unit creates several challenges for developers and designers. When working with small spacing values, developers must make arbitrary choices between inconsistent values like 3px, 5px, or 7px, since 10px doesn't provide clean subdivisions. For example, dividing 10px by 4 yields 2.5px, which forces rounding decisions that accumulate into visual inconsistencies across an application.

Additionally, the larger base unit limits precision when creating visual hierarchy. Dense information displays and complex interfaces require fine-grained control over spacing that a 10px system cannot provide without resorting to arbitrary pixel values. From an accessibility perspective, the 10px base also creates challenges since browsers use 16px as the default font size (1rem). While 10px doesn't align cleanly with this standard, 4px divides evenly (16px = 4 × 4px).

Benefits of 4px Grid

The 4px grid system addresses these limitations through predictable, mathematically clean values. The spacing scale (4, 8, 12, 16, 20, 24, 32, 48) follows simple multiples that are easy to remember and apply consistently. This finer granularity provides better precision for tight layouts without requiring arbitrary pixel values, while base-2 friendly calculations simplify responsive design and scaling operations. Most importantly, having a consistent set of spacing values eliminates one-off decisions, resulting in more predictable and maintainable layouts.

Impact on Applications

Visual Changes

Most applications will experience minimal visual changes. Components currently using 10px and 20px spacing will remain unchanged in the initial migration. Where changes do occur, they will be subtle: 5px values will become 4px, and 15px will become 16px. These minor adjustments will improve visual consistency by eliminating arbitrary spacing values that don't fit within a clear system.

Migration Path

This migration has been designed to minimize disruption. The $pt-grid-size variable will remain available for backward compatibility, though it is now deprecated and will be removed in a future major release. For new component development, consumers of Blueprint should use the $pt-spacing variable to ensure consistency with the new system.

Example Conversions

// Old approach with 10px base
padding: $pt-grid-size * 0.5;  // 5px
margin: $pt-grid-size * 1.5;   // 15px

// New approach with 4px base
padding: $pt-spacing;           // 4px
margin: $pt-spacing * 4;        // 16px

Timeline

The rollout follows a phased approach. In August 2025, the $pt-spacing variable will be introduced and $pt-grid-size will be marked as deprecated. September 2025 will focus on design validation, refinement, and the migration of existing Blueprint components to the new system.

References

• Migrate $pt-grid-size values to $pt-spacing [#7541](https://github.com/palantir/blueprint/pull/7541)
• Add docs around $pt-spacing and note deprecation of $pt-grid-size [#7548](https://github.com/palantir/blueprint/pull/7548)