docs: record the visual identity in DESIGN.md

DESIGN.md states the two rules that carry the board's identity (big value
at the card's top-right, rows label-left/value-right), plus the type,
colour and glyph conventions, with AGENTS.md pointing at it for anyone
adding a widget.

3 files changed, 108 insertions, 0 deletions

diff --git a/AGENTS.md b/AGENTS.md
new file mode 100644
index 0000000..ff8abc9
--- /dev/null
+++ b/AGENTS.md
@@ -0,0 +1,34 @@
+# Agent notes
+
+Project-level guidance for this repository. The global agent preferences still
+apply; this file only adds what is specific to `conky-theme-udt`.
+
+## Read this first
+
+`DESIGN.md` is the repository's visual identity. Before adding or changing a
+widget, read it and match it: the big value at the card's top-right, rows
+label-left / value-right, one fluid type size, the `ok` / `warning` / `critical`
+colour language. A new card that ignores it is a defect, not a style choice.
+
+## Working on the dashboard
+
+- After editing a widget or `dashboard.lua`: `./restart.sh`. Conky caches a
+  required widget module, so a widget edit needs the restart; editing
+  `dashboard.lua` alone does not.
+- Only a `conky.conf.in` or palette change needs
+  `../unified-desktop-theme/install.sh`, which re-renders `conky.conf`.
+- Checks: `lua test/test_data.lua && lua test/test_layout.lua && lua test/test_weather.lua`
+- Render one widget offscreen without conky:
+  `lua test/render.lua <widget> <cols> <rows> <wspan> <hspan> <out.png>`
+- The offscreen renderer crops to a single card, so it says nothing about size
+  beside neighbours. Check the live dashboard for that.
+
+## Constraints
+
+- This repository is public: no keys, real locations, LAN addresses, hostnames
+  or usernames in committed files. Derive per-host data at runtime; use
+  `Example City` / generic placeholders in fixtures.
+- A Lua error in conky is a blank screen with no message. The `pcall` overlay in
+  `dashboard.lua` is the only reason faults are visible, so parsers and widgets
+  return nil or a safe default rather than raising.
+- Commits are GPG-signed.
diff --git a/DESIGN.md b/DESIGN.md
new file mode 100644
index 0000000..2249fac
--- /dev/null
+++ b/DESIGN.md
@@ -0,0 +1,72 @@
+# Design language
+
+The dashboard's visual identity. Every card follows it, so one glance reads the
+whole board without relearning a scheme per card. Follow this file when you add
+or change a widget; the primitives it names live in `lib/card.lua`.
+
+## Card anatomy
+
+A card is a rounded rect (`card.card`) with padding. Its content runs top to
+bottom:
+
+- **Header.** The title, or the glyph that stands in for it, sits top-left in
+  the `label` colour. The card's **big number** sits at the right edge, on the
+  same line, in `FONT_HEAVY`. Nothing else shares that line.
+- **Body.** Rows follow one pattern: **label left, value right**
+  (`card.text` and `card.text_right`), so the eye runs down the right edge for
+  numbers. A row's value takes the `threshold` colour when it is a measured
+  quantity, and stays in `value` when it is not (a fan RPM, a total).
+- **Variable band.** One element may absorb the height left over, chosen per
+  card: the equaliser in `system`, the daylight arc in `weather`, the ring row
+  in `disks`. Or the type itself fills the cell.
+
+Failure states keep the chrome and draw a notice in it ("no cache data", `--`
+for a missing sensor). An empty cell is indistinguishable from a crashed
+widget, so a card never draws nothing. A missing sensor is `--`, never `0`:
+zero is a legitimate reading.
+
+## The two rules that carry the identity
+
+1. **The big value sits at the card's top-right.**
+2. **Rows run label-left, value-right.**
+
+Everything else exists to keep those two readable at any cell size.
+
+## Type
+
+- **Fluid, filling the cell.** Derive one base size from the cell: the smaller
+  of a width fit and a height budget. `card.fit_unit` measures candidate rows
+  and returns the largest base size that fits the width, and a row that would
+  collide pulls the size down. Bigger cell, bigger type instead of empty space.
+  The `system`, `gpu` and `cache` cards do this; a card that cannot afford the
+  measuring pass may key off width with a clamped factor.
+- **Roles.** `FONT_MONO` for labels and row text, `FONT_HEAVY` for the big
+  number, `FONT_UI` for prose (a condition description, a notice). Sizes within
+  a card keep their ratios.
+- **Scale by the rect, not fixed pixels**, offsets included. The same widget
+  must compose at any cell size the grid gives it.
+
+## Colour
+
+One language for every measured quantity, so state is read rather than decoded:
+
+| State | Role | Example |
+|---|---|---|
+| fine | `ok` | a cool sensor, an empty filesystem |
+| busy | `warning` | a core under load, a filesystem past 25% |
+| hot / full | `critical` | a sensor at its ceiling, a nearly full disk |
+
+- Proportions (CPU load, filesystem and cache usage) use **25% / 75%**.
+- Temperatures use a **per-sensor pair**, because 70C is unremarkable on a CPU
+  and alarming on an NVMe. The pairs live beside the hwmon bindings in the
+  widget.
+- `warning` is the palette's middle role. The board should show all three
+  states in normal use, or the language is not earning its place.
+
+## Glyphs
+
+Nerd Font glyphs stand in for labels where an icon reads faster than a word:
+the disks rings put a distro / house / disk / network glyph at each ring's
+centre, weather puts the condition glyph in its header. A wrong-but-present
+codepoint draws a plausible neighbour rather than failing, so render a new
+glyph and look at it before trusting it.
diff --git a/README.md b/README.md
index 71efc9e..ba3e260 100644
--- a/README.md
+++ b/README.md
@@ -153,6 +153,8 @@ grid or the screen changes.
 
 ## Writing a widget
 
+`DESIGN.md` is the visual identity every card follows; read it first.
+
 A widget module exports one function, `draw(cr, rect, colors)`. `lib/card.lua`
 carries the primitives it should use rather than reaching for Cairo directly: