homeassistant_espscreen/docs/THEME.md

Colours and Dark mode

Every colour the screens choose themselves lives in one file, components/smart_display/theme.h (firmware 0.2.54+). Dark mode is a second value for each of them, not a second design: the layout, the fonts and the sizes stay exactly as they are. This page says how the colours reach the glass and what a new colour takes.

The model

Part	What it is	Where
Role	What a colour is for (PAGE, CARD, INK, MUTED, KEY_PRESSED, ...), with a light and a dark value	theme::ROLES, the table at the top of theme.h
Swatch	A named card colour a tile or an alert can pick (red ... gray), light and dark	theme::SWATCHES
State colour	Home Assistant's colour for a state (the amber of a light that is on), the same in both looks	theme::ha
Paint	A shared LVGL style filled from roles: card is a card's background, hairline and text	theme::Paint, theme::PAINTS
Look	theme::dark, set by theme::set_dark() from the Dark mode setting	settings_screen::dark_mode

The light values are the design as it has always been; tests/test_theme.cpp pins the main ones. The dark values follow a few rules: a black page, graphite cards (#1A1A1A) with a hairline, soft white text (#DADADA) and greys for secondary words, Home Assistant's state colours unchanged, their tints a little stronger over graphite, and a grey whose red, green and blue land on the same step of the RGB565 panel, so it stays grey on both boards.

How a colour reaches the glass

• Board profiles write no colour. A widget names a paint, styles: paint_card, or a style that carries one (style_page, style_tile, style_room, ...). The style definitions have no colour; on_boot sets theme::paints to the list of theme::fill(id(style), Paint::...) calls and runs it. The list is code in flash, not a table in RAM, and theme::set_dark() runs it again. Scripts that colour a widget by state ask for a role: theme::color(selected ? theme::ACCENT_BRIGHT : theme::CARD).
• Firmware asks for roles: theme::color(theme::INK), theme::hex(theme::MUTED), the detail_text(..., theme::SUBTLE) and detail_shape(..., theme::TRACK, ...) overloads. A widget that lives as long as the screen and never changes colour by state takes a paint too: lv_obj_add_style(obj, theme::style(theme::Paint::knob), LV_PART_KNOB).
• State colours pass through a helper on their way to the glass: state() (Home Assistant's greys become the dark greys), foreground() (a glyph, a line or words: deep colours are lifted in dark), tint() (the pale circle, a halo, a slider track), icon() (a tile's icon), surface() and outline() (a card's own colour and hairline), key_on() (keys inside a card of any colour) and fill_opacity() (the area under a graph).

A change of look

settings_screen::set("dark_mode", ...) stores the setting in its own preference (DRK1), runs apply_screen_settings, and that calls theme::set_dark(). A look the screen already has costs nothing. A real change runs theme::paints, refills the firmware's own paints, tells LVGL once, and calls theme::redraw, set in on_boot, which draws again what code painted by state:

• runtime_tiles::restyle(): every tile's palette, the top bar's icons, and an open card, in place;
• light_controls::restyle(), settings_screen::restyle();
• an alert that is up (theme::surface(id(alert_card_color))), and the climate card and its mode picker when they are open.

Everything happens in the same pass, so no frame shows half of each look. At boot set_dark() runs before the first frame.

A redraw has to give exactly what a first draw gives, whatever came before it. Two things that did not were found by comparing a screen that switched with one that booted in that look: a position worked out from coordinates LVGL had not laid out yet (they read 0 until its next pass: use the size you set), and a palette pass that overwrote a colour the sun path had chosen itself.

Adding a colour

1. A role: one line in enum Role and one row in ROLES, in the same order (the tests read both). The light value is the design; choose the dark value on a render, not in the table.
2. In firmware code: theme::color(theme::YOUR_ROLE). Never lv_color_hex(0x...).
3. In the profiles: the widget takes a paint. For a new combination add it to enum class Paint and PAINTS, a colourless - id: paint_<name> in the style_definitions of packages/core.yaml (or of one board file, for a paint only that board uses), and theme::fill(id(paint_<name>), Paint::<name>); in the core's theme::paints list (a board-only paint goes into the board's BOARD_PAINT_FILL hook).
4. Something drawn once and kept that changes colour by state: set it where the state is drawn, and make sure the redraw above reaches that code.
5. A local colour always wins over a paint: an object that takes a paint must not also get a local colour for the same property and part.

Checks

• tests/test_theme.cpp: the light design, contrast of the text roles on every surface and swatch in both looks, neutral dark greys, and the helpers.
• tests/test_theme.py: no colour outside theme.h (the light's colour picker and the value card's colour wheel keep their hues), every paint defined, filled once and used, and the look applied at boot, after a change and in the redraw.
• Renders of the host build in both looks (see docs/RELEASING.md, Compatibility 0.2.63): the light look pixel for pixel against the previous firmware, a screen that boots dark against one that switched, and every card opened in light and switched while open against the same card opened in dark.