Skip to main content

no-local-src-in-font-face

Disallow local() references in @font-face src declarations.

Rule catalog ID: R030

Targeted pattern scopeโ€‹

  • The src descriptor inside every @font-face block.

What this rule reportsโ€‹

  • @font-face src entries that use local() to reference a font installed on the user's operating system.

Why this rule existsโ€‹

local() instructs the browser to use a font already installed on the user's machine instead of downloading the web font file. While this can reduce network requests, it introduces a category of unpredictability that is unacceptable for pixel-perfect, reproducible rendering scenarios:

  1. Version skew. The locally installed font may be an older or newer version than the web font. Different versions often have different glyph metrics, kerning tables, or hinting data, producing subtle โ€” or dramatic โ€” layout differences across user machines.

  2. OS-level substitution. Some operating systems (particularly macOS and iOS) ship their own version of widely-used typefaces (for example Helvetica Neue, Arial, Georgia). local("Helvetica Neue") on macOS will resolve to Apple's version, which is metrically distinct from the version a designer uses on Windows or Linux.

  3. Reproducibility and QA. Font rendering differences caused by local() cannot be reproduced in isolation โ€” they vary per user device โ€” making visual regression testing unreliable.

  4. Security (font fingerprinting). The presence or absence of specific locally-installed fonts can be used by third-party scripts to fingerprint browsers. Removing local() from @font-face blocks reduces that attack surface.

This rule is intentionally recommended: false because local() is a legitimate performance optimisation when version skew is not a concern (for example generic system-font stacks or internal tools). Enable it only when pixel-perfect, reproducible rendering is required.

โŒ Incorrectโ€‹

/* local() lookup is unpredictable across OS/version */
@font-face {
  font-family: "Inter";
  src: local("Inter"), url("./inter.woff2") format("woff2");
}

โœ… Correctโ€‹

/* URL-only source list โ€” predictable across all user environments */
@font-face {
  font-family: "Inter";
  src: url("./inter.woff2") format("woff2"),
       url("./inter.woff") format("woff");
}

Stylelint config exampleโ€‹

{ "font/no-local-src-in-font-face": true }

When not to use itโ€‹

  • System-font stacks where you explicitly want to leverage OS-level fonts.
  • Internal tooling where all users share the same controlled OS image.
  • Projects that intentionally prioritise local cache hits over pixel-perfect consistency.

Further readingโ€‹