2.0 KiB
2.0 KiB
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-sansis Yekan Bakh FaNum, for every UI text.font-latinis Yekan Bakh, only for شبا and other codes that banks print in Latin digits.- Name each font file
<name>.v<N>.woff2in islandfonts/. Serve it from each app'spublic/fonts/under that exact name, withCache-Control: public, max-age=31536000, immutable. No step hashes or renames it,next/fontincluded. - 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 ofpublic/.
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_ORIGINwas removed. - Debt: the fallback face has no
size-adjustyet. Measure it with Persian text set in Tahoma against Yekan Bakh.