# 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. A card whose data
  lives entirely in its variable band drops the big number and lets that band be the value.
- **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 daylight arc in `weather`. 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 `cache` card does 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 fresh cache, a current changelog |
| busy | `warning` | a cache past 25% |
| hot / full | `critical` | a cache past 75%, a stale changelog |

- Proportions (cache usage) use **25% / 75%**.
- `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.
- The big value's colour follows what it is: `body` for a plain number, the
  threshold roles when it is a measured quantity, the phase's own role in
  `breaktimer`, and `heading` when it names rather than measures (the calendar
  month).

## Glyphs

Nerd Font glyphs stand in for labels where an icon reads faster than a word:
weather puts the condition glyph in its header, and every card title
carries one in `highlight` before its label (the codepoints live in
`card.ICON`). A wrong-but-present codepoint draws a plausible neighbour rather
than failing, so render a new glyph and look at it before trusting it.