V2 Overview
Welcome to Framework v2 - the first open-source ePaper adaptive front-end framework. This release introduces support for multiple devices, orientations, and bit-depths, while making layouts and utilities smarter and more automatic. The overview highlights the key improvements, new features, and breaking changes, and points you to detailed guides for upgrading and getting the most out of v2.
#
Highlights
- Adaptive in Context: the framework automatically adapts to the current bit-depth, size, and orientation. Layouts adjust with automatic enhancement on richer devices and graceful degradation on limited ones.
- Expanded palette: from 1-bit (2 shades) to 4-bit (16 shades).
- Dynamic Engines: engines like Overflow Overflow Handle column items overflow The Overflow engine automatically lays out items into up to N columns and adds an "and X more" label when content exceeds the available height. It also applies text clamping per-column width and handles grouped headers without leaving orphaned headings. and Clamp Clamp Manage text overflow with single and multi-line truncation The Clamp engine truncates text to a specified number of lines using word-based ellipsis. It preserves the original text, measures available width, and re-applies clamping whenever layouts change. are now smart enough to calculate available space themselves. No more hard-coded pixel values required.
- Backwards compatibility: existing code continues to work, enhancing automatically when displayed on more capable devices.
#
What's New
- New utilities: 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. , Visibility Visibility Control element visibility based on display bit depth Show or hide an element and set its display type. Hidden and visible controls plus display helpers like flex, grid, and inline, each with responsive and bit-depth variants for device-specific layouts. , Aspect Ratio Aspect Ratio Maintain consistent proportions for elements regardless of their content Hold an element to a fixed width-to-height ratio. The utilities set the native CSS aspect-ratio property, so images, charts, and containers keep their proportions at any screen size. , Rounded Rounded Control element rounding with predefined values Utility classes for corner radius. Predefined sizes, per-corner control, and arbitrary pixel values. .
- New element: Divider Divider Create horizontal or vertical dividers between elements The Divider element provides a simple, standalone shorthand for horizontal and vertical separators. It uses the same border-level rendering pipeline as the Border utility and defaults to level 6. .
- New 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. bar.
- Table overflow engine: Table Overflow Table Overflow Handle table rows overflow When a table has more rows than can fit within the available vertical space, it constrains its height and appends a trailing "and X more" row to indicate the hidden entries. - new engine for tables, automatically handling row overflows and adding an “and X more” row.
- Extended utilities: 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. , 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 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. are now adaptive across bit-depths and contexts.
#
What's Enhanced
- Clamp engine: Clamp Clamp Manage text overflow with single and multi-line truncation The Clamp engine truncates text to a specified number of lines using word-based ellipsis. It preserves the original text, measures available width, and re-applies clamping whenever layouts change. rebuilt as a true JavaScript DOM engine, integrated with other engines like Overflow Overflow Handle column items overflow The Overflow engine automatically lays out items into up to N columns and adds an "and X more" label when content exceeds the available height. It also applies text clamping per-column width and handles grouped headers without leaving orphaned headings. .
- Overflow engine: Overflow Overflow Handle column items overflow The Overflow engine automatically lays out items into up to N columns and adds an "and X more" label when content exceeds the available height. It also applies text clamping per-column width and handles grouped headers without leaving orphaned headings. adds smarter features like smart columns, clamp-aware distribution, group headers, and harmonious group columns.
- Content limiter engine: Content Limiter Content Limiter Change font size when content overflows to fit within the container Content areas are capped in height by the view type they sit in. Past that threshold the limiter steps typography down and the Clamp engine truncates the first block that still overflows. enhanced to drop fixed values and calculate available space dynamically.
- Item component: Item Item Build standardized list items and content blocks A row for lists, schedules, and other repeating content, with optional meta text, an index, or an icon. Stack items in a Layout and let the Overflow engine handle the ones that do not fit. adds new meta-emphasis classes to emphasise items.
- Table component: Table Table Create data tables optimized for 1-bit rendering Tabular data with optional row indexes. Five size variants, and the Overflow and Clamp engines drop rows and truncate cells that do not fit the space available. adds new style variants, including small tables, large tables, and index tables.
#
What's Changed
- Border utility: 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. expanded from 1-bit only → now works across 1, 2, and 4-bit spaces. Requires new class names.
- Clamping: Title Title Style headings with consistent typography Headings for a plugin screen. Five size variants from small to xxlarge, each with responsive prefixes for breakpoints and orientation. , 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. , and Description Description Format descriptive text with standardized styles Supporting body text, sized to sit under a Title or a Value rather than compete with it. Four size variants from base to xxlarge, with wrapping or line clamping for longer copy. are now unclamped by default. Developers must explicitly clamp if needed.
#
Start Here
- Upgrading from v1? → V2 Upgrade Guide V2 Upgrade Guide Steps to upgrade your plugins to Framework v2 This short guide helps you upgrade from Framework v1 to v2. The new framework stays backward compatible, with the exception of the Border utility. .
- Looking to take advantage of new features? → V2 Enhancement Guide V2 Enhancement Guide Device, bit-depth, and orientation-responsive patterns for plugins This guide explains how to enhance plugins with Framework v2.0's expanded responsive capabilities. For a quick migration checklist, see the Upgrade Guide. .