V3 Overview
Framework v3 introduces a complete color system for e-paper 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.
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 page documenting the full grayscale, chromatic, and semantic palette.
- Label color variants:
Label
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
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 follows the same CSS variable pattern, supporting chromatic and semantic text colors alongside grayscale.
- Border and Outline:
Border
and
Outline
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 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
by default on low-density displays. Add
screen--fonts-classicto keep the 3.0 Classic typography.
Start Here
- Upgrading from v2? → V3 Upgrade Guide .
- Looking to use colors and the new palette system? → V3 Enhancement Guide .
- New to the framework? Start with the Colors reference page.