V3.2 Enhancement Guide

Framework 3.2 lets an existing plugin follow themes, dark mode, and device modes everywhere: in markup, in charts, in icons, and in text and image outlines. This guide walks through each enhancement you can adopt (theme readiness, adaptive charts, adaptive icons, JS paint, the border step rail, and legible overlaid text and images), one at a time and in any order.

#

1. Make Your Plugin Theme-Ready

A theme restyles the whole screen by remapping which tokens paint each surface. Your plugin does not load themes itself; it renders inside a screen that may carry one. A plugin is theme-ready when everything it draws goes through framework classes and tokens.

  • Style with framework utilities (bg--, text--, border--) and elements (label, value, title). Themes remap all of them.
  • Avoid hardcoded hex colors and inline styles; a theme cannot remap paint it does not own.
  • Test with the Style selector in the docs screen picker. It applies a theme to every example on the page.

To theme a screen you control, include the theme stylesheet and add the theme class. Note that screen--dark-mode has no effect on a themed screen; a theme is a complete color statement. See Themes . 

<link rel="stylesheet" href="plugins.css">
<link rel="stylesheet" href="themes/black-and-yellow-theme.css">

<div class="screen screen--theme-black-and-yellow">...</div>
#

2. Migrate Charts to TRMNLCharts

Charts with hardcoded colors stay frozen while the rest of the screen adapts. The plugin runtime bundles TRMNLCharts, a Highcharts adapter that resolves series fills, grid lines, and text styles from the live screen.

  • Build your chart inside TRMNLCharts.watch() so it rebuilds when the device, scale, mode, dark mode, or theme changes.
  • Start from TRMNLCharts.options() merged under your own settings.
  • Color each series with TRMNLCharts.series(i, n) instead of a literal color.
  • Convert numeric chart dimensions with TRMNLPaint.px().
var el = document.getElementById("my-chart");

TRMNLCharts.watch(el, function () {
  var px = function (value) { return TRMNLPaint.px(value, { el: el }); };
  Highcharts.chart(el, TRMNLCharts.merge(TRMNLCharts.options({ el: el }), {
    chart: { height: px(260) },
    plotOptions: { series: { lineWidth: px(4) } },
    series: [
      { data: incoming, color: TRMNLCharts.series(0, 2, { el: el }) },
      { data: outgoing, color: TRMNLCharts.series(1, 2, { el: el }) }
    ]
  }));

  // Paint legend markers tagged data-chart-series="i" from the same ramp.
  TRMNLCharts.applySwatches({ el: el });
});

Full examples for line, multi-series, and bar charts are on the Chart page.

#

3. Mark Monochrome Icons Adaptive

Add image--adaptive to monochrome silhouette icons. The framework flattens the icon to its alpha shape and repaints it with the screen's icon paint, following Raw/Preview, bit depth, dark mode, and the active theme.

<!-- Monochrome silhouette icons (shape on a transparent background) -->
<img class="image--adaptive" src="path to icon">
#

4. Resolve Paint from JavaScript

For custom JS-drawn visuals beyond Highcharts (canvas, SVG, other libraries), resolve framework paint with TRMNLPaint. It reads the live cascade, so bit depth, dark mode, themes, and limited palettes are already applied.

// A background token: solid color on 4-bit+, dither tile on 1-bit.
var fill = TRMNLPaint.bg("gray-40", { el: "my-visual" });

// The effective one-color value of a text utility for SVG or canvas text.
var ink = TRMNLPaint.textColor("default", { el: "my-visual" });

// Rebuild whenever the screen device, scale, mode, dark mode, or theme changes.
TRMNLPaint.watch("my-visual", function () { draw(); });

The full resolver and painter surface is documented on Paint API .

#

5. Move Borders to the Step Rail

Replace the numbered border levels with shade-step selectors (the numbered classes still render, but they are deprecated). Steps use the same 10 to 75 scale as the background utility, and themes repaint the whole rail. The rail now renders as generated gradients instead of PNG tiles, so a bordered screen fetches no border images.

<!-- Before: numbered levels (deprecated) -->
<div class="item border--h-5">...</div>

<!-- After: shade steps, plus semantic black/white rails -->
<div class="item border--h-45">...</div>
<div class="item border--h-black">...</div>

See Border for the full step scale and the themed rendering behavior.

#

6. Keep Overlaid Text and Images Legible

Text and images placed over a shaded or patterned surface can lose contrast. The Text Stroke and Image Stroke utilities outline them, and both were rebuilt to follow themes, dark mode, and bit depth like the rest of the screen.

  • Add text-stroke to framework text over a busy background, and size it with text-stroke--small through text-stroke--xlarge. The stroke renders as drop-shadow rings, so it stays behind the glyph and behind background-clipped pattern fills in every browser.
  • Add image-stroke to a transparent or vector image for the same effect, with the matching --small through --xlarge sizes.
  • Leave the color off to stroke with the default contrast ink, or set one with a color variant (text-stroke--black, image-stroke--white, or any palette token). Color variants resolve through the theme chain, so themed and dark-mode screens recolor the outline to match.
<!-- Framework text over a shaded background -->
<span class="value text-stroke text-stroke--medium">64%</span>

<!-- Transparent or vector image over a pattern -->
<img class="image-stroke image-stroke--large" src="path to icon">

Full size and color scales are on the Text Stroke and Image Stroke pages.