From e5362d56fc451daf316a2e4427094af7a01b8a52 Mon Sep 17 00:00:00 2001
From: jamey <jamey@server.jamey.stream>
Date: Fri, 20 Feb 2026 17:14:01 +0000
Subject: [PATCH] add admin font loading plan doc

Documents the missing @font-face and font-family on admin/setup
pages, the cache miss path resolver bug, and options for fixing.

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
---
 PROGRESS.md                      |  4 +-
 docs/plans/admin-font-loading.md | 70 ++++++++++++++++++++++++++++++++
 2 files changed, 73 insertions(+), 1 deletion(-)
 create mode 100644 docs/plans/admin-font-loading.md

diff --git a/PROGRESS.md b/PROGRESS.md
index 343bf37..1e0288e 100644
--- a/PROGRESS.md
+++ b/PROGRESS.md
@@ -27,7 +27,7 @@
 
 Ordered by dependency level — admin shell chain first (unblocks most downstream work).
 
-Plans: [admin-redesign.md](docs/plans/admin-redesign.md) | [setup-wizard.md](docs/plans/setup-wizard.md) | [setup-and-launch.md](docs/plans/setup-and-launch.md) | [search.md](docs/plans/search.md) | [products-refactor.md](/home/jamey/.claude/plans/snug-roaming-zebra.md) | [shipping-sync.md](docs/plans/shipping-sync.md) | [printful-integration.md](docs/plans/printful-integration.md) | [provider-strategy.md](docs/plans/provider-strategy.md) | [css-migration.md](docs/plans/css-migration.md)
+Plans: [admin-redesign.md](docs/plans/admin-redesign.md) | [admin-font-loading.md](docs/plans/admin-font-loading.md) | [setup-wizard.md](docs/plans/setup-wizard.md) | [setup-and-launch.md](docs/plans/setup-and-launch.md) | [search.md](docs/plans/search.md) | [products-refactor.md](/home/jamey/.claude/plans/snug-roaming-zebra.md) | [shipping-sync.md](docs/plans/shipping-sync.md) | [printful-integration.md](docs/plans/printful-integration.md) | [provider-strategy.md](docs/plans/provider-strategy.md) | [css-migration.md](docs/plans/css-migration.md)
 
 | # | Task | Depends on | Est | Status |
 |---|------|------------|-----|--------|
@@ -79,6 +79,8 @@ Plans: [admin-redesign.md](docs/plans/admin-redesign.md) | [setup-wizard.md](doc
 | ~~38~~ | ~~Phase 6: Replace DaisyUI (admin)~~ | 37 | 3h | done |
 | ~~39~~ | ~~Phase 7: Remove Tailwind entirely~~ | 38 | 1.5h | done |
 | 40 | Phase 8: Optimisation + modern enhancements | 39 | 2.5h | |
+| | **Bugs / polish** | | | |
+| 49 | Admin font loading + cache miss path resolver ([plan](docs/plans/admin-font-loading.md)) | — | 1h | |
 
 **Total remaining: ~7 hours across ~3-4 sessions** (Printful tests, CSS optimisation)
 
diff --git a/docs/plans/admin-font-loading.md b/docs/plans/admin-font-loading.md
new file mode 100644
index 0000000..36ed4f6
--- /dev/null
+++ b/docs/plans/admin-font-loading.md
@@ -0,0 +1,70 @@
+# Admin font loading
+
+Status: Open — needs discussion
+
+## Problem
+
+Custom fonts don't load on admin or setup pages. The setup page at `/setup` renders in the browser's default serif font on production.
+
+### Root cause
+
+The admin CSS (`admin.css`) has **no `@font-face` declarations** and **no `font-family` on body/root**. Font family CSS variables are defined in `theme-primitives.css` (e.g. `--p-font-inter: 'Inter', system-ui, sans-serif`) but the actual woff2 font files are only loaded via `@font-face` rules generated at runtime by `CSSGenerator` for shop pages (injected into `<style>` tags via `ThemeHook` / `LoadTheme` plug).
+
+Admin and setup pages use the `root.html.heex` layout which loads `admin.css` only — no generated theme CSS, no `@font-face` declarations.
+
+### Why it works locally
+
+If you have Inter or other theme fonts installed on your system, the browser resolves the font-family names without needing `@font-face`. On production or other machines without the fonts installed, it falls through to browser defaults (usually serif).
+
+### Secondary bug: cache miss path
+
+Three places regenerate CSS on ETS cache miss **without** the `path_resolver` for digested font URLs. This means if the cache is cold (after invalidation, restart race, etc.), the cached CSS contains bare paths like `/fonts/inter-v20-latin-regular.woff2` which 404 in production (only digested paths are served).
+
+Affected files:
+- `lib/berrypod_web/plugs/load_theme.ex:30` — `CSSGenerator.generate(settings)` (no resolver)
+- `lib/berrypod_web/theme_hook.ex:29` — same
+- `lib/berrypod_web/controllers/error_html.ex:117` — same
+
+`CSSCache.warm/0` does it correctly: `CSSGenerator.generate(settings, &BerrypodWeb.Endpoint.static_path/1)`
+
+## Options
+
+### Option A: Quick fix — system font stack for admin
+
+Add `font-family: system-ui, -apple-system, sans-serif` to the admin reset CSS. Admin pages get a clean sans-serif font without loading any custom font files.
+
+Pros: zero extra bytes, fast, no font loading flash
+Cons: admin and shop have completely different typographic feel
+
+### Option B: Load Inter for admin pages
+
+Add static `@font-face` declarations for Inter (the default body font) to admin.css. Admin gets a consistent font with minimal overhead (~50KB for regular + medium weights).
+
+Pros: consistent typography across admin/shop
+Cons: extra font loading, static declarations need updating if font files change
+
+### Option C: Shared font loading infrastructure
+
+Rethink the split between admin and shop CSS. Currently they're two completely separate stacks:
+- **Shop**: runtime-generated CSS with `@font-face` via `CSSGenerator`, theme tokens, semantic layer
+- **Admin**: hand-written CSS with DaisyUI-derived colour themes, no font loading
+
+Could unify font loading so both share the same `@font-face` declarations (either static in a shared CSS file, or via a shared plug/hook). The theme font primitives are already in `theme-primitives.css` which both stacks import.
+
+This is a bigger piece of work and might be overengineering for the current state — the admin and shop serve very different purposes and their CSS stacks reflect that.
+
+### Option D: Full admin CSS rework
+
+Rebuild admin CSS to share more with the shop CSS architecture. Both would use the three-layer system (primitives, attributes, semantic) with the admin getting its own semantic layer but sharing primitives and font loading.
+
+This is the most ambitious option and would need its own plan. Worth considering if the admin UI is going to grow significantly, but could be premature for MVP.
+
+## Recommendation
+
+Fix the cache miss bug regardless (Option A baseline). For fonts specifically, Option A or B are both reasonable quick wins. Option C/D are worth revisiting when the admin UI needs a bigger rework.
+
+## Related
+
+- Cache miss bug affects shop pages too (not just admin)
+- `CSSCache.warm/0` runs on startup so the bug only manifests on race conditions or manual invalidation
+- The `@font-face` declarations in generated CSS use bare paths without `path_resolver`, which 404s in production