# Designing screens

A "screen" is one image a device can display — a calendar view, a weather forecast, a lunch menu. Each
device has a YAML config file (under `CONFIG_DIR`, normally `configs/`) that declares its data sources
and the set of screens it can show, plus a schedule of when to show each one.

Getting a screen onto the panel goes through three stages:

1. **Config** — the device's YAML file says which Jinja template renders a given screen name, and what
   named data sources (a calendar feed, a weather API) are available to it. See
   {doc}`config-format`.
2. **Template → XML** — the template (`configs/**/*.xml.jinja`) is a Jinja template whose *output* is an
   XML document: a small markup vocabulary of layout and content tags (`<box>`, `<column>`, `<text>`,
   `<image>`, …). Jinja handles anything dynamic (pulling data from a source, looping over calendar
   events, date formatting); the tags it emits describe the static layout. See {doc}`templates` and
   {doc}`../widgets/index` for the full tag reference.
3. **XML → image** — the resulting XML tree is walked, each tag composited into a `PIL.Image`, and the
   final image is saved in the device's raw e-paper format (or PNG, for previewing).

The fastest iteration loop while designing a screen is the `todays_paper` CLI (see
{doc}`../installation`), which renders straight to a PNG without needing the server running:

```bash
uv run todays_paper dev -s family_calendar -o preview.png
```

To start from something that already works, see the {doc}`../examples/index`.

```{toctree}
:hidden:

config-format
templates
```