Sass API
The Sass API is the framework's SCSS source, open since 3.2. A custom stack serves either an official released build or its own build compiled from this source; these pages document the build-your-own path. The TRMNL Platform always serves official builds.
You never build or serve the framework. The TRMNL Platform renders every plugin against its official builds: recipes can pin a specific release, and the developer license lets a private plugin tie to one.
You choose the framework build your screens load: a released build straight from the releases CDN, or your own build compiled from this SCSS source.
<!-- plugins.css (platform-provided) -->
<!-- plugins.js (platform-provided) -->
<div class="screen">...</div><!-- Option 1: serve a released build -->
<link rel="stylesheet" href="https://usetrmnl.com/css/latest/plugins.css">
<script src="https://usetrmnl.com/js/latest/plugins.js"></script>
<!-- Option 2: compile and serve your own build -->
<link rel="stylesheet" href="/assets/plugins.css">
<script src="/assets/plugins.js"></script>The source at a glance
Everything compiles from one entrypoint. plugins.scss
loads the framework module
(framework/index.scss), which composes the
configuration, the mixins, and the style layers in a fixed cascade order.
// framework/index.scss: configuration and mixins load first,
// then every style lands in a declared cascade layer.
@forward 'config/custom';
@use 'config/tokens' as vars;
@use 'mixins' as mixins;
@layer tn--normalize, tn--elements, tn--components, tn--base,
tn--device-overrides, tn--themes, tn--utilities;
Every rule lands in a tn-- prefixed cascade
layer, so a custom stack can run the framework next to other CSS without specificity fights. The codebase
is pure Dart Sass module system: @use and
@forward throughout, no
@import.
config/: the device map, design-token maps, generated color maps, fonts, and the root CSS variables.mixins/: screen targeting, theme slots, and the scale functions. This is the consumer-facing Sass surface; see Sass Mixins Sass Mixins Screen-targeting mixins and scale functions for authoring device-aware SCSS The screen mixins generate device-aware rules from the same grammar the responsive utility classes use: size, orientation, and bit depth. The scale functions wrap pixel values so custom CSS scales with the device like framework CSS does. .base/,elements/,components/,utilities/: the screen scaffolding, text elements, higher components, and utility classes the docs document page by page.themes/: standalone theme stylesheets, compiled separately fromplugins.css. See Themes Themes Opt-in stylesheets that re-theme screens while preserving device-capability rendering Themes are standalone stylesheets that re-point semantic channels, component slots, and utility tokens at different palette tokens. A themed screen still renders through its device mode: dither patterns on 1-bit, palette images on limited color, solids on full color. .
For the repository tour, the license, and the release pipeline, see Open Source Open Source What this repository is, how it fits together, and the paint mandate that shapes it The TRMNL Framework is open source as of version 3.2. It is the design system TRMNL plugin screens are built with, tuned for 1-bit, 2-bit, and limited-color ePaper displays. This repository holds the CSS, the JavaScript runtime, the design tokens, and the documentation site you are reading. .
Public and internal surface
- Public: the
$custom-devicesconfiguration, the three supportedframework/mixinsfamilies (screen targeting, scale functions, theme slots) named on Sass Mixins Sass Mixins Screen-targeting mixins and scale functions for authoring device-aware SCSS The screen mixins generate device-aware rules from the same grammar the responsive utility classes use: size, orientation, and bit depth. The scale functions wrap pixel values so custom CSS scales with the device like framework CSS does. , the compiled CSS classes, and the public--*variables listed on Tokens Tokens Complete CSS variable reference with root defaults, density, and bit-depth overrides The Tokens reference lists every Framework CSS variable from_variables_root.scssand display overrides in_variables_overrides.scss. Use it to understand defaults, 2-bit visual/layout behavior, high-density typography, and 4-bit-and-up scaling. . - Internal: members whose names start with
-or_(private to their module), every other mixin and functionframework/mixinsforwards, and the paint variables (--bg-*,--text-*,--border-*) owned by the screen-mode engine. Internal members can change without notice. - Generated: files with a DO NOT EDIT header (the device map, the color maps) regenerate from
db/data/via rake tasks. Configure or extend them; do not hand-edit them.
Theme stylesheets have their own authoring contract built on the theme-slot mixins; it is documented on
Authoring Themes
and enforced by
rake framework:themes:lint.
Go deeper
Compiling the Framework
The toolchain, the entrypoint, themes, the JS runtime, and what to serve.
Custom Devices
The device map schema and the $custom-devices configuration for your own panels.
Sass Mixins
Screen-targeting mixins and scale functions for authoring device-aware SCSS.