Before writing any widget code, note that several properties of the widget's runtime can change while your widget is running, without a reload. Widgets should ideally be written so that these properties are read dynamically, not captured at initialisation.
| What can change? | Consequence if ignored | Correct pattern |
| Graphical theme (dark / light / blue) — the user can switch at any time, without a restart (§2.14, §4.12) | Any hard-coded colour will be wrong in at least one theme and will not update when the user switches | Use --clr-* CSS variables with a fallback; for canvas/SVG, read the computed value at draw time and redraw on the THEME message. Or, use selectors which vary with CSS class set by the graphical theme by using |
| Document direction (LTR / RTL) — set based on the user's language (§6.1.1, §6.1.2) | Layouts using physical properties (padding-right, left: 0) will appear broken in Arabic / Hebrew | Use CSS logical properties (padding-inline-end, inset-inline-start) instead |
| Widget size — the user can resize docks and floating windows freely | Fixed-pixel layouts will clip or leave dead space | Use flexbox / grid; test at narrow widths including BrowserPhoneScreen (§6.1.1) |
The rule of thumb: never capture these at initialisation. Read them when you need them, and subscribe to the relevant OnMessage type to react to changes.