nextjs-font-css-variable-collision

Installation
SKILL.md

next/font CSS Variable Name Collision

Problem

When next/font configuration uses the same CSS custom property names as your design system (e.g., both define --font-display), the CSS cascade determines which value wins based on source order in the compiled CSS bundle. This creates a latent bug that can appear or disappear when unrelated changes (like adding new font imports) cause webpack to reorder CSS chunks.

The result: @font-face registers fonts under hashed internal names (e.g., '__Instrument_Serif_315a98'), but the CSS variable resolves to the literal name ('Instrument Serif') which has no matching @font-face rule. The browser falls back to the next font in the stack (e.g., Georgia).

Context / Trigger Conditions

Related skills
Installs
1
First Seen
Apr 16, 2026