wealth/docs/decisions/0009-versioned-yekan-bakh-n...

28 lines
2.0 KiB
Markdown
Raw Normal View History

# 0009 Yekan Bakh under versioned names, never hashed
Status: Superseded by 0011 · Area: design · Date: 2026-10-05 · Decided by: user · Supersedes: 0007
## Context
0007 served the fonts under content-hashed names, and the apps still loaded them with `next/font`, which hashes them again into `/_next/static/media/`. A hash changes whenever a build step changes its output, such as a Next.js upgrade, even when the font didn't change. Every visitor then downloads the fonts again, though the cached copy was still correct.
## Decision
- `font-sans` is Yekan Bakh FaNum, for every UI text. `font-latin` is Yekan Bakh, only for شبا and other codes that banks print in Latin digits.
- Name each font file `<name>.v<N>.woff2` in island `fonts/`. Serve it from each app's `public/fonts/` under that exact name, with `Cache-Control: public, max-age=31536000, immutable`. No step hashes or renames it, `next/font` included.
- Declare the faces in island `styles/fonts.css`, with root paths (`url('/fonts/…')`), `font-display: swap`, the variable ranges (`font-weight: 100 950`, `font-stretch: 62.5% 150%`), and a fallback face that has Yekan Bakh's vertical metrics.
- Preload only `CRITICAL_FONT_URL` (FaNum), from each root layout.
- A changed font gets the next version, in the same commit. Never overwrite a versioned file or reuse a version.
- A CDN serves the fonts only in front of the app's own domain, under the same paths.
## Alternatives
- Content hashes (0007): stable for unchanged bytes, but a pipeline change can rename them, and the user wants the cache to survive deploys.
- `next/font/local`: hashes the files and moves them out of `public/`.
## Consequences
- A developer, not the build, decides when visitors download a font again. Review must block a changed font that kept its version.
- A cross-origin font CDN isn't supported anymore. `NEXT_PUBLIC_CDN_ORIGIN` was removed.
- Debt: the fallback face has no `size-adjust` yet. Measure it with Persian text set in Tahoma against Yekan Bakh.