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
Draw a horizontal or vertical rule on any element with the border--h and border--v utilities, named on the same 10 to 75 shade scale as backgrounds. On 1-bit displays a step renders as a dither pattern of black and white pixels, so a rule can read as gray. 4-bit and full-color screens draw all 14 steps; the other rails pair them onto seven levels.
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 Headings for a plugin screen. Five size variants from small to xxlarge, each with responsive prefixes for breakpoints and orientation. , Label Label Create clear labels for unified content identification Short captions and status chips for a plugin screen. Five sizes plus style variants (filled, outline, underline, inverted) and semantic variants such as label--success and label--error. , and Description Description Format descriptive text with standardized styles Supporting body text, sized to sit under a Title or a Value rather than compete with it. Four size variants from base to xxlarge, with wrapping or line clamping for longer copy. 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.