Blueprint v4.0 & v5.0 semantic swap

September 23, 2021

Up until today, the major version plan for Blueprint was:

• v4.0 includes JS API and library changes, most notably compatibility with React strict mode (and therefore React 17) and upgrading to Popper.js v2
• v5.0 includes color changes with a modern color palette which improves component accessibility to pass WCAG 2.0 AA requirements

We’ve been putting a lot of work into the v4.0 migration across our FE code bases at Palantir over the past few weeks/months but it’s taking longer than we’d like. At this rate, with some new issues raised by additional components which will need a popover migration step (Select, DateInput, etc.), we may not be able to migrate fully by the end of October.

During this v4.0 migration, we’ve also been working on “v5.0” colors in parallel, and it’s looking like they will be ready for production pretty soon (in a week or two) in time for our final round of accessibility certification testing (mid-October).

Although we have designed a mechanism to apply the “v5.0“ colors on top of the existing v3.x packages (see blueprint-modern.scss), we now propose another solution which avoids this kind of “soft fork” of Blueprint’s CSS:

Swap the set of changes going into the Blueprint v4.0 and v5.0 releases.

This is only a semantic change in what “v4” and “v5” mean for Blueprint, and we don’t lose any work we’ve done up to this point. The major version plan now becomes:

• v4.0 includes color changes with the modern color palette.
• v5.0 includes all the API breaks which originally planned for v4.0 as outlined in Blueprint 4.0 Overview (edit: this content has moved to Blueprint 5.0 Overview).

The advantages here are that applications can take the new colors without relying on a “forked” version of the CSS.

Mechanically, in the palantir/blueprint repo, this new plan will involve:

• Renaming next branch to v5
• Branching off develop to create a new next branch
• On next:
  • Move the blueprint-modern.scss code into the proper/normal Sass source files, integrating them into the main code base rather than leaving them as an add-on
  • Copy / cherry-pick / apply any other breaking changes from v5 which we want to squeeze into this v4 release, while we’re here
    • Icon tooling breaking changes could go here, so that we quickly restore support for the icon font API
    • “bp3-” class prefix changes to “bp4-”
• On develop:
  • Continue to merge a11y enhancements and cut a release or two
• On v5:
  • Nothing... until next merges → develop and v4.0 stable is out in the wild... at which point this becomes the new next branch

What does this mean for Blueprint v5.0?

In general, one of the takeaways from this “v4.0” migration is that we should likely make a smaller set of changes in a major version of Blueprint, given the amount of complexity involved in the migrations across our large FE code bases. To that end, we may see a smaller set of breaking changes in v5.0, with a v6.0 release coming soon after, etc.