Verificação HTML: CSS: "font-display": A propriedade "font-display" não existe.

Sobre este problema de CSS

font-display controla como uma fonte é apresentada com base em quando foi transferida e está pronta para usar. Os seus valores aceites — auto, block, swap, fallback e optional — determinam o comportamento durante a linha temporal de carregamento da fonte (período de bloqueio, período de troca e período de falha). Como governa o comportamento de carregamento de uma definição de fonte, só faz sentido dentro de uma regra @font-face, não como uma propriedade aplicada a um elemento HTML.

Quando coloca font-display dentro de um seletor regular como body ou .heading, o validador CSS sinaliza-o corretamente como uma propriedade desconhecida. Os navegadores vão ignorá-lo silenciosamente, o que significa que a sua estratégia pretendida de carregamento de fonte não terá efeito. Os utilizadores podem experienciar um flash de texto invisível (FOIT) ou outro comportamento indesejado porque o navegador volta à sua estratégia padrão de font-display.

Porque isto é importante

Desempenho de carregamento de fonte: Sem um descritor font-display válido na sua regra @font-face, perde o controlo sobre como o navegador trata a renderização de texto enquanto as fontes personalizadas carregam. Usar font-display: swap, por exemplo, garante que o texto permanece visível com uma fonte de fallback até que a fonte personalizada esteja pronta — uma boa prática fundamental de desempenho web.
Conformidade com padrões: A especificação do CSS Fonts Module Level 4 define font-display exclusivamente como um descritor @font-face. Usá-lo noutros locais produz CSS inválido.
Falha silenciosa: Os navegadores não vão lançar erros visíveis — simplesmente ignoram a propriedade inválida, o que pode tornar difícil diagnosticar porque é que o seu comportamento de carregamento de fonte não está a funcionar como esperado.

Como corrigir

Remova font-display de qualquer regra CSS regular (seletores como body, h1, .class, etc.).
Adicione font-display dentro da at-rule @font-face onde define a sua fonte personalizada.
Se estiver a carregar fontes via um serviço de terceiros (como o Google Fonts), pode frequentemente anexar um parâmetro &display=swap ao URL da fonte em vez de escrever o seu próprio bloco @font-face.

Exemplos

❌ Incorreto: `font-display` usado como propriedade CSS

body {
  font-family: "Open Sans", sans-serif;
  font-display: swap;
}

Isto desencadeia o erro do validador porque font-display não é uma propriedade CSS válida para seletores de elementos.

✅ Correto: `font-display` usado dentro de `@font-face`

@font-face {
  font-family: "Open Sans";
  src: url("/fonts/open-sans.woff2") format("woff2"),
       url("/fonts/open-sans.woff") format("woff");
  font-display: swap;
}

body {
  font-family: "Open Sans", sans-serif;
}

Aqui, font-display: swap está corretamente colocado dentro da regra @font-face, dizendo ao navegador para renderizar imediatamente o texto com uma fonte de fallback e depois trocar para “Open Sans” assim que termine de carregar.

✅ Correto: Usar `display=swap` com Google Fonts

Se usa o Google Fonts, não precisa de escrever o seu próprio bloco @font-face. Em vez disso, adicione o parâmetro display ao URL:

<link rel="stylesheet" href="https://fonts.googleapis.com/css2?family=Open+Sans&display=swap">

O Google Fonts vai gerar as regras @font-face com font-display: swap incluído automaticamente.

❌ Incorreto: `font-display` num seletor de classe

.heading {
  font-family: "Roboto", sans-serif;
  font-display: optional;
}

✅ Correto: Separar o descritor da regra de estilo

@font-face {
  font-family: "Roboto";
  src: url("/fonts/roboto.woff2") format("woff2");
  font-display: optional;
}

.heading {
  font-family: "Roboto", sans-serif;
}

O descritor font-display: optional agora vive corretamente no bloco @font-face, onde diz ao navegador para usar a fonte personalizada apenas se já estiver em cache — caso contrário, fica com a fallback. A regra .heading simplesmente referencia a família de fonte pelo nome.