V2 Upgrade Guide
Framework v2 builds on everything you've already created, enriching your work while keeping most of your existing logic functional. The only two areas that require your attention are borders and clamping, and both can be addressed with just a few quick changes.
Borders
Initially, the border utility was designed to work in a 1-bit space on white backgrounds.
We’ve expanded it to adapt across 1, 2, and 4-bit spaces, covering the full grayscale spectrum and working on both light and dark backgrounds. Borders are now versatile and support a range of devices with different display capabilities.
Search your markup for a class name like border--h-5 and re-evaluate the intensity using the updated
Border
Border
Apply border patterns that create the illusion of different border intensities
The Border system creates the illusion of grayscale borders through carefully designed dither patterns. When rendered on 1-bit displays, these patterns create varying border intensities using alternating black and white pixels.
scale. You may choose a different level (e.g., border--h-3) to match the intended appearance.
Clamping
Previously, Title Title Style headings with consistent typography The Title system provides consistent text headings with different size variants. It helps maintain visual hierarchy and readability throughout the interface. , Label Label Create clear labels for unified content identification The Label system provides various styles for displaying text labels, with options for different visual treatments and sizes. The filled variant uses black (darkest) background; label--primary, label--success, etc. use semantic colors. Labels can be used to highlight text, show status, or create visual hierarchy in your interface. , and Description Description Format descriptive text with standardized styles The Description component provides a standardized way to display descriptive text content with consistent styling. were clamped to a single line by default.
We’ve rebuilt the clamp engine in JavaScript at the DOM level, making it more robust and fully integrated with other modulation utilities like
Overflow
Overflow
Handle column items overflow
The Overflow engine automatically lays out items into up to N columns and adds an “and X more” label when content exceeds the available height. It also applies text clamping per-column width and handles grouped headers without leaving orphaned headings.
. Clamping is no longer enforced automatically - the content is now displayed in its entirety by default. You decide whether clamping is needed and set sensible limits. The legacy clamp--N classes remain supported for compatibility, but the new data-clamp attribute is the preferred approach going forward.
Search your markup for parts like <span class="label"> and add the clamping attribute <span class="label" data-clamp="2"> (or whichever clamp value fits your layout).
Troubleshooting
Framework v2 is also more precise than earlier versions, which may expose issues if your markup doesn't follow intended usage. If you run into problems beyond borders or clamping, check the V2 Troubleshooting V2 Troubleshooting Resolve issues surfaced by v2’s stricter markup requirements When upgrading to v2, validate markup against intended usage. This guide lists common issues surfaced by v2’s more precise behavior. for solutions.
Next Steps
Once you've updated borders and clamping, your project is ready for Framework v2. From here, head to the V2 Enhancement Guide V2 Enhancement Guide Device, bit-depth, and orientation-responsive patterns for plugins This guide explains how to enhance plugins with Framework v2.0’s expanded responsive capabilities. For a quick migration checklist, see the Upgrade Guide. to explore new utilities, components, and techniques for building even more capable interfaces.