Round dashboards: shape and ring, the ring drawn and turned in every look, Knob preset and face guide in the editor

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

docs/interface/dashboards.md

@@ -168,6 +168,52 @@ Background draws an image beneath the widgets. Lock disables publishing from
 controls and shows **Read-only** when viewing the dashboard. It does not
 restrict API permissions and does not disable controls in edit mode.
 
+## Round dashboards
+
+For a round screen such as a rotary knob, set the canvas to **Round** in the
+dashboard settings, or pick the **Knob** preset (360×360). A round dashboard is
+drawn in the circle its canvas holds, so its canvas is square (`shape: "round"`
+forces `canvas_height` to `canvas_width`). Tiles are drawn without a card, and
+there is no rail; a panel with several dashboards shows page dots instead.
+
+One Slider, Selector, Colour or Gauge can go **On the ring** (`ring: <widget
+id>`): it is drawn along the edge instead of in the grid. Drag along the ring or
+use the mouse wheel; one notch is one step, one option or one hue step
+(`hue_step`, default 5°, wrapping). The value moves at once and is published
+once, 300 ms after the last notch or when the pointer is released. A gauge on
+the ring only shows. When the ring is the only widget, its reading is written
+large in the middle.
+
+The editor shades what lies outside the circle and warns about tiles whose
+corners leave it. Inputs, button grids, charts, forecasts, agendas, websites
+and a segmented Selector are marked as a poor fit, but allowed.
+
+### Geometry
+
+Devices that draw dashboards natively use these numbers. They are canvas
+pixels, scaled with the canvas; S is the canvas width. Angles are degrees
+clockwise from three o'clock.
+
+| Part | Value |
+|---|---|
+| Face | circle of diameter S at (S/2, S/2); nothing is drawn outside it |
+| Ring band | 40 along the edge, only when a ring is set |
+| Grid area | the square inset by 12, plus 40 with a ring; columns, rows and cell proportions as on a rectangular canvas. Knob, 4 columns, ring: 256×256, columns 55, rows 30 at a 42 pitch, 6 rows |
+| Safe circle | radius S/2 − 40 with a ring, S/2 without; a tile corner outside it is warned about |
+| Ring arc | start 120°, sweep 300° (ends at 60°), centre-line radius S/2 − 20, stroke 16 with round caps |
+| Slider | track over the sweep, value arc from the start to the value (none at the minimum), handle 28 across |
+| Selector | a 6 mark per option at i/(n−1) of the sweep (one option: the middle), the selected one under the handle; no wrap |
+| Colour | hue h at h/360 of the sweep, red at both ends; the handle is filled with the colour |
+| Gauge | track and value arc, no handle |
+| Gap line | centred at y = S − 28, 13 high, at most 160 wide: the title (muted), then the reading unless it is in the middle; a colour has none |
+| Page dots | 6 dots 16 apart, centred at y = S − 12; the current one in the text colour, the others muted at half opacity |
+| Centre reading | value 72 with its unit at 0.4 em, muted; a Selector's label 36; a colour swatch 96 across with a hairline border |
+| Tiles | no surface, border or shadow; padding 8; title 12, muted and centred; a single reading centred |
+
+Paint follows the look: Fluksio draws a muted track, a primary value and a
+handle of the ground colour ringed in primary; Material a tonal track and a
+primary handle; Glass a translucent track, a glowing value and a white handle.
+
 ## Showing one
 
 Open `/view/{name}` for a dashboard-only view with your normal session.