ZephUI layout

Every board hands your app a safe area — the region between the status band at the top and the close bar at the bottom. Lay your screen out inside it, and read it off the board at launch: it is a different shape on every device.

The safe area, on every board

Status

Content

Status band — the clock, battery, connection.

Your content — the safe area you lay out in.

Close bar — the system exit, always yours to keep.

Screen 368×448·Safe area 332×362

The same insets the device enforces, drawn to scale. Switch boards to see how the content region changes.

Pick a layout

A screen does not place things by pixel. It picks one of four built-in layouts, and the layout owns the safe area and where the regions sit — you just fill them.

The built-in screen layouts

FoundationThe default. Content from the top, scrolls when there is more.

CenteredOne thing in focus — a now-playing card, a status.

ListA menu or settings — a title that stays, rows that scroll.

PinnedContent with one action — it scrolls, the button stays.

Pick one for a screen and it owns the safe area and the regions — you fill them.

Start from Foundation and reach for another when the screen calls for it. Inside any of them you compose: a row puts children side by side, a list stacks rows, a section groups them under a heading. Build the screen up from these pieces rather than hand-placing it — that is what lets the same screen sit correctly on a tall panel and a round one alike.

The scroll rule: a screen root scrolls, so content past the fold stays reachable. A box or list root does not — anything past the fold is unreachable, and a screenshot will never reveal it. Budget eight to ten children.

Compose with columns

Two containers arrange children in two dimensions, so a screen reads like a small dashboard instead of one long column.

box — a flex line. Set axis to row or col, a gap between children, and how they distribute (pack from the start, or sb for space-between).
grid — a wrapping grid of equal columns. cols is 1–4. A child spans columns with span (a span: 2 cell is two columns wide — a hero over a pair of tiles), and fill: 1 stretches the grid to the remaining height with its cells — and their buttons — filling to match, instead of sitting content-height at the top.

{ "k": "grid", "cols": 2, "fill": 1, "c": [
  { "k": "btn", "t": "Now Playing", "span": 2 },
  { "k": "btn", "t": "Volume" },
  { "k": "btn", "t": "Skip" }
] }

Every surface speaks the same words. What you write here as a device app is the same box/grid an agent pushes over MCP and the same shapes the glance templates (Grid, Hero, Dashboard, Corner) are built from — one layout language, three ways in.

Every board's numbers

Usable width and usable height are different numbers on every board — read the axis, not the larger number.

Waveshare

AMOLED 1.8"

ESP32-S3-Touch-AMOLED-1.8

Panel

Shape: rect
Resolutionpx: 368 x 448
Physical sizemm: 28.7 x 34.94
Corner radius: 59 px / 4.6 mm

Safe area

Insetstop / right / bottom / left, px: 52 / 18 / 34 / 18
Usable WIDTHhorizontal axis: 332 px
Usable HEIGHTvertical axis: 362 px

Hardware

Touch: Yes
Buttons: main: tap, double, holdaux: tap, double
Microphone: single
Speaker: Yes
IMU: Yes
Real-time clock: Yes
SD card: Yes
Haptics: No
Battery: Yes
FlashMB: 16
Firmware board: zeph/zeph_v0_amoled_eval

AMOLED 1.75" round

ESP32-S3-Touch-AMOLED-1.75C

Panel

Shape: round
Resolutionpx: 466 x 466
Physical sizemm: 44.45 x 44.45
Corner radius: 233 px / 22.2 mm

Safe area

Insetstop / right / bottom / left, px: 50 / 64 / 50 / 64
Usable WIDTHhorizontal axis: 338 px
Usable HEIGHTvertical axis: 366 px

Hardware

Touch: Yes
Buttons: main: tap, double, holdaux: tap, double, hold
Microphone: dual
Speaker: Yes
IMU: Yes
Real-time clock: No
SD card: No
Haptics: No
Battery: Yes
FlashMB: 32
Firmware board: zeph/zeph_v1_amoled_175c

AMOLED 2.06"

ESP32-S3-Touch-AMOLED-2.06

Panel

Shape: rect
Resolutionpx: 410 x 502
Physical sizemm: 33.09 x 41.51
Corner radius: 111 px / 9.2 mm

Safe area

Insetstop / right / bottom / left, px: 64 / 36 / 48 / 36
Usable WIDTHhorizontal axis: 338 px
Usable HEIGHTvertical axis: 390 px

Hardware

Touch: Yes
Buttons: main: tap, double, holdaux: tap, double
Microphone: dual
Speaker: Yes
IMU: Yes
Real-time clock: Yes
SD card: No
Haptics: No
Battery: Yes
FlashMB: 32
Firmware board: zeph/zeph_v1_amoled_206

AMOLED 2.16"

ESP32-S3-Touch-AMOLED-2.16

Panel

Shape: rect
Resolutionpx: 480 x 480
Physical sizemm: 43.3 x 43.3
Corner radius: 72 px / 5.8 mm

Safe area

Insetstop / right / bottom / left, px: 56 / 40 / 56 / 40
Usable WIDTHhorizontal axis: 400 px
Usable HEIGHTvertical axis: 368 px

Hardware

Touch: Yes
Buttons: main: tap, double, holdaux: tap, double, holdpower: tap, double
Microphone: dual
Speaker: Yes
IMU: Yes
Real-time clock: Yes
SD card: Yes
Haptics: No
Battery: Yes
FlashMB: 16
Firmware board: zeph/zeph_v1_amoled_216

ZephUI layout

Pick a layout

Compose with columns

Every board's numbers

Waveshare

On this page