Designing Layouts

Both accept: file path (layouts/my.html), short name (neon-dash), or built-in name (system-stats).

Use --mock to inject realistic gaming-load data (144 FPS, 67°C CPU, 71°C GPU, 285W) when testing layouts that depend on sensors not currently active.

Read the PNG after every render. Unreviewed output is unknown output.

Critical Engine Constraint: Explicit Heights

The rendering engine (taffy) cannot measure text. Every element that contains text MUST have an explicit height or it collapses to 0px and overlaps with siblings.

<!-- BAD: span has no height, will overlap with siblings -->
<span style="font-size: 24px; color: #e94560;">72°C</span>

<!-- GOOD: height slightly larger than font-size -->
<span style="height: 30px; font-size: 24px; color: #e94560;">72°C</span>

Rule of thumb: height ≈ font-size × 1.2

This is the single most common layout bug. If text overlaps, check for missing heights.

SVG Layouts (Primary Format)

SVG is the primary layout format. Use the SvgRenderer pipeline: SVG template → Tera substitution → resvg → Pixmap.

{# history: cpu_util=60s, gpu_temp=120s #}
<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 480 480">
  <!-- Background pattern -->
  {{ background(pattern="grid", color="#ffffff08", spacing=24) }}

  <!-- Area graph: CPU utilization history -->
  {{ graph(data=cpu_util_history, x=0, y=380, w=480, h=100,
           style="area", fill="#e9456033", stroke="#e94560") }}

  <!-- Current CPU temp (hero value) -->
  <text x="240" y="200" text-anchor="middle" font-size="96"
        fill="{{ theme_primary }}" font-family="monospace">
    {{ cpu_temp | default(value="--") }}°C
  </text>
</svg>

Key SVG layout rules:

1. viewBox="0 0 480 480" — always 480x480 canvas
2. {# history: ... #} frontmatter declares metrics to buffer (see components.md)
3. Text uses absolute x,y coordinates — no flexbox in SVG
4. Components are Tera function calls that emit SVG fragments
5. Document order = z-order: background first, text last

Component Composability Rules

These are binding contracts for how components interact:

1. Position-independent. Every component takes x, y, w, h and renders within that bounding box. No assumptions about position on canvas.

2. Theme-aware defaults. Components default to theme_* variables for colors, overridable with explicit hex. A layout using all defaults inherits the active theme automatically.

3. Opt-in history. Only metrics declared in {# history: ... #} frontmatter get buffered. Components needing history for an undeclared metric render empty — graceful degradation.

4. Purely additive. Components emit SVG elements only. They don't modify the canvas or other components. Compositing (opacity, layering) is your responsibility via standard SVG attributes.

5. Single background rule. At most one background per layout (last {{ background() }} call wins). Global config background_image overrides per-layout background when set.

6. Document-order stacking. Layering follows SVG document order: background → graphs/visualizations → panels → text. Control z-order by element placement in the template.

7. Graceful degradation. Missing sensor data → default(value="--"). Missing history → empty graph. Missing theme → default palette. Missing background asset → transparent. No component causes a render failure.

8. Sensor polling independence. Render tick rate and sensor poll rate are independent. Animation-driven tick rate increases do not increase sensor reads.

Quick Start: Creating a Layout (HTML)

For HTML layouts using the legacy TemplateRenderer. A layout is an HTML file using a CSS subset with Tera template variables for sensor data.

<div style="display: flex; flex-direction: column; width: 480px; height: 480px;
            background: #08080f; padding: 16px; gap: 12px;">

  <!-- Card with label + hero value + secondary info -->
  <div style="display: flex; flex-direction: column; height: 172px;
              background: #12121e; padding: 12px; gap: 4px;">
    <span style="height: 20px; font-size: 14px; color: #888888;">CPU</span>
    <span style="height: 88px; font-size: 64px; color: #e94560;">
      {{ cpu_temp | default(value="--") }}°C
    </span>
    <span style="height: 28px; font-size: 22px; color: #c4546e;">
      {{ cpu_util | default(value="--") }}% LOAD
    </span>
  </div>

</div>

Key patterns:

1. Root div sets display dimensions, page background, outer padding
2. Cards use darker background (#12121e) on darker page (#08080f) for depth
3. Every text span has explicit height
4. Sensor values use {{ key | default(value="--") }} for missing data
5. Colors create hierarchy: bright accent for hero, dimmed accent for secondary, gray for labels

Design System

Typography Scale

Single font: JetBrains Mono (monospace). Numbers won't shift width when values change — no layout jitter.

Color System

Page backgrounds — never pure black, use tinted near-blacks:

• #08080f — blue-tinted black (recommended default)
• #0a0a14 — slightly lighter
• #0a0a0a — near-black

Card backgrounds — subtly lighter for depth:

• #12121e — standard card
• #1a1a2e — slightly lighter card
• #111118 — very subtle elevation

Color-tinted cards for visual drama (strongest design tool):

• #1a0a10 — dark red tint (CPU panels)
• #0a1420 — dark blue tint (GPU panels)

Accent colors by metric type:

Labels and muted text: #888888 minimum — anything dimmer becomes invisible on LCD hardware.

For temperature ramps, utilization coding, alternative palettes, and Tera conditional examples, see color-system.md.

Spacing

• Outer padding: 16-20px
• Gap between cards: 10-12px
• Inner card padding: 8-12px
• Gap between text elements: 2-4px

Layout Arithmetic

All dimensions must be explicit pixels. Verify math before rendering:

Total height = root height (480)
Content height = total - 2 × padding
Available for rows = content height - (num_gaps × gap_size)
Sum of row heights must equal available height

For layout pattern examples with complete HTML, see layout-patterns.md.

Supported CSS Properties

Not supported: flex-grow, flex-shrink, flex-wrap, % units, em/rem, per-side padding/margin, gradients, borders, shadows, images, grid, positioning, opacity, transforms.

Available Sensor Keys

Aggregate (always available)

Per-core CPU (sysinfo)

Per-core temperature (hwmon coretemp)

CCD temps (hwmon k10temp, AMD Zen3+)

Network (sysinfo, available after second poll)

Always use {{ key | default(value="--") }} — sensors may be unavailable.

Dynamic Color Coding with Tera

Tera {% if %} conditionals can change colors based on sensor values. Sensor values are strings — use | int for numeric comparison, and guard with existence check.

For complete temperature/utilization color ramps and Tera implementation examples, see color-system.md.

Extending the Rendering Engine

The engine is intentionally minimal. When a design needs something missing:

1. Identify the gap — which CSS property or feature is needed?
2. Check parser.rs — is it parsed but not rendered? (e.g., border-radius)
3. Implement in the right layer:
   • New CSS property → parser.rs (parse) + layout.rs (if layout-affecting) + draw.rs (render)
   • New visual feature (images, shapes) → draw.rs using tiny-skia
   • New sensor data → add provider in src/sensor/
4. Test with preview_layout before pushing to hardware

The rendering pipeline: Tera template substitution → HTML parsing → taffy flexbox layout → tiny-skia pixel rendering → JPEG encoding with rotation.

Common Mistakes

References

• components.md — Full component catalog: signatures, args, examples (graph, btop_bars, btop_net, btop_ram, background)
• color-system.md — Temperature ramps, utilization coding, full palette
• layout-patterns.md — Concrete layout examples with complete HTML
• rendering-engine.md — Full engine details, pipeline architecture, extension guide