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 The Scale system provides utility classes to scale the entire interface by adjusting the UI scale factor. This is useful for adapting content density for different viewing distances or user preferences. , Visibility Visibility Control element visibility based on display bit depth The visibility and display utilities provide comprehensive control over element visibility and display types across devices. They include hidden/visible controls and display helpers like flex, grid, and inline, with responsive and bit-depth variants for device-specific layouts. , Aspect Ratio Aspect Ratio Maintain consistent proportions for elements regardless of their content The Aspect Ratio utility uses the native CSS aspect-ratio property to maintain consistent proportions for elements. Perfect for images, videos, and containers that need to maintain specific width-to-height ratios across different screen sizes. , Rounded Rounded Control element rounding with predefined values The Rounded system provides consistent border radius values for creating smooth corners on elements. It offers predefined sizes, corner-specific controls, and custom values to maintain visual consistency throughout your interface. .
- New element: Divider Divider Create horizontal or vertical dividers between elements The Divider element provides a simple, standalone way to create visual separations in your layouts. Dividers automatically adapt to their background color for optimal visibility across four background types: white, light, dark, and black. .
- New 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. 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 <a class="font-medium hover:underline" href="/framework/docs/3.1/colors">Colors</a> palette. , 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 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. 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 The Content Limiter system automatically restricts the height of content areas based on the view type. When content exceeds the height threshold, it applies smaller typography and truncates overflowing text using the Clamp Engine to fit the available space. enhanced to drop fixed values and calculate available space dynamically.
- Item component: Item Item Build standardized list items and content blocks The Item component provides a flexible container for displaying content with optional metadata and indexing. It's commonly used for lists, schedules, and other content that needs consistent formatting. adds new meta-emphasis classes to emphasise items.
- Table component: Table Table Create data tables optimized for 1-bit rendering The Table system provides structured data presentation with consistent styling and various size options. It's designed to display information in a clear, scannable format while maintaining visual hierarchy. 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 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. 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 The Title system provides consistent text headings with different size variants. It helps maintain visual hierarchy and readability throughout the interface. , 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. , and Description Description Format descriptive text with standardized styles The Description component provides a standardized way to display descriptive text content with consistent styling. 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. .