wealth/docs/decisions/0011-yekan-bakh-under-fixed...

1.7 KiB

0011 Yekan Bakh under fixed names, never hashed or versioned

Status: Accepted · Area: design · Date: 2026-10-05 · Decided by: user · Supersedes: 0009

Context

0009 put a version in each font's file name (<name>.v<N>.woff2). The front-end-architect skill gives fonts fixed names with no version, and the user chose the skill's rule for this project.

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.
  • Keep each font under its own fixed name in island fonts/ (yekan-bakh-fa-num-vf.woff2, yekan-bakh-vf.woff2). 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.
  • Fonts have no version. Never change a font under its name: a changed font ships as a new file with a new name, in fonts/, styles/fonts.css, and CRITICAL_FONT_URL, in the same commit.
  • Declare the faces in island styles/fonts.css, with root paths (url('/fonts/…')), font-display: swap, the variable ranges, and a fallback face with Yekan Bakh's vertical metrics.
  • Preload only CRITICAL_FONT_URL (FaNum), from each root layout.
  • A CDN serves the fonts only in front of the app's own domain, under the same paths.

Alternatives

  • Versioned names (0009): the same caching, but a version number the skill doesn't use.

Consequences

  • A developer, not the build, decides when visitors download a font again. Review blocks a font changed under its old name.
  • Debt: the fallback face has no size-adjust yet. Measure it with Persian text set in Tahoma against Yekan Bakh.