feat(theme): draw the app in the shard's chosen type families (M12 phase 3) #36

wtclaude · 2026-08-08T10:47:24Z

wtclaude commented

2026-08-08 10:47:24 +00:00

Phase 3 of M12 (docs/android/THEMING_AND_NAV.md §5.3) — the fonts third of the admin's Appearance page, after phase 1's colors and phase 2's structure. Targets edge; the milestone reaches main as one edge → main merge.

ShardTypeface.resolve(theme) maps the three font stacks onto three FontFamily values and shardTypography(faces) draws the M5 type scale in them. Only the family moves — every size, weight, line height and tracking below it is the M5 value, so an unthemed instance reproduces the pre-M12 scale exactly. Resolution is pure, so every assertion is a plain JVM test with no Compose rule.

Seven families are bundled beside the existing Cinzel (EB Garamond, Merriweather, Playfair Display, IM Fell English, Inter, Work Sans, Source Sans 3), taken verbatim from google/fonts the way M5 took Cinzel, each with its SIL OFL licence under app/licenses/. Italics for the four families client/index.html requests one for; the rest are skewed, as every family in the app was before this PR.

The APK nearly tripled, and that is a decision rather than a discovery

Measured unsigned release, R8 full-mode + resource shrink, edge @ 7acbe54 against this branch:

	added (compressed)	release APK
before	—	5,031,411 B — 4.80 MiB
after	8,543,292 B — 8.15 MiB	13,574,703 B — 12.94 MiB

The drafted §5.3 estimate was 1.5–2.5 MB, so this needs saying plainly: Merriweather is 6.08 MiB of the 8.15, because upstream ships it as a three-axis [opsz,wdth,wght] variable font at 4.6 MB per style that deflates only 31% where the others manage 50–60%. The org lead chose to bundle it verbatim with the cheaper options costed — Google's own static 400/700 builds would have held the whole app near 6.8 MiB, and dropping it near 6.2 MiB at the price of a serif option that silently does nothing on Android. R8 does not shrink res/font/; the APK's deflate is the only saving available.

Three things the spec did not survive contact with

1. The per-role font list is not the set of values a role can hold. The server validates an admin-entered font against FONT_OPTIONS[role], but a preset's tokens are copied verbatim by resolveThemeTokens and never pass through that dropdown — modern publishes --display: 'Work Sans', Arial, sans-serif, which the display role does not offer, and fantasy publishes --sans: 'EB Garamond', Georgia, serif, which the sans role does not either. So the lookup is one global map keyed by the lowercased first family name, and both preset cases are asserted by name so a future per-role "tidy-up" fails loudly. Same trap phase 2 hit with --shadow-card, in a different token group.

2. Every bundled family must supply all four weights, for the same reason: a family is not confined to the role its dropdown lives in, so Work Sans has to answer a display request at 600 and a label request at 500/700. The variable faces pin the four through FontVariation. Two exceptions, both upstream facts rather than choices — IM Fell English has one weight per style (its 400 face answers all four and Android synthesises the bold, which is why the website labels it "no bold weight"), and Cinzel keeps M5's 500/600/700 since the server offers it in the display role alone, so nothing can ask it for 400 and adding an instance would have edited M5's type for no reachable case.

3. Typography implements equals — like phase 2's Shapes, unlike phase 1's ColorScheme, checked the same way in the material3 1.3.0 bytecode. So AC-1's type half is one comparison against a verbatim copy of the pre-M12 scale held in the test, which also means a stray edit to a size or a letter-spacing in Type.kt fails there rather than quietly redefining what "shipped" means.

Why there is no `LocalShardTypeface`

The palette and the structure each needed a composition local for the part MaterialTheme cannot carry — five colors without a Material role, and a Card elevation that is a default argument. The families need none: every text style in the app comes from MaterialTheme.typography, and the two composables that override anything (NotificationsScreen's hint, BlockRenderer's italic title) override the style, not the family. FontFamily.Monospace on the recovery-codes screen stays fixed, as a semantic choice rather than a themed one.

That is also why this phase has no call-site sweep, unlike phase 1's color imports and phase 2's 24 Card( sites: Cinzel/AppSerif/AppSans were referenced from Type.kt and nowhere else, so val Typography becoming shardTypography(faces) is the entire migration.

.gitattributes gains *.ttf binary. text=auto already detects them, but a font is too easy to corrupt silently to leave to a heuristic now that eleven of them are in the tree.

Tests

ShardTypefaceTest — 15 cases: the shipped families and the pre-M12 scale, the runic-gateway no-op, both preset bypasses by name, all thirteen shortlist options, first-name parsing against quoting/casing/whitespace, per-field fallback, a colors-only theme, blank and comma-only stacks, and a themed scale proved to differ from the shipped one only in its families.

401 unit tests green (386 + 15), lintDebug and assembleDebug clean. Not exercised on device — that is AC-5, in phase 8, where IM Fell English's synthesised bold is the thing to look at.

Docs: RunicGateway/docs#115.

AI-assisted: written with Claude Code (Claude Opus 5)

Phase 3 of M12 (`docs/android/THEMING_AND_NAV.md` §5.3) — the **fonts** third of the admin's Appearance page, after phase 1's colors and phase 2's structure. Targets `edge`; the milestone reaches `main` as one `edge` → `main` merge. `ShardTypeface.resolve(theme)` maps the three font stacks onto three `FontFamily` values and `shardTypography(faces)` draws the M5 type scale in them. **Only the family moves** — every size, weight, line height and tracking below it is the M5 value, so an unthemed instance reproduces the pre-M12 scale exactly. Resolution is pure, so every assertion is a plain JVM test with no Compose rule. Seven families are bundled beside the existing Cinzel (EB Garamond, Merriweather, Playfair Display, IM Fell English, Inter, Work Sans, Source Sans 3), taken verbatim from `google/fonts` the way M5 took Cinzel, each with its SIL OFL licence under `app/licenses/`. Italics for the four families `client/index.html` requests one for; the rest are skewed, as every family in the app was before this PR. ### The APK nearly tripled, and that is a decision rather than a discovery Measured unsigned release, R8 full-mode + resource shrink, `edge` @ `7acbe54` against this branch: | | added (compressed) | release APK | |---|---|---| | before | — | 5,031,411 B — 4.80 MiB | | after | 8,543,292 B — 8.15 MiB | 13,574,703 B — **12.94 MiB** | The drafted §5.3 estimate was 1.5–2.5 MB, so this needs saying plainly: **Merriweather is 6.08 MiB of the 8.15**, because upstream ships it as a three-axis `[opsz,wdth,wght]` variable font at 4.6 MB per style that deflates only 31% where the others manage 50–60%. The org lead chose to bundle it verbatim with the cheaper options costed — Google's own static 400/700 builds would have held the whole app near 6.8 MiB, and dropping it near 6.2 MiB at the price of a serif option that silently does nothing on Android. R8 does not shrink `res/font/`; the APK's deflate is the only saving available. ### Three things the spec did not survive contact with **1. The per-role font list is not the set of values a role can hold.** The server validates an *admin-entered* font against `FONT_OPTIONS[role]`, but a preset's tokens are copied verbatim by `resolveThemeTokens` and never pass through that dropdown — `modern` publishes `--display: 'Work Sans', Arial, sans-serif`, which the display role does not offer, and `fantasy` publishes `--sans: 'EB Garamond', Georgia, serif`, which the sans role does not either. So the lookup is **one global map** keyed by the lowercased first family name, and both preset cases are asserted by name so a future per-role "tidy-up" fails loudly. Same trap phase 2 hit with `--shadow-card`, in a different token group. **2. Every bundled family must supply all four weights**, for the same reason: a family is not confined to the role its dropdown lives in, so Work Sans has to answer a display request at 600 *and* a label request at 500/700. The variable faces pin the four through `FontVariation`. Two exceptions, both upstream facts rather than choices — **IM Fell English has one weight per style** (its 400 face answers all four and Android synthesises the bold, which is why the website labels it "no bold weight"), and **Cinzel keeps M5's 500/600/700** since the server offers it in the display role alone, so nothing can ask it for 400 and adding an instance would have edited M5's type for no reachable case. **3. `Typography` implements `equals`** — like phase 2's `Shapes`, unlike phase 1's `ColorScheme`, checked the same way in the material3 1.3.0 bytecode. So AC-1's type half is one comparison against a verbatim copy of the pre-M12 scale held in the test, which also means a stray edit to a size or a letter-spacing in `Type.kt` fails there rather than quietly redefining what "shipped" means. ### Why there is no `LocalShardTypeface` The palette and the structure each needed a composition local for the part `MaterialTheme` cannot carry — five colors without a Material role, and a `Card` elevation that is a default argument. The families need none: every text style in the app comes from `MaterialTheme.typography`, and the two composables that override anything (`NotificationsScreen`'s hint, `BlockRenderer`'s italic title) override the *style*, not the family. `FontFamily.Monospace` on the recovery-codes screen stays fixed, as a semantic choice rather than a themed one. That is also why this phase has no call-site sweep, unlike phase 1's color imports and phase 2's 24 `Card(` sites: `Cinzel`/`AppSerif`/`AppSans` were referenced from `Type.kt` and nowhere else, so `val Typography` becoming `shardTypography(faces)` is the entire migration. `.gitattributes` gains `*.ttf binary`. `text=auto` already detects them, but a font is too easy to corrupt silently to leave to a heuristic now that eleven of them are in the tree. ### Tests `ShardTypefaceTest` — 15 cases: the shipped families and the pre-M12 scale, the `runic-gateway` no-op, both preset bypasses by name, all thirteen shortlist options, first-name parsing against quoting/casing/whitespace, per-field fallback, a colors-only theme, blank and comma-only stacks, and a themed scale proved to differ from the shipped one *only* in its families. **401 unit tests green** (386 + 15), `lintDebug` and `assembleDebug` clean. Not exercised on device — that is AC-5, in phase 8, where IM Fell English's synthesised bold is the thing to look at. Docs: RunicGateway/docs#115. --- - [x] AI-assisted: written with Claude Code (Claude Opus 5)

wtclaude added 1 commit 2026-08-08 10:47:26 +00:00

feat(theme): draw the app in the shard's chosen type families (M12 phase 3) a19fdd3582

Phase 3 of M12 (docs/android/THEMING_AND_NAV.md §5.3) — the fonts third of the
admin's Appearance page, after phase 1's colors and phase 2's structure.

ShardTypeface.resolve(theme) maps the three font stacks onto three FontFamily
values and shardTypography(faces) draws the M5 type scale in them. Only the
family moves: every size, weight, line height and tracking is the M5 value, so
an unthemed instance reproduces the pre-M12 scale exactly. Resolution is pure,
so every assertion is a plain JVM test with no Compose rule.

Seven families are bundled beside the existing Cinzel (EB Garamond,
Merriweather, Playfair Display, IM Fell English, Inter, Work Sans,
Source Sans 3), taken verbatim from google/fonts the way M5 took Cinzel, each
with its SIL OFL licence under app/licenses/. Italics for the four families
client/index.html requests one for; the rest are skewed, as they were before.

Three things worth knowing:

1. The per-role font list is not the set of values a role can hold. The server
   validates admin-entered fonts against FONT_OPTIONS[role], but a preset's
   tokens are copied verbatim by resolveThemeTokens and never pass through it —
   `modern` publishes --display: 'Work Sans' and `fantasy` publishes
   --sans: 'EB Garamond', neither of which its own dropdown offers. The lookup
   is therefore one global map keyed by the lowercased first family name, and
   both preset cases are asserted by name so a per-role "tidy-up" fails loudly.
   Same trap phase 2 hit with --shadow-card, in a different token group.

2. The APK nearly tripled, and that was a decision, not a discovery. Measured
   unsigned release, R8 + resource shrink: 5,031,411 B (4.80 MiB) before,
   13,574,703 B (12.94 MiB) after — +8.15 MiB against a drafted estimate of
   1.5-2.5 MB. Merriweather alone is 6.08 MiB of that, because upstream ships
   it as a three-axis [opsz,wdth,wght] variable font that deflates only 31%.
   The org lead chose to bundle it verbatim with the cheaper options costed:
   Google's own static 400/700 builds would have held the app near 6.8 MiB,
   and dropping it near 6.2 MiB at the price of a serif option that silently
   does nothing on Android.

3. Typography implements equals — like phase 2's Shapes, unlike phase 1's
   ColorScheme, checked the same way in the material3 1.3.0 bytecode. AC-1's
   type half is one comparison against a verbatim copy of the pre-M12 scale
   held in the test.

No LocalShardTypeface: unlike the palette and the structure, MaterialTheme
carries the families completely, and the two composables that override
anything override the style rather than the family. Type.kt's `val Typography`
becoming a function is the whole migration — the three families were
referenced from that one file and nowhere else.

Tests: ShardTypefaceTest (15). 401 unit tests green (386 + 15), lintDebug and
assembleDebug clean. Not exercised on device — that is AC-5, in phase 8, where
IM Fell English's synthesised bold is the thing to look at.

Docs: RunicGateway/docs#TBD

Co-Authored-By: Claude <noreply@anthropic.com>

whitlocktech merged commit 0051e97bc7 into edge

2026-08-08 10:51:42 +00:00

whitlocktech referenced this issue from a commit

2026-08-08 10:51:43 +00:00

Merge pull request 'feat(theme): draw the app in the shard's chosen type families (M12 phase 3)' (#36) from feat/m12-phase-3-fonts into edge

whitlocktech deleted branch feat/m12-phase-3-fonts

2026-08-08 10:51:43 +00:00

wtclaude referenced this pull request

2026-08-08 16:12:19 +00:00

feat(theme): make the app a full consumer of the shard's admin theming and nav (M12 cutover) #41

Sign in to join this conversation.