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

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-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.