V3.3 Upgrade Guide
Framework 3.3 is fully backward compatible with 3.0, 3.1, and 3.2. Existing class names render unchanged, and every new feature (themes, the paint API, adaptive charts, maps, and icons) is opt-in. This guide lists the few things worth reviewing when you upgrade.
From Framework 3.0 or 3.1
On the TRMNL platform there is nothing to install: plugins render against the platform's current framework build, and a custom stack upgrades by pointing at the 3.3 stylesheet. Your plugin looks the same until you opt into 3.2 and 3.3 features. Two things are worth reviewing.
- Numbered border levels are deprecated:
border--h-1throughborder--h-7(and vertical counterparts) still render, but will be removed in Framework 4.0. Prefer the shade steps (border--h-10toborder--h-75) in new markup. See Border Border Draw horizontal and vertical rules on the same shade scale as backgrounds 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; everywhere else two neighboring steps share a line. . - Themed screens ignore dark mode: if you add a
screen--theme-<id>class,screen--dark-modeno longer applies. A theme already decides every color. See Themes Themes Visually customize any plugin with a drop-in stylesheet that recolors the whole screen Themes are a simple way to visually customize any TRMNL plugin. A theme adjusts the framework's colors (backgrounds, text, borders, chart colors) without touching plugin markup, and gracefully adapts to every supported device, from 1-bit ePaper to full color. .
From Framework v2
v3 is backward compatible with v2: your class names still render. One visual change needs review. v3 rebuilt the 1-bit grayscale dither patterns on a 14-step linear scale, so most shade names look lighter or darker than they did in v2.
The full shade-by-shade migration table lives in the Framework 3.1 upgrade guide. It lists each shade's v2 and v3 lightness and which v3 shade restores the original look.
Verifying the Upgrade
Use the Raw / Preview toggle in the screen picker (top right) to compare the raw colors against what the panel will actually show. To check themes, pick a Style in the same picker and confirm your plugin stays legible under each one.
Next Steps
Head to the V3.3 Enhancement Guide V3.3 Enhancement Guide Make your plugin theme-ready and adopt adaptive charts, icons, and JS paint Framework 3.3 lets an existing plugin follow themes and device modes everywhere: in markup, in charts, in icons, and in outlined text and images. This guide walks through the enhancements one at a time; adopt them in any order. to make your plugin theme-ready and to adopt adaptive charts and icons.