visuals: print styles for the wall and the diagrams, and Phase 7 notes

- Diagrams carry a print style block, so they print as ink on white rather than
  as dark panels; the client wall and the chips go white with a hairline.
- docs/phase-7-notes.md records what batch 1 shipped, how to add a mark or an
  image, and the Lighthouse measurements taken after the batch (100/100/100/100,
  CLS 0, mobile and desktop).

(cherry picked from commit ae9282e5f62b8c7ee149ebf96f8d3f00067a49e2)
This commit is contained in:
2026-10-28 15:51:52 +11:00
parent a76882de67
commit 6ac0e1ff47
4 changed files with 120 additions and 0 deletions

71
docs/phase-7-notes.md Normal file
View File

@@ -0,0 +1,71 @@
# Phase 7 — notes
Running record for the visual layer (AUD-149). Each batch states what changed,
what it measures, and what it still needs.
---
## Batch 1 — marks, area icons, client wall, two diagrams
### What is in the tree
| Piece | Where | Note |
|---|---|---|
| Technology marks | `internal/brand/` | 50 Simple Icons paths (CC0), inlined as 16 px `currentColor` SVG. No request, no font, no bundler. |
| Regenerator | `tools/gen_brand_icons.sh` | Development-time only. The generated Go file is committed, so `make build` never needs the network. |
| Area icons | `internal/web/templates/icons.templ` | Six marks drawn for this site, plus one for the evidence index. 24×24, 1.6 px stroke, `aria-hidden`. |
| Client wall | `content/history/l3/history-client-wall.md` + `.client-wall` in `site.css` | 45 names, one typeface, one size, one grid of equal tiles. No client mark is used, because none has been approved. |
| Diagrams | `content/assets/diagrams/` | Homelab topology and RAG pipeline. Both referenced from the page they explain. |
| Image sizing | `internal/content/markdown.go` | Every content image gets intrinsic `width`/`height`, `loading="lazy"`, `decoding="async"`. |
| Guard | `internal/site/site_test.go` | `TestImagesReserveTheirSpace` fails if an image ships without size or alt text. |
| Topbar | `site.css` | Two rows at desktop. One row overlapped the search form once the marks were added; Lighthouse `target-size` caught it. |
| Favicon | `internal/web/static/favicon.svg` | Stops the browser asking for a missing `/favicon.ico` (it was the only console error). |
### Adding a technology mark
1. Add the label → slug pair to `slugs` in `internal/brand/brand.go`.
2. Add the slug to `slugs()` in `tools/gen_brand_icons.sh` and run it.
3. `make dist`, then check the chip on the page.
A technology with no published mark renders as text alone, on purpose: a chip
with a missing image would read as a broken page.
### Adding an image
- File goes under `content/assets/` (published at `/assets/...`).
- SVG needs explicit `width` and `height` on the root element; PNG and JPEG are
measured with `image.DecodeConfig`. Both give the page its reserved space.
- Alt text describes the thing, not the file name.
- The diagrams carry their own print style, so they print as ink on white.
### Measurements (2026-10-28)
Lighthouse 12.8.2, headless Chrome, against the local server on `127.0.0.1`.
| Page | Mode | Performance | Accessibility | Best practices | SEO | CLS |
|---|---|---|---|---|---|---|
| Landing | mobile | 100 | 100 | 100 | 100 | 0 |
| Landing | desktop | 100 | 100 | 100 | 100 | 0 |
| Platform network (diagram) | mobile | 100 | 100 | 100 | 100 | 0 |
| AI retrieval (diagram) | desktop | 100 | 100 | 100 | 100 | 0 |
| Client wall | mobile | 100 | 100 | 100 | 100 | — |
| Edge audio artefact | mobile | 100 | 100 | 100 | 100 | — |
Total page weight: landing 153 KiB, diagram page 105 KiB. Diagram files are 5.7
KiB and 6.6 KiB; the stylesheet is 24 KiB; htmx is 51 KiB and is the largest
single asset.
Two defects were found by measurement rather than by eye and fixed in this
batch: the desktop topbar overlap, and the missing favicon.
### Still open — needs Sam
| DoD line | State | What is needed |
|---|---|---|
| At least one real photograph in use | Not started | Which photographs may be used (Immich on `.35` is the likely source). Anything used is checked for people, address and screens in shot. |
| Two screenshots in use | Not started | Approval to capture Home Assistant, Gitea, TUIOS with agent panes, or Graphify's `graph.html`. Screens must contain nothing personal. |
| One recording, 30–60 s | Not started | Either Sam records it, or Sam approves a recording of the agent console. |
| Client wall marks | Deliberately absent | Official marks only, with Sam's approval. Nothing invented. |
Nothing above is blocking the site: it ships, measures 100 across the board, and
every page works with the AI services stopped.