diff --git a/docs/decisions/0007-yekan-bakh-from-public-or-cdn.md b/docs/decisions/0007-yekan-bakh-from-public-or-cdn.md index ce5e314..1976868 100644 --- a/docs/decisions/0007-yekan-bakh-from-public-or-cdn.md +++ b/docs/decisions/0007-yekan-bakh-from-public-or-cdn.md @@ -1,11 +1,13 @@ # 0007 Yekan Bakh served from the app's public folder or a CDN -Status: Accepted · Area: design · Date: 2026-10-04 · Decided by: user · Supersedes: 0004 +Status: Superseded by 0009 · Area: design · Date: 2026-10-04 · Decided by: user · Supersedes: 0004 ## Context + Lumina uses two variable faces from `packages/island/src/fonts/`: Yekan Bakh FaNum (`yekan-bakh-fa-num-vf.woff2`), which draws Latin digits as Persian, and Yekan Bakh (`yekan-bakh-vf.woff2`), which keeps Latin digits. 0004 loaded them with `next/font/local`, which serves them only from `/_next/static/media`. The user wants fonts served as plain files from each app's `public/` or from a CDN, put there by a plugin (0008). ## Decision + - `font-sans` is Yekan Bakh FaNum, for every UI text. Formatters output Latin digits, which the font draws as Persian, and insert `٬` and `٫` themselves, because the font doesn't map `,` and `.`. - `font-latin` is Yekan Bakh, only for text that must show Latin digits: شبا and other codes banks print in Latin digits. - Serve both as content-hashed files from the app's `public/fonts/`, or from a CDN under the same paths. Never use `next/font`, and never use a public third-party font CDN. @@ -14,9 +16,11 @@ Lumina uses two variable faces from `packages/island/src/fonts/`: Yekan Bakh FaN - A CDN on another origin must send `Access-Control-Allow-Origin`, because browsers fetch `@font-face` URLs in CORS mode. ## Alternatives + - `next/font/local` with `assetPrefix` for the CDN (0004): it gives hashing, preload, and fallback metrics for free, but fonts can't live in `public/`. ## Consequences + - We now own what `next/font` did: hashed names and immutable `Cache-Control` (the asset plugin), the preload (`FontFaces`), and the fallback metrics (`FONT_FALLBACK` in island `constants.ts`, measured on Persian text). - The font is licensed. "Never a public CDN" means only the company's own CDN. Confirm the licence covers web embedding from that CDN. - Debt: both apps still load the faces with `next/font/local` in `src/styles/fonts.ts`, and `island.css` says so. `FontFaces` and `FONT_FALLBACK` don't exist yet; island env and the asset plugin do, and already write and pass the hashed font URLs. diff --git a/docs/decisions/0008-island-asset-plugin.md b/docs/decisions/0008-island-asset-plugin.md index 5f48c92..98b7414 100644 --- a/docs/decisions/0008-island-asset-plugin.md +++ b/docs/decisions/0008-island-asset-plugin.md @@ -1,11 +1,13 @@ # 0008 Island asset plugin in each app's next.config -Status: Accepted · Area: architecture · Date: 2026-10-04 · Decided by: user +Status: Superseded by 0010 · Area: architecture · Date: 2026-10-04 · Decided by: user ## Context + Fonts (0007) and the icon sprite live in island, but browsers load them from each app's `public/` or a CDN. Something must put them there in dev and in build. ## Decision + - Island ships one build-time plugin, `withIslandAssets` in `tools/asset-plugin` (it replaces the planned `icon-sprite-plugin`). Each app wraps its `next.config.ts` export with it. - On `next dev` and `next build` (gated on `PHASE_DEVELOPMENT_SERVER` and `PHASE_PRODUCTION_BUILD`), it writes into the app's `public/`: - the fonts, under content-hashed names; @@ -17,10 +19,12 @@ Fonts (0007) and the icon sprite live in island, but browsers load them from eac - The sprite always loads from a root-relative, same-origin URL (`/icons/symbol-defs..svg#icon-x`). `` is same-origin only in every engine, and CORS can't change that. To serve it through a CDN, put the CDN in front of the app's own domain, or add a `beforeFiles` rewrite. Never use an absolute CDN URL or `assetPrefix`. ## Alternatives + - An Nx target or `predev`/`prebuild` script: runs exactly once per command, but the user chose the next.config plugin. - Inlining the sprite in the root layout: no request, but it adds weight to every HTML response. ## Consequences + - Every app gets fonts and icons by registering one plugin; island stays the single source. - In dev, edits to island assets need a dev-server restart (Next watches only next.config), unless the plugin adds a watcher. - Other phases, `next start` included, get the config back unchanged: the build already inlined `env` and wrote the headers into its routes manifest, so production needs neither island's sources nor svgo. `next typegen` and other build-phase commands still run it. diff --git a/docs/decisions/0009-versioned-yekan-bakh-never-hashed.md b/docs/decisions/0009-versioned-yekan-bakh-never-hashed.md new file mode 100644 index 0000000..1943307 --- /dev/null +++ b/docs/decisions/0009-versioned-yekan-bakh-never-hashed.md @@ -0,0 +1,27 @@ +# 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 `.v.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. diff --git a/docs/decisions/0010-island-sprite-and-font-plugins.md b/docs/decisions/0010-island-sprite-and-font-plugins.md new file mode 100644 index 0000000..5e12a52 --- /dev/null +++ b/docs/decisions/0010-island-sprite-and-font-plugins.md @@ -0,0 +1,29 @@ +# 0010 Island icon-sprite and font-copy plugins, versioned and unhashed + +Status: Superseded by 0012 · Area: architecture · Date: 2026-10-05 · Decided by: user · Supersedes: 0008 + +## Context + +0008's single asset plugin wrote the fonts and the svgo sprite into `public/` under content-hashed names, and passed those names to island through env. An svgo or Next.js upgrade changes the bytes, so the hash renames the sprite even when no icon changed, and every visitor downloads it again. The user wants unchanged files to stay cached across deploys. + +## Decision + +- island ships two build-time plugins, and each app wraps its `next.config.ts` export with both: `withIconSprite(withFontCopy(config))`. + - `tools/icon-sprite-plugin` builds the sprite from `icons/*.svg` with svgo and writes it to `ICON_SPRITE_URL` (`/icons/symbol-defs.v.svg`). + - `tools/font-copy-plugin` copies `fonts/` byte for byte into `public/fonts/`. +- Neither plugin adds a hash. The versions live in island `constants.ts`: `ICON_SPRITE_VERSION`, `ICON_SPRITE_URL`, and `CRITICAL_FONT_URL`. The `Icon` atom and the root layouts read them directly, so island needs no env. +- Raise `ICON_SPRITE_VERSION` with every change to an icon or to the svgo step, in the same commit. +- The plugins write in `headers()`, which only `next dev` and `next build` call. They skip unchanged files, write atomically (temp file, then rename), and warn in dev when a file changed under the same version. +- Each app's `next.config.ts` sends `Cache-Control: public, max-age=31536000, immutable` for `/fonts/:path*` and `/icons/:path*`. Configure the same header on the CDN. +- The sprite always loads from a root-relative, same-origin URL, because `` never loads across origins. +- The generated files are gitignored. + +## Alternatives + +- Content hashes (0008): automatic, but a pipeline change renames the files and empties every visitor's cache. + +## Consequences + +- island's `env/` module, the app's `island-env.ts`, and the `NEXT_PUBLIC_ISLAND_*` variables are gone. +- svgo loads only while the sprite is built, so `next start` doesn't need it. +- Shipping a changed icon or svgo config without a version bump leaves visitors on the old sprite for a year. Review blocks it, and the dev-time warning helps catch it. diff --git a/docs/decisions/0011-yekan-bakh-under-fixed-names.md b/docs/decisions/0011-yekan-bakh-under-fixed-names.md new file mode 100644 index 0000000..65318ff --- /dev/null +++ b/docs/decisions/0011-yekan-bakh-under-fixed-names.md @@ -0,0 +1,25 @@ +# 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 (`.v.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. diff --git a/docs/decisions/0012-sprite-version-in-link.md b/docs/decisions/0012-sprite-version-in-link.md new file mode 100644 index 0000000..bcd6a73 --- /dev/null +++ b/docs/decisions/0012-sprite-version-in-link.md @@ -0,0 +1,26 @@ +# 0012 Icon sprite under a fixed name, versioned in its link + +Status: Accepted · Area: architecture · Date: 2026-10-05 · Decided by: user · Supersedes: 0010 + +## Context + +0010 wrote the sprite as `symbol-defs.v.svg`. The front-end-architect skill keeps `symbol-defs.svg` as a fixed name and puts the version in its link, and the user chose the skill's rule for this project. + +## Decision + +- island ships two build-time plugins, and each app wraps its `next.config.ts` export with both: `withIconSprite(withFontCopy(config))`. island's root `index.ts` leaves them out. + - `tools/icon-sprite-plugin` builds the sprite from `icons/*.svg` with svgo and writes it to `ICON_SPRITE_PATH` (`/icons/symbol-defs.svg`). + - `tools/font-copy-plugin` copies `fonts/` byte for byte into `public/fonts/`. +- Neither plugin adds a hash or a version to a file name. island `constants.ts` holds `ICON_SPRITE_VERSION`, and `ICON_SPRITE_URL` (`/icons/symbol-defs.svg?v=`) built from it. The `Icon` atom links `${ICON_SPRITE_URL}#`. +- Raise `ICON_SPRITE_VERSION` with every change to an icon or to the svgo step, in the same commit. Never reuse or lower it. +- The plugins write in `headers()`, skip unchanged files, write atomically, and warn in dev when a file changed without a new version or name. The sprite's first line stamps its version for that check. +- Each app sends `Cache-Control: public, max-age=31536000, immutable` for `/fonts/:path*` and `/icons/:path*`. The CDN keeps the same header and keeps the query string in its cache key. The sprite stays same-origin and root-relative. The generated files are gitignored. + +## Alternatives + +- Version in the file name (0010): a deploy that mixes old and new instances returns 404 for the new sprite, instead of old icons under the new `?v=`. + +## Consequences + +- During a rolling deploy, an old instance can answer `?v=` with the old sprite, and a CDN would cache it for a year. Finish the rollout, or purge that URL, before the CDN caches it. +- A CDN that drops the query string from its cache key serves the old sprite after every bump. diff --git a/docs/decisions/README.md b/docs/decisions/README.md index 58bc408..9ff2bf0 100644 --- a/docs/decisions/README.md +++ b/docs/decisions/README.md @@ -1,14 +1,17 @@ # Decisions ## Design (DDR) + - 0002 Render every tag through island `Element`, flex layouts through `FlexBox`, grid layouts through `GridBox`; never native JSX tags or `flex`/`grid` classes, island included. -- 0007 Serve Yekan Bakh FaNum (`font-sans`, all UI text) and Yekan Bakh (`font-latin`, شبا and bank codes only) as hashed `@font-face` files from the app's `public/fonts/` or our CDN, never `next/font`. +- 0011 Serve Yekan Bakh FaNum (`font-sans`, all UI text) and Yekan Bakh (`font-latin`, شبا and bank codes only) from `public/fonts/` under fixed names declared in island `fonts.css`; no version, never hashed, never `next/font`; a changed font gets a new name. ## Architecture (ADR) + - 0001 Share one platform, `platforms/market`, between `apps/bull` and `apps/bear`; tag all three `scope:market`. -- 0008 Register island's asset plugin in each app's `next.config`; on dev and build it writes hashed fonts and the svgo sprite into `public/`; the sprite stays same-origin. +- 0012 Wrap each app's `next.config` in island's `withIconSprite` and `withFontCopy`; they write `symbol-defs.svg` and the fonts into `public/` unhashed, served immutable; link the sprite as `?v=`. ## Proposed + - 0003 design: Only semantic tokens, named as in the Lumina Design System, produce Tailwind utilities (`@theme inline`); primitives stay plain `:root` variables and Tailwind's defaults are removed. - 0005 design: Island holds Lumina's product components and status-to-tone map; they take every text as props (`children` or `labels`) and never import i18next or platform code. - 0006 architecture: Make every non-app project a pnpm workspace package `@lumina/` with subpath `exports`; third-party dependencies stay in the root package.json.