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 framework typography independently from 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 blend pairs The Colors system defines the complete palette for the framework: grayscale, chromatic hues, blend pairs, 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
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.
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 <a class="font-medium hover:underline" href="/framework/docs/3.1/colors">Colors</a>. 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 <a class="font-medium hover:underline" href="/framework/docs/3.1/colors">Colors</a> 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
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.
and
Outline
Outline
Pixel-perfect rounded borders using border-image for 1-bit displays
The Outline utility provides pixel-perfect rounded borders using CSS border-image with a 9-slice composite image. On 1-bit displays, it renders crisp, dithered corner patterns that scale with the element. On 2-bit and 4-bit displays, it falls back to standard CSS borders 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 The Progress component provides visual indicators for completion status and step-based processes. Optimized for ePaper displays with bitmap patterns for 1-bit displays and solid colors for 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 This guide covers the v2 to v3 upgrade path. The transition is fully backward-compatible: adopt the new color system and extended grayscale at your own pace. .
- 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 This guide explains how to use Framework v3 color features: chromatic backgrounds and text, semantic roles, label color variants, and the Raw/Preview toggle. .
- New to the framework? Start with the Colors Colors Complete palette definition: grayscale, chromatic hues, and blend pairs The Colors system defines the complete palette for the framework: grayscale, chromatic hues, blend pairs, 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.