Max Gramser
d76461d774
The two board profiles (5,000 lines each, 87 % the same text) become packages/core.yaml and one file per board under packages/boards/: the hardware, a table of 84 sizes and font sizes, 18 hooks with the lines of C++ only that board adds inside a shared lambda, and the board's own sections. packages/cyd.yaml and packages/guition.yaml keep their names and places (a screen installed from ESP Screens builds as before); home-like-2432s028.yaml and guition-4848s040.yaml become the same entries for a checkout. The firmware stays 0.2.70: the C++ ESPHome generates for each board, through the checkout profile and through the GitHub package route, was compared line by line with the old profiles' (docs/TEST_RESULTS_0284.md). tools/check_packages.py replaces tools/generate_packages.py; tools/profiles.py gives the tests and tools the three files as one; docs/PROFILES.md says how the files fit together and how a board is added. Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>
85 lines
5.7 KiB
Markdown
85 lines
5.7 KiB
Markdown
# 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.
|