esh-pfi-infrastructure/persistent-memory.d/2026-08-19-homepage-skyfall-theme.md

[2026-08-19] Homepage cleaned up, then themed with Australis Skyfall + an Arbo-generated background

Commits 9d92c4b, c3de7db, 45c1995, f38cf69, df68dd2.

The cleanup (three real defects)

• UltraSeedbox rendered on all four tabs. The bookmark group had no entry in settings.yaml's layout: block at all, and Homepage's documented behaviour is that a group with no tab: is shown on every tab. Pinned to Main. ⚠️ This will happen again to the next group added without a tab: — the rule is now written at the top of the layout block.
• Uptime Kuma rendered twice — a manual services.yaml entry under Monitoring and homepage.group=Apps on the container. Exactly the "never list a labelled container manually" failure the stack README warns about; it survived the previous day's audit because a duplicate reads as two plausible cards rather than as an error. Manual block deleted, label moved to Monitoring, homepage.siteMonitor added.
• Column counts were fiction — several groups declared more columns than they had members, so the last row of each was dead space (Notes: 1 card in a 4-wide row). Columns now track member counts; GET /api/services prints the live per-group counts and is the check.

Later, on operator instruction, the AI tab was reordered by clickability: Gateways & Chat → Image & Media → Audio Tools on top, then the vLLM /docs seats and TTS endpoints. Reasoning written into the config so it survives: order by "would I click this?", not by how central the service is.

⚠️ The expensive red herring — the tab bar after a recreate

After a recreate the client render comes up with no tab bar, no wallpaper and no i18n (search box shows the raw key search.search), groups falling back to side-by-side columns. It restores itself with no intervention.

Timing, measured rather than assumed: a fresh container was still tab-less at 4m30s, twice; it was healthy again after roughly an hour. docker ps reporting healthy says nothing about it — the container is serving, the page is just wrong.

An hour went into ruling out four causes that were never the cause:

1. Not the config — restoring settings.yaml and services.yaml to their committed versions reproduces it, as does the pre-adoption backup in /opt/docker-bu/conf/homepage/.
2. Not the v2.0.0 release — a throwaway container on v1.13.2 shows identical symptoms, and the image never changed anyway (working and broken both report v2.0.0 / rev 17456f2).
3. Not PUID/PGID, and not Docker discovery — tested both, and with the socket unmounted entirely.
4. Not server-side — the server-rendered HTML still contains the tab markup, the background URL and useEqualHeights; GET /api/validate returns []. The loss is client-side, with no page error, no failed chunk and no non-200.

Every throwaway container in that list was judged within ~30s of starting, so they were all inside the same window — and that consistency read as a reproduction when it was the same measurement mistake five times over.

Operative rule: recreate, walk away, re-check later. Do not chase it.

⚠️ The iteration loop that would have prevented the overcook

custom.css is served per request from /api/config/custom.css, so a CSS change needs a browser reload — not a container recreate, and it never owed the layout warm-up above. Conflating the two costs ~10 operator-visible minutes per attempt (operator called this out directly).

Faster still, and how the final pass was done: inject candidate CSS into the running page and screenshot it — await p.addStyleTag({content: css}) in Playwright against the live dashboard. Seconds per iteration, no deploy. Build + deploy only once the render looks right.

The theme — Australis Skyfall

Operator supplied a Claude Design handoff bundle via the Booth (26-copper). Skyfall is a dual-theme OKLCH system: one lightness law across every chromatic family (deep 0.48 / base 0.66 / bright 0.80), all hues cooler than neutral, a Sea neutral ramp drifting ice-blue→ocean-green as it brightens, and a "calm depth" language of hairline + two-layer shadow on every elevated surface, never one without the other.

theme/colors.css layout.css typography.css   vendored VERBATIM from the bundle
theme/fonts/Supreme-{400,500,700}.woff2      the body/UI face
theme/skyfall.css.in                         the Homepage bindings (ours)
theme/build.py            → conf/custom.css  (generated — do not hand-edit)

The build step exists for one reason: Homepage serves only custom.css and custom.js out of its config dir, with no static route beside them, so a @font-face pointing at a vendored .woff2 would 404 — the face must arrive as a data URI. The background image takes the other road, because /app/public/images is a real static route (mounted read-only in compose.yaml).

Only Supreme is embedded: a link dashboard has no display type, and Victor Mono ships as 2.4 MB TTF statics per cut — 30x the whole stylesheet for a handful of latency figures.

The background is generated, not stock

Arbo as an image-gen engine (the operator's actual ask, which I first misread as "use Arbo's palette" and had to redo). Arbo's t2i-ui-background workflow is purpose-built: "abstract full-bleed backgrounds, no subject". Job 13f0891f4e42, seed 26, flux2-klein-9b, 2048×1152, 1.6 MB PNG → 22 KB WebP (smooth gradients compress absurdly well).

⚠️ Arbo API gotcha: prompt is a discriminated union, not a string — a bare string 422s. {"kind":"raw","text":…,"negative":…} is the shape.

Two documented deviations from the design system

1. Skyfall forbids this background. Its rule is "flat semantic surfaces; no photography, no textures", with one permitted motif — a subtle aurora gradient on hero/empty-state areas only, "never behind body text blocks". A dashboard is a body-text block. Present on the operator's explicit instruction, mitigated rather than excused: abstract, no subject, strictly cool temperature, held at opacity: 30. That number is load-bearing — at 14 the aurora was invisible, and turning it up makes the cards fight the ribbon.
2. Service icons stay full-colour vendor logos. Desaturating them from CSS only makes them illegible.

Overcorrection, and the colour pass

First stat-well pass went from font-thin 13px straight to bold 22px in heading white — operator: "went from subtle to BASH YOU OVER THE HEAD." The principle missed: a stat only has to out-rank its own label, not the service name above it. Now --text-md medium in cyan.

Colour was then lifted from inside the system: Skyfall names Aurora (blue, cyan, green) the primary families, "used generously, in that order", while Dawn (amber/red/violet) is semantic-only. So group markers cycle blue→cyan→green down the page (icons full strength, names at 0.72), service icons take a single cool wash, latency tags move to the info family so "how fast" stops looking like "is it alive". No Dawn colour is used decoratively anywhere.

Two DOM findings that made it possible:

• Homepage renders mdi icons as a gradient behind an SVG mask — recolour via background, not color.
• Homepage emits docker-status-<state>, not status-<state>. The original selectors matched nothing, so every green pill up to that point was stock colouring rather than the theme. Both forms are now matched.