V3 Overview
Framework v3 introduces a complete color system for ePaper devices. The framework now supports chromatic palettes, semantic color roles, and an extended grayscale scale, while shifting its internal architecture to CSS custom properties for cleaner, smaller stylesheets. Existing markup continues to work without changes.
#
Most Important Upgrades
- Color support: v3 adds a complete color system with chromatic palettes, semantic color roles, and automatic adaptation to each device's supported palette and bit-depth.
- Architecture overhaul: the framework moves from a rules-based selector system to CSS custom properties, greatly reducing combinatorial mode rules while keeping existing class names stable.
- High-density support: framework rendering now supports high-density
1bitand2bitoutput modes. - Expanded 1bit grayscale: the usable
1bitgrayscale palette increases from 7 shades to 14. - Raw / Preview simulation: Device Preview can compare full-bright tokens (Raw) against panel-accurate output that simulates true colors and white point.
- Text Scale: 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. adjusts every framework font size and pixel line height without applying the same factor to interface geometry or text strokes.
- Fluid Mashups:
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 themashup--3x3layout and cell placement modifiers for custom tilings. adds a three by three grid with column, row, and span modifiers for custom tilings.
#
What's New
- Chromatic utilities:
bg--red,bg--blue-40,text--green-60and similar classes for all 10 hues and 14 steps. - Semantic colors:
bg--primary,text--success,label--error,bg--warning- intent-based styling that maps to underlying hues. - Colors reference: new 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. page documenting the full grayscale, chromatic, and semantic palette.
- Label color variants:
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.
gains
label--primary,label--success,label--error, andlabel--warningfor colored badges. - Closest-hue mapping: when a selected device cannot render a requested color directly, framework tokens map to the nearest supported hue automatically.
- Color pattern images: auto-generated dither patterns for limited-palette devices in
public/images/color-*/.
#
What's Enhanced
- Background utility:
Background
Background
Apply color tokens as backgrounds with bg--{token}
Use the color palette defined in Colors. Apply these shades with bg--{token} for backgrounds. On 1-bit displays, grayscale uses dither patterns; on 2-bit and 4-bit+, solid colors render.
refactored to reference CSS custom properties. Now supports grayscale, chromatic, and semantic tokens in a single class, including high-density
1bitand2bitrendering modes. - Text utility: Text Text Control text color, alignment and formatting The Text Color system creates the illusion of grayscale text through carefully designed dither patterns. When rendered on 1-bit (black and white only) displays, these patterns create an illusion of different shades of gray by using specific arrangements of black and white pixels. The shade scale matches the Colors palette. follows the same CSS variable pattern, supporting chromatic and semantic text colors alongside grayscale.
- Border and Outline:
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.
and
Outline
Outline
Pixel-perfect dotted rounded borders drawn with CSS gradients on 1-bit displays
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 and 4-bit displays it falls back to a standard CSS border with border-radius.
use shared mixins for DRY, consistent rendering across bit-depths and color palettes, including high-density
1bitand2bitmodes. - Dark mode: grayscale tokens invert automatically; chromatic hues stay stable while their lightness steps mirror (light to dark).
- Progress component: Progress Progress Display progress bars in different styles Progress bars and step dots for completion state. The fill renders as a bitmap pattern on 1-bit displays and as a solid color on 4-bit+ displays. updated to render with color palette awareness.
#
What's Changed
- Grayscale scale: the primary naming convention is now
gray-10throughgray-75(14 steps of 5). In1bit, the usable grayscale palette expands from 7 shades to 14. The legacy namesgray-1throughgray-7remain functional but are deprecated. - Rendering model: mode-dependent styling (bit-depth, dark mode, palette) is driven by CSS custom properties on
.screenrather than combinatorial selector rules. This is an internal change - existing class names are unaffected. - Default font bundle: Framework 3.1 uses the TRMNL bundle from
Font Family
Font Family
Switch between Classic and TRMNL font bundles per device
The Framework ships two pixel font bundles: Classic (NicoPups, NicoClean, BlockKie) and TRMNL (TRMNL12, TRMNL16, TRMNL21). Low-density displays use the selected bundle; high-density displays use Inter Variable for legibility.
by default on low-density displays. Add
screen--fonts-classicto keep the 3.0 Classic typography.
#
Start Here
- Upgrading from v2? → V3 Upgrade Guide V3 Upgrade Guide Steps to upgrade your plugins from Framework v2 to v3 Framework 3.2 is fully backward compatible with 3.0 and 3.1. Existing class names render unchanged, and every 3.2 feature (themes, the paint API, adaptive charts, adaptive icons) is opt-in. This guide lists the few things worth reviewing when you upgrade. .
- Looking to use colors and the new palette system? → V3 Enhancement Guide V3 Enhancement Guide Use chromatic colors, semantic roles, and label variants in your plugins Framework 3.2 lets an existing plugin follow themes, dark mode, and device modes everywhere: in markup, in charts, in icons, and in text and image outlines. This guide walks through each enhancement you can adopt (theme readiness, adaptive charts, adaptive icons, JS paint, the border step rail, and legible overlaid text and images), one at a time and in any order. .
- New to the framework? Start with the 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. reference page.