V3.3 Overview
Framework 3.3 adds adaptive maps, position utilities for content that sits over other content, and a theme contract that reaches the title bar, item cards, structure and text. It builds on the 3.2 open-source release: themes, a JavaScript paint API, adaptive charts and icons, rebuilt borders and strokes, Text Scale, complete Scale modifiers, and Fluid Mashups. Existing markup keeps working; every 3.2 and 3.3 feature is opt-in.
Open Source
The design system behind every TRMNL screen is now yours to read, fork, and build on. It lived inside the core product since inception; 3.2 pulled it out into its own public repository at github.com/usetrmnl/trmnl-framework.
It is yours to shape too. Test suites and CI run on every pull request, and the Open Source Open Source What this repository is, how it fits together, and the paint mandate that shapes it The TRMNL Framework is open source as of version 3.2. It is the design system TRMNL plugin screens are built with, tuned for 1-bit, 2-bit, 4-bit, and limited-color ePaper displays. This repository holds the CSS, the JavaScript runtime, the design tokens, and the documentation site you are reading. and Contributing Contributing Run the framework locally, find your way around, run the tests, and open a good pull request Everything you need to make your first contribution to the TRMNL Framework: run it locally, find your way around the code, run the test suites, and open a pull request that lands. Start here, then read CONTRIBUTING.md for the fine print. guides show where everything lives and how to ship a change.
The v3 Color Foundation
3.3 builds on the color system introduced in v3.0: 10 hues with 14 lightness steps, semantic roles (primary, success, error, warning), and a 14-step grayscale, listed in full on Colors Colors Complete palette definition: grayscale, chromatic hues, and semantic roles The Colors system defines the complete palette for the framework: grayscale, chromatic hues, and semantic roles (primary, success, error, warning). Use these tokens with bg--, text--, and other utilities. See Background and Text Color for usage examples. . Every color adapts to the device's palette and bit depth on its own, with no per-device markup.
Independent Text Scale
Text Scale resizes all framework text without touching the rest of the interface. It stacks with Scale, so a dense layout can keep its text large instead of shrinking both together. See Text Scale Text Scale Scale all framework typography independently of interface geometry Text Scale adjusts every framework font size and pixel line height from one screen modifier. It composes with Scale, so you can change text readability without applying the same factor to interface geometry or text strokes. .
Themes
Recolor a whole screen by loading one extra stylesheet and adding screen--theme-<id>. The theme picks the colors; each device renders them with the inks it has. 3.2 ships three themes: Black and Yellow, White and Red, and Dark.
- Author your own theme with the
theme-slotsmixins and validate it withrake framework:themes:lint. - Preview any docs example with a theme via the Style selector in the screen picker.
Full reference: 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. .
Extended Theming
3.3 widens what a theme can reach. The title bar's inks split into slots of their own, item cards gain a fill, a paired ink, padding and a border art, and dividers gain a slot, so a theme restyles those surfaces instead of leaving them on the screen's defaults.
Structure moves through unitless factors over the unthemed geometry, where 1 is always the unthemed screen: whitespace, corners, title bar height and progress. A signed weight shift moves every vector-face role, and text modifiers set case and tracking per text role. Size and line height stay out of it, because those belong to the device and the reader's own text scale.
Every slot and factor: Theme Slots Theme Slots Every part of a screen a theme can recolor, from whole-screen colors down to single components, utilities, borders, and chart series This page lists every slot: each part of a screen a theme can recolor, and the mixin that sets it. A slot takes a framework token, not a raw color, so whatever you map still renders correctly on every device. .
TRMNLPaint: the JavaScript Paint API
Read any framework color, border, text style, or size from JavaScript. TRMNLPaint returns what CSS would paint right now, with the device, scale, and theme already applied, so your JavaScript never hardcodes a color.
- Resolvers read one value each:
bg(),text(),semantic(),series(),border(),type(), and more. - Painters:
apply(),applyBorder(),applyType()write resolved paint onto nodes. watch()re-runs your build function whenever the screen's device, scale, mode, dark mode, or theme changes.cssVar()reads any public--*variable, which is how a theme hands values to plugin code.slot()returns what any component slot paints with, andtoMapLibre()shapes a Fill for MapLibre GL JS.scale()reads the current scale factor, andpx()converts pixel numbers with it.
Full reference: Paint API Paint API TRMNLPaint: read the exact colors and patterns CSS paints right now, from JavaScript TRMNLPaint is the framework's JavaScript API for its paint: colors, border lines, and text styles. Ask it for any framework color and it returns what CSS would actually paint right now, with the device and the active theme already applied. Use it wherever JavaScript draws: charts, maps, canvases, or your own rendering. .
Generated Paint Assets
Every dither pattern is now generated at build time as an inline SVG instead of shipping as a PNG image, so a screen paints with zero image fetches.
- CSS and JavaScript share the same generated patterns:
TRMNLPaintreads back exactly what CSS paints. - Every screen mode, Raw/Preview included, paints from the same generated set, so pattern shapes never change between modes.
Adaptive Charts
The runtime now bundles TRMNLCharts, a Highcharts adapter built on TRMNLPaint. Series colors, grid lines, and chart text all come from the framework, so a chart adapts with the rest of the screen instead of carrying its own fixed colors.
options()andmerge()give you adaptive Highcharts defaults under your own settings.series(i, n)picks each series color;applySwatches()paints matching legend markers.watch()rebuilds the chart on device, scale, mode, dark mode, or theme changes.TRMNLPaint.px()scales numeric chart dimensions from the same live CSS contract.
Usage and live examples: Chart Chart Visualize data with charts that adapt to the device and theme Plugins can draw charts with any JavaScript charting library. The TRMNLCharts helper supplies the framework's colors, so a chart adapts to the device and themes like the rest of the screen. . For charting beyond Highcharts, use Paint API Paint API TRMNLPaint: read the exact colors and patterns CSS paints right now, from JavaScript TRMNLPaint is the framework's JavaScript API for its paint: colors, border lines, and text styles. Ask it for any framework color and it returns what CSS would actually paint right now, with the device and the active theme already applied. Use it wherever JavaScript draws: charts, maps, canvases, or your own rendering. directly.
Adaptive Maps
Maps join charts on TRMNLPaint. The runtime bundles TRMNLMaps, a MapLibre GL JS adapter that composes the map style from the framework's map slots over OpenStreetMap vector tiles, so a plotted map takes dither tiles on 1-bit, solids on 4-bit, hues on a color panel, and a theme's own tokens. Maps render as one still frame, with no interaction and no animation.
A map with no source of its own fetches OpenStreetMap's public Shortbread tiles directly. A plugin names its own source and key instead, and a host can hand one to a single plugin instance, so a key never sits in the markup.
Usage and live examples, including a Strava activity: Map Map Plot locations and routes on a vector map that adapts to the device and theme Maps render OpenStreetMap vector tiles through MapLibre GL JS, with every layer painted by the framework. The TRMNLMaps helper composes the map style from the live screen, so a map adapts to the device and themes like the rest of the screen. Maps are plotted, never satellite, and never interactive. . The resolvers and adapter behind it: Painting Maps Painting Maps Map slot colors for the current device, mode, and theme, with MapLibre GL JS adapters These functions give you the color of every part of a map: land, water, roads, parks, buildings, and labels, correct for the current device, mode, and theme. Adapters turn each answer into a MapLibre GL JS paint property, and TRMNLMaps assembles whole map styles out of them. .
Positioned Content
relative and absolute put one element over another instead of beside it, so a full-bleed panel can take the whole layout and carry a compact card in one corner of it. Offsets run on the spacing scale, and a short stacking scale settles which of two overlapping elements is drawn on top.
An element out of flow is not measured by the fitting engines, so it carries its own size and clamps. The classes, the scale, and what an overlay needs to stay readable on 1-bit: Position Position Take an element out of flow and set its distance from each edge of its container Use Position to put one element over another instead of beside it. Offsets on the spacing scale hold it a set distance from the edges of its container, and a short stacking scale says which of two overlapping elements is drawn on top. .
Adaptive Icons
Add image--adaptive to a monochrome icon and the framework recolors it the way it colors text: it follows the device, Raw/Preview, and the active theme. One set of icons works everywhere, as long as they are same-origin or CORS-readable. See
Image
Image
Place images with size, object fit, dithering, inversion, and adaptive icon utilities
Place images on a screen and control their size, object fit, and inversion. On 1-bit displays, dithering arranges black and white pixels so an image still reads as shades of gray.
.
Rebuilt Borders, Outlines, and Strokes
The Border, Outline, Text Stroke, and Image Stroke utilities were rebuilt the same way as the color system and now follow the device and themes on their own.
- Borders:
border--h-{step}andborder--v-{step}now use the same 10 to 75 shade scale as backgrounds, plusborder--h-blackandborder--h-white. Lines render as generated gradients instead of PNG tiles, so a bordered screen fetches no images. The numbered levelsborder--h-1throughborder--h-7still work but are deprecated. 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. . - Outline: draws a pixel-perfect dotted rounded border on 1-bit, and a solid rounded border on 2-bit and 4-bit. 3.3 rounds the element itself on the same 8px curve, so a card with its own background ends where the outline does, and adds
outline--mutedfor an edge in a mid gray that still prints on 1-bit. See Outline Outline Draw a pixel-perfect dotted rounded border on any element The Outline utility draws a pixel-perfect dotted rounded border on any element. On 1-bit displays it places single-pixel dots at exact integer coordinates with pure CSS gradients; on 2-bit, 4-bit, and full-color displays it draws a standard CSS border with border-radius instead. . - Text Stroke: renders as stacked drop shadows instead of native
-webkit-text-stroke, so the stroke sits behind the letters in every browser, even when the text is filled with a pattern. Sizes runtext-stroke--smalltotext-stroke--xlarge. See Text Stroke Text Stroke Legible text when displayed on shaded backgrounds Outline text so it stays legible on a shaded background. Set the stroke width and color with the text stroke utilities. . - Image Stroke: outlines transparent images with the same size and color variants. See Image Stroke Image Stroke Legible images when displayed on shaded backgrounds Outline a vector or transparent raster image so it stays legible on a shaded background. Set the stroke width and color with the image stroke utilities. .
Mashup Backdrop
The screen--backdrop modifier now follows themes like every other surface. See
Mashup
Mashup
Assemble multiple plugin views into a single interface
A Mashup arranges multiple plugin views within a single screen. A fixed mashup modifier (e.g. mashup--1Lx1R, mashup--2x2) positions the views, while each view's own modifier sets how much space it occupies. Fluid Mashups use the mashup--3x3 layout and cell placement modifiers for custom tilings.
.
Fluid Mashups
Fluid Mashups sit alongside the fixed layouts: place views on a three by three grid with mashup--3x3 and the mashup-cell modifiers, no inline styles needed. Every cell keeps its frame and a compact title bar at any size, on every device and under themes. See
Mashup
Mashup
Assemble multiple plugin views into a single interface
A Mashup arranges multiple plugin views within a single screen. A fixed mashup modifier (e.g. mashup--1Lx1R, mashup--2x2) positions the views, while each view's own modifier sets how much space it occupies. Fluid Mashups use the mashup--3x3 layout and cell placement modifiers for custom tilings.
.
Complete Scale Modifiers
Scale modifiers now resize everything: gaps, pixel utilities, image presets, component geometry, radii, and strokes, on top of each device's own density. The new screen--scale-xxsmall level adds a 66% scale for dense mashups, and TRMNLPaint.px() lets JavaScript convert pixel numbers the same way. See
Scale
Scale
Scale interface to affect content density and readability
Scale the whole interface from one screen modifier by changing the UI scale factor. Use it to match content density to viewing distance or user preference.
.
Under the Hood
- Smaller stylesheets: the responsive and device rules were refactored onto
:is()selectors.
Start Here
- Upgrading an existing plugin? → V3.3 Upgrade Guide V3.3 Upgrade Guide Compatibility notes for upgrading plugins to Framework 3.3 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. .
- Want to adopt themes, adaptive charts, and adaptive icons? → 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. .