Static Astro site that generates metric-adjusted fallback font stacks for web fonts, per target OS/browser audience, with live preview and live layout-shift (CLS) estimation.
Inspired by:
- screenspan.net/fallback — upload a font, tune descriptors, overlay preview.
- abacktools font fallback stack generator — curated stack presets per category.
- cssfontstack.com — font availability per OS.
The default entry point is choosing fonts (upload / catalog). Arriving from the bookmarklet is a secondary path and is not emphasized on the first screen.
Delivered incrementally:
- File upload (woff2/woff/ttf/otf) — fully local, no network. First to ship.
- Google Fonts picker — catalog JSON generated by
pnpm google-fonts:catalogand committed (lazy-loaded chunk); font files fetched fromfonts.gstatic.com(CORS-enabled). The site import (#34) is documented indocs/security.mdandextension/README.md. The Fontsource picker (#44) adds the non-Google open fonts (pnpm fontsource:catalog), files fromcdn.jsdelivr.net. - Site import — hosting is static (no proxy), so:
- Bookmarklet run on the user's site: collects
@font-facerules,document.fonts, computedfont-familyof key elements (body,h1–h3, buttons), element boxes, fetches same-origin font files, then opens the generator in a new tab and hands the payload over (window.open+postMessagehandshake; clipboard JSON as a fallback). The user lands directly in the tuning UI with their site's fonts preloaded; the preview and CLS simulation keep the sample article until #173 brings the site structure. - Direct URL fetch attempted from the browser; works only when the site sends CORS headers (font files usually do, HTML/CSS usually don't). Failure falls back to the bookmarklet or the extension with a clear explanation. Implemented in
site-import/lib/direct-fetch.ts; limits and theconnect-srcexception are indocs/security.md. - Paste CSS (
@font-faceblocks / Google Fonts<link>URL).
- Bookmarklet run on the user's site: collects
- Browserslist tag editor in the browser: quick-add tags (
baseline widely available,baseline newly available,baseline 20XX,defaults,> 0.5%, last 2 versions, mobile-only, desktop-only, browsers, operating systems) with a hovernotaction, typed or pasted queries,.browserslistdrop, validation and live resolved list. - Resolved browsers are mapped to OS groups:
ios_saf→ iOS,safari→ macOS,and_chr/samsung/and_ff/and_uc→ Android,chrome/edge/firefox/opera→ Windows/macOS/Linux/ChromeOS (desktop split is configurable). - My stats: load
browserslist-stats.jsonfrom the user's analytics (see 2.3) to usein my statsqueries and traffic-weighted coverage. - Manual mode: user adds/removes OS groups and versions directly, ignoring browserslist.
- The audience drives: which per-OS fallback selectors are shown, descriptor support warnings, and coverage estimates.
- One column/selector per OS group. Each lists fonts preinstalled on that OS (from our dataset), ranked by metric similarity to the web font (x-width avg, cap height, x-height, ascent/descent ratios) with an "auto-pick best" default.
- Multiple fallbacks per OS allowed (ordered).
- Stack resolver: simulates, per OS, which
local()face wins given the finalfont-familyorder (e.g. Arial also exists on macOS, so the macOS pick must come before Arial). Shows conflicts and proposes a reordering. local()name variants (full name + PostScript name) emitted per font, since naming differs across OSes.
Every numeric control = slider + number input + "auto" toggle. Auto values recompute when inputs change; manual edits pin the value until reset.
| Value | Auto-fit method |
|---|---|
size-adjust |
Ratio of weighted average glyph width (language-specific letter frequencies, per script) of web font vs fallback; optional exact fit against the preview text by measuring rendered width. |
ascent-override / descent-override / line-gap-override |
Web font vertical metrics (hhea/OS2 selected by an explicit engine policy) divided by the web font's own unitsPerEm and size-adjust. |
letter-spacing / word-spacing |
Numeric optimizer minimizing line-break mismatches and block height delta on sample text across chosen viewports. Emitted as a "fonts loading" CSS class + Font Loading API snippet (these are not @font-face descriptors). |
font-size-adjust |
Computed from x-height/cap-height ratio; offered as the Safari strategy (see 1.6). |
| Automatic CLS fit | Runs the solver on every chosen fallback whenever inputs change; values pinned by hand stay and the rest are optimized to minimize the estimated CLS. |
Both modes:
- (a) Coverage-limited fallback: extract the web font's cmap, emit a compact
unicode-rangefor each adjusted fallback@font-face, so metric overrides apply only to characters the web font actually covers. - (b) Per-script fallback chains: Latin / Cyrillic / Greek / CJK / Arabic / … each get their own fallback font per OS and their own adjusted
@font-facewith the script's range and per-script fit (Capsize-style per-subset x-width). - Range compaction (merge adjacent code points, named presets matching Google Fonts subsets).
- Layout shift (CLS) simulation, updated live while sliders move (debounced to animation frames):
- Preview document rendered in hidden same-origin iframes at preset viewports (412 / 1350, the Lighthouse mobile and desktop sizes).
- Element boxes collected with fallback vs web font, layout shift score computed per the Layout Instability spec (impact fraction × distance fraction).
- Shows score per viewport with Good / Needs improvement / Poor rating (0.1 / 0.25 thresholds), plus line-count delta, block height delta, width delta %, line-break mismatches.
- The sample article, or the element boxes of an imported page when the bookmarklet or extension collected them (#173); a direct URL import and the per-OS ranking still use the sample article.
- Device picker in the preview toolbar (Responsive, phones, foldables, tablets, laptops and displays; list generated from Chrome DevTools' emulated devices by
pnpm devices:import). A chosen device or a dragged preview width sets the frame width and the score is recomputed at that width; the page width is measured too when the preview is not constrained.
- Descriptor support matrix for the selected audience (MDN BCD data). Notably Safari/iOS do not support
ascent-override/descent-override/line-gap-override(onlysize-adjustfrom 17), so the tool shows the expected residual shift there and offers thefont-size-adjust+ fixedline-heightstrategy. - Coverage estimate: share of the audience whose OS has each fallback preinstalled (usage from browserslist/caniuse data × OS availability dataset).
- Loading strategy guidance:
font-displaychoice and its effect on CLS (optional= no swap shift),<link rel="preload" … crossorigin>, font file size, FOUT/FOIT trade-offs.
- Plain CSS (
@font-face+font-family), CSS custom properties variant. - Tailwind v4
@theme, Next.jsnext/font/local(declarations,adjustFontFallback: false+ manual fallback), Fontaine / Nuxt Fonts config, Astro Fonts config. - Font Loading API snippet for the "fonts loading" class.
- Preload
<link>tags. - Machine-readable JSON (all inputs, computed metrics, outputs).
- Impact report (Markdown): CLS per viewport, support matrix, coverage, warnings.
- Share link: only the difference from the app defaults is serialized into the URL hash, including the open dock panel and the preview modes (uploaded font files are kept in IndexedDB locally; link warns they are not shared; fonts picked from Google Fonts or Fontsource travel as
sourcesand are downloaded again after the recipient confirms).- The link carries a short fingerprint of the preset picks over the bundled OS font dataset (
data). If it differs from the recipient's, only the picks whose fonts still exist in the recipient's dataset are restored (the rest fall back to the preset) and a dismissable notice is shown; the other settings are applied. Settings saved in the browser carry the same fingerprint and raise the same notice. Opening a link does not overwrite the recipient's saved dock layout. The preview heading and body families travel in the view diff (headingFont,bodyFont); page text is never carried. - Auto-fit values are recomputed by the recipient from a browser-dependent calibration, so the numbers can differ slightly between browsers. The opt-in "Pin auto-fit values" checkbox next to Share writes the selected font's current fit numbers (size-adjust, ascent, descent, line gap; percent, two decimals) into the link as manual values; they stay fixed instead of recalculating when the recipient changes the font. Other fonts of a multi-font link are not pinned, and a pinned link over the hash limit is copied unpinned with a notice.
- The link carries a short fingerprint of the preset picks over the bundled OS font dataset (
- Font catalog (cssfontstack analog): table of system fonts × OS/versions with availability and estimated audience coverage; static page per font with metrics and specimen.
- Presets (abacktools analog): curated stacks per category (sans, serif, mono, display, handwriting, system-ui, modern-font-stacks families), each openable in the generator.
- Model (#510): a preset is not a CSS stack that is copied into the output. It sets the font type and preselects, per system, the stack fonts that the OS fonts dataset lists as preinstalled and that have metrics; the fitted
@font-facefallbacks (size-adjust, overrides) are then computed for those picks like for any other pick, and flow into every export format, the preview and the share link. Stack fonts without dataset entries or metrics (for example Rockwell, Charter, Menlo) cannot be fitted and are skipped (as is any stack font beyond two per system); the Fine-tuning panel lists them, or says that the preset only sets the font type when none of the selected systems has a usable pick.
- Model (#510): a preset is not a CSS stack that is copied into the output. It sets the font type and preselects, per system, the stack fonts that the OS fonts dataset lists as preinstalled and that have metrics; the fitted
- Guide: how descriptors,
unicode-rangeand CLS interact. - Footer links: Credits page, source repository (fogrew/fontstay.dev).
- More OFL font sources besides Google Fonts (Fontsource, Bunny Fonts, independent foundries).
- @capsizecss/metrics (MIT): used as a cross-check for Google Fonts and a few system fonts only. It has just
latin/thaisubsets and ~20 system fonts (spike). - Own metrics format: per face, advances of every code point in supported scripts (Latin, Cyrillic, Greek first) plus vertical metrics, produced by
scripts/extract-metrics.tsfrom installed font files. Only metrics are committed, never font files. - Optional in-browser enhancement: Local Font Access API (Chromium) to read the user's actual installed fallback fonts.
fonts/<font-id>.json: names (family, full, PostScript per OS), category, scripts covered, and availability[os][version] = preinstalled | on-demand | optional-feature | absent, each entry with a source link.
Seeds:
- Official vendor lists: Microsoft Learn Windows font lists, Apple "Fonts included with macOS / iOS" pages, AOSP
fonts.xml(Apache-2.0), default font packages of Ubuntu/Fedora, ChromeOS. - adrg/os-font-list (MIT, unmaintained since Nov 2021) — one-time import for older Windows/macOS/Linux versions, with attribution; not a dependency.
- modern-font-stacks (CC0, active) — preset stacks and cross-check of availability.
- Validated by a schema (Valibot/Zod) and unit tests (every entry has a source, no unknown OS ids).
- Browser version usage:
caniuse-liteviabrowserslist(CC BY 4.0). - Own traffic stats: the user can load a
browserslist-stats.json(custom usage data schema) produced bybrowserslist-plausible,browserslist-ga,browserslist-ga-exportor by hand. Enables> N% in my statsqueries and weights all coverage estimates by the user's real traffic. Parsed and validated locally, never uploaded. - Desktop OS split for desktop browsers: default from StatCounter (CC BY-SA 3.0, attributed), user-editable.
- Descriptor support:
@mdn/browser-compat-data(CC0), compiled to a small JSON at build time.
- Astro (static output, no adapter, no server), TypeScript strict.
- Hosting: Cloudflare Workers with static assets only (no Worker script), deployed by Workers Builds from GitHub.
- Preact +
@preact/signalsfor the interactive generator island (client:loadfor generator,client:visibleelsewhere). - Font parsing: fontkitten (MIT, ~93 KB gzip, woff2 included) in a Web Worker; we compute metrics ourselves from cmap + glyph advances (spike).
browserslist+baseline-browser-mappingbundled for the browser (lazy-loaded chunk).- i18n: Astro i18n routing (
/en/,/ru/, default locale redirect) + Paraglide JS 2 for the typed message keys and the locale runtime; the texts themselves are the per-locale JSON files (messages/<locale>.json), whichmessagesForfills in{name}placeholders from. A page fetches only the file of its own locale (preloaded from the head, read before the islands hydrate); prerendering reads all of them.
FEOD levels: app, pages, modules, common, global. Imports only through each entity's root index.ts; direction per the import matrix.
Astro routes live in src/app/pages (srcDir: ./src/app), which frees src/pages for the FEOD pages level; route files are thin and render page entities.
src/
app/ # Astro srcDir: routes, layouts, global styles, i18n wiring, head/meta, theme
pages/ # thin Astro routes ([locale]/index.astro, fonts/[slug].astro, …)
layouts/
styles/
pages/ # FEOD pages level: page entities with root index.ts
generator/ # composition of modules for the generator page
catalog/
presets/
guide/
modules/
font-source/ # web font inputs
upload/ google-fonts/ site-import/ # submodules
font-metrics/ # parsing worker, metrics, cmap, script detection
system-fonts/ # dataset access, similarity ranking, local() names
audience/ # browserslist tag editor, OS mapping, support matrix, coverage
fallback-fit/ # fit math, solver, unicode-range builder, stack resolver
layout-shift/ # CLS simulation (iframes, box diff, scoring)
preview/ # overlay/side-by-side preview, toggles
export/ # CSS/Tailwind/Next/Fontaine/Astro/JSON/report generators
presets/ # curated stacks
project-state/ # signals store, URL hash + IndexedDB persistence
common/
ui/ # Button, FitField (slider+number+auto), Select, Tabs, CodeBlock, Disclosure, LiveRegion
i18n/ # Paraglide runtime re-exports, locale helpers
lib/ # math, debounce, typed worker RPC
global/ # env.d.ts, polyfills
data/ # fonts/*.json, metrics/*.json, presets.json (+ schemas)
scripts/ # extract-metrics, google-fonts/import-catalog, build-bcd-subset, i18n-add-locale
tests/e2e/
Pure logic (fallback-fit, font-metrics, audience, layout-shift scoring, export) has no UI dependency and is unit-tested in isolation.
messages/en.jsonis the source of truth;ru.jsonetc. typed against it by Paraglide (missing key = type error).pnpm i18n:add <locale>scaffolds the messages file, registers the locale in Paraglide settings and Astro i18n config.- Unit test checks key parity and ICU plural forms; e2e smoke runs per locale.
- Language switcher keeps the current state (URL hash survives).
- Native inputs (
<input type="range">+ linked<input type="number">), visible labels, units in accessible names. - Full keyboard operation, visible focus, logical order, skip link.
- Live CLS value announced via throttled polite
aria-liveregion (only on settle, not every frame). - Light/dark via
light-dark()andprefers-color-scheme, respectsprefers-reduced-motionandforced-colors. - Preview overlay is not color-only: outline/dash patterns distinguish fallback vs web font.
@axe-core/playwrightchecks on every page in both locales and themes.
-
pnpm, Biome (lint + format), lefthook pre-commit:
biome check --staged --write(fixes re-staged),astro check(typecheck incl..astro),feod-analyzer analyze . --fail-on warning(@feod/analyzer, MIT) + BiomenoRestrictedImportspatterns for deep imports.
-
Vitest (unit +
fast-checkproperty tests for the solver and range compaction). -
Playwright e2e against
astro preview(Chromium; WebKit/Firefox if available in CI image). -
lefthook
commit-msg: commitlint (Conventional Commits). Changelog generated from commits by git-cliff into Keep a Changelog format. -
Cloudflare Workers Builds (no GitHub Actions): the build command runs everything, so every PR gets a check run + preview URL, and a failing check fails the deployment:
pnpm run verify # biome ci → astro check → feod-analyzer → vitest run → astro build → playwright testDeploy:
wrangler deployonmain,wrangler versions upload(preview URL) on other branches.wrangler.jsoncservesdist/as static assets. Node pinned via.node-version, pnpm via thePNPM_VERSIONbuild variable (the build image default may be older thanpackageManager).
Each phase ends deployable with a green PR check.
Phase 0 — Bootstrap & spikes
- Astro + Preact + TS strict, Biome, lefthook, Vitest, Playwright, Paraglide (EN/RU), FEOD skeleton with
index.tsper entity. - Cloudflare Workers Builds connected;
verifypipeline running on PRs. - Spikes (go/no-go):
@feod/analyzer(0.1.x): parses.ts/.tsxonly, not.astro(see issues).- Done: font parsing in a worker (fontkitten, own metrics format) and
@capsizecss/metricscoverage; results indocs/spikes/.
Phase 1 — Core engine (no UI)
- Font parsing worker, metrics model, fit math,
@font-face/CSS generator, stack resolver. - Unit tests against known reference outputs (Capsize/Fontaine results for e.g. Inter→Arial, Roboto→Arial).
Phase 2 — MVP generator
- Upload input, one fallback, FitFields with auto, overlay + side-by-side preview, CSS output, copy button, EN/RU, a11y baseline.
Phase 3 — Audience & per-OS fallbacks
- Browserslist tag editor with Baseline tags,
browserslist-stats.jsonimport, OS mapping, manual mode, per-OS selectors with similarity ranking, stack resolver UI, descriptor support warnings, Safari strategy.
Phase 4 — Layout shift
- CLS simulator, live metric per viewport, letter/word-spacing fit, "Optimize for CLS".
Phase 5 — unicode-range
- cmap extraction, coverage-limited ranges, per-script fallback chains with per-script fit.
- Unicode map and glyph coverage per Unicode block, with counts of covered code points (#100).
Phase 6 — Data & catalog
- OS availability dataset + schema + sources, metrics extraction script, catalog pages, coverage estimates.
Phase 7 — More inputs
- Google Fonts picker, site import (bookmarklet, extension, direct CORS fetch, paste CSS).
- Font collections (
.ttc,.otc): list the members, let the user pick one (#99). - Preview of text the font cannot render: substitute missing glyphs explicitly and offer per-glyph fallback fonts (#84).
Phase 8 — Presets, exports, sharing
- Presets page, all export formats, impact report, share links, persistence.
Phase 9 — Polish
- Full a11y audit, performance (lazy chunks, worker), SEO/meta/OG, guide page, Credits page, README. The guide also covers
@font-facesyntax, descriptor and format support, font licenses and specification links (#102). - Split web font audit of imported and pasted
@font-facerules in the generator, CLI and MCP server (#418). - Spike: Playwright in the Cloudflare build container (gVisor, Ubuntu 22.04, no root for
aptdeps), to decide whether e2e can run in the build (#7). - More UI languages (the set is chosen after researching the target markets) and a language dropdown instead of the link list in the header (#126).
Backlog
- Font inspector in the style of everythingfonts.com: colour and background previews (the image background landed in #483), a size waterfall, a glyph viewer with bounding boxes and line metrics, name-table attributes (#101).
- Offline use and a service-worker update flow: an "Update" toast with a changelog link while the app is open, the new version downloaded in the background, and a toast after an automatic update linking to the combined changelog of all applied versions (#78).
- Right-to-left interface and an Arabic locale (#221): all layout uses logical properties (inline and block), direction-dependent geometry (the slider, the X-ray lens, the width handle, disclosure glyphs) is mirrored, and the Arabic messages need a native review before the locale ships.
| Risk | Mitigation |
|---|---|
| Playwright browsers may not run in Cloudflare's build container (Workers Builds) | Spike in Phase 0; options: headless shell only, Chromium-only e2e, or a separate e2e check (needs a decision). |
| Build time limit / monthly build quota | Cache node_modules and Playwright browsers; keep e2e suite focused. |
@feod/analyzer is early (0.1.x), single maintainer, prebuilt binaries without provenance, no .astro parsing |
Kept with mitigations (#50): exact version pin, sha256 verification of the platform binary against scripts/feod-analyzer.sha256.json, execution with a scrubbed environment (it keeps secrets from the analyzer binary, not from the rest of the build command), own relative-path-literal check for .astro, Biome import restrictions as a second line. Revisit if upstream adds provenance or .astro support. |
| System font metrics vary by OS version | Store metrics per OS version where they differ; show "measured on" source. |
| Safari lacks vertical overrides | Explicit residual-shift estimate + font-size-adjust strategy. |
| No precise "% of users have font X" data exists | Estimate from OS availability × browser/OS usage; label as estimate. |
Every external source (data, libraries with notable data, inspiration sites, specs) is listed in CREDITS.md with its license, and rendered on a Credits page of the site (linked from the footer).
- If Playwright cannot run in the Cloudflare build: allow a single GitHub Actions job for e2e only, or run e2e Chromium-only / locally? (decided by the spike in Phase 9, #7)