Sass API
The Sass API is the framework's SCSS source, open since 3.2. These pages cover the build-your-own path: compiling from source, adding device profiles, and using the mixins in your own SCSS. A custom stack can also skip the build entirely and serve an official released build, which is what the TRMNL Platform always does.
The TRMNL Platform serves the framework for you, rendering every plugin against its official builds. Recipes can pin a specific release, and the developer license lets a private plugin do the same.
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://trmnl.com/css/latest/plugins.css">
<script src="https://trmnl.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 loads the
configuration, the mixins, and the style layers in a fixed 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
uses the Dart Sass module system throughout: @use and
@forward, never
@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 let your own SCSS target the same conditions the responsive utilities do: device size, orientation, and bit depth. The scale functions wrap pixel values so your CSS scales with the device the way framework CSS does. .base/,elements/,components/,utilities/: the screen scaffolding, text elements, larger components, and utility classes these docs cover page by page.themes/: standalone theme stylesheets, compiled separately fromplugins.css. See Themes Themes Visually customize any plugin with a drop-in stylesheet that recolors the whole screen Themes are a simple way to visually customize any TRMNL plugin. A theme adjusts the framework's colors (backgrounds, text, borders, chart colors) without touching plugin markup, and gracefully adapts to every supported device, from 1-bit ePaper to full color. .
The source lives at github.com/usetrmnl/trmnl-framework. 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, 4-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 let your own SCSS target the same conditions the responsive utilities do: device size, orientation, and bit depth. The scale functions wrap pixel values so your CSS scales with the device the way 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 function thatframework/mixinsforwards, and the paint variables (--bg-*,--text-*,--border-*) the framework's rendering owns. 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.