diff options
| -rw-r--r-- | docs/superpowers/specs/2026-09-17-system-widgets-design.md | 99 |
1 files changed, 87 insertions, 12 deletions
diff --git a/docs/superpowers/specs/2026-09-17-system-widgets-design.md b/docs/superpowers/specs/2026-09-17-system-widgets-design.md index eea3a88..9fee4a5 100644 --- a/docs/superpowers/specs/2026-09-17-system-widgets-design.md +++ b/docs/superpowers/specs/2026-09-17-system-widgets-design.md @@ -134,22 +134,97 @@ All four follow the fluid convention documented in the README: sizes derive from `inner.w` with clamps, the slack is distributed deliberately, and an element that cannot fit drops out rather than overlapping. -### A shared bar primitive +### One colour language across all four cards -`lib/card.lua` gains `card.bar(cr, x, y, w, h, frac, colors, colour)`: a track -with a filled portion. Three of the four widgets need it (per-core load, RAM, -filesystem usage), which is the third use that earns the abstraction rather -than each widget drawing its own rectangles. +Every quantity that has a comfortable range and an uncomfortable one is +coloured the same way, so a glance at any card reads without learning a new +scheme: -It takes an explicit colour so a bar can turn `colors.critical` past a -threshold, which is what makes a filesystem at 84% readable at a glance. +| State | Role | Meaning | +|---|---|---| +| fine | `ok` | below the first threshold | +| busy | `warning` | between the thresholds | +| nearly full / hot | `critical` | above the second | + +**`warning` is new to the dashboard palette.** `dashboard.lua`'s `palette()` +exposes `ok` and `critical` but no middle colour. `udt-palette` already +resolves `warning` in every scheme: it maps `yellow`, or Nord's +`aurora_yellow`, to that role globally, the same way it maps `red` to +`critical` even though `[conky]` never lists it, and other generators already +read `res['warning']`. + +Three places, one line each, none of them a scheme file: + +1. `bin/udt-palette` (UDT repo), `gen_conky`: add `"warning"` to the tuple of + roles it substitutes. `critical` was added to that same tuple for the error + overlay, so this is the established way. +2. `conky.conf.in`: a `color8 = '@WARNING@'` line. +3. `dashboard.lua`'s `palette()`: `warning = hex(CFG.color8)`. + +Scheme switching keeps working untouched, and every existing scheme gets the +colour for free. + +Thresholds by kind: + +- **Filesystems and cache**: 25% and 75%, as requested. +- **CPU load**: the same 25/75, so a core at rest, a core working and a core + pinned are distinguishable at a glance. +- **Temperatures**: per sensor, because 70C is unremarkable for a CPU and + alarming for an NVMe. Each carries its own pair in the widget's binding + table, alongside the hwmon path it already needs: + + Tctl 75 / 90 + Tccd1 75 / 90 + NVMe 60 / 70 + Arc pkg 75 / 85 + Arc VRAM 80 / 90 + board 60 / 70 + + These are starting values, host-specific exactly as the hwmon bindings are, + and sit in one table so they are easy to retune once real numbers under load + are known. + +### Shared primitives in `lib/card.lua` + +`card.bar(cr, x, y, w, h, frac, colour)` — a track with a filled portion. + +`card.ring(cr, cx, cy, r, frac, colour, colors)` — an open circle with an arc +covering `frac` of it, after `idea2.png`: the arc starts at twelve o'clock and +sweeps clockwise, over a dim full-circle track, with room at the centre for a +glyph. + +`card.threshold(frac, warn, crit, colors)` — returns the colour for a value +against two thresholds. One function so all four widgets agree, and so the +rule is stated once rather than re-derived per card. + +### The per-core row as an equaliser + +Sixteen vertical bars across the card, each rising from a common baseline with +its core's load, coloured by the same thresholds. Reads as a level meter: idle +cores sit low and green, a compile lights the whole row amber to red. + +Bar width and gap derive from the cell. Below the width where sixteen bars +would each be thinner than about 3px the widget drops to the aggregate bar +alone rather than drawing an illegible grey smear, which is the same +drop-rather-than-crush rule the weather arc follows. + +### The disks as rings + +After `idea2.png`: one ring per filesystem, each with an icon at its centre +naming what it is (a drive glyph for local, a network glyph for NFS), the arc +showing usage and coloured by threshold. The mount point and percentage sit +beside or beneath depending on how many fit across the card width. + +Rings wrap to as many rows as the cell allows and, past the point where a ring +would be too small to read, the widget falls back to the labelled horizontal +bars `card.bar` already provides. -### The per-core row +### Cache -Sixteen thin vertical bars across the card width is the one novel layout. Bar -width derives from the cell, and below the width where sixteen would be thinner -than about 3px the widget drops to the aggregate bar alone rather than drawing a -grey smear. +The total as a heading, then the four largest subdirectories. The largest is +drawn in `warning` (or `critical` if it dominates, over half the total) while +the rest stay in `value`, so the thing worth deleting is the thing that catches +the eye. ## Staleness and failure |