Text Fields & Zones — LCARdS Dynamic and Customizable Text Layout System

[snootched]

One of the inconsistencies and (logged) issues in LCARdS are text fields and their placement across the different card types. Text can come from several places (components, presets, user-defined) and getting these placed precisely and consistently can be hard (and buggy.)

That changes with release 2026.04.3+. LCARdS now ships a first-class text field + zone system across the three main card types that use text fields: Button, Slider, and Elbow.

Here's a quick tour.

---

What Are Zones?

A zone is a named rectangular region of a card's SVG surface. You can now target a named zone and the card handles the geometry for you — padding, relative positioning, and font sizing all operate within the zone bounds.

The key insight is that each card ships with meaningful rectangular sub-regions: a button has its face, an elbow has its vertical bar and its horizontal bar, a slider has its track and its border caps. Zones make those regions addressable.

---

Auto-calculated Zones

No configuration needed — each supported card automatically builds a zone map when it renders. These are dynamic and calculate at runtime making them responsive to card size changes.

Button

A button in preset mode exposes a single zone: body — the full card face. In component mode (SVG component packs) the component itself declares named zones that match its internal geometry.

Zone	What it covers
body	Full card face (preset mode)
(component-defined)	Per-component named regions (component mode) Ex. ALERT component has alert_line and sub_line zones.

---

Slider

The slider exposes its inner track and one zone per enabled border cap.

Zone	What it covers
track	The inner track bounds
left	Left border cap (when enabled)
right	Right border cap (when enabled)
top	Top border cap (when enabled)
bottom	Bottom border cap (when enabled)

---

Elbow

Elbows have the richest zone vocabulary because the card type itself has the most distinct visual regions.

Simple elbow:

Zone	What it covers
vertical_bar	The vertical portion of the L-shape
horizontal_bar	The horizontal portion of the L-shape
body	The open corner area

Segmented elbow:

Zone	What it covers
outer_vertical_bar	Outer segment of vertical bar
inner_vertical_bar	Inner segment of vertical bar
outer_horizontal_bar	Outer segment of horizontal bar
inner_horizontal_bar	Inner segment of horizontal bar
body	Open corner area

Frame elbow:

Zone	What it covers
top, bottom, left, right	Each border bar independently
body	Central open area

---

Routing Text Fields to Zones

Every text field now accepts a zone: key. Drop a field into any auto-zone without touching a pixel value:

type: custom:lcards-elbow
entity: sensor.toronto_temperature
text:
  label:
    content: LIVING ROOM
    zone: horizontal_bar
    position: center
    font_size_percent: 80
    color:
      default: var(--lcards-blue)
  value:
    content: "{entity.state}"
    zone: vertical_bar
    position: center
    font_size_percent: 10
    color:
      default: var(--lcards-blue)
  floor:
    content: GROUND FLOOR
    zone: body
    position: bottom-right
    font_size: 40
    color:
      default: var(--lcards-blue)
grid_options:
  columns: 12
  rows: 3
elbow:
  type: header-left
  style: simple
  segment:
    bar_height: 35
    bar_width: 150

Fields without a `zone:` key fall back to the card's primary zone automatically, so existing configs continue to work unchanged.

---

font_size_percent — Fill the Height

The font_size_percent property sets text size relative to the zone height rather than a fixed pixel value. 100 means the cap-height of your glyphs spans the full height of the zone; 60 means 60%, and so on.

This is fully responsive: resize the card in the HA dashboard and the text scales with it.

Example of 80% height from the elbow example:

text:
  label:
    content: LIVING ROOM
    zone: horizontal_bar
    position: center
    font_size_percent: 80
    color:
      default: var(--lcards-blue)

The math uses a measured cap_height_ratio of 0.86 for the Antonio font — this corrects for the gap between the SVG font-size attribute and the actual visible cap height, so 100% is genuinely full-height, not overshooting or leaving a gap.

---

stretch — Fill the Width Too

Pair font_size_percent with stretch: true and the text fills both axes simultaneously. The zone height governs glyph size; stretch then expands or compresses glyph spacing to span the zone width using SVG textLength.

text:
  label:
    content: LIVING ROOM
    zone: horizontal_bar
    position: center
    font_size_percent: 80
    color:
      default: var(--lcards-blue)
    stretch: true               # glyph spacing fills full width

A numeric value like stretch: 0.7 targets 70% of zone width instead of 100%.

---

User-Defined Zones

Auto-zones cover the card's structural regions. For custom layouts, you can define your own zones in config.zones.

Values accept pixels, percent, or a mix per axis:

type: custom:lcards-button
entity: sensor.bedroom_dial_battery
zones:
  label_col:
    x: 0
    "y": 0
    width: 80
    height_percent: 100
  value_col:
    x: 80
    "y": 0
    width_percent: 100
    height_percent: 100
text:
  label:
    content: POWER
    zone: label_col
    position: center
    font_size: 16
  value:
    content: "{entity.state}"
    zone: value_col
    position: center
    font_size_percent: 70
    font_weight: bold
debug_zones: true

Custom zone names that match an auto-zone name (e.g. body) replace the auto-calculated bounds entirely, so you can shrink or reposition the primary zone too.

Zones can also be managed visually in the Zones tab of the card editor — draw, resize, and name zones without touching YAML.

---

Debug Overlay

When designing a layout, add debug_zones: true to the card config to render a colour-coded overlay of every zone with its name:

debug_zones: true

The toggle is in Zones → Developer Tools in the editor. Remove it (or set to false) before saving your final dashboard config.

---

What Works With Zones

Zones are supported on all three cards today. Here's the compatibility matrix:

Feature	Button	Slider	Elbow
Auto-zones	✅	✅	✅
zone: routing	✅	✅	✅
font_size_percent	✅	✅	✅
stretch	✅	✅	✅
config.zones (custom)	✅	✅	✅
debug_zones overlay	✅	✅	✅
Editor Zones tab	✅	✅	✅

All template syntaxes (token {...}, JavaScript [[[...]]], Jinja2 {{...}}, DataSource {ds:...}) work inside the content property of any text field.

---

Further Reading

• Text Fields reference — all text field options, inheritance model, background labels, display format
• Zones reference — zone tables per card, custom zones, debug overlay